npm - experimental-a2 - Versions diffs - 0.7.0 → 0.8.1 - Mend

experimental-a2 0.7.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (150) hide show

package/AGENTS.md +11 -0
package/CHANGELOG.md +27 -0
package/README.md +29 -0
package/dist/ai-server.d.ts +1 -1
package/dist/ai-server.d.ts.map +1 -1
package/dist/ai-server.js +13 -11
package/dist/ai-server.js.map +1 -1
package/dist/ai.d.ts +1 -1
package/dist/index.d.ts +1 -1
package/dist/scheduler-qstash.d.ts +2 -2
package/dist/scheduler-qstash.js +1 -1
package/dist/scheduler-vercel.d.ts +2 -2
package/dist/scheduler-vercel.js +1 -1
package/dist/{server-286j79Mt.js → server-B2XNevQA.js} +123 -53
package/dist/server-B2XNevQA.js.map +1 -0
package/dist/{server-DgXmORIq.d.ts → server-DjPhHnbI.d.ts} +7 -4
package/dist/server-DjPhHnbI.d.ts.map +1 -0
package/dist/server.d.ts +3 -3
package/dist/server.js +1 -1
package/dist/store-N8PXxDAS.js.map +1 -1
package/dist/{store-flRz1OWh.d.ts → store-RJO35BMj.d.ts} +25 -8
package/dist/store-RJO35BMj.d.ts.map +1 -0
package/dist/store-memory.d.ts +1 -1
package/dist/store-memory.d.ts.map +1 -1
package/dist/store-memory.js +79 -19
package/dist/store-memory.js.map +1 -1
package/dist/store-postgres.d.ts +1 -1
package/dist/store-postgres.d.ts.map +1 -1
package/dist/store-postgres.js +230 -101
package/dist/store-postgres.js.map +1 -1
package/dist/{store-redis-core-DEYO8Ryv.js → store-redis-core-DT01r4GZ.js} +167 -29
package/dist/store-redis-core-DT01r4GZ.js.map +1 -0
package/dist/store-redis-http.d.ts +1 -1
package/dist/store-redis-http.js +2 -2
package/dist/store-redis-http.js.map +1 -1
package/dist/store-redis.d.ts +1 -1
package/dist/store-redis.js +2 -2
package/dist/store-redis.js.map +1 -1
package/dist/store-sqlite.d.ts +1 -1
package/dist/store-sqlite.d.ts.map +1 -1
package/dist/store-sqlite.js +103 -19
package/dist/store-sqlite.js.map +1 -1
package/docs/concepts/02-handlers.mdx +4 -0
package/docs/concepts/04-state.mdx +57 -9
package/docs/guides/06-ai-agents.mdx +2 -1
package/docs/guides/07-examples.mdx +56 -0
package/docs/index.mdx +13 -0
package/docs/reference/01-api.mdx +39 -16
package/examples/README.md +15 -0
package/examples/playground/AGENTS.md +11 -0
package/examples/playground/DEPLOY.md +106 -0
package/examples/playground/README.md +19 -0
package/examples/playground/activity-feed.test.ts +10 -0
package/examples/playground/app/agent/[agentId]/agent-client.tsx +376 -0
package/examples/playground/app/agent/[agentId]/page.tsx +29 -0
package/examples/playground/app/agent/events/route.ts +4 -0
package/examples/playground/app/agent/model.ts +3 -0
package/examples/playground/app/agent/new-agent-session.tsx +98 -0
package/examples/playground/app/agent/page.tsx +25 -0
package/examples/playground/app/agent/scheduler/route.ts +5 -0
package/examples/playground/app/agent/server.ts +153 -0
package/examples/playground/app/agent/session.ts +13 -0
package/examples/playground/app/canvas/[canvasId]/canvas-client.tsx +682 -0
package/examples/playground/app/canvas/[canvasId]/canvas-replay.test.ts +68 -0
package/examples/playground/app/canvas/[canvasId]/canvas-replay.ts +19 -0
package/examples/playground/app/canvas/[canvasId]/page.tsx +22 -0
package/examples/playground/app/canvas/[canvasId]/session.ts +19 -0
package/examples/playground/app/canvas/events/route.ts +13 -0
package/examples/playground/app/canvas/model.ts +94 -0
package/examples/playground/app/canvas/open-canvas.tsx +40 -0
package/examples/playground/app/canvas/page.tsx +20 -0
package/examples/playground/app/canvas/server.ts +9 -0
package/examples/playground/app/chat/[chatId]/agent-stream-drawer.test.tsx +118 -0
package/examples/playground/app/chat/[chatId]/agent-stream-drawer.tsx +316 -0
package/examples/playground/app/chat/[chatId]/chat-client.tsx +922 -0
package/examples/playground/app/chat/[chatId]/chat-view.test.ts +152 -0
package/examples/playground/app/chat/[chatId]/chat-view.ts +101 -0
package/examples/playground/app/chat/[chatId]/composer.test.ts +44 -0
package/examples/playground/app/chat/[chatId]/composer.ts +30 -0
package/examples/playground/app/chat/[chatId]/page.tsx +30 -0
package/examples/playground/app/chat/[chatId]/session.ts +7 -0
package/examples/playground/app/chat/events/route.ts +7 -0
package/examples/playground/app/chat/model.test.ts +155 -0
package/examples/playground/app/chat/model.ts +310 -0
package/examples/playground/app/chat/new-conversation.tsx +16 -0
package/examples/playground/app/chat/page.tsx +25 -0
package/examples/playground/app/chat/scheduler/route.ts +5 -0
package/examples/playground/app/chat/server.ts +184 -0
package/examples/playground/app/components/activity-feed.tsx +54 -0
package/examples/playground/app/components/connection-pill.tsx +29 -0
package/examples/playground/app/counter/counter-client.tsx +72 -0
package/examples/playground/app/counter/events/route.ts +4 -0
package/examples/playground/app/counter/model.test.ts +36 -0
package/examples/playground/app/counter/model.ts +31 -0
package/examples/playground/app/counter/page.tsx +24 -0
package/examples/playground/app/counter/server.ts +9 -0
package/examples/playground/app/counter/session.ts +13 -0
package/examples/playground/app/documents/[documentId]/code-editor.tsx +80 -0
package/examples/playground/app/documents/[documentId]/document-client.tsx +525 -0
package/examples/playground/app/documents/[documentId]/page.tsx +23 -0
package/examples/playground/app/documents/[documentId]/session.ts +7 -0
package/examples/playground/app/documents/events/route.ts +4 -0
package/examples/playground/app/documents/model.ts +55 -0
package/examples/playground/app/documents/open-document.tsx +40 -0
package/examples/playground/app/documents/page.tsx +22 -0
package/examples/playground/app/documents/server.ts +9 -0
package/examples/playground/app/globals.css +2078 -0
package/examples/playground/app/layout.tsx +44 -0
package/examples/playground/app/orders/[orderId]/order-client.tsx +140 -0
package/examples/playground/app/orders/[orderId]/page.tsx +29 -0
package/examples/playground/app/orders/[orderId]/session.ts +11 -0
package/examples/playground/app/orders/create/route.ts +30 -0
package/examples/playground/app/orders/events/route.ts +4 -0
package/examples/playground/app/orders/model.ts +79 -0
package/examples/playground/app/orders/new-order-form.tsx +98 -0
package/examples/playground/app/orders/page.tsx +22 -0
package/examples/playground/app/orders/scheduler/route.ts +5 -0
package/examples/playground/app/orders/server.ts +50 -0
package/examples/playground/app/page.tsx +102 -0
package/examples/playground/app/recovery/[recoveryId]/page.tsx +31 -0
package/examples/playground/app/recovery/[recoveryId]/recovery-client.tsx +144 -0
package/examples/playground/app/recovery/[recoveryId]/session.ts +7 -0
package/examples/playground/app/recovery/events/route.ts +3 -0
package/examples/playground/app/recovery/model.ts +55 -0
package/examples/playground/app/recovery/new-recovery-session.tsx +20 -0
package/examples/playground/app/recovery/page.tsx +22 -0
package/examples/playground/app/recovery/scheduler/route.ts +7 -0
package/examples/playground/app/recovery/server.ts +53 -0
package/examples/playground/app/recovery/start/route.ts +41 -0
package/examples/playground/css.d.ts +4 -0
package/examples/playground/lib/store.ts +15 -0
package/examples/playground/next-env.d.ts +5 -0
package/examples/playground/next.config.ts +10 -0
package/examples/playground/package.json +46 -0
package/examples/playground/tsconfig.json +37 -0
package/examples/playground/vercel.json +40 -0
package/package.json +5 -2
package/src/ai-server.ts +27 -10
package/src/server.ts +242 -87
package/src/store-memory.ts +138 -20
package/src/store-postgres.ts +355 -138
package/src/store-redis-core.ts +201 -27
package/src/store-redis-http.ts +1 -1
package/src/store-redis.ts +1 -1
package/src/store-sqlite.ts +191 -34
package/src/store.ts +27 -9
package/dist/server-286j79Mt.js.map +0 -1
package/dist/server-DgXmORIq.d.ts.map +0 -1
package/dist/store-flRz1OWh.d.ts.map +0 -1
package/dist/store-redis-core-DEYO8Ryv.js.map +0 -1

