@cldmv/slothlet 3.15.3 → 3.16.0

package/types/stub/lib/helpers/config.d.mts

@@ -1,3 +1,322 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/helpers/config";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Normalize the `hook` config (V2-style support) into a canonical
+ * `{ enabled, pattern, suppressErrors }` object.
+ *
+ * Accepts the boolean form (enable/disable with the catch-all pattern), the string form
+ * (enable, restricting hooks to a global path pattern — e.g. `"database.*"`), or the full
+ * object form. Idempotent: an already-normalized object normalizes to an equivalent object,
+ * so `reload()` can re-feed it.
+ *
+ * Exported as a standalone function (not just a {@link Config} method) because the HookManager
+ * is constructed during `_initializeComponents` — BEFORE `transformConfig` runs — so it cannot
+ * rely on the normalized config being in place yet, and must normalize the raw `config.hook`
+ * itself from the same source of truth.
+ *
+ * @param {boolean|string|Object} [hook] - Raw hook config in any supported form.
+ * @returns {{enabled: boolean, pattern: (string|null), suppressErrors: boolean, pin: boolean}} Normalized hook config.
+ * @public
+ */
+export function normalizeHookConfig(hook?: boolean | string | Object): {
+    enabled: boolean;
+    pattern: (string | null);
+    suppressErrors: boolean;
+    pin: boolean;
+};
+/**
+ * Configuration normalization utilities
+ * @class Config
+ * @extends ComponentBase
+ * @public
+ */
+export class Config extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Normalize collision configuration for handling property collisions
+     * @param {string|Object} collision - Collision mode or object with per-context modes
+     * @returns {Object} Normalized collision configuration with initial and api.slothlet.api.add modes
+     * @public
+     *
+     * @description
+     * Normalizes collision handling configuration for both initial load (buildAPI)
+     * and hot reload (api.add) contexts. Supports six collision modes:
+     * - "skip": Silently ignore collision, keep existing value
+     * - "warn": Warn about collision, keep existing value
+     * - "replace": Replace existing value completely
+     * - "merge": Merge properties (preserve original + add new)
+     * - "merge-replace": Merge properties (add new + overwrite existing with new values)
+     * - "error": Throw error on collision
+     *
+     * @example
+     * // String shorthand applies to both contexts
+     * normalizeCollision("merge")
+     * // => { initial: "merge", api: "merge" }
+     *
+     * @example
+     * // Object allows per-context control
+     * normalizeCollision({ initial: "warn", api: "error" })
+     * // => { initial: "warn", api: "error" }
+     */
+    public normalizeCollision(collision: string | Object): Object;
+    /**
+     * Normalize runtime input to internal standard format
+     * @param {string} runtime - Input runtime type (various formats accepted)
+     * @returns {string} Normalized runtime type ("async" or "live")
+     * @public
+     */
+    public normalizeRuntime(runtime: string): string;
+    /**
+     * Normalize mode input to internal standard format
+     * @param {string} mode - Input mode type (various formats accepted)
+     * @returns {string} Normalized mode type ("eager" or "lazy")
+     * @public
+     */
+    public normalizeMode(mode: string): string;
+    /**
+     * Normalize mutations configuration for API modification control
+     * @param {Object} mutations - Mutations config object with add/remove/reload properties
+     * @returns {Object} Normalized mutations configuration
+     * @public
+     *
+     * @description
+     * Normalizes mutation control configuration for API runtime modifications.
+     * Controls whether api.slothlet.api.add(), api.slothlet.api.remove(), and
+     * api.slothlet.reload() operations are allowed.
+     *
+     * @example
+     * // Allow all mutations (default)
+     * normalizeMutations({ add: true, remove: true, reload: true })
+     * // => { add: true, remove: true, reload: true }
+     *
+     * @example
+     * // Disable all mutations
+     * normalizeMutations({ add: false, remove: false, reload: false })
+     * // => { add: false, remove: false, reload: false }
+     */
+    public normalizeMutations(mutations: Object): Object;
+    /**
+     * Normalize debug configuration
+     * @param {boolean|Object} debug - Debug flag or object with targeted flags
+     * @returns {Object} Normalized debug object with all flags
+     * @public
+     */
+    public normalizeDebug(debug: boolean | Object): Object;
+    /**
+     * Normalize execution-environment target from the raw `platform` config value.
+     *
+     * @description
+     * Distinct from `normalizeEnv()` which handles the `process.env` snapshot
+     * allowlist (`config.env`). This method determines *where* slothlet is executing
+     * so that filesystem-dependent code paths can be bypassed in browser/worker builds.
+     *
+     * When `platform` is omitted the method auto-detects by checking whether
+     * `process.versions.node` is available (true in Node.js; absent or undefined
+     * in browsers, web workers, and Electron renderers without nodeIntegration).
+     * Pass `"browser"` or `"node"` to override auto-detection for edge cases
+     * (e.g. Deno, Electron with custom process polyfills).
+     *
+     * @param {*} platform - Raw value of `config.platform` before normalisation.
+     * @returns {"browser"|"node"} Execution-environment target.
+     * @public
+     *
+     * @example
+     * normalizeEnvTarget("browser"); // => "browser" (explicit override)
+     * normalizeEnvTarget("node");    // => "node"    (explicit override)
+     * normalizeEnvTarget(undefined); // => "browser" or "node" (auto-detected)
+     */
+    public normalizeEnvTarget(platform: any, hasManifest?: boolean): "browser" | "node";
+    /**
+     * Normalize the `hook` config (V2-style support) into a canonical
+     * `{ enabled, pattern, suppressErrors }` object.
+     *
+     * Accepts the boolean form (enable/disable with the catch-all pattern), the string form
+     * (enable, restricting hooks to a global path pattern — e.g. `"database.*"`), or the full
+     * object form. Idempotent: an already-normalized object normalizes to an equivalent object,
+     * so `reload()` can re-feed it. Shared by {@link transformConfig} and the HookManager so both
+     * derive the same values regardless of construction order (the manager is built before
+     * transformConfig runs, so it cannot rely on the normalized config being in place yet).
+     *
+     * @param {boolean|string|Object} [hook] - Raw hook config in any supported form.
+     * @returns {{enabled: boolean, pattern: (string|null), suppressErrors: boolean, pin: boolean}} Normalized hook config.
+     * @public
+     */
+    public normalizeHook(hook?: boolean | string | Object): {
+        enabled: boolean;
+        pattern: (string | null);
+        suppressErrors: boolean;
+        pin: boolean;
+    };
+    /**
+     * Transform and validate configuration
+     * @param {Object} config - Raw configuration options
+     * @returns {Object} Normalized configuration
+     * @throws {SlothletError} If configuration is invalid
+     * @public
+     */
+    public transformConfig(config?: Object): Object;
+    /**
+     * Normalize and validate the suppressFixes option. Emits a deprecation warning for each
+     * rule ID present. Invalid entries (non-strings, unknown rule IDs) are silently dropped.
+     *
+     * @param {string[]|undefined} suppressFixes - Raw suppressFixes value from user config.
+     * @param {boolean} silent - If true, suppress warnings.
+     * @returns {Set<string>} Normalized set of suppressed rule IDs.
+     * @example
+     * // Rule IDs use the <rule>_<PR> form. The C03 fix landed in PR #116.
+     * normalizeSuppressFixes(["C03_116"], false); // emits WARN_SUPPRESS_FIX_ACTIVE for C03_116
+     * @public
+     */
+    public normalizeSuppressFixes(suppressFixes: string[] | undefined, silent: boolean): Set<string>;
+    /**
+     * Normalize TypeScript configuration
+     * @param {boolean|string|Object} typescript - TypeScript config (true, "fast", or { mode: "fast"|"strict", ... })
+     * @returns {Object|null} Normalized TypeScript configuration or null if disabled
+     * @public
+     */
+    public normalizeTypeScript(typescript: boolean | string | Object): Object | null;
+    /**
+     * Normalize env snapshot configuration.
+     *
+     * @description
+     * Validates the `env` option from user config. When `include` is a non-empty
+     * string array, returns `{ include }` (the allowlist used by `_captureEnvSnapshot`).
+     * Any other value — including `undefined`, `null`, `{}`, or an empty `include`
+     * array — is normalised to `null`, meaning the full `process.env` snapshot is used.
+     *
+     * @param {Object|null|undefined} env - Raw env option from user config.
+     * @param {string[]} [env.include] - Allowlist of env variable names to capture.
+     * @returns {{ include: string[] }|null} Normalized env config, or `null` for full snapshot.
+     * @public
+     *
+     * @example
+     * // No restriction — full snapshot
+     * normalizeEnv(undefined); // => null
+     * normalizeEnv(null);      // => null
+     * normalizeEnv({});        // => null
+     *
+     * @example
+     * // Include allowlist
+     * normalizeEnv({ include: ["NODE_ENV", "PORT"] });
+     * // => { include: ["NODE_ENV", "PORT"] }
+     *
+     * @example
+     * // Non-string keys in the include array are filtered out
+     * normalizeEnv({ include: ["NODE_ENV", 42, null] });
+     * // => { include: ["NODE_ENV"] }
+     */
+    public normalizeEnv(env: Object | null | undefined): {
+        include: string[];
+    } | null;
+    /**
+     * Normalize + validate the construction-time `lifecycle` subscription map (#148).
+     *
+     * @description
+     * The `lifecycle` option registers event handlers on the Lifecycle emitter BEFORE the api builds,
+     * so events emitted during cold-start `buildAPI` (init-time `impl:warning` / `impl:created` / …)
+     * are observable. It is a plain object mapping an event name to a handler function or an array of
+     * handler functions. Any event name is accepted — registration is just early `subscribe()` calls,
+     * so these handlers also receive runtime events afterward.
+     *
+     * Idempotent: an already-normalized map (values already functions / arrays of functions) passes
+     * through unchanged, so `reload()` can re-feed it.
+     *
+     * @param {object|null|undefined} lifecycle - Raw `lifecycle` option from user config.
+     * @returns {object|null} The validated map, or `null` when absent.
+     * @throws {SlothletError} INVALID_CONFIG when the shape is not a plain object of functions / function arrays.
+     * @public
+     *
+     * @example
+     * normalizeLifecycle({ "impl:warning": (data) => log(data) });
+     * // => { "impl:warning": (data) => log(data) }
+     *
+     * @example
+     * normalizeLifecycle({ "impl:error": [onError, auditError] });
+     * // => { "impl:error": [onError, auditError] }
+     */
+    public normalizeLifecycle(lifecycle: object | null | undefined): object | null;
+    /**
+     * Normalize + validate the `routines` config option (#341).
+     *
+     * @description
+     * A routine is a named cross-module runnable: every mounted module that exports a function
+     * matching a configured routine name gets stacked into one chain at its resolved api path, and
+     * a root cascade runs every matching contribution anywhere, ordered per the entry's `order`.
+     * See `docs/LIFECYCLE.md` ("Routines") for the full contract.
+     *
+     * Each entry normalizes to `{ name, mode, recursive, order }` — `recursive` and `order` are
+     * always present on the normalized output, even when the raw entry omitted them:
+     * - `"name"` (string, no `:`) → `{ name, mode: "manual", recursive: false, order: "mount" }`.
+     * - `"name:mode"` (string, split once on the first `:`) → `{ name, mode, recursive: false, order: <mode-defaulted> }`.
+     * - `{ name, mode?, recursive?, order? }` (object) → `mode` defaults to `"manual"`, `recursive` to
+     *   `false`, and `order` to {@link DEFAULT_ROUTINE_ORDER_BY_MODE}`[mode]` when each is omitted.
+     *
+     * Providing `routines` at all REPLACES {@link DEFAULT_ROUTINES} — that is the off-switch
+     * (`routines: []` disables every routine). Omitting the option keeps the built-in defaults.
+     * `slothlet.defaults.routines` is the frozen source of those defaults, exported for a consumer
+     * to spread (extend) or filter (drop one) rather than replace wholesale.
+     *
+     * Idempotent: an already-normalized list (every entry already `{ name, mode, recursive, order }`)
+     * normalizes to an equivalent list — same values, always freshly-built objects (never the same
+     * references) — so `reload()` can safely re-feed it.
+     *
+     * @param {undefined|null|Array<string|{name: string, mode?: string, recursive?: boolean, order?: string}>} routines - Raw `routines` option.
+     * @returns {Array<{name: string, mode: "manual"|"startup"|"shutdown"|"destroy", recursive: boolean, order: "mount"|"depth"}>} Normalized routines list.
+     * @throws {SlothletError} INVALID_CONFIG when the shape is invalid, a name is empty/reserved/an invalid glob, or a mode/order is unrecognized.
+     * @public
+     *
+     * @example
+     * normalizeRoutines(undefined);
+     * // => [{ name: "initialize", mode: "startup", recursive: false, order: "mount" },
+     * //     { name: "shutdown", mode: "shutdown", recursive: false, order: "depth" }]
+     *
+     * @example
+     * normalizeRoutines(["launch", "prefetch:startup", { name: "warmup" }]);
+     * // => [{ name: "launch", mode: "manual", recursive: false, order: "mount" },
+     * //     { name: "prefetch", mode: "startup", recursive: false, order: "mount" },
+     * //     { name: "warmup", mode: "manual", recursive: false, order: "mount" }]
+     *
+     * @example
+     * normalizeRoutines([]);
+     * // => [] — disables every routine
+     */
+    public normalizeRoutines(routines: undefined | null | Array<string | {
+        name: string;
+        mode?: string;
+        recursive?: boolean;
+        order?: string;
+    }>): Array<{
+        name: string;
+        mode: "manual" | "startup" | "shutdown" | "destroy";
+        recursive: boolean;
+        order: "mount" | "depth";
+    }>;
+    /**
+     * Normalize permissions configuration.
+     *
+     * @param {object|null} [permissions] - Raw permissions config from user.
+     * @param {string} [permissions.defaultPolicy="allow"] - Fallback policy: "allow" or "deny".
+     * @param {boolean} [permissions.enabled=true] - Global toggle.
+     * @param {string|boolean} [permissions.audit="default"] - Audit level: `"default"` (denied + self-bypass only),
+     *   `"verbose"` (all decisions). `true` and `false` are accepted and both normalize to `"default"`.
+     * @param {object} [permissions.references] - Options governing api functions held as references.
+     * @param {boolean} [permissions.references.capture=true] - When `true` (the default), a function read
+     *   out of the api carries the identity of the module that read it, so it stays enforced as that module
+     *   wherever it is later invoked. Set `false` to restore the older host-initiated treatment.
+     * @param {boolean} [permissions.failOpenOnAbsentCaller=false] - When `false` (the default), calls
+     *   and reads occurring inside an active context with no resolvable (or forged) caller identity
+     *   fail closed (denied); only genuinely host-initiated calls are exempt via the trusted-root
+     *   marker. Set `true` to restore the legacy fail-open behaviour.
+     * @param {boolean} [permissions.readGating=true] - When `true` (the default), reading a terminal
+     *   data value (primitive, Buffer, TypedArray, Date, Map, etc.) off a module API path is
+     *   permission-checked, the same way calls are. Set `false` to opt out and gate calls only.
+     * @param {Array<object>} [permissions.rules=[]] - Initial permission rules.
+     * @returns {object|null} Normalized permissions config, or null when permissions is absent or not an object.
+     *
+     * @example
+     * normalizePermissions({ defaultPolicy: "deny", rules: [{ caller: "**", target: "admin.**", effect: "deny" }] });
+     * // => { defaultPolicy: "deny", enabled: true, audit: "default", readGating: true, rules: [...] }
+     */
+    normalizePermissions(permissions?: object | null): object | null;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/helpers/defaults.d.mts

