@zvndev/darkmown 2.1.0 → 2.3.0

package/types/compiler/page.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Compile a page source file into a full HTML document plus its assets.
+ * @param {string} file Absolute path to the source `.md`/`.wd` file.
+ * @param {Paths} context Resolved project paths.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader }} [options]
+ *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
+ *   site has dated posts), `feed` carries its absolute href + title so every page
+ *   links it. `collections` is the build-time collection index a bare-name
+ *   `@loop` resolves against; `vars` seeds the document scope (the pager `page`
+ *   object on a paginated route). `reader` is the source reader (fs-backed by
+ *   default via `src/compiler.js`; in-memory for `compileFromMemory`).
+ * @returns {CompiledPage}
+ */
+export function compilePage(file: string, context: Paths, options?: {
+    feed?: {
+        href: string;
+        title: string;
+    };
+    collections?: Map<string, import("./collections.js").CollectionRow[]>;
+    vars?: Record<string, unknown>;
+    reader?: import("./reader.js").Reader;
+}): CompiledPage;
+/**
+ * Harden every `<img>` in the assembled page body — compile-time only, zero
+ * runtime JS. Bare markdown images reflow the page as they decode (cumulative
+ * layout shift — the literal "jump" on navigation) and load eagerly. This
+ * stamps intrinsic `width`/`height` (read from the file on disk so the browser
+ * reserves space), `decoding="async"` on all, and a load-priority split: the
+ * first image is the LCP candidate (eager + `fetchpriority="high"`), the rest
+ * lazy-load. Author-set attributes are never overwritten.
+ * @param {string} html Assembled page body HTML.
+ * @param {Paths} paths Resolved project paths.
+ * @param {import("./reader.js").Reader} reader Source reader for the image bytes.
+ * @returns {string}
+ */
+export function enhanceImages(html: string, paths: Paths, reader: import("./reader.js").Reader): string;
+/**
+ * Compile a source file into its body HTML, frontmatter, and assets (no page shell).
+ * @param {string} file Absolute path to the source file.
+ * @param {Paths} context Resolved project paths.
+ * @param {string[]} [stack] Include stack for cycle detection.
+ * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @param {Map<string, import("./collections.js").CollectionRow[]>} [collections]
+ *   Build-time collection index a bare-name `@loop` resolves against.
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed when
+ *   omitted via `src/compiler.js`; in-memory for `compileFromMemory`).
+ * @returns {CompiledDocument}
+ */
+export function compileDocument(file: string, context: Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./collections.js").CollectionRow[]>, reader?: import("./reader.js").Reader): CompiledDocument;
+/**
+ * Compile a single file: parse frontmatter, collect assets, render body.
+ * @param {string} file
+ * @param {Paths} context
+ * @param {string[]} stack
+ * @param {Scope} scope
+ * @param {Compilation} comp
+ * @param {string[]} sections
+ * @param {string | null} loopItem
+ * @param {number} [reactiveDepth] Enclosing REACTIVE `@loop` levels, threaded in
+ *   from the including page so an include's body can't bypass the two-level
+ *   reactive-nesting limit at the `@include` boundary.
+ * @param {{ at: string, line: string } | null} [loopOpener] The enclosing `@loop`
+ *   opener, threaded in so a depth error inside the include names the right opener.
+ * @returns {{ meta: Meta, html: string }}
+ */
+export function compileFile(file: string, context: Paths, stack: string[], scope: Scope, comp: Compilation, sections: string[], loopItem: string | null, reactiveDepth?: number, loopOpener?: {
+    at: string;
+    line: string;
+} | null): {
+    meta: Meta;
+    html: string;
+};
+/**
+ * Compile a page entirely from an in-memory file map — no filesystem, no
+ * `node:fs`. `files` maps PROJECT-RELATIVE POSIX paths (`site/pages/index.wd`,
+ * `site/_/nav.wd`) to their source strings; `entryPath` is the project-relative
+ * path of the page to compile. Includes, colocated `.skin`/`.js` detection, and
+ * `@loop` JSON-data reads all resolve against the same map (anything not in it
+ * is simply "absent"), so `@include`s work as long as their targets are present.
+ *
+ * This is the strategic fs-free entry point the browser playground and a planned
+ * mobile host use: the entire module graph reachable from here is free of
+ * `node:fs`, so it bundles for the browser. It returns the same
+ * {@link CompiledPage} shape as {@link compilePage} and throws the same
+ * `file:line` compile errors, so the error DX is identical in-browser.
+ * @param {Record<string, string> | Map<string, string>} files Project-relative
+ *   path → source content.
+ * @param {string} entryPath Project-relative path of the page to compile.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, cwd?: string }} [options]
+ *   Same shell options as {@link compilePage}; `cwd` overrides the virtual
+ *   project root the relative keys resolve against (defaults to `/`).
+ * @returns {CompiledPage}
+ */
+export function compileFromMemory(files: Record<string, string> | Map<string, string>, entryPath: string, options?: {
+    feed?: {
+        href: string;
+        title: string;
+    };
+    collections?: Map<string, import("./collections.js").CollectionRow[]>;
+    vars?: Record<string, unknown>;
+    cwd?: string;
+}): CompiledPage;
+export type Paths = import("./context.js").Paths;
+export type Meta = import("./context.js").Meta;
+export type Scope = import("./context.js").Scope;
+export type Compilation = import("./context.js").Compilation;
+export type Ctx = import("./context.js").Ctx;
+export type CompiledDocument = import("./context.js").CompiledDocument;
+export type CompiledPage = import("./context.js").CompiledPage;

package/types/compiler/predicates.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @param {string} raw
+ * @param {string} itemName
+ * @param {Ctx} ctx
+ * @returns {Predicate}
+ */
+export function compilePredicate(raw: string, itemName: string, ctx: Ctx): Predicate;
+/**
+ * Evaluate a compiled predicate against a row at build time by walking its AST —
+ * the same closed evaluator the runtime uses, so the fold matches. No eval.
+ * @param {string} body
+ * @param {unknown} item
+ * @param {Ctx} ctx
+ * @returns {boolean}
+ */
+export function evalPredicate(body: string, item: unknown, ctx: Ctx): boolean;
+/**
+ * Compile a `::: … .class when <predicate>`. Allows `:if`-style bare truthy
+ * paths and `where`-style `left <op> right` conditions joined by `and`/`or`.
+ * Folds to a static verdict when every operand is build-known, else returns a
+ * runtime body over I()/S()/C() plus whether it reads the reactive loop item
+ * (which decides data-wd-each-class vs the global data-wd-class).
+ * @param {string} raw
+ * @param {Ctx} ctx
+ * @param {string} [what] Directive label for error messages.
+ * @returns {{ static: true, value: boolean } | { static: false, body: string, item: boolean }}
+ */
+export function compileWhen(raw: string, ctx: Ctx, what?: string): {
+    static: true;
+    value: boolean;
+} | {
+    static: false;
+    body: string;
+    item: boolean;
+};
+/**
+ * Compile a `:computed` expression into safe JS over the `S(key, path)` reader.
+ * @param {string} raw
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function compileComputedExpr(raw: string, ctx: Ctx): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").Predicate} Predicate
+ */
+export const PREDICATE_OPS: string[];
+export const PREDICATE_JOINERS: string[];
+export type Ctx = import("./context.js").Ctx;
+export type Predicate = import("./context.js").Predicate;

package/types/compiler/reader.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The narrow filesystem surface the compiler needs. Every method takes an
+ * ABSOLUTE path (the compiler resolves includes/assets to absolute paths before
+ * reading), so a reader only has to map absolute paths to bytes/existence.
+ * @typedef {object} Reader
+ * @property {(absPath: string) => string} readText Read a UTF-8 text file. The
+ *   result is ALWAYS LF-normalized: every parser downstream is line-structured
+ *   and LF-shaped, so a CRLF source (Windows, or any `core.autocrlf` checkout)
+ *   would otherwise fail to match delimiters like `---`. A custom reader must
+ *   uphold this.
+ * @property {(absPath: string) => Uint8Array} readBinary Read raw bytes (images).
+ * @property {(absPath: string) => boolean} exists Whether the path exists.
+ * @property {(absPath: string) => string} realpath Canonical path (symlinks
+ *   resolved on a real fs; a no-op normalize in memory) — used for cycle keys.
+ */
+/**
+ * A reader backed by an in-memory map of PROJECT-RELATIVE path → content. Keys
+ * are POSIX, project-relative (e.g. `site/pages/index.wd`, `site/_/nav.wd`);
+ * lookups translate an absolute compile path back to its key via `cwd`. There
+ * are no symlinks in memory, so `realpath` just normalizes. Binary reads are
+ * unsupported (the playground has no image files, and image measuring degrades
+ * to "no dimensions" on a throw), so `readBinary` throws — callers already
+ * try/catch it.
+ * @param {Record<string, string> | Map<string, string>} files
+ * @param {string} [cwd] Virtual project root the keys are relative to.
+ * @returns {Reader}
+ */
+export function memoryReader(files: Record<string, string> | Map<string, string>, cwd?: string): Reader;
+/**
+ * The narrow filesystem surface the compiler needs. Every method takes an
+ * ABSOLUTE path (the compiler resolves includes/assets to absolute paths before
+ * reading), so a reader only has to map absolute paths to bytes/existence.
+ */
+export type Reader = {
+    /**
+     * Read a UTF-8 text file. The
+     * result is ALWAYS LF-normalized: every parser downstream is line-structured
+     * and LF-shaped, so a CRLF source (Windows, or any `core.autocrlf` checkout)
+     * would otherwise fail to match delimiters like `---`. A custom reader must
+     * uphold this.
+     */
+    readText: (absPath: string) => string;
+    /**
+     * Read raw bytes (images).
+     */
+    readBinary: (absPath: string) => Uint8Array;
+    /**
+     * Whether the path exists.
+     */
+    exists: (absPath: string) => boolean;
+    /**
+     * Canonical path (symlinks
+     * resolved on a real fs; a no-op normalize in memory) — used for cycle keys.
+     */
+    realpath: (absPath: string) => string;
+};

package/types/compiler/state.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleState(line: string, ctx: Ctx, index: number): string;
+/**
+ * Register a state key in the current section scope, enabling the runtime.
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Ctx} ctx
+ * @returns {string} The fully-qualified state key.
+ */
+export function declareState(name: string, value: unknown, ctx: Ctx): string;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleStore(line: string, ctx: Ctx, index: number): string;
+/**
+ * Register a page-global store. The bare name is added to `comp.state` so every
+ * resolver (interpolation, :if, @loop, :computed, actions) sees it, and tracked
+ * in `comp.stores` for collision checks. Never section-scoped.
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Ctx} ctx
+ * @returns {string} The store name (also its bare state key).
+ */
+export function declareStore(name: string, value: unknown, ctx: Ctx): string;
+/**
+ * Seed a `<name>_error` state key (null) if absent. Shared by :fetch and the
+ * round-trip :form so error fallbacks have a key to bind.
+ * @param {string} key
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+export function declareErrorState(key: string, ctx: Ctx): void;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleComputed(line: string, ctx: Ctx, index: number): string;
+/**
+ * `: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: string, ctx: Ctx, index: number): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+export const STATE_EXAMPLE: ":state count = 0";
+export const STORE_EXAMPLE: ":store cart = []";
+export const COMPUTED_EXAMPLE: ":computed total = items.length * 4";
+export const THEME_EXAMPLE: ":theme";
+export type Ctx = import("./context.js").Ctx;

package/types/compiler/structure.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleInclude(line: string, ctx: Ctx, index: number): string;
+/**
+ * @param {string} header
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleContainer(header: string, bodyLines: string[], ctx: Ctx, index: number): string;
+/**
+ * `:carousel [autoplay=N]` … `:endcarousel` — a horizontally scroll-snapping
+ * carousel. Contract: each DIRECT child element of the track is one slide, so put
+ * each slide in its own block (e.g. a `::: slide` container) and give that block
+ * the slide sizing in your skin — loose prose lines would each count as a slide.
+ * Registers the `carousel` behavior (prev/next, dot nav, optional autoplay, mouse
+ * drag); native CSS scroll-snap + the page skin handle layout and touch swipe.
+ * `autoplay` is suppressed under `prefers-reduced-motion`. No runtime required.
+ * @param {string} line
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleCarousel(line: string, bodyLines: string[], ctx: Ctx, index: number): string;
+/**
+ * @param {string} line
+ * @param {string[]} truthyLines
+ * @param {string[]} falsyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @param {number} [falsyStart] 0-based index the falsy body starts at in the
+ *   current slice, so nested errors in that branch report the true file line.
+ * @returns {string}
+ */
+export function handleIf(line: string, truthyLines: string[], falsyLines: string[], ctx: Ctx, index: number, falsyStart?: number): string;
+/**
+ * Render the documentation-demo directives (`:try`, `:note`, `:sprint`).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function renderDemoDirective(line: string, ctx: Ctx): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+export const INCLUDE_EXAMPLE: "@include /header.wd";
+export const CONTAINER_EXAMPLE: "::: card .featured";
+export const IF_EXAMPLE: ":if count > 0";
+export const CAROUSEL_EXAMPLE: ":carousel autoplay=3000";
+export type Ctx = import("./context.js").Ctx;

package/types/compiler.d.ts

@@ -1,236 +1,48 @@
 /**
- * Compile a page source file into a full HTML document plus its assets.
+ * Compile a page source file into a full HTML document plus its assets, reading
+ * from the real filesystem by default. Pass `options.reader` to compile against
+ * a different source (see `compileFromMemory`).
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
- * @param {Paths} context Resolved project paths.
+ * @param {import("./config.js").Paths} context Resolved project paths.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
  * @returns {CompiledPage}
  */
-export function compilePage(file: string, context: Paths): CompiledPage;
+export function compilePage(file: string, context: import("./config.js").Paths, options?: {
+    feed?: {
+        href: string;
+        title: string;
+    };
+    collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>;
+    vars?: Record<string, unknown>;
+    reader?: import("./compiler/reader.js").Reader;
+}): CompiledPage;
 /**
- * Compile a source file into its body HTML, frontmatter, and assets (no page shell).
+ * Compile a source file into its body HTML, frontmatter, and assets (no page
+ * shell), reading from the real filesystem by default.
  * @param {string} file Absolute path to the source file.
- * @param {Paths} context Resolved project paths.
+ * @param {import("./config.js").Paths} context Resolved project paths.
  * @param {string[]} [stack] Include stack for cycle detection.
  * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} [collections]
+ * @param {import("./compiler/reader.js").Reader} [reader] Source reader.
  * @returns {CompiledDocument}
  */
-export function compileDocument(file: string, context: Paths, stack?: string[], vars?: Record<string, unknown>): CompiledDocument;
-/**
- * Compile a page from an in-memory map of project-relative path → source, with
- * no filesystem access. `entryPath` is the project-relative path of the page to
- * compile; includes and `@loop` data resolve against the same map.
- * @param {Record<string, string> | Map<string, string>} files
- * @param {string} entryPath
- * @param {{ vars?: Record<string, unknown>, cwd?: string }} [options]
- * @returns {CompiledPage}
- */
-export function compileFromMemory(files: Record<string, string> | Map<string, string>, entryPath: string, options?: {
-    vars?: Record<string, unknown>;
-    cwd?: string;
-}): CompiledPage;
-/**
- * Split a raw file into its frontmatter `meta` and `body`.
- * @param {string} raw Full file contents.
- * @param {string} [file] Source path, used only for error messages.
- * @returns {{ meta: Meta, body: string }}
- */
-export function parseFrontmatter(raw: string, file?: string): {
-    meta: Meta;
-    body: string;
-};
+export function compileDocument(file: string, context: import("./config.js").Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, reader?: import("./compiler/reader.js").Reader): CompiledDocument;
 /**
- * Stable per-render key for a loop row, disambiguating duplicates with `#n`.
- * @param {unknown} item
- * @param {Map<string, number>} counts Mutable seen-count accumulator.
+ * Harden every `<img>` in an assembled page body, reading intrinsic dimensions
+ * from the real filesystem by default.
+ * @param {string} html Assembled page body HTML.
+ * @param {import("./config.js").Paths} paths Resolved project paths.
+ * @param {import("./compiler/reader.js").Reader} [reader] Source reader for image bytes.
  * @returns {string}
  */
-export function loopKeyOf(item: unknown, counts: Map<string, number>): string;
-/**
- * Escape a value for safe inclusion in HTML text and attribute contexts.
- * @param {unknown} value
- * @returns {string}
- */
-export function escapeHtml(value: unknown): string;
-/**
- * A loop offset/limit argument: a non-negative integer literal or a state key.
- */
-export type NumArg = {
-    kind: "literal";
-    value: number;
-} | {
-    kind: "key";
-    value: string;
-};
-/**
- * A compiled `@loop … where` predicate.
- */
-export type Predicate = {
-    /**
-     * Safe JS boolean expression over `I()`/`S()`/`C()`.
-     */
-    body: string;
-    /**
-     * Whether the predicate reads declared state.
-     */
-    refsState: boolean;
-};
-/**
- * Loop clause configuration shared by the static and reactive paths.
- */
-export type LoopOpts = {
-    where: Predicate | null;
-    sort: {
-        key: string;
-        dir: string;
-    } | null;
-    reverse: boolean;
-    offset: NumArg | null;
-    limit: NumArg | null;
-    /**
-     * Empty-branch body lines, if any.
-     */
-    empty: string[] | null;
-    /**
-     * Whether offset/limit reference state.
-     */
-    clauseRefsState: boolean;
-};
-export type Paths = import("./config.js").Paths;
-/**
- * Frontmatter values are scalars or inline arrays of scalars.
- */
-export type FrontmatterValue = string | number | boolean | null | Array<string | number | boolean | null>;
-/**
- * Parsed page frontmatter, keyed by field name.
- */
-export type Meta = Record<string, FrontmatterValue>;
-/**
- * Collected output assets for a compiled document.
- */
-export type Assets = {
-    /**
-     * Public hrefs of compiled skin stylesheets.
-     */
-    skins: Set<string>;
-    /**
-     * Public hrefs of colocated page scripts.
-     */
-    scripts: Set<string>;
-    /**
-     * Source path → public href for emitted assets.
-     */
-    files: Map<string, string>;
-    /**
-     * Whether the reactive runtime is required.
-     */
-    runtime: boolean;
-};
-/**
- * Per-document compilation accumulator shared across includes/sections.
- */
-export type Compilation = {
-    assets: Assets;
-    /**
-     * Declared state keys → initial values.
-     */
-    state: Map<string, unknown>;
-    /**
-     * Page-global store names (a subset of state keys).
-     */
-    stores: Set<string>;
-    /**
-     * Non-fatal authoring hints.
-     */
-    warnings: string[];
-    /**
-     * Counter for auto-generated section ids.
-     */
-    sectionCounter: number;
-};
-/**
- * A lexical scope chain for static interpolation values (include args, loop vars).
- */
-export type Scope = {
-    parent: Scope | null;
-    vars: Record<string, unknown>;
-};
-/**
- * Per-file compile context threaded through the directive handlers.
- */
-export type Ctx = {
-    /**
-     * Absolute path to the file being compiled.
-     */
-    file: string;
-    /**
-     * Resolved project paths.
-     */
-    context: Paths;
-    /**
-     * Include stack (real paths) for cycle detection.
-     */
-    stack: string[];
-    /**
-     * Static value scope chain.
-     */
-    scope: Scope;
-    /**
-     * Shared compilation accumulator.
-     */
-    comp: Compilation;
-    /**
-     * Active section-id scope chain.
-     */
-    sections: string[];
-    /**
-     * Name of the current reactive loop item, if any.
-     */
-    loopItem: string | null;
-    /**
-     * State key of the list being looped, if any.
-     */
-    loopKey?: string | undefined;
-    /**
-     * Inside a loop body, so `$index`/`$first`/… are valid.
-     */
-    loopMeta?: boolean | undefined;
-    /**
-     * Markdown-it instance selected for this file.
-     */
-    md?: MarkdownIt | undefined;
-};
-/**
- * A compiled page document.
- */
-export type CompiledDocument = {
-    meta: Meta;
-    html: string;
-    assets: Assets;
-    warnings: string[];
-};
-/**
- * A compiled page: the document plus its full HTML shell.
- */
-export type CompiledPage = {
-    meta: Meta;
-    html: string;
-    assets: Assets;
-    warnings: string[];
-};
-/**
- * A parsed `:button` action.
- */
-export type Action = {
-    /**
-     * Runtime operation (inc/dec/add/sub/append/prepend/set/toggle/member-toggle/remove/remove-value/clear/merge/delete/reset/append-row).
-     */
-    op: string;
-    /**
-     * State key (possibly dotted) the action mutates.
-     */
-    target: string;
-    /**
-     * Literal value for value-carrying ops.
-     */
-    value?: unknown;
-};
-import MarkdownIt from "markdown-it";
+export function enhanceImages(html: string, paths: import("./config.js").Paths, reader?: import("./compiler/reader.js").Reader): string;
+export type Meta = import("./compiler/context.js").Meta;
+export type FrontmatterValue = import("./compiler/context.js").FrontmatterValue;
+export type Assets = import("./compiler/context.js").Assets;
+export type Compilation = import("./compiler/context.js").Compilation;
+export type Scope = import("./compiler/context.js").Scope;
+export type Ctx = import("./compiler/context.js").Ctx;
+export type CompiledDocument = import("./compiler/context.js").CompiledDocument;
+export type CompiledPage = import("./compiler/context.js").CompiledPage;
+export { compileFromMemory, escapeHtml, loopKeyOf, parseFrontmatter, stampScope } from "./compiler/index.js";

package/types/dev.d.ts

@@ -1,9 +1,54 @@
 /**
- * Inject the dev-client `<script>` before `</body>` (or append it if absent).
+ * Serialize the dev server's rebuilds: at most ONE child build runs at a time.
+ * Every build read-modify-writes the dependency map (`dist/.wd-dev-deps.json`),
+ * so overlapping children could persist a stale map missing deps a concurrent
+ * build just recorded — after which the affected routes silently stop
+ * rebuilding. Changes debounce into a batch; changes arriving MID-build
+ * accumulate into the next batch (duplicate paths coalesce via the Set, and a
+ * `null` — a `src/` change or an unattributable event, forcing a full rebuild —
+ * swallows the whole batch into one full build).
+ * @param {(changed: string[]) => Promise<void> | void} runBuild Runs one child
+ *   build over the changed `site/` paths (`[]` = full rebuild). Build failures
+ *   are its own concern (report + resolve); a rejection still frees the queue.
+ * @param {number} [debounceMs] Debounce window for batching change events.
+ * @returns {{ change: (path: string | null) => void, close: () => void }}
+ */
+export function createRebuildQueue(runBuild: (changed: string[]) => Promise<void> | void, debounceMs?: number): {
+    change: (path: string | null) => void;
+    close: () => void;
+};
+/**
+ * Inject the dev-client `<script>` before `</body>` (or append it if absent),
+ * plus — for a `draft: true` page — an inline draft-banner script. Both are
+ * injected at dev-SERVE time only, so neither ever touches the shipped HTML on
+ * disk (a production build excludes drafts entirely; a `build --drafts` staging
+ * build emits clean HTML with no banner).
  * @param {string} html Page HTML to augment.
+ * @param {{ draft?: boolean }} [options] `draft: true` adds the visible banner.
+ * @returns {string}
+ */
+export function injectDevClient(html: string, options?: {
+    draft?: boolean;
+}): string;
+/**
+ * The inline dev-only draft banner: a fixed bar marking the page as an unpublished
+ * draft, so it's unmistakable in `darkmown dev` that this content is excluded from
+ * a production build. Inert (`pointer-events:none`) and high-z so it never blocks
+ * the page; dev-serve-injected, so it's never in shipped output.
+ * @returns {string}
+ */
+export function draftBannerScript(): string;
+/**
+ * The page the dev server serves for a route with no dist output while the last
+ * build is FAILED — the honest alternative to the production 404 copy, which
+ * would claim the route "is hidden or has not been created" when the real cause
+ * is a compile error. The message renders inline (works without JS) and the
+ * injected dev client replays the `builderror` overlay on connect, then reloads
+ * the real page on the next successful build.
+ * @param {string} message The recorded build failure.
  * @returns {string}
  */
-export function injectDevClient(html: string): string;
+export function buildFailedPage(message: string): string;
 /**
  * The dev-client browser script that opens the SSE channel for live reload.
  * @returns {string}