@atolljs/islands 0.1.6 → 0.1.8

package/src/island.ts

@@ -1,20 +1,30 @@
 /**
  * Per-island mounter — the main-thread half of one React tree in one worker.
  *
- * `mountIsland` mounts one island scoped so several can coexist on one page:
- * each island gets its own `connectWorker` client (own pool of ONE worker,
- * own doorbell buffer via `makeDoorbell()`), its own nodes/props/listeners
- * maps (op ids are only unique within a worker — sharing maps between
- * islands would corrupt them), and its own `onEvent` sink for `emit` ops.
+ * `mountIsland` mounts one island scoped so several can coexist on one page.
+ * A `worker:` mount builds its own client (one dedicated worker, own
+ * doorbell buffer via `makeDoorbell()`), i.e. spawns a worker; a `client:`
+ * mount adds an instance to that client's existing worker instead. Either
+ * way each island gets its own nodes/props/listeners maps (op ids are only
+ * unique within a worker — sharing maps between islands would corrupt them),
+ * and its own `onEvent` sink for `emit` ops.
  *
  * There is no React on this thread — the driver below just replays ops.
  *
- * poolSize: 1 is REQUIRED per island — the reconciled tree lives in one
- * worker's memory. A real pool can't serve islands today anyway: task routing
- * is least-busy round-robin, so a second worker would receive dispatches for
- * a tree it doesn't hold (sticky routing is future work).
+ * One worker per island client is REQUIRED — the reconciled tree lives in
+ * one worker's memory. A pool can't serve islands: task routing is
+ * least-busy, so a second worker would receive dispatches for a tree it
+ * doesn't hold. Island clients therefore run on `workers: 1`, a dedicated
+ * worker with no pool.
  */