package/examples/playground/app/layout.tsx ADDED Viewed

@@ -0,0 +1,44 @@
+import type { Metadata } from 'next'
+import type { ReactNode } from 'react'
+import Link from 'next/link'
+import './globals.css'
+export const metadata: Metadata = {
+  title: 'a2 example',
+  description:
+    'A durable event log for serverless apps — counters, agents, orders, streaming, cancellation, multiplayer documents, and a shared canvas.',
+}
+export default function RootLayout({
+  children,
+}: {
+  children: ReactNode
+}): ReactNode {
+  return (
+    <html lang="en">
+      <body>
+        <header className="site-header">
+          <nav>
+            <Link href="/" className="brand">
+              a2 <span>example</span>
+            </Link>
+            <Link href="/orders">Orders</Link>
+            <Link href="/chat">Chat</Link>
+            <Link href="/agent">Agent</Link>
+            <Link href="/canvas">Canvas</Link>
+            <Link href="/documents">Documents</Link>
+            <Link href="/recovery">Recovery</Link>
+            <Link href="/counter">Counter</Link>
+          </nav>
+        </header>
+        <main>{children}</main>
+        <footer className="site-footer">
+          <p>
+            Everything on these pages is a fold over an append-only log — check{' '}
+            <code>.a2/dev.db</code>.
+          </p>
+        </footer>
+      </body>
+    </html>
+  )
+}

