@zvndev/darkmown 0.20.0 → 1.1.0

package/site/pages/showcase/index.skin

@@ -0,0 +1,130 @@
+/* Showcase hub — layers on /base.wd. Gallery of the flagship apps. */
+
+main.showcase
+  max-width 1080px
+
+.sc-hero
+  padding 3.5rem 0 2.5rem
+  border-bottom 1px solid $line
+  margin-bottom 2.5rem
+
+.sc-hero h1
+  max-width 18ch
+
+.sc-hero > p
+  max-width 64ch
+  font-size 1.18rem
+  color $ink-soft
+  margin 1rem 0 1.75rem
+
+.sc-cta
+  display flex
+  flex-wrap wrap
+
+/* ── App gallery ────────────────────────────────────────────────── */
+
+.sc-apps
+  display grid
+  grid-template-columns 1fr 1fr
+  gap 1.25rem
+  margin 1rem 0 3rem
+
+@media (max-width: 760px)
+  .sc-apps
+    grid-template-columns 1fr
+
+.sc-app
+  position relative
+  padding 1.6rem 1.6rem 1.4rem
+  border 1px solid $line
+  radius $radius-lg
+  overflow hidden
+  transition transform .14s ease, box-shadow .14s ease
+
+.sc-app:hover
+  transform translateY(-3px)
+  box-shadow 0 18px 40px -22px rgba(28,24,20,.45)
+
+/* A soft accent wash per app — its identity color. */
+.sc-app::before
+  content ""
+  position absolute
+  inset 0 0 auto 0
+  height 4px
+
+.sc-folio::before
+  background #b8462e
+
+.sc-pulse::before
+  background #18b89a
+
+.sc-forge::before
+  background #6d5ae6
+
+.sc-compass::before
+  background #e0894a
+
+.sc-ledger::before
+  background #c79a3a
+
+.sc-emoji
+  font-size 2rem
+  line-height 1
+
+.sc-app h3
+  margin .6rem 0 .5rem
+  font-size 1.45rem
+
+.sc-app p
+  color $ink-soft
+  margin .4rem 0 1rem
+
+.sc-open
+  display inline-block
+  margin-top .4rem
+  font-weight 600
+  text-decoration none
+  color $accent-deep
+
+.sc-open:hover
+  text-decoration underline
+
+/* ── Weight section ─────────────────────────────────────────────── */
+
+.sc-weight
+  margin 1rem 0 3rem
+
+.sc-scale
+  list-style none
+  padding 1.25rem 1.5rem
+  margin 1.25rem 0
+
+.sc-scale li
+  padding .55rem 0
+  border-bottom 1px solid $line-soft
+  color $ink-soft
+
+.sc-scale li:last-child
+  border-bottom 0
+
+.sc-scale strong
+  color $ink
+
+.sc-scale code
+  font-size 1em
+  font-weight 700
+  color $accent-deep
+  background $accent-soft
+
+/* ── Mini demos ─────────────────────────────────────────────────── */
+
+.sc-mini
+  padding 1.1rem 1.25rem
+
+.sc-mini p
+  margin 0 0 .6rem
+  color $ink-soft
+
+.sc-mini a
+  font-weight 600
+  text-decoration none

package/site/pages/showcase/index.wd

