@markii/host 0.0.1 → 0.17.0-next.3

package/dist/host/editor-behavior.d.ts

@@ -0,0 +1,153 @@
+import type { CompletionContext, CompletionItem, HoverInfo, InsertableComponent, LineColumn } from '@markii/stdlib/editor';
+import type { HostEditor, HostTextEdit } from './adapter.js';
+/** The origin tag every host's completion row shows for a component item: `'standard'`, `'layout'`, or the owning pack's own namespace. Empty string for an attribute or value item, which has no `group`. */
+export declare const STANDARD_ORIGIN_TAG = "standard";
+export declare const LAYOUT_ORIGIN_TAG = "layout";
+/**
+ * The origin tag a completion item carries: the lower-case
+ * `'standard'`/`'layout'` strings above, or the pack name.
+ */
+export declare function completionOriginTag(item: CompletionItem): string;
+/** A small cache in front of `buildComponentCatalog` (`../insert/component-catalog.js`), so a completion/hover provider does not re-discover packs from disk on every keystroke. */
+export interface CatalogCache {
+    /** The cached catalog, building it via `load` on first use and again after `invalidate()`. Never throws: a rejected `load` degrades to the standard-set-only catalog. */
+    get(): Promise<readonly InsertableComponent[]>;
+    /** The cached catalog if one is built, else `undefined`. Never starts a build. */
+    peek(): readonly InsertableComponent[] | undefined;
+    /** Drops the cached catalog (and any in-flight build), so the next `get()` rebuilds from `load`. */
+    invalidate(): void;
+}
+/**
+ * Builds a `CatalogCache` around `buildCatalog` (typically
+ * `../insert/component-catalog.js`'s `buildComponentCatalog` composed with
+ * a pack-discovery call). Concurrent `get()` calls made before a build
+ * finishes share one in-flight promise rather than each starting their own
+ * pack discovery.
+ */
+export declare function createCatalogCache(buildCatalog: () => Promise<readonly InsertableComponent[]>): CatalogCache;
+/**
+ * `completionAt` composed over a `HostEditor`'s document text, at the
+ * POSITION a completion request names — not `editor.cursor()`. A real
+ * editor's completion provider is invoked with an explicit position (the
+ * position the user is typing at when the provider fires), which is why a
+ * completion/hover request always carries its own `line`/`column` rather
+ * than reading the live caret a second time. `editor.cursor()` stays
+ * reserved for `insertComponentPlan`, which genuinely inserts at the
+ * caret.
+ */
+export declare function completeAtViaEditor(editor: Pick<HostEditor, 'documentText'>, position: LineColumn, catalog: readonly InsertableComponent[]): CompletionContext;
+/**
+ * Everything a completion UI needs for one request, decided once in the
+ * shared layer: the items, the replace span (`replaceStart`/`replaceEnd`),
+ * the token start a filtering popup should score against (`tokenStart`,
+ * which equals `replaceStart` unless a colon run precedes the name), and
+ * the fence lengthening edits an accepted CONTAINER item needs. Hosts only
+ * map this onto their own popup type.
+ */
+export interface CompletionPlan {
+    readonly kind: CompletionContext['kind'];
+    readonly items: readonly CompletionItem[];
+    readonly replaceStart: number;
+    readonly replaceEnd: number;
+    readonly tokenStart: number;
+    /**
+     * Fence rewrites to apply in the SAME undo step as an accepted container
+     * item, in pre-edit coordinates, never on the insertion line. Empty when
+     * no item in the response opens a container or the document's fences do
+     * not pair cleanly. Every container item in one context inserts the same
+     * fence shape, so one list serves them all; a host applies it only when
+     * the accepted item is a container (`isContainerCompletionItem`).
+     */
+    readonly fenceEdits: readonly HostTextEdit[];
+}
+/** Whether accepting `item` opens a container, and so needs `CompletionPlan.fenceEdits` applied with it. */
+export declare function isContainerCompletionItem(item: {
+    readonly insertText: string;
+}): boolean;
+/**
+ * `completionAt` over a whole document at a position, plus the two
+ * decisions both editors used to repeat at their own trigger boundary: a
+ * bare colon run that CLOSES an open container is not an opener waiting
+ * for a name (so no plan), and fence edits are computed once per response.
+ * Returns `undefined` when there is nothing to offer. Never throws.
+ */
+export declare function completionPlanAt(documentText: string, position: LineColumn, catalog: readonly InsertableComponent[]): CompletionPlan | undefined;
+/** `hoverAt` composed over a `HostEditor`'s document text at a given position, the same way `completeAtViaEditor` composes `completionAt`. */
+export declare function hoverAtViaEditor(editor: Pick<HostEditor, 'documentText'>, position: LineColumn, catalog: readonly InsertableComponent[]): HoverInfo | undefined;
+/**
+ * Plain-text hover documentation for `item`: `@markii/stdlib/editor`'s
+ * `formatComponentDocumentation`, the shape every host without a
+ * rich-markdown hover surface (or a host doing its own markdown mapping)
+ * can use as-is. This is also what `createMarkiiHost`'s `hoverAt` returns
+ * (via `hoverAtViaEditor`'s `HoverInfo.documentation`) rather than the
+ * bare summary sentence: the summary alone can read as generic prose with
+ * no component name in it (a callout's summary is "A colored box for an
+ * aside, warning, or danger note.", nowhere mentioning "callout"), while
+ * the formatted text's `Example: :::callout{}` line always names the
+ * directive.
+ */
+export declare function hoverDocumentationText(item: InsertableComponent): string;
+/** One text edit and the cursor position an insertion leaves behind, both relative to the document `insertionLine`/`insertionColumn` named. */
+export interface InsertComponentEdit {
+    readonly line: number;
+    readonly startColumn: number;
+    readonly endColumn: number;
+    readonly text: string;
+}
+export interface InsertComponentPlan {
+    /**
+     * Every edit `HostEditor.applyEdits` must apply together as one
+     * undoable edit: the skeleton insertion plus any fence lines an
+     * enclosing container needs lengthened.
+     *
+     * All edits are expressed in the ORIGINAL document's coordinates (the
+     * text `documentText` named, before any of these edits land) — exactly
+     * like `fenceExtensionEdits` already promises, and exactly what both
+     * apps' `HostTextEdit`-consuming adapters already assume of a
+     * multi-edit `applyEdits` call. That is what makes the array safe to
+     * apply as one atomic transaction: a host whose `applyEdits` resolves
+     * every position against the pre-edit document (VS Code's
+     * `WorkspaceEdit`, Obsidian's `Editor.transaction`) can apply them in
+     * any order.
+     *
+     * The array is ALSO returned bottom-to-top (descending by line, ties
+     * broken by descending column) as a second-line defense for a simpler
+     * host: one that applies this list as a sequence of plain string
+     * splices against a single mutable buffer rather than a coordinate-free
+     * transaction. Splicing text at a line shifts every line and column
+     * number below it; splicing from the bottom of the document upward
+     * means each edit is always applied before anything that could move
+     * out from under it, and nothing below an edit's line is ever touched
+     * after that edit lands. Fence edits never land on the insertion line
+     * itself (`fenceExtensionEdits`'s own guarantee, an enclosing pair by
+     * definition straddles it), so the insertion edit's own line never
+     * collides with a fence edit's line and the ordering rule never has to
+     * break a tie between them.
+     */
+    readonly edits: readonly InsertComponentEdit[];
+    readonly cursor: LineColumn;
+}
+/**
+ * Builds the skeleton for `component` (`@markii/stdlib/editor`'s
+ * `componentSkeleton`), turns its flat `cursorOffset` into an absolute
+ * line/column given where the insertion happens, and folds in the fence
+ * edits (`@markii/stdlib/editor`'s `fenceExtensionEdits`) an enclosing
+ * container needs lengthened so it still nests legally. This is the pure
+ * half of both apps' `insert-component.ts` command handlers: build the
+ * skeleton, insert it at the cursor, lengthen any enclosing fences, place
+ * the cursor inside it — all in one plan a host applies as one undoable
+ * edit (`HostEditor.applyEdits`'s contract).
+ *
+ * `documentText` is the document as it stands before this insertion (the
+ * same text `fenceExtensionEdits` scans); a caller inserting from a
+ * completion accept passes the same text it already read to decide what
+ * to insert.
+ *
+ * Never throws: a failure to compute fence edits (hostile input, an
+ * unpaired document `fenceExtensionEdits` refuses to touch) degrades to
+ * the skeleton insertion alone, exactly as inserting always worked before
+ * fence auto-extension existed.
+ */
+export declare function insertComponentPlan(component: Pick<InsertableComponent, 'directiveName' | 'kind'> & {
+    readonly requiredAttributes?: readonly string[];
+}, documentText: string, insertionLine: number, insertionColumn: number): InsertComponentPlan;

