@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/shared/href-validation.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared href/URL validation for all navigation sinks.
+ *
+ * Used by <Link>, useRouter().push/replace, and redirectExternal().
+ * Single source of truth for dangerous-scheme detection — prevents
+ * control-character smuggling that bypasses naive regex checks.
+ *
+ * See design/13-security.md §"Link scheme injection" (test #9)
+ * and design/07-routing.md §"<Link> Scheme Validation".
+ */
+
+/**
+ * All C0 control characters (U+0000–U+001F) that browsers strip during
+ * URL preprocessing. Browsers and `new URL()` strip the full C0 range,
+ * not just tab/LF/CR — so we must match that behavior to prevent
+ * bypass vectors like `\x00javascript:alert(1)`.
+ */
+// eslint-disable-next-line no-control-regex -- intentional: must match all C0 controls to prevent bypass
+const CONTROL_CHARS_RE = /[\x00-\x1f]/g;
+
+const DANGEROUS_SCHEMES = new Set(['javascript:', 'data:', 'vbscript:']);
+
+/**
+ * Strip C0 control chars and leading whitespace, then extract the scheme.
+ * Returns the lowercase scheme (e.g. "javascript:") or null if no scheme.
+ */
+function extractScheme(href: string): string | null {
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart();
+  const match = /^([a-z][a-z0-9+.-]*:)/i.exec(cleaned);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Validate an href for navigation sinks (<Link>, useRouter, etc.).
+ *
+ * Rejects dangerous schemes (javascript:, data:, vbscript:) even when
+ * control characters are embedded to bypass naive regex checks.
+ * Also rejects protocol-relative URLs (//evil.com).
+ *
+ * Throws on rejection. Safe hrefs pass through silently.
+ */
+export function validateNavigationHref(href: string): void {
+  // Normalize for validation: strip C0 controls, trim, then replace backslashes
+  // with forward slashes. Browsers normalize \ → / during URL resolution, so
+  // "/\evil.com" becomes "//evil.com" (protocol-relative open redirect).
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  // Protocol-relative URLs can redirect to attacker-controlled origins
+  if (cleaned.startsWith('//')) {
+    throw new Error(
+      `Navigation received a protocol-relative or backslash-prefixed URL: "${href}". ` +
+        'Use an absolute URL with an explicit scheme or a relative path.'
+    );
+  }
+
+  const scheme = extractScheme(href);
+  if (scheme && DANGEROUS_SCHEMES.has(scheme)) {
+    throw new Error(
+      `Navigation received a dangerous href: "${href}". ` +
+        'javascript:, data:, and vbscript: URLs are not allowed.'
+    );
+  }
+}
+
+/**
+ * Check if an href is internal (same-origin navigation) or external.
+ *
+ * Strips control characters before checking so that "java\tscript:" is
+ * correctly identified as having a scheme (and thus not internal).
+ */
+export function isInternalHref(href: string): boolean {
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (cleaned.startsWith('//')) return false;
+  if (cleaned.startsWith('/') || cleaned.startsWith('#') || cleaned.startsWith('?')) return true;
+
+  const scheme = extractScheme(href);
+  if (scheme) return false;
+
+  return true;
+}
+
+/** Pattern matching absolute URLs: any scheme (http:, javascript:, …) or protocol-relative // */
+const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
+
+/**
+ * Assert that a redirect target is a relative path — rejects absolute and
+ * protocol-relative URLs. Used by both the server `redirect()` primitive and
+ * the client next/navigation shim so they enforce identical semantics.
+ *
+ * Normalizes for validation only: strips C0 controls, trims, then replaces
+ * backslashes with forward slashes. Browsers normalize \ → / during URL
+ * resolution, so "/\evil.com" becomes "//evil.com" (protocol-relative open
+ * redirect). See design/13-security.md tests #8, #8a–#8c.
+ */
+export function assertRelativeRedirectPath(path: string): void {
+  const cleaned = path.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (ABSOLUTE_URL_RE.test(cleaned)) {
+    throw new Error(
+      `redirect() only accepts relative URLs. Got absolute URL: "${path}". ` +
+        'Use redirectExternal(url, allowList) for external redirects.'
+    );
+  }
+
+  // eslint-disable-next-line no-control-regex -- intentional: must match C0 controls
+  if (/[\x00-\x1f]/.test(path)) {
+    throw new Error(
+      `redirect() received a path containing control characters (U+0000–U+001F). ` +
+        'Sanitize user input before passing it to redirect().'
+    );
+  }
+}
+
+const SAFE_REDIRECT_SCHEMES = new Set(['http:', 'https:']);
+
+/**
+ * Validate and canonicalize an external redirect URL.
+ *
+ * Requires http: or https: scheme and checks origin against an allow-list.
+ * Returns the parsed canonical URL string (from URL.href) to prevent
+ * raw user input from reaching the Location header.
+ *
+ * @throws On invalid URL, dangerous scheme, or origin not in allow-list.
+ */
+export function validateExternalRedirectUrl(url: string, allowList: string[]): string {
+  // Strip control chars before parsing to prevent scheme smuggling
+  const cleaned = url.replace(CONTROL_CHARS_RE, '').trimStart();
+
+  if (cleaned.startsWith('//')) {
+    throw new Error(
+      `redirectExternal() received a protocol-relative URL: "${url}". ` +
+        'Use an absolute URL with http: or https: scheme.'
+    );
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(cleaned);
+  } catch {
+    throw new Error(`redirectExternal() received an invalid URL: "${url}"`);
+  }
+
+  if (!SAFE_REDIRECT_SCHEMES.has(parsed.protocol)) {
+    throw new Error(
+      `redirectExternal() received a non-http(s) URL: "${url}". ` +
+        'Only http: and https: schemes are allowed for external redirects.'
+    );
+  }
+
+  if (!allowList.includes(parsed.origin)) {
+    throw new Error(
+      `redirectExternal() target "${parsed.origin}" is not in the allow-list. ` +
+        `Allowed: [${allowList.join(', ')}]`
+    );
+  }
+
+  return parsed.href;
+}

package/src/shared/merge-search-params.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared utility for merging preserved search params into a target URL.
+ *
+ * Used by both <Link> (client) and redirect() (server). Extracted to a shared
+ * module to avoid importing client code ('use client') from server modules.
+ */
+
+/**
+ * Merge preserved search params from the current URL into a target href.
+ *
+ * When `preserve` is `true`, all current search params are merged.
+ * When `preserve` is a `string[]`, only the named params are merged.
+ *
+ * The target href's own search params take precedence — preserved params
+ * are only added if the target doesn't already define them.
+ *
+ * @param targetHref - The resolved target href (may already contain query string)
+ * @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+ * @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+ * @returns The target href with preserved search params merged in
+ */
+export function mergePreservedSearchParams(
+  targetHref: string,
+  currentSearch: string,
+  preserve: true | string[]
+): string {
+  const currentParams = new URLSearchParams(currentSearch);
+  if (currentParams.size === 0) return targetHref;
+
+  // Split hash fragment from target before processing query params.
+  // Hash must come after query string: /path?query=value#hash
+  const hashIdx = targetHref.indexOf('#');
+  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';
+
+  // Split target into path and existing query
+  const qIdx = hrefWithoutHash.indexOf('?');
+  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');
+
+  // Collect params to preserve (that aren't already in the target)
+  const merged = new URLSearchParams(targetParams);
+  for (const [key, value] of currentParams) {
+    // Only preserve if: (a) not already in target, and (b) included in preserve list
+    if (!targetParams.has(key)) {
+      if (preserve === true || preserve.includes(key)) {
+        merged.append(key, value);
+      }
+    }
+  }
+
+  const qs = merged.toString();
+  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;
+  return pathWithQuery + hash;
+}

package/src/shared/redirect-type.ts

@@ -0,0 +1,17 @@
+/**
+ * Next.js redirect type discriminator.
+ *
+ * Provided for API compatibility with libraries that import `RedirectType`
+ * from `next/navigation`. In timber, `redirect()` always uses `replace`
+ * semantics (no history entry for the redirect itself).
+ *
+ * Lives in shared/ (isomorphic) so both the server primitives and the
+ * client-only next/navigation shim export the same definition without the
+ * client shim pulling in server code.
+ */
+export const RedirectType = {
+  push: 'push',
+  replace: 'replace',
+} as const;
+
+export type RedirectTypeValue = (typeof RedirectType)[keyof typeof RedirectType];

package/src/shims/font-google.ts

@@ -17,7 +17,7 @@
  * Design doc: 24-fonts.md, "Next.js Font Compatibility"
  */
 
-import type { GoogleFontConfig, FontResult } from '#/fonts/types.js';
+import type { GoogleFontConfig, FontResult } from '../fonts/types.js';
 
 export type { GoogleFontConfig, FontResult };
 

package/src/shims/font-local.ts

@@ -0,0 +1,34 @@
+/**
+ * Fallback shim for `next/font/local` → `@timber/fonts/local`.
+ *
+ * At build time, the timber-fonts plugin's transform hook replaces
+ * `localFont()` calls with static FontResult objects containing real
+ * class names and font stacks. This file serves two purposes:
+ *
+ * 1. **TypeScript resolution** — provides types for IDEs and `tsc` outside
+ *    of Vite's module graph (where the virtual module handles it).
+ * 2. **Runtime fallback** — returns empty className/fontFamily values when
+ *    the plugin hasn't processed a call (e.g. in tests or non-Vite environments).
+ *
+ * Design doc: 24-fonts.md, "Next.js Font Compatibility"
+ */
+
+import type { LocalFontConfig, FontResult } from '../fonts/types.js';
+
+export type { LocalFontConfig, FontResult };
+
+/**
+ * Create a local font.
+ *
+ * The timber-fonts plugin replaces these calls at build time with real
+ * class names and font stacks. This stub ensures code that imports
+ * `localFont` outside of the build pipeline (tests, type-checking)
+ * gets a valid FontResult shape without runtime errors.
+ */
+export default function localFont(config?: LocalFontConfig): FontResult {
+  return {
+    className: '',
+    style: { fontFamily: '' },
+    variable: config?.variable,
+  };
+}

package/src/shims/headers.ts

@@ -4,6 +4,127 @@
  * Imports from @timber-js/app/server which Vite resolves to dist/server/index.js
  * via native package.json exports. This ensures the same ALS singleton as the
  * pipeline (both import from the same shared request-context chunk in dist/).
+ *
+ * `cookies()` is NOT a bare alias of `getCookieJar()`: Next.js's
+ * RequestCookies returns `{ name, value }` RequestCookie objects from
+ * `.get()`/`.getAll()`, while timber's native jar returns bare strings from
+ * `.get()`. Ecosystem libraries written against the real API use
+ * `(await cookies()).get('session')?.value` — with the bare-string shape
+ * that silently reads `undefined` off a string. The adapter below presents
+ * the Next shape while delegating every operation to the timber jar, so the
+ * encoding contract, cookie-octet validation, and mutable-context checks
+ * (design/29-cookies.md, ONGOING_SECURITY.md H-3) apply unchanged.
+ * See TIM-1042 and design/14-ecosystem.md §next/headers.
+ */
+
+import { getCookieJar } from '@timber-js/app/server';
+import type { CookieOptions, SetCookieOptions } from '@timber-js/app/server';
+
+// Re-export timber's primary API
+export { getHeaders, getCookieJar } from '@timber-js/app/server';
+
+// Next.js compat alias — libraries importing from 'next/headers' expect this name.
+export { getHeaders as headers } from '@timber-js/app/server';
+
+/** Next.js's request cookie shape: `cookies().get(name)` → `{ name, value }`. */
+export interface RequestCookie {
+  name: string;
+  value: string;
+}
+
+/** Next.js's `cookies().set()` options — `expires` may be a ms timestamp. */
+export interface NextCookieOptions extends Omit<SetCookieOptions, 'expires'> {
+  expires?: Date | number;
+}
+
+/** Next.js's object overload for `cookies().set({ name, value, ...options })`. */
+export interface NextCookieListItem extends NextCookieOptions {
+  name: string;
+  value: string;
+}
+
+/** Next.js's RequestCookies surface, backed by timber's cookie jar. */
+export interface NextRequestCookies {
+  get(name: string): RequestCookie | undefined;
+  get(cookie: RequestCookie): RequestCookie | undefined;
+  getAll(name?: string): RequestCookie[];
+  getAll(cookie: RequestCookie): RequestCookie[];
+  has(name: string): boolean;
+  readonly size: number;
+  set(name: string, value: string, options?: NextCookieOptions): void;
+  set(cookie: NextCookieListItem): void;
+  delete(name: string): void;
+  delete(cookie: { name: string } & Pick<CookieOptions, 'path' | 'domain'>): void;
+  [Symbol.iterator](): IterableIterator<[string, RequestCookie]>;
+  toString(): string;
+}
+
+/** Normalize Next's `expires?: Date | number` (ms timestamp) to timber's `Date`. */
+function normalizeOptions(options?: NextCookieOptions): SetCookieOptions | undefined {
+  if (!options) return undefined;
+  const { expires, ...rest } = options;
+  if (typeof expires === 'number') return { ...rest, expires: new Date(expires) };
+  return options as SetCookieOptions;
+}
+
+/**
+ * Next.js compat: `cookies()` returning the RequestCookies shape.
+ *
+ * Next.js 15 makes `cookies()` async; awaiting this sync return value works
+ * for both the `(await cookies()).get()` and legacy `cookies().get()` call
+ * styles, so libraries targeting either Next version resolve correctly.
  */
+export function cookies(): NextRequestCookies {
+  const jar = getCookieJar();
+
+  const toCookie = (name: string): RequestCookie | undefined => {
+    const value = jar.get(name);
+    return value === undefined ? undefined : { name, value };
+  };
 
-export { headers, cookies } from '@timber-js/app/server';
+  return {
+    get(nameOrCookie: string | RequestCookie): RequestCookie | undefined {
+      return toCookie(typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name);
+    },
+    getAll(nameOrCookie?: string | RequestCookie): RequestCookie[] {
+      const all = jar.getAll();
+      if (nameOrCookie === undefined) return all;
+      const name = typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name;
+      return all.filter((cookie) => cookie.name === name);
+    },
+    has(name: string): boolean {
+      return jar.has(name);
+    },
+    get size(): number {
+      return jar.size;
+    },
+    set(
+      nameOrCookie: string | NextCookieListItem,
+      value?: string,
+      options?: NextCookieOptions
+    ): void {
+      if (typeof nameOrCookie === 'string') {
+        jar.set(nameOrCookie, value as string, normalizeOptions(options));
+      } else {
+        const { name, value: cookieValue, ...objectOptions } = nameOrCookie;
+        jar.set(name, cookieValue, normalizeOptions(objectOptions));
+      }
+    },
+    delete(nameOrCookie: string | ({ name: string } & Pick<CookieOptions, 'path' | 'domain'>)) {
+      if (typeof nameOrCookie === 'string') {
+        jar.delete(nameOrCookie);
+      } else {
+        const { name, ...options } = nameOrCookie;
+        jar.delete(name, options);
+      }
+    },
+    *[Symbol.iterator](): IterableIterator<[string, RequestCookie]> {
+      for (const cookie of jar.getAll()) {
+        yield [cookie.name, cookie];
+      }
+    },
+    toString(): string {
+      return jar.toString();
+    },
+  };
+}

package/src/shims/navigation-client.ts

@@ -1,12 +1,19 @@
 /**
  * Shim: next/navigation (client environment only)
  *
- * Re-exports only the client-side hooks from timber's client API.
- * Server-only functions (redirect, notFound, etc.) are excluded to prevent
- * server/primitives.ts from being pulled into the browser bundle.
+ * Re-exports the client-side hooks from timber's client API, and implements
+ * client-render `redirect()` / `permanentRedirect()` / `notFound()` without
+ * pulling server/primitives.ts into the browser bundle.
+ *
+ * Next.js supports calling redirect()/notFound() during client component
+ * render. timber matches that by throwing a plain Error carrying the same
+ * JSON digest the server pipeline attaches to RedirectSignal/DenySignal.
+ * TimberErrorBoundary recognizes the digest and converts it to an SPA
+ * navigation (redirect) or a status-code fallback (notFound), and
+ * browser-dev's isFrameworkSignalError() keeps it out of the dev overlay.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
- * where both client hooks and server functions are needed.
+ * where the real server primitives produce proper HTTP responses.
  *
  * Imports use @timber-js/app/client (not #/ subpath imports) so they resolve
  * to the same module instances as user code in Vite dev — preventing module
@@ -16,42 +23,57 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks — imported from the public barrel for module singleton consistency.
+import { assertRelativeRedirectPath } from '../shared/href-validation.js';
+import type { RedirectTypeValue } from '../shared/redirect-type.js';
+
+// Hooks — useSegmentParams and useSearchParams import from direct modules
+// since they're no longer in @timber-js/app/client public exports.
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
-// RedirectType enum is safe (no server code dependency) and used by some
-// client-side libraries for type checking.
-export const RedirectType = {
-  push: 'push',
-  replace: 'replace',
-} as const;
+// Single source of truth shared with server/primitives.ts.
+export { RedirectType } from '../shared/redirect-type.js';
 
-// Server-only stubs — throw at runtime if called from the client.
-// These exist for type compatibility with libraries that import the types
-// but should never execute in the browser.
-export function redirect(): never {
-  throw new Error(
-    'redirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
+/** Throw a plain Error carrying a framework signal digest. */
+function throwSignal(message: string, digest: Record<string, unknown>): never {
+  const err = new Error(message);
+  (err as Error & { digest?: string }).digest = JSON.stringify(digest);
+  throw err;
 }
 
-export function permanentRedirect(): never {
-  throw new Error(
-    'permanentRedirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
+/**
+ * Client-render redirect. Throws a redirect-digest error that the nearest
+ * TimberErrorBoundary converts into an SPA navigation (replace semantics).
+ *
+ * The optional RedirectType argument is accepted for Next.js API
+ * compatibility but ignored — timber always uses replace semantics,
+ * matching the server-side redirect().
+ */
+export function redirect(path: string, _type?: RedirectTypeValue): never {
+  assertRelativeRedirectPath(path);
+  throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 302 });
 }
 
+/**
+ * Client-render permanent redirect. On the client there is no HTTP status —
+ * this behaves identically to redirect() apart from the digest's status.
+ */
+export function permanentRedirect(path: string, _type?: RedirectTypeValue): never {
+  assertRelativeRedirectPath(path);
+  throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 308 });
+}
+
+/**
+ * Client-render notFound. Throws a deny-digest error (status 404) that the
+ * nearest matching TimberErrorBoundary renders as the 404 fallback. The
+ * message matches DenySignal's so digest-less fallback parsing still works.
+ */
 export function notFound(): never {
-  throw new Error(
-    'notFound() is a server-only function and cannot be called from client components.'
-  );
+  throwSignal('Access denied with status 404', { type: 'deny', status: 404, data: null });
 }

package/src/shims/navigation.ts

@@ -1,20 +1,27 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks import from @timber-js/app/client (the public barrel) so they
- * resolve to the same module instances as user code in Vite dev. Server
- * functions import from @timber-js/app/server for ALS singleton consistency.
+ * Client hooks import from their direct modules since useSegmentParams,
+ * useSearchParams, and useQueryStates are no longer part of
+ * @timber-js/app/client public exports (they live on define* factories).
+ * The shim re-exports them for next/navigation library compat (nuqs etc).
+ *
+ * Server functions import from @timber-js/app/server for ALS singleton consistency.
  */
 
-// Hooks (client-side — imported from public barrel for module singleton)
+// Hooks re-exported for next/navigation compat
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
 // Functions (server-side)
-export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';
+
+// Next.js compat aliases — these are not part of timber's primary API.
+// They exist so that libraries importing from 'next/navigation' still work.
+export { permanentRedirect, notFound } from '../server/primitives.js';

package/src/utils/state-machine.ts

@@ -0,0 +1,111 @@
+/**
+ * Tiny typed state machine utility.
+ *
+ * Enforces discriminated-union states, typed transitions with runtime
+ * guards, subscribe for external store integration, and assertPhase
+ * for function entry guards.
+ *
+ * Designed for 3–5 state consumers (stream transforms, client navigation,
+ * build phase sequencing). No async, no hierarchy, no history.
+ *
+ * Performance: send() is one object lookup + one function call.
+ * Equivalent cost to a boolean check after V8 inlining.
+ */
+
+/** A state machine instance with typed state and events. */
+export interface Machine<TState extends { phase: string }, TEvent extends { type: string }> {
+  /** Current state (discriminated union — narrowed by phase). */
+  readonly state: TState;
+
+  /** Transition with runtime guard. Throws on invalid source+event pair. */
+  send(event: TEvent): void;
+
+  /** Subscribe to state changes. Returns unsubscribe function. */
+  subscribe(listener: (state: TState) => void): () => void;
+
+  /** Throw if not in the expected phase. Entry guard for functions. */
+  assertPhase<P extends TState['phase']>(phase: P): void;
+}
+
+/**
+ * Transition map: `transitions[phase][eventType]` returns the next state.
+ *
+ * Each handler receives the current state (narrowed by phase context)
+ * and the event, returning the new state.
+ */
+export type TransitionMap<TState extends { phase: string }, TEvent extends { type: string }> = {
+  [P in TState['phase']]?: {
+    [E in TEvent['type']]?: (
+      state: Extract<TState, { phase: P }>,
+      event: Extract<TEvent, { type: E }>
+    ) => TState;
+  };
+};
+
+export interface MachineConfig<TState extends { phase: string }, TEvent extends { type: string }> {
+  initial: TState;
+  transitions: TransitionMap<TState, TEvent>;
+  /** Fires after every valid transition. Use for side effects. */
+  onTransition?: (prev: TState, next: TState, event: TEvent) => void;
+}
+
+/**
+ * Create a state machine from a config.
+ *
+ * @example
+ * ```ts
+ * type State = { phase: 'idle' } | { phase: 'running'; pid: number };
+ * type Event = { type: 'START'; pid: number } | { type: 'STOP' };
+ *
+ * const m = createMachine<State, Event>({
+ *   initial: { phase: 'idle' },
+ *   transitions: {
+ *     idle: { START: (_s, e) => ({ phase: 'running', pid: e.pid }) },
+ *     running: { STOP: () => ({ phase: 'idle' }) },
+ *   },
+ * });
+ * ```
+ */
+export function createMachine<TState extends { phase: string }, TEvent extends { type: string }>(
+  config: MachineConfig<TState, TEvent>
+): Machine<TState, TEvent> {
+  let current: TState = config.initial;
+  const listeners = new Set<(state: TState) => void>();
+
+  return {
+    get state() {
+      return current;
+    },
+
+    send(event: TEvent): void {
+      const phaseHandlers = config.transitions[current.phase as TState['phase']];
+      const handler = phaseHandlers?.[event.type as TEvent['type']] as
+        | ((state: TState, event: TEvent) => TState)
+        | undefined;
+
+      if (!handler) {
+        throw new Error(`[state-machine] Invalid transition: ${current.phase} + ${event.type}`);
+      }
+
+      const prev = current;
+      current = handler(prev, event);
+
+      config.onTransition?.(prev, current, event);
+
+      for (const listener of listeners) {
+        listener(current);
+      }
+    },
+
+    subscribe(listener: (state: TState) => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    assertPhase<P extends TState['phase']>(phase: P): void {
+      if (current.phase !== phase) {
+        throw new Error(`[state-machine] Expected phase "${phase}", got "${current.phase}"`);
+      }
+    },
+  };
+}