ruact 0.0.16 → 0.0.17

data/vendor/javascript/vite-plugin-ruact/flight-conformance.test.mjs

@@ -0,0 +1,286 @@
+// @vitest-environment jsdom
+//
+// Story 18-1 — React's Flight client (the copy vendored in the gem) reads what
+// the Ruby side writes. Every payload here is the serializer's own output,
+// written and guarded against drift by spec/ruact/flight/*_fixtures_spec.rb.
+//
+// The suite runs once per client build: FLIGHT_CLIENT_MODE=development (the
+// default) and =production (`npm test` runs both). CI also runs it against the
+// lowest React the gem supports.
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { act, createElement as h, Suspense } from "react";
+import { createRoot } from "react-dom/client";
+import { createFromReadableStream } from "virtual:ruact/flight-client";
+import { setModuleRegistry } from "./runtime/flight-modules.js";
+import { setBoundaryErrorHandler } from "./runtime/suspense-boundary.js";
+import { RootBoundary } from "./runtime/root-boundary.js";
+import { labelledStream } from "./runtime/transport.js";
+
+const MODE = process.env.FLIGHT_CLIENT_MODE || "development";
+const FIXTURES = path.join(import.meta.dirname, "../../../spec/fixtures/flight");
+const read = (name) => new Uint8Array(fs.readFileSync(path.join(FIXTURES, name)));
+const readJSON = (name) => JSON.parse(fs.readFileSync(path.join(FIXTURES, name), "utf8"));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+function Bad() {
+  throw new Error("boom");
+}
+
+function LikeButton({ likes, tags }) {
+  return h("button", null, `${likes}:${Array.isArray(tags) ? `[${tags.join(",")}]` : String(tags)}`);
+}
+setModuleRegistry({ "/LikeButton.jsx": { LikeButton }, "/Bad.jsx": { Bad } });
+
+function streamOf(chunks) {
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(chunk);
+      controller.close();
+    },
+  });
+}
+
+// As the runtime reads a response: through ./runtime/transport.js. React's
+// client returns a thenable, not a Promise; wrap it so `rejects` really checks.
+const decode = (chunks) => Promise.resolve(createFromReadableStream(labelledStream(streamOf(chunks))));
+
+async function mount(value) {
+  const container = document.createElement("div");
+  const root = createRoot(container);
+  await act(async () => {
+    root.render(h(Suspense, { fallback: "…" }, value));
+  });
+  return { container, root };
+}
+
+let consoleError;
+beforeEach(() => {
+  consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  consoleError.mockRestore();
+  setBoundaryErrorHandler(null);
+});
+
+describe(`React's Flight client (${MODE}) reads a page the Ruby side rendered`, () => {
+  // The development wire carries the slots React's development client reads.
+  const fixture = MODE === "development" ? "conformance_tree_dev.txt" : "conformance_tree.txt";
+  const html =
+    "<main><h1>Posts</h1>" +
+    "<article><button>1:[only]</button></article>" +
+    "<article><button>2:[only]</button></article>" +
+    "<article><button>3:[only]</button></article>" +
+    "<p>late</p><p>after</p></main>";
+
+  // FIRST render in this file on purpose: React reports a missing key once per
+  // location, so a later test would see nothing even on the wrong wire.
+  it("renders host elements, an ERB loop of client components and a Suspense child — and logs nothing", async () => {
+    const { container, root } = await mount(decode([read(fixture)]));
+    expect(container.innerHTML).toBe(html);
+    // The development build reports a missing key after the commit, on a later
+    // task; wait for it before concluding there is none.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(consoleError).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  it("keeps a one-element array prop a one-element array (Story 17.0a)", async () => {
+    const tree = await decode([read(fixture)]);
+    const article = tree.props.children[1];
+    expect(article.props.children.props.tags).toEqual(["only"]);
+  });
+
+  it("does not depend on where the network splits the bytes", async () => {
+    const bytes = read(fixture);
+    for (let cut = 1; cut < bytes.length; cut += 37) {
+      const { container, root } = await mount(decode([bytes.subarray(0, cut), bytes.subarray(cut)]));
+      expect(container.innerHTML).toBe(html);
+      act(() => root.unmount());
+    }
+  });
+});
+
+describe(`text rows (${MODE}) — Story 17-0d`, () => {
+  const expected = readJSON("text_framing_expected.json");
+
+  it("decodes every value the serializer framed, byte for byte", async () => {
+    expect(await decode([read("text_framing.txt")])).toEqual(expected);
+  });
+
+  it("decodes the same split at every byte, including inside lengths and code points", async () => {
+    const bytes = read("text_framing.txt");
+    for (let cut = 1; cut < bytes.length; cut += 1) {
+      expect(await decode([bytes.subarray(0, cut), bytes.subarray(cut)])).toEqual(expected);
+    }
+  });
+
+  it("decodes one byte at a time", async () => {
+    const bytes = read("text_framing.txt");
+    expect(await decode([...bytes].map((b) => Uint8Array.of(b)))).toEqual(expected);
+  });
+
+  it("puts long text inside Suspense content where the deferred row points", async () => {
+    const { container, root } = await mount(decode([read("text_framing_suspense.txt")]));
+    expect(container.querySelector("p").textContent).toBe(expected.multibyte);
+    act(() => root.unmount());
+  });
+
+  it("rejects a stream cut inside a text row instead of rendering part of it", async () => {
+    const bytes = read("text_framing.txt");
+    const cut = Buffer.from(bytes).indexOf(":T") + 10;
+    await expect(decode([bytes.subarray(0, cut)])).rejects.toThrow(/the response ended before the whole page arrived/);
+  });
+});
+
+describe(`dates and big integers (${MODE}) — Story 17-0c`, () => {
+  // Expected JSON tags what JSON cannot hold: { date: ISO } and { bigint: "…" }.
+  const revive = (value) => {
+    if (Array.isArray(value)) return value.map(revive);
+    if (value && typeof value === "object") {
+      if ("date" in value) return new Date(value.date);
+      if ("bigint" in value) return BigInt(value.bigint);
+      return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, revive(v)]));
+    }
+    return value;
+  };
+
+  it("rebuilds every value with its JS type, nested ones included", async () => {
+    expect(await decode([read("scalar_round_trip.txt")])).toEqual(revive(readJSON("scalar_round_trip_expected.json")));
+  });
+
+  it("keeps a literal string that starts with $D a string", async () => {
+    expect((await decode([read("scalar_round_trip.txt")])).literal).toBe("$D2026-01-01 is a string");
+  });
+
+  it("reads NaN, ±Infinity, undefined and an escaped $", async () => {
+    const value = await decode([new TextEncoder().encode(
+      '0:{"nan":"$NaN","inf":"$Infinity","ninf":"$-Infinity","negz":"$-0","und":"$undefined","cash":"$$5"}\n',
+    )]);
+    expect(Number.isNaN(value.nan)).toBe(true);
+    expect(value.inf).toBe(Infinity);
+    expect(value.ninf).toBe(-Infinity);
+    expect(Object.is(value.negz, -0)).toBe(true);
+    expect(value.und).toBeUndefined();
+    expect(value.cash).toBe("$5");
+  });
+});
+
+describe(`a Suspense child whose row is an error (${MODE})`, () => {
+  const timeout = () => read("conformance_suspense_timeout.txt");
+  // The same page, its Suspense row now content: the timeout fixture with the
+  // error row replaced.
+  const recovered = () => new TextEncoder().encode(
+    new TextDecoder().decode(timeout()).replace(/^1:E.*$/m, '1:["$","p",null,{"children":"late"}]'),
+  );
+
+  it("keeps the fallback on screen and reports the server's message, in production too", async () => {
+    const reported = [];
+    setBoundaryErrorHandler((error) => reported.push(error));
+    const { container, root } = await mount(decode([timeout()]));
+
+    expect(container.innerHTML).toBe("<span>loading</span>");
+    expect(reported.map((e) => e.message)).toEqual(["[ruact] Server error: Suspense timeout exceeded"]);
+    act(() => root.unmount());
+  });
+
+  it("keeps the fallback when the response ends before the Suspense row, in production too", async () => {
+    const reported = [];
+    setBoundaryErrorHandler((error) => reported.push(error));
+    const cut = new TextDecoder().decode(timeout()).replace(/^1:E.*\n?/m, "");
+    const tree = await decode([new TextEncoder().encode(cut)]);
+    const container = document.createElement("div");
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(h(RootBoundary, { tree }, h(Suspense, { fallback: "…" }, tree)));
+    });
+    expect(container.innerHTML).toBe("<span>loading</span>");
+    expect(reported.map((e) => e.message)).toEqual([
+      "[ruact] Server error: the response ended before the whole page arrived",
+    ]);
+    act(() => root.unmount());
+  });
+
+  it("keeps the fallback when the network fails mid-response", async () => {
+    const reported = [];
+    setBoundaryErrorHandler((error) => reported.push(error));
+    const head = new TextDecoder().decode(timeout()).replace(/^1:E.*\n?/m, "");
+    const failing = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(head));
+        setTimeout(() => controller.error(new TypeError("network error")), 0);
+      },
+    });
+    const tree = await createFromReadableStream(labelledStream(failing));
+    const container = document.createElement("div");
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(h(RootBoundary, { tree }, h(Suspense, { fallback: "…" }, tree)));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+    expect(container.innerHTML).toBe("<span>loading</span>");
+    expect(reported).toHaveLength(1);
+    act(() => root.unmount());
+  });
+
+  it("does not stay failed: the next response for the same page renders", async () => {
+    setBoundaryErrorHandler(() => {});
+    const { container, root } = await mount(decode([timeout()]));
+    expect(container.innerHTML).toBe("<span>loading</span>");
+
+    // What revalidate() or a navigation to a page of the same shape does.
+    const next = decode([recovered()]);
+    await act(async () => {
+      root.render(h(Suspense, { fallback: "…" }, next));
+    });
+    expect(container.innerHTML).toBe("<p>late</p>");
+    act(() => root.unmount());
+  });
+
+  it("lets a crash in the app's own component through, to the root's boundary", async () => {
+    const reported = [];
+    setBoundaryErrorHandler((error) => reported.push(error));
+    const wire = new TextDecoder().decode(timeout())
+      .replace(/^1:E.*$/m, '1:["$","$L5",null,{}]')
+      .replace(/^/, '5:I["/Bad.jsx",[],"Bad"]\n');
+    const tree = await decode([new TextEncoder().encode(wire)]);
+    const container = document.createElement("div");
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(h(RootBoundary, { tree }, tree));
+    });
+    expect(container.textContent).toBe("[ruact] Error: boom");
+    expect(reported).toEqual([]);
+    act(() => root.unmount());
+  });
+});
+
+describe(`a component missing from the registry (${MODE})`, () => {
+  it("shows an error in place of the page instead of removing it", async () => {
+    const tree = await decode([new TextEncoder().encode('1:I["/Gone.jsx",[],"Gone"]\n0:["$","$L1",null,{}]\n')]);
+    const container = document.createElement("div");
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(h(RootBoundary, { tree }, tree));
+    });
+    expect(container.textContent).toBe(
+      '[ruact] Error: client component not registered: /Gone.jsx — is it under app/javascript/components/ with "use client" at the top?',
+    );
+    act(() => root.unmount());
+  });
+});
+
+describe(`responses the router reads (${MODE})`, () => {
+  it("decodes a redirect body to the object the router checks", async () => {
+    // redirect_row.txt is what Ruact::Controller#redirect_to writes (controller_spec guards it).
+    expect(await decode([read("redirect_row.txt")])).toEqual({ redirectUrl: "/posts/1", redirectType: "push" });
+  });
+
+  it("rejects a stream that ends before its root row", async () => {
+    await expect(decode([new TextEncoder().encode('1:["$","p",null,{}]\n')])).rejects.toThrow(
+      /the response ended before the whole page arrived/,
+    );
+  });
+});

