@markii/host 0.0.1 → 0.17.0-next.3

package/dist/node.d.ts

@@ -0,0 +1,6 @@
+export type { SpawnRunOptions } from './run/run-host.js';
+export type { NodeHostIsolateOptions } from './run/node-isolate.js';
+export { createNodeHostIsolate, workerThreadIsolate, } from './run/node-isolate.js';
+export { createNetProvider } from './run/net-provider.js';
+export { createNodeArchiveExtractFs, createNodeDirectoryLister, createNodeFileReader, createNodePackDiscoveryIo, createNodeReader as createNodePackScriptsReader, } from './node-fs.js';
+export { createHtmlExportEngine } from './html-engine.js';

package/dist/node.js

@@ -0,0 +1,13 @@
+// @markii/host/node: the half of this package that needs Node, or that
+// carries a heavy engine dependency the main entry must not.
+//
+// The main entry (`./index.ts`) is environment-neutral. This entry adds:
+// - the worker_threads isolate and the pinned network provider (`node:*`);
+// - the Node-backed file-system seams the neutral code takes by injection;
+// - the `@markii/html`-backed static export engine;
+//
+// A Node host imports from both entries. No browser bundle imports this one.
+export { createNodeHostIsolate, workerThreadIsolate, } from './run/node-isolate.js';
+export { createNetProvider } from './run/net-provider.js';
+export { createNodeArchiveExtractFs, createNodeDirectoryLister, createNodeFileReader, createNodePackDiscoveryIo, createNodeReader as createNodePackScriptsReader, } from './node-fs.js';
+export { createHtmlExportEngine } from './html-engine.js';

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/packs/discover.d.ts

