@markii/host 0.17.0-next.3 → 0.17.0-next.5

package/dist/host/create-host.d.ts

@@ -18,9 +18,11 @@ import type { StoredValue } from '@markii/runtime';
 import type { OnDiagnostic, UnavailableComponent } from '@markii/stdlib';
 import type { CompletionItem, ComponentDocumentation, LineColumn } from '@markii/stdlib/editor';
 import { type RunViaAdapterRequest, type RunViaAdapterResult } from './run-behavior.js';
-import { type ArchiveExtractFs } from './pack-archive.js';
 import { type PackDiscoveryIo } from './pack-load.js';
-import type { HtmlExportEngine } from '../export/note-export.js';
+import type { ExportBodyRenderer, ExportPackStylesheet, ExportRenderInfo, HtmlExportEngine, StaticExportReason } from '../export/note-export.js';
+import type { EmbeddedImageReport, ExportImageReader } from '../export/image-embed.js';
+import type { CascadeLinkResolver } from '../export/cascade.js';
+import { type CascadeExportOutcome } from './cascade-export-behavior.js';
 import type { DiscoveredPack, SkippedPackFolder } from '../packs/discover.js';
 import { type TerminalPackScript } from './terminal-packs.js';
 import { type RemovePackOutcome } from './pack-remove.js';
