@takazudo/zfb 2.22.1 → 3.1.0

package/dist/runtime.js

@@ -20,6 +20,8 @@
 // happy-dom or bare Node, and the absence of `IntersectionObserver` /
 // `requestIdleCallback` / `matchMedia` is handled gracefully.
 import { resolveWhen } from "./types.js";
+import { ROOT_KEY } from "./zudo-react/root.js";
+import { parseProps as parseOwnedProps } from "./zudo-react/props-transport.js";
 const g = globalThis;
 /**
  * Internal variant of `scheduleHydrate` that also reports whether the fire
@@ -195,53 +197,89 @@ const PERSIST_ATTR = "data-zfb-transition-persist";
 // string). Consumed by clearMountedForRemount(). See #1389.
 const ISLAND_REMOUNT_ATTR = "data-zfb-island-remount";
 /**
- * Public DOM signal written after an island's mount function returns.
+ * Public observation marker; the symbol handle is the live-root guard.
  *
- * State table (the marker is observational only and is never a mount guard):
- *
- * - initial: absent; `mountIslands` / `mountNewIslands` strip a marker that is
- *   stale relative to this module instance's `mounted` map before scheduling.
- * - deferred idle / visible / media: absent while the scheduler is waiting.
- * - importing: absent while the URL module is in `pending`.
- * - mounted via URL: `scheduleMount`'s URL success handler writes it only after
- *   `fn(propsForMount, element, mode)` returns, alongside the `mounted` entry.
- * - mounted via inline module: `fireInlineMount` writes it only after
- *   `fn(props, element, mode)` returns, alongside the `mounted` entry.
- * - missing manifest entry: absent; `scheduleMount` returns without writing.
- * - no `mount` export: absent; both manifest paths return without writing.
- * - synchronous mount throw: absent; the `mounted` entry is not written, so a
- *   later walk can retry the element.
- * - rejected import: absent; the URL rejection handler clears `pending` and
- *   any defensive `mounted` entry.
- * - detached during import: absent; the URL success handler clears `pending`
- *   and returns before calling mount.
- * - unmounted (discarded): `unmountIslands` clears the marker and `mounted`
- *   entry in `finally`, even when the unmount thunk throws.
- * - unmounted (persisted-lifted): retained together with the `mounted` entry;
- *   `unmountIslands` skips elements whose persist id exists in the incoming body.
- * - props-changed remount: `clearMountedForRemount` clears the marker and map
- *   entry in `finally`, then the forced mount writes it again after mount returns.
- * - dev hot-swap over a marked DOM: a fresh module's `mountIslands` strips the
- *   stale marker before scheduling, then writes it after its own mount returns.
+ * State table:
+ * - initial/deferred/missing entry/failed mount: marker and handle absent;
+ * - successful mount: both present;
+ * - discarded root: disposal leaves DOM for the body swap, then clears both;
+ * - unchanged island inside a retained persist boundary: handle and marker survive;
+ * - changed island inside a retained boundary: metadata and remount flag are set,
+ *   then the post-swap scan disposes once and mounts in render mode;
+ * - removed island inside a retained boundary: dispose and detach before swap;
+ * - bundle re-import: dispose the old symbol handle before render mode replaces it.
  */
 export const ISLAND_MOUNTED_ATTR = "data-zfb-island-mounted";
