@zvndev/darkmown 1.5.0 → 2.0.1

package/src/compiler/media.js

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// Media — :video / :audio / :embed. Compile-time only (zero runtime): hardened
+// HTML5 media and privacy-friendly, lazy iframe embeds. The extension stays the
+// feature gate; these emit no `data-wd-*`, so a media-only page ships zero JS.
+//
+// Every handler receives the 0-based line `index` so its malformed/invalid
+// errors report `file:line` (via `at`) — matching the unclosed-block errors —
+// while keeping the message text and `Use:` hints intact.
+// ---------------------------------------------------------------------------
+
+import { at } from "./context.js";
+import { validateFetchUrl } from "./fetch.js";
+import { escapeHtml, stripQuotes } from "./interpolation.js";
+
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+
+/** @type {Record<"video" | "audio", { flags: string[], attrs: string[] }>} */
+const MEDIA_SPEC = {
+  video: {
+    flags: ["controls", "autoplay", "loop", "muted", "playsinline"],
+    attrs: ["poster", "width", "height", "preload"]
+  },
+  audio: { flags: ["controls", "autoplay", "loop", "muted"], attrs: ["preload"] }
+};
+
+/**
+ * `:video /clip.mp4 [poster=…] [width=…] [height=…] [preload=…] [controls] [autoplay]
+ * [loop] [muted] [playsinline]` and `:audio /track.mp3 [preload=…] [controls] …` →
+ * a hardened `<video>`/`<audio>`. Defaults: `preload="metadata"`, and `controls`
+ * unless the clip is an `autoplay` background (autoplay also implies `muted`, which
+ * browsers require). Author flags/attrs always win. URLs use the `:fetch` scheme
+ * guard (relative or http(s)).
+ * @param {string} line
+ * @param {"video" | "audio"} kind
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleMedia(line, kind, ctx, index) {
+  const match = line.match(new RegExp(`^:${kind}\\s+(\\S+)\\s*(.*)$`));
+  if (!match) {
+    throw new Error(
+      `Malformed :${kind} in ${at(ctx, index)}: ${line}. Use: :${kind} /clip [controls] [autoplay] [loop] [muted]`
+    );
+  }
+  const src = validateFetchUrl(stripQuotes(match[1]), ctx, `:${kind}`);
+  const spec = MEDIA_SPEC[kind];
+  /** @type {Set<string>} */
+  const flags = new Set();
+  /** @type {Map<string, string>} */
+  const attrs = new Map();
+  const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
+  for (const token of (match[2] || "").matchAll(re)) {
+    if (token[3]) {
+      if (!spec.flags.includes(token[3]))
+        throw new Error(`Unknown :${kind} flag "${token[3]}" in ${at(ctx, index)}`);
+      flags.add(token[3]);
+    } else {
+      if (!spec.attrs.includes(token[1]))
+        throw new Error(`Unknown :${kind} attribute "${token[1]}" in ${at(ctx, index)}`);
+      attrs.set(token[1], stripQuotes(token[2]));
+    }
+  }
+  // Sensible defaults; author input always wins.
+  if (flags.has("autoplay")) flags.add("muted"); // browsers block unmuted autoplay
+  if (kind === "audio" || !flags.has("autoplay")) flags.add("controls");
+  const parts = [`src="${escapeHtml(src)}"`];
+  if (attrs.has("poster"))
+    parts.push(
+      `poster="${escapeHtml(validateFetchUrl(/** @type {string} */ (attrs.get("poster")), ctx, `:${kind} poster`))}"`
+    );
+  for (const name of ["width", "height"]) {
+    if (attrs.has(name))
+      parts.push(`${name}="${escapeHtml(/** @type {string} */ (attrs.get(name)))}"`);
+  }
+  parts.push(`preload="${escapeHtml(attrs.get("preload") || "metadata")}"`);
+  for (const flag of spec.flags) if (flags.has(flag)) parts.push(flag);
+  return `<${kind} ${parts.join(" ")}></${kind}>`;
+}
+
+/**
+ * `:embed <url> [title="…"]` → a lazy, privacy-friendly responsive iframe. A
+ * YouTube or Vimeo URL is rewritten to its no-cookie / player embed; any other
+ * http(s) URL becomes a generic 16:9 iframe. Inline styles keep the wrapper
+ * self-contained (no framework CSS), so an embed-only page stays zero-JS/zero-CSS.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEmbed(line, ctx, index) {
+  const match = line.match(/^:embed\s+(\S+)\s*(.*)$/);
+  if (!match) {
+    throw new Error(
+      `Malformed :embed in ${at(ctx, index)}: ${line}. Use: :embed https://youtu.be/ID [title="…"]`
+    );
+  }
+  const raw = stripQuotes(match[1]);
+  let title = "";
+  const re = /([A-Za-z-]+)=("[^"]*"|\S+)/g;
+  for (const token of (match[2] || "").matchAll(re)) {
+    if (token[1] !== "title")
+      throw new Error(`Unknown :embed attribute "${token[1]}" in ${at(ctx, index)}`);
+    title = stripQuotes(token[2]);
+  }
+  const { url, label } = resolveEmbed(raw, ctx);
+  const iframe =
+    `<iframe src="${escapeHtml(url)}" title="${escapeHtml(title || label)}" loading="lazy" ` +
+    `referrerpolicy="strict-origin-when-cross-origin" ` +
+    `allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" ` +
+    `allowfullscreen style="width:100%;height:100%;border:0"></iframe>`;
+  return `<div class="wd-embed" style="aspect-ratio:16/9">${iframe}</div>`;
+}
+
+/**
+ * Map a watch/share URL to its embeddable form. YouTube → no-cookie embed, Vimeo →
+ * player; anything else is validated as a generic http(s) iframe source.
+ * @param {string} raw
+ * @param {Ctx} ctx
+ * @returns {{ url: string, label: string }}
+ */
+function resolveEmbed(raw, ctx) {
+  const youtube = raw.match(
+    /(?:youtube\.com\/(?:watch\?v=|embed\/|shorts\/)|youtu\.be\/)([\w-]{6,})/
+  );
+  if (youtube)
+    return { url: `https://www.youtube-nocookie.com/embed/${youtube[1]}`, label: "YouTube video" };
+  const vimeo = raw.match(/vimeo\.com\/(?:video\/)?(\d+)/);
+  if (vimeo) return { url: `https://player.vimeo.com/video/${vimeo[1]}`, label: "Vimeo video" };
+  return { url: validateFetchUrl(raw, ctx, ":embed"), label: "Embedded content" };
+}

