ruact 0.0.5 → 0.0.7

data/vendor/javascript/vite-plugin-ruact/manifest-http.test.mjs

@@ -0,0 +1,125 @@
+// Fix (manifest-over-HTTP) — the dev server exposes the live in-memory manifest
+// at GET /__ruact/manifest so the Rails gem can resolve components without
+// racing the on-disk react-client-manifest.json write at boot. This file
+// covers the configureServer middleware:
+//
+//   1. responds with the current manifest (no internal `_sourceFile` field);
+//   2. reflects a rebuild when a "use client" component is added/changed.
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import ruact from "./index.js";
+
+let dir;
+beforeEach(() => {
+  dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "ruact-manifest-http-")));
+});
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function write(rel, body) {
+  const full = path.join(dir, rel);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, body);
+  return full;
+}
+
+const COMPONENT = (name) =>
+  `"use client";\nexport function ${name}() { return null; }\n`;
+
+// A minimal connect-style server harness: captures the path-mounted middleware
+// and the watcher callbacks the plugin registers in configureServer.
+function makeServer() {
+  const middlewares = new Map();
+  const watcherHandlers = { change: [], add: [], unlink: [] };
+  return {
+    middlewares: { use: (route, fn) => middlewares.set(route, fn) },
+    moduleGraph: { getModuleById: () => null, invalidateModule: () => {} },
+    ws: { send: () => {} },
+    watcher: {
+      add: () => {},
+      on: (event, fn) => {
+        (watcherHandlers[event] ||= []).push(fn);
+      },
+    },
+    _invokeMiddleware(route, method = "GET") {
+      const fn = middlewares.get(route);
+      let body = "";
+      let nextCalled = false;
+      const headers = {};
+      const res = {
+        setHeader: (k, v) => {
+          headers[k] = v;
+        },
+        end: (chunk) => {
+          body = chunk;
+        },
+      };
+      fn({ url: route, method }, res, () => {
+        nextCalled = true;
+      });
+      return { body, headers, nextCalled };
+    },
+    _fireChange(file) {
+      for (const fn of watcherHandlers.change) fn(file);
+    },
+  };
+}
+
+async function bootPlugin() {
+  const plugin = ruact();
+  await plugin.configResolved({ root: dir });
+  await plugin.buildStart({});
+  const server = makeServer();
+  await plugin.configureServer(server);
+  return server;
+}
+
+describe("GET /__ruact/manifest (dev server middleware)", () => {
+  it("serves the current manifest as JSON without the internal _sourceFile field", async () => {
+    write("app/javascript/components/LikeButton.jsx", COMPONENT("LikeButton"));
+    const server = await bootPlugin();
+
+    const { body, headers } = server._invokeMiddleware("/__ruact/manifest");
+    expect(headers["Content-Type"]).toBe("application/json");
+
+    const manifest = JSON.parse(body);
+    expect(manifest).toHaveProperty("LikeButton");
+    expect(manifest.LikeButton).toMatchObject({
+      id: "/LikeButton.jsx",
+      name: "LikeButton",
+      chunks: ["/LikeButton.jsx"],
+    });
+    // The internal field used only during the prod build must never go on the wire.
+    expect(manifest.LikeButton).not.toHaveProperty("_sourceFile");
+  });
+
+  it("reflects a rebuild when a new component is added", async () => {
+    write("app/javascript/components/LikeButton.jsx", COMPONENT("LikeButton"));
+    const server = await bootPlugin();
+
+    expect(JSON.parse(server._invokeMiddleware("/__ruact/manifest").body)).not.toHaveProperty(
+      "CommentBox"
+    );
+
+    const added = write("app/javascript/components/CommentBox.jsx", COMPONENT("CommentBox"));
+    server._fireChange(added);
+
+    const manifest = JSON.parse(server._invokeMiddleware("/__ruact/manifest").body);
+    expect(manifest).toHaveProperty("LikeButton");
+    expect(manifest).toHaveProperty("CommentBox");
+    expect(manifest.CommentBox).not.toHaveProperty("_sourceFile");
+  });
+
+  it("falls through (calls next) for non-GET methods", async () => {
+    write("app/javascript/components/LikeButton.jsx", COMPONENT("LikeButton"));
+    const server = await bootPlugin();
+
+    const { body, nextCalled } = server._invokeMiddleware("/__ruact/manifest", "POST");
+    expect(nextCalled).toBe(true);
+    expect(body).toBe("");
+  });
+});

