@pyric/cli 0.1.0-alpha.14 → 0.1.0-alpha.15

package/src/serve/namespace.ts

@@ -10,18 +10,18 @@
  * Bridge routes (`/__pyric/mcp`, `/__pyric/sandbox`) mount here in P2.
  */
 import { randomBytes } from 'node:crypto';
-import { existsSync, statSync } from 'node:fs';
-import { basename, extname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { ActivityIncident } from 'pyric/firestore/internal';
 import { collectBody } from '../bridge/server/peer.js';
 import { StateFileError, type StateSection, type StateStore } from './state-store.js';
 import { createWriterLock, type WriterLock } from './writer-lock.js';
 import { createStudioRoutes, type StudioRouteOptions } from './studio/index.js';
-import { contentTypeFor, pipeFileToResponse, resolveStaticFile, type ServeLogger } from './server.js';
-import { SANDBOX_BUILD_MARKER } from './sandbox-marker.js';
+import { pipeFileToResponse, type ServeLogger } from './server.js';
 import type { InitPayload } from './init-payload.js';
 import { handleActivity } from './activity-route.js';
+import { createSiteTreeHandler } from './site-tree.js';
 export type { InitPayload } from './init-payload.js';
 
 /**
@@ -34,12 +34,19 @@ export interface ServeEventHub {
   handle(req: IncomingMessage, res: ServerResponse): void;
   broadcast(event: string, data: unknown): void;
   clientCount(): number;
+  /** End all open streams. Idempotent; used by host-neutral session cleanup. */
+  close(): void;
 }
 
 export function createEventHub(): ServeEventHub {
   const clients = new Set<ServerResponse>();
+  let closed = false;
   return {
     handle(req, res) {
+      if (closed) {
+        res.writeHead(503, { 'content-type': 'text/plain' }).end('sandbox session closed');
+        return;
+      }
       res.writeHead(200, {
         'content-type': 'text/event-stream',
         'cache-control': 'no-store',
@@ -53,6 +60,7 @@ export function createEventHub(): ServeEventHub {
       res.on('error', () => clients.delete(res));
     },
     broadcast(event, data) {
+      if (closed) return;
       const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
       for (const res of clients) {
         try {
@@ -63,6 +71,12 @@ export function createEventHub(): ServeEventHub {
       }
     },
     clientCount: () => clients.size,
+    close() {
+      if (closed) return;
+      closed = true;
+      for (const res of clients) res.end();
+      clients.clear();
+    },
   };
 }
 
@@ -85,22 +99,14 @@ export interface NamespaceOptions {
    *  current fixture JSON (200) or 404 when nothing is captured yet, so the
    *  served worker can re-hydrate its event history on boot after a death. */
   capture?: { write(json: string): void; read(): string | null };
+  /** Unified Astro documentation + Studio tree, built for `/__pyric/ui/`. */
+  siteUiDir?: string;
+  /** Served SharedWorker epoch stamped only into Studio entry documents. */
+  workerVersion?: string;
   /** `--ui` (Pyric Studio): mounts `/__pyric/workspace` + `/__pyric/projects`
    *  (disk-backed `WorkspaceStore`/`ProjectStore`, plus the SSE watch stream)
    *  that `@pyric/studio`'s `local` mode talks to. */
   studio?: StudioRouteOptions;
-  /** `--ui` (Pyric Studio): the dir of the built Studio app, served under
-   *  `/__pyric/ui/`. Resolved by file path in the CLI (@pyric/cli never
-   *  imports `@pyric/studio`). Absent when `--ui` is off or the build is
-   *  missing. */
-  studioUiDir?: string;
-  /** `--ui` (Pyric Studio): the built docs site (site-docs), served so the
-   *  Studio Docs tab has local docs without the hosted site. Built with base
-   *  `/__pyric/ui/`, so its output straddles two subtrees under the mount:
-   *  the pages/twins/index.json live under `/__pyric/ui/docs/`, but the shared
-   *  assets live at `/__pyric/ui/_astro/` (Astro's asset dir, at the base
-   *  root — NOT under `docs/`). Both are served from this one dir. */
-  docsUiDir?: string;
   /** The OpenAI-compatible upstream `/__pyric/ai-proxy` forwards to
    *  (pyric/ai — cdd-deltas #98.2). Falls back to the
    *  `PYRIC_AI_PROXY_UPSTREAM` env var, then `http://localhost:11434/v1`
@@ -467,6 +473,9 @@ async function handleDenials(
 export function createPyricNamespace(opts: NamespaceOptions) {
   const writerLock = createWriterLock();
   const studioRoutes = opts.studio ? createStudioRoutes(opts.studio) : null;
+  const siteTree = opts.siteUiDir
+    ? createSiteTreeHandler(opts.siteUiDir, opts.workerVersion)
+    : null;
   const denialThrottle = createDenialThrottle();
   // Issued once per server boot. The outer static/Vite host guard protects
   // init.json before this capability is disclosed to the served runtime.
@@ -517,159 +526,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
       pipeFileToResponse(file, res);
       return true;
     }
-    // Embedded docs site (site-docs). MUST run BEFORE the general
-    // `/__pyric/ui/` studio handler below: that handler's SPA fallback answers
-    // every miss with Studio's index.html, which would swallow docs pages and
-    // (worse) return HTML for a missing docs asset. Built with base
-    // `/__pyric/ui/`, the docs output lives in TWO subtrees under the mount —
-    // pages/twins/index.json under `/__pyric/ui/docs/`, and shared assets at
-    // `/__pyric/ui/_astro/` (Astro's asset dir sits at the base root, not under
-    // `docs/`). We claim both; `_astro` is Astro-specific and never collides
-    // with Studio (Vite emits `/__pyric/ui/assets/`). No SPA fallback here — a
-    // genuinely missing docs page 404s (a broken doc link must fail loudly, not
-    // masquerade as another page). Directory-format pages (`<slug>/index.html`)
-    // and `bunx serve`-style extensionless→trailing-slash redirects are handled
-    // by resolveStaticFile + the directory redirect below.
-    if (
-      opts.docsUiDir &&
-      (url.pathname === '/__pyric/ui/docs' ||
-        url.pathname.startsWith('/__pyric/ui/docs/') ||
-        url.pathname.startsWith('/__pyric/ui/_astro/'))
-    ) {
-      const rel = url.pathname.slice('/__pyric/ui'.length) || '/';
-      // `bunx serve` parity: an extensionless path that names a real directory
-      // (e.g. `/__pyric/ui/docs` or `/__pyric/ui/docs/<slug>`) redirects to the
-      // trailing-slash form so the directory's index.html loads with correct
-      // relative-URL resolution.
-      if (!rel.endsWith('/') && !extname(rel)) {
-        const dir = join(opts.docsUiDir, decodeURIComponent(rel));
-        if (existsSync(dir) && statSync(dir).isDirectory()) {
-          res.writeHead(301, { location: `${url.pathname}/` }).end();
-          return true;
-        }
-      }
-      const file = resolveStaticFile(opts.docsUiDir, rel);
-      if (!file) {
-        res.writeHead(404).end('not found');
-        return true;
-      }
-      res.writeHead(200, { 'content-type': contentTypeFor(file), 'cache-control': 'no-store' });
-      pipeFileToResponse(file, res);
-      return true;
-    }
-    if (
-      opts.studioUiDir &&
-      (url.pathname === '/__pyric/ui' || url.pathname.startsWith('/__pyric/ui/'))
-    ) {
-      // The built Pyric Studio app. Served verbatim (NOT through
-      // injectServeTags: that import-map/init injection is for sandbox pages,
-      // not Studio). Studio uses History-API routing under this mount, so any
-      // path that doesn't resolve to a real file falls back to index.html —
-      // INCLUDING paths with dots (deep links like /storage/uploads/logo.png).
-      // Only misses under Vite's content-hashed asset dir stay hard 404s, so a
-      // broken script/style URL fails loudly instead of returning HTML.
-      if (url.pathname === '/__pyric/ui') {
-        res.writeHead(301, { location: '/__pyric/ui/' }).end();
-        return true;
-      }
-      const rel = url.pathname.slice('/__pyric/ui'.length) || '/';
-      let file = resolveStaticFile(opts.studioUiDir, rel);
-      if (!file && !rel.startsWith('/assets/')) {
-        file = resolveStaticFile(opts.studioUiDir, '/index.html');
-      }
-      if (!file) {
-        res.writeHead(404).end('not found');
-        return true;
-      }
-      res.writeHead(200, { 'content-type': contentTypeFor(file), 'cache-control': 'no-store' });
-      pipeFileToResponse(file, res);
-      return true;
-    }
+    if (siteTree?.(req, res, url)) return true;
     return false; // unknown /__pyric/* → caller 404s
   };
 }
-
-// ─── HTML injection ───────────────────────────────────────────────────
-
-/** The import-map targets. Spec → served URL. */
-export function sdkImportMap(): Record<string, string> {
-  return {
-    'firebase/ai': '/__pyric/sdk/ai.js',
-    'firebase/app': '/__pyric/sdk/app.js',
-    'firebase/auth': '/__pyric/sdk/auth.js',
-    'firebase/database': '/__pyric/sdk/database.js',
-    'firebase/firestore': '/__pyric/sdk/firestore.js',
-    'firebase/messaging': '/__pyric/sdk/messaging.js',
-    'firebase/messaging/sw': '/__pyric/sdk/messaging-sw.js',
-    'firebase/storage': '/__pyric/sdk/storage.js',
-  };
-}
-
-/**
- * Inject the import map + init script into an HTML document. The import map
- * MUST precede any module script that imports a mapped specifier, so both
- * tags go at the very start of `<head>` (fallbacks: after `<html>`, else
- * prepended). Idempotent — a page already carrying the marker is untouched
- * (matters when transformHtml runs over an SPA fallback repeatedly).
- */
-export function injectServeTags(
-  html: string,
-  importMap: Record<string, string> = sdkImportMap(),
-  workerVersion?: string,
-  forceInPage = false,
-): string {
-  const MARKER = 'data-pyric-serve';
-  if (html.includes(MARKER)) return html;
-  // A pyric SANDBOX BUILD (`vite build` under the pyricSandbox plugin's sandbox
-  // mode) already BUNDLES its own runtime + init chunk — injecting the import
-  // map + /__pyric/sdk/init.js on top would boot a SECOND runtime instance on
-  // the page (two banners, two bridge peer registrations, races between them).
-  // The bundle owns the sandbox for a marked page: it fetches
-  // /__pyric/init.json itself (worker path: the SharedWorker does; in-page
-  // path: the runtime does) and owns rules hot-reload the same way. The ONLY
-  // serve-time contribution left is the worker-version staleness stamp, which
-  // the bundled runtime reads from this meta to warn about a stale
-  // still-running SharedWorker.
-  if (html.includes(SANDBOX_BUILD_MARKER)) {
-    if (!workerVersion || html.includes('pyric-worker-v')) return html;
-    const meta = `<meta name="pyric-worker-v" content="${workerVersion}" ${MARKER}>`;
-    const headTag = html.match(/<head[^>]*>/i);
-    if (headTag && headTag.index !== undefined) {
-      const at = headTag.index + headTag[0].length;
-      return html.slice(0, at) + meta + html.slice(at);
-    }
-    return meta + html;
-  }
-  // Stamp the worker's content hash so the page can DETECT staleness: a live
-  // SharedWorker survives serve restarts + reloads and can't hot-update, so it
-  // keeps running old code until every tab of the origin closes. The worker
-  // name is intentionally STABLE (one backend shared by all tabs), so rather
-  // than split tabs across versions, `runtime.ts` compares this served hash to
-  // the running worker's baked hash and warns the user to close all tabs.
-  const versionMeta = workerVersion
-    ? `<meta name="pyric-worker-v" content="${workerVersion}" ${MARKER}>`
-    : '';
-  // `--bridge`: the MCP bridge peers with the IN-PAGE sandbox, so force the page
-  // off the default SharedWorker path. Otherwise the agent drives an empty
-  // in-page sandbox while the app's data lives in the worker. Set before any app
-  // code runs; mirrors the Vite plugin's transformIndexHtml.
-  const forceTag = forceInPage
-    ? `<script ${MARKER}>globalThis.__PYRIC_FORCE_INPAGE__=true;</script>`
-    : '';
-  const tags =
-    versionMeta +
-    forceTag +
-    `<script type="importmap" ${MARKER}>${JSON.stringify({ imports: importMap })}</script>` +
-    `<script type="module" src="/__pyric/sdk/init.js" ${MARKER}></script>`;
-  const head = html.match(/<head[^>]*>/i);
-  if (head && head.index !== undefined) {
-    const at = head.index + head[0].length;
-    return html.slice(0, at) + tags + html.slice(at);
-  }
-  const htmlTag = html.match(/<html[^>]*>/i);
-  if (htmlTag && htmlTag.index !== undefined) {
-    const at = htmlTag.index + htmlTag[0].length;
-    return html.slice(0, at) + tags + html.slice(at);
-  }
-  return tags + html;
-}

package/src/serve/runtime/worker-replacement.ts

@@ -1,4 +1,4 @@
-interface WorkerReplacementOptions {
+export interface WorkerReplacementOptions {
   targetEpoch: string;
   retire(): Promise<void>;
   subscribeReload(listener: (epoch: string) => void): () => void;

package/src/serve/sandbox-session.ts

@@ -0,0 +1,233 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ActivityIncident } from 'pyric/firestore/internal';
+import type { FirebaseJson } from '../cli/firebase-json.js';
+import { createCaptureStore, type CaptureStore } from './capture-store.js';
+import type { InitPayload } from './init-payload.js';
+import {
+  loadProjectDatabaseRules,
+  loadProjectRules,
+  loadProjectStorageRules,
+  prepareRulesSource,
+  rulesHashOf,
+} from './rules.js';
+import { createEventHub, createPyricNamespace } from './namespace.js';
+import { diskProjectStore, diskWorkspace } from './studio/index.js';
+import type { ServeLogger } from './server.js';
+import {
+  createStateStore,
+  firestoreDocCount,
+  STATE_FILE_VERSION,
+  type PyricStateFile,
+  type StateStore,
+} from './state-store.js';
+
+export interface SandboxSessionOptions {
+  projectDir: string;
+  firebaseConfig: FirebaseJson | null;
+  sdk: { dir: string; workerVersion?: string };
+  seedFile?: string;
+  capture?: boolean;
+  persistence?: { fresh?: boolean };
+  studio?: false | { siteUiDir?: string };
+  bridgeUrl?: () => string | null;
+  ai?: InitPayload['ai'];
+  aiProxyUpstream?: string;
+  logger?: ServeLogger;
+  activity?: (incident: ActivityIncident) => void;
+}
+
+export interface SandboxSessionSummary {
+  rules: {
+    firestore: { sourcePath: string | null; hash: string | null };
+    database: { sourcePath: string | null; hash: string | null };
+    storage: { sourcePath: string | null; hash: string | null };
+  };
+  persistence: null | {
+    path: string;
+    backupPath: string;
+    restoredDocs: number;
+    restoredUsers: number;
+    restored: boolean;
+  };
+  capturePath: string | null;
+  seedLabel: string | null;
+  seedStaged: boolean;
+  studioMounted: boolean;
+}
+
+export interface SandboxSession {
+  readonly summary: SandboxSessionSummary;
+  payload(): InitPayload;
+  handle(req: IncomingMessage, res: ServerResponse, url: URL): boolean | Promise<boolean>;
+  reloadFirestoreRules(): Promise<RulesReloadResult>;
+  close(): Promise<void>;
+}
+
+export class SandboxSeedError extends Error {
+  constructor(
+    readonly kind: 'read' | 'shape',
+    readonly path: string,
+    readonly detail: string,
+  ) {
+    super(kind === 'read' ? `failed to read seed ${path}: ${detail}` : `seed must be a JSON object (${detail})`);
+    this.name = 'SandboxSeedError';
+  }
+}
+
+export type RulesReloadResult =
+  | { kind: 'not-configured' }
+  | { kind: 'reloaded'; rulesHash: string; clients: number }
+  | { kind: 'rejected'; error: Error };
+
+export async function createSandboxSession(
+  options: SandboxSessionOptions,
+): Promise<SandboxSession> {
+  // Preserve the established fail-fast order: Firestore, then RTDB, then
+  // Storage. Callers historically surfaced the first error in this sequence.
+  const firestore = await loadProjectRules(options.projectDir, options.firebaseConfig);
+  const database = await loadProjectDatabaseRules(options.projectDir, options.firebaseConfig);
+  const storage = await loadProjectStorageRules(options.projectDir, options.firebaseConfig);
+  const live = {
+    rules: firestore.rules,
+    rulesHash: firestore.rulesHash,
+  };
+  const events = createEventHub();
+  const capture: CaptureStore | undefined = (options.capture ?? true)
+    ? createCaptureStore(options.projectDir)
+    : undefined;
+  const state: StateStore | undefined = options.persistence
+    ? createStateStore(options.projectDir)
+    : undefined;
+  if (state && options.persistence?.fresh) {
+    for (const file of [state.path, state.backupPath]) {
+      if (existsSync(file)) rmSync(file);
+    }
+  }
+  let persisted = state?.load() ?? null;
+  let seed: Record<string, Record<string, unknown>> | null = null;
+  let seedState: unknown | null = null;
+  let seedUsers: Record<string, unknown>[] | null = null;
+  let seedLabel: string | null = null;
+  if (options.seedFile) {
+    const seedPath = resolve(options.projectDir, options.seedFile);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(seedPath, 'utf8')) as unknown;
+    } catch (error) {
+      throw new SandboxSeedError('read', seedPath, error instanceof Error ? error.message : String(error));
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new SandboxSeedError('shape', seedPath, `got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
+    }
+    const record = parsed as Record<string, unknown>;
+    if (record.version === STATE_FILE_VERSION && ('firestore' in record || 'auth' in record)) {
+      const fixture = record as unknown as PyricStateFile;
+      const restoredDocs = firestoreDocCount(fixture.firestore);
+      const restoredUsers = fixture.auth?.users?.length ?? 0;
+      seedLabel = `${restoredDocs} doc(s) + ${restoredUsers} user(s) from state fixture`;
+      if (state && !state.exists()) {
+        if (fixture.firestore != null) state.writeSection('firestore', fixture.firestore);
+        if (fixture.auth != null) state.writeSection('auth', fixture.auth);
+        persisted = state.load();
+      } else if (!state) {
+        seedState = fixture.firestore ?? null;
+        seedUsers = (fixture.auth?.users as Record<string, unknown>[] | undefined) ?? null;
+      }
+    } else {
+      seed = record as Record<string, Record<string, unknown>>;
+      seedLabel = `${Object.keys(seed).length} document(s)`;
+    }
+  }
+
+  const payload = (): InitPayload => ({
+    rules: live.rules,
+    rulesHash: live.rulesHash,
+    databaseRules: database.rules,
+    databaseRulesHash: database.rulesHash,
+    databaseUrl: database.databaseUrl,
+    storageRules: storage.rules,
+    storageRulesHash: storage.rulesHash,
+    projectKey: options.projectDir,
+    bridgeUrl: options.bridgeUrl?.() ?? null,
+    seed: state?.exists() ? null : seed,
+    seedState,
+    persist: Boolean(state),
+    capture: Boolean(capture),
+    authUsers: state
+      ? ((state.readSection('auth') as { users?: Record<string, unknown>[] } | null)?.users ?? null)
+      : seedUsers,
+    messaging: true,
+    ai: options.ai ?? null,
+  });
+
+  const summary: SandboxSessionSummary = {
+    rules: {
+      firestore: { sourcePath: firestore.sourcePath, hash: firestore.rulesHash },
+      database: { sourcePath: database.sourcePath, hash: database.rulesHash },
+      storage: { sourcePath: storage.sourcePath, hash: storage.rulesHash },
+    },
+    persistence: state
+      ? {
+          path: state.path,
+          backupPath: state.backupPath,
+          restoredDocs: firestoreDocCount(persisted?.firestore),
+          restoredUsers: persisted?.auth?.users?.length ?? 0,
+          restored: persisted !== null,
+        }
+      : null,
+    capturePath: capture?.path ?? null,
+    seedLabel,
+    seedStaged: Boolean((seed && !state?.exists()) || seedState || seedUsers),
+    studioMounted: Boolean(options.studio),
+  };
+
+  const namespace = createPyricNamespace({
+    sdkDir: options.sdk.dir,
+    initPayload: payload,
+    events,
+    state,
+    capture,
+    studio: options.studio
+      ? {
+          workspace: diskWorkspace(options.projectDir),
+          projects: diskProjectStore(join(options.projectDir, '.pyric', 'projects')),
+        }
+      : undefined,
+    siteUiDir: options.studio ? options.studio.siteUiDir : undefined,
+    workerVersion: options.sdk.workerVersion,
+    aiProxyUpstream: options.aiProxyUpstream,
+    activity: options.activity,
+    logger: options.logger,
+  });
+
+  const reloadFirestoreRules = async (): Promise<RulesReloadResult> => {
+    if (!firestore.sourcePath) return { kind: 'not-configured' };
+    try {
+      const raw = await readFile(firestore.sourcePath, 'utf8');
+      const rules = prepareRulesSource(raw, firestore.sourcePath);
+      const rulesHash = rulesHashOf(rules);
+      live.rules = rules;
+      live.rulesHash = rulesHash;
+      events.broadcast('rules-changed', { rules, rulesHash });
+      return { kind: 'reloaded', rulesHash, clients: events.clientCount() };
+    } catch (error) {
+      return { kind: 'rejected', error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  };
+  let closePromise: Promise<void> | null = null;
+  const close = (): Promise<void> => {
+    closePromise ??= Promise.resolve().then(() => events.close());
+    return closePromise;
+  };
+
+  return {
+    summary,
+    payload,
+    handle: namespace,
+    reloadFirestoreRules,
+    close,
+  };
+}

package/src/serve/server.ts

@@ -173,14 +173,29 @@ export function contentTypeFor(path: string): string {
   return CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
 }
 
-/** Resolve a request path inside `publicDir`, refusing traversal. Returns
- *  null when the path escapes the root or doesn't exist as a file. */
-export function resolveStaticFile(publicDir: string, pathname: string): string | null {
-  const decoded = decodeURIComponent(pathname);
+/** Decode a URL pathname for static-file lookup. Malformed escapes are misses. */
+export function decodeStaticPathname(pathname: string): string | null {
+  try {
+    return decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve a request path inside `publicDir`, refusing malformed or escaping paths. */
+export function resolveStaticPath(publicDir: string, pathname: string): string | null {
+  const decoded = decodeStaticPathname(pathname);
+  if (decoded === null) return null;
   const root = resolve(publicDir);
   const candidate = normalize(join(root, decoded));
   if (candidate !== root && !candidate.startsWith(root + sep)) return null; // traversal
-  let file = candidate;
+  return candidate;
+}
+
+/** Resolve an existing static file inside `publicDir`. */
+export function resolveStaticFile(publicDir: string, pathname: string): string | null {
+  let file = resolveStaticPath(publicDir, pathname);
+  if (file === null) return null;
   if (existsSync(file) && statSync(file).isDirectory()) file = join(file, 'index.html');
   if (!existsSync(file) || !statSync(file).isFile()) return null;
   return file;

package/src/serve/site-tree.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { extname, join } from 'node:path';
+import {
+  contentTypeFor,
+  decodeStaticPathname,
+  pipeFileToResponse,
+  resolveStaticFile,
+  resolveStaticPath,
+} from './server.js';
+
+interface StudioRoutesManifest {
+  routes: string[];
+}
+
+interface RequestWithOriginalUrl extends IncomingMessage {
+  originalUrl?: string;
+}
+
+const SITE_TREE_MOUNT_PATH = '/__pyric/ui';
+const SITE_TREE_DESCENDANT_PREFIX = `${SITE_TREE_MOUNT_PATH}/`;
+
+function studioRoutesFromSite(root: string): ReadonlySet<string> {
+  const manifestPath = join(root, 'studio-routes.json');
+  const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as StudioRoutesManifest;
+  if (!Array.isArray(parsed.routes) || parsed.routes.some((route) => typeof route !== 'string')) {
+    throw new Error(`pyric: invalid Studio route manifest at ${manifestPath}`);
+  }
+  return new Set(parsed.routes);
+}
+
+function rawRequestPathname(request: RequestWithOriginalUrl, parsedUrl: URL): string {
+  let requestTarget = request.originalUrl;
+
+  if (requestTarget === undefined) {
+    requestTarget = request.url;
+  }
+
+  if (requestTarget === undefined) {
+    return parsedUrl.pathname;
+  }
+
+  const queryStringStart = requestTarget.indexOf('?');
+
+  if (queryStringStart === -1) {
+    return requestTarget;
+  }
+
+  return requestTarget.slice(0, queryStringStart);
+}
+
+function isSiteTreePath(pathname: string): boolean {
+  if (pathname === SITE_TREE_MOUNT_PATH) {
+    return true;
+  }
+
+  return pathname.startsWith(SITE_TREE_DESCENDANT_PREFIX);
+}
+
+function withWorkerVersion(html: string, workerVersion: string | undefined): string {
+  if (!workerVersion || html.includes('name="pyric-worker-v"')) return html;
+  if (!/^[a-f0-9]{16}$/.test(workerVersion)) {
+    throw new Error(`pyric: invalid SharedWorker epoch '${workerVersion}'`);
+  }
+  const meta = `<meta name="pyric-worker-v" content="${workerVersion}" data-pyric-serve>`;
+  const head = html.match(/<head[^>]*>/i);
+  if (!head || head.index === undefined) return meta + html;
+  const at = head.index + head[0].length;
+  return html.slice(0, at) + meta + html.slice(at);
+}
+
+/** Serve the one Astro tree with SPA fallback limited to generated Studio entries. */
+export function createSiteTreeHandler(root: string, workerVersion?: string) {
+  const studioRoutes = studioRoutesFromSite(root);
+
+  return (
+    req: RequestWithOriginalUrl,
+    res: ServerResponse,
+    url: URL,
+  ): boolean => {
+    // URL parsing normalizes encoded dot segments before `url.pathname`
+    // reaches us. Route and validate against the raw request target so an
+    // encoded traversal cannot cross from Studio into docs or static assets.
+    // Connect preserves that target in `originalUrl` after stripping a mount
+    // prefix from `url`.
+    const rawPathname = rawRequestPathname(req, url);
+    if (!isSiteTreePath(rawPathname)) {
+      return false;
+    }
+    if (rawPathname === SITE_TREE_MOUNT_PATH) {
+      res.writeHead(301, { location: SITE_TREE_DESCENDANT_PREFIX }).end();
+      return true;
+    }
+
+    let relativePath = rawPathname.slice(SITE_TREE_MOUNT_PATH.length);
+
+    if (relativePath === '') {
+      relativePath = '/';
+    }
+
+    const decodedRel = decodeStaticPathname(relativePath);
+    if (decodedRel === null || decodedRel.includes('\\')) {
+      res.writeHead(404).end('not found');
+      return true;
+    }
+    const decodedSegments = decodedRel.split('/').filter(Boolean);
+    if (decodedSegments.some((segment) => segment === '.' || segment === '..')) {
+      res.writeHead(404).end('not found');
+      return true;
+    }
+    if (!relativePath.endsWith('/') && !extname(relativePath)) {
+      const dir = resolveStaticPath(root, relativePath);
+      if (dir && existsSync(dir) && statSync(dir).isDirectory()) {
+        res.writeHead(301, { location: `${rawPathname}/` }).end();
+        return true;
+      }
+    }
+
+    const first = decodedSegments[0];
+    const studioRequest = first === undefined || studioRoutes.has(first);
+    let file = resolveStaticFile(root, relativePath);
+    // Storage object names commonly contain extensions (logo.png), while the
+    // other Studio routes reserve extension-bearing misses for static assets.
+    const allowsDottedState = first === 'storage';
+    const hasDottedStateSegment = decodedSegments
+      .slice(1)
+      .some((segment) => segment.includes('.'));
+    if (!file && studioRequest && (allowsDottedState || !hasDottedStateSegment)) {
+      const entry = first === undefined ? '/index.html' : `/${first}/index.html`;
+      file = resolveStaticFile(root, entry);
+    }
+    if (!file) {
+      res.writeHead(404).end('not found');
+      return true;
+    }
+
+    const contentType = contentTypeFor(file);
+    res.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' });
+    if (studioRequest && contentType.includes('text/html')) {
+      res.end(withWorkerVersion(readFileSync(file, 'utf8'), workerVersion));
+    } else {
+      pipeFileToResponse(file, res);
+    }
+    return true;
+  };
+}