@cldmv/slothlet-types 3.15.3 → 3.16.1

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

@@ -1,12 +1,179 @@
-export function collectPackageSpecifiers(packageRoot: any): Promise<Map<any, any>>;
-export function collectSlothletSpecifiers(root: any): Promise<Set<string>>;
-export function generateBrowserAssets(apiDir: any, options?: {}): Promise<{
-    manifest: any;
+/**
+ * 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: {};
+        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: {};
+    imports: {
+        [x: string]: string;
+    };
 }>;
-export function generateManifest(dir: any): Promise<any>;
+/**
+ * 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>>;

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

@@ -1,6 +1,26 @@
+/**
+ * Hint detection for providing helpful error hints
+ * @class HintDetector
+ * @extends ComponentBase
+ * @package
+ */
 export class HintDetector extends ComponentBase {
     static slothletProperty: string;
-    detectHint(error: any, errorCode: any): 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;
 }
-export function detectHint(error: any, errorCode: any): 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
+ */
+export function detectHint(error: Error, errorCode: string): string | undefined;
 import { ComponentBase } from "#factories/component-base";

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

@@ -1 +1,100 @@
-export function createManifestResolver(base: any): (entry: any) => string;
+/**
+ *	@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/lib/helpers/modes-utils.d.mts

@@ -1,7 +1,34 @@
+/**
+ * Mode processing utilities component class
+ * @extends ComponentBase
+ */
 export class ModesUtils extends ComponentBase {
     static slothletProperty: string;
-    ensureNamedExportFunction(fn: any, ____nameHint: any): any;
-    cloneWrapperImpl(value: any, mode: any): any;
-    getOwnershipCollisionMode(config: any, collisionContext?: string): any;
+    /**
+     * 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/lib/helpers/module-discovery.d.mts

@@ -1,7 +1,80 @@
-export function discoverModules(options?: {}): Promise<Readonly<{
-    packageName: any;
-    packageRoot: any;
-    mountPath: readonly any[];
-    apiDir: any;
-    manifest: any;
-}>[]>;
+/**
+ * @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/lib/helpers/module-manifest-validator.d.mts

@@ -1,13 +1,36 @@
-export function validateModuleManifest(manifest: any, packageContext: any): {
-    schemaVersion: number;
-    name: any;
-    version: any;
-    description: any;
-    mountPath: any[];
-    apiDir: any;
-    kind: any;
-    priority: any;
-    dependencies: any;
-    permissions: any;
-    metadata: any;
-};
+/**
+ * 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/lib/helpers/module-sort.d.mts

@@ -1 +1,64 @@
-export function sortModules(results: any, comparator: any): any[];
+/**
+ *	@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/lib/helpers/observer-context.d.mts

@@ -0,0 +1,21 @@
+/**
+ * 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/lib/helpers/pattern-matcher.d.mts

@@ -1,3 +1,43 @@
-export function compilePattern(pattern: any, options?: {}): any;
-export function expandBraces(pattern: any, depth?: number, maxDepth?: number, options?: {}): any;
-export function splitBraceAlternatives(content: any): string[];
+/**
+ * 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[];