@luckystack/devkit 0.1.0

package/docs/supervisor.md

@@ -0,0 +1,292 @@
+# Supervisor (`supervisor.ts`)
+
+> Dev-only. The supervisor is the parent process that watches files which cannot be hot-reloaded in-process (config, bootstrap, sockets setup, auth wiring) and restarts the LuckyStack server child whenever one of them changes. In production it skips the watcher entirely and just keeps the child crash-restarted.
+
+The supervisor is a single Node script (`packages/devkit/src/supervisor.ts`) compiled into the devkit `dist/` and invoked by consumer projects via their own `npm run dev` script (typically `tsx node_modules/@luckystack/devkit/dist/supervisor.js` or equivalent).
+
+It owns one child process at a time. The child runs `tsx` against `server/server.ts` and inherits stdio so its logs surface in the parent's terminal as-is.
+
+---
+
+## Process model
+
+```typescript
+const tsxCliPath = path.resolve(process.cwd(), 'node_modules', 'tsx', 'dist', 'cli.mjs');
+const childArgs = [tsxCliPath, 'server/server.ts'];
+
+const startChild = () => {
+  if (isShuttingDown) return;
+  childBootStartedAt = performance.now();
+  childProcess = spawn(process.execPath, childArgs, {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      LUCKYSTACK_CORE_SUPERVISED: 'true',
+    },
+  });
+  // ... attach 'exit' handler ...
+};
+```
+
+Key points:
+
+- `process.execPath` is the running Node binary, so the child uses the same Node version as the supervisor.
+- `tsx` is invoked as a Node script (`node node_modules/tsx/dist/cli.mjs`) rather than via a shell — fewer cross-platform surprises (no PATH dependency, no `.cmd` shim on Windows).
+- `stdio: 'inherit'` means child logs go directly to the parent's TTY. Backpressure is handled by Node, the supervisor doesn't touch the streams.
+- `LUCKYSTACK_CORE_SUPERVISED=true` is set in the child env so framework code can detect that it is running under the supervisor (useful for adjusting log prefixes or skipping its own crash-restart logic).
+
+The supervisor stores the active child handle on a module-level variable:
+
+```typescript
+let childProcess: ChildProcess | null = null;
+let pendingRestart = false;
+let restartTimer: NodeJS.Timeout | null = null;
+let crashRestartTimer: NodeJS.Timeout | null = null;
+let childBootStartedAt = 0;
+let isShuttingDown = false;
+```
+
+This is intentionally global to the file — the supervisor is a single-purpose entry script, not a library.
+
+---
+
+## `CORE_WATCH_GLOBS`
+
+```typescript
+const CORE_WATCH_GLOBS = [
+  'config.ts',
+  '.env',
+  '.env.local',
+  'server/server.ts',
+  'server/bootstrap/**/*.ts',
+  'server/auth/**/*.ts',
+  'server/functions/db.ts',
+  'server/functions/redis.ts',
+  'server/functions/sentry.ts',
+];
+```
+
+These are files that cannot be hot-reloaded inside the same Node process — they own framework-wide singletons (Prisma client, Redis client, Sentry SDK, Socket.io server, OAuth providers). Changing any of them requires a fresh boot.
+
+Everything not in this list — API/sync files, page components, shared helpers, locale `.json`, `_components/*` — is hot-reloaded by `setupWatchers()` running inside the child (see `hot-reload.md`).
+
+Adding new globs here should be deliberate. The rule of thumb: if mutation can be reflected by reassigning a module-level binding inside `@luckystack/core` (the `registerXxx` extension points), it can hot-reload; if it needs to re-run a top-level `new SomeClient(...)`, it needs a supervisor restart.
+
+---
+
+## Restart debouncing
+
+```typescript
+const RESTART_DEBOUNCE_MS = 150;
+const CRASH_RESTART_DELAY_MS = 300;
+
+const scheduleRestart = ({ event, changedPath }: { event: string; changedPath: string }) => {
+  if (restartTimer) clearTimeout(restartTimer);
+
+  restartTimer = setTimeout(() => {
+    restartTimer = null;
+    pendingRestart = true;
+
+    console.log(`[Supervisor] Core change detected (${event}): ${changedPath}. Restarting server`, 'yellow');
+
+    if (!childProcess) {
+      pendingRestart = false;
+      startChild();
+      return;
+    }
+
+    childProcess.kill('SIGTERM');
+  }, RESTART_DEBOUNCE_MS);
+};
+```
+
+Two constants:
+
+- **`RESTART_DEBOUNCE_MS = 150`** — coalesces bursts of save events (e.g. a project-wide rename) into a single restart.
+- **`CRASH_RESTART_DELAY_MS = 300`** — delay before re-spawning after a non-zero exit, so a syntax error doesn't restart-loop at full speed.
+
+The flow on a save:
+
+1. Watcher fires `all` -> `scheduleRestart`.
+2. Existing timer cleared; new timer queued at 150 ms.
+3. Timer expires: `pendingRestart = true`, then either start a fresh child (no current) or `kill('SIGTERM')` the running one.
+4. The child's `exit` handler sees `pendingRestart === true` and respawns.
+
+`pendingRestart` is the bridge between the kill and the respawn. It's needed because the child exit handler runs asynchronously; the supervisor must remember that this particular exit was intentional.
+
+---
+
+## State machine
+
+```
+                    +----------------+
+                    |   no child     |
+                    +-------+--------+
+                            | startChild()
+                            v
+                    +----------------+
+   file change ---> |    running     |
+                    +-------+--------+
+                            |
+            +---------------+----------------+
+            |               |                |
+            v               v                v
+        SIGTERM          exit 0         exit code != 0
+        (intentional)   (graceful,      (crash)
+            |            user Ctrl+C    
+            v                |              |
+       respawn after     stop (or          schedule respawn
+       150ms debounce    process.exit      after 300ms
+       coalesce          if isShuttingDown)
+```
+
+Key transitions in the `exit` handler:
+
+```typescript
+childProcess.on('exit', (code, signal) => {
+  const uptimeMs = Math.round(performance.now() - childBootStartedAt);
+  const shouldRestart = pendingRestart;
+  childProcess = null;
+
+  if (isShuttingDown) {
+    process.exit(0);
+  }
+
+  if (shouldRestart) {
+    pendingRestart = false;
+    console.log(`[Supervisor] Restarting server after ${String(uptimeMs)}ms uptime`, 'yellow');
+    startChild();
+    return;
+  }
+
+  if (signal === 'SIGTERM' || signal === 'SIGINT') {
+    return;
+  }
+
+  if (typeof code === 'number' && code !== 0) {
+    console.log(`[Supervisor] Server crashed with code ${String(code)}. Restarting in ${String(CRASH_RESTART_DELAY_MS)}ms`, 'red');
+    crashRestartTimer = setTimeout(() => {
+      crashRestartTimer = null;
+      startChild();
+    }, CRASH_RESTART_DELAY_MS);
+  }
+});
+```
+
+Cases handled:
+
+| Exit signal/code | Behavior |
+|---|---|
+| `isShuttingDown` | `process.exit(0)` — Ctrl+C raced with a crash, do not respawn |
+| `pendingRestart === true` | Respawn immediately, log uptime |
+| Signal `SIGTERM` / `SIGINT` (not from us) | Treat as ordered shutdown, do not respawn |
+| `code === 0` | Clean exit, do not respawn |
+| `code !== 0` | Schedule a `setTimeout(startChild, 300)` respawn |
+
+The `isShuttingDown` guard at the top is critical: without it, a crash that raced with Ctrl+C would re-spawn indefinitely because `pendingRestart` is independent of the shutdown flag.
+
+---
+
+## Shutdown handling
+
+```typescript
+const shutdownSupervisor = () => {
+  isShuttingDown = true;
+
+  if (restartTimer) {
+    clearTimeout(restartTimer);
+    restartTimer = null;
+  }
+  if (crashRestartTimer) {
+    clearTimeout(crashRestartTimer);
+    crashRestartTimer = null;
+  }
+
+  pendingRestart = false;
+
+  if (childProcess) {
+    childProcess.kill('SIGTERM');
+    setTimeout(() => process.exit(0), 1500).unref();
+  } else {
+    process.exit(0);
+  }
+};
+
+const handleSignal = (signalName: string) => {
+  if (isShuttingDown) {
+    process.exit(1);  // second Ctrl+C — hard exit
+  }
+  isShuttingDown = true;
+  console.log(`[Supervisor] Received ${signalName}, shutting down`, 'yellow');
+  void watcher.close().then(() => {
+    shutdownSupervisor();
+  }).catch(() => {
+    shutdownSupervisor();
+  });
+};
+
+process.on('SIGINT', () => handleSignal('SIGINT'));
+process.on('SIGTERM', () => handleSignal('SIGTERM'));
+```
+
+Notes:
+
+- **`isShuttingDown` is set synchronously** at the top of `handleSignal` so any in-flight child `exit` handler running BEFORE `watcher.close()` resolves can't schedule a new spawn.
+- **Second Ctrl+C exits with code 1** immediately, bypassing the graceful watcher close. The user is impatient; this is the right move.
+- **`setTimeout(process.exit, 1500).unref()`** is the force-exit grace period. On Windows, child processes sometimes ignore `SIGTERM`; the unrefed timer guarantees the supervisor exits even if the child sits.
+- **Watcher close is awaited** so chokidar releases file handles before exit (matters on Windows where unreleased handles block subsequent processes).
+
+---
+
+## Production mode
+
+```typescript
+if (env.NODE_ENV === 'production') {
+  startChild();
+} else {
+  const watcher = watch(CORE_WATCH_GLOBS, {
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 120,
+      pollInterval: 20,
+    },
+  });
+
+  watcher.on('all', (event, changedPath) => {
+    scheduleRestart({ event, changedPath });
+  });
+
+  process.on('SIGINT', () => handleSignal('SIGINT'));
+  process.on('SIGTERM', () => handleSignal('SIGTERM'));
+
+  startChild();
+}
+```
+
+In production:
+
+- No file watcher.
+- Only `startChild()` is called.
+- The crash-restart timer still fires on non-zero exit (the `exit` handler always runs), so the supervisor doubles as a minimal process keeper for prod boots — useful when running directly without a system supervisor (PM2, systemd, etc.).
+- Signal handlers are NOT registered in the prod branch above; the child receives signals directly (or via the system supervisor), and crash-restart is the only behavior.
+
+`env.NODE_ENV` is read through `@luckystack/core`'s env helper, not directly from `process.env`, so any project-level env preprocessing (e.g. loading `.env.local` overrides) applies before the branch.
+
+---
+
+## Edge cases
+
+- **Child exits between two debounce ticks.** The first tick set `pendingRestart = true` and killed the child. The child's exit handler respawns. The second tick fires, but `childProcess` is already a fresh process — it kills the new child too. This is correct: both saves are part of the same coalesced restart from the user's perspective.
+- **Watcher event arrives during shutdown.** `handleSignal` sets `isShuttingDown = true` synchronously; `scheduleRestart` does not check this flag, but its eventual `startChild()` call DOES (`if (isShuttingDown) return;`). The kill+respawn sequence is short-circuited.
+- **SIGTERM ignored by Windows child.** `shutdownSupervisor` schedules a 1500 ms force-exit via `setTimeout(process.exit, 1500).unref()`. The unref means the timer doesn't keep the event loop alive if the child does exit cleanly.
+- **Rapid Ctrl+C double-tap.** First Ctrl+C: `handleSignal` flags shutdown, calls `watcher.close()`. Second Ctrl+C: `handleSignal` sees `isShuttingDown === true` and calls `process.exit(1)` immediately — no waiting for watchers or children.
+- **Respawn loop after a config syntax error.** Child crashes with non-zero exit -> 300 ms crash-restart timer -> child crashes again. The supervisor will loop until the user fixes the config or kills it. There is no exponential backoff currently.
+
+---
+
+## Operational guidance
+
+- The supervisor is NOT the place to add type-map regeneration — that lives in `setupWatchers` inside the child (`hot-reload.md`). The supervisor only handles restarts.
+- Add new globs to `CORE_WATCH_GLOBS` only when a file change cannot be picked up by hot reload. Most additions are unnecessary — hot reload handles `_api/`, `_sync/`, components, helpers, locales, and the import dependency graph for shared modules.
+- The supervisor doesn't manage ports. The child binds whatever port the framework / config specifies. If the previous child exits cleanly on SIGTERM, the port is released before the new child starts; if it doesn't, the new child's `EADDRINUSE` is a config bug, not a supervisor bug.
+- Logs from the supervisor are prefixed `[Supervisor]` and colored cyan/yellow/red. They appear alongside child logs because of `stdio: 'inherit'`.

