Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

48.6 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// bento-sync session — the bridge between the CRDT engine (crdt.ts) and the
// running editor. Owns: the differ hook on the store, transports (same-machine
// BroadcastChannel always; an online relay transport can be added), presence,
// and peer catch-up. See docs/collab-design.md.
//
// Wire protocol (one JSON frame per message; E2EE happens inside the online
// transport — this layer never knows):
//   {t:'hello', a, vv, p}    join/announce — receivers reply hello + missing ops
//   {t:'ops',   a, ops}      op batch
//   {t:'need',  a, vv}       gap catch-up request (receivers send missing ops)
//   {t:'p',     a, p}        presence heartbeat   {t:'bye', a}  leave
//
// The differ is the whole integration: every local mutation already flows
// through store.commit/touch → 'doc' event → (debounced) diff against the
// session's shadow → ops out. Remote ops apply surgically by id and re-emit
// the same store events the editor already listens to. Zero editor rewrites.

import {
  SyncEngine,
  SYNC_V,
  BLOB_INLINE_MAX,
  DOC_NODE,
  type BlobRef,
  type CollabCreds,
  type Op,
  type SyncDoc,
  type SyncStateJSON,
} from './crdt.ts'

// Re-exported: these are DOCUMENT-FORMAT types and live with the engine, but
// every consumer meets them through the session.
export type { BlobRef, CollabCreds, SyncDoc }
import { putBlob, getBlob, dataUriToBytes, bytesToDataUri, encodedSize, MAX_BLOB } from './blobs.ts'
import { mintCollab, cachedMemberPub } from './online.ts'
import { lsGet, lsJson } from '../storage.ts'
import { copy } from '../documentvalue.ts'

/**
 * The store the session drives, reduced to what it actually touches.
 *
 * Every app already has this: bento/slides' Store satisfies it as written.
 * Stated structurally rather than imported so the kernel does not reach into
 * an app — kernel/README.md's rule.
 */
export interface HostStore {
  doc: SyncDoc
  readOnly?: boolean
  on(event: string, fn: () => void): unknown
  emit(event: string): void
  commit(fn: () => void): void
  setDirty(v: boolean): void
}

/**
 * The app-shaped decisions the session cannot make for itself.
 *
 * This is deliberately SMALL. Of 727 lines, five places knew what a slide was:
 * repairing an emptied document, clamping the current position, pruning a
 * selection of ids that no longer exist, saying where this person is for
 * presence, and recognising embedded media in a refused batch. Everything else
 * — the differ, the shadow, catch-up, gap recovery, blobs, the fork snapshot
 * exchange — was already generic and moved unchanged.
 *
 * A word processor answers all five differently: "empty" is a document with no
 * blocks, "where you are" is a block and a caret rather than a slide and a
 * selection.
 */
export interface SyncHost {
  readonly store: HostStore
  /**
   * Repair the document after a remote change — an emptied container, say.
   * Return true if it mutated the doc.
   *
   * THE REPAIR DOES NOT CONVERGE BY ITSELF. Returning true makes the session
   * mint the change as an ordinary local op, and an op is all it is: two
   * replicas that heal concurrently mint TWO nodes and the CRDT faithfully
   * keeps both. Nothing here deduplicates them.
   *
   * So any id the repair creates MUST be derived from stable document data —
   * `docId`, or the content — and never freshly generated, so that concurrent
   * healers produce the SAME node and the merge collapses it. bento/slides
   * gets away with a random id because a spare blank slide is visible and
   * harmless; a spare page in a space is a phantom in the sidebar, and a spare
   * paragraph is one somebody has to notice and delete.
   *
   * This comment previously said the session "mints the repair as a local op
   * so every replica converges on one healer's version", which reads as though
   * convergence were handled for you. It is not, and that belief is exactly
   * what produces a random-id heal. (Caught by the bento/spaces session, which
   * hit the race while writing its own adapter.)
   */
  heal(): boolean
  /**
   * Snapshot per-tab view state BEFORE a remote change is applied. Optional:
   * a shape whose view survives any edit does not need one.
   *
   * It exists because clamping after the fact is not enough. Keeping the user
   * on the same slide when someone else deletes a different one requires
   * knowing which slide they were on by IDENTITY, and after the apply that
   * information is gone — the index now points at whatever moved into the gap.
   * bento/slides fixed exactly this upstream (#262) and the fix is unavailable
   * to a post-hoc clamp.
   */
  captureView?(): unknown
  /**
   * Reconcile per-tab view state (current position, selection) with a document
   * that changed underneath it, given whatever `captureView` returned. Return
   * true if the SELECTION changed, which is the only part the session has to
   * announce.
   */
  clampView(view?: unknown): boolean
  /** Where this replica is, for presence. */
  presence(): { at: string; sel: string[] }
  /**
   * Store events fired after EVERY remote change.
   *
   * Was hard-coded to `'doc'`, which is what bento/slides calls "something in
   * the document changed, repaint". It is not universal: in bento/spaces the
   * same name is the DIRTY/STATUS signal and repainting goes through 'tree'
   * and 'page', so emitting it for a remote op would label a colleague's edit
   * "Edited" in this user's chrome. Which events a remote change should raise
   * is the app's to say — the kernel knowing one app's vocabulary is exactly
   * what this seam exists to stop.
   *
   * (Raised by the bento/spaces session reviewing this interface. The kernel
   * had shipped its own app's habit as a default.)
   */
  readonly changeEvents: readonly string[]
  /** Extra events a STRUCTURAL remote change needs, on top of changeEvents. */
  readonly structureEvents: readonly string[]
  /** Events that should push a fresh presence frame when the app emits them. */
  readonly presenceEvents: readonly string[]
  /** Structural probe: does this refused batch carry embedded media? */
  carriesMedia(ops: Op[]): boolean
  /**
   * The engine BOUND to this app's document shape.
   *
   * Passed as the class, not an instance, because the session constructs one
   * per attach and restores one from saved state — and `fromJSON` on a bound
   * subclass returns that subclass (pinned by scripts/test-sync-shape.ts).
   * A session that built a bare `SyncEngine` here would silently hold slides'
   * shape for every app.
   */
  readonly engine: {
    new (actor: string): SyncEngine
    fromJSON(actor: string, json: SyncStateJSON): SyncEngine
  }
}

