@pascal-app/editor 1.0.3 → 1.0.5

package/src/lib/point-ask/pin-machine.ts

@@ -0,0 +1,217 @@
+import type { PinState } from './types'
+
+/**
+ * What the chat tells the pin about its ask's turn (the scene/chat boundary agreed with the chat
+ * side: queued, working with the live sentence, and one end with what happened).
+ */
+export type PinStatus =
+  | { askId: string; turnId?: string; status: 'queued' }
+  | { askId: string; turnId?: string; status: 'working'; sentence?: string }
+  /** The turn waits on a question to the person; `working` follows once it is answered. */
+  | { askId: string; turnId?: string; status: 'asking'; question: string }
+  | {
+      askId: string
+      turnId?: string
+      status: 'ended'
+      outcome: 'completed' | 'cancelled' | 'errored'
+      /** The turn ended on a question to the person. */
+      asked: boolean
+      /** The turn made at least one scene-writing tool call. */
+      wroteScene: boolean
+      answer?: string
+      error?: string
+    }
+
+export type PinEvent =
+  | { type: 'sent' }
+  | { type: 'status'; status: PinStatus }
+  /** A scene commit while the ask works; `isInTargets` supplies subtree or room membership. */
+  | {
+      type: 'commit'
+      changedNodeIds: readonly string[]
+      isInTargets?: (id: string) => boolean
+      /** A real semantic commit can write materials or collections without changing any node. */
+      committed?: boolean
+    }
+  | { type: 'undo' }
+  | { type: 'undone'; ok: boolean }
+  /** The person brought the undone ask back (Redo, while nothing else was done). */
+  | { type: 'redo' }
+  | { type: 'keep' }
+
+export type PinModel = {
+  askId: string
+  /** The ask's words, for the pin's tooltip. */
+  text: string
+  targetIds: string[]
+  state: PinState
+  /** The live step words while it works. */
+  sentence?: string
+  /** What Pascal is waiting to be told, while the turn is paused on a question. */
+  question?: string
+  turnId?: string
+  /** The card's title for a done pin, built by the caller from the step sentences. */
+  title?: string
+  answer?: string
+  error?: string
+  /** Steps whose commits touched a target: each is a small pop on the pin. */
+  landed: number
+  changedTargetIds: string[]
+  alsoChangedIds: string[]
+  /** An observed durable scene change, not merely a scene-writing tool being called. */
+  committed: boolean
+  ended: boolean
+  undone: boolean
+  kept: boolean
+}
+
+export function createPin(init: { askId: string; text: string; targetIds: string[] }): PinModel {
+  return {
+    askId: init.askId,
+    text: init.text,
+    targetIds: [...init.targetIds],
+    state: 'sent',
+    landed: 0,
+    changedTargetIds: [],
+    alsoChangedIds: [],
+    committed: false,
+    ended: false,
+    undone: false,
+    kept: false,
+  }
+}
+
+const union = (list: string[], more: readonly string[]) => {
+  const next = [...list]
+  for (const id of more) if (!next.includes(id)) next.push(id)
+  return next.length === list.length ? list : next
+}
+
+const IN_FLIGHT: readonly PinState[] = ['sent', 'queued', 'working']
+/** A turn that waits on a question is still open: it resumes, or ends still asking. */
+const OPEN: readonly PinState[] = [...IN_FLIGHT, 'needs-input']
+
+function reduceStatus(pin: PinModel, status: PinStatus): PinModel {
+  if (status.askId !== pin.askId || pin.ended) return pin
+  const turnId = status.turnId ?? pin.turnId
+  if (status.status === 'queued') {
+    if (pin.state !== 'sent' && pin.state !== 'queued') return pin
+    return { ...pin, state: 'queued', turnId }
+  }
+  if (status.status === 'asking') {
+    if (!OPEN.includes(pin.state)) return pin
+    return { ...pin, state: 'needs-input', turnId, question: status.question }
+  }
+  if (status.status === 'working') {
+    if (!OPEN.includes(pin.state)) return pin
+    const { question: _answered, ...rest } = pin
+    return { ...rest, state: 'working', turnId, sentence: status.sentence ?? pin.sentence }
+  }
+  if (!OPEN.includes(pin.state)) return pin
+  let state: PinState
+  if (status.outcome === 'errored') state = 'error'
+  else if (pin.committed) state = 'done'
+  else if (status.asked) state = 'needs-input'
+  else if (status.outcome === 'cancelled') state = 'no-change'
+  else if (!status.wroteScene && status.answer) state = 'answered'
+  else state = 'no-change'
+  return {
+    ...pin,
+    state,
+    turnId,
+    ended: true,
+    sentence: undefined,
+    ...(pin.sentence ? { title: pin.sentence } : {}),
+    ...(status.answer === undefined ? {} : { answer: status.answer }),
+    ...(status.error === undefined ? {} : { error: status.error }),
+  }
+}
+
+/** The pin's state machine (spec 2.6-2.8): pure, so every transition is a test. */
+export function reducePin(pin: PinModel, event: PinEvent): PinModel {
+  switch (event.type) {
+    case 'sent':
+      return pin
+    case 'status':
+      return reduceStatus(pin, event.status)
+    case 'commit': {
+      if (pin.state !== 'working' || (event.changedNodeIds.length === 0 && !event.committed))
+        return pin
+      const isTarget = (id: string) =>
+        pin.targetIds.includes(id) ||
+        pin.changedTargetIds.includes(id) ||
+        event.isInTargets?.(id) === true
+      const hits = event.changedNodeIds.filter(isTarget)
+      const others = event.changedNodeIds.filter((id) => !isTarget(id))
+      const changedTargetIds = union(pin.changedTargetIds, hits)
+      const also = union(pin.alsoChangedIds, others)
+      const alsoChangedIds = also.some((id) => changedTargetIds.includes(id))
+        ? also.filter((id) => !changedTargetIds.includes(id))
+        : also
+      if (hits.length === 0 && alsoChangedIds === pin.alsoChangedIds && pin.committed) return pin
+      return {
+        ...pin,
+        landed: hits.length > 0 ? pin.landed + 1 : pin.landed,
+        changedTargetIds,
+        alsoChangedIds,
+        committed: true,
+      }
+    }
+    case 'undo':
+      return pin.state === 'done' ? { ...pin, state: 'undone', undone: true } : pin
+    case 'undone':
+      // A failed undo hands the pin back; a good one is already shown.
+      return !event.ok && pin.state === 'undone' && pin.undone
+        ? { ...pin, state: 'done', undone: false }
+        : pin
+    case 'redo':
+      return pin.state === 'undone' && pin.undone ? { ...pin, state: 'done', undone: false } : pin
+    case 'keep':
+      return pin.kept ? pin : { ...pin, kept: true }
+  }
+}
+
+const firstLines = (text: string, count: number) => text.split('\n').slice(0, count).join('\n')
+
+/** The card's headline: the error's words, an answer's first two lines, "Undone", or the title. */
+export function cardTitle(pin: PinModel, fallback = 'Done'): string {
+  if (pin.state === 'error' && pin.error) return pin.error
+  if (pin.state === 'answered' && pin.answer) return firstLines(pin.answer, 2)
+  if (pin.state === 'undone') return 'Undone'
+  if (pin.title) return pin.title
+  if (pin.state === 'done' && pin.committed) {
+    const count = new Set([...pin.changedTargetIds, ...pin.alsoChangedIds]).size
+    return count
+      ? `Pascal changed ${count} element${count === 1 ? '' : 's'}`
+      : 'Pascal updated the scene'
+  }
+  return fallback
+}
+
+/** "Also changed 2 other elements": the objects a prompt names can differ from the ones it changes. */
+export function alsoChangedLine(pin: PinModel): string | null {
+  const count = pin.alsoChangedIds.length
+  if (count === 0) return null
+  return `Also changed ${count} other element${count === 1 ? '' : 's'}`
+}
+
+/**
+ * The card rides its pin, so a camera flight (an Undo playing the build backwards, say) can carry it
+ * out from under a pointer that has not moved. That is not the person leaving, and the card holds
+ * the Redo, so it stays for a while. The leave event of a pointer that walked out is dispatched
+ * before the move that caused it, so it is told by position: `at` is where the leave says the
+ * pointer is, `last` where the last move left it; a pointer that did not move is where it was.
+ * A finger leaves without a move whenever it lifts, so only a mouse can be carried.
+ */
+export function cardCarriedFromPointer(leave: {
+  pointerType: string
+  at: { x: number; y: number }
+  last: { x: number; y: number } | null
+}): boolean {
+  return (
+    leave.pointerType === 'mouse' &&
+    leave.last !== null &&
+    Math.abs(leave.at.x - leave.last.x) < 0.5 &&
+    Math.abs(leave.at.y - leave.last.y) < 0.5
+  )
+}

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

