@webjsdev/core 0.7.9 → 0.7.11

package/src/router-client.js

@@ -2,6 +2,15 @@
 // `import '@webjsdev/core/client-router'` get the escape-hatch element
 // available without a second import.
 import './webjs-frame.js';
+// Same for the <webjs-stream> element. Registering it here means the surgical
+// stream-action applier (and `renderStream`) is available app-wide wherever
+// the client router is active, for both the HTTP form path (below) and a
+// live-channel `connectWS` handler.
+import './webjs-stream.js';
+import { renderStream } from './webjs-stream.js';
+
+/** The content type a content-negotiated stream-action response carries (#248). */
+const STREAM_MIME = 'text/vnd.webjs-stream.html';
 
 /**
  * Client router for webjs: nested-layout-aware partial swap.
@@ -227,6 +236,58 @@ export async function navigate(url, opts) {
   await performNavigation(target.href, opts?.replace ?? false, null);
 }
 
+/**
+ * Self-load a `<webjs-frame src>`: fetch `url` as a frame nav and apply the
+ * matching `<webjs-frame id>` subtree into `frameEl` through the EXACT same
+ * frame-swap path a click-driven frame nav uses (`fetchAndApply` with the
+ * frame's id). So the #252 `aria-busy` lifecycle + `webjs:frame-busy` events,
+ * the #249 `webjs:navigation-error` recovery, the keyed reconciler, and the
+ * `webjs:frame-missing` fallback all apply for free; a `src` self-load and a
+ * click that targets the same frame produce identical DOM.
+ *
+ * This is NOT a page navigation: it records no history entry, takes no page
+ * snapshot, and shows no optimistic loading skeleton (it swaps one region, not
+ * the page). It runs under a fresh nav token + AbortController so it interleaves
+ * safely with real navigations and with a superseding `src` change on the same
+ * frame (the later load's token wins; the earlier one's teardown never clears
+ * the newer load's busy state, see `frameBusyTokens`).
+ *
+ * Called only by `<webjs-frame>` itself (`webjs-frame.js`), which owns the
+ * no-double-load guard (eager connect vs lazy-viewport vs a `src` mutation).
+ *
+ * @param {Element} frameEl  The live `<webjs-frame>` element to fill.
+ * @param {string} url  The `src` value, resolved against `location.href`.
+ * @returns {Promise<{ ok: boolean, status: number | null, aborted: boolean }>}
+ */
+export async function loadFrame(frameEl, url) {
+  if (typeof location === 'undefined') return { ok: false, status: null, aborted: false };
+  const id = frameEl && /** @type any */ (frameEl).id;
+  if (!id) return { ok: false, status: null, aborted: false };
+  const target = new URL(url, location.href);
+  // Cross-origin can't be a same-document frame swap (and a frame fetch must
+  // send a same-origin credentialed request). Leave the frame unchanged.
+  if (target.origin !== location.origin) return { ok: false, status: null, aborted: false };
+
+  // A frame self-load shares the global abort + token machinery so a real
+  // navigation that starts mid-load supersedes it (and vice versa), exactly
+  // like a click-driven frame nav routed through performNavigation.
+  if (activeAbortController) activeAbortController.abort();
+  activeAbortController = new AbortController();
+  const signal = activeAbortController.signal;
+  const myToken = ++currentNavigationToken;
+
+  return fetchAndApply(
+    target.href,
+    id,
+    /* recordHistory */ false,
+    /* optimisticState */ null,
+    'GET',
+    /* body */ null,
+    signal,
+    myToken,
+  );
+}
+
 /**
  * Invalidate a cached snapshot. Call after a server action mutates data
  * that affects a cached page so the next visit refetches.
@@ -288,10 +349,11 @@ function onClick(e) {
   if (NON_HTML_EXTENSIONS.test(url.pathname)) return;
 
   e.preventDefault();
-  // Identify the active <webjs-frame> via closest(), returning null if the
-  // click wasn't inside any frame. The frame escape-hatch takes precedence
-  // over the auto-derived layout markers when both are present.
-  const frameId = activeFrameId(anchor);
+  // Resolve the target frame. An explicit `data-webjs-frame` on (or above)
+  // the anchor drives a frame by id from anywhere in the document (an
+  // external sidebar/nav link), `_top` breaks out to a full-page nav, and
+  // absence falls back to the closest enclosing frame (today's default).
+  const frameId = resolveTargetFrameId(anchor);
   performNavigation(href, false, frameId);
 }
 
@@ -355,8 +417,11 @@ function onSubmit(e) {
   const body = buildSubmitFormData(form, submitter);
 
   e.preventDefault();
-  const frameId = activeFrameId(form);
-  performSubmission(url.href, method, body, frameId);
+  // Resolve the target frame for the submit, same precedence as a link:
+  // an explicit `data-webjs-frame` on (or above) the form or its submitter
+  // wins, `_top` breaks out, absence falls back to the enclosing frame.
+  const frameId = resolveTargetFrameId(submitter || form);
+  performSubmission(url.href, method, body, frameId, form);
 }
 
 /**
@@ -451,6 +516,89 @@ function activeFrameId(el) {
   return null;
 }
 
+/**
+ * The reserved `data-webjs-frame` token that forces a full-page navigation,
+ * breaking OUT of any enclosing frame (Turbo's `data-turbo-frame="_top"`).
+ * `resolveTargetFrameId` returns this sentinel; callers treat it exactly
+ * like "no frame" (a normal layout-marker / full-body swap), so a trigger
+ * physically nested in a frame escapes the frame swap. Distinct from `null`
+ * only inside `resolveTargetFrameId` (where `null` would otherwise fall back
+ * to the enclosing frame); both reach `performNavigation` as a frameless
+ * nav, so they behave identically downstream.
+ */
+const FRAME_TOP = '_top';
+
+/**
+ * Resolve which `<webjs-frame>` (if any) a trigger drives, honoring an
+ * explicit `data-webjs-frame` attribute before the closest-enclosing-frame
+ * default. Models Turbo's `data-turbo-frame` external targeting:
+ *
+ *   - `data-webjs-frame="<id>"` on (or above) the trigger drives the frame
+ *     with that id, resolved via `getElementById` in the CURRENT document.
+ *     This lets an EXTERNAL link / form (a sidebar, a filter form) drive a
+ *     content frame it is NOT DOM-nested in. If the id does not resolve to a
+ *     live `<webjs-frame>`, we warn ONCE and fall back to a normal full nav
+ *     (the fail-safe posture: never throw, never silently swap the wrong
+ *     region).
+ *   - `data-webjs-frame="_top"` forces a full-page navigation even when the
+ *     trigger is inside a frame, returning `null` so the swap escapes to the
+ *     layout-marker / full-body path.
+ *   - No `data-webjs-frame` keeps today's behavior: the innermost enclosing
+ *     frame via `activeFrameId`.
+ *
+ * Resolution precedence: explicit `data-webjs-frame` > closest enclosing
+ * frame. The attribute is read with `closest('[data-webjs-frame]')` so it
+ * may live on the trigger itself or any ancestor (e.g. a `<nav>` wrapping a
+ * set of links that all target one frame).
+ *
+ * @param {Element | null} trigger
+ * @returns {string | null}  A frame id to swap, or null for a full nav.
+ */
+function resolveTargetFrameId(trigger) {
+  if (!trigger) return null;
+  const carrier = trigger.closest && trigger.closest('[data-webjs-frame]');
+  const explicit = carrier
+    ? (/** @type {HTMLElement} */ (carrier).dataset
+        ? /** @type {HTMLElement} */ (carrier).dataset.webjsFrame
+        : carrier.getAttribute('data-webjs-frame'))
+    : null;
+  if (explicit != null && explicit !== '') {
+    if (explicit === FRAME_TOP) {
+      // Break out: a full-page nav, never a frame swap.
+      return null;
+    }
+    // External targeting by id. Resolve in the current document.
+    const el = typeof document !== 'undefined' ? document.getElementById(explicit) : null;
+    if (el && el.tagName && el.tagName.toLowerCase() === 'webjs-frame') {
+      return explicit;
+    }
+    // Unresolvable id: warn once, fall back to a normal full nav so the
+    // click still works rather than swapping nothing or the wrong region.
+    warnOnce(
+      `webjs:frame-unresolved:${explicit}`,
+      `[webjs] data-webjs-frame="${explicit}" did not match a live <webjs-frame id="${explicit}">; performing a normal navigation instead.`,
+    );
+    return null;
+  }
+  // No explicit target: today's closest-enclosing-frame default.
+  return activeFrameId(trigger);
+}
+
+/**
+ * Emit a `console.warn` at most once per `key` for the lifetime of the
+ * page, so a repeated misconfiguration (a stale `data-webjs-frame` clicked
+ * many times) does not spam the console.
+ *
+ * @type {Set<string>}
+ */
+const warnedKeys = new Set();
+/** @param {string} key @param {string} message */
+function warnOnce(key, message) {
+  if (warnedKeys.has(key)) return;
+  warnedKeys.add(key);
+  if (typeof console !== 'undefined' && console.warn) console.warn(message);
+}
+
 /* ====================================================================
  * Marker discovery (the heart of the partial-swap mechanism)
  * ==================================================================== */
