@atolljs/core 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# AtollJS
+
+[![CI](https://github.com/jwhenry3/atolljs/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/jwhenry3/atolljs/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jwhenry3/atolljs/graph/badge.svg?branch=master)](https://codecov.io/gh/jwhenry3/atolljs)
+
+Typed shared-memory worker pools for TypeScript — deterministic `SharedArrayBuffer`
+layouts, first-class task methods, and cross-thread reactive state.
+
+## Packages
+
+| Package | What it is |
+|---|---|
+| `@atolljs/core` | Core SDK — `defineWorker`/`connectWorker` typed worker clients over `WorkerPool`, shared-memory contracts, `watch`/`observe`, codecs |
+| `@atolljs/react` | React hooks — `useObservable`, `useSharedValue`, `useTask` |
+| `@atolljs/vue` | Vue composables — `useObservable`, `useSharedValue`, `useTask` |
+| `@atolljs/solidjs` | Solid primitives — `createObservable`, `createSharedValue`, `createTask` |
+| `@atolljs/svelte` | Svelte 5 rune bindings — `observableValue`, `sharedValue`, `taskState` |
+| `@atolljs/angular` | Angular signals — `observableSignal`, `sharedValue`, `taskState` |
+| `@atolljs/nextjs` | Next.js client-component bindings (React re-export) |
+| `@atolljs/node` | `node:worker_threads` runtime adapter |
+| `@atolljs/nestjs` | NestJS module/decorators for worker pools |
+| `@atolljs/islands` | worker-side React reconciler + proxy DOM islands — opt-in DOM rendering |
+| `@atolljs/react-island` | React shell components for islands — `<Island/>`, `islandComponent`, `lazyIsland` |
+| `@atolljs/vue-island` | Vue shell (`useIsland`, `<AtollIsland>`) + Vue worker renderer |
+| `@atolljs/svelte-island` | Svelte shell (`use:island`, `createIslandState`) + Svelte 5 worker renderer |
+| `@atolljs/solid-island` | Solid shell (`createIsland`, `Island`) + `solid-js/universal` worker renderer |
+| `@atolljs/angular-island` | Angular shell (`<atoll-island>`, `[atollIsland]`) + `Renderer2` worker renderer |
+
+Framework bindings are published independently — install only the one you use:
+
+```bash
+npm install @atolljs/core @atolljs/react
+```
+
+## Documentation
+
+- **`docs/`** — in-repo markdown documentation covering internals, contracts,
+  islands, and per-framework bindings. Start at [`docs/README.md`](docs/README.md)
+  (agents: `AGENTS.md` points here before extensive work).
+- **`docs-consumer/`** — the consumer-facing package-usage site; deploys to
+  GitHub Pages on every push to `master`:
+  [jwhenry3.github.io/atolljs](https://jwhenry3.github.io/atolljs/) (`/consumer/`).
+
+## Releasing
+
+Create a GitHub Release tagged `v<semver>` — `.github/workflows/publish.yml`
+runs the full test suite, builds the core `dist`, stamps every publishable
+package at the tag's version (lockstep; `packages/incidents` stays private),
+and **stages** each to npm with provenance. Staged versions aren't
+installable until a maintainer approves them — `npm stage list` /
+`npm stage approve <stage-id>` (2FA at approval, not in CI), or the Staged
+Packages tab on npmjs.com. Requires a granular `NPM_TOKEN` repo secret.
+Preview the plan locally: `node scripts/publish.mjs v0.1.0 --dry-run`.
+
+Staging needs each package to already exist on the registry, so the first
+release is a manual bootstrap — from the repo root:
+
+```bash
+npm login                                    # once
+npm ci && npx vite build && npx tsc -p tsconfig.build.json
+node scripts/publish.mjs 0.1.0 --direct      # prompts for 2FA per package
+```
+
+Once all nine packages exist, release-driven `npm stage publish` works for
+every subsequent version.
+
+### Trusted publishing (OIDC)
+
+Prefer OIDC over the `NPM_TOKEN` secret — no long-lived credential, and a
+trust relationship can be **stage-only** so the workflow can't direct-publish
+even if compromised. Configure per package (needs the package to exist on
+npm, and npm CLI ≥ 11.10):
+
+```bash
+for p in atoll atoll-node atoll-react atoll-angular atoll-nestjs atoll-nextjs atoll-solidjs atoll-svelte atoll-vue; do
+  npm trust github "@atolljs/$p" --repo jwhenry3/atolljs --file publish.yml --allow-stage-publish -y
+  sleep 2
+done
+```
+
+Omit `--allow-publish` — stage-only. First call prompts for 2FA; choose
+"skip for 5 minutes" and the loop finishes hands-free. Verify with
+`npm trust list @atolljs/core`. Once all nine show the relationship,
+delete the `NODE_AUTH_TOKEN` env line in `publish.yml` (npm only uses OIDC
+when no token is present) — the secret can be revoked after.
+
+## Layout
+
+```
+src/            core SDK — contract/ (shared protocol), pool/, worker/
+packages/<fw>/      independently publishable framework bindings
+packages/incidents/ demo domain package (contract + worker + pool)
+examples/<fw>/      per-framework demo apps
+docs/               in-repo markdown documentation (internals + bindings)
+docs-consumer/      consumer docs site
+```
+
+## Scripts
+
+```bash
+npm test            # vitest — all suites (sdk + packages + example e2e)
+npm run build       # typecheck + lib build
+npm run dev:all     # launch every example dev server
+npm run build:pages # consumer docs + examples → dist-pages (GitHub Pages artifact)
+```
+
+Worker demos require cross-origin isolation (COOP/COEP) — the dev servers set it;
+GitHub Pages cannot send headers, so the Pages artifact ships `coi-sw.js`, a
+service worker that injects them (first visit reloads once; islands fall back to
+their poll transport where isolation still isn't available).

package/dist/index.js

@@ -0,0 +1,19 @@
+import { msgpackrCodec as e } from "./index2.js";
+import { listSchema as t } from "./index3.js";
+import { getLogLevel as n, log as r, scoped as i, setLogLevel as a, setLogSink as o } from "./index4.js";
+import { defineSharedMemory as s, field as c, getDefinedSharedMemoryCount as l, jsonCodec as u, registerConnectorFactory as d } from "./index5.js";
+import { mz as f } from "./index6.js";
+import { msgpackCodec as p } from "./index7.js";
+import { MemoryManager as m } from "./index8.js";
+import { PoolQueueFullError as h, TaskAbortedError as g, TaskTimeoutError as _, WorkerCrashedError as v } from "./index9.js";
+import { WorkerPool as y } from "./index10.js";
+import { connectWorker as b, workerClient as x } from "./index11.js";
+import { connectSharedWorker as S } from "./index12.js";
+import { TaskRegistry as C } from "./index13.js";
+import { sharedWorkerHost as w } from "./index14.js";
+import { createClient as T, defineService as E, implementService as D, rpc as O, serviceMethod as k } from "./index15.js";
+import { RESERVED_CLIENT_KEYS as A, defineWorker as j } from "./index17.js";
+import { reactive as M, shallowEqual as N, watch as P } from "./index18.js";
+import { observe as F } from "./index19.js";
+import { defineTask as I, isAsyncTask as L, toTask as R } from "./index20.js";
+export { m as MemoryManager, h as PoolQueueFullError, A as RESERVED_CLIENT_KEYS, g as TaskAbortedError, C as TaskRegistry, _ as TaskTimeoutError, v as WorkerCrashedError, y as WorkerPool, S as connectSharedWorker, b as connectWorker, T as createClient, E as defineService, s as defineSharedMemory, I as defineTask, j as defineWorker, c as field, l as getDefinedSharedMemoryCount, n as getLogLevel, D as implementService, L as isAsyncTask, u as jsonCodec, t as listSchema, r as log, p as msgpackCodec, e as msgpackrCodec, f as mz, F as observe, M as reactive, d as registerConnectorFactory, O as rpc, i as scoped, k as serviceMethod, a as setLogLevel, o as setLogSink, N as shallowEqual, w as sharedWorkerHost, R as toTask, P as watch, x as workerClient };

package/dist/index10.js

@@ -0,0 +1,186 @@
+import { fmtBytes as e, scoped as t } from "./index4.js";
+import { MemoryManager as n } from "./index8.js";
+import { PoolQueueFullError as r, TaskAbortedError as i, TaskTimeoutError as a, WorkerCrashedError as o } from "./index9.js";
+//#region src/pool/workerPool.ts
+var s = t("pool"), c = t("task"), l = () => ({
+	count: 0,
+	mean: 0,
+	max: 0,
+	add(e) {
+		this.count++, this.mean += (e - this.mean) / this.count, e > this.max && (this.max = e);
+	}
+}), u = class {
+	slots = [];
+	pending = /* @__PURE__ */ new Map();
+	nextMessageId = 0;
+	queue = [];
+	memoryManager;
+	workerUrl;
+	spawn;
+	concurrency;
+	maxQueue;
+	respawn;
+	taskTimeout;
+	closed = !1;
+	drainWaiters = [];
+	statsAgg = {
+		completed: 0,
+		failed: 0,
+		aborted: 0,
+		waitMs: l(),
+		runMs: l()
+	};
+	sharedMemory;
+	constructor(t) {
+		if (t.sharedMemory && (typeof SharedArrayBuffer > "u" || typeof crossOriginIsolated < "u" && !crossOriginIsolated)) throw Error("WorkerPool requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.");
+		if (!t.workerUrl && !t.createWorker) throw Error("WorkerPool requires either `workerUrl` or `createWorker` in its config.");
+		this.workerUrl = t.workerUrl, this.spawn = t.createWorker ?? (() => new Worker(this.workerUrl, { type: "module" })), this.concurrency = t.concurrency ?? 1, this.maxQueue = t.maxQueue ?? Infinity, this.respawn = t.respawn ?? !0, this.taskTimeout = t.taskTimeout, t.sharedMemory && (this.sharedMemory = t.sharedMemory, this.memoryManager = new n(t.memory), this.memoryManager.ensureCapacity(this.sharedMemory.totalBytes), this.sharedMemory.bind(this.memoryManager.getBuffer()));
+		let r = t.poolSize ?? "auto", i = r === "auto" ? navigator.hardwareConcurrency ?? 4 : r;
+		s.info(this.sharedMemory ? `spawning ${i} worker(s) with ${e(this.sharedMemory.totalBytes)} shared buffer` : `spawning ${i} worker(s), message-only`, { workerUrl: t.workerUrl ? String(t.workerUrl) : "createWorker()" }), s.debug("tip: setLogLevel('trace') for per-task detail");
+		for (let e = 0; e < i; e++) this.addWorker(this.spawn());
+		let a = t.tasks ?? {};
+		for (let [e, t] of Object.entries(a)) {
+			if (e in this) {
+				s.warn(`task "${e}" collides with a WorkerPool member — not installed`);
+				continue;
+			}
+			this[e] = (...e) => this.runTask(t, ...e);
+		}
+		Object.keys(a).length > 0 && s.info(`task methods: ${Object.keys(a).join(", ")}`);
+	}
+	addWorker(e) {
+		let t = {
+			worker: e,
+			inFlight: 0
+		};
+		return e.addEventListener("message", (e) => {
+			this.handleReply(t, e.data);
+		}), e.addEventListener("error", (e) => {
+			this.handleWorkerError(t, e);
+		}), this.memoryManager ? e.postMessage({
+			type: "INIT_MEMORY",
+			memory: this.memoryManager.memory
+		}) : e.postMessage({ type: "INIT" }), this.slots.push(t), s.debug(`worker spawned, ${this.memoryManager ? "INIT_MEMORY" : "INIT"} sent`), t;
+	}
+	handleReply(e, t) {
+		let n = t.messageId === void 0 ? void 0 : this.pending.get(t.messageId);
+		n && (this.pending.delete(t.messageId), e.inFlight--, this.detach(n), n.done || (n.done = !0, this.statsAgg.runMs.add(performance.now() - (n.sentAt ?? n.enqueuedAt)), t.success ? (this.statsAgg.completed++, c.debug(`← ${n.contract.taskId} ok`), n.resolve(t.result)) : (this.statsAgg.failed++, c.warn(`← ${n.contract.taskId} failed: ${t.error}`), n.reject(Error(t.error)))), this.drainQueue(), this.checkDrained());
+	}
+	handleWorkerError(e, t) {
+		if (this.closed) return;
+		let n = t, r = n?.message ?? (n?.error ? String(n.error) : "worker error");
+		s.warn(`worker error: ${r}`);
+		for (let [t, n] of [...this.pending]) if (n.slot === e) {
+			if (this.pending.delete(t), this.detach(n), n.done) continue;
+			n.done = !0, this.statsAgg.failed++, n.reject(new o(r));
+		}
+		let i = this.slots.indexOf(e);
+		if (i >= 0 && this.slots.splice(i, 1), e.worker.terminate(), this.respawn) s.info("respawning crashed worker"), this.addWorker(this.spawn());
+		else if (this.slots.length === 0) for (let e of this.queue.splice(0)) e.done = !0, this.detach(e), this.statsAgg.failed++, e.reject(new o(r));
+		this.drainQueue(), this.checkDrained();
+	}
+	pickWorker() {
+		let e;
+		for (let t of this.slots) t.inFlight >= this.concurrency || (!e || t.inFlight < e.inFlight) && (e = t);
+		return e;
+	}
+	drainQueue() {
+		let e;
+		for (; this.queue.length > 0 && (e = this.pickWorker());) {
+			let t = this.queue.shift();
+			t.done || this.send(e, t);
+		}
+	}
+	send(e, t) {
+		let n = this.nextMessageId++;
+		t.messageId = n, t.slot = e, t.sentAt = performance.now(), this.statsAgg.waitMs.add(performance.now() - t.enqueuedAt), e.inFlight++, this.pending.set(n, t), c.debug(`→ ${t.contract.taskId}`, {
+			worker: this.slots.indexOf(e),
+			args: t.args
+		}), e.worker.postMessage({
+			type: "EXECUTE_TASK",
+			messageId: n,
+			taskId: t.contract.taskId,
+			args: t.args
+		});
+	}
+	detach(e) {
+		e.timer && clearTimeout(e.timer), e.signal && e.onSignalAbort && e.signal.removeEventListener("abort", e.onSignalAbort);
+	}
+	cancel(e, t) {
+		if (e.done) return;
+		let n = this.queue.indexOf(e);
+		n >= 0 && this.queue.splice(n, 1), e.done = !0, this.detach(e), this.statsAgg.aborted++, e.reject(t), this.drainQueue(), this.checkDrained();
+	}
+	checkDrained() {
+		if (this.queue.length === 0 && this.pending.size === 0) {
+			let e = this.drainWaiters.splice(0);
+			for (let t of e) t();
+		}
+	}
+	dispatch(e, t, n) {
+		return this.closed || this.slots.length === 0 ? Promise.reject(new o("WorkerPool has been terminated — no workers available.")) : n?.signal?.aborted ? Promise.reject(new i()) : new Promise((o, s) => {
+			let c = {
+				contract: e,
+				args: t,
+				enqueuedAt: performance.now(),
+				resolve: o,
+				reject: s,
+				done: !1,
+				signal: n?.signal
+			};
+			n?.signal && (c.onSignalAbort = () => this.cancel(c, new i()), n.signal.addEventListener("abort", c.onSignalAbort, { once: !0 }));
+			let l = n?.timeout ?? this.taskTimeout;
+			l !== void 0 && (c.timer = setTimeout(() => this.cancel(c, new a()), l));
+			let u = this.pickWorker();
+			if (u) this.send(u, c);
+			else if (this.queue.length >= this.maxQueue) {
+				c.done = !0, this.detach(c), s(new r());
+				return;
+			} else this.queue.push(c);
+		});
+	}
+	runTask(e, ...t) {
+		return this.dispatch(e, t);
+	}
+	stats() {
+		return {
+			workers: this.slots.length,
+			idle: this.slots.filter((e) => e.inFlight === 0).length,
+			inFlight: this.pending.size,
+			queued: this.queue.length,
+			completed: this.statsAgg.completed,
+			failed: this.statsAgg.failed,
+			aborted: this.statsAgg.aborted,
+			waitMs: {
+				count: this.statsAgg.waitMs.count,
+				mean: this.statsAgg.waitMs.mean,
+				max: this.statsAgg.waitMs.max
+			},
+			runMs: {
+				count: this.statsAgg.runMs.count,
+				mean: this.statsAgg.runMs.mean,
+				max: this.statsAgg.runMs.max
+			}
+		};
+	}
+	close() {
+		return this.queue.length === 0 && this.pending.size === 0 ? (this.terminate(), Promise.resolve()) : new Promise((e) => {
+			this.drainWaiters.push(() => {
+				this.terminate(), e();
+			});
+		});
+	}
+	terminate() {
+		this.closed = !0, s.info(`terminating ${this.slots.length} worker(s)`);
+		let e = new o("pool terminated");
+		for (let [, t] of this.pending) this.detach(t), !t.done && (t.done = !0, this.statsAgg.failed++, t.reject(e));
+		this.pending.clear();
+		for (let t of this.queue.splice(0)) t.done = !0, this.detach(t), this.statsAgg.failed++, t.reject(e);
+		for (let e of this.slots) e.worker.terminate();
+		this.slots = [], this.checkDrained();
+	}
+};
+//#endregion
+export { u as WorkerPool };
+
+//# sourceMappingURL=index10.js.map

package/dist/index11.js

@@ -0,0 +1,52 @@
+import { WorkerPool as e } from "./index10.js";
+//#region src/pool/workerClient.ts
+var t = (e, n, r, i) => {
+	let a = /* @__PURE__ */ new Map();
+	return new Proxy(() => {}, {
+		get(o, s) {
+			if (s === "then" || typeof s == "symbol") return;
+			if (s === "with") return (i) => t(e, n, r, i);
+			if (e.length === 0 && r && s in r) return Reflect.get(r, s);
+			let c = a.get(s);
+			return c || (c = t([...e, s], n, r, i), a.set(s, c)), c;
+		},
+		apply(t, r, a) {
+			let o = n(), s = { taskId: e.join(".") };
+			return o.dispatch ? o.dispatch(s, a, i) : o.runTask(s, ...a);
+		}
+	});
+};
+function n(e) {
+	let n;
+	return t([], typeof e == "function" ? () => n ??= e() : () => e);
+}
+function r(n) {
+	let r = null, i = () => r ??= new e({
+		sharedMemory: n.sharedMemory,
+		createWorker: typeof n.worker == "function" ? n.worker : () => new Worker(n.worker, { type: "module" }),
+		poolSize: n.poolSize,
+		memory: n.memory,
+		concurrency: n.concurrency,
+		maxQueue: n.maxQueue,
+		respawn: n.respawn,
+		taskTimeout: n.taskTimeout
+	});
+	return n.lazy === !1 && i(), t([], i, {
+		start: () => {
+			i();
+		},
+		terminate: () => {
+			r?.terminate(), r = null;
+		},
+		get pool() {
+			return r;
+		},
+		get sharedMemory() {
+			return n.sharedMemory;
+		}
+	});
+}
+//#endregion
+export { r as connectWorker, n as workerClient };
+
+//# sourceMappingURL=index11.js.map

package/dist/index12.js

@@ -0,0 +1,66 @@
+import { scoped as e } from "./index4.js";
+//#region src/shared/sharedWorkerClient.ts
+var t = e("shared-client"), n = e("task"), r = class {
+	clientIndex;
+	sharedMemory;
+	port;
+	constructor(e, n, r) {
+		this.clientIndex = n, this.port = e, this.sharedMemory = r.sharedMemory;
+		let i = r.tasks ?? {};
+		for (let [e, n] of Object.entries(i)) {
+			if (e in this) {
+				t.warn(`task "${e}" collides with a SharedWorkerClient member — not installed`);
+				continue;
+			}
+			this[e] = (...e) => this.runTask(n, ...e);
+		}
+		Object.keys(i).length > 0 && t.info(`task methods: ${Object.keys(i).join(", ")}`);
+	}
+	runTask(e, ...t) {
+		return new Promise((r, i) => {
+			let a = Math.random().toString(36).substring(2), o = performance.now();
+			n.debug(`→ ${e.taskId}`, { args: t });
+			let s = (t) => {
+				let c = t.data;
+				if (c.messageId === a) {
+					this.port.removeEventListener("message", s);
+					let t = (performance.now() - o).toFixed(1);
+					c.success ? (n.debug(`← ${e.taskId} ok`, { ms: +t }), r(c.result)) : (n.warn(`← ${e.taskId} failed: ${c.error}`, { ms: +t }), i(Error(c.error)));
+				}
+			};
+			this.port.addEventListener("message", s), this.port.postMessage({
+				type: "EXECUTE_TASK",
+				messageId: a,
+				taskId: e.taskId,
+				args: t
+			});
+		});
+	}
+	disconnect() {
+		try {
+			this.port.postMessage({ type: "SHARED_DISCONNECT" });
+		} finally {
+			this.port.close();
+		}
+	}
+};
+async function i(e) {
+	if (typeof SharedArrayBuffer > "u" || typeof crossOriginIsolated < "u" && !crossOriginIsolated) throw Error("connectSharedWorker requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.");
+	if (!e.port && !e.workerUrl && !e.createWorker) throw Error("connectSharedWorker requires `workerUrl`, `createWorker`, or `port` in its config.");
+	let n = e.port ?? (e.createWorker ? e.createWorker().port : new SharedWorker(e.workerUrl, { type: "module" }).port);
+	return n.start(), await new Promise((i, a) => {
+		let o = setTimeout(() => a(/* @__PURE__ */ Error("connectSharedWorker: timed out waiting for the shared worker — is the host module calling sharedWorkerHost()?")), e.connectTimeoutMs ?? 1e4), s = (a) => {
+			let c = a.data;
+			c?.type === "SHARED_MEMORY" && (n.removeEventListener("message", s), clearTimeout(o), e.sharedMemory.bind(c.buffer), t.info(`connected as client #${c.clientIndex}`, { bytes: c.buffer.byteLength }), i(new r(n, c.clientIndex, e)));
+		};
+		n.addEventListener("message", s), n.postMessage({
+			type: "SHARED_CONNECT",
+			memoryBytes: e.sharedMemory.totalBytes,
+			memory: e.memory
+		});
+	});
+}
+//#endregion
+export { i as connectSharedWorker };
+
+//# sourceMappingURL=index12.js.map

package/dist/index13.js

@@ -0,0 +1,27 @@
+import { scoped as e } from "./index4.js";
+//#region src/worker/registry.ts
+var t = e("registry"), n = class {
+	static tasks = /* @__PURE__ */ new Map();
+	static register(e, n) {
+		this.tasks.set(e.taskId, {
+			contract: e,
+			handler: n
+		}), t.debug(`registered "${e.taskId}"`, {
+			args: e.argsSchema ? "validated" : "unvalidated",
+			result: e.resultSchema ? "validated" : "unvalidated"
+		});
+	}
+	static getContract(e) {
+		return this.tasks.get(e)?.contract;
+	}
+	static async execute(e, ...t) {
+		let n = this.tasks.get(e);
+		if (!n) throw Error(`Task handler not found for id: ${e}`);
+		let { contract: r, handler: i } = n, a = await i(...r.argsSchema ? r.argsSchema.parse(t) : t);
+		return r.resultSchema ? r.resultSchema.parse(a) : a;
+	}
+};
+//#endregion
+export { n as TaskRegistry };
+
+//# sourceMappingURL=index13.js.map

package/dist/index14.js

@@ -0,0 +1,63 @@
+import { fmtBytes as e, scoped as t } from "./index4.js";
+import { bindSharedMemories as n } from "./index5.js";
+import { MemoryManager as r } from "./index8.js";
+import { TaskRegistry as i } from "./index13.js";
+//#region src/shared/sharedWorkerHost.ts
+var a = t("shared-worker"), o = null, s = 0;
+function c(t, i) {
+	if (o) return o.buffer.byteLength < t && a.warn(`client requested ${e(t)} but buffer is ${e(o.buffer.byteLength)} — first client's capacity wins`), o;
+	let s = new r(i);
+	return s.ensureCapacity(t), o = s.memory, n(s.getBuffer()), a.info(`shared buffer allocated (${e(o.buffer.byteLength)})`), o;
+}
+function l(e) {
+	let t = ++s;
+	a.info(`client #${t} connected`), e.onmessage = async (n) => {
+		let r = n.data;
+		if (r?.type === "SHARED_CONNECT") {
+			let n = c(r.memoryBytes ?? 0, r.memory);
+			e.postMessage({
+				type: "SHARED_MEMORY",
+				buffer: n.buffer,
+				clientIndex: t
+			});
+			return;
+		}
+		if (r?.type === "EXECUTE_TASK") {
+			let { messageId: n, taskId: s, args: c } = r;
+			if (!o) {
+				e.postMessage({
+					messageId: n,
+					success: !1,
+					error: "Shared memory not initialized in worker."
+				});
+				return;
+			}
+			let l = performance.now();
+			try {
+				let r = await i.execute(s, ...c || []);
+				a.debug(`task ${s} → ${(performance.now() - l).toFixed(1)}ms (client #${t})`), e.postMessage({
+					messageId: n,
+					success: !0,
+					result: r
+				});
+			} catch (t) {
+				a.warn(`task ${s} failed: ${t.message || String(t)}`), e.postMessage({
+					messageId: n,
+					success: !1,
+					error: t.message || String(t)
+				});
+			}
+			return;
+		}
+		r?.type === "SHARED_DISCONNECT" && (e.close(), a.info(`client #${t} disconnected`));
+	}, e.start();
+}
+function u() {
+	self.onconnect = (e) => {
+		l(e.ports[0]);
+	};
+}
+//#endregion
+export { l as attachSharedPort, u as sharedWorkerHost };
+
+//# sourceMappingURL=index14.js.map

package/dist/index15.js

@@ -0,0 +1,50 @@
+import { scoped as e } from "./index4.js";
+import { TaskRegistry as t } from "./index13.js";
+//#region src/service.ts
+var n = e("service");
+function r(e = {}) {
+	return e;
+}
+function i(e) {
+	return e;
+}
+function a(e, t) {
+	let n = {};
+	for (let [r, i] of Object.entries(t)) {
+		let t = "def" in i ? i.def : i;
+		n[r] = {
+			taskId: t.taskId ?? `${e}.${r}`,
+			...t.dataType ? { dataType: t.dataType } : {},
+			...t.argsSchema ? { argsSchema: t.argsSchema } : {},
+			...t.resultSchema ? { resultSchema: t.resultSchema } : {}
+		};
+	}
+	return {
+		name: e,
+		tasks: n
+	};
+}
+function o(e, r) {
+	let i = Object.keys(e.tasks).filter((e) => {
+		let t = r[e];
+		return typeof t != "function" && typeof t?.run != "function";
+	});
+	if (i.length > 0) throw Error(`implementService("${e.name}"): missing handlers for ${i.join(", ")}`);
+	for (let [n, i] of Object.entries(e.tasks)) {
+		let e = r[n];
+		t.register(i, typeof e == "function" ? e.bind(r) : e.run.bind(e));
+	}
+	return n.info(`service "${e.name}" implemented — ${Object.keys(e.tasks).join(", ")}`), {
+		service: e,
+		handlers: r
+	};
+}
+function s(e, t) {
+	let n = {};
+	for (let [r, i] of Object.entries(e.tasks)) n[r] = (...e) => t.runTask(i, ...e);
+	return n;
+}
+//#endregion
+export { s as createClient, a as defineService, o as implementService, r as rpc, i as serviceMethod };
+
+//# sourceMappingURL=index15.js.map

package/dist/index16.js

@@ -0,0 +1,46 @@
+import { fmtBytes as e, scoped as t } from "./index4.js";
+import { bindSharedMemories as n, getDefinedSharedMemoryCount as r } from "./index5.js";
+import { TaskRegistry as i } from "./index13.js";
+//#region src/worker/workerBootstrap.ts
+var a = t("worker"), o = !1;
+typeof self > "u" ? a.warn("workerBootstrap: no worker global found — skipping message wiring") : self.onmessage = async (t) => {
+	let s = t.data;
+	if (s.type === "INIT") {
+		o = !0, r() > 0 && a.warn("pool sent INIT without memory, but shared-memory contracts are defined — field access will throw until bound"), a.info("initialized (message-only pool — no shared memory)");
+		return;
+	}
+	if (s.type === "INIT_MEMORY") {
+		let t = s.memory;
+		n(t.buffer), o = !0, a.info(`shared memory initialized (${e(t.buffer.byteLength)})`);
+		return;
+	}
+	if (s.type === "EXECUTE_TASK") {
+		let { messageId: e, taskId: t, args: n } = s;
+		if (!o) {
+			a.warn(`rejected ${t} — shared memory not initialized`), self.postMessage({
+				messageId: e,
+				success: !1,
+				error: "Shared memory not initialized in worker."
+			});
+			return;
+		}
+		let r = performance.now();
+		try {
+			let o = await i.execute(t, ...n || []);
+			a.debug(`task ${t} → ${(performance.now() - r).toFixed(1)}ms`), self.postMessage({
+				messageId: e,
+				success: !0,
+				result: o
+			});
+		} catch (n) {
+			a.warn(`task ${t} failed: ${n.message || String(n)}`), self.postMessage({
+				messageId: e,
+				success: !1,
+				error: n.message || String(n)
+			});
+		}
+	}
+};
+//#endregion
+
+//# sourceMappingURL=index16.js.map

package/dist/index17.js

@@ -0,0 +1,42 @@
+import { scoped as e } from "./index4.js";
+import { TaskRegistry as t } from "./index13.js";
+import "./index16.js";
+//#region src/worker/defineWorker.ts
+var n = e("worker"), r = [
+	"start",
+	"terminate",
+	"pool",
+	"sharedMemory",
+	"then",
+	"with"
+], i = (e) => typeof e == "object" && !!e && "run" in e, a = new Set(r);
+function o(e) {
+	let r = e.methods ?? {}, o = e.services ?? {}, s = 0, c = (e, n, r, o) => {
+		if (a.has(n)) throw Error(`defineWorker: "${n}" is reserved for the client API — rename the method`);
+		if (i(r)) {
+			let { def: n } = r;
+			t.register({
+				taskId: n.taskId ?? e,
+				...n.dataType ? { dataType: n.dataType } : {},
+				...n.argsSchema ? { argsSchema: n.argsSchema } : {},
+				...n.resultSchema ? { resultSchema: n.resultSchema } : {}
+			}, r.run.bind(r));
+		} else t.register({ taskId: e }, r.bind(o));
+		s++;
+	};
+	for (let [e, t] of Object.entries(r)) c(e, e, t, r);
+	for (let [e, t] of Object.entries(o)) {
+		if (a.has(e)) throw Error(`defineWorker: service name "${e}" is reserved for the client API — rename it`);
+		for (let [n, r] of Object.entries(t)) c(`${e}.${n}`, n, r, t);
+	}
+	n.info(`worker defined — ${s} method(s)`);
+	let l = {
+		methods: r,
+		services: o
+	};
+	return e.sharedMemory && (l.sharedMemory = e.sharedMemory), l;
+}
+//#endregion
+export { r as RESERVED_CLIENT_KEYS, o as defineWorker };
+
+//# sourceMappingURL=index17.js.map