@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/dev/server.ts

@@ -0,0 +1,968 @@
+// `realm-sdk dev` HTTP server. Runs locally and gives the same iframe + loader
+// experience Home offers, driven by a single realm.ts(x) on disk with no Home
+// or Worker in the picture: it builds the iframe runtime, install-panel and
+// dev-landing bundles into a temp dir, compiles the app against the on-disk
+// fixture, and serves the landing, the install panel, iframe shells, the
+// loader/action proxies into the running container, and an SSE reload channel.
+//
+// v0 scope: single worker. A merge loader runs on one response and the iframe
+// runtime applies surface.merge([result]) for parity with Home's fan-out shape;
+// multi-worker fan-out lands later.
+
+import { join } from "@std/path";
+import { z } from "zod";
+import { runBuildRuntime } from "../cli/build-runtime.ts";
+import { runBuildInstallPanel } from "../cli/build-install-panel.ts";
+import { runBuildDevLanding } from "../cli/build-dev-landing.ts";
+import { handleUiProxy, type UiProxyResponse } from "../worker/ui-proxy.ts";
+import { resolveTrustedHeaders, stampHeaders } from "../trusted-headers.ts";
+import { findBinDirs } from "../tailwind-bin.ts";
+import { bundle } from "../bundle.ts";
+import { extractAppName } from "../sandbox.ts";
+import { iconSourceUrl } from "../app-icon.ts";
+import { firstPublicDomain } from "../service-url.ts";
+import type { WidgetManifest } from "../resolve.ts";
+import type { RequestMethod } from "../ui-surface.ts";
+import { buildPackedApp } from "../pack-build.ts";
+import { bringUp, compileAndBundle, type DevState } from "./state.ts";
+import {
+  handleInstall,
+  handlePreview,
+  installErrorToResponse,
+  InstallHandlerError,
+} from "./install-handler.ts";
+
+const KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const HASH_RE = /^[a-f0-9]{64}$/;
+
+interface DevServerOpts {
+  cwd: string;
+  port: number;
+  realmFile: string;
+}
+
+interface ReloadChannel {
+  push(): void;
+  subscribe(controller: ReadableStreamDefaultController<Uint8Array>): () => void;
+  /**
+   * Close every active SSE stream. `server.shutdown()` waits for
+   * in-flight responses to settle, and SSE responses never naturally
+   * complete, so this has to run before shutdown to avoid hanging the
+   * dev server on Ctrl-C while a browser tab is still subscribed.
+   */
+  closeAll(): void;
+}
+
+function createReloadChannel(): ReloadChannel {
+  const subscribers = new Set<ReadableStreamDefaultController<Uint8Array>>();
+  const encoder = new TextEncoder();
+  return {
+    push() {
+      const msg = `event: reload\ndata: ${Date.now()}\n\n`;
+      for (const ctrl of subscribers) {
+        try {
+          ctrl.enqueue(encoder.encode(msg));
+        } catch {
+          subscribers.delete(ctrl);
+        }
+      }
+    },
+    subscribe(controller) {
+      subscribers.add(controller);
+      return () => subscribers.delete(controller);
+    },
+    closeAll() {
+      for (const ctrl of subscribers) {
+        try {
+          ctrl.close();
+        } catch {
+          // Already closed.
+        }
+      }
+      subscribers.clear();
+    },
+  };
+}
+
+function escape(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+interface ShellPayload {
+  appName: string;
+  pathname: string;
+  sidebarOpen: boolean;
+  pages: { key: string; title: string; icon?: string }[];
+}
+
+interface LandingPayload extends ShellPayload {
+  routers: {
+    serviceId: string;
+    name: string;
+    iconSrc?: string;
+    publicDomain?: string;
+  }[];
+  widgets: (Pick<WidgetManifest, "title" | "icon" | "cols" | "rows"> & { key: string })[];
+}
+
+function readSidebarOpen(req: Request): boolean {
+  // Mirrors platform/home/src/routes/(authed)/_layout.tsx. The Sidebar
+  // provider writes `sidebar_state=true|false` on toggle; reading it
+  // server-side avoids the flash from defaulting open and then
+  // collapsing on hydrate.
+  const cookie = req.headers.get("cookie") ?? "";
+  const match = cookie.match(/(?:^|;\s*)sidebar_state=(true|false)/);
+  return match ? match[1] === "true" : true;
+}
+
+function pagesPayload(state: DevState | null): { key: string; title: string; icon?: string }[] {
+  const ui = state?.resolvedState.ui;
+  return Object.entries(ui?.pages ?? {}).map(([k, v]) => ({
+    key: k,
+    title: v.title,
+    icon: v.icon,
+  }));
+}
+
+function landingHtml(opts: { state: DevState; pathname: string; sidebarOpen: boolean }): string {
+  // Thin HTML shell: ships shell + Home metadata as JSON and mounts the
+  // dev-landing preact island, which owns the sidebar + breadcrumb, the
+  // postMessage bridge to /loader, and SSE reload. Chrome styling comes from
+  // runtime.css (clay theme + tailwind), so this page matches /install.
+  const { state, pathname, sidebarOpen } = opts;
+  const ui = state.resolvedState.ui;
+  const routers = Object.entries(state.resolvedState.services).flatMap(([serviceId, svc]) => {
+    const router = svc.router;
+    if (!router) return [];
+    // Mirror extractHomeView: `tile: false` keeps the route but no home tile.
+    if (router.tile === false) return [];
+    const publicDomain = firstPublicDomain(router.publicDomain);
+    const entry: LandingPayload["routers"][number] = {
+      serviceId,
+      name: router.name ?? serviceId,
+    };
+    // No Home here to cache and re-serve the bytes, so the landing loads the
+    // icon straight from its source.
+    if (router.icon) entry.iconSrc = iconSourceUrl(router.icon);
+    if (publicDomain) entry.publicDomain = publicDomain;
+    return [entry];
+  });
+  const widgets: LandingPayload["widgets"] = Object.entries(ui?.widgets ?? {}).map(([k, v]) => ({
+    key: k,
+    title: v.title,
+    icon: v.icon,
+    cols: v.cols,
+    rows: v.rows,
+  }));
+  const payload: LandingPayload = {
+    appName: state.appName,
+    pathname,
+    sidebarOpen,
+    pages: pagesPayload(state),
+    routers,
+    widgets,
+  };
+  const devState = JSON.stringify(payload);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>realm-sdk dev — ${escape(state.appName)}</title>
+<link rel="stylesheet" href="/runtime.css">
+</head>
+<body>
+<div id="root"></div>
+<script type="application/json" id="dev-state">${devState.replaceAll("<", "\\u003c")}</script>
+<script type="module" src="/dev-landing.js"></script>
+</body>
+</html>`;
+}
+
+function installHtml(opts: {
+  initialSource: string;
+  state: DevState | null;
+  appName: string;
+  sidebarOpen: boolean;
+}): string {
+  // Same shell shape as landingHtml: two JSON script tags (dev-state for the
+  // shared shell, install-config for the panel itself) and one module entry.
+  // State is null on cold boot — the sidebar renders against the app name
+  // extracted from the bundle, and pages stay empty until an install lands.
+  const config = JSON.stringify({ initialSource: opts.initialSource, hideDeployTargets: true });
+  const payload: ShellPayload = {
+    appName: opts.appName,
+    pathname: "/install",
+    sidebarOpen: opts.sidebarOpen,
+    pages: pagesPayload(opts.state),
+  };
+  const devState = JSON.stringify(payload);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>realm-sdk dev — install ${escape(opts.appName)}</title>
+<link rel="stylesheet" href="/runtime.css">
+</head>
+<body>
+<div id="root"></div>
+<script type="application/json" id="dev-state">${devState.replaceAll("<", "\\u003c")}</script>
+<script type="application/json" id="install-config">${config.replaceAll("<", "\\u003c")}</script>
+<script type="module" src="/install-panel.js"></script>
+</body>
+</html>`;
+}
+
+function shellHtml(opts: {
+  kind: string;
+  key: string;
+  bundleHash: string;
+  config: unknown;
+}): string {
+  // Mirrors platform/home/src/routes/(authed)/api/ui/[appId]/[kind]/[key].ts
+  // — same importmap, same two stylesheets, same mount call. Two
+  // differences: bundle is served at /bundle/<hash> (no Home auth), and
+  // the parent here is the dev landing page rather than DashboardShell.
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escape(opts.kind)}/${escape(opts.key)}</title>
+<script type="importmap">
+{
+  "imports": {
+    "@yourrealm/sdk/ui": "/runtime.js",
+    "@yourrealm/sdk/services": "/runtime.js",
+    "@yourrealm/sdk/preact": "/runtime.js",
+    "@yourrealm/sdk/jsx-runtime": "/runtime.js",
+    "@yourrealm/sdk": "/runtime.js",
+    "zod": "/runtime.js"
+  }
+}
+</script>
+<link rel="stylesheet" href="/runtime.css">
+<link rel="stylesheet" href="/bundle/${escape(opts.bundleHash)}.css">
+</head>
+<body>
+<div id="root"></div>
+<script type="module">
+  import { mount } from "/runtime.js";
+  import surface from "/bundle/${escape(opts.bundleHash)}.js";
+  mount({
+    surface: surface.default ?? surface,
+    container: document.getElementById("root"),
+    config: ${JSON.stringify(opts.config ?? null).replaceAll("<", "\\u003c")},
+  });
+</script>
+</body>
+</html>`;
+}
+
+/**
+ * Strip `additionalProperties: false` before round-tripping JSON Schema
+ * back through Zod. Mirrors Home's `loosenJsonSchema` in the surface-call
+ * route: Zod's default "strip" mode emits `additionalProperties: false`
+ * which `z.fromJSONSchema` then parses as `.strict()`, rejecting any
+ * upstream payload with extra fields. Realm's contract is loose-by-
+ * default — services often grow fields over time.
+ */
+function loosenJsonSchema(schema: unknown): unknown {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) return schema.map(loosenJsonSchema);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(schema as Record<string, unknown>)) {
+    if (k === "additionalProperties" && v === false) continue;
+    out[k] = loosenJsonSchema(v);
+  }
+  return out;
+}
+
+// The proxy answers JSON text or nothing; a body that claims JSON and isn't
+// reaches the schema check as null, which reports it as a mismatch.
+function parseUpstreamJson(res: UiProxyResponse): unknown {
+  try {
+    return JSON.parse(res.body);
+  } catch {
+    return null;
+  }
+}
+
+function validateAgainst(
+  schema: unknown,
+  value: unknown,
+): { ok: true; data: unknown } | { ok: false; issues: unknown[] } {
+  if (!schema || typeof schema !== "object") return { ok: true, data: value };
+  let live;
+  try {
+    live = z.fromJSONSchema(loosenJsonSchema(schema) as Parameters<typeof z.fromJSONSchema>[0]);
+  } catch {
+    // The schema doesn't compile — pass through rather than block on one we
+    // can't parse ourselves. Mirrors Home.
+    return { ok: true, data: value };
+  }
+  const result = live.safeParse(value);
+  if (result.success) return { ok: true, data: result.data };
+  return { ok: false, issues: result.error.issues };
+}
+
+// `realm-sdk dev` has no Home and no session, but an author developing a
+// surface must see the same brokered identity the app gets in production, so a
+// fixed viewer runs through the same resolver Home uses on both of its doors.
+const DEV_VIEWER = { username: "dev", email: "dev@realm.test", role: "admin" } as const;
+
+function devStampedHeaders(
+  state: DevState,
+  declared: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  return stampHeaders(
+    declared,
+    resolveTrustedHeaders(state.resolvedState.trustedHeaders?.byRole, DEV_VIEWER),
+  );
+}
+
+type DevRequestShape = {
+  method: RequestMethod;
+  path: string;
+  query?: Record<string, string | number | boolean>;
+  body?: unknown;
+};
+
+const REQUEST_METHODS: ReadonlySet<string> = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+
+/** The iframe's own JSON, so the shape is checked here rather than trusted. */
+function isRequestShape(value: unknown): value is DevRequestShape {
+  if (value === null || typeof value !== "object") return false;
+  const shape = value as { path?: unknown; method?: unknown };
+  return typeof shape.path === "string" && REQUEST_METHODS.has(shape.method as string);
+}
+
+async function callLoader(
+  state: DevState,
+  kind: "page" | "widget",
+  key: string,
+  name: string,
+  request: DevRequestShape,
+): Promise<Response> {
+  const ui = state.resolvedState.ui;
+  const surfaceMap = kind === "page" ? ui?.pages : ui?.widgets;
+  const surface = surfaceMap?.[key];
+  if (!surface) return Response.json({ error: "surface not found" }, { status: 404 });
+  const call = surface.loaders?.[name];
+  if (!call) return Response.json({ error: "loader not found" }, { status: 404 });
+
+  // No input validation — the request shape (method/path/query/body) is
+  // built by the surface's stitch fn; service/port come from the manifest.
+
+  // Headers in the manifest are already-resolved strings: compile()
+  // walked refs on the resolved state, so call.headers contains no
+  // `{__realmRef:...}` markers. Anything non-string here is an author bug
+  // we surface as 500.
+  let headers: Record<string, string> | undefined;
+  if (call.headers) {
+    headers = {};
+    for (const [k, v] of Object.entries(call.headers)) {
+      if (typeof v !== "string") {
+        return Response.json({ error: `header ${k} did not resolve to a string` }, { status: 500 });
+      }
+      headers[k] = v;
+    }
+  }
+
+  const payload = {
+    appId: state.appId,
+    service: call.service,
+    port: call.port,
+    path: request.path,
+    method: request.method,
+    query: request.query,
+    headers: devStampedHeaders(state, headers),
+    body: request.body,
+  };
+
+  // `handleUiProxy` is called directly, so a dev loader takes the same code
+  // path that runs inside a real Worker. The port bound is the worker's own
+  // wire state, which dev has none of, so nothing is bounded here.
+  const upstreamRes = await handleUiProxy(payload, () => undefined);
+
+  // Pass through service-level errors (4xx/5xx) verbatim — outputSchema
+  // describes the success shape and isn't meaningful for service errors.
+  if (upstreamRes.status < 200 || upstreamRes.status >= 300) {
+    const errBody = upstreamRes.body;
+    console.error(
+      `[realm-dev] loader ${kind}/${key}/${name} → upstream ${upstreamRes.status}: ${errBody.slice(0, 256)}`,
+    );
+    if (call.merge === true) {
+      let parsed: unknown = errBody;
+      try {
+        // The body comes from our own `handleUiProxy`, which always emits JSON
+        // on the error path, so a plain JSON.parse is enough.
+        parsed = JSON.parse(errBody);
+      } catch {
+        // upstream returned non-JSON; keep the raw text in `error`.
+      }
+      return Response.json(
+        { error: "all workers failed", failures: [{ workerId: "local", error: parsed }] },
+        { status: 502 },
+      );
+    }
+    return new Response(errBody, {
+      status: upstreamRes.status,
+      headers: { "content-type": upstreamRes.headers["content-type"] ?? "application/json" },
+    });
+  }
+
+  const body = parseUpstreamJson(upstreamRes);
+  const outputCheck = validateAgainst(call.outputSchema, body);
+  if (!outputCheck.ok) {
+    console.error(
+      `[realm-dev] loader ${kind}/${key}/${name} → outputSchema mismatch:`,
+      outputCheck.issues,
+    );
+    return Response.json(
+      { error: "service response does not match outputSchema", issues: outputCheck.issues },
+      { status: 502 },
+    );
+  }
+
+  if (call.merge === true) {
+    // v0: single worker. Wrap the validated body so the runtime's loader
+    // queryFn applies surface.merge([result]) — keeps the iframe contract
+    // identical to multi-worker fan-out for free.
+    return Response.json({ results: [outputCheck.data], failures: [] });
+  }
+  return Response.json(outputCheck.data);
+}
+
+async function callAction(
+  state: DevState,
+  kind: "page" | "widget",
+  key: string,
+  name: string,
+  request: DevRequestShape,
+): Promise<Response> {
+  const ui = state.resolvedState.ui;
+  const surfaceMap = kind === "page" ? ui?.pages : ui?.widgets;
+  const surface = surfaceMap?.[key];
+  if (!surface) return Response.json({ error: "surface not found" }, { status: 404 });
+  const call = surface.actions?.[name];
+  if (!call) return Response.json({ error: "action not found" }, { status: 404 });
+
+  // No input validation — the request shape is built by the stitch fn;
+  // service/port come from the manifest.
+
+  let headers: Record<string, string> | undefined;
+  if (call.headers) {
+    headers = {};
+    for (const [k, v] of Object.entries(call.headers)) {
+      if (typeof v !== "string") {
+        return Response.json({ error: `header ${k} did not resolve to a string` }, { status: 500 });
+      }
+      headers[k] = v;
+    }
+  }
+
+  const payload = {
+    appId: state.appId,
+    service: call.service,
+    port: call.port,
+    path: request.path,
+    method: request.method,
+    query: request.query,
+    headers: devStampedHeaders(state, headers),
+    body: request.body,
+  };
+
+  const upstreamRes = await handleUiProxy(payload, () => undefined);
+
+  if (upstreamRes.status < 200 || upstreamRes.status >= 300) {
+    const errBody = upstreamRes.body;
+    console.error(
+      `[realm-dev] action ${kind}/${key}/${name} → upstream ${upstreamRes.status}: ${errBody.slice(0, 256)}`,
+    );
+    return new Response(errBody, {
+      status: upstreamRes.status,
+      headers: { "content-type": upstreamRes.headers["content-type"] ?? "application/json" },
+    });
+  }
+
+  const body = parseUpstreamJson(upstreamRes);
+  const outputCheck = validateAgainst(call.outputSchema, body);
+  if (!outputCheck.ok) {
+    console.error(
+      `[realm-dev] action ${kind}/${key}/${name} → outputSchema mismatch:`,
+      outputCheck.issues,
+    );
+    return Response.json(
+      { error: "service response does not match outputSchema", issues: outputCheck.issues },
+      { status: 502 },
+    );
+  }
+  if (state.resolvedState.kind === "system") {
+    // v0 dev parity: single worker, but wrap so the runtime sees the
+    // same `{ results, failures }` shape as Home's fan-out path.
+    return Response.json({ results: [outputCheck.data], failures: [] });
+  }
+  return Response.json(outputCheck.data);
+}
+
+export async function startDevServer(opts: DevServerOpts): Promise<void> {
+  // The SDK spawns `esbuild` + `tailwindcss` by bare name. pnpm injects
+  // `<workspaceRoot>/node_modules/.bin` into PATH only for `pnpm <script>`,
+  // and running `realm-sdk` through `deno run` skips that. Every ancestor
+  // `.bin` is prepended, not just the nearest: a workspace package's local
+  // `.bin` holds only its direct deps, and both binaries are SDK devDeps.
+  const binDirs = findBinDirs(opts.cwd);
+  if (binDirs.length > 0) {
+    Deno.env.set("PATH", `${binDirs.join(":")}:${Deno.env.get("PATH") ?? ""}`);
+  }
+
+  const tmpDir = await Deno.makeTempDir({ prefix: "realm-dev-" });
+  const runtimeDir = join(tmpDir, "runtime");
+
+  console.log(`[realm-dev] building iframe runtime…`);
+  const buildCode = await runBuildRuntime(["--out", runtimeDir]);
+  if (buildCode !== 0) throw new Error("build-runtime failed");
+  const installPanelCode = await runBuildInstallPanel(["--out", runtimeDir]);
+  if (installPanelCode !== 0) throw new Error("build-install-panel failed");
+  const devLandingCode = await runBuildDevLanding(["--out", runtimeDir]);
+  if (devLandingCode !== 0) throw new Error("build-dev-landing failed");
+
+  // Boot state machine: a non-null `state` is normal mode, where every route
+  // works and the watcher recompiles on edits. A null one is install-required
+  // mode, where only /install, its API and the static assets it needs are
+  // served, anything needing a running stack 503s, and / + /pages/<key>
+  // redirect to /install. A full compile + bringUp is tried first so an app
+  // with a good realm-sdk.dev.ts boots straight into the dashboard; on failure
+  // the bundle is built only to extract the app name for the sidebar.
+  console.log(`[realm-dev] compiling realm.ts…`);
+  let state: DevState | null = null;
+  let appName = "(uninitialized)";
+  try {
+    state = await compileAndBundle({ cwd: opts.cwd, realmFile: opts.realmFile });
+    appName = state.appName;
+  } catch (err) {
+    console.warn(`[realm-dev] initial compile failed — entering install mode:`);
+    console.warn((err as Error).message);
+    try {
+      const source = await Deno.readTextFile(opts.realmFile);
+      const bundledCode = await bundle(source);
+      appName = await extractAppName(bundledCode);
+    } catch {
+      // Fall through with the placeholder appName.
+    }
+  }
+
+  type StackHandle = Awaited<ReturnType<typeof bringUp>>;
+  let stack: StackHandle | null = null;
+  if (state) {
+    console.log(`[realm-dev] booting stack (com.realm.dev=true)…`);
+    stack = await bringUp(state, tmpDir);
+  }
+
+  const reload = createReloadChannel();
+  const cwd = opts.cwd;
+
+  // File watcher: any change to a realm.ts(x) re-runs compile + bundle, in
+  // either mode — fixing the source in install-required mode is what promotes
+  // the server to normal mode without a restart. realm-sdk.dev.ts is not
+  // watched: the install panel is its only legitimate writer and already
+  // applies the resulting state + stack via /install/api/install.
+  const watcher = Deno.watchFs(cwd);
+  let pending: ReturnType<typeof setTimeout> | null = null;
+  // Reload on the app entry (`realm.tsx`/`realm.ts`, anchored to a path
+  // component start so a sibling `myrealm.ts` is ignored) or on any surface
+  // file under `pages/` / `widgets/`. The throwaway `.realm.dev-*.tsx` collapse
+  // entries never match (`.realm` ≠ `/realm`), so a collapse can't loop.
+  const RELOAD_RE = /(?:^|\/)realm\.tsx?$|\/(?:pages|widgets)\/[^/]+\.tsx$/;
+  (async () => {
+    try {
+      for await (const ev of watcher) {
+        if (!ev.paths.some((p) => RELOAD_RE.test(p))) continue;
+        if (pending !== null) clearTimeout(pending);
+        pending = setTimeout(async () => {
+          pending = null;
+          try {
+            const next = await compileAndBundle({ cwd: opts.cwd, realmFile: opts.realmFile });
+            const prev = stack;
+            stack = await bringUp(next, tmpDir);
+            // Only tear down the previous stack when its compose project is
+            // *different* from the new one. The project name derives from the
+            // appId, stable across realm.tsx edits, so a typical reload re-uses
+            // the project and bringUp's `compose up -d` has already updated it
+            // in place. Comparing handle identity instead is always true
+            // (bringUp returns a fresh handle) and would `compose down -v` the
+            // containers it just brought up.
+            if (prev && prev.project !== stack.project) prev.cleanup().catch(() => {});
+            const wasUninitialized = state === null;
+            state = next;
+            appName = next.appName;
+            console.log(wasUninitialized ? `[realm-dev] installed` : `[realm-dev] reloaded`);
+            reload.push();
+          } catch (err) {
+            console.error(`[realm-dev] reload failed: ${(err as Error).message}`);
+          }
+        }, 150);
+      }
+    } catch {
+      // Watcher closed during shutdown — fine.
+    }
+  })();
+
+  const handler = async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    const path = url.pathname;
+
+    if (path === "/" || path === "") {
+      // Install-required mode: no DevState yet, so the landing has nothing to
+      // render. Once the install succeeds, / serves the landing.
+      if (!state) {
+        return new Response(null, { status: 302, headers: { location: "/install" } });
+      }
+      return new Response(
+        landingHtml({ state, pathname: "/", sidebarOpen: readSidebarOpen(req) }),
+        {
+          headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+        },
+      );
+    }
+
+    // /pages/<key> renders the same landing HTML with a different pathname;
+    // the dev-landing island reads the path from the JSON payload and mounts a
+    // page iframe instead of Home. An unknown key is not a 404 — the island
+    // shows a "not declared" notice with the sidebar still rendered, which is
+    // more useful to an operator on a stale bookmark mid-realm.ts edit.
+    const pagesRouteMatch = path.match(/^\/pages\/([^/]+)$/);
+    if (pagesRouteMatch) {
+      if (!state) {
+        return new Response(null, { status: 302, headers: { location: "/install" } });
+      }
+      return new Response(
+        landingHtml({ state, pathname: path, sidebarOpen: readSidebarOpen(req) }),
+        {
+          headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+        },
+      );
+    }
+
+    // The iframe shell and its subresources load into a sandboxed iframe (no
+    // allow-same-origin → opaque origin). An ESM `<script type="module">` from
+    // an opaque origin is cross-origin against the dev server, so the bundle +
+    // runtime fetches need ACAO + CORP to satisfy CORS. Mirrors Home's
+    // middleware/security.ts isUiPath branch.
+    const uiHeaders = {
+      "access-control-allow-origin": "*",
+      "cross-origin-resource-policy": "cross-origin",
+    };
+
+    if (path === "/runtime.js") {
+      const bytes = await Deno.readFile(join(runtimeDir, "runtime.js"));
+      return new Response(bytes, {
+        headers: {
+          "content-type": "application/javascript",
+          "cache-control": "no-store",
+          ...uiHeaders,
+        },
+      });
+    }
+    if (path === "/runtime.css") {
+      const bytes = await Deno.readFile(join(runtimeDir, "runtime.css"));
+      return new Response(bytes, {
+        headers: { "content-type": "text/css", "cache-control": "no-store", ...uiHeaders },
+      });
+    }
+
+    if (path === "/install-panel.js") {
+      const bytes = await Deno.readFile(join(runtimeDir, "install-panel.js"));
+      return new Response(bytes, {
+        headers: {
+          "content-type": "application/javascript",
+          "cache-control": "no-store",
+        },
+      });
+    }
+
+    if (path === "/dev-landing.js") {
+      const bytes = await Deno.readFile(join(runtimeDir, "dev-landing.js"));
+      return new Response(bytes, {
+        headers: {
+          "content-type": "application/javascript",
+          "cache-control": "no-store",
+        },
+      });
+    }
+
+    if (path === "/install") {
+      // Pre-fill the box with the packed artifact — the exact bytes that ship
+      // and that Install re-consumes — so the dev funnel mirrors Home's paste →
+      // preview → install. A single-file app packs to its raw source (no
+      // markers); a multi-file app to the `// realm-file:` archive.
+      let initialSource = "";
+      try {
+        initialSource = await buildPackedApp(opts.cwd);
+      } catch (err) {
+        console.error(`[realm-dev] /install: cannot pack ${opts.cwd}: ${(err as Error).message}`);
+      }
+      return new Response(
+        installHtml({ initialSource, state, appName, sidebarOpen: readSidebarOpen(req) }),
+        {
+          headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+        },
+      );
+    }
+
+    if (path === "/install/api/preview" && req.method === "POST") {
+      let body: { source?: unknown };
+      try {
+        body = await req.json();
+      } catch {
+        return Response.json({ error: "invalid body" }, { status: 400 });
+      }
+      if (typeof body.source !== "string") {
+        return Response.json({ error: "source must be a string" }, { status: 400 });
+      }
+      try {
+        const result = await handlePreview(body.source, {
+          cwd: opts.cwd,
+          appName,
+        });
+        return Response.json(result);
+      } catch (err) {
+        if (err instanceof InstallHandlerError) return installErrorToResponse(err);
+        throw err;
+      }
+    }
+
+    if (path === "/install/api/install" && req.method === "POST") {
+      let body: {
+        source?: unknown;
+        config?: unknown;
+        grants?: unknown;
+        deployed?: unknown;
+      };
+      try {
+        body = await req.json();
+      } catch {
+        return Response.json({ error: "invalid body" }, { status: 400 });
+      }
+      if (typeof body.source !== "string") {
+        return Response.json({ error: "source must be a string" }, { status: 400 });
+      }
+      const config = (body.config ?? {}) as Record<string, unknown>;
+      // deno-lint-ignore no-explicit-any
+      const grants = (body.grants ?? {}) as any;
+      try {
+        const prevStack = stack;
+        const result = await handleInstall(
+          { source: body.source, config, grants, deployed: body.deployed },
+          { cwd: opts.cwd, realmFile: opts.realmFile, tmpDir },
+        );
+        state = result.state;
+        stack = result.stack;
+        appName = result.state.appName;
+        if (prevStack && prevStack !== result.stack) {
+          // Best-effort: drops the orphan ActiveStack from the global
+          // registry. The new compose is bound to the same project name, so
+          // nothing is taken down.
+          prevStack.cleanup().catch(() => {});
+        }
+        reload.push();
+        return new Response(null, { status: 204 });
+      } catch (err) {
+        if (err instanceof InstallHandlerError) return installErrorToResponse(err);
+        throw err;
+      }
+    }
+
+    const bundleMatch = path.match(/^\/bundle\/([a-f0-9]+)\.(js|css)$/);
+    if (bundleMatch) {
+      if (!state) return new Response("install required", { status: 503 });
+      const hash = bundleMatch[1]!;
+      const ext = bundleMatch[2]!;
+      if (!HASH_RE.test(hash)) return new Response("not found", { status: 404 });
+      const b = state.bundles.get(hash);
+      if (!b) return new Response("not found", { status: 404 });
+      return new Response(ext === "js" ? b.jsBytes : b.cssBytes, {
+        headers: {
+          "content-type": ext === "js" ? "application/javascript" : "text/css",
+          "cache-control": "no-store",
+          ...uiHeaders,
+        },
+      });
+    }
+
+    const iframeMatch = path.match(/^\/iframe\/(page|widget)\/([^/]+)$/);
+    if (iframeMatch) {
+      if (!state) return new Response("install required", { status: 503 });
+      const kind = iframeMatch[1]!;
+      const key = iframeMatch[2]!;
+      if (!KEY_RE.test(key)) return new Response("not found", { status: 404 });
+      const hash = state.surfaceHashes.get(`${kind}:${key}`);
+      if (!hash) return new Response("not found", { status: 404 });
+      const devSurface = (
+        kind === "page" ? state.resolvedState.ui?.pages : state.resolvedState.ui?.widgets
+      )?.[key];
+      const origin = url.origin;
+      // CSP mirrors Home's iframe-shell route. The iframe is sandboxed without
+      // `allow-same-origin` (opaque origin), so 'self' matches nothing — the
+      // dev origin is listed explicitly. A surface that violates CSP fails here
+      // the same way it does in prod, rather than after deploy.
+      const csp = `default-src 'none'; script-src ${origin} 'unsafe-inline'; style-src ${origin} 'unsafe-inline'; img-src ${origin} data:; font-src ${origin} data:; connect-src 'none'; frame-src 'none'; base-uri 'none'`;
+      return new Response(
+        shellHtml({
+          kind,
+          key,
+          bundleHash: hash,
+          config: devSurface?.defaultConfig,
+        }),
+        {
+          headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "content-security-policy": csp,
+            ...uiHeaders,
+          },
+        },
+      );
+    }
+
+    const loaderMatch = path.match(/^\/loader\/(page|widget)\/([^/]+)\/([^/]+)$/);
+    if (loaderMatch && req.method === "POST") {
+      if (!state) return Response.json({ error: "install required" }, { status: 503 });
+      const kind = loaderMatch[1] as "page" | "widget";
+      const key = loaderMatch[2]!;
+      const name = loaderMatch[3]!;
+      if (!NAME_RE.test(key) || !NAME_RE.test(name)) {
+        return Response.json({ error: "not found" }, { status: 404 });
+      }
+      let body: { request?: unknown };
+      try {
+        body = await req.json();
+      } catch {
+        return Response.json({ error: "invalid body" }, { status: 400 });
+      }
+      if (!isRequestShape(body.request)) {
+        return Response.json({ error: "invalid request shape" }, { status: 400 });
+      }
+      return await callLoader(state, kind, key, name, body.request);
+    }
+
+    const actionMatch = path.match(/^\/action\/(page|widget)\/([^/]+)\/([^/]+)$/);
+    if (actionMatch && req.method === "POST") {
+      if (!state) return Response.json({ error: "install required" }, { status: 503 });
+      const kind = actionMatch[1] as "page" | "widget";
+      const key = actionMatch[2]!;
+      const name = actionMatch[3]!;
+      if (!NAME_RE.test(key) || !NAME_RE.test(name)) {
+        return Response.json({ error: "not found" }, { status: 404 });
+      }
+      let body: { request?: unknown };
+      try {
+        body = await req.json();
+      } catch {
+        return Response.json({ error: "invalid body" }, { status: 400 });
+      }
+      if (!isRequestShape(body.request)) {
+        return Response.json({ error: "invalid request shape" }, { status: 400 });
+      }
+      return await callAction(state, kind, key, name, body.request);
+    }
+
+    if (path === "/events") {
+      // SSE channel — the landing page subscribes; iframe shells don't,
+      // they reload via the parent.
+      let unsubscribe: (() => void) | null = null;
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(`: connected\n\n`));
+          unsubscribe = reload.subscribe(controller);
+        },
+        cancel() {
+          unsubscribe?.();
+        },
+      });
+      return new Response(stream, {
+        headers: {
+          "content-type": "text/event-stream",
+          "cache-control": "no-store",
+          connection: "keep-alive",
+        },
+      });
+    }
+
+    return new Response("not found", { status: 404 });
+  };
+
+  const server = Deno.serve(
+    {
+      port: opts.port,
+      hostname: "127.0.0.1",
+      onListen: ({ port, hostname }) => {
+        const url = `http://${hostname}:${port}`;
+        console.log("");
+        if (state) {
+          const ui = state.resolvedState.ui;
+          const surfaceCount =
+            Object.keys(ui?.pages ?? {}).length + Object.keys(ui?.widgets ?? {}).length;
+          const surfaces = surfaceCount === 1 ? "1 surface" : `${surfaceCount} surfaces`;
+          console.log(`  realm-sdk dev — ${state.appName} (${surfaces})`);
+        } else {
+          console.log(`  realm-sdk dev — ${appName} (install required)`);
+        }
+        console.log(`  ${url}`);
+        console.log("");
+        console.log(`  watching ${opts.cwd}`);
+        console.log(`  Ctrl-C to stop`);
+        console.log("");
+      },
+    },
+    handler,
+  );
+
+  // Drain on Ctrl-C: the bringUpStack module hooks beforeunload, but SIGINT
+  // bypasses that. The first signal starts graceful shutdown (docker compose
+  // down, ~3-5s); a second hard-exits in case cleanup hangs, without which
+  // breaking out of the `for await` takes three Ctrl-Cs.
+  let shuttingDown = false;
+  const onSignal = (sig: Deno.Signal) => {
+    if (shuttingDown) {
+      console.log(`[realm-dev] ${sig} again — hard exit`);
+      Deno.exit(130);
+    }
+    shuttingDown = true;
+    console.log(`[realm-dev] ${sig} received, shutting down (Ctrl-C again to force)…`);
+    // Closing the watcher unblocks the `for await` loop above so its
+    // iterator settles and stops keeping the event loop alive.
+    try {
+      watcher.close();
+    } catch {
+      // Already closed.
+    }
+    if (pending !== null) clearTimeout(pending);
+    // Close every SSE subscriber up front: server.shutdown() awaits all
+    // in-flight responses, and an SSE stream never naturally completes,
+    // so a browser tab on the landing page would otherwise pin shutdown
+    // forever. After this returns, in-flight HTTP requests can drain.
+    reload.closeAll();
+    // Drain in the background so the signal handler returns
+    // immediately and the next signal can land. Docker teardown and
+    // HTTP shutdown are independent — run them in parallel so the
+    // slowest one bounds the wait, not their sum.
+    (async () => {
+      if (stack) console.log(`[realm-dev] tearing down docker stack…`);
+      await Promise.all([
+        stack?.cleanup().catch(() => {}) ?? Promise.resolve(),
+        server.shutdown().catch(() => {}),
+      ]);
+      console.log(`[realm-dev] done`);
+      Deno.exit(0);
+    })();
+  };
+  Deno.addSignalListener("SIGINT", () => onSignal("SIGINT"));
+  Deno.addSignalListener("SIGTERM", () => onSignal("SIGTERM"));
+
+  await server.finished;
+}