experimental-a2 0.8.0 → 0.9.0

package/AGENTS.md

@@ -0,0 +1,11 @@
+# Using A2 from this package
+
+When answering questions or editing applications that use A2:
+
+1. Read `docs/` for the supported API and guarantees.
+2. Read `examples/playground/` for complete application structure.
+3. Read `src/` only when implementation details are relevant.
+
+Do not infer application patterns from `dist/`. The playground uses public
+package entry points and shows where contracts, reducers, servers, route
+handlers, clients, authorization, WebSocket capabilities, and schedulers live.

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.9.0
+
+### Minor Changes
+
+- a29bad2: New experimental actor module: durable-objects-shaped actors built on
+  sessions. Three entry points: `experimental-a2/actor` (server),
+  `experimental-a2/actor/client` (framework-agnostic typed calls), and
+  `experimental-a2/actor/react` (the `useActor` hook).
+
+  Define an actor over a protocol of types (`state`, `events`, optional
+  `presence`): handlers are serial per instance (one message at a time,
+  one atomic commit at return), `concurrent(...)` opts a handler off the
+  lane for slow work, `ctx.send` buffers typed self-sends into the
+  commit, and `ctx.schedule` arms protocol-typed durable timers. Handles
+  expose `call` (send and await the answer), `send`, `state`, and a
+  managed `fetch` door: GET streams state commits over SSE, POST serves
+  calls and presence envelopes, with per-operation `authorize` and
+  per-mount `view` projections. Presence is protocol-typed audience
+  state: `participant`, `presence`, and `setPresence` on `useActor`.
+
+  Core additions: `NonRetriableError` (a deterministic failure that
+  dead-letters on its first throw instead of burning the retry budget)
+  and a `'*'` catch-all entry in presence vocabularies (unknown fields
+  validate against it; object-plumbing names never do).
+
+  Docs: a new Actors section (introduction, concurrency, deadlines and
+  timers, routes and clients).
+
+## 0.8.1
+
+### Patch Changes
+
+- 3bff761: Include a standalone snapshot of the complete Next.js playground in the npm
+  package, with package and documentation indexes that direct coding agents to
+  the supported docs and example structure.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,29 @@
+# experimental-a2
+
+Durable sync and reactions for things with a lifecycle. Each session has an
+event log, derived state, handlers, timers, and a live client.
+
+## Read the package
+
+The npm package includes more than compiled output:
+
+- `docs/` defines the supported API.
+- `examples/playground/` contains complete, standalone Next.js examples.
+- `src/` contains the TypeScript implementation.
+
+Coding agents should read `docs/` and `examples/playground/` before inferring
+usage from `dist/` or internal implementation details. Every playground feature
+owns its contract, reducer, server, route handlers, and scheduler when needed.
+The package and copied playground both include `AGENTS.md` discovery files.
+
+## Copy the playground
+
+```sh
+cp -R node_modules/experimental-a2/examples/playground ./a2-playground
+cd a2-playground
+pnpm install
+pnpm dev
+```
+
+The copied application has a standalone `package.json`. Its A2 dependency is
+pinned to the package version that shipped the snapshot.

package/dist/actor-client.d.ts

@@ -0,0 +1,46 @@
+import { c as ActorRefusedError } from "./actor-shared-BACubf4x.js";
+//#region src/actor-client.d.ts
+/** The loose shape of an `actor()` definition — carried type-only. */
+type AnyActorDefinition = {
+  actor(id: string): {
+    state(): Promise<{
+      state: unknown;
+      index: number;
+    }>;
+    call: object;
+  };
+};
+type HandleOf<D extends AnyActorDefinition> = ReturnType<D["actor"]>;
+type ActorStateOf<D extends AnyActorDefinition> = Awaited<ReturnType<HandleOf<D>["state"]>>["state"];
+/**
+ * The server handle's `call` record mirrored to the client, with
+ * answers carrying `View` — the projected shape when the route mounts
+ * `fetch(req, { view })`, the full state otherwise (the default).
+ */
+type ActorClientCall<D extends AnyActorDefinition, View = ActorStateOf<D>> = { readonly [K in keyof HandleOf<D>["call"]]: HandleOf<D>["call"][K] extends ((...args: infer P) => Promise<{
+  state: unknown;
+  index: number;
+}>) ? (...args: P) => Promise<{
+  state: View;
+  index: number;
+}> : never; };
+type ActorClient<D extends AnyActorDefinition, View = ActorStateOf<D>> = {
+  /** Typed calls over POST — the response is the answer. */
+  readonly call: ActorClientCall<D, View>;
+};
+type CreateActorClientOptions = {
+  /** The route whose handler delegates to `handle.fetch` for this instance. */
+  api: string;
+  /** Injectable transport (tests, custom auth headers). */
+  fetch?: typeof globalThis.fetch;
+};
+/**
+ * A typed call surface for one actor instance's route. When the route
+ * mounts a `view`, pass its shape as the second type argument so call
+ * answers carry the projected state:
+ * `createActorClient<typeof vault, PublicVault>({ api })`.
+ */
+declare function createActorClient<D extends AnyActorDefinition, View = ActorStateOf<D>>(options: CreateActorClientOptions): ActorClient<D, View>;
+//#endregion
+export { ActorClient, ActorClientCall, ActorRefusedError, ActorStateOf, AnyActorDefinition, CreateActorClientOptions, createActorClient };
+//# sourceMappingURL=actor-client.d.ts.map

