nnw-theme 2.1.0 → 2.2.0

package/README.md

@@ -33,7 +33,7 @@ version, name it: `npx nnw-theme@2.0.0 check`.
 | `preview` | Serve the gallery on localhost, open it, and rebuild and reload it on save |
 | `render [fixtures…]` | Write the gallery to `build/preview/` once |
 | `check` | Validate and package, then render and test every case in WebKit |
-| `screenshot` | Check one case and save its image; `--promote` makes it the marketplace card |
+| `screenshot` | Check one case (any fixture and platform) and save its image; `--card` crops to the marketplace card, `--promote` makes it the card |
 | `package` | Validate and build `dist/<Name>.nnwtheme.zip` |
 | `fixture list` / `fixture add <name>…` | Add ready-made fixtures modeled on WordPress, Ghost, Substack, and Medium markup |
 | `capture` | Explain how to capture a real article from NetNewsWire as a fixture |

package/assets/guide/fixtures.md

@@ -42,6 +42,12 @@ usually runs it. Rendering swaps every image that would load over the network fo
 same-size placeholder and a network feed icon for a generated one; do not inline or
 fetch the originals.
 
+To show a real image, as a marketplace screenshot needs, commit it under
+`fixtures/media/` and reference it by that relative path:
+`<img src="media/sunset.jpg" width="1600" height="900">`. Rendering inlines it, so
+previews stay offline; a missing file shows as a placeholder. Use only images the theme may redistribute, and keep them small:
+each is copied into every page that renders the fixture.
+
 Footnote markers are the links NetNewsWire's `newsfoot.js` handles: `a.footnote`.
 Its `main.js` adds that class to local `sup > a[href*='#fn']` links and to Substack's
 `a[id^='footnote-anchor-']` links; a theme script may add it to other formats. `check` requires every visible marker to resolve to a

package/assets/guide/publishing.md

@@ -24,6 +24,12 @@ stable GitHub release; and the valid ZIP asset. A useful repository description
 metadata warns but does not block publication. `npx nnw-theme@2 marketplace enable`
 adds the recommended topic through the author’s authenticated `gh` session.
 
+`npx nnw-theme@2 screenshot --fixture NAME --card --promote` makes the card image from
+any fixture: an 800×552 viewport at 2x, the shape of the card, which crops from the top. A
+fixture written for the card, with images in `fixtures/media/`, shows the theme best;
+`--platform ipad` or `iphone` renders it on another platform. The **Refresh marketplace
+screenshot** workflow takes the same fixture name and card choice.
+
 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

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

@@ -5,15 +5,18 @@ on:
   workflow_dispatch:
     inputs:
       fixture:
