experimental-a2 0.3.0 → 0.5.0

package/docs/guides/09-presence.mdx

@@ -0,0 +1,263 @@
+---
+title: Presence
+description: "Ephemeral participant state on a durable session: cursors, typing, live progress. Presence repaints; the log replays."
+---
+
+## Two planes, one session
+
+Everything in the log is a fact: stored forever, folded by reducers,
+replayed on demand. Presence is not a fact. "Her cursor is at (312, 88)"
+has a useful lifetime of about two seconds, no replay value, and no
+durability requirement; a lost update is repainted by the next one.
+
+The test that separates the planes:
+
+> Will anyone, human or reducer, care about this datum after the moment
+> passes? Yes: event, in the log. No: presence.
+
+Messages, document updates, cancellations: events. Cursors, selections,
+typing, "who's online", a handler's live progress: presence.
+
+A2 gives presence its own plane on the session you already have. Same
+contract, same route, same auth, same stream. Each participant owns a
+small ephemeral state; A2 replicates the latest value of each field to
+everyone subscribed and stores none of it in the log. Reducers never see
+it, `history()` never returns it, and the browser cache never persists
+it. One invariant covers the whole design:
+
+> **Presence repaints; the log replays.** Anything that decides (a fold,
+> a retry, an abort match) reads the log. Presence only hurries pixels.
+
+## Declare it in the contract
+
+`presence` is a second vocabulary next to `events`: each key is a field
+of one participant's ephemeral state, each value a schema for it.
+
+```ts contracts.ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+
+export const canvas = a2.contract({
+  name: 'canvas',
+  events: {
+    'shape.created': z.object({
+      id: z.string(),
+      kind: z.enum(['rect', 'ellipse']),
+      x: z.number(),
+      y: z.number(),
+    }),
+    'shape.moved': z.object({ id: z.string(), x: z.number(), y: z.number() }),
+  },
+  presence: {
+    cursor: z.object({ x: z.number(), y: z.number() }),
+    dragging: z.object({ shapeId: z.string(), x: z.number(), y: z.number() }),
+  },
+})
+```
+
+The field is the unit of replication: last writer wins per participant
+per field. Setting `cursor` does not touch `dragging`. Fields are absent
+until a participant sets them, and clear when set to `null` or when
+their backend TTL lapses (a closed tab disappears by silence, no
+explicit leave required).
+
+## The route
+
+The same `handle` route as [Live UI](/guides/react), with one option.
+`presence: true` interleaves presence patches with events on the
+stream, starting with a snapshot of the current map; the push body
+grows an optional `presence` sibling to `events`, forwarded to
+`setPresence`.
+
+```ts app/api/canvas-events/route.ts
+import { handle } from 'experimental-a2/http'
+import { canvasServer } from '@/server/canvas'
+
+export const { GET, POST } = handle(canvasServer, {
+  presence: true,
+  before({ request, intent }) {
+    // here's where you'd do auth, or any other checks. On a push,
+    // intent.presence carries the whole patch; the participant id
+    // is caller-supplied, so authorize it like you authorize events.
+    // createServer's validatePush is the same seam and covers every
+    // transport (socket presence frames never become intents): on the
+    // presence plane it receives { sessionId, events: [], presence }.
+  },
+})
+```
+
+`setPresence` validates each field against the contract, then
+broadcasts. No append transaction, no dispatch, no scheduler arm, no log
+row. A bad field throws `INVALID_PAYLOAD`; an unknown field throws
+`UNKNOWN_PRESENCE_FIELD`; nothing is broadcast on either. A
+presence-only push acks `[]`.
+
+## The browser
+
+The provider takes a `participant` id (yours to mint: a user id, a tab
+nonce, the playground's guest name). The hook grows two members. The
+session module is the usual pair from
+[Live UI](/guides/react#the-session-module), bound to a reducer that
+carries the canvas contract:
+
+```ts app/canvas/[canvasId]/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { canvas } from '@/contracts'
+
+// a minimal scene fold; the real one lives with your reducers
+const sceneReducer = canvas
+  .reducer({ name: 'scene', initialState: {} })
+  .fold((state) => state)
+
+export const canvasClient = createClient({
+  reducer: sceneReducer,
+  api: '/api/canvas-events',
+})
+export const { SessionProvider, useSession } = createReact({
+  client: canvasClient,
+})
+```
+
+```tsx app/canvas/[canvasId]/canvas-client.tsx
+'use client'
+import { useSession } from './session'
+
+export function CanvasClient() {
+  const { presence, setPresence } = useSession()
+
+  return (
+    <div
+      onPointerMove={(e) => setPresence({ cursor: { x: e.clientX, y: e.clientY } })}
+    >
+      {Object.entries(presence).map(([participant, fields]) =>
+        // render-time expiry: a cursor silent for a few seconds is gone
+        fields.cursor && Date.now() - fields.cursor.at.getTime() < 5_000 ? (
+          <Cursor key={participant} {...fields.cursor.value} />
+        ) : null,
+      )}
+    </div>
+  )
+}
+
+// your cursor sprite:
+// function Cursor({ x, y }: { x: number; y: number }) { ... }
+const Cursor = (props: { x: number; y: number }) => null
+```
+
+- **`setPresence(values)`** is fire-and-forget: validated locally,
+  merged into the local map immediately, coalesced on the wire to a
+  fixed cadence. The first set sends immediately; within the interval,
+  later values merge field by field (latest wins, `null` included) and
+  one trailing send carries the merged batch, so a 60Hz pointer becomes
+  about fifteen sends per second and losing one is repainted by the
+  next. Sends may overlap in flight; that is safe because merges are
+  last-writer-wins by `at` per field. No ack, no `confirmed`, no retry,
+  no optimistic rollback: there is nothing to roll back, because
+  nothing was ever true.
+- **`presence`** is the replicated map,
+  `Record<participantId, { [field]: { value, seen, at } }>`, including
+  your own participant. `at` is the sender's stamp for when the value
+  was set, and the last-writer-wins comparator; the client stamps its
+  sends monotonically, so overlapping sends can never invert. How long
+  a cursor stays painted is view logic, decided at render time. Wall
+  clocks never enter folds, and presence is not folded state.
+
+Set a field to `null` to clear it (pointer leaves the canvas, blur,
+unmount). Everything else expires by TTL when a tab goes silent: 60
+seconds by default, set `createServer({ presence: { ttlMs } })` to
+change it. Expiry counts on the backend's clock, not the sender's
+stamp.
+
+Both members are typed from the contract's `presence` map, through the
+reducer, with no type arguments: field names, payloads, and `null`
+clears all autocomplete. On a contract without `presence` the members
+do not exist, so reaching for them is a compile error, not a silent
+no-op. One symptom worth knowing: if the map holds only your own
+echo while others are active, the GET route forgot `presence: true`.
+
+## Reconciling the planes: `seen`
+
+Every presence value carries `seen`, the sender's stream frontier at the
+moment it was set. The client stamps it automatically. This is what lets
+the two planes agree on an order without wall clocks.
+
+The classic race: a participant drags a shape (presence), drops it
+(event), and a stale `dragging` patch arrives after the durable
+`shape.moved`. Without a shared coordinate system the shape flickers
+backwards. With `seen`, superseding is one render-time rule:
+
+```ts
+// in render code: a ghost is dead once the log has moved past it.
+// show fields.dragging only if
+//   fields.dragging.seen >= state.shapes[fields.dragging.value.shapeId].movedAt
+// where movedAt is the index your reducer recorded for the last shape.moved
+```
+
+The durable event at index 214 beats any presence stamped 213 or lower,
+deterministically. A2 carries the stamp and exposes the frontiers; the
+comparison is yours, in view code, next to the pixels it protects.
+
+## Handlers broadcast too
+
+`ctx.session.setPresence` is the same session operation. A handler
+grinding through work can publish live progress without writing
+non-facts to the log:
+
+```ts server/canvas.ts
+import { createServer } from 'experimental-a2/server'
+import { canvas } from '@/contracts'
+
+export const canvasServer = createServer({
+  contract: canvas,
+  handlers: {
+    'shape.created': async (ctx) => {
+      // long work; broadcast progress as it goes:
+      // await ctx.session.setPresence({
+      //   participant: 'system:thumbnails',
+      //   values: { progress: { step: 2, of: 5 } },
+      // })
+    },
+  },
+})
+```
+
+The participant id is the handler's choice; a `system:` prefix keeps
+robots and humans apart in the map. Append the durable outcome as an
+event when the work completes; the progress was never a fact, the result
+is.
+
+## What presence never does
+
+- Never appears in `history()`, `state()`, or a reducer's input type.
+  The separation is structural: presence fields are not events, so a
+  fold cannot reach them even by accident.
+- Never arms the scheduler, takes a claim, or retries. A crashed presence
+  update is a non-event, literally.
+- Never enters the IndexedDB cache. Cache the log, never the moment.
+- Never blocks an append. The planes share a route, not a transaction.
+
+## Backends
+
+Presence needs a broadcast primitive, and backends differ. Declaring
+`presence` in a contract requires a store with the presence capability;
+`createServer` throws `PRESENCE_NOT_SUPPORTED` at construction
+otherwise. All built-in stores have it, at two tiers:
+
+| Backend | Delivery |
+| --- | --- |
+| `store-redis` | push: TTL'd hash plus pub/sub patch, single-digit ms to parked subscribers |
+| `store-memory` | in-process, immediate |
+| `store-postgres`, `store-sqlite`, `store-redis-http` | degraded: bounded TTL'd rows, read on the live feed's poll cadence |
+
+Degraded means later, not lost while watched: presence-only traffic
+surfaces on a fixed 250ms re-read tick plus event wakes; the 25ms
+adaptive floor engages only while events flow. The push tier never
+broadcasts TTL expiry: a participant that departs silently keeps their
+last values in connected clients' maps until those clients reconnect,
+which is why the render-time expiry above is the guard. Cursors want
+the push tier; typing indicators and progress read fine on either. The presence rows are
+bounded per session and participant, so this is not log growth in
+disguise, but on metered backends every patch is still a network
+operation. Presence makes ephemeral state correct, not free.

package/docs/guides/10-transports.mdx

@@ -0,0 +1,140 @@
+---
+title: Transports
+description: "One client, three wires: a single HTTP route, split routes for per-route timeouts, or one WebSocket for both directions."
+---
+
+## One wire seam, same client
+
+Everything the client does is transport-agnostic: optimistic pushes
+with ack and `confirmed`, frontier-resumed live reads, reconnection
+with backoff, the presence throttle and re-send. `api` picks the wire
+underneath it:
+
+```ts
+// in a 'use client' session module:
+api: '/api/order-events'
+api: { type: 'http', push: '/api/order-push', stream: '/api/order-stream' }
+api: { type: 'ws', url: '/api/order-events' }
+```
+
+- **The string** is the default and the recommendation: one route
+  serving GET (SSE stream) and POST (push), one file, one auth surface.
+  Everything else in these docs uses it.
+- **`http` split** serves the two verbs from two routes. Use it when
+  platform duration limits differ per verb: the stream is a long-lived
+  read that wants a high `maxDuration`, the push is a short write that
+  doesn't.
+- **`ws`** rides everything over one WebSocket: streams come down it,
+  pushes and presence go up it. One socket carries every session of
+  the client; a page showing ten sessions holds one connection, not
+  ten. Use it when latency or per-message cost matters; at a presence
+  cadence of fifteen sends a second, each send is a socket frame
+  instead of a route invocation.
+
+A split socket is unrepresentable on purpose. The socket is one
+connection in both directions; there is nothing left to split.
+
+One wire is missing from `ws` by design: the history lane.
+[`loadHistory`](/guides/react#the-client-component) is a bounded cold
+read and rides plain HTTP; on a `ws` api it throws a `TypeError`.
+
+## The WebSocket route
+
+The same `handle` route serves both transports. Pass `options.upgrade`
+and a GET carrying an upgrade header becomes the socket; plain GETs
+stay SSE, POST keeps working next to it. A `ws` client never calls
+POST, an `http` client never upgrades; the transports are additive.
+
+```ts app/api/order-events/route.ts
+import { experimental_upgradeWebSocket } from '@vercel/functions'
+import { handle } from 'experimental-a2/http'
+import { ordersServer } from '@/server/orders'
+
+export const { GET, POST } = handle(ordersServer, {
+  before({ request, intent }) {
+    // here's where you'd do auth, or any other checks: the upgrade
+    // itself, every subscribe, and every push arrive here as intents
+  },
+  upgrade: (attach) =>
+    experimental_upgradeWebSocket(attach, {
+      // ws defaults to 100 MiB per frame; POST bodies cap at about
+      // 4.5 MB on the platform. Keep the two ingress paths at parity.
+      maxPayload: 4 * 1024 * 1024,
+    }),
+})
+```
+
+The socket is multiplexed: `subscribe` frames open per-session lanes,
+each resuming from its own frontier; every down frame carries the
+`sessionId` it belongs to; pushes and presence route by it. One
+heartbeat, one connection, all of the client's sessions.
+
+Auth has two moments. `before` runs for the upgrade itself
+(`intent.type === 'ws-upgrade'`), while the request is still a request;
+return a Response to refuse and no socket ever opens. It then runs
+again for every subscribe and push frame: each subscribe arrives as a
+`stream` intent, each push as a `push` intent, with `request` always
+the original upgrade Request. A Response cannot cross a socket, so a
+denial answers in the wire's own vocabulary: a denied subscribe gets an
+`unsubscribed` notice (every other session on the socket streams on), a
+denied push a non-retryable error ack. Socket presence frames are
+fire-and-forget and never become intents; the presence plane's policy
+seam on every wire is `validatePush`.
+
+Two more options ride along: `presence: true` interleaves presence with
+events on every lane, the same opt-in as `stream()`, and `deadline`
+(epoch milliseconds) closes the socket cleanly ahead of a known
+platform deadline, so clients reconnect on your schedule.
+
+## The client
+
+```ts app/orders/[orderId]/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { ordersReducer } from '@/reducer'
+
+export const ordersClient = createClient({
+  reducer: ordersReducer,
+  api: { type: 'ws', url: '/api/order-events' },
+})
+export const { SessionProvider, useSession } = createReact({
+  client: ordersClient,
+})
+```
+
+Nothing else changes. `useSession` is identical, `push` returns the
+same ack and `confirmed`, presence coalesces on the same cadence. The
+connection status, the stall watchdog (two missed heartbeats), and
+reconnection with backoff all behave as they do over SSE, because they
+are the same machinery above the wire seam.
+
+## Lifecycle
+
+A socket closes when the platform ends the function invocation, or
+when the server closes it deliberately ahead of a known deadline. The
+client treats every close the same way it treats a dropped SSE stream:
+reconnect with backoff, re-subscribe every session at its own frontier,
+receive fresh presence snapshots, re-send its own presence fields set
+since the disconnect. A push whose socket died before the ack rejects as
+retryable: nothing was acknowledged, and if the append had already
+committed, the client-generated event ids make the retry an idempotent
+replay (you get the original events back). Push retries wait for the
+restored socket rather than a fixed clock, capped by the reconnect
+backoff, so a push caught in a routine blip resolves the way it would
+have over HTTP, where pushes never depended on the stream.
+
+On Vercel, WebSocket connections pin to one function instance and new
+connections may land anywhere. A2 never relies on instance affinity:
+the log is the shared state, so two clients on two instances converge
+through it, exactly as they do over HTTP.
+
+## Choosing
+
+SSE plus POST is the right default: simplest route, ordinary HTTP
+semantics, and one auth surface. Reach for `ws` when the send rate
+makes per-request overhead visible (live cursors, drag ghosts) or when
+round-trip latency is the product. Reach for the `http` split only when
+per-route duration configuration forces it. The protocol underneath is
+the same in every case: the log replays, presence repaints, and the
+wire is an implementation detail.

package/docs/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: A2 is durable sync and reactions for things with a lifecycle. Append events, run handlers, and keep one live view from server to browser.
+description: A2 is durable sync and reactions for things with a lifecycle. Append or schedule events, run handlers, and keep one live view from server to browser.
 ---
 
 ```bash
@@ -86,9 +86,11 @@ export async function POST(req: Request) {
 }
 ```
 
-That append is durable. The event hits the log before anything else happens,
-then A2 starts its handler inline. In production, queue-backed recovery wakes
-pending work after a crash or timeout.
+A2 commits the event before its handler can start. The handler may begin before
+`append` returns; the return confirms durability, not handler completion.
+A queue-backed scheduler wakes pending work after a crash or timeout. The same
+scheduler lets a session append a typed event later with
+`session.schedule(name, { delay: '30s' }, event)`.
 
 ## State is a fold
 
@@ -167,8 +169,8 @@ twenty lines; [Live UI](/guides/react) wires it end to end.
 
 - **Handlers are plain async functions.** They run concurrently by default.
   Use a lane for selective FIFO execution.
-- **Handlers are optional per event type.** A log-only event settles during
-  append and creates no reaction or recovery work.
+- **Handlers are optional per event type.** A history-only event settles during
+  append and creates no reaction or scheduler work.
 - **History is real.** [`history()`](/concepts/state) returns what
   actually happened, in order. Debugging is reading, not reconstructing.
 - **Nothing inside a session is sacred except its log.** Snapshots, claims, queue
@@ -182,7 +184,7 @@ twenty lines; [Live UI](/guides/react) wires it end to end.
 
 Yes. Omit `handlers` and use `append`, `history`, reducers, and live streams as
 a durable event log. Events settle in their append transaction, with no drain,
-claim, or queue message. A contract can also mix handled and log-only event
+claim, or queue message. A contract can also mix handled and history-only event
 types. A2 decides per event type.
 
 See [Events without handlers](/concepts/handlers#events-without-handlers).
@@ -192,9 +194,10 @@ See [Events without handlers](/concepts/handlers#events-without-handlers).
 <details>
 <summary>How do I schedule an event for later?</summary>
 
-Anything that can deliver an HTTP call later (QStash, a cron, a payment
-provider's webhook) can hit a route that appends. Schedule the session id and
-event as the request payload. See [Timers](/guides/timers).
+Configure Vercel Queues or QStash, then call
+`session.schedule(name, { delay: '30s' }, event)` or use `{ at: Date }`. The
+same scheduler route handles recovery and the delayed append. Names and omitted
+event ids stay stable across retries. See [Timers](/guides/timers).
 
 </details>
 
@@ -220,10 +223,11 @@ recovery story behind them.
 <details>
 <summary>What does production need?</summary>
 
-A durable log backend, such as Postgres or Redis. Add queue-backed recovery
-when the contract has handlers. A log-only contract needs no reaction
-infrastructure. Development needs neither: SQLite appears under `.a2/` and
-state survives restarts. See [Going to production](/guides/production).
+A durable store backend, such as Postgres or Redis. Add a queue-backed scheduler
+when the contract has handlers or calls `session.schedule`. A history-only
+contract with no timers needs no reaction infrastructure. Development needs
+neither: SQLite appears under `.a2/` and state survives restarts. See
+[Going to production](/guides/production).
 
 </details>