@preact-mvc/atoll 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@preact-mvc/atoll",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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",
+    "./package.json": "./package.json",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@atolljs/core": "0.1.11",
+    "@atolljs/islands": "0.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwhenry3/preact-mvc",
+    "directory": "packages/atoll"
+  },
+  "license": "MIT"
+}

package/src/driver.ts

@@ -0,0 +1,123 @@
+/**
+ * `@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!) });
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * `@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 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 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/src/worker.ts

@@ -0,0 +1,74 @@
+/**
+ * `@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 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 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);
+/** Restore the scope `enterInstance` returned (`''` when there was none). */
+export const exitInstance = (prev: string | null): void => {
+  setActiveInstance(prev ?? '');
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.