@cldmv/slothlet 3.15.2 → 3.16.0

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

@@ -1,3 +1,58 @@
 // 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/utilities";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * General utility functions
+ * @class Utilities
+ * @extends ComponentBase
+ * @package
+ */
+export class Utilities extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Check if value is a plain object
+     * @param {*} obj - Value to check
+     * @returns {boolean} True if plain object
+     * @public
+     */
+    public isPlainObject(obj: any): boolean;
+    /**
+     * Deep merge two plain objects recursively.
+     *
+     * Differences from a simple spread:
+     * - Recursively merges nested plain objects rather than replacing them.
+     * - Uses `hasOwnProperty` to skip prototype-chain keys (no prototype pollution).
+     * - Non-plain values (arrays, class instances, primitives) are always copied by
+     *   value from `source`, never merged.
+     * - When `source[key]` is a plain object but `target[key]` is not (or absent),
+     *   the merge starts from `{}` so the returned sub-tree is always a fresh copy.
+     * - If either top-level argument is not a plain object, returns `source` as-is.
+     *
+     * @param {unknown} target - Base object (not mutated).
+     * @param {unknown} source - Source object whose keys are merged in.
+     * @returns {unknown} New merged object, or `source` as-is if either argument is not a plain object.
+     * @public
+     */
+    public deepMerge(target: unknown, source: unknown): unknown;
+    /**
+     * Deep clone a value, handling Proxy objects and functions that `structuredClone`
+     * cannot serialise.
+     *
+     * Strategy:
+     * 1. Try `structuredClone` — fast and spec-correct for plain data.
+     * 2. Fall back to a manual recursive copy for Proxies, callables, and other
+     *    non-serialisable objects; errors on individual property clones are swallowed
+     *    and the original reference is retained for that key.
+     *
+     * @param {unknown} obj - Value to clone.
+     * @returns {unknown} Deep clone of `obj`.
+     * @public
+     */
+    public deepClone(obj: unknown): unknown;
+    /**
+     * Generate unique ID
+     * @returns {string} Unique identifier
+     * @public
+     */
+    public generateId(): string;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/i18n/translations.d.mts

@@ -1,3 +1,53 @@
 // 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/i18n";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Set current language (synchronous)
+ * Merges requested language translations over default English translations
+ * @param {string} lang - Language code
+ * @public
+ */
+export function setLanguage(lang: string): void;
+/**
+ * Set the current language asynchronously — the browser-capable path.
+ *
+ * @description
+ * Mirrors {@link setLanguage}, but awaits the locale load so it works in a browser, where locales
+ * arrive via dynamic `import(…, { with: { type: "json" } })` rather than the filesystem. In Node it
+ * awaits the same synchronous read (the await is a no-op). A failed load warns and keeps the bundled
+ * English default. Use this when you need to *await* a locale switch (e.g. in an Electron renderer).
+ * @param {string} lang - Language code (e.g. "es-mx").
+ * @returns {Promise<void>}
+ * @public
+ */
+export function setLanguageAsync(lang: string): Promise<void>;
+/**
+ * Get current language
+ * @returns {string} Language code
+ * @public
+ */
+export function getLanguage(): string;
+/**
+ * Translate error message with interpolation
+ * @param {string} errorCode - Error code
+ * @param {Object} params - Parameters for interpolation
+ * @returns {string} Translated message
+ * @public
+ */
+export function translate(errorCode: string, params?: Object): string;
+/**
+ * Initialize i18n system (synchronous)
+ * @param {Object} options - Options
+ * @param {string} [options.language] - Language code (auto-detect if not provided)
+ * @public
+ */
+export function initI18n(options?: {
+    language?: string | undefined;
+}): void;
+/**
+ * Translate error message with interpolation
+ * @param {string} errorCode - Error code
+ * @param {Object} params - Parameters for interpolation
+ * @returns {string} Translated message
+ * @public
+ */
+export function t(errorCode: string, params?: Object): string;

package/types/stub/lib/modes/eager.d.mts

@@ -1,3 +1,57 @@
 // 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/modes/eager";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Eager mode component - builds APIs by loading all modules immediately.
