@moku-labs/core 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/index.d.mts

@@ -1,89 +1,3 @@
-//#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.
@@ -147,14 +61,14 @@ type MinimalContext<Config, C> = {
 * })
 * ```
 */
-type PluginContext<Config, Events extends Record<string, unknown>, C, S> = {
+type PluginContext<Config, Events extends Record<string, unknown>, C, S, CoreApis extends Record<string, unknown> = {}> = {
   readonly global: Readonly<Config>;
   readonly config: Readonly<C>;
   state: S;
   emit: EmitFunction$1<Events>;
   require: RequireFunction;
   has: HasFunction;
-};
+} & { readonly [K in keyof CoreApis]: CoreApis[K] };
 /**
 * Strictly typed emit function (kernel-layer generic signature).
 * Only known event names are accepted, with matching payload required.
@@ -216,15 +130,15 @@ type HasFunction = (name: string) => boolean;
 *   { 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>>> = {
+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>>, CoreApis extends Record<string, unknown> = {}> = {
   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;
-  onStart?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void | Promise<void>;
+  api?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S, CoreApis>) => A;
+  onInit?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S, CoreApis>) => void;
+  onStart?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S, CoreApis>) => 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> };
+  hooks?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S, CoreApis>) => { [K in string & keyof (Events & PluginEvents & DepsEvents<Deps>)]?: (payload: (Events & PluginEvents & DepsEvents<Deps>)[K]) => void | Promise<void> };
 };
 /**
 * Plugin instance — the return value of createPlugin.
@@ -343,13 +257,13 @@ type BuildPluginApis<P extends PluginInstance<string, any, any, any, any>> = { [
 * app.router.navigate("/about");
 * ```
 */
-type App<_Config extends Record<string, unknown>, Events extends Record<string, unknown>, P extends PluginInstance<string, any, any, any, any>> = {
+type App<_Config extends Record<string, unknown>, Events extends Record<string, unknown>, P extends PluginInstance<string, any, any, any, any>, CoreApis extends Record<string, unknown> = {}> = {
   readonly start: () => Promise<void>;
   readonly stop: () => Promise<void>;
   readonly emit: EmitFunction$1<Events>;
   readonly require: RequireFunction;
   readonly has: HasFunction;
-} & BuildPluginApis<P>;
+} & BuildPluginApis<P> & { readonly [K in keyof CoreApis]: CoreApis[K] };
 /**
 * Context passed to consumer lifecycle callbacks (onReady, onStart, onStop).
 * Includes frozen config, event emission, plugin lookup, and mounted plugin APIs.
@@ -363,12 +277,12 @@ type App<_Config extends Record<string, unknown>, Events extends Record<string,
 * 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>> = {
+type AppCallbackContext<Config extends Record<string, unknown>, Events extends Record<string, unknown>, P extends PluginInstance<string, any, any, any, any>, CoreApis extends Record<string, unknown> = {}> = {
   readonly config: Readonly<Config>;
   readonly emit: EmitFunction$1<Events>;
   readonly require: RequireFunction;
   readonly has: HasFunction;
-} & BuildPluginApis<P>;
+} & BuildPluginApis<P> & { readonly [K in keyof CoreApis]: CoreApis[K] };
 /**
 * Options for createApp (Step 3). Structured namespaces replace flat key discrimination:
 * - `plugins`: extra consumer plugins
@@ -385,14 +299,14 @@ type AppCallbackContext<Config extends Record<string, unknown>, Events extends R
 * });
 * ```
 */
