@markii/host 0.0.1 → 0.17.0-next.2

package/dist/packs/pack-diagnostics.js

@@ -0,0 +1,105 @@
+/**
+ * Formats a host's pack-loading outcome as plain text lines for that host's
+ * own diagnostics surface (AGENTS.md's "clean is not silent": every
+ * failure needs a full diagnostic somewhere a user can find it, not just a
+ * quiet marker in the preview).
+ *
+ * This module owns the STRUCTURAL wording — one line per loaded pack, one
+ * per skipped folder, the CSS-warning lines, and the pack-registration
+ * lines (invalid registration reasons and the namespace-collision line) —
+ * which is identical across every host. It deliberately does NOT format
+ * the relative-entry note or the prebuilt-shadow note: which setting a
+ * relative entry belongs to (VS Code's `markii.packs`, this plugin's
+ * device-local pack-folder list) and what "relative" means for that host (a
+ * different workspace window vs. a different vault) is host-specific
+ * knowledge, and naming a host's own "build pack for distribution" command
+ * in the shadow note is host-specific the same way, so each host formats
+ * those lines itself and passes them in already-rendered
+ * (`relativeEntryLines`/`prebuiltShadowLines` below) — see
+ * `apps/vscode/src/packs/pack-diagnostics.ts` and
+ * `apps/obsidian/src/packs/pack-diagnostics.ts` for each host's own wording
+ * and thin wrapper around this function.
+ */
+import { packComponents, packComponentsForEngine } from '@markii/pack';
+/** The one line for a folder `discoverPacks` could not turn into a usable pack. */
+export function skippedPackFolderLine(entry) {
+    return `Skipped pack folder "${entry.folder}": ${entry.reason}`;
+}
+/** One line for each folder `discoverPacks`/a host's `loadPackContext` could not turn into a usable pack. */
+function skippedLines(context) {
+    return context.skipped.map(skippedPackFolderLine);
+}
+/** One line for each pack that loaded successfully, naming what a user would want to confirm: its name, namespace, and how many components it registered. */
+function loadedLines(context) {
+    return context.packs.map((pack) => {
+        const componentCount = context.engine === undefined
+            ? packComponents(pack.manifest).length
+            : packComponentsForEngine(pack.manifest, context.engine).length;
+        const plural = componentCount === 1 ? 'component' : 'components';
+        return `Loaded pack "${pack.manifest.name}" (namespace: ${pack.manifest.name}, ${String(componentCount)} ${plural})`;
+    });
+}
+/** The one summary line for a namespace collision among registered packs, or `[]` when there was none. */
+function collisionLines(context) {
+    const collisions = context.registrationCollisions ?? [];
+    if (collisions.length === 0)
+        return [];
+    return [
+        `Installed packs share a namespace (${collisions.join(', ')}); none of them were installed.`,
+    ];
+}
+/** One line per composed directive name two different packs both claimed, naming the pack that kept it and the pack whose component was skipped — `[]` when there was none (the ordinary case). */
+function duplicateComposedNameLines(context) {
+    const duplicates = context.duplicateComposedNames ?? [];
+    return duplicates.map((duplicate) => `Pack "${duplicate.skippedPack}"'s component composed to the directive name "${duplicate.composedName}", already claimed by pack "${duplicate.keptPack}"; the later component was skipped.`);
+}
+/** One line per pack dropped because this renderer cannot run its declared engine (batch 7 #46) — `[]` when there was none. */
+function droppedEngineLines(context) {
+    const dropped = context.droppedEngines ?? [];
+    return dropped.map((entry) => `Pack "${entry.name}" declares engine "${entry.engine}", which this renderer cannot run; it installed with zero components (every directive under its namespace falls back to the unknown-component box).`);
+}
+/**
+ * The full set of diagnostic lines for one pack-loading outcome: loaded
+ * packs first (the confirmation that the setting is working at all), then
+ * every skipped folder with its reason, then relative-entry lines, then
+ * prebuilt-shadow lines, then pack CSS lint warnings, then any
+ * invalid-registration, namespace-collision, or duplicate-composed-name
+ * lines. Empty when nothing is configured at all — the caller decides
+ * whether an empty result is worth writing anything to its own
+ * diagnostics surface.
+ */
+export function formatPackDiagnosticLines(context) {
+    return [
+        ...loadedLines(context),
+        ...skippedLines(context),
+        ...(context.relativeEntryLines ?? []),
+        ...(context.prebuiltShadowLines ?? []),
+        ...context.cssWarnings,
+        ...(context.invalidRegistrationReasons ?? []),
+        ...collisionLines(context),
+        ...duplicateComposedNameLines(context),
+        ...droppedEngineLines(context),
+    ];
+}
+/** How many configured folders failed to produce a usable pack — what a preview's quiet marker counts. */
+export function skippedPackCount(context) {
+    return context.skipped.length;
+}
+/**
+ * One informational line for a pack whose prebuilt `webview.js` shadows
+ * component sources still present in the same folder — survey finding A9:
+ * `apps/vscode/src/packs/pack-diagnostics.ts` and
+ * `apps/obsidian/src/packs/pack-diagnostics.ts` each defined this exact
+ * sentence shape, differing only in the tail clause naming how a user
+ * would rebuild the prebuilt artifact from those sources (VS Code's own
+ * Export Pack command versus, from Obsidian, VS Code's Export Pack command
+ * by name, since Obsidian has no build command of its own).
+ *
+ * Never a failure: shipping both the built artifact and its sources is a
+ * supported distribution shape. `rebuildInstruction` is the one thing that
+ * differs per host — a short clause completing "Edits to them take effect
+ * only after you delete webview.js, or ...".
+ */
+export function prebuiltShadowLine(pack, rebuildInstruction) {
+    return `Pack "${pack.name}" is using its prebuilt webview.js, so the component sources in that folder are not compiled. Edits to them take effect only after you delete webview.js, or ${rebuildInstruction}.`;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Resolves each entry in `packs` to an absolute path. `homeDir` is a plain
+ * parameter (not read via `os.homedir()` internally) so this stays testable
+ * against a fixed value instead of the real host's home directory; the real
+ * caller (each host's own `pack-context.ts`) passes `os.homedir()` itself.
+ * Omitted (or `undefined`) disables `~` expansion entirely — a `~` entry is
+ * then simply relative like any other.
+ *
+ * - A `~`/`~/...` entry is expanded against `homeDir` FIRST (`expandHome`)
+ *   — this makes an absolute path pleasant to write, which matters because
+ *   a relative entry can mean a different folder in every window/vault it
+ *   happens to be open in, so an absolute (or `~`-relative) entry is the
+ *   only spelling that means the same folder everywhere.
+ * - An entry that is (now) already absolute passes through UNCHANGED —
+ *   never re-rooted, and never rejected for pointing outside `baseDir`,
+ *   since an absolute path is the user explicitly naming a folder wherever
+ *   it is (docs/packs.md: packs are installed into the application, not
+ *   jailed the way a bundle's contents are).
+ * - A relative entry (still relative after `~` expansion) is joined
+ *   against `baseDir` and NORMALIZED (`path.normalize` via `path.join`,
+ *   which collapses `..` segments syntactically). A relative entry that
+ *   climbs out of `baseDir` via `..` is intentionally still honored, for
+ *   the same reason an absolute entry is: this setting is a user-authored
+ *   trust decision, not a content-derived path that needs jailing — unlike
+ *   a bundle's `scripts/`/`assets/` paths (`@markii/bundle`'s
+ *   `normalizeBundlePath`), which DO get jailed because they come from
+ *   potentially-hostile bundle content, not from the user directly editing
+ *   their own settings.
+ * - `baseDir === undefined` (no workspace/vault open) leaves every relative
+ *   entry UNRESOLVED (returned as-is, unjoined) rather than guessing a
+ *   base — a relative entry with nothing open cannot mean anything, so the
+ *   caller's later folder-read simply fails to find a `pack.json` there
+ *   and `discoverPacks` quietly skips it, the same cleanliness posture as
+ *   any other unreadable folder.
+ *
+ * Never throws — every input is a configuration string a user typed by
+ * hand, and a malformed one should degrade to "not found", not to a crash.
+ */
+export declare function resolvePackPaths(packs: readonly string[], baseDir: string | undefined, homeDir?: string): string[];
+/**
+ * The detection half of the relative-entry diagnostics: the ORIGINAL
+ * (unexpanded) entries in
+ * `packs` that are relative once `~` expansion is accounted for — i.e.
+ * exactly the entries `resolvePackPaths` resolves against `baseDir` rather
+ * than using as-is. A relative entry can silently mean a different folder
+ * in every window/vault it happens to be open in, so a caller surfaces
+ * these to its own diagnostics surface, in its own wording (each host
+ * names its setting and the ambiguity differently — see this module's top
+ * doc comment); `resolvePackPaths` keeps resolving them exactly as it
+ * always has: this function only ever adds a warning, never changes
+ * behavior.
+ */
+export declare function relativePackEntries(packs: readonly string[], homeDir?: string): string[];

package/dist/packs/pack-paths.js

@@ -0,0 +1,106 @@
+/**
+ * Resolves a host's pack-folder setting entries to absolute folder paths.
+ * Pure (paths in, a base directory in, absolute paths out) so it is
+ * unit-testable without a real workspace/vault.
+ *
+ * `baseDir` is deliberately a generic name: what it MEANS differs per host
+ * (VS Code resolves a relative entry against the open workspace folder,
+ * since `markii.packs` is a user-scoped setting; an Obsidian plugin
+ * resolves it against the open vault, since its pack-folder list is a
+ * device-local setting that can be opened against several vaults) but the
+ * resolution RULE is identical, so only the base directory's identity is a
+ * host concern — reading the setting itself, and naming what "relative"
+ * means in a diagnostic message, stays in each host's own app code.
+ *
+ * DECISION (per orchestrator direction, carried over from the original VS
+ * Code module this was hoisted from): a relative entry is resolved against
+ * `baseDir` as given by the caller; an absolute entry is used as-is. This
+ * matches how a user reads the setting's own description: "this pack
+ * folder, relative to my project/vault".
+ */
+import { isAbsolutePath, joinPath } from '../path-util.js';
+/**
+ * Expands a leading `~` in `entry` against `homeDir` — `~` alone, or
+ * `~/...`/`~\...` (both separators accepted regardless of host platform, so
+ * a setting written on one OS still expands sensibly if synced to
+ * another). Any other entry (including one that merely CONTAINS a `~`
+ * elsewhere, or has no `homeDir` to expand against) passes through
+ * unchanged. This is convenience, not path resolution: the result still
+ * goes through the ordinary absolute/relative handling in
+ * `resolvePackPaths` below, exactly like a path the user typed out in
+ * full.
+ */
+function expandHome(entry, homeDir) {
+    if (homeDir === undefined)
+        return entry;
+    if (entry === '~')
+        return homeDir;
+    if (entry.startsWith('~/') || entry.startsWith('~\\')) {
+        return joinPath(homeDir, entry.slice(2));
+    }
+    return entry;
+}
+/**
+ * Resolves each entry in `packs` to an absolute path. `homeDir` is a plain
+ * parameter (not read via `os.homedir()` internally) so this stays testable
+ * against a fixed value instead of the real host's home directory; the real
+ * caller (each host's own `pack-context.ts`) passes `os.homedir()` itself.
+ * Omitted (or `undefined`) disables `~` expansion entirely — a `~` entry is
+ * then simply relative like any other.
+ *
+ * - A `~`/`~/...` entry is expanded against `homeDir` FIRST (`expandHome`)
+ *   — this makes an absolute path pleasant to write, which matters because
+ *   a relative entry can mean a different folder in every window/vault it
+ *   happens to be open in, so an absolute (or `~`-relative) entry is the
+ *   only spelling that means the same folder everywhere.
+ * - An entry that is (now) already absolute passes through UNCHANGED —
+ *   never re-rooted, and never rejected for pointing outside `baseDir`,
+ *   since an absolute path is the user explicitly naming a folder wherever
+ *   it is (docs/packs.md: packs are installed into the application, not
+ *   jailed the way a bundle's contents are).
+ * - A relative entry (still relative after `~` expansion) is joined
+ *   against `baseDir` and NORMALIZED (`path.normalize` via `path.join`,
+ *   which collapses `..` segments syntactically). A relative entry that
+ *   climbs out of `baseDir` via `..` is intentionally still honored, for
+ *   the same reason an absolute entry is: this setting is a user-authored
+ *   trust decision, not a content-derived path that needs jailing — unlike
+ *   a bundle's `scripts/`/`assets/` paths (`@markii/bundle`'s
+ *   `normalizeBundlePath`), which DO get jailed because they come from
+ *   potentially-hostile bundle content, not from the user directly editing
+ *   their own settings.
+ * - `baseDir === undefined` (no workspace/vault open) leaves every relative
+ *   entry UNRESOLVED (returned as-is, unjoined) rather than guessing a
+ *   base — a relative entry with nothing open cannot mean anything, so the
+ *   caller's later folder-read simply fails to find a `pack.json` there
+ *   and `discoverPacks` quietly skips it, the same cleanliness posture as
+ *   any other unreadable folder.
+ *
+ * Never throws — every input is a configuration string a user typed by
+ * hand, and a malformed one should degrade to "not found", not to a crash.
+ */
+export function resolvePackPaths(packs, baseDir, homeDir) {
+    return packs.map((entry) => {
+        const expanded = expandHome(entry, homeDir);
+        if (isAbsolutePath(expanded))
+            return expanded;
+        if (baseDir === undefined)
+            return expanded;
+        return joinPath(baseDir, expanded);
+    });
+}
+/**
+ * The detection half of the relative-entry diagnostics: the ORIGINAL
+ * (unexpanded) entries in
+ * `packs` that are relative once `~` expansion is accounted for — i.e.
+ * exactly the entries `resolvePackPaths` resolves against `baseDir` rather
+ * than using as-is. A relative entry can silently mean a different folder
+ * in every window/vault it happens to be open in, so a caller surfaces
+ * these to its own diagnostics surface, in its own wording (each host
+ * names its setting and the ambiguity differently — see this module's top
+ * doc comment); `resolvePackPaths` keeps resolving them exactly as it
+ * always has: this function only ever adds a warning, never changes
+ * behavior.
+ */
+export function relativePackEntries(packs, homeDir) {
+    return packs.filter((entry) => !isAbsolutePath(expandHome(entry, homeDir)));
+}

package/dist/packs/pack-render-registry.d.ts

@@ -0,0 +1,83 @@
+import type { PackManifest } from '@markii/pack';
+import type { Registry, RegistryEntry } from '@markii/react';
+/**
+ * The renderer-specific half of building a pack-aware registry: the
+ * renderer's own `loadPack`, `createRegistry` and `mergeRegistries`. A
+ * React host passes `@markii/react`'s `reactPackEngine`; the host layer
+ * itself names no renderer.
+ */
+export interface PackRegistryEngine {
+    loadPack(manifest: PackManifest, componentModules: Record<string, RegistryEntry>): {
+        registry: Registry;
+        dropped?: {
+            name: string;
+            engine: string;
+        };
+    };
+    createRegistry(entries?: Record<string, RegistryEntry>): Registry;
+    mergeRegistries(...registries: Registry[]): Registry;
+}
+/** One registration a compiled pack script queued by calling `window.__markiiRegisterPack(manifestJson, componentModules)` (see `./pack-build.ts`'s top doc comment for the full registration convention). Structurally identical across every host that satisfies the convention. */
+export interface QueuedPackRegistration {
+    readonly manifestJson: unknown;
+    readonly componentModules: unknown;
+}
+/**
+ * One composed directive name two DIFFERENT packs both claimed. Under
+ * `@markii/pack`'s current underscore join (issue #19) this cannot arise
+ * from two packs' names and local names composing to the same string — the
+ * join is bijective (see `namespace.ts`'s `composeDirectiveName` doc
+ * comment) — so this is a defense-in-depth invariant, not a reachable case
+ * of ordinary pack composition. It stays because a hand-written pack
+ * registration script (or a future regression in the composition rule)
+ * could still hand `buildRenderRegistry` two registrations that carry the
+ * identical composed name; when that happens the FIRST claimant keeps the
+ * name and the later one is dropped, exactly like a malformed registration.
+ */
+export interface DuplicateComposedName {
+    readonly composedName: string;
+    /** The pack whose component kept the name. */
+    readonly keptPack: string;
+    /** The pack whose component was skipped because the name was already taken. */
+    readonly skippedPack: string;
+}
+/** What `buildRenderRegistry` reports alongside the merged registry — developer-facing diagnostics for a caller to fold into its own surface, never shown as page content. */
+export interface BuildRenderRegistryResult {
+    readonly registry: Registry;
+    /** One line per malformed registration, dropped rather than installed. */
+    readonly invalidReasons: readonly string[];
+    /** Non-empty only when two or more validated registrations shared a namespace — the WHOLE install was then rejected (docs/packs.md's install-time rejection rule) and `registry` falls back to `defaultRegistry` alone. */
+    readonly collisions: readonly string[];
+    /** One entry per composed directive name claimed by two different packs — see `DuplicateComposedName`. Always empty for registrations that went through ordinary composition; kept as an executable invariant, not dead code (see `./pack-render-registry.test.ts`'s constructed-collision test). */
+    readonly duplicateComposedNames: readonly DuplicateComposedName[];
+    /**
+     * One entry per validated, non-colliding pack whose manifest declares an
+     * engine `@markii/react`'s `loadPack` cannot run (batch 7 #46). Before
+     * this field existed, such a pack installed as an empty contribution
+     * with no record anywhere that it had even been attempted — every
+     * directive under its namespace fell through to the ordinary
+     * unknown-component fallback, indistinguishable from a directive that
+     * was never a pack component at all. Always empty for an ordinary
+     * all-react-engine install.
+     */
+    readonly droppedEngines: readonly {
+        name: string;
+        engine: string;
+    }[];
+}
+/**
+ * Builds the render registry: `defaultRegistry` merged with every
+ * successfully validated, non-colliding pack registration in `queued`.
+ * Never throws:
+ *
+ * - an individual malformed registration is dropped (reason recorded, never
+ *   shown on the page);
+ * - a namespace collision between two loaded packs (the same pack name
+ *   registered twice) rejects the WHOLE install (matching docs/packs.md's
+ *   install-time rejection rule) and this function falls back to
+ *   `defaultRegistry` alone;
+ * - a composed-directive-name collision between two DIFFERENTLY named packs
+ *   (see `DuplicateComposedName`) drops only the later claimant's
+ *   component, not the whole pack.
+ */
+export declare function buildRenderRegistry(queued: readonly QueuedPackRegistration[], defaultRegistry: Registry, engine: PackRegistryEngine): BuildRenderRegistryResult;

package/dist/packs/pack-render-registry.js

@@ -0,0 +1,182 @@
+/**
+ * Validates a batch of `QueuedPackRegistration`s and merges them into a
+ * render `Registry` on top of a base registry, using `@markii/react`'s
+ * `loadPack` per pack (namespace-collision rejection reimplemented here so
+ * this module can also guard against a same-composed-name collision
+ * between two differently named packs — see `DuplicateComposedName` and
+ * `mergePacksKeepingFirstClaim`).
+ *
+ * Every entry here crossed a boundary from a SEPARATELY EVALUATED script (a
+ * pack's compiled artifact, not code a host's own bundle compiled) — same
+ * trust as that bundle once loaded (docs/security.md: "packs are
+ * user-installed/trusted"), but still validated structurally before use,
+ * because "trusted" does not mean "guaranteed well-formed": a buggy or
+ * half-built pack script must degrade the SAME way an unsupported engine or
+ * a missing component module already does in `@markii/react`'s `loadPack`
+ * (an empty contribution, never a crash), not bring down the rest of a
+ * preview.
+ *
+ * Host-neutral by design: this module takes an already-collected array of
+ * queued registrations as a plain parameter, and returns the outcome as
+ * data (never logs or throws), so a host wires up wherever those
+ * registrations came from — VS Code reads `window.__markiiPackRegistrations`
+ * off its webview and logs the result to its output channel; an Obsidian
+ * plugin evaluates each pack's compiled script in-process
+ * (`collectPackRegistrations`) and folds the result into its own
+ * diagnostics. Reading a host-specific global and deciding where to log a
+ * diagnostic line both stay in that host's own app code.
+ */
+import { detectNamespaceCollisions, parsePackManifest } from '@markii/pack';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+/** Structurally validates one `componentModules` object: every OWN entry has a function `component` and an optional boolean `inline`. Read with `Object.hasOwn` only — the same hostile-map discipline `@markii/pack`/`@markii/react` use throughout, so a `componentModules` object with a poisoned `__proto__` can't leak an inherited value in as a registered component. */
+function isPackComponentModules(value) {
+    if (!isPlainObject(value))
+        return false;
+    for (const key of Object.keys(value)) {
+        if (!hasOwn(value, key))
+            continue;
+        const entry = value[key];
+        if (!isPlainObject(entry))
+            return false;
+        if (typeof entry.component !== 'function')
+            return false;
+        if (hasOwn(entry, 'inline') && typeof entry.inline !== 'boolean') {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * One queued entry, validated into a `PackToInstall`, or `undefined` if
+ * either half fails validation — the reason is returned rather than logged
+ * directly, so the caller can fold it into its own diagnostics the same way
+ * every other pack failure is reported.
+ *
+ * Deliberately NOT exported, including from `../browser.ts`: every caller,
+ * VS Code's webview included, reaches this through `buildRenderRegistry`,
+ * which runs it per queued entry. A host reads its own registration queue
+ * off its own global and hands over the batch; validating that batch is
+ * this module's job, and keeping the per-entry step private means there is
+ * one entry point into it rather than two.
+ */
+function toPackToInstall(entry, index) {
+    if (typeof entry.manifestJson !== 'string') {
+        return {
+            invalidReason: `pack registration #${String(index)} did not provide a manifest JSON string; ignored.`,
+        };
+    }
+    const parsed = parsePackManifest(entry.manifestJson);
+    if (!parsed.ok) {
+        return {
+            invalidReason: `pack registration #${String(index)}'s manifest is invalid (${parsed.errors.join('; ')}); ignored.`,
+        };
+    }
+    if (!isPackComponentModules(entry.componentModules)) {
+        return {
+            invalidReason: `pack "${parsed.manifest.name}"'s registered components are malformed; ignored.`,
+        };
+    }
+    const manifest = parsed.manifest;
+    return { pack: { manifest, componentModules: entry.componentModules } };
+}
+/**
+ * Loads every pack's own registry (`@markii/react`'s `loadPack`, which
+ * already gates on engine and skips an unsatisfied component) and merges
+ * them onto `base` left to right, but — unlike `@markii/react`'s ordinary
+ * `mergeRegistries` last-wins semantics — keeps the FIRST pack to claim a
+ * given composed directive name and skips any later pack that claims the
+ * same name, recording the skip as a `DuplicateComposedName`. `base`'s own
+ * entries are not part of this check: a pack's composed name overriding an
+ * unrelated `base` entry is ordinary last-wins behavior, the same as
+ * `installPacks` already gives it.
+ */
+function mergePacksKeepingFirstClaim(packs, base, engine) {
+    const merged = { ...base };
+    const owner = new Map();
+    const duplicateComposedNames = [];
+    const droppedEngines = [];
+    for (const pack of packs) {
+        const { registry: loaded, dropped } = engine.loadPack(pack.manifest, pack.componentModules);
+        if (dropped)
+            droppedEngines.push(dropped);
+        for (const composedName of Object.keys(loaded)) {
+            if (!Object.hasOwn(loaded, composedName))
+                continue;
+            const existingOwner = owner.get(composedName);
+            if (existingOwner !== undefined) {
+                duplicateComposedNames.push({
+                    composedName,
+                    keptPack: existingOwner,
+                    skippedPack: pack.manifest.name,
+                });
+                continue;
+            }
+            owner.set(composedName, pack.manifest.name);
+            merged[composedName] = loaded[composedName];
+        }
+    }
+    return {
+        registry: engine.createRegistry(merged),
+        duplicateComposedNames,
+        droppedEngines,
+    };
+}
+/**
+ * Builds the render registry: `defaultRegistry` merged with every
+ * successfully validated, non-colliding pack registration in `queued`.
+ * Never throws:
+ *
+ * - an individual malformed registration is dropped (reason recorded, never
+ *   shown on the page);
+ * - a namespace collision between two loaded packs (the same pack name
+ *   registered twice) rejects the WHOLE install (matching docs/packs.md's
+ *   install-time rejection rule) and this function falls back to
+ *   `defaultRegistry` alone;
+ * - a composed-directive-name collision between two DIFFERENTLY named packs
+ *   (see `DuplicateComposedName`) drops only the later claimant's
+ *   component, not the whole pack.
+ */
+export function buildRenderRegistry(queued, defaultRegistry, engine) {
+    const packs = [];
+    const invalidReasons = [];
+    queued.forEach((entry, index) => {
+        const { pack, invalidReason } = toPackToInstall(entry, index);
+        if (pack)
+            packs.push(pack);
+        if (invalidReason)
+            invalidReasons.push(invalidReason);
+    });
+    if (packs.length === 0) {
+        return {
+            registry: defaultRegistry,
+            invalidReasons,
+            collisions: [],
+            duplicateComposedNames: [],
+            droppedEngines: [],
+        };
+    }
+    const namespaces = packs.map((pack) => pack.manifest.name);
+    const namespaceCollisions = detectNamespaceCollisions(namespaces);
+    if (namespaceCollisions.length > 0) {
+        return {
+            registry: engine.mergeRegistries(engine.createRegistry(), defaultRegistry),
+            invalidReasons,
+            collisions: namespaceCollisions.map((collision) => collision.namespace),
+            duplicateComposedNames: [],
+            droppedEngines: [],
+        };
+    }
+    const { registry, duplicateComposedNames, droppedEngines } = mergePacksKeepingFirstClaim(packs, defaultRegistry, engine);
+    return {
+        registry,
+        invalidReasons,
+        collisions: [],
+        duplicateComposedNames,
+        droppedEngines,
+    };
+}

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

@@ -0,0 +1,20 @@
+import type { DiscoveredPack } from './discover.js';
+import type { PackModulesMap } from '../run/lua-resolver.js';
+export interface PackScriptsReader {
+    /** Lists one directory's immediate entries, or `[]` if it does not exist / cannot be read (never throws — a pack with no `scripts/` folder is the ordinary case). */
+    readDirectory(absoluteDir: string): Promise<ReadonlyArray<{
+        name: string;
+        isDirectory: boolean;
+    }>>;
+    /** Reads one file's UTF-8 text, or `undefined` if it cannot be read. */
+    readFile(absolutePath: string): Promise<string | undefined>;
+}
+/**
+ * Builds the full `PackModulesMap` for `packs`: every discovered pack's
+ * namespace mapped to its `scripts/*.lua` files, keyed by their
+ * jail-normalized relative path. A pack with no `scripts/` directory (or an
+ * unreadable one) simply contributes an empty module map — a
+ * `require "thatPack/anything"` then resolves as an ordinary "no such
+ * module", never a crash.
+ */
+export declare function loadPackModules(packs: readonly DiscoveredPack[], reader: PackScriptsReader): Promise<PackModulesMap>;

package/dist/packs/pack-scripts.js

@@ -0,0 +1,96 @@
+/**
+ * Host-side, UI-free loader that reads every pack's `scripts/*.lua` files
+ * ahead of a run, producing the `PackModulesMap` `./run/lua-resolver.ts`'s
+ * `createPackModuleResolver` looks up synchronously inside the Run worker —
+ * see that module's doc comment for why the reading happens here, on the
+ * host, rather than inside the worker.
+ *
+ * Filesystem access is injected (`PackScriptsReader`) so this module is
+ * testable with an in-memory fake; `createNodeReader` in `../node-fs.ts`
+ * (exported from `@markii/host/node`) is the real `node:fs/promises`-backed
+ * implementation a Node host's pack-loading composition wires up.
+ */
+import { joinPath } from '../path-util.js';
+import { normalizeBundlePath } from '@markii/bundle';
+/** A sane upper bound on how many `.lua` files one pack's `scripts/` tree may contribute — defense in depth against a pathological pack folder (a symlink cycle a directory walk would otherwise never terminate on, or simply an absurd number of files) turning "load the installed packs" into an unbounded scan. */
+const MAX_SCRIPT_FILES_PER_PACK = 500;
+/** Recursion depth cap for the same reason — a plain bound alongside the file-count cap, independent of it. */
+const MAX_SCRIPT_DIR_DEPTH = 16;
+/**
+ * A per-file size cap on a pack's `scripts/*.lua` (H-2, pass-3 pentest report
+ * section 10.2). Packs are user-installed, trusted folders, so this is
+ * defense in depth rather than a trust boundary — but it matches the posture
+ * `buildBundleSnapshot` already takes for bundle files: a single file's whole
+ * text is read into the host process and then structured-cloned into the
+ * Run worker's job, so an absurdly large `.lua` (accidental or hostile) would
+ * otherwise pull an unbounded amount into host memory. A file over this cap
+ * is skipped exactly like an unreadable one — `require`-ing it then resolves
+ * as an ordinary "no such module", never a crash. 1 MB is far above any real
+ * shared Lua module while still bounding a pathological one.
+ */
+const MAX_SCRIPT_FILE_BYTES = 1_000_000;
+/**
+ * Walks `pack.scriptsDir` (relative to it) collecting every `.lua` file's
+ * bundle-jail-normalized relative path -> source text. A relative path the
+ * jail rejects (should not arise from a real directory listing, but this is
+ * defense in depth, matching every other filesystem-adjacent module in this
+ * codebase) is silently skipped rather than throwing — same cleanliness
+ * posture as `./discover.ts`. An unreadable individual file is skipped the
+ * same way.
+ */
+async function collectPackModules(pack, reader) {
+    const result = Object.create(null);
+    let fileCount = 0;
+    async function walk(relativeDir, depth) {
+        if (depth > MAX_SCRIPT_DIR_DEPTH)
+            return;
+        const absoluteDir = relativeDir
+            ? joinPath(pack.scriptsDir, relativeDir)
+            : pack.scriptsDir;
+        const entries = await reader.readDirectory(absoluteDir);
+        for (const entry of entries) {
+            if (fileCount >= MAX_SCRIPT_FILES_PER_PACK)
+                return;
+            const relativePath = relativeDir
+                ? `${relativeDir}/${entry.name}`
+                : entry.name;
+            if (entry.isDirectory) {
+                await walk(relativePath, depth + 1);
+                continue;
+            }
+            if (!entry.name.endsWith('.lua'))
+                continue;
+            const normalized = normalizeBundlePath(relativePath);
+            if (!normalized.ok)
+                continue;
+            const absolutePath = joinPath(pack.scriptsDir, relativePath);
+            const source = await reader.readFile(absolutePath);
+            if (source === undefined)
+                continue;
+            // H-2: skip a file whose UTF-8 size exceeds the per-file cap, same as an
+            // unreadable one. `TextEncoder` measures the encoded bytes (what
+            // actually crosses into the worker), not the JS string's UTF-16 length.
+            if (new TextEncoder().encode(source).length > MAX_SCRIPT_FILE_BYTES)
+                continue;
+            result[normalized.path] = source;
+            fileCount += 1;
+        }
+    }
+    await walk('', 0);
+    return result;
+}
+/**
+ * Builds the full `PackModulesMap` for `packs`: every discovered pack's
+ * namespace mapped to its `scripts/*.lua` files, keyed by their
+ * jail-normalized relative path. A pack with no `scripts/` directory (or an
+ * unreadable one) simply contributes an empty module map — a
+ * `require "thatPack/anything"` then resolves as an ordinary "no such
+ * module", never a crash.
+ */
+export async function loadPackModules(packs, reader) {
+    const map = Object.create(null);
+    for (const pack of packs) {
+        map[pack.manifest.name] = await collectPackModules(pack, reader);
+    }
+    return map;
+}