@cldmv/slothlet 2.11.0 → 3.0.1

package/types/dist/lib/handlers/ownership.d.mts

@@ -0,0 +1,170 @@
+/**
+ * Summary result of an unregister operation.
+ * @typedef {Object} UnregisterResult
+ * @property {string[]} removed - API paths that were removed.
+ * @property {Object[]} rolledBack - Entries that were rolled back to a previous owner.
+ */
+/**
+ * Tracks which modules own which API paths for hot reload and rollback
+ * @class OwnershipManager
+ * @extends ComponentBase
+ * @public
+ */
+export class OwnershipManager extends ComponentBase {
+    static slothletProperty: string;
+    constructor(slothlet: any);
+    moduleToPath: Map<any, any>;
+    pathToModule: Map<any, any>;
+    _unregisteredModules: Set<any>;
+    /**
+     * Register module ownership of API path with its value
+     * @param {Object} options - Registration options
+     * @param {string} options.moduleID - Module identifier
+     * @param {string} options.apiPath - API path being registered
+     * @param {*} options.value - The actual function/object being registered
+     * @param {string} [options.source="core"] - Source of registration
+     * @param {string} [options.collisionMode="error"] - Collision mode: skip, warn, error, merge, replace
+     * @param {Object} [options.config] - Config object for silent mode check
+     * @param {string} [options.filePath=null] - File path of the module source (for metadata tracking)
+     * @returns {Object|null} Registration entry or null if skipped
+     * @public
+     */
+    public register({ moduleID, apiPath, value, source, collisionMode, config, filePath }: {
+        moduleID: string;
+        apiPath: string;
+        value: any;
+        source?: string;
+        collisionMode?: string;
+        config?: any;
+        filePath?: string;
+    }): any | null;
+    /**
+     * @param {string} moduleID - Module to unregister.
+     * @returns {UnregisterResult} Removal summary.
+     * @public
+     *
+     * @description
+     * Removes all paths owned by the provided moduleID and reports removals and rollbacks.
+     *
+     * @example
+     * const result = ownership.unregister("module-a");
+     */
+    public unregister(moduleID: string): UnregisterResult;
+    /**
+     * @param {string} apiPath - API path to modify.
+     * @param {string|null} [moduleID=null] - Module to remove (defaults to current owner).
+     * @returns {{ action: "delete"|"none"|"restore", removedModuleId: string|null,
+     * restoreModuleId: string|null }} Action taken for the path.
+     * @public
+     *
+     * @description
+     * Removes a module owner from a specific API path. If the current owner is removed and
+     * previous owners exist, the path is restored to the previous owner.
+     *
+     * @example
+     * const result = ownership.removePath("plugins.tools", "module-a");
+     */
+    public removePath(apiPath: string, moduleID?: string | null): {
+        action: "delete" | "none" | "restore";
+        removedModuleId: string | null;
+        restoreModuleId: string | null;
+    };
+    /**
+     * Get current owner of API path
+     * @param {string} apiPath - API path to check
+     * @returns {Object|null} Current owner entry or null
+     * @public
+     */
+    public getCurrentOwner(apiPath: string): any | null;
+    /**
+     * Get current value for API path
+     * @param {string} apiPath - API path to check
+     * @returns {*} Current value or undefined
+     * @public
+     */
+    public getCurrentValue(apiPath: string): any;
+    /**
+     * Get all paths owned by module
+     * @param {string} moduleID - Module to query
+     * @returns {Array<string>} Array of API paths
+     * @public
+     */
+    public getModulePaths(moduleID: string): Array<string>;
+    /**
+     * Get ownership history for path
+     * @param {string} apiPath - API path to query
+     * @returns {Array<Object>} Ownership history stack
+     * @public
+     */
+    public getPathHistory(apiPath: string): Array<any>;
+    /**
+     * Check if module owns path
+     * @param {string} moduleID - Module to check
+     * @param {string} apiPath - API path to check
+     * @returns {boolean} True if module owns path
+     * @public
+     */
+    public ownsPath(moduleID: string, apiPath: string): boolean;
+    /**
+     * Get diagnostic info about ownership
+     * @returns {Object} Diagnostic information
+     * @public
+     */
+    public getDiagnostics(): any;
+    /**
+     * Get ownership info for a specific API path
+     * @param {string} apiPath - API path to check
+     * @returns {Set<string>|null} Set of moduleIDs that own this path, or null if path not found
+     * @public
+     */
+    public getPathOwnership(apiPath: string): Set<string> | null;
+    /**
+     * Recursively register API subtree with ownership
+     * @param {object} api - API object or subtree
+     * @param {string} moduleID - Module identifier (owner)
+     * @param {string} path - Current API path
+     * @param {WeakSet} [visited] - Visited objects (prevents circular refs)
+     * @returns {void}
+     * @public
+     *
+     * @description
+     * Registers entire API subtree structure with ownership manager.
+     * Used during load, reload, and api.add to establish ownership relationships.
+     *
+     * @example
+     * ownership.registerSubtree(api, "base_abc123", "");
+     */
+    public registerSubtree(api: object, moduleID: string, path: string, visited?: WeakSet<any>): void;
+    /**
+     * Clear all ownership data
+     * @public
+     */
+    public clear(): void;
+    /**
+     * Export ownership state for preservation during reload
+     * @returns {Object} Serializable ownership state
+     * @public
+     */
+    public exportState(): any;
+    /**
+     * Import ownership state from exported data
+     * @param {Object} state - Previously exported state
+     * @public
+     */
+    public importState(state: any): void;
+}
+/**
+ * Summary result of an unregister operation.
+ */
+export type UnregisterResult = {
+    /**
+     * - API paths that were removed.
+     */
+    removed: string[];
+    /**
+     * - Entries that were rolled back to a previous owner.
+     */
+    rolledBack: any[];
+};
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=ownership.d.mts.map

