@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/bundle-ui.ts

@@ -0,0 +1,211 @@
+// Per-surface iframe bundling.
+//
+// Each `ui.pages.*` / `ui.widgets.*` declared on a realm.ts app becomes its own
+// ESM bundle + per-surface CSS file. Both are content-addressed (sha-256 of the
+// JS bytes — the CSS is a sibling of the same hash) and served by Home at
+// `/api/ui-bundles/<hash>.{js,css}`. The iframe HTML loads the runtime first
+// (chrome + tokens + @yourrealm/sdk/ui base), then the per-surface CSS, then
+// the surface bundle; the runtime mounts the bundle's default export.
+//
+// The SDK subpaths and `zod` are externalized (EXTERNAL_SPECIFIERS below) so
+// Home's iframe importmap resolves them once for every surface: inlined, a
+// surface is ~414 KB raw (~71 KB gzipped); external, single-digit KB.
+//
+// CSS comes from Tailwind v4 with `@source` pointing at the per-surface JS
+// bundle, so it emits only the utilities that bundle's class strings use on top
+// of runtime.css (chrome + every @yourrealm/sdk/ui component class).
+
+import { dirname, join } from "@std/path";
+import { esbuildBinIn } from "./bundle.ts";
+import { RealmCompileError } from "./errors.ts";
+import { sha256Hex } from "./generator/hash.ts";
+import { isPacked } from "./pack.ts";
+import { extractUiSurfaceKeys, type SurfaceDescriptor } from "./sandbox.ts";
+import { mergePackedSource } from "./surfaces.ts";
+import { pkgRoot } from "./pkg-root.ts";
+import { findTailwindBin } from "./tailwind-bin.ts";
+
+const EVAL_PKG_DIR = pkgRoot(import.meta.url);
+
+const EXTERNAL_SPECIFIERS = [
+  "@yourrealm/sdk/ui",
+  "@yourrealm/sdk/services",
+  "@yourrealm/sdk/preact",
+  // JSX automatic runtime: esbuild emits `import { jsx as _jsx } from
+  // "@yourrealm/sdk/jsx-runtime"` for every <Component/> (--jsx-import-source
+  // below). External so the importmap gives all surfaces one preact instance.
+  "@yourrealm/sdk/jsx-runtime",
+  // Registry-gate helpers a `verifyAnonymousRequest` hook closes over at module
+  // load (e.g. Forge). The iframe never runs the gate, but the surface bundle
+  // imports the names, so the importmap resolves them to the runtime. The
+  // `@yourrealm/sdk` entry below already covers this subpath; it is listed
+  // explicitly to mirror the importmap.
+  "@yourrealm/sdk/docker",
+  "@yourrealm/sdk",
+  "zod",
+];
+
+/**
+ * Bundled iframe artifact for one ui surface. `jsBytes` is the ESM
+ * source Home serves at `/api/ui-bundles/<hash>.js`; `cssBytes` is
+ * the matching per-surface utility CSS served at the same hash with
+ * `.css`. `hash` is the content address of the JS bytes — CSS is a 1:1
+ * sibling, so two surfaces with identical JS share one hash and one CSS.
+ */
+export interface UiSurfaceBundle {
+  hash: string;
+  jsBytes: string;
+  cssBytes: string;
+  surface: SurfaceDescriptor;
+}
+
+function findNodeModules(startDir: string): string | null {
+  let dir = startDir;
+  while (true) {
+    const candidate = join(dir, "node_modules");
+    try {
+      Deno.statSync(candidate);
+      try {
+        Deno.statSync(join(candidate, "@yourrealm", "sdk"));
+        return candidate;
+      } catch {
+        // node_modules exists but doesn't expose @yourrealm/sdk - keep walking
+      }
+    } catch {
+      // no node_modules at this level
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function entryFor(surface: SurfaceDescriptor): string {
+  const accessor = surface.kind === "page" ? "pages" : "widgets";
+  return [
+    `import app from "./realm.tsx";`,
+    `if (!app || !app.ui || !app.ui.${accessor} || !app.ui.${accessor}[${JSON.stringify(surface.key)}]) {`,
+    `  throw new Error("ui.${accessor}.${surface.key} not declared on createApp output");`,
+    `}`,
+    `export default app.ui.${accessor}[${JSON.stringify(surface.key)}];`,
+    "",
+  ].join("\n");
+}
+
+async function esbuildEntry(entryFile: string, nodeModules: string | null): Promise<string> {
+  const externals = EXTERNAL_SPECIFIERS.flatMap((s) => ["--external:" + s]);
+  // The same binary bundle() spawns: bare `esbuild` only resolves when the
+  // invoking package happens to have it on PATH.
+  const cmd = new Deno.Command(esbuildBinIn(nodeModules), {
+    args: [
+      entryFile,
+      "--bundle",
+      "--format=esm",
+      "--platform=neutral",
+      "--main-fields=module,main",
+      "--target=es2020",
+      "--jsx=automatic",
+      "--jsx-import-source=@yourrealm/sdk",
+      // Strips esbuild's module-header comments, which carry the random
+      // temp-dir path and would make the hash non-deterministic across runs,
+      // along with all other whitespace. Identifier names are preserved.
+      "--minify-whitespace",
+      ...externals,
+    ],
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const { code, stdout, stderr } = await cmd.output();
+  if (code !== 0) {
+    const err = new TextDecoder().decode(stderr);
+    throw new RealmCompileError({ kind: "eval", message: err });
+  }
+  return new TextDecoder().decode(stdout);
+}
+
+const PER_SURFACE_CSS_TEMPLATE = `@import "tailwindcss/utilities" layer(utilities);
+@import "tailwindcss/theme.css" theme(reference);
+@source ".";
+`;
+
+async function tailwindForSurface(jsBundleDir: string, tailwindBin: string): Promise<string> {
+  // Tailwind v4 scans the directory pointed at by `@source` for class strings
+  // (.js files included), so each surface gets its own dir and Tailwind sees
+  // only that surface's bundle — no class bleed between siblings.
+  const cssIn = join(jsBundleDir, "in.css");
+  const cssOut = join(jsBundleDir, "out.css");
+  await Deno.writeTextFile(cssIn, PER_SURFACE_CSS_TEMPLATE);
+  const cmd = new Deno.Command(tailwindBin, {
+    args: ["--input", cssIn, "--output", cssOut, "--minify"],
+    cwd: jsBundleDir,
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const { code, stderr } = await cmd.output();
+  if (code !== 0) {
+    const err = new TextDecoder().decode(stderr);
+    throw new RealmCompileError({
+      kind: "eval",
+      message: `tailwindcss for surface failed:\n${err}`,
+    });
+  }
+  return await Deno.readTextFile(cssOut);
+}
+
+/**
+ * Bundle every ui surface declared on a realm.ts app. Each surface
+ * produces both an ESM JS bundle and a per-surface CSS file (utilities
+ * Tailwind extracted from the bundle's class strings).
+ *
+ * `source` is the original realm.ts text; `bundledCode` is the
+ * quickjs-shaped IIFE produced by `bundle(source)` and used here only
+ * to enumerate surface keys via the sandbox.
+ *
+ * The returned bundles map surface kind+key → JS + CSS bytes + content
+ * hash. Identical render code under the same key produces the same
+ * hash; Home can therefore content-deduplicate across uploads.
+ */
+export async function bundleUiSurfaces(
+  source: string,
+  bundledCode: string,
+): Promise<UiSurfaceBundle[]> {
+  const surfaces = await extractUiSurfaceKeys(bundledCode);
+  if (surfaces.length === 0) return [];
+
+  // The iframe entry imports `./realm.tsx` and reads `app.ui.<kind>[key]`, so it
+  // needs the merged source (surfaces attached on the app), not the raw packed
+  // artifact. Single-file sources pass through.
+  if (isPacked(source)) source = await mergePackedSource(source);
+
+  const resolveDir = Deno.env.get("ESBUILD_RESOLVE_DIR") ?? EVAL_PKG_DIR ?? Deno.cwd();
+  const tailwindBin = findTailwindBin(resolveDir);
+  const tmpDir = await Deno.makeTempDir({ prefix: "realm-ui-bundle-" });
+  try {
+    const nodeModules = findNodeModules(resolveDir);
+    if (nodeModules) {
+      await Deno.symlink(nodeModules, join(tmpDir, "node_modules"));
+    }
+    // Always .tsx so esbuild's tsx loader handles both plain TS and JSX: the
+    // source is opaque text, and authors pick whichever syntax they prefer.
+    await Deno.writeTextFile(join(tmpDir, "realm.tsx"), source);
+
+    const bundles: UiSurfaceBundle[] = [];
+    for (const surface of surfaces) {
+      const entryName = `entry-${surface.kind}-${surface.key}.tsx`;
+      const entryPath = join(tmpDir, entryName);
+      await Deno.writeTextFile(entryPath, entryFor(surface));
+      const jsBytes = await esbuildEntry(entryPath, nodeModules);
+      // Each surface gets its own scratch dir for tailwind so the
+      // @source "." scan only picks up this one bundle's classes.
+      const surfaceDir = join(tmpDir, `surface-${surface.kind}-${surface.key}`);
+      await Deno.mkdir(surfaceDir);
+      await Deno.writeTextFile(join(surfaceDir, "bundle.js"), jsBytes);
+      const cssBytes = await tailwindForSurface(surfaceDir, tailwindBin);
+      const hash = await sha256Hex(jsBytes);
+      bundles.push({ hash, jsBytes, cssBytes, surface });
+    }
+    return bundles;
+  } finally {
+    await Deno.remove(tmpDir, { recursive: true }).catch(() => {});
+  }
+}