data/vendor/javascript/vite-plugin-ruact/package-lock.json

@@ -9,6 +9,7 @@
       "version": "0.0.0-bundled",
       "license": "MIT",
       "devDependencies": {
+        "typescript": "^5.5.0",
         "vitest": "^2.0.0"
       }
     },
@@ -1259,12 +1260,27 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
     "node_modules/vite": {
       "version": "5.4.21",
       "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",

data/vendor/javascript/vite-plugin-ruact/package.json

@@ -5,9 +5,11 @@
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.scaffold.json && tsc --noEmit -p tsconfig.scaffold-agnostic.json"
   },
   "devDependencies": {
+    "typescript": "^5.5.0",
     "vitest": "^2.0.0"
   },
   "license": "MIT",

data/vendor/javascript/vite-plugin-ruact/registry.test.mjs

@@ -0,0 +1,199 @@
+// Story 10.1b (component auto-registry) — the build emits MODULE_REGISTRY.
+//
+// vite-plugin-ruact exposes a virtual module (`virtual:ruact/registry`) whose
+// default export is `{ [manifest id]: moduleExports }`, derived from the SAME
+// scan that writes react-client-manifest.json. This file covers:
+//
+//   1. generateRegistrySource — the pure renderer (keys == manifest ids,
+//      one import per source file, membership == manifest membership).
+//   2. dev id-match — registry keys equal the manifest `id` the gem serializes
+//      as the Flight moduleId (source-relative in dev).
+//   3. prod id-match (LOAD-BEARING, AC2/NFR16) — a REAL `vite build` through the
+//      plugin: the emitted manifest ids equal the built registry keys, proving
+//      dev/prod parity (the eager registry inlines components, so the
+//      hashed-URL rewrite never fires and the id stays source-relative in prod).
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { build } from "vite";
+import {
+  buildManifest,
+  generateRegistrySource,
+  REGISTRY_VIRTUAL_ID,
+} from "./index.js";
+import ruact from "./index.js";
+
+let dir;
+beforeEach(() => {
+  // realpath so the dir matches Rollup's symlink-resolved `facadeModuleId`
+  // (macOS /tmp → /private/tmp); the build's id-rewrite match keys off it.
+  dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "ruact-10-1b-")));
+});
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function write(rel, body) {
+  const full = path.join(dir, rel);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, body);
+}
+
+const USE_CLIENT = '"use client";';
+
+describe("generateRegistrySource (Story 10.1b)", () => {
+  it("keys the registry on the manifest `id` and imports the source file", () => {
+    write("PostList.jsx", [USE_CLIENT, "export function PostList() { return null; }"].join("\n"));
+    const manifest = buildManifest(dir);
+    const src = generateRegistrySource(manifest);
+
+    // Key == the manifest id the gem serializes as the Flight moduleId.
+    expect(manifest.PostList.id).toBe("/PostList.jsx");
+    expect(src).toContain('"/PostList.jsx":');
+    // Imports the absolute source file (forward-slashed specifier).
+    expect(src).toContain(`import * as __ruact_m0 from "${path.join(dir, "PostList.jsx").replace(/\\/g, "/")}"`);
+    expect(src).toContain("export default MODULE_REGISTRY;");
+  });
+
+  it("emits exactly one import per source file even with multiple exports", () => {
+    write(
+      "Pair.jsx",
+      [USE_CLIENT, "export function Primary() { return null; }", "export function Secondary() { return null; }"].join("\n")
+    );
+    const src = generateRegistrySource(buildManifest(dir));
+    // Both exports share the same id ("/Pair.jsx") → one import, one entry.
+    expect((src.match(/import \* as/g) || []).length).toBe(1);
+    expect((src.match(/"\/Pair\.jsx":/g) || []).length).toBe(1);
+  });
+
+  it("registry membership equals manifest membership (use-client only, .jsx/.tsx, nested)", () => {
+    write("Client.jsx", [USE_CLIENT, "export function Client() { return null; }"].join("\n"));
+    write("Typed.tsx", [USE_CLIENT, "export function Typed() { return null; }"].join("\n"));
+    write("ui/Button.jsx", [USE_CLIENT, "export function Button() { return null; }"].join("\n"));
+    // NOT registered: no "use client" directive.
+    write("ServerOnly.jsx", ["export function ServerOnly() { return null; }"].join("\n"));
+
+    const manifest = buildManifest(dir);
+    const src = generateRegistrySource(manifest);
+
+    expect(src).toContain('"/Client.jsx":');
+    expect(src).toContain('"/Typed.tsx":');
+    expect(src).toContain('"/ui/Button.jsx":'); // nested path preserved
+    expect(src).not.toContain("ServerOnly");
+    // Exactly the manifest ids, nothing more.
+    const ids = new Set(Object.values(manifest).map((e) => e.id));
+    for (const id of ids) expect(src).toContain(`${JSON.stringify(id)}:`);
+  });
+
+  it("renders an empty registry for a manifest with no components", () => {
+    const src = generateRegistrySource({});
+    expect(src).toContain("const MODULE_REGISTRY = {");
+    expect(src).toContain("export default MODULE_REGISTRY;");
+    expect(src).not.toContain("import * as");
+  });
+});
+
+describe("dev id-match invariant (Story 10.1b AC2)", () => {
+  it("registry keys equal the source-relative manifest ids (dev form)", () => {
+    write("PostList.jsx", [USE_CLIENT, "export function PostList() { return null; }"].join("\n"));
+    write("ui/Button.tsx", [USE_CLIENT, "export function Button() { return null; }"].join("\n"));
+    const manifest = buildManifest(dir);
+    const src = generateRegistrySource(manifest);
+
+    for (const entry of Object.values(manifest)) {
+      // entry.id is what client_manifest.rb serializes as moduleId; the registry
+      // MUST carry that exact key so moduleRegistry[moduleId] resolves.
+      expect(src).toContain(`${JSON.stringify(entry.id)}:`);
+    }
+    expect(manifest.PostList.id).toBe("/PostList.jsx");
+    expect(manifest.Button.id).toBe("/ui/Button.tsx");
+  });
+});
+
+describe("prod id-match invariant — real vite build (Story 10.1b AC2, LOAD-BEARING)", () => {
+  it("a built bundle resolves every manifest id through the emitted registry", async () => {
+    // Plain-JS components (no JSX/react) so the built bundle is self-contained
+    // and importable in node — the invariant under test is id↔key parity, not
+    // rendering. The eager registry inlines these into the entry chunk.
+    write("components/PostList.js", [USE_CLIENT, "export function PostList() { return 'PostList'; }"].join("\n"));
+    write("components/PostForm.js", [USE_CLIENT, "export function PostForm() { return 'PostForm'; }"].join("\n"));
+    write("components/ui/Button.js", [USE_CLIENT, "export function Button() { return 'Button'; }"].join("\n"));
+    // Entry re-exports the auto-registry so we can inspect it post-build.
+    write("entry.js", `export { default as registry } from ${JSON.stringify(REGISTRY_VIRTUAL_ID)};`);
+
+    await build({
+      root: dir,
+      logLevel: "silent",
+      plugins: [ruact({ componentsDir: "components" })],
+      build: {
+        outDir: "dist",
+        write: true,
+        minify: false,
+        rollupOptions: {
+          input: path.join(dir, "entry.js"),
+          // Keep the entry's `registry` export (a Vite app build otherwise
+          // tree-shakes unused entry exports, emptying the chunk).
+          preserveEntrySignatures: "strict",
+          output: { entryFileNames: "entry.js", format: "es" },
+        },
+      },
+    });
+
+    // The manifest the gem will read (ids === Flight moduleIds).
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(dir, "public/react-client-manifest.json"), "utf8")
+    );
+    const manifestIds = new Set(Object.values(manifest).map((e) => e.id));
+
+    // Prod ids stay source-relative (eager-inlined components → no facade chunk
+    // → generateBundle's hashed-URL rewrite never fires). This is the dev/prod
+    // parity guarantee (NFR16).
+    expect(manifestIds).toEqual(new Set(["/PostList.js", "/PostForm.js", "/ui/Button.js"]));
+
+    // The built registry's keys equal the manifest ids exactly, and each value
+    // exposes the component export the Flight client looks up (mod[exportName]).
+    const built = await import(pathToFileURL(path.join(dir, "dist/entry.js")).href);
+    const registry = built.registry;
+    expect(new Set(Object.keys(registry))).toEqual(manifestIds);
+    for (const [name, entry] of Object.entries(manifest)) {
+      // moduleRegistry[moduleId][exportName] must be defined for every manifest entry.
+      expect(registry[entry.id][entry.name]).toBeTypeOf("function");
+      expect(registry[entry.id][entry.name]()).toBe(name);
+    }
+  }, 30000);
+
+  it("FAILS the build loudly if a component becomes a hashed facade chunk (no silent miss)", async () => {
+    // The hazardous branch: a component is ALSO a Rollup entry → it gets its own
+    // hashed facade chunk → generateBundle would rewrite its manifest id to the
+    // hashed URL while the registry still keys it by source path. The id-match
+    // guard must turn that into a build error, not a silent prod hydration miss.
+    write("components/PostList.js", [USE_CLIENT, "export function PostList() { return 'PostList'; }"].join("\n"));
+    write("entry.js", `export { default as registry } from ${JSON.stringify(REGISTRY_VIRTUAL_ID)};`);
+
+    await expect(
+      build({
+        root: dir,
+        logLevel: "silent",
+        plugins: [ruact({ componentsDir: "components" })],
+        build: {
+          outDir: "dist",
+          write: false,
+          minify: false,
+          rollupOptions: {
+            // Force the component to be its own entry → hashed facade chunk.
+            input: {
+              entry: path.join(dir, "entry.js"),
+              PostList: path.join(dir, "components/PostList.js"),
+            },
+            preserveEntrySignatures: "strict",
+            // Hashed names mirror a real prod build (the rewrite the guard catches).
+            output: { entryFileNames: "[name]-[hash].js", format: "es" },
+          },
+        },
+      })
+    ).rejects.toThrow(/silent hydration miss|standalone .* chunks/i);
+  }, 30000);
+});

