@markii/host 0.0.0-stage → 0.17.0-next.2

package/dist/export/image-embed.js

@@ -0,0 +1,274 @@
+/**
+ * Embedding a note's local images into its exported HTML (GitHub issue #28
+ * slice 3, part 1), so an exported file is genuinely self-contained: one
+ * document a user can mail, archive, or open on a machine that has never
+ * seen the vault, with its pictures still in it.
+ *
+ * WHERE THIS SITS. `./note-export.ts` composes an already-rendered body
+ * string into the export page. This module rewrites that body BEFORE the
+ * composition, turning every embeddable `<img src>` into a `data:` URI. It
+ * works on the rendered string rather than on the note's AST on purpose:
+ * the body is whatever engine rendered it, React or `@markii/html`, and a
+ * pack component's own images have to be embedded too. A string rewrite is
+ * the one place both engines and every component meet.
+ *
+ * WHAT STAYS A URL. Anything with a scheme, so `http:` and `https:` sources
+ * stay live URLs exactly as authored, and a `data:` URI is already
+ * embedded. A protocol-relative `//host/x.png` is a remote source too. Only
+ * a genuinely local, relative path is a candidate.
+ *
+ * THE HOST SEAM. This package knows nothing about vaults, workspace
+ * folders, or filesystems, so reading the bytes is injected: a host hands
+ * in an `ExportImageReader` that resolves a source the way its own preview
+ * resolves one and reads it, or reports that it could not. That keeps
+ * `@markii/host` free of host APIs while the size cap, the MIME rules, the
+ * base64 encoding, and the reporting stay in ONE place, shared by every
+ * host.
+ *
+ * NOTHING HERE EVER FAILS AN EXPORT. An image that is too large, of an
+ * unknown type, missing, or unreadable keeps the source the author wrote
+ * and is recorded in the returned report. The host turns that report into
+ * diagnostics lines: per AGENTS.md, a skipped image is a quiet fact on the
+ * diagnostics surface, never a notice and never a failed export.
+ */
+/**
+ * The per-image ceiling for embedding, 2 MiB. An image above it keeps its
+ * original path rather than inflating the exported file by a third of its
+ * own size in base64. Exported so a host with a cheap size check can skip
+ * reading such a file at all and report `oversize` straight away.
+ */
+export const MAX_EMBEDDED_IMAGE_BYTES = 2 * 1024 * 1024;
+/**
+ * The extensions this embeds, and the MIME type each becomes. Hand-rolled
+ * and deliberately small, in the same spirit as this repo's other
+ * hand-rolled validation: an extension that is not on this list is not
+ * embedded at all, rather than guessed at with a generic type that a
+ * browser would then have to sniff.
+ */
+const IMAGE_MIME_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    bmp: 'image/bmp',
+    ico: 'image/x-icon',
+    svg: 'image/svg+xml',
+};
+/** Every extension `mimeTypeForImageSrc` recognizes, lowercase and without the dot. Exported for a host that wants to name them in its own documentation or tests. */
+export const EMBEDDABLE_IMAGE_EXTENSIONS = Object.keys(IMAGE_MIME_TYPES);
+/**
+ * The MIME type for one image source, read from its extension, or
+ * `undefined` when the extension is missing or unrecognized. Any `?query`
+ * or `#fragment` is ignored first, so `logo.png?v=2` still reads as a PNG.
+ */
+export function mimeTypeForImageSrc(src) {
+    const withoutQuery = src.split(/[?#]/, 1)[0] ?? '';
+    const lastDot = withoutQuery.lastIndexOf('.');
+    if (lastDot === -1)
+        return undefined;
+    const extension = withoutQuery.slice(lastDot + 1).toLowerCase();
+    if (extension.length === 0)
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(IMAGE_MIME_TYPES, extension)
+        ? IMAGE_MIME_TYPES[extension]
+        : undefined;
+}
+/**
+ * True when `value` begins with a URL scheme, using the same rule as
+ * `@markii/core`'s `isSafeUrl` and `apps/vscode/src/webview/
+ * document-images.ts`: text before the first `:`, but only when that `:`
+ * comes before any `/`, `?` or `#`. So `notes/a:b.png` is correctly a
+ * relative path, while `https://x/y.png` and `data:image/png;base64,...`
+ * are not.
+ */
+function hasScheme(value) {
+    const colon = value.indexOf(':');
+    if (colon === -1)
+        return false;
+    const slash = value.indexOf('/');
+    const questionMark = value.indexOf('?');
+    const numberSign = value.indexOf('#');
+    return ((slash === -1 || colon < slash) &&
+        (questionMark === -1 || colon < questionMark) &&
+        (numberSign === -1 || colon < numberSign));
+}
+/**
+ * True for a source this will try to embed: a non-empty, local, relative
+ * path. A scheme of any kind, a protocol-relative `//host/...`, and an
+ * empty or fragment-only value are all left exactly as authored.
+ */
+export function isEmbeddableImageSrc(src) {
+    if (src.length === 0)
+        return false;
+    if (src.startsWith('#'))
+        return false;
+    if (src.startsWith('//'))
+        return false;
+    return !hasScheme(src);
+}
+/** An empty report, for an export that embedded nothing because no host reader was offered. */
+export const EMPTY_IMAGE_REPORT = {
+    embedded: [],
+    embeddedBytes: 0,
+    skipped: [],
+    remote: 0,
+};
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * Base64 for a byte array, hand-rolled so this module needs neither
+ * `Buffer` (Node only) nor `btoa` (which cannot take bytes without a
+ * lossy string round trip) and stays environment-free, matching how this
+ * repo hand-rolls its manifest validation and `uses:` reader rather than
+ * taking a dependency for something this small.
+ */
+export function encodeBase64(bytes) {
+    let result = '';
+    const full = bytes.length - (bytes.length % 3);
+    for (let index = 0; index < full; index += 3) {
+        const chunk = ((bytes[index] ?? 0) << 16) |
+            ((bytes[index + 1] ?? 0) << 8) |
+            (bytes[index + 2] ?? 0);
+        result +=
+            BASE64_ALPHABET[(chunk >> 18) & 63] +
+                BASE64_ALPHABET[(chunk >> 12) & 63] +
+                BASE64_ALPHABET[(chunk >> 6) & 63] +
+                BASE64_ALPHABET[chunk & 63];
+    }
+    const remaining = bytes.length - full;
+    if (remaining === 1) {
+        const chunk = (bytes[full] ?? 0) << 16;
+        result +=
+            BASE64_ALPHABET[(chunk >> 18) & 63] +
+                BASE64_ALPHABET[(chunk >> 12) & 63] +
+                '==';
+    }
+    else if (remaining === 2) {
+        const chunk = ((bytes[full] ?? 0) << 16) | ((bytes[full + 1] ?? 0) << 8);
+        result +=
+            BASE64_ALPHABET[(chunk >> 18) & 63] +
+                BASE64_ALPHABET[(chunk >> 12) & 63] +
+                BASE64_ALPHABET[(chunk >> 6) & 63] +
+                '=';
+    }
+    return result;
+}
+/** One image's bytes as a `data:` URI. Base64 output is alphanumeric plus `+/=`, so it is always safe inside a double-quoted HTML attribute with no further escaping. */
+export function toImageDataUri(bytes, mimeType) {
+    return `data:${mimeType};base64,${encodeBase64(bytes)}`;
+}
+/** The five entities a renderer escapes in an attribute value, decoded back to the path the author actually wrote. `&amp;` is decoded last so `&amp;lt;` does not become `<`. */
+function decodeAttributeValue(value) {
+    return value
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#(?:39|x27);/g, "'")
+        .replace(/&amp;/g, '&');
+}
+/**
+ * Matches one `<img ...>` start tag. Both renderers emit attribute values
+ * in double quotes, and every `<` inside rendered text or code is escaped
+ * to `&lt;` before it reaches here, so a `>`-terminated scan cannot run
+ * past a tag or match a literal `<img` a note merely talks about.
+ */
+const IMG_TAG_PATTERN = /<img\b[^>]*>/gi;
+/** Matches the `src="..."` attribute inside one already-matched `<img>` tag. */
+const SRC_ATTRIBUTE_PATTERN = /(\ssrc=")([^"]*)(")/i;
+/**
+ * Rewrites every embeddable local `<img src>` in `html` into a `data:` URI,
+ * using `readImage` to fetch each source's bytes, and reports what happened
+ * to every image it saw.
+ *
+ * Each distinct source is read at most once, so a note that shows the same
+ * picture five times reads and encodes it once and embeds the same URI five
+ * times. Never throws: a reader that throws is recorded as `unreadable` and
+ * that one image keeps its original source.
+ */
+export async function embedImagesInHtml(html, readImage) {
+    const embedded = [];
+    const skipped = [];
+    let embeddedBytes = 0;
+    let remote = 0;
+    // Resolved once per distinct source: `undefined` means "keep the original".
+    const dataUris = new Map();
+    const tags = html.match(IMG_TAG_PATTERN) ?? [];
+    for (const tag of tags) {
+        const attribute = SRC_ATTRIBUTE_PATTERN.exec(tag);
+        if (!attribute)
+            continue;
+        const rawSrc = attribute[2] ?? '';
+        const src = decodeAttributeValue(rawSrc);
+        if (!isEmbeddableImageSrc(src)) {
+            if (src.length > 0 && !src.startsWith('#'))
+                remote += 1;
+            continue;
+        }
+        if (dataUris.has(src))
+            continue;
+        const mimeType = mimeTypeForImageSrc(src);
+        if (mimeType === undefined) {
+            dataUris.set(src, undefined);
+            skipped.push({ src, reason: 'unsupported-type' });
+            continue;
+        }
+        let result;
+        try {
+            result = await readImage(src);
+        }
+        catch (error) {
+            result = {
+                kind: 'unreadable',
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (result.kind === 'oversize') {
+            dataUris.set(src, undefined);
+            skipped.push({
+                src,
+                reason: 'too-large',
+                byteLength: result.byteLength,
+            });
+            continue;
+        }
+        if (result.kind === 'unreadable') {
+            dataUris.set(src, undefined);
+            skipped.push({
+                src,
+                reason: 'unreadable',
+                ...(result.detail !== undefined ? { detail: result.detail } : {}),
+            });
+            continue;
+        }
+        // Re-checked here even though a host may have checked already: the cap
+        // is this module's rule, and a host that cannot cheaply stat a file
+        // legitimately reads first and lets this decide.
+        if (result.bytes.byteLength > MAX_EMBEDDED_IMAGE_BYTES) {
+            dataUris.set(src, undefined);
+            skipped.push({
+                src,
+                reason: 'too-large',
+                byteLength: result.bytes.byteLength,
+            });
+            continue;
+        }
+        dataUris.set(src, toImageDataUri(result.bytes, mimeType));
+        embedded.push(src);
+        embeddedBytes += result.bytes.byteLength;
+    }
+    const rewritten = html.replace(IMG_TAG_PATTERN, (tag) => {
+        const attribute = SRC_ATTRIBUTE_PATTERN.exec(tag);
+        if (!attribute)
+            return tag;
+        const src = decodeAttributeValue(attribute[2] ?? '');
+        const dataUri = dataUris.get(src);
+        if (dataUri === undefined)
+            return tag;
+        return tag.replace(SRC_ATTRIBUTE_PATTERN, (_match, before, _value, after) => `${before}${dataUri}${after}`);
+    });
+    return {
+        html: rewritten,
+        report: { embedded, embeddedBytes, skipped, remote },
+    };
+}

package/dist/export/note-export.d.ts

@@ -0,0 +1,332 @@
+import type { ValueStore } from '@markii/runtime';
+import type { EmbeddedImageReport, ExportImageReader } from './image-embed.js';
+import type { StoredValue } from '@markii/runtime';
+import type { OnDiagnostic, UnavailableComponent } from '@markii/stdlib';
+/** The canonical Markii file extension, matching `apps/vscode/src/mark-document.ts`'s `MARK_EXTENSION`. */
+export declare const MARK_EXTENSION = ".mk.md";
+/** The extensions an export can be written as. */
+export type ExportExtension = '.html' | '.pdf' | '.txt' | '.md';
+/**
+ * The name used when a note has no usable base name at all — a file called
+ * exactly `.mk.md`, or an empty path segment. Rare enough that neither host
+ * offers it as a normal path, but a file name is not optional here, so
+ * there has to be one rather than an empty string.
+ */
+export declare const FALLBACK_EXPORT_BASE_NAME = "markii-note";
+/**
+ * The base name an export is built from: the file name with a recognized
+ * Markii/markdown extension removed, case-insensitively. `notes.mk.md` and
+ * `notes.md` both give `notes`; a name with any other extension keeps it
+ * (`notes.txt` gives `notes.txt`), because guessing at an unknown extension
+ * would be more surprising than leaving it alone. A `/`-separated path is
+ * accepted too: only its last segment is read.
+ */
+export declare function exportBaseName(pathOrName: string): string;
+/** The exported file's name for `fileName`: `notes.mk.md` + `.html` gives `notes.html`. */
+export declare function exportedFileName(fileName: string, extension: ExportExtension): string;
+/**
+ * The path an export is written to when it lands beside its source note:
+ * the same folder, the same base name, the new extension. `notePath` is a
+ * `/`-separated path — a `vscode.Uri.path` or an Obsidian vault-relative
+ * path, never a platform `fsPath` — so no `node:path` import and no
+ * platform branching is needed, and this module stays environment-free.
+ */
+export declare function exportedSiblingPath(notePath: string, extension: ExportExtension): string;
+/** The exported document's `<title>`: the note's own base name, so a browser tab and a PDF's metadata name the note rather than the format. */
+export declare function exportDocumentTitle(fileName: string): string;
+/**
+ * The page-level CSS an exported file carries in addition to `doc.css`.
+ *
+ * `doc.css` is deliberately a LIBRARY stylesheet: it styles `.doc` and
+ * never claims `:root` or `body`, because hosts embed it into pages they
+ * do not own. A standalone exported file has no host to supply the page
+ * around it, so this is that page: a ground color, a readable measure, and
+ * print rules, all of them host-authored and trusted (they are passed to
+ * the engine's `composeDocument` as `extraCss`, which is inserted verbatim).
+ *
+ * The print block matters more than it looks: the Obsidian PDF command
+ * prints exactly this document, so the paper layout is decided here rather
+ * than in a host-specific branch. `@page` sets the sheet's own margins
+ * (the PDF command has no separate page-setup step of its own), the
+ * `break-inside: avoid` list keeps a card/callout/table from splitting
+ * across two pages wherever it fits on one, and the collapsed script
+ * marker and the VS Code webview's run marker are hidden on paper: both
+ * are live-preview affordances (a disclosure toggle, a status line about
+ * the last run) that mean nothing on a printed or archived page.
+ */
+/**
+ * The class `composeNoteHtmlExport`/`buildNoteHtmlExport` put on the `.doc`
+ * wrapper when `hideScriptBlocks` is on, and the class `EXPORT_PAGE_CSS`'s
+ * rule below is scoped to.
+ *
+ * Both hosts already have this preference (VS Code's
+ * `markii.hideScriptBlocks`, Obsidian's "Hide script blocks" setting) for
+ * their live preview, hiding only the collapsed `⚙ name` marker and
+ * nothing else — a failure a reader needs to see is never hidden along
+ * with it. An export carries whichever value the exporting host's own
+ * preview was showing, so a note exported with scripts hidden in the
+ * editor stays that way in the file.
+ */
+export declare const EXPORT_HIDE_SCRIPT_BLOCKS_CLASS = "mk-export--hide-scripts";
+export declare const EXPORT_PAGE_CSS = "\nbody {\n  margin: 0;\n  background: #fff;\n}\n.doc {\n  box-sizing: border-box;\n  max-width: 46rem;\n  margin: 0 auto;\n  padding: 2.5rem 1.5rem 4rem;\n}\n.doc.mk-export--hide-scripts .mk-script {\n  display: none;\n}\n@page {\n  margin: 2cm;\n}\n@media print {\n  .doc {\n    max-width: none;\n    margin: 0;\n    padding: 0;\n  }\n  .doc .mk-card,\n  .doc .mk-callout,\n  .doc .mk-stat,\n  .doc .mk-figure,\n  .doc .mk-unknown,\n  .doc table {\n    break-inside: avoid;\n  }\n  /* A collapsed `details` prints as its summary alone, which loses the\n     content the author wrote. On paper there is nothing to expand, so\n     every disclosure prints open. */\n  .doc details > *:not(summary) {\n    display: block;\n  }\n  .doc .mk-script,\n  .doc .mk-preview__run-marker {\n    display: none;\n  }\n}\n";
+/**
+ * The static HTML engine, injected so this module imports no renderer.
+ * A host passes `createHtmlExportEngine()` from `@markii/host/node`, which
+ * wraps `@markii/html`; a test may pass a stub.
+ */
+export interface HtmlExportEngine {
+    /** Renders one note's source to a body string with the standard component set, last-run values bound through `store`. Never throws. */
+    renderBody(text: string, store: ValueStore | undefined, diagnostics: {
+        readonly unavailableComponents?: readonly UnavailableComponent[];
+        readonly onDiagnostic?: OnDiagnostic;
+    }): string;
+    /** Wraps a body in the full-page shell (`doc.css` embedded). */
+    composeDocument(bodyHtml: string, options: {
+        readonly title: string;
+        readonly extraCss: string;
+        readonly docClassName?: string;
+    }): string;
+    /** The one HTML-escaping primitive. */
+    escapeHtml(value: string): string;
+}
+/** What `buildNoteHtmlExport` needs to turn one note into a standalone file. */
+export interface NoteHtmlExportOptions {
+    /** The static HTML engine. */
+    readonly engine: HtmlExportEngine;
+    /** The note's full source text. */
+    readonly text: string;
+    /** The note's file name, used for the document title. A path is accepted; only the last segment is read. */
+    readonly fileName: string;
+    /**
+     * The note's last-run values, exactly as the host persisted them
+     * (`readPersistedValues`). Bound components and `:value[...]` markers
+     * bake these in. Omitted or empty means the note exports with its
+     * standard empty states, which is what a note that has never been run
+     * should show.
+     */
+    readonly values?: Record<string, StoredValue>;
+    /** Extra host CSS appended after `doc.css` and `EXPORT_PAGE_CSS`. Trusted, inserted verbatim. */
+    readonly extraCss?: string;
+    /**
+     * Hides the collapsed script marker in the exported file, mirroring the
+     * exporting host's own `hideScriptBlocks` preview preference. Defaults to
+     * `false`, which exports every script marker exactly as the preview
+     * would show it with the preference off.
+     */
+    readonly hideScriptBlocks?: boolean;
+    /** Installed pack components the static engine cannot draw; see `NoteExportBuildRequest`. */
+    readonly unavailableComponents?: readonly UnavailableComponent[];
+    /** Receives the static engine's render diagnostics. */
+    readonly onDiagnostic?: OnDiagnostic;
+}
+/**
+ * Renders one note to a complete, self-contained HTML document string.
+ *
+ * Never throws: `renderMarkToHtml` already returns its own failure fallback
+ * rather than propagating, so a caller always gets a document it can write.
+ */
+export declare function buildNoteHtmlExport(options: NoteHtmlExportOptions): string;
+/**
+ * ISSUE #28 SLICE 2: rendering an export through a host's REACT engine.
+ *
+ * Slice 1 rendered every export with `@markii/html`, so a pack directive
+ * came out as that engine's unknown-component box. The static engine cannot
+ * load a pack, because a pack component is a React module. The fix is not a
+ * second component system: it is to let a host that ALREADY has React and a
+ * merged registry in front of it (both do, for the preview) render the
+ * export body with exactly what the preview renders, and hand the resulting
+ * STRING back here.
+ *
+ * That keeps this package React-free. Composition is the host-neutral part
+ * (the page shell, `doc.css`, the print rules, the pack stylesheets, the
+ * file name), and it needs no renderer at all once it has a body string.
+ * The React render itself happens where React already lives: the VS Code
+ * webview, and the Obsidian plugin's own renderer process.
+ */
+/** One loaded pack's emitted stylesheet, as a host already holds it for its preview. */
+export interface ExportPackStylesheet {
+    /** The pack's namespace, used only to label the block in the exported file. */
+    readonly namespace: string;
+    /** The stylesheet's text, exactly as the host injects it into its preview. */
+    readonly cssText: string;
+}
+/**
+ * Why an export fell back to the static engine. Diagnostics-facing: each
+ * host words these itself, since the thing a user would do about it differs
+ * per host.
+ *
+ * - `no-packs`: no pack components were loaded, so the static engine
+ *   renders precisely what the React engine would have. Not a degradation.
+ * - `no-renderer`: the host had no React surface to render through at all
+ *   (VS Code with no preview panel open).
+ * - `timeout`: the host's renderer was asked and did not answer in time.
+ * - `render-failed`: the renderer answered with a failure, or threw.
+ */
+export type StaticExportReason = 'no-packs' | 'no-renderer' | 'timeout' | 'render-failed';
+/** Which engine actually rendered an export's body, and what that means. */
+export type ExportRenderInfo = {
+    readonly engine: 'react';
+    /** How many loaded packs contributed components to the registry that rendered this file. */
+    readonly packCount: number;
+    /** How many of those packs contributed a stylesheet embedded in the file. */
+    readonly stylesheetCount: number;
+} | {
+    readonly engine: 'static';
+    readonly reason: StaticExportReason;
+    /** The verbatim detail behind a `timeout`/`render-failed`, for the diagnostics surface only. */
+    readonly detail?: string;
+};
+/** What a host's React renderer returns: the body markup, or why it could not produce one. */
+export type ExportBodyResult = {
+    readonly ok: true;
+    readonly html: string;
+} | {
+    readonly ok: false;
+    readonly reason: Extract<StaticExportReason, 'timeout' | 'render-failed'>;
+    readonly detail?: string;
+};
+/**
+ * A host's React render of one note's body, as a string. Given the note's
+ * text and the values to bake in, it returns the markup that goes INSIDE
+ * the exported document's `.doc` wrapper. It is expected not to throw; one
+ * that does is caught here and treated as `render-failed`, so a caller
+ * always gets a document it can write.
+ */
+export type ExportBodyRenderer = (text: string, values: Record<string, StoredValue>) => ExportBodyResult | Promise<ExportBodyResult>;
+/**
+ * The pack stylesheets as one CSS block, in the order the host loaded them
+ * — the same order its preview injects them, which is what decides the
+ * cascade between two packs that style the same thing. Each block is
+ * labeled with its pack's namespace so a reader of the exported file can
+ * tell whose rules these are.
+ *
+ * Placed AFTER `doc.css` and `EXPORT_PAGE_CSS` by `composeNoteHtmlExport`,
+ * matching docs/packs.md's load order: a pack sees resolved `--mk-*` token
+ * values and is not overridden by the document stylesheet's broader rules.
+ */
+export declare function packStylesheetsCss(sheets: readonly ExportPackStylesheet[]): string;
+/** What `composeNoteHtmlExport` needs to wrap an already-rendered body in the export shell. */
+export interface ComposeNoteHtmlExportOptions {
+    /** The static HTML engine. */
+    readonly engine: HtmlExportEngine;
+    /** The rendered body markup that goes inside the `.doc` wrapper. Inserted verbatim; it is expected to be renderer output, already escaped. */
+    readonly bodyHtml: string;
+    /** The note's file name, used for the document title. A path is accepted; only the last segment is read. */
+    readonly fileName: string;
+    /** The loaded packs' stylesheets, appended after `doc.css` and `EXPORT_PAGE_CSS`. */
+    readonly packStylesheets?: readonly ExportPackStylesheet[];
+    /** Extra host CSS, appended after `EXPORT_PAGE_CSS` and before the pack stylesheets. Trusted, inserted verbatim. */
+    readonly extraCss?: string;
+    /** Hides the collapsed script marker in the exported file. See `NoteHtmlExportOptions.hideScriptBlocks`. Defaults to `false`. */
+    readonly hideScriptBlocks?: boolean;
+}
+/**
+ * Wraps an already-rendered body in the standalone export page: the same
+ * shell, `doc.css`, and print rules `buildNoteHtmlExport` produces, plus
+ * every loaded pack's stylesheet so pack components in the body are styled.
+ *
+ * Host-neutral and renderer-neutral on purpose: it takes a STRING, so the
+ * React path and the static path compose the identical page and can never
+ * drift on what an exported file carries.
+ */
+export declare function composeNoteHtmlExport(options: ComposeNoteHtmlExportOptions): string;
+/** What `buildNoteExport` needs. Everything except `text`/`fileName` is optional; omitting `renderBody` is the plain static export. */
+export interface NoteExportBuildRequest {
+    /** The static HTML engine. */
+    readonly engine: HtmlExportEngine;
+    /** The note's full source text. */
+    readonly text: string;
+    /** The note's file name, used for the document title. A path is accepted; only the last segment is read. */
+    readonly fileName: string;
+    /** The note's last-run values, baked in wherever the note binds one. Omitted or empty exports the note's standard empty states. */
+    readonly values?: Record<string, StoredValue>;
+    /**
+     * The host's React render of the body. Omitted when the host has nothing
+     * to render through, in which case `staticReason` says which case that
+     * is and the static engine renders instead.
+     */
+    readonly renderBody?: ExportBodyRenderer;
+    /** Why the static engine is being used, when `renderBody` is omitted. Defaults to `no-packs`. */
+    readonly staticReason?: StaticExportReason;
+    /** The loaded packs' stylesheets. Embedded only when the React path actually rendered the body; the static engine's output never references them. */
+    readonly packStylesheets?: readonly ExportPackStylesheet[];
+    /** How many loaded packs contributed components to the registry that rendered this file. Diagnostics only. */
+    readonly packCount?: number;
+    /** Extra host CSS appended after `EXPORT_PAGE_CSS`. Trusted, inserted verbatim. */
+    readonly extraCss?: string;
+    /**
+     * Reads one of the note's local images, so the export can embed it as a
+     * `data:` URI and stand on its own (`./image-embed.ts`, issue #28 slice
+     * 3). Omitted leaves every image source exactly as the author wrote it,
+     * which is slice 2's behavior.
+     */
+    readonly embedImages?: ExportImageReader;
+    /** Hides the collapsed script marker in the exported file. See `NoteHtmlExportOptions.hideScriptBlocks`. Defaults to `false`. */
+    readonly hideScriptBlocks?: boolean;
+    /**
+     * Installed pack components the static engine cannot draw. A directive
+     * naming one reads "no HTML view for" instead of "unknown component" in
+     * the exported body. Ignored on the React path, whose host passes the
+     * same list to its own renderer inside `renderBody`.
+     */
+    readonly unavailableComponents?: readonly UnavailableComponent[];
+    /** Receives the static engine's render diagnostics (the `no-engine-view` event). Same scope as `unavailableComponents`. */
+    readonly onDiagnostic?: OnDiagnostic;
+}
+/** One built export: the complete document, how it was rendered, and how many values it baked in. */
+export interface NoteExportDocument {
+    /** The complete, self-contained HTML document. */
+    readonly html: string;
+    /** Which engine rendered the body, and why when it was the static one. */
+    readonly render: ExportRenderInfo;
+    /** How many last-run values were baked in. */
+    readonly valueCount: number;
+    /** What image embedding did, for the host's diagnostics surface. Empty when no `embedImages` reader was offered. */
+    readonly images: EmbeddedImageReport;
+}
+/**
+ * Builds one note's standalone export document, through the host's React
+ * engine when it offered one and through `@markii/html` otherwise.
+ *
+ * Never throws and never leaves a caller without a file: a renderer that
+ * fails, times out, or throws is classified, recorded in `render`, and
+ * replaced by the static engine's output, which is the same document slice
+ * 1 produced.
+ */
+export declare function buildNoteExport(request: NoteExportBuildRequest): Promise<NoteExportDocument>;
+/**
+ * Whether `text` contains at least one Markii script fence, i.e. a code
+ * fence whose info string names `lua`. Both hosts' export notices use this
+ * so a note with no scripts is never told to run itself first.
+ */
+export declare function noteHasScripts(text: string): boolean;
+/**
+ * One note a cascade index page links to (GitHub issue #28 slice 3, part
+ * 2's `index.html`).
+ */
+export interface CascadeIndexEntry {
+    /**
+     * The note's title as shown on the index page — the same base name
+     * `exportDocumentTitle` gives that note's own `<title>` tag, so the two
+     * pages never name a note two different ways.
+     */
+    readonly title: string;
+    /** The note's exported file name inside the archive, e.g. `week-2.html`. Used as the link's `href`, relative to `index.html`. */
+    readonly fileName: string;
+}
+/**
+ * Builds a cascade archive's `index.html`: a self-contained document
+ * listing every exported note by title, each linking to its own file.
+ *
+ * A cascade archive has no single note to open first once it is
+ * unzipped, and without this a reader has to guess a file name or open the
+ * archive's contents blind. `entries` is expected in the same order the
+ * cascade walked (root note first, breadth first), which is what makes the
+ * list read as a sensible table of contents rather than an alphabetized
+ * jumble.
+ *
+ * Uses the same page shell every exported note gets (`doc.css`,
+ * `EXPORT_PAGE_CSS`), so the index reads as part of the same export rather
+ * than a bare, unstyled file dropped in beside it.
+ */
+export declare function buildCascadeIndexHtml(entries: readonly CascadeIndexEntry[], engine: HtmlExportEngine): string;