@nowline/embed 0.2.2

package/dist/pipeline.d.ts

@@ -0,0 +1,28 @@
+import { type NowlineFile } from '@nowline/core';
+import { type ThemeName } from '@nowline/layout';
+export interface EmbedRenderOptions {
+    theme?: ThemeName;
+    today?: Date;
+    locale?: string;
+    width?: number;
+    /**
+     * Override the deterministic id prefix used for in-SVG `<style>`
+     * scoping. Each block on a page should use a unique prefix so two
+     * roadmaps cannot bleed styles into each other; the auto-scan path
+     * generates a per-block prefix and threads it here.
+     */
+    idPrefix?: string;
+}
+export interface EmbedParseResult {
+    ast: NowlineFile;
+    /** Lexer + parser + Langium validation diagnostics, normalized to strings. */
+    errors: string[];
+}
+export declare function parseSource(source: string): Promise<EmbedParseResult>;
+export declare function renderSource(source: string, options?: EmbedRenderOptions): Promise<string>;
+export declare class EmbedRenderError extends Error {
+    readonly details: string[];
+    constructor(message: string, details: string[]);
+}
+export declare function __resetEmbedPipelineForTests(): void;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAOA,OAAO,EAEH,KAAK,WAAW,EAGnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKhE,MAAM,WAAW,kBAAkB;IAC/B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC7B,GAAG,EAAE,WAAW,CAAC;IACjB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAoBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAa3E;AAED,wBAAsB,YAAY,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,MAAM,CAAC,CAiDjB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aAGnB,OAAO,EAAE,MAAM,EAAE;gBADjC,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,EAAE;CAKxC;AAKD,wBAAgB,4BAA4B,IAAI,IAAI,CAInD"}

package/dist/pipeline.js