+ * @class EagerMode
+ * @extends ComponentBase
+ * @package
+ */
+export class EagerMode extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Create EagerMode instance.
+     * @param {object} slothlet - Slothlet orchestrator instance.
+     * @package
+     */
+    constructor(slothlet: object);
+    /**
+     * Build API in eager mode (load all modules immediately).
+     * @param {Object} options - Build options
+     * @param {string} options.dir - Directory path to load from
+     * @param {string} [options.apiPathPrefix=""] - Prefix for API paths
+     * @param {string} [options.collisionContext="initial"] - Collision context
+     * @param {string|null} [options.collisionMode=null] - Per-call collision mode override (e.g. from `api.add()`'s `forceOverwrite`) — see `lazy.mjs`'s identical parameter
+     * @param {string} [options.moduleID] - Module ID
+     * @param {number} [options.apiDepth=DEFAULT_API_DEPTH] - Maximum directory depth ({@link DEFAULT_API_DEPTH})
+     * @param {string|null} [options.cacheBust=null] - Cache-busting value
+     * @param {Function|null} [options.fileFilter=null] - Optional filter (fileName) => boolean
+     * @param {string|string[]|null} [options.hidden=null] - Glob(s) hiding files/folders, matched against each entry's path relative to the API root
+     * @param {boolean} [options.scanHiddenFolders=false] - Deprecated: restore the pre-v3.11 scanning of `.`/`__`-prefixed folders
+     * @param {Object|null} [options.preloadedStructure=null] - Pre-built `{ files, directories }` structure
+     *   to use instead of scanning `dir` (synthetic / in-memory build, #117). Each synthetic file entry
+     *   carries its exports directly so no module is loaded from disk.
+     * @param {boolean} [options.rootUnwrap=false] - The mount exposes the single root entry's exports
+     *   directly at the mount path (a single-file or synthetic `api.add()`), so that entry creates no api
+     *   level and must contribute no path segment either.
+     * @returns {Promise<Object>} Built API object
+     * @public
+     *
+     * @example
+     * const api = await slothlet.modes.eager.buildAPI({ dir: "./api", moduleID: "base" });
+     */
+    public buildAPI({ dir, apiPathPrefix, collisionContext, collisionMode, moduleID, apiDepth, cacheBust, fileFilter, hidden, scanHiddenFolders, preloadedStructure, rootUnwrap }: {
+        dir: string;
+        apiPathPrefix?: string | undefined;
+        collisionContext?: string | undefined;
+        collisionMode?: string | null | undefined;
+        moduleID?: string | undefined;
+        apiDepth?: number | undefined;
+        cacheBust?: string | null | undefined;
+        fileFilter?: Function | null | undefined;
+        hidden?: string | string[] | null | undefined;
+        scanHiddenFolders?: boolean | undefined;
+        preloadedStructure?: Object | null | undefined;
+        rootUnwrap?: boolean | undefined;
+    }): Promise<Object>;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/modes/lazy.d.mts

@@ -1,3 +1,68 @@
 // 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/modes/lazy";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Lazy mode component - builds APIs with deferred (on-demand) loading.
