@pascal-app/editor 1.0.3 → 1.0.5

package/src/lib/point-ask/spring-keyframes.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'bun:test'
+import { springKeyframes } from './spring-keyframes'
+
+// The bubble grows from the click as a spring: scale 0.92 to 1 with the opacity and the blur
+// arriving together. Written first: a first frame that is not the start, a last frame that is not
+// the rest, opacity leaving 0 to 1, and a critically damped spring overshooting.
+describe('springKeyframes', () => {
+  const frames = springKeyframes(
+    { scale: 0.92, opacity: 0, blur: 4 },
+    { scale: 1, opacity: 1, blur: 0 },
+    360,
+  )
+
+  test('starts at the start and rests at the end', () => {
+    expect(frames[0]).toMatchObject({
+      offset: 0,
+      opacity: 0,
+      transform: 'translate3d(0px, 0px, 0) scale(0.92)',
+      filter: 'blur(4px)',
+    })
+    const last = frames.at(-1)!
+    expect(last.opacity).toBeCloseTo(1, 2)
+    expect(String(last.transform)).toContain('scale(1')
+    expect(String(last.filter)).toBe('blur(0px)')
+  })
+
+  test('critically damped, it never overshoots the end', () => {
+    for (const frame of frames) expect(Number(frame.opacity)).toBeLessThanOrEqual(1)
+    const scales = frames.map((f) => Number(/scale\(([\d.]+)\)/.exec(String(f.transform))?.[1]))
+    expect(Math.max(...scales)).toBeLessThanOrEqual(1.0001)
+  })
+
+  test('with momentum (damping 0.8) the scale overshoots, and opacity still stays in 0-1', () => {
+    const springy = springKeyframes({ scale: 0.9 }, { scale: 1 }, 400, { damping: 0.8 })
+    const scales = springy.map((f) => Number(/scale\(([\d.]+)\)/.exec(String(f.transform))?.[1]))
+    expect(Math.max(...scales)).toBeGreaterThan(1)
+    for (const f of springy) expect(Number(f.opacity)).toBeGreaterThanOrEqual(0)
+  })
+
+  test('moves along x and y too', () => {
+    const slid = springKeyframes({ y: 8 }, { y: 0 }, 320)
+    expect(String(slid[0]?.transform)).toContain('translate3d(0px, 8px, 0)')
+    expect(String(slid.at(-1)?.transform)).toContain('translate3d(0px, 0')
+  })
+})

package/src/lib/point-ask/spring-keyframes.ts