@@ -0,0 +1,203 @@
+import { describe, expect, test } from 'bun:test'
+import { type PlacementInput, type PlacementState, placeBubble } from './placement'
+import type { Rect } from './types'
+
+// The bubble sits beside its target and never covers it (spec 2.4, placement). Written first: a
+// bubble over the thing it asks about; a side that flips on every frame at the boundary; a bubble
+// that detaches from its anchor; a bubble that leaves the viewport.
+
+const VIEWPORT: Rect = { x0: 12, y0: 56, x1: 1000, y1: 700 }
+const SIZE = { w: 320, h: 180 }
+const FRESH: PlacementState = { side: null, badMs: 0 }
+
+const input = (more: Partial<PlacementInput> = {}): PlacementInput => ({
+  box: { x0: 400, y0: 300, x1: 500, y1: 400 },
+  click: { x: 450, y: 350 },
+  size: SIZE,
+  viewport: VIEWPORT,
+  offset: { x: 0, y: 0 },
+  first: true,
+  ...more,
+})
+
+const bubbleRect = (pos: { x: number; y: number }): Rect => ({
+  x0: pos.x,
+  y0: pos.y,
+  x1: pos.x + SIZE.w,
+  y1: pos.y + SIZE.h,
+})
+
+const touches = (a: Rect, b: Rect) => !(a.x1 < b.x0 || a.x0 > b.x1 || a.y1 < b.y0 || a.y0 > b.y1)
+
+describe('which side the bubble takes', () => {
+  test('is clamped inside the viewport', () => {
+    const box = { x0: 30, y0: 60, x1: 90, y1: 120 }
+    const placed = placeBubble(input({ box, click: { x: 60, y: 90 } }), FRESH, 16)
+
+    expect(placed.pos.x).toBeGreaterThanOrEqual(VIEWPORT.x0)
+    expect(placed.pos.y).toBeGreaterThanOrEqual(VIEWPORT.y0)
+    expect(placed.pos.x + SIZE.w).toBeLessThanOrEqual(VIEWPORT.x1)
+    expect(placed.pos.y + SIZE.h).toBeLessThanOrEqual(VIEWPORT.y1)
+  })
+
+  test('never covers the target when a side fits', () => {
+    for (const box of [
+      { x0: 400, y0: 300, x1: 500, y1: 400 },
+      { x0: 700, y0: 300, x1: 800, y1: 400 },
+      { x0: 50, y0: 300, x1: 990, y1: 400 },
+      { x0: 50, y0: 560, x1: 990, y1: 690 },
+    ]) {
+      const click = { x: (box.x0 + box.x1) / 2, y: (box.y0 + box.y1) / 2 }
+      const placed = placeBubble(input({ box, click }), FRESH, 16)
+
+      expect(touches(bubbleRect(placed.pos), box)).toBe(false)
+    }
+  })
+
+  test('a target filling the view puts the bubble beside the click, outside a 48 px disc', () => {
+    const box = { x0: 12, y0: 56, x1: 900, y1: 690 }
+    const click = { x: 450, y: 300 }
+    const placed = placeBubble(input({ box, click }), FRESH, 16)
+    const disc = { x0: click.x - 48, y0: click.y - 48, x1: click.x + 48, y1: click.y + 48 }
+
+    expect(placed.side).toBe('right')
+    expect(placed.pos.x).toBe(click.x + 48 + 16)
+    expect(touches(bubbleRect(placed.pos), disc)).toBe(false)
+  })
+
+  test('the user’s drag offset moves it, and the tail follows', () => {
+    const plain = placeBubble(input(), FRESH, 16)
+    const moved = placeBubble(input({ offset: { x: 30, y: -20 } }), FRESH, 16)
+
+    expect(moved.pos).toEqual({ x: plain.pos.x + 30, y: plain.pos.y - 20 })
+    expect(moved.tail?.y).toBe((plain.tail?.y ?? 0) + 20)
+  })
+})
+
+describe('hysteresis: a side is kept until it has been wrong for 150 ms', () => {
+  const blockedRight = input({
+    box: { x0: 700, y0: 300, x1: 800, y1: 400 },
+    click: { x: 750, y: 350 },
+    first: false,
+  })
+
+  test('no switch before 150 ms', () => {
+    const first = placeBubble(blockedRight, { side: 'right', badMs: 0 }, 100)
+
+    expect(first.side).toBe('right')
+    expect(first.glide).toBe(false)
+    expect(first.state).toEqual({ side: 'right', badMs: 100 })
+  })
+
+  test('the switch after 150 ms glides, and resets the clock', () => {
+    const first = placeBubble(blockedRight, { side: 'right', badMs: 0 }, 100)
+    const second = placeBubble(blockedRight, first.state, 60)
+
+    expect(second.side).toBe('left')
+    expect(second.glide).toBe(true)
+    expect(second.state).toEqual({ side: 'left', badMs: 0 })
+  })
+
+  test('a side that is right again clears the count', () => {
+    const wrong = placeBubble(blockedRight, { side: 'right', badMs: 0 }, 100)
+    const right = placeBubble(input({ first: false }), wrong.state, 16)
+
+    expect(right.side).toBe('right')
+    expect(right.state.badMs).toBe(0)
+  })
+
+  test('with every side blocked it still obeys the 150 ms rule', () => {
+    const viewport = { x0: 400, y0: 200, x1: 620, y1: 420 }
+    const crowded = input({
+      box: { x0: 400, y0: 200, x1: 620, y1: 420 },
+      click: { x: 500, y: 300 },
+      viewport,
+      first: false,
+    })
+    const early = placeBubble(crowded, { side: 'left', badMs: 0 }, 100)
+    const late = placeBubble(crowded, early.state, 100)
+
+    expect(early.side).toBe('left')
+    expect(early.glide).toBe(false)
+    expect(late.side).toBe('right')
+    expect(late.glide).toBe(true)
+  })
+})
+
+describe('the tail', () => {
+  test('is clamped 16 px from the corners', () => {
+    const placed = placeBubble(
+      input({ box: { x0: 400, y0: 300, x1: 500, y1: 400 }, click: { x: 450, y: 305 } }),
+      FRESH,
+      16,
+    )
+
+    expect(placed.tail?.edge).toBe('left')
+    expect(placed.tail?.y).toBeGreaterThanOrEqual(16)
+    expect(placed.tail?.y).toBeLessThanOrEqual(180 - 16)
+  })
+
+  test('is hidden when the click is under the bubble', () => {
+    const box = { x0: 12, y0: 56, x1: 1000, y1: 700 }
+    const placed = placeBubble(
+      input({ box, click: { x: 600, y: 300 }, offset: { x: -200, y: 0 } }),
+      FRESH,
+      16,
+    )
+
+    expect(placed.tail).toBeNull()
+  })
+})
+
+describe('docking', () => {
+  test('a click off the viewport docks at the nearest edge, the tail turned to it', () => {
+    const placed = placeBubble(
+      input({ click: { x: -50, y: 300 }, box: { x0: -80, y0: 250, x1: -20, y1: 350 } }),
+      FRESH,
+      16,
+    )
+
+    expect(placed.side).toBe('dock')
+    expect(placed.pos.x).toBe(VIEWPORT.x0)
+    expect(placed.tail).toEqual({ edge: 'left', x: 0, y: 90 })
+  })
+
+  test('docks on the right and at the bottom too', () => {
+    const right = placeBubble(
+      input({ click: { x: 1300, y: 300 }, box: { x0: 1280, y0: 250, x1: 1320, y1: 350 } }),
+      FRESH,
+      16,
+    )
+    const bottom = placeBubble(
+      input({ click: { x: 500, y: 900 }, box: { x0: 480, y0: 880, x1: 520, y1: 920 } }),
+      FRESH,
+      16,
+    )
+
+    expect(right.pos.x).toBe(VIEWPORT.x1 - SIZE.w)
+    expect(right.tail?.edge).toBe('right')
+    expect(bottom.pos.y).toBe(VIEWPORT.y1 - SIZE.h)
+    expect(bottom.tail?.edge).toBe('bottom')
+  })
+
+  test('a click that cannot be projected docks inside the view with no tail', () => {
+    const placed = placeBubble(input({ click: null }), FRESH, 16)
+
+    expect(placed.side).toBe('dock')
+    expect(placed.tail).toBeNull()
+    expect(placed.pos.x).toBeGreaterThanOrEqual(VIEWPORT.x0)
+    expect(placed.pos.x + SIZE.w).toBeLessThanOrEqual(VIEWPORT.x1)
+  })
+
+  test('coming back from the dock re-chooses a side and glides', () => {
+    const docked = placeBubble(
+      input({ click: { x: -50, y: 300 }, box: { x0: -80, y0: 250, x1: -20, y1: 350 } }),
+      FRESH,
+      16,
+    )
+    const back = placeBubble(input({ first: false }), docked.state, 16)
+
+    expect(back.side).toBe('right')
+    expect(back.glide).toBe(true)
+  })
+})

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

