storyink 0.3.0 → 0.3.2

package/dist/core/index.js

@@ -1,6 +1,7 @@
-import"../chunks/index-8fbs7b39.js";
+import"../chunks/index-ygm89806.js";
 import {
   ARROWS,
+  CAMERA,
   DIAGRAM_TYPES,
   DIRECTIONS,
   EDGE_STYLES,
@@ -8,26 +9,38 @@ import {
   GRAPH_NODE_KINDS,
   MESSAGE_KINDS,
   PARTICIPANT_KINDS,
+  STEP_BEAT,
+  STORY_MOTIONS,
   StoryinkError,
   VERSION,
   animatedHeaderHeight,
   animatedSvg,
   autoStory,
   beatTimes,
+  cameraAt,
+  cameraAtEnd,
+  centreOn,
+  clampCamera,
   compileStory,
   counterValue,
+  deadZoneRect,
   detectMermaid,
   elbowPath,
   elbowPathV,
   exports_tokens,
+  fitCamera,
+  fitIsReadable,
+  followStep,
   fontCss,
   formatDiagnostic,
   fromMermaid,
+  inView,
   isSequence,
   layout,
   parseHash,
   pinnedCss,
   readTime,
+  readableScale,
   renderAnimatedSvg,
   renderHtml,
   renderSvg,
@@ -36,15 +49,23 @@ import {
   roundedPolyline,
   simplify,
   simplifyError,
+  stepAt,
+  stepFocus,
+  steppedIndex,
+  steppedSchedule,
+  steppedStop,
+  steppedTime,
   storyState,
   textWidth,
   toScene,
+  toScreen,
   validate,
   wirePath,
   wrap
-} from "../chunks/index-060cd52n.js";
+} from "../chunks/index-n3gf4fyb.js";
 export {
   ARROWS,
+  CAMERA,
   DIAGRAM_TYPES,
   DIRECTIONS,
   EDGE_STYLES,
@@ -52,25 +73,37 @@ export {
   GRAPH_NODE_KINDS,
   MESSAGE_KINDS,
   PARTICIPANT_KINDS,
+  STEP_BEAT,
+  STORY_MOTIONS,
   StoryinkError,
   VERSION,
   animatedHeaderHeight,
   animatedSvg,
   autoStory,
   beatTimes,
+  cameraAt,
+  cameraAtEnd,
+  centreOn,
+  clampCamera,
   compileStory,
   counterValue,
+  deadZoneRect,
   detectMermaid,
   elbowPath,
   elbowPathV,
+  fitCamera,
+  fitIsReadable,
+  followStep,
   fontCss,
   formatDiagnostic,
   fromMermaid,
+  inView,
   isSequence,
   layout,
   parseHash,
   pinnedCss,
   readTime,
+  readableScale,
   renderAnimatedSvg,
   renderHtml,
   renderSvg,
@@ -79,9 +112,16 @@ export {
   roundedPolyline,
   simplify,
   simplifyError,
+  stepAt,
+  stepFocus,
+  steppedIndex,
+  steppedSchedule,
+  steppedStop,
+  steppedTime,
   storyState,
   textWidth,
   toScene,
+  toScreen,
   exports_tokens as tokens,
   validate,
   wirePath,

package/dist/index.js

@@ -1,14 +1,17 @@
-import"./chunks/index-8fbs7b39.js";
+import"./chunks/index-ygm89806.js";
 import {
   findBrowser,
   loadSpec,
   parseSource,
+  setStoryCamera,
+  setStoryMotion,
   snapshot,
   writeAnimatedSvg,
   writeDiagram
-} from "./chunks/index-zjyrjkn6.js";
+} from "./chunks/index-5qmjsg8w.js";
 import {
   ARROWS,
+  CAMERA,
   DIAGRAM_TYPES,
   DIRECTIONS,
   EDGE_STYLES,
@@ -16,26 +19,38 @@ import {
   GRAPH_NODE_KINDS,
   MESSAGE_KINDS,
   PARTICIPANT_KINDS,
+  STEP_BEAT,
+  STORY_MOTIONS,
   StoryinkError,
   VERSION,
   animatedHeaderHeight,
   animatedSvg,
   autoStory,
   beatTimes,
+  cameraAt,
+  cameraAtEnd,
+  centreOn,
+  clampCamera,
   compileStory,
   counterValue,
+  deadZoneRect,
   detectMermaid,
   elbowPath,
   elbowPathV,
   exports_tokens,
+  fitCamera,
+  fitIsReadable,
+  followStep,
   fontCss,
   formatDiagnostic,
   fromMermaid,
+  inView,
   isSequence,
   layout,
   parseHash,
   pinnedCss,
   readTime,
+  readableScale,
   renderAnimatedSvg,
   renderHtml,
   renderSvg,
@@ -44,13 +59,20 @@ import {
   roundedPolyline,
   simplify,
   simplifyError,
+  stepAt,
+  stepFocus,
+  steppedIndex,
+  steppedSchedule,
+  steppedStop,
+  steppedTime,
   storyState,
   textWidth,
   toScene,
+  toScreen,
   validate,
   wirePath,
   wrap
-} from "./chunks/index-060cd52n.js";
+} from "./chunks/index-n3gf4fyb.js";
 // src/plugin.ts
 import fs2 from "node:fs";
 import path2 from "node:path";
@@ -154,6 +176,16 @@ var plugin = {
             svg: { type: "string", description: "Optional output .svg path" },
             theme: { ...THEME, description: "Pin the theme; default follows the viewer's system preference" },
             story: { type: "string", enum: ["auto"], description: "Add an auto-generated storyboard (only when the user asked for an animated diagram)" },
+            motion: {
+              type: "string",
+              enum: ["full", "reduced", "system"],
+              description: `Story playback motion: "full" (default, animates even when the reader's OS reduces motion), "reduced" (step by step), "system" (follow prefers-reduced-motion)`
+            },
+            camera: {
+              type: "string",
+              enum: ["follow", "fit"],
+              description: 'Viewer camera while playing: "follow" (default: zoom to a readable scale when the diagram is large and pan to each step) or "fit" (whole diagram always in view)'
+            },
             animatedSvg: {
               type: ["boolean", "string"],
               enum: [true, false, "both"],
@@ -174,6 +206,10 @@ var plugin = {
           const s = specFrom(i);
           if (s.ok && s.spec && i.story === "auto" && s.spec.story === undefined)
             s.spec.story = "auto";
+          if (s.ok && s.spec && i.motion)
+            setStoryMotion(s.spec, i.motion);
+          if (s.ok && s.spec && i.camera)
+            setStoryCamera(s.spec, i.camera);
           if (!s.ok || !s.spec)
             return {
               content: `storyink: spec is invalid, nothing written.
@@ -281,6 +317,8 @@ ${summarize(s.diagnostics)}`,
               enum: ["overview", "full", "none"],
               description: 'Inline image: "overview" (default: one compact image; beat sheets reflow into more columns), "full" (normal sheet layout, split into ≤ 3 downscaled parts when tall), "none" (paths only)'
             },
+            motion: { type: "string", enum: ["full", "reduced"], description: 'Motion mode for `at` frames: "reduced" = stepped playback (settled step states)' },
+            camera: { type: "string", enum: ["fit", "follow"], description: '`at` frames: "fit" (default, whole diagram) or "follow" (the follow camera\'s view at a 1280×720 stage)' },
             maxImageSize: { type: "number", description: "Longest side of the returned image in px (default 1024, 256–2048)" }
           },
           required: ["html"],
@@ -295,6 +333,8 @@ ${summarize(s.diagnostics)}`,
             ...i.at ? { at: i.at.map((x) => x === "end" ? "end" : Number(x)) } : {},
             sheet: i.sheet === "none" ? false : i.sheet === "beats" ? "beats" : true,
             ...i.themes ? { themes: i.themes } : {},
+            ...i.motion ? { motion: i.motion } : {},
+            ...i.camera === "follow" ? { camera: "follow" } : {},
             ...i.width ? { width: i.width } : {},
             ...i.outDir ? { outDir: abs(i.outDir) } : {},
             signal: context.signal
@@ -323,6 +363,7 @@ ${summarize(s.diagnostics)}`,
 var plugin_default = plugin;
 export {
   ARROWS,
+  CAMERA,
   DIAGRAM_TYPES,
   DIRECTIONS,
   EDGE_STYLES,
@@ -331,22 +372,33 @@ export {
   MESSAGE_KINDS,
   PARTICIPANT_KINDS,
   PLUGIN_ID,
+  STEP_BEAT,
+  STORY_MOTIONS,
   StoryinkError,
   VERSION,
   animatedHeaderHeight,
   animatedSvg,
   autoStory,
   beatTimes,
+  cameraAt,
+  cameraAtEnd,
+  centreOn,
+  clampCamera,
   compileStory,
   counterValue,
+  deadZoneRect,
   plugin_default as default,
   detectMermaid,
   elbowPath,
   elbowPathV,
   findBrowser,
+  fitCamera,
+  fitIsReadable,
+  followStep,
   fontCss,
   formatDiagnostic,
   fromMermaid,
+  inView,
   isSequence,
   layout,
   loadSpec,
@@ -354,6 +406,7 @@ export {
   parseSource,
   pinnedCss,
   readTime,
+  readableScale,
   renderAnimatedSvg,
   renderHtml,
   renderSvg,
@@ -363,9 +416,16 @@ export {
   simplify,
   simplifyError,
   snapshot,
+  stepAt,
+  stepFocus,
+  steppedIndex,
+  steppedSchedule,
+  steppedStop,
+  steppedTime,
   storyState,
   textWidth,
   toScene,
+  toScreen,
   exports_tokens as tokens,
   validate,
   wirePath,

package/dist/node/index.js

@@ -5,11 +5,13 @@ import {
   parseSource,
   pictureSnippet,
   screenshotPage,
+  setStoryCamera,
+  setStoryMotion,
   snapshot,
   writeAnimatedSvg,
   writeDiagram
-} from "../chunks/index-zjyrjkn6.js";
-import"../chunks/index-060cd52n.js";
+} from "../chunks/index-5qmjsg8w.js";
+import"../chunks/index-n3gf4fyb.js";
 export {
   browserVersion,
   findBrowser,
@@ -17,6 +19,8 @@ export {
   parseSource,
   pictureSnippet,
   screenshotPage,
+  setStoryCamera,
+  setStoryMotion,
   snapshot,
   writeAnimatedSvg,
   writeDiagram

package/dist/types/core/index.d.ts

@@ -10,7 +10,8 @@ export { renderSvg, renderHtml, toScene, fontCss, StoryinkError, type SvgOptions
 export { parseHash, type HashParams } from "./render/App.js";
 export * as tokens from "../theme/tokens.js";
 export { VERSION } from "../generated/meta.js";
-export { storyState, restFrame, beatTimes, counterValue, type StateOptions } from "./story/state.js";
+export { storyState, restFrame, beatTimes, counterValue, steppedSchedule, steppedIndex, steppedStop, steppedTime, STEP_BEAT, type StateOptions, type SteppedStop } from "./story/state.js";
+export { CAMERA, cameraAt, cameraAtEnd, centreOn, clampCamera, deadZoneRect, fitCamera, fitIsReadable, followStep, inView, readableScale, stepAt, stepFocus, toScreen, type Camera, type Viewport } from "./story/camera.js";
 export { compileStory, resolveEdge, readTime, type CompileResult } from "./story/compile.js";
 export { autoStory } from "./story/auto.js";
 export type { Timeline, TimelineStep, TimelinePulse, TimelineGlow, TimelineDraw, PulseFrame, GlowFrame, Frame as StoryFrame } from "./story/types.js";

package/dist/types/core/render/App.d.ts

@@ -27,8 +27,35 @@ export interface HashParams {
     /** Beat sheet layout: fixed column count and a tile range (for compact previews). */
     cols?: number;
     range?: [number, number];
+    /** `#camera=follow|fit`: follow the story (also places a `#t=` frame) or keep the whole diagram in view. */
+    camera?: "follow" | "fit";
 }
 export declare function parseHash(hash: string): HashParams;
+/**
+ * Effective motion mode. Precedence: `#motion=` hash, then the reader's stored toolbar choice
+ * (`localStorage["storyink-motion"]`), then the author's `story.motion` (default "full"). The OS
+ * `prefers-reduced-motion` is consulted only when the author chose "system".
+ */
+export declare function resolveMotion(o: {
+    hash?: "full" | "reduced";
+    stored?: string | null;
+    author?: "full" | "reduced" | "system";
+    system: boolean;
+}): "full" | "reduced";
+export declare const MOTION_KEY = "storyink-motion";
+export declare const FOLLOW_KEY = "storyink-follow";
+/**
+ * Whether the camera follows the story. Precedence: `#camera=` hash, then the reader's stored
+ * toolbar choice (`localStorage["storyink-follow"]` = "on" | "off"), then the author's
+ * `story.camera` (default "follow").
+ */
+export declare function resolveFollow(o: {
+    hash?: "follow" | "fit";
+    stored?: string | null;
+    author?: "follow" | "fit";
+}): boolean;
+/** Pointerdown targets that never start a pan (controls inside the stage). */
+export declare const NO_PAN = "button, input, select, textarea, a, [role=slider], .si-tools, .si-transport, .si-gate, [data-no-pan]";
 /** Viewer shell. Server-rendered with defaults, then hydrated; hash state applies after hydration. */
 export declare function App({ scene, hooks }: AppProps & {
     hooks?: ViewerHooks;

package/dist/types/core/render/Story.d.ts

@@ -35,8 +35,9 @@ export interface StoryOptions {
  */
 export declare function useStory(scene: Scene, tl: Timeline | undefined, opts: StoryOptions): StoryControls | undefined;
 /** The click-to-play gate (STYLE.md §6): dimmed t = 0 frame, centred play triangle, idle rings. */
-export declare function Gate({ onPlay }: {
+export declare function Gate({ onPlay, still }: {
     onPlay: () => void;
+    still?: boolean;
 }): ReactElement;
 /** Play/pause, replay, scrubber with step and chapter ticks. */
 export declare function Transport({ c, tl }: {

package/dist/types/core/spec.d.ts

@@ -90,8 +90,24 @@ export interface Story {
     autoplay?: boolean;
     /** "hold" (default) the final frame, or "loop". */
     end?: "hold" | "loop";
-    steps: StoryStep[];
+    /**
+     * Playback motion (default "full"): "full" always animates, "reduced" always plays step by
+     * step, "system" follows the reader's `prefers-reduced-motion`. The reader's toolbar choice
+     * and `#motion=` still win.
+     */
+    motion?: StoryMotion;
+    /**
+     * Viewer camera while playing (default "follow"): "follow" zooms to a readable scale when the
+     * fit view is too small and pans to each step; "fit" keeps the whole diagram in view. The
+     * reader's Follow toggle and `#camera=` still win.
+     */
+    camera?: StoryCamera;
+    /** Steps, or "auto" to derive them (like `"story": "auto"`, with the options above). */
+    steps: StoryStep[] | "auto";
 }
+export type StoryMotion = "full" | "reduced" | "system";
+export type StoryCamera = "follow" | "fit";
+export declare const STORY_MOTIONS: readonly ["full", "reduced", "system"];
 export interface GraphGroup {
     id: string;
     label?: string;

package/dist/types/core/story/camera.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The follow camera: pure geometry. Where each story step happens (`stepFocus`) and where the
+ * viewer's camera sits for it (`followStep`, `cameraAt`). No DOM, no wall time: the viewer, the
+ * snapshot `#camera=follow` capture and the tests all evaluate the same functions.
+ *
+ * Camera convention (the viewer's `.si-canvas` transform): a diagram point p is drawn on screen at
+ * `x + (p.x - viewBox.x) * k`, `y + (p.y - viewBox.y) * k`.
+ */
+import type { Box, Scene } from "../scene.js";
+import type { Timeline } from "./types.js";
+export interface Camera {
+    k: number;
+    x: number;
+    y: number;
+}
+/** The stage in CSS px. `bottom` is reserved for overlaid chrome (transport, toolbar). */
+export interface Viewport {
+    w: number;
+    h: number;
+    bottom?: number;
+}
+export declare const CAMERA: {
+    /** Node label size in diagram px. */
+    readonly label: 11;
+    /** Fit is readable when labels render at least this large on screen. */
+    readonly minLabel: 10;
+    /** Target on-screen label size when fit is too small. */
+    readonly readableLabel: 12.5;
+    /** Never zoom in past this for readability. */
+    readonly maxK: 2;
+    /** Fit padding (matches the viewer's Fit button). */
+    readonly fitPad: 32;
+    /** Padding around a step's focus, diagram px. */
+    readonly focusPad: 24;
+    /** Follow only when the focus leaves the inner share of the viewport. */
+    readonly deadZone: 0.8;
+    /** Keep this much page margin at the diagram's edges when clamping, CSS px. */
+    readonly edge: 24;
+    /** Camera move: bounce-free spring (STYLE.md: content springs have no bounce). */
+    readonly spring: {
+        readonly type: "spring";
+        readonly bounce: 0;
+        readonly visualDuration: 0.75;
+    };
+};
+/** The whole diagram in view (identical to the viewer's Fit, snapped for pixel-stable captures). */
+export declare function fitCamera(vb: Box, vp: Viewport): Camera;
+/** Fit when its labels are readable (≥ 10 px on screen); otherwise the scale for ~12.5 px labels (capped). */
+export declare function readableScale(vb: Box, vp: Viewport): number;
+/** Whether fit already renders labels readably. */
+export declare const fitIsReadable: (vb: Box, vp: Viewport) => boolean;
+/** Index of the step in effect at `t` (the last one started; 0 before the first). */
+export declare function stepAt(tl: Timeline, t: number): number;
+/**
+ * Bounding box (diagram px, padded) of everything step i animates: reveals, pulse routes, drawn
+ * wires, highlights and arrival glows, counter nodes (captions point at those same elements).
+ * Undefined when the step touches nothing on the diagram (a caption-only step).
+ */
+export declare function stepFocus(scene: Scene, tl: Timeline, i: number, pad?: number): Box | undefined;
+/** A diagram box on screen under `cam`. */
+export declare function toScreen(cam: Camera, vb: Box, b: Box): Box;
+/** The inner `deadZone` share of the usable viewport, CSS px. */
+export declare function deadZoneRect(vp: Viewport, dz?: number): Box;
+/** True when `focus` (diagram px) sits inside the dead zone under `cam`. */
+export declare function inView(cam: Camera, vb: Box, vp: Viewport, focus: Box, dz?: number): boolean;
+/** Keep the diagram covering the viewport where it can (no panning into empty page), whole pixels. */
+export declare function clampCamera(cam: Camera, vb: Box, vp: Viewport): Camera;
+/** Centre `focus` at scale k (clamped to the diagram). */
+export declare function centreOn(vb: Box, vp: Viewport, focus: Box, k: number): Camera;
+/**
+ * One follow move. The scale is the base (readable or the user's zoom), reduced only as far as
+ * needed for the focus to fit the dead zone. Inside the dead zone at that scale: stay. Otherwise
+ * centre on the focus (clamped to the diagram edges). A camera zoomed out for an earlier, larger
+ * focus zooms back to the base when the focus allows it.
+ */
+export declare function followStep(cam: Camera, vb: Box, vp: Viewport, focus: Box | undefined, base?: number, dz?: number): Camera;
+/** True once every event has settled: the camera shows the whole diagram again. */
+export declare const cameraAtEnd: (tl: Timeline, t: number) => boolean;
+/**
+ * Where the follow camera sits at story time t for a viewport and base scale (default: readable).
+ * Pure: plays the dead-zone moves forward from fit through step 0..i, so a capture at t equals the uninterrupted
+ * live camera. After the last event it is fit.
+ */
+export declare function cameraAt(scene: Scene, tl: Timeline, t: number, vp: Viewport, k?: number): Camera;

package/dist/types/core/story/state.d.ts

@@ -3,6 +3,12 @@ import type { Frame, Timeline } from "./types.js";
 export interface StateOptions {
     /** Reduced motion: springs become steps, no pulses or glows. */
     reduced?: boolean;
+    /**
+     * Stepped playback (implies `reduced`): `t` names the step in effect (see `steppedTime`) and
+     * the frame is that step's settled state: its pulses have landed (wires drawn), while
+     * reveals, counters and captions of later steps have not begun.
+     */
+    stepped?: boolean;
 }
 /** The resting frame: everything shown, nothing moving. Equals the static diagram. */
 export declare function restFrame(t?: number): Frame;
@@ -34,3 +40,29 @@ export declare function beatTimes(tl: Timeline, max?: number): Beat[];
 export declare function beatCaption(tl: Timeline, frame: Frame, beat: Beat): string | undefined;
 /** Minimum beat-tile width for a diagram (wide diagrams get fewer, larger tiles). */
 export declare const beatTileMin: (w: number) => number;
+/** Reduced-motion hold for a step without a caption (STYLE.md: a beat of ~1.2–1.8 s). */
+export declare const STEP_BEAT = 1.5;
+/** One stop of stepped (reduced-motion) playback: the settled time of a step and how long it holds. */
+export interface SteppedStop {
+    /** Step index (-1 = before the story, `steps.length` = the final frame). */
+    step: number;
+    /** Story time whose reduced frame is this step's settled state. */
+    t: number;
+    /** Seconds to hold before advancing (0 for the final frame). */
+    hold: number;
+}
+/**
+ * Stepped playback schedule (reduced motion, "Play steps"): each step shown
+ * settled (its reveals, draws, counters and caption applied at once) for its
+ * reading time, then the final frame. Pure data: the same for every run.
+ */
+export declare function steppedSchedule(tl: Timeline): SteppedStop[];
+/** Index into `steppedSchedule` of the step in effect at `t` (-1 before the first step starts). */
+export declare function steppedIndex(tl: Timeline, t: number): number;
+/** Position in `steppedSchedule` of the stop in effect at `t` (-1 before the first step). */
+export declare function steppedStop(tl: Timeline, t: number): number;
+/**
+ * Quantise any `t` to the settled time of the step in effect (reduced motion).
+ * Before the first step: 0. At or after the end: the duration (final frame).
+ */
+export declare function steppedTime(tl: Timeline, t: number): number;

package/dist/types/core/story/types.d.ts

@@ -55,6 +55,10 @@ export interface Timeline {
     duration: number;
     lastEvent: number;
     autoplay: boolean;
+    /** Author's playback motion ("full" default; "system" follows prefers-reduced-motion). */
+    motion: "full" | "reduced" | "system";
+    /** Author's viewer camera ("follow" default). */
+    camera?: "follow" | "fit";
     loop: boolean;
     steps: TimelineStep[];
     /** Element id → time it is revealed. Absent = visible from t = 0. */

package/dist/types/generated/meta.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.3.2";