@canmi/seam-react 0.2.3 → 0.3.7

package/scripts/skeleton/process.mjs

@@ -0,0 +1,184 @@
+/* packages/client/react/scripts/skeleton/process.mjs */
+
+import { buildI18nValue, computeCacheKey, pathToSlug, readCache, writeCache } from "./cache.mjs";
+import { renderLayout } from "./layout.mjs";
+import { renderRoute } from "./schema.mjs";
+
+function processLayoutsWithCache(layoutMap, ctx) {
+  return [...layoutMap.entries()].map(([id, entry]) => {
+    // i18n: render once per locale, return localeHtml map
+    if (ctx.i18n) {
+      const localeHtml = {};
+      let collectedKeys = null;
+      for (const locale of ctx.i18n.locales) {
+        const i18nValue = buildI18nValue(locale, ctx.i18n.messages, ctx.i18n.default);
+        const messagesJson = JSON.stringify(ctx.i18n.messages?.[locale] || {});
+        const compHash = ctx.componentHashes.get(entry.component?.name);
+        if (compHash) {
+          const config = { id, loaders: entry.loaders, mock: entry.mock };
+          const key = computeCacheKey(
+            compHash,
+            ctx.manifestContent,
+            config,
+            ctx.scriptHash,
+            locale,
+            messagesJson,
+          );
+          const slug = `layout_${id}_${locale}`;
+          const cached = readCache(ctx.cacheDir, slug);
+          if (cached && cached.key === key) {
+            ctx.stats.hits++;
+            localeHtml[locale] = cached.data.html;
+            if (!collectedKeys) collectedKeys = cached.data.i18nKeys;
+            continue;
+          }
+          const html = renderLayout(
+            entry.component,
+            id,
+            entry,
+            ctx.manifest,
+            i18nValue,
+            ctx.warnCtx,
+          );
+          const i18nKeys = [...i18nValue._usedKeys].sort();
+          writeCache(ctx.cacheDir, slug, key, { html, i18nKeys });
+          ctx.stats.misses++;
+          localeHtml[locale] = html;
+          if (!collectedKeys) collectedKeys = i18nKeys;
+        } else {
+          ctx.stats.misses++;
+          const html = renderLayout(
+            entry.component,
+            id,
+            entry,
+            ctx.manifest,
+            i18nValue,
+            ctx.warnCtx,
+          );
+          const i18nKeys = [...i18nValue._usedKeys].sort();
+          localeHtml[locale] = html;
+          if (!collectedKeys) collectedKeys = i18nKeys;
+        }
+      }
+      return {
+        id,
+        localeHtml,
+        loaders: entry.loaders,
+        parent: entry.parentId,
+        i18nKeys: collectedKeys || [],
+      };
+    }
+
+    // No i18n: original behavior
+    const compHash = ctx.componentHashes.get(entry.component?.name);
+    if (compHash) {
+      const config = { id, loaders: entry.loaders, mock: entry.mock };
+      const key = computeCacheKey(compHash, ctx.manifestContent, config, ctx.scriptHash);
+      const slug = `layout_${id}`;
+      const cached = readCache(ctx.cacheDir, slug);
+      if (cached && cached.key === key) {
+        ctx.stats.hits++;
+        return cached.data;
+      }
+      const data = {
+        id,
+        html: renderLayout(entry.component, id, entry, ctx.manifest, undefined, ctx.warnCtx),
+        loaders: entry.loaders,
+        parent: entry.parentId,
+      };
+      writeCache(ctx.cacheDir, slug, key, data);
+      ctx.stats.misses++;
+      return data;
+    }
+    ctx.stats.misses++;
+    return {
+      id,
+      html: renderLayout(entry.component, id, entry, ctx.manifest, undefined, ctx.warnCtx),
+      loaders: entry.loaders,
+      parent: entry.parentId,
+    };
+  });
+}
+
+function processRoutesWithCache(flat, ctx) {
+  return flat.map((r) => {
+    // i18n: render once per locale, return localeVariants map
+    if (ctx.i18n) {
+      const localeVariants = {};
+      let collectedKeys = null;
+      for (const locale of ctx.i18n.locales) {
+        const i18nValue = buildI18nValue(locale, ctx.i18n.messages, ctx.i18n.default);
+        const messagesJson = JSON.stringify(ctx.i18n.messages?.[locale] || {});
+        const compHash = ctx.componentHashes.get(r.component?.name);
+        if (compHash) {
+          const config = { path: r.path, loaders: r.loaders, mock: r.mock, nullable: r.nullable };
+          const key = computeCacheKey(
+            compHash,
+            ctx.manifestContent,
+            config,
+            ctx.scriptHash,
+            locale,
+            messagesJson,
+          );
+          const slug = `route_${pathToSlug(r.path)}_${locale}`;
+          const cached = readCache(ctx.cacheDir, slug);
+          if (cached && cached.key === key) {
+            ctx.stats.hits++;
+            localeVariants[locale] = cached.data;
+            if (!collectedKeys) collectedKeys = cached.data.i18nKeys;
+            continue;
+          }
+          const data = renderRoute(r, ctx.manifest, i18nValue, ctx.warnCtx);
+          data.i18nKeys = [...i18nValue._usedKeys].sort();
+          writeCache(ctx.cacheDir, slug, key, data);
+          ctx.stats.misses++;
+          localeVariants[locale] = data;
+          if (!collectedKeys) collectedKeys = data.i18nKeys;
+        } else {
+          ctx.stats.misses++;
+          const data = renderRoute(r, ctx.manifest, i18nValue, ctx.warnCtx);
+          data.i18nKeys = [...i18nValue._usedKeys].sort();
+          localeVariants[locale] = data;
+          if (!collectedKeys) collectedKeys = data.i18nKeys;
+        }
+      }
+      // Combine per-locale data into the expected output format
+      const first = localeVariants[ctx.i18n.locales[0]];
+      return {
+        path: r.path,
+        loaders: first.loaders,
+        layout: first.layout,
+        mock: first.mock,
+        pageSchema: first.pageSchema,
+        i18nKeys: collectedKeys || [],
+        localeVariants: Object.fromEntries(
+          Object.entries(localeVariants).map(([loc, data]) => [
+            loc,
+            { axes: data.axes, variants: data.variants, mockHtml: data.mockHtml },
+          ]),
+        ),
+      };
+    }
+
+    // No i18n: original behavior
+    const compHash = ctx.componentHashes.get(r.component?.name);
+    if (compHash) {
+      const config = { path: r.path, loaders: r.loaders, mock: r.mock, nullable: r.nullable };
+      const key = computeCacheKey(compHash, ctx.manifestContent, config, ctx.scriptHash);
+      const slug = `route_${pathToSlug(r.path)}`;
+      const cached = readCache(ctx.cacheDir, slug);
+      if (cached && cached.key === key) {
+        ctx.stats.hits++;
+        return cached.data;
+      }
+      const data = renderRoute(r, ctx.manifest, undefined, ctx.warnCtx);
+      writeCache(ctx.cacheDir, slug, key, data);
+      ctx.stats.misses++;
+      return data;
+    }
+    ctx.stats.misses++;
+    return renderRoute(r, ctx.manifest, undefined, ctx.warnCtx);
+  });
+}
+
+export { processLayoutsWithCache, processRoutesWithCache };

