@cldmv/slothlet 3.15.2 → 3.16.0

package/types/stub/lib/helpers/hint-detector.d.mts

@@ -1,3 +1,28 @@
 // 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/hint-detector";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Hint detection for providing helpful error hints
+ * @class HintDetector
+ * @extends ComponentBase
+ * @package
+ */
+export class HintDetector extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Detect appropriate hint key based on error
+     * @param {Error} error - The original error
+     * @param {string} errorCode - The SlothletError code
+     * @returns {string|undefined} Hint key for i18n translation, or undefined
+     * @public
+     */
+    public detectHint(error: Error, errorCode: string): string | undefined;
+}
+/**
+ * Detect appropriate hint key based on error
+ * @param {Error} error - The original error
+ * @param {string} errorCode - The SlothletError code
+ * @returns {string|undefined} Hint key for i18n translation, or undefined
+ * @public
+ */
+export function detectHint(error: Error, errorCode: string): string | undefined;
+import { ComponentBase } from "#factories/component-base";

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

@@ -1,3 +1,102 @@
 // 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/manifest-resolver";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /src/lib/helpers/manifest-resolver.mjs
+ *	@Date: 2026-05-28 00:00:00 -07:00 (1748419200)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-05-28 08:10:28 -07:00 (1779981028)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+/**
+ * @fileoverview Browser-safe factory for the `resolveModuleSpecifier` callback.
+ *
+ * @description
+ * `createManifestResolver(base)` produces a `resolveModuleSpecifier` function that
+ * resolves manifest-relative file paths to absolute URLs using the standard
+ * `new URL(path, base)` algorithm. This is the correct resolver for any deployment
+ * where API modules are served from a known base URL (the vast majority of use cases).
+ *
+ * This file has **no Node.js-specific imports** — it is safe to include in a browser
+ * bundle directly. For the build-time `generateManifest` utility (which uses `node:fs`)
+ * see `@cldmv/slothlet/helpers/generate-manifest`.
+ *
+ * ### Typical browser workflow
+ *
+ * ```text
+ * Build time  →  generateManifest("./src/api")  →  api-manifest.json
+ * Bundle time →  import api-manifest.json
+ * Runtime     →  createManifestResolver(import.meta.url)  →  pass to slothlet()
+ * ```
+ *
+ * @example
+ * // API modules live next to the current module
+ * import { createManifestResolver } from "@cldmv/slothlet/helpers/manifest-resolver";
+ * import manifest from "./api-manifest.json" assert { type: "json" };
+ * import { slothlet } from "@cldmv/slothlet";
+ *
+ * const api = await slothlet({
+ *   manifest,
+ *   resolveModuleSpecifier: createManifestResolver(import.meta.url)
+ * });
+ *
+ * @example
+ * // API modules live in a sub-directory relative to the current module
+ * import { createManifestResolver } from "@cldmv/slothlet/helpers/manifest-resolver";
+ *
+ * const api = await slothlet({
+ *   manifest,
+ *   resolveModuleSpecifier: createManifestResolver(new URL("./api/", import.meta.url))
+ * });
+ *
+ * @module @cldmv/slothlet/helpers/manifest-resolver
+ * @public
+ */
+/**
+ * Create a `resolveModuleSpecifier` callback that resolves manifest file entries
+ * to absolute URLs using a fixed base URL.
+ *
+ * The returned function implements the exact signature expected by
+ * `slothlet({ resolveModuleSpecifier })`: it receives a manifest file entry object
+ * and returns an importable URL string.
+ *
+ * @param {string|URL} base - The base URL that all manifest paths are relative to.
+ *   Pass `import.meta.url` when API modules sit next to your entry point, or
+ *   `new URL("./api/", import.meta.url)` when they are in a sub-directory.
+ * @returns {(entry: { path: string, name: string, fullName: string }) => string}
+ *   A `resolveModuleSpecifier` function ready to pass to `slothlet()`.
+ *
+ * @throws {TypeError} If `base` is not a string or URL instance.
+ *
+ * @example
+ * // Modules in the same directory as the current file
+ * const resolver = createManifestResolver(import.meta.url);
+ * // resolver({ path: "math.mjs", name: "math", fullName: "math.mjs" })
+ * // => "https://example.com/app/math.mjs"
+ *
+ * @example
+ * // Modules in an ./api/ sub-directory
+ * const resolver = createManifestResolver(new URL("./api/", import.meta.url));
+ * // resolver({ path: "auth.mjs", name: "auth", fullName: "auth.mjs" })
+ * // => "https://example.com/app/api/auth.mjs"
+ *
+ * @example
+ * // Full slothlet integration
+ * import manifest from "./api-manifest.json" assert { type: "json" };
+ * import { slothlet } from "@cldmv/slothlet";
+ * import { createManifestResolver } from "@cldmv/slothlet/helpers/manifest-resolver";
+ *
+ * const api = await slothlet({
+ *   manifest,
+ *   resolveModuleSpecifier: createManifestResolver(new URL("./api/", import.meta.url))
+ * });
+ */
+export function createManifestResolver(base: string | URL): (entry: {
+    path: string;
+    name: string;
+    fullName: string;
+}) => string;

