@nowline/embed 0.0.0-dev.20260601071750.g04bdff9

package/src/index.ts

@@ -0,0 +1,230 @@
+// 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.
+
+// Build-time constants substituted by esbuild's `define` (see
+// `scripts/bundle.mjs`). The `typeof` guards keep this file safe to
+// import under vitest, where esbuild's define never runs and the
+// identifiers are undeclared.
+declare const __NOWLINE_EMBED_VERSION__: string;
+declare const __NOWLINE_EMBED_SHA__: string;
+
+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 { ShareOption } from './share.js';
+import { type EmbedTheme, effectiveTheme, resolveSystemTheme } from './theme.js';
+
+export {
+    type AutoScanResult,
+    type EmbedParseResult,
+    EmbedRenderError,
+    type EmbedTheme,
+    type ShareOption,
+};
+
+/**
+ * Bundle provenance, mirroring the legal-comment banner that
+ * `scripts/bundle.mjs` injects at the top of every artifact:
+ * `@nowline/embed <version> sha=<short-sha> built=<iso-utc>`.
+ *
+ * Exposed on the IIFE global as `nowline.version` / `nowline.sha` so
+ * pages and bug reports can identify the exact build without scraping
+ * the comment banner.
+ */
+export const version: string =
+    typeof __NOWLINE_EMBED_VERSION__ !== 'undefined' ? __NOWLINE_EMBED_VERSION__ : '0.0.0';
+export const sha: string =
+    typeof __NOWLINE_EMBED_SHA__ !== 'undefined' ? __NOWLINE_EMBED_SHA__ : 'unknown';
+
+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;
+    /**
+     * Controls the "Share on Nowline" anchor appended after each rendered SVG.
+     * - `true` (default) — link to the Free app open route
+     *   (`https://free.nowline.io/open`).
+     * - string — a custom base URL (may include a path); the fragment is appended.
+     * - `false` / `'none'` — no anchor rendered.
+     * - `{ textUrl, remoteUrl }` — template with `{text}` / `{url}` substitution.
+     */
+    share?: ShareOption;
+    /**
+     * Global source URL for all blocks on the page. When set, share links
+     * use `#url=<sourceUrl>` instead of `#text=` (inline encoding).
+     * Per-block `data-nowline-source-url` overrides this for individual blocks.
+     * Only `https:` URLs are emitted as `#url=`.
+     */
+    sourceUrl?: string;
+}
+
+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';
+    /** Controls the "Share on Nowline" anchor. Defaults to `true`. */
+    share: ShareOption;
+    /** Global canonical source URL; per-block `data-nowline-source-url` takes priority. */
+    sourceUrl?: string;
+}
+
+const initialConfig: ResolvedConfig = {
+    theme: 'auto',
+    startOnLoad: true,
+    selector: DEFAULT_SELECTOR,
+    systemTheme: resolveSystemTheme(),
+    share: true,
+};
+
+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,
+        share: options.share ?? config.share,
+        sourceUrl: options.sourceUrl ?? config.sourceUrl,
+        // 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,
+        share: overrides?.share ?? config.share,
+        sourceUrl: overrides?.sourceUrl ?? config.sourceUrl,
+        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/pipeline.ts