@@ -0,0 +1,119 @@
+import type { PackManifest } from '@markii/pack';
+import type { UnavailableComponent } from '@markii/stdlib';
+/**
+ * What a valid pack that declares nothing for this host's engine carries on
+ * its skipped entry: its namespace, and every component it declares with
+ * the engines each one does ship a view for, so a note that uses one can say
+ * "no view here" rather than "unknown component".
+ */
+export interface EngineUnsupportedPack {
+    readonly packName: string;
+    readonly components: readonly UnavailableComponent[];
+}
+/**
+ * Every component a pack declares, as `{ directive, pack, engines }` with
+ * the engine ids sorted. The shape a host hands a renderer's
+ * `unavailableComponents` option after filtering.
+ */
+export declare function declaredPackComponents(manifest: Pick<PackManifest, 'name' | 'components' | 'engine'>): UnavailableComponent[];
+/** The components, from `declared`, that ship no view for `engine`. */
+export declare function componentsWithoutEngineView(declared: readonly UnavailableComponent[], engine: string): UnavailableComponent[];
+/** Reads a file's UTF-8 text, or resolves `undefined` if it does not exist / cannot be read. Never rejects for an ordinary "not found" — injected so this module needs no real filesystem to test. */
+export type PackFileReader = (absolutePath: string) => Promise<string | undefined>;
+/** Lists one directory's immediate entries, or `[]` if it does not exist / cannot be read / is not a directory. Never rejects — injected (like `PackFileReader`) so the one-level parent-folder scan below is testable without real disk. */
+export type PackDirectoryLister = (absoluteDir: string) => Promise<ReadonlyArray<{
+    name: string;
+    isDirectory: boolean;
+}>>;
+/** One successfully discovered, validated pack. */
+export interface DiscoveredPack {
+    /** The configured folder this pack was discovered in (absolute path, as given). */
+    readonly folder: string;
+    readonly manifest: PackManifest;
+    /** Local component name -> absolute path to its declared source file (`manifest.components[name]`, resolved against `folder`). Informational: what a host consumes them for (bundling, `import()`, or locating the pack's prebuilt registration script) is that host's own concern. */
+    readonly componentPaths: Readonly<Record<string, string>>;
+    /** Engine id -> (local component name -> absolute source path), for every engine any component declares a source for. `componentPaths` is the `react` slice of this. A terminal build (`ansi`) reads its slice here. */
+    readonly componentPathsByEngine?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** Absolute path to this pack's `scripts/` directory (docs/packs.md: shared Lua modules travel here). The directory need not actually exist — a pack with no shared Lua simply has nothing under it. */
+    readonly scriptsDir: string;
+    /**
+     * Absolute path to this pack's prebuilt registration script (`webview.js`,
+     * sibling to `pack.json`) — a HOST-SPECIFIC CONVENTION layered on top of
+     * the neutral pack contract (`@markii/pack`'s `PackManifest.components`
+     * only names pack-relative SOURCE paths for a bundler, per
+     * docs/packs.md; it says nothing about a prebuilt browser artifact).
+     * Named `scriptPath`, not `webviewScriptPath`: this field is read by
+     * every host that loads a pack's compiled registration script, not only
+     * a host with an actual webview (e.g. an Obsidian plugin evaluates it
+     * in-process — see that host's `pack-runtime.ts`), and this package has
+     * no webview of its own. The on-disk filename convention (`webview.js`)
+     * is unchanged — a script authored for one host still works for another,
+     * since the compiled-artifact contract itself
+     * (`window.__markiiRegisterPack`/lazy `window.__markiiReact`) is
+     * host-neutral (see `./pack-build.ts`'s top doc comment). The file need
+     * not actually exist — a pack with no such script simply never
+     * contributes anything to a host's registry, and every directive under
+     * its namespace falls through to the standard unknown-component
+     * fallback (the same engine-gating posture `@markii/react`'s `loadPack`
+     * already takes for an unsupported `engine`).
+     */
+    readonly scriptPath: string;
+    /**
+     * Absolute path to this pack's emitted stylesheet, when one exists — a
+     * SIBLING of `scriptPath`'s compiled output (`./pack-build.ts`, same
+     * cache directory, same content-hash base name, `.css` in place of
+     * `.js`). `undefined` here always: discovery itself never scans for one,
+     * only a host's own pack-context composition knows whether a build
+     * actually produced a stylesheet — it overrides this field on the
+     * `DiscoveredPack` copy it uses once `buildPackRegistrationScript`'s
+     * outcome carries a `stylesheetPath`. A pack that ships its own prebuilt
+     * `webview.js` (no compile step at all) has no established
+     * sibling-stylesheet convention and never gets one here either.
+     */
+    readonly stylesheetPath?: string;
+}
+/** One folder that did not produce a usable pack, and why — developer-facing only, never shown as page content. */
+export interface SkippedPackFolder {
+    readonly folder: string;
+    readonly reason: string;
+    /** Set when the pack is valid but declares nothing for this host's renderer engine (an expected state, not a failure). `packName` is its namespace. */
+    readonly engineUnsupported?: EngineUnsupportedPack;
+}
+export interface DiscoverPacksResult {
+    /** Every pack that validated AND whose namespace does not collide with another discovered pack. Empty when every configured folder was invalid or every valid pack collided. */
+    readonly packs: readonly DiscoveredPack[];
+    /** Namespaces that appeared more than once across the configured folders (docs/packs.md: "Installing two packs with the same namespace is rejected at install time") — every pack sharing a colliding namespace is excluded from `packs`, not just the second one, so install stays all-or-nothing per namespace. */
+    readonly collisions: readonly string[];
+    /** Folders that produced no pack, with a short reason each (missing/unreadable `pack.json`, malformed JSON, failed manifest validation). */
+    readonly skipped: readonly SkippedPackFolder[];
+}
+/**
+ * Discovers and validates a pack in each of `folders`, in order, then
+ * removes (and reports via `collisions`) every pack whose namespace repeats
+ * across the set. Duplicate folder entries in `folders` collapse to one
+ * discovery attempt each (`Set`), so a repeated setting entry can never
+ * itself manufacture a spurious collision.
+ *
+ * `supportedEngine`, when given, additionally skips (rather than
+ * discovers) any pack whose manifest names a different `engine` — see
+ * `checkEngine`. Omitted (the default), a pack's engine is not checked
+ * here at all, matching this function's behavior before this parameter
+ * existed; a caller that only lists packs for a purpose engine-agnostic
+ * (e.g. `@markii/pack`'s own tooling) is unaffected.
+ *
+ * ONE-LEVEL PARENT-FOLDER SCAN: when a configured folder has no `pack.json`
+ * of its own (not "has one that fails validation" — see `ManifestAttempt`'s
+ * doc comment), its immediate subfolders are probed the same way, and each
+ * one that DOES have a valid `pack.json` counts as its own discovered pack
+ * (`folder` set to the child path). This lets a user configure one parent
+ * (`packs`) that holds several pack folders (`packs/pack1`, `packs/pack2`)
+ * instead of listing each one in the host's setting. Exactly one level
+ * deep, never recursive: a grandchild's `pack.json` is never found this
+ * way. A parent with neither its own manifest nor any child manifest is
+ * skipped exactly as before ("no readable pack.json"), and a child that
+ * DOES have a `pack.json` but fails validation is skipped individually, by
+ * its own (child) folder path.
+ */
+export declare function discoverPacks(folders: readonly string[], readFile: PackFileReader, listDirectory: PackDirectoryLister, supportedEngine?: string): Promise<DiscoverPacksResult>;
+/** The discovered packs' namespaces — what `resolveUses` (`@markii/pack`) checks a note's `uses:` declaration against. */
+export declare function installedNamespaces(packs: readonly DiscoveredPack[]): string[];