package/examples/playground/app/orders/[orderId]/order-client.tsx ADDED Viewed

@@ -0,0 +1,140 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+import type { OrderState } from '../model'
+import { ActivityFeed } from '@/app/components/activity-feed'
+import { ConnectionPill } from '@/app/components/connection-pill'
+import { useSession } from './session'
+const STATUS_LABEL: Record<OrderState['status'], string> = {
+  new: 'no events yet',
+  created: 'created',
+  notified: 'shop notified',
+  preparing: 'preparing',
+  'courier-assigned': 'courier assigned',
+  delivering: 'out for delivery',
+  delivered: 'delivered',
+}
+/** The journey as steps, in log order — `status` maps to how far the
+ * fold has advanced through them. */
+const JOURNEY: Array<{ status: OrderState['status']; label: string }> = [
+  { status: 'created', label: 'Created' },
+  { status: 'notified', label: 'Shop notified' },
+  { status: 'preparing', label: 'Preparing' },
+  { status: 'courier-assigned', label: 'Courier assigned' },
+  { status: 'delivering', label: 'Out for delivery' },
+  { status: 'delivered', label: 'Delivered' },
+]
+export function OrderClient({ sessionId }: { sessionId: string }): ReactNode {
+  const { state, push, events, index, connection } = useSession()
+  const [error, setError] = useState<string | null>(null)
+  const reached = JOURNEY.findIndex((step) => step.status === state.status)
+  const delivered = state.status === 'delivered'
+  // Show the button only until the kitchen takes over; after that the
+  // journey finishes on its own.
+  const showStart =
+    state.status === 'new' ||
+    state.status === 'created' ||
+    state.status === 'notified'
+  const canStart = state.status === 'created' || state.status === 'notified'
+  const startPreparation = async (): Promise<void> => {
+    setError(null)
+    try {
+      await push({ type: 'shop.started', payload: {} })
+    } catch (err) {
+      // Rejected pushes roll back automatically; we just surface why.
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+  return (
+    <article>
+      <header className="session-header">
+        <h1>
+          Order <code>{sessionId}</code>
+        </h1>
+        <ConnectionPill connection={connection} />
+        <span
+          className={`badge${delivered ? ' done' : state.status === 'new' ? '' : ' live'}`}
+        >
+          {STATUS_LABEL[state.status]}
+        </span>
+      </header>
+      {state.status === 'new' ? (
+        <p className="hint">
+          This session has no events — an unknown id and an empty order look
+          identical, because state is only ever a fold over the log.
+        </p>
+      ) : (
+        <>
+          <ol className="timeline">
+            {JOURNEY.map((step, i) => (
+              <li
+                key={step.status}
+                className={
+                  i < reached || delivered
+                    ? 'done'
+                    : i === reached
+                      ? 'current'
+                      : ''
+                }
+              >
+                {step.label}
+              </li>
+            ))}
+          </ol>
+          <dl className="facts">
+            <dt>Shop</dt>
+            <dd>{state.shopId ?? '—'}</dd>
+            <dt>Items</dt>
+            <dd>{state.items.join(', ') || '—'}</dd>
+            <dt>Courier</dt>
+            <dd>{state.driverId ?? 'not assigned yet'}</dd>
+            {state.etaMinutes !== null ? (
+              <>
+                <dt>ETA</dt>
+                <dd>~{state.etaMinutes} min</dd>
+              </>
+            ) : null}
+          </dl>
+        </>
+      )}
+      {showStart ? (
+        <>
+          <button
+            onClick={() => void startPreparation()}
+            disabled={!canStart}
+            title={canStart ? undefined : 'Create the order first'}
+          >
+            Start preparation
+          </button>
+          {error ? <p className="error">{error}</p> : null}
+          <p className="hint">
+            The button pushes <code>shop.started</code> optimistically — the
+            badge flips before the server acks. Everything after that is
+            handlers appending the next fact: courier assigned, picked up,
+            delivered — watch it arrive over the stream, hands off.
+          </p>
+        </>
+      ) : delivered ? (
+        <p className="hint">
+          Journey complete. Every hop above is an event in the log — the feed
+          below is the whole story, oldest first.
+        </p>
+      ) : (
+        <p className="hint">
+          Hands off from here — each status lands on its own as handlers append
+          the next fact.
+        </p>
+      )}
+      <ActivityFeed events={events} index={index} />
+    </article>
+  )
+}

package/examples/playground/app/orders/[orderId]/page.tsx ADDED Viewed

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react'
+import { ordersReducer } from '../model'
+import { ordersServer } from '../server'
+import { SessionProvider } from './session'
+import { OrderClient } from './order-client'
+export default async function OrderPage({
+  params,
+}: {
+  params: Promise<{ orderId: string }>
+}): Promise<ReactNode> {
+  const { orderId } = await params
+  // First paint costs no client JS: fold on the server, pass it down.
+  // `index` is the fold's frontier — the stream resumes exactly there.
+  const { state, index } = await ordersServer
+    .session(decodeURIComponent(orderId))
+    .state(ordersReducer)
+  return (
+    <SessionProvider
+      sessionId={decodeURIComponent(orderId)}
+      api="/orders/events"
+      initialState={state}
+      initialIndex={index}
+    >
+      <OrderClient sessionId={decodeURIComponent(orderId)} />
+    </SessionProvider>
+  )
+}

package/examples/playground/app/orders/[orderId]/session.ts ADDED Viewed

@@ -0,0 +1,11 @@
+'use client'
+/**
+ * The whole client/server seam: bind the reducer once, export the
+ * pair. Nothing in this file touches the machine module.
+ */
+import { createReact } from 'experimental-a2/react'
+import { ordersReducer } from '../model'
+export const { SessionProvider, useSession } = createReact({
+  reducer: ordersReducer,
+})

package/examples/playground/app/orders/create/route.ts ADDED Viewed

@@ -0,0 +1,30 @@
+import { A2Error } from 'experimental-a2'
+import { ordersServer } from '../server'
+const errorResponse = (error: unknown): Response => {
+  if (error instanceof A2Error) {
+    return new Response(error.message, {
+      status: error.code === 'STORE_UNAVAILABLE' ? 503 : 400,
+    })
+  }
+  return new Response('internal error', { status: 500 })
+}
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const { orderId, shopId, items } = await request.json()
+    if (typeof orderId !== 'string' || orderId.length === 0) {
+      throw new A2Error('INVALID_PAYLOAD', 'orderId must be a non-empty string')
+    }
+    const appended = await ordersServer.session(orderId).append({
+      type: 'created',
+      payload: { shopId, items },
+    })
+    return Response.json(appended)
+  } catch (error) {
+    return errorResponse(error)
+  }
+}