+ * @class LazyMode
+ * @extends ComponentBase
+ * @package
+ */
+export class LazyMode extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Create LazyMode instance.
+     * @param {object} slothlet - Slothlet orchestrator instance.
+     * @package
+     */
+    constructor(slothlet: object);
+    /**
+     * Create a named async materialization function for lazy subdirectories.
+     * @param {string} apiPath - API path to derive the function name from.
+     * @param {Function} handler - Async handler that performs materialization.
+     * @returns {Function} Named async materialization function.
+     * @public
+     *
+     * @example
+     * const fn = lazyMode.createNamedMaterializeFunc('api.math', async () => ({ add: (a,b) => a+b }));
+     */
+    public createNamedMaterializeFunc(apiPath: string, handler: Function): Function;
+    /**
+     * Build API in lazy mode (proxy-based deferred loading).
+     * @param {Object} options - Build options
+     * @param {string} options.dir - Directory to build from
+     * @param {string} [options.apiPathPrefix=""] - Prefix for API paths
+     * @param {string} [options.collisionContext="initial"] - Collision context
+     * @param {string|null} [options.collisionMode=null] - Collision mode override from api.add()
+     * @param {string} [options.moduleID] - Module ID
+     * @param {number} [options.apiDepth=DEFAULT_API_DEPTH] - Maximum directory depth ({@link DEFAULT_API_DEPTH})
+     * @param {string|null} [options.cacheBust=null] - Cache-busting value
+     * @param {Function|null} [options.fileFilter=null] - Optional filter (fileName) => boolean
+     * @param {string|string[]|null} [options.hidden=null] - Glob(s) hiding files/folders, matched against each entry's path relative to the API root
+     * @param {boolean} [options.scanHiddenFolders=false] - Deprecated: restore the pre-v3.11 scanning of `.`/`__`-prefixed folders
+     * @param {Object|null} [options.preloadedStructure=null] - Pre-built `{ files, directories }` structure
+     *   to use instead of scanning `dir` (synthetic / in-memory build, #117). Each synthetic file entry
+     *   carries its exports directly so no module is loaded from disk.
+     * @param {boolean} [options.rootUnwrap=false] - The mount exposes the single root entry's exports
+     *   directly at the mount path (a single-file or synthetic `api.add()`), so that entry creates no api
+     *   level and must contribute no path segment either.
+     * @returns {Promise<Object>} Built API object with lazy proxies
+     * @public
+     *
+     * @example
+     * const api = await slothlet.modes.lazy.buildAPI({ dir: "./api", moduleID: "base" });
+     */
+    public buildAPI({ dir, apiPathPrefix, collisionContext, collisionMode, moduleID, apiDepth, cacheBust, fileFilter, hidden, scanHiddenFolders, preloadedStructure, rootUnwrap }: {
+        dir: string;
+        apiPathPrefix?: string | undefined;
+        collisionContext?: string | undefined;
+        collisionMode?: string | null | undefined;
+        moduleID?: string | undefined;
+        apiDepth?: number | undefined;
+        cacheBust?: string | null | undefined;
+        fileFilter?: Function | null | undefined;
+        hidden?: string | string[] | null | undefined;
+        scanHiddenFolders?: boolean | undefined;
+        preloadedStructure?: Object | null | undefined;
+        rootUnwrap?: boolean | undefined;
+    }): Promise<Object>;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/processors/flatten.d.mts

@@ -1,3 +1,124 @@
 // 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/processors/flatten";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Flattening decision processor
