@scenar/core 0.0.1

package/src/timeline/step-duration.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { getStepDurationMs } from "./step-duration.js";
+
+describe("getStepDurationMs", () => {
+  const steps = [
+    { delayMs: 0, data: null },
+    { delayMs: 1500, data: null },
+    { delayMs: 2000, data: null },
+  ];
+
+  it("returns narration duration when manifest has an entry", () => {
+    const manifest = {
+      steps: [{ src: "a.mp3", durationMs: 4000 }, null, null],
+    };
+    expect(getStepDurationMs(0, manifest, steps)).toBe(4000);
+  });
+
+  it("falls back to next step delayMs when no narration", () => {
+    expect(getStepDurationMs(0, undefined, steps)).toBe(1500);
+    expect(getStepDurationMs(1, undefined, steps)).toBe(2000);
+  });
+
+  it("falls back to 3000 for the last step with no narration", () => {
+    expect(getStepDurationMs(2, undefined, steps)).toBe(3000);
+  });
+
+  it("treats zero narration duration as missing", () => {
+    const manifest = {
+      steps: [{ src: "a.mp3", durationMs: 0 }, null, null],
+    };
+    expect(getStepDurationMs(0, manifest, steps)).toBe(1500);
+  });
+
+  it("handles null entries in manifest", () => {
+    const manifest = { steps: [null, null, null] };
+    expect(getStepDurationMs(0, manifest, steps)).toBe(1500);
+  });
+});

package/src/timeline/step-duration.ts

@@ -0,0 +1,25 @@
+import type { NarrationManifest } from "../narration/types.js";
+import type { ScenarioStep } from "../scenario/types.js";
+
+/** Fallback duration for the last step when no narration exists. */
+const LAST_STEP_FALLBACK_MS = 3000;
+
+/**
+ * Compute the effective duration of a step for interaction timing.
+ *
+ * Uses the narration clip duration if available. Falls back to the
+ * next step's `delayMs` (since the next step's delay is the time
+ * until it appears, which equals the current step's screen time).
+ * For the last step, falls back to {@link LAST_STEP_FALLBACK_MS}.
+ */
+export function getStepDurationMs<T>(
+  stepIndex: number,
+  manifest: NarrationManifest | undefined,
+  steps: readonly ScenarioStep<T>[],
+): number {
+  const narrationMs = manifest?.steps[stepIndex]?.durationMs;
+  if (narrationMs != null && narrationMs > 0) return narrationMs;
+
+  const nextStep = steps[stepIndex + 1];
+  return nextStep ? nextStep.delayMs : LAST_STEP_FALLBACK_MS;
+}

package/src/timing/constants.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared timing constants for the scenario playback engine.
+ *
+ * These values coordinate animation timing between the Cursor component
+ * (visual ripple) and the step-interactions hook (action dispatch).
+ * Both must agree on when the cursor has "arrived" at its target so
+ * the click ripple and the DOM click event fire in sync.
+ */
+
+/**
+ * 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.
+ */
+export const CLICK_DELAY_MS = 450;
+
+/**
+ * Default milliseconds between characters for the `type` action.
+ *
+ * 50 ms per character = 20 characters/second — fast enough to feel
+ * like confident typing, slow enough that each character is readable
+ * in both browser playback and video export. Overridable per-action
+ * via {@link StepAction.typeDelay}.
+ */
+export const TYPE_CHAR_DELAY_MS = 50;
+
+/**
+ * Default milliseconds to hold the cursor in place during a `hover`
+ * action, between the enter-event dispatch and the leave-event
+ * dispatch.
+ *
+ * 1500 ms gives viewers enough time to read a tooltip or notice a
+ * hover-state change in both browser playback and video export.
+ * Overridable per-action via {@link StepAction.hoverDuration}.
+ */
+export const HOVER_HOLD_MS = 1500;
+
+/**
+ * Milliseconds to pause at the drag source after pressing before
+ * starting the drag movement to the destination.
+ *
+ * 200 ms mimics the brief human hesitation between mousedown and the
+ * start of a deliberate drag gesture.
+ */
+export const DRAG_SETTLE_MS = 200;
+
+/**
+ * Expected milliseconds for the viewport transition spring to settle
+ * after a zoom or pan change.
+ *
+ * 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.
+ */
+export const VIEWPORT_SETTLE_MS = 500;

