nnw-theme 2.2.0 → 2.4.0

package/README.md

@@ -33,9 +33,9 @@ version, name it: `npx nnw-theme@2.0.0 check`.
 | `preview` | Serve the gallery on localhost, open it, and rebuild and reload it on save |
 | `render [fixtures…]` | Write the gallery to `build/preview/` once |
 | `check` | Validate and package, then render and test every case in WebKit |
-| `screenshot` | Check one case (any fixture and platform) and save its image; `--card` crops to the marketplace card, `--promote` makes it the card |
+| `screenshot` | Check one case (any fixture and platform) and save its image; `--delivery` renders it as FreshRSS or Miniflux delivers it, `--card` crops to the marketplace card, `--promote` makes it the card |
 | `package` | Validate and build `dist/<Name>.nnwtheme.zip` |
-| `fixture list` / `fixture add <name>…` | Add ready-made fixtures modeled on WordPress, Ghost, Substack, and Medium markup |
+| `fixture list` / `fixture add <name>…` | Add ready-made fixtures modeled on WordPress, Ghost, Substack, Medium, and Mastodon markup, and on podcast and Media RSS enclosures |
 | `capture` | Explain how to capture a real article from NetNewsWire as a fixture |
 | `bump` | Increase the `Info.plist` `Version` before a release |
 | `marketplace enable` | Add the marketplace discovery topic on GitHub |

package/THIRD_PARTY_NOTICES.md

@@ -1,8 +1,8 @@
 # Third-party notices
 
 The published package includes rendering files from
