ruact 0.0.14 → 0.0.16

data/lib/ruact/flight/utf8.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Flight
+    # Every string leaves the serializer as valid UTF-8. A `T` row is framed by
+    # its byte length, and JSON (a model row, the inline page payload) refuses
+    # invalid UTF-8: one record holding Latin-1 bytes made its page answer 500
+    # for every viewer.
+    module Utf8
+      REPLACEMENT = "\uFFFD"
+
+      # Binary-tagged text (`File.binread`, an HTTP body) is retagged; another
+      # encoding is transcoded; bytes that are not text in that encoding become
+      # U+FFFD, as a browser shows them.
+      #
+      # @param value [String]
+      # @return [String] valid UTF-8 (the same object when it already was)
+      def self.text(value)
+        return value if value.encoding == Encoding::UTF_8 && value.valid_encoding?
+
+        text =
+          begin
+            if [Encoding::BINARY, Encoding::UTF_8].include?(value.encoding)
+              value.dup.force_encoding(Encoding::UTF_8)
+            else
+              value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT)
+            end
+          rescue Encoding::ConverterNotFoundError
+            # An encoding Ruby cannot convert from (UTF-7, say): its bytes.
+            value.dup.force_encoding(Encoding::UTF_8)
+          end
+        text.valid_encoding? ? text : text.scrub(REPLACEMENT)
+      end
+    end
+  end
+end

data/lib/ruact/flight.rb

@@ -3,6 +3,8 @@
 require_relative "flight/react_element"
 require_relative "flight/request"
 require_relative "flight/row_emitter"
+require_relative "flight/js_date"
+require_relative "flight/utf8"
 require_relative "flight/serializer"
 require_relative "flight/renderer"
 

data/lib/ruact/redirect_path.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Reducing a same-origin redirect URL to its path is what lets the client
+  # navigate in place. One path must not be produced that way: `//host` (or
+  # `/\host`), which a browser reads as a URL to ANOTHER host. Shared by the
+  # page redirect ({Ruact::Controller}) and the server-function `$redirect`
+  # ({Ruact::Server}); neither loads the other.
+  module RedirectPath
+    # @param path [String] a redirect target already reduced to a path
+    # @return [Boolean] whether a browser would read it as another host
+    def self.protocol_relative?(path)
+      path.match?(%r{\A[/\\]{2}})
+    end
+  end
+end

data/lib/ruact/server.rb

@@ -14,6 +14,8 @@ require_relative "../ruact"
 require_relative "server_functions/error_rendering"
 require_relative "server_functions/bucket_two_payload"
 require_relative "server_functions/name_bridge"
+require_relative "server_functions/action_assigns"
+require_relative "redirect_path"
 require_relative "validation_errors_collector"
 
 module Ruact
@@ -68,6 +70,9 @@ module Ruact
   module Server
     extend ActiveSupport::Concern
 
+    # A function call returns the action's own ivars, not its callbacks'.
+    include Ruact::ServerFunctions::ActionAssigns
+
     include Ruact::ServerFunctions::ErrorRendering
     include Ruact::ValidationErrorsCollector
 
@@ -201,16 +206,16 @@ module Ruact
     # Story 9.2 AC2/AC4 (D1) — Bucket-2 success-path negotiation. When the
     # action finished without an explicit render on a function-call request
     # ({#__ruact_function_call?} — `Accept: application/json`, non-GET), serialize
-    # the action's exposed instance variables (Rails `view_assigns`, verbatim —
-    # the same set a view would see) as a JSON object keyed by ivar name, or
+    # the instance variables the ACTION assigned (Rails `view_assigns` minus
+    # what callbacks set and the action left alone — see
+    # {Ruact::ServerFunctions::ActionAssigns}) as a JSON object keyed by ivar name, or
     # `204 No Content` when none were set. Any other request shape falls through
     # to `super` so Bucket-1 rendering — the host's `Ruact::Controller` Flight
     # re-render, then Rails — is byte-for-byte unchanged (AC1).
     #