package/examples/playground/app/orders/events/route.ts ADDED Viewed

@@ -0,0 +1,4 @@
+import { ordersServer } from '../server'
+export const GET = ordersServer.fetch
+export const POST = ordersServer.fetch

package/examples/playground/app/orders/model.ts ADDED Viewed

@@ -0,0 +1,79 @@
+import * as a2 from 'experimental-a2'
+import { z } from 'zod'
+export const orders = a2.contract({
+  name: 'orders',
+  events: {
+    created: z.object({
+      shopId: z.string(),
+      items: z.array(z.string()).min(1),
+    }),
+    'shop.notified': z.object({}),
+    'shop.started': z.object({}),
+    'driver.notified': z.object({ driverId: z.string() }),
+    'courier.picked_up': z.object({ etaMinutes: z.number().int().positive() }),
+    delivered: z.object({}),
+  },
+})
+const orderState = z.object({
+  status: z.enum([
+    'new',
+    'created',
+    'notified',
+    'preparing',
+    'courier-assigned',
+    'delivering',
+    'delivered',
+  ]),
+  shopId: z.string().nullable(),
+  items: z.array(z.string()),
+  driverId: z.string().nullable(),
+  etaMinutes: z.number().nullable(),
+})
+export type OrderState = z.output<typeof orderState>
+export const ordersReducer = orders
+  .reducer({
+    name: 'order-status',
+    initialState: {
+      status: 'new',
+      shopId: null,
+      items: [],
+      driverId: null,
+      etaMinutes: null,
+    },
+    stateSchema: orderState,
+  })
+  .fold((state, event) => {
+    switch (event.type) {
+      case 'created':
+        return {
+          ...state,
+          status: 'created',
+          shopId: event.payload.shopId,
+          items: event.payload.items,
+        }
+      case 'shop.notified':
+        return { ...state, status: 'notified' }
+      case 'shop.started':
+        return { ...state, status: 'preparing' }
+      case 'driver.notified':
+        return {
+          ...state,
+          status: 'courier-assigned',
+          driverId: event.payload.driverId,
+        }
+      case 'courier.picked_up':
+        return {
+          ...state,
+          status: 'delivering',
+          etaMinutes: event.payload.etaMinutes,
+        }
+      case 'delivered':
+        return { ...state, status: 'delivered', etaMinutes: null }
+      default:
+        return state
+    }
+  })

