@ggui-ai/dev-stack 0.1.0-rc.1

package/dist/dev-server/http.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Read-only HTTP surface for `LocalUiRegistry`.
+ *
+ * Endpoints (v1):
+ *
+ *   GET  /health            → `{ ok: true, app, uiCount, issues }`
+ *   GET  /uis               → `UiManifestEntry[]` (JSON)
+ *   GET  /uis/:id           → `UiManifestEntry` or 404
+ *   GET  /uis/:id/bundle    → compiled JS bundle, or 404
+ *
+ * No write verbs, no subscribe. The `UiRegistry.capabilities` probe
+ * exposed on `LocalUiRegistry` already declares this publicly; the
+ * endpoints are strictly GETs so hosts / Studio can't accidentally
+ * attempt a publish against a read-only source.
+ *
+ * Security posture:
+ *
+ *   - Binds to `127.0.0.1` by default (loopback only). A user who
+ *     wants LAN access passes `host: '0.0.0.0'` and accepts the
+ *     implication.
+ *   - Token / CORS policy is supplied by the caller via the
+ *     security-policy seam (see `./auth.ts`).
+ *
+ * Node's native `http` module is used directly — no framework
+ * dependency. The handler is small enough (≈4 routes) that a router
+ * would be overkill, and keeps the open CLI's dependency footprint
+ * minimal.
+ */
+import { type Server } from 'node:http';
+import type { LocalUiRegistry } from '../local-registry/local-registry.js';
+import type { GguiJsonV1 } from '@ggui-ai/project-config';
+import type { DevServerSecurityPolicy } from './auth.js';
+import { type RuntimeSupervisor } from '../runtime-supervisor.js';
+export interface DevServerOptions {
+    registry: LocalUiRegistry;
+    /** Loaded `ggui.json`, used for the `/health` payload. */
+    manifest: GguiJsonV1;
+    /**
+     * Port to bind. `0` asks the OS for a free port — the chosen port
+     * is available via `DevServerHandle.port`.
+     */
+    port?: number;
+    /**
+     * Bind address. Defaults to `127.0.0.1` — loopback-only. Pass
+     * `'0.0.0.0'` only if you know you want LAN exposure.
+     */
+    host?: string;
+    /**
+     * Auth + CORS policy. Optional — when omitted the server is open
+     * to any reachable caller, appropriate only for tests. The CLI
+     * always constructs a real policy via
+     * {@link createSecurityPolicy} (see `./auth.ts`).
+     */
+    security?: DevServerSecurityPolicy;
+    /**
+     * Late-binding accessor for the runtime supervisor. The dev
+     * server asks the accessor per-request so a supervisor that
+     * attaches AFTER `startDevServer` resolves is still visible at
+     * `/runtime/*`. Returning `null` yields a consistent
+     * `{ present: false }` payload for the "no runtime" case.
+     */
+    getRuntimeSupervisor?: () => RuntimeSupervisor | null;
+}
+export interface DevServerHandle {
+    /** Host the server is actually listening on. */
+    host: string;
+    /** Port the server is actually listening on (resolved if opts.port was 0). */
+    port: number;
+    /** Graceful shutdown. Resolves after all active connections close. */
+    close(): Promise<void>;
+    /** Raw server, in case callers need direct access for tests. */
+    raw: Server;
+}
+/**
+ * Start the read-only dev server. Resolves after `listen` completes
+ * so callers can safely fire requests at the returned `port`.
+ */
+export declare function startDevServer(options: DevServerOptions): Promise<DevServerHandle>;
+//# sourceMappingURL=http.d.ts.map

package/dist/dev-server/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/dev-server/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAGL,KAAK,MAAM,EAEZ,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAQlC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,EAAE,UAAU,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;CACb;AAKD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CA4C1B"}

package/dist/dev-server/http.js