@@ -0,0 +1,168 @@
+---
+title: Showcase — real apps built in Markdown
+description: Five complete, beautiful apps — a storefront, a live dashboard, a pricing configurator, a product-finder quiz, and a sortable expense ledger — each one a readable Markdown file. See the app, then view its source.
+image: https://darkmown.com/__wd/media/og-showcase.png
+transitions: true
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main class="wide showcase">
+
+<header class="sc-hero">
+<span class="eyebrow">Built with Darkmown</span>
+
+# Real apps. Written in Markdown.
+
+Each of these is a complete, working app — a storefront with a cart, a live status dashboard, an interactive pricing builder, a guided quiz. Open one, use it, then **view its source**. It's a Markdown file you can read top to bottom.
+
+<div class="sc-cta">
+<a class="btn primary" href="/folio/">Open the storefront</a>
+<a class="btn" href="/docs/">Read the docs</a>
+</div>
+</header>
+
+<section class="sc-apps">
+
+::: card .sc-app .sc-folio
+<span class="sc-emoji">🛍️</span>
+
+### Folio — boutique storefront
+
+A multi-page shop where the cart **persists across pages, reloads, and browser tabs**, and navigation is instant. Live search, add-to-cart, checkout.
+
+<span class="tag">static → reactive</span> <span class="tag">:store</span> <span class="tag">keyed @loop</span> <span class="tag">:form</span>
+
+[Open Folio →](/folio/){.sc-open}
+:::
+
+::: card .sc-app .sc-pulse
+<span class="sc-emoji">📈</span>
+
+### Pulse — status dashboard
+
+A service dashboard driven by `:fetch` — loading, error, and empty states, live refresh, sortable metrics, status badges. No hand-written JavaScript.
+
+<span class="tag">:fetch lifecycle</span> <span class="tag">:computed</span> <span class="tag">.class when</span> <span class="tag">sort / where</span>
+
+[Open Pulse →](/pulse/){.sc-open}
+:::
+
+::: card .sc-app .sc-forge
+<span class="sc-emoji">🧩</span>
+
+### Forge — plan configurator
+
+Build your plan: toggle features, adjust seats, watch the price recompute instantly, get smart upsell hints, then check out — the classic "this needs React" interaction.
+
+<span class="tag">:computed pricing</span> <span class="tag">:if logic</span> <span class="tag">toggles</span> <span class="tag">:form</span>
+
+[Open Forge →](/forge/){.sc-open}
+:::
+
+::: card .sc-app .sc-compass
+<span class="sc-emoji">🧭</span>
+
+### Compass — product finder
+
+A guided quiz that asks a few questions, scores your answers, and recommends a match — a branching state machine expressed entirely as `:if` steps.
+
+<span class="tag">:if state machine</span> <span class="tag">:computed</span> <span class="tag">scored flow</span>
+
+[Open Compass →](/compass/){.sc-open}
+:::
+
+::: card .sc-app .sc-ledger
+<span class="sc-emoji">📒</span>
+
+### Ledger — sortable expense table
+
+A spreadsheet-grade data table: click a header to re-sort live, filter by merchant, watch running totals recompute, flip light/dark — formatted with `| money` and `| date`, totalled with `sum()`.
+
+<span class="tag">format pipes</span> <span class="tag">aggregates</span> <span class="tag">reactive sort</span> <span class="tag">:theme</span>
+
+[Open Ledger →](/ledger/){.sc-open}
+:::
+
+</section>
+
+<section class="sc-weight">
+
+## What it costs
+
+Darkmown's whole pitch is weight. A static page ships **zero** framework JavaScript — not "a little," none. The runtime loads only when a page actually declares reactivity, and it's one shared file, CI-enforced under 8 KB gzipped.
+
+::: card .sc-scale
+- **Static Darkmown page** — `0 KB` framework JS. Forever.
+- **Reactive Darkmown page** — one shared `~7.4 KB` gzipped runtime, no per-component bundles.
+- **A typical SPA** — ships a framework runtime in the **~15–60 KB** gzipped range *before* your app code, on every page (Alpine ~15 KB, Vue ~18 KB runtime, React 19 ~59 KB).
+:::
+
+The two Darkmown numbers above are measured on every commit; the runtime budget fails CI if it crosses 8 KB. The comparison figures are representative min+gzip runtime sizes (June 2026) — the point isn't "smallest" (Preact is smaller), it's **nothing at all until you ask for it.**
+
+</section>
+
+<section class="sc-more">
+
+## The directive demos
+
+Prefer to see each feature in isolation? These pages tour the building blocks the apps are made of:
+
+<div class="grid auto">
+
+::: card .sc-mini
+**Reactive** — state, keyed loops, scoped sections.
+
+[Open →](/reactive/)
+:::
+
+::: card .sc-mini
+**Loops** — sort, paging, `@empty`, nesting.
+
+[Open →](/loops/)
+:::
+
+::: card .sc-mini
+**Store** — durable, cross-tab global state.
+
+[Open →](/store/)
+:::
+
+::: card .sc-mini
+**Theme** — zero-JS OS dark mode from a skin.
+
+[Open →](/theme/)
+:::
+
+::: card .sc-mini
+**Swiper** — a draggable carousel via the escape hatch.
+
+[Open →](/carousel/)
+:::
+
+::: card .sc-mini
+**Media** — `:video`, `:audio`, `:embed`, zero JS.
+
+[Open →](/media/)
+:::
+
+::: card .sc-mini
+**Data & Forms** — fetch lifecycle, server round-trips.
+
+[Open →](/data/)
+:::
+
+::: card .sc-mini
+**Plain Markdown** — a `.md` page, directives inert.
+
+[Open →](/markdown/)
+:::
+
+</div>
+
+</section>
+
+</main>
+
+@include /footer.wd

package/src/compiler/body.js

@@ -15,16 +15,20 @@ import {
   handleComputed,
   handleContainer,
   handleEffect,
+  handleEmbed,
+  handleEvery,
   handleFetch,
   handleForm,
   handleIf,
   handleInclude,
   handleInput,
+  handleMedia,
   handleSelect,
   handleState,
   handleStore,
   handleSubmit,
   handleTextarea,
+  handleTheme,
   renderDemoDirective
 } from "./directives.js";
 import { handleLoop } from "./loops.js";