package/src/viewport/transform.ts

@@ -0,0 +1,13 @@
+/** Viewport transform state produced by step interactions. */
+export interface ViewportTransform {
+  scale: number;
+  x: number;
+  y: number;
+}
+
+/** The identity transform — no zoom, no translation. */
+export const VIEWPORT_TRANSFORM_IDENTITY: Readonly<ViewportTransform> = {
+  scale: 1,
+  x: 0,
+  y: 0,
+};

package/targeting/data-attributes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Centralized data-attribute contract for the scenario engine.
+ *
+ * The engine identifies interactive elements in the DOM via these
+ * data attributes. This module is the single source of truth for
+ * attribute names and selector builders — consumers never hard-code
+ * attribute strings.
+ */
+/** Attribute name for cursor-targetable elements. */
+export declare const CURSOR_TARGET_ATTRIBUTE = "data-cursor-target";
+/** Attribute name for scroll-targetable elements. */
+export declare const SCROLL_TARGET_ATTRIBUTE = "data-scroll-target";
+/** Attribute set on elements during hover interactions. */
+export declare const HOVER_STATE_ATTRIBUTE = "data-hover";
+/** Attribute set on elements during drag interactions. */
+export declare const DRAG_STATE_ATTRIBUTE = "data-dragging";
+/** Build a CSS selector for a cursor target by its ID. */
+export declare function cursorTargetSelector(id: string): string;
+/** Build a CSS selector for a scroll target by its ID. */
+export declare function scrollTargetSelector(id: string): string;
+//# sourceMappingURL=data-attributes.d.ts.map

package/targeting/data-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-attributes.d.ts","sourceRoot":"","sources":["../../src/targeting/data-attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,0DAA0D;AAC1D,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,0DAA0D;AAC1D,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/targeting/data-attributes.js

@@ -0,0 +1,25 @@
+/**
+ * Centralized data-attribute contract for the scenario engine.
+ *
+ * The engine identifies interactive elements in the DOM via these
+ * data attributes. This module is the single source of truth for
+ * attribute names and selector builders — consumers never hard-code
+ * attribute strings.
+ */
+/** Attribute name for cursor-targetable elements. */
+export const CURSOR_TARGET_ATTRIBUTE = "data-cursor-target";
+/** Attribute name for scroll-targetable elements. */
+export const SCROLL_TARGET_ATTRIBUTE = "data-scroll-target";
+/** Attribute set on elements during hover interactions. */
+export const HOVER_STATE_ATTRIBUTE = "data-hover";
+/** Attribute set on elements during drag interactions. */
+export const DRAG_STATE_ATTRIBUTE = "data-dragging";
+/** Build a CSS selector for a cursor target by its ID. */
+export function cursorTargetSelector(id) {
+    return `[${CURSOR_TARGET_ATTRIBUTE}="${id}"]`;
+}
+/** Build a CSS selector for a scroll target by its ID. */
+export function scrollTargetSelector(id) {
+    return `[${SCROLL_TARGET_ATTRIBUTE}="${id}"]`;
+}
+//# sourceMappingURL=data-attributes.js.map

package/targeting/data-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-attributes.js","sourceRoot":"","sources":["../../src/targeting/data-attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE5D,qDAAqD;AACrD,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE5D,2DAA2D;AAC3D,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAElD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,IAAI,uBAAuB,KAAK,EAAE,IAAI,CAAC;AAChD,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,IAAI,uBAAuB,KAAK,EAAE,IAAI,CAAC;AAChD,CAAC"}

package/timeline/compute-step-timeline.d.ts