package/dist/actor-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-client.d.ts","names":[],"sources":["../src/actor-client.ts"],"mappings":";;;KAyBY;EACV,MAAM;IACJ,SAAS;MAAU;MAAgB;;IACnC;;;KAIC,SAAS,UAAU,sBAAsB,WAAW;KAE7C,aAAa,UAAU,sBAAsB,QACvD,WAAW,SAAS;;;;;;KAQV,gBACV,UAAU,oBACV,OAAO,aAAa,kBAEV,WAAW,SAAS,aAAa,SAAS,WAAW,gBAC1D,YAAY,MACZ;EAAU;EAAgB;UACvB,MAAM,MAAM;EAAU,OAAO;EAAM;;KAIjC,YACV,UAAU,oBACV,OAAO,aAAa;;WAGX,MAAM,gBAAgB,GAAG;;KAGxB;;EAEV;;EAEA,eAAe,WAAW;;;;;;;;iBAiDZ,kBACd,UAAU,oBACV,OAAO,aAAa,IACpB,SAAS,2BAA2B,YAAY,GAAG"}

package/dist/actor-client.js

@@ -0,0 +1,54 @@
+import { i as ActorRefusedError } from "./actor-shared-DI7J5upy.js";
+//#region src/actor-client.ts
+/**
+* experimental-a2/actor/client — typed calls to an actor over HTTP.
+* Framework-agnostic: no React, no framework machinery; works in any
+* browser code and server-to-server.
+*
+* `client.call` mirrors the server handle's `call` record over the
+* call lane `handle.fetch` serves — POST `{ event, input, messageId? }`
+* → the answer (post-state), a 409 refusal (revived as
+* `ActorRefusedError`), or a 400. Both ends of that wire are library
+* code: the types here are backed by `handle.fetch`, not by a
+* hand-written convention.
+*
+* ```ts
+* import type { vault } from '@/app/vault/server' // type-only, erased
+* const client = createActorClient<typeof vault>({ api: `/vault/${id}` })
+* await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal
+* ```
+*/
+const CALL_TIMEOUT_MS = 3e4;
+const callOverWire = async (fetchImpl, api, event, input, options) => {
+	const response = await fetchImpl(api, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			event,
+			...input === void 0 ? {} : { input },
+			...options?.id === void 0 ? {} : { messageId: options.id }
+		}),
+		signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS)
+	});
+	const body = await response.json().catch(() => ({}));
+	if (response.status === 409 && typeof body["error"] === "string") throw new ActorRefusedError(typeof body["event"] === "string" ? body["event"] : event, typeof body["messageId"] === "string" ? body["messageId"] : "", body["error"]);
+	if (!response.ok) {
+		const message = typeof body["error"] === "string" ? body["error"] : `actor call failed (${response.status})`;
+		throw new Error(message);
+	}
+	return body;
+};
+/**
+* A typed call surface for one actor instance's route. When the route
+* mounts a `view`, pass its shape as the second type argument so call
+* answers carry the projected state:
+* `createActorClient<typeof vault, PublicVault>({ api })`.
+*/
+function createActorClient(options) {
+	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+	return { call: new Proxy({}, { get: (_target, event) => typeof event === "string" ? (input, callOptions) => callOverWire(fetchImpl, options.api, event, input, callOptions) : void 0 }) };
+}
+//#endregion
+export { ActorRefusedError, createActorClient };
+
+//# sourceMappingURL=actor-client.js.map