package/types/dist/lib/handlers/ownership.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/ownership.mjs"],"names":[],"mappings":"AAqBA;;;;;GAKG;AAEH;;;;;GAKG;AACH;IACC,gCAAsC;IAEtC,2BAKC;IAHA,4BAA6B;IAC7B,4BAA6B;IAC7B,+BAAqC;IAGtC;;;;;;;;;;;;OAYG;IACH,uFAVG;QAAwB,QAAQ,EAAxB,MAAM;QACU,OAAO,EAAvB,MAAM;QACK,KAAK,EAAhB,GAAC;QACgB,MAAM,GAAvB,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,MAAM;QACN,QAAQ,GAAzB,MAAM;KACd,GAAU,MAAO,IAAI,CAsFvB;IAED;;;;;;;;;;OAUG;IACH,4BAVW,MAAM,GACJ,gBAAgB,CAsC5B;IAED;;;;;;;;;;;;;OAaG;IACH,2BAbW,MAAM,aACN,MAAM,GAAC,IAAI,GACT;QAAE,MAAM,EAAE,QAAQ,GAAC,MAAM,GAAC,SAAS,CAAC;QAAC,eAAe,EAAE,MAAM,GAAC,IAAI,CAAC;QAC5E,eAAe,EAAE,MAAM,GAAC,IAAI,CAAA;KAAE,CA4ChC;IAED;;;;;OAKG;IACH,gCAJW,MAAM,GACJ,MAAO,IAAI,CAOvB;IAED;;;;;OAKG;IACH,gCAJW,MAAM,GACJ,GAAC,CAkBb;IAED;;;;;OAKG;IACH,gCAJW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAKzB;IAED;;;;;OAKG;IACH,+BAJW,MAAM,GACJ,KAAK,KAAQ,CAKzB;IAED;;;;;;OAMG;IACH,0BALW,MAAM,WACN,MAAM,GACJ,OAAO,CAMnB;IAED;;;;OAIG;IACH,6BAeC;IAED;;;;;OAKG;IACH,iCAJW,MAAM,GACJ,GAAG,CAAC,MAAM,CAAC,GAAC,IAAI,CAS5B;IAED;;;;;;;;;;;;;;;OAeG;IACH,4BAdW,MAAM,YACN,MAAM,QACN,MAAM,2BAEJ,IAAI,CAwDhB;IAED;;;OAGG;IACH,qBAIC;IAED;;;;OAIG;IACH,0BAKC;IAED;;;;OAIG;IACH,qCAaC;CACD;;;;;;;;aAlaa,MAAM,EAAE;;;;gBACR,KAAQ;;8BAPQ,0CAA0C"}

package/types/dist/lib/handlers/unified-wrapper.d.mts