package/examples/playground/app/orders/new-order-form.tsx ADDED Viewed

@@ -0,0 +1,98 @@
+'use client'
+import type { FormEvent, ReactNode } from 'react'
+import { useRouter } from 'next/navigation'
+import { useState } from 'react'
+const randomOrderId = (): string =>
+  `order-${Math.random().toString(36).slice(2, 8)}`
+export function NewOrderForm(): ReactNode {
+  const router = useRouter()
+  const [orderId, setOrderId] = useState(randomOrderId)
+  const [shopId, setShopId] = useState('shop-7')
+  const [items, setItems] = useState('flat white, croissant')
+  const [existingId, setExistingId] = useState('')
+  const [error, setError] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+  const createOrder = async (e: FormEvent): Promise<void> => {
+    e.preventDefault()
+    setBusy(true)
+    setError(null)
+    try {
+      const res = await fetch('/orders/create', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          orderId,
+          shopId,
+          items: items
+            .split(',')
+            .map((item) => item.trim())
+            .filter(Boolean),
+        }),
+      })
+      if (!res.ok) {
+        throw new Error(
+          (await res.text()) || `unexpected ${res.status} response`,
+        )
+      }
+      router.push(`/orders/${encodeURIComponent(orderId)}`)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+      setBusy(false)
+    }
+  }
+  const openExisting = (e: FormEvent): void => {
+    e.preventDefault()
+    if (existingId.trim()) {
+      router.push(`/orders/${encodeURIComponent(existingId.trim())}`)
+    }
+  }
+  return (
+    <>
+      <form onSubmit={(e) => void createOrder(e)}>
+        <label>
+          Order id
+          <input
+            value={orderId}
+            onChange={(e) => setOrderId(e.target.value)}
+            required
+          />
+        </label>
+        <label>
+          Shop
+          <select value={shopId} onChange={(e) => setShopId(e.target.value)}>
+            <option value="shop-7">shop-7 — Third Wave Espresso</option>
+            <option value="shop-12">shop-12 — Brutalist Bagels</option>
+            <option value="shop-31">shop-31 — Soup, Reduced</option>
+          </select>
+        </label>
+        <label>
+          Items (comma-separated)
+          <input value={items} onChange={(e) => setItems(e.target.value)} />
+        </label>
+        <button type="submit" disabled={busy}>
+          {busy ? 'Appending…' : 'Create order'}
+        </button>
+        {error ? <p className="error">{error}</p> : null}
+      </form>
+      <form className="inline-form" onSubmit={openExisting}>
+        <label>
+          Open an existing order
+          <input
+            value={existingId}
+            onChange={(e) => setExistingId(e.target.value)}
+            placeholder="order-abc123"
+          />
+        </label>
+        <button type="submit" className="secondary">
+          Open
+        </button>
+      </form>
+    </>
+  )
+}