-import { connectWorker, observe } from '@atolljs/core';
+import {
+  connectWorker,
+  devtoolsEnabled,
+  emitDevtools,
+  estimateCloneBytes,
+  observe,
+  previewValue,
+} from '@atolljs/core';
 import type {
   ConnectWorkerConfig,
   SharedSpec,
@@ -31,27 +41,31 @@ import {
 } from './ops';
 
 import { marshalCallbackProps, CALLBACK_EVENT } from './callbackProps';
+import { trackIslandForDevtools } from './devtoolsCommands';
+import { propsPreview } from './devtoolsPreview';
+import type { ProxyElement } from './worker/dom/element';
 
 export type Mode = 'push' | 'poll';
 
 /** The worker definition every `definePolyWorker` call produces. */
 export type IslandWorkerDefinition = WorkerDefinition<DoorbellSpec, IslandWorkerMethods>;
 
-/** One island client: one pool, one worker, one doorbell buffer. */
+/** One island client: one dedicated worker, one doorbell buffer. */
 export type IslandClient = WorkerClient<IslandWorkerDefinition, DoorbellSpec>;
 
 /**
- * Islands are microfrontend containers: each owns ONE worker holding ONE
- * reconciled tree, so pooling is disabled by construction — the type omits
- * `poolSize`/`worker`/`sharedMemory` (all island-internal) and the literal
- * below pins `poolSize: 1` after the spread, so a wider pool can't sneak
+ * An island client is ONE worker holding its islands' trees (one per mount
+ * on it), so pooling is disabled by construction — the type omits
+ * `workers`/`poolSize`/`worker`/`sharedMemory` (all island-internal) and the
+ * literal below pins `workers: 1` after the spread, so a pool can't sneak
  * through a cast either. `worker` is supplied per call — the package can't
  * know where the consumer's worker entry lives — everything else
- * (concurrency, taskTimeout, respawn, lazy…) still passes through.
+ * (taskTimeout, respawn, lazy…) still passes through. The pool-only
+ * `concurrency`/`maxQueue` are accepted but have no effect.
  */
 export type IslandWorkerOptions = Omit<
   ConnectWorkerConfig<SharedSpec>,
-  'sharedMemory' | 'worker' | 'poolSize'
+  'sharedMemory' | 'worker' | 'workers' | 'poolSize'
 >;
 
 export interface ConnectIslandWorkerConfig extends IslandWorkerOptions {
@@ -64,13 +78,13 @@ export interface ConnectIslandWorkerConfig extends IslandWorkerOptions {
   /**
    * Default true — the client carries a SharedArrayBuffer doorbell for
    * push-mode flush (requires COOP/COEP cross-origin isolation). Pass
-   * `false` for a message-only pool: `setMode('push')` falls back to
+   * `false` for a message-only client: `setMode('push')` falls back to
    * polling and the page needs no special headers.
    */
   doorbell?: boolean;
 }
 
-/** One island client: one pool, one worker, one doorbell buffer. */
+/** One island client: one dedicated worker, one doorbell buffer. */
 export const connectIslandWorker = <W extends IslandWorkerDefinition = IslandWorkerDefinition>({
   worker,
   doorbell,
@@ -80,12 +94,17 @@ export const connectIslandWorker = <W extends IslandWorkerDefinition = IslandWor
     ...options,
     sharedMemory: doorbell === false ? undefined : makeDoorbell(),
     worker,
-    poolSize: 1,
+    workers: 1,
   });
 
 interface MountIslandBaseOptions {
-  /** Container element the island's ops are applied into. */
-  el: HTMLElement;
+  /**
+   * Container element the island's ops are applied into — a real element on
+   * the shell side, or a `ProxyElement` inside a worker-rendered island
+   * (nested mount: the sub-island's ops replay into the parent instance's
+   * shadow tree and tunnel upward through its op stream). Required.
+   */
+  el: HTMLElement | ProxyElement;
   /**
    * Registry app name — a key of the `apps` map passed to
    * `definePolyWorker`. Optional against a instance worker
@@ -103,6 +122,10 @@ interface MountIslandBaseOptions {
    * events, zero wire). Called again with `null` when the worker removes or
    * renames the element, so the shell can tear down. The element itself
    * stays worker-owned — its box/layout props apply normally.
+   *
+   * Nested mounts (a ProxyElement `el`) receive the anchor's ProxyElement
+   * instead, and only claim names present in this object (`name in slots`);
+   * unclaimed slot names bubble up to the outer island's `slots`.
    */
   slots?: Record<string, (el: HTMLElement | null) => void>;
   /** Fired after each applied op batch — the shell uses it for stats. */
@@ -121,6 +144,14 @@ 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', …). When
+   * omitted (and devtools is on), the driver asks the worker: package
+   * adapters report their renderer, imperative apps report none and the
+   * map draws them as plain workers. An explicit tag always wins.
+   */
+  framework?: string;
   /**
    * Milliseconds the mount handshake (mount + whoami) may take before the
    * returned promise rejects — default 15_000, `0` disables. A worker entry
@@ -148,6 +179,11 @@ export interface IslandHandle {
   readonly app: string;
   /** The worker-side instance's random id — proof each island is a distinct worker. */
   readonly pid: string;
+  /**
+   * The wire instance key — `app@N` for a top-level island, `parent~app@N`
+   * when mounted into a proxy element inside a worker island.
+   */
+  readonly instance: string;
   readonly mode: Mode;
   opsApplied: number;
   flushCalls: number;
@@ -240,6 +276,37 @@ function buildEventPayload(
   };
 }
 
+/**
+ * User Timing entry for one main-thread op replay (devtools only). The
+ * `detail.devtools` track-entry extension puts it on an 'atoll › islands'
+ * track in Chrome's Performance panel; other engines keep a plain measure.
+ * Same shape as core's task measures (`src/userTiming.ts`), including the
+ * immediate clear: per-batch entries would otherwise grow the buffer.
+ */
+const measureReplay = (instance: string, via: string, count: number, start: number, end: number): void => {
+  if (typeof performance?.measure !== 'function') return;
+  const name = `atoll replay ${instance}`;
+  try {
+    performance.measure(name, {
+      start,
+      end,
+      detail: {
+        devtools: {
+          dataType: 'track-entry',
+          trackGroup: 'atoll',
+          track: 'islands',
+          color: 'primary',
+          tooltipText: `${instance} · ${via} · ${count} ops`,
+          properties: [['via', via], ['ops', count]],
+        },
+      },
+    });
+    performance.clearMeasures?.(name);
+  } catch {
+    /* no User Timing L3 — skip */
+  }
+};
+
 /** Per-island instance counter — see the instance key note in mountIsland. */
 let islandSeq = 0;
 
@@ -289,7 +356,7 @@ const uncloneablePath = (value: unknown, path: string): string => {
   return path;
 };
 
-const assertCloneableProps = (props: Record<string, unknown>, context: string): void => {
+export const assertCloneableProps = (props: Record<string, unknown>, context: string): void => {
   if (canClone(props)) return;
   const path = uncloneablePath(props, '');
   throw new Error(
@@ -320,8 +387,10 @@ const UNITLESS_CSS = new Set([
 ]);
 
 /** Coerce a wire style value to a CSS string — px-suffixes bare numbers
- *  on non-unitless keys (custom properties pass verbatim). */
-const cssStyleValue = (key: string, value: unknown): string => {
+ *  on non-unitless keys (custom properties pass verbatim). Exported for the
+ *  worker-side nested driver (worker/subIsland.ts), which applies the same
+ *  unit semantics when replaying style values into proxy elements. */
+export const cssStyleValue = (key: string, value: unknown): string => {
   if (
     typeof value === 'number' &&
     value !== 0 &&
@@ -333,12 +402,48 @@ const cssStyleValue = (key: string, value: unknown): string => {
   return String(value);
 };
 
+/**
+ * The worker-side mounter — registered by `@atolljs/islands/worker`
+ * (`worker/subIsland.ts`) so `mountIsland` serves BOTH mount targets with
+ * one signature: a proxy `el` (inside a worker-rendered island) takes the
+ * nested path, which replays the sub-worker's ops into the parent
+ * instance's shadow tree. Kept behind a registration slot rather than an
+ * import so the main-thread bundle never loads the proxy DOM.
+ */
+let subMounter: ((opts: MountIslandOptions) => Promise<IslandHandle>) | null = null;
+export const registerSubIslandMounter = (
+  fn: (opts: MountIslandOptions) => Promise<IslandHandle>,
+): void => {
+  subMounter = fn;
+};
+
+/**
+ * Structural discriminant — a proxy element's `doc.instance` is the parent
+ * instance key, a real element has no `doc` property at all. Type beats
+ * environment sniffing: in-process harnesses run worker and shell in one
+ * module graph where globals lie, but the mount target never does.
+ */
+const isProxyMountTarget = (el: unknown): el is ProxyElement =>
+  typeof (el as { doc?: { instance?: unknown } } | null)?.doc?.instance === '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,
+    el: target, onEvent, onActivity, onOps, slots, mode: initialMode, mountTimeout,
+    client: givenClient, worker, app: givenApp, props: givenProps, framework,
     ...workerConfig
   } = opts;
+  if (isProxyMountTarget(target)) {
+    if (subMounter === null) {
+      throw new Error(
+        'mountIsland: a proxy-element mount target means a nested island — ' +
+          'the worker entry (`@atolljs/islands/worker`) must be loaded to register the sub-mounter.',
+      );
+    }
+    return subMounter(opts);
+  }
+  // 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;
   // 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.
@@ -349,6 +454,8 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
     return cbSeq;
   };
   const props = marshalCallbackProps(givenProps ?? {}, registerCb) as Record<string, unknown>;
+  /** The props as the caller last gave them — devtools previews/commands read these. */
+  let currentProps: Record<string, unknown> = givenProps ?? {};
   if (givenClient === undefined && worker === undefined) {
     throw new Error(
       'mountIsland: pass `worker` (a `() => new Worker(...)`/URL entry — this call builds the ' +
@@ -358,6 +465,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
   const client: IslandClient =
     givenClient ??
     connectIslandWorker({
+      name: givenApp,
       ...workerConfig,
       worker,
       // Poll-mode shorthand islands don't need SharedArrayBuffer at all —
@@ -442,9 +550,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 +878,62 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
           break;
         }
         // Not a DOM mutation — the island→shell channel.
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'island:event', instance, name: op.name, payload: previewValue(op.payload, 1024) });
+        }
         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 t1 = performance.now();
+    const replayMs = t1 - t0;
+    if (devtoolsEnabled()) {
+      emitDevtools({
+        type: 'island:ops', instance, via, count: ops.length, replayMs,
+        bytes: estimateCloneBytes(ops),
+      });
+      measureReplay(instance, via, ops.length, t0, t1);
+    }
+    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 +987,21 @@ 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)));
+    if (devtoolsEnabled()) {
+      // an explicit tag wins; otherwise ask the worker which renderer the app uses
+      const fw = framework ?? (await client.renderer(instance).catch(() => null)) ?? undefined;
+      emitDevtools({ type: 'island:mount', instance, app, pid, poolId: client.pool?.poolId, framework: fw });
+      emitDevtools({ type: 'island:props', instance, props: propsPreview(currentProps) });
+    }
   } 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 +1030,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'
@@ -905,6 +1056,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
   const handle: IslandHandle = {
     app,
     pid,
+    instance,
     get mode() {
       return mode;
     },
@@ -918,13 +1070,18 @@ 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');
+      currentProps = next;
+      if (devtoolsEnabled()) emitDevtools({ type: 'island:props', instance, props: propsPreview(next) });
     },
     flush: async () => {
-      applyOps(await client.flush(instance));
+      applyOps(await islandCall('flush', client.flush(instance)), 'flush');
     },
     destroy: () => {
       destroyed = true;
+      untrackDevtools?.();
+      untrackDevtools = null;
+      emitDevtools({ type: 'island:unmount', instance });
       unsubscribe?.();
       resizeObserver?.disconnect();
       if (pollTimer !== null) clearInterval(pollTimer);
@@ -936,7 +1093,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 +1101,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
@@ -956,5 +1112,9 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
       }
     },
   };