@@ -0,0 +1,250 @@
+/**
+ * Resolves a value to its backing UnifiedWrapper instance.
+ * Accepts a proxy registered via createProxy() or a raw UnifiedWrapper instance.
+ * Returns null for any other value.
+ *
+ * @param {unknown} value - Value to resolve
+ * @returns {UnifiedWrapper|null} The backing wrapper, or null
+ *
+ * @example
+ * const wrapper = resolveWrapper(someProxy);
+ * if (wrapper) wrapper.____slothletInternal.impl = newImpl;
+ */
+export function resolveWrapper(value: unknown): UnifiedWrapper | null;
+export namespace TYPE_STATES {
+    let UNMATERIALIZED: symbol;
+    let IN_FLIGHT: symbol;
+}
+/**
+ * Unified wrapper class that handles all proxy concerns in one place:
+ * - __impl pattern for reload support
+ * - Lazy/eager mode materialization
+ * - Recursive waiting proxy for deep lazy loading
+ * - Context binding through contextManager
+ *
+ * @class
+ * @extends ComponentBase
+ * @public
+ */
+export class UnifiedWrapper extends ComponentBase {
+    /**
+     * Shallow-clone a non-Proxy object implementation to prevent ___adoptImplChildren
+     * from mutating shared module export references via its `delete this.____slothletInternal.impl[key]`
+     * operations. When concurrent materializations (e.g., old + new wrapper during reload)
+     * both load the same cached module, the first ___adoptImplChildren would destroy the
+     * shared export, causing subsequent wrappers to receive empty objects.
+     *
+     * Returns the value unchanged if it is not a plain object, or if it IS a Proxy
+     * (cloning a Proxy destroys its trap behavior - e.g., LG TV controllers using
+     * numeric-index access through custom get traps).
+     *
+     * @param {*} value - The implementation value to (maybe) clone.
+     * @returns {*} A shallow clone of `value` when it is a non-Proxy plain object,
+     *              otherwise the original `value`.
+     * @static
+     * @private
+     */
+    private static _cloneImpl;
+    /**
+     * Reconstruct a full implementation object from a wrapper whose _impl may have
+     * been depleted by ___adoptImplChildren.
+     *
+     * @description
+     * After ___adoptImplChildren runs, children are moved from _impl onto the wrapper as
+     * own properties and deleted from _impl. This helper reconstructs the original
+     * impl by merging the remaining _impl keys with the adopted children extracted
+     * from the wrapper.
+     *
+     * Recursively walks the wrapper tree so nested objects whose _impl was also
+     * depleted are properly reconstructed. For callable (function) impls, returns
+     * the function directly since keepImplProperties prevents depletion.
+     *
+     * @param {Object} wrapper - The UnifiedWrapper instance to extract from
+     * @returns {*} The reconstructed implementation mirroring original module exports
+     * @static
+     * @private
+     */
+    private static _extractFullImpl;
+    /**
+     * @param {Object} slothlet - Slothlet instance (provides contextManager, instanceID, ownership)
+     * @param {Object} options - Configuration options
+     * @param {string} options.mode - "lazy" or "eager"
+     * @param {string} options.apiPath - API path for this wrapper (e.g., "math.advanced.calc")
+     * @param {Object} [options.initialImpl=null] - Initial implementation (null for lazy mode)
+     * @param {Function} [options.materializeFunc=null] - Async function to materialize lazy modules
+     * @param {boolean} [options.isCallable=false] - Whether the wrapper should be callable
+     * @param {boolean} [options.materializeOnCreate=false] - Whether to materialize on creation
+     * @param {string} [options.filePath=null] - File path of the module source
+     * @param {string} [options.moduleID=null] - Module identifier
+     * @param {string} [options.sourceFolder=null] - Source folder for metadata
+     *
+     * @description
+     * Creates a unified wrapper instance for a specific API path. Extends ComponentBase
+     * to access slothlet.contextManager, slothlet.instanceID, and slothlet.handlers.ownership.
+     *
+     * @example
+     * const wrapper = new UnifiedWrapper(this.slothlet, {
+     * 	mode: "lazy",
+     * 	apiPath: "math",
+     * 	initialImpl: null,
+     * 	materializeFunc: async () => import("./math.mjs")
+     * });
+     */
+    constructor(slothlet: any, { mode, apiPath, initialImpl, materializeFunc, isCallable, materializeOnCreate, filePath, moduleID, sourceFolder }: {
+        mode: string;
+        apiPath: string;
+        initialImpl?: any;
+        materializeFunc?: Function;
+        isCallable?: boolean;
+        materializeOnCreate?: boolean;
+        filePath?: string;
+        moduleID?: string;
+        sourceFolder?: string;
+    });
+    /**
+     * Internal state accessor used by framework-internal code only.
+     * Backed by the private `#internal` field - prototype property, not an own property,
+     * so proxy invariants never apply and getTrap can legally return undefined for it.
+     *
+     * Uses a private-field brand check (`#internal in this`) so the getter is safe to
+     * invoke with any receiver - including `UnifiedWrapper.prototype` itself during a
+     * prototype chain walk via `Object.getPrototypeOf` - without throwing a TypeError.
+     * Without the brand check, `Object.getPrototypeOf(proxy).____slothletInternal` would
+     * throw because the prototype object was never constructed and has no `#internal` field.
+     * @returns {Object|undefined} Internal state container, or undefined for non-instances
+     */
+    get ____slothletInternal(): any | undefined;
+    /**
+     * Get current implementation
+     * @returns {Object|null} Current __impl value
+     * @public
+     */
+    public get __impl(): any | null;
+    /**
+     * Core implementation-application logic shared by ___setImpl and lazy materialization.
+     * Clones the implementation (protecting the API cache from ___adoptImplChildren's
+     * delete operations), clears the invalid flag, upgrades __isCallable when a
+     * callable impl arrives on a configurable wrapper, updates __filePath for lazy
+     * folder wrappers, and adopts children.
+     *
+     * @param {*} newImpl - The new implementation value.
+     * @param {boolean} [forceReuseChildren=false] - When true, always reuse existing child
+     *   wrappers regardless of mode (used by ___setImpl to preserve live references).
+     * @private
+     */
+    private _applyNewImpl;
+    /**
+     * Set new implementation and adopt children.
+     * Delegates core impl work to _applyNewImpl, then emits lifecycle events
+     * and updates materialization state.
+     *
+     * @param {*} newImpl - New implementation
+     * @param {string} [moduleID] - Optional moduleID for lifecycle event (for replacements)
+     * @param {boolean} [forceReuseChildren=false] - When true, always reuse existing child
+     *   wrappers and bypass collision-merged key guards. Use this for direct/explicit
+     *   ___setImpl calls where reference preservation is the intent. Do NOT set for
+     *   hot-reload paths (syncWrapper) where lazy refs should intentionally break.
+     * @private
+     */
+    private ___setImpl;
+    /**
+     * Reset wrapper to un-materialized lazy state with a fresh materialization function.
+     * Used during reload to restore lazy wrappers to their shell state instead of
+     * eagerly loading all implementations. Preserves proxy identity so existing
+     * references continue to work - next property access triggers materialization
+     * from the fresh materializeFunc (which reads updated source files from disk).
+     * @param {Function} newMaterializeFunc - Fresh materialization function from rebuild
+     * @returns {void}
+     * @private
+     */
+    private ___resetLazy;
+    /**
+     * Trigger materialization (lazy mode only)
+     * @returns {Promise<void>}
+     * @private
+     */
+    private ___materialize;
+    /**
+     * @private
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Exposes lazy materialization for waiting proxies and nested wrappers.
+     *
+     * @example
+     * await wrapper._materialize();
+     */
+    private _materialize;
+    /**
+     * @private
+     * @returns {void}
+     *
+     * @description
+     * Invalidates this wrapper when its parent removes the API path.
+     *
+     * @example
+     * wrapper.___invalidate();
+     */
+    private ___invalidate;
+    /**
+     * @private
+     * @returns {void}
+     *
+     * @description
+     * Moves child properties off the impl and attaches them to wrapper as properties
+     * so this wrapper only represents the current API path.
+     *
+     * @example
+     * wrapper.___adoptImplChildren();
+     */
+    private ___adoptImplChildren;
+    /**
+     * @private
+     * @param {string|symbol} key - Child property name
+     * @param {unknown} value - Child value
+     * @returns {Object|Function|undefined} Wrapped child proxy when applicable
+     *
+     * @description
+     * Creates a child wrapper for impl values, including primitives.
+     *
+     * @example
+     * const child = wrapper.___createChildWrapper("add", fn);
+     */
+    private ___createChildWrapper;
+    /**
+     * Create recursive waiting proxy for deep lazy loading
+     * Builds property chain (e.g., ["advanced", "calc", "power"]) and waits for all parent
+     * wrappers to materialize before accessing the final property.
+     *
+     * Waiting proxies are ONLY created when not materialized or in-flight.
+     * Once materialized, we return actual cached values, not waiting proxies.
+     * Therefore, waiting proxies always represent in-flight/unmaterialized state.
+     *
+     * CRITICAL: Caches waiting proxies by propChain key to ensure subsequent accesses
+     * return the SAME proxy object, which can then delegate once materialization completes.
+     * This matches v2's propertyProxyCache behavior.
+     *
+     * @private
+     * @param {Array<string|symbol>} [propChain=[]] - Property chain to resolve.
+     * @returns {Proxy} Proxy that waits for materialization before applying calls.
+     */
+    private ___createWaitingProxy;
+    /**
+     * Create main proxy for this wrapper
+     * Handles lazy/eager mode logic, property access, and context binding
+     *
+     * @returns {Proxy} Main proxy for API
+     * @public
+     */
+    public createProxy(): ProxyConstructor;
+    lastSyncError: any;
+    /**
+     * Custom inspect output for Node.js util.inspect.
+     * @returns {*} The actual implementation for inspection.
+     */
+    [util.inspect.custom](____depth: any, ____options: any, ____inspect: any): any;
+    #private;
+}
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+import util from "node:util";
+//# sourceMappingURL=unified-wrapper.d.mts.map

