ruact 0.0.12 → 0.0.13

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

@@ -0,0 +1,433 @@
+// Story 17.0f — the navigation boundary, from the router's side.
+//
+// ruact-router.js had no tests at all. It runs in a browser; this file runs in
+// vitest's node environment with the smallest fakes of `document`, `window`,
+// `location`, `history` and `HTMLFormElement` the router actually touches — no
+// jsdom, which this package does not depend on. `fetch` is stubbed per test.
+//
+// What is pinned: a response the server marks `Ruact-Boundary: native` is handed
+// to the browser (a full load, or a NATIVE form submit — the action never ran,
+// so resubmitting is safe); a non-Flight response that escaped the server's
+// classifier is never a silent no-op; and a Flight response still renders.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { setupRouter, teardownRouter } from "./runtime/ruact-router.js";
+
+const ORIGIN = "http://localhost:3000";
+
+function fakeLocation(path) {
+  let url = new URL(path, ORIGIN);
+  return {
+    get href() { return url.href; },
+    get origin() { return url.origin; },
+    get pathname() { return url.pathname; },
+    get search() { return url.search; },
+    get hash() { return url.hash; },
+    assign: vi.fn(),
+    replace: vi.fn(),
+    _set(next) { url = new URL(next, ORIGIN); },
+  };
+}
+
+function installDom(path = "/products/1") {
+  const listeners = { document: {}, window: {} };
+  const on = (bucket) => (type, fn) => { (listeners[bucket][type] ||= []).push(fn); };
+  const off = (bucket) => (type, fn) => {
+    listeners[bucket][type] = (listeners[bucket][type] || []).filter((f) => f !== fn);
+  };
+
+  const metas = {};
+  globalThis.document = {
+    addEventListener: on("document"),
+    removeEventListener: off("document"),
+    querySelector: (selector) => {
+      const name = selector.match(/meta\[name="([^"]+)"\]/)?.[1];
+      return name && name in metas ? { content: metas[name] } : null;
+    },
+    createElement: (tag) => {
+      const el = { tagName: tag.toUpperCase(), type: "", name: "", value: "", parent: null };
+      el.remove = () => { if (el.parent) el.parent.children = el.parent.children.filter((c) => c !== el); };
+      return el;
+    },
+  };
+  globalThis.window = {
+    addEventListener: on("window"),
+    removeEventListener: off("window"),
+    scrollTo: vi.fn(),
+  };
+  globalThis.location = fakeLocation(path);
+  globalThis.history = { pushState: vi.fn((_s, _t, next) => globalThis.location._set(next)) };
+
+  class FakeForm {
+    constructor(attrs) {
+      this.tagName = "FORM";
+      this.attrs = { ...attrs };
+      this.children = [];
+    }
+    getAttribute(name) { return name in this.attrs ? this.attrs[name] : null; }
+    hasAttribute(name) { return name in this.attrs; }
+    setAttribute(name, value) { this.attrs[name] = value; }
+    removeAttribute(name) { delete this.attrs[name]; }
+    appendChild(node) { node.parent = this; this.children.push(node); }
+    querySelector(selector) {
+      const name = selector.match(/\[name="([^"]+)"\]/)?.[1];
+      return this.children.find((c) => c.name === name) ?? null;
+    }
+    get action() { return new URL(this.attrs.action ?? globalThis.location.href, ORIGIN).href; }
+    submit() {}
+  }
+  globalThis.HTMLFormElement = FakeForm;
+  globalThis.FormData = class { constructor() { this.entries = []; } forEach() {} };
+
+  return { listeners, FakeForm, metas };
+}
+
+function flightBody(text) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(text));
+      controller.close();
+    },
+  });
+}
+
+function respond({ status = 200, contentType = "text/x-component", boundary = null, body = "", url = "" } = {}) {
+  const headers = new Headers({ "content-type": contentType });
+  if (boundary) headers.set("ruact-boundary", boundary);
+  return { ok: status >= 200 && status < 300, status, statusText: String(status), url, headers, body: flightBody(body) };
+}
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+async function settle() {
+  for (let i = 0; i < 5; i += 1) await flush();
+}
+
+function anchor(href) {
+  const el = {
+    getAttribute: (name) => (name === "href" ? href : null),
+    hasAttribute: () => false,
+    target: "",
+  };
+  el.closest = () => el;
+  return el;
+}
+
+function click(listeners, href) {
+  const event = {
+    defaultPrevented: false, metaKey: false, ctrlKey: false, shiftKey: false, altKey: false, button: 0,
+    target: anchor(href),
+    preventDefault() { this.defaultPrevented = true; },
+  };
+  listeners.document.click.forEach((fn) => fn(event));
+  return event;
+}
+
+function submit(listeners, form, submitter = null) {
+  const event = { defaultPrevented: false, target: form, submitter, preventDefault() { this.defaultPrevented = true; } };
+  listeners.document.submit.forEach((fn) => fn(event));
+  return event;
+}
+
+describe("ruact-router — the navigation boundary (Story 17.0f)", () => {
+  let dom;
+  let onNavigate;
+  let onError;
+
+  beforeEach(() => {
+    dom = installDom();
+    onNavigate = vi.fn();
+    onError = vi.fn();
+    globalThis.fetch = vi.fn();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    setupRouter({ onNavigate, moduleRegistry: {}, onError });
+  });
+
+  afterEach(() => {
+    teardownRouter();
+    vi.restoreAllMocks();
+  });
+
+  describe("a link the server marks Ruact-Boundary: native", () => {
+    it("is handed to the browser as a full load — no render, no pushState", async () => {
+      fetch.mockResolvedValue(respond({ contentType: "text/plain", boundary: "native", url: `${ORIGIN}/people/1` }));
+
+      click(dom.listeners, "/people/1");
+      await settle();
+
+      expect(location.assign).toHaveBeenCalledWith(`${ORIGIN}/people/1`);
+      expect(onNavigate).not.toHaveBeenCalled();
+      expect(history.pushState).not.toHaveBeenCalled();
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    // Back/forward: `assign` would push a NEW entry in the middle of the history
+    // the user is walking through.
+    it("uses location.replace when it came from popstate", async () => {
+      fetch.mockResolvedValue(respond({ contentType: "text/plain", boundary: "native", url: `${ORIGIN}/people/1` }));
+      location._set("/people/1");
+
+      dom.listeners.window.popstate.forEach((fn) => fn({}));
+      await settle();
+
+      expect(location.replace).toHaveBeenCalledWith(`${ORIGIN}/people/1`);
+      expect(location.assign).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("a non-Flight answer that escaped the server's classifier", () => {
+    // The 2026-09-12 spike's S2: a Rails controller answers 200 text/html, the
+    // line parser returns null for every HTML line, nothing renders, the URL does
+    // not change, and nothing reports an error. A dead click.
+    it("on a GET, becomes a full load instead of a dead click", async () => {
+      fetch.mockResolvedValue(respond({ contentType: "text/html; charset=utf-8", body: "<h1>person</h1>\n", url: `${ORIGIN}/people/1` }));
+
+      click(dom.listeners, "/people/1");
+      await settle();
+
+      expect(location.assign).toHaveBeenCalledWith(`${ORIGIN}/people/1`);
+      expect(onNavigate).not.toHaveBeenCalled();
+    });
+
+    // The action already ran: resubmitting would run it twice. Say so instead.
+    it("on a non-GET form, reports an error naming the form and the fix — never silent, never resubmitted", async () => {
+      const form = new dom.FakeForm({ action: "/people", method: "post" });
+      const nativeSubmit = vi.spyOn(HTMLFormElement.prototype, "submit");
+      fetch.mockResolvedValue(respond({ status: 422, contentType: "text/html", body: "<p>invalid</p>" }));
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      const message = onError.mock.calls[0][0].message;
+      expect(message).toContain("POST /people");
+      expect(message).toContain("422");
+      expect(message).toContain('data-ruact="false"');
+      expect(nativeSubmit).not.toHaveBeenCalled();
+      expect(location.assign).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("a form the server marks Ruact-Boundary: native", () => {
+    it("is submitted NATIVELY — the action never ran, so this is its one run", async () => {
+      const form = new dom.FakeForm({ action: "/people", method: "post" });
+      const nativeSubmit = vi.spyOn(HTMLFormElement.prototype, "submit");
+      fetch.mockResolvedValue(respond({ contentType: "text/plain", boundary: "native" }));
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(nativeSubmit).toHaveBeenCalledTimes(1);
+      expect(nativeSubmit.mock.contexts[0]).toBe(form);
+      expect(fetch).toHaveBeenCalledTimes(1);
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    // A native submit loses the submitter unless it is carried over: the
+    // browser only includes `name=value` of the button that was clicked.
+    it("carries the submitter's name/value and overrides DURING the submit, and takes them back after", async () => {
+      const form = new dom.FakeForm({ action: "/people", method: "post" });
+      const submitter = {
+        name: "op", value: "archive",
+        hasAttribute: (n) => ["formAction", "formMethod", "formaction", "formmethod", "formenctype"].includes(n),
+        getAttribute: (n) => ({
+          formAction: "/people/archive", formaction: "/people/archive",
+          formMethod: "post", formmethod: "post", formenctype: "multipart/form-data",
+        })[n] ?? null,
+      };
+      let during;
+      vi.spyOn(HTMLFormElement.prototype, "submit").mockImplementation(function () {
+        during = { action: this.getAttribute("action"), enctype: this.getAttribute("enctype"), fields: this.children.map((c) => [c.name, c.value]) };
+      });
+      fetch.mockResolvedValue(respond({ contentType: "text/plain", boundary: "native" }));
+
+      submit(dom.listeners, form, submitter);
+      await settle();
+
+      expect(during).toEqual({ action: "/people/archive", enctype: "multipart/form-data", fields: [["op", "archive"]] });
+      // Taken back: a page that survives the submit keeps its form as it was.
+      expect(form.getAttribute("action")).toBe("/people");
+      expect(form.hasAttribute("enctype")).toBe(false);
+      expect(form.children).toEqual([]);
+    });
+
+    // Review round 1 — a form a React component rendered has no token field;
+    // the router's fetch sent it as a header, a native submit cannot.
+    it("adds the CSRF token from the meta tags when the form has no token field", async () => {
+      dom.metas["csrf-param"] = "authenticity_token";
+      dom.metas["csrf-token"] = "tok-123";
+      const form = new dom.FakeForm({ action: "/people", method: "post" });
+      let fields;
+      vi.spyOn(HTMLFormElement.prototype, "submit").mockImplementation(function () {
+        fields = this.children.map((c) => [c.name, c.value]);
+      });
+      fetch.mockResolvedValue(respond({ contentType: "text/plain", boundary: "native" }));
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(fields).toEqual([["authenticity_token", "tok-123"]]);
+    });
+
+    // Review round 1 — a native answer at the END of a redirect the fetch
+    // followed means the action already ran. Resubmitting would run it twice.
+    it("loads the redirect target instead of resubmitting when the fetch was redirected", async () => {
+      const form = new dom.FakeForm({ action: "/people", method: "post" });
+      const nativeSubmit = vi.spyOn(HTMLFormElement.prototype, "submit");
+      fetch.mockResolvedValue({ ...respond({ contentType: "text/plain", boundary: "native", url: `${ORIGIN}/people/3` }), redirected: true });
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(nativeSubmit).not.toHaveBeenCalled();
+      expect(location.assign).toHaveBeenCalledWith(`${ORIGIN}/people/3`);
+    });
+  });
+
+  describe("review round 1 — errors stay errors", () => {
+    // Review round 2 — the default app passes no onError: an error page kept
+    // on the error path is a console line and a dead click. Load it, so the
+    // user sees it; repeating a GET is harmless.
+    it("loads a GET error page (500 HTML) in full so the user sees it", async () => {
+      fetch.mockResolvedValue(respond({ status: 500, contentType: "text/html", body: "<h1>oops</h1>", url: `${ORIGIN}/products/9` }));
+
+      click(dom.listeners, "/products/9");
+      await settle();
+
+      expect(location.assign).toHaveBeenCalledWith(`${ORIGIN}/products/9`);
+    });
+
+    it("rejects revalidate() when the server says the page is not ruact's", async () => {
+      fetch.mockResolvedValue(respond({ contentType: "text/plain", boundary: "native" }));
+
+      await expect(globalThis.__ruact_revalidate()).rejects.toThrow("is not a ruact page");
+      expect(location.assign).not.toHaveBeenCalled();
+    });
+
+    it("rejects revalidate() on a non-Flight answer instead of reloading", async () => {
+      fetch.mockResolvedValue(respond({ contentType: "text/html", body: "<h1>html</h1>" }));
+
+      await expect(globalThis.__ruact_revalidate()).rejects.toThrow("did not answer with a ruact response");
+      expect(location.assign).not.toHaveBeenCalled();
+    });
+
+    // A 403 is a CSRF rejection: the action did NOT run, and telling the
+    // developer it did (and to add data-ruact="false") points the wrong way.
+    it("does not call a 403 on a form 'not a ruact page'", async () => {
+      const form = new dom.FakeForm({ action: "/people", method: "post" });
+      fetch.mockResolvedValue(respond({ status: 403, contentType: "text/html", body: "forbidden" }));
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(onError.mock.calls[0][0].message).not.toContain("data-ruact");
+      expect(onError.mock.calls[0][0].message).toContain("403");
+    });
+
+    // Fetch drops the #fragment from response.url.
+    it("keeps the link's #fragment on a full load", async () => {
+      fetch.mockResolvedValue(respond({ contentType: "text/plain", boundary: "native", url: `${ORIGIN}/docs/guide` }));
+
+      click(dom.listeners, "/docs/guide#install");
+      await settle();
+
+      expect(location.assign).toHaveBeenCalledWith(`${ORIGIN}/docs/guide#install`);
+    });
+  });
+
+  // Story 17.0i — `render :new, status: :unprocessable_entity` on a ruact page
+  // answers Flight with a 422: the validation errors are the page's content,
+  // not a transport failure.
+  describe("a Flight answer with a 422", () => {
+    const tree = '0:["$","p",null,{"children":"Title can\'t be blank"}]\n';
+
+    it("renders a form's re-render and keeps the form's URL — the POST URL is not replayable", async () => {
+      const form = new dom.FakeForm({ action: "/posts", method: "post" });
+      fetch.mockResolvedValue(respond({ status: 422, body: tree, url: `${ORIGIN}/posts` }));
+      globalThis.location._set("/posts/new");
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(onNavigate).toHaveBeenCalledTimes(1);
+      expect(onError).not.toHaveBeenCalled();
+      expect(history.pushState).not.toHaveBeenCalled();
+      expect(location.pathname).toBe("/posts/new");
+    });
+
+    it("renders a navigation's 422 too", async () => {
+      fetch.mockResolvedValue(respond({ status: 422, body: tree, url: `${ORIGIN}/posts/new` }));
+
+      click(dom.listeners, "/posts/new");
+      await settle();
+
+      expect(onNavigate).toHaveBeenCalledTimes(1);
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    it("resolves revalidate() — a 422 is content, not a failure", async () => {
+      fetch.mockResolvedValue(respond({ status: 422, body: tree }));
+
+      await expect(globalThis.__ruact_revalidate()).resolves.not.toThrow();
+      expect(onNavigate).toHaveBeenCalledTimes(1);
+    });
+
+    // Review R1 — only a FLIGHT 422 is a page. Rails' own HTML 422 error page
+    // (RecordInvalid) on a revalidate is a failure to report, as before.
+    it("still rejects revalidate() on a 422 that is not Flight", async () => {
+      fetch.mockResolvedValue(respond({ status: 422, contentType: "text/html", body: "<h1>Unprocessable</h1>" }));
+
+      await expect(globalThis.__ruact_revalidate()).rejects.toThrow();
+      expect(onNavigate).not.toHaveBeenCalled();
+    });
+
+    // Review R1 — a POST the fetch followed through a redirect ended on a GET:
+    // that URL can be asked for again, and it is the page being shown.
+    it("pushes the URL a form's redirect ended on", async () => {
+      const form = new dom.FakeForm({ action: "/posts", method: "post" });
+      const response = respond({ status: 422, body: tree, url: `${ORIGIN}/drafts/9/edit` });
+      response.redirected = true;
+      fetch.mockResolvedValue(response);
+      globalThis.location._set("/posts/new");
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(onNavigate).toHaveBeenCalledTimes(1);
+      expect(history.pushState).toHaveBeenCalledWith(null, "", "/drafts/9/edit");
+    });
+
+    it("still rejects revalidate() on any other failing Flight status", async () => {
+      for (const status of [404, 500]) {
+        fetch.mockResolvedValue(respond({ status, body: tree }));
+        await expect(globalThis.__ruact_revalidate()).rejects.toThrow(`Request failed: ${status}`);
+      }
+      expect(onNavigate).not.toHaveBeenCalled();
+    });
+
+    it("keeps every other non-2xx Flight answer on the error path", async () => {
+      const form = new dom.FakeForm({ action: "/posts", method: "post" });
+      fetch.mockResolvedValue(respond({ status: 500, body: tree }));
+
+      submit(dom.listeners, form);
+      await settle();
+
+      expect(onNavigate).not.toHaveBeenCalled();
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(onError.mock.calls[0][0].message).toContain("Request failed: 500");
+    });
+  });
+
+  describe("a Flight answer", () => {
+    it("still renders in place, as before", async () => {
+      fetch.mockResolvedValue(respond({ body: '0:["$","h1",null,{"children":"hi"}]\n', url: `${ORIGIN}/products/2` }));
+
+      click(dom.listeners, "/products/2");
+      await settle();
+
+      expect(onNavigate).toHaveBeenCalledTimes(1);
+      expect(history.pushState).toHaveBeenCalled();
+      expect(location.assign).not.toHaveBeenCalled();
+    });
+  });
+});

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

@@ -275,6 +275,101 @@ function _buildFormData(form, submitter) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Story 17.0f — the navigation boundary
+// ---------------------------------------------------------------------------
+
+function _isNativeBoundary(response) {
+  return response.headers?.get("ruact-boundary") === "native";
+}
+
+function _isFlight(response) {
+  return (response.headers?.get("content-type") || "").includes("text/x-component");
+}
+
+// A full document load of the final URL (after any redirect the fetch
+// followed). `replace` for back/forward, so no entry is pushed mid-history.
+//
+// `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 } = {}) {
+  const requested = new URL(targetUrl, location.href);
+  const destination = new URL(response.url || requested.href);
+  if (!destination.hash && requested.hash) destination.hash = requested.hash;
+  if (replace) location.replace(destination.href);
+  else location.assign(destination.href);
+}
+
+function _escapedFormMessage(method, targetUrl, response) {
+  const path = new URL(targetUrl, location.href).pathname;
+  const type = response.headers?.get("content-type") || "no content type";
+  return `[ruact] ${method} ${path} answered ${response.status} with ${type}, not a ruact page. ` +
+    "The action already ran, so ruact will not submit the form again. " +
+    'Add data-ruact="false" to this <form> to let the browser submit it, ' +
+    "or have the action answer through ruact.";
+}
+
+// Submits the form as the browser would, WITHOUT dispatching a `submit` event —
+// so neither this router nor Turbo intercepts it again. The browser only sends
+// the clicked button's `name=value` (and honours its `formaction` / `formmethod`
+// / `formtarget`) when that button is the submitter, which `submit()` has no way
+// to express: both are carried over onto the form first.
+//
+// Everything added to the form is taken back right after: `submit()` builds its
+// entry list synchronously, and a page that survives the submit (a download, a
+// 204, a return from the back-forward cache) must not keep the last button's
+// overrides and value for the next one.
+//
+// A form rendered by a React component has no `authenticity_token` field — the
+// router's own fetch sent the token as a header. A native submit cannot, so the
+// token from `<meta name="csrf-token">` goes in as a field, the way rails-ujs
+// does it.
+const _SUBMITTER_OVERRIDES = [
+  ["formaction", "action"], ["formmethod", "method"], ["formtarget", "target"], ["formenctype", "enctype"],
+];
+
+function _nativeSubmit(form, submitter) {
+  const restore = [];
+  const added = [];
+
+  if (submitter) {
+    for (const [override, attribute] of _SUBMITTER_OVERRIDES) {
+      if (!submitter.hasAttribute(override)) continue;
+      restore.push([attribute, form.hasAttribute(attribute) ? form.getAttribute(attribute) : null]);
+      form.setAttribute(attribute, submitter.getAttribute(override));
+    }
+    if (submitter.name) added.push(_hiddenField(submitter.name, submitter.value));
+  }
+
+  const csrfParam = document.querySelector('meta[name="csrf-param"]')?.content;
+  const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
+  if (csrfParam && csrfToken && !_hasField(form, csrfParam)) added.push(_hiddenField(csrfParam, csrfToken));
+
+  added.forEach((field) => form.appendChild(field));
+  try {
+    HTMLFormElement.prototype.submit.call(form);
+  } finally {
+    added.forEach((field) => field.remove?.());
+    restore.forEach(([attribute, value]) => {
+      if (value === null) form.removeAttribute?.(attribute);
+      else form.setAttribute(attribute, value);
+    });
+  }
+}
+
+function _hiddenField(name, value) {
+  const field = document.createElement("input");
+  field.type = "hidden";
+  field.name = name;
+  field.value = value;
+  return field;
+}
+
+function _hasField(form, name) {
+  const quoted = name.replace(/["\\]/g, "\\$&");
+  return Boolean(form.elements?.namedItem?.(name) ?? form.querySelector?.(`[name="${quoted}"]`));
+}
+
 async function _submitForm(form, submitter = null) {
   clearPendingChunks();
 
@@ -317,7 +412,18 @@ async function _submitForm(form, submitter = null) {
       headers,
       signal:  controller.signal,
     });
-    await _processFlightResponse(response, { push: true, targetUrl: action });
+    // Story 17.0f — not a ruact page, and the action did NOT run: this native
+    // submit is its one and only run, and its real response (a 422 with the
+    // validation errors included) is what the user sees.
+    if (_isNativeBoundary(response)) {
+      // The boundary answer came at the END of a redirect the fetch followed:
+      // the form's action already ran (a real 3xx, e.g. to another scheme), and
+      // resubmitting would run it twice. Load where it redirected to instead.
+      if (response.redirected) _fullLoad(response, action);
+      else _nativeSubmit(form, submitter);
+      return;
+    }
+    await _processFlightResponse(response, { push: true, targetUrl: action, method: htmlMethod });
   } catch (err) {
     if (err.name === "AbortError") return;
     console.error("[ruact-router] Form submission error:", err);
@@ -330,7 +436,9 @@ async function _submitForm(form, submitter = null) {
 // ---------------------------------------------------------------------------
 
 function handlePopstate() {
-  navigate(location.pathname + location.search + location.hash, { push: false, scroll: false });
+  // 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.
+  navigate(location.pathname + location.search + location.hash, { push: false, scroll: false, replace: true });
 }
 
 // ---------------------------------------------------------------------------
@@ -346,7 +454,7 @@ 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 } = {}) {
+async function navigate(url, { push = true, scroll = true, throwOnError = false, replace = false } = {}) {
   // Clear stale lazy refs from any previous streaming navigation
   clearPendingChunks();
 
@@ -359,11 +467,21 @@ async function navigate(url, { push = true, scroll = true, throwOnError = false
       headers: { Accept: "text/x-component", "Ruact-Request": "1" },
       signal:  controller.signal,
     });
+    // Story 17.0f — the server said the destination is not a ruact page, and
+    // ran nothing to say so. The browser takes it from here.
+    if (_isNativeBoundary(response)) {
+      // A caller that asked to be told (revalidate) refetches the page it is
+      // ON; "not a ruact page" there is a failure to report, not a reload.
+      if (throwOnError) throw new Error(`[ruact] ${url} is not a ruact page`);
+      _fullLoad(response, url, { replace });
+      return;
+    }
     await _processFlightResponse(response, {
       push,
       targetUrl: url,
       scroll,
       throwOnError,
+      replace,
     });
   } catch (err) {
     if (err.name === "AbortError") {
@@ -380,8 +498,47 @@ async function navigate(url, { push = true, scroll = true, throwOnError = false
 // Shared Flight response processor (used by navigate + _submitForm)
 // ---------------------------------------------------------------------------
 
-async function _processFlightResponse(response, { push, targetUrl, scroll = true, throwOnError = false }) {
-  if (!response.ok) {
+async function _processFlightResponse(response, {
+  push, targetUrl, scroll = true, throwOnError = false, replace = false, method = "GET",
+}) {
+  // Story 17.0f — a response that is not Flight escaped the server's boundary
+  // classifier. Feeding it to the line parser was the old dead click: every HTML
+  // line parses to null, nothing renders, nothing reports.
+  //
+  // A non-Flight GET — a page, or an error page (404, 500, a 401 from auth) —
+  // is loaded in full so the user SEES it: the default app passes no onError,
+  // and a console line is a dead click by another name. Repeating a GET is
+  // harmless. A caller that asked to be told (`throwOnError`: revalidate)
+  // gets the error instead of a reload.
+  if (!_isFlight(response)) {
+    if (method === "GET" && !throwOnError) {
+      _fullLoad(response, targetUrl, { replace });
+      return;
+    }
+    // A form whose action answered HTML — it ran, so it will not be resubmitted.
+    // Only a 2xx or a 422 is that; a 403 (CSRF) or a 500 is a failure, below.
+    if (method !== "GET" && (response.ok || response.status === 422)) {
+      const err = new Error(_escapedFormMessage(method, targetUrl, response));
+      console.error(err.message);
+      _onError?.(err);
+      if (throwOnError) throw err;
+      return;
+    }
+    if (response.ok) {
+      const err = new Error(`[ruact] ${targetUrl} did not answer with a ruact response`);
+      console.error(err.message);
+      _onError?.(err);
+      if (throwOnError) throw err;
+      return;
+    }
+  }
+
+  // Story 17.0i — a Flight 422 is a page: `render :new, status:
+  // :unprocessable_entity` re-rendering a form with its validation errors. The
+  // errors are the content, not a transport failure. Every other non-2xx stays
+  // a failure — an HTML 422 (Rails' own error page) included.
+  const unprocessable = response.status === 422 && _isFlight(response);
+  if (!response.ok && !unprocessable) {
     const msg = `[ruact] Request failed: ${response.status} ${response.statusText}`;
     console.error(msg);
     const err = new Error(msg);
@@ -392,6 +549,12 @@ async function _processFlightResponse(response, { push, targetUrl, scroll = true
     return;
   }
 
+  // Story 17.0i — a form's 422 re-render keeps the form's URL: the POST URL is
+  // not one a reload or Back can ask for again (a reload of `/posts` would be
+  // the index). Unless the fetch followed a redirect: it then ended on a GET,
+  // and that URL is the page being shown.
+  const pushEntry = push && !(unprocessable && method !== "GET" && !response.redirected);
+
   // Use final URL after any redirects (response.url is the resolved URL).
   const finalPath = response.url
     ? (() => { const u = new URL(response.url); return u.pathname + u.search + u.hash; })()
@@ -422,7 +585,7 @@ async function _processFlightResponse(response, { push, targetUrl, scroll = true
       }
       // Normal case: build tree and render immediately.
       const tree = buildTreeFromRows(rows, _moduleRegistry);
-      if (push) history.pushState(null, "", finalPath);
+      if (pushEntry) history.pushState(null, "", finalPath);
       _onNavigate(tree);
       if (scroll) window.scrollTo(0, 0);
       initialTreeSet = true;
@@ -466,7 +629,7 @@ async function _processFlightResponse(response, { push, targetUrl, scroll = true
   // Fallback: if row 0 never triggered (shouldn't happen with valid server)
   if (!initialTreeSet && !redirected && rows.has(0)) {
     const tree = buildTreeFromRows(rows, _moduleRegistry);
-    if (push) history.pushState(null, "", finalPath);
+    if (pushEntry) history.pushState(null, "", finalPath);
     _onNavigate(tree);
     if (scroll) window.scrollTo(0, 0);
   }