package/scripts/skeleton/render.mjs

@@ -0,0 +1,160 @@
+/* packages/client/react/scripts/skeleton/render.mjs */
+
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { SeamDataProvider } from "@canmi/seam-react";
+
+let _I18nProvider = null;
+
+export function setI18nProvider(provider) {
+  _I18nProvider = provider;
+}
+
+class SeamBuildError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SeamBuildError";
+  }
+}
+
+// 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 renderWithData(component, data, i18nValue) {
+  const inner = createElement(SeamDataProvider, { value: data }, createElement(component));
+  if (i18nValue && _I18nProvider) {
+    return renderToString(createElement(_I18nProvider, { value: i18nValue }, inner));
+  }
+  return renderToString(inner);
+}
+
+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, "");
+}
+
+/**
+ * Render a component with full safety guards.
+ * @param {string} routePath - route or layout identifier for error messages
+ * @param {Function} component - React component to render
+ * @param {object} data - sentinel or tracked data
+ * @param {object|null} i18nValue - i18n context value
+ * @param {{ buildWarnings: string[], seenWarnings: Set<string> }} ctx - shared warning state
+ */
+function guardedRender(routePath, component, data, i18nValue, ctx) {
+  const violations = [];
+  const teardowns = [];
+
+  installRenderTraps(violations, teardowns);
+
+  let html;
+  try {
+    html = renderWithData(component, data, i18nValue);
+  } catch (e) {
+    if (e instanceof SeamBuildError) {
+      throw new SeamBuildError(
+        `[seam] error: Skeleton rendering failed for route "${routePath}":\n` +
+          `       ${e.message}\n\n` +
+          "       Move browser API calls into useEffect() or event handlers.",
+      );
+    }
+    throw e;
+  } 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 — dedup per message
+  for (const v of violations) {
+    const msg = `[seam] warning: ${routePath}\n  ${v.reason}`;
+    if (!ctx.seenWarnings.has(msg)) {
+      ctx.seenWarnings.add(msg);
+      ctx.buildWarnings.push(msg);
+    }
+  }
+  if (violations.length > 0) {
+    html = stripResourceHints(html);
+  }
+
+  return html;
+}
+
+export { SeamBuildError, guardedRender, stripResourceHints, RESOURCE_HINT_RE };

