theokit 0.67.0 → 0.69.0

package/dist/cloudflare-GK4VD3EU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/cloudflare.ts"],"sourcesContent":["/* eslint-disable security/detect-non-literal-fs-filename --\n * Cloudflare deploy adapter. All write paths are under `cwd/.theokit/cloudflare/`\n * and `cwd/wrangler.toml`. Build-time tool — no HTTP input.\n */\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { resolve } from 'node:path'\n\nimport type { TheoConfig } from '../config/schema.js'\nimport { findRootDiv } from '../core/contracts/find-root-div.js'\nimport { parseAssetsMap } from '../core/contracts/module-preloads.js'\nimport type { SecurityHeadersConfig } from '../core/contracts/security-headers.js'\nimport { assertServicesUnsupported, readManifest } from '../services/index.js'\n\nimport { deployedAgentsFragment, type DeployedAgent } from './deployed-agents.js'\nimport { deployedCorsFragment, type DeployedCorsOptions } from './deployed-cors.js'\nimport { deployedCsrfFragment, type DeployedCsrfOptions } from './deployed-csrf.js'\nimport { planDeployedPlugins } from './deployed-plugins-module.js'\nimport {\n  deployedRuntimeConfigFragment,\n  serverDirLiteral,\n  type DeployedRuntimeConfigOptions,\n  type DeployedServerDirOptions,\n} from './deployed-runtime-config.js'\nimport { deployedTraceFragment } from './deployed-trace.js'\nimport { nodeAdapter } from './node.js'\nimport { describeDeployedSecurityHeaders, securityHeadersDeclarations } from './security-headers.js'\nimport type { AdapterBuildContext, DeployAdapter } from './types.js'\n\n/**\n * T2.1 — Cloudflare adapter rewritten to consume `theokit/adapters/web-shim`\n * instead of emitting an inline plain-object Request/Response shim. Reduces\n * template from ~50 lines to ~25 and centralizes maintenance.\n */\n\n/**\n * The built `index.html` split into the part before `<div id=\"root\">` and the\n * part after it.\n *\n * Refuses by name when streaming is on and the template is missing, rather than\n * emitting a worker that serves a headless document. A build that cannot produce\n * a correct artifact should say so at build time; the alternative is a deploy\n * that looks successful and serves pages with no stylesheet.\n */\n/**\n * @internal Exported for tests only. Nothing re-exports this module, so this does not reach the\n * published surface — `findRootDiv`, exported for the same reason, appears 0 times in `dist/`.\n */\nexport function readDocumentShell(\n  cwd: string,\n  streaming: boolean,\n): { htmlHead?: string; htmlTail?: string } {\n  if (!streaming) return {}\n\n  const indexPath = resolve(cwd, '.theokit/client/index.html')\n  if (!existsSync(indexPath)) {\n    throw new Error(\n      `[adapter-cloudflare] ssrStreaming is on but ${indexPath} does not exist, so the worker ` +\n        `would serve a document with no <head> and no client entry. Run the client build first, ` +\n        `or set ssrStreaming: false in theo.config.ts.`,\n    )\n  }\n\n  const indexHtml = readFileSync(indexPath, 'utf-8')\n  const rootDiv = findRootDiv(indexHtml)\n  if (rootDiv === undefined) {\n    throw new Error(\n      `[adapter-cloudflare] ${indexPath} has no <div id=\"root\">, so the streamed document has ` +\n        `nowhere to put the app. Add one, or set ssrStreaming: false in theo.config.ts.`,\n    )\n  }\n\n  return {\n    htmlHead: indexHtml.slice(0, rootDiv.insertAt),\n    htmlTail: indexHtml.slice(rootDiv.insertAt),\n  }\n}\n\n/**\n * The routes, turned into source: static imports, a module map and a literal table (#369).\n *\n * Extracted so the worker renderer stays inside its length budget, and because this is the whole of\n * what changed about how a Worker finds a route — it reads as one idea rather than as three loops\n * inside a hundred lines of template.\n *\n * `../../` because the worker is written to `.theokit/cloudflare/worker.mjs` and `filePath` is\n * relative to the project root. The imports are static so Wrangler's bundler follows them:\n * `wrangler.toml` uploads `.theokit/client` and has never uploaded `server/`, so a module not\n * bundled INTO the worker is not on the platform at all.\n */\nfunction renderBakedRoutes(\n  routes: readonly { filePath: string; routePath: string; methods?: readonly string[] }[],\n): { routeImports: string[]; routeModuleEntries: string[]; routeTableEntries: string[] } {\n  const routeVar = (index: number): string => `__theoRoute${String(index)}`\n  return {\n    routeImports: routes.map(\n      (route, index) => `import * as ${routeVar(index)} from '../../${route.filePath}'`,\n    ),\n    routeModuleEntries: routes.map(\n      (route, index) => `  ${JSON.stringify(route.filePath)}: ${routeVar(index)},`,\n    ),\n    routeTableEntries: routes.map(\n      (route) =>\n        `  { filePath: ${JSON.stringify(route.filePath)}, routePath: ${JSON.stringify(route.routePath)}, ` +\n        `methods: ${JSON.stringify([...(route.methods ?? [])])}, ` +\n        `...compilePattern(${JSON.stringify(route.routePath)}) },`,\n    ),\n  }\n}\n\n/**\n * The route-resolution runtime the Worker gets instead of a directory scan (#369).\n *\n * A module map, the literal table, and a loader that refuses anything the build did not bake.\n * Emitted as its own block because it replaces one idea — \"find the routes\" — wholesale.\n */\nfunction routeRuntimeLines(moduleEntries: string[], tableEntries: string[]): string[] {\n  return [\n    `// #369 — the routes are baked at build time. The Worker used to reach for`,\n    `// \\`scanServerRoutes\\` on the server directory — a readdirSync, in a runtime with no`,\n    `// filesystem. The pattern is recompiled here from the same routePath the scanner`,\n    `// used, so one function decides precedence on every target.`,\n    `const ROUTE_MODULES = {`,\n    ...moduleEntries,\n    `}`,\n    ``,\n    `const routes = [`,\n    ...tableEntries,\n    `]`,\n    ``,\n    `// The executor asks for a module by the path the table names. Anything else was`,\n    `// never bundled, and saying so beats returning undefined and failing later on a`,\n    `// property access far from the cause.`,\n    `async function loadModule(path) {`,\n    `  const mod = ROUTE_MODULES[path]`,\n    `  if (mod === undefined) {`,\n    // No backticks in this message: it is emitted INTO a template literal, and a stray one closes\n    // it. That is how #344 shipped a SyntaxError, and the emitted-entry parse gate caught this one\n    // before it left the branch.\n    \"  throw new Error(`Route module '\" +\n      '${path}' +\n      \"' was not bundled into this Worker. \" +\n      'A Worker has no filesystem, so every route is imported at build time. ' +\n      'Re-run: theokit build --target cloudflare`)',\n    `  }`,\n    `  return mod`,\n    `}`,\n    ``,\n  ]\n}\n\n/**\n * Read the map `theokit build` emitted, for baking into the worker (B-035).\n *\n * Returns `undefined` — never throws — for an absent or malformed file. A deploy that failed\n * because an optimisation was missing would turn a lost round trip into a broken build, and the\n * worker is correct without it.\n */\nexport function readAssetsMapForBake(path: string): Record<string, string[]> | undefined {\n  try {\n    return parseAssetsMap(readFileSync(path, 'utf8'))\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * The baked route-to-chunks map, as worker source (B-035).\n *\n * A literal and not a read, for the same reason the document shell is: a Worker has no filesystem\n * at request time. Emitted only when the build produced a map; otherwise the worker carries\n * nothing about preloads and behaves exactly as before.\n *\n * **It emits the DATA and no longer the code.** An earlier revision emitted a hand-written copy of\n * `injectModulePreloads`, justified by a claim that the worker could not import it. That claim was\n * false — `theokit/server` re-exports from `core/contracts/` and the generated worker already\n * imports that subpath — and the copy drifted within a day: a fix for proxy-form request targets\n * landed in the original and not in the duplicate. The worker now imports the real function, which\n * is the shape `adapters/security-headers.ts` established one directory over for exactly this\n * build-half/runtime-half pair.\n */\n/**\n * Whether this worker can preload at all (B-035).\n *\n * ONE predicate, read by the bake, the import and the call. Two conditions for one decision is\n * how the import came to be emitted for a worker that had no map to give it — found at review, in\n * the same change where a copy and its original had already drifted apart.\n *\n * Streaming is required because the other branch serves the document from `env.ASSETS` as a\n * static file and can inject nothing into it.\n */\nfunction preloadsApplyTo(opts: {\n  ssrStreaming?: boolean\n  assetsMap?: Record<string, string[]>\n}): boolean {\n  return opts.ssrStreaming === true && opts.assetsMap !== undefined\n}\n\nfunction renderPreloadSupport(assetsMap: Record<string, string[]> | undefined): string {\n  if (assetsMap === undefined) return ''\n  return `const __THEO_ASSETS_MAP = ${JSON.stringify(assetsMap)}`\n}\n\n/**\n * The branch that answers a non-API request: streamed SSR, or the static asset the Worker\n * platform serves. Extracted at review — it is the one decision in this emitter with two whole\n * shapes behind it, and keeping it inline pushed the caller past its line budget.\n */\nfunction renderNonApiBranch(\n  opts: NonNullable<Parameters<typeof renderCloudflareWorkerEntry>[0]>,\n  preloadsApply: boolean,\n): string {\n  return opts.ssrStreaming\n    ? [\n        `      // T2.3 — streaming SSR for non-API routes`,\n        `      // The same primitive \\`theokit start\\` uses, not a second one:`,\n        `      // 16 bytes of Web Crypto entropy, base64.`,\n        `      const nonce = generateNonce()`,\n        `      return withSecurityHeaders(`,\n        `        await renderStreamingWeb(request, {`,\n        !preloadsApply\n          ? `          htmlHead: ${JSON.stringify(opts.htmlHead ?? '')},`\n          : `          htmlHead: injectModulePreloads(${JSON.stringify(opts.htmlHead ?? '')}, __THEO_ASSETS_MAP, new URL(request.url).pathname),`,\n        `          htmlTail: ${JSON.stringify(opts.htmlTail ?? '')},`,\n        `          nonce,`,\n        `        }),`,\n        `        buildSecurityHeaders(SECURITY_HEADERS_CONFIG, { production: true }, { nonce }),`,\n        `      )`,\n      ].join('\\n')\n    : [\n        `      // #412 — the document, served by the worker so it carries the same baseline every`,\n        `      // API response carries. It used to return 404 here while wrangler.toml declared a`,\n        `      // \\`[site]\\` bucket nothing read, so the page was missing rather than unprotected.`,\n        `      const assets = env?.ASSETS`,\n        `      // A wrangler.toml that predates this binding has no ASSETS. Reading .fetch off`,\n        `      // undefined would turn every page request into a 500; 404 is what this target`,\n        `      // answered before, which is the honest fallback rather than a new failure.`,\n        `      if (assets === undefined) return notFoundResponse()`,\n        `      return withSecurityHeaders(await assets.fetch(request), SECURITY_HEADERS)`,\n      ].join('\\n')\n}\n\nexport function renderCloudflareWorkerEntry(\n  opts: {\n    ssrStreaming?: boolean\n    htmlHead?: string\n    htmlTail?: string\n    /**\n     * B-035 — the route-to-chunks map, baked as a literal for the same reason the shell above\n     * is: a Worker has no filesystem at request time. Absent when the build produced no map,\n     * and then nothing about preloads is emitted at all.\n     */\n    assetsMap?: Record<string, string[]>\n    securityHeaders?: SecurityHeadersConfig\n    /**\n     * The server routes, scanned on the BUILD machine (#369).\n     *\n     * A Worker has no filesystem, so the worker used to call `scanServerRoutes` — a `readdirSync` —\n     * against a directory that does not exist there, and load each module through `import()` of a\n     * file path. Both are baked here instead, which is the road this adapter already takes for the\n     * document shell one function away.\n     *\n     * `filePath` is relative to the project root and is used for two things: the key the executor\n     * looks a module up by, and the specifier the static import uses. Paths are emitted relative to\n     * `.theokit/cloudflare/`, where the worker is written.\n     */\n    routes?: readonly { filePath: string; routePath: string; methods?: readonly string[] }[]\n    /**\n     * The two concerns #410 could not bake (#425), composed from one place so the six targets\n     * cannot drift into six spellings. `serialization` is a literal like the security values above;\n     * `plugins` is an import, because a closure has no literal.\n     */\n    runtimeConfigModule?: DeployedRuntimeConfigOptions['runtimeConfigModule']\n    serialization?: DeployedRuntimeConfigOptions['serialization']\n    /**\n     * The app's agents, scanned on the build machine (#367).\n     *\n     * A different scan from `routes` and served by a different function — which is why a worker\n     * that only consulted the route table answered every `/api/agents/<name>` with a 404.\n     */\n    agents?: readonly DeployedAgent[]\n    /** B-185 — the app's `server/context.ts`, project-relative, or absent when it declares none. */\n    contextModule?: string\n    /** WebSocket route files, scanned on the build machine. Only their presence is used (#369). */\n    wsRoutes?: readonly string[]\n  } & DeployedServerDirOptions &\n    DeployedCsrfOptions &\n    DeployedCorsOptions = {},\n): string {\n  const streamingImport = opts.ssrStreaming\n    ? `import { renderStreamingWeb } from '/@theo/entry-server'`\n    : `// (ssrStreaming off: renderStreamingWeb not imported)`\n  // #343 — the document shell is inlined as a build-time literal because a Worker\n  // has no filesystem to read `index.html` from at request time. Without it,\n  // `renderStreamingWeb` falls back to its empty-string defaults and the response\n  // is React output with no `<html>`, no `<head>`, no stylesheet and no client\n  // entry — hydration data for a page that cannot hydrate. The streaming\n  // assembly was fixed in the generated entry and this, its only caller, was\n  // left passing nothing.\n  //\n  // `JSON.stringify` and not a template literal: the shell contains quotes,\n  // angle brackets and a `</script>`, and embedding it naively produces a worker\n  // that fails to parse at deploy time rather than here.\n  //\n  // #410 — this is also the ONE deploy path that renders HTML at request time,\n  // so the one that can mint a per-request CSP nonce: `renderStreamingWeb`\n  // threads `options.nonce` into `renderToReadableStream` and into the hydration\n  // script (`router/entry-server.ts`). Every other response below carries the\n  // nonce-less baseline, which is what `buildSecurityHeaders` already does for a\n  // prerendered route (EC-4).\n  // Only the streaming branch renders HTML at request time; the other serves the document from\n  // `env.ASSETS` as a static file and can inject nothing. Baking the map for it would ship the whole\n  // route table as dead weight — found at review, where the emitter was measured declaring it with\n  // zero call sites.\n  const preloadsApply = preloadsApplyTo(opts)\n  const preloadSupport = preloadsApply ? renderPreloadSupport(opts.assetsMap) : ''\n\n  const nonApiBranch = renderNonApiBranch(opts, preloadsApply)\n\n  // CR-006: Workers lack `process.cwd()` and the `node:*` import surface\n  // is brittle even under `nodejs_compat`. We use the Web Crypto\n  // `crypto.randomUUID()` instead of `node:crypto.randomUUID`, and embed\n  // the server directory as a build-time literal instead of resolving via\n  // `node:path` at runtime.\n  const { routeImports, routeModuleEntries, routeTableEntries } = renderBakedRoutes(\n    opts.routes ?? [],\n  )\n  const runtimeConfig = deployedRuntimeConfigFragment(opts)\n  const agentsFragment = deployedAgentsFragment(\n    opts.agents === undefined\n      ? undefined\n      : // B-185 — a Worker has no filesystem, so its identity module is baked exactly like its\n        // agents and its routes (ADR 0014). `contextModule` is `undefined` for an app that\n        // declares none, and the generator then emits no import for it.\n        { kind: 'baked', agents: opts.agents, contextModule: opts.contextModule },\n    {\n      wrapSecurityHeaders: true,\n      // B-185 — bound only when the runtime-config fragment declared the const, which is\n      // exactly when a plugins module was emitted. Referencing it otherwise would emit an\n      // identifier the entry never declares.\n      pluginRunnerExpr:\n        opts.runtimeConfigModule === undefined ? undefined : 'await THEO_PLUGIN_RUNNER',\n    },\n  )\n\n  return [\n    `// Generated by Theo — Cloudflare Workers Adapter`,\n    `//`,\n    `// REQUIREMENTS (EC-3):`,\n    `//   - wrangler.toml MUST include compatibility_flags = [\"nodejs_compat\"]`,\n    `//     (still required for transitive theokit/server deps, e.g. busboy)`,\n    `//   - package.json MUST list \"theokit\" in dependencies (not devDependencies)`,\n    `//     so Wrangler bundles theokit and its transitive deps`,\n    `//   - Deploy: wrangler deploy`,\n    ``,\n    !preloadsApply\n      ? `import { matchRoute, executeRoute, compilePattern, extractTraceIdFromRequest, TRACE_HEADER, createCorsWebHandler } from 'theokit/server'`\n      : `import { matchRoute, executeRoute, compilePattern, extractTraceIdFromRequest, TRACE_HEADER, createCorsWebHandler } from 'theokit/server'\\nimport { injectModulePreloads } from 'theokit/server/http'`,\n    `import { createWebShim } from 'theokit/adapters/web-shim'`,\n    opts.ssrStreaming\n      ? `import { buildSecurityHeaders, generateNonce, withSecurityHeaders } from 'theokit/adapters/security-headers'`\n      : `import { buildSecurityHeaders, withSecurityHeaders } from 'theokit/adapters/security-headers'`,\n    `// T3.4 — WS bridge for Cloudflare Workers`,\n    `import { createCloudflareWsBridge } from 'theokit/adapters/ws-shim'`,\n    streamingImport,\n    ``,\n    ...runtimeConfig.imports,\n    ...agentsFragment.imports,\n    ...routeImports,\n    ``,\n    `// CR-006: server directory is a build-time literal — Workers cannot`,\n    `// call process.cwd() and resolving paths at runtime returned '/server'.`,\n    `const serverDir = ${serverDirLiteral(opts)}`,\n    ``,\n    ...routeRuntimeLines(routeModuleEntries, routeTableEntries),\n    `// #410 — the security baseline \\`theokit start\\` puts on every response, carried`,\n    `// here as a literal because a Worker has no theo.config.ts to read. Same`,\n    `// function, same input, so the deployed page and the local one cannot`,\n    `// disagree about what the configuration means.`,\n    preloadSupport,\n    ...securityHeadersDeclarations(opts.securityHeaders),\n    ``,\n    ...deployedCsrfFragment(opts, 'a Worker'),\n    ``,\n    ...runtimeConfig.declarations,\n    ...agentsFragment.declarations,\n    ...deployedCorsFragment(opts.cors, 'cloudflare'),\n    `// #369 — whether this project declares a WebSocket route, decided at build time. It used`,\n    `// to answer it with \\`scanWebSocketRoutes\\`, which is the same readdirSync.`,\n    `const HAS_WS_ROUTES = ${String((opts.wsRoutes ?? []).length > 0)}`,\n    ``,\n    `function notFoundResponse() {`,\n    `  return withSecurityHeaders(`,\n    `    new Response(`,\n    `      JSON.stringify({ error: { code: 'NOT_FOUND', message: 'Route not found' } }),`,\n    `      { status: 404, headers: { 'Content-Type': 'application/json' } },`,\n    `    ),`,\n    `    SECURITY_HEADERS,`,\n    `  )`,\n    `}`,\n    ``,\n    ...cloudflareHandleRequestFragment(\n      nonApiBranch,\n      runtimeConfig.executeRouteSpread,\n      agentsFragment.branch,\n      agentsFragment.hostBypass,\n    ),\n  ].join('\\n')\n}\n\n/**\n * The Worker's request handler, as generated source.\n *\n * Extracted for the reason `vercel.ts` extracts its own fragments: the emitter is one array\n * literal, so every line the entry gains counts against `max-lines-per-function`, and #410 added\n * the CSRF literal to an emitter already sitting exactly at the ceiling.\n *\n * @param nonApiBranch - what a non-`/api/` request gets, which differs with `ssrStreaming`\n */\nfunction cloudflareHandleRequestFragment(\n  nonApiBranch: string,\n  runtimeSpread: string,\n  agentBranch: readonly string[],\n  /** SI-020 — the condition that keeps an agent card path out of the static-asset branch. */\n  hostBypass: string,\n): string[] {\n  return [\n    `async function handleRequest(request, url, env) {`,\n    `    if (!url.pathname.startsWith('/api/')${hostBypass}) {`,\n    nonApiBranch,\n    `    }`,\n    ``,\n    ...agentBranch,\n    ``,\n    `    const match = matchRoute(url.pathname, routes)`,\n    `    if (!match) return notFoundResponse()`,\n    ``,\n    `    const { req, res, toResponse } = createWebShim(request, { trustedProxy: 'platform' })`,\n    ...deployedTraceFragment('request', '    '),\n    `    const method = request.method.toUpperCase()`,\n    `    // #382 — the run is NOT awaited before the Response is taken. toResponse()`,\n    `    // settles as soon as status + headers are known and carries a live body, so`,\n    `    // the Worker starts flushing while the handler is still writing. Awaiting`,\n    `    // executeRoute() first would re-buffer the whole response here even though`,\n    `    // the shim streams; awaiting toResponse() does not — it settles at the head.`,\n    `    return withSecurityHeaders(await toResponse(executeRoute({`,\n    `      route: match.route, method, params: match.params,`,\n    `      req, res, loadModule, serverDir, requestId, ...CSRF_CONFIG, ${runtimeSpread}`,\n    `    })), SECURITY_HEADERS)`,\n    `}`,\n    ``,\n    `export default {`,\n    `  async fetch(request, env, ctx) {`,\n    `    const url = new URL(request.url)`,\n    ``,\n    `    // T3.4 — Detect WebSocket upgrade and delegate to the CF bridge.`,\n    `    // A 101 carries no document and no script, so the security baseline does`,\n    `    // not apply to it.`,\n    `    if (request.headers.get('upgrade')?.toLowerCase() === 'websocket') {`,\n    `      if (!HAS_WS_ROUTES) return notFoundResponse()`,\n    `      const cfWs = createCloudflareWsBridge({`,\n    `        onOpen: () => {},`,\n    `        onMessage: (ws, data) => { ws.send(data) },`,\n    `        onClose: () => {},`,\n    `      })`,\n    `      return cfWs.handle(request)`,\n    `    }`,\n    ``,\n    `    // #409 — the preflight is answered BEFORE anything routes: an OPTIONS the router handles`,\n    `    // is an OPTIONS the browser never gets a CORS answer to. The WebSocket upgrade above is`,\n    `    // deliberately upstream of it — a 101 is not a CORS-governed response.`,\n    `    const preflight = corsPreflight(request)`,\n    `    if (preflight !== null) return withSecurityHeaders(preflight, SECURITY_HEADERS)`,\n    ``,\n    `    return withCors(request, await handleRequest(request, url, env))`,\n    `  },`,\n    `}`,\n  ]\n}\n\nexport function renderWranglerToml(): string {\n  return [\n    `# Generated by Theo — Cloudflare Workers`,\n    `name = \"theo-app\"`,\n    `main = \".theokit/cloudflare/worker.mjs\"`,\n    `compatibility_date = \"2025-09-01\"`,\n    `compatibility_flags = [\"nodejs_compat\"]`,\n    ``,\n    `# #412 — \\`[assets]\\` with a BINDING, not the legacy \\`[site]\\` bucket.`,\n    `#`,\n    `# \\`[site]\\` uploads to KV and is read through \\`kv-asset-handler\\` and a`,\n    `# \\`__STATIC_CONTENT\\` binding — neither of which this worker has ever had. So the`,\n    `# bucket was declared, uploaded, and consumed by nothing: with ssrStreaming off, a`,\n    `# deploy answered 404 for its own page. This binding is what the worker calls.`,\n    `[assets]`,\n    `directory = \".theokit/client\"`,\n    `binding = \"ASSETS\"`,\n    `# A client-routed app asks for /dashboard, which is no file. Without this the asset`,\n    `# handler 404s a deep link and the SPA never boots.`,\n    `not_found_handling = \"single-page-application\"`,\n    ``,\n    `# Environment variables are set via wrangler secret or dashboard`,\n    `# Example: wrangler secret put DATABASE_URL`,\n  ].join('\\n')\n}\n\nexport const cloudflareAdapter: DeployAdapter = {\n  name: 'cloudflare',\n  streamsResponses: true,\n  // #409 / #410 — the generated entry calls `executeRoute` with routes, loader\n  // and serverDir only. CSRF, route policy, file middleware and Zod validation\n  // still run because they live inside `executeRoute`; none of the remaining\n  // configurable concerns reach it. Declared explicitly rather than omitted so\n  // the gap is a statement in the source and not an absence.\n  //\n  // `securityHeaders` IS applied: the worker carries `security.headers` as a\n  // literal and puts the built baseline on every response it returns, including\n  // the streamed SSR document — with a per-request nonce, the only deploy path\n  // that can mint one (`adapters/security-headers.ts`).\n  servesAgents: true,\n  appliesConfig: ['securityHeaders', 'csrf', 'disallowed', 'cors', 'serialization', 'plugins'],\n\n  async build(config: TheoConfig, cwd: string, ctx?: AdapterBuildContext): Promise<void> {\n    // Wave 2 (T2.2) — reject polyglot services on this adapter.\n    assertServicesUnsupported('cloudflare', readManifest(cwd))\n\n    // 1. Run the standard Node build first (ctx forwarded so nodeAdapter has makeVitePlugins)\n    await nodeAdapter.build(config, cwd, ctx)\n\n    const outputDir = resolve(cwd, '.theokit/cloudflare')\n    mkdirSync(outputDir, { recursive: true })\n\n    // 2. Emit Worker entry (now uses the shared web-shim)\n    //\n    // The document shell is read HERE, after the Node build produced\n    // `.theokit/client/index.html`, and inlined into the worker: a Worker has no\n    // filesystem at request time. Split on the root div with the same helper the\n    // Node server uses (`ssr-setup.ts`), so the two paths cannot disagree about\n    // where the shell ends (#343).\n    const shell = readDocumentShell(cwd, config.ssrStreaming)\n    // B-035 — the route-to-chunks map, read HERE on the build machine for the same reason the\n    // shell above is: a Worker has no filesystem at request time. `nodeAdapter.build` ran\n    // first, so the map the Node build emitted is on disk by now. Absent map -> nothing about\n    // preloads is emitted, and the worker behaves exactly as it did before.\n    const assetsMap = readAssetsMapForBake(resolve(cwd, '.theokit', 'client', 'assets-map.json'))\n\n    // #369 — the routes are resolved HERE, on the build machine, for the same reason the document\n    // shell above is read here: a Worker has no filesystem at request time, and the worker used to\n    // run the scan itself against a directory that does not exist there.\n    //\n    // The scanner is INJECTED rather than imported: importing it would add an `adapters → server`\n    // edge, which is the layering inversion ADR-0001 v3 removed for `vite-plugin` and which\n    // `adapters-may-only-depend-on-core-router-services` refuses. An absent scanner emits a worker\n    // with no routes rather than falling back to a runtime scan — the fallback IS the defect.\n    const scanned = ctx?.scanRoutes?.(config.serverDir) ?? {\n      routes: [],\n      wsRoutes: [],\n      agents: [],\n      // B-185 — no provider means no scan, and an app whose context nobody looked for is\n      // indistinguishable here from one that has none. Both resolve an anonymous caller, which is\n      // the honest answer rather than an invented subject.\n      contextModule: undefined,\n    }\n\n    const pluginsPlan = planDeployedPlugins(config.plugins, 'cloudflare')\n    if (pluginsPlan !== undefined) {\n      // Beside the worker, so the emitted import is a sibling. Wrangler bundles from here, which is\n      // what lets the static import reach the app's own module at all (#425).\n      writeFileSync(resolve(outputDir, 'theo.plugins.mjs'), pluginsPlan.source)\n    }\n\n    writeFileSync(\n      resolve(outputDir, 'worker.mjs'),\n      renderCloudflareWorkerEntry({\n        ssrStreaming: config.ssrStreaming,\n        ...shell,\n        securityHeaders: config.security?.headers,\n        csrf: config.security?.csrf,\n        disallowed: config.security?.disallowed,\n        cors: config.security?.cors,\n        assetsMap,\n        // #425 — a selector, not a transformer, so it rides as a literal like the values above.\n        serialization: config.serialization,\n        // #425 — the ONE concern that is not a literal. A closure cannot be baked, so a plugin\n        // declared by module specifier is imported by the emitted module instead; a constructed one\n        // is refused by name at build time rather than dropped in silence.\n        runtimeConfigModule: pluginsPlan?.moduleSpecifier,\n        routes: scanned.routes,\n        // #367 — a Worker has no filesystem, so its agents are decided here like its routes.\n        agents: scanned.agents,\n        // B-185 — rides beside the agents because it is decided by the same provider, for the same\n        // reason: `build.ts` holds `serverDir` and a Worker cannot look for the module itself.\n        contextModule: scanned.contextModule,\n        wsRoutes: scanned.wsRoutes,\n      }),\n    )\n\n    // 3. Emit wrangler.toml (with nodejs_compat enforced)\n    writeFileSync(resolve(cwd, 'wrangler.toml'), renderWranglerToml())\n\n    // eslint-disable-next-line no-console -- CLI build progress\n    console.log('\\n  ✓ Cloudflare output → .theokit/cloudflare/ + wrangler.toml')\n    // eslint-disable-next-line no-console -- CLI build progress\n    console.log(\n      `${describeDeployedSecurityHeaders({\n        target: 'cloudflare',\n        securityHeaders: config.security?.headers,\n        // Only the streaming worker renders HTML per request, so only it can put\n        // the same nonce on the header and on the script tag it emits.\n        mintsNonce: config.ssrStreaming,\n        // #412 — either way the worker returns the document now: streamed by\n        // `renderStreamingWeb`, or from the ASSETS binding it finally calls.\n        documentHeaders: 'handler',\n      })}\\n`,\n    )\n  },\n}\n"],"mappings":"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","names":[]}

package/dist/{route-config-B7FaTSby.d.ts → define-middleware-BOHpPOBs.d.ts}

@@ -69,4 +69,42 @@ interface RouteConfig<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z
     }) => TResponse | Promise<TResponse>;
 }
 