package/src/compiler/page.js

@@ -12,7 +12,12 @@ import { htmlHasHighlight } from "../highlight.js";
 import { compileBody } from "./body.js";
 import { createCompilation, createScope } from "./context.js";
 import { parseFrontmatter, warnLikelyFrontmatter } from "./frontmatter.js";
-import { collectColocatedAssets, scanMarkdownHints, scopedSkinFor } from "./includes.js";
+import {
+  collectColocatedAssets,
+  scanMarkdownHints,
+  scopedSkinFor,
+  stampScope
+} from "./includes.js";
 import { escapeHtml } from "./interpolation.js";
 import { selectMd } from "./markdown.js";
 
@@ -26,6 +31,13 @@ import { selectMd } from "./markdown.js";
  * @typedef {import("./context.js").CompiledPage} CompiledPage
  */
 
+// Skip-to-content link: the first focusable element on every page, visually
+// hidden until keyboard focus reveals it. Styled inline (not via a skin) so it
+// behaves on pages with no stylesheet at all; it rides ahead of page skins in
+// the head, so a project skin can restyle `.wd-skip-link` freely.
+const SKIP_LINK_STYLE =
+  "<style>.wd-skip-link{position:absolute;top:0;left:0;z-index:100;padding:.55rem 1.1rem;background:#18221d;color:#f7f3ea;font:600 .9rem/1.2 system-ui,sans-serif;text-decoration:none;border-radius:0 0 8px 0;transform:translateY(-150%)}.wd-skip-link:focus{transform:none}</style>";
+
 /**
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
@@ -42,6 +54,12 @@ export function compilePage(file, context, options = {}) {
   const compiled = compileDocument(file, context, [], options.vars, options.collections);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
+  // Per-page document language for the `<html lang>` attribute (`lang: fr` in
+  // frontmatter). Defaults to English.
+  const lang =
+    typeof compiled.meta.lang === "string" && compiled.meta.lang.trim()
+      ? compiled.meta.lang.trim()
+      : "en";
   // Optional `image:` frontmatter sets the social-share preview (absolute URL).
   const image = typeof compiled.meta.image === "string" ? compiled.meta.image : "";
   /** @type {string[]} */
