@markdy/renderer-dom 0.7.23 → 0.7.25

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,6 +81,11 @@ 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

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;

package/dist/index.js

@@ -21,10 +21,20 @@ var EASE_MAP = {
   linear: "linear",
   in: "ease-in",
   out: "ease-out",
-  inout: "ease-in-out"
+  inout: "ease-in-out",
+  // Named cubic-bezier presets for authors who want a more polished feel
+  // than the four raw CSS keywords above without hand-writing a curve.
+  smooth: "cubic-bezier(0.4, 0, 0.2, 1)",
+  snappy: "cubic-bezier(0.16, 1, 0.3, 1)",
+  overshoot: "cubic-bezier(0.34, 1.56, 0.64, 1)",
+  sharp: "cubic-bezier(0.4, 0, 1, 1)"
 };
+var CUBIC_BEZIER_RE = /^cubic-bezier\(\s*-?\d*\.?\d+\s*,\s*-?\d*\.?\d+\s*,\s*-?\d*\.?\d+\s*,\s*-?\d*\.?\d+\s*\)$/;
 function toEasing(val) {
-  return EASE_MAP[String(val ?? "")] ?? "linear";
+  const str = String(val ?? "");
+  if (EASE_MAP[str]) return EASE_MAP[str];
+  if (CUBIC_BEZIER_RE.test(str)) return str;
+  return "linear";
 }
 
 // src/figure.ts
@@ -450,6 +460,12 @@ function createActorEl(name, def, assetDefs, assetOverrides) {
 }
 
 // src/animations.ts
+var DEFAULT_EASE_BY_ACTION = {
+  enter: "out",
+  fade_in: "out",
+  exit: "in",
+  fade_out: "in"
+};
 function isSceneDark(scene) {
   const bg = scene.style.background || "white";
   let hex = bg.trim().replace(/^#/, "");
@@ -483,7 +499,7 @@ function buildAnimations(ast, actorEls, scene, assetOverrides, faceSwaps) {
       1,
       (typeof ev.params.dur === "number" ? ev.params.dur : 0.5) * 1e3
     );
-    const easing = toEasing(ev.params.ease);
+    const easing = toEasing(ev.params.ease ?? DEFAULT_EASE_BY_ACTION[ev.action]);
     const baseOpts = {
       delay: delayMs,
       duration: durMs,
@@ -1328,10 +1344,13 @@ function createPlayer(opts) {
     loop = true,
     copyright = true,
     progressBar = true,
-    onWarning = (w) => console.warn(`[markdy] line ${w.line}: ${w.message} (${w.kind})`)
+    onWarning = (w) => console.warn(`[markdy] line ${w.line}: ${w.message} (${w.kind})`),
+    onTimeUpdate,
+    onPlayStateChange
   } = opts;
   const ast = parse(code, imports ? { imports } : void 0);
   const totalDurationMs = (ast.meta.duration ?? 0) * 1e3;
+  const durationSeconds = totalDurationMs / 1e3;
   for (const w of ast.warnings) onWarning(w);
   const viewport = document.createElement("div");
   Object.assign(viewport.style, {
@@ -1456,6 +1475,7 @@ function createPlayer(opts) {
       anim.currentTime = sceneMs;
     }
     applyFaceSwaps();
+    onTimeUpdate?.(sceneMs / 1e3, durationSeconds);
   }
   function applyFaceSwaps() {
     if (faceSwaps.length === 0) return;
@@ -1489,6 +1509,7 @@ function createPlayer(opts) {
         sceneMs = totalDurationMs;
         applyCurrentTime();
         isPlaying = false;
+        onPlayStateChange?.(false);
         lastRafTs = null;
         rafId = null;
         return;
@@ -1502,12 +1523,14 @@ function createPlayer(opts) {
     play() {
       if (isPlaying) return;
       isPlaying = true;
+      onPlayStateChange?.(true);
       lastRafTs = null;
       rafId = requestAnimationFrame(rafTick);
     },
     pause() {
       if (!isPlaying) return;
       isPlaying = false;
+      onPlayStateChange?.(false);
       if (rafId !== null) {
         cancelAnimationFrame(rafId);
         rafId = null;
@@ -1515,10 +1538,28 @@ function createPlayer(opts) {
       lastRafTs = null;
     },
     seek(seconds) {
-      sceneMs = seconds * 1e3;
+      const nextMs = seconds * 1e3;
+      sceneMs = totalDurationMs > 0 ? Math.min(Math.max(nextMs, 0), totalDurationMs) : Math.max(nextMs, 0);
       applyCurrentTime();
       if (totalDurationMs > 0) updateProgressBar(sceneMs / totalDurationMs);
     },
+    currentTime() {
+      return sceneMs / 1e3;
+    },
+    duration() {
+      return durationSeconds;
+    },
+    isPlaying() {
+      return isPlaying;
+    },
+    chapters() {
+      return ast.chapters;
+    },
+    seekToChapter(name) {
+      const chapter = ast.chapters.find((c) => c.name === name);
+      if (!chapter) return;
+      player.seek(chapter.startTime);
+    },
     destroy() {
       player.pause();
       for (const anim of allAnims) anim.cancel();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdy/renderer-dom",
-  "version": "0.7.23",
+  "version": "0.7.25",
   "description": "Web Animations API renderer for MarkdyScript scenes.",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@markdy/core": "0.7.23"
+    "@markdy/core": "0.7.25"
   },
   "devDependencies": {
     "jsdom": "^29.1.1",