+ * @class Flatten
+ * @extends ComponentBase
+ * @package
+ */
+export class Flatten extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Create a Flatten instance
+     * @param {Object} slothlet - Slothlet instance
+     */
+    constructor(slothlet: Object);
+    /**
+     * Core flattening decision function.
+     * Implements conditions C01-C07 from getFlatteningDecision().
+     * @param {object} options - Decision options
+     * @param {object} options.mod - Module exports
+     * @param {string} options.moduleName - Sanitized module name
+     * @param {string} options.categoryName - Category/folder name
+     * @param {object} options.analysis - Export analysis
+     * @param {boolean} options.hasMultipleDefaults - Multiple defaults in folder
+     * @param {string[]} options.moduleKeys - Keys from module
+     * @param {function} options.t - Translation function
+     * @returns {Promise<object>} Flattening decision
+     * @public
+     */
+    public getFlatteningDecision(options: {
+        mod: object;
+        moduleName: string;
+        categoryName: string;
+        analysis: object;
+        hasMultipleDefaults: boolean;
+        moduleKeys: string[];
+        t: Function;
+    }): Promise<object>;
+    /**
+     * Build module content for API assignment.
+     *
+     * Canonical implementation of the C08-C09b content-building rules, including
+     * AddApi detection and collision handling. Previously this logic was inlined
+     * inside modes-processor.mjs; it now lives here so the processor stays focused
+     * on wrapping and assignment concerns only.
+     *
+     * Collision config, modesUtils helpers, and SlothletWarning are accessed
+     * directly through {@link this.slothlet} / {@link this.slothlet.config} — no caller
+     * plumbing required.
+     *
+     * @param {object}   options                              - Processing options.
+     * @param {object}   options.mod                         - Module exports.
+     * @param {object}   options.decision                    - Flattening decision from getFlatteningDecision.
+     * @param {string}   options.moduleName                  - Sanitized module name (used for C08 auto-flatten key lookup).
+     * @param {string}   options.propertyName                - Resolved preferred name (decision.preferredName || moduleName).
+     * @param {string[]} options.moduleKeys                  - Named export keys (excluding "default").
+     * @param {object}   options.analysis                    - { hasDefault, hasNamed, defaultExportType }.
+     * @param {object}   [options.file=null]                 - File descriptor for AddApi detection via file.name / file.fullName.
+     * @param {string}   [options.collisionContext="initial"] - Collision context ("initial" | "api").
+     * @param {string}   [options.apiPathPrefix=""]          - API path prefix for collision error messages.
+     * @param {string|null} [options.collisionModeOverride=null] - Caller's per-call override (e.g.
+     *   `api.add({ forceOverwrite: true })`), preferred over `collisionContext`'s config default for
+     *   the function-default-vs-named-export merge decision below.
+     * @returns {{ moduleContent: object|Function }} Built module content ready for wrapping/assignment.
+     * @public
+     */
+    public processModuleForAPI(options: {
+        mod: object;
+        decision: object;
+        moduleName: string;
+        propertyName: string;
+        moduleKeys: string[];
+        analysis: object;
+        file?: object | undefined;
+        collisionContext?: string | undefined;
+        apiPathPrefix?: string | undefined;
+        collisionModeOverride?: string | null | undefined;
+    }): {
+        moduleContent: object | Function;
+    };
+    /**
+     * Build category-level flattening decisions.
+     * Implements conditions C10-C33 from buildCategoryDecisions().
+     * @param {object} options - Category options
+     * @param {string} options.categoryName - Category name
+     * @param {object} options.mod - Module exports
+     * @param {string} options.moduleName - Module name
+     * @param {string} options.fileBaseName - File base name
+     * @param {object} options.analysis - Export analysis
+     * @param {string[]} options.moduleKeys - Module keys
+     * @param {number} options.currentDepth - Current depth
+     * @param {unknown[]} options.moduleFiles - Files in category
+     * @param {function} options.t - Translation function
+     * @returns {Promise<object>} Category decision
+     * @public
+     */
+    public buildCategoryDecisions(options: {
+        categoryName: string;
+        mod: object;
+        moduleName: string;
+        fileBaseName: string;
+        analysis: object;
+        moduleKeys: string[];
+        currentDepth: number;
+        moduleFiles: unknown[];
+        t: Function;
+    }): Promise<object>;
+    /**
+     * Decide whether a named export should be attached to a callable default export.
+     *
+     * Returns false when the named export is the same reference as the default (re-export
+     * pattern), or when the export key matches the function name (self-referential export).
+     *
+     * @param {string} key - Named export key.
+     * @param {unknown} value - Named export value.
+     * @param {Function} defaultFunc - Wrapped callable default export.
+     * @param {Function} originalDefault - Original default export.
+     * @returns {boolean} True if the export should be attached.
+     * @public
+     */
+    public shouldAttachNamedExport(key: string, value: unknown, defaultFunc: Function, originalDefault: Function): boolean;
+    #private;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/processors/loader.d.mts

@@ -1,3 +1,84 @@
 // 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/processors/loader";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Warns when a coverage run will silently misattribute the consumer's leaf coverage (#235).