package/examples/playground/app/orders/page.tsx ADDED Viewed

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react'
+import { NewOrderForm } from './new-order-form'
+export default function OrdersPage(): ReactNode {
+  return (
+    <article>
+      <h1>Order tracker</h1>
+      <p className="lede">
+        Creating an order appends a single <code>created</code> event.
+        Everything after that — the shop notification, the courier, the delivery
+        itself — is handlers appending the next fact to the same log, all the
+        way to <code>delivered</code>.
+      </p>
+      <NewOrderForm />
+      <p className="hint">
+        Order ids are yours to choose: revisit{' '}
+        <code>/orders/&lt;your-id&gt;</code> any time — the log survives{' '}
+        <code>next dev</code> restarts.
+      </p>
+    </article>
+  )
+}

package/examples/playground/app/orders/scheduler/route.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import { ordersScheduler, ordersServer } from '../server'
+export const POST =
+  ordersScheduler?.handler(ordersServer) ??
+  (() => new Response('orders scheduler is not configured', { status: 503 }))

package/examples/playground/app/orders/server.ts ADDED Viewed

@@ -0,0 +1,50 @@
+import 'server-only'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { createServer } from 'experimental-a2/server'
+import { store } from '@/lib/store'
+import { orders } from './model'
+const wait = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms))
+const drivers = ['driver-ada', 'driver-grace', 'driver-alan', 'driver-edsger']
+export const ordersScheduler =
+  process.env.VERCEL || process.env.A2_QUEUES
+    ? vercelQueues({ topic: 'a2-orders' })
+    : undefined
+export const ordersServer = createServer({
+  ...(store ? { store } : {}),
+  ...(ordersScheduler ? { scheduler: ordersScheduler } : {}),
+  contract: orders,
+  handlers: {
+    created: async ({ session }) => {
+      await wait(800)
+      await session.append('notify-shop', {
+        type: 'shop.notified',
+        payload: {},
+      })
+    },
+    'shop.started': async ({ session }) => {
+      await wait(1200)
+      const driverId = drivers[Math.floor(Math.random() * drivers.length)]!
+      await session.append('notify-driver', {
+        type: 'driver.notified',
+        payload: { driverId },
+      })
+    },
+    'driver.notified': async ({ session }) => {
+      await wait(3000)
+      const etaMinutes = 3 + Math.floor(Math.random() * 5)
+      await session.append('courier-picked-up', {
+        type: 'courier.picked_up',
+        payload: { etaMinutes },
+      })
+    },
+    'courier.picked_up': async ({ session }) => {
+      await wait(3500)
+      await session.append('delivered', { type: 'delivered', payload: {} })
+    },
+  },
+})

package/examples/playground/app/page.tsx ADDED Viewed