package/dist/host/editor-behavior.js

@@ -0,0 +1,223 @@
+/**
+ * The `completeAt`/`hoverAt`/`insertComponent` behaviors' shared half,
+ * merged from `apps/vscode/src/completion.ts` + `completion-catalog.ts`,
+ * `apps/obsidian/src/complete-component.ts`, and both apps'
+ * `insert-component.ts`.
+ *
+ * NODE-FREE by design: re-exported
+ * from `../browser.ts` as well as `../index.ts`, so VS Code's webview
+ * bundle can read the origin-tag vocabulary and the pure completion math
+ * directly if a future slice needs to. `CatalogCache.get`'s injected
+ * `load` is the one thing that reaches disk, and it is always supplied by
+ * the caller (a main-entry-only pack-discovery call), never imported here.
+ *
+ * What stays app-side (deliberately): VS
+ * Code's sectioned quick-pick presentation (`Standard`/`Layout`/`<pack>
+ * pack` separators) and Obsidian's flat fuzzy list are a genuine product
+ * difference, not duplication — this module returns the catalog and the
+ * origin tag; it never picks a picker shape. Snippet escaping
+ * (`snippetText`) is VS Code's own snippet-syntax concern and stays there
+ * too. Hover exists only on VS Code today; a host with no `adapter.editor`
+ * simply never calls `hoverAtViaAdapter`.
+ */
+import { closesOpenContainerFence, completionAt, componentDocumentation, fenceExtensionEdits, insertedContainerColonCount, formatComponentDocumentation, hoverAt, offsetToLineColumn, componentSkeleton, } from '@markii/stdlib/editor';
+/** The origin tag every host's completion row shows for a component item: `'standard'`, `'layout'`, or the owning pack's own namespace. Empty string for an attribute or value item, which has no `group`. */
+export const STANDARD_ORIGIN_TAG = 'standard';
+export const LAYOUT_ORIGIN_TAG = 'layout';
+/**
+ * The origin tag a completion item carries: the lower-case
+ * `'standard'`/`'layout'` strings above, or the pack name.
+ */
+export function completionOriginTag(item) {
+    if (item.kind !== 'component')
+        return '';
+    if (item.group === 'standard')
+        return STANDARD_ORIGIN_TAG;
+    if (item.group === 'layout')
+        return LAYOUT_ORIGIN_TAG;
+    return item.packName ?? '';
+}
+/**
+ * Builds a `CatalogCache` around `buildCatalog` (typically
+ * `../insert/component-catalog.js`'s `buildComponentCatalog` composed with
+ * a pack-discovery call). Concurrent `get()` calls made before a build
+ * finishes share one in-flight promise rather than each starting their own
+ * pack discovery.
+ */
+export function createCatalogCache(buildCatalog) {
+    let cached;
+    let pending;
+    async function build() {
+        try {
+            return await buildCatalog();
+        }
+        catch {
+            return [];
+        }
+    }
+    return {
+        async get() {
+            if (cached !== undefined)
+                return cached;
+            if (pending === undefined) {
+                pending = build().then((catalog) => {
+                    cached = catalog;
+                    pending = undefined;
+                    return catalog;
+                });
+            }
+            return pending;
+        },
+        peek() {
+            return cached;
+        },
+        invalidate() {
+            cached = undefined;
+            pending = undefined;
+        },
+    };
+}
+/** The line of `documentText` that `line` (zero-based) names, or `''` past the end of the document. */
+function lineTextAt(documentText, line) {
+    return documentText.split('\n')[line] ?? '';
+}
+/**
+ * `completionAt` composed over a `HostEditor`'s document text, at the
+ * POSITION a completion request names — not `editor.cursor()`. A real
+ * editor's completion provider is invoked with an explicit position (the
+ * position the user is typing at when the provider fires), which is why a
+ * completion/hover request always carries its own `line`/`column` rather
+ * than reading the live caret a second time. `editor.cursor()` stays
+ * reserved for `insertComponentPlan`, which genuinely inserts at the
+ * caret.
+ */
+export function completeAtViaEditor(editor, position, catalog) {
+    const line = lineTextAt(editor.documentText(), position.line);
+    return completionAt(line, position.column, catalog);
+}
+/** Whether accepting `item` opens a container, and so needs `CompletionPlan.fenceEdits` applied with it. */
+export function isContainerCompletionItem(item) {
+    try {
+        return insertedContainerColonCount(item.insertText) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `completionAt` over a whole document at a position, plus the two
+ * decisions both editors used to repeat at their own trigger boundary: a
+ * bare colon run that CLOSES an open container is not an opener waiting
+ * for a name (so no plan), and fence edits are computed once per response.
+ * Returns `undefined` when there is nothing to offer. Never throws.
+ */
+export function completionPlanAt(documentText, position, catalog) {
+    try {
+        const line = lineTextAt(documentText, position.line);
+        if (closesOpenContainerFence(documentText, position.line, line)) {
+            return undefined;
+        }
+        const context = completionAt(line, position.column, catalog);
+        if (context.kind === 'none' || context.items.length === 0) {
+            return undefined;
+        }
+        const container = context.items.find(isContainerCompletionItem);
+        let fenceEdits = [];
+        if (container !== undefined) {
+            try {
+                fenceEdits = fenceExtensionEdits(documentText, position.line, container.insertText)
+                    .filter((edit) => edit.line !== position.line)
+                    .map((edit) => ({
+                    line: edit.line,
+                    startColumn: edit.column,
+                    endColumn: edit.column + edit.oldText.length,
+                    text: edit.newText,
+                }));
+            }
+            catch {
+                fenceEdits = [];
+            }
+        }
+        return {
+            kind: context.kind,
+            items: context.items,
+            replaceStart: context.replaceStart,
+            replaceEnd: context.replaceEnd,
+            tokenStart: context.tokenStart ?? context.replaceStart,
+            fenceEdits,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `hoverAt` composed over a `HostEditor`'s document text at a given position, the same way `completeAtViaEditor` composes `completionAt`. */
+export function hoverAtViaEditor(editor, position, catalog) {
+    const line = lineTextAt(editor.documentText(), position.line);
+    return hoverAt(line, position.column, catalog);
+}
+/**
+ * Plain-text hover documentation for `item`: `@markii/stdlib/editor`'s
+ * `formatComponentDocumentation`, the shape every host without a
+ * rich-markdown hover surface (or a host doing its own markdown mapping)
+ * can use as-is. This is also what `createMarkiiHost`'s `hoverAt` returns
+ * (via `hoverAtViaEditor`'s `HoverInfo.documentation`) rather than the
+ * bare summary sentence: the summary alone can read as generic prose with
+ * no component name in it (a callout's summary is "A colored box for an
+ * aside, warning, or danger note.", nowhere mentioning "callout"), while
+ * the formatted text's `Example: :::callout{}` line always names the
+ * directive.
+ */
+export function hoverDocumentationText(item) {
+    return formatComponentDocumentation(componentDocumentation(item));
+}
+/**
+ * Builds the skeleton for `component` (`@markii/stdlib/editor`'s
+ * `componentSkeleton`), turns its flat `cursorOffset` into an absolute
+ * line/column given where the insertion happens, and folds in the fence
+ * edits (`@markii/stdlib/editor`'s `fenceExtensionEdits`) an enclosing
+ * container needs lengthened so it still nests legally. This is the pure
+ * half of both apps' `insert-component.ts` command handlers: build the
+ * skeleton, insert it at the cursor, lengthen any enclosing fences, place
+ * the cursor inside it — all in one plan a host applies as one undoable
+ * edit (`HostEditor.applyEdits`'s contract).
+ *
+ * `documentText` is the document as it stands before this insertion (the
+ * same text `fenceExtensionEdits` scans); a caller inserting from a
+ * completion accept passes the same text it already read to decide what
+ * to insert.
+ *
+ * Never throws: a failure to compute fence edits (hostile input, an
+ * unpaired document `fenceExtensionEdits` refuses to touch) degrades to
+ * the skeleton insertion alone, exactly as inserting always worked before
+ * fence auto-extension existed.
+ */
+export function insertComponentPlan(component, documentText, insertionLine, insertionColumn) {
+    const skeleton = componentSkeleton(component.directiveName, component.kind, component.requiredAttributes ?? []);
+    const relative = offsetToLineColumn(skeleton.text, skeleton.cursorOffset);
+    const cursor = relative.line === 0
+        ? { line: insertionLine, column: insertionColumn + relative.column }
+        : { line: insertionLine + relative.line, column: relative.column };
+    const insertionEdit = {
+        line: insertionLine,
+        startColumn: insertionColumn,
+        endColumn: insertionColumn,
+        text: skeleton.text,
+    };
+    let fenceEdits;
+    try {
+        fenceEdits = fenceExtensionEdits(documentText, insertionLine, skeleton.text)
+            .filter((edit) => edit.line !== insertionLine)
+            .map((edit) => ({
+            line: edit.line,
+            startColumn: edit.column,
+            endColumn: edit.column + edit.oldText.length,
+            text: edit.newText,
+        }));
+    }
+    catch {
+        fenceEdits = [];
+    }
+    const edits = [...fenceEdits, insertionEdit].sort((a, b) => a.line !== b.line ? b.line - a.line : b.startColumn - a.startColumn);
+    return { edits, cursor };
+}

package/dist/host/export/md-plain.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Downgrades `text` to plain CommonMark: container directives lose their
+ * opening/closing fence lines and keep their inner markdown, leaf
+ * directives are removed, a text directive is replaced by its own text
+ * content, and named script fences are removed entirely. A component
+ * becomes its inner content only — this is a readability floor, not a
+ * faithful render.
+ *
+ * Every edit is a pure deletion (the inner text a directive wraps is
+ * already the correct, final text — nothing is rewritten, only the
+ * surrounding directive syntax is cut away), applied from the END of the
+ * source backwards so earlier offsets stay valid as later ones are
+ * consumed.
+ */
+export declare function mdPlainFromSource(text: string): string;

package/dist/host/export/md-plain.js

@@ -0,0 +1,125 @@
+/**
+ * The `md-plain` export format: a SOURCE-LEVEL rewrite of a note down to
+ * plain CommonMark. Moved out of `apps/cli/src/export-note.ts` (the only
+ * host that ever offered this format): pure logic over `@markii/core`'s
+ * parse tree that never imports `node:*`, so it never belonged behind an
+ * app's main entry in the first place.
+ *
+ * No markdown serializer, no new dependency: every directive's own
+ * fence/bracket syntax is deleted from the original text using the
+ * offsets `@markii/core`'s `parse` already puts on every node, leaving the
+ * author's own inner markdown untouched.
+ */
+import { parse, extractScripts } from '@markii/core';
+import { visit, SKIP } from 'unist-util-visit';
+function offsetsOf(position) {
+    if (position === undefined ||
+        position.start.offset === undefined ||
+        position.end.offset === undefined) {
+        return undefined;
+    }
+    return { start: position.start.offset, end: position.end.offset };
+}
+/**
+ * The shared logic for a container directive or a text directive: keep
+ * exactly the children's own source range, trimming the fence lines
+ * (container) or `:name[`/`]{...}` (text) away on either side. An empty
+ * directive (no children — attributes only, or no label) has nothing to
+ * preserve, so its whole range is removed instead, and visiting does not
+ * need to descend into it.
+ */
+function wrapperEdits(node, edits) {
+    const outer = offsetsOf(node.position);
+    if (outer === undefined)
+        return undefined;
+    const { children } = node;
+    if (children.length === 0) {
+        edits.push(outer);
+        return SKIP;
+    }
+    const first = children[0];
+    const last = children[children.length - 1];
+    const firstOffsets = offsetsOf(first?.position);
+    const lastOffsets = offsetsOf(last?.position);
+    if (firstOffsets !== undefined && firstOffsets.start > outer.start) {
+        edits.push({ start: outer.start, end: firstOffsets.start });
+    }
+    if (lastOffsets !== undefined && lastOffsets.end < outer.end) {
+        edits.push({ start: lastOffsets.end, end: outer.end });
+    }
+    // No SKIP: keep visiting into `children` so a nested directive inside
+    // this one's content still gets its own wrapper stripped.
+    return undefined;
+}
+/**
+ * Every directive's wrapper-syntax edit: a leaf directive (`::name[...]`)
+ * is removed in full (there is no "inner markdown" to keep — a leaf
+ * directive's label is inline attributes-shaped content, not a nested
+ * document); a container or text directive keeps its inner markdown and
+ * loses only its own fence/bracket syntax (`wrapperEdits`, above).
+ */
+function collectDirectiveEdits(tree) {
+    const edits = [];
+    visit(tree, 'containerDirective', (node) => wrapperEdits(node, edits));
+    visit(tree, 'textDirective', (node) => wrapperEdits(node, edits));
+    visit(tree, 'leafDirective', (node) => {
+        const outer = offsetsOf(node.position);
+        if (outer !== undefined)
+            edits.push(outer);
+        return SKIP;
+    });
+    return edits;
+}
+/** Script fences are removed entirely — their own `position` (the whole fence, per `@markii/core`'s `extractScripts`) is the edit. */
+function collectScriptEdits(tree) {
+    const edits = [];
+    const blocks = extractScripts(tree);
+    for (const block of blocks) {
+        const offsets = offsetsOf(block.position);
+        if (offsets !== undefined)
+            edits.push(offsets);
+    }
+    return edits;
+}
+/**
+ * Downgrades `text` to plain CommonMark: container directives lose their
+ * opening/closing fence lines and keep their inner markdown, leaf
+ * directives are removed, a text directive is replaced by its own text
+ * content, and named script fences are removed entirely. A component
+ * becomes its inner content only — this is a readability floor, not a
+ * faithful render.
+ *
+ * Every edit is a pure deletion (the inner text a directive wraps is
+ * already the correct, final text — nothing is rewritten, only the
+ * surrounding directive syntax is cut away), applied from the END of the
+ * source backwards so earlier offsets stay valid as later ones are
+ * consumed.
+ */
+export function mdPlainFromSource(text) {
+    const tree = parse(text);
+    const edits = [
+        ...collectDirectiveEdits(tree),
+        ...collectScriptEdits(tree),
+    ].sort((a, b) => b.start - a.start);
+    let result = text;
+    for (const edit of edits) {
+        result = result.slice(0, edit.start) + result.slice(edit.end);
+    }
+    return collapseBlankRuns(result);
+}
+/**
+ * Collapses a run of three or more consecutive newlines down to two, and
+ * trims the leading and trailing blank lines off the whole file.
+ *
+ * Cutting a directive out of the source leaves the blank lines that stood
+ * on either side of it behind, so a note with a few leaf directives comes
+ * out pocked with three and four line gaps. CommonMark treats any run of
+ * blank lines as one paragraph break, so closing them up changes nothing
+ * about how the file parses and a great deal about how it reads.
+ */
+function collapseBlankRuns(text) {
+    return `${text
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/^\n+/, '')
+        .replace(/\n+$/, '')}\n`;
+}

package/dist/host/export-behavior.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The `exportNote` behavior: outcome shape, wording, and format gating,
+ * merged from `apps/vscode/src/export-html.ts`, the host-neutral half of
+ * `apps/obsidian/src/export-note.ts`, and `apps/cli/src/export-note.ts`'s
+ * `exportHtml`.
+ *
+ * `html` and `md-plain` are fully implemented here, over `../export/note-export.js`'s
+ * `buildNoteExport` (already host-neutral, already shared) and
+ * `./export/md-plain.js`'s `mdPlainFromSource` (moved in this same phase).
+ * `ansi` needs an engine this package does not depend on
+ * (`@markii/ansi` is deliberately never a `@markii/host` dependency — see
+ * AGENTS.md's package boundaries), so it is rendered through the injected
+ * `renderAnsi` option; a host that omits it gets `Unsupported`.
+ *
+ * PDF stays a seam, never an implementation here, this module builds the same HTML
+ * document `html` would have written and hands it to
+ * `adapter.exports.htmlToPdf`, but the DEGRADE-TO-HTML-ON-FAILURE product
+ * behavior Obsidian's own `exportNoteAsPdf` layers on top (falling back to
+ * writing the HTML file when printing is unavailable or fails, and
+ * reporting which of the two happened) is Obsidian-specific policy about
+ * what to do with a seam's failure, not the seam itself — it stays
+ * app-side.
+ *
+ * Cascade orchestration (multi-note export, `walkNoteCascade` +
+ * `assignCascadeFileNames` + `rewriteCascadeLinks` + `zipExportArchive`)
+ * is not part of this module: it stays with each host.
+ */
+import type { StoredValue } from '@markii/runtime';
+import type { OnDiagnostic, UnavailableComponent } from '@markii/stdlib';
+import type { HtmlExportEngine, ExportBodyRenderer, ExportPackStylesheet, ExportRenderInfo, StaticExportReason } from '../export/note-export.js';
+import type { EmbeddedImageReport, ExportImageReader } from '../export/image-embed.js';
+import type { HostAdapter, HostExportFormat, HostLabels } from './adapter.js';
+/** The file name an export lands under, by format: the note's own base name with the format's own extension, so the export lands beside the note unless the host's picker says otherwise. */
+export declare function exportDefaultFileName(notePath: string, format: HostExportFormat): string;
+/** What a `'html'` or `'pdf'` export attempt produced. Every shape except `failed` means the host got a file, and every shape but `failed` carries the same diagnostics-facing detail so the two hosts' wording can share it. */
+export type NoteFileExportOutcome = {
+    readonly kind: 'written';
+    readonly path: string;
+    readonly bytes: number;
+    /** How many last-run values were baked into the file. */
+    readonly valueCount: number;
+    /** `true` when the note contains a script fence. Absent or `false` means no scripts, so the message never explains an empty state the note cannot have. */
+    readonly hasScripts?: boolean;
+    /** Which engine rendered the body, and why when it was the static one. Diagnostics-facing only. */
+    readonly render: ExportRenderInfo;
+    /** What image embedding did. The empty report when the note has no images or none was offered a reader. */
+    readonly images: EmbeddedImageReport;
+} | {
+    readonly kind: 'failed';
+    readonly path?: string;
+    readonly reason: string;
+};
+/** The last path segment of a `/`-separated or `\`-separated path, for naming a file in a message. */
+export declare function fileNameOf(path: string): string;
+/**
+ * The short result message for a written or failed html/pdf export. A
+ * success names the file. A failure says what failed and points at this
+ * host's own diagnostics surface (`labels.diagnosticsSurface`), never at
+ * a stack trace — the verbatim reason goes there instead.
+ */
+export declare function exportResultMessage(outcome: NoteFileExportOutcome, labels: HostLabels): string;
+/** One diagnostic line describing HOW an export's body was rendered: the pack-vs-static distinction, kept off the result message and put here instead. */
+export declare function renderEngineDiagnosticLine(render: ExportRenderInfo): string;
+/** `bytes`, formatted as a human-readable size (`"1.2 KB"`, `"512 bytes"`). */
+export declare function formatByteSize(bytes: number): string;
+/** The image lines for `exportDiagnosticLines`: how many images were embedded and how many bytes they added, one line per skipped image, and a remote-source count when any sources still reach the network. Empty when a note has no images at all. */
+export declare function imageEmbedDiagnosticLines(images: EmbeddedImageReport): string[];
+/** The full diagnostics-surface detail for one html/pdf export attempt. */
+export declare function exportDiagnosticLines(outcome: NoteFileExportOutcome): string[];
+/** What `exportHtmlDocumentViaAdapter` needs beyond the note's own text and path. */
+export interface ExportHtmlDocumentRequest {
+    /** The static HTML engine. Required for the `html` and `pdf` formats; `exportNoteFileViaAdapter` declines those without it. */
+    readonly engine?: HtmlExportEngine;
+    readonly notePath: string;
+    readonly text: string;
+    readonly values?: Record<string, StoredValue>;
+    readonly renderBody?: ExportBodyRenderer;
+    readonly staticReason?: StaticExportReason;
+    readonly packStylesheets?: readonly ExportPackStylesheet[];
+    readonly packCount?: number;
+    readonly embedImages?: ExportImageReader;
+    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;
+}
+/** Builds the standalone HTML document `html` and `pdf` both export, via the shared, already-host-neutral `buildNoteExport`. Never throws: a failing `renderBody` degrades to the static engine rather than propagating. */
+export declare function buildExportDocument(request: ExportHtmlDocumentRequest & {
+    readonly engine: HtmlExportEngine;
+}): Promise<{
+    html: string;
+    valueCount: number;
+    hasScripts: boolean;
+    render: ExportRenderInfo;
+    images: EmbeddedImageReport;
+}>;
+/**
+ * Exports one note as `format`, gated on `adapter.exports?.formats`. A
+ * format the host has not declared returns `undefined` immediately
+ * (`createMarkiiHost`'s `exportNote` turns that into the shared
+ * `Unsupported` outcome and writes its own diagnostics line, matching
+ * every other capability-gated behavior).
+ *
+ * `renderAnsi` is required to actually produce an `'ansi'` outcome — a
+ * host that offers the `'ansi'` FORMAT capability but passes no renderer
+ * is a configuration bug on that host's part, not a Markii user's problem
+ * to see, so it also resolves to `undefined` here (never a thrown error)
+ * and the caller's `Unsupported` fallback covers it.
+ */
+export declare function exportNoteFileViaAdapter(adapter: HostAdapter, format: HostExportFormat, request: ExportHtmlDocumentRequest, renderAnsi?: (text: string) => Promise<string>): Promise<NoteFileExportOutcome | undefined>;