package/types/stub/lib/helpers/modes-utils.d.mts

@@ -1,3 +1,36 @@
 // 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/modes-utils";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Mode processing utilities component class
+ * @extends ComponentBase
+ */
+export class ModesUtils extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Create a named wrapper for default export functions when they are anonymous.
+     * NOTE: This function is now a pass-through since UnifiedWrapper handles name/length/toString
+     * through its proxy get trap. Wrapping is no longer needed and causes toString mismatches.
+     * @param {Function} fn - Original function.
+     * @param {string} nameHint - Name to apply if fn is anonymous or named "default" (unused).
+     * @returns {Function} Original function unmodified.
+     * @public
+     */
+    public ensureNamedExportFunction(fn: Function, ____nameHint: any): Function;
+    /**
+     * Clone eager-mode module exports to avoid mutating import cache objects.
+     * @param {unknown} value - Value to clone for wrapping
+     * @param {string} mode - Current mode ("eager" or "lazy")
+     * @returns {unknown} Cloned value for eager mode, original otherwise
+     * @public
+     */
+    public cloneWrapperImpl(value: unknown, mode: string): unknown;
+    /**
+     * Helper to determine collision mode for ownership conflicts
+     * @param {Object} config - Slothlet configuration
+     * @param {string} collisionContext - Either 'initial' or 'api'
+     * @returns {string} Collision mode from config
+     * @public
+     */
+    public getOwnershipCollisionMode(config: Object, collisionContext?: string): string;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/helpers/module-discovery.d.mts

@@ -1,3 +1,82 @@
 // 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/module-discovery";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * @typedef {object} DiscoverOptions
