@zvndev/darkmown 2.10.0 → 2.10.1

package/src/skin.js

@@ -1,6 +1,12 @@
 import crypto from "node:crypto";
 import { wdError } from "./compiler/context.js";
 
+// Concrete, compilable skins for the at-rule error hints + the error registry
+// (src/errors.js). Multi-line because both at-rules are block constructs; a
+// test in tests/skin-atrules.test.js compiles each verbatim.
+export const FONT_FACE_EXAMPLE = '@font-face\n  font-family "Newsreader"';
+export const KEYFRAMES_EXAMPLE = "@keyframes fade-in\n  to\n    opacity 1";
+
 const aliases = new Map([
   ["radius", "border-radius"],
   ["shadow", "box-shadow"],
@@ -70,28 +76,37 @@ const PAGE_LEVEL_SELECTORS = new Set(["page", "*", "html", "body", "::selection"
  * selectors), they are ALWAYS global (never scope-stamped, same contract as
  * `tokens`), and their declaration values use the same alias/`$token` pipeline.
  * @param {string} source
- * @param {{ scope?: string, subjects?: Set<string> }} [opts] `scope`: the scope
- *   id enabling scoped mode. `subjects`: an optional set the compiler fills with
- *   every scoped subject token (`.card`, `h2`, `#id`) for the unused-selector
- *   warning, so the caller need not re-parse the source.
+ * @param {{ scope?: string, subjects?: Set<string>, file?: string }} [opts]
+ *   `scope`: the scope id enabling scoped mode. `subjects`: an optional set the
+ *   compiler fills with every scoped subject token (`.card`, `h2`, `#id`) for
+ *   the unused-selector warning, so the caller need not re-parse the source.
+ *   `file`: the skin's path, threaded into author-facing errors so they report
+ *   `file:line` (the builder always passes it; a bare call reports `on line N`).
  * @returns {string}
  */
 export function compileSkin(source, opts = {}) {
   const scope = opts.scope;
   const subjects = opts.subjects;
+  const file = opts.file;
   const lines = source
     .replace(/\r\n?/g, "\n")
-    .replace(/\/\*[\s\S]*?\*\//g, "") // strip /* … */ block comments (any span)
+    // Strip /* … */ block comments (any span), KEEPING their newlines so the
+    // `line` recorded below stays the true file line even past a multi-line
+    // comment.
+    .replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ""))
     .split("\n")
-    .filter((raw) => {
-      const t = raw.trim();
-      if (!t || t.startsWith("//")) return false;
+    .map((raw, index) => ({
+      indent: (raw.match(/^\s*/)?.[0] ?? "").length,
+      text: raw.trim(),
+      line: index + 1
+    }))
+    .filter(({ text }) => {
+      if (!text || text.startsWith("//")) return false;
       // Decorative divider lines (----, ====, * * *, ~~~) carry no rule and would
       // otherwise parse as a bogus selector/declaration. Anything with a letter or
       // digit is real content; punctuation-only lines are skipped.
-      return /[A-Za-z0-9]/.test(t);
-    })
-    .map((raw) => ({ indent: (raw.match(/^\s*/)?.[0] ?? "").length, text: raw.trim() }));
+      return /[A-Za-z0-9]/.test(text);
+    });
 
   // The opt-in marker: `scoped` must be the FIRST meaningful line (the filter
   // above has already dropped comments, blanks, and dividers). Anywhere else it
@@ -181,7 +196,7 @@ export function compileSkin(source, opts = {}) {
     const atRule = /^@(font-face|keyframes)(?:\s+(.+))?$/.exec(text);
     if (atRule) {
       const media = stack.find((frame) => frame.media)?.media;
-      const block = collectAtRule(atRule[1], atRule[2], lines, i);
+      const block = collectAtRule(atRule[1], atRule[2], lines, i, file);
       css.push(media ? `${media} {\n${block.css}\n}` : block.css);
       i = block.end;
       continue;
@@ -367,17 +382,19 @@ function normalizeSelector(text, parent) {
 const KEYFRAME_SELECTOR = /^(?:from|to|\d+(?:\.\d+)?%)(?:\s*,\s*(?:from|to|\d+(?:\.\d+)?%))*$/;
 
 /**
- * A plain Error, no WD code: the code registry (`src/errors.js`) and its drift
- * guard (`tests/error-codes.test.js`) are owned by a parallel change, so a
- * `code: "WD8xx"` here would fail the "every code thrown is registered" gate
- * and an inline throw would fail the "no author-facing throw bypasses wdError"
- * scan. Messages still lead with the construct and end with a corrective
- * example, registry-style.
- * @param {string} message
- * @returns {Error}
+ * An author-facing at-rule error, routed through `wdError` like every other
+ * compile error: it carries a registered WD8xx code (src/errors.js), the true
+ * source line, and a corrective `Use:` hint. The file is named when the caller
+ * threaded one (the builder always does); a bare `compileSkin` call has no
+ * path, so the location falls back to `on line N`.
+ * @param {string} summary What is wrong, naming the offending text.
+ * @param {import("./compiler/context.js").WdErrorInfo} wd The structured mirror;
+ *   `code` is required (every at-rule error is registered in src/errors.js).
+ * @returns {Error & { wd: import("./compiler/context.js").WdErrorInfo }}
  */
-function skinError(message) {
-  return new Error(message);
+function skinError(summary, wd) {
+  const where = wd.file ? ` in ${wd.file}:${wd.line}` : ` on line ${wd.line}`;
+  return wdError(`${summary}${where}. Use: ${wd.hint}`, wd);
 }
 
 /**
@@ -403,21 +420,28 @@ function declaration(text) {
  * `50%, 75%`), each with its own indented declarations; a keyframe selector is
  * validated against KEYFRAME_SELECTOR so it can never be misread as a
  * declaration or an element selector, and declarations cannot nest further.
+ * Every rejection is a coded WD8xx error pointing at the offending line.
  * @param {string} kind `font-face` or `keyframes`.
  * @param {string | undefined} rest Text after the at-rule keyword (the
  *   keyframes name; invalid on `@font-face`).
- * @param {{ indent: number, text: string }[]} lines Preprocessed skin lines.
+ * @param {{ indent: number, text: string, line: number }[]} lines Preprocessed
+ *   skin lines, each carrying its true 1-based file line.
  * @param {number} start Index of the at-rule line.
+ * @param {string | undefined} file The skin's path, when the caller knows it.
  * @returns {{ css: string, end: number }} `end` = last consumed line index.
  */
-function collectAtRule(kind, rest, lines, start) {
+function collectAtRule(kind, rest, lines, start, file) {
   const indent = lines[start].indent;
 
   if (kind === "font-face") {
     if (rest)
-      throw skinError(
-        `@font-face takes no name, got "${rest}" — write the descriptors indented beneath a bare @font-face line, e.g. font-family "Newsreader"`
-      );
+      throw skinError(`@font-face takes no name, got "${rest}"`, {
+        code: "WD804",
+        file,
+        line: lines[start].line,
+        hint: `write the descriptors indented beneath a bare @font-face line — e.g. font-family "Newsreader"`,
+        example: FONT_FACE_EXAMPLE
+      });
     /** @type {string[]} */
     const decls = [];
     let i = start;
@@ -425,52 +449,94 @@ function collectAtRule(kind, rest, lines, start) {
       i++;
       if (i + 1 < lines.length && lines[i + 1].indent > lines[i].indent)
         throw skinError(
-          `@font-face only takes declarations — "${lines[i].text}" opens a nested block, which is not valid inside @font-face`
+          `@font-face only takes declarations — "${lines[i].text}" opens a nested block, which is not valid inside @font-face`,
+          {
+            code: "WD804",
+            file,
+            line: lines[i].line,
+            hint: `keep every @font-face child a flat prop value declaration — e.g. font-family "Newsreader"`,
+            example: FONT_FACE_EXAMPLE
+          }
         );
       decls.push(`  ${declaration(lines[i].text)}`);
     }
     if (!decls.length)
-      throw skinError(
-        '@font-face has no declarations — indent its descriptors beneath it, e.g. font-family "Newsreader"'
-      );
+      throw skinError("@font-face has no declarations", {
+        code: "WD804",
+        file,
+        line: lines[start].line,
+        hint: `indent its descriptors beneath it — e.g. font-family "Newsreader"`,
+        example: FONT_FACE_EXAMPLE
+      });
     return { css: `@font-face {\n${decls.join("\n")}\n}`, end: i };
   }
 
-  if (!rest) throw skinError("@keyframes needs a name — e.g. @keyframes fade-in");
+  if (!rest)
+    throw skinError("@keyframes needs a name", {
+      code: "WD805",
+      file,
+      line: lines[start].line,
+      hint: "@keyframes <name> — e.g. @keyframes fade-in",
+      example: KEYFRAMES_EXAMPLE
+    });
   if (!/^-?[A-Za-z_][\w-]*$/.test(rest))
-    throw skinError(
-      `invalid @keyframes name "${rest}" — use a plain CSS identifier, e.g. @keyframes fade-in`
-    );
+    throw skinError(`invalid @keyframes name "${rest}"`, {
+      code: "WD805",
+      file,
+      line: lines[start].line,
+      hint: "name it with a plain CSS identifier — e.g. @keyframes fade-in",
+      example: KEYFRAMES_EXAMPLE
+    });
   /** @type {string[]} */
   const stops = [];
   let i = start;
   while (i + 1 < lines.length && lines[i + 1].indent > indent) {
     i++;
     const selector = lines[i].text;
+    const selectorLine = lines[i].line;
     const selectorIndent = lines[i].indent;
     if (!KEYFRAME_SELECTOR.test(selector))
-      throw skinError(
-        `"${selector}" is not a keyframe selector in @keyframes ${rest} — use from, to, or a percentage (50%, or a list like 50%, 75%)`
-      );
+      throw skinError(`"${selector}" is not a keyframe selector in @keyframes ${rest}`, {
+        code: "WD806",
+        file,
+        line: selectorLine,
+        hint: "use from, to, or a percentage (50%, or a list like 50%, 75%)",
+        example: KEYFRAMES_EXAMPLE
+      });
     /** @type {string[]} */
     const decls = [];
     while (i + 1 < lines.length && lines[i + 1].indent > selectorIndent) {
       i++;
       if (i + 1 < lines.length && lines[i + 1].indent > lines[i].indent)
         throw skinError(
-          `@keyframes declarations cannot nest — "${lines[i].text}" opens a block inside keyframe "${selector}"`
+          `@keyframes declarations cannot nest — "${lines[i].text}" opens a block inside keyframe "${selector}"`,
+          {
+            code: "WD807",
+            file,
+            line: lines[i].line,
+            hint: "keep each keyframe's declarations flat, one level beneath its selector — e.g. opacity 1",
+            example: KEYFRAMES_EXAMPLE
+          }
         );
       decls.push(`    ${declaration(lines[i].text)}`);
     }
     if (!decls.length)
-      throw skinError(
-        `keyframe "${selector}" in @keyframes ${rest} has no declarations — indent them beneath it`
-      );
+      throw skinError(`keyframe "${selector}" in @keyframes ${rest} has no declarations`, {
+        code: "WD807",
+        file,
+        line: selectorLine,
+        hint: "indent the declarations beneath the keyframe selector — e.g. opacity 1",
+        example: KEYFRAMES_EXAMPLE
+      });
     stops.push(`  ${selector} {\n${decls.join("\n")}\n  }`);
   }
   if (!stops.length)
-    throw skinError(
-      `@keyframes ${rest} has no keyframe selectors — indent from/to/percentage blocks beneath it`
-    );
+    throw skinError(`@keyframes ${rest} has no keyframe selectors`, {
+      code: "WD807",
+      file,
+      line: lines[start].line,
+      hint: "indent from/to/percentage blocks beneath it — e.g. from",
+      example: KEYFRAMES_EXAMPLE
+    });
   return { css: `@keyframes ${rest} {\n${stops.join("\n")}\n}`, end: i };
 }

package/src/templates/dashboard/README.md

@@ -12,7 +12,9 @@ in `darkmown dev` and on every host. Loading and error states are handled inline
 
 - `npm run dev` — live compiler + local `/api/*` runner on http://localhost:5173.
 - `npm run build` — compile to `dist/`.
-- `npm run preview` — serve the built `dist/` locally (static only; use `dev` for `/api`).
+- `npm run preview`: serve the built `dist/` locally. Since Darkmown 2.8.0 this
+  runs your `api/` functions too, so the dashboard fetches live data in preview
+  exactly like in `dev`.
 
 ## Deploy
 

package/src/templates/landing/site/pages/index.skin

@@ -164,6 +164,13 @@ input:focus-visible, textarea:focus-visible, select:focus-visible
   radius 12px
   padding 1.25rem
 
+.icon
+  color $accent
+  margin-bottom .35rem
+
+.icon svg
+  display block
+
 .feature h3
   margin .25rem 0 .5rem
 

package/src/templates/landing/site/pages/index.wd

@@ -2,6 +2,7 @@
 title: Acme — ship faster
 description: A marketing one-pager built with Darkmown. Zero framework JS on the static parts, with a testimonials carousel.
 transitions: true
+html: true
 ---
 
 @include /nav.wd
@@ -20,15 +21,21 @@ The all-in-one toolkit your team actually enjoys using.
 
 ::: features
 ::: feature
-### ⚡ Fast
+<div class="icon"><svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M13 2 4 14h6l-1 8 9-12h-6l1-8z"/></svg></div>
+
+### Fast
 Static pages, zero framework JavaScript. Instant loads, perfect Lighthouse.
 :::
 ::: feature
-### 🧩 Simple
+<div class="icon"><svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="4" width="7" height="7" rx="1.5"/><rect x="13" y="4" width="7" height="7" rx="1.5"/><rect x="4" y="13" width="7" height="7" rx="1.5"/><rect x="13" y="13" width="7" height="7" rx="1.5"/></svg></div>
+
+### Simple
 Write Markdown. Add a directive only on the pages that need interactivity.
 :::
 ::: feature
-### 🚀 Deploy anywhere
+<div class="icon"><svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 15V3"/><path d="m6 9 6-6 6 6"/><path d="M4 21h16"/></svg></div>
+
+### Deploy anywhere
 One command to Vercel or Cloudflare — your API comes along for free.
 :::
 :::

package/src/templates/store/README.md

@@ -3,7 +3,9 @@
 A storefront in Markdown: a product grid with live search, a shared `:store` cart,
 and a checkout that POSTs to a serverless function.
 
-- **Static catalog** — `site/pages/index.wd` loops `site/_/products.json`.
+- **Static catalog**: `site/pages/index.wd` loops `site/_/products.json`, rendering
+  each product through the `site/_/card.wd` include (a `defaults:` fallback plus a
+  `{ children }` slot for the add-to-cart button).
 - **Cart** — a `:store` shared across the page; add/remove with `:button`.
 - **Checkout** — `:form action="/api/checkout"` posts to `api/checkout.js`, a plain
   Web-standard `(request) => Response` function that runs in `darkmown dev` and on
@@ -13,7 +15,8 @@ and a checkout that POSTs to a serverless function.
 
 - `npm run dev` — live compiler + the local `/api/*` runner on http://localhost:5173.
 - `npm run build` — compile to `dist/`.
-- `npm run preview` — serve the built `dist/` locally (static only; use `dev` for `/api`).
+- `npm run preview`: serve the built `dist/` locally. Since Darkmown 2.8.0 this
+  runs your `api/` functions too, so checkout works in preview exactly like in `dev`.
 
 ## Deploy
 

package/src/templates/store/site/_/card.wd

@@ -0,0 +1,19 @@
+---
+defaults: [note="Ships in 2 days"]
+---
+
+::: card .product
+::: tile
+{ p.initial }
+:::
+::: pname
+{ p.name }
+:::
+::: price
+{ p.price | money }
+:::
+::: note
+{ note }
+:::
+{ children }
+:::

package/src/templates/store/site/_/products.json

@@ -1,8 +1,8 @@
 [
-  { "name": "Ceramic Mug", "emoji": "☕️", "price": 18 },
-  { "name": "Linen Tote", "emoji": "👜", "price": 32 },
-  { "name": "Pocket Notebook", "emoji": "📓", "price": 12 },
-  { "name": "Desk Lamp", "emoji": "💡", "price": 64 },
-  { "name": "Plant Pot", "emoji": "🪴", "price": 24 },
-  { "name": "Wall Clock", "emoji": "🕰️", "price": 48 }
+  { "name": "Ceramic Mug", "initial": "C", "price": 18 },
+  { "name": "Linen Tote", "initial": "L", "price": 32 },
+  { "name": "Pocket Notebook", "initial": "P", "price": 12 },
+  { "name": "Desk Lamp", "initial": "D", "price": 64 },
+  { "name": "Plant Pot", "initial": "P", "price": 24 },
+  { "name": "Wall Clock", "initial": "W", "price": 48 }
 ]

package/src/templates/store/site/pages/index.skin

@@ -93,13 +93,28 @@ input:focus-visible, select:focus-visible, textarea:focus-visible
   border-color $accent
   box-shadow 0 12px 26px -16px rgba(26,31,43,.4)
 
-.emoji
-  font-size 2.25rem
+.tile
+  width 3rem
+  height 3rem
+  margin 0 auto
+  display grid
+  place-items center
+  font-size 1.3rem
+  font-weight 700
+  color $accent-deep
+  bg $paper
+  border 1px solid $line
+  radius 10px
 
 .pname
   font-weight 600
   margin .35rem 0 .15rem
 
+.note
+  color $muted
+  font-size .82rem
+  margin-bottom .6rem
+
 .price
   color $accent
   font-weight 600

package/src/templates/store/site/pages/index.wd

@@ -23,18 +23,9 @@ transitions: true
 
 ::: catalog
 @loop /products.json into p where p.name contains q
-::: card .product
-::: emoji
-{ p.emoji }
-:::
-::: pname
-{ p.name }
-:::
-::: price
-{ p.price | money }
-:::
+@include /card.wd
 :button "Add to cart" -> cart += p
-:::
+@endinclude
 @empty
 ::: card .empty
 Nothing matches "**{ q }**".
@@ -46,7 +37,7 @@ Nothing matches "**{ q }**".
 
 @loop cart into item
 ::: card .line
-{ item.emoji } **{ item.name }** — { item.price | money }
+**{ item.name }** — { item.price | money }
 :button "Remove" -> cart remove item
 :::
 @empty

package/types/api-runner.d.ts

@@ -38,18 +38,25 @@ export function discoverApiRoutes(apiDir: string): ApiRoute[];
 /**
  * Match a request pathname against discovered routes. The pathname is expected
  * to start with `/api`; anything else returns `null` (caller serves static).
+ * A dynamic segment whose percent-encoding is malformed (`%E0%A4%A`) makes
+ * `decodeURIComponent` throw — that is reported as `{ malformed: true }` so the
+ * caller answers a clean 400 instead of crashing the request handler.
  * @param {ApiRoute[]} routes
  * @param {string} pathname Request pathname (no query string).
- * @returns {{ file: string, params: Record<string, string> } | null}
+ * @returns {{ file: string, params: Record<string, string> } | { malformed: true } | null}
  */
 export function matchApiRoute(routes: ApiRoute[], pathname: string): {
     file: string;
     params: Record<string, string>;
+} | {
+    malformed: true;
 } | null;
 /**
  * Build a Web-standard `Request` from a Node `IncomingMessage`. The body (for
- * methods that carry one) is buffered fully — dev endpoints are small and this
- * avoids the `duplex: "half"` streaming dance.
+ * methods that carry one) is buffered up to {@link MAX_BODY_BYTES} — dev and
+ * preview endpoints are small and this avoids the `duplex: "half"` streaming
+ * dance. A larger body rejects with {@link BodyTooLargeError}, which
+ * `handleApiRequest` answers as a 413.
  * @param {import("node:http").IncomingMessage} req
  * @returns {Promise<Request>}
  */
@@ -75,19 +82,28 @@ export function writeWebResponse(response: Response, res: import("node:http").Se
  * the handler succeeded or threw), `false` when nothing matched so the caller
  * should fall through to static serving.
  *
+ * Error disclosure: a handler throw is answered as JSON either way, but the
+ * `error` field carries the real message only when `discloseErrors` is set
+ * (the dev server's default — a documented dev convenience). The preview
+ * server passes `false` and the client gets the generic "Internal error",
+ * matching the shape the generated Cloudflare worker ships.
+ *
  * @param {object} io
  * @param {string} io.apiDir Absolute path to the project's `api/` directory.
  * @param {import("node:http").IncomingMessage} io.req
  * @param {import("node:http").ServerResponse} io.res
  * @param {string | string[] | undefined} [io.acceptEncoding] The request's
  *   Accept-Encoding header, when the caller negotiates compression (preview).
+ * @param {boolean} [io.discloseErrors] Echo the thrown message to the client
+ *   (default true, the dev behavior). Pass false on any production-shaped path.
  * @returns {Promise<boolean>}
  */
-export function handleApiRequest({ apiDir, req, res, acceptEncoding }: {
+export function handleApiRequest({ apiDir, req, res, acceptEncoding, discloseErrors }: {
     apiDir: string;
     req: import("node:http").IncomingMessage;
     res: import("node:http").ServerResponse;
     acceptEncoding?: string | string[] | undefined;
+    discloseErrors?: boolean | undefined;
 }): Promise<boolean>;
 /**
  * A discovered API route.

package/types/errors.d.ts

@@ -33,8 +33,9 @@ export function errorsMarkdown(): string;
  * @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. */
 /** @type {ErrorArea[]} */
@@ -93,8 +94,9 @@ export type ErrorEntry = {
      */
     fix: string;
     /**
-     * A concrete, compilable line, sourced from the
-     * compiler's own `*_EXAMPLE` constants.
+     * 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.
      */
     example?: string | undefined;
 };

package/types/font-subset.d.ts

@@ -29,17 +29,21 @@ export function subsetFonts(paths: Paths, options?: {
  * build is synchronous; the wasm API is not), communicating through temp JSON
  * files rather than stdio so a large payload never hits a pipe buffer. The
  * worker always writes a results file — a missing or unparsable one means the
- * child itself died, which is reported as `unavailable` (the build then behaves
- * as if the toolchain were absent: a hint, no subsets, no failure).
+ * child itself died (crashed, or killed by the spawn timeout), which is
+ * reported as `unavailable` (the build then behaves as if the toolchain were
+ * absent: a hint, no subsets, no failure).
  * @param {{ charset: number[], jobs: SubsetJob[] }} payload
  * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
  *   Injectable for tests; the real one is `spawnSync`.
+ * @param {number} [timeoutMs] The worker is killed after this long (default
+ *   two minutes), so a hung toolchain call cannot stall a build forever. The
+ *   kill lands in the same `unavailable` path as any other dead child.
  * @returns {SubsetResult}
  */
 export function runSubsetJobs(payload: {
     charset: number[];
     jobs: SubsetJob[];
-}, spawn?: (cmd: string, args: string[], opts: object) => unknown): SubsetResult;
+}, spawn?: (cmd: string, args: string[], opts: object) => unknown, timeoutMs?: number): SubsetResult;
 /**
  * The subset charset for a build: the base set plus every code point appearing
  * in the given texts (the emitted pages' HTML). Numeric character references

package/types/image-variants.d.ts

@@ -29,14 +29,18 @@ export function generateImageVariants(paths: Paths, options?: {
  * build is synchronous; sharp is not), communicating through temp JSON files
  * rather than stdio so a large job list never hits a pipe buffer. The worker
  * always writes a results file — a missing or unparsable one means the child
- * itself died, which is reported as `unavailable` (the build then behaves as
- * if sharp were absent: a hint, no variants, no failure).
+ * itself died (crashed, or killed by the spawn timeout), which is reported as
+ * `unavailable` (the build then behaves as if sharp were absent: a hint, no
+ * variants, no failure).
  * @param {ResizeJob[]} jobs
  * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
  *   Injectable for tests; the real one is `spawnSync`.
+ * @param {number} [timeoutMs] The worker is killed after this long (default
+ *   two minutes), so a hung sharp call cannot stall a build forever. The kill
+ *   lands in the same `unavailable` path as any other dead child.
  * @returns {ResizeResult}
  */
-export function runResizeJobs(jobs: ResizeJob[], spawn?: (cmd: string, args: string[], opts: object) => unknown): ResizeResult;
+export function runResizeJobs(jobs: ResizeJob[], spawn?: (cmd: string, args: string[], opts: object) => unknown, timeoutMs?: number): ResizeResult;
 /**
  * @typedef {import("./config.js").Paths} Paths
  */

package/types/router.d.ts

@@ -38,6 +38,11 @@ export function discoverRoutes(routesRoot: string, options?: {
 export function isDraft(meta: Meta): boolean;
 /**
  * Derive a public route path from a source file path.
+ *
+ * Fail-closed on control/whitespace characters: the route string flows RAW
+ * into generated config (`dist/_headers` blocks, llms.txt lines), where a
+ * newline in a filename would inject whole config lines. Rejecting here, at
+ * the one route-derivation chokepoint, protects every downstream sink at once.
  * @param {string} routesRoot Absolute path to `site/pages`.
  * @param {string} file Absolute path to the source file.
  * @returns {string}

package/types/skin.d.ts

@@ -33,16 +33,21 @@ export function scopeIdFor(relPath: string): string;
  * selectors), they are ALWAYS global (never scope-stamped, same contract as
  * `tokens`), and their declaration values use the same alias/`$token` pipeline.
  * @param {string} source
- * @param {{ scope?: string, subjects?: Set<string> }} [opts] `scope`: the scope
- *   id enabling scoped mode. `subjects`: an optional set the compiler fills with
- *   every scoped subject token (`.card`, `h2`, `#id`) for the unused-selector
- *   warning, so the caller need not re-parse the source.
+ * @param {{ scope?: string, subjects?: Set<string>, file?: string }} [opts]
+ *   `scope`: the scope id enabling scoped mode. `subjects`: an optional set the
+ *   compiler fills with every scoped subject token (`.card`, `h2`, `#id`) for
+ *   the unused-selector warning, so the caller need not re-parse the source.
+ *   `file`: the skin's path, threaded into author-facing errors so they report
+ *   `file:line` (the builder always passes it; a bare call reports `on line N`).
  * @returns {string}
  */
 export function compileSkin(source: string, opts?: {
     scope?: string;
     subjects?: Set<string>;
+    file?: string;
 }): string;
+export const FONT_FACE_EXAMPLE: "@font-face\n  font-family \"Newsreader\"";
+export const KEYFRAMES_EXAMPLE: "@keyframes fade-in\n  to\n    opacity 1";
 /**
  * A nesting frame in the indentation stack.
  */