@@ -0,0 +1,277 @@
+/**
+ * Read-only HTTP surface for `LocalUiRegistry`.
+ *
+ * Endpoints (v1):
+ *
+ *   GET  /health            → `{ ok: true, app, uiCount, issues }`
+ *   GET  /uis               → `UiManifestEntry[]` (JSON)
+ *   GET  /uis/:id           → `UiManifestEntry` or 404
+ *   GET  /uis/:id/bundle    → compiled JS bundle, or 404
+ *
+ * No write verbs, no subscribe. The `UiRegistry.capabilities` probe
+ * exposed on `LocalUiRegistry` already declares this publicly; the
+ * endpoints are strictly GETs so hosts / Studio can't accidentally
+ * attempt a publish against a read-only source.
+ *
+ * Security posture:
+ *
+ *   - Binds to `127.0.0.1` by default (loopback only). A user who
+ *     wants LAN access passes `host: '0.0.0.0'` and accepts the
+ *     implication.
+ *   - Token / CORS policy is supplied by the caller via the
+ *     security-policy seam (see `./auth.ts`).
+ *
+ * Node's native `http` module is used directly — no framework
+ * dependency. The handler is small enough (≈4 routes) that a router
+ * would be overkill, and keeps the open CLI's dependency footprint
+ * minimal.
+ */
+import { createServer, } from 'node:http';
+import { openEventStream } from './events.js';
+import { emptyRuntimeSnapshot, } from '../runtime-supervisor.js';
+import { serveHubShell } from './hub.js';
+import { extractSelectedId, serveHubPreviewBundle, serveHubPreviewShell, } from './hub-preview.js';
+const UI_ROUTE = /^\/uis(?:\/([^/]+)(?:\/(bundle))?)?\/?$/;
+const RUNTIME_ROUTE = /^\/runtime(?:\/(status|events))?\/?$/;
+/**
+ * Start the read-only dev server. Resolves after `listen` completes
+ * so callers can safely fire requests at the returned `port`.
+ */
+export async function startDevServer(options) {
+    const host = options.host ?? '127.0.0.1';
+    const requestedPort = options.port ?? 0;
+    const server = createServer((req, res) => {
+        void handleRequest(req, res, options).catch((err) => {
+            if (!res.headersSent) {
+                writeJson(res, 500, { error: 'internal', message: errorMessage(err) });
+            }
+            else {
+                res.destroy();
+            }
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(requestedPort, host, () => {
+            server.removeListener('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        throw new Error(`dev server bound to unexpected address ${String(address)}`);
+    }
+    return {
+        host: address.address,
+        port: address.port,
+        raw: server,
+        async close() {
+            // Shut down the registry watcher FIRST so open SSE streams
+            // stop receiving events; otherwise write attempts after
+            // `server.close()` land on half-closed sockets.
+            await options.registry.close();
+            // Force-destroy open sockets so SSE clients don't hold the
+            // close promise open for their full keep-alive window.
+            server.closeAllConnections?.();
+            await new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+async function handleRequest(req, res, options) {
+    if (options.security) {
+        const result = options.security.apply(req, res);
+        if (result.outcome === 'handled')
+            return;
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        writeJson(res, 405, { error: 'method-not-allowed' });
+        return;
+    }
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    const path = url.pathname;
+    if (path === '/events' || path === '/events/') {
+        // SSE stream — lifecycle is owned by the stream handler; it
+        // returns after writing the preamble and keeps running until
+        // the client disconnects.
+        openEventStream(req, res, options.registry);
+        return;
+    }
+    if (path === '/hub' || path === '/hub/') {
+        // Hub shell is served unauthenticated (see `auth.ts` /
+        // `PUBLIC_PATHS`). The same-origin browser tab that opens the
+        // page still gets bearer-gated XHR responses — the shell
+        // embeds the token so its JS carries it automatically.
+        serveHubShell(req, res, {
+            token: options.security?.token ?? null,
+            manifest: options.manifest,
+        });
+        return;
+    }
+    if (path === '/hub/preview.js') {
+        // Public JS bundle for the iframe's module script. See
+        // `hub-preview.ts` for the rationale (browsers don't attach
+        // Authorization on element-triggered script loads).
+        await serveHubPreviewBundle(req, res);
+        return;
+    }
+    if (path === '/hub/preview' || path === '/hub/preview/') {
+        // Preview iframe shell. Public for the same reason `/hub` is
+        // public — the browser loads it before any XHR fires. The
+        // iframe reads `?ui=<id>` from its own URL; the shell sanitises
+        // the value defensively before echoing it back.
+        const selectedId = extractSelectedId(url.search.slice(1));
+        serveHubPreviewShell(req, res, {
+            token: options.security?.token ?? null,
+            selectedId,
+        });
+        return;
+    }
+    if (path === '/health' || path === '/health/') {
+        const list = await options.registry.list();
+        const issues = options.registry.getIssues();
+        writeJson(res, 200, {
+            ok: true,
+            app: options.manifest.app,
+            protocol: options.manifest.protocol,
+            uiCount: list.length,
+            issueCount: issues.length,
+        });
+        return;
+    }
+    const runtimeMatch = RUNTIME_ROUTE.exec(path);
+    if (runtimeMatch) {
+        const [, kind] = runtimeMatch;
+        const supervisor = options.getRuntimeSupervisor?.() ?? null;
+        if (!supervisor) {
+            // Always return a consistent "absent" payload rather than
+            // 404 — hosts that poll `/runtime/status` don't need to
+            // branch on HTTP status for the no-runtime case.
+            writeJson(res, 200, emptyRuntimeSnapshot());
+            return;
+        }
+        const snapshot = supervisor.snapshot();
+        if (!kind || kind === 'status') {
+            // Status endpoint returns everything EXCEPT the buffered
+            // events, so clients that only need lifecycle state don't
+            // pay the payload cost.
+            const { recentEvents: _omit, ...rest } = snapshot;
+            void _omit;
+            writeJson(res, 200, rest);
+            return;
+        }
+        if (kind === 'events') {
+            writeJson(res, 200, {
+                present: snapshot.present,
+                name: snapshot.name,
+                runId: snapshot.runId,
+                status: snapshot.status,
+                lastEventAt: snapshot.lastEventAt,
+                events: snapshot.recentEvents,
+            });
+            return;
+        }
+    }
+    const match = UI_ROUTE.exec(path);
+    if (match) {
+        const [, rawId, subresource] = match;
+        if (!rawId) {
+            const list = await options.registry.list();
+            writeJson(res, 200, list);
+            return;
+        }
+        const id = decodeURIComponent(rawId);
+        const entry = await options.registry.get(id);
+        if (!entry) {
+            writeJson(res, 404, { error: 'not-found', id });
+            return;
+        }
+        if (!subresource) {
+            writeJson(res, 200, entry);
+            return;
+        }
+        if (subresource === 'bundle') {
+            const result = await options.registry.fetchBundle(id);
+            switch (result.kind) {
+                case 'ok':
+                    writeBundle(res, result.bundle);
+                    return;
+                case 'not-found':
+                    writeJson(res, 404, { error: 'not-found', id });
+                    return;
+                case 'missing-entry':
+                    // 404 still — the contract is "no bundle," Studio collapses
+                    // this to the "no preview available" state. The body gives
+                    // the developer the exact list of paths we searched so they
+                    // know what to add (a `ggui.ui.tsx` beside the manifest, or
+                    // an `entryPoint` field in `ggui.ui.json`).
+                    writeJson(res, 404, {
+                        error: 'missing-entry',
+                        id,
+                        message: 'No compiled bundle AND no TSX entry could be resolved. Declare `entryPoint` in ggui.ui.json, ' +
+                            'or colocate a ggui.ui.tsx / index.tsx / component.tsx beside the manifest.',
+                        tried: result.tried,
+                    });
+                    return;
+                case 'compile-failed':
+                    // 422 Unprocessable Entity — the server understood the
+                    // request but couldn't produce output because the source
+                    // fails to compile. Body carries structured esbuild errors
+                    // so Studio can render the first error with its file /
+                    // line / column / highlighted line.
+                    writeJson(res, 422, {
+                        error: 'compile-failed',
+                        id,
+                        entry: result.entry,
+                        errors: result.errors,
+                        warnings: result.warnings,
+                    });
+                    return;
+            }
+        }
+    }
+    writeJson(res, 404, { error: 'not-found', path });
+}
+function writeJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload).toString(),
+    });
+    res.end(payload);
+}
+function writeBundle(res, bundle) {
+    // Streams are valid per the contract, but the LocalUiRegistry
+    // always produces string bundles today; accept both defensively so
+    // future cloud-registry wrappers drop in without a change here.
+    if (typeof bundle.code === 'string') {
+        const buffer = Buffer.from(bundle.code, 'utf-8');
+        res.writeHead(200, {
+            'content-type': bundle.contentType,
+            'content-length': buffer.byteLength.toString(),
+        });
+        res.end(buffer);
+        return;
+    }
+    res.writeHead(200, { 'content-type': bundle.contentType });
+    const reader = bundle.code.getReader();
+    void (async () => {
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                if (value !== undefined) {
+                    res.write(typeof value === 'string' ? value : Buffer.from(value));
+                }
+            }
+        }
+        finally {
+            res.end();
+        }
+    })();
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/dev-server/hub-preview.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Context the preview shell needs at boot. */
+export interface HubPreviewShellContext {
+    /** Bearer token the preview's own JS sends on data XHRs. `null`
+     * when the server was started without a security policy (tests). */
+    readonly token: string | null;
+    /** Selected UI id from the `?ui=` query param. Empty string for
+     * the no-selection state — the shell renders a tiny "pick a UI"
+     * hint rather than a blank frame. */
+    readonly selectedId: string;
+}
+/**
+ * Build the preview iframe's HTML document. Pure function so tests
+ * can exercise the rendered shape without binding a port.
+ */
+export declare function renderHubPreviewHtml(ctx: HubPreviewShellContext): string;
+/**
+ * Read the `?ui=` query param and sanitise it. A UI id coming from
+ * the URL bar is untrusted; the shell already escapes when it renders,
+ * but stripping obviously-hostile characters keeps the accepted
+ * surface tight. IDs produced by the registry are plain kebab/dot
+ * strings, so any control char or slash is a sign of tampering.
+ */
+export declare function extractSelectedId(rawQuery: string): string;
+/**
+ * Write the preview shell to `res` with no-cache headers.
+ *
+ * `X-Frame-Options: SAMEORIGIN` — the hub is the only expected
+ * embedder. A different origin trying to frame this page is blocked
+ * so the iframe's bearer-embedded bootstrap can't leak to a hostile
+ * parent.
+ */
+export declare function serveHubPreviewShell(req: IncomingMessage, res: ServerResponse, ctx: HubPreviewShellContext): void;
+export declare function resolveHubPreviewBundlePath(): string;
+/** Test seam — set an explicit bundle path (usually a temp file) so
+ * the HTTP layer can be exercised without running the esbuild step. */
+export declare function __setHubPreviewBundlePathForTest(path: string | null): void;
+/**
+ * Serve the compiled preview-client bundle at `/hub/preview.js`.
+ *
+ * The iframe's `<script type="module" src="/hub/preview.js">` tag
+ * cannot attach an `Authorization` header — browsers don't allow it
+ * on a plain script load. Matching the HTML shell's approach, this
+ * route is public; the existing origin allowlist blocks cross-origin
+ * reads, and the bundle itself is harmless code (reads from the
+ * iframe's same-origin `window.__GGUI_DEV_PREVIEW__`).
+ *
+ * On first boot + before `pnpm build` has run, the file may not
+ * exist. We return a 503 with an actionable message rather than a
+ * bare stack trace so the developer knows the build step is
+ * missing — the HTML shell in the iframe will paint a "Loading
+ * renderer…" placeholder and the console error will point to this
+ * response.
+ */
+export declare function serveHubPreviewBundle(_req: IncomingMessage, res: ServerResponse): Promise<void>;
+//# sourceMappingURL=hub-preview.d.ts.map

package/dist/dev-server/hub-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-preview.d.ts","sourceRoot":"","sources":["../../src/dev-server/hub-preview.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;wEACoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;yCAEqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,sBAAsB,GAAG,MAAM,CAqCxE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW1D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,sBAAsB,GAC1B,IAAI,CAUN;AAkCD,wBAAgB,2BAA2B,IAAI,MAAM,CAIpD;AAED;uEACuE;AACvE,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/dev-server/hub-preview.js

@@ -0,0 +1,237 @@
+/**
+ * Local dev hub — preview iframe shell.
+ *
+ * The hub at `/hub` is a code-first observability dashboard (vanilla
+ * JS, no framework). Rendering a React component there would drag the
+ * whole renderer stack into the hub's surface and violate the charter.
+ * Instead, the hub embeds `<iframe src="/hub/preview?ui=<id>">` and
+ * this module owns the iframe's HTML shell.
+ *
+ * Shape (locked 2026-04-18):
+ *
+ *   - One self-contained HTML document per iframe. Dep-free at this
+ *     layer — the React-based renderer arrives in the next commit and
+ *     mounts against a root node this shell already provides.
+ *   - Public path (bearer-exempt) for the same reason `/hub` is
+ *     public: a browser loads the HTML before it has the token. The
+ *     origin allowlist in `auth.ts` still blocks cross-origin reads,
+ *     and the shell embeds the bearer so same-origin XHRs carry it.
+ *   - Bootstrap globals sit at `window.__GGUI_DEV_PREVIEW__` (distinct
+ *     from the hub's `window.__GGUI_DEV__`) so the two pages never
+ *     accidentally alias each other's state.
+ *   - `noindex` / `no-store` / `X-Frame-Options: SAMEORIGIN` — hub
+ *     loads this iframe from the same origin; any other framing is
+ *     rejected.
+ *
+ * Invariants for this commit:
+ *
+ *   - No component rendering yet. The shell shows a loading placeholder
+ *     and the selected UI id. The actual DynamicComponent-based render
+ *     lands as the next commit on top of this plumbing.
+ *   - Selected id is validated defensively (non-empty, no control
+ *     chars, no slashes) so a crafted URL can't inject HTML into the
+ *     shell even though the server escapes it.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Build the preview iframe's HTML document. Pure function so tests
+ * can exercise the rendered shape without binding a port.
+ */
+export function renderHubPreviewHtml(ctx) {
+    const idForDisplay = escapeHtml(ctx.selectedId);
+    const bootstrap = JSON.stringify({
+        token: ctx.token,
+        selectedId: ctx.selectedId,
+    }).replace(/</g, '\\u003c');
+    const title = ctx.selectedId.length > 0
+        ? `Preview: ${idForDisplay}`
+        : 'Preview';
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>${title}</title>
+<style>${PREVIEW_CSS}</style>
+</head>
+<body>
+<main id="preview-root">
+  <div class="frame" data-state="loading">
+    <div class="pane">
+      ${ctx.selectedId.length > 0
+        ? `<div class="meta">Preview of <code>${idForDisplay}</code></div>
+           <div class="status">Loading renderer…</div>`
+        : `<div class="meta">No UI selected</div>
+           <div class="status">Pick a UI from the Discovered UIs panel to preview it here.</div>`}
+    </div>
+  </div>
+</main>
+<script>window.__GGUI_DEV_PREVIEW__ = ${bootstrap};</script>
+<script type="module" src="/hub/preview.js"></script>
+</body>
+</html>
+`;
+}
+/**
+ * Read the `?ui=` query param and sanitise it. A UI id coming from
+ * the URL bar is untrusted; the shell already escapes when it renders,
+ * but stripping obviously-hostile characters keeps the accepted
+ * surface tight. IDs produced by the registry are plain kebab/dot
+ * strings, so any control char or slash is a sign of tampering.
+ */
+export function extractSelectedId(rawQuery) {
+    const params = new URLSearchParams(rawQuery);
+    const value = (params.get('ui') ?? '').trim();
+    // Reject anything that isn't plain identifier-ish text. Registry ids
+    // are kebab/snake with dots at most; this keeps the accepted shape
+    // narrow without needing to cross-check against the live registry
+    // (the renderer's bundle fetch will 404 honestly anyway).
+    if (value.length === 0)
+        return '';
+    if (value.length > 200)
+        return '';
+    if (!/^[a-zA-Z0-9._\-:@/]+$/.test(value))
+        return '';
+    return value;
+}
+/**
+ * Write the preview shell to `res` with no-cache headers.
+ *
+ * `X-Frame-Options: SAMEORIGIN` — the hub is the only expected
+ * embedder. A different origin trying to frame this page is blocked
+ * so the iframe's bearer-embedded bootstrap can't leak to a hostile
+ * parent.
+ */
+export function serveHubPreviewShell(req, res, ctx) {
+    const html = renderHubPreviewHtml(ctx);
+    const body = Buffer.from(html, 'utf-8');
+    res.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8',
+        'content-length': body.byteLength.toString(),
+        'cache-control': 'no-store',
+        'x-frame-options': 'SAMEORIGIN',
+    });
+    res.end(body);
+}
+const HTML_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch] ?? ch);
+}
+/**
+ * Absolute path to the compiled preview-client bundle. The bundle is
+ * produced by `scripts/build-hub-preview.mjs` during `pnpm build` and
+ * lives at `dist/hub-preview/client.js`.
+ *
+ * Resolution is relative to this module's compiled location in `dist/`
+ * via `import.meta.url`:
+ *
+ *   dist/dev-server/hub-preview.js
+ *        ↓ dirname
+ *   dist/dev-server
+ *        ↓ ../hub-preview/client.js
+ *   dist/hub-preview/client.js
+ *
+ * Computed once at module load and cached. Tests override via
+ * `__setHubPreviewBundlePathForTest` (export below) so they can
+ * assert serving logic without a real build being in place.
+ */
+let bundlePathOverride = null;
+export function resolveHubPreviewBundlePath() {
+    if (bundlePathOverride !== null)
+        return bundlePathOverride;
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolvePath(here, '..', 'hub-preview', 'client.js');
+}
+/** Test seam — set an explicit bundle path (usually a temp file) so
+ * the HTTP layer can be exercised without running the esbuild step. */
+export function __setHubPreviewBundlePathForTest(path) {
+    bundlePathOverride = path;
+}
+/**
+ * Serve the compiled preview-client bundle at `/hub/preview.js`.
+ *
+ * The iframe's `<script type="module" src="/hub/preview.js">` tag
+ * cannot attach an `Authorization` header — browsers don't allow it
+ * on a plain script load. Matching the HTML shell's approach, this
+ * route is public; the existing origin allowlist blocks cross-origin
+ * reads, and the bundle itself is harmless code (reads from the
+ * iframe's same-origin `window.__GGUI_DEV_PREVIEW__`).
+ *
+ * On first boot + before `pnpm build` has run, the file may not
+ * exist. We return a 503 with an actionable message rather than a
+ * bare stack trace so the developer knows the build step is
+ * missing — the HTML shell in the iframe will paint a "Loading
+ * renderer…" placeholder and the console error will point to this
+ * response.
+ */
+export async function serveHubPreviewBundle(_req, res) {
+    const path = resolveHubPreviewBundlePath();
+    try {
+        await stat(path);
+    }
+    catch {
+        const message = 'hub preview bundle is missing. Run `pnpm --filter @ggui-ai/dev-stack build` to produce it.';
+        const body = JSON.stringify({ error: 'preview-bundle-missing', message });
+        res.writeHead(503, {
+            'content-type': 'application/json; charset=utf-8',
+            'content-length': Buffer.byteLength(body).toString(),
+            'cache-control': 'no-store',
+        });
+        res.end(body);
+        return;
+    }
+    const buffer = await readFile(path);
+    res.writeHead(200, {
+        'content-type': 'application/javascript; charset=utf-8',
+        'content-length': buffer.byteLength.toString(),
+        'cache-control': 'no-store',
+    });
+    res.end(buffer);
+}
+/**
+ * Preview CSS. Matches the hub's dark-terminal palette so the iframe
+ * blends seamlessly with the surrounding panel. Kept minimal — once
+ * the renderer mounts, the compiled UI brings its own theme.
+ */
+const PREVIEW_CSS = `
+:root { color-scheme: dark; }
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; background: #0a0a0a; color: #e7e7e7;
+  font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+body { min-height: 100vh; display: flex; }
+main { flex: 1; display: flex; }
+.frame { flex: 1; display: flex; align-items: center; justify-content: center;
+  padding: 24px; }
+.pane { max-width: 480px; display: flex; flex-direction: column; gap: 10px;
+  text-align: center; }
+.meta { font-size: 12px; color: #8a8a8a; text-transform: uppercase;
+  letter-spacing: 0.06em; }
+.meta code { color: #7cb2e8; font-family: inherit; text-transform: none;
+  letter-spacing: 0; }
+.status { color: #b8b8b8; font-size: 13px; }
+.status .dim { color: #666; }
+.tried { background: #141414; color: #8a8a8a; padding: 8px 12px;
+  border-radius: 3px; font-size: 11px; text-align: left;
+  white-space: pre-wrap; word-break: break-all; margin: 8px 0 0; }
+ul.errors { list-style: none; margin: 0; padding: 0; text-align: left; }
+ul.errors li { padding: 6px 0; border-top: 1px solid #181818; }
+ul.errors li:first-child { border-top: none; }
+pre.location { margin: 0; color: #7cb2e8; font-size: 11px;
+  font-family: inherit; text-align: left; }
+pre.error { margin: 2px 0 0; color: #e57373; font-size: 12px;
+  font-family: inherit; white-space: pre-wrap; text-align: left; }
+pre.line-text { margin: 4px 0 0; background: #141414; color: #ccc;
+  padding: 4px 8px; border-radius: 3px; font-size: 11px;
+  font-family: inherit; text-align: left; overflow-x: auto; }
+.surface { flex: 1; display: flex; align-items: stretch; padding: 16px; }
+.surface > div { flex: 1; min-width: 0; }
+`;