package/types/dist/lib/handlers/unified-wrapper.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-wrapper.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/unified-wrapper.mjs"],"names":[],"mappings":"AAquGA;;;;;;;;;;;GAWG;AACH,sCAPW,OAAO,GACL,cAAc,GAAC,IAAI,CAkB/B;;;;;AAjpGD;;;;;;;;;;GAUG;AACH;IAiQC;;;;;;;;;;;;;;;;OAgBG;IACH,0BA8BC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,gCA0DC;IApWD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+IAtBG;QAAwB,IAAI,EAApB,MAAM;QACU,OAAO,EAAvB,MAAM;QACW,WAAW;QACT,eAAe;QAChB,UAAU,GAA5B,OAAO;QACW,mBAAmB,GAArC,OAAO;QACU,QAAQ,GAAzB,MAAM;QACW,QAAQ,GAAzB,MAAM;QACW,YAAY,GAA7B,MAAM;KAEd,EA4KF;IA1MD;;;;;;;;;;;OAWG;IACH,4BAFa,MAAO,SAAS,CAK5B;IA+ND;;;;OAIG;IACH,qBAHa,MAAO,IAAI,CAKvB;IAkID;;;;;;;;;;;OAWG;IACH,sBAiCC;IAED;;;;;;;;;;;;OAYG;IACH,mBAgDC;IAED;;;;;;;;;OASG;IACH,qBAmDC;IAED;;;;OAIG;IACH,uBA+FC;IAED;;;;;;;;;OASG;IACH,qBAEC;IAED;;;;;;;;;OASG;IACH,sBAiBC;IAED;;;;;;;;;;OAUG;IACH,6BAmbC;IAED;;;;;;;;;;;OAWG;IACH,8BAwIC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,8BA8oBC;IAED;;;;;;OAMG;IACH,uCA8qCC;IAjVE,mBAA0B;IApkF7B;;;OAGG;IACH,2EAFa,GAAC,CA8Bb;;CAs3FD;8BA7sG6B,0CAA0C;iBADvD,WAAW"}

