@markii/host 0.0.1 → 0.17.0-next.3

package/dist/host/adapter.d.ts

@@ -0,0 +1,218 @@
+/**
+ * `HostAdapter`: the minimal set of primitives a host (VS Code, Obsidian,
+ * the CLI, or a future one) provides so `createMarkiiHost` can run every
+ * shared behavior once. Nothing in this file names a `vscode`, `obsidian`,
+ * Electron or TTY type — an adapter is built from injected dependencies,
+ * so a test can construct the REAL adapter over fakes.
+ *
+ * A capability group (`isolate`, `editor`, `packs`, `exports`) is absent
+ * when a host does not offer it. `createMarkiiHost` never assumes one is
+ * present: a behavior whose capability is missing declines with an
+ * `Unsupported` outcome and a diagnostics line, per AGENTS.md's "clean is
+ * not silent" rule.
+ */
+import type { GrantMemento } from '../run/grant-flow.js';
+import type { IsolateSpawner } from '../run/isolate.js';
+import type { LineColumn } from '@markii/stdlib/editor';
+import type { DiscoveredPack } from '../packs/discover.js';
+/** One entry from `listFolder`. Reuses the shape `@markii/host`'s existing `PackDirectoryLister` (`../packs/discover.ts`) already returns, rather than inventing a second. */
+export interface HostDirEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+}
+/**
+ * One yes/no question. Every grant, consent, and replace prompt in the
+ * whole app surface routes through this single method. `message`, `allowLabel`, and `denyLabel` are already fully
+ * built by `@markii/host`; the adapter only has to show them.
+ */
+export interface HostPromptRequest {
+    readonly kind: 'grant-host' | 'grant-unknown-hosts' | 'grant-many-hosts' | 'pack-install-consent' | 'pack-replace' | 'pack-overwrite-export' | 'enable-scripts';
+    readonly message: string;
+    readonly allowLabel: string;
+    readonly denyLabel: string;
+    /**
+     * `true` for anything authorizing execution or network. A host that can
+     * only show a non-blocking surface (the CLI with no TTY, for example)
+     * must DENY rather than assume yes — that policy stays the host's own,
+     * `HostAdapter.prompt`'s contract only requires it never THROWS.
+     */
+    readonly consequential: boolean;
+}
+/**
+ * A discriminated union: `workerPath` and `workerBytes` are mutually
+ * exclusive per host. A Node host (VS Code, the CLI)
+ * gives a synchronous path lookup; a host whose runtime cannot create
+ * worker threads (an Electron renderer, which is what the Obsidian plugin
+ * runs in) gives an async, disposable Web Worker spawner instead.
+ */
+export type HostIsolate = {
+    readonly kind: 'node';
+    /**
+     * The worker entry on disk. A host with its own bundled worker
+     * resolves it here. `createNodeHostIsolate()` from
+     * `@markii/host/node` supplies the packaged one.
+     */
+    workerPath(): string;
+    /**
+     * Creates the worker-thread isolate: `workerThreadIsolate` from
+     * `@markii/host/node`. Injected so the shared run path imports
+     * nothing from `node:*`.
+     */
+    readonly spawnIsolate: IsolateSpawner;
+} | {
+    readonly kind: 'browser';
+    spawner(): Promise<IsolateSpawner>;
+    dispose(): void;
+    /**
+     * What a browser isolate reports as its entry. A Web Worker started
+     * from a blob URL has no path to name, but the run path still labels
+     * the entry it handed out, so this supplies that label. It is never
+     * resolved or opened. Defaults to `BROWSER_ISOLATE_ENTRY`.
+     */
+    entryLabel?: string;
+};
+/**
+ * The entry label a blob-URL Web Worker reports when its host does not
+ * supply one. It is a label, never a path: nothing resolves or opens it,
+ * and the worker's real bytes come from the blob the host built. It exists
+ * because the shared run path always names the entry it handed out, and
+ * the alternative (leaving the entry unset) reaches a fallback that is
+ * deliberately dev-only and throws in a packaged host.
+ */
+export declare const BROWSER_ISOLATE_ENTRY = "markii:embedded-worker";
+export interface HostTextEdit {
+    /** Zero-based. */
+    readonly line: number;
+    readonly startColumn: number;
+    readonly endColumn: number;
+    readonly text: string;
+}
+/**
+ * The live editor surface, for hosts that have one. `applyEdits` applies
+ * the whole array as ONE undoable edit — both GUI hosts already do this
+ * for insertion plus fence extension; stating it here means a third host
+ * cannot get it wrong. The CLI omits `editor` entirely: it has no live
+ * cursor or edit surface.
+ */
+export interface HostEditor {
+    documentText(): string;
+    documentPath(): string | undefined;
+    cursor(): LineColumn;
+    applyEdits(edits: readonly HostTextEdit[]): Promise<boolean>;
+}
+/**
+ * Pack POLICY (which folders are even candidates) is irreducibly
+ * host-specific; everything after the list exists is
+ * already shared in `../packs/discover.ts` and friends. The adapter
+ * supplies only the list and the install destination.
+ */
+export interface HostPackSource {
+    /**
+     * The renderer engine this host runs packs for (`@markii/pack`'s
+     * per-component `sources` keys): `react` for the GUI hosts, `ansi` for
+     * the terminal host. Required: the host layer names no engine itself.
+     * Discovery, completion and insert keep only packs and components that
+     * have a source for it.
+     */
+    readonly engine: string;
+    /**
+     * Whether installed packs are gated on a device-local trust list.
+     * `'device-list'`: a folder in `installRoot` loads only when the trust
+     * list in the adapter's `memento` names its namespace, and the host
+     * gains `installedPacks`, `enablePack` and `disablePack`. An install
+     * trusts the pack it installs. Requires `installRoot`. `'none'`: every
+     * folder this host's own policy authorizes loads, which is right for a
+     * host that trusts its own install store (VS Code, the CLI). A web host
+     * that installs packs from users picks `'device-list'`. Required: a
+     * host states its choice explicitly.
+     */
+    readonly trust: 'device-list' | 'none';
+    /**
+     * Folders this host currently AUTHORIZES. Under `trust: 'device-list'`
+     * these are the folders beyond the install root (the host adds the
+     * trusted installed ones itself): VS Code's resolved
+     * `markii.packs` setting plus bundled packs; Obsidian's trust-filtered
+     * installed folders plus bundled packs.
+     */
+    authorizedFolders(): Promise<readonly string[]>;
+    /**
+     * Namespaces an install may never claim. Empty for VS Code, the bundled
+     * three (`read`/`dash`/`prep`) for Obsidian.
+     */
+    reservedNamespaces(): ReadonlySet<string>;
+    /** Where an installed pack is unzipped. Absent means this host cannot install a pack. */
+    installRoot?(): string;
+    /**
+     * Packs embedded in the host's own build, with no folder on disk
+     * (Obsidian carries its bundled packs inside `main.js`). They join the
+     * catalog completion, hover, and insert read, ahead of the discovered
+     * ones. Absent when every pack the host offers lives in a folder
+     * `authorizedFolders` names.
+     */
+    bundledPacks?(): readonly DiscoveredPack[];
+    /** Removes an installed pack folder. Required when `installRoot` is present. */
+    removeFolder?(path: string): Promise<void>;
+}
+/** Every export format any host offers today. */
+export type HostExportFormat = 'html' | 'pdf' | 'ansi' | 'md-plain';
+export interface HostExportCapabilities {
+    readonly formats: ReadonlySet<HostExportFormat>;
+    /** GUI hosts show a picker; the CLI returns the path it was given. */
+    resolveTarget(suggestedFileName: string, format: HostExportFormat): Promise<string | undefined>;
+    /** Only present on a host declaring `'pdf'`. The one Electron-touching seam. */
+    htmlToPdf?(html: string): Promise<Uint8Array>;
+}
+/**
+ * The wording nouns every shared behavior's message templates interpolate
+ * (`./labels.ts`). One template plus these per-host nouns
+ * replaces a per-host copy of each sentence.
+ */
+export interface HostLabels {
+    /** "extension" | "plugin" | "command line tool" */
+    readonly appNoun: string;
+    /** "every Markii preview" | "the Markii preview" | "the rendered note" */
+    readonly previewNoun: string;
+    /** "the Markii output" | "the Markii diagnostics" | "the run log" */
+    readonly diagnosticsSurface: string;
+    /** "this workspace" | "this device" */
+    readonly deviceNoun: string;
+    /**
+     * The literal setting a user would toggle to turn script execution back
+     * on, when this host exposes one as a named setting (`"markii.scriptsDisabled"`
+     * for VS Code). Naming it is how a user finds the switch without opening
+     * developer tools (AGENTS.md's "clean is not silent" test), so
+     * `./script-execution.ts`'s diagnostics-surface lines include it when
+     * present. `undefined` for a host with no single named setting (a
+     * command or toggle instead) — the plain sentence is used there.
+     */
+    readonly settingName?: string;
+}
+/**
+ * Everything an adapter provides. An adapter is constructible from
+ * injected dependencies (no module-scope global reads), which is what
+ * lets a conformance test build the REAL adapter over a fake editor
+ *.
+ */
+export interface HostAdapter {
+    readonly id: 'vscode' | 'obsidian' | 'cli' | (string & {});
+    readonly labels: HostLabels;
+    readFile(path: string): Promise<Uint8Array>;
+    exists(path: string): Promise<boolean>;
+    writeFile(path: string, bytes: Uint8Array): Promise<void>;
+    /** A missing folder resolves to an empty list — never throws, matching the existing `PackDirectoryLister` contract. */
+    listFolder(path: string): Promise<readonly HostDirEntry[]>;
+    prompt(request: HostPromptRequest): Promise<boolean>;
+    /**
+     * Device-local state. Structurally the existing `GrantMemento`,
+     * unchanged, so VS Code keeps handing `context.workspaceState` straight
+     * through with no adapter wrapper at all.
+     */
+    readonly memento: GrantMemento;
+    /** One diagnostics line on this host's designated surface (docs/integration.md). */
+    diagnostics(line: string): void;
+    now(): number;
+    readonly isolate?: HostIsolate;
+    readonly editor?: HostEditor;
+    readonly packs?: HostPackSource;
+    readonly exports?: HostExportCapabilities;
+}

