@markdy/renderer-dom 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { SceneAST, ParseWarning } from '@markdy/core';
+
 /**
  * @markdy/renderer-dom — Player
  *
@@ -19,10 +21,18 @@
  * each actor's before-phase state falls through to the inline style we set,
  * which gives correct initial positions and opacity values.
  */
+
 interface PlayerOptions {
     container: HTMLElement;
     code: string;
     assets?: Record<string, string>;
+    /**
+     * Host-resolved ASTs for `import "<path>" as <ns>` statements. When
+     * provided, the namespaces' `vars`, `defs`, and `seqs` merge into the
+     * parsed scene under `ns.<name>`. Unresolved namespaces emit a soft
+     * `import-unresolved` warning.
+     */
+    imports?: Record<string, SceneAST>;
     autoplay?: boolean;
     /** Loop the animation when it reaches the end. Defaults to true. */
     loop?: boolean;
@@ -30,6 +40,12 @@ interface PlayerOptions {
     copyright?: boolean;
     /** Show a rainbow progress bar around the viewport border. Defaults to true. */
     progressBar?: boolean;
+    /**
+     * Invoked once per soft `ParseWarning` emitted by the parser — e.g. unknown
+     * actions, unknown modifier keys, unresolved imports. Defaults to `console.warn`.
+     * Pass a no-op to silence; pass a custom collector to surface warnings in a UI.
+     */
+    onWarning?: (warning: ParseWarning) => void;
 }
 interface Player {
     play(): void;

package/dist/index.js

@@ -14,6 +14,9 @@ function stateFrom(def) {
 function tx(s) {
   return `translate(${s.x}px, ${s.y}px) scale(${s.scale}) rotate(${s.rotate}deg)`;
 }
+function txCaption(s) {
+  return `translate(calc(${s.x}px - 50%), calc(${s.y}px - 50%)) scale(${s.scale}) rotate(${s.rotate}deg)`;
+}
 var EASE_MAP = {
   linear: "linear",
   in: "ease-in",
@@ -335,6 +338,31 @@ function createActorEl(name, def, assetDefs, assetOverrides) {
       el = div;
       break;
     }
+    case "caption": {
+      const div = document.createElement("div");
+      div.textContent = def.args[0] ?? "";
+      div.dataset.markdyCaption = def.anchor ?? "top";
+      Object.assign(div.style, {
+        fontSize: `${def.size ?? 32}px`,
+        fontFamily: "system-ui, -apple-system, sans-serif",
+        fontWeight: "700",
+        whiteSpace: "nowrap",
+        textAlign: "center",
+        lineHeight: "1.1",
+        padding: "6px 14px",
+        borderRadius: "4px",
+        background: "rgba(0, 0, 0, 0.55)",
+        color: "#fff",
+        textShadow: "0 2px 6px rgba(0, 0, 0, 0.45)",
+        userSelect: "none",
+        pointerEvents: "none"
+        // Center the caption on its (x, y) point (x = sceneWidth/2).
+        // We combine translate-centering with the actor transform in the
+        // dataset below so the player can re-apply on state changes.
+      });
+      el = div;
+      break;
+    }
     case "figure": {
       el = createFigureEl(def);
       break;
@@ -354,9 +382,10 @@ function createActorEl(name, def, assetDefs, assetOverrides) {
   el.style.left = "0";
   el.style.top = "0";
   el.style.transformOrigin = "center center";
-  el.style.transform = tx(stateFrom(def));
+  el.style.transform = def.type === "caption" ? txCaption(stateFrom(def)) : tx(stateFrom(def));
   el.style.opacity = String(def.opacity ?? 1);
   if (def.z !== void 0) el.style.zIndex = String(def.z);
+  else if (def.type === "caption") el.style.zIndex = "100";
   return el;
 }
 
@@ -380,12 +409,15 @@ function buildAnimations(ast, actorEls, scene, assetOverrides, faceSwaps) {
   for (const [name, def] of Object.entries(ast.actors)) {
     states.set(name, stateFrom(def));
   }
+  const captionActors = /* @__PURE__ */ new Set();
+  for (const [name, def] of Object.entries(ast.actors)) {
+    if (def.type === "caption") captionActors.add(name);
+  }
+  const txFor = (actorName) => captionActors.has(actorName) ? txCaption : tx;
   const events = [...ast.events].sort((a, b) => a.time - b.time);
-  preInitInlineStyles(ast, actorEls, states, events);
+  preInitInlineStyles(ast, actorEls, states, events, txFor);
+  const cameraState = freshCameraState();
   for (const ev of events) {
-    const el = actorEls.get(ev.actor);
-    const s = states.get(ev.actor);
-    if (!el || !s) continue;
     const delayMs = ev.time * 1e3;
     const durMs = Math.max(
       1,
@@ -398,13 +430,39 @@ function buildAnimations(ast, actorEls, scene, assetOverrides, faceSwaps) {
       fill: "forwards",
       easing
     };
-    buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, assetOverrides, faceSwaps, anims);
+    if (ev.actor === "camera") {
+      buildCameraAction(ev, scene, ast, baseOpts, anims, cameraState);
+      continue;
+    }
+    const el = actorEls.get(ev.actor);
+    const s = states.get(ev.actor);
+    if (!el || !s) continue;
+    buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, assetOverrides, faceSwaps, anims, txFor(ev.actor));
   }
   return anims;
 }
-function preInitInlineStyles(ast, actorEls, states, events) {
+function offscreenState(s, direction, sceneWidth, sceneHeight) {
+  const out = { ...s };
+  switch (direction) {
+    case "left":
+      out.x = -sceneWidth * 1.1;
+      break;
+    case "right":
+      out.x = sceneWidth * 2.1;
+      break;
+    case "top":
+      out.y = -sceneHeight * 1.1;
+      break;
+    case "bottom":
+      out.y = sceneHeight * 2.1;
+      break;
+  }
+  return out;
+}
+function preInitInlineStyles(ast, actorEls, states, events, txFor) {
   const firstEventByActor = /* @__PURE__ */ new Map();
   for (const ev of events) {
+    if (ev.actor === "camera") continue;
     if (!firstEventByActor.has(ev.actor)) firstEventByActor.set(ev.actor, ev);
   }
   for (const [name, def] of Object.entries(ast.actors)) {
@@ -412,31 +470,78 @@ function preInitInlineStyles(ast, actorEls, states, events) {
     const s = states.get(name);
     if (!el || !s) continue;
     const firstEv = firstEventByActor.get(name);
+    const txFn = txFor(name);
     if (firstEv?.action === "enter") {
       const from = String(firstEv.params.from ?? "left");
-      const offscreen = { ...s };
-      switch (from) {
-        case "left":
-          offscreen.x = -ast.meta.width * 1.1;
-          break;
-        case "right":
-          offscreen.x = ast.meta.width * 2.1;
-          break;
-        case "top":
-          offscreen.y = -ast.meta.height * 1.1;
-          break;
-        case "bottom":
-          offscreen.y = ast.meta.height * 2.1;
-          break;
-      }
-      el.style.transform = tx(offscreen);
+      const offscreen = offscreenState(s, from, ast.meta.width, ast.meta.height);
+      el.style.transform = txFn(offscreen);
     }
     if (firstEv?.action === "fade_in" && (def.opacity === void 0 || def.opacity > 0)) {
       el.style.opacity = "0";
     }
   }
 }
-function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, assetOverrides, faceSwaps, anims) {
+function freshCameraState() {
+  return { x: 0, y: 0, zoom: 1 };
+}
+function cameraTx(s) {
+  return `translate(${-s.x}px, ${-s.y}px) scale(${s.zoom})`;
+}
+function buildCameraAction(ev, scene, ast, baseOpts, anims, cameraState) {
+  const s = cameraState;
+  switch (ev.action) {
+    case "pan": {
+      const to = ev.params.to;
+      if (!to) break;
+      const sceneW = ast.meta.width;
+      const sceneH = ast.meta.height;
+      const targetX = to[0] - sceneW / 2;
+      const targetY = to[1] - sceneH / 2;
+      const next = { ...s, x: targetX, y: targetY };
+      anims.push(
+        scene.animate(
+          [{ transform: cameraTx(s) }, { transform: cameraTx(next) }],
+          baseOpts
+        )
+      );
+      s.x = next.x;
+      s.y = next.y;
+      break;
+    }
+    case "zoom": {
+      const to = typeof ev.params.to === "number" ? ev.params.to : s.zoom;
+      const next = { ...s, zoom: to };
+      anims.push(
+        scene.animate(
+          [{ transform: cameraTx(s) }, { transform: cameraTx(next) }],
+          baseOpts
+        )
+      );
+      s.zoom = next.zoom;
+      break;
+    }
+    case "shake": {
+      const mag = typeof ev.params.intensity === "number" ? ev.params.intensity : 8;
+      anims.push(
+        scene.animate(
+          [
+            { transform: cameraTx(s), offset: 0 },
+            { transform: cameraTx({ ...s, x: s.x - mag, y: s.y - mag * 0.4 }), offset: 0.15 },
+            { transform: cameraTx({ ...s, x: s.x + mag, y: s.y + mag * 0.4 }), offset: 0.35 },
+            { transform: cameraTx({ ...s, x: s.x - mag * 0.6, y: s.y + mag * 0.3 }), offset: 0.55 },
+            { transform: cameraTx({ ...s, x: s.x + mag * 0.5, y: s.y - mag * 0.3 }), offset: 0.75 },
+            { transform: cameraTx(s), offset: 1 }
+          ],
+          { ...baseOpts, easing: "linear" }
+        )
+      );
+      break;
+    }
+    default:
+      break;
+  }
+}
+function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, assetOverrides, faceSwaps, anims, txFn) {
   switch (ev.action) {
     // ── move ────────────────────────────────────────────────────────────────
     case "move": {
@@ -445,7 +550,7 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
       const toY = toArr?.[1] ?? s.y;
       anims.push(
         el.animate(
-          [{ transform: tx(s) }, { transform: tx({ ...s, x: toX, y: toY }) }],
+          [{ transform: txFn(s) }, { transform: txFn({ ...s, x: toX, y: toY }) }],
           baseOpts
         )
       );
@@ -454,29 +559,45 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
       break;
     }
     // ── enter ───────────────────────────────────────────────────────────────
+    // Slides the actor from the given screen edge into its current (s)
+    // position while also restoring opacity to 1. The opacity restore makes
+    // `enter` symmetric with `exit` so actors can re-enter after exiting
+    // without needing a separate fade_in.
     case "enter": {
       const from = String(ev.params.from ?? "left");
-      const fromState = { ...s };
-      switch (from) {
-        case "left":
-          fromState.x = -ast.meta.width;
-          break;
-        case "right":
-          fromState.x = ast.meta.width * 2;
-          break;
-        case "top":
-          fromState.y = -ast.meta.height;
-          break;
-        case "bottom":
-          fromState.y = ast.meta.height * 2;
-          break;
-      }
+      const fromState = offscreenState(s, from, ast.meta.width, ast.meta.height);
       anims.push(
         el.animate(
-          [{ transform: tx(fromState) }, { transform: tx(s) }],
+          [
+            { transform: txFn(fromState), opacity: s.opacity },
+            { transform: txFn(s), opacity: 1 }
+          ],
+          baseOpts
+        )
+      );
+      s.opacity = 1;
+      break;
+    }
+    // ── exit ────────────────────────────────────────────────────────────────
+    // Mirror of enter: slides off-screen in the given direction while also
+    // fading opacity to 0. Universal — works on any actor type (caption, text,
+    // figure, box, sprite). Leaves `s` at the off-screen state since the
+    // actor is conceptually gone after this.
+    case "exit": {
+      const to = String(ev.params.to ?? "right");
+      const toState = offscreenState(s, to, ast.meta.width, ast.meta.height);
+      anims.push(
+        el.animate(
+          [
+            { transform: txFn(s), opacity: s.opacity },
+            { transform: txFn(toState), opacity: 0 }
+          ],
           baseOpts
         )
       );
+      s.x = toState.x;
+      s.y = toState.y;
+      s.opacity = 0;
       break;
     }
     // ── fade_in ─────────────────────────────────────────────────────────────
@@ -498,7 +619,7 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
       const toScale = typeof ev.params.to === "number" ? ev.params.to : s.scale;
       anims.push(
         el.animate(
-          [{ transform: tx(s) }, { transform: tx({ ...s, scale: toScale }) }],
+          [{ transform: txFn(s) }, { transform: txFn({ ...s, scale: toScale }) }],
           baseOpts
         )
       );
@@ -510,7 +631,7 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
       const toDeg = typeof ev.params.to === "number" ? ev.params.to : s.rotate;
       anims.push(
         el.animate(
-          [{ transform: tx(s) }, { transform: tx({ ...s, rotate: toDeg }) }],
+          [{ transform: txFn(s) }, { transform: txFn({ ...s, rotate: toDeg }) }],
           baseOpts
         )
       );
@@ -523,12 +644,12 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
       anims.push(
         el.animate(
           [
-            { transform: tx(s), offset: 0 },
-            { transform: tx({ ...s, x: s.x + mag }), offset: 0.2 },
-            { transform: tx({ ...s, x: s.x - mag }), offset: 0.4 },
-            { transform: tx({ ...s, x: s.x + mag }), offset: 0.6 },
-            { transform: tx({ ...s, x: s.x - mag }), offset: 0.8 },
-            { transform: tx(s), offset: 1 }
+            { transform: txFn(s), offset: 0 },
+            { transform: txFn({ ...s, x: s.x + mag }), offset: 0.2 },
+            { transform: txFn({ ...s, x: s.x - mag }), offset: 0.4 },
+            { transform: txFn({ ...s, x: s.x + mag }), offset: 0.6 },
+            { transform: txFn({ ...s, x: s.x - mag }), offset: 0.8 },
+            { transform: txFn(s), offset: 1 }
           ],
           { ...baseOpts, easing: "linear" }
         )
@@ -739,12 +860,12 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
       anims.push(
         el.animate(
           [
-            { transform: tx(s), offset: 0 },
-            { transform: tx({ ...s, scale: s.scale * 0.9 }), offset: 0.1 },
-            { transform: tx({ ...s, y: s.y - jHeight, scale: s.scale * 1.1 }), offset: 0.45 },
-            { transform: tx({ ...s, y: s.y - jHeight * 0.3, scale: s.scale * 1.05 }), offset: 0.7 },
-            { transform: tx({ ...s, scale: s.scale * 0.92 }), offset: 0.88 },
-            { transform: tx(s), offset: 1 }
+            { transform: txFn(s), offset: 0 },
+            { transform: txFn({ ...s, scale: s.scale * 0.9 }), offset: 0.1 },
+            { transform: txFn({ ...s, y: s.y - jHeight, scale: s.scale * 1.1 }), offset: 0.45 },
+            { transform: txFn({ ...s, y: s.y - jHeight * 0.3, scale: s.scale * 1.05 }), offset: 0.7 },
+            { transform: txFn({ ...s, scale: s.scale * 0.92 }), offset: 0.88 },
+            { transform: txFn(s), offset: 1 }
           ],
           { ...baseOpts, easing: "ease-in-out" }
         )
@@ -779,24 +900,24 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
     case "bounce": {
       const bIntensity = typeof ev.params.intensity === "number" ? ev.params.intensity : 15;
       const bCount = typeof ev.params.count === "number" ? ev.params.count : 3;
-      const keyframes = [{ transform: tx(s), offset: 0 }];
+      const keyframes = [{ transform: txFn(s), offset: 0 }];
       for (let bi = 0; bi < bCount; bi++) {
         const amp = bIntensity * Math.pow(0.55, bi);
         const baseOffset = (bi + 0.5) / (bCount + 0.5);
         const peakOffset = Math.min(baseOffset, 0.98);
         const valleyOffset = Math.min(baseOffset + 0.25 / (bCount + 0.5), 0.99);
         keyframes.push({
-          transform: tx({ ...s, y: s.y - amp }),
+          transform: txFn({ ...s, y: s.y - amp }),
           offset: peakOffset
         });
         if (bi < bCount - 1) {
           keyframes.push({
-            transform: tx(s),
+            transform: txFn(s),
             offset: valleyOffset
           });
         }
       }
-      keyframes.push({ transform: tx(s), offset: 1 });
+      keyframes.push({ transform: txFn(s), offset: 1 });
       anims.push(
         el.animate(keyframes, { ...baseOpts, easing: "ease-out" })
       );
@@ -872,9 +993,20 @@ function bgToTextColor(bg) {
   return named[bg.toLowerCase()] ?? "#1a1a1a";
 }
 function createPlayer(opts) {
-  const { container, code, assets: assetOverrides = {}, autoplay = true, loop = true, copyright = true, progressBar = true } = opts;
-  const ast = parse(code);
+  const {
+    container,
+    code,
+    assets: assetOverrides = {},
+    imports,
+    autoplay = true,
+    loop = true,
+    copyright = true,
+    progressBar = true,
+    onWarning = (w) => console.warn(`[markdy] line ${w.line}: ${w.message} (${w.kind})`)
+  } = opts;
+  const ast = parse(code, imports ? { imports } : void 0);
   const totalDurationMs = (ast.meta.duration ?? 0) * 1e3;
+  for (const w of ast.warnings) onWarning(w);
   const viewport = document.createElement("div");
   Object.assign(viewport.style, {
     position: "relative",
@@ -953,6 +1085,17 @@ function createPlayer(opts) {
     transformOrigin: "0 0"
   });
   viewport.appendChild(scene);
+  const sceneContent = document.createElement("div");
+  Object.assign(sceneContent.style, {
+    position: "absolute",
+    top: "0",
+    left: "0",
+    width: "100%",
+    height: "100%",
+    transformOrigin: "50% 50%",
+    willChange: "transform"
+  });
+  scene.appendChild(sceneContent);
   function scaleScene() {
     const s = viewport.clientWidth / ast.meta.width;
     scene.style.transform = `scale(${s})`;
@@ -963,11 +1106,11 @@ function createPlayer(opts) {
   const actorEls = /* @__PURE__ */ new Map();
   for (const [name, def] of Object.entries(ast.actors)) {
     const el = createActorEl(name, def, ast.assets, assetOverrides);
-    scene.appendChild(el);
+    sceneContent.appendChild(el);
     actorEls.set(name, el);
   }
   const faceSwaps = [];
-  const allAnims = buildAnimations(ast, actorEls, scene, assetOverrides, faceSwaps);
+  const allAnims = buildAnimations(ast, actorEls, sceneContent, assetOverrides, faceSwaps);
   faceSwaps.sort((a, b) => a.timeMs - b.timeMs);
   for (const anim of allAnims) {
     anim.pause();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdy/renderer-dom",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Web Animations API renderer for MarkdyScript scenes.",
   "license": "MIT",
   "type": "module",
@@ -43,15 +43,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@markdy/core": "0.6.0"
+    "@markdy/core": "0.7.1"
   },
   "devDependencies": {
+    "jsdom": "^26.0.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
   }
 }