theokit 0.48.13 → 0.50.0

package/dist/{chunk-YRBR424R.js → chunk-OAUI273L.js}

@@ -1,36 +1,29 @@
 #!/usr/bin/env node
 import "tsx/esm";
 import {
+  createAgentSubjectResolver,
   handleAgentApproval,
   isAgentCardPath,
   isApprovalPath,
-  isListApprovalsPath,
+  matchAgentAuxRoute,
+  parseApprovalAgentName,
+  resolvePluginSpecifiers,
   resolveTransformer,
-  serveAgentAuxRoute,
-  setupSsrDevMiddleware,
-  writeWebResponseToServerResponse
-} from "./chunk-GRI4XHBJ.js";
+  serveMatchedAuxRoute,
+  serveThroughPluginLifecycle,
+  setupSsrDevMiddleware
+} from "./chunk-JWRCZIA4.js";
 import {
-  isMcpPath
-} from "./chunk-2CVV6CNN.js";
+  resolveTheoRootDir
+} from "./chunk-FDOOBTXJ.js";
 import {
   isRouteFile,
   scanRoutes
-} from "./chunk-IEES3CHD.js";
-import {
-  loadConfig
-} from "./chunk-S433N3CT.js";
-import {
-  buildServicesProxyConfig
-} from "./chunk-7VPQHEAJ.js";
-import {
-  broadcastToDevtools
-} from "./chunk-5ODOE6EF.js";
+} from "./chunk-47MM2JUK.js";
 import {
   BATCH_PATH,
   CSP_REPORT_PATH,
   CsrfReadinessStore,
-  TRACE_HEADER,
   applySecurityHeaders,
   createCorsHandler,
   createPluginRunnerFromConfig,
@@ -38,37 +31,54 @@ import {
   createViteLoader,
   executeAction,
   executeRoute,
-  extractTraceId,
   findSuggestion,
   handleBatchRequest,
   handleCspReport,
   handleCsrfReadiness,
-  mountAgent
-} from "./chunk-BIVCP6X5.js";
+  mountAgent,
+  readAgentPolicy,
+  writeWebResponseToServerResponse
+} from "./chunk-C62IZEJI.js";
 import {
   getApprovalRegistry,
   resolveProvider
-} from "./chunk-6GGWS7J3.js";
+} from "./chunk-5YPXXSYY.js";
 import {
+  createWebRequestSource,
   dispatchControllerRequest,
   incomingMessageToHandlerRequest,
-  incomingMessageToWebRequest,
-  logRequest,
   sendError
-} from "./chunk-T5C46IIU.js";
+} from "./chunk-HWBRS4DZ.js";
+import {
+  TRACE_HEADER,
+  createObservabilityPluginFromConfig,
+  extractTraceId
+} from "./chunk-7PM6K5EV.js";
+import {
+  logRequest
+} from "./chunk-2AMLGJJA.js";
 import {
   scanAgents
-} from "./chunk-LNVMHQ2Z.js";
+} from "./chunk-EVZKNA2W.js";
 import {
   matchRoute,
   scanServerActions,
   scanServerRoutes,
   scanWebSocketRoutes
-} from "./chunk-BMHS4WAN.js";
+} from "./chunk-XS7EX55U.js";
+import {
+  loadConfig
+} from "./chunk-QTHVHNJJ.js";
+import {
+  buildServicesProxyConfig
+} from "./chunk-ZNZISJDZ.js";
+import {
+  broadcastToDevtools
+} from "./chunk-5ODOE6EF.js";
 
 // src/vite-plugin/index.ts
