ruact 0.0.19 → 0.0.21

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

@@ -0,0 +1,108 @@
+// 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";
+
+/**
+ * What the router dispatches on the document before it stops one it leaves
+ * while it still loads (Story 19-2).
+ */
+export const LEAVE_EVENT = "ruact:leave";
+
+/**
+ * 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.
+ *
+ * A document the router leaves ({@link LEAVE_EVENT}) ends the stream as an
+ * aborted navigation does: the page being left reports no response cut short.
+ */
+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 = (error) => {
+        if (!open) return;
+        open = false;
+        doc?.removeEventListener?.("readystatechange", atEnd);
+        doc?.removeEventListener?.(LEAVE_EVENT, left);
+        if (error) controller.error(error);
+        else controller.close();
+      };
+      // Closed when the document stops loading: its end (`interactive`, just
+      // before DOMContentLoaded), or the router stopping it (Story 19-2).
+      const atEnd = () => {
+        if (doc.readyState !== "loading") close();
+      };
+      const left = () => close(new DOMException("the page was left while it loaded", "AbortError"));
+      if (doc?.readyState === "loading") {
+        doc.addEventListener("readystatechange", atEnd);
+        doc.addEventListener(LEAVE_EVENT, left);
+      } 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 */ }
+}

data/vendor/javascript/vite-plugin-ruact/runtime/ruact-router.js

@@ -10,9 +10,8 @@
  * Also handles popstate for browser back/forward.
  */
 
-import { createFromReadableStream } from "virtual:ruact/flight-client";
 import { setBoundaryErrorHandler } from "./suspense-boundary.js";
-import { labelledStream } from "./transport.js";
+import { LEAVE_EVENT, openPage } from "./page-stream.js";
 
 // Errors already reported once (by a Suspense boundary) that navigate() must
 // not report again on their way out to a revalidate() caller.
@@ -22,17 +21,29 @@ let _onNavigate     = null;
 let _onError        = null;
 let _currentAbort   = null;
 
+// Story 19-2 — whether the page on screen is a document the router stopped
+// and has not replaced yet (a new tree, a full load, a native submit); and the
+// path of the page on screen, which a `#anchor` does not leave.
+let _pageStopped    = false;
+let _renderedPath   = null;
+
 /**
  * @param {object}   opts
  * @param {function} opts.onNavigate     - called with the new React element tree
  * @param {function} [opts.onError]      - called with an Error when navigation fails,
  *                                         or when a Suspense child's row is an error
+ * @param {function} [opts.onBoundaryError] - called, too, when a Suspense child's
+ *                                         row is an error (the bootstrap's development
+ *                                         overlay — Story 19-1); not for a navigation
  */
