@atolljs/islands 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/islands",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",
@@ -19,7 +19,7 @@
     "htmlparser2": "^12.0.0"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.5"
+    "@atolljs/core": "0.1.7"
   },
   "repository": {
     "type": "git",

package/src/app.ts

@@ -10,6 +10,9 @@
  * The stamp is a plain data property — stable through minification.
  */
 
+import { isIslandContract } from './contract';
+import type { IslandContract } from './contract';
+
 /** The data property `islandApp` stamps — read by islandAppNameOf. */
 const ISLAND_APP_NAME = 'islandAppName';
 
@@ -41,6 +44,9 @@ export const islandApp = <A>(name: string, app: A): A & { readonly islandAppName
 export const islandAppNameOf = (app: unknown): string | undefined => {
   if (typeof app === 'string') return app === '' ? undefined : app;
   if (app === null || (typeof app !== 'function' && typeof app !== 'object')) return undefined;
+  // A contract's registry key IS its `app` field — checked before the
+  // function/imperative fallbacks so `app={checkoutContract}` resolves.
+  if (isIslandContract(app)) return app.app === '' ? undefined : app.app;
   const stamped = (app as unknown as Record<string, unknown>)[ISLAND_APP_NAME];
   if (typeof stamped === 'string' && stamped !== '') return stamped;
   if (typeof app === 'function') {
@@ -62,13 +68,15 @@ export const islandAppNameOf = (app: unknown): string | undefined => {
  * string names (the un-typed mount path). Interfaces without index
  * signatures still infer here — serialization happens at mount.
  */
-export type IslandAppProps<A> = A extends {
-  imperative: (doc: never, props: infer P) => void;
-}
+export type IslandAppProps<A> = A extends IslandContract<infer P, infer _E>
   ? P
-  : A extends (props: infer P) => unknown
+  : A extends {
+        imperative: (doc: never, props: infer P) => void;
+      }
     ? P
-    : Record<string, unknown>;
+    : A extends (props: infer P) => unknown
+      ? P
+      : Record<string, unknown>;
 
 /**
  * The structural shape of a mountable app — `never` params so ANY component,
@@ -80,4 +88,5 @@ export type IslandAppProps<A> = A extends {
 export type IslandAppLike =
   | ((props: never) => unknown)
   | { imperative: (doc: never, props: never) => void }
-  | { mount: (ctx: never) => unknown };
+  | { mount: (ctx: never) => unknown }
+  | IslandContract;

package/src/contract.ts

@@ -0,0 +1,136 @@
+/**
+ * Island contracts — the framework-free seam between a micro-frontend's
+ * worker and any shell.
+ *
+ * The contract module is the one file BOTH sides import: it names the
+ * registry app, declares the props/events wire shape as `Schema`s (the
+ * vendored `z` from `@atolljs/core`, consumer-supplied zod, or any
+ * `{ parse }` validator), and can carry the worker factory so
+ * `lazyIsland(() => import('./x.contract'))` is a self-contained split
+ * point. No framework types cross it — a React shell mounting an Angular
+ * app needs only this file.
+ *
+ * ```ts
+ * // checkout.contract.ts — published by the MFE, imported by both threads
+ * import { z } from '@atolljs/core';
+ * import { defineIslandContract } from '@atolljs/islands';
+ *
+ * export const checkout = defineIslandContract({
+ *   app: 'checkout',
+ *   props: z.object({ label: z.string().optional() }),
+ *   events: { paid: z.object({ total: z.number() }) },
+ *   worker: () => new Worker(new URL('./checkout.worker.ts', import.meta.url), { type: 'module' }),
+ * });
+ * ```
+ *
+ * Enforcement is worker-side: mount/updateProps parse props AFTER
+ * `unmarshalCallbackProps` restores `callbackProp` callables (declare those
+ * members `z.callback<Fn>()`), and `emit` parses payloads for declared
+ * event names. Undeclared event names pass through — a contract describes
+ * the wire, it doesn't fence it (a newer worker emitting an event an older
+ * shell doesn't know is normal evolution; a mismatched payload on a KNOWN
+ * event is the violation).
+ */
+import type { Schema } from '@atolljs/core';
+
+/** The brand property `defineIslandContract` stamps — a data property,
+ *  like `islandAppName`, so it survives minification and `{...spread}`. */
+const CONTRACT_MARK = 'islandContract';
+/** The property `withContract` stamps on an app def — read at mount. */
+const APP_CONTRACT = 'appContract';
+
+/**
+ * A mountable app contract: the registry key, the prop/event wire schemas,
+ * and optionally the worker factory. `P`/`E` are the shell-facing types —
+ * they ride the contract as pure type information, so consumers of a
+ * framework-rendered island (an Angular component, a Vue SFC) get typed
+ * props and narrowed `onEvent` without ever importing that framework.
+ */
+export interface IslandContract<
+  P = Record<string, unknown>,
+  E extends Record<string, unknown> = Record<string, unknown>,
+> {
+  readonly islandContract: true;
+  /** Registry key — the name `mountIsland({ app })` resolves to. */
+  readonly app: string;
+  /** Prop wire schema — enforced worker-side at mount and updateProps. */
+  readonly props?: Schema<P>;
+  /** Declared emit vocabulary — declared names' payloads parse at emit(). */
+  readonly events?: { readonly [K in keyof E & string]: Schema<E[K]> };
+  /** The worker factory — optional; when present the contract object itself
+   *  is a lazy contract module (`{ app, worker }`). */
+  readonly worker?: (() => Worker) | URL;
+}
+
+export function defineIslandContract<
+  P = Record<string, unknown>,
+  E extends Record<string, unknown> = Record<string, unknown>,
+>(contract: {
+  app: string;
+  props?: Schema<P>;
+  events?: { [K in keyof E & string]: Schema<E[K]> };
+  worker?: (() => Worker) | URL;
+}): IslandContract<P, E> {
+  return { ...contract, [CONTRACT_MARK]: true as const };
+}
+
+/** Structural contract check — the brand, not the shape, so a hand-rolled
+ *  `{ app, props }` without `defineIslandContract` stays an app reference. */
+export const isIslandContract = (value: unknown): value is IslandContract =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as Record<string, unknown>)[CONTRACT_MARK] === true;
+
+/** The props a contract admits — `IslandContract<P>` → `P`. */
+export type IslandContractProps<C> = C extends IslandContract<infer P, infer _E>
+  ? P
+  : Record<string, unknown>;
+
+/** The event vocabulary a contract declares — name → payload map. */
+export type IslandContractEvents<C> = C extends IslandContract<infer _P, infer E>
+  ? E
+  : Record<string, unknown>;
+
+/**
+ * The `onEvent` signature a contract implies — `(name, payload)` with the
+ * payload narrowed per event name. Framework-free sibling of
+ * `@atolljs/angular-island`'s `IslandEventHandler<C>`.
+ */
+export type IslandContractEventHandler<C> = <
+  K extends keyof IslandContractEvents<C> & string,
+>(
+  name: K,
+  payload: IslandContractEvents<C>[K],
+) => void;
+
+/**
+ * `withContract(contract, app)` — attach a contract to a registry app
+ * (imperative def or any framework adapter's `RenderedIslandApp`). The
+ * stamp rides the app object like `islandAppName`; the worker reads it at
+ * mount/updateProps for prop validation and hands it to `emit` for
+ * declared-payload checks.
+ *
+ *   apps: {
+ *     checkout: withContract(checkout, angularIslandApp(CheckoutComponent)),
+ *   }
+ */
+export function withContract<C extends IslandContract, A>(contract: C, app: A): A {
+  (app as Record<string, unknown>)[APP_CONTRACT] = contract;
+  return app;
+}
+
+/** Read the contract a `withContract`-stamped app carries (undefined when
+ *  unstamped — most registry entries). */
+export const contractOf = (app: unknown): IslandContract | undefined => {
+  if (typeof app !== 'object' && typeof app !== 'function') return undefined;
+  if (app === null) return undefined;
+  const c = (app as Record<string, unknown>)[APP_CONTRACT];
+  return isIslandContract(c) ? c : undefined;
+};
+
+/** The worker factory a contract-carrying `app` reference supplies —
+ *  mount seams fall back to it when no `worker`/`client` was passed, so
+ *  `<Island app={contract}/>` and `islandComponent(contract)` are fully
+ *  self-contained. */
+export const contractWorkerOf = (app: unknown): (() => Worker) | URL | undefined =>
+  isIslandContract(app) ? app.worker : undefined;

package/src/index.ts

@@ -28,6 +28,20 @@ export type { DoorbellSpec } from './memory';
 export { islandApp, islandAppNameOf } from './app';
 export type { IslandAppLike, IslandAppProps } from './app';
 
+export {
+  defineIslandContract,
+  isIslandContract,
+  withContract,
+  contractOf,
+  contractWorkerOf,
+} from './contract';
+export type {
+  IslandContract,
+  IslandContractEventHandler,
+  IslandContractEvents,
+  IslandContractProps,
+} from './contract';
+
 export { callbackProp } from './callbackProps';
 
 export { isEventRef } from './ops';

package/src/island.ts

@@ -14,7 +14,7 @@
  * is least-busy round-robin, so a second worker would receive dispatches for
  * a tree it doesn't hold (sticky routing is future work).
  */
-import { connectWorker, observe } from '@atolljs/core';
+import { connectWorker, emitDevtools, observe } from '@atolljs/core';
 import type {
   ConnectWorkerConfig,
   SharedSpec,
@@ -121,6 +121,13 @@ interface MountIslandBaseOptions {
    * cross-origin isolation requirement. Switch later with `handle.setMode`.
    */
   mode?: Mode;
+  /**
+   * Optional renderer/framework tag — pure observability metadata forwarded
+   * to devtools on `island:mount` ('react', 'vue', 'svelte', …). Framework
+   * shell bindings can set it automatically; direct mountIsland callers
+   * declare it themselves.
+   */
+  framework?: string;
   /**
    * Milliseconds the mount handshake (mount + whoami) may take before the
    * returned promise rejects — default 15_000, `0` disables. A worker entry
@@ -336,7 +343,7 @@ const cssStyleValue = (key: string, value: unknown): string => {
 export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandle> {
   const {
     el, onEvent, onActivity, onOps, slots, mode: initialMode, mountTimeout,
-    client: givenClient, worker, app: givenApp, props: givenProps,
+    client: givenClient, worker, app: givenApp, props: givenProps, framework,
     ...workerConfig
   } = opts;
   // Shell→worker callables: callbackProp() markers marshal to {__cb:id}
@@ -442,9 +449,8 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
       );
       // The whole point: an event = one postMessage round-trip. The worker
       // re-renders, we apply whatever ops come back.
-      void client
-        .dispatch(handlerId, payload)
-        .then(applyOps)
+      void islandCall('dispatch', client.dispatch(handlerId, payload))
+        .then((ops) => applyOps(ops, 'dispatch'))
         .catch((err) => console.error(`[island ${instance}] dispatch failed`, err));
     };
   }
@@ -771,24 +777,53 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
           break;
         }
         // Not a DOM mutation — the island→shell channel.
+        emitDevtools({ type: 'island:event', instance, name: op.name });
         onEvent?.(op.name, op.payload);
         break;
       }
     }
   }
 
-  function applyOps(ops: Op[]): void {
+  function applyOps(ops: Op[], via: 'mount' | 'updateProps' | 'dispatch' | 'setSize' | 'flush'): void {
     opsApplied += ops.length;
     onActivity?.();
-    const t0 = onOps !== undefined ? performance.now() : 0;
+    const t0 = performance.now();
     for (const op of ops) applyOp(op);
-    onOps?.(ops, performance.now() - t0);
+    const replayMs = performance.now() - t0;
+    emitDevtools({ type: 'island:ops', instance, via, count: ops.length, replayMs });
+    onOps?.(ops, replayMs);
   }
 
+  /** Times a main→worker round-trip for the devtools inspector. */
+  const islandCall = <T>(
+    method: 'mount' | 'whoami' | 'dispatch' | 'setSize' | 'updateProps' | 'flush' | 'unmount',
+    p: Promise<T>,
+  ): Promise<T> => {
+    const t0 = performance.now();
+    return p.then(
+      (r) => {
+        emitDevtools({
+          type: 'island:task', instance, method,
+          ms: performance.now() - t0,
+          ops: Array.isArray(r) ? r.length : undefined,
+        });
+        return r;
+      },
+      (err) => {
+        emitDevtools({
+          type: 'island:task', instance, method,
+          ms: performance.now() - t0,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+      },
+    );
+  };
+
   const doFlush = (): void => {
     if (destroyed) return;
     flushCalls++;
-    void client.flush(instance).then(applyOps);
+    void islandCall('flush', client.flush(instance)).then((ops) => applyOps(ops, 'flush'));
   };
 
   /* ── Transport: push (shared-memory doorbell) vs poll ─────────────────── */
@@ -842,15 +877,16 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
 
   let pid: string;
   try {
-    applyOps(await raced(client.mount(instance, props)));
-    pid = await raced(client.whoami(instance));
+    applyOps(await raced(islandCall('mount', client.mount(instance, props))), 'mount');
+    pid = await raced(islandCall('whoami', client.whoami(instance)));
+    emitDevtools({ type: 'island:mount', instance, app, pid, poolId: client.pool?.poolId, framework });
   } catch (err) {
     // The instance may exist worker-side with ops we never applied — release it.
     // An island-owned client also terminates (stops a crash→respawn loop on
     // a permanently-broken entry); a shared client just drops the instance.
     clientMounts.set(client, (clientMounts.get(client) ?? 1) - 1);
     if (givenClient === undefined) client.terminate();
-    else void client.unmount(instance).catch(() => {});
+    else void islandCall('unmount', client.unmount(instance)).catch(() => {});
     throw err;
   }
 
@@ -879,7 +915,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
     if (w === lastW && h === lastH) return;
     lastW = w;
     lastH = h;
-    void client.setSize(instance, w, h).then(applyOps);
+    void islandCall('setSize', client.setSize(instance, w, h)).then((ops) => applyOps(ops, 'setSize'));
   };
   const resizeObserver =
     typeof ResizeObserver === 'function'
@@ -918,13 +954,14 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
     updateProps: async (next: Record<string, unknown>) => {
       const marshalled = marshalCallbackProps(next, registerCb) as Record<string, unknown>;
       assertCloneableProps(marshalled, `updateProps(${app})`);
-      applyOps(await client.updateProps(instance, marshalled));
+      applyOps(await islandCall('updateProps', client.updateProps(instance, marshalled)), 'updateProps');
     },
     flush: async () => {
-      applyOps(await client.flush(instance));
+      applyOps(await islandCall('flush', client.flush(instance)), 'flush');
     },
     destroy: () => {
       destroyed = true;
+      emitDevtools({ type: 'island:unmount', instance });
       unsubscribe?.();
       resizeObserver?.disconnect();
       if (pollTimer !== null) clearInterval(pollTimer);
@@ -936,7 +973,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         // detach ops are irrelevant if our element is already gone, so the
         // return batch is dropped. Best-effort: the instance map and its
         // handlers release regardless.
-        void client.unmount(instance).catch(() => {});
+        void islandCall('unmount', client.unmount(instance)).catch(() => {});
       } else {
         // Last island — still run the instance's teardown first so the app's
         // dispose hook cancels deferred work (library timers, animation
@@ -944,8 +981,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         // kill the thread before unmount lands — equally fine, process
         // death is teardown — but in-process workers need this or the
         // instance zombies on and its pending callbacks mutate foreign docs.
-        void client
-          .unmount(instance)
+        void islandCall('unmount', client.unmount(instance))
           .catch(() => {})
           .finally(() => {
             // A remount may have registered while teardown was in flight

package/src/worker/defineWorkers.ts

@@ -58,6 +58,7 @@
 import { defineWorker } from '@atolljs/core';
 import type { SharedMemory, WorkerDefinition } from '@atolljs/core';
 import { islandAppNameOf } from '../app';
+import { contractOf, type IslandContract } from '../contract';
 import { renderMemory, type DoorbellSpec } from '../memory';
 import { CALLBACK_EVENT, unmarshalCallbackProps } from '../callbackProps';
 import {
@@ -76,6 +77,7 @@ import {
   pushOp,
   runInInstance,
   setDoorbellContract,
+  setInstanceContract,
   setInstanceSize,
   takeOps,
 } from './instance';
@@ -198,6 +200,9 @@ interface InstanceBase {
    *  distinct render instance (in production: a distinct worker). Stable across
    *  remounts of the same instance key. */
   pid: string;
+  /** The `withContract`-stamped contract — drives props validation at
+   *  mount/updateProps; mirrored into instanceContracts for `emit`. */
+  contract?: IslandContract;
 }
 
 interface ImperativeInstance extends InstanceBase {
@@ -286,17 +291,43 @@ function createIslandRuntime(
   // installDomShim, which builds on this.
   installInstanceDispatcher();
 
+  /**
+   * Contract enforcement — a `withContract`-stamped app's prop schema parses
+   * the unmarshalled props (callbackProp callables already restored, so
+   * `z.callback()` members see functions). parse() also strips undeclared
+   * keys, making the contract the authoritative wire shape. Throws —
+   * mount/updateProps reject, which mountIsland surfaces as a named error.
+   */
+  const parseContractProps = (
+    contract: IslandContract | undefined,
+    key: string,
+    props: Record<string, unknown>,
+  ): Record<string, unknown> => {
+    if (contract?.props === undefined) return props;
+    try {
+      return contract.props.parse(props) as Record<string, unknown>;
+    } catch (err) {
+      throw new Error(
+        `[island "${contract.app}"] props for "${key}" rejected by contract: ` +
+          (err instanceof Error ? err.message : String(err)),
+      );
+    }
+  };
+
   // Container creation is per-instance, not module-level, so a second mount()
   // can't collide with the first instance's tree. Imperative mounts skip the
   // renderer entirely — their "host environment" is the proxy DOM, and
   // build() emits ops itself.
   function createInstance(key: string, pid: string): Instance {
     const app = resolveApp(appNameOf(key));
+    const contract = contractOf(app);
+    setInstanceContract(key, contract);
     if (isRendered(app)) {
       return {
         key,
         app: appNameOf(key),
         pid,
+        contract,
         rendered: { app, handle: undefined, props: {} },
       };
     }
@@ -305,6 +336,7 @@ function createIslandRuntime(
         key,
         app: appNameOf(key),
         pid,
+        contract,
         imperative: {
           build: app.imperative,
           dispose: app.dispose,
@@ -397,6 +429,7 @@ function createIslandRuntime(
             `mount: unknown app "${instance}" — registry has: ${[...APP_REGISTRY.keys()].join(', ')}`,
           );
         }
+        props = parseContractProps(contractOf(App), instance, props);
 
         const mounted = mounts.get(instance);
         // Remount — same clear+rebuild semantics as updateProps; the instance
@@ -445,6 +478,7 @@ function createIslandRuntime(
         if (mounted === undefined) {
           throw new Error(`updateProps: "${instance}" is not mounted in this worker — mount() first`);
         }
+        props = parseContractProps(mounted.contract, instance, props);
         // Imperative mounts have no diffing — updateProps REBUILDS: clear the
         // root and re-run build(props) on a fresh proxy document. Documented
         // as the honest semantics; fine for widgets, not for huge trees.
@@ -540,6 +574,7 @@ function createIslandRuntime(
         const mounted = mounts.get(instance);
         if (mounted === undefined) return [];
         mounts.delete(instance);
+        setInstanceContract(instance, undefined);
         return runInInstance(instance, () => {
           if (isImperativeInstance(mounted)) {
             // The app's dispose hook cancels deferred work (library timers,

package/src/worker/index.ts

@@ -27,6 +27,14 @@ export type {
 
 export { islandApp, islandAppNameOf } from '../app';
 
+export { defineIslandContract, isIslandContract, withContract, contractOf } from '../contract';
+export type {
+  IslandContract,
+  IslandContractEventHandler,
+  IslandContractEvents,
+  IslandContractProps,
+} from '../contract';
+
 export {
   allocId,
   bumpOpsVersion,

package/src/worker/instance.ts

@@ -15,6 +15,7 @@
 
 import { renderMemory } from '../memory';
 import { enterProxyFrame, exitProxyFrame, proxyMetrics } from '../metrics';
+import type { IslandContract } from '../contract';
 import type { Op, WireProps } from '../ops';
 
 /**
@@ -95,6 +96,21 @@ const handlers = new Map<number, HandlerEntry>();
 let nextId = 1;
 let nextHandlerId = 1;
 
+/**
+ * instance key → the `withContract`-attached contract (undefined for
+ * unstamped apps — most mounts). `emit` validates declared event payloads
+ * against it; defineWorkers registers it at instance create and clears it
+ * at unmount.
+ */
+const instanceContracts = new Map<string, IslandContract>();
+export const setInstanceContract = (
+  instance: string,
+  contract: IslandContract | undefined,
+): void => {
+  if (contract === undefined) instanceContracts.delete(instance);
+  else instanceContracts.set(instance, contract);
+};
+
 /** Allocate an instance id — the shared counter React and the proxy DOM both draw from. */
 export const allocId = (): number => nextId++;
 
@@ -285,6 +301,20 @@ export const unregisterHandler = (id: number): void => {
  */
 export const emit = (name: string, payload?: unknown): void => {
   timed(() => {
+    // Contract enforcement: a declared event's payload parses before it
+    // crosses — undeclared names pass through (the contract describes the
+    // wire; it doesn't fence forward-compatible additions).
+    const schema = instanceContracts.get(activeInstance)?.events?.[name];
+    if (schema !== undefined) {
+      try {
+        payload = schema.parse(payload);
+      } catch (err) {
+        throw new Error(
+          `emit("${name}") rejected by the island contract for "${activeInstance}": ` +
+            (err instanceof Error ? err.message : String(err)),
+        );
+      }
+    }
     pushOp(activeInstance, { t: 'emit', name, payload });
   });
 };