-import { existsSync as existsSync7 } from "fs";
-import { resolve as resolve6, dirname as dirname4 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { resolve as resolve5, dirname as dirname4 } from "path";
 import { fileURLToPath } from "url";
 
 // src/vite-plugin/config-hook.ts
@@ -113,42 +123,56 @@ function runConfigHook(ctx) {
     },
     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}`) },
+        // Order still matters — first match wins — but the entries below are
+        // EXACT (#377). A Vite alias whose `find` is a string matches by prefix,
+        // and every replacement here points at a FILE, so the old string form
+        // rewrote `theokit/client/core` into `…/client/index.ts/core` and the
+        // build died with ENOTDIR. It did that for every subpath nobody had
+        // listed, which made the failure open-ended rather than a typo.
+        { find: /^theokit\/server$/u, replacement: resolve(ctx.theoSrcDir, `server/index${ext}`) },
+        { find: /^theokit\/client$/u, 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",
+          find: /^theokit\/react-query$/u,
           replacement: resolve(ctx.theoSrcDir, `client/react-query${ext}`)
         },
         {
-          find: "theokit/vite-plugin",
+          find: /^theokit\/vite-plugin$/u,
           replacement: resolve(ctx.theoSrcDir, `vite-plugin/index${ext}`)
         },
         {
-          find: "theokit/adapters/web-shim",
+          find: /^theokit\/adapters\/web-shim$/u,
           replacement: resolve(ctx.theoSrcDir, `adapters/web-shim${ext}`)
         },
         {
-          find: "theokit/adapters/ws-shim",
+          find: /^theokit\/adapters\/ws-shim$/u,
           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",
+          find: /^theokit\/devtools\/entry$/u,
           replacement: resolve(
             ctx.theoSrcDir,
             ext === ".ts" ? "devtools/dom/entry.tsx" : "devtools/entry.js"
           )
         },
-        { find: "theokit", replacement: resolve(ctx.theoSrcDir, `index${ext}`) }
+        // Everything else under the package, by one rule rather than a list that
+        // has to grow with the exports map. The source layout mirrors the
+        // subpath, so `theokit/cache` is `<src>/cache` and Vite's own extension
+        // resolution finds the file. The two entries above that do NOT mirror it
+        // — react-query moved to a sibling, devtools' source carries a `/dom/`
+        // segment the dist flattens — are matched before this and keep their
+        // mapping.
+        { find: /^theokit\/(.+)$/u, replacement: resolve(ctx.theoSrcDir, "$1") },
+        // Exact, so a package merely NAMED like ours — `theokit-anything` — is
+        // left alone. The prefix form ate those too.
+        { find: /^theokit$/u, replacement: resolve(ctx.theoSrcDir, `index${ext}`) }
       ]
     }
   };
@@ -253,7 +277,14 @@ var DEFAULT_RESOLVED = {
 async function resolvePluginConfig(projectRoot) {
   try {
     const userConfig = await loadConfig(projectRoot);
-    const pluginRunner = await createPluginRunnerFromConfig(userConfig.plugins);
+    const observabilityPlugin = createObservabilityPluginFromConfig(
+      userConfig.observability,
+      process.env
+    );
+    const declaredPlugins = await resolvePluginSpecifiers(userConfig.plugins ?? [], projectRoot);
+    const pluginRunner = await createPluginRunnerFromConfig(
+      observabilityPlugin === void 0 ? declaredPlugins : [observabilityPlugin, ...declaredPlugins]
+    );
     const transformer = resolveTransformer(userConfig.serialization);
     let resolvedBatching;
     if (userConfig.batching === true) {
@@ -409,7 +440,7 @@ function createActionMiddleware(vite, serverDir, options) {
 // src/vite-plugin/agent-middleware.ts
 import { randomUUID as randomUUID2 } from "crypto";
 var PREFIX2 = "/api/agents/";
-async function serveApprove(req, res, urlPath, csrfMode, log) {
+async function serveApprove(req, res, urlPath, deps, log) {
   const method = (req.method ?? "POST").toUpperCase();
   if (method !== "POST") {
     sendError(
@@ -429,24 +460,36 @@ async function serveApprove(req, res, urlPath, csrfMode, log) {
     });
     return;
   }
-  try {
-    const response = await handleAgentApproval(
-      incomingMessageToWebRequest(req),
-      urlPath,
-      getApprovalRegistry(),
-      csrfMode
-    );
-    await writeWebResponseToServerResponse(response, res);
-  } catch (err) {
-    sendError(
+  await serveThroughPluginLifecycle(
+    {
+      source: createWebRequestSource(req),
       res,
-      "INTERNAL",
-      err instanceof Error ? err.message : "Approve handler failed",
-      500,
-      void 0,
-      log.requestId
-    );
-  }
+      requestId: log.requestId,
+      pluginRunner: deps.pluginRunner,
+      failureMessage: "Approve handler failed"
+    },
+    async (request) => {
+      const agent = scanAgents(deps.projectRoot, deps.agentsDir).find(
+        (a) => a.name === parseApprovalAgentName(urlPath)
+      );
+      const resolveSubject = createAgentSubjectResolver({
+        req,
+        res,
+        loadModule: deps.loadModule,
+        serverDir: deps.serverDir,
+        pluginRunner: deps.pluginRunner
+      });
+      const policy = agent === void 0 ? void 0 : readAgentPolicy(await deps.loadModule(agent.filePath), agent.filePath);
+      const response = await handleAgentApproval(
+        request,
+        urlPath,
+        getApprovalRegistry(),
+        deps.csrfMode,
+        { policy, resolveSubject }
+      );
+      await writeWebResponseToServerResponse(response, res);
+    }
+  );
   logRequest({
     method,
     url: req.url ?? "",
@@ -458,53 +501,69 @@ async function serveApprove(req, res, urlPath, csrfMode, log) {
 async function serveAux(req, res, next, urlPath, deps) {
   const requestId = randomUUID2();
   const start = Date.now();
-  try {
-    const request = incomingMessageToWebRequest(req);
-    const response = await serveAgentAuxRoute(request, urlPath, {
-      agents: scanAgents(deps.projectRoot, deps.agentsDir),
-      loadModule: deps.loadModule,
-      baseUrl: `http://${req.headers.host ?? "localhost"}`,
-      csrfMode: deps.csrfMode,
-      // M39 — the thread follow-up route drives the agent; resolve the key on demand.
-      resolveApiKey: () => resolveProvider().apiKey
-    });
-    if (response === null) {
-      next();
-      return;
-    }
-    res.setHeader("x-request-id", requestId);
-    await writeWebResponseToServerResponse(response, res);
-  } catch (err) {
-    res.setHeader("x-request-id", requestId);
-    sendError(
+  const auxDeps = {
+    agents: scanAgents(deps.projectRoot, deps.agentsDir),
+    loadModule: deps.loadModule,
+    baseUrl: `http://${req.headers.host ?? "localhost"}`,
+    csrfMode: deps.csrfMode,
+    // M39 — the thread follow-up route drives the agent; resolve the key on demand.
+    // theokit#328 — the thread route drives an agent, so its key follows the model too.
+    resolveApiKey: (model) => resolveProvider(model).apiKey,
+    // usetheokit/theokit#365 — parity with `theokit start`; lazy for the same reason.
+    resolveSubject: createAgentSubjectResolver({
+      req,
       res,
-      "INTERNAL",
-      err instanceof Error ? err.message : "Agent aux handler failed",
-      500,
-      void 0,
-      requestId
-    );
+      loadModule: deps.loadModule,
+      serverDir: deps.serverDir,
+      pluginRunner: deps.pluginRunner
+    })
+  };
+  const method = (req.method ?? "GET").toUpperCase();
+  const route = await matchAgentAuxRoute(method, urlPath, auxDeps);
+  if (route === null) {
+    next();
+    return;
   }
+  res.setHeader("x-request-id", requestId);
+  await serveThroughPluginLifecycle(
+    {
+      source: createWebRequestSource(req),
+      res,
+      requestId,
+      pluginRunner: deps.pluginRunner,
+      failureMessage: "Agent aux handler failed"
+    },
+    async (request) => {
+      await writeWebResponseToServerResponse(
+        await serveMatchedAuxRoute(route, request, auxDeps),
+        res
+      );
+    }
+  );
   logRequest({
-    method: (req.method ?? "GET").toUpperCase(),
+    method,
     url: req.url ?? "",
     status: res.statusCode,
     duration: Date.now() - start,
     requestId
   });
 }
