@impractical-ai/motion 0.1.5 → 0.1.7

package/assets/kits/kits.ts

@@ -0,0 +1,343 @@
+// Side-effect import: the draft-side working-views engine (Studio reveal
+// verbs on the currently deployed engine). Every kit imports this module,
+// so any kit-using draft carries it. It installs a nonce-gated message
+// listener and stands down when the engine-side bridge takes over.
+import './reveal'
+
+// ─── Shared kit primitives ────────────────────────────────────────────────
+// Cross-kit helpers that were each duplicated inline before. `logo.ts` already
+// imports `prand` from `./text`, so cross-kit imports are house style.
+//
+// Everything here is deterministic: nothing reads a clock, and nothing that
+// runs per frame allocates. The kits that use these still obey the five
+// conventions (factory, every tween through `deps.tl`, return `{duration,…}`,
+// `(target, effect, opts?, position?)`, deterministic only) — plus a sixth
+// that was unwritten until now:
+//
+//   6. Kit DOM appends to `stage`, not `stage.parentElement`. The stage div
+//      carries `key={build.tick}` (src/stage/main.tsx:1279), so it is
+//      destroyed and recreated on every rebuild — anything under it is
+//      auto-cleaned. `transition.ts` self-clears its overlays precisely
+//      because it mounts on the parent to escape the camera transform.
+
+/** Marker for a kit's proxy-tween target.
+ *
+ * It lives on the tween TARGET, never in `vars`, for two reasons: the Tweak
+ * panel enumerates `tween.vars` (engine.ts:1003-1025) and would otherwise show
+ * `kit`/`on` as bogus text controls, while `kindOf` (engine.ts:658-670) reads
+ * `targets[0]` and can classify from here. Without a marker a proxy tween is
+ * classified `'hold'`, which labels it "Hold the frame", HIDES its ease
+ * selector (main.tsx:2792), and files it under the "pause" filter chip. */
+export type KitProxy = {
+  kit: 'filter' | 'mask' | 'axis' | 'three' | 'audio'
+  /** Human label for the element the proxy drives — `labelForTween` uses it. */
+  on: string
+}
+
+/** A short, stable description of an element for proxy-tween labels. Mirrors
+ * what `describeTarget` (engine.ts:635-644) produces for real element tweens,
+ * so the Tweak panel reads consistently across both. */
+export function labelOf(el: Element): string {
+  const data = Array.from((el as HTMLElement).attributes ?? [])
+    .map((a) => a.name)
+    .find((n) => n.startsWith('data-') && n !== 'data-block')
+  if (data) return `[${data}]`
+  if (el.id) return `#${el.id}`
+  const cls = (el.getAttribute('class') ?? '').split(/\s+/).filter(Boolean)[0]
+  return cls ? `.${cls}` : el.tagName.toLowerCase()
+}
+
+/** One `<svg><defs>` host per build, for SVG filters and masks.
+ *
+ * Created LAZILY on first use, not in `buildScene`'s prep zone
+ * (engine.ts:717-741). The prep zone is for things that must exist *before the
+ * direction runs* (fonts, video metadata); a defs host is needed only if a kit
+ * that uses one is actually called. Putting it in the prep zone would make all
+ * 145 scenes pay for a DOM node they never touch and would couple engine.ts to
+ * kit internals. The precedent is `transition.ts`'s lazy `makeRoot()`.
+ *
+ * Ids are per-build sequential, so preview and export of the same scene
+ * produce identical markup. */
+export type DefsHost = {
+  def: (prefix: string, node: SVGElement) => string
+}
+
+export function createDefsHost(stage: HTMLElement): DefsHost {
+  const ns = 'http://www.w3.org/2000/svg'
+  let defs: SVGDefsElement | null = null
+  let n = 0
+  return {
+    def(prefix, node) {
+      if (!defs) {
+        const svg = document.createElementNS(ns, 'svg')
+        svg.setAttribute('data-kit-defs', '')
+        svg.setAttribute('width', '0')
+        svg.setAttribute('height', '0')
+        svg.style.cssText =
+          'position:absolute;width:0;height:0;overflow:hidden;pointer-events:none;'
+        defs = document.createElementNS(ns, 'defs')
+        svg.appendChild(defs)
+        stage.appendChild(svg)
+      }
+      const id = `kit-${prefix}-${n++}`
+      node.setAttribute('id', id)
+      defs.appendChild(node)
+      return id
+    },
+  }
+}
+
+/** Serialize an element's silhouette to a data-URI mask value, from a CLEAN
+ * clone. Lifted from `logo.shine` (logo.ts:601-617), which needs the cleaning
+ * because by the time it runs, reveal effects have written inline styles onto
+ * the live shapes — `draw` zeroes every `stroke-dasharray` and hides fills,
+ * which would serialize into a fully transparent mask, and a transparent mask
+ * hides everything.
+ *
+ * Returns `null` when there is no usable source, so callers can warn and
+ * degrade rather than silently masking an element to nothing. */
+export function silhouetteUrl(source: Element): string | null {
+  if (source instanceof HTMLImageElement) return `url("${source.src}")`
+  const svg =
+    source instanceof SVGSVGElement
+      ? source
+      : (source.querySelector('svg') as SVGSVGElement | null)
+  if (svg) {
+    const clean = svg.cloneNode(true) as SVGSVGElement
+    for (const node of [clean, ...Array.from(clean.querySelectorAll('*'))]) {
+      node.removeAttribute('style')
+      node.removeAttribute('stroke-dasharray')
+      node.removeAttribute('stroke-dashoffset')
+    }
+    const markup = new XMLSerializer().serializeToString(clean)
+    return `url("data:image/svg+xml;utf8,${encodeURIComponent(markup)}")`
+  }
+  const img = source.querySelector('img') as HTMLImageElement | null
+  return img ? `url("${img.src}")` : null
+}
+
+/** Freeze per-unit widths so a property that changes glyph advance can't
+ * reflow the line mid-tween. Third occurrence of this pattern (text.ts:300-306
+ * for scramble, text.ts:528-533 for count), which is why it lives here.
+ *
+ * Matters most for variable-font `wght`: an unlocked weight wave makes the
+ * whole line breathe horizontally as it passes. */
+export function lockWidths(units: HTMLElement[]): void {
+  // Measure every unit BEFORE mutating any of them — setting `display` on unit
+  // i changes layout for unit i+1, so an interleaved read/write loop records
+  // widths that are already wrong.
+  const widths = units.map((u) => u.offsetWidth)
+  units.forEach((u, i) => {
+    u.style.width = `${widths[i]}px`
+    u.style.display = 'inline-block'
+    u.style.textAlign = 'center'
+  })
+}
+
+/** Give an element's beat its own stacking context so a blend mode composites
+ * against that beat and not the whole frame.
+ *
+ * `mix-blend-mode` composites against the nearest stacking context. Assembled
+ * videos hide sections with `autoAlpha: 0` (studio/blocks.ts:1888) and
+ * `opacity < 1` creates one — so a blend inside a HIDDEN block is already
+ * contained. But a VISIBLE block at opacity 1 (`absolute inset-0`, no
+ * z-index) does not create one, so its blend would reach past its own beat and
+ * composite against whatever sits underneath. One line fixes it, and without
+ * it blends are subtly wrong in exactly the assembled-video case the product
+ * generates most. */
+export function isolateBlock(el: Element, stage: HTMLElement): void {
+  const host = (el.closest('[data-block]') as HTMLElement | null) ?? stage
+  host.style.isolation = 'isolate'
+}
+
+/** Composes a multi-slot CSS property (`filter`, `mask-image`) so two kits, or
+ * two effects from one kit, can drive the same element without clobbering each
+ * other's style string.
+ *
+ * Whatever the element already carried is captured once as the base and always
+ * emitted first, so an authored `filter: drop-shadow(...)` survives a later
+ * `fx.apply(el, 'blur')`. */
+export type CssChain = {
+  /** Register `value` under `slot` and rewrite the property. Idempotent. */
+  add: (el: HTMLElement, slot: string, value: string) => void
+  /** Drop a slot and rewrite. */
+  remove: (el: HTMLElement, slot: string) => void
+  /** Is this slot already registered on this element? */
+  has: (el: HTMLElement, slot: string) => boolean
+}
+
+export function cssChain(prop: 'filter' | 'maskImage'): CssChain {
+  const slots = new WeakMap<HTMLElement, Map<string, string>>()
+  const bases = new WeakMap<HTMLElement, string>()
+  const joiner = prop === 'filter' ? ' ' : ', '
+
+  const write = (el: HTMLElement) => {
+    const map = slots.get(el)
+    const base = bases.get(el) ?? ''
+    const parts = [base, ...(map ? Array.from(map.values()) : [])].filter(Boolean)
+    const value = parts.join(joiner)
+    if (prop === 'filter') {
+      el.style.filter = value
+    } else {
+      el.style.setProperty('mask-image', value)
+      el.style.setProperty('-webkit-mask-image', value)
+    }
+  }
+
+  return {
+    add(el, slot, value) {
+      if (!bases.has(el)) {
+        const authored =
+          prop === 'filter'
+            ? el.style.filter
+            : el.style.getPropertyValue('mask-image')
+        bases.set(el, authored && authored !== 'none' ? authored : '')
+      }
+      let map = slots.get(el)
+      if (!map) {
+        map = new Map()
+        slots.set(el, map)
+      }
+      map.set(slot, value)
+      write(el)
+    },
+    remove(el, slot) {
+      slots.get(el)?.delete(slot)
+      write(el)
+    },
+    has(el, slot) {
+      return slots.get(el)?.has(slot) ?? false
+    },
+  }
+}
+
+/** Resolve a `string | Element` target against the stage, throwing the same
+ * shape of error `ctx.q` does (engine.ts:835-839) so a bad selector fails
+ * loudly at build time rather than silently animating nothing. */
+export function resolveTarget(
+  stage: HTMLElement,
+  target: string | Element,
+  kind: string
+): HTMLElement {
+  const el =
+    typeof target === 'string' ? stage.querySelector(target) : (target as Element)
+  if (!el) throw new Error(`${kind} target not found: ${String(target)}`)
+  return el as HTMLElement
+}
+
+/** Resolve to many elements — the group form. Empty is an error for the same
+ * reason: an effect that animates nothing is a silent authoring bug. */
+export function resolveTargets(
+  stage: HTMLElement,
+  target: string | Element | Element[],
+  kind: string
+): HTMLElement[] {
+  if (Array.isArray(target)) return target as HTMLElement[]
+  if (typeof target !== 'string') return [target as HTMLElement]
+  const found = Array.from(stage.querySelectorAll(target)) as HTMLElement[]
+  if (!found.length) throw new Error(`${kind} target not found: ${target}`)
+  return found
+}
+
+/** Element rect in AUTHORED-LAYOUT scene coords.
+ *
+ * gsap `from()` renders its from-state at BUILD time, so a live rect measured
+ * while a direction is being authored is displaced by whatever entrance tweens
+ * are mid-flight. Kits that place overlays or compute travel (actions,
+ * highlight, looks) want the RESTING layout, so this measures with every
+ * transform from the element up to and including the camera-carrying stage
+ * temporarily neutralized, then restores them. Scaling OUTSIDE the stage (the
+ * studio player fitting the composition to the window) divides out via the
+ * stage's own ratio. */
+export function layoutRect(
+  stage: HTMLElement,
+  el: HTMLElement
+): { left: number; top: number; width: number; height: number } {
+  return withNeutralizedTransforms(stage, el, (measure) => measure(el.getBoundingClientRect()))
+}
+
+/** Element rect in stage-local coords WITH authored transforms applied — where
+ * the element actually sits RIGHT NOW, with only the stage's own transform
+ * (camera + studio player fit) divided out. `layoutRect` answers "where does
+ * this element rest in the authored layout"; `visualRect` answers "where is it
+ * at this moment". Anything that AIMS at an element from stage space (cursor
+ * hotspots, rings, flights) wants visualRect resolved at action time — a
+ * container the direction has scaled mid-timeline moves its children away from
+ * their resting rects, and an aim taken from layoutRect lands beside the UI. */
+export function visualRect(
+  stage: HTMLElement,
+  el: HTMLElement
+): { left: number; top: number; width: number; height: number } {
+  const stageRect = stage.getBoundingClientRect()
+  const k = stage.offsetWidth ? stageRect.width / stage.offsetWidth : 1
+  const r = el.getBoundingClientRect()
+  return {
+    left: (r.left - stageRect.left) / k,
+    top: (r.top - stageRect.top) / k,
+    width: r.width / k,
+    height: r.height / k,
+  }
+}
+
+/** The TEXT rect of an element in authored-layout scene coords.
+ *
+ * A block element's box spans its full column even when its glyphs don't —
+ * the same tension `textRect` solves for camera framing. Annotations that
+ * decorate text (marker swipes, hand-drawn circles, underlines) must fit the
+ * GLYPHS, or a highlight on "99.99%" swallows half a card of empty space.
+ * Falls back to the element box when there is no text content. */
+export function layoutTextRect(
+  stage: HTMLElement,
+  el: HTMLElement
+): { left: number; top: number; width: number; height: number } {
+  return withNeutralizedTransforms(stage, el, (measure) => {
+    const range = document.createRange()
+    range.selectNodeContents(el)
+    const r = range.getBoundingClientRect()
+    return r.width > 0 && r.height > 0 ? measure(r) : measure(el.getBoundingClientRect())
+  })
+}
+
+function withNeutralizedTransforms(
+  stage: HTMLElement,
+  el: HTMLElement,
+  read: (
+    measure: (r: DOMRect) => { left: number; top: number; width: number; height: number }
+  ) => { left: number; top: number; width: number; height: number }
+): { left: number; top: number; width: number; height: number } {
+  const touched: Array<{ node: HTMLElement; transform: string }> = []
+  let node: HTMLElement | null = el
+  while (node) {
+    if (node.style.transform) {
+      touched.push({ node, transform: node.style.transform })
+      node.style.transform = 'none'
+    }
+    if (node === stage) break
+    node = node.parentElement
+  }
+  const stageRect = stage.getBoundingClientRect()
+  const k = stage.offsetWidth ? stageRect.width / stage.offsetWidth : 1
+  const result = read((r) => ({
+    left: (r.left - stageRect.left) / k,
+    top: (r.top - stageRect.top) / k,
+    width: r.width / k,
+    height: r.height / k,
+  }))
+  for (const { node: touchedNode, transform } of touched) {
+    touchedNode.style.transform = transform
+  }
+  return result
+}
+
+/** Warn once per (scope, key). Mirrors `logo.ts`'s `warned` Set: kits degrade
+ * with a console warning rather than throwing, because templates and the AI
+ * director can regenerate markup out from under a direction and a hard throw
+ * turns "renders flat" into "renders not at all". */
+export function createWarner(scope: string) {
+  const seen = new Set<string>()
+  return (key: string, message: string) => {
+    if (seen.has(key)) return
+    seen.add(key)
+    console.warn(`[${scope}] ${message}`)
+  }
+}