@takazudo/zfb 2.22.1 → 3.0.0

package/dist/runtime.d.ts

@@ -1,4 +1,5 @@
 import { type When } from "./types.js";
+import { type RootHandle } from "./zudo-react/root.js";
 /**
  * Schedule a hydration `fire` callback for `target` according to `when`.
  *
@@ -10,69 +11,37 @@ import { type When } from "./types.js";
  */
 export declare function scheduleHydrate(target: Element, when: When | string | undefined, fire: () => void): () => void;
 /**
- * The shape of the default export each per-island bundle ships.
+ * The mount function supplied by a shared-bundle island module.
  *
  * `mode === "hydrate"` is used for SSR'd islands, `"render"` for
  * SSR-skip islands.
  */
-type IslandMount = (props: Record<string, unknown>, element: Element, mode: "hydrate" | "render") => void;
-type IslandUnmount = (element: Element) => void;
+type IslandMount = (props: Record<string, unknown>, element: Element, mode: "hydrate" | "render") => RootHandle | null;
 interface IslandModule {
-    mount?: IslandMount;
-    default?: IslandMount;
-    unmount?: IslandUnmount;
+    identity: {
+        component: string;
+        build: string;
+    };
+    mount: IslandMount;
 }
 /**
  * Map of `componentName → island descriptor` baked into the runtime entry.
  *
- * Two descriptor shapes are accepted so the same `mountIslands` runtime
- * handles both bundling strategies the build emits:
- *
- *   1. `string` — a per-island bundle URL. The runtime fetches it via
- *      dynamic `import()` and reads `mount` / `default` off the loaded
- *      module. Used by the per-island bundling path
- *      (`bundle_per_island` / `render_runtime_entry_source`).
- *
- *   2. `IslandModule` — an inline module-shaped object whose `mount` (or
- *      `default`) is called directly. Used by the shared-bundle path
- *      (`render_shared_bundle_entry_source`): every island's source code
- *      is already in the same bundle, so the synthesised entry can hand
- *      the runtime the constructed mount functions inline without a
- *      second HTTP fetch. This preserves the one-request shared-bundle
- *      contract while giving up nothing on hydration semantics
- *      (zudolab/zudo-doc#1355 wave 6).
+ * Each manifest value is an inline module with `mount` or `default`.
+ * The shared bundle imports island sources at build time.
  */
-export type IslandManifestValue = string | IslandModule;
+export type IslandManifestValue = IslandModule;
 export type IslandManifest = Readonly<Record<string, IslandManifestValue>>;
 /**
- * Public DOM signal written after an island's mount function returns.
- *
- * 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.
+ * Public observation marker; the symbol handle is the live-root guard.
+ *
+ * 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 persisted root: both survive with the same DOM node;
+ * - changed persisted root: dispose, clear, then mount in render mode;
+ * - bundle re-import: dispose the old symbol handle before render mode replaces it.
  */
 export declare const ISLAND_MOUNTED_ATTR = "data-zfb-island-mounted";
 /**
@@ -81,7 +50,7 @@ export declare const ISLAND_MOUNTED_ATTR = "data-zfb-island-mounted";
  *
  * 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.
@@ -110,33 +79,10 @@ export declare function mountNewIslands(): void;
  */
 export declare function cancelPendingIslands(): void;
 /**
- * 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).
+ * Dispose roots that the incoming body will discard. Persisted roots keep their
+ * handles and DOM until the post-swap scan determines whether to recreate them.
  */
 export declare function unmountIslands(root?: ParentNode, incomingBody?: ParentNode | null): void;
-/**
- * Test-only seam. Replace the module dynamic-import with a fake.
- * Returns the previous implementation so tests can restore it.
- */
-export declare function __setIslandImporterForTests(impl: (url: string) => Promise<IslandModule>): (url: string) => Promise<IslandModule>;
 /**
  * Test-only seam. Returns whether the given element has an entry in the
  * module-private `pendingCancels` Map. Used to assert that a synchronous