-function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir = "agents") {
+function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir = "agents", deps = {}) {
+  const { pluginRunner, serverDir } = deps;
   const loadModule = createViteLoader(vite);
+  const cardDeps = () => ({
+    projectRoot,
+    loadModule,
+    agentsDir,
+    csrfMode,
+    serverDir,
+    pluginRunner
+  });
   return (req, res, next) => {
     void (async () => {
       const url = req.url ?? "";
       if (isAgentCardPath(url.split("?")[0]) !== null) {
-        await serveAux(req, res, next, url.split("?")[0], {
-          projectRoot,
-          loadModule,
-          agentsDir,
-          csrfMode
-        });
+        await serveAux(req, res, next, url.split("?")[0], cardDeps());
         return;
       }
       if (!url.startsWith(PREFIX2)) {
@@ -516,16 +575,12 @@ function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir
       res.setHeader("x-request-id", requestId);
       const urlPath = url.split("?")[0];
       if (isApprovalPath(urlPath)) {
-        await serveApprove(req, res, urlPath, csrfMode, { requestId, start });
-        return;
-      }
-      if (isListApprovalsPath(urlPath) !== null || isMcpPath(urlPath) !== null) {
-        await serveAux(req, res, next, urlPath, { projectRoot, loadModule, agentsDir, csrfMode });
+        await serveApprove(req, res, urlPath, cardDeps(), { requestId, start });
         return;
       }
       const agent = scanAgents(projectRoot, agentsDir).find((a) => a.agentPath === urlPath);
       if (!agent) {
-        next();
+        await serveAux(req, res, next, urlPath, cardDeps());
         return;
       }
       const method = (req.method ?? "POST").toUpperCase();
@@ -541,30 +596,70 @@ function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir
         logRequest({ method, url, status: 405, duration: Date.now() - start, requestId });
         return;
       }
-      try {
-        const mod = await loadModule(agent.filePath);
-        const apiKey = resolveProvider().apiKey;
-        const request = incomingMessageToWebRequest(req);
-        const response = await mountAgent(mod, request, apiKey, {
-          source: agent.filePath,
-          csrfMode,
-          projectRoot
-        });
-        await writeWebResponseToServerResponse(response, res);
-      } catch (err) {
-        sendError(
-          res,
-          "INTERNAL",
-          err instanceof Error ? err.message : "Agent handler failed",
-          500,
-          void 0,
-          requestId
-        );
-      }
-      logRequest({ method, url, status: res.statusCode, duration: Date.now() - start, requestId });
+      await serveAgentTurn({
+        req,
+        res,
+        agent,
+        method,
+        url,
+        requestId,
+        start,
+        loadModule,
+        csrfMode,
+        projectRoot,
+        pluginRunner,
+        serverDir
+      });
     })();
   };
 }