package/types/dist/lib/helpers/class-instance-wrapper.d.mts

@@ -0,0 +1,54 @@
+/**
+ * @function runtime_shouldWrapMethod
+ * @package
+ * @param {*} value - The value to check
+ * @param {string|symbol} prop - The property name
+ * @returns {boolean} True if the method should be wrapped
+ *
+ * @description
+ * Determines if a method should be wrapped with context preservation.
+ * Excludes constructors, Object.prototype methods, and internal methods.
+ *
+ * @example
+ * runtime_shouldWrapMethod(myInstance.method, "method"); // true
+ * runtime_shouldWrapMethod(myInstance.constructor, "constructor"); // false
+ */
+export function runtime_shouldWrapMethod(value: any, prop: string | symbol): boolean;
+/**
+ * @function runtime_isClassInstance
+ * @package
+ * @param {*} val - The value to check
+ * @returns {boolean} True if the value is a class instance that should be wrapped
+ *
+ * @description
+ * Determines if a value is a class instance (not a plain object, array, or primitive)
+ * that should have its methods wrapped to preserve AsyncLocalStorage context.
+ * Uses systematic exclusion lists for better maintainability.
+ *
+ * @example
+ * // Check if value is a class instance
+ * const isInstance = runtime_isClassInstance(new MyClass());
+ */
+export function runtime_isClassInstance(val: any): boolean;
+/**
+ * @function runtime_wrapClassInstance
+ * @package
+ * @param {object} instance - The class instance to wrap
+ * @param {object} contextManager - The context manager (async or live)
+ * @param {string} instanceID - The slothlet instance ID
+ * @param {WeakMap} instanceCache - The cache for wrapped instances
+ * @returns {Proxy} A proxied instance with context-aware method calls
+ *
+ * @description
+ * Wraps a class instance so that all method calls maintain the AsyncLocalStorage context.
+ * This ensures that calls to methods on returned class instances preserve the slothlet
+ * context for runtime imports like `self` and `context`.
+ *
+ * V3 Adaptation: Uses contextManager.runInContext() instead of V2's runWithCtx().
+ *
+ * @example
+ * // Wrap a class instance to preserve context
+ * const wrappedInstance = runtime_wrapClassInstance(instance, contextManager, instanceID, instanceCache);
+ */
+export function runtime_wrapClassInstance(instance: object, contextManager: object, instanceID: string, instanceCache: WeakMap<any, any>): ProxyConstructor;
+//# sourceMappingURL=class-instance-wrapper.d.mts.map

