ruact 0.0.18 → 0.0.20

data/lib/ruact/view_helper/suspense.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ViewHelper
+    # The helper a `<Suspense>` becomes ({ErbPreprocessor}). Part of
+    # {ViewHelper}.
+    module Suspense
+      # A `<Suspense>`: the preprocessor makes the ERB between its tags this
+      # block's body, and passes the `fallback` and `delay` attributes as the
+      # template wrote them.
+      #
+      # In an action that streams (`ruact_streaming`), the block is kept, not
+      # run: the marker ({Markers}) carries its index, and the response renders
+      # it after the shell is sent ({DeferredRender}). Anywhere else the content
+      # is evaluated here, in place, so the page renders as one piece — and, in
+      # development, the log says the action could stream.
+      #
+      # Only what the block writes is the content: a value it ends on is not
+      # (`capture` would print a block's value when it writes nothing).
+      def __ruact_suspense__(fallback, delay = nil, &block)
+        ctx = @ruact_render_context
+        if ctx&.deferring?
+          index = ctx.defer_block(RenderContext::Block.new(self, block, @virtual_path, @current_template,
+                                                           caller_locations(1, 1).first))
+          return "#{Markers.suspense_open(fallback, delay, block: index)}#{Markers::SUSPENSE_CLOSE}".html_safe
+        end
+
+        __ruact_note_unstreamed_suspense(ctx, caller_locations(1, 1).first) if ctx
+        content = capture do
+          yield
+          nil
+        end
+        "#{Markers.suspense_open(fallback, delay)}#{content}#{Markers::SUSPENSE_CLOSE}".html_safe
+      end
+
+      # Story 19-1 — a `<Suspense>` in an action that does not stream renders its
+      # content before the page is sent, as it always did. Development says so,
+      # once per response, with the line that makes the action stream.
+      def __ruact_note_unstreamed_suspense(ctx, location)
+        return unless defined?(Rails) && Rails.env.development?
+        return if ctx.unstreamed_suspense_noted?
+
+        ctx.note_unstreamed_suspense!
+
+        owner = respond_to?(:controller) ? controller : nil
+        return unless owner.respond_to?(:action_name) && owner.respond_to?(:logger)
+        # Declared, and answering a request it cannot stream to (HTTP/1.0).
+        return if owner.class.respond_to?(:ruact_streaming?) && owner.class.ruact_streaming?(owner.action_name)
+
+        where = location ? " (#{location.path.delete_prefix("#{Rails.root}/")}:#{location.lineno})" : ""
+        owner.logger&.warn(
+          "[ruact] #{owner.class.name}##{owner.action_name} renders a <Suspense>#{where} in an action " \
+          "that does not stream, so its content ran before the page was sent. To send the page first " \
+          "and the content when it is ready, add `ruact_streaming only: :#{owner.action_name}` to " \
+          "#{owner.class.name}."
+        )
+      end
+
+      private :__ruact_note_unstreamed_suspense
+    end
+  end
+end

data/lib/ruact/view_helper.rb

@@ -3,6 +3,7 @@
 require "erb"
 require "json"
 require "socket"
+require_relative "view_helper/suspense"
 
 module Ruact
   # ActionView helper module included in ActionView::Base via Railtie.
@@ -14,6 +15,9 @@ module Ruact
   # +@ruact_render_context+ and copied to the view by Rails's view_assigns
   # plumbing — see Story 7.9 / Bug 7.8-B) is per-request — no shared state.
   module ViewHelper
+    # `<Suspense>`: the content in place, or kept for after the shell.
+    include Suspense
+
     # Registers +name+ with +props+ in the per-render RenderContext (set by
     # Ruact::Controller#ruact_render on the controller as +@ruact_render_context+;
     # Rails copies it to the view via +_assigns_for_view_context+ because the
@@ -28,8 +32,7 @@ module Ruact
       ctx = @ruact_render_context
       raise Ruact::Error, __ruact_outside_render_message(name) if ctx.nil?
 