+async function serveAgentTurn(t) {
+  const {
+    req,
+    res,
+    agent,
+    method,
+    url,
+    requestId,
+    start,
+    loadModule,
+    csrfMode,
+    projectRoot,
+    pluginRunner,
+    serverDir
+  } = t;
+  const resolveSubject = createAgentSubjectResolver({
+    req,
+    res,
+    loadModule,
+    serverDir,
+    pluginRunner
+  });
+  await serveThroughPluginLifecycle(
+    {
+      source: createWebRequestSource(req),
+      res,
+      requestId,
+      pluginRunner,
+      failureMessage: "Agent handler failed"
+    },
+    async (request) => {
+      const mod = await loadModule(agent.filePath);
+      const apiKey = (model) => resolveProvider(model).apiKey;
+      const response = await mountAgent(mod, request, apiKey, {
+        source: agent.filePath,
+        csrfMode,
+        projectRoot,
+        // usetheokit/theokit#365 — the policy comes off `mod`; the caller owes the identity.
+        // usetheokit/theokit#406 — and the same name labels the run's spans.
+        agentName: agent.name,
+        resolveSubject
+      });
+      await writeWebResponseToServerResponse(response, res);
+    }
+  );
+  logRequest({ method, url, status: res.statusCode, duration: Date.now() - start, requestId });
+}
 
 // src/vite-plugin/api-middleware.ts
 import { resolve as resolve2 } from "path";
@@ -615,10 +710,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((resolve6, reject) => {
       req.on("data", (c) => chunks.push(c));
       req.on("end", () => {
-        resolve7();
+        resolve6();
       });
       req.on("error", reject);
     });
