@pascal-app/editor 1.0.3 → 1.0.5

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

@@ -0,0 +1,157 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  isRegionBigEnough,
+  rankInRegion,
+  rectFromDrag,
+  regionFractions,
+  regionSizeMetres,
+} from './region'
+
+// A region is a view, not a selection (spec 2.3): a rectangle dragged on the canvas, its size in
+// metres shown live, what lies inside it ranked for the agent. Written first: a rectangle dragged
+// right to left coming out inverted; a rectangle past the canvas edge; a speck of a drag taken as
+// a region; a size measured through a ray that points at the sky; the ranking leaning on elements
+// that merely touch the rectangle.
+
+const canvas = { x0: 0, y0: 0, x1: 1000, y1: 600 }
+
+describe('rectFromDrag', () => {
+  test('is the same rectangle whichever corner the drag starts from', () => {
+    const rect = { x0: 100, y0: 80, x1: 300, y1: 200 }
+
+    expect(rectFromDrag({ x: 100, y: 80 }, { x: 300, y: 200 }, canvas)).toEqual(rect)
+    expect(rectFromDrag({ x: 300, y: 200 }, { x: 100, y: 80 }, canvas)).toEqual(rect)
+    expect(rectFromDrag({ x: 300, y: 80 }, { x: 100, y: 200 }, canvas)).toEqual(rect)
+  })
+
+  test('is kept inside the canvas', () => {
+    expect(rectFromDrag({ x: -40, y: 20 }, { x: 1200, y: 700 }, canvas)).toEqual({
+      x0: 0,
+      y0: 20,
+      x1: 1000,
+      y1: 600,
+    })
+  })
+})
+
+describe('isRegionBigEnough', () => {
+  test('wants 24 px on both sides, so a click that wobbled is not a region', () => {
+    expect(isRegionBigEnough({ x0: 0, y0: 0, x1: 24, y1: 24 })).toBe(true)
+    expect(isRegionBigEnough({ x0: 0, y0: 0, x1: 23, y1: 200 })).toBe(false)
+    expect(isRegionBigEnough({ x0: 0, y0: 0, x1: 200, y1: 23.9 })).toBe(false)
+  })
+})
+
+describe('regionFractions', () => {
+  test('is [left, top, right, bottom] as 0-1 of the full frame', () => {
+    const box = { left: 100, top: 50, width: 800, height: 400 }
+
+    expect(regionFractions({ x0: 300, y0: 150, x1: 700, y1: 350 }, box)).toEqual([
+      0.25, 0.25, 0.75, 0.75,
+    ])
+  })
+
+  test('is clamped to the frame', () => {
+    const box = { left: 100, top: 50, width: 800, height: 400 }
+
+    expect(regionFractions({ x0: 0, y0: 0, x1: 2000, y1: 2000 }, box)).toEqual([0, 0, 1, 1])
+  })
+})
+
+describe('regionSizeMetres', () => {
+  // A camera straight above: the screen point (x, y) looks down at the world point (x / 10, 0, y / 10).
+  const down = (x: number, y: number) => ({
+    origin: [x / 10, 10, y / 10] as [number, number, number],
+    direction: [0, -1, 0] as [number, number, number],
+  })
+  const rect = { x0: 100, y0: 100, x1: 300, y1: 200 }
+
+  test('is the distance between the left and right edge hits, and top and bottom, on the plane', () => {
+    expect(regionSizeMetres(rect, down, 0)).toEqual({ width: 20, depth: 10 })
+  })
+
+  test('measures on the plane it is given', () => {
+    // At y = 5 the same rays hit the same x and z (they are straight down): the size does not change.
+    expect(regionSizeMetres(rect, down, 5)).toEqual({ width: 20, depth: 10 })
+  })
+
+  test('is null when a ray misses the plane: it points up, along it, or does not exist', () => {
+    expect(
+      regionSizeMetres(rect, () => ({ origin: [0, 1, 0], direction: [0, 1, 0] }), 0),
+    ).toBeNull()
+    expect(
+      regionSizeMetres(rect, () => ({ origin: [0, 1, 0], direction: [1, 0, 0] }), 0),
+    ).toBeNull()
+    expect(regionSizeMetres(rect, () => null, 0)).toBeNull()
+  })
+
+  test('is null when only one of the four rays misses (the sky in a corner of the frame)', () => {
+    const skyAtTop = (x: number, y: number) =>
+      y <= 100
+        ? {
+            origin: [0, 1, 0] as [number, number, number],
+            direction: [0, 1, 0] as [number, number, number],
+          }
+        : down(x, y)
+
+    expect(regionSizeMetres(rect, skyAtTop, 0)).toBeNull()
+  })
+})
+
+describe('rankInRegion', () => {
+  const region = { x0: 100, y0: 100, x1: 300, y1: 300 }
+
+  test('ranks by the area of overlap with the region, biggest first', () => {
+    const ranked = rankInRegion(
+      [
+        { id: 'small', rect: { x0: 250, y0: 250, x1: 350, y1: 350 } }, // 50 x 50
+        { id: 'big', rect: { x0: 0, y0: 0, x1: 400, y1: 400 } }, // the whole region
+        { id: 'mid', rect: { x0: 100, y0: 100, x1: 200, y1: 300 } }, // 100 x 200
+      ],
+      region,
+    )
+
+    expect(ranked).toEqual({ ids: ['big', 'mid', 'small'], more: 0 })
+  })
+
+  test('leaves out what is outside, what only touches an edge, and what has no screen box', () => {
+    const ranked = rankInRegion(
+      [
+        { id: 'outside', rect: { x0: 500, y0: 500, x1: 600, y1: 600 } },
+        { id: 'touching', rect: { x0: 300, y0: 100, x1: 400, y1: 300 } },
+        { id: 'hidden', rect: null },
+        { id: 'inside', rect: { x0: 150, y0: 150, x1: 160, y1: 160 } },
+      ],
+      region,
+    )
+
+    expect(ranked).toEqual({ ids: ['inside'], more: 0 })
+  })
+
+  test('ties go by id, so the same view always ranks the same way', () => {
+    const same = { x0: 120, y0: 120, x1: 140, y1: 140 }
+
+    expect(
+      rankInRegion(
+        [
+          { id: 'b', rect: same },
+          { id: 'a', rect: same },
+        ],
+        region,
+      ).ids,
+    ).toEqual(['a', 'b'])
+  })
+
+  test('keeps the top few and counts the rest', () => {
+    const many = Array.from({ length: 15 }, (_, i) => ({
+      id: `e${String(i).padStart(2, '0')}`,
+      rect: { x0: 110, y0: 110, x1: 110 + 10 + i, y1: 120 },
+    }))
+    const ranked = rankInRegion(many, region)
+
+    expect(ranked.ids).toHaveLength(12)
+    expect(ranked.more).toBe(3)
+    expect(ranked.ids[0]).toBe('e14')
+    expect(rankInRegion(many, region, 5)).toMatchObject({ more: 10 })
+  })
+})

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

