@canmi/seam-react 0.2.3

package/README.md

@@ -0,0 +1,34 @@
+# @canmi/seam-react
+
+React bindings for SeamJS, providing hooks and components to consume server-injected data and real-time subscriptions.
+
+## Key Exports
+
+| Export                | Purpose                                                       |
+| --------------------- | ------------------------------------------------------------- |
+| `defineRoutes`        | Define client-side route configuration                        |
+| `useSeamData`         | Access server-injected data from `SeamDataProvider` context   |
+| `SeamDataProvider`    | Context provider for server data                              |
+| `parseSeamData`       | Parse JSON from `<script id="__SEAM_DATA__">`                 |
+| `buildSentinelData`   | Build sentinel data for skeleton rendering                    |
+| `useSeamSubscription` | Hook for SSE subscriptions, returns `{ data, error, status }` |
+
+## Structure
+
+- `src/index.ts` — Public API exports
+- `src/use-seam-data.ts` — Data provider and hooks
+- `src/use-seam-subscription.ts` — SSE subscription hook
+- `src/define-routes.ts` — Route definition utilities
+- `src/sentinel.ts` — Sentinel data builder for skeleton rendering
+- `scripts/` — Build-time scripts
+
+## Development
+
+- Build: `bun run --filter '@canmi/seam-react' build`
+- Test: `bun run --filter '@canmi/seam-react' test`
+
+## Notes
+
+- Peer dependencies: `react` ^18 || ^19, `react-dom` ^18 || ^19
+- Depends on `@canmi/seam-client` for underlying RPC and subscription logic
+- `parseSeamData()` reads from a `<script>` tag injected by the server during HTML rendering

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import * as react from "react";
+import { ComponentType, ReactNode } from "react";
+import { SeamClientError } from "@canmi/seam-client";
+
+//#region src/types.d.ts
+interface ParamMapping {
+  from: "route";
+  type?: "string" | "int";
+}
+interface LoaderDef {
+  procedure: string;
+  params?: Record<string, ParamMapping>;
+}
+interface RouteDef {
+  path: string;
+  component?: ComponentType<Record<string, unknown>>;
+  layout?: ComponentType<{
+    children: ReactNode;
+  }>;
+  children?: RouteDef[];
+  loaders?: Record<string, LoaderDef>;
+  mock?: Record<string, unknown>;
+  nullable?: string[];
+}
+//#endregion
+//#region src/define-routes.d.ts
+declare function defineRoutes(routes: RouteDef[]): RouteDef[];
+//#endregion
+//#region src/use-seam-data.d.ts
+declare const SeamDataProvider: react.Provider<unknown>;
+declare function useSeamData<T extends object = Record<string, unknown>>(): T;
+declare function parseSeamData(): Record<string, unknown>;
+//#endregion
+//#region src/sentinel.d.ts
+/**
+ * Replace every leaf value in `obj` with a sentinel string `%%SEAM:dotted.path%%`.
+ * Nested objects are recursed; primitives and null become leaf sentinels.
+ *
+ * Arrays of objects (length > 0, first element is object) produce a 1-element
+ * sentinel array where each leaf in the object template uses `$.` path prefix.
+ * Arrays of primitives, empty arrays, and null remain leaf sentinels.
+ */
+declare function buildSentinelData(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+//#endregion
+//#region src/use-seam-subscription.d.ts
+type SubscriptionStatus = "connecting" | "active" | "error" | "closed";
+interface UseSeamSubscriptionResult<T> {
+  data: T | null;
+  error: SeamClientError | null;
+  status: SubscriptionStatus;
+}
+declare function useSeamSubscription<T>(baseUrl: string, procedure: string, input: unknown): UseSeamSubscriptionResult<T>;
+//#endregion
+//#region src/use-seam-navigate.d.ts
+declare const SeamNavigateProvider: react.Provider<(url: string) => void>;
+declare function useSeamNavigate(): (url: string) => void;
+//#endregion
+export { type LoaderDef, type ParamMapping, type RouteDef, SeamDataProvider, SeamNavigateProvider, type SubscriptionStatus, type UseSeamSubscriptionResult, buildSentinelData, defineRoutes, parseSeamData, useSeamData, useSeamNavigate, useSeamSubscription };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/define-routes.ts","../src/use-seam-data.ts","../src/sentinel.ts","../src/use-seam-subscription.ts","../src/use-seam-navigate.ts"],"mappings":";;;;;UAIiB,YAAA;EACf,IAAA;EACA,IAAA;AAAA;AAAA,UAGe,SAAA;EACf,SAAA;EACA,MAAA,GAAS,MAAA,SAAe,YAAA;AAAA;AAAA,UAGT,QAAA;EACf,IAAA;EACA,SAAA,GAAY,aAAA,CAAc,MAAA;EAC1B,MAAA,GAAS,aAAA;IAAgB,QAAA,EAAU,SAAA;EAAA;EACnC,QAAA,GAAW,QAAA;EACX,OAAA,GAAU,MAAA,SAAe,SAAA;EACzB,IAAA,GAAO,MAAA;EACP,QAAA;AAAA;;;iBCjBc,YAAA,CAAa,MAAA,EAAQ,QAAA,KAAa,QAAA;;;cCErC,gBAAA,EAA2C,KAAA,CAA3B,QAAA;AAAA,iBAEb,WAAA,oBAA+B,MAAA,kBAAA,CAAA,GAA4B,CAAA;AAAA,iBAO3D,aAAA,CAAA,GAAiB,MAAA;;;;;;;;AFXjC;;;iBGMgB,iBAAA,CACd,GAAA,EAAK,MAAA,mBACL,MAAA,YACC,MAAA;;;KCRS,kBAAA;AAAA,UAEK,yBAAA;EACf,IAAA,EAAM,CAAA;EACN,KAAA,EAAO,eAAA;EACP,MAAA,EAAQ,kBAAA;AAAA;AAAA,iBAGM,mBAAA,GAAA,CACd,OAAA,UACA,SAAA,UACA,KAAA,YACC,yBAAA,CAA0B,CAAA;;;cCThB,oBAAA,EAAmD,KAAA,CAA/B,QAAA,EAAA,GAAA;AAAA,iBAEjB,eAAA,CAAA,IAAoB,GAAA"}

package/dist/index.js

@@ -0,0 +1,112 @@
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { SeamClientError } from "@canmi/seam-client";
+
+//#region src/define-routes.ts
+function defineRoutes(routes) {
+	return routes;
+}
+
+//#endregion
+//#region src/use-seam-data.ts
+const SeamDataContext = createContext(null);
+const SeamDataProvider = SeamDataContext.Provider;
+function useSeamData() {
+	const value = useContext(SeamDataContext);
+	if (value === null || value === void 0) throw new Error("useSeamData must be used inside <SeamDataProvider>");
+	return value;
+}
+function parseSeamData() {
+	const el = document.getElementById("__SEAM_DATA__");
+	if (!el?.textContent) throw new Error("__SEAM_DATA__ not found");
+	return JSON.parse(el.textContent);
+}
+
+//#endregion
+//#region src/sentinel.ts
+/**
+* Replace every leaf value in `obj` with a sentinel string `%%SEAM:dotted.path%%`.
+* Nested objects are recursed; primitives and null become leaf sentinels.
+*
+* Arrays of objects (length > 0, first element is object) produce a 1-element
+* sentinel array where each leaf in the object template uses `$.` path prefix.
+* Arrays of primitives, empty arrays, and null remain leaf sentinels.
+*/
+function buildSentinelData(obj, prefix = "") {
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) result[key] = buildSentinelData(value, path);
+		else if (Array.isArray(value) && value.length > 0 && typeof value[0] === "object" && value[0] !== null) result[key] = [buildSentinelData(value[0], `${path}.$`)];
+		else result[key] = `%%SEAM:${path}%%`;
+	}
+	return result;
+}
+
+//#endregion
+//#region src/use-seam-subscription.ts
+function useSeamSubscription(baseUrl, procedure, input) {
+	const [data, setData] = useState(null);
+	const [error, setError] = useState(null);
+	const [status, setStatus] = useState("connecting");
+	const inputKey = JSON.stringify(input);
+	const inputRef = useRef(inputKey);
+	inputRef.current = inputKey;
+	useEffect(() => {
+		setData(null);
+		setError(null);
+		setStatus("connecting");
+		const url = `${baseUrl.replace(/\/+$/, "")}/_seam/subscribe/${procedure}?${new URLSearchParams({ input: inputKey }).toString()}`;
+		const es = new EventSource(url);
+		es.addEventListener("data", (e) => {
+			try {
+				setData(JSON.parse(e.data));
+				setStatus("active");
+			} catch {
+				setError(new SeamClientError("INTERNAL_ERROR", "Failed to parse SSE data", 0));
+				setStatus("error");
+				es.close();
+			}
+		});
+		es.addEventListener("error", (e) => {
+			if (e instanceof MessageEvent) try {
+				const payload = JSON.parse(e.data);
+				setError(new SeamClientError("INTERNAL_ERROR", typeof payload.message === "string" ? payload.message : "SSE error", 0));
+			} catch {
+				setError(new SeamClientError("INTERNAL_ERROR", "SSE error", 0));
+			}
+			else setError(new SeamClientError("INTERNAL_ERROR", "SSE connection error", 0));
+			setStatus("error");
+			es.close();
+		});
+		es.addEventListener("complete", () => {
+			setStatus("closed");
+			es.close();
+		});
+		return () => {
+			es.close();
+		};
+	}, [
+		baseUrl,
+		procedure,
+		inputKey
+	]);
+	return {
+		data,
+		error,
+		status
+	};
+}
+
+//#endregion
+//#region src/use-seam-navigate.ts
+const SeamNavigateContext = createContext((url) => {
+	globalThis.location.href = url;
+});
+const SeamNavigateProvider = SeamNavigateContext.Provider;
+function useSeamNavigate() {
+	return useContext(SeamNavigateContext);
+}
+
+//#endregion
+export { SeamDataProvider, SeamNavigateProvider, buildSentinelData, defineRoutes, parseSeamData, useSeamData, useSeamNavigate, useSeamSubscription };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/define-routes.ts","../src/use-seam-data.ts","../src/sentinel.ts","../src/use-seam-subscription.ts","../src/use-seam-navigate.ts"],"sourcesContent":["/* packages/client/react/src/define-routes.ts */\n\nimport type { RouteDef } from \"./types.js\";\n\nexport function defineRoutes(routes: RouteDef[]): RouteDef[] {\n  return routes;\n}\n","/* packages/client/react/src/use-seam-data.ts */\n\nimport { createContext, useContext } from \"react\";\n\nconst SeamDataContext = createContext<unknown>(null);\n\nexport const SeamDataProvider = SeamDataContext.Provider;\n\nexport function useSeamData<T extends object = Record<string, unknown>>(): T {\n  const value = useContext(SeamDataContext);\n  if (value === null || value === undefined)\n    throw new Error(\"useSeamData must be used inside <SeamDataProvider>\");\n  return value as T;\n}\n\nexport function parseSeamData(): Record<string, unknown> {\n  const el = document.getElementById(\"__SEAM_DATA__\");\n  if (!el?.textContent) throw new Error(\"__SEAM_DATA__ not found\");\n  return JSON.parse(el.textContent) as Record<string, unknown>;\n}\n","/* packages/client/react/src/sentinel.ts */\n\n/**\n * Replace every leaf value in `obj` with a sentinel string `%%SEAM:dotted.path%%`.\n * Nested objects are recursed; primitives and null become leaf sentinels.\n *\n * Arrays of objects (length > 0, first element is object) produce a 1-element\n * sentinel array where each leaf in the object template uses `$.` path prefix.\n * Arrays of primitives, empty arrays, and null remain leaf sentinels.\n */\nexport function buildSentinelData(\n  obj: Record<string, unknown>,\n  prefix = \"\",\n): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(obj)) {\n    const path = prefix ? `${prefix}.${key}` : key;\n    if (value !== null && typeof value === \"object\" && !Array.isArray(value)) {\n      result[key] = buildSentinelData(value as Record<string, unknown>, path);\n    } else if (\n      Array.isArray(value) &&\n      value.length > 0 &&\n      typeof value[0] === \"object\" &&\n      value[0] !== null\n    ) {\n      // Array of objects: produce 1-element sentinel array with $.field paths\n      result[key] = [buildSentinelData(value[0] as Record<string, unknown>, `${path}.$`)];\n    } else {\n      result[key] = `%%SEAM:${path}%%`;\n    }\n  }\n  return result;\n}\n","/* packages/client/react/src/use-seam-subscription.ts */\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { SeamClientError } from \"@canmi/seam-client\";\n\nexport type SubscriptionStatus = \"connecting\" | \"active\" | \"error\" | \"closed\";\n\nexport interface UseSeamSubscriptionResult<T> {\n  data: T | null;\n  error: SeamClientError | null;\n  status: SubscriptionStatus;\n}\n\nexport function useSeamSubscription<T>(\n  baseUrl: string,\n  procedure: string,\n  input: unknown,\n): UseSeamSubscriptionResult<T> {\n  const [data, setData] = useState<T | null>(null);\n  const [error, setError] = useState<SeamClientError | null>(null);\n  const [status, setStatus] = useState<SubscriptionStatus>(\"connecting\");\n\n  // Serialize input for stable dependency\n  const inputKey = JSON.stringify(input);\n  const inputRef = useRef(inputKey);\n  inputRef.current = inputKey;\n\n  useEffect(() => {\n    setData(null);\n    setError(null);\n    setStatus(\"connecting\");\n\n    const cleanBase = baseUrl.replace(/\\/+$/, \"\");\n    const params = new URLSearchParams({ input: inputKey });\n    const url = `${cleanBase}/_seam/subscribe/${procedure}?${params.toString()}`;\n    const es = new EventSource(url);\n\n    es.addEventListener(\"data\", (e) => {\n      try {\n        setData(JSON.parse(e.data as string) as T);\n        setStatus(\"active\");\n      } catch {\n        setError(new SeamClientError(\"INTERNAL_ERROR\", \"Failed to parse SSE data\", 0));\n        setStatus(\"error\");\n        es.close();\n      }\n    });\n\n    es.addEventListener(\"error\", (e) => {\n      if (e instanceof MessageEvent) {\n        try {\n          const payload = JSON.parse(e.data as string) as { code?: string; message?: string };\n          setError(\n            new SeamClientError(\n              \"INTERNAL_ERROR\",\n              typeof payload.message === \"string\" ? payload.message : \"SSE error\",\n              0,\n            ),\n          );\n        } catch {\n          setError(new SeamClientError(\"INTERNAL_ERROR\", \"SSE error\", 0));\n        }\n      } else {\n        setError(new SeamClientError(\"INTERNAL_ERROR\", \"SSE connection error\", 0));\n      }\n      setStatus(\"error\");\n      es.close();\n    });\n\n    es.addEventListener(\"complete\", () => {\n      setStatus(\"closed\");\n      es.close();\n    });\n\n    return () => {\n      es.close();\n    };\n  }, [baseUrl, procedure, inputKey]);\n\n  return { data, error, status };\n}\n","/* packages/client/react/src/use-seam-navigate.ts */\n\nimport { createContext, useContext } from \"react\";\n\nconst SeamNavigateContext = createContext<(url: string) => void>((url) => {\n  globalThis.location.href = url;\n});\n\nexport const SeamNavigateProvider = SeamNavigateContext.Provider;\n\nexport function useSeamNavigate(): (url: string) => void {\n  return useContext(SeamNavigateContext);\n}\n"],"mappings":";;;;AAIA,SAAgB,aAAa,QAAgC;AAC3D,QAAO;;;;;ACDT,MAAM,kBAAkB,cAAuB,KAAK;AAEpD,MAAa,mBAAmB,gBAAgB;AAEhD,SAAgB,cAA6D;CAC3E,MAAM,QAAQ,WAAW,gBAAgB;AACzC,KAAI,UAAU,QAAQ,UAAU,OAC9B,OAAM,IAAI,MAAM,qDAAqD;AACvE,QAAO;;AAGT,SAAgB,gBAAyC;CACvD,MAAM,KAAK,SAAS,eAAe,gBAAgB;AACnD,KAAI,CAAC,IAAI,YAAa,OAAM,IAAI,MAAM,0BAA0B;AAChE,QAAO,KAAK,MAAM,GAAG,YAAY;;;;;;;;;;;;;ACRnC,SAAgB,kBACd,KACA,SAAS,IACgB;CACzB,MAAM,SAAkC,EAAE;AAC1C,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,EAAE;EAC9C,MAAM,OAAO,SAAS,GAAG,OAAO,GAAG,QAAQ;AAC3C,MAAI,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,MAAM,CACtE,QAAO,OAAO,kBAAkB,OAAkC,KAAK;WAEvE,MAAM,QAAQ,MAAM,IACpB,MAAM,SAAS,KACf,OAAO,MAAM,OAAO,YACpB,MAAM,OAAO,KAGb,QAAO,OAAO,CAAC,kBAAkB,MAAM,IAA+B,GAAG,KAAK,IAAI,CAAC;MAEnF,QAAO,OAAO,UAAU,KAAK;;AAGjC,QAAO;;;;;AClBT,SAAgB,oBACd,SACA,WACA,OAC8B;CAC9B,MAAM,CAAC,MAAM,WAAW,SAAmB,KAAK;CAChD,MAAM,CAAC,OAAO,YAAY,SAAiC,KAAK;CAChE,MAAM,CAAC,QAAQ,aAAa,SAA6B,aAAa;CAGtE,MAAM,WAAW,KAAK,UAAU,MAAM;CACtC,MAAM,WAAW,OAAO,SAAS;AACjC,UAAS,UAAU;AAEnB,iBAAgB;AACd,UAAQ,KAAK;AACb,WAAS,KAAK;AACd,YAAU,aAAa;EAIvB,MAAM,MAAM,GAFM,QAAQ,QAAQ,QAAQ,GAAG,CAEpB,mBAAmB,UAAU,GADvC,IAAI,gBAAgB,EAAE,OAAO,UAAU,CAAC,CACS,UAAU;EAC1E,MAAM,KAAK,IAAI,YAAY,IAAI;AAE/B,KAAG,iBAAiB,SAAS,MAAM;AACjC,OAAI;AACF,YAAQ,KAAK,MAAM,EAAE,KAAe,CAAM;AAC1C,cAAU,SAAS;WACb;AACN,aAAS,IAAI,gBAAgB,kBAAkB,4BAA4B,EAAE,CAAC;AAC9E,cAAU,QAAQ;AAClB,OAAG,OAAO;;IAEZ;AAEF,KAAG,iBAAiB,UAAU,MAAM;AAClC,OAAI,aAAa,aACf,KAAI;IACF,MAAM,UAAU,KAAK,MAAM,EAAE,KAAe;AAC5C,aACE,IAAI,gBACF,kBACA,OAAO,QAAQ,YAAY,WAAW,QAAQ,UAAU,aACxD,EACD,CACF;WACK;AACN,aAAS,IAAI,gBAAgB,kBAAkB,aAAa,EAAE,CAAC;;OAGjE,UAAS,IAAI,gBAAgB,kBAAkB,wBAAwB,EAAE,CAAC;AAE5E,aAAU,QAAQ;AAClB,MAAG,OAAO;IACV;AAEF,KAAG,iBAAiB,kBAAkB;AACpC,aAAU,SAAS;AACnB,MAAG,OAAO;IACV;AAEF,eAAa;AACX,MAAG,OAAO;;IAEX;EAAC;EAAS;EAAW;EAAS,CAAC;AAElC,QAAO;EAAE;EAAM;EAAO;EAAQ;;;;;AC3EhC,MAAM,sBAAsB,eAAsC,QAAQ;AACxE,YAAW,SAAS,OAAO;EAC3B;AAEF,MAAa,uBAAuB,oBAAoB;AAExD,SAAgB,kBAAyC;AACvD,QAAO,WAAW,oBAAoB"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@canmi/seam-react",
+  "version": "0.2.3",
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@canmi/seam-client": "workspace:*",
+    "esbuild": "^0.25.0"
+  },
+  "devDependencies": {
+    "@canmi/seam-injector": "workspace:*",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^28.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsdown": "^0.20.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  }
+}