@@ -683,7 +778,18 @@ async function tryControllerFallthrough(ctx) {
     requestId: ctx.requestId,
     // M47 — serve @Expose-bound agent routes via the ONE runtime (mountAgent). CSRF is already enforced
     // once at the controller-dispatch boundary (G5), so mountAgent runs with csrfMode 'off' (no double gate).
-    serveAgent: (agent, request) => mountAgent(agent, request, resolveProvider().apiKey, { source: "expose", csrfMode: "off" })
+    //
+    // usetheokit/theokit#365 gated the CONVENTION endpoints (`agents/<name>.ts`) and deliberately
+    // left this one to the decorator stack: an `@Expose` route is a controller method, so its
+    // access decision is the controller's `@Guard` chain, which the dispatcher already runs before
+    // it gets here. Passing a policy as well would give this one surface two authorization
+    // mechanisms and no rule for which wins. What is NOT solved by that: an `@Expose`d agent shares
+    // the conversation store with the convention endpoints, so a guard that admits a caller admits
+    // them to whatever `sessionId` the body names — see the advisory.
+    serveAgent: (agent, request) => mountAgent(agent, request, (model) => resolveProvider(model).apiKey, {
+      source: "expose",
+      csrfMode: "off"
+    })
   });
   if (!handled) return false;
   logRequest(
@@ -870,7 +976,12 @@ async function runConfigureServer(server, ctx) {
     })
   );
   server.middlewares.use(
-    createAgentMiddleware(server, ctx.projectRoot, ctx.csrfMode, ctx.agentsDir)
+    createAgentMiddleware(server, ctx.projectRoot, ctx.csrfMode, ctx.agentsDir, {
+      pluginRunner: ctx.pluginRunner,
+      // usetheokit/theokit#365 — the same backend root the route middleware scans, so an agent's
+      // declared policy is judged against the identity `server/context.ts` establishes.
+      serverDir
+    })
   );
   const servicesProxyPrefixes = ctx.services && Object.keys(ctx.services).length > 0 ? Object.values(ctx.services).map((s) => s.proxy) : [];
   const csrfReadinessStore = ctx.csrfReadinessStoreOverride ?? new CsrfReadinessStore();