-    # The exposed-ivar set is Rails' own `view_assigns` with no custom filtering:
-    # Rails already excludes its protected `@_`-prefixed internals (including the
-    # CSRF `@_marked_for_same_origin_verification` flag), so what remains is
-    # exactly what the action assigned. Each value is serialized through the
+    # Rails' `view_assigns` already excludes its protected `@_`-prefixed
+    # internals (including the CSRF `@_marked_for_same_origin_verification`
+    # flag); ActionAssigns then drops what callbacks set. Each value is serialized through the
     # `ruact_props` / `Ruact::Serializable` / `strict_serialization` rules
     # ({Ruact::ServerFunctions::BucketTwoPayload}); a single ivar stays keyed
     # (no magic unwrap).
@@ -221,7 +226,7 @@ module Ruact
       # dev `@errors`) are dropped from the serialized assigns; Rails' own
       # `view_assigns` only filters a fixed set of `@_` ivars, not every `@__`
       # one (see {Ruact::ValidationErrorsCollector::RESERVED_ASSIGN_KEYS}).
-      assigns = view_assigns.except(*ValidationErrorsCollector::RESERVED_ASSIGN_KEYS)
+      assigns = __ruact_action_assigns(view_assigns.except(*ValidationErrorsCollector::RESERVED_ASSIGN_KEYS))
 
       # Story 15.0 (F6) — reaching this branch means ruact itself is producing
       # the function-call response (fall-through: injection, plain JSON, or
@@ -327,6 +332,11 @@ module Ruact
       path = uri.path.nil? || uri.path.empty? ? "/" : uri.path
       path += "?#{uri.query}" if uri.query
       path += "##{uri.fragment}" if uri.fragment
+      # `https://app//evil.com` is same-origin, and Rails lets it through; as a
+      # path, `//evil.com` is a protocol-relative URL to ANOTHER host. Keep
+      # the absolute URL for any path a browser would read that way.
+      return url if Ruact::RedirectPath.protocol_relative?(path)
+
       path
     rescue ::URI::InvalidURIError
       url

data/lib/ruact/server_functions/action_assigns.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # What a server function's JSON is made of (decision, 2026-10-03): the
+    # ivars the ACTION assigned, not everything a view would see.
+    #
+    # Two filters. Callbacks run before `send_action`, so what they put on the
+    # controller (a `set_post`, a `set_current_user`) is recorded there and
+    # left out of the JSON unless the action assigns it again. And some ivars
+    # are filled DURING the action without the action naming them — Devise's
+    # `current_user` memoizes `@current_user` on first call, Pundit's
+    # `authorize` sets `@pundit` — so names in
+    # `Ruact.config.server_function_hidden_ivars`, and every name starting
+    # with `_`, are never returned. Without these, a function call carried the
+    # signed-in user, and under `strict_serialization` (production's default)
+    # a user model without `ruact_props` made every call a 500. A page
+    # render's view still sees every ivar; only the function-call JSON
+    # narrows.
+    module ActionAssigns
+      # The snapshot's own name, kept out of what it filters.
+      CALLBACK_IVARS_KEY = "__ruact_callback_ivars"
+
+      private
+
+      def send_action(...)
+        if __ruact_function_call?
+          @__ruact_callback_ivars = instance_variables.to_h do |name|
+            [name.to_s.delete_prefix("@"), instance_variable_get(name)]
+          end
+        end
+        super
+      end
+
+      # +assigns+ minus what callbacks set and the action left holding the
+      # same object. Only a DIFFERENT object makes it the action's: setting
+      # the same value again (`@ok = false` after a callback did, a memoized
+      # helper returning what the callback already stored) leaves it out.
+      # Security first — a callback's `@current_user_id = 5` must not ride
+      # every response — at the price of a key that is absent when callback
+      # and action happen to agree.
+      def __ruact_action_assigns(assigns)
+        before = @__ruact_callback_ivars || {}
+        hidden = Ruact.config.server_function_hidden_ivars
+        assigns.reject do |name, value|
+          name == CALLBACK_IVARS_KEY || name.start_with?("_") || hidden.include?(name) ||
+            (before.key?(name) && before[name].equal?(value))
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/bucket_two_payload.rb

