@atolljs/islands 0.1.13 → 0.1.15

package/dist/boundary.d.ts

@@ -0,0 +1,57 @@
+import type { IslandHandle, MountIslandOptions } from './island.js';
+/** What a boundary render fn may return — applied via el.replaceChildren/append. */
+export type BoundaryContent = Node | string | Array<Node | string> | null | undefined;
+/** Where the failure happened — 'mount' (handshake), 'runtime' (worker crash). */
+export type IslandBoundaryPhase = 'mount' | 'runtime';
+export interface IslandBoundaryContext {
+    /** The mount's app key. */
+    app: string;
+    /** The island's container element — the boundary's render target. */
+    el: HTMLElement;
+    /** 1-based mount attempt counter — increments across retries. */
+    attempt: number;
+}
+export interface IslandBoundaryErrorContext extends IslandBoundaryContext {
+    /** The caught failure (mount rejection, crash error). */
+    error: unknown;
+    phase: IslandBoundaryPhase;
+    /** Manual remount — wire it to a retry button in the error render. */
+    retry(): void;
+}
+export interface IslandBoundary {
+    /** Rendered while the first mount attempt is in flight. */
+    loading?(ctx: IslandBoundaryContext): BoundaryContent;
+    /** Rendered when the island fails — mount rejection or runtime crash. */
+    error?(ctx: IslandBoundaryErrorContext): BoundaryContent;
+    /** Fires on every boundary-entering failure — logging/telemetry. */
+    onError?(error: unknown, phase: IslandBoundaryPhase): void;
+    /**
+     * Auto-remount policy: a number is the max retry count (delay grows
+     * ~250ms per attempt, capped at 2s); a function maps (attempt, error)
+     * to a delay in ms, `false`/`undefined` to stop. Omit for no auto-retry.
+     */
+    retry?: number | ((attempt: number, error: unknown) => number | false | undefined | void);
+    /**
+     * What the error state does to the container: 'clear' (default) replaces
+     * its contents with the fallback; 'preserve' appends the fallback over
+     * the stale last frame on runtime crashes (mount failures always clear —
+     * there is no frame to preserve).
+     */
+    domOnError?: 'clear' | 'preserve';
+}
+export type IslandBoundaryState = 'loading' | 'mounted' | 'error';
+/**
+ * The boundary-aware handle: a normal IslandHandle when mounted, safe
+ * no-ops while failed (updateProps stashes into the next attempt's props),
+ * plus the boundary's own state.
+ */
+export interface IslandBoundaryHandle extends IslandHandle {
+    readonly state: IslandBoundaryState;
+    /** The error that put the boundary in 'error' state (undefined otherwise). */
+    readonly error: unknown;
+    /** Remount now — same as ctx.retry() handed to the error render fn. */
+    retry(): void;
+}
+export declare function mountIslandWithBoundary(opts: MountIslandOptions & {
+    boundary: IslandBoundary;
+}): Promise<IslandBoundaryHandle>;

package/dist/{chunk-TX4FAHRB.js → chunk-P3G2GL3T.js}

