@pylonsync/functions 0.8.3 → 0.9.1

package/dist/design-stamp.d.ts

@@ -0,0 +1,24 @@
+export declare const DESIGN_STAMP_ATTR = "data-pylon-src";
+/** True when the design stamp should be active for this process. */
+export declare function isDesignMode(env?: Record<string, string | undefined>): boolean;
+/** Directories (relative to the project root) whose JSX gets stamped. */
+export declare const DESIGN_STAMP_DIRS: readonly ["app", "components", ".design"];
+/**
+ * Regex matching absolute paths of the `.tsx` / `.jsx` files under the scoped
+ * directories of `root`. Used as the `onLoad` filter so files outside the
+ * scope never reach the transform.
+ */
+export declare function designStampScopePattern(root: string): RegExp;
+/** Project-relative path with forward slashes, for the attribute value. */
+export declare function relativeSourcePath(root: string, absPath: string): string;
+/**
+ * Add `data-pylon-src="<relPath>:<line>:<col>"` to every DOM element in a
+ * JSX/TSX source. `line` and `col` are 1-based and point at the opening `<`.
+ * Returns the source unchanged when no element needs a stamp.
+ */
+export declare function stampJsxSource(source: string, relPath: string): string;
+/**
+ * Register the Bun plugin for the project rooted at `root`. Only the files
+ * matched by `designStampScopePattern(root)` are transformed.
+ */
+export declare function registerDesignStampPlugin(root?: string): void;

package/dist/ssr-runtime.d.ts

@@ -74,6 +74,13 @@ export interface RenderRouteMessage {
      * override it via `response.setStatus`.
      */
     initial_status?: number;
+    /**
+     * Design render (dev only). No hydration tail, no dev HUD, no live-reload
+     * snippet; the stylesheet is inlined with no size cap and the head gets a
+     * `<base href>` so the HTML works inside a `srcdoc` iframe. See
+     * `designHeadBlob`.
+     */
+    design?: boolean;
 }
 type Send = (msg: Record<string, unknown>) => void;
 /**
@@ -403,7 +410,13 @@ export declare function buildDevHudChunk(devInfo: Record<string, unknown>): stri
  * install.
  */
 export declare function buildCloudBadgeChunk(env?: Record<string, string | undefined>): string;