export interface PresenceInfo {
  name: string
  color: string
  /**
   * WHERE THIS PERSON IS — a slide id in bento/slides, a page id in
   * bento/spaces, a block id in bento/type.
   *
   * The NAME is wrong for three of the four apps and is kept anyway, because
   * it is on the wire: deployed clients read this field, and the relay stores
   * frames containing it. Renaming it to `at` would fork presence between
   * versions for no user-visible gain — a live session would show colleagues
   * as nowhere. The app-side name IS `at` (SyncHost.presence returns `{at,
   * sel}`), so the honest name is used everywhere it costs nothing, and the
   * frozen one only where it is load-bearing.
   */
  slide: string
  /** selected element ids */
  sel: string[]
  /** element id currently being text-edited (in-text presence) */
  editing?: string
  /** v2 fine-grained: the key this copy signs with — key-bound identity */
  pub?: string
  /** capability of this copy, derived locally from its collab material */
  role?: 'owner' | 'editor' | 'viewer'
  /** the tab is backgrounded (document.hidden) — the UI can dim the avatar
   *  instead of treating a throttled beat as a departure. Presence only; never
   *  in the document. Absent = present/unknown. */
  away?: boolean
}

export interface Peer extends PresenceInfo {
  actor: string
  at: number
}

interface HelloFrame { t: 'hello'; a: string; vv: Record<string, number>; p: PresenceInfo }
interface OpsFrame { t: 'ops'; a: string; ops: Op[] }
interface NeedFrame { t: 'need'; a: string; vv: Record<string, number> }
interface PresFrame { t: 'p'; a: string; p: PresenceInfo }
interface ByeFrame { t: 'bye'; a: string }
/** state-based fork merge: a rejoining offline-edited copy announces itself */
interface SnapFrame {
  t: 'snap'
  a: string
  doc: SyncDoc
  state: SyncStateJSON
}
/** every frame is stamped with the sync protocol version (`pv: SYNC_V`) by
 * send(); frames without the current pv (old builds, stale relay logs from
 * the bare-id era) are dropped in onFrame — their keys don't interoperate */
export type Frame = (HelloFrame | OpsFrame | NeedFrame | PresFrame | ByeFrame | SnapFrame) & {
  pv?: number
}

export interface Transport {
  readonly kind: string
  send(frame: Frame): void
  close(): void
  // ——— broadcast (the online transport only; BroadcastChannel has no show) ———
  /** resolves once the socket may write (proven, or an older/relay reader) */
  writeReady?(): Promise<void>
  /** true when this is a receive-only audience socket */
  readonly audience?: boolean
  /** import (or clear, with null) the per-show key Ke */
  setShowKey?(rawB64: string | null): Promise<void>
  /** an op batch to the audience, sealed under Ke */
  sendAud?(ops: Op[]): void | Promise<void>
  /** the whole projected document to the audience, under Ke */
  sendAudSnap?(doc: SyncDoc, state: SyncStateJSON): void | Promise<void>
  /** a control verb: live/end (signed literal) or nav/black/laser (under Ke) */
  sendVerb?(kind: 'live' | 'end' | 'nav' | 'black' | 'laser', payload?: unknown): void | Promise<void>
}

/** What a broadcast surfaces to the app. The audience acts on `verb` and
 *  `closed`; the presenter on `checkpoint` (send a fresh audsnap — the session
 *  does that for you) and `count`. */
export type ShowEvent =
  | { t: 'verb'; kind: 'nav' | 'black' | 'laser'; payload: unknown }
  | { t: 'closed'; code: number }
  | { t: 'checkpoint' }
  | { t: 'count'; n: number }

/** The presenter's control surface, live only while a show is on. Every call
 *  is a no-op before the socket is proven — startShow awaits that first. */
export interface ShowVerbs {
  nav(payload: unknown): void
  black(payload: unknown): void
  laser(payload: unknown): void
}

/** What the app injects to run a show. The kernel never learns the app's field
 *  names: `projectOp` decides which ops an audience may see, `snapshot` returns
 *  the ALREADY-PROJECTED document. Both are the app's (slides/src/audience.ts). */
export interface ShowConfig {
  /** raw AES-GCM show key Ke, base64url */
  showKey: string
  /** null = this op is not for the audience (dropped from the aud stream) */
  projectOp(op: Op): Op | null
  /** the projected document ONLY. The session builds the sync state itself
   *  (freshAudState) — an adopt of this doc, so no stash or text history leaks
   *  past the projection. The app must NOT supply a state; there is nowhere it
   *  could get a safe one. */
  snapshot(): { doc: SyncDoc }
}

/**
 * Why the relay refused a frame (`{ctl:'refused', code, …}` — see
 * server/sync-worker). Everything but 'rate-limited' is PERMANENT for the
 * frame that drew it: retrying can only reproduce the refusal.
 */
export type RefusalCode = 'too-large' | 'storage-failed' | 'room-full' | 'rate-limited'

/**
 * Something the user deserves to know about the live session. The transport
 * detects it, the session records the consequence, the editor renders the
 * sentence (t() must run at display time, so no text crosses this boundary).
 */
export interface SyncNotice {
  code: RefusalCode
  /** true = the change will never reach collaborators; false = retrying */
  permanent: boolean
  /** how many ops were abandoned (0 when the refused frame wasn't ours to name) */
  ops: number
  /** the abandoned ops carried embedded media — lets the UI say "that image" */
  media?: boolean
  /** the refused frame was a whole-deck SNAPSHOT, not a single change (the relay
   *  could not attribute it to any op of ours). Lets the UI say "this deck is too
   *  large to share" rather than "that change is too large". `ops` is 0 here. */
  snapshot?: boolean
}

/** Same-machine transport: every open tab/window of this document. */
class BroadcastTransport implements Transport {
  readonly kind = 'local'
  private ch: BroadcastChannel
  constructor(docId: string, onFrame: (f: Frame) => void) {
    this.ch = new BroadcastChannel(`bento-sync-${docId}`)
    this.ch.onmessage = (ev) => onFrame(ev.data as Frame)
  }
  send(frame: Frame) {
    this.ch.postMessage(frame)
  }
  close() {
    this.ch.close()
  }
}