-// WeakMap<Element, unmount thunk> — replaces the old WeakSet.
-// Value is a per-element function that calls the bundle's unmount(element)
-// (or a noop if the bundle does not expose one). Used by unmountIslands()
-// to fire framework lifecycle cleanups before a body swap.
-const mounted = new WeakMap();
+const COMPOSITION_KEY = Symbol.for("@takazudo/zfb/zudo-react/composition-v1");
+const TRACKER_KEY = Symbol.for("@takazudo/zfb/zudo-react/composition-tracker-v1");
+// A fresh bundle instance replaces roots installed by a previous instance.
+// Ordinary repeat scans in the same instance keep their live handles.
+const owned = new WeakSet();
+function rootHandle(element) {
+    return element[ROOT_KEY];
+}
+function setRootHandle(element, handle) {
+    const target = element;
+    if (handle)
+        target[ROOT_KEY] = handle;
+    else
+        delete target[ROOT_KEY];
+}
+function reportIslandError(element, phase, error) {
+    const name = element.getAttribute("data-zfb-island") ??
+        element.getAttribute("data-zfb-island-skip-ssr") ??
+        "unknown";
+    try {
+        console.error(`[zfb] island "${name}" ${phase} failed`, error);
+    }
+    catch {
+        // A broken reporter must not stop other roots.
+    }
+}
+function disposeIsland(element, phase) {
+    const handle = rootHandle(element);
+    try {
+        handle?.dispose();
+    }
+    catch (error) {
+        reportIslandError(element, phase, error);
+    }
+    finally {
+        if (rootHandle(element) === handle)
+            setRootHandle(element, undefined);
+        element.removeAttribute(ISLAND_MOUNTED_ATTR);
+    }
+}
+function installCompositionTracker(doc) {
+    const target = doc;
+    if (target[TRACKER_KEY])
+        return;
+    const set = (event, value) => {
+        if (event.target instanceof Element) {
+            event.target[COMPOSITION_KEY] = value;
+        }
+    };
+    const start = (event) => set(event, "active");
+    const end = (event) => set(event, "idle");
+    const input = (event) => {
+        if (event.isComposing)
+            set(event, "active");
+    };
+    doc.addEventListener("compositionstart", start, true);
+    doc.addEventListener("compositionend", end, true);
+    doc.addEventListener("input", input, true);
+    doc.addEventListener("blur", end, true);
+    target[TRACKER_KEY] = () => {
+        doc.removeEventListener("compositionstart", start, true);
+        doc.removeEventListener("compositionend", end, true);
+        doc.removeEventListener("input", input, true);
+        doc.removeEventListener("blur", end, true);
+        delete target[TRACKER_KEY];
+    };
+}
 // Elements for which the nested-island self-wrap warning has already been
 // emitted. Guards against repeated warn spam across re-walks (e.g. SPA swaps).
 const warnedNested = new WeakSet();
-// Elements with an in-flight dynamic import that has not yet resolved.
-// Two concurrent `mountIslands` invocations (or two `scheduleMount`
-// calls hitting the same element through different code paths) could
-// otherwise both pass the `mounted` guard and both spawn an
-// `importIsland(url)` -> `fn()` chain, double-mounting the component.
-// Adding the element to `pending` synchronously, before the import is
-// fired, closes that window; the entry is removed in both the success
-// (after `mounted.set`) and failure branches.
-const pending = new WeakSet();
 // Module-level captured manifest — set by the first `mountIslands` call and reused by
 // `mountNewIslands()` so the client-router does not need to know the manifest directly.
 // Named technical cause (W1B §12.1): the router lives in @takazudo/zfb-runtime; the
@@ -260,7 +298,7 @@ const pendingCancels = new Map();
  *
  * No-op when `document` is undefined (SSR, edge runtime). Safe to call
  * multiple times: each element is mounted at most once thanks to the
- * `mounted` WeakSet guard.
+ * symbol-handle guard.
  *
  * The manifest is captured at module level so `mountNewIslands()` can re-use
  * it after an SPA body swap without needing the caller to re-supply it.