@@ -94,12 +98,16 @@ export function compileBody(lines, ctx) {
     }
     if (/^:state\s/.test(line)) {
       flush();
-      out.push(handleState(line, ctx, i));
+      const v = joinValueDirective(lines, i);
+      out.push(handleState(v.line, ctx, i));
+      i = v.end;
       continue;
     }
     if (/^:store\s/.test(line)) {
       flush();
-      out.push(handleStore(line, ctx, i));
+      const v = joinValueDirective(lines, i);
+      out.push(handleStore(v.line, ctx, i));
+      i = v.end;
       continue;
     }
     if (/^:fetch\s/.test(line)) {
@@ -117,6 +125,29 @@ export function compileBody(lines, ctx) {
       out.push(handleEffect(line, ctx, i));
       continue;
     }
+    if (/^:every\s/.test(line)) {
+      flush();
+      out.push(handleEvery(line, ctx, i));
+      continue;
+    }
+    if (/^:theme(?:\s|$)/.test(line)) {
+      flush();
+      const v = joinValueDirective(lines, i);
+      out.push(handleTheme(v.line, ctx, i));
+      i = v.end;
+      continue;
+    }
+    const media = line.match(/^:(video|audio)\s/);
+    if (media) {
+      flush();
+      out.push(handleMedia(line, /** @type {"video" | "audio"} */ (media[1]), ctx, i));
+      continue;
+    }
+    if (/^:embed\s/.test(line)) {
+      flush();
+      out.push(handleEmbed(line, ctx, i));
+      continue;
+    }
     if (/^:form\s/.test(line)) {
       flush();
       const block = scanBlock(lines, i, /^:form\s/, ":endform", ctx.file);
@@ -217,7 +248,7 @@ export function compileBody(lines, ctx) {
 // narrow (lowercase token + boundary; emoji shortcodes, times, and `@user`
 // followed by punctuation do not match).
 const KNOWN_DIRECTIVE =
-  /^(?:@(?:include|loop|empty|endloop)|:(?:state|store|fetch|computed|effect|form|endform|input|textarea|select|checkbox|radio|bind|submit|button|if|endif|else|try|note|sprint))(?:\s|$)/;
+  /^(?:@(?:include|loop|empty|endloop)|:(?:state|store|fetch|computed|effect|every|theme|video|audio|embed|form|endform|input|textarea|select|checkbox|radio|bind|submit|button|if|endif|else|try|note|sprint))(?:\s|$)/;
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -236,6 +267,61 @@ function warnUnknownDirective(line, ctx) {
   }
 }
 
+/**
+ * Net bracket depth of a string, ignoring brackets inside JSON string literals.
+ * Positive means more openers (`[`/`{`) than closers — the value is unbalanced.
+ * @param {string} s
+ * @returns {number}
+ */
+function bracketDepth(s) {
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (const ch of s) {
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === "[" || ch === "{") depth++;
+    else if (ch === "]" || ch === "}") depth--;
+  }
+  return depth;
+}
+
+/**
+ * `:state`/`:store`/`:theme` take a single-line value, but a JSON array/object
+ * seed reads far better across several lines. When the value after `=` opens an
+ * unbalanced `[`/`{` on the directive line, gather the contiguous continuation
+ * lines (stopping at a blank line, which delimits the literal) until the brackets
+ * balance, then collapse them into one physical line the existing single-line
+ * handler parses unchanged — JSON ignores the inter-token whitespace. A literal
+ * that never balances falls through as-is, so `parseStateValue` reports it.
+ * @param {string[]} lines
+ * @param {number} start Index of the directive line.
+ * @returns {{ line: string, end: number }} `end` = last consumed line index.
+ */
+function joinValueDirective(lines, start) {
+  const opener = lines[start];
+  const eq = opener.indexOf("=");
+  if (eq === -1) return { line: opener, end: start };
+  const value = opener.slice(eq + 1);
+  // Only a JSON array/object literal can span lines; bare scalars/strings cannot.
+  if (!/^\s*[[{]/.test(value)) return { line: opener, end: start };
+  let depth = bracketDepth(value);
+  if (depth <= 0) return { line: opener, end: start }; // already balanced on one line
+  const parts = [opener];
+  let i = start;
+  while (depth > 0 && i + 1 < lines.length && lines[i + 1].trim() !== "") {
+    i++;
+    parts.push(lines[i]);
+    depth += bracketDepth(lines[i]);
+  }
+  return { line: parts.join(" "), end: i };
+}
+
 /**
  * Capture lines from an opener until a matching close token, honoring nesting and fences.
  * @param {string[]} lines

package/src/compiler/context.js

@@ -97,7 +97,7 @@
  * Loop clause configuration shared by the static and reactive paths.
  * @typedef {object} LoopOpts
  * @property {Predicate | null} where
- * @property {{ key: string, dir: string } | null} sort
+ * @property {{ key: string, keyKind: "literal" | "key", dir: string, dirKind: "literal" | "key" } | null} sort A literal item field + asc/desc, or a `:state`/`:store` key for either (reactive, clickable-header sort).
  * @property {boolean} reverse
  * @property {NumArg | null} offset
  * @property {NumArg | null} limit

package/src/compiler/directives.js

@@ -11,6 +11,7 @@
 
 import { compileBody } from "./body.js";
 import { at, createScope, LOOP_META } from "./context.js";
+import { FORMATTERS } from "./format.js";
 import { resolveInclude } from "./includes.js";
 import {
   escapeHtml,
@@ -174,7 +175,7 @@ export function handleContainer(header, bodyLines, ctx, index) {
 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.file, index)}: ${line}`);
-  const value = parseStateValue(match[2]);
+  const value = parseStateValue(match[2], at(ctx.file, 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>`;
@@ -214,7 +215,7 @@ export function handleStore(line, ctx, index) {
     throw new Error(
       `Malformed :store in ${at(ctx.file, index)}: ${line}. Use: :store name = value [ephemeral]`
     );
-  const value = parseStateValue(match[2]);
+  const value = parseStateValue(match[2], at(ctx.file, 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>`;
@@ -411,7 +412,14 @@ export function handleComputed(line, ctx, index) {
   try {
     /** @param {string} key @param {string} [path] */
     const read = (key, path) => getPath(ctx.comp.state.get(key), path ? path.split(".") : []);
-    initial = new Function("S", `return (${expr});`)(read);
+    // 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.`
@@ -811,6 +819,194 @@ export function handleEffect(line, ctx, index) {
   return `<script type="application/json" data-wd-effect>${safeScriptJson({ watch, actions })}</script>`;
 }
 
+const EVERY_USE =
+  "Use: :every <duration> -> action[; action…] — duration like 5s, 500ms, or 2m (actions use the :button vocabulary).";
+
+/**
+ * Parse a duration token into milliseconds: `<int>[ms|s|m]`, defaulting to ms.
+ * @param {string} raw
+ * @returns {number | null}
+ */
+function parseDuration(raw) {
+  const match = raw.trim().match(/^(\d+)(ms|s|m)?$/);
+  if (!match) return null;
+  const n = Number(match[1]);
+  return match[2] === "s" ? n * 1000 : match[2] === "m" ? n * 60000 : n;
+}
+
+/**
+ * Parse `:every <duration> -> <actions>` into a marker the runtime drives on a
+ * timer: every `<duration>` it runs `<actions>` (the same `:button` vocabulary,
+ * `;`-chained), and the interval auto-pauses while the tab is hidden. The one time
+ * primitive — behind live polling (`:every 5s -> board refetch`), clocks and
+ * countdowns (`:every 1s -> seconds++`), and slideshow autoplay (`:every 4s -> slide++`).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEvery(line, ctx, index) {
+  const match = line.match(/^:every\s+(\S+)\s*->\s*(.+)$/);
+  if (!match) throw new Error(`Malformed :every in ${at(ctx.file, index)}: ${line}. ${EVERY_USE}`);
+  const ms = parseDuration(match[1]);
+  if (ms == null || ms <= 0) {
+    throw new Error(
+      `:every duration "${match[1]}" is not valid in ${at(ctx.file, index)}. ${EVERY_USE}`
+    );
+  }
+  ctx.comp.assets.runtime = true;
+  const action = parseAction(match[2], ctx);
+  const actions = Array.isArray(action) ? action : [action];
+  return `<script type="application/json" data-wd-every>${safeScriptJson({ ms, actions })}</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.file, index)}: ${line}. Use: :theme  (or  :theme name = "auto")`
+    );
+  }
+  const name = match[1] || "theme";
+  const seed = match[2] != null ? parseStateValue(match[2], at(ctx.file, 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>`;
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+/** @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.file, 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.file, index)}`);
+      flags.add(token[3]);
+    } else {
+      if (!spec.attrs.includes(token[1]))
+        throw new Error(`Unknown :${kind} attribute "${token[1]}" in ${at(ctx.file, 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.file, 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.file, 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" };
+}
+
 /**
  * @param {string} line
  * @param {string[]} truthyLines