-export type { RouteConfig as R };
+/**
+ * A middleware, as the framework's own builder produces it (usetheokit/theokit#345).
+ *
+ * `(request, context)`: read the request as a Web `Request`, decorate `context` for the route that
+ * follows, and RETURN a `Response` to answer the request yourself. Returning nothing continues to
+ * the next middleware, and then to the route.
+ *
+ * ## Why not `(request, next) => Response`
+ *
+ * That was this type's first shape, and it described a continuation pipeline nothing in this
+ * repository implements: the file-scan runner runs BEFORE routing, so it has no downstream
+ * `Response` to hand back from `next(request)`. The consequence was measured rather than
+ * theorised — `MiddlewareHandler` had **zero runtime consumers**, while `README.md` documented the
+ * builder that produces it as the way to write middleware. A published builder whose output nothing
+ * can call is worse than a missing one, because it reads as supported.
+ *
+ * This shape is the one that fits the model AND already runs: `executeWebRequest` has invoked
+ * `(request, context) => Response | void` since T3.2 (`http/web-middleware-runner.ts`). Adopting it
+ * here converges two of the three middleware contracts instead of adding a fourth.
+ *
+ * The Express-style `(req, res, next)` export keeps working in `server/middleware/*.ts`. It is
+ * Node-bound — which is why it cannot be the framework's contract — but evicting it would break
+ * every app that has one.
+ */
+/**
+ * Run the rest of the chain and resolve to what it produced.
+ *
+ * Declared HERE rather than beside the runner because the dependency runs
+ * `http/ -> define/` and never the other way (`http/middleware-runner.ts:10`
+ * already imports from this module). A middleware's contract belongs with the
+ * definition of a middleware; the runner consumes it.
+ *
+ * `docs/adr/0006` clause 3 is what this parameter buys: code AFTER the
+ * downstream, which the short-circuit shape cannot express.
+ */
+type MiddlewareNext = () => Promise<Response | undefined>;
+type MiddlewareHandler = (request: Request, context: Record<string, unknown>, next: MiddlewareNext) => Response | undefined | void | Promise<Response | undefined | void>;
+
+export type { MiddlewareHandler as M, RouteConfig as R, MiddlewareNext as a };

