theokit 0.4.0-beta.0 → 0.4.0

package/dist/{chunk-BIGBFZSU.js → chunk-2F4FROEQ.js}

@@ -1,481 +1,770 @@
+import {
+  buildServicesProxyConfig,
+  servicesConfigSchema
+} from "./chunk-DNMSV3R3.js";
 import {
   broadcastToDevtools
 } from "./chunk-7BIM27LV.js";
 import {
-  buildServicesProxyConfig,
-  servicesConfigSchema
-} from "./chunk-O4BLVPML.js";
+  loadEnv,
+  resolveTransformer
+} from "./chunk-PIVX3DYW.js";
+import {
+  findSuggestion
+} from "./chunk-5QW7IQQU.js";
+import {
+  createPluginRunnerFromConfig
+} from "./chunk-IAJ2JVEH.js";
+import {
+  createRateLimiter
+} from "./chunk-VMEWD57H.js";
+import {
+  createViteLoader
+} from "./chunk-JQSKBMXP.js";
+import {
+  matchRoute,
+  scanServerRoutes,
+  scanWebSocketRoutes
+} from "./chunk-OLPB36O2.js";
+import {
+  scanServerActions
+} from "./chunk-R7OC6UDK.js";
 import {
-  BATCH_PATH,
   CSP_REPORT_PATH,
   CsrfReadinessStore,
-  TRACE_HEADER,
   applySecurityHeaders,
+  handleCspReport,
+  handleCsrfReadiness
+} from "./chunk-B3L3TJVF.js";
+import {
+  generateNonce
+} from "./chunk-C3ZZ56YZ.js";
+import {
+  importUserModule
+} from "./chunk-7MQOHNHE.js";
+import {
+  BATCH_PATH,
+  TRACE_HEADER,
   createCorsHandler,
-  createPluginRunnerFromConfig,
-  createRateLimiter,
-  createViteLoader,
   executeAction,
   executeRoute,
   extractTraceId,
-  findSuggestion,
   handleBatchRequest,
-  handleCspReport,
-  handleCsrfReadiness,
-  loadEnv,
-  logRequest,
-  resolveTransformer,
   sendError
-} from "./chunk-CZM6WWWS.js";
-import {
-  matchRoute,
-  scanServerRoutes,
-  scanWebSocketRoutes
-} from "./chunk-B6RP57M3.js";
-import {
-  scanServerActions
-} from "./chunk-7TOMTMHT.js";
+} from "./chunk-5Z2727GV.js";
 import {
-  generateNonce
-} from "./chunk-PB4GR7EP.js";
+  logRequest
+} from "./chunk-Z5IGLBWE.js";
 
 // src/vite-plugin/index.ts