const PEER_COLORS = ['#FF9E8A', '#8FA3BF', '#7FC8A9', '#E8C468', '#C792EA', '#6AB7D6', '#E88AB0', '#A9C77F']

const actorColor = (actor: string): string => {
  let h = 0
  for (let i = 0; i < actor.length; i++) h = (h * 31 + actor.charCodeAt(i)) >>> 0
  return PEER_COLORS[h % PEER_COLORS.length]
}

/**
 * Actor id: fresh per SESSION INSTANCE, deliberately — a reloaded tab is a
 * new replica with empty CRDT state, and the engine skips "own" ops on
 * apply, so reusing an id would make relay replay of the previous
 * incarnation's ops a no-op. Random ids sidestep the whole class.
 */
function tabActor(): string {
  return Math.random().toString(36).slice(2, 10)
}

const DIFF_DEBOUNCE_MS = 90
const HEARTBEAT_MS = 5000
// The TTL must clear the worst LEGITIMATE beat interval, not a multiple of the
// ideal one. A browser throttles a backgrounded tab's timers hard — Chrome to
// about once a MINUTE after a few minutes hidden, Safari sooner — so a
// collaborator whose tab is in the background still beats, just every ~60 s. At
// 13 s (2.6× the 5 s ideal) the sweep dropped them between throttled beats and
// the next beat re-added them: everyone saw that person leave and rejoin once a
// minute. 75 s clears the 60 s throttle with margin. A real departure is still
// gone within 75 s (and instantly on `bye`); backgrounded peers also send
// `away` so the UI can dim rather than wait.
const PEER_TTL_MS = 75000

/** Offload once the inline assets TOTAL runs past this, even if no single one is
 *  over BLOB_INLINE_MAX — the "fifty 50 KB icons" deck whose sum overflows a
 *  frame. Below the relay MAX_FRAME with room for the document and its state. */
const INLINE_TOTAL_MAX = 256 * 1024

/**
 * Which inline assets to offload to blobs. Pure, so it is tested without a relay
 * (session.offloadAssets does the upload). Two rules:
 *   · per-asset  — anything over `inlineMax` (too big to ride in an op);
 *   · cumulative — when the inline TOTAL is over `totalMax`, the LARGEST inline
 *     assets, biggest first, until the remaining inline bytes are back under it.
 * `offloadable` is false for a raw-SVG asset (not a data: URI) — it stays inline
 * because there is nothing to blob; it still counts toward the total.
 */
export function assetsToOffload(
  entries: Array<{ key: string; len: number; offloadable: boolean }>,
  inlineMax: number,
  totalMax: number,
): Set<string> {
  const picks = new Set<string>()
  let total = 0
  for (const e of entries) total += e.len
  for (const e of entries) if (e.offloadable && e.len > inlineMax) picks.add(e.key)
  if (total > totalMax) {
    let rem = total
    for (const e of entries) if (picks.has(e.key)) rem -= e.len
    for (const e of entries.filter((e) => !picks.has(e.key) && e.offloadable).sort((a, b) => b.len - a.len)) {
      if (rem <= totalMax) break
      picks.add(e.key)
      rem -= e.len
    }
  }
  return picks
}

export class SyncSession {
  readonly actor: string
  state!: SyncEngine
  private shadow = ''
  private docId = ''
  private log: Op[] = []
  private transports: Transport[] = []
  private peersMap = new Map<string, Peer>()
  private applying = false
  private diffTimer: number | null = null
  private heartbeat: number | null = null
  private peerListeners = new Set<() => void>()
  private noticeListeners = new Set<(n: SyncNotice) => void>()
  private editingEl: string | undefined
  /** extra transports (the online relay) get plugged in here */
  private makeExtraTransports: Array<(docId: string, onFrame: (f: Frame) => void) => Transport> = []

  private readonly host: SyncHost
  /** the app's store — every call site below predates the host and still reads
   *  `this.store`, which is exactly the point: the move changed the seam, not
   *  the session's logic */
  private get store(): HostStore { return this.host.store }

  constructor(host: SyncHost) {
    this.host = host
    const store = host.store
    this.actor = tabActor()
    this.attach()
    store.on('doc', () => this.onLocalChange())
    for (const ev of host.presenceEvents) store.on(ev, () => this.pushPresence())
    window.addEventListener('beforeunload', () => this.broadcast({ t: 'bye', a: this.actor }))
    // A backgrounded tab's heartbeat is throttled to ~once a minute, so beat the
    // instant it changes visibility: on return the peer refreshes before the TTL
    // could sweep it, and on leaving it carries `away` so peers dim promptly.
    // visibilitychange fires unthrottled in both directions.
    if (typeof document !== 'undefined') {
      document.addEventListener('visibilitychange', () => this.pushPresence())
    }
  }

  // --- lifecycle -----------------------------------------------------------

  /** a restored offline fork still owes the room its snapshot */
  private forkPending = false

  /**
   * This replica carries offline-fork contributions that live only in its doc
   * VALUES + restored registers, never as replayable log ops. `forkPending`
   * drives the ONE broadcast at our own hello and is cleared once the relay has
   * our server snapshot; this stays set for the session, because a peer that
   * joins LATER still can't learn those contributions from the log. Online late
   * joiners recover from the relay's server snapshot, but a same-machine tab
   * joins over BroadcastChannel, which has no replay — so we re-snap each new
   * peer while this holds (see onFrame 'hello').
   */
  private carriesForkState = false

  /** the loaded doc arrived carrying collab creds (was saved/shared) */
  private bornWithCollab = false
  /** the user opted in this session (saved, or hit "Start live session") */
  private explicitShare = false

  /** Should this doc auto-connect to the relay on open? See attach(). */
  shareEligible(): boolean {
    return this.bornWithCollab || this.explicitShare
  }

  /** Mark that the user opted into sharing (save / explicit Start live). */
  enableSharing() {
    this.explicitShare = true
  }

