@pascal-app/editor 1.0.3 → 1.0.5

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,
+  }
+}

package/src/lib/point-ask/describe-target.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNode } from '@pascal-app/core'
+import { house } from './__fixtures__/house'
+import { describeTarget } from './describe-target'
+
+// Point and ask names what the finger is on, in the viewer's unit, for the label chip and the
+// bubble's context row, and in metres for the agent (the context's `size`). Written first: a size
+// in the wrong unit; a wall that does not say which room it bounds; a window's sill missing from the
+// context; an element of a kind nobody described showing no name at all.
+
+const nodes = house()
+const metric = { unit: 'metric' } as const
+const at = (id: string, unit: Parameters<typeof describeTarget>[2] = metric) =>
+  describeTarget(nodes[id] as AnyNode, nodes, unit)
+
+describe('a room', () => {
+  test('is named by its zone, sized by its area, and is the kind "room"', () => {
+    const room = at('zone_kitchen')
+
+    expect(room).toMatchObject({
+      id: 'zone_kitchen',
+      type: 'zone',
+      kind: 'room',
+      name: 'Kitchen',
+      size: '12.0 m²',
+      levelId: 'level_0',
+    })
+    expect(room.sizes).toEqual({ area: 12, width: 4, depth: 3 })
+    expect(room.zoneId).toBeUndefined()
+  })
+
+  test('a room with no name is "Room"', () => {
+    const unnamed = { ...nodes.zone_kitchen, name: '' } as AnyNode
+
+    expect(describeTarget(unnamed, { ...nodes, zone_kitchen: unnamed }, metric).name).toBe('Room')
+  })
+})
+
+describe('a wall', () => {
+  test('says which room it bounds, its length by its height, and the room it is in', () => {
+    const wall = at('wall_north')
+
+    expect(wall).toMatchObject({ kind: 'wall', name: 'Wall · Kitchen', zoneId: 'zone_kitchen' })
+    expect(wall.sizes.length).toBeCloseTo(4, 6)
+    expect(wall.sizes.thickness).toBeGreaterThan(0)
+    expect(wall.size).toBe(`4.00 × ${wall.sizes.height!.toFixed(2)} m`)
+  })
+
+  test('a wall bounding no room is just "Wall"', () => {
+    const { zone_kitchen: _gone, ...without } = nodes
+    const wall = describeTarget(nodes.wall_north as AnyNode, without as typeof nodes, metric)
+
+    expect(wall.name).toBe('Wall')
+    expect(wall.zoneId).toBeUndefined()
+  })
+})
+
+describe('a window and a door', () => {
+  test('a window: width by height, its sill in the context, its wall as parent', () => {
+    const window = at('window_north')
+
+    expect(window).toMatchObject({
+      kind: 'window',
+      name: 'Window',
+      size: '1.20 × 1.40 m',
+      parentId: 'wall_north',
+      zoneId: 'zone_kitchen',
+    })
+    expect(window.sizes.width).toBeCloseTo(1.2, 6)
+    expect(window.sizes.height).toBeCloseTo(1.4, 6)
+    expect(window.sizes.sill).toBeCloseTo(0.7, 6)
+  })
+
+  test('a door stands on the floor: sill 0', () => {
+    const door = at('door_front')
+
+    expect(door).toMatchObject({ kind: 'door', name: 'Door', size: '0.90 × 2.10 m' })
+    expect(door.sizes.sill).toBeCloseTo(0, 6)
+  })
+})
+
+describe('an item', () => {
+  test('is named by the person’s name, sized by its width, and sits in the room it stands in', () => {
+    const sofa = at('item_sofa')
+
+    expect(sofa).toMatchObject({
+      kind: 'item',
+      name: 'Sofa',
+      size: '2.10 m wide',
+      zoneId: 'zone_kitchen',
+    })
+    expect(sofa.parentId).toBeUndefined()
+    expect(sofa.sizes).toEqual({ width: 2.1, depth: 0.95, height: 0.85 })
+  })
+
+  test('with no name it is the asset’s, and then just "Item"', () => {
+    const unnamed = { ...nodes.item_sofa, name: undefined } as AnyNode
+    expect(describeTarget(unnamed, nodes, metric).name).toBe('Oslo 3-seat')
+
+    const bare = {
+      ...nodes.item_sofa,
+      name: undefined,
+      asset: { ...(nodes.item_sofa as never as { asset: object }).asset, name: '' },
+    } as AnyNode
+    expect(describeTarget(bare, nodes, metric).name).toBe('Item')
+  })
+})
+
+describe('units', () => {
+  test('imperial reads in feet, inches and square feet', () => {
+    const imperial = { unit: 'imperial' } as const
+
+    expect(at('zone_kitchen', imperial).size).toBe('129.2 ft²')
+    expect(at('window_north', imperial).size).toBe(`3'11" × 4'7"`)
+    expect(at('item_sofa', imperial).size).toBe(`6'11" wide`)
+    // The context stays in metres whatever the viewer shows.
+    expect(at('window_north', imperial).sizes.width).toBeCloseTo(1.2, 6)
+  })
+
+  test('millimetres when the viewer shows them', () => {
+    const mm = { unit: 'metric', metricNotation: 'millimeters' } as const
+
+    expect(at('window_north', mm).size).toBe('1200 × 1400 mm')
+    expect(at('item_sofa', mm).size).toBe('2100 mm wide')
+  })
+})
+
+describe('everything else', () => {
+  test('a kind nobody described still has a name and a type', () => {
+    const odd = {
+      id: 'column_1',
+      type: 'column',
+      parentId: 'level_0',
+      name: 'Pillar',
+    } as unknown as AnyNode
+    const anonymous = { id: 'fence_1', type: 'fence', parentId: 'level_0' } as unknown as AnyNode
+
+    expect(describeTarget(odd, { ...nodes, column_1: odd }, metric)).toMatchObject({
+      kind: 'other',
+      name: 'Pillar',
+      type: 'column',
+    })
+    expect(describeTarget(anonymous, { ...nodes, fence_1: anonymous }, metric).name).toBe('Fence')
+  })
+
+  test('a roof segment is the kind "roof" and a stair the kind "stair"', () => {
+    const segment = {
+      id: 'roof_segment_1',
+      type: 'roof-segment',
+      parentId: 'roof_1',
+      width: 8,
+      depth: 6,
+    } as unknown as AnyNode
+    const stair = {
+      id: 'stair_1',
+      type: 'stair',
+      parentId: 'level_0',
+      width: 1,
+      totalRise: 2.7,
+    } as unknown as AnyNode
+
+    expect(describeTarget(segment, nodes, metric).kind).toBe('roof')
+    expect(describeTarget(stair, nodes, metric).kind).toBe('stair')
+  })
+})