@scenar/core 0.5.0 → 0.7.0

package/index.d.ts

@@ -2,15 +2,15 @@ export type { ScenarioStep } from "./scenario/types.js";
 export type { ScenarioBundle } from "./scenario/bundle.js";
 export type { ActionType, StepAction, UseStepInteractionsOptions, } from "./scenario/step-action.js";
 export type { NarrationEntry, NarrationManifest } from "./narration/types.js";
-export type { ViewportTransform } from "./viewport/transform.js";
-export { VIEWPORT_TRANSFORM_IDENTITY } from "./viewport/transform.js";
+export type { ViewportTransform, ViewportCameraMove } from "./viewport/transform.js";
+export { VIEWPORT_TRANSFORM_IDENTITY, VIEWPORT_CAMERA_AT_REST, cameraEase, interpolateViewportTransform, } from "./viewport/transform.js";
 export type { Position } from "./cursor/compute-position.js";
 export { computeCursorPosition } from "./cursor/compute-position.js";
 export type { StepTimeline } from "./timeline/compute-step-timeline.js";
 export { computeStepTimeline } from "./timeline/compute-step-timeline.js";
 export { deriveStepFromTime } from "./timeline/derive-step.js";
 export { getStepDurationMs } from "./timeline/step-duration.js";
-export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, VIEWPORT_SETTLE_MS, } from "./timing/constants.js";
+export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, CAMERA_TRANSITION_MS, VIEWPORT_SETTLE_MS, } from "./timing/constants.js";
 export { findScrollParent, scrollTargetIntoView, scrollTargetIntoViewInstant, } from "./dom/scroll.js";
 export { CURSOR_TARGET_ATTRIBUTE, SCROLL_TARGET_ATTRIBUTE, HOVER_STATE_ATTRIBUTE, DRAG_STATE_ATTRIBUTE, cursorTargetSelector, scrollTargetSelector, } from "./targeting/data-attributes.js";
 export { SCENAR_EMBED_SOURCE, SCENAR_EMBED_PROTOCOL_VERSION, frameEmbedEvent, frameEmbedCommand, parseEmbedCommand, parseEmbedEvent, } from "./embed/protocol.js";

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,UAAU,EACV,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAGtE,YAAY,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,UAAU,EACV,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,UAAU,EACV,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC"}

package/index.js

@@ -1,12 +1,12 @@
 // @scenar/core — public API
 // Pure TypeScript types, timing, and utilities for scenario playback.
-export { VIEWPORT_TRANSFORM_IDENTITY } from "./viewport/transform.js";
+export { VIEWPORT_TRANSFORM_IDENTITY, VIEWPORT_CAMERA_AT_REST, cameraEase, interpolateViewportTransform, } from "./viewport/transform.js";
 export { computeCursorPosition } from "./cursor/compute-position.js";
 export { computeStepTimeline } from "./timeline/compute-step-timeline.js";
 export { deriveStepFromTime } from "./timeline/derive-step.js";
 export { getStepDurationMs } from "./timeline/step-duration.js";
 // Timing constants
-export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, VIEWPORT_SETTLE_MS, } from "./timing/constants.js";
+export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, CAMERA_TRANSITION_MS, VIEWPORT_SETTLE_MS, } from "./timing/constants.js";
 // DOM scroll utilities
 export { findScrollParent, scrollTargetIntoView, scrollTargetIntoViewInstant, } from "./dom/scroll.js";
 // Data-attribute targeting contract

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,sEAAsE;AAgBtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAItE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,uBAAuB;AACvB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,0EAA0E;AAC1E,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAQ7B,uEAAuE;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,sEAAsE;AAgBtE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,UAAU,EACV,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,uBAAuB;AACvB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,0EAA0E;AAC1E,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAQ7B,uEAAuE;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenar/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Pure TypeScript types, timing, and utilities for the Scenar scenario engine.",
   "license": "Apache-2.0",
   "type": "module",

package/scenario/step-action.d.ts