@@ -0,0 +1,27 @@
+import type { NarrationManifest } from "../narration/types.js";
+/**
+ * Minimal step shape for timeline computation. Accepts any
+ * ScenarioStep<T> without caring about the data payload.
+ */
+interface StepTiming {
+    delayMs: number;
+}
+export interface StepTimeline {
+    /** Start time of each step in milliseconds (index 0 is always 0). */
+    stepStartTimesMs: number[];
+    /** Total playback duration in milliseconds. */
+    totalDurationMs: number;
+}
+/**
+ * Pre-compute step start times and total duration from step definitions
+ * and an optional narration manifest.
+ *
+ * Step N+1 starts after `max(steps[N+1].delayMs, manifest.steps[N].durationMs)` —
+ * whichever is longer, the base delay or the narration clip for the current step.
+ *
+ * Shared between browser ScenarioPlayer (progress bar) and Remotion
+ * video export (frame-based timeline).
+ */
+export declare function computeStepTimeline(steps: readonly StepTiming[], manifest: NarrationManifest | null | undefined): StepTimeline;
+export {};
+//# sourceMappingURL=compute-step-timeline.d.ts.map

package/timeline/compute-step-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-step-timeline.d.ts","sourceRoot":"","sources":["../../src/timeline/compute-step-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;;GAGG;AACH,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAC7C,YAAY,CAed"}

package/timeline/compute-step-timeline.js

@@ -0,0 +1,26 @@
+/** Dwell time on the final step so viewers can absorb the result. */
+const FINAL_DWELL_MS = 3_000;
+/**
+ * Pre-compute step start times and total duration from step definitions
+ * and an optional narration manifest.
+ *
+ * Step N+1 starts after `max(steps[N+1].delayMs, manifest.steps[N].durationMs)` —
+ * whichever is longer, the base delay or the narration clip for the current step.
+ *
+ * Shared between browser ScenarioPlayer (progress bar) and Remotion
+ * video export (frame-based timeline).
+ */
+export function computeStepTimeline(steps, manifest) {
+    const stepStartTimesMs = [0];
+    for (let i = 1; i < steps.length; i++) {
+        const prevStart = stepStartTimesMs[i - 1];
+        const baseDelay = steps[i].delayMs;
+        const narrationMs = manifest?.steps[i - 1]?.durationMs ?? 0;
+        stepStartTimesMs.push(prevStart + Math.max(baseDelay, narrationMs));
+    }
+    const lastStepStart = stepStartTimesMs[stepStartTimesMs.length - 1] ?? 0;
+    const lastNarrationMs = manifest?.steps[steps.length - 1]?.durationMs ?? 0;
+    const totalDurationMs = lastStepStart + Math.max(FINAL_DWELL_MS, lastNarrationMs);
+    return { stepStartTimesMs, totalDurationMs };
+}
+//# sourceMappingURL=compute-step-timeline.js.map

package/timeline/compute-step-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-step-timeline.js","sourceRoot":"","sources":["../../src/timeline/compute-step-timeline.ts"],"names":[],"mappings":"AAUA,qEAAqE;AACrE,MAAM,cAAc,GAAG,KAAK,CAAC;AAS7B;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA4B,EAC5B,QAA8C;IAE9C,MAAM,gBAAgB,GAAa,CAAC,CAAC,CAAC,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;QAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC;QACpC,MAAM,WAAW,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;QAC5D,gBAAgB,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,aAAa,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACzE,MAAM,eAAe,GAAG,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;IAC3E,MAAM,eAAe,GAAG,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IAElF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAC/C,CAAC"}

package/timeline/derive-step.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Find the active step for a given playback time by scanning the
+ * pre-computed step start times in reverse. Returns `0` if the
+ * time precedes all steps.
+ */
+export declare function deriveStepFromTime(currentTimeMs: number, stepStartTimesMs: readonly number[], maxIndex: number): number;
+//# sourceMappingURL=derive-step.d.ts.map

package/timeline/derive-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-step.d.ts","sourceRoot":"","sources":["../../src/timeline/derive-step.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,SAAS,MAAM,EAAE,EACnC,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR"}