-[NetNewsWire](https://github.com/Ranchero-Software/NetNewsWire), release `mac-7.2b4`,
-commit `b7f4d8c7d273e4247c5d033ee47014805072297b`, under `assets/netnewswire/`.
+[NetNewsWire](https://github.com/Ranchero-Software/NetNewsWire) release `mac-7.3b4`,
+commit `e530be1ab19f68fe322850bf5fb95bca4b36fb91`, under `assets/netnewswire/`.
 `netnewswire.json` in the source repository records the SHA-256 of every file, and the
 build verifies each one, including NetNewsWire’s MIT license, which ships beside them as
 `assets/netnewswire/LICENSE`. These files are used only to preview themes; they are

package/assets/catalog/mastodon.toml

@@ -0,0 +1,50 @@
+# nnw-theme catalog fixture: mastodon (catalog version 1)
+# Markup: a Mastodon post from an account's RSS feed (https://example.org/@NAME.rss), as
+#   NetNewsWire renders it, captured 2026-11. Mastodon items have no title, and
+#   the feed is named for the account. The body is Mastodon's status HTML with its RSS
+#   content-warning preroll; the post's images arrive only as Media RSS
+#   <media:content> items, which NetNewsWire keeps without their alt text or size.
+# Text and links are synthetic; the structure, classes, and attributes are real.
+# Exercises: an untitled article (articleDatelineTitle), the content-warning paragraph
+#   and rule, h-card mentions and hashtags, a long link split into Mastodon's
+#   .invisible and .ellipsis spans (NetNewsWire shows all of them), 16x16 custom
+#   emoji inline in the text, a quote post's RE: fallback, and three unsized image
+#   enclosures with no caption.
+# Enclosures need NetNewsWire 7.3b3 for Mac or 7.3 for iOS, or later.
+# Refresh: npx nnw-theme@2 fixture add mastodon --force
+
+date_long = 'November 3, 2026'
+date_medium = 'Nov 3, 2026'
+date_short = '11/3/26'
+dateline_style = 'articleDatelineTitle'
+datetime_long = 'November 3, 2026 at 8:12:47 PM'
+datetime_medium = 'Nov 3, 2026 at 8:12 PM'
+datetime_short = '11/3/26, 8:12 PM'
+feed_link = 'https://example.org/@ines'
+feed_link_title = 'Ines Calloway 📷 (@ines@example.org)'
+preferred_link = 'https://example.org/@ines/115501234567890123'
+time_long = '8:12:47 PM PST'
+time_medium = '8:12:47 PM'
+time_short = '8:12 PM'
+title = ''
+body = '''
+<p><strong>Content warning:</strong> darkroom chemistry, one (1) paper cut</p><hr /><p class="quote-inline">RE: <a href="https://example.org/@kai/115498765432109876" target="_blank" rel="nofollow noopener" translate="no"><span class="invisible">https://</span><span class="ellipsis">example.org/@kai/1154987654321</span><span class="invisible">09876</span></a></p><p>First roll through the new tank and it came out… fine? Better than fine. <span class="h-card" translate="no"><a href="https://example.org/@kai" class="u-url mention">@<span>kai</span></a></span> was right about the agitation schedule, and <span class="h-card" translate="no"><a href="https://example.org/@marguerite" class="u-url mention">@<span>marguerite</span></a></span> was right that I would cut myself opening the canister <img rel="emoji" draggable="false" width="16" height="16" class="emojione custom-emoji" alt=":blobcat_sweat:" title=":blobcat_sweat:" src="https://example.org/system/custom_emojis/images/000/012/345/original/blobcat_sweat.png" /></p><p>Developer at 20°C, 9 minutes, inversions every 30 seconds for the first minute and then every minute after.<br />Stop bath, fixer, a long rinse, and a lot of staring at the negatives in front of the window like they would tell me something.</p><p>Notes and the full chart are up here: <a href="https://example.org/2026/11/notes-from-the-darkroom-first-roll-through-the-new-tank" target="_blank" rel="nofollow noopener" translate="no"><span class="invisible">https://</span><span class="ellipsis">example.org/2026/11/notes-from</span><span class="invisible">-the-darkroom-first-roll-through-the-new-tank</span></a> <img rel="emoji" draggable="false" width="16" height="16" class="emojione custom-emoji" alt=":film:" title=":film:" src="https://example.org/system/custom_emojis/images/000/006/789/original/film.png" /></p><p><a href="https://example.org/tags/FilmPhotography" class="mention hashtag" rel="tag">#<span>FilmPhotography</span></a> <a href="https://example.org/tags/Darkroom" class="mention hashtag" rel="tag">#<span>Darkroom</span></a> <a href="https://example.org/tags/BelieveInFilm" class="mention hashtag" rel="tag">#<span>BelieveInFilm</span></a></p>
+'''
+
+[[attachments]]
+url = 'https://example.org/system/media_attachments/files/115/501/234/567/890/123/original/9f2c4e1a7b3d5f60.jpg'
+mime_type = 'image/jpeg'
+size_in_bytes = 482113
+medium = 'image'
+
+[[attachments]]
+url = 'https://example.org/system/media_attachments/files/115/501/234/567/890/124/original/0b7d1e93c4a6f528.jpg'
+mime_type = 'image/jpeg'
+size_in_bytes = 397208
+medium = 'image'
+
+[[attachments]]
+url = 'https://example.org/system/media_attachments/files/115/501/234/567/890/125/original/c81a5f02e9d74b36.png'
+mime_type = 'image/png'
+size_in_bytes = 1204977
+medium = 'image'

package/assets/catalog/media-rss.toml

@@ -0,0 +1,79 @@
+# nnw-theme catalog fixture: media-rss (catalog version 1)
+# Markup: a photo-and-video post whose feed lists its media as RSS <enclosure> and
+#   Media RSS <media:content> items, as NetNewsWire renders them, captured 2026-10.
+# Text and links are synthetic; the structure and the enclosures' fields are real. The
+#   YouTube link is the channel-feed form NetNewsWire turns into its player; previews
+#   swap in a same-size placeholder and never load it.
+# Exercises: [[enclosures]] images with captions, a landscape and a portrait image,
+#   a video file with its poster, the YouTube player, an image the body already shows
+#   (skipped), and a PDF (not shown).
+# Enclosures need NetNewsWire with enclosure support (upstream main, October 2026).
+# Refresh: npx nnw-theme@2 fixture add media-rss --force
+
+byline = 'Ines Calloway'
+date_long = 'October 19, 2026'
+date_medium = 'Oct 19, 2026'
+date_short = '10/19/26'
+dateline_style = 'articleDateline'
+datetime_long = 'October 19, 2026 at 7:40:00 AM'
+datetime_medium = 'Oct 19, 2026 at 7:40 AM'
+datetime_short = '10/19/26, 7:40 AM'
+feed_link = 'https://example.org/'
+feed_link_title = 'Field & Frame'
+preferred_link = 'https://example.org/2026/10/ridge-at-first-light/'
+time_long = '7:40:00 AM PDT'
+time_medium = '7:40:00 AM'
+time_short = '7:40 AM'
+title = 'The ridge at first light'
+image_url = 'https://example.org/media/2026/10/ridge-poster.jpg'
+body = '''
+<p>We left the trailhead at four, which is the only way to reach the ridge before the light does. The forecast promised clear skies and delivered a lid of low cloud that burned off, all at once, about ten minutes after sunrise.</p>
+<p><img src="https://example.org/media/2026/10/ridge-wide.jpg" width="2000" height="1000" alt="The ridge from the saddle, under cloud"></p>
+<p>The feed lists everything we shot as enclosures. The wide view above is in the post itself, so the reader shows it once. The rest follow the post: two photographs, the timelapse, and the video walk-through from the channel.</p>
+<p>Getting there: the saddle is four miles and 2,600 feet from the upper trailhead. The last half mile is loose scree, slow going in the dark, and worth a helmet if anyone is above you. Bring more water than seems reasonable; there is none after the first creek crossing.</p>
+<p>Next month: the same ridge under the first snow, if the road stays open long enough to reach it.</p>
+<p>The PDF trail map rides along as an enclosure too, though there is nothing to show for it in the article.</p>
+'''
+
+[[attachments]]
+url = 'https://example.org/media/2026/10/ridge-wide.jpg'
+mime_type = 'image/jpeg'
+width = 2000
+height = 1000
+medium = 'image'
+
+[[attachments]]
+url = 'https://example.org/media/2026/10/cairn.jpg'
+mime_type = 'image/jpeg'
+title = 'The cairn at the false summit, with the real one behind it.'
+width = 1600
+height = 1067
+medium = 'image'
+
+[[attachments]]
+url = 'https://example.org/media/2026/10/larch.jpg'
+title = 'Larches turning on the north slope.'
+width = 1000
+height = 1500
+
+[[attachments]]
+url = 'https://example.org/media/2026/10/ridge-timelapse.mp4'
+mime_type = 'video/mp4'
+title = 'Timelapse: the cloud lid lifting, 40 minutes in 30 seconds.'
+size_in_bytes = 48210944
+duration_in_seconds = 30
+width = 1920
+height = 1080
+medium = 'video'
+
+[[attachments]]
+url = 'https://www.youtube.com/v/Xr2kTq9mZ4c?version=3'
+mime_type = 'application/x-shockwave-flash'
+width = 640
+height = 390
+
+[[attachments]]
+url = 'https://example.org/media/2026/10/ridge-trail-map.pdf'
+mime_type = 'application/pdf'
+size_in_bytes = 2310144
+medium = 'document'

package/assets/catalog/podcast.toml

@@ -0,0 +1,52 @@
+# nnw-theme catalog fixture: podcast (catalog version 1)
+# Markup: a podcast episode as NetNewsWire renders it from RSS, captured 2026-10: show
+#   notes in the body, an <enclosure> for the episode's audio, and the episode's
+#   itunes:image as the article image. Modeled on ATP 311 in NetNewsWire's own tests.
+# Text and links are synthetic; the structure and the enclosure's fields are real.
+# Exercises: the [[enclosures]] audio player and its caption (title · duration · size),
+#   and the article image NetNewsWire shows as an enclosure when nothing else is visual.
+# Enclosures need NetNewsWire with enclosure support (upstream main, October 2026).
+# Refresh: npx nnw-theme@2 fixture add podcast --force
+
+byline = 'Morgan Hale, Priya Nandakumar, Theo Brandt'
+date_long = 'October 22, 2026'
+date_medium = 'Oct 22, 2026'
+date_short = '10/22/26'
+dateline_style = 'articleDateline'
+datetime_long = 'October 22, 2026 at 6:15:00 PM'
+datetime_medium = 'Oct 22, 2026 at 6:15 PM'
+datetime_short = '10/22/26, 6:15 PM'
+feed_link = 'https://example.org/podcast/'
+feed_link_title = 'Three Desks Over'
+preferred_link = 'https://example.org/podcast/311'
+time_long = '6:15:00 PM PDT'
+time_medium = '6:15:00 PM'
+time_short = '6:15 PM'
+title = '311: The Long One'
+image_url = 'https://example.org/podcast/artwork/311-artwork.jpg'
+body = '''
+<p>The follow-up runs long, the main topic runs longer, and an After Show question finally gets the answer it deserves.</p>
+<ul>
+<li>Follow-up:<ul>
+<li><a href="https://example.org/notes/keyboard-repair">The keyboard repair program</a>, again</li>
+<li>Listener mail about <a href="https://example.org/notes/backups">offsite backups</a></li>
+</ul></li>
+<li><a href="https://example.org/notes/video-calls">Video calls that join themselves</a></li>
+<li><a href="https://example.org/notes/app-review">What app review is for</a></li>
+<li>Post-show: <a href="https://example.org/notes/coffee">the coffee grinder that won’t quit</a></li>
+</ul>
+<p>Sponsored by:</p>
+<ul>
+<li><a href="https://example.org/sponsors/notebooks">Field Notebooks</a>: Paper that keeps up. Use code <strong>DESKS</strong> for 20% off.</li>
+<li><a href="https://example.org/sponsors/hosting">Quiet Hosting</a>: Your site, faster, with nothing to configure.</li>
+</ul>
+<p>Become a member for ad-free episodes and our <a href="https://example.org/podcast/bootleg">bootleg feed</a>, with every show’s raw recording.</p>
+'''
+
+[[attachments]]
+url = 'https://example.org/podcast/audio/tdo311.mp3'
+mime_type = 'audio/mpeg'
+title = '311: The Long One'
+size_in_bytes = 54919661
+duration_in_seconds = 6849
+medium = 'audio'

package/assets/enclosures.js

@@ -0,0 +1,113 @@
+// Enclosure checks, evaluated in each rendered page after its screenshot. Returns a
+// list of failure messages. NetNewsWire writes each enclosure as
+// div.nnw-enclosure > (img | video | audio | iframe), with an optional
+// div.nnw-enclosure-caption, inside one div.nnw-enclosures: at [[enclosures]] in the
+// template, or after the body when the template has no such macro. A theme script
+// may move an enclosure elsewhere, so each is found wherever it ended up.
+() => {
+	const failures = [];
+	const fail = (message) => failures.push(message);
+	const width = document.documentElement.clientWidth;
+	const px = (value) => Math.round(value);
+	const size = (value) => {
+		const number = Number(value);
+		return Number.isFinite(number) && number > 0 ? number : 0;
+	};
+
+	const enclosures = [...document.querySelectorAll(".nnw-enclosure")];
+	enclosures.forEach((enclosure, index) => {
+		const media = enclosure.querySelector(":scope > :is(img, video, audio, iframe)");
+		if (!media) return;
+		const kind =
+			media.localName === "iframe"
+				? "video player"
+				: {
+						img: "image",
+						video: "video",
+						audio: "audio player",
+					}[media.localName];
+		const label = `enclosure ${index + 1} (${kind})`;
+		const box = media.getBoundingClientRect();
+		if (
+			!media.getClientRects().length ||
+			box.width < 1 ||
+			box.height < 1 ||
+			getComputedStyle(media).visibility !== "visible"
+		) {
+			fail(`${label}: not shown`);
+			return;
+		}
+		if (box.left < -1 || box.right > width + 1) {
+			fail(`${label}: spans ${px(box.left)}–${px(box.right)}px, outside the ${width}px window`);
+		}
+		if (media.localName === "audio") {
+			// Narrower than this, WebKit drops the scrubber and the player can't seek.
+			const least = Math.min(240, width * 0.6);
+			if (box.width < least) fail(`${label}: only ${px(box.width)}px wide`);
+			return;
+		}
+		if (media.localName === "iframe") {
+			// The player letterboxes its video in any box, so only a squashed or
+			// towering frame is wrong; its width and height are the old Flash player's.
+			const ratio = box.height / box.width;
+			if (ratio < 0.45 || ratio > 1.05) {
+				fail(`${label}: drawn ${px(box.width)}×${px(box.height)}, not a video's shape`);
+			}
+			return;
+		}
+		const [w, h] =
+			media.localName === "img" && media.naturalWidth
+				? [media.naturalWidth, media.naturalHeight]
+				: [size(media.getAttribute("width")), size(media.getAttribute("height"))];
+		if (!w || !h) return;
+		const expected = (box.width * h) / w;
+		if (Math.abs(box.height - expected) > Math.max(2, expected * 0.03)) {
+			fail(
+				`${label}: drawn ${px(box.width)}×${px(box.height)}, distorting its ${w}×${h} shape`,
+			);
+		}
+	});
+
+	// A caption must stand out from what it sits on, as footnote numerals must.
+	const rgba = (value) => {
+		const n = (value.match(/[\d.]+/g) || []).map(Number);
+		return n.length ? [n[0], n[1], n[2], n.length > 3 ? n[3] : 1] : [0, 0, 0, 0];
+	};
+	const backdrop = (element) => {
+		const layers = [];
+		for (let node = element; node; node = node.parentElement) {
+			const layer = rgba(getComputedStyle(node).backgroundColor);
+			if (!layer[3]) continue;
+			layers.push(layer);
+			if (layer[3] === 1) break;
+		}
+		let base = layers.pop() || [255, 255, 255, 1];
+		while (layers.length) {
+			const top = layers.pop();
+			base = [0, 1, 2].map((i) => top[i] * top[3] + base[i] * (1 - top[3]));
+		}
+		return base.slice(0, 3);
+	};
+	const distance = (a, b) => [0, 1, 2].reduce((sum, i) => sum + Math.abs(a[i] - b[i]), 0);
+	const captions = [...document.querySelectorAll(".nnw-enclosure-caption")];
+	for (const caption of captions) {
+		if (!caption.getClientRects().length || !caption.innerText.trim()) continue;
+		const name = JSON.stringify(caption.innerText.trim().slice(0, 40));
+		const glyphs = [caption, ...caption.querySelectorAll("*")].filter((element) =>
+			[...element.childNodes].some(
+				(node) => node.nodeType === Node.TEXT_NODE && node.data.trim(),
+			),
+		);
+		for (const glyph of glyphs) {
+			const color = rgba(getComputedStyle(glyph).color);
+			const ground = backdrop(glyph);
+			if (color[3] < 0.5 || distance(color, ground) <= 60) {
+				fail(`enclosure caption ${name}: text ${color.slice(0, 3)} is illegible on ${ground}`);
+				break;
+			}
+		}
+		const fontSize = Number.parseFloat(getComputedStyle(caption).fontSize);
+		if (fontSize < 10) fail(`enclosure caption ${name}: ${fontSize}px text is too small`);
+	}
+	return failures;
+}

package/assets/footnotes.js

@@ -1,5 +1,5 @@
-// Footnote checks, evaluated in each rendered page after its screenshot. Returns a
-// list of failure messages. NetNewsWire's newsfoot.js opens a popover for any
+// Footnote checks, evaluated in each rendered page after its screenshot. Returns
+// {failures, warnings}, each a list of messages. NetNewsWire's newsfoot.js opens a popover for any
 // a.footnote whose hash names an element; main.js adds that class to local
 // sup > a[href*='#fn'] links and Substack's a[id^='footnote-anchor-'] links, and a
 // theme script may add it to other formats.
@@ -7,11 +7,13 @@
 // expect is the fixture's [expect.footnotes] table: notes maps each marker's text to
 // its note text, plain_links lists selectors for links that are not footnotes, and
 // keep_with_word requires a marker written against its word to stay on its line.
-async ({notes = null, plain_links = [], keep_with_word = false} = {}) => {
+// all_converted makes an unconverted marker a failure rather than a warning.
+async ({notes = null, plain_links = [], keep_with_word = false, all_converted = false} = {}) => {
 	const failures = [];
+	const warnings = [];
 	const fail = message => failures.push(message);
 	const article = document.querySelector(".articleBody");
-	if (!article) return failures;
+	if (!article) return {failures, warnings};
 	const text = element => element.textContent.replace(/\s+/g, " ").trim();
 	const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -19,11 +21,42 @@ async ({notes = null, plain_links = [], keep_with_word = false} = {}) => {
 	const markers = [...article.querySelectorAll("a.footnote")]
 		.filter(marker => marker.getClientRects().length);
 	const label = marker => text(marker) || marker.getAttribute("href");
+	const fragment = link => {
+		try {
+			return link.hash ? decodeURIComponent(link.hash.slice(1)) : "";
+		} catch {
+			return "";
+		}
+	};
+
+	// A reference in a shape main.js or a theme converts, linking to an element in the
+	// article, that never became a marker: NetNewsWire opens it as a link. It happens
+	// when the page's base URL doesn't match the link, as for an article synced through
+	// the Reader API, or when a sync service rewrote the markup a theme script expects.
+	const plain = new Set();
+	for (const selector of plain_links) {
+		try {
+			for (const link of document.querySelectorAll(selector)) plain.add(link);
+		} catch {
+			// Reported below.
+		}
+	}
+	const references = article.querySelectorAll(
+		"sup > a[href], sup > div > a[href], a[id^='footnote-anchor-'][href]");
+	for (const link of references) {
+		if (link.matches(".footnote") || plain.has(link) || !link.getClientRects().length) continue;
+		const id = fragment(link);
+		const target = id && document.getElementById(id);
+		if (!target || !article.contains(target) || target.contains(link)) continue;
+		const message = `footnote ${label(link)}: ${link.getAttribute("href")} links to a note ` +
+			"but never became an a.footnote marker, so NetNewsWire opens it as a link";
+		(all_converted ? failures : warnings).push(message);
+	}
 
 	// Every marker resolves, as newsfoot does, to one non-empty note.
 	const noteFor = new Map();
 	for (const marker of markers) {
-		const id = marker.hash ? decodeURIComponent(marker.hash.slice(1)) : "";
+		const id = fragment(marker);
 		const target = id && document.getElementById(id);
 		if (!target) {
 			fail(`footnote ${label(marker)}: ${marker.getAttribute("href")} names no note`);
@@ -179,5 +212,5 @@ async ({notes = null, plain_links = [], keep_with_word = false} = {}) => {
 		document.body.dispatchEvent(new MouseEvent("click", {bubbles: true, cancelable: true, view: window}));
 		await pause(30);
 	}
-	return failures;
+	return {failures, warnings};
 }

package/assets/guide/design-checklist.md

@@ -14,6 +14,12 @@ prescribed aesthetic.
 - Check large-text macOS and iPhone renders for clipping, overlap, and lost hierarchy.
   These exercise the real mechanisms: a macOS size class and an iOS Dynamic Type size.
 - Check JavaScript-off macOS and iPhone renders for readable content and usable links.
+- If the theme styles enclosures, check the `podcast` and `media-rss` fixtures: players,
+  captions, and the article image leading a podcast episode, in light and dark.
+- If the theme script handles footnotes or relies on classes or ids, give a fixture
+  `deliveries = ["freshrss", "miniflux"]` and check the cases synced readers see.
+- Check an untitled article, such as the `mastodon` fixture: the dateline stands in for
+  the headline, and inline 16x16 custom emoji must stay inline beside the text.
 - Inspect a real WebKit screenshot, not only the live gallery or Chromium fallback.
 - Promote `screenshots/theme-preview.png` only when the 16:10 macOS article image is
   an intentional representation of the release.

package/assets/guide/fixtures.md

@@ -24,7 +24,7 @@ npx nnw-theme@2 fixture add wordpress --force    # replace a copy with the curre
 
 Each is copied into `fixtures/` and is from then on an ordinary fixture of the
 repository, checked on macOS and iPhone in light and dark: four more renders per
-fixture in every `check`, sixteen for all four. Their structure, classes, and attributes
+fixture in every `check`, twenty-eight for all seven. Their structure, classes, and attributes
 come from real feeds; their text is synthetic and their links point at `example.org`.
 The copy never changes on its own when `nnw-theme` updates. A header comment records
 its catalog version, and `fixture list` says when a newer one is available; take it
@@ -33,12 +33,66 @@ with `fixture add NAME --force`, which replaces any edits to the file.
 NetNewsWire turns Substack footnotes into popovers on its own. Most WordPress
 footnotes stay plain links until a theme script turns them into `a.footnote` markers.
 
+## Enclosures
+
+An article's enclosures are data, not markup: NetNewsWire renders them into the
+`enclosures` macro, or after the body, from the article's attachments. A fixture lists
+them after its other keys, in feed order, and may give the article's image:
+
+```toml
+image_url = "https://example.org/episode-art.jpg"  # else thumbnail_url
+
+[[attachments]]
+url = "https://example.org/episode-311.mp3"        # required
+mime_type = "audio/mpeg"
+title = "311: The Long One"
+size_in_bytes = 54919661
+duration_in_seconds = 6849
+width = 1920                                        # images and video
+height = 1080
+medium = "audio"            # image, audio, video, document, or executable
+```
+
+`nnw-theme` renders them as the pinned NetNewsWire does; the `theme-format` guide
+describes the markup. `fixture add podcast media-rss` adds fixtures that exercise
+every kind. Previews stay offline: images and posters become same-size placeholders,
+players lose their network source, a video with nothing to show gets a placeholder
+poster at its size, and the YouTube player becomes a placeholder frame. A `media/NAME`
+URL plays or shows the file from `fixtures/media/`, including audio and video for a
+screenshot; keep such files tiny, since every page that renders the fixture embeds them.
+
+## Sync services
+
+Readers who sync through a service see an article as that service hands it to
+NetNewsWire, not as the publisher wrote it. A fixture can be rendered that way too:
+
+```toml
+deliveries = ["freshrss", "miniflux"]   # also render as each service delivers it
+base_url = "https://example.org/"       # the page's base URL in every case
+```
+
+Each delivery adds two cases, Mac light and iPhone dark, with the body rewritten by
+that service's sanitizer and the feed's home page (`feed_link`, or `base_url` when
+given) as the page's base URL. That base is what NetNewsWire uses for every article synced through the Reader
+API, since those carry only an external link. FreshRSS renames every `id` and `class` to
+`data-sanitized-id` and `data-sanitized-class` and makes every link absolute,
+fragments included; NetNewsWire 7.3 restores the names for FreshRSS accounts, but
+earlier releases do not, and the delivery shows the content as they do. Miniflux strips
+`class`, keeps `id` only on links, headings, list items, and `sup`, unwraps wrappers
+such as `div.footnotes`, and marks external links `target="_blank"`. `base_url`
+replaces the base in every case, delivered or not: give it the site URL the service
+reports when that differs from the post URLs, or use it alone to reproduce a page whose
+base differs from its links without rewriting the body.
+
 ## Your own articles
 
 Prefer real articles for content a theme must handle. `npx nnw-theme@2 capture`
 prints the steps for saving the selected article from a NetNewsWire debug build with
 the `nnwdump` lldb command; it needs Xcode and a NetNewsWire clone, so the person
-usually runs it. Rendering swaps every image that would load over the network for a
+usually runs it. It records the article's attachments and image as the keys above,
+not NetNewsWire's rendered enclosures, so any template previews them, and records
+`base_url` when the page's base differs from the article's link, as it does for an
+article synced through the Reader API. Rendering swaps every image that would load over the network for a
 same-size placeholder and a network feed icon for a generated one; do not inline or
 fetch the originals.
 
@@ -50,15 +104,21 @@ each is copied into every page that renders the fixture.
 
 Footnote markers are the links NetNewsWire's `newsfoot.js` handles: `a.footnote`.
 Its `main.js` adds that class to local `sup > a[href*='#fn']` links and to Substack's
-`a[id^='footnote-anchor-']` links; a theme script may add it to other formats. `check` requires every visible marker to resolve to a
+`a[id^='footnote-anchor-']` links, where local means the link starts with the page's
+base URL; a theme script may add it to other formats. `check` requires every visible marker to resolve to a
 non-empty note with a unique id, stay legible on its background, match the other
 markers' height, font size, and baseline offset, and open a popover with its note
-without resizing. A fixture may declare exact expectations after its other keys:
+without resizing. A `sup > a` or Substack anchor whose fragment names an element in
+the article but that never became a marker is opened as a link instead: `check` warns
+about one, and fails it in a fixture with `base_url` or `deliveries`, or with
+`all_converted = true`. List a link that really is ordinary in `plain_links`.
+A fixture may declare exact expectations after its other keys:
 
 ```toml
 [expect.footnotes]
 plain_links = ["#ordinary-sup-link"]   # CSS selectors that must not become markers
 keep_with_word = true                  # markers must not wrap apart from their word
+all_converted = true                   # fail, not warn, on footnote links left plain
 
 [expect.footnotes.notes]
 "1" = "First note."                    # marker text as rendered = note text

package/assets/guide/skill.md

@@ -20,7 +20,8 @@ specific reading needs. Prefer changing the CSS variables and rules in
 needs it. For format constraints and macro behavior, read the `theme-format` topic.
 To preview content the built-in articles lack, such as a real feed's markup or
 footnotes, add a fixture as the `fixtures` topic describes; `npx nnw-theme@2 fixture
-list` offers ready-made ones modeled on WordPress, Ghost, Substack, and Medium.
+list` offers ready-made ones modeled on WordPress, Ghost, Substack, Medium, and
+Mastodon, plus podcast and Media RSS enclosures.
 
 Iterate with this loop:
 

package/assets/guide/theme-format.md

@@ -39,13 +39,59 @@ comment early and shows the rest of it as text. `check` fails on them. NetNewsWi
 `:root`; a theme with its own typography should not, because that shorthand resets
 `font-family` and `line-height`.
 
-The renderer pins NetNewsWire `mac-7.2b4` commit
-`b7f4d8c7d273e4247c5d033ee47014805072297b`. It uses upstream `core.css`, macOS and
+## Enclosures
+
+NetNewsWire shows an article's enclosures (RSS `<enclosure>` and Media RSS items) as
+players and images. A template places them with the `enclosures` macro; one without it
+gets them appended after the body, inside the body container, and its body is then
+wrapped in an extra `<div>` (so the enclosures escape any tag the body leaves open).
+That wrapper changes the body's children: a theme whose selectors rely on
+`.articleBody > …` should place the macro itself. NetNewsWire tests for the literal
+macro text anywhere in `template.html`, comments included.
+
+The markup is fixed and carries no inline styles:
+
+```html
+<div class="nnw-enclosures">
+  <div class="nnw-enclosure nnw-enclosure-image"><img src="…" alt="" width="…" height="…"></div>
+  <div class="nnw-enclosure nnw-enclosure-audio"><audio controls preload="none" src="…"></audio>
+    <div class="nnw-enclosure-caption">Title · 1:54:09 · 54.9 MB</div></div>
+  <div class="nnw-enclosure nnw-enclosure-video"><video controls preload="metadata" playsinline …></video></div>
+  <div class="nnw-enclosure nnw-enclosure-video"><iframe src="https://www.youtube-nocookie.com/embed/…" …></iframe></div>
+</div>
+```
+
+Images and video carry the feed's `width` and `height` when it gives both; a caption
+appears only when there is text for it. The audio caption joins the title (else the
+file name), duration, and size with ` · `. A YouTube channel enclosure becomes the
+iframe player. Enclosures whose URL already appears in the body are skipped, and
+documents are never shown. When nothing visual remains, neither an enclosure nor an
+image or video in the body, the article's image (or thumbnail) leads the list as an
+image enclosure: a podcast episode's artwork above its player. A video uses that image
+as its poster.
+
+NetNewsWire releases before enclosure support leave the macro as literal text in
+every article, so a theme that places it should hide its container when it holds no
+enclosures, for example `<div class="my-enclosures">[[enclosures]]</div>` with
+`.my-enclosures:not(:has(.nnw-enclosures)) { display: none; }`. `check` renders the
+article fixture that way too and fails if the text shows. With enclosures in a
+fixture, `check` also fails an enclosure image, player, or video that is hidden,
+leaves the window, or is drawn out of its shape, an audio player too narrow to seek,
+and an illegible caption.
+
+## Pinned NetNewsWire
+
+The renderer pins NetNewsWire 7.3b4 for Mac (`mac-7.3b4`, commit
+`e530be1ab19f68fe322850bf5fb95bca4b36fb91`), whose rendering files iOS 7.3 shares.
+Enclosure support starts with 7.3b3, and 7.3b4 keeps the footnote popover inside the
+article column. It uses upstream `core.css`, macOS and
 iOS page skeletons, and `main.js`, `main_mac.js`, `main_ios.js`, and `newsfoot.js`.
 These files ship inside the `nnw-theme` package, verified by SHA-256, so previews work
 offline. iPhone and iPad share the iOS skeleton. WebKit native
 color-scheme emulation controls light/dark captures; CSS is not rewritten.
 
+## Scripts and resources
+
 Inline scripts in `template.html` are supported. External scripts and stylesheets are
 rejected. Remote theme-owned fonts, images, audio, or video require an explicit local
 warning override and are still blocked during checks. The article must remain useful

package/assets/netnewswire/Mac/main_mac.js

@@ -30,6 +30,11 @@ function selectedHTML() {
 	container.querySelectorAll("a[href]").forEach(function(anchor) {
 		anchor.setAttribute("href", anchor.href);
 	});
+	// Images served from the timeline’s copy would break outside this page.
+	container.querySelectorAll("img[data-nnw-src]").forEach(function(image) {
+		image.setAttribute("src", image.getAttribute("data-nnw-src"));
+		image.removeAttribute("data-nnw-src");
+	});
 	// A single-paragraph selection doesn't need its <p> wrapper.
 	if (container.childNodes.length === 1 && container.firstChild.nodeName === "P") {
 		return container.firstChild.innerHTML;