nnw-theme 2.2.0 → 2.4.0

package/dist/render.js

@@ -3,6 +3,8 @@ import { mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync,
 import { extname, isAbsolute, join, relative } from "node:path";
 import { decodeHTML } from "entities";
 import { Parser } from "htmlparser2";
+import { DELIVERIES, DELIVERY_NAMES, deliver } from "./delivery.js";
+import { enclosuresHTML, fixtureAttachments, fixtureImageURL, placeEnclosures, } from "./enclosures.js";
 import { renderingInputs } from "./netnewswire.js";
 import { fixturePath, readFixture, repositoryFixtures, ThemeError, themeStem, } from "./project.js";
 import { formatG, pyStr } from "./pyformat.js";
@@ -64,7 +66,7 @@ const VIEWPORTS = {
 // 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 = {
+const IMAGE_TYPES = {
     ".avif": "image/avif",
     ".gif": "image/gif",
     ".jpeg": "image/jpeg",
@@ -73,6 +75,23 @@ const MEDIA_TYPES = {
     ".svg": "image/svg+xml",
     ".webp": "image/webp",
 };
+// Enclosure players may also play a fixture's own audio or video file.
+const PLAYABLE_TYPES = {
+    ".aac": "audio/aac",
+    ".flac": "audio/flac",
+    ".m4a": "audio/mp4",
+    ".m4v": "video/mp4",
+    ".mov": "video/quicktime",
+    ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4",
+    ".oga": "audio/ogg",
+    ".ogg": "audio/ogg",
+    ".opus": "audio/ogg",
+    ".wav": "audio/wav",
+    ".webm": "video/webm",
+};
+// An enclosure's own tag, as enclosuresHTML writes it.
+const ENCLOSURE_TAG_RE = /<(video|audio|iframe)\b([^>]*)>/g;
 // 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 = {
@@ -102,6 +121,12 @@ const SCENARIOS = [
         "The kitchen-sink fixture at a large reading size: the xxLargeText size class on " +
             "Mac and 23 pt Dynamic Type on iPhone.",
     ],
+    [
+        "older-netnewswire",
+        "Older NetNewsWire",
+        "The article fixture as NetNewsWire releases before enclosure support render it: " +
+            "they leave the template's [[enclosures]] macro as literal text, which must not show.",
+    ],
     [
         "article-javascript-off",
         "Article JavaScript off",
@@ -117,6 +142,8 @@ const CHECKS = [
     "no broken images",
     "no external requests",
     "no JavaScript errors",
+    "enclosure players and images show, fit the window, and keep their shape",
+    "enclosure captions are legible",
 ];
 export class RenderTarget {
     fixture;
@@ -126,16 +153,22 @@ export class RenderTarget {
     height;
     largeText;
     themeScripts;
+    /** Rendered as NetNewsWire before [[enclosures]]: the macro stays literal. */
+    olderNetNewsWire;
     /** A 2x capture of the card viewport alone, for the marketplace card. */
     card;
-    constructor(fixture, platform, appearance, { largeText = false, themeScripts = true, card = false } = {}) {
+    /** The sync service the article arrives through, rewritten as it delivers it. */
+    delivery;
+    constructor(fixture, platform, appearance, { largeText = false, themeScripts = true, olderNetNewsWire = false, card = false, delivery = undefined, } = {}) {
         this.fixture = fixture;
         this.platform = platform;
         this.appearance = appearance;
         [this.width, this.height] = card ? CARD_VIEWPORT : VIEWPORTS[platform];
         this.largeText = largeText;
         this.themeScripts = themeScripts;
+        this.olderNetNewsWire = olderNetNewsWire;
         this.card = card;
+        this.delivery = delivery;
     }
     get ios() {
         return this.platform === "iphone" || this.platform === "ipad";
@@ -150,6 +183,10 @@ export class RenderTarget {
             parts.push("large text");
         if (!this.themeScripts)
             parts.push("Article JavaScript off");
+        if (this.olderNetNewsWire)
+            parts.push("older NetNewsWire");
+        if (this.delivery)
+            parts.push(`via ${DELIVERY_NAMES[this.delivery]}`);
         if (this.card)
             parts.push("card");
         return parts.join(" · ");
@@ -159,6 +196,10 @@ export class RenderTarget {
             return "large-text";
         if (!this.themeScripts)
             return "article-javascript-off";
+        if (this.olderNetNewsWire)
+            return "older-netnewswire";
+        if (this.delivery)
+            return `${this.fixture} via ${DELIVERY_NAMES[this.delivery]}`;
         return this.fixture;
     }
     get slug() {
@@ -167,6 +208,10 @@ export class RenderTarget {
             parts.push("large-text");
         if (!this.themeScripts)
             parts.push("no-article-js");
+        if (this.olderNetNewsWire)
+            parts.push("older-netnewswire");
+        if (this.delivery)
+            parts.push(this.delivery);
         if (this.card)
             parts.push("card");
         return parts.join("-");
@@ -181,32 +226,80 @@ export function extraFixtures(root) {
     }
     return extras;
 }
-export function normalTargets(extras = []) {
+/** A fixture's deliveries = [...] key, validated: the services to also render it through. */
+export function fixtureDeliveries(fixture, name) {
+    const value = fixture.deliveries;
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) ||
+        !value.every((item) => DELIVERIES.includes(item)) ||
+        new Set(value).size !== value.length) {
+        throw new ThemeError(`${name}: deliveries must list distinct services from ${DELIVERIES.join(", ")}`);
+    }
+    return value;
+}
+/**
+ * Each fixture's deliveries = [...], for those that list any. fixtures are the names
+ * to read: the template's own and the extras.
+ */
+export function readDeliveries(root, fixtures) {
+    const result = {};
+    for (const name of fixtures) {
+        const deliveries = fixtureDeliveries(readFixture(fixturePath(root, name)), `fixtures/${name}.toml`);
+        if (deliveries.length)
+            result[name] = deliveries;
+    }
+    return result;
+}
+/** The fixtures a repository renders: the template's own, then its extras. */
+export function allFixtures(extras) {
+    return [...Object.keys(FIXTURE_NAMES), ...extras];
+}
+/**
+ * Every fixture's matrix. A fixture that lists deliveries is also rendered through
+ * each service, on Mac in light and iPhone in dark, right after its own cases.
+ */
+export function normalTargets(extras = [], deliveries = {}) {
     const targets = [];
-    for (const fixture of Object.keys(FIXTURE_NAMES)) {
-        for (const platform of PLATFORMS) {
+    for (const fixture of allFixtures(extras)) {
+        const platforms = fixture in FIXTURE_NAMES ? PLATFORMS : EXTRA_PLATFORMS;
+        for (const platform of platforms) {
             for (const appearance of APPEARANCES) {
                 targets.push(new RenderTarget(fixture, platform, appearance));
             }
         }
-    }
-    for (const fixture of extras) {
-        for (const platform of EXTRA_PLATFORMS) {
-            for (const appearance of APPEARANCES) {
-                targets.push(new RenderTarget(fixture, platform, appearance));
-            }
+        for (const delivery of deliveries[fixture] ?? []) {
+            targets.push(new RenderTarget(fixture, "mac", "light", { delivery }), new RenderTarget(fixture, "iphone", "dark", { delivery }));
         }
     }
     return targets;
 }
-export function checkTargets(extras = []) {
-    return [
-        ...normalTargets(extras),
+/** A repository's normal matrix, including each fixture's deliveries. */
+export function repositoryTargets(root) {
+    const extras = extraFixtures(root);
+    return normalTargets(extras, readDeliveries(root, allFixtures(extras)));
+}
+/**
+ * Everything check renders. A template that places [[enclosures]] itself also gets
+ * the older-NetNewsWire cases, since releases before enclosure support leave that
+ * macro as text in every article.
+ */
+export function checkTargets(extras = [], { enclosuresMacro = false, deliveries = {} } = {}) {
+    const targets = [
+        ...normalTargets(extras, deliveries),
         new RenderTarget("kitchen-sink", "mac", "light", { largeText: true }),
         new RenderTarget("kitchen-sink", "iphone", "light", { largeText: true }),
         new RenderTarget("article", "mac", "light", { themeScripts: false }),
         new RenderTarget("article", "iphone", "light", { themeScripts: false }),
     ];
+    if (enclosuresMacro) {
+        targets.push(new RenderTarget("article", "mac", "light", { olderNetNewsWire: true }), new RenderTarget("article", "iphone", "dark", { olderNetNewsWire: true }));
+    }
+    return targets;
+}
+/** Whether a theme places enclosures itself, as NetNewsWire decides it. */
+export function placesEnclosures(theme) {
+    return read(join(theme, "template.html")).includes("[[enclosures]]");
 }
 /** Perform NetNewsWire's single-pass, non-recursive macro substitution. */
 export function substitute(template, mapping) {
@@ -258,8 +351,8 @@ function placeholder(width, height) {
  * 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()];
+function mediaDataURI(media, src, types = IMAGE_TYPES) {
+    const type = types[extname(src).toLowerCase()];
     if (!src.startsWith("media/") || !type)
         return undefined;
     try {
@@ -306,14 +399,73 @@ export function offlineMedia(body, media) {
         return `<${tagName}${kept} src="${local ?? placeholder(values.get("width"), values.get("height"))}">`;
     });
 }
-function fixtureMapping(fixture, target, media) {
+/** A tag's attributes, in order, with their raw (still quoted) values. */
+function parseAttributes(rest) {
+    return [...rest.matchAll(ATTRIBUTE_RE)].map((match) => [
+        match[1] ?? "",
+        match[2] ?? "",
+    ]);
+}
+function attributeValue(attributes, name) {
+    const found = attributes.find(([key]) => key.toLowerCase() === name);
+    return found && decodeHTML(found[1].replace(/^["']+|["']+$/g, ""));
+}
+/**
+ * Take enclosures offline, as offlineMedia does a body. Images and a video's poster
+ * become placeholders (media/NAME shows the fixture's file); a player that would
+ * fetch loses its source, as if the file had not loaded, unless it plays a media/
+ * file; a video with nothing to show gets a placeholder poster at its own size, for
+ * the frame it would load; and the YouTube player becomes a same-size placeholder.
+ */
+export function offlineEnclosures(html, media) {
+    const local = (src, types) => media === undefined ? undefined : mediaDataURI(media, src, types);
+    return offlineMedia(html, media).replace(ENCLOSURE_TAG_RE, (_whole, tagName, rest) => {
+        const attributes = parseAttributes(rest);
+        const width = attributeValue(attributes, "width");
+        const height = attributeValue(attributes, "height");
+        const src = attributeValue(attributes, "src") ?? "";
+        if (tagName === "iframe") {
+            const label = `${width && height ? `${width} × ${height} ` : ""}YouTube player`;
+            const page = "<body style='margin:0;display:grid;place-items:center;height:100vh;" +
+                `background:#8a8f98;color:#fff;font:600 16px system-ui'>${label}`;
+            const kept = attributes.filter(([name]) => name.toLowerCase() !== "src");
+            return `<iframe${kept.map(([n, v]) => (v ? ` ${n}=${v}` : ` ${n}`)).join("")} srcdoc="${escapeHTML(page)}">`;
+        }
+        const playable = fetches(src) ? local(src, PLAYABLE_TYPES) : src;
+        const kept = attributes.filter(([name]) => !["src", "poster"].includes(name.toLowerCase()));
+        let tag = `<${tagName}${kept.map(([n, v]) => (v ? ` ${n}=${v}` : ` ${n}`)).join("")}`;
+        if (playable)
+            tag += ` src="${escapeHTML(playable)}"`;
+        if (tagName === "video") {
+            const poster = attributeValue(attributes, "poster");
+            let shown;
+            if (poster)
+                shown = fetches(poster) ? (local(poster) ?? placeholder(width, height)) : poster;
+            else if (!playable)
+                shown = placeholder(width, height);
+            if (shown)
+                tag += ` poster="${escapeHTML(shown)}"`;
+        }
+        return `${tag}>`;
+    });
+}
+function fixtureMapping(fixture, target, template, 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 ?? "", media);
+    let body = mapping.body ?? "";
+    if (target.delivery)
+        body = deliver(body, target.delivery, mapping.preferred_link ?? "");
+    mapping.body = offlineMedia(body, media);
+    // NetNewsWire before enclosure support ignores attachments and leaves the macro.
+    if (!target.olderNetNewsWire) {
+        const name = `fixtures/${target.fixture}.toml`;
+        const enclosures = enclosuresHTML(fixtureAttachments(fixture, name), body, fixtureImageURL(fixture, name));
+        Object.assign(mapping, placeEnclosures(template, mapping.body, offlineEnclosures(enclosures, media)));
+    }
     if (!mapping.avatar_src || fetches(mapping.avatar_src)) {
         mapping.avatar_src = avatarDataURI(mapping.feed_link_title ?? "");
     }
@@ -381,6 +533,42 @@ function isFile(path) {
         return false;
     }
 }
+/**
+ * Article.baseURL, made absolute as NetNewsWire does: no fragment, and nothing unless
+ * http or https.
+ */
+export function articleBaseURL(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return "";
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return "";
+    url.hash = "";
+    return url.href;
+}
+/**
+ * The page's base URL: the fixture's base_url when it gives one, else its link. An
+ * article synced through the Reader API (FreshRSS, Miniflux, Inoreader) has only an
+ * external link, so NetNewsWire falls back to the feed's home page: a delivered case
+ * uses feed_link, unless base_url gives the home page the service reports instead.
+ */
+function pageBaseURL(fixture, target) {
+    const name = `fixtures/${target.fixture}.toml`;
+    const baseURL = fixture.base_url;
+    if (baseURL !== undefined && typeof baseURL !== "string") {
+        throw new ThemeError(`${name}: base_url must be a string`);
+    }
+    if (baseURL !== undefined)
+        return articleBaseURL(baseURL);
+    if (target.delivery && typeof fixture.feed_link === "string" && fixture.feed_link) {
+        return articleBaseURL(fixture.feed_link);
+    }
+    return pyStr(fixture.preferred_link || fixture.feed_link || "");
+}
 export function renderPage(theme, fixture, target, snapshot = renderingInputs().path, media) {
     const pagePath = join(snapshot, target.ios ? "iOS" : "Mac", "page.html");
     const required = [
@@ -401,14 +589,14 @@ 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, media));
+    let body = substitute(template, fixtureMapping(fixture, target, template, media));
     if (!target.themeScripts)
         body = removeScripts(body);
     let page = substitute(skeleton, {
         title: fixture.title ?? "Theme preview",
         style,
         body,
-        baseURL: fixture.preferred_link || fixture.feed_link || "",
+        baseURL: pageBaseURL(fixture, target),
         windowScrollY: "0",
     });
     page = injectScripts(page, snapshot, target.platform);
@@ -498,7 +686,18 @@ export function writeGallery(site, themeName, targets, results = null) {
     const known = new Set(RESERVED_FIXTURE_NAMES);
     const scenarios = new Map(SCENARIOS.map(([scenario, heading, text]) => [scenario, [heading, text]]));
     for (const target of targets) {
-        if (!known.has(target.scenario) && !scenarios.has(target.scenario)) {
+        if (known.has(target.scenario) || scenarios.has(target.scenario))
+            continue;
+        if (target.delivery) {
+            const service = DELIVERY_NAMES[target.delivery];
+            scenarios.set(target.scenario, [
+                target.scenario,
+                `fixtures/${target.fixture}.toml as ${service} delivers it through the Reader ` +
+                    `API: its body rewritten by ${service}'s sanitizer, and the feed's home page ` +
+                    "as the page's base URL.",
+            ]);
+        }
+        else {
             scenarios.set(target.scenario, [target.fixture, `Your fixtures/${target.fixture}.toml.`]);
         }
     }

package/lldb/nnwdump.py

@@ -4,6 +4,14 @@ 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@2 capture` prints the setup steps.
 
+NetNewsWire with enclosure support renders an article's enclosures into that
+dictionary: as `enclosures`, or appended to a wrapped `body` when the template has no
+[[enclosures]] macro. nnwdump keeps neither. It records the article's attachments
+and image instead, as [[attachments]] tables and image_url/thumbnail_url, so nnw-theme
+renders them for whichever template previews the fixture. When the page's base URL
+differs from the article's link, as for an article synced through the Reader API, it
+also records base_url.
+
 Values cross the debugger boundary base64-encoded, so nothing is truncated or
 mis-escaped. HTML values are written as '''literal''' strings, so fixtures stay
 readable and diff cleanly.
@@ -16,6 +24,7 @@ helpers can be tested without a debugger.
 from __future__ import annotations
 
 import base64
+import json
 import optparse
 import shlex
 from pathlib import Path
@@ -24,6 +33,20 @@ USAGE = "nnwdump [--var NAME] [--article NAME] [--no-icon] [OUTPUT.toml]"
 DEFAULT_OUTPUT = "fixtures/nnw-capture.toml"
 # Sorted last so the short metadata stays at the top of the file.
 _HTML_KEYS = {"body"}
+_ENCLOSURES_KEY = "enclosures"
+# ArticleRenderer's body for a template without [[enclosures]]: <div>BODY</div>ENCLOSURES.
+_WRAPPED_BODY_TAIL = '</div><div class="nnw-enclosures">'
+# Attachment's Codable keys, in fixture order, with their fixture names.
+_ATTACHMENT_KEYS = (
+    ("url", "url"),
+    ("mimeType", "mime_type"),
+    ("title", "title"),
+    ("sizeInBytes", "size_in_bytes"),
+    ("durationInSeconds", "duration_in_seconds"),
+    ("width", "width"),
+    ("height", "height"),
+    ("medium", "medium"),
+)
 
 
 def resolve_output(argument: str) -> Path:
@@ -56,13 +79,55 @@ def toml_line(key: str, value: str) -> str:
     return f'{key} = "{_toml_basic(value)}"'
 
 
-def fixture_text(pairs: list[tuple[str, str]], name: str) -> str:
+def without_enclosures(pairs: list[tuple[str, str]]) -> list[tuple[str, str]]:
+    """The substitutions as they were before NetNewsWire rendered the enclosures."""
+    values = dict(pairs)
+    if _ENCLOSURES_KEY not in values:
+        body = values.get("body", "")
+        at = body.rfind(_WRAPPED_BODY_TAIL)
+        if body.startswith("<div>") and at != -1:
+            values["body"] = body[len("<div>") : at]
+    values.pop(_ENCLOSURES_KEY, None)
+    return list(values.items())
+
+
+def attachments_from_json(text: str) -> list[dict]:
+    """Attachment JSON, as [Attachment].json() writes it, as fixture tables."""
+    tables = []
+    for attachment in json.loads(text or "[]") or []:
+        table = {
+            name: attachment[key]
+            for key, name in _ATTACHMENT_KEYS
+            if attachment.get(key) is not None
+        }
+        if table.get("url"):
+            tables.append(table)
+    return tables
+
+
+def base_url_pairs(pairs: list[tuple[str, str]], base_url: str) -> list[tuple[str, str]]:
+    """base_url, when the rendered page's base differs from preferred_link."""
+    preferred = dict(pairs).get("preferred_link", "")
+    return [] if base_url == preferred else [("base_url", base_url)]
+
+
+def _toml_value_line(key: str, value) -> str:
+    if isinstance(value, bool) or not isinstance(value, int):
+        return toml_line(key, str(value))
+    return f"{key} = {value}"
+
+
+def fixture_text(pairs: list[tuple[str, str]], name: str, attachments: list[dict] = ()) -> 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@2 render {name}\n\n"
     )
-    return header + "\n".join(toml_line(key, value) for key, value in ordered) + "\n"
+    text = header + "\n".join(toml_line(key, value) for key, value in ordered) + "\n"
+    for table in attachments:
+        lines = [_toml_value_line(key, value) for key, value in table.items()]
+        text += "\n[[attachments]]\n" + "\n".join(lines) + "\n"
+    return text
 
 
 def _evaluate(interpreter, expression: str):
@@ -127,19 +192,36 @@ def nnwdump(debugger, command, result, internal_dict):
         result.SetError(f"`{options.var}` is empty; is this the substitution dictionary?")
         return
 
+    # Older NetNewsWire has no attachments to read; capture the article without them.
+    pairs = without_enclosures(pairs)
+    attachments = []
+    raw, _ = _evaluate(interpreter, f'({options.article}.attachments ?? []).json() ?? "[]"')
+    if raw:
+        attachments = attachments_from_json(raw)
+    for key, link in (("image_url", "imageLink"), ("thumbnail_url", "thumbnailLink")):
+        value, _ = _evaluate(interpreter, f'{options.article}.{link} ?? ""')
+        if value:
+            pairs.append((key, value))
+    # The renderer's own base: the article's link, else the feed's home page.
+    base_url, _ = _evaluate(interpreter, 'self.baseURL?.absoluteString ?? ""')
+    if base_url is not None:
+        pairs.extend(base_url_pairs(pairs, base_url))
+
     note = ""
+    if attachments:
+        note = f" and {len(attachments)} attachment{'s' if len(attachments) > 1 else ''}"
     if not options.no_icon:
         icon = _icon_data_url(interpreter, options.article)
         if icon:
             pairs = [(key, value) for key, value in pairs if key != "avatar_src"]
             pairs.append(("avatar_src", icon))
-            note = " with the feed's icon"
+            note += " with the feed's icon"
         else:
-            note = "; the feed has no icon, so previews generate one"
+            note += "; the feed has no icon, so previews generate one"
 
     try:
         output.parent.mkdir(parents=True, exist_ok=True)
-        output.write_text(fixture_text(pairs, output.stem), encoding="utf-8")
+        output.write_text(fixture_text(pairs, output.stem, attachments), encoding="utf-8")
     except OSError as error:
         result.SetError(f"could not write {output}: {error}")
         return

package/package.json

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