@cldmv/slothlet 2.11.0 → 3.0.1

package/index.cjs

@@ -2,13 +2,13 @@
  *	@Project: @cldmv/slothlet
  *	@Filename: /index.cjs
  *	@Date: 2025-11-09 11:15:17 -08:00 (1762715717)
- *	@Author: Nate Hyson <CLDMV>
+ *	@Author: Nate Corcoran <CLDMV>
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
- *	@Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2025-11-09 14:43:17 -08:00 (1762728197)
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01 20:21:36 -08:00 (1772425296)
  *	-----
- *	@Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  */
 
 /**

package/index.mjs

@@ -1,43 +1,95 @@
 /**
- * @fileoverview ESM entry point for @cldmv/slothlet with automatic source/dist detection and live-binding context.
- * @module @cldmv/slothlet
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /index.mjs
+ *	@Date: 2025-09-09T08:06:19-07:00 (1757430379)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-03-01 20:21:36 -08:00 (1772425296)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  */
 
 /**
- * Normalize runtime input to internal standard format.
- * @function normalizeRuntimeType
- * @param {string} runtime - Input runtime type (various formats accepted)
- * @returns {string} Normalized runtime type ("async" or "live")
- * @internal
- * @private
+ * @fileoverview ESM entry point for @cldmv/slothlet with automatic source/dist detection and live-binding context.
+ * @module @cldmv/slothlet
  */