package/timeline/derive-step.js

@@ -0,0 +1,13 @@
+/**
+ * Find the active step for a given playback time by scanning the
+ * pre-computed step start times in reverse. Returns `0` if the
+ * time precedes all steps.
+ */
+export function deriveStepFromTime(currentTimeMs, stepStartTimesMs, maxIndex) {
+    for (let i = stepStartTimesMs.length - 1; i >= 0; i--) {
+        if (currentTimeMs >= stepStartTimesMs[i])
+            return Math.min(i, maxIndex);
+    }
+    return 0;
+}
+//# sourceMappingURL=derive-step.js.map

package/timeline/derive-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-step.js","sourceRoot":"","sources":["../../src/timeline/derive-step.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,aAAqB,EACrB,gBAAmC,EACnC,QAAgB;IAEhB,KAAK,IAAI,CAAC,GAAG,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACtD,IAAI,aAAa,IAAI,gBAAgB,CAAC,CAAC,CAAE;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/timeline/step-duration.d.ts

@@ -0,0 +1,12 @@
+import type { NarrationManifest } from "../narration/types.js";
+import type { ScenarioStep } from "../scenario/types.js";
+/**
+ * Compute the effective duration of a step for interaction timing.
+ *
+ * Uses the narration clip duration if available. Falls back to the
+ * next step's `delayMs` (since the next step's delay is the time
+ * until it appears, which equals the current step's screen time).
+ * For the last step, falls back to {@link LAST_STEP_FALLBACK_MS}.
+ */
+export declare function getStepDurationMs<T>(stepIndex: number, manifest: NarrationManifest | undefined, steps: readonly ScenarioStep<T>[]): number;
+//# sourceMappingURL=step-duration.d.ts.map

package/timeline/step-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-duration.d.ts","sourceRoot":"","sources":["../../src/timeline/step-duration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAKzD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,GAChC,MAAM,CAMR"}

package/timeline/step-duration.js

@@ -0,0 +1,18 @@
+/** Fallback duration for the last step when no narration exists. */
+const LAST_STEP_FALLBACK_MS = 3000;
+/**
+ * Compute the effective duration of a step for interaction timing.
+ *
+ * Uses the narration clip duration if available. Falls back to the
+ * next step's `delayMs` (since the next step's delay is the time
+ * until it appears, which equals the current step's screen time).
+ * For the last step, falls back to {@link LAST_STEP_FALLBACK_MS}.
+ */
+export function getStepDurationMs(stepIndex, manifest, steps) {
+    const narrationMs = manifest?.steps[stepIndex]?.durationMs;
+    if (narrationMs != null && narrationMs > 0)
+        return narrationMs;
+    const nextStep = steps[stepIndex + 1];
+    return nextStep ? nextStep.delayMs : LAST_STEP_FALLBACK_MS;
+}
+//# sourceMappingURL=step-duration.js.map

package/timeline/step-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-duration.js","sourceRoot":"","sources":["../../src/timeline/step-duration.ts"],"names":[],"mappings":"AAGA,oEAAoE;AACpE,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,QAAuC,EACvC,KAAiC;IAEjC,MAAM,WAAW,GAAG,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;IAC3D,IAAI,WAAW,IAAI,IAAI,IAAI,WAAW,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC;IAE/D,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC;AAC7D,CAAC"}