+ * @property {string|string[]} [scanRoot] - Filesystem path(s) to scan. Default: upward-walk from process.cwd() to nearest node_modules ancestor.
+ * @property {string} [manifest="slothlet.module.json"] - Manifest filename, or `<file>#<dotted.key>` locator pointing at a subkey of another file (e.g. `"package.json#slothlet"`).
+ * @property {Record<string, string>} [schema] - Field-name remap for legacy manifests. Maps canonical name → legacy name.
+ * @property {string|string[]} [prefix] - Name-prefix filter applied BEFORE manifest read. Matches against full package name including scope.
+ * @property {(manifest: object, packageName: string) => boolean} [filter] - Content-based filter applied AFTER manifest validation.
+ */
+/**
+ * @typedef {object} DiscoverResult
+ * @property {string} packageName - Package name from package.json.
+ * @property {string} packageRoot - Resolved absolute filesystem path to the package directory.
+ * @property {string[]} mountPath - Normalized mountPath segments (always an array).
+ * @property {string} apiDir - Absolute resolved filesystem path to the apiDir inside the package.
+ * @property {object} manifest - Normalized + deep-frozen manifest (per M3).
+ */
+/**
+ * Walk the filesystem and return validated module candidates.
+ *
+ * @param {DiscoverOptions} [options] - Discovery options.
+ * @returns {Promise<DiscoverResult[]>} Discovered modules in walk order (apply `sort()` for deterministic ordering).
+ * @throws {SlothletError} `MODULE_*` codes on manifest validation failures or G7 duplicate-name-version-mismatch.
+ *
+ * @example
+ * import { discoverModules } from "@cldmv/slothlet/helpers/module-discovery";
+ *
+ * const found = await discoverModules();
+ * // Default upward-walk scanRoot, default slothlet.module.json manifest.
+ *
+ * @example
+ * const drivers = await discoverModules({
+ *   prefix: "@cldmv/packrat-driver-",
+ *   filter: (m) => m.kind === "driver"
+ * });
+ */
+export function discoverModules(options?: DiscoverOptions): Promise<DiscoverResult[]>;
+export type DiscoverOptions = {
+    /**
+     * - Filesystem path(s) to scan. Default: upward-walk from process.cwd() to nearest node_modules ancestor.
+     */
+    scanRoot?: string | string[] | undefined;
+    /**
+     * - Manifest filename, or `<file>#<dotted.key>` locator pointing at a subkey of another file (e.g. `"package.json#slothlet"`).
+     */
+    manifest?: string | undefined;
+    /**
+     * - Field-name remap for legacy manifests. Maps canonical name → legacy name.
+     */
+    schema?: Record<string, string> | undefined;
+    /**
+     * - Name-prefix filter applied BEFORE manifest read. Matches against full package name including scope.
+     */
+    prefix?: string | string[] | undefined;
+    /**
+     * - Content-based filter applied AFTER manifest validation.
+     */
+    filter?: ((manifest: object, packageName: string) => boolean) | undefined;
+};
+export type DiscoverResult = {
+    /**
+     * - Package name from package.json.
+     */
+    packageName: string;
+    /**
+     * - Resolved absolute filesystem path to the package directory.
+     */
+    packageRoot: string;
+    /**
+     * - Normalized mountPath segments (always an array).
+     */
+    mountPath: string[];
+    /**
+     * - Absolute resolved filesystem path to the apiDir inside the package.
+     */
+    apiDir: string;
+    /**
+     * - Normalized + deep-frozen manifest (per M3).
+     */
+    manifest: object;
+};

package/types/stub/lib/helpers/module-manifest-validator.d.mts

@@ -1,3 +1,38 @@
 // 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/module-manifest-validator";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Validate a parsed slothlet.module.json manifest and return a normalized form.
+ *
+ * @param {object} manifest - Parsed JSON manifest object (must already be valid JSON).
+ * @param {object} packageContext - Context derived from the host package.
+ * @param {string} packageContext.packageName - npm package `name` from package.json.
+ * @param {string} packageContext.packageVersion - npm package `version` from package.json.
+ * @param {string} [packageContext.packageDescription] - npm package `description` from package.json.
+ * @param {string} packageContext.packageRoot - Absolute filesystem path to the package root.
+ * @param {string} packageContext.manifestPath - Path to the manifest file (used in error context for diagnostics).
+ * @returns {object} Normalized manifest with the following shape:
+ *   - All optional fields filled in from defaults / package.json fallbacks
+ *   - `name`, `version` always present (from package.json if absent in manifest)
+ *   - `description` from manifest (override) or package.json (fallback)
+ *   - `priority` defaults to 0 if absent
+ *   - `mountPath` normalized to an array of segments
+ * @throws {SlothletError} with `MODULE_*` code on any validation failure.
+ *
+ * @example
+ * const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+ * const pkgJson = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+ * const normalized = validateModuleManifest(manifest, {
+ *   packageName: pkgJson.name,
+ *   packageVersion: pkgJson.version,
+ *   packageDescription: pkgJson.description,
+ *   packageRoot,
+ *   manifestPath
+ * });
+ */
+export function validateModuleManifest(manifest: object, packageContext: {
+    packageName: string;
+    packageVersion: string;
+    packageDescription?: string | undefined;
+    packageRoot: string;
+    manifestPath: string;
+}): object;

package/types/stub/lib/helpers/module-sort.d.mts

@@ -1,3 +1,66 @@
 // 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/module-sort";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /src/lib/helpers/module-sort.mjs
