@nowline/export 0.8.6 → 0.9.0

package/dist/index.d.ts

@@ -1,8 +1,24 @@
+import { type ResolveDiagnostic } from '@nowline/core';
 import type { ResolvedFontPair } from '@nowline/export-core';
-import { type ThemeName } from '@nowline/layout';
+import type { NonWorkingDisplay, ThemeName } from '@nowline/layout';
+import { type StagedRoadmap, type StageInputs, type StageResult } from '@nowline/renderer';
 export type { PdfOrientation, ResolvedFontPair } from '@nowline/export-core';
-export type { ThemeName } from '@nowline/layout';
+export type { NonWorkingDisplay, ThemeName } from '@nowline/layout';
 export { civilDateInZone, type NormalizedZone, normalizeZone, type ResolveTodayOptions, resolveToday, TimezoneError, } from '@nowline/layout';
+export type { StagedRoadmap, StageResult } from '@nowline/renderer';
+/**
+ * Thrown when include resolution reports a wave-rule error (a coded or
+ * `rule: 'wave'` diagnostic, specs/waves.md §6.1) and no other include error.
+ * `message` is the same `@nowline/export: include error in …` text as the
+ * plain include error; `diagnostics` carries every resolver diagnostic, errors
+ * and warnings, so a surface can report the routed ones (see
+ * `isRoutedResolveDiagnostic`) with file and line, like validator diagnostics.
+ * Every other include error stays a plain `Error`.
+ */
+export declare class IncludeResolveError extends Error {
+    readonly diagnostics: ResolveDiagnostic[];
+    constructor(message: string, diagnostics: ResolveDiagnostic[]);
+}
 /** The eight canonical export formats. Every surface produces exactly these. */
 export type ExportFormat = 'svg' | 'png' | 'pdf' | 'html' | 'mermaid' | 'xlsx' | 'msproj' | 'json';
 /**
@@ -46,14 +62,26 @@ export interface RenderInputs {
      * Optional for text-only formats (svg, html, json, mermaid, msproj, xlsx).
      */
     fonts?: ResolvedFontPair;
-    /** Optional fixed canvas width in px. */
+    /** Optional best-effort maximum canvas width in px; unset fits the content. */
     width?: number;
+    /**
+     * How the chart shows a calendar's non-working days (`hide` collapses them,
+     * `show` draws shaded bands). Wins over the file's
+     * `default roadmap non-working:` key; leave it unset (undefined) to let the
+     * key apply, then `hide`. The schedule exporters (mermaid, msproj, xlsx)
+     * take no display input, so their bytes are the same in both views.
+     */
+    nonWorking?: NonWorkingDisplay;
     /** Drop `<a>` links from the rendered SVG. */
     noLinks?: boolean;
     /** Treat render warnings (e.g. missing assets) as hard errors. */
     strict?: boolean;
-    /** PDF page size — a preset name or a custom dimensions string. */
-    pageSize?: string;
+    /**
+     * PDF page size: a preset name, a custom dimensions string, or a value
+     * already parsed with `parsePageSize` (so a caller can reject a bad one
+     * before rendering).
+     */
+    pageSize?: import('@nowline/export-core').PdfPageSize | string;
     /** PDF orientation. */
     orientation?: import('@nowline/export-core').PdfOrientation;
     /** PDF margin in points. */
@@ -62,19 +90,68 @@ export interface RenderInputs {
     pngScale?: number;
     /** MS Project start-date override (YYYY-MM-DD). */
     msprojStart?: string;
+    /**
+     * Called before layout with the routed (wave-rule) resolver diagnostics
+     * when include resolution succeeds, which leaves only warnings (possibly
+     * none). Errors throw `IncludeResolveError` instead. Never affects output.
+     */
+    onResolveDiagnostics?: (diagnostics: ResolveDiagnostic[]) => void;
+    /**
+     * Receives non-fatal notices about the artifact, such as the MS Project
+     * lossy-feature summary. Never affects output. Omit to keep each
+     * exporter's default (stderr), as before.
+     */
+    onNotice?: (message: string) => void;
+    /**
+     * Receives asset warnings, such as a `logo:` file that is missing or
+     * unreadable (the render then proceeds without the logo) or SVG logo
+     * content the sanitizer removed. Under `strict` they throw instead and
+     * this is not called.
+     */
+    onWarning?: (message: string) => void;
+}
+/** What a caller that has already parsed `source` may hand to {@link stageForExport}. */
+export interface StageForExportOptions {
+    /** A document the caller already parsed and validated from `source`. */
+    document?: StageInputs['document'];
+    /** The caller's Langium services, which built `document`. Omitted: the kernel's own. */
+    services?: StageInputs['services'];
 }