  private attach() {
    this.docId = this.store.doc.docId
    const doc = this.store.doc
    // Auto-connect eligibility: a doc that ARRIVED carrying collab creds was
    // saved/shared by someone — it should go live on open. A doc we mint creds
    // for right now (the anonymous starter demo, a fresh template instance) is
    // NOT auto-connected — it phones home only after the user saves or clicks
    // "Start live session" (enableSharing). This keeps casual visitors off the
    // relay and honours "nothing phones home unless you ask".
    this.bornWithCollab = !!doc.collab
    this.explicitShare = false
    // credentials are minted AT CREATION: any copy of the file can join once
    // it is live (on:true by default). Minting is async now (the writer
    // keypair) — fine because a freshly-minted doc is never auto-connected, so
    // the sub-frame gap before collab lands touches nothing. See eligibility.
    if (!doc.collab) void this.ensureCollab()
    const saved = doc.collab?.sync
    if (saved && saved.v === SYNC_V) {
      // this file was saved during/after a shared session: restore the CRDT
      // state so our offline edits carry real registers, remote replay
      // dedups by version vector, and a state-based snapshot exchange can
      // merge the fork BOTH ways (see docs/collab-design.md)
      this.state = this.host.engine.fromJSON(this.actor, JSON.parse(JSON.stringify(saved)))
      this.forkPending = true
      this.carriesForkState = true
    } else {
      // no saved state, or state from the pre-composite-key era (v1) — that
      // scheme collapsed same-id-on-many-slides, so it is discarded and the
      // file joins as a never-synced adopt (deterministic keys from the doc)
      this.state = new this.host.engine(this.actor)
    }
    this.state.adopt(doc)
    this.shadow = JSON.stringify(doc)
    this.log = []
    this.peersMap.clear()
    this.emitPeers()
    for (const tr of this.transports) tr.close()
    this.transports = [new BroadcastTransport(this.docId, (f) => this.onFrame(f))]
    for (const mk of this.makeExtraTransports) this.transports.push(mk(this.docId, (f) => this.onFrame(f)))
    this.hello() // announces + (for restored forks) broadcasts the state snapshot
    if (this.heartbeat) clearInterval(this.heartbeat)
    this.heartbeat = window.setInterval(() => {
      this.pushPresence()
      this.sweepPeers()
    }, HEARTBEAT_MS)
  }

  /** Mint collab credentials (incl. the writer keypair) for a doc created
   *  without them. Direct mutation (no undo entry), guarded against a race with
   *  a real collab arriving via loadDoc. */
  private async ensureCollab() {
    if (this.store.doc.collab) return
    const creds = await mintCollab()
    if (!this.store.doc.collab) this.store.doc.collab = creds
  }

  /** register a factory for an additional transport (online relay) and connect it */
  addTransport(mk: (docId: string, onFrame: (f: Frame) => void) => Transport): Transport {
    this.makeExtraTransports.push(mk)
    const tr = mk(this.docId, (f) => this.onFrame(f))
    this.transports.push(tr)
    this.broadcast({ t: 'hello', a: this.actor, vv: this.state.vv, p: this.presence() })
    return tr
  }

  removeTransport(tr: Transport) {
    tr.close()
    this.transports = this.transports.filter((x) => x !== tr)
    this.makeExtraTransports = []
  }

  get transportKinds(): string[] {
    return this.transports.map((t) => t.kind)
  }

  // --- local mutations → ops ----------------------------------------------

  private onLocalChange() {
    if (this.applying) return
    if (this.store.doc.docId !== this.docId) {
      // replaceDoc / loadDoc swapped in a different document — re-key
      this.attach()
      return
    }
    if (this.diffTimer) return
    this.diffTimer = window.setTimeout(() => {
      this.diffTimer = null
      this.flush()
    }, DIFF_DEBOUNCE_MS)
  }

  /** diff now (also called before presence-relevant transitions) */
  /**
   * Assets too large for an op (docs/blob-offload.md) are uploaded to the
   * relay's blob store and published as a small `blobs.<key>` reference, which
   * IS small enough to sync. Runs after a local edit; the reference lands on
   * the next flush like any other change.
   *
   * TWO rules pick what to offload — see assetsToOffload: anything over
   * BLOB_INLINE_MAX (too big for an op), AND, when the inline TOTAL runs past
   * INLINE_TOTAL_MAX, the largest inline assets until it is back under, so a
   * deck of fifty 50 KB icons (none over 64 KB alone) does not sum past the
   * snapshot/frame ceiling.
   *
   * The bytes are always cached locally even when the upload fails, because
   * the cache is per-ORIGIN: same-machine tabs syncing over BroadcastChannel
   * resolve from it with no relay involved at all.
   */
  private async offloadAssets() {
    const doc = this.store.doc
    const assets = doc.assets ?? {}
    const entries = Object.entries(assets)
      .filter(([k, v]) => typeof v === 'string' && !doc.blobs?.[k])
      .map(([k, v]) => ({ key: k, len: (v as string).length, offloadable: dataUriToBytes(v as string) !== null }))
    const picks = assetsToOffload(entries, BLOB_INLINE_MAX, INLINE_TOTAL_MAX)
    if (!picks.size) return
    const creds = this.blobCreds()
    for (const k of picks) {
      const parsed = dataUriToBytes(assets[k] as string)
      if (!parsed) continue // offloadable was true, but be defensive
      if (encodedSize(parsed.bytes.length) > MAX_BLOB) {
        this.notify('blob-too-large', k)
        continue
      }
      if (!creds) continue // no relay yet; retry on the next edit
      const res = await putBlob(
        { base: creds.base, room: creds.room, tok: creds.tok }, creds.rawKey, parsed.bytes,
      )
      if (!res.ok) {
        // 'unsupported' = relay has no blob storage. Not an error: small assets
        // still inline, and same-origin tabs resolve from the local cache.
        if (res.reason !== 'unsupported') this.notify(`blob-${res.reason}`, k)
        continue
      }
      this.store.commit(() => {
        const d = this.store.doc
        ;(d.blobs ??= {})[k] = { key: res.key, mime: parsed.mime, size: parsed.bytes.length }
      })
    }
  }