@@ -1,3 +1,42 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/helpers/defaults";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * The default `apiDepth` (directory-traversal depth) applied when a caller does not specify one.
+ * Unbounded by default. The config normalizer ({@link module:@cldmv/slothlet/helpers/config}) is
+ * what every real compose path reads — it resolves `config.apiDepth` once and the mode processors
+ * receive that already-normalized value. The mode processors' and the loader's own parameter
+ * defaults exist only for the case where they are invoked directly, bypassing normalization (a
+ * standalone call, a future direct consumer); they read this same constant so that case can never
+ * silently disagree with the normalized default.
+ * @type {number}
+ */
+export const DEFAULT_API_DEPTH: number;
+/**
+ * The built-in `routines` list applied when a caller omits the `routines` config option entirely.
+ * Each entry is `{ name, mode }` (bare mount-relative names, non-recursive, mode-defaulted `order`)
+ * — see `docs/LIFECYCLE.md` ("Routines") for the full contract, including the `recursive`/`order`/
+ * `destroy`-mode fields a caller-supplied entry may also set. Passing `routines` at all REPLACES
+ * this list (it is the off-switch); a consumer that wants to extend rather than replace it spreads
+ * this array: `slothlet.defaults.routines`.
+ *
+ * Frozen at every level (the array, and each entry object) so a consumer's spread copies the
+ * entries by reference safely without risking a mutation here leaking across consumers.
+ * @type {ReadonlyArray<{name: string, mode: "manual"|"startup"|"shutdown"|"destroy"}>}
+ */
+export const DEFAULT_ROUTINES: ReadonlyArray<{
+    name: string;
+    mode: "manual" | "startup" | "shutdown" | "destroy";
+}>;
+/**
+ * The complete set of framework-reserved export names — names a module export can never
+ * meaningfully claim because the framework's own wrapper machinery already owns them.
+ *
+ * Derived as the union of {@link ComponentBase.INTERNAL_KEYS} (wrapper state/control properties)
+ * and `IMPL_METADATA_KEYS` (child-adoption metadata) — the same two Sets `isFrameworkReservedKey()`
+ * (`#handlers/unified-wrapper`) checks against, combined here into one Set for convenient
+ * introspection. Wrapped via {@link freezeSet} — `Object.freeze()` alone would leave `add`/
+ * `delete`/`clear` callable, letting a consumer mutate this shared singleton (and corrupt what
+ * every other consumer in the same process sees) despite it claiming to be frozen.
+ * @type {ReadonlySet<string>}
+ */
+export const RESERVED_EXPORTS: ReadonlySet<string>;

