@preact-mvc/atoll 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,66 @@
+# @preact-mvc/atoll
+
+[![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)](https://badge.socket.dev/npm/package/@preact-mvc/atoll)
+
+Framework-free worker-rendered islands, modeled on
+[Atoll](https://jwhenry3.github.io/atolljs/): a facade over
+`@atolljs/islands` + `@atolljs/core` that mounts a worker-hosted UI tree
+as an ordinary element. The worker renders against a proxy DOM; commits
+stream back over `postMessage` as ops the main-thread driver replays as
+real DOM. Nothing in this package knows about the framework — that's what
+`@preact-mvc/atoll-island` adds.
+
+**[preact-mvc — islands documentation](https://jwhenry3.github.io/preact-mvc/docs/islands/)**
+
+## Install
+
+```bash
+npm install @preact-mvc/atoll
+```
+
+## The contract is the shared module
+
+`defineIslandContract` names the registry app, declares emit payloads
+(validated worker-side with zod), and carries the worker factory — the
+one file both threads import:
+
+```ts
+// ticker.contract.ts
+import { defineIslandContract, z } from '@preact-mvc/atoll';
+
+export const tickerContract = defineIslandContract({
+  app: 'ticker',
+  events: {
+    'worker-ping': z.object({ count: z.number() }),
+  },
+  // The URL literal stays bundler-detectable — never hoist or compute it.
+  worker: () =>
+    new Worker(new URL('./ticker.worker.ts', import.meta.url), {
+      type: 'module',
+    }),
+});
+```
+
+## Shell side
+
+```ts
+import { mountIsland, connectIslandWorker, callbackProp } from '@preact-mvc/atoll';
+```
+
+- `mountIsland` — mount a registered worker app into a host element.
+- `connectIslandWorker` — drive an already-running worker.
+- `callbackProp` — mark a prop as a function that crosses the wire.
+- `islandApp`, `defineIslandContract`, `isIslandContract`, `z` — the
+  registry/contract API re-exported from `@atolljs/islands` +
+  `@atolljs/core`.
+- `@preact-mvc/atoll/worker` — the worker-side entry (proxy DOM,
+  instance dispatcher); import it only in worker code.
+
+Rules of the wire: props and event payloads must be `structuredClone`-able;
+functions cross only via `callbackProp` markers; worker code sees the
+proxy DOM and nothing else — `document` resolves through the instance
+dispatcher, never ambient globals.
+
+Published builds ship compiled `dist/` (`.js` + `.d.ts`).

package/dist/driver.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `@preact-mvc/atoll` shell surface — a thin facade over `@atolljs/islands`
+ * (docs/atoll/islands.md). The op protocol, proxy DOM, instance lifecycle,
+ * and op-replay driver are the real package now; this file only normalizes
+ * the worker option (an already-created WorkerLike counts as an entry, the
+ * real package wants a bundler-detectable factory or URL) and defaults the
+ * transport to message-only so mounts work without COOP/COEP headers —
+ * GitHub Pages can't serve them.
+ *
+ * Push mode still works: pass `mode: 'push'` on a `worker:` mount (builds a
+ * doorbell client) or `doorbell: true` on `connectIslandWorker`, and serve
+ * Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy:
+ * require-corp.
+ */
+import { callbackProp } from '@atolljs/islands';
+import type { IslandClient, IslandHandle, IslandWorkerOptions, Mode, Op } from '@atolljs/islands';
+export { callbackProp };
+export type { IslandClient, IslandHandle, Mode, Op };
+/**
+ * What a `worker:` option accepts: a bundler-detectable factory
+ * `() => new Worker(new URL(...))`, a URL, or an already-spawned worker
+ * (test doubles like `InProcessWorker` count — the real `Worker` type would
+ * reject them, so the surface is structural).
+ */
+export type WorkerLike = Pick<Worker, 'postMessage' | 'addEventListener' | 'removeEventListener' | 'terminate'>;
+export interface ConnectOptions extends IslandWorkerOptions {
+    /** Bundler-detectable factory / URL, or an already-spawned worker. */
+    worker: WorkerLike | (() => WorkerLike) | URL;
+    /**
+     * Shared-memory doorbell for push-mode flush — requires cross-origin
+     * isolation. Default false (message-only): mounts fall back to the 50ms
+     * poll, which needs no special headers.
+     */
+    doorbell?: boolean;
+    /**
+     * Keep the worker thread resident (but idle) when its last island
+     * destroys: the instance still unmounts — dispose hooks run, ops stop —
+     * but the thread's module graph and worker-side caches survive, so the
+     * next mount on this client is a warm start. Explicit `client.terminate()`
+     * still kills it.
+     */
+    keepAlive?: boolean;
+}
+/** One island client = one dedicated worker. Islands mounted with `client:`
+ *  share it; each `worker:` mount builds its own. */
+export declare function connectIslandWorker({ worker, doorbell, ...options }: ConnectOptions): IslandClient;
+export interface MountOptions extends IslandWorkerOptions {
+    /** Container the island's ops replay into. */
+    el: HTMLElement;
+    /**
+     * Which app to mount: the `apps` registry key, a stamped app
+     * (`islandApp`/`viewIsland` result), or a contract. Resolved through
+     * `islandAppNameOf` — bare components fall back to the function name.
+     */
+    app?: unknown;
+    props?: Record<string, unknown>;
+    /** Island → shell channel: receives every worker-side `emit(name, payload)`. */
+    onEvent?: (name: string, payload: unknown) => void;
+    /** `data-atoll-slot` transclusion holes — shell mounts real DOM inside. */
+    slots?: Record<string, (el: HTMLElement | null) => void>;
+    onActivity?: () => void;
+    onOps?: (ops: readonly Op[], elapsedMs: number) => void;
+    /**
+     * 'push' uses the doorbell SAB (cross-origin isolation required for
+     * `worker:` mounts); 'poll' (the default here) needs none.
+     */
+    mode?: Mode;
+    /** Devtools renderer tag ('preact-mvc'); the adapter sets it. */
+    framework?: string;
+    mountTimeout?: number;
+    /** This mount's destroy() leaves the client resident-but-idle. */
+    keepAlive?: boolean;
+    /** A shared `connectIslandWorker` client, OR an entry this mount owns. */
+    client?: IslandClient;
+    worker?: WorkerLike | (() => WorkerLike) | URL;
+}
+export declare function mountIsland(opts: MountOptions): Promise<IslandHandle>;

package/dist/driver.js

@@ -0,0 +1,34 @@
+/**
+ * `@preact-mvc/atoll` shell surface — a thin facade over `@atolljs/islands`
+ * (docs/atoll/islands.md). The op protocol, proxy DOM, instance lifecycle,
+ * and op-replay driver are the real package now; this file only normalizes
+ * the worker option (an already-created WorkerLike counts as an entry, the
+ * real package wants a bundler-detectable factory or URL) and defaults the
+ * transport to message-only so mounts work without COOP/COEP headers —
+ * GitHub Pages can't serve them.
+ *
+ * Push mode still works: pass `mode: 'push'` on a `worker:` mount (builds a
+ * doorbell client) or `doorbell: true` on `connectIslandWorker`, and serve
+ * Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy:
+ * require-corp.
+ */
+import { callbackProp, connectIslandWorker as atollConnectIslandWorker, islandAppNameOf, mountIsland as atollMountIsland, } from '@atolljs/islands';
+export { callbackProp };
+const asWorkerEntry = (w) => w instanceof URL ? w : typeof w === 'function' ? w : () => w;
+/** One island client = one dedicated worker. Islands mounted with `client:`
+ *  share it; each `worker:` mount builds its own. */
+export function connectIslandWorker({ worker, doorbell = false, ...options }) {
+    return atollConnectIslandWorker({ ...options, doorbell, worker: asWorkerEntry(worker) });
+}
+export function mountIsland(opts) {
+    const { worker, client, app, mode = 'poll', ...rest } = opts;
+    const name = islandAppNameOf(app);
+    if (app !== undefined && name === undefined) {
+        return Promise.reject(new Error('mountIsland: could not resolve an app name — pass the registry key ' +
+            'or stamp the app with islandApp(name, app)'));
+    }
+    const base = { ...rest, app: name, mode };
+    return client !== undefined
+        ? atollMountIsland({ ...base, client })
+        : atollMountIsland({ ...base, worker: asWorkerEntry(worker) });
+}

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

@@ -13,24 +13,11 @@
  */
 export { islandApp, islandAppNameOf } from '@atolljs/islands';
 export type { IslandAppProps } from '@atolljs/islands';
-export {
-  defineIslandContract,
-  isIslandContract,
-  withContract,
-  contractOf,
-  contractWorkerOf,
-} from '@atolljs/islands';
-export type {
-  IslandContract,
-  IslandContractEventHandler,
-  IslandContractEvents,
-  IslandContractProps,
-  IslandWorkerOptions,
-} from '@atolljs/islands';
+export { defineIslandContract, isIslandContract, withContract, contractOf, contractWorkerOf, } from '@atolljs/islands';
+export type { IslandContract, IslandContractEventHandler, IslandContractEvents, IslandContractProps, IslandWorkerOptions, } from '@atolljs/islands';
 export type { EventPayload, Op, WireProps } from '@atolljs/islands';
 export { z } from '@atolljs/core';
 export type { Schema } from '@atolljs/core';
-
 export { mountIsland, connectIslandWorker, callbackProp } from './driver';
 export type { ConnectOptions, MountOptions, WorkerLike } from './driver';
 export type { IslandClient, IslandHandle, Mode } from './driver';

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@preact-mvc/atoll` — the shell-facing facade over the real Atoll
+ * packages (`@atolljs/islands` + `@atolljs/core`). Worker islands render
+ * inside Web Workers against a proxy DOM; commits stream back as ops the
+ * driver replays onto real DOM.
+ *
+ * Shell side (this entry): `mountIsland`, `connectIslandWorker`,
+ * `callbackProp`, `islandApp`. Worker side (import in worker entries):
+ * the `./worker` subpath re-exports `@atolljs/islands/worker` —
+ * `definePolyWorker`/`defineMonoWorker`, `emit`, instance scope. The
+ * preact-mvc adapter and `<Island/>` shell components live in
+ * `@preact-mvc/atoll-island`.
+ */
+export { islandApp, islandAppNameOf } from '@atolljs/islands';
+export { defineIslandContract, isIslandContract, withContract, contractOf, contractWorkerOf, } from '@atolljs/islands';
+export { z } from '@atolljs/core';
+export { mountIsland, connectIslandWorker, callbackProp } from './driver';

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

@@ -5,20 +5,7 @@
  *   import { definePolyWorker } from '@preact-mvc/atoll/worker';
  *   export const worker = definePolyWorker({ apps: { ... } });
  */
-export {
-  definePolyWorker,
-  defineMonoWorker,
-  islandApp,
-  islandAppNameOf,
-  emit,
-  runInInstance,
-  getActiveInstance,
-  getLastActiveInstance,
-  getLastTouchedInstance,
-  setActiveInstance,
-  installDomShim,
-  ProxyElement,
-} from '@atolljs/islands/worker';
+export { definePolyWorker, defineMonoWorker, islandApp, islandAppNameOf, emit, runInInstance, getActiveInstance, getLastActiveInstance, getLastTouchedInstance, setActiveInstance, installDomShim, ProxyElement, } from '@atolljs/islands/worker';
 /**
  * Nested-island surfaces: `mountIsland` is the ONE mount API on both
  * threads — a ProxyElement target (inside a worker-rendered tree) routes
@@ -30,45 +17,21 @@ export {
  * `new Worker` needs an engine that supports it — Chrome/Firefox/Node,
  * NOT Safari workers.
  */
-export {
-  connectIslandWorker,
-  mountIsland,
-  callbackProp,
-} from './driver';
+export { connectIslandWorker, mountIsland, callbackProp, } from './driver';
 export type { ConnectIslandWorkerConfig, MountIslandOptions } from '@atolljs/islands/worker';
-export {
-  defineIslandContract,
-  isIslandContract,
-  withContract,
-  contractOf,
-} from '@atolljs/islands/worker';
-export type {
-  ImperativeIslandApp,
-  IslandApp,
-  IslandContract,
-  PolyWorkerRegistry,
-  ProxyDocument,
-  RenderContext,
-  RenderedHandle,
-  RenderedIslandApp,
-} from '@atolljs/islands/worker';
+export { defineIslandContract, isIslandContract, withContract, contractOf, } from '@atolljs/islands/worker';
+export type { ImperativeIslandApp, IslandApp, IslandContract, PolyWorkerRegistry, ProxyDocument, RenderContext, RenderedHandle, RenderedIslandApp, } from '@atolljs/islands/worker';
 export type { EventPayload, Op, WireProps } from '@atolljs/islands/worker';
 export type { IslandWorkerDefinition } from '@atolljs/islands';
-
-import { setActiveInstance } from '@atolljs/islands/worker';
 import type { IslandWorkerDefinition } from '@atolljs/islands';
-
 /** What `definePolyWorker`/`defineMonoWorker` return — the worker def type
  *  island clients type-check against. */
 export type IslandWorkerDef = IslandWorkerDefinition;
-
 /**
  * Enter `key`'s instance scope, returning the previous key for restore —
  * a named pair around `setActiveInstance` (which returns the prev itself),
  * used by the preact-mvc adapter's out-of-task render scoping.
  */
-export const enterInstance = (key: string): string => setActiveInstance(key);
+export declare const enterInstance: (key: string) => string;
 /** Restore the scope `enterInstance` returned (`''` when there was none). */
-export const exitInstance = (prev: string | null): void => {
-  setActiveInstance(prev ?? '');
-};
+export declare const exitInstance: (prev: string | null) => void;

package/dist/worker.js

@@ -0,0 +1,32 @@
+/**
+ * `@preact-mvc/atoll/worker` — the worker-side entry, re-exported from
+ * `@atolljs/islands/worker`. Import in worker entries only:
+ *
+ *   import { definePolyWorker } from '@preact-mvc/atoll/worker';
+ *   export const worker = definePolyWorker({ apps: { ... } });
+ */
+export { definePolyWorker, defineMonoWorker, islandApp, islandAppNameOf, emit, runInInstance, getActiveInstance, getLastActiveInstance, getLastTouchedInstance, setActiveInstance, installDomShim, ProxyElement, } from '@atolljs/islands/worker';
+/**
+ * Nested-island surfaces: `mountIsland` is the ONE mount API on both
+ * threads — a ProxyElement target (inside a worker-rendered tree) routes
+ * to the registered sub-mounter and spawns a real sub-worker; a real
+ * element drives the main-thread applier. `connectIslandWorker` is
+ * thread-agnostic and spawns from whichever thread calls it. Re-exported
+ * through our driver facade so the same worker-option normalization and
+ * message-only defaults apply on nested mounts. Platform note: nested
+ * `new Worker` needs an engine that supports it — Chrome/Firefox/Node,
+ * NOT Safari workers.
+ */
+export { connectIslandWorker, mountIsland, callbackProp, } from './driver';
+export { defineIslandContract, isIslandContract, withContract, contractOf, } from '@atolljs/islands/worker';
+import { setActiveInstance } from '@atolljs/islands/worker';
+/**
+ * Enter `key`'s instance scope, returning the previous key for restore —
+ * a named pair around `setActiveInstance` (which returns the prev itself),
+ * used by the preact-mvc adapter's out-of-task render scoping.
+ */
+export const enterInstance = (key) => setActiveInstance(key);
+/** Restore the scope `enterInstance` returned (`''` when there was none). */
+export const exitInstance = (prev) => {
+    setActiveInstance(prev ?? '');
+};

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "@preact-mvc/atoll",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-free worker-rendered islands: op protocol, proxy DOM, worker runtime, main-thread driver",
   "type": "module",
   "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"
   },
   "publishConfig": {
     "access": "public",
@@ -30,5 +35,6 @@
     "url": "https://github.com/jwhenry3/preact-mvc",
     "directory": "packages/atoll"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "types": "./dist/index.d.ts"
 }

package/src/driver.ts

@@ -1,123 +0,0 @@
-/**
- * `@preact-mvc/atoll` shell surface — a thin facade over `@atolljs/islands`
- * (docs/atoll/islands.md). The op protocol, proxy DOM, instance lifecycle,
- * and op-replay driver are the real package now; this file only normalizes
- * the worker option (an already-created WorkerLike counts as an entry, the
- * real package wants a bundler-detectable factory or URL) and defaults the
- * transport to message-only so mounts work without COOP/COEP headers —
- * GitHub Pages can't serve them.
- *
- * Push mode still works: pass `mode: 'push'` on a `worker:` mount (builds a
- * doorbell client) or `doorbell: true` on `connectIslandWorker`, and serve
- * Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy:
- * require-corp.
- */
-import {
-  callbackProp,
-  connectIslandWorker as atollConnectIslandWorker,
-  islandAppNameOf,
-  mountIsland as atollMountIsland,
-} from '@atolljs/islands';
-import type {
-  IslandClient,
-  IslandHandle,
-  IslandWorkerOptions,
-  Mode,
-  Op,
-} from '@atolljs/islands';
-
-export { callbackProp };
-export type { IslandClient, IslandHandle, Mode, Op };
-
-/**
- * What a `worker:` option accepts: a bundler-detectable factory
- * `() => new Worker(new URL(...))`, a URL, or an already-spawned worker
- * (test doubles like `InProcessWorker` count — the real `Worker` type would
- * reject them, so the surface is structural).
- */
-export type WorkerLike = Pick<
-  Worker,
-  'postMessage' | 'addEventListener' | 'removeEventListener' | 'terminate'
->;
-
-const asWorkerEntry = (
-  w: WorkerLike | (() => WorkerLike) | URL,
-): (() => Worker) | URL =>
-  w instanceof URL ? w : typeof w === 'function' ? (w as () => Worker) : () => w as Worker;
-
-export interface ConnectOptions extends IslandWorkerOptions {
-  /** Bundler-detectable factory / URL, or an already-spawned worker. */
-  worker: WorkerLike | (() => WorkerLike) | URL;
-  /**
-   * Shared-memory doorbell for push-mode flush — requires cross-origin
-   * isolation. Default false (message-only): mounts fall back to the 50ms
-   * poll, which needs no special headers.
-   */
-  doorbell?: boolean;
-  /**
-   * Keep the worker thread resident (but idle) when its last island
-   * destroys: the instance still unmounts — dispose hooks run, ops stop —
-   * but the thread's module graph and worker-side caches survive, so the
-   * next mount on this client is a warm start. Explicit `client.terminate()`
-   * still kills it.
-   */
-  keepAlive?: boolean;
-}
-
-/** One island client = one dedicated worker. Islands mounted with `client:`
- *  share it; each `worker:` mount builds its own. */
-export function connectIslandWorker({
-  worker,
-  doorbell = false,
-  ...options
-}: ConnectOptions): IslandClient {
-  return atollConnectIslandWorker({ ...options, doorbell, worker: asWorkerEntry(worker) });
-}
-
-export interface MountOptions extends IslandWorkerOptions {
-  /** Container the island's ops replay into. */
-  el: HTMLElement;
-  /**
-   * Which app to mount: the `apps` registry key, a stamped app
-   * (`islandApp`/`viewIsland` result), or a contract. Resolved through
-   * `islandAppNameOf` — bare components fall back to the function name.
-   */
-  app?: unknown;
-  props?: Record<string, unknown>;
-  /** Island → shell channel: receives every worker-side `emit(name, payload)`. */
-  onEvent?: (name: string, payload: unknown) => void;
-  /** `data-atoll-slot` transclusion holes — shell mounts real DOM inside. */
-  slots?: Record<string, (el: HTMLElement | null) => void>;
-  onActivity?: () => void;
-  onOps?: (ops: readonly Op[], elapsedMs: number) => void;
-  /**
-   * 'push' uses the doorbell SAB (cross-origin isolation required for
-   * `worker:` mounts); 'poll' (the default here) needs none.
-   */
-  mode?: Mode;
-  /** Devtools renderer tag ('preact-mvc'); the adapter sets it. */
-  framework?: string;
-  mountTimeout?: number;
-  /** This mount's destroy() leaves the client resident-but-idle. */
-  keepAlive?: boolean;
-  /** A shared `connectIslandWorker` client, OR an entry this mount owns. */
-  client?: IslandClient;
-  worker?: WorkerLike | (() => WorkerLike) | URL;
-}
-
-export function mountIsland(opts: MountOptions): Promise<IslandHandle> {
-  const { worker, client, app, mode = 'poll', ...rest } = opts;
-  const name = islandAppNameOf(app);
-  if (app !== undefined && name === undefined) {
-    return Promise.reject(
-      new Error(
-        'mountIsland: could not resolve an app name — pass the registry key ' +
-          'or stamp the app with islandApp(name, app)',
-      ),
-    );
-  }
-  const base = { ...rest, app: name, mode };
-  return client !== undefined
-    ? atollMountIsland({ ...base, client })
-    : atollMountIsland({ ...base, worker: asWorkerEntry(worker!) });
-}