@@ -0,0 +1,94 @@
+// Render pipeline shared by `nowline.render(source)` and the auto-scan
+// path. Mirrors the shape of `packages/vscode-extension/src/preview/
+// render-pipeline.ts` but stripped of every Node-only dependency: no
+// `fs`, no `path`, no asset resolver. Includes are resolved against a
+// no-op `readFile` so a file containing `include "./other.nowline"`
+// renders the parts that survive without a network fetch.
+import { createNowlineServices, resolveIncludes, } from '@nowline/core';
+import { layoutRoadmap } from '@nowline/layout';
+import { renderSvg } from '@nowline/renderer';
+import { URI } from 'langium';
+import { isNoOpIncludeDiagnosticMessage, noOpIncludeReadFile } from './no-op-include-resolver.js';
+let cachedServices;
+let docCounter = 0;
+let includeWarningEmitted = false;
+function getServices() {
+    if (!cachedServices)
+        cachedServices = createNowlineServices();
+    return cachedServices;
+}
+function freshUri() {
+    return URI.parse(`memory:///nowline-embed-${++docCounter}.nowline`);
+}
+export async function parseSource(source) {
+    const services = getServices();
+    const docFactory = services.shared.workspace.LangiumDocumentFactory;
+    const doc = docFactory.fromString(source, freshUri());
+    await services.shared.workspace.DocumentBuilder.build([doc], { validation: true });
+    const errors = [];
+    for (const e of doc.parseResult.lexerErrors)
+        errors.push(e.message);
+    for (const e of doc.parseResult.parserErrors)
+        errors.push(e.message);
+    for (const d of doc.diagnostics ?? []) {
+        if (d.severity === 1)
+            errors.push(d.message);
+    }
+    return { ast: doc.parseResult.value, errors };
+}
+export async function renderSource(source, options = {}) {
+    const parsed = await parseSource(source);
+    if (parsed.errors.length > 0) {
+        throw new EmbedRenderError(`Failed to parse Nowline source: ${parsed.errors.join('; ')}`, parsed.errors);
+    }
+    const services = getServices();
+    const resolved = await resolveIncludes(parsed.ast, '/embed.nowline', {
+        services: services.Nowline,
+        readFile: noOpIncludeReadFile,
+    });
+    let sawIncludeWarning = false;
+    const blockingErrors = [];
+    for (const diag of resolved.diagnostics) {
+        if (diag.severity !== 'error')
+            continue;
+        if (isNoOpIncludeDiagnosticMessage(diag.message)) {
+            sawIncludeWarning = true;
+            continue;
+        }
+        blockingErrors.push(diag.message);
+    }
+    if (blockingErrors.length > 0) {
+        throw new EmbedRenderError(`Failed to resolve Nowline source: ${blockingErrors.join('; ')}`, blockingErrors);
+    }
+    if (sawIncludeWarning && !includeWarningEmitted) {
+        includeWarningEmitted = true;
+        console.warn('nowline: `include` directives are skipped in the browser embed (single-file mode). ' +
+            'Render multi-file roadmaps with the CLI or the GitHub Action.');
+    }
+    const model = layoutRoadmap(parsed.ast, resolved, {
+        theme: options.theme,
+        today: options.today,
+        locale: options.locale,
+        width: options.width,
+    });
+    return renderSvg(model, {
+        idPrefix: options.idPrefix,
+    });
+}
+export class EmbedRenderError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'EmbedRenderError';
+    }
+}
+// Test-only escape hatch. The console.warn is intentionally emitted at
+// most once per page load; tests that exercise the warning path need to
+// reset the latch between cases.
+export function __resetEmbedPipelineForTests() {
+    includeWarningEmitted = false;
+    cachedServices = undefined;
+    docCounter = 0;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,oEAAoE;AACpE,0DAA0D;AAE1D,OAAO,EACH,qBAAqB,EAGrB,eAAe,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAkB,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AA2BlG,IAAI,cAA0C,CAAC;AAC/C,IAAI,UAAU,GAAG,CAAC,CAAC;AACnB,IAAI,qBAAqB,GAAG,KAAK,CAAC;AAElC,SAAS,WAAW;IAChB,IAAI,CAAC,cAAc;QAAE,cAAc,GAAG,qBAAqB,EAAE,CAAC;IAC9D,OAAO,cAAc,CAAC;AAC1B,CAAC;AAED,SAAS,QAAQ;IACb,OAAO,GAAG,CAAC,KAAK,CAAC,2BAA2B,EAAE,UAAU,UAAU,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAc;IAC5C,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,sBAAsB,CAAC;IACpE,MAAM,GAAG,GAAG,UAAU,CAAC,UAAU,CAAc,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnE,MAAM,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAEnF,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,WAAW;QAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,YAAY;QAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACrE,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;QACpC,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAC9B,MAAc,EACd,UAA8B,EAAE;IAEhC,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,gBAAgB,CACtB,mCAAmC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC7D,MAAM,CAAC,MAAM,CAChB,CAAC;IACN,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,GAAG,EAAE,gBAAgB,EAAE;QACjE,QAAQ,EAAE,QAAQ,CAAC,OAAO;QAC1B,QAAQ,EAAE,mBAAmB;KAChC,CAAC,CAAC;IAEH,IAAI,iBAAiB,GAAG,KAAK,CAAC;IAC9B,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;YAAE,SAAS;QACxC,IAAI,8BAA8B,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/C,iBAAiB,GAAG,IAAI,CAAC;YACzB,SAAS;QACb,CAAC;QACD,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,gBAAgB,CACtB,qCAAqC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAChE,cAAc,CACjB,CAAC;IACN,CAAC;IACD,IAAI,iBAAiB,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC9C,qBAAqB,GAAG,IAAI,CAAC;QAC7B,OAAO,CAAC,IAAI,CACR,qFAAqF;YACjF,+DAA+D,CACtE,CAAC;IACN,CAAC;IAED,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE;QAC9C,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK;KACvB,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC,KAAK,EAAE;QACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC7B,CAAC,CAAC;AACP,CAAC;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAGnB;IAFpB,YACI,OAAe,EACC,OAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,YAAO,GAAP,OAAO,CAAU;QAGjC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACnC,CAAC;CACJ;AAED,uEAAuE;AACvE,wEAAwE;AACxE,iCAAiC;AACjC,MAAM,UAAU,4BAA4B;IACxC,qBAAqB,GAAG,KAAK,CAAC;IAC9B,cAAc,GAAG,SAAS,CAAC;IAC3B,UAAU,GAAG,CAAC,CAAC;AACnB,CAAC"}

package/dist/theme.d.ts

@@ -0,0 +1,5 @@
+import type { ThemeName } from '@nowline/layout';
+export type EmbedTheme = ThemeName | 'auto';
+export declare function resolveSystemTheme(): ThemeName;
+export declare function effectiveTheme(theme: EmbedTheme | undefined, systemTheme: ThemeName): ThemeName;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5C,wBAAgB,kBAAkB,IAAI,SAAS,CAS9C;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,WAAW,EAAE,SAAS,GAAG,SAAS,CAG/F"}

package/dist/theme.js

@@ -0,0 +1,32 @@
+// Theme resolution for the embed.
+//
+// Precedence (highest to lowest):
+//   1. `initialize({ theme })` flag (light / dark / auto).
+//   2. The file's own `nowline v1 theme:` directive — handled inside
+//      layout, so we just don't override it when the embed config says
+//      `'auto'` and we have no system preference reading.
+//   3. The browser's `prefers-color-scheme` media query.
+//
+// `prefers-color-scheme` is read **once on init**, not reactively, so
+// flipping the OS theme mid-session does not cause every embedded
+// roadmap on the page to repaint. This matches Mermaid's posture and
+// keeps the embed deterministic for screenshot tools.
+export function resolveSystemTheme() {
+    if (typeof globalThis === 'undefined')
+        return 'light';
+    const win = globalThis.matchMedia;
+    if (typeof win !== 'function')
+        return 'light';
+    try {
+        return win('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+    catch {
+        return 'light';
+    }
+}
+export function effectiveTheme(theme, systemTheme) {
+    if (theme === 'light' || theme === 'dark')
+        return theme;
+    return systemTheme;
+}
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,kCAAkC;AAClC,2DAA2D;AAC3D,qEAAqE;AACrE,uEAAuE;AACvE,0DAA0D;AAC1D,yDAAyD;AACzD,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,qEAAqE;AACrE,sDAAsD;AAMtD,MAAM,UAAU,kBAAkB;IAC9B,IAAI,OAAO,UAAU,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IACtD,MAAM,GAAG,GAAI,UAAmE,CAAC,UAAU,CAAC;IAC5F,IAAI,OAAO,GAAG,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC;IAC9C,IAAI,CAAC;QACD,OAAO,GAAG,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,OAAO,CAAC;IACnB,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAA6B,EAAE,WAAsB;IAChF,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,WAAW,CAAC;AACvB,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nowline/embed",
+  "version": "0.2.2",
+  "description": "Browser embed bundle for Nowline. Drop a <script> tag and ```nowline``` blocks render in place.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lolay/nowline.git",
+    "directory": "packages/embed"
+  },
+  "homepage": "https://github.com/lolay/nowline",
+  "bugs": {
+    "url": "https://github.com/lolay/nowline/issues"
+  },
+  "keywords": [
+    "nowline",
+    "roadmap",
+    "gantt",
+    "embed",
+    "browser",
+    "cdn"
+  ],
+  "dependencies": {
+    "langium": "~4.2.2",
+    "@nowline/layout": "0.2.2",
+    "@nowline/core": "0.2.2",
+    "@nowline/renderer": "0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.0",
+    "happy-dom": "^15.11.0",
+    "typescript": "~5.7.0",
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json && node scripts/bundle.mjs",
+    "watch": "tsc -b tsconfig.json --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "bundle": "node scripts/bundle.mjs",
+    "check-size": "node scripts/check-size.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/auto-scan.ts

@@ -0,0 +1,107 @@
+// DOM scanner that finds `<pre><code class="language-nowline">…</code></pre>`
+// blocks (or whatever selector the caller registered) and replaces each
+// with its rendered SVG. Each block gets a unique `idPrefix` so two
+// roadmaps on the same page never share `<style>` ids.
+
+import type { ThemeName } from '@nowline/layout';
+import { type EmbedRenderOptions, renderSource } from './pipeline.js';
+
+export interface AutoScanInputs {
+    selector: string;
+    theme?: ThemeName;
+    locale?: string;
+    width?: number;
+    today?: Date;
+    /**
+     * Document to scan. Defaults to `globalThis.document`. Tests inject
+     * a happy-dom document; the IIFE running on a real page picks up
+     * the live document.
+     */
+    document?: Document;
+}
+
+export interface AutoScanResult {
+    /** Number of code blocks that were successfully replaced with SVG. */
+    rendered: number;
+    /** Number of blocks that failed to render (logged to console.error). */
+    failed: number;
+}
+
+let runCounter = 0;
+
+export async function runAutoScan(inputs: AutoScanInputs): Promise<AutoScanResult> {
+    const doc = inputs.document ?? (globalThis as { document?: Document }).document;
+    if (!doc) {
+        return { rendered: 0, failed: 0 };
+    }
+
+    const blocks = doc.querySelectorAll<HTMLElement>(inputs.selector);
+    let rendered = 0;
+    let failed = 0;
+    const baseRunId = ++runCounter;
+
+    const tasks: Array<Promise<void>> = [];
+    let blockIndex = 0;
+    for (const code of Array.from(blocks)) {
+        const target = pickReplacementTarget(code);
+        if (!target) {
+            continue;
+        }
+        const source = readBlockSource(code);
+        const idPrefix = `nl-r${baseRunId}-${blockIndex++}`;
+        const opts: EmbedRenderOptions = {
+            theme: inputs.theme,
+            locale: inputs.locale,
+            width: inputs.width,
+            today: inputs.today,
+            idPrefix,
+        };
+        tasks.push(
+            renderSource(source, opts).then(
+                (svg) => {
+                    replaceWithSvg(target, svg);
+                    rendered++;
+                },
+                (err: unknown) => {
+                    failed++;
+                    console.error('nowline: render failed', err);
+                },
+            ),
+        );
+    }
+
+    await Promise.all(tasks);
+    return { rendered, failed };
+}
+
+// Markdown-rendered Nowline blocks usually look like
+// `<pre><code class="language-nowline">…</code></pre>`. We replace the
+// outer `<pre>` so the spacing the markdown processor reserved for the
+// fenced block is reused by the SVG. When the matched element has no
+// `<pre>` ancestor (custom hosting) we replace the matched element
+// itself.
+function pickReplacementTarget(matched: HTMLElement): HTMLElement | null {
+    const parent = matched.parentElement;
+    if (parent && parent.tagName.toUpperCase() === 'PRE') {
+        return parent;
+    }
+    return matched;
+}
+
+function readBlockSource(code: HTMLElement): string {
+    // `textContent` preserves whitespace and newlines; `innerText` would
+    // collapse them per CSS, which would corrupt indentation-sensitive
+    // .nowline source.
+    return code.textContent ?? '';
+}
+
+function replaceWithSvg(target: HTMLElement, svg: string): void {
+    // `outerHTML` parses the SVG string into a real `<svg>` element and
+    // swaps it into the DOM, preserving each render's per-`idPrefix`
+    // `<style>` scope so two blocks on the page can never bleed styles.
+    target.outerHTML = svg;
+}
+
+export function __resetAutoScanForTests(): void {
+    runCounter = 0;
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+// Public API for `@nowline/embed`. Mirrors Mermaid's surface
+// (`initialize`, `render`, `parse`, `init`/`run`) so users coming from
+// Mermaid don't have to relearn anything.
+//
+// The IIFE bundle exposes everything below as `window.nowline.*`. ESM
+// consumers import named exports from the package root.
+
+import {
+    __resetAutoScanForTests,
+    type AutoScanInputs,
+    type AutoScanResult,
+    runAutoScan,
+} from './auto-scan.js';
+import {
+    __resetEmbedPipelineForTests,
+    type EmbedParseResult,
+    EmbedRenderError,
+    type EmbedRenderOptions,
+    parseSource,
+    renderSource,
+} from './pipeline.js';
+import { type EmbedTheme, effectiveTheme, resolveSystemTheme } from './theme.js';
+
+export { type AutoScanResult, type EmbedParseResult, EmbedRenderError, type EmbedTheme };
+
+const DEFAULT_SELECTOR = 'pre code.language-nowline, code.language-nowline';
+
+export interface InitializeOptions {
+    /** `light`, `dark`, or `auto` (read once via `prefers-color-scheme`). */
+    theme?: EmbedTheme;
+    /**
+     * Auto-run `init()` on `DOMContentLoaded`. Defaults to `true`.
+     * Setting this to `false` defers rendering until the page calls
+     * `nowline.init()` (or `nowline.run()`) manually.
+     */
+    startOnLoad?: boolean;
+    /**
+     * CSS selector used to locate Nowline blocks. The default matches
+     * markdown-renderer output (`<pre><code class="language-nowline">…</code></pre>`)
+     * plus standalone `<code class="language-nowline">` for hosts that
+     * skip the `<pre>` wrapper.
+     */
+    selector?: string;
+    /** BCP-47 locale forwarded to the layout engine for axis labels and the now-pill. */
+    locale?: string;
+    /** Layout canvas width in pixels. Layout's default is 1280. */
+    width?: number;
+    /** Pin a `today` for deterministic snapshots; defaults to live `new Date()` per render. */
+    today?: Date;
+}
+
+interface ResolvedConfig {
+    theme: EmbedTheme;
+    startOnLoad: boolean;
+    selector: string;
+    locale?: string;
+    width?: number;
+    today?: Date;
+    /** System theme captured at init; not reactive to OS theme flips mid-session. */
+    systemTheme: 'light' | 'dark';
+}
+
+const initialConfig: ResolvedConfig = {
+    theme: 'auto',
+    startOnLoad: true,
+    selector: DEFAULT_SELECTOR,
+    systemTheme: resolveSystemTheme(),
+};
+
+let config: ResolvedConfig = { ...initialConfig };
+let autoStartScheduled = false;
+
+export function initialize(options: InitializeOptions = {}): void {
+    config = {
+        theme: options.theme ?? config.theme,
+        startOnLoad: options.startOnLoad ?? config.startOnLoad,
+        selector: options.selector ?? config.selector,
+        locale: options.locale ?? config.locale,
+        width: options.width ?? config.width,
+        today: options.today ?? config.today,
+        // Re-read `prefers-color-scheme` on every initialize() so callers
+        // who explicitly want the latest system theme can ask for it by
+        // calling initialize() again. Auto-scan paths still use the value
+        // captured at initialize time.
+        systemTheme: resolveSystemTheme(),
+    };
+}
+
+/** Build the EmbedRenderOptions used by `render` and the auto-scan path. */
+function renderOptionsFromConfig(): EmbedRenderOptions {
+    return {
+        theme: effectiveTheme(config.theme, config.systemTheme),
+        locale: config.locale,
+        width: config.width,
+        today: config.today,
+    };
+}
+
+/**
+ * Render a single Nowline source string to an SVG. Useful for
+ * applications that want to control exactly when and where the SVG
+ * lands (custom `<div>` containers, dynamically loaded blocks, etc.).
+ */
+export async function render(source: string, options: EmbedRenderOptions = {}): Promise<string> {
+    const merged: EmbedRenderOptions = {
+        ...renderOptionsFromConfig(),
+        ...options,
+    };
+    return renderSource(source, merged);
+}
+
+/**
+ * Parse a Nowline source string. Returns the AST and any lexer /
+ * parser / validator errors. Does not run layout or render — useful for
+ * editor experiences that want diagnostics without paying the render
+ * cost.
+ */
+export async function parse(source: string): Promise<EmbedParseResult> {
+    return parseSource(source);
+}
+
+/**
+ * Scan the DOM for Nowline blocks and replace each with its rendered
+ * SVG. Aliased as `run` for parity with Mermaid's recent API.
+ */
+export async function init(overrides?: Partial<AutoScanInputs>): Promise<AutoScanResult> {
+    const inputs: AutoScanInputs = {
+        selector: overrides?.selector ?? config.selector,
+        theme: overrides?.theme ?? renderOptionsFromConfig().theme,
+        locale: overrides?.locale ?? config.locale,
+        width: overrides?.width ?? config.width,
+        today: overrides?.today ?? config.today,
+        document: overrides?.document,
+    };
+    return runAutoScan(inputs);
+}
+
+/** Alias for `init`, matching Mermaid's `mermaid.run()`. */
+export const run = init;
+
+// IIFE-bundle bootstrap. When the bundled script tag loads on a page,
+// the bundler invokes the module body; we schedule auto-scan to fire on
+// DOMContentLoaded unless the page disables it with
+// `nowline.initialize({ startOnLoad: false })` synchronously after the
+// script tag.
+//
+// Guarded by `typeof document !== 'undefined'` so ESM consumers
+// (Node tests, build pipelines, server-side rendering) don't trigger
+// the auto-scan branch.
+if (typeof document !== 'undefined' && !autoStartScheduled) {
+    autoStartScheduled = true;
+    const start = (): void => {
+        if (!config.startOnLoad) return;
+        // Fire-and-forget; render errors are surfaced via `console.error`
+        // inside `runAutoScan`.
+        void init();
+    };
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', start, { once: true });
+    } else {
+        // Document is already parsed; defer to next microtask so any
+        // synchronous `initialize({ startOnLoad: false })` after the
+        // script tag still wins the race.
+        queueMicrotask(start);
+    }
+}
+
+// Test-only escape hatch. Exposed as a named export so tests can reset
+// the module's hidden state (config, system-theme cache, the once-only
+// console.warn latch) between cases.
+export function __resetForTests(): void {
+    config = { ...initialConfig, systemTheme: resolveSystemTheme() };
+    autoStartScheduled = false;
+    __resetEmbedPipelineForTests();
+    __resetAutoScanForTests();
+}

package/src/no-op-include-resolver.ts

@@ -0,0 +1,22 @@
+// Browser-side `readFile` that always rejects with a stable, sniff-able
+// error. The render pipeline catches matching diagnostics and converts
+// them into a single `console.warn` (deduped), so authors notice when
+// they ship a file with `include` directives that the embed cannot
+// satisfy without a network fetch.
+//
+// A real HTTP-fetch resolver is intentionally out of scope for m4 (see
+// `specs/handoffs/handoff-m4-embed.md`): CORS, relative-URL semantics,
+// and waterfall performance each warrant their own decision and are
+// best handled behind an opt-in flag in a follow-up.
+
+export const NOWLINE_EMBED_NOOP_INCLUDE_TAG = '__nowline_embed_noop_include__';
+
+export async function noOpIncludeReadFile(absPath: string): Promise<string> {
+    throw new Error(
+        `${NOWLINE_EMBED_NOOP_INCLUDE_TAG}: include "${absPath}" was skipped — the embed runs in single-file mode.`,
+    );
+}
+
+export function isNoOpIncludeDiagnosticMessage(message: string): boolean {
+    return message.includes(NOWLINE_EMBED_NOOP_INCLUDE_TAG);
+}