experimental-a2 0.8.0 → 0.8.1

package/examples/playground/app/canvas/[canvasId]/canvas-client.tsx

@@ -0,0 +1,682 @@
+'use client'
+import type {
+  CSSProperties,
+  PointerEvent as ReactPointerEvent,
+  MouseEvent as ReactMouseEvent,
+  ReactNode,
+} from 'react'
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react'
+import type { CanvasShape, CanvasState, PaletteColor } from '../model'
+import { ConnectionPill } from '@/app/components/connection-pill'
+import { confirmedCanvasEventsSince, replayCanvas } from './canvas-replay'
+import { SessionProvider, useSession } from './session'
+
+const VIEW_W = 960
+const VIEW_H = 540
+/** How long a cursor stays painted after its last move — render-time
+ * logic against Date.now(); presence is not folded state. */
+const CURSOR_TTL_MS = 4_000
+
+const IDENTITY_KEY = 'a2-playground-canvas-identity'
+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<PaletteColor, string> = {
+  teal: '#16836a',
+  amber: '#bd7917',
+  blue: '#3874c8',
+  violet: '#7956b6',
+  rose: '#bd5269',
+}
+
+/** The tab's identity: an opaque participant id, plus the name and
+ * color it publishes as `profile` presence. */
+type CanvasIdentity = { id: string; name: string; color: PaletteColor }
+
+const isColor = (value: string | undefined): value is PaletteColor =>
+  value !== undefined && (COLORS as readonly string[]).includes(value)
+
+function isIdentity(value: unknown): value is CanvasIdentity {
+  if (!value || typeof value !== 'object') return false
+  const identity = value as Record<string, unknown>
+  return (
+    typeof identity['id'] === 'string' &&
+    typeof identity['name'] === 'string' &&
+    typeof identity['color'] === 'string' &&
+    isColor(identity['color'])
+  )
+}
+
+function loadIdentity(): CanvasIdentity {
+  // The id is the stable per-tab identity; name and color re-roll on
+  // every load — refreshing hands you a new guise.
+  let id: string | null = null
+  try {
+    const stored = sessionStorage.getItem(IDENTITY_KEY)
+    if (stored) {
+      const parsed: unknown = JSON.parse(stored)
+      if (isIdentity(parsed)) id = parsed.id
+    }
+  } catch {
+    // Storage may be unavailable; a tab-local identity still works.
+  }
+  const random = new Uint32Array(3)
+  crypto.getRandomValues(random)
+  const identity: CanvasIdentity = {
+    id: id ?? crypto.randomUUID(),
+    name: `${ADJECTIVES[random[0]! % ADJECTIVES.length]!} ${ANIMALS[random[1]! % ANIMALS.length]!}`,
+    color: COLORS[random[2]! % COLORS.length]!,
+  }
+  try {
+    sessionStorage.setItem(IDENTITY_KEY, JSON.stringify(identity))
+  } catch {
+    // The in-memory identity is enough for this visit.
+  }
+  return identity
+}
+
+let tabIdentity: CanvasIdentity | null = null
+const subscribeToIdentity = (): (() => void) => () => {}
+const serverIdentitySnapshot = (): null => null
+const clientIdentitySnapshot = (): CanvasIdentity | null => {
+  if (typeof window === 'undefined') return null
+  tabIdentity ??= loadIdentity()
+  return tabIdentity
+}
+
+const useCanvasIdentity = (): CanvasIdentity | null =>
+  useSyncExternalStore(
+    subscribeToIdentity,
+    clientIdentitySnapshot,
+    serverIdentitySnapshot,
+  )
+
+/** A participant whose `profile` hasn't arrived (TTL'd out, or the
+ * snapshot raced the patch) still paints — neutrally. */
+const GUEST_LABEL = { name: 'guest', color: 'teal' } as const
+
+const labelOf = (fields: {
+  profile?: { value: { name: string; color: PaletteColor } }
+}): { name: string; color: PaletteColor } =>
+  fields.profile?.value ?? GUEST_LABEL
+
+/**
+ * Remote motion chases the newest sample instead of replaying the
+ * past: exponential convergence with a ~45ms time constant, so a
+ * flick reads as a flick and bursty arrivals never build a playback
+ * backlog. Writes the transform imperatively, no React re-render per
+ * frame; the loop parks when converged. Local input never goes
+ * through here: your own cursor and drag render straight from
+ * pointer state.
+ */
+const CHASE_TAU_MS = 45
+
+function useSmoothPoint(
+  x: number,
+  y: number,
+): (el: SVGGElement | null) => void {
+  const elRef = useRef<SVGGElement | null>(null)
+  const s = useRef({ x, y, tx: x, ty: y, raf: 0, lastT: 0 }).current
+
+  const paint = useCallback(() => {
+    elRef.current?.setAttribute('transform', `translate(${s.x} ${s.y})`)
+  }, [s])
+
+  useLayoutEffect(() => {
+    s.tx = x
+    s.ty = y
+    if (s.raf !== 0) return
+    s.lastT = performance.now()
+    const step = (now: number): void => {
+      const k = 1 - Math.exp(-(now - s.lastT) / CHASE_TAU_MS)
+      s.lastT = now
+      s.x += (s.tx - s.x) * k
+      s.y += (s.ty - s.y) * k
+      if (Math.abs(s.tx - s.x) < 0.5 && Math.abs(s.ty - s.y) < 0.5) {
+        s.x = s.tx
+        s.y = s.ty
+        s.raf = 0
+      } else {
+        s.raf = requestAnimationFrame(step)
+      }
+      paint()
+    }
+    s.raf = requestAnimationFrame(step)
+  }, [s, paint, x, y])
+
+  useLayoutEffect(
+    () => () => {
+      if (s.raf !== 0) cancelAnimationFrame(s.raf)
+      s.raf = 0
+    },
+    [s],
+  )
+
+  // The first paint lands with the mount — no flash at the SVG origin.
+  return useCallback(
+    (el: SVGGElement | null) => {
+      elRef.current = el
+      if (el) paint()
+    },
+    [paint],
+  )
+}
+
+function Smoothed({
+  x,
+  y,
+  className,
+  children,
+}: {
+  x: number
+  y: number
+  className?: string
+  children: ReactNode
+}): ReactNode {
+  const ref = useSmoothPoint(x, y)
+  return (
+    <g ref={ref} className={className}>
+      {children}
+    </g>
+  )
+}
+
+export function CanvasSession({
+  canvasId,
+  initialState,
+  initialIndex,
+}: {
+  canvasId: string
+  initialState: CanvasState
+  initialIndex: number
+}): ReactNode {
+  // The server snapshot is null so hydration matches exactly. The
+  // browser snapshot then mints one stable tab identity before presence
+  // becomes interactive.
+  const identity = useCanvasIdentity()
+  return (
+    <SessionProvider
+      sessionId={canvasId}
+      initialState={initialState}
+      initialIndex={initialIndex}
+      {...(identity ? { participant: identity.id } : {})}
+    >
+      <CanvasClient
+        key={`${canvasId}:${initialIndex}:${identity?.id ?? 'joining'}`}
+        canvasId={canvasId}
+        identity={identity}
+        replayBaseState={initialState}
+        replayBaseIndex={initialIndex}
+      />
+    </SessionProvider>
+  )
+}
+
+type Drag = {
+  shapeId: string
+  /** Pointer offset inside the shape, so it doesn't jump to the cursor. */
+  dx: number
+  dy: number
+  /** Where the pointer went down — a few stray pixels is still a click. */
+  sx: number
+  sy: number
+  x: number
+  y: number
+  moved: boolean
+}
+
+const clamp = (value: number, max: number): number =>
+  Math.min(Math.max(value, 0), max)
+
+function CanvasClient({
+  canvasId,
+  identity,
+  replayBaseState,
+  replayBaseIndex,
+}: {
+  canvasId: string
+  identity: CanvasIdentity | null
+  replayBaseState: CanvasState
+  replayBaseIndex: number
+}): ReactNode {
+  const { state, events, index, connection, push, presence, setPresence } =
+    useSession()
+  const svgRef = useRef<SVGSVGElement>(null)
+  const [profile, setProfile] = useState(() =>
+    identity ? { name: identity.name, color: identity.color } : null,
+  )
+  const [drag, setDrag] = useState<Drag | null>(null)
+  /** null = live; a number pins the scene to a received-event prefix. */
+  const [scrub, setScrub] = useState<number | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [copied, setCopied] = useState(false)
+  /** Render-time clock for cursor expiry — never enters the fold. */
+  const [now, setNow] = useState(() => Date.now())
+
+  const live = scrub === null
+  const replayEvents = useMemo(
+    () => confirmedCanvasEventsSince(events, replayBaseIndex, index),
+    [events, replayBaseIndex, index],
+  )
+  const replayThrough =
+    scrub === null ? replayEvents.length : Math.min(scrub, replayEvents.length)
+  // Start at the server-rendered fold, then replay only the tail this
+  // client observed. Loading the page never requires the historical log.
+  const scene = useMemo(
+    () =>
+      live ? state : replayCanvas(replayBaseState, replayEvents, replayThrough),
+    [live, state, replayEvents, replayThrough, replayBaseState],
+  )
+
+  // Identity metadata is presence: published on join and on every
+  // rename. Last-writer-wins per field, so a new name repaints in
+  // every open tab — nothing durable to migrate.
+  useEffect(() => {
+    if (!identity || !profile) return
+    const name = profile.name.trim()
+    if (!name) return
+    setPresence({ profile: { name, color: profile.color } })
+    try {
+      sessionStorage.setItem(
+        IDENTITY_KEY,
+        JSON.stringify({ id: identity.id, name, color: profile.color }),
+      )
+    } catch {
+      // The in-memory identity is enough for this visit.
+    }
+  }, [identity, profile, setPresence])
+
+  // A blurred window is nobody at the canvas: clear the ephemeral
+  // fields; the next pointer move repaints them.
+  useEffect(() => {
+    if (!identity) return
+    const clear = (): void => setPresence({ cursor: null, dragging: null })
+    const onVisibility = (): void => {
+      if (document.visibilityState === 'hidden') clear()
+    }
+    window.addEventListener('blur', clear)
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      window.removeEventListener('blur', clear)
+      document.removeEventListener('visibilitychange', onVisibility)
+    }
+  }, [identity, setPresence])
+
+  const others = Object.entries(presence).filter(([id]) => id !== identity?.id)
+
+  // Tick once a second while any cursor could expire.
+  const hasCursors = others.some(([, fields]) => fields.cursor)
+  useEffect(() => {
+    if (!hasCursors) return
+    const timer = setInterval(() => setNow(Date.now()), 1_000)
+    return () => clearInterval(timer)
+  }, [hasCursors])
+
+  const cursors = live
+    ? others.flatMap(([id, fields]) => {
+        const cursor = fields.cursor
+        if (!cursor || now - cursor.at.getTime() > CURSOR_TTL_MS) return []
+        return [{ id, ...cursor.value, ...labelOf(fields) }]
+      })
+    : [] // durable events replay; presence has no historical state
+
+  // A ghost is dead once the log has moved past it: show `dragging`
+  // only while its `seen` frontier reaches the shape's durable
+  // `movedAt` (/guides/presence#reconciling-the-planes-seen).
+  const ghosts = new Map<
+    string,
+    { x: number; y: number; color: PaletteColor }
+  >()
+  if (live) {
+    for (const [, fields] of others) {
+      const dragging = fields.dragging
+      if (!dragging) continue
+      const shape = state.shapes[dragging.value.shapeId]
+      if (!shape || dragging.seen < shape.movedAt) continue
+      ghosts.set(dragging.value.shapeId, {
+        x: dragging.value.x,
+        y: dragging.value.y,
+        color: labelOf(fields).color,
+      })
+    }
+  }
+
+  const toPoint = (e: { clientX: number; clientY: number }) => {
+    const rect = svgRef.current!.getBoundingClientRect()
+    return {
+      x: Math.round(((e.clientX - rect.left) / rect.width) * VIEW_W),
+      y: Math.round(((e.clientY - rect.top) / rect.height) * VIEW_H),
+    }
+  }
+
+  const pushShape = (event: Parameters<typeof push>[0]): void => {
+    setError(null)
+    push(event).catch((err: unknown) =>
+      setError(err instanceof Error ? err.message : String(err)),
+    )
+  }
+
+  const createShape = (e: ReactMouseEvent<SVGSVGElement>): void => {
+    // detail > 1 is the second click of a double-click; target check
+    // skips clicks that started on a shape.
+    if (!live || e.target !== e.currentTarget || e.detail !== 1) return
+    const p = toPoint(e)
+    const random = new Uint32Array(4)
+    crypto.getRandomValues(random)
+    const w = 70 + (random[2]! % 71)
+    const h = 50 + (random[3]! % 61)
+    pushShape({
+      type: 'shape.created',
+      payload: {
+        id: crypto.randomUUID().slice(0, 8),
+        kind: random[0]! % 2 ? 'rect' : 'ellipse',
+        x: clamp(p.x - Math.round(w / 2), VIEW_W - w),
+        y: clamp(p.y - Math.round(h / 2), VIEW_H - h),
+        w,
+        h,
+        color: COLORS[random[1]! % COLORS.length]!,
+      },
+    })
+  }
+
+  const startDrag = (
+    e: ReactPointerEvent<SVGGraphicsElement>,
+    shape: CanvasShape,
+  ): void => {
+    if (!live || !identity) return
+    e.currentTarget.setPointerCapture(e.pointerId)
+    const p = toPoint(e)
+    setDrag({
+      shapeId: shape.id,
+      dx: p.x - shape.x,
+      dy: p.y - shape.y,
+      sx: p.x,
+      sy: p.y,
+      x: shape.x,
+      y: shape.y,
+      moved: false,
+    })
+  }
+
+  const onPointerMove = (e: ReactPointerEvent<SVGSVGElement>): void => {
+    if (!live || !identity) return
+    const p = toPoint(e)
+    if (drag) {
+      const shape = state.shapes[drag.shapeId]
+      const x = clamp(p.x - drag.dx, VIEW_W - (shape?.w ?? 0))
+      const y = clamp(p.y - drag.dy, VIEW_H - (shape?.h ?? 0))
+      const moved =
+        drag.moved || Math.abs(p.x - drag.sx) + Math.abs(p.y - drag.sy) > 3
+      setDrag({ ...drag, x, y, moved })
+      // One patch, both fields: the ghost everyone else renders, and
+      // the cursor riding along. Coalesced on the wire by the client.
+      setPresence({
+        cursor: p,
+        dragging: { shapeId: drag.shapeId, x, y },
+      })
+    } else {
+      setPresence({ cursor: p })
+    }
+  }
+
+  const endDrag = (): void => {
+    if (!drag || !identity) return
+    setDrag(null)
+    // Facts decide; presence repaints. The seen rule kills the ghost
+    // the moment shape.moved arrives, so an explicit dragging-null
+    // would only race the event across planes — and losing that race
+    // rubber-bands the shape to its pre-drag position. Clear presence
+    // only when no event is coming: a sub-threshold click, or a
+    // rejected push.
+    if (!drag.moved) {
+      setPresence({ dragging: null })
+      return
+    }
+    setError(null)
+    push({
+      type: 'shape.moved',
+      payload: { id: drag.shapeId, x: drag.x, y: drag.y },
+    }).catch((err: unknown) => {
+      setPresence({ dragging: null })
+      setError(err instanceof Error ? err.message : String(err))
+    })
+  }
+
+  const onPointerLeave = (): void => {
+    if (!identity || drag) return
+    setPresence({ cursor: null })
+  }
+
+  const deleteShape = (shapeId: string): void => {
+    if (!live) return
+    pushShape({
+      type: 'shape.deleted',
+      payload: { id: shapeId },
+    })
+  }
+
+  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 shapes = Object.values(scene.shapes)
+
+  return (
+    <article>
+      <header className="session-header document-header">
+        <div>
+          <p className="eyebrow">Multiplayer canvas</p>
+          <h1>
+            <code>{canvasId}</code>
+          </h1>
+        </div>
+        <ConnectionPill connection={connection} />
+        <span className="badge">
+          {shapes.length} {shapes.length === 1 ? 'shape' : 'shapes'}
+        </span>
+        <button
+          className="secondary compact"
+          type="button"
+          onClick={() => void copyLink()}
+        >
+          {copied ? 'Copied!' : 'Copy link'}
+        </button>
+      </header>
+      <p className="hint">
+        Click to create a shape, drag to move it, double-click to delete. Open
+        the same URL in a second tab: shapes are durable events; cursors and
+        drag ghosts are presence, never stored. Rename yourself below and every
+        tab repaints — your profile is presence too. Deployed, pushes and
+        presence ride one WebSocket; in dev the same route serves SSE.
+      </p>
+
+      <div className="canvas-toolbar">
+        <label className="identity-field">
+          You are
+          <input
+            value={profile?.name ?? ''}
+            onChange={(e) =>
+              setProfile((current) =>
+                current
+                  ? { ...current, name: e.target.value.slice(0, 40) }
+                  : current,
+              )
+            }
+            placeholder="Joining…"
+            disabled={!identity}
+          />
+        </label>
+        <div className="collaborators" aria-label="Cursors on this canvas">
+          {profile ? (
+            <span className="collaborator">
+              <span
+                className="collaborator-dot"
+                style={
+                  {
+                    '--collaborator-color': COLOR_HEX[profile.color],
+                  } as CSSProperties
+                }
+              />
+              {profile.name.trim() || 'guest'} (you)
+            </span>
+          ) : null}
+          {cursors.length === 0 ? (
+            <span className="hint">No other cursors right now</span>
+          ) : (
+            cursors.map((cursor) => (
+              <span className="collaborator" key={cursor.id}>
+                <span
+                  className="collaborator-dot"
+                  style={
+                    {
+                      '--collaborator-color': COLOR_HEX[cursor.color],
+                    } as CSSProperties
+                  }
+                />
+                {cursor.name}
+              </span>
+            ))
+          )}
+        </div>
+      </div>
+
+      <div className={`canvas-stage${live ? '' : ' historical'}`}>
+        <svg
+          ref={svgRef}
+          className="canvas-svg"
+          viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+          role="application"
+          aria-label="Shared canvas"
+          onClick={createShape}
+          onPointerMove={onPointerMove}
+          onPointerUp={endDrag}
+          onPointerLeave={onPointerLeave}
+        >
+          {shapes.map((shape) => {
+            const mine = drag?.shapeId === shape.id ? drag : null
+            const ghost = mine ? null : ghosts.get(shape.id)
+            const hex = COLOR_HEX[shape.color]
+            const common = {
+              className: `canvas-shape${ghost ? ' ghost' : ''}${mine ? ' dragging' : ''}`,
+              fill: hex,
+              stroke: ghost ? COLOR_HEX[ghost.color] : hex,
+              onPointerDown: (e: ReactPointerEvent<SVGGraphicsElement>) =>
+                startDrag(e, shape),
+              onDoubleClick: () => deleteShape(shape.id),
+            }
+            const geometry =
+              shape.kind === 'rect' ? (
+                <rect width={shape.w} height={shape.h} rx={6} {...common} />
+              ) : (
+                <ellipse
+                  cx={shape.w / 2}
+                  cy={shape.h / 2}
+                  rx={shape.w / 2}
+                  ry={shape.h / 2}
+                  {...common}
+                />
+              )
+            // Your own drag renders raw from pointer state; scrubbed
+            // scenes stay static. Everything else lives in one chaser
+            // per shape, stable across its whole life: the target is
+            // the ghost while a live remote drag holds the shape, the
+            // fold position otherwise — so a drop is just a target
+            // change, converging in lockstep with the cursor chaser.
+            if (mine || !live) {
+              return (
+                <g
+                  key={shape.id}
+                  transform={`translate(${mine ? mine.x : shape.x} ${mine ? mine.y : shape.y})`}
+                >
+                  {geometry}
+                </g>
+              )
+            }
+            return (
+              <Smoothed
+                key={shape.id}
+                x={ghost?.x ?? shape.x}
+                y={ghost?.y ?? shape.y}
+              >
+                {geometry}
+              </Smoothed>
+            )
+          })}
+          {cursors.map((cursor) => (
+            <Smoothed
+              key={cursor.id}
+              x={cursor.x}
+              y={cursor.y}
+              className="canvas-cursor"
+            >
+              <path
+                d="M 0 0 L 0 16 L 4.6 12.3 L 7.2 18 L 9.5 17 L 6.9 11.3 L 12.6 11.3 Z"
+                fill={COLOR_HEX[cursor.color]}
+              />
+              <text x={13} y={21} fill={COLOR_HEX[cursor.color]}>
+                {cursor.name}
+              </text>
+            </Smoothed>
+          ))}
+        </svg>
+        <p className={`canvas-status${live ? '' : ' replaying'}`}>
+          <span className="canvas-status-text">
+            {live
+              ? `Live — ${replayEvents.length} confirmed ${replayEvents.length === 1 ? 'event' : 'events'} received since the snapshot`
+              : `Replaying from the server snapshot through ${replayThrough} of ${replayEvents.length} confirmed events.`}
+          </span>
+          {/* Lives in the fixed-slot status line, hidden-not-removed,
+              so neither the slider row nor this line ever reflows. */}
+          <button
+            className="secondary compact canvas-back-to-live"
+            type="button"
+            disabled={live}
+            onClick={() => setScrub(null)}
+          >
+            Back to live
+          </button>
+        </p>
+      </div>
+
+      <div className="canvas-scrubber">
+        <input
+          type="range"
+          min={0}
+          max={replayEvents.length}
+          value={replayThrough}
+          disabled={replayEvents.length === 0}
+          onChange={(e) => {
+            const value = Number(e.target.value)
+            setScrub(value >= replayEvents.length ? null : value)
+          }}
+          aria-label="Replay events received since the server snapshot"
+        />
+        <span className="hint">
+          {live
+            ? `live — ${replayEvents.length} confirmed ${replayEvents.length === 1 ? 'event' : 'events'}`
+            : `confirmed event ${replayThrough} of ${replayEvents.length}`}
+        </span>
+      </div>
+      <p className="frontier">
+        This page starts from one server-rendered state snapshot, then folds
+        each confirmed event the client receives. The slider replays only that
+        observed tail.
+      </p>
+      {error ? <p className="error">{error}</p> : null}
+    </article>
+  )
+}