@@ -0,0 +1,141 @@
+import { BIG_BOX_DISC, BUBBLE_GAP, SIDE_HYSTERESIS_MS } from './choreography'
+import type { BubbleSide, Rect, ScreenPoint } from './types'
+
+export type PlacementInput = {
+  /** The targets' screen box. */
+  box: Rect
+  /** Where the finger landed on screen; null when the anchor cannot be projected (behind the camera). */
+  click: ScreenPoint | null
+  /** The bubble's size. */
+  size: { w: number; h: number }
+  /** The free viewport: the canvas minus the chat column and toolbars, already inset. */
+  viewport: Rect
+  /** Where the person dragged the bubble to by its context row, from its placed position. */
+  offset: ScreenPoint
+  /** The first placement of this bubble: no hysteresis yet. */
+  first: boolean
+}
+
+export type PlacementState = {
+  side: BubbleSide | null
+  /** How long the current side has been invalid, in ms. */
+  badMs: number
+}
+
+export type TailEdge = 'left' | 'right' | 'top' | 'bottom'
+
+export type Placement = {
+  /** The bubble's top-left on screen, drag offset included. */
+  pos: ScreenPoint
+  side: BubbleSide
+  /** Where the tail sits on the bubble's edge, relative to the bubble; null when the click is under it. */
+  tail: { edge: TailEdge; x: number; y: number } | null
+  /** The side just changed: the caller springs to `pos` instead of snapping. */
+  glide: boolean
+  /** The click inside the bubble, for `transform-origin` on the open motion. */
+  origin: ScreenPoint
+  state: PlacementState
+}
+
+const SIDES = ['right', 'left', 'below', 'above'] as const
+const TAIL_CORNER = 16
+const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max)
+
+const area = (rect: Rect) => Math.max(0, rect.x1 - rect.x0) * Math.max(0, rect.y1 - rect.y0)
+
+/**
+ * Beside the target, never over it; the anchor is tracked 1:1 by the caller each frame, so this is
+ * only the choice of side. A side is kept until it has been invalid for 150 ms, then the next
+ * free one is taken and the move glides; with the anchor off screen the bubble docks at the nearest
+ * edge (spec 2.4, rules 1-5).
+ */
+export function placeBubble(input: PlacementInput, state: PlacementState, dtMs: number): Placement {
+  const { box, size, viewport: V, offset } = input
+  const { w: bw, h: bh } = size
+  const fit = (p: ScreenPoint): ScreenPoint => ({
+    x: clamp(p.x, V.x0, Math.max(V.x0, V.x1 - bw)),
+    y: clamp(p.y, V.y0, Math.max(V.y0, V.y1 - bh)),
+  })
+  const anchor =
+    input.click ??
+    (Number.isFinite(box.x0 + box.x1 + box.y0 + box.y1)
+      ? { x: (box.x0 + box.x1) / 2, y: (box.y0 + box.y1) / 2 }
+      : { x: (V.x0 + V.x1) / 2, y: (V.y0 + V.y1) / 2 })
+  const onScreen =
+    input.click !== null &&
+    anchor.x >= V.x0 &&
+    anchor.x <= V.x1 &&
+    anchor.y >= V.y0 &&
+    anchor.y <= V.y1
+
+  let pos: ScreenPoint
+  let side: BubbleSide
+  let badMs = state.badMs
+  if (onScreen) {
+    // A target filling the view cannot be avoided: stand clear of the click instead.
+    const big = area(box) > 0.5 * area(V)
+    const R: Rect = big
+      ? {
+          x0: anchor.x - BIG_BOX_DISC,
+          x1: anchor.x + BIG_BOX_DISC,
+          y0: anchor.y - BIG_BOX_DISC,
+          y1: anchor.y + BIG_BOX_DISC,
+        }
+      : box
+    const at: Record<(typeof SIDES)[number], ScreenPoint> = {
+      right: { x: R.x1 + BUBBLE_GAP, y: anchor.y - bh / 2 },
+      left: { x: R.x0 - BUBBLE_GAP - bw, y: anchor.y - bh / 2 },
+      below: { x: anchor.x - bw / 2, y: R.y1 + BUBBLE_GAP },
+      above: { x: anchor.x - bw / 2, y: R.y0 - BUBBLE_GAP - bh },
+    }
+    const free = (s: (typeof SIDES)[number]) => {
+      const p = fit(at[s])
+      return p.x + bw < R.x0 - 2 || p.x > R.x1 + 2 || p.y + bh < R.y0 - 2 || p.y > R.y1 + 2
+    }
+    const best = SIDES.find(free) ?? 'right'
+    const held = state.side && state.side !== 'dock' && !input.first ? state.side : null
+    let chosen: (typeof SIDES)[number]
+    if (!held) {
+      chosen = best
+      badMs = 0
+    } else if (!free(held)) {
+      badMs += dtMs
+      if (badMs > SIDE_HYSTERESIS_MS) {
+        chosen = best
+        badMs = 0
+      } else chosen = held
+    } else {
+      chosen = held
+      badMs = 0
+    }
+    side = chosen
+    pos = fit(at[chosen])
+  } else {
+    side = 'dock'
+    badMs = 0
+    pos = fit({ x: anchor.x - bw / 2, y: anchor.y - bh / 2 })
+  }
+
+  const glide = !input.first && state.side !== null && side !== state.side
+  const placed = { x: pos.x + offset.x, y: pos.y + offset.y }
+
+  // The tail points at the click from the bubble's nearest edge; under the bubble there is none.
+  let tail: Placement['tail'] = null
+  const lx = anchor.x - placed.x
+  const ly = anchor.y - placed.y
+  if (input.click !== null) {
+    if (lx < 0) tail = { edge: 'left', x: 0, y: clamp(ly, TAIL_CORNER, bh - TAIL_CORNER) }
+    else if (lx > bw) tail = { edge: 'right', x: bw, y: clamp(ly, TAIL_CORNER, bh - TAIL_CORNER) }
+    else if (ly < 0) tail = { edge: 'top', x: clamp(lx, TAIL_CORNER, bw - TAIL_CORNER), y: 0 }
+    else if (ly > bh) tail = { edge: 'bottom', x: clamp(lx, TAIL_CORNER, bw - TAIL_CORNER), y: bh }
+  }
+
+  return {
+    pos: placed,
+    side,
+    tail,
+    glide,
+    origin: { x: clamp(lx, 0, bw), y: clamp(ly, 0, bh) },
+    state: { side, badMs },
+  }
+}