package/dist/host/adapter.js

@@ -0,0 +1,9 @@
+/**
+ * The entry label a blob-URL Web Worker reports when its host does not
+ * supply one. It is a label, never a path: nothing resolves or opens it,
+ * and the worker's real bytes come from the blob the host built. It exists
+ * because the shared run path always names the entry it handed out, and
+ * the alternative (leaving the entry unset) reaches a fallback that is
+ * deliberately dev-only and throws in a packaged host.
+ */
+export const BROWSER_ISOLATE_ENTRY = 'markii:embedded-worker';

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

@@ -0,0 +1,120 @@
+/**
+ * The cascade export's shared half: walking the notes a root note links
+ * to, rendering each one the way a single-note export does, packing the
+ * results into one archive, and every user-facing string that outcome
+ * produces. Written once so the hosts cannot drift on what a cascade is
+ * or what it says.
+ *
+ * Deliberately outside `createMarkiiHost`: choosing where the archive goes
+ * and writing it are each host's own picker and file-system business, so
+ * this module builds the bytes and words the outcome, and the host writes
+ * and displays. The per-host nouns (which surface holds the details) come
+ * from `HostLabels`, never from a literal here.
+ *
+ * BOUNDS ARE FIXED. The walk always uses `DEFAULT_CASCADE_MAX_DEPTH` and
+ * `DEFAULT_CASCADE_MAX_NOTES`; nothing here lets a caller override them.
+ */
+import type { StoredValue } from '@markii/runtime';
+import type { OnDiagnostic, UnavailableComponent } from '@markii/stdlib';
+import type { CascadeLinkResolver, CascadeNoteReader, CascadeTruncation } from '../export/cascade.js';
+import type { HtmlExportEngine, ExportBodyRenderer, ExportPackStylesheet, ExportRenderInfo, StaticExportReason } from '../export/note-export.js';
+import type { EmbeddedImageReport, ExportImageReader } from '../export/image-embed.js';
+import type { HostLabels } from './adapter.js';
+/** One note the cascade exported, for the diagnostics surface. */
+export interface CascadeExportedNote {
+    /** The note's own path, in the same form the reader and resolver use. */
+    readonly path: string;
+    /** The file name this note got inside the archive. */
+    readonly entryName: string;
+    readonly valueCount: number;
+    readonly render: ExportRenderInfo;
+    readonly images: EmbeddedImageReport;
+}
+/** A link that resolved to a note in range which could not be read. */
+export interface UnreadableCascadeNote {
+    readonly path: string;
+    readonly from: string;
+}
+/** What one cascade export attempt did, for both the message and the diagnostics lines. */
+export type CascadeExportOutcome = {
+    readonly kind: 'written';
+    /** The written archive's display path. */
+    readonly path: string;
+    readonly bytes: number;
+    /** Every note the archive contains, breadth first, the root note first. */
+    readonly notes: readonly CascadeExportedNote[];
+    /** Notes a link pointed at that could not be read. */
+    readonly unreadable: readonly UnreadableCascadeNote[];
+    /** Set when a bound stopped the walk before it ran out of links to follow. */
+    readonly truncated?: CascadeTruncation;
+} | {
+    readonly kind: 'failed';
+    /** Where the write was attempted, when it got that far. */
+    readonly path?: string;
+    /** The verbatim reason. Diagnostics only, never the popup. */
+    readonly reason: string;
+};
+/** What building one cascade archive needs beyond a single note's export inputs. */
+export interface CascadeArchiveRequest {
+    /** The static HTML engine every note and the index page render with. */
+    readonly engine: HtmlExportEngine;
+    /** The root note's path, in whatever form `readNote` and `resolveLink` understand. */
+    readonly rootPath: string;
+    readonly readNote: CascadeNoteReader;
+    readonly resolveLink: CascadeLinkResolver;
+    /** Reads one note's persisted last-run values, keyed by that note's own path. An empty object exports that note's standard empty states. */
+    readonly readValues: (notePath: string) => Record<string, StoredValue>;
+    /** The host's React render of a note's body, shared by every note in the cascade since it comes from one merged pack registry. Omitted renders every note with the static engine. */
+    readonly renderBody?: ExportBodyRenderer;
+    /** Why the static engine is used when `renderBody` is omitted. Defaults to `no-packs`. */
+    readonly staticReason?: StaticExportReason;
+    readonly packStylesheets?: readonly ExportPackStylesheet[];
+    readonly packCount?: number;
+    /** Installed pack components the static engine cannot draw, labeled "no HTML view" in every note rendered statically. */
+    readonly unavailableComponents?: readonly UnavailableComponent[];
+    /** Receives the static engine's render diagnostics for every note. */
+    readonly onDiagnostic?: OnDiagnostic;
+    /** Builds the image reader for one note, bound to that note's own folder so a relative source resolves against the note that wrote it. Omitted embeds no images. */
+    readonly embedImagesFor?: (notePath: string) => ExportImageReader;
+    /** Hides the collapsed script marker in every exported note. Defaults to `false`. */
+    readonly hideScriptBlocks?: boolean;
+}
+/** The archive a cascade would write, or why it could not be built. Nothing is written here; the caller owns the save path. */
+export type CascadeArchiveResult = {
+    readonly kind: 'archive';
+    readonly bytes: Uint8Array;
+    readonly notes: readonly CascadeExportedNote[];
+    readonly unreadable: readonly UnreadableCascadeNote[];
+    readonly truncated?: CascadeTruncation;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+/** The verbatim reason for a thrown value, for the diagnostics surface. Never shown in a popup. */
+export declare function cascadeReasonOf(error: unknown): string;
+/** `count` plus `noun`, pluralized with a trailing `s`. Every noun used here is regular. */
+export declare function countedNoun(count: number, noun: string): string;
+/**
+ * Walks a note's cascade, exports every note it reaches, and returns the
+ * archive bytes. Never throws: an error anywhere in the walk or a render
+ * comes back as a `failed` result.
+ */
+export declare function buildCascadeArchive(request: CascadeArchiveRequest): Promise<CascadeArchiveResult>;
+/**
+ * The short message shown after a cascade export. A success names the
+ * archive and how many notes it holds, plus an optional host-specific
+ * `where` sentence (for example where the archive landed). A partial
+ * success adds one sentence pointing at the host's diagnostics surface,
+ * because a cascade that quietly left notes out would be mute about it. A
+ * failure says what failed and points at the same surface, never at a
+ * stack trace.
+ */
+export declare function cascadeResultMessage(outcome: CascadeExportOutcome, labels: HostLabels, where?: string): string;
+/**
+ * The lines for the host's diagnostics surface for one cascade export:
+ * every note reached named with the file it became, every note skipped
+ * named with the note that linked to it, and any bound that cut the walk
+ * short. A failure reaches here in full, including the reason the popup
+ * deliberately omits.
+ */
+export declare function cascadeDiagnosticLines(outcome: CascadeExportOutcome): string[];

package/dist/host/cascade-export-behavior.js

@@ -0,0 +1,151 @@
+import { CASCADE_INDEX_FILE_NAME, DEFAULT_CASCADE_MAX_DEPTH, DEFAULT_CASCADE_MAX_NOTES, assignCascadeFileNames, rewriteCascadeLinks, walkNoteCascade, } from '../export/cascade.js';
+import { buildCascadeIndexHtml, buildNoteExport, exportBaseName, exportDocumentTitle, } from '../export/note-export.js';
+import { zipExportArchive } from '../export/export-zip.js';
+import { fileNameOf, imageEmbedDiagnosticLines, renderEngineDiagnosticLine, } from './export-behavior.js';
+/** The verbatim reason for a thrown value, for the diagnostics surface. Never shown in a popup. */
+export function cascadeReasonOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** `count` plus `noun`, pluralized with a trailing `s`. Every noun used here is regular. */
+export function countedNoun(count, noun) {
+    return `${String(count)} ${noun}${count === 1 ? '' : 's'}`;
+}
+/**
+ * Walks a note's cascade, exports every note it reaches, and returns the
+ * archive bytes. Never throws: an error anywhere in the walk or a render
+ * comes back as a `failed` result.
+ */
+export async function buildCascadeArchive(request) {
+    try {
+        const walk = await walkNoteCascade({
+            rootPath: request.rootPath,
+            readNote: request.readNote,
+            resolveLink: request.resolveLink,
+            maxDepth: DEFAULT_CASCADE_MAX_DEPTH,
+            maxNotes: DEFAULT_CASCADE_MAX_NOTES,
+        });
+        if (walk.notes.length === 0) {
+            const rootUnreadable = walk.unreadable.find((entry) => entry.path === request.rootPath);
+            return {
+                kind: 'failed',
+                reason: rootUnreadable
+                    ? `could not read the root note ${rootUnreadable.path}`
+                    : 'nothing was exported',
+            };
+        }
+        // Every archive carries an index.html listing its notes, so an unzipped
+        // set has one page to open first; a note named index is renamed clear of it.
+        const fileNames = assignCascadeFileNames(walk.notes.map((note) => note.path), [CASCADE_INDEX_FILE_NAME]);
+        const notes = [];
+        const entries = [];
+        for (const note of walk.notes) {
+            const text = rewriteCascadeLinks(note, fileNames, request.resolveLink);
+            const document = await buildNoteExport({
+                engine: request.engine,
+                text,
+                fileName: note.path,
+                values: request.readValues(note.path),
+                ...(request.renderBody !== undefined
+                    ? { renderBody: request.renderBody }
+                    : {}),
+                ...(request.staticReason !== undefined
+                    ? { staticReason: request.staticReason }
+                    : {}),
+                ...(request.packStylesheets !== undefined
+                    ? { packStylesheets: request.packStylesheets }
+                    : {}),
+                ...(request.packCount !== undefined
+                    ? { packCount: request.packCount }
+                    : {}),
+                ...(request.unavailableComponents !== undefined
+                    ? { unavailableComponents: request.unavailableComponents }
+                    : {}),
+                ...(request.onDiagnostic !== undefined
+                    ? { onDiagnostic: request.onDiagnostic }
+                    : {}),
+                ...(request.embedImagesFor !== undefined
+                    ? { embedImages: request.embedImagesFor(note.path) }
+                    : {}),
+                ...(request.hideScriptBlocks !== undefined
+                    ? { hideScriptBlocks: request.hideScriptBlocks }
+                    : {}),
+            });
+            const entryName = fileNames.get(note.path) ?? `${exportBaseName(note.path)}.html`;
+            entries.push({ name: entryName, text: document.html });
+            notes.push({
+                path: note.path,
+                entryName,
+                valueCount: document.valueCount,
+                render: document.render,
+                images: document.images,
+            });
+        }
+        entries.push({
+            name: CASCADE_INDEX_FILE_NAME,
+            text: buildCascadeIndexHtml(notes.map((note) => ({
+                title: exportDocumentTitle(note.path),
+                fileName: note.entryName,
+            })), request.engine),
+        });
+        return {
+            kind: 'archive',
+            bytes: zipExportArchive(entries),
+            notes,
+            unreadable: walk.unreadable,
+            ...(walk.truncated !== undefined ? { truncated: walk.truncated } : {}),
+        };
+    }
+    catch (error) {
+        return { kind: 'failed', reason: cascadeReasonOf(error) };
+    }
+}
+/**
+ * The short message shown after a cascade export. A success names the
+ * archive and how many notes it holds, plus an optional host-specific
+ * `where` sentence (for example where the archive landed). A partial
+ * success adds one sentence pointing at the host's diagnostics surface,
+ * because a cascade that quietly left notes out would be mute about it. A
+ * failure says what failed and points at the same surface, never at a
+ * stack trace.
+ */
+export function cascadeResultMessage(outcome, labels, where) {
+    if (outcome.kind === 'failed') {
+        return `Markii: could not export this cascade. Open ${labels.diagnosticsSurface} for details.`;
+    }
+    const name = fileNameOf(outcome.path);
+    const summary = `Markii: exported ${name} with ${countedNoun(outcome.notes.length, 'note')}.`;
+    const partial = outcome.truncated !== undefined || outcome.unreadable.length > 0;
+    if (partial) {
+        return `${summary} Some linked notes were left out, so open ${labels.diagnosticsSurface} for details.`;
+    }
+    return where === undefined ? summary : `${summary} ${where}`;
+}
+/**
+ * The lines for the host's diagnostics surface for one cascade export:
+ * every note reached named with the file it became, every note skipped
+ * named with the note that linked to it, and any bound that cut the walk
+ * short. A failure reaches here in full, including the reason the popup
+ * deliberately omits.
+ */
+export function cascadeDiagnosticLines(outcome) {
+    if (outcome.kind === 'failed') {
+        const where = outcome.path ? ` to ${outcome.path}` : '';
+        return [`Cascade export failed${where}: ${outcome.reason}`];
+    }
+    const lines = [
+        `Cascade export wrote ${outcome.path}: ${String(outcome.bytes)} bytes, ${countedNoun(outcome.notes.length, 'note')}.`,
+    ];
+    for (const note of outcome.notes) {
+        lines.push(`Exported ${note.path} as ${note.entryName} with ${countedNoun(note.valueCount, 'stored value')} baked in.`, renderEngineDiagnosticLine(note.render), ...imageEmbedDiagnosticLines(note.images));
+    }
+    if (outcome.truncated === 'depth') {
+        lines.push(`The walk stopped at the maximum depth of ${String(DEFAULT_CASCADE_MAX_DEPTH)} hops, so notes further out were left out.`);
+    }
+    else if (outcome.truncated === 'count') {
+        lines.push(`The walk stopped at the maximum of ${countedNoun(DEFAULT_CASCADE_MAX_NOTES, 'note')}, so the remaining links were left out.`);
+    }
+    for (const entry of outcome.unreadable) {
+        lines.push(`Could not read ${entry.path}, linked from ${entry.from}.`);
+    }
+    return lines;
+}

package/dist/host/conformance-runner.d.ts

@@ -0,0 +1,159 @@
+import type { ArchiveExtractFs } from './pack-archive.js';
+import type { RunTrigger } from '@markii/runtime';
+import type { HostAdapter } from './adapter.js';
+/**
+ * `conformance/host/`, resolved relative to this module's own file, never
+ * `process.cwd()`. An installed package carries the corpus at
+ * `dist/conformance/host/`, a sibling of `dist/host/`; a repo checkout runs
+ * from `src/host/` and finds the repo-root corpus through
+ * `@markii/core/corpus`'s `conformanceDir`.
+ */
+export declare function hostConformanceDir(): string;
+/** Every scenario directory name under `dir`, sorted. */
+export declare function listHostScenarioNames(dir?: string): string[];
+/** A `run` action's stand-in for what a real isolate would have produced — see this file's top comment. */
+export interface RunSimulation {
+    /** The script/value name the simulated run reports on. */
+    readonly name: string;
+    /** The value a successful simulated run stores. Defaults to `1`. */
+    readonly value?: number;
+    /** A host that must be in the run's granted allowlist for the value to land; otherwise the simulated run reports `'capability-denied'`. */
+    readonly requiresHost?: string;
+    /** `true` for a simulated write: the run reports `'tier-blocked'` under any trigger but `'manual'`, regardless of grants. */
+    readonly requiresManualTier?: boolean;
+}
+export type HostScenarioAction = {
+    readonly type: 'open';
+} | {
+    readonly type: 'run';
+    readonly trigger: RunTrigger;
+    /** `"allow"`/`"deny"`, consumed by the grant flow's prompts, in order, across the WHOLE scenario (see `createAnswerQueue`). */
+    readonly answers?: readonly string[];
+    /** When `true`, this action never reaches `host.run` at all — see this file's top comment on the scripts-disabled scenario. */
+    readonly scriptsDisabled?: boolean;
+    readonly simulate?: RunSimulation;
+} | {
+    readonly type: 'exportHtml';
+} | {
+    readonly type: 'exportAnsi';
+} | {
+    readonly type: 'installPack';
+    /** A directory under the scenario's own folder (e.g. `"files/ana-1.0.0"`), zipped into `.mkp` bytes by this module — never a committed binary. */
+    readonly archive: string;
+    readonly answers?: readonly string[];
+    /** `true`: the action belongs to a trust scenario, so a host without the device trust list reports it as `unsupported` (`pack-trust`) instead of running it. */
+    readonly requiresTrust?: boolean;
+} | {
+    readonly type: 'loadPacks';
+    readonly requiresTrust?: boolean;
+} | {
+    readonly type: 'removePack';
+    readonly namespace: string;
+    readonly requiresTrust?: boolean;
+} | {
+    /** Copies a directory under the scenario's folder into the install root as `<namespace>/`, with no consent and no trust entry: the way a pack arrives through a file sync or a hand copy. */
+    readonly type: 'placePack';
+    readonly archive: string;
+    readonly namespace: string;
+} | {
+    readonly type: 'listPacks';
+} | {
+    readonly type: 'enablePack';
+    readonly namespace: string;
+    readonly answers?: readonly string[];
+} | {
+    readonly type: 'disablePack';
+    readonly namespace: string;
+} | {
+    readonly type: 'completeAt';
+    readonly line: number;
+    readonly column: number;
+} | {
+    readonly type: 'hoverAt';
+    readonly line: number;
+    readonly column: number;
+} | {
+    readonly type: 'insertComponent';
+    readonly name: string;
+};
+export interface HostScenario {
+    readonly id: string;
+    readonly invariant: string;
+    /** Fixes `adapter.now()` for the whole scenario, so a `RunTrace` write is byte-stable. */
+    readonly clock: number;
+    readonly actions: readonly HostScenarioAction[];
+}
+/** `expected.json`'s schema. `outcomes[i]` is a coarse, partial projection of `actions[i]`'s real outcome — see `outcomeMismatches` for exactly what each `kind` compares. */
+export interface HostScenarioExpected {
+    readonly outcomes: readonly Record<string, unknown>[];
+    readonly diagnostics: readonly string[];
+    readonly prompts: readonly string[];
+}
+export interface LoadedHostScenario {
+    readonly dir: string;
+    readonly noteText: string;
+    readonly scenario: HostScenario;
+    readonly expected: HostScenarioExpected;
+}
+/** Loads one scenario's three files. Never validates beyond `JSON.parse` — a malformed fixture is a corpus bug, and throwing loudly here is the right failure mode for it. */
+export declare function loadHostScenario(name: string, baseDir?: string): LoadedHostScenario;
+/** Zips a scenario's `files/<name>` directory into `.mkp` archive bytes on the fly — this is how the corpus ships pack fixtures as plain files instead of a committed binary. */
+export declare function zipArchiveDirectory(archiveDir: string): Uint8Array;
+export type HostScenarioCapability = 'isolate' | 'editor' | 'packs' | 'pack-trust' | 'export-format';
+/** The one static map from an action's type to the capability it needs. `undefined` means every host supports it (there is nothing to decline). */
+export declare const ACTION_CAPABILITY: Readonly<Record<HostScenarioAction['type'], HostScenarioCapability | undefined>>;
+/** Whether `adapter` declares the capability `action` needs. Never consults the scenario or `expected.json` — only the adapter under test. */
+export declare function hostDeclaresCapability(adapter: HostAdapter, action: HostScenarioAction): boolean;
+/**
+ * Flattens every `run`/`installPack` action's `answers` into one queue, in
+ * document order — the same order the grant/consent prompts fire in, since
+ * `expected.json`'s `prompts` array is itself the ordered proof of that.
+ * `next()` THROWS once exhausted rather than returning a default: an
+ * unanswered prompt means the scenario and the implementation disagree
+ * about how many questions get asked, which must never be silently read
+ * as a deny.
+ */
+export declare function createAnswerQueue(scenario: HostScenario): {
+    next(): boolean;
+};
+export interface HostScenarioRunResult {
+    /** `outcomes[i]` is `actions[i]`'s real (or synthesized, for the two cases documented above) outcome, JSON-shaped for diffing. */
+    readonly outcomes: readonly unknown[];
+    /** Every diagnostics line written, UNPREFIXED (this module wraps `adapter.diagnostics` before the real adapter's own sink prefixing runs), in order. */
+    readonly diagnostics: readonly string[];
+    /** Every prompt's `message`, in order, exactly as built by `@markii/host`'s shared message functions. */
+    readonly prompts: readonly string[];
+    /** Set when a scripted prompt ran out of answers — a hard error, never folded into a silent deny. */
+    readonly promptQueueError?: string;
+}
+/**
+ * Runs `scenario` against `adapter` end to end. `adapter` is the REAL,
+ * already-constructed host adapter under test (built by the caller from
+ * its own injected dependencies plus a scripted prompt source, e.g.
+ * `createAnswerQueue`); this function never builds one itself, so it works
+ * identically for any `HostAdapter`.
+ */
+export declare function runHostScenario(adapter: HostAdapter, scenario: HostScenario, noteText: string, scenarioDir: string, options?: {
+    readonly renderAnsi?: (text: string) => Promise<string>;
+    /** Where an installed pack archive is extracted. Defaults to the Node file system, which is right for an adapter that reads and writes real files. An adapter over another store (memory, a virtual file system) passes the matching writer. */
+    readonly archiveExtractFs?: ArchiveExtractFs;
+}): Promise<HostScenarioRunResult>;
+/** `expected[i]` compared against `actual[i]` for each index up to `expected`'s own length; a length mismatch is reported once rather than index-by-index noise. */
+export declare function containsInOrder(actual: readonly string[], expected: readonly string[]): string[];
+/**
+ * A coarse, per-`kind` comparison between one action's real outcome and its
+ * `expected.json` entry. Deliberately partial (matching the design's own
+ * "deliberately coarse" posture): a `'ran'` outcome compares landed values
+ * and failure KINDS, never timings or raw messages; an `'exported'` outcome
+ * compares `contains`/`excludes` substrings against the written file's
+ * content, never the whole document.
+ */
+export declare function outcomeMismatches(actual: unknown, expected: Record<string, unknown> | undefined): string[];
+/**
+ * The full assertion an app's conformance test makes for one scenario: for
+ * every action whose capability `adapter` declares, its outcome matches
+ * `expected`'s; for every other action, the outcome is exactly the shared
+ * `unsupported` record. Returns a list of human-readable problems — empty
+ * means the scenario passed.
+ */
+export declare function assertHostScenario(adapter: HostAdapter, scenario: HostScenario, expected: HostScenarioExpected, result: HostScenarioRunResult): string[];