-export declare function cssHeadTag(css: string, prefix: string, routeOverride?: boolean): Promise<string>;
+export declare function cssHeadTag(css: string, prefix: string, routeOverride?: boolean, maxBytes?: number): Promise<string>;
+/**
+ * `<base href>` for a design render. The HTML is shown in a `srcdoc` iframe,
+ * where relative URLs have no origin to resolve against; the base points them
+ * at the dev server. Uses the request's Host, else `127.0.0.1:<PYLON_PORT>`.
+ */
+export declare function designBaseHref(headers: Record<string, string | undefined>, env?: Record<string, string | undefined>): string;
 /**
  * Build the hydration tail appended after React's stream EOFs: the
  * `__PYLON_DATA__` JSON blob (props + ssrData) + the per-route entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -48,10 +48,10 @@
   "license": "MIT OR Apache-2.0",
   "dependencies": {
     "satori": "^0.26.0",
-    "@resvg/resvg-wasm": "^2.6.2"
+    "@resvg/resvg-wasm": "^2.6.2",
+    "typescript": "^5.5"
   },
   "devDependencies": {
-    "typescript": "^5.5",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "@types/react": "^19.0.0",

package/src/design-stamp.test.ts

@@ -0,0 +1,170 @@
+// Design-mode JSX stamp: every DOM element under app/, components/ and
+// .design/ gets `data-pylon-src="<rel>:<line>:<col>"`. Components are left
+// alone, the transform is idempotent, and files outside the scoped dirs are
+// never touched. The last case runs the real preload in a child Bun process
+// so the plugin wiring (filter + loader) is covered, not only the transform.
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DESIGN_STAMP_ATTR,
+  designStampScopePattern,
+  relativeSourcePath,
+  stampJsxSource,
+} from "./design-stamp";
+
+const STAMP = /data-pylon-src="([^"]+)"/g;
+
+function stamps(src: string): string[] {
+  return [...src.matchAll(STAMP)].map((m) => m[1]);
+}
+
+describe("stampJsxSource", () => {
+  test("stamps DOM elements with 1-based line and column of the opening <", () => {
+    const src = [
+      "export default function Page() {",
+      "  return (",
+      "    <main className=\"p-4\">",
+      "      <h1>Hello</h1>",
+      "      <img src=\"/a.png\" />",
+      "    </main>",
+      "  );",
+      "}",
+      "",
+    ].join("\n");
+    const out = stampJsxSource(src, "app/page.tsx");
+    expect(stamps(out)).toEqual([
+      "app/page.tsx:3:5",
+      "app/page.tsx:4:7",
+      "app/page.tsx:5:7",
+    ]);
+    // Existing attributes survive.
+    expect(out).toContain('className="p-4"');
+    expect(out).toContain('src="/a.png"');
+  });
+
+  test("components and member-expression tags are not stamped", () => {
+    const src = [
+      "import { Card } from \"../components/card\";",
+      "const UI = { Box: (p: any) => <div {...p} /> };",
+      "export default function Page() {",
+      "  return (",
+      "    <Card title=\"x\">",
+      "      <UI.Box>",
+      "        <span>inner</span>",
+      "      </UI.Box>",
+      "      <Card.Footer />",
+      "    </Card>",
+      "  );",
+      "}",
+      "",
+    ].join("\n");
+    const out = stampJsxSource(src, "app/page.tsx");
+    // Only the <div> in the inline component and the <span> are DOM.
+    expect(stamps(out)).toEqual(["app/page.tsx:2:31", "app/page.tsx:7:9"]);
+    expect(out).not.toMatch(/<Card[^>]*data-pylon-src/);
+    expect(out).not.toMatch(/<UI\.Box[^>]*data-pylon-src/);
+    expect(out).not.toMatch(/<Card\.Footer[^>]*data-pylon-src/);
+  });
+
+  test("is idempotent and keeps a hand-written attribute", () => {
+    const src = [
+      "export const A = () => (",
+      "  <section data-pylon-src=\"custom:1:1\">",
+      "    <p>x</p>",
+      "  </section>",
+      ");",
+      "",
+    ].join("\n");
+    const once = stampJsxSource(src, "components/a.tsx");
+    expect(stamps(once)).toEqual(["custom:1:1", "components/a.tsx:3:5"]);
+    const twice = stampJsxSource(once, "components/a.tsx");
+    expect(twice).toBe(once);
+  });
+
+  test("returns the source unchanged when there is nothing to stamp", () => {
+    const src = "export const n = 1;\nexport const C = () => <Comp />;\n";
+    expect(stampJsxSource(src, "app/x.tsx")).toBe(src);
+  });
+
+  test("handles fragments, conditionals, and .jsx files", () => {
+    const src = [
+      "export default function P({ ok }) {",
+      "  return (",
+      "    <>",
+      "      {ok ? <b>yes</b> : <i>no</i>}",
+      "      {[1, 2].map((n) => <li key={n}>{n}</li>)}",
+      "    </>",
+      "  );",
+      "}",
+      "",
+    ].join("\n");
+    const out = stampJsxSource(src, "app/p.jsx");
+    expect(stamps(out)).toEqual(["app/p.jsx:4:13", "app/p.jsx:4:26", "app/p.jsx:5:26"]);
+    expect(out).toContain("key={n}");
+  });
+});
+
+describe("scope", () => {
+  test("pattern matches only tsx/jsx under app, components and .design", () => {
+    const root = "/proj/my app";
+    const re = designStampScopePattern(root);
+    expect(re.test("/proj/my app/app/page.tsx")).toBe(true);
+    expect(re.test("/proj/my app/app/blog/[slug]/page.tsx")).toBe(true);
+    expect(re.test("/proj/my app/components/card.jsx")).toBe(true);
+    expect(re.test("/proj/my app/.design/variants/v1.tsx")).toBe(true);
+    expect(re.test("/proj/my app/lib/ui.tsx")).toBe(false);
+    expect(re.test("/proj/my app/app/data.ts")).toBe(false);
+    expect(re.test("/proj/my app/node_modules/x/app/page.tsx")).toBe(false);
+    expect(re.test("/proj/my apple/app/page.tsx")).toBe(false);
+  });
+
+  test("relativeSourcePath strips the root", () => {
+    expect(relativeSourcePath("/proj", "/proj/app/page.tsx")).toBe("app/page.tsx");
+    expect(relativeSourcePath("/proj/", "/proj/.design/v.tsx")).toBe(".design/v.tsx");
+  });
+});
+
+// The preload itself: a child Bun process with PYLON_DESIGN_MODE=1 and
+// `--preload design-stamp.ts` renders two modules to static markup. The one
+// under app/ is stamped; the one under lib/ is not.
+test("preload stamps app/ modules and leaves lib/ modules alone", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-design-stamp-"));
+  mkdirSync(join(dir, "app"), { recursive: true });
+  mkdirSync(join(dir, "lib"), { recursive: true });
+  const body =
+    "export default function C() { return <div className=\"c\"><span>t</span></div>; }\n";
+  writeFileSync(join(dir, "app", "page.tsx"), body);
+  writeFileSync(join(dir, "lib", "widget.tsx"), body);
+  // Resolve react from this package's node_modules (the temp dir has none).
+  const reactDir = join(import.meta.dir, "..");
+  const probe = `
+import React from ${JSON.stringify(join(reactDir, "node_modules/react"))};
+import { renderToStaticMarkup } from ${JSON.stringify(join(reactDir, "node_modules/react-dom/server"))};
+const a = (await import(${JSON.stringify(join(dir, "app/page.tsx"))})).default;
+const b = (await import(${JSON.stringify(join(dir, "lib/widget.tsx"))})).default;
+console.log("APP " + renderToStaticMarkup(React.createElement(a)));
+console.log("LIB " + renderToStaticMarkup(React.createElement(b)));
+`;
+  writeFileSync(join(dir, "probe.ts"), probe);
+  const preload = join(import.meta.dir, "design-stamp.ts");
+  const proc = Bun.spawn(["bun", "run", "--preload", preload, join(dir, "probe.ts")], {
+    cwd: dir,
+    env: { ...process.env, PYLON_DESIGN_MODE: "1" },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  expect(await proc.exited).toBe(0);
+  if (err.trim()) console.error(err);
+  const app = out.split("\n").find((l) => l.startsWith("APP "))!;
+  const lib = out.split("\n").find((l) => l.startsWith("LIB "))!;
+  expect(app).toContain(`${DESIGN_STAMP_ATTR}="app/page.tsx:1:38"`);
+  expect(app).toContain(`${DESIGN_STAMP_ATTR}="app/page.tsx:1:57"`);
+  expect(lib).not.toContain(DESIGN_STAMP_ATTR);
+});

package/src/design-stamp.ts

@@ -0,0 +1,160 @@
+/**
+ * Design-mode JSX source stamp.
+ *
+ * A Bun preload plugin. When `PYLON_DESIGN_MODE=1`, every `.tsx` / `.jsx`
+ * module under the app's `app/`, `components/`, and `.design/` directories is
+ * rewritten on load so each DOM element carries
+ * `data-pylon-src="<relative path>:<line>:<col>"`. The design canvas reads the
+ * attribute off the rendered HTML to map a clicked element back to its source.
+ *
+ * The rewrite runs on the SSR runner only. The client bundler does not load
+ * this plugin, so browser bundles are unchanged.
+ *
+ * The transform uses the TypeScript compiler API. Components (tags that start
+ * with an uppercase letter, or member expressions) are left alone; their own
+ * DOM elements are stamped where they are written. An element that already has
+ * the attribute keeps it, so the transform is idempotent.
+ *
+ * Load with `bun run --preload <this file> ...`. The plugin registers itself
+ * on import; `stampJsxSource` and `designStampScopePattern` are exported for
+ * tests and for the runtime that wires the preload.
+ */
+import ts from "typescript";
+
+export const DESIGN_STAMP_ATTR = "data-pylon-src";
+
+/** True when the design stamp should be active for this process. */
+export function isDesignMode(env: Record<string, string | undefined> = process.env): boolean {
+  const v = env.PYLON_DESIGN_MODE;
+  return v === "1" || v?.toLowerCase() === "true";
+}
+
+/** Directories (relative to the project root) whose JSX gets stamped. */
+export const DESIGN_STAMP_DIRS = ["app", "components", ".design"] as const;
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Regex matching absolute paths of the `.tsx` / `.jsx` files under the scoped
+ * directories of `root`. Used as the `onLoad` filter so files outside the
+ * scope never reach the transform.
+ */
+export function designStampScopePattern(root: string): RegExp {
+  const base = escapeRegExp(root.replace(/[\\/]+$/, ""));
+  const dirs = DESIGN_STAMP_DIRS.map(escapeRegExp).join("|");
+  return new RegExp(`^${base}[\\\\/](?:${dirs})[\\\\/].*\\.(?:tsx|jsx)$`);
+}
+
+/** Project-relative path with forward slashes, for the attribute value. */
+export function relativeSourcePath(root: string, absPath: string): string {
+  const base = root.replace(/[\\/]+$/, "");
+  let rel = absPath.startsWith(base) ? absPath.slice(base.length) : absPath;
+  rel = rel.replace(/^[\\/]+/, "").replace(/\\/g, "/");
+  return rel;
+}
+
+function isDomTag(tagName: ts.JsxTagNameExpression): boolean {
+  return ts.isIdentifier(tagName) && /^[a-z]/.test(tagName.text);
+}
+
+function hasStampAttr(attrs: ts.JsxAttributes): boolean {
+  return attrs.properties.some(
+    (p) => ts.isJsxAttribute(p) && ts.isIdentifier(p.name) && p.name.text === DESIGN_STAMP_ATTR,
+  );
+}
+
+/**
+ * Add `data-pylon-src="<relPath>:<line>:<col>"` to every DOM element in a
+ * JSX/TSX source. `line` and `col` are 1-based and point at the opening `<`.
+ * Returns the source unchanged when no element needs a stamp.
+ */
+export function stampJsxSource(source: string, relPath: string): string {
+  const kind = relPath.endsWith(".jsx") ? ts.ScriptKind.JSX : ts.ScriptKind.TSX;
+  const sourceFile = ts.createSourceFile(relPath, source, ts.ScriptTarget.Latest, true, kind);
+  let stamped = 0;
+
+  const transformer: ts.TransformerFactory<ts.SourceFile> = (ctx) => {
+    const f = ctx.factory;
+    const stampFor = (node: ts.Node): ts.JsxAttribute => {
+      const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+        node.getStart(sourceFile),
+      );
+      const value = `${relPath}:${line + 1}:${character + 1}`;
+      return f.createJsxAttribute(
+        f.createIdentifier(DESIGN_STAMP_ATTR),
+        f.createStringLiteral(value),
+      );
+    };
+    const withStamp = (attrs: ts.JsxAttributes, attr: ts.JsxAttribute): ts.JsxAttributes =>
+      f.updateJsxAttributes(attrs, [...attrs.properties, attr]);
+
+    const visit: ts.Visitor = (node) => {
+      if (ts.isJsxOpeningElement(node)) {
+        const shouldStamp = isDomTag(node.tagName) && !hasStampAttr(node.attributes);
+        const attr = shouldStamp ? stampFor(node) : null;
+        const visited = ts.visitEachChild(node, visit, ctx);
+        if (!attr) return visited;
+        stamped++;
+        return f.updateJsxOpeningElement(
+          visited,
+          visited.tagName,
+          visited.typeArguments,
+          withStamp(visited.attributes, attr),
+        );
+      }
+      if (ts.isJsxSelfClosingElement(node)) {
+        const shouldStamp = isDomTag(node.tagName) && !hasStampAttr(node.attributes);
+        const attr = shouldStamp ? stampFor(node) : null;
+        const visited = ts.visitEachChild(node, visit, ctx);
+        if (!attr) return visited;
+        stamped++;
+        return f.updateJsxSelfClosingElement(
+          visited,
+          visited.tagName,
+          visited.typeArguments,
+          withStamp(visited.attributes, attr),
+        );
+      }
+      return ts.visitEachChild(node, visit, ctx);
+    };
+    return (root) => ts.visitNode(root, visit) as ts.SourceFile;
+  };
+
+  const result = ts.transform(sourceFile, [transformer], { jsx: ts.JsxEmit.Preserve });
+  try {
+    if (stamped === 0) return source;
+    const printer = ts.createPrinter({
+      newLine: ts.NewLineKind.LineFeed,
+      removeComments: false,
+    });
+    return printer.printFile(result.transformed[0]);
+  } finally {
+    result.dispose();
+  }
+}
+
+/**
+ * Register the Bun plugin for the project rooted at `root`. Only the files
+ * matched by `designStampScopePattern(root)` are transformed.
+ */
+export function registerDesignStampPlugin(root: string = process.cwd()): void {
+  const filter = designStampScopePattern(root);
+  Bun.plugin({
+    name: "pylon-design-stamp",
+    setup(build) {
+      build.onLoad({ filter }, async (args) => {
+        const source = await Bun.file(args.path).text();
+        const rel = relativeSourcePath(root, args.path);
+        return { contents: stampJsxSource(source, rel), loader: "tsx" };
+      });
+    },
+  });
+}
+
+// Preload entry: `bun run --preload design-stamp.ts`. Registration is gated on
+// the env so importing this module from a test without the flag is a no-op.
+if (isDesignMode()) {
+  registerDesignStampPlugin(process.cwd());
+}

