experimental-a2 0.8.0 → 0.8.1

package/examples/playground/app/canvas/[canvasId]/canvas-replay.test.ts

@@ -0,0 +1,68 @@
+import type { ContractEvent } from 'experimental-a2'
+import { describe, expect, it } from 'vitest'
+import { canvas, type CanvasState } from '../model'
+import { confirmedCanvasEventsSince, replayCanvas } from './canvas-replay'
+
+type CanvasEvents = typeof canvas.events
+type CanvasEvent<
+  K extends keyof CanvasEvents & string = keyof CanvasEvents & string,
+> = ContractEvent<CanvasEvents, K>
+
+const event = <K extends keyof CanvasEvents & string>(
+  index: number,
+  type: K,
+  payload: CanvasEvent<K>['payload'],
+): CanvasEvent<K> =>
+  ({
+    id: `event-${index}`,
+    type,
+    payload,
+    index,
+    sessionId: 'canvas-1',
+    createdAt: new Date(index * 1_000),
+  }) as CanvasEvent<K>
+
+describe('canvas replay', () => {
+  it('replays confirmed events after the server snapshot', () => {
+    const snapshot: CanvasState = {
+      shapes: {
+        square: {
+          id: 'square',
+          kind: 'rect',
+          x: 10,
+          y: 10,
+          w: 80,
+          h: 60,
+          color: 'teal',
+          movedAt: 4,
+        },
+      },
+    }
+    const observed: CanvasEvent[] = [
+      event(4, 'shape.moved', { id: 'square', x: 99, y: 99 }),
+      event(5, 'shape.moved', { id: 'square', x: 20, y: 30 }),
+      event(6, 'shape.deleted', { id: 'square' }),
+      event(7, 'shape.created', {
+        id: 'optimistic',
+        kind: 'ellipse',
+        x: 0,
+        y: 0,
+        w: 50,
+        h: 50,
+        color: 'rose',
+      }),
+    ]
+
+    const confirmed = confirmedCanvasEventsSince(observed, 4, 6)
+
+    expect(confirmed.map(({ index }) => index)).toEqual([5, 6])
+    expect(replayCanvas(snapshot, confirmed, 0)).toEqual(snapshot)
+    expect(replayCanvas(snapshot, confirmed, 1).shapes['square']).toEqual({
+      ...snapshot.shapes['square'],
+      x: 20,
+      y: 30,
+      movedAt: 5,
+    })
+    expect(replayCanvas(snapshot, confirmed, 2).shapes).toEqual({})
+  })
+})

package/examples/playground/app/canvas/[canvasId]/canvas-replay.ts

@@ -0,0 +1,19 @@
+import type { ContractEvent } from 'experimental-a2'
+import { canvas, canvasReducer, type CanvasState } from '../model'
+
+type CanvasEvent = ContractEvent<(typeof canvas)['events']>
+
+export const confirmedCanvasEventsSince = (
+  events: CanvasEvent[],
+  snapshotIndex: number,
+  frontier: number,
+): CanvasEvent[] =>
+  events.filter(
+    (event) => event.index > snapshotIndex && event.index <= frontier,
+  )
+
+export const replayCanvas = (
+  snapshot: CanvasState,
+  events: CanvasEvent[],
+  through: number,
+): CanvasState => events.slice(0, through).reduce(canvasReducer.fold, snapshot)

package/examples/playground/app/canvas/[canvasId]/page.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react'
+import { canvasReducer } from '../model'
+import { canvasServer } from '../server'
+import { CanvasSession } from './canvas-client'
+
+export default async function CanvasSessionPage({
+  params,
+}: {
+  params: Promise<{ canvasId: string }>
+}): Promise<ReactNode> {
+  const { canvasId } = await params
+  const session = canvasServer.session(canvasId)
+  const { state, index } = await session.state(canvasReducer)
+
+  return (
+    <CanvasSession
+      canvasId={canvasId}
+      initialState={state}
+      initialIndex={index}
+    />
+  )
+}

package/examples/playground/app/canvas/[canvasId]/session.ts

@@ -0,0 +1,19 @@
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { canvasReducer } from '../model'
+
+// One route, two wires: on Vercel (production and previews), pushes
+// and presence ride one WebSocket. Anywhere else, including `next
+// dev` (which drops the upgrade handshake before the route runs) and
+// a local `next start`, the same route serves the SSE + POST pair.
+export const canvasClient = createClient({
+  reducer: canvasReducer,
+  api: process.env.NEXT_PUBLIC_VERCEL_ENV
+    ? { type: 'ws', url: '/canvas/events' }
+    : '/canvas/events',
+})
+
+export const { SessionProvider, useSession } = createReact({
+  client: canvasClient,
+})

