zumly 0.18.1 → 0.92.0

package/docs/DRIVER_API.md

@@ -0,0 +1,340 @@
+# Writing a Zumly Transition Driver
+
+**Zumly** (*Z over XY* — focus-driven navigation, zoom into what matters) delegates animation to **transition drivers**. A driver controls **how** views move during zoom-in, zoom-out, and lateral navigation. The engine computes **what** moves where (transforms, origins, snapshot); the driver applies motion — CSS keyframes, WAAPI, GSAP, Motion, Anime.js, or a custom timeline.
+
+**See also:** [README.md](../README.md) (options, built-in drivers, plugins) · [geometry-optimization.md](geometry-optimization.md) (how zoom-out layout reads are batched before the driver runs).
+
+## Quick start
+
+A driver is an object with a single method:
+
+```js
+const myDriver = {
+  runTransition(spec, onComplete) {
+    // Animate views from spec.currentStage backward → forward states
+    // Call onComplete() when done — this is mandatory.
+  }
+}
+```
+
+Register it in the constructor:
+
+```js
+new Zumly({
+  mount: '.canvas',
+  initialView: 'home',
+  views: { home, detail },
+  transitions: {
+    driver: myDriver.runTransition, // pass the function directly
+    duration: '600ms',
+    ease: 'ease-in-out',
+  },
+})
+```
+
+Or as a factory function:
+
+```js
+transitions: {
+  driver: (spec, onComplete) => myDriver.runTransition(spec, onComplete),
+}
+```
+
+---
+
+## The `spec` object
+
+Your `runTransition(spec, onComplete)` receives a spec with everything needed:
+
+### Common fields (all transition types)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'zoomIn' \| 'zoomOut' \| 'lateral'` | What kind of transition |
+| `currentView` | `HTMLElement` | The incoming view (zoom-in) or outgoing view (zoom-out) |
+| `previousView` | `HTMLElement` | The parent view |
+| `lastView` | `HTMLElement \| null` | Grandparent view (null at depth ≤ 2) |
+| `currentStage` | `object` | Snapshot with computed states (see below) |
+| `duration` | `string` | e.g. `'500ms'`, `'1s'` |
+| `ease` | `string` | CSS easing, e.g. `'ease-in-out'` |
+| `canvas` | `HTMLElement` | The canvas container (zoom-out and lateral only) |
+
+### `currentStage.views[]` — The animation data
+
+An array of view entries, indexed by role:
+
+```
+views[0] → current view  (the one zooming in/out)
+views[1] → previous view (the parent)
+views[2] → last view     (grandparent, when depth > 2)
+```
+
+Each entry has:
+
+```js
+{
+  viewName: 'detail',
+  backwardState: {
+    origin: '125px 100px',    // CSS transform-origin
+    transform: 'translate(50px, 60px) scale(0.25)',  // "start" for zoom-in, "end" for zoom-out
+    duration: '500ms',
+    ease: 'ease-in-out',
+  },
+  forwardState: {
+    origin: '125px 100px',
+    transform: 'translate(100px, 50px)',  // "end" for zoom-in, "start" for zoom-out
+    duration: '500ms',
+    ease: 'ease-in-out',
+  }
+}
+```
+
+**For zoom-in:** animate from `backwardState.transform` → `forwardState.transform`.
+**For zoom-out:** animate from `forwardState.transform` → `backwardState.transform`.
+
+### Lateral-specific fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `backView` | `HTMLElement \| null` | The parent view behind current depth |
+| `backViewState` | `{ transformStart, transformEnd }` | Slide transforms for backView |
+| `lastViewState` | `{ transformStart, transformEnd }` | Slide transforms for lastView |
+| `incomingTransformStart` | `string` | Incoming view start transform |
+| `incomingTransformEnd` | `string` | Incoming view final transform |
+| `outgoingTransform` | `string` | Outgoing view current transform |
+| `outgoingTransformEnd` | `string` | Outgoing view exit transform |
+| `slideDeltaX` | `number` | Horizontal slide distance |
+| `slideDeltaY` | `number` | Vertical slide distance |
+
+---
+
+## What your driver MUST do
+
+### 1. Call `onComplete()` — always, exactly once
+
+This is the #1 rule. The engine sets `blockEvents = true` before calling your driver and only resets it in `onComplete`. If you never call it, the UI freezes permanently.
+
+Use the `createFinishGuard` helper to guarantee this:
+
+```js
+import { createFinishGuard, SAFETY_BUFFER_MS, parseDurationMs } from 'zumly/driver-helpers'
+
+function runTransition(spec, onComplete) {
+  const durationMs = parseDurationMs(spec.duration)
+
+  const { finish } = createFinishGuard(() => {
+    // cleanup work here...
+    onComplete()
+  }, durationMs + SAFETY_BUFFER_MS)
+
+  // Your animation...
+  myAnimation.onfinish = finish
+  // If the animation fails/gets cancelled, the safety timer calls finish() anyway.
+}
+```
+
+*(In this repo, you can import from `../src/drivers/driver-helpers.js` from your own source files.)*
+
+### 2. Apply final DOM state after animation
+
+When the animation ends, the DOM must reflect the final state — the engine does NOT do this for you. Use the shared helpers:
+
+```js
+import {
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  showViews
+} from 'zumly/driver-helpers'
+
+// Before animating — make views visible:
+showViews(spec.currentView, spec.previousView, spec.lastView)
+
+// After zoom-in animation completes:
+applyZoomInEndState(currentView, currentStage)
+applyZoomInEndState(previousView, currentStage)
+if (lastView) applyZoomInEndState(lastView, currentStage)
+
+// After zoom-out animation completes:
+removeViewFromCanvas(currentView, canvas)
+applyZoomOutPreviousState(previousView, currentStage.views[1].backwardState)
+if (lastView) applyZoomOutLastState(lastView, currentStage.views[2].backwardState)
+```
+
+### 3. Handle all three types
+
+Your driver receives `spec.type` which is one of:
+- `'zoomIn'` — drill deeper
+- `'zoomOut'` — go back
+- `'lateral'` — same-level swap
+
+For lateral, the built-in **`waapi`** driver runs a **slide animation**. If you author a minimal custom driver and want **no** lateral motion, call the instant helper:
+
+```js
+import { runLateralInstant } from 'zumly/driver-helpers'
+
+if (spec.type === 'lateral') {
+  runLateralInstant(spec, onComplete)
+  return
+}
+```
+
+---
+
+## Available helpers
+
+Import from `zumly/driver-helpers` (published) or `src/drivers/driver-helpers.js` (monorepo):
+
+| Helper | Purpose |
+|--------|---------|
+| `parseDurationMs(duration)` | Parse `'1s'`/`'500ms'`/number → ms |
+| `parseDurationSec(duration)` | Same but returns seconds |
+| `applyZoomInEndState(el, stage)` | Apply final classes + transforms after zoom-in |
+| `applyZoomOutPreviousState(el, state)` | Final state for previous view after zoom-out |
+| `applyZoomOutLastState(el, state)` | Final state for last view after zoom-out |
+| `removeViewFromCanvas(el, canvas)` | Safe removal (handles wrapped elements) |
+| `showViews(...elements)` | Remove `hide` class + set `contentVisibility: auto` |
+| `runLateralInstant(spec, onComplete)` | Instant lateral transition (no animation) |
+| `createFinishGuard(cleanup, timeoutMs)` | Once-only finish + safety timeout |
+| `SAFETY_BUFFER_MS` | Default safety buffer (150ms) |
+
+### Matrix interpolation toolkit
+
+For drivers that need to interpolate through computed CSS matrices (e.g. when transform-origin varies between states):
+
+| Helper | Purpose |
+|--------|---------|
+| `readComputedMatrix(el, origin, transform)` | Read browser-computed matrix (⚠️ forces reflow) |
+| `interpolateMatrix(from, to, t)` | Lerp between two matrix objects |
+| `matrixToString(m)` | `{ a,b,c,d,e,f }` → `"matrix(...)"` |
+| `parseMatrixString(str)` | `"matrix(...)"` → `{ a,b,c,d,e,f }` |
+| `identityMatrix()` | Returns `{ a:1, b:0, c:0, d:1, e:0, f:0 }` |
+| `lerp(a, b, t)` | Linear interpolation |
+
+---
+
+## Example: minimal custom driver
+
+A complete, minimal driver that does a simple opacity crossfade instead of zoom:
+
+```js
+import {
+  parseDurationMs,
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  runLateralInstant,
+  createFinishGuard,
+  SAFETY_BUFFER_MS,
+} from 'zumly/driver-helpers'
+
+export function runTransition(spec, onComplete) {
+  const { type, currentView, previousView, lastView, currentStage, duration, canvas } = spec
+
+  if (type === 'lateral') {
+    runLateralInstant(spec, onComplete)
+    return
+  }
+
+  const ms = parseDurationMs(duration)
+  showViews(currentView, previousView, lastView)
+
+  if (type === 'zoomIn') {
+    // Simple crossfade: incoming fades in, outgoing fades out
+    currentView.style.opacity = '0'
+    currentView.style.transition = `opacity ${ms}ms ease`
+    previousView.style.transition = `opacity ${ms}ms ease`
+
+    requestAnimationFrame(() => {
+      currentView.style.opacity = '1'
+      previousView.style.opacity = '0.3'
+    })
+
+    const { finish } = createFinishGuard(() => {
+      currentView.style.transition = ''
+      previousView.style.transition = ''
+      previousView.style.opacity = ''
+      applyZoomInEndState(currentView, currentStage)
+      applyZoomInEndState(previousView, currentStage)
+      if (lastView) applyZoomInEndState(lastView, currentStage)
+      onComplete()
+    }, ms + SAFETY_BUFFER_MS)
+
+    currentView.addEventListener('transitionend', finish, { once: true })
+    return
+  }
+
+  if (type === 'zoomOut') {
+    currentView.style.transition = `opacity ${ms}ms ease`
+    requestAnimationFrame(() => {
+      currentView.style.opacity = '0'
+      previousView.style.opacity = '1'
+    })
+
+    const { finish } = createFinishGuard(() => {
+      currentView.style.transition = ''
+      removeViewFromCanvas(currentView, canvas)
+      applyZoomOutPreviousState(previousView, currentStage.views[1].backwardState)
+      if (lastView) applyZoomOutLastState(lastView, currentStage.views[2].backwardState)
+      onComplete()
+    }, ms + SAFETY_BUFFER_MS)
+
+    currentView.addEventListener('transitionend', finish, { once: true })
+    return
+  }
+
+  onComplete()
+}
+```
+
+---
+
+## Testing your driver
+
+Use `driver: 'none'` as a reference — it applies final state instantly and calls `onComplete()` synchronously. Your driver should produce the same final DOM state, just animated.
+
+Key things to test:
+1. After zoom-in: `.is-current-view` exists with correct `dataset.viewName`
+2. After zoom-out: previous view is now `.is-current-view`, old current is removed from DOM
+3. `onComplete()` is always called, even if elements are removed mid-animation
+4. `blockEvents` is reset (the engine handles this in `onComplete`, but verify your driver calls it)
+
+```js
+const app = new Zumly({
+  mount: '.canvas',
+  initialView: 'home',
+  views: { home, detail },
+  transitions: { driver: myDriver, duration: '100ms' },
+})
+await app.init()
+await app.zoomTo('detail')
+expect(app.getCurrentViewName()).toBe('detail')
+app.back()
+expect(app.getCurrentViewName()).toBe('home')
+```
+
+---
+
+## Registering with `getDriver()`
+
+Built-in drivers are resolved by name (`'css'`, `'waapi'`, `'none'`, etc.) in [`src/drivers/index.js`](../src/drivers/index.js). Community drivers are passed as functions — no registration needed:
+
+```js
+// Direct function — works out of the box:
+transitions: { driver: myDriver.runTransition }
+
+// If you want to publish as a package:
+// npm: zumly-driver-lottie
+import { runTransition } from 'zumly-driver-lottie'
+new Zumly({ transitions: { driver: runTransition } })
+```
+
+---
+
+## See also
+
+- [README.md](../README.md) — installation and transition driver table
+- [roadMap.md](roadMap.md) — architecture notes and animation driver history

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zumly",
-  "version": "0.18.1",
+  "version": "0.92.0",
   "description": "Javascript library for building zooming user interfaces",
   "type": "module",
   "author": "Juan Martin Muda - Zumerlab",