@@ -101,5 +101,15 @@ export interface UseStepInteractionsOptions<T> {
      * needed to center the target element and calls this callback.
      */
     setViewportTransform?: (transform: ViewportTransform) => void;
+    /**
+     * The camera's content element (`ViewportTransformLayer`'s `contentRef`).
+     * `viewport_transition` target math measures against it so canonical
+     * coordinates stay correct at any camera state. Optional — effects fall
+     * back to `containerRef`, which is only exact while the camera is at
+     * identity.
+     */
+    cameraRef?: {
+        current: HTMLElement | null;
+    };
 }
 //# sourceMappingURL=step-action.d.ts.map

package/scenario/step-action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-action.d.ts","sourceRoot":"","sources":["../../src/scenario/step-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,YAAY,GACZ,cAAc,GACd,OAAO,GACP,MAAM,GACN,OAAO,GACP,MAAM,GACN,qBAAqB,CAAC;AAE1B,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,sDAAsD;AACtD,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,qCAAqC;IACrC,YAAY,EAAE;QAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,qDAAqD;IACrD,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACtD;;;;OAIG;IACH,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/D"}
+{"version":3,"file":"step-action.d.ts","sourceRoot":"","sources":["../../src/scenario/step-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,YAAY,GACZ,cAAc,GACd,OAAO,GACP,MAAM,GACN,OAAO,GACP,MAAM,GACN,qBAAqB,CAAC;AAE1B,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,sDAAsD;AACtD,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,qCAAqC;IACrC,YAAY,EAAE;QAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,qDAAqD;IACrD,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACtD;;;;OAIG;IACH,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC9D;;;;;;OAMG;IACH,SAAS,CAAC,EAAE;QAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;KAAE,CAAC;CAC7C"}

package/src/index.ts

@@ -14,8 +14,13 @@ export type {
 export type { NarrationEntry, NarrationManifest } from "./narration/types.js";
 
 // Viewport types
-export type { ViewportTransform } from "./viewport/transform.js";
-export { VIEWPORT_TRANSFORM_IDENTITY } from "./viewport/transform.js";
+export type { ViewportTransform, ViewportCameraMove } from "./viewport/transform.js";
+export {
+  VIEWPORT_TRANSFORM_IDENTITY,
+  VIEWPORT_CAMERA_AT_REST,
+  cameraEase,
+  interpolateViewportTransform,
+} from "./viewport/transform.js";
 
 // Cursor types
 export type { Position } from "./cursor/compute-position.js";
@@ -33,6 +38,7 @@ export {
   TYPE_CHAR_DELAY_MS,
   HOVER_HOLD_MS,
   DRAG_SETTLE_MS,
+  CAMERA_TRANSITION_MS,
   VIEWPORT_SETTLE_MS,
 } from "./timing/constants.js";
 

package/src/scenario/step-action.ts

@@ -110,4 +110,12 @@ export interface UseStepInteractionsOptions<T> {
    * needed to center the target element and calls this callback.
    */
   setViewportTransform?: (transform: ViewportTransform) => void;
+  /**
+   * The camera's content element (`ViewportTransformLayer`'s `contentRef`).
+   * `viewport_transition` target math measures against it so canonical
+   * coordinates stay correct at any camera state. Optional — effects fall
+   * back to `containerRef`, which is only exact while the camera is at
+   * identity.
+   */
+  cameraRef?: { current: HTMLElement | null };
 }

package/src/timing/constants.ts

@@ -11,9 +11,9 @@
  * Milliseconds after a cursor target is set before the cursor is
  * considered "arrived" and the click ripple appears.
  *
- * Derived from the Cursor spring parameters (stiffness 170,
- * damping 22, mass 0.6) — the spring visually settles within
- * this window for typical travel distances in the viewport.
+ * The Cursor's distance-adaptive travel clamps its longest move to
+ * settle inside this window (see `travelTransition` in
+ * `@scenar/react`'s Cursor) — the ripple must never fire mid-flight.
  */
 export const CLICK_DELAY_MS = 450;
 
@@ -48,12 +48,19 @@ export const HOVER_HOLD_MS = 1500;
 export const DRAG_SETTLE_MS = 200;
 
 /**
- * Expected milliseconds for the viewport transition spring to settle
- * after a zoom or pan change.
+ * Duration (ms) of a camera move — a `viewport_transition` zoom or pan.
  *
- * The ViewportTransformLayer uses a softer spring (stiffness 100,
- * damping 20, mass 0.8) than the cursor spring, so it takes longer
- * to settle. Used for dev-mode warnings when a subsequent cursor
- * action is scheduled too close to a viewport transition.
+ * This is a fixed tween, not a spring: browser playback eases toward the
+ * target with `cameraEase` over exactly this duration, and video export
+ * computes the same curve per frame via `interpolateViewportTransform`,
+ * so both paths agree at every instant.
  */
-export const VIEWPORT_SETTLE_MS = 500;
+export const CAMERA_TRANSITION_MS = 600;
+
+/**
+ * Milliseconds after a `viewport_transition` fires before the camera is
+ * at rest. Equal to {@link CAMERA_TRANSITION_MS} (the move is a fixed
+ * tween). Used for dev-mode warnings when a subsequent cursor action is
+ * scheduled too close to a viewport transition.
+ */
+export const VIEWPORT_SETTLE_MS = CAMERA_TRANSITION_MS;

package/src/viewport/transform.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import {
+  VIEWPORT_CAMERA_AT_REST,
+  VIEWPORT_TRANSFORM_IDENTITY,
+  cameraEase,
+  interpolateViewportTransform,
+} from "./transform.js";
+
+describe("cameraEase", () => {
+  it("starts at 0 and ends at 1", () => {
+    expect(cameraEase(0)).toBe(0);
+    expect(cameraEase(1)).toBe(1);
+  });
+
+  it("clamps out-of-range progress", () => {
+    expect(cameraEase(-0.5)).toBe(0);
+    expect(cameraEase(1.5)).toBe(1);
+  });
+
+  it("is monotonically non-decreasing", () => {
+    let prev = cameraEase(0);
+    for (let i = 1; i <= 100; i++) {
+      const next = cameraEase(i / 100);
+      expect(next).toBeGreaterThanOrEqual(prev);
+      prev = next;
+    }
+  });
+
+  it("decelerates: covers more than half the distance in the first quarter", () => {
+    // The defining property of a camera move — commit fast, glide to rest.
+    expect(cameraEase(0.25)).toBeGreaterThan(0.5);
+  });
+
+  it("never overshoots", () => {
+    for (let i = 0; i <= 100; i++) {
+      expect(cameraEase(i / 100)).toBeLessThanOrEqual(1);
+    }
+  });
+});
+
+describe("interpolateViewportTransform", () => {
+  const from = { scale: 1, x: 0, y: 0 };
+  const to = { scale: 1.5, x: -200, y: -120 };
+
+  it("returns `from` at progress 0", () => {
+    expect(interpolateViewportTransform(from, to, 0)).toEqual(from);
+  });
+
+  it("returns `to` at progress 1", () => {
+    expect(interpolateViewportTransform(from, to, 1)).toEqual(to);
+  });
+
+  it("clamps beyond-end progress to `to` (the camera rests after the move)", () => {
+    expect(interpolateViewportTransform(from, to, 42)).toEqual(to);
+  });
+
+  it("applies the ease to every component consistently", () => {
+    const eased = cameraEase(0.5);
+    const mid = interpolateViewportTransform(from, to, 0.5);
+    expect(mid.scale).toBeCloseTo(1 + 0.5 * eased, 10);
+    expect(mid.x).toBeCloseTo(-200 * eased, 10);
+    expect(mid.y).toBeCloseTo(-120 * eased, 10);
+  });
+
+  it("is an identity when from and to are equal", () => {
+    for (const p of [0, 0.3, 0.7, 1]) {
+      expect(
+        interpolateViewportTransform(
+          VIEWPORT_TRANSFORM_IDENTITY,
+          VIEWPORT_TRANSFORM_IDENTITY,
+          p,
+        ),
+      ).toEqual(VIEWPORT_TRANSFORM_IDENTITY);
+    }
+  });
+
+  it("VIEWPORT_CAMERA_AT_REST holds the identity at any time", () => {
+    const { from: f, to: t } = VIEWPORT_CAMERA_AT_REST;
+    expect(interpolateViewportTransform(f, t, 0.5)).toEqual(VIEWPORT_TRANSFORM_IDENTITY);
+  });
+});

package/src/viewport/transform.ts

@@ -11,3 +11,65 @@ export const VIEWPORT_TRANSFORM_IDENTITY: Readonly<ViewportTransform> = {
   x: 0,
   y: 0,
 };
+
+/**
+ * A camera move: the transform it started `from`, the transform it is
+ * heading `to`, and the timeline instant the move fired at.
+ *
+ * Both output paths derive the same visual from this one value: browser
+ * playback tweens toward `to` with {@link cameraEase} over
+ * {@link CAMERA_TRANSITION_MS}; video export computes the exact
+ * intermediate transform for any frame with
+ * {@link interpolateViewportTransform} — same curve, same duration,
+ * zero drift.
+ */
+export interface ViewportCameraMove {
+  readonly from: ViewportTransform;
+  readonly to: ViewportTransform;
+  /** Timeline time (ms) the move fired at, in the scenario's time domain. */
+  readonly atTimeMs: number;
+}
+
+/** A camera resting at the identity transform since t=0. */
+export const VIEWPORT_CAMERA_AT_REST: Readonly<ViewportCameraMove> = {
+  from: VIEWPORT_TRANSFORM_IDENTITY,
+  to: VIEWPORT_TRANSFORM_IDENTITY,
+  atTimeMs: 0,
+};
+
+/**
+ * The camera's deceleration curve (ease-out quint).
+ *
+ * A camera move commits fast and glides to a stop — it must never
+ * overshoot, because overshoot reads as a zoom *effect* rather than a
+ * camera. Referentially transparent so browser playback (as a tween
+ * easing) and video export (via {@link interpolateViewportTransform})
+ * share one implementation.
+ */
+export function cameraEase(progress: number): number {
+  const t = Math.min(1, Math.max(0, progress));
+  return 1 - (1 - t) ** 5;
+}
+
+/**
+ * The intermediate transform of a camera move at linear progress
+ * `progress` (0..1, clamped). Applies {@link cameraEase}, then
+ * interpolates each component. Pure — the video-export path calls this
+ * per frame.
+ */
+export function interpolateViewportTransform(
+  from: ViewportTransform,
+  to: ViewportTransform,
+  progress: number,
+): ViewportTransform {
+  // Exact endpoint, not `from + (to - from) * 1`: floating point does not
+  // guarantee that expression returns `to`, and a camera at rest must land
+  // on the authored transform bit-for-bit (consumers compare identity).
+  if (progress >= 1) return { ...to };
+  const eased = cameraEase(progress);
+  return {
+    scale: from.scale + (to.scale - from.scale) * eased,
+    x: from.x + (to.x - from.x) * eased,
+    y: from.y + (to.y - from.y) * eased,
+  };
+}

package/timing/constants.d.ts

@@ -10,9 +10,9 @@
  * Milliseconds after a cursor target is set before the cursor is
  * considered "arrived" and the click ripple appears.
  *
- * Derived from the Cursor spring parameters (stiffness 170,
- * damping 22, mass 0.6) — the spring visually settles within
- * this window for typical travel distances in the viewport.
+ * The Cursor's distance-adaptive travel clamps its longest move to
+ * settle inside this window (see `travelTransition` in
+ * `@scenar/react`'s Cursor) — the ripple must never fire mid-flight.
  */
 export declare const CLICK_DELAY_MS = 450;
 /**
@@ -43,13 +43,19 @@ export declare const HOVER_HOLD_MS = 1500;
  */
 export declare const DRAG_SETTLE_MS = 200;
 /**
- * Expected milliseconds for the viewport transition spring to settle
- * after a zoom or pan change.
+ * Duration (ms) of a camera move — a `viewport_transition` zoom or pan.
  *
- * The ViewportTransformLayer uses a softer spring (stiffness 100,
- * damping 20, mass 0.8) than the cursor spring, so it takes longer
- * to settle. Used for dev-mode warnings when a subsequent cursor
- * action is scheduled too close to a viewport transition.
+ * This is a fixed tween, not a spring: browser playback eases toward the
+ * target with `cameraEase` over exactly this duration, and video export
+ * computes the same curve per frame via `interpolateViewportTransform`,
+ * so both paths agree at every instant.
  */
-export declare const VIEWPORT_SETTLE_MS = 500;
+export declare const CAMERA_TRANSITION_MS = 600;
+/**
+ * Milliseconds after a `viewport_transition` fires before the camera is
+ * at rest. Equal to {@link CAMERA_TRANSITION_MS} (the move is a fixed
+ * tween). Used for dev-mode warnings when a subsequent cursor action is
+ * scheduled too close to a viewport transition.
+ */
+export declare const VIEWPORT_SETTLE_MS = 600;
 //# sourceMappingURL=constants.d.ts.map

package/timing/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/timing/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/timing/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,MAAuB,CAAC"}

package/timing/constants.js

@@ -10,9 +10,9 @@
  * Milliseconds after a cursor target is set before the cursor is
  * considered "arrived" and the click ripple appears.
  *
- * Derived from the Cursor spring parameters (stiffness 170,
- * damping 22, mass 0.6) — the spring visually settles within
- * this window for typical travel distances in the viewport.
+ * The Cursor's distance-adaptive travel clamps its longest move to
+ * settle inside this window (see `travelTransition` in
+ * `@scenar/react`'s Cursor) — the ripple must never fire mid-flight.
  */
 export const CLICK_DELAY_MS = 450;
 /**
@@ -43,13 +43,19 @@ export const HOVER_HOLD_MS = 1500;
  */
 export const DRAG_SETTLE_MS = 200;
 /**
- * Expected milliseconds for the viewport transition spring to settle
- * after a zoom or pan change.
+ * Duration (ms) of a camera move — a `viewport_transition` zoom or pan.
  *
- * The ViewportTransformLayer uses a softer spring (stiffness 100,
- * damping 20, mass 0.8) than the cursor spring, so it takes longer
- * to settle. Used for dev-mode warnings when a subsequent cursor
- * action is scheduled too close to a viewport transition.
+ * This is a fixed tween, not a spring: browser playback eases toward the
+ * target with `cameraEase` over exactly this duration, and video export
+ * computes the same curve per frame via `interpolateViewportTransform`,
+ * so both paths agree at every instant.
  */
-export const VIEWPORT_SETTLE_MS = 500;
+export const CAMERA_TRANSITION_MS = 600;
+/**
+ * Milliseconds after a `viewport_transition` fires before the camera is
+ * at rest. Equal to {@link CAMERA_TRANSITION_MS} (the move is a fixed
+ * tween). Used for dev-mode warnings when a subsequent cursor action is
+ * scheduled too close to a viewport transition.
+ */
+export const VIEWPORT_SETTLE_MS = CAMERA_TRANSITION_MS;
 //# sourceMappingURL=constants.js.map

package/timing/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/timing/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/timing/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC"}

package/viewport/transform.d.ts

@@ -6,4 +6,40 @@ export interface ViewportTransform {
 }
 /** The identity transform — no zoom, no translation. */
 export declare const VIEWPORT_TRANSFORM_IDENTITY: Readonly<ViewportTransform>;
+/**
+ * A camera move: the transform it started `from`, the transform it is
+ * heading `to`, and the timeline instant the move fired at.
+ *
+ * Both output paths derive the same visual from this one value: browser
+ * playback tweens toward `to` with {@link cameraEase} over
+ * {@link CAMERA_TRANSITION_MS}; video export computes the exact
+ * intermediate transform for any frame with
+ * {@link interpolateViewportTransform} — same curve, same duration,
+ * zero drift.
+ */
+export interface ViewportCameraMove {
+    readonly from: ViewportTransform;
+    readonly to: ViewportTransform;
+    /** Timeline time (ms) the move fired at, in the scenario's time domain. */
+    readonly atTimeMs: number;
+}
+/** A camera resting at the identity transform since t=0. */
+export declare const VIEWPORT_CAMERA_AT_REST: Readonly<ViewportCameraMove>;
+/**
+ * The camera's deceleration curve (ease-out quint).
+ *
+ * A camera move commits fast and glides to a stop — it must never
+ * overshoot, because overshoot reads as a zoom *effect* rather than a
+ * camera. Referentially transparent so browser playback (as a tween
+ * easing) and video export (via {@link interpolateViewportTransform})
+ * share one implementation.
+ */
+export declare function cameraEase(progress: number): number;
+/**
+ * The intermediate transform of a camera move at linear progress
+ * `progress` (0..1, clamped). Applies {@link cameraEase}, then
+ * interpolates each component. Pure — the video-export path calls this
+ * per frame.
+ */
+export declare function interpolateViewportTransform(from: ViewportTransform, to: ViewportTransform, progress: number): ViewportTransform;
 //# sourceMappingURL=transform.d.ts.map

package/viewport/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/viewport/transform.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wDAAwD;AACxD,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,iBAAiB,CAInE,CAAC"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/viewport/transform.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wDAAwD;AACxD,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,iBAAiB,CAInE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,kBAAkB,CAIhE,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAWnB"}

package/viewport/transform.js

@@ -4,4 +4,42 @@ export const VIEWPORT_TRANSFORM_IDENTITY = {
     x: 0,
     y: 0,
 };
+/** A camera resting at the identity transform since t=0. */
+export const VIEWPORT_CAMERA_AT_REST = {
+    from: VIEWPORT_TRANSFORM_IDENTITY,
+    to: VIEWPORT_TRANSFORM_IDENTITY,
+    atTimeMs: 0,
+};
+/**
+ * The camera's deceleration curve (ease-out quint).
+ *
+ * A camera move commits fast and glides to a stop — it must never
+ * overshoot, because overshoot reads as a zoom *effect* rather than a
+ * camera. Referentially transparent so browser playback (as a tween
+ * easing) and video export (via {@link interpolateViewportTransform})
+ * share one implementation.
+ */
+export function cameraEase(progress) {
+    const t = Math.min(1, Math.max(0, progress));
+    return 1 - (1 - t) ** 5;
+}
+/**
+ * The intermediate transform of a camera move at linear progress
+ * `progress` (0..1, clamped). Applies {@link cameraEase}, then
+ * interpolates each component. Pure — the video-export path calls this
+ * per frame.
+ */
+export function interpolateViewportTransform(from, to, progress) {
+    // Exact endpoint, not `from + (to - from) * 1`: floating point does not
+    // guarantee that expression returns `to`, and a camera at rest must land
+    // on the authored transform bit-for-bit (consumers compare identity).
+    if (progress >= 1)
+        return { ...to };
+    const eased = cameraEase(progress);
+    return {
+        scale: from.scale + (to.scale - from.scale) * eased,
+        x: from.x + (to.x - from.x) * eased,
+        y: from.y + (to.y - from.y) * eased,
+    };
+}
 //# sourceMappingURL=transform.js.map

package/viewport/transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../src/viewport/transform.ts"],"names":[],"mappings":"AAOA,wDAAwD;AACxD,MAAM,CAAC,MAAM,2BAA2B,GAAgC;IACtE,KAAK,EAAE,CAAC;IACR,CAAC,EAAE,CAAC;IACJ,CAAC,EAAE,CAAC;CACL,CAAC"}
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../src/viewport/transform.ts"],"names":[],"mappings":"AAOA,wDAAwD;AACxD,MAAM,CAAC,MAAM,2BAA2B,GAAgC;IACtE,KAAK,EAAE,CAAC;IACR,CAAC,EAAE,CAAC;IACJ,CAAC,EAAE,CAAC;CACL,CAAC;AAoBF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,uBAAuB,GAAiC;IACnE,IAAI,EAAE,2BAA2B;IACjC,EAAE,EAAE,2BAA2B;IAC/B,QAAQ,EAAE,CAAC;CACZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC1C,IAAuB,EACvB,EAAqB,EACrB,QAAgB;IAEhB,wEAAwE;IACxE,yEAAyE;IACzE,sEAAsE;IACtE,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACnC,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK;QACnD,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK;QACnC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK;KACpC,CAAC;AACJ,CAAC"}