@markii/host 0.0.1 → 0.17.0-next.2

package/dist/packs/pack-trust.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The DEVICE-LOCAL pack trust list: which installed-pack namespaces this
+ * device authorizes to load (docs/packs.md). Every namespace named here
+ * has its pack code evaluated at host trust, so the list authorizes code
+ * execution and must live in device-local state (the adapter's
+ * `memento`), never in anything that travels with a vault, a workspace
+ * file, or a sync service.
+ *
+ * A pack folder can sit in the install root without being trusted: it
+ * arrived through a file sync, or a user copied it there by hand. Such a
+ * folder is never loaded until its namespace is added here, exactly like
+ * a freshly installed one, and the consent prompt is asked either way.
+ * The trust list, not the presence of a folder, decides whether code
+ * runs. `../host/pack-trust-behavior.ts` enforces that for every host
+ * that declares `trust: 'device-list'`.
+ *
+ * Pure and environment-free, so the shape and its hostile-input
+ * normalization are unit-testable with no host in sight.
+ */
+/** The memento key this shape lives under. It is the key Obsidian has always stored this list under, so an existing device keeps its trust list. */
+export declare const PACK_TRUST_STORAGE_KEY = "markii:installedPacks";
+/** A sane upper bound on how many namespaces this list may hold : a real device installs a handful of packs; this only exists to bound a hostile or corrupt stored value. */
+export declare const MAX_TRUSTED_PACKS = 200;
+/** One namespace this device trusts, and the version it was installed at (the manifest's own `version` field, or `undefined` when the pack declares none). */
+export interface PackTrustEntry {
+    readonly namespace: string;
+    readonly version?: string;
+}
+export interface PackTrustList {
+    readonly entries: readonly PackTrustEntry[];
+}
+export declare const DEFAULT_PACK_TRUST_LIST: PackTrustList;
+/**
+ * Normalizes whatever `app.loadLocalStorage(PACK_TRUST_STORAGE_KEY)` handed
+ * back into a well-formed `PackTrustList` : hostile-shape-guarded the same
+ * way every other device-local shape in this plugin is, since this is also
+ * hand-editable, foreign-version-shaped data in principle. A malformed
+ * entry is dropped rather than failing the whole read; duplicates are
+ * removed by namespace, first occurrence wins; the list is bounded by
+ * `MAX_TRUSTED_PACKS`.
+ */
+export declare function normalizePackTrustList(data: unknown): PackTrustList;
+/** Whether `namespace` is trusted on this device. */
+export declare function isPackTrusted(list: PackTrustList, namespace: string): boolean;
+/**
+ * Adds (or replaces) `namespace`'s trust entry, recording `version` when
+ * given. Used both by a fresh install and by "Enable" for a pack folder
+ * that was already present on disk. Returns the same list unchanged (never
+ * a new object) when the entry is already present with the same version,
+ * so a caller can skip a write that would change nothing.
+ */
+export declare function trustPack(list: PackTrustList, namespace: string, version?: string): PackTrustList;
+/**
+ * Removes `namespace`'s trust entry. Returns the same list unchanged when
+ * it was not present, so a caller can skip a no-op write.
+ */
+export declare function untrustPack(list: PackTrustList, namespace: string): PackTrustList;

package/dist/packs/pack-trust.js