+ *	@Date: 2026-05-27T11:22:33-07:00 (1779906153)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-05-27 18:57:20 -07:00 (1779933440)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+/**
+ * @fileoverview Pure sort function for `DiscoverResult[]`.
+ * @module @cldmv/slothlet/helpers/module-sort
+ * @internal
+ *
+ * @description
+ * Default comparator sorts by `manifest.priority` descending (higher first)
+ * with `packageName` ascending as the tiebreak. Pass any custom comparator
+ * matching `Array.prototype.sort`'s `(a, b) => number` signature to override.
+ *
+ * Pure function: returns a new array; never mutates the input. The
+ * `DiscoverResult` entries are already deep-frozen by `discoverModules()`
+ * per M3, so the comparator cannot mutate them through this surface either.
+ */
+/**
+ * @typedef {object} DiscoverResult
+ * @property {string} packageName
+ * @property {string} packageRoot
+ * @property {string[]} mountPath
+ * @property {string} apiDir
+ * @property {object} manifest
+ */
+/**
+ * Sort a `DiscoverResult[]` and return a new array. Pure function.
+ *
+ * @param {DiscoverResult[]} results - Discovery results to sort.
+ * @param {(a: DiscoverResult, b: DiscoverResult) => number} [comparator] - Custom comparator. Defaults to priority desc + alphabetical tiebreak.
+ * @returns {DiscoverResult[]} New array sorted by the chosen comparator. Input is not mutated.
+ *
+ * @example
+ * import { sortModules } from "@cldmv/slothlet/helpers/module-sort";
+ *
+ * const sorted = sortModules(found);
+ * // Default: priority desc, then packageName asc.
+ *
+ * @example
+ * // Custom: alphabetical only.
+ * const alpha = sortModules(found, (a, b) => a.packageName.localeCompare(b.packageName));
+ *
+ * @example
+ * // Topological over manifest.dependencies (caller's responsibility to
+ * // implement; slothlet ships the plumbing, not the topo sort itself).
+ * const topo = sortModules(found, makeDependencyComparator(found));
+ */
+export function sortModules(results: DiscoverResult[], comparator?: (a: DiscoverResult, b: DiscoverResult) => number): DiscoverResult[];
+export type DiscoverResult = {
+    packageName: string;
+    packageRoot: string;
+    mountPath: string[];
+    apiDir: string;
+    manifest: object;
+};

package/types/stub/lib/helpers/observer-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 observer callbacks to the module that constructs 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 enableObserverPatching(): void;
+/**
+ * Restore the original observer constructors.
+ *
+ * Restores a constructor only when the wrapper installed here is still in place, so anything that
+ * replaced it afterwards keeps ownership of its own restore.
+ *
+ * @returns {void}
+ * @public
+ */
+export function disableObserverPatching(): void;

package/types/stub/lib/helpers/pattern-matcher.d.mts

@@ -1,3 +1,45 @@
 // 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/pattern-matcher";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Compile a glob pattern into a matcher function.
+ * Supports: * (any chars except .), ** (any chars including .), ? (single char),
+ * {a,b} brace expansion, !pattern negation
+ *
+ * @param {string} pattern - Glob pattern
+ * @param {object} [options={}] - Options
+ * @param {Function} [options.onMaxDepth] - Called when brace expansion exceeds max depth.
+ *   Should throw an error. If not provided, a SlothletError("BRACE_EXPANSION_MAX_DEPTH") is thrown.
+ * @returns {function} Matcher function that takes a path and returns boolean
+ * @example
+ * const matcher = compilePattern("payments.**");
+ * matcher("payments.charge"); // true
+ * matcher("admin.users");     // false
+ */
+export function compilePattern(pattern: string, options?: {
+    onMaxDepth?: Function | undefined;
+}): Function;
+/**
+ * Expand brace patterns {a,b,c} into multiple patterns.
+ * Supports nested braces with configurable depth limit.
+ *
+ * @param {string} pattern - Pattern with braces to expand
+ * @param {number} [depth=0] - Current recursion depth
+ * @param {number} [maxDepth=10] - Maximum nesting depth
+ * @param {object} [options={}] - Options
+ * @param {Function} [options.onMaxDepth] - Called when max depth exceeded. Should throw.
+ * @returns {string[]} Array of expanded patterns
+ * @example
+ * expandBraces("{a,b}.path"); // ["a.path", "b.path"]
+ */
+export function expandBraces(pattern: string, depth?: number, maxDepth?: number, options?: {
+    onMaxDepth?: Function | undefined;
+}): string[];
+/**
+ * Split brace alternatives on commas, respecting nested braces.
+ *
+ * @param {string} content - Content inside braces
+ * @returns {string[]} Array of alternatives
+ * @example
+ * splitBraceAlternatives("a,b,c"); // ["a", "b", "c"]
+ */
+export function splitBraceAlternatives(content: string): string[];

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