data/vendor/javascript/vite-plugin-ruact/runtime/bootstrap.jsx

@@ -0,0 +1,68 @@
+// Ruact bootstrap entry — served to the app as the virtual module
+// `virtual:ruact/bootstrap` (Story 14.2, FR104). This source ships INSIDE the
+// gem so it never sits in the user's `app/javascript/` tree; the bundled
+// vite-plugin's resolveId/load serve it (mirroring `virtual:ruact/registry`).
+//
+// IMPORTANT — this file is loaded as VIRTUAL-MODULE TEXT, not from disk, so its
+// resolved id is `\0virtual:ruact/bootstrap`, which is NOT a filesystem path:
+//   • Relative imports (`./flight-client.js`) do NOT resolve from a `\0virtual:`
+//     id. The plugin's `load` hook rewrites the two runtime imports below to
+//     ABSOLUTE fs specifiers into the gem `runtime/` dir before serving them
+//     (see `generateBootstrapSource` in index.js).
+//   • Bare specifiers (`react`, `react-dom/client`) and the `virtual:` id DO
+//     resolve — Vite resolves them from the APP ROOT, so React/react-dom come
+//     from the USER's node_modules (a single React instance — non-negotiable).
+//   • No JSX syntax is used here (the inner App is built with `createElement`)
+//     so the virtual module loads through Vite's default loader exactly like
+//     `virtual:ruact/registry`, with no dependency on @vitejs/plugin-react
+//     transforming a `\0virtual:` id.
+import { createRoot } from 'react-dom/client';
+import { createElement, useState, useEffect } from 'react';
+import { createFromFlightPayload } from './flight-client.js';
+import { setupRouter, teardownRouter } from './ruact-router.js';
+
+// MODULE_REGISTRY maps react-client-manifest "id" values to component exports.
+// It is auto-derived by vite-plugin-ruact from the SAME scan that emits
+// public/react-client-manifest.json — every "use client" component under
+// app/javascript/components/ is registered automatically, so adding or removing
+// one needs ZERO edits here. (To opt a component out, place it outside
+// app/javascript/components/ or drop its "use client" directive.)
+import MODULE_REGISTRY from 'virtual:ruact/registry';
+
+// ---------------------------------------------------------------------------
+// Boot
+// ---------------------------------------------------------------------------
+const flightData = globalThis.__FLIGHT_DATA;
+
+if (!flightData || flightData.length === 0) {
+  // Non-RSC page or Rails server not running — skip hydration.
+  const root = document.getElementById('root');
+  if (root && root.childNodes.length === 0) {
+    root.textContent = '[ruact] No Flight data found — is the Rails server running?';
+  }
+} else {
+  const payload = flightData.join('');
+
+  let initialTree;
+  try {
+    initialTree = createFromFlightPayload(payload, MODULE_REGISTRY);
+  } catch (err) {
+    console.error('[ruact] Failed to parse Flight payload:', err);
+    const root = document.getElementById('root');
+    if (root) root.textContent = '[ruact] Error: ' + err.message;
+    throw err;
+  }
+
+  function App() {
+    const [tree, setTree] = useState(() => initialTree);
+
+    useEffect(() => {
+      setupRouter({ onNavigate: setTree, moduleRegistry: MODULE_REGISTRY });
+      return () => teardownRouter();
+    }, []);
+
+    return tree;
+  }
+
+  createRoot(document.getElementById('root')).render(createElement(App));
+}