-import { existsSync as existsSync7 } from "fs";
-import { resolve as resolve6, basename, dirname as dirname4 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { resolve as resolve9, dirname as dirname4 } from "path";
 import { fileURLToPath } from "url";
 
-// src/devtools/server-side/route-manifest.ts
-function buildPath(parents, segment) {
-  const joined = [...parents, segment].filter(Boolean).join("/");
-  return "/" + joined;
-}
-function walk(node, parents, layoutChain, acc) {
-  const path = buildPath(parents, node.segment);
-  const nextChain = node.layout ? [...layoutChain, node.layout] : layoutChain;
-  if (node.page) {
-    acc.routes.push({
-      path,
-      absoluteFilePath: node.page,
-      layoutChain: [...layoutChain],
-      // freeze chain at this leaf
-      hasLoading: Boolean(node.loading),
-      hasError: Boolean(node.error),
-      hasNotFound: Boolean(node.notFound)
-    });
-  }
-  for (const child of node.children) {
-    const nextParents = node.segment ? [...parents, node.segment] : parents;
-    walk(child, nextParents, nextChain, acc);
-  }
-}
-function buildRouteManifest(tree) {
-  const acc = { routes: [] };
-  walk(tree, [], [], acc);
-  return { routes: acc.routes };
-}
-function broadcastRouteManifest(tree) {
-  const manifest = buildRouteManifest(tree);
-  broadcastToDevtools("theo:devtools:manifest", manifest);
+// src/vite-plugin/config-hook.ts
+import { existsSync } from "fs";
+import { resolve } from "path";
+function runConfigHook(ctx) {
+  const ext = existsSync(resolve(ctx.theoSrcDir, "index.ts")) ? ".ts" : ".js";
+  const warmupClientFiles = [];
+  for (const candidate of ["app/layout.tsx", "app/page.tsx", "app/page.jsx"]) {
+    const full = resolve(ctx.projectRoot, candidate);
+    if (existsSync(full)) warmupClientFiles.push(`./${candidate}`);
+  }
+  const servicesProxy = ctx.services && Object.keys(ctx.services).length > 0 ? buildServicesProxyConfig(ctx.services) : void 0;
+  return {
+    envPrefix: "THEO_PUBLIC_",
+    optimizeDeps: {
+      ...ctx.optimizeDepsInclude.length > 0 ? { include: ctx.optimizeDepsInclude } : {},
+      force: true
+    },
+    server: {
+      ...warmupClientFiles.length > 0 ? { warmup: { clientFiles: warmupClientFiles } } : {},
+      ...servicesProxy !== void 0 ? { proxy: servicesProxy } : {},
+      // Skip watching gitignored heavy dirs to avoid hitting ENOSPC
+      // (inotify watcher exhaustion).
+      watch: {
+        ignored: [
+          "**/referencias/**",
+          "**/.theokit/**",
+          "**/.theo/**",
+          "**/dist/**",
+          "**/node_modules/**"
+        ]
+      }
+    },
+    resolve: {
+      alias: [
+        // Order matters: most-specific first so `theokit/X` doesn't
+        // get matched by the bare `theokit` alias.
+        { find: "theokit/server", replacement: resolve(ctx.theoSrcDir, `server/index${ext}`) },
+        { find: "theokit/client", replacement: resolve(ctx.theoSrcDir, `client/index${ext}`) },
+        {
+          // T2.1 (M5 lonely folders) moved the source from
+          // `react-query/index.ts` into `client/react-query.ts` (sibling of
+          // `client/index.ts`). The package.json export `./react-query`
+          // still points at the build artifact `./dist/react-query/index.{js,d.ts}`,
+          // but the dev-time source alias must follow the new location.
+          find: "theokit/react-query",
+          replacement: resolve(ctx.theoSrcDir, `client/react-query${ext}`)
+        },
+        {
+          find: "theokit/vite-plugin",
+          replacement: resolve(ctx.theoSrcDir, `vite-plugin/index${ext}`)
+        },
+        {
+          find: "theokit/adapters/web-shim",
+          replacement: resolve(ctx.theoSrcDir, `adapters/web-shim${ext}`)
+        },
+        {
+          find: "theokit/adapters/ws-shim",
+          replacement: resolve(ctx.theoSrcDir, `adapters/ws-shim${ext}`)
+        },
+        // T1.2 — devtools entry (DEV only; tree-shaken in build).
+        // Source layout: src/devtools/dom/entry.tsx (has /dom/ segment)
+        // Dist layout:   dist/devtools/entry.js    (tsup flattens /dom/)
+        {
+          find: "theokit/devtools/entry",
+          replacement: resolve(
+            ctx.theoSrcDir,
+            ext === ".ts" ? "devtools/dom/entry.tsx" : "devtools/entry.js"
+          )
+        },
+        { find: "theokit", replacement: resolve(ctx.theoSrcDir, `index${ext}`) }
+      ]
+    }
+  };
 }
 
-// src/router/entry-server.ts
-function generateEntryServer(options = {}) {
-  if (options.streaming) {
-    return generateStreamingEntry(options);
-  }
-  return generateSingleShotEntry(options);
-}
-function buildAppTreeJs(options) {
-  const theme = options.theoUi?.theme ?? "violet-forge";
-  if (options.theoUi) {
-    return [
-      `React.createElement(TheoUIProvider, { theme: { defaultTheme: '${theme}' } },`,
-      `      React.createElement(Suspense, { fallback: null },`,
-      `        React.createElement(StaticRouterProvider, { router, context, hydrate: false })`,
-      `      )`,
-      `    )`
-    ].join("\n");
+// src/config/load-config.ts
+import { existsSync as existsSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+
+// src/config/errors.ts
+var TheoConfigError = class extends Error {
+  issues;
+  configPath;
+  constructor(issues, configPath) {
+    const issueLines = issues.map((i) => `  - ${i.field}: ${i.message}`).join("\n");
+    super(
+      `Invalid theo.config.ts
+
+  File: ${configPath}
+
+` + (issueLines ? `  Issues:
+${issueLines}
+` : "")
+    );
+    this.name = "TheoConfigError";
+    this.issues = issues;
+    this.configPath = configPath;
   }
-  return `React.createElement(Suspense, { fallback: null },
-      React.createElement(StaticRouterProvider, { router, context, hydrate: false })
-    )`;
-}
-function hydrationDataExtractSnippet() {
-  return [
-    `    const hydrationData = {`,
-    `      loaderData: context.loaderData,`,
-    `      actionData: context.actionData,`,
-    `      errors: context.errors,`,
-    `    }`
-  ].join("\n");
-}
-function generateSingleShotEntry(options) {
-  const theoUiImport = options.theoUi ? `import { TheoUIProvider } from '@theokit/ui'
-` : "";
-  const appTree = buildAppTreeJs(options);
-  return [
-    `import React, { Suspense } from 'react'`,
-    `import { renderToPipeableStream } from 'react-dom/server'`,
-    `import { createStaticHandler, createStaticRouter, StaticRouterProvider } from 'react-router'`,
-    `import { PassThrough } from 'node:stream'`,
-    `import { routes } from '/@theo/route-manifest'`,
-    theoUiImport,
-    `export async function render(url, options = {}) {`,
-    `  const handler = createStaticHandler(routes)`,
-    `  const request = new Request('http://localhost' + url)`,
-    `  const context = await handler.query(request)`,
-    ``,
-    `  if (context instanceof Response) {`,
-    `    return { redirect: context }`,
-    `  }`,
-    ``,
-    `  const router = createStaticRouter(handler.dataRoutes, context)`,
-    `  const app = ${appTree}`,
-    ``,
-    hydrationDataExtractSnippet(),
-    ``,
-    `  return new Promise((resolve, reject) => {`,
-    `    let html = ''`,
-    `    let piped = false`,
-    `    const passthrough = new PassThrough()`,
-    `    passthrough.on('data', (chunk) => { html += chunk.toString() })`,
-    `    passthrough.on('end', () => { resolve({ html, hydrationData }) })`,
-    `    passthrough.on('error', reject)`,
-    ``,
-    `    // Pipe on onShellReady (Next.js pattern). Calling pipe() twice`,
-    `    // throws "React currently only supports piping to one writable`,
-    `    // stream". The \`piped\` flag is a belt-and-suspenders guard if`,
-    `    // onShellReady fires unexpectedly more than once.`,
-    `    // Forward options.nonce to React so every <script> tag React`,
-    `    // emits (Suspense boundary scripts) carries the nonce attribute.`,
-    `    const { pipe } = renderToPipeableStream(app, {`,
-    `      nonce: options.nonce,`,
-    `      onShellReady() { if (!piped) { piped = true; pipe(passthrough) } },`,
-    `      onShellError(err) { reject(err) },`,
-    `      onError(err) { console.error('[SSR Error]', err) },`,
-    `    })`,
-    `  })`,
-    `}`
-  ].join("\n");
-}
-function streamingWebRenderer(appTree) {
-  return [
-    `// T2.3 \u2014 Web Standards streaming entry for edge runtimes (Cloudflare,`,
-    `// Bun, Deno, Vercel Edge). Uses renderToReadableStream and returns a`,
-    `// Response with the stream as body. Honors request.signal for client`,
-    `// disconnect cleanup.`,
-    `export async function renderStreamingWeb(request, options = {}) {`,
-    `  const handler = createStaticHandler(routes)`,
-    `  const url = new URL(request.url)`,
-    `  const context = await handler.query(request)`,
-    ``,
-    `  if (context instanceof Response) {`,
-    `    return context`,
-    `  }`,
-    ``,
-    `  const router = createStaticRouter(handler.dataRoutes, context)`,
-    `  const app = ${appTree}`,
-    ``,
-    `  const stream = await renderToReadableStream(app, {`,
-    `    signal: request.signal,`,
-    `    nonce: options.nonce,`,
-    `    onError(err) { console.error('[SSR Web Stream Error]', err) },`,
-    `  })`,
-    `  return new Response(stream, {`,
-    `    status: 200,`,
-    `    headers: {`,
-    `      'Content-Type': 'text/html; charset=utf-8',`,
-    `      'Transfer-Encoding': 'chunked',`,
-    `    },`,
-    `  })`,
-    `}`
-  ];
-}
-function streamingNodeRenderer(appTree) {
-  return [
-    `// T6.1 \u2014 Node streaming SSR entry (opt-in via theo.config.ts > ssrStreaming: true)`,
-    `// Flushes the shell as soon as it's ready, then streams Suspense boundaries.`,
-    `// EC-11: respects request.signal for client-disconnect cleanup.`,
-    `export async function renderStreaming(url, response, options = {}) {`,
-    `  const handler = createStaticHandler(routes)`,
-    `  const request = new Request('http://localhost' + url, { signal: options.signal })`,
-    `  const context = await handler.query(request)`,
-    ``,
-    `  if (context instanceof Response) {`,
-    `    return { redirect: context }`,
-    `  }`,
-    ``,
-    `  const router = createStaticRouter(handler.dataRoutes, context)`,
-    `  const app = ${appTree}`,
-    ``,
-    `  return new Promise((resolve, reject) => {`,
-    `    let didError = false`,
-    `    const stream = renderToPipeableStream(app, {`,
-    `      nonce: options.nonce,`,
-    `      onShellReady() {`,
-    `        response.statusCode = didError ? 500 : 200`,
-    `        response.setHeader('Content-Type', 'text/html; charset=utf-8')`,
-    `        response.setHeader('Transfer-Encoding', 'chunked')`,
-    `        stream.pipe(response)`,
-    `        resolve({ streaming: true })`,
-    `      },`,
-    `      onShellError(err) { reject(err) },`,
-    `      onError(err) {`,
-    `        didError = true`,
-    `        console.error('[SSR Stream Error]', err)`,
-    `      },`,
-    `    })`,
-    ``,
-    `    // EC-11: client disconnect cleanup`,
-    `    if (options.signal) {`,
-    `      options.signal.addEventListener('abort', () => { stream.abort() })`,
-    `    }`,
-    `  })`,
-    `}`
-  ];
-}
-function backCompatRenderer(appTree) {
-  return [
-    `// Backward compatibility: keep the single-shot render export available so`,
-    `// callers that always used 'render()' don't break when streaming is on.`,
-    `export async function render(url, options = {}) {`,
-    `  const handler = createStaticHandler(routes)`,
-    `  const request = new Request('http://localhost' + url)`,
-    `  const context = await handler.query(request)`,
-    ``,
-    `  if (context instanceof Response) {`,
-    `    return { redirect: context }`,
-    `  }`,
-    ``,
-    `  const router = createStaticRouter(handler.dataRoutes, context)`,
-    `  const app = ${appTree}`,
-    ``,
-    hydrationDataExtractSnippet(),
-    ``,
-    `  const { PassThrough } = await import('node:stream')`,
-    `  return new Promise((resolve, reject) => {`,
-    `    let html = ''`,
-    `    let piped = false`,
-    `    const passthrough = new PassThrough()`,
-    `    passthrough.on('data', (chunk) => { html += chunk.toString() })`,
-    `    passthrough.on('end', () => { resolve({ html, hydrationData }) })`,
-    `    passthrough.on('error', reject)`,
-    ``,
-    `    // Pipe on onShellReady (Next.js pattern). nonce forwarded.`,
-    `    const { pipe } = renderToPipeableStream(app, {`,
-    `      nonce: options.nonce,`,
-    `      onShellReady() { if (!piped) { piped = true; pipe(passthrough) } },`,
-    `      onShellError(err) { reject(err) },`,
-    `      onError(err) { console.error('[SSR Error]', err) },`,
-    `    })`,
-    `  })`,
-    `}`
-  ];
-}
-function generateStreamingEntry(options) {
-  const theoUiImport = options.theoUi ? `import { TheoUIProvider } from '@theokit/ui'
-` : "";
-  const appTree = buildAppTreeJs(options);
-  return [
-    `import React, { Suspense } from 'react'`,
-    `import { renderToPipeableStream, renderToReadableStream } from 'react-dom/server'`,
-    `import { createStaticHandler, createStaticRouter, StaticRouterProvider } from 'react-router'`,
-    `import { routes } from '/@theo/route-manifest'`,
-    theoUiImport,
-    ``,
-    ...streamingWebRenderer(appTree),
-    ``,
-    ...streamingNodeRenderer(appTree),
-    ``,
-    ...backCompatRenderer(appTree)
-  ].join("\n");
-}
+};
 
-// src/router/entry.ts
-function generateEntryClient(ssr, opts = {}) {
-  const rootMethod = ssr ? "hydrateRoot" : "createRoot";
-  const theoUiImports = [];
-  if (opts.theoUi) {
-    theoUiImports.push(
-      `// T2.2 \u2014 TheoUI CSS auto-injected (config.ui)`,
-      `import '@theokit/ui/styles.css'`
-    );
-    const fontsModule = opts.theoUi.fonts === "cdn" ? "fonts-cdn.css" : "fonts.css";
-    theoUiImports.push(
-      `import '@theokit/ui/${fontsModule}'`,
-      `// T2.3 \u2014 TheoUIProvider auto-wraps RouterProvider`,
-      `import { TheoUIProvider } from '@theokit/ui'`
+// src/config/schema.ts
+import { z as z8 } from "zod";
+
+// src/config/schemas/header-safe.ts
+import { z } from "zod";
+var headerSafeString = z.string().refine((s) => !/[\r\n]/.test(s), { message: "Header value must not contain CR/LF" });
+
+// src/config/schemas/rate-limit.ts
+import { z as z2 } from "zod";
+var baseRateLimitSchema = z2.object({
+  windowMs: z2.number().min(1),
+  max: z2.number().int().min(1)
+});
+var rateLimitSchema = z2.union([
+  baseRateLimitSchema,
+  z2.object({
+    default: baseRateLimitSchema.optional(),
+    routes: z2.record(z2.string(), baseRateLimitSchema).optional(),
+    keyBy: z2.union([
+      z2.enum(["ip", "session", "user"]),
+      z2.function({ input: z2.tuple([z2.unknown()]), output: z2.string() })
+    ]).optional(),
+    cookieName: z2.string().min(1).optional()
+  })
+]);
+
+// src/config/schemas/upload.ts
+import { z as z3 } from "zod";
+var uploadSchema = z3.object({
+  maxFileSize: z3.number().min(1).default(10 * 1024 * 1024),
+  // 10MB
+  maxFiles: z3.number().int().min(1).default(10),
+  maxFieldSize: z3.number().min(1).default(1 * 1024 * 1024)
+  // 1MB
+});
+
+// src/config/schemas/logging.ts
+import { z as z4 } from "zod";
+var loggingSchema = z4.object({
+  level: z4.enum(["debug", "info", "warn", "error", "silent"]).default("info")
+});
+
+// src/config/schemas/cache.ts
+import { z as z5 } from "zod";
+var routeRuleSchema = z5.object({
+  maxAge: z5.number().nonnegative().finite().optional(),
+  swr: z5.number().nonnegative().finite().optional(),
+  tags: z5.array(z5.string()).optional()
+});
+var cacheSchema = z5.object({
+  enabled: z5.boolean().default(true),
+  /** 'memory' uses InMemoryCacheAdapter; otherwise pass a custom adapter instance. */
+  storage: z5.union([z5.literal("memory"), z5.custom()]).default("memory"),
+  maxEntries: z5.number().int().positive().default(1e3),
+  defaults: z5.object({
+    maxAge: z5.number().nonnegative().finite().default(1),
+    swr: z5.number().nonnegative().finite().optional(),
+    cacheErrors: z5.boolean().default(false)
+  }).default({ maxAge: 1, cacheErrors: false }),
+  keyDerivation: z5.object({
+    excludeQuery: z5.array(z5.string()).optional(),
+    sortQuery: z5.boolean().default(true),
+    lowercaseHost: z5.boolean().default(true)
+  }).default({ sortQuery: true, lowercaseHost: true }),
+  routeRules: z5.record(z5.string(), routeRuleSchema).optional()
+});
+
+// src/config/schemas/security.ts
+import { z as z6 } from "zod";
+var securityHeadersSchema = z6.object({
+  csp: z6.union([headerSafeString, z6.literal(false)]).optional(),
+  // T6.1 — default flipped from 'report-only' to 'enforce' for 0.3.0.
+  // Users who want the old behaviour set `cspMode: 'report-only'`
+  // explicitly. See docs/migrating/0.2-to-0.3.md.
+  cspMode: z6.enum(["enforce", "report-only", "off"]).default("enforce"),
+  hsts: z6.union([headerSafeString, z6.literal(false)]).optional(),
+  frameOptions: z6.enum(["DENY", "SAMEORIGIN"]).default("DENY"),
+  contentTypeOptions: z6.literal("nosniff").default("nosniff"),
+  referrerPolicy: headerSafeString.default("strict-origin-when-cross-origin"),
+  /**
+   * T1.1 — Permissions-Policy directive string. EC-3-refined: rejects CR/LF.
+   * Pass `false` to suppress the header.
+   */
+  permissionsPolicy: z6.union([headerSafeString, z6.literal(false)]).optional()
+});
+var disallowedConfigSchema = z6.object({
+  routes: z6.array(z6.union([z6.string(), z6.instanceof(RegExp)])),
+  behavior: z6.enum(["warn", "raise"]).default("raise")
+});
+var corsSchema = z6.object({
+  origins: z6.union([
+    z6.literal("*"),
+    headerSafeString,
+    z6.instanceof(RegExp),
+    z6.array(z6.union([headerSafeString, z6.instanceof(RegExp)])),
+    z6.function({ input: z6.tuple([z6.string()]), output: z6.boolean() })
+  ]),
+  methods: z6.array(z6.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"])).optional(),
+  allowedHeaders: z6.array(headerSafeString).optional(),
+  exposedHeaders: z6.array(headerSafeString).optional(),
+  credentials: z6.boolean().default(false),
+  maxAge: z6.number().int().min(0).max(86400).default(600)
+}).refine((c) => !(c.origins === "*" && c.credentials), {
+  message: 'CORS spec forbids origins:"*" with credentials:true \u2014 browsers ignore the wildcard'
+});
+var securitySchema = z6.object({
+  // T6.1 — default flipped from 'warn' to 'strict' for 0.3.0. Apps that
+  // grep their warn-mode logs from 0.2.x already know which endpoints
+  // break; opt back into 'warn' globally OR use disallowedRoutes for
+  // surgical migration. See docs/migrating/0.2-to-0.3.md.
+  csrf: z6.enum(["off", "warn", "strict"]).default("strict"),
+  headers: securityHeadersSchema.optional(),
+  /** T5.1 — per-route escalation (Rails disallowed_warnings pattern). */
+  disallowed: disallowedConfigSchema.optional(),
+  /** T1.2 — Cross-Origin Resource Sharing. Single global config; runs first in pipeline. */
+  cors: corsSchema.optional()
+});
+
+// src/config/schemas/storage.ts
+import { z as z7 } from "zod";
+var tlsConfigSchema = z7.object({
+  rejectUnauthorized: z7.boolean().optional(),
+  caCert: z7.string().optional(),
+  clientCert: z7.string().optional(),
+  clientKey: z7.string().optional()
+});
+var serverConfigSchema = z7.object({
+  host: z7.string().min(1),
+  port: z7.number().int().positive().max(65535).optional(),
+  user: z7.string().min(1),
+  /** Password may be the empty string (some providers permit it). */
+  password: z7.string(),
+  tls: tlsConfigSchema.optional()
+});
+var postgresPoolConfigSchema = z7.object({
+  min: z7.number().int().nonnegative().optional(),
+  max: z7.number().int().positive().optional(),
+  connectionTimeoutMillis: z7.number().int().positive().optional(),
+  idleTimeoutMillis: z7.number().int().nonnegative().optional()
+});
+var postgresDatabaseConfigSchema = z7.object({
+  /** References a key in `storage.servers`. Resolved at `usePostgres()` call time. */
+  server: z7.string().min(1),
+  database: z7.string().min(1),
+  pool: postgresPoolConfigSchema.optional()
+});
+var redisServerConfigSchema = serverConfigSchema.extend({
+  db: z7.number().int().nonnegative().optional(),
+  maxRetriesPerRequest: z7.number().int().nonnegative().optional()
+});
+var storageSchema = z7.object({
+  servers: z7.record(z7.string(), serverConfigSchema).optional(),
+  databases: z7.record(z7.string(), postgresDatabaseConfigSchema).optional(),
+  redis: z7.record(z7.string(), redisServerConfigSchema).optional()
+});
+
+// src/config/schema.ts
+var theoConfigSchema = z8.object({
+  /**
+   * Plan v1.2 T2.1 — project identifier propagated into
+   * `.theo/services.json` v2 `project` field. DNS-1123 compatible (drives
+   * Gitea repo + ArgoCD App naming on TheoCloud). When omitted, the build
+   * emits services.json v1 with the legacy `services-bundle` fallback
+   * (ADR D10) and logs a deprecation warning.
+   */
+  name: z8.string().max(63).refine(
+    // DNS-1123 equivalent expressed as explicit single-char anchors so
+    // security/detect-unsafe-regex stays clean (no backtracking).
+    (value) => value.length > 0 && /^[a-z0-9-]+$/u.test(value) && !value.startsWith("-") && !value.endsWith("-"),
+    "name must match DNS-1123 (lowercase alphanumeric+hyphens, 1-63 chars, no leading/trailing hyphen)"
+  ).optional(),
+  appDir: z8.string().default("app"),
+  serverDir: z8.string().default("server"),
+  /**
+   * T2.2 / EC-4 — Build output directory. Must be a relative path inside
+   * the project root. Refused absolute or parent-relative paths to prevent
+   * `cleanOutDir` from wiping arbitrary locations (defense-in-depth on
+   * top of cleanOutDir's runtime EC-3 guard).
+   */
+  distDir: z8.string().default(".theo").refine(
+    (d) => !/^([A-Za-z]:)?[/\\]/.test(d) && !d.startsWith(".."),
+    'distDir must be a relative path inside the project root (e.g., ".theo")'
+  ),
+  /**
+   * Agent runtime configuration.
+   *
+   * - `maxRegistries` (T2.3, legacy): dev-mode cleanup of stale
+   *   `.theokit/agents/<id>/` dirs by mtime. Now superseded by SDK's
+   *   native registry GC but kept for backward-compat.
+   * - `registry` (Phase 6, Production-Readiness #2): forwarded to
+   *   `Agent.registry.configure()` lazily on first request.
+   *   * `maxAgents` — LRU cap. MUST be ≥ max-concurrent-active-conversations
+   *     (EC-17 DOCUMENT): with maxAgents:1 and 2 concurrent chats, LRU evicts
+   *     mid-stream → SDK aborts with code:'aborted'. Default 100 covers
+   *     indie/small-team; tune up for high-traffic.
+   *   * `idleTimeoutMs` — auto-evict idle agents (default 30 min). 0 disables
+   *     idle eviction (LRU only).
+   */
+  agents: z8.object({
+    maxRegistries: z8.number().int().positive().default(100),
+    registry: z8.object({
+      /** LRU cap — MUST be ≥ max-concurrent-active-conversations. */
+      maxAgents: z8.number().int().positive().max(1e4).default(100),
+      /** Idle eviction window in ms. 0 disables idle eviction (LRU only). */
+      idleTimeoutMs: z8.number().int().nonnegative().default(30 * 6e4)
+    }).optional()
+  }).optional(),
+  port: z8.number().int().min(1).max(65535).default(3e3),
+  ssr: z8.boolean().default(false),
+  /** When true (and ssr === true), use renderToPipeableStream with progressive
+   * shell flush instead of single-shot renderToString. Opt-in for streaming
+   * SSR; default false preserves the current behavior. */
+  ssrStreaming: z8.boolean().default(false),
+  rateLimit: rateLimitSchema.optional(),
+  upload: uploadSchema.optional(),
+  logging: loggingSchema.optional(),
+  security: securitySchema.optional(),
+  serialization: z8.enum(["json", "superjson"]).default("json"),
+  // Plugins are validated structurally at runtime by createPluginRunnerFromConfig.
+  // Zod only checks the shape minimally (must be array). Type-level safety is
+  // provided through defineConfig at the user surface.
+  plugins: z8.array(z8.unknown()).optional(),
+  /** Enable client-side batching of theoFetch calls and the
+   * /api/__theo_batch__ server endpoint. */
+  batching: z8.union([z8.boolean(), z8.object({ max: z8.number().int().positive().optional() })]).optional(),
+  /** T4.1 — Audit log. When `logger` is provided, framework events
+   * (csrf.warn, rate-limit.exceeded, session.rotated, csp.violation) are
+   * emitted to it. Default: noop. */
+  audit: z8.object({
+    logger: z8.unknown().optional()
+  }).optional(),
+  /** TheoUI auto-wire (T2.1). `false` = opt-out; object = explicit theme/fonts;
+   * undefined = enabled when @theokit/ui is detected in node_modules. */
+  ui: z8.union([
+    z8.literal(false),
+    z8.object({
+      theme: z8.enum(["violet-forge", "noir", "paper"]).optional(),
+      fonts: z8.enum(["bundled", "cdn"]).optional()
+    })
+  ]).optional(),
+  /**
+   * Cache subsystem (caching-and-revalidation-plan).
+   * Default `undefined` keeps caching disabled (backward compatible).
+   * Pass `cache: {}` to opt in with defaults.
+   */
+  cache: cacheSchema.optional(),
+  /**
+   * Devtools overlay (Phase 0.4.0+ — see docs/plans/devtools-plan.md).
+   *
+   * - `undefined` (default): devtools auto-injects in `pnpm dev`, NEVER in `vite build`.
+   * - `false`: devtools disabled entirely (Vite plugin skips injection even in dev).
+   * - `{ ... }`: devtools enabled with explicit defaults (position, theme).
+   *
+   * Tree-shaken to noop in prod via the dual-export pattern in
+   * `packages/theo/src/devtools/index.ts` (EC-17 positive prod check).
+   */
+  devtools: z8.union([
+    z8.literal(false),
+    z8.object({
+      position: z8.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional(),
+      theme: z8.enum(["light", "dark", "system"]).optional()
+    })
+  ]).optional(),
+  /**
+   * Informative list of deploy adapters the app supports. Does NOT
+   * trigger per-build translations — only the `--target` CLI flag does
+   * (EC-201 / ADR D2). If `config.adapters` includes a target NOT
+   * matching `--target`, `theokit build` emits a cross-reference note.
+   */
+  adapters: z8.array(z8.string()).optional(),
+  /**
+   * Extra package names to pre-bundle via Vite's `optimizeDeps.include`.
+   *
+   * Framework auto-includes `@theokit/ui` and `lucide-react` when present.
+   * Apps adding plugin peer-deps that rely on a runtime `import('<pkg>')`
+   * (dynamic specifier) — e.g. `@theokit/plugin-canvas` consumers
+   * installing `mermaid` for Mermaid SVG rendering — must declare those
+   * here so Vite can resolve the literal in dev mode without
+   * "Failed to resolve module specifier" errors. Production builds use
+   * tsup/esbuild bundling and are not affected.
+   *
+   * Example:
+   *   viteOptimizeDeps: ['mermaid']
+   */
+  viteOptimizeDeps: z8.array(z8.string()).optional(),
+  /**
+   * Jobs backend (ADR D3 + T2.1). When configured, every request gets
+   * `ctx.queue.enqueue` auto-wired via the outbox lifecycle. Pass a
+   * `JobBackend` instance (InMemoryJobBackend, PostgresJobBackend, etc.).
+   */
+  jobs: z8.object({
+    backend: z8.custom((v) => typeof v === "object" && v !== null)
+  }).optional(),
+  /**
+   * StorageManager configuration (T1.1 / ADR-0007).
+   *
+   * Declares Postgres servers + databases + Redis servers. Consumed by
+   * `getStorageManager().configure()` at boot via `start.ts`.
+   *
+   * Default `undefined` means manager exists but is not configured — adapters
+   * relying on the manager (PostgresJobBackend.fromStorageManager, etc.) will
+   * throw with an actionable error on first use.
+   */
+  storage: storageSchema.optional(),
+  /**
+   * Wave 2 — Polyglot services orchestration (T1.1 / ADR-0012/0013/0014/0015).
+   *
+   * Declarative external sidecar processes (Python FastAPI / Node Hono)
+   * that boot alongside the TheoKit TS app. Empty `services: {}` is the
+   * default and preserves Wave 1 behavior.
+   */
+  services: servicesConfigSchema,
+  /**
+   * G2 — OpenAPI emit (build-time only).
+   *
+   * When present, `theokit build` writes a generated `openapi.json` from
+   * every `defineRoute()` body/query/params Zod schema. `undefined` keeps
+   * the framework backward-compatible (no emit). Pass `openapi: {}` to
+   * opt in with defaults.
+   *
+   * Defaults: spec 3.1.0 · servers `http://localhost:3000` · title
+   * "TheoKit App" · version "0.0.0" · outDir ".theo" (next to dist).
+   *
+   * The env var `THEOKIT_OPENAPI_SERVERS` (CSV of URLs) overrides
+   * `servers[].url` at emit time without rebuilding the config.
+   */
+  openapi: z8.object({
+    servers: z8.array(
+      z8.object({
+        url: z8.string().url(),
+        description: z8.string().optional()
+      })
+    ).default([{ url: "http://localhost:3000", description: "Local development" }]),
+    specVersion: z8.enum(["3.1.0", "3.0.3"]).default("3.1.0"),
+    title: z8.string().default("TheoKit App"),
+    version: z8.string().default("0.0.0"),
+    outDir: z8.string().default(".theo")
+  }).optional(),
+  /**
+   * G5 T1.3 — error envelope transformer hook (blueprint ADR D3).
+   *
+   * When present, runs at framework error-boundary time to enrich the
+   * envelope with consumer-defined extensions (`hint`, custom telemetry
+   * tags, etc.) BEFORE the envelope is serialized to the client. The
+   * function signature is preserved via the explicit `FormatErrorHook`
+   * type — TS inference flows from `theo.config.ts` into `@theo/client`
+   * codegen and `@theokit/ui` AgentErrorCard consumers.
+   *
+   * Use `z.custom<FormatErrorHook>(...)` because Zod's built-in
+   * `z.function()` discards its TS signature after parse; `z.custom`
+   * with a function-typed runtime guard preserves the call-site type
+   * without trading off Zod runtime validation.
+   */
+  formatError: z8.custom((val) => typeof val === "function", {
+    message: "formatError must be a function"
+  }).optional()
+}).refine((cfg) => !Object.values(cfg.services).some((s) => s.port === cfg.port), {
+  message: "service.port collides with TheoKit web port \u2014 change one of them",
+  path: ["services"]
+});
+
+// src/config/load-config.ts
+var CONFIG_FILE = "theo.config.ts";
+function deepMerge(base, override) {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    const baseVal = base[key];
+    const overVal = override[key];
+    if (overVal !== null && typeof overVal === "object" && !Array.isArray(overVal) && baseVal !== null && typeof baseVal === "object" && !Array.isArray(baseVal)) {
+      result[key] = deepMerge(
+        baseVal,
+        overVal
+      );
+    } else {
+      result[key] = overVal;
+    }
+  }
+  return result;
+}
+async function loadConfig(dir) {
+  loadEnv({ cwd: dir });
+  const configPath = resolve2(dir, CONFIG_FILE);
+  if (!existsSync2(configPath)) {
+    return theoConfigSchema.parse({});
+  }
+  let mod;
+  try {
+    mod = await importUserModule(configPath);
+  } catch (err) {
+    throw new TheoConfigError([{ field: "_file", message: err.message }], configPath);
+  }
+  const userConfig = mod.default;
+  if (userConfig == null || typeof userConfig !== "object") {
+    throw new TheoConfigError(
+      [
+        {
+          field: "_export",
+          message: "theo.config.ts must use export default defineConfig({...})"
+        }
+      ],
+      configPath
     );
   }
-  const theme = opts.theoUi?.theme ?? "violet-forge";
-  const routerTree = opts.theoUi ? `React.createElement(TheoUIProvider, { theme: { defaultTheme: '${theme}' } },
-      React.createElement(Suspense, { fallback: null },
-        React.createElement(RouterProvider, { router })
-      )
-    )` : `React.createElement(Suspense, { fallback: null },
-      React.createElement(RouterProvider, { router })
-    )`;
-  const renderCall = ssr ? `  ${rootMethod}(el,
-    ${routerTree}
-  )` : `  ${rootMethod}(el).render(
-    ${routerTree}
-  )`;
-  const hydrationLine = ssr ? `const router = createBrowserRouter(routes, { hydrationData: window.__staticRouterHydrationData })` : `const router = createBrowserRouter(routes)`;
-  const preloadBlock = ssr ? [
-    `// Phase 4 \u2014 preload matched-route modules before hydrate (EC-3 safeguard)`,
-    `const __theoMatches = matchRoutes(routes, window.location.pathname) ?? []`,
-    `const __theoPreloadPaths = __theoMatches`,
-    `  .map((m) => m.route && (m.route).path)`,
-    `  .filter((p) => typeof p === 'string' && p in __theoPreloadMap)`,
-    `const __theoPreloadPromise = Promise.all(`,
-    `  __theoPreloadPaths.map((p) => __theoPreloadMap[p]().catch((err) => { console.error('[theo] preload failed', p, err); return null }))`,
-    `)`,
-    `const __theoTimeout = new Promise((resolve) => setTimeout(() => resolve('timeout'), 1500))`,
-    `await Promise.race([__theoPreloadPromise, __theoTimeout])`,
-    ""
-  ] : [];
-  const renderBlock = ssr ? [
-    `if (el) {`,
-    `  ;(async () => {`,
-    ...preloadBlock.map((l) => "    " + l),
-    renderCall,
-    `  })()`,
-    `}`
-  ] : [`if (el) {`, renderCall, `}`];
-  const manifestImports = ssr ? `import { routes, __theoPreloadMap } from '/@theo/route-manifest'` : `import { routes } from '/@theo/route-manifest'`;
-  const reactRouterImports = ssr ? `import { createBrowserRouter, RouterProvider, matchRoutes } from 'react-router'` : `import { createBrowserRouter, RouterProvider } from 'react-router'`;
-  return [
-    `import React, { Suspense } from 'react'`,
-    `import { ${rootMethod} } from 'react-dom/client'`,
-    reactRouterImports,
-    manifestImports,
-    `// T1.3 \u2014 side-effect import sets globalThis.__THEO_TRANSFORMER__ for theoFetch`,
-    `import '/@theo/runtime-config'`,
-    ...theoUiImports,
-    ``,
-    hydrationLine,
-    `const el = document.getElementById('root')`,
-    ...renderBlock
-  ].join("\n");
+  let rawConfig = userConfig;
+  const nodeEnv = process.env.NODE_ENV;
+  if (nodeEnv) {
+    const envFile = `theo.config.${nodeEnv}.ts`;
+    const envPath = resolve2(dir, envFile);
+    if (existsSync2(envPath)) {
+      try {
+        const envMod = await importUserModule(envPath);
+        const envConfig = envMod.default;
+        if (envConfig != null && typeof envConfig === "object") {
+          rawConfig = deepMerge(rawConfig, envConfig);
+        }
+      } catch (err) {
+        throw new TheoConfigError([{ field: "_file", message: err.message }], envPath);
+      }
+    }
+  }
+  const result = theoConfigSchema.safeParse(rawConfig);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => ({
+      field: i.path.join("."),
+      message: i.message
+    }));
+    throw new TheoConfigError(issues, configPath);
+  }
+  return result.data;
 }
 
-// src/router/generate.ts
-function normalizePath(p) {
-  return p.replace(/\\/g, "/");
-}
-function safeVarName(segment, prefix) {
-  const safe = segment.replace(/[^a-zA-Z0-9]/g, "_") || "root";
-  return `${prefix}_${safe}`;
-}
-function buildRoutePath(parents, segment) {
-  const joined = [...parents, segment].filter(Boolean).join("/");
-  return "/" + joined;
+// src/vite-plugin/theoui-detect.ts
+import { existsSync as existsSync3, readFileSync } from "fs";
+import { dirname, join } from "path";
+function resolveTheoUiConfig(raw) {
+  return {
+    theme: raw?.theme ?? "violet-forge",
+    fonts: raw?.fonts ?? "bundled"
+  };
 }
-function pushIf(staticImports, filePath, varName) {
-  if (filePath !== void 0) {
-    staticImports.push({ varName, importPath: normalizePath(filePath) });
+function resolveExportSubpath(pkgRoot, subpath) {
+  const pkgJsonPath = join(pkgRoot, "package.json");
+  if (!existsSync3(pkgJsonPath)) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+    const exportKey = `./${subpath}`;
+    const exp = pkg.exports?.[exportKey];
+    if (!exp) {
+      const fallback = join(pkgRoot, "dist", subpath);
+      return existsSync3(fallback) ? fallback : null;
+    }
+    let target;
+    if (typeof exp === "string") target = exp;
+    else if (typeof exp === "object") {
+      const e = exp;
+      target = e.import ?? e.default;
+    }
+    if (!target) return null;
+    const cleaned = target.replace(/^\.\//, "");
+    const candidate = join(pkgRoot, cleaned);
+    return existsSync3(candidate) ? candidate : null;
+  } catch {
+    return null;
   }
 }
-function walkRouteTree(node, parents, acc) {
-  const seg = node.segment || "root";
-  const routePath = buildRoutePath(parents, node.segment);
-  if (node.page !== void 0) {
-    acc.lazyPages.push({
-      varName: safeVarName(seg, "Page"),
-      importPath: normalizePath(node.page),
-      routePath
-    });
+var defaultResolver = (specifier, projectRoot) => {
+  const parts = specifier.split("/");
+  const pkgName = parts[0]?.startsWith("@") && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+  if (!pkgName) return false;
+  const subpath = specifier.slice(pkgName.length + 1);
+  if (!subpath) return false;
+  let dir = projectRoot;
+  for (let depth = 0; depth < 10; depth++) {
+    const pkgRoot = join(dir, "node_modules", ...pkgName.split("/"));
+    if (existsSync3(pkgRoot)) {
+      const resolved = resolveExportSubpath(pkgRoot, subpath);
+      if (resolved) return true;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
-  if (node.layout !== void 0) acc.layoutState.found = true;
-  pushIf(acc.staticImports, node.layout, safeVarName(seg, "Layout"));
-  pushIf(acc.staticImports, node.error, safeVarName(seg, "Error"));
-  pushIf(acc.staticImports, node.loading, safeVarName(seg, "Loading"));
-  pushIf(acc.staticImports, node.notFound, safeVarName(seg, "NotFound"));
-  for (const child of node.children) {
-    const nextParents = node.segment ? [...parents, node.segment] : parents;
-    walkRouteTree(child, nextParents, acc);
+  return false;
+};
+function isDeclaredInPackageJson(projectRoot) {
+  try {
+    const raw = readFileSync(join(projectRoot, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw);
+    return Boolean(
+      pkg.dependencies?.["@theokit/ui"] ?? pkg.devDependencies?.["@theokit/ui"] ?? pkg.peerDependencies?.["@theokit/ui"]
+    );
+  } catch {
+    return false;
   }
 }
-function generateRouteManifest(tree) {
-  const acc = {
-    staticImports: [],
-    lazyPages: [],
-    layoutState: { found: false }
-  };
-  walkRouteTree(tree, [], acc);
-  const staticImports = acc.staticImports;
-  const lazyPages = acc.lazyPages;
-  const layoutState = acc.layoutState;
-  const lines = [`import React, { Suspense } from 'react'`];
-  if (layoutState.found) {
-    lines.push(`import { Outlet } from 'react-router'`);
-  }
-  lines.push("");
-  for (const imp of staticImports) {
-    lines.push(`import ${imp.varName} from '${imp.importPath}'`);
+function detectTheoUi(projectRoot, rawConfig, resolver = defaultResolver) {
+  const config = resolveTheoUiConfig(typeof rawConfig === "object" ? rawConfig : void 0);
+  if (rawConfig === false) {
+    return { enabled: false, config };
   }
-  for (const lp of lazyPages) {
-    lines.push(`const ${lp.varName} = React.lazy(() => import('${lp.importPath}'))`);
+  if (!isDeclaredInPackageJson(projectRoot)) {
+    return { enabled: false, config };
   }
-  lines.push("");
-  const preloadEntries = lazyPages.map(
-    (lp) => `  '${lp.routePath}': () => import('${lp.importPath}'),`
-  );
-  lines.push("export const __theoPreloadMap = {");
-  for (const e of preloadEntries) lines.push(e);
-  lines.push("}", "");
-  function buildChildrenArray(node, seg) {
-    const childConfigs = [];
-    if (node.page) {
-      const pageVar = safeVarName(seg, "Page");
-      const fallbackEl = node.loading ? `React.createElement(${safeVarName(seg, "Loading")})` : "null";
-      const pageElement = `React.createElement(Suspense, { fallback: ${fallbackEl} }, React.createElement(${pageVar}))`;
-      childConfigs.push(`{ index: true, element: ${pageElement} }`);
-    }
-    for (const child of node.children) {
-      childConfigs.push(genRouteConfig(child, false));
+  const probes = ["@theokit/ui/styles.css", "@theokit/ui/fonts.css"];
+  for (const probe of probes) {
+    if (resolver(probe, projectRoot)) {
+      return { enabled: true, config };
     }
-    if (node.notFound) {
-      const nfVar = safeVarName(seg, "NotFound");
-      childConfigs.push(`{ path: '*', element: React.createElement(${nfVar}) }`);
+  }
+  return { enabled: false, config };
+}
+
+// src/vite-plugin/config-resolve.ts
+var DEFAULT_RESOLVED = {
+  pluginRunner: void 0,
+  transformer: void 0,
+  resolvedBatching: void 0,
+  theoUi: void 0,
+  csrfMode: "strict",
+  securityHeaders: void 0,
+  disallowed: void 0,
+  cors: void 0,
+  auditLogger: void 0,
+  devtoolsEnabled: true,
+  openapi: void 0,
+  distDir: ".theo"
+};
+async function resolvePluginConfig(projectRoot) {
+  try {
+    const userConfig = await loadConfig(projectRoot);
+    const pluginRunner = await createPluginRunnerFromConfig(userConfig.plugins);
+    const transformer = resolveTransformer(userConfig.serialization);
+    let resolvedBatching;
+    if (userConfig.batching === true) {
+      resolvedBatching = {};
+    } else if (typeof userConfig.batching === "object") {
+      resolvedBatching = userConfig.batching;
     }
-    let arr = `[${childConfigs.join(", ")}]`;
-    if (node.error) {
-      const errVar = safeVarName(seg, "Error");
-      arr = `[{ errorElement: React.createElement(${errVar}), children: ${arr} }]`;
+    const theoUi = detectTheoUi(projectRoot, userConfig.ui);
+    let auditLogger;
+    const maybeLogger = userConfig.audit?.logger;
+    if (maybeLogger && typeof maybeLogger.log === "function") {
+      auditLogger = maybeLogger;
     }
-    return arr;
+    return {
+      pluginRunner,
+      transformer,
+      resolvedBatching,
+      theoUi,
+      csrfMode: userConfig.security?.csrf ?? "strict",
+      securityHeaders: userConfig.security?.headers,
+      disallowed: userConfig.security?.disallowed,
+      cors: userConfig.security?.cors,
+      auditLogger,
+      devtoolsEnabled: userConfig.devtools !== false,
+      openapi: userConfig.openapi,
+      distDir: userConfig.distDir
+    };
+  } catch {
+    return DEFAULT_RESOLVED;
+  }
+}
+
+// src/vite-plugin/configure-server-hook.ts
+import { resolve as resolve6, basename } from "path";
+
+// src/devtools/server-side/route-manifest.ts
+function buildPath(parents, segment) {
+  const joined = [...parents, segment].filter(Boolean).join("/");
+  return "/" + joined;
+}
+function walk(node, parents, layoutChain, acc) {
+  const path = buildPath(parents, node.segment);
+  const nextChain = node.layout ? [...layoutChain, node.layout] : layoutChain;
+  if (node.page) {
+    acc.routes.push({
+      path,
+      absoluteFilePath: node.page,
+      layoutChain: [...layoutChain],
+      // freeze chain at this leaf
+      hasLoading: Boolean(node.loading),
+      hasError: Boolean(node.error),
+      hasNotFound: Boolean(node.notFound)
+    });
   }
-  function genRouteConfig(node, isRoot) {
-    const seg = node.segment || "root";
-    const childrenArray = buildChildrenArray(node, seg);
-    if (node.layout) {
-      const layoutVar = safeVarName(seg, "Layout");
-      const pathPart = isRoot ? `path: '/'` : `path: '${node.segment}'`;
-      return `{ ${pathPart}, element: React.createElement(${layoutVar}, { children: React.createElement(Outlet) }), children: ${childrenArray} }`;
-    }
-    if (isRoot) {
-      if (node.children.length === 0 && !node.page && !node.notFound && !node.error) {
-        return `{ path: '/', children: [] }`;
-      }
-      return `{ path: '/', children: ${childrenArray} }`;
-    }
-    if (node.page && node.children.length === 0 && !node.error && !node.notFound) {
-      const pageVar = safeVarName(seg, "Page");
-      const fallbackEl = node.loading ? `React.createElement(${safeVarName(seg, "Loading")})` : "null";
-      const pageElement = `React.createElement(Suspense, { fallback: ${fallbackEl} }, React.createElement(${pageVar}))`;
-      return `{ path: '${node.segment}', element: ${pageElement} }`;
-    }
-    return `{ path: '${node.segment}', children: ${childrenArray} }`;
+  for (const child of node.children) {
+    const nextParents = node.segment ? [...parents, node.segment] : parents;
+    walk(child, nextParents, nextChain, acc);
   }
-  const routeConfig = genRouteConfig(tree, true);
-  lines.push(`export const routes = [${routeConfig}]`);
-  return lines.join("\n");
+}
+function buildRouteManifest(tree) {
+  const acc = { routes: [] };
+  walk(tree, [], [], acc);
+  return { routes: acc.routes };
+}
+function broadcastRouteManifest(tree) {
+  const manifest = buildRouteManifest(tree);
+  broadcastToDevtools("theo:devtools:manifest", manifest);
 }
 
 // src/router/scan.ts
-import { readdirSync, statSync, existsSync } from "fs";
-import { join, resolve } from "path";
+import { readdirSync, statSync, existsSync as existsSync4 } from "fs";
+import { join as join2, resolve as resolve3 } from "path";
 
 // src/router/types.ts
 var ROUTE_FILE_NAMES = ["page", "layout", "error", "loading", "not-found"];
@@ -515,8 +804,8 @@ function attachRouteFiles(node, dir) {
     if (node[key] !== void 0) continue;
     for (const ext of ROUTE_FILE_EXTENSIONS) {
       const filename = `${name}${ext}`;
-      if (existsSync(join(dir, filename))) {
-        setRouteFile(node, key, resolve(dir, filename));
+      if (existsSync4(join2(dir, filename))) {
+        setRouteFile(node, key, resolve3(dir, filename));
         break;
       }
     }
@@ -531,8 +820,10 @@ function scanDir(dir, segment, routePath) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
     if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
-    const childPath = routePath === "/" ? `/${entry.name}` : `${routePath}/${entry.name}`;
-    const child = scanDir(join(dir, entry.name), entry.name, childPath);
+    const isRouteGroup = entry.name.startsWith("(") && entry.name.endsWith(")");
+    const urlSegment = isRouteGroup ? "" : entry.name;
+    const childPath = urlSegment ? routePath === "/" ? `/${urlSegment}` : `${routePath}/${urlSegment}` : routePath;
+    const child = scanDir(join2(dir, entry.name), isRouteGroup ? "" : entry.name, childPath);
     if (nodeHasContent(child)) {
       node.children.push(child);
     }
@@ -540,7 +831,7 @@ function scanDir(dir, segment, routePath) {
   return node;
 }
 function scanRoutes(appDir) {
-  if (!existsSync(appDir)) {
+  if (!existsSync4(appDir)) {
     throw new Error(`App directory does not exist: ${appDir}`);
   }
   if (!statSync(appDir).isDirectory()) {
@@ -680,10 +971,10 @@ async function handleBatchIfMatch(req, res, ctx) {
 async function handleBatchInline(req, res, batching, requestId) {
   try {
     const chunks = [];
-    await new Promise((resolve7, reject) => {
+    await new Promise((resolve10, reject) => {
       req.on("data", (c) => chunks.push(c));
       req.on("end", () => {
-        resolve7();
+        resolve10();
       });
       req.on("error", reject);
     });
@@ -829,542 +1120,483 @@ function createApiMiddleware(vite, serverDir, rateLimitConfigOrOptions) {
   };
 }
 
-// src/config/load-config.ts
-import { existsSync as existsSync2 } from "fs";
-import { resolve as resolve2 } from "path";
-import { pathToFileURL } from "url";
-
-// src/config/errors.ts
-var TheoConfigError = class extends Error {
-  issues;
-  configPath;
-  constructor(issues, configPath) {
-    const issueLines = issues.map((i) => `  - ${i.field}: ${i.message}`).join("\n");
-    super(
-      `Invalid theo.config.ts
-
-  File: ${configPath}
-
-` + (issueLines ? `  Issues:
-${issueLines}
-` : "")
-    );
-    this.name = "TheoConfigError";
-    this.issues = issues;
-    this.configPath = configPath;
-  }
-};
+// src/vite-plugin/ssr-dev-middleware.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve4 } from "path";
+function isSsrRenderResult(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("html" in value)) return false;
+  return typeof value.html === "string";
+}
+function setupSsrDevMiddleware(server, opts) {
+  server.middlewares.use((req, res, next) => {
+    void (async () => {
+      const url = req.url ?? "/";
+      if (url.startsWith("/api/") || url.startsWith("/@") || url.startsWith("/node_modules/") || url.includes(".")) {
+        next();
+        return;
+      }
+      try {
+        const indexPath = resolve4(opts.projectRoot, "index.html");
+        let template = readFileSync2(indexPath, "utf-8");
+        template = await server.transformIndexHtml(url, template);
+        const nonce = generateNonce();
+        applySecurityHeaders(
+          res,
+          opts.securityHeaders ?? {},
+          { production: process.env.NODE_ENV === "production" },
+          { nonce }
+        );
+        const mod = await server.ssrLoadModule(opts.virtualEntryServerId);
+        const result = await mod.render(url, { nonce });
+        if (result && typeof result === "object" && "redirect" in result) {
+          res.writeHead(302, {
+            Location: result.redirect.headers.get("location") ?? "/"
+          });
+          res.end();
+          return;
+        }
+        let ssrHtml;
+        let hydrationScript = "";
+        if (typeof result === "string") {
+          ssrHtml = result;
+        } else if (isSsrRenderResult(result)) {
+          ssrHtml = result.html;
+          const dataJson = JSON.stringify(result.hydrationData).replace(/</g, "\\u003c");
+          hydrationScript = `<script nonce="${nonce}">window.__staticRouterHydrationData=${dataJson}</script>`;
+        } else {
+          ssrHtml = "";
+        }
+        const rootDivMatch = /<div id=["']root["'][^>]*>/.exec(template);
+        if (!rootDivMatch) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(template);
+          return;
+        }
+        const splitIdx = template.indexOf(rootDivMatch[0]) + rootDivMatch[0].length;
+        const html = template.slice(0, splitIdx) + ssrHtml + hydrationScript + template.slice(splitIdx);
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(html);
+      } catch (err) {
+        server.ssrFixStacktrace(err);
+        console.error("[SSR Dev Error]", err);
+        next();
+        return;
+      }
+    })();
+  });
+}
 
-// src/config/schema.ts
-import { z } from "zod";
-var baseRateLimitSchema = z.object({
-  windowMs: z.number().min(1),
-  max: z.number().int().min(1)
-});
-var rateLimitSchema = z.union([
-  baseRateLimitSchema,
-  z.object({
-    default: baseRateLimitSchema.optional(),
-    routes: z.record(z.string(), baseRateLimitSchema).optional(),
-    keyBy: z.union([
-      z.enum(["ip", "session", "user"]),
-      z.function().args(z.unknown()).returns(z.string())
-    ]).optional(),
-    cookieName: z.string().min(1).optional()
-  })
-]);
-var uploadSchema = z.object({
-  maxFileSize: z.number().min(1).default(10 * 1024 * 1024),
-  // 10MB
-  maxFiles: z.number().int().min(1).default(10),
-  maxFieldSize: z.number().min(1).default(1 * 1024 * 1024)
-  // 1MB
-});
-var loggingSchema = z.object({
-  level: z.enum(["debug", "info", "warn", "error", "silent"]).default("info")
-});
-var routeRuleSchema = z.object({
-  maxAge: z.number().nonnegative().finite().optional(),
-  swr: z.number().nonnegative().finite().optional(),
-  tags: z.array(z.string()).optional()
-});
-var cacheSchema = z.object({
-  enabled: z.boolean().default(true),
-  /** 'memory' uses InMemoryCacheAdapter; otherwise pass a custom adapter instance. */
-  storage: z.union([z.literal("memory"), z.custom()]).default("memory"),
-  maxEntries: z.number().int().positive().default(1e3),
-  defaults: z.object({
-    maxAge: z.number().nonnegative().finite().default(1),
-    swr: z.number().nonnegative().finite().optional(),
-    cacheErrors: z.boolean().default(false)
-  }).default({}),
-  keyDerivation: z.object({
-    excludeQuery: z.array(z.string()).optional(),
-    sortQuery: z.boolean().default(true),
-    lowercaseHost: z.boolean().default(true)
-  }).default({}),
-  routeRules: z.record(z.string(), routeRuleSchema).optional()
-});
-var headerSafeString = z.string().refine((s) => !/[\r\n]/.test(s), { message: "Header value must not contain CR/LF" });
-var securityHeadersSchema = z.object({
-  csp: z.union([headerSafeString, z.literal(false)]).optional(),
-  // T6.1 — default flipped from 'report-only' to 'enforce' for 0.3.0.
-  // Users who want the old behaviour set `cspMode: 'report-only'`
-  // explicitly. See docs/migrating/0.2-to-0.3.md.
-  cspMode: z.enum(["enforce", "report-only", "off"]).default("enforce"),
-  hsts: z.union([headerSafeString, z.literal(false)]).optional(),
-  frameOptions: z.enum(["DENY", "SAMEORIGIN"]).default("DENY"),
-  contentTypeOptions: z.literal("nosniff").default("nosniff"),
-  referrerPolicy: headerSafeString.default("strict-origin-when-cross-origin"),
-  /**
-   * T1.1 — Permissions-Policy directive string. EC-3-refined: rejects CR/LF.
-   * Pass `false` to suppress the header.
-   */
-  permissionsPolicy: z.union([headerSafeString, z.literal(false)]).optional()
-});
-var disallowedConfigSchema = z.object({
-  routes: z.array(z.union([z.string(), z.instanceof(RegExp)])),
-  behavior: z.enum(["warn", "raise"]).default("raise")
-});
-var corsSchema = z.object({
-  origins: z.union([
-    z.literal("*"),
-    headerSafeString,
-    z.instanceof(RegExp),
-    z.array(z.union([headerSafeString, z.instanceof(RegExp)])),
-    z.function().args(z.string()).returns(z.boolean())
-  ]),
-  methods: z.array(z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"])).optional(),
-  allowedHeaders: z.array(headerSafeString).optional(),
-  exposedHeaders: z.array(headerSafeString).optional(),
-  credentials: z.boolean().default(false),
-  maxAge: z.number().int().min(0).max(86400).default(600)
-}).refine((c) => !(c.origins === "*" && c.credentials), {
-  message: 'CORS spec forbids origins:"*" with credentials:true \u2014 browsers ignore the wildcard'
-});
-var securitySchema = z.object({
-  // T6.1 — default flipped from 'warn' to 'strict' for 0.3.0. Apps that
-  // grep their warn-mode logs from 0.2.x already know which endpoints
-  // break; opt back into 'warn' globally OR use disallowedRoutes for
-  // surgical migration. See docs/migrating/0.2-to-0.3.md.
-  csrf: z.enum(["off", "warn", "strict"]).default("strict"),
-  headers: securityHeadersSchema.optional(),
-  /** T5.1 — per-route escalation (Rails disallowed_warnings pattern). */
-  disallowed: disallowedConfigSchema.optional(),
-  /** T1.2 — Cross-Origin Resource Sharing. Single global config; runs first in pipeline. */
-  cors: corsSchema.optional()
-});
-var tlsConfigSchema = z.object({
-  rejectUnauthorized: z.boolean().optional(),
-  caCert: z.string().optional(),
-  clientCert: z.string().optional(),
-  clientKey: z.string().optional()
-});
-var serverConfigSchema = z.object({
-  host: z.string().min(1),
-  port: z.number().int().positive().max(65535).optional(),
-  user: z.string().min(1),
-  /** Password may be the empty string (some providers permit it). */
-  password: z.string(),
-  tls: tlsConfigSchema.optional()
-});
-var postgresPoolConfigSchema = z.object({
-  min: z.number().int().nonnegative().optional(),
-  max: z.number().int().positive().optional(),
-  connectionTimeoutMillis: z.number().int().positive().optional(),
-  idleTimeoutMillis: z.number().int().nonnegative().optional()
-});
-var postgresDatabaseConfigSchema = z.object({
-  /** References a key in `storage.servers`. Resolved at `usePostgres()` call time. */
-  server: z.string().min(1),
-  database: z.string().min(1),
-  pool: postgresPoolConfigSchema.optional()
-});
-var redisServerConfigSchema = serverConfigSchema.extend({
-  db: z.number().int().nonnegative().optional(),
-  maxRetriesPerRequest: z.number().int().nonnegative().optional()
-});
-var storageSchema = z.object({
-  servers: z.record(z.string(), serverConfigSchema).optional(),
-  databases: z.record(z.string(), postgresDatabaseConfigSchema).optional(),
-  redis: z.record(z.string(), redisServerConfigSchema).optional()
-});
-var theoConfigSchema = z.object({
-  appDir: z.string().default("app"),
-  serverDir: z.string().default("server"),
-  /**
-   * T2.2 / EC-4 — Build output directory. Must be a relative path inside
-   * the project root. Refused absolute or parent-relative paths to prevent
-   * `cleanOutDir` from wiping arbitrary locations (defense-in-depth on
-   * top of cleanOutDir's runtime EC-3 guard).
-   */
-  distDir: z.string().default(".theo").refine(
-    (d) => !/^([A-Za-z]:)?[/\\]/.test(d) && !d.startsWith(".."),
-    'distDir must be a relative path inside the project root (e.g., ".theo")'
-  ),
-  /**
-   * Agent runtime configuration.
-   *
-   * - `maxRegistries` (T2.3, legacy): dev-mode cleanup of stale
-   *   `.theokit/agents/<id>/` dirs by mtime. Now superseded by SDK's
-   *   native registry GC but kept for backward-compat.
-   * - `registry` (Phase 6, Production-Readiness #2): forwarded to
-   *   `Agent.registry.configure()` lazily on first request.
-   *   * `maxAgents` — LRU cap. MUST be ≥ max-concurrent-active-conversations
-   *     (EC-17 DOCUMENT): with maxAgents:1 and 2 concurrent chats, LRU evicts
-   *     mid-stream → SDK aborts with code:'aborted'. Default 100 covers
-   *     indie/small-team; tune up for high-traffic.
-   *   * `idleTimeoutMs` — auto-evict idle agents (default 30 min). 0 disables
-   *     idle eviction (LRU only).
-   */
-  agents: z.object({
-    maxRegistries: z.number().int().positive().default(100),
-    registry: z.object({
-      /** LRU cap — MUST be ≥ max-concurrent-active-conversations. */
-      maxAgents: z.number().int().positive().max(1e4).default(100),
-      /** Idle eviction window in ms. 0 disables idle eviction (LRU only). */
-      idleTimeoutMs: z.number().int().nonnegative().default(30 * 6e4)
-    }).optional()
-  }).optional(),
-  port: z.number().int().min(1).max(65535).default(3e3),
-  ssr: z.boolean().default(false),
-  /** When true (and ssr === true), use renderToPipeableStream with progressive
-   * shell flush instead of single-shot renderToString. Opt-in for streaming
-   * SSR; default false preserves the current behavior. */
-  ssrStreaming: z.boolean().default(false),
-  rateLimit: rateLimitSchema.optional(),
-  upload: uploadSchema.optional(),
-  logging: loggingSchema.optional(),
-  security: securitySchema.optional(),
-  serialization: z.enum(["json", "superjson"]).default("json"),
-  // Plugins are validated structurally at runtime by createPluginRunnerFromConfig.
-  // Zod only checks the shape minimally (must be array). Type-level safety is
-  // provided through defineConfig at the user surface.
-  plugins: z.array(z.unknown()).optional(),
-  /** Enable client-side batching of theoFetch calls and the
-   * /api/__theo_batch__ server endpoint. */
-  batching: z.union([z.boolean(), z.object({ max: z.number().int().positive().optional() })]).optional(),
-  /** T4.1 — Audit log. When `logger` is provided, framework events
-   * (csrf.warn, rate-limit.exceeded, session.rotated, csp.violation) are
-   * emitted to it. Default: noop. */
-  audit: z.object({
-    logger: z.unknown().optional()
-  }).optional(),
-  /** TheoUI auto-wire (T2.1). `false` = opt-out; object = explicit theme/fonts;
-   * undefined = enabled when @theokit/ui is detected in node_modules. */
-  ui: z.union([
-    z.literal(false),
-    z.object({
-      theme: z.enum(["violet-forge", "noir", "paper"]).optional(),
-      fonts: z.enum(["bundled", "cdn"]).optional()
+// src/vite-plugin/ws-upgrade.ts
+import { resolve as resolve5 } from "path";
+function setupWsUpgrade(server, projectRoot) {
+  const wsRoutes = scanWebSocketRoutes(resolve5(projectRoot, "server"));
+  if (wsRoutes.length === 0) return;
+  const wsHttpServer = server.httpServer;
+  if (!wsHttpServer) return;
+  void import("ws").then(({ WebSocketServer }) => {
+    const wss = new WebSocketServer({ noServer: true });
+    wsHttpServer.on("upgrade", (request, socket, head) => {
+      void (async () => {
+        const url = request.url ?? "/";
+        if (!url.startsWith("/ws/")) return;
+        const wsPath = url.split("?")[0];
+        const match = wsRoutes.find((r) => r.wsPath === wsPath);
+        if (!match) {
+          socket.destroy();
+          return;
+        }
+        try {
+          const mod = await server.ssrLoadModule(match.filePath);
+          const handler = mod.default ?? mod;
+          wss.handleUpgrade(request, socket, head, (ws) => {
+            void handler.onOpen?.(ws, request);
+            ws.on("message", (data) => {
+              void handler.onMessage?.(ws, data.toString());
+            });
+            ws.on("close", (code, reason) => {
+              void handler.onClose?.(ws, code, reason);
+            });
+            ws.on("error", (err) => {
+              void handler.onError?.(ws, err);
+            });
+          });
+        } catch {
+          socket.destroy();
+        }
+      })();
+    });
+  }).catch(() => {
+    console.warn(
+      '[Theo] WebSocket routes found but "ws" package not installed. Run: npm install ws'
+    );
+  });
+}
+
+// src/vite-plugin/configure-server-hook.ts
+async function runConfigureServer(server, ctx) {
+  ctx.isDevMode.value = true;
+  globalThis.__theoViteHotServer = server;
+  server.ws.on("theo:devtools:request-manifest", () => {
+    try {
+      const tree = scanRoutes(ctx.appDir);
+      broadcastRouteManifest(tree);
+    } catch {
+    }
+  });
+  const serverDir = resolve6(ctx.projectRoot, "server");
+  server.middlewares.use(
+    createActionMiddleware(server, serverDir, {
+      pluginRunner: ctx.pluginRunner,
+      csrfMode: ctx.csrfMode,
+      disallowed: ctx.disallowed
     })
-  ]).optional(),
-  /**
-   * Cache subsystem (caching-and-revalidation-plan).
-   * Default `undefined` keeps caching disabled (backward compatible).
-   * Pass `cache: {}` to opt in with defaults.
-   */
-  cache: cacheSchema.optional(),
-  /**
-   * Devtools overlay (Phase 0.4.0+ — see docs/plans/devtools-plan.md).
-   *
-   * - `undefined` (default): devtools auto-injects in `pnpm dev`, NEVER in `vite build`.
-   * - `false`: devtools disabled entirely (Vite plugin skips injection even in dev).
-   * - `{ ... }`: devtools enabled with explicit defaults (position, theme).
-   *
-   * Tree-shaken to noop in prod via the dual-export pattern in
-   * `packages/theo/src/devtools/index.ts` (EC-17 positive prod check).
-   */
-  devtools: z.union([
-    z.literal(false),
-    z.object({
-      position: z.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional(),
-      theme: z.enum(["light", "dark", "system"]).optional()
+  );
+  const servicesProxyPrefixes = ctx.services && Object.keys(ctx.services).length > 0 ? Object.values(ctx.services).map((s) => s.proxy) : [];
+  const csrfReadinessStore = ctx.csrfReadinessStoreOverride ?? new CsrfReadinessStore();
+  server.middlewares.use(
+    createApiMiddleware(server, serverDir, {
+      rateLimitConfig: ctx.rateLimit,
+      pluginRunner: ctx.pluginRunner,
+      batching: ctx.resolvedBatching,
+      transformer: ctx.transformer,
+      csrfMode: ctx.csrfMode,
+      securityHeaders: ctx.securityHeaders,
+      disallowed: ctx.disallowed,
+      cors: ctx.cors,
+      auditLogger: ctx.auditLogger,
+      servicesProxyPrefixes,
+      csrfReadinessStore
     })
-  ]).optional(),
-  /**
-   * Informative list of deploy adapters the app supports. Does NOT
-   * trigger per-build translations — only the `--target` CLI flag does
-   * (EC-201 / ADR D2). If `config.adapters` includes a target NOT
-   * matching `--target`, `theokit build` emits a cross-reference note.
-   */
-  adapters: z.array(z.string()).optional(),
-  /**
-   * Extra package names to pre-bundle via Vite's `optimizeDeps.include`.
-   *
-   * Framework auto-includes `@theokit/ui` and `lucide-react` when present.
-   * Apps adding plugin peer-deps that rely on a runtime `import('<pkg>')`
-   * (dynamic specifier) — e.g. `@theokit/plugin-canvas` consumers
-   * installing `mermaid` for Mermaid SVG rendering — must declare those
-   * here so Vite can resolve the literal in dev mode without
-   * "Failed to resolve module specifier" errors. Production builds use
-   * tsup/esbuild bundling and are not affected.
-   *
-   * Example:
-   *   viteOptimizeDeps: ['mermaid']
-   */
-  viteOptimizeDeps: z.array(z.string()).optional(),
-  /**
-   * Jobs backend (ADR D3 + T2.1). When configured, every request gets
-   * `ctx.queue.enqueue` auto-wired via the outbox lifecycle. Pass a
-   * `JobBackend` instance (InMemoryJobBackend, PostgresJobBackend, etc.).
-   */
-  jobs: z.object({
-    backend: z.custom((v) => typeof v === "object" && v !== null)
-  }).optional(),
-  /**
-   * StorageManager configuration (T1.1 / ADR-0007).
-   *
-   * Declares Postgres servers + databases + Redis servers. Consumed by
-   * `getStorageManager().configure()` at boot via `start.ts`.
-   *
-   * Default `undefined` means manager exists but is not configured — adapters
-   * relying on the manager (PostgresJobBackend.fromStorageManager, etc.) will
-   * throw with an actionable error on first use.
-   */
-  storage: storageSchema.optional(),
-  /**
-   * Wave 2 — Polyglot services orchestration (T1.1 / ADR-0012/0013/0014/0015).
-   *
-   * Declarative external sidecar processes (Python FastAPI / Node Hono)
-   * that boot alongside the TheoKit TS app. Empty `services: {}` is the
-   * default and preserves Wave 1 behavior.
-   */
-  services: servicesConfigSchema,
-  /**
-   * G2 — OpenAPI emit (build-time only).
-   *
-   * When present, `theokit build` writes a generated `openapi.json` from
-   * every `defineRoute()` body/query/params Zod schema. `undefined` keeps
-   * the framework backward-compatible (no emit). Pass `openapi: {}` to
-   * opt in with defaults.
-   *
-   * Defaults: spec 3.1.0 · servers `http://localhost:3000` · title
-   * "TheoKit App" · version "0.0.0" · outDir ".theo" (next to dist).
-   *
-   * The env var `THEOKIT_OPENAPI_SERVERS` (CSV of URLs) overrides
-   * `servers[].url` at emit time without rebuilding the config.
-   */
-  openapi: z.object({
-    servers: z.array(
-      z.object({
-        url: z.string().url(),
-        description: z.string().optional()
-      })
-    ).default([{ url: "http://localhost:3000", description: "Local development" }]),
-    specVersion: z.enum(["3.1.0", "3.0.3"]).default("3.1.0"),
-    title: z.string().default("TheoKit App"),
-    version: z.string().default("0.0.0"),
-    outDir: z.string().default(".theo")
-  }).optional()
-}).refine((cfg) => !Object.values(cfg.services).some((s) => s.port === cfg.port), {
-  message: "service.port collides with TheoKit web port \u2014 change one of them",
-  path: ["services"]
-});
-
-// src/config/load-config.ts
-var CONFIG_FILE = "theo.config.ts";
-function deepMerge(base, override) {
-  const result = { ...base };
-  for (const key of Object.keys(override)) {
-    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
-    const baseVal = base[key];
-    const overVal = override[key];
-    if (overVal !== null && typeof overVal === "object" && !Array.isArray(overVal) && baseVal !== null && typeof baseVal === "object" && !Array.isArray(baseVal)) {
-      result[key] = deepMerge(
-        baseVal,
-        overVal
+  );
+  const configPath = resolve6(ctx.projectRoot, "theo.config.ts");
+  server.watcher.on("change", (file) => {
+    if (file === configPath) {
+      console.warn(
+        "\n[theokit] theo.config.ts changed; restart dev server for plugin changes to take effect\n"
       );
-    } else {
-      result[key] = overVal;
     }
+  });
+  if (ctx.ssrEnabled) {
+    setupSsrDevMiddleware(server, {
+      projectRoot: ctx.projectRoot,
+      virtualEntryServerId: ctx.virtualEntryServerId,
+      securityHeaders: ctx.securityHeaders
+    });
   }
-  return result;
-}
-async function loadConfig(dir) {
-  loadEnv({ cwd: dir });
-  const configPath = resolve2(dir, CONFIG_FILE);
-  if (!existsSync2(configPath)) {
-    return theoConfigSchema.parse({});
+  function handleRouteChange(filePath) {
+    if (!isRouteFile(basename(filePath))) return;
+    if (!filePath.startsWith(ctx.appDir)) return;
+    const mod = server.moduleGraph.getModuleById(ctx.resolvedManifestId);
+    if (mod) {
+      server.moduleGraph.invalidateModule(mod);
+      server.ws.send({ type: "full-reload" });
+    }
   }
-  let mod;
+  server.watcher.on("add", handleRouteChange);
+  server.watcher.on("unlink", handleRouteChange);
+  if (ctx.resolvedOpenApi !== void 0) {
+    const openApiCfg = ctx.resolvedOpenApi;
+    const { reEmitOpenApi } = await import("./dev-emit-5VPRCHOD.js");
+    const openApiServerDir = resolve6(ctx.projectRoot, "server");
+    const openApiDistDir = resolve6(ctx.projectRoot, ctx.resolvedDistDir);
+    const isRouteFileForOpenApi = (file) => file.startsWith(openApiServerDir) && /\.(ts|tsx|js|mjs)$/.test(file);
+    void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+    server.watcher.on("change", (file) => {
+      if (isRouteFileForOpenApi(file)) {
+        void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+      }
+    });
+    server.watcher.on("add", (file) => {
+      if (isRouteFileForOpenApi(file)) {
+        void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+      }
+    });
+    server.watcher.on("unlink", (file) => {
+      if (isRouteFileForOpenApi(file)) {
+        void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+      }
+    });
+  }
+  setupWsUpgrade(server, ctx.projectRoot);
+  server.httpServer?.once("close", () => {
+    ;
+    globalThis.__theoViteHotServer = void 0;
+  });
+}
+
+// src/vite-plugin/integrate-ui.ts
+import { existsSync as existsSync6, readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname3, join as join4 } from "path";
+import { pathToFileURL } from "url";
+
+// src/vite-plugin/auto-detect.ts
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+function isDeclared(name, projectRoot) {
   try {
-    mod = await import(pathToFileURL(configPath).href);
-  } catch (err) {
-    throw new TheoConfigError([{ field: "_file", message: err.message }], configPath);
+    const raw = readFileSync3(join3(projectRoot, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw);
+    return Boolean(
+      pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? pkg.peerDependencies?.[name]
+    );
+  } catch {
+    return false;
   }
-  const userConfig = mod.default;
-  if (userConfig == null || typeof userConfig !== "object") {
-    throw new TheoConfigError(
-      [
-        {
-          field: "_export",
-          message: "theo.config.ts must use export default defineConfig({...})"
+}
+function resolvePackageJson(name, cwd) {
+  let dir = cwd;
+  for (let depth = 0; depth < 10; depth++) {
+    const pkgJsonPath = join3(dir, "node_modules", ...name.split("/"), "package.json");
+    if (existsSync5(pkgJsonPath)) {
+      try {
+        const raw = readFileSync3(pkgJsonPath, "utf-8");
+        const pkg = JSON.parse(raw);
+        if (pkg.name === name) {
+          return { path: pkgJsonPath, version: pkg.version };
         }
-      ],
-      configPath
-    );
+      } catch {
+      }
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function fallbackProbe(name, cwd) {
+  const candidates = ["index.mjs", "dist/index.mjs", "dist/index.js", "index.js"];
+  let dir = cwd;
+  for (let depth = 0; depth < 10; depth++) {
+    const pkgDir = join3(dir, "node_modules", ...name.split("/"));
+    for (const candidate of candidates) {
+      const entry = join3(pkgDir, candidate);
+      if (existsSync5(entry)) return { resolvedEntry: entry };
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function findOwningPackageJson(entry, expectedName) {
+  let dir = dirname2(entry);
+  for (let i = 0; i < 10; i++) {
+    const candidate = join3(dir, "package.json");
+    if (existsSync5(candidate)) {
+      try {
+        const raw = readFileSync3(candidate, "utf-8");
+        const pkg = JSON.parse(raw);
+        if (pkg.name === expectedName) {
+          return { path: candidate, version: pkg.version };
+        }
+      } catch {
+      }
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function detectPackage(name, cwd) {
+  if (!isDeclared(name, cwd)) {
+    return { installed: false };
+  }
+  const pkgJson = resolvePackageJson(name, cwd);
+  if (pkgJson) {
+    return {
+      installed: true,
+      version: pkgJson.version,
+      resolvedPath: pkgJson.path
+    };
+  }
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    const nmPath = join3(dir, "node_modules", ...name.split("/"));
+    const nmPkgJson = join3(nmPath, "package.json");
+    if (existsSync5(nmPkgJson)) {
+      try {
+        const raw = readFileSync3(nmPkgJson, "utf-8");
+        const pkg = JSON.parse(raw);
+        if (pkg.name === name) {
+          return { installed: true, version: pkg.version, resolvedPath: nmPkgJson };
+        }
+      } catch {
+      }
+      return { installed: true };
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const probe = fallbackProbe(name, cwd);
+  if (probe) {
+    const owning = findOwningPackageJson(probe.resolvedEntry, name);
+    if (owning) {
+      return { installed: true, version: owning.version, resolvedPath: owning.path };
+    }
+    return { installed: true };
   }
-  let rawConfig = userConfig;
-  const nodeEnv = process.env.NODE_ENV;
-  if (nodeEnv) {
-    const envFile = `theo.config.${nodeEnv}.ts`;
-    const envPath = resolve2(dir, envFile);
-    if (existsSync2(envPath)) {
+  return { installed: false };
+}
+
+// src/vite-plugin/integrate-ui.ts
+function resolveConsumerImport(name, cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    const pkgDir = join4(dir, "node_modules", ...name.split("/"));
+    const pkgJsonPath = join4(pkgDir, "package.json");
+    if (existsSync6(pkgJsonPath)) {
       try {
-        const envMod = await import(pathToFileURL(envPath).href);
-        const envConfig = envMod.default;
-        if (envConfig != null && typeof envConfig === "object") {
-          rawConfig = deepMerge(rawConfig, envConfig);
+        const raw = readFileSync4(pkgJsonPath, "utf-8");
+        const pkg = JSON.parse(raw);
+        let entry;
+        const dotExport = pkg.exports?.["."];
+        if (typeof dotExport === "string") entry = dotExport;
+        else if (dotExport && typeof dotExport === "object") {
+          entry = dotExport.import ?? dotExport.default;
         }
-      } catch (err) {
-        throw new TheoConfigError([{ field: "_file", message: err.message }], envPath);
+        entry ??= pkg.module ?? pkg.main;
+        if (!entry) return null;
+        const cleaned = entry.replace(/^\.\//, "");
+        return pathToFileURL(join4(pkgDir, cleaned)).href;
+      } catch {
+        return null;
       }
     }
+    const parent = dirname3(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
-  const result = theoConfigSchema.safeParse(rawConfig);
-  if (!result.success) {
-    const issues = result.error.issues.map((i) => ({
-      field: i.path.join("."),
-      message: i.message
-    }));
-    throw new TheoConfigError(issues, configPath);
-  }
-  return result.data;
+  return null;
 }
-
-// src/vite-plugin/theoui-detect.ts
-import { existsSync as existsSync3, readFileSync } from "fs";
-import { dirname, join as join2 } from "path";
-function resolveTheoUiConfig(raw) {
-  return {
-    theme: raw?.theme ?? "violet-forge",
-    fonts: raw?.fonts ?? "bundled"
-  };
+function isValidPlugin(value) {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  if (!("name" in value)) return false;
+  return typeof value.name === "string";
 }
-function resolveExportSubpath(pkgRoot, subpath) {
-  const pkgJsonPath = join2(pkgRoot, "package.json");
-  if (!existsSync3(pkgJsonPath)) return null;
-  try {
-    const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
-    const exportKey = `./${subpath}`;
-    const exp = pkg.exports?.[exportKey];
-    if (!exp) {
-      const fallback = join2(pkgRoot, "dist", subpath);
-      return existsSync3(fallback) ? fallback : null;
-    }
-    let target;
-    if (typeof exp === "string") target = exp;
-    else if (typeof exp === "object") {
-      const e = exp;
-      target = e.import ?? e.default;
+function normalizePluginReturn(value) {
+  if (Array.isArray(value)) {
+    const result = [];
+    for (const entry of value) {
+      if (!isValidPlugin(entry)) return null;
+      result.push(entry);
     }
-    if (!target) return null;
-    const cleaned = target.replace(/^\.\//, "");
-    const candidate = join2(pkgRoot, cleaned);
-    return existsSync3(candidate) ? candidate : null;
-  } catch {
-    return null;
+    return result.length > 0 ? result : null;
   }
+  if (isValidPlugin(value)) return [value];
+  return null;
 }
-var defaultResolver = (specifier, projectRoot) => {
-  const parts = specifier.split("/");
-  const pkgName = parts[0]?.startsWith("@") && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
-  if (!pkgName) return false;
-  const subpath = specifier.slice(pkgName.length + 1);
-  if (!subpath) return false;
-  let dir = projectRoot;
-  for (let depth = 0; depth < 10; depth++) {
-    const pkgRoot = join2(dir, "node_modules", ...pkgName.split("/"));
-    if (existsSync3(pkgRoot)) {
-      const resolved = resolveExportSubpath(pkgRoot, subpath);
-      if (resolved) return true;
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
+async function integrateUseTheoUI(cwd, opts) {
+  if (opts?.enabled === false) return [];
+  const uiDetect = detectPackage("@theokit/ui", cwd);
+  if (!uiDetect.installed) return [];
+  if (opts?.consumerTailwindConfig || opts?.consumerPostcssConfig) {
+    console.info(
+      `[theokit] Detected your tailwind.config / postcss.config \u2014 skipping auto-config. Extend with \`import preset from '@theokit/ui/preset'\` to apply UI theme.`
+    );
+    return [];
   }
-  return false;
-};
-function isDeclaredInPackageJson(projectRoot) {
+  const tailwindDetect = detectPackage("@tailwindcss/vite", cwd);
+  if (!tailwindDetect.installed) {
+    console.warn(
+      `[theokit] @theokit/ui detected but @tailwindcss/vite is not installed. Run \`pnpm add -D @tailwindcss/vite\` to enable styling.`
+    );
+    return [];
+  }
+  const tailwindUrl = resolveConsumerImport("@tailwindcss/vite", cwd);
+  if (!tailwindUrl) {
+    console.warn(
+      `[theokit] @tailwindcss/vite installed but its package entry was not resolvable from ${cwd}. Skipping auto-config.`
+    );
+    return [];
+  }
+  let tailwindMod;
+  let uiMod;
   try {
-    const raw = readFileSync(join2(projectRoot, "package.json"), "utf-8");
-    const pkg = JSON.parse(raw);
-    return Boolean(
-      pkg.dependencies?.["@theokit/ui"] ?? pkg.devDependencies?.["@theokit/ui"] ?? pkg.peerDependencies?.["@theokit/ui"]
+    tailwindMod = await import(tailwindUrl);
+  } catch (err) {
+    console.warn(
+      `[theokit] @tailwindcss/vite dynamic import failed (${err.message}). Skipping auto-config.`
     );
-  } catch {
-    return false;
+    return [];
   }
-}
-function detectTheoUi(projectRoot, rawConfig, resolver = defaultResolver) {
-  const config = resolveTheoUiConfig(typeof rawConfig === "object" ? rawConfig : void 0);
-  if (rawConfig === false) {
-    return { enabled: false, config };
+  const uiPkgInstalled = detectPackage("@theokit/ui", cwd);
+  const uiPkgDir = uiPkgInstalled.resolvedPath ? uiPkgInstalled.resolvedPath.replace(/[\\/]package\.json$/, "") : null;
+  const uiPluginPath = uiPkgDir ? join4(uiPkgDir, "dist", "vite-plugin.js") : null;
+  if (!uiPluginPath || !existsSync6(uiPluginPath)) {
+    console.warn(
+      `[theokit] @theokit/ui/vite-plugin entry not found at ${String(uiPluginPath)}. Skipping auto-config.`
+    );
+    return [];
   }
-  if (!isDeclaredInPackageJson(projectRoot)) {
-    return { enabled: false, config };
+  try {
+    uiMod = await import(pathToFileURL(uiPluginPath).href);
+  } catch (err) {
+    console.warn(
+      `[theokit] @theokit/ui/vite-plugin dynamic import failed (${err.message}). Skipping auto-config.`
+    );
+    return [];
   }
-  const probes = ["@theokit/ui/styles.css", "@theokit/ui/fonts.css"];
-  for (const probe of probes) {
-    if (resolver(probe, projectRoot)) {
-      return { enabled: true, config };
-    }
+  if (typeof tailwindMod.default !== "function") {
+    console.warn(
+      `[theokit] @tailwindcss/vite does not expose a default-export function. Skipping auto-config.`
+    );
+    return [];
   }
-  return { enabled: false, config };
+  if (typeof uiMod.default !== "function") {
+    console.warn(
+      `[theokit] @theokit/ui/vite-plugin does not expose a default-export function. Skipping auto-config.`
+    );
+    return [];
+  }
+  let tailwindPlugin;
+  let uiPlugin;
+  try {
+    tailwindPlugin = tailwindMod.default();
+  } catch (err) {
+    console.warn(`[theokit] @tailwindcss/vite() threw: ${err.message}`);
+    return [];
+  }
+  try {
+    uiPlugin = uiMod.default({
+      tailwind: false
+    });
+  } catch (err) {
+    console.warn(`[theokit] @theokit/ui/vite-plugin() threw: ${err.message}`);
+    return [];
+  }
+  const tailwindPlugins = normalizePluginReturn(tailwindPlugin);
+  if (tailwindPlugins === null) {
+    console.warn(`[theokit] @tailwindcss/vite returned unexpected shape. Skipping auto-config.`);
+    return [];
+  }
+  const uiPlugins = normalizePluginReturn(uiPlugin);
+  if (uiPlugins === null) {
+    console.warn(
+      `[theokit] @theokit/ui/vite-plugin returned unexpected shape. Skipping auto-config.`
+    );
+    return [];
+  }
+  return [...tailwindPlugins, ...uiPlugins];
 }
 
-// src/vite-plugin/config-resolve.ts
-var DEFAULT_RESOLVED = {
-  pluginRunner: void 0,
-  transformer: void 0,
-  resolvedBatching: void 0,
-  theoUi: void 0,
-  csrfMode: "strict",
-  securityHeaders: void 0,
-  disallowed: void 0,
-  cors: void 0,
-  auditLogger: void 0,
-  devtoolsEnabled: true,
-  openapi: void 0,
-  distDir: ".theo"
-};
-async function resolvePluginConfig(projectRoot) {
-  try {
-    const userConfig = await loadConfig(projectRoot);
-    const pluginRunner = await createPluginRunnerFromConfig(userConfig.plugins);
-    const transformer = resolveTransformer(userConfig.serialization);
-    let resolvedBatching;
-    if (userConfig.batching === true) {
-      resolvedBatching = {};
-    } else if (typeof userConfig.batching === "object") {
-      resolvedBatching = userConfig.batching;
-    }
-    const theoUi = detectTheoUi(projectRoot, userConfig.ui);
-    let auditLogger;
-    const maybeLogger = userConfig.audit?.logger;
-    if (maybeLogger && typeof maybeLogger.log === "function") {
-      auditLogger = maybeLogger;
-    }
-    return {
-      pluginRunner,
-      transformer,
-      resolvedBatching,
-      theoUi,
-      csrfMode: userConfig.security?.csrf ?? "strict",
-      securityHeaders: userConfig.security?.headers,
-      disallowed: userConfig.security?.disallowed,
-      cors: userConfig.security?.cors,
-      auditLogger,
-      devtoolsEnabled: userConfig.devtools !== false,
-      openapi: userConfig.openapi,
-      distDir: userConfig.distDir
-    };
-  } catch {
-    return DEFAULT_RESOLVED;
+// src/vite-plugin/resolve-theo-root.ts
+import { existsSync as existsSync7 } from "fs";
+import { resolve as resolve7 } from "path";
+function resolveTheoRootDir(currentDir) {
+  if (existsSync7(resolve7(currentDir, "client"))) {
+    return currentDir;
   }
+  return resolve7(currentDir, "..");
 }
 
+// src/vite-plugin/transform-html-hook.ts
+import { existsSync as existsSync8 } from "fs";
+import { resolve as resolve8 } from "path";
+
 // src/vite-plugin/inject-devtools.ts
 var DEVTOOLS_VIRTUAL_ID = "/@theo/devtools/entry.js";
 var DEVTOOLS_RESOLVED_ID = "\0@theo/devtools/entry.js";
@@ -1450,385 +1682,461 @@ function injectStylesheets(html, opts) {
 ${html}`, injected: tagsToInject };
 }
 
-// src/vite-plugin/integrate-ui.ts
-import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
-import { dirname as dirname3, join as join4 } from "path";
-import { pathToFileURL as pathToFileURL2 } from "url";
+// src/vite-plugin/transform-html-hook.ts
+function runTransformIndexHtml(html, ctx) {
+  const entry = injectEntryClient(html);
+  if (entry.warning) console.warn(entry.warning);
+  let next = entry.html;
+  const devtools = injectDevtoolsScript(next, {
+    isDev: ctx.isDevMode.value,
+    enabled: ctx.devtoolsEnabled
+  });
+  if (devtools.warning) console.warn(devtools.warning);
+  next = devtools.html;
+  const styles = injectStylesheets(next, {
+    isDev: ctx.isDevMode.value,
+    hasPackage: (name) => existsSync8(resolve8(ctx.projectRoot, "node_modules", ...name.split("/")))
+  });
+  next = styles.html;
+  return next;
+}
 
-// src/vite-plugin/auto-detect.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
-function isDeclared(name, projectRoot) {
-  try {
-    const raw = readFileSync2(join3(projectRoot, "package.json"), "utf-8");
-    const pkg = JSON.parse(raw);
-    return Boolean(
-      pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? pkg.peerDependencies?.[name]
-    );
-  } catch {
-    return false;
+// src/router/entry-server.ts
+function generateEntryServer(options = {}) {
+  if (options.streaming) {
+    return generateStreamingEntry(options);
   }
+  return generateSingleShotEntry(options);
 }
-function resolvePackageJson(name, cwd) {
-  let dir = cwd;
-  for (let depth = 0; depth < 10; depth++) {
-    const pkgJsonPath = join3(dir, "node_modules", ...name.split("/"), "package.json");
-    if (existsSync4(pkgJsonPath)) {
-      try {
-        const raw = readFileSync2(pkgJsonPath, "utf-8");
-        const pkg = JSON.parse(raw);
-        if (pkg.name === name) {
-          return { path: pkgJsonPath, version: pkg.version };
-        }
-      } catch {
-      }
-    }
-    const parent = dirname2(dir);
-    if (parent === dir) break;
-    dir = parent;
+function buildAppTreeJs(options) {
+  const theme = options.theoUi?.theme ?? "violet-forge";
+  if (options.theoUi) {
+    return [
+      `React.createElement(TheoUIProvider, { theme: { defaultTheme: '${theme}' } },`,
+      `      React.createElement(Suspense, { fallback: null },`,
+      `        React.createElement(StaticRouterProvider, { router, context, hydrate: false })`,
+      `      )`,
+      `    )`
+    ].join("\n");
   }
-  return null;
+  return `React.createElement(Suspense, { fallback: null },
+      React.createElement(StaticRouterProvider, { router, context, hydrate: false })
+    )`;
 }
-function fallbackProbe(name, cwd) {
-  const candidates = ["index.mjs", "dist/index.mjs", "dist/index.js", "index.js"];
-  let dir = cwd;
-  for (let depth = 0; depth < 10; depth++) {
-    const pkgDir = join3(dir, "node_modules", ...name.split("/"));
-    for (const candidate of candidates) {
-      const entry = join3(pkgDir, candidate);
-      if (existsSync4(entry)) return { resolvedEntry: entry };
-    }
-    const parent = dirname2(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
+function hydrationDataExtractSnippet() {
+  return [
+    `    const hydrationData = {`,
+    `      loaderData: context.loaderData,`,
+    `      actionData: context.actionData,`,
+    `      errors: context.errors,`,
+    `    }`
+  ].join("\n");
 }
-function findOwningPackageJson(entry, expectedName) {
-  let dir = dirname2(entry);
-  for (let i = 0; i < 10; i++) {
-    const candidate = join3(dir, "package.json");
-    if (existsSync4(candidate)) {
-      try {
-        const raw = readFileSync2(candidate, "utf-8");
-        const pkg = JSON.parse(raw);
-        if (pkg.name === expectedName) {
-          return { path: candidate, version: pkg.version };
-        }
-      } catch {
-      }
-    }
-    const parent = dirname2(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
+function generateSingleShotEntry(options) {
+  const theoUiImport = options.theoUi ? `import { TheoUIProvider } from '@theokit/ui'
+` : "";
+  const appTree = buildAppTreeJs(options);
+  return [
+    `import React, { Suspense } from 'react'`,
+    `import { renderToPipeableStream } from 'react-dom/server'`,
+    `import { createStaticHandler, createStaticRouter, StaticRouterProvider } from 'react-router'`,
+    `import { PassThrough } from 'node:stream'`,
+    `import { routes } from '/@theo/route-manifest'`,
+    theoUiImport,
+    `export async function render(url, options = {}) {`,
+    `  const handler = createStaticHandler(routes)`,
+    `  const request = new Request('http://localhost' + url)`,
+    `  const context = await handler.query(request)`,
+    ``,
+    `  if (context instanceof Response) {`,
+    `    return { redirect: context }`,
+    `  }`,
+    ``,
+    `  const router = createStaticRouter(handler.dataRoutes, context)`,
+    `  const app = ${appTree}`,
+    ``,
+    hydrationDataExtractSnippet(),
+    ``,
+    `  return new Promise((resolve, reject) => {`,
+    `    let html = ''`,
+    `    let piped = false`,
+    `    const passthrough = new PassThrough()`,
+    `    passthrough.on('data', (chunk) => { html += chunk.toString() })`,
+    `    passthrough.on('end', () => { resolve({ html, hydrationData }) })`,
+    `    passthrough.on('error', reject)`,
+    ``,
+    `    // Pipe on onShellReady (Next.js pattern). Calling pipe() twice`,
+    `    // throws "React currently only supports piping to one writable`,
+    `    // stream". The \`piped\` flag is a belt-and-suspenders guard if`,
+    `    // onShellReady fires unexpectedly more than once.`,
+    `    // Forward options.nonce to React so every <script> tag React`,
+    `    // emits (Suspense boundary scripts) carries the nonce attribute.`,
+    `    const { pipe } = renderToPipeableStream(app, {`,
+    `      nonce: options.nonce,`,
+    `      onShellReady() { if (!piped) { piped = true; pipe(passthrough) } },`,
+    `      onShellError(err) { reject(err) },`,
+    `      onError(err) { console.error('[SSR Error]', err) },`,
+    `    })`,
+    `  })`,
+    `}`
+  ].join("\n");
+}
+function streamingWebRenderer(appTree) {
+  return [
+    `// T2.3 \u2014 Web Standards streaming entry for edge runtimes (Cloudflare,`,
+    `// Bun, Deno, Vercel Edge). Uses renderToReadableStream and returns a`,
+    `// Response with the stream as body. Honors request.signal for client`,
+    `// disconnect cleanup.`,
+    `export async function renderStreamingWeb(request, options = {}) {`,
+    `  const handler = createStaticHandler(routes)`,
+    `  const url = new URL(request.url)`,
+    `  const context = await handler.query(request)`,
+    ``,
+    `  if (context instanceof Response) {`,
+    `    return context`,
+    `  }`,
+    ``,
+    `  const router = createStaticRouter(handler.dataRoutes, context)`,
+    `  const app = ${appTree}`,
+    ``,
+    `  const stream = await renderToReadableStream(app, {`,
+    `    signal: request.signal,`,
+    `    nonce: options.nonce,`,
+    `    onError(err) { console.error('[SSR Web Stream Error]', err) },`,
+    `  })`,
+    `  return new Response(stream, {`,
+    `    status: 200,`,
+    `    headers: {`,
+    `      'Content-Type': 'text/html; charset=utf-8',`,
+    `      'Transfer-Encoding': 'chunked',`,
+    `    },`,
+    `  })`,
+    `}`
+  ];
+}
+function streamingNodeRenderer(appTree) {
+  return [
+    `// T6.1 \u2014 Node streaming SSR entry (opt-in via theo.config.ts > ssrStreaming: true)`,
+    `// Flushes the shell as soon as it's ready, then streams Suspense boundaries.`,
+    `// EC-11: respects request.signal for client-disconnect cleanup.`,
+    `export async function renderStreaming(url, response, options = {}) {`,
+    `  const handler = createStaticHandler(routes)`,
+    `  const request = new Request('http://localhost' + url, { signal: options.signal })`,
+    `  const context = await handler.query(request)`,
+    ``,
+    `  if (context instanceof Response) {`,
+    `    return { redirect: context }`,
+    `  }`,
+    ``,
+    `  const router = createStaticRouter(handler.dataRoutes, context)`,
+    `  const app = ${appTree}`,
+    ``,
+    `  return new Promise((resolve, reject) => {`,
+    `    let didError = false`,
+    `    const stream = renderToPipeableStream(app, {`,
+    `      nonce: options.nonce,`,
+    `      onShellReady() {`,
+    `        response.statusCode = didError ? 500 : 200`,
+    `        response.setHeader('Content-Type', 'text/html; charset=utf-8')`,
+    `        response.setHeader('Transfer-Encoding', 'chunked')`,
+    `        stream.pipe(response)`,
+    `        resolve({ streaming: true })`,
+    `      },`,
+    `      onShellError(err) { reject(err) },`,
+    `      onError(err) {`,
+    `        didError = true`,
+    `        console.error('[SSR Stream Error]', err)`,
+    `      },`,
+    `    })`,
+    ``,
+    `    // EC-11: client disconnect cleanup`,
+    `    if (options.signal) {`,
+    `      options.signal.addEventListener('abort', () => { stream.abort() })`,
+    `    }`,
+    `  })`,
+    `}`
+  ];
+}
+function backCompatRenderer(appTree) {
+  return [
+    `// Backward compatibility: keep the single-shot render export available so`,
+    `// callers that always used 'render()' don't break when streaming is on.`,
+    `export async function render(url, options = {}) {`,
+    `  const handler = createStaticHandler(routes)`,
+    `  const request = new Request('http://localhost' + url)`,
+    `  const context = await handler.query(request)`,
+    ``,
+    `  if (context instanceof Response) {`,
+    `    return { redirect: context }`,
+    `  }`,
+    ``,
+    `  const router = createStaticRouter(handler.dataRoutes, context)`,
+    `  const app = ${appTree}`,
+    ``,
+    hydrationDataExtractSnippet(),
+    ``,
+    `  const { PassThrough } = await import('node:stream')`,
+    `  return new Promise((resolve, reject) => {`,
+    `    let html = ''`,
+    `    let piped = false`,
+    `    const passthrough = new PassThrough()`,
+    `    passthrough.on('data', (chunk) => { html += chunk.toString() })`,
+    `    passthrough.on('end', () => { resolve({ html, hydrationData }) })`,
+    `    passthrough.on('error', reject)`,
+    ``,
+    `    // Pipe on onShellReady (Next.js pattern). nonce forwarded.`,
+    `    const { pipe } = renderToPipeableStream(app, {`,
+    `      nonce: options.nonce,`,
+    `      onShellReady() { if (!piped) { piped = true; pipe(passthrough) } },`,
+    `      onShellError(err) { reject(err) },`,
+    `      onError(err) { console.error('[SSR Error]', err) },`,
+    `    })`,
+    `  })`,
+    `}`
+  ];
+}
+function generateStreamingEntry(options) {
+  const theoUiImport = options.theoUi ? `import { TheoUIProvider } from '@theokit/ui'
+` : "";
+  const appTree = buildAppTreeJs(options);
+  return [
+    `import React, { Suspense } from 'react'`,
+    `import { renderToPipeableStream, renderToReadableStream } from 'react-dom/server'`,
+    `import { createStaticHandler, createStaticRouter, StaticRouterProvider } from 'react-router'`,
+    `import { routes } from '/@theo/route-manifest'`,
+    theoUiImport,
+    ``,
+    ...streamingWebRenderer(appTree),
+    ``,
+    ...streamingNodeRenderer(appTree),
+    ``,
+    ...backCompatRenderer(appTree)
+  ].join("\n");
 }
-function detectPackage(name, cwd) {
-  if (!isDeclared(name, cwd)) {
-    return { installed: false };
-  }
-  const pkgJson = resolvePackageJson(name, cwd);
-  if (pkgJson) {
-    return {
-      installed: true,
-      version: pkgJson.version,
-      resolvedPath: pkgJson.path
-    };
-  }
-  let dir = cwd;
-  for (let i = 0; i < 10; i++) {
-    const nmPath = join3(dir, "node_modules", ...name.split("/"));
-    const nmPkgJson = join3(nmPath, "package.json");
-    if (existsSync4(nmPkgJson)) {
-      try {
-        const raw = readFileSync2(nmPkgJson, "utf-8");
-        const pkg = JSON.parse(raw);
-        if (pkg.name === name) {
-          return { installed: true, version: pkg.version, resolvedPath: nmPkgJson };
-        }
-      } catch {
-      }
-      return { installed: true };
-    }
-    const parent = dirname2(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  const probe = fallbackProbe(name, cwd);
-  if (probe) {
-    const owning = findOwningPackageJson(probe.resolvedEntry, name);
-    if (owning) {
-      return { installed: true, version: owning.version, resolvedPath: owning.path };
-    }
-    return { installed: true };
+
+// src/router/entry.ts
+function generateEntryClient(ssr, opts = {}) {
+  const rootMethod = ssr ? "hydrateRoot" : "createRoot";
+  const theoUiImports = [];
+  if (opts.theoUi) {
+    theoUiImports.push(
+      `// T2.2 \u2014 TheoUI CSS auto-injected (config.ui)`,
+      `import '@theokit/ui/styles.css'`
+    );
+    const fontsModule = opts.theoUi.fonts === "cdn" ? "fonts-cdn.css" : "fonts.css";
+    theoUiImports.push(
+      `import '@theokit/ui/${fontsModule}'`,
+      `// T2.3 \u2014 TheoUIProvider auto-wraps RouterProvider`,
+      `import { TheoUIProvider } from '@theokit/ui'`
+    );
   }
-  return { installed: false };
+  const theme = opts.theoUi?.theme ?? "violet-forge";
+  const routerTree = opts.theoUi ? `React.createElement(TheoUIProvider, { theme: { defaultTheme: '${theme}' } },
+      React.createElement(Suspense, { fallback: null },
+        React.createElement(RouterProvider, { router })
+      )
+    )` : `React.createElement(Suspense, { fallback: null },
+      React.createElement(RouterProvider, { router })
+    )`;
+  const renderCall = ssr ? `  ${rootMethod}(el,
+    ${routerTree}
+  )` : `  ${rootMethod}(el).render(
+    ${routerTree}
+  )`;
+  const hydrationLine = ssr ? `const router = createBrowserRouter(routes, { hydrationData: window.__staticRouterHydrationData })` : `const router = createBrowserRouter(routes)`;
+  const preloadBlock = ssr ? [
+    `// Phase 4 \u2014 preload matched-route modules before hydrate (EC-3 safeguard)`,
+    `const __theoMatches = matchRoutes(routes, window.location.pathname) ?? []`,
+    `const __theoPreloadPaths = __theoMatches`,
+    `  .map((m) => m.route && (m.route).path)`,
+    `  .filter((p) => typeof p === 'string' && p in __theoPreloadMap)`,
+    `const __theoPreloadPromise = Promise.all(`,
+    `  __theoPreloadPaths.map((p) => __theoPreloadMap[p]().catch((err) => { console.error('[theo] preload failed', p, err); return null }))`,
+    `)`,
+    `const __theoTimeout = new Promise((resolve) => setTimeout(() => resolve('timeout'), 1500))`,
+    `await Promise.race([__theoPreloadPromise, __theoTimeout])`,
+    ""
+  ] : [];
+  const renderBlock = ssr ? [
+    `if (el) {`,
+    `  ;(async () => {`,
+    ...preloadBlock.map((l) => "    " + l),
+    renderCall,
+    `  })()`,
+    `}`
+  ] : [`if (el) {`, renderCall, `}`];
+  const manifestImports = ssr ? `import { routes, __theoPreloadMap } from '/@theo/route-manifest'` : `import { routes } from '/@theo/route-manifest'`;
+  const reactRouterImports = ssr ? `import { createBrowserRouter, RouterProvider, matchRoutes } from 'react-router'` : `import { createBrowserRouter, RouterProvider } from 'react-router'`;
+  return [
+    `import React, { Suspense } from 'react'`,
+    `import { ${rootMethod} } from 'react-dom/client'`,
+    reactRouterImports,
+    manifestImports,
+    `// T1.3 \u2014 side-effect import sets globalThis.__THEO_TRANSFORMER__ for theoFetch`,
+    `import '/@theo/runtime-config'`,
+    ...theoUiImports,
+    ``,
+    hydrationLine,
+    `const el = document.getElementById('root')`,
+    ...renderBlock
+  ].join("\n");
 }
 
-// src/vite-plugin/integrate-ui.ts
-function resolveConsumerImport(name, cwd) {
-  let dir = cwd;
-  for (let i = 0; i < 10; i++) {
-    const pkgDir = join4(dir, "node_modules", ...name.split("/"));
-    const pkgJsonPath = join4(pkgDir, "package.json");
-    if (existsSync5(pkgJsonPath)) {
-      try {
-        const raw = readFileSync3(pkgJsonPath, "utf-8");
-        const pkg = JSON.parse(raw);
-        let entry;
-        const dotExport = pkg.exports?.["."];
-        if (typeof dotExport === "string") entry = dotExport;
-        else if (dotExport && typeof dotExport === "object") {
-          entry = dotExport.import ?? dotExport.default;
-        }
-        entry ??= pkg.module ?? pkg.main;
-        if (!entry) return null;
-        const cleaned = entry.replace(/^\.\//, "");
-        return pathToFileURL2(join4(pkgDir, cleaned)).href;
-      } catch {
-        return null;
-      }
-    }
-    const parent = dirname3(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
+// src/router/generate.ts
+function normalizePath(p) {
+  return p.replace(/\\/g, "/");
 }
-function isValidPlugin(value) {
-  if (value === null || typeof value !== "object") return false;
-  if (Array.isArray(value)) return false;
-  if (!("name" in value)) return false;
-  return typeof value.name === "string";
+function safeVarName(segment, prefix) {
+  const safe = segment.replace(/[^a-zA-Z0-9]/g, "_") || "root";
+  return `${prefix}_${safe}`;
 }
-function normalizePluginReturn(value) {
-  if (Array.isArray(value)) {
-    const result = [];
-    for (const entry of value) {
-      if (!isValidPlugin(entry)) return null;
-      result.push(entry);
-    }
-    return result.length > 0 ? result : null;
-  }
-  if (isValidPlugin(value)) return [value];
-  return null;
+function buildRoutePath(parents, segment) {
+  const joined = [...parents, segment].filter(Boolean).join("/");
+  return "/" + joined;
 }
-async function integrateUseTheoUI(cwd, opts) {
-  if (opts?.enabled === false) return [];
-  const uiDetect = detectPackage("@theokit/ui", cwd);
-  if (!uiDetect.installed) return [];
-  if (opts?.consumerTailwindConfig || opts?.consumerPostcssConfig) {
-    console.info(
-      `[theokit] Detected your tailwind.config / postcss.config \u2014 skipping auto-config. Extend with \`import preset from '@theokit/ui/preset'\` to apply UI theme.`
-    );
-    return [];
-  }
-  const tailwindDetect = detectPackage("@tailwindcss/vite", cwd);
-  if (!tailwindDetect.installed) {
-    console.warn(
-      `[theokit] @theokit/ui detected but @tailwindcss/vite is not installed. Run \`pnpm add -D @tailwindcss/vite\` to enable styling.`
-    );
-    return [];
-  }
-  const tailwindUrl = resolveConsumerImport("@tailwindcss/vite", cwd);
-  if (!tailwindUrl) {
-    console.warn(
-      `[theokit] @tailwindcss/vite installed but its package entry was not resolvable from ${cwd}. Skipping auto-config.`
-    );
-    return [];
-  }
-  let tailwindMod;
-  let uiMod;
-  try {
-    tailwindMod = await import(tailwindUrl);
-  } catch (err) {
-    console.warn(
-      `[theokit] @tailwindcss/vite dynamic import failed (${err.message}). Skipping auto-config.`
-    );
-    return [];
-  }
-  const uiPkgInstalled = detectPackage("@theokit/ui", cwd);
-  const uiPkgDir = uiPkgInstalled.resolvedPath ? uiPkgInstalled.resolvedPath.replace(/[\\/]package\.json$/, "") : null;
-  const uiPluginPath = uiPkgDir ? join4(uiPkgDir, "dist", "vite-plugin.js") : null;
-  if (!uiPluginPath || !existsSync5(uiPluginPath)) {
-    console.warn(
-      `[theokit] @theokit/ui/vite-plugin entry not found at ${String(uiPluginPath)}. Skipping auto-config.`
-    );
-    return [];
-  }
-  try {
-    uiMod = await import(pathToFileURL2(uiPluginPath).href);
-  } catch (err) {
-    console.warn(
-      `[theokit] @theokit/ui/vite-plugin dynamic import failed (${err.message}). Skipping auto-config.`
-    );
-    return [];
-  }
-  if (typeof tailwindMod.default !== "function") {
-    console.warn(
-      `[theokit] @tailwindcss/vite does not expose a default-export function. Skipping auto-config.`
-    );
-    return [];
+function pushIf(staticImports, filePath, varName) {
+  if (filePath !== void 0) {
+    staticImports.push({ varName, importPath: normalizePath(filePath) });
   }
-  if (typeof uiMod.default !== "function") {
-    console.warn(
-      `[theokit] @theokit/ui/vite-plugin does not expose a default-export function. Skipping auto-config.`
-    );
-    return [];
+}
+function walkRouteTree(node, parents, acc) {
+  const seg = node.segment || "root";
+  const routePath = buildRoutePath(parents, node.segment);
+  if (node.page !== void 0) {
+    acc.lazyPages.push({
+      varName: safeVarName(seg, "Page"),
+      importPath: normalizePath(node.page),
+      routePath
+    });
   }
-  let tailwindPlugin;
-  let uiPlugin;
-  try {
-    tailwindPlugin = tailwindMod.default();
-  } catch (err) {
-    console.warn(`[theokit] @tailwindcss/vite() threw: ${err.message}`);
-    return [];
+  if (node.layout !== void 0) acc.layoutState.found = true;
+  pushIf(acc.staticImports, node.layout, safeVarName(seg, "Layout"));
+  pushIf(acc.staticImports, node.error, safeVarName(seg, "Error"));
+  pushIf(acc.staticImports, node.loading, safeVarName(seg, "Loading"));
+  pushIf(acc.staticImports, node.notFound, safeVarName(seg, "NotFound"));
+  for (const child of node.children) {
+    const nextParents = node.segment ? [...parents, node.segment] : parents;
+    walkRouteTree(child, nextParents, acc);
   }
-  try {
-    uiPlugin = uiMod.default({
-      tailwind: false
-    });
-  } catch (err) {
-    console.warn(`[theokit] @theokit/ui/vite-plugin() threw: ${err.message}`);
-    return [];
+}
+function generateRouteManifest(tree) {
+  const acc = {
+    staticImports: [],
+    lazyPages: [],
+    layoutState: { found: false }
+  };
+  walkRouteTree(tree, [], acc);
+  const staticImports = acc.staticImports;
+  const lazyPages = acc.lazyPages;
+  const layoutState = acc.layoutState;
+  const lines = [`import React, { Suspense } from 'react'`];
+  if (layoutState.found) {
+    lines.push(`import { Outlet } from 'react-router'`);
   }
-  const tailwindPlugins = normalizePluginReturn(tailwindPlugin);
-  if (tailwindPlugins === null) {
-    console.warn(`[theokit] @tailwindcss/vite returned unexpected shape. Skipping auto-config.`);
-    return [];
+  lines.push("");
+  for (const imp of staticImports) {
+    lines.push(`import ${imp.varName} from '${imp.importPath}'`);
   }
-  const uiPlugins = normalizePluginReturn(uiPlugin);
-  if (uiPlugins === null) {
-    console.warn(
-      `[theokit] @theokit/ui/vite-plugin returned unexpected shape. Skipping auto-config.`
-    );
-    return [];
+  for (const lp of lazyPages) {
+    lines.push(`const ${lp.varName} = React.lazy(() => import('${lp.importPath}'))`);
   }
-  return [...tailwindPlugins, ...uiPlugins];
-}
-
-// src/vite-plugin/resolve-theo-root.ts
-import { existsSync as existsSync6 } from "fs";
-import { resolve as resolve3 } from "path";
-function resolveTheoRootDir(currentDir) {
-  if (existsSync6(resolve3(currentDir, "client"))) {
-    return currentDir;
+  lines.push("");
+  const preloadEntries = lazyPages.map(
+    (lp) => `  '${lp.routePath}': () => import('${lp.importPath}'),`
+  );
+  lines.push("export const __theoPreloadMap = {");
+  for (const e of preloadEntries) lines.push(e);
+  lines.push("}", "");
+  function buildChildrenArray(node, seg) {
+    const childConfigs = [];
+    if (node.page) {
+      const pageVar = safeVarName(seg, "Page");
+      const fallbackEl = node.loading ? `React.createElement(${safeVarName(seg, "Loading")})` : "null";
+      const pageElement = `React.createElement(Suspense, { fallback: ${fallbackEl} }, React.createElement(${pageVar}))`;
+      childConfigs.push(`{ index: true, element: ${pageElement} }`);
+    }
+    for (const child of node.children) {
+      childConfigs.push(genRouteConfig(child, false));
+    }
+    if (node.notFound) {
+      const nfVar = safeVarName(seg, "NotFound");
+      childConfigs.push(`{ path: '*', element: React.createElement(${nfVar}) }`);
+    }
+    let arr = `[${childConfigs.join(", ")}]`;
+    if (node.error) {
+      const errVar = safeVarName(seg, "Error");
+      arr = `[{ errorElement: React.createElement(${errVar}), children: ${arr} }]`;
+    }
+    return arr;
   }
-  return resolve3(currentDir, "..");
-}
-
-// src/vite-plugin/ssr-dev-middleware.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { resolve as resolve4 } from "path";
-function isSsrRenderResult(value) {
-  if (typeof value !== "object" || value === null) return false;
-  if (!("html" in value)) return false;
-  return typeof value.html === "string";
-}
-function setupSsrDevMiddleware(server, opts) {
-  server.middlewares.use((req, res, next) => {
-    void (async () => {
-      const url = req.url ?? "/";
-      if (url.startsWith("/api/") || url.startsWith("/@") || url.startsWith("/node_modules/") || url.includes(".")) {
-        next();
-        return;
-      }
-      try {
-        const indexPath = resolve4(opts.projectRoot, "index.html");
-        let template = readFileSync4(indexPath, "utf-8");
-        template = await server.transformIndexHtml(url, template);
-        const nonce = generateNonce();
-        applySecurityHeaders(
-          res,
-          opts.securityHeaders ?? {},
-          { production: process.env.NODE_ENV === "production" },
-          { nonce }
-        );
-        const mod = await server.ssrLoadModule(opts.virtualEntryServerId);
-        const result = await mod.render(url, { nonce });
-        if (result && typeof result === "object" && "redirect" in result) {
-          res.writeHead(302, {
-            Location: result.redirect.headers.get("location") ?? "/"
-          });
-          res.end();
-          return;
-        }
-        let ssrHtml;
-        let hydrationScript = "";
-        if (typeof result === "string") {
-          ssrHtml = result;
-        } else if (isSsrRenderResult(result)) {
-          ssrHtml = result.html;
-          const dataJson = JSON.stringify(result.hydrationData).replace(/</g, "\\u003c");
-          hydrationScript = `<script nonce="${nonce}">window.__staticRouterHydrationData=${dataJson}</script>`;
-        } else {
-          ssrHtml = "";
-        }
-        const rootDivMatch = /<div id=["']root["'][^>]*>/.exec(template);
-        if (!rootDivMatch) {
-          res.writeHead(200, { "Content-Type": "text/html" });
-          res.end(template);
-          return;
-        }
-        const splitIdx = template.indexOf(rootDivMatch[0]) + rootDivMatch[0].length;
-        const html = template.slice(0, splitIdx) + ssrHtml + hydrationScript + template.slice(splitIdx);
-        res.writeHead(200, { "Content-Type": "text/html" });
-        res.end(html);
-      } catch (err) {
-        server.ssrFixStacktrace(err);
-        console.error("[SSR Dev Error]", err);
-        next();
-        return;
+  function genRouteConfig(node, isRoot) {
+    const seg = node.segment || "root";
+    const childrenArray = buildChildrenArray(node, seg);
+    if (node.layout) {
+      const layoutVar = safeVarName(seg, "Layout");
+      const pathPart = isRoot ? `path: '/'` : `path: '${node.segment}'`;
+      return `{ ${pathPart}, element: React.createElement(${layoutVar}, { children: React.createElement(Outlet) }), children: ${childrenArray} }`;
+    }
+    if (isRoot) {
+      if (node.children.length === 0 && !node.page && !node.notFound && !node.error) {
+        return `{ path: '/', children: [] }`;
       }
-    })();
-  });
+      return `{ path: '/', children: ${childrenArray} }`;
+    }
+    if (node.page && node.children.length === 0 && !node.error && !node.notFound) {
+      const pageVar = safeVarName(seg, "Page");
+      const fallbackEl = node.loading ? `React.createElement(${safeVarName(seg, "Loading")})` : "null";
+      const pageElement = `React.createElement(Suspense, { fallback: ${fallbackEl} }, React.createElement(${pageVar}))`;
+      return `{ path: '${node.segment}', element: ${pageElement} }`;
+    }
+    return `{ path: '${node.segment}', children: ${childrenArray} }`;
+  }
+  const routeConfig = genRouteConfig(tree, true);
+  lines.push(`export const routes = [${routeConfig}]`);
+  return lines.join("\n");
 }
 
-// src/vite-plugin/ws-upgrade.ts
-import { resolve as resolve5 } from "path";
-function setupWsUpgrade(server, projectRoot) {
-  const wsRoutes = scanWebSocketRoutes(resolve5(projectRoot, "server"));
-  if (wsRoutes.length === 0) return;
-  const wsHttpServer = server.httpServer;
-  if (!wsHttpServer) return;
-  void import("ws").then(({ WebSocketServer }) => {
-    const wss = new WebSocketServer({ noServer: true });
-    wsHttpServer.on("upgrade", (request, socket, head) => {
-      void (async () => {
-        const url = request.url ?? "/";
-        if (!url.startsWith("/ws/")) return;
-        const wsPath = url.split("?")[0];
-        const match = wsRoutes.find((r) => r.wsPath === wsPath);
-        if (!match) {
-          socket.destroy();
-          return;
-        }
-        try {
-          const mod = await server.ssrLoadModule(match.filePath);
-          const handler = mod.default ?? mod;
-          wss.handleUpgrade(request, socket, head, (ws) => {
-            void handler.onOpen?.(ws, request);
-            ws.on("message", (data) => {
-              void handler.onMessage?.(ws, data.toString());
-            });
-            ws.on("close", (code, reason) => {
-              void handler.onClose?.(ws, code, reason);
-            });
-            ws.on("error", (err) => {
-              void handler.onError?.(ws, err);
-            });
-          });
-        } catch {
-          socket.destroy();
-        }
-      })();
+// src/vite-plugin/virtual-modules-hook.ts
+function resolveVirtualModuleId(id, ids) {
+  if (id === ids.VIRTUAL_ENTRY_ID) return ids.RESOLVED_ENTRY_ID;
+  if (id === ids.VIRTUAL_MANIFEST_ID) return ids.RESOLVED_MANIFEST_ID;
+  if (id === ids.VIRTUAL_ENTRY_SERVER_ID) return ids.RESOLVED_ENTRY_SERVER_ID;
+  if (id === ids.VIRTUAL_RUNTIME_CONFIG_ID) return ids.RESOLVED_RUNTIME_CONFIG_ID;
+  if (id === DEVTOOLS_VIRTUAL_ID) return DEVTOOLS_RESOLVED_ID;
+  return void 0;
+}
+function loadVirtualModule(id, ctx) {
+  if (id === ctx.ids.RESOLVED_ENTRY_ID) {
+    return generateEntryClient(ctx.ssrEnabled, {
+      theoUi: ctx.theoUi?.enabled ? { fonts: ctx.theoUi.config.fonts, theme: ctx.theoUi.config.theme } : void 0
     });
-  }).catch(() => {
-    console.warn(
-      '[Theo] WebSocket routes found but "ws" package not installed. Run: npm install ws'
-    );
-  });
+  }
+  if (id === ctx.ids.RESOLVED_MANIFEST_ID) {
+    const tree = scanRoutes(ctx.appDir);
+    broadcastRouteManifest(tree);
+    return generateRouteManifest(tree);
+  }
+  if (id === ctx.ids.RESOLVED_ENTRY_SERVER_ID) {
+    return generateEntryServer({
+      streaming: ctx.streamingEnabled,
+      theoUi: ctx.theoUi?.enabled ? { theme: ctx.theoUi.config.theme } : void 0
+    });
+  }
+  if (id === ctx.ids.RESOLVED_RUNTIME_CONFIG_ID) {
+    const tName = ctx.transformer?.name ?? "json";
+    return [
+      `// Generated by Theo Vite plugin`,
+      `;(globalThis).__THEO_TRANSFORMER__ = ${JSON.stringify(tName)}`,
+      `export const TRANSFORMER_NAME = ${JSON.stringify(tName)}`
+    ].join("\n");
+  }
+  if (id === DEVTOOLS_RESOLVED_ID) {
+    return [
+      `// Theo devtools \u2014 virtual entry (DEV only)`,
+      `import('theokit/devtools/entry').catch((e) => console.error('[theo devtools] mount failed', e))`
+    ].join("\n");
+  }
+  return void 0;
 }
 
 // src/vite-plugin/integrations.ts
@@ -1941,8 +2249,8 @@ function findConsumerConfig(projectRoot, basename2) {
   let dir = projectRoot;
   for (let level = 0; level < 3; level++) {
     for (const ext of extensions) {
-      const candidate = resolve6(dir, `${basename2}${ext}`);
-      if (existsSync7(candidate)) return candidate;
+      const candidate = resolve9(dir, `${basename2}${ext}`);
+      if (existsSync9(candidate)) return candidate;
     }
     const parent = dirname4(dir);
     if (parent === dir) break;
@@ -1961,7 +2269,7 @@ async function theoPluginAsync(rootOrOptions) {
   });
   const servicesPlugins = [];
   if (options.services && Object.keys(options.services).length > 0) {
-    const { servicesTypedClientPlugin } = await import("./services-typed-client-XWYYBWGW.js");
+    const { servicesTypedClientPlugin } = await import("./services-typed-client-KK6RHRDG.js");
     servicesPlugins.push(
       servicesTypedClientPlugin({
         cwd: projectRoot,
@@ -1969,20 +2277,20 @@ async function theoPluginAsync(rootOrOptions) {
       })
     );
   }
-  const { appTypedClientPlugin } = await import("./app-typed-client-62FYBLVJ.js");
+  const { appTypedClientPlugin } = await import("./app-typed-client-YOMWSA3F.js");
   const appClientPlugin = appTypedClientPlugin({
     cwd: projectRoot,
-    serverDir: resolve6(projectRoot, "server"),
-    distDir: resolve6(projectRoot, ".theo")
+    serverDir: resolve9(projectRoot, "server"),
+    distDir: resolve9(projectRoot, ".theo")
   });
-  const { actionsVirtualModule } = await import("./actions-virtual-module-SEIPACG5.js");
+  const { actionsVirtualModule } = await import("./actions-virtual-module-XNHDNCZ6.js");
   const actionsPlugin = actionsVirtualModule({
-    serverDir: resolve6(projectRoot, "server"),
-    distDir: resolve6(projectRoot, ".theo")
+    serverDir: resolve9(projectRoot, "server"),
+    distDir: resolve9(projectRoot, ".theo")
   });
   const { serverRoutesHmrPlugin } = await import("./server-routes-hmr-PBHSKCQJ.js");
   const routesHmrPlugin = serverRoutesHmrPlugin({
-    serverDir: resolve6(projectRoot, "server")
+    serverDir: resolve9(projectRoot, "server")
   });
   return [
     theoPlugin(rootOrOptions),
@@ -1995,10 +2303,10 @@ async function theoPluginAsync(rootOrOptions) {
 }
 function buildOptimizeDepsInclude(projectRoot, viteOptimizeDeps) {
   const include = [];
-  if (existsSync7(resolve6(projectRoot, "node_modules", "@theokit", "ui"))) {
+  if (existsSync9(resolve9(projectRoot, "node_modules", "@theokit", "ui"))) {
     include.push("@theokit/ui");
   }
-  if (existsSync7(resolve6(projectRoot, "node_modules", "lucide-react"))) {
+  if (existsSync9(resolve9(projectRoot, "node_modules", "lucide-react"))) {
     include.push("lucide-react");
   }
   include.push("devalue");
@@ -2011,10 +2319,20 @@ function buildOptimizeDepsInclude(projectRoot, viteOptimizeDeps) {
   }
   return include;
 }
+var VIRTUAL_MODULE_IDS = {
+  VIRTUAL_ENTRY_ID,
+  RESOLVED_ENTRY_ID,
+  VIRTUAL_MANIFEST_ID,
+  RESOLVED_MANIFEST_ID,
+  VIRTUAL_ENTRY_SERVER_ID,
+  RESOLVED_ENTRY_SERVER_ID,
+  VIRTUAL_RUNTIME_CONFIG_ID,
+  RESOLVED_RUNTIME_CONFIG_ID
+};
 function theoPlugin(rootOrOptions) {
   const options = typeof rootOrOptions === "string" ? { root: rootOrOptions } : rootOrOptions ?? {};
   const projectRoot = options.root ?? process.cwd();
-  const appDir = resolve6(projectRoot, "app");
+  const appDir = resolve9(projectRoot, "app");
   const ssrEnabled = options.ssr ?? false;
   const currentDir = dirname4(fileURLToPath(import.meta.url));
   const theoSrcDir = resolveTheoRootDir(currentDir);
@@ -2030,7 +2348,7 @@ function theoPlugin(rootOrOptions) {
   let devtoolsEnabled = true;
   let resolvedOpenApi;
   let resolvedDistDir = ".theo";
-  let isDevMode = false;
+  const isDevModeRef = { value: false };
   let configLoadedOnce = false;
   return {
     name: "theo",
@@ -2051,223 +2369,73 @@ function theoPlugin(rootOrOptions) {
       resolvedOpenApi = resolved.openapi;
       resolvedDistDir = resolved.distDir;
     },
-    // Vite calls this hook (sync return is fine — no awaits left after
-    // the auto-chain moved to theoPluginAsync). The @theokit/ui +
-    // @tailwindcss/vite auto-chain lives in `theoPluginAsync` because
-    // Vite drops plugins returned from a child plugin's config() hook.
+    // T2.6 (M6) — config() body extracted to config-hook.ts. The hook
+    // owns optimizeDeps + warmup + services proxy + alias cascade.
+    // The @theokit/ui + @tailwindcss/vite auto-chain lives in
+    // `theoPluginAsync` because Vite drops plugins returned from a
+    // child plugin's config() hook.
     config() {
-      const ext = existsSync7(resolve6(theoSrcDir, "index.ts")) ? ".ts" : ".js";
-      const optimizeDepsInclude = buildOptimizeDepsInclude(projectRoot, options.viteOptimizeDeps);
-      const warmupClientFiles = [];
-      for (const candidate of ["app/layout.tsx", "app/page.tsx", "app/page.jsx"]) {
-        const full = resolve6(projectRoot, candidate);
-        if (existsSync7(full)) warmupClientFiles.push(`./${candidate}`);
-      }
-      const servicesProxy = options.services && Object.keys(options.services).length > 0 ? buildServicesProxyConfig(options.services) : void 0;
-      return {
-        envPrefix: "THEO_PUBLIC_",
-        optimizeDeps: {
-          ...optimizeDepsInclude.length > 0 ? { include: optimizeDepsInclude } : {},
-          force: true
-        },
-        server: {
-          ...warmupClientFiles.length > 0 ? { warmup: { clientFiles: warmupClientFiles } } : {},
-          ...servicesProxy !== void 0 ? { proxy: servicesProxy } : {},
-          // Skip watching gitignored heavy dirs to avoid hitting ENOSPC
-          // (inotify watcher exhaustion). `referencias/` are deep-research
-          // clones; `.theokit/` is per-conversation cache; `.theo/` is
-          // build output. None should trigger HMR.
-          watch: {
-            ignored: [
-              "**/referencias/**",
-              "**/.theokit/**",
-              "**/.theo/**",
-              "**/dist/**",
-              "**/node_modules/**"
-            ]
-          }
-        },
-        resolve: {
-          alias: [
-            // Order matters: most-specific first so `theokit/X` doesn't
-            // get matched by the bare `theokit` alias.
-            { find: "theokit/server", replacement: resolve6(theoSrcDir, `server/index${ext}`) },
-            { find: "theokit/client", replacement: resolve6(theoSrcDir, `client/index${ext}`) },
-            {
-              find: "theokit/react-query",
-              replacement: resolve6(theoSrcDir, `react-query/index${ext}`)
-            },
-            {
-              find: "theokit/vite-plugin",
-              replacement: resolve6(theoSrcDir, `vite-plugin/index${ext}`)
-            },
-            {
-              find: "theokit/adapters/web-shim",
-              replacement: resolve6(theoSrcDir, `adapters/web-shim${ext}`)
-            },
-            {
-              find: "theokit/adapters/ws-shim",
-              replacement: resolve6(theoSrcDir, `adapters/ws-shim${ext}`)
-            },
-            // T1.2 — devtools entry (DEV only; tree-shaken in build because
-            // the script tag is never injected by inject-devtools.ts in build mode)
-            {
-              find: "theokit/devtools/entry",
-              replacement: resolve6(theoSrcDir, `devtools/entry${ext === ".ts" ? ".tsx" : ".js"}`)
-            },
-            { find: "theokit", replacement: resolve6(theoSrcDir, `index${ext}`) }
-          ]
-        }
-      };
+      return runConfigHook({
+        projectRoot,
+        theoSrcDir,
+        services: options.services,
+        optimizeDepsInclude: buildOptimizeDepsInclude(projectRoot, options.viteOptimizeDeps)
+      });
     },
-    // Auto-inject the entry-client `<script>` into every served HTML
-    // (Phase 2 of nextjs-maturity plan). Runs BEFORE Vite's own
-    // transform so the injection lands inside <body>, not after
-    // Vite-injected content. Idempotent: if the user already wrote
-    // the script tag, the HTML is returned unchanged.
+    // T2.6 (M6) — transformIndexHtml hook extracted to transform-html-hook.ts.
+    // Preserves the canonical 3-step order (entry-client → devtools → styles)
+    // so EC-10 (Vite hook ordering side effects) is honored.
     transformIndexHtml: {
       order: "pre",
       handler(html) {
-        const entry = injectEntryClient(html);
-        if (entry.warning) console.warn(entry.warning);
-        let next = entry.html;
-        const devtools = injectDevtoolsScript(next, {
-          isDev: isDevMode,
-          enabled: devtoolsEnabled
+        return runTransformIndexHtml(html, {
+          isDevMode: isDevModeRef,
+          devtoolsEnabled,
+          projectRoot
         });
-        if (devtools.warning) console.warn(devtools.warning);
-        next = devtools.html;
-        const styles = injectStylesheets(next, {
-          isDev: isDevMode,
-          hasPackage: (name) => existsSync7(resolve6(projectRoot, "node_modules", ...name.split("/")))
-        });
-        next = styles.html;
-        return next;
       }
     },
+    // T2.6 (M6) — virtual-module resolveId + load dispatch extracted to
+    // virtual-modules-hook.ts. Pure structural split; identity branches
+    // preserved.
     resolveId(id) {
-      if (id === VIRTUAL_ENTRY_ID) return RESOLVED_ENTRY_ID;
-      if (id === VIRTUAL_MANIFEST_ID) return RESOLVED_MANIFEST_ID;
-      if (id === VIRTUAL_ENTRY_SERVER_ID) return RESOLVED_ENTRY_SERVER_ID;
-      if (id === VIRTUAL_RUNTIME_CONFIG_ID) return RESOLVED_RUNTIME_CONFIG_ID;
-      if (id === DEVTOOLS_VIRTUAL_ID) return DEVTOOLS_RESOLVED_ID;
+      return resolveVirtualModuleId(id, VIRTUAL_MODULE_IDS);
     },
     load(id) {
-      if (id === RESOLVED_ENTRY_ID) {
-        return generateEntryClient(ssrEnabled, {
-          theoUi: theoUi?.enabled ? { fonts: theoUi.config.fonts, theme: theoUi.config.theme } : void 0
-        });
-      }
-      if (id === RESOLVED_MANIFEST_ID) {
-        const tree = scanRoutes(appDir);
-        broadcastRouteManifest(tree);
-        return generateRouteManifest(tree);
-      }
-      if (id === RESOLVED_ENTRY_SERVER_ID) {
-        return generateEntryServer({
-          streaming: options.ssrStreaming === true,
-          theoUi: theoUi?.enabled ? { theme: theoUi.config.theme } : void 0
-        });
-      }
-      if (id === RESOLVED_RUNTIME_CONFIG_ID) {
-        const tName = transformer?.name ?? "json";
-        return [
-          `// Generated by Theo Vite plugin`,
-          `;(globalThis).__THEO_TRANSFORMER__ = ${JSON.stringify(tName)}`,
-          `export const TRANSFORMER_NAME = ${JSON.stringify(tName)}`
-        ].join("\n");
-      }
-      if (id === DEVTOOLS_RESOLVED_ID) {
-        return [
-          `// Theo devtools \u2014 virtual entry (DEV only)`,
-          `import('theokit/devtools/entry').catch((e) => console.error('[theo devtools] mount failed', e))`
-        ].join("\n");
-      }
+      return loadVirtualModule(id, {
+        ids: VIRTUAL_MODULE_IDS,
+        appDir,
+        ssrEnabled,
+        streamingEnabled: options.ssrStreaming === true,
+        theoUi,
+        transformer
+      });
     },
+    // T2.6 (M6) — configureServer body extracted to configure-server-hook.ts.
+    // The hook owns middleware order, ws subscriptions, watcher handlers,
+    // OpenAPI re-emit, and WS upgrade. EC-10 honored (every effect preserved
+    // in its original ordering).
     async configureServer(server) {
-      isDevMode = true;
-      globalThis.__theoViteHotServer = server;
-      server.ws.on("theo:devtools:request-manifest", () => {
-        try {
-          const tree = scanRoutes(appDir);
-          broadcastRouteManifest(tree);
-        } catch {
-        }
-      });
-      const serverDir = resolve6(projectRoot, "server");
-      server.middlewares.use(
-        createActionMiddleware(server, serverDir, { pluginRunner, csrfMode, disallowed })
-      );
-      const servicesProxyPrefixes = options.services && Object.keys(options.services).length > 0 ? Object.values(options.services).map((s) => s.proxy) : [];
-      const csrfReadinessStore = options.csrfReadinessStore ?? new CsrfReadinessStore();
-      server.middlewares.use(
-        createApiMiddleware(server, serverDir, {
-          rateLimitConfig: options.rateLimit,
-          pluginRunner,
-          batching: resolvedBatching,
-          transformer,
-          csrfMode,
-          securityHeaders,
-          disallowed,
-          cors,
-          auditLogger,
-          servicesProxyPrefixes,
-          csrfReadinessStore
-        })
-      );
-      const configPath = resolve6(projectRoot, "theo.config.ts");
-      server.watcher.on("change", (file) => {
-        if (file === configPath) {
-          console.warn(
-            "\n[theokit] theo.config.ts changed; restart dev server for plugin changes to take effect\n"
-          );
-        }
-      });
-      if (ssrEnabled) {
-        setupSsrDevMiddleware(server, {
-          projectRoot,
-          virtualEntryServerId: VIRTUAL_ENTRY_SERVER_ID,
-          securityHeaders
-        });
-      }
-      function handleRouteChange(filePath) {
-        if (!isRouteFile(basename(filePath))) return;
-        if (!filePath.startsWith(appDir)) return;
-        const mod = server.moduleGraph.getModuleById(RESOLVED_MANIFEST_ID);
-        if (mod) {
-          server.moduleGraph.invalidateModule(mod);
-          server.ws.send({ type: "full-reload" });
-        }
-      }
-      server.watcher.on("add", handleRouteChange);
-      server.watcher.on("unlink", handleRouteChange);
-      if (resolvedOpenApi !== void 0) {
-        const openApiCfg = resolvedOpenApi;
-        const { reEmitOpenApi } = await import("./dev-emit-RBSFZZNO.js");
-        const openApiServerDir = resolve6(projectRoot, "server");
-        const openApiDistDir = resolve6(projectRoot, resolvedDistDir);
-        const isRouteFileForOpenApi = (file) => file.startsWith(openApiServerDir) && /\.(ts|tsx|js|mjs)$/.test(file);
-        void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
-        server.watcher.on("change", (file) => {
-          if (isRouteFileForOpenApi(file)) {
-            void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
-          }
-        });
-        server.watcher.on("add", (file) => {
-          if (isRouteFileForOpenApi(file)) {
-            void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
-          }
-        });
-        server.watcher.on("unlink", (file) => {
-          if (isRouteFileForOpenApi(file)) {
-            void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
-          }
-        });
-      }
-      setupWsUpgrade(server, projectRoot);
-      server.httpServer?.once("close", () => {
-        ;
-        globalThis.__theoViteHotServer = void 0;
+      await runConfigureServer(server, {
+        projectRoot,
+        appDir,
+        resolvedDistDir,
+        ssrEnabled,
+        isDevMode: isDevModeRef,
+        pluginRunner,
+        transformer,
+        resolvedBatching,
+        csrfMode,
+        securityHeaders,
+        disallowed,
+        cors,
+        auditLogger,
+        resolvedOpenApi,
+        services: options.services,
+        rateLimit: options.rateLimit,
+        csrfReadinessStoreOverride: options.csrfReadinessStore,
+        virtualEntryServerId: VIRTUAL_ENTRY_SERVER_ID,
+        resolvedManifestId: RESOLVED_MANIFEST_ID
       });
     }
   };
@@ -2278,10 +2446,10 @@ export {
   theoConfigSchema,
   deepMerge,
   loadConfig,
-  generateEntryClient,
-  generateRouteManifest,
   isRouteFile,
   scanRoutes,
+  generateEntryClient,
+  generateRouteManifest,
   defineTheoIntegration,
   IntegrationVirtualModulePrefixError,
   IntegrationRouteCollisionError,
@@ -2289,4 +2457,4 @@ export {
   theoPluginAsync,
   theoPlugin
 };
-//# sourceMappingURL=chunk-BIGBFZSU.js.map
+//# sourceMappingURL=chunk-2F4FROEQ.js.map