@@ -0,0 +1,136 @@
+import { formatLinearMeasurement } from '../measurements'
+import type { Rect, ScreenPoint } from './types'
+
+// A region is a view, not a selection (spec 2.3, "A region is a view, not a selection"): a
+// rectangle dragged on the canvas, its size shown live in metres, the crop it frames, and what lies
+// inside it ranked for the agent. Pure: the camera is handed in as a ray function.
+
+const MIN_SIDE_PX = 24
+const RAY_EPSILON = 1e-6
+
+const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max)
+
+/** The rectangle between two drag points, whichever way it was dragged, kept inside `bounds`. */
+export function rectFromDrag(a: ScreenPoint, b: ScreenPoint, bounds: Rect): Rect {
+  return {
+    x0: clamp(Math.min(a.x, b.x), bounds.x0, bounds.x1),
+    y0: clamp(Math.min(a.y, b.y), bounds.y0, bounds.y1),
+    x1: clamp(Math.max(a.x, b.x), bounds.x0, bounds.x1),
+    y1: clamp(Math.max(a.y, b.y), bounds.y0, bounds.y1),
+  }
+}
+
+/** Under 24 px on a side it is a click that wobbled, not a region. */
+export function isRegionBigEnough(rect: Rect): boolean {
+  return rect.x1 - rect.x0 >= MIN_SIDE_PX && rect.y1 - rect.y0 >= MIN_SIDE_PX
+}
+
+/** The rectangle as 0-1 fractions of the canvas's full frame: [left, top, right, bottom]. */
+export function regionFractions(
+  rect: Rect,
+  canvas: { left: number; top: number; width: number; height: number },
+): [number, number, number, number] {
+  const fraction = (value: number, origin: number, extent: number) =>
+    clamp((value - origin) / extent, 0, 1)
+  return [
+    fraction(rect.x0, canvas.left, canvas.width),
+    fraction(rect.y0, canvas.top, canvas.height),
+    fraction(rect.x1, canvas.left, canvas.width),
+    fraction(rect.y1, canvas.top, canvas.height),
+  ]
+}
+
+type Ray = { origin: [number, number, number]; direction: [number, number, number] }
+
+/** Where a ray meets the horizontal plane `y = planeY` in front of it; null when it points up or along it. */
+function hitPlane(ray: Ray | null, planeY: number): [number, number, number] | null {
+  if (!ray || ray.direction[1] >= -RAY_EPSILON) return null
+  const t = (planeY - ray.origin[1]) / ray.direction[1]
+  if (!Number.isFinite(t) || t < 0) return null
+  return [ray.origin[0] + ray.direction[0] * t, planeY, ray.origin[2] + ray.direction[2] * t]
+}
+
+const distance = (a: readonly number[], b: readonly number[]) =>
+  Math.hypot((a[0] ?? 0) - (b[0] ?? 0), (a[1] ?? 0) - (b[1] ?? 0), (a[2] ?? 0) - (b[2] ?? 0))
+
+/**
+ * What the rectangle spans on the ground, in metres: the rays through the middle of its four sides
+ * meet the plane at `planeY` (the level's floor), and the width and depth are the distances between
+ * opposite hits. Null when any of the four misses the plane (the sky in a corner of the frame).
+ */
+export function regionSizeMetres(
+  rect: Rect,
+  cameraRay: (x: number, y: number) => Ray | null,
+  planeY: number,
+): { width: number; depth: number } | null {
+  const midX = (rect.x0 + rect.x1) / 2
+  const midY = (rect.y0 + rect.y1) / 2
+  const left = hitPlane(cameraRay(rect.x0, midY), planeY)
+  const right = hitPlane(cameraRay(rect.x1, midY), planeY)
+  const top = hitPlane(cameraRay(midX, rect.y0), planeY)
+  const bottom = hitPlane(cameraRay(midX, rect.y1), planeY)
+  if (!(left && right && top && bottom)) return null
+  return { width: distance(left, right), depth: distance(top, bottom) }
+}
+
+/** "4.2 × 3.1 m", or feet and inches as the editor writes them. */
+export function formatRegionSize(
+  size: { width: number; depth: number },
+  unit: 'metric' | 'imperial',
+): string {
+  if (unit === 'imperial')
+    return `${formatLinearMeasurement(size.width, 'imperial')} × ${formatLinearMeasurement(size.depth, 'imperial')}`
+  return `${size.width.toFixed(1)} × ${size.depth.toFixed(1)} m`
+}
+
+const overlapArea = (a: Rect, b: Rect) =>
+  Math.max(0, Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0)) *
+  Math.max(0, Math.min(a.y1, b.y1) - Math.max(a.y0, b.y0))
+
+/**
+ * What the region shows, by how much of it each element covers, the biggest first, ties by id so
+ * the same view ranks the same way; elements that only touch an edge, or have no box on screen,
+ * are not in it. The top `limit` are named, the rest only counted.
+ */
+export function rankInRegion(
+  candidates: readonly { id: string; rect: Rect | null }[],
+  region: Rect,
+  limit = 12,
+): { ids: string[]; more: number } {
+  const ranked = candidates
+    .flatMap(({ id, rect }) => {
+      const area = rect ? overlapArea(rect, region) : 0
+      return area > 0 ? [{ id, area }] : []
+    })
+    .sort((a, b) => b.area - a.area || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  return {
+    ids: ranked.slice(0, limit).map((entry) => entry.id),
+    more: Math.max(0, ranked.length - limit),
+  }
+}
+
+/** The region chip's words: "Area · 6 elements". */
+export function regionLabel(count: number): string {
+  if (count <= 0) return 'Area'
+  return `Area · ${count} element${count === 1 ? '' : 's'}`
+}
+
+/**
+ * Where the bubble's tail points on the rectangle: the release point put on its nearest edge. A
+ * point outside is clamped onto the rectangle; one inside is pushed out to the closest side.
+ */
+export function nearestEdgePoint(rect: Rect, to: ScreenPoint): ScreenPoint {
+  const x = clamp(to.x, rect.x0, rect.x1)
+  const y = clamp(to.y, rect.y0, rect.y1)
+  const inside = to.x > rect.x0 && to.x < rect.x1 && to.y > rect.y0 && to.y < rect.y1
+  if (!inside) return { x, y }
+  const toLeft = x - rect.x0
+  const toRight = rect.x1 - x
+  const toTop = y - rect.y0
+  const toBottom = rect.y1 - y
+  const nearest = Math.min(toLeft, toRight, toTop, toBottom)
+  if (nearest === toRight) return { x: rect.x1, y }
+  if (nearest === toLeft) return { x: rect.x0, y }
+  if (nearest === toTop) return { x, y: rect.y0 }
+  return { x, y: rect.y1 }
+}

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

@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  BuildingNode,
+  clearSceneHistory,
+  emitter,
+  LevelNode,
+  type PointAskSubmit,
+  registerPointAskHandler,
+  useScene,
+  WallNode,
+} from '@pascal-app/core'
+import { type BubbleTarget, type PinRecord, usePointAsk } from '../../store/use-point-ask'
+import { createPin } from './pin-machine'
+import { planRetry } from './retry'
+import { retryAsk, sendBubble, startPointAskSession } from './session'
+
+// Retrying an ask from the chat: the same words, targets, camera and crop as a new ask with its own
+// pin. Architect's Retry goes through here; a finished ask keeps its pin (its compare and Undo
+// stay), an errored one is replaced, as "Try again" does.
+
+const submit: PointAskSubmit = {
+  askId: 'ask_old',
+  context: {
+    askId: 'ask_old',
+    camera: {
+      aspect: 1.6,
+      fov: 50,
+      position: [0, 1, 5],
+      projection: 'perspective',
+      target: [0, 1, 0],
+    },
+    capturedAt: '2026-10-12T10:00:00.000Z',
+    gesture: 'click',
+    image: { dataUrl: 'data:image/jpeg;base64,AAAA', height: 320, marked: true, width: 512 },
+    kind: 'scene-point',
+    level: { id: 'level_0', name: 'Ground floor' },
+    source: 'editor',
+    targets: [],
+    version: 1,
+  },
+  from: { height: 24, width: 120, x: 600, y: 300 },
+  text: 'make this window wider',
+}
+
+function pinIn(state: 'error' | 'done'): PinRecord {
+  const model = createPin({ askId: 'ask_old', targetIds: ['window_kitchen_n1'], text: submit.text })
+  return {
+    anchor: [0, 1, 0],
+    createdAt: 1,
+    label: 'Window · Kitchen',
+    levelId: 'level_0',
+    local: null,
+    model: { ...model, state } as PinRecord['model'],
+    retireAt: 123,
+    submit,
+  }
+}
+
+describe('planRetry', () => {
+  test('the new ask has its own id, the same words, targets, camera and crop', () => {
+    const plan = planRetry(pinIn('done'), 'ask_new', 5)
+    expect(plan?.submit.askId).toBe('ask_new')
+    expect(plan?.submit.context.askId).toBe('ask_new')
+    expect(plan?.submit.text).toBe('make this window wider')
+    expect(plan?.submit.context.camera).toEqual(submit.context.camera)
+    expect(plan?.submit.context.image).toEqual(submit.context.image)
+    expect(plan?.pin.model.askId).toBe('ask_new')
+    expect(plan?.pin.model.targetIds).toEqual(['window_kitchen_n1'])
+    expect(plan?.pin.retireAt).toBeNull()
+    expect(plan?.pin.createdAt).toBe(5)
+  })
+
+  test('an errored pin is replaced (Try again); any other state keeps its pin, with its compare and Undo', () => {
+    expect(planRetry(pinIn('error'), 'ask_new', 5)?.keepOld).toBe(false)
+    expect(planRetry(pinIn('done'), 'ask_new', 5)?.keepOld).toBe(true)
+  })
+
+  test('a pin that kept no submit cannot be retried', () => {
+    const { submit: _gone, ...noSubmit } = pinIn('error')
+    expect(planRetry(noSubmit as PinRecord, 'ask_new', 5)).toBeNull()
+  })
+})
+
+const building = BuildingNode.parse({ id: 'building_retry' })
+const level = LevelNode.parse({ id: 'level_retry', parentId: building.id })
+const wall = WallNode.parse({
+  id: 'wall_retry',
+  parentId: level.id,
+  start: [0, 0],
+  end: [4, 0],
+  height: 2.6,
+})
+building.children = [level.id]
+level.children = [wall.id]
+const target = {
+  id: wall.id,
+  type: 'wall',
+  name: 'Wall',
+  levelId: level.id,
+  size: { length: 4, height: 2.6, thickness: 0.2 },
+  box: { min: [0, 0, -0.1], max: [4, 2.6, 0.1] },
+} as unknown as BubbleTarget
+
+const original = useScene.getState()
+const originalWindow = globalThis.window
+const originalDocument = globalThis.document
+const originalRaf = globalThis.requestAnimationFrame
+const originalCancelRaf = globalThis.cancelAnimationFrame
+let stopSession = () => {}
+let unregister = () => {}
+let handed: PointAskSubmit[] = []
+
+beforeEach(() => {
+  const stub = { addEventListener() {}, removeEventListener() {} }
+  globalThis.window = { ...stub, innerWidth: 1280, innerHeight: 800 } as never
+  globalThis.document = { ...stub, hidden: false } as never
+  globalThis.requestAnimationFrame = (callback) => {
+    callback(0)
+    return 0
+  }
+  globalThis.cancelAnimationFrame = () => {}
+  useScene.setState({
+    nodes: { [building.id]: building, [level.id]: level, [wall.id]: wall },
+    rootNodeIds: [building.id],
+    dirtyNodes: new Set(),
+    readOnly: false,
+  } as never)
+  clearSceneHistory()
+  usePointAsk.setState({ pins: {}, pinOrder: [], bubble: null, comparing: null, busy: false })
+  handed = []
+  unregister = registerPointAskHandler(async (sent) => {
+    handed.push(sent)
+    return { ok: true }
+  })
+  stopSession = startPointAskSession()
+})
+
+afterEach(() => {
+  stopSession()
+  unregister()
+  useScene.setState(original, true)
+  clearSceneHistory()
+  globalThis.window = originalWindow
+  globalThis.document = originalDocument
+  if (originalRaf) globalThis.requestAnimationFrame = originalRaf
+  else Reflect.deleteProperty(globalThis, 'requestAnimationFrame')
+  if (originalCancelRaf) globalThis.cancelAnimationFrame = originalCancelRaf
+  else Reflect.deleteProperty(globalThis, 'cancelAnimationFrame')
+})
+
+async function sendAsk() {
+  usePointAsk.getState().openBubble({
+    targets: [target],
+    anchor: [2, 1, 0],
+    hit: { point: [2, 1, 0], normal: [0, 0, 1] },
+    gesture: 'click',
+    capturedAt: new Date().toISOString(),
+    camera: null,
+    crop: { state: 'failed' },
+    draft: '',
+    error: null,
+  })
+  await sendBubble('make this wall taller', { x: 0, y: 0, width: 10, height: 10 })
+  const askId = usePointAsk.getState().pinOrder[0]
+  if (!askId) throw new Error('the ask did not plant a pin')
+  return askId
+}
+
+const status = (askId: string, rest: Record<string, unknown>) =>
+  emitter.emit('point-ask:status', { askId, ...rest } as never)
+
+describe('retryAsk', () => {
+  test('hands the same words and targets to the chat as a new ask, and says it did', async () => {
+    const askId = await sendAsk()
+    status(askId, { status: 'working' })
+    status(askId, { status: 'ended', outcome: 'completed', asked: false, wroteScene: true })
+    expect(await retryAsk(askId)).toBe(true)
+    expect(handed).toHaveLength(2)
+    expect(handed[1]?.askId).not.toBe(askId)
+    expect(handed[1]?.context.askId).toBe(handed[1]?.askId)
+    expect(handed[1]?.text).toBe('make this wall taller')
+    expect(handed[1]?.context.targets.map((t) => t.id)).toEqual([wall.id])
+  })
+
+  test('a finished ask keeps its pin, so its compare and Undo stay', async () => {
+    const askId = await sendAsk()
+    status(askId, { status: 'working' })
+    status(askId, { status: 'ended', outcome: 'completed', asked: false, wroteScene: true })
+    await retryAsk(askId)
+    const { pinOrder, pins } = usePointAsk.getState()
+    expect(pinOrder).toHaveLength(2)
+    expect(pins[askId]).toBeDefined()
+    const next = pinOrder.find((id) => id !== askId)
+    expect(next && pins[next]?.model.state).toBe('sent')
+  })
+
+  test('an errored ask is replaced by the retry, as "Try again" does', async () => {
+    const askId = await sendAsk()
+    status(askId, { status: 'working' })
+    status(askId, {
+      status: 'ended',
+      outcome: 'errored',
+      asked: false,
+      wroteScene: false,
+      error: 'x',
+    })
+    await retryAsk(askId)
+    const { pinOrder, pins } = usePointAsk.getState()
+    expect(pinOrder).toHaveLength(1)
+    expect(pins[askId]).toBeUndefined()
+  })
+
+  test("says it could not when the pin is gone (a reload, a collaborator's ask)", async () => {
+    expect(await retryAsk('ask_unknown')).toBe(false)
+    expect(handed).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,37 @@
+import type { PointAskSubmit } from '@pascal-app/core'
+import type { PinRecord } from '../../store/use-point-ask'
+import { createPin } from './pin-machine'
+
+/**
+ * What retrying an ask puts in the world: the same words, context and crop under a new ask id, planted
+ * where the old pin was. An errored ask is replaced (the pin's own "Try again"); any other is kept, so
+ * a retry from the chat of a finished ask does not take away that result's compare and Undo.
+ * Null when the pin kept no submit to send again.
+ */
+export function planRetry(
+  old: PinRecord,
+  nextAskId: string,
+  now: number,
+): { pin: PinRecord; submit: PointAskSubmit; keepOld: boolean } | null {
+  if (!old.submit) return null
+  const submit: PointAskSubmit = {
+    ...old.submit,
+    askId: nextAskId,
+    context: { ...old.submit.context, askId: nextAskId },
+  }
+  return {
+    pin: {
+      ...old,
+      model: createPin({
+        askId: nextAskId,
+        text: old.model.text,
+        targetIds: old.model.targetIds,
+      }),
+      submit,
+      retireAt: null,
+      createdAt: now,
+    },
+    submit,
+    keepOld: old.model.state !== 'error',
+  }
+}