package/scripts/skeleton/schema.mjs

@@ -0,0 +1,120 @@
+/* packages/client/react/scripts/skeleton/schema.mjs */
+
+import { buildSentinelData } from "@canmi/seam-react";
+import {
+  collectStructuralAxes,
+  cartesianProduct,
+  buildVariantSentinel,
+} from "../variant-generator.mjs";
+import {
+  generateMockFromSchema,
+  flattenLoaderMock,
+  deepMerge,
+  collectHtmlPaths,
+  createAccessTracker,
+  checkFieldAccess,
+} from "../mock-generator.mjs";
+import { SeamBuildError, guardedRender, stripResourceHints } from "./render.mjs";
+
+/**
+ * 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.",
+  );
+}
+
+/**
+ * Render a route: generate variants from structural axes, plus a mock-data render for CTR check.
+ * @param {{ buildWarnings: string[], seenWarnings: Set<string> }} ctx - shared warning state
+ */
+function renderRoute(route, manifest, i18nValue, ctx) {
+  const mock = resolveRouteMock(route, manifest);
+  const pageSchema = buildPageSchema(route, manifest);
+  const htmlPaths = pageSchema ? collectHtmlPaths(pageSchema) : new Set();
+  const baseSentinel = buildSentinelData(mock, "", htmlPaths);
+  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, i18nValue, ctx);
+    return { variant, html };
+  });
+
+  // Render with real mock data for CTR equivalence check.
+  // Wrap mock with Proxy to track field accesses and detect schema mismatches.
+  const accessed = new Set();
+  const trackedMock = createAccessTracker(mock, accessed);
+  const mockHtml = stripResourceHints(
+    guardedRender(route.path, route.component, trackedMock, i18nValue, ctx),
+  );
+
+  const fieldWarnings = checkFieldAccess(accessed, pageSchema, route.path);
+  for (const w of fieldWarnings) {
+    const msg = `[seam] warning: ${w}`;
+    if (!ctx.seenWarnings.has(msg)) {
+      ctx.seenWarnings.add(msg);
+      ctx.buildWarnings.push(msg);
+    }
+  }
+
+  return {
+    path: route.path,
+    loaders: route.loaders,
+    layout: route._layoutId || undefined,
+    axes,
+    variants,
+    mockHtml,
+    mock,
+    pageSchema,
+  };
+}
+
+export { buildPageSchema, resolveRouteMock, renderRoute };