@@ -1,3 +1,112 @@
 // 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/platform";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /src/lib/helpers/platform.mjs
+ *	@Date: 2026-05-29 22:02:43 -07:00 (1780117363)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-06-03 21:17:59 -07:00 (1780546679)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+/**
+ * @fileoverview Single source of truth for Node.js-vs-browser host differences.
+ * @module @cldmv/slothlet/helpers/platform
+ * @internal
+ *
+ * @description
+ * Slothlet runs in two hosts: Node.js (full filesystem access) and browser /
+ * Electron-renderer "browser mode" (no `node:*` builtins, manifest-based loading).
+ * Rather than scatter `typeof process` checks and gated `await import("node:*")`
+ * blocks across a dozen modules (#123), every host difference is decided ONCE here
+ * and the rest of the codebase imports the resolved builtins (or browser shims)
+ * plus `isNode` via plain static imports — no `node:*` specifier ever enters the
+ * static-import graph a browser must parse.
+ *
+ * The builtins are pulled in through a single top-level-await `import()` block
+ * guarded by `isNode`. In a browser the same exports resolve to `null` (for the
+ * Node-only ones, whose every call site is `isNode`-guarded) or to a minimal shim
+ * (`util`, which is consumed in both hosts for `inspect` / `types.isProxy`).
+ *
+ * Anything that genuinely cannot run outside Node and is never reachable from a
+ * browser module graph (TypeScript compilation, type generation, manifest
+ * generation) keeps its own direct `node:*` imports — routing those through here
+ * would only drag build-time-only builtins (`crypto`, `os`) into the shared hub.
+ *
+ * ## Browser-only branches & coverage (policy)
+ * The browser arms here — and in the modules that import `isNode` (the `else`/`: null` shims, the
+ * i18n browser paths, the live-mode null-ALS arm) — are UNREACHABLE under the Node coverage run:
+ * `process.versions.node` is always truthy there, even in the `platform:"browser"` node-side suites.
+ *
+ * They are now genuinely covered+counted by a **vitest browser-mode** run (real headless Chromium,
+ * Playwright provider — `.configs/vitest.browser.config.mjs`, `tests/browser/*.browser.test.mjs`).
+ * Because that run uses the SAME `@vitest/coverage-v8` provider over vite-transformed source as the
+ * node run, the two `coverage-final.json` maps align and merge cleanly
+ * (`tools/coverage/merge-browser-coverage.mjs`, wired as `npm run coverage:all`). An earlier merge was
+ * rejected, but that was of the raw-source Playwright *smoke* (`npm run test:browser`), whose importmap
+ * serves raw `src/` — those maps don't align with node's. The vitest-browser run does, which is what
+ * makes the merge correct. Only arms unreachable in BOTH hosts (e.g. an exotic non-Node host with no
+ * `process`/`navigator`) keep a precise v8 ignore-next comment. The smoke remains as a raw-importmap
+ * load check (the path a real consumer uses), not the coverage justification.
+ */
+export const isNode: boolean;
+/**
+ * Resolved Node.js builtins (Node host) or browser shims / `null` (browser host).
+ *
+ * Each is initialized to `null` and reassigned to the real builtin inside the `isNode`
+ * block below; in a browser the Node-only ones stay `null` (every call site is
+ * `isNode`-guarded) and `util` becomes a minimal shim. Annotated `any` (not bare `null`,
+ * which would make a TS consumer treat them as non-callable, nor the precise
+ * `typeof import("node:*")` shape, which would force `@types/node` onto every consumer —
+ * including browser ones — and break the no-extra-types export contract). `any` keeps them
+ * usable from TS while the polymorphic real-module / shim / `null` behavior is documented here.
+ * @private
+ */
+/** @type {any} */
+export let fs: any;
+/** @type {any} */
+export let fsp: any;
+/** @type {any} */
+export let path: any;
+/** @type {any} */
+export let url: any;
+/** @type {any} */
+export let util: any;
+/** @type {any} */
+export let EventEmitter: any;
+/** @type {any} */
+export let AsyncLocalStorage: any;
+/** @type {any} */
+export let AsyncResource: any;
+/** @type {any} */
+export let createRequire: any;
+/**
+ * Load and parse JSON, branching on host — this is the single place that knows how each
+ * environment reads JSON.
+ *
+ * @description
+ * - **Node**: synchronous `fs.readFileSync` + parse. Returns the parsed object directly (or
+ *   `null` on a read/parse failure). `ref` is a filesystem path or `file:` URL.
+ * - **Browser**: asynchronous dynamic `import(ref, { with: { type: "json" } })`. Returns a
+ *   `Promise<object|null>` — a miss resolves to `null` (callers keep their bundled default;
+ *   a failed import also surfaces a console error, which is harmless). `ref` is a module
+ *   specifier resolvable via the page's importmap (e.g. `@cldmv/slothlet/i18n/language/es-mx.json`).
+ *
+ * The return type is therefore polymorphic by host: `object|null` in Node, `Promise<object|null>`
+ * in a browser. Callers that already branch on `isNode` consume the matching form directly;
+ * `await loadJson(...)` is safe in both (awaiting a non-promise is a no-op).
+ *
+ * @param {string} ref - Filesystem path / `file:` URL (Node) or importmap specifier (browser).
+ * @returns {object|null|Promise<object|null>} Parsed JSON (Node, sync) or a promise of it (browser).
+ * @internal
+ *
+ * @example
+ * // Node (sync):
+ * const pkg = loadJson(new URL("../../package.json", import.meta.url));
+ * // Browser (async):
+ * const es = await loadJson("@cldmv/slothlet/i18n/language/es-mx.json");
+ */
+export function loadJson(ref: string): object | null | Promise<object | null>;