+/**
+ * Stage `source` the way the kernel does (`stageRoadmap` with the host's
+ * source and asset reads, laid out with `inputs`) and return the raw result:
+ * `invalid`, `include-error` or `staged`. A surface that reports the stage's
+ * own diagnostics maps them itself, then hands a `staged` result to
+ * {@link exportStaged}; {@link acceptStagedRoadmap} is the kernel's mapping.
+ */
+export declare function stageForExport(source: string, inputs: RenderInputs, host: HostEnv, options?: StageForExportOptions): Promise<StageResult>;
+/**
+ * Map a stage result to the kernel's contract: validation and include errors
+ * throw, routed warnings reach `onResolveDiagnostics`, and logo warnings
+ * reach `onWarning` (or throw under `strict`). Returns the staged roadmap.
+ */
+export declare function acceptStagedRoadmap(stage: StageResult, inputs: RenderInputs): StagedRoadmap;
 /**
  * Produce the export artifact for `source` in `format`. This is the single
  * code path to any exported artifact — no surface re-implements a stage.
+ * It is `stageRoadmap` plus the kernel's error mapping, then `exportStaged`.
  *
  * Text formats (svg / json / html / mermaid / msproj) are returned as UTF-8
  * bytes; binary formats (png / pdf / xlsx) as their native bytes. Returning
  * Uint8Array for every format keeps the determinism gate able to `sha256` one
  * value per (fixture, format).
- *
- * Note: PNG rasterizes via @nowline/export-png (native resvg-js) until s4
- * swaps it to @resvg/resvg-wasm. The `host.loadWasm()` seam is reserved for
- * that swap and is not called here yet.
  */
 export declare function exportDocument(source: string, format: ExportFormat, inputs: RenderInputs, host: HostEnv): Promise<Uint8Array>;
+/**
+ * Export a roadmap the caller already staged with `stageRoadmap`, so a
+ * surface that stages once (for diagnostics or layout insights) does not
+ * parse and lay out again. The stage must have been laid out with the same
+ * theme, today, width, locale and non-working display as `inputs`; a
+ * mismatch throws. The caller owns the stage's own errors and warnings
+ * (`exportDocument` maps them to the kernel's contract first); this applies
+ * `noLinks`, `strict` and `onWarning` to the render only.
+ *
+ * The SVG is rendered only for the formats that use it (svg, html, png, pdf).
+ */
+export declare function exportStaged(stage: StagedRoadmap, format: ExportFormat, inputs: RenderInputs, host: HostEnv): Promise<Uint8Array>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKhE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACH,eAAe,EACf,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,mBAAmB,EACxB,YAAY,EACZ,aAAa,GAChB,MAAM,iBAAiB,CAAC;AAEzB,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnG;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACpB,uFAAuF;IACvF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,oEAAoE;IACpE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,gEAAgE;IAChE,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,yGAAyG;IACzG,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,KAAK,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAGzB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IAGjB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,cAAc,CAAC;IAC5D,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AA2OD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,OAAO,GACd,OAAO,CAAC,UAAU,CAAC,CA2FrB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,7 +1,8 @@
 // @nowline/export — the shared export kernel.
 //
 // The single code path from `.nowline` source to any of the eight export
-// artifacts (parse → resolve includes → layout → renderSvg → format adapter).
+// artifacts (stageRoadmap: parse → resolve includes → load logo → schedule →
+// layout; then renderSvg → format adapter).
 // Every surface — the CLI, the `@nowline/mcp` server, the VS Code extension,
 // and the Free/Pro web apps — runs this same code with the same inputs, so
 // they all produce byte-for-byte identical output for the same source and the