  /**
   * The other direction: a peer published a reference we have no bytes for.
   * Fetch, decrypt and materialise it into `assets` so the renderer can use it
   * exactly as if it had arrived inline.
   *
   * A blob that never arrives leaves the asset ABSENT rather than blank —
   * `assetRef()` in render.ts resolves a missing key to '', which the UI shows
   * as a visibly empty element. Silent-but-wrong is the failure mode we are
   * avoiding everywhere in this system.
   */
  private async resolveBlobs() {
    const doc = this.store.doc
    const refs = doc.blobs ?? {}
    const creds = this.blobCreds()
    for (const [k, ref] of Object.entries(refs)) {
      if (doc.assets?.[k]) continue // already have the bytes
      if (this.fetching.has(ref.key)) continue
      this.fetching.add(ref.key)
      try {
        // cache-first, so same-origin tabs need no relay at all
        const bytes = creds
          ? await getBlob({ base: creds.base, room: creds.room, tok: creds.tok }, creds.rawKey, ref.key)
          : null
        if (!bytes) { this.notify('blob-unavailable', k); continue }
        // Land the materialised asset the way a REMOTE OP does — mutate the doc
        // and emit the store's change events, NOT store.commit. A read-only
        // live-viewer copy no-ops commit (store.readOnly), so going through it
        // left relay-offloaded images blank for readers; assets are local
        // content-addressed bytes (never an op), so the differ sends nothing
        // either way and the shadow needs no update.
        const d = this.store.doc
        ;(d.assets ??= {})[k] = bytesToDataUri(bytes, ref.mime)
        for (const ev of this.host.changeEvents) this.store.emit(ev)
      } finally {
        this.fetching.delete(ref.key)
      }
    }
  }

  private fetching = new Set<string>()
  /** set by the editor when an online transport exists */
  /** Credentials the blob layer needs, taken from whichever transport can
   *  reach a relay.
   *
   *  Resolved ON DEMAND, deliberately. The obvious shape — a hook assigned when
   *  the online transport connects — is what shipped broken: nothing ever
   *  assigned it, so `creds` was always null, every upload was skipped by the
   *  `if (!creds) continue` guard, and the whole offload was inert with no
   *  error anywhere. Transports are also torn down and rebuilt on reconnect and
   *  on rejoin, so even a correctly-assigned hook goes stale. Asking the live
   *  transport list each time cannot drift. */
  private blobCreds(): { base: string; room: string; tok: string; rawKey: Uint8Array } | null {
    for (const tr of this.transports) {
      const f = (tr as { blobCreds?: () => { base: string; room: string; tok: string; rawKey: Uint8Array } | null }).blobCreds
      if (typeof f !== 'function') continue
      const c = f.call(tr)
      if (c) return c
    }
    return null
  }
  private notify(code: string, detail?: string) {
    // routed through the existing notice channel so the editor can toast it
    try { (this as unknown as { noticeFn?: (c: string, d?: string) => void }).noticeFn?.(code, detail) } catch { /* none */ }
  }

  flush() {
    if (this.applying) return
    const before = JSON.parse(this.shadow) as SyncDoc
    let ops: Op[]
    try {
      ops = this.state.diff(before, this.store.doc, { text: true })
    } catch (err) {
      this.recoverFromDiffFailure(err)
      return
    }
    this.shadow = JSON.stringify(this.store.doc)
    // Any large asset the differ just skipped needs its bytes offloaded; the
    // resulting reference syncs on the next flush like an ordinary change.
    void this.offloadAssets()
    if (!ops.length) return
    this.log.push(...ops)
    this.broadcast({ t: 'ops', a: this.actor, ops })
    if (this.showCfg) this.projectToAudience(ops)
  }

  /**
   * A differ bug must not WEDGE the session. The shadow is only advanced after
   * a successful diff, so an uncaught throw here poisons every later flush:
   * the same delta is re-diffed, throws again, and nothing syncs for the rest
   * of the session — on any slide, not just the element that broke. That
   * amplifier is what turned the ~200KB-text stack overflow (fixed in crdt.ts:
   * splice-without-spread) into total, silent collab failure. The trigger is
   * gone; the amplifier stays armed for the next differ bug, so disarm it.
   *
   * Recovery, best-effort in this order:
   *  - Advance the shadow past the poison delta. Re-diffing it would just
   *    re-throw, and a wedged differ is strictly worse than one lost delta.
   *  - Ship a state snapshot. diff() mints ops and advances its registers as
   *    it goes, so a mid-diff throw leaves some changes stamped but never
   *    broadcast — they now live only in our doc VALUES. That is exactly the
   *    offline-fork case, and a snapshot is how those travel (see hello()).
   *    forkPending re-sends it on the next reconnect too.
   *
   * Deliberately not a SyncNotice: those name conditions a user can act on
   * (too large, room full). This path is a bug — console is the right surface.
   */
  private recoverFromDiffFailure(err: unknown) {
    console.error('[bento-sync] diff failed; recovering via snapshot', err)
    this.shadow = JSON.stringify(this.store.doc)
    this.forkPending = true
    this.carriesForkState = true
    try {
      // snapshotPair() rather than this.snapshot() — that calls flush(), and
      // flush() is our caller
      this.broadcast({ t: 'snap', a: this.actor, ...this.snapshotPair() })
    } catch (e2) {
      // snapshot itself failed (state unserializable) — the shadow is still
      // advanced, so editing continues and the next reconnect retries
      console.error('[bento-sync] snapshot recovery failed', e2)
    }
  }

  // --- remote frames --------------------------------------------------------