@@ -693,12 +841,29 @@ async function performNavigation(href, isPopState, frameId) {
  * been server-side-mutated by this submission; refusing to clear would
  * serve stale content on subsequent back/forward.
  *
+ * Submission-state events + aria-busy: while the enhanced submission fetch
+ * is in flight the router sets `aria-busy="true"` on the FORM element and
+ * dispatches `webjs:submit-start` (detail `{ form, url }`); on EVERY settle
+ * path (success swap, validation re-render, navigation error, abort by a
+ * superseding submit/nav) it clears `aria-busy` and dispatches
+ * `webjs:submit-end` (detail `{ form, url, ok }`, `ok` = the submission was
+ * not an error outcome). The toggle uses the same nav-token guard the
+ * `<webjs-frame>` busy state uses (`formBusyTokens` / `markFormBusy` /
+ * `clearFormBusy`): a superseded submit's teardown never clears the busy
+ * state a NEWER submit already set, so a rapid re-submit stays busy until the
+ * live submission settles. The native `aria-busy` attribute on the form is
+ * the readable "is this form submitting" primitive (any component can read
+ * it); the events are the push-notification counterpart. Progressive
+ * enhancement: with JS off this whole code path is skipped and the form is a
+ * plain POST.
+ *
  * @param {string} href     Absolute target URL.
  * @param {string} method   Lowercased HTTP verb.
  * @param {FormData} body
  * @param {string | null} frameId
+ * @param {HTMLFormElement | null} [form]  The submitted form, for busy + events.
  */
-async function performSubmission(href, method, body, frameId) {
+async function performSubmission(href, method, body, frameId, form) {
   if (activeAbortController) activeAbortController.abort();
   activeAbortController = new AbortController();
   const signal = activeAbortController.signal;
@@ -729,8 +894,17 @@ async function performSubmission(href, method, body, frameId) {
 
   const optimisticState = applyOptimisticLoading();
 
+  // Submission-state lifecycle: mark the form busy + announce the start, then
+  // clear + announce the settle in the finally so EVERY exit (success,
+  // validation re-render, navigation error, abort by a superseding submit)
+  // balances the pair. `ok` is filled from the fetch outcome; an abort or a
+  // teardown that never reached the fetch settles ok:false. The token guard
+  // (markFormBusy/clearFormBusy) keeps a superseded submit's teardown from
+  // clearing the busy state a newer submit set.
+  const busyForm = form ? markFormBusy(form, myToken, url.href) : null;
+  let outcomeOk = false;
   try {
-    await fetchAndApply(
+    const outcome = await fetchAndApply(
       url.href,
       frameId,
       /* recordHistory */ true,
@@ -740,6 +914,7 @@ async function performSubmission(href, method, body, frameId) {
       signal,
       myToken,
     );
+    outcomeOk = !!(outcome && outcome.ok);
     // Mutating submissions invalidate cached versions of other URLs -
     // do this *after* the response applies so the new page itself is
     // snapshotted on the next nav, not pre-emptively wiped. Clear the
@@ -750,6 +925,7 @@ async function performSubmission(href, method, body, frameId) {
       prefetchCache.clear();
     }
   } finally {
+    if (busyForm) clearFormBusy(busyForm, myToken, url.href, outcomeOk);
     if (navigatingFlagTimer) clearTimeout(navigatingFlagTimer);
     if (myToken === currentNavigationToken) {
       document.documentElement.removeAttribute('data-navigating');
@@ -1154,6 +1330,91 @@ function refreshPrefetchObservers() {
   }
 }
 
+/**
+ * Render the minimal default in-place error surface into the deepest
+ * shared layout children slot, so the SPA shell (outer chrome, nav,
+ * scroll, focus, client state) survives a failed navigation instead of
+ * being destroyed by a full reload. Returns true when it rendered into a
+ * slot, false when no shared layout marker exists (a cross-document nav).
+ * On a false return the caller may fall back to a hard load as a last
+ * resort.
+ *
+ * @param {number | null} status  HTTP status of the failed response, or null for a transport/parse failure.
+ * @returns {boolean}
+ */
+function renderInPlaceNavError(status) {
+  if (typeof document === 'undefined' || !document.body) return false;
+  const here = collectChildrenSlots(document.body);
+  // The deepest slot is the same swap target a normal partial swap writes
+  // to (longest path wins), so the outer chrome / nav are preserved.
+  /** @type {{ start: Comment, end: Comment } | undefined} */
+  let deepest;
+  let deepestPathLen = -1;
+  for (const [path, slot] of here) {
+    if (path.length > deepestPathLen) { deepestPathLen = path.length; deepest = slot; }
+  }
+  if (!deepest) return false;
+  const liveParent = deepest.start.parentNode;
+  if (!liveParent || deepest.start.parentNode !== deepest.end.parentNode) return false;
+
+  const alert = document.createElement('div');
+  alert.setAttribute('role', 'alert');
+  alert.setAttribute('data-webjs-nav-error', '');
+  const msg = status
+    ? `This page could not be loaded. (status ${status})`
+    : 'This page could not be loaded.';
+  alert.textContent = msg;
+
+  // Replace the slot contents with the alert.
+  const range = document.createRange();
+  range.setStartAfter(deepest.start);
+  range.setEndBefore(deepest.end);
+  range.deleteContents();
+  liveParent.insertBefore(alert, deepest.end);
+  return true;
+}
+
+/**
+ * Shared fallback for a non-HTML error response or a transport/parse
+ * failure during a client navigation. Dispatches a cancelable
+ * `webjs:navigation-error` event on `document` (matching the
+ * `webjs:frame-missing` / `webjs:prefetch` dispatch convention) so the
+ * app can recover in place. If the app calls `preventDefault()`, the
+ * router does NOTHING further and leaves the current page exactly as it
+ * is. Otherwise it renders a minimal in-place `role="alert"` surface into
+ * the deepest layout children slot (the SPA shell survives), and only
+ * hard-navigates as a last resort when no in-place target exists.
+ *
+ * Never call this for an AbortError: a superseding nav is a normal
+ * supersede, not an error, and must not surface a navigation-error.
+ *
+ * @param {string} href  The URL that failed to navigate to.
+ * @param {number | null} status  HTTP status when a response arrived, else null.
+ * @param {Error | null} error  The Error for a transport/parse failure, else null.
+ */
+function handleNavigationError(href, status, error) {
+  const evt = new CustomEvent('webjs:navigation-error', {
+    bubbles: true,
+    cancelable: true,
+    detail: { url: href, status: status == null ? null : status, error: error || null },
+  });
+  // Guard the dispatch: a throwing app listener must not wedge the nav engine.
+  if (typeof document !== 'undefined') {
+    try { document.dispatchEvent(evt); } catch { /* a buggy listener cannot break recovery */ }
+  }
+  // The app owns recovery: leave the page untouched (shell, scroll, focus,
+  // client state all preserved). No reload, no render.
+  if (evt.defaultPrevented) return;
+  // Default: render a minimal in-place error surface so the SPA is not
+  // destroyed and the user is not sent to a second failing round-trip.
+  if (renderInPlaceNavError(status)) return;
+  // Last resort only: no shared layout marker to render into (a genuine
+  // cross-document nav). Fall back to a hard load so an unrecoverable case
+  // is not a silent dead-end. This is the exception, reached only after
+  // the event was not cancelled AND no in-place target exists.
+  if (typeof location !== 'undefined') location.href = href;
+}
+
 /**
  * Fetch the target URL and apply the swap.
  *
@@ -1163,16 +1424,35 @@ function refreshPrefetchObservers() {
  * @param {{ slot: { start: Comment, end: Comment }, oldChildren: Node[], token: number } | null} optimisticState
  * @param {string} [method]  HTTP verb (uppercase). Default 'GET'.
  * @param {BodyInit | null} [body]  Request body for non-GET methods.
- * @param {AbortSignal | null} [signal]  Abort signal - newer nav cancels this fetch.
+ * @param {AbortSignal | null} [signal]  Abort signal. A newer nav cancels this fetch.
  * @param {number} [token]  Nav-token captured at the caller's entry; stale → skip apply.
+ * @returns {Promise<{ ok: boolean, status: number | null, aborted: boolean }>}
+ *   The fetch outcome, so a caller (the form-submission busy/event lifecycle)
+ *   can report whether the submission settled as a success, an error, or an
+ *   abort. `ok` mirrors `response.ok` for an HTTP response (a 422 validation
+ *   re-render is `ok:false`), `false` for a transport/parse error, and `false`
+ *   for an abort (which also sets `aborted:true`). `status` is the HTTP status
+ *   or `null` when the request never produced one.
  */
 async function fetchAndApply(href, frameId, recordHistory, optimisticState, method, body, signal, token) {
   method = method || 'GET';
   const myToken = typeof token === 'number' ? token : currentNavigationToken;
   let html;
   let incomingBuild = null;
+  /** @type {number | null} */
+  let respStatus = null;
+  /** @type {boolean} */
+  let respOk = false;
   /** @type {string} */
   let finalUrl = href;
+  // aria-busy lifecycle: when this nav targets a <webjs-frame>, mark the
+  // live frame busy for the duration of its fetch+apply so assistive tech
+  // can announce it and CSS can style `webjs-frame[aria-busy="true"]`. The
+  // outer try/finally guarantees the busy state is cleared on EVERY exit
+  // (success swap, frame-missing, an HTTP/transport error, an abort by a
+  // newer nav), never leaving a frame stuck busy.
+  const busyFrame = frameId ? markFrameBusy(frameId, myToken) : null;
+  try {
   try {
     // Warm-cache fast path: a hover/focus/viewport prefetch may have
     // already fetched this exact page (same X-Webjs-Have shell). Consume
@@ -1185,11 +1465,21 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
       html = prefetched.html;
       incomingBuild = prefetched.build;
       finalUrl = prefetched.finalUrl;
+      // A consumed prefetch is a successful 200 GET fragment.
+      respStatus = 200;
+      respOk = true;
     } else {
     const headers = { 'x-webjs-router': '1' };
     const have = buildHaveHeader();
     if (have) headers['x-webjs-have'] = have;
     if (frameId) headers['x-webjs-frame'] = frameId;
+    // Content-negotiate a stream-action response on a write submission (a
+    // non-GET body). The server returns the stream MIME only when this Accept
+    // is present, so with JS off (no router, no Accept) the same form gets a
+    // normal render/redirect: the grammar is additive and PE-safe (#248).
+    if (body != null && method !== 'GET' && method !== 'HEAD') {
+      headers['accept'] = STREAM_MIME + ', text/html';
+    }
 
     /** @type {RequestInit} */
     const init = { method, headers, credentials: 'same-origin' };
@@ -1197,8 +1487,26 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     if (body != null && method !== 'GET' && method !== 'HEAD') init.body = body;
 
     const resp = await fetch(href, init);
+    respStatus = resp.status;
+    respOk = resp.ok;
     const ctype = resp.headers.get('content-type') || '';
     const isHTML = /^text\/html\b/i.test(ctype);
+    const isStream = ctype.toLowerCase().indexOf(STREAM_MIME) === 0;
+    // Stream-action response (#248): the body is `<webjs-stream>` elements
+    // applied surgically to the live DOM, NOT a region swap. Apply them and
+    // return; do not parse the body as a page document (it has no shell). A
+    // stream body of any status is fine. This runs BEFORE the !isHTML branch
+    // so the non-text/html stream MIME is not treated as a navigation error.
+    if (isStream) {
+      const text = await resp.text();
+      if (myToken === currentNavigationToken) {
+        // Roll back any optimistic loading skeleton: a stream response patches
+        // the page in place, it does not swap the region the skeleton covered.
+        restoreOptimistic(optimisticState);
+        renderStream(text);
+      }
+      return { ok: respOk, status: respStatus, aborted: false };
+    }
     // Server-side redirect (PRG, auth-gate, etc.): fetch followed it
     // automatically. Record the FINAL URL in history, not the
     // originally-requested one, so back/forward + bookmarking work.
@@ -1213,16 +1521,27 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
       if (myToken === currentNavigationToken && recordHistory) {
         history.pushState(null, '', finalUrl);
       }
-      return;
+      return { ok: respOk, status: respStatus, aborted: false };
     }
 
-    // Non-HTML response (JSON error, file download, opaque): let the
-    // browser handle it. Same for non-OK responses that aren't HTML
-    // (a 500 returning `{"error": "..."}` shouldn't be rendered as a
-    // page).
+    // Non-HTML response (JSON error, file download, opaque): can't be
+    // rendered as a page (a 500 returning `{"error": "..."}` is not an
+    // HTML page). Instead of abandoning the SPA with a full reload (which
+    // discards the partial-swap shell, scroll, and in-flight state, and
+    // eats a second round-trip that may itself fail), dispatch a
+    // cancelable `webjs:navigation-error` so the app can recover in place;
+    // by default render a minimal in-place error surface. The adjacent
+    // HTML-status branch below already renders 4xx/5xx HTML bodies in
+    // place; this closes the same gap for a non-HTML error body.
     if (!isHTML) {
-      if (myToken === currentNavigationToken) location.href = href;
-      return;
+      if (myToken === currentNavigationToken) {
+        // Roll back any optimistic loading skeleton FIRST, so a
+        // preventDefault()-ing app sees the page exactly as it was (the catch
+        // block below does the same for a transport failure).
+        restoreOptimistic(optimisticState);
+        handleNavigationError(href, resp.status, null);
+      }
+      return { ok: false, status: respStatus, aborted: false };
     }
 
     // HTML body of ANY status: 2xx, 4xx validation errors, 5xx error
@@ -1240,22 +1559,31 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     html = await resp.text();
     }
   } catch (err) {
-    // Aborted by a newer navigation: let it run, don't fall back.
-    if (err && /** @type any */ (err).name === 'AbortError') return;
-    // Stale (a newer nav started before we got the network error) -
-    // the newer nav owns the page now; don't clobber it.
-    if (myToken !== currentNavigationToken) return;
+    // Aborted by a newer navigation: let it run, don't fall back. An
+    // AbortError is a normal supersede, NOT a navigation error, so it must
+    // NEVER dispatch webjs:navigation-error (the key no-false-positive
+    // line).
+    if (err && /** @type any */ (err).name === 'AbortError') return { ok: false, status: null, aborted: true };
+    // Stale (a newer nav started before we got the network error): the
+    // newer nav owns the page now, so don't clobber it.
+    if (myToken !== currentNavigationToken) return { ok: false, status: null, aborted: true };
     restoreOptimistic(optimisticState);
-    location.href = href;
-    return;
+    // Transport/parse failure (fetch rejected, e.g. offline / DNS / TLS).
+    // Surface a navigation-error so the app can recover in place instead
+    // of a destructive full reload.
+    handleNavigationError(href, null, err instanceof Error ? err : new Error(String(err)));
+    return { ok: false, status: null, aborted: false };
   }
 
   // A newer navigation started while we awaited the response body -
   // bail before we overwrite its work.
-  if (myToken !== currentNavigationToken) return;
+  if (myToken !== currentNavigationToken) return { ok: false, status: respStatus, aborted: true };
 
   const doc = parseHTML(html);
-  if (!doc) { location.href = href; return; }
+  // The body claimed text/html but didn't parse into a document (a
+  // malformed/empty HTML body). Surface a navigation-error so the app can
+  // recover in place rather than a destructive full reload.
+  if (!doc) { restoreOptimistic(optimisticState); handleNavigationError(href, null, new Error('navigation response did not parse as HTML')); return { ok: false, status: respStatus, aborted: false }; }
 
   applySwap(doc, frameId, false, finalUrl, incomingBuild);
 
@@ -1283,6 +1611,164 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
   }
 
   document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url: finalUrl, frameId, from: 'navigate' } }));
+  return { ok: respOk, status: respStatus, aborted: false };
+  } finally {
+    // Clear the frame's busy state on every exit path (the early returns
+    // above all unwind through here). No-op when this was not a frame nav.
+    if (busyFrame) clearFrameBusy(busyFrame, myToken);
+  }
+}
+
+/**
+ * The nav token that currently OWNS each frame's busy state. Under two rapid
+ * frame navs the router aborts the first; its `finally` would otherwise clear
+ * `aria-busy` that the SECOND nav already re-set, leaving the frame falsely
+ * idle while still loading (and an unbalanced busy-event stream). A clear only
+ * fires when its token still owns the frame, so the superseding nav's busy
+ * state survives the aborted nav's teardown.
+ *
+ * @type {WeakMap<Element, number>}
+ */
+const frameBusyTokens = new WeakMap();
+
+/**
+ * Set `aria-busy="true"` on the live `<webjs-frame id>` element and announce
+ * the start of its load with a bubbling `webjs:frame-busy` event (detail
+ * `{ frameId, busy: true }`), mirroring Turbo's `frame.markAsBusy`. Stamps the
+ * nav `token` as the frame's busy owner (see `frameBusyTokens`). Returns the
+ * resolved frame element so `clearFrameBusy` can target the SAME node even if
+ * the swap later replaces the frame's id lookup (the element identity is stable
+ * across a child-only frame swap). Returns null when the frame is not in the
+ * live DOM (e.g. a stale external `data-webjs-frame` that slipped the
+ * resolve-time check), so nothing to mark.
+ *
+ * @param {string} frameId
+ * @param {number} token
+ * @returns {Element | null}
+ */
+function markFrameBusy(frameId, token) {
+  if (typeof document === 'undefined') return null;
+  let frame = null;
+  try {
+    frame = document.querySelector(`webjs-frame#${CSS.escape(frameId)}`);
+  } catch { frame = document.getElementById(frameId); }
+  if (!frame) return null;
+  // Dispatch the `true` edge only on a real idle -> busy transition, so a nav
+  // that supersedes an in-flight one (frame already busy) does not emit a
+  // redundant `true`. The token always advances to the newest owner.
+  const wasBusy = frameBusyTokens.has(frame);
+  frameBusyTokens.set(frame, token);
+  frame.setAttribute('aria-busy', 'true');
+  if (!wasBusy) {
+    frame.dispatchEvent(new CustomEvent('webjs:frame-busy', {
+      bubbles: true,
+      detail: { frameId, busy: true },
+    }));
+  }
+  return frame;
+}
+
+/**
+ * Clear the busy state set by `markFrameBusy`: set `aria-busy="false"` and
+ * dispatch the matching `webjs:frame-busy` (detail `{ frameId, busy: false }`)
+ * so app code sees a symmetric start/finish pair. Mirrors Turbo's
+ * `frame.clearBusyState`. Operates on the element captured at start, so an
+ * abort / error clears the same node the start marked. A clear whose token no
+ * longer owns the frame (a newer nav re-set busy) is a stale teardown from a
+ * superseded nav and is skipped, so the live nav stays busy.
+ *
+ * @param {Element} frame
+ * @param {number} token
+ */
+function clearFrameBusy(frame, token) {
+  if (frameBusyTokens.get(frame) !== token) return;
+  frameBusyTokens.delete(frame);
+  frame.setAttribute('aria-busy', 'false');
+  const frameId = frame.id || null;
+  frame.dispatchEvent(new CustomEvent('webjs:frame-busy', {
+    bubbles: true,
+    detail: { frameId, busy: false },
+  }));
+}
+
+/**
+ * The nav token that currently OWNS each form's submission-busy state. Same
+ * role as `frameBusyTokens` for frames: under two rapid submits the router
+ * aborts the first, and its `finally` would otherwise clear `aria-busy` /
+ * dispatch `webjs:submit-end` for a submission the SECOND submit already
+ * re-set, leaving the form falsely idle while still submitting (and an
+ * unbalanced start/end event stream). A clear only fires when its token still
+ * owns the form, so the superseding submit's busy state survives the aborted
+ * submit's teardown.
+ *
+ * @type {WeakMap<Element, number>}
+ */
+const formBusyTokens = new WeakMap();
+
+/**
+ * Mark a submitting `<form>` busy: set the native `aria-busy="true"` (the
+ * readable "is this form submitting" primitive any component can poll) and
+ * dispatch a bubbling `webjs:submit-start` event (detail `{ form, url }`).
+ * Stamps `token` as the form's busy owner (see `formBusyTokens`). The `true`
+ * edge fires only on a real idle -> busy transition, so a submit that
+ * supersedes an in-flight one (form already busy) does not emit a redundant
+ * start; the token always advances to the newest owner. Returns the form so
+ * `clearFormBusy` targets the same node.
+ *
+ * @param {HTMLFormElement} form
+ * @param {number} token
+ * @param {string} url   Resolved action URL the submission targets.
+ * @returns {HTMLFormElement}
+ */
+function markFormBusy(form, token, url) {
+  const wasBusy = formBusyTokens.has(form);
+  formBusyTokens.set(form, token);
+  form.setAttribute('aria-busy', 'true');
+  if (!wasBusy) {
+    form.dispatchEvent(new CustomEvent('webjs:submit-start', {
+      bubbles: true,
+      detail: { form, url },
+    }));
+  }
+  return form;
+}
+
+/**
+ * Clear the busy state set by `markFormBusy`: set `aria-busy="false"` and
+ * dispatch the matching `webjs:submit-end` (detail `{ form, url, ok }`, `ok` =
+ * the submission settled as a success / not an error outcome) so app code sees
+ * a symmetric start/finish pair. Operates on the element captured at start, so
+ * an abort / error clears the same node the start marked. A clear whose token
+ * no longer owns the form (a newer submit re-set busy) is a stale teardown
+ * from a superseded submit and is skipped, so the live submit stays busy.
+ *
+ * @param {HTMLFormElement} form
+ * @param {number} token
+ * @param {string} url
+ * @param {boolean} ok
+ */
+function clearFormBusy(form, token, url, ok) {
+  if (formBusyTokens.get(form) !== token) return;
+  formBusyTokens.delete(form);
+  form.setAttribute('aria-busy', 'false');
+  const evt = new CustomEvent('webjs:submit-end', {
+    bubbles: true,
+    detail: { form, url, ok: !!ok },
+  });
+  // A successful submission swaps the page in place, and a full-body swap
+  // (or a swap whose region contained the form) detaches the form before
+  // this teardown runs. A bubbling event dispatched on a DISCONNECTED node
+  // never reaches a `document`-level listener, so a synchronous swap (the
+  // no-view-transition default) would silently drop `submit-end`. Dispatch
+  // on `document` when the form is no longer connected so the symmetric
+  // start/end pair always lands, regardless of swap timing.
+  if (form.isConnected) {
+    form.dispatchEvent(evt);
+  } else if (typeof document !== 'undefined') {
+    document.dispatchEvent(evt);
+  } else {
+    form.dispatchEvent(evt);
+  }
 }
 
 /**
@@ -1349,6 +1835,207 @@ function trackedReloadSignature(root) {
   return sig;
 }
 
+/* ====================================================================
+ * View Transitions (opt-in) + permanent-element persistence
+ * ==================================================================== */
+
+/**
+ * Whether the current page opts into the native View Transitions API for
+ * client-router swaps. OFF by default (no animation surprise, no
+ * regression for browsers without the API): a transition is purely
+ * opt-in via a `<meta name="view-transition" content="same-origin">` in
+ * the document head, mirroring Turbo's `<meta name="view-transition">`
+ * convention. The accepted opt-in value is `same-origin` (every
+ * client-router swap is same-origin by construction, so it reads as "yes,
+ * animate these in-app navigations"). Any other value, or the meta being
+ * absent, keeps transitions off.
+ *
+ * Re-read per navigation rather than cached: the meta can be added or
+ * removed by a swap (the head merge brings in the new page's head), so a
+ * page can turn transitions on or off as the user navigates.
+ *
+ * @returns {boolean}
+ */
+function viewTransitionsEnabled() {
+  if (typeof document === 'undefined') return false;
+  const meta = document.querySelector('meta[name="view-transition"]');
+  if (!meta) return false;
+  const content = (meta.getAttribute('content') || '').trim().toLowerCase();
+  return content === 'same-origin';
+}
+
+/**
+ * Run a synchronous DOM-mutation thunk, wrapping it in
+ * `document.startViewTransition()` when the page has opted in AND the
+ * browser supports the API. Otherwise the thunk runs synchronously,
+ * byte-identical to the pre-View-Transitions behaviour (no flash, no
+ * regression). The thunk is the SAME swap code in both branches; the
+ * transition only captures the before/after around the mutation (the
+ * fetch already happened, so it is never inside the callback).
+ *
+ * @param {() => void} thunk  The synchronous DOM swap to perform.
+ * @param {() => void} [afterFinished]  Optional post-transition work
+ *   (e.g. re-upgrade custom elements) run when the transition settles; for
+ *   the synchronous fallback it runs immediately after the thunk.
+ */
+function runWithTransition(thunk, afterFinished) {
+  const start = typeof document !== 'undefined'
+    ? /** @type any */ (document).startViewTransition
+    : undefined;
+  if (viewTransitionsEnabled() && typeof start === 'function') {
+    const t = start.call(document, thunk);
+    if (t && t.finished && typeof t.finished.then === 'function') {
+      t.finished.then(() => { if (afterFinished) afterFinished(); }).catch(() => {});
+    } else if (afterFinished) {
+      afterFinished();
+    }
+    return;
+  }
+  thunk();
+  if (afterFinished) afterFinished();
+}
+
+/**
+ * Persist `data-webjs-permanent` elements across a swap by NODE IDENTITY.
+ *
+ * Mirrors Turbo's permanent-element behaviour: an element the author
+ * marks `data-webjs-permanent` (and which carries an `id`) survives a
+ * destructive swap as the SAME live DOM node, so a playing
+ * `<audio>` / `<video>`, a live widget, an open menu, or any element with
+ * accumulated JS state keeps running across the navigation instead of
+ * being destroyed and re-created from the incoming HTML.
+ *
+ * The mechanism runs BEFORE the destructive `replaceChildren` / range
+ * delete: for each `[data-webjs-permanent][id]` in the CURRENT subtree, if
+ * the INCOMING tree has a matching `#id`, the live current node is MOVED
+ * into the incoming tree's position (replacing the incoming placeholder).
+ * The subsequent swap then ADOPTS the live node (it is already part of the
+ * incoming tree) rather than destroying the current one. The keyed
+ * reconciler matches it by id afterwards and leaves it in place.
+ *
+ * Guards (correctness):
+ *   - both-exist: only regraft an id present in BOTH the current and
+ *     incoming subtree. An id in the current but NOT the incoming is being
+ *     removed; leave it (do not force it to persist).
+ *   - current-is-permanent: only move when the CURRENT node actually
+ *     carries `data-webjs-permanent` (an incoming `#id` that resolves to a
+ *     non-permanent current element is left untouched).
+ *   - boundary-respecting: the live node is placed exactly where the
+ *     incoming document puts it, so it never escapes a frame/region.
+ *
+ * @param {ParentNode} currentRoot   The live subtree being swapped out.
+ * @param {ParentNode} incomingRoot  The incoming subtree being swapped in.
+ */
+function regraftPermanentElements(currentRoot, incomingRoot) {
+  if (!currentRoot || !incomingRoot) return;
+  if (typeof currentRoot.querySelectorAll !== 'function') return;
+  const permanents = currentRoot.querySelectorAll('[data-webjs-permanent][id]');
+  for (const live of permanents) {
+    const id = live.id;
+    if (!id) continue;
+    // both-exist guard: the incoming subtree must carry a matching #id.
+    let placeholder = null;
+    try {
+      placeholder = incomingRoot.querySelector(`#${CSS.escape(id)}`);
+    } catch { placeholder = null; }
+    if (!placeholder) continue;
+    // current-is-permanent guard is implicit in the selector above, but
+    // re-assert defensively (the live node is the one we move).
+    if (!live.hasAttribute || !live.hasAttribute('data-webjs-permanent')) continue;
+    const parent = placeholder.parentNode;
+    if (!parent) continue;
+    // Move the LIVE node into the incoming tree's position, replacing the
+    // incoming placeholder. The swap then adopts the live node.
+    if (placeholder === live) continue;
+    parent.replaceChild(live, placeholder);
+  }
+}
+
+/**
+ * Permanent-element regraft for the marker-range path, where the two
+ * sides are ARRAYS of sibling nodes (the live slice between markers, and
+ * the imported-but-detached incoming slice) rather than single roots.
+ *
+ * For each `[data-webjs-permanent][id]` reachable from the LIVE slice, if
+ * a matching `#id` exists anywhere in the INCOMING slice, replace the
+ * incoming (freshly-imported) copy with the LIVE node so the reconciler
+ * adopts the live node by identity. Searches both top-level slice members
+ * and their descendants. The same both-exist + current-is-permanent
+ * guards as `regraftPermanentElements` apply.
+ *
+ * @param {Node[]} liveSlice
+ * @param {Node[]} incomingSlice
+ */
+function regraftPermanentInSlice(liveSlice, incomingSlice) {
+  /** @type {Element[]} */
+  const livePermanents = [];
+  for (const n of liveSlice) {
+    if (n.nodeType !== 1) continue;
+    const el = /** @type {Element} */ (n);
+    if (el.hasAttribute && el.hasAttribute('data-webjs-permanent') && el.id) {
+      livePermanents.push(el);
+    }
+    if (typeof el.querySelectorAll === 'function') {
+      for (const d of el.querySelectorAll('[data-webjs-permanent][id]')) livePermanents.push(d);
+    }
+  }
+  if (!livePermanents.length) return;
+
+  for (const live of livePermanents) {
+    const id = live.id;
+    if (!id) continue;
+    const placeholder = findInSlice(incomingSlice, id);
+    if (!placeholder) continue; // both-exist guard
+    if (placeholder === live) continue;
+    const parent = placeholder.parentNode;
+    if (parent) {
+      parent.replaceChild(live, placeholder);
+    } else {
+      // Placeholder is a top-level slice member with no parent (detached):
+      // replace it in the incomingSlice array so the reconciler inserts the
+      // live node in that position.
+      const idx = incomingSlice.indexOf(placeholder);
+      if (idx !== -1) incomingSlice[idx] = live;
+    }
+  }
+}
+
+/**
+ * Find an element with `#id` within an array of (possibly detached)
+ * sibling nodes, searching each member and its descendants.
+ *
+ * @param {Node[]} slice
+ * @param {string} id
+ * @returns {Element | null}
+ */
+function findInSlice(slice, id) {
+  for (const n of slice) {
+    if (n.nodeType !== 1) continue;
+    const el = /** @type {Element} */ (n);
+    if (el.id === id) return el;
+    if (typeof el.querySelector === 'function') {
+      let match = null;
+      try { match = el.querySelector(`#${CSS.escape(id)}`); } catch { match = null; }
+      if (match) return match;
+    }
+  }
+  return null;
+}
+
+/**
+ * Re-upgrade custom elements between a marker pair after a transitioned
+ * swap settles. The View Transitions API snapshots and replaces DOM, so
+ * elements can need a re-upgrade once the animation finishes.
+ *
+ * @param {{ start: Comment, end: Comment } | undefined} range
+ */
+function upgradeCustomElementsInRange(range) {
+  if (!range || !range.start) return;
+  for (let n = range.start.nextSibling; n && n !== range.end; n = n.nextSibling) {
+    if (n.nodeType === 1) upgradeCustomElements(/** @type {Element} */ (n));
+  }
+}
+
 function applySwap(doc, frameId, revalidating, href, incomingBuild) {
   // Any clean swap (no importmap mismatch, including cache restores
   // and frame swaps where we don't even run the mismatch check) is a
@@ -1466,11 +2153,17 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild) {
       // (Tailwind CSS injection, etc.) that the outer layout's scripts
       // already produced.
       addNewHeadElements(doc.head);
-      diffChildren(target, source);
-      reactivateScripts(target);
-      upgradeCustomElements(target);
+      // `diffChildren` -> `reconcileChildren` regrafts permanent elements
+      // by node identity (it imports the incoming children first, then
+      // swaps the live permanent node into the imported tree), so the live
+      // `<audio>`/widget keeps running across the frame swap.
+      runWithTransition(() => {
+        diffChildren(target, source);
+        reactivateScripts(target);
+        upgradeCustomElements(target);
+        blurOutgoingFocus();
+      }, () => upgradeCustomElements(target));
       forwardSuspenseResolvers(doc.body);
-      blurOutgoingFocus();
       return;
     }
     // The response did not carry the requested frame (source null), or the
