@moku-labs/core 0.1.0-alpha.0

package/dist/index.mjs

@@ -0,0 +1,713 @@
+//#region src/utilities.ts
+/**
+* Checks whether a value is a non-null, non-array object record.
+*
+* @param value - Value to inspect.
+* @returns `true` when value is an object record.
+* @example
+* ```ts
+* isRecord({ key: "value" }); // => true
+* isRecord([1, 2, 3]);        // => false
+* isRecord(null);              // => false
+* ```
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Reserved app method names that cannot be used as plugin names.
+*
+* @example
+* ```ts
+* RESERVED_NAMES.has("start"); // true
+* RESERVED_NAMES.has("router"); // false
+* ```
+*/
+const RESERVED_NAMES = new Set([
+	"start",
+	"stop",
+	"emit",
+	"require",
+	"has",
+	"config",
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Check that no plugin name collides with reserved app method names.
+*
+* @param id - Framework identifier for error messages.
+* @param names - Array of plugin names to check.
+* @example
+* ```ts
+* checkReservedNames("my-site", ["router", "seo"]); // ok
+* checkReservedNames("my-site", ["start"]); // throws TypeError
+* ```
+*/
+function checkReservedNames(id, names) {
+	for (const name of names) if (RESERVED_NAMES.has(name)) throw new TypeError(`[${id}] Plugin name "${name}" conflicts with a reserved app method.\n  Choose a different plugin name.`);
+}
+/**
+* Check that no duplicate plugin names exist.
+*
+* @param id - Framework identifier for error messages.
+* @param names - Array of plugin names to check.
+* @example
+* ```ts
+* checkDuplicateNames("my-site", ["router", "seo"]); // ok
+* checkDuplicateNames("my-site", ["router", "router"]); // throws TypeError
+* ```
+*/
+function checkDuplicateNames(id, names) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		if (seen.has(name)) throw new TypeError(`[${id}] Duplicate plugin name: "${name}".\n  Each plugin must have a unique name.`);
+		seen.add(name);
+	}
+}
+/**
+* Check that all dependencies exist and appear before the dependent plugin.
+*
+* @param id - Framework identifier for error messages.
+* @param plugins - The plugin list.
+* @param names - Array of plugin names (same order as plugins).
+* @example
+* ```ts
+* checkDependencyOrder("my-site", [routerPlugin, loggerPlugin], ["router", "logger"]);
+* ```
+*/
+function checkDependencyOrder(id, plugins, names) {
+	for (const [index, plugin] of plugins.entries()) {
+		if (!plugin.spec.depends) continue;
+		for (const dependency of plugin.spec.depends) {
+			const depName = dependency.name;
+			const depIndex = names.indexOf(depName);
+			if (depIndex === -1) throw new TypeError(`[${id}] Plugin "${plugin.name}" depends on "${depName}", but "${depName}" is not registered.\n  Add "${depName}" to your plugin list before "${plugin.name}".`);
+			if (depIndex >= index) throw new TypeError(`[${id}] Plugin "${plugin.name}" depends on "${depName}", but "${depName}" appears after "${plugin.name}".\n  Move "${depName}" before "${plugin.name}" in your plugin list.`);
+		}
+	}
+}
+/**
+* Validate a plugin list for correctness.
+* Checks: no reserved names, no duplicates, dependencies exist and are ordered.
+*
+* @param id - Framework identifier for error messages.
+* @param plugins - The plugin list to validate.
+* @throws {TypeError} If validation fails.
+* @example
+* ```ts
+* validatePlugins("my-site", plugins); // throws if invalid
+* ```
+*/
+function validatePlugins(id, plugins) {
+	const names = plugins.map((p) => p.name);
+	checkReservedNames(id, names);
+	checkDuplicateNames(id, names);
+	checkDependencyOrder(id, plugins, names);
+}
+
+//#endregion
+//#region src/app.ts
+/**
+* Cast a value to Record if it is a non-null object, or return empty object.
+*
+* @param value - The value to cast.
+* @returns The value as a Record, or an empty object if not a non-null object.
+* @example
+* ```ts
+* asRecord({ a: 1 }); // => { a: 1 }
+* asRecord(undefined); // => {}
+* ```
+*/
+function asRecord(value) {
+	return isRecord(value) ? value : {};
+}
+/**
+* Create a require function that looks up a plugin API by instance reference.
+*
+* @param runtime - The kernel runtime containing the API map.
+* @param formatError - Formats the error message using the plugin instance name.
+* @returns A function that returns the API for a given plugin instance or throws.
+* @example
+* ```ts
+* const require = createRequire(runtime, name => `Plugin "${name}" not found.`);
+* const api = require(routerPlugin);
+* ```
+*/
+function createRequire(runtime, formatError) {
+	return (instance) => {
+		const api = runtime.apis.get(instance.name);
+		if (!api) throw new Error(formatError(instance.name));
+		return api;
+	};
+}
+/**
+* Create a has function from the runtime's plugin name set.
+*
+* @param runtime - The kernel runtime containing the plugin name set.
+* @returns A function that checks if a plugin name is registered.
+* @example
+* ```ts
+* const has = createHas(runtime);
+* has("router"); // => true or false
+* ```
+*/
+function createHas(runtime) {
+	return (name) => runtime.pluginNameSet.has(name);
+}
+/**
+* Resolve per-plugin configs: 3-level merge (plugin defaults, framework, consumer), freeze.
+*
+* @param flatPlugins - The flattened plugin list.
+* @param frameworkPluginConfigs - Framework-level plugin config overrides.
+* @param consumerPluginConfigs - Consumer-level plugin config overrides.
+* @returns A map of plugin names to their frozen resolved configs.
+* @example
+* ```ts
+* const configs = resolvePluginConfigs(plugins, frameworkConfigs, consumerConfigs);
+* configs.get("router"); // => { basePath: "/" }
+* ```
+*/
+function resolvePluginConfigs(flatPlugins, frameworkPluginConfigs, consumerPluginConfigs) {
+	const resolvedConfigs = /* @__PURE__ */ new Map();
+	for (const plugin of flatPlugins) {
+		const merged = Object.freeze({
+			...plugin.spec.config,
+			...asRecord(frameworkPluginConfigs[plugin.name]),
+			...asRecord(consumerPluginConfigs[plugin.name])
+		});
+		resolvedConfigs.set(plugin.name, merged);
+	}
+	return resolvedConfigs;
+}
+/**
+* Create plugin state using MinimalContext (global + config only).
+*
+* @param flatPlugins - The flattened plugin list.
+* @param globalConfig - The frozen global config object.
+* @param resolvedConfigs - The resolved per-plugin config map.
+* @returns A map of plugin names to their initial state objects.
+* @example
+* ```ts
+* const states = createPluginStates(plugins, globalConfig, resolvedConfigs);
+* states.get("counter"); // => { count: 0 }
+* ```
+*/
+function createPluginStates(flatPlugins, globalConfig, resolvedConfigs) {
+	const states = /* @__PURE__ */ new Map();
+	for (const plugin of flatPlugins) if (plugin.spec.createState) {
+		const minimalContext = {
+			global: globalConfig,
+			config: resolvedConfigs.get(plugin.name) ?? {}
+		};
+		states.set(plugin.name, plugin.spec.createState(minimalContext));
+	} else states.set(plugin.name, {});
+	return states;
+}
+/**
+* Build event bus: hookMap with async dispatch, fire-and-forget emit, and registerHook.
+*
+* @param onError - Optional error handler for hook execution failures.
+* @returns An object with emit and registerHook functions.
+* @example
+* ```ts
+* const { emit, registerHook } = buildEventBus(error => console.error(error));
+* registerHook("page:view", payload => console.log(payload));
+* emit("page:view", { path: "/" });
+* ```
+*/
+function buildEventBus(onError) {
+	const hookMap = /* @__PURE__ */ new Map();
+	/**
+	* Dispatch an event to all registered handlers sequentially.
+	*
+	* @param eventName - The event name to dispatch.
+	* @param payload - The event payload.
+	* @example
+	* ```ts
+	* await dispatch("page:view", { path: "/" });
+	* ```
+	*/
+	async function dispatch(eventName, payload) {
+		const handlers = hookMap.get(eventName);
+		if (!handlers) return;
+		for (const handler of handlers) try {
+			await handler(payload);
+		} catch (error) {
+			if (onError) onError(error);
+		}
+	}
+	/**
+	* Fire-and-forget emit that dispatches without awaiting.
+	*
+	* @param eventName - The event name to emit.
+	* @param payload - The optional event payload.
+	* @example
+	* ```ts
+	* emit("page:view", { path: "/" });
+	* ```
+	*/
+	const emit = (eventName, payload) => {
+		dispatch(eventName, payload);
+	};
+	/**
+	* Register a hook handler for a given event name.
+	*
+	* @param eventName - The event name to listen for.
+	* @param handler - The handler to invoke when the event fires.
+	* @example
+	* ```ts
+	* registerHook("page:view", payload => console.log(payload));
+	* ```
+	*/
+	const registerHook = (eventName, handler) => {
+		let list = hookMap.get(eventName);
+		if (!list) {
+			list = [];
+			hookMap.set(eventName, list);
+		}
+		list.push(handler);
+	};
+	return {
+		emit,
+		registerHook
+	};
+}
+/**
+* Register hooks from all plugins. Each plugin's hooks(ctx) produces a handler map.
+*
+* @param flatPlugins - The flattened plugin list.
+* @param buildPluginContext - Factory that builds context for a plugin.
+* @param registerHook - Function to register a hook handler for an event.
+* @example
+* ```ts
+* registerPluginHooks(plugins, contextFactory, registerHook);
+* ```
+*/
+function registerPluginHooks(flatPlugins, buildPluginContext, registerHook) {
+	for (const plugin of flatPlugins) if (plugin.spec.hooks) {
+		const hookHandlers = plugin.spec.hooks(buildPluginContext(plugin));
+		for (const [eventName, handler] of Object.entries(hookHandlers)) {
+			if (!handler) continue;
+			registerHook(eventName, handler);
+		}
+	}
+}
+/**
+* Create a factory that builds PluginContext for a given plugin.
+*
+* @param runtime - The kernel runtime with shared state.
+* @param resolvedConfigs - The resolved per-plugin config map.
+* @param states - The plugin state map.
+* @returns A factory function that produces a PluginContext for any plugin.
+* @example
+* ```ts
+* const factory = createContextFactory(runtime, configs, states);
+* const ctx = factory(routerPlugin);
+* ```
+*/
+function createContextFactory(runtime, resolvedConfigs, states) {
+	const has = createHas(runtime);
+	return (plugin) => ({
+		global: runtime.globalConfig,
+		config: resolvedConfigs.get(plugin.name),
+		state: states.get(plugin.name),
+		emit: runtime.emit,
+		require: createRequire(runtime, (name) => `[${runtime.id}] Plugin "${plugin.name}" requires "${name}", but "${name}" is not registered.\n  Add "${name}" to your plugin list.`),
+		has
+	});
+}
+/**
+* Build callback context for consumer lifecycle callbacks (onReady, onStart, onStop).
+*
+* @param runtime - The kernel runtime with shared state and APIs.
+* @returns A dynamic object with config, emit, require, has, and all plugin APIs.
+* @example
+* ```ts
+* const ctx = buildCallbackContext(runtime);
+* ctx.config; // frozen global config
+* ctx.router; // router plugin API (if registered)
+* ```
+*/
+function buildCallbackContext(runtime) {
+	const context = {
+		config: runtime.globalConfig,
+		emit: runtime.emit,
+		require: createRequire(runtime, (name) => `[${runtime.id}] Plugin "${name}" is not registered.\n  Add "${name}" to your plugin list.`),
+		has: createHas(runtime)
+	};
+	for (const [name, api] of runtime.apis) context[name] = api;
+	return context;
+}
+/**
+* Run onStop for all plugins in reverse order.
+*
+* @param flatPlugins - The flattened plugin list.
+* @param globalConfig - The frozen global config object.
+* @example
+* ```ts
+* await executeStop(plugins, globalConfig);
+* ```
+*/
+async function executeStop(flatPlugins, globalConfig) {
+	for (const plugin of flatPlugins.toReversed()) {
+		if (!plugin.spec.onStop) continue;
+		await plugin.spec.onStop({ global: globalConfig });
+	}
+}
+/**
+* Build the frozen app object with start, stop, emit, require, has and mounted plugin APIs.
+*
+* @param runtime - The kernel runtime with shared state and APIs.
+* @param flatPlugins - The flattened plugin list.
+* @param buildPluginContext - Factory that builds context for a plugin.
+* @param consumer - Optional consumer lifecycle callbacks.
+* @returns A frozen app object with lifecycle methods and plugin APIs.
+* @example
+* ```ts
+* const app = buildApp(runtime, plugins, contextFactory, onError, consumer);
+* await app.start();
+* ```
+*/
+function buildApp(runtime, flatPlugins, buildPluginContext, consumer) {
+	let started = false;
+	const appRequire = createRequire(runtime, (name) => `[${runtime.id}] app.require("${name}") failed: "${name}" is not registered.\n  Check your plugin list.`);
+	const appHas = createHas(runtime);
+	const app = {
+		start: async () => {
+			if (started) throw new Error(`[${runtime.id}] App already started.\n  start() can only be called once.`);
+			for (const plugin of flatPlugins) if (plugin.spec.onStart) await plugin.spec.onStart(buildPluginContext(plugin));
+			if (consumer?.onStart) await consumer.onStart(buildCallbackContext(runtime));
+			started = true;
+		},
+		stop: async () => {
+			if (!started) throw new Error(`[${runtime.id}] App not started.\n  Call start() before stop().`);
+			await executeStop(flatPlugins, runtime.globalConfig);
+			if (consumer?.onStop) await consumer.onStop(buildCallbackContext(runtime));
+		},
+		emit: (eventName, payload) => {
+			runtime.emit(eventName, payload);
+		},
+		require: (instance) => appRequire(instance),
+		has: (name) => appHas(name)
+	};
+	for (const [name, api] of runtime.apis) app[name] = api;
+	return Object.freeze(app);
+}
+/**
+* The kernel — creates and initializes the application.
+*
+* Receives pre-flattened, pre-validated plugins and all captured context from
+* createCore. Performs: config resolution, state creation, event bus setup,
+* API building, lifecycle execution, returns frozen app object.
+*
+* @param parameters - All kernel inputs captured from the factory chain.
+* @returns A promise that resolves to the frozen app object.
+* @example
+* ```ts
+* const app = await kernel({ id: "my-app", configDefaults: {}, ... });
+* ```
+*/
+async function kernel(parameters) {
+	const { id, configDefaults, frameworkPluginConfigs, flatPlugins, configOverrides, consumerPluginConfigs, onReady, onError, consumer } = parameters;
+	const pluginNameSet = new Set(flatPlugins.map((plugin) => plugin.name));
+	const globalConfig = Object.freeze({
+		...configDefaults,
+		...configOverrides
+	});
+	const resolvedConfigs = resolvePluginConfigs(flatPlugins, frameworkPluginConfigs, consumerPluginConfigs);
+	const states = createPluginStates(flatPlugins, globalConfig, resolvedConfigs);
+	const apis = /* @__PURE__ */ new Map();
+	const { emit, registerHook } = buildEventBus(onError || consumer?.onError ? (error) => {
+		if (onError) onError(error);
+		if (consumer?.onError) consumer.onError(error, buildCallbackContext(runtime));
+	} : void 0);
+	const runtime = {
+		id,
+		globalConfig,
+		emit,
+		apis,
+		pluginNameSet
+	};
+	const buildPluginContext = createContextFactory(runtime, resolvedConfigs, states);
+	registerPluginHooks(flatPlugins, buildPluginContext, registerHook);
+	for (const plugin of flatPlugins) if (plugin.spec.api) apis.set(plugin.name, plugin.spec.api(buildPluginContext(plugin)));
+	for (const plugin of flatPlugins) if (plugin.spec.onInit) await plugin.spec.onInit(buildPluginContext(plugin));
+	if (onReady) await onReady({ config: globalConfig });
+	if (consumer?.onReady) await consumer.onReady(buildCallbackContext(runtime));
+	return buildApp(runtime, flatPlugins, buildPluginContext, consumer);
+}
+
+//#endregion
+//#region src/core.ts
+/**
+* Creates a bound `createCore` function that captures framework context.
+*
+* Generic parameters:
+* - `Config`: app-wide config from `createCoreConfig`
+* - `Events`: app-wide events from `createCoreConfig`
+*
+* @param frameworkId - The framework identifier for error messages.
+* @param configDefaults - Default config values captured from Step 1.
+* @param createPlugin - Bound createPlugin function from Step 1.
+* @returns A createCore function bound to the framework's Config and Events types.
+* @example
+* ```ts
+* const createCore = createCoreFactory<MyConfig, MyEvents>(
+*   "my-app", configDefaults, createPlugin
+* );
+* ```
+*/
+function createCoreFactory(frameworkId, configDefaults, createPlugin) {
+	/**
+	* Step 2: Captures framework default plugins and returns createApp.
+	*
+	* @param _coreConfig - The CoreConfigResult object (for type flow only).
+	* @param coreOptions - Framework-level defaults: plugins, pluginConfigs, onReady, onError.
+	* @returns An object with createApp (async function) and createPlugin (same reference).
+	* @example
+	* ```ts
+	* const { createApp, createPlugin } = createCore(coreConfig, { plugins: [routerPlugin] });
+	* ```
+	*/
+	const createCore = (_coreConfig, coreOptions) => {
+		const options = coreOptions;
+		const defaultPlugins = options.plugins;
+		const frameworkPluginConfigs = options.pluginConfigs ?? {};
+		const onReady = options.onReady;
+		const onError = options.onError;
+		/**
+		* Step 3: Creates and initializes the application.
+		* Merges consumer options with framework defaults, flattens and validates
+		* plugins, then delegates to the kernel for lifecycle execution.
+		*
+		* @param consumerOptions - Consumer-level config, plugins, and callbacks.
+		* @returns A promise that resolves to the frozen App object.
+		* @example
+		* ```ts
+		* const app = await createApp({ config: { siteName: "Blog" } });
+		* ```
+		*/
+		const createApp = async (consumerOptions) => {
+			const appOptions = consumerOptions ?? {};
+			const allPlugins = [...defaultPlugins, ...appOptions.plugins ?? []];
+			validatePlugins(frameworkId, allPlugins);
+			return kernel({
+				id: frameworkId,
+				configDefaults,
+				frameworkPluginConfigs,
+				flatPlugins: allPlugins,
+				configOverrides: appOptions.config ?? {},
+				consumerPluginConfigs: appOptions.pluginConfigs ?? {},
+				onReady,
+				onError,
+				consumer: {
+					onReady: appOptions.onReady,
+					onError: appOptions.onError,
+					onStart: appOptions.onStart,
+					onStop: appOptions.onStop
+				}
+			});
+		};
+		return {
+			createApp,
+			createPlugin
+		};
+	};
+	return createCore;
+}
+
+//#endregion
+//#region src/plugin.ts
+/**
+* Asserts that a plugin name is a non-empty string.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param name - Candidate plugin name.
+* @example
+* ```ts
+* assertValidPluginName("my-app", "router");
+* ```
+*/
+function assertValidPluginName(frameworkId, name) {
+	if (typeof name === "string" && name.length > 0) return;
+	throw new TypeError(`[${frameworkId}] Plugin name must be a non-empty string.\n  Pass a non-empty string as the first argument.`);
+}
+/**
+* Asserts that the plugin spec is a non-null object.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param spec - Candidate plugin spec.
+* @example
+* ```ts
+* assertValidPluginSpec("my-app", "router", { onInit: () => {} });
+* ```
+*/
+function assertValidPluginSpec(frameworkId, pluginName, spec) {
+	if (isRecord(spec)) return;
+	throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid spec: expected an object.\n  Provide a plugin specification object as the second argument.`);
+}
+/**
+* Validates lifecycle handlers (`onInit`, `onStart`, `onStop`) if provided.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param spec - Runtime plugin spec.
+* @example
+* ```ts
+* assertValidLifecycleHandlers("my-app", "router", { onStart: () => {} });
+* ```
+*/
+function assertValidLifecycleHandlers(frameworkId, pluginName, spec) {
+	for (const methodName of [
+		"onInit",
+		"onStart",
+		"onStop"
+	]) {
+		const methodValue = spec[methodName];
+		if (methodValue !== void 0 && typeof methodValue !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid ${methodName}: expected a function.\n  Provide a function for ${methodName} or remove it from the spec.`);
+	}
+}
+/**
+* Validates that events is a function (the register callback factory) if provided.
+* The kernel does not call events at runtime — it exists for compile-time type inference.
+* This validation catches typos like `events: { ... }` instead of `events: register => ({ ... })`.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param events - Candidate events value from plugin spec.
+* @example
+* ```ts
+* assertValidEvents("my-app", "auth", register => ({ "auth:login": register<{ userId: string }>() }));
+* ```
+*/
+function assertValidEvents(frameworkId, pluginName, events) {
+	if (events === void 0) return;
+	if (typeof events !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid events: expected a function.\n  Provide a function like: events: register => ({ "event:name": register<PayloadType>() })`);
+}
+/**
+* Validates that hooks is a function (the context-receiving factory).
+* The return value (handler map) is validated at kernel time when hooks(ctx) is called.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param hooks - Candidate hooks value from plugin spec.
+* @example
+* ```ts
+* assertValidHooks("my-app", "router", ctx => ({ "route:change": () => {} }));
+* ```
+*/
+function assertValidHooks(frameworkId, pluginName, hooks) {
+	if (hooks === void 0) return;
+	if (typeof hooks !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid hooks: expected a function.\n  Provide a function like: hooks: ctx => ({ "event:name": payload => { ... } })`);
+}
+/**
+* Validates that `api` is a function if provided.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param api - Candidate api value from plugin spec.
+* @example
+* ```ts
+* assertValidApi("my-app", "router", ctx => ({ navigate: () => {} }));
+* ```
+*/
+function assertValidApi(frameworkId, pluginName, api) {
+	if (api !== void 0 && typeof api !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid api: expected a function.\n  Provide a function like: api: ctx => ({ methodName: () => { ... } })`);
+}
+/**
+* Validates that `createState` is a function if provided.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param createState - Candidate createState value from plugin spec.
+* @example
+* ```ts
+* assertValidCreateState("my-app", "router", ctx => ({ count: 0 }));
+* ```
+*/
+function assertValidCreateState(frameworkId, pluginName, createState) {
+	if (createState !== void 0 && typeof createState !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid createState: expected a function.\n  Provide a function like: createState: ctx => ({ key: initialValue })`);
+}
+/**
+* Creates a bound `createPlugin` function that captures framework generics.
+*
+* Generic parameters:
+* - `GlobalConfig`: app-wide config from `createCoreConfig`
+* - `GlobalEventMap`: app-wide events from `createCoreConfig`
+*
+* @param frameworkId - The framework identifier for error messages.
+* @returns A createPlugin function bound to the framework's Config and Events types.
+* @example
+* ```ts
+* const createPlugin = createPluginFactory<MyConfig, MyEvents>("my-app");
+* const plugin = createPlugin("router", { config: { basePath: "/" } });
+* ```
+*/
+function createPluginFactory(frameworkId) {
+	/**
+	* Creates a plugin instance with inferred types from the spec object.
+	*
+	* @param name - Unique plugin name (inferred as literal string type).
+	* @param spec - Plugin specification with config, state, api, lifecycle, hooks.
+	* @returns A PluginInstance carrying phantom types for compile-time inference.
+	* @example
+	* ```ts
+	* const router = createPlugin("router", {
+	*   config: { basePath: "/" },
+	*   api: (ctx) => ({ navigate: (path: string) => path }),
+	* });
+	* ```
+	*/
+	const createPlugin = (name, spec) => {
+		assertValidPluginName(frameworkId, name);
+		assertValidPluginSpec(frameworkId, name, spec);
+		assertValidLifecycleHandlers(frameworkId, name, spec);
+		assertValidEvents(frameworkId, name, spec.events);
+		assertValidHooks(frameworkId, name, spec.hooks);
+		assertValidApi(frameworkId, name, spec.api);
+		assertValidCreateState(frameworkId, name, spec.createState);
+		return {
+			name,
+			spec,
+			_phantom: {}
+		};
+	};
+	return createPlugin;
+}
+
+//#endregion
+//#region src/config.ts
+/**
+* Step 1 of the 3-step factory chain. Captures Config and Events generics
+* in a closure and returns { createPlugin, createCore }.
+*
+* This is the ONLY export from `@moku-labs/core`. All downstream types flow from
+* the generics captured here.
+*
+* @param id - Framework identifier used in error messages.
+* @param options - Configuration options containing the default config values.
+* @param options.config - Default configuration values for the framework.
+* @returns An object with createPlugin (bound to Config/Events) and createCore.
+* @example
+* ```ts
+* const coreConfig = createCoreConfig<SiteConfig, SiteEvents>("my-site", {
+*   config: { siteName: "Untitled", mode: "development" }
+* });
+* const { createPlugin, createCore } = coreConfig;
+* ```
+*/
+function createCoreConfig(id, options) {
+	const configDefaults = options.config;
+	const frameworkId = id;
+	const createPlugin = createPluginFactory(frameworkId);
+	return {
+		createPlugin,
+		createCore: createCoreFactory(frameworkId, configDefaults, createPlugin)
+	};
+}
+
+//#endregion
+export { createCoreConfig };