@zvndev/darkmown 2.2.0 → 2.3.0

package/src/router.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { wdError } from "./compiler/context.js";
 import { parseFrontmatter } from "./compiler.js";
 import { isHiddenName, pageExtensions } from "./config.js";
 
@@ -64,8 +65,9 @@ export function discoverRoutes(routesRoot, options = {}) {
   const seen = new Map();
   for (const route of routes) {
     if (seen.has(route.route)) {
-      throw new Error(
-        `Duplicate route "${route.route}" from ${seen.get(route.route)} and ${route.file}`
+      throw wdError(
+        `Duplicate route "${route.route}" from ${seen.get(route.route)} and ${route.file}`,
+        { code: "WD901", file: route.file }
       );
     }
     seen.set(route.route, route.file);
@@ -114,8 +116,9 @@ export function outputPathForRoute(distRoot, route) {
   const clean = route === "/" ? "" : route.replace(/^\/|\/$/g, "");
   const out = path.join(distRoot, clean, "index.html");
   if (!path.resolve(out).startsWith(path.resolve(distRoot) + path.sep)) {
-    throw new Error(
-      `Route "${route}" resolves outside the build output directory ${distRoot} — routes must not contain traversal segments`
+    throw wdError(
+      `Route "${route}" resolves outside the build output directory ${distRoot} — routes must not contain traversal segments`,
+      { code: "WD902" }
     );
   }
   return out;

package/src/scaffold.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { wdError } from "./compiler/context.js";
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const templatesDir = path.join(moduleDir, "templates");
@@ -36,9 +37,10 @@ export function initProject(root, options = {}) {
   const templateDir = path.join(templatesDir, template);
   if (!fs.existsSync(templateDir) || !fs.statSync(templateDir).isDirectory()) {
     const list = availableTemplates().join(", ");
-    throw new Error(
+    throw wdError(
       `Unknown template "${template}". Available templates: ${list || "(none)"}. ` +
-        "Use: darkmown init [dir] --template <name>"
+        "Use: darkmown init [dir] --template <name>",
+      { code: "WD903", hint: "darkmown init [dir] --template <name>" }
     );
   }
 

package/src/skin.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { wdError } from "./compiler/context.js";
 
 const aliases = new Map([
   ["radius", "border-radius"],
@@ -96,7 +97,7 @@ export function compileSkin(source, opts = {}) {
   }
   for (let i = start; i < lines.length; i++) {
     if (lines[i].text === "scoped" && lines[i].indent === 0) {
-      throw new Error('"scoped" must be the first line of a .skin file');
+      throw wdError('"scoped" must be the first line of a .skin file', { code: "WD801" });
     }
   }
 
@@ -184,8 +185,9 @@ export function compileSkin(source, opts = {}) {
     // place a filtered bare `*`/`page` reset would otherwise leak through to), so
     // it errors with the same hint instead of emitting a never-matching rule.
     if (scope && current === ":root") {
-      throw new Error(
-        `page-level declaration "${text}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      throw wdError(
+        `page-level declaration "${text}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`,
+        { code: "WD802" }
       );
     }
     const media = stack.find((frame) => frame.media)?.media;
@@ -235,8 +237,9 @@ function guardPageLevel(text, parent) {
   for (const part of text.split(",")) {
     const clean = part.trim();
     if (PAGE_LEVEL_SELECTORS.has(clean)) {
-      throw new Error(
-        `page-level selector "${clean}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      throw wdError(
+        `page-level selector "${clean}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`,
+        { code: "WD803" }
       );
     }
   }
@@ -308,7 +311,15 @@ function subjectBase(base) {
  */
 function normalizeAttr(bracketed) {
   const m = bracketed.match(/^\[\s*([^\]=\s]+)\s*=\s*"?([^\]"]*)"?\s*\]$/);
-  return m ? `[${m[1]}="${m[2]}"]` : null;
+  if (!m) return null;
+  // The value is quoted on the way out, but the NAME lands in the selector
+  // verbatim — so it must be validated, not just captured. Without this an
+  // input like `tokens [{=v]` emitted `:root[{="v"]`, whose stray brace
+  // unbalances the stylesheet and makes a CSS parser swallow every rule that
+  // follows it. Anything that is not a plain CSS identifier falls through to
+  // the caller's `:root` fallback. (Found by tests/fuzz-skin.test.js.)
+  if (!/^[A-Za-z_-][\w-]*$/.test(m[1])) return null;
+  return `[${m[1]}="${m[2]}"]`;
 }
 
 /**

package/types/api-runner.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The local-dev serverless API runner. Gives `darkmown dev` the SAME `/api/*`
+ * behavior a project gets on Vercel / Cloudflare in production, so a `:fetch
+ * /api/x` or a form POST works identically before you ever deploy.
+ *
+ * The convention is deliberately plain: a backend endpoint is a plain-JS file
+ * under the project's top-level `api/` directory that default-exports a
+ * Web-standard handler `(request: Request, context) => Response | Promise<Response>`.
+ * That is the exact signature Vercel Edge, Cloudflare Pages, Netlify Edge and
+ * Deno already run — Darkmown owns no server, it just emulates the host locally.
+ *
+ * File → route, rooted at the `/api` URL prefix (matching Vercel's `api/`):
+ *   api/echo.js          → /api/echo
+ *   api/users/index.js   → /api/users
+ *   api/users/list.js    → /api/users/list
+ *   api/users/[id].js    → /api/users/:id   (context.params.id)
+ *
+ * Nothing here mutates module state: routes are discovered per call so a newly
+ * added function is picked up without a restart, and each handler is imported
+ * with an mtime cache-buster so edits hot-reload.
+ */
+/**
+ * A discovered API route.
+ * @typedef {object} ApiRoute
+ * @property {string} file Absolute path to the handler module.
+ * @property {string[]} segments Route segments after `/api`; a dynamic segment
+ *   is stored as `[name]` (e.g. `["users", "[id]"]`).
+ */
+/**
+ * Walk `apiDir` and return every `.js`/`.mjs` handler as an {@link ApiRoute}.
+ * Files/dirs whose name starts with `.`, `_`, or `-` are treated as private
+ * (helpers, fixtures) and never routed, matching the router's hidden-path rule.
+ * Returns `[]` when `apiDir` does not exist.
+ * @param {string} apiDir Absolute path to the project's `api/` directory.
+ * @returns {ApiRoute[]}
+ */
+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).
+ * @param {ApiRoute[]} routes
+ * @param {string} pathname Request pathname (no query string).
+ * @returns {{ file: string, params: Record<string, string> } | null}
+ */
+export function matchApiRoute(routes: ApiRoute[], pathname: string): {
+    file: string;
+    params: Record<string, string>;
+} | 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.
+ * @param {import("node:http").IncomingMessage} req
+ * @returns {Promise<Request>}
+ */
+export function nodeRequestToWeb(req: import("node:http").IncomingMessage): Promise<Request>;
+/**
+ * Write a Web-standard `Response` back onto a Node `ServerResponse`.
+ * @param {Response} response
+ * @param {import("node:http").ServerResponse} res
+ * @returns {Promise<void>}
+ */
+export function writeWebResponse(response: Response, res: import("node:http").ServerResponse): Promise<void>;
+/**
+ * Handle a request as an API call if its pathname matches a function under
+ * `apiDir`. Returns `true` when it owned the request (a route matched, whether
+ * the handler succeeded or threw), `false` when nothing matched so the caller
+ * should fall through to static serving.
+ *
+ * @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
+ * @returns {Promise<boolean>}
+ */
+export function handleApiRequest({ apiDir, req, res }: {
+    apiDir: string;
+    req: import("node:http").IncomingMessage;
+    res: import("node:http").ServerResponse;
+}): Promise<boolean>;
+/**
+ * A discovered API route.
+ */
+export type ApiRoute = {
+    /**
+     * Absolute path to the handler module.
+     */
+    file: string;
+    /**
+     * Route segments after `/api`; a dynamic segment
+     * is stored as `[name]` (e.g. `["users", "[id]"]`).
+     */
+    segments: string[];
+};

package/types/builder.d.ts

@@ -1,24 +1,127 @@
 /**
  * Compile the whole site under `cwd` into `dist`, returning the route manifest.
+ *
+ * The build is always 100% static, CDN-cacheable HTML. Backend `api/*.js`
+ * functions are NOT compiled — they are the host's concern. `target` only
+ * decides the small amount of host glue Darkmown emits alongside the static
+ * output: the default (`vercel`/anything) leaves `api/` for the platform to pick
+ * up natively; `cloudflare` emits a `dist/_worker.js/` module that routes
+ * `/api/*` to those same functions and serves everything else as a static asset.
+ *
  * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
- * @returns {{ routes: RouteManifestEntry[], distRoot: string }}
+ * @param {{ target?: string, includeDrafts?: boolean, depMap?: boolean, changed?: string[], quietFeedHints?: boolean }} [options]
+ *   `target: "cloudflare"` emits the Pages worker. `includeDrafts: true` keeps
+ *   `draft: true` pages in the build + feeds (dev / `build --drafts`); default
+ *   excludes them at route discovery so feeds never see a draft. `depMap: true`
+ *   (dev builds) writes the per-route dependency map to `dist/.wd-dev-deps.json`.
+ *   `changed` (project-relative paths, dev only; implies `depMap`) attempts an
+ *   incremental rebuild of just the affected routes, falling back to a full
+ *   rebuild on ANY uncertainty — a stale page is worse than a slow rebuild.
+ * @returns {BuildResult}
  */
-export function buildSite(cwd?: string): {
-    routes: RouteManifestEntry[];
-    distRoot: string;
-};
+export function buildSite(cwd?: string, options?: {
+    target?: string;
+    includeDrafts?: boolean;
+    depMap?: boolean;
+    changed?: string[];
+    quietFeedHints?: boolean;
+}): BuildResult;
 /**
- * Strip JSDoc `/** ... *\/` blocks from the runtime before it ships.
- * The source keeps full type annotations (for `checkJs` + `.d.ts`), but the
- * browser never needs to download them — this keeps the shipped runtime lean
- * and the gzip budget honest (measured against what users actually receive).
- * Only `/** ... *\/` blocks are removed; code and string literals are untouched.
+ * Strip developer comments from the runtime before it ships. The source keeps
+ * full JSDoc type annotations (for `checkJs` + `.d.ts`) and explanatory comments
+ * so it stays readable; the browser downloads neither. This keeps the shipped
+ * runtime lean and the gzip budget honest (measured against what users receive),
+ * WITHOUT minifying — identifiers, structure, and whitespace are all preserved.
+ *
+ * Two passes, each conservative: `/** ... *\/` JSDoc blocks, then whole-line
+ * `//` comments (a line that is nothing but a comment). Trailing `//` after code
+ * and `//` inside strings/URLs are deliberately left untouched, so no string
+ * literal is ever harmed.
  * @param {string} source
  * @returns {string}
  */
 export function stripRuntimeComments(source: string): string;
+/**
+ * Render the Cloudflare Pages `_headers` file from the route manifest.
+ *
+ * Cloudflare applies every matching block in order; when blocks set the same
+ * header, the later block wins. So we emit the catch-all `/*` first (baseline
+ * security headers + the reactive CSP, which since 2.1 is eval-free and satisfies
+ * every page), then one block per static route that re-states the same eval-free
+ * CSP as defense-in-depth. Reactive routes need no override — the catch-all
+ * already carries the eval-free CSP.
+ *
+ * Clean URLs mean a route like `/docs/` is served at both `/docs` and `/docs/`,
+ * so each static route emits a path glob (`/docs`, `/docs/*`) that covers both.
+ * @param {RouteManifestEntry[]} manifest
+ * @returns {string}
+ */
+export function renderCloudflareHeaders(manifest: RouteManifestEntry[]): string;
+/**
+ * @typedef {import("./config.js").Paths} Paths
+ * @typedef {import("./compiler.js").Assets} Assets
+ * @typedef {import("./compiler.js").Meta} Meta
+ * @typedef {import("./router.js").Route} Route
+ */
+/**
+ * A built route entry written to `dist/routes.json`.
+ * @typedef {object} RouteManifestEntry
+ * @property {string} route Public route path.
+ * @property {string} file Source file path, relative to cwd, POSIX-separated.
+ * @property {{ skins: string[], scripts: string[], runtime: boolean }} assets
+ */
+/**
+ * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
+ * written by dev builds so a later `--changed` build can rebuild only the routes
+ * whose dependency graph contains the changed file.
+ * @typedef {object} DepMapEntry
+ * @property {string} file Source file, project-relative, POSIX-separated.
+ * @property {string[]} deps Every source file this route's compile read (the page
+ *   itself, includes, loop JSON data files, colocated `.skin`/`.js`) —
+ *   project-relative, POSIX-separated, sorted.
+ * @property {string[]} collections Collection names the route loops, so a change
+ *   to any entry of the collection rebuilds this route.
+ * @property {RouteManifestEntry[]} pages The manifest entries this route emitted
+ *   (one, or one per pagination page), so `routes.json`/`_headers`/the sitemap
+ *   can be reassembled globally without recompiling untouched routes.
+ */
+/** The dev dependency map's filename under `dist/`. */
+export const DEP_MAP_FILE: ".wd-dev-deps.json";
+/**
+ * The value `buildSite` returns. `incremental` is present only when a `changed`
+ * build actually rebuilt a subset of routes (absent on every full rebuild).
+ */
+export type BuildResult = {
+    routes: RouteManifestEntry[];
+    distRoot: string;
+    feeds: {
+        sitemap: number | null;
+        rss: number | null;
+    };
+    incremental?: {
+        changed: string[];
+        rebuilt: string[];
+        total: number;
+    } | undefined;
+};
+/**
+ * A compiled page bound for a concrete output route. Mirrors `CompiledPage` plus
+ * the public `route` it's written to — for a paginated listing, page 1 keeps the
+ * listing route and pages 2+ get `/<route>/page/<n>/`.
+ */
+export type EmittedPage = {
+    /**
+     * Public route path this page is written to.
+     */
+    route: string;
+    html: string;
+    assets: import("./compiler.js").Assets;
+    warnings: string[];
+};
 export type Paths = import("./config.js").Paths;
 export type Assets = import("./compiler.js").Assets;
+export type Meta = import("./compiler.js").Meta;
+export type Route = import("./router.js").Route;
 /**
  * A built route entry written to `dist/routes.json`.
  */
@@ -37,3 +140,31 @@ export type RouteManifestEntry = {
         runtime: boolean;
     };
 };
+/**
+ * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
+ * written by dev builds so a later `--changed` build can rebuild only the routes
+ * whose dependency graph contains the changed file.
+ */
+export type DepMapEntry = {
+    /**
+     * Source file, project-relative, POSIX-separated.
+     */
+    file: string;
+    /**
+     * Every source file this route's compile read (the page
+     * itself, includes, loop JSON data files, colocated `.skin`/`.js`) —
+     * project-relative, POSIX-separated, sorted.
+     */
+    deps: string[];
+    /**
+     * Collection names the route loops, so a change
+     * to any entry of the collection rebuilds this route.
+     */
+    collections: string[];
+    /**
+     * The manifest entries this route emitted
+     * (one, or one per pagination page), so `routes.json`/`_headers`/the sitemap
+     * can be reassembled globally without recompiling untouched routes.
+     */
+    pages: RouteManifestEntry[];
+};

package/types/catalog.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The structured, machine-readable catalog of the whole `.wd` authoring surface.
+ * @returns {DirectiveCatalog}
+ */
+export function directiveCatalog(): DirectiveCatalog;
+/**
+ * Render the catalog as a compact llms.txt-style markdown cheatsheet — the
+ * artifact an app pastes into a small model's system prompt. Generated entirely
+ * from {@link directiveCatalog}, so it can never disagree with what compiles.
+ * @returns {string}
+ */
+export function llmsText(): string;
+/** The action tokens the catalog exposes — used by the drift guard. */
+export const CATALOG_ACTION_TOKENS: string[];
+/**
+ * Whether the directive
+ *   ships zero JS (static), needs the reactive runtime (reactive), or can be
+ *   either depending on whether it reads `:state`/`:store` (either).
+ */
+export type Reactivity = "static" | "reactive" | "either";
+export type DirectiveEntry = {
+    /**
+     * The directive token (`@loop`, `:state`, `:::`, …).
+     */
+    name: string;
+    /**
+     * A single line, or an opener with a closer.
+     */
+    kind: "line" | "block";
+    /**
+     * One-line schematic (`[…]` = optional, `<…>` = slot).
+     */
+    syntax: string;
+    /**
+     * One-line, plain-language summary.
+     */
+    description: string;
+    /**
+     * One concrete, compilable line.
+     */
+    example: string;
+    reactive: Reactivity;
+};
+/**
+ * A clause / action-op / pipe / operator entry.
+ */
+export type CatalogEntry = {
+    name: string;
+    syntax?: string | undefined;
+    description: string;
+    example?: string | undefined;
+};
+export type DirectiveCatalog = {
+    /**
+     * The installed Darkmown version.
+     */
+    version: string;
+    /**
+     * Always `.wd` — the file extension that gates directives.
+     */
+    format: string;
+    directives: DirectiveEntry[];
+    /**
+     * Clauses of the `@loop` header (fixed order).
+     */
+    loopClauses: CatalogEntry[];
+    /**
+     * Per-row meta variables valid in a loop body.
+     */
+    loopVariables: CatalogEntry[];
+    /**
+     * The `:button`/`:effect`/`:every` action vocabulary.
+     */
+    actionOps: CatalogEntry[];
+    /**
+     * The `{ value | pipe }` formatter whitelist.
+     */
+    formatPipes: CatalogEntry[];
+    /**
+     * Comparison operators for `where`/`:if`/`when`.
+     */
+    predicateOps: CatalogEntry[];
+    /**
+     * Logical joiners (`and`/`or`/`not`).
+     */
+    predicateJoiners: string[];
+    /**
+     * The `WDxxx` code blocks.
+     */
+    errorAreas: import("./errors.js").ErrorArea[];
+    /**
+     * Every stable compile-error
+     * code, with its cause and fix. A thrown error's message starts with its code
+     * (`[WD201] …`) and mirrors it on `err.wd.code`.
+     */
+    errors: import("./errors.js").ErrorEntry[];
+};

package/types/compiler/actions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleButton(line: string, ctx: Ctx, index: number): string;
+/**
+ * Parse `:effect <watched> -> <actions>` into a zero-output marker the runtime
+ * watches: when `<watched>` state changes, it runs `<actions>` (the same `:button`
+ * action vocabulary, `;`-chained). For arbitrary side effects beyond `:computed`
+ * (derive state) and fetch deps (auto-refetch).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEffect(line: string, ctx: Ctx, index: number): string;
+/**
+ * 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: string, ctx: Ctx, index: number): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").Action} Action
+ */
+export const BUTTON_EXAMPLE: ":button \"Add one\" -> count++";
+export const EFFECT_EXAMPLE: ":effect query -> searches++";
+export const EVERY_EXAMPLE: ":every 5s -> seconds++";
+export const ACTION_EXAMPLE: "count++";
+export const ACTION_USE: "Use: name++, name--, n += k, n -= k, name = v, flag toggle, list append/prepend v, list toggle v, list remove v, x clear, obj merge other, obj delete key, name reset — chain with \";\" — e.g. count++";
+export type Ctx = import("./context.js").Ctx;
+export type Action = import("./context.js").Action;

package/types/compiler/body.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+/**
+ * Parse a `.wd` body line-by-line into HTML, mixing directives and prose.
+ * @param {string[]} lines
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function compileBody(lines: string[], ctx: Ctx): string;
+export type Ctx = import("./context.js").Ctx;

package/types/compiler/collections.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Build the collection index from the router's discovered routes: one entry per
+ * `site/pages/<name>/…` route, grouped under the FIRST path segment (the
+ * collection name). The home route, top-level pages, and the synthetic `/404/`
+ * route are not entries. Reuses each route's already-parsed `meta` (no re-parse)
+ * and reads the `.md` body only for the excerpt fallback. When a collection has
+ * a `_schema.wd`, every entry is validated against it here (throwing on the
+ * first violation), so a malformed entry fails the build with a `file:line`.
+ *
+ * @param {Route[]} routes Post-draft-filter routes from `discoverRoutes`.
+ * @param {Paths} paths Resolved project paths (`routesRoot` for `_schema.wd`).
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed by
+ *   default; pass an in-memory reader to build collections without a filesystem).
+ * @returns {Map<string, CollectionRow[]>} Collection name → entry rows.
+ */
+export function buildCollections(routes: Route[], paths: Paths, reader?: import("./reader.js").Reader): Map<string, CollectionRow[]>;
+/**
+ * A parsed `_schema.wd` field rule.
+ * @typedef {object} SchemaField
+ * @property {string} name Field name.
+ * @property {string} type One of {@link SCHEMA_TYPES}.
+ * @property {boolean} optional Whether the field may be absent (`?` modifier).
+ */
+/**
+ * Read + parse a collection's `_schema.wd`, or null when the file is absent
+ * (validation is opt-in). The schema is frontmatter-shaped — one `field: type`
+ * line per rule inside the `---` block — so authors write it exactly like the
+ * frontmatter it validates. Each type must be in the closed {@link SCHEMA_TYPES}
+ * vocabulary (`?` suffix = optional); an unknown token is a compile error in the
+ * schema file itself, pointing at the offending line.
+ * @param {string} name Collection name.
+ * @param {Paths} paths
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed by default).
+ * @returns {SchemaField[] | null}
+ */
+export function readSchema(name: string, paths: Paths, reader?: import("./reader.js").Reader): SchemaField[] | null;
+/**
+ * Parse a `_schema.wd` source into field rules. The schema fields live in the
+ * frontmatter block; the body (if any) is ignored, so a schema file can carry a
+ * prose note after its `---` fence. Each field line is `name: type` where type
+ * is a closed token with an optional trailing `?`.
+ * @param {string} raw `_schema.wd` file contents.
+ * @param {string} file Absolute path, for `file:line` errors.
+ * @returns {SchemaField[]}
+ */
+export function parseSchema(raw: string, file: string): SchemaField[];
+/**
+ * A parsed `_schema.wd` field rule.
+ */
+export type SchemaField = {
+    /**
+     * Field name.
+     */
+    name: string;
+    /**
+     * One of {@link SCHEMA_TYPES}.
+     */
+    type: string;
+    /**
+     * Whether the field may be absent (`?` modifier).
+     */
+    optional: boolean;
+};
+export type Paths = import("./context.js").Paths;
+export type Meta = import("./context.js").Meta;
+export type Route = import("../router.js").Route;
+/**
+ * A collection entry row: every frontmatter field, plus derived `url`/`slug`/
+ * `excerpt`. Keyed loosely so authors' custom frontmatter keys pass through to
+ * `{ post.whatever }` and `where`/`sort` without a closed schema here.
+ */
+export type CollectionRow = Record<string, unknown> & {
+    url: string;
+    slug: string;
+    excerpt: string;
+};