package/timing/constants.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared timing constants for the scenario playback engine.
+ *
+ * These values coordinate animation timing between the Cursor component
+ * (visual ripple) and the step-interactions hook (action dispatch).
+ * Both must agree on when the cursor has "arrived" at its target so
+ * the click ripple and the DOM click event fire in sync.
+ */
+/**
+ * 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.
+ */
+export declare const CLICK_DELAY_MS = 450;
+/**
+ * Default milliseconds between characters for the `type` action.
+ *
+ * 50 ms per character = 20 characters/second — fast enough to feel
+ * like confident typing, slow enough that each character is readable
+ * in both browser playback and video export. Overridable per-action
+ * via {@link StepAction.typeDelay}.
+ */
+export declare const TYPE_CHAR_DELAY_MS = 50;
+/**
+ * Default milliseconds to hold the cursor in place during a `hover`
+ * action, between the enter-event dispatch and the leave-event
+ * dispatch.
+ *
+ * 1500 ms gives viewers enough time to read a tooltip or notice a
+ * hover-state change in both browser playback and video export.
+ * Overridable per-action via {@link StepAction.hoverDuration}.
+ */
+export declare const HOVER_HOLD_MS = 1500;
+/**
+ * Milliseconds to pause at the drag source after pressing before
+ * starting the drag movement to the destination.
+ *
+ * 200 ms mimics the brief human hesitation between mousedown and the
+ * start of a deliberate drag gesture.
+ */
+export declare const DRAG_SETTLE_MS = 200;
+/**
+ * Expected milliseconds for the viewport transition spring to settle
+ * after a zoom or pan change.
+ *
+ * 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.
+ */
+export declare const VIEWPORT_SETTLE_MS = 500;
+//# sourceMappingURL=constants.d.ts.map

package/timing/constants.d.ts.map

@@ -0,0 +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"}

package/timing/constants.js

@@ -0,0 +1,55 @@
+/**
+ * Shared timing constants for the scenario playback engine.
+ *
+ * These values coordinate animation timing between the Cursor component
+ * (visual ripple) and the step-interactions hook (action dispatch).
+ * Both must agree on when the cursor has "arrived" at its target so
+ * the click ripple and the DOM click event fire in sync.
+ */
+/**
+ * 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.
+ */
+export const CLICK_DELAY_MS = 450;
+/**
+ * Default milliseconds between characters for the `type` action.
+ *
+ * 50 ms per character = 20 characters/second — fast enough to feel
+ * like confident typing, slow enough that each character is readable
+ * in both browser playback and video export. Overridable per-action
+ * via {@link StepAction.typeDelay}.
+ */
+export const TYPE_CHAR_DELAY_MS = 50;
+/**
+ * Default milliseconds to hold the cursor in place during a `hover`
+ * action, between the enter-event dispatch and the leave-event
+ * dispatch.
+ *
+ * 1500 ms gives viewers enough time to read a tooltip or notice a
+ * hover-state change in both browser playback and video export.
+ * Overridable per-action via {@link StepAction.hoverDuration}.
+ */
+export const HOVER_HOLD_MS = 1500;
+/**
+ * Milliseconds to pause at the drag source after pressing before
+ * starting the drag movement to the destination.
+ *
+ * 200 ms mimics the brief human hesitation between mousedown and the
+ * start of a deliberate drag gesture.
+ */
+export const DRAG_SETTLE_MS = 200;
+/**
+ * Expected milliseconds for the viewport transition spring to settle
+ * after a zoom or pan change.
+ *
+ * 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.
+ */
+export const VIEWPORT_SETTLE_MS = 500;
+//# sourceMappingURL=constants.js.map

package/timing/constants.js.map

@@ -0,0 +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"}

package/viewport/transform.d.ts

@@ -0,0 +1,9 @@
+/** Viewport transform state produced by step interactions. */
+export interface ViewportTransform {
+    scale: number;
+    x: number;
+    y: number;
+}
+/** The identity transform — no zoom, no translation. */
+export declare const VIEWPORT_TRANSFORM_IDENTITY: Readonly<ViewportTransform>;
+//# sourceMappingURL=transform.d.ts.map

package/viewport/transform.d.ts.map

@@ -0,0 +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"}

package/viewport/transform.js

@@ -0,0 +1,7 @@
+/** The identity transform — no zoom, no translation. */
+export const VIEWPORT_TRANSFORM_IDENTITY = {
+    scale: 1,
+    x: 0,
+    y: 0,
+};
+//# sourceMappingURL=transform.js.map

package/viewport/transform.js.map

@@ -0,0 +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"}