@@ -7,7 +7,7 @@ require_relative "../errors"
 module Ruact
   module ServerFunctions
     # Story 9.2 — pure serializer for the Bucket-2 (imperative `await fn()`)
-    # response body. Takes the host action's exposed instance variables (Rails
+    # response body. Takes the instance variables the action returns (Rails
     # `view_assigns`, resolved by the caller) and produces a JSON-ready Ruby
     # Hash, keyed by ivar name, applying the SAME prop-exposure policy as the
     # Flight serializer ({Ruact::Flight::Serializer#serialize_unknown}):

data/lib/ruact/testing/component_query.rb

@@ -26,10 +26,14 @@ module Ruact
       ELEMENT_HEAD = "$"
       # A client-component element's type is "$L" followed by the import's hex id.
       CLIENT_REF = /\A\$L(?<hex>\h+)\z/
+      # A string of 1024+ bytes travels as a `T` row, and the props hold a
+      # `"$T<hex>"` reference to it (Story 17-0d).
+      TEXT_REF = /\A\$T(?<hex>\h+)\z/
 
       # @param wire [String] the raw Flight wire byte string.
       def initialize(wire)
         @rows = FlightWireParser.parse(wire)
+        @texts = index_texts(@rows)
         @imports = index_imports(@rows)
         @instances = collect_instances(@rows)
       end
@@ -74,6 +78,24 @@ module Ruact
         end
       end
 
+      def index_texts(rows)
+        rows.each_with_object({}) do |row, acc|
+          acc[row[:id]] = row[:payload].dup.force_encoding(Encoding::UTF_8) if row[:class] == :text
+        end
+      end
+
+      # Props as the component receives them: text references resolved.
+      def resolve_texts(node)
+        case node
+        when String
+          ref = node.match(TEXT_REF)
+          ref && @texts.key?(ref[:hex].to_i(16)) ? @texts[ref[:hex].to_i(16)] : node
+        when Array then node.map { |child| resolve_texts(child) }
+        when Hash then node.transform_values { |child| resolve_texts(child) }
+        else node
+        end
+      end
+
       def import_ids_for(name)
         @imports.select do |_id, meta|
           meta[:export_name] == name || meta[:basename] == name
@@ -95,7 +117,7 @@ module Ruact
       def walk(node, instances)
         if element?(node)
           ref = node[1].match(CLIENT_REF)
-          instances << { ref_id: ref[:hex].to_i(16), props: node[3] } if ref
+          instances << { ref_id: ref[:hex].to_i(16), props: resolve_texts(node[3]) } if ref
           # An element's props/children may themselves contain nested elements.
           walk(node[3], instances)
         elsif node.is_a?(Array)

data/lib/ruact/testing/flight_extractor.rb

@@ -133,7 +133,12 @@ module Ruact
                   "This response did not render a ruact component (no Flight data was inlined)."
           end
 
-          decode_ruby_string_literal(match[:literal])
+          literal = match[:literal]
+          # The literal is JSON (ruact >= 0.0.15). The Ruby-literal decoder stays
+          # for documents captured from earlier versions.
+          JSON.parse(literal)
+        rescue JSON::ParserError
+          decode_ruby_string_literal(literal)
         end
 
         def json_body?(body)

data/lib/ruact/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruact
-  VERSION = "0.0.14"
+  VERSION = "0.0.16"
 end

data/lib/ruact/view_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "erb"
 require "json"
 require "socket"
 
@@ -214,15 +215,31 @@ module Ruact
 
     # The `__FLIGHT_DATA` inline bootstrap `<script>` — pushes the per-render
     # Flight payload onto the global queue the bootstrap entry drains on boot.
-    # `</script>` in the payload is escaped to prevent an HTML/XSS breakout
-    # (mandatory whenever Flight data is inlined into a `<script>` tag).
+    #
+    # 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
+
     def ruact_flight_data_script(flight_payload)