package/src/runtime-returned-error.test.ts

@@ -0,0 +1,89 @@
+/**
+ * A handler that RETURNS `ctx.error(...)` instead of throwing it must
+ * still fail the call. An Error has no JSON shape, so a returned one
+ * used to reach the client as HTTP 200 with `{}` — a forged proof
+ * "passed" because the author wrote `return` where `throw` belonged.
+ *
+ * Same child-process harness as runtime-db.test.ts: runtime.ts runs
+ * main() on import, loads the functions dir from argv[2], and speaks
+ * NDJSON on stdin/stdout like the Rust host.
+ */
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+const DEFINE = join(import.meta.dir, "index.ts");
+
+function frames(text: string): Record<string, unknown>[] {
+  return text
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+test("a returned ctx.error rejects the call with its code", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-returned-error-"));
+  mkdirSync(join(dir, "functions"));
+  writeFileSync(
+    join(dir, "functions", "checkProof.ts"),
+    `import { query } from ${JSON.stringify(DEFINE)};
+export default query({
+  args: {},
+  auth: "public",
+  async handler(ctx) {
+    // Wrong on purpose: return instead of throw.
+    return ctx.error("INVALID_PROOF", "proof rejected") as unknown as { ok: boolean };
+  },
+});
+`,
+  );
+  writeFileSync(
+    join(dir, "functions", "plain.ts"),
+    `import { query } from ${JSON.stringify(DEFINE)};
+export default query({
+  args: {},
+  auth: "public",
+  async handler() {
+    return { ok: true };
+  },
+});
+`,
+  );
+
+  const proc = Bun.spawn([process.execPath, RUNTIME, "functions"], {
+    cwd: dir,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const reader = proc.stdout.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  let seen: Record<string, unknown>[] = [];
+  const until = async (pred: (f: Record<string, unknown>[]) => boolean) => {
+    while (!pred(seen)) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      seen = frames(buffered);
+    }
+  };
+
+  await until((f) => f.some((m) => m.type === "ready"));
+  const send = (msg: Record<string, unknown>) =>
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+  const auth = { user_id: null, is_admin: false };
+  send({ type: "call", call_id: "c_bad", fn_name: "checkProof", fn_type: "query", args: {}, auth });
+  send({ type: "call", call_id: "c_ok", fn_name: "plain", fn_type: "query", args: {}, auth });
+  await proc.stdin.flush();
+  await until((f) => f.some((m) => m.call_id === "c_bad") && f.some((m) => m.call_id === "c_ok"));
+  proc.kill();
+
+  const bad = seen.find((m) => m.call_id === "c_bad");
+  expect(bad).toMatchObject({ type: "error", code: "INVALID_PROOF", message: "proof rejected" });
+  const ok = seen.find((m) => m.call_id === "c_ok");
+  expect(ok).toMatchObject({ type: "return", value: { ok: true } });
+});

package/src/runtime.ts

@@ -1394,6 +1394,11 @@ async function handleCall(msg: CallMessage): Promise<void> {
   try {
     const result = await def.handler(ctx, msg.args);
     if (cancelledCalls.has(msg.call_id)) return;
+    // `return ctx.error(...)` instead of `throw ctx.error(...)` is a
+    // common slip. An Error has no JSON shape, so a returned one can
+    // only mean the handler meant to fail: treat it as thrown so the
+    // caller gets the error code, not a 200 with `{}`.
+    if (result instanceof Error) throw result;
     send({
       type: "return",
       call_id: msg.call_id,

package/src/ssr-design-render.test.ts

@@ -0,0 +1,159 @@
+// Design render (`RenderRouteMessage.design: true`): the document the design
+// canvas loads into a `srcdoc` iframe. Compared with the same page rendered
+// normally in dev mode, it must have
+//   - a `<base href>` first in the injected head blob,
+//   - the stylesheet inlined even when it is over PYLON_SSR_INLINE_CSS_MAX,
+//   - no modulepreload links, no `__PYLON_DATA__`, no module script,
+//   - no live-reload snippet and no dev HUD.
+//
+// ssr-runtime.ts pulls in runtime.ts (the bun runner entrypoint, which runs
+// main() on import), so — like ssr-raw-get.test.ts — the render runs in a child
+// process with a kept-open stdin pipe and reports its frames over stderr.
+
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { designBaseHref } from "./ssr-runtime";
+
+const SSR_RUNTIME = join(import.meta.dir, "ssr-runtime.ts");
+const PKG_NODE_MODULES = join(import.meta.dir, "..", "node_modules");
+
+interface Frame {
+  type: string;
+  status?: number;
+  headers?: Record<string, string>;
+  data?: string;
+}
+
+function makeApp(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-design-render-"));
+  mkdirSync(join(dir, "app"), { recursive: true });
+  mkdirSync(join(dir, ".pylon", "client-build"), { recursive: true });
+  // react / react-dom resolve from this package's install.
+  symlinkSync(PKG_NODE_MODULES, join(dir, "node_modules"), "dir");
+  writeFileSync(
+    join(dir, "app", "layout.tsx"),
+    `export default function Layout({ children }: any) {
+  return <html><head><title>t</title></head><body><main id="root">{children}</main></body></html>;
+}
+`,
+  );
+  writeFileSync(
+    join(dir, "app", "page.tsx"),
+    `export default function Page() {
+  return <section className="hero"><h1>Hello</h1><img src="/logo.png" /></section>;
+}
+`,
+  );
+  // A stylesheet larger than the default 32KB inline cap.
+  const css = ".hero{padding:1rem}\n" + "/* pad */\n".repeat(5000);
+  writeFileSync(join(dir, ".pylon", "client-build", "app.css"), css);
+  writeFileSync(join(dir, ".pylon", "client-build", "entry.js"), "");
+  writeFileSync(
+    join(dir, ".pylon", "client-build", "manifest.json"),
+    JSON.stringify({
+      outdir: ".pylon/client-build",
+      public_prefix: "/_pylon/build/",
+      routes: {
+        "app/page": { file: "entry.js", imports: ["chunks/shared.js"], css: ["app.css"] },
+      },
+    }),
+  );
+  return dir;
+}
+
+async function render(dir: string, design: boolean): Promise<{ frames: Frame[]; html: string }> {
+  const msg = {
+    type: "render_route",
+    call_id: "c1",
+    component: "app/page",
+    layouts: ["app/layout"],
+    route_path: "/",
+    url: "/",
+    params: {},
+    search_params: {},
+    headers: { host: "127.0.0.1:4599" },
+    cookies: {},
+    auth: { user_id: null, is_admin: false, tenant_id: null, roles: [] },
+    design,
+  };
+  const probe = `
+import { handleRenderRoute } from ${JSON.stringify(SSR_RUNTIME)};
+const frames = [];
+await handleRenderRoute(${JSON.stringify(msg)}, (m) => frames.push(m));
+console.error("FRAMES " + JSON.stringify(frames));
+setTimeout(() => process.exit(0), 50);
+`;
+  const probePath = join(dir, design ? "probe-design.ts" : "probe-plain.ts");
+  writeFileSync(probePath, probe);
+  const proc = Bun.spawn(["bun", "run", probePath], {
+    cwd: dir,
+    env: { ...process.env, PYLON_DEV_MODE: "1" },
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  // runtime.ts prefixes console.error lines with "[error] ".
+  const line = err.split("\n").find((l) => l.includes("FRAMES "));
+  if (code !== 0 || !line) {
+    throw new Error(`probe failed (exit ${code})\nstdout: ${out}\nstderr: ${err}`);
+  }
+  const frames = JSON.parse(line.slice(line.indexOf("FRAMES ") + "FRAMES ".length)) as Frame[];
+  const html = frames
+    .filter((f) => f.type === "render_chunk")
+    .map((f) => Buffer.from(f.data!, "base64").toString("utf8"))
+    .join("");
+  return { frames, html };
+}
+
+test("designBaseHref uses the request host, else 127.0.0.1:PYLON_PORT", () => {
+  expect(designBaseHref({ host: "localhost:4321" })).toBe('<base href="http://localhost:4321/">');
+  expect(designBaseHref({}, { PYLON_PORT: "5000" })).toBe('<base href="http://127.0.0.1:5000/">');
+  expect(designBaseHref({}, {})).toBe('<base href="http://127.0.0.1:4321/">');
+});
+
+test("design render: base href, inlined CSS, no hydration, no dev chrome", async () => {
+  const dir = makeApp();
+  const { frames, html } = await render(dir, true);
+  expect(frames[0].type).toBe("response_start");
+  expect(frames[0].status).toBe(200);
+  expect(frames[frames.length - 1].type).toBe("render_done");
+
+  // Page DOM is intact.
+  expect(html).toContain('<section class="hero"');
+  expect(html).toContain('<img src="/logo.png"');
+  // <base href> is the first injected head tag.
+  const headEnd = html.indexOf("</head>");
+  const base = html.indexOf('<base href="http://127.0.0.1:4599/">');
+  expect(base).toBeGreaterThan(-1);
+  expect(base).toBeLessThan(headEnd);
+  const style = html.indexOf('<style data-pylon-css="app.css">');
+  expect(style).toBeGreaterThan(base);
+  expect(html).toContain(".hero{padding:1rem}");
+  expect(html).not.toContain('<link rel="stylesheet"');
+  expect(html).not.toContain("modulepreload");
+  // No hydration, no dev chrome.
+  expect(html).not.toContain("__PYLON_DATA__");
+  expect(html).not.toContain('<script type="module"');
+  expect(html).not.toContain("/_pylon/dev/live");
+  expect(html).not.toContain("__pylon_hud");
+  expect(html).not.toMatch(/<script/);
+});
+
+test("the same page rendered normally in dev mode keeps hydration and dev chrome", async () => {
+  const dir = makeApp();
+  const { html } = await render(dir, false);
+  expect(html).not.toContain("<base href");
+  // Over the 32KB cap → the link, not an inline sheet.
+  expect(html).toContain('<link rel="stylesheet" href="/_pylon/build/app.css">');
+  expect(html).toContain("modulepreload");
+  expect(html).toContain("__PYLON_DATA__");
+  expect(html).toContain('<script type="module"');
+  expect(html).toContain("/_pylon/dev/live");
+});

package/src/ssr-runtime.ts

@@ -93,6 +93,13 @@ export interface RenderRouteMessage {
    * override it via `response.setStatus`.
    */
   initial_status?: number;
+  /**
+   * Design render (dev only). No hydration tail, no dev HUD, no live-reload
+   * snippet; the stylesheet is inlined with no size cap and the head gets a
+   * `<base href>` so the HTML works inside a `srcdoc` iframe. See
+   * `designHeadBlob`.
+   */
+  design?: boolean;
 }
 
 type Send = (msg: Record<string, unknown>) => void;
@@ -1923,6 +1930,9 @@ export async function cssHeadTag(
   css: string,
   prefix: string,
   routeOverride?: boolean,
+  // Size cap override. A design render passes `Infinity`: the whole sheet is
+  // inlined so the HTML is self-contained.
+  maxBytes?: number,
 ): Promise<string> {
   const link = `<link rel="stylesheet" href="${prefix}${css}">`;
   // Per-route `export const inlineCss = true|false` beats the env
@@ -1932,7 +1942,10 @@ export async function cssHeadTag(
     routeOverride ??
     /^(1|true)$/i.test(process.env.PYLON_SSR_INLINE_CSS ?? "");
   if (!enabled) return link;
-  let cached = inlineCssCache.get(css);
+  const max =
+    maxBytes ?? (Number(process.env.PYLON_SSR_INLINE_CSS_MAX ?? "") || 32768);
+  const cacheKey = `${max}:${css}`;
+  let cached = inlineCssCache.get(cacheKey);
   if (cached === undefined) {
     cached = null;
     try {
@@ -1940,7 +1953,6 @@ export async function cssHeadTag(
       const manifest: any = await getManifest();
       const fs = await import("fs");
       const path = await import("path");
-      const max = Number(process.env.PYLON_SSR_INLINE_CSS_MAX ?? "") || 32768;
       const file = path.join(
         process.cwd(),
         manifest.outdir || ".pylon/client-build",
@@ -1955,13 +1967,66 @@ export async function cssHeadTag(
       cached = null;
     }
     if (inlineCssCache.size > 64) inlineCssCache.clear();
-    inlineCssCache.set(css, cached);
+    inlineCssCache.set(cacheKey, cached);
   }
   return cached === null
     ? link
     : `<style data-pylon-css="${css}">${cached}</style>`;
 }
 
+/**
+ * `<base href>` for a design render. The HTML is shown in a `srcdoc` iframe,
+ * where relative URLs have no origin to resolve against; the base points them
+ * at the dev server. Uses the request's Host, else `127.0.0.1:<PYLON_PORT>`.
+ */
+export function designBaseHref(
+  headers: Record<string, string | undefined>,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const host = (headers.host ?? "").trim();
+  const origin = host
+    ? `http://${host}`
+    : `http://127.0.0.1:${env.PYLON_PORT || "4321"}`;
+  return `<base href="${origin.replace(/"/g, "%22")}/">`;
+}
+
+/**
+ * Head blob for a design render: `<base href>` first, then fonts, then every
+ * route stylesheet inlined with no size cap. No modulepreloads: the page does
+ * not hydrate, so no client chunk is fetched.
+ */
+async function designHeadBlob(
+  headers: Record<string, string | undefined>,
+  manifestRoute: { css: string[] } | null,
+  publicPrefix: string,
+): Promise<string> {
+  let blob = designBaseHref(headers);
+  blob += await buildFontHeadBlob();
+  if (manifestRoute) {
+    for (const css of manifestRoute.css) {
+      blob += await cssHeadTag(css, publicPrefix, true, Infinity);
+    }
+    return blob;
+  }
+  // No per-route entry: inline the stylesheet union like the boundary path.
+  try {
+    const { getManifest } = await import("./ssr-client-bundler");
+    const manifest = await getManifest();
+    const prefix = manifest.public_prefix || "/_pylon/build/";
+    const seen = new Set<string>();
+    for (const route of Object.values(manifest.routes || {}) as any[]) {
+      for (const css of (route.css || []) as string[]) {
+        if (seen.has(css)) continue;
+        seen.add(css);
+        blob += await cssHeadTag(css, prefix, true, Infinity);
+      }
+    }
+  } catch {
+    // Unstyled design render; the canvas still shows the DOM.
+  }
+  return blob;
+}
+
 async function collectBoundaryHeadBlob(): Promise<string> {
   try {
     const { getManifest } = await import("./ssr-client-bundler");
@@ -2240,6 +2305,8 @@ async function renderBoundaryToClient(
     kind: "error" | "not-found";
     errorForClient?: { message: string; digest?: string };
   },
+  // Design render: no hydration tail, inlined CSS, `<base href>`.
+  design?: { headers: Record<string, string | undefined> },
 ): Promise<void> {
   const stream: ReadableStream<Uint8Array> = await renderToReadableStream(tree, {
     onError(e: unknown) {
@@ -2264,7 +2331,9 @@ async function renderBoundaryToClient(
       manifestRoute = null;
     }
   }
-  if (manifestRoute) {
+  if (design) {
+    headBlob = await designHeadBlob(design.headers, manifestRoute, publicPrefix);
+  } else if (manifestRoute) {
     headBlob += await buildFontHeadBlob();
     const co = /^https?:\/\//i.test(publicPrefix) ? " crossorigin" : "";
     for (const css of manifestRoute.css) {
@@ -2293,9 +2362,9 @@ async function renderBoundaryToClient(
     stream.getReader(),
     headBlob,
     sendChunk,
-    buildCloudBadgeChunk(),
+    design ? "" : buildCloudBadgeChunk(),
   );
-  if (tail && manifestRoute) {
+  if (tail && manifestRoute && !design) {
     const tailHtml = buildHydrationTail({
       component: tail.component,
       layouts: tail.layouts,
@@ -2329,6 +2398,7 @@ async function tryRenderBoundary(
     callId: string;
     status: number;
     headers: Record<string, string>;
+    design?: { headers: Record<string, string | undefined> };
   },
 ): Promise<boolean> {
   const { React, renderToReadableStream, cwd, componentPath, fileName, props, send, callId, status, headers } =
@@ -2417,6 +2487,7 @@ async function tryRenderBoundary(
         kind: fileName === "error" ? "error" : "not-found",
         errorForClient,
       },
+      opts.design,
     );
     return true;
   } catch (e) {
@@ -3323,6 +3394,9 @@ export async function handleRenderRoute(
     // render still runs (it is what resolves serverData), but the response
     // carries only the head metadata and the data.
     const navRender = isNavRequest(msg.headers as Record<string, unknown>);
+    // Design render (dev only, set by the host for `X-Pylon-Design: 1` and
+    // `/_pylon/dev/render`): static HTML for the design canvas.
+    const designRender = msg.design === true && !navRender;
 
     // loading.tsx (#278): the nearest `loading` module — walked up from the
     // page dir, like not-found/error — becomes ONE route-level Suspense
@@ -3641,7 +3715,13 @@ export async function handleRenderRoute(
     // modulepreloads. The entry script tag stays in the body-tail
     // (it needs the inline __PYLON_DATA__ to have been parsed first).
     let headBlob = "";
-    if (preloadManifestRoute) {
+    if (designRender) {
+      headBlob = await designHeadBlob(
+        msg.headers,
+        preloadManifestRoute,
+        preloadPublicPrefix,
+      );
+    } else if (preloadManifestRoute) {
       headBlob += await buildFontHeadBlob();
       const co = /^https?:\/\//i.test(preloadPublicPrefix) ? " crossorigin" : "";
       const inlineOverride =
@@ -3704,7 +3784,7 @@ export async function handleRenderRoute(
         stream.getReader(),
         headBlob,
         sendChunk,
-        buildCloudBadgeChunk(),
+        designRender ? "" : buildCloudBadgeChunk(),
       );
     }
 
@@ -3773,7 +3853,9 @@ export async function handleRenderRoute(
     // load. `buildHydrationTail` does the props strip (serverData/response +
     // the security headers/cookies strip) + the </script> + U+2028/2029
     // escaping. The CSS/modulepreload links were already injected into <head>.
-    const wantsHydration = !isBoundaryComponent || !!preloadManifestRoute;
+    // A design render never hydrates: the canvas owns the DOM.
+    const wantsHydration =
+      !designRender && (!isBoundaryComponent || !!preloadManifestRoute);
     if (wantsHydration) {
       const tail = buildHydrationTail({
         component: msg.component,
@@ -3808,7 +3890,7 @@ export async function handleRenderRoute(
     //
     // Never on a navigation response: there is no document for the overlay to
     // attach to, and its blob would dwarf the payload it rode in on.
-    if (devVerdict && !navRender) {
+    if (devVerdict && !navRender && !designRender) {
       const renderMs = Math.round((performance.now() - renderStart) * 10) / 10;
       // Build-level failures that degraded this page (currently: the
       // Tailwind compile). Dev-only and unmissable — the HUD paints a
@@ -3887,6 +3969,7 @@ export async function handleRenderRoute(
           callId: msg.call_id,
           status: 404,
           headers: finalizeHeaders(responseState),
+          design: msg.design === true ? { headers: msg.headers } : undefined,
         })
       ) {
         return;
@@ -3924,6 +4007,7 @@ export async function handleRenderRoute(
         callId: msg.call_id,
         status: 500,
         headers: finalizeHeaders(responseState),
+        design: msg.design === true ? { headers: msg.headers } : undefined,
       })
     ) {
       return;