@@ -22,10 +22,32 @@
     "ZUI"
   ],
   "main": "dist/zumly.js",
+  "module": "dist/zumly.mjs",
+  "types": "types/zumly.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/zumly.d.ts",
+      "import": "./dist/zumly.mjs",
+      "require": "./dist/zumly.js",
+      "default": "./dist/zumly.mjs"
+    },
+    "./style.css": "./dist/zumly.css",
+    "./css": "./dist/zumly.css",
+    "./drivers": {
+      "import": "./src/drivers/index.js"
+    },
+    "./driver-helpers": {
+      "import": "./src/drivers/driver-helpers.js"
+    }
+  },
+  "sideEffects": [
+    "dist/zumly.css",
+    "dist/zumly.min.css"
+  ],
   "scripts": {
     "compile": "node esbuild.config.mjs",
     "build": "npm run compile && npm pack",
-    "dev": "npm run compile && npx serve public -p 9090",
+    "dev": "npm run compile && npx serve . -p 9090 -c ./serve.json",
     "test": "npx vitest run --browser.headless --reporter=verbose",
     "test:unit": "npx vitest run __tests__/utils.test.js --reporter=verbose",
     "test:coverage": "npx vitest run --browser.headless --coverage",
@@ -35,6 +57,9 @@
   },
   "files": [
     "dist",
+    "src/drivers/driver-helpers.js",
+    "src/drivers/index.js",
+    "docs/DRIVER_API.md",
     "README.md"
   ],
   "devDependencies": {

package/src/drivers/driver-helpers.js

@@ -0,0 +1,315 @@
+import { showViewContent } from '../view-visibility.js'
+
+/**
+ * Shared helpers for Zumly transition drivers.
+ *
+ * These utilities handle the repetitive DOM work that every driver needs:
+ * applying final states, removing views, parsing durations, and running
+ * lateral (same-level) transitions. Import what you need; skip what you don't.
+ *
+ * @module driver-helpers
+ * @see ../../docs/DRIVER_API.md for the full driver authoring guide
+ */
+
+// ─── Duration parsing ────────────────────────────────────────────────
+
+/**
+ * Parse a CSS-style duration string to milliseconds.
+ * Accepts "1s", "500ms", "0.3s", or a raw number (treated as ms).
+ * Returns a safe fallback (500ms) for garbage input.
+ *
+ * @param {string|number} duration
+ * @returns {number} Duration in milliseconds (≥ 0)
+ *
+ * @example
+ *   parseDurationMs('1s')    // → 1000
+ *   parseDurationMs('200ms') // → 200
+ *   parseDurationMs(300)     // → 300
+ *   parseDurationMs('nope')  // → 500
+ */
+export function parseDurationMs (duration) {
+  if (typeof duration === 'number' && !Number.isNaN(duration)) return Math.max(0, duration)
+  const str = String(duration)
+  const m = str.match(/^(\d+(?:\.\d+)?)\s*(ms|s)?$/i)
+  if (!m) return 500
+  const val = parseFloat(m[1])
+  const unit = (m[2] || 's').toLowerCase()
+  return unit === 'ms' ? Math.max(0, val) : Math.max(0, val * 1000)
+}
+
+/**
+ * Parse duration to seconds (convenience for libs like GSAP that use seconds).
+ *
+ * @param {string|number} duration
+ * @returns {number} Duration in seconds (≥ 0)
+ */
+export function parseDurationSec (duration) {
+  return parseDurationMs(duration) / 1000
+}
+
+// ─── End-state application ───────────────────────────────────────────
+
+/**
+ * Apply the final zoom-in state to an element based on its current class.
+ * This is the DOM cleanup that runs after the animation finishes.
+ *
+ * What it does for each role:
+ * - `is-new-current-view` → becomes `is-current-view`, no-events removed, final transform applied
+ * - `is-previous-view` → no-events removed, final transform applied
+ * - `is-last-view` → no-events removed, final transform applied
+ *
+ * @param {HTMLElement} element - The view element
+ * @param {object} currentStage - The snapshot with `views[]` array
+ */
+export function applyZoomInEndState (element, currentStage) {
+  if (element.classList.contains('is-new-current-view')) {
+    const v = currentStage.views[0].forwardState
+    element.classList.replace('is-new-current-view', 'is-current-view')
+    element.classList.remove('zoom-current-view', 'has-no-events')
+    element.style.transformOrigin = v.origin
+    element.style.transform = v.transform
+    return
+  }
+  if (element.classList.contains('is-previous-view')) {
+    const v = currentStage.views[1].forwardState
+    element.classList.remove('zoom-previous-view', 'has-no-events')
+    element.style.transformOrigin = v.origin
+    element.style.transform = v.transform
+    return
+  }
+  if (element.classList.contains('is-last-view')) {
+    const v = currentStage.views[2].forwardState
+    element.classList.remove('zoom-last-view', 'has-no-events')
+    element.style.transformOrigin = v.origin
+    element.style.transform = v.transform
+  }
+}
+
+/**
+ * Apply the final zoom-out state to the previous view (it becomes current).
+ *
+ * @param {HTMLElement} element
+ * @param {{ origin?: string, transform: string }} backwardState
+ */
+export function applyZoomOutPreviousState (element, backwardState) {
+  element.classList.remove('zoom-previous-view-reverse', 'has-no-events', 'has-effect', 'has-effect-reverse')
+  element.style.removeProperty('--z-effect-filter')
+  element.style.transformOrigin = '0 0'
+  element.style.transform = backwardState.transform
+}
+
+/**
+ * Apply the final zoom-out state to the last view (it becomes previous).
+ *
+ * @param {HTMLElement} element
+ * @param {{ origin: string, transform: string }} backwardState
+ */
+export function applyZoomOutLastState (element, backwardState) {
+  element.classList.remove('zoom-last-view-reverse', 'has-no-events', 'has-effect', 'has-effect-reverse')
+  element.style.removeProperty('--z-effect-filter')
+  element.style.transformOrigin = backwardState.origin
+  element.style.transform = backwardState.transform
+}
+
+// ─── DOM removal ─────────────────────────────────────────────────────
+
+/**
+ * Safely remove a view from the canvas. Handles wrapped elements (e.g. Svelte
+ * components that get an extra parent div).
+ *
+ * @param {HTMLElement} element - The view to remove
+ * @param {HTMLElement} canvas - The canvas container
+ */
+export function removeViewFromCanvas (element, canvas) {
+  try {
+    if (canvas) canvas.removeChild(element)
+  } catch (e) {
+    try {
+      if (element.parentElement) canvas.removeChild(element.parentElement)
+    } catch (e2) {
+      // Element already removed or re-parented — safe to ignore.
+    }
+  }
+}
+
+// ─── Visibility helpers ──────────────────────────────────────────────
+
+/**
+ * Make a view visible and interactive before animating it.
+ * Views start hidden (class `hide` for opacity, `contentVisibility: hidden` via view-visibility)
+ * when inserted by prepareAndInsertView. Drivers must call this before running any animation.
+ *
+ * @param  {...HTMLElement} elements - One or more view elements (nulls are skipped)
+ */
+export function showViews (...elements) {
+  for (const el of elements) {
+    if (!el) continue
+    el.classList.remove('hide')
+    showViewContent(el)
+  }
+}
+
+// ─── Lateral (same-level) transition ─────────────────────────────────
+
+/**
+ * Instant lateral navigation: swap current view without animation.
+ * This is the shared implementation that drivers use as a baseline.
+ * Drivers that want animated lateral transitions can override this.
+ *
+ * @param {object} spec - Full lateral spec from the engine
+ * @param {function} onComplete - Must be called when done
+ */
+export function runLateralInstant (spec, onComplete) {
+  const {
+    currentView: incomingView,
+    previousView: outgoingView,
+    backView,
+    backViewState,
+    lastView,
+    lastViewState,
+    incomingTransformEnd,
+    currentStage,
+    canvas
+  } = spec
+  const v0 = currentStage.views[0]
+
+  showViews(incomingView)
+  incomingView.classList.replace('is-new-current-view', 'is-current-view')
+  incomingView.classList.remove('zoom-current-view', 'has-no-events')
+  incomingView.style.transformOrigin = v0.forwardState.origin
+  incomingView.style.transform = incomingTransformEnd || v0.forwardState.transform
+
+  if (backView && backViewState) backView.style.transform = backViewState.transformEnd
+  if (lastView && lastViewState) lastView.style.transform = lastViewState.transformEnd
+
+  if (!spec.keepAlive) removeViewFromCanvas(outgoingView, canvas)
+  onComplete()
+}
+
+// ─── Safety timeout ──────────────────────────────────────────────────
+
+/**
+ * Default safety buffer (ms) beyond the parsed duration. Ensures onComplete
+ * fires even if animationend / Promise.all never settles (element removed,
+ * duration 0, browser quirk, etc.).
+ */
+export const SAFETY_BUFFER_MS = 150
+
+/**
+ * Create a finish-once guard: returns a `finish()` function that only runs
+ * the first time it's called, and clears the safety timer.
+ *
+ * Use this to avoid the "completed" flag boilerplate in every driver.
+ *
+ * @param {function} cleanup - The actual cleanup + onComplete work
+ * @param {number} timeoutMs - Safety timeout duration
+ * @returns {{ finish: function, safetyTimer: number }}
+ *
+ * @example
+ *   const { finish, safetyTimer } = createFinishGuard(() => {
+ *     cancelAnimations()
+ *     applyFinalState()
+ *     onComplete()
+ *   }, durationMs + SAFETY_BUFFER_MS)
+ *
+ *   // In your animation's onComplete:
+ *   animation.onfinish = finish
+ *
+ *   // The safetyTimer ensures finish() runs even if onfinish never fires.
+ */
+export function createFinishGuard (cleanup, timeoutMs) {
+  let completed = false
+  const safetyTimer = setTimeout(() => {
+    if (!completed) { completed = true; cleanup() }
+  }, timeoutMs)
+
+  return {
+    finish () {
+      if (completed) return
+      completed = true
+      clearTimeout(safetyTimer)
+      cleanup()
+    },
+    safetyTimer
+  }
+}
+
+// ─── Matrix interpolation toolkit ────────────────────────────────────
+// Used by matrix-based drivers (anime, motion, or any custom driver that
+// needs to interpolate transforms through computed matrices).
+
+/** Identity CSS matrix components. */
+export function identityMatrix () {
+  return { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 }
+}
+
+/**
+ * Parse a CSS matrix() string into components.
+ * @param {string} mStr - e.g. "matrix(1, 0, 0, 1, 100, 50)"
+ * @returns {{ a, b, c, d, e, f }}
+ */
+export function parseMatrixString (mStr) {
+  if (!mStr || mStr === 'none') return identityMatrix()
+  const m = String(mStr).match(
+    /matrix\(([-\d.eE]+),\s*([-\d.eE]+),\s*([-\d.eE]+),\s*([-\d.eE]+),\s*([-\d.eE]+),\s*([-\d.eE]+)\)/
+  )
+  if (!m) return identityMatrix()
+  return {
+    a: parseFloat(m[1]) || 1,
+    b: parseFloat(m[2]) || 0,
+    c: parseFloat(m[3]) || 0,
+    d: parseFloat(m[4]) || 1,
+    e: parseFloat(m[5]) || 0,
+    f: parseFloat(m[6]) || 0,
+  }
+}
+
+/**
+ * Convert matrix components back to a CSS matrix() string.
+ * @param {{ a, b, c, d, e, f }} m
+ * @returns {string}
+ */
+export function matrixToString (m) {
+  return `matrix(${m.a}, ${m.b}, ${m.c}, ${m.d}, ${m.e}, ${m.f})`
+}
+
+/** Linear interpolation between two numbers. */
+export function lerp (a, b, t) {
+  return a + (b - a) * t
+}
+
+/**
+ * Interpolate between two matrix objects.
+ * @param {{ a,b,c,d,e,f }} from
+ * @param {{ a,b,c,d,e,f }} to
+ * @param {number} t - Progress 0..1
+ * @returns {{ a,b,c,d,e,f }}
+ */
+export function interpolateMatrix (from, to, t) {
+  const tt = Math.max(0, Math.min(1, t))
+  return {
+    a: lerp(from.a, to.a, tt),
+    b: lerp(from.b, to.b, tt),
+    c: lerp(from.c, to.c, tt),
+    d: lerp(from.d, to.d, tt),
+    e: lerp(from.e, to.e, tt),
+    f: lerp(from.f, to.f, tt),
+  }
+}
+
+/**
+ * Read the browser-computed matrix for a given transform + origin pair.
+ * ⚠️  Forces a reflow (getBoundingClientRect). Use sparingly — once per
+ * element per animation setup, not per frame.
+ *
+ * @param {HTMLElement} element
+ * @param {string} origin - CSS transform-origin
+ * @param {string} transformStr - CSS transform value
+ * @returns {{ a,b,c,d,e,f }}
+ */
+export function readComputedMatrix (element, origin, transformStr) {
+  element.style.transformOrigin = origin
+  element.style.transform = transformStr
+  try { element.getBoundingClientRect() } catch {}
+  return parseMatrixString(getComputedStyle(element).transform)
+}