@@ -450,6 +450,7 @@ async function mountIsland(opts) {
     app: givenApp,
     props: givenProps,
     framework,
+    boundary,
     ...workerConfig
   } = opts;
   if (isProxyMountTarget(target)) {
@@ -461,6 +462,9 @@ async function mountIsland(opts) {
     return subMounter(opts);
   }
   const el = target;
+  if (boundary !== void 0) {
+    return mountIslandWithBoundary(opts);
+  }
   const cbTable = /* @__PURE__ */ new Map();
   let cbSeq = 0;
   const registerCb = (fn) => {
@@ -1118,6 +1122,172 @@ async function mountIsland(opts) {
   return handle;
 }
 
+// src/boundary.ts
+async function mountIslandWithBoundary(opts) {
+  const {
+    boundary,
+    el: target,
+    client: givenClient,
+    worker,
+    app: givenApp,
+    props: givenProps,
+    mode: initialMode,
+    ...mountOpts
+  } = opts;
+  const client = givenClient ?? connectIslandWorker({
+    name: givenApp,
+    ...mountOpts,
+    worker,
+    doorbell: initialMode !== "poll"
+  });
+  const app = givenApp ?? "main";
+  const el = target;
+  let state = "loading";
+  let lastError;
+  let current = null;
+  let attempt = 0;
+  let destroyed = false;
+  let retryTimer = null;
+  let pendingProps = givenProps;
+  let pendingMode = initialMode;
+  const setContent = (content, how) => {
+    if (content === null || content === void 0) {
+      if (how === "replace") el.replaceChildren();
+      return;
+    }
+    const parts = (Array.isArray(content) ? content : [content]).filter(
+      (p) => p !== null && p !== void 0
+    );
+    if (how === "replace") el.replaceChildren(...parts);
+    else el.append(...parts);
+  };
+  const scheduleRetry = (error) => {
+    const policy = boundary.retry;
+    if (policy === void 0 || retryTimer !== null) return;
+    const delay = typeof policy === "number" ? attempt <= policy ? Math.min(250 * attempt, 2e3) : false : policy(attempt, error);
+    if (delay === false || delay === void 0 || typeof delay !== "number") return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void tryMount();
+    }, Math.max(0, delay));
+  };
+  const fail = (error, phase) => {
+    if (destroyed) return;
+    state = "error";
+    lastError = error;
+    boundary.onError?.(error, phase);
+    const content = boundary.error?.({
+      app,
+      el,
+      attempt,
+      error,
+      phase,
+      retry: manualRetry
+    });
+    if (boundary.domOnError === "preserve" && phase === "runtime") {
+      setContent(content, "append");
+    } else {
+      setContent(content, "replace");
+    }
+    scheduleRetry(error);
+  };
+  const tryMount = async () => {
+    if (destroyed) return;
+    attempt++;
+    el.replaceChildren();
+    try {
+      const handle2 = await mountIsland({
+        ...mountOpts,
+        client,
+        el,
+        app: givenApp,
+        props: pendingProps,
+        mode: pendingMode
+      });
+      if (destroyed) {
+        handle2.destroy();
+        return;
+      }
+      current = handle2;
+      state = "mounted";
+    } catch (err) {
+      fail(err, "mount");
+    }
+  };
+  const manualRetry = () => {
+    if (destroyed) return;
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+    void tryMount();
+  };
+  const offLifecycle = client.onWorkerEvent?.((event) => {
+    if (destroyed || state === "error" || event.type !== "error") return;
+    const stale = current;
+    current = null;
+    stale?.destroy();
+    fail(
+      new Error(
+        `[island ${app}] worker crashed` + (event.message !== void 0 ? `: ${event.message}` : "")
+      ),
+      "runtime"
+    );
+  });
+  const handle = {
+    get app() {
+      return current?.app ?? app;
+    },
+    get pid() {
+      return current?.pid ?? "unmounted";
+    },
+    get instance() {
+      return current?.instance ?? `${app}@?`;
+    },
+    get mode() {
+      return current?.mode ?? pendingMode ?? "push";
+    },
+    get opsApplied() {
+      return current?.opsApplied ?? 0;
+    },
+    get flushCalls() {
+      return current?.flushCalls ?? 0;
+    },
+    get state() {
+      return state;
+    },
+    get error() {
+      return lastError;
+    },
+    retry: manualRetry,
+    setMode: (mode) => {
+      pendingMode = mode;
+      current?.setMode(mode);
+    },
+    updateProps: async (next) => {
+      pendingProps = next;
+      await current?.updateProps(next);
+    },
+    flush: async () => {
+      await current?.flush();
+    },
+    destroy: () => {
+      if (destroyed) return;
+      destroyed = true;
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
+      offLifecycle?.();
+      current?.destroy();
+      current = null;
+    }
+  };
+  setContent(boundary.loading?.({ app, el, attempt: 1 }), "replace");
+  await tryMount();
+  return handle;
+}
+
 // src/contract.ts
 var CONTRACT_MARK = "islandContract";
 var APP_CONTRACT = "appContract";