@@ -270,9 +308,10 @@ export function mountIslands(manifest) {
         return;
     // Capture the manifest for post-swap re-walks via mountNewIslands().
     capturedManifest = manifest;
+    installCompositionTracker(document);
     const ssrIslands = document.querySelectorAll("[data-zfb-island]");
     for (const el of Array.from(ssrIslands)) {
-        stripStaleMountedMarker(el);
+        const replacing = prepareMount(el);
         // Skip the empty-skeleton case left behind when the server-side
         // rewriter has not run yet (data-zfb-island="" with no component
         // name). The hydration emit step is expected to fill this in
@@ -282,16 +321,16 @@ export function mountIslands(manifest) {
         if (!name)
             continue;
         warnIfNestedIsland(el, name);
-        scheduleMount(manifest, el, name, "hydrate");
+        scheduleMount(manifest, el, name, replacing ? "render" : "hydrate", { force: replacing });
     }
     const skipSsrIslands = document.querySelectorAll("[data-zfb-island-skip-ssr]");
     for (const el of Array.from(skipSsrIslands)) {
-        stripStaleMountedMarker(el);
+        const replacing = prepareMount(el);
         const name = el.getAttribute("data-zfb-island-skip-ssr");
         if (!name)
             continue;
         warnIfNestedIsland(el, name);
-        scheduleMount(manifest, el, name, "render");
+        scheduleMount(manifest, el, name, "render", { force: replacing });
     }
 }
 /**
@@ -313,81 +352,46 @@ export function mountNewIslands() {
     const manifest = capturedManifest;
     const ssrIslands = document.querySelectorAll("[data-zfb-island]");
     for (const el of Array.from(ssrIslands)) {
-        stripStaleMountedMarker(el);
+        const replacing = prepareMount(el);
         const name = el.getAttribute("data-zfb-island");
         if (!name)
             continue;
-        // A persisted island whose props changed across the body swap is flagged
-        // for remount by swap-functions.swapBodyElement. Clear its surviving mounted
-        // entry BEFORE scheduleMount's already-mounted guard so it re-mounts fresh
-        // with the refreshed data-props. No-op for every other element.
-        const forceRemount = clearMountedForRemount(el);
+        // The router marks changed persisted identity/props on the surviving node.
+        const forceRemount = clearMountedForRemount(el) || replacing;
         warnIfNestedIsland(el, name);
-        scheduleMount(manifest, el, name, "hydrate", { force: forceRemount });
+        scheduleMount(manifest, el, name, forceRemount ? "render" : "hydrate", { force: forceRemount });
     }
     const skipSsrIslands = document.querySelectorAll("[data-zfb-island-skip-ssr]");
     for (const el of Array.from(skipSsrIslands)) {
-        stripStaleMountedMarker(el);
+        const replacing = prepareMount(el);
         const name = el.getAttribute("data-zfb-island-skip-ssr");
         if (!name)
             continue;
         warnIfNestedIsland(el, name);
-        scheduleMount(manifest, el, name, "render");
+        const forceRemount = clearMountedForRemount(el) || replacing;
+        scheduleMount(manifest, el, name, "render", { force: forceRemount });
     }
 }
-/**
- * Consume the cross-package "needs-remount" signal for the persist-props hybrid
- * path (port-spec §12.3.1 hybrid case / §12.3.2). When a persisted island's
- * props differ from the incoming markup, `swapBodyElement` refreshes the
- * surviving element's `data-props` and marks it with `ISLAND_REMOUNT_ATTR`.
- * That attribute is the ONLY channel that crosses the zfb-runtime → zfb package
- * boundary — the `mounted` map is module-private to this file, so a shared
- * in-memory "needs-remount" queue between the two packages is impossible; the
- * live DOM node carrying the flag IS the queue.
- *
- * On a flagged mounted element: fire the old instance's unmount thunk (so its
- * useEffect/framework cleanups run against the still-connected node), drop the
- * `mounted` entry so `scheduleMount`'s guard no longer short-circuits, strip the
- * flag, and ask the caller to force the replacement mount through immediately
- * instead of re-entering any deferred scheduler. This keeps a deferred persisted
- * island from blanking while it waits for idle/visible/media to fire again.
- *
- * On a flagged element whose URL import is still pending, leave the flag in
- * place. The already-running import's success handler consumes it after the
- * module resolves and re-reads `data-props` at that point, so a props refresh
- * that happened during the import wins without starting a duplicate import.
- *
- * A no-op for elements without the flag (the common case: fresh markers and
- * props-unchanged persisted islands).
- *
- * Scope: only the `[data-zfb-island]` (hydrated) loop calls this, mirroring the
- * writer side — swapBodyElement sets the flag only for `newTarget.matches(
- * "[data-zfb-island]")`, never for skip-ssr islands.
- */
+/** Consume a persisted root's remount flag and dispose its previous resources. */
 function clearMountedForRemount(el) {
     if (!el.hasAttribute(ISLAND_REMOUNT_ATTR))
         return false;
-    if (pending.has(el))
-        return false;
-    const thunk = mounted.get(el);
-    if (thunk) {
-        try {
-            thunk();
-        }
-        finally {
-            mounted.delete(el);
-            el.removeAttribute(ISLAND_MOUNTED_ATTR);
-            el.removeAttribute(ISLAND_REMOUNT_ATTR);
-        }
-        return true;
-    }
-    el.removeAttribute(ISLAND_MOUNTED_ATTR);
     el.removeAttribute(ISLAND_REMOUNT_ATTR);
-    return false;
+    if (rootHandle(el))
+        disposeIsland(el, "remount disposal");
+    else
+        el.removeAttribute(ISLAND_MOUNTED_ATTR);
+    return true;
 }
-function stripStaleMountedMarker(el) {
-    if (!mounted.has(el))
+function prepareMount(el) {
+    let replacing = false;
+    if (rootHandle(el) && !owned.has(el)) {
+        disposeIsland(el, "dev replacement disposal");
+        replacing = true;
+    }
+    if (!rootHandle(el))
         el.removeAttribute(ISLAND_MOUNTED_ATTR);
+    return replacing;
 }
 /**
  * Cancel deferred-hydration callbacks for all islands in the old body before a
@@ -438,10 +442,7 @@ function warnIfNestedIsland(el, componentName) {
         `and apply <Island when="..."> at the call site instead.`);
 }
 function scheduleMount(manifest, element, componentName, mode, options = {}) {
-    // Skip elements already mounted OR currently importing — the latter
-    // prevents two concurrent `mountIslands` calls from each firing a
-    // separate dynamic import for the same element.
-    if (mounted.has(element) || pending.has(element))
+    if (rootHandle(element))
         return;
     const entry = manifest[componentName];
     if (entry == null) {
@@ -452,140 +453,21 @@ function scheduleMount(manifest, element, componentName, mode, options = {}) {
         }
         return;
     }
-    const when = element.getAttribute("data-when") ?? undefined;
-    // Two manifest shapes:
-    //
-    //   - `string` (per-island bundle URL): fetch via dynamic `import()`
-    //     and call `mount` / `default` on the resolved module.
-    //   - `IslandModule` (inline descriptor): the shared-bundle path has
-    //     already imported every island's source into the same bundle and
-    //     constructed a mount function for it. Skip the dynamic import
-    //     and call the supplied function directly.
-    if (typeof entry !== "string") {
-        fireInlineMount(element, entry, mode, options);
-        return;
-    }
-    const url = entry;
-    const fire = () => {
-        // Re-check both guards in case `fire` is invoked from a deferred
-        // scheduler (rIC/rAF/visibility) after a sibling caller already
-        // mounted or started importing for this element.
-        if (mounted.has(element) || pending.has(element))
-            return;
-        // When the deferred fire actually runs, the cancel handle is no longer
-        // needed — remove it so pendingCancels doesn't hold stale entries.
-        pendingCancels.delete(element);
-        // Lazy props parse: read and parse data-props only now that we know we
-        // are actually going to mount this island. For deferred strategies
-        // (media, visible, idle) this avoids JSON.parse work at boot time for
-        // islands that may never hydrate (e.g. media query never matches).
-        const props = readProps(element);
-        // Mark as pending BEFORE firing the import so any concurrent
-        // `mountIslands` invocation that arrives during the await window
-        // is short-circuited by `scheduleMount`'s guard.
-        pending.add(element);
-        // Dynamic-import is cached by the JS runtime, so repeat hits for
-        // the same URL share the resolved module — module-level
-        // singletons are fine.
-        //
-        // We move the element from `pending` to `mounted` only on the
-        // success path so a failed import (e.g. transient network blip
-        // in dev) doesn't permanently block a retry of the same element.
-        let started;
-        try {
-            started = importIsland(url);
-        }
-        catch (err) {
-            // Some implementations of dynamic-import wrappers can throw
-            // synchronously (e.g. URL parsing errors). Treat the same as
-            // an async rejection.
-            pending.delete(element);
-            // eslint-disable-next-line no-console
-            console.error(`[zfb] failed to start dynamic import for ${url}`, err);
-            return;
-        }
-        started.then((mod) => {
-            const fn = mod.mount ?? mod.default;
-            if (typeof fn !== "function") {
-                pending.delete(element);
-                if (typeof process !== "undefined" &&
-                    process.env &&
-                    process.env["NODE_ENV"] !== "production") {
-                    // eslint-disable-next-line no-console
-                    console.warn(`[zfb] island bundle at ${url} did not export mount() or default()`);
-                }
-                return;
-            }
-            // Stale-mount race guard: if the element was detached while the
-            // dynamic import was in-flight (e.g. a body swap happened), skip
-            // mounting — the element is no longer in the live document and
-            // its useEffect listeners would never receive a cleanup call.
-            if (!element.isConnected) {
-                pending.delete(element);
-                return;
-            }
-            const shouldRefreshProps = element.hasAttribute(ISLAND_REMOUNT_ATTR);
-            const propsForMount = shouldRefreshProps ? readProps(element) : props;
-            if (shouldRefreshProps)
-                element.removeAttribute(ISLAND_REMOUNT_ATTR);
-            const unmountThunk = mod.unmount
-                ? () => mod.unmount(element)
-                : () => {
-                    // noop — bundle does not expose unmount
-                };
-            try {
-                fn(propsForMount, element, mode);
-                mounted.set(element, unmountThunk);
-                element.setAttribute(ISLAND_MOUNTED_ATTR, "");
-            }
-            finally {
-                pending.delete(element);
-            }
-        }, (err) => {
-            // Surface the error in dev so the user notices, then clear
-            // both guards so a later retry (e.g. another scheduleHydrate
-            // fire) can attempt the import again.
-            pending.delete(element);
-            mounted.delete(element);
-            // eslint-disable-next-line no-console
-            console.error(`[zfb] failed to load island bundle ${url}`, err);
-        });
-    };
-    if (mode === "render") {
-        // SSR-skip islands ignore data-when: there is nothing to defer
-        // hydration of, just an empty container we paint into. Mount
-        // immediately so the user sees output.
-        fire();
-        return;
-    }
-    if (options.force) {
-        fire();
-        return;
-    }
-    const { fired, cancel } = scheduleHydrateInternal(element, when, fire);
-    // Track deferred-hydration cancel handle so cancelPendingIslands() can abort
-    // idle / visibility callbacks before a body swap. (W1B §12.5)
-    // Only register when the scheduler did NOT fire synchronously — a synchronous
-    // fire means the island is already handling its import and there is no
-    // deferred callback to cancel. Registering noop after a sync fire would leave
-    // a stale pendingCancels entry for an already-handled element. (#743)
-    if (when && when !== "load" && !fired) {
-        pendingCancels.set(element, cancel);
-    }
+    fireInlineMount(element, entry, mode, options);
 }
 /**
  * Run the mount step for the inline-module manifest shape used by the
  * shared-bundle path. The module is already in memory (it was imported
  * into the bundle at build time), so there is no async window to
  * coordinate around — we just call `mount` / `default` directly,
- * gated by the same `data-when` semantics as the URL path.
+ * gated by `data-when` semantics.
  */
 function fireInlineMount(element, mod, mode, options = {}) {
-    const fn = mod.mount ?? mod.default;
+    const fn = mod.mount;
     if (typeof fn !== "function") {
         if (typeof process !== "undefined" && process.env && process.env["NODE_ENV"] !== "production") {
             // eslint-disable-next-line no-console
-            console.warn("[zfb] inline island manifest entry did not export mount() or default()");
+            console.warn("[zfb] owned island manifest entry did not export mount()");
         }
         return;
     }
@@ -593,7 +475,7 @@ function fireInlineMount(element, mod, mode, options = {}) {
         // Re-check the guard in case `fire` is invoked from a deferred
         // scheduler (rIC/rAF/visibility) after a sibling caller already
         // mounted this element.
-        if (mounted.has(element))
+        if (rootHandle(element))
             return;
         // When the deferred fire actually runs, the cancel handle is no longer
         // needed — remove it so pendingCancels doesn't hold stale entries.
@@ -605,20 +487,24 @@ function fireInlineMount(element, mod, mode, options = {}) {
         // Lazy props parse: read and parse data-props only at mount time.
         // For deferred strategies (media, visible, idle) this avoids JSON.parse
         // work at boot time for islands that may never hydrate.
-        const props = readProps(element);
-        const unmountThunk = mod.unmount
-            ? () => mod.unmount(element)
-            : () => {
-                // noop — inline module does not expose unmount
-            };
-        fn(props, element, mode);
-        mounted.set(element, unmountThunk);
-        element.setAttribute(ISLAND_MOUNTED_ATTR, "");
+        try {
+            const props = readProps(element, mod.identity);
+            const result = fn(props, element, mode);
+            if (result === null)
+                return;
+            if (!result || typeof result.dispose !== "function" || typeof result.unmount !== "function") {
+                throw new TypeError(`ZR_ROOT_HANDLE: island ${mod.identity.component} returned no root handle`);
+            }
+            const handle = result;
+            setRootHandle(element, handle);
+            owned.add(element);
+            element.setAttribute(ISLAND_MOUNTED_ATTR, "");
+        }
+        catch (error) {
+            element.removeAttribute(ISLAND_MOUNTED_ATTR);
+            reportIslandError(element, "mount", error);
+        }
     };
-    if (mode === "render") {
-        fire();
-        return;
-    }
     if (options.force) {
         fire();
         return;
@@ -636,115 +522,196 @@ function fireInlineMount(element, mod, mode, options = {}) {
     }
 }
 /**
- * Unmount the mounted islands within `root` (default: `document.body`) that will
- * NOT survive the body swap.
- *
- * Walks `root` for `[data-zfb-island]` and `[data-zfb-island-skip-ssr]` elements,
- * looks up each element's unmount thunk in the `mounted` WeakMap, calls it (which
- * triggers `render(null, element)` for Preact or `root.unmount()` for React), and
- * removes the entry from the map so `mountNewIslands()` can re-mount later.
- *
- * Call this before `swapBodyElement(...)` so the OLD body's islands receive proper
- * framework lifecycle cleanup (useEffect teardowns, etc.) before being discarded.
- *
- * When `incomingBody` is supplied (the client-router passes the parsed incoming
- * document body), any island whose `data-zfb-transition-persist` id matches a
- * marker in that body is DELIBERATELY SKIPPED: swapBodyElement will physically
- * lift the node into the new body, so its component instance and internal state
- * must survive — unmounting it here would empty the container before the lift and
- * defeat the persist contract (issue #1389). Omit `incomingBody` (or pass null)
- * to unmount everything, the pre-#1389 behavior.
- *
- * No-op for elements not in the `mounted` map (e.g. never-mounted or already cleaned up).
+ * Snapshot persistence and island pairings before changing any old-body node.
+ * The router lifts only matched persist nodes whose incoming targets are not
+ * nested inside another matched target. Their descendants survive that lift.
  */
 export function unmountIslands(root = document.body, incomingBody) {
-    const selector = "[data-zfb-island],[data-zfb-island-skip-ssr]";
-    // Persist ids that `swapBodyElement` will physically LIFT from the old body
-    // into the incoming body — an old marker survives iff the incoming body has a
-    // marker with the same `data-zfb-transition-persist` id. Those DOM nodes are
-    // moved, not discarded, so their component instance and internal state MUST
-    // survive the swap: skip their framework unmount here or the persist contract
-    // preserves nothing (port-spec §12.3.1 case (a) / issue #1389). A persisted
-    // island whose props changed is skipped here too — its refreshed remount runs
-    // later in mountNewIslands via the `data-zfb-island-remount` flag (see
-    // `clearMountedForRemount`) swapBodyElement sets. With no incoming body (a
-    // call outside a swap) nothing is preserved, so the walk is byte-identical to
-    // the pre-#1389 behavior.
-    const preservedPersistIds = collectPersistIds(incomingBody);
-    const elements = root.querySelectorAll(selector);
-    for (const el of Array.from(elements)) {
-        const persistId = el.getAttribute(PERSIST_ATTR);
-        if (persistId !== null && preservedPersistIds.has(persistId))
+    const islandSelector = "[data-zfb-island],[data-zfb-island-skip-ssr]";
+    const oldIslands = Array.from(root.querySelectorAll(islandSelector));
+    if (!incomingBody) {
+        for (const island of oldIslands)
+            disposeIsland(island, "disposal");
+        return;
+    }
+    const persistSelector = `[${PERSIST_ATTR}]`;
+    const oldPersist = Array.from(root.querySelectorAll(persistSelector));
+    const incomingPersist = Array.from(incomingBody.querySelectorAll(persistSelector));
+    const incomingById = new Map();
+    for (const element of incomingPersist) {
+        const id = element.getAttribute(PERSIST_ATTR);
+        if (id !== null && !incomingById.has(id))
+            incomingById.set(id, element);
+    }
+    const targets = new Map();
+    for (const element of oldPersist) {
+        const id = element.getAttribute(PERSIST_ATTR);
+        const target = id === null ? undefined : incomingById.get(id);
+        if (target)
+            targets.set(element, target);
+    }
+    const matchedTargets = new Set(targets.values());
+    const lifted = new Set();
+    for (const [element, target] of targets) {
+        let ancestor = target.parentElement;
+        while (ancestor && !matchedTargets.has(ancestor))
+            ancestor = ancestor.parentElement;
+        if (!ancestor)
+            lifted.add(element);
+    }
+    const retained = new Set(lifted);
+    for (const element of oldPersist) {
+        if (!targets.has(element))
+            continue;
+        let ancestor = element.parentElement;
+        while (ancestor && !lifted.has(ancestor))
+            ancestor = ancestor.parentElement;
+        if (ancestor)
+            retained.add(element);
+    }
+    const boundaryById = new Map();
+    for (const element of oldPersist) {
+        if (!retained.has(element))
+            continue;
+        const id = element.getAttribute(PERSIST_ATTR);
+        if (id !== null && !boundaryById.has(id))
+            boundaryById.set(id, element);
+    }
+    const oldByBoundary = new Map();
+    const incomingByBoundary = new Map();
+    const withoutBoundary = [];
+    for (const island of oldIslands) {
+        let ancestor = island;
+        while (ancestor && !retained.has(ancestor))
+            ancestor = ancestor.parentElement;
+        if (!ancestor) {
+            withoutBoundary.push(island);
             continue;
-        const thunk = mounted.get(el);
-        try {
-            thunk?.();
         }
-        finally {
-            mounted.delete(el);
-            el.removeAttribute(ISLAND_MOUNTED_ATTR);
+        const group = oldByBoundary.get(ancestor) ?? [];
+        group.push(island);
+        oldByBoundary.set(ancestor, group);
+    }
+    for (const island of incomingBody.querySelectorAll(islandSelector)) {
+        let ancestor = island;
+        let boundary;
+        while (ancestor && !boundary) {
+            const id = ancestor.getAttribute(PERSIST_ATTR);
+            if (id !== null)
+                boundary = boundaryById.get(id);
+            ancestor = ancestor.parentElement;
         }
+        if (!boundary)
+            continue;
+        const group = incomingByBoundary.get(boundary) ?? [];
+        group.push(island);
+        incomingByBoundary.set(boundary, group);
+    }
+    const pairs = [];
+    const removed = [];
+    for (const [boundary, oldGroup] of oldByBoundary) {
+        const incomingGroup = incomingByBoundary.get(boundary) ?? [];
+        const pairedOld = new Set();
+        const pairedIncoming = new Set();
+        // A persisted island root always maps to its own target, even when the
+        // target changes component or ceases to be an island.
+        if (oldGroup.includes(boundary)) {
+            pairedOld.add(boundary);
+            const target = targets.get(boundary);
+            if (target && incomingGroup.includes(target)) {
+                pairs.push({ old: boundary, incoming: target });
+                pairedIncoming.add(target);
+            }
+            else {
+                removed.push(boundary);
+            }
+        }
+        for (const old of oldGroup) {
+            if (pairedOld.has(old))
+                continue;
+            const name = islandName(old);
+            const incoming = incomingGroup.find((candidate) => !pairedIncoming.has(candidate) && islandName(candidate) === name);
+            if (!incoming)
+                continue;
+            pairs.push({ old, incoming });
+            pairedOld.add(old);
+            pairedIncoming.add(incoming);
+        }
+        const remainingIncoming = incomingGroup.filter((island) => !pairedIncoming.has(island));
+        let next = 0;
+        for (const old of oldGroup) {
+            if (pairedOld.has(old))
+                continue;
+            const incoming = remainingIncoming[next++];
+            if (incoming)
+                pairs.push({ old, incoming });
+            else
+                removed.push(old);
+        }
+    }
+    // Apply only after all boundaries and pairings have been computed. An old
+    // descendant removed from a lifted wrapper must be detached as well as
+    // disposed, or the post-swap walk could hydrate its mutated DOM.
+    for (const island of withoutBoundary)
+        disposeIsland(island, "disposal");
+    for (const { old, incoming } of pairs) {
+        const copyProps = !old.hasAttribute("data-zfb-transition-persist-props") ||
+            old.getAttribute("data-zfb-transition-persist-props") === "false";
+        const identityChanged = ISLAND_IDENTITY_ATTRS.some((attribute) => old.getAttribute(attribute) !== incoming.getAttribute(attribute));
+        if (!old.hasAttribute(ISLAND_REMOUNT_ATTR) &&
+            !identityChanged &&
+            (!copyProps || old.getAttribute("data-props") === incoming.getAttribute("data-props")))
+            continue;
+        for (const attribute of ISLAND_IDENTITY_ATTRS)
+            copyAttribute(incoming, old, attribute);
+        if (copyProps)
+            copyAttribute(incoming, old, "data-props");
+        old.setAttribute(ISLAND_REMOUNT_ATTR, "");
+    }
+    for (const island of removed) {
+        disposeIsland(island, "disposal");
+        island.remove();
     }
 }
-/**
- * Collect the `data-zfb-transition-persist` ids present in the incoming body so
- * `unmountIslands` can tell which old-body islands `swapBodyElement` will lift
- * (and therefore must be left mounted). Returns an empty set when no incoming
- * body is supplied.
- */
-function collectPersistIds(incomingBody) {
-    const ids = new Set();
-    if (!incomingBody)
-        return ids;
-    for (const el of incomingBody.querySelectorAll(`[${PERSIST_ATTR}]`)) {
-        const id = el.getAttribute(PERSIST_ATTR);
-        if (id !== null)
-            ids.add(id);
-    }
-    return ids;
+const ISLAND_IDENTITY_ATTRS = [
+    "data-zfb-island",
+    "data-zfb-island-skip-ssr",
+    "data-zfb-transport",
+    "data-zfb-protocol",
+    "data-zfb-build",
+];
+function islandName(element) {
+    return (element.getAttribute("data-zfb-island") ?? element.getAttribute("data-zfb-island-skip-ssr"));
+}
+function copyAttribute(from, to, attribute) {
+    const value = from.getAttribute(attribute);
+    if (value === null)
+        to.removeAttribute(attribute);
+    else
+        to.setAttribute(attribute, value);
 }
-function readProps(element) {
+function readProps(element, identity) {
     const raw = element.getAttribute("data-props");
-    if (!raw)
-        return {};
+    const hasHydrate = element.hasAttribute("data-zfb-island");
+    const hasSkipSsr = element.hasAttribute("data-zfb-island-skip-ssr");
+    const component = element.getAttribute("data-zfb-island") ?? element.getAttribute("data-zfb-island-skip-ssr");
+    if (hasHydrate === hasSkipSsr ||
+        component !== identity.component ||
+        element.getAttribute("data-zfb-transport") !== "json/1" ||
+        element.getAttribute("data-zfb-protocol") !== "zudo-react/1" ||
+        element.getAttribute("data-zfb-build") !== identity.build ||
+        raw === null) {
+        throw new TypeError(`ZR_IDENTITY: island ${identity.component} has invalid transport identity`);
+    }
+    if (element.querySelector("[data-zfb-island],[data-zfb-island-skip-ssr]")) {
+        throw new TypeError(`ZR_NESTED_ISLAND: island ${identity.component} contains another island`);
+    }
     try {
-        const parsed = JSON.parse(raw);
-        // Reject arrays explicitly: `typeof [] === "object"` is true but
-        // an array is not a valid props bag, and passing it through would
-        // mean the component receives index-keyed values where it
-        // expected a record. Fall through to the empty-object default
-        // instead of forwarding a malformed shape.
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
-        }
+        return parseOwnedProps(raw);
     }
-    catch {
-        // fall through
+    catch (error) {
+        throw new TypeError(`ZR_PROPS: island ${identity.component}: ${String(error)}`);
     }
-    return {};
-}
-/**
- * Indirection so tests can stub the dynamic import without intercepting
- * the global `import()`. In production this is a thin wrapper over
- * native `import(url)`.
- */
-let importImpl = (url) => 
-// Modern bundlers (esbuild, Vite, Rollup, webpack) preserve a plain
-// `import(<dynamic>)` call when the argument isn't a static literal,
-// so we no longer need the `new Function(...)` indirection — which
-// also failed under strict CSPs that disallow `unsafe-eval`.
-import(/* @vite-ignore */ /* webpackIgnore: true */ url);
-function importIsland(url) {
-    return importImpl(url);
-}
-/**
- * Test-only seam. Replace the module dynamic-import with a fake.
- * Returns the previous implementation so tests can restore it.
- */
-export function __setIslandImporterForTests(impl) {
-    const prev = importImpl;
-    importImpl = impl;
-    return prev;
 }
 /**
  * Test-only seam. Returns whether the given element has an entry in the