nnw-theme 1.1.0 → 2.0.1

package/README.md

@@ -16,15 +16,15 @@ Not affiliated with or endorsed by Ranchero Software or the NetNewsWire project.
 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 reloads on save
-npx nnw-theme@1 check      # the release gate: package, render, and test every case
+npx nnw-theme@2 init       # once: name the theme and choose its permanent identifier
+npx nnw-theme@2 setup      # once per machine: install the WebKit build checks use
+npx nnw-theme@2 preview    # live gallery that reloads on save
+npx nnw-theme@2 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
+`@2` picks the newest 2.x release, so fixes arrive on their own and a breaking 3.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`.
+version, name it: `npx nnw-theme@2.0.0 check`.
 
 | Command | What it does |
 | --- | --- |
@@ -46,16 +46,16 @@ 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
+also defines an `nnw-theme` command that runs `npx --yes nnw-theme@2`, 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
+npx nnw-theme@2 completion fish > ~/.config/fish/conf.d/nnw-theme.fish
 # zsh (~/.zshrc, after compinit)
-source <(npx --yes nnw-theme@1 completion zsh)
+source <(npx --yes nnw-theme@2 completion zsh)
 # bash (~/.bashrc)
-source <(npx --yes nnw-theme@1 completion bash)
+source <(npx --yes nnw-theme@2 completion bash)
 ```
 
 Fish loads a file rather than running npx at every shell start. Zsh and bash users can
@@ -64,11 +64,21 @@ Regenerate it when commands change.
 
 ## GitHub workflows
 
-Theme repositories call this repository's reusable workflows, pinned to `@v1`:
+Theme repositories call this repository's reusable workflows, pinned to `@v2`:
 `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.
 
+## Upgrading from 1.x
+
+2.0 fails `check` when `template.html` writes a macro in double brackets inside an HTML
+comment. NetNewsWire substitutes it there too, so an article containing `-->` ends the
+comment early and the rest shows as text; the 1.x starter template did this. Write the
+names without brackets. Then replace the stub files `check` warns about (`AGENTS.md`,
+the agent skill, and the four workflow callers) with the template's current copies,
+which run `npx nnw-theme@2` and call the workflows at `@v2`. 1.x and `@v1` keep working
+unchanged.
+
 ## Developing
 
 See [AGENTS.md](AGENTS.md). Report problems at

package/assets/fixtures/kitchen-sink.toml

@@ -31,6 +31,7 @@ body = """
 <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>
+<!-- SC_OFF --><div class="md"><p>A comment-wrapped paragraph, as Reddit sends every post.</p></div><!-- SC_ON -->
 <h3>Final heading</h3>
 <p>End of the fixture.</p>
 """

package/assets/guide/fixtures.md

@@ -10,7 +10,7 @@ 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`
+Prefer real articles for content a theme must handle. `npx nnw-theme@2 capture`
 prints the steps for saving the selected article from a NetNewsWire debug build with
 the `nnwdump` lldb command; it needs Xcode and a NetNewsWire clone, so the person
 usually runs it. Rendering swaps every image that would load over the network for a

package/assets/guide/publishing.md

@@ -3,8 +3,8 @@
 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