package/dist/actor-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-client.js","names":[],"sources":["../src/actor-client.ts"],"sourcesContent":["/**\n * experimental-a2/actor/client — typed calls to an actor over HTTP.\n * Framework-agnostic: no React, no framework machinery; works in any\n * browser code and server-to-server.\n *\n * `client.call` mirrors the server handle's `call` record over the\n * call lane `handle.fetch` serves — POST `{ event, input, messageId? }`\n * → the answer (post-state), a 409 refusal (revived as\n * `ActorRefusedError`), or a 400. Both ends of that wire are library\n * code: the types here are backed by `handle.fetch`, not by a\n * hand-written convention.\n *\n * ```ts\n * import type { vault } from '@/app/vault/server' // type-only, erased\n * const client = createActorClient<typeof vault>({ api: `/vault/${id}` })\n * await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal\n * ```\n */\n\nimport { ActorRefusedError } from './actor-shared.ts'\nimport type { ActorCallOptions, ActorCallResult } from './actor.ts'\n\nexport { ActorRefusedError }\n\n/** The loose shape of an `actor()` definition — carried type-only. */\nexport type AnyActorDefinition = {\n  actor(id: string): {\n    state(): Promise<{ state: unknown; index: number }>\n    call: object\n  }\n}\n\ntype HandleOf<D extends AnyActorDefinition> = ReturnType<D['actor']>\n\nexport type ActorStateOf<D extends AnyActorDefinition> = Awaited<\n  ReturnType<HandleOf<D>['state']>\n>['state']\n\n/**\n * The server handle's `call` record mirrored to the client, with\n * answers carrying `View` — the projected shape when the route mounts\n * `fetch(req, { view })`, the full state otherwise (the default).\n */\nexport type ActorClientCall<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  readonly [K in keyof HandleOf<D>['call']]: HandleOf<D>['call'][K] extends (\n    ...args: infer P\n  ) => Promise<{ state: unknown; index: number }>\n    ? (...args: P) => Promise<{ state: View; index: number }>\n    : never\n}\n\nexport type ActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  /** Typed calls over POST — the response is the answer. */\n  readonly call: ActorClientCall<D, View>\n}\n\nexport type CreateActorClientOptions = {\n  /** The route whose handler delegates to `handle.fetch` for this instance. */\n  api: string\n  /** Injectable transport (tests, custom auth headers). */\n  fetch?: typeof globalThis.fetch\n}\n\nconst CALL_TIMEOUT_MS = 30_000\n\nconst callOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  event: string,\n  input: unknown,\n  options?: ActorCallOptions,\n): Promise<ActorCallResult<unknown>> => {\n  const response = await fetchImpl(api, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({\n      event,\n      ...(input === undefined ? {} : { input }),\n      ...(options?.id === undefined ? {} : { messageId: options.id }),\n    }),\n    signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),\n  })\n  const body = (await response.json().catch(() => ({}))) as Record<\n    string,\n    unknown\n  >\n  if (response.status === 409 && typeof body['error'] === 'string') {\n    throw new ActorRefusedError(\n      typeof body['event'] === 'string' ? body['event'] : event,\n      typeof body['messageId'] === 'string' ? body['messageId'] : '',\n      body['error'],\n    )\n  }\n  if (!response.ok) {\n    const message =\n      typeof body['error'] === 'string'\n        ? body['error']\n        : `actor call failed (${response.status})`\n    throw new Error(message)\n  }\n  return body as ActorCallResult<unknown>\n}\n\n/**\n * A typed call surface for one actor instance's route. When the route\n * mounts a `view`, pass its shape as the second type argument so call\n * answers carry the projected state:\n * `createActorClient<typeof vault, PublicVault>({ api })`.\n */\nexport function createActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n>(options: CreateActorClientOptions): ActorClient<D, View> {\n  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)\n  const call = new Proxy(\n    {},\n    {\n      get: (_target, event) =>\n        typeof event === 'string'\n          ? (input?: unknown, callOptions?: ActorCallOptions) =>\n              callOverWire(fetchImpl, options.api, event, input, callOptions)\n          : undefined,\n    },\n  ) as ActorClientCall<D, View>\n  return { call }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqEA,MAAM,kBAAkB;AAExB,MAAM,eAAe,OACnB,WACA,KACA,OACA,OACA,YACsC;CACtC,MAAM,WAAW,MAAM,UAAU,KAAK;EACpC,QAAQ;EACR,SAAS,EAAE,gBAAgB,mBAAmB;EAC9C,MAAM,KAAK,UAAU;GACnB;GACA,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;GACvC,GAAI,SAAS,OAAO,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,QAAQ,GAAG;EAC/D,CAAC;EACD,QAAQ,YAAY,QAAQ,SAAS,aAAa,eAAe;CACnE,CAAC;CACD,MAAM,OAAQ,MAAM,SAAS,KAAK,CAAC,CAAC,aAAa,CAAC,EAAE;CAIpD,IAAI,SAAS,WAAW,OAAO,OAAO,KAAK,aAAa,UACtD,MAAM,IAAI,kBACR,OAAO,KAAK,aAAa,WAAW,KAAK,WAAW,OACpD,OAAO,KAAK,iBAAiB,WAAW,KAAK,eAAe,IAC5D,KAAK,QACP;CAEF,IAAI,CAAC,SAAS,IAAI;EAChB,MAAM,UACJ,OAAO,KAAK,aAAa,WACrB,KAAK,WACL,sBAAsB,SAAS,OAAO;EAC5C,MAAM,IAAI,MAAM,OAAO;CACzB;CACA,OAAO;AACT;;;;;;;AAQA,SAAgB,kBAGd,SAAyD;CACzD,MAAM,YAAY,QAAQ,SAAS,WAAW,MAAM,KAAK,UAAU;CAWnE,OAAO,EAAE,MAAA,IAVQ,MACf,CAAC,GACD,EACE,MAAM,SAAS,UACb,OAAO,UAAU,YACZ,OAAiB,gBAChB,aAAa,WAAW,QAAQ,KAAK,OAAO,OAAO,WAAW,IAChE,KAAA,EACR,CAEU,EAAE;AAChB"}

package/dist/actor-react.d.ts