+ *
+ * @param {object} config - The instance's transformed config.
+ * @param {object} [overrides] - Environment inputs, injectable for tests.
+ * @param {object|undefined} [overrides.worker] - The vitest worker global, when present.
+ * @param {boolean} [overrides.externalized] - Whether this slothlet copy is outside the runner's
+ *   module graph.
+ * @returns {boolean} True when the warning was emitted.
+ * @package
+ *
+ * @description
+ * Fires only when every condition of the misattribution scenario holds: a vitest COVERAGE run is
+ * active (`__vitest_worker__.config.coverage.enabled` — a plain test run stays silent), this
+ * slothlet copy is EXTERNALIZED (an inlined copy attributes fine), no `import` importer is
+ * configured (the fix), and the instance is not `silent`. The worker global is vitest-internal,
+ * so it is read defensively — its absence or a shape change simply means no hint, never a wrong
+ * one. Detection cannot DO the fix: the importer must be a closure authored in the consumer's own
+ * transformed code, which is why this is a pointer to docs/TESTING.md rather than an auto-enable.
+ */
+export function warnIfCoverageWithoutImporter(config: object, { worker, externalized }?: {
+    worker?: object | undefined;
+    externalized?: boolean | undefined;
+}): boolean;
+/**
+ * Loader component for module loading, directory scanning, and API merging
+ * @class Loader
+ * @extends ComponentBase
+ * @package
+ */
+export class Loader extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Create a Loader instance.
+     * @param {object} slothlet - Slothlet class instance.
+     * @package
+     */
+    constructor(slothlet: object);
+    /**
+     * Load a single module
+     * @param {string} filePath - Path to module file
+     * @param {string} [instanceID] - Slothlet instance ID for cache busting
+     * @param {string} [moduleID] - Module ID for additional cache busting (used in api.slothlet.api.add)
+     * @param {number|null} [cacheBust=null] - Timestamp for reload cache busting (forces fresh import)
+     * @returns {Promise<Object>} Loaded module
+     * @public
+     */
+    public loadModule(filePath: string, instanceID?: string, moduleID?: string, cacheBust?: number | null): Promise<Object>;
+    /**
+     * Scan directory for module files
+     * @param {string} dir - Directory to scan
+     * @param {Object} [options={}] - Scan options
+     * @param {boolean} [options.isRootScan=true] - Whether this is the root directory scan (shows empty dir warning)
+     * @param {number} [options.currentDepth=0] - Current traversal depth
+     * @param {number} [options.maxDepth=DEFAULT_API_DEPTH] - Maximum traversal depth ({@link DEFAULT_API_DEPTH})
+     * @param {Function|null} [options.fileFilter=null] - Optional filter function (fileName) => boolean to load specific files only
+     * @param {string|string[]|Function|null} [options.hidden=null] - Glob(s) hiding files/folders, matched against each entry's
+     *   path relative to the API root (extension-stripped for files). Internal recursion passes the compiled matcher function.
+     * @param {boolean} [options.scanHiddenFolders=false] - Deprecated: restore the pre-v3.11 scanning of `.`/`__`-prefixed folders.
+     * @param {string} [options.rootDir] - API root the relative hidden-glob paths are computed from (defaults to the scanned dir).
+     * @returns {Promise<Object>} Directory structure
+     * @public
+     */
+    public scanDirectory(dir: string, options?: {
+        isRootScan?: boolean | undefined;
+        currentDepth?: number | undefined;
+        maxDepth?: number | undefined;
+        fileFilter?: Function | null | undefined;
+        hidden?: string | Function | string[] | null | undefined;
+        scanHiddenFolders?: boolean | undefined;
+        rootDir?: string | undefined;
+    }): Promise<Object>;
+    /**
+     * Extract exports from module
+     * @param {Object} module - Loaded module
+     * @returns {Object} Extracted exports
+     * @public
+     */
+    public extractExports(module: Object): Object;
+    #private;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/processors/type-generator.d.mts

@@ -1,3 +1,20 @@
 // 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/processors/type-generator";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Generate TypeScript declaration file for a Slothlet API
+ * @param {object} api - The loaded Slothlet API
+ * @param {object} options - Generation options
+ * @param {string} options.output - Output file path for .d.ts
+ * @param {string} options.interfaceName - Name of the interface to generate
+ * @param {boolean} [options.includeDocumentation=true] - Include JSDoc comments
+ * @returns {Promise<{output: string, filePath: string}>} Generated declaration and output path
+ * @public
+ */
+export function generateTypes(api: object, options: {
+    output: string;
+    interfaceName: string;
+    includeDocumentation?: boolean | undefined;
+}): Promise<{
+    output: string;
+    filePath: string;
+}>;

package/types/stub/lib/processors/typescript.d.mts

@@ -1,3 +1,175 @@
 // 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/processors/typescript";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Transform TypeScript code to JavaScript using esbuild
