nnw-theme 2.0.3 → 2.1.0

package/README.md

@@ -35,6 +35,7 @@ version, name it: `npx nnw-theme@2.0.0 check`.
 | `check` | Validate and package, then render and test every case in WebKit |
 | `screenshot` | Check one case and save its image; `--promote` makes it the marketplace 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 |
 | `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/assets/catalog/ghost.toml

@@ -0,0 +1,118 @@
+# nnw-theme catalog fixture: ghost (catalog version 1)
+# Markup: Ghost Koenig editor cards, as sent in Ghost RSS content:encoded, captured 2026-09.
+# Text and links are synthetic; the structure, classes and attributes are real.
+# Exercises: a bare unsized lead image, wide/full image cards, gallery rows, bookmark,
+#   callout, button, call-to-action, toggle, video and embed cards, loading="lazy" images.
+# Refresh: npx nnw-theme@2 fixture add ghost --force
+
+byline = 'Rowan Ellery, Sam Okafor'
+date_long = 'September 28, 2026'
+date_medium = 'Sep 28, 2026'
+date_short = '9/28/26'
+dateline_style = 'articleDateline'
+datetime_long = 'September 28, 2026 at 9:00:00 AM'
+datetime_medium = 'Sep 28, 2026 at 9:00 AM'
+datetime_short = '9/28/26, 9:00 AM'
+feed_link = 'https://example.org/'
+feed_link_title = 'The Workbench Journal'
+preferred_link = 'https://example.org/notes-from-the-workbench/'
+time_long = '9:00:00 AM PDT'
+time_medium = '9:00:00 AM'
+time_short = '9:00 AM'
+title = 'Notes from the workbench: a season of small repairs'
+body = '''
+<img src="https://example.org/content/images/2026/09/workbench-lead.jpg" alt="Notes from the workbench: a season of small repairs"><p>Ghost’s RSS feed opens with the post’s feature image as a bare <code>img</code>, unsized and unwrapped, directly before the first paragraph. Everything after it is written by Ghost’s editor, which marks each rich block as a <code>kg-card</code>.</p>
+<p>An image card with a caption:</p>
+<figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://example.org/content/images/2026/09/bench-vise.jpg" class="kg-image" alt="A bench vise holding a strip of wood" loading="lazy" width="492" height="316"><figcaption><span style="white-space: pre-wrap;">A narrow image keeps its own size; the caption runs wider than the picture.</span></figcaption></figure>
+<p>A wide image card, meant to break out of the text column:</p>
+<figure class="kg-card kg-image-card kg-width-wide kg-card-hascaption"><img src="https://example.org/content/images/2026/09/shop-floor.jpg" class="kg-image" alt="The shop floor seen from the doorway" loading="lazy" width="2000" height="1125" srcset="https://example.org/content/images/size/w600/2026/09/shop-floor.jpg 600w, https://example.org/content/images/size/w1000/2026/09/shop-floor.jpg 1000w, https://example.org/content/images/size/w1600/2026/09/shop-floor.jpg 1600w, https://example.org/content/images/2026/09/shop-floor.jpg 2000w" sizes="(min-width: 1200px) 1200px"><figcaption><span style="white-space: pre-wrap;">The shop floor after the spring clean-out.</span></figcaption></figure>
+<p>A full-width image card, meant to span the whole window:</p>
+<figure class="kg-card kg-image-card kg-width-full"><img src="https://example.org/content/images/2026/09/lumber-rack.jpg" class="kg-image" alt="A rack of sorted lumber" loading="lazy" width="2400" height="900" srcset="https://example.org/content/images/size/w600/2026/09/lumber-rack.jpg 600w, https://example.org/content/images/size/w1000/2026/09/lumber-rack.jpg 1000w, https://example.org/content/images/size/w1600/2026/09/lumber-rack.jpg 1600w, https://example.org/content/images/size/w2400/2026/09/lumber-rack.jpg 2400w"></figure>
+<p>A YouTube embed. Ghost’s oEmbed markup sizes every one at 200×113:</p>
+<figure class="kg-card kg-embed-card"><iframe width="200" height="113" src="https://example.org/embed/sharpening-a-plane-iron?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen title="Sharpening a plane iron, start to finish"></iframe></figure>
+<p>Another embed, sized 560×316:</p>
+<figure class="kg-card kg-embed-card"><iframe src="https://example.org/talks/the-case-for-hand-tools" width="560" height="316" frameborder="0" scrolling="no" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe></figure>
+<p>A bookmark card, a link preview; the feed drops its thumbnail and icon:</p>
+<figure class="kg-card kg-bookmark-card"><a class="kg-bookmark-container" href="https://example.org/a-guide-to-winter-finishes/"><div class="kg-bookmark-content"><div class="kg-bookmark-title">A Guide to Winter Finishes &#x2022; The Workbench Journal</div><small><div class="kg-bookmark-description">Oils, waxes, and varnishes behave differently when the shop is cold. Here is what we use from November to March, and why each one earns its place.</div></small></div></a></figure>
+<p>Text between two bookmark cards.</p>
+<figure class="kg-card kg-bookmark-card"><a class="kg-bookmark-container" href="https://example.org/the-long-bench/"><div class="kg-bookmark-content"><div class="kg-bookmark-title">The Long Bench</div><small><div class="kg-bookmark-description">Twelve feet of maple and three years of arguments about where it should go.</div></small></div></a></figure>
+<p>A toggle card:</p>
+<div class="kg-card kg-toggle-card" data-kg-toggle-state="close">
+            <div class="kg-toggle-heading">
+                <h4 class="kg-toggle-heading-text"><span style="white-space: pre-wrap;">What we bought this season (~&#x24;2,100)</span></h4>
+                <button class="kg-toggle-card-icon" aria-label="Expand toggle to read content">
+                    <svg id="Regular" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+                        <path class="cls-1" d="M23.25,7.311,12.53,18.03a.749.749,0,0,1-1.06,0L.75,7.311"/>
+                    </svg>
+                </button>
+            </div>
+            <div class="kg-toggle-content"><ul><li value="1"><a href="https://example.org/tools/block-plane" target="_blank" rel="noopener noreferrer"><span style="white-space: pre-wrap;">Low-angle block plane</span></a><span style="white-space: pre-wrap;"> &#x2014; &#x24;180</span></li><li value="2"><a href="https://example.org/tools/marking-gauge" target="_blank" rel="noopener noreferrer"><span style="white-space: pre-wrap;">Wheel marking gauge</span></a><span style="white-space: pre-wrap;"> &#x2014; &#x24;45</span></li><li value="3"><a href="https://example.org/tools/dust-collector" target="_blank" rel="noopener noreferrer"><span style="white-space: pre-wrap;">Dust collector with a cyclone separator</span></a><span style="white-space: pre-wrap;"> &#x2014; &#x24;1,875</span></li></ul></div>
+        </div>
+<p>A callout card:</p>
+<div class="kg-card kg-callout-card kg-callout-card-grey"><div class="kg-callout-emoji">&#x1f4a1;</div><div class="kg-callout-text"><b><strong style="white-space: pre-wrap;">Have a repair story you would like us to feature? Send a few photos and a paragraph about what went wrong and how you fixed it; we read every one.</strong></b></div></div>
+<p>A minimal call-to-action card:</p>
+<div class="kg-card kg-cta-card kg-cta-bg-grey kg-cta-minimal    " data-layout="minimal">
+
+            <div class="kg-cta-content">
+
+
+                    <div class="kg-cta-content-inner">
+
+                        <div class="kg-cta-text">
+                            <p><span style="white-space: pre-wrap;">&#x1f4e2; The workshop schedule for next month is up. Sessions are small, so sign up early if you want a bench.</span></p>
+                        </div>
+
+
+                    </div>
+
+            </div>
+        </div>
+<p>A sponsored call-to-action card with an unsized image and a button:</p>
+<div class="kg-card kg-cta-card kg-cta-bg-yellow kg-cta-minimal  kg-cta-has-img  kg-cta-centered" data-layout="minimal">
+
+                <div class="kg-cta-sponsor-label-wrapper">
+                    <div class="kg-cta-sponsor-label">
+                        <b><strong style="white-space: pre-wrap;">from our friends at the Lumber Co-op</strong></b>
+                    </div>
+                </div>
+
+            <div class="kg-cta-content">
+
+                    <div class="kg-cta-image-container">
+                        <a href="https://example.org/co-op?ref=workbench"><img src="https://example.org/content/images/2026/01/co-op-logo.webp" alt="CTA Image" data-image-dimensions="240x240"></a>
+                    </div>
+
+
+                    <div class="kg-cta-content-inner">
+
+                        <div class="kg-cta-text">
+                            <p><span style="white-space: pre-wrap;">Looking for well-dried hardwood? </span><a href="https://example.org/co-op?ref=workbench" class="cta-link-color"><b><strong style="white-space: pre-wrap;">The Lumber Co-op</strong></b></a><span style="white-space: pre-wrap;"> is giving readers </span><b><strong style="white-space: pre-wrap;">10 percent</strong></b><span style="white-space: pre-wrap;"> off their first order this fall. </span></p>
+                        </div>
+
+
+                        <a href="https://example.org/co-op?ref=workbench" class="kg-cta-button " style="background-color: #000000; color: #FFFFFF;">
+                            BROWSE THE YARD
+                        </a>
+
+                    </div>
+
+            </div>
+        </div>
+<p>A button card:</p>
+<div class="kg-card kg-button-card kg-align-left"><a href="https://example.org/podcast/episode-12?t=2748" class="kg-btn kg-btn-accent">Shop Talk, Episode #12, 45:47</a></div>
+<p>A gallery card with two rows of lazy images:</p>
+<figure class="kg-card kg-gallery-card kg-width-wide"><div class="kg-gallery-container"><div class="kg-gallery-row"><div class="kg-gallery-image"><img src="https://example.org/content/images/2026/09/joint-1.png" width="934" height="1098" loading="lazy" alt="A dovetail joint" srcset="https://example.org/content/images/size/w600/2026/09/joint-1.png 600w, https://example.org/content/images/2026/09/joint-1.png 934w" sizes="(min-width: 720px) 720px"></div><div class="kg-gallery-image"><img src="https://example.org/content/images/2026/09/joint-2.png" width="1212" height="1050" loading="lazy" alt="A mortise and tenon" srcset="https://example.org/content/images/size/w600/2026/09/joint-2.png 600w, https://example.org/content/images/size/w1000/2026/09/joint-2.png 1000w, https://example.org/content/images/2026/09/joint-2.png 1212w" sizes="(min-width: 720px) 720px"></div></div><div class="kg-gallery-row"><div class="kg-gallery-image"><img src="https://example.org/content/images/2026/09/joint-3.png" width="1310" height="1208" loading="lazy" alt="A bridle joint" srcset="https://example.org/content/images/size/w600/2026/09/joint-3.png 600w, https://example.org/content/images/size/w1000/2026/09/joint-3.png 1000w, https://example.org/content/images/2026/09/joint-3.png 1310w" sizes="(min-width: 720px) 720px"></div><div class="kg-gallery-image"><img src="https://example.org/content/images/2026/09/joint-4.png" width="1084" height="1122" loading="lazy" alt="A half-lap joint" srcset="https://example.org/content/images/size/w600/2026/09/joint-4.png 600w, https://example.org/content/images/size/w1000/2026/09/joint-4.png 1000w, https://example.org/content/images/2026/09/joint-4.png 1084w" sizes="(min-width: 720px) 720px"></div><div class="kg-gallery-image"><img src="https://example.org/content/images/2026/09/joint-5.png" width="1200" height="800" loading="lazy" alt="A finger joint" srcset="https://example.org/content/images/size/w600/2026/09/joint-5.png 600w, https://example.org/content/images/size/w1000/2026/09/joint-5.png 1000w, https://example.org/content/images/2026/09/joint-5.png 1200w" sizes="(min-width: 720px) 720px"></div></div></div></figure>
+<p>A portrait video card:</p>
+<figure class="kg-card kg-video-card kg-width-regular" data-kg-thumbnail="https://example.org/content/media/2026/09/glue-up_thumb.jpg" data-kg-custom-thumbnail>
+            <div class="kg-video-container">
+                <video src="https://example.org/content/media/2026/09/glue-up.mp4" poster="https://example.org/content/media/2026/09/glue-up_thumb.jpg" width="1080" height="1920" playsinline preload="metadata" controls></video>
+
+
+            </div>
+
+        </figure>
+<p>A social embed, without its loader script:</p>
+<figure class="kg-card kg-embed-card"><blockquote class="twitter-tweet"><p lang="en" dir="ltr">finished the long bench today. twelve feet, zero regrets &#x1fab5; <a href="https://example.org/s/bench-photo">example.org/s/bench-photo</a></p>&#x2014; Workbench Journal (@workbench) <a href="https://example.org/workbench/status/2100349174529265967">September 16, 2026</a></blockquote></figure>
+<p>The alternative blockquote style:</p>
+<blockquote class="kg-blockquote-alt">&#x201c;Measure twice, cut once, and then measure again out of habit.&#x201d; &#x2014; <a style="font-weight:300;color: var(--color-secondary-text);" href="https://example.org/sayings/" rel="noopener noreferrer" target="_blank">Shop saying</a></blockquote>
+<p>That is the whole season. Next month: the finishing room.</p>'''

package/assets/catalog/medium.toml

@@ -0,0 +1,26 @@
+# nnw-theme catalog fixture: medium (catalog version 1)
+# Markup: Medium posts, as sent in Medium RSS content:encoded, captured 2026-09.
+# Text and links are synthetic; the structure, classes and attributes are real.
+# Exercises: classless markup; figures whose images have no width or height (they
+#   render as 1600x900 placeholders, so a theme must scale them down), captions with
+#   emphasis, <pre> blocks written with <br> and long lines, an embed iframe, the
+#   1x1 tracking pixel, and the "originally published" footer after an <hr>.
+# Refresh: npx nnw-theme@2 fixture add medium --force
+
+byline = 'Field Notes Engineering Team'
+date_long = 'September 18, 2026'
+date_medium = 'Sep 18, 2026'
+date_short = '9/18/26'
+dateline_style = 'articleDateline'
+datetime_long = 'September 18, 2026 at 11:31:07 AM'
+datetime_medium = 'Sep 18, 2026 at 11:31 AM'
+datetime_short = '9/18/26, 11:31 AM'
+feed_link = 'https://example.org/field-notes?source=rss'
+feed_link_title = 'Field Notes - Medium'
+preferred_link = 'https://example.org/field-notes/caching-the-slow-path-5e1a0c9b7d2f?source=rss'
+time_long = '11:31:07 AM PDT'
+time_medium = '11:31:07 AM'
+time_short = '11:31 AM'
+title = 'Caching the Slow Path: What We Learned Moving Our Search Index Closer to Readers'
+body = '''
+<p><em>By </em><a href="https://example.org/@avery.lind"><em>Avery Lind</em></a><em> and </em><a href="https://example.org/@tomas.reyes"><em>Tomás Reyes</em></a></p><h3>Introduction</h3><p>Most of our search queries are fast. A small share are not, and those few slow ones account for nearly all of the complaints. This post describes how we found them, why caching them was harder than it looked, and what the change did to latency for readers far from our data centers.</p><figure><img alt="" src="https://example.org/max/1024/1*search-latency-overview.png" /><figcaption>Query latency by percentile before the change. The long tail on the right is the slow path.</figcaption></figure><h3>Finding the slow path</h3><p>We started by sampling every query that took longer than a second and grouping them by shape. Three shapes covered 90 percent of the slow queries, and all three shared one expensive step: expanding a reader’s saved filters into a full query.</p><blockquote><em>If a query is slow because of the reader, not the content, the cache key has to be the reader.</em></blockquote><p>That observation shaped everything that followed. Here is the filter definition that expanded into the largest queries:</p><pre>{<br>  "filter": "saved",<br>  "owner": "reader:7f3a",<br>  "expand": ["topics", "authors", "publications", "followed_tags", "muted_tags", "language_preferences"],<br>  "limit": 50<br>}</pre><h4><strong>Why a plain cache did not work</strong></h4><p>A reader’s filters change rarely, but the content they match changes constantly. Caching the results would have served stale lists; caching only the expansion kept results fresh and removed the expensive step.</p><figure><img alt="" src="https://example.org/max/248/1*cache-key-formula.png" /><figcaption><em>The cache key: a hash of the reader’s filter set and its version, so any edit invalidates it.</em></figcaption></figure><ol><li><strong>Hash the filter set.</strong> Readers with identical filters share an entry.</li><li><strong>Version on edit.</strong> Any change to a filter bumps its version and misses the cache.</li><li><strong>Expire slowly.</strong> Entries live for a day, which is longer than most filters go unused.</li></ol><p>The rollout was gradual. We enabled the cache for one region at a time and compared latency against the regions still waiting:</p><figure><img alt="" src="https://example.org/max/1024/1*latency-by-region.jpeg" /><figcaption>Median and 99th-percentile latency by region, two weeks after rollout. Regions farthest from our data centers improved the most.</figcaption></figure><p>We also recorded a short walkthrough of the dashboards we used during the rollout:</p><figure><iframe src="https://example.org/widgets/media.html?src=https%3A%2F%2Fexample.org%2Fembed%2Fsearch-rollout&amp;display_name=Video&amp;type=text%2Fhtml&amp;schema=video" width="854" height="480" frameborder="0" scrolling="no"><a href="https://example.org/media/3b9f0e2c7d1a">https://example.org/media/3b9f0e2c7d1a</a></iframe></figure><h3>What we would do differently</h3><ul><li>Measure the slow path per region from the start; the global numbers hid the worst of it.</li><li>Build the invalidation first. Every bug we shipped was a stale entry.</li></ul><pre>curl -s "https://example.org/api/search?filter=saved&amp;owner=reader:7f3a&amp;expand=topics,authors,publications,followed_tags,muted_tags,language_preferences&amp;limit=50" | jq '.results | length'</pre><h3>Acknowledgements</h3><p>Thanks to <a href="https://example.org/@jun.park"><em>Jun Park</em></a> for the latency dashboards and <a href="https://example.org/@lena.koch"><em>Lena Koch</em></a> for reviewing the invalidation design.</p><img src="https://example.org/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5e1a0c9b7d2f" width="1" height="1" alt=""><hr><p><a href="https://example.org/field-notes/caching-the-slow-path-5e1a0c9b7d2f">Caching the Slow Path: What We Learned Moving Our Search Index Closer to Readers</a> was originally published in <a href="https://example.org/field-notes">Field Notes</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>'''

package/assets/catalog/substack.toml

@@ -0,0 +1,33 @@
+# nnw-theme catalog fixture: substack (catalog version 1)
+# Markup: Substack posts, as sent in Substack RSS content:encoded, captured 2026-09.
+# Text and links are synthetic; the structure, classes and attributes are real.
+# Exercises: captioned-image-container wrapping <picture> with <source> srcsets and
+#   image2 data attributes, wide and narrow images, inline SVG buttons over images,
+#   footnote-anchor / footnote-content footnotes, subscribe and button widgets,
+#   pullquote, callout, embedded post, iframe embeds, and a long publication name.
+# NetNewsWire's own scripts turn the footnote anchors into popovers, and check tests
+# each one.
+# Refresh: npx nnw-theme@2 fixture add substack --force
+
+byline = 'Morgan Halloway'
+date_long = 'September 24, 2026'
+date_medium = 'Sep 24, 2026'
+date_short = '9/24/26'
+dateline_style = 'articleDateline'
+datetime_long = 'September 24, 2026 at 6:02:41 AM'
+datetime_medium = 'Sep 24, 2026 at 6:02 AM'
+datetime_short = '9/24/26, 6:02 AM'
+feed_link = 'https://example.org/'
+feed_link_title = 'The Commonplace Dispatch: Notes on Cities, Transit, and the Stubborn Economics of Everyday Life'
+preferred_link = 'https://example.org/p/why-the-bus-is-late-and-what-it-costs'
+time_long = '6:02:41 AM PDT'
+time_medium = '6:02:41 AM'
+time_short = '6:02 AM'
+title = 'Why the bus is late, what it quietly costs everyone who rides it, and the three fixes that actually work'
+body = '''
+<div class="captioned-image-container"><figure><a class="image-link image2 is-viewable-img" target="_blank" href="https://example.org/image/fetch/w_1456/bus-stop.jpeg" data-component-name="Image2ToDOM"><div class="image2-inset"><picture><source type="image/webp" srcset="https://example.org/image/fetch/w_424,f_webp/bus-stop.jpeg 424w, https://example.org/image/fetch/w_848,f_webp/bus-stop.jpeg 848w, https://example.org/image/fetch/w_1272,f_webp/bus-stop.jpeg 1272w, https://example.org/image/fetch/w_1456,f_webp/bus-stop.jpeg 1456w" sizes="100vw"><img src="https://example.org/image/fetch/w_1456,f_auto/bus-stop.jpeg" width="1456" height="971" data-attrs="{&quot;src&quot;:&quot;https://example.org/public/images/bus-stop_2048x1366.jpeg&quot;,&quot;srcNoWatermark&quot;:null,&quot;fullscreen&quot;:null,&quot;imageSize&quot;:null,&quot;height&quot;:971,&quot;width&quot;:1456,&quot;resizeWidth&quot;:null,&quot;bytes&quot;:402119,&quot;alt&quot;:null,&quot;title&quot;:null,&quot;type&quot;:&quot;image/jpeg&quot;,&quot;href&quot;:null,&quot;belowTheFold&quot;:false,&quot;topImage&quot;:true,&quot;internalRedirect&quot;:null,&quot;isProcessing&quot;:false,&quot;align&quot;:null,&quot;offset&quot;:false}" class="sizing-normal" alt="" srcset="https://example.org/image/fetch/w_424,f_auto/bus-stop.jpeg 424w, https://example.org/image/fetch/w_848,f_auto/bus-stop.jpeg 848w, https://example.org/image/fetch/w_1272,f_auto/bus-stop.jpeg 1272w, https://example.org/image/fetch/w_1456,f_auto/bus-stop.jpeg 1456w" sizes="100vw" fetchpriority="high"></picture><div class="image-link-expand"><div class="pencraft pc-display-flex pc-gap-8 pc-reset"><button tabindex="0" type="button" class="pencraft pc-reset pencraft icon-container restack-image buttonBase-GK1x3M"><svg aria-hidden="true" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke-width="1.5" stroke="var(--color-fg-primary)" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg" class="icon-noB79L"><g><path d="M2.53001 7.81595C3.49179 4.73911 6.43281 2.5 9.91173 2.5C13.1684 2.5 15.9537 4.46214 17.0852 7.23684L17.6179 8.67647M17.6179 8.67647L18.5002 4.26471M17.6179 8.67647L13.6473 6.91176M17.4995 12.1841C16.5378 15.2609 13.5967 17.5 10.1178 17.5C6.86118 17.5 4.07589 15.5379 2.94432 12.7632L2.41165 11.3235M2.41165 11.3235L1.5293 15.7353M2.41165 11.3235L6.38224 13.0882"></path></g></svg></button><button tabindex="0" type="button" class="pencraft pc-reset pencraft icon-container view-image buttonBase-GK1x3M"><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-maximize2 lucide-maximize-2 icon-noB79L"><polyline points="15 3 21 3 21 9"></polyline><polyline points="9 21 3 21 3 15"></polyline><line x1="21" x2="14" y1="3" y2="10"></line><line x1="3" x2="10" y1="21" y2="14"></line></svg></button></div></div></div></a><figcaption class="image-caption">Riders waiting at a stop on a route that is scheduled every ten minutes and arrives, on average, every seventeen. Photo by the author.</figcaption></figure></div><p><span>Every transit agency publishes a schedule, and every rider learns how far to trust it.</span><a class="footnote-anchor" data-component-name="FootnoteAnchorToDOM" id="footnote-anchor-1" href="#footnote-1" target="_self">1</a><span> The gap between the two is where most of the cost of a late bus hides: not in the minutes themselves, but in the slack people build into their days to absorb them.</span></p><p>This week I want to walk through where that slack comes from, how to put a number on it, and which fixes cities have tried that measurably shrink it.<a class="footnote-anchor" data-component-name="FootnoteAnchorToDOM" id="footnote-anchor-2" href="#footnote-2" target="_self">2</a></p><div class="subscription-widget-wrap-editor" data-attrs="{&quot;url&quot;:&quot;https://example.org/subscribe?&quot;,&quot;text&quot;:&quot;Subscribe&quot;,&quot;language&quot;:&quot;en&quot;}" data-component-name="SubscribeWidgetToDOM"><div class="subscription-widget show-subscribe"><div class="preamble"><p class="cta-caption">The Commonplace Dispatch is reader-supported. To receive new posts and support the work, consider becoming a free or paid subscriber.</p></div><form class="subscription-widget-subscribe"><input type="email" class="email-input" name="email" placeholder="Type your email&#8230;" tabindex="-1"><input type="submit" class="button primary" value="Subscribe"><div class="fake-input-wrapper"><div class="fake-input"></div><div class="fake-button"></div></div></form></div></div><h3>Where the minutes go</h3><p>A bus that runs late at the start of its route rarely catches up. Each stop adds a little dwell time, and a crowded bus dwells longer, so the delay compounds as the trip goes on. The chart below shows one route’s average delay by stop over a month of weekday mornings.</p><div class="captioned-image-container"><figure><a class="image-link image2" target="_blank" href="https://example.org/image/fetch/w_1456/delay-by-stop.png" data-component-name="Image2ToDOM"><div class="image2-inset"><picture><source type="image/webp" srcset="https://example.org/image/fetch/w_424,f_webp/delay-by-stop.png 424w, https://example.org/image/fetch/w_848,f_webp/delay-by-stop.png 848w, https://example.org/image/fetch/w_1272,f_webp/delay-by-stop.png 1272w, https://example.org/image/fetch/w_1456,f_webp/delay-by-stop.png 1456w" sizes="100vw"><img src="https://example.org/image/fetch/w_1456,f_auto/delay-by-stop.png" width="1456" height="49" data-attrs="{&quot;src&quot;:&quot;https://example.org/public/images/delay-by-stop_1456x49.png&quot;,&quot;height&quot;:49,&quot;width&quot;:1456,&quot;type&quot;:&quot;image/png&quot;,&quot;belowTheFold&quot;:true,&quot;topImage&quot;:false,&quot;isProcessing&quot;:false,&quot;align&quot;:null,&quot;offset&quot;:false}" class="sizing-normal" alt="" title="" srcset="https://example.org/image/fetch/w_424,f_auto/delay-by-stop.png 424w, https://example.org/image/fetch/w_848,f_auto/delay-by-stop.png 848w, https://example.org/image/fetch/w_1272,f_auto/delay-by-stop.png 1272w, https://example.org/image/fetch/w_1456,f_auto/delay-by-stop.png 1456w" sizes="100vw" loading="lazy"></picture><div></div></div></a></figure></div><p>The pattern is the same on nearly every route we looked at: a small delay at the first few stops, then a steady climb.</p><div class="pullquote"><p>The cost of a late bus is not the minutes it loses. It is the minutes everyone adds to their day in case it does.</p></div><p>A narrow image stays at its own size rather than stretching to the column:</p><div class="captioned-image-container"><figure><a class="image-link image2 is-viewable-img" target="_blank" href="https://example.org/image/fetch/w_616/route-map.jpeg" data-component-name="Image2ToDOM"><div class="image2-inset"><picture><source type="image/webp" srcset="https://example.org/image/fetch/w_424,f_webp/route-map.jpeg 424w, https://example.org/image/fetch/w_848,f_webp/route-map.jpeg 848w" sizes="100vw"><img src="https://example.org/image/fetch/w_616,f_auto/route-map.jpeg" width="616" height="452" data-attrs="{&quot;src&quot;:&quot;https://example.org/public/images/route-map_616x452.jpeg&quot;,&quot;height&quot;:452,&quot;width&quot;:616,&quot;type&quot;:&quot;image/jpeg&quot;,&quot;belowTheFold&quot;:true,&quot;topImage&quot;:false,&quot;isProcessing&quot;:false,&quot;align&quot;:null,&quot;offset&quot;:false}" class="sizing-normal" alt="" srcset="https://example.org/image/fetch/w_424,f_auto/route-map.jpeg 424w, https://example.org/image/fetch/w_848,f_auto/route-map.jpeg 848w" sizes="100vw" loading="lazy"></picture><div></div></div></a><figcaption class="image-caption">The route, with the three stops where most of the delay starts.</figcaption></figure></div><h3>Three fixes that work</h3><ol><li><p><strong>Board at every door.</strong> Letting riders tap on at the back cuts dwell time at busy stops by a third.</p></li><li><p><strong>Paint the lane.</strong> A bus lane only helps if it is kept clear, but even a painted one changes where drivers stop.</p></li><li><p><strong>Hold the signal.</strong> Giving a late bus a few extra seconds of green light keeps small delays from compounding.<a class="footnote-anchor" data-component-name="FootnoteAnchorToDOM" id="footnote-anchor-3" href="#footnote-3" target="_self">3</a></p></li></ol><div class="callout-block" data-callout="true"><h4><strong>&#128338; How we measured</strong></h4><p>We compared scheduled and actual arrival times for every weekday morning trip in August, using the agency’s published real-time feed. <em><strong>Updated September 24, 2026</strong></em></p></div><p>I wrote about the politics of bus lanes last spring, and the argument still holds:</p><div class="embedded-post-wrap" data-attrs="{&quot;id&quot;:171234567,&quot;url&quot;:&quot;https://example.org/p/who-owns-the-curb&quot;,&quot;publication_name&quot;:&quot;The Commonplace Dispatch&quot;}" data-component-name="EmbeddedPostToDOM"><a class="embedded-post" native="true" href="https://example.org/p/who-owns-the-curb"><div class="embedded-post-header"><img class="embedded-post-publication-logo" src="https://example.org/image/fetch/w_56,h_56/logo.png"><span class="embedded-post-publication-name">The Commonplace Dispatch</span></div><div class="embedded-post-title-wrapper"><div class="embedded-post-title">Who owns the curb? </div></div><div class="embedded-post-body">Every city street is a negotiation between people who want to park, people who want to load, and people who want to get through. The curb is where that negotiation gets loud&#8230;</div><div class="embedded-post-cta-wrapper"><span class="embedded-post-cta">Read more</span></div><div class="embedded-post-meta">5 months ago &#183; 212 likes &#183; 48 comments &#183; Morgan Halloway</div></a></div><p>An interactive chart, embedded as an iframe:</p><div id="datawrapper-iframe" class="datawrapper-wrap outer" data-attrs="{&quot;url&quot;:&quot;https://example.org/charts/dw-delay/1/&quot;}" data-component-name="DatawrapperToDOM"><iframe id="iframe-datawrapper" class="datawrapper-iframe" src="https://example.org/charts/dw-delay/1/" width="730" height="471" frameborder="0" scrolling="no"></iframe></div><div class="twitter-embed" data-attrs="{&quot;url&quot;:&quot;https://example.org/transit/status/1971234567&quot;}" data-component-name="Twitter2ToDOM"></div><blockquote><p><span>A schedule is a promise the agency makes to itself. A frequency is a promise it makes to riders.</span></p></blockquote><p><span>That line from a planner I interviewed has stuck with me. If you ride a route that runs often enough, the schedule stops mattering, and so does most of the slack.</span></p><p class="button-wrapper" data-attrs="{&quot;url&quot;:&quot;https://example.org/subscribe?&quot;,&quot;text&quot;:&quot;Subscribe now&quot;,&quot;action&quot;:null,&quot;class&quot;:null}" data-component-name="ButtonCreateButton"><a class="button primary" href="https://example.org/subscribe?"><span>Subscribe now</span></a></p><hr><p>Thanks for reading. Next week: why transfers feel twice as long as they are.</p><div class="footnote" data-component-name="FootnoteToDOM"><a id="footnote-1" href="#footnote-anchor-1" class="footnote-number" contenteditable="false" target="_self">1</a><div class="footnote-content"><p>Most riders, when asked, give a number within a minute or two of the route’s real average delay.</p></div></div><div class="footnote" data-component-name="FootnoteToDOM"><a id="footnote-2" href="#footnote-anchor-2" class="footnote-number" contenteditable="false" target="_self">2</a><div class="footnote-content"><p>The measurements come from a month of weekday mornings; evenings are <a href="https://example.org/p/the-evening-problem">a different story</a>.</p></div></div><div class="footnote" data-component-name="FootnoteToDOM"><a id="footnote-3" href="#footnote-anchor-3" class="footnote-number" contenteditable="false" target="_self">3</a><div class="footnote-content"><p>Signal priority works best on routes with long gaps between intersections. On a dense grid, the gains shrink.</p></div></div>'''
+
+[expect.footnotes.notes]
+"1" = "Most riders, when asked, give a number within a minute or two of the route’s real average delay."
+"2" = "The measurements come from a month of weekday mornings; evenings are a different story."
+"3" = "Signal priority works best on routes with long gaps between intersections. On a dense grid, the gains shrink."

package/assets/catalog/wordpress.toml

@@ -0,0 +1,84 @@
+# nnw-theme catalog fixture: wordpress (catalog version 1)
+# Markup: WordPress 6 block and classic editor output, as sent in WordPress RSS
+# content:encoded, captured 2026-08 and 2026-09.
+# Text and links are synthetic; the structure, classes and attributes are real.
+# Exercises: wp-block-image with an inline pixel width wider than the image,
+#   alignwide / alignfull, wp-element-caption, a gallery, pullquote, table, and embed
+#   figures; classic wp-caption with an inline width, alignleft / alignright floats, and
+#   an inline-styled float beside a paragraph; a <picture> ad; footnotes from WordPress
+#   core, Jetpack and Modern Footnotes; the "appeared first on" feed footer.
+# NetNewsWire's own scripts turn only the Jetpack markers into popovers; a theme script
+# can handle the others, and check then tests each popover.
+# Refresh: npx nnw-theme@2 fixture add wordpress --force
+
+byline = 'Priya Castellanos'
+date_long = 'September 22, 2026'
+date_medium = 'Sep 22, 2026'
+date_short = '9/22/26'
+dateline_style = 'articleDateline'
+datetime_long = 'September 22, 2026 at 6:45:00 AM'
+datetime_medium = 'Sep 22, 2026 at 6:45 AM'
+datetime_short = '9/22/26, 6:45 AM'
+feed_link = 'https://example.org/'
+feed_link_title = 'Gulf Coast Weather Desk'
+preferred_link = 'https://example.org/2026/09/22/one-more-hot-week-then-a-front/'
+time_long = '6:45:00 AM CDT'
+time_medium = '6:45:00 AM'
+time_short = '6:45 AM'
+title = 'One more hot week, then a front with some modest hope behind it'
+body = '''
+<p>Good morning. We are in the last stretch of the hot season, and the week ahead looks like it knows it. Expect highs in the middle 90s through Thursday before a weak front offers some relief this weekend.<sup data-fn="5f2c1a7e-3b4d-4e8f-9a60-1c2d3e4f5a6b" class="fn"><a href="#5f2c1a7e-3b4d-4e8f-9a60-1c2d3e4f5a6b" id="5f2c1a7e-3b4d-4e8f-9a60-1c2d3e4f5a6b-link">1</a></sup></p>
+
+<figure class="wp-block-image size-full is-resized"><img fetchpriority="high" decoding="async" width="830" height="342" src="https://example.org/wp-content/uploads/2026/09/forecast-week.png" alt="" class="wp-image-59086" style="width:869px;height:auto" srcset="https://example.org/wp-content/uploads/2026/09/forecast-week.png 830w, https://example.org/wp-content/uploads/2026/09/forecast-week-300x124.png 300w, https://example.org/wp-content/uploads/2026/09/forecast-week-767x316.png 767w" sizes="(max-width: 830px) 100vw, 830px" /><figcaption class="wp-element-caption">The middle of this week will be hot and mostly dry. (Forecast model)</figcaption></figure>
+
+<h2 class="wp-block-heading">Monday</h2>
+
+<p>Another hot and mostly sunny day, with highs of 94 to 97 degrees. Rain chances are near zero, and winds will be light out of the southwest.<sup id="fnref-59090-1"><a href="#fn-59090-1" class="jetpack-footnote" title="Southwest winds keep the sea breeze from reaching inland neighborhoods.">2</a></sup></p>
+
+<figure class="wp-block-image alignwide size-large"><img decoding="async" width="1024" height="576" src="https://example.org/wp-content/uploads/2026/09/radar-1024x576.png" alt="Radar loop over the coast" class="wp-image-59085" srcset="https://example.org/wp-content/uploads/2026/09/radar-1024x576.png 1024w, https://example.org/wp-content/uploads/2026/09/radar-300x169.png 300w, https://example.org/wp-content/uploads/2026/09/radar-1536x864.png 1536w, https://example.org/wp-content/uploads/2026/09/radar.png 1920w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">A wide image: the radar is quiet, for now.</figcaption></figure>
+
+<figure class="wp-block-image alignfull size-full"><img decoding="async" width="2560" height="720" src="https://example.org/wp-content/uploads/2026/09/skyline-scaled.jpg" alt="" class="wp-image-59084" srcset="https://example.org/wp-content/uploads/2026/09/skyline-scaled.jpg 2560w, https://example.org/wp-content/uploads/2026/09/skyline-300x84.jpg 300w, https://example.org/wp-content/uploads/2026/09/skyline-1024x288.jpg 1024w" sizes="(max-width: 2560px) 100vw, 2560px" /></figure>
+
+<h2 class="wp-block-heading">Tuesday through Thursday</h2>
+
+<p>More of the same. The overnight lows are the real story: they will barely drop below 80 near the coast, which gives the air conditioning no break.<sup class="modern-footnotes-footnote " data-mfn="3" data-mfn-post-scope="000000000000059090_3"><a href="javascript:void(0)" role="button" aria-pressed="false" aria-describedby="mfn-content-000000000000059090_3-3">3</a></sup><span id="mfn-content-000000000000059090_3-3" role="tooltip" class="modern-footnotes-footnote__note" tabindex="0" data-mfn="3">Lows in the 80s are about ten degrees above the long-term normal for late September.</span></p>
+
+<figure class="wp-block-table"><table class="has-fixed-layout"><thead><tr><th>Day</th><th>High</th><th>Low</th><th>Rain chance</th></tr></thead><tbody><tr><td>Tuesday</td><td>96°</td><td>80°</td><td>0%</td></tr><tr><td>Wednesday</td><td>97°</td><td>81°</td><td>10%</td></tr><tr><td>Thursday</td><td>95°</td><td>79°</td><td>20%</td></tr></tbody></table><figcaption class="wp-element-caption">The week ahead, at the airport station.</figcaption></figure>
+
+<figure class="wp-block-pullquote"><blockquote><p>The front will not be dramatic. It will simply be the first one of the season that makes it all the way here.</p><cite>Forecast discussion, Monday morning</cite></blockquote></figure>
+
+<figure class="wp-block-gallery has-nested-images columns-default is-cropped wp-block-gallery-1 is-layout-flex wp-block-gallery-is-layout-flex">
+<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="768" data-id="59081" src="https://example.org/wp-content/uploads/2026/09/clouds-1-1024x768.jpg" alt="" class="wp-image-59081" srcset="https://example.org/wp-content/uploads/2026/09/clouds-1-1024x768.jpg 1024w, https://example.org/wp-content/uploads/2026/09/clouds-1-300x225.jpg 300w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>
+
+<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="768" height="1024" data-id="59082" src="https://example.org/wp-content/uploads/2026/09/clouds-2-768x1024.jpg" alt="" class="wp-image-59082" srcset="https://example.org/wp-content/uploads/2026/09/clouds-2-768x1024.jpg 768w, https://example.org/wp-content/uploads/2026/09/clouds-2-225x300.jpg 225w" sizes="auto, (max-width: 768px) 100vw, 768px" /></figure>
+
+<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="683" data-id="59083" src="https://example.org/wp-content/uploads/2026/09/clouds-3-1024x683.jpg" alt="" class="wp-image-59083" srcset="https://example.org/wp-content/uploads/2026/09/clouds-3-1024x683.jpg 1024w, https://example.org/wp-content/uploads/2026/09/clouds-3-300x200.jpg 300w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>
+<figcaption class="blocks-gallery-caption wp-element-caption">Reader photos of last week’s afternoon clouds.</figcaption></figure>
+
+<figure class="wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
+<iframe loading="lazy" title="How a cold front forms" width="640" height="360" src="https://example.org/embed/cold-front?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</div></figure>
+
+<h2 class="wp-block-heading">The weekend</h2>
+
+<div id="attachment_59070" style="width: 1034px" class="wp-caption aligncenter"><img aria-describedby="caption-attachment-59070" decoding="async" loading="lazy" class="size-large wp-image-59070" src="https://example.org/wp-content/uploads/2026/09/rain-chances-1024x696.png" alt="" width="1024" height="696" srcset="https://example.org/wp-content/uploads/2026/09/rain-chances-1024x696.png 1024w, https://example.org/wp-content/uploads/2026/09/rain-chances-300x204.png 300w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><p id="caption-attachment-59070" class="wp-caption-text">A classic-editor caption: its inline width is 10 pixels wider than the image.</p></div>
+
+<p><img loading="lazy" decoding="async" class="alignright size-medium wp-image-59071" src="https://example.org/wp-content/uploads/2026/09/thermometer-300x200.jpg" alt="" width="300" height="200" />The front should arrive Saturday evening and bring rain chances up to about 30 percent. Behind it, lows fall into the upper 60s for the first time since May. This paragraph wraps beside an image floated right by the classic editor, and it goes on long enough to run past the bottom of the image on a wide window.</p>
+
+<p><img loading="lazy" decoding="async" class="alignleft size-thumbnail wp-image-59072" src="https://example.org/wp-content/uploads/2026/09/umbrella-150x150.jpg" alt="" width="150" height="150" />A shorter paragraph beside a left-floated thumbnail.</p>
+
+<figure style="float:left; margin: 0 1.5em 1em 0;"><img width="96" height="96" src="https://example.org/wp-content/uploads/2026/03/station-icon-128x128.png" class="type:primaryImage wp-post-image" alt="Station icon" decoding="async" /></figure><p>A feed that floats a small icon in an inline-styled figure, followed by a real paragraph, which must wrap under the icon rather than run down beside it as a narrow column. After the front, the forecast settles into dry, mild days with highs near 85 and clear nights. It is the kind of weather this region waits all summer for, and it should last at least through the middle of next week.</p>
+
+<p style="margin-top: 3em"><a href="https://example.org/sponsor/"><picture><source srcset="https://example.org/wp-content/uploads/2026/05/sponsor-640x200.png" media="(max-width: 600px)" type="image/png"><img src="https://example.org/wp-content/uploads/2026/05/sponsor-1456x180.png" srcset="https://example.org/wp-content/uploads/2026/05/sponsor-1456x180.png 1456w, https://example.org/wp-content/uploads/2026/05/sponsor-1456x180-640x79.png 640w" alt="Sponsored by a local generator installer"></picture></a></p>
+
+<ol class="wp-block-footnotes"><li id="5f2c1a7e-3b4d-4e8f-9a60-1c2d3e4f5a6b">The front is the first of the season to reach the coast; earlier ones stalled well inland. <a href="#5f2c1a7e-3b4d-4e8f-9a60-1c2d3e4f5a6b-link" aria-label="Jump to footnote reference 1">↩︎</a></li></ol>
+
+<div class="footnotes">
+<hr />
+<ol>
+<li id="fn-59090-1">
+Southwest winds keep the sea breeze from reaching inland neighborhoods.&#160;<a href="#fnref-59090-1">&#8617;</a>
+</li>
+</ol>
+</div>
+<p>The post <a href="https://example.org/2026/09/22/one-more-hot-week-then-a-front/">One more hot week, then a front with some modest hope behind it</a> appeared first on <a href="https://example.org">Gulf Coast Weather Desk</a>.</p>'''

package/assets/footnotes.js

@@ -1,7 +1,8 @@
 // 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
 // a.footnote whose hash names an element; main.js adds that class to local
-// sup > a[href*='#fn'] links, and a theme script may add it to other formats.
+// sup > a[href*='#fn'] links and Substack's a[id^='footnote-anchor-'] links, and a
+// theme script may add it to other formats.
 //
 // 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
@@ -31,7 +32,15 @@ async ({notes = null, plain_links = [], keep_with_word = false} = {}) => {
 		if (document.querySelectorAll(`[id="${CSS.escape(id)}"]`).length > 1) {
 			fail(`footnote ${label(marker)}: more than one element has id ${id}`);
 		}
-		const note = text(target);
+		// newsfoot shows a Substack note from the elements after its backlink
+		// <a id="footnote-N">N</a>, and any other note from the target itself.
+		let note = text(target);
+		if (marker.matches("a[id^='footnote-anchor-']")) {
+			let content = "";
+			for (let node = target.nextElementSibling; node && !node.matches("a[id^='footnote-']");
+				node = node.nextElementSibling) content += node.textContent;
+			note = content.replace(/\s+/g, " ").trim();
+		}
 		if (note) noteFor.set(marker, note);
 		else fail(`footnote ${label(marker)}: note is empty`);
 	}

package/assets/guide/fixtures.md

@@ -10,6 +10,31 @@ checked on macOS and iPhone in light and dark. Names used by check scenarios
 (`large-text`, `article-javascript-off`) are reserved. Use `'''literal'''` strings for
 HTML bodies so they need no escaping.
 
+## Platform fixtures
+
+Much of a theme's hardest content comes from the software that published the article:
+Ghost cards, WordPress captions with inline pixel widths, Substack's image and footnote
+wrappers. `nnw-theme` ships ready-made fixtures modeled on that markup:
+
+```sh
+npx nnw-theme@2 fixture list                     # names, summaries, and which you have
+npx nnw-theme@2 fixture add ghost substack       # copy into fixtures/ghost.toml, ...
+npx nnw-theme@2 fixture add wordpress --force    # replace a copy with the current one
+```
+
+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
+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
+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.
+
+## 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
@@ -18,8 +43,8 @@ same-size placeholder and a network feed icon for a generated one; do not inline
 fetch the originals.
 
 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; a theme script
-may add it to other formats. `check` requires every visible marker to resolve to a
+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
 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:

package/assets/guide/skill.md

@@ -19,7 +19,8 @@ specific reading needs. Prefer changing the CSS variables and rules in
 `stylesheet.css`. Edit `template.html` only when the requested structure or behavior
 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.
+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.
 
 Iterate with this loop:
 

package/dist/commands/check.js

@@ -5,7 +5,7 @@ import { checkPages } from "../browser.js";
 import { interactive, openInBrowser, promptConfirm } from "../interactive.js";
 import { version } from "../main.js";
 import { buildArchive } from "../package.js";
-import { findRoot, findTheme, fixturePath, footnoteExpectations, readFixture, ThemeError, themeStem, } from "../project.js";
+import { findRoot, findTheme, fixturePath, footnoteExpectations, readFixture, repositoryFixtures, ThemeError, themeStem, } from "../project.js";
 import { checkTargets, extraFixtures, renderSite, writeGallery, } from "../render.js";
 import { staleStubs } from "../stubs.js";
 import { printWarnings } from "./package.js";
@@ -17,6 +17,13 @@ export function expectations(root, targets) {
     }
     return result;
 }
+/** A one-line pointer to the platform fixtures, for a theme with no fixtures of its own. */
+export function fixtureHint(root) {
+    if (repositoryFixtures(root).length)
+        return undefined;
+    return ("Hint: this theme has no fixtures of its own. `npx nnw-theme@2 fixture list` " +
+        "shows ready-made ones modeled on WordPress, Ghost, Substack, and Medium markup.");
+}
 async function offerToOpen(index, choice) {
     const open = choice ?? (interactive() && (await promptConfirm("Open the preview?", true)));
     if (open)
@@ -58,6 +65,9 @@ export default async function check({ values }) {
         writeFileSync(report, `PASS\n${targets.length} WebKit renders checked\nPackage: ${packageName}\n${footer}`, "utf8");
         console.log(`PASS: ${targets.length} WebKit renders and ${packageName}`);
     }
+    const hint = fixtureHint(root);
+    if (hint)
+        console.log(hint);
     const index = join(site, "index.html");
     console.log(`Preview: ${index}`);
     await offerToOpen(index, values.open);

package/dist/commands/fixture.js

@@ -0,0 +1,82 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CATALOG_FIXTURES } from "../commands.js";
+import { catalogPath, findRoot, ThemeError } from "../project.js";
+const VERSION_RE = /^# nnw-theme catalog fixture: \S+ \(catalog version (\d+)\)$/m;
+/** The catalog version a fixture file's header records, if it has one. */
+export function catalogVersion(text) {
+    const match = VERSION_RE.exec(text);
+    return match ? Number(match[1]) : undefined;
+}
+/** How a repository's copy of a catalog fixture compares with the catalog's. */
+export function catalogStatus(root, name) {
+    const own = join(root, "fixtures", `${name}.toml`);
+    if (!existsSync(own))
+        return "";
+    const ours = readFileSync(own, "utf8");
+    const theirs = readFileSync(catalogPath(name), "utf8");
+    if (ours === theirs)
+        return "added";
+    const [have, latest] = [catalogVersion(ours), catalogVersion(theirs)];
+    if (have !== undefined && latest !== undefined && have < latest) {
+        return `added (version ${have}; version ${latest} available)`;
+    }
+    return "added (differs)";
+}
+/** Copy catalog fixtures into fixtures/, keeping existing files unless forced. */
+export function addCatalogFixtures(root, names, force = false) {
+    const result = { added: [], current: [], skipped: [] };
+    mkdirSync(join(root, "fixtures"), { recursive: true });
+    for (const name of new Set(names)) {
+        const source = catalogPath(name);
+        const destination = join(root, "fixtures", `${name}.toml`);
+        if (existsSync(destination)) {
+            if (readFileSync(destination, "utf8") === readFileSync(source, "utf8")) {
+                result.current.push(name);
+                continue;
+            }
+            if (!force) {
+                result.skipped.push(name);
+                continue;
+            }
+        }
+        copyFileSync(source, destination);
+        result.added.push(name);
+    }
+    return result;
+}
+export function list() {
+    let root;
+    try {
+        root = findRoot();
+    }
+    catch (error) {
+        if (!(error instanceof ThemeError))
+            throw error;
+    }
+    const names = Object.keys(CATALOG_FIXTURES);
+    const width = Math.max(...names.map((name) => name.length)) + 2;
+    const summaryWidth = Math.max(...Object.values(CATALOG_FIXTURES).map((text) => text.length)) + 2;
+    for (const [name, summary] of Object.entries(CATALOG_FIXTURES)) {
+        const status = root ? catalogStatus(root, name) : "";
+        console.log(`${name.padEnd(width)}${status ? summary.padEnd(summaryWidth) + status : summary}`);
+    }
+    console.log("\nAdd one with `npx nnw-theme@2 fixture add NAME`. Each adds four renders to every check.");
+}
+export function add({ values, positionals }) {
+    const root = findRoot();
+    const { added, current, skipped } = addCatalogFixtures(root, positionals, values.force === true);
+    for (const name of added)
+        console.log(`Added fixtures/${name}.toml.`);
+    for (const name of current)
+        console.log(`fixtures/${name}.toml is already current.`);
+    if (added.length) {
+        const renders = added.length * 4;
+        console.log(`Preview with \`npx nnw-theme@2 render ${added.join(" ")}\`, then run ` +
+            `\`npx nnw-theme@2 check\` (${renders} more renders).`);
+    }
+    if (skipped.length) {
+        throw new ThemeError(`kept existing ${skipped.map((name) => `fixtures/${name}.toml`).join(", ")}; ` +
+            "pass --force to replace with the catalog version");
+    }
+}