package/scripts/build-skeletons.mjs

@@ -0,0 +1,370 @@
+/* packages/client/react/scripts/build-skeletons.mjs */
+
+import { build } from "esbuild";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { readFileSync, unlinkSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SeamDataProvider, buildSentinelData } from "@canmi/seam-react";
+import {
+  collectStructuralAxes,
+  cartesianProduct,
+  buildVariantSentinel,
+} from "./variant-generator.mjs";
+import { generateMockFromSchema, flattenLoaderMock, deepMerge } from "./mock-generator.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// -- Rendering --
+
+function renderWithData(component, data) {
+  return renderToString(createElement(SeamDataProvider, { value: data }, createElement(component)));
+}
+
+// -- Render guards --
+
+class SeamBuildError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SeamBuildError";
+  }
+}
+
+const buildWarnings = [];
+
+// Matches React-injected resource hint <link> tags.
+// Only rel values used by React's resource APIs are targeted (preload, dns-prefetch, preconnect,
+// data-precedence); user-authored <link> tags (canonical, alternate, stylesheet) are unaffected.
+const RESOURCE_HINT_RE =
+  /<link[^>]+rel\s*=\s*"(?:preload|dns-prefetch|preconnect)"[^>]*>|<link[^>]+data-precedence[^>]*>/gi;
+
+function installRenderTraps(violations, teardowns) {
+  function trapCall(obj, prop, label) {
+    const orig = obj[prop];
+    obj[prop] = function () {
+      violations.push({ severity: "error", reason: `${label} called during skeleton render` });
+      throw new SeamBuildError(`${label} is not allowed in skeleton components`);
+    };
+    teardowns.push(() => {
+      obj[prop] = orig;
+    });
+  }
+
+  trapCall(globalThis, "fetch", "fetch()");
+  trapCall(Math, "random", "Math.random()");
+  trapCall(Date, "now", "Date.now()");
+  if (globalThis.crypto?.randomUUID) {
+    trapCall(globalThis.crypto, "randomUUID", "crypto.randomUUID()");
+  }
+
+  // Timer APIs — these don't affect renderToString output, but pending handles
+  // prevent the build process from exiting (Node keeps the event loop alive).
+  trapCall(globalThis, "setTimeout", "setTimeout()");
+  trapCall(globalThis, "setInterval", "setInterval()");
+  if (globalThis.setImmediate) {
+    trapCall(globalThis, "setImmediate", "setImmediate()");
+  }
+  trapCall(globalThis, "queueMicrotask", "queueMicrotask()");
+
+  // Trap browser globals (only if not already defined — these are undefined in Node;
+  // typeof checks bypass getters, so `typeof window !== 'undefined'` remains safe)
+  for (const name of ["window", "document", "localStorage"]) {
+    if (!(name in globalThis)) {
+      Object.defineProperty(globalThis, name, {
+        get() {
+          violations.push({ severity: "error", reason: `${name} accessed during skeleton render` });
+          throw new SeamBuildError(`${name} is not available in skeleton components`);
+        },
+        configurable: true,
+      });
+      teardowns.push(() => {
+        delete globalThis[name];
+      });
+    }
+  }
+}
+
+function validateOutput(html, violations) {
+  if (html.includes("<!--$!-->")) {
+    violations.push({
+      severity: "error",
+      reason:
+        "Suspense abort detected \u2014 a component used an unresolved async resource\n" +
+        "  (e.g. use(promise)) inside a <Suspense> boundary, producing an incomplete\n" +
+        "  template with fallback content baked in.\n" +
+        "  Fix: remove use() from skeleton components. Async data belongs in loaders.",
+    });
+  }
+
+  const hints = Array.from(html.matchAll(RESOURCE_HINT_RE));
+  if (hints.length > 0) {
+    violations.push({
+      severity: "warning",
+      reason:
+        `stripped ${hints.length} resource hint <link> tag(s) injected by React's preload()/preinit().\n` +
+        "  These are not data-driven and would cause hydration mismatch.",
+    });
+  }
+}
+
+function stripResourceHints(html) {
+  return html.replace(RESOURCE_HINT_RE, "");
+}
+
+function guardedRender(routePath, component, data) {
+  const violations = [];
+  const teardowns = [];
+
+  installRenderTraps(violations, teardowns);
+
+  let html;
+  try {
+    html = renderWithData(component, data);
+  } finally {
+    for (const teardown of teardowns) teardown();
+  }
+
+  validateOutput(html, violations);
+
+  const fatal = violations.filter((v) => v.severity === "error");
+  if (fatal.length > 0) {
+    const msg = fatal.map((v) => `[seam] error: ${routePath}\n  ${v.reason}`).join("\n\n");
+    throw new SeamBuildError(msg);
+  }
+
+  // After fatal check, only warnings remain
+  for (const v of violations) {
+    buildWarnings.push(`[seam] warning: ${routePath}\n  ${v.reason}`);
+  }
+  if (violations.length > 0) {
+    html = stripResourceHints(html);
+  }
+
+  return html;
+}
+
+/**
+ * Merge loader procedure schemas from manifest into a combined page schema.
+ * Each loader contributes its output schema fields to the top-level properties.
+ */
+function buildPageSchema(route, manifest) {
+  if (!manifest) return null;
+
+  const properties = {};
+
+  for (const [loaderKey, loaderDef] of Object.entries(route.loaders || {})) {
+    const procName = loaderDef.procedure;
+    const proc = manifest.procedures?.[procName];
+    if (!proc?.output) continue;
+
+    // Always nest under the loader key so axis paths (e.g. "user.bio")
+    // align with sentinel data paths built from mock (e.g. sentinel.user.bio).
+    properties[loaderKey] = proc.output;
+  }
+
+  const result = {};
+  if (Object.keys(properties).length > 0) result.properties = properties;
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Resolve mock data for a route: auto-generate from schema when available,
+ * then deep-merge any user-provided partial mock on top.
+ */
+function resolveRouteMock(route, manifest) {
+  const pageSchema = buildPageSchema(route, manifest);
+
+  if (pageSchema) {
+    const keyedMock = generateMockFromSchema(pageSchema);
+    const autoMock = flattenLoaderMock(keyedMock);
+    return route.mock ? deepMerge(autoMock, route.mock) : autoMock;
+  }
+
+  // No manifest (frontend-only mode) — mock is required
+  if (route.mock) return route.mock;
+
+  throw new SeamBuildError(
+    `[seam] error: Mock data required for route "${route.path}"\n\n` +
+      "  No procedure manifest found \u2014 cannot auto-generate mock data.\n" +
+      "  Provide mock data in your route definition:\n\n" +
+      "    defineRoutes([{\n" +
+      `      path: "${route.path}",\n` +
+      "      component: YourComponent,\n" +
+      '      mock: { user: { name: "..." }, repos: [...] }\n' +
+      "    }])\n\n" +
+      "  Or switch to fullstack mode with typed Procedures\n" +
+      "  to enable automatic mock generation from schema.",
+  );
+}
+
+function renderRoute(route, manifest) {
+  const mock = resolveRouteMock(route, manifest);
+  const baseSentinel = buildSentinelData(mock);
+  const pageSchema = buildPageSchema(route, manifest);
+  const axes = pageSchema ? collectStructuralAxes(pageSchema, mock) : [];
+  const combos = cartesianProduct(axes);
+
+  const variants = combos.map((variant) => {
+    const sentinel = buildVariantSentinel(baseSentinel, mock, variant);
+    const html = guardedRender(route.path, route.component, sentinel);
+    return { variant, html };
+  });
+
+  // Render with real mock data for CTR equivalence check
+  const mockHtml = stripResourceHints(guardedRender(route.path, route.component, mock));
+
+  return {
+    path: route.path,
+    loaders: route.loaders,
+    layout: route._layoutId || undefined,
+    axes,
+    variants,
+    mockHtml,
+    mock,
+    pageSchema,
+  };
+}
+
+// -- Layout helpers --
+
+function toLayoutId(path) {
+  return path === "/"
+    ? "_layout_root"
+    : `_layout_${path.replace(/^\/|\/$/g, "").replace(/\//g, "-")}`;
+}
+
+/** Extract layout components and metadata from route tree */
+function extractLayouts(routes) {
+  const seen = new Map();
+  (function walk(defs, parentId) {
+    for (const def of defs) {
+      if (def.layout && def.children) {
+        const id = toLayoutId(def.path);
+        if (!seen.has(id)) {
+          seen.set(id, {
+            component: def.layout,
+            loaders: def.loaders || {},
+            mock: def.mock || null,
+            parentId: parentId || null,
+          });
+        }
+        walk(def.children, id);
+      }
+    }
+  })(routes, null);
+  return seen;
+}
+
+/**
+ * Resolve mock data for a layout: auto-generate from schema when loaders exist,
+ * then deep-merge any user-provided partial mock on top.
+ * Unlike resolveRouteMock, a layout with no loaders and no mock is valid (empty shell).
+ */
+function resolveLayoutMock(entry, manifest) {
+  if (Object.keys(entry.loaders).length > 0) {
+    const schema = buildPageSchema(entry, manifest);
+    if (schema) {
+      const keyedMock = generateMockFromSchema(schema);
+      const autoMock = flattenLoaderMock(keyedMock);
+      return entry.mock ? deepMerge(autoMock, entry.mock) : autoMock;
+    }
+  }
+  return entry.mock || {};
+}
+
+/** Render layout with seam-outlet placeholder, optionally with sentinel data */
+function renderLayout(LayoutComponent, id, entry, manifest) {
+  const mock = resolveLayoutMock(entry, manifest);
+  const data = Object.keys(mock).length > 0 ? buildSentinelData(mock) : {};
+  function LayoutWithOutlet() {
+    return createElement(LayoutComponent, null, createElement("seam-outlet", null));
+  }
+  return guardedRender(`layout:${id}`, LayoutWithOutlet, data);
+}
+
+/** Flatten routes, annotating each leaf with its parent layout id */
+function flattenRoutes(routes, currentLayout) {
+  const leaves = [];
+  for (const route of routes) {
+    if (route.layout && route.children) {
+      leaves.push(...flattenRoutes(route.children, toLayoutId(route.path)));
+    } else if (route.children) {
+      leaves.push(...flattenRoutes(route.children, currentLayout));
+    } else {
+      if (currentLayout) route._layoutId = currentLayout;
+      leaves.push(route);
+    }
+  }
+  return leaves;
+}
+
+// -- Main --
+
+async function main() {
+  const routesFile = process.argv[2];
+  const manifestFile = process.argv[3];
+
+  if (!routesFile) {
+    console.error("Usage: node build-skeletons.mjs <routes-file> [manifest-file]");
+    process.exit(1);
+  }
+
+  // Load manifest if provided
+  let manifest = null;
+  if (manifestFile && manifestFile !== "none") {
+    try {
+      manifest = JSON.parse(readFileSync(resolve(manifestFile), "utf-8"));
+    } catch (e) {
+      console.error(`warning: could not read manifest: ${e.message}`);
+    }
+  }
+
+  const absRoutes = resolve(routesFile);
+  const outfile = join(__dirname, ".tmp-routes-bundle.mjs");
+
+  await build({
+    entryPoints: [absRoutes],
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    outfile,
+    external: ["react", "react-dom", "@canmi/seam-react"],
+  });
+
+  try {
+    const mod = await import(outfile);
+    const routes = mod.default || mod.routes;
+    if (!Array.isArray(routes)) {
+      throw new Error("Routes file must export default or named 'routes' as an array");
+    }
+
+    const layoutMap = extractLayouts(routes);
+    const layouts = [...layoutMap.entries()].map(([id, entry]) => ({
+      id,
+      html: renderLayout(entry.component, id, entry, manifest),
+      loaders: entry.loaders,
+      parent: entry.parentId,
+    }));
+    const flat = flattenRoutes(routes);
+    const output = {
+      layouts,
+      routes: flat.map((r) => renderRoute(r, manifest)),
+      warnings: buildWarnings,
+    };
+    process.stdout.write(JSON.stringify(output));
+  } finally {
+    try {
+      unlinkSync(outfile);
+    } catch {}
+  }
+}
+
+main().catch((err) => {
+  if (err instanceof SeamBuildError) {
+    console.error(err.message);
+  } else {
+    console.error(err);
+  }
+  process.exit(1);
+});

package/scripts/mock-generator.mjs

@@ -0,0 +1,165 @@
+/* packages/client/react/scripts/mock-generator.mjs */
+
+/**
+ * Auto-generate deterministic mock data from JTD schema.
+ * Lets users omit mock in route definitions when a manifest is available.
+ */
+
+const STRING_RULES = [
+  { test: (f) => /name/i.test(f), value: "Example Name" },
+  { test: (f) => /url|href|src/i.test(f), value: "https://example.com" },
+  { test: (f) => /email/i.test(f), value: "user@example.com" },
+  { test: (f) => /color/i.test(f), value: "#888888" },
+  { test: (f) => /description|bio|summary/i.test(f), value: "Sample description" },
+  { test: (f) => /title/i.test(f), value: "Sample Title" },
+  { test: (f) => /^id$/i.test(f), value: "sample-id" },
+];
+
+function inferStringValue(fieldPath) {
+  const lastSegment = fieldPath ? fieldPath.split(".").pop() : "";
+  for (const rule of STRING_RULES) {
+    if (rule.test(lastSegment)) return rule.value;
+  }
+  // Capitalize first letter for readability
+  const label = lastSegment ? lastSegment.charAt(0).toUpperCase() + lastSegment.slice(1) : "text";
+  return `Sample ${label}`;
+}
+
+/**
+ * Recursively traverse a JTD schema and produce deterministic mock values.
+ * @param {object} schema - JTD schema node
+ * @param {string} [fieldPath=""] - dot-separated path for semantic string inference
+ * @returns {unknown}
+ */
+export function generateMockFromSchema(schema, fieldPath = "") {
+  if (!schema || typeof schema !== "object") return {};
+
+  // Strip nullable wrapper — generate a populated (non-null) value
+  if (schema.nullable) {
+    const inner = { ...schema };
+    delete inner.nullable;
+    return generateMockFromSchema(inner, fieldPath);
+  }
+
+  // Primitive type forms
+  if (schema.type) {
+    switch (schema.type) {
+      case "string":
+        return inferStringValue(fieldPath);
+      case "boolean":
+        return true;
+      case "int8":
+      case "int16":
+      case "int32":
+      case "uint8":
+      case "uint16":
+      case "uint32":
+      case "float32":
+      case "float64":
+        return 1;
+      case "timestamp":
+        return "2024-01-01T00:00:00Z";
+      default:
+        return `Sample ${schema.type}`;
+    }
+  }
+
+  // Enum form
+  if (schema.enum) {
+    return schema.enum[0];
+  }
+
+  // Object form (properties / optionalProperties)
+  if (schema.properties || schema.optionalProperties) {
+    const result = {};
+    const props = schema.properties || {};
+    const optProps = schema.optionalProperties || {};
+    for (const [key, sub] of Object.entries(props)) {
+      result[key] = generateMockFromSchema(sub, fieldPath ? `${fieldPath}.${key}` : key);
+    }
+    for (const [key, sub] of Object.entries(optProps)) {
+      result[key] = generateMockFromSchema(sub, fieldPath ? `${fieldPath}.${key}` : key);
+    }
+    return result;
+  }
+
+  // Array form (elements)
+  if (schema.elements) {
+    return [
+      generateMockFromSchema(schema.elements, fieldPath ? `${fieldPath}.$` : "$"),
+      generateMockFromSchema(schema.elements, fieldPath ? `${fieldPath}.$` : "$"),
+    ];
+  }
+
+  // Record/map form (values)
+  if (schema.values) {
+    return {
+      item1: generateMockFromSchema(schema.values, fieldPath ? `${fieldPath}.item1` : "item1"),
+      item2: generateMockFromSchema(schema.values, fieldPath ? `${fieldPath}.item2` : "item2"),
+    };
+  }
+
+  // Discriminator form (tagged union)
+  if (schema.discriminator && schema.mapping) {
+    const tag = schema.discriminator;
+    const mappingKeys = Object.keys(schema.mapping);
+    if (mappingKeys.length === 0) return { [tag]: "" };
+    const firstKey = mappingKeys[0];
+    const variant = generateMockFromSchema(schema.mapping[firstKey], fieldPath);
+    return { [tag]: firstKey, ...variant };
+  }
+
+  // Empty / any schema
+  return {};
+}
+
+/**
+ * Replicate page handler's merge logic: keyed loader data flattened
+ * so that top-level keys from each loader's object result are also
+ * accessible at the root level.
+ * @param {Record<string, unknown>} keyedMock
+ * @returns {Record<string, unknown>}
+ */
+export function flattenLoaderMock(keyedMock) {
+  const flat = { ...keyedMock };
+  for (const value of Object.values(keyedMock)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      Object.assign(flat, value);
+    }
+  }
+  return flat;
+}
+
+/**
+ * Deep merge base with override:
+ * - object + object → recursive merge
+ * - array in override → replaces entirely
+ * - primitive/null in override → replaces
+ * - keys only in base → preserved
+ * @param {unknown} base
+ * @param {unknown} override
+ * @returns {unknown}
+ */
+export function deepMerge(base, override) {
+  if (override === null || override === undefined) return override;
+  if (typeof override !== "object" || Array.isArray(override)) return override;
+  if (typeof base !== "object" || base === null || Array.isArray(base)) return override;
+
+  const result = { ...base };
+  for (const [key, val] of Object.entries(override)) {
+    if (
+      key in result &&
+      typeof result[key] === "object" &&
+      result[key] !== null &&
+      !Array.isArray(result[key]) &&
+      typeof val === "object" &&
+      val !== null &&
+      !Array.isArray(val)
+    ) {
+      result[key] = deepMerge(result[key], val);
+    } else {
+      result[key] = val;
+    }
+  }
+  return result;
+}