@@ -0,0 +1,111 @@
+/**
+ * The DEVICE-LOCAL pack trust list: which installed-pack namespaces this
+ * device authorizes to load (docs/packs.md). Every namespace named here
+ * has its pack code evaluated at host trust, so the list authorizes code
+ * execution and must live in device-local state (the adapter's
+ * `memento`), never in anything that travels with a vault, a workspace
+ * file, or a sync service.
+ *
+ * A pack folder can sit in the install root without being trusted: it
+ * arrived through a file sync, or a user copied it there by hand. Such a
+ * folder is never loaded until its namespace is added here, exactly like
+ * a freshly installed one, and the consent prompt is asked either way.
+ * The trust list, not the presence of a folder, decides whether code
+ * runs. `../host/pack-trust-behavior.ts` enforces that for every host
+ * that declares `trust: 'device-list'`.
+ *
+ * Pure and environment-free, so the shape and its hostile-input
+ * normalization are unit-testable with no host in sight.
+ */
+/** The memento key this shape lives under. It is the key Obsidian has always stored this list under, so an existing device keeps its trust list. */
+export const PACK_TRUST_STORAGE_KEY = 'markii:installedPacks';
+/** A sane upper bound on how many namespaces this list may hold : a real device installs a handful of packs; this only exists to bound a hostile or corrupt stored value. */
+export const MAX_TRUSTED_PACKS = 200;
+export const DEFAULT_PACK_TRUST_LIST = { entries: [] };
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Normalizes one raw entry, or `undefined` when it does not have a usable `namespace`. A non-string, empty, or whitespace-only `namespace` is dropped rather than crashing the whole read; a non-string `version` is dropped (the entry survives, just without one). */
+function normalizeEntry(raw) {
+    if (!isPlainObject(raw))
+        return undefined;
+    const namespace = raw.namespace;
+    if (typeof namespace !== 'string')
+        return undefined;
+    const trimmed = namespace.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const version = raw.version;
+    return typeof version === 'string' && version.trim().length > 0
+        ? { namespace: trimmed, version: version.trim() }
+        : { namespace: trimmed };
+}
+/**
+ * Normalizes whatever `app.loadLocalStorage(PACK_TRUST_STORAGE_KEY)` handed
+ * back into a well-formed `PackTrustList` : hostile-shape-guarded the same
+ * way every other device-local shape in this plugin is, since this is also
+ * hand-editable, foreign-version-shaped data in principle. A malformed
+ * entry is dropped rather than failing the whole read; duplicates are
+ * removed by namespace, first occurrence wins; the list is bounded by
+ * `MAX_TRUSTED_PACKS`.
+ */
+export function normalizePackTrustList(data) {
+    if (!isPlainObject(data))
+        return { ...DEFAULT_PACK_TRUST_LIST };
+    const rawEntries = data.entries;
+    if (!Array.isArray(rawEntries))
+        return { ...DEFAULT_PACK_TRUST_LIST };
+    const seen = new Set();
+    const entries = [];
+    for (const rawEntry of rawEntries) {
+        if (entries.length >= MAX_TRUSTED_PACKS)
+            break;
+        const entry = normalizeEntry(rawEntry);
+        if (!entry)
+            continue;
+        if (seen.has(entry.namespace))
+            continue;
+        seen.add(entry.namespace);
+        entries.push(entry);
+    }
+    return { entries };
+}
+/** Whether `namespace` is trusted on this device. */
+export function isPackTrusted(list, namespace) {
+    return list.entries.some((entry) => entry.namespace === namespace);
+}
+/**
+ * Adds (or replaces) `namespace`'s trust entry, recording `version` when
+ * given. Used both by a fresh install and by "Enable" for a pack folder
+ * that was already present on disk. Returns the same list unchanged (never
+ * a new object) when the entry is already present with the same version,
+ * so a caller can skip a write that would change nothing.
+ */
+export function trustPack(list, namespace, version) {
+    const trimmed = namespace.trim();
+    if (trimmed.length === 0)
+        return list;
+    const existing = list.entries.find((entry) => entry.namespace === trimmed);
+    if (existing && existing.version === version)
+        return list;
+    const withoutExisting = list.entries.filter((entry) => entry.namespace !== trimmed);
+    const next = [
+        ...withoutExisting,
+        version !== undefined
+            ? { namespace: trimmed, version }
+            : { namespace: trimmed },
+    ];
+    return { entries: next.slice(0, MAX_TRUSTED_PACKS) };
+}
+/**
+ * Removes `namespace`'s trust entry. Returns the same list unchanged when
+ * it was not present, so a caller can skip a no-op write.
+ */
+export function untrustPack(list, namespace) {
+    if (!list.entries.some((entry) => entry.namespace === namespace)) {
+        return list;
+    }
+    return {
+        entries: list.entries.filter((entry) => entry.namespace !== namespace),
+    };
+}

package/dist/packs/prebuilt.d.ts