package/docs/template-customization.md

@@ -0,0 +1,136 @@
+# Template customization
+
+`@luckystack/devkit` injects starter content into newly-created **empty** files
+under `src/` (a new `_api/*.ts`, `_sync/*.ts`, or `page.tsx`). Two things are
+customizable, both from the consumer's `.luckystack/templates/` folder:
+
+1. **Which** template a file gets — the *selection rules*.
+2. **What** that template contains — the *content*.
+
+Everything here is **dev-only**: devkit reads it from the hot-reload path during
+`npm run server`. Nothing ships to end users.
+
+---
+
+## How a file gets a template
+
+`injectTemplate(filePath)` (called by the file watcher on empty-file creation):
+
+1. **Classify** the file structurally into a `fileKind`:
+   `'api' | 'sync_server' | 'sync_client' | 'page'` (derived from the route
+   conventions — override the markers via `registerRoutingRules`). For pages,
+   placement is validated first; an un-routable placement gets a commented
+   diagnostic instead of a real template.
+2. **Select a kind** via `resolveTemplateKind(ctx)` — the registered rules are
+   evaluated by descending `priority` (ties: newest registration first), and the
+   first matching rule's `kind` wins.
+3. **Resolve content** for that kind, first hit wins:
+   - `.luckystack/templates/<kind>.template.ts(x)` — consumer file
+   - a `registerTemplate('<kind>', '...')` string override
+   - the bundled default shipped inside devkit (`dist/templates/`)
+4. **Substitute placeholders** (`{{REL_PATH}}`, `{{PAGE_PATH}}`, `{{SYNC_NAME}}`)
+   and write the file.
+
+The match context is:
+
+```ts
+interface TemplateMatchContext {
+  filePath: string;                                    // absolute path of the new file
+  fileKind: 'api' | 'sync_server' | 'sync_client' | 'page';
+  hasPairedServer: boolean;                            // sync_client: does *_server_v<N>.ts exist?
+  srcRelativePath: string | null;                      // path relative to src/, or null
+}
+```
+
+---
+
+## The consumer overlay: `.luckystack/templates/`
+
+`create-luckystack-app` scaffolds this folder. devkit auto-loads
+`.luckystack/templates/templateRules.ts` **once, in dev, before the first
+injection** (a plain dynamic import — no wiring needed). Absent file ⇒ devkit's
+built-in defaults apply.
+
+```
+.luckystack/templates/
+  templateRules.ts                 # the selection logic — edit/remove/add rules
+  api.template.ts                  # editable copies of the built-in template bodies
+  sync_server.template.ts
+  sync_client_paired.template.ts
+  sync_client_standalone.template.ts
+  page_plain.template.tsx
+  page_dashboard.template.tsx
+  README.md
+```
+
+A `*.template.*` file in this folder overrides that kind's content. **Delete** a
+file to fall back to devkit's (upgradeable) bundled default. The shipped copies
+are a snapshot of the defaults at scaffold time — to refresh, copy from
+`node_modules/@luckystack/devkit/dist/templates/`.
+
+---
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `registerTemplateRule({ kind, match, priority? })` | Add a selection rule. `priority` default for direct calls is the caller's; defaults use 10 (specific) / 0 (page catch-all). |
+| `registerTemplateKind(kind, { match, content?, priority? })` | Register a brand-new kind (rule + optional inline content) in one call. Default priority 100 so custom kinds beat the built-ins. |
+| `registerTemplate(kind, content)` | Override just the content body of a kind (string). |
+| `resolveTemplateKind(ctx)` | Evaluate the active rules → the chosen kind (or null). |
+| `getTemplateRules()` | The active rules in evaluation order. |
+| `clearTemplateRules()` | Drop ALL rules — including the built-in defaults. The scaffolded `templateRules.ts` calls this first so it is the single source of truth. |
+| `registerDefaultTemplateRules()` | (Re)arm the framework defaults. Armed automatically on module load; idempotent. |
+| `BUILT_IN_TEMPLATE_KINDS` / `BUILT_IN_TEMPLATE_FILENAMES` / `DEFAULT_DASHBOARD_PATH_PATTERN` | The 6 kinds, their bundled filenames, and the page-dashboard heuristic regex. |
+
+Built-in kinds: `api`, `sync_server`, `sync_client_paired`,
+`sync_client_standalone`, `page_plain`, `page_dashboard`.
+
+---
+
+## Recipes
+
+### Change when a page gets the dashboard layout
+
+Edit the `page_dashboard` rule in `.luckystack/templates/templateRules.ts`:
+
+```ts
+registerTemplateRule({
+  kind: 'page_dashboard',
+  priority: 10,
+  match: (ctx) => ctx.fileKind === 'page' && ctx.filePath.replaceAll('\\', '/').includes('/app/'),
+});
+```
+
+### Remove a rule entirely
+
+The scaffolded `templateRules.ts` starts with `clearTemplateRules()` and then
+re-declares each default. Delete the rule you don't want — that mapping no
+longer applies (a page with no matching rule simply isn't injected).
+
+### Add a brand-new template kind
+
+```ts
+// .luckystack/templates/templateRules.ts
+import { registerTemplateKind } from '@luckystack/devkit';
+
+registerTemplateKind('page_marketing', {
+  priority: 20, // beats page_dashboard / page_plain
+  match: (ctx) => ctx.fileKind === 'page' && ctx.filePath.replaceAll('\\', '/').includes('/marketing/'),
+});
+```
+
+Then create `.luckystack/templates/page_marketing.template.tsx` with the body.
+Custom kinds resolve content from `<kind>.template.tsx` then `<kind>.template.ts`
+in the overlay folder (or a `registerTemplate('page_marketing', '...')` string).
+
+---
+
+## Packaging note (framework maintainers)
+
+The bundled templates live at `packages/devkit/src/templates/`. They are read at
+runtime via `fs.readFileSync(dist/templates/...)`, so `tsup.config.ts` copies
+`src/templates → dist/templates` in its `onSuccess` hook and `files: ["dist"]`
+ships them in the tarball. The scaffolded consumer copies live separately under
+`create-luckystack-app/template/_dot_luckystack/templates/` (the `_dot_` prefix
+is rewritten to `.` by the scaffold so npm doesn't drop the dot-folder).

package/docs/ts-program-cache.md

@@ -0,0 +1,199 @@
+# TypeScript Program Cache (`typeMap/tsProgram.ts`)
+
+> Dev-only. Internal to `@luckystack/devkit`. The cached `ts.Program` is used by the type-map emitter, the public extractors (`getInputTypeFromFile`, `getSyncClientDataType`), and the runtime type resolver. Production servers never load this module — the type-map emitter runs at build time / dev-time, and the generated `apiTypes.generated.ts` is what production reads.
+
+The cache exists for one reason: building a `ts.Program` from `tsconfig.server.json` is the single most expensive step in type-map generation. A medium-sized LuckyStack project (50+ APIs, 20+ syncs, full Prisma schema) pays multi-second program-build cost. Hot reload must be sub-second, and a full type-map regeneration must reuse the same program across every extractor call within one pass.
+
+---
+
+## Module surface
+
+```typescript
+let cachedProgram: ts.Program | null = null;
+
+export const getServerProgram = (): ts.Program;
+export const invalidateProgramCache = (): void;
+
+export interface UnresolvedTypeSymbol {
+  name: string;
+  sourceFile?: string;
+  importPath?: string;
+}
+
+export interface ExpandedTypeResult {
+  text: string;
+  unresolvedSymbols: UnresolvedTypeSymbol[];
+}
+
+export const expandTypeDetailed = (
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  depth?: number,
+  state?: ExpandState,
+): ExpandedTypeResult;
+
+export const expandType = (
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  depth?: number,
+): string;
+```
+
+`cachedProgram` is module-level state. It starts as `null` and is only assigned by `getServerProgram()`. Resetting it to `null` (via `invalidateProgramCache()`) is the only invalidation path; the module never replaces a live program in place.
+
+---
+
+## `getServerProgram()` flow
+
+```typescript
+export const getServerProgram = (): ts.Program => {
+  if (cachedProgram) return cachedProgram;
+
+  const tsconfigPath = ts.findConfigFile(ROOT_DIR, ts.sys.fileExists, 'tsconfig.server.json');
+  if (!tsconfigPath) throw new Error('[TypeProgram] tsconfig.server.json not found');
+
+  const { config } = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+  const { options, fileNames } = ts.parseJsonConfigFileContent(
+    config,
+    ts.sys,
+    path.dirname(tsconfigPath),
+  );
+
+  cachedProgram = ts.createProgram(fileNames, options);
+  return cachedProgram;
+};
+```
+
+Steps:
+
+1. Return the cached program if present. This is the hot path.
+2. Locate `tsconfig.server.json` relative to `ROOT_DIR` (resolved from `@luckystack/core`). The constant is the project's working directory at process start — registered once in `@luckystack/core/src/projectRoot.ts`.
+3. Throw a typed error if no tsconfig is found. There is no fallback; the type emitter has no way to resolve cross-file symbols without a tsconfig.
+4. Parse the JSON tsconfig (`ts.readConfigFile` + `ts.parseJsonConfigFileContent`) to expand `extends`, `include`, `exclude`, `paths`, etc. into the concrete `options` + `fileNames` arrays the compiler accepts.
+5. Build the program with `ts.createProgram(fileNames, options)`. This is the multi-second cost.
+6. Memoize and return.
+
+Re-entrancy: this function is synchronous and single-threaded. Two concurrent extractor calls within the same generation pass will each hit step 1 after the first call returns.
+
+---
+
+## `invalidateProgramCache()` rules
+
+```typescript
+export const invalidateProgramCache = (): void => {
+  cachedProgram = null;
+};
+```
+
+Setting `cachedProgram = null` forces the next `getServerProgram()` call to rebuild from disk.
+
+Invalidation points in the codebase:
+
+- `loader.ts` `upsertApiFromFile(filePath)` — calls `invalidateProgramCache()` before re-importing the changed file. The next type extraction must see the new file contents.
+- `loader.ts` `removeApiFromFile(filePath)` — same; references to the deleted file must be re-resolved.
+- `loader.ts` `upsertSyncFromFile(filePath)` and `removeSyncFromFile(filePath)` — same.
+- `typeMapGenerator.ts` `generateTypeMapFile(...)` — calls `invalidateProgramCache()` at the start of every full regeneration so a build script picks up files that changed since the previous in-process run.
+
+Deliberate non-invalidation points:
+
+- `loader.ts` `initializeApis()` and `initializeSyncs()` — **do not** invalidate on the boot path. `cachedProgram` is `null` at module load, so the first `getServerProgram()` call builds it from scratch anyway. With `initializeApis` and `initializeSyncs` running in parallel via `Promise.all`, invalidating in both forced a redundant double-build (measured ~3-4 s wasted on a 54-API project). The annotated reason lives in `loader.ts` directly above the call.
+
+Invalidation must always be paired with `clearRuntimeTypeResolverCache()` — the runtime resolver caches expanded text keyed by the `(filePath, typeText)` pair, and stale entries can outlive a program rebuild.
+
+---
+
+## `expandTypeDetailed(...)` — recursive expander
+
+`expandTypeDetailed(type, checker, depth, state)` walks a `ts.Type` and produces a fully self-contained inline type string. The result has no named references, no import paths, and can be dropped into `apiTypes.generated.ts` verbatim.
+
+Key behaviors:
+
+- **Cycle protection.** Uses `state.stackTypeIds: Set<number>` keyed by TypeScript's internal type IDs. When the walker re-enters a type already on the stack, it short-circuits with `checker.typeToString(type)` plus `collectTypeSymbolFallback(type)` (so the unresolved-symbol bookkeeping still fires).
+- **Depth cap.** `DEPTH_LIMIT = 12`. Above this, the walker stops expanding and returns `checker.typeToString(type)`. Twelve levels is enough for every realistic Prisma model + nested DTO combination encountered in practice; beyond that the cost is exponential and the emitted text becomes unreadable.
+- **JSON passthrough.** `JSON_TYPE_NAMES` — `Json`, `JsonValue`, `JsonObject`, `JsonArray`, `InputJsonValue`, `InputJsonObject`, `InputJsonArray` — short-circuit to the literal text `JsonValue`. Prisma's recursive `Json` types blow the depth limit if expanded structurally, and the structural expansion is meaningless anyway (the runtime is "any JSON-shaped value").
+- **Opaque containers.** `SKIP_EXPANSION` — `Promise`, `Map`, `WeakMap`, `Set`, `WeakSet`, `Error`, `Date`, `RegExp`, `Buffer`, `ArrayBuffer`, `ReadonlyArray` — are returned as `checker.typeToString(type)` without recursion into internals. Their structural shape is irrelevant to API/sync wire types.
+- **Arrays.** `Array<T>` and `ReadonlyArray<T>` are rendered as `T[]`. Union/intersection element types are parenthesized: `(A | B)[]` not `A | B[]`.
+- **Tuples.** `[A, B, C]` literal form, recursing into each element.
+- **Unions and intersections.** Each constituent is expanded; results are joined with ` | ` or ` & `. Unresolved-symbol lists are merged via `mergeUnresolvedSymbols`.
+- **Object types.** `checker.getPropertiesOfType(type)` + `checker.getIndexInfosOfType(type)`. For each property:
+  - If the property's declaration is a `PropertyAssignment` / `ShorthandPropertyAssignment` whose initializer is a literal, the literal text is preserved (`'hello'`, `42`, `true`, `null`). This is what lets the emitter render `httpMethod: 'POST'` as a literal type rather than the generic `string`.
+  - Otherwise the property type is recursively expanded.
+  - Optional flag (`prop.flags & ts.SymbolFlags.Optional`) is rendered as `?:`.
+- **Index signatures.** Both the key type and the value type are recursively expanded; rendered as `[key: KeyType]: ValueType`.
+- **Primitives.** `string`, `number`, `boolean`, `true`, `false`, `null`, `undefined`, `any`, `unknown`, `never`, `void` are returned via `checker.typeToString(type)` unchanged.
+- **String / number literals.** Single-quoted (with escape handling) for strings, numeric text for numbers. Negative number literals are reconstructed from prefix-unary expressions.
+- **Indentation.** The walker tracks `depth` and uses `'  '.repeat(depth + 1)` for property indent and `'  '.repeat(depth)` for the closing brace. This keeps the generated `apiTypes.generated.ts` readable.
+
+`expandType(type, checker, depth)` is the convenience wrapper that returns only the `text` field — used when the caller doesn't care about unresolved symbols (the runtime resolver path).
+
+---
+
+## `UnresolvedTypeSymbol` and import collection
+
+```typescript
+export interface UnresolvedTypeSymbol {
+  name: string;
+  sourceFile?: string;
+  importPath?: string;
+}
+```
+
+When the walker reaches the depth limit, hits a cycle, or encounters a type whose properties cannot be expanded (typically an opaque type from a `node_modules` package), it falls back to `checker.typeToString(type)` and records the type's symbol via `collectTypeSymbolFallback`.
+
+`collectTypeSymbolFallback` resolves the source file via `symbol.declarations?.[0]?.getSourceFile().fileName`. If the source file is outside `node_modules`, it computes a relative import path via `normalizeImportPath(sourceFile)` — relative to `src/_sockets/` (the directory where `apiTypes.generated.ts` lives). Otherwise the symbol is recorded with only its `name`, so the emitter can decide whether to surface it as an unresolved alias or skip it.
+
+The type-map generator collects every unresolved symbol from every extractor call. If any unresolved symbol has no `importPath` (i.e., it cannot be reached by an import statement from the generated file), `generateTypeMapFile` throws an aggregated error listing every offending name. This is a strict gate — there is no `--allow-unresolved` flag.
+
+---
+
+## `expandState` — single recursion context
+
+```typescript
+interface ExpandState {
+  stackTypeIds: Set<number>;
+}
+```
+
+Callers do not need to pass `state` explicitly; the walker creates one on the first call. The state is local to one top-level expansion — it does not leak across calls. The `try { ... } finally { stackTypeIds.delete(typeId); }` block in the walker guarantees the stack is unwound even on exception.
+
+---
+
+## Consumer surface
+
+Only the following modules import `tsProgram.ts`:
+
+- `typeMap/extractors.ts` — calls `getServerProgram()` once per extractor invocation.
+- `typeMapGenerator.ts` — calls `invalidateProgramCache()` at the start of every regeneration.
+- `runtimeTypeResolver.ts` — calls `getServerProgram()` and `expandType` on the lazy expansion path.
+- `loader.ts` — calls `invalidateProgramCache()` from hot-reload upsert/remove handlers.
+
+Code outside `@luckystack/devkit` MUST NOT call `getServerProgram()` directly. Use the public extractors `getInputTypeFromFile(filePath)` and `getSyncClientDataType(filePath)` from `@luckystack/devkit`. They wrap program access, expansion, and error handling, and they are the only stable cross-package surface.
+
+---
+
+## Interaction with the runtime type resolver
+
+`runtimeTypeResolver.ts` and `tsProgram.ts` share the cached program. When the resolver expands an identifier via `resolveIdentifier(identifier, filePath)`, it calls `getServerProgram()` to get the same `ts.Program` the type-map emitter uses. This avoids paying the program-build cost twice during dev startup.
+
+The two modules also share an invalidation contract: any code path that calls `invalidateProgramCache()` MUST also call `clearRuntimeTypeResolverCache()`. The hot-reload upsert/remove handlers in `loader.ts` do both. If the resolver's cache outlives a program rebuild, the resolver returns stale expanded text and the runtime validator will reject valid payloads.
+
+---
+
+## Failure modes
+
+- **Missing `tsconfig.server.json`.** `getServerProgram()` throws synchronously. Boot fails loudly; there is no fallback.
+- **TypeScript version drift.** `typescript` is a required peer dependency at `~5.7.3`. A consumer with a different `typescript` version may produce different inlined output (`checker.typeToString` formatting drifts across TS versions). Treat this as a hard peer.
+- **Depth limit hit.** `expandTypeDetailed` returns `checker.typeToString(type)` and records the type's symbol as unresolved. The emitter logs the offending route (`[TypeMapGenerator] Unresolved API type (page/name/version): SymbolName`) and aborts the whole generation if any unresolved symbol cannot be imported.
+- **Cyclic type.** Same as depth-limit hit — short-circuit to the type's string form and record the symbol.
+- **Symbol with no source file.** The fallback returns `{ name }` without `sourceFile` or `importPath`. The emitter treats this as a hard unresolved alias and aborts generation.
+- **Stale cache after a file change.** If `invalidateProgramCache()` is not called between a file change and the next extraction, the extractor will see the previous file contents. The hot-reload loader handles this; consumers calling extractors directly must invalidate themselves.
+
+---
+
+## Constants
+
+- `DEPTH_LIMIT = 12` — recursion cap for `expandTypeDetailed`.
+- `JSON_TYPE_NAMES` — set of seven Prisma-related JSON aliases that short-circuit to `JsonValue`.
+- `SKIP_EXPANSION` — set of opaque generic / built-in container names that pass through unexpanded.
+
+These constants are not exported. They are tuning knobs internal to the expander; changing them requires regenerating the type map for every consumer project to verify no previously-expanding type now bottoms out as an unresolved alias.