@atolljs/react-island 0.1.7 → 0.1.9

package/README.md

@@ -111,7 +111,47 @@ it with `<Island worker={mapWorker}/>` or `islandComponent<P>()` with no key.
 
 For multi-island-per-worker, share a client:
 `client={connectIslandWorker({ worker })}` mounts each island's instance into
-the SAME worker (separate reconcilers, op queues, and pids — one OS thread).
+the SAME worker (separate reconcilers, op queues, and pids, one OS thread).
+
+## Islands inside worker islands
+
+A worker-rendered React app mounts islands with the **same components**:
+`@atolljs/react-island/worker` re-exports `Island`, `islandComponent`,
+`lazyIsland` and `connectIslandWorker`. Inside a worker the container div is
+a proxy element, so the mount is routed to a sub-worker whose DOM tunnels
+up through the parent island. Props and semantics are identical:
+
+```tsx
+// a component in the PARENT worker's registry: its module is in the parent
+// worker's bundle, so the `new Worker` literal stays bundler-detectable
+import { useState } from 'react';
+import { connectIslandWorker, emit, Island } from '@atolljs/react-island/worker';
+
+const regionEntry = () =>
+  new Worker(new URL('./region.worker.tsx', import.meta.url), { type: 'module' });
+
+function Regions() {
+  const [cards] = useState(() => connectIslandWorker({ worker: regionEntry }));
+  return (
+    <>
+      <Island client={cards} app="region" props={{ region: 'us-east' }} />
+      <Island client={cards} app="region" props={{ region: 'eu-central' }} />
+      <Island worker={regionEntry} app="forecast" onEvent={(n, p) => emit(n, p)} />
+    </>
+  );
+}
+```
+
+- `worker` spawns a sub-worker for that mount; a shared `client` adds an
+  instance to one sub-worker (the two cards above share a thread, the
+  forecast doesn't).
+- `onEvent` runs in the parent island's scope, so `emit` relays to the page.
+- `slots` portal worker-side content into the sub-island's anchors; slot
+  names you don't list bubble up to the page shell's `slots`.
+- `SubIsland` is kept as an alias of `Island`.
+
+Nested `new Worker` needs an engine that supports it (Chrome, Firefox,
+Node).
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/react-island",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "React shell components for atoll-islands islands — <Island/>, islandComponent, lazyIsland",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
@@ -16,8 +16,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.7",
-    "@atolljs/islands": "0.1.7",
+    "@atolljs/core": "0.1.9",
+    "@atolljs/islands": "0.1.9",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-reconciler": "^0.34.0"

package/src/index.tsx

@@ -36,6 +36,14 @@
  *   is SHARED (several `<Island client={c}/>` mount mounts into one worker —
  *   the instance unmounts and the worker dies with the last island to leave).
  *
+ * Both threads, one API: `@atolljs/react-island/worker` re-exports these
+ * same `Island`/`islandComponent`/`lazyIsland` for worker-rendered trees.
+ * Inside a worker the container div is a proxy element, so `mountIsland`
+ * routes the mount to the nested path (a sub-worker spawned from this
+ * worker, ops tunneled through the parent island). `worker` vs `client`
+ * means the same thing on either thread: spawn a worker for this mount, or
+ * add an instance to an existing one.
+ *
  * The `app` prop accepts the registry name OR the app itself — a React
  * component, an `islandApp`-stamped value, or an `{ imperative }` def. Pass
  * the component to get `props` inference; `islandApp('name', Comp)` is the
@@ -87,8 +95,8 @@ export interface IslandProps<A = string>
   worker?: (() => Worker) | URL;
   client?: IslandClient;
   /**
-   * Extra pool options — concurrency, taskTimeout, respawn… (poolSize stays
-   * 1). `doorbell: false` builds the shorthand client message-only — no
+   * Extra client options — taskTimeout, respawn, lazy… (always one
+   * dedicated worker, no pool). `doorbell: false` builds the shorthand client message-only — no
    * SharedArrayBuffer, no COOP/COEP requirement (same as `mode: 'poll'` on
    * a direct `mountIsland` shorthand mount).
    */
@@ -101,6 +109,8 @@ export interface IslandProps<A = string>
    * Mount-time only; switch later via the handle's `setMode`.
    */
   mode?: Mode;
+  /** Renderer tag reported to devtools on mount ('react', 'vue', …). */
+  framework?: string;
   /** Initial + updated root props — serialized to the worker. */
   props?: IslandAppProps<A>;
   /** Island → shell channel: every `emit` op lands here. */
@@ -127,6 +137,7 @@ export function Island<A = string>({
   client: clientProp,
   workerOptions,
   mode,
+  framework,
   props,
   onEvent,
   onActivity,
@@ -193,7 +204,12 @@ export function Island<A = string>({
     const client =
       clientProp ??
       (resolvedWorker !== undefined
-        ? connectIslandWorker({ worker: resolvedWorker, ...workerOptions })
+        ? connectIslandWorker({
+            name: appName,
+            worker: resolvedWorker,
+            doorbell: mode !== 'poll',
+            ...workerOptions,
+          })
         : undefined);
     if (client === undefined) {
       report(new Error('<Island> requires either `worker` or `client`'));
@@ -203,10 +219,13 @@ export function Island<A = string>({
     // React portal anchors: the worker marks `data-atoll-slot="name"`, the
     // driver hands us the real element, and we render the matching slot
     // content into it with createPortal.
+    // `has` answers for the slots actually passed: a nested mount only
+    // claims names it lists and lets the rest bubble to the outer island.
     const slotProxy = new Proxy({} as Record<string, (el: HTMLElement | null) => void>, {
       get: (_t, name: string) => (e: HTMLElement | null) => {
         setSlotTargets((prev) => (prev[name] === e ? prev : { ...prev, [name]: e }));
       },
+      has: (_t, name: string) => slotsRef.current?.[name] != null,
     });
 
     void (async () => {
@@ -216,6 +235,7 @@ export function Island<A = string>({
           el,
           app: appName,
           mode,
+          framework,
           // Serialized across the wire either way — cast preserves inference
           // for props types without an index signature.
           props: (propsRef.current ?? {}) as Record<string, unknown>,
@@ -290,6 +310,8 @@ export interface IslandShellProps {
   workerOptions?: IslandWorkerOptions & { doorbell?: boolean };
   /** Initial flush mode — see IslandProps.mode. */
   mode?: Mode;
+  /** Devtools renderer tag — see IslandProps.framework. */
+  framework?: string;
   /** Island → shell channel: every `emit` op lands here. */
   onEvent?: (name: string, payload: unknown) => void;
   /** Fired after each applied op batch. */
@@ -314,6 +336,7 @@ const SHELL_PROP_KEYS: ReadonlySet<string> = new Set([
   'client',
   'workerOptions',
   'mode',
+  'framework',
   'onEvent',
   'onActivity',
   'onReady',
@@ -412,6 +435,7 @@ function ProxyIsland({
         client={shell.client}
         workerOptions={shell.workerOptions}
         mode={shell.mode}
+        framework={shell.framework}
         props={islandProps as Record<string, unknown>}
         onEvent={shell.onEvent}
         onActivity={shell.onActivity}

package/src/subIsland.tsx

@@ -0,0 +1,42 @@
+/**
+ * `SubIsland` — the original name for a nested mount, kept as an alias.
+ * New code uses `Island` from `@atolljs/react-island/worker`, which is the
+ * same component (and props) the page uses: inside a worker its container
+ * is a proxy element, so `mountIsland` routes to the nested path.
+ *
+ *   const subWorker = () =>
+ *     new Worker(new URL('./counter.worker.tsx', import.meta.url), { type: 'module' });
+ *
+ *   function Dashboard() {
+ *     return <Island worker={subWorker} app="counter" props={{ label: 'nested' }} />;
+ *   }
+ *
+ * `SubIsland` differs only in defaults: it tags devtools mounts as
+ * `framework: 'react'` and stamps `data-atoll-sub-island` on its host div.
+ */
+import type { CSSProperties, ReactElement } from 'react';
+import type { IslandClient, IslandHandle, Mode } from '@atolljs/islands/worker';
+import { Island } from './index';
+
+export interface SubIslandProps {
+  /** Bundler-detectable sub-worker entry, evaluated INSIDE this worker. */
+  worker?: (() => Worker) | URL;
+  /** A shared `connectIslandWorker` client built inside this worker. */
+  client?: IslandClient;
+  /** Registry app name — a key of the sub-worker's `apps` map. */
+  app?: string;
+  /** Wire props for the sub-app's root — serializable data only. */
+  props?: Record<string, unknown>;
+  /** Sub-island emit channel — a plain worker-side call. */
+  onEvent?: (name: string, payload: unknown) => void;
+  /** Flush transport — 'push' (default) or 'poll'. */
+  mode?: Mode;
+  className?: string;
+  style?: CSSProperties;
+  /** Receives the mounted handle (pid, instance, updateProps, destroy). */
+  onReady?: (handle: IslandHandle) => void;
+}
+
+export function SubIsland(props: SubIslandProps): ReactElement {
+  return <Island framework="react" data-atoll-sub-island="" {...props} />;
+}

package/src/worker.ts

@@ -52,6 +52,13 @@ import { createReactInstance } from './reactInstance';
 // island→shell channel — `import { emit } from '@atolljs/react-island/worker'`.
 export { emit, runInInstance } from '@atolljs/islands/worker';
 export { Slot } from './slot';
+// The page's mount components, unchanged: inside a worker the container is
+// a proxy element and mountIsland takes the nested (sub-worker) path.
+export { Island, islandComponent, lazyIsland } from './index';
+export type { IslandProps, IslandShellProps, IslandAppRef } from './index';
+export { connectIslandWorker } from '@atolljs/islands/worker';
+export { SubIsland } from './subIsland';
+export type { SubIslandProps } from './subIsland';
 
 type AnyComponent = ComponentType<Record<string, unknown>>;
 
@@ -72,6 +79,7 @@ export function reactIslandApp(
   contract?: IslandContract,
 ): RenderedIslandApp {
   const app: RenderedIslandApp = {
+    renderer: 'react',
     mount({ instance, props }: RenderContext): RenderedHandle {
       const react = createReactInstance(instance);
       const render = (next: Record<string, unknown>): void =>