@cldmv/slothlet-types 3.15.3 → 3.16.1

package/lib/processors/flatten.d.mts

@@ -1,62 +1,122 @@
+/**
+ * Flattening decision processor
+ * @class Flatten
+ * @extends ComponentBase
+ * @package
+ */
 export class Flatten extends ComponentBase {
     static slothletProperty: string;
-    getFlatteningDecision(options: any): Promise<{
-        preserveAsNamespace: boolean;
-        reason: any;
-        flattenToRoot?: undefined;
-    } | {
-        flattenToRoot: boolean;
-        reason: any;
-        preserveAsNamespace?: undefined;
-    } | {
-        flattenToCategory: boolean;
-        flattenType: string;
-        reason: any;
-        useAutoFlattening?: undefined;
-        preserveAsNamespace?: undefined;
-        preferredName?: undefined;
-    } | {
-        useAutoFlattening: boolean;
-        reason: any;
-        flattenToCategory?: undefined;
-        flattenType?: undefined;
-        preserveAsNamespace?: undefined;
-        preferredName?: undefined;
-    } | {
-        flattenToCategory: boolean;
-        reason: any;
-        flattenType?: undefined;
-        useAutoFlattening?: undefined;
-        preserveAsNamespace?: undefined;
-        preferredName?: undefined;
-    } | {
-        preserveAsNamespace: boolean;
-        preferredName: any;
-        reason: any;
-        flattenToCategory?: undefined;
-        flattenType?: undefined;
-        useAutoFlattening?: undefined;
-    }>;
-    processModuleForAPI(options: any): {
-        moduleContent: any;
+    /**
+     * 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;
     };
-    buildCategoryDecisions(options: any): Promise<{
-        shouldFlatten: boolean;
-        flattenType: string;
-        reason: any;
-        preferredName?: undefined;
-    } | {
-        shouldFlatten: boolean;
-        flattenType: string;
-        preferredName: any;
-        reason: any;
-    } | {
-        shouldFlatten: boolean;
-        preferredName: any;
-        reason: any;
-        flattenType?: undefined;
-    }>;
-    shouldAttachNamedExport(key: any, value: any, defaultFunc: any, originalDefault: any): boolean;
+    /**
+     * 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/lib/processors/loader.d.mts

@@ -1,15 +1,82 @@
+/**
+ * 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;
-    loadModule(filePath: any, instanceID: any, moduleID: any, cacheBust?: null): Promise<any>;
-    scanDirectory(dir: any, options?: {}): Promise<{
-        files: never[];
-        directories: never[];
-    }>;
-    extractExports(module: any): {};
+    /**
+     * 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;
 }
-export function warnIfCoverageWithoutImporter(config: any, { worker, externalized }?: {
-    worker?: any;
-    externalized?: boolean | undefined;
-}): boolean;
 import { ComponentBase } from "#factories/component-base";

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

@@ -1,4 +1,18 @@
-export function generateTypes(api: any, options: any): Promise<{
+/**
+ * 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;
-    filePath: any;
+    interfaceName: string;
+    includeDocumentation?: boolean | undefined;
+}): Promise<{
+    output: string;
+    filePath: string;
 }>;

package/lib/processors/typescript.d.mts

@@ -1,17 +1,173 @@
-export function createDataUrl(code: any): string;
-export function formatDiagnostics(diagnostics: any, ts: any): any;
-export function maskStringsAndComments(code: any): Uint8Array<any>;
-export function resolveModuleFile(absoluteTarget: any): {
-    path: any;
+/**
+ * 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;
 };
-export function rewriteRelativeSpecifiers(code: any, sourcePath: any, resolve: any): any;
-export function transformTypeScript(filePath: any, options?: {}): Promise<any>;
-export function transformTypeScriptStrict(filePath: any, options?: {}): Promise<{
-    code: any;
-    diagnostics: any[];
+/**
+ * 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;
 }>;
-export function writeTransformedToCache(originalPath: any, code: any, instanceID: any, transform: any): Promise<{
-    url: any;
-    cacheDir: any;
+/**
+ * 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[];

package/lib/runtime/runtime-asynclocalstorage.d.mts

@@ -1,3 +1,71 @@
-export const context: {};
-export const instanceID: {};
-export const self: {};
+/**
+ * Live binding to the current API (self-reference)
+ * @type {Proxy}
+ * @public
+ *
+ * @description
+ * A proxy that provides access to the full API object within the current context.
+ * Automatically resolves to the correct instance's API in AsyncLocalStorage context.
+ *
+ * @example
+ * import { self } from "@cldmv/slothlet/runtime/async";
+ *
+ * export function callOtherFunction() {
+ *   // Call another function in the same API
+ *   return self.otherFunction();
+ * }
+ */
+export const self: ProxyConstructor;
+/**
+ * User-provided context object
+ * @type {Proxy}
+ * @public
+ *
+ * @description
+ * A proxy that provides access to user-provided context data (e.g., request data, user info).
+ * Can be set via `slothlet.run()` or `slothlet.scope()`.
+ *
+ * @example
+ * import { context } from "@cldmv/slothlet/runtime/async";
+ *
+ * export function getUserInfo() {
+ *   // Access user-provided context
+ *   return {
+ *     userId: context.userId,
+ *     userName: context.userName
+ *   };
+ * }
+ */
+export const context: ProxyConstructor;
+/**
+ * Reference to initialization reference object
+ * @type {Proxy}
+ * @public
+ *
+ * @description
+ * The reference object is merged directly into the API at initialization using the add API system.
+ * It is NOT available as a runtime export. Access it directly from the API or via api.slothlet.diag.reference().
+ *
+ * @example
+ * // Reference merged into API - access directly:
+ * export function useReferenceData() {
+ *   return self.myData; // if reference had myData property
+ * }
+ */
+/**
+ * Current instance ID
+ * @type {Proxy}
+ * @public
+ *
+ * @description
+ * A proxy that provides access to the current slothlet instance ID.
+ * Useful for debugging and tracking which instance is handling a request.
+ *
+ * @example
+ * import { instanceID } from "@cldmv/slothlet/runtime/async";
+ *
+ * export function getInstanceInfo() {
+ *   return { instanceID };
+ * }
+ */
+export const instanceID: ProxyConstructor;

package/lib/runtime/runtime-livebindings.d.mts

@@ -1,2 +1,37 @@
-export const context: {};
-export const self: {};
+/**
+ * Live binding to the current API (self-reference)
+ * @type {Proxy}
+ * @public
+ *
+ * @description
+ * A proxy that provides direct access to the current instance's API.
+ * In live mode, this directly references the active instance without AsyncLocalStorage.
+ *
+ * @example
+ * import { self } from "@cldmv/slothlet/runtime/live";
+ *
+ * export function callOtherFunction() {
+ *   return self.otherFunction();
+ * }
+ */
+export const self: ProxyConstructor;
+/**
+ * User-provided context object
+ * @type {Proxy}
+ * @public
+ *
+ * @description
+ * A proxy that provides access to user-provided context data.
+ * In live mode, this directly accesses the current instance's context.
+ *
+ * @example
+ * import { context } from "@cldmv/slothlet/runtime/live";
+ *
+ * export function getUserInfo() {
+ *   return {
+ *     userId: context.userId,
+ *     userName: context.userName
+ *   };
+ * }
+ */
+export const context: ProxyConstructor;

package/lib/runtime/runtime.d.mts

@@ -1,3 +1,39 @@
-export const context: {};
-export const instanceID: {};
-export const self: {};
+/**
+ * Live binding to the current API instance. Resolves to the running Slothlet proxy,
+ * giving API modules access to all other API methods without import cycles.
+ *
+ * @memberof module:@cldmv/slothlet/runtime
+ * @type {object}
+ * @example
+ * import { self } from "@cldmv/slothlet/runtime";
+ * // Inside an API function:
+ * const result = await self.math.add(1, 2);
+ */
+export const self: object;
+/**
+ * The current ambient context object. Seeded at instance startup via `config.context` and
+ * persists for the lifetime of the instance. `api.slothlet.context.run()` and `.scope()` can
+ * temporarily override it for the duration of a single call, after which the previous context
+ * is restored. Readable and writable.
+ *
+ * @memberof module:@cldmv/slothlet/runtime
+ * @type {object}
+ * @example
+ * import { context } from "@cldmv/slothlet/runtime";
+ * // Read the ambient context set via config.context or written by a previous call:
+ * const userId = context.userId;
+ * // context.run() overrides it only for the duration of that one call:
+ * await api.slothlet.context.run({ userId: 42 }, myFn);
+ */
+export const context: object;
+/**
+ * Current Slothlet instance identifier. Unique per `slothlet()` call; useful when
+ * multiple Slothlet instances coexist and you need to identify which one is active.
+ *
+ * @memberof module:@cldmv/slothlet/runtime
+ * @type {string}
+ * @example
+ * import { instanceID } from "@cldmv/slothlet/runtime";
+ * console.log(instanceID); // e.g. "slothlet-1"
+ */
+export const instanceID: string;