@@ -0,0 +1,106 @@
+// Thin shim around `@nowline/browser`'s pipeline. The browser package
+// owns parse / resolveIncludes / layout / render; the embed layers two
+// embed-specific behaviours on top:
+//
+//  - Throws `EmbedRenderError` on failure instead of returning a
+//    discriminated union. The Mermaid-compatible `nowline.render(source)`
+//    surface promises a string; throwing matches the documented v1
+//    contract and keeps the auto-scan path's per-block error handling
+//    simple.
+//  - Latches a once-per-page-load `console.warn` the first time an
+//    `include` directive is encountered. The browser pipeline emits a
+//    structured callback for each skip; the embed converts that into a
+//    single, deduped user-visible message.
+
+import {
+    __resetBrowserPipelineForTests,
+    type RenderOptions as BrowserRenderOptions,
+    parseSource as browserParseSource,
+    renderSource as browserRenderSource,
+    type DiagnosticRow,
+    type ParseResult,
+} from '@nowline/browser';
+import type { ThemeName } from '@nowline/layout';
+
+const EMBED_SOURCE_PATH = '/embed.nowline';
+
+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: ParseResult['ast'];
+    /** Lexer + parser + Langium validation diagnostics, normalized to strings. */
+    errors: string[];
+}
+
+let includeWarningEmitted = false;
+
+export async function parseSource(source: string): Promise<EmbedParseResult> {
+    const { ast, diagnostics } = await browserParseSource(source, {
+        filePath: EMBED_SOURCE_PATH,
+    });
+    return {
+        ast,
+        errors: diagnostics
+            .filter((d: DiagnosticRow) => d.severity === 'error')
+            .map((d) => d.message),
+    };
+}
+
+export async function renderSource(
+    source: string,
+    options: EmbedRenderOptions = {},
+): Promise<string> {
+    const browserOptions: BrowserRenderOptions = {
+        filePath: EMBED_SOURCE_PATH,
+        theme: options.theme,
+        today: options.today,
+        locale: options.locale,
+        width: options.width,
+        idPrefix: options.idPrefix,
+        onSkippedInclude: () => {
+            if (!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 result = await browserRenderSource(source, browserOptions);
+    if (result.kind === 'svg') return result.svg;
+
+    const messages = result.diagnostics.filter((d) => d.severity === 'error').map((d) => d.message);
+    throw new EmbedRenderError(`Failed to render Nowline source: ${messages.join('; ')}`, messages);
+}
+
+export class EmbedRenderError extends Error {
+    constructor(
+        message: string,
+        public readonly details: string[],
+    ) {
+        super(message);
+        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(): void {
+    includeWarningEmitted = false;
+    __resetBrowserPipelineForTests();
+}

package/src/share.ts

@@ -0,0 +1,108 @@
+// Share-link generation for the "Share on Nowline" anchor that the
+// auto-scan loop appends after each rendered SVG.
+//
+// Encoding grammar (normative — defined in specs/embed.md):
+//   #text=base64url(zlib(utf8(source)))
+//   #url=<https-url>
+//
+// zlib = RFC 1950 via fflate zlibSync (byte-compatible with native
+// CompressionStream('deflate')); base64url strips padding and maps
+// +→- /→_.
+//
+// Sync, works on every browser, no feature-detect.
+
+import { zlibSync } from 'fflate';
+
+export const DEFAULT_SHARE_BASE = 'https://free.nowline.io/open';
+
+/**
+ * The `share` initialize option selects where share links point.
+ *
+ * - `true` — use DEFAULT_SHARE_BASE (the default).
+ * - `string` — a base URL with optional path; built via the URL API so
+ *   `https://foo.com/open` → `https://foo.com/open#text=…`.
+ * - `false` / `'none'` — disable the share anchor entirely.
+ * - `{ textUrl, remoteUrl }` — escape hatch for non-hash URL shapes;
+ *   `{text}` substituted with the base64url payload, `{url}` with the
+ *   percent-encoded source URL.
+ */
+export type ShareOption = boolean | 'none' | string | { textUrl: string; remoteUrl: string };
+
+/**
+ * Encode source text → `#text=<base64url(zlib(utf8(source)))>`.
+ *
+ * The return value includes the `#text=` key so callers can use it
+ * directly as a URL fragment.
+ *
+ * Sync, single code path, no feature-detect.
+ */
+export function encodeText(source: string): string {
+    return `#text=${_encodePayload(source)}`;
+}
+
+/** base64url(zlib(utf8(source))) without the `#text=` prefix. */
+function _encodePayload(source: string): string {
+    const bytes = new TextEncoder().encode(source);
+    const compressed = zlibSync(bytes);
+    // Convert Uint8Array to binary string for btoa. Chunked to avoid
+    // call-stack limits on large payloads.
+    const chunk = 0x8000; // 32 KB — safe below JS engine stack limits
+    let bin = '';
+    for (let i = 0; i < compressed.length; i += chunk) {
+        bin += String.fromCharCode(...compressed.subarray(i, i + chunk));
+    }
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export interface BuildShareLinkOptions {
+    /** The roadmap source text (used to build the #text= fragment). */
+    source: string;
+    /**
+     * Resolved source URL for the block (per-block → global → undefined).
+     * Only `https:` URLs are emitted as `#url=`; anything else falls
+     * back to the inline `#text=` encoding.
+     */
+    sourceUrl?: string | undefined;
+    /** The `share` option from InitializeOptions. */
+    share: ShareOption;
+}
+
+/**
+ * Build the full "Share on Nowline" URL for a rendered block.
+ *
+ * Returns `null` when `share` is `false` or `'none'`, signalling that
+ * no anchor should be rendered.
+ */
+export function buildShareLink({ source, sourceUrl, share }: BuildShareLinkOptions): string | null {
+    if (share === false || share === 'none') {
+        return null;
+    }
+
+    if (typeof share === 'object') {
+        // Template mode: { textUrl, remoteUrl }
+        if (sourceUrl !== undefined && _isHttps(sourceUrl)) {
+            return share.remoteUrl.replace('{url}', encodeURIComponent(sourceUrl));
+        }
+        return share.textUrl.replace('{text}', _encodePayload(source));
+    }
+
+    // share === true → DEFAULT_SHARE_BASE; share is a string → custom base URL
+    const base = share === true ? DEFAULT_SHARE_BASE : share;
+    const url = new URL(base);
+
+    if (sourceUrl !== undefined && _isHttps(sourceUrl)) {
+        url.hash = `url=${encodeURIComponent(sourceUrl)}`;
+    } else {
+        url.hash = `text=${_encodePayload(source)}`;
+    }
+
+    return url.toString();
+}
+
+function _isHttps(url: string): boolean {
+    try {
+        return new URL(url).protocol === 'https:';
+    } catch {
+        return false;
+    }
+}

package/src/theme.ts

@@ -0,0 +1,35 @@
+// Theme resolution for the embed.
+//
+// Precedence (highest to lowest):
+//   1. `initialize({ theme })` flag (light / dark / grayscale / auto;
+//      `greyscale` is accepted and canonicalized to `grayscale`).
+//   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.
+
+import { normalizeThemeName, type ThemeName } from '@nowline/layout';
+
+// `'greyscale'` (UK) is an accepted alias for the canonical `'grayscale'`.
+export type EmbedTheme = ThemeName | 'greyscale' | 'auto';
+
+export function resolveSystemTheme(): 'light' | 'dark' {
+    if (typeof globalThis === 'undefined') return 'light';
+    const win = (globalThis as { matchMedia?: (q: string) => { matches: boolean } }).matchMedia;
+    if (typeof win !== 'function') return 'light';
+    try {
+        return win('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    } catch {
+        return 'light';
+    }
+}
+
+export function effectiveTheme(theme: EmbedTheme | undefined, systemTheme: ThemeName): ThemeName {
+    if (theme && theme !== 'auto') return normalizeThemeName(theme) ?? systemTheme;
+    return systemTheme;
+}