package/dist/packs/discover.js

@@ -0,0 +1,266 @@
+/**
+ * Node-side, host-UI-free discovery of installed component packs
+ * (docs/packs.md, GitHub issue #3 slice 5). Given the folders named by a
+ * host's own pack-folder setting (VS Code's `markii.packs`, this plugin's
+ * device-local pack-folder list, or any future host's equivalent), reads
+ * each folder's `pack.json`, validates it with `@markii/pack`'s
+ * `parsePackManifest`, and returns a model of what was found: the manifest
+ * plus absolute, host-resolved paths to the pack-relative locations a
+ * later step needs (each component's declared source, and the pack's
+ * `scripts/` directory for shared Lua modules).
+ *
+ * Lives in `@markii/host` (not any one app) because it is pure logic over
+ * paths, manifests, and strings — no `vscode`, no `obsidian`, no React, and
+ * no knowledge of which host is calling it. `apps/vscode/src/packs/`'s
+ * `apps/obsidian/src/packs/` copies of this file (pre-dating this hoist)
+ * differed only in the field names below (`scriptPath`/`stylesheetPath` —
+ * see those fields' own doc comments for why the neutral names won).
+ *
+ * Filesystem access is injected (`readFile`) rather than imported directly,
+ * so this whole module is testable with plain in-memory fakes.
+ *
+ * Cleanliness (AGENTS.md): a folder with no `pack.json`, malformed JSON, or
+ * a manifest that fails validation is QUIETLY skipped — never a thrown
+ * error or a dump in the UI. A caller that wants to surface *why* a pack
+ * failed to load can read `DiscoverPacksResult.skipped`, which is optional,
+ * developer-facing detail (a host's own diagnostics surface), never
+ * something shown as page content.
+ */
+import { joinPath } from '../path-util.js';
+import { parsePackManifest } from '@markii/pack';
+import { composeDirectiveName, detectNamespaceCollisions, packComponents, packComponentsForEngine, packDeclaredEngines, packSupportsEngine, } from '@markii/pack';
+/**
+ * Every component a pack declares, as `{ directive, pack, engines }` with
+ * the engine ids sorted. The shape a host hands a renderer's
+ * `unavailableComponents` option after filtering.
+ */
+export function declaredPackComponents(manifest) {
+    const declared = [];
+    for (const listing of packComponents(manifest)) {
+        const composed = composeDirectiveName(manifest.name, listing.localName);
+        if (!composed.ok)
+            continue;
+        declared.push({
+            directive: composed.name,
+            pack: manifest.name,
+            engines: Object.keys(listing.sources).sort(),
+        });
+    }
+    return declared;
+}
+/** The components, from `declared`, that ship no view for `engine`. */
+export function componentsWithoutEngineView(declared, engine) {
+    return declared.filter((component) => !component.engines.includes(engine));
+}
+/** A sane upper bound on how many immediate children of one configured folder the one-level parent-folder scan (`discoverPacks`) will probe for a `pack.json` — defense in depth against a pathological folder (thousands of entries, a symlink farm) turning "load the installed packs" into an unbounded scan. Matches the spirit of `./pack-scripts.ts`'s `MAX_SCRIPT_FILES_PER_PACK`. */
+const MAX_CHILD_FOLDERS_PER_PARENT = 200;
+/**
+ * The engine whose source paths fill `DiscoveredPack.componentPaths`. A
+ * data-field name from the pack contract, not a renderer dependency.
+ */
+const COMPONENT_PATHS_ENGINE = 'react';
+/** `folder`/`pack.json`, joined with the host path separator. */
+function manifestPathFor(folder) {
+    return joinPath(folder, 'pack.json');
+}
+async function tryLoadPackAt(folder, readFile) {
+    const manifestPath = manifestPathFor(folder);
+    let text;
+    try {
+        text = await readFile(manifestPath);
+    }
+    catch {
+        text = undefined;
+    }
+    if (text === undefined) {
+        return { kind: 'missing' };
+    }
+    const result = parsePackManifest(text);
+    if (!result.ok) {
+        return {
+            kind: 'invalid',
+            reason: `invalid pack.json (${result.errors.join('; ')})`,
+        };
+    }
+    // Read the manifest's components map only through @markii/pack's
+    // packComponents() — the one accessor that normalizes both the string
+    // shorthand and the object form (source/description/kind), so this
+    // module never re-implements that walk or its Object.hasOwn guarding.
+    const componentPaths = {};
+    for (const listing of packComponentsForEngine(result.manifest, COMPONENT_PATHS_ENGINE)) {
+        componentPaths[listing.localName] = joinPath(folder, listing.source);
+    }
+    const componentPathsByEngine = {};
+    for (const listing of packComponents(result.manifest)) {
+        for (const [engine, source] of Object.entries(listing.sources)) {
+            const slice = (componentPathsByEngine[engine] ??= {});
+            slice[listing.localName] = joinPath(folder, source);
+        }
+    }
+    return {
+        kind: 'found',
+        pack: {
+            folder,
+            manifest: result.manifest,
+            componentPaths,
+            componentPathsByEngine,
+            scriptsDir: joinPath(folder, 'scripts'),
+            scriptPath: joinPath(folder, 'webview.js'),
+        },
+    };
+}
+/**
+ * Discovers and validates a pack in each of `folders`, in order, then
+ * removes (and reports via `collisions`) every pack whose namespace repeats
+ * across the set. Duplicate folder entries in `folders` collapse to one
+ * discovery attempt each (`Set`), so a repeated setting entry can never
+ * itself manufacture a spurious collision.
+ *
+ * ONE-LEVEL PARENT-FOLDER SCAN: when a configured folder has no `pack.json`
+ * of its own (not "has one that fails validation" — see `ManifestAttempt`'s
+ * doc comment), its immediate subfolders are probed the same way, and each
+ * one that DOES have a valid `pack.json` counts as its own discovered pack
+ * (`folder` set to the child path). This lets a user configure one parent
+ * (`packs`) that holds several pack folders (`packs/pack1`, `packs/pack2`)
+ * instead of listing each one in the host's setting. Exactly one level
+ * deep, never recursive: a grandchild's `pack.json` is never found this
+ * way. A parent with neither its own manifest nor any child manifest is
+ * skipped exactly as before ("no readable pack.json"), and a child that
+ * DOES have a `pack.json` but fails validation is skipped individually, by
+ * its own (child) folder path.
+ */
+/**
+ * When a `ManifestAttempt` succeeded (`kind: 'found'`) but the manifest's
+ * `engine` does not match `supportedEngine`, downgrades it to
+ * a `SkippedPackFolder` instead of a `DiscoveredPack` — same effect
+ * `@markii/react`'s `loadPack` already has for an unsupported engine
+ * (nothing registered for that namespace, unknown-component fallback for
+ * every directive under it), but recorded here too so it also drops out of
+ * a host's Insert Component / completion catalog (`discoverConfiguredPacks`
+ * consumers) instead of offering a snippet for a component nothing can
+ * ever render, and so the skip reaches the SAME diagnostics line every
+ * other skip does — never silent.
+ */
+function checkEngine(pack, supportedEngine) {
+    if (supportedEngine === undefined ||
+        packSupportsEngine(pack.manifest, supportedEngine)) {
+        return { kind: 'found', pack };
+    }
+    return {
+        kind: 'invalid',
+        reason: `pack engine "${packDeclaredEngines(pack.manifest)}" is not supported here (expected "${supportedEngine}"); its components fall back to the unknown-component box`,
+        engineUnsupported: {
+            packName: pack.manifest.name,
+            components: declaredPackComponents(pack.manifest),
+        },
+    };
+}
+/**
+ * Discovers and validates a pack in each of `folders`, in order, then
+ * removes (and reports via `collisions`) every pack whose namespace repeats
+ * across the set. Duplicate folder entries in `folders` collapse to one
+ * discovery attempt each (`Set`), so a repeated setting entry can never
+ * itself manufacture a spurious collision.
+ *
+ * `supportedEngine`, when given, additionally skips (rather than
+ * discovers) any pack whose manifest names a different `engine` — see
+ * `checkEngine`. Omitted (the default), a pack's engine is not checked
+ * here at all, matching this function's behavior before this parameter
+ * existed; a caller that only lists packs for a purpose engine-agnostic
+ * (e.g. `@markii/pack`'s own tooling) is unaffected.
+ *
+ * ONE-LEVEL PARENT-FOLDER SCAN: when a configured folder has no `pack.json`
+ * of its own (not "has one that fails validation" — see `ManifestAttempt`'s
+ * doc comment), its immediate subfolders are probed the same way, and each
+ * one that DOES have a valid `pack.json` counts as its own discovered pack
+ * (`folder` set to the child path). This lets a user configure one parent
+ * (`packs`) that holds several pack folders (`packs/pack1`, `packs/pack2`)
+ * instead of listing each one in the host's setting. Exactly one level
+ * deep, never recursive: a grandchild's `pack.json` is never found this
+ * way. A parent with neither its own manifest nor any child manifest is
+ * skipped exactly as before ("no readable pack.json"), and a child that
+ * DOES have a `pack.json` but fails validation is skipped individually, by
+ * its own (child) folder path.
+ */
+export async function discoverPacks(folders, readFile, listDirectory, supportedEngine) {
+    const uniqueFolders = [...new Set(folders)];
+    const found = [];
+    const skipped = [];
+    for (const folder of uniqueFolders) {
+        const rawAttempt = await tryLoadPackAt(folder, readFile);
+        const attempt = rawAttempt.kind === 'found'
+            ? checkEngine(rawAttempt.pack, supportedEngine)
+            : rawAttempt;
+        if (attempt.kind === 'found') {
+            found.push(attempt.pack);
+            continue;
+        }
+        if (attempt.kind === 'invalid') {
+            skipped.push({
+                folder,
+                reason: attempt.reason,
+                ...(attempt.engineUnsupported
+                    ? { engineUnsupported: attempt.engineUnsupported }
+                    : {}),
+            });
+            continue;
+        }
+        // 'missing': this folder itself has no pack.json — try its immediate
+        // children, one level only.
+        let entries = [];
+        try {
+            entries = await listDirectory(folder);
+        }
+        catch {
+            entries = [];
+        }
+        let anyChildManifest = false;
+        for (const entry of entries.slice(0, MAX_CHILD_FOLDERS_PER_PARENT)) {
+            if (!entry.isDirectory)
+                continue;
+            const childFolder = joinPath(folder, entry.name);
+            const rawChildAttempt = await tryLoadPackAt(childFolder, readFile);
+            const childAttempt = rawChildAttempt.kind === 'found'
+                ? checkEngine(rawChildAttempt.pack, supportedEngine)
+                : rawChildAttempt;
+            if (childAttempt.kind === 'found') {
+                found.push(childAttempt.pack);
+                anyChildManifest = true;
+            }
+            else if (childAttempt.kind === 'invalid') {
+                skipped.push({
+                    folder: childFolder,
+                    reason: childAttempt.reason,
+                    ...(childAttempt.engineUnsupported
+                        ? { engineUnsupported: childAttempt.engineUnsupported }
+                        : {}),
+                });
+                anyChildManifest = true;
+            }
+            // 'missing' for a child: an ordinary non-pack subfolder, not worth
+            // reporting individually.
+        }
+        if (!anyChildManifest) {
+            skipped.push({ folder, reason: 'no readable pack.json' });
+        }
+    }
+    const collisionNames = new Set(detectNamespaceCollisions(found.map((pack) => pack.manifest.name)).map((collision) => collision.namespace));
+    const packs = found.filter((pack) => !collisionNames.has(pack.manifest.name));
+    for (const pack of found) {
+        if (collisionNames.has(pack.manifest.name)) {
+            skipped.push({
+                folder: pack.folder,
+                reason: `pack namespace "${pack.manifest.name}" collides with another configured pack and was not installed`,
+            });
+        }
+    }
+    return {
+        packs,
+        collisions: [...collisionNames],
+        skipped,
+    };
+}
+/** The discovered packs' namespaces — what `resolveUses` (`@markii/pack`) checks a note's `uses:` declaration against. */
+export function installedNamespaces(packs) {
+    return packs.map((pack) => pack.manifest.name);
+}

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