package/types/stub/lib/helpers/eventemitter-context.d.mts

@@ -1,3 +1,32 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/helpers/eventemitter-context";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Set the context checker callback
+ * Called by the runtime to register a way to detect API context
+ * @param {Function} checker - Function that returns true if in API context
+ * @public
+ */
+export function setApiContextChecker(checker: Function): void;
+/**
+ * Enable EventEmitter context propagation by patching EventEmitter.prototype.
+ * This should be called ONCE globally when the first slothlet instance is created.
+ * Subsequent calls will be ignored (patching is global).
+ *
+ * @public
+ */
+export function enableEventEmitterPatching(): void;
+/**
+ * Disable EventEmitter context propagation and restore original methods.
+ * This should only be called when ALL slothlet instances have been shut down.
+ *
+ * @public
+ */
+export function disableEventEmitterPatching(): void;
+/**
+ * Cleanup all tracked EventEmitters created within slothlet API context.
+ * This removes all listeners from tracked emitters and clears tracking structures.
+ * Should be called during shutdown to prevent memory leaks and hanging processes.
+ *
+ * @public
+ */
+export function cleanupEventEmitterResources(): void;

package/types/stub/lib/helpers/eventtarget-context.d.mts

@@ -1,3 +1,22 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/helpers/eventtarget-context";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Enable context propagation through `EventTarget` listeners.
+ *
+ * Called once globally when the first instance is created; later calls are ignored, matching how
+ * EventEmitter patching behaves.
+ *
+ * @returns {void}
+ * @public
+ */
+export function enableEventTargetPatching(): void;
+/**
+ * Restore the original `EventTarget` methods.
+ *
+ * Restores a method only when the patch installed here is still in place, so anything that replaced
+ * it afterwards keeps ownership of its own restore.
+ *
+ * @returns {void}
+ * @public
+ */
+export function disableEventTargetPatching(): void;