package/scripts/variant-generator.mjs

@@ -0,0 +1,142 @@
+/* packages/client/react/scripts/variant-generator.mjs */
+
+/**
+ * Walk a JTD schema + mock data to discover all structural axes.
+ * Each axis represents a dimension that affects template structure:
+ * boolean fields, enum fields, nullable fields, array (elements) fields.
+ */
+export function collectStructuralAxes(schema, mock, prefix = "") {
+  const axes = [];
+  if (!schema || typeof schema !== "object") return axes;
+
+  const props = schema.properties || {};
+  const optProps = schema.optionalProperties || {};
+  const allProps = { ...props, ...optProps };
+
+  for (const [key, fieldSchema] of Object.entries(allProps)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+
+    if (fieldSchema.type === "boolean") {
+      axes.push({ path, kind: "boolean", values: [true, false] });
+    } else if (fieldSchema.enum) {
+      axes.push({ path, kind: "enum", values: [...fieldSchema.enum] });
+    } else if (fieldSchema.nullable) {
+      axes.push({ path, kind: "nullable", values: ["present", "null"] });
+      // Recurse into the underlying schema (remove nullable flag)
+      const innerSchema = { ...fieldSchema };
+      delete innerSchema.nullable;
+      if (innerSchema.properties || innerSchema.optionalProperties) {
+        const mockValue = mock?.[key];
+        axes.push(...collectStructuralAxes(innerSchema, mockValue, path));
+      }
+    } else if (fieldSchema.elements) {
+      axes.push({ path, kind: "array", values: ["populated", "empty"] });
+      // Recurse into element schema with $.prefix
+      const elemSchema = fieldSchema.elements;
+      const mockArray = mock?.[key];
+      const elemMock = Array.isArray(mockArray) && mockArray.length > 0 ? mockArray[0] : {};
+      if (elemSchema.properties || elemSchema.optionalProperties) {
+        axes.push(...collectStructuralAxes(elemSchema, elemMock, `${path}.$`));
+      }
+    } else if (fieldSchema.properties || fieldSchema.optionalProperties) {
+      // Nested object: recurse
+      const mockValue = mock?.[key];
+      axes.push(...collectStructuralAxes(fieldSchema, mockValue, path));
+    }
+    // string/number/etc: non-structural, skip
+  }
+
+  return axes;
+}
+
+/**
+ * Compute cartesian product of all axis values.
+ * Returns array of variant objects, e.g. [{ isAdmin: true, role: "admin" }, ...]
+ */
+export function cartesianProduct(axes) {
+  if (axes.length === 0) return [{}];
+
+  let combos = [{}];
+  for (const axis of axes) {
+    const next = [];
+    for (const existing of combos) {
+      for (const value of axis.values) {
+        next.push({ ...existing, [axis.path]: value });
+      }
+    }
+    combos = next;
+  }
+
+  if (combos.length > 10000) {
+    console.error(`warning: ${combos.length} variants detected — build may be slow`);
+  }
+
+  return combos;
+}
+
+/**
+ * Build sentinel data with structural fields set according to a variant combo.
+ * Uses the base sentinel as starting point and adjusts structural fields.
+ */
+export function buildVariantSentinel(baseSentinel, mock, variant) {
+  const result = JSON.parse(JSON.stringify(baseSentinel));
+
+  for (const [path, value] of Object.entries(variant)) {
+    applyVariantValue(result, mock, path, value);
+  }
+
+  return result;
+}
+
+function applyVariantValue(sentinel, mock, path, value) {
+  // Handle $.prefixed paths (inside arrays) — these modify the element template
+  if (path.includes(".$")) {
+    const parts = path.split(".$.");
+    const arrayPath = parts[0];
+    const innerPath = parts.slice(1).join(".$.");
+    const arr = getNestedValue(sentinel, arrayPath);
+    if (Array.isArray(arr) && arr.length > 0) {
+      for (const item of arr) {
+        applyVariantValue(item, getNestedValue(mock, arrayPath)?.[0] || {}, innerPath, value);
+      }
+    }
+    return;
+  }
+
+  const pathParts = path.split(".");
+
+  if (value === "null") {
+    setNestedValue(sentinel, pathParts, null);
+  } else if (value === "empty") {
+    setNestedValue(sentinel, pathParts, []);
+  } else if (value === "populated") {
+    // Already populated from base sentinel, no change needed
+  } else if (value === "present") {
+    // Already present from base sentinel, no change needed
+  } else if (value === true || value === false) {
+    setNestedValue(sentinel, pathParts, value);
+  } else if (typeof value === "string") {
+    // Enum value: set the field to the actual value
+    setNestedValue(sentinel, pathParts, value);
+  }
+}
+
+function getNestedValue(obj, dottedPath) {
+  const parts = dottedPath.split(".");
+  let cur = obj;
+  for (const part of parts) {
+    if (cur === null || cur === undefined || typeof cur !== "object") return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+function setNestedValue(obj, parts, value) {
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur[parts[i]] === null || cur[parts[i]] === undefined || typeof cur[parts[i]] !== "object")
+      return;
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}