-      token = ctx.register(name, props)
-      "<!-- #{token} -->".html_safe
+      Markers.component(ctx.register(name, props)).html_safe
     end
 
     # Story 18-2 — the opening of a component with children. Registers it like
@@ -41,8 +44,7 @@ module Ruact
       ctx = @ruact_render_context
       raise Ruact::Error, __ruact_outside_render_message(name) if ctx.nil?
 
-      token = ctx.register(name, props)
-      %(<ruact-component data-ruact-token="#{token}">).html_safe
+      Markers.component_open(ctx.register(name, props)).html_safe
     end
 
     # Story 17.0i — a client component in a template Rails is rendering on its
@@ -228,31 +230,15 @@ module Ruact
 
     # The `__FLIGHT_DATA` inline bootstrap `<script>` — pushes the per-render
     # Flight payload onto the global queue the bootstrap entry drains on boot.
-    #
-    # The payload carries application data (props, record content), so it is
-    # embedded as a JSON string literal with `<`, `>`, `&`, U+2028 and U+2029
-    # escaped as `\uXXXX`. No byte of the payload can then close the `<script>`
-    # — `</SCRIPT>`, `</script >` and `<!--` included — and every character
-    # reaches JavaScript intact (a Ruby `String#inspect` literal did neither:
-    # it escaped only a lowercase `</script>`, and its `\e`-style escapes mean
-    # something else in JS).
-    SCRIPT_UNSAFE = /[<>&\u2028\u2029]/
-    private_constant :SCRIPT_UNSAFE
-
-    # A JSON string literal that is also safe inside a `<script>` element.
-    # The payload is UTF-8 by construction (the serializer normalizes every
-    # string); a binary-tagged buffer is retagged, not transcoded.
-    def __ruact_script_safe_json(string)
-      utf8 = string.encoding == Encoding::UTF_8 ? string : string.dup.force_encoding(Encoding::UTF_8)
-      JSON.generate(utf8).gsub(SCRIPT_UNSAFE) { |char| format("\\u%04x", char.ord) }
-    end
-
+    # The payload is written as {InlineScript.string_literal} writes it (a
+    # Ruby `String#inspect` literal, used before, escaped only a lowercase
+    # `</script>`, and its `\e`-style escapes mean something else in JS).
     def ruact_flight_data_script(flight_payload)
       <<~HTML.strip
         <script>
           (function() {
             var d = (self.__FLIGHT_DATA = self.__FLIGHT_DATA || []);
-            d.push(#{__ruact_script_safe_json(flight_payload)});
+            d.push(#{InlineScript.string_literal(flight_payload)});
           })();
         </script>
       HTML
@@ -262,32 +248,38 @@ module Ruact
     # the Vite dev server (with the react-refresh preamble + `@vite/client`);
     # prod reads the hashed URL from the Vite manifest. Both target the SAME
     # virtual entry id (`Ruact.bootstrap_virtual_id`) so dev/prod stay in lockstep.
+    #
+    # Story 19-1 — the entry is `async`: it runs as soon as it has loaded. A
+    # module script is otherwise deferred to the end of the document, and a
+    # page that streams ends after its last `<Suspense>` — its fallback would
+    # never show. The bootstrap then reads the rows the document pushes while
+    # it is still open.
     def ruact_vite_tags
       if Rails.env.development? && vite_dev_running?
         # @vitejs/plugin-react normally injects this preamble by processing index.html.
         # Since our HTML is generated by Rails (not Vite), we inject it manually.
         # Without it, every JSX file throws "can't detect preamble" at runtime.
+        # One async module, so the preamble still runs before any component
+        # module: it installs the preamble, then imports the client and the
+        # bootstrap, in that order.
         dev_server = Ruact.config.vite_dev_server.chomp("/")
-        react_preamble = <<~JS
-          <script type="module">
+        <<~HTML
+          <script type="module" async>
             import RefreshRuntime from '#{dev_server}/@react-refresh';
             RefreshRuntime.injectIntoGlobalHook(window);
             window.$RefreshReg$ = () => {};
             window.$RefreshSig$ = () => (type) => type;
             window.__vite_plugin_react_preamble_installed__ = true;
+            await import('#{dev_server}/@vite/client');
+            await import('#{ruact_bootstrap_dev_url}');
           </script>
-        JS
-
-        react_preamble + <<~HTML
-          <script type="module" src="#{dev_server}/@vite/client"></script>
-          <script type="module" src="#{ruact_bootstrap_dev_url}"></script>
         HTML
       else
         # Production: read the hashed URL from the Vite manifest, keyed on the
         # virtual entry id (the manifest key Vite emits for the virtual input).
         entry = vite_manifest_entry(Ruact.bootstrap_virtual_id)
         src   = entry ? "/assets/#{entry['file']}" : "/assets/application.js"
-        tag   = %(<script type="module" src="#{src}"></script>)
+        tag   = %(<script type="module" async src="#{src}"></script>)
         # Story 17-0k — in development with neither the Vite dev server nor a
         # build, that script 404s and the page stays empty with no error.
         Rails.env.development? && entry.nil? ? "#{ruact_vite_down_warning}\n#{tag}" : tag

data/lib/ruact.rb

@@ -10,12 +10,16 @@ require_relative "ruact/string_distance"
 require_relative "ruact/layout_source"
 require_relative "ruact/component_contract"
 require_relative "ruact/component_attributes"
+require_relative "ruact/markers"
+require_relative "ruact/request_kind"
+require_relative "ruact/inline_script"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"
 require_relative "ruact/html_converter"
 require_relative "ruact/client_manifest"
 require_relative "ruact/manifest_resolver"
 require_relative "ruact/render_pipeline"
+require_relative "ruact/deferred_render"
 require_relative "ruact/view_helper"
 require_relative "ruact/erb_preprocessor_hook"
 require_relative "ruact/server_functions"

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

@@ -56,15 +56,28 @@ describe("virtual:ruact/bootstrap — load (Story 14.2)", () => {
 
   it("imports the runtime modules via ABSOLUTE fs specifiers, not relative", () => {
     expect(src).toMatch(/from '\/.*\/runtime\/flight-modules\.js'/);
-    expect(src).toMatch(/import '\/.*\/runtime\/suspense-boundary\.js'/);
+    expect(src).toMatch(/from '\/.*\/runtime\/suspense-boundary\.js'/);
     expect(src).toMatch(/from '\/.*\/runtime\/ruact-router\.js'/);
-    // Story 18-1 — React's Flight client, through the plugin's virtual id.
-    expect(src).toContain("from 'virtual:ruact/flight-client'");
+    // The page is opened through page-stream.js, which reads React's Flight
+    // client through the plugin's virtual id (Story 18-1).
+    expect(src).toMatch(/from '\/.*\/runtime\/page-stream\.js'/);
     // No `\0virtual:`-unresolvable relative import survives.
     expect(src).not.toMatch(/(from|import)\s+['"]\.\/[\w.-]+\.js['"]/);
     expect(src).not.toMatch(/from\s+['"]\.\/ruact-router\.js['"]/);
   });
 
+  // Story 19-1 — the boundary handler is in place before the first render: a
+  // row that is already an error when the page mounts is caught during that
+  // first commit, before the router's effect runs.
+  it("installs the boundary error handler before it mounts, and mounts into the root once it exists", () => {
+    expect(src).toMatch(/from '\/.*\/runtime\/dev-overlay\.js'/);
+    expect(src.indexOf("setBoundaryErrorHandler((error)")).toBeGreaterThan(-1);
+    expect(src.indexOf("setBoundaryErrorHandler((error)")).toBeLessThan(src.indexOf("createRoot(container"));
+    expect(src).toContain("Promise.all([initialTree, whenRoot()])");
+    expect(src).toContain("openPage(documentRows(flightData))");
+    expect(src).toContain("setupRouter({ onNavigate: setCurrent, onBoundaryError })");
+  });
+
   it("contains no JSX syntax (loads via the default loader like the registry)", () => {
     expect(src).not.toContain("<App");
     expect(src).toContain("createElement(App)");

data/vendor/javascript/vite-plugin-ruact/page-mount.test.mjs

@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+//
+// Story 19-1 — the entry is `async`: it can run before the parser reaches the
+// page's `<div id="root">`, and a <Suspense> that failed on the server is shown
+// over the page in development.
+import { describe, it, expect } from "vitest";
+import { whenRoot } from "./runtime/page-stream.js";
+import { showDevOverlay } from "./runtime/dev-overlay.js";
+
+function loadingDocument() {
+  const doc = document.implementation.createHTMLDocument("page");
+  Object.defineProperty(doc, "readyState", { value: "loading", configurable: true });
+  return doc;
+}
+
+describe("whenRoot", () => {
+  it("gives the root at once when it is there", async () => {
+    const doc = document.implementation.createHTMLDocument("page");
+    doc.body.innerHTML = '<div id="root"></div>';
+    await expect(whenRoot(doc)).resolves.toBe(doc.getElementById("root"));
+  });
+
+  it("waits for a root the parser has not reached yet", async () => {
+    const doc = loadingDocument();
+    let found = null;
+    const waiting = whenRoot(doc).then((root) => { found = root; });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(found).toBeNull();
+
+    const root = doc.createElement("div");
+    root.id = "root";
+    doc.body.appendChild(root);
+    await waiting;
+    expect(found).toBe(root);
+  });
+
+  it("gives up with null when the document ends without one", async () => {
+    const doc = loadingDocument();
+    const waiting = whenRoot(doc);
+    doc.dispatchEvent(new Event("DOMContentLoaded"));
+    await expect(waiting).resolves.toBeNull();
+  });
+});
+
+describe("showDevOverlay", () => {
+  it("shows the server's error over the page, and closes on a click", () => {
+    const cause = new Error("ArgumentError: boom in a block");
+    cause.stack = "ArgumentError: boom in a block\n    at app/views/posts/show.html.erb:4";
+    showDevOverlay(new Error("[ruact] Server error: ArgumentError: boom in a block", { cause }));
+
+    const overlay = document.getElementById("ruact-dev-overlay");
+    expect(overlay.querySelector("[data-overlay-message]").textContent).toBe("ArgumentError: boom in a block");
+    expect(overlay.querySelector("[data-overlay-stack]").textContent).toContain("show.html.erb:4");
+
+    overlay.click();
+    expect(document.getElementById("ruact-dev-overlay")).toBeNull();
+  });
+
+  it("shows the latest failure in the one overlay", () => {
+    showDevOverlay(new Error("first"));
+    showDevOverlay(new Error("second"));
+    const overlays = document.querySelectorAll("#ruact-dev-overlay");
+    expect(overlays).toHaveLength(1);
+    expect(overlays[0].querySelector("[data-overlay-message]").textContent).toBe("second");
+    overlays[0].click();
+  });
+});

data/vendor/javascript/vite-plugin-ruact/page-stream.test.mjs

@@ -0,0 +1,107 @@
+// The two ways a page is opened read the same way: the rows a document inlined
+// in `__FLIGHT_DATA`, and a fetch body that may end early.
+import { describe, it, expect } from "vitest";
+import { documentRows, openPage } from "./runtime/page-stream.js";
+
+const encoder = new TextEncoder();
+
+function bodyOf(chunks, { error } = {}) {
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+      if (error) controller.error(error);
+      else controller.close();
+    },
+  });
+}
+
+describe("openPage", () => {
+  it("opens the rows a document inlined, joined in the order they were pushed", async () => {
+    const page = openPage(documentRows(['1:"wor', 'ld"\n0:["hello","$1"]\n'], { readyState: "complete" }));
+    expect(await page.root).toEqual(["hello", "world"]);
+    await expect(page.end).resolves.toBeUndefined();
+  });
+
+  it("resolves the root at row 0, before a deferred row has arrived", async () => {
+    let push;
+    const body = new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode('0:{"later":"$@1"}\n'));
+        push = (row) => {
+          controller.enqueue(encoder.encode(row));
+          controller.close();
+        };
+      },
+    });
+    const page = openPage(body);
+    const root = await page.root;
+    expect(root.later).toBeInstanceOf(Promise);
+
+    push('1:"arrived"\n');
+    await expect(root.later).resolves.toBe("arrived");
+    await expect(page.end).resolves.toBeUndefined();
+  });
+
+  it("labels a body that ends before the root as the transport's failure, and rejects the end", async () => {
+    const page = openPage(bodyOf([], { error: new TypeError("network down") }));
+    await expect(page.root).rejects.toMatchObject({ digest: "ruact:connection-closed" });
+    await expect(page.end).rejects.toThrow("network down");
+  });
+});
+
+// Story 19-1 — a page that streams: the document is still open when the
+// bootstrap runs, and pushes each <Suspense>'s rows as they are ready.
+describe("documentRows", () => {
+  function openDocument() {
+    const listeners = {};
+    return {
+      readyState: "loading",
+      addEventListener(type, listener) { listeners[type] = listener; },
+      finish() {
+        this.readyState = "interactive";
+        listeners.DOMContentLoaded?.();
+      },
+    };
+  }
+
+  it("reads what the queue holds, then each row pushed later, until the document ends", async () => {
+    const doc = openDocument();
+    const queue = ['0:{"later":"$@1"}\n'];
+    const page = openPage(documentRows(queue, doc));
+    const root = await page.root;
+    expect(root.later).toBeInstanceOf(Promise);
+
+    queue.push('1:"arrived"\n');
+    await expect(root.later).resolves.toBe("arrived");
+    expect(queue).toHaveLength(0);
+
+    doc.finish();
+    await expect(page.end).resolves.toBeUndefined();
+  });
+
+  it("keeps the stream open while the document loads, and closes it when the document ends", async () => {
+    const doc = openDocument();
+    const stream = documentRows(['0:"shell"\n'], doc);
+    const reader = stream.getReader();
+    await reader.read();
+    let closed = false;
+    const next = reader.read().then((result) => { closed = result.done; });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(closed).toBe(false);
+    doc.finish();
+    await next;
+    expect(closed).toBe(true);
+  });
+
+  it("closes at once when the document has already ended", async () => {
+    const reader = documentRows(['0:"x"\n'], { readyState: "complete" }).getReader();
+    await reader.read();
+    await expect(reader.read()).resolves.toMatchObject({ done: true });
+  });
+
+  it("ignores a row pushed after the document ended instead of throwing", () => {
+    const queue = [];
+    documentRows(queue, { readyState: "complete" });
+    expect(() => queue.push('9:"late"\n')).not.toThrow();
+  });
+});

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

@@ -18,15 +18,16 @@
 //     transforming a `\0virtual:` id.
 import { createRoot } from 'react-dom/client';
 import { createElement, useState, useEffect } from 'react';
-// Story 18-1 — React's own Flight client: the copy vendored in the gem, or the
-// app's `react-server-dom-webpack` when installed (the plugin decides).
-import { createFromReadableStream } from 'virtual:ruact/flight-client';
 import { setModuleRegistry } from './flight-modules.js';
 // Registers the boundary the server wraps each Suspense child in.
-import './suspense-boundary.js';
+import { setBoundaryErrorHandler } from './suspense-boundary.js';
 import { RootBoundary, onCaughtError } from './root-boundary.js';
-import { labelledStream } from './transport.js';
+// The page, opened from its Flight bytes with React's own Flight client (the
+// copy vendored in the gem, or the app's `react-server-dom-webpack` when it
+// declares one: the plugin decides).
+import { documentRows, openPage, whenRoot } from './page-stream.js';
 import { setupRouter, teardownRouter } from './ruact-router.js';
+import { showDevOverlay } from './dev-overlay.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
@@ -56,31 +57,35 @@ if (!flightData || flightData.length === 0) {
     root.textContent = '[ruact] No Flight data found — is the Rails server running?';
   }
 } else {
-  // The inline payload, as the stream the client reads. The root is mounted
-  // once the tree resolves, so the first paint is the page, not a fallback.
-  const bytes = new TextEncoder().encode(flightData.join(''));
-  const stream = new ReadableStream({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
+  // Story 19-1 — in development a <Suspense> that failed on the server is shown
+  // over the page. The handler is in place before anything renders: a row that
+  // is already an error when the page mounts is caught during that first
+  // commit, before the router's effect would install one.
+  const onBoundaryError = import.meta.env?.DEV ? (error) => showDevOverlay(error) : null;
+  setBoundaryErrorHandler((error) => {
+    console.error(error.message);
+    onBoundaryError?.(error);
   });
 
+  // The document's rows, as the stream the client reads — open while the
+  // document is: a page that streams pushes each <Suspense>'s rows as they are
+  // ready. The root is mounted once the tree resolves, so the first paint is
+  // the page with its fallbacks.
   let initialTree;
   try {
-    initialTree = createFromReadableStream(labelledStream(stream));
+    initialTree = openPage(documentRows(flightData)).root;
   } catch (err) {
     showBootError(err);
     throw err;
   }
 
-  initialTree.then(
-    (tree) => {
+  Promise.all([initialTree, whenRoot()]).then(
+    ([tree, container]) => {
       function App() {
         const [current, setCurrent] = useState(() => tree);
 
         useEffect(() => {
-          setupRouter({ onNavigate: setCurrent });
+          setupRouter({ onNavigate: setCurrent, onBoundaryError });
           return () => teardownRouter();
         }, []);
 
@@ -88,7 +93,7 @@ if (!flightData || flightData.length === 0) {
         return createElement(RootBoundary, { tree: current }, current);
       }
 
-      createRoot(document.getElementById('root'), { onCaughtError }).render(createElement(App));
+      createRoot(container, { onCaughtError }).render(createElement(App));
     },
     (err) => {
       showBootError(err);

data/vendor/javascript/vite-plugin-ruact/runtime/dev-overlay.js

@@ -0,0 +1,39 @@
+// Story 19-1 (ADR D5) — in development, a `<Suspense>` whose content failed on
+// the server is shown over the page: what failed, and where in the templates.
+// Production shows nothing of the error; the boundary keeps its fallback.
+//
+// The boundary hands the error to the handler ./suspense-boundary.js was given
+// (the bootstrap installs one before the first render, the router keeps it).
+// React's development client rebuilds the server's backtrace into the error's
+// `stack`.
+
+const OVERLAY_ID = "ruact-dev-overlay";
+
+/** Shows +error+ over the page; a click closes it. */
+export function showDevOverlay(error, doc = globalThis.document) {
+  const cause = error?.cause ?? error;
+  let overlay = doc.getElementById(OVERLAY_ID);
+  if (!overlay) {
+    overlay = doc.createElement("div");
+    overlay.id = OVERLAY_ID;
+    overlay.setAttribute("role", "alertdialog");
+    overlay.setAttribute("aria-label", "A <Suspense> failed on the server");
+    overlay.style.cssText =
+      "position:fixed;inset:0;z-index:2147483647;background:rgba(24,6,6,.94);color:#fff;" +
+      "font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;padding:32px;overflow:auto;" +
+      "white-space:pre-wrap;cursor:pointer";
+    overlay.addEventListener("click", () => overlay.remove());
+    (doc.body ?? doc.documentElement).appendChild(overlay);
+  }
+  const title = doc.createElement("h2");
+  title.textContent = "[ruact] A <Suspense> failed on the server";
+  const message = doc.createElement("p");
+  message.dataset.overlayMessage = "";
+  message.textContent = cause?.message ?? String(cause);
+  const stack = doc.createElement("pre");
+  stack.dataset.overlayStack = "";
+  stack.textContent = cause?.stack ?? "";
+  const hint = doc.createElement("p");
+  hint.textContent = "Development only. Click to close.";
+  overlay.replaceChildren(title, message, stack, hint);
+}

data/vendor/javascript/vite-plugin-ruact/runtime/page-stream.js

@@ -0,0 +1,88 @@
+// How a page is opened from its Flight bytes, wherever they come from: the
+// rows the document pushes onto `__FLIGHT_DATA` (the first load) or the body of
+// the router's fetch (a navigation, a form, revalidate()).
+//
+// The bytes go to React's Flight client through ./transport.js, so a response
+// cut short reaches the Suspense boundaries labelled, and a second reader
+// settles when the last byte is in.
+import { createFromReadableStream } from "virtual:ruact/flight-client";
+import { labelledStream } from "./transport.js";
+
+/**
+ * The rows the document pushes onto `__FLIGHT_DATA`, as a byte stream that
+ * stays open while the document does (Story 19-1): the rows already in the
+ * queue, then each one pushed later — a page that streams pushes one script per
+ * `<Suspense>` — until the document has finished loading. A row pushed before
+ * this runs is in the queue, and read first.
+ */
+export function documentRows(queue, doc = globalThis.document) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      let open = true;
+      const read = (row) => controller.enqueue(encoder.encode(row));
+      queue.forEach(read);
+      queue.length = 0;
+      queue.push = (...rows) => {
+        if (open) rows.forEach(read);
+        return 0;
+      };
+      const close = () => {
+        open = false;
+        controller.close();
+      };
+      if (doc?.readyState === "loading") {
+        doc.addEventListener("DOMContentLoaded", close, { once: true });
+      } else {
+        close();
+      }
+    },
+  });
+}
+
+/**
+ * The element the page mounts into. The entry is `async` and may run before
+ * the parser reaches `<div id="root">` — a layout that puts `ruact_js_assets`
+ * above it — so this waits for it, and gives up (null) when the document ends
+ * without one.
+ */
+export function whenRoot(doc = globalThis.document) {
+  const found = doc.getElementById("root");
+  if (found || doc.readyState !== "loading") return Promise.resolve(found);
+  return new Promise((resolve) => {
+    const observer = new MutationObserver(() => {
+      const root = doc.getElementById("root");
+      if (root) finish(root);
+    });
+    const finish = (root) => {
+      observer.disconnect();
+      doc.removeEventListener("DOMContentLoaded", atEnd);
+      resolve(root);
+    };
+    const atEnd = () => finish(doc.getElementById("root"));
+    observer.observe(doc.documentElement, { childList: true, subtree: true });
+    doc.addEventListener("DOMContentLoaded", atEnd);
+  });
+}
+
+/**
+ * Opens a page from a byte stream.
+ *
+ * `root` resolves with the tree as soon as row 0 has arrived; deferred Suspense
+ * rows keep streaming into it. A stream that ends without a root rejects it
+ * (./transport.js labels the failure). `end` settles when the last byte is in,
+ * and rejects with the stream's error; it never goes unhandled on its own.
+ */
+export function openPage(body) {
+  const [forClient, forEnd] = body.tee();
+  const end = drain(forEnd);
+  end.catch(() => {});
+  // React's client returns a thenable; a Promise is what callers can await,
+  // chain and assert on.
+  return { root: Promise.resolve(createFromReadableStream(labelledStream(forClient))), end };
+}
+
+async function drain(stream) {
+  const reader = stream.getReader();
+  while (!(await reader.read()).done) { /* the client has its own copy */ }
+}