@pascal-app/editor 1.0.4 → 1.0.6

package/src/lib/point-ask/build-context.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNode, PointContext } from '@pascal-app/core'
+import { house, LEVEL_ID } from './__fixtures__/house'
+import { type BuildPointContextInput, buildPointContext } from './build-context'
+
+// What the agent receives when the person points (spec section 5): ids first, in metres, the camera
+// the person saw. Written first: an id the agent cannot read back; a size in the viewer's unit
+// instead of metres; a target dropped past a preview limit; an orthographic camera with no width, a
+// perspective one with a stray one; fields present as `undefined` where there is nothing to say.
+
+const CAMERA = {
+  position: [6.2, 4.1, 7.5] as [number, number, number],
+  target: [2, 1, 1.5] as [number, number, number],
+  fov: 50,
+  aspect: 1.6,
+  projection: 'perspective' as const,
+}
+
+const nodes = house()
+const when = new Date('2026-10-08T01:02:03.000Z')
+
+const build = (over: Partial<BuildPointContextInput> = {}): PointContext =>
+  buildPointContext({
+    askId: 'ask_1',
+    capturedAt: when,
+    gesture: 'click',
+    nodes,
+    levelId: LEVEL_ID,
+    camera: CAMERA,
+    targets: [{ id: 'zone_kitchen' }],
+    ...over,
+  })
+
+describe('the context of a click on a room', () => {
+  const context = build()
+
+  test('names itself, its ask, its moment and its surface', () => {
+    expect(context).toMatchObject({
+      kind: 'scene-point',
+      version: 1,
+      askId: 'ask_1',
+      capturedAt: '2026-10-08T01:02:03.000Z',
+      source: 'editor',
+      gesture: 'click',
+      level: { id: 'level_0', name: 'Level 0' },
+    })
+  })
+
+  test('carries the room by id, with its name, level, size in metres and box', () => {
+    const [kitchen] = context.targets
+
+    expect(kitchen).toMatchObject({
+      id: 'zone_kitchen',
+      type: 'zone',
+      name: 'Kitchen',
+      levelId: 'level_0',
+      size: { area: 12, width: 4, depth: 3 },
+    })
+    expect(kitchen!.box.min[0]).toBeCloseTo(0, 6)
+    expect(kitchen!.box.max[0]).toBeCloseTo(4, 6)
+    expect(kitchen!.box.min[2]).toBeCloseTo(0, 6)
+    expect(kitchen!.box.max[2]).toBeCloseTo(3, 6)
+    expect(kitchen!.box.max[1]).toBeGreaterThan(kitchen!.box.min[1])
+  })
+
+  test('the camera is the one the person saw, as view_scene takes it', () => {
+    expect(context.camera).toEqual(CAMERA)
+    expect('viewWidth' in context.camera).toBe(false)
+  })
+
+  test('says nothing it has nothing to say about', () => {
+    for (const key of ['inRegion', 'region', 'image', 'suggestion'])
+      expect(key in context, key).toBe(false)
+    expect('hit' in context.targets[0]!).toBe(false)
+  })
+})
+
+describe('targets', () => {
+  test('a window: its wall as parent, its room, the finger’s hit, its sill', () => {
+    const hit = {
+      point: [2, 1.4, 0] as [number, number, number],
+      normal: [0, 0, -1] as [number, number, number],
+      face: 'exterior' as const,
+    }
+    const [window] = build({ targets: [{ id: 'window_north', hit }] }).targets
+
+    expect(window).toMatchObject({
+      id: 'window_north',
+      type: 'window',
+      name: 'Window',
+      parentId: 'wall_north',
+      zoneId: 'zone_kitchen',
+      hit,
+    })
+    expect(window!.size.sill).toBeCloseTo(0.7, 6)
+  })
+
+  test('a wall and an item', () => {
+    const [wall, sofa] = build({ targets: [{ id: 'wall_north' }, { id: 'item_sofa' }] }).targets
+
+    expect(wall).toMatchObject({ type: 'wall', zoneId: 'zone_kitchen' })
+    expect(wall!.size.length).toBeCloseTo(4, 6)
+    expect(sofa).toMatchObject({ type: 'item', name: 'Sofa' })
+    expect(sofa!.size).toEqual({ width: 2.1, depth: 0.95, height: 0.85 })
+  })
+
+  test('the viewer’s unit never reaches the context: sizes are metres', () => {
+    const [window] = build({ targets: [{ id: 'window_north' }] }).targets
+
+    expect(window!.size.width).toBeCloseTo(1.2, 6)
+  })
+
+  test('a dozen and more all arrive, each by its own id (no preview limit)', () => {
+    const extra: AnyNode[] = Array.from(
+      { length: 14 },
+      (_, i) =>
+        ({
+          ...(nodes.item_sofa as object),
+          id: `item_chair_${i}`,
+          name: 'Chair',
+        }) as unknown as AnyNode,
+    )
+    const scene = house(extra)
+    const context = build({
+      nodes: scene,
+      gesture: 'multi',
+      targets: extra.map((node) => ({ id: node.id })),
+    })
+
+    expect(context.targets).toHaveLength(14)
+    expect(new Set(context.targets.map((t) => t.id)).size).toBe(14)
+    expect(context.targets.every((t) => t.name === 'Chair')).toBe(true)
+  })
+
+  test('an element that is gone is left out, never guessed', () => {
+    const context = build({ targets: [{ id: 'zone_kitchen' }, { id: 'wall_gone' }] })
+
+    expect(context.targets.map((t) => t.id)).toEqual(['zone_kitchen'])
+  })
+})
+
+describe('the camera and the picture', () => {
+  test('an orthographic camera carries its view width, a perspective one does not', () => {
+    const ortho = build({ camera: { ...CAMERA, projection: 'orthographic', viewWidth: 14 } })
+
+    expect(ortho.camera).toMatchObject({ projection: 'orthographic', viewWidth: 14 })
+    expect('viewWidth' in build({ camera: { ...CAMERA, viewWidth: 14 } }).camera).toBe(false)
+  })
+
+  test('a region is a view, not a selection: its ids ride beside empty targets', () => {
+    const context = build({
+      gesture: 'region',
+      targets: [],
+      region: [0.2, 0.3, 0.6, 0.8],
+      inRegion: { ids: ['wall_north', 'window_north'], more: 3 },
+    })
+
+    expect(context).toMatchObject({
+      gesture: 'region',
+      targets: [],
+      region: [0.2, 0.3, 0.6, 0.8],
+      inRegion: { ids: ['wall_north', 'window_north'], more: 3 },
+    })
+  })
+
+  test('the crop and the suggestion pass through as given', () => {
+    const image = { dataUrl: 'data:image/png;base64,AAAA', width: 640, height: 480, marked: true }
+    const context = build({ image, suggestion: 'make-it-wider' })
+
+    expect(context.image).toEqual(image)
+    expect(context.suggestion).toBe('make-it-wider')
+  })
+})