-function normalizeRuntimeType(runtime) {
-	if (!runtime || typeof runtime !== "string") {
-		return "async"; // Default to AsyncLocalStorage
-	}
 
-	const normalized = runtime.toLowerCase().trim();
+// Custom uncaught exception handler for SlothletError
+process.on("uncaughtException", (error) => {
+	if (error.name === "SlothletError") {
+		console.error("\n================================================================================");
+		console.error(`ERROR [${error.code}]: ${error.message}`);
 
-	// AsyncLocalStorage runtime variants
-	if (normalized === "async" || normalized === "asynclocal" || normalized === "asynclocalstorage") {
-		return "async";
-	}
+		// Extract and show file/line from original error stack if available
+		const stackToUse = error.originalError?.stack || error.stack;
+		if (stackToUse) {
+			const stackLines = stackToUse.split("\n");
+			// For import errors, try to extract from the error message first (more accurate)
+			if (
+				error.originalError?.message?.includes("does not provide an export") ||
+				error.originalError?.message?.includes("Cannot find module")
+			) {
+				// Extract file path from context (modulePath is the file that failed to import)
+				const failedFile = error.context?.modulePath;
+				if (failedFile) {
+					console.error(`\n📍 Location: ${failedFile} (import statement)`);
+				}
+			} else {
+				// Otherwise extract from stack trace
+				const firstStackLine = stackLines[1]; // First line after error message
+				if (firstStackLine) {
+					// Extract file:line info from stack trace (format: "at function (file:line:col)")
+					const match = firstStackLine.match(/\((.+?):(\d+):(\d+)\)/) || firstStackLine.match(/at (.+?):(\d+):(\d+)/);
+					if (match) {
+						console.error(`\n📍 Location: ${match[1]}:${match[2]}`);
+					}
+				}
+			}
+		}
+
+		if (error.hint) {
+			console.error("\n💡 Hint:");
+			console.error(`  ${error.hint}`);
+		}
+
+		// Show minimal context (filter out error/hint/originalError which are already shown)
+		const contextKeys = Object.keys(error.context || {}).filter((k) => k !== "error" && k !== "hint" && k !== "originalError");
+		if (contextKeys.length > 0) {
+			console.error("\nDetails:");
+			for (const key of contextKeys) {
+				const value = error.context[key];
+				const displayValue = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+				console.error(`  ${key}: ${displayValue}`);
+			}
+		}
 
-	// Live bindings runtime variants
-	if (normalized === "live" || normalized === "livebindings" || normalized === "experimental") {
-		return "live";
+		// Show clean stack trace (prefer original error's stack)
+		const stackForDisplay = error.originalError?.stack || error.stack;
+		if (stackForDisplay) {
+			console.error("\nStack Trace:");
+			const stackLines = stackForDisplay.split("\n").slice(1); // Skip first line (error message)
+			for (const line of stackLines) {
+				console.error(`  ${line.trim()}`);
+			}
+		}
+
+		console.error("================================================================================\n");
+		process.exit(1);
 	}
 
-	// Default to async for unknown values
-	return "async";
-}
+	// Re-throw other errors to let Node.js handle them
+	throw error;
+});
 
 // Development environment check (must happen before slothlet imports)
-(async () => {
+const devcheckPromise = (async () => {
 	try {
 		await import("@cldmv/slothlet/devcheck");
 	} catch {
-		// ignore
+		// Ignore errors (e.g., devcheck.mjs not found in production)
+		// devcheck.mjs uses process.exit() for environment errors
 	}
 })();
 
@@ -67,30 +119,15 @@ function normalizeRuntimeType(runtime) {
  *
  */
 export default async function slothlet(options = {}) {
-	// Dynamic imports after environment check
+	// Wait for devcheck to complete before proceeding
+	await devcheckPromise;
+
 	// Dynamic imports after environment check
 	const mod = await import("@cldmv/slothlet/slothlet");
 
-	const build = mod.slothlet ?? mod.default;
-
-	const api = await build(options);
-
-	// Use the same runtime selection logic as slothlet.mjs
-	const normalizedRuntime = normalizeRuntimeType(options.runtime);
-	let runtimeModule;
-	if (normalizedRuntime === "live") {
-		runtimeModule = await import("@cldmv/slothlet/runtime/live");
-	} else {
-		// Default to AsyncLocalStorage runtime (original master branch implementation)
-		runtimeModule = await import("@cldmv/slothlet/runtime/async");
-	}
-	const { makeWrapper } = runtimeModule;
-
-	// Prefer an explicit instance context the internal attached to the API (api.__ctx),
-	// else fall back to module-level pieces if you expose them.
-	const ctx = api?.__ctx ?? { self: mod.self, context: mod.context, reference: mod.reference };
+	const slothlet = mod.slothlet ?? mod.default;
 
-	return makeWrapper(ctx)(api);
+	return slothlet(options);
 }
 
 /**

package/package.json

@@ -1,11 +1,11 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "2.11.0",
+	"version": "3.0.1",
 	"moduleVersions": {
-		"lazy": "1.3.1",
-		"eager": "1.3.1",
-		"async": "1.1.0",
-		"live": "1.1.0"
+		"lazy": "3.0.0",
+		"eager": "3.0.0",
+		"async": "3.0.0",
+		"live": "3.0.0"
 	},
 	"description": "Slothlet: Modular API Loader for Node.js. Lazy mode dynamically loads API modules and submodules only when accessed, supporting both lazy and eager loading.",
 	"main": "./index.cjs",
@@ -67,42 +67,134 @@
 			},
 			"types": "./types/dist/lib/modes/*.d.mts",
 			"import": "./dist/lib/modes/*.mjs"
+		},
+		"./builders/*": {
+			"slothlet-dev": {
+				"types": "./types/src/lib/builders/*.d.mts",
+				"import": "./src/lib/builders/*.mjs"
+			},
+			"types": "./types/dist/lib/builders/*.d.mts",
+			"import": "./dist/lib/builders/*.mjs"
+		},
+		"./handlers/*": {
+			"slothlet-dev": {
+				"types": "./types/src/lib/handlers/*.d.mts",
+				"import": "./src/lib/handlers/*.mjs"
+			},
+			"types": "./types/dist/lib/handlers/*.d.mts",
+			"import": "./dist/lib/handlers/*.mjs"
+		},
+		"./processors/*": {
+			"slothlet-dev": {
+				"types": "./types/src/lib/processors/*.d.mts",
+				"import": "./src/lib/processors/*.mjs"
+			},
+			"types": "./types/dist/lib/processors/*.d.mts",
+			"import": "./dist/lib/processors/*.mjs"
+		},
+		"./factories/*": {
+			"slothlet-dev": {
+				"types": "./types/src/lib/factories/*.d.mts",
+				"import": "./src/lib/factories/*.mjs"
+			},
+			"types": "./types/dist/lib/factories/*.d.mts",
+			"import": "./dist/lib/factories/*.mjs"
+		},
+		"./errors": {
+			"slothlet-dev": {
+				"types": "./types/src/lib/errors.d.mts",
+				"import": "./src/lib/errors.mjs"
+			},
+			"types": "./types/dist/lib/errors.d.mts",
+			"import": "./dist/lib/errors.mjs"
+		},
+		"./i18n": {
+			"slothlet-dev": {
+				"types": "./types/src/lib/i18n/translations.d.mts",
+				"import": "./src/lib/i18n/translations.mjs"
+			},
+			"types": "./types/dist/lib/i18n/translations.d.mts",
+			"import": "./dist/lib/i18n/translations.mjs"
 		}
 	},
 	"types": "./types/index.d.mts",
 	"scripts": {
-		"precommit": "node tools/precommit-validation.mjs",
-		"publish:manual": "npm publish --access public",
-		"test": "node tests/test-conditional.mjs",
+		"precommit": "node tools/dev/precommit-validation.mjs",
+		"debug": "node tests/debug-slothlet.mjs",
+		"i18n:check": "node tools/ci/check-i18n-languages.mjs",
+		"vitest": "node tests/vitests/run-all-vitest.mjs --workers 8",
+		"baseline": "npm run vitest -- --baseline",
+		"coverage": "npm run vitest -- --coverage-quiet",
+		"test": "npm run test:pre-build",
 		"test:pre-build": "node tests/test-conditional.mjs",
 		"test:post-build": "npm run test:types",
 		"test:complete": "node tests/test-conditional.mjs && npm run test:post-build",
-		"test:unit": "vitest --config .configs/vitest.config.mjs run",
 		"test:node": "node tests/run-all-tests.mjs",
 		"test:all": "node tests/test-conditional.mjs && npm run test:node",
 		"test:types": "node tests/validate-typescript.mjs",
-		"debug": "node tests/debug-slothlet.mjs",
-		"test:entry": "node tests/test-entry-points.mjs",
-		"test:performance": "node tests/performance-benchmark.mjs",
-		"test:performance-aggregated": "node tests/performance-benchmark-aggregated.mjs",
+		"test:performance": "node tests/performance/performance-benchmark-aggregated.mjs",
+		"test:performance-simple": "node tests/performance/performance-benchmark.mjs",
 		"lint": "eslint --config .configs/eslint.config.mjs .",
-		"build": "node tools/build-with-tests.mjs",
+		"inspect": "node tools/dev/inspect-api-structure.mjs",
+		"check:node-versions": "node tools/dev/check-node-versions.mjs",
+		"analyze": "node tools/dev/analyze-errors.mjs",
+		"fix:headers": "node tools/dev/fix-headers.mjs",
+		"build": "npm run build:dev",
 		"build:ci": "npm run build:cleanup && npm run build:dist && npm run build:types && npm run build:exports && npm run test:types && npm run build:prepend-license && npm run ci:cleanup-src",
+		"build:dev": "npm run build:cleanup && npm run build:dist && npm run build:types && npm run build:exports && npm run test:types && npm run build:prepend-license && npm run build:cleanup",
 		"build:unsafe": "npm run build:cleanup && npm run build:dist && npm run build:types && npm run build:exports && npm run test:types && npm run build:prepend-license",
-		"ci:cleanup-src": "node tools/ci-cleanup-src.mjs",
+		"ci:cleanup-src": "node tools/ci/ci-cleanup-src.mjs",
 		"build:cleanup": "shx rm -rf types && shx rm -rf dist",
-		"build:dist": "shx mkdir -p dist && shx cp -r src/* dist/ && shx rm -rf dist/**/*.backup",
+		"build:dist": "shx mkdir -p dist && node tools/build/build-dist.mjs && shx rm -rf dist/**/*.backup",
 		"build:types": "npx tsc -p .configs/tsconfig.dts.jsonc",
-		"build:docs": "npm run build:docs:slothlet && npm run build:docs:api-tests",
-		"build:docs:slothlet": "jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"src/{slothlet.mjs,lib/{modes,helpers,runtime}/**/*.mjs}\" > docs/generated/API.md",
-		"build:docs:api-tests": "npm run build:docs:api-test && npm run build:docs:api-test-cjs && npm run build:docs:api-test-mixed",
-		"build:docs:api-test": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test/**/*.mjs\" > docs/generated/api_tests/api_test.md",
-		"build:docs:api-test-cjs": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_cjs/**/*.{mjs,cjs}\" > docs/generated/api_tests/api_test_cjs.md",
-		"build:docs:api-test-mixed": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_mixed/**/*.{mjs,cjs}\" > docs/generated/api_tests/api_test_mixed.md",
-		"build:docs:tools": "shx mkdir -p docs/tools && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"tools/**/*.mjs\" > docs/tools/build-tools.md",
-		"build:exports": "node tools/build-exports.mjs",
-		"build:prepend-license": "node tools/prepend-license.mjs dist",
-		"prepublish-check": "npm run build && npm pack && node tools/prepublish-check.mjs"
+		"build:exports": "node tools/build/build-exports.mjs",
+		"build:prepend-license": "node tools/build/prepend-license.mjs dist",
+		"prepublish-check": "npm run build && npm pack && node tools/build/prepublish-check.mjs",
+		"docs:build": "npm run docs:build:slothlet && npm run docs:build:api-tests",
+		"docs:build:slothlet": "jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"src/{slothlet.mjs,lib/**/**/*.mjs}\" > docs/generated/API.md",
+		"publish:manual": "npm publish --access public",
+		"docs:build:api_adb_test": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_adb_test/**/*.mjs\" > docs/generated/api_tests/api_adb_test.md",
+		"docs:build:api_test": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test/**/*.mjs\" > docs/generated/api_tests/api_test.md",
+		"docs:build:api_test-builtin-types": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_builtin_types/**/*.mjs\" > docs/generated/api_tests/api_test_builtin_types.md",
+		"docs:build:api_test-cjs": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_cjs/**/*.{mjs,cjs}\" > docs/generated/api_tests/api_test_cjs.md",
+		"docs:build:api_test-collections": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_collections/**/*.mjs\" > docs/generated/api_tests/api_test_collections.md",
+		"docs:build:api_test-collisions": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_collisions/**/*.mjs\" > docs/generated/api_tests/api_test_collisions.md",
+		"docs:build:api_test-impl": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_impl/**/*.mjs\" > docs/generated/api_tests/api_test_impl.md",
+		"docs:build:api_test-mixed": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_mixed/**/*.{mjs,cjs}\" > docs/generated/api_tests/api_test_mixed.md",
+		"docs:build:api_test-modes-debug": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_modes_debug/**/*.mjs\" > docs/generated/api_tests/api_test_modes_debug.md",
+		"docs:build:api_test-multi-root-fn": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_multi_root_fn/**/*.mjs\" > docs/generated/api_tests/api_test_multi_root_fn.md",
+		"docs:build:api_test-multiple-roots": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_multiple_roots/**/*.mjs\" > docs/generated/api_tests/api_test_multiple_roots.md",
+		"docs:build:api_test-primitives": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_primitives/**/*.mjs\" > docs/generated/api_tests/api_test_primitives.md",
+		"docs:build:api_test-reserved-name": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_reserved_name/**/*.mjs\" > docs/generated/api_tests/api_test_reserved_name.md",
+		"docs:build:api_test-root-issue": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_root_issue/**/*.mjs\" > docs/generated/api_tests/api_test_root_issue.md",
+		"docs:build:api_test-single-root-fn": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_test_single_root_fn/**/*.mjs\" > docs/generated/api_tests/api_test_single_root_fn.md",
+		"docs:build:api_tv_test": "shx mkdir -p docs/generated/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/api_tv_test/**/*.mjs\" > docs/generated/api_tests/api_tv_test.md",
+		"docs:build:sf-addapi": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_addapi/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_addapi.md",
+		"docs:build:sf-addapi-function": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_addapi_function/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_addapi_function.md",
+		"docs:build:sf-addapi-subfolder": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_addapi_subfolder/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_addapi_subfolder.md",
+		"docs:build:sf-addapi-with-folders": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_addapi_with_folders/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_addapi_with_folders.md",
+		"docs:build:sf-bad-module": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_bad_module/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_bad_module.md",
+		"docs:build:sf-conflict": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_conflict/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_conflict.md",
+		"docs:build:sf-file-folder-lazy": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_file_folder_lazy/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_file_folder_lazy.md",
+		"docs:build:sf-fn-file-folder-lazy": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_fn_file_folder_lazy/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_fn_file_folder_lazy.md",
+		"docs:build:sf-fn-fn-folder": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_fn_fn_folder/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_fn_fn_folder.md",
+		"docs:build:sf-folder-config": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_folder_config/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_folder_config.md",
+		"docs:build:sf-folder-different": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_folder_different/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_folder_different.md",
+		"docs:build:sf-folder-with-named": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_folder_with_named/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_folder_with_named.md",
+		"docs:build:sf-lazy-fn-collision": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_lazy_fn_collision/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_lazy_fn_collision.md",
+		"docs:build:sf-lazy-nested-file-folder": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_lazy_nested_file_folder/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_lazy_nested_file_folder.md",
+		"docs:build:sf-multi-export-skip": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_multi_export_skip/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_multi_export_skip.md",
+		"docs:build:sf-multiple": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_multiple/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_multiple.md",
+		"docs:build:sf-nested": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_nested/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_nested.md",
+		"docs:build:sf-none": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_none/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_none.md",
+		"docs:build:sf-nowrap-cases": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_nowrap_cases/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_nowrap_cases.md",
+		"docs:build:sf-object-default-merge": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_object_default_merge/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_object_default_merge.md",
+		"docs:build:sf-obj-fn-folder": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_obj_fn_folder/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_obj_fn_folder.md",
+		"docs:build:sf-single": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_single/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_single.md",
+		"docs:build:sf-solo-subfolder": "shx mkdir -p docs/generated/api_tests/smart_flatten && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"api_tests/smart_flatten/api_smart_flatten_solo_subfolder/**/*.mjs\" > docs/generated/api_tests/smart_flatten/api_smart_flatten_solo_subfolder.md",
+		"docs:build:smart-flatten": "shx mkdir -p docs/generated/api_tests/smart_flatten && npm run docs:build:sf-addapi && npm run docs:build:sf-addapi-function && npm run docs:build:sf-addapi-subfolder && npm run docs:build:sf-addapi-with-folders && npm run docs:build:sf-bad-module && npm run docs:build:sf-conflict && npm run docs:build:sf-file-folder-lazy && npm run docs:build:sf-fn-file-folder-lazy && npm run docs:build:sf-fn-fn-folder && npm run docs:build:sf-folder-config && npm run docs:build:sf-folder-different && npm run docs:build:sf-folder-with-named && npm run docs:build:sf-lazy-fn-collision && npm run docs:build:sf-lazy-nested-file-folder && npm run docs:build:sf-multi-export-skip && npm run docs:build:sf-multiple && npm run docs:build:sf-nested && npm run docs:build:sf-none && npm run docs:build:sf-nowrap-cases && npm run docs:build:sf-object-default-merge && npm run docs:build:sf-obj-fn-folder && npm run docs:build:sf-single && npm run docs:build:sf-solo-subfolder",
+		"docs:build:api-tests": "npm run docs:build:api_adb_test && npm run docs:build:api_test && npm run docs:build:api_test-builtin-types && npm run docs:build:api_test-cjs && npm run docs:build:api_test-collections && npm run docs:build:api_test-collisions && npm run docs:build:api_test-impl && npm run docs:build:api_test-mixed && npm run docs:build:api_test-modes-debug && npm run docs:build:api_test-multi-root-fn && npm run docs:build:api_test-multiple-roots && npm run docs:build:api_test-primitives && npm run docs:build:api_test-reserved-name && npm run docs:build:api_test-root-issue && npm run docs:build:api_test-single-root-fn && npm run docs:build:api_tv_test && npm run docs:build:smart-flatten",
+		"docs:build:tools": "shx mkdir -p docs/tools && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/generated/helpers.cjs\" --template \"docs/generated/template.hbs\" \"tools/dev/**/*.mjs\" > docs/tools/build-tools.md"
 	},
 	"keywords": [
 		"api",
@@ -152,26 +244,47 @@
 		"url": "https://github.com/sponsors/shinrai"
 	},
 	"type": "module",
+	"peerDependencies": {
+		"esbuild": "^0.27.3",
+		"typescript": "^5.9.3"
+	},
+	"peerDependenciesMeta": {
+		"esbuild": {
+			"optional": true
+		},
+		"typescript": {
+			"optional": true
+		}
+	},
 	"devDependencies": {
+		"@cldmv/fix-headers": "^1.2.0",
+		"@cldmv/vitest-runner": "^1.0.3",
 		"@eslint/css": "^0.10.0",
 		"@eslint/js": "^9.33.0",
 		"@eslint/json": "^0.13.1",
 		"@eslint/markdown": "^7.2.0",
-		"@html-eslint/eslint-plugin": "^0.45.0",
 		"@html-eslint/parser": "^0.45.0",
 		"@types/node": "^24.9.1",
+		"@vitest/coverage-v8": "^4.0.18",
 		"chalk": "^5.6.0",
+		"chokidar": "^5.0.0",
 		"dmd": "^7.1.1",
-		"eslint": "^9.33.0",
+		"esbuild": "^0.27.3",
+		"eslint": "^10.0.2",
+		"globals": "^17.4.0",
 		"jsdoc": "^4.0.4",
 		"jsdoc-to-markdown": "^9.1.2",
 		"jsdoc2md": "^1.0.0",
 		"jsonc-parser": "^3.3.1",
 		"prettier": "^3.3.3",
 		"shx": "^0.4.0",
-		"typescript": "^5.9.2",
+		"typescript": "^5.9.3",
 		"vest": "^5.4.6",
-		"vitest": "^3.2.4"
+		"vitest": "^4.0.18"
+	},
+	"overrides": {
+		"minimatch": "^10.2.3",
+		"rollup": "^4.59.0"
 	},
 	"repository": {
 		"type": "git",

package/types/dist/lib/builders/api-assignment.d.mts

@@ -0,0 +1,97 @@
+/**
+ * Manages unified API assignment logic
+ * @class ApiAssignment
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Class-based utility for assigning values to API paths with collision detection,
+ * wrapper sync, and merge operations. Extends ComponentBase for Slothlet property access.
+ *
+ * @example
+ * const assignment = new ApiAssignment(slothlet);
+ * assignment.assignToApiPath(api, "math", mathWrapper, {});
+ */
+export class ApiAssignment extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Check if a value is a UnifiedWrapper proxy
+     * @param {unknown} value - Value to check
+     * @returns {boolean} True if value is a wrapper proxy
+     * @private
+     */
+    private isWrapperProxy;
+    /**
+     * Assign a value to an API object at a given property key.
+     * Handles wrapper sync, collision detection, and proper proxy preservation.
+     *
+     * @param {Object} targetApi - Target object to assign to (may be a UnifiedWrapper proxy)
+     * @param {string|symbol} key - Property name to assign
+     * @param {unknown} value - Value to assign (may be UnifiedWrapper proxy, raw value, etc.)
+     * @param {Object} options - Assignment options
+     * @param {boolean} [options.allowOverwrite=false] - Allow overwriting existing non-wrapper values
+     * @param {boolean} [options.mutateExisting=false] - Sync existing wrappers instead of replacing
+     * @param {boolean} [options.useCollisionDetection=false] - Enable collision detection using config.collision mode
+     * @param {Object} [options.config] - Slothlet config (uses config.collision.initial or config.collision.api)
+     * @param {string} [options.collisionContext="initial"] - Collision context: "initial" or "api"
+     * @param {Function} [options.syncWrapper] - Function to sync two wrapper proxies
+     * @returns {boolean} True if assignment succeeded, false if blocked by collision or other constraint
+     *
+     * @description
+     * This function encapsulates all assignment patterns from processFiles:
+     * - Direct assignment when no collision
+     * - Wrapper sync when both existing and new are wrappers
+     * - Collision detection using config.collision[context] mode (merge/replace/error/skip/warn)
+     * - Proper handling of UnifiedWrapper proxies (preserves them, doesn't unwrap)
+     *
+     * @example
+     * // Direct assignment
+     * assignment.assignToApiPath(api, "math", mathWrapper, {});
+     *
+     * @example
+     * // Sync existing wrapper with new data
+     * assignment.assignToApiPath(api, "config", newConfigWrapper, { mutateExisting: true, syncWrapper });
+     *
+     * @example
+     * // With collision detection
+     * assignment.assignToApiPath(api.math, "add", addFunction, {
+     *     useCollisionDetection: true,
+     *     config,
+     *     collisionContext: "initial"
+     * });
+     */
+    assignToApiPath(targetApi: any, key: string | symbol, value: unknown, options?: {
+        allowOverwrite?: boolean;
+        mutateExisting?: boolean;
+        useCollisionDetection?: boolean;
+        config?: any;
+        collisionContext?: string;
+        syncWrapper?: Function;
+    }): boolean;
+    /**
+     * Recursively merge a source object into a target object using assignToApiPath logic.
+     *
+     * @param {Object} targetApi - Target object
+     * @param {Object} sourceApi - Source object to merge from
+     * @param {Object} options - Assignment options (passed to assignToApiPath)
+     * @param {boolean} [options.removeMissing=false] - Remove keys from target that don't exist in source
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Recursively walks the source object and assigns each value to the target using
+     * assignToApiPath. This provides consistent merge behavior for both initial build
+     * and hot reload operations.
+     *
+     * @example
+     * await assignment.mergeApiObjects(api.config, newConfigApi, {
+     *     mutateExisting: true,
+     *     syncWrapper,
+     *     removeMissing: false
+     * });
+     */
+    mergeApiObjects(targetApi: any, sourceApi: any, options?: {
+        removeMissing?: boolean;
+    }): Promise<void>;
+}
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=api-assignment.d.mts.map

package/types/dist/lib/builders/api-assignment.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-assignment.d.mts","sourceRoot":"","sources":["../../../../dist/lib/builders/api-assignment.mjs"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;GAaG;AACH;IACC,gCAA0C;IAc1C;;;;;OAKG;IACH,uBAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,qCAlCW,MAAM,GAAC,MAAM,SACb,OAAO,YAEf;QAA0B,cAAc,GAAhC,OAAO;QACW,cAAc,GAAhC,OAAO;QACW,qBAAqB,GAAvC,OAAO;QACU,MAAM;QACN,gBAAgB,GAAjC,MAAM;QACa,WAAW;KACtC,GAAU,OAAO,CA+fnB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,0DAfG;QAA0B,aAAa,GAA/B,OAAO;KACf,GAAU,OAAO,CAAC,IAAI,CAAC,CA2FzB;CACD;8BA5pB6B,0CAA0C"}

package/types/dist/lib/builders/api_builder.d.mts

@@ -0,0 +1,96 @@
+/**
+ * Builds final API with built-in methods attached
+ * @class ApiBuilder
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Class-based builder for final API construction with built-in namespace attachment.
+ * Extends ComponentBase for common Slothlet property access.
+ *
+ * @example
+ * const builder = new ApiBuilder(slothlet);
+ * const api = await builder.buildFinalAPI(userApi);
+ */
+export class ApiBuilder extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Build final API with built-in methods attached
+     * @param {Object} userApi - User API object from mode builder
+     * @returns {Promise<Object>} Final API with built-ins attached
+     * @public
+     */
+    public buildFinalAPI(userApi: any): Promise<any>;
+    /**
+     * @param {object} userApi - User API object (for diagnostics).
+     * @returns {Promise<object>} Slothlet namespace object.
+     * @private
+     *
+     * @description
+     * Builds the slothlet namespace with version metadata, API controls, and lifecycle
+     * helpers for the current instance.
+     *
+     * @example
+     * const namespace = await this.createSlothletNamespace(api);
+     */
+    private createSlothletNamespace;
+    /**
+     * Create root-level shutdown function (convenience)
+     * @returns {Function} Shutdown function that dynamically calls user hooks
+     * @private
+     */
+    private createShutdownFunction;
+    /**
+     * Create root-level run function (per-request context isolation)
+     * @returns {Function} Run function that executes callbacks with isolated context
+     * @private
+     */
+    private createRunFunction;
+    /**
+     * Create root-level scope function (structured per-request context with options)
+     * @returns {Function} Scope function that executes functions with isolated context
+     * @private
+     */
+    private createScopeFunction;
+    /**
+     * Create root-level destroy function (permanent destruction)
+     * @param {Object} api - Full API object
+     * @returns {Function} Destroy function that dynamically calls user hooks
+     * @private
+     */
+    private createDestroyFunction;
+    /**
+     * Attach built-in methods to user API
+     * @param {Object} userApi - User API object
+     * @param {Object} builtins - Built-in methods to attach
+     * @private
+     */
+    private attachBuiltins;
+}
+/**
+ * i18n translation helpers exposed on every Slothlet namespace.
+ */
+export type I18nNamespace = {
+    /**
+     * - Set the active locale (e.g. "en-us").
+     */
+    setLanguage: Function;
+    /**
+     * - Return the current active locale string.
+     */
+    getLanguage: Function;
+    /**
+     * - Translate an error code with optional params.
+     */
+    translate: Function;
+    /**
+     * - Alias for translate.
+     */
+    t: Function;
+    /**
+     * - Initialise the i18n system with options.
+     */
+    initI18n: Function;
+};
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=api_builder.d.mts.map

package/types/dist/lib/builders/api_builder.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/builders/api_builder.mjs"],"names":[],"mappings":"AAkEA;;;;;;;;;;;;;GAaG;AACH;IACC,gCAAuC;IAcvC;;;;;OAKG;IACH,oCAHa,OAAO,KAAQ,CAiG3B;IAED;;;;;;;;;;;OAWG;IACH,gCAghCC;IAED;;;;OAIG;IACH,+BAYC;IAED;;;;OAIG;IACH,0BAgCC;IAED;;;;OAIG;IACH,4BAoMC;IAED;;;;;OAKG;IACH,8BAyCC;IAED;;;;;OAKG;IACH,uBAgCC;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;8BAriD6B,0CAA0C"}