@impractical-ai/motion 0.1.7 → 0.1.9

package/assets/kits/actions.ts

@@ -1,803 +0,0 @@
-// ─── Actions — cursor, click, drag, scroll, and UI state primitives ────────
-//
-// The interaction vocabulary that every scene used to hand-roll: cursors that
-// travel and click, buttons that squash, containers that scroll, UI state that
-// changes on the timeline. One call per action, one Tweak row per gesture,
-// perceptually-tuned defaults where scenes used to carry magic numbers.
-//
-// The cursor is a STATEFUL ACTOR, not a per-call sprite. The kit tracks where
-// every cursor is and whether it is on screen, so continuation is the default
-// and entry/exit are explicit moments:
-//
-//   cursor.click('[data-new]')                  // enters from the nearest edge,
-//   type('[data-input]', 'hello')               //   travels, morphs, clicks
-//   cursor.click('[data-send]')                 // continues FROM WHERE IT WAS
-//   cursor.exit()                               // leaves via the nearest edge
-//
-// Icons live in the engine with REGISTERED HOTSPOTS (where the tip actually
-// is), so click math can never drift the way per-scene hand-rolled rigs did.
-// Every action defaults to `ease-in-out-cubic` and takes a `duration`; the two
-// deliberate exceptions are typing (stepped by definition, see typeInto) and
-// `ui.set` (instant — a cut is hard).
-//
-// Everything obeys the kit conventions: factory, every tween through `deps.tl`,
-// `(target, opts?, position?)`, returns `{ duration }`, deterministic — no
-// clocks, no randomness; the idle "human" drift is a fixed sine.
-
-import gsap from 'gsap'
-import { createWarner, layoutRect as sharedLayoutRect, visualRect as sharedVisualRect, resolveTarget } from './kits'
-
-type Rect = { left: number; top: number; width: number; height: number }
-
-export type ActionsDeps = {
-  tl: gsap.core.Timeline
-  stage: HTMLElement
-  config: { width: number; height: number }
-}
-
-/** Built-in cursor icons. `collab` is the Figma-style colored arrow + name
- * chip for multi-user scenes. Custom art passes `{ svg, hotspot }` — the
- * hotspot (0..1 of the icon box, where the tip sits) is part of the contract,
- * so brand cursors cannot reopen the misaligned-click bug. */
-export type CursorIconName =
-  | 'arrow'
-  | 'pointer'
-  | 'ibeam'
-  | 'grab'
-  | 'grabbing'
-  | 'crosshair'
-  | 'collab'
-export type CursorIcon = CursorIconName | { svg: string; hotspot: { x: number; y: number } }
-
-export type CursorActorOpts = {
-  /** Icon set. Default 'arrow'; named collaborators usually want 'collab'. */
-  icon?: CursorIcon
-  /** Tint for the collab arrow and label chip. */
-  color?: string
-  /** Figma-style name tag riding the cursor. */
-  label?: string
-  /** Icon box size in scene px. Default 56 (at 1080p) — marketing videos
-   * oversize the cursor so the action reads at a glance. */
-  size?: number
-  /** 'still' (default) or 'human' — sub-pixel drift while parked between
-   * actions, so a resting cursor never reads as a freeze-frame. */
-  idle?: 'still' | 'human'
-  /** Auto-morph arrow → pointer over the last stretch of a click travel.
-   * Default true. */
-  morph?: boolean
-}
-
-export type CursorMoveOpts = {
-  /** Travel time in seconds. Default 0.8. */
-  duration?: number
-  /** Default 'ease-in-out-cubic' — every action eases in-out. */
-  ease?: string
-  /** Where on the target to land, as fractions of its box. Default
-   * `{ x: 0.5, y: 0.52 }` — the corpus's observed natural click point. */
-  anchor?: { x?: number; y?: number }
-  /** Extra scene-px nudge after the anchor. */
-  offset?: { x?: number; y?: number }
-  /** First-action entrance: 'edge' (default — slides in from the nearest
-   * frame edge) or 'fade' (materializes just short of the target, for tight
-   * close-ups where the edge is far away). Ignored while already visible. */
-  enter?: 'edge' | 'fade'
-}
-
-/** What the cursor does after the action — the continuity contract.
- * 'stay' (default) parks it where it is so the NEXT action continues from
- * there; 'exit' leaves via the nearest edge; 'park' steps aside just below
- * the target (clears it for typing or a reveal); a selector travels to that
- * element and parks there. */
-export type CursorThen = 'stay' | 'exit' | 'park' | string
-
-export type CursorClickOpts = CursorMoveOpts & {
-  /** Target squash scale. 'auto' (default) derives from the element's size —
-   * big surfaces squash less. A number (e.g. 0.9) is used verbatim. */
-  press?: number | 'auto'
-  /** Squash time each way. Default 0.09. */
-  pressDuration?: number
-  then?: CursorThen
-}
-
-export type CursorDragOpts = CursorMoveOpts & {
-  /** Subtle scale lift on the payload while it is held. Default true. */
-  lift?: boolean
-  then?: CursorThen
-}
-
-export type CursorExitOpts = {
-  duration?: number
-  ease?: string
-  /** 'edge' (default) or 'fade'. */
-  via?: 'edge' | 'fade'
-}
-
-export type CursorActor = {
-  /** Move to an element (or continue there from the last position). */
-  to: (
-    target: string | Element,
-    opts?: CursorMoveOpts,
-    position?: gsap.Position
-  ) => { duration: number }
-  /** Travel + press: squashes the cursor AND the target, ordered so the
-   * click visibly precedes any result the direction schedules after it. */
-  click: (
-    target: string | Element,
-    opts?: CursorClickOpts,
-    position?: gsap.Position
-  ) => { duration: number }
-  /** Grab a payload and carry it: cursor and payload move as ONE tween pair
-   * with identical timing, so they cannot desync. `to` is an element/selector
-   * (payload centers on it) or a scene-px delta `{ x, y }`. */
-  drag: (
-    payload: string | Element,
-    to: string | Element | { x: number; y: number },
-    opts?: CursorDragOpts,
-    position?: gsap.Position
-  ) => { duration: number }
-  /** Leave the frame. The next action re-enters fresh. */
-  exit: (opts?: CursorExitOpts, position?: gsap.Position) => { duration: number }
-  /** Update the collab name chip on the timeline. */
-  label: (text: string, position?: gsap.Position) => void
-}
-
-export type CursorKit = CursorActor & {
-  /** Declare a named cursor — an independent actor with its own icon, color,
-   * label chip, and continuity state. Two actors animate concurrently just by
-   * overlapping their positions. */
-  actor: (name: string, opts?: CursorActorOpts) => CursorActor
-}
-
-export type PressOpts = {
-  /** Squash scale; 'auto' (default) derives from element size. */
-  amount?: number | 'auto'
-  /** Each way. Default 0.09. */
-  duration?: number
-  ease?: string
-}
-
-export type ScrollOpts = {
-  duration?: number
-  ease?: string
-  /** Where the target settles in the container: 0 top, 0.5 center (default),
-   * 1 bottom. */
-  align?: number
-}
-
-export type UiChange = {
-  /** Replace the element's text content. */
-  text?: string
-  /** Set an input's value. */
-  value?: string
-  /** Swap an image/video source. */
-  src?: string
-  /** Set attributes verbatim. */
-  attrs?: Record<string, string>
-  /** Add/remove classes (resolved against the authored class list). */
-  classes?: { add?: string[]; remove?: string[] }
-  /** Brief brightness pulse after the change, so the state change reads as an
-   * event rather than a glitch. */
-  flash?: boolean
-}
-
-export type ActionsKit = {
-  cursor: CursorKit
-  /** Squash without a cursor — keyboard sends, programmatic actions. */
-  press: (
-    target: string | Element,
-    opts?: PressOpts,
-    position?: gsap.Position
-  ) => { duration: number }
-  /** Animated scroll of a container until `to` (element, selector, or an
-   * absolute scrollTop) is in view. `duration: 0` sets it instantly for
-   * initial state. */
-  scroll: (
-    container: string | Element,
-    to: string | Element | number,
-    opts?: ScrollOpts,
-    position?: gsap.Position
-  ) => { duration: number }
-  /** Declarative hard UI state change on the timeline (seek-reversible).
-   * Instant by design — a cut is hard; `flash` adds the one animated accent. */
-  ui: {
-    set: (
-      target: string | Element,
-      change: UiChange,
-      position?: gsap.Position
-    ) => { duration: number }
-  }
-}
-
-// ─── icon library ─────────────────────────────────────────────────────────
-// All 32x32 viewBox. White fill + ink outline reads on any background; the
-// collab arrow takes the actor's color. Hotspots are FRACTIONS of the icon
-// box marking where the functional tip sits.
-
-const OUTLINE = 'stroke="#1a1a1f" stroke-width="1.6" stroke-linejoin="round"'
-
-const ICONS: Record<CursorIconName, { svg: (color: string) => string; hotspot: { x: number; y: number } }> = {
-  arrow: {
-    svg: () =>
-      `<svg viewBox="0 0 32 32"><path d="M8 3 L8 24.5 L13.4 19.6 L16.9 27.2 L20.1 25.7 L16.6 18.3 L23.8 17.9 Z" fill="#fff" ${OUTLINE}/></svg>`,
-    hotspot: { x: 0.25, y: 0.09 },
-  },
-  pointer: {
-    svg: () =>
-      `<svg viewBox="0 0 32 32"><path d="M12.2 3.6 a1.7 1.7 0 0 1 3.4 0 V13.6 h1.1 V8.2 a1.7 1.7 0 0 1 3.4 0 v6 h1.1 V10.4 a1.7 1.7 0 0 1 3.4 0 v9.2 c0 4.6-3.1 8.2-7.7 8.2 h-1.2 c-3 0-5.2-1.6-6.6-4.1 l-3-5.3 c-0.6-1.1 0.7-2.3 1.8-1.6 l3.3 2 V3.6 z" fill="#fff" ${OUTLINE}/></svg>`,
-    hotspot: { x: 0.43, y: 0.06 },
-  },
-  ibeam: {
-    svg: () =>
-      `<svg viewBox="0 0 32 32"><path d="M11 4 h4 v1.8 h3 V4 h4 M16 5.8 V26.2 M11 28 h4 v-1.8 h3 V28 h4 M13 4.9 h6 M13 27.1 h6" fill="none" stroke="#fff" stroke-width="4"/><path d="M11 4 h10 M11 28 h10 M16 5 V27" fill="none" stroke="#1a1a1f" stroke-width="1.8"/></svg>`,
-    hotspot: { x: 0.5, y: 0.5 },
-  },
-  grab: {
-    svg: () =>
-      `<svg viewBox="0 0 32 32"><path d="M9.5 15 v-3 a1.7 1.7 0 0 1 3.4 0 v-2 a1.7 1.7 0 0 1 3.4 0 v-0.6 a1.7 1.7 0 0 1 3.4 0 v1.6 a1.7 1.7 0 0 1 3.4 0 v7.5 c0 4.4-3 7.5-7.4 7.5 h-0.8 c-2.9 0-4.9-1.5-6.3-3.9 l-1.7-3 c-0.6-1.1 0.6-2.3 1.7-1.7 z" fill="#fff" ${OUTLINE}/></svg>`,
-    hotspot: { x: 0.5, y: 0.45 },
-  },
-  grabbing: {
-    svg: () =>
-      `<svg viewBox="0 0 32 32"><path d="M9.5 17 v-1.5 a1.7 1.7 0 0 1 3.4 0 v-1 a1.7 1.7 0 0 1 3.4 0 v-0.4 a1.7 1.7 0 0 1 3.4 0 v0.8 a1.7 1.7 0 0 1 3.4 0 v5.6 c0 4.2-3 7-7.4 7 h-0.8 c-2.9 0-4.9-1.4-6.3-3.7 l-1.4-2.4 c-0.6-1.1 0.6-2.3 1.7-1.7 z" fill="#fff" ${OUTLINE}/></svg>`,
-    hotspot: { x: 0.5, y: 0.5 },
-  },
-  crosshair: {
-    svg: () =>
-      `<svg viewBox="0 0 32 32"><path d="M16 5 V27 M5 16 H27" fill="none" stroke="#fff" stroke-width="4"/><path d="M16 5 V27 M5 16 H27" fill="none" stroke="#1a1a1f" stroke-width="1.6"/></svg>`,
-    hotspot: { x: 0.5, y: 0.5 },
-  },
-  collab: {
-    svg: (color) =>
-      `<svg viewBox="0 0 32 32"><path d="M8 3 L8 24.5 L13.4 19.6 L16.9 27.2 L20.1 25.7 L16.6 18.3 L23.8 17.9 Z" fill="${color}" stroke="#fff" stroke-width="1.6" stroke-linejoin="round"/></svg>`,
-    hotspot: { x: 0.25, y: 0.09 },
-  },
-}
-
-/** The icon layers a built-in actor carries, so morphs are opacity crossfades
- * between pre-rendered siblings (deterministic and seek-reversible). */
-const MORPH_SET: CursorIconName[] = ['arrow', 'pointer', 'grab', 'grabbing']
-
-const DEFAULTS = {
-  size: 56,
-  travel: 0.8,
-  ease: 'ease-in-out-cubic',
-  anchor: { x: 0.5, y: 0.52 },
-  pressDuration: 0.09,
-  exitDuration: 0.5,
-  enterFade: 0.18,
-  morphDuration: 0.12,
-}
-
-/** Target squash from its smallest dimension: a 48px chip squashes to 0.86,
- * a 400px+ surface barely moves (0.97). This is the one press parameter the
- * corpus varied LEGITIMATELY by element size — so it is a derivation, not a
- * constant. */
-export function autoPressAmount(rect: { width: number; height: number }): number {
-  const d = Math.min(rect.width, rect.height)
-  const t = Math.min(1, Math.max(0, (d - 48) / 352))
-  return Math.round((0.86 + t * 0.11) * 1000) / 1000
-}
-
-/** Entry point just outside the nearest frame edge to `p`, so a cursor's
- * first travel reads as "someone's hand arrived", not a teleport. */
-export function nearestEdgeStart(
-  p: { x: number; y: number },
-  frame: { width: number; height: number },
-  margin: number
-): { x: number; y: number } {
-  const candidates = [
-    { d: p.x, x: -margin, y: p.y },
-    { d: frame.width - p.x, x: frame.width + margin, y: p.y },
-    { d: p.y, x: p.x, y: -margin },
-    { d: frame.height - p.y, x: p.x, y: frame.height + margin },
-  ]
-  candidates.sort((a, b) => a.d - b.d)
-  return { x: candidates[0].x, y: candidates[0].y }
-}
-
-// ─── the kit ──────────────────────────────────────────────────────────────
-
-type ActorState = {
-  el: HTMLElement
-  layers: Partial<Record<string, HTMLElement>>
-  chip: HTMLElement | null
-  hotspot: { x: number; y: number }
-  size: number
-  idle: 'still' | 'human'
-  morph: boolean
-  baseIcon: string
-  activeIcon: string
-  /** Scene-px position of the HOTSPOT after the last action. Null = off. */
-  pos: { x: number; y: number } | null
-  visible: boolean
-  /** Timeline second at which this actor's last action ends. */
-  clock: number | null
-}
-
-export function createActionsKit(deps: ActionsDeps): ActionsKit {
-  const { tl, stage, config } = deps
-  const warn = createWarner('actions')
-  let actorCount = 0
-  let labelCount = 0
-
-  /** Rect in authored-layout scene coords — see kits.ts `layoutRect`. */
-  const layoutRect = (el: HTMLElement): Rect => sharedLayoutRect(stage, el)
-
-  /** Rect where the element sits RIGHT NOW (authored transforms included) —
-   * see kits.ts `visualRect`. Aim points resolve through this at action time. */
-  const visualRect = (el: HTMLElement): Rect => sharedVisualRect(stage, el)
-
-  /** Resolve any gsap position expression to absolute seconds via a label. */
-  const resolvePosition = (position: gsap.Position | undefined, fallback: number): number => {
-    if (position === undefined) return fallback
-    if (typeof position === 'number') return position
-    const name = `__action-${labelCount++}`
-    tl.addLabel(name, position)
-    return tl.labels[name] ?? fallback
-  }
-
-  const anchorPoint = (
-    target: string | Element,
-    opts: CursorMoveOpts,
-    kind: string
-  ): { el: HTMLElement; rect: Rect; x: number; y: number; resolve: () => { x: number; y: number } } => {
-    const el = resolveTarget(stage, target, kind)
-    const rect = layoutRect(el)
-    const ax = opts.anchor?.x ?? DEFAULTS.anchor.x
-    const ay = opts.anchor?.y ?? DEFAULTS.anchor.y
-    const point = (r: Rect) => ({
-      x: r.left + r.width * ax + (opts.offset?.x ?? 0),
-      y: r.top + r.height * ay + (opts.offset?.y ?? 0),
-    })
-    const estimate = point(rect)
-    return {
-      el,
-      rect,
-      x: estimate.x,
-      y: estimate.y,
-      // Resolved when the travel tween first renders, not when the direction
-      // builds: a container the direction scales mid-timeline (a shell zoom)
-      // has moved the target by then, and only the at-render rect knows where.
-      resolve: () => point(visualRect(el)),
-    }
-  }
-
-  const squash = (
-    el: HTMLElement,
-    amount: number,
-    each: number,
-    at: number,
-    origin = '50% 50%'
-  ) => {
-    tl.to(
-      el,
-      {
-        scale: amount,
-        duration: each,
-        repeat: 1,
-        yoyo: true,
-        ease: 'ease-in-out-quad',
-        transformOrigin: origin,
-      },
-      at
-    )
-  }
-
-  function buildActor(name: string, opts: CursorActorOpts): CursorActor {
-    const size = opts.size ?? DEFAULTS.size
-    const color = opts.color ?? '#5865F2'
-    const iconOpt = opts.icon ?? 'arrow'
-    const custom = typeof iconOpt === 'object' ? iconOpt : null
-    const baseIcon = custom ? 'custom' : (iconOpt as string)
-    const hotspot = custom ? custom.hotspot : ICONS[iconOpt as CursorIconName].hotspot
-
-    const el = document.createElement('div')
-    el.setAttribute(`data-cursor-${name}`, '')
-    el.style.cssText = `position:absolute;left:0;top:0;width:${size}px;height:${size}px;pointer-events:none;z-index:${9990 + actorCount};filter:drop-shadow(0 1.5px 3px rgba(0,0,0,0.35));`
-
-    const layers: Partial<Record<string, HTMLElement>> = {}
-    const addLayer = (key: string, svg: string, visible: boolean) => {
-      const layer = document.createElement('div')
-      layer.style.cssText = `position:absolute;inset:0;opacity:${visible ? 1 : 0};`
-      layer.innerHTML = svg
-      el.appendChild(layer)
-      layers[key] = layer
-    }
-    if (custom) {
-      addLayer('custom', custom.svg, true)
-    } else if (MORPH_SET.includes(baseIcon as CursorIconName)) {
-      // The morphing set is pre-rendered as stacked siblings so every morph is
-      // an opacity crossfade — deterministic and seek-reversible.
-      for (const key of MORPH_SET) addLayer(key, ICONS[key].svg(color), key === baseIcon)
-    } else {
-      addLayer(baseIcon, ICONS[baseIcon as CursorIconName].svg(color), true)
-    }
-
-    let chip: HTMLElement | null = null
-    if (opts.label) {
-      chip = document.createElement('div')
-      chip.textContent = opts.label
-      chip.style.cssText = `position:absolute;left:${size * 0.62}px;top:${size * 0.72}px;background:${color};color:#fff;font:600 ${Math.round(size * 0.34)}px/1.25 system-ui,sans-serif;padding:2px 8px;border-radius:999px;white-space:nowrap;box-shadow:0 1px 3px rgba(0,0,0,0.25);`
-      el.appendChild(chip)
-    }
-
-    gsap.set(el, { autoAlpha: 0, x: -size * 3, y: -size * 3, force3D: false })
-    stage.appendChild(el)
-
-    const state: ActorState = {
-      el,
-      layers,
-      chip,
-      hotspot,
-      size,
-      idle: opts.idle ?? 'still',
-      morph: opts.morph ?? true,
-      baseIcon,
-      activeIcon: baseIcon,
-      pos: null,
-      visible: false,
-      clock: null,
-    }
-    actorCount += 1
-
-    /** Wrapper x/y from a hotspot scene point. */
-    const place = (p: { x: number; y: number }) => ({
-      x: p.x - state.hotspot.x * state.size,
-      y: p.y - state.hotspot.y * state.size,
-    })
-
-    const morphTo = (icon: string, at: number) => {
-      if (!state.morph || icon === state.activeIcon) return
-      const fromLayer = state.layers[state.activeIcon]
-      const toLayer = state.layers[icon]
-      if (!fromLayer || !toLayer) return
-      tl.to(fromLayer, { opacity: 0, duration: DEFAULTS.morphDuration, ease: 'ease-in-out-quad' }, at)
-      tl.to(toLayer, { opacity: 1, duration: DEFAULTS.morphDuration, ease: 'ease-in-out-quad' }, at)
-      state.activeIcon = icon
-    }
-
-    /** Common start-of-action bookkeeping: resolve the start second, warn on
-     * mid-travel overlap, and fill a long park with the idle drift. */
-    const begin = (position: gsap.Position | undefined): number => {
-      const start = resolvePosition(position, state.clock ?? tl.duration())
-      if (state.clock !== null && start < state.clock - 1e-6) {
-        warn(
-          `overlap-${name}`,
-          `cursor "${name}" is scheduled at ${start.toFixed(2)}s while still mid-action ` +
-            `until ${state.clock.toFixed(2)}s — author each cursor's actions in order.`
-        )
-      }
-      if (
-        state.idle === 'human' &&
-        state.visible &&
-        state.clock !== null &&
-        start - state.clock > 0.4
-      ) {
-        const gap = start - state.clock
-        tl.to(
-          el,
-          { x: '+=2.4', y: '-=1.8', duration: gap / 2, repeat: 1, yoyo: true, ease: 'sine.inOut' },
-          state.clock
-        )
-      }
-      return start
-    }
-
-    /** The label chip rides along during travel and fades just after arrival —
-     * parked on target it occludes exactly the thing the cursor points at. */
-    const chipRide = (start: number, duration: number) => {
-      if (!chip) return
-      tl.set(chip, { autoAlpha: 1 }, start)
-      tl.to(chip, { autoAlpha: 0, duration: 0.18, ease: 'ease-in-quad' }, start + duration + 0.15)
-    }
-
-    /** Travel the hotspot to scene point `p`. Returns total travel duration. */
-    const travelTo = (
-      p: { x: number; y: number },
-      opts: CursorMoveOpts,
-      start: number,
-      resolve?: () => { x: number; y: number }
-    ): number => {
-      const duration = opts.duration ?? DEFAULTS.travel
-      const ease = opts.ease ?? DEFAULTS.ease
-      const dest = place(p)
-      // Destination resolves when the tween first renders: by then every
-      // earlier tween (container zooms included) has applied, so the aim is
-      // taken from where the target actually sits, not its resting layout.
-      const destX = resolve ? () => place(resolve()).x : dest.x
-      const destY = resolve ? () => place(resolve()).y : dest.y
-      if (!state.visible) {
-        const enter = opts.enter ?? 'edge'
-        const from =
-          enter === 'fade'
-            ? { x: dest.x - state.size * 0.7, y: dest.y - state.size * 0.5 }
-            : place(nearestEdgeStart(p, config, state.size * 1.5))
-        tl.fromTo(
-          el,
-          { autoAlpha: 0 },
-          { autoAlpha: 1, duration: DEFAULTS.enterFade, ease: 'ease-out-quad' },
-          start
-        )
-        tl.fromTo(el, { x: from.x, y: from.y }, { x: destX, y: destY, duration, ease }, start)
-      } else {
-        tl.to(el, { x: destX, y: destY, duration, ease }, start)
-      }
-      chipRide(start, duration)
-      state.pos = p
-      state.visible = true
-      return duration
-    }
-
-    const doExit = (opts: CursorExitOpts, start: number): number => {
-      if (!state.visible || !state.pos) {
-        warn(`exit-${name}`, `cursor "${name}" exit was skipped — it is not on screen.`)
-        return 0
-      }
-      const duration = opts.duration ?? DEFAULTS.exitDuration
-      const ease = opts.ease ?? DEFAULTS.ease
-      if ((opts.via ?? 'edge') === 'edge') {
-        const out = place(nearestEdgeStart(state.pos, config, state.size * 1.5))
-        tl.to(el, { x: out.x, y: out.y, duration, ease }, start)
-      }
-      tl.to(
-        el,
-        { autoAlpha: 0, duration: Math.min(0.15, duration), ease: 'ease-in-quad' },
-        start + duration - Math.min(0.15, duration)
-      )
-      morphTo(state.baseIcon, start + duration)
-      state.visible = false
-      state.pos = null
-      state.clock = start + duration
-      return duration
-    }
-
-    const handleThen = (then: CursorThen | undefined, at: number): number => {
-      if (!then || then === 'stay') return 0
-      if (then === 'exit') return 0.25 + doExit({}, at + 0.25)
-      if (then === 'park') {
-        const p = { x: state.pos!.x + 56, y: state.pos!.y + 46 }
-        const dest = place(p)
-        tl.to(el, { x: dest.x, y: dest.y, duration: 0.35, ease: DEFAULTS.ease }, at + 0.2)
-        state.pos = p
-        return 0.55
-      }
-      // A selector: travel there and park.
-      const point = anchorPoint(then, {}, 'cursor.then')
-      tl.to(
-        el,
-        {
-          x: () => place(point.resolve()).x,
-          y: () => place(point.resolve()).y,
-          duration: 0.6,
-          ease: DEFAULTS.ease,
-        },
-        at + 0.3
-      )
-      state.pos = { x: point.x, y: point.y }
-      return 0.9
-    }
-
-    const actor: CursorActor = {
-      to: (target, opts = {}, position) => {
-        const start = begin(position)
-        const point = anchorPoint(target, opts, 'cursor.to')
-        const duration = travelTo(point, opts, start, point.resolve)
-        state.clock = start + duration
-        return { duration }
-      },
-
-      click: (target, opts = {}, position) => {
-        const start = begin(position)
-        const point = anchorPoint(target, opts, 'cursor.click')
-        const travel = travelTo(point, opts, start, point.resolve)
-        // Arrow melts into the pointer hand over the last stretch of travel —
-        // the detail that makes a click read as intentional.
-        if (state.baseIcon === 'arrow') morphTo('pointer', start + travel * 0.85)
-        const each = opts.pressDuration ?? DEFAULTS.pressDuration
-        const arrive = start + travel
-        squash(
-          el,
-          0.9,
-          each,
-          arrive,
-          `${state.hotspot.x * 100}% ${state.hotspot.y * 100}%`
-        )
-        const amount =
-          typeof opts.press === 'number' ? opts.press : autoPressAmount(point.rect)
-        squash(point.el, amount, each, arrive)
-        if (state.baseIcon === 'arrow') morphTo('arrow', arrive + each * 2 + 0.3)
-        state.clock = arrive + each * 2
-        const tail = handleThen(opts.then, state.clock)
-        state.clock += tail
-        return { duration: travel + each * 2 + tail }
-      },
-
-      drag: (payload, to, opts = {}, position) => {
-        const start = begin(position)
-        const payloadEl = resolveTarget(stage, payload, 'cursor.drag')
-        const payloadRect = layoutRect(payloadEl)
-        const gax = opts.anchor?.x ?? 0.5
-        const gay = opts.anchor?.y ?? 0.5
-        const grabResolve = () => {
-          const r = visualRect(payloadEl)
-          return { x: r.left + r.width * gax, y: r.top + r.height * gay }
-        }
-        const grabPoint = {
-          el: payloadEl,
-          rect: payloadRect,
-          x: payloadRect.left + payloadRect.width * gax,
-          y: payloadRect.top + payloadRect.height * gay,
-        }
-        const approach = travelTo(
-          { x: grabPoint.x, y: grabPoint.y },
-          { ...opts, duration: 0.6 },
-          start,
-          grabResolve
-        )
-        const grabAt = start + approach
-        morphTo('grab', grabAt - 0.1)
-        morphTo('grabbing', grabAt + 0.08)
-
-        let delta: { x: number; y: number }
-        if (typeof to === 'object' && 'x' in to && !('nodeType' in (to as object))) {
-          delta = { x: (to as { x: number }).x, y: (to as { y: number }).y }
-        } else {
-          const dest = resolveTarget(stage, to as string | Element, 'cursor.drag destination')
-          const destRect = layoutRect(dest)
-          delta = {
-            x: destRect.left + destRect.width / 2 - (payloadRect.left + payloadRect.width / 2),
-            y: destRect.top + destRect.height / 2 - (payloadRect.top + payloadRect.height / 2),
-          }
-        }
-
-        const carry = opts.duration ?? 1.0
-        const ease = opts.ease ?? DEFAULTS.ease
-        const holdBeat = 0.16
-        const carryAt = grabAt + holdBeat
-        if (opts.lift !== false) {
-          tl.to(payloadEl, { scale: 1.04, duration: holdBeat, ease: 'ease-out-quad' }, grabAt)
-          tl.to(payloadEl, { scale: 1, duration: 0.2, ease: 'ease-out-quad' }, carryAt + carry)
-        }
-        // One delta, two targets, identical timing — the pair cannot desync.
-        // The payload's delta is layout-space: payload and destination share a
-        // container, so any ancestor scale applies to both equally and the
-        // authored delta is exactly the transform the payload needs. The CURSOR
-        // lives in stage space, so its version of the same delta must be
-        // multiplied by whatever the container's ancestors scale it to on
-        // screen — measured at carry time, after any shell zoom has applied.
-        // This tween is inserted BEFORE the payload's, so its function values
-        // resolve while the payload still sits at the grab point.
-        const carryDest = () => {
-          const grab = grabResolve()
-          const scale = payloadRect.width ? visualRect(payloadEl).width / payloadRect.width : 1
-          return place({ x: grab.x + delta.x * scale, y: grab.y + delta.y * scale })
-        }
-        tl.to(el, { x: () => carryDest().x, y: () => carryDest().y, duration: carry, ease }, carryAt)
-        tl.to(payloadEl, { x: `+=${delta.x}`, y: `+=${delta.y}`, duration: carry, ease }, carryAt)
-        morphTo('grab', carryAt + carry + 0.02)
-        morphTo('arrow', carryAt + carry + 0.24)
-        state.pos = { x: state.pos!.x + delta.x, y: state.pos!.y + delta.y }
-        state.clock = carryAt + carry + 0.2
-        const tail = handleThen(opts.then, state.clock)
-        state.clock += tail
-        return { duration: state.clock - start }
-      },
-
-      exit: (opts = {}, position) => {
-        const start = begin(position)
-        return { duration: doExit(opts, start) }
-      },
-
-      label: (text, position) => {
-        if (!chip) {
-          warn(`chip-${name}`, `cursor "${name}" has no label chip — declare it with a label.`)
-          return
-        }
-        const at = typeof position === 'number' ? position : (state.clock ?? tl.duration())
-        tl.set(chip, { textContent: text, autoAlpha: 1 }, at)
-        tl.to(chip, { autoAlpha: 0, duration: 0.18, ease: 'ease-in-quad' }, at + 1.2)
-      },
-    }
-    return actor
-  }
-
-  const actors = new Map<string, CursorActor>()
-  const defaultActor = () => {
-    let actor = actors.get('__default')
-    if (!actor) {
-      actor = buildActor('main', {})
-      actors.set('__default', actor)
-    }
-    return actor
-  }
-
-  const cursor: CursorKit = {
-    to: (target, opts, position) => defaultActor().to(target, opts, position),
-    click: (target, opts, position) => defaultActor().click(target, opts, position),
-    drag: (payload, to, opts, position) => defaultActor().drag(payload, to, opts, position),
-    exit: (opts, position) => defaultActor().exit(opts, position),
-    label: (text, position) => defaultActor().label(text, position),
-    actor: (name, opts = {}) => {
-      let actor = actors.get(name)
-      if (!actor) {
-        actor = buildActor(name, opts)
-        actors.set(name, actor)
-      }
-      return actor
-    },
-  }
-
-  const press: ActionsKit['press'] = (target, opts = {}, position) => {
-    const el = resolveTarget(stage, target, 'press')
-    const rect = layoutRect(el)
-    const each = opts.duration ?? DEFAULTS.pressDuration
-    const amount = typeof opts.amount === 'number' ? opts.amount : autoPressAmount(rect)
-    const at = resolvePosition(position, tl.duration())
-    tl.to(
-      el,
-      {
-        scale: amount,
-        duration: each,
-        repeat: 1,
-        yoyo: true,
-        ease: opts.ease ?? 'ease-in-out-quad',
-        transformOrigin: '50% 50%',
-      },
-      at
-    )
-    return { duration: each * 2 }
-  }
-
-  const scroll: ActionsKit['scroll'] = (container, to, opts = {}, position) => {
-    const el = resolveTarget(stage, container, 'scroll')
-    let desired: number
-    if (typeof to === 'number') {
-      desired = to
-    } else {
-      const targetEl = resolveTarget(stage, to, 'scroll target')
-      const crect = layoutRect(el)
-      const trect = layoutRect(targetEl)
-      const align = opts.align ?? 0.5
-      const clientH = el.clientHeight
-      desired = el.scrollTop + (trect.top - crect.top) - (clientH - trect.height) * align
-    }
-    desired = Math.max(0, Math.min(desired, el.scrollHeight - el.clientHeight))
-    const duration = opts.duration ?? 0.7
-    const at = resolvePosition(position, tl.duration())
-    if (duration <= 0) {
-      tl.set(el, { scrollTop: desired }, at)
-      return { duration: 0 }
-    }
-    tl.to(el, { scrollTop: desired, duration, ease: opts.ease ?? DEFAULTS.ease }, at)
-    return { duration }
-  }
-
-  const uiSet: ActionsKit['ui']['set'] = (target, change, position) => {
-    const el = resolveTarget(stage, target, 'ui.set')
-    const at = resolvePosition(position, tl.duration())
-    const vars: gsap.TweenVars = {}
-    if (change.text !== undefined) vars.textContent = change.text
-    if (change.value !== undefined) (vars as Record<string, unknown>).value = change.value
-    if (change.src !== undefined) (vars as Record<string, unknown>).src = change.src
-    if (change.attrs) vars.attr = change.attrs
-    if (change.classes) {
-      const current = new Set((el.getAttribute('class') ?? '').split(/\s+/).filter(Boolean))
-      for (const cls of change.classes.add ?? []) current.add(cls)
-      for (const cls of change.classes.remove ?? []) current.delete(cls)
-      ;(vars as Record<string, unknown>).className = Array.from(current).join(' ')
-    }
-    if (Object.keys(vars).length) tl.set(el, vars, at)
-    if (change.flash) {
-      tl.fromTo(
-        el,
-        { filter: 'brightness(1)' },
-        { filter: 'brightness(1.35)', duration: 0.12, repeat: 1, yoyo: true, ease: 'ease-in-out-quad' },
-        at
-      )
-      return { duration: 0.24 }
-    }
-    return { duration: 0 }
-  }
-
-  return { cursor, press, scroll, ui: { set: uiSet } }
-}