@@ -0,0 +1,102 @@
+import type { ReactNode } from 'react'
+import Link from 'next/link'
+export default function HomePage(): ReactNode {
+  return (
+    <article>
+      <h1>A durable event log, live in your browser</h1>
+      <p className="lede">
+        Seven small demos, one model: append an event, let a handler react, fold
+        the log into a view — on the server for the first paint, in the browser
+        for every moment after.
+      </p>
+      <div className="card-grid">
+        <Link className="card" href="/orders">
+          <h2>Order tracker</h2>
+          <p>
+            A form appends <code>created</code>, and handlers chain the rest —
+            shop notified, courier assigned, picked up, delivered — while the
+            page watches over a live stream. One optimistic click, then the
+            order runs itself to the end.
+          </p>
+        </Link>
+        <Link className="card" href="/chat">
+          <h2>Multiplayer chat + agent</h2>
+          <p>
+            Messages, “is typing…” presence, and an AI participant share one
+            stream. Mention <code>@agent</code>, or enable ambient mode for the
+            room. The model can stay silent or call a durable <code>post</code>{' '}
+            tool; its private generation appears only as “thinking” or
+            “writing.”
+          </p>
+        </Link>
+        <Link className="card" href="/agent">
+          <h2>Agent</h2>
+          <p>
+            A durable AI agent inspects a service, records tool calls, pauses
+            for approval, runs Bash in a persistent Vercel Sandbox, and sets
+            reminders that return as new user messages. Messages, progress,
+            tools, timers, and the human decision are all ordinary A2 events.
+          </p>
+        </Link>
+        <Link className="card" href="/canvas">
+          <h2>Multiplayer canvas</h2>
+          <p>
+            Shapes are durable events you can scrub back through after the
+            server snapshot. Cursors and drag ghosts are presence: replicated
+            live, stored never.
+          </p>
+        </Link>
+        <Link className="card" href="/documents">
+          <h2>Multiplayer document</h2>
+          <p>
+            Two CodeMirror editors share one Yjs document. A2 durably orders the
+            CRDT updates while Yjs Awareness — live cursors and selections —
+            rides the session's presence plane, never touching the log.
+          </p>
+        </Link>
+        <Link className="card" href="/recovery">
+          <h2>Cross-invocation recovery</h2>
+          <p>
+            Chain four 8-second handlers under a 20-second function limit, then
+            watch Vercel stop one mid-handler and A2 retry that pending event
+            under a fresh claim.
+          </p>
+        </Link>
+        <Link className="card" href="/counter">
+          <h2>Counter</h2>
+          <p>
+            Increment and decrement one shared value. Every click is a durable
+            event applied optimistically in the browser, then confirmed by the
+            stream — open two tabs and watch both folds converge.
+          </p>
+        </Link>
+      </div>
+      <section>
+        <h2>Where things live</h2>
+        <ul>
+          <li>
+            Each demo owns a <code>model.ts</code> with its contract, reducer,
+            and shared types.
+          </li>
+          <li>
+            Its <code>server.ts</code> implements handlers and configures the
+            production store and scheduler it actually needs.
+          </li>
+          <li>
+            Its <code>events/route.ts</code> exposes <code>server.fetch</code>{' '}
+            directly, adding only feature-specific authorization or WebSocket
+            capabilities.
+          </li>
+          <li>
+            Demos with handlers or timers own a private{' '}
+            <code>scheduler/route.ts</code> and queue topic. Counter, canvas,
+            and documents need no scheduler.
+          </li>
+        </ul>
+      </section>
+    </article>
+  )
+}

package/examples/playground/app/recovery/[recoveryId]/page.tsx ADDED Viewed

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react'
+import { recoveryReducer } from '../model'
+import { recoveryServer } from '../server'
+import { RecoveryClient } from './recovery-client'
+import { SessionProvider } from './session'
+export default async function RecoveryRunPage({
+  params,
+}: {
+  params: Promise<{ recoveryId: string }>
+}): Promise<ReactNode> {
+  const { recoveryId } = await params
+  const sessionId = decodeURIComponent(recoveryId)
+  const { state, index } = await recoveryServer
+    .session(sessionId)
+    .state(recoveryReducer)
+  return (
+    <SessionProvider
+      sessionId={sessionId}
+      api="/recovery/events"
+      initialState={state}
+      initialIndex={index}
+    >
+      <RecoveryClient
+        sessionId={sessionId}
+        onVercel={Boolean(process.env.VERCEL)}
+      />
+    </SessionProvider>
+  )
+}