-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>[]> = {
+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>[], CoreApis extends Record<string, unknown> = {}> = {
   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;
-  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>;
+  onReady?: (context: AppCallbackContext<Config, Events, P, CoreApis>) => void;
+  onError?: (error: Error, context: AppCallbackContext<Config, Events, P, CoreApis>) => void;
+  onStart?: (context: AppCallbackContext<Config, Events, P, CoreApis>) => void | Promise<void>;
+  onStop?: (context: AppCallbackContext<Config, Events, P, CoreApis>) => void | Promise<void>;
 };
 /**
 * Domain context type for extracted plugin files (api.ts, handlers.ts, etc.).
@@ -430,6 +344,234 @@ type PluginContext_<C, S, E extends Record<string, unknown> = Record<never, neve
   emit: EmitFunction<E>;
 };
 //#endregion
+//#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/core-plugin.d.ts
+/**
+* Minimal context for core plugins. Only config and state — no global, emit,
+* require, or has. Core plugins are self-contained infrastructure.
+*
+* @example
+* ```ts
+* type LogCtx = CorePluginContext<{ level: string }, { entries: string[] }>;
+* // => { readonly config: Readonly<{ level: string }>; state: { entries: string[] } }
+* ```
+*/
+type CorePluginContext<C, S> = {
+  readonly config: Readonly<C>;
+  state: S;
+};
+/**
+* Core plugin specification — the shape passed to createCorePlugin.
+*
+* Same lifecycle methods as regular plugins (config, createState, api, onInit,
+* onStart, onStop) but NO depends, events, or hooks.
+*
+* @example
+* ```ts
+* const spec: CorePluginSpec<{ level: string }, { entries: string[] }, { info(msg: string): void }> = {
+*   config: { level: "info" },
+*   createState: () => ({ entries: [] }),
+*   api: ctx => ({ info: (msg) => { ctx.state.entries.push(msg); } }),
+* };
+* ```
+*/
+type CorePluginSpec<C extends Record<string, unknown>, S, A extends Record<string, any>> = {
+  /** Default config values for this core plugin. Consumers can override via pluginConfigs. */config?: C; /** Factory for mutable state. Called once with { config } only. */
+  createState?: (context: {
+    readonly config: Readonly<C>;
+  }) => S; /** API factory. The returned object is injected directly onto every regular plugin's context. */
+  api?: (context: CorePluginContext<C, S>) => A; /** Called after core plugin APIs are built. Synchronous. */
+  onInit?: (context: CorePluginContext<C, S>) => void; /** Called when app starts. Core plugins start before regular plugins. */
+  onStart?: (context: CorePluginContext<C, S>) => void | Promise<void>; /** Called when app stops. Core plugins stop after regular plugins. */
+  onStop?: (context: CorePluginContext<C, S>) => void | Promise<void>;
+};
+/**
+* Core plugin instance — the return value of createCorePlugin.
+*
+* Carries phantom types for compile-time inference and a `_corePlugin: true`
+* brand to distinguish from regular PluginInstance.
+*
+* @example
+* ```ts
+* const log = createCorePlugin("log", { api: ctx => ({ info: () => {} }) });
+* // log: CorePluginInstance<"log", Record<string, never>, Record<string, never>, { info(): void }>
+* ```
+*/
+interface CorePluginInstance<N extends string = string, C = void, S = void, A extends Record<string, any> = Record<string, never>> {
+  readonly name: N;
+  readonly spec: CorePluginSpec<any, any, any>;
+  readonly _corePlugin: true;
+  readonly _phantom: {
+    config: C;
+    state: S;
+    api: A;
+  };
+}
+/**
+* Widened CorePluginInstance type for generic constraints on arrays.
+*
+* @example
+* ```ts
+* function processCorePlugins(plugins: AnyCorePluginInstance[]): void { ... }
+* ```
+*/
+type AnyCorePluginInstance = CorePluginInstance<string, any, any, any>;
+/**
+* Extract the name literal type from a CorePluginInstance.
+*
+* @example
+* ```ts
+* type Name = ExtractCoreName<typeof logPlugin>; // "log"
+* ```
+*/
+type ExtractCoreName<P> = P extends CorePluginInstance<infer N, any, any, any> ? N : never;
+/**
+* Extract the API phantom type from a CorePluginInstance.
+*
+* @example
+* ```ts
+* type LogApi = ExtractCoreApi<typeof logPlugin>; // { info(msg: string): void }
+* ```
+*/
+type ExtractCoreApi<P> = P extends CorePluginInstance<string, any, any, infer A> ? A : never;
+/**
+* Extract the config phantom type from a CorePluginInstance.
+*
+* @example
+* ```ts
+* type LogConfig = ExtractCoreConfig<typeof logPlugin>; // { level: string }
+* ```
+*/
+type ExtractCoreConfig<P> = P extends CorePluginInstance<string, infer C, any, any> ? C : never;
+/**
+* Map a core plugin union to `{ readonly [Name]: Api }` for context injection.
+* Core plugins with empty API (Record<string, never>) are excluded.
+* Core plugins with non-literal name type (string) are excluded.
+*
+* @example
+* ```ts
+* type Apis = BuildCorePluginApis<typeof logPlugin | typeof envPlugin>;
+* // => { readonly log: { info(msg: string): void }; readonly env: { isDev(): boolean } }
+* ```
+*/
+type BuildCorePluginApis<P extends CorePluginInstance<string, any, any, any>> = { readonly [K in P as ExtractCoreApi<K> extends Record<string, never> ? never : IsLiteralString<ExtractCoreName<K>> extends true ? ExtractCoreName<K> : never]: ExtractCoreApi<K> };
+/**
+* Compute core API map from a core plugin tuple.
+* Convenience alias: extracts the union from the tuple, then builds the map.
+*
+* @example
+* ```ts
+* type Apis = CoreApisFromTuple<readonly [typeof logPlugin, typeof envPlugin]>;
+* // => { readonly log: LogApi; readonly env: EnvApi }
+* ```
+*/
+type CoreApisFromTuple<T extends readonly AnyCorePluginInstance[]> = BuildCorePluginApis<T[number]>;
+/**
+* Creates a core plugin instance. Core plugins are standalone, self-contained
+* infrastructure plugins (log, storage, env) whose APIs are injected directly
+* onto every regular plugin's context.
+*
+* @param name - Unique core plugin name (inferred as literal string type).
+* @param spec - Core plugin specification: config, createState, api, lifecycle.
+* @returns A CorePluginInstance carrying phantom types for compile-time inference.
+* @example
+* ```ts
+* const logPlugin = createCorePlugin("log", {
+*   config: { level: "info" },
+*   createState: () => ({ entries: [] as string[] }),
+*   api: ctx => ({
+*     info: (msg: string) => { ctx.state.entries.push(msg); console.log(msg); },
+*   }),
+* });
+* ```
+*/
+declare function createCorePlugin<const N extends string, C extends Record<string, unknown> = Record<string, never>, S = Record<string, never>, A extends Record<string, any> = Record<string, never>>(name: N, spec: CorePluginSpec<C, S, A>): CorePluginInstance<N, C, S, A>;
+//#endregion
 //#region src/plugin.d.ts
 /**
 * Structural plugin shape used for generic constraints without variance issues.
@@ -521,7 +663,7 @@ type MergedPluginEvents<GlobalEventMap extends FrameworkEventMap, PluginEventMap
 * >;
 * ```
 */
-type PluginExecutionContext<GlobalConfig extends FrameworkConfig, AllEvents extends Record<string, unknown>, PluginConfig, PluginState> = {
+type PluginExecutionContext<GlobalConfig extends FrameworkConfig, AllEvents extends Record<string, unknown>, PluginConfig, PluginState, CoreApis extends Record<string, unknown> = {}> = {
   /**
   * Frozen app-wide config from `createCoreConfig`. Shared by all plugins.
   *
@@ -580,7 +722,7 @@ type PluginExecutionContext<GlobalConfig extends FrameworkConfig, AllEvents exte
   * ```
   */
   has: (name: string) => boolean;
-};
+} & { readonly [K in keyof CoreApis]: CoreApis[K] };
 /**
 * Descriptor returned by register(). Carries the payload type.
 * and an optional description string for runtime event catalogs.
@@ -639,7 +781,7 @@ type RegisterFunction = {
 * >;
 * ```
 */
-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> = {
+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, CoreApis extends Record<string, unknown> = {}, Helpers extends Record<string, (...arguments_: any[]) => any> = Record<never, never>> = {
   /**
   * Declare plugin-specific events via a register callback.
   * Used for compile-time type inference only — the kernel does not call this at runtime.
@@ -696,7 +838,7 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * })
   * ```
   */
-  api?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => PluginApi;
+  api?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => PluginApi;
   /**
   * Called after all plugins are registered and APIs are built. Runs in forward
   * plugin order, synchronously. Use for setup that depends on other plugins.
@@ -710,7 +852,7 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * }
   * ```
   */
-  onInit?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void;
+  onInit?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => void;
   /**
   * Called when the app starts. Runs in forward plugin order, sequentially awaited.
   * Use for runtime startup (open connections, start listeners).
@@ -722,7 +864,7 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * }
   * ```
   */
-  onStart?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void | Promise<void>;
+  onStart?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => 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.
@@ -750,7 +892,21 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * })
   * ```
   */
-  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> };
+  hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => { [EventName in string & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>]?: (payload: MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>[EventName]) => void | Promise<void> };
+  /**
+  * Static helper functions exposed directly on the plugin instance.
+  * Helpers run before createApp — they receive no context.
+  * Use for typed factories and builders that produce config values.
+  *
+  * @example
+  * ```ts
+  * helpers: {
+  *   route: (path: string, component: string) => ({ path, component }),
+  *   redirect: (from: string, to: string) => ({ from, to, type: 'redirect' as const }),
+  * }
+  * ```
+  */
+  helpers?: Helpers;
 };
 /**
 * Bound createPlugin function type, parameterized by the framework's Config and Events.
@@ -764,10 +920,11 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
 * 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>;
+type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, CoreApis extends Record<string, unknown> = {}> = {
+  <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>, Helpers extends Record<string, (...arguments_: any[]) => any> = Record<never, never>>(name: PluginName, spec: Omit<CreatePluginSpec<GlobalConfig, GlobalEventMap, PluginEventMap, PluginConfig, PluginState, PluginApi, DependencyPlugins, CoreApis>, "hooks" | "helpers"> & {
+    hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => { [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 };
+    helpers?: Helpers;
+  }): PluginInstance<PluginName, PluginConfig, PluginState, PluginApi, PluginEventMap> & Helpers;
 };
 /**
 * Creates a bound `createPlugin` function that captures framework generics.
@@ -815,7 +972,7 @@ interface CreateCoreOptions<Config> {
 * const { createApp, createPlugin } = createCore(coreConfig, { plugins: [...] });
 * ```
 */
-interface CreateCoreResult<Config extends Record<string, unknown>, Events extends Record<string, unknown>, Plugins extends readonly AnyPluginInstance[] = readonly AnyPluginInstance[]> {
+interface CreateCoreResult<Config extends Record<string, unknown>, Events extends Record<string, unknown>, Plugins extends readonly AnyPluginInstance[] = readonly AnyPluginInstance[], CorePlugins extends readonly AnyCorePluginInstance[] = readonly []> {
   /**
   * Step 3: Creates and initializes the application.
   * Generic over ExtraPlugins to merge consumer plugins into the return type.
@@ -823,9 +980,9 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
   * @param options - Consumer-level config overrides, plugin configs, extra plugins.
   * @returns The frozen, fully typed App object.
   */
-  readonly createApp: <const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: CreateAppOptions<Config, Events, Plugins[number] | ExtraPlugins[number], [...ExtraPlugins]>) => App<Config, Events, Plugins[number] | ExtraPlugins[number]>;
+  readonly createApp: <const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: CreateAppOptions<Config, Events, Plugins[number] | ExtraPlugins[number], [...ExtraPlugins], CoreApisFromTuple<CorePlugins>>) => App<Config, Events, Plugins[number] | ExtraPlugins[number], CoreApisFromTuple<CorePlugins>>;
   /** Re-exported createPlugin for consumer convenience. */
-  readonly createPlugin: BoundCreatePluginFunction<Config, Events>;
+  readonly createPlugin: BoundCreatePluginFunction<Config, Events, CoreApisFromTuple<CorePlugins>>;
 }
 /**
 * Bound createCore function type. Generic method captures the Plugins tuple
@@ -836,11 +993,11 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
 * 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>;
+type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events extends Record<string, unknown>, CorePlugins extends readonly AnyCorePluginInstance[] = readonly []> = <const Plugins extends readonly AnyPluginInstance[]>(coreConfig: {
+  readonly createPlugin: BoundCreatePluginFunction<Config, Events, CoreApisFromTuple<CorePlugins>>;
 }, options: CreateCoreOptions<Config> & {
   readonly plugins: [...Plugins];
-}) => CreateCoreResult<Config, Events, Plugins>;
+}) => CreateCoreResult<Config, Events, Plugins, CorePlugins>;
 /**
 * Creates a bound `createCore` function that captures framework context.
 *
@@ -851,6 +1008,8 @@ type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events exte
 * @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.
+* @param corePlugins - Core plugin instances from createCoreConfig.
+* @param corePluginConfigs - Core plugin config overrides from createCoreConfig.
 * @returns A createCore function bound to the framework's Config and Events types.
 * @example
 * ```ts
@@ -869,11 +1028,11 @@ type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events exte
 * const result: CoreConfigResult<SiteConfig, SiteEvents> = createCoreConfig("app", { config: defaults });
 * ```
 */