  private onFrame(f: Frame) {
    if (f.pv !== SYNC_V) return // old-protocol frame (bare-id keys) — ignore
    if (f.a === this.actor) return
    switch (f.t) {
      case 'hello': {
        const newcomer = !this.peersMap.has(f.a)
        this.touchPeer(f.a, f.p)
        // answer so the newcomer learns us + catch them up from our log,
        // AND tell them our vv so ops they minted before connecting (which
        // nothing else would push) flow back to us — need→ops terminates
        this.send({ t: 'p', a: this.actor, p: this.presence() })
        this.send({ t: 'need', a: this.actor, vv: this.state.vv })
        const missing = this.state.missingFor(this.log, f.vv)
        if (missing.length) this.send({ t: 'ops', a: this.actor, ops: missing })
        // A fork's offline contributions aren't in the log — the log catch-up
        // above can't convey them. We snapshot them ONCE at our own hello, which
        // a peer that joins LATER misses; re-send to each genuinely new peer so
        // a same-machine tab opened later (BroadcastChannel has no replay) still
        // merges our fork. Online peers also get it from the relay snapshot; the
        // merge is idempotent, so a duplicate is harmless.
        if (newcomer && this.carriesForkState) {
          const s = this.snapshot()
          this.send({ t: 'snap', a: this.actor, doc: s.doc, state: s.state })
        }
        break
      }
      case 'ops':
        this.applyRemote(f.ops)
        break
      case 'need': {
        const missing = this.state.missingFor(this.log, f.vv)
        if (missing.length) this.send({ t: 'ops', a: this.actor, ops: missing })
        break
      }
      case 'p':
        this.touchPeer(f.a, f.p)
        break
      case 'snap':
        this.applySnapshot(f.doc, f.state)
        break
      case 'bye':
        this.peersMap.delete(f.a)
        this.emitPeers()
        break
    }
  }

  applyRemote(ops: Op[]) {
    // make sure our own pending edits are diffed first (they pre-date the
    // remote batch locally; LWW settles the rest)
    this.flush()
    for (const op of ops) if (!this.log.some((o) => o.a === op.a && o.s === op.s)) this.log.push(op)
    this.applying = true
    // Before the document moves, not after: see captureView on the host shape.
    const view = this.host.captureView?.()
    try {
      const res = this.state.apply(this.store.doc, ops)
      if (res.changed) this.afterRemoteChange(res.structure, view)
    } finally {
      this.applying = false
    }
    // While presenting, a CO-PRESENTER's edits arrive here, not through flush,
    // so they must be projected onto the aud stream too — otherwise the
    // audience sees another writer's changes only at the next checkpoint. Only
    // the presenter has a show config, so this fires for it alone; the audience
    // (which reaches applyRemote via applyShowOps) has none and re-projects
    // nothing.
    if (this.showCfg) this.projectToAudience(ops)
    if (this.state.gappedActors.length) {
      this.send({ t: 'need', a: this.actor, vv: this.state.vv })
    }
  }

  private afterRemoteChange(structure: boolean, view?: unknown) {
    void this.resolveBlobs()
    const store = this.store
    // A delete-everything race can leave a document with no content at all,
    // which no editor can render. What "empty" means and what repairs it are
    // the app's to say.
    if (this.host.heal()) {
      // mint the repair as a local op so every replica converges on ONE
      // healer's version (LWW keeps all healers'; harmless duplicates)
      this.applying = false
      this.flush()
      this.applying = true
    }
    const selChanged = this.host.clampView(view)
    this.shadow = JSON.stringify(store.doc)
    store.doc.modified = new Date().toISOString()
    store.setDirty(true)
    for (const ev of this.host.changeEvents) store.emit(ev)
    if (structure) for (const ev of this.host.structureEvents) store.emit(ev)
    if (selChanged) store.emit('selection')
  }

  // --- presence -------------------------------------------------------------

  private presence(): PresenceInfo {
    let name = 'Guest'
    try {
      name = lsGet('bento-author') || 'Guest'
    } catch {
      /* storage unavailable */
    }
    // key-bound identity (v2): which key this copy signs with + its capability.
    // The device key is minted by the transport on first connect; until then a
    // member's pub is simply absent from presence (it fills in on reconnect).
    const c = this.store.doc.collab
    let pub: string | undefined
    let role: 'owner' | 'editor' | 'viewer' | undefined
    if (c) {
      if (c.role === 'reader') role = 'viewer'
      else if (c.v === 2 && c.ownerPriv) { role = 'owner'; pub = c.owner }
      else if (c.v === 2 && c.invite) {
        role = 'editor'
        // the identity this page resolved first; the stored pubkey otherwise
        pub = cachedMemberPub(this.store.doc.docId) ??
          lsJson<{ pub?: string } | null>(`bento-member-${this.store.doc.docId}`, null)?.pub
      } else if (c.writerPriv) { role = 'editor'; pub = c.writerPub }
    }
    const where = this.host.presence()
    return {
      name,
      color: actorColor(this.actor),
      // `slide` is the WIRE name and is frozen — deployed clients and the
      // relay both read it. It means "where this person is", which for a word
      // processor is a block rather than a slide.
      slide: where.at,
      sel: where.sel,
      ...(this.editingEl ? { editing: this.editingEl } : {}),
      ...(pub ? { pub } : {}),
      ...(role ? { role } : {}),
      ...(typeof document !== 'undefined' && document.hidden ? { away: true } : {}),
    }
  }

  /** canvas hooks this while a text element is being edited (M3 presence) */
  setEditing(elId: string | undefined) {
    if (this.editingEl === elId) return
    this.editingEl = elId
    this.pushPresence()
  }

  private pushPresence() {
    this.send({ t: 'p', a: this.actor, p: this.presence() })
  }

  private touchPeer(actor: string, p: PresenceInfo) {
    this.peersMap.set(actor, { ...p, actor, at: Date.now() })
    this.emitPeers()
  }

  private sweepPeers() {
    const cut = Date.now() - PEER_TTL_MS
    let changed = false
    for (const [a, p] of this.peersMap) {
      if (p.at < cut) {
        this.peersMap.delete(a)
        changed = true
      }
    }
    if (changed) this.emitPeers()
  }

  peers(): Peer[] {
    return [...this.peersMap.values()].sort((a, b) => (a.actor < b.actor ? -1 : 1))
  }

  onPeers(fn: () => void): () => void {
    this.peerListeners.add(fn)
    return () => this.peerListeners.delete(fn)
  }

  private emitPeers() {
    this.peerListeners.forEach((fn) => fn())
  }

  // --- relay refusals -------------------------------------------------------