package/src/lib/point-ask/build-context.ts

@@ -0,0 +1,94 @@
+import type {
+  AnyNode,
+  LevelNode,
+  PointCamera,
+  PointContext,
+  PointTarget as PointContextTarget,
+} from '@pascal-app/core'
+import { sceneViewBounds } from '@pascal-app/core/agent-operations'
+import { describeTarget } from './describe-target'
+
+// What the agent receives when the person points (point-and-ask-spec.md section 5): ids first, in
+// metres, from the camera the person saw. The words stay the person's; this is metadata.
+
+export type BuildPointContextInput = {
+  /** The pin, the chat chip and the turn share it. */
+  askId: string
+  /** The moment of pointing (pointer-down); now when absent. */
+  capturedAt?: Date | string
+  gesture: PointContext['gesture']
+  nodes: Readonly<Record<string, AnyNode>>
+  /** The level in view. */
+  levelId: string
+  /** What the finger is on, each by id, with where it landed. */
+  targets: { id: string; hit?: PointContextTarget['hit'] }[]
+  camera: PointCamera
+  inRegion?: PointContext['inRegion']
+  region?: PointContext['region']
+  image?: PointContext['image']
+  suggestion?: string
+}
+
+type Box = PointContextTarget['box']
+
+/** The element's box as view_scene frames it; a point at its position when that cannot say. */
+function boxOf(nodes: Readonly<Record<string, AnyNode>>, node: AnyNode): Box {
+  try {
+    return sceneViewBounds(nodes, node.id)
+  } catch {
+    const at = (node as { position?: number[] }).position ?? [0, 0, 0]
+    const point: [number, number, number] = [at[0] ?? 0, at[1] ?? 0, at[2] ?? 0]
+    return { min: point, max: point }
+  }
+}
+
+export function buildPointContext(input: BuildPointContextInput): PointContext {
+  const { nodes } = input
+  const level = nodes[input.levelId] as LevelNode | undefined
+  const camera: PointCamera = {
+    position: input.camera.position,
+    target: input.camera.target,
+    fov: input.camera.fov,
+    aspect: input.camera.aspect,
+    projection: input.camera.projection,
+    ...(input.camera.projection === 'orthographic' && input.camera.viewWidth !== undefined
+      ? { viewWidth: input.camera.viewWidth }
+      : {}),
+  }
+
+  const targets: PointContextTarget[] = []
+  for (const { id, hit } of input.targets) {
+    const node = nodes[id]
+    // An element deleted between the pointing and the send is not a target any more.
+    if (!node) continue
+    const described = describeTarget(node, nodes, { unit: 'metric' })
+    targets.push({
+      id: node.id,
+      type: node.type,
+      name: described.name,
+      levelId: described.levelId,
+      ...(described.zoneId ? { zoneId: described.zoneId } : {}),
+      ...(described.parentId ? { parentId: described.parentId } : {}),
+      ...(hit ? { hit } : {}),
+      box: boxOf(nodes, node),
+      size: described.sizes,
+    })
+  }
+
+  const capturedAt = input.capturedAt ?? new Date()
+  return {
+    kind: 'scene-point',
+    version: 1,
+    askId: input.askId,
+    capturedAt: typeof capturedAt === 'string' ? capturedAt : capturedAt.toISOString(),
+    source: 'editor',
+    gesture: input.gesture,
+    level: { id: input.levelId, name: level?.name?.trim() || `Level ${level?.level ?? 0}` },
+    targets,
+    camera,
+    ...(input.inRegion ? { inRegion: input.inRegion } : {}),
+    ...(input.region ? { region: input.region } : {}),
+    ...(input.image ? { image: input.image } : {}),
+    ...(input.suggestion ? { suggestion: input.suggestion } : {}),
+  }
+}