@@ -917,7 +1028,7 @@ async function runConfigureServer(server, ctx) {
   server.watcher.on("unlink", handleRouteChange);
   if (ctx.resolvedOpenApi !== void 0) {
     const openApiCfg = ctx.resolvedOpenApi;
-    const { reEmitOpenApi } = await import("./dev-emit-GWD6IXV7.js");
+    const { reEmitOpenApi } = await import("./dev-emit-BFNMDCPB.js");
     const openApiServerDir = ctx.serverDir;
     const openApiDistDir = resolve3(ctx.projectRoot, ctx.resolvedDistDir);
     const isRouteFileForOpenApi = (file) => file.startsWith(openApiServerDir) && /\.(ts|tsx|js|mjs)$/.test(file);
@@ -1224,19 +1335,9 @@ async function integrateUseTheoUI(cwd, opts) {
   return [...tailwindPlugins, ...uiPlugins];
 }
 
-// src/vite-plugin/resolve-theo-root.ts
+// src/vite-plugin/transform-html-hook.ts
 import { existsSync as existsSync5 } from "fs";
 import { resolve as resolve4 } from "path";
-function resolveTheoRootDir(currentDir) {
-  if (existsSync5(resolve4(currentDir, "client"))) {
-    return currentDir;
-  }
-  return resolve4(currentDir, "..");
-}
-
-// src/vite-plugin/transform-html-hook.ts
-import { existsSync as existsSync6 } from "fs";
-import { resolve as resolve5 } from "path";
 
 // src/vite-plugin/inject-devtools.ts
 var DEVTOOLS_VIRTUAL_ID = "/@theo/devtools/entry.js";
@@ -1336,7 +1437,7 @@ function runTransformIndexHtml(html, ctx) {
   next = devtools.html;
   const styles = injectStylesheets(next, {
     isDev: ctx.isDevMode.value,
-    hasPackage: (name) => existsSync6(resolve5(ctx.projectRoot, "node_modules", ...name.split("/")))
+    hasPackage: (name) => existsSync5(resolve4(ctx.projectRoot, "node_modules", ...name.split("/")))
   });
   next = styles.html;
   return next;
@@ -1439,6 +1540,46 @@ function generateSingleShotEntry(options) {
     `}`
   ].join("\n");
 }
+function streamingDocumentHelpers() {
+  return [
+    `function __theoHydrationScript(hydrationData, nonce) {`,
+    // `<` is escaped rather than the whole payload: loader data is developer
+    // data, and the only sequence that can break out of a script element is
+    // `</script`. Mirrors what the non-streaming path does in request-handler.ts.
+    `  const json = JSON.stringify(hydrationData).replace(/</g, '\\u003c')`,
+    `  const attr = nonce ? ' nonce="' + nonce + '"' : ''`,
+    `  return '<script' + attr + '>window.__staticRouterHydrationData=' + json + '<' + '/script>'`,
+    `}`,
+    ``,
+    `function __theoDocumentStream(appStream, hydrationData, options) {`,
+    `  const encoder = new TextEncoder()`,
+    `  const head = options.htmlHead ?? ''`,
+    `  const tail = options.htmlTail ?? ''`,
+    `  return new ReadableStream({`,
+    `    async start(controller) {`,
+    // Its own chunk: the reader gets <head> before React has rendered anything.
+    `      if (head) controller.enqueue(encoder.encode(head))`,
+    `      const reader = appStream.getReader()`,
+    `      try {`,
+    `        for (;;) {`,
+    `          const { done, value } = await reader.read()`,
+    `          if (done) break`,
+    `          controller.enqueue(value)`,
+    `        }`,
+    `      } finally {`,
+    `        reader.releaseLock()`,
+    `      }`,
+    // The hydration script trails the app markup and precedes the tail, so it
+    // still runs before the client entry the tail loads.
+    `      controller.enqueue(`,
+    `        encoder.encode(__theoHydrationScript(hydrationData, options.nonce) + tail),`,
+    `      )`,
+    `      controller.close()`,
+    `    },`,
+    `  })`,
+    `}`
+  ];
+}
 function streamingWebRenderer(appTree) {
   return [
     `// T2.3 \u2014 Web Standards streaming entry for edge runtimes (Cloudflare,`,
@@ -1458,13 +1599,16 @@ function streamingWebRenderer(appTree) {
     // Streaming still applies to genuine data-fetching Suspense, which is where it earns its keep.
     // A failed import is swallowed on purpose: React.lazy will retry and suspend as before, which
     // is strictly no worse than not having preloaded at all.
-    `  const __theoMatches = matchRoutes(routes, url.split('?')[0]) ?? []`,
+    // `url` is a URL here, not the string the other renderers receive as a parameter —
+    // so the match key is `.pathname`, never `.split('?')`. Hoisting the declaration
+    // without changing the accessor trades the TDZ for a TypeError (#344).
+    `  const url = new URL(request.url)`,
+    `  const __theoMatches = matchRoutes(routes, url.pathname) ?? []`,
     `  await Promise.all(`,
     `    __theoPreloadPathsFor(__theoMatches).map((p) => __theoPreloadMap[p]().catch(() => null)),`,
     `  )`,
     ``,
     `  const handler = createStaticHandler(routes)`,
-    `  const url = new URL(request.url)`,
     `  const context = await handler.query(request)`,
     ``,
     `  if (context instanceof Response) {`,
@@ -1474,12 +1618,14 @@ function streamingWebRenderer(appTree) {
     `  const router = createStaticRouter(handler.dataRoutes, context)`,
     `  const app = ${appTree}`,
     ``,
+    hydrationDataExtractSnippet(),
+    ``,
     `  const stream = await renderToReadableStream(app, {`,
     `    signal: request.signal,`,
     `    nonce: options.nonce,`,
     `    onError(err) { console.error('[SSR Web Stream Error]', err) },`,
     `  })`,
-    `  return new Response(stream, {`,
+    `  return new Response(__theoDocumentStream(stream, hydrationData, options), {`,
     `    status: 200,`,
     `    headers: {`,
     `      'Content-Type': 'text/html; charset=utf-8',`,
@@ -1523,15 +1669,29 @@ function streamingNodeRenderer(appTree) {
     `  const router = createStaticRouter(handler.dataRoutes, context)`,
     `  const app = ${appTree}`,
     ``,
+    hydrationDataExtractSnippet(),
+    ``,
+    `  const { PassThrough } = await import('node:stream')`,
     `  return new Promise((resolve, reject) => {`,
     `    let didError = false`,
+    // React's `pipe(dest)` ends `dest` when the source ends, which would close the
+    // response before the hydration script could be written. Piping into a
+    // PassThrough keeps the response open for the tail.
+    `    const passthrough = new PassThrough()`,
+    `    passthrough.on('data', (chunk) => { response.write(chunk) })`,
+    `    passthrough.on('end', () => {`,
+    `      response.end(__theoHydrationScript(hydrationData, options.nonce) + (options.htmlTail ?? ''))`,
+    `    })`,
+    `    passthrough.on('error', reject)`,
     `    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)`,
+    // The head goes out on its own write, before any React byte.
+    `        if (options.htmlHead) response.write(options.htmlHead)`,
+    `        stream.pipe(passthrough)`,
     `        resolve({ streaming: true })`,
     `      },`,
     `      onShellError(err) { reject(err) },`,
@@ -1615,6 +1775,8 @@ function generateStreamingEntry(options) {
     `import { routes, __theoPreloadMap, __theoPreloadPathsFor } from '/@theo/route-manifest'`,
     theoUiImport,
     ``,
+    ...streamingDocumentHelpers(),
+    ``,
     ...streamingWebRenderer(appTree),
     ``,
     ...streamingNodeRenderer(appTree),
@@ -1724,7 +1886,6 @@ function walkRouteTree(node, parents, acc) {
       routePath
     });
   }
-  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"));
@@ -1739,18 +1900,20 @@ function generateRouteManifest(tree, options = {}) {
   const lazyPages_ = options.lazyPages !== false;
   const acc = {
     staticImports: [],
-    lazyPages: [],
-    layoutState: { found: false }
+    lazyPages: []
   };
   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("");
+  lines.push(
+    `import { Outlet, ScrollRestoration } from 'react-router'`,
+    // #421 — react-router restores the DOCUMENT. The layout this framework scaffolds scrolls an
+    // inner element, so the restoration that was mounted and running restored nothing. Both are
+    // emitted: one owns the document, the other owns the elements the app marked.
+    `import { ElementScrollRestoration } from 'theokit/router/element-scroll-restoration'`,
+    ""
+  );
   for (const imp of staticImports) {
     lines.push(`import ${imp.varName} from '${imp.importPath}'`);
   }
@@ -1804,16 +1967,20 @@ function generateRouteManifest(tree, options = {}) {
   function genRouteConfig(node, isRoot) {
     const seg = node.segment || "root";
     const childrenArray = buildChildrenArray(node, seg);
+    const withScrollRestoration = (element) => `React.createElement(React.Fragment, null, React.createElement(ScrollRestoration), React.createElement(ElementScrollRestoration), ${element})`;
     if (node.layout) {
       const layoutVar = safeVarName(seg, "Layout");
       const pathPart = isRoot ? `path: '/'` : `path: '${segmentPath(node)}'`;
-      return `{ ${pathPart}, element: React.createElement(${layoutVar}, { children: React.createElement(Outlet) }), children: ${childrenArray} }`;
+      const layoutElement = `React.createElement(${layoutVar}, { children: React.createElement(Outlet) })`;
+      const element = isRoot ? withScrollRestoration(layoutElement) : layoutElement;
+      return `{ ${pathPart}, element: ${element}, children: ${childrenArray} }`;
     }
     if (isRoot) {
+      const rootElement = withScrollRestoration(`React.createElement(Outlet)`);
       if (node.children.length === 0 && !node.page && !node.notFound && !node.error) {
-        return `{ path: '/', children: [] }`;
+        return `{ path: '/', element: ${rootElement}, children: [] }`;
       }
-      return `{ path: '/', children: ${childrenArray} }`;
+      return `{ path: '/', element: ${rootElement}, children: ${childrenArray} }`;
     }
     if (node.page && node.children.length === 0 && !node.error && !node.notFound) {
       const pageVar = safeVarName(seg, "Page");
@@ -1981,8 +2148,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 = resolve5(dir, `${basename2}${ext}`);
+      if (existsSync6(candidate)) return candidate;
     }
     const parent = dirname4(dir);
     if (parent === dir) break;
@@ -1993,7 +2160,7 @@ function findConsumerConfig(projectRoot, basename2) {
 async function theoPluginAsync(rootOrOptions) {
   const options = typeof rootOrOptions === "string" ? { root: rootOrOptions } : rootOrOptions ?? {};
   const projectRoot = options.root ?? process.cwd();
-  const serverDirAbs = resolve6(projectRoot, options.serverDir ?? "server");
+  const serverDirAbs = resolve5(projectRoot, options.serverDir ?? "server");
   const agentsDirName = options.agentsDir ?? "agents";
   const consumerTailwindConfig = findConsumerConfig(projectRoot, "tailwind.config");
   const consumerPostcssConfig = findConsumerConfig(projectRoot, "postcss.config");
@@ -2004,7 +2171,7 @@ async function theoPluginAsync(rootOrOptions) {
   const studioPlugins = await integrateStudio();
   const servicesPlugins = [];
   if (options.services && Object.keys(options.services).length > 0) {
-    const { servicesTypedClientPlugin } = await import("./services-typed-client-PSAGRPFF.js");
+    const { servicesTypedClientPlugin } = await import("./services-typed-client-XGT5SUUN.js");
     servicesPlugins.push(
       servicesTypedClientPlugin({
         cwd: projectRoot,
@@ -2012,23 +2179,23 @@ async function theoPluginAsync(rootOrOptions) {
       })
     );
   }
-  const { appTypedClientPlugin } = await import("./app-typed-client-G3J5G7E5.js");
+  const { appTypedClientPlugin } = await import("./app-typed-client-DQM3Y6YY.js");
   const appClientPlugin = appTypedClientPlugin({
     cwd: projectRoot,
     serverDir: serverDirAbs,
-    distDir: resolve6(projectRoot, ".theokit")
+    distDir: resolve5(projectRoot, ".theokit")
   });
-  const { actionsVirtualModule } = await import("./actions-virtual-module-LB4NGONI.js");
+  const { actionsVirtualModule } = await import("./actions-virtual-module-ZYLMNW6K.js");
   const actionsPlugin = actionsVirtualModule({
     serverDir: serverDirAbs,
-    distDir: resolve6(projectRoot, ".theokit")
+    distDir: resolve5(projectRoot, ".theokit")
   });
   const { agentsTypedClientPlugin } = await import("./agents-typed-client-D4OA2TXB.js");
-  const { generateManifest } = await import("./internal-api-V5L65YSJ.js");
+  const { generateManifest } = await import("./internal-api-IP35YU3G.js");
   const agentsClientPlugin = agentsTypedClientPlugin({
     projectRoot,
     agentsDir: agentsDirName,
-    distDir: resolve6(projectRoot, ".theokit"),
+    distDir: resolve5(projectRoot, ".theokit"),
     // Agents live at <projectRoot>/<agentsDir>; generateManifest scans them via the server dir's
     // parent (projectRoot for the canonical layout) + the agents dir name (#95 follow-up).
     scanManifest: () => generateManifest(serverDirAbs, projectRoot, agentsDirName)
@@ -2041,11 +2208,17 @@ async function theoPluginAsync(rootOrOptions) {
   const controllerTransformPlugin = controllerSwcTransformPlugin({
     serverDir: serverDirAbs
   });
+  const { serverOnlyImportBoundary } = await import("./server-boundary-7VZQRPPX.js");
+  const serverBoundaryPlugin = serverOnlyImportBoundary({
+    projectRoot,
+    serverDir: serverDirAbs
+  });
   return [
     theoPlugin(rootOrOptions),
     ...uiPlugins,
     ...studioPlugins,
     ...servicesPlugins,
+    serverBoundaryPlugin,
     // #122 — swc-compile controllers/** (enforce:'pre'; order-independent).
     controllerTransformPlugin,
     appClientPlugin,
@@ -2056,10 +2229,10 @@ async function theoPluginAsync(rootOrOptions) {
 }
 function buildOptimizeDepsInclude(projectRoot, viteOptimizeDeps) {
   const include = [];
-  if (existsSync7(resolve6(projectRoot, "node_modules", "@theokit", "ui"))) {
+  if (existsSync6(resolve5(projectRoot, "node_modules", "@theokit", "ui"))) {
     include.push("@theokit/ui");
   }
-  if (existsSync7(resolve6(projectRoot, "node_modules", "lucide-react"))) {
+  if (existsSync6(resolve5(projectRoot, "node_modules", "lucide-react"))) {
     include.push("lucide-react");
   }
   include.push("devalue");
@@ -2085,8 +2258,8 @@ var VIRTUAL_MODULE_IDS = {
 function theoPlugin(rootOrOptions) {
   const options = typeof rootOrOptions === "string" ? { root: rootOrOptions } : rootOrOptions ?? {};
   const projectRoot = options.root ?? process.cwd();
-  const appDir = resolve6(projectRoot, options.appDir ?? "app");
-  const serverDir = resolve6(projectRoot, options.serverDir ?? "server");
+  const appDir = resolve5(projectRoot, options.appDir ?? "app");
+  const serverDir = resolve5(projectRoot, options.serverDir ?? "server");
   const agentsDir = options.agentsDir ?? "agents";
   const ssrEnabled = options.ssr ?? false;
   const currentDir = dirname4(fileURLToPath(import.meta.url));
@@ -2210,4 +2383,4 @@ export {
   theoPluginAsync,
   theoPlugin
 };
-//# sourceMappingURL=chunk-YRBR424R.js.map
+//# sourceMappingURL=chunk-OAUI273L.js.map