experimental-a2 0.8.0 → 0.9.0

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

@@ -0,0 +1,525 @@
+'use client'
+import type { CSSProperties, ChangeEvent, ReactNode } from 'react'
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react'
+import * as Y from 'yjs'
+import {
+  Awareness,
+  applyAwarenessUpdate,
+  encodeAwarenessUpdate,
+} from 'y-protocols/awareness'
+import { ConnectionPill } from '@/app/components/connection-pill'
+import type { DocumentActor, DocumentState } from '../model'
+import { CodeMirrorEditor } from './code-editor'
+import { SessionProvider, useSession } from './session'
+
+const EDIT_DEBOUNCE_MS = 120
+const A2_REMOTE_ORIGIN = Symbol('a2-remote')
+const ACTOR_KEY = 'a2-example-document-actor'
+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',
+}
+
+type SyncState = 'saved' | 'saving' | 'error'
+
+function randomItem<T>(values: readonly T[], value: number): T {
+  return values[value % values.length]!
+}
+
+function isActor(value: unknown): value is DocumentActor {
+  if (!value || typeof value !== 'object') return false
+  const actor = value as Record<string, unknown>
+  return (
+    typeof actor['id'] === 'string' &&
+    typeof actor['name'] === 'string' &&
+    typeof actor['color'] === 'string' &&
+    COLORS.includes(actor['color'] as DocumentActor['color'])
+  )
+}
+
+/** One roll per page load, shared by the session wrapper and the
+ * toolbar. The id is the stable per-tab identity (contributor history
+ * stays one person); name and color re-roll on every refresh. */
+let loadedActor: DocumentActor | null = null
+
+function loadActor(): DocumentActor {
+  if (loadedActor) return loadedActor
+  let id: string | null = null
+  try {
+    const stored = sessionStorage.getItem(ACTOR_KEY)
+    if (stored) {
+      const parsed: unknown = JSON.parse(stored)
+      if (isActor(parsed)) id = parsed.id
+    }
+  } catch {
+    // Storage may be unavailable; a tab-local identity still works.
+  }
+
+  const random = new Uint32Array(3)
+  crypto.getRandomValues(random)
+  const actor: DocumentActor = {
+    id: id ?? crypto.randomUUID(),
+    name: `${randomItem(ADJECTIVES, random[0]!)} ${randomItem(ANIMALS, random[1]!)}`,
+    color: randomItem(COLORS, random[2]!),
+  }
+  try {
+    sessionStorage.setItem(ACTOR_KEY, JSON.stringify(actor))
+  } catch {
+    // The in-memory identity is enough for this visit.
+  }
+  loadedActor = actor
+  return actor
+}
+
+function updateToBase64(update: Uint8Array): string {
+  let binary = ''
+  const chunkSize = 0x8000
+  for (let start = 0; start < update.length; start += chunkSize) {
+    binary += String.fromCharCode(...update.subarray(start, start + chunkSize))
+  }
+  return btoa(binary)
+}
+
+function updateFromBase64(encoded: string): Uint8Array {
+  const binary = atob(encoded)
+  const update = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i += 1) {
+    update[i] = binary.charCodeAt(i)
+  }
+  return update
+}
+
+function createDocument(updates: readonly string[]): Y.Doc {
+  const doc = new Y.Doc()
+  for (const update of updates) {
+    Y.applyUpdate(doc, updateFromBase64(update), A2_REMOTE_ORIGIN)
+  }
+  return doc
+}
+
+/** Translate the controlled title input into a minimal Y.Text splice. */
+function replaceText(text: Y.Text, next: string): void {
+  const current = text.toString()
+  if (current === next) return
+
+  let prefix = 0
+  while (
+    prefix < current.length &&
+    prefix < next.length &&
+    current[prefix] === next[prefix]
+  ) {
+    prefix += 1
+  }
+
+  let suffix = 0
+  while (
+    suffix < current.length - prefix &&
+    suffix < next.length - prefix &&
+    current[current.length - 1 - suffix] === next[next.length - 1 - suffix]
+  ) {
+    suffix += 1
+  }
+
+  const deleteCount = current.length - prefix - suffix
+  const insertion = next.slice(prefix, next.length - suffix)
+  if (deleteCount > 0) text.delete(prefix, deleteCount)
+  if (insertion) text.insert(prefix, insertion)
+}
+
+function useYText(doc: Y.Doc, name: string): string {
+  const [text] = useState(() => doc.getText(name))
+  const subscribe = useCallback(
+    (notify: () => void) => {
+      const observer = (): void => notify()
+      text.observe(observer)
+      return () => text.unobserve(observer)
+    },
+    [text],
+  )
+  const snapshot = useCallback(() => text.toString(), [text])
+  return useSyncExternalStore(subscribe, snapshot, snapshot)
+}
+
+export function DocumentSession({
+  documentId,
+  initialState,
+  initialIndex,
+}: {
+  documentId: string
+  initialState: DocumentState
+  initialIndex: number
+}): ReactNode {
+  // Minted before the provider connects, so the session carries its
+  // participant id from the first frame. The rendered UI keeps its
+  // own post-mount actor state; loadActor reads the same storage key,
+  // so both are one identity.
+  const [identity] = useState(() =>
+    typeof window === 'undefined' ? null : loadActor(),
+  )
+  return (
+    <SessionProvider
+      sessionId={documentId}
+      api="/documents/events"
+      initialState={initialState}
+      initialIndex={initialIndex}
+      {...(identity ? { participant: identity.id } : {})}
+    >
+      <DocumentClient documentId={documentId} />
+    </SessionProvider>
+  )
+}
+
+export function DocumentClient({
+  documentId,
+}: {
+  documentId: string
+}): ReactNode {
+  const { state, push, events, index, connection, presence, setPresence } =
+    useSession()
+  const [doc] = useState(() => createDocument(state.updates))
+  const title = useYText(doc, 'title')
+  const body = useYText(doc, 'body')
+  const [actor, setActor] = useState<DocumentActor | null>(null)
+  const [syncState, setSyncState] = useState<SyncState>('saved')
+  const [error, setError] = useState<string | null>(null)
+  const [copied, setCopied] = useState(false)
+  const appliedUpdates = useRef(new Set(state.updates))
+  const pendingUpdates = useRef<Uint8Array[]>([])
+  const flushing = useRef(false)
+  const flushTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const actorRef = useRef(actor)
+  const pushRef = useRef(push)
+  const flushRef = useRef<() => Promise<void>>(async () => undefined)
+  const queueUpdateRef = useRef<(update: Uint8Array) => void>(() => undefined)
+
+  actorRef.current = actor
+  pushRef.current = push
+
+  useEffect(() => setActor(loadActor()), [])
+
+  useEffect(() => {
+    for (const update of state.updates) {
+      if (appliedUpdates.current.has(update)) continue
+      Y.applyUpdate(doc, updateFromBase64(update), A2_REMOTE_ORIGIN)
+      appliedUpdates.current.add(update)
+    }
+  }, [doc, state.updates])
+
+  // ── awareness × presence ── Yjs's second protocol rides A2's second
+  // plane. The Awareness instance is the local API (yCollab renders
+  // remote selections from it); A2 presence is its only transport.
+  const [awareness] = useState(() => new Awareness(doc))
+  useEffect(() => () => awareness.destroy(), [awareness])
+
+  // The cursor label y-codemirror shows: LWW state, so a rename here
+  // repaints the caret in every tab. Blur empties the chair: a blurred
+  // window or hidden tab clears the whole local state, so peers drop
+  // the caret immediately instead of waiting out the protocol's 30s
+  // timeout; focus re-seats the identity, and the next editor update
+  // re-adds the caret.
+  useEffect(() => {
+    if (!actor) return
+    const hex = COLOR_HEX[actor.color]
+    // setLocalState, not setLocalStateField: the field setter
+    // silently no-ops while the state is null, and blur nulls it —
+    // this must revive the seat from nothing.
+    const seat = (): void => {
+      awareness.setLocalState({
+        ...awareness.getLocalState(),
+        user: {
+          name: actor.name.trim() || 'Anonymous editor',
+          color: hex,
+          colorLight: `${hex}33`,
+        },
+      })
+    }
+    const clear = (): void => awareness.setLocalState(null)
+    const onVisibility = (): void => {
+      if (document.visibilityState === 'hidden') clear()
+      else seat()
+    }
+    seat()
+    window.addEventListener('blur', clear)
+    window.addEventListener('focus', seat)
+    window.addEventListener('beforeunload', clear)
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      window.removeEventListener('blur', clear)
+      window.removeEventListener('focus', seat)
+      window.removeEventListener('beforeunload', clear)
+      document.removeEventListener('visibilitychange', onVisibility)
+    }
+  }, [awareness, actor])
+
+  // Outbound: any local awareness change (selection moved, field set,
+  // the protocol's periodic keep-alive) publishes the encoded update as
+  // presence — the client's send throttle coalesces caret storms, and
+  // every set refreshes the A2 TTL alongside awareness's own timeout.
+  useEffect(() => {
+    if (!actor) return
+    const publish = (_changes: unknown, origin: unknown): void => {
+      if (origin === A2_REMOTE_ORIGIN) return
+      setPresence({
+        awareness: updateToBase64(
+          encodeAwarenessUpdate(awareness, [doc.clientID]),
+        ),
+      })
+    }
+    awareness.on('update', publish)
+    return () => awareness.off('update', publish)
+  }, [awareness, doc, actor, setPresence])
+
+  // Inbound: foreign participants' values feed the same instance.
+  // applyAwarenessUpdate dedupes by the protocol's own clocks, so
+  // re-applying an unchanged value is a no-op; vanished peers expire
+  // via awareness's 30s timeout.
+  useEffect(() => {
+    for (const [participant, fields] of Object.entries(presence)) {
+      if (participant === actor?.id) continue
+      const encoded = fields.awareness?.value
+      if (encoded) {
+        applyAwarenessUpdate(
+          awareness,
+          updateFromBase64(encoded),
+          A2_REMOTE_ORIGIN,
+        )
+      }
+    }
+  }, [presence, awareness, actor])
+
+  useEffect(
+    () => () => {
+      if (flushTimer.current) clearTimeout(flushTimer.current)
+    },
+    [],
+  )
+
+  flushRef.current = async (): Promise<void> => {
+    const currentActor = actorRef.current
+    if (
+      flushing.current ||
+      !currentActor ||
+      pendingUpdates.current.length === 0
+    ) {
+      return
+    }
+
+    if (flushTimer.current) clearTimeout(flushTimer.current)
+    flushTimer.current = null
+    const batch = pendingUpdates.current.splice(0)
+    const update = Y.mergeUpdates(batch)
+    const eventActor = {
+      ...currentActor,
+      name: currentActor.name.trim() || 'Anonymous editor',
+    }
+    flushing.current = true
+    setSyncState('saving')
+    setError(null)
+
+    try {
+      await pushRef.current({
+        type: 'document.updated',
+        payload: { update: updateToBase64(update), actor: eventActor },
+      })
+      flushing.current = false
+      if (pendingUpdates.current.length > 0) {
+        void flushRef.current()
+      } else {
+        setSyncState('saved')
+      }
+    } catch (err) {
+      // Keep the failed CRDT bytes. Retry merges them with any newer
+      // edits, so dependencies are never sent out of order.
+      pendingUpdates.current.unshift(update)
+      flushing.current = false
+      setSyncState('error')
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  const queueUpdate = (update: Uint8Array): void => {
+    pendingUpdates.current.push(update)
+    setSyncState('saving')
+    if (flushTimer.current) clearTimeout(flushTimer.current)
+    flushTimer.current = setTimeout(
+      () => void flushRef.current(),
+      EDIT_DEBOUNCE_MS,
+    )
+  }
+  queueUpdateRef.current = queueUpdate
+
+  useEffect(() => {
+    const publishLocalUpdate = (update: Uint8Array, origin: unknown): void => {
+      if (origin !== A2_REMOTE_ORIGIN) queueUpdateRef.current(update)
+    }
+    doc.on('update', publishLocalUpdate)
+    return () => doc.off('update', publishLocalUpdate)
+  }, [doc])
+
+  const editTitle = (next: string): void => {
+    if (!actor) return
+    doc.transact(() => replaceText(doc.getText('title'), next), actor.id)
+  }
+
+  const rename = (event: ChangeEvent<HTMLInputElement>): void => {
+    const name = event.target.value.slice(0, 40)
+    setActor((current) => (current ? { ...current, name } : current))
+  }
+
+  const saveActor = (): void => {
+    if (!actor) return
+    const normalized = actor.name.trim() || 'Anonymous editor'
+    const next = { ...actor, name: normalized }
+    setActor(next)
+    try {
+      sessionStorage.setItem(ACTOR_KEY, JSON.stringify(next))
+    } catch {
+      // Keep the identity in memory when storage is unavailable.
+    }
+  }
+
+  const copyLink = async (): Promise<void> => {
+    try {
+      await navigator.clipboard.writeText(window.location.href)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1500)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  const collaborators = state.contributors.toReversed()
+
+  return (
+    <article className="document-page">
+      <header className="session-header document-header">
+        <div>
+          <p className="eyebrow">Multiplayer document</p>
+          <h1>
+            <code>{documentId}</code>
+          </h1>
+        </div>
+        <ConnectionPill connection={connection} />
+        <button
+          className="secondary compact"
+          type="button"
+          onClick={() => void copyLink()}
+        >
+          {copied ? 'Copied!' : 'Copy link'}
+        </button>
+      </header>
+
+      <div className="editor-toolbar">
+        <label className="identity-field">
+          You are
+          <input
+            value={actor?.name ?? ''}
+            onChange={rename}
+            onBlur={saveActor}
+            disabled={!actor}
+            placeholder="Joining…"
+          />
+        </label>
+        <div className="collaborators" aria-label="Document contributors">
+          {collaborators.length === 0 ? (
+            <span className="hint">No durable edits yet</span>
+          ) : (
+            collaborators.map((contributor) => (
+              <span className="collaborator" key={contributor.id}>
+                <span
+                  className="collaborator-dot"
+                  style={
+                    {
+                      '--collaborator-color': COLOR_HEX[contributor.color],
+                    } as CSSProperties
+                  }
+                />
+                {contributor.id === actor?.id ? actor.name : contributor.name}
+                {contributor.id === actor?.id ? ' (you)' : ''}
+              </span>
+            ))
+          )}
+        </div>
+      </div>
+
+      <section className="document-editor" aria-label="Collaborative editor">
+        <input
+          className="document-title"
+          aria-label="Document title"
+          value={title}
+          onChange={(event) => editTitle(event.target.value)}
+          placeholder="Untitled document"
+          disabled={!actor}
+        />
+        <CodeMirrorEditor doc={doc} awareness={awareness} disabled={!actor} />
+        <footer className="editor-status" aria-live="polite">
+          <span className={`sync-state ${syncState}`}>
+            {syncState === 'saved'
+              ? `Saved through log position ${index}`
+              : syncState === 'saving'
+                ? 'Saving…'
+                : 'Local edits not saved'}
+          </span>
+          <span>{body.length.toLocaleString()} characters</span>
+          {syncState === 'error' ? (
+            <button
+              className="secondary compact"
+              type="button"
+              onClick={() => void flushRef.current()}
+            >
+              Retry
+            </button>
+          ) : null}
+        </footer>
+      </section>
+      {error ? <p className="error">{error}</p> : null}
+
+      <section>
+        <h2>Durable update log</h2>
+        <p className="hint">
+          {state.updates.length} update{' '}
+          {state.updates.length === 1 ? 'batch' : 'batches'} folded into this
+          document.
+        </p>
+        {events.length === 0 ? (
+          <p className="hint">
+            No new updates observed since this tab connected. Start typing to
+            append one.
+          </p>
+        ) : (
+          <ol className="feed document-feed">
+            {events.map((event) => (
+              <li key={event.id}>
+                <span className="idx">#{event.index}</span>
+                <span className="type">{event.payload.actor.name}</span>
+                <span className="payload">
+                  Yjs update ·{' '}
+                  {Math.ceil((event.payload.update.length * 3) / 4)} bytes
+                </span>
+                <time dateTime={event.createdAt.toISOString()}>
+                  {event.createdAt.toLocaleTimeString()}
+                </time>
+              </li>
+            ))}
+          </ol>
+        )}
+        <p className="frontier">
+          A2 orders and replays opaque CRDT bytes; Yjs materializes the same
+          title and body in every browser.
+        </p>
+      </section>
+    </article>
+  )
+}

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

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react'
+import { documentsReducer } from '../model'
+import { documentsServer } from '../server'
+import { DocumentSession } from './document-client'
+
+export default async function DocumentPage({
+  params,
+}: {
+  params: Promise<{ documentId: string }>
+}): Promise<ReactNode> {
+  const { documentId } = await params
+  const { state, index } = await documentsServer
+    .session(documentId)
+    .state(documentsReducer)
+
+  return (
+    <DocumentSession
+      documentId={documentId}
+      initialState={state}
+      initialIndex={index}
+    />
+  )
+}

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

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

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

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

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

@@ -0,0 +1,55 @@
+import * as a2 from 'experimental-a2'
+import { z } from 'zod'
+
+const paletteSchema = z.enum(['teal', 'amber', 'blue', 'violet', 'rose'])
+
+export const documentActorSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1).max(40),
+  color: paletteSchema,
+})
+
+export type DocumentActor = z.output<typeof documentActorSchema>
+
+export const documents = a2.contract({
+  name: 'documents',
+  events: {
+    'document.updated': z.object({
+      update: z.string().min(1),
+      actor: documentActorSchema,
+    }),
+  },
+  presence: {
+    awareness: z.string().min(1),
+  },
+})
+
+const documentState = z.object({
+  updates: z.array(z.string()),
+  contributors: z.array(documentActorSchema),
+})
+
+export type DocumentState = z.output<typeof documentState>
+
+export const documentsReducer = documents
+  .reducer({
+    name: 'document-updates',
+    initialState: { updates: [], contributors: [] },
+    stateSchema: documentState,
+  })
+  .fold((state, event) => {
+    switch (event.type) {
+      case 'document.updated':
+        return {
+          updates: [...state.updates, event.payload.update],
+          contributors: [
+            ...state.contributors.filter(
+              (actor) => actor.id !== event.payload.actor.id,
+            ),
+            event.payload.actor,
+          ],
+        }
+      default:
+        return state
+    }
+  })

package/examples/playground/app/documents/open-document.tsx

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

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

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react'
+import { OpenDocument } from './open-document'
+
+export default function DocumentsPage(): ReactNode {
+  return (
+    <article>
+      <h1>A multiplayer document, backed by the log</h1>
+      <p className="lede">
+        CodeMirror binds directly to a shared Y.Text. Every edit becomes a
+        compact Yjs update in an A2 session: open the document URL in another
+        tab, type in both, and watch the CRDT merge both editors over the same
+        live event stream used by the other demos.
+      </p>
+      <OpenDocument />
+      <p className="hint">
+        A2 provides durable ordering, optimistic pushes, and reconnecting SSE.
+        Yjs provides the conflict-free text model. Presence is deliberately not
+        persisted: the names below mean contributors, not who is online.
+      </p>
+    </article>
+  )
+}

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

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