@adea-ai/spatial 0.112.0 → 0.113.0

package/src/sim-bridge/scene.ts

@@ -0,0 +1,679 @@
+import { boundedString, isPlainRecord, strictRecord } from './record'
+import type { OriginAllowlist } from './origin'
+import { SIM_BRIDGE_CHANNEL, SIM_BRIDGE_VERSION, type SimMessageEventLike } from './messages'
+
+/**
+ * The workspace scene channel of the Agent Sim bridge (M26, #24, #25, #489, #27). The host feeds
+ * the engine the workspace scene that Virtual view already draws: areas, agents, lead turn and
+ * child-job markers, and lead routes, as a full snapshot and then as diffs against the last
+ * revision the engine acknowledged. The engine renders it and never writes it back: there is no
+ * scene message from the frame other than an acknowledgement, a refusal and a measurement.
+ *
+ * Spec: docs/specs/sim-bridge-scene.md. Rules the code holds:
+ * - Scene messages share the bridge envelope (channel, version, per-mount bridgeId) and its
+ *   origin/source checks, with their own size budget (`MAX_SCENE_MESSAGE_BYTES`).
+ * - One revision is in flight at a time. While it is unacknowledged, newer scene states coalesce:
+ *   the next diff is computed from the acknowledged state to the newest one.
+ * - A diff names the revision it applies to. The engine refuses a diff whose base is not its
+ *   current revision (`revision_gap`), and the host answers with a full snapshot.
+ * - An ack that names any revision other than the one in flight is ignored.
+ * - No ack within `ackTimeoutMs`, an `invalid` or `too_large` refusal, or a gap, resends a full
+ *   snapshot, backing off; `busy` waits `retryAfterMs` (bounded) and resends; `version_unsupported`
+ *   stops the feed.
+ */
+export const SIM_SCENE_VERSION = 1
+/** A scene message, JSON-encoded, may not exceed this. Snapshots are split into parts. */
+export const MAX_SCENE_MESSAGE_BYTES = 64 * 1024
+export const MAX_SCENE_ENTITIES_PER_MESSAGE = 200
+/** The largest scene the host transmits or records as acknowledged. */
+export const MAX_SCENE_ENTITIES = 5_000
+
+const encoder = new TextEncoder()
+const encodedBytes = (value: object) => encoder.encode(JSON.stringify(value)).byteLength
+
+export const SIM_SCENE_KINDS = ['workspace', 'area', 'agent', 'turn', 'child_job', 'route'] as const
+export type SimSceneKind = (typeof SIM_SCENE_KINDS)[number]
+export const SIM_SCENE_STATUSES = [
+  'error',
+  'awaiting_input',
+  'working',
+  'queued',
+  'offline',
+  'unavailable',
+  'idle',
+  'completed',
+  'cancelled',
+  'archived',
+] as const
+export type SimSceneStatus = (typeof SIM_SCENE_STATUSES)[number]
+export const SIM_SCENE_ANIMATIONS = ['rest', 'work', 'wait', 'alert', 'celebrate', 'sleep'] as const
+export type SimSceneAnimation = (typeof SIM_SCENE_ANIMATIONS)[number]
+export const SIM_SCENE_TONES = [
+  'neutral',
+  'active',
+  'attention',
+  'danger',
+  'success',
+  'muted',
+] as const
+export type SimSceneTone = (typeof SIM_SCENE_TONES)[number]
+
+/**
+ * One scene entity on the wire. Ids are the scene graph's stable ids (`agent:<id>`,
+ * `conversation:<id>`, `turn:<intentId>`, ...; a route is `route:<turn id>`), so the same backend
+ * object is the same engine object across reloads. Coordinates are map units: the engine places
+ * its world from them and may scale, but keeps relative placement.
+ */
+export type SimSceneEntity = Readonly<{
+  id: string
+  kind: SimSceneKind
+  /** The containing entity; absent only for the workspace. */
+  parentId?: string
+  label: string
+  status: SimSceneStatus
+  animation: SimSceneAnimation
+  tone: SimSceneTone
+  /** Areas and the workspace commons. */
+  rect?: Readonly<{ x: number; y: number; width: number; height: number }>
+  /** Agents, turns and child jobs. */
+  at?: Readonly<{ x: number; y: number }>
+  /** Agents. */
+  role?: 'lead' | 'agent'
+  characterRef?: string
+  /** No character reference: the engine shows its explicit default character. */
+  fallback?: boolean
+  /** Routes: from an agent to a turn marker. */
+  from?: string
+  to?: string
+  lead?: boolean
+}>
+
+export type SimHostSceneMessage =
+  | Readonly<{
+      type: 'host.scene.snapshot'
+      payload: Readonly<{
+        sceneVersion: typeof SIM_SCENE_VERSION
+        workspaceId: string
+        revision: number
+        /** 1-based part of `parts`. The engine applies the snapshot once every part arrived. */
+        part: number
+        parts: number
+        entities: readonly SimSceneEntity[]
+      }>
+    }>
+  | Readonly<{
+      type: 'host.scene.diff'
+      payload: Readonly<{
+        sceneVersion: typeof SIM_SCENE_VERSION
+        workspaceId: string
+        baseRevision: number
+        revision: number
+        upserts: readonly SimSceneEntity[]
+        removes: readonly string[]
+      }>
+    }>
+
+export const SIM_SCENE_REFUSALS = [
+  'revision_gap',
+  'invalid',
+  'too_large',
+  'version_unsupported',
+  'busy',
+] as const
+export type SimSceneRefusal = (typeof SIM_SCENE_REFUSALS)[number]
+
+/** What the engine measured for the scene, for #27's budgets. Durations in ms, memory in bytes. */
+export type SimScenePerf = Readonly<{
+  revision: number
+  sampleWindowMs: number
+  frames: number
+  frameP50Ms: number
+  frameP95Ms: number
+  frameMaxMs: number
+  /** Frames over 50 ms in the window. */
+  longFrames: number
+  /** From the first snapshot part to the first frame drawn with it. */
+  loadMs: number
+  /** How long the last applied revision took to apply. */
+  applyMs: number
+  entities: number
+  /** `performance.memory.usedJSHeapSize` where the browser exposes it. */
+  heapBytes?: number
+  /** The renderer's own estimate of GPU memory (geometries + textures), when it keeps one. */
+  gpuBytes?: number
+}>
+
+export type SimFrameSceneMessage =
+  | Readonly<{ type: 'frame.scene.ack'; payload: Readonly<{ revision: number }> }>
+  | Readonly<{
+      type: 'frame.scene.nack'
+      payload: Readonly<{ revision: number; code: SimSceneRefusal; retryAfterMs?: number }>
+    }>
+  | Readonly<{ type: 'frame.scene.perf'; payload: SimScenePerf }>
+
+const REVISION_MAX = Number.MAX_SAFE_INTEGER
+const isRevision = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= REVISION_MAX
+const isMeasure = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1e13
+
+const PERF_REQUIRED = [
+  'revision',
+  'sampleWindowMs',
+  'frames',
+  'frameP50Ms',
+  'frameP95Ms',
+  'frameMaxMs',
+  'longFrames',
+  'loadMs',
+  'applyMs',
+  'entities',
+] as const
+
+/** Reads the payload of a `frame.scene.*` message; null when it is not exactly that shape. */
+export function parseFrameScenePayload(
+  type: string,
+  payload: unknown
+): SimFrameSceneMessage | null {
+  switch (type) {
+    case 'frame.scene.ack': {
+      const body = strictRecord(payload, ['revision'])
+      return body && isRevision(body.revision)
+        ? { type, payload: { revision: body.revision } }
+        : null
+    }
+    case 'frame.scene.nack': {
+      const body = strictRecord(payload, ['revision', 'code'], ['retryAfterMs'])
+      const code = SIM_SCENE_REFUSALS.find((item) => item === body?.code)
+      if (!body || !code || !isRevision(body.revision)) return null
+      if ('retryAfterMs' in body && (code !== 'busy' || !isMeasure(body.retryAfterMs))) return null
+      return {
+        type,
+        payload: {
+          revision: body.revision,
+          code,
+          ...(typeof body.retryAfterMs === 'number' ? { retryAfterMs: body.retryAfterMs } : {}),
+        },
+      }
+    }
+    case 'frame.scene.perf': {
+      const body = strictRecord(payload, PERF_REQUIRED, ['heapBytes', 'gpuBytes'])
+      if (!body || !isRevision(body.revision)) return null
+      for (const key of [...PERF_REQUIRED, 'heapBytes', 'gpuBytes'])
+        if (key in body && !isMeasure(body[key])) return null
+      return { type, payload: body as SimScenePerf }
+    }
+    default:
+      return null
+  }
+}
+
+function sceneEnvelope(bridgeId: string, message: SimHostSceneMessage) {
+  return {
+    channel: SIM_BRIDGE_CHANNEL,
+    version: SIM_BRIDGE_VERSION,
+    bridgeId,
+    type: message.type,
+    payload: message.payload,
+  } as const
+}
+
+type PostTarget = Readonly<{ postMessage(message: unknown, targetOrigin: string): void }>
+
+/** Host to frame, for scene messages. Same origin rule as `postToFrame`, and a size bound. */
+export function postSceneToFrame(
+  frameWindow: PostTarget,
+  frameOrigin: string,
+  origins: OriginAllowlist,
+  bridgeId: string,
+  message: SimHostSceneMessage
+): void {
+  if (!origins.has(frameOrigin)) throw new Error('Refusing to post to an unlisted Agent Sim origin')
+  const envelope = sceneEnvelope(bridgeId, message)
+  if (encodedBytes(envelope) > MAX_SCENE_MESSAGE_BYTES)
+    throw new Error('Agent Sim scene message is over its size budget')
+  frameWindow.postMessage(envelope, frameOrigin)
+}
+
+const ID = /^[a-z_]+:[A-Za-z0-9_.:-]{1,160}$/
+const LABEL_MAX = 200
+const REF = /^[\x21-\x7e]{1,512}$/
+const COORD_MAX = 1e6
+
+const isCoord = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= COORD_MAX
+
+function readEntity(value: unknown): SimSceneEntity | null {
+  const body = strictRecord(
+    value,
+    ['id', 'kind', 'label', 'status', 'animation', 'tone'],
+    ['parentId', 'rect', 'at', 'role', 'characterRef', 'fallback', 'from', 'to', 'lead']
+  )
+  if (!body) return null
+  const kind = SIM_SCENE_KINDS.find((item) => item === body.kind)
+  const status = SIM_SCENE_STATUSES.find((item) => item === body.status)
+  const animation = SIM_SCENE_ANIMATIONS.find((item) => item === body.animation)
+  const tone = SIM_SCENE_TONES.find((item) => item === body.tone)
+  const id = boundedString(body.id, ID)
+  if (!kind || !status || !animation || !tone || !id) return null
+  if (typeof body.label !== 'string' || body.label.length > LABEL_MAX) return null
+  if ('parentId' in body && !boundedString(body.parentId, ID)) return null
+  if ('rect' in body) {
+    const rect = strictRecord(body.rect, ['x', 'y', 'width', 'height'])
+    if (!rect || ![rect.x, rect.y, rect.width, rect.height].every(isCoord)) return null
+  }
+  if ('at' in body) {
+    const at = strictRecord(body.at, ['x', 'y'])
+    if (!at || !isCoord(at.x) || !isCoord(at.y)) return null
+  }
+  if ('role' in body && body.role !== 'lead' && body.role !== 'agent') return null
+  if ('characterRef' in body && !boundedString(body.characterRef, REF)) return null
+  if ('fallback' in body && typeof body.fallback !== 'boolean') return null
+  if ('lead' in body && typeof body.lead !== 'boolean') return null
+  for (const key of ['from', 'to']) if (key in body && !boundedString(body[key], ID)) return null
+  if (kind === 'route' && (!('from' in body) || !('to' in body))) return null
+  return body as SimSceneEntity
+}
+
+function readEntities(value: unknown): SimSceneEntity[] | null {
+  if (!Array.isArray(value) || value.length > MAX_SCENE_ENTITIES_PER_MESSAGE) return null
+  const entities: SimSceneEntity[] = []
+  for (let index = 0; index < value.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, index)
+    if (!descriptor || !('value' in descriptor)) return null
+    const entity = readEntity(descriptor.value)
+    if (!entity) return null
+    entities.push(entity)
+  }
+  return entities
+}
+
+export type SimSceneParseFailure =
+  | 'origin_refused'
+  | 'source_mismatch'
+  | 'not_a_scene_message'
+  | 'bridge_mismatch'
+  | 'version_unsupported'
+  | 'too_large'
+  | 'invalid'
+
+/**
+ * Engine side: accepts a host scene message only from the embedding window at its exact origin,
+ * on this mount's bridge id, in a supported scene version, within budget and with every entity in
+ * shape. The engine answers `invalid`, `too_large` or `version_unsupported` with a `nack`.
+ */
+export function parseHostSceneMessage(
+  event: SimMessageEventLike,
+  context: Readonly<{ parentOrigin: string; parentWindow: unknown; bridgeId: string }>
+):
+  | Readonly<{ ok: true; message: SimHostSceneMessage }>
+  | Readonly<{ ok: false; reason: SimSceneParseFailure }> {
+  const fail = (reason: SimSceneParseFailure) => ({ ok: false, reason }) as const
+  if (event.origin !== context.parentOrigin) return fail('origin_refused')
+  if (event.source == null || event.source !== context.parentWindow) return fail('source_mismatch')
+  const data = strictRecord(event.data, ['channel', 'version', 'bridgeId', 'type', 'payload'])
+  if (!data || data.channel !== SIM_BRIDGE_CHANNEL) return fail('not_a_scene_message')
+  if (data.type !== 'host.scene.snapshot' && data.type !== 'host.scene.diff')
+    return fail('not_a_scene_message')
+  if (data.version !== SIM_BRIDGE_VERSION) return fail('version_unsupported')
+  if (data.bridgeId !== context.bridgeId) return fail('bridge_mismatch')
+  if (!isPlainRecord(data.payload)) return fail('invalid')
+  let size: number
+  try {
+    size = encodedBytes(data)
+  } catch {
+    return fail('invalid')
+  }
+  if (size > MAX_SCENE_MESSAGE_BYTES) return fail('too_large')
+  if (data.payload.sceneVersion !== SIM_SCENE_VERSION) return fail('version_unsupported')
+  if (data.type === 'host.scene.snapshot') {
+    const body = strictRecord(data.payload, [
+      'sceneVersion',
+      'workspaceId',
+      'revision',
+      'part',
+      'parts',
+      'entities',
+    ])
+    const entities = readEntities(body?.entities)
+    if (
+      !body ||
+      !entities ||
+      typeof body.workspaceId !== 'string' ||
+      !isRevision(body.revision) ||
+      !Number.isSafeInteger(body.parts) ||
+      !Number.isSafeInteger(body.part) ||
+      (body.part as number) < 1 ||
+      (body.part as number) > (body.parts as number) ||
+      (body.parts as number) > MAX_SCENE_ENTITIES
+    )
+      return fail('invalid')
+    return {
+      ok: true,
+      message: {
+        type: 'host.scene.snapshot',
+        payload: {
+          sceneVersion: SIM_SCENE_VERSION,
+          workspaceId: body.workspaceId,
+          revision: body.revision,
+          part: body.part as number,
+          parts: body.parts as number,
+          entities,
+        },
+      },
+    }
+  }
+  const body = strictRecord(data.payload, [
+    'sceneVersion',
+    'workspaceId',
+    'baseRevision',
+    'revision',
+    'upserts',
+    'removes',
+  ])
+  const upserts = readEntities(body?.upserts)
+  const removes = body?.removes
+  if (
+    !body ||
+    !upserts ||
+    typeof body.workspaceId !== 'string' ||
+    !isRevision(body.baseRevision) ||
+    !isRevision(body.revision) ||
+    body.revision <= body.baseRevision ||
+    !Array.isArray(removes) ||
+    removes.length > MAX_SCENE_ENTITIES_PER_MESSAGE ||
+    !removes.every((id) => boundedString(id, ID))
+  )
+    return fail('invalid')
+  return {
+    ok: true,
+    message: {
+      type: 'host.scene.diff',
+      payload: {
+        sceneVersion: SIM_SCENE_VERSION,
+        workspaceId: body.workspaceId,
+        baseRevision: body.baseRevision,
+        revision: body.revision,
+        upserts,
+        removes: removes as string[],
+      },
+    },
+  }
+}
+
+export type SimSceneFeedState =
+  | 'idle'
+  | 'sending'
+  | 'synced'
+  | 'backing_off'
+  | 'stopped'
+  | 'disposed'
+
+export type SimSceneFeedStats = Readonly<{
+  state: SimSceneFeedState
+  /** The revision the engine last acknowledged; 0 before the first. */
+  ackedRevision: number
+  snapshots: number
+  diffs: number
+  timeouts: number
+  refusals: number
+  /** Acks naming a revision that was not in flight. */
+  ignoredAcks: number
+  lastPerf: SimScenePerf | null
+}>
+
+export type SimSceneFeedOptions = Readonly<{
+  workspaceId: string
+  send(message: SimHostSceneMessage): void
+  onPerf?(perf: SimScenePerf): void
+  ackTimeoutMs?: number
+  /** Schedules `run` after `ms` and returns a canceller. */
+  schedule?: (run: () => void, ms: number) => () => void
+}>
+
+export type SimSceneFeed = Readonly<{
+  /** The newest scene. It is sent now, or coalesced into the next send after the pending ack. */
+  update(entities: readonly SimSceneEntity[]): void
+  /** A validated `frame.scene.*` message from the current frame. */
+  receive(message: SimFrameSceneMessage): void
+  stats(): SimSceneFeedStats
+  dispose(): void
+}>
+
+const DEFAULT_ACK_TIMEOUT_MS = 5_000
+const BACKOFF_MIN_MS = 500
+const BACKOFF_MAX_MS = 30_000
+
+function defaultSchedule(run: () => void, ms: number): () => void {
+  const id = setTimeout(run, ms)
+  return () => clearTimeout(id)
+}
+
+function sameEntity(a: SimSceneEntity, b: SimSceneEntity) {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+/**
+ * The host side of the scene channel: keeps what the engine acknowledged, sends one revision at a
+ * time, and recovers from refusals, gaps and silence by resending a full snapshot with backoff.
+ */
+export function createSimSceneFeed(options: SimSceneFeedOptions): SimSceneFeed {
+  const schedule = options.schedule ?? defaultSchedule
+  const ackTimeoutMs = Math.min(
+    Math.max(options.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS, 250),
+    60_000
+  )
+  let desired: ReadonlyMap<string, SimSceneEntity> | null = null
+  let acked = new Map<string, SimSceneEntity>()
+  let ackedRevision = 0
+  let nextRevision = 1
+  let needSnapshot = true
+  let inFlight: { revision: number; target: ReadonlyMap<string, SimSceneEntity> } | null = null
+  let cancelTimer: (() => void) | undefined
+  let state: SimSceneFeedState = 'idle'
+  let failures = 0
+  const counts = { snapshots: 0, diffs: 0, timeouts: 0, refusals: 0, ignoredAcks: 0 }
+  let lastPerf: SimScenePerf | null = null
+
+  const clearTimer = () => {
+    cancelTimer?.()
+    cancelTimer = undefined
+  }
+  const backOff = (ms: number) => {
+    clearTimer()
+    state = 'backing_off'
+    cancelTimer = schedule(() => {
+      cancelTimer = undefined
+      state = 'idle'
+      pump()
+    }, ms)
+  }
+  const retryLater = () => {
+    const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * 2 ** failures)
+    failures += 1
+    backOff(delay)
+  }
+
+  function pump() {
+    if (state === 'disposed' || state === 'stopped' || state === 'backing_off') return
+    if (inFlight || !desired) return
+    const target = desired
+    const messages: SimHostSceneMessage[] = []
+    const revision = nextRevision
+    if (needSnapshot) {
+      const entities = [...target.values()]
+      const chunks: SimSceneEntity[][] = [[]]
+      // Reserve the maximum bridge id (64 characters) and part-number widths.
+      // Count each entity once, rather than serializing every growing candidate chunk.
+      const overhead = encodedBytes(
+        sceneEnvelope('x'.repeat(64), {
+          type: 'host.scene.snapshot',
+          payload: {
+            sceneVersion: SIM_SCENE_VERSION,
+            workspaceId: options.workspaceId,
+            revision,
+            part: MAX_SCENE_ENTITIES,
+            parts: MAX_SCENE_ENTITIES,
+            entities: [],
+          },
+        })
+      )
+      let chunk = chunks[0]!
+      let bytes = overhead
+      for (const entity of entities) {
+        const entityBytes = encodedBytes(entity)
+        if (overhead + entityBytes > MAX_SCENE_MESSAGE_BYTES)
+          throw new Error('Agent Sim scene entity is over its size budget')
+        if (
+          chunk.length > 0 &&
+          (chunk.length === MAX_SCENE_ENTITIES_PER_MESSAGE ||
+            bytes + 1 + entityBytes > MAX_SCENE_MESSAGE_BYTES)
+        ) {
+          chunk = []
+          chunks.push(chunk)
+          bytes = overhead
+        }
+        bytes += entityBytes + (chunk.length > 0 ? 1 : 0)
+        chunk.push(entity)
+      }
+      for (const [index, partEntities] of chunks.entries())
+        messages.push({
+          type: 'host.scene.snapshot',
+          payload: {
+            sceneVersion: SIM_SCENE_VERSION,
+            workspaceId: options.workspaceId,
+            revision,
+            part: index + 1,
+            parts: chunks.length,
+            entities: partEntities,
+          },
+        })
+    } else {
+      const upserts: SimSceneEntity[] = []
+      const removes: string[] = []
+      for (const [id, entity] of target) {
+        const old = acked.get(id)
+        if (!old || !sameEntity(old, entity)) upserts.push(entity)
+      }
+      for (const id of acked.keys()) if (!target.has(id)) removes.push(id)
+      if (upserts.length === 0 && removes.length === 0) {
+        state = 'synced'
+        return
+      }
+      // A change too big for one message is cheaper as a snapshot than as a split diff.
+      if (
+        upserts.length > MAX_SCENE_ENTITIES_PER_MESSAGE ||
+        removes.length > MAX_SCENE_ENTITIES_PER_MESSAGE
+      ) {
+        needSnapshot = true
+        pump()
+        return
+      }
+      const message: SimHostSceneMessage = {
+        type: 'host.scene.diff',
+        payload: {
+          sceneVersion: SIM_SCENE_VERSION,
+          workspaceId: options.workspaceId,
+          baseRevision: ackedRevision,
+          revision,
+          upserts,
+          removes,
+        },
+      }
+      if (encodedBytes(sceneEnvelope('x'.repeat(64), message)) > MAX_SCENE_MESSAGE_BYTES) {
+        needSnapshot = true
+        pump()
+        return
+      }
+      messages.push(message)
+    }
+    nextRevision += 1
+    // In flight before the first post: an engine may answer synchronously.
+    inFlight = { revision, target }
+    state = 'sending'
+    clearTimer()
+    cancelTimer = schedule(() => {
+      cancelTimer = undefined
+      if (!inFlight || inFlight.revision !== revision) return
+      counts.timeouts += 1
+      inFlight = null
+      needSnapshot = true
+      retryLater()
+    }, ackTimeoutMs)
+    if (messages[0]!.type === 'host.scene.snapshot') counts.snapshots += 1
+    else counts.diffs += 1
+    try {
+      for (const message of messages) {
+        // An answer that arrived mid-snapshot ended this revision; stop sending its parts.
+        if (inFlight?.revision !== revision && messages.length > 1) break
+        options.send(message)
+      }
+    } catch {
+      if (inFlight?.revision === revision) {
+        clearTimer()
+        inFlight = null
+        needSnapshot = true
+        retryLater()
+      }
+    }
+  }
+
+  return {
+    update(entities) {
+      if (state === 'disposed') return
+      const next = new Map(entities.map((entity) => [entity.id, entity]))
+      // Acknowledgements must describe exactly the bounded scene sent to the engine.
+      desired =
+        next.size <= MAX_SCENE_ENTITIES ? next : new Map([...next].slice(0, MAX_SCENE_ENTITIES))
+      pump()
+    },
+    receive(message) {
+      if (state === 'disposed') return
+      if (message.type === 'frame.scene.perf') {
+        lastPerf = message.payload
+        options.onPerf?.(message.payload)
+        return
+      }
+      if (!inFlight || message.payload.revision !== inFlight.revision) {
+        counts.ignoredAcks += 1
+        return
+      }
+      clearTimer()
+      const { revision, target } = inFlight
+      inFlight = null
+      if (message.type === 'frame.scene.ack') {
+        acked = new Map(target)
+        ackedRevision = revision
+        needSnapshot = false
+        failures = 0
+        state = 'idle'
+        pump()
+        if (!inFlight && (state as SimSceneFeedState) === 'idle') state = 'synced'
+        return
+      }
+      counts.refusals += 1
+      switch (message.payload.code) {
+        case 'version_unsupported':
+          state = 'stopped'
+          return
+        case 'busy':
+          backOff(Math.min(Math.max(message.payload.retryAfterMs ?? BACKOFF_MIN_MS, 100), 10_000))
+          return
+        default:
+          needSnapshot = true
+          retryLater()
+      }
+    },
+    stats: () => ({
+      state,
+      ackedRevision,
+      ...counts,
+      lastPerf,
+    }),
+    dispose() {
+      clearTimer()
+      inFlight = null
+      state = 'disposed'
+    },
+  }
+}