zumly 0.92.3 → 0.92.5

package/src/drivers/css-transition.js

@@ -0,0 +1,261 @@
+/**
+ * CSS-based transition driver (default).
+ * Uses CSS variables and keyframe classes; completes via animationend.
+ * Includes safety timeout so onComplete runs even if animationend is missed.
+ *
+ * @param {Object} spec - Transition spec from the engine
+ * @param {function} onComplete - MUST be called exactly once when done
+ */
+import {
+  parseDurationMs,
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  createFinishGuard,
+  SAFETY_BUFFER_MS,
+} from './driver-helpers.js'
+
+export function runTransition (spec, onComplete) {
+  const { type, currentView, previousView, lastView, currentStage, duration, ease, canvas } = spec
+
+  if (!currentView || !previousView || !currentStage) {
+    onComplete()
+    return
+  }
+
+  if (type === 'lateral') {
+    runLateral(spec, onComplete)
+  } else if (type === 'zoomIn') {
+    runZoomIn(currentView, previousView, lastView, currentStage, duration, ease, onComplete)
+  } else if (type === 'zoomOut') {
+    runZoomOut(currentView, previousView, lastView, currentStage, duration, ease, canvas, onComplete)
+  } else {
+    onComplete()
+  }
+}
+
+// ─── Lateral ─────────────────────────────────────────────────────────
+
+function runLateral (spec, onComplete) {
+  const {
+    currentView: incomingView,
+    previousView: outgoingView,
+    backView,
+    backViewState,
+    lastView,
+    lastViewState,
+    incomingTransformStart,
+    incomingTransformEnd,
+    outgoingTransform,
+    outgoingTransformEnd,
+    currentStage,
+    duration,
+    ease,
+    canvas,
+  } = spec
+  const durationMs = parseDurationMs(duration)
+  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
+
+  // Set CSS variables and animation classes for each participating element
+  if (backView && backViewState) {
+    setCSSVars(backView, duration, ease, { '--lateral-from': backViewState.transformStart, '--lateral-to': backViewState.transformEnd })
+    backView.classList.add('zoom-lateral-back')
+  }
+  if (lastView && lastViewState) {
+    setCSSVars(lastView, duration, ease, { '--lateral-from': lastViewState.transformStart, '--lateral-to': lastViewState.transformEnd })
+    lastView.classList.add('zoom-lateral-back')
+  }
+
+  // Skip outgoing animation in 'visible' keepAlive mode
+  if (spec.keepAlive !== 'visible') {
+    setCSSVars(outgoingView, duration, ease, { '--lateral-out-from': outgoingTransform, '--lateral-out-to': outgoingTransformEnd })
+    outgoingView.classList.add('zoom-lateral-out')
+  }
+
+  setCSSVars(incomingView, duration, ease, { '--lateral-in-from': incomingTransformStart, '--lateral-in-to': incomingTransformEnd })
+  incomingView.classList.add('zoom-lateral-in')
+
+  // Collect all animated elements
+  const elements = spec.keepAlive === 'visible' ? [incomingView] : [outgoingView, incomingView]
+  if (backView && backViewState) elements.push(backView)
+  if (lastView && lastViewState) elements.push(lastView)
+
+  let pending = elements.length
+  const { finish } = createFinishGuard(() => {
+    cleanupListeners(elements, handleEnd)
+    if (spec.keepAlive) {
+      outgoingView.classList.remove('zoom-lateral-out')
+      outgoingView.style.opacity = ''
+    } else {
+      removeViewFromCanvas(outgoingView, canvas)
+    }
+    if (backView) {
+      backView.classList.remove('zoom-lateral-back')
+      backView.style.transform = backViewState?.transformEnd || backView.style.transform
+    }
+    if (lastView) {
+      lastView.classList.remove('zoom-lateral-back')
+      lastView.style.transform = lastViewState?.transformEnd || lastView.style.transform
+    }
+    incomingView.classList.remove('zoom-lateral-in')
+    incomingView.style.transform = incomingTransformEnd
+    onComplete()
+  }, durationMs + SAFETY_BUFFER_MS)
+
+  function handleEnd (event) {
+    const el = event?.target
+    if (el) el.removeEventListener('animationend', handleEnd)
+    pending--
+    if (pending <= 0) finish()
+  }
+
+  elements.forEach(el => el.addEventListener('animationend', handleEnd))
+}
+
+// ─── Zoom In ─────────────────────────────────────────────────────────
+
+function runZoomIn (currentView, previousView, lastView, currentStage, duration, ease, onComplete) {
+  showViews(currentView, previousView, lastView)
+
+  const stagger = currentStage.stagger || 0
+
+  // Set CSS variables for keyframe animations
+  setCSSVars(currentView, duration, ease, {
+    '--current-view-transform-start': currentStage.views[0].backwardState.transform,
+    '--current-view-transform-end': currentStage.views[0].forwardState.transform,
+  })
+  if (stagger > 0) currentView.style.setProperty('animation-delay', '0ms')
+  setCSSVars(previousView, duration, ease, {
+    '--previous-view-transform-start': currentStage.views[1].backwardState.transform,
+    '--previous-view-transform-end': currentStage.views[1].forwardState.transform,
+  })
+  if (stagger > 0) previousView.style.setProperty('animation-delay', `${stagger}ms`)
+  if (lastView) {
+    setCSSVars(lastView, duration, ease, {
+      '--last-view-transform-start': currentStage.views[2].backwardState.transform,
+      '--last-view-transform-end': currentStage.views[2].forwardState.transform,
+    })
+    if (stagger > 0) lastView.style.setProperty('animation-delay', `${stagger * 2}ms`)
+  }
+
+  // Trigger animations via classes
+  currentView.classList.add('zoom-current-view')
+  previousView.classList.add('zoom-previous-view')
+  if (lastView) lastView.classList.add('zoom-last-view')
+
+  const elements = lastView ? [currentView, previousView, lastView] : [currentView, previousView]
+  let pending = elements.length
+  const durationMs = parseDurationMs(duration)
+  const maxDelay = lastView ? stagger * 2 : stagger
+
+  const { finish } = createFinishGuard(() => {
+    cleanupListeners(elements, handleEnd)
+    // Clean up animation-delay
+    elements.forEach(el => el.style.removeProperty('animation-delay'))
+    onComplete()
+  }, durationMs + maxDelay + SAFETY_BUFFER_MS)
+
+  function handleEnd (event) {
+    const el = event?.target
+    if (el) el.removeEventListener('animationend', handleEnd)
+    if (el?.isConnected) {
+      try { applyZoomInEndState(el, currentStage) } catch (e) { /* ignore */ }
+    }
+    pending--
+    if (pending <= 0) finish()
+  }
+
+  elements.forEach(el => el.addEventListener('animationend', handleEnd))
+}
+
+// ─── Zoom Out ────────────────────────────────────────────────────────
+
+function runZoomOut (currentView, previousView, lastView, currentStage, duration, ease, canvas, onComplete) {
+  const v0 = currentStage.views[0]
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+  const stagger = currentStage.stagger || 0
+
+  setCSSVars(currentView, duration, ease, {
+    '--current-view-transform-start': v0.backwardState.transform,
+    '--current-view-transform-end': v0.forwardState.transform,
+  })
+  if (stagger > 0) currentView.style.setProperty('animation-delay', '0ms')
+  setCSSVars(previousView, duration, ease, {
+    '--previous-view-transform-start': v1.backwardState.transform,
+    '--previous-view-transform-end': v1.forwardState.transform,
+  })
+  if (stagger > 0) previousView.style.setProperty('animation-delay', `${stagger}ms`)
+  if (lastView && v2) {
+    setCSSVars(lastView, duration, ease, {
+      '--last-view-transform-start': v2.backwardState.transform,
+      '--last-view-transform-end': v2.forwardState.transform,
+    })
+    if (stagger > 0) lastView.style.setProperty('animation-delay', `${stagger * 2}ms`)
+  }
+
+  // Trigger reverse animations
+  currentView.classList.add('zoom-current-view-reverse')
+  previousView.classList.add('zoom-previous-view-reverse')
+  if (lastView) lastView.classList.add('zoom-last-view-reverse')
+
+  const elements = lastView ? [currentView, previousView, lastView] : [currentView, previousView]
+  let pending = elements.length
+  const durationMs = parseDurationMs(duration)
+  const maxDelay = lastView ? stagger * 2 : stagger
+
+  const { finish } = createFinishGuard(() => {
+    cleanupListeners(elements, handleEnd)
+    elements.forEach(el => el.style.removeProperty('animation-delay'))
+    onComplete()
+  }, durationMs + maxDelay + SAFETY_BUFFER_MS)
+
+  function handleEnd (event) {
+    const el = event?.target
+    if (el) el.removeEventListener('animationend', handleEnd)
+    if (el?.isConnected) {
+      try { applyZoomOutEndState(el, currentStage, canvas) } catch (e) { /* ignore */ }
+    }
+    pending--
+    if (pending <= 0) finish()
+  }
+
+  elements.forEach(el => el.addEventListener('animationend', handleEnd))
+}
+
+function applyZoomOutEndState (element, currentStage, canvas) {
+  if (element.classList.contains('zoom-current-view-reverse')) {
+    removeViewFromCanvas(element, canvas)
+    return
+  }
+  if (element.classList.contains('zoom-previous-view-reverse')) {
+    applyZoomOutPreviousState(element, currentStage.views[1].backwardState)
+    return
+  }
+  if (element.classList.contains('zoom-last-view-reverse')) {
+    applyZoomOutLastState(element, currentStage.views[2].backwardState)
+  }
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────
+
+function setCSSVars (el, duration, ease, vars) {
+  el.style.setProperty('--zoom-duration', duration)
+  el.style.setProperty('--zoom-ease', ease)
+  for (const [key, value] of Object.entries(vars)) {
+    el.style.setProperty(key, value)
+  }
+}
+
+function cleanupListeners (elements, handler) {
+  for (const el of elements) {
+    if (el?.removeEventListener) el.removeEventListener('animationend', handler)
+  }
+}

package/src/drivers/driver-helpers.d.ts

@@ -0,0 +1,23 @@
+// Type definitions for zumly/driver-helpers
+
+import type { ZoomSnapshot, ViewState, TransitionSpec, MatrixComponents } from '../../types/zumly.js'
+
+export function parseDurationMs(duration: string | number): number
+export function parseDurationSec(duration: string | number): number
+export function applyZoomInEndState(element: HTMLElement, currentStage: ZoomSnapshot): void
+export function applyZoomOutPreviousState(element: HTMLElement, backwardState: ViewState): void
+export function applyZoomOutLastState(element: HTMLElement, backwardState: ViewState): void
+export function removeViewFromCanvas(element: HTMLElement, canvas: HTMLElement): void
+export function showViews(...elements: (HTMLElement | null | undefined)[]): void
+export function runLateralInstant(spec: TransitionSpec, onComplete: () => void): void
+export const SAFETY_BUFFER_MS: number
+export function createFinishGuard(
+  cleanup: () => void,
+  timeoutMs: number
+): { finish: () => void; safetyTimer: number }
+export function identityMatrix(): MatrixComponents
+export function parseMatrixString(mStr: string): MatrixComponents
+export function matrixToString(m: MatrixComponents): string
+export function lerp(a: number, b: number, t: number): number
+export function interpolateMatrix(from: MatrixComponents, to: MatrixComponents, t: number): MatrixComponents
+export function readComputedMatrix(element: HTMLElement, origin: string, transformStr: string): MatrixComponents

package/src/drivers/driver-helpers.js

@@ -23,15 +23,23 @@ import { showViewContent } from '../view-visibility.js'
  *
  * @example
  *   parseDurationMs('1s')    // → 1000
+ *   parseDurationMs('.7s')   // → 700
  *   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 str = String(duration).trim()
+  // \d*\.?\d+ also accepts a leading dot ('.7s'), which CSS allows —
+  // previously that fell silently into the 500ms fallback.
+  const m = str.match(/^(\d*\.?\d+)\s*(ms|s)?$/i)
+  if (!m) {
+    if (typeof console !== 'undefined') {
+      console.warn(`[zumly] Could not parse duration "${str}" — falling back to 500ms.`) // eslint-disable-line no-console
+    }
+    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)

package/src/drivers/gsap-transition.js

@@ -0,0 +1,149 @@
+/**
+ * GSAP transition driver.
+ * Requires global `gsap` — load from CDN before use:
+ * <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
+ *
+ * @param {Object} spec - Transition spec from the engine
+ * @param {function} onComplete - MUST be called exactly once when done
+ */
+import {
+  parseDurationSec,
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  runLateralInstant,
+} from './driver-helpers.js'
+
+export function runTransition (spec, onComplete) {
+  const gsap = typeof globalThis !== 'undefined' && globalThis.gsap
+  if (!gsap || typeof gsap.to !== 'function') {
+    console.warn('Zumly GSAP driver: GSAP not loaded. Add <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>')
+    onComplete()
+    return
+  }
+
+  const { type, currentView, previousView, lastView, currentStage, duration, ease, canvas } = spec
+  if (!currentView || !previousView || !currentStage) {
+    onComplete()
+    return
+  }
+
+  const durationSec = parseDurationSec(duration)
+
+  if (type === 'lateral') {
+    runLateralInstant(spec, onComplete)
+  } else if (type === 'zoomIn') {
+    runZoomIn(gsap, currentView, previousView, lastView, currentStage, durationSec, ease, onComplete)
+  } else if (type === 'zoomOut') {
+    runZoomOut(gsap, currentView, previousView, lastView, currentStage, durationSec, ease, canvas, onComplete)
+  } else {
+    onComplete()
+  }
+}
+
+// ─── Zoom In ─────────────────────────────────────────────────────────
+
+function runZoomIn (gsap, currentView, previousView, lastView, currentStage, durationSec, ease, onComplete) {
+  showViews(currentView, previousView, lastView)
+
+  const v0 = currentStage.views[0]
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+
+  // Set initial transforms
+  setTransform(currentView, v0.backwardState)
+  setTransform(previousView, v1.backwardState)
+  if (v2) setTransform(lastView, v2.backwardState)
+
+  const tl = gsap.timeline({
+    onComplete: () => {
+      applyZoomInEndState(currentView, currentStage)
+      applyZoomInEndState(previousView, currentStage)
+      if (lastView) applyZoomInEndState(lastView, currentStage)
+      onComplete()
+    }
+  })
+
+  const gsapEase = normalizeEasing(ease)
+  const staggerSec = (currentStage.stagger || 0) / 1000
+  tl.to(currentView, { transform: v0.forwardState.transform, duration: durationSec, ease: gsapEase }, 0)
+  tl.to(previousView, { transform: v1.forwardState.transform, duration: durationSec, ease: gsapEase }, staggerSec)
+  if (v2) {
+    tl.to(lastView, { transform: v2.forwardState.transform, duration: durationSec, ease: gsapEase }, staggerSec * 2)
+  }
+}
+
+// ─── Zoom Out ────────────────────────────────────────────────────────
+
+function runZoomOut (gsap, currentView, previousView, lastView, currentStage, durationSec, ease, canvas, onComplete) {
+  const v0 = currentStage.views[0]
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+  const to1 = v1.backwardState
+  const to2 = v2 ? v2.backwardState : null
+
+  setTransform(currentView, v0.forwardState)
+
+  const from1 = previousView.style.transform || getComputedStyle(previousView).transform || v1.forwardState.transform
+  const from2 = lastView && v2
+    ? (lastView.style.transform || getComputedStyle(lastView).transform || v2.forwardState.transform)
+    : null
+
+  previousView.style.transformOrigin = v1.forwardState.origin
+  if (lastView && v2) lastView.style.transformOrigin = v2.forwardState.origin
+
+  const gsapEase = normalizeEasing(ease)
+
+  const tl = gsap.timeline({
+    onComplete: () => {
+      removeViewFromCanvas(currentView, canvas)
+      applyZoomOutPreviousState(previousView, to1)
+      if (lastView && to2) applyZoomOutLastState(lastView, to2)
+      onComplete()
+    }
+  })
+
+  const staggerSec = (currentStage.stagger || 0) / 1000
+
+  // Set initial transforms so views hold position during stagger delay
+  gsap.set(previousView, { transform: from1 })
+  if (lastView && from2) gsap.set(lastView, { transform: from2 })
+
+  tl.fromTo(currentView,
+    { transform: v0.forwardState.transform },
+    { transform: v0.backwardState.transform, duration: durationSec, ease: gsapEase },
+    0
+  )
+  tl.fromTo(previousView,
+    { transform: from1 },
+    { transform: to1.transform, duration: durationSec, ease: gsapEase },
+    staggerSec
+  )
+
+  if (lastView && to2) {
+    tl.fromTo(lastView,
+      { transform: from2 },
+      { transform: to2.transform, duration: durationSec, ease: gsapEase },
+      staggerSec * 2
+    )
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function setTransform (el, state) {
+  el.style.transformOrigin = state.origin
+  el.style.transform = state.transform
+}
+
+function normalizeEasing (ease) {
+  if (typeof ease !== 'string') return 'power2.inOut'
+  const s = ease.toLowerCase()
+  if (s === 'linear') return 'none'
+  if (s.includes('ease-in-out')) return 'power2.inOut'
+  if (s.includes('ease-in')) return 'power2.in'
+  if (s.includes('ease-out')) return 'power2.out'
+  return s
+}

package/src/drivers/motion-transition.js

@@ -0,0 +1,178 @@
+/**
+ * Motion (motion.dev) transition driver.
+ * Interpolates computed transform matrices during animation.
+ * Load Motion before use:
+ * <script src="https://cdn.jsdelivr.net/npm/motion@11/dist/motion.min.js"></script>
+ *
+ * @param {Object} spec - Transition spec from the engine
+ * @param {function} onComplete - MUST be called exactly once when done
+ */
+import {
+  parseDurationSec,
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  runLateralInstant,
+  readComputedMatrix,
+  interpolateMatrix,
+  matrixToString,
+} from './driver-helpers.js'
+
+export function runTransition (spec, onComplete) {
+  const animate = getMotionAnimate()
+  if (!animate || typeof animate !== 'function') {
+    console.warn('Zumly Motion driver: Motion not loaded. Add <script src="https://cdn.jsdelivr.net/npm/motion@11/dist/motion.min.js"></script>')
+    onComplete()
+    return
+  }
+
+  const { type, currentView, previousView, lastView, currentStage, duration, ease, canvas } = spec
+  if (!currentView || !previousView || !currentStage) {
+    onComplete()
+    return
+  }
+
+  const durationSec = parseDurationSec(duration)
+
+  if (type === 'lateral') {
+    runLateralInstant(spec, onComplete)
+  } else if (type === 'zoomIn') {
+    runZoomIn(animate, currentView, previousView, lastView, currentStage, durationSec, ease, onComplete)
+  } else if (type === 'zoomOut') {
+    runZoomOut(animate, currentView, previousView, lastView, currentStage, durationSec, ease, canvas, onComplete)
+  } else {
+    onComplete()
+  }
+}
+
+// ─── Zoom In ─────────────────────────────────────────────────────────
+
+function runZoomIn (animate, currentView, previousView, lastView, currentStage, durationSec, ease, onComplete) {
+  showViews(currentView, previousView, lastView)
+
+  const matrices = computeMatrixPairs(
+    currentView, previousView, lastView, currentStage, 'forward'
+  )
+  applyMatricesAtProgress(matrices, 0)
+
+  const stagger = currentStage.stagger || 0
+  const staggerSec = stagger / 1000
+  const durationMs = durationSec * 1000
+  const totalSec = durationSec + (matrices.length > 2 ? staggerSec * 2 : staggerSec)
+
+  const controls = animate(0, 1, {
+    duration: totalSec,
+    ease: normalizeEasing(ease),
+    onUpdate: t => {
+      const elapsed = t * totalSec * 1000
+      applyStaggeredMatrices(matrices, elapsed, durationMs, stagger)
+    },
+  })
+
+  controls.then(() => {
+    applyZoomInEndState(currentView, currentStage)
+    applyZoomInEndState(previousView, currentStage)
+    if (lastView) applyZoomInEndState(lastView, currentStage)
+    onComplete()
+  }).catch(() => onComplete())
+}
+
+// ─── Zoom Out ────────────────────────────────────────────────────────
+
+function runZoomOut (animate, currentView, previousView, lastView, currentStage, durationSec, ease, canvas, onComplete) {
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+  const to1 = v1.backwardState
+  const to2 = v2 ? v2.backwardState : null
+
+  const matrices = computeMatrixPairs(
+    currentView, previousView, lastView, currentStage, 'backward'
+  )
+  applyMatricesAtProgress(matrices, 0)
+
+  const stagger = currentStage.stagger || 0
+  const staggerSec = stagger / 1000
+  const durationMs = durationSec * 1000
+  const totalSec = durationSec + (matrices.length > 2 ? staggerSec * 2 : staggerSec)
+
+  const controls = animate(0, 1, {
+    duration: totalSec,
+    ease: normalizeEasing(ease),
+    onUpdate: t => {
+      const elapsed = t * totalSec * 1000
+      applyStaggeredMatrices(matrices, elapsed, durationMs, stagger)
+    },
+  })
+
+  controls.then(() => {
+    removeViewFromCanvas(currentView, canvas)
+    applyZoomOutPreviousState(previousView, to1)
+    if (lastView && to2) applyZoomOutLastState(lastView, to2)
+    onComplete()
+  }).catch(() => onComplete())
+}
+
+// ─── Matrix computation ──────────────────────────────────────────────
+
+function computeMatrixPairs (currentView, previousView, lastView, currentStage, direction) {
+  const v0 = currentStage.views[0]
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+
+  const entries = [
+    { el: currentView, backward: v0.backwardState, forward: v0.forwardState },
+    { el: previousView, backward: v1.backwardState, forward: v1.forwardState },
+  ]
+  if (v2) entries.push({ el: lastView, backward: v2.backwardState, forward: v2.forwardState })
+
+  return entries.map(({ el, backward, forward }) => {
+    if (direction === 'forward') {
+      return {
+        el,
+        from: readComputedMatrix(el, backward.origin, backward.transform),
+        to: readComputedMatrix(el, backward.origin, forward.transform),
+      }
+    } else {
+      return {
+        el,
+        from: readComputedMatrix(el, forward.origin, forward.transform),
+        to: readComputedMatrix(el, forward.origin, backward.transform),
+      }
+    }
+  })
+}
+
+function applyMatricesAtProgress (matrices, t) {
+  for (const { el, from, to } of matrices) {
+    el.style.transform = matrixToString(interpolateMatrix(from, to, t))
+  }
+}
+
+function applyStaggeredMatrices (matrices, elapsed, durationMs, stagger) {
+  for (let i = 0; i < matrices.length; i++) {
+    const { el, from, to } = matrices[i]
+    const delay = i * stagger
+    const localElapsed = Math.max(0, elapsed - delay)
+    const t = durationMs > 0 ? Math.min(1, localElapsed / durationMs) : 1
+    el.style.transform = matrixToString(interpolateMatrix(from, to, t))
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function getMotionAnimate () {
+  const g = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : {}
+  return g.motion?.animate || g.Motion?.animate || g.animate
+}
+
+function normalizeEasing (ease) {
+  if (typeof ease !== 'string') return 'easeInOut'
+  const s = ease.toLowerCase()
+  if (s === 'linear') return 'linear'
+  if (s.includes('ease-in-out')) return 'easeInOut'
+  if (s.includes('ease-in')) return 'easeIn'
+  if (s.includes('ease-out')) return 'easeOut'
+  return ease
+}

package/src/drivers/none-transition.js

@@ -0,0 +1,54 @@
+/**
+ * No-animation transition driver.
+ * Applies final state immediately and calls onComplete synchronously.
+ * Useful for tests, instant UX, or reduced-motion preference.
+ *
+ * This is the simplest possible Zumly driver — a good starting point
+ * for writing your own. See docs/DRIVER_API.md for the full guide.
+ *
+ * @param {Object} spec - Transition spec from the engine
+ * @param {function} onComplete - MUST be called exactly once when done
+ */
+import {
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  runLateralInstant,
+} from './driver-helpers.js'
+
+export function runTransition (spec, onComplete) {
+  const { type, currentView, previousView, lastView, currentStage, canvas } = spec
+
+  if (!currentView || !previousView || !currentStage) {
+    onComplete()
+    return
+  }
+
+  if (type === 'lateral') {
+    runLateralInstant(spec, onComplete)
+    return
+  }
+
+  if (type === 'zoomIn') {
+    showViews(currentView, previousView, lastView)
+    applyZoomInEndState(currentView, currentStage)
+    applyZoomInEndState(previousView, currentStage)
+    if (lastView) applyZoomInEndState(lastView, currentStage)
+    onComplete()
+    return
+  }
+
+  if (type === 'zoomOut') {
+    removeViewFromCanvas(currentView, canvas)
+    showViews(previousView, lastView)
+    applyZoomOutPreviousState(previousView, currentStage.views[1].backwardState)
+    if (lastView) applyZoomOutLastState(lastView, currentStage.views[2].backwardState)
+    onComplete()
+    return
+  }
+
+  // Unknown type — still must call onComplete
+  onComplete()
+}