nnw-theme 2.3.0 → 2.4.0

package/dist/commands/preview.js

@@ -3,7 +3,7 @@ import { relative, sep } from "node:path";
 import { serve } from "../browser.js";
 import { openInBrowser } from "../interactive.js";
 import { findRoot, findTheme } from "../project.js";
-import { extraFixtures, normalTargets, renderSite } from "../render.js";
+import { renderSite, repositoryTargets } from "../render.js";
 /** Whether a changed path is theme or fixture content the gallery is built from. */
 export function watched(root, path) {
     const parts = relative(root, path).split(sep);
@@ -15,7 +15,7 @@ export function watched(root, path) {
 export default async function preview({ values }) {
     const root = findRoot();
     const theme = findTheme(root);
-    const build = () => renderSite(root, theme, normalTargets(extraFixtures(root)));
+    const build = () => renderSite(root, theme, repositoryTargets(root));
     const site = build();
     const server = await serve(site, { live: true });
     console.log(`Preview: ${server.url}`);

package/dist/commands/render.js

@@ -1,9 +1,9 @@
 import { findRoot, findTheme, ThemeError } from "../project.js";
-import { extraFixtures, normalTargets, renderSite } from "../render.js";
+import { renderSite, repositoryTargets } from "../render.js";
 export default function render({ positionals }) {
     const root = findRoot();
     const theme = findTheme(root);
-    let targets = normalTargets(extraFixtures(root));
+    let targets = repositoryTargets(root);
     if (positionals.length) {
         const requested = new Set(positionals);
         targets = targets.filter((target) => requested.has(target.fixture));

package/dist/commands/screenshot.js

@@ -6,12 +6,13 @@ import { extraFixtures, FIXTURE_NAMES, RenderTarget, renderSite, } from "../rend
 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 { fixture, platform, appearance, card } = values;
+    const { fixture, platform, appearance, card, delivery } = values;
     if (![...Object.keys(FIXTURE_NAMES), ...extraFixtures(root)].includes(fixture)) {
         throw new ThemeError(`unknown fixture: ${fixture}`);
     }
     return new RenderTarget(fixture, platform, appearance, {
         card: !!card,
+        delivery: delivery,
     });
 }
 export default async function screenshot({ values }) {
@@ -19,7 +20,11 @@ export default async function screenshot({ values }) {
     const theme = findTheme(root);
     const target = selectTarget(root, values);
     const site = renderSite(root, theme, [target]);
-    const results = await checkPages(site, [target], undefined, expectations(root, [target]));
+    const warned = {};
+    const expected = expectations(root, [target]);
+    const results = await checkPages(site, [target], undefined, expected, warned);
+    for (const warning of warned[target.slug] ?? [])
+        console.log(`Warning: ${warning}`);
     const failures = results[target.slug] ?? [];
     if (failures.length) {
         throw new ThemeError(`screenshot checks failed:\n- ${failures.join("\n- ")}`);

package/dist/commands.js

@@ -1,5 +1,6 @@
 // The one description of the command line: the parser, help, and shell completion
 // are all generated from it, so they cannot drift apart.
+import { DELIVERIES } from "./delivery.js";
 export const PROGRAM = "nnw-theme";
 export const DESCRIPTION = "Create, preview, check, and publish a NetNewsWire theme.";
 export const GUIDE_TOPICS = [
@@ -18,6 +19,7 @@ export const BUILT_IN_FIXTURE_NAMES = ["article", "kitchen-sink"];
  */
 export const CATALOG_FIXTURES = {
     ghost: "Ghost cards, galleries, and lazy images",
+    mastodon: "Mastodon post: mentions, hashtags, custom emoji, image enclosures",
     medium: "Medium figures, unsized images, and footer",
     "media-rss": "Image, video, and YouTube enclosures with captions",
     podcast: "Podcast audio enclosure and episode artwork",
@@ -112,7 +114,7 @@ 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: any " +
-            "fixture, on any platform. With --card, capture an 800x552 viewport at 2x, the " +
+            "fixture, on any platform, directly or --delivery through a sync service. 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: [
@@ -125,6 +127,12 @@ export const COMMANDS = [
             },
             { name: "platform", type: "string", choices: ["mac", "iphone", "ipad"], default: "mac" },
             { name: "appearance", type: "string", choices: ["light", "dark"], default: "light" },
+            {
+                name: "delivery",
+                type: "string",
+                choices: DELIVERIES,
+                help: "render the fixture as this sync service delivers it",
+            },
             { name: "card", type: "boolean", help: "capture the marketplace card's shape at 2x" },
             { name: "promote", type: "boolean", help: "use it as the marketplace screenshot" },
         ],
@@ -136,7 +144,7 @@ export const COMMANDS = [
     },
     {
         name: "fixture",
-        summary: "add fixtures modeled on WordPress, Ghost, Substack, and Medium",
+        summary: "add fixtures modeled on WordPress, Ghost, Substack, Medium, and Mastodon",
         description: "Copy ready-made fixtures with markup modeled on what major publishing platforms " +
             "send into fixtures/, where preview and check pick them up. Each one adds four " +
             "renders to every check.",

package/dist/delivery.js

@@ -0,0 +1,516 @@
+// Article HTML as a sync service delivers it to NetNewsWire. FreshRSS and Miniflux
+// sanitize every article before NetNewsWire sees it, and both rewrites can break a
+// theme that relies on the publisher's ids, classes, wrappers, or relative links.
+//
+// Each policy follows its service's sanitizer, closely enough for a preview: Miniflux's
+// internal/reader/sanitizer/sanitizer.go (2.3.5) and FreshRSS's SimplePie settings in
+// app/Models/SimplePieCustom.php (1.30.4). Neither removes tracking parameters or
+// rewrites iframe URLs, which no theme can see in an offline preview. No imports from
+// the project: commands.ts lists DELIVERIES, and project.ts imports commands.ts.
+import { Parser } from "htmlparser2";
+export const DELIVERIES = ["freshrss", "miniflux"];
+export const DELIVERY_NAMES = {
+    freshrss: "FreshRSS",
+    miniflux: "Miniflux",
+};
+const VOID_ELEMENTS = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+]);
+function escapeText(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function escapeAttribute(value) {
+    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;");
+}
+function absolute(value, base) {
+    try {
+        return new URL(value.trim(), base || undefined).href;
+    }
+    catch {
+        return undefined;
+    }
+}
+function scheme(url) {
+    return url.slice(0, Math.max(url.indexOf(":"), 0)).toLowerCase();
+}
+/** Rewrite html element by element, as policy decides; comments are always dropped. */
+function rewrite(html, policy, articleURL) {
+    let output = "";
+    // One entry per open element: whether its end tag is written, or "drop" while its subtree is skipped.
+    const stack = [];
+    const dropping = () => stack.includes("drop");
+    const parser = new Parser({
+        onopentag(name, attribs) {
+            if (dropping()) {
+                stack.push("drop");
+                return;
+            }
+            const decision = policy(name, Object.entries(attribs), articleURL);
+            if (decision === "drop") {
+                stack.push("drop");
+            }
+            else if (decision === "unwrap") {
+                stack.push(false);
+            }
+            else {
+                const attributes = decision.keep
+                    .map(([key, value]) => value === "" ? ` ${key}` : ` ${key}="${escapeAttribute(value)}"`)
+                    .join("");
+                output += `<${name}${attributes}>`;
+                stack.push(!VOID_ELEMENTS.has(name));
+            }
+        },
+        ontext(text) {
+            if (!dropping())
+                output += escapeText(text);
+        },
+        onclosetag(name) {
+            const entry = stack.pop();
+            if (entry === true)
+                output += `</${name}>`;
+        },
+    }, { decodeEntities: true });
+    parser.end(html);
+    return output;
+}
+// Miniflux: an allowlist of elements and attributes; anything else is unwrapped.
+const MINIFLUX_ALLOWED = {
+    a: ["href", "title", "id"],
+    abbr: ["title"],
+    acronym: ["title"],
+    aside: [],
+    audio: ["src"],
+    blockquote: [],
+    b: [],
+    br: [],
+    caption: [],
+    cite: [],
+    code: [],
+    dd: ["id"],
+    del: [],
+    dfn: [],
+    dl: ["id"],
+    dt: ["id"],
+    em: [],
+    figcaption: [],
+    figure: [],
+    h1: ["id"],
+    h2: ["id"],
+    h3: ["id"],
+    h4: ["id"],
+    h5: ["id"],
+    h6: ["id"],
+    hr: [],
+    i: [],
+    iframe: ["width", "height", "frameborder", "src", "allowfullscreen"],
+    img: [
+        "alt",
+        "title",
+        "src",
+        "srcset",
+        "sizes",
+        "width",
+        "height",
+        "fetchpriority",
+        "decoding",
+    ],
+    ins: [],
+    kbd: [],
+    li: ["id"],
+    ol: ["id"],
+    p: [],
+    picture: [],
+    pre: [],
+    q: ["cite"],
+    rp: [],
+    rt: [],
+    rtc: [],
+    ruby: [],
+    s: [],
+    small: [],
+    samp: [],
+    source: ["src", "type", "srcset", "sizes", "media"],
+    strong: [],
+    sub: [],
+    sup: ["id"],
+    table: [],
+    td: ["rowspan", "colspan"],
+    tfoot: [],
+    th: ["rowspan", "colspan"],
+    thead: [],
+    time: ["datetime"],
+    tr: [],
+    u: [],
+    ul: ["id"],
+    var: [],
+    video: ["poster", "height", "width", "src"],
+    wbr: [],
+};
+const MINIFLUX_IFRAME_HOSTS = new Set([
+    "bandcamp.com",
+    "cdn.embedly.com",
+    "dailymotion.com",
+    "framatube.org",
+    "open.spotify.com",
+    "player.bilibili.com",
+    "player.twitch.tv",
+    "player.vimeo.com",
+    "soundcloud.com",
+    "vk.com",
+    "w.soundcloud.com",
+    "youtube-nocookie.com",
+    "youtube.com",
+]);
+const MINIFLUX_BLOCKED_URLS = [
+    "api.flattr.com",
+    "www.facebook.com/sharer.php",
+    "feeds.feedburner.com",
+    "feedsportal.com",
+    "linkedin.com/shareArticle",
+    "pinterest.com/pin/create/button/",
+    "stats.wordpress.com",
+    "twitter.com/intent/tweet",
+    "twitter.com/share",
+    "x.com/intent/tweet",
+    "x.com/share",
+];
+const MINIFLUX_SCHEMES = new Set(("https http apt bitcoin callto dav davs ed2k facetime feed ftp geo git gopher irc irc6 " +
+    "ircs itms-apps itms magnet mailto news nntp rtmp sftp sip sips shortcuts skype spotify " +
+    "ssh steam svn svn+ssh tel webcal xmpp opener hack").split(" "));
+const MINIFLUX_DATA_IMAGES = [
+    "data:image/avif",
+    "data:image/apng",
+    "data:image/png",
+    "data:image/svg",
+    "data:image/jpg",
+    "data:image/jpeg",
+    "data:image/gif",
+    "data:image/webp",
+];
+const URL_ATTRIBUTES = new Set(["src", "href", "poster", "cite"]);
+function positiveInteger(value) {
+    return /^\+?[0-9]+$/.test(value) && Number(value) > 0;
+}
+function minifluxSrcset(value, base) {
+    return value
+        .split(",")
+        .map((candidate) => candidate.trim().split(/\s+/))
+        .flatMap(([url = "", ...descriptors]) => {
+        const resolved = url ? absolute(url, base) : undefined;
+        if (!resolved || !MINIFLUX_SCHEMES.has(scheme(resolved)))
+            return [];
+        if (MINIFLUX_BLOCKED_URLS.some((blocked) => resolved.includes(blocked)))
+            return [];
+        return [[resolved, ...descriptors].join(" ")];
+    })
+        .join(", ");
+}
+const miniflux = (tag, attributes, articleURL) => {
+    if (["script", "style", "noscript"].includes(tag))
+        return "drop";
+    if (attributes.some(([key]) => key === "hidden"))
+        return "drop";
+    if (tag === "img") {
+        const tiny = (key) => attributes.some(([name, value]) => name === key && (value === "0" || value === "1"));
+        if (tiny("width") && tiny("height"))
+            return "drop";
+    }
+    const allowed = MINIFLUX_ALLOWED[tag];
+    if (!allowed)
+        return "unwrap";
+    const keep = [];
+    let anchorLink = false;
+    let youTube = false;
+    for (const [key, raw] of attributes) {
+        if (!allowed.includes(key))
+            continue;
+        let value = raw;
+        if (tag === "img") {
+            if (key === "fetchpriority" && !["high", "low", "auto"].includes(value))
+                continue;
+            if (key === "decoding" && !["sync", "async", "auto"].includes(value))
+                continue;
+            if ((key === "width" || key === "height") && !positiveInteger(value))
+                continue;
+        }
+        if ((tag === "img" || tag === "source") && key === "srcset") {
+            value = minifluxSrcset(value, articleURL);
+            if (!value)
+                continue;
+        }
+        if (URL_ATTRIBUTES.has(key)) {
+            if (tag === "iframe") {
+                let host = "";
+                try {
+                    host = new URL(raw, "https://invalid.example").hostname.replace(/^www\./, "");
+                }
+                catch {
+                    // Not a URL: not an allowed host.
+                }
+                if (!MINIFLUX_IFRAME_HOSTS.has(host))
+                    return "drop";
+                youTube = host === "youtube.com" || host === "youtube-nocookie.com";
+            }
+            else if (tag === "img" &&
+                key === "src" &&
+                MINIFLUX_DATA_IMAGES.some((p) => raw.startsWith(p))) {
+                // Allowed data image.
+            }
+            else if (tag === "a" && key === "href" && raw.startsWith("#")) {
+                anchorLink = true;
+            }
+            else {
+                if (MINIFLUX_BLOCKED_URLS.some((blocked) => raw.includes(blocked))) {
+                    return tag === "iframe" ? "drop" : "unwrap";
+                }
+                const resolved = absolute(raw, articleURL);
+                if (!resolved || !MINIFLUX_SCHEMES.has(scheme(resolved)))
+                    continue;
+                value = resolved;
+            }
+        }
+        keep.push([key, value]);
+    }
+    const has = (key) => keep.some(([name]) => name === key);
+    const required = tag === "a"
+        ? has("href")
+        : tag === "iframe"
+            ? has("src")
+            : tag === "img" || tag === "source"
+                ? has("src") || has("srcset")
+                : true;
+    if (!required)
+        return tag === "iframe" ? "drop" : "unwrap";
+    if (!anchorLink) {
+        if (tag === "a") {
+            keep.push(["rel", "noopener noreferrer"], ["referrerpolicy", "no-referrer"]);
+            // The default for Miniflux's "Open external links in a new tab" setting.
+            keep.push(["target", "_blank"]);
+        }
+        else if (tag === "video" || tag === "audio") {
+            keep.push(["controls", ""]);
+        }
+        else if (tag === "iframe") {
+            keep.push([
+                "sandbox",
+                "allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox",
+            ], ["loading", "lazy"]);
+            if (youTube)
+                keep.push(["referrerpolicy", "strict-origin-when-cross-origin"]);
+        }
+        else if (tag === "img") {
+            keep.push(["loading", "lazy"]);
+        }
+    }
+    return { keep };
+};
+// FreshRSS: SimplePie with FreshRSS's allowlist. id and class survive only renamed,
+// as data-sanitized-id and data-sanitized-class; data-* and aria-* attributes stay.
+const FRESHRSS_GLOBAL = ["dir", "draggable", "hidden", "lang", "role", "title"];
+const FRESHRSS_ALLOWED = {
+    a: ["href", "hreflang", "type"],
+    abbr: [],
+    acronym: [],
+    address: [],
+    article: [],
+    aside: [],
+    audio: ["controlslist", "loop", "muted", "src"],
+    b: [],
+    bdi: [],
+    bdo: [],
+    big: [],
+    blink: [],
+    blockquote: ["cite"],
+    br: ["clear"],
+    button: ["disabled"],
+    canvas: ["width", "height"],
+    caption: ["align"],
+    center: [],
+    cite: [],
+    code: [],
+    col: ["span", "align", "valign", "width"],
+    colgroup: ["span", "align", "valign", "width"],
+    data: ["value"],
+    datalist: [],
+    dd: [],
+    del: ["cite", "datetime"],
+    details: ["open"],
+    dfn: [],
+    dialog: [],
+    dir: [],
+    div: ["align"],
+    dl: [],
+    dt: [],
+    em: [],
+    fieldset: ["disabled"],
+    figcaption: [],
+    figure: [],
+    footer: [],
+    h1: [],
+    h2: [],
+    h3: [],
+    h4: [],
+    h5: [],
+    h6: [],
+    header: [],
+    hgroup: [],
+    hr: ["align", "noshade", "size", "width"],
+    i: [],
+    iframe: [
+        "src",
+        "align",
+        "frameborder",
+        "longdesc",
+        "marginheight",
+        "marginwidth",
+        "scrolling",
+        "allowfullscreen",
+    ],
+    img: ["src", "alt", "width", "height", "align", "border", "hspace", "longdesc", "vspace"],
+    ins: ["cite", "datetime"],
+    kbd: [],
+    label: [],
+    legend: [],
+    li: ["value", "type"],
+    main: [],
+    mark: [],
+    menu: [],
+    meter: ["value", "min", "max", "low", "high", "optimum"],
+    nav: [],
+    nobr: [],
+    ol: ["reversed", "start", "type"],
+    output: [],
+    p: ["align"],
+    picture: [],
+    pre: ["width", "wrap"],
+    progress: ["max", "value"],
+    q: ["cite"],
+    rb: [],
+    rp: [],
+    rt: [],
+    rtc: [],
+    ruby: [],
+    s: [],
+    samp: [],
+    search: [],
+    section: [],
+    small: [],
+    source: ["type", "src", "media", "height", "width"],
+    span: [],
+    strike: [],
+    strong: [],
+    sub: [],
+    summary: [],
+    sup: [],
+    table: ["align", "border", "cellpadding", "cellspacing", "rules", "summary", "width"],
+    tbody: ["align", "char", "charoff", "valign"],
+    td: ["colspan", "headers", "rowspan", "abbr", "align", "height", "scope", "valign", "width"],
+    tfoot: ["align", "valign"],
+    th: ["abbr", "colspan", "rowspan", "scope", "align", "height", "valign", "width"],
+    thead: ["align", "valign"],
+    time: ["datetime"],
+    tr: ["align", "valign"],
+    track: ["default", "kind", "srclang", "label", "src"],
+    tt: [],
+    u: [],
+    ul: ["type"],
+    var: [],
+    video: ["src", "poster", "controlslist", "height", "loop", "muted", "playsinline", "width"],
+    wbr: [],
+};
+const FRESHRSS_STRIPPED_DATA = new Set([
+    "data-auto-leave-validation",
+    "data-leave-validation",
+    "data-no-leave-validation",
+    "data-original",
+]);
+const FRESHRSS_URLS = {
+    a: ["href"],
+    audio: ["src"],
+    blockquote: ["cite"],
+    del: ["cite"],
+    iframe: ["src"],
+    img: ["longdesc", "src"],
+    ins: ["cite"],
+    q: ["cite"],
+    source: ["src"],
+    track: ["src"],
+    video: ["poster", "src"],
+};
+const FRESHRSS_ADDED = {
+    audio: [
+        ["controls", "controls"],
+        ["preload", "none"],
+    ],
+    iframe: [
+        [
+            "allow",
+            "accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
+        ],
+        ["sandbox", "allow-scripts allow-same-origin"],
+        ["allowfullscreen", "allowfullscreen"],
+    ],
+    video: [
+        ["controls", "controls"],
+        ["preload", "none"],
+    ],
+};
+const freshRSS = (tag, attributes, articleURL) => {
+    if (tag === "script" || tag === "style")
+        return "drop";
+    const allowed = FRESHRSS_ALLOWED[tag];
+    if (!allowed)
+        return "unwrap";
+    const urls = FRESHRSS_URLS[tag] ?? [];
+    const keep = [];
+    for (const [key, raw] of attributes) {
+        let name = key;
+        let value = raw;
+        if (key === "id" || key === "class") {
+            name = `data-sanitized-${key}`;
+        }
+        else if (key.startsWith("data-")) {
+            if (FRESHRSS_STRIPPED_DATA.has(key))
+                continue;
+        }
+        else if (!key.startsWith("aria-") &&
+            !allowed.includes(key) &&
+            !FRESHRSS_GLOBAL.includes(key)) {
+            continue;
+        }
+        if (urls.includes(key)) {
+            // SimplePie makes every URL absolute against the article, fragments included.
+            const resolved = absolute(raw, articleURL);
+            if (!resolved)
+                continue;
+            const kind = scheme(resolved);
+            if (kind === "javascript" || (kind === "data" && !(tag === "img" && key === "src"))) {
+                continue;
+            }
+            value = resolved;
+        }
+        keep.push([name, value]);
+    }
+    const added = FRESHRSS_ADDED[tag] ?? [];
+    const names = new Set(keep.map(([name]) => name));
+    keep.push(...added.filter(([name]) => !names.has(name)));
+    return { keep };
+};
+const POLICIES = { freshrss: freshRSS, miniflux };
+/** body as delivery would hand it to NetNewsWire for the article at articleURL. */
+export function deliver(body, delivery, articleURL) {
+    return rewrite(body, POLICIES[delivery], articleURL);
+}

package/dist/project.js

@@ -153,6 +153,7 @@ export function fixturePath(root, name) {
     }
     throw new ThemeError(`fixture not found: ${own}`);
 }
+const FOOTNOTE_KEYS = ["notes", "plain_links", "keep_with_word", "all_converted"];
 function isTable(value) {
     return (!!value && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date));
 }
@@ -161,7 +162,9 @@ function isTable(value) {
  *
  * notes maps each footnote marker's rendered text to the note text its popover must
  * show; plain_links lists CSS selectors for links that must not become footnotes;
- * keep_with_word requires markers written against a word to stay on its line.
+ * keep_with_word requires markers written against a word to stay on its line;
+ * all_converted fails, rather than warns about, a footnote link that never became a
+ * marker.
  */
 export function footnoteExpectations(fixture, name) {
     const expect = fixture.expect ?? {};
@@ -172,7 +175,7 @@ export function footnoteExpectations(fixture, name) {
         throw new ThemeError(`${name}: [expect] may contain only a [expect.footnotes] table`);
     }
     const unknown = Object.keys(footnotes)
-        .filter((key) => !["notes", "plain_links", "keep_with_word"].includes(key))
+        .filter((key) => !FOOTNOTE_KEYS.includes(key))
         .sort();
     if (unknown.length) {
         throw new ThemeError(`${name}: unknown [expect.footnotes] key(s): ${unknown.join(", ")}`);
@@ -198,5 +201,11 @@ export function footnoteExpectations(fixture, name) {
         }
         result.keep_with_word = footnotes.keep_with_word;
     }
+    if ("all_converted" in footnotes) {
+        if (typeof footnotes.all_converted !== "boolean") {
+            throw new ThemeError(`${name}: expect.footnotes.all_converted must be true or false`);
+        }
+        result.all_converted = footnotes.all_converted;
+    }
     return result;
 }