@markii/host 0.0.1 → 0.17.0-next.2

package/dist/node-fs.js

@@ -0,0 +1,70 @@
+/**
+ * The Node-backed implementations of the file-system seams the
+ * environment-free half of this package injects: pack discovery's file
+ * reader and directory lister, the pack-scripts reader, and the `.mkp`
+ * extraction filesystem. Reached only through `@markii/host/node`; nothing
+ * in the main entry imports this module.
+ */
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+/** The real, Node-backed `PackDirectoryLister`. Never rejects: an unreadable, missing or non-directory path resolves `[]`. */
+export function createNodeDirectoryLister() {
+    return async (absoluteDir) => {
+        try {
+            const entries = await readdir(absoluteDir, { withFileTypes: true });
+            return entries.map((entry) => ({
+                name: entry.name,
+                isDirectory: entry.isDirectory(),
+            }));
+        }
+        catch {
+            return [];
+        }
+    };
+}
+/** The real, Node-backed `PackFileReader`. Never rejects: an unreadable or missing path resolves `undefined`. */
+export function createNodeFileReader() {
+    return async (absolutePath) => {
+        try {
+            return await readFile(absolutePath, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+/** The real, Node-backed `PackScriptsReader`. */
+export function createNodeReader() {
+    const listDirectory = createNodeDirectoryLister();
+    const readText = createNodeFileReader();
+    return {
+        readDirectory: (absoluteDir) => listDirectory(absoluteDir),
+        readFile: (absolutePath) => readText(absolutePath),
+    };
+}
+/** The real, Node-backed `ArchiveExtractFs`. */
+export function createNodeArchiveExtractFs() {
+    return {
+        removeDirectory: async (absolutePath) => {
+            try {
+                await rm(absolutePath, { recursive: true, force: true });
+            }
+            catch {
+                // Quiet: the write that follows fails loudly on its own if the
+                // path is genuinely unusable.
+            }
+        },
+        makeDirectory: async (absolutePath) => {
+            await mkdir(absolutePath, { recursive: true });
+        },
+        writeFile: async (absolutePath, bytes) => {
+            await writeFile(absolutePath, bytes);
+        },
+    };
+}
+/** Pack discovery's reads over the real file system. */
+export function createNodePackDiscoveryIo() {
+    return {
+        readFile: createNodeFileReader(),
+        listDirectory: createNodeDirectoryLister(),
+    };
+}

package/dist/node.d.ts

@@ -0,0 +1,5 @@
+export type { SpawnRunOptions } from './run/run-host.js';
+export { defaultWorkerPath, spawnRunInThread, 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 { defaultWorkerPath, spawnRunInThread, 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` (batch 7 #46), 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,81 @@
+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`, batch 7 #46). 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 — 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 declare function prebuiltShadowLine(pack: {
+    readonly name: string;
+    readonly folder: string;
+}, rebuildInstruction: string): string;