@scenar/core 0.8.0 → 0.9.1

package/index.d.ts

@@ -10,6 +10,8 @@ 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 type { ScenarioShot } from "./timeline/collect-shots.js";
+export { SHOT_NAME_PATTERN, collectScenarioShots, collectShotNames, } from "./timeline/collect-shots.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";

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,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"}
+{"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;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAGrC,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

@@ -5,6 +5,7 @@ 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";
+export { SHOT_NAME_PATTERN, collectScenarioShots, collectShotNames, } from "./timeline/collect-shots.js";
 // Timing constants
 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

package/index.js.map

@@ -1 +1 @@
-{"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"}
+{"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,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAErC,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.8.0",
+  "version": "0.9.1",
   "description": "Pure TypeScript types, timing, and utilities for the Scenar scenario engine.",
   "license": "Apache-2.0",
   "type": "module",

package/scenario/types.d.ts

@@ -29,5 +29,21 @@ export interface ScenarioStep<T> {
      * share the same atPercent, they fire in array order.
      */
     readonly interactions?: readonly StepAction[];
+    /**
+     * Names this step as a still-capture point for `scenar shoot`.
+     *
+     * The capture happens at the step's settled *end* — after every
+     * interaction (and its tail: click dispatch, per-char typing, camera
+     * tween) has fired — so a shot-bearing step's duration must fit its
+     * interaction tails.
+     *
+     * Shots are addressed by this name, never by step index, so inserting a
+     * beat into a scenario never renumbers existing docs references. Names
+     * must be unique within a scenario and kebab-case
+     * (`^[a-z0-9]+(-[a-z0-9]+)*$`) — each becomes a filename
+     * (`stills/<shot>.<theme>.png`) and a URL segment in the deployed
+     * bundle. Steps without a `shot` are simply walked through.
+     */
+    readonly shot?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/scenario/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC/C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/src/index.ts

@@ -31,6 +31,12 @@ 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 type { ScenarioShot } from "./timeline/collect-shots.js";
+export {
+  SHOT_NAME_PATTERN,
+  collectScenarioShots,
+  collectShotNames,
+} from "./timeline/collect-shots.js";
 
 // Timing constants
 export {

package/src/scenario/types.ts

@@ -31,4 +31,20 @@ export interface ScenarioStep<T> {
    * share the same atPercent, they fire in array order.
    */
   readonly interactions?: readonly StepAction[];
+  /**
+   * Names this step as a still-capture point for `scenar shoot`.
+   *
+   * The capture happens at the step's settled *end* — after every
+   * interaction (and its tail: click dispatch, per-char typing, camera
+   * tween) has fired — so a shot-bearing step's duration must fit its
+   * interaction tails.
+   *
+   * Shots are addressed by this name, never by step index, so inserting a
+   * beat into a scenario never renumbers existing docs references. Names
+   * must be unique within a scenario and kebab-case
+   * (`^[a-z0-9]+(-[a-z0-9]+)*$`) — each becomes a filename
+   * (`stills/<shot>.<theme>.png`) and a URL segment in the deployed
+   * bundle. Steps without a `shot` are simply walked through.
+   */
+  readonly shot?: string;
 }

package/src/timeline/collect-shots.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import { computeStepTimeline } from "./compute-step-timeline.js";
+import { SHOT_NAME_PATTERN, collectScenarioShots, collectShotNames } from "./collect-shots.js";
+
+describe("collectScenarioShots", () => {
+  it("resolves each shot to the settled end of its step", () => {
+    const steps = [
+      { delayMs: 0, shot: "opening" },
+      { delayMs: 1000 },
+      { delayMs: 2000, shot: "detail-open" },
+    ];
+    const timeline = computeStepTimeline(steps, null);
+    // Starts: [0, 1000, 3000]; total: 3000 + 3000 (final dwell).
+    expect(collectScenarioShots(steps, timeline)).toEqual([
+      { name: "opening", timeMs: 999, stepIndex: 0 },
+      { name: "detail-open", timeMs: 5999, stepIndex: 2 },
+    ]);
+  });
+
+  it("places a final-step shot inside the final dwell", () => {
+    const steps = [{ delayMs: 0 }, { delayMs: 500, shot: "finale" }];
+    const timeline = computeStepTimeline(steps, null);
+    expect(collectScenarioShots(steps, timeline)).toEqual([
+      { name: "finale", timeMs: timeline.totalDurationMs - 1, stepIndex: 1 },
+    ]);
+  });
+
+  it("resolves shot times against narration-driven step durations", () => {
+    const steps = [{ delayMs: 0, shot: "narrated" }, { delayMs: 500 }];
+    const timeline = computeStepTimeline(steps, {
+      steps: [{ src: "a.mp3", durationMs: 4000 }, null],
+    });
+    // Step 1 starts at max(500, 4000) = 4000; the shot lands just before it.
+    expect(collectScenarioShots(steps, timeline)).toEqual([
+      { name: "narrated", timeMs: 3999, stepIndex: 0 },
+    ]);
+  });
+
+  it("returns an empty list when no step declares a shot", () => {
+    const steps = [{ delayMs: 0 }, { delayMs: 1000 }];
+    expect(collectScenarioShots(steps, computeStepTimeline(steps, null))).toEqual([]);
+  });
+
+  it("rejects a non-kebab-case name, naming the step", () => {
+    const steps = [{ delayMs: 0 }, { delayMs: 100, shot: "Detail_Open" }];
+    expect(() =>
+      collectScenarioShots(steps, computeStepTimeline(steps, null)),
+    ).toThrowError(/step 1 declares shot "Detail_Open"/);
+  });
+
+  it.each(["-leading", "trailing-", "double--dash", "UPPER", "with.dot", "with space", ""])(
+    'rejects invalid shot name "%s"',
+    (name) => {
+      const steps = [{ delayMs: 0, shot: name }];
+      expect(() =>
+        collectScenarioShots(steps, computeStepTimeline(steps, null)),
+      ).toThrowError(/not kebab-case/);
+    },
+  );
+
+  it.each(["a", "shot-1", "agent-detail", "step2-open"])(
+    'accepts valid shot name "%s"',
+    (name) => {
+      expect(SHOT_NAME_PATTERN.test(name)).toBe(true);
+    },
+  );
+
+  it("rejects duplicate names, naming both steps", () => {
+    const steps = [
+      { delayMs: 0, shot: "opening" },
+      { delayMs: 100 },
+      { delayMs: 100, shot: "opening" },
+    ];
+    expect(() =>
+      collectScenarioShots(steps, computeStepTimeline(steps, null)),
+    ).toThrowError(/steps 0 and 2 both declare shot "opening"/);
+  });
+});
+
+describe("collectShotNames", () => {
+  it("returns the declared names in step order, without needing a timeline", () => {
+    const steps = [
+      { delayMs: 0, shot: "opening" },
+      { delayMs: 1000 },
+      { delayMs: 2000, shot: "detail-open" },
+    ];
+    expect(collectShotNames(steps)).toEqual(["opening", "detail-open"]);
+  });
+
+  it("returns an empty list when no step declares a shot", () => {
+    expect(collectShotNames([{ delayMs: 0 }, { delayMs: 1000 }])).toEqual([]);
+  });
+
+  it("throws the same validation errors as collectScenarioShots", () => {
+    expect(() => collectShotNames([{ delayMs: 0, shot: "Not_Kebab" }])).toThrowError(
+      /not kebab-case/,
+    );
+    expect(() =>
+      collectShotNames([
+        { delayMs: 0, shot: "opening" },
+        { delayMs: 100, shot: "opening" },
+      ]),
+    ).toThrowError(/steps 0 and 1 both declare shot "opening"/);
+  });
+
+  it("agrees with collectScenarioShots on every valid scenario (shared walk)", () => {
+    const steps = [
+      { delayMs: 0, shot: "opening" },
+      { delayMs: 500 },
+      { delayMs: 700, shot: "midway" },
+      { delayMs: 300, shot: "finale" },
+    ];
+    const resolved = collectScenarioShots(steps, computeStepTimeline(steps, null));
+    expect(collectShotNames(steps)).toEqual(resolved.map((shot) => shot.name));
+  });
+});

package/src/timeline/collect-shots.ts

@@ -0,0 +1,114 @@
+import type { StepTimeline } from "./compute-step-timeline.js";
+
+/**
+ * Minimal step shape for shot collection. Accepts any ScenarioStep<T>
+ * without caring about the data payload.
+ */
+interface StepWithShot {
+  delayMs: number;
+  shot?: string;
+}
+
+/** A named still-capture point resolved to its position on the timeline. */
+export interface ScenarioShot {
+  /** The step's declared `shot` name (validated kebab-case, unique). */
+  readonly name: string;
+  /**
+   * The capture time: the step's settled end. For step i this is
+   * `stepStartTimesMs[i + 1] - 1`; for the final step it is
+   * `totalDurationMs - 1`, which already includes the final dwell (or the
+   * final narration clip, whichever is longer).
+   */
+  readonly timeMs: number;
+  /** Index of the step that declared the shot. */
+  readonly stepIndex: number;
+}
+
+/**
+ * The shape a `shot` name must have. Each name becomes a filename
+ * (`stills/<shot>.<theme>.png`) and a URL segment in the deployed bundle,
+ * so the charset is deliberately the strict kebab-case subset of what the
+ * deploy path contract admits.
+ */
+export const SHOT_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * Walk the steps and validate every declared `shot`, returning name +
+ * declaring index in step order — the single validation pass behind both
+ * {@link collectShotNames} and {@link collectScenarioShots}, so a name
+ * that passes one can never fail the other.
+ *
+ * Throws on the two authoring mistakes that must never reach a deployed
+ * bundle: a name that cannot be a clean filename/URL segment, and a
+ * duplicate name (shots are addressed by name, never by index — a
+ * collision would silently overwrite a still). Error messages name the
+ * offending step index so the fix is local.
+ */
+function collectDeclaredShots(
+  steps: readonly StepWithShot[],
+): Array<{ name: string; stepIndex: number }> {
+  const declared: Array<{ name: string; stepIndex: number }> = [];
+  const seen = new Map<string, number>();
+
+  for (let i = 0; i < steps.length; i++) {
+    const name = steps[i]?.shot;
+    if (name === undefined) continue;
+
+    if (!SHOT_NAME_PATTERN.test(name)) {
+      throw new Error(
+        `step ${i} declares shot "${name}", which is not kebab-case ` +
+          `(expected ${SHOT_NAME_PATTERN}); it becomes a filename and a URL segment`,
+      );
+    }
+    const firstIndex = seen.get(name);
+    if (firstIndex !== undefined) {
+      throw new Error(
+        `steps ${firstIndex} and ${i} both declare shot "${name}"; ` +
+          `shot names must be unique within a scenario`,
+      );
+    }
+    seen.set(name, i);
+    declared.push({ name, stepIndex: i });
+  }
+
+  return declared;
+}
+
+/**
+ * The validated shot names declared by a scenario, in step order —
+ * everything about a scenario's shots that is knowable without a
+ * timeline. `scenar pack` records this list in the bundle's
+ * scenario.json so tooling can learn a bundle's shots (or that it has
+ * none) without booting a browser.
+ *
+ * Throws on the same authoring mistakes as {@link collectScenarioShots};
+ * see {@link collectDeclaredShots}.
+ */
+export function collectShotNames(steps: readonly StepWithShot[]): string[] {
+  return collectDeclaredShots(steps).map((shot) => shot.name);
+}
+
+/**
+ * Resolve every `shot`-bearing step to its named capture point, in
+ * timeline order.
+ *
+ * Validation (and the errors it throws) is shared with
+ * {@link collectShotNames}; see {@link collectDeclaredShots}.
+ *
+ * The `timeline` must be computed from the same steps (and the same
+ * narration manifest) the capture will walk — shot times are meaningless
+ * against any other timeline.
+ */
+export function collectScenarioShots(
+  steps: readonly StepWithShot[],
+  timeline: StepTimeline,
+): ScenarioShot[] {
+  return collectDeclaredShots(steps).map(({ name, stepIndex }) => {
+    const nextStartMs = timeline.stepStartTimesMs[stepIndex + 1];
+    return {
+      name,
+      timeMs: (nextStartMs ?? timeline.totalDurationMs) - 1,
+      stepIndex,
+    };
+  });
+}

package/timeline/collect-shots.d.ts

@@ -0,0 +1,55 @@
+import type { StepTimeline } from "./compute-step-timeline.js";
+/**
+ * Minimal step shape for shot collection. Accepts any ScenarioStep<T>
+ * without caring about the data payload.
+ */
+interface StepWithShot {
+    delayMs: number;
+    shot?: string;
+}
+/** A named still-capture point resolved to its position on the timeline. */
+export interface ScenarioShot {
+    /** The step's declared `shot` name (validated kebab-case, unique). */
+    readonly name: string;
+    /**
+     * The capture time: the step's settled end. For step i this is
+     * `stepStartTimesMs[i + 1] - 1`; for the final step it is
+     * `totalDurationMs - 1`, which already includes the final dwell (or the
+     * final narration clip, whichever is longer).
+     */
+    readonly timeMs: number;
+    /** Index of the step that declared the shot. */
+    readonly stepIndex: number;
+}
+/**
+ * The shape a `shot` name must have. Each name becomes a filename
+ * (`stills/<shot>.<theme>.png`) and a URL segment in the deployed bundle,
+ * so the charset is deliberately the strict kebab-case subset of what the
+ * deploy path contract admits.
+ */
+export declare const SHOT_NAME_PATTERN: RegExp;
+/**
+ * The validated shot names declared by a scenario, in step order —
+ * everything about a scenario's shots that is knowable without a
+ * timeline. `scenar pack` records this list in the bundle's
+ * scenario.json so tooling can learn a bundle's shots (or that it has
+ * none) without booting a browser.
+ *
+ * Throws on the same authoring mistakes as {@link collectScenarioShots};
+ * see {@link collectDeclaredShots}.
+ */
+export declare function collectShotNames(steps: readonly StepWithShot[]): string[];
+/**
+ * Resolve every `shot`-bearing step to its named capture point, in
+ * timeline order.
+ *
+ * Validation (and the errors it throws) is shared with
+ * {@link collectShotNames}; see {@link collectDeclaredShots}.
+ *
+ * The `timeline` must be computed from the same steps (and the same
+ * narration manifest) the capture will walk — shot times are meaningless
+ * against any other timeline.
+ */
+export declare function collectScenarioShots(steps: readonly StepWithShot[], timeline: StepTimeline): ScenarioShot[];
+export {};
+//# sourceMappingURL=collect-shots.d.ts.map

package/timeline/collect-shots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-shots.d.ts","sourceRoot":"","sources":["../../src/timeline/collect-shots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D;;;GAGG;AACH,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAA6B,CAAC;AA4C5D;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,EAAE,CAEzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,QAAQ,EAAE,YAAY,GACrB,YAAY,EAAE,CAShB"}

package/timeline/collect-shots.js

@@ -0,0 +1,75 @@
+/**
+ * The shape a `shot` name must have. Each name becomes a filename
+ * (`stills/<shot>.<theme>.png`) and a URL segment in the deployed bundle,
+ * so the charset is deliberately the strict kebab-case subset of what the
+ * deploy path contract admits.
+ */
+export const SHOT_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * Walk the steps and validate every declared `shot`, returning name +
+ * declaring index in step order — the single validation pass behind both
+ * {@link collectShotNames} and {@link collectScenarioShots}, so a name
+ * that passes one can never fail the other.
+ *
+ * Throws on the two authoring mistakes that must never reach a deployed
+ * bundle: a name that cannot be a clean filename/URL segment, and a
+ * duplicate name (shots are addressed by name, never by index — a
+ * collision would silently overwrite a still). Error messages name the
+ * offending step index so the fix is local.
+ */
+function collectDeclaredShots(steps) {
+    const declared = [];
+    const seen = new Map();
+    for (let i = 0; i < steps.length; i++) {
+        const name = steps[i]?.shot;
+        if (name === undefined)
+            continue;
+        if (!SHOT_NAME_PATTERN.test(name)) {
+            throw new Error(`step ${i} declares shot "${name}", which is not kebab-case ` +
+                `(expected ${SHOT_NAME_PATTERN}); it becomes a filename and a URL segment`);
+        }
+        const firstIndex = seen.get(name);
+        if (firstIndex !== undefined) {
+            throw new Error(`steps ${firstIndex} and ${i} both declare shot "${name}"; ` +
+                `shot names must be unique within a scenario`);
+        }
+        seen.set(name, i);
+        declared.push({ name, stepIndex: i });
+    }
+    return declared;
+}
+/**
+ * The validated shot names declared by a scenario, in step order —
+ * everything about a scenario's shots that is knowable without a
+ * timeline. `scenar pack` records this list in the bundle's
+ * scenario.json so tooling can learn a bundle's shots (or that it has
+ * none) without booting a browser.
+ *
+ * Throws on the same authoring mistakes as {@link collectScenarioShots};
+ * see {@link collectDeclaredShots}.
+ */
+export function collectShotNames(steps) {
+    return collectDeclaredShots(steps).map((shot) => shot.name);
+}
+/**
+ * Resolve every `shot`-bearing step to its named capture point, in
+ * timeline order.
+ *
+ * Validation (and the errors it throws) is shared with
+ * {@link collectShotNames}; see {@link collectDeclaredShots}.
+ *
+ * The `timeline` must be computed from the same steps (and the same
+ * narration manifest) the capture will walk — shot times are meaningless
+ * against any other timeline.
+ */
+export function collectScenarioShots(steps, timeline) {
+    return collectDeclaredShots(steps).map(({ name, stepIndex }) => {
+        const nextStartMs = timeline.stepStartTimesMs[stepIndex + 1];
+        return {
+            name,
+            timeMs: (nextStartMs ?? timeline.totalDurationMs) - 1,
+            stepIndex,
+        };
+    });
+}
+//# sourceMappingURL=collect-shots.js.map

package/timeline/collect-shots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-shots.js","sourceRoot":"","sources":["../../src/timeline/collect-shots.ts"],"names":[],"mappings":"AA0BA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,SAAS,oBAAoB,CAC3B,KAA8B;IAE9B,MAAM,QAAQ,GAA+C,EAAE,CAAC;IAChE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;QAC5B,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS;QAEjC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,QAAQ,CAAC,mBAAmB,IAAI,6BAA6B;gBAC3D,aAAa,iBAAiB,4CAA4C,CAC7E,CAAC;QACJ,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,SAAS,UAAU,QAAQ,CAAC,uBAAuB,IAAI,KAAK;gBAC1D,6CAA6C,CAChD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA8B;IAC7D,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAA8B,EAC9B,QAAsB;IAEtB,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE;QAC7D,MAAM,WAAW,GAAG,QAAQ,CAAC,gBAAgB,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QAC7D,OAAO;YACL,IAAI;YACJ,MAAM,EAAE,CAAC,WAAW,IAAI,QAAQ,CAAC,eAAe,CAAC,GAAG,CAAC;YACrD,SAAS;SACV,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}