package/examples/playground/app/canvas/events/route.ts

@@ -0,0 +1,13 @@
+import { experimental_upgradeWebSocket } from '@vercel/functions'
+import { canvasServer } from '../server'
+
+export const POST = canvasServer.fetch
+
+export function GET(request: Request): Promise<Response> {
+  return canvasServer.fetch(request, {
+    upgradeWebSocket: (attach) =>
+      experimental_upgradeWebSocket(attach, {
+        maxPayload: 4 * 1024 * 1024,
+      }),
+  })
+}

package/examples/playground/app/canvas/model.ts

@@ -0,0 +1,94 @@
+import * as a2 from 'experimental-a2'
+import { z } from 'zod'
+
+const paletteSchema = z.enum(['teal', 'amber', 'blue', 'violet', 'rose'])
+
+export type PaletteColor = z.output<typeof paletteSchema>
+
+export const canvas = a2.contract({
+  name: 'canvas',
+  events: {
+    'shape.created': z.object({
+      id: z.string().min(1),
+      kind: z.enum(['rect', 'ellipse']),
+      x: z.number(),
+      y: z.number(),
+      w: z.number().positive(),
+      h: z.number().positive(),
+      color: paletteSchema,
+    }),
+    'shape.moved': z.object({
+      id: z.string().min(1),
+      x: z.number(),
+      y: z.number(),
+    }),
+    'shape.deleted': z.object({ id: z.string().min(1) }),
+  },
+  presence: {
+    profile: z.object({
+      name: z.string().min(1).max(40),
+      color: paletteSchema,
+    }),
+    cursor: z.object({ x: z.number(), y: z.number() }),
+    dragging: z.object({ shapeId: z.string(), x: z.number(), y: z.number() }),
+  },
+})
+
+const canvasShapeSchema = z.object({
+  id: z.string(),
+  kind: z.enum(['rect', 'ellipse']),
+  x: z.number(),
+  y: z.number(),
+  w: z.number(),
+  h: z.number(),
+  color: paletteSchema,
+  movedAt: z.number(),
+})
+
+const canvasState = z.object({
+  shapes: z.record(z.string(), canvasShapeSchema),
+})
+
+export type CanvasState = z.output<typeof canvasState>
+export type CanvasShape = CanvasState['shapes'][string]
+
+export const canvasReducer = canvas
+  .reducer({
+    name: 'canvas-scene',
+    initialState: { shapes: {} },
+    stateSchema: canvasState,
+  })
+  .fold((state, event) => {
+    switch (event.type) {
+      case 'shape.created':
+        return {
+          shapes: {
+            ...state.shapes,
+            [event.payload.id]: { ...event.payload, movedAt: event.index },
+          },
+        }
+      case 'shape.moved': {
+        const shape = state.shapes[event.payload.id]
+        if (!shape) return state
+        return {
+          shapes: {
+            ...state.shapes,
+            [shape.id]: {
+              ...shape,
+              x: event.payload.x,
+              y: event.payload.y,
+              movedAt: event.index,
+            },
+          },
+        }
+      }
+      case 'shape.deleted': {
+        if (!state.shapes[event.payload.id]) return state
+        const shapes = { ...state.shapes }
+        delete shapes[event.payload.id]
+        return { shapes }
+      }
+      default:
+        return state
+    }
+  })

package/examples/playground/app/canvas/open-canvas.tsx

@@ -0,0 +1,40 @@
+'use client'
+import type { FormEvent, ReactNode } from 'react'
+import { useState } from 'react'
+import { useRouter } from 'next/navigation'
+
+export function OpenCanvas(): ReactNode {
+  const router = useRouter()
+  const [canvasId, setCanvasId] = useState('')
+
+  const open = (event: FormEvent): void => {
+    event.preventDefault()
+    const id = canvasId.trim()
+    if (id) router.push(`/canvas/${encodeURIComponent(id)}`)
+  }
+
+  return (
+    <form className="document-picker" onSubmit={open}>
+      <button
+        type="button"
+        onClick={() =>
+          router.push(`/canvas/${crypto.randomUUID().slice(0, 8)}`)
+        }
+      >
+        New canvas
+      </button>
+      <span className="hint">or</span>
+      <label>
+        Open a canvas ID
+        <input
+          value={canvasId}
+          onChange={(event) => setCanvasId(event.target.value)}
+          placeholder="moodboard"
+        />
+      </label>
+      <button className="secondary" type="submit" disabled={!canvasId.trim()}>
+        Open
+      </button>
+    </form>
+  )
+}