@@ -0,0 +1,49 @@
+import type { DiscoveredPack } from './discover.js';
+export declare const PREBUILT_SCRIPT_FILENAME = "webview.js";
+export declare const PREBUILT_STYLESHEET_FILENAME = "webview.css";
+/** The terminal engine's prebuilt registration module, beside `webview.js` (docs/packs.md). Optional: a pack with no terminal views never has one. */
+export declare const PREBUILT_TERMINAL_SCRIPT_FILENAME = "terminal.js";
+/** Absolute path of a pack folder's prebuilt terminal script. No existence check. */
+export declare function prebuiltTerminalScriptPathFor(folder: string): string;
+/**
+ * The `webview.js` an export writes for a pack that has terminal views but
+ * no React ones: a registration with no components, so the archive keeps
+ * its required `webview.js` and a React host loads the pack as having
+ * nothing for it (every directive falls back).
+ */
+export declare function emptyWebviewScript(manifestJson: string): string;
+/** Absolute path of a pack folder's prebuilt registration script. No existence check. */
+export declare function prebuiltScriptPathFor(folder: string): string;
+/** Absolute path of a pack folder's prebuilt sibling stylesheet. No existence check. */
+export declare function prebuiltStylesheetPathFor(folder: string): string;
+/** Whether an absolute path exists. Injected so this module needs no real disk to test; may be sync or async. */
+export type PackPathExists = (absolutePath: string) => boolean | Promise<boolean>;
+export interface PrebuiltPackResolution {
+    /** Absolute path to the pack's prebuilt webview.js (it exists). */
+    readonly scriptPath: string;
+    /** Absolute path to the sibling webview.css, present only when that file exists. */
+    readonly stylesheetPath?: string;
+    /**
+     * Absolute paths of the manifest-declared component sources that are
+     * present on disk and therefore shadowed by the prebuilt script. Empty
+     * when the pack ships no sources (the ordinary distribution shape:
+     * `webview.js` alone, docs/packs.md's "This is the form to ship when
+     * other people will use your pack").
+     */
+    readonly shadowedComponentSources: readonly string[];
+}
+/**
+ * Resolves the prebuilt artifacts of one discovered pack, or `undefined`
+ * when the pack ships no `webview.js` at all (the from-source path, which a
+ * host compiles via `./pack-build.ts` instead).
+ *
+ * `pack.scriptPath` (already `folder/webview.js` from `./discover.ts`) is
+ * used as the script path rather than recomputed, but the stylesheet path
+ * is derived from the script path's own directory so the two always stay
+ * siblings even if a caller ever hands this a `DiscoveredPack` copy whose
+ * `folder` and `scriptPath` were computed independently.
+ *
+ * Never throws: an `exists` that throws is treated as "does not exist" for
+ * every path this function checks.
+ */
+export declare function resolvePrebuiltPack(pack: Pick<DiscoveredPack, 'folder' | 'componentPaths' | 'scriptPath'>, exists: PackPathExists): Promise<PrebuiltPackResolution | undefined>;

package/dist/packs/prebuilt.js