+  // Dashboard commands (`island.*`) — registered only while devtools is on.
+  let untrackDevtools: (() => void) | null = devtoolsEnabled()
+    ? trackIslandForDevtools({ handle, el, props: () => currentProps })
+    : null;
   return handle;
 }

package/src/ops.ts

@@ -212,4 +212,10 @@ export type IslandWorkerMethods = {
   unmount(instance: string): Op[];
   /** The mounted instance's random id — the island's "worker pid" badge. */
   whoami(instance: string): string;
+  /**
+   * The instance's renderer tag ('react', 'vue', …) from its adapter; null
+   * for imperative apps. Read by the driver only for devtools, and only
+   * when the mount declared no `framework`.
+   */
+  renderer(instance: string): string | null;
 };

package/src/worker/defineWorkers.ts

@@ -153,6 +153,13 @@ export interface RenderedHandle {
  */
 export interface RenderedIslandApp {
   mount(ctx: RenderContext): RenderedHandle | void;
+  /**
+   * Renderer tag ('react', 'vue', 'svelte', 'solid', 'angular'): set by the
+   * package adapters, reported by the `renderer` task so devtools can mark
+   * an island whose mount declared no `framework`. Hand-written adapters
+   * may set it; imperative apps have none.
+   */
+  renderer?: string;
 }
 /** The apps an island can mount — keyed by the name the shell passes to mount(). */
 export type IslandApp = ImperativeIslandApp | RenderedIslandApp;
@@ -266,10 +273,13 @@ const resolveApp = (name: string): IslandApp | undefined =>
 
 const newPid = (): string => `w-${Math.random().toString(36).slice(2, 8)}`;
 
-/** 'controls' or 'data-table@7' → 'data-table' — registry name part of a instance key. */
+/** 'controls' or 'data-table@7' → 'data-table' — registry name part of a instance key.
+ *  Nested keys ('host@1~counter@1', one '~' per level) resolve the last segment. */
 const appNameOf = (instance: string): string => {
   const at = instance.lastIndexOf('@');
-  return at === -1 ? instance : instance.slice(0, at);
+  const name = at === -1 ? instance : instance.slice(0, at);
+  const tilde = name.lastIndexOf('~');
+  return tilde === -1 ? name : name.slice(tilde + 1);
 };
 
 /**
@@ -617,6 +627,12 @@ function createIslandRuntime(
       whoami(instance: string): string {
         return mounts.get(instance)?.pid ?? 'unmounted';
       },
+
+      /** The instance's renderer tag (an adapter's `renderer`); null for imperative or unknown. */
+      renderer(instance: string): string | null {
+        const mounted = mounts.get(instance);
+        return (mounted && isRenderedInstance(mounted) && mounted.rendered.app.renderer) || null;
+      },
     },
   });
 }

