@zvndev/darkmown 1.5.0 → 2.0.0

package/src/compiler/frontmatter.js

@@ -12,13 +12,15 @@ import { stripQuotes } from "./interpolation.js";
  */
 
 /**
- * Split a raw file into its frontmatter `meta` and `body`.
+ * Split a raw file into its frontmatter `meta` and `body`. `bodyLine` is the
+ * 0-based file line index the body starts on (the number of lines the
+ * frontmatter block consumed) so compile errors can report true file lines.
  * @param {string} raw Full file contents.
  * @param {string} [file] Source path, used only for error messages.
- * @returns {{ meta: Meta, body: string }}
+ * @returns {{ meta: Meta, body: string, bodyLine: number }}
  */
 export function parseFrontmatter(raw, file) {
-  if (!raw.startsWith("---\n")) return { meta: {}, body: raw };
+  if (!raw.startsWith("---\n")) return { meta: {}, body: raw, bodyLine: 0 };
   const end = raw.indexOf("\n---", 3);
   if (end === -1) {
     const where = file ? ` in ${file}` : "";
@@ -27,14 +29,17 @@ export function parseFrontmatter(raw, file) {
     );
   }
   const front = raw.slice(4, end).trim();
-  const body = raw.slice(end + 4).replace(/^\n/, "");
+  let bodyStart = end + 4;
+  if (raw[bodyStart] === "\n") bodyStart++;
+  const body = raw.slice(bodyStart);
+  const bodyLine = raw.slice(0, bodyStart).split("\n").length - 1;
   /** @type {Meta} */
   const meta = {};
   for (const line of front.split("\n")) {
     const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
     if (match) meta[match[1]] = parseFrontmatterValue(match[2]);
   }
-  return { meta, body };
+  return { meta, body, bodyLine };
 }
 
 /**

package/src/compiler/includes.js

@@ -1,7 +1,8 @@
 // ---------------------------------------------------------------------------
 // Includes / assets: resolve `@include` (and `@loop` data) targets to absolute
 // paths inside `site/pages` or `site/_`, register colocated `.skin`/`.js`
-// siblings, and warn when a plain `.md` file uses `.wd`-only syntax.
+// siblings, detect scoped skins and stamp their subtree HTML (`stampScope`),
+// and warn when a plain `.md` file uses `.wd`-only syntax.
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
@@ -57,6 +58,70 @@ export function scopedSkinFor(file, context) {
   return scopeInfoForSkin(candidate, context.cwd);
 }
 
+/**
+ * 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;
+}
+
 /**
  * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
  * @param {string} file

package/src/compiler/index.js

@@ -4,20 +4,32 @@
 //   context.js        shared typedefs + tiny helpers (createCompilation, at, …)
 //   interpolation.js  path/value resolution, state-key lookup, escapeHtml, literals
 //   frontmatter.js    `---` block → meta + body, inline scalar/array parsing
-//   includes.js       @include / @loop-data resolution, colocated assets, .md hints
+//   includes.js       @include / @loop-data resolution, colocated assets,
+//                     scoped-skin detection + the HTML scope stamp, .md hints
 //   predicates.js     where / when / :if / :computed expression compilers
 //   format.js         { value | pipe } format pipes + list aggregates (value layer)
 //   markdown.js       markdown-it instances + plugins + prose interpolation
+//   state.js          :state / :store / :computed / :theme + declare* helpers
+//   actions.js        the :button action parser + :button / :effect / :every
+//   fetch.js          :fetch + the shared URL scheme guard
+//   forms.js          :form + field directives + :bind / :slider
+//   media.js          :video / :audio / :embed
+//   structure.js      @include / ::: container / :if / :carousel + demo directives
+//   directives.js     barrel re-exporting the handle* family from the six above
 //   loops.js          @loop pipeline + row-template initial-paint fill
-//   directives.js     the handle* family + :button action parser + demo directives
 //   body.js           the line-based directive dispatcher (compileBody)
 //   page.js           HTML page shell, image hardening, per-file compile
 //
+// Handlers recurse into nested bodies through `ctx.compileBody` (and `@include`
+// through `ctx.compileFile`), threaded in by `compileFile` — so the graph is an
+// import-cycle-free DAG rooted at context.js.
+//
 // This barrel re-exports the public API; `src/compiler.js` re-exports from here
 // so every existing `import … from "./compiler.js"` keeps working unchanged.
 // ---------------------------------------------------------------------------
 
 export { parseFrontmatter } from "./frontmatter.js";
+export { stampScope } from "./includes.js";
 export { escapeHtml } from "./interpolation.js";
 export { loopKeyOf } from "./loops.js";
-export { compileDocument, compilePage, enhanceImages, stampScope } from "./page.js";
+export { compileDocument, compilePage, enhanceImages } from "./page.js";

package/src/compiler/loops.js

@@ -7,8 +7,7 @@
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
-import { compileBody } from "./body.js";
-import { createScope } from "./context.js";
+import { at, createScope, nestedCtx } from "./context.js";
 import { applyPipeline, stagesFromAttr } from "./format.js";
 import { resolveInclude } from "./includes.js";
 import {
@@ -213,9 +212,12 @@ function numArgAttr(arg) {
  * @param {string[]} bodyLines
  * @param {string[] | null} emptyLines
  * @param {Ctx} ctx
+ * @param {number} index 0-based line index of the `@loop` opener.
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-export function handleLoop(line, bodyLines, emptyLines, ctx) {
+export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart = 0) {
   const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)(\s+.+?)?\s*$/);
   if (!match) throw new Error(`Malformed @loop in ${ctx.file}: ${line}. ${LOOP_USAGE}`);
   const source = stripQuotes(match[1].trim());
@@ -265,10 +267,14 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     offset: clauses.offset,
     limit: clauses.limit,
     empty: emptyLines,
+    emptyStart,
     clauseRefsState: clauses.refsState,
     sortable: clauses.sortable,
     paginate: clauses.paginate
   };
+  // The loop body starts on the line after the opener; nested errors in it (and
+  // in the empty branch, via `opts.emptyStart`) report the true file line.
+  const bodyCtx = nestedCtx(ctx, index + 1);
 
   if (
     source.startsWith("/") ||
@@ -278,20 +284,28 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
   ) {
     if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
     const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
+    ctx.comp.deps.add(dataFile);
     const rows = JSON.parse(fs.readFileSync(dataFile, "utf8"));
     if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
-    return loopOverData(rows, itemName, bodyLines, ctx, opts);
+    return loopOverData(rows, itemName, bodyLines, bodyCtx, opts);
   }
 
   const resolved = lookupPath(source, ctx);
   if (resolved.found) {
     if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+    // A missing/unset field (e.g. an optional frontmatter key) is an EMPTY
+    // list, not an error — the `@empty` branch renders, matching the runtime.
+    if (resolved.value === null || resolved.value === undefined) {
+      return loopOverData([], itemName, bodyLines, bodyCtx, opts);
+    }
     if (!Array.isArray(resolved.value)) {
       throw new Error(
-        `@loop ${source} in ${ctx.file} found an in-scope value, but it is not a list`
+        `@loop ${source} in ${at(ctx, index)} found an in-scope value, but it is not a list ` +
+          `(got ${typeof resolved.value}). Use: a list value (e.g. \`tags: [a, b]\` in frontmatter) — ` +
+          `or leave the field out entirely, which loops zero rows and renders the @empty branch.`
       );
     }
-    return loopOverData(resolved.value, itemName, bodyLines, ctx, opts);
+    return loopOverData(resolved.value, itemName, bodyLines, bodyCtx, opts);
   }
 
   // A bare name OR a dotted path resolving to declared :state (e.g. team.members).
@@ -304,13 +318,16 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     if (key) {
       if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
-      return reactiveLoop(fullKey, itemName, bodyLines, ctx, opts);
+      return reactiveLoop(fullKey, itemName, bodyLines, bodyCtx, opts);
     }
     // A bare name matching a collection (any `site/pages/<name>/` subdir) resolves
     // to its entry rows at build time and static-unrolls — zero JS. This is checked
     // after state so a declared `:state` of the same name still wins.
     const collection = segs.length === 1 ? ctx.comp.collections.get(source) : undefined;
-    if (collection) return loopOverCollection(collection, source, itemName, bodyLines, ctx, opts);
+    if (collection) {
+      ctx.comp.collectionsUsed.add(source);
+      return loopOverCollection(collection, source, itemName, bodyLines, bodyCtx, opts);
+    }
     // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
     // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
     if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
@@ -320,7 +337,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
         );
       }
       if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
-      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
+      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, bodyCtx, opts);
     }
   }
 
@@ -387,7 +404,14 @@ function loopOverCollection(rows, name, itemName, bodyLines, ctx, opts) {
   // document scope). Slice this page out of the already-filtered/sorted list.
   const current = currentPage(ctx);
   const start = (current - 1) * perPage;
-  return staticUnroll(filtered.slice(start, start + perPage), itemName, bodyLines, ctx, opts.empty);
+  return staticUnroll(
+    filtered.slice(start, start + perPage),
+    itemName,
+    bodyLines,
+    ctx,
+    opts.empty,
+    opts.emptyStart
+  );
 }
 
 /**
@@ -466,7 +490,8 @@ function loopOverData(rows, itemName, bodyLines, ctx, opts) {
     itemName,
     bodyLines,
     ctx,
-    opts.empty
+    opts.empty,
+    opts.emptyStart
   );
 }
 
@@ -476,10 +501,13 @@ function loopOverData(rows, itemName, bodyLines, ctx, opts) {
  * @param {string[]} bodyLines
  * @param {Ctx} ctx
  * @param {string[] | null} [empty] Empty-branch body, rendered when 0 rows.
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-function staticUnroll(rows, itemName, bodyLines, ctx, empty = null) {
-  if (rows.length === 0 && empty) return compileBody(empty, { ...ctx, loopMeta: true });
+function staticUnroll(rows, itemName, bodyLines, ctx, empty = null, emptyStart = 0) {
+  if (rows.length === 0 && empty)
+    return ctx.compileBody(empty, { ...nestedCtx(ctx, emptyStart), loopMeta: true });
   const out = [];
   const count = rows.length;
   for (let i = 0; i < count; i++) {
@@ -495,7 +523,7 @@ function staticUnroll(rows, itemName, bodyLines, ctx, empty = null) {
       loopMeta: true,
       scope: createScope(ctx.scope, { [itemName]: rows[i], ...meta })
     };
-    out.push(compileBody(bodyLines, rowCtx));
+    out.push(ctx.compileBody(bodyLines, rowCtx));
   }
   return out.join("\n");
 }
@@ -521,7 +549,7 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     loopMeta: true,
     scope: createScope(ctx.scope)
   };
-  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+  const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
 
   const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
@@ -577,10 +605,12 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     })
     .join("");
 
-  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx);
+  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx, opts?.emptyStart);
   const initialOut =
     count === 0 && emptyLines
-      ? compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()
+      ? ctx
+          .compileBody(emptyLines, { ...nestedCtx(ctx, opts?.emptyStart ?? 0), loopMeta: true })
+          .trim()
       : initial;
 
   // `sortable` tags the region for the drag-reorder behavior (emitted only here)
@@ -615,11 +645,13 @@ function wrapRowTemplate(templateHtml) {
  * there is no empty branch). Shared by top-level and item-relative loops.
  * @param {string[] | null} emptyLines
  * @param {Ctx} ctx
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-function loopEmptyTemplate(emptyLines, ctx) {
+function loopEmptyTemplate(emptyLines, ctx, emptyStart = 0) {
   return emptyLines
-    ? `<template data-wd-loop-empty>${compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()}</template>`
+    ? `<template data-wd-loop-empty>${ctx.compileBody(emptyLines, { ...nestedCtx(ctx, emptyStart), loopMeta: true }).trim()}</template>`
     : "";
 }
 
@@ -668,11 +700,11 @@ function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
     loopMeta: true,
     scope: createScope(ctx.scope)
   };
-  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+  const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
 
   const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
-  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx);
+  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx, opts.emptyStart);
   const attrs = loopClauseAttrs({
     where: opts.where || null,
     sort: opts.sort || null,

package/src/compiler/markdown.js

@@ -1,6 +1,6 @@
 // ---------------------------------------------------------------------------
-// Markdown layer: the shared markdown-it instances (raw-HTML default + a lazy
-// `html: false` strict variant), the `wd_binding` inline plugin and `wd_attrs`
+// Markdown layer: the shared markdown-it instances (strict default + a lazy
+// `html: true` raw-HTML variant), the `wd_binding` inline plugin and `wd_attrs`
 // core plugin, and prose rendering with `{ name.path }` interpolation resolved
 // against the loop item / static scope / declared state.
 // ---------------------------------------------------------------------------
@@ -26,29 +26,33 @@ import {
 // with a known language. The callback returns escaped token HTML or `""` to let
 // markdown-it render a plain escaped `<code>` (graceful degradation). Both
 // instances share it so `html: false` pages highlight too.
-const md = new MarkdownIt({ html: true, highlight: highlightCode });
+const md = new MarkdownIt({ html: false, highlight: highlightCode });
 md.use(bindingPlugin);
 md.use(attrsPlugin);
+md.use(anchorPlugin);
 
-// Raw HTML in markdown passes through by default (a documented design choice).
-// Pages can opt out with frontmatter `html: false` for untrusted content; the
-// stricter instance is built lazily so the default path stays a single instance.
+// Raw HTML in markdown is escaped by default: a stray `<script>` or `onerror=`
+// attribute in content renders as inert text, so multi-author content (blog
+// collections, contributed docs) is stored-XSS-safe out of the box. A page
+// whose author writes their own HTML opts in with frontmatter `html: true`;
+// that instance is built lazily so the default path stays a single instance.
 /** @type {MarkdownIt | null} */