  // ——— broadcast: the presenter's show, and the audience's reception ———
  private showCfg: ShowConfig | null = null
  private showListeners = new Set<(e: ShowEvent) => void>()

  /** The presenter's live-verb surface, or null when no show is running. */
  show: ShowVerbs | null = null

  /** Subscribe to show events (verbs, count, checkpoint, close). */
  onShow(fn: (e: ShowEvent) => void): () => void {
    this.showListeners.add(fn)
    return () => this.showListeners.delete(fn)
  }
  private emitShow(e: ShowEvent) { this.showListeners.forEach((fn) => fn(e)) }

  /** The online transport, if one is connected — the only one with a show. */
  private showTransport(): Transport | undefined {
    return this.transports.find((t) => typeof t.setShowKey === 'function')
  }

  /** A sync state built ONLY from the projected doc — adopt-shaped, so it
   *  carries no stash and no text history to leak past the projection. */
  private freshAudState(doc: SyncDoc): SyncStateJSON {
    const eng = new this.host.engine(this.actor)
    eng.adopt(doc as never)
    return JSON.parse(JSON.stringify(eng.toJSON())) as SyncStateJSON
  }

  /**
   * Begin broadcasting. The caller is already sharing (a proven writer); this
   * installs the show key, waits until the socket may write, sends the first
   * audsnap, and opens the verb surface. Ops flow to the audience from the next
   * flush on. Idempotent-ish: a second call replaces the config.
   */
  async startShow(cfg: ShowConfig): Promise<void> {
    const tr = this.showTransport()
    if (!tr?.setShowKey) throw new Error('startShow: no online transport to broadcast on')
    if (tr.audience) throw new Error('startShow: an audience copy cannot present')
    this.showCfg = cfg
    await tr.setShowKey(cfg.showKey)
    await tr.writeReady?.()
    await tr.sendVerb?.('live')
    const snap = cfg.snapshot()
    await tr.sendAudSnap?.(snap.doc, this.freshAudState(snap.doc))
    this.show = {
      nav: (p) => { void this.showTransport()?.sendVerb?.('nav', p) },
      black: (p) => { void this.showTransport()?.sendVerb?.('black', p) },
      laser: (p) => { void this.showTransport()?.sendVerb?.('laser', p) },
    }
  }

  /** End the show: a signed `end`, then the key is dropped. */
  async endShow(): Promise<void> {
    const tr = this.showTransport()
    this.show = null
    this.showCfg = null
    await tr?.sendVerb?.('end')
    await tr?.setShowKey?.(null)
  }

  /** Each local op batch, projected onto the aud stream. An op the app maps to
   *  null is not the audience's to see; a batch that projects to nothing sends
   *  no frame. */
  private projectToAudience(ops: Op[]) {
    if (!this.showCfg) return
    const projected: Op[] = []
    for (const op of ops) { const p = this.showCfg.projectOp(op); if (p) projected.push(p) }
    if (projected.length) void this.showTransport()?.sendAud?.(projected)
  }

  /** The relay asked us to checkpoint (soft cap) or refused an aud op
   *  (show-full). Either way a fresh audsnap re-bases the audience and resets
   *  the relay's cap; the audsnap subsumes any refused batch, so nothing needs
   *  resending. The session does this itself (it holds snapshot()); the event
   *  is for the app's awareness. */
  showCheckpoint(): void {
    if (!this.showCfg) return
    const snap = this.showCfg.snapshot()
    void this.showTransport()?.sendAudSnap?.(snap.doc, this.freshAudState(snap.doc))
    this.emitShow({ t: 'checkpoint' })
  }
  showCount(n: number): void { this.emitShow({ t: 'count', n }) }
  showVerb(kind: 'nav' | 'black' | 'laser', payload: unknown): void { this.emitShow({ t: 'verb', kind, payload }) }
  showClosed(code: number): void { this.emitShow({ t: 'closed', code }) }
  /** An aud op batch arrived (audience): apply through the reader path. */
  applyShowOps(ops: Op[]): void { this.applyRemote(ops) }
  /** An aud snapshot arrived (audience). */
  applyShowSnap(doc: SyncDoc, state: SyncStateJSON): void { this.applySnapshot(doc, state) }

  /** the editor subscribes here to toast what the relay refused */
  onNotice(fn: (n: SyncNotice) => void): () => void {
    this.noticeListeners.add(fn)
    return () => this.noticeListeners.delete(fn)
  }

  private emitNotice(n: SyncNotice) {
    this.noticeListeners.forEach((fn) => fn(n))
  }

  /**
   * A transport reports that the relay refused a frame. For the PERMANENT
   * codes the named ops can never be delivered, so they leave the resend log.
   *
   * Why dropping is the right call, and why it is narrow: `missingFor` answers
   * every peer `need` (and `onRelayReady`) out of `log`, so an op the relay
   * will always refuse would be re-offered, re-sent, re-refused — forever.
   * That loop is the bug this exists to break. The price is real and cannot be
   * undone: the local document KEEPS the change, remote replicas never see it,
   * and nothing reconciles it later (short of the file being re-opened, which
   * re-adopts the doc wholesale). Because it is a permanent divergence we drop
   * ONLY the exact ops the refused frame carried — never a range, never the
   * rest of the log, and never anything when the frame couldn't be identified.
   */
  refused(code: RefusalCode, ops: Op[] | null, opts?: { snapshot?: boolean }) {
    const doomed = ops ?? []
    if (doomed.length) {
      const keys = new Set(doomed.map((o) => `${o.a}:${o.s}`))
      this.log = this.log.filter((o) => !keys.has(`${o.a}:${o.s}`))
    }
    this.emitNotice({
      code,
      permanent: code !== 'rate-limited',
      ops: doomed.length,
      ...(this.host.carriesMedia(doomed) ? { media: true } : {}),
      ...(opts?.snapshot ? { snapshot: true } : {}),
    })
  }

  // --- snapshots (online catch-up + file-fork merge) ------------------------