@@ -0,0 +1,97 @@
+/**
+ * The prebuilt-pack convention (docs/packs.md's "Two ways to run a pack:
+ * prebuilt and from source"): a pack that ships a compiled `webview.js`
+ * sibling to its `pack.json` is used as-is, no compiler runs. This module
+ * adds the second half of that convention (issue #15): an OPTIONAL sibling
+ * `webview.css`, injected/removed by a host's own pack-context composition
+ * keyed by namespace exactly like a compiled pack's own emitted stylesheet
+ * (`./pack-build.ts`'s `stylesheetPath`). A prebuilt pack with no
+ * `webview.css` simply has no stylesheet — never an error, matching
+ * `./discover.ts`'s "the file need not actually exist" posture for every
+ * other pack artifact.
+ *
+ * Also detects the SHADOWING case docs/packs.md names: "When a pack folder
+ * holds both a `webview.js` and sources, the prebuilt script wins and the
+ * sources are ignored." `resolvePrebuiltPack` reports exactly which of the
+ * manifest-declared component sources are present on disk, so a host's own
+ * diagnostics surface can name them (host-specific wording; this module
+ * only supplies the facts).
+ *
+ * Filesystem access is injected (`PackPathExists`), not imported directly,
+ * so this module is testable with plain in-memory fakes — matching every
+ * other module in this directory.
+ */
+import { dirnamePath, joinPath } from '../path-util.js';
+export const PREBUILT_SCRIPT_FILENAME = 'webview.js';
+export const PREBUILT_STYLESHEET_FILENAME = 'webview.css';
+/** The terminal engine's prebuilt registration module, beside `webview.js` (docs/packs.md). Optional: a pack with no terminal views never has one. */
+export const PREBUILT_TERMINAL_SCRIPT_FILENAME = 'terminal.js';
+/** Absolute path of a pack folder's prebuilt terminal script. No existence check. */
+export function prebuiltTerminalScriptPathFor(folder) {
+    return joinPath(folder, PREBUILT_TERMINAL_SCRIPT_FILENAME);
+}
+/**
+ * The `webview.js` an export writes for a pack that has terminal views but
+ * no React ones: a registration with no components, so the archive keeps
+ * its required `webview.js` and a React host loads the pack as having
+ * nothing for it (every directive falls back).
+ */
+export function emptyWebviewScript(manifestJson) {
+    return [
+        "if (typeof window !== 'undefined' && typeof window.__markiiRegisterPack === 'function') {",
+        `  window.__markiiRegisterPack(${JSON.stringify(manifestJson)}, {});`,
+        '}',
+        '',
+    ].join('\n');
+}
+/** Absolute path of a pack folder's prebuilt registration script. No existence check. */
+export function prebuiltScriptPathFor(folder) {
+    return joinPath(folder, PREBUILT_SCRIPT_FILENAME);
+}
+/** Absolute path of a pack folder's prebuilt sibling stylesheet. No existence check. */
+export function prebuiltStylesheetPathFor(folder) {
+    return joinPath(folder, PREBUILT_STYLESHEET_FILENAME);
+}
+/** Calls `exists`, treating a thrown error the same as "does not exist" — an unreadable path is not proof a file is absent, but this module's contract (like every other filesystem-adjacent module in this directory) is to degrade quietly rather than surface a raw I/O error here. */
+async function existsQuietly(exists, absolutePath) {
+    try {
+        return await exists(absolutePath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves the prebuilt artifacts of one discovered pack, or `undefined`
+ * when the pack ships no `webview.js` at all (the from-source path, which a
+ * host compiles via `./pack-build.ts` instead).
+ *
+ * `pack.scriptPath` (already `folder/webview.js` from `./discover.ts`) is
+ * used as the script path rather than recomputed, but the stylesheet path
+ * is derived from the script path's own directory so the two always stay
+ * siblings even if a caller ever hands this a `DiscoveredPack` copy whose
+ * `folder` and `scriptPath` were computed independently.
+ *
+ * Never throws: an `exists` that throws is treated as "does not exist" for
+ * every path this function checks.
+ */
+export async function resolvePrebuiltPack(pack, exists) {
+    const scriptExists = await existsQuietly(exists, pack.scriptPath);
+    if (!scriptExists)
+        return undefined;
+    const stylesheetPath = joinPath(dirnamePath(pack.scriptPath), PREBUILT_STYLESHEET_FILENAME);
+    const stylesheetExists = await existsQuietly(exists, stylesheetPath);
+    const shadowedComponentSources = [];
+    for (const sourcePath of Object.values(pack.componentPaths)) {
+        if (sourcePath === undefined)
+            continue;
+        if (await existsQuietly(exists, sourcePath)) {
+            shadowedComponentSources.push(sourcePath);
+        }
+    }
+    return {
+        scriptPath: pack.scriptPath,
+        ...(stylesheetExists ? { stylesheetPath } : {}),
+        shadowedComponentSources,
+    };
+}

package/dist/path-util.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Small, environment-free path helpers for the paths the host layer hands to
+ * a `HostAdapter` (`readFile`, `writeFile`, `listFolder`). They are adapter
+ * paths, not OS paths: this layer never touches a file system itself, so it
+ * must not import `node:path`.
+ *
+ * They stay correct for a Windows host, where the VS Code adapter does hand
+ * over `C:\Users\ana\packs` style strings (from `os.homedir()`, a
+ * `globalStorageUri.fsPath`, or a hand-written setting). The separator is
+ * taken from the base path: a base that uses backslashes and no forward
+ * slashes is a Windows path, joined and split with backslashes (forward
+ * slashes inside later segments are accepted as separators too, as
+ * `path.win32` does). Any other base is posix.
+ */
+/** True for a rooted path: `/x`, `\x`, `\\server\share`, or `C:\x` / `C:/x`. */
+export declare function isAbsolutePath(path: string): boolean;
+/**
+ * Joins `base` and `parts` with the separator `base` uses, collapsing `.`,
+ * `..` and repeated separators the way `path.join` does. An empty result is
+ * `.`.
+ */
+export declare function joinPath(base: string, ...parts: string[]): string;
+/** The parent folder of `path`, `path.dirname`-style (a root's parent is itself). */
+export declare function dirnamePath(path: string): string;

package/dist/path-util.js

@@ -0,0 +1,82 @@
+/**
+ * Small, environment-free path helpers for the paths the host layer hands to
+ * a `HostAdapter` (`readFile`, `writeFile`, `listFolder`). They are adapter
+ * paths, not OS paths: this layer never touches a file system itself, so it
+ * must not import `node:path`.
+ *
+ * They stay correct for a Windows host, where the VS Code adapter does hand
+ * over `C:\Users\ana\packs` style strings (from `os.homedir()`, a
+ * `globalStorageUri.fsPath`, or a hand-written setting). The separator is
+ * taken from the base path: a base that uses backslashes and no forward
+ * slashes is a Windows path, joined and split with backslashes (forward
+ * slashes inside later segments are accepted as separators too, as
+ * `path.win32` does). Any other base is posix.
+ */
+const DRIVE_PREFIX = /^[A-Za-z]:/;
+function separatorOf(path) {
+    return path.includes('\\') && !path.includes('/') ? '\\' : '/';
+}
+/** True for a rooted path: `/x`, `\x`, `\\server\share`, or `C:\x` / `C:/x`. */
+export function isAbsolutePath(path) {
+    return (path.startsWith('/') ||
+        path.startsWith('\\') ||
+        /^[A-Za-z]:[\\/]/.test(path));
+}
+function parse(path, sep) {
+    const splitter = sep === '\\' ? /[\\/]+/ : /\/+/;
+    let root = '';
+    let rest = path;
+    if (sep === '\\') {
+        const drive = DRIVE_PREFIX.exec(rest);
+        if (drive) {
+            root = drive[0];
+            rest = rest.slice(2);
+        }
+        if (/^[\\/]{2}[^\\/]/.test(path) && root === '') {
+            root = '\\\\';
+            rest = rest.replace(/^[\\/]+/, '');
+        }
+        else if (/^[\\/]/.test(rest)) {
+            root += '\\';
+        }
+    }
+    else if (rest.startsWith('/')) {
+        root = '/';
+    }
+    const segments = [];
+    for (const part of rest.split(splitter)) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            const last = segments[segments.length - 1];
+            if (last !== undefined && last !== '..')
+                segments.pop();
+            else if (root === '')
+                segments.push('..');
+            continue;
+        }
+        segments.push(part);
+    }
+    return { root, segments };
+}
+function format({ root, segments }, sep) {
+    const body = segments.join(sep);
+    if (body === '')
+        return root === '' ? '.' : root;
+    return root + body;
+}
+/**
+ * Joins `base` and `parts` with the separator `base` uses, collapsing `.`,
+ * `..` and repeated separators the way `path.join` does. An empty result is
+ * `.`.
+ */
+export function joinPath(base, ...parts) {
+    const sep = separatorOf(base);
+    return format(parse([base, ...parts].filter((p) => p !== '').join(sep), sep), sep);
+}
+/** The parent folder of `path`, `path.dirname`-style (a root's parent is itself). */
+export function dirnamePath(path) {
+    const sep = separatorOf(path);
+    const parsed = parse(path, sep);
+    return format({ root: parsed.root, segments: parsed.segments.slice(0, -1) }, sep);
+}

package/dist/run/browser-isolate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A `RunIsolate` backed by a Web Worker, for hosts whose runtime cannot
+ * create a worker thread (see `./isolate.ts`).
+ *
+ * Two details are load-bearing.
+ *
+ * The worker is started from a BLOB URL built from the bundle's own bytes,
+ * read off disk by the host. Loading a worker from a `file://` URL is
+ * refused by Chromium, and an Electron app's custom protocols are not
+ * something this package can assume, so reading the file the host already
+ * has and handing it over as a blob sidesteps the question entirely.
+ * `glue.wasm` travels the same way, because wasmoon fetches it by URL and
+ * there is no `__dirname` inside a worker to find it beside the bundle.
+ *
+ * Network is served by the HOST, not the worker: `serveNetRequests` wires
+ * every `markii:net-request` to the caller's own `NetProvider`, which is
+ * the same pinned one a worker-thread isolate runs. The isolate has no
+ * network stack of its own, so the allowlist cannot be bypassed from
+ * inside it.
+ *
+ * What this CANNOT do, stated plainly because it is a real difference: a
+ * Web Worker takes no `maxOldGenerationSizeMb`, so `options`'s heap cap is
+ * accepted and ignored. Lua's own memory limit and the external watchdog
+ * still apply; a runaway JavaScript-side allocation inside the isolate is
+ * bounded only by the browser engine, and exhausting it can take the host
+ * renderer down. docs/security.md records this.
+ */
+import type { NetProvider } from '@markii/lua';
+import type { RunIsolate, SpawnIsolateOptions } from './isolate.js';
+/** The Web Worker surface this uses, declared structurally so the package needs no DOM lib. */
+export interface WorkerLike {
+    postMessage: (message: unknown) => void;
+    terminate: () => void;
+    addEventListener: (type: 'message' | 'error' | 'messageerror', listener: (event: unknown) => void) => void;
+}
+export interface BrowserIsolateOptions {
+    /** Creates the worker. Injected so a test never needs a real one, and so a host can decide how it mints the URL. */
+    createWorker: (entryPath: string) => WorkerLike;
+    /** The host's own pinned provider. Every `net.*` call the script makes is answered by this, in the host, never in the isolate. */
+    netProvider: (netAllowlist: string[], maxFetchBytes: number, netPolicy: unknown) => NetProvider;
+    /** Where the worker should fetch wasmoon's `glue.wasm`; sent along with the job. */
+    wasmUri?: string;
+}
+/** Builds the spawner a host passes as `SpawnRunOptions.spawnIsolate`. */
+export declare function createBrowserIsolate(options: BrowserIsolateOptions): (spawn: SpawnIsolateOptions) => RunIsolate;

package/dist/run/browser-isolate.js

@@ -0,0 +1,81 @@
+import { isNetBridgeRequest, serveNetRequest, } from './net-bridge.js';
+/** Pulls the fields the host needs to build the same provider the worker would have built for itself. */
+function netArgsFrom(job) {
+    const j = (job ?? {});
+    return {
+        allowlist: Array.isArray(j.netAllowlist)
+            ? j.netAllowlist.filter((h) => typeof h === 'string')
+            : [],
+        maxFetchBytes: typeof j.limits?.maxFetchBytes === 'number'
+            ? j.limits.maxFetchBytes
+            : 2 * 1024 * 1024,
+        // Fail closed, exactly as the worker does with an absent policy.
+        policy: j.netPolicy ?? { allowRestrictedAddresses: false },
+    };
+}
+/** Builds the spawner a host passes as `SpawnRunOptions.spawnIsolate`. */
+export function createBrowserIsolate(options) {
+    return (spawn) => {
+        const worker = options.createWorker(spawn.entryPath);
+        let provider;
+        let alive = true;
+        const messageListeners = [];
+        const errorListeners = [];
+        worker.addEventListener('message', (event) => {
+            const data = event?.data;
+            if (isNetBridgeRequest(data)) {
+                if (!provider)
+                    return;
+                void serveNetRequest(data, provider, (reply) => {
+                    // A reply posted to a worker that is already gone would throw and
+                    // take out this handler; the run is over either way.
+                    if (alive)
+                        worker.postMessage(reply);
+                });
+                return;
+            }
+            for (const listener of messageListeners)
+                listener(data);
+        });
+        worker.addEventListener('error', (event) => {
+            const message = event?.message ?? 'worker error';
+            for (const listener of errorListeners) {
+                listener(new Error(String(message)));
+            }
+        });
+        // A message that could not be deserialized is a failed run, not silence.
+        worker.addEventListener('messageerror', () => {
+            for (const listener of errorListeners) {
+                listener(new Error('worker sent an undeserializable message'));
+            }
+        });
+        return {
+            send: (job) => {
+                const { allowlist, maxFetchBytes, policy } = netArgsFrom(job);
+                provider = options.netProvider(allowlist, maxFetchBytes, policy);
+                worker.postMessage({
+                    ...job,
+                    ...(options.wasmUri !== undefined
+                        ? { wasmUri: options.wasmUri }
+                        : {}),
+                });
+            },
+            kill: () => {
+                if (!alive)
+                    return;
+                alive = false;
+                worker.terminate();
+            },
+            onMessage: (listener) => {
+                messageListeners.push(listener);
+            },
+            onError: (listener) => {
+                errorListeners.push(listener);
+            },
+            // A Web Worker has no exit event: `terminate()` is immediate and
+            // silent. `spawnRun`'s watchdog path settles on its own timer rather
+            // than waiting for one, so there is nothing to report here.
+            onExit: () => { },
+        };
+    };
+}

package/dist/run/bundle-document.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a bundle's note lives and what a bundle is called on disk. Every
+ * host that opens a `.mkz` (the VS Code preview, the CLI) asks these
+ * questions, so the answers live here once.
+ */
+import type { BundleManifest } from '@markii/bundle';
+/** The conventional document path inside a bundle when the manifest does not name one (docs/bundles.md). */
+export declare const DEFAULT_BUNDLE_DOCUMENT_PATH = "note.mk.md";
+/** The current bundle extension; new bundles are always written with this one. */
+export declare const BUNDLE_EXTENSION = ".mkz";
+/** The legacy bundle extension, still recognized. */
+export declare const LEGACY_BUNDLE_EXTENSION = ".mkbundle";
+/**
+ * True when `name` ends with `.mkz` or the legacy `.mkbundle`
+ * (case-insensitively) AND has a non-empty base name before the extension.
+ */
+export declare function isBundleName(name: string): boolean;
+/**
+ * The bundle-relative path of the document to open: the manifest's own
+ * `document` field when it names one, normalized through the same path jail
+ * every other bundle path goes through so a manifest cannot point outside
+ * the bundle; otherwise the conventional `note.mk.md`.
+ *
+ * Returns `undefined` when a `document` field is present but not a usable
+ * bundle-relative path (wrong type, or rejected by `normalizeBundlePath`,
+ * including any path with a `..` segment). That is a manifest authoring
+ * error, not something to ignore silently.
+ */
+export declare function resolveBundleDocumentPath(manifest: BundleManifest): string | undefined;

package/dist/run/bundle-document.js

@@ -0,0 +1,40 @@
+import { normalizeBundlePath } from '@markii/bundle';
+/** The conventional document path inside a bundle when the manifest does not name one (docs/bundles.md). */
+export const DEFAULT_BUNDLE_DOCUMENT_PATH = 'note.mk.md';
+/** The current bundle extension; new bundles are always written with this one. */
+export const BUNDLE_EXTENSION = '.mkz';
+/** The legacy bundle extension, still recognized. */
+export const LEGACY_BUNDLE_EXTENSION = '.mkbundle';
+/**
+ * True when `name` ends with `.mkz` or the legacy `.mkbundle`
+ * (case-insensitively) AND has a non-empty base name before the extension.
+ */
+export function isBundleName(name) {
+    const lower = name.toLowerCase();
+    for (const extension of [BUNDLE_EXTENSION, LEGACY_BUNDLE_EXTENSION]) {
+        if (lower.endsWith(extension) && lower.length > extension.length) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The bundle-relative path of the document to open: the manifest's own
+ * `document` field when it names one, normalized through the same path jail
+ * every other bundle path goes through so a manifest cannot point outside
+ * the bundle; otherwise the conventional `note.mk.md`.
+ *
+ * Returns `undefined` when a `document` field is present but not a usable
+ * bundle-relative path (wrong type, or rejected by `normalizeBundlePath`,
+ * including any path with a `..` segment). That is a manifest authoring
+ * error, not something to ignore silently.
+ */
+export function resolveBundleDocumentPath(manifest) {
+    const raw = manifest.document;
+    if (raw === undefined)
+        return DEFAULT_BUNDLE_DOCUMENT_PATH;
+    if (typeof raw !== 'string')
+        return undefined;
+    const normalized = normalizeBundlePath(raw);
+    return normalized.ok ? normalized.path : undefined;
+}