@@ -1171,6 +1341,7 @@ export {
   marshalCallbackProps,
   unmarshalCallbackProps,
   propsPreview,
+  mountIslandWithBoundary,
   isKeepAliveClient,
   connectIslandWorker,
   assertCloneableProps,

package/dist/index.d.ts

@@ -13,6 +13,8 @@
  */
 export { connectIslandWorker, isKeepAliveClient, mountIsland } from './island.js';
 export type { ConnectIslandWorkerConfig, IslandClient, IslandHandle, IslandWorkerDefinition, IslandWorkerOptions, Mode, MountIslandOptions, } from './island.js';
+export { mountIslandWithBoundary } from './boundary.js';
+export type { BoundaryContent, IslandBoundary, IslandBoundaryContext, IslandBoundaryErrorContext, IslandBoundaryHandle, IslandBoundaryPhase, IslandBoundaryState, } from './boundary.js';
 export { makeDoorbell } from './memory.js';
 export type { DoorbellSpec } from './memory.js';
 export { islandApp, islandAppNameOf } from './app.js';

package/dist/index.js

@@ -11,8 +11,9 @@ import {
   islandAppNameOf,
   makeDoorbell,
   mountIsland,
+  mountIslandWithBoundary,
   withContract
-} from "./chunk-TX4FAHRB.js";
+} from "./chunk-P3G2GL3T.js";
 export {
   callbackProp,
   connectIslandWorker,
@@ -26,5 +27,6 @@ export {
   islandAppNameOf,
   makeDoorbell,
   mountIsland,
+  mountIslandWithBoundary,
   withContract
 };

package/dist/island.d.ts

@@ -1,6 +1,7 @@
 import type { ConnectWorkerConfig, SharedSpec, WorkerClient, WorkerDefinition } from '@atolljs/core';
 import { type DoorbellSpec } from './memory.js';
 import { type IslandWorkerMethods, type Op } from './ops.js';
+import type { IslandBoundary, IslandBoundaryHandle } from './boundary.js';
 import type { ProxyElement } from './worker/dom/element.js';
 export type Mode = 'push' | 'poll';
 /** The worker definition every `definePolyWorker` call produces. */
@@ -117,6 +118,15 @@ interface MountIslandBaseOptions {
      * client warm for this island's teardown.
      */
     keepAlive?: boolean;
+    /**
+     * Error boundary — `loading`/`error` state render functions plus a retry
+     * policy, covering mount rejection, mountTimeout, and runtime worker
+     * crashes (detected via the client's lifecycle events). When set, the
+     * mount resolves to an `IslandBoundaryHandle` after the first attempt
+     * settles — errors render the fallback instead of rejecting. Ignored on
+     * nested (proxy-element) mounts. See boundary.ts / docs error-boundaries.
+     */
+    boundary?: IslandBoundary;
 }
 /**
  * The mount needs one worker-side endpoint: either a `client` a
@@ -171,5 +181,8 @@ export declare const assertCloneableProps: (props: Record<string, unknown>, cont
  *  unit semantics when replaying style values into proxy elements. */
 export declare const cssStyleValue: (key: string, value: unknown) => string;
 export declare const registerSubIslandMounter: (fn: (opts: MountIslandOptions) => Promise<IslandHandle>) => void;
+export declare function mountIsland(opts: MountIslandOptions & {
+    boundary: IslandBoundary;
+}): Promise<IslandBoundaryHandle>;
 export declare function mountIsland(opts: MountIslandOptions): Promise<IslandHandle>;
 export {};

package/dist/worker/defineWorkers.d.ts

@@ -142,6 +142,16 @@ export interface PolyWorkerRegistry {
     /** Name → island app registry. The shell's `mountIsland({ app: name })`
      *  picks one per island. */
     apps: Record<string, IslandApp>;
+    /**
+     * Lazy app loader — consulted by `mount` when the requested registry name
+     * isn't present yet. Returning an app registers it under that name (so a
+     * second mount is a registry hit); returning `undefined` lets the mount
+     * fail as unknown. Federation hosts pass a remote-module importer here —
+     * see `@atolljs/federation`. When set, the single-registered-app
+     * name-blind fallback is DISABLED: a loader host resolves every mount by
+     * its exact registry key, never by "the only app I have".
+     */
+    loadApp?: (name: string) => IslandApp | undefined | Promise<IslandApp | undefined>;
     /**
      * The doorbell contract the worker exposes — defaults to the package's
      * `renderMemory`. Rarely needed: pass a different doorbell-SPEC instance
@@ -185,6 +195,13 @@ interface RenderedInstance extends InstanceBase {
 }
 /** A mounted instance — one per island worker in production. */
 export type Instance = ImperativeInstance | RenderedInstance;
+/**
+ * Register an app into the module-level registry after the definer ran —
+ * the manual counterpart to `loadApp` (warm-up/preload outside a mount).
+ * Registers under `name` exactly; the mount-time name-blind fallback only
+ * applies to single-registry workers without a loader.
+ */
+export declare const registerIslandApp: (name: string, app: IslandApp) => void;
 /**
  * PolyWorker — one worker script serving a REGISTRY of islands:
  * `mountIsland({ app: name })` picks one per island, and every island in

package/dist/worker/index.d.ts

@@ -14,7 +14,7 @@
  * Framework-neutral by construction: this entry imports no framework — React's
  * reconciler adapter lives in `@atolljs/react-island/worker`.
  */
-export { definePolyWorker, defineMonoWorker } from './defineWorkers.js';
+export { definePolyWorker, defineMonoWorker, registerIslandApp } from './defineWorkers.js';
 export type { ImperativeIslandApp, Instance, IslandApp, PolyWorkerRegistry, RenderContext, RenderedHandle, RenderedIslandApp, } from './defineWorkers.js';
 export { islandApp, islandAppNameOf } from '../app.js';
 export { defineIslandContract, isIslandContract, withContract, contractOf } from '../contract.js';

package/dist/worker/index.js

@@ -17,7 +17,7 @@ import {
   renderMemory,
   unmarshalCallbackProps,
   withContract
-} from "../chunk-TX4FAHRB.js";
+} from "../chunk-P3G2GL3T.js";
 
 // src/worker/defineWorkers.ts
 import { defineWorker } from "@atolljs/core";
@@ -2321,7 +2321,7 @@ var isImperativeInstance = (r) => r.imperative !== void 0;
 var isRenderedInstance = (r) => r.rendered !== void 0;
 var mounts = /* @__PURE__ */ new Map();
 var APP_REGISTRY = /* @__PURE__ */ new Map();
-var registerSingleApp = (name, app) => {
+var registerIslandApp = (name, app) => {
   APP_REGISTRY.set(name, app);
 };
 var resolveApp = (name) => APP_REGISTRY.get(name) ?? (APP_REGISTRY.size === 1 ? APP_REGISTRY.values().next().value : void 0);
@@ -2332,7 +2332,7 @@ var appNameOf = (instance) => {
   const tilde = name.lastIndexOf("~");
   return tilde === -1 ? name : name.slice(tilde + 1);
 };
-function createIslandRuntime(sharedMemory = renderMemory) {
+function createIslandRuntime(sharedMemory = renderMemory, loadApp) {
   setDoorbellContract(sharedMemory);
   installInstanceDispatcher();
   const parseContractProps = (contract, key, props) => {
@@ -2423,7 +2423,17 @@ function createIslandRuntime(sharedMemory = renderMemory) {
        */
       async mount(instance, props = {}) {
         props = unmarshalCallbackProps(props, callbackFactory(instance));
-        const App = resolveApp(appNameOf(instance));
+        const appName = appNameOf(instance);
+        let App = APP_REGISTRY.get(appName);
+        if (App === void 0 && loadApp !== void 0) {
+          const loaded = await loadApp(appName);
+          if (loaded !== void 0) {
+            registerIslandApp(appName, loaded);
+            App = loaded;
+          }
+        } else if (App === void 0) {
+          App = resolveApp(appName);
+        }
         if (App === void 0) {
           throw new Error(
             `mount: unknown app "${instance}" \u2014 registry has: ${[...APP_REGISTRY.keys()].join(", ")}`
@@ -2603,13 +2613,13 @@ function definePolyWorker(registry, options) {
         `[definePolyWorker] app registered as "${key}" but stamped "${stamped}" \u2014 component-reference mounts resolve "${stamped}" and will fail. Fix the key or the stamp.`
       );
     }
-    registerSingleApp(key, app);
+    registerIslandApp(key, app);
   }
-  return createIslandRuntime(registry.sharedMemory ?? options?.sharedMemory);
+  return createIslandRuntime(registry.sharedMemory ?? options?.sharedMemory, registry.loadApp);
 }
 function defineMonoWorker(app, options) {
   const stamp = app.islandAppName;
-  registerSingleApp(typeof stamp === "string" && stamp !== "" ? stamp : "main", app);
+  registerIslandApp(typeof stamp === "string" && stamp !== "" ? stamp : "main", app);
   return createIslandRuntime(options?.sharedMemory);
 }
 
@@ -3147,6 +3157,7 @@ export {
   proxyInstanceStats,
   pushOp,
   registerHandler,
+  registerIslandApp,
   renderMemory,
   runInInstance,
   serializeProps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/islands",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Atoll islands — MonoWorker/PolyWorker hosts rendering framework islands (React/Vue/Svelte/Solid/Angular) over a proxy-DOM op protocol",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
@@ -29,7 +29,7 @@
     "htmlparser2": "^12.0.0"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.13"
+    "@atolljs/core": "^0.1.15"
   },
   "repository": {
     "type": "git",

package/src/boundary.ts

@@ -0,0 +1,304 @@
+/**
+ * Island error boundaries — a configurable safety net around every
+ * breakable point in a mount's lifecycle:
+ *
+ *   mountIsland({
+ *     worker, el, app,
+ *     boundary: {
+ *       loading: () => spinnerEl,                       // render fn per state
+ *       error: ({ error, retry }) => errorEl,           // …incl. the retry hook
+ *       retry: 3,                                       // auto-remount policy
+ *       onError: (err, phase) => report(err, phase),    // telemetry hook
+ *     },
+ *   })
+ *
+ * Breakable points covered:
+ * - MOUNT: worker entry fails to load, mountTimeout, contract prop
+ *   rejection, federation `loadApp` failures (bad remote URL, unsatisfied
+ *   `requires`) — the mount handshake rejects, the boundary renders the
+ *   error state instead of propagating an unhandled rejection.
+ * - RUNTIME: the worker crashes mid-life. The client's onWorkerEvent
+ *   'error' transition detects it (in-flight tasks already rejected as
+ *   WorkerCrashedError), the stale driver tears down, and the boundary
+ *   enters the error state — `retry()`/auto-retry remounts into the
+ *   respawned worker.
+ *
+ * Render functions are framework-free: they return `Node | string` (or an
+ * array), applied to the island's container element. Loading replaces the
+ * container's contents; the error state replaces them by default —
+ * `domOnError: 'preserve'` appends the fallback over the stale last frame
+ * instead (crash-overlay style).
+ *
+ * The returned handle is an IslandHandle plus `state`/`error`/`retry()` —
+ * it resolves after the FIRST attempt settles (mounted or error state),
+ * so callers never see an unhandled rejection, and a later retry() can
+ * still produce a working island under the same handle.
+ */
+import { connectIslandWorker, mountIsland } from './island';
+import type {
+  ConnectIslandWorkerConfig,
+  IslandClient,
+  IslandHandle,
+  Mode,
+  MountIslandOptions,
+} from './island';
+
+/** What a boundary render fn may return — applied via el.replaceChildren/append. */
+export type BoundaryContent = Node | string | Array<Node | string> | null | undefined;
+
+/** Where the failure happened — 'mount' (handshake), 'runtime' (worker crash). */
+export type IslandBoundaryPhase = 'mount' | 'runtime';
+
+export interface IslandBoundaryContext {
+  /** The mount's app key. */
+  app: string;
+  /** The island's container element — the boundary's render target. */
+  el: HTMLElement;
+  /** 1-based mount attempt counter — increments across retries. */
+  attempt: number;
+}
+
+export interface IslandBoundaryErrorContext extends IslandBoundaryContext {
+  /** The caught failure (mount rejection, crash error). */
+  error: unknown;
+  phase: IslandBoundaryPhase;
+  /** Manual remount — wire it to a retry button in the error render. */
+  retry(): void;
+}
+
+export interface IslandBoundary {
+  /** Rendered while the first mount attempt is in flight. */
+  loading?(ctx: IslandBoundaryContext): BoundaryContent;
+  /** Rendered when the island fails — mount rejection or runtime crash. */
+  error?(ctx: IslandBoundaryErrorContext): BoundaryContent;
+  /** Fires on every boundary-entering failure — logging/telemetry. */
+  onError?(error: unknown, phase: IslandBoundaryPhase): void;
+  /**
+   * Auto-remount policy: a number is the max retry count (delay grows
+   * ~250ms per attempt, capped at 2s); a function maps (attempt, error)
+   * to a delay in ms, `false`/`undefined` to stop. Omit for no auto-retry.
+   */
+  retry?: number | ((attempt: number, error: unknown) => number | false | undefined | void);
+  /**
+   * What the error state does to the container: 'clear' (default) replaces
+   * its contents with the fallback; 'preserve' appends the fallback over
+   * the stale last frame on runtime crashes (mount failures always clear —
+   * there is no frame to preserve).
+   */
+  domOnError?: 'clear' | 'preserve';
+}
+
+export type IslandBoundaryState = 'loading' | 'mounted' | 'error';
+
+/**
+ * The boundary-aware handle: a normal IslandHandle when mounted, safe
+ * no-ops while failed (updateProps stashes into the next attempt's props),
+ * plus the boundary's own state.
+ */
+export interface IslandBoundaryHandle extends IslandHandle {
+  readonly state: IslandBoundaryState;
+  /** The error that put the boundary in 'error' state (undefined otherwise). */
+  readonly error: unknown;
+  /** Remount now — same as ctx.retry() handed to the error render fn. */
+  retry(): void;
+}
+
+export async function mountIslandWithBoundary(
+  opts: MountIslandOptions & { boundary: IslandBoundary },
+): Promise<IslandBoundaryHandle> {
+  const {
+    boundary,
+    el: target,
+    client: givenClient,
+    worker,
+    app: givenApp,
+    props: givenProps,
+    mode: initialMode,
+    ...mountOpts
+  } = opts;
+  // The boundary owns the client when the caller used the `worker`
+  // shorthand — it needs the lifecycle subscription (and clientMounts
+  // accounting keeps last-island-destroy → terminate semantics identical).
+  const client: IslandClient =
+    givenClient ??
+    connectIslandWorker({
+      name: givenApp,
+      ...mountOpts,
+      worker,
+      doorbell: initialMode !== 'poll',
+    } as ConnectIslandWorkerConfig);
+  const app = givenApp ?? 'main';
+  // mountIsland only routes here for REAL mount targets — proxy elements
+  // take the nested path before the boundary check.
+  const el = target as HTMLElement;
+
+  let state: IslandBoundaryState = 'loading';
+  let lastError: unknown;
+  let current: IslandHandle | null = null;
+  let attempt = 0;
+  let destroyed = false;
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Latest props — updateProps while failed stashes here for the remount. */
+  let pendingProps = givenProps;
+  let pendingMode: Mode | undefined = initialMode;
+
+  const setContent = (content: BoundaryContent, how: 'replace' | 'append'): void => {
+    if (content === null || content === undefined) {
+      if (how === 'replace') el.replaceChildren();
+      return;
+    }
+    const parts = (Array.isArray(content) ? content : [content]).filter(
+      (p): p is Node | string => p !== null && p !== undefined,
+    );
+    if (how === 'replace') el.replaceChildren(...parts);
+    else el.append(...parts);
+  };
+
+  const scheduleRetry = (error: unknown): void => {
+    const policy = boundary.retry;
+    if (policy === undefined || retryTimer !== null) return;
+    const delay =
+      typeof policy === 'number'
+        ? attempt <= policy
+          ? Math.min(250 * attempt, 2000)
+          : false
+        : policy(attempt, error);
+    if (delay === false || delay === undefined || typeof delay !== 'number') return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void tryMount();
+    }, Math.max(0, delay));
+  };
+
+  const fail = (error: unknown, phase: IslandBoundaryPhase): void => {
+    if (destroyed) return;
+    state = 'error';
+    lastError = error;
+    boundary.onError?.(error, phase);
+    const content = boundary.error?.({
+      app,
+      el,
+      attempt,
+      error,
+      phase,
+      retry: manualRetry,
+    });
+    // Runtime 'preserve' paints over the stale frame; everything else
+    // replaces (mount failures never produced a frame worth keeping).
+    if (boundary.domOnError === 'preserve' && phase === 'runtime') {
+      setContent(content, 'append');
+    } else {
+      setContent(content, 'replace');
+    }
+    scheduleRetry(error);
+  };
+
+  const tryMount = async (): Promise<void> => {
+    if (destroyed) return;
+    attempt++;
+    // The worker's mount batch assumes an empty container — stale frames,
+    // loading content, and error fallbacks all clear before it replays.
+    el.replaceChildren();
+    try {
+      const handle = await mountIsland({
+        ...mountOpts,
+        client,
+        el,
+        app: givenApp,
+        props: pendingProps,
+        mode: pendingMode,
+      } as MountIslandOptions);
+      if (destroyed) {
+        handle.destroy();
+        return;
+      }
+      current = handle;
+      state = 'mounted';
+    } catch (err) {
+      fail(err, 'mount');
+    }
+  };
+
+  const manualRetry = (): void => {
+    if (destroyed) return;
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+    void tryMount();
+  };
+
+  // Worker-death detection: the client's lifecycle events fire on the
+  // runner's 'error' transition — every instance on this client just died.
+  // Shared clients notify each island's boundary individually.
+  const offLifecycle = client.onWorkerEvent?.((event) => {
+    if (destroyed || state === 'error' || event.type !== 'error') return;
+    const stale = current;
+    current = null;
+    // Tear the dead driver down — stops doorbell/poll/RO timers and
+    // releases instance state (its unmount task rejects, which destroy
+    // already swallows; a last-island terminate races the runner's own
+    // respawn harmlessly).
+    stale?.destroy();
+    fail(
+      new Error(
+        `[island ${app}] worker crashed` + (event.message !== undefined ? `: ${event.message}` : ''),
+      ),
+      'runtime',
+    );
+  });
+
+  const handle: IslandBoundaryHandle = {
+    get app() {
+      return current?.app ?? app;
+    },
+    get pid() {
+      return current?.pid ?? 'unmounted';
+    },
+    get instance() {
+      return current?.instance ?? `${app}@?`;
+    },
+    get mode() {
+      return current?.mode ?? pendingMode ?? 'push';
+    },
+    get opsApplied() {
+      return current?.opsApplied ?? 0;
+    },
+    get flushCalls() {
+      return current?.flushCalls ?? 0;
+    },
+    get state() {
+      return state;
+    },
+    get error() {
+      return lastError;
+    },
+    retry: manualRetry,
+    setMode: (mode) => {
+      pendingMode = mode;
+      current?.setMode(mode);
+    },
+    updateProps: async (next) => {
+      pendingProps = next;
+      await current?.updateProps(next);
+    },
+    flush: async () => {
+      await current?.flush();
+    },
+    destroy: () => {
+      if (destroyed) return;
+      destroyed = true;
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
+      offLifecycle?.();
+      current?.destroy();
+      current = null;
+    },
+  };
+
+  setContent(boundary.loading?.({ app, el, attempt: 1 }), 'replace');
+  await tryMount();
+  return handle;
+}

package/src/index.ts

@@ -22,6 +22,17 @@ export type {
   MountIslandOptions,
 } from './island';
 
+export { mountIslandWithBoundary } from './boundary';
+export type {
+  BoundaryContent,
+  IslandBoundary,
+  IslandBoundaryContext,
+  IslandBoundaryErrorContext,
+  IslandBoundaryHandle,
+  IslandBoundaryPhase,
+  IslandBoundaryState,
+} from './boundary';
+
 export { makeDoorbell } from './memory';
 export type { DoorbellSpec } from './memory';
 

package/src/island.ts

@@ -44,6 +44,8 @@ import {
 import { marshalCallbackProps, CALLBACK_EVENT } from './callbackProps';
 import { trackIslandForDevtools } from './devtoolsCommands';
 import { propsPreview } from './devtoolsPreview';
+import { mountIslandWithBoundary } from './boundary';
+import type { IslandBoundary, IslandBoundaryHandle } from './boundary';
 import type { ProxyElement } from './worker/dom/element';
 
 export type Mode = 'push' | 'poll';
@@ -189,6 +191,15 @@ interface MountIslandBaseOptions {
    * client warm for this island's teardown.
    */
   keepAlive?: boolean;
+  /**
+   * Error boundary — `loading`/`error` state render functions plus a retry
+   * policy, covering mount rejection, mountTimeout, and runtime worker
+   * crashes (detected via the client's lifecycle events). When set, the
+   * mount resolves to an `IslandBoundaryHandle` after the first attempt
+   * settles — errors render the fallback instead of rejecting. Ignored on
+   * nested (proxy-element) mounts. See boundary.ts / docs error-boundaries.
+   */
+  boundary?: IslandBoundary;
 }
 
 /**
@@ -471,10 +482,15 @@ export const registerSubIslandMounter = (
 const isProxyMountTarget = (el: unknown): el is ProxyElement =>
   typeof (el as { doc?: { instance?: unknown } } | null)?.doc?.instance === 'string';
 
+export function mountIsland(
+  opts: MountIslandOptions & { boundary: IslandBoundary },
+): Promise<IslandBoundaryHandle>;
+export function mountIsland(opts: MountIslandOptions): Promise<IslandHandle>;
 export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandle> {
   const {
     el: target, onEvent, onActivity, onOps, slots, mode: initialMode, mountTimeout,
     client: givenClient, worker, app: givenApp, props: givenProps, framework,
+    boundary,
     ...workerConfig
   } = opts;
   if (isProxyMountTarget(target)) {
@@ -489,6 +505,12 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
   // Real DOM from here on (the proxy path delegated above) — the declared
   // type keeps closures honest; the guard did the proving.
   const el = target as HTMLElement;
+  if (boundary !== undefined) {
+    // Error-boundary path — mount/handshake failures and runtime worker
+    // crashes render state fallbacks instead of rejecting; the returned
+    // handle wraps the eventual island. Nested mounts ignore the option.
+    return mountIslandWithBoundary(opts as MountIslandOptions & { boundary: IslandBoundary });
+  }
   // Shell→worker callables: callbackProp() markers marshal to {__cb:id}
   // wire handles; the island's table keeps the real functions and the
   // driver's emit-case routes worker-side invocations back here.

package/src/worker/defineWorkers.ts

@@ -170,6 +170,16 @@ export interface PolyWorkerRegistry {
   /** Name → island app registry. The shell's `mountIsland({ app: name })`
    *  picks one per island. */
   apps: Record<string, IslandApp>;
+  /**
+   * Lazy app loader — consulted by `mount` when the requested registry name
+   * isn't present yet. Returning an app registers it under that name (so a
+   * second mount is a registry hit); returning `undefined` lets the mount
+   * fail as unknown. Federation hosts pass a remote-module importer here —
+   * see `@atolljs/federation`. When set, the single-registered-app
+   * name-blind fallback is DISABLED: a loader host resolves every mount by
+   * its exact registry key, never by "the only app I have".
+   */
+  loadApp?: (name: string) => IslandApp | undefined | Promise<IslandApp | undefined>;
   /**
    * The doorbell contract the worker exposes — defaults to the package's
    * `renderMemory`. Rarely needed: pass a different doorbell-SPEC instance
@@ -259,7 +269,13 @@ const mounts = new Map<string, Instance>();
  */
 const APP_REGISTRY = new Map<string, IslandApp>();
 
-const registerSingleApp = (name: string, app: IslandApp): void => {
+/**
+ * Register an app into the module-level registry after the definer ran —
+ * the manual counterpart to `loadApp` (warm-up/preload outside a mount).
+ * Registers under `name` exactly; the mount-time name-blind fallback only
+ * applies to single-registry workers without a loader.
+ */
+export const registerIslandApp = (name: string, app: IslandApp): void => {
   APP_REGISTRY.set(name, app);
 };
 
@@ -292,6 +308,7 @@ const appNameOf = (instance: string): string => {
  */
 function createIslandRuntime(
   sharedMemory: SharedMemory<DoorbellSpec> = renderMemory,
+  loadApp?: PolyWorkerRegistry['loadApp'],
 ): WorkerDefinition<DoorbellSpec, IslandWorkerMethods> {
   // Point bumpOpsVersion at the declared contract (it's the same object as
   // renderMemory unless a custom doorbell instance was passed).
@@ -435,7 +452,20 @@ function createIslandRuntime(
         // marshalled function (fire-and-forget, doorbell-rung for out-of-
         // task callers like timers/promise continuations).
         props = unmarshalCallbackProps(props, callbackFactory(instance)) as Record<string, unknown>;
-        const App = resolveApp(appNameOf(instance));
+        const appName = appNameOf(instance);
+        let App = APP_REGISTRY.get(appName);
+        if (App === undefined && loadApp !== undefined) {
+          // Lazy registration — the loader imports a remote module (federation)
+          // or otherwise supplies the app; a defined result registers under
+          // the requested name so subsequent mounts resolve directly.
+          const loaded = await loadApp(appName);
+          if (loaded !== undefined) {
+            registerIslandApp(appName, loaded);
+            App = loaded;
+          }
+        } else if (App === undefined) {
+          App = resolveApp(appName); // sole-app fallback (no loader present)
+        }
         if (App === undefined) {
           throw new Error(
             `mount: unknown app "${instance}" — registry has: ${[...APP_REGISTRY.keys()].join(', ')}`,
@@ -684,9 +714,9 @@ export function definePolyWorker(
           `component-reference mounts resolve "${stamped}" and will fail. Fix the key or the stamp.`,
       );
     }
-    registerSingleApp(key, app);
+    registerIslandApp(key, app);
   }
-  return createIslandRuntime(registry.sharedMemory ?? options?.sharedMemory);
+  return createIslandRuntime(registry.sharedMemory ?? options?.sharedMemory, registry.loadApp);
 }
 
 /**
@@ -700,6 +730,6 @@ export function defineMonoWorker(
   options?: { sharedMemory?: SharedMemory<DoorbellSpec> },
 ): WorkerDefinition<DoorbellSpec, IslandWorkerMethods> {
   const stamp = (app as { islandAppName?: unknown }).islandAppName;
-  registerSingleApp(typeof stamp === 'string' && stamp !== '' ? stamp : 'main', app);
+  registerIslandApp(typeof stamp === 'string' && stamp !== '' ? stamp : 'main', app);
   return createIslandRuntime(options?.sharedMemory);
 }

package/src/worker/index.ts

@@ -14,7 +14,7 @@
  * Framework-neutral by construction: this entry imports no framework — React's
  * reconciler adapter lives in `@atolljs/react-island/worker`.
  */
-export { definePolyWorker, defineMonoWorker } from './defineWorkers';
+export { definePolyWorker, defineMonoWorker, registerIslandApp } from './defineWorkers';
 export type {
   ImperativeIslandApp,
   Instance,