package/types/stub/lib/helpers/eventtarget-property-context.d.mts

@@ -0,0 +1,23 @@
+// AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Pin `on*` handler assignments to the module that makes them.
+ *
+ * Called once globally when the first instance is created; later calls are ignored, matching how the
+ * other boundary patches behave. Costs nothing when no runtime registered a pinning strategy — the
+ * wrapper hands the callback straight through.
+ *
+ * @returns {void}
+ * @public
+ */
+export function enableEventTargetPropertyPatching(): void;
+/**
+ * Restore the original `on*` handler accessors.
+ *
+ * Restores an accessor only when the patch installed here is still in place, so anything that replaced
+ * it afterwards keeps ownership of its own restore.
+ *
+ * @returns {void}
+ * @public
+ */
+export function disableEventTargetPropertyPatching(): void;

package/types/stub/lib/helpers/generate-manifest.d.mts

@@ -1,3 +1,181 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/helpers/generate-manifest";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Generate a slothlet browser manifest by scanning a directory at build time.
+ *
+ * This is the primary entry point for producing the `manifest` object required by
+ * `slothlet({ manifest, resolveModuleSpecifier })`. Call this once during your build
+ * step and embed the result in your browser bundle.
+ *
+ * @param {string} dir - Absolute or relative path to the API root directory.
+ * @returns {Promise<{ files: Array<{path:string,name:string,fullName:string}>, directories: Array }>}
+ *   Manifest object ready to pass to `slothlet()`.
+ *
+ * @throws {SlothletError} `GENERATE_MANIFEST_DIR_INVALID` if `dir` is not a non-empty string.
+ * @throws {SlothletError} `GENERATE_MANIFEST_DIR_UNREADABLE` if `dir` cannot be read (missing path, permission denied); the underlying reason is surfaced in the message.
+ * @throws {SlothletError} `GENERATE_MANIFEST_NOT_DIRECTORY` if `dir` exists but is not a directory.
+ *
+ * @example
+ * // Build script — produces a manifest and writes it to disk
+ * import { generateManifest } from "@cldmv/slothlet/helpers/generate-manifest";
+ * import { writeFileSync } from "node:fs";
+ *
+ * const manifest = await generateManifest("./src/api");
+ * writeFileSync("./dist/api-manifest.json", JSON.stringify(manifest, null, 2));
+ *
+ * @example
+ * // Vite plugin — inline manifest into the browser bundle
+ * import { generateManifest } from "@cldmv/slothlet/helpers/generate-manifest";
+ *
+ * export function slothletManifestPlugin(apiDir) {
+ *   return {
+ *     name: "slothlet-manifest",
+ *     async buildStart() {
+ *       const manifest = await generateManifest(apiDir);
+ *       this.emitFile({
+ *         type: "asset",
+ *         fileName: "slothlet-manifest.json",
+ *         source: JSON.stringify(manifest)
+ *       });
+ *     }
+ *   };
+ * }
+ */
+export function generateManifest(dir: string): Promise<{
+    files: Array<{
+        path: string;
+        name: string;
+        fullName: string;
+    }>;
+    directories: any[];
+}>;
+/**
+ * Generate everything the browser needs to run slothlet, in one build-time call.
+ *
+ * Returns both halves of a browser-mode setup:
+ * - `manifest` — the API-directory listing passed to `slothlet({ manifest })` (replaces the
+ *   filesystem `readdir` slothlet uses in Node).
+ * - `importmap` — the `<script type="importmap">` content that lets the browser resolve slothlet's
+ *   own module graph AND the third-party packages the registered API leaves import.
+ *
+ * Run this in your build step (or, for Electron, in the main process) and send both to the
+ * renderer: inline `importmap` into the page's importmap script tag, and pass `manifest` (plus a
+ * `resolveModuleSpecifier` for your API base) to `slothlet()`.
+ *
+ * The importmap covers two surfaces. First, slothlet's own modules (rebased onto `slothletBase`).
+ * Second — and this is what the registered API leaves need — the **exact `exports` subpaths** of the
+ * other packages in the browser graph: the generator scans the `apiDir` leaves for the packages they
+ * import, reads each package's `package.json` `exports`, and emits the redirected subpath keys a
+ * plain prefix map can't produce (`@scope/ext/errors` → `…/@scope/ext/src/lib/errors.mjs`). Without
+ * these, a subpath the `exports` map redirects resolves to a literal URL and 404s in the browser, so
+ * consumers previously hand-maintained allowlists. Those sibling packages are served next to
+ * `@cldmv/slothlet` under a base **derived** from `slothletBase` (its node_modules/CDN parent). (#297)
+ *
+ * @param {string} apiDir - Absolute or relative path to the API root directory.
+ * @param {object} [options] - Options.
+ * @param {string} [options.slothletBase="/node_modules/@cldmv/slothlet/"] - URL/path prefix where
+ *   the `@cldmv/slothlet` package is served in the browser. Defaults to the conventional
+ *   node_modules location (slothlet installed as a dependency, node_modules served at the web
+ *   root). Override with a CDN URL, an Electron protocol path, or `"/"` when the package is served
+ *   at the web root.
+ * @returns {Promise<{ manifest: { files: Array, directories: Array }, importmap: { imports: Object<string,string> } }>}
+ *   The API manifest and slothlet's own browser importmap.
+ *
+ * @throws {SlothletError} `GENERATE_BROWSER_ASSETS_SLOTHLET_BASE_INVALID` if `options.slothletBase` is provided but is not a string.
+ *
+ * @example
+ * // Build step — slothlet installed in node_modules (default base), ship both to the renderer.
+ * import { generateBrowserAssets } from "@cldmv/slothlet/helpers/generate-manifest";
+ * const { manifest, importmap } = await generateBrowserAssets("./src/api");
+ * // → inline importmap: `<script type="importmap">${JSON.stringify(importmap)}</script>`
+ * // → pass manifest to slothlet({ manifest, resolveModuleSpecifier })
+ *
+ * @example
+ * // Override the base for a CDN (or "/" when the package is served at the web root).
+ * const { manifest, importmap } = await generateBrowserAssets("./src/api", {
+ *   slothletBase: "https://cdn.example.com/@cldmv/slothlet@3/"
+ * });
+ */
+export function generateBrowserAssets(apiDir: string, options?: {
+    slothletBase?: string | undefined;
+}): Promise<{
+    manifest: {
+        files: any[];
+        directories: any[];
+    };
+    importmap: {
+        imports: {
+            [x: string]: string;
+        };
+    };
+}>;
+/**
+ * Generate the browser importmap for slothlet's OWN modules.
+ *
+ * In a browser, slothlet's internal imports (`@cldmv/slothlet`, `@cldmv/slothlet/helpers/*`, …)
+ * are static and resolved by the page's importmap **before slothlet runs** — they cannot route
+ * through `resolveModuleSpecifier` (which only governs API-leaf loads). This produces that
+ * importmap from slothlet's public export surface so consumers never hand-roll it.
+ *
+ * Each specifier is resolved via `import.meta.resolve`, which automatically picks the dev
+ * (`slothlet-dev` → `src/`) or published (`default` → `dist/`) files based on the conditions of
+ * the build process — then rebased onto `slothletBase` (where the package is served).
+ *
+ * @param {string} [slothletBase="/node_modules/@cldmv/slothlet/"] - URL/path prefix where the
+ *   `@cldmv/slothlet` package is served in the browser. Defaults to the conventional node_modules
+ *   location; override with a CDN URL, an Electron protocol path, or `"/"` when the package is
+ *   served at the web root.
+ * @returns {Promise<{ imports: Object<string,string> }>} An importmap object ready to inline as
+ *   `<script type="importmap">`.
+ */
+export function generateImportMap(slothletBase?: string): Promise<{
+    imports: {
+        [x: string]: string;
+    };
+}>;
+/**
+ * Collect the full set of `@cldmv/slothlet[/sub]` specifiers the browser importmap must cover.
+ *
+ * Three sources, unioned so the map mirrors slothlet's public export surface: (1) declared flat entry points from package.json `exports` — so
+ * every flat (non-wildcard) public module specifier a consumer can import resolves via the importmap, including public aggregators that
+ * slothlet's own internals never import directly (notably the bare `@cldmv/slothlet/runtime`, whose
+ * `/runtime/async` + `/runtime/live` variants are the only ones internally referenced); (2) a per-file
+ * enumeration of every wildcard `exports` directory (`./helpers/*`, `./handlers/*`, …) so EVERY exported
+ * subpath gets an entry by construction — not just the modules slothlet itself imports, so a browser can
+ * never hit a wildcard endpoint the map lacks; and (3) a recursive source scan as a backstop for any
+ * imported specifier the first two miss. i18n locales are handled separately — they are dynamic-template imports the
+ * static scan can't see, and are enumerated separately from the languages directory. Inclusion here is about
+ * specifier resolution, not runtime compatibility — some public exports (e.g. `typegen`, `devcheck`) are
+ * Node-only and won't execute in a browser even though their specifier resolves. JSON exports (the
+ * module-manifest schema) are tooling-only and excluded too — they aren't browser module imports. (#137)
+ *
+ * @param {string} root - The slothlet package root (holds package.json and the shipped source).
+ * @returns {Promise<Set<string>>} The set of bare specifiers, always including `@cldmv/slothlet` and
+ *   its flat (non-wildcard) public exports.
+ */
+export function collectSlothletSpecifiers(root: string): Promise<Set<string>>;
+/**
+ * Collect the exact importmap subpath keys for ANY package from its `package.json` `exports`.
+ *
+ * The package-agnostic counterpart to {@link collectSlothletSpecifiers}: given a package's root
+ * directory, read its `exports` map and return the bare specifier → relative-target pairs a browser
+ * importmap needs. Import maps do plain prefix substitution and never consult a package's `exports`,
+ * so a subpath the `exports` map *redirects* (`@scope/pkg/errors` → `./src/lib/errors.mjs`) 404s
+ * unless the importmap carries that exact key. This produces those keys.
+ *
+ * Handles the same shapes the self-collector does, generalized: the package root (`.`), flat
+ * (non-wildcard) subpaths, wildcard directories (`./x/*` → every module file under the declared
+ * target dir), conditional `exports` (via {@link pickBrowserTarget} — browser/import/default, never
+ * node/require), and the string-exports and conditions-only (`.` sugar) forms. Only ES-module
+ * targets are emitted (see {@link isBrowserModuleTarget}); a package with no `exports` (or an
+ * unreadable `package.json`) yields an empty map — the prefix map already covers those.
+ *
+ * The returned targets are the paths the `exports` map itself declares, so the caller rebases them
+ * onto wherever the package is served — no `import.meta.resolve` (which resolves from slothlet's own
+ * scope, not the consumer's) is involved.
+ *
+ * @param {string} packageRoot - Absolute path to the package's root (the dir holding its package.json).
+ * @returns {Promise<Map<string,string>>} Map of bare specifier → target path relative to `packageRoot`.
+ * @public
+ */
+export function collectPackageSpecifiers(packageRoot: string): Promise<Map<string, string>>;