+Run `npx nnw-theme@2 bump`, commit the new integer `Version`, and run
+`npx nnw-theme@2 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.
@@ -21,7 +21,7 @@ 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`
+metadata warns but does not block publication. `npx nnw-theme@2 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

package/assets/guide/skill.md

@@ -1,8 +1,8 @@
 # Create NetNewsWire themes
 
 This guide is for people and agents building a theme with `nnw-theme`. Run the tool
-as `npx nnw-theme@1 <command>`; never install it globally or add it to the theme
-repository. Read another topic with `npx nnw-theme@1 guide <topic>`: `theme-format`,
+as `npx nnw-theme@2 <command>`; never install it globally or add it to the theme
+repository. Read another topic with `npx nnw-theme@2 guide <topic>`: `theme-format`,
 `fixtures`, `design-checklist`, or `publishing`.
 
 The upstream `dave-atx/netnewswire-theme-template` repository is a GitHub template.
@@ -11,7 +11,7 @@ upstream template or a fork. If they already have their own copy open, use it.
 Otherwise, help them create one from the template if you can, or ask them to create
 and open it; confirm before creating a GitHub repository. Then work on its single
 root-level `*.nnwtheme` bundle. If `.nnw-theme-uninitialized` exists, run the guided
-`npx nnw-theme@1 init` before design work; let the person approve the permanent
+`npx nnw-theme@2 init` before design work; let the person approve the permanent
 identifier even when other identity details are already known.
 
 Collect or infer a compact design brief: mood, typography, color direction, and any
@@ -24,18 +24,18 @@ footnotes, add a fixture as the `fixtures` topic describes.
 Iterate with this loop:
 
 1. Make a focused theme edit.
-2. Run `npx nnw-theme@1 render` for fast generated pages or
-   `npx nnw-theme@1 screenshot` when a checked image is needed.
+2. Run `npx nnw-theme@2 render` for fast generated pages or
+   `npx nnw-theme@2 screenshot` when a checked image is needed.
 3. Inspect relevant light/dark and device previews under `build/preview/`.
 4. Explain what changed in visual terms and incorporate the person’s reaction.
 
 Use the `design-checklist` topic during final visual review. Always finish
-implementation with `npx nnw-theme@1 check`; do not substitute a Chromium result for
+implementation with `npx nnw-theme@2 check`; do not substitute a Chromium result for
 the required WebKit gate. Give the person a concrete preview or screenshot path they
-can open. If `check` reports that WebKit is missing, run `npx nnw-theme@1 setup`.
+can open. If `check` reports that WebKit is missing, run `npx nnw-theme@2 setup`.
 
 Treat the root bundle filename and `ThemeIdentifier` as permanent after the first
-release. Increase the integer `Version` with `npx nnw-theme@1 bump` for each release.
+release. Increase the integer `Version` with `npx nnw-theme@2 bump` for each release.
 Read the `publishing` topic for publishing work. Local packaging is not publication.
 Obtain clear user confirmation immediately before triggering a GitHub release or
 another external mutation.

package/assets/guide/theme-format.md

@@ -34,7 +34,8 @@ the size classes are inert on iOS, where the app never sets one. Do not reach fo
 uses it: no desktop WebKit implements that property, so every preview resolves the iOS
 branch as false and platform-conditional CSS is checked the wrong way round. Do not
 write macro names in double brackets inside comments either, because substitution
-rewrites those too. NetNewsWire's stylesheet also sets `font: -apple-system-body` at
+rewrites those too: a body containing `-->`, as every Reddit post does, closes the
+comment early and shows the rest of it as text. `check` fails on them. NetNewsWire's stylesheet also sets `font: -apple-system-body` at
 `:root`; a theme with its own typography should not, because that shorthand resets
 `font-family` and `line-height`.
 

package/assets/stubs/.agents/skills/creating-nnw-themes/SKILL.md

@@ -2,21 +2,21 @@
 name: creating-nnw-themes
 description: Create, restyle, preview, test, package, or publish the NetNewsWire theme in this repository. Do not use for generic web design or NetNewsWire app development.
 ---
-<!-- nnw-theme-stub: skill v1 -->
+<!-- nnw-theme-stub: skill v2 -->
 
 # Create NetNewsWire themes
 
-Read the full guide first: `npx nnw-theme@1 guide`. Details live in its topics
-(`npx nnw-theme@1 guide theme-format`, `fixtures`, `design-checklist`, `publishing`),
+Read the full guide first: `npx nnw-theme@2 guide`. Details live in its topics
+(`npx nnw-theme@2 guide theme-format`, `fixtures`, `design-checklist`, `publishing`),
 which update with the tool.
 
-1. If `.nnw-theme-uninitialized` exists, run `npx nnw-theme@1 init` and let the person
+1. If `.nnw-theme-uninitialized` exists, run `npx nnw-theme@2 init` and let the person
    approve the permanent theme identifier.
 2. Collect a compact design brief: mood, typography, color, reading needs.
 3. Edit `stylesheet.css` first; change `template.html` only when structure requires it.
-4. Run `npx nnw-theme@1 render` and inspect `build/preview/` in light and dark on each
+4. Run `npx nnw-theme@2 render` and inspect `build/preview/` in light and dark on each
    device; explain the change and take the person's reaction.
-5. Finish with `npx nnw-theme@1 check` and give the person the preview path.
+5. Finish with `npx nnw-theme@2 check` and give the person the preview path.
 
 Never change the bundle name or `ThemeIdentifier` after the first release. Confirm
 with the person immediately before any release or other GitHub mutation.

package/assets/stubs/.github/workflows/check.yml

@@ -1,4 +1,4 @@
-# nnw-theme-stub: check v1
+# nnw-theme-stub: check v2
 # Runs the nnw-theme release gate: https://github.com/dave-atx/nnw-theme
 name: Theme checks
 
@@ -11,4 +11,4 @@ permissions:
 
 jobs:
   check:
-    uses: dave-atx/nnw-theme/.github/workflows/theme-check.yml@v1
+    uses: dave-atx/nnw-theme/.github/workflows/theme-check.yml@v2

package/assets/stubs/.github/workflows/pages.yml

@@ -1,4 +1,4 @@
-# nnw-theme-stub: pages v1
+# nnw-theme-stub: pages v2
 # Publishes the checked preview gallery when Pages builds from GitHub Actions.
 name: Publish preview pages
 
@@ -21,4 +21,4 @@ concurrency:
 
 jobs:
   pages:
-    uses: dave-atx/nnw-theme/.github/workflows/theme-pages.yml@v1
+    uses: dave-atx/nnw-theme/.github/workflows/theme-pages.yml@v2

package/assets/stubs/.github/workflows/release.yml

@@ -1,4 +1,4 @@
-# nnw-theme-stub: release v1
+# nnw-theme-stub: release v2
 name: Publish theme
 
 on:
@@ -18,7 +18,7 @@ permissions:
 
 jobs:
   release:
-    uses: dave-atx/nnw-theme/.github/workflows/theme-release.yml@v1
+    uses: dave-atx/nnw-theme/.github/workflows/theme-release.yml@v2
     with:
       tag: ${{ inputs.tag }}
       notes: ${{ inputs.notes }}

package/assets/stubs/.github/workflows/screenshot.yml

@@ -1,4 +1,4 @@
-# nnw-theme-stub: screenshot v1
+# nnw-theme-stub: screenshot v2
 name: Refresh marketplace screenshot
 
 on:
@@ -21,7 +21,7 @@ permissions:
 
 jobs:
   screenshot:
-    uses: dave-atx/nnw-theme/.github/workflows/theme-screenshot.yml@v1
+    uses: dave-atx/nnw-theme/.github/workflows/theme-screenshot.yml@v2
     with:
       fixture: ${{ inputs.fixture }}
       appearance: ${{ inputs.appearance }}

package/assets/stubs/AGENTS.md

@@ -1,10 +1,10 @@
-<!-- nnw-theme-stub: agents v1 -->
+<!-- nnw-theme-stub: agents v2 -->
 # Repository guidance
 
 This repository is one NetNewsWire theme: the single root `*.nnwtheme` bundle,
 its `fixtures/`, and `screenshots/`. The tooling is the `nnw-theme` npm package;
-run it as `npx nnw-theme@1 <command>`. Never install it globally and never add
-it to this repository. Read `npx nnw-theme@1 guide` before theme work.
+run it as `npx nnw-theme@2 <command>`. Never install it globally and never add
+it to this repository. Read `npx nnw-theme@2 guide` before theme work.
 
 If this repository is `dave-atx/netnewswire-theme-template` itself (check
 `git remote -v`), it is the GitHub template, not a theme: do not initialize,
@@ -13,13 +13,13 @@ fork, or design in it. Help the user create their own repository from it with
 dave-atx/netnewswire-theme-template --clone`, confirming before you create it,
 then work in that copy.
 