@@ -0,0 +1,54 @@
+import { a as ContractEvent, s as EventDefs } from "./reducer-DJKWm3cp.js";
+import { i as ActorPresenceMap, o as ActorPresenceValues } from "./actor-shared-BACubf4x.js";
+import { ActorClientCall, ActorStateOf, AnyActorDefinition } from "./actor-client.js";
+import { Connection } from "./client.js";
+//#region src/actor-react.d.ts
+/** The server-to-client handoff: `await def.actor(id).state()`. */
+type ActorSnapshot<S> = {
+  state: S;
+  index: number;
+};
+type UseActorOptions<View> = {
+  /** The route whose handler delegates to `handle.fetch` for this instance. */
+  api: string;
+  /** The instance id. */
+  id: string;
+  /** The server-rendered fold — the stream resumes after `index`. */
+  initial: ActorSnapshot<View>;
+  /** This client's presence identity — required to call `setPresence`. */
+  participant?: string;
+};
+/** The definition's presence vocabulary, `never` when undeclared. */
+type PresenceOf<D extends AnyActorDefinition> = D extends {
+  protocol?: infer P;
+} ? NonNullable<P> extends {
+  presence: infer Values extends object;
+} ? Values : never : never;
+type UseActorResult<D extends AnyActorDefinition, View> = {
+  /** The actor's state, live: every commit streams in and replaces it. */
+  state: View;
+  /** The stream frontier. */
+  index: number;
+  connection: Connection;
+  /** Typed calls over POST — the response is the answer. */
+  call: ActorClientCall<D, View>;
+  /** The state-commit feed this browser has observed. */
+  events: ContractEvent<EventDefs>[];
+  /**
+   * The replicated presence map: participant → field → latest value.
+   * Peer-authored — render values like user input. Empty (and
+   * `setPresence` untyped-callable-with-nothing) when the protocol
+   * declares no presence.
+   */
+  presence: ActorPresenceMap<PresenceOf<D>>;
+  /**
+   * Announce this client's presence fields (throttled, resent on
+   * reconnect; `null` clears a field). Requires `participant`.
+   */
+  setPresence: (values: ActorPresenceValues<PresenceOf<D>>) => void;
+};
+/** Use one actor instance: live state plus typed calls. No provider. */
+declare function useActor<D extends AnyActorDefinition, View = ActorStateOf<D>>(options: UseActorOptions<View>): UseActorResult<D, View>;
+//#endregion
+export { ActorSnapshot, UseActorOptions, UseActorResult, useActor };
+//# sourceMappingURL=actor-react.d.ts.map

package/dist/actor-react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-react.d.ts","names":[],"sources":["../src/actor-react.ts"],"mappings":";;;;;;KA6CY,cAAc;EAAO,OAAO;EAAG;;KAE/B,gBAAgB;;EAE1B;;EAEA;;EAEA,SAAS,cAAc;;EAEvB;;;KAIG,WAAW,UAAU,sBAAsB;EAC9C,iBAAiB;IAEf,YAAY;EAAa,gBAAgB;IACvC;KAIM,eAAe,UAAU,oBAAoB;;EAEvD,OAAO;;EAEP;EACA,YAAY;;EAEZ,MAAM,gBAAgB,GAAG;;EAEzB,QAAQ,cAAc;;;;;;;EAOtB,UAAU,iBAAiB,WAAW;;;;;EAKtC,cAAc,QAAQ,oBAAoB,WAAW;;;iBA2BvC,SAAS,UAAU,oBAAoB,OAAO,aAAa,IACzE,SAAS,gBAAgB,QACxB,eAAe,GAAG"}

package/dist/actor-react.js

@@ -0,0 +1,79 @@
+"use client";
+import { createClient } from "./client.js";
+import { useSession } from "./react.js";
+import { l as openPresenceDefs } from "./actor-shared-DI7J5upy.js";
+import { createActorClient } from "./actor-client.js";
+//#region src/actor-react.ts
+/**
+* experimental-a2/actor/react — use an actor from React: live state
+* plus typed calls, one hook. A thin wrapper: the state pump follows
+* the SSE that `handle.fetch` serves (frontier resume, reconnection,
+* heartbeat watchdog — both ends library code), and `call` is
+* `createActorClient`'s typed surface (the framework-agnostic
+* primitive for everything that isn't React).
+*
+* ```tsx
+* // server component
+* const initial = await vault.actor(id).state()
+* // client component — typed by the server module, erased at build
+* const { state, call, connection } = useActor<typeof vault>({
+*   api: `/vault/${id}`, // your route: auth, then handle.fetch
+*   id,
+*   initial,
+* })
+* await call.withdraw({ amount: 60 }) // ActorRefusedError on refusal
+* ```
+*
+* The fold is library code (last write wins over state commits), so no
+* reducers, schemas, or contracts appear in browser code. Live, not
+* optimistic: handlers are server code deciding against serialized
+* fresh state, so a local guess would be wrong exactly when the actor
+* matters. On a view-projected mount, pass the projected shape as the
+* second type argument — `useActor<typeof vault, PublicVault>` — and
+* `initial`, `state`, and call answers all carry it.
+*/
+/**
+* The follower fold, untyped on purpose: the state type comes from the
+* caller's `initial` handoff, and the fold never inspects state.
+* `initialState` is never rendered — `initial` is required, so every
+* session hydrates before it connects.
+*/
+const followerReducer = {
+	name: "a2.actor.follower.v1",
+	events: {},
+	presence: openPresenceDefs,
+	fold: (state, event) => event.type === "a2.actor.state" ? event.payload.state : state,
+	initialState: void 0,
+	stateSchema: void 0
+};
+const clients = /* @__PURE__ */ new Map();
+/** Use one actor instance: live state plus typed calls. No provider. */
+function useActor(options) {
+	const { api } = options;
+	let client = clients.get(api);
+	if (!client) {
+		client = createClient({
+			reducer: followerReducer,
+			api
+		});
+		clients.set(api, client);
+	}
+	const session = useSession(client, options.id, {
+		hydrate: options.initial,
+		...options.participant === void 0 ? {} : { participant: options.participant }
+	});
+	const { call } = createActorClient({ api });
+	return {
+		state: session.state,
+		index: session.index,
+		connection: session.connection,
+		call,
+		events: session.events,
+		presence: session.presence,
+		setPresence: session.setPresence
+	};
+}
+//#endregion
+export { useActor };
+
+//# sourceMappingURL=actor-react.js.map

