nnw-theme 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1 +1,75 @@
-Placeholder. See https://github.com/dave-atx/nnw-theme
+# nnw-theme
+
+Tools for building [NetNewsWire](https://netnewswire.com) themes. `nnw-theme` renders a
+theme into a live preview gallery, checks it in WebKit on Mac, iPhone, and iPad in light
+and dark, and packages it for release.
+
+Start a theme from
+[netnewswire-theme-template](https://github.com/dave-atx/netnewswire-theme-template)
+(**Use this template**). The repository you get holds only the theme; the tooling runs
+from npm, so it never needs updating by hand.
+
+Not affiliated with or endorsed by Ranchero Software or the NetNewsWire project.
+
+## Usage
+
+Run it with `npx`, from anywhere inside the theme repository. It needs Node 24 or newer.
+
+```sh
+npx nnw-theme@1 init       # once: name the theme and choose its permanent identifier
+npx nnw-theme@1 setup      # once per machine: install the WebKit build checks use
+npx nnw-theme@1 preview    # live gallery that rebuilds on save
+npx nnw-theme@1 check      # the release gate: package, render, and test every case
+```
+
+`@1` picks the newest 1.x release, so fixes arrive on their own and a breaking 2.0 never
+does. Don't install it globally or add it to a theme repository. To use one exact
+version, name it: `npx nnw-theme@1.4.2 check`.
+
+| Command | What it does |
+| --- | --- |
+| `init` | Personalize a fresh copy of the template (run once) |
+| `setup` | Install the WebKit browser that `check` and `screenshot` use (`--with-deps` on Linux CI) |
+| `preview` | Serve the gallery on localhost, open it, and rebuild 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 and save its image; `--promote` makes it the marketplace card |
+| `package` | Validate and build `dist/<Name>.nnwtheme.zip` |
+| `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 |
+| `guide [topic]` | Print the authoring guide: `skill`, `theme-format`, `fixtures`, `design-checklist`, `publishing` |
+| `completion <shell>` | Print shell completion for `fish`, `zsh`, or `bash` |
+
+Every command takes `--help`.
+
+## Shell completion
+
+`completion` prints a script that completes commands, options, and fixture names. It
+also defines an `nnw-theme` command that runs `npx --yes nnw-theme@1`, so you can type
+`nnw-theme check`. The wrapper is skipped when a real `nnw-theme` is already installed.
+
+```sh
+# fish
+npx nnw-theme@1 completion fish > ~/.config/fish/conf.d/nnw-theme.fish
+# zsh (~/.zshrc, after compinit)
+source <(npx --yes nnw-theme@1 completion zsh)
+# bash (~/.bashrc)
+source <(npx --yes nnw-theme@1 completion bash)
+```
+
+Fish loads a file rather than running npx at every shell start. Zsh and bash users can
+do the same with a file in `~/.zsh/` or `~/.local/share/bash-completion/completions/`.
+Regenerate it when commands change.
+
+## GitHub workflows
+
+Theme repositories call this repository's reusable workflows, pinned to `@v1`:
+`theme-check.yml` (the release gate on every push), `theme-pages.yml` (publishes the
+checked gallery), `theme-release.yml` (manual release), and `theme-screenshot.yml`
+(refreshes the marketplace image). The template carries the ten-line callers.
+
+## Developing
+
+See [AGENTS.md](AGENTS.md). Report problems at
+https://github.com/dave-atx/nnw-theme/issues with the version line `check` prints.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-party notices
+
+The published package includes rendering files from
+[NetNewsWire](https://github.com/Ranchero-Software/NetNewsWire), release `mac-7.1.3`,
+commit `f2daca0f24f29c08d9cb16e1bdc56293fd6fe286`, 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
+never added to a theme's release archive.
+
+nnw-theme is not affiliated with or endorsed by Ranchero Software or the NetNewsWire
+project.
+
+The npm dependencies listed in `package.json` are distributed under their own licenses.

package/assets/fixtures/article.toml

@@ -0,0 +1,24 @@
+title = "A Walk Through the Quiet City"
+preferred_link = "https://example.org/articles/quiet-city"
+external_link = "https://example.org/articles/quiet-city"
+external_link_label = "Read on Example Journal"
+external_link_stripped = "example.org"
+feed_link = "https://example.org/"
+feed_link_title = "Example Journal"
+byline = "Mara Bell"
+date_long = "September 17, 2026"
+date_medium = "Sep 17, 2026"
+date_short = "9/17/26"
+datetime_long = "2026-09-17T08:30:00-07:00"
+datetime_medium = "Sep 17, 2026 at 8:30 AM"
+datetime_short = "9/17/26, 8:30 AM"
+time_long = "8:30:00 AM PDT"
+time_medium = "8:30:00 AM"
+time_short = "8:30 AM"
+avatar_src = ""
+body = """
+<p class="standfirst">Before the doors opened, the city belonged to bakers, bus drivers, and the first warm light on the brickwork.</p>
+<p>I took the long route toward the river. A row of plane trees made a shifting pattern on the pavement, and every open window seemed to hold a different morning.</p>
+<blockquote><p>A familiar street becomes new when you give it enough time.</p></blockquote>
+<p>By nine, the cafés had filled and the spell had softened. I wrote down three small details so I would remember: green tiles, the sound of a broom, and a paper boat turning under the bridge.</p>
+"""

package/assets/fixtures/kitchen-sink.toml

@@ -0,0 +1,36 @@
+title = "A Deliberately Long Headline for Testing How a Theme Handles Narrow Screens and Patient Readers"
+preferred_link = "https://example.org/guides/kitchen-sink"
+external_link = "https://example.org/guides/kitchen-sink"
+external_link_label = "Continue reading on Example Journal"
+external_link_stripped = "example.org"
+feed_link = "https://example.org/"
+feed_link_title = "Example Journal With a Long Publication Name"
+byline = "Alexandra Example and the Editorial Systems Working Group"
+date_long = "September 17, 2026"
+date_medium = "Sep 17, 2026"
+date_short = "9/17/26"
+datetime_long = "2026-09-17T08:30:00-07:00"
+datetime_medium = "Sep 17, 2026 at 8:30 AM"
+datetime_short = "9/17/26, 8:30 AM"
+time_long = "8:30:00 AM PDT"
+time_medium = "8:30:00 AM"
+time_short = "8:30 AM"
+avatar_src = ""
+body = """
+<p>This synthetic article checks <strong>strong text</strong>, <em>emphasis</em>, <del>deletions</del>, <mark>highlights</mark>, <a href="https://example.org/reference">ordinary links</a>, and inline <code>code()</code>.</p>
+<h2>Lists and quotations</h2>
+<ul><li>A short item</li><li>A nested list<ul><li>with another level</li></ul></li><li>An item containing aSuperLongUnbrokenIdentifierDesignedToRevealHorizontalOverflowProblemsImmediately</li></ul>
+<ol><li>Measure the readable column.</li><li>Check the rhythm.</li><li>Try large text.</li></ol>
+<blockquote><p>Good defaults should remain calm when the content is not.</p><footer>— A synthetic quotation</footer></blockquote>
+<h2>Code and tabular data</h2>
+<pre><code>def greet(reader: str) -&gt; str:
+    return f"Welcome, {reader}. This line is intentionally wider than a phone viewport."
+</code></pre>
+<table><thead><tr><th>Viewport</th><th>Purpose</th><th>Expected behavior</th></tr></thead><tbody><tr><td>macOS</td><td>Reading</td><td>Comfortable measure</td></tr><tr><td>iPhone</td><td>Small screen</td><td>No document overflow</td></tr><tr><td>iPad</td><td>Large text</td><td>Stable hierarchy</td></tr></tbody></table>
+<h2>Media and footnotes</h2>
+<figure><img alt="Abstract green and cream test pattern" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1200' height='675' viewBox='0 0 1200 675'%3E%3Crect width='1200' height='675' fill='%23d8d2c6'/%3E%3Ccircle cx='380' cy='337' r='240' fill='%232f6655'/%3E%3Cpath d='M0 560L1200 180V675H0Z' fill='%23f7f5f0'/%3E%3C/svg%3E"><figcaption>A synthetic image checks wide-media scaling.</figcaption></figure>
+<p>The note marker uses common generated markup.<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup></p>
+<div class="footnotes"><ol><li id="fn:1"><p>Footnote content should remain readable in place and in NetNewsWire’s popover. <a href="#fnref:1" class="reversefootnote">↩</a></p></li></ol></div>
+<h3>Final heading</h3>
+<p>End of the fixture.</p>
+"""

package/assets/footnotes.js

@@ -0,0 +1,174 @@
+// 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.
+//
+// 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} = {}) => {
+	const failures = [];
+	const fail = message => failures.push(message);
+	const article = document.querySelector(".articleBody");
+	if (!article) return failures;
+	const text = element => element.textContent.replace(/\s+/g, " ").trim();
+	const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+	// Markers the reader can see; a theme may hide the source's originals.
+	const markers = [...article.querySelectorAll("a.footnote")]
+		.filter(marker => marker.getClientRects().length);
+	const label = marker => text(marker) || marker.getAttribute("href");
+
+	// 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 target = id && document.getElementById(id);
+		if (!target) {
+			fail(`footnote ${label(marker)}: ${marker.getAttribute("href")} names no note`);
+			continue;
+		}
+		if (document.querySelectorAll(`[id="${CSS.escape(id)}"]`).length > 1) {
+			fail(`footnote ${label(marker)}: more than one element has id ${id}`);
+		}
+		const note = text(target);
+		if (note) noteFor.set(marker, note);
+		else fail(`footnote ${label(marker)}: note is empty`);
+	}
+
+	if (notes) {
+		const byLabel = new Map(markers.map(marker => [text(marker), marker]));
+		for (const [expected, note] of Object.entries(notes)) {
+			const marker = byLabel.get(expected);
+			if (!marker) fail(`footnote ${expected}: no marker with this text`);
+			else if (noteFor.has(marker) && noteFor.get(marker) !== note) {
+				fail(`footnote ${expected}: note reads ${JSON.stringify(noteFor.get(marker))}, ` +
+					`expected ${JSON.stringify(note)}`);
+			}
+		}
+		for (const found of byLabel.keys()) {
+			if (!Object.hasOwn(notes, found)) fail(`unexpected footnote marker ${JSON.stringify(found)}`);
+		}
+	}
+
+	for (const selector of plain_links) {
+		let links = [];
+		try {
+			links = [...document.querySelectorAll(selector)];
+		} catch {
+			fail(`plain link ${selector}: invalid selector`);
+			continue;
+		}
+		if (!links.length) fail(`plain link ${selector}: not found`);
+		if (links.some(link => link.matches(".footnote"))) {
+			fail(`plain link ${selector}: treated as a footnote`);
+		}
+	}
+
+	// The numeral must stand out from what it sits on. A marker's fill may be a
+	// tint, so flatten the backgrounds under it before comparing.
+	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);
+	for (const marker of markers) {
+		// The deepest element carrying the numeral is what actually gets painted.
+		const glyph = [...marker.querySelectorAll("*")].filter(e => text(e)).pop() || marker;
+		const color = rgba(getComputedStyle(glyph).color);
+		const ground = backdrop(marker);
+		if (distance(color, ground) <= 60) {
+			fail(`footnote ${label(marker)}: numeral ${color.slice(0, 3)} is illegible on ${ground}`);
+		}
+		const box = marker.getBoundingClientRect();
+		const inner = glyph.getBoundingClientRect();
+		if (inner.top < box.top - 1 || inner.bottom > box.bottom + 1) {
+			fail(`footnote ${label(marker)}: numeral spills out of its marker`);
+		}
+	}
+
+	// A marker written against its word, with no space between, stays on that
+	// word's line: a line that starts with a marker has lost what it annotates.
+	// Opt-in: core.css makes a.footnote inline-block, so a line may break before any
+	// marker, and only a theme script can hold the pair together.
+	for (const marker of keep_with_word ? markers : []) {
+		let box = marker;
+		while (box.parentElement && box.parentElement !== article &&
+			box.parentElement.childNodes.length === 1) box = box.parentElement;
+		// Empty elements, such as an anchor landmark for return links, don't count.
+		let before = box.previousSibling;
+		while (before && !before.textContent) before = before.previousSibling;
+		if (before?.nodeType !== Node.TEXT_NODE || !before.data || /\s$/.test(before.data)) continue;
+		const range = document.createRange();
+		range.setStart(before, before.data.length - 1);
+		range.setEnd(before, before.data.length);
+		if (marker.getBoundingClientRect().top >= range.getBoundingClientRect().bottom - 1) {
+			fail(`footnote ${label(marker)}: wraps onto a new line, apart from its word`);
+		}
+	}
+
+	// Every marker presents alike, whatever markup the source used. Seat is measured
+	// against a probe on the marker's own line, so it holds across lines. The probe
+	// is a zero-width word joiner: it always fits, so it never wraps to the next line
+	// or pushes an unbreakable group there, and the marker is measured beside it.
+	const geometry = markers.map(marker => {
+		const probe = document.createElement("span");
+		probe.textContent = "\u2060";
+		marker.after(probe);
+		const box = marker.getBoundingClientRect();
+		const seat = box.bottom - probe.getBoundingClientRect().bottom;
+		probe.remove();
+		return {marker, height: box.height, seat, size: parseFloat(getComputedStyle(marker).fontSize)};
+	});
+	const [first] = geometry;
+	for (const g of geometry.slice(1)) {
+		const name = `footnote ${label(g.marker)}`;
+		const reference = label(first.marker);
+		if (Math.abs(g.height - first.height) >= 0.5) {
+			fail(`${name}: ${g.height}px tall, footnote ${reference} is ${first.height}px`);
+		}
+		if (Math.abs(g.seat - first.seat) >= 0.5) {
+			fail(`${name}: sits ${g.seat}px from its baseline, footnote ${reference} ${first.seat}px`);
+		}
+		if (Math.abs(g.size - first.size) >= 0.1) {
+			fail(`${name}: font-size ${g.size}px, footnote ${reference} is ${first.size}px`);
+		}
+	}
+
+	// End to end: a click opens newsfoot's popover with the note, and moving the
+	// marker into newsfoot's container does not restyle it.
+	for (const marker of markers) {
+		const note = noteFor.get(marker);
+		if (note === undefined) continue;
+		const resting = marker.getBoundingClientRect();
+		marker.dispatchEvent(new MouseEvent("click", {bubbles: true, cancelable: true, view: window}));
+		await pause(60);
+		const opened = marker.getBoundingClientRect();
+		if (Math.abs(resting.width - opened.width) >= 0.5 ||
+			Math.abs(resting.height - opened.height) >= 0.5) {
+			fail(`footnote ${label(marker)}: ${resting.width}x${resting.height} marker became ` +
+				`${opened.width}x${opened.height} when opened`);
+		}
+		const popover = document.querySelector(".newsfoot-footnote-popover");
+		const shown = popover ? text(popover) : null;
+		if (shown !== note) fail(`footnote ${label(marker)}: popover showed ${JSON.stringify(shown)}`);
+		document.body.dispatchEvent(new MouseEvent("click", {bubbles: true, cancelable: true, view: window}));
+		await pause(30);
+	}
+	return failures;
+}

package/assets/guide/design-checklist.md

@@ -0,0 +1,19 @@
+# Visual review checklist
+
+Use this after the design direction is established; it is an inspection guide, not a
+prescribed aesthetic.
+
+- Read the pleasant article at ordinary size before judging edge cases.
+- Check hierarchy, measure, paragraph rhythm, link recognition, and muted-text
+  contrast in both light and dark appearance.
+- Check long title/byline wrapping on macOS, iPhone, and iPad.
+- Check lists, quotations, inline code, preformatted code, tables, captions, media,
+  and footnotes in the kitchen-sink article and any fixtures the theme added. `check`
+  verifies footnote popovers and marker consistency; judge how they look.
+- Confirm wide media and long tokens do not create document-level horizontal scroll.
+- 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.
+- 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

@@ -0,0 +1,42 @@
+# Fixtures
+
+Read this when adding, capturing, or changing the articles previews render.
+
+Each `fixtures/*.toml` is one article: keys are the template macros, and any omitted
+key renders empty. `article` and `kitchen-sink` are built into `nnw-theme` and get the
+full matrix plus the large-text and Article-JavaScript-off cases; a repository's own
+`fixtures/article.toml` or `fixtures/kitchen-sink.toml` replaces the built-in one. Every other fixture is
+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.
+
+Prefer real articles for content a theme must handle. `npx nnw-theme@1 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
+same-size placeholder and a network feed icon for a generated one; do not inline or
+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
+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:
+
+```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
+
+[expect.footnotes.notes]
+"1" = "First note."                    # marker text as rendered = note text
+```
+
+With `notes`, every listed marker must exist and any other marker fails. With
+`keep_with_word`, a marker written against its word, with no space, must not wrap
+onto a new line apart from it. NetNewsWire's `core.css` makes `a.footnote`
+`inline-block`, which allows that break, and CSS alone cannot remove it: a theme
+script must hold the pair together, for example in a `white-space: nowrap` span.
+Expectations describe the theme's own scripts, so they are skipped with Article
+JavaScript off.

package/assets/guide/publishing.md

@@ -0,0 +1,34 @@
+# Publishing and marketplace listing
+
+Read this before versioning, promoting the marketplace screenshot, changing GitHub
+metadata, or releasing.
+
+Run `npx nnw-theme@1 bump`, commit the new integer `Version`, and run
+`npx nnw-theme@1 check`. The bundle filename and `ThemeIdentifier` cannot change
+after the first release. Release tags may use any valid Git ref beginning with `v`;
+semantic tags such as `v1.0.0` are the suggested default and are independent of the
+plist version.
+
+Publishing is manual: use **Actions → Publish theme → Run workflow** or an equivalent
+explicitly authorized GitHub CLI action. Tag pushes do not publish. The workflow uses
+the current default-branch HEAD, refuses an existing tag/release, compares identity
+and version to the previous stable release, and uploads one
+`<Name>.nnwtheme.zip` asset. Notes are optional; when they are empty and
+`.github/cliff.toml` exists, git-cliff generates them from the commits since the
+previous tag.
+
+Marketplace participation is optional. Automatic discovery expects a public,
+non-archived, non-fork repository; the `netnewswire-theme` or `netnewswire` topic; a
+stable GitHub release; and the valid ZIP asset. A useful repository description and
+`screenshots/theme-preview.png` improve the card. Missing optional marketplace/card
+metadata warns but does not block publication. `npx nnw-theme@1 marketplace enable`
+adds the recommended topic through the author’s authenticated `gh` session.
+
+The screenshot workflow pushes a branch and opens a pull request for review, so the
+repository needs **Settings → Actions → General → Workflow permissions → Allow GitHub
+Actions to create and approve pull requests**. Without it the run pushes the branch and
+then fails with "GitHub Actions is not permitted to create or approve pull requests".
+
+Creating releases, topics, branches, pull requests, or other GitHub state is external
+mutation. Confirm the person’s intent immediately before doing it. Ordinary edits,
+local previews, checks, and packages do not need that additional confirmation.