package/dist/commands/init.js

@@ -2,10 +2,12 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { setupWebkit } from "../browser.js";
+import { CATALOG_FIXTURE_NAMES } from "../commands.js";
 import { interactive, promptConfirm, promptText } from "../interactive.js";
 import { findRoot, findTheme, IDENTITY_END, IDENTITY_START, PLACEHOLDER_MARKER, readPlist, ThemeError, writePlist, } from "../project.js";
 import { pyRepr } from "../pyformat.js";
 import { urlsplit } from "../urlparse.js";
+import { addCatalogFixtures } from "./fixture.js";
 import { marketplaceEnable } from "./marketplace.js";
 function slug(value) {
     return value
@@ -153,6 +155,24 @@ export default async function init({ values }) {
     }
     if (marketplace === "yes")
         marketplaceEnable();
+    let platformFixtures = flag("platform-fixtures");
+    if (platformFixtures === undefined && interactive()) {
+        const renders = CATALOG_FIXTURE_NAMES.length * 4;
+        platformFixtures = (await promptConfirm(`Add platform fixtures (${CATALOG_FIXTURE_NAMES.join(", ")})? They catch layout ` +
+            "bugs from real publishing platforms' markup, but add " +
+            `${renders} renders to every check, so check and CI take longer.`, false))
+            ? "yes"
+            : "no";
+        if (platformFixtures === "no") {
+            console.log("Add any of them later: `npx nnw-theme@2 fixture list`.");
+        }
+    }
+    if (platformFixtures === "yes") {
+        const { added } = addCatalogFixtures(root, CATALOG_FIXTURE_NAMES);
+        if (added.length) {
+            console.log(`Added ${added.map((name) => `fixtures/${name}.toml`).join(", ")}.`);
+        }
+    }
     let install = values["install-browser"];
     if (install === undefined && prompting && interactive()) {
         install = await promptConfirm("Set up WebKit for previews now?");

package/dist/commands.js

@@ -12,6 +12,17 @@ export const GUIDE_TOPICS = [
 export const SHELLS = ["fish", "zsh", "bash"];
 /** Fixtures that ship in the package; also in project.ts, which reads them. */
 export const BUILT_IN_FIXTURE_NAMES = ["article", "kitchen-sink"];
+/**
+ * Platform fixtures a theme can copy into fixtures/ with `fixture add`, each with the
+ * summary `fixture list` prints. They live in assets/catalog/ and never run unless added.
+ */
+export const CATALOG_FIXTURES = {
+    ghost: "Ghost cards, galleries, and lazy images",
+    medium: "Medium figures, unsized images, and footer",
+    substack: "Substack images, widgets, and footnotes",
+    wordpress: "WordPress block and classic editor markup",
+};
+export const CATALOG_FIXTURE_NAMES = Object.keys(CATALOG_FIXTURES);
 const allowRemoteMedia = {
     name: "allow-remote-media",
     type: "boolean",
@@ -22,7 +33,8 @@ export const COMMANDS = [
         name: "init",
         summary: "personalize a fresh copy of the template (run once)",
         description: "Name the theme, choose its permanent identifier, and optionally join the " +
-            "marketplace and install WebKit. Runs once, while .nnw-theme-uninitialized exists.",
+            "marketplace, add the platform fixtures, and install WebKit. Runs once, while " +
+            ".nnw-theme-uninitialized exists.",
         options: [
             { name: "name", type: "string" },
             { name: "creator", type: "string" },
@@ -31,6 +43,12 @@ export const COMMANDS = [
             { name: "confirm-identifier", type: "string" },
             { name: "github-user", type: "string" },
             { name: "marketplace", type: "string", choices: ["yes", "no"] },
+            {
+                name: "platform-fixtures",
+                type: "string",
+                choices: ["yes", "no"],
+                help: "add every platform fixture (more renders in each check)",
+            },
             { name: "install-browser", type: "boolean", negatable: true },
         ],
     },
@@ -111,6 +129,42 @@ export const COMMANDS = [
         summary: "validate the theme and build its release ZIP (no WebKit)",
         options: [{ name: "output-dir", type: "string", default: "dist" }, allowRemoteMedia],
     },
+    {
+        name: "fixture",
+        summary: "add fixtures modeled on WordPress, Ghost, Substack, and Medium",
+        description: "Copy ready-made fixtures with markup modeled on what major publishing platforms " +
+            "send into fixtures/, where preview and check pick them up. Each one adds four " +
+            "renders to every check.",
+        options: [],
+        subcommands: [
+            {
+                name: "list",
+                summary: "list the platform fixtures and which ones this theme has",
+                options: [],
+            },
+            {
+                name: "add",
+                summary: "copy platform fixtures into fixtures/",
+                description: "Copy each named platform fixture to fixtures/NAME.toml. An existing file is " +
+                    "kept unless --force is given. Each added fixture is checked on Mac and iPhone " +
+                    "in light and dark: four more renders per check.",
+                options: [
+                    {
+                        name: "force",
+                        type: "boolean",
+                        help: "replace existing copies with the current version",
+                    },
+                ],
+                positionals: {
+                    name: "names",
+                    help: `platform fixtures to add: ${CATALOG_FIXTURE_NAMES.join(", ")}`,
+                    variadic: true,
+                    choices: CATALOG_FIXTURE_NAMES,
+                    required: true,
+                },
+            },
+        ],
+    },
     {
         name: "capture",
         summary: "explain how to capture a real article from NetNewsWire as a fixture",

package/dist/completion.js

@@ -47,59 +47,88 @@ export function fish() {
         `complete -c ${PROGRAM} -n __fish_use_subcommand -l version -d 'Print the version'`,
     ];
     for (const command of visible()) {
-        const when = `'__fish_seen_subcommand_from ${command.name}'`;
         lines.push(`complete -c ${PROGRAM} -n __fish_use_subcommand -a ${command.name} -d ${fishQuote(command.summary)}`);
-        for (const option of command.options) {
-            const description = option.help ? ` -d ${fishQuote(option.help)}` : "";
-            let values = "";
-            if (option.completeFixtures)
-                values = " -x -a '(__nnw_theme_fixtures)'";
-            else if (option.choices)
-                values = ` -x -a ${fishQuote(option.choices.join(" "))}`;
-            else if (option.type === "string")
-                values = option.name.endsWith("dir") ? " -r -F" : " -x";
-            lines.push(`complete -c ${PROGRAM} -n ${when} -l ${option.name}${values}${description}`);
-            if (option.negatable)
-                lines.push(`complete -c ${PROGRAM} -n ${when} -l no-${option.name}`);
+        const seen = `__fish_seen_subcommand_from ${command.name}`;
+        if (!command.subcommands) {
+            fishCommand(lines, command, `'${seen}'`);
+            continue;
         }
-        const words = positionalWords(command);
-        if (words === null)
-            lines.push(`complete -c ${PROGRAM} -n ${when} -a '(__nnw_theme_fixtures)'`);
-        else if (words) {
-            const subs = command.subcommands ?? [];
-            for (const word of words) {
-                const sub = subs.find((item) => item.name === word);
-                const description = sub ? ` -d ${fishQuote(sub.summary)}` : "";
-                lines.push(`complete -c ${PROGRAM} -n ${when} -a ${word}${description}`);
-            }
+        const names = command.subcommands.map((sub) => sub.name).join(" ");
+        for (const sub of command.subcommands) {
+            lines.push(`complete -c ${PROGRAM} -n '${seen}; and not __fish_seen_subcommand_from ${names}' ` +
+                `-a ${sub.name} -d ${fishQuote(sub.summary)}`);
+            fishCommand(lines, sub, `'${seen}; and __fish_seen_subcommand_from ${sub.name}'`);
         }
     }
     return `${lines.join("\n")}\n`;
 }
+/** A leaf command's options and positional words, completed while `when` holds. */
+function fishCommand(lines, command, when) {
+    for (const option of command.options) {
+        const description = option.help ? ` -d ${fishQuote(option.help)}` : "";
+        let values = "";
+        if (option.completeFixtures)
+            values = " -x -a '(__nnw_theme_fixtures)'";
+        else if (option.choices)
+            values = ` -x -a ${fishQuote(option.choices.join(" "))}`;
+        else if (option.type === "string")
+            values = option.name.endsWith("dir") ? " -r -F" : " -x";
+        lines.push(`complete -c ${PROGRAM} -n ${when} -l ${option.name}${values}${description}`);
+        if (option.negatable)
+            lines.push(`complete -c ${PROGRAM} -n ${when} -l no-${option.name}`);
+    }
+    const words = positionalWords(command);
+    if (words === null)
+        lines.push(`complete -c ${PROGRAM} -n ${when} -a '(__nnw_theme_fixtures)'`);
+    else if (words)
+        lines.push(`complete -c ${PROGRAM} -n ${when} -a ${fishQuote(words.join(" "))}`);
+}
 // bash ---------------------------------------------------------------------------
+/** The case body completing a leaf command's options and positional words. */
+function bashCommand(command, indent) {
+    const valueCases = [];
+    for (const option of command.options) {
+        if (option.type !== "string")
+            continue;
+        let reply = "COMPREPLY=()";
+        if (option.completeFixtures)
+            reply = 'COMPREPLY=($(compgen -W "$(_nnw_theme_fixtures)" -- "$cur"))';
+        else if (option.choices)
+            reply = `COMPREPLY=($(compgen -W ${single(option.choices.join(" "))} -- "$cur"))`;
+        else if (option.name.endsWith("dir"))
+            reply = 'COMPREPLY=($(compgen -d -- "$cur"))';
+        valueCases.push(`${indent}  --${option.name}) ${reply}; return ;;`);
+    }
+    const words = positionalWords(command);
+    let positional = "COMPREPLY=()";
+    if (words === null)
+        positional = 'COMPREPLY=($(compgen -W "$(_nnw_theme_fixtures)" -- "$cur"))';
+    else if (words)
+        positional = `COMPREPLY=($(compgen -W ${single(words.join(" "))} -- "$cur"))`;
+    return [
+        ...(valueCases.length ? [`${indent}case "$prev" in`, ...valueCases, `${indent}esac`] : []),
+        `${indent}if [[ "$cur" == -* ]]; then`,
+        `${indent}  COMPREPLY=($(compgen -W ${single(allFlags(command).join(" "))} -- "$cur"))`,
+        `${indent}else`,
+        `${indent}  ${positional}`,
+        `${indent}fi`,
+    ];
+}
 export function bash() {
     const cases = [];
     for (const command of visible()) {
-        const valueCases = [];
-        for (const option of command.options) {
-            if (option.type !== "string")
-                continue;
-            let reply = "COMPREPLY=()";
-            if (option.completeFixtures)
-                reply = 'COMPREPLY=($(compgen -W "$(_nnw_theme_fixtures)" -- "$cur"))';
-            else if (option.choices)
-                reply = `COMPREPLY=($(compgen -W ${single(option.choices.join(" "))} -- "$cur"))`;
-            else if (option.name.endsWith("dir"))
-                reply = 'COMPREPLY=($(compgen -d -- "$cur"))';
-            valueCases.push(`        --${option.name}) ${reply}; return ;;`);
+        cases.push(`    ${command.name})`);
+        if (command.subcommands) {
+            const names = command.subcommands.map((sub) => sub.name).join(" ");
+            cases.push("      if (( COMP_CWORD == 2 )); then", `        COMPREPLY=($(compgen -W ${single(`${names} --help`)} -- "$cur"))`, "        return", "      fi", `      case "\${COMP_WORDS[2]}" in`);
+            for (const sub of command.subcommands) {
+                cases.push(`        ${sub.name})`, ...bashCommand(sub, "          "), "          ;;");
+            }
+            cases.push("      esac");
         }
-        const words = positionalWords(command);
-        let positional = "COMPREPLY=()";
-        if (words === null)
-            positional = 'COMPREPLY=($(compgen -W "$(_nnw_theme_fixtures)" -- "$cur"))';
-        else if (words)
-            positional = `COMPREPLY=($(compgen -W ${single(words.join(" "))} -- "$cur"))`;
-        cases.push(`    ${command.name})`, ...(valueCases.length ? ['      case "$prev" in', ...valueCases, "      esac"] : []), '      if [[ "$cur" == -* ]]; then', `        COMPREPLY=($(compgen -W ${single(allFlags(command).join(" "))} -- "$cur"))`, "      else", `        ${positional}`, "      fi", "      ;;");
+        else
+            cases.push(...bashCommand(command, "      "));
+        cases.push("      ;;");
     }
     return `# nnw-theme completion for bash. Install: source <(npx --yes nnw-theme@2 completion bash)
 if ! type -P ${PROGRAM} >/dev/null 2>&1; then
@@ -151,17 +180,28 @@ function zshOption(option) {
         specs.push(`'--no-${option.name}[${help}]'`);
     return specs;
 }
+/** An _arguments call completing a leaf command's options and positional words. */
+function zshArguments(command) {
+    const specs = [...command.options.flatMap(zshOption), "'(- *)'{-h,--help}'[show help]'"];
+    const words = positionalWords(command);
+    if (words === null)
+        specs.push("'*:fixture:_nnw_theme_fixtures'");
+    else if (words) {
+        const position = command.positionals?.variadic ? "*" : "1";
+        specs.push(`'${position}:${command.positionals?.name ?? "command"}:(${words.join(" ")})'`);
+    }
+    return `_arguments -s ${specs.join(" ")}`;
+}
 export function zsh() {
     const described = visible().map((command) => `    '${command.name}:${zshEscape(command.summary)}'`);
     const cases = [];
     for (const command of visible()) {
-        const specs = [...command.options.flatMap(zshOption), "'(- *)'{-h,--help}'[show help]'"];
-        const words = positionalWords(command);
-        if (words === null)
-            specs.push("'*:fixture:_nnw_theme_fixtures'");
-        else if (words)
-            specs.push(`'1:${command.positionals?.name ?? "command"}:(${words.join(" ")})'`);
-        cases.push(`    ${command.name}) _arguments -s ${specs.join(" ")} ;;`);
+        if (!command.subcommands) {
+            cases.push(`    ${command.name}) ${zshArguments(command)} ;;`);
+            continue;
+        }
+        const described = command.subcommands.map((sub) => `'${sub.name}:${zshEscape(sub.summary)}'`);
+        cases.push(`    ${command.name})`, "      if (( CURRENT == 2 )); then", `        local -a subcommands=(${described.join(" ")})`, `        _describe -t commands 'nnw-theme ${command.name} command' subcommands`, "        return", "      fi", "      local subcommand=$words[2]", "      shift words", "      (( CURRENT-- ))", "      case $subcommand in", ...command.subcommands.map((sub) => `        ${sub.name}) ${zshArguments(sub)} ;;`), "      esac", "      ;;");
     }
     return `# nnw-theme completion for zsh. Install: source <(npx --yes nnw-theme@2 completion zsh)
 if (( ! $+commands[${PROGRAM}] )); then

package/dist/main.js

@@ -14,6 +14,8 @@ const HANDLERS = {
     capture: () => import("./commands/capture.js"),
     bump: () => import("./commands/bump.js"),
     "marketplace enable": () => import("./commands/marketplace.js"),
+    "fixture list": async () => ({ default: (await import("./commands/fixture.js")).list }),
+    "fixture add": async () => ({ default: (await import("./commands/fixture.js")).add }),
     guide: () => import("./commands/guide.js"),
     completion: () => import("./commands/completion.js"),
     update: () => import("./commands/update.js"),
@@ -91,8 +93,12 @@ export function commandHelp(command, path) {
     if (command.subcommands)
         usage.push(`{${command.subcommands.map((sub) => sub.name).join(",")}}`);
     if (command.positionals) {
+        const { variadic, required } = command.positionals;
         const name = command.positionals.name.toUpperCase();
-        usage.push(command.positionals.variadic ? `[${name} ...]` : `[${name}]`);
+        if (required)
+            usage.push(variadic ? `${name} [${name} ...]` : name);
+        else
+            usage.push(variadic ? `[${name} ...]` : `[${name}]`);
     }
     const sections = [
         wrap(usage.join(" "), 0),
@@ -158,6 +164,9 @@ function parseCommand(command, argv) {
     if (!spec && positionals.length) {
         throw new UsageError(`unrecognized arguments: ${positionals.join(" ")}`);
     }
+    if (spec?.required && !positionals.length) {
+        throw new UsageError(`the following arguments are required: ${spec.name}`);
+    }
     if (spec && !spec.variadic && positionals.length > 1) {
         throw new UsageError(`unrecognized arguments: ${positionals.slice(1).join(" ")}`);
     }

package/dist/project.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseToml } from "smol-toml";
-import { BUILT_IN_FIXTURE_NAMES } from "./commands.js";
+import { BUILT_IN_FIXTURE_NAMES, CATALOG_FIXTURE_NAMES } from "./commands.js";
 import { buildPlist, parsePlist } from "./plist.js";
 export const REQUIRED_THEME_FILES = ["Info.plist", "template.html", "stylesheet.css"];
 export const PLACEHOLDER_MARKER = ".nnw-theme-uninitialized";
@@ -136,6 +136,13 @@ export function repositoryFixtures(root) {
         .map((name) => name.slice(0, -".toml".length))
         .sort();
 }
+/** A platform fixture in the package's catalog, which `fixture add` copies from. */
+export function catalogPath(name) {
+    if (!CATALOG_FIXTURE_NAMES.includes(name)) {
+        throw new ThemeError(`unknown platform fixture: ${name} (choose from ${CATALOG_FIXTURE_NAMES.join(", ")})`);
+    }
+    return packagePath("assets", "catalog", `${name}.toml`);
+}
 /** Where a fixture lives: the repository's copy, else the package's built-in one. */
 export function fixturePath(root, name) {
     const own = join(root, "fixtures", `${name}.toml`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nnw-theme",
-	"version": "2.0.3",
+	"version": "2.1.0",
 	"description": "Create, preview, check, and publish a NetNewsWire theme.",
 	"license": "Apache-2.0",
 	"author": "Dave Marquard",