package/types/stub/lib/helpers/resolve-from-caller.d.mts

@@ -1,3 +1,34 @@
 // 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/resolve-from-caller";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Path resolver component
+ * @class Resolver
+ * @extends ComponentBase
+ * @package
+ */
+export class Resolver extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Get V8 stack trace as CallSite array.
+     * @param {Function} [skipFn] - Optional function to skip from stack trace
+     * @returns {Array} Array of CallSite objects
+     * @public
+     */
+    public getStack(skipFn?: Function): any[];
+    /**
+     * Convert file:// URL to filesystem path or return as-is.
+     * @param {any} v - Value to convert
+     * @returns {string|null} Filesystem path or null
+     * @public
+     */
+    public toFsPath(v: any): string | null;
+    /**
+     * Resolve relative path from caller's context.
+     * @param {string} rel - Relative path to resolve
+     * @returns {string} Absolute filesystem path
+     * @public
+     */
+    public resolvePathFromCaller(rel: string): string;
+    #private;
+}
+import { ComponentBase } from "#factories/component-base";

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

@@ -1,3 +1,24 @@
 // 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/scheduler-context";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Pin deferred callbacks to the module that schedules them.
+ *
+ * Called once globally when the first instance is created; later calls are ignored, matching how
+ * EventEmitter patching behaves. Costs nothing when no runtime registered a pinning strategy — the
+ * wrapper hands the callback straight through.
+ *
+ * @returns {void}
+ * @public
+ */
+export function enableSchedulerPatching(): void;
+/**
+ * Restore the original scheduler entry points.
+ *
+ * Restores an entry point only when the wrapper installed here is still the one in place. Anything
+ * that replaced a scheduler afterwards — a test runner's fake timers being the usual case — owns that
+ * slot and its own restore, and writing over it would strand the process on a stale function.
+ *
+ * @returns {void}
+ * @public
+ */
+export function disableSchedulerPatching(): void;