-If `.nnw-theme-uninitialized` exists, run `npx nnw-theme@1 init` first and let
+If `.nnw-theme-uninitialized` exists, run `npx nnw-theme@2 init` first and let
 the user confirm the permanent theme identifier. Prefer CSS changes; change
 `template.html` only when the requested structure or behavior requires it.
-Finish theme work with `npx nnw-theme@1 check` and report the preview path.
+Finish theme work with `npx nnw-theme@2 check` and report the preview path.
 
 Do not change `ThemeIdentifier` or the `.nnwtheme` bundle name after the first
-release. Increase the plist `Version` (`npx nnw-theme@1 bump`) before every
+release. Increase the plist `Version` (`npx nnw-theme@2 bump`) before every
 release.
 
 If the tooling misbehaves, do not work around it here: report it at

package/dist/browser.js

@@ -11,7 +11,7 @@ import { packagePath, ThemeError } from "./project.js";
 import { pyReprList } from "./pyformat.js";
 const FOOTNOTE_CHECK = readFileSync(packagePath("assets", "footnotes.js"), "utf8");
 const LIVE_RELOAD = readFileSync(packagePath("assets", "live-reload.js"), "utf8");
-const NOT_INSTALLED = "WebKit is not installed; run `npx nnw-theme@1 setup`";
+const NOT_INSTALLED = "WebKit is not installed; run `npx nnw-theme@2 setup`";
 const CONTENT_TYPES = {
     ".html": "text/html; charset=utf-8",
     ".png": "image/png",
@@ -154,6 +154,8 @@ export function failures(state) {
         found.push(`broken images: ${pyReprList(state.brokenImages)}`);
     if (state.collapsedImages.length)
         found.push(`images drawn at zero size: ${pyReprList(state.collapsedImages)}`);
+    if (state.unloadedImages.length)
+        found.push(`images still loading: ${pyReprList(state.unloadedImages)}`);
     found.push(...(state.footnotes ?? []));
     if (state.blocked.length)
         found.push(`external requests: ${pyReprList(state.blocked)}`);
@@ -161,6 +163,21 @@ export function failures(state) {
         found.push(`page errors: ${pyReprList(state.pageErrors)}`);
     return found;
 }
+// Runs in the page before its screenshot. A loading="lazy" image outside the viewport
+// never starts loading in a full-page screenshot, so it would draw as blank space and
+// escape the image checks; NetNewsWire loads it as the reader scrolls, so load every
+// image now and wait (up to timeout ms) for each to finish or fail.
+async function loadImages(timeout) {
+    const images = [...document.images];
+    for (const image of images)
+        if (image.loading === "lazy")
+            image.loading = "eager";
+    const settled = images.map((image) => image.decode().catch(() => { }));
+    await Promise.race([
+        Promise.all(settled),
+        new Promise((resolve) => setTimeout(resolve, timeout)),
+    ]);
+}
 // Runs in the page after its screenshot.
 function pageState() {
     const article = document.querySelector(".articleBody");
@@ -194,6 +211,10 @@ function pageState() {
             return box.width < 1 || box.height < 1;
         })
             .map((image) => image.currentSrc || image.src),
+        // Still loading after loadImages: neither drawn nor covered by the checks above.
+        unloadedImages: [...document.images]
+            .filter((image) => !image.complete)
+            .map((image) => image.currentSrc || image.src),
     };
 }
 /**
@@ -260,6 +281,7 @@ async function checkPage(browser, origin, url, target, screenshot, footnotes) {
         const page = await context.newPage();
         page.on("pageerror", (error) => pageErrors.push(String(error)));
         await page.goto(url, { waitUntil: "networkidle" });
+        await page.evaluate(loadImages, 10_000);
         await page.screenshot({ path: screenshot, fullPage: true });
         const state = await page.evaluate(pageState);
         // Last: it clicks footnotes open, so it must not disturb the screenshot.

package/dist/commands/capture.js

@@ -18,7 +18,7 @@ export default function capture() {
    nnwdump ${output}
    continue
 
-4. Preview it with \`npx nnw-theme@1 render my-article\`.
+4. Preview it with \`npx nnw-theme@2 render my-article\`.
 
 nnwdump embeds the feed's real icon; pass --no-icon to keep the generated one.
 The debugger's working directory is /, so give nnwdump an absolute path.

package/dist/commands/init.js

@@ -75,7 +75,7 @@ function templateRoot() {
             "clone it, and run init inside it. With the GitHub CLI:\n" +
             `  gh repo create my-theme --template ${TEMPLATE} --public --clone\n` +
             "  cd my-theme\n" +
-            "  npx nnw-theme@1 init");
+            "  npx nnw-theme@2 init");
     }
 }
 async function ask(value, flag, label, fallback) {
@@ -89,7 +89,7 @@ export default async function init({ values }) {
     const root = templateRoot();
     let theme = findTheme(root);
     if (!existsSync(join(root, PLACEHOLDER_MARKER))) {
-        throw new ThemeError("this repository is already initialized; run `npx nnw-theme@1 setup` to install preview tools");
+        throw new ThemeError("this repository is already initialized; run `npx nnw-theme@2 setup` to install preview tools");
     }
     const flag = (name) => values[name];
     const prompting = !(flag("name") && flag("creator") && flag("homepage"));
@@ -143,7 +143,7 @@ export default async function init({ values }) {
     rmSync(join(root, "screenshots", "theme-preview.png"), { force: true });
     rmSync(join(root, PLACEHOLDER_MARKER));
     console.log(`Initialized ${name}.nnwtheme with identifier ${identifier}.`);
-    console.log("Create a deliberate marketplace image with `npx nnw-theme@1 screenshot --promote`.");
+    console.log("Create a deliberate marketplace image with `npx nnw-theme@2 screenshot --promote`.");
     let marketplace = flag("marketplace");
     if (marketplace === undefined) {
         marketplace =
@@ -165,8 +165,8 @@ export default async function init({ values }) {
         }
         catch (error) {
             console.error(`Warning: initialization succeeded, but preview setup did not: ${error.message}\n` +
-                "Finish preview setup later with `npx nnw-theme@1 setup`.");
+                "Finish preview setup later with `npx nnw-theme@2 setup`.");
         }
     }
-    console.log(`Next: work on your design in ${relative(process.cwd(), theme) || "."}, then run \`npx nnw-theme@1 preview\`.`);
+    console.log(`Next: work on your design in ${relative(process.cwd(), theme) || "."}, then run \`npx nnw-theme@2 preview\`.`);
 }

package/dist/commands/marketplace.js

@@ -5,13 +5,13 @@ export function marketplaceEnable() {
         encoding: "utf8",
     });
     if (result.error) {
-        console.error("Warning: GitHub CLI is not installed. Run `npx nnw-theme@1 marketplace enable` " +
+        console.error("Warning: GitHub CLI is not installed. Run `npx nnw-theme@2 marketplace enable` " +
             "after installing and authenticating gh.");
         return false;
     }
     if (result.status) {
         console.error("Warning: could not add the marketplace topic. " +
-            `Run \`npx nnw-theme@1 marketplace enable\` later.\n${(result.stderr || result.stdout).trim()}`);
+            `Run \`npx nnw-theme@2 marketplace enable\` later.\n${(result.stderr || result.stdout).trim()}`);
         return false;
     }
     console.log("Added the netnewswire-theme GitHub topic.");

package/dist/commands/update.js

@@ -1,6 +1,6 @@
 import { ThemeError } from "../project.js";
 export default function update() {
-    throw new ThemeError("update was removed: the tooling now runs from npm with `npx nnw-theme@1`, so " +
+    throw new ThemeError("update was removed: the tooling now runs from npm with `npx nnw-theme@2`, so " +
         "fixes arrive without changing this repository. Delete src/, tests/, " +
         "pyproject.toml, uv.lock, and .python-version, and replace the stubs `check` " +
         "warns about.");

package/dist/commands.js

@@ -145,7 +145,7 @@ export const COMMANDS = [
     {
         name: "completion",
         summary: "print shell completion and an npx wrapper for fish, zsh, or bash",
-        description: "Print a script that defines an nnw-theme command running `npx --yes nnw-theme@1` " +
+        description: "Print a script that defines an nnw-theme command running `npx --yes nnw-theme@2` " +
             "(skipped when nnw-theme is already installed) and completes its commands, " +
             "options, and fixture names.",
         options: [],

package/dist/completion.js

@@ -1,9 +1,9 @@
 // Shell completion scripts, generated from the same command spec the parser uses.
-// Each script also defines an nnw-theme function that runs `npx --yes nnw-theme@1`
+// Each script also defines an nnw-theme function that runs `npx --yes nnw-theme@2`
 // unless a real nnw-theme is already on PATH. The scripts never call npx to complete,
 // so completion is instant.
 import { BUILT_IN_FIXTURE_NAMES, COMMANDS, PROGRAM, } from "./commands.js";
-const RUN = "npx --yes nnw-theme@1";
+const RUN = "npx --yes nnw-theme@2";
 const visible = () => COMMANDS.filter((command) => !command.hidden);
 function flags(option) {
     return option.negatable ? [`--${option.name}`, `--no-${option.name}`] : [`--${option.name}`];
@@ -26,7 +26,7 @@ function fishQuote(text) {
 }
 export function fish() {
     const lines = [
-        "# nnw-theme completion for fish. Install: npx nnw-theme@1 completion fish > ~/.config/fish/conf.d/nnw-theme.fish",
+        "# nnw-theme completion for fish. Install: npx nnw-theme@2 completion fish > ~/.config/fish/conf.d/nnw-theme.fish",
         `if not command -q ${PROGRAM}`,
         `    function ${PROGRAM} --description 'Run nnw-theme through npx'`,
         `        ${RUN} $argv`,
@@ -101,7 +101,7 @@ export function bash() {
             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", "      ;;");
     }
-    return `# nnw-theme completion for bash. Install: source <(npx --yes nnw-theme@1 completion bash)
+    return `# nnw-theme completion for bash. Install: source <(npx --yes nnw-theme@2 completion bash)
 if ! type -P ${PROGRAM} >/dev/null 2>&1; then
   ${PROGRAM}() { ${RUN} "$@"; }
 fi
@@ -163,7 +163,7 @@ export function zsh() {
             specs.push(`'1:${command.positionals?.name ?? "command"}:(${words.join(" ")})'`);
         cases.push(`    ${command.name}) _arguments -s ${specs.join(" ")} ;;`);
     }
-    return `# nnw-theme completion for zsh. Install: source <(npx --yes nnw-theme@1 completion zsh)
+    return `# nnw-theme completion for zsh. Install: source <(npx --yes nnw-theme@2 completion zsh)
 if (( ! $+commands[${PROGRAM}] )); then
   ${PROGRAM}() { ${RUN} "$@"; }
 fi

package/dist/main.js

@@ -78,7 +78,7 @@ export function mainHelp() {
         ]),
         "",
         `Run \`${PROGRAM} COMMAND --help\` for a command's options.`,
-        `Run it through npx: \`npx nnw-theme@1 COMMAND\`.`,
+        `Run it through npx: \`npx nnw-theme@2 COMMAND\`.`,
         "",
     ].join("\n");
 }

package/dist/render.js

@@ -81,7 +81,7 @@ const SCENARIOS = [
         "Stress test",
         "The kitchen-sink fixture: a very long headline, byline, and feed name; inline " +
             "formatting; nested lists; an unbroken identifier that exposes horizontal " +
-            "overflow; a quotation, code block, table, figure, and footnote.",
+            "overflow; a quotation, code block, table, figure, footnote, and HTML comments in the body.",
     ],
     [
         "large-text",
@@ -437,7 +437,7 @@ export function writeGallery(site, themeName, targets, results = null) {
     if (results === null) {
         summary =
             `<p class=summary>${targets.length} cases, not checked yet. Run ` +
-                "<code>npx nnw-theme@1 check</code> to verify them in WebKit.</p>";
+                "<code>npx nnw-theme@2 check</code> to verify them in WebKit.</p>";
     }
     else {
         const failed = targets.filter((target) => results[target.slug]?.length);

package/dist/stubs.js

@@ -4,12 +4,12 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 export const TEMPLATE_BLOB = "https://github.com/dave-atx/netnewswire-theme-template/blob/main";
 export const STUBS = [
-    { path: "AGENTS.md", name: "agents", version: 1 },
-    { path: ".agents/skills/creating-nnw-themes/SKILL.md", name: "skill", version: 1 },
-    { path: ".github/workflows/check.yml", name: "check", version: 1 },
-    { path: ".github/workflows/pages.yml", name: "pages", version: 1 },
-    { path: ".github/workflows/release.yml", name: "release", version: 1 },
-    { path: ".github/workflows/screenshot.yml", name: "screenshot", version: 1 },
+    { path: "AGENTS.md", name: "agents", version: 2 },
+    { path: ".agents/skills/creating-nnw-themes/SKILL.md", name: "skill", version: 2 },
+    { path: ".github/workflows/check.yml", name: "check", version: 2 },
+    { path: ".github/workflows/pages.yml", name: "pages", version: 2 },
+    { path: ".github/workflows/release.yml", name: "release", version: 2 },
+    { path: ".github/workflows/screenshot.yml", name: "screenshot", version: 2 },
 ];
 const MARKER = /nnw-theme-stub:\s*([a-z-]+)\s+v(\d+)/;
 /** The marker in a stub file: its first line, or the first after YAML front matter. */