data/vendor/javascript/vite-plugin-ruact/runtime/flight-client.js

@@ -0,0 +1,235 @@
+/**
+ * Minimal React Flight wire format parser.
+ *
+ * Handles the subset we emit from the Ruby server:
+ *   - Model rows:  <hex_id>:<json>\n
+ *   - Import rows: <hex_id>:I[moduleId, exportName, chunks]\n
+ *
+ * Returns a React element tree by recursively converting
+ * ["$", type, key, props] tuples into React.createElement calls.
+ *
+ * Supports Suspense streaming:
+ *   - "$SS" element type → React.Suspense
+ *   - "$L{hex}" referencing a missing row → React.lazy() that resolves when the row arrives
+ */
+
+import { createElement, Fragment, lazy, Suspense } from "react";
+
+// ---------------------------------------------------------------------------
+// Pending chunk registry — used for streaming Suspense deferred rows
+// ---------------------------------------------------------------------------
+
+const pendingChunks = new Map(); // rowId → { promise, resolve }
+const lazyCache     = new Map(); // rowId → React.lazy component (memoized)
+
+/** Clear all pending lazy refs. Call at the start of each navigation. */
+export function clearPendingChunks() {
+  pendingChunks.clear();
+  lazyCache.clear();
+}
+
+/**
+ * Called when a deferred model row arrives during streaming.
+ * Resolves the pending lazy component so React re-renders the Suspense boundary.
+ *
+ * @param {number} rowId
+ * @param {*}      element - the React element tree built from the deferred row
+ */
+export function resolvePendingChunk(rowId, element) {
+  const chunk = pendingChunks.get(rowId);
+  if (chunk) {
+    chunk.resolve(element);
+    pendingChunks.delete(rowId);
+  }
+}
+
+function createLazyForPending(rowId) {
+  if (lazyCache.has(rowId)) return lazyCache.get(rowId);
+
+  let resolve;
+  const promise = new Promise((r) => { resolve = r; });
+  pendingChunks.set(rowId, { promise, resolve });
+
+  // React.lazy expects { default: ComponentType }. We wrap the element in a function component.
+  const LazyComp = lazy(() => promise.then((el) => ({ default: () => el })));
+  lazyCache.set(rowId, LazyComp);
+  return LazyComp;
+}
+
+// ---------------------------------------------------------------------------
+// Row parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single Flight wire format line into { id, row }.
+ * Returns null for blank or malformed lines.
+ *
+ * @param {string} line
+ * @returns {{ id: number, row: object } | null}
+ */
+export function parseLine(line) {
+  if (!line.trim()) return null;
+
+  const colonIdx = line.indexOf(":");
+  if (colonIdx === -1) return null;
+
+  const id   = parseInt(line.slice(0, colonIdx), 16);
+  const rest = line.slice(colonIdx + 1);
+
+  try {
+    if (rest.startsWith("I")) {
+      const [moduleId, exportName] = JSON.parse(rest.slice(1));
+      return { id, row: { kind: "import", moduleId, exportName } };
+    }
+
+    if (rest.startsWith("E")) {
+      const errorData = JSON.parse(rest.slice(1));
+      const message = typeof errorData === "string"
+        ? errorData
+        : (errorData.message || String(errorData));
+      return { id, row: { kind: "error", message } };
+    }
+
+    return { id, row: { kind: "model", value: JSON.parse(rest) } };
+  } catch (e) {
+    console.warn("[flight-client] Skipping malformed row:", line, e);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tree building
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a React element tree from a fully-populated rows Map.
+ *
+ * @param {Map}    rows           - id → { kind, ... } rows
+ * @param {Object} moduleRegistry - { [moduleId]: { [exportName]: Component } }
+ * @returns React element tree
+ */
+export function buildTreeFromRows(rows, moduleRegistry) {
+  const root = rows.get(0);
+  if (!root) throw new Error("[flight-client] No root row (id=0) found in payload");
+  if (root.kind === "error") throw new Error(`[ruact] Server error: ${root.message}`);
+  if (root.kind !== "model") throw new Error("[flight-client] Root row is not a model row");
+  return buildTree(root.value, rows, moduleRegistry);
+}
+
+/**
+ * Build a React element tree from a single row value.
+ * Used when resolving a deferred (Suspense) row that has arrived via streaming.
+ *
+ * @param {*}      value
+ * @param {Map}    rows
+ * @param {Object} moduleRegistry
+ */
+export function buildTree(value, rows, moduleRegistry) {
+  return _buildTree(value, rows, moduleRegistry);
+}
+
+/**
+ * Parse a Flight payload string and return a React element tree.
+ * Convenience wrapper — used for the initial (non-streaming) page load.
+ *
+ * @param {string}  payload
+ * @param {Object}  moduleRegistry
+ */
+export function createFromFlightPayload(payload, moduleRegistry) {
+  const rows = new Map();
+  for (const line of payload.split("\n")) {
+    const parsed = parseLine(line);
+    if (parsed) rows.set(parsed.id, parsed.row);
+  }
+  return buildTreeFromRows(rows, moduleRegistry);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _buildTree(value, rows, moduleRegistry) {
+  if (value === null || value === undefined) return value;
+
+  // --- Strings with special $ prefixes ---
+  if (typeof value === "string") {
+    if (value.startsWith("$$"))   return value.slice(1);   // escaped $
+    if (value === "$undefined")   return undefined;
+    if (value === "$NaN")         return NaN;
+    if (value === "$Infinity")    return Infinity;
+    if (value === "$-Infinity")   return -Infinity;
+    if (value === "$-0")          return -0;
+    if (value.startsWith("$L")) {
+      const refId = parseInt(value.slice(2), 16);
+      const row   = rows.get(refId);
+
+      if (!row) {
+        // Row hasn't arrived yet — create a lazy component that suspends until it does
+        return createLazyForPending(refId);
+      }
+      if (row.kind === "error") {
+        throw new Error(`[ruact] Server error: ${row.message}`);
+      }
+      if (row.kind === "import") {
+        const mod = moduleRegistry[row.moduleId];
+        if (!mod) throw new Error(`[flight-client] Module not registered: ${row.moduleId}`);
+        const component = mod[row.exportName];
+        if (!component) throw new Error(`[flight-client] Export "${row.exportName}" not found in ${row.moduleId}`);
+        return component;
+      }
+      // Model row — deferred content already arrived (non-streaming path).
+      // Wrap in a function component so it can be used as a type in createElement.
+      const content = _buildTree(row.value, rows, moduleRegistry);
+      return () => content;
+    }
+    return value;
+  }
+
+  // --- Arrays ---
+  if (Array.isArray(value)) {
+    // React element tuple: ["$", type, key, props]
+    if (value[0] === "$") {
+      const [, rawType, key, rawProps] = value;
+      const type   = resolveType(rawType, rows, moduleRegistry);
+      const props  = buildProps(rawProps, rows, moduleRegistry);
+      if (key != null) props.key = key;
+      return createElement(type, props);
+    }
+
+    // Plain array / fragment children
+    const items = value.map((v) => _buildTree(v, rows, moduleRegistry));
+    return items.length === 1 ? items[0] : items;
+  }
+
+  // --- Plain objects ---
+  if (typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, _buildTree(v, rows, moduleRegistry)])
+    );
+  }
+
+  return value;
+}
+
+function resolveType(rawType, rows, moduleRegistry) {
+  if (typeof rawType === "string") {
+    if (rawType === "$SS")        return Suspense;                                    // React.Suspense
+    if (rawType.startsWith("$L")) return _buildTree(rawType, rows, moduleRegistry);  // lazy / import
+    return rawType;
+  }
+  return rawType;
+}
+
+function buildProps(rawProps, rows, moduleRegistry) {
+  if (!rawProps) return {};
+  const props = {};
+  for (const [key, val] of Object.entries(rawProps)) {
+    if (key === "children") {
+      const children = _buildTree(val, rows, moduleRegistry);
+      if (children !== undefined) props.children = children;
+    } else {
+      props[key] = _buildTree(val, rows, moduleRegistry);
+    }
+  }
+  return props;
+}