package/dist/actor-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-react.js","names":[],"sources":["../src/actor-react.ts"],"sourcesContent":["'use client'\n/**\n * experimental-a2/actor/react — use an actor from React: live state\n * plus typed calls, one hook. A thin wrapper: the state pump follows\n * the SSE that `handle.fetch` serves (frontier resume, reconnection,\n * heartbeat watchdog — both ends library code), and `call` is\n * `createActorClient`'s typed surface (the framework-agnostic\n * primitive for everything that isn't React).\n *\n * ```tsx\n * // server component\n * const initial = await vault.actor(id).state()\n * // client component — typed by the server module, erased at build\n * const { state, call, connection } = useActor<typeof vault>({\n *   api: `/vault/${id}`, // your route: auth, then handle.fetch\n *   id,\n *   initial,\n * })\n * await call.withdraw({ amount: 60 }) // ActorRefusedError on refusal\n * ```\n *\n * The fold is library code (last write wins over state commits), so no\n * reducers, schemas, or contracts appear in browser code. Live, not\n * optimistic: handlers are server code deciding against serialized\n * fresh state, so a local guess would be wrong exactly when the actor\n * matters. On a view-projected mount, pass the projected shape as the\n * second type argument — `useActor<typeof vault, PublicVault>` — and\n * `initial`, `state`, and call answers all carry it.\n */\n\nimport { ACTOR_STATE_EVENT, openPresenceDefs } from './actor-shared.ts'\nimport type { ActorPresenceMap, ActorPresenceValues } from './actor-shared.ts'\nimport {\n  createActorClient,\n  type ActorClientCall,\n  type ActorStateOf,\n  type AnyActorDefinition,\n} from './actor-client.ts'\nimport { createClient } from './client.ts'\nimport type { A2Client, Connection } from './client.ts'\nimport type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'\nimport type { Reducer } from './reducer.ts'\nimport { useSession } from './react.ts'\n\n/** The server-to-client handoff: `await def.actor(id).state()`. */\nexport type ActorSnapshot<S> = { state: S; index: number }\n\nexport type UseActorOptions<View> = {\n  /** The route whose handler delegates to `handle.fetch` for this instance. */\n  api: string\n  /** The instance id. */\n  id: string\n  /** The server-rendered fold — the stream resumes after `index`. */\n  initial: ActorSnapshot<View>\n  /** This client's presence identity — required to call `setPresence`. */\n  participant?: string\n}\n\n/** The definition's presence vocabulary, `never` when undeclared. */\ntype PresenceOf<D extends AnyActorDefinition> = D extends {\n  protocol?: infer P\n}\n  ? NonNullable<P> extends { presence: infer Values extends object }\n    ? Values\n    : never\n  : never\n\nexport type UseActorResult<D extends AnyActorDefinition, View> = {\n  /** The actor's state, live: every commit streams in and replaces it. */\n  state: View\n  /** The stream frontier. */\n  index: number\n  connection: Connection\n  /** Typed calls over POST — the response is the answer. */\n  call: ActorClientCall<D, View>\n  /** The state-commit feed this browser has observed. */\n  events: ContractEvent<EventDefs>[]\n  /**\n   * The replicated presence map: participant → field → latest value.\n   * Peer-authored — render values like user input. Empty (and\n   * `setPresence` untyped-callable-with-nothing) when the protocol\n   * declares no presence.\n   */\n  presence: ActorPresenceMap<PresenceOf<D>>\n  /**\n   * Announce this client's presence fields (throttled, resent on\n   * reconnect; `null` clears a field). Requires `participant`.\n   */\n  setPresence: (values: ActorPresenceValues<PresenceOf<D>>) => void\n}\n\n/**\n * The follower fold, untyped on purpose: the state type comes from the\n * caller's `initial` handoff, and the fold never inspects state.\n * `initialState` is never rendered — `initial` is required, so every\n * session hydrates before it connects.\n */\nconst followerReducer: Reducer<EventDefs, unknown, PresenceDefs> = {\n  name: 'a2.actor.follower.v1',\n  events: {},\n  // The open vocabulary ('*' catch-all): the browser cannot know a\n  // server-defined field list, so the server stays the authority and\n  // the protocol types honest callers at compile time.\n  presence: openPresenceDefs,\n  fold: (state, event) =>\n    event.type === ACTOR_STATE_EVENT\n      ? (event.payload as { state: unknown }).state\n      : state,\n  initialState: undefined,\n  stateSchema: undefined,\n}\n\nconst clients = new Map<string, A2Client<EventDefs, unknown, PresenceDefs>>()\n\n/** Use one actor instance: live state plus typed calls. No provider. */\nexport function useActor<D extends AnyActorDefinition, View = ActorStateOf<D>>(\n  options: UseActorOptions<View>,\n): UseActorResult<D, View> {\n  const { api } = options\n  let client = clients.get(api)\n  if (!client) {\n    client = createClient({ reducer: followerReducer, api })\n    clients.set(api, client)\n  }\n  const session = useSession(client, options.id, {\n    hydrate: options.initial,\n    ...(options.participant === undefined\n      ? {}\n      : { participant: options.participant }),\n  })\n  const { call } = createActorClient<D, View>({ api })\n  return {\n    state: session.state as View,\n    index: session.index,\n    connection: session.connection,\n    call,\n    events: session.events,\n    presence: session.presence as ActorPresenceMap<PresenceOf<D>>,\n    setPresence: session.setPresence as (\n      values: ActorPresenceValues<PresenceOf<D>>,\n    ) => void,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiGA,MAAM,kBAA6D;CACjE,MAAM;CACN,QAAQ,CAAC;CAIT,UAAU;CACV,OAAO,OAAO,UACZ,MAAM,SAAA,mBACD,MAAM,QAA+B,QACtC;CACN,cAAc,KAAA;CACd,aAAa,KAAA;AACf;AAEA,MAAM,0BAAU,IAAI,IAAwD;;AAG5E,SAAgB,SACd,SACyB;CACzB,MAAM,EAAE,QAAQ;CAChB,IAAI,SAAS,QAAQ,IAAI,GAAG;CAC5B,IAAI,CAAC,QAAQ;EACX,SAAS,aAAa;GAAE,SAAS;GAAiB;EAAI,CAAC;EACvD,QAAQ,IAAI,KAAK,MAAM;CACzB;CACA,MAAM,UAAU,WAAW,QAAQ,QAAQ,IAAI;EAC7C,SAAS,QAAQ;EACjB,GAAI,QAAQ,gBAAgB,KAAA,IACxB,CAAC,IACD,EAAE,aAAa,QAAQ,YAAY;CACzC,CAAC;CACD,MAAM,EAAE,SAAS,kBAA2B,EAAE,IAAI,CAAC;CACnD,OAAO;EACL,OAAO,QAAQ;EACf,OAAO,QAAQ;EACf,YAAY,QAAQ;EACpB;EACA,QAAQ,QAAQ;EAChB,UAAU,QAAQ;EAClB,aAAa,QAAQ;CAGvB;AACF"}

package/dist/actor-shared-BACubf4x.d.ts

@@ -0,0 +1,136 @@
+import { h as StandardSchemaV1 } from "./reducer-DJKWm3cp.js";
+import { f as ScheduleTiming } from "./server-CKY3_lbw.js";
+//#region src/actor-shared.d.ts
+/**
+ * A handler answered by throwing `NonRetriableError`: the event
+ * settled, the state did not change. Isomorphic — the server raises it
+ * from calls and `fetch()` serializes it as a 409; the client's `call`
+ * proxy revives it from that response.
+ */
+declare class ActorRefusedError extends Error {
+  /** The refused event's name. */
+  readonly event: string;
+  /** The refused event's message id. */
+  readonly messageId: string;
+  constructor(event: string, messageId: string, message: string);
+}
+/**
+ * The declaration an actor is defined over: its state shape and its
+ * event vocabulary, as types. Core A2 contracts are schemas because
+ * the wire is untrusted; actor protocols are types because your
+ * server is trusted — same contract-first design language, dialed to
+ * the trust level.
+ */
+type ActorProtocol = {
+  state: object;
+  events: object;
+  /**
+   * Optional third vocabulary: presence field → value type. Ephemeral
+   * audience state (who is here, cursors), replicated to subscribers
+   * and never stored in the log. Declaring it requires `presence:
+   * true` in the actor options — the wire bit types cannot carry.
+   */
+  presence?: object;
+};
+/** The protocol's presence vocabulary, `never` when undeclared. */
+type ActorPresenceOf<D extends ActorProtocol> = D extends {
+  presence: infer P extends object;
+} ? P : never;
+/** A `setPresence` patch: changed fields, `null` clears one. */
+type ActorPresenceValues<P> = { [F in keyof P & string]?: P[F] | null; };
+/**
+ * The replicated presence map: participant → field → latest value,
+ * last write wins per field. Values are peer-authored — render them
+ * like user input.
+ */
+type ActorPresenceMap<P> = {
+  [participant: string]: { [F in keyof P & string]?: {
+    value: P[F];
+    seen: number;
+    at: Date;
+  }; };
+};
+/**
+ * The typed self-send surface: one method per declared event —
+ * `ctx.send.transfer({ ref, amount })`. Buffered, not immediate: every
+ * send requested during a handler commits atomically with that
+ * handler's completion (a serial handler's state commit, a concurrent
+ * handler's settlement), riding core's returned-events semantics — so
+ * a reserve-and-trigger can never half-happen, and re-runs converge on
+ * the same deterministic message ids.
+ */
+type ActorSend<E> = { readonly [K in keyof E]: {} extends E[K] ? (input?: E[K]) => void : (input: E[K]) => void; };
+/**
+ * Timing for a scheduled event: exactly `{ delay: '5d' }` or
+ * `{ at: Date }` (core §6 semantics — relative delays anchor to the
+ * triggering message's durable `createdAt`, so re-runs resolve the
+ * same due time). `name` overrides the timer's identity — it defaults
+ * to the target event name, scoped to the triggering message, so one
+ * handler run gets one timer per target event unless named apart.
+ */
+type ActorScheduleOptions = ScheduleTiming & {
+  name?: string;
+};
+/**
+ * The typed durable-timer surface: one method per declared event —
+ * `ctx.schedule.refund({ ref: ctx.id }, { delay: '1h' })`. Unlike
+ * `send`, scheduling is immediate, not buffered: it awaits provider
+ * acceptance at call time (a timer is provider-side, not a log row),
+ * so a handler that schedules and then refuses has still armed the
+ * timer. That is safe by the guarded-delivery idiom — the stale timer
+ * fires into an idempotent no-op — but it is the one exception to
+ * "refusals are total". Requires a configured `scheduler`.
+ */
+type ActorScheduleSend<E> = { readonly [K in keyof E]: {} extends E[K] ? (input: E[K] | undefined, options: ActorScheduleOptions) => Promise<void> : (input: E[K], options: ActorScheduleOptions) => Promise<void>; };
+/** What a serial handler receives alongside its typed input. */
+type ActorContext<D extends ActorProtocol> = {
+  /** Mutable draft, committed atomically with the handler's completion. */
+  state: D["state"];
+  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  id: string;
+  /** Durable 1-based dispatch ordinal of this message. */
+  attempt: number;
+  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */
+  signal: AbortSignal;
+  /** Typed buffered self-send — committed atomically with the state commit. */
+  send: ActorSend<D["events"]>;
+  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */
+  schedule: ActorScheduleSend<D["events"]>;
+};
+/**
+ * What a `concurrent: true` handler receives. No draft — concurrent
+ * handlers run off the lane, in parallel, so state is a snapshot read
+ * (honest about staleness) and mutations happen by sending events
+ * whose serial handlers decide against fresh state.
+ */
+type ActorConcurrentContext<D extends ActorProtocol> = {
+  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  id: string;
+  /** Durable 1-based dispatch ordinal of this message. */
+  attempt: number;
+  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */
+  signal: AbortSignal;
+  /** Snapshot read — observational; the world moves while this runs. */
+  state(): Promise<{
+    state: D["state"];
+    index: number;
+  }>;
+  /** Typed buffered self-send — committed atomically with settlement. */
+  send: ActorSend<D["events"]>;
+  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */
+  schedule: ActorScheduleSend<D["events"]>;
+};
+type ActorStatePayload<S> = {
+  state: S;
+  /** The event whose handler committed this state. */
+  event: string;
+  /** The message (invocation event) id this state answers. */
+  message: string;
+};
+/** The event vocabulary a client needs to follow an actor's state. */
+type ActorClientEventDefs<S> = {
+  "a2.actor.state": StandardSchemaV1<ActorStatePayload<S>>;
+};
+//#endregion
+export { ActorPresenceOf as a, ActorRefusedError as c, ActorSend as d, ActorPresenceMap as i, ActorScheduleOptions as l, ActorConcurrentContext as n, ActorPresenceValues as o, ActorContext as r, ActorProtocol as s, ActorClientEventDefs as t, ActorScheduleSend as u };
+//# sourceMappingURL=actor-shared-BACubf4x.d.ts.map

package/dist/actor-shared-BACubf4x.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-shared-BACubf4x.d.ts","names":[],"sources":["../src/actor-shared.ts"],"mappings":";;;;;;;;;cAgCa,0BAA0B;;WAE5B;;WAEA;EACT,YAAY,eAAe,mBAAmB;;;;;;;;;KAepC;EACV;EACA;;;;;;;EAOA;;;KAIU,gBAAgB,UAAU,iBAAiB;EACrD,gBAAgB;IAEd;;KAIQ,oBAAoB,QAC7B,WAAW,cAAc,EAAE;;;;;;KAQlB,iBAAiB;GAExB,yBAAA,WAAW;IAAgB,OAAO,EAAE;IAAI;IAAc,IAAI;;;;;;;;;;;;KAanD,UAAU,iBACV,WAAW,eAAe,EAAE,MACjC,QAAQ,EAAE,eACV,OAAO,EAAE;;;;;;;;;KAWJ,uBAAuB;EAAmB;;;;;;;;;;;;KAY1C,kBAAkB,iBAClB,WAAW,eAAe,EAAE,MACjC,OAAO,EAAE,gBAAgB,SAAS,yBAAyB,iBAC3D,OAAO,EAAE,IAAI,SAAS,yBAAyB;;KAI1C,aAAa,UAAU;;EAEjC,OAAO;;EAEP;;EAEA;;EAEA,QAAQ;;EAER,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;;;;;;;KASlB,uBAAuB,UAAU;;EAE3C;;EAEA;;EAEA,QAAQ;;EAER,SAAS;IAAU,OAAO;IAAY;;;EAEtC,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;KAGlB,kBAAkB;EAC5B,OAAO;;EAEP;;EAEA;;;KAWU,qBAAqB;EAC/B,kBAAkB,iBAAiB,kBAAkB"}

package/dist/actor-shared-DI7J5upy.js

@@ -0,0 +1,127 @@
+import { t as contract } from "./contract-48bUMgcL.js";
+//#region src/actor-shared.ts
+/**
+* Internal shared vocabulary of the actor module — the reserved event
+* envelopes, the protocol and context types, the state fold. Not an
+* entry point: the public surfaces are experimental-a2/actor (server),
+* /actor/client, and /actor/react.
+*
+* An actor is a durable mailbox with memory: one session per instance,
+* events processed one at a time (a lane) unless a handler opts out
+* with `concurrent: true`, state materialized as `a2.actor.state`
+* events committed atomically with each handler's completion.
+*/
+/** Event type of a committed state change — one per completed serial handler. */
+const ACTOR_STATE_EVENT = "a2.actor.state";
+/** Event type of a refusal — a handler that answered by throwing NonRetriableError. */
+const ACTOR_FAILED_EVENT = "a2.actor.failed";
+/** The per-instance lane every serial handler shares — the state's write lock. */
+const ACTOR_LANE = "a2.actor";
+/** Reducer identity — bump when the fold's meaning changes. */
+const ACTOR_REDUCER_NAME = "a2.actor.v1";
+/**
+* A handler answered by throwing `NonRetriableError`: the event
+* settled, the state did not change. Isomorphic — the server raises it
+* from calls and `fetch()` serializes it as a 409; the client's `call`
+* proxy revives it from that response.
+*/
+var ActorRefusedError = class extends Error {
+	/** The refused event's name. */
+	event;
+	/** The refused event's message id. */
+	messageId;
+	constructor(event, messageId, message) {
+		super(message);
+		this.name = "ActorRefusedError";
+		this.event = event;
+		this.messageId = messageId;
+	}
+};
+const issue = (message) => ({ issues: [{ message }] });
+const schema = (label, parse) => ({ "~standard": {
+	version: 1,
+	vendor: "a2",
+	validate(value) {
+		try {
+			return parse(value);
+		} catch (error) {
+			return issue(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+} });
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** True for plain JSON trees — what the log can store without loss. */
+function isJsonTree(value, seen = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object") return false;
+	if (seen.has(value)) return false;
+	seen.add(value);
+	const valid = Array.isArray(value) ? value.every((item) => isJsonTree(item, seen)) : Object.getPrototypeOf(value) === Object.prototype && Object.values(value).every((item) => item === void 0 || isJsonTree(item, seen));
+	seen.delete(value);
+	return valid;
+}
+/** Per-field ceiling for presence values — presence is a cursor, not a document. */
+const PRESENCE_VALUE_MAX_BYTES = 8192;
+/**
+* The open presence vocabulary: the '*' catch-all validates any field
+* name against the JSON floor. The protocol types the vocabulary at
+* compile time; the route's `authorize` sees every set before
+* acceptance; renderers treat values as user input. Meaning has three
+* guards — this schema only owns the bytes.
+*/
+const openPresenceDefs = Object.freeze({ "*": { "~standard": {
+	version: 1,
+	vendor: "a2",
+	validate: (value) => {
+		if (!isJsonTree(value)) return { issues: [{ message: "presence values must be plain JSON trees" }] };
+		if (JSON.stringify(value).length > 8192) return { issues: [{ message: `presence values are capped at ${PRESENCE_VALUE_MAX_BYTES} bytes` }] };
+		return { value };
+	}
+} } });
+/**
+* The `a2.actor.state` envelope: provenance plus the state, held to a
+* plain JSON tree (a `Date` or `Map` in state fails loudly at commit,
+* never silently coerces in the log).
+*/
+function actorStateSchema() {
+	return schema(ACTOR_STATE_EVENT, (value) => {
+		if (!isRecord(value) || typeof value["event"] !== "string" || typeof value["message"] !== "string") return issue(`invalid ${ACTOR_STATE_EVENT} payload`);
+		const state = value["state"];
+		if (!isJsonTree(state)) return issue("the actor state must be a plain JSON tree");
+		return { value: {
+			state,
+			event: value["event"],
+			message: value["message"]
+		} };
+	});
+}
+const actorFailedSchema = schema(ACTOR_FAILED_EVENT, (value) => {
+	if (!isRecord(value) || typeof value["message"] !== "string" || typeof value["event"] !== "string" || typeof value["error"] !== "string") return issue(`invalid ${ACTOR_FAILED_EVENT} payload`);
+	return { value: {
+		message: value["message"],
+		event: value["event"],
+		error: value["error"]
+	} };
+});
+/**
+* The library fold over an actor's state commits — last write wins.
+* Pure library code: a browser bundle folds an actor's live state with
+* no user code, so the actor definition itself stays server-only
+* (import the server module's type for typing, this reducer for data).
+*/
+function actorReducer(options) {
+	if (!isJsonTree(options.state)) throw new TypeError(`actor '${options.name}': the initial state must be a plain JSON tree`);
+	const events = { [ACTOR_STATE_EVENT]: actorStateSchema() };
+	return contract({
+		name: options.name,
+		events
+	}).reducer({
+		name: ACTOR_REDUCER_NAME,
+		initialState: options.state
+	}).fold((state, event) => event.type === "a2.actor.state" ? event.payload.state : state);
+}
+//#endregion
+export { actorFailedSchema as a, isJsonTree as c, ActorRefusedError as i, openPresenceDefs as l, ACTOR_LANE as n, actorReducer as o, ACTOR_STATE_EVENT as r, actorStateSchema as s, ACTOR_FAILED_EVENT as t };
+
+//# sourceMappingURL=actor-shared-DI7J5upy.js.map