-        description: Fixture to capture
-        type: choice
-        options: [article, kitchen-sink]
+        description: Fixture to capture (article, kitchen-sink, or a fixtures/*.toml name)
+        type: string
         default: article
       appearance:
         description: Appearance to capture
         type: choice
         options: [light, dark]
         default: light
+      card:
+        description: Capture the marketplace card's shape instead of the full page
+        type: boolean
+        default: true
 
 permissions:
   contents: write
@@ -25,3 +28,4 @@ jobs:
     with:
       fixture: ${{ inputs.fixture }}
       appearance: ${{ inputs.appearance }}
+      card: ${{ inputs.card }}

package/dist/browser.js

@@ -255,6 +255,7 @@ export async function checkPages(site, targets, progress, expectations = {}) {
 async function checkPage(browser, origin, url, target, screenshot, footnotes) {
     const context = await browser.newContext({
         viewport: { width: target.width, height: target.height },
+        deviceScaleFactor: target.card ? 2 : 1,
         colorScheme: target.appearance,
         serviceWorkers: "block",
     });
@@ -282,7 +283,7 @@ async function checkPage(browser, origin, url, target, screenshot, footnotes) {
         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 });
+        await page.screenshot({ path: screenshot, fullPage: !target.card });
         const state = await page.evaluate(pageState);
         // Last: it clicks footnotes open, so it must not disturb the screenshot.
         const found = (await page.evaluate(`(${FOOTNOTE_CHECK})(${JSON.stringify(footnotes)})`));

package/dist/commands/screenshot.js

@@ -2,18 +2,17 @@ import { copyFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { checkPages } from "../browser.js";
 import { findRoot, findTheme, ThemeError } from "../project.js";
-import { extraFixtures, normalTargets, renderSite } from "../render.js";
+import { extraFixtures, FIXTURE_NAMES, RenderTarget, renderSite, } from "../render.js";
 import { expectations } from "./check.js";
+// Any fixture on any platform: a screenshot is a deliberate one-off, not the check matrix.
 function selectTarget(root, values) {
-    const targets = normalTargets(extraFixtures(root));
-    const { fixture, platform, appearance } = values;
-    if (!targets.some((target) => target.fixture === fixture)) {
+    const { fixture, platform, appearance, card } = values;
+    if (![...Object.keys(FIXTURE_NAMES), ...extraFixtures(root)].includes(fixture)) {
         throw new ThemeError(`unknown fixture: ${fixture}`);
     }
-    const target = targets.find((item) => item.fixture === fixture && item.platform === platform && item.appearance === appearance);
-    if (!target)
-        throw new ThemeError(`${fixture} is checked on Mac and iPhone only`);
-    return target;
+    return new RenderTarget(fixture, platform, appearance, {
+        card: !!card,
+    });
 }
 export default async function screenshot({ values }) {
     const root = findRoot();

package/dist/commands.js

@@ -109,8 +109,10 @@ export const COMMANDS = [
     {
         name: "screenshot",
         summary: "check one case in WebKit and save its image",
-        description: "Render and check a single case in WebKit and save its full-page screenshot. " +
-            "With --promote, it becomes screenshots/theme-preview.png, the marketplace card.",
+        description: "Render and check a single case in WebKit and save its full-page screenshot: any " +
+            "fixture, on any platform. With --card, capture an 800x552 viewport at 2x, the " +
+            "shape of the marketplace card. With --promote, it becomes " +
+            "screenshots/theme-preview.png, the marketplace card.",
         options: [
             {
                 name: "fixture",
@@ -121,6 +123,7 @@ export const COMMANDS = [
             },
             { name: "platform", type: "string", choices: ["mac", "iphone", "ipad"], default: "mac" },
             { name: "appearance", type: "string", choices: ["light", "dark"], default: "light" },
+            { name: "card", type: "boolean", help: "capture the marketplace card's shape at 2x" },
             { name: "promote", type: "boolean", help: "use it as the marketplace screenshot" },
         ],
     },

package/dist/render.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { extname, isAbsolute, join, relative } from "node:path";
 import { decodeHTML } from "entities";
 import { Parser } from "htmlparser2";
 import { renderingInputs } from "./netnewswire.js";
@@ -61,6 +61,18 @@ const VIEWPORTS = {
     iphone: [393, 852],
     ipad: [834, 1112],
 };
+// The marketplace card shows its image at 347x240, cropped from the top.
+const CARD_VIEWPORT = [800, 552];
+// Fixture images a fixture may reference as media/NAME, from fixtures/media/NAME.
+const MEDIA_TYPES = {
+    ".avif": "image/avif",
+    ".gif": "image/gif",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+};
 // The template's own fixtures get the full matrix and the stress cases. Any other
 // fixture a theme adds is an extra: checked on Mac and iPhone in both appearances.
 export const FIXTURE_NAMES = {
@@ -114,13 +126,16 @@ export class RenderTarget {
     height;
     largeText;
     themeScripts;
-    constructor(fixture, platform, appearance, { largeText = false, themeScripts = true } = {}) {
+    /** A 2x capture of the card viewport alone, for the marketplace card. */
+    card;
+    constructor(fixture, platform, appearance, { largeText = false, themeScripts = true, card = false } = {}) {
         this.fixture = fixture;
         this.platform = platform;
         this.appearance = appearance;
-        [this.width, this.height] = VIEWPORTS[platform];
+        [this.width, this.height] = card ? CARD_VIEWPORT : VIEWPORTS[platform];
         this.largeText = largeText;
         this.themeScripts = themeScripts;
+        this.card = card;
     }
     get ios() {
         return this.platform === "iphone" || this.platform === "ipad";
@@ -135,6 +150,8 @@ export class RenderTarget {
             parts.push("large text");
         if (!this.themeScripts)
             parts.push("Article JavaScript off");
+        if (this.card)
+            parts.push("card");
         return parts.join(" · ");
     }
     get scenario() {
@@ -150,6 +167,8 @@ export class RenderTarget {
             parts.push("large-text");
         if (!this.themeScripts)
             parts.push("no-article-js");
+        if (this.card)
+            parts.push("card");
         return parts.join("-");
     }
 }
@@ -235,14 +254,34 @@ function placeholder(width, height) {
         '<rect width="100%" height="100%" fill="#8a8f98" fill-opacity=".35"/></svg>';
     return `data:image/svg+xml;base64,${base64(svg)}`;
 }
+/**
+ * A fixture's own image, media/NAME, as a data URI read from fixtures/media/NAME.
+ * Undefined, so a placeholder as before, unless it is an image inside that directory.
+ */
+function mediaDataURI(media, src) {
+    const type = MEDIA_TYPES[extname(src).toLowerCase()];
+    if (!src.startsWith("media/") || !type)
+        return undefined;
+    try {
+        const path = realpathSync(join(media, src.slice("media/".length)));
+        const inside = relative(realpathSync(media), path);
+        if (inside.startsWith("..") || isAbsolute(inside))
+            return undefined;
+        return `data:${type};base64,${readFileSync(path).toString("base64")}`;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Swap a fixture's network images for same-size placeholders.
  *
  * Previews never touch the network, so a captured article's images would otherwise
  * render broken. Each <img> keeps its attributes and width/height (16:9 when it has
  * none), so layout matches; a <source> that would fetch is dropped for its <img>.
+ * With a media directory, an <img src="media/NAME"> shows that file instead.
  */
-export function offlineMedia(body) {
+export function offlineMedia(body, media) {
     return body.replace(MEDIA_TAG_RE, (whole, tagName, rest) => {
         const tag = tagName.toLowerCase();
         const attributes = [...rest.matchAll(ATTRIBUTE_RE)].map((match) => [
@@ -253,8 +292,9 @@ export function offlineMedia(body) {
             name.toLowerCase(),
             decodeHTML(value.replace(/^["']+|["']+$/g, "")),
         ]));
+        const src = values.get("src") ?? "";
         const srcset = (values.get("srcset") ?? "").split(",").some(fetches);
-        if (!(srcset || fetches(values.get("src") ?? "")))
+        if (!(srcset || fetches(src)))
             return whole;
         if (tag === "source")
             return "";
@@ -262,17 +302,18 @@ export function offlineMedia(body) {
             .filter(([name]) => !["src", "srcset", "sizes"].includes(name.toLowerCase()))
             .map(([name, value]) => (value ? ` ${name}=${value}` : ` ${name}`))
             .join("");
-        return `<${tagName}${kept} src="${placeholder(values.get("width"), values.get("height"))}">`;
+        const local = media === undefined ? undefined : mediaDataURI(media, src);
+        return `<${tagName}${kept} src="${local ?? placeholder(values.get("width"), values.get("height"))}">`;
     });
 }
-function fixtureMapping(fixture, target) {
+function fixtureMapping(fixture, target, media) {
     const mapping = {};
     for (const key of TEMPLATE_KEYS)
         mapping[key] = pyStr(fixture[key] ?? "");
     if (!mapping.dateline_style) {
         mapping.dateline_style = mapping.title ? "articleDateline" : "articleDatelineTitle";
     }
-    mapping.body = offlineMedia(mapping.body ?? "");
+    mapping.body = offlineMedia(mapping.body ?? "", media);
     if (!mapping.avatar_src || fetches(mapping.avatar_src)) {
         mapping.avatar_src = avatarDataURI(mapping.feed_link_title ?? "");
     }
@@ -340,7 +381,7 @@ function isFile(path) {
         return false;
     }
 }
-export function renderPage(theme, fixture, target, snapshot = renderingInputs().path) {
+export function renderPage(theme, fixture, target, snapshot = renderingInputs().path, media) {
     const pagePath = join(snapshot, target.ios ? "iOS" : "Mac", "page.html");
     const required = [
         pagePath,
@@ -360,7 +401,7 @@ export function renderPage(theme, fixture, target, snapshot = renderingInputs().
     }
     const style = substitute(`${read(join(snapshot, "Shared", "core.css"))}\n${stylesheet}`, styleSubstitutions);
     const template = read(join(theme, "template.html"));
-    let body = substitute(template, fixtureMapping(fixture, target));
+    let body = substitute(template, fixtureMapping(fixture, target, media));
     if (!target.themeScripts)
         body = removeScripts(body);
     let page = substitute(skeleton, {
@@ -390,7 +431,7 @@ export function renderSite(root, theme, targets, snapshot = renderingInputs().pa
     const name = themeStem(theme);
     for (const target of targets) {
         const fixture = readFixture(fixturePath(root, target.fixture));
-        writeFileSync(join(pages, `${target.slug}.html`), renderPage(theme, fixture, target, snapshot), "utf8");
+        writeFileSync(join(pages, `${target.slug}.html`), renderPage(theme, fixture, target, snapshot, join(root, "fixtures", "media")), "utf8");
         const label = escapeHTML(target.label);
         const viewer = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width">

package/package.json

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