@@ -10,84 +11,47 @@
 // Spec: specs/export-determinism.md (the byte-identity precedent and the
 // HostEnv / RenderInputs contract this surface implements).
 //
-// Plan: s2 implements the kernel pipeline (parse → resolve → layout →
-// renderSvg → format dispatch). s4 swaps export-png to resvg-wasm.
-import { collectDocumentDiagnostics, createNowlineServices, resolveIncludes, } from '@nowline/core';
-import { layoutRoadmap } from '@nowline/layout';
-import { renderSvg } from '@nowline/renderer';
-import { URI } from 'langium';
+// Staging is `@nowline/renderer`'s `stageRoadmap` (specs/surface-options.md
+// §3.3); `exportStaged` exports a roadmap a caller already staged.
+import { createNowlineServices, serializeToJson, } from '@nowline/core';
+import { renderSvg, stageRoadmap, } from '@nowline/renderer';
 export { civilDateInZone, normalizeZone, resolveToday, TimezoneError, } from '@nowline/layout';
+/**
+ * Thrown when include resolution reports a wave-rule error (a coded or
+ * `rule: 'wave'` diagnostic, specs/waves.md §6.1) and no other include error.
+ * `message` is the same `@nowline/export: include error in …` text as the
+ * plain include error; `diagnostics` carries every resolver diagnostic, errors
+ * and warnings, so a surface can report the routed ones (see
+ * `isRoutedResolveDiagnostic`) with file and line, like validator diagnostics.
+ * Every other include error stays a plain `Error`.
+ */
+export class IncludeResolveError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.name = 'IncludeResolveError';
+        this.diagnostics = diagnostics;
+    }
+}
 let cachedServices;
-let docCounter = 0;
 function getExportServices() {
     if (!cachedServices)
         cachedServices = createNowlineServices();
     return cachedServices;
 }
-function freshUri() {
-    // Always mint a fresh URI — re-using one lets Langium mutate the prior
-    // document in place, causing spurious diagnostics on repeated exports.
-    return URI.parse(`memory:///kernel-${++docCounter}.nowline`);
-}
-// ---- Inline JSON serializer ---------------------------------------------------
+// ---- JSON serializer ---------------------------------------------------------
 //
