@atolljs/core 0.1.0 → 0.1.2

package/README.md

@@ -1,47 +1,171 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/atoll-dark.svg" />
+  <source media="(prefers-color-scheme: light)" srcset="assets/atoll-light.svg" />
+  <img src="assets/atoll-light.svg" alt="Atoll — islands of framework workers around a shared core" width="280" />
+</picture>
+
 # 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)
+[![CI](https://github.com/jwhenry3/atolljs/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jwhenry3/atolljs/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jwhenry3/atolljs/graph/badge.svg?branch=main)](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.
+layouts, first-class task methods, and cross-thread reactive state. A worker
+atoll: pools and shared workers joined to your app through one shared-memory
+fabric, so work is offloaded as typed method calls while large state stays put
+(zero-copy, no postMessage serialization of the values themselves).
 
-## Packages
+**[Atoll — package documentation](https://jwhenry3.github.io/atolljs/consumer/quickstart/)**
 
-| 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:
+## Install
 
 ```bash
-npm install @atolljs/core @atolljs/react
+npm install @atolljs/core            # the whole SDK
+npm install @atolljs/react           # + one framework binding, if you use one
 ```
 
+Framework bindings are published independently — install only the one you use.
+
+## Quickstart
+
+A minimal counter — one shared field, one worker method, one component.
+Four files, and the method name is written exactly once.
+
+```ts
+// counter.memory.ts — shared memory, imported by both threads
+import { defineSharedMemory, field } from '@atolljs/core';
+
+export const counterMemory = defineSharedMemory({
+  count: field.number(),
+});
+```
+
+```ts
+// counter.worker.ts — the worker entry; methods live here
+import { defineWorker } from '@atolljs/core';
+import { counterMemory } from './counter.memory';
+
+export const counterWorker = defineWorker({
+  sharedMemory: counterMemory,
+  methods: {
+    increment(delta: number) {
+      const next = counterMemory.count.read() + delta;
+      counterMemory.count.write(next);  // write in place — no postMessage
+      return next;
+    },
+  },
+});
+export type CounterWorker = typeof counterWorker;
+```
+
+```ts
+// counter.ts — the typed client; import type only, no worker code in this bundle
+import { connectWorker } from '@atolljs/core';
+import { counterMemory } from './counter.memory';
+import type { CounterWorker } from './counter.worker';
+
+export const counter = connectWorker<CounterWorker>({
+  sharedMemory: counterMemory,
+  // Inline new Worker(new URL(..., import.meta.url)) — every bundler's
+  // worker transform can see the entry point this way.
+  worker: () => new Worker(new URL('./counter.worker.ts', import.meta.url), { type: 'module' }),
+  poolSize: 'auto',   // navigator.hardwareConcurrency, or pass a number
+});
+// counter.increment(1) → Promise<number>. The pool spawns on first call
+// (SSR-safe to import); counter.terminate() tears it down.
+```
+
+```tsx
+// App.tsx — bind it in your framework
+import { useSharedValue, useTask } from '@atolljs/react';
+import { counterMemory } from './counter.memory';
+import { counter } from './counter';
+
+export function App() {
+  const count = useSharedValue(counterMemory, 'count');
+  const increment = useTask(counter.increment);   // latest-wins task state
+  return <button onClick={() => increment.run(1)}>count: {count ?? '…'}</button>;
+}
+```
+
+`increment.run(1)` posts the call to a worker, the worker writes `count` in
+place, and the binding re-renders on the next field write.
+
+Shared memory is opt-in: leave `sharedMemory` out of both `defineWorker` and
+`connectWorker` and you get a typed, pooled, cancellable worker RPC that runs
+anywhere Workers do — no isolation headers needed. With shared memory,
+`SharedArrayBuffer` requires
+[cross-origin isolation headers](https://jwhenry3.github.io/atolljs/consumer/hosting/)
+(COOP/COEP) in the browser; Node needs nothing.
+
+## Packages
+
+`@atolljs/core` is the SDK; everything else is independently published —
+install only what you use.
+
+### Framework bindings
+
+| Framework | Package | What it is | Docs |
+|---|---|---|---|
+| React | [`@atolljs/react`](https://www.npmjs.com/package/@atolljs/react) | Hooks — `useObservable`, `useSharedValue`, `useTask` | [React guide](https://jwhenry3.github.io/atolljs/consumer/fw-react/) |
+| Vue | [`@atolljs/vue`](https://www.npmjs.com/package/@atolljs/vue) | Composables — `useObservable`, `useSharedValue`, `useTask` | [Vue guide](https://jwhenry3.github.io/atolljs/consumer/fw-vue/) |
+| SolidJS | [`@atolljs/solidjs`](https://www.npmjs.com/package/@atolljs/solidjs) | Primitives — `createObservable`, `createSharedValue`, `createTask` | [SolidJS guide](https://jwhenry3.github.io/atolljs/consumer/fw-solid/) |
+| Svelte | [`@atolljs/svelte`](https://www.npmjs.com/package/@atolljs/svelte) | Svelte 5 rune bindings — `observableValue`, `sharedValue`, `taskState` | [Svelte guide](https://jwhenry3.github.io/atolljs/consumer/fw-svelte/) |
+| Angular | [`@atolljs/angular`](https://www.npmjs.com/package/@atolljs/angular) | Signals + DI — `observableSignal`, `sharedValue`, `taskState`, `provideAtoll` | [Angular guide](https://jwhenry3.github.io/atolljs/consumer/fw-angular/) |
+| Next.js | [`@atolljs/nextjs`](https://www.npmjs.com/package/@atolljs/nextjs) | Client-component bindings (React re-export) | [Next.js guide](https://jwhenry3.github.io/atolljs/consumer/fw-nextjs/) |
+| NestJS | [`@atolljs/nestjs`](https://www.npmjs.com/package/@atolljs/nestjs) | Server-side module/decorators for worker pools | [NestJS guide](https://jwhenry3.github.io/atolljs/consumer/fw-nestjs/) |
+
+### Worker islands — render framework trees off the main thread
+
+| Framework | Package | What it is | Docs |
+|---|---|---|---|
+| *(engine)* | [`@atolljs/islands`](https://www.npmjs.com/package/@atolljs/islands) | `mountIsland`, op protocol, proxy DOM, worker runtimes | [Worker islands](https://jwhenry3.github.io/atolljs/consumer/islands/) |
+| React | [`@atolljs/react-island`](https://www.npmjs.com/package/@atolljs/react-island) | `<Island/>`, `islandComponent`, `lazyIsland` | [React islands](https://jwhenry3.github.io/atolljs/consumer/fw-react/worker-islands/) |
+| Vue | [`@atolljs/vue-island`](https://www.npmjs.com/package/@atolljs/vue-island) | `useIsland`, `<AtollIsland>` + Vue worker renderer | [Vue islands](https://jwhenry3.github.io/atolljs/consumer/fw-vue/worker-islands/) |
+| Svelte | [`@atolljs/svelte-island`](https://www.npmjs.com/package/@atolljs/svelte-island) | `use:island`, `createIslandState` + Svelte 5 worker renderer | [Svelte islands](https://jwhenry3.github.io/atolljs/consumer/fw-svelte/worker-islands/) |
+| SolidJS | [`@atolljs/solid-island`](https://www.npmjs.com/package/@atolljs/solid-island) | `createIsland`, `Island`, `islandComponent`, `lazyIsland` + `solid-js/universal` worker renderer | [Solid islands](https://jwhenry3.github.io/atolljs/consumer/fw-solid/worker-islands/) |
+| Angular | [`@atolljs/angular-island`](https://www.npmjs.com/package/@atolljs/angular-island) | `islandComponent` facades typed off `@AngularIsland` worker components, `<atoll-island>`/`[atollIsland]` + `Renderer2` worker renderer | [Angular islands](https://jwhenry3.github.io/atolljs/consumer/fw-angular/worker-islands/) |
+
+### Runtimes
+
+| Package | What it is | Docs |
+|---|---|---|
+| [`@atolljs/core`](https://www.npmjs.com/package/@atolljs/core) | Core SDK — `defineWorker`/`connectWorker` typed worker clients over `WorkerPool`, shared-memory contracts, `watch`/`observe`, codecs | [Quickstart](https://jwhenry3.github.io/atolljs/consumer/quickstart/) · [Shared memory](https://jwhenry3.github.io/atolljs/consumer/shared-memory/) · [Tasks](https://jwhenry3.github.io/atolljs/consumer/tasks/) |
+| [`@atolljs/node`](https://www.npmjs.com/package/@atolljs/node) | `node:worker_threads` runtime adapter | [Tasks](https://jwhenry3.github.io/atolljs/consumer/tasks/) |
+
 ## 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/`).
+- **[Atoll — package documentation](https://jwhenry3.github.io/atolljs/consumer/quickstart/)** —
+  the consumer-facing site: quickstart, API guides, framework pages, islands,
+  hosting & headers.
+- [`docs/`](docs/README.md) — in-repo documentation covering internals,
+  contracts, islands, and per-framework bindings (agents: `AGENTS.md` points
+  here before extensive work).
+
+## Developing this repo
+
+```
+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 (deploys to GitHub Pages on main)
+```
+
+```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)
+```
 
-## Releasing
+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).
+
+### Releasing
 
 Create a GitHub Release tagged `v<semver>` — `.github/workflows/publish.yml`
 runs the full test suite, builds the core `dist`, stamps every publishable
@@ -50,7 +174,13 @@ 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`.
+Preview the plan locally: `node scripts/publish.mjs v0.1.0 --dry-run` —
+it lists the exact tarball contents (`npm pack --dry-run`) and the stage
+commands, with nothing written or published. The workflow run ends with a
+step-summary table of every package staged and its result; each publishable
+manifest also pins `publishConfig.registry` to `registry.npmjs.org`, so the
+destination is declared in the repo rather than resolved from the
+publisher's local npmrc.
 
 Staging needs each package to already exist on the registry, so the first
 release is a manual bootstrap — from the repo root:
@@ -61,10 +191,10 @@ 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
+Once every package exists, release-driven `npm stage publish` works for
 every subsequent version.
 
-### Trusted publishing (OIDC)
+#### 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
@@ -72,7 +202,8 @@ 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
+for p in core node react vue solidjs svelte angular nextjs nestjs \
+         islands react-island vue-island svelte-island solid-island angular-island; do
   npm trust github "@atolljs/$p" --repo jwhenry3/atolljs --file publish.yml --allow-stage-publish -y
   sleep 2
 done
@@ -80,31 +211,6 @@ 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,
+`npm trust list @atolljs/core`. Once every package shows 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/contract/listSchema.d.ts

@@ -0,0 +1,47 @@
+import { z } from './zod';
+import type { ListFieldSpec, ListFields, ListMember } from './sharedMemory';
+/** Maps a list member to the zod shape whose inferred output type is
+ *  identical to `ListRecord<F>[K]` — zod members pass through as
+ *  themselves so declared bounds (e.g. `.max(3)`) stay in effect. */
+export type ListZodShape<F extends ListFields> = {
+    [K in keyof F]: F[K] extends z.ZodTypeAny ? F[K] : F[K] extends {
+        string: number;
+    } ? z.ZodType<string> : F[K] extends {
+        bool: boolean;
+    } ? z.ZodType<boolean> : F[K] extends 'i64' | 'u64' ? z.ZodType<bigint> : z.ZodType<number>;
+};
+/**
+ * Builds a zod object schema from a member map — the shape you would pass
+ * to `mz.object(...)` for `field.list({ schema, count })`. Members may be
+ * spec tokens or zod schemas; the result's `z.infer` is the record type:
+ *
+ * ```ts
+ * const shape = { id: 'u32', site: { string: 10 } } as const;
+ * const schema = listSchema(shape);            // zod object with storage bounds
+ * type Row = z.infer<typeof schema>;
+ * ```
+ *
+ * `{ string: n }` fields validate UTF-8 byte length, matching the inline
+ * capacity the connector enforces; zod `z.string().meta({ bytes: n })`
+ * members get the same bound attached to the declared schema.
+ */
+export declare function listSchema<F extends ListFields>(fields: F): z.ZodObject<ListZodShape<F>>;
+/**
+ * Compiles one fixed-layout member — a spec token or a zod schema — to its
+ * binary layout form. Throws for members that can't express a fixed-width
+ * layout.
+ */
+export declare function memberToSpec(member: ListMember, name: string): ListFieldSpec;
+/** The declared member map of a zod object, or null when `schema` isn't one. */
+export declare function zodObjectShape(schema: unknown): ListFields | null;
+/**
+ * Element schema + capacity of a bounded zod array — `.max(n)` /
+ * `.length(n)` carry the bound in their checks. Returns null for non-array
+ * schemas; `capacity` is null for unbounded arrays.
+ */
+export declare function zodArrayInfo(schema: unknown): {
+    element: z.ZodTypeAny;
+    capacity: number | null;
+} | null;
+/** The byte budget carried by `mz.string(n)` / `z.string().meta({ bytes: n })` — null otherwise. */
+export declare function zodStringBytes(schema: unknown): number | null;

package/dist/contract/msgpackCodec.d.ts

@@ -0,0 +1,7 @@
+import type { Codec } from './sharedMemory';
+/**
+ * MessagePack transport codec: smaller payloads than JSON and supports types
+ * JSON can't express (Uint8Array, BigInt, etc.). Decoded values are still
+ * validated by each field's zod schema.
+ */
+export declare const msgpackCodec: Codec;

package/dist/contract/msgpackrCodec.d.ts

@@ -0,0 +1,2 @@
+import type { Codec } from './sharedMemory';
+export declare const msgpackrCodec: Codec;

package/dist/contract/mz.d.ts

@@ -0,0 +1,43 @@
+import { z } from './zod';
+/**
+ * Atoll zod — the fixed-width schema vocabulary. Every helper produces a
+ * plain zod schema the layout compiler can read a byte width from: number
+ * formats (`mz.u32()`), int bounds (`mz.int(0, 3)` → u8), byte budgets
+ * (`mz.string(10)`), or flags (`mz.boolean()` → u8). There are no unfixed
+ * members — `mz.number()`/`z.date()`/`z.enum()` aren't exposed because they
+ * can't promise a width.
+ *
+ * Width coverage: zod 4 provides int32/uint32/float32/float64/int64/uint64
+ * formats; mz fills the gaps (i8/u8/i16/u16 via bounded ints, which the
+ * compiler narrows identically) so all ten scalar kinds have one spelling.
+ *
+ * Composition derives byte width upward — `mz.object({...})` members lay out
+ * as a fixed record (field.object derives byteLength from it, no maxBytes),
+ * `mz.array(el).max(n)` bounds element capacity for field.array, and
+ * `mz.string(n)` carries the budget for field.string. The returned values are
+ * ordinary zod schemas — `.meta()`, `.refine()`, `.max()` all still work.
+ */
+export declare const mz: {
+    i8: () => import("zod").ZodNumber;
+    u8: () => import("zod").ZodNumber;
+    i16: () => import("zod").ZodNumber;
+    u16: () => import("zod").ZodNumber;
+    i32: () => import("zod").ZodInt32;
+    u32: () => import("zod").ZodUInt32;
+    f32: () => import("zod").ZodFloat32;
+    f64: () => import("zod").ZodFloat64;
+    i64: () => import("zod").ZodInt64;
+    u64: () => import("zod").ZodUInt64;
+    /** Bounded int — compiles to the narrowest covering kind (0..3 → u8). */
+    int: (min: number, max: number) => import("zod").ZodNumber;
+    /** A flag byte — reads and writes as boolean. */
+    boolean: () => import("zod").ZodBoolean;
+    /** Fixed-capacity inline UTF-8 string — `bytes` is the byte budget. The
+     *  schema itself refuses over-budget values, so `.parse` and connector
+     *  writes enforce the same limit. */
+    string: (bytes: number) => import("zod").ZodString;
+    /** A fixed-layout record shape — every member must be a fixed-width schema. */
+    object: <S extends z.ZodRawShape>(shape: S) => import("zod").ZodObject<{ -readonly [P in keyof S]: S[P]; }, import("zod/v4/core").$strip>;
+    /** A fixed-stride element — bound it with `.max(n)` or `.length(n)` before field.array. */
+    array: <E extends z.ZodTypeAny>(element: E) => import("zod").ZodArray<E>;
+};