@@ -0,0 +1,79 @@
+import type { PackManifest } from '@markii/pack';
+/** The minimal shape of one loaded pack this module needs — a structural subset of `./discover.ts`'s `DiscoveredPack`. */
+export interface PackDiagnosticsPack {
+    readonly manifest: Pick<PackManifest, 'name' | 'engine' | 'components'>;
+}
+/** The minimal shape of one skipped folder this module needs — a structural subset of `./discover.ts`'s `SkippedPackFolder`. */
+export interface PackDiagnosticsSkippedFolder {
+    readonly folder: string;
+    readonly reason: string;
+}
+export interface PackDiagnosticsContext {
+    /** Every validated, non-colliding discovered pack. */
+    readonly packs: readonly PackDiagnosticsPack[];
+    /** The renderer engine whose components the "Loaded pack" line counts. Absent counts every declared component. */
+    readonly engine?: string;
+    /** Configured folders that produced no usable pack, and why. */
+    readonly skipped: readonly PackDiagnosticsSkippedFolder[];
+    /** Already-formatted lines, one per relative pack-folder-setting entry (host-specific wording — see this module's top doc comment). Defaults to none. */
+    readonly relativeEntryLines?: readonly string[];
+    /** Already-formatted informational lines, one per pack whose prebuilt webview.js shadows component sources on disk (host-specific wording, since each host names its own build command). Informational, never a failure: shipping both is a supported state. */
+    readonly prebuiltShadowLines?: readonly string[];
+    /** Pack CSS authoring warnings against every built pack's emitted stylesheet. Warnings only, developer-facing. */
+    readonly cssWarnings: readonly string[];
+    /** One line per malformed pack registration, dropped rather than installed (`./pack-render-registry.ts`'s `BuildRenderRegistryResult.invalidReasons`). Omitted (or empty) contributes nothing — a host that never validates registrations on this side (e.g. VS Code's webview validates them separately, in the browser) simply has none to report yet. */
+    readonly invalidRegistrationReasons?: readonly string[];
+    /** Namespaces shared by two or more registered packs (`./pack-render-registry.ts`'s `BuildRenderRegistryResult.collisions`). When non-empty, contributes one summary line. */
+    readonly registrationCollisions?: readonly string[];
+    /** Composed directive names two DIFFERENT packs both claimed (`./pack-render-registry.ts`'s `BuildRenderRegistryResult.duplicateComposedNames`) — the first pack keeps the name, and each entry here names both the pack that kept it and the pack whose component was skipped. Omitted (or empty) contributes nothing; this is expected to stay empty under ordinary pack composition (see that module's doc comment). */
+    readonly duplicateComposedNames?: readonly {
+        readonly composedName: string;
+        readonly keptPack: string;
+        readonly skippedPack: string;
+    }[];
+    /**
+     * One entry per validated, non-colliding pack whose declared engine
+     * `@markii/react`'s `loadPack` cannot run (`./pack-render-registry.ts`'s
+     * `BuildRenderRegistryResult.droppedEngines`). Omitted (or
+     * empty) contributes nothing — the ordinary case where every registered
+     * pack's engine is supported.
+     */
+    readonly droppedEngines?: readonly {
+        name: string;
+        engine: string;
+    }[];
+}
+/** The one line for a folder `discoverPacks` could not turn into a usable pack. */
+export declare function skippedPackFolderLine(entry: PackDiagnosticsSkippedFolder): string;
+/**
+ * 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 declare function formatPackDiagnosticLines(context: PackDiagnosticsContext): string[];
+/** How many configured folders failed to produce a usable pack — what a preview's quiet marker counts. */
+export declare function skippedPackCount(context: {
+    readonly skipped: readonly PackDiagnosticsSkippedFolder[];
+}): number;
+/**
+ * One informational line for a pack whose prebuilt `webview.js` shadows
+ * component sources still present in the same folder.
+ * The tail clause names how a user would rebuild the prebuilt artifact
+ * from those sources: VS Code's own Export Pack command, or, 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 declare function prebuiltShadowLine(pack: {
+    readonly name: string;
+    readonly folder: string;
+}, rebuildInstruction: string): string;

package/dist/packs/pack-diagnostics.js

@@ -0,0 +1,103 @@
+/**
+ * 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 — `[]` 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.
+ * The tail clause names how a user would rebuild the prebuilt artifact
+ * from those sources: VS Code's own Export Pack command, or, 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[];