@preact-mvc/atoll-island 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,78 @@
+# @preact-mvc/atoll-island
+
+[![CI](https://github.com/jwhenry3/preact-mvc/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jwhenry3/preact-mvc/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jwhenry3/preact-mvc/graph/badge.svg?branch=main)](https://codecov.io/gh/jwhenry3/preact-mvc)
+[![Socket Badge](https://badge.socket.dev/npm/package/@preact-mvc/atoll-island)](https://badge.socket.dev/npm/package/@preact-mvc/atoll-island)
+
+The PreactMVC adapter for `@preact-mvc/atoll` worker islands — the
+`*-island` half of the angular/react vs `*-island` pattern. On the shell,
+`islandComponent(contract)` turns a shared contract into a mountable
+component. In the worker, `viewIslandApp` + `defineViewPolyWorker` render
+`View` classes (or any component) against the proxy DOM, so island views
+get the same DI, modules, lifecycle, and signals as main-thread views.
+
+**[PreactMVC — island documentation](https://jwhenry3.github.io/preact-mvc/docs/island-apps/)**
+
+## Install
+
+```bash
+npm install @preact-mvc/atoll-island @preact-mvc/core @preact-mvc/atoll
+```
+
+## Contract → component → island
+
+```ts
+// islands/ticker.contract.ts — imported by BOTH sides
+import { defineIslandContract, z } from '@preact-mvc/atoll-island';
+
+export const tickerContract = defineIslandContract({
+  app: 'ticker',
+  events: { 'worker-ping': z.object({ count: z.number() }) },
+  worker: () =>
+    new Worker(new URL('../workers/ticker.worker.tsx', import.meta.url), {
+      type: 'module',
+    }),
+});
+```
+
+```tsx
+// workers/ticker.worker.tsx — the worker entry
+import { Component, View, signal } from '@preact-mvc/core';
+import { defineViewPolyWorker, viewIslandApp } from '@preact-mvc/atoll-island/worker';
+import { tickerContract } from '../islands/ticker.contract';
+
+@Component()
+class TickerIsland extends View {
+  /* signals, inject(), lifecycle — same as main thread */
+}
+
+export const worker = defineViewPolyWorker({
+  apps: { ticker: viewIslandApp(TickerIsland, { contract: tickerContract }) },
+});
+```
+
+```tsx
+// views/demo.view.tsx — the shell mount
+import { islandComponent } from '@preact-mvc/atoll-island';
+import { tickerContract } from '../islands/ticker.contract';
+
+const TickerIsland = islandComponent(tickerContract);
+// <TickerIsland onEvent={(e) => …} />
+```
+
+## Shell surface
+
+- `<Island/>` — low-level mount element (driver + options by hand).
+- `islandComponent(contract | app)` — the typed facade; props/emit/events
+  flow through the contract.
+- `lazyIsland(loader)` — code-split a contract's mount.
+- `viewIsland(App)` — mount a single component as a one-off island.
+
+## Worker surface (`@preact-mvc/atoll-island/worker`)
+
+- `viewIslandApp(Component, { contract })` — the worker renderer: views
+  render against the proxy DOM, every mutation serializing to ops.
+- `defineViewPolyWorker({ apps })` — one worker hosting many islands;
+  `defineViewMonoWorker` for a dedicated single app.
+
+Published builds ship compiled `dist/` (`.js` + `.d.ts`).

package/dist/adapter.d.ts

@@ -0,0 +1,32 @@
+import type { ComponentType } from 'preact';
+import { type Provider } from '@preact-mvc/core';
+import { type ImperativeIslandApp, type IslandContract, type IslandWorkerDef, type RenderedIslandApp } from '@preact-mvc/atoll/worker';
+type AnyComponent = ComponentType<Record<string, unknown>>;
+export interface ViewIslandAppOptions {
+    /** Providers for the island's root injector — the island-side equivalent
+     *  of `bootstrap(AppModule, providers)`. */
+    providers?: Provider[];
+    /** Attach a `defineIslandContract` contract: mount/updateProps props are
+     *  validated against its schema, and declared `emit` payloads are
+     *  checked worker-side. */
+    contract?: IslandContract;
+}
+/** Wrap a View class or function component as a `RenderedIslandApp`. */
+export declare function viewIslandApp(App: AnyComponent, opts?: ViewIslandAppOptions): RenderedIslandApp;
+/** Stamp + wrap in one step — `viewIsland('counter', CounterView)` yields
+ *  both the registry value and the name the shell mounts by. */
+export declare const viewIsland: (name: string, App: AnyComponent, opts?: ViewIslandAppOptions) => RenderedIslandApp & {
+    readonly islandAppName: string;
+};
+export interface ViewPolyWorkerRegistry {
+    /** Name → component (or `{ imperative }` app / pre-wrapped app). Plain
+     *  components pass through `viewIslandApp`. */
+    apps: Record<string, AnyComponent | ImperativeIslandApp | RenderedIslandApp>;
+}
+/** `definePolyWorker` for framework views — maps each component in the
+ *  registry through `viewIslandApp` and delegates. */
+export declare function defineViewPolyWorker(registry: ViewPolyWorkerRegistry): IslandWorkerDef;
+/** `defineMonoWorker` for a single framework view — the isolated-bundle
+ *  host shape (own worker, own failure domain). */
+export declare function defineViewMonoWorker(app: AnyComponent | ImperativeIslandApp | RenderedIslandApp, opts?: ViewIslandAppOptions): IslandWorkerDef;
+export {};

package/dist/adapter.js

@@ -0,0 +1,174 @@
+/**
+ * The framework renderer adapter — our `*-island` package's renderer half
+ * (docs/atoll/islands-frameworks.md). `viewIslandApp(Component)` wraps a
+ * `View` class or function component as a `RenderedIslandApp`; each mount
+ * renders into the instance's proxy document via Preact, so every DOM
+ * mutation serializes to ops.
+ *
+ * `defineViewPolyWorker`/`defineViewMonoWorker` are the single-framework
+ * convenience definers — they wrap plain components automatically:
+ *
+ *   // render.worker.ts
+ *   export const worker = defineViewPolyWorker({
+ *     apps: { counter: CounterView, clock: ClockView },
+ *   });
+ *
+ * DI inside islands: the app gets a fresh root injector per instance —
+ * worker-side injectables (stores, controllers) live in the worker, and
+ * `@Component({ providers/imports/controllers })` metadata works unchanged
+ * because the View host machinery runs in the worker too.
+ */
+import { h, options, render } from 'preact';
+import { Injector, InjectorContext } from '@preact-mvc/core';
+import { defineMonoWorker, definePolyWorker, islandApp, islandAppNameOf, enterInstance, exitInstance, getActiveInstance, withContract, ProxyElement, } from '@preact-mvc/atoll/worker';
+const ISLAND_KEY = '__islandInstance';
+const PREV_KEY = '__islandPrevScope';
+/**
+ * Instance-scoped rendering for OUT-OF-TASK renders. Mount/updateProps run
+ * inside `runInInstance`, but signal-driven re-renders are deferred by
+ * Preact to a microtask with no active scope — ambient `document` would
+ * resolve via the last-active heuristic and could create nodes on a SIBLING
+ * island's document (in shared-client/in-process topologies).
+ *
+ * Fix: every root vnode is stamped `__islandInstance`; `options.__r` walks
+ * the `__` parent chain before each component render and enters that
+ * instance's scope; `options.diffed` restores. Deterministic, and strictly
+ * better than the ambient heuristic.
+ */
+let renderScopeInstalled = false;
+function installRenderScope() {
+    if (renderScopeInstalled)
+        return;
+    renderScopeInstalled = true;
+    const opts = options;
+    const prevR = opts.__r;
+    const prevD = opts.diffed;
+    opts.__r = (vnode) => {
+        let v = vnode;
+        let key;
+        while (v) {
+            if (v[ISLAND_KEY]) {
+                key = v[ISLAND_KEY];
+                break;
+            }
+            v = v.__ ?? null;
+        }
+        if (key && key !== getActiveInstance())
+            vnode[PREV_KEY] = enterInstance(key);
+        prevR?.(vnode);
+    };
+    opts.diffed = (vnode) => {
+        prevD?.(vnode);
+        const v = vnode;
+        if (PREV_KEY in v) {
+            exitInstance(v[PREV_KEY] ?? null);
+            delete v[PREV_KEY];
+        }
+    };
+}
+let eventBridgeInstalled = false;
+function installEventNameBridge() {
+    if (eventBridgeInstalled)
+        return;
+    eventBridgeInstalled = true;
+    /** element → original fn → prop-sliced type → wrapped fn */
+    const bridged = new WeakMap();
+    // Prop-sliced PascalCase → the real lowercase DOM type. Only the
+    // PascalCase shape is rewritten: 'MouseLeave' → 'mouseleave',
+    // 'DblClick' → 'dblclick'. All-caps ('DOMContentLoaded'), lowercase
+    // ('click'), and camelCase custom types pass through — lowercasing
+    // 'DOMContentLoaded' would break it the other way.
+    const decap = (type) => type.length > 1 &&
+        type[0] === type[0].toUpperCase() &&
+        type[1] === type[1].toLowerCase()
+        ? type.toLowerCase()
+        : type;
+    const proto = ProxyElement.prototype;
+    const origAdd = proto.addEventListener;
+    const origRemove = proto.removeEventListener;
+    proto.addEventListener = function (type, fn, opts) {
+        const dom = decap(type);
+        let effective = fn;
+        if (dom !== type) {
+            effective = function (e) {
+                fn.call(this, { ...e, type });
+            };
+            let byFn = bridged.get(this);
+            if (byFn === undefined)
+                bridged.set(this, (byFn = new Map()));
+            let byType = byFn.get(fn);
+            if (byType === undefined)
+                byFn.set(fn, (byType = new Map()));
+            byType.set(type, effective);
+        }
+        origAdd.call(this, dom, effective, opts);
+    };
+    proto.removeEventListener = function (type, fn, opts) {
+        const effective = bridged.get(this)?.get(fn)?.get(type) ?? fn;
+        origRemove.call(this, decap(type), effective, opts);
+    };
+}
+/** Wrap a View class or function component as a `RenderedIslandApp`. */
+export function viewIslandApp(App, opts) {
+    installRenderScope();
+    installEventNameBridge();
+    const app = {
+        renderer: 'preact-mvc',
+        mount({ instance, doc, props }) {
+            const inj = new Injector(undefined, `island ${instance}`);
+            for (const p of opts?.providers ?? [])
+                inj.provide(p);
+            let current = props;
+            const renderRoot = (p) => {
+                current = p;
+                const vnode = h(InjectorContext.Provider, { value: inj }, h(App, p));
+                vnode[ISLAND_KEY] = instance;
+                render(vnode, doc.body);
+            };
+            renderRoot(props);
+            return {
+                update: renderRoot,
+                // The dispatch task's sync lane: run the event handler, then
+                // re-render synchronously (Preact's render() IS the flush — signal
+                // writes would otherwise defer to a microtask and their ops would
+                // miss this task's batch, surfacing a poll later).
+                sync: (fn) => {
+                    fn();
+                    renderRoot(current);
+                },
+                dispose: () => {
+                    try {
+                        render(null, doc.body);
+                    }
+                    finally {
+                        inj.deactivate();
+                    }
+                },
+            };
+        },
+    };
+    const stamp = islandAppNameOf(App);
+    if (stamp !== undefined)
+        app.islandAppName = stamp;
+    return opts?.contract !== undefined ? withContract(opts.contract, app) : app;
+}
+/** Stamp + wrap in one step — `viewIsland('counter', CounterView)` yields
+ *  both the registry value and the name the shell mounts by. */
+export const viewIsland = (name, App, opts) => islandApp(name, viewIslandApp(App, opts));
+/** `definePolyWorker` for framework views — maps each component in the
+ *  registry through `viewIslandApp` and delegates. */
+export function defineViewPolyWorker(registry) {
+    installRenderScope();
+    const apps = {};
+    for (const [key, app] of Object.entries(registry.apps)) {
+        apps[key] = typeof app === 'function' ? viewIslandApp(app) : app;
+    }
+    return definePolyWorker({ apps });
+}
+/** `defineMonoWorker` for a single framework view — the isolated-bundle
+ *  host shape (own worker, own failure domain). */
+export function defineViewMonoWorker(app, opts) {
+    installRenderScope();
+    const resolved = typeof app === 'function' ? viewIslandApp(app, opts) : app;
+    return defineMonoWorker(resolved);
+}

package/{src/index.ts → dist/index.d.ts}

@@ -1,7 +1,7 @@
 /**
  * `@preact-mvc/atoll-island` — the `*-island` package's shell surface
  * (docs/atoll/islands-frameworks.md): mount a worker-hosted island tree as
- * an ordinary element in a preact-mvc app. The worker-side renderer
+ * an ordinary element in a PreactMVC app. The worker-side renderer
  * (viewIslandApp, defineViewPolyWorker) lives in the `./worker` entry.
  *
  * The facade pattern: a contract module (`defineIslandContract`) names the
@@ -13,37 +13,6 @@
  * code only needs this one package.
  */
 export { Island, islandComponent, lazyIsland } from './shell';
-export type {
-  IslandAppRef,
-  IslandFacadeProps,
-  IslandProps,
-  IslandShellProps,
-} from './shell';
-export {
-  callbackProp,
-  connectIslandWorker,
-  contractOf,
-  contractWorkerOf,
-  defineIslandContract,
-  isIslandContract,
-  islandApp,
-  islandAppNameOf,
-  mountIsland,
-  withContract,
-  z,
-} from '@preact-mvc/atoll';
-export type {
-  ConnectOptions,
-  IslandAppProps,
-  IslandClient,
-  IslandContract,
-  IslandContractEventHandler,
-  IslandContractEvents,
-  IslandContractProps,
-  IslandHandle,
-  IslandWorkerOptions,
-  Mode,
-  MountOptions,
-  Schema,
-  WorkerLike,
-} from '@preact-mvc/atoll';
+export type { IslandAppRef, IslandFacadeProps, IslandProps, IslandShellProps, } from './shell';
+export { callbackProp, connectIslandWorker, contractOf, contractWorkerOf, defineIslandContract, isIslandContract, islandApp, islandAppNameOf, mountIsland, withContract, z, } from '@preact-mvc/atoll';
+export type { ConnectOptions, IslandAppProps, IslandClient, IslandContract, IslandContractEventHandler, IslandContractEvents, IslandContractProps, IslandHandle, IslandWorkerOptions, Mode, MountOptions, Schema, WorkerLike, } from '@preact-mvc/atoll';

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@preact-mvc/atoll-island` — the `*-island` package's shell surface
+ * (docs/atoll/islands-frameworks.md): mount a worker-hosted island tree as
+ * an ordinary element in a PreactMVC app. The worker-side renderer
+ * (viewIslandApp, defineViewPolyWorker) lives in the `./worker` entry.
+ *
+ * The facade pattern: a contract module (`defineIslandContract`) names the
+ * app, declares the wire schemas, and carries the worker factory — the
+ * view imports the contract only and mounts `islandComponent(contract)`
+ * with no worker plumbing at the call site.
+ *
+ * The driver/mount API is re-exported from `@preact-mvc/atoll` so shell
+ * code only needs this one package.
+ */
+export { Island, islandComponent, lazyIsland } from './shell';
+export { callbackProp, connectIslandWorker, contractOf, contractWorkerOf, defineIslandContract, isIslandContract, islandApp, islandAppNameOf, mountIsland, withContract, z, } from '@preact-mvc/atoll';

package/dist/shell.d.ts

@@ -0,0 +1,77 @@
+import type { ComponentChildren, FunctionComponent } from 'preact';
+import type { IslandAppProps, IslandClient, IslandContract, IslandContractEventHandler, IslandContractProps, IslandHandle, IslandWorkerOptions, Mode, WorkerLike } from '@preact-mvc/atoll';
+/** Props consumed by a proxy component itself — everything else forwards to
+ *  the island as its props. */
+export interface IslandShellProps {
+    /** Bundler-detectable factory `() => new Worker(new URL(...))` (or a URL
+     *  / spawned worker). Optional when `app` is a contract carrying its own
+     *  worker — the contract module is then the whole connection. */
+    worker?: WorkerLike | (() => WorkerLike) | URL;
+    /** A shared `connectIslandWorker` client — this mount adds an instance. */
+    client?: IslandClient;
+    /** Client options for `worker`-shorthand mounts (taskTimeout, respawn,
+     *  lazy, doorbell). `doorbell: true` needs cross-origin isolation. */
+    workerOptions?: IslandWorkerOptions & {
+        doorbell?: boolean;
+    };
+    /** 'push' rides the doorbell SAB (COOP/COEP); 'poll' (default) is
+     *  message-only — no headers needed. */
+    mode?: Mode;
+    /** Devtools renderer tag. */
+    framework?: string;
+    /** Receives every worker-side `emit(name, payload)`. */
+    onEvent?: (name: string, payload: unknown) => void;
+    /** Fired after each applied op batch. */
+    onActivity?: () => void;
+    /** The mounted handle (pid, updateProps, flush, setMode…) once ready. */
+    onReady?: (island: IslandHandle) => void;
+    /** Mount/update errors surface here instead of an unhandled rejection. */
+    onError?: (err: unknown) => void;
+    /** `data-atoll-slot` transclusion holes: worker owns the box, shell owns
+     *  the contents. */
+    slots?: Record<string, (el: HTMLElement | null) => void>;
+    /** Rendered while the worker mounts (lazy facades). */
+    fallback?: ComponentChildren;
+    className?: string;
+    style?: string | Record<string, string | number>;
+    mountTimeout?: number;
+    children?: ComponentChildren;
+}
+export interface IslandProps extends IslandShellProps {
+    /** Registry key, stamped app (`islandApp`/`viewIsland`), or contract —
+     *  resolved through `islandAppNameOf`. */
+    app?: unknown;
+    /** Structured-cloneable props (functions via `callbackProp`). */
+    props?: Record<string, unknown>;
+}
+export declare const Island: FunctionComponent<IslandProps>;
+/** What `app` accepts on a facade: the registry name, or a reference to
+ *  resolve (component, stamped app, contract). */
+export type IslandAppRef<A> = A | string;
+export type IslandFacadeProps<A> = Omit<IslandShellProps, 'onEvent'> & IslandAppProps<A> & {
+    props?: Record<string, unknown>;
+    onEvent?: (name: string, payload: unknown) => void;
+};
+/**
+ * `islandComponent(contract)` — the cross-framework facade: the component's
+ * props are the island's props (from the contract's schema), `onEvent`
+ * narrows to the declared event vocabulary, and the contract's own worker
+ * factory means call sites pass NO worker/client at all. The shell imports
+ * the contract module only — never the worker entry or the island's code.
+ *
+ * `islandComponent<P>('charts')` — the string-keyed form for registries
+ * whose workers the shell already knows.
+ */
+export declare function islandComponent<C extends IslandContract>(app: C): FunctionComponent<IslandContractProps<C> & Omit<IslandShellProps, 'onEvent'> & {
+    props?: Record<string, unknown>;
+    onEvent?: IslandContractEventHandler<C>;
+}>;
+export declare function islandComponent<A>(app: A | string): FunctionComponent<IslandFacadeProps<A>>;
+/**
+ * `lazyIsland(() => import('./counter.contract'))` — the module must export
+ * a contract (`defineIslandContract` — app + worker factory in one object),
+ * a stamped app (`viewIsland('counter', CounterView)`), or a default export
+ * resolvable by `islandAppNameOf`. A contract's own worker factory is used
+ * when no `worker` prop is passed.
+ */
+export declare function lazyIsland<A>(load: () => Promise<Record<string, unknown>>): FunctionComponent<IslandFacadeProps<A>>;

package/dist/shell.js

@@ -0,0 +1,152 @@
+import { jsxs as _jsxs, jsx as _jsx } from "preact/jsx-runtime";
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { connectIslandWorker, contractWorkerOf, islandAppNameOf, isIslandContract, mountIsland, } from '@preact-mvc/atoll';
+export const Island = (p) => {
+    const ref = useRef(null);
+    const handle = useRef(null);
+    const [failed, setFailed] = useState(null);
+    // 'main' mounts a mono worker's sole app namelessly; registries error
+    // with the key list if 'main' isn't a real key.
+    const appName = p.app === undefined ? 'main' : islandAppNameOf(p.app);
+    // Mount once per app — worker/client/app are identity; change via `key`.
+    useEffect(() => {
+        if (appName === undefined) {
+            setFailed(new Error('<Island> could not resolve an app name — pass the registry key ' +
+                'or stamp the app with islandApp(name, app)'));
+            return;
+        }
+        const mode = p.mode ?? 'poll';
+        // A contract `app` can carry its own worker factory — the contract
+        // module is then the whole connection, call sites pass no worker.
+        const resolvedWorker = p.worker ?? contractWorkerOf(p.app);
+        const client = p.client ??
+            (resolvedWorker !== undefined
+                ? connectIslandWorker({
+                    name: appName,
+                    worker: resolvedWorker,
+                    doorbell: mode !== 'poll',
+                    ...p.workerOptions,
+                })
+                : undefined);
+        if (client === undefined) {
+            setFailed(new Error('<Island> requires either `worker`, `client`, or a contract carrying `worker`'));
+            return;
+        }
+        let cancelled = false;
+        mountIsland({
+            el: ref.current,
+            client,
+            app: appName,
+            props: p.props,
+            onEvent: p.onEvent,
+            onActivity: p.onActivity,
+            slots: p.slots,
+            mode,
+            framework: p.framework,
+            mountTimeout: p.mountTimeout,
+        })
+            .then((h) => {
+            if (cancelled)
+                h.destroy();
+            else {
+                handle.current = h;
+                p.onReady?.(h);
+            }
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            if (p.onError)
+                p.onError(err);
+            else
+                setFailed(err instanceof Error ? err : new Error(String(err)));
+        });
+        return () => {
+            cancelled = true;
+            handle.current?.destroy();
+            handle.current = null;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [appName, p.client]);
+    // Prop updates flow through the handle — deduped by wire-serialized
+    // identity; a repeat send would be a wasted round-trip.
+    const propsJson = JSON.stringify(p.props ?? {});
+    useEffect(() => {
+        handle.current?.updateProps(p.props ?? {});
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [propsJson]);
+    if (failed) {
+        return (_jsxs("div", { class: "island-error", style: { border: '1px solid #c00', padding: '0.5em' }, children: ["Island mount failed: ", failed.message] }));
+    }
+    return _jsx("div", { ref: ref, class: p.className, style: p.style });
+};
+/** Props consumed by a facade component itself — everything else forwards
+ *  to the island as its props. */
+const SHELL_PROP_KEYS = new Set([
+    'worker',
+    'client',
+    'workerOptions',
+    'mode',
+    'framework',
+    'onEvent',
+    'onActivity',
+    'onReady',
+    'onError',
+    'slots',
+    'fallback',
+    'className',
+    'style',
+    'mountTimeout',
+    'children',
+]);
+const splitProxyProps = (raw) => {
+    const shell = {};
+    const islandProps = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (SHELL_PROP_KEYS.has(key))
+            shell[key] = value;
+        else
+            islandProps[key] = value;
+    }
+    return { shell: shell, islandProps };
+};
+export function islandComponent(app) {
+    const Facade = ({ props, ...raw }) => {
+        const { shell, islandProps } = splitProxyProps(raw);
+        return _jsx(Island, { app: app, props: { ...islandProps, ...(props ?? {}) }, ...shell });
+    };
+    Facade.displayName = `Island(${islandAppNameOf(app) ?? 'main'})`;
+    return Facade;
+}
+/**
+ * `lazyIsland(() => import('./counter.contract'))` — the module must export
+ * a contract (`defineIslandContract` — app + worker factory in one object),
+ * a stamped app (`viewIsland('counter', CounterView)`), or a default export
+ * resolvable by `islandAppNameOf`. A contract's own worker factory is used
+ * when no `worker` prop is passed.
+ */
+export function lazyIsland(load) {
+    const Lazy = (p) => {
+        const [app, setApp] = useState(null);
+        useEffect(() => {
+            let live = true;
+            void load().then((mod) => {
+                if (!live)
+                    return;
+                const unwrapped = 'default' in mod ? mod.default : mod;
+                const resolved = isIslandContract(unwrapped) ? unwrapped
+                    : Object.values(mod).find((v) => isIslandContract(v)) ??
+                        Object.values(mod).find((v) => v && typeof v === 'object' && 'islandAppName' in v) ??
+                        unwrapped;
+                setApp(() => resolved);
+            });
+            return () => {
+                live = false;
+            };
+        }, []);
+        if (!app)
+            return _jsx("div", { class: p.className, style: p.style, children: p.fallback });
+        return _jsx(Island, { ...p, app: app });
+    };
+    return Lazy;
+}

package/{src/worker.ts → dist/worker.d.ts}

@@ -12,12 +12,7 @@
  * `@preact-mvc/atoll/worker` so a worker entry needs no direct atoll-core
  * import (same convention as Atoll's `*-island` packages).
  */
-export {
-  viewIslandApp,
-  viewIsland,
-  defineViewPolyWorker,
-  defineViewMonoWorker,
-} from './adapter';
+export { viewIslandApp, viewIsland, defineViewPolyWorker, defineViewMonoWorker, } from './adapter';
 export type { ViewIslandAppOptions, ViewPolyWorkerRegistry } from './adapter';
 /**
  * The mount components on the worker side — same surface as the shell
@@ -28,39 +23,7 @@ export type { ViewIslandAppOptions, ViewPolyWorkerRegistry } from './adapter';
  * client; `emit` in a nested `onEvent` relays events to the page.
  */
 export { Island, islandComponent, lazyIsland } from './shell';
-export type {
-  IslandProps,
-  IslandShellProps,
-  IslandAppRef,
-  IslandFacadeProps,
-} from './shell';
+export type { IslandProps, IslandShellProps, IslandAppRef, IslandFacadeProps, } from './shell';
 export { connectIslandWorker, mountIsland, callbackProp } from '@preact-mvc/atoll/worker';
-export {
-  contractOf,
-  defineIslandContract,
-  definePolyWorker,
-  defineMonoWorker,
-  emit,
-  installDomShim,
-  isIslandContract,
-  runInInstance,
-  enterInstance,
-  exitInstance,
-  getActiveInstance,
-  getLastActiveInstance,
-  islandApp,
-  islandAppNameOf,
-  withContract,
-  ProxyElement,
-} from '@preact-mvc/atoll/worker';
-export type {
-  EventPayload,
-  ImperativeIslandApp,
-  IslandContract,
-  RenderedIslandApp,
-  RenderContext,
-  RenderedHandle,
-  IslandApp,
-  IslandWorkerDef,
-  ProxyDocument,
-} from '@preact-mvc/atoll/worker';
+export { contractOf, defineIslandContract, definePolyWorker, defineMonoWorker, emit, installDomShim, isIslandContract, runInInstance, enterInstance, exitInstance, getActiveInstance, getLastActiveInstance, islandApp, islandAppNameOf, withContract, ProxyElement, } from '@preact-mvc/atoll/worker';
+export type { EventPayload, ImperativeIslandApp, IslandContract, RenderedIslandApp, RenderContext, RenderedHandle, IslandApp, IslandWorkerDef, ProxyDocument, } from '@preact-mvc/atoll/worker';

package/dist/worker.js

@@ -0,0 +1,26 @@
+/**
+ * `@preact-mvc/atoll-island/worker` — the `*-island` package's worker
+ * renderer (docs/atoll/islands-frameworks.md): render View classes and
+ * function components into the instance's proxy document via Preact.
+ *
+ *   // render.worker.ts
+ *   export const worker = defineViewPolyWorker({
+ *     apps: { counter: CounterView, clock: ClockView },
+ *   });
+ *
+ * The framework-free worker API is re-exported from
+ * `@preact-mvc/atoll/worker` so a worker entry needs no direct atoll-core
+ * import (same convention as Atoll's `*-island` packages).
+ */
+export { viewIslandApp, viewIsland, defineViewPolyWorker, defineViewMonoWorker, } from './adapter';
+/**
+ * The mount components on the worker side — same surface as the shell
+ * entry (Atoll's `react-island/worker` convention): inside a worker-
+ * rendered tree the component's div is a ProxyElement, `mountIsland`
+ * takes the nested path, and the sub-island's ops tunnel up the parent
+ * instance's op stream. `connectIslandWorker` builds a shared sub-worker
+ * client; `emit` in a nested `onEvent` relays events to the page.
+ */
+export { Island, islandComponent, lazyIsland } from './shell';
+export { connectIslandWorker, mountIsland, callbackProp } from '@preact-mvc/atoll/worker';
+export { contractOf, defineIslandContract, definePolyWorker, defineMonoWorker, emit, installDomShim, isIslandContract, runInInstance, enterInstance, exitInstance, getActiveInstance, getLastActiveInstance, islandApp, islandAppNameOf, withContract, ProxyElement, } from '@preact-mvc/atoll/worker';

package/package.json

@@ -1,25 +1,31 @@
 {
   "name": "@preact-mvc/atoll-island",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "preact-mvc island adapter: <Island/> shell components + Preact renderer for @preact-mvc/atoll worker islands",
   "type": "module",
+  "sideEffects": false,
   "exports": {
-    ".": "./src/index.ts",
-    "./worker": "./src/worker.ts",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "default": "./dist/worker.js"
+    },
     "./package.json": "./package.json",
-    "./*": "./src/*"
+    "./*": "./dist/*"
   },
   "files": [
-    "src",
-    "!src/**/*.test.ts",
-    "!src/**/*.test.tsx"
+    "dist"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@preact-mvc/atoll": "0.1.0",
-    "@preact-mvc/core": "0.1.0",
+    "@preact-mvc/atoll": "0.1.2",
+    "@preact-mvc/core": "0.1.2",
     "preact": "^10.24.0"
   },
   "devDependencies": {
@@ -35,5 +41,6 @@
     "url": "https://github.com/jwhenry3/preact-mvc",
     "directory": "packages/atoll-island"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "types": "./dist/index.d.ts"
 }

package/src/adapter.tsx

@@ -1,258 +0,0 @@
-/**
- * The framework renderer adapter — our `*-island` package's renderer half
- * (docs/atoll/islands-frameworks.md). `viewIslandApp(Component)` wraps a
- * `View` class or function component as a `RenderedIslandApp`; each mount
- * renders into the instance's proxy document via Preact, so every DOM
- * mutation serializes to ops.
- *
- * `defineViewPolyWorker`/`defineViewMonoWorker` are the single-framework
- * convenience definers — they wrap plain components automatically:
- *
- *   // render.worker.ts
- *   export const worker = defineViewPolyWorker({
- *     apps: { counter: CounterView, clock: ClockView },
- *   });
- *
- * DI inside islands: the app gets a fresh root injector per instance —
- * worker-side injectables (stores, controllers) live in the worker, and
- * `@Component({ providers/imports/controllers })` metadata works unchanged
- * because the View host machinery runs in the worker too.
- */
-import { h, options, render } from 'preact';
-import type { ComponentType, VNode } from 'preact';
-import { Injector, InjectorContext, type Provider } from '@preact-mvc/core';
-import {
-  defineMonoWorker,
-  definePolyWorker,
-  islandApp,
-  islandAppNameOf,
-  enterInstance,
-  exitInstance,
-  getActiveInstance,
-  withContract,
-  ProxyElement,
-  type ImperativeIslandApp,
-  type IslandContract,
-  type IslandWorkerDef,
-  type RenderContext,
-  type RenderedHandle,
-  type RenderedIslandApp,
-} from '@preact-mvc/atoll/worker';
-
-type AnyComponent = ComponentType<Record<string, unknown>>;
-
-const ISLAND_KEY = '__islandInstance';
-const PREV_KEY = '__islandPrevScope';
-
-/**
- * Instance-scoped rendering for OUT-OF-TASK renders. Mount/updateProps run
- * inside `runInInstance`, but signal-driven re-renders are deferred by
- * Preact to a microtask with no active scope — ambient `document` would
- * resolve via the last-active heuristic and could create nodes on a SIBLING
- * island's document (in shared-client/in-process topologies).
- *
- * Fix: every root vnode is stamped `__islandInstance`; `options.__r` walks
- * the `__` parent chain before each component render and enters that
- * instance's scope; `options.diffed` restores. Deterministic, and strictly
- * better than the ambient heuristic.
- */
-let renderScopeInstalled = false;
-function installRenderScope(): void {
-  if (renderScopeInstalled) return;
-  renderScopeInstalled = true;
-  type IVNode = VNode & { [ISLAND_KEY]?: string; [PREV_KEY]?: string | null; __?: IVNode | null };
-  const opts = options as unknown as {
-    __r?: (v: VNode) => void;
-    diffed?: (v: VNode) => void;
-  };
-  const prevR = opts.__r;
-  const prevD = opts.diffed;
-  opts.__r = (vnode: VNode) => {
-    let v = vnode as IVNode | null;
-    let key: string | undefined;
-    while (v) {
-      if (v[ISLAND_KEY]) {
-        key = v[ISLAND_KEY];
-        break;
-      }
-      v = v.__ ?? null;
-    }
-    if (key && key !== getActiveInstance())
-      (vnode as IVNode)[PREV_KEY] = enterInstance(key);
-    prevR?.(vnode);
-  };
-  opts.diffed = (vnode: VNode) => {
-    prevD?.(vnode);
-    const v = vnode as IVNode;
-    if (PREV_KEY in v) {
-      exitInstance(v[PREV_KEY] ?? null);
-      delete v[PREV_KEY];
-    }
-  };
-}
-
-/**
- * Event-name bridge for the proxy DOM. Preact decides the DOM event name
- * via `'onclick' in el`: real elements report the lowercase handler props
- * as present, so `onClick` registers `addEventListener('click', …)` and
- * keys `dom._listeners['click']`. The proxy element has no `on*` props —
- * the probe fails and Preact uses the prop-sliced name 'Click' for BOTH.
- * The driver then listens for a type real DOM never dispatches (no events
- * arrive), and `eventProxy` looks its dict up under 'Click' anyway.
- *
- * The bridge normalizes at the proxy boundary: the `listen` op carries
- * the real DOM type ('click' — driver attaches a working listener) while
- * the wrapped handler re-tags the enriched payload with the prop-sliced
- * name ('Click') so Preact's `eventProxy` still finds its dict entry.
- * All-caps ('DOMContentLoaded') and lowercase types pass through. The
- * wrapped-handler map keeps removeEventListener able to detach the same
- * registration.
- */
-type EventFn = (this: unknown, e: unknown) => void;
-let eventBridgeInstalled = false;
-function installEventNameBridge(): void {
-  if (eventBridgeInstalled) return;
-  eventBridgeInstalled = true;
-  /** element → original fn → prop-sliced type → wrapped fn */
-  const bridged = new WeakMap<object, Map<EventFn, Map<string, EventFn>>>();
-
-  // Prop-sliced PascalCase → the real lowercase DOM type. Only the
-  // PascalCase shape is rewritten: 'MouseLeave' → 'mouseleave',
-  // 'DblClick' → 'dblclick'. All-caps ('DOMContentLoaded'), lowercase
-  // ('click'), and camelCase custom types pass through — lowercasing
-  // 'DOMContentLoaded' would break it the other way.
-  const decap = (type: string): string =>
-    type.length > 1 &&
-    type[0] === type[0]!.toUpperCase() &&
-    type[1] === type[1]!.toLowerCase()
-      ? type.toLowerCase()
-      : type;
-
-  type ListenerMethods = {
-    addEventListener: (this: object, type: string, fn: EventFn, opts?: unknown) => void;
-    removeEventListener: (this: object, type: string, fn: EventFn, opts?: unknown) => void;
-  };
-  const proto = ProxyElement.prototype as unknown as ListenerMethods;
-  const origAdd = proto.addEventListener;
-  const origRemove = proto.removeEventListener;
-
-  proto.addEventListener = function (
-    this: object,
-    type: string,
-    fn: EventFn,
-    opts?: unknown,
-  ): void {
-    const dom = decap(type);
-    let effective = fn;
-    if (dom !== type) {
-      effective = function (this: unknown, e: unknown): void {
-        fn.call(this, { ...(e as Record<string, unknown>), type });
-      };
-      let byFn = bridged.get(this);
-      if (byFn === undefined) bridged.set(this, (byFn = new Map()));
-      let byType = byFn.get(fn);
-      if (byType === undefined) byFn.set(fn, (byType = new Map()));
-      byType.set(type, effective);
-    }
-    origAdd.call(this, dom, effective, opts);
-  };
-
-  proto.removeEventListener = function (
-    this: object,
-    type: string,
-    fn: EventFn,
-    opts?: unknown,
-  ): void {
-    const effective = bridged.get(this)?.get(fn)?.get(type) ?? fn;
-    origRemove.call(this, decap(type), effective, opts);
-  };
-}
-
-export interface ViewIslandAppOptions {
-  /** Providers for the island's root injector — the island-side equivalent
-   *  of `bootstrap(AppModule, providers)`. */
-  providers?: Provider[];
-  /** Attach a `defineIslandContract` contract: mount/updateProps props are
-   *  validated against its schema, and declared `emit` payloads are
-   *  checked worker-side. */
-  contract?: IslandContract;
-}
-
-/** Wrap a View class or function component as a `RenderedIslandApp`. */
-export function viewIslandApp(App: AnyComponent, opts?: ViewIslandAppOptions): RenderedIslandApp {
-  installRenderScope();
-  installEventNameBridge();
-  const app: RenderedIslandApp = {
-    renderer: 'preact-mvc',
-    mount({ instance, doc, props }: RenderContext): RenderedHandle {
-      const inj = new Injector(undefined, `island ${instance}`);
-      for (const p of opts?.providers ?? []) inj.provide(p);
-      let current = props;
-      const renderRoot = (p: Record<string, unknown>): void => {
-        current = p;
-        const vnode = h(InjectorContext.Provider, { value: inj }, h(App, p));
-        (vnode as unknown as Record<string, unknown>)[ISLAND_KEY] = instance;
-        render(vnode, doc.body as never);
-      };
-      renderRoot(props);
-      return {
-        update: renderRoot,
-        // The dispatch task's sync lane: run the event handler, then
-        // re-render synchronously (Preact's render() IS the flush — signal
-        // writes would otherwise defer to a microtask and their ops would
-        // miss this task's batch, surfacing a poll later).
-        sync: (fn: () => void) => {
-          fn();
-          renderRoot(current);
-        },
-        dispose: () => {
-          try {
-            render(null, doc.body as never);
-          } finally {
-            inj.deactivate();
-          }
-        },
-      };
-    },
-  };
-  const stamp = islandAppNameOf(App);
-  if (stamp !== undefined) (app as { islandAppName?: string }).islandAppName = stamp;
-  return opts?.contract !== undefined ? withContract(opts.contract, app) : app;
-}
-
-/** Stamp + wrap in one step — `viewIsland('counter', CounterView)` yields
- *  both the registry value and the name the shell mounts by. */
-export const viewIsland = (
-  name: string,
-  App: AnyComponent,
-  opts?: ViewIslandAppOptions,
-): RenderedIslandApp & { readonly islandAppName: string } =>
-  islandApp(name, viewIslandApp(App, opts));
-
-export interface ViewPolyWorkerRegistry {
-  /** Name → component (or `{ imperative }` app / pre-wrapped app). Plain
-   *  components pass through `viewIslandApp`. */
-  apps: Record<string, AnyComponent | ImperativeIslandApp | RenderedIslandApp>;
-}
-
-/** `definePolyWorker` for framework views — maps each component in the
- *  registry through `viewIslandApp` and delegates. */
-export function defineViewPolyWorker(registry: ViewPolyWorkerRegistry): IslandWorkerDef {
-  installRenderScope();
-  const apps: Record<string, ImperativeIslandApp | RenderedIslandApp> = {};
-  for (const [key, app] of Object.entries(registry.apps)) {
-    apps[key] = typeof app === 'function' ? viewIslandApp(app) : app;
-  }
-  return definePolyWorker({ apps });
-}
-
-/** `defineMonoWorker` for a single framework view — the isolated-bundle
- *  host shape (own worker, own failure domain). */
-export function defineViewMonoWorker(
-  app: AnyComponent | ImperativeIslandApp | RenderedIslandApp,
-  opts?: ViewIslandAppOptions,
-): IslandWorkerDef {
-  installRenderScope();
-  const resolved = typeof app === 'function' ? viewIslandApp(app, opts) : app;
-  return defineMonoWorker(resolved);
-}

package/src/shell.tsx

@@ -1,280 +0,0 @@
-/**
- * The shell surface — our `*-island` package's main-thread half
- * (docs/atoll/islands-frameworks.md): mount a worker-hosted tree as an
- * ordinary element in a framework app.
- *
- *   <Island worker={entry} app="counter" props={{ start: 5 }}
- *           onEvent={(name, p) => ...} />
- *
- *   const Counter = islandComponent(counterContract);   // the facade:
- *   <Counter start={5} onEvent={...} />                 // no worker prop —
- *                                                        the contract carries it
- *
- *   const Lazy = lazyIsland(() => import('./counter.contract'));
- *
- * These are plain function components — hooks are legal here (only `View`
- * classes forbid them). `worker`/`client`/`app` are mount identity: change
- * them with a `key`.
- */
-import { h } from 'preact';
-import { useEffect, useRef, useState } from 'preact/hooks';
-import type { ComponentChildren, FunctionComponent } from 'preact';
-import {
-  connectIslandWorker,
-  contractWorkerOf,
-  islandAppNameOf,
-  isIslandContract,
-  mountIsland,
-} from '@preact-mvc/atoll';
-import type {
-  IslandAppProps,
-  IslandClient,
-  IslandContract,
-  IslandContractEventHandler,
-  IslandContractProps,
-  IslandHandle,
-  IslandWorkerOptions,
-  Mode,
-  WorkerLike,
-} from '@preact-mvc/atoll';
-
-/** Props consumed by a proxy component itself — everything else forwards to
- *  the island as its props. */
-export interface IslandShellProps {
-  /** Bundler-detectable factory `() => new Worker(new URL(...))` (or a URL
-   *  / spawned worker). Optional when `app` is a contract carrying its own
-   *  worker — the contract module is then the whole connection. */
-  worker?: WorkerLike | (() => WorkerLike) | URL;
-  /** A shared `connectIslandWorker` client — this mount adds an instance. */
-  client?: IslandClient;
-  /** Client options for `worker`-shorthand mounts (taskTimeout, respawn,
-   *  lazy, doorbell). `doorbell: true` needs cross-origin isolation. */
-  workerOptions?: IslandWorkerOptions & { doorbell?: boolean };
-  /** 'push' rides the doorbell SAB (COOP/COEP); 'poll' (default) is
-   *  message-only — no headers needed. */
-  mode?: Mode;
-  /** Devtools renderer tag. */
-  framework?: string;
-  /** Receives every worker-side `emit(name, payload)`. */
-  onEvent?: (name: string, payload: unknown) => void;
-  /** Fired after each applied op batch. */
-  onActivity?: () => void;
-  /** The mounted handle (pid, updateProps, flush, setMode…) once ready. */
-  onReady?: (island: IslandHandle) => void;
-  /** Mount/update errors surface here instead of an unhandled rejection. */
-  onError?: (err: unknown) => void;
-  /** `data-atoll-slot` transclusion holes: worker owns the box, shell owns
-   *  the contents. */
-  slots?: Record<string, (el: HTMLElement | null) => void>;
-  /** Rendered while the worker mounts (lazy facades). */
-  fallback?: ComponentChildren;
-  className?: string;
-  style?: string | Record<string, string | number>;
-  mountTimeout?: number;
-  children?: ComponentChildren; // reserved for future slot sugar
-}
-
-export interface IslandProps extends IslandShellProps {
-  /** Registry key, stamped app (`islandApp`/`viewIsland`), or contract —
-   *  resolved through `islandAppNameOf`. */
-  app?: unknown;
-  /** Structured-cloneable props (functions via `callbackProp`). */
-  props?: Record<string, unknown>;
-}
-
-export const Island: FunctionComponent<IslandProps> = (p) => {
-  const ref = useRef<HTMLDivElement>(null);
-  const handle = useRef<IslandHandle | null>(null);
-  const [failed, setFailed] = useState<Error | null>(null);
-
-  // 'main' mounts a mono worker's sole app namelessly; registries error
-  // with the key list if 'main' isn't a real key.
-  const appName = p.app === undefined ? 'main' : islandAppNameOf(p.app);
-
-  // Mount once per app — worker/client/app are identity; change via `key`.
-  useEffect(() => {
-    if (appName === undefined) {
-      setFailed(
-        new Error(
-          '<Island> could not resolve an app name — pass the registry key ' +
-            'or stamp the app with islandApp(name, app)',
-        ),
-      );
-      return;
-    }
-    const mode = p.mode ?? 'poll';
-    // A contract `app` can carry its own worker factory — the contract
-    // module is then the whole connection, call sites pass no worker.
-    const resolvedWorker = p.worker ?? contractWorkerOf(p.app);
-    const client =
-      p.client ??
-      (resolvedWorker !== undefined
-        ? connectIslandWorker({
-            name: appName,
-            worker: resolvedWorker,
-            doorbell: mode !== 'poll',
-            ...p.workerOptions,
-          })
-        : undefined);
-    if (client === undefined) {
-      setFailed(new Error('<Island> requires either `worker`, `client`, or a contract carrying `worker`'));
-      return;
-    }
-    let cancelled = false;
-    mountIsland({
-      el: ref.current!,
-      client,
-      app: appName,
-      props: p.props,
-      onEvent: p.onEvent,
-      onActivity: p.onActivity,
-      slots: p.slots,
-      mode,
-      framework: p.framework,
-      mountTimeout: p.mountTimeout,
-    })
-      .then((h) => {
-        if (cancelled) h.destroy();
-        else {
-          handle.current = h;
-          p.onReady?.(h);
-        }
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        if (p.onError) p.onError(err);
-        else setFailed(err instanceof Error ? err : new Error(String(err)));
-      });
-    return () => {
-      cancelled = true;
-      handle.current?.destroy();
-      handle.current = null;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [appName, p.client]);
-
-  // Prop updates flow through the handle — deduped by wire-serialized
-  // identity; a repeat send would be a wasted round-trip.
-  const propsJson = JSON.stringify(p.props ?? {});
-  useEffect(() => {
-    handle.current?.updateProps(p.props ?? {});
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [propsJson]);
-
-  if (failed) {
-    return (
-      <div class="island-error" style={{ border: '1px solid #c00', padding: '0.5em' }}>
-        Island mount failed: {failed.message}
-      </div>
-    );
-  }
-  return <div ref={ref} class={p.className} style={p.style as string} />;
-};
-
-/** What `app` accepts on a facade: the registry name, or a reference to
- *  resolve (component, stamped app, contract). */
-export type IslandAppRef<A> = A | string;
-
-export type IslandFacadeProps<A> = Omit<IslandShellProps, 'onEvent'> &
-  IslandAppProps<A> & {
-    props?: Record<string, unknown>;
-    onEvent?: (name: string, payload: unknown) => void;
-  };
-
-/** Props consumed by a facade component itself — everything else forwards
- *  to the island as its props. */
-const SHELL_PROP_KEYS: ReadonlySet<string> = new Set([
-  'worker',
-  'client',
-  'workerOptions',
-  'mode',
-  'framework',
-  'onEvent',
-  'onActivity',
-  'onReady',
-  'onError',
-  'slots',
-  'fallback',
-  'className',
-  'style',
-  'mountTimeout',
-  'children',
-]);
-
-const splitProxyProps = (
-  raw: Record<string, unknown>,
-): { shell: IslandShellProps; islandProps: Record<string, unknown> } => {
-  const shell: Record<string, unknown> = {};
-  const islandProps: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(raw)) {
-    if (SHELL_PROP_KEYS.has(key)) shell[key] = value;
-    else islandProps[key] = value;
-  }
-  return { shell: shell as IslandShellProps, islandProps };
-};
-
-/**
- * `islandComponent(contract)` — the cross-framework facade: the component's
- * props are the island's props (from the contract's schema), `onEvent`
- * narrows to the declared event vocabulary, and the contract's own worker
- * factory means call sites pass NO worker/client at all. The shell imports
- * the contract module only — never the worker entry or the island's code.
- *
- * `islandComponent<P>('charts')` — the string-keyed form for registries
- * whose workers the shell already knows.
- */
-export function islandComponent<C extends IslandContract>(
-  app: C,
-): FunctionComponent<
-  IslandContractProps<C> &
-    Omit<IslandShellProps, 'onEvent'> & {
-      props?: Record<string, unknown>;
-      onEvent?: IslandContractEventHandler<C>;
-    }
->;
-export function islandComponent<A>(app: A | string): FunctionComponent<IslandFacadeProps<A>>;
-export function islandComponent(app: unknown): FunctionComponent<Record<string, unknown>> {
-  const Facade: FunctionComponent<Record<string, unknown>> = ({ props, ...raw }) => {
-    const { shell, islandProps } = splitProxyProps(raw as Record<string, unknown>);
-    return <Island app={app} props={{ ...islandProps, ...(props ?? {}) }} {...shell} />;
-  };
-  Facade.displayName = `Island(${islandAppNameOf(app) ?? 'main'})`;
-  return Facade as FunctionComponent<Record<string, unknown>>;
-}
-
-/**
- * `lazyIsland(() => import('./counter.contract'))` — the module must export
- * a contract (`defineIslandContract` — app + worker factory in one object),
- * a stamped app (`viewIsland('counter', CounterView)`), or a default export
- * resolvable by `islandAppNameOf`. A contract's own worker factory is used
- * when no `worker` prop is passed.
- */
-export function lazyIsland<A>(
-  load: () => Promise<Record<string, unknown>>,
-): FunctionComponent<IslandFacadeProps<A>> {
-  const Lazy: FunctionComponent<IslandFacadeProps<A>> = (p) => {
-    const [app, setApp] = useState<unknown>(null);
-    useEffect(() => {
-      let live = true;
-      void load().then((mod) => {
-        if (!live) return;
-        const unwrapped = 'default' in mod ? mod.default : mod;
-        const resolved =
-          isIslandContract(unwrapped) ? unwrapped
-          : Object.values(mod).find((v) => isIslandContract(v)) ??
-            Object.values(mod).find(
-              (v) => v && typeof v === 'object' && 'islandAppName' in v,
-            ) ??
-            unwrapped;
-        setApp(() => resolved);
-      });
-      return () => {
-        live = false;
-      };
-    }, []);
-    if (!app)
-      return <div class={p.className} style={p.style as string}>{p.fallback}</div>;
-    return <Island {...(p as IslandProps)} app={app} />;
-  };
-  return Lazy;
-}