v0.1.0-alpha.5

What's New

Plugin Helpers — static factory/builder functions that live on the plugin instance and are available before createApp. Consumers get typed, autocomplete-friendly APIs for building config values.

import { createPlugin, createApp } from "my-framework";

type Route = { path: string; component: string };

// Framework author defines helpers on the plugin spec:
export const routerPlugin = createPlugin("router", {
  config: { routes: [] as Route[] },
  api: ctx => ({
    navigate: (path: string) => { /* ... */ },
  }),
  helpers: {
    route: (path: string, component: string): Route => ({ path, component }),
  },
});

// Consumer uses helpers BEFORE createApp — fully typed:
const home = routerPlugin.route("/home", "HomePage");
const about = routerPlugin.route("/about", "AboutPage");

const app = createApp({
  pluginConfigs: { router: { routes: [home, about] } },
});

// Destructuring also works — types preserved:
const { route } = routerPlugin;
const contact = route("/contact", "ContactPage");

Features

• helpers field on plugin spec — plain object of functions, each value must be a function. Optional field, defaults to empty.
• Intersection return type — createPlugin returns PluginInstance<...> & Helpers. No 6th generic added to PluginInstance — the intersection widens away naturally in constraint positions (AnyPluginInstance, depends, plugins arrays).
• Zero breaking changes — existing plugins without helpers work identically. & Record<never, never> is the identity intersection.
• Runtime validation — helpers must be a plain object of functions. Helper names must not collide with PluginInstance fields (name, spec, _phantom). Clear error messages on violation.
• Full type inference — helper parameter types and return types are inferred from the spec. Destructured helpers preserve their signatures.
• Static pure functions — helpers have no access to ctx, no lifecycle, no side effects. They run before the kernel exists.

Tests

• 722 tests passing (169 unit, 41 integration, 512 sandbox)
• New unit tests for helpers validation (valid helpers, null/non-object rejection, non-function values, name collisions, empty helpers)
• New type-level tests for helpers inference, intersection behavior, destructuring, and constraint assignability

Spec Updates

Updated specifications: 03 (Plugin System), 12 (Plugin Patterns), 13 (Kernel Pseudocode), 15 (Plugin Structure), README index, and CLAUDE.md.