package/dist/validate.js

@@ -20,6 +20,7 @@ const SAFE_BUNDLE_NAME = /^[^/\\\0]+$/;
 const OPTIONAL_THEME_FILE = /^(?:LICENSE|NOTICE)(?:\.[A-Za-z0-9-]+)?$/;
 const S_IFMT = 0o170000;
 const S_IFLNK = 0o120000;
+const MACRO = /\[\[[A-Za-z0-9_-]+\]\]/g;
 export class ValidationReport {
     errors = [];
     warnings = [];
@@ -52,6 +53,15 @@ function resourceReferences(template) {
     parser.end(template);
     return references;
 }
+/** Macros written inside HTML comments, which NetNewsWire substitutes like any other. */
+function commentedMacros(template) {
+    const found = new Set();
+    for (const comment of template.matchAll(/<!--[\s\S]*?-->/g)) {
+        for (const macro of comment[0].matchAll(MACRO))
+            found.add(macro[0]);
+    }
+    return [...found];
+}
 function isRemote(value) {
     return value.startsWith("//") || ["http", "https"].includes(urlsplit(value).scheme);
 }
@@ -113,7 +123,7 @@ export function validateSource(theme, { allowRemoteMedia = false } = {}) {
         report.errors.push("theme bundle name contains path-unsafe characters");
     }
     if (existsSync(join(dirname(theme), PLACEHOLDER_MARKER))) {
-        report.errors.push("run `npx nnw-theme@1 init` before packaging this theme");
+        report.errors.push("run `npx nnw-theme@2 init` before packaging this theme");
     }
     const names = readdirSync(theme);
     for (const required of REQUIRED_THEME_FILES) {
@@ -144,6 +154,14 @@ export function validateSource(theme, { allowRemoteMedia = false } = {}) {
         if (!template.includes("[[")) {
             report.warnings.push("template.html contains no NetNewsWire macros");
         }
+        const commented = commentedMacros(template);
+        if (commented.length) {
+            report.errors.push(`template.html has macros inside an HTML comment (${commented[0]}` +
+                `${commented.length > 1 ? ` and ${commented.length - 1} more` : ""}). ` +
+                "NetNewsWire substitutes them there too, so an article containing --> " +
+                "ends the comment early and the rest shows as text; " +
+                "write macro names without double brackets");
+        }
         const references = resourceReferences(template);
         if (/<style\b[^>]*>[\s\S]*?@import\s/i.test(template)) {
             report.errors.push("CSS @import is not allowed in template.html");

package/lldb/nnwdump.py

@@ -2,7 +2,7 @@
 
 Stopped at the final `return d` of ArticleRenderer.articleSubstitutions(), this
 reads the substitution dictionary NetNewsWire built for the selected article and
-writes it as a TOML fixture. `npx nnw-theme@1 capture` prints the setup steps.
+writes it as a TOML fixture. `npx nnw-theme@2 capture` prints the setup steps.
 
 Values cross the debugger boundary base64-encoded, so nothing is truncated or
 mis-escaped. HTML values are written as '''literal''' strings, so fixtures stay
@@ -30,7 +30,7 @@ def resolve_output(argument: str) -> Path:
     """Relative paths resolve against the working directory.
 
     This file ships in the nnw-theme package, not the theme repository, and lldb's
-    working directory under Xcode is /, so `npx nnw-theme@1 capture` prints an absolute
+    working directory under Xcode is /, so `npx nnw-theme@2 capture` prints an absolute
     output path to pass instead.
     """
     path = Path(argument).expanduser()
@@ -60,7 +60,7 @@ def fixture_text(pairs: list[tuple[str, str]], name: str) -> str:
     ordered = sorted(pairs, key=lambda pair: (pair[0] in _HTML_KEYS, pair[0]))
     header = (
         "# NetNewsWire article captured with nnwdump.\n"
-        f"# Preview with: npx nnw-theme@1 render {name}\n\n"
+        f"# Preview with: npx nnw-theme@2 render {name}\n\n"
     )
     return header + "\n".join(toml_line(key, value) for key, value in ordered) + "\n"
 

package/package.json

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