-interface CoreConfigResult<Config extends Record<string, unknown>, Events extends Record<string, unknown>> {
+interface CoreConfigResult<Config extends Record<string, unknown>, Events extends Record<string, unknown>, CorePlugins extends readonly AnyCorePluginInstance[] = readonly []> {
   /** Creates a plugin instance with all types inferred from the spec object. */
-  readonly createPlugin: BoundCreatePluginFunction<Config, Events>;
+  readonly createPlugin: BoundCreatePluginFunction<Config, Events, CoreApisFromTuple<CorePlugins>>;
   /** Step 2 factory: captures default plugins and returns createApp + createPlugin. */
-  readonly createCore: BoundCreateCoreFunction<Config, Events>;
+  readonly createCore: BoundCreateCoreFunction<Config, Events, CorePlugins>;
 }
 /**
 * Step 1 of the 3-step factory chain. Captures Config and Events generics
@@ -885,6 +1044,8 @@ interface CoreConfigResult<Config extends Record<string, unknown>, Events extend
 * @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.
+* @param options.plugins - Optional core plugin instances to register.
+* @param options.pluginConfigs - Optional config overrides for core plugins.
 * @returns An object with createPlugin (bound to Config/Events) and createCore.
 * @example
 * ```ts
@@ -894,8 +1055,10 @@ interface CoreConfigResult<Config extends Record<string, unknown>, Events extend
 * const { createPlugin, createCore } = coreConfig;
 * ```
 */
-declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = Record<string, never>>(id: string, options: {
+declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = Record<string, never>, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
   config: Config;
-}): CoreConfigResult<Config, Events>;
+  plugins?: [...CorePlugins];
+  pluginConfigs?: { [K in CorePlugins[number] as ExtractCoreConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractCoreName<K>> extends true ? ExtractCoreName<K> : never]?: Partial<ExtractCoreConfig<K>> };
+}): CoreConfigResult<Config, Events, CorePlugins>;
 //#endregion
-export { type AnyPluginInstance, type App, type BoundCreateCoreFunction, type BoundCreatePluginFunction, type CoreConfigResult, type CreateAppOptions, type CreateCoreOptions, type CreateCoreResult, type EmitFunction as EmitFn, type PluginContext_ as PluginCtx, type PluginInstance, createCoreConfig };
+export { type AnyCorePluginInstance, type AnyPluginInstance, type App, type BoundCreateCoreFunction, type BoundCreatePluginFunction, type CoreApisFromTuple, type CoreConfigResult, type CorePluginInstance, type CreateAppOptions, type CreateCoreOptions, type CreateCoreResult, type EmitFunction as EmitFn, type PluginContext_ as PluginCtx, type PluginInstance, createCoreConfig, createCorePlugin };