package/examples/playground/app/canvas/page.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react'
+import { OpenCanvas } from './open-canvas'
+
+export default function CanvasPage(): ReactNode {
+  return (
+    <article>
+      <h1>A multiplayer canvas on two planes</h1>
+      <p className="lede">
+        Shapes are durable events: create, drag, delete, then scrub the events
+        this page receives to watch the reducer replay from its server snapshot.
+        Cursors and drag ghosts are presence — replicated live, stored never.
+      </p>
+      <OpenCanvas />
+      <p className="hint">
+        Open the same canvas in two tabs. While a shape is mid-drag you are
+        watching presence; the moment it drops you are watching the log.
+      </p>
+    </article>
+  )
+}

package/examples/playground/app/canvas/server.ts

@@ -0,0 +1,9 @@
+import 'server-only'
+import { createServer } from 'experimental-a2/server'
+import { store } from '@/lib/store'
+import { canvas } from './model'
+
+export const canvasServer = createServer({
+  ...(store ? { store } : {}),
+  contract: canvas,
+})

package/examples/playground/app/chat/[chatId]/agent-stream-drawer.test.tsx

@@ -0,0 +1,118 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+import type { ChatAgentMessage } from '../model'
+import { AgentStreamDrawer } from './agent-stream-drawer'
+import type { AgentMessageMetadata, AgentStreamSelection } from './chat-view'
+
+const usage = (
+  inputTokens: number,
+  outputTokens: number,
+  reasoningTokens: number,
+) => ({
+  inputTokens,
+  inputTokenDetails: {
+    noCacheTokens: inputTokens - 2,
+    cacheReadTokens: 2,
+    cacheWriteTokens: 0,
+  },
+  outputTokens,
+  outputTokenDetails: {
+    textTokens: outputTokens - reasoningTokens,
+    reasoningTokens,
+  },
+  totalTokens: inputTokens + outputTokens,
+})
+
+describe('AgentStreamDrawer', () => {
+  it('renders the complete ordered UIMessage stream and completed metadata', () => {
+    const parts: ChatAgentMessage['parts'] = [
+      { type: 'step-start' },
+      {
+        type: 'reasoning',
+        text: 'Consider whether this would help the room.',
+        state: 'done',
+      },
+      {
+        type: 'text',
+        text: 'Private model text that was not posted.',
+        state: 'done',
+      },
+      {
+        type: 'tool-post',
+        toolCallId: 'call-1',
+        state: 'output-available',
+        input: { message: 'Visible room message from the post tool.' },
+        output: { posted: true },
+      },
+      {
+        type: 'custom',
+        kind: 'openai.trace',
+        providerMetadata: { openai: { traceId: 'trace-1' } },
+      },
+    ]
+    const metadata: AgentMessageMetadata = {
+      kind: 'agent',
+      author: 'agent',
+      mode: 'ambient',
+      steps: [
+        {
+          generationId: 'generation-1',
+          model: 'openai/gpt-first',
+          finishReason: 'tool-calls',
+          usage: usage(12, 5, 2),
+          completedAt: '2026-08-16T12:00:00.000Z',
+        },
+        {
+          generationId: 'generation-2',
+          model: 'openai/gpt-second',
+          finishReason: 'stop',
+          usage: usage(15, 3, 0),
+          completedAt: '2026-08-16T12:00:01.000Z',
+        },
+      ],
+    }
+    const message: ChatAgentMessage = {
+      id: 'assistant-1',
+      role: 'assistant',
+      metadata,
+      parts,
+    }
+    const selection: AgentStreamSelection = {
+      message,
+      parts,
+      metadata,
+    }
+
+    const markup = renderToStaticMarkup(
+      <AgentStreamDrawer
+        responseMessageId={message.id}
+        selection={selection}
+        summary="ambient · 35 tokens · 2 model steps"
+        status="completed"
+        onClose={vi.fn<() => void>()}
+      />,
+    )
+
+    const orderedMarkers = [
+      'Model step',
+      'Consider whether this would help the room.',
+      'Private model text that was not posted.',
+      'Visible room message from the post tool.',
+      'openai.trace',
+    ]
+    const positions = orderedMarkers.map((marker) => markup.indexOf(marker))
+    expect(positions.every((position) => position >= 0)).toBe(true)
+    expect(positions).toEqual(
+      [...positions].toSorted((left, right) => left - right),
+    )
+
+    expect(markup).toContain('openai/gpt-first')
+    expect(markup).toContain('tool-calls')
+    expect(markup).toContain('generation-1')
+    expect(markup).toContain('openai/gpt-second')
+    expect(markup).toContain('generation-2')
+    expect(markup).toContain('Full AI SDK usage')
+    expect(markup).toContain('cacheReadTokens')
+    expect(markup).toContain('Raw extended UIMessage')
+  })
+})