-// Equivalent to packages/cli/src/convert/schema.ts. Inlined here so the kernel
-// has no dependency on @nowline/cli.
-const JSON_SCHEMA_VERSION = '1';
-const CONTAINER_KEYS = new Set(['$container', '$containerProperty', '$containerIndex']);
-const RUNTIME_KEYS = new Set(['$cstNode', '$document']);
-function isAstNode(v) {
-    return (v !== null && typeof v === 'object' && typeof v.$type === 'string');
-}
-function serializeNode(node, includePositions) {
-    const out = { $type: node.$type };
-    if (includePositions && node.$cstNode) {
-        const cst = node.$cstNode;
-        out.$position = {
-            start: {
-                line: cst.range.start.line + 1,
-                column: cst.range.start.character + 1,
-                offset: cst.offset,
-            },
-            end: {
-                line: cst.range.end.line + 1,
-                column: cst.range.end.character + 1,
-                offset: cst.end,
-            },
-        };
-    }
-    for (const [key, value] of Object.entries(node)) {
-        if (key.startsWith('$') || CONTAINER_KEYS.has(key) || RUNTIME_KEYS.has(key))
-            continue;
-        out[key] = serializeValue(value, includePositions);
-    }
-    return out;
-}
-function serializeValue(value, includePositions) {
-    if (value === null || value === undefined)
-        return value;
-    if (Array.isArray(value))
-        return value.map((v) => serializeValue(v, includePositions));
-    if (isAstNode(value))
-        return serializeNode(value, includePositions);
-    if (typeof value === 'object') {
-        const out = {};
-        for (const [k, v] of Object.entries(value)) {
-            if (k.startsWith('$') || CONTAINER_KEYS.has(k) || RUNTIME_KEYS.has(k))
-                continue;
-            out[k] = serializeValue(v, includePositions);
-        }
-        return out;
-    }
-    return value;
-}
+// Delegates to core's `serializeToJson`. The one envelope difference: the
+// stage parses from a synthetic `memory:///stage-N.nowline` URI, so it
+// overrides `file.uri` with the raw `file://${sourcePath}` concatenation —
+// not `URI.file()`, which would percent-encode and change the bytes the
+// determinism gate hashes.
 function serializeDocumentToJson(document, source, sourcePath) {
-    const ast = document.parseResult.value;
-    return JSON.stringify({
-        $nowlineSchema: JSON_SCHEMA_VERSION,
-        file: { uri: `file://${sourcePath}`, source },
-        ast: serializeNode(ast, true),
-    }, null, 2);
+    const doc = serializeToJson(document, source, {
+        includePositions: true,
+        uri: `file://${sourcePath}`,
+    });
+    return JSON.stringify(doc, null, 2);
 }
 // ---- MIME inference ----------------------------------------------------------
 function guessMime(ref) {
@@ -102,23 +66,46 @@ function guessMime(ref) {
         return 'image/webp';
     return 'application/octet-stream';
 }
-/**
- * Pin the renderer's per-role families to the resolved fonts' real family
- * names so raster/preview SVG names exactly the bundled face. `serif` maps to
- * the sans family: the resolver has no serif role and raster already falls
- * back serif->sans (resvg has no serif face loaded), so this is behavior-
- * preserving while making the SVG explicit.
- */
-function pinnedFamilies(fonts) {
-    return { sans: fonts.sans.name, serif: fonts.sans.name, mono: fonts.mono.name };
+function hostAssetResolver(host) {
+    return async (ref) => {
+        const bytes = await host.readAsset(ref);
+        return { bytes, mime: guessMime(ref) };
+    };
 }
-async function stageDocument(source, inputs, host) {
-    const services = getExportServices();
-    const uri = freshUri();
-    const doc = services.shared.workspace.LangiumDocumentFactory.fromString(source, uri);
-    await services.shared.workspace.DocumentBuilder.build([doc], { validation: true });
+// ---- Argument checks ---------------------------------------------------------
+function checkHostAndInputs(host, inputs) {
+    if (typeof host?.readSource !== 'function' ||
+        typeof host.readAsset !== 'function' ||
+        typeof host.loadWasm !== 'function') {
+        throw new TypeError('@nowline/export: host must implement the HostEnv interface.');
+    }
+    if (!(inputs?.today instanceof Date) && inputs?.today !== undefined) {
+        throw new TypeError('@nowline/export: inputs.today must be a Date (UTC midnight) or undefined.');
+    }
+    if (typeof inputs?.sourcePath !== 'string' || inputs.sourcePath.length === 0) {
+        throw new TypeError('@nowline/export: inputs.sourcePath must be a non-empty string.');
+    }
+}
+const STAGE_LAYOUT_KEYS = ['theme', 'today', 'width', 'locale', 'nonWorking'];
+function sameLayoutValue(a, b) {
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    return a === b;
+}
+/** A stage laid out with other options would export a different chart than `inputs` asks for. */
+function checkStageMatches(stage, inputs) {
+    for (const key of STAGE_LAYOUT_KEYS) {
+        if (!sameLayoutValue(stage.layout[key], inputs[key])) {
+            throw new Error(`@nowline/export: the staged roadmap was laid out with a different ${key} than inputs.${key}.`);
+        }
+    }
+}
+// ---- Staging -----------------------------------------------------------------
+/** Lexer, parser and validator error messages, in document order. */
+function errorMessages(diagnostics) {
     const errors = [];
-    for (const raw of collectDocumentDiagnostics(doc)) {
+    for (const raw of diagnostics) {
         if (raw.origin === 'lexer') {
             errors.push(raw.error.message);
         }
@@ -129,58 +116,92 @@ async function stageDocument(source, inputs, host) {
             errors.push(raw.diagnostic.message);
         }
     }
-    if (errors.length > 0) {
-        throw new Error(`@nowline/export: validation errors in ${inputs.sourcePath}: ${errors.join('; ')}`);
-    }
-    const ast = doc.parseResult.value;
-    const resolved = await resolveIncludes(ast, inputs.sourcePath, {
-        services: services.Nowline,
-        readFile: host.readSource.bind(host),
+    return errors;
+}
+/**
+ * Stage `source` the way the kernel does (`stageRoadmap` with the host's
+ * source and asset reads, laid out with `inputs`) and return the raw result:
+ * `invalid`, `include-error` or `staged`. A surface that reports the stage's
+ * own diagnostics maps them itself, then hands a `staged` result to
+ * {@link exportStaged}; {@link acceptStagedRoadmap} is the kernel's mapping.
+ */
+export function stageForExport(source, inputs, host, options = {}) {
+    return stageRoadmap({
+        source,
+        sourcePath: inputs.sourcePath,
+        services: options.services ?? getExportServices(),
+        readSource: host.readSource.bind(host),
+        assetResolver: hostAssetResolver(host),
+        document: options.document,
+        layout: inputs,
     });
-    for (const diag of resolved.diagnostics) {
-        if (diag.severity === 'error') {
-            throw new Error(`@nowline/export: include error in ${inputs.sourcePath}: ${diag.message}`);
-        }
+}
+/**
+ * Map a stage result to the kernel's contract: validation and include errors
+ * throw, routed warnings reach `onResolveDiagnostics`, and logo warnings
+ * reach `onWarning` (or throw under `strict`). Returns the staged roadmap.
+ */
+export function acceptStagedRoadmap(stage, inputs) {
+    if (stage.kind === 'invalid') {
+        throw new Error(`@nowline/export: validation errors in ${inputs.sourcePath}: ${errorMessages(stage.diagnostics).join('; ')}`);
     }
-    const model = layoutRoadmap(ast, resolved, {
-        theme: inputs.theme,
-        today: inputs.today,
-        width: inputs.width,
-        locale: inputs.locale,
+    // Include errors are more fundamental than wave-rule errors: any of them
+    // keeps the plain throw. Wave-rule errors alone travel on a typed error.
+    const includeError = (diag) => `@nowline/export: include error in ${inputs.sourcePath}: ${diag.message}`;
+    if (stage.kind === 'include-error') {
+        if (stage.legacy)
+            throw new Error(includeError(stage.legacy));
+        const firstError = stage.routed.filter((d) => d.severity === 'error')[0];
+        throw new IncludeResolveError(includeError(firstError), stage.resolved.diagnostics);
+    }
+    inputs.onResolveDiagnostics?.(stage.routed);
+    // A failed logo load warns (throws under strict); the stage laid out as
+    // if no logo were declared.
+    if (inputs.strict && stage.warnings.length > 0) {
+        throw new Error(`@nowline/export: render warnings (--strict): ${stage.warnings.join('; ')}`);
+    }
+    for (const msg of stage.warnings)
+        inputs.onWarning?.(msg);
+    return stage;
+}
+/** Stage `source` and map the result to the kernel's contract. */
+async function stageDocument(source, inputs, host) {
+    return acceptStagedRoadmap(await stageForExport(source, inputs, host), inputs);
+}
+// ---- Rendering ---------------------------------------------------------------
+/**
+ * Pin the renderer's per-role families to the resolved fonts' real family
+ * names so raster/preview SVG names exactly the bundled face. `serif` maps to
+ * the sans family: the resolver has no serif role and raster already falls
+ * back serif->sans (resvg has no serif face loaded), so this is behavior-
+ * preserving while making the SVG explicit.
+ */
+function pinnedFamilies(fonts) {
+    return { sans: fonts.sans.name, serif: fonts.sans.name, mono: fonts.mono.name };
+}
+/**
+ * Render the staged model. The portable render (no `fontFamilies`, the
+ * FONT_STACK) reports non-strict warnings to `onWarning`; a font-pinned
+ * raster re-render does not repeat them. Every render embeds the stage's
+ * logo bytes, so the logo is read once.
+ */
+async function renderStaged(stage, inputs, assetResolver, fontFamilies) {
+    const warnings = [];
+    const svg = await renderSvg(stage.model, {
+        assetResolver,
+        logo: stage.logo,
+        noLinks: inputs.noLinks ?? false,
+        strict: inputs.strict ?? false,
+        warn: (msg) => warnings.push(msg),
+        fontFamilies,
     });
-    const assetResolver = async (ref) => {
-        const bytes = await host.readAsset(ref);
-        return { bytes, mime: guessMime(ref) };
-    };
-    const renderWith = async (fontFamilies) => {
-        const warnings = [];
-        const svg = await renderSvg(model, {
-            assetResolver,
-            noLinks: inputs.noLinks ?? false,
-            strict: inputs.strict ?? false,
-            warn: (msg) => warnings.push(msg),
-            fontFamilies,
-        });
-        if (inputs.strict && warnings.length > 0) {
-            throw new Error(`@nowline/export: render warnings (--strict): ${warnings.join('; ')}`);
-        }
-        return svg;
-    };
-    // Portable render (FONT_STACK) for the svg/html file exports.
-    const svg = await renderWith();
-    return {
-        svg,
-        renderWith: (fontFamilies) => renderWith(fontFamilies),
-        exportInputs: {
-            model,
-            ast,
-            resolved,
-            sourcePath: inputs.sourcePath,
-            today: inputs.today,
-        },
-        document: doc,
-        source,
-    };
+    if (inputs.strict && warnings.length > 0) {
+        throw new Error(`@nowline/export: render warnings (--strict): ${warnings.join('; ')}`);
+    }
+    if (!fontFamilies)
+        for (const msg of warnings)
+            inputs.onWarning?.(msg);
+    return svg;
 }
 // ---- Text encoding -----------------------------------------------------------
 const encoder = new TextEncoder();
@@ -191,61 +212,81 @@ function toUtf8(text) {
 /**
  * Produce the export artifact for `source` in `format`. This is the single
  * code path to any exported artifact — no surface re-implements a stage.
+ * It is `stageRoadmap` plus the kernel's error mapping, then `exportStaged`.
  *
  * Text formats (svg / json / html / mermaid / msproj) are returned as UTF-8
  * bytes; binary formats (png / pdf / xlsx) as their native bytes. Returning
  * Uint8Array for every format keeps the determinism gate able to `sha256` one
  * value per (fixture, format).
- *
- * Note: PNG rasterizes via @nowline/export-png (native resvg-js) until s4
- * swaps it to @resvg/resvg-wasm. The `host.loadWasm()` seam is reserved for
- * that swap and is not called here yet.
  */
 export async function exportDocument(source, format, inputs, host) {
     if (typeof source !== 'string') {
         throw new TypeError('@nowline/export: source must be a string.');
     }
-    if (typeof host?.readSource !== 'function' ||
-        typeof host.readAsset !== 'function' ||
-        typeof host.loadWasm !== 'function') {
-        throw new TypeError('@nowline/export: host must implement the HostEnv interface.');
-    }
-    if (!(inputs?.today instanceof Date) && inputs?.today !== undefined) {
-        throw new TypeError('@nowline/export: inputs.today must be a Date (UTC midnight) or undefined.');
-    }
-    if (typeof inputs?.sourcePath !== 'string' || inputs.sourcePath.length === 0) {
-        throw new TypeError('@nowline/export: inputs.sourcePath must be a non-empty string.');
-    }
+    checkHostAndInputs(host, inputs);
     const stage = await stageDocument(source, inputs, host);
+    return exportStaged(stage, format, inputs, host);
+}
+/**
+ * Export a roadmap the caller already staged with `stageRoadmap`, so a
+ * surface that stages once (for diagnostics or layout insights) does not
+ * parse and lay out again. The stage must have been laid out with the same
+ * theme, today, width, locale and non-working display as `inputs`; a
+ * mismatch throws. The caller owns the stage's own errors and warnings
+ * (`exportDocument` maps them to the kernel's contract first); this applies
+ * `noLinks`, `strict` and `onWarning` to the render only.
+ *
+ * The SVG is rendered only for the formats that use it (svg, html, png, pdf).
+ */
+export async function exportStaged(stage, format, inputs, host) {
+    checkHostAndInputs(host, inputs);
+    checkStageMatches(stage, inputs);
+    const assetResolver = hostAssetResolver(host);
+    const portableSvg = () => renderStaged(stage, inputs, assetResolver);
+    const rasterSvg = (fonts) => renderStaged(stage, inputs, assetResolver, pinnedFamilies(fonts));
+    const exportInputs = {
+        model: stage.model,
+        ast: stage.ast,
+        resolved: stage.resolved,
+        schedule: stage.schedule,
+        sourcePath: inputs.sourcePath,
+        today: inputs.today,
+    };
     if (format === 'svg') {
-        return toUtf8(stage.svg);
+        return toUtf8(await portableSvg());
     }
     if (format === 'json') {
-        return toUtf8(serializeDocumentToJson(stage.document, stage.source, inputs.sourcePath));
+        const source = stage.document.textDocument.getText();
+        return toUtf8(serializeDocumentToJson(stage.document, source, inputs.sourcePath));
     }
     if (format === 'html') {
+        const svg = await portableSvg();
         const mod = await import('@nowline/export-html');
-        const html = await mod.exportHtml(stage.exportInputs, stage.svg);
+        const html = await mod.exportHtml(exportInputs, svg);
         return toUtf8(html);
     }
     if (format === 'mermaid') {
         const mod = await import('@nowline/export-mermaid');
-        const md = mod.exportMermaid(stage.exportInputs);
+        const md = mod.exportMermaid(exportInputs);
         return toUtf8(md);
     }
     if (format === 'msproj') {
         const mod = await import('@nowline/export-msproj');
-        const xml = mod.exportMsProjXml(stage.exportInputs, {
+        const xml = mod.exportMsProjXml(exportInputs, {
             startDate: inputs.msprojStart,
+            onLossy: inputs.onNotice,
         });
         return toUtf8(xml);
     }
     if (format === 'xlsx') {
         const mod = await import('@nowline/export-xlsx');
-        const bytes = await mod.exportXlsx(stage.exportInputs, { generated: inputs.today });
+        const bytes = await mod.exportXlsx(exportInputs, { generated: inputs.today });
         return bytes;
     }
     if (format === 'png') {
+        // The portable render still runs first: its warnings reach
+        // `onWarning` (or throw under strict) before any raster work.
+        await portableSvg();
         if (!inputs.fonts) {
             throw new TypeError('@nowline/export: inputs.fonts is required for png format.');
         }
@@ -254,22 +295,23 @@ export async function exportDocument(source, format, inputs, host) {
         await pngMod.initPngWasm(wasmBytes);
         // Raster with the pinned bundled family so the SVG resvg rasterizes
         // names exactly the embedded font (matches the live preview).
-        const rasterSvg = await stage.renderWith(pinnedFamilies(inputs.fonts));
-        const bytes = await pngMod.exportPng(stage.exportInputs, rasterSvg, {
+        const svg = await rasterSvg(inputs.fonts);
+        const bytes = await pngMod.exportPng(exportInputs, svg, {
             scale: inputs.pngScale ?? 2,
             fonts: inputs.fonts,
         });
         return bytes;
     }
     if (format === 'pdf') {
+        await portableSvg();
         if (!inputs.fonts) {
             throw new TypeError('@nowline/export: inputs.fonts is required for pdf format.');
         }
         const mod = await import('@nowline/export-pdf');
         // Same pinned-family raster SVG as PNG so PDF text names the embedded
         // font explicitly and stays consistent with preview + PNG.
-        const rasterSvg = await stage.renderWith(pinnedFamilies(inputs.fonts));
-        const bytes = await mod.exportPdf(stage.exportInputs, rasterSvg, {
+        const svg = await rasterSvg(inputs.fonts);
+        const bytes = await mod.exportPdf(exportInputs, svg, {
             pageSize: inputs.pageSize,
             orientation: inputs.orientation,
             marginPt: inputs.marginPt,