package/types/dist/lib/helpers/class-instance-wrapper.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class-instance-wrapper.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/class-instance-wrapper.mjs"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;GAcG;AACH,gDAZW,GAAC,QACD,MAAM,GAAC,MAAM,GACX,OAAO,CAkBnB;AAED;;;;;;;;;;;;;;GAcG;AACH,6CAZW,GAAC,GACC,OAAO,CA6BnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oDAjBW,MAAM,kBACN,MAAM,cACN,MAAM,sDA8EhB"}

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

@@ -0,0 +1,96 @@
+/**
+ * Configuration normalization utilities
+ * @class Config
+ * @extends ComponentBase
+ * @public
+ */
+export class Config extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Normalize collision configuration for handling property collisions
+     * @param {string|Object} collision - Collision mode or object with per-context modes
+     * @returns {Object} Normalized collision configuration with initial and api.slothlet.api.add modes
+     * @public
+     *
+     * @description
+     * Normalizes collision handling configuration for both initial load (buildAPI)
+     * and hot reload (api.add) contexts. Supports six collision modes:
+     * - "skip": Silently ignore collision, keep existing value
+     * - "warn": Warn about collision, keep existing value
+     * - "replace": Replace existing value completely
+     * - "merge": Merge properties (preserve original + add new)
+     * - "merge-replace": Merge properties (add new + overwrite existing with new values)
+     * - "error": Throw error on collision
+     *
+     * @example
+     * // String shorthand applies to both contexts
+     * normalizeCollision("merge")
+     * // => { initial: "merge", api: "merge" }
+     *
+     * @example
+     * // Object allows per-context control
+     * normalizeCollision({ initial: "warn", api: "error" })
+     * // => { initial: "warn", api: "error" }
+     */
+    public normalizeCollision(collision: string | any): any;
+    /**
+     * Normalize runtime input to internal standard format
+     * @param {string} runtime - Input runtime type (various formats accepted)
+     * @returns {string} Normalized runtime type ("async" or "live")
+     * @public
+     */
+    public normalizeRuntime(runtime: string): string;
+    /**
+     * Normalize mode input to internal standard format
+     * @param {string} mode - Input mode type (various formats accepted)
+     * @returns {string} Normalized mode type ("eager" or "lazy")
+     * @public
+     */
+    public normalizeMode(mode: string): string;
+    /**
+     * Normalize mutations configuration for API modification control
+     * @param {Object} mutations - Mutations config object with add/remove/reload properties
+     * @returns {Object} Normalized mutations configuration
+     * @public
+     *
+     * @description
+     * Normalizes mutation control configuration for API runtime modifications.
+     * Controls whether api.slothlet.api.add(), api.slothlet.api.remove(), and
+     * api.slothlet.reload() operations are allowed.
+     *
+     * @example
+     * // Allow all mutations (default)
+     * normalizeMutations({ add: true, remove: true, reload: true })
+     * // => { add: true, remove: true, reload: true }
+     *
+     * @example
+     * // Disable all mutations
+     * normalizeMutations({ add: false, remove: false, reload: false })
+     * // => { add: false, remove: false, reload: false }
+     */
+    public normalizeMutations(mutations: any): any;
+    /**
+     * Normalize debug configuration
+     * @param {boolean|Object} debug - Debug flag or object with targeted flags
+     * @returns {Object} Normalized debug object with all flags
+     * @public
+     */
+    public normalizeDebug(debug: boolean | any): any;
+    /**
+     * Transform and validate configuration
+     * @param {Object} config - Raw configuration options
+     * @returns {Object} Normalized configuration
+     * @throws {SlothletError} If configuration is invalid
+     * @public
+     */
+    public transformConfig(config?: any): any;
+    /**
+     * Normalize TypeScript configuration
+     * @param {boolean|string|Object} typescript - TypeScript config (true, "fast", or { mode: "fast"|"strict", ... })
+     * @returns {Object|null} Normalized TypeScript configuration or null if disabled
+     * @public
+     */
+    public normalizeTypeScript(typescript: boolean | string | any): any | null;
+}
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=config.d.mts.map