@@ -0,0 +1,38 @@
+import { springValueAt } from './spring'
+
+// A spring played as a Web Animations keyframe list: the element moves on the compositor with a
+// spring's shape (critically damped, or overshooting when the gesture carried momentum), and the
+// animation can still be cancelled and re-read mid-flight like any other.
+
+export type SpringFrame = Record<string, number | string>
+
+const lerp = (a: number, b: number, p: number) => a + (b - a) * p
+
+/**
+ * `from` and `to` are the numeric ends of scale, opacity, blur (px), x and y (px); the result is
+ * ready for `element.animate(frames, { duration, easing: 'linear', fill: 'both' })`.
+ */
+export function springKeyframes(
+  from: { scale?: number; opacity?: number; blur?: number; x?: number; y?: number },
+  to: { scale?: number; opacity?: number; blur?: number; x?: number; y?: number },
+  durationMs: number,
+  options: { damping?: number; response?: number; samples?: number } = {},
+): Keyframe[] {
+  const { damping = 1, response = 0.35, samples = 18 } = options
+  const frames: Keyframe[] = []
+  for (let i = 0; i <= samples; i++) {
+    const offset = i / samples
+    // The last frame is the rest exactly: a spring that has not quite settled must not hold short.
+    const p = i === samples ? 1 : springValueAt((offset * durationMs) / 1000, damping, response)
+    const scale = lerp(from.scale ?? 1, to.scale ?? 1, p)
+    const x = lerp(from.x ?? 0, to.x ?? 0, p)
+    const y = lerp(from.y ?? 0, to.y ?? 0, p)
+    frames.push({
+      offset,
+      opacity: Math.min(1, Math.max(0, lerp(from.opacity ?? 1, to.opacity ?? 1, p))),
+      transform: `translate3d(${x}px, ${y}px, 0) scale(${scale})`,
+      filter: `blur(${Math.max(0, lerp(from.blur ?? 0, to.blur ?? 0, p))}px)`,
+    })
+  }
+  return frames
+}

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

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test'
+import { MOMENTUM, SPRING } from './choreography'
+import { Spring } from './spring'
+
+const FRAME = 1 / 60
+
+function run(spring: Spring, seconds: number) {
+  const samples: number[] = []
+  for (let t = 0; t < seconds; t += FRAME) samples.push(spring.step(FRAME))
+  return samples
+}
+
+describe('Spring', () => {
+  test('critically damped, it arrives without overshoot', () => {
+    const spring = new Spring(0, SPRING).to(1)
+    const samples = run(spring, 2)
+
+    expect(Math.max(...samples)).toBeLessThanOrEqual(1 + 1e-3)
+    expect(samples.every((value, i) => i === 0 || value >= samples[i - 1]! - 1e-9)).toBe(true)
+  })
+
+  test('with damping 0.8 it overshoots, then settles', () => {
+    const spring = new Spring(0, MOMENTUM).to(1)
+    const samples = run(spring, 3)
+
+    expect(Math.max(...samples)).toBeGreaterThan(1.01)
+    expect(spring.rest).toBe(true)
+    expect(spring.x).toBe(1)
+  })
+
+  test('settles to rest exactly on its target', () => {
+    const spring = new Spring(0.2).to(0.9)
+    run(spring, 3)
+
+    expect(spring.rest).toBe(true)
+    expect(spring.x).toBe(0.9)
+    expect(spring.v).toBe(0)
+  })
+
+  test('a retarget mid-flight keeps the velocity: no jump, no restart', () => {
+    const spring = new Spring(0, SPRING).to(100)
+    run(spring, 0.1)
+    const velocity = spring.v
+    const position = spring.x
+
+    spring.to(0)
+
+    expect(velocity).toBeGreaterThan(0)
+    expect(spring.v).toBe(velocity)
+    expect(spring.x).toBe(position)
+    // It carries on forward for a moment before it turns back.
+    const next = spring.step(FRAME)
+    expect(next).toBeGreaterThan(position)
+  })
+
+  test('a long frame takes sub-steps and stays stable', () => {
+    const spring = new Spring(0, SPRING).to(1)
+
+    for (let i = 0; i < 20; i++) spring.step(0.25)
+
+    expect(spring.x).toBe(1)
+  })
+})

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