-export function setupRouter({ onNavigate, onError = null }) {
+export function setupRouter({ onNavigate, onError = null, onBoundaryError = null }) {
   _onNavigate     = onNavigate;
   _onError        = onError;
+  _pageStopped    = false;
+  _renderedPath   = typeof location === "undefined" ? null : location.pathname + location.search;
   setBoundaryErrorHandler((error) => {
     console.error(error.message);
+    onBoundaryError?.(error);
     _onError?.(error);
   });
 
@@ -55,11 +66,15 @@ export function setupRouter({ onNavigate, onError = null }) {
   // what link clicks and form submits want, but a programmatic
   // `revalidate()` caller HAS to be able to branch on success vs.
   // failure.
+  // `leave: false` (Story 19-2): revalidate() stays on the page, so a
+  // document still streaming is not stopped — stopping it would also fail the
+  // page's other requests in flight (a server function, a useQuery).
   globalThis.__ruact_revalidate = (target) =>
     navigate(target ?? location.pathname + location.search, {
       push: false,
       scroll: false,
       throwOnError: true,
+      leave: false,
     });
 }
 
@@ -109,9 +124,12 @@ function handleClick(event) {
   const anchor = event.target.closest("a[href]");
   if (!shouldIntercept(anchor)) return;
 
-  event.preventDefault();
-
   const url = new URL(anchor.getAttribute("href"), location.href);
+  // Story 19-2 — this page with a `#anchor`: the browser scrolls; nothing to
+  // fetch, and a page still streaming is not left.
+  if (url.hash && url.pathname + url.search === location.pathname + location.search) return;
+
+  event.preventDefault();
   navigate(url.pathname + url.search + url.hash);
 }
 
@@ -301,6 +319,7 @@ function _isFlight(response) {
 // `response.url` never carries the #fragment (Fetch strips it), so the one
 // the link asked for is put back.
 function _fullLoad(response, targetUrl, { replace = false } = {}) {
+  _pageStopped = false;
   const requested = new URL(targetUrl, location.href);
   const destination = new URL(response.url || requested.href);
   if (!destination.hash && requested.hash) destination.hash = requested.hash;
@@ -337,6 +356,7 @@ const _SUBMITTER_OVERRIDES = [
 ];
 
 function _nativeSubmit(form, submitter) {
+  _pageStopped = false;
   const restore = [];
   const added = [];
 
@@ -402,6 +422,7 @@ async function _submitForm(form, submitter = null) {
   // Rails _method hidden field is included in FormData automatically;
   // Rack::MethodOverride reads it and routes to the correct action.
   _currentAbort?.abort();
+  _leaveOpenDocument();
   const controller = (_currentAbort = new AbortController());
 
   const headers = { Accept: "text/x-component", "Ruact-Request": "1" };
@@ -436,6 +457,8 @@ async function _submitForm(form, submitter = null) {
     if (err.name === "AbortError") return;
     console.error("[ruact-router] Form submission error:", err);
     _onError?.(err);
+  } finally {
+    _recoverStoppedPage(controller);
   }
 }
 
@@ -446,6 +469,9 @@ async function _submitForm(form, submitter = null) {
 function handlePopstate() {
   // Story 17.0f — `replace`: if this entry turns out not to be a ruact page, the
   // full load must not push a NEW entry into the history being walked.
+  // Story 19-2 — only the hash changed (a `#anchor`, Back over one): the page
+  // on screen is this one, and the browser scrolls.
+  if (location.pathname + location.search === _renderedPath) return;
   navigate(location.pathname + location.search + location.hash, { push: false, scroll: false, replace: true });
 }
 
@@ -453,6 +479,38 @@ function handlePopstate() {
 // Navigation
 // ---------------------------------------------------------------------------
 
+/**
+ * Story 19-2 — the page being left may be a document still arriving: a page
+ * that streams, whose <Suspense> rows are still to come. Nobody will see them,
+ * so stop loading it: the connection closes, and the server, which asks before
+ * each block, starts no further block for it. Only a document that streams
+ * and has rows still to come (the server marks it, `__FLIGHT_DATA.streaming`):
+ * any other document still being parsed — a slow network, a long layout — is
+ * left to load, the part of its layout after `#root` included.
+ */
+function _leaveOpenDocument() {
+  if (typeof document === "undefined" || document.readyState !== "loading") return;
+  if (globalThis.__FLIGHT_DATA?.streaming !== true) return;
+  // First its rows' stream ends as an aborted navigation: stopped, it would
+  // read as a response cut short, which the page being left reports.
+  if (typeof document.dispatchEvent === "function") document.dispatchEvent(new Event(LEAVE_EVENT));
+  if (typeof window !== "undefined" && typeof window.stop === "function") window.stop();
+  _pageStopped = true;
+}
+
+/**
+ * Story 19-2 — a navigation ended without replacing a page the router had
+ * stopped (a failed fetch, a 403 or a 500 to a form — this navigation's, or a
+ * later one's that superseded the one that stopped it): the user is still on
+ * that page, whose boundaries would keep their fallback. Fetch it again,
+ * without stopping anything, once. Not when a newer navigation took over.
+ */
+function _recoverStoppedPage(controller) {
+  if (!_pageStopped || controller.signal.aborted) return;
+  _pageStopped = false;
+  navigate(location.pathname + location.search, { push: false, scroll: false, leave: false });
+}
+
 /**
  * Story 8.2 review patch R7 (2026-05-17) — `throwOnError` opts a caller
  * out of the swallow-and-forward error mode. The default (false) is the
@@ -462,9 +520,10 @@ function handlePopstate() {
  * REJECTS on a failed Flight fetch — without this, callers cannot
  * branch on success vs. failure of a programmatic refetch.
  */
-async function navigate(url, { push = true, scroll = true, throwOnError = false, replace = false } = {}) {
+async function navigate(url, { push = true, scroll = true, throwOnError = false, replace = false, leave = true } = {}) {
   // Abort any in-flight fetch so we don't apply a stale response
   _currentAbort?.abort();
+  if (leave) _leaveOpenDocument();
   const controller = (_currentAbort = new AbortController());
 
   try {
@@ -501,6 +560,8 @@ async function navigate(url, { push = true, scroll = true, throwOnError = false,
     console.error("[ruact-router] Navigation error:", err);
     _onError?.(err);
     if (throwOnError) throw err;
+  } finally {
+    _recoverStoppedPage(controller);
   }
 }
 
@@ -570,15 +631,11 @@ async function _processFlightResponse(response, {
     ? (() => { const u = new URL(response.url); return u.pathname + u.search + u.hash; })()
     : targetUrl;
 
-  // Two readers of one body: React's client, and a drain that settles when the
-  // last row is in — `revalidate()` resolves then, as it always has.
-  const [forClient, forEnd] = response.body.tee();
-  const streamEnd = _drain(forEnd);
-  streamEnd.catch(() => {}); // awaited below; an abort must not be "unhandled" first
-
   // Resolves when row 0 arrives; deferred Suspense rows keep streaming into it.
-  // A stream that ends without a root rejects (runtime/transport.js labels it).
-  const root = await createFromReadableStream(labelledStream(forClient));
+  // `page.end` settles when the last row is in — `revalidate()` resolves then,
+  // as it always has.
+  const page = openPage(response.body);
+  const root = await page.root;
 
   // A newer navigation started while this one was in flight: it owns the page.
   if (signal?.aborted) return;
@@ -595,11 +652,13 @@ async function _processFlightResponse(response, {
   }
 
   if (pushEntry) history.pushState(null, "", finalPath);
+  _pageStopped = false;
+  _renderedPath = location.pathname + location.search;
   _onNavigate(root);
   if (scroll) window.scrollTo(0, 0);
 
   try {
-    await streamEnd;
+    await page.end;
   } catch (err) {
     // The page is on screen. A row that never arrived was reported by its
     // Suspense boundary; a revalidate() caller still learns it failed.
@@ -607,8 +666,3 @@ async function _processFlightResponse(response, {
     throw err;
   }
 }
-
-async function _drain(stream) {
-  const reader = stream.getReader();
-  while (!(await reader.read()).done) { /* the client has its own copy */ }
-}

data/vendor/javascript/vite-plugin-ruact/runtime/suspense-boundary.js

@@ -27,6 +27,7 @@ export function setBoundaryErrorHandler(handler) {
 // runtime/transport.js labels a response cut short the same way.
 const DIGEST_MESSAGES = {
   "ruact:suspense-timeout": "Suspense timeout exceeded",
+  "ruact:suspense-error": "An error occurred in a <Suspense>",
   "ruact:connection-closed": "the response ended before the whole page arrived",
 };
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.19
+  version: 0.0.21
 platform: ruby
 authors:
 - Luiz Garcia
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -71,15 +71,20 @@ files:
 - lib/generators/ruact/scaffold/templates/views/new.html.erb.tt
 - lib/generators/ruact/scaffold/templates/views/show.html.erb.tt
 - lib/ruact.rb
+- lib/ruact/cached_blocks.rb
 - lib/ruact/client_manifest.rb
 - lib/ruact/component_attributes.rb
 - lib/ruact/component_contract.rb
 - lib/ruact/configuration.rb
 - lib/ruact/controller.rb
+- lib/ruact/controller/delivery.rb
 - lib/ruact/controller/document_rendering.rb
 - lib/ruact/controller/format_negotiation.rb
 - lib/ruact/controller/page_rendering.rb
 - lib/ruact/controller/pages.rb
+- lib/ruact/controller/streaming.rb
+- lib/ruact/declared_content.rb
+- lib/ruact/deferred_render.rb
 - lib/ruact/doctor.rb
 - lib/ruact/erb_preprocessor.rb
 - lib/ruact/erb_preprocessor_hook.rb
@@ -93,15 +98,20 @@ files:
 - lib/ruact/flight/serializer.rb
 - lib/ruact/flight/utf8.rb
 - lib/ruact/html_converter.rb
+- lib/ruact/inline_script.rb
 - lib/ruact/layout_source.rb
+- lib/ruact/load_async_note.rb
 - lib/ruact/manifest_resolver.rb
+- lib/ruact/markers.rb
 - lib/ruact/navigation_boundary.rb
 - lib/ruact/packaging.rb
 - lib/ruact/query.rb
+- lib/ruact/query_watch.rb
 - lib/ruact/railtie.rb
 - lib/ruact/redirect_path.rb
 - lib/ruact/render_context.rb
 - lib/ruact/render_pipeline.rb
+- lib/ruact/request_kind.rb
 - lib/ruact/routing.rb
 - lib/ruact/serializable.rb
 - lib/ruact/server.rb
@@ -134,6 +144,7 @@ files:
 - lib/ruact/validation_errors_collector.rb
 - lib/ruact/version.rb
 - lib/ruact/view_helper.rb
+- lib/ruact/view_helper/suspense.rb
 - lib/ruact/views/layouts/ruact.html.erb
 - lib/rubocop/cop/ruact.rb
 - lib/rubocop/cop/ruact/no_extend_self.rb
@@ -154,11 +165,15 @@ files:
 - vendor/javascript/vite-plugin-ruact/manifest-http.test.mjs
 - vendor/javascript/vite-plugin-ruact/package-lock.json
 - vendor/javascript/vite-plugin-ruact/package.json
+- vendor/javascript/vite-plugin-ruact/page-mount.test.mjs
+- vendor/javascript/vite-plugin-ruact/page-stream.test.mjs
 - vendor/javascript/vite-plugin-ruact/registry.test.mjs
 - vendor/javascript/vite-plugin-ruact/ruact-router.test.mjs
 - vendor/javascript/vite-plugin-ruact/runtime/bootstrap.jsx
+- vendor/javascript/vite-plugin-ruact/runtime/dev-overlay.js
 - vendor/javascript/vite-plugin-ruact/runtime/flight-modules.js
 - vendor/javascript/vite-plugin-ruact/runtime/flight-webpack-globals.js
+- vendor/javascript/vite-plugin-ruact/runtime/page-stream.js
 - vendor/javascript/vite-plugin-ruact/runtime/root-boundary.js
 - vendor/javascript/vite-plugin-ruact/runtime/ruact-router.js
 - vendor/javascript/vite-plugin-ruact/runtime/suspense-boundary.js