@zvndev/darkmown 2.9.0 → 2.10.1

package/src/compiler/media.js

@@ -175,6 +175,7 @@ export function handleEmbed(line, ctx, index) {
   const sizing = embedSizing(attrs, ctx, index);
   const allow = embedAllow(attrs, ctx, index);
   const { url, label } = resolveEmbed(raw, ctx);
+  recordEmbedHost(ctx, url);
   const title = attrs.get("title") || "";
   const iframe =
     `<iframe src="${escapeHtml(url)}" title="${escapeHtml(title || label)}" loading="lazy" ` +
@@ -237,6 +238,30 @@ function embedAllow(attrs, ctx, index) {
   return tokens.join("; ");
 }
 
+/**
+ * Record the frame source the emitted iframe actually loads, so the builder can
+ * union it into this route's CSP `frame-src`. An absolute http(s) URL contributes
+ * its origin; a relative URL frames the page's own origin, so it contributes
+ * `'self'`. A `{ state }`-driven URL is unknowable at compile time and records
+ * nothing (widening that policy is the app's deploy-config decision, exactly
+ * like a remote `:fetch` target widening `connect-src`).
+ * @param {Ctx} ctx
+ * @param {string} url The FINAL iframe src (post YouTube/Vimeo rewrite).
+ * @returns {void}
+ */
+function recordEmbedHost(ctx, url) {
+  if (url.startsWith("{")) return;
+  if (!/^https?:\/\//i.test(url)) {
+    ctx.comp.assets.embedHosts.add("'self'");
+    return;
+  }
+  try {
+    ctx.comp.assets.embedHosts.add(new URL(url).origin);
+  } catch {
+    /* a malformed-but-scheme-valid URL paints as-is; nothing to authorize */
+  }
+}
+
 /**
  * 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.

package/src/compiler/page.js

@@ -14,6 +14,7 @@ import { parseFrontmatter, resolveSharedSkins, warnLikelyFrontmatter } from "./f
 import { imageSize } from "./image-size.js";
 import {
   collectColocatedAssets,
+  isAllowedInclude,
   scanMarkdownHints,
   scopedSkinFor,
   scopeInfoForSkin,
@@ -408,6 +409,10 @@ function srcOf(tag) {
  * Read an image's intrinsic dimensions from disk, or null when the src is
  * remote/relative/unreadable. Resolution mirrors the asset emit: `/__wd/media/x`
  * comes from the shelf (`site/_`), other absolute paths from `site/pages`.
+ * Containment mirrors the `@include` sandbox ({@link isAllowedInclude}): a src
+ * that resolves OUTSIDE those roots — `![x](/../../anywhere.png)`, or a symlink
+ * pointing out — is treated exactly like a missing image (no dimensions), never
+ * read.
  * @param {string} src
  * @param {Paths} paths
  * @param {import("./reader.js").Reader} reader
@@ -423,6 +428,7 @@ function measureImage(src, paths, reader) {
   } else {
     return null; // page-relative: the source directory is lost after assembly
   }
+  if (!isAllowedInclude(filePath, paths, reader)) return null;
   try {
     // `imageSize` itself never throws (an unsupported or malformed image is just
     // null); the try/catch is for the read, which does throw on a missing file.

package/src/compiler/state.js

@@ -174,6 +174,79 @@ function rejectStateSeed(value, raw, directive, ctx, index) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// A SECRET-SHAPED SEED IS A HINT, NEVER AN ERROR.
+//
+// Every `:state`/`:store` seed is stored verbatim and inlined into the public
+// HTML as a JSON script tag — that is the design, and it means a seed that is
+// really an API key or token is published to every reader of the page. The
+// documented pattern is to seed empty and fill from an api/ endpoint at
+// runtime, but nothing stopped an author from pasting the key itself. This
+// check is a heuristic over string seeds (and string values nested in
+// array/object seeds), pushed onto the same `comp.warnings` channel as the
+// other build hints: it can never fail a build, because a false positive must
+// never break one, and it fires at most once per declaration.
+//
+// The shapes are deliberately tight — false positives are the enemy:
+//
+// - Known key prefixes (`sk-`, `ghp_`, `xoxb-`, `AKIA`, …) followed by a real
+//   token body, and the `-----BEGIN` private-key header.
+// - A JWT: three base64url segments joined by dots, opening with `eyJ` (the
+//   base64 of `{"` — requiring it keeps dotted prose quiet).
+// - A long unbroken token: 32+ chars from the base64/base64url alphabet with
+//   no spaces, requiring BOTH cases and a digit. Requiring the case mix keeps
+//   kebab-case slugs, hex hashes, and UUIDs (all lowercase) silent, and the
+//   charset excludes `:`, `.`, and space, so URLs, file paths, and prose
+//   never match.
+// ---------------------------------------------------------------------------
+const SECRET_PREFIX = /^(?:sk-|sk_live_|sk_test_|ghp_|gho_|xoxb-|xoxp-|AKIA)/;
+const SECRET_TOKEN_BODY = /^[A-Za-z0-9_-]{8,}$/;
+const JWT_SHAPE = /^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/;
+const LONG_TOKEN_SHAPE = /^[A-Za-z0-9/_+=-]{32,}$/;
+
+/**
+ * Test one string for the secret shapes above.
+ * @param {string} text
+ * @returns {boolean}
+ */
+function looksLikeSecret(text) {
+  if (text.startsWith("-----BEGIN")) return true;
+  const prefixed = text.match(SECRET_PREFIX);
+  if (prefixed && SECRET_TOKEN_BODY.test(text.slice(prefixed[0].length))) return true;
+  if (JWT_SHAPE.test(text)) return true;
+  return LONG_TOKEN_SHAPE.test(text) && /[a-z]/.test(text) && /[A-Z]/.test(text) && /\d/.test(text);
+}
+
+/**
+ * Walk a parsed seed for a secret-shaped string: the seed itself, or any
+ * string value nested in its arrays/objects.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function seedContainsSecret(value) {
+  if (typeof value === "string") return looksLikeSecret(value);
+  if (Array.isArray(value)) return value.some(seedContainsSecret);
+  if (value && typeof value === "object") return Object.values(value).some(seedContainsSecret);
+  return false;
+}
+
+/**
+ * Push the secret-seed hint when a `:state`/`:store` seed carries one.
+ * @param {unknown} value The parsed seed.
+ * @param {string} name The declared name, for the message.
+ * @param {string} directive `:state` or `:store`, for the message.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line`.
+ * @returns {void}
+ */
+function warnSecretSeed(value, name, directive, ctx, index) {
+  if (!seedContainsSecret(value)) return;
+  ctx.comp.warnings.push(
+    `${at(ctx, index)}: ${directive} "${name}" seed looks like a secret — it will be inlined into public HTML. ` +
+      `Seed empty and fill it from an api/ endpoint at runtime.`
+  );
+}
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -195,6 +268,7 @@ export function handleState(line, ctx, index) {
   const flags = parseModifiers(match[3], ":state", ctx, index);
   const value = parseStateValue(match[2], at(ctx, index));
   rejectStateSeed(value, match[2], ":state", ctx, index);
+  warnSecretSeed(value, match[1], ":state", ctx, index);
   const key = declareState(match[1], value, ctx);
   recordSymbol(ctx, index, { kind: "state", name: key, detail: `${key} = ${match[2].trim()}` });
   const persistAttr = flags.persist ? ` data-wd-persist="${escapeHtml(key)}"` : "";
@@ -263,6 +337,7 @@ export function handleStore(line, ctx, index) {
   const flags = parseModifiers(match[3], ":store", ctx, index);
   const value = parseStateValue(match[2], at(ctx, index));
   rejectStateSeed(value, match[2], ":store", ctx, index);
+  warnSecretSeed(value, match[1], ":store", ctx, index);
   const name = declareStore(match[1], value, ctx);
   recordSymbol(ctx, index, { kind: "store", name, detail: `${name} = ${match[2].trim()}` });
   const ephemeral = flags.ephemeral ? " data-wd-store-ephemeral" : "";

package/src/compiler/structure.js

@@ -11,8 +11,25 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, createScope, LOOP_META, lineOf, nestedCtx, recordSymbol, wdError } from "./context.js";
-import { resolveInclude, scopedSkinFor, stampScope } from "./includes.js";
+import path from "node:path";
+import {
+  at,
+  createScope,
+  LOOP_META,
+  lineOf,
+  nestedCtx,
+  normalizeNewlines,
+  recordSymbol,
+  wdError
+} from "./context.js";
+import { parseFrontmatter } from "./frontmatter.js";
+import {
+  CHILDREN_SLOT_LINE,
+  INCLUDE_CHILDREN,
+  resolveInclude,
+  scopedSkinFor,
+  stampScope
+} from "./includes.js";
 import {
   escapeHtml,
   getPath,
@@ -146,12 +163,31 @@ export function a11yAttrHtml(attrs) {
 }
 
 /**
+ * Compile an `@include` line — inline form (`@include /nav.wd`) or block form
+ * (`@include /card.wd … @endinclude`, with `childrenLines` holding the lines
+ * between opener and closer, captured by {@link scanIncludeBlock}).
+ *
+ * Block form is compile-time macro expansion and nothing more: the children
+ * lines compile in the CALLER's context (its scope, its `:state`, its loop
+ * item when the call sits in a `@loop` body) BEFORE the target compiles, and
+ * the resulting HTML rides into the include's scope under
+ * {@link INCLUDE_CHILDREN}, where the body parser splices it at each
+ * `{ children }` slot line. No runtime marker, no reactivity of its own.
+ * Children compile ONCE even when the include places the slot twice, so state
+ * a child line declares is declared once in the caller.
+ *
+ * The include file's own frontmatter may declare `defaults: [name="value" …]`
+ * fallback values for `with` arguments (see {@link parseIncludeDefaults}); a
+ * caller-provided argument always wins over a default, and an argument with
+ * neither keeps the literal-braces behavior.
  * @param {string} line
  * @param {Ctx} ctx
  * @param {number} index 0-based line index for `file:line` errors.
+ * @param {string[]} [childrenLines] Lines between `@include` and `@endinclude`
+ *   for the block form; undefined for the inline form.
  * @returns {string}
  */
-export function handleInclude(line, ctx, index) {
+export function handleInclude(line, ctx, index, childrenLines) {
   const match = line.match(/^@include\s+(\S+)(?:\s+with\s+(.+))?$/);
   if (!match)
     throw wdError(`Malformed @include in ${at(ctx, index)}: ${line}. ${INCLUDE_USE}`, {
@@ -171,7 +207,39 @@ export function handleInclude(line, ctx, index) {
   );
   const args = parseIncludeArgs(match[2] || "", ctx);
   recordSymbol(ctx, index, { kind: "include", name: match[1], detail: `@include ${match[1]}` });
-  const childScope = createScope(ctx.scope, args);
+  const component = includeComponentInfo(target, ctx);
+  let childrenHtml = "";
+  if (childrenLines) {
+    // One nesting level is the contract: a block include's children (or an
+    // include file's own body) may hold one block include, no more. Children
+    // depth travels on the ctx (children compile in the caller's context);
+    // include-FILE depth is the include stack's length (page = 1, its include
+    // = 2, an include's include = 3 — too deep for a block).
+    if ((ctx.includeBlockDepth ?? 0) >= 2 || ctx.stack.length > 2) {
+      const hint = `${INCLUDE_BLOCK_USE}`;
+      throw wdError(
+        `Block-form @include nested too deep in ${at(ctx, index)}: ${line}. A children block or an include body may hold ONE level of @include … @endinclude. Use: ${hint}`,
+        { code: "WD616", file: ctx.file, line: lineOf(ctx, index), hint, example: INCLUDE_EXAMPLE }
+      );
+    }
+    childrenHtml = ctx.compileBody(childrenLines, {
+      ...nestedCtx(ctx, index + 1),
+      includeBlockDepth: (ctx.includeBlockDepth ?? 0) + 1
+    });
+    if (childrenHtml.trim() && !component.usesChildren) {
+      ctx.comp.warnings.push(
+        `${at(ctx, index)}: the @include block for "${match[1]}" passes children, but ${target} never uses a { children } line, so the content is dropped. Add { children } where the slot content should appear, or drop the block.`
+      );
+    }
+  }
+  // Caller args sit over defaults (the caller always wins); the children slot
+  // sits alongside them. An inline call still sets the slot (""), so a nested
+  // include never sees an OUTER include's children through the scope chain.
+  const childScope = createScope(ctx.scope, {
+    ...component.defaults,
+    ...args,
+    [INCLUDE_CHILDREN]: childrenHtml
+  });
   // Thread the reactive-nesting depth (and the enclosing loop opener, so a depth
   // error names the right opener) into the include, exactly as `loopItem` is —
   // otherwise a reactive @loop inside the include would start counting from zero
@@ -196,6 +264,206 @@ export function handleInclude(line, ctx, index) {
   return scopedSkin && scopedSkin.scoped ? stampScope(child.html, scopedSkin.scopeId) : child.html;
 }
 
+const INCLUDE_BLOCK_USE = `@include /partial.wd [with key="value"] … @endinclude — e.g. @include /card.wd with title="Pricing"`;
+
+/**
+ * Scan ahead from an `@include` opener for the `@endinclude` that pairs with
+ * it. Pairing is nearest-opener-first: a nested `@include` line pushes, an
+ * `@endinclude` line pops the most recent unclosed opener, and the first
+ * `@endinclude` found with nothing on the stack belongs to THIS opener — so
+ * nested blocks pair correctly, and an inline `@include` earlier in the file
+ * than a block (the common nav-include-then-card-block page) is unaffected.
+ * Fenced code is skipped, exactly as in the other block scanners.
+ *
+ * Returns null when no closer pairs — the include is the INLINE form, which
+ * stays legal (backward compatible): an opener that never pairs is an inline
+ * include followed by ordinary prose, and the two are indistinguishable, so
+ * there is deliberately no "unclosed block" error.
+ * @param {string[]} lines The current body slice.
+ * @param {number} start 0-based index of the `@include` opener line.
+ * @returns {{ body: string[], end: number } | null} The children lines and the
+ *   closer's 0-based index, or null for the inline form.
+ */
+export function scanIncludeBlock(lines, start) {
+  /** @type {number[]} */
+  const stack = [];
+  /** @type {string | null} */
+  let fence = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = line.match(/^(```+|~~~+)/);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length)
+        fence = null;
+      continue;
+    }
+    if (fenceMatch) {
+      fence = fenceMatch[1];
+      continue;
+    }
+    if (/^@include\s/.test(line)) {
+      stack.push(i);
+      continue;
+    }
+    if (line.trim() === "@endinclude") {
+      if (stack.length === 0) return { body: lines.slice(start + 1, i), end: i };
+      stack.pop();
+    }
+  }
+  return null;
+}
+
+/**
+ * `@endinclude` reached the body dispatcher, meaning no `@include` opener
+ * claimed it — the one-closer-too-many case (a typo'd closer, or a nested
+ * block attempted inside a children block, where the inner opener already
+ * took the closer the author meant for the outer one). Always throws.
+ * @param {string} line The offending line, for the message.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line`.
+ * @returns {never}
+ */
+export function strayEndinclude(line, ctx, index) {
+  const hint = INCLUDE_BLOCK_USE;
+  throw wdError(
+    `Stray "${line.trim()}" with no unpaired @include before it in ${at(ctx, index)}. @endinclude pairs with the nearest preceding unpaired @include. Use: ${hint}`,
+    { code: "WD614", file: ctx.file, line: lineOf(ctx, index), hint, example: INCLUDE_EXAMPLE }
+  );
+}
+
+/**
+ * The component-facing facts about an include target's source: its declared
+ * argument `defaults` (frontmatter) and whether its body ever places the
+ * `{ children }` slot. Reads the target once, ahead of the compileFile read.
+ * @param {string} target Absolute include path.
+ * @param {Ctx} ctx
+ * @returns {{ defaults: Record<string, string>, usesChildren: boolean }}
+ */
+function includeComponentInfo(target, ctx) {
+  const raw = normalizeNewlines(ctx.comp.reader.readText(target));
+  const { meta, body } = parseFrontmatter(raw, target);
+  return {
+    defaults: parseIncludeDefaults(meta, raw, target),
+    // A `.md` include never runs the directive/interpolation layer, so a
+    // `{ children }` line in one is inert text, not a slot: the drop-hint must
+    // treat the file as slotless.
+    usesChildren: path.extname(target) !== ".md" && usesChildrenSlot(body)
+  };
+}
+
+/**
+ * Parse an include file's `defaults:` frontmatter: an inline array of
+ * `name="value"` entries, e.g. `defaults: [title="Untitled", cta="Learn more"]`.
+ * Values are STRINGS (frontmatter is string-typed) and apply only inside that
+ * include; a caller-provided `with` argument always wins.
+ *
+ * The raw `defaults:` line is split quote-aware (so a value may contain a
+ * comma) rather than trusting the generic frontmatter array items, whose
+ * splitter only honors item-leading quotes. Reached only when
+ * `parseFrontmatter` already produced an array for the key, so the source
+ * line and its `[…]` shape are guaranteed present.
+ * @param {import("./context.js").Meta} meta The include file's frontmatter.
+ * @param {string} raw The include file's full (newline-normalized) source.
+ * @param {string} target Absolute include path, for error messages.
+ * @returns {Record<string, string>}
+ */
+function parseIncludeDefaults(meta, raw, target) {
+  if (meta.defaults === undefined) return {};
+  const use = 'an inline array of name="value" entries — e.g. defaults: [title="Untitled"]';
+  if (!Array.isArray(meta.defaults)) {
+    throw wdError(`Invalid defaults frontmatter in ${target}: the value must be ${use}.`, {
+      code: "WD613",
+      file: target,
+      hint: use,
+      example: 'defaults: [title="Untitled"]'
+    });
+  }
+  const lines = raw.split("\n");
+  const lineIndex = lines.findIndex((l) => /^defaults\s*:/.test(l));
+  const valueText = lines[lineIndex].replace(/^defaults\s*:\s*/, "").trim();
+  const inner = valueText.slice(1, -1); // strip the […] the array shape guarantees
+  /** @type {Record<string, string>} */
+  const defaults = {};
+  for (const entry of splitDefaultEntries(inner)) {
+    const match =
+      entry.match(/^([A-Za-z0-9_-]+)="([^"]*)"$/) ?? entry.match(/^([A-Za-z0-9_-]+)='([^']*)'$/);
+    if (!match) {
+      throw wdError(
+        `Invalid defaults frontmatter in ${target}:${lineIndex + 1}: entry "${entry}" must look like name="value". Use: ${use}.`,
+        {
+          code: "WD613",
+          file: target,
+          line: lineIndex + 1,
+          hint: use,
+          example: 'defaults: [title="Untitled"]'
+        }
+      );
+    }
+    defaults[match[1]] = match[2];
+  }
+  return defaults;
+}
+
+/**
+ * Split the inside of a `defaults: […]` array on top-level commas, honoring
+ * quotes ANYWHERE in an entry (the value follows `name=`, so the quote is not
+ * entry-leading and the generic frontmatter splitter would break on a comma
+ * inside it). An unterminated quote leaves its entry malformed, which the
+ * caller's entry check rejects.
+ * @param {string} inner
+ * @returns {string[]} Trimmed, non-empty entries.
+ */
+function splitDefaultEntries(inner) {
+  /** @type {string[]} */
+  const entries = [];
+  let buf = "";
+  /** @type {string | null} */
+  let quote = null;
+  for (const ch of inner) {
+    if (quote) {
+      buf += ch;
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      buf += ch;
+    } else if (ch === ",") {
+      entries.push(buf);
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  entries.push(buf);
+  return entries.map((entry) => entry.trim()).filter(Boolean);
+}
+
+/**
+ * Whether an include body ever places the `{ children }` slot: a standalone
+ * slot-marker line outside fenced code. Fence-aware so a documentation fence
+ * demonstrating `{ children }` does not count (its content is literal text —
+ * the slot really is unused there, and the drop-hint should still fire).
+ * @param {string} body The include file's post-frontmatter body.
+ * @returns {boolean}
+ */
+function usesChildrenSlot(body) {
+  /** @type {string | null} */
+  let fence = null;
+  for (const line of body.split("\n")) {
+    const fenceMatch = line.match(/^(```+|~~~+)/);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length)
+        fence = null;
+      continue;
+    }
+    if (fenceMatch) {
+      fence = fenceMatch[1];
+      continue;
+    }
+    if (CHILDREN_SLOT_LINE.test(line)) return true;
+  }
+  return false;
+}
+
 /**
  * @param {string} raw
  * @param {Ctx} ctx

package/src/errors.js

@@ -76,6 +76,7 @@ import {
   IF_EXAMPLE,
   INCLUDE_EXAMPLE
 } from "./compiler/structure.js";
+import { FONT_FACE_EXAMPLE, KEYFRAMES_EXAMPLE } from "./skin.js";
 
 /**
  * One subsystem block of the numbering scheme.
@@ -94,8 +95,9 @@ import {
  * @property {string} title Short name for the mistake.
  * @property {string} cause What the author wrote that triggers it.
  * @property {string} fix The corrective action, in one line.
- * @property {string} [example] A concrete, compilable line, sourced from the
- *   compiler's own `*_EXAMPLE` constants.
+ * @property {string} [example] A concrete, compilable line (or, for block
+ *   constructs like the `.skin` at-rules, a minimal compilable block), sourced
+ *   from the compiler's own `*_EXAMPLE` constants.
  */
 
 /** The subsystem blocks, in code order. */
@@ -1057,6 +1059,30 @@ const ENTRIES = [
       "An `@include` chain reaches a file that is already being compiled, so the compile would never terminate.",
     fix: "Break the loop: remove the `@include` that points back, or move the shared content into a third file both sides include."
   },
+  {
+    code: "WD613",
+    title: "Invalid include `defaults`",
+    cause:
+      'An include file\'s `defaults:` frontmatter is not an inline array of `name="value"` entries.',
+    fix: 'Write an inline array of quoted entries, e.g. `defaults: [title="Untitled"]`. Values are strings; a caller-provided `with` argument always wins over a default.',
+    example: INCLUDE_EXAMPLE
+  },
+  {
+    code: "WD614",
+    title: "Stray `@endinclude`",
+    cause:
+      "An `@endinclude` has no unpaired `@include` before it — the closer pairs with the nearest preceding unpaired opener, and every opener in range already paired.",
+    fix: "Remove the extra closer, or open a block above it: `@include /partial.wd`, the children lines, then `@endinclude`.",
+    example: INCLUDE_EXAMPLE
+  },
+  {
+    code: "WD616",
+    title: "Include block nested too deep",
+    cause:
+      "A block-form `@include … @endinclude` sits inside another include block's children or inside a nested include's own body, past the one supported level.",
+    fix: "Keep one level: move the inner block into the include's own file, or use the inline form `@include /partial.wd`.",
+    example: INCLUDE_EXAMPLE
+  },
   {
     code: "WD650",
     title: "Attribute is not on the accessibility whitelist",
@@ -1143,6 +1169,36 @@ const ENTRIES = [
     cause: "A top-level `page`/`body`/`html`/`*`/`::selection` selector escapes the scope.",
     fix: "Move page-level styles to a global (non-scoped) skin."
   },
+  {
+    code: "WD804",
+    title: "Malformed `@font-face` block",
+    cause:
+      "`@font-face` was given a name, holds a nested block, or has no descriptors — it takes plain `prop value` declaration lines only.",
+    fix: "Write a bare `@font-face` line and indent each descriptor beneath it.",
+    example: FONT_FACE_EXAMPLE
+  },
+  {
+    code: "WD805",
+    title: "Invalid `@keyframes` name",
+    cause: "The name after `@keyframes` is missing or is not a plain CSS identifier.",
+    fix: "Name the animation with a plain identifier, e.g. `@keyframes fade-in`.",
+    example: KEYFRAMES_EXAMPLE
+  },
+  {
+    code: "WD806",
+    title: "Invalid keyframe selector",
+    cause: "A child of `@keyframes` is not `from`, `to`, or a percentage.",
+    fix: "Use `from`, `to`, a percentage (`50%`), or a comma list of them (`50%, 75%`).",
+    example: KEYFRAMES_EXAMPLE
+  },
+  {
+    code: "WD807",
+    title: "Malformed `@keyframes` body",
+    cause:
+      "A keyframe's declarations nest deeper, a keyframe selector has no declarations, or the block has no keyframe selectors at all.",
+    fix: "Give each keyframe selector a flat list of declarations indented one level beneath it.",
+    example: KEYFRAMES_EXAMPLE
+  },
 
   // --- WD9xx: project, routing, CLI ----------------------------------------
   {
@@ -1187,6 +1243,13 @@ const ENTRIES = [
     cause: "The home page's `ai_crawlers:` is neither `allow` nor `deny`.",
     fix: "Write `ai_crawlers: allow` or `ai_crawlers: deny` (absent means allow)."
   },
+  {
+    code: "WD908",
+    title: "Unsafe route name",
+    cause:
+      "A page filename produced a route containing whitespace or control characters, which would corrupt generated config files (dist/_headers, llms.txt).",
+    fix: "Rename the file using only letters, digits, dashes, and underscores."
+  },
   {
     code: "WD950",
     title: "Invalid `rss_limit`",
@@ -1272,7 +1335,15 @@ export function errorsMarkdown() {
     out.push("| Code | Error | Cause | Fix | Example |");
     out.push("| --- | --- | --- | --- | --- |");
     for (const row of rows) {
-      const example = row.example ? `\`${escapeCell(row.example)}\`` : "";
+      // A multi-line example (the `.skin` at-rule blocks are block constructs)
+      // becomes one code span per line joined by <br>, keeping the table row
+      // on a single markdown line.
+      const example = row.example
+        ? row.example
+            .split("\n")
+            .map((line) => `\`${escapeCell(line)}\``)
+            .join("<br>")
+        : "";
       out.push(
         `| \`${row.code}\` | ${escapeCell(row.title)} | ${escapeCell(row.cause)} | ${escapeCell(row.fix)} | ${example} |`
       );