package/dist/{deno-deploy-BXOQ45LD.js → deno-deploy-WMNXRVGL.js}

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
 import "tsx/esm";
 import {
-  deployedAgentsFragment,
   planDeployedPlugins
-} from "./chunk-O55RLSGG.js";
+} from "./chunk-V5SSTT3C.js";
+import {
+  deployedEntryPreamble
+} from "./chunk-XG6SQUEP.js";
 import {
-  deployedCorsFragment,
-  deployedCsrfFragment,
+  agentsDirLiteral,
+  deployedAgentsFragment,
   deployedRuntimeConfigFragment,
   deployedTraceFragment,
   describeDeployedSecurityHeaders,
-  renderSecurityHeadersConfigLiteral
-} from "./chunk-6B3CMPE4.js";
+  scannedFromLoaderCache,
+  serverDirLiteral
+} from "./chunk-FFGP2LGQ.js";
 import {
   nodeAdapter
 } from "./chunk-KI4DOTN4.js";
@@ -24,17 +27,25 @@ import {
 // src/adapters/deno-deploy.ts
 import { mkdirSync, writeFileSync } from "fs";
 import { resolve } from "path";
+var FRAMEWORK_IMPORTS = [
+  `// Use npm: specifier so Deno resolves theokit from the user's package.json`,
+  `// equivalent (works in both local 'deno run' and Deno Deploy).`,
+  `import { scanServerRoutes, matchRoute, executeRoute, createProductionLoader, scanWebSocketRoutes, extractTraceIdFromRequest, TRACE_HEADER, createCorsWebHandler } from 'npm:theokit/server'`,
+  `import { createWebShim } from 'npm:theokit/adapters/web-shim'`,
+  `import { buildSecurityHeaders, withSecurityHeaders } from 'npm:theokit/adapters/security-headers'`,
+  `// T3.3 \u2014 WS bridge for Deno runtime`,
+  `import { createDenoWsBridge } from 'npm:theokit/adapters/ws-shim'`
+];
 function renderDenoEntry(port, opts = {}) {
   const runtimeConfig = deployedRuntimeConfigFragment(opts);
-  const agentsFragment = deployedAgentsFragment(
-    {
-      kind: "scan",
-      projectRoot: "cwd",
-      loadModule: "loaderCache",
-      ensureLoader: "if (!loaderCache) loaderCache = createProductionLoader()"
-    },
-    { notFound: "notFound()", importPrefix: "npm:" }
-  );
+  const agentsFragment = deployedAgentsFragment(scannedFromLoaderCache(agentsDirLiteral(opts)), {
+    notFound: "notFound()",
+    importPrefix: "npm:",
+    // B-185 — bound only when the runtime-config fragment declared the const, which is
+    // exactly when a plugins module was emitted. Referencing it otherwise would emit an
+    // identifier the entry never declares.
+    pluginRunnerExpr: opts.runtimeConfigModule === void 0 ? void 0 : "await THEO_PLUGIN_RUNNER"
+  });
   return [
     `// Generated by Theo \u2014 Deno Deploy Adapter`,
     `// Deploy: deployctl deploy --project=<name> .theokit/deno/server.ts`,
@@ -45,17 +56,11 @@ function renderDenoEntry(port, opts = {}) {
     `  throw new Error('TheoDenoDeployAdapter must run inside Deno.')`,
     `}`,
     ``,
-    `// Use npm: specifier so Deno resolves theokit from the user's package.json`,
-    `// equivalent (works in both local 'deno run' and Deno Deploy).`,
-    `import { scanServerRoutes, matchRoute, executeRoute, createProductionLoader, scanWebSocketRoutes, extractTraceIdFromRequest, TRACE_HEADER, createCorsWebHandler } from 'npm:theokit/server'`,
-    `import { createWebShim } from 'npm:theokit/adapters/web-shim'`,
-    `import { buildSecurityHeaders, withSecurityHeaders } from 'npm:theokit/adapters/security-headers'`,
-    `// T3.3 \u2014 WS bridge for Deno runtime`,
-    `import { createDenoWsBridge } from 'npm:theokit/adapters/ws-shim'`,
+    ...FRAMEWORK_IMPORTS,
     ``,
     `const port = Number(Deno.env.get('PORT') ?? '${port}')`,
     `const cwd = Deno.cwd()`,
-    `const serverDir = cwd + '/server'`,
+    `const serverDir = cwd + '/' + ${serverDirLiteral(opts)}`,
     `let routesCache = null`,
     `let wsRoutesCache = null`,
     `let loaderCache = null`,
@@ -65,16 +70,7 @@ function renderDenoEntry(port, opts = {}) {
     `// theo.config.ts to read. Non-API paths 404 here and are served by Deno`,
     `// Deploy's static asset handler, so this covers the API and not the`,
     `// document (usetheokit/theokit#412).`,
-    `const SECURITY_HEADERS_CONFIG = ${renderSecurityHeadersConfigLiteral(opts.securityHeaders)}`,
-    `const SECURITY_HEADERS = buildSecurityHeaders(SECURITY_HEADERS_CONFIG, { production: true })`,
-    ``,
-    ...runtimeConfig.imports,
-    ...agentsFragment.imports,
-    ...runtimeConfig.declarations,
-    ...agentsFragment.declarations,
-    ...deployedCsrfFragment(opts),
-    ``,
-    ...deployedCorsFragment(opts.cors, "deno-deploy"),
+    ...deployedEntryPreamble(runtimeConfig, agentsFragment, opts, "deno-deploy"),
     ``,
     `function notFound() {`,
     `  return new Response(JSON.stringify({ error: { code: 'NOT_FOUND' } }), {`,
@@ -108,7 +104,7 @@ function renderDenoEntry(port, opts = {}) {
     `async function handleRequest(request) {`,
     `  const url = new URL(request.url)`,
     ``,
-    `  if (!url.pathname.startsWith('/api/')) {`,
+    `  if (!url.pathname.startsWith('/api/')${agentsFragment.hostBypass}) {`,
     `    // Static + SPA fallback are served by Deno Deploy's static asset handler.`,
     `    return notFound()`,
     `  }`,
@@ -150,7 +146,12 @@ async function buildDeno(config, cwd, deps = {}, ctx) {
     // #425 — the ONE concern that is not a literal. A closure cannot be baked, so a plugin
     // declared by module specifier is imported by the emitted module instead; a constructed one
     // is refused by name at build time rather than dropped in silence.
-    runtimeConfigModule: pluginsPlan?.moduleSpecifier
+    runtimeConfigModule: pluginsPlan?.moduleSpecifier,
+    // #95 — the configured directories, which `build.ts:210` already threads into the Vite
+    // plugins. Without these two lines the literals above fall to their defaults and a project
+    // with a custom dir deploys an entry that resolves a directory it does not have.
+    serverDir: config.serverDir,
+    agentsDir: config.agentsDir
   });
   const write = deps.writeEntry ?? ((p, c) => {
     writeFileSync(p, c);
@@ -193,4 +194,4 @@ export {
   denoDeployAdapter,
   renderDenoEntry
 };
-//# sourceMappingURL=deno-deploy-BXOQ45LD.js.map
+//# sourceMappingURL=deno-deploy-WMNXRVGL.js.map

package/dist/deno-deploy-WMNXRVGL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/deno-deploy.ts"],"sourcesContent":["/* eslint-disable security/detect-non-literal-fs-filename --\n * Deno Deploy adapter. Writes to `cwd/.theokit/deno-deploy/`. Build-time.\n */\nimport { mkdirSync, writeFileSync } from 'node:fs'\nimport { resolve } from 'node:path'\n\nimport type { TheoConfig } from '../config/schema.js'\nimport { assertServicesUnsupported, readManifest } from '../services/index.js'\n\nimport { deployedAgentsFragment, scannedFromLoaderCache } from './deployed-agents.js'\nimport { planDeployedPlugins } from './deployed-plugins-module.js'\nimport { deployedEntryPreamble } from './deployed-preamble.js'\nimport {\n  agentsDirLiteral,\n  deployedRuntimeConfigFragment,\n  serverDirLiteral,\n} from './deployed-runtime-config.js'\nimport { deployedTraceFragment } from './deployed-trace.js'\nimport { nodeAdapter } from './node.js'\nimport { describeDeployedSecurityHeaders } from './security-headers.js'\nimport type { AdapterBuildContext, DeployAdapter, DeployedEntryOptions } from './types.js'\n\nexport interface DenoBuildDeps {\n  runNodeBuild?: (config: TheoConfig, cwd: string, ctx?: AdapterBuildContext) => Promise<void>\n  writeEntry?: (path: string, content: string) => void\n  ensureDir?: (path: string) => void\n}\n\n/**\n * The framework imports this entry opens with, as `npm:` specifiers.\n *\n * Extracted from `renderDenoEntry` when adding the configured-directory literal pushed it past the\n * per-function line budget. A cohesive block — every line is one import of the same package family\n * — so lifting it keeps the budget a signal about the renderer rather than about its preamble.\n */\nconst FRAMEWORK_IMPORTS: readonly string[] = [\n  `// Use npm: specifier so Deno resolves theokit from the user's package.json`,\n  `// equivalent (works in both local 'deno run' and Deno Deploy).`,\n  `import { scanServerRoutes, matchRoute, executeRoute, createProductionLoader, scanWebSocketRoutes, extractTraceIdFromRequest, TRACE_HEADER, createCorsWebHandler } from 'npm:theokit/server'`,\n  `import { createWebShim } from 'npm:theokit/adapters/web-shim'`,\n  `import { buildSecurityHeaders, withSecurityHeaders } from 'npm:theokit/adapters/security-headers'`,\n  `// T3.3 — WS bridge for Deno runtime`,\n  `import { createDenoWsBridge } from 'npm:theokit/adapters/ws-shim'`,\n]\n\nexport function renderDenoEntry(port: number, opts: DeployedEntryOptions = {}): string {\n  const runtimeConfig = deployedRuntimeConfigFragment(opts)\n  const agentsFragment = deployedAgentsFragment(scannedFromLoaderCache(agentsDirLiteral(opts)), {\n    notFound: 'notFound()',\n    importPrefix: 'npm:',\n    // B-185 — bound only when the runtime-config fragment declared the const, which is\n    // exactly when a plugins module was emitted. Referencing it otherwise would emit an\n    // identifier the entry never declares.\n    pluginRunnerExpr:\n      opts.runtimeConfigModule === undefined ? undefined : 'await THEO_PLUGIN_RUNNER',\n  })\n  return [\n    `// Generated by Theo — Deno Deploy Adapter`,\n    `// Deploy: deployctl deploy --project=<name> .theokit/deno/server.ts`,\n    `// Requires Deno >= 1.40 (Deno.serve + npm: specifier support)`,\n    ``,\n    `// Runtime guard`,\n    `if (typeof Deno === 'undefined') {`,\n    `  throw new Error('TheoDenoDeployAdapter must run inside Deno.')`,\n    `}`,\n    ``,\n    ...FRAMEWORK_IMPORTS,\n    ``,\n    `const port = Number(Deno.env.get('PORT') ?? '${port}')`,\n    `const cwd = Deno.cwd()`,\n    `const serverDir = cwd + '/' + ${serverDirLiteral(opts)}`,\n    `let routesCache = null`,\n    `let wsRoutesCache = null`,\n    `let loaderCache = null`,\n    ``,\n    `// #410 — the security baseline \\`theokit start\\` puts on every response,`,\n    `// carried here as a literal because the deployed isolate has no`,\n    `// theo.config.ts to read. Non-API paths 404 here and are served by Deno`,\n    `// Deploy's static asset handler, so this covers the API and not the`,\n    `// document (usetheokit/theokit#412).`,\n    ...deployedEntryPreamble(runtimeConfig, agentsFragment, opts, 'deno-deploy'),\n    ``,\n    `function notFound() {`,\n    `  return new Response(JSON.stringify({ error: { code: 'NOT_FOUND' } }), {`,\n    `    status: 404,`,\n    `    headers: { 'Content-Type': 'application/json' },`,\n    `  })`,\n    `}`,\n    ``,\n    `Deno.serve({ port }, async (request) => {`,\n    `  // T3.3 — Detect WebSocket upgrade and delegate to the Deno bridge.`,\n    `  // A 101 carries no document and no script, so the security baseline does`,\n    `  // not apply to it.`,\n    `  if (request.headers.get('upgrade')?.toLowerCase() === 'websocket') {`,\n    `    if (!wsRoutesCache) wsRoutesCache = scanWebSocketRoutes(serverDir)`,\n    `    if (wsRoutesCache.length === 0) return notFound()`,\n    `    const denoWs = createDenoWsBridge({`,\n    `      onOpen: () => {},`,\n    `      onMessage: (ws, data) => { ws.send(data) },`,\n    `      onClose: () => {},`,\n    `    }, Deno)`,\n    `    return denoWs.handle(request)`,\n    `  }`,\n    ``,\n    `  // #409 — the preflight is answered BEFORE anything routes: an OPTIONS the router`,\n    `  // handles is an OPTIONS the browser never gets a CORS answer to.`,\n    `  const preflight = corsPreflight(request)`,\n    `  if (preflight !== null) return withSecurityHeaders(preflight, SECURITY_HEADERS)`,\n    `  return withCors(request, withSecurityHeaders(await handleRequest(request), SECURITY_HEADERS))`,\n    `})`,\n    ``,\n    `async function handleRequest(request) {`,\n    `  const url = new URL(request.url)`,\n    ``,\n    `  if (!url.pathname.startsWith('/api/')${agentsFragment.hostBypass}) {`,\n    `    // Static + SPA fallback are served by Deno Deploy's static asset handler.`,\n    `    return notFound()`,\n    `  }`,\n    ``,\n    `  if (!routesCache) routesCache = scanServerRoutes(serverDir)`,\n    `  if (!loaderCache) loaderCache = createProductionLoader()`,\n    ``,\n    ...agentsFragment.branch,\n    ``,\n    `  const match = matchRoute(url.pathname, routesCache)`,\n    `  if (!match) return notFound()`,\n    ``,\n    `  const { req, res, toResponse } = createWebShim(request)`,\n    ...deployedTraceFragment('request', '  '),\n    `  const method = request.method.toUpperCase()`,\n    `  // #382 — not awaited: toResponse() settles at the headers and carries a`,\n    `  // live body, so Deno.serve streams while the handler writes.`,\n    `  return toResponse(executeRoute({ route: match.route, method, params: match.params, req, res, loadModule: loaderCache, serverDir, requestId, ...CSRF_CONFIG, ${runtimeConfig.executeRouteSpread} }))`,\n    `}`,\n    ``,\n    `console.log('Theo (Deno Deploy) listening on :' + port)`,\n  ].join('\\n')\n}\n\nexport async function buildDeno(\n  config: TheoConfig,\n  cwd: string,\n  deps: DenoBuildDeps = {},\n  ctx?: AdapterBuildContext,\n): Promise<void> {\n  // Wave 2 (T2.2) — reject polyglot services on this adapter.\n  assertServicesUnsupported('deno-deploy', readManifest(cwd))\n\n  const runNodeBuild = deps.runNodeBuild ?? nodeAdapter.build.bind(nodeAdapter)\n  await runNodeBuild(config, cwd, ctx)\n\n  const outputDir = resolve(cwd, '.theokit/deno')\n  const ensureDir = deps.ensureDir ?? ((p: string) => mkdirSync(p, { recursive: true }))\n  ensureDir(outputDir)\n\n  const pluginsPlan = planDeployedPlugins(config.plugins, denoDeployAdapter.name)\n  const entry = renderDenoEntry(config.port, {\n    securityHeaders: config.security?.headers,\n    csrf: config.security?.csrf,\n    disallowed: config.security?.disallowed,\n    cors: config.security?.cors,\n    // #425 — a selector, not a transformer, so it rides as a literal like the values above.\n    serialization: config.serialization,\n    // #425 — the ONE concern that is not a literal. A closure cannot be baked, so a plugin\n    // declared by module specifier is imported by the emitted module instead; a constructed one\n    // is refused by name at build time rather than dropped in silence.\n    runtimeConfigModule: pluginsPlan?.moduleSpecifier,\n    // #95 — the configured directories, which `build.ts:210` already threads into the Vite\n    // plugins. Without these two lines the literals above fall to their defaults and a project\n    // with a custom dir deploys an entry that resolves a directory it does not have.\n    serverDir: config.serverDir,\n    agentsDir: config.agentsDir,\n  })\n  const write =\n    deps.writeEntry ??\n    ((p, c) => {\n      writeFileSync(p, c)\n    })\n  if (pluginsPlan !== undefined) {\n    // Beside the entry, so the emitted import is a sibling. Written through the same seam as\n    // the entry so a test that captures one captures both (#425).\n    write(resolve(outputDir, 'theo.plugins.mjs'), pluginsPlan.source)\n  }\n  write(resolve(outputDir, 'server.ts'), entry)\n\n  // eslint-disable-next-line no-console -- CLI build progress\n  console.log('\\n  ✓ Deno Deploy output → .theokit/deno/server.ts')\n  // eslint-disable-next-line no-console -- CLI build progress\n  console.log(\n    `${describeDeployedSecurityHeaders({\n      target: 'deno-deploy',\n      securityHeaders: config.security?.headers,\n      mintsNonce: false,\n      documentHeaders: 'platform-unmanaged',\n    })}\\n`,\n  )\n}\n\nexport const denoDeployAdapter: DeployAdapter = {\n  name: 'deno-deploy',\n  streamsResponses: true,\n  // #409 / #410 — the generated entry calls `executeRoute` with routes, loader\n  // and serverDir only. CSRF, route policy, file middleware and Zod validation\n  // still run because they live inside `executeRoute`; none of the remaining\n  // configurable concerns reach it. Declared explicitly rather than omitted so\n  // the gap is a statement in the source and not an absence.\n  //\n  // `securityHeaders` IS applied -- to every response this isolate returns. The\n  // document comes from Deno Deploy's static asset handler and does not pass\n  // through it (usetheokit/theokit#412).\n  servesAgents: true,\n  appliesConfig: ['securityHeaders', 'csrf', 'disallowed', 'cors', 'serialization', 'plugins'],\n  build(config, cwd, ctx) {\n    return buildDeno(config, cwd, {}, ctx)\n  },\n}\n"],"mappings":"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","names":[]}

package/dist/{dev-GLUZNBNH.js → dev-72ISY3BP.js}

@@ -11,19 +11,19 @@ import {
 } from "./chunk-KTMQUYED.js";
 import {
   theoPluginAsync
-} from "./chunk-PRZCPSUE.js";
-import "./chunk-ASBXR57P.js";
+} from "./chunk-I2H6KRCQ.js";
+import "./chunk-4WB62S22.js";
 import "./chunk-BDH5GKFZ.js";
 import "./chunk-3PWQQWT6.js";
 import "./chunk-FDOOBTXJ.js";
-import "./chunk-47MM2JUK.js";
-import "./chunk-B4Z7KIIU.js";
-import "./chunk-UETVDZBE.js";
+import "./chunk-SJ4AW54X.js";
+import "./chunk-BINRCILF.js";
 import "./chunk-QD5X56I3.js";
 import "./chunk-WSMLSIS5.js";
-import "./chunk-5VLP3GQ2.js";
+import "./chunk-MS4A7N77.js";
 import "./chunk-C27VRUVN.js";
 import "./chunk-7UZZHCRN.js";
+import "./chunk-47MM2JUK.js";
 import "./chunk-BCFA6LHL.js";
 import "./chunk-5NNFO7R7.js";
 import "./chunk-NO6HA4FG.js";
@@ -128,4 +128,4 @@ export {
   devCommand,
   startDevServer
 };
-//# sourceMappingURL=dev-GLUZNBNH.js.map
+//# sourceMappingURL=dev-72ISY3BP.js.map

package/dist/{index-BdIaxp0c.d.ts → index-DZ_G5iY2.d.ts}

@@ -3,10 +3,11 @@ import { IncomingMessage, ServerResponse } from 'node:http';
 import { P as PluginContext, W as WebOnRequestHook, g as WebPreHandlerHook, h as WebOnResponseHook, i as WebOnErrorHook } from './plugin-types-BUVfUQ0V.js';
 import { P as PluginRunner } from './plugin-runner-BVMOSxvb.js';
 import { J as JobBackend } from './job-backend-CgC8Xf33.js';
-import { L as LoadModule, S as ServerRouteNode } from './match-Dw4CNXJH.js';
+import { S as ServerRouteNode } from './match-DaKsL73w.js';
+import { L as LoadModule } from './module-loader-DCip7NoL.js';
 import { C as CsrfMode, D as DisallowedConfig } from './csrf-Dgot9qSM.js';
 import { z } from 'zod';
-import { R as RouteConfig } from './route-config-B7FaTSby.js';
+import { a as MiddlewareNext, R as RouteConfig } from './define-middleware-BOHpPOBs.js';
 import './action-protocol-tGm3NKRg.js';
 
 interface ExecuteActionOptions {
@@ -461,6 +462,28 @@ declare function serverErrorToEnvelope(value: unknown): TheoErrorEnvelope;
  */
 declare function envelopeCodeToStatus(code: string): number;
 
+/**
+ * Render `<link rel="modulepreload">` for the chunks a route needs beyond the entry (B-035).
+ *
+ * **The single source of truth, for the Node server AND the Cloudflare worker.**
+ *
+ * An earlier revision of this file asserted that the worker had to carry a COPY because
+ * `theokit`'s package exports declare no subpath reaching `core/`. **That was false, and it was
+ * stated three times** — here, in `adapters/cloudflare.ts`, and in a commit message. `server/
+ * index.ts` already re-exports from `core/contracts/` *"for consumer ergonomics"* in its own
+ * words, `adapters/security-headers.ts` imports `generateNonce` and `buildSecurityHeaders` from
+ * here, and the generated worker imports BOTH of those subpaths. Adding a named export to an
+ * existing barrel touches no `package.json`, so the constraint never existed.
+ *
+ * The copy is gone. `theokit/server` re-exports `injectModulePreloads` and the worker imports it,
+ * which is the shape `adapters/security-headers.ts` established one directory over — and whose
+ * docblock states the reason better than this one could: *"a shape stated in two files drifts"*.
+ * It drifted the same day: the proxy fix below landed in this file and not in the copy.
+ */
+/** A route path mapped to the chunk file names it needs beyond the entry. */
+type AssetsMap = Record<string, string[] | undefined>;
+declare function injectModulePreloads(head: string, assetsMap: AssetsMap | undefined, url: string): string;
+
 /**
  * Canonical error handler for HTTP request pipelines (T3.4 of
  * architecture-review-remediation-plan, PV-9 DRY).
@@ -521,6 +544,32 @@ interface MiddlewareResult {
     aborted: boolean;
 }
 declare function _resetMiddlewareCacheForTests(): void;
+/**
+ * Run a Web-shaped middleware — the one `middleware()` and `defineMiddleware()` produce (#345).
+ *
+ * This used to REFUSE the shape by name, because the runner could only invoke `(req, res, next)`
+ * and calling a Web handler that way hands it `res` as its `next`. Refusing was better than the
+ * blank response it replaced, and it was never the end state: the README documented the builder as
+ * the way to write middleware, so the documented path was loud instead of silent, but still broken.
+ *
+ * It runs now because the published contract became the one that fits this model:
+ * `(request, context) => Response | void`. No continuation is needed — returning a `Response`
+ * answers the request, returning nothing continues — which is exactly what a runner that executes
+ * BEFORE routing can honestly offer.
+ *
+ * The `Request` is built by the same converter the agent and action branches use, so a middleware
+ * reads the request the way every other Web-shaped surface in the framework does.
+ */
+/**
+ * Raised when a `server/middleware/*.ts` middleware awaits `next`.
+ *
+ * Typed rather than a bare `Error` so a caller can tell this apart from a failure inside the
+ * middleware's own body — `rules/error-handling.md` § 2, and the same shape as
+ * `http/in-process-caller.ts`'s three.
+ */
+declare class MiddlewareNextUnavailableError extends Error {
+    constructor();
+}
 declare function runMiddlewareAndContext(req: IncomingMessage, res: ServerResponse, loadModule: LoadModule, serverDir: string): Promise<MiddlewareResult>;
 /**
  * Run ONLY the application's `server/context.ts` factory and return what it produced.
@@ -647,8 +696,30 @@ declare function serveStaticFile(req: IncomingMessage, res: ServerResponse, clie
  * Full semantic parity with the Node `defineMiddleware` contract is part of the
  * deferred Node→Web pipeline convergence, not this slice.
  */
-/** A Web-path middleware: mutate `context`, or return a `Response` to short-circuit. */
-type WebMiddleware = (request: Request, context: Record<string, unknown>) => Promise<Response | undefined> | Response | undefined | void;
+
+/**
+ * Run the rest of the chain and resolve to what it produced.
+ *
+ * An ALIAS, not a second declaration. The two lived as separate structurally
+ * identical types before this change and were measured on 2026-09-19 to be
+ * incompatible the moment either moved — `MiddlewareHandler` admits
+ * `Promise<void>` and `WebMiddleware` did not, so the builder's output was not
+ * assignable to the runner's parameter and `tsc` said so in SEVERAL errors that no
+ * test could see. (This said "15" until review: control gives 0, an isolated revert 3, a full
+ * revert 14, and no reconstruction gives 15 — it was measured on an uncommitted tree and
+ * published as a measurement. The mechanism holds; the figure did not, and a figure in a code
+ * comment outlives the CHANGELOG entry that carried the same one.) Two names for one contract is how that happens.
+ */
+type WebNext = MiddlewareNext;
+/**
+ * A Web-path middleware: mutate `context`, return a `Response`, or call `next`.
+ *
+ * `next` is OPTIONAL in the parameter list so every middleware written against
+ * the two-parameter shape keeps compiling and keeps behaving identically — see
+ * `docs/adr/0006` clause 5, which rests that claim on a measured call site
+ * rather than on confidence.
+ */
+type WebMiddleware = (request: Request, context: Record<string, unknown>, next: WebNext) => Response | undefined | void | Promise<Response | undefined | void>;
 
 /**
  * The route module exported by a `server/routes/*.ts` file (after T2.6 G6
@@ -907,4 +978,4 @@ interface OpenApiDocsOptions {
  */
 declare function createOpenApiHandler(opts?: OpenApiDocsOptions): (request: Request) => Response | null;
 
-export { extractTraceIdFromRequest as $, appendDeleteCookieToHeaders as A, BATCH_PATH as B, type CookieOptions as C, callProcedure as D, type ExecuteActionOptions as E, FileTooLargeError as F, createCorsHandler as G, type HandleBatchOptions as H, createCorsWebHandler as I, createOpenApiHandler as J, createServerContext as K, deleteCookie as L, MAX_ERROR_HTML_BYTES as M, NotFoundError as N, type OpenApiDocsOptions as O, type ParsedBody as P, envelopeCodeToStatus as Q, type RawRouteInput as R, STRIPPED_HEADERS as S, TRACE_HEADER as T, type UploadedFile as U, executeAction as V, type W3CTraceContext as W, executeRoute as X, executeWebRequest as Y, extractTraceId as Z, _resetMiddlewareCacheForTests as _, type BatchExecuteFn as a, extractW3CTraceContext as a0, fromUnknown as a1, getCookie as a2, getCookieFromRequest as a3, handleBatchRequest as a4, handleRequestError as a5, handleWebRequestError as a6, jsonTransformer as a7, loadCustomErrorPages as a8, matchesOrigin as a9, parseCookieHeader as aa, parseRequestBody as ab, parseTraceparent as ac, parseTraceparentContext as ad, resolveTransformer as ae, runMiddlewareAndContext as af, sendError as ag, sendJson as ah, serializeCookie as ai, serveStaticFile as aj, serverErrorToEnvelope as ak, setCookie as al, superjsonTransformer as am, validateRouteInput as an, BatchPathConflictError as b, type BatchPayload as c, type BatchRequestItem as d, type BatchResponse as e, type BatchResultItem as f, type BodyParserOptions as g, type CorsConfig as h, type CorsHandler as i, type CorsOrigin as j, type CorsWebHandler as k, type CustomErrorPages as l, type ExecuteRouteContext as m, type MiddlewareResult as n, type ProcedureInput as o, ProcedureInputError as p, ProcedureOutputError as q, type RouteInputChannel as r, type RouteInputSchemas as s, type RouteInputValidation as t, type SendErrorInput as u, type SendErrorOptions as v, TRACE_PARENT_HEADER as w, TheoError as x, type TheoTransformer as y, appendCookieToHeaders as z };
+export { extractTraceId as $, appendCookieToHeaders as A, BATCH_PATH as B, type CookieOptions as C, appendDeleteCookieToHeaders as D, type ExecuteActionOptions as E, FileTooLargeError as F, callProcedure as G, type HandleBatchOptions as H, createCorsHandler as I, createCorsWebHandler as J, createOpenApiHandler as K, createServerContext as L, MAX_ERROR_HTML_BYTES as M, NotFoundError as N, type OpenApiDocsOptions as O, type ParsedBody as P, deleteCookie as Q, type RawRouteInput as R, STRIPPED_HEADERS as S, TRACE_HEADER as T, type UploadedFile as U, envelopeCodeToStatus as V, type W3CTraceContext as W, executeAction as X, executeRoute as Y, executeWebRequest as Z, _resetMiddlewareCacheForTests as _, type BatchExecuteFn as a, extractTraceIdFromRequest as a0, extractW3CTraceContext as a1, fromUnknown as a2, getCookie as a3, getCookieFromRequest as a4, handleBatchRequest as a5, handleRequestError as a6, handleWebRequestError as a7, injectModulePreloads as a8, jsonTransformer as a9, loadCustomErrorPages as aa, matchesOrigin as ab, parseCookieHeader as ac, parseRequestBody as ad, parseTraceparent as ae, parseTraceparentContext as af, resolveTransformer as ag, runMiddlewareAndContext as ah, sendError as ai, sendJson as aj, serializeCookie as ak, serveStaticFile as al, serverErrorToEnvelope as am, setCookie as an, superjsonTransformer as ao, validateRouteInput as ap, BatchPathConflictError as b, type BatchPayload as c, type BatchRequestItem as d, type BatchResponse as e, type BatchResultItem as f, type BodyParserOptions as g, type CorsConfig as h, type CorsHandler as i, type CorsOrigin as j, type CorsWebHandler as k, type CustomErrorPages as l, type ExecuteRouteContext as m, MiddlewareNextUnavailableError as n, type MiddlewareResult as o, type ProcedureInput as p, ProcedureInputError as q, ProcedureOutputError as r, type RouteInputChannel as s, type RouteInputSchemas as t, type RouteInputValidation as u, type SendErrorInput as v, type SendErrorOptions as w, TRACE_PARENT_HEADER as x, TheoError as y, type TheoTransformer as z };

package/dist/index.js

@@ -8,21 +8,22 @@ import {
   scanRoutes,
   theoConfigSchema,
   theoPlugin
-} from "./chunk-YNK7DW5V.js";
+} from "./chunk-QVXMAHZC.js";
 import "./chunk-7NRFZBAL.js";
 import "./chunk-SSYDEKWF.js";
-import "./chunk-WAYUHS54.js";
-import "./chunk-GAJOZJWD.js";
+import "./chunk-425FJKKO.js";
+import "./chunk-BDPD5HEO.js";
+import "./chunk-MOGTMGGA.js";
 import "./chunk-OIGJOYX6.js";
 import "./chunk-U3SPBLJF.js";
 import "./chunk-WSOAN4KN.js";
 import "./chunk-ENSFCKP6.js";
 import "./chunk-OGLS76RN.js";
-import "./chunk-5AGNZXHJ.js";
+import "./chunk-SRJBH5E5.js";
+import "./chunk-3T5XLDOH.js";
 import "./chunk-P6OS7652.js";
 import "./chunk-ZDUO4IYN.js";
-import "./chunk-D4VP2QPR.js";
-import "./chunk-ENRT6DAU.js";
+import "./chunk-IDWN2OSG.js";
 import "./chunk-47FFT43U.js";
 import "./chunk-NTDN54XO.js";
 import "./chunk-PVNMLZ5G.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/config/define-config.ts","../src/config/config-builder.ts","../src/config/validate-structure.ts","../src/core/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOO,SAAS,aAAaA,SAAkD;AAC7E,SAAOA;AACT;;;ACuCA,SAAS,kBAAkB,MAA0C;AACnE,QAAM,QAAQ,CAAC,UACb,kBAAkB,EAAE,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,SAAO;AAAA,IACL,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,WAAW,CAAC,UAAU,MAAM,EAAE,WAAW,MAAM,CAAC;AAAA,IAChD,QAAQ,CAAC,UAAU,MAAM,EAAE,QAAQ,MAAM,CAAC;AAAA,IAC1C,WAAW,CAAC,UAAU,MAAM,EAAE,WAAW,MAAM,CAAC;AAAA,IAChD,SAAS,CAAC,UAAU,MAAM,EAAE,SAAS,MAAM,CAAC;AAAA,IAC5C,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,cAAc,CAAC,UAAU,MAAM,EAAE,cAAc,MAAM,CAAC;AAAA,IACtD,KAAK,CAAC,UAAU,MAAM,EAAE,KAAK,MAAM,CAAC;AAAA,IACpC,KAAK,CAAC,YAAY,MAAM,OAAO;AAAA,IAC/B,OAAO,MAAM,aAAa,IAAI;AAAA,EAChC;AACF;AAKO,SAAS,SAAwB;AACtC,SAAO,kBAAkB,CAAC,CAAC;AAC7B;;;ACnEA,SAAS,kBAAkB;AAC3B,SAAS,YAAY;;;ACLd,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1B;AAAA,EACA;AAAA,EAEhB,YAAY,QAAkB,SAAiB;AAC7C,UAAM,aAAa,OAAO,IAAI,CAAC,MAAM,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI;AAE1D;AAAA,MACE;AAAA;AAAA,UACa,OAAO;AAAA;AAAA,KACjB,aAAa;AAAA,EAAc,UAAU;AAAA,IAAO;AAAA,IACjD;AAEA,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,UAAU;AAAA,EACjB;AACF;;;ADHA,IAAM,iBAAmC;AAAA,EACvC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAIO,SAAS,yBAAyB,SAAiB,SAAS,OAAa;AAC9E,MAAI,CAAC,WAAW,OAAO,GAAG;AACxB,UAAM,IAAI,iBAAiB,CAAC,qCAAqC,OAAO,EAAE,GAAG,OAAO;AAAA,EACtF;AAEA,QAAM,SAAmB,CAAC;AAE1B,QAAM,eAAiC;AAAA,IACrC,EAAE,MAAM,QAAQ,cAAc,+BAA+B,MAAM,IAAI;AAAA,EACzE;AAEA,aAAW,QAAQ,cAAc;AAC/B,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,aAAW,QAAQ,gBAAgB;AACjC,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,IAAI,iBAAiB,QAAQ,OAAO;AAAA,EAC5C;AACF;","names":["config"]}
+{"version":3,"sources":["../src/config/define-config.ts","../src/config/config-builder.ts","../src/config/validate-structure.ts","../src/core/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOO,SAAS,aAAaA,SAAkD;AAC7E,SAAOA;AACT;;;ACuCA,SAAS,kBAAkB,MAA0C;AACnE,QAAM,QAAQ,CAAC,UACb,kBAAkB,EAAE,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,SAAO;AAAA,IACL,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,WAAW,CAAC,UAAU,MAAM,EAAE,WAAW,MAAM,CAAC;AAAA,IAChD,QAAQ,CAAC,UAAU,MAAM,EAAE,QAAQ,MAAM,CAAC;AAAA,IAC1C,WAAW,CAAC,UAAU,MAAM,EAAE,WAAW,MAAM,CAAC;AAAA,IAChD,SAAS,CAAC,UAAU,MAAM,EAAE,SAAS,MAAM,CAAC;AAAA,IAC5C,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,cAAc,CAAC,UAAU,MAAM,EAAE,cAAc,MAAM,CAAC;AAAA,IACtD,KAAK,CAAC,UAAU,MAAM,EAAE,KAAK,MAAM,CAAC;AAAA,IACpC,KAAK,CAAC,YAAY,MAAM,OAAO;AAAA,IAC/B,OAAO,MAAM,aAAa,IAAI;AAAA,EAChC;AACF;AAKO,SAAS,SAAwB;AACtC,SAAO,kBAAkB,CAAC,CAAC;AAC7B;;;ACnEA,SAAS,kBAAkB;AAC3B,SAAS,YAAY;;;ACLd,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1B;AAAA,EACA;AAAA,EAEhB,YAAY,QAAkB,SAAiB;AAC7C,UAAM,aAAa,OAAO,IAAI,CAAC,MAAM,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI;AAE1D;AAAA,MACE;AAAA;AAAA,UACa,OAAO;AAAA;AAAA,KACjB,aAAa;AAAA,EAAc,UAAU;AAAA,IAAO;AAAA,IACjD;AAEA,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,UAAU;AAAA,EACjB;AACF;;;ADHA,IAAM,iBAAmC;AAAA,EACvC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAIO,SAAS,yBAAyB,SAAiB,SAAS,OAAa;AAC9E,MAAI,CAAC,WAAW,OAAO,GAAG;AACxB,UAAM,IAAI,iBAAiB,CAAC,qCAAqC,OAAO,EAAE,GAAG,OAAO;AAAA,EACtF;AAEA,QAAM,SAAmB,CAAC;AAE1B,QAAM,eAAiC;AAAA,IACrC,EAAE,MAAM,QAAQ,cAAc,+BAA+B,MAAM,IAAI;AAAA,EACzE;AAEA,aAAW,QAAQ,cAAc;AAC/B,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,aAAW,QAAQ,gBAAgB;AACjC,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,IAAI,iBAAiB,QAAQ,OAAO;AAAA,EAC5C;AACF;","names":["config"]}

package/dist/{internal-api-3JIWUI3V.js → internal-api-CEZSXGRB.js}

@@ -16,10 +16,10 @@ import {
   handleCspReport,
   handleCsrfReadiness,
   mountAgent
-} from "./chunk-B4Z7KIIU.js";
+} from "./chunk-SJ4AW54X.js";
 import {
   resolveProvider
-} from "./chunk-UETVDZBE.js";
+} from "./chunk-BINRCILF.js";
 import {
   dispatchControllerRequest,
   incomingMessageToHandlerRequest,
@@ -31,7 +31,7 @@ import {
 import {
   TRACE_HEADER,
   extractTraceId
-} from "./chunk-5VLP3GQ2.js";
+} from "./chunk-MS4A7N77.js";
 import {
   logRequest
 } from "./chunk-C27VRUVN.js";
@@ -87,4 +87,4 @@ export {
   scanWebSocketRoutes,
   sendError
 };
-//# sourceMappingURL=internal-api-3JIWUI3V.js.map
+//# sourceMappingURL=internal-api-CEZSXGRB.js.map

package/dist/{internal-api-OK7FS2ZF.js → internal-api-XRIBUACB.js}

@@ -1,9 +1,9 @@
 import {
   dispatchControllerRequest
-} from "./chunk-WAYUHS54.js";
+} from "./chunk-425FJKKO.js";
 import {
   mountAgent
-} from "./chunk-GAJOZJWD.js";
+} from "./chunk-MOGTMGGA.js";
 import {
   CSP_REPORT_PATH,
   CsrfReadinessStore,
@@ -17,14 +17,15 @@ import {
   createCorsHandler,
   executeAction,
   executeRoute,
-  handleBatchRequest,
+  handleBatchRequest
+} from "./chunk-SRJBH5E5.js";
+import {
   incomingMessageToHandlerRequest,
   sendError
-} from "./chunk-5AGNZXHJ.js";
+} from "./chunk-3T5XLDOH.js";
 import "./chunk-P6OS7652.js";
 import "./chunk-ZDUO4IYN.js";
-import "./chunk-D4VP2QPR.js";
-import "./chunk-ENRT6DAU.js";
+import "./chunk-IDWN2OSG.js";
 import "./chunk-47FFT43U.js";
 import {
   findSuggestion
@@ -107,4 +108,4 @@ export {
   scanWebSocketRoutes,
   sendError
 };
-//# sourceMappingURL=internal-api-OK7FS2ZF.js.map
+//# sourceMappingURL=internal-api-XRIBUACB.js.map

package/dist/match-DaKsL73w.d.ts

@@ -0,0 +1,28 @@
+interface ServerRouteNode {
+    filePath: string;
+    routePath: string;
+    paramNames: string[];
+    pattern: RegExp;
+    /** HTTP methods (uppercase) the route file exports. Optional for backward
+     * compatibility with manifests generated before G1. Empty array means the
+     * file has no HTTP exports (util-only); undefined means "not detected". */
+    methods?: string[];
+    /**
+     * The subset of `methods` whose policy is the literal `'public'` (ADR 0001).
+     *
+     * `undefined` means "not detected" — a manifest built before the field existed — and is NOT the
+     * same as `[]`, which means "detected, and nothing is public". `public-exposure-gate.ts` depends
+     * on that distinction: reading absence as safety is the failure it exists to prevent.
+     */
+    publicMethods?: string[];
+}
+declare function compilePattern(routePath: string): {
+    pattern: RegExp;
+    paramNames: string[];
+};
+declare function matchRoute(url: string, routes: ServerRouteNode[]): {
+    route: ServerRouteNode;
+    params: Record<string, string>;
+} | null;
+
+export { type ServerRouteNode as S, compilePattern as c, matchRoute as m };

package/dist/{mcp-IPDFRK4S.js → mcp-S2AOB3RE.js}

@@ -2,12 +2,12 @@
 import "tsx/esm";
 import {
   createAgentSsrLoader
-} from "./chunk-UKMOQWUC.js";
+} from "./chunk-TJPENLGQ.js";
 import {
   extractAppResources,
   handleMcpJsonRpc
 } from "./chunk-BDH5GKFZ.js";
-import "./chunk-UETVDZBE.js";
+import "./chunk-BINRCILF.js";
 import {
   scanAgents
 } from "./chunk-5NNFO7R7.js";
@@ -75,4 +75,4 @@ async function mcpCommand(name, deps = {}) {
 export {
   mcpCommand
 };
-//# sourceMappingURL=mcp-IPDFRK4S.js.map
+//# sourceMappingURL=mcp-S2AOB3RE.js.map