package/src/lib/point-ask/pointer-tracker.ts

@@ -0,0 +1,34 @@
+// The pointer's last position on the page, shared by whatever follows it (the label chip), so the
+// chip moves on the frame of the pointer event, never after a React render.
+
+type PointerFn = (x: number, y: number) => void
+
+let x = -1
+let y = -1
+let attached = false
+const subscribers = new Set<PointerFn>()
+
+function onMove(event: PointerEvent) {
+  x = event.clientX
+  y = event.clientY
+  for (const fn of subscribers) fn(x, y)
+}
+
+export function getPointer(): { x: number; y: number } | null {
+  return x < 0 ? null : { x, y }
+}
+
+export function subscribePointer(fn: PointerFn): () => void {
+  subscribers.add(fn)
+  if (!attached && typeof window !== 'undefined') {
+    window.addEventListener('pointermove', onMove, { passive: true, capture: true })
+    attached = true
+  }
+  return () => {
+    subscribers.delete(fn)
+    if (subscribers.size === 0 && attached) {
+      window.removeEventListener('pointermove', onMove, { capture: true })
+      attached = false
+    }
+  }
+}

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

@@ -0,0 +1,83 @@
+import { Vector3 } from 'three'
+import { getEditorThreeContext } from '../../components/editor/three-context-bridge'
+import { BUBBLE_BOTTOM_INSET, BUBBLE_TOP_INSET, VIEWPORT_INSET } from './overlay-metrics'
+import type { Rect, ScreenPoint } from './types'
+
+// World to screen for the DOM overlay, read from the live editor camera each frame: the overlay
+// lives outside the R3F tree, so it asks the same camera the canvas draws with. Screen units are
+// CSS pixels in viewport coordinates (the overlay is `position: fixed`).
+
+const scratch = new Vector3()
+
+export type Projected = ScreenPoint & { ok: boolean }
+
+/** The canvas the editor draws in, or null before it mounts. */
+export function canvasRect(): DOMRect | null {
+  return getEditorThreeContext()?.domElement.getBoundingClientRect() ?? null
+}
+
+/** A world point on the page; `ok` is false behind the camera or outside the clip volume. */
+export function projectWorld(point: readonly [number, number, number]): Projected {
+  const three = getEditorThreeContext()
+  if (!three) return { x: 0, y: 0, ok: false }
+  const rect = three.domElement.getBoundingClientRect()
+  scratch.set(point[0], point[1], point[2])
+  three.camera.updateMatrixWorld()
+  scratch.project(three.camera)
+  const ok = scratch.z > -1 && scratch.z < 1
+  return {
+    x: rect.left + (scratch.x * 0.5 + 0.5) * rect.width,
+    y: rect.top + (-scratch.y * 0.5 + 0.5) * rect.height,
+    ok,
+  }
+}
+
+/** The screen box of a world box (its eight corners projected); null when nothing of it is in front of the camera. */
+export function projectBox(box: {
+  min: readonly [number, number, number]
+  max: readonly [number, number, number]
+}): Rect | null {
+  let x0 = Number.POSITIVE_INFINITY
+  let y0 = Number.POSITIVE_INFINITY
+  let x1 = Number.NEGATIVE_INFINITY
+  let y1 = Number.NEGATIVE_INFINITY
+  let any = false
+  for (const x of [box.min[0], box.max[0]])
+    for (const y of [box.min[1], box.max[1]])
+      for (const z of [box.min[2], box.max[2]]) {
+        const p = projectWorld([x, y, z])
+        if (!p.ok) continue
+        any = true
+        x0 = Math.min(x0, p.x)
+        y0 = Math.min(y0, p.y)
+        x1 = Math.max(x1, p.x)
+        y1 = Math.max(y1, p.y)
+      }
+  return any ? { x0, y0, x1, y1 } : null
+}
+
+/** The union of several screen boxes. */
+export function unionRect(rects: readonly Rect[]): Rect | null {
+  if (rects.length === 0) return null
+  return rects.reduce((all, r) => ({
+    x0: Math.min(all.x0, r.x0),
+    y0: Math.min(all.y0, r.y0),
+    x1: Math.max(all.x1, r.x1),
+    y1: Math.max(all.y1, r.y1),
+  }))
+}
+
+/**
+ * The free viewport a bubble may sit in: the canvas inset on every side, and clear of the top bar
+ * and the action bar the editor floats over it.
+ */
+export function freeViewport(): Rect | null {
+  const rect = canvasRect()
+  if (!rect) return null
+  return {
+    x0: rect.left + VIEWPORT_INSET,
+    y0: rect.top + BUBBLE_TOP_INSET,
+    x1: rect.right - VIEWPORT_INSET,
+    y1: rect.bottom - BUBBLE_BOTTOM_INSET,
+  }
+}