package/types/dist/lib/helpers/config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/config.mjs"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH;IACC,gCAAmC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,qCAxBW,MAAM,MAAO,OAkDvB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;OAKG;IACH,2BAJW,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,+CAcC;IAED;;;;;OAKG;IACH,6BAJW,OAAO,MAAO,OA6DxB;IAED;;;;;;OAMG;IACH,0CA+HC;IAED;;;;;OAKG;IACH,uCAJW,OAAO,GAAC,MAAM,MAAO,GACnB,MAAO,IAAI,CAsCvB;CACD;8BA/Y6B,0CAA0C"}

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

@@ -0,0 +1,31 @@
+/**
+ * Set the context checker callback
+ * Called by the runtime to register a way to detect API context
+ * @param {Function} checker - Function that returns true if in API context
+ * @public
+ */
+export function setApiContextChecker(checker: Function): void;
+/**
+ * Enable EventEmitter context propagation by patching EventEmitter.prototype.
+ * This should be called ONCE globally when the first slothlet instance is created.
+ * Subsequent calls will be ignored (patching is global).
+ *
+ * @public
+ */
+export function enableEventEmitterPatching(): void;
+/**
+ * Disable EventEmitter context propagation and restore original methods.
+ * This should only be called when ALL slothlet instances have been shut down.
+ *
+ * @public
+ */
+export function disableEventEmitterPatching(): void;
+/**
+ * Cleanup all tracked EventEmitters created within slothlet API context.
+ * This removes all listeners from tracked emitters and clears tracking structures.
+ * Should be called during shutdown to prevent memory leaks and hanging processes.
+ *
+ * @public
+ */
+export function cleanupEventEmitterResources(): void;
+//# sourceMappingURL=eventemitter-context.d.mts.map

package/types/dist/lib/helpers/eventemitter-context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventemitter-context.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/eventemitter-context.mjs"],"names":[],"mappings":"AAsCA;;;;;GAKG;AACH,8DAEC;AAyWD;;;;;;GAMG;AACH,mDAeC;AAED;;;;;GAKG;AACH,oDAmBC;AAED;;;;;;GAMG;AACH,qDAcC"}

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

@@ -0,0 +1,20 @@
+/**
+ * Hint detection for providing helpful error hints
+ * @class HintDetector
+ * @extends ComponentBase
+ * @package
+ */
+export class HintDetector extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Detect appropriate hint key based on error
+     * @param {Error} error - The original error
+     * @param {string} errorCode - The SlothletError code
+     * @returns {string|undefined} Hint key for i18n translation, or undefined
+     * @public
+     */
+    public detectHint(error: Error, errorCode: string): string | undefined;
+}
+export const detectHint: any;
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=hint-detector.d.mts.map

package/types/dist/lib/helpers/hint-detector.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint-detector.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/hint-detector.mjs"],"names":[],"mappings":"AAwCA;;;;;GAKG;AACH;IACC,gCAAyC;IAEzC;;;;;;OAMG;IACH,yBALW,KAAK,aACL,MAAM,GACJ,MAAM,GAAC,SAAS,CAiB5B;CACD;AAID,6BAA2G;8BAxD7E,0CAA0C"}