@@ -28,7 +30,7 @@ import type { DisablePackOutcome, EnablePackOutcome, InstalledPacksListing } fro
 /** The shared decline shape every behavior returns when the adapter lacks the capability it needs. */
 export interface Unsupported {
     readonly kind: 'unsupported';
-    readonly capability: 'isolate' | 'editor' | 'packs' | 'pack-trust' | 'export-format';
+    readonly capability: 'isolate' | 'editor' | 'packs' | 'pack-trust' | 'export-format' | 'linked-set-export';
     readonly detail?: string;
 }
 export interface OpenRequest {
@@ -61,11 +63,31 @@ export interface ExportRequest {
     readonly unavailableComponents?: readonly UnavailableComponent[];
     /** Receives the static engine's render diagnostics, such as the `no-engine-view` event. */
     readonly onDiagnostic?: OnDiagnostic;
+    /** The host's own render of the body (a React pass bound to its loaded packs). Omitted means the static engine renders, and `staticReason` says why. Used by the `html` and `pdf` formats. */
+    readonly renderBody?: ExportBodyRenderer;
+    /** Why the static engine renders when `renderBody` is omitted. Defaults to `no-packs`. */
+    readonly staticReason?: StaticExportReason;
+    /** The loaded packs' stylesheets, embedded only when `renderBody` ran. */
+    readonly packStylesheets?: readonly ExportPackStylesheet[];
+    /** How many loaded packs contributed to the render. Diagnostics only. */
+    readonly packCount?: number;
+    /** Reads one of the note's local images so the export embeds it as a `data:` URI. Omitted leaves every image source as written. */
+    readonly embedImages?: ExportImageReader;
+    /** Hides the collapsed script marker in the exported file. Defaults to `false`. */
+    readonly hideScriptBlocks?: boolean;
 }
 export type ExportOutcome = {
     readonly kind: 'exported';
     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. */
+    readonly hasScripts?: boolean;
+    /** Which engine rendered the body, and why when it was the static one. */
+    readonly render: ExportRenderInfo;
+    /** What image embedding did. */
+    readonly images: EmbeddedImageReport;
 } | {
     readonly kind: 'failed';
     readonly reason: string;
@@ -74,6 +96,41 @@ export type ExportOutcome = {
  | {
     readonly kind: 'cancelled';
 } | Unsupported;
+export interface ExportLinkedSetRequest {
+    /** The root note's path, in whatever form `adapter.readFile` and `resolveLink` understand. */
+    readonly rootPath: string;
+    /** Resolves one link in a note to the path of a note this host can export, or `undefined` to leave the link as written. */
+    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 own render of each note's body. Omitted renders every note with the static engine, and `staticReason` says why. */
+    readonly renderBody?: ExportBodyRenderer;
+    /** Why the static engine renders when `renderBody` is omitted. Defaults to `no-packs`. */
+    readonly staticReason?: StaticExportReason;
+    /** The loaded packs' stylesheets, embedded only when `renderBody` ran. */
+    readonly packStylesheets?: readonly ExportPackStylesheet[];
+    /** How many loaded packs contributed to the render. Diagnostics only. */
+    readonly packCount?: number;
+    /** Installed pack components the static engine cannot draw. */
+    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. Omitted embeds no images. */
+    readonly embedImagesFor?: (notePath: string) => ExportImageReader;
+    /** Hides the collapsed script marker in every exported note. Defaults to `false`. */
+    readonly hideScriptBlocks?: boolean;
+}
+export type ExportLinkedSetOutcome = Extract<CascadeExportOutcome, {
+    kind: 'exported';
+}> | {
+    readonly kind: 'failed';
+    readonly path?: string;
+    readonly reason: string;
+}
+/** The host's picker was cancelled, so nothing was written. */
+ | {
+    readonly kind: 'cancelled';
+} | Unsupported;
 export interface InstallPackRequest {
     readonly archiveBytes: Uint8Array;
     /** The archive's own path or display name, used only in wording. Defaults to a generic phrase when omitted. */
@@ -82,6 +139,8 @@ export interface InstallPackRequest {
 export type InstallPackOutcome = {
     readonly kind: 'installed';
     readonly namespace: string;
+    /** The folder the pack now lives in, under the adapter's install root. */
+    readonly installedDir: string;
     readonly replaced: boolean;
 } | {
     readonly kind: 'declined';
@@ -196,6 +255,8 @@ export interface MarkiiHost {
     open(request: OpenRequest): Promise<OpenOutcome>;
     run(request: RunRequest): Promise<RunOutcome>;
     exportNote(request: ExportRequest): Promise<ExportOutcome>;
+    /** Exports a note and the notes it links to as one zip archive of HTML files. */
+    exportLinkedSet(request: ExportLinkedSetRequest): Promise<ExportLinkedSetOutcome>;
     installPack(request: InstallPackRequest): Promise<InstallPackOutcome>;
     loadPacks(): Promise<LoadPacksOutcome>;
     /**
@@ -237,15 +298,11 @@ export interface MarkiiHost {
  */
 export interface MarkiiHostOptions {
     readonly spawnRun?: (options: SpawnRunRequest) => Promise<RunResult>;
-    /** The `.mkp` extraction filesystem `installPack` writes through. Required for a host that installs packs (`createNodeArchiveExtractFs()` from `@markii/host/node`); without it `installPack` is `Unsupported`. */
-    readonly archiveExtractFs?: ArchiveExtractFs;
-    /** The static HTML engine behind the `html` and `pdf` exports (`createHtmlExportEngine()` from `@markii/host/node`). Without it those formats decline, like `renderAnsi` for `ansi`. */
+    /** The static HTML engine behind the `html` and `pdf` exports (`createHtmlExportEngine()` from `@markii/host/html-engine`). Without it those formats decline, like `renderAnsi` for `ansi`. */
     readonly htmlEngine?: HtmlExportEngine;
     /** Pack discovery's file reads. Defaults to reads through the adapter's own `readFile` and `listFolder`. */
     readonly packDiscoveryIo?: PackDiscoveryIo;
     /** `@markii/ansi`'s renderer, injected because this package never depends on `@markii/ansi` (a platform renderer, never a `@markii/host` dependency). A host declaring `'ansi'` in `adapter.exports.formats` without supplying this gets `Unsupported` at export time. */
     readonly renderAnsi?: (text: string) => Promise<string>;
-    /** Composes a pack-aware render registry (webview registration, in-process evaluation, ...). Reserved for a future slice that renders through `exportNote`'s `html` path with packs; unused today, since `buildExportDocument`'s default (no `renderBody`) already produces a correct, pack-free static export. */
-    readonly buildPackRegistration?: unknown;
 }
 export declare function createMarkiiHost(adapter: HostAdapter, options?: MarkiiHostOptions): MarkiiHost;

package/dist/host/create-host.js

@@ -1,6 +1,8 @@
 import { runViaAdapter, } from './run-behavior.js';
 import { installPackDiagnosticLines, installPackFromArchive, } from './pack-install.js';
 import { loadPacksViaAdapter, packDiscoveryIoFromAdapter, } from './pack-load.js';
+import { exportBaseName } from '../export/note-export.js';
+import { exportLinkedSetViaAdapter, } from './cascade-export-behavior.js';
 import { buildComponentCatalog } from '../insert/component-catalog.js';
 import { formatPackDiagnosticLines, skippedPackFolderLine, } from '../packs/pack-diagnostics.js';
 import { readTerminalPackScripts, } from './terminal-packs.js';
@@ -95,6 +97,24 @@ export function createMarkiiHost(adapter, options = {}) {
                 ...(request.onDiagnostic !== undefined
                     ? { onDiagnostic: request.onDiagnostic }
                     : {}),
+                ...(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.embedImages !== undefined
+                    ? { embedImages: request.embedImages }
+                    : {}),
+                ...(request.hideScriptBlocks !== undefined
+                    ? { hideScriptBlocks: request.hideScriptBlocks }
+                    : {}),
             }, options.renderAnsi);
             if (outcome === undefined) {
                 adapter.diagnostics(`export declined: format "${request.format}" has no working export path on ${adapter.id} (a cancelled picker, or a missing renderer/PDF seam).`);
@@ -106,47 +126,58 @@ export function createMarkiiHost(adapter, options = {}) {
             if (outcome.kind === 'failed') {
                 return { kind: 'failed', reason: outcome.reason };
             }
-            return { kind: 'exported', path: outcome.path, bytes: outcome.bytes };
+            return {
+                kind: 'exported',
+                path: outcome.path,
+                bytes: outcome.bytes,
+                valueCount: outcome.valueCount,
+                ...(outcome.hasScripts !== undefined
+                    ? { hasScripts: outcome.hasScripts }
+                    : {}),
+                render: outcome.render,
+                images: outcome.images,
+            };
+        },
+        async exportLinkedSet(request) {
+            if (adapter.exports?.resolveLinkedSetTarget === undefined) {
+                return unsupported(adapter, 'linked-set-export', `the linked-set export is not available on ${adapter.id}.`);
+            }
+            if (options.htmlEngine === undefined) {
+                return unsupported(adapter, 'linked-set-export', 'no HTML export engine was supplied, so the linked-set export cannot render.');
+            }
+            const outcome = await exportLinkedSetViaAdapter(adapter, {
+                ...request,
+                engine: options.htmlEngine,
+                suggestedFileName: `${exportBaseName(request.rootPath)}.zip`,
+            });
+            if (outcome === undefined) {
+                adapter.diagnostics(`linked-set export declined: no archive target was chosen on ${adapter.id}.`);
+                return { kind: 'cancelled' };
+            }
+            return outcome;
         },
         async installPack(request) {
             if (!adapter.packs?.installRoot) {
                 return unsupported(adapter, 'packs', 'this host has no pack-install destination configured.');
             }
             const archivePath = request.archivePath ?? 'the selected archive';
-            const extractFs = options.archiveExtractFs;
-            if (extractFs === undefined) {
-                return unsupported(adapter, 'packs', 'this host was given no archive extraction filesystem.');
+            const removeFolder = adapter.packs.removeFolder;
+            if (removeFolder === undefined) {
+                return unsupported(adapter, 'packs', 'this host has no way to remove an installed pack folder.');
             }
             const outcome = await installPackFromArchive(adapter, {
                 archiveBytes: request.archiveBytes,
                 archivePath,
                 installRoot: adapter.packs.installRoot(),
                 exists: (path) => adapter.exists(path),
-                extractFs,
+                removeFolder: (path) => removeFolder.call(adapter.packs, path),
                 reservedNamespaces: adapter.packs.reservedNamespaces(),
             });
             catalogCache.invalidate();
             for (const line of installPackDiagnosticLines(outcome, archivePath)) {
                 adapter.diagnostics(line);
             }
-            if (outcome.kind === 'installed') {
-                return {
-                    kind: 'installed',
-                    namespace: outcome.packName,
-                    replaced: outcome.replaced,
-                };
-            }
-            if (outcome.kind === 'declined') {
-                return {
-                    kind: 'declined',
-                    step: outcome.step,
-                    namespace: outcome.packName,
-                };
-            }
-            if (outcome.kind === 'reserved') {
-                return { kind: 'reserved', namespace: outcome.packName };
-            }
-            return { kind: 'rejected', reason: outcome.reason };
+            return outcome;
         },
         async loadPacks() {
             if (!adapter.packs) {

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

@@ -30,6 +30,7 @@ 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';
+import type { ExportOutcome } from './create-host.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. */
@@ -58,7 +59,7 @@ export declare function fileNameOf(path: string): string;
  * 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;
+export declare function exportResultMessage(outcome: ExportOutcome, 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"`). */

package/dist/host/export-behavior.js

@@ -23,7 +23,7 @@ export function fileNameOf(path) {
  * a stack trace — the verbatim reason goes there instead.
  */
 export function exportResultMessage(outcome, labels) {
-    if (outcome.kind === 'failed') {
+    if (outcome.kind !== 'exported') {
         return `Markii: could not export this note. Open ${labels.diagnosticsSurface} for details.`;
     }
     const name = fileNameOf(outcome.path);

package/dist/host/labels.d.ts

@@ -1,20 +1,11 @@
 /**
- * `HostLabels`: the wording nouns every shared behavior module
- * (`./script-execution.ts`, `./refresh-interval.ts`) interpolates, and the
- * one concrete record per app this repo ships. Each app's `HostAdapter`
- * imports its record rather than inventing its own strings, which is what
- * lets one template serve every host.
+ * The shared wording templates a host's shared behaviors interpolate
+ * `HostLabels` into live beside each behavior. This module holds the one
+ * label sentence that has no per-host noun. Each app owns its own
+ * `HostLabels` record and passes it as `HostAdapter.labels`.
  *
- * Pure and dependency-free: re-exported from `../browser.ts` as well as
- * `../index.ts` so VS Code's Node-free webview bundle can read it too.
+ * Pure and dependency-free.
  */
-import type { HostLabels } from './adapter.js';
-/** The VS Code extension's labels, taken from its current wording (`apps/vscode/src/script-execution.ts`, `apps/vscode/src/extension.ts`'s output channel). */
-export declare const VSCODE_LABELS: HostLabels;
-/** The Obsidian plugin's labels, taken from its current wording (`apps/obsidian/src/script-execution.ts`, docs/integration.md's host checklist). */
-export declare const OBSIDIAN_LABELS: HostLabels;
-/** The `markii` command line tool's labels: it has no persistent preview panel, and its diagnostics surface is stderr, gated behind `--verbose` for anything short of a failure (`apps/cli/src/main.ts`). */
-export declare const CLI_LABELS: HostLabels;
 /**
  * The quiet marker a rendered note shows when its `uses:` list names packs
  * this host has not installed (docs/packs.md). One sentence for every host;

package/dist/host/labels.js

@@ -1,25 +1,11 @@
-/** The VS Code extension's labels, taken from its current wording (`apps/vscode/src/script-execution.ts`, `apps/vscode/src/extension.ts`'s output channel). */
-export const VSCODE_LABELS = {
-    appNoun: 'extension',
-    previewNoun: 'the Markii preview',
-    diagnosticsSurface: 'the Markii output channel',
-    deviceNoun: 'this device',
-    settingName: 'markii.scriptsDisabled',
-};
-/** The Obsidian plugin's labels, taken from its current wording (`apps/obsidian/src/script-execution.ts`, docs/integration.md's host checklist). */
-export const OBSIDIAN_LABELS = {
-    appNoun: 'plugin',
-    previewNoun: 'the Markii preview',
-    diagnosticsSurface: 'the Markii diagnostics',
-    deviceNoun: 'this device',
-};
-/** The `markii` command line tool's labels: it has no persistent preview panel, and its diagnostics surface is stderr, gated behind `--verbose` for anything short of a failure (`apps/cli/src/main.ts`). */
-export const CLI_LABELS = {
-    appNoun: 'command line tool',
-    previewNoun: 'the rendered note',
-    diagnosticsSurface: 'stderr',
-    deviceNoun: 'this device',
-};
+/**
+ * The shared wording templates a host's shared behaviors interpolate
+ * `HostLabels` into live beside each behavior. This module holds the one
+ * label sentence that has no per-host noun. Each app owns its own
+ * `HostLabels` record and passes it as `HostAdapter.labels`.
+ *
+ * Pure and dependency-free.
+ */
 /**
  * The quiet marker a rendered note shows when its `uses:` list names packs
  * this host has not installed (docs/packs.md). One sentence for every host;

package/dist/host/pack-archive.d.ts

@@ -1,14 +1,8 @@
 import type { PackArchiveContents, PackArchiveError } from '@markii/pack';
 /** One line describing why `openPackArchive` rejected an archive, for a host's install-diagnostics wording. Passes `kind: 'zip'`'s and `kind: 'missing-entry'`'s message through verbatim (already specific); summarizes a manifest failure plainly. */
 export declare function describeArchiveError(error: PackArchiveError): string;
-/** The filesystem write seam `writeArchiveContents` needs (`./pack-install.ts`). Deliberately narrow: extracting an archive only ever creates files under a directory it first clears, it never reads back or deletes anything else. */
-export interface ArchiveExtractFs {
-    /** Removes `absolutePath` and everything under it, or resolves quietly if it does not exist. Never rejects: a directory that fails to clear is treated the same as a fresh one, and the write that follows fails loudly on its own if the path is genuinely unusable. */
-    readonly removeDirectory: (absolutePath: string) => Promise<void>;
-    /** Creates a directory and any missing parents. May reject on a genuine I/O failure. */
-    readonly makeDirectory: (absolutePath: string) => Promise<void>;
-    readonly writeFile: (absolutePath: string, bytes: Uint8Array) => Promise<void>;
-}
+/** Writes one file and creates its missing parent folders: `HostAdapter.writeFile`. */
+export type ArchiveFileWriter = (absolutePath: string, bytes: Uint8Array) => Promise<void>;
 /**
  * Writes a validated archive's contents into `destinationDir`: `pack.json`
  * (the parsed manifest, re-serialized: `openPackArchive` keeps only the
@@ -17,7 +11,7 @@ export interface ArchiveExtractFs {
  * copy), `webview.js`, `webview.css` and `terminal.js` when the archive has them, and
  * `scripts/*` when it ships any. Does NOT clear `destinationDir` first;
  * a caller that needs a clean re-extract (a reinstall replacing an
- * existing pack) calls `fs.removeDirectory` itself before this.
+ * existing pack) removes the folder itself before this.
  *
  * PATH JAIL: `@markii/pack`'s `openPackArchive` has already rejected any
  * entry whose name escapes the archive (`../`, an absolute path) or
@@ -27,4 +21,4 @@ export interface ArchiveExtractFs {
  * `webview.css`, or a `scripts/`-relative Lua module name), never from
  * anything read back out of the zip's raw entry names.
  */
-export declare function writeArchiveContents(archive: PackArchiveContents, destinationDir: string, fs: ArchiveExtractFs): Promise<void>;
+export declare function writeArchiveContents(archive: PackArchiveContents, destinationDir: string, writeFile: ArchiveFileWriter): Promise<void>;

package/dist/host/pack-archive.js

@@ -1,18 +1,17 @@
 /**
  * `.mkp` pack archive handling, merged from `apps/vscode/src/packs/archive-packs.ts`
  * and `apps/obsidian/src/packs/archive-packs.ts`. It exports
- * `describeArchiveError`, `writeArchiveContents` and `ArchiveExtractFs`.
+ * `describeArchiveError`, `writeArchiveContents` and `ArchiveFileWriter`.
  *
  * This module bridges `@markii/pack`'s in-memory archive reader
  * (`openPackArchive`, never modified here) into the write a pack install
  * needs: extracting a validated archive's contents onto disk, under
  * whichever install root the calling host names (`HostPackSource.installRoot`).
  *
- * Environment-free (`ArchiveExtractFs` is an injected seam). The real
- * Node-backed one, `createNodeArchiveExtractFs`, lives in `../node-fs.ts`
- * and is exported from `@markii/host/node`.
+ * Environment-free: the write goes through the host adapter's `writeFile`,
+ * which creates any missing parent folder.
  */
-import { dirnamePath, joinPath } from '../path-util.js';
+import { joinPath } from '../path-util.js';
 /** One line describing why `openPackArchive` rejected an archive, for a host's install-diagnostics wording. Passes `kind: 'zip'`'s and `kind: 'missing-entry'`'s message through verbatim (already specific); summarizes a manifest failure plainly. */
 export function describeArchiveError(error) {
     if (error.kind === 'zip')
@@ -29,7 +28,7 @@ export function describeArchiveError(error) {
  * copy), `webview.js`, `webview.css` and `terminal.js` when the archive has them, and
  * `scripts/*` when it ships any. Does NOT clear `destinationDir` first;
  * a caller that needs a clean re-extract (a reinstall replacing an
- * existing pack) calls `fs.removeDirectory` itself before this.
+ * existing pack) removes the folder itself before this.
  *
  * PATH JAIL: `@markii/pack`'s `openPackArchive` has already rejected any
  * entry whose name escapes the archive (`../`, an absolute path) or
@@ -39,24 +38,22 @@ export function describeArchiveError(error) {
  * `webview.css`, or a `scripts/`-relative Lua module name), never from
  * anything read back out of the zip's raw entry names.
  */
-export async function writeArchiveContents(archive, destinationDir, fs) {
-    await fs.makeDirectory(destinationDir);
+export async function writeArchiveContents(archive, destinationDir, writeFile) {
     const encoder = new TextEncoder();
-    await fs.writeFile(joinPath(destinationDir, 'pack.json'), encoder.encode(JSON.stringify(archive.manifest, null, 2) + '\n'));
-    await fs.writeFile(joinPath(destinationDir, 'webview.js'), archive.scriptBytes);
+    await writeFile(joinPath(destinationDir, 'pack.json'), encoder.encode(JSON.stringify(archive.manifest, null, 2) + '\n'));
+    await writeFile(joinPath(destinationDir, 'webview.js'), archive.scriptBytes);
     if (archive.stylesheetBytes !== undefined) {
-        await fs.writeFile(joinPath(destinationDir, 'webview.css'), archive.stylesheetBytes);
+        await writeFile(joinPath(destinationDir, 'webview.css'), archive.stylesheetBytes);
     }
     if (archive.terminalScriptBytes !== undefined) {
-        await fs.writeFile(joinPath(destinationDir, 'terminal.js'), archive.terminalScriptBytes);
+        await writeFile(joinPath(destinationDir, 'terminal.js'), archive.terminalScriptBytes);
     }
     const moduleNames = Object.keys(archive.scriptModules);
     if (moduleNames.length > 0) {
         const scriptsDir = joinPath(destinationDir, 'scripts');
         for (const name of moduleNames) {
             const target = joinPath(scriptsDir, name);
-            await fs.makeDirectory(dirnamePath(target));
-            await fs.writeFile(target, archive.scriptModules[name]);
+            await writeFile(target, archive.scriptModules[name]);
         }
     }
 }

package/dist/host/pack-install.d.ts

@@ -1,5 +1,5 @@
-import type { ArchiveExtractFs } from './pack-archive.js';
 import type { HostAdapter, HostLabels } from './adapter.js';
+import type { InstallPackOutcome as HostInstallPackOutcome } from './create-host.js';
 /** Whether a directory already exists under the install root, injected so this module needs no real disk to test. */
 export type PackDirectoryExists = (absolutePath: string) => Promise<boolean>;
 export interface InstallPackFromArchiveOptions {
@@ -9,7 +9,8 @@ export interface InstallPackFromArchiveOptions {
     /** This host's own pack-install directory (`HostPackSource.installRoot()`). Each installed pack gets a subdirectory named by its namespace, since two packs can never share one (docs/packs.md's collision rule), which makes "is this namespace already installed" a plain directory check. */
     readonly installRoot: string;
     readonly exists: PackDirectoryExists;
-    readonly extractFs: ArchiveExtractFs;
+    /** Removes the installed folder before a replacing install (`HostPackSource.removeFolder`). Called only when the namespace is already installed. */
+    readonly removeFolder: (absolutePath: string) => Promise<void>;
     /**
      * Namespaces this install may never claim (`HostPackSource.reservedNamespaces()`).
      * Empty for a host with no reserved set (VS Code). Checked before the
@@ -17,22 +18,10 @@ export interface InstallPackFromArchiveOptions {
      */
     readonly reservedNamespaces: ReadonlySet<string>;
 }
-export type InstallPackOutcome = {
-    readonly kind: 'installed';
-    readonly packName: string;
-    readonly installedDir: string;
-    readonly replaced: boolean;
-} | {
-    readonly kind: 'declined';
-    readonly step: 'consent' | 'replace';
-    readonly packName: string;
-} | {
-    readonly kind: 'reserved';
-    readonly packName: string;
-} | {
-    readonly kind: 'rejected';
-    readonly reason: string;
-};
+/** What one install attempt produced, in the shape `createMarkiiHost(...).installPack` returns (minus `unsupported`, which only the host behavior can say). */
+export type InstallAttemptOutcome = Exclude<HostInstallPackOutcome, {
+    readonly kind: 'unsupported';
+}>;
 /**
  * Never throws: a validation failure, a declined prompt, or a write
  * failure all come back as a structured outcome. Order: validate the
@@ -47,7 +36,7 @@ export type InstallPackOutcome = {
  * a host that can only show a non-blocking surface must deny rather than
  * assume yes.
  */
-export declare function installPackFromArchive(adapter: HostAdapter, options: InstallPackFromArchiveOptions): Promise<InstallPackOutcome>;
+export declare function installPackFromArchive(adapter: HostAdapter, options: InstallPackFromArchiveOptions): Promise<InstallAttemptOutcome>;
 /**
  * The consent prompt's wording (AGENTS.md's product principles: "clean is
  * not silent," and a consent step must say plainly what it authorizes).
@@ -82,6 +71,6 @@ export declare function installReplaceConfirmMessage(packName: string): string;
  * `markii.packs` before anything loads it), so it doesn't. Defaults to
  * `false`.
  */
-export declare function installPackMessage(outcome: InstallPackOutcome, archivePath: string, labels: HostLabels, reloadsAutomatically?: boolean): string;
+export declare function installPackMessage(outcome: HostInstallPackOutcome, archivePath: string, labels: HostLabels, reloadsAutomatically?: boolean): string;
 /** The full diagnostics-surface detail for one install attempt (AGENTS.md's "clean is not silent": the other of a failure's two homes). */
-export declare function installPackDiagnosticLines(outcome: InstallPackOutcome, archivePath: string): string[];
+export declare function installPackDiagnosticLines(outcome: InstallAttemptOutcome, archivePath: string): string[];

package/dist/host/pack-install.js

@@ -39,7 +39,7 @@ function describeThrown(err) {
  * assume yes.
  */
 export async function installPackFromArchive(adapter, options) {
-    const { archiveBytes, archivePath, installRoot, exists, extractFs, reservedNamespaces, } = options;
+    const { archiveBytes, archivePath, installRoot, exists, removeFolder, reservedNamespaces, } = options;
     const opened = await openPackArchive(archiveBytes);
     if (!opened.ok) {
         return {
@@ -49,7 +49,7 @@ export async function installPackFromArchive(adapter, options) {
     }
     const packName = opened.archive.manifest.name;
     if (reservedNamespaces.has(packName)) {
-        return { kind: 'reserved', packName };
+        return { kind: 'reserved', namespace: packName };
     }
     let consented;
     try {
@@ -65,7 +65,7 @@ export async function installPackFromArchive(adapter, options) {
         return { kind: 'rejected', reason: describeThrown(err) };
     }
     if (!consented) {
-        return { kind: 'declined', step: 'consent', packName };
+        return { kind: 'declined', step: 'consent', namespace: packName };
     }
     const targetDir = joinPath(installRoot, packName);
     let alreadyInstalled;
@@ -91,13 +91,14 @@ export async function installPackFromArchive(adapter, options) {
             return { kind: 'rejected', reason: describeThrown(err) };
         }
         if (!proceed) {
-            return { kind: 'declined', step: 'replace', packName };
+            return { kind: 'declined', step: 'replace', namespace: packName };
         }
         replaced = true;
     }
     try {
-        await extractFs.removeDirectory(targetDir);
-        await writeArchiveContents(opened.archive, targetDir, extractFs);
+        if (alreadyInstalled)
+            await removeFolder(targetDir);
+        await writeArchiveContents(opened.archive, targetDir, (path, bytes) => adapter.writeFile(path, bytes));
     }
     catch (err) {
         return {
@@ -106,7 +107,12 @@ export async function installPackFromArchive(adapter, options) {
         };
     }
     await trustInstalledPack(adapter, packName, targetDir);
-    return { kind: 'installed', packName, installedDir: targetDir, replaced };
+    return {
+        kind: 'installed',
+        namespace: packName,
+        installedDir: targetDir,
+        replaced,
+    };
 }
 /**
  * The consent prompt's wording (AGENTS.md's product principles: "clean is
@@ -147,21 +153,21 @@ export function installReplaceConfirmMessage(packName) {
  * `false`.
  */
 export function installPackMessage(outcome, archivePath, labels, reloadsAutomatically = false) {
-    if (outcome.kind === 'rejected') {
+    if (outcome.kind === 'rejected' || outcome.kind === 'unsupported') {
         return `Markii: could not install a pack from "${archivePath}". Open ${labels.diagnosticsSurface} for details.`;
     }
     if (outcome.kind === 'reserved') {
-        return `Markii: "${outcome.packName}" is built in and cannot be installed. Nothing was installed.`;
+        return `Markii: "${outcome.namespace}" is built in and cannot be installed. Nothing was installed.`;
     }
     if (outcome.kind === 'declined') {
         return outcome.step === 'consent'
-            ? `Markii: install of "${outcome.packName}" cancelled. Nothing was installed.`
-            : `Markii: install of "${outcome.packName}" cancelled. The existing pack was kept.`;
+            ? `Markii: install of "${outcome.namespace}" cancelled. Nothing was installed.`
+            : `Markii: install of "${outcome.namespace}" cancelled. The existing pack was kept.`;
     }
     const reloadSuffix = reloadsAutomatically ? ' Markii packs reloaded.' : '';
     return outcome.replaced
-        ? `Markii: reinstalled pack "${outcome.packName}".${reloadSuffix}`
-        : `Markii: installed pack "${outcome.packName}".${reloadSuffix}`;
+        ? `Markii: reinstalled pack "${outcome.namespace}".${reloadSuffix}`
+        : `Markii: installed pack "${outcome.namespace}".${reloadSuffix}`;
 }
 /** The full diagnostics-surface detail for one install attempt (AGENTS.md's "clean is not silent": the other of a failure's two homes). */
 export function installPackDiagnosticLines(outcome, archivePath) {
@@ -172,15 +178,15 @@ export function installPackDiagnosticLines(outcome, archivePath) {
     }
     if (outcome.kind === 'reserved') {
         return [
-            `Install pack from file refused "${archivePath}": pack "${outcome.packName}" is a reserved namespace and cannot be installed.`,
+            `Install pack from file refused "${archivePath}": pack "${outcome.namespace}" is a reserved namespace and cannot be installed.`,
         ];
     }
     if (outcome.kind === 'declined') {
         return [
-            `Install pack from file cancelled for "${archivePath}" (pack "${outcome.packName}") at the ${outcome.step} step; nothing was installed.`,
+            `Install pack from file cancelled for "${archivePath}" (pack "${outcome.namespace}") at the ${outcome.step} step; nothing was installed.`,
         ];
     }
     return [
-        `Install pack from file installed pack "${outcome.packName}" from "${archivePath}" to ${outcome.installedDir}${outcome.replaced ? ' (replacing the previous install)' : ''}.`,
+        `Install pack from file installed pack "${outcome.namespace}" from "${archivePath}" to ${outcome.installedDir}${outcome.replaced ? ' (replacing the previous install)' : ''}.`,
     ];
 }

package/dist/host/pack-trust-behavior.js

@@ -1,5 +1,5 @@
 /**
- * The shared pack-trust behavior (docs/packs.md, docs/integration.md's host
+ * The shared pack-trust behavior (docs/packs.md, docs/hosts.md's host
  * checklist). A host that declares `HostPackSource.trust: 'device-list'`
  * loads an installed pack only when this device's trust list names its
  * namespace. A folder that sits in the install root without being named

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

@@ -74,6 +74,10 @@ export interface RunViaAdapterRequest {
 /** A run's result plus the `RunTrace` it just recorded, so a host can show its in-note marker from the same value the shared path persisted. */
 export type RunViaAdapterResult = RunOnceResult & {
     readonly trace: RunTrace;
+    /** How many of this run's values came back with the value store's `fresh` status. */
+    readonly freshCount: number;
+    /** How many of this run's values came back with the value store's `error` status. */
+    readonly errorCount: number;
 };
 /**
  * Runs one manual, auto, or scheduled pass of `request.text`'s scripts,

package/dist/host/run-behavior.js

@@ -185,5 +185,13 @@ export async function runViaAdapter(adapter, request, overrideSpawnRun) {
     // must never turn a successful (or already-reported) run into a thrown
     // error.
     await writeLastRunTrace(adapter.memento, request.documentKey, trace).then(undefined, () => { });
-    return { ...result, trace };
+    let freshCount = 0;
+    let errorCount = 0;
+    for (const value of Object.values(result.values)) {
+        if (value.status === 'fresh')
+            freshCount += 1;
+        else if (value.status === 'error')
+            errorCount += 1;
+    }
+    return { ...result, trace, freshCount, errorCount };
 }