package/src/lib/point-ask/capture-crop.ts

@@ -0,0 +1,129 @@
+import {
+  emitter,
+  type SnapshotCapturedEvent,
+  type SnapshotCaptureFailedEvent,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { canvasRect } from './projector'
+import type { Rect } from './types'
+
+// The picture an ask carries as evidence (spec 2.4): the targets' screen box padded 25%, at least
+// 512 px on its long side, rendered by the snapshot pipeline as an ephemeral frame so nothing is
+// stored. Started at pointer-down, so it is ready by the time the person has typed.
+
+const CROP_LONG_SIDE_MIN = 512
+const CROP_LONG_SIDE_MAX = 768
+const CAPTURE_TIMEOUT_MS = 12_000
+
+export type CapturedCrop = { dataUrl: string; width: number; height: number }
+
+/** The target's box padded by `pad` of its size on every side, and kept inside the canvas. */
+export function paddedCropRect(
+  box: Rect,
+  canvas: { width: number; height: number },
+  pad = 0.25,
+): Rect {
+  const w = Math.max(48, box.x1 - box.x0)
+  const h = Math.max(48, box.y1 - box.y0)
+  const cx = (box.x0 + box.x1) / 2
+  const cy = (box.y0 + box.y1) / 2
+  const half = { x: (w * (1 + pad * 2)) / 2, y: (h * (1 + pad * 2)) / 2 }
+  return {
+    x0: Math.max(0, cx - half.x),
+    y0: Math.max(0, cy - half.y),
+    x1: Math.min(canvas.width, cx + half.x),
+    y1: Math.min(canvas.height, cy + half.y),
+  }
+}
+
+/** A rectangle as 0-1 fractions of the frame, for the snapshot pipeline's `cropRegion`. */
+export function toCropRegion(rect: Rect, canvas: { width: number; height: number }) {
+  return {
+    x: rect.x0 / canvas.width,
+    y: rect.y0 / canvas.height,
+    width: (rect.x1 - rect.x0) / canvas.width,
+    height: (rect.y1 - rect.y0) / canvas.height,
+  }
+}
+
+async function blobToScaledDataUrl(blob: Blob): Promise<CapturedCrop> {
+  const bitmap = await createImageBitmap(blob)
+  const long = Math.max(bitmap.width, bitmap.height)
+  const scale =
+    long > CROP_LONG_SIDE_MAX ? CROP_LONG_SIDE_MAX / long : long < CROP_LONG_SIDE_MIN ? 1 : 1
+  const width = Math.round(bitmap.width * scale)
+  const height = Math.round(bitmap.height * scale)
+  const canvas = document.createElement('canvas')
+  canvas.width = width
+  canvas.height = height
+  const context = canvas.getContext('2d')
+  if (!context) throw new Error('No 2D canvas to scale the picture')
+  context.drawImage(bitmap, 0, 0, width, height)
+  bitmap.close()
+  return { dataUrl: canvas.toDataURL('image/jpeg', 0.84), width, height }
+}
+
+const BUSY = 'Another snapshot is being captured'
+const BUSY_RETRY_MS = 1_500
+
+/**
+ * One crop of the current view over `screenRect` (viewport pixels); once more after 1.5 s when
+ * another capture (the agent's own view) holds the renderer. Rejects when the 3D canvas cannot
+ * answer in time (a hidden tab, a busy renderer): the ask then goes without a picture.
+ */
+export async function captureViewCrop(
+  screenRect: Rect,
+  options: { pad?: number } = {},
+): Promise<CapturedCrop> {
+  try {
+    return await captureOnce(screenRect, options)
+  } catch (error) {
+    if (!(error instanceof Error && error.message.startsWith(BUSY))) throw error
+    await new Promise((resolve) => setTimeout(resolve, BUSY_RETRY_MS))
+    return captureOnce(screenRect, options)
+  }
+}
+
+function captureOnce(screenRect: Rect, options: { pad?: number }): Promise<CapturedCrop> {
+  const rect = canvasRect()
+  const projectId = useViewer.getState().projectId
+  if (!rect || !projectId) return Promise.reject(new Error('The 3D view is not ready'))
+  const local: Rect = {
+    x0: screenRect.x0 - rect.left,
+    y0: screenRect.y0 - rect.top,
+    x1: screenRect.x1 - rect.left,
+    y1: screenRect.y1 - rect.top,
+  }
+  const cropRegion = toCropRegion(paddedCropRect(local, rect, options.pad ?? 0.25), rect)
+  const requestId = `point-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`
+  return new Promise((resolve, reject) => {
+    const stop = () => {
+      clearTimeout(timer)
+      emitter.off('snapshot:captured', onCaptured)
+      emitter.off('snapshot:capture-failed', onFailed)
+    }
+    const onCaptured = (event: SnapshotCapturedEvent) => {
+      if (event.requestId !== requestId) return
+      stop()
+      blobToScaledDataUrl(event.blob).then(resolve, reject)
+    }
+    const onFailed = (event: SnapshotCaptureFailedEvent) => {
+      if (event.requestId !== requestId) return
+      stop()
+      reject(new Error(event.error))
+    }
+    const timer = setTimeout(() => {
+      stop()
+      reject(new Error('No picture came back from the 3D view'))
+    }, CAPTURE_TIMEOUT_MS)
+    emitter.on('snapshot:captured', onCaptured)
+    emitter.on('snapshot:capture-failed', onFailed)
+    emitter.emit('camera-controls:generate-thumbnail', {
+      projectId,
+      requestId,
+      ephemeral: true,
+      captureMode: 'area',
+      cropRegion,
+    })
+  })
+}

package/src/lib/point-ask/choreography.ts

@@ -0,0 +1,69 @@
+// The numbers Point and ask moves by, in one place: the direction's tokens
+// (chat-juice-direction.md), the choreography section of point-and-ask-spec.md, and where the two
+// differ, the prototype's (pascal-builds.html), which the owner played and called the bar.
+
+export const EASE_OUT = 'cubic-bezier(0.23, 1, 0.32, 1)'
+export const EASE_IN_OUT = 'cubic-bezier(0.77, 0, 0.175, 1)'
+
+export type SpringTokens = { damping: number; response: number }
+
+/** Critically damped: the default for anything a person can touch. */
+export const SPRING: SpringTokens = { damping: 1, response: 0.35 }
+/** A little bounce, only for things that carry momentum. */
+export const MOMENTUM: SpringTokens = { damping: 0.8, response: 0.35 }
+/** The outline's four corners travelling between targets. */
+export const CORNER_SPRING: SpringTokens = { damping: 1, response: 0.16 }
+
+// Durations (ms).
+export const PRESS_MS = 120
+export const ENTER_MS = 180
+export const CARD_MS = 220
+/** An exit is quicker than an entrance. */
+export const BUBBLE_CLOSE_MS = 150
+export const CARD_CLOSE_MS = 120
+export const PIN_RETIRE_FADE_MS = 180
+export const CHECK_STROKE_MS = 240
+export const CHECK_PULSE_MS = 380
+export const PIN_DROP_MS = 320
+export const PIN_RING_MS = 560
+export const PIN_RING_DELAY_MS = 160
+// The prototype's flash, longer than the spec's 120 ms: a shutter has to be seen to be felt.
+export const REGION_FLASH_MS = 280
+export const SUGGESTION_STAGGER_MS = 30
+export const SUGGESTION_DELAY_MS = 40
+export const CHIP_FADE_MS = 120
+
+// Thresholds and dwell (ms or px).
+export const CLICK_SLOP_PX = 6
+export const DWELL_MS = 120
+export const SIDE_HYSTERESIS_MS = 150
+export const TAP_LATCH_MS = 200
+export const CARD_AUTO_MS = 4000
+export const CARD_CLOSE_DELAY_MS = 400
+// A card the camera carried from under a still pointer stays this long, for the pointer to reach it.
+export const CARD_CARRIED_MS = 6000
+export const PIN_RETIRE_MS = 8000
+// A press on a done pin that stays down this long shows the scene as it was before the turn.
+export const PIN_HOLD_MS = 220
+// While held, the pointer may drift this far from where it pressed before the hold ends.
+export const PIN_HOLD_SLOP_PX = 36
+export const THIN_TARGET_PX = 6
+
+// Layout (px).
+export const BUBBLE_W = 320
+export const BUBBLE_GAP = 16
+export const VIEWPORT_INSET = 12
+export const BIG_BOX_DISC = 48
+export const MAX_TARGETS = 12
+export const PIN_DISC = 24
+export const PIN_HIT = 32
+export const PIN_HIT_TOUCH = 44
+export const CARD_W = 250
+export const CHIP_OFFSET = 14
+
+// Motion shapes.
+/** The bubble grows from the click: 0.92 -> 1 with opacity and a 4 px blur (the prototype's, not the spec's 0.96). */
+export const BUBBLE_OPEN_SCALE = 0.92
+export const BUBBLE_OPEN_BLUR_PX = 4
+export const PIN_DROP_PX = 8
+export const CHIP_RISE_PX = 4

package/src/lib/point-ask/compare.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from 'bun:test'
+import { createCompare } from './compare'
+
+// Hold a control, see the scene as it was before the turn; let go, and it is back. The preview is
+// the core's (it writes nothing: its own tests say so); what this decides is when one may start,
+// and that it always ends. Written first: a hold that starts under a turn that is writing, or with
+// no state to show; a second hold that leaves the first up; a release that is missed.
+
+const snapshot = { nodes: {} } as never
+
+function setup(options: { before?: unknown; working?: boolean; begin?: unknown } = {}) {
+  const ended: string[] = []
+  const changes: (string | null)[] = []
+  let began = 0
+  const compare = createCompare({
+    before: () => ('before' in options ? (options.before as never) : snapshot),
+    turnsWorking: () => options.working ?? false,
+    begin: () => {
+      began++
+      if (options.begin === null) return null
+      return { end: () => ended.push('end') }
+    },
+    onChange: (askId) => changes.push(askId),
+  })
+  return { compare, ended, changes, began: () => began }
+}
+
+describe('why a hold is refused', () => {
+  test('says a turn is writing', () => {
+    const { compare } = setup({ working: true })
+    compare.start('ask_1')
+    expect(compare.refusal()).toBe('turn-working')
+  })
+
+  test('says history cannot show the before', () => {
+    const { compare } = setup({ before: null })
+    compare.start('ask_1')
+    expect(compare.refusal()).toBe('no-before')
+  })
+
+  test('says the scene is held by something else', () => {
+    const { compare } = setup({ begin: null })
+    compare.start('ask_1')
+    expect(compare.refusal()).toBe('history-held')
+  })
+
+  test('says nothing after a hold that started', () => {
+    const { compare } = setup({ working: true })
+    compare.start('ask_1')
+    const next = setup()
+    next.compare.start('ask_1')
+    expect(next.compare.refusal()).toBeNull()
+  })
+})
+
+describe('start', () => {
+  test('shows the before of that ask and says whose', () => {
+    const { compare, changes } = setup()
+
+    expect(compare.start('ask_1')).toBe(true)
+
+    expect(compare.current()).toBe('ask_1')
+    expect(changes).toEqual(['ask_1'])
+  })
+
+  test('does not start while a turn is writing: it would be swallowed or land on the wrong state', () => {
+    const { compare, began } = setup({ working: true })
+
+    expect(compare.start('ask_1')).toBe(false)
+
+    expect(began()).toBe(0)
+    expect(compare.current()).toBeNull()
+  })
+
+  test('does not start when history cannot say what it was before', () => {
+    const { compare, began } = setup({ before: null })
+
+    expect(compare.start('ask_1')).toBe(false)
+
+    expect(began()).toBe(0)
+  })
+
+  test('does not start when the scene would not take a preview (a gesture holds it)', () => {
+    const { compare, changes } = setup({ begin: null })
+
+    expect(compare.start('ask_1')).toBe(false)
+
+    expect(compare.current()).toBeNull()
+    expect(changes).toEqual([])
+  })
+
+  test('a second hold ends the first before it starts', () => {
+    const { compare, ended, changes } = setup()
+    compare.start('ask_1')
+
+    compare.start('ask_2')
+
+    expect(ended).toEqual(['end'])
+    expect(compare.current()).toBe('ask_2')
+    expect(changes).toEqual(['ask_1', null, 'ask_2'])
+  })
+})
+
+describe('end', () => {
+  test('lets the scene go and clears the tag', () => {
+    const { compare, ended, changes } = setup()
+    compare.start('ask_1')
+
+    compare.end()
+
+    expect(ended).toEqual(['end'])
+    expect(compare.current()).toBeNull()
+    expect(changes).toEqual(['ask_1', null])
+  })
+
+  test('is idempotent: a pointer-up, a blur and a key can all arrive', () => {
+    const { compare, ended, changes } = setup()
+    compare.start('ask_1')
+
+    compare.end()
+    compare.end()
+    compare.end()
+
+    expect(ended).toEqual(['end'])
+    expect(changes).toEqual(['ask_1', null])
+  })
+
+  test('with nothing held is nothing', () => {
+    const { compare, changes } = setup()
+
+    compare.end()
+
+    expect(changes).toEqual([])
+  })
+
+  test('when the scene let go by itself (a write), the tag follows', () => {
+    const { compare, changes } = setup()
+    compare.start('ask_1')
+
+    compare.released()
+
+    expect(compare.current()).toBeNull()
+    expect(changes).toEqual(['ask_1', null])
+  })
+})

package/src/lib/point-ask/compare.ts

@@ -0,0 +1,73 @@
+import type { SceneSnapshot } from '@pascal-app/core'
+
+// Hold a control on a pin or its card to see the scene as it was before that turn (the owner,
+// 8 October: "I hold and I see the previous state in 3D"). The core's scene preview does the
+// showing and writes nothing; this decides when a hold may start and keeps the person's view of it
+// (whose, for the "Before" tag) in step with the preview, which ends on its own when a write is
+// about to land.
+
+export type CompareDeps = {
+  /** The scene as it was before the ask's turn, from the history Undo would restore; null when unknown. */
+  before: (askId: string) => SceneSnapshot | null
+  /** A turn is writing the scene: it would swallow the preview's writes or land on the wrong state. */
+  turnsWorking: () => boolean
+  /** The core's `beginScenePreview`: null when the scene will not take one. */
+  begin: (snapshot: SceneSnapshot) => { end: () => void } | null
+  /** Whose before is on screen, or null: the tag follows. */
+  onChange: (askId: string | null) => void
+}
+
+/** Why a hold did not start, so the person is told instead of left holding a button that does nothing. */
+export type CompareRefusal = 'turn-working' | 'no-before' | 'history-held'
+
+export type Compare = {
+  /** Starts showing that ask's before; false when it may not. Ends a hold already up. */
+  start: (askId: string) => boolean
+  /** Why the last `start` returned false; null after one that started. */
+  refusal: () => CompareRefusal | null
+  /** Lets go. Idempotent. */
+  end: () => void
+  /** The preview ended by itself (a write was about to land): clears the tag. */
+  released: () => void
+  current: () => string | null
+}
+
+export function createCompare(deps: CompareDeps): Compare {
+  let held: { askId: string; preview: { end: () => void } } | null = null
+  let refused: CompareRefusal | null = null
+
+  const set = (askId: string | null) => deps.onChange(askId)
+
+  return {
+    start(askId) {
+      const refuse = (reason: CompareRefusal) => {
+        refused = reason
+        return false
+      }
+      if (deps.turnsWorking()) return refuse('turn-working')
+      const snapshot = deps.before(askId)
+      if (!snapshot) return refuse('no-before')
+      if (held) this.end()
+      const preview = deps.begin(snapshot)
+      if (!preview) return refuse('history-held')
+      refused = null
+      held = { askId, preview }
+      set(askId)
+      return true
+    },
+    end() {
+      if (!held) return
+      const { preview } = held
+      held = null
+      preview.end()
+      set(null)
+    },
+    released() {
+      if (!held) return
+      held = null
+      set(null)
+    },
+    refusal: () => refused,
+    current: () => held?.askId ?? null,
+  }
+}