@@ -1501,15 +2194,22 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild) {
     // ADD-ONLY head merge for the same reason: outer layout stays
     // mounted, its head-bound runtime state must not be invalidated.
     addNewHeadElements(doc.head);
-    swapMarkerRange(here.get(sharedPath), there.get(sharedPath), doc);
+    runWithTransition(() => {
+      swapMarkerRange(here.get(sharedPath), there.get(sharedPath), doc);
+      blurOutgoingFocus();
+    }, () => upgradeCustomElementsInRange(here.get(sharedPath)));
     forwardSuspenseResolvers(doc.body);
-    blurOutgoingFocus();
     return;
   }
 
   // 3. Full body swap fallback. Use full head merge: different root
   // layout, so stale head elements should be removed.
   mergeHead(doc.head);
+  // Persist permanent elements by node identity across the full-body
+  // swap: move each live [data-webjs-permanent][id] node into the matching
+  // position in the incoming body BEFORE replaceChildren reads it, so the
+  // live node is adopted rather than destroyed.
+  regraftPermanentElements(document.body, doc.body);
   const newChildren = [...doc.body.childNodes];
   const doSwap = () => {
     document.body.replaceChildren(...newChildren);
@@ -1517,12 +2217,7 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild) {
     upgradeCustomElements(document.body);
     blurOutgoingFocus();
   };