+ * @param {string} filePath - Path to the TypeScript file
+ * @param {object} [options={}] - esbuild transform options
+ * @param {string} [options.target] - ECMAScript target version (default: "es2020")
+ * @param {string} [options.format] - Module format (default: "esm")
+ * @param {boolean} [options.sourcemap] - Generate source maps (default: false)
+ * @returns {Promise<string>} Transformed JavaScript code
+ * @throws {SlothletError} If transformation fails
+ * @public
+ */
+export function transformTypeScript(filePath: string, options?: {
+    target?: string | undefined;
+    format?: string | undefined;
+    sourcemap?: boolean | undefined;
+}): Promise<string>;
+/**
+ * Create a data URL for dynamic import with cache busting
+ * @param {string} code - JavaScript code to encode
+ * @returns {string} Data URL suitable for dynamic import
+ * @public
+ */
+export function createDataUrl(code: string): string;
+/**
+ * Resolve the on-disk file a relative specifier targets and classify it as a
+ * TypeScript source or not.
+ *
+ * Besides the literal path, this probes the TypeScript source-extension
+ * convention: a specifier may name a `.mjs` / `.js` file (or omit the
+ * extension) while the file on disk is the corresponding `.mts` / `.ts`
+ * source. Whichever form exists wins.
+ * @param {string} absoluteTarget - Absolute path the specifier resolves to, as written
+ * @returns {{ path: string, isTS: boolean }} The resolved file and whether it is a `.ts`/`.mts` source
+ * @private
+ */
+export function resolveModuleFile(absoluteTarget: string): {
+    path: string;
+    isTS: boolean;
+};
+/**
+ * Mark every character index that falls inside a string literal, template
+ * literal, comment, or regular-expression literal, so the specifier rewrite can
+ * skip `import`/`from` text that is not actually part of an import statement
+ * (e.g. `const s = "import('./x')"`).
+ *
+ * Template literals are masked whole — opening backtick to closing backtick,
+ * including any `${…}` interpolations — so a relative dynamic `import()` inside
+ * a template interpolation is left un-rewritten rather than risk a false
+ * rewrite; nested template literals are not deeply parsed.
+ *
+ * Regex literals are masked whole as well: their bodies can contain text shaped
+ * like a line- or block-comment delimiter (`/\/\//`), and without regex
+ * awareness the scanner would mis-read that as a comment and mask the rest of
+ * the line — silently suppressing a real `import()` later on the same line. A
+ * `/` is read as a regex when the previous significant token expects an
+ * expression (start of input, an operator, `(`/`{`/`}`/`,`/`;`/`:`, or a
+ * {@link REGEX_PRECEDING_KEYWORDS} keyword) and as division otherwise. The one
+ * imperfect case is a `/` directly after the `)` of an `if`/`for`/`while`
+ * header — treated as division — an accepted limit of this lightweight scan.
+ * @param {string} code - JavaScript source to scan
+ * @returns {Uint8Array} `1` at indices inside a string/template/comment/regex, `0` elsewhere
+ * @private
+ */
+export function maskStringsAndComments(code: string): Uint8Array;
+/**
+ * Rewrite relative `import`/`export` specifiers in transformed TS output.
+ *
+ * Transformed TS modules are written to (and imported from) a cache file under
+ * `.slothlet-cache/…`, which is not co-located with the original source.
+ * esbuild and tsc transform the code but never rewrite specifiers, so a
+ * relative specifier (`./sibling.mjs`, `../shared/util.mjs`) left as-is would
+ * resolve against the cache directory and fail with `Cannot find module`.
+ *
+ * Each relative specifier is resolved against the original source directory
+ * and handed to `resolve`, which returns its replacement. The default `resolve`
+ * emits an absolute `file://` URL at the source location — correct for plain
+ * `.mjs`/`.cjs`/`.js` targets. {@link writeTransformedToCache} passes a `resolve`
+ * that additionally points relative `.ts`/`.mts` targets at their transpiled
+ * cache files. Bare specifiers (`@cldmv/slothlet/runtime`, npm packages) and
+ * absolute URLs are never touched.
+ *
+ * Matches inside a string literal or comment are skipped via
+ * {@link maskStringsAndComments}, so import-shaped text in string data or
+ * comments is never mutated.
+ *
+ * Covered statement forms: static `import`/`export … from` declarations
+ * (including multi-line binding lists and `export *`), bare side-effect
+ * `import "…"`, and dynamic `import("…")` with a static string literal.
+ * Whitespace and comments between the tokens of these forms — including
+ * between `from`/`import` and the module string — are tolerated.
+ * @param {string} code - Transformed JavaScript (ESM) code
+ * @param {string} sourcePath - Absolute path to the original .ts/.mts source
+ * @param {(absoluteTarget: string, suffix: string, specifier: string) => string} [resolve]
+ *   - Maps a relative specifier to its replacement. Receives the absolute path the
+ *   specifier resolves to, any `?query`/`#hash` suffix, and the original specifier
+ *   text. Defaults to an absolute `file://` URL anchored at the source directory.
+ * @returns {string} Code with relative specifiers rewritten
+ * @private
+ */
+export function rewriteRelativeSpecifiers(code: string, sourcePath: string, resolve?: (absoluteTarget: string, suffix: string, specifier: string) => string): string;
+/**
+ * Write transformed TS output — and the transitive graph of `.ts`/`.mts` files
+ * it relatively imports — to content-hashed cache files inside the project,
+ * returning the entry module's `file://` URL.
+ *
+ * The cache file is not co-located with the source, so every relative specifier
+ * is rewritten by {@link rewriteRelativeSpecifiers}:
+ *
+ * - **Bare specifiers** (`@cldmv/slothlet/runtime`, npm packages) resolve
+ *   normally — the cache lives inside the project tree, so Node walks up to
+ *   `node_modules` as usual. They are left untouched.
+ * - **Relative imports of plain `.mjs`/`.cjs`/`.js` files** are rewritten to an
+ *   absolute `file://` URL at the original source location.
+ * - **Relative imports of other `.ts`/`.mts` files** are followed: when a
+ *   `transform` callback is supplied, each dependency is transpiled and cached
+ *   too, and the importing specifier is rewritten to the dependency's cache
+ *   file. Import cycles are handled. Without `transform`, a relative `.ts`/`.mts`
+ *   target is left at its source path (and will not load).
+ *
+ * Each cache file is named by a hash over the absolute source paths and
+ * transpiled code of its whole relative-`.ts`/`.mts` closure, so editing any
+ * file in the graph produces fresh URLs for every importer — a reload never
+ * serves stale linked output.
+ *
+ * Cache lives at `<projectRoot>/.slothlet-cache/<pid>-<instanceID>/<hash>.mjs` —
+ * deliberately OUTSIDE `node_modules/` because Node's `READ_PACKAGE_SCOPE` halts
+ * at a `node_modules` segment and would otherwise break self-reference resolution
+ * (needed when slothlet runs inside its own repo / monorepo workspace, where no
+ * `node_modules/@cldmv/slothlet` exists). The `<pid>-` prefix lets the startup
+ * sweep detect orphaned dirs (owner PID gone) without touching live ones.
+ * @param {string} originalPath - Path to the original .ts/.mts source (relative or absolute; normalized internally)
+ * @param {string} code - Transformed JavaScript code for `originalPath`
+ * @param {string} instanceID - Slothlet instance ID (used as cache namespace)
+ * @param {(filePath: string) => Promise<string>} [transform] - Transpiles a `.ts`/`.mts`
+ *   file to JavaScript; enables following relative `.ts`/`.mts` imports.
+ * @returns {Promise<{url: string, cacheDir: string}>} Entry file URL and the cache directory for this instance
+ * @public
+ */
+export function writeTransformedToCache(originalPath: string, code: string, instanceID: string, transform?: (filePath: string) => Promise<string>): Promise<{
+    url: string;
+    cacheDir: string;
+}>;
+/**
+ * Transform TypeScript code to JavaScript using tsc with type checking
+ * @param {string} filePath - Path to the TypeScript file
+ * @param {object} [options={}] - TypeScript compiler options
+ * @param {string} [options.target] - ECMAScript target version (default: "ES2020")
+ * @param {string} [options.module] - Module format (default: "ESNext")
+ * @param {boolean} [options.strict] - Enable strict type checking (default: true)
+ * @param {boolean} [options.skipTypeCheck] - Skip type checking and only transform (default: false)
+ * @param {string} [options.typeDefinitionPath] - Path to .d.ts file for type checking
+ * @returns {Promise<{code: string, diagnostics: object[]}>} Transformed code and type diagnostics
+ * @throws {SlothletError} If transformation fails
+ * @public
+ */
+export function transformTypeScriptStrict(filePath: string, options?: {
+    target?: string | undefined;
+    module?: string | undefined;
+    strict?: boolean | undefined;
+    skipTypeCheck?: boolean | undefined;
+    typeDefinitionPath?: string | undefined;
+}): Promise<{
+    code: string;
+    diagnostics: object[];
+}>;
+/**
+ * Format TypeScript diagnostics into readable error messages
+ * @param {object[]} diagnostics - TypeScript diagnostic objects
+ * @param {object} ts - TypeScript module instance
+ * @returns {string[]} Array of formatted error messages
+ * @public
+ */
+export function formatDiagnostics(diagnostics: object[], ts: object): string[];