@moku-labs/core 0.1.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,900 @@
+//#region src/utilities.d.ts
+/**
+* Base constraint for framework configuration objects.
+*
+* @example
+* ```ts
+* function createConfig<C extends FrameworkConfig>(defaults: C): C { return defaults; }
+* ```
+*/
+type FrameworkConfig = Record<string, unknown>;
+/**
+* Base constraint for framework event maps.
+*
+* @example
+* ```ts
+* function createEvents<E extends FrameworkEventMap>(events: E): E { return events; }
+* ```
+*/
+type FrameworkEventMap = Record<string, unknown>;
+/**
+* Empty event map used as the default when a plugin declares no custom events.
+* `Record<never, never>` is the identity element for intersection (`T & {} = T`).
+*
+* @example
+* ```ts
+* type PluginEvents = EmptyPluginEventMap; // default when no events declared
+* ```
+*/
+type EmptyPluginEventMap = Record<never, never>;
+/**
+* Convert a union to an intersection via distributive conditional + contra-variance.
+*
+* @example
+* ```ts
+* type Result = UnionToIntersection<{ a: 1 } | { b: 2 }>; // { a: 1 } & { b: 2 }
+* ```
+*/
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/**
+* Detect if a string type is a literal (e.g. "router") vs the general `string` type.
+* Used by BuildPluginApis to exclude plugins with non-literal names from the mapped type.
+*
+* @example
+* ```ts
+* type Yes = IsLiteralString<"router">; // true
+* type No = IsLiteralString<string>;    // false
+* ```
+*/
+type IsLiteralString<S extends string> = string extends S ? false : true;
+/**
+* Auto-generate overloaded emit call signatures from an event map type.
+*
+* Converts `{ "a": X; "b": Y }` into `((name: "a", payload: X) => void) & ((name: "b", payload: Y) => void)`.
+* Uses `UnionToIntersection` to transform a union of per-event functions into
+* an intersection (overloaded call signatures).
+*
+* When `E` has no keys, produces an uncallable but constructible function type
+* so `vi.fn()` and `() => {}` remain assignable while calling emit is a compile error.
+*
+* Exported from the package entry point for plugin authors at Standard+ tier.
+*
+* @example
+* ```ts
+* type CmsEmit = EmitFn<{
+*   "cms:publish": { contentId: string; path: string };
+*   "cms:draft": { contentId: string };
+* }>;
+* // Equivalent to:
+* // ((name: "cms:publish", payload: { contentId: string; path: string }) => void)
+* // & ((name: "cms:draft", payload: { contentId: string }) => void)
+* ```
+*/
+type EmitFunction<E extends Record<string, unknown>> = [keyof E] extends [never] ? (...arguments_: never[]) => void : UnionToIntersection<{ [K in string & keyof E]: (name: K, payload: E[K]) => void }[string & keyof E]>;
+/**
+* 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
+* ```
+*/
+//#endregion
+//#region src/types.d.ts
+/**
+* Teardown context — the most minimal context tier.
+* Used by: onStop
+*
+* During teardown, plugins may be partially or fully stopped. Only the frozen
+* global config is available.
+*
+* @example
+* ```ts
+* type StopCtx = TeardownContext<{ siteName: string }>;
+* // => { readonly global: Readonly<{ siteName: string }> }
+*
+* // Used in plugin spec:
+* onStop: (ctx: StopCtx) => { console.log(`Stopping ${ctx.global.siteName}`); }
+* ```
+*/
+type TeardownContext<Config> = {
+  readonly global: Readonly<Config>;
+};
+/**
+* Minimal context — teardown context plus plugin config.
+* Used by: createState
+*
+* At this stage, not all plugins have been created yet. Communication methods
+* (emit, require, has) are intentionally unavailable.
+*
+* @example
+* ```ts
+* type StateCtx = MinimalContext<{ siteName: string }, { basePath: string }>;
+* // => { readonly global: ...; readonly config: Readonly<{ basePath: string }> }
+*
+* // Used in plugin spec:
+* createState: (ctx: StateCtx) => ({ currentPath: ctx.config.basePath })
+* ```
+*/
+type MinimalContext<Config, C> = {
+  readonly global: Readonly<Config>;
+  readonly config: Readonly<C>;
+};
+/**
+* Full plugin context — everything is live.
+* Used by: api, onInit, onStart
+*
+* Provides global config, plugin config, mutable state, event emission,
+* and inter-plugin communication.
+*
+* @example
+* ```ts
+* type Ctx = PluginContext<
+*   { siteName: string },
+*   { "page:view": { path: string } },
+*   { basePath: string },
+*   { count: number }
+* >;
+* // => { global, config, state, emit, require, has }
+*
+* // Used in plugin spec:
+* api: (ctx: Ctx) => ({
+*   navigate: (path: string) => { ctx.state.count += 1; ctx.emit("page:view", { path }); }
+* })
+* ```
+*/
+type PluginContext<Config, Events extends Record<string, unknown>, C, S> = {
+  readonly global: Readonly<Config>;
+  readonly config: Readonly<C>;
+  state: S;
+  emit: EmitFunction$1<Events>;
+  require: RequireFunction;
+  has: HasFunction;
+};
+/**
+* Strictly typed emit function (kernel-layer generic signature).
+* Only known event names are accepted, with matching payload required.
+*
+* This is the compile-time generic signature used by PluginContext and App.
+* app.ts defines a separate runtime-layer `EmitFunction` alias without generics
+* for dynamically typed dispatch — they are intentionally different.
+*
+* @example
+* ```ts
+* type Emit = EmitFunction<{ "page:view": { path: string }; "auth:login": { userId: string } }>;
+*
+* declare const emit: Emit;
+* emit("page:view", { path: "/" });   // OK — known event with correct payload
+* // emit("page:view", { url: "/" }); // Error — wrong payload shape
+* // emit("unknown", {});             // Error — unknown event name
+* ```
+*/
+type EmitFunction$1<Events extends Record<string, unknown>> = <K extends string & keyof Events>(name: K, payload: Events[K]) => void;
+/**
+* Get a dependency plugin's API by instance reference.
+* Accepts only PluginInstance values (not strings). Returns the fully typed API
+* extracted from the phantom type, or throws at runtime if not registered.
+*
+* @example
+* ```ts
+* declare const require: RequireFunction;
+* const api = require(routerPlugin); // => typeof routerPlugin's API
+* // api.navigate("/about");         // fully typed — method comes from phantom type
+* ```
+*/
+type RequireFunction = <P extends PluginInstance<string, any, any, any, any>>(plugin: P) => ExtractApi<P>;
+/**
+* Check if a plugin is registered by name. String-based boolean check.
+* Unlike require, this accepts a plain string and returns a boolean instead of throwing.
+*
+* @example
+* ```ts
+* declare const has: HasFunction;
+* if (has("analytics")) {
+*   // analytics plugin is registered — safe to require
+* }
+* ```
+*/
+type HasFunction = (name: string) => boolean;
+/**
+* Plugin specification — the shape passed to createPlugin.
+*
+* All generics (N, C, S, A) are inferred from the spec object values.
+* Config and Events flow from the createCoreConfig closure.
+* PluginEvents is the only explicit generic (defines new events).
+*
+* @example
+* ```ts
+* // Rarely written explicitly — inferred from createPlugin spec object.
+* // The kernel uses this type internally to constrain spec shapes:
+* type RouterSpec = PluginSpec<SiteConfig, SiteEvents, RouterEvents,
+*   { basePath: string }, { currentPath: string },
+*   { navigate(path: string): void }, readonly []>;
+* ```
+*/
+type PluginSpec<Config, Events extends Record<string, unknown>, PluginEvents extends Record<string, unknown>, C, S, A extends Record<string, any>, Deps extends ReadonlyArray<PluginInstance<string, any, any, any, any>>> = {
+  config?: C;
+  depends?: Deps;
+  createState?: (context: MinimalContext<Config, C>) => S;
+  api?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => A;
+  onInit?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void | Promise<void>;
+  onStart?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void | Promise<void>;
+  onStop?: (context: TeardownContext<Config>) => void | Promise<void>;
+  hooks?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => { [K in string & keyof (Events & PluginEvents & DepsEvents<Deps>)]?: (payload: (Events & PluginEvents & DepsEvents<Deps>)[K]) => void | Promise<void> };
+};
+/**
+* Plugin instance — the return value of createPlugin.
+*
+* Carries phantom types for compile-time type inference. The _phantom field
+* is never read at runtime (it is `{} as { ... }`).
+*
+* @example
+* ```ts
+* // Created via createPlugin — types are inferred, not written:
+* const router = createPlugin("router", {
+*   config: { basePath: "/" },
+*   api: ctx => ({ navigate: (path: string) => path }),
+* });
+* // router: PluginInstance<"router", { basePath: string }, ..., { navigate(path: string): string }>
+* ```
+*/
+interface PluginInstance<N extends string = string, C = void, S = void, A extends Record<string, any> = Record<string, never>, PluginEvents extends Record<string, unknown> = {}> {
+  readonly name: N;
+  readonly spec: PluginSpec<any, any, any, C, S, A, any>;
+  readonly _phantom: {
+    config: C;
+    state: S;
+    api: A;
+    events: PluginEvents;
+  };
+}
+/**
+* Widened PluginInstance type for generic constraints on arrays.
+* Used across multiple modules (utilities, core, app) for plugin list parameters.
+*
+* @example
+* ```ts
+* function processPlugins(plugins: AnyPluginInstance[]): void { ... }
+* ```
+*/
+type AnyPluginInstance = PluginInstance<string, any, any, any, any>;
+/**
+* Extract the API phantom type from a PluginInstance.
+* Used by RequireFunction to return the correct API type from require(plugin).
+*
+* @example
+* ```ts
+* type RouterApi = ExtractApi<typeof routerPlugin>; // { navigate(path: string): void }
+* ```
+*/
+type ExtractApi<P> = P extends PluginInstance<string, any, any, infer A, any> ? A : never;
+/**
+* Extract the events phantom type from a PluginInstance.
+* Used by DepsEvents to merge event maps from dependency plugins.
+*
+* @example
+* ```ts
+* type RouterEvents = ExtractEvents<typeof routerPlugin>;
+* // { "router:navigate": { from: string; to: string } }
+* ```
+*/
+type ExtractEvents<P> = P extends PluginInstance<string, any, any, any, infer E> ? E : never;
+/**
+* Extract the name literal type from a PluginInstance.
+* Used by BuildPluginApis to key the app surface by plugin name.
+*
+* @example
+* ```ts
+* type Name = ExtractName<typeof routerPlugin>; // "router"
+* ```
+*/
+type ExtractName<P> = P extends PluginInstance<infer N, any, any, any, any> ? N : never;
+/**
+* Extract the config phantom type from a PluginInstance.
+* Used by CreateAppOptions to type pluginConfigs keys.
+*
+* @example
+* ```ts
+* type RouterConfig = ExtractConfig<typeof routerPlugin>; // { basePath: string }
+* ```
+*/
+type ExtractConfig<P> = P extends PluginInstance<string, infer C, any, any, any> ? C : never;
+/**
+* Intersection of all PluginEvents from a depends tuple.
+* Merges events from [authPlugin, routerPlugin] into AuthEvents & RouterEvents.
+* Falls back to `{}` (identity element) when the tuple is empty.
+*
+* @example
+* ```ts
+* type Combined = DepsEvents<readonly [typeof authPlugin, typeof routerPlugin]>;
+* // => { "auth:login": { userId: string } } & { "router:navigate": { path: string } }
+* ```
+*/
+type DepsEvents<Deps extends ReadonlyArray<PluginInstance<string, any, any, any, any>>> = Deps[number] extends never ? {} : UnionToIntersection<ExtractEvents<Deps[number]>>;
+/**
+* Map a plugin tuple to `{ [Name]: Api }` for the app surface.
+* Plugins with empty API (Record<string, never>) are excluded.
+* Plugins with non-literal name type (string) are excluded to prevent
+* index signature pollution on the App type.
+*
+* @example
+* ```ts
+* type Apis = BuildPluginApis<typeof routerPlugin | typeof authPlugin>;
+* // => { router: { navigate(path: string): void }; auth: { login(): void } }
+* ```
+*/
+type BuildPluginApis<P extends PluginInstance<string, any, any, any, any>> = { [K in P as ExtractApi<K> extends Record<string, never> ? never : IsLiteralString<ExtractName<K>> extends true ? ExtractName<K> : never]: ExtractApi<K> };
+/**
+* Typed App object returned by createApp.
+* Combines base methods (start, stop, emit, require, has) with plugin APIs
+* mapped by name via BuildPluginApis.
+*
+* @example
+* ```ts
+* type MyApp = App<SiteConfig, SiteEvents, typeof routerPlugin | typeof authPlugin>;
+* // => { start, stop, emit, require, has, router: RouterApi, auth: AuthApi }
+*
+* declare const app: MyApp;
+* await app.start();
+* app.router.navigate("/about");
+* ```
+*/
+type App<_Config extends Record<string, unknown>, Events extends Record<string, unknown>, P extends PluginInstance<string, any, any, any, any>> = {
+  readonly start: () => Promise<void>;
+  readonly stop: () => Promise<void>;
+  readonly emit: EmitFunction$1<Events>;
+  readonly require: RequireFunction;
+  readonly has: HasFunction;
+} & BuildPluginApis<P>;
+/**
+* Context passed to consumer lifecycle callbacks (onReady, onStart, onStop).
+* Includes frozen config, event emission, plugin lookup, and mounted plugin APIs.
+*
+* @example
+* ```ts
+* type Ctx = AppCallbackContext<SiteConfig, SiteEvents, typeof routerPlugin>;
+* // => { config, emit, require, has, router: RouterApi }
+*
+* // Used in createApp options:
+* onReady: (ctx: Ctx) => { ctx.router.navigate("/home"); }
+* ```
+*/
+type AppCallbackContext<Config extends Record<string, unknown>, Events extends Record<string, unknown>, P extends PluginInstance<string, any, any, any, any>> = {
+  readonly config: Readonly<Config>;
+  readonly emit: EmitFunction$1<Events>;
+  readonly require: RequireFunction;
+  readonly has: HasFunction;
+} & BuildPluginApis<P>;
+/**
+* Options for createApp (Step 3). Structured namespaces replace flat key discrimination:
+* - `plugins`: extra consumer plugins
+* - `config`: global config overrides (shallow-merged with framework defaults)
+* - `pluginConfigs`: per-plugin config overrides keyed by plugin name
+* - `onReady/onError/onStart/onStop`: consumer lifecycle callbacks
+*
+* @example
+* ```ts
+* const app = await createApp({
+*   config: { siteName: "My Blog" },
+*   pluginConfigs: { router: { basePath: "/blog" } },
+*   onReady: ctx => { console.log("App ready:", ctx.config.siteName); },
+* });
+* ```
+*/
+type CreateAppOptions<Config extends Record<string, unknown>, Events extends Record<string, unknown>, P extends PluginInstance<string, any, any, any, any>, ExtraPlugins extends readonly PluginInstance<string, any, any, any, any>[]> = {
+  plugins?: ExtraPlugins;
+  config?: { [K in keyof Config]?: Config[K] };
+  pluginConfigs?: { [K in P as ExtractConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractName<K>> extends true ? ExtractName<K> : never]?: Partial<ExtractConfig<K>> };
+  onReady?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
+  onError?: (error: Error, context: AppCallbackContext<Config, Events, P>) => void;
+  onStart?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
+  onStop?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
+};
+/**
+* Domain context type for extracted plugin files (api.ts, handlers.ts, etc.).
+*
+* Provides `config`, `state`, and strictly typed `emit` with overloaded call
+* signatures auto-generated from the event map `E`. Replaces manual overload
+* declarations that must be kept in sync with the event type.
+*
+* For plugins without events, omit `E` — emit becomes uncallable.
+* For advanced composition (e.g., adding `require`), use `EmitFn<E>` directly.
+*
+* @example
+* ```ts
+* import type { PluginCtx } from "@moku-labs/core";
+*
+* type CmsEvents = {
+*   "cms:publish": { contentId: string; path: string };
+*   "cms:draft": { contentId: string };
+* };
+*
+* // One line replaces manual emit overloads:
+* type CmsCtx = PluginCtx<CmsConfig, CmsState, CmsEvents>;
+*
+* // Use in domain factories:
+* export const createCmsApi = (ctx: CmsCtx) => ({
+*   publish: (id: string, path: string) => {
+*     ctx.emit("cms:publish", { contentId: id, path }); // strictly typed
+*   },
+* });
+* ```
+*/
+type PluginContext_<C, S, E extends Record<string, unknown> = Record<never, never>> = {
+  readonly config: Readonly<C>;
+  state: S;
+  emit: EmitFunction<E>;
+};
+//#endregion
+//#region src/plugin.d.ts
+/**
+* Structural plugin shape used for generic constraints without variance issues.
+*
+* @example
+* ```ts
+* const pluginRef: PluginLike = somePlugin;
+* ```
+*/
+type PluginLike = {
+  readonly name: string;
+  readonly spec: unknown;
+  readonly _phantom: {
+    readonly config: unknown;
+    readonly state: unknown;
+    readonly api: unknown;
+    readonly events: Record<string, unknown>;
+  };
+};
+/**
+* Readonly dependency tuple accepted by `depends`.
+*
+* @example
+* ```ts
+* const deps: DependencyPluginTuple = [];
+* ```
+*/
+type DependencyPluginTuple = readonly PluginLike[];
+/**
+* Extracts API type from a plugin-like value.
+*
+* @example
+* ```ts
+* type Api = ExtractPluginApi<typeof somePlugin>;
+* ```
+*/
+type ExtractPluginApi<PluginCandidate> = PluginCandidate extends {
+  readonly _phantom: {
+    readonly api: infer PluginApi;
+  };
+} ? PluginApi : never;
+/**
+* Extracts event map type from a plugin-like value.
+*
+* @example
+* ```ts
+* type Events = ExtractPluginEvents<typeof somePlugin>;
+* ```
+*/
+type ExtractPluginEvents<PluginCandidate> = PluginCandidate extends {
+  readonly _phantom: {
+    readonly events: infer PluginEvents;
+  };
+} ? PluginEvents extends Record<string, unknown> ? PluginEvents : EmptyPluginEventMap : EmptyPluginEventMap;
+/**
+* Event map contributed by all dependency plugins.
+*
+* @example
+* ```ts
+* type DepEvents = DependencyEvents<readonly [authPlugin, routerPlugin]>;
+* ```
+*/
+type DependencyEvents<DependencyPlugins extends DependencyPluginTuple> = DependencyPlugins[number] extends never ? EmptyPluginEventMap : UnionToIntersection<ExtractPluginEvents<DependencyPlugins[number]>>;
+/**
+* Intersection of framework events, plugin events, and dependency events.
+*
+* @example
+* ```ts
+* type AllEvents = MergedPluginEvents<SiteConfigEvents, RouterEvents, readonly [authPlugin]>;
+* ```
+*/
+type MergedPluginEvents<GlobalEventMap extends FrameworkEventMap, PluginEventMap extends Record<string, unknown>, DependencyPlugins extends DependencyPluginTuple> = GlobalEventMap & PluginEventMap & DependencyEvents<DependencyPlugins>;
+/**
+* Runtime context for `api`, `onInit`, and `onStart`.
+*
+* Generic parameters:
+* - `GlobalConfig`: frozen app-wide config from `createCoreConfig`
+* - `AllEvents`: merged events the plugin can emit
+* - `PluginConfig`: this plugin's config slice
+* - `PluginState`: mutable plugin state
+*
+* @example
+* ```ts
+* type Ctx = PluginExecutionContext<
+*   SiteConfig,
+*   SiteEvents,
+*   { basePath: string },
+*   { currentPath: string }
+* >;
+* ```
+*/
+type PluginExecutionContext<GlobalConfig extends FrameworkConfig, AllEvents extends Record<string, unknown>, PluginConfig, PluginState> = {
+  /**
+  * Frozen app-wide config from `createCoreConfig`. Shared by all plugins.
+  *
+  * @example
+  * ```ts
+  * const siteUrl = ctx.global.siteUrl;
+  * ```
+  */
+  readonly global: Readonly<GlobalConfig>;
+  /**
+  * Frozen plugin-specific config. Defaults from the plugin spec, shallow-merged
+  * with consumer overrides.
+  *
+  * @example
+  * ```ts
+  * const base = ctx.config.basePath; // from plugin defaults or consumer override
+  * ```
+  */
+  readonly config: Readonly<PluginConfig>;
+  /**
+  * Mutable plugin state created by `createState`. The only mutable store in the system.
+  *
+  * @example
+  * ```ts
+  * ctx.state.count += 1;
+  * ctx.state.cache.set(key, value);
+  * ```
+  */
+  state: PluginState;
+  /**
+  * Dispatch a typed event. Only known event names are accepted (no escape hatch).
+  *
+  * @example
+  * ```ts
+  * ctx.emit("auth:login", { userId: "123" });
+  * ```
+  */
+  emit: EmitFunction$1<AllEvents>;
+  /**
+  * Get a registered plugin's API by instance reference. Throws if the plugin is not registered.
+  * Accepts any plugin instance, not just declared dependencies (not strings).
+  *
+  * @example
+  * ```ts
+  * const http = ctx.require(httpPlugin);
+  * http.use(authMiddleware);
+  * ```
+  */
+  require: <PluginCandidate extends PluginLike>(plugin: PluginCandidate) => ExtractPluginApi<PluginCandidate>;
+  /**
+  * Check if a plugin is registered by name. String-based (boolean check only).
+  *
+  * @example
+  * ```ts
+  * if (ctx.has("analytics")) { ... }
+  * ```
+  */
+  has: (name: string) => boolean;
+};
+/**
+* Descriptor returned by register(). Carries the payload type.
+* and an optional description string for runtime event catalogs.
+*/
+type EventDescriptor<PayloadType = unknown> = {
+  readonly description: string; /** Phantom field — carries `PayloadType` for inference. Never set at runtime. */
+  readonly _type?: PayloadType;
+};
+/**
+* The register function passed to the events callback.
+* Two usage modes:
+* - `register<T>(description?)` — register a single event with payload type `T`.
+* - `register.map<EventMap>(descriptions?)` — bulk-register all events from a
+*   pre-declared event map type. Eliminates per-event `register<Events["name"]>()` calls.
+*
+* @example
+* ```ts
+* // Individual registration (inline event types):
+* events: register => ({
+*   "auth:login": register<{ userId: string }>("Triggered after login"),
+* })
+*
+* // Bulk registration (Standard+ plugins with separate XxxEvents type):
+* events: register => register.map<AuthEvents>({
+*   "auth:login": "Triggered after login",
+*   "auth:logout": "Triggered after logout",
+* })
+* ```
+*/
+type RegisterFunction = {
+  <PayloadType>(description?: string): EventDescriptor<PayloadType>;
+  map: <EventMap extends Record<string, unknown>>(descriptions?: { [K in keyof EventMap]?: string }) => { [K in keyof EventMap]: EventDescriptor<EventMap[K]> };
+};
+/**
+* Specification object passed to `createPlugin`.
+*
+* Generic parameters:
+* - `GlobalConfig`: app-wide config object
+* - `GlobalEventMap`: app-wide events from `createCoreConfig`
+* - `PluginEventMap`: plugin-specific events declared by `events`
+* - `PluginConfig`: plugin config shape from `config`
+* - `PluginState`: mutable state returned by `createState`
+* - `PluginApi`: API returned by `api`
+* - `DependencyPlugins`: tuple from `depends`
+*
+* @example
+* ```ts
+* type RouterSpec = CreatePluginSpec<
+*   SiteConfig,
+*   SiteEvents,
+*   Record<never, never>,
+*   { basePath: string },
+*   { currentPath: string },
+*   { navigate(path: string): void },
+*   readonly []
+* >;
+* ```
+*/
+type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, PluginEventMap extends Record<string, unknown>, PluginConfig extends Record<string, unknown>, PluginState, PluginApi extends Record<string, unknown>, DependencyPlugins extends DependencyPluginTuple> = {
+  /**
+  * Declare plugin-specific events via a register callback.
+  * Used for compile-time type inference only — the kernel does not call this at runtime.
+  *
+  * @example
+  * ```ts
+  * events: (register) => ({
+  *   "auth:login": register<{ userId: string }>("Triggered after user login"),
+  *   "auth:logout": register<{ userId: string }>("Triggered after user logout"),
+  * })
+  * ```
+  */
+  events?: (register: RegisterFunction) => { [EventName in keyof PluginEventMap]: EventDescriptor<PluginEventMap[EventName]> };
+  /**
+  * Default config values for this plugin. Consumers can override via `pluginName: { ... }`.
+  * Shallow-merged at startup, then frozen.
+  *
+  * @example
+  * ```ts
+  * config: { basePath: "/", trailing: false }
+  * ```
+  */
+  config?: PluginConfig;
+  /**
+  * Plugins this plugin depends on. Dependency APIs are available via `ctx.require()`.
+  * Dependencies must appear earlier in the plugins array (no topological sort).
+  *
+  * @example
+  * ```ts
+  * depends: [authPlugin, httpPlugin]
+  * ```
+  */
+  depends?: DependencyPlugins;
+  /**
+  * Factory for mutable plugin state. Called once at startup with a minimal context
+  * (global config + plugin config). The returned object is the only mutable store.
+  *
+  * @example
+  * ```ts
+  * createState: (ctx) => ({ count: 0, cache: new Map() })
+  * ```
+  */
+  createState?: (context: MinimalContext<GlobalConfig, PluginConfig>) => PluginState;
+  /**
+  * Public API factory. Receives full plugin context; returns the API object
+  * other plugins access via `ctx.require(thisPlugin)`.
+  * Must be synchronous and side-effect-free — do not call `ctx.emit()` from this factory.
+  *
+  * @example
+  * ```ts
+  * api: (ctx) => ({
+  *   navigate: (path: string) => { ctx.state.currentPath = path; },
+  *   getCurrentPath: () => ctx.state.currentPath,
+  * })
+  * ```
+  */
+  api?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => PluginApi;
+  /**
+  * Called after all plugins are registered and APIs are built. Runs in forward
+  * plugin order, sequentially awaited. Use for setup that depends on other plugins.
+  *
+  * @example
+  * ```ts
+  * onInit: (ctx) => {
+  *   const http = ctx.require(httpPlugin);
+  *   http.use(authMiddleware);
+  * }
+  * ```
+  */
+  onInit?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void | Promise<void>;
+  /**
+  * Called when the app starts. Runs in forward plugin order, sequentially awaited.
+  * Use for runtime startup (open connections, start listeners).
+  *
+  * @example
+  * ```ts
+  * onStart: async (ctx) => {
+  *   await ctx.state.db.connect(ctx.config.connectionString);
+  * }
+  * ```
+  */
+  onStart?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void | Promise<void>;
+  /**
+  * Called when the app stops. Runs in **reverse** plugin order, sequentially awaited.
+  * Use for teardown (close connections, flush buffers). Receives only global config.
+  *
+  * @example
+  * ```ts
+  * onStop: async (ctx) => {
+  *   await db.disconnect();
+  * }
+  * ```
+  */
+  onStop?: (context: TeardownContext<GlobalConfig>) => void | Promise<void>;
+  /**
+  * Event subscription factory. Receives full plugin context; returns a map of
+  * event handlers. Same closure pattern as `api`. Handlers can access `ctx.state`,
+  * `ctx.emit`, `ctx.require`, etc.
+  *
+  * @example
+  * ```ts
+  * hooks: (ctx) => ({
+  *   "auth:login": ({ userId }) => {
+  *     ctx.state.lastLogin = userId;
+  *     ctx.emit("page:render", { path: "/dashboard", html: "<div>Welcome</div>" });
+  *   },
+  * })
+  * ```
+  */
+  hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => { [EventName in string & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>]?: (payload: MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>[EventName]) => void | Promise<void> };
+};
+/**
+* Bound createPlugin function type, parameterized by the framework's Config and Events.
+*
+* All type parameters are inferred from the spec object — no explicit generics needed.
+* Per-plugin events use the register callback pattern instead of explicit type arguments.
+*
+* @example
+* ```ts
+* const { createPlugin } = createCoreConfig<MyConfig, MyEvents>("my-app", { config: defaults });
+* const router = createPlugin("router", { config: { basePath: "/" } });
+* ```
+*/
+type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap> = {
+  <const PluginName extends string = string, PluginConfig extends Record<string, unknown> = Record<string, never>, PluginState = Record<string, never>, PluginApi extends Record<string, unknown> = Record<string, never>, DependencyPlugins extends DependencyPluginTuple = readonly [], PluginEventMap extends Record<string, unknown> = EmptyPluginEventMap, HookHandlerMap extends Record<string, any> = Record<never, never>>(name: PluginName, spec: Omit<CreatePluginSpec<GlobalConfig, GlobalEventMap, PluginEventMap, PluginConfig, PluginState, PluginApi, DependencyPlugins>, "hooks"> & {
+    hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => { [K in keyof HookHandlerMap]: K extends string & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins> ? (payload: MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>[K & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>]) => void | Promise<void> : never };
+  }): PluginInstance<PluginName, PluginConfig, PluginState, PluginApi, PluginEventMap>;
+};
+/**
+* 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: "/" } });
+* ```
+*/
+//#endregion
+//#region src/core.d.ts
+/**
+* Options for createCore (Step 2).
+*
+* @example
+* ```ts
+* createCore(coreConfig, { plugins: [routerPlugin], onReady: (ctx) => console.log(ctx.config) });
+* ```
+*/
+interface CreateCoreOptions<Config> {
+  /** Framework default plugins. */
+  readonly plugins: AnyPluginInstance[];
+  /** Framework-level plugin config overrides keyed by plugin name. */
+  readonly pluginConfigs?: Record<string, unknown>;
+  /** Called after all plugins are initialized. */
+  readonly onReady?: (context: {
+    config: Readonly<Config>;
+  }) => void | Promise<void>;
+  /** Error handler for hook dispatch and teardown failures. */
+  readonly onError?: (error: Error) => void;
+}
+/**
+* Return type of createCore (Step 2).
+* Carries the Plugins type parameter to thread type information through createApp.
+*
+* @example
+* ```ts
+* const { createApp, createPlugin } = createCore(coreConfig, { plugins: [...] });
+* ```
+*/
+interface CreateCoreResult<Config extends Record<string, unknown>, Events extends Record<string, unknown>, Plugins extends readonly AnyPluginInstance[] = readonly AnyPluginInstance[]> {
+  /**
+  * Step 3: Creates and initializes the application.
+  * Generic over ExtraPlugins to merge consumer plugins into the return type.
+  *
+  * @param options - Consumer-level config overrides, plugin configs, extra plugins.
+  * @returns A promise that resolves to the frozen, fully typed App object.
+  */
+  readonly createApp: <const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: CreateAppOptions<Config, Events, Plugins[number] | ExtraPlugins[number], [...ExtraPlugins]>) => Promise<App<Config, Events, Plugins[number] | ExtraPlugins[number]>>;
+  /** Re-exported createPlugin for consumer convenience. */
+  readonly createPlugin: BoundCreatePluginFunction<Config, Events>;
+}
+/**
+* Bound createCore function type. Generic method captures the Plugins tuple
+* from options.plugins to thread type information into CreateCoreResult.
+*
+* @example
+* ```ts
+* const framework = createCore(coreConfig, { plugins: [routerPlugin] });
+* ```
+*/
+type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events extends Record<string, unknown>> = <const Plugins extends readonly AnyPluginInstance[]>(coreConfig: {
+  readonly createPlugin: BoundCreatePluginFunction<Config, Events>;
+}, options: CreateCoreOptions<Config> & {
+  readonly plugins: [...Plugins];
+}) => CreateCoreResult<Config, Events, Plugins>;
+/**
+* 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
+* );
+* ```
+*/
+//#endregion
+//#region src/config.d.ts
+/**
+* Return type of createCoreConfig. Named type required for isolatedDeclarations.
+*
+* @example
+* ```ts
+* const result: CoreConfigResult<SiteConfig, SiteEvents> = createCoreConfig("app", { config: defaults });
+* ```
+*/
+interface CoreConfigResult<Config extends Record<string, unknown>, Events extends Record<string, unknown>> {
+  /** Creates a plugin instance with all types inferred from the spec object. */
+  readonly createPlugin: BoundCreatePluginFunction<Config, Events>;
+  /** Step 2 factory: captures default plugins and returns createApp + createPlugin. */
+  readonly createCore: BoundCreateCoreFunction<Config, Events>;
+}
+/**
+* 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;
+* ```
+*/
+declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = Record<string, never>>(id: string, options: {
+  config: Config;
+}): CoreConfigResult<Config, Events>;
+//#endregion
+export { type EmitFunction as EmitFn, type PluginContext_ as PluginCtx, createCoreConfig };