@markdy/renderer-dom 0.7.24 → 0.7.26

package/README.md

@@ -70,6 +70,9 @@ player.destroy();    // clean up DOM + cancel animations
 | `loop` | `boolean` | `true` | Loop the animation when it reaches the end |
 | `copyright` | `boolean` | `true` | Show a small "Powered by Markdy" badge below the animation |
 | `progressBar` | `boolean` | `true` | Show a rainbow progress bar around the viewport border |
+| `onWarning` | `(warning: ParseWarning) => void` | `console.warn` | Called for each soft parse warning |
+| `onTimeUpdate` | `(seconds: number, durationSeconds: number) => void` | — | Called whenever playback or seek changes the current time |
+| `onPlayStateChange` | `(playing: boolean) => void` | — | Called when playback starts or pauses |
 
 ### `Player`
 
@@ -78,20 +81,50 @@ player.destroy();    // clean up DOM + cancel animations
 | `play()` | Start or resume playback |
 | `pause()` | Pause at current position |
 | `seek(seconds)` | Jump to a specific time |
+| `currentTime()` | Current playback position in seconds |
+| `duration()` | Total scene duration in seconds |
+| `isPlaying()` | Whether the scene is currently playing |
+| `chapters()` | Named `scene "..." { ... }` chapter blocks, in author order (empty if none) |
+| `seekToChapter(name)` | Seek to the start of a named chapter; no-op if the name doesn't match |
 | `destroy()` | Remove DOM elements and cancel all animations |
 
 ## Module Structure
 
 ```
 src/
-  types.ts        — ActorState, FaceSwap, easing utilities
-  figure.ts       — Stick-figure DOM factory (emoji body parts)
-  actors.ts       — Actor element factory (sprite, text, figure, box)
-  animations.ts   — Timeline → WAAPI Animation builder
-  player.ts       — Public API, rAF loop, face-swap engine
   index.ts        — Barrel exports
+  player.ts       — Public API, rAF loop, face-swap engine
+  animations.ts   — Timeline walker: dispatches each event to its handler
+  actions/
+    context.ts    — ActionContext: the one argument every handler receives
+    registry.ts   — Action name → handler table
+    transform.ts  — move, enter, exit, fade, scale, rotate, shake, jump, bounce
+    figure.ts     — Figure-only gestures and limb articulation
+    speech.ts     — say (speech bubbles)
+    projectile.ts — throw
+    flow.ts       — request / response / emit (system-diagram edges)
+  geometry/
+    rect.ts       — Actor bounds and hit-testing (DOM-free, unit tested)
+    path.ts       — Polyline measurement and obstacle-aware edge routing
+  camera.ts       — pan / zoom / shake on the scene-content layer
+  stage.ts        — t=0 staging and off-screen placement
+  theme.ts        — Scene-adaptive colors for renderer-drawn chrome
+  actors.ts       — Actor element factory (sprite, text, figure, box, caption)
+  figure.ts       — Stick-figure DOM factory (emoji body parts)
+  types.ts        — ActorState, FaceSwap, easing utilities
 ```
 
+### Adding an action
+
+1. Write a handler — a function taking `ActionContext` — in the relevant
+   `actions/` module (or a new one).
+2. Register it by name in `actions/registry.ts`.
+3. Add the name to the matching list in `@markdy/core`'s `registry.ts` so the
+   parser accepts it.
+
+Step 3 is enforced: `tests/action-coverage.test.ts` fails the build if the
+parser accepts an action the renderer can't draw, or vice versa.
+
 ## Documentation
 
 - **[Syntax Reference](../../docs/SYNTAX.md)** — complete DSL language spec

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SceneAST, ParseWarning } from '@markdy/core';
+import { Chapter, SceneAST, ParseWarning } from '@markdy/core';
 
 /**
  * @markdy/renderer-dom — Player
@@ -46,11 +46,22 @@ interface PlayerOptions {
      * Pass a no-op to silence; pass a custom collector to surface warnings in a UI.
      */
     onWarning?: (warning: ParseWarning) => void;
+    /** Invoked whenever playback or seek changes the current timeline time. */
+    onTimeUpdate?: (seconds: number, durationSeconds: number) => void;
+    /** Invoked when playback starts or pauses. */
+    onPlayStateChange?: (playing: boolean) => void;
 }
 interface Player {
     play(): void;
     pause(): void;
     seek(seconds: number): void;
+    currentTime(): number;
+    duration(): number;
+    isPlaying(): boolean;
+    /** Named `scene "..." { ... }` chapter blocks, in author order. Empty when the scene has none. */
+    chapters(): Chapter[];
+    /** Seeks to the start of the named chapter. No-op if the name doesn't match a chapter. */
+    seekToChapter(name: string): void;
     destroy(): void;
 }
 declare function createPlayer(opts: PlayerOptions): Player;