data/vendor/javascript/vite-plugin-ruact/index.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import { installServerFunctionsHooks } from "./server-functions-codegen.mjs";
 
 /**
@@ -56,6 +57,11 @@ const RESOLVED_REGISTRY_ID = "\0" + REGISTRY_VIRTUAL_ID;
 // `/@id/__x00__virtual:ruact/bootstrap`; prod Vite-manifest key
 // `virtual:ruact/bootstrap`). Mirrors REGISTRY_VIRTUAL_ID exactly.
 export const BOOTSTRAP_VIRTUAL_ID = "virtual:ruact/bootstrap";
+
+// Story 18-1 — React's Flight client, as the runtime imports it. The plugin
+// decides which copy answers (see `flightClientSource`).
+export const FLIGHT_CLIENT_VIRTUAL_ID = "virtual:ruact/flight-client";
+const RESOLVED_FLIGHT_CLIENT_ID = "\0" + FLIGHT_CLIENT_VIRTUAL_ID;
 const RESOLVED_BOOTSTRAP_ID = "\0" + BOOTSTRAP_VIRTUAL_ID;
 
 // The gem-shipped runtime sources the virtual bootstrap pulls in. Resolved
@@ -71,18 +77,30 @@ export default function ruact(options = {}) {
 
   let root;
   let manifest = {};
+  let flightClient; // { source: "app" | "vendored", version, mode }
 
   return installServerFunctionsHooks({
     name: "vite-plugin-ruact",
 
+    // Story 18-1 — the runtime (and React's Flight client vendored with it) is
+    // served from the gem's directory, not the app's. Its `react` and
+    // `react-dom` imports must still be the app's: one React instance.
+    config() {
+      return { resolve: { dedupe: ["react", "react-dom"] } };
+    },
+
     configResolved(config) {
       root = config.root;
+      flightClient = resolveFlightClient(root, config.isProduction ? "production" : "development");
+      // Dev server and build alike, so a build log shows it too.
+      config.logger?.info?.(`[ruact] Flight client: ${describeFlightClient(flightClient)}`);
     },
 
     // Story 10.1b / 14.2 — resolve ruact's virtual module ids.
     resolveId(id) {
       if (id === REGISTRY_VIRTUAL_ID) return RESOLVED_REGISTRY_ID;
       if (id === BOOTSTRAP_VIRTUAL_ID) return RESOLVED_BOOTSTRAP_ID;
+      if (id === FLIGHT_CLIENT_VIRTUAL_ID) return RESOLVED_FLIGHT_CLIENT_ID;
       return null;
     },
 
@@ -96,6 +114,7 @@ export default function ruact(options = {}) {
       // Story 14.2 — serve the gem-shipped bootstrap source, with its relative
       // runtime imports rewritten to absolute fs specifiers (see below).
       if (id === RESOLVED_BOOTSTRAP_ID) return generateBootstrapSource();
+      if (id === RESOLVED_FLIGHT_CLIENT_ID) return flightClientSource(flightClient);
       return null;
     },
 
@@ -303,28 +322,84 @@ export function generateRegistrySource(manifest) {
 // Story 14.2 (FR104) — render the virtual bootstrap source from the gem-shipped
 // `runtime/bootstrap.jsx`. A `load` hook returns module TEXT whose relative
 // imports resolve against the resolved id (`\0virtual:ruact/bootstrap`), which
-// is NOT a filesystem path — so `./flight-client.js` / `./ruact-router.js`
-// would fail. We rewrite those two specifiers to ABSOLUTE fs specifiers into the
+// is NOT a filesystem path — so `./flight-modules.js` / `./ruact-router.js`
+// would fail. We rewrite those specifiers to ABSOLUTE fs specifiers into the
 // gem `runtime/` dir (the same technique `generateRegistrySource` uses via
 // `toImportSpecifier`). The bare `react` / `react-dom/client` specifiers and the
 // `virtual:ruact/registry` id are left untouched — Vite resolves them from the
 // app root (so React comes from the USER's node_modules: one React instance).
 export function generateBootstrapSource(runtimeDir = RUNTIME_DIR) {
   const src = fs.readFileSync(path.join(runtimeDir, "bootstrap.jsx"), "utf8");
-  const abs = (name) => toImportSpecifier(path.join(runtimeDir, name));
-  // Rewrite EVERY `from './<runtime>.js'` import specifier to its absolute fs
-  // path. Matching the quoted `from '...'` form (not the bare filename) avoids
-  // hitting prose mentions of the file in comments, and the global regex
-  // tolerates either quote style. The replacement is supplied as a function so a
-  // `$` in the absolute path is never treated as a replacement pattern.
-  const rewrite = (code, name) => {
-    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return code.replace(
-      new RegExp(`from\\s+(['"])\\./${escaped}\\1`, "g"),
-      () => `from '${abs(name)}'`,
+  // Rewrite EVERY relative `from './<runtime>.js'` and side-effect
+  // `import './<runtime>.js'` specifier to its absolute fs path. Matching the
+  // quoted specifier after `from`/`import` (not the bare filename) leaves prose
+  // mentions of a file in comments alone, and either quote style is accepted.
+  // The replacement is a function so a `$` in the absolute path is never read
+  // as a replacement pattern.
+  return src.replace(
+    /\b(from|import)(\s+)(['"])\.\/([\w.-]+\.js)\3/g,
+    (_match, keyword, space, _quote, name) =>
+      `${keyword}${space}'${toImportSpecifier(path.join(runtimeDir, name))}'`,
+  );
+}
+
+// Story 18-1 (packaging option C, docs/internal/decisions/flight-client-compatibility.md)
+// — which copy of React's Flight client the runtime uses. The app's own
+// `react-server-dom-webpack` when the app declares it in its package.json (an
+// app that needs a different React version installs it); otherwise the copy
+// vendored in the gem, which brings no `webpack` into the app's install. A copy
+// that only resolves — another package's dependency, hoisted — is not chosen:
+// it was not picked for this app's React.
+export function resolveFlightClient(appRoot, mode, runtimeDir = RUNTIME_DIR) {
+  const vendored = () => {
+    const { version } = JSON.parse(
+      fs.readFileSync(path.join(runtimeDir, "vendor", "react-server-dom-webpack", "VERSION.json"), "utf8"),
     );
+    return { source: "vendored", version, mode };
   };
-  return rewrite(rewrite(src, "flight-client.js"), "ruact-router.js");
+  let declared = false;
+  try {
+    const app = JSON.parse(fs.readFileSync(path.join(appRoot, "package.json"), "utf8"));
+    declared = Boolean(app.dependencies?.["react-server-dom-webpack"] ?? app.devDependencies?.["react-server-dom-webpack"]);
+  } catch {
+    return vendored();
+  }
+  if (!declared) return vendored();
+  try {
+    const require = createRequire(path.join(appRoot, "package.json"));
+    const pkg = require("react-server-dom-webpack/package.json");
+    return { source: "app", version: pkg.version, mode };
+  } catch {
+    // Declared but not installed: npm install has not run. The vendored copy
+    // keeps the page working meanwhile.
+    return vendored();
+  }
+}
+
+export function describeFlightClient({ source, version, mode }) {
+  return source === "app"
+    ? `react-server-dom-webpack ${version} from the app (${mode})`
+    : `react-server-dom-webpack ${version} vendored in ruact (${mode})`;
+}
+
+// The `virtual:ruact/flight-client` module. The vendored copy is an ES module
+// whose webpack hooks are module-local. The app's copy is CommonJS reading
+// webpack's globals, which must exist before it evaluates — hence the
+// side-effect import first.
+export function flightClientSource({ source, mode }, runtimeDir = RUNTIME_DIR) {
+  const names = "createFromReadableStream, createFromFetch";
+  if (source === "app") {
+    const globals = toImportSpecifier(path.join(runtimeDir, "flight-webpack-globals.js"));
+    return [
+      `import '${globals}';`,
+      `export { ${names} } from 'react-server-dom-webpack/client.browser';`,
+      "",
+    ].join("\n");
+  }
+  const vendored = toImportSpecifier(
+    path.join(runtimeDir, "vendor", "react-server-dom-webpack", `client.browser.${mode}.js`),
+  );
+  return `export { ${names} } from '${vendored}';\n`;
 }
 
 // A bundler import specifier for an absolute fs path. Vite/Rollup resolve