@@ -0,0 +1,107 @@
+import { SPRING, type SpringTokens } from './choreography'
+
+const TAU = Math.PI * 2
+
+/**
+ * A spring in Apple's two parameters: damping (1 = critically damped, below 1 it overshoots) and
+ * response (seconds to arrive). Retargeting keeps the velocity, so an interrupted motion bends to
+ * its new target instead of restarting, which is what makes a grabbed bubble feel held.
+ */
+export class Spring {
+  x: number
+  t: number
+  v = 0
+  private k = 0
+  private c = 0
+
+  constructor(x = 0, params: Partial<SpringTokens> = SPRING) {
+    this.x = this.t = x
+    this.set(params)
+  }
+
+  set({ damping = 1, response = 0.35 }: Partial<SpringTokens> = {}) {
+    this.k = (TAU / response) ** 2
+    this.c = (4 * Math.PI * damping) / response
+    return this
+  }
+
+  to(target: number, params?: Partial<SpringTokens>) {
+    if (params) this.set(params)
+    this.t = target
+    return this
+  }
+
+  snap(x: number) {
+    this.x = this.t = x
+    this.v = 0
+    return this
+  }
+
+  /** Advances by `dt` seconds in sub-steps of at most 1/240 s, so a long frame stays stable. */
+  step(dt: number) {
+    if (this.rest) return this.x
+    const n = Math.max(1, Math.ceil(dt * 240))
+    const s = dt / n
+    for (let i = 0; i < n; i++) {
+      this.v += (-this.k * (this.x - this.t) - this.c * this.v) * s
+      this.x += this.v * s
+    }
+    if (Math.abs(this.x - this.t) < 1e-4 && Math.abs(this.v) < 1e-3) {
+      this.x = this.t
+      this.v = 0
+    }
+    return this.x
+  }
+
+  get rest() {
+    return this.x === this.t && this.v === 0
+  }
+}
+
+/** Two independent springs: 2D motion on one spring desyncs when x and y move at different speeds. */
+export class SpringPair {
+  readonly x: Spring
+  readonly y: Spring
+
+  constructor(x = 0, y = 0, params: Partial<SpringTokens> = SPRING) {
+    this.x = new Spring(x, params)
+    this.y = new Spring(y, params)
+  }
+
+  to(x: number, y: number, params?: Partial<SpringTokens>) {
+    this.x.to(x, params)
+    this.y.to(y, params)
+    return this
+  }
+
+  snap(x: number, y: number) {
+    this.x.snap(x)
+    this.y.snap(y)
+    return this
+  }
+
+  step(dt: number) {
+    this.x.step(dt)
+    this.y.step(dt)
+    return this.value
+  }
+
+  get value() {
+    return { x: this.x.x, y: this.y.x }
+  }
+
+  get rest() {
+    return this.x.rest && this.y.rest
+  }
+}
+
+/** The same spring as a closed-form function of time (0 to 1), for motion locked to a clock. */
+export function springValueAt(t: number, damping = 1, response = 0.35) {
+  if (t <= 0) return 0
+  const w = TAU / response
+  if (damping >= 1) return 1 - (1 + w * t) * Math.exp(-w * t)
+  const wd = w * Math.sqrt(1 - damping * damping)
+  return (
+    1 - Math.exp(-damping * w * t) * (Math.cos(wd * t) + ((damping * w) / wd) * Math.sin(wd * t))
+  )
+}

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

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'bun:test'
+import { followUpSuggestionsFor, suggestionsFor } from './suggestions'
+
+// Chosen locally from the kind and the element's state, with no model call, so they are there on
+// the first frame (spec 2.4). Three chips each, sentence case.
+
+describe('suggestionsFor', () => {
+  test('a room: furnish when it is empty, rearrange when it is not', () => {
+    const empty = suggestionsFor('room', { empty: true })
+    const furnished = suggestionsFor('room', { empty: false })
+
+    expect(empty[0]).not.toBe(furnished[0])
+    expect(suggestionsFor('room', {})[0]).toBe(furnished[0])
+  })
+
+  test('a wall: a window at the clicked station, unless one is there', () => {
+    const bare = suggestionsFor('wall', {})
+    const windowed = suggestionsFor('wall', { hasWindowAtStation: true })
+
+    expect(windowed[0]).not.toBe(bare[0])
+    expect(windowed.slice(1)).toEqual(bare.slice(1))
+  })
+
+  test('every kind gives three, in sentence case, with no duplicates', () => {
+    for (const kind of [
+      'room',
+      'wall',
+      'window',
+      'door',
+      'item',
+      'roof',
+      'stair',
+      'several',
+      'area',
+      'other',
+    ] as const) {
+      const chips = suggestionsFor(kind, {})
+
+      expect(chips).toHaveLength(3)
+      expect(new Set(chips).size).toBe(3)
+      for (const chip of chips) expect(chip[0]).toBe(chip[0]?.toUpperCase())
+    }
+  })
+})
+
+describe('followUpSuggestionsFor', () => {
+  const kinds = [
+    'room',
+    'wall',
+    'window',
+    'door',
+    'item',
+    'roof',
+    'stair',
+    'several',
+    'area',
+    'other',
+  ] as const
+
+  for (const kind of kinds) {
+    test(`${kind}: three fresh chips, none of them what was just asked`, () => {
+      const first = suggestionsFor(kind, {})
+      const chips = followUpSuggestionsFor(kind, first[0] as string)
+
+      expect(chips).toHaveLength(3)
+      expect(new Set(chips).size).toBe(3)
+      expect(chips.map((c) => c.toLowerCase())).not.toContain((first[0] as string).toLowerCase())
+      // "Change more" is not the first bubble again: at most one chip is one it already offered.
+      expect(chips.filter((chip) => first.includes(chip)).length).toBeLessThanOrEqual(1)
+    })
+  }
+
+  test('skips the words just sent, whatever the case or the full stop', () => {
+    const [firstOffered] = followUpSuggestionsFor('window', '')
+    const chips = followUpSuggestionsFor('window', ` ${(firstOffered as string).toUpperCase()}. `)
+
+    expect(chips).toHaveLength(3)
+    expect(chips).not.toContain(firstOffered)
+  })
+})

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