-let mdNoHtml = null;
+let mdRawHtml = null;
 /**
- * Pick the markdown-it instance for a page (raw HTML on by default, off with `html: false`).
+ * Pick the markdown-it instance for a page (raw HTML off by default, on with `html: true`).
  * @param {Meta} [meta]
  * @returns {MarkdownIt}
  */
 export function selectMd(meta) {
   // Frontmatter scalars stay strings (no coercion), so accept both forms.
-  if (meta?.html !== false && meta?.html !== "false") return md;
-  if (!mdNoHtml) {
-    mdNoHtml = new MarkdownIt({ html: false, highlight: highlightCode });
-    mdNoHtml.use(bindingPlugin);
-    mdNoHtml.use(attrsPlugin);
+  if (meta?.html !== true && meta?.html !== "true") return md;
+  if (!mdRawHtml) {
+    mdRawHtml = new MarkdownIt({ html: true, highlight: highlightCode });
+    mdRawHtml.use(bindingPlugin);
+    mdRawHtml.use(attrsPlugin);
+    mdRawHtml.use(anchorPlugin);
   }
-  return mdNoHtml;
+  return mdRawHtml;
 }
 
 /**
@@ -59,7 +63,8 @@ export function selectMd(meta) {
 export function renderProse(text, ctx) {
   text = resolveDestinationBindings(text, ctx);
   return (ctx.md ?? md).render(text, {
-    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx)
+    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx),
+    headingSlugs: ctx.comp.headingSlugs
   });
 }
 
@@ -197,6 +202,51 @@ export function attrTarget(children, i) {
   return null;
 }
 
+/**
+ * GitHub-style heading slug: lowercase, punctuation stripped (letters, numbers,
+ * whitespace, `_`, and `-` survive), each whitespace character becomes a hyphen.
+ * Punctuation-only headings fall back to `"section"` so the id is never empty.
+ * @param {string} text Plain heading text.
+ * @returns {string}
+ */
+export function slugify(text) {
+  const slug = text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]+/gu, "")
+    .replace(/\s/gu, "-");
+  return slug || "section";
+}
+
+/**
+ * markdown-it plugin (core rule): every heading gets a stable slugified `id`
+ * so long pages are linkable without any JS. Duplicate slugs dedupe with
+ * `-1`/`-2` suffixes; the counters live in `env.headingSlugs` so a page whose
+ * prose renders in chunks (directives between headings) still dedupes across
+ * the whole document. Bindings and inline HTML inside a heading contribute no
+ * slug text — only literal text and inline code do.
+ * @param {MarkdownIt} mdInstance
+ * @returns {void}
+ */
+function anchorPlugin(mdInstance) {
+  mdInstance.core.ruler.push("wd_heading_anchors", (state) => {
+    const counts = (state.env.headingSlugs ??= new Map());
+    const tokens = state.tokens;
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i].type !== "heading_open") continue;
+      let text = "";
+      for (const child of tokens[i + 1].children ?? []) {
+        if (child.type === "text" || child.type === "code_inline") text += child.content;
+      }
+      const base = slugify(text);
+      const seen = counts.get(base) ?? 0;
+      counts.set(base, seen + 1);
+      tokens[i].attrSet("id", seen ? `${base}-${seen}` : base);
+    }
+    return false;
+  });
+}
+
 /**
  * Resolve a `{ name.path }` binding to HTML: loop item span, static value, or
  * a reactive bind span. Returns null when nothing in scope matches.

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" };
+}