-      escaped_payload = flight_payload.gsub("</script>", '<\/script>')
       <<~HTML.strip
         <script>
           (function() {
             var d = (self.__FLIGHT_DATA = self.__FLIGHT_DATA || []);
-            d.push(#{escaped_payload.inspect});
+            d.push(#{__ruact_script_safe_json(flight_payload)});
           })();
         </script>
       HTML
@@ -257,10 +274,31 @@ module Ruact
         # 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"
-        %(<script type="module" src="#{src}"></script>)
+        tag   = %(<script type="module" 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
       end
     end
 
+    # Story 17-0k — `bin/rails server` on its own, once Vite has run before:
+    # the component manifest is on disk, so the render succeeds, but the page's
+    # JavaScript is not served and `#root` stays empty — a blank 200 whose only
+    # clue was a 404 in the network tab. Development only. Plain HTML with
+    # inline style: the warning cannot depend on the bundle that did not load.
+    def ruact_vite_down_warning
+      server = Ruact.config.vite_dev_server.chomp("/")
+      message = "The Vite dev server is not running (#{server}), so this page has no JavaScript " \
+                "and its React components cannot render. Start the app with bin/dev, which runs " \
+                "Rails and Vite together."
+      Rails.logger&.warn("[ruact] #{message}")
+      <<~HTML.strip
+        <div role="alert" data-ruact-vite-down style="position:fixed;inset:0 0 auto 0;z-index:2147483647;padding:12px 16px;background:#7f1d1d;color:#fff;font:14px/1.4 system-ui,sans-serif">
+          <strong>[ruact]</strong> #{ERB::Util.html_escape(message)}
+        </div>
+      HTML
+    end
+
     # The Vite dev-server URL for the virtual bootstrap. Vite serves virtual
     # modules under `/@id/`, encoding the resolved id's leading NUL (`\0`) as
     # `__x00__` — so `\0virtual:ruact/bootstrap` is served at

data/lib/ruact.rb

@@ -9,6 +9,7 @@ require_relative "ruact/flight"
 require_relative "ruact/string_distance"
 require_relative "ruact/layout_source"
 require_relative "ruact/component_contract"
+require_relative "ruact/component_attributes"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"
 require_relative "ruact/html_converter"

data/vendor/javascript/ruact-server-functions-runtime/index.js

@@ -270,6 +270,16 @@ let inflightQueries = new WeakMap();
 // is still invoked and the error surfaces (Story 9.5 behavior), instead of an
 // invalid call wrongly joining an in-flight no-param request. `null`/no params
 // both serialize to "".
+// Story 17-0c — a query param as it goes on the wire, or `undefined` when it
+// cannot be one. Pages now hand components a `BigInt` (an id beyond JS's safe
+// range) and a `Date` (a Ruby Time); both must be able to go back as params.
+function wireParam(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  return undefined;
+}
+
 function canonicalParamsKey(params) {
   if (params == null) return "";
   if (typeof params !== "object" || Array.isArray(params)) return null;
@@ -279,8 +289,8 @@ function canonicalParamsKey(params) {
     if (value === undefined) continue;
     if (value === null) {
       tokens.push(encodeURIComponent(key)); // bare key — mirrors buildQueryUrl
-    } else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-      tokens.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    } else if (wireParam(value) !== undefined) {
+      tokens.push(`${encodeURIComponent(key)}=${encodeURIComponent(wireParam(value))}`);
     } else {
       return null; // array/object value — buildQueryUrl throws; non-shareable
     }
@@ -536,16 +546,12 @@ function buildQueryUrl(path, params) {
     if (value === undefined) continue;
     if (value === null) {
       bareKeys.push(encodeURIComponent(key));
-    } else if (
-      typeof value === "string" ||
-      typeof value === "number" ||
-      typeof value === "boolean"
-    ) {
-      search.append(key, String(value));
+    } else if (wireParam(value) !== undefined) {
+      search.append(key, wireParam(value));
     } else {
       throw new TypeError(
         `ruact useQuery for ${path}: param "${key}" must be a string, number, ` +
-          "boolean, or null — arrays and objects are rejected",
+          "bigint, Date, boolean, or null — arrays and objects are rejected",
       );
     }
   }
@@ -684,7 +690,10 @@ function buildFetchInit(args, method = "POST") {
     body = args;
   } else {
     headers["Content-Type"] = "application/json";
-    body = JSON.stringify(args ?? {});
+    // A BigInt (an id beyond JS's safe range, Story 17-0c) has no JSON form:
+    // it goes as its decimal string, which Rails reads as it reads any id.
+    // A Date already serializes to its ISO string.
+    body = JSON.stringify(args ?? {}, (_key, value) => (typeof value === "bigint" ? value.toString() : value));
   }
 
   return {

data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs

@@ -491,6 +491,13 @@ describe("mutation core — configureRuactRuntime", () => {
 });
 
 describe("Story 8.1 — __internals (test-only surface)", () => {
+  // Story 17-0c — a BigInt id from a page has no JSON form; it goes as its
+  // decimal string instead of throwing.
+  it("sends a BigInt argument as its decimal string", () => {
+    const init = __internals.buildFetchInit({ id: 9007199254740993n, at: new Date("2026-09-08T00:00:00.000Z") });
+    expect(JSON.parse(init.body)).toEqual({ id: "9007199254740993", at: "2026-09-08T00:00:00.000Z" });
+  });
+
   it("exposes buildFetchInit, resolveCsrfToken, parseResponse for granular asserts", () => {
     expect(typeof __internals.buildFetchInit).toBe("function");
     expect(typeof __internals.resolveCsrfToken).toBe("function");

data/vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs

@@ -203,6 +203,18 @@ describe("Story 9.5 — _makeQuery / buildQueryUrl wire format (FR88)", () => {
     expect(() => buildQueryUrl("/q/search", { q: { deep: 1 } })).toThrow(/arrays and objects are rejected/);
   });
 
+  // Story 17-0c — pages now hand components BigInt ids and Date values; they
+  // must be able to go back as query params.
+  it("sends a BigInt as its decimal string and a Date as its ISO string", () => {
+    expect(buildQueryUrl("/q/search", { id: 9007199254740993n })).toBe("/q/search?id=9007199254740993");
+    expect(buildQueryUrl("/q/search", { at: new Date("2026-09-08T12:30:45.123Z") }))
+      .toBe("/q/search?at=2026-09-08T12%3A30%3A45.123Z");
+  });
+
+  it("rejects an Invalid Date rather than sending 'Invalid Date'", () => {
+    expect(() => buildQueryUrl("/q/search", { at: new Date("nope") })).toThrow(/arrays and objects are rejected/);
+  });
+
   it("rejects a top-level array of params", () => {
     expect(() => buildQueryUrl("/q/search", [1, 2])).toThrow(/plain object/);
   });

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

@@ -31,11 +31,13 @@
 // against shuffling being turned on later.
 
 import { describe, it, expect, beforeEach } from "vitest";
+import { Fragment } from "react";
 import fs from "node:fs";
 import path from "node:path";
 import {
   buildTree,
   createFromFlightPayload,
+  createRowParser,
   clearPendingChunks,
 } from "./runtime/flight-client.js";
 
@@ -319,3 +321,179 @@ describe("Story 17.0a — the contract, driven by a gem-produced fixture", () =>
     expect(tree.props.posts).toEqual([{ id: 1, title: "$5 plan" }]);
   });
 });
+
+// Story 17-0d — every string of 1024+ bytes travels as a `T` row framed by its
+// BYTE length, with no trailing newline. The decoder split on "\n" and so lost
+// the root row: one long post body blanked the whole page. The fixtures are
+// what the Ruby serializer emits (spec/ruact/flight/text_framing_fixtures_spec.rb
+// writes and guards them).
+describe("text rows (Story 17-0d)", () => {
+  const FIXTURES = path.join(import.meta.dirname, "../../../spec/fixtures/flight");
+  const read = (name) => fs.readFileSync(path.join(FIXTURES, name));
+  const expected = JSON.parse(read("text_framing_expected.json").toString("utf8"));
+
+  const rowsOf = (chunks) => {
+    const rows = new Map();
+    const parser = createRowParser(({ id, row }) => rows.set(id, row));
+    for (const chunk of chunks) parser.push(chunk);
+    parser.end();
+    return rows;
+  };
+
+  it("decodes every value the serializer framed, byte for byte", () => {
+    const tree = createFromFlightPayload(read("text_framing.txt").toString("utf8"), MODULE_REGISTRY);
+    expect(tree).toEqual(expected);
+  });
+
+  it("puts long text inside Suspense content where the deferred row points", () => {
+    const tree = createFromFlightPayload(read("text_framing_suspense.txt").toString("utf8"), MODULE_REGISTRY);
+    const deferred = tree.props.children.type; // the already-arrived deferred row, wrapped
+    expect(deferred().props.children).toBe(expected.multibyte);
+  });
+
+  it("does not depend on where the network splits the bytes", () => {
+    const bytes = new Uint8Array(read("text_framing.txt"));
+    const whole = rowsOf([bytes]);
+
+    // Every single split point: inside ids, `T` lengths, text bodies and
+    // multibyte code points, and between rows.
+    for (let cut = 1; cut < bytes.length; cut += 1) {
+      const split = rowsOf([bytes.subarray(0, cut), bytes.subarray(cut)]);
+      expect(split).toEqual(whole);
+    }
+
+    // And one byte at a time.
+    expect(rowsOf([...bytes].map((b) => Uint8Array.of(b)))).toEqual(whole);
+  });
+
+  it("refuses a truncated text row instead of rendering part of the page", () => {
+    const bytes = new Uint8Array(read("text_framing.txt"));
+    const firstText = Buffer.from(bytes).indexOf(":T") + 10;
+    expect(() => rowsOf([bytes.subarray(0, firstText)])).toThrow(/Truncated Flight payload/);
+  });
+
+  it("refuses a malformed text length", () => {
+    const enc = new TextEncoder();
+    expect(() => rowsOf([enc.encode("1:Tzz,abc0:\"$T1\"\n")])).toThrow(/Malformed text row length/);
+  });
+
+  it("names a text reference whose row never arrived", () => {
+    expect(() => createFromFlightPayload('0:{"body":"$T7"}\n', MODULE_REGISTRY))
+      .toThrow(/Text row 7 is referenced but was never received/);
+  });
+
+  it("skips a stray line without a colon instead of losing the row after it", () => {
+    const rows = rowsOf([new TextEncoder().encode('garbage\n0:{"a":1}\n')]);
+    expect(rows.get(0)).toEqual({ kind: "model", value: { a: 1 } });
+  });
+
+  it("reads a large row arriving in small chunks in linear time", () => {
+    const big = JSON.stringify({ items: Array.from({ length: 60000 }, (_, i) => ({ id: i, name: `item ${i}` })) });
+    const bytes = new TextEncoder().encode(`0:${big}\n`);
+    const chunks = [];
+    for (let i = 0; i < bytes.length; i += 4096) chunks.push(bytes.subarray(i, i + 4096));
+    const started = performance.now();
+    const rows = rowsOf(chunks);
+    expect(rows.get(0).value.items).toHaveLength(60000);
+    // ~2.3 MB in 4 KB chunks; quadratic re-copying took seconds.
+    expect(performance.now() - started).toBeLessThan(1000);
+  });
+
+  it("still reads a last row that lost its trailing newline", () => {
+    const rows = rowsOf([new TextEncoder().encode('0:{"a":1}')]);
+    expect(rows.get(0)).toEqual({ kind: "model", value: { a: 1 } });
+  });
+});
+
+// Story 17-0c — the serializer emits Ruby Time/DateTime as "$D<ISO>" and
+// integers beyond ±(2^53 − 1) as "$n<decimal>". Components got the marker
+// strings. The fixture is the Ruby serializer's own output
+// (spec/ruact/flight/scalar_fixtures_spec.rb writes and guards it).
+describe("dates and big integers (Story 17-0c)", () => {
+  const FIXTURES = path.join(import.meta.dirname, "../../../spec/fixtures/flight");
+  const payload = fs.readFileSync(path.join(FIXTURES, "scalar_round_trip.txt"), "utf8");
+  const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, "scalar_round_trip_expected.json"), "utf8"));
+
+  // 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", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    expect(tree).toEqual(revive(expected));
+  });
+
+  it("gives a Date the same instant, offset applied, to the millisecond", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    expect(tree.time).toBeInstanceOf(Date);
+    expect(tree.time.toISOString()).toBe("2026-09-08T12:30:45.123Z");
+    expect(tree.zoned.toISOString()).toBe("2026-09-08T12:30:00.000Z");
+  });
+
+  it("keeps safe integers as numbers and only the unsafe ones as BigInt", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    expect(typeof tree.max_safe).toBe("number");
+    expect(typeof tree.min_safe).toBe("number");
+    expect(typeof tree.big).toBe("bigint");
+    expect(tree.big).toBe(9007199254740993n);
+    expect(tree.negative_big).toBe(-18446744073709551616n);
+  });
+
+  it("leaves a literal string that starts with $D a string", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    expect(tree.literal).toBe("$D2026-01-01 is a string");
+  });
+});
+
+// A server-rendered tree has unkeyed siblings (an <h1> beside a component, the
+// rows of an ERB loop). Handed to React as an array they made it log "Each
+// child in a list should have a unique key" on the Getting Started page. They
+// are passed as separate children instead — static, like JSX — and no key is
+// invented (an invented index key can collide with a template's own key and
+// duplicate a row, or reset state when a sibling comes or goes).
+describe("sibling children", () => {
+  const payload = [
+    '1:I["/TaskList.jsx","TaskList"]',
+    '0:[["$","h1",null,{"children":"Hello"}],["$","$L1",null,{"tasks":[]}],["$","ul",null,{"children":[["$","li",null,{"children":"a"}],["$","li","explicit",{"children":"b"}]]}]]',
+    "",
+  ].join("\n");
+
+  it("wraps several root siblings in a Fragment, without inventing keys", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    expect(tree.type).toBe(Fragment);
+    expect(tree.props.children.map((el) => el.key)).toEqual([null, null, null]);
+  });
+
+  it("keeps the template's own key and invents none for the others", () => {
+    const tree = createFromFlightPayload(payload, MODULE_REGISTRY);
+    const ul = tree.props.children[2];
+    expect(ul.props.children.map((el) => el.key)).toEqual([null, "explicit"]);
+    expect(ul.props.children).toHaveLength(2);
+  });
+
+  it("wraps a Suspense boundary's deferred siblings the same way", () => {
+    const deferred = buildTree([["$", "h2", null, { children: "A" }], ["$", "p", null, { children: "B" }]], EMPTY_ROWS, MODULE_REGISTRY);
+    expect(deferred.type).toBe(Fragment);
+    expect(deferred.props.children).toHaveLength(2);
+  });
+
+  it("does not spread a data array passed as children (it stays mutable)", () => {
+    const tree = createFromFlightPayload(payloadWithProps({ children: ["a", "b", "c"] }), MODULE_REGISTRY);
+    expect(tree.props.children).toEqual(["a", "b", "c"]);
+    expect(Object.isFrozen(tree.props.children)).toBe(false);
+  });
+
+  it("leaves a single root, data arrays and one-element children as they were", () => {
+    const tree = createFromFlightPayload(payloadWithProps({ tasks: [{ id: 1 }, { id: 2 }] }), MODULE_REGISTRY);
+    expect(tree.key).toBeNull();
+    expect(tree.props.tasks).toEqual([{ id: 1 }, { id: 2 }]);
+    expect(createFromFlightPayload('0:[1,2]\n', MODULE_REGISTRY)).toEqual([1, 2]);
+  });
+});