experimental-a2 0.16.1 → 0.18.0

package/examples/playground/app/components/activity-feed.tsx

@@ -1,4 +1,7 @@
-import type { ReactNode } from 'react'
+'use client'
+
+import { useState, type ReactNode } from 'react'
+import type { HistoryState } from 'experimental-a2/client'
 
 /** The structural shape every machine's events share — enough for a
  * feed that shows the log itself. */
@@ -18,11 +21,26 @@ export function ActivityFeed({
   events,
   index,
   status,
+  history,
+  loadHistory,
 }: {
   events: readonly FeedEvent[]
   index: number
   status?: ReactNode
+  history?: HistoryState
+  loadHistory?: () => Promise<unknown>
 }): ReactNode {
+  const [error, setError] = useState<string | null>(null)
+  const loadEarlier = async (): Promise<void> => {
+    setError(null)
+    try {
+      await loadHistory?.()
+    } catch (cause) {
+      setError(
+        cause instanceof Error ? cause.message : 'Could not load history.',
+      )
+    }
+  }
   return (
     <section>
       <h2>Activity</h2>
@@ -45,6 +63,17 @@ export function ActivityFeed({
         </ol>
       )}
       {status ? <p className="activity-status">{status}</p> : null}
+      {history && loadHistory && !history.complete ? (
+        <button
+          type="button"
+          className="secondary"
+          disabled={history.loading}
+          onClick={() => void loadEarlier()}
+        >
+          {history.loading ? 'Loading…' : 'Load earlier events'}
+        </button>
+      ) : null}
+      {error ? <p role="alert">{error}</p> : null}
       <p className="frontier">
         Stream frontier: <code>{index}</code> — the last server-confirmed log
         position this browser has folded.

package/examples/playground/app/components/activity-history.test.tsx

@@ -0,0 +1,35 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import { ActivityFeed } from './activity-feed'
+
+afterEach(cleanup)
+
+it('loads an earlier page only on request and keeps failures retryable', async () => {
+  const loadHistory = vi
+    .fn<() => Promise<unknown>>()
+    .mockRejectedValueOnce(new Error('Read failed'))
+    .mockResolvedValueOnce([])
+  render(
+    <ActivityFeed
+      events={[]}
+      index={100}
+      history={{ loading: false, complete: false, oldestLoaded: null }}
+      loadHistory={loadHistory}
+    />,
+  )
+  expect(loadHistory).not.toHaveBeenCalled()
+  await act(async () =>
+    fireEvent.click(
+      screen.getByRole('button', { name: 'Load earlier events' }),
+    ),
+  )
+  expect(screen.getByRole('alert').textContent).toBe('Read failed')
+  await act(async () =>
+    fireEvent.click(
+      screen.getByRole('button', { name: 'Load earlier events' }),
+    ),
+  )
+  expect(screen.queryByRole('alert')).toBeNull()
+  expect(loadHistory).toHaveBeenCalledTimes(2)
+})

package/examples/playground/app/components/demo-icons.tsx

@@ -0,0 +1,89 @@
+import type { ReactNode } from 'react'
+
+/** A 24px line icon: ink strokes, with its `accent` parts in orange. */
+function Glyph({ children }: { children: ReactNode }): ReactNode {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="square"
+      aria-hidden
+    >
+      {children}
+    </svg>
+  )
+}
+
+export const A0Icon = (): ReactNode => (
+  <Glyph>
+    <rect x="3" y="4" width="18" height="16" />
+    <path d="M3 8h18" />
+    <path className="accent" d="M7 12l2.5 2L7 16M12 16h5" />
+  </Glyph>
+)
+
+export const OrdersIcon = (): ReactNode => (
+  <Glyph>
+    <path d="M3 4h18v5H3zM5 9v11h14V9" />
+    <path className="accent" d="M10 13h4" />
+  </Glyph>
+)
+
+export const ChatIcon = (): ReactNode => (
+  <Glyph>
+    <path d="M3 4h18v13H10l-4 3.5V17H3z" />
+    <rect className="fill" x="7" y="10" width="2" height="2" />
+    <rect className="fill" x="11" y="10" width="2" height="2" />
+    <rect className="accent-fill" x="15" y="10" width="2" height="2" />
+  </Glyph>
+)
+
+export const AgentIcon = (): ReactNode => (
+  <Glyph>
+    <rect x="3" y="3" width="18" height="18" />
+    <path className="accent" d="M12 7v10M7.7 9.5l8.6 5M7.7 14.5l8.6-5" />
+  </Glyph>
+)
+
+export const CanvasIcon = (): ReactNode => (
+  <Glyph>
+    <rect x="3" y="3" width="10" height="10" />
+    <circle cx="13" cy="13" r="5" />
+    <path className="accent-fill" d="M13 13l8.5 3.4-3.6 1.3-1.3 3.6z" />
+  </Glyph>
+)
+
+export const DocumentsIcon = (): ReactNode => (
+  <Glyph>
+    <path d="M5 3h10l4 4v14H5z" />
+    <path d="M8 10h8M8 14h4M8 18h7" />
+    <path className="accent" d="M14 12v4" />
+  </Glyph>
+)
+
+export const RecoveryIcon = (): ReactNode => (
+  <Glyph>
+    <path d="M20.5 12a8.5 8.5 0 1 1-2.5-6l2.5 2.5" />
+    <path d="M20.5 3.5v5h-5" />
+    <rect className="accent-fill" x="10" y="10" width="4" height="4" />
+  </Glyph>
+)
+
+export const VaultIcon = (): ReactNode => (
+  <Glyph>
+    <rect x="3" y="4" width="18" height="15" />
+    <circle cx="11" cy="11.5" r="3.5" />
+    <path className="accent" d="M11 11.5l2-2" />
+    <path d="M17.5 9.5v4M6 19v2M18 19v2" />
+  </Glyph>
+)
+
+export const CounterIcon = (): ReactNode => (
+  <Glyph>
+    <rect x="3" y="6" width="18" height="12" />
+    <path className="accent" d="M6.5 12h5M9 9.5v5" />
+    <path d="M16.5 9v6M15 10.5L16.5 9" />
+  </Glyph>
+)

package/examples/playground/app/components/demos.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react'
+import {
+  A0Icon,
+  AgentIcon,
+  CanvasIcon,
+  ChatIcon,
+  CounterIcon,
+  DocumentsIcon,
+  OrdersIcon,
+  RecoveryIcon,
+  VaultIcon,
+} from './demo-icons'
+
+export type Demo = {
+  href: string
+  name: string
+  icon: ReactNode
+  /** The demo fills the window and places the site nav itself. */
+  fullWindow?: true
+}
+
+/** Every demo, in the order the header menu and the home page list them. */
+export const demos: Demo[] = [
+  { href: '/a0', name: 'A0', icon: <A0Icon />, fullWindow: true },
+  { href: '/orders', name: 'Orders', icon: <OrdersIcon /> },
+  { href: '/chat', name: 'Chat', icon: <ChatIcon /> },
+  { href: '/agent', name: 'Agent', icon: <AgentIcon /> },
+  { href: '/canvas', name: 'Canvas', icon: <CanvasIcon /> },
+  { href: '/documents', name: 'Documents', icon: <DocumentsIcon /> },
+  { href: '/recovery', name: 'Recovery', icon: <RecoveryIcon /> },
+  { href: '/vault', name: 'Vault', icon: <VaultIcon /> },
+  { href: '/counter', name: 'Counter', icon: <CounterIcon /> },
+]

package/examples/playground/app/components/fast-link.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import {
+  cleanup,
+  createEvent,
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { FastLink } from './fast-link'
+
+const push = vi.fn<(href: string) => void>()
+vi.mock('next/navigation', () => ({ useRouter: () => ({ push }) }))
+
+// Whether each click reached the browser's default; then stop jsdom's
+// unimplemented navigation.
+let navigatedByClick: boolean[] = []
+const record = (event: MouseEvent): void => {
+  navigatedByClick.push(!event.defaultPrevented)
+  event.preventDefault()
+}
+beforeEach(() => {
+  push.mockReset()
+  navigatedByClick = []
+  document.addEventListener('click', record)
+})
+afterEach(() => {
+  document.removeEventListener('click', record)
+  cleanup()
+})
+
+const link = () => screen.getByRole('link', { name: 'Apps' })
+const press = (): void => {
+  const event = createEvent.pointerDown(link())
+  // jsdom has no PointerEvent, so the plain event gets its fields here.
+  Object.defineProperties(event, {
+    pointerType: { value: 'mouse' },
+    button: { value: 0 },
+  })
+  fireEvent(link(), event)
+}
+
+it('navigates on the press and swallows only that click', () => {
+  render(<FastLink href="/a0">Apps</FastLink>)
+  press()
+  expect(push).toHaveBeenCalledWith('/a0')
+  fireEvent.click(link(), { detail: 1 })
+  fireEvent.click(link(), { detail: 1 })
+  expect(navigatedByClick).toEqual([false, true])
+})
+
+it('lets a keyboard activation through after a press that never clicked', () => {
+  render(<FastLink href="/a0">Apps</FastLink>)
+  press()
+  // The pointer left before release, so no click followed the press.
+  fireEvent.click(link(), { detail: 0 })
+  expect(navigatedByClick).toEqual([true])
+})

package/examples/playground/app/components/fast-link.tsx

@@ -0,0 +1,55 @@
+'use client'
+import type { ComponentProps, ReactNode } from 'react'
+import { useRef } from 'react'
+import Link from 'next/link'
+import { useRouter } from 'next/navigation'
+
+/**
+ * A Link that navigates on mouse down instead of on click, which saves the
+ * press-to-release time. Anything else keeps the browser's behavior: modified
+ * presses (open in a new tab or window), other buttons, and touch, where a
+ * press can still turn into a scroll.
+ */
+export function FastLink({
+  href,
+  onPointerDown,
+  onClick,
+  ...props
+}: Omit<ComponentProps<typeof Link>, 'href'> & { href: string }): ReactNode {
+  const router = useRouter()
+  const navigated = useRef(false)
+  return (
+    <Link
+      href={href}
+      {...props}
+      onPointerDown={(event) => {
+        onPointerDown?.(event)
+        navigated.current = false
+        if (
+          event.defaultPrevented ||
+          event.pointerType !== 'mouse' ||
+          event.button !== 0 ||
+          event.metaKey ||
+          event.ctrlKey ||
+          event.shiftKey ||
+          event.altKey ||
+          props.target
+        )
+          return
+        navigated.current = true
+        router.push(href)
+      }}
+      onClick={(event) => {
+        onClick?.(event)
+        const pressed = navigated.current
+        navigated.current = false
+        // The press already navigated, so its click doesn't navigate again. A
+        // keyboard activation (detail 0) is never that click, even when an
+        // earlier press never got one.
+        if (pressed && event.detail !== 0) {
+          event.preventDefault()
+        }
+      }}
+    />
+  )
+}

package/examples/playground/app/components/site-header.tsx

@@ -0,0 +1,96 @@
+'use client'
+import type { FocusEvent, ReactNode } from 'react'
+import { useEffect, useRef } from 'react'
+import { FastLink } from './fast-link'
+import { usePathname } from 'next/navigation'
+import { Asterisk, ChevronDown } from 'lucide-react'
+import { type Demo, demos } from './demos'
+
+const close = (details: HTMLDetailsElement | null): void =>
+  details?.removeAttribute('open')
+
+function useCurrentDemo(): { pathname: string; current: Demo | undefined } {
+  const pathname = usePathname()
+  const current = demos.find(
+    (demo) => pathname === demo.href || pathname.startsWith(`${demo.href}/`),
+  )
+  return { pathname, current }
+}
+
+/** The site header, unless the demo lays out the whole window itself. */
+export function SiteHeader(): ReactNode {
+  const { current } = useCurrentDemo()
+  if (current?.fullWindow) return null
+  return (
+    <header className="site-header">
+      <SiteNav />
+    </header>
+  )
+}
+
+/** The wordmark, then a menu that switches between the demos. */
+export function SiteNav(): ReactNode {
+  const { pathname, current } = useCurrentDemo()
+  const menu = useRef<HTMLDetailsElement>(null)
+
+  useEffect(() => {
+    const outside = (event: PointerEvent): void => {
+      if (!menu.current?.contains(event.target as Node)) close(menu.current)
+    }
+    const escape = (event: KeyboardEvent): void => {
+      const details = menu.current
+      if (event.key !== 'Escape' || !details?.open) return
+      const hadFocus = details.contains(document.activeElement)
+      close(details)
+      if (hadFocus) details.querySelector('summary')?.focus()
+    }
+    document.addEventListener('pointerdown', outside)
+    document.addEventListener('keydown', escape)
+    return () => {
+      document.removeEventListener('pointerdown', outside)
+      document.removeEventListener('keydown', escape)
+    }
+  }, [])
+
+  const leave = (event: FocusEvent<HTMLDetailsElement>): void => {
+    if (!event.currentTarget.contains(event.relatedTarget)) {
+      close(event.currentTarget)
+    }
+  }
+
+  return (
+    <>
+      <FastLink href="/" className="brand">
+        <Asterisk size={18} strokeWidth={2.5} aria-hidden />
+        <span>A2</span>
+      </FastLink>
+      <details ref={menu} className="demo-menu" onBlur={leave}>
+        <summary>
+          <span aria-hidden>/</span>
+          <span className="sr-only">Demo:</span>
+          {current?.name ?? 'Playground'}
+          <ChevronDown size={13} aria-hidden />
+        </summary>
+        <nav aria-label="Demos">
+          {demos.map((demo) => (
+            <FastLink
+              key={demo.href}
+              href={demo.href}
+              aria-current={
+                demo !== current
+                  ? undefined
+                  : pathname === demo.href
+                    ? 'page'
+                    : 'true'
+              }
+              onClick={() => close(menu.current)}
+            >
+              {demo.name}
+              {demo === current ? <Asterisk size={12} aria-hidden /> : null}
+            </FastLink>
+          ))}
+        </nav>
+      </details>
+    </>
+  )
+}

package/examples/playground/app/counter/counter-client.tsx

@@ -34,9 +34,9 @@ export function CounterClient(): ReactNode {
         <span className="badge live">shared</span>
       </header>
       <p className="lede">
-        Every click appends one fact to a durable log. This page folds those
-        facts into a value on the server for the first paint, then keeps folding
-        the live stream in your browser.
+        Every click appends one fact to a durable log. The subscription starts
+        with the current value from the server, then keeps folding live events
+        in your browser.
       </p>
 
       <section className="counter-panel" aria-label="Shared counter controls">

package/examples/playground/app/counter/model.test.ts

@@ -1,6 +1,6 @@
 import type { ContractEvent } from 'experimental-a2'
 import { describe, expect, it } from 'vitest'
-import { counter, counterReducer } from './model'
+import { counter } from './model'
 
 type CounterEvents = typeof counter.events
 type CounterEvent<
@@ -27,8 +27,8 @@ describe('counter reducer', () => {
       event(2, 'incremented'),
       event(3, 'decremented'),
     ].reduce(
-      (current, nextEvent) => counterReducer.fold(current, nextEvent),
-      counterReducer.initialState,
+      (current, nextEvent) => counter.reducer.fold(current, nextEvent),
+      counter.reducer.initialState,
     )
 
     expect(state).toEqual({ value: 1 })

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

@@ -1,31 +1,21 @@
-import * as a2 from 'experimental-a2'
+import { contract } from 'experimental-a2'
 import { z } from 'zod'
 
-export const counter = a2.contract({
+const counterState = z.object({ value: z.number().int() })
+export type CounterState = z.output<typeof counterState>
+
+export const counter = contract({
   name: 'counter',
   events: {
     incremented: z.object({}),
     decremented: z.object({}),
   },
-})
-
-const counterState = z.object({ value: z.number().int() })
-
-export type CounterState = z.output<typeof counterState>
-
-export const counterReducer = counter
-  .reducer({
+  reducer: {
     name: 'counter-value',
     initialState: { value: 0 },
     stateSchema: counterState,
-  })
-  .fold((state, event) => {
-    switch (event.type) {
-      case 'incremented':
-        return { value: state.value + 1 }
-      case 'decremented':
-        return { value: state.value - 1 }
-      default:
-        return state
-    }
-  })
+    fold: (state, event) => ({
+      value: state.value + (event.type === 'incremented' ? 1 : -1),
+    }),
+  },
+})

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

@@ -1,23 +1,10 @@
 import type { ReactNode } from 'react'
-import { counterReducer } from './model'
-import { counterServer } from './server'
 import { CounterClient } from './counter-client'
 import { SessionProvider } from './session'
 
-export const dynamic = 'force-dynamic'
-
-const COUNTER_SESSION_ID = 'shared'
-
-export default async function CounterPage(): Promise<ReactNode> {
-  const session = counterServer.session(COUNTER_SESSION_ID)
-  const { state, index } = await session.state(counterReducer)
-
+export default function CounterPage(): ReactNode {
   return (
-    <SessionProvider
-      sessionId={COUNTER_SESSION_ID}
-      initialState={state}
-      initialIndex={index}
-    >
+    <SessionProvider sessionId="shared">
       <CounterClient />
     </SessionProvider>
   )

package/examples/playground/app/counter/session.ts

@@ -1,10 +1,10 @@
 'use client'
 import { createClient } from 'experimental-a2/client'
 import { createReact } from 'experimental-a2/react'
-import { counterReducer } from './model'
+import { counter } from './model'
 
 export const counterClient = createClient({
-  reducer: counterReducer,
+  contract: counter,
   api: '/counter/events',
 })
 

package/examples/playground/app/documents/[documentId]/code-editor.tsx

@@ -23,10 +23,14 @@ export function CodeMirrorEditor({
   const host = useRef<HTMLDivElement>(null)
   const view = useRef<EditorView | null>(null)
   const [editable] = useState(() => new Compartment())
+  const [theme] = useState(() => new Compartment())
 
   useEffect(() => {
     if (!host.current) return
 
+    // CodeMirror's own defaults (cursor, search panel, tooltips) follow the
+    // system theme along with the page.
+    const dark = window.matchMedia('(prefers-color-scheme: dark)')
     const body = doc.getText('body')
     const editor = new EditorView({
       parent: host.current,
@@ -34,6 +38,7 @@ export function CodeMirrorEditor({
         doc: body.toString(),
         extensions: [
           basicSetup,
+          theme.of(EditorView.darkTheme.of(dark.matches)),
           EditorView.lineWrapping,
           EditorView.contentAttributes.of({
             'aria-label': 'Document body',
@@ -60,12 +65,18 @@ export function CodeMirrorEditor({
       }),
     })
     view.current = editor
+    const followTheme = (): void =>
+      editor.dispatch({
+        effects: theme.reconfigure(EditorView.darkTheme.of(dark.matches)),
+      })
+    dark.addEventListener('change', followTheme)
 
     return () => {
+      dark.removeEventListener('change', followTheme)
       editor.destroy()
       view.current = null
     }
-  }, [doc, awareness, editable])
+  }, [doc, awareness, editable, theme])
 
   useEffect(() => {
     view.current?.dispatch({

package/examples/playground/app/documents/[documentId]/document-client.tsx

@@ -1,4 +1,5 @@
 'use client'
+import type { StateSnapshot } from 'experimental-a2'
 import type { CSSProperties, ChangeEvent, ReactNode } from 'react'
 import {
   useCallback,
@@ -25,11 +26,11 @@ const ADJECTIVES = ['Bright', 'Calm', 'Curious', 'Kind', 'Swift'] as const
 const ANIMALS = ['Fox', 'Heron', 'Otter', 'Panda', 'Wren'] as const
 const COLORS = ['teal', 'amber', 'blue', 'violet', 'rose'] as const
 const COLOR_HEX: Record<DocumentActor['color'], string> = {
-  teal: '#16836a',
-  amber: '#bd7917',
-  blue: '#3874c8',
-  violet: '#7956b6',
-  rose: '#bd5269',
+  teal: '#3ccf9f',
+  amber: '#f2b54b',
+  blue: '#6ea8fe',
+  violet: '#a98bff',
+  rose: '#ff7a93',
 }
 
 type SyncState = 'saved' | 'saving' | 'error'
@@ -154,12 +155,10 @@ function useYText(doc: Y.Doc, name: string): string {
 
 export function DocumentSession({
   documentId,
-  initialState,
-  initialIndex,
+  initial,
 }: {
   documentId: string
-  initialState: DocumentState
-  initialIndex: number
+  initial: StateSnapshot<DocumentState>
 }): ReactNode {
   // Minted before the provider connects, so the session carries its
   // participant id from the first frame. The rendered UI keeps its
@@ -172,8 +171,8 @@ export function DocumentSession({
     <SessionProvider
       sessionId={documentId}
       api="/documents/events"
-      initialState={initialState}
-      initialIndex={initialIndex}
+      initial={initial}
+
       {...(identity ? { participant: identity.id } : {})}
     >
       <DocumentClient documentId={documentId} />

package/examples/playground/app/documents/[documentId]/page.tsx

@@ -16,8 +16,7 @@ export default async function DocumentPage({
   return (
     <DocumentSession
       documentId={documentId}
-      initialState={state}
-      initialIndex={index}
+      initial={{ state: state, index: index }}
     />
   )
 }

package/examples/playground/app/documents/[documentId]/session.ts

@@ -1,7 +1,7 @@
 'use client'
 import { createReact } from 'experimental-a2/react'
-import { documentsReducer } from '../model'
+import { documents } from '../model'
 
 export const { SessionProvider, useSession } = createReact({
-  reducer: documentsReducer,
+  contract: documents,
 })