package/src/worker/index.ts

@@ -47,6 +47,7 @@ export {
   instances,
   newElement,
   newText,
+  proxyInstanceStats,
   pushOp,
   registerHandler,
   ROOT_CONTAINER,
@@ -85,3 +86,19 @@ export type { EventPayload, IslandWorkerMethods, Op, WireProps } from '../ops';
 export { isEventRef } from '../ops';
 export { renderMemory } from '../memory';
 export type { DoorbellSpec } from '../memory';
+
+export { mountSubIsland } from './subIsland';
+export type { MountSubIslandOptions, SubIslandHandle } from './subIsland';
+
+// Nested-island clients: `connectIslandWorker` is thread-agnostic — a worker
+// shell calls it to spawn a sub-worker. `mountIsland` is the ONE surface:
+// a proxy `el` (inside a worker-rendered tree) delegates to the registered
+// sub-mounter in ./subIsland; a real `el` drives the main-thread applier.
+export { connectIslandWorker, mountIsland } from '../island';
+export type {
+  ConnectIslandWorkerConfig,
+  IslandClient,
+  IslandHandle,
+  Mode,
+  MountIslandOptions,
+} from '../island';

package/src/worker/instance.ts

@@ -237,10 +237,14 @@ export const proxyInstanceStats = (): {
   liveNodes: number;
   handlers: number;
   queuedOps: number;
+  queuedByInstance: Record<string, number>;
 } => ({
   liveNodes: instances.size,
   handlers: handlers.size,
   queuedOps: [...opsByInstance.values()].reduce((a, q) => a + q.length, 0),
+  queuedByInstance: Object.fromEntries(
+    [...opsByInstance.entries()].map(([k, q]) => [k, q.length]),
+  ),
 });
 
 export const getHandler = (id: number): HandlerEntry | undefined => handlers.get(id);