  /**
   * A doc clone SAFE to put in a relay snapshot frame. Inline assets larger than
   * BLOB_INLINE_MAX are DROPPED — exactly as crdt.ts diffDoc keeps them out of
   * ops — because they travel as blobs (offloadAssets) and the receiver
   * materialises them with resolveBlobs. Without this, a photo-heavy deck's
   * snapshot inlines the whole asset table and the frame text (after JSON +
   * AES-GCM + base64) exceeds the relay's MAX_FRAME, so the relay refuses it
   * 'too-large'; since a snapshot is never acked no op matches the refusal and
   * the editor showed the wrong per-change limit. `blobs` is left intact so the
   * references survive. See docs/DECISIONS.md and docs/blob-offload.md.
   */
  private snapshotDoc(): SyncDoc {
    const doc = JSON.parse(JSON.stringify(this.store.doc)) as SyncDoc
    // A snapshot is readable by EVERY room-key holder, readers included, but the
    // live doc carries this device's whole collab block (owner / writer private
    // keys, invite material). So every never-synced field leaves the snapshot:
    // the engine's skipDoc set, unconditionally and map-independently, apart
    // from the structural container. Receivers lose nothing — mergeSnapshot only
    // copies keys that have a register, and skipDoc keys never get one.
    const skip = this.state.S.skipDoc
    const rec = doc as unknown as Record<string, unknown>
    for (const k of Object.keys(rec)) if (skip.has(k) && k !== this.state.S.parents) delete rec[k]
    const assets = doc.assets
    if (assets)
      for (const [k, v] of Object.entries(assets))
        if (typeof v === 'string' && v.length > BLOB_INLINE_MAX) delete assets[k]
    return doc
  }

  /** The sync state as a snapshot may carry it: the doc-level registers of every
   *  key snapshotDoc() strips are dropped too — a register whose value is missing
   *  from the snapshot doc would read to a receiver's mergeSnapshot as a DELETE. */
  private snapshotState(): SyncStateJSON {
    const j = JSON.parse(JSON.stringify(this.state.toJSON())) as SyncStateJSON
    const skip = this.state.S.skipDoc
    const regs: SyncStateJSON['regs'] = {}
    for (const [rk, r] of Object.entries(j.regs ?? {})) {
      if (rk.startsWith(`${DOC_NODE} `) && skip.has(rk.slice(DOC_NODE.length + 1))) continue
      regs[rk] = r
    }
    j.regs = regs
    return j
  }

  /** THE snapshot builder. Every path that sends a snapshot off this peer — the
   *  relay upload (snapshot()), the hello re-snap, the fork broadcast, and the
   *  flush-time fork snap — builds from this and from nothing else. */
  private snapshotPair(): { doc: SyncDoc; state: SyncStateJSON } {
    return { doc: this.snapshotDoc(), state: this.snapshotState() }
  }

  /** current (doc, sync-state) pair for an encrypted relay snapshot */
  snapshot(): { doc: SyncDoc; state: SyncStateJSON } {
    this.flush()
    return this.snapshotPair()
  }

  /** How many inline assets are still awaiting blob offload — over
   *  BLOB_INLINE_MAX and without a published `blobs` reference yet. While this is
   *  > 0 a joining collaborator may see those pictures blank until the reference
   *  syncs, so the editor can surface "N pictures still uploading". Cheap: one
   *  pass over the asset table. */
  pendingBlobUploads(): number {
    const doc = this.store.doc
    const assets = doc.assets ?? {}
    let n = 0
    for (const [k, v] of Object.entries(assets))
      if (typeof v === 'string' && v.length > BLOB_INLINE_MAX && !doc.blobs?.[k]) n++
    return n
  }

  /** merge a remote snapshot (relay replay for far-behind joiners) */
  applySnapshot(rdoc: SyncDoc, rstate: SyncStateJSON) {
    if (!rstate || rstate.v !== SYNC_V) return // pre-v2 room snapshot — unusable
    this.flush()
    this.applying = true
    const view = this.host.captureView?.()
    try {
      const res = this.state.mergeSnapshot(this.store.doc, rdoc, rstate)
      if (res.changed) {
        this.afterRemoteChange(true, view)
        // We absorbed register-only state a snapshot carried — it isn't in our
        // log, so a peer that joins later can't learn it from our catch-up. Carry
        // it onward: re-snap new peers too (bounded once-per-peer, see 'hello').
        // This is what converges a 3-tab offline chain (A forks, B merges A, C
        // joins asking B) over replay-less BroadcastChannel.
        this.carriesForkState = true
      }
    } finally {
      this.applying = false
    }
  }

  /** re-announce (an online transport reconnected) */
  hello() {
    this.broadcast({ t: 'hello', a: this.actor, vv: this.state.vv, p: this.presence() })
    if (this.forkPending) {
      // rejoining offline fork: our contributions live in doc values +
      // restored registers, not ops — a state snapshot is how they travel
      const s = this.snapshot()
      this.broadcast({ t: 'snap', a: this.actor, doc: s.doc, state: s.state })
    }
  }

  /**
   * Relay replay finished. `seen` holds the (actor,seq) pairs the room
   * already has; anything in our log it lacks gets (re)sent for persistence
   * — covers ops minted before the transport connected. Returns whether a
   * fresh server snapshot should be uploaded (fork just merged).
   */
  onRelayReady(seen: Set<string>): boolean {
    const missing = this.log.filter((o) => !seen.has(`${o.a}:${o.s}`))
    if (missing.length) this.send({ t: 'ops', a: this.actor, ops: missing })
    const fork = this.forkPending
    this.forkPending = false
    return fork
  }

  /**
   * Stamp the CRDT state into doc.collab.sync so the SAVED file can rejoin
   * as a true fork later. Called by the save/serialize paths; only shared
   * documents carry it (never-shared files stay clean).
   */
  stampInto(doc: SyncDoc) {
    if (!doc.collab || doc.collab.on === false) return
    this.flush()
    doc.collab.sync = copy(this.state.toJSON())
  }

  // --- plumbing -------------------------------------------------------------

  private send(frame: Frame) {
    const stamped = { ...frame, pv: SYNC_V }
    for (const tr of this.transports) tr.send(stamped)
  }

  private broadcast(frame: Frame) {
    this.send(frame)
  }
}