@@ -0,0 +1,125 @@
+import type { PointKind, PointTarget } from './types'
+
+type SuggestionState = {
+  /** A room with nothing in it. */
+  empty?: boolean
+  /** A window already stands where the wall was clicked. */
+  hasWindowAtStation?: boolean
+}
+
+const CHIPS: Record<Exclude<PointKind, 'room' | 'wall'>, [string, string, string]> = {
+  window: ['Make it wider', 'Add a matching window', 'Change the frame colour'],
+  door: ['Flip the swing', 'Make it a sliding door', 'Widen it to 90 cm'],
+  item: ['Swap for something similar', 'Put it against the wall', 'Remove it'],
+  roof: ['Change the pitch', 'Make it a hip roof', 'Change the roofing'],
+  stair: ['Turn it 90°', 'Add a handrail', 'Make it wider'],
+  several: ['Make these match', 'Line them up', 'Space them evenly'],
+  area: ['What’s wrong here?', 'Make this match the reference', 'Tidy this up'],
+  other: ['Tell me about this', 'Change its finish', 'Remove it'],
+}
+
+/**
+ * Three chips chosen locally from the kind and the element's state, with no model call, so they
+ * are there on the first frame and teach what Pascal can do here (spec 2.4).
+ */
+export function suggestionsFor(kind: PointKind, state: SuggestionState = {}): string[] {
+  if (kind === 'room')
+    return [
+      state.empty ? 'Furnish this room' : 'Rearrange the furniture',
+      'Make it 1 m longer',
+      'Change the floor finish',
+    ]
+  if (kind === 'wall')
+    return [
+      state.hasWindowAtStation ? 'Move the window along the wall' : 'Add a window here',
+      'Change the finish on this side',
+      'Move it 50 cm',
+    ]
+  return [...CHIPS[kind]]
+}
+
+const THIS: Partial<Record<PointKind, string>> = {
+  wall: 'this wall',
+  window: 'this window',
+  door: 'this door',
+  item: 'this item',
+  roof: 'this roof',
+  stair: 'this stair',
+}
+
+/** "Ask about Kitchen…", "Ask about this window…", "Ask about these…", "Ask about this area…". */
+export function placeholderFor(targets: readonly PointTarget[]): string {
+  if (targets.length === 0) return 'Ask about this area…'
+  if (targets.length > 1) return 'Ask about these…'
+  const [only] = targets as [PointTarget]
+  if (only.kind === 'room') return `Ask about ${only.name}…`
+  if (only.kind === 'area') return 'Ask about this area…'
+  return `Ask about ${THIS[only.kind] ?? 'this'}…`
+}
+
+/** What the chips are chosen by, from a node's type. A region is an area whatever it holds. */
+export function kindOf(nodeType: string, isRegion = false): PointKind {
+  if (isRegion) return 'area'
+  switch (nodeType) {
+    case 'zone':
+      return 'room'
+    case 'wall':
+      return 'wall'
+    case 'window':
+      return 'window'
+    case 'door':
+      return 'door'
+    case 'item':
+    case 'procedural-item':
+    case 'imported-mesh':
+    case 'column':
+      return 'item'
+    case 'roof':
+    case 'roof-segment':
+      return 'roof'
+    case 'stair':
+    case 'stair-segment':
+      return 'stair'
+    default:
+      return 'other'
+  }
+}
+
+export function kindForTargets(targets: readonly PointTarget[], isRegion = false): PointKind {
+  if (isRegion || targets.length === 0) return 'area'
+  if (targets.length > 1) return 'several'
+  return (targets[0] as PointTarget).kind
+}
+
+const FOLLOW_UP_CHIPS: Record<PointKind, string[]> = {
+  room: ['Add a rug', 'Change the wall colour', 'Hang something on the walls', 'Add more light'],
+  wall: ['Add a door here', 'Paint this wall', 'Hang something on it', 'Make it thicker'],
+  window: [
+    'Make it taller',
+    'Move it 30 cm along the wall',
+    'Change the sill height',
+    'Add a matching window',
+  ],
+  door: ['Make it wider', 'Move it along the wall', 'Change the colour', 'Add a window beside it'],
+  item: ['Turn it 90°', 'Make it bigger', 'Change its colour', 'Add another one'],
+  roof: ['Add a skylight', 'Make the eaves longer', 'Change the colour', 'Add a chimney'],
+  stair: ['Add a landing', 'Change the treads', 'Move it 50 cm', 'Make the rise lower'],
+  several: ['Make them bigger', 'Change their colour', 'Group them', 'Remove the second one'],
+  area: ['Add something here', 'Clear this space', 'Make it brighter', 'Change the floor here'],
+  other: ['Make it bigger', 'Change the colour', 'Move it 50 cm', 'Duplicate it'],
+}
+
+const plain = (words: string) =>
+  words
+    .trim()
+    .toLowerCase()
+    .replace(/[.!?…]+$/u, '')
+
+/**
+ * Three chips for asking again on what a turn just changed ("Change more"): the next things to
+ * try, never the words that were just sent.
+ */
+export function followUpSuggestionsFor(kind: PointKind, justAsked: string): string[] {
+  const sent = plain(justAsked)
+  return FOLLOW_UP_CHIPS[kind].filter((chip) => plain(chip) !== sent).slice(0, 3)
+}