@canmi/seam-react 0.2.14 → 0.4.3

package/scripts/skeleton/cache.mjs

@@ -0,0 +1,139 @@
+/* packages/client/react/scripts/skeleton/cache.mjs */
+
+import { build } from "esbuild";
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Parse import statements to map local names to specifiers */
+function parseComponentImports(source) {
+  const map = new Map();
+  const re = /import\s+(?:(\w+)\s*,?\s*)?(?:\{([^}]*)\}\s*)?from\s+['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    const [, defaultName, namedPart, specifier] = m;
+    if (defaultName) map.set(defaultName, specifier);
+    if (namedPart) {
+      for (const part of namedPart.split(",")) {
+        const t = part.trim();
+        if (!t) continue;
+        const asMatch = t.match(/^(\w+)\s+as\s+(\w+)$/);
+        if (asMatch) {
+          map.set(asMatch[2], specifier);
+          map.set(asMatch[1], specifier);
+        } else {
+          map.set(t, specifier);
+        }
+      }
+    }
+  }
+  return map;
+}
+
+/** Bundle each component via esbuild (write: false) and SHA-256 hash the output */
+async function computeComponentHashes(names, importMap, routesDir) {
+  const hashes = new Map();
+  const seen = new Set();
+  const tasks = [];
+  for (const name of names) {
+    const specifier = importMap.get(name);
+    if (!specifier || seen.has(specifier)) continue;
+    seen.add(specifier);
+    tasks.push(
+      build({
+        stdin: { contents: `import '${specifier}'`, resolveDir: routesDir, loader: "js" },
+        bundle: true,
+        write: false,
+        format: "esm",
+        platform: "node",
+        treeShaking: false,
+        external: ["react", "react-dom", "@canmi/seam-react", "@canmi/seam-i18n"],
+        logLevel: "silent",
+      })
+        .then((result) => {
+          const content = result.outputFiles[0]?.text || "";
+          const hash = createHash("sha256").update(content).digest("hex");
+          for (const [n, s] of importMap) {
+            if (s === specifier) hashes.set(n, hash);
+          }
+        })
+        .catch(() => {}),
+    );
+  }
+  await Promise.all(tasks);
+  return hashes;
+}
+
+/**
+ * Hash the build scripts themselves to invalidate cache when tooling changes.
+ * @param {string[]} scriptFiles - absolute paths of script files to hash
+ */
+function computeScriptHash(scriptFiles) {
+  const h = createHash("sha256");
+  for (const f of scriptFiles) h.update(readFileSync(f, "utf-8"));
+  return h.digest("hex");
+}
+
+function pathToSlug(path) {
+  const t = path
+    .replace(/^\/|\/$/g, "")
+    .replace(/\//g, "-")
+    .replace(/:/g, "");
+  return t || "index";
+}
+
+function readCache(cacheDir, slug) {
+  try {
+    return JSON.parse(readFileSync(join(cacheDir, `${slug}.json`), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cacheDir, slug, key, data) {
+  writeFileSync(join(cacheDir, `${slug}.json`), JSON.stringify({ key, data }));
+}
+
+function computeCacheKey(componentHash, manifestContent, config, scriptHash, locale, messagesJson) {
+  const h = createHash("sha256");
+  h.update(componentHash);
+  h.update(manifestContent);
+  h.update(JSON.stringify(config));
+  h.update(scriptHash);
+  if (locale) h.update(locale);
+  if (messagesJson) h.update(messagesJson);
+  return h.digest("hex").slice(0, 16);
+}
+
+let _createI18n = null;
+async function buildI18nValue(locale, messages, defaultLocale) {
+  if (!_createI18n) {
+    const mod = await import("@canmi/seam-i18n");
+    _createI18n = mod.createI18n;
+  }
+  const localeMessages = messages?.[locale] || {};
+  const fallback =
+    defaultLocale && locale !== defaultLocale ? messages?.[defaultLocale] || {} : undefined;
+  const instance = _createI18n(locale, localeMessages, fallback);
+  const usedKeys = new Set();
+  const origT = instance.t;
+  return {
+    locale: instance.locale,
+    t(key, params) {
+      usedKeys.add(key);
+      return origT(key, params);
+    },
+    _usedKeys: usedKeys,
+  };
+}
+
+export {
+  parseComponentImports,
+  computeComponentHashes,
+  computeScriptHash,
+  pathToSlug,
+  readCache,
+  writeCache,
+  computeCacheKey,
+  buildI18nValue,
+};

package/scripts/skeleton/layout.mjs

@@ -0,0 +1,109 @@
+/* packages/client/react/scripts/skeleton/layout.mjs */
+
+import { createElement } from "react";
+import { buildSentinelData } from "@canmi/seam-react";
+import {
+  generateMockFromSchema,
+  flattenLoaderMock,
+  deepMerge,
+  collectHtmlPaths,
+  createAccessTracker,
+  checkFieldAccess,
+} from "../mock-generator.mjs";
+import { guardedRender } from "./render.mjs";
+import { buildPageSchema } from "./schema.mjs";
+
+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.
+ * @param {{ buildWarnings: string[], seenWarnings: Set<string> }} ctx - shared warning state
+ */
+function renderLayout(LayoutComponent, id, entry, manifest, i18nValue, ctx) {
+  const mock = resolveLayoutMock(entry, manifest);
+  const schema =
+    Object.keys(entry.loaders || {}).length > 0 ? buildPageSchema(entry, manifest) : null;
+  const htmlPaths = schema ? collectHtmlPaths(schema) : new Set();
+  const data = Object.keys(mock).length > 0 ? buildSentinelData(mock, "", htmlPaths) : {};
+
+  // Wrap data with Proxy to detect schema/component field mismatches
+  const accessed = new Set();
+  const trackedData = Object.keys(data).length > 0 ? createAccessTracker(data, accessed) : data;
+
+  function LayoutWithOutlet() {
+    return createElement(LayoutComponent, null, createElement("seam-outlet", null));
+  }
+  const html = guardedRender(`layout:${id}`, LayoutWithOutlet, trackedData, i18nValue, ctx);
+
+  const fieldWarnings = checkFieldAccess(accessed, schema, `layout:${id}`);
+  for (const w of fieldWarnings) {
+    const msg = `[seam] warning: ${w}`;
+    if (!ctx.seenWarnings.has(msg)) {
+      ctx.seenWarnings.add(msg);
+      ctx.buildWarnings.push(msg);
+    }
+  }
+
+  return html;
+}
+
+/** 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;
+}
+
+export { toLayoutId, extractLayouts, resolveLayoutMock, renderLayout, flattenRoutes };

package/scripts/skeleton/process.mjs

@@ -0,0 +1,188 @@
+/* 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";
+
+async function processLayoutsWithCache(layoutMap, ctx) {
+  return Promise.all(
+    [...layoutMap.entries()].map(async ([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 = await 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,
+      };
+    }),
+  );
+}
+
+async function processRoutesWithCache(flat, ctx) {
+  return Promise.all(
+    flat.map(async (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 = await 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 };