@@ -68,10 +86,8 @@ export function compilePage(file, context, options = {}) {
   // The framework highlight stylesheet rides ahead of page skins so a project's
   // own `$code-*` tokens / overrides still cascade over it. Pay-for-what-you-use:
   // linked only on pages with a highlighted code block (`hasCode`).
-  const highlightLink = compiled.assets.hasCode
-    ? [`<link rel="stylesheet" href="/__wd/highlight.css">`]
-    : [];
-  const cssLinks = [...highlightLink, ...compiled.assets.skins]
+  const highlightHref = compiled.assets.hasCode ? ["/__wd/highlight.css"] : [];
+  const cssLinks = [...highlightHref, ...compiled.assets.skins]
     .map((href) => `<link rel="stylesheet" href="${href}">`)
     .join("\n");
   // RSS feed discovery: when the site emits an `rss.xml` (home `site_url` set +
@@ -143,20 +159,25 @@ export function compilePage(file, context, options = {}) {
   const stamped =
     scopedSkin && scopedSkin.scoped ? stampScope(compiled.html, scopedSkin.scopeId) : compiled.html;
   const body = enhanceImages(stamped, context);
+  const { content, target } = ensureMainLandmark(body);
 
   return {
     meta: compiled.meta,
+    deps: compiled.deps,
+    collectionsUsed: compiled.collectionsUsed,
     html: `<!doctype html>
-<html lang="en">
+<html lang="${escapeHtml(lang)}">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(title)}</title>${descriptionTag}
   <link rel="icon" href="${favicon}">${feedLink}
+  ${SKIP_LINK_STYLE}
   ${cssLinks}${transitions}${speculation}
 </head>
 <body>
-${body}
+<a class="wd-skip-link" href="#${escapeHtml(target)}">Skip to content</a>
+${content}
 ${scripts}
 </body>
 </html>`,
@@ -166,6 +187,25 @@ ${scripts}
   };
 }
 
+/**
+ * Guarantee the page body exposes a main-content landmark the skip link can
+ * target. A body that already has a `<main>` keeps it: an author-supplied id
+ * wins as the skip target; a `<main>` without one gets `id="main"` stamped on.
+ * A body with no `<main>` at all is wrapped whole. Pure compile-time string
+ * pass (like {@link enhanceImages}) — a static page stays static.
+ * @param {string} html Assembled page body HTML.
+ * @returns {{ content: string, target: string }}
+ */
+function ensureMainLandmark(html) {
+  const open = html.match(/<main\b[^>]*>/i);
+  if (!open) return { content: `<main id="main">\n${html}\n</main>`, target: "main" };
+  // The id attribute must start after whitespace (or a closing quote — sloppy
+  // but browser-parsed) so `data-id="…"` never masquerades as the real id.
+  const id = open[0].match(/[\s"']id\s*=\s*["']([^"']*)["']/i);
+  if (id) return { content: html, target: id[1] || "main" };
+  return { content: html.replace(open[0], `${open[0].slice(0, -1)} id="main">`), target: "main" };
+}
+
 /**
  * Harden every `<img>` in the assembled page body — compile-time only, zero
  * runtime JS. Bare markdown images reflow the page as they decode (cumulative
@@ -203,70 +243,6 @@ export function enhanceImages(html, paths) {
   });
 }
 
-/**
- * Raw-text (`script`, `style`) and escapable-raw-text (`textarea`, `title`)
- * elements per the HTML spec: their CONTENT is not markup, so `<`/`>` inside them
- * are plain characters and must never be treated as tags. The content runs to the
- * first matching close tag.
- * @type {Set<string>}
- */
-const RAW_TEXT_ELEMENTS = new Set(["script", "style", "textarea", "title"]);
-
-/**
- * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
- * half of compile-time scoped styles, mirroring {@link enhanceImages}: a
- * compile-time post-pass over assembled HTML, zero runtime JS. Every element
- * start tag that doesn't already carry a scope attribute gets one, so the scoped
- * stylesheet (whose selectors end in `[data-wd-scope="<id>"]`) matches inside
- * this subtree and nowhere else. Void/self-closing tags are stamped too (the
- * attribute is valid on any element). Closing tags, comments, doctype, and the
- * `<!`/`<?` families are left alone. A tag that ALREADY has a `data-wd-scope`
- * (e.g. a nested include with its own scope) keeps its own — first stamp wins.
- *
- * Raw-text / escapable-raw-text elements (`script`, `style`, `textarea`,
- * `title`) are special-cased: their OPENING tag is stamped (valid), but their
- * BODY is left byte-intact — `<`/`>` inside a `<script>` are JavaScript, not
- * markup, so stamping there would corrupt the content. A small tokenizer walks
- * tag-by-tag (quote-aware in attribute lists) and, on entering a raw-text
- * element, copies through verbatim until the matching close tag.
- * @param {string} html Subtree HTML to scope.
- * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
- * @returns {string}
- */
-export function stampScope(html, scopeId) {
-  // Opening tag: name + (quote-aware) attribute list + optional self-close slash.
-  const openTag = /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
-  let out = "";
-  let cursor = 0;
-  for (let m = openTag.exec(html); m; m = openTag.exec(html)) {
-    const [tag, name, attrs, slash] = m;
-    out += html.slice(cursor, m.index); // text/markup before this opening tag
-    const stamped = /\bdata-wd-scope\s*=/.test(attrs)
-      ? tag // first stamp wins — a pre-stamped tag keeps its own scope
-      : `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
-    out += stamped;
-    cursor = m.index + tag.length;
-
-    // Raw-text element (not self-closed): copy its body through untouched and
-    // resume scanning after the matching close tag, so nothing inside is stamped.
-    if (!slash && RAW_TEXT_ELEMENTS.has(name.toLowerCase())) {
-      const rest = html.slice(cursor);
-      const closeMatch = new RegExp(`</${name}\\s*>`, "i").exec(rest);
-      if (!closeMatch) {
-        out += rest; // unterminated raw-text element — copy the remainder verbatim
-        cursor = html.length;
-        break;
-      }
-      const through = closeMatch.index + closeMatch[0].length; // body + close tag
-      out += rest.slice(0, through); // byte-intact
-      cursor += through;
-      openTag.lastIndex = cursor; // skip the body the scanner would otherwise re-walk
-    }
-  }
-  out += html.slice(cursor); // trailing text after the last opening tag
-  return out;
-}
-
 /**
  * Extract the `src` attribute value from an `<img>` tag, or "" if absent.
  * @param {string} tag
@@ -317,13 +293,25 @@ function measureImage(src, paths) {
 export function compileDocument(file, context, stack = [], vars = {}, collections = new Map()) {
   const comp = createCompilation();
   comp.collections = collections;
-  const result = compileFile(file, context, stack, createScope(null, vars), comp, [], null);
+  const result = compileFile(
+    file,
+    context,
+    stack,
+    createScope(null, vars),
+    comp,
+    [],
+    null,
+    0,
+    null
+  );
   return {
     meta: result.meta,
     html: result.html,
     assets: comp.assets,
     warnings: comp.warnings,
-    pagination: comp.pagination
+    pagination: comp.pagination,
+    deps: comp.deps,
+    collectionsUsed: comp.collectionsUsed
   };
 }
 
@@ -336,9 +324,24 @@ export function compileDocument(file, context, stack = [], vars = {}, collection
  * @param {Compilation} comp
  * @param {string[]} sections
  * @param {string | null} loopItem
+ * @param {number} [reactiveDepth] Enclosing REACTIVE `@loop` levels, threaded in
+ *   from the including page so an include's body can't bypass the two-level
+ *   reactive-nesting limit at the `@include` boundary.
+ * @param {{ at: string, line: string } | null} [loopOpener] The enclosing `@loop`
+ *   opener, threaded in so a depth error inside the include names the right opener.
  * @returns {{ meta: Meta, html: string }}
  */
-export function compileFile(file, context, stack, scope, comp, sections, loopItem) {
+export function compileFile(
+  file,
+  context,
+  stack,
+  scope,
+  comp,
+  sections,
+  loopItem,
+  reactiveDepth = 0,
+  loopOpener = null
+) {
   const real = fs.realpathSync(file);
   if (stack.includes(real)) {
     throw new Error(
@@ -347,13 +350,16 @@ export function compileFile(file, context, stack, scope, comp, sections, loopIte
   }
 
   const raw = fs.readFileSync(file, "utf8");
-  const { meta, body } = parseFrontmatter(raw, file);
+  const { meta, body, bodyLine } = parseFrontmatter(raw, file);
   warnLikelyFrontmatter(raw, file, comp);
+  comp.deps.add(file);
   collectColocatedAssets(file, context, comp.assets);
 
   if (path.extname(file) === ".md") {
     scanMarkdownHints(body, file, comp);
-    const html = selectMd(meta).render(body, {});
+    // Share the compilation's heading-slug counters (as renderProse does), so a
+    // `.md` included from a `.wd` page still dedupes anchors document-wide.
+    const html = selectMd(meta).render(body, { headingSlugs: comp.headingSlugs });
     if (htmlHasHighlight(html)) comp.assets.hasCode = true;
     return { meta, html };
   }
@@ -363,13 +369,18 @@ export function compileFile(file, context, stack, scope, comp, sections, loopIte
   /** @type {Ctx} */
   const ctx = {
     file,
+    bodyLine,
     context,
     stack: [...stack, real],
     scope: createScope(scope, { meta }),
     comp,
     sections,
     loopItem,
-    md: selectMd(meta)
+    reactiveDepth,
+    ...(loopOpener ? { loopOpener } : {}),
+    md: selectMd(meta),
+    compileBody,
+    compileFile
   };
   const html = compileBody(body.replace(/\r\n?/g, "\n").split("\n"), ctx);
   if (htmlHasHighlight(html)) comp.assets.hasCode = true;

package/src/compiler/state.js

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// State declarations: the `:state` / `:store` / `:computed` / `:theme` handlers
+// plus the shared declare* helpers (declareState/declareStore/declareErrorState)
+// the `:fetch` and form handlers lean on to register their auto-declared keys.
+//
+// Every handler receives the 0-based line `index` so its malformed/invalid
+// errors report `file:line` (via `at`) — matching the unclosed-block errors —
+// while keeping the message text and `Use:` hints intact.
+// ---------------------------------------------------------------------------
+
+import { at } from "./context.js";
+import { FORMATTERS } from "./format.js";
+import { escapeHtml, getPath, parseStateValue, safeScriptJson } from "./interpolation.js";
+import { compileComputedExpr } from "./predicates.js";
+
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleState(line, ctx, index) {
+  const match = line.match(/^:state\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+persist)?$/);
+  if (!match) throw new Error(`Malformed :state in ${at(ctx, index)}: ${line}`);
+  const value = parseStateValue(match[2], at(ctx, index));
+  const key = declareState(match[1], value, ctx);
+  const persistAttr = match[3] ? ` data-wd-persist="${key}"` : "";
+  return `<script type="application/json" data-wd-state${persistAttr}>${safeScriptJson({ [key]: value })}</script>`;
+}
+
+/**
+ * Register a state key in the current section scope, enabling the runtime.
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Ctx} ctx
+ * @returns {string} The fully-qualified state key.
+ */
+export function declareState(name, value, ctx) {
+  if (ctx.loopItem)
+    throw new Error(`State cannot be declared inside a reactive @loop body (${ctx.file})`);
+  if (ctx.comp.stores.has(name))
+    throw new Error(
+      `State "${name}" collides with a :store of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    );
+  const key = ctx.sections.length ? `${ctx.sections.at(-1)}:${name}` : name;
+  if (ctx.comp.state.has(key))
+    throw new Error(`State "${name}" is declared twice in the same scope (${ctx.file})`);
+  ctx.comp.state.set(key, value);
+  ctx.comp.assets.runtime = true;
+  return key;
+}
+
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleStore(line, ctx, index) {
+  const match = line.match(/^:store\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+ephemeral)?$/);
+  if (!match)
+    throw new Error(
+      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral]`
+    );
+  const value = parseStateValue(match[2], at(ctx, index));
+  const name = declareStore(match[1], value, ctx);
+  const ephemeral = match[3] ? " data-wd-store-ephemeral" : "";
+  return `<script type="application/json" data-wd-store="${name}"${ephemeral}>${safeScriptJson(value)}</script>`;
+}
+
+/**
+ * Register a page-global store. The bare name is added to `comp.state` so every
+ * resolver (interpolation, :if, @loop, :computed, actions) sees it, and tracked
+ * in `comp.stores` for collision checks. Never section-scoped.
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Ctx} ctx
+ * @returns {string} The store name (also its bare state key).
+ */
+export function declareStore(name, value, ctx) {
+  if (ctx.comp.stores.has(name))
+    throw new Error(`Store "${name}" is declared twice in ${ctx.file}. Use: :store name = value`);
+  if (ctx.comp.state.has(name))
+    throw new Error(
+      `Store "${name}" collides with a :state of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    );
+  ctx.comp.stores.add(name);
+  ctx.comp.state.set(name, value);
+  ctx.comp.assets.runtime = true;
+  return name;
+}
+
+/**
+ * Seed a `<name>_error` state key (null) if absent. Shared by :fetch and the
+ * round-trip :form so error fallbacks have a key to bind.
+ * @param {string} key
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+export function declareErrorState(key, ctx) {
+  const errorKey = `${key}_error`;
+  if (!ctx.comp.state.has(errorKey)) ctx.comp.state.set(errorKey, null);
+}
+
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleComputed(line, ctx, index) {
+  const match = line.match(/^:computed\s+([A-Za-z_$][\w$]*)\s*=\s*(.+)$/);
+  if (!match)
+    throw new Error(
+      `Malformed :computed in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
+    );
+  const expr = compileComputedExpr(match[2].trim(), ctx);
+  /** @type {unknown} */
+  let initial;
+  try {
+    /** @param {string} key @param {string} [path] */
+    const read = (key, path) => getPath(ctx.comp.state.get(key), path ? path.split(".") : []);
+    // Build-time mirror of the runtime's AGG helper, so a `:computed total = sum(...)`
+    // has the same initial value the runtime will recompute to.
+    const agg = (
+      /** @type {string} */ name,
+      /** @type {any} */ list,
+      /** @type {string} */ field
+    ) => (FORMATTERS[name] ? FORMATTERS[name](list, field == null ? [] : [field]) : undefined);
+    initial = new Function("S", "A", `return (${expr});`)(read, agg);
+  } catch {
+    console.warn(
+      `:computed "${match[2].trim()}" in ${ctx.file} could not be evaluated at build time; falling back to null. Check the expression.`
+    );
+    initial = null;
+  }
+  const key = declareState(match[1], initial ?? null, ctx);
+  return `<span data-wd-computed data-wd-computed-key="${key}" data-wd-computed-expr="${escapeHtml(expr)}"></span><script type="application/json" data-wd-state>${safeScriptJson({ [key]: initial ?? null })}</script>`;
+}
+
+/**
+ * `:theme [name] [= "auto"]` declares a durable `:store` (default name `theme`,
+ * seed `"auto"`) and reflects its value onto `<html data-theme>`. This layers a
+ * manual light/dark switch over the OS preference: `"auto"` follows the skin's
+ * `tokens dark` media query, while `"light"`/`"dark"` force the matching
+ * `:root[data-theme]` scope. Wire a switch with ordinary store actions —
+ * `:button "Dark" -> theme = "dark"`. Durable, so the choice survives reloads.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleTheme(line, ctx, index) {
+  const match = line.match(/^:theme(?:\s+([A-Za-z_$][\w$]*))?(?:\s*=\s*(.+))?$/);
+  if (!match) {
+    throw new Error(
+      `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto")`
+    );
+  }
+  const name = match[1] || "theme";
+  const seed = match[2] != null ? parseStateValue(match[2], at(ctx, index)) : "auto";
+  const storeName = declareStore(name, seed, ctx);
+  return `<script type="application/json" data-wd-store="${storeName}">${safeScriptJson(seed)}</script><span data-wd-theme="${storeName}" hidden></span>`;
+}