-  if (/** @type any */ (document).startViewTransition) {
-    const t = /** @type any */ (document).startViewTransition(doSwap);
-    t.finished.then(() => upgradeCustomElements(document.body)).catch(() => {});
-  } else {
-    doSwap();
-  }
+  runWithTransition(doSwap, () => upgradeCustomElements(document.body));
 }
 
 /**
@@ -1588,6 +2283,12 @@ function swapMarkerRange(target, source, _doc) {
     incomingSlice.push(document.importNode(n, true));
   }
 
+  // Persist permanent elements by node identity: regraft each live
+  // [data-webjs-permanent][id] node into the matching position in the
+  // imported incoming slice, replacing the freshly-imported copy, so the
+  // keyed reconciler adopts the live node instead of destroying it.
+  regraftPermanentInSlice(liveSlice, incomingSlice);
+
   // Run the keyed diff.
   reconcileSiblings(liveParent, target.start, target.end, liveSlice, incomingSlice);
 
@@ -1675,6 +2376,12 @@ function reconcileSiblings(parent, startMarker, endMarker, live, incoming) {
  * @param {Element} src  The element to copy from (incoming HTML).
  */
 function diffElementInPlace(dst, src) {
+  // A regrafted `data-webjs-permanent` node is the SAME node on both
+  // sides (the live node was moved into the incoming tree). Diffing it
+  // against itself would recurse into its own children and re-import
+  // them; instead leave it exactly as the user left it (that is the whole
+  // point of permanence).
+  if (dst === src) return;
   if (dst.tagName !== src.tagName) {
     dst.replaceWith(src);
     return;
@@ -1713,6 +2420,15 @@ function reconcileChildren(dst, src) {
   const liveChildren = [...dst.childNodes];
   const incomingChildren = [...src.childNodes].map((n) => document.importNode(n, true));
 
+  // Persist `data-webjs-permanent` elements by node identity: regraft each
+  // live permanent node into the matching position in the freshly-imported
+  // incoming children (replacing the imported copy), so the keyed match
+  // below adopts the LIVE node and the reconciler never recreates it. This
+  // is the in-region (frame + nested) counterpart of the full-body and
+  // marker-range regrafts; running it here covers permanents nested below
+  // the top keyed level too.
+  regraftPermanentInSlice(liveChildren, incomingChildren);
+
   // Build keyed map of live children for reuse.
   /** @type {Map<string, Element>} */
   const keyedLive = new Map();
@@ -2133,6 +2849,12 @@ export {
   reactivateScripts as _reactivateScripts,
   findAnchorInPath as _findAnchorInPath,
   activeFrameId as _activeFrameId,
+  resolveTargetFrameId as _resolveTargetFrameId,
+  FRAME_TOP as _FRAME_TOP,
+  markFrameBusy as _markFrameBusy,
+  clearFrameBusy as _clearFrameBusy,
+  markFormBusy as _markFormBusy,
+  clearFormBusy as _clearFormBusy,
   collectChildrenSlots as _collectChildrenSlots,
   longestSharedPath as _longestSharedPath,
   keyOf as _keyOf,
@@ -2148,6 +2870,10 @@ export {
   buildSubmitFormData as _buildSubmitFormData,
   restoreOptimistic as _restoreOptimistic,
   eligibleAnchorHref as _eligibleAnchorHref,
+  viewTransitionsEnabled as _viewTransitionsEnabled,
+  runWithTransition as _runWithTransition,
+  regraftPermanentElements as _regraftPermanentElements,
+  regraftPermanentInSlice as _regraftPermanentInSlice,
   prefetchSuppressed as _prefetchSuppressed,
   prefetchMode as _prefetchMode,
   prefetch as _prefetch,