feat: v1.2.0-rc.2 - Media display fixes and feed enhancements

## Added - Feed Media Enhancement with Media RSS namespace support - RSS enclosure, media:content, media:thumbnail elements - JSON Feed image field for first image - ADR-059: Full feed media standardization roadmap ## Fixed - Media display on homepage (was only showing on note pages) - Responsive image sizing with CSS constraints - Caption display (now alt text only, not visible) - Logging correlation ID crash in non-request contexts ## Documentation - Feed media design documents and implementation reports - Media display fixes design and validation reports - Updated ROADMAP with v1.3.0/v1.4.0 media plans 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-09 14:58:37 -07:00
parent 10d85bb78b
commit 27501f6381
21 changed files with 3360 additions and 44 deletions
--- a/docs/design/v1.1.2-caption-alttext-update.md
+++ b/docs/design/v1.1.2-caption-alttext-update.md
@@ -0,0 +1,153 @@
+# Caption Display Update - Alt Text Only (v1.1.2)
+
+## Status
+**Superseded by media-display-fixes.md**
+
+This document contains an earlier approach to caption handling. The authoritative specification is now in `media-display-fixes.md` which provides a complete solution for media display including caption handling, CSS constraints, and homepage media.
+
+## Context
+
+User has clarified that media captions should be used as alt text only, not displayed as visible `<figcaption>` elements in the note body.
+
+## Decision
+
+Remove all visible caption display from templates while maintaining caption data for accessibility (alt text) purposes.
+
+## Required Changes
+
+### 1. CSS Updates
+
+**File:** `/home/phil/Projects/starpunk/static/css/style.css`
+
+**Remove:** Lines related to figcaption styling (line 17 in the media CSS section)
+
+```css
+/* REMOVE THIS LINE */
+.note-media figcaption, .e-content figcaption { margin-top: var(--spacing-sm); font-size: 0.875rem; color: var(--color-text-light); font-style: italic; }
+```
+
+The remaining CSS should be:
+
+```css
+/* Media Display Styles (v1.2.0) - Updated for alt-text only captions */
+.note-media { margin-bottom: var(--spacing-md); }
+.note-media img, .e-content img, .u-photo { max-width: 100%; height: auto; display: block; border-radius: var(--border-radius); }
+
+/* Multiple media items grid */
+.note-media { display: flex; flex-wrap: wrap; gap: var(--spacing-md); }
+.note-media .media-item { flex: 1 1 100%; }
+
+/* Desktop: side-by-side for multiple images */
+@media (min-width: 768px) {
+  .note-media .media-item:only-child { flex: 1 1 100%; }
+  .note-media .media-item:not(:only-child) { flex: 1 1 calc(50% - var(--spacing-sm)); }
+}
+```
+
+### 2. Template Updates
+
+#### File: `/home/phil/Projects/starpunk/templates/note.html`
+
+**Change:** Lines 17-29 - Simplify media display structure
+
+**From:**
+```html
+{% if note.media %}
+<div class="note-media">
+  {% for item in note.media %}
+  <figure class="media-item">
+    <img src="{{ url_for('public.media_file', path=item.path) }}"
+         alt="{{ item.caption or 'Image' }}"
+         class="u-photo"
+         width="{{ item.width }}"
+         height="{{ item.height }}">
+    {% if item.caption %}
+    <figcaption>{{ item.caption }}</figcaption>
+    {% endif %}
+  </figure>
+  {% endfor %}
+</div>
+{% endif %}
+```
+
+**To:**
+```html
+{% if note.media %}
+<div class="note-media">
+  {% for item in note.media %}
+  <div class="media-item">
+    <img src="{{ url_for('public.media_file', path=item.path) }}"
+         alt="{{ item.caption or 'Image' }}"
+         class="u-photo"
+         width="{{ item.width }}"
+         height="{{ item.height }}">
+  </div>
+  {% endfor %}
+</div>
+{% endif %}
+```
+
+**Changes:**
+- Replace `<figure>` with `<div>` (simpler, no semantic figure/caption relationship)
+- Remove the `{% if item.caption %}` block and `<figcaption>` element entirely
+- Keep caption in `alt` attribute for accessibility
+
+#### File: `/home/phil/Projects/starpunk/templates/index.html`
+
+**Status:** No changes needed
+- Index template doesn't display media items in the preview
+- Only shows truncated content
+
+### 3. Feed Generators
+
+**Status:** No changes needed
+
+The feed generators already handle captions correctly:
+- RSS, ATOM, and JSON Feed all use captions as alt text in `<img>` tags
+- JSON Feed also includes captions in attachment metadata (correct behavior)
+
+**Current implementation (correct):**
+```python
+# In all feed generators
+caption = media_item.get('caption', '')
+content_html += f'<img src="{media_url}" alt="{caption}" />'
+```
+
+## Rationale
+
+1. **Simplicity**: Removing visible captions reduces visual clutter
+2. **Accessibility**: Alt text provides necessary context for screen readers
+3. **User Intent**: Captions are metadata, not content to be displayed
+4. **Clean Design**: Images speak for themselves without redundant text
+
+## Implementation Checklist
+
+- [ ] Update CSS to remove figcaption styles
+- [ ] Update note.html template to remove figcaption elements
+- [ ] Test with images that have captions
+- [ ] Test with images without captions
+- [ ] Verify alt text is properly set
+- [ ] Test responsive layout still works
+- [ ] Verify feed output unchanged
+
+## Testing Requirements
+
+1. **Visual Testing:**
+   - Confirm no caption text appears below images
+   - Verify image layout unchanged
+   - Test responsive behavior on mobile/desktop
+
+2. **Accessibility Testing:**
+   - Inspect HTML to confirm alt attributes are set
+   - Test with screen reader to verify alt text is announced
+
+3. **Feed Testing:**
+   - Verify RSS/ATOM/JSON feeds still include alt text
+   - Confirm JSON Feed attachments retain title field
+
+## Standards Compliance
+
+- **HTML**: Valid use of img alt attribute
+- **Accessibility**: WCAG 2.1 Level A compliance for images
+- **IndieWeb**: Maintains u-photo microformat class
+- **Progressive Enhancement**: Images functional without CSS