@markdy/renderer-dom 0.5.8 → 0.7.0

package/README.md

@@ -5,10 +5,12 @@ Web Animations API renderer for [MarkdyScript](../../docs/SYNTAX.md) scenes. Tra
 ## Features
 
 - **Browser-native** — Web Animations API + CSS transforms, no Canvas or GSAP
-- **Emoji stick figures** — `figure` actor type with articulatable limbs (punch, kick, rotate_part)
+- **Emoji stick figures** — `figure` actor type with articulatable limbs, shoulder/hip joints, and body-part rig
+- **Expressive gestures** — built-in `wave`, `nod`, `jump`, `bounce`, and multi-part `pose` actions
 - **Seek-safe** — manual `currentTime` control enables reliable `seek()` in any direction
 - **Face expressions** — instant emoji face swaps that work correctly on seek-back
 - **Speech bubbles** — auto-positioned bubbles with fade-in/fade-out
+- **Z-index layering** — `z` modifier for actor depth ordering
 - **Single dependency** — only `@markdy/core`
 
 ## Installation

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",
@@ -29,7 +32,7 @@ function createFigureEl(def) {
   const skinColor = def.args[0] || "#ffdbac";
   const isFemale = def.args[1] === "f";
   const startFace = def.args[2] || (isFemale ? "\u{1F642}" : "\u{1F636}");
-  const ink = "#2a2a2a";
+  const ink = "currentColor";
   const WRAP_W = 80;
   const FACE_FS = 40;
   const SHIRT_FS = isFemale ? 48 : 44;
@@ -39,6 +42,7 @@ function createFigureEl(def) {
   const shY = Math.round(SHIRT_FS * 0.28);
   const ARM_W = 36, ARM_H = 22;
   const LEG_H = 54, LEG_STICK_H = 34;
+  const JOINT_SIZE = 6;
   const wrap = document.createElement("div");
   Object.assign(wrap.style, {
     position: "relative",
@@ -62,13 +66,13 @@ function createFigureEl(def) {
   });
   const neck = document.createElement("div");
   Object.assign(neck.style, {
-    width: "8px",
-    height: "8px",
+    width: "10px",
+    height: "10px",
     background: skinColor,
-    borderRadius: "3px",
+    borderRadius: "4px",
     flexShrink: "0",
-    marginTop: "-2px",
-    marginBottom: "-2px",
+    marginTop: "-3px",
+    marginBottom: "-3px",
     zIndex: "4"
   });
   const shirtRow = document.createElement("div");
@@ -91,6 +95,12 @@ function createFigureEl(def) {
     pointerEvents: "none"
   });
   shirtRow.appendChild(torso);
+  const shoulderL = buildJoint("left", skinColor, JOINT_SIZE, shLx, shY, WRAP_W);
+  const shoulderR = buildJoint("right", skinColor, JOINT_SIZE, shRx, shY, WRAP_W);
+  shoulderL.dataset.figShoulderL = "";
+  shoulderR.dataset.figShoulderR = "";
+  shirtRow.appendChild(shoulderL);
+  shirtRow.appendChild(shoulderR);
   const armHandEmoji = isFemale ? "\u{1F485}" : "\u{1F91C}";
   shirtRow.appendChild(
     buildArm("left", armHandEmoji, skinColor, {
@@ -112,21 +122,57 @@ function createFigureEl(def) {
       flipFist: false
     })
   );
+  const hipRow = document.createElement("div");
+  Object.assign(hipRow.style, {
+    position: "relative",
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    flexShrink: "0",
+    overflow: "visible"
+  });
+  const hipBridge = document.createElement("div");
+  Object.assign(hipBridge.style, {
+    width: "28px",
+    height: "4px",
+    background: skinColor,
+    borderRadius: "2px",
+    marginBottom: "1px",
+    zIndex: "3"
+  });
+  hipRow.appendChild(hipBridge);
   const legsRow = document.createElement("div");
   Object.assign(legsRow.style, {
     display: "flex",
     justifyContent: "center",
     gap: "10px",
     flexShrink: "0",
-    overflow: "visible"
+    overflow: "visible",
+    position: "relative"
   });
-  legsRow.append(
-    buildLeg(true, isFemale, ink, LEG_H, LEG_STICK_H),
-    buildLeg(false, isFemale, ink, LEG_H, LEG_STICK_H)
-  );
-  wrap.append(faceEl, neck, shirtRow, legsRow);
+  const legL = buildLeg(true, isFemale, ink, skinColor, LEG_H, LEG_STICK_H, JOINT_SIZE);
+  const legR = buildLeg(false, isFemale, ink, skinColor, LEG_H, LEG_STICK_H, JOINT_SIZE);
+  legsRow.append(legL, legR);
+  hipRow.appendChild(legsRow);
+  wrap.append(faceEl, neck, shirtRow, hipRow);
   return wrap;
 }
+function buildJoint(side, skinColor, size, anchorX, anchorY, wrapW) {
+  const joint = document.createElement("div");
+  const isLeft = side === "left";
+  Object.assign(joint.style, {
+    position: "absolute",
+    width: `${size}px`,
+    height: `${size}px`,
+    borderRadius: "50%",
+    background: skinColor,
+    ...isLeft ? { right: `${wrapW - anchorX - size / 2}px` } : { left: `${anchorX - size / 2}px` },
+    top: `${anchorY - size / 2}px`,
+    zIndex: "5",
+    pointerEvents: "none"
+  });
+  return joint;
+}
 function buildArm(side, handEmoji, skinColor, g) {
   const arm = document.createElement("div");
   const ds = arm.dataset;
@@ -150,7 +196,7 @@ function buildArm(side, handEmoji, skinColor, g) {
     ...isLeft ? { right: "5px" } : { left: "5px" },
     top: `${g.h / 2 - 2}px`,
     width: "18px",
-    height: "3px",
+    height: "4px",
     background: skinColor,
     borderRadius: "2px"
   });
@@ -169,7 +215,7 @@ function buildArm(side, handEmoji, skinColor, g) {
   arm.append(stick, fist);
   return arm;
 }
-function buildLeg(isLeft, isFemale, ink, legH, stickH) {
+function buildLeg(isLeft, isFemale, ink, skinColor, legH, stickH, jointSize) {
   const leg = document.createElement("div");
   const ds = leg.dataset;
   ds[isLeft ? "figLegL" : "figLegR"] = "";
@@ -181,17 +227,44 @@ function buildLeg(isLeft, isFemale, ink, legH, stickH) {
     transform: "rotate(0deg)",
     overflow: "visible"
   });
+  const hipJoint = document.createElement("div");
+  hipJoint.dataset[isLeft ? "figHipL" : "figHipR"] = "";
+  Object.assign(hipJoint.style, {
+    position: "absolute",
+    width: `${jointSize}px`,
+    height: `${jointSize}px`,
+    borderRadius: "50%",
+    background: skinColor,
+    left: "50%",
+    top: `-${jointSize / 2}px`,
+    transform: "translateX(-50%)",
+    zIndex: "3",
+    pointerEvents: "none"
+  });
   const stick = document.createElement("div");
   Object.assign(stick.style, {
     position: "absolute",
-    width: "3px",
+    width: "4px",
     height: `${stickH}px`,
     background: ink,
-    borderRadius: "1px",
+    borderRadius: "2px",
     left: "50%",
     top: "0",
     transform: "translateX(-50%)"
   });
+  const knee = document.createElement("div");
+  Object.assign(knee.style, {
+    position: "absolute",
+    width: "4px",
+    height: "4px",
+    borderRadius: "50%",
+    background: skinColor,
+    left: "50%",
+    top: `${stickH * 0.55}px`,
+    transform: "translateX(-50%)",
+    zIndex: "2",
+    pointerEvents: "none"
+  });
   const shoe = document.createElement("span");
   shoe.textContent = isFemale ? "\u{1F460}" : "\u{1F45F}";
   Object.assign(shoe.style, {
@@ -208,7 +281,7 @@ function buildLeg(isLeft, isFemale, ink, legH, stickH) {
   } else {
     shoe.style.right = "0";
   }
-  leg.append(stick, shoe);
+  leg.append(hipJoint, stick, knee, shoe);
   return leg;
 }
 var PART_SEL = {
@@ -265,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;
@@ -284,24 +382,42 @@ 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;
 }
 
 // src/animations.ts
+function isSceneDark(scene) {
+  const bg = scene.style.background || "white";
+  let hex = bg.trim().replace(/^#/, "");
+  if (hex.length === 3) hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+  if (hex.length === 6) {
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    return 0.299 * r + 0.587 * g + 0.114 * b <= 140;
+  }
+  const dark = { black: true, "#000": true, "#000000": true };
+  return dark[bg.toLowerCase()] ?? false;
+}
 function buildAnimations(ast, actorEls, scene, assetOverrides, faceSwaps) {
   const anims = [];
   const states = /* @__PURE__ */ new Map();
   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,
@@ -314,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)) {
@@ -328,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": {
@@ -361,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
         )
       );
@@ -370,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 ─────────────────────────────────────────────────────────────
@@ -414,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
         )
       );
@@ -426,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
         )
       );
@@ -439,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" }
         )
@@ -529,6 +734,11 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
     case "say": {
       const text = String(ev.params.text ?? "");
       const inverseScale = 1 / (s.scale || 1);
+      const sceneDark = isSceneDark(scene);
+      const bubbleBg = sceneDark ? "#1e2530" : "white";
+      const bubbleBorder = sceneDark ? "#475569" : "#222";
+      const bubbleText = sceneDark ? "#e2e8f0" : "#222";
+      const bubbleShadow = sceneDark ? "0 2px 8px rgba(0,0,0,0.35)" : "0 2px 8px rgba(0,0,0,0.12)";
       const bubble = document.createElement("div");
       bubble.textContent = text;
       bubble.style.opacity = "0";
@@ -538,9 +748,9 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
         left: "50%",
         transform: `translateX(-50%) scale(${inverseScale})`,
         transformOrigin: "center bottom",
-        background: "white",
-        border: "2px solid #222",
-        color: "#222",
+        background: bubbleBg,
+        border: `2px solid ${bubbleBorder}`,
+        color: bubbleText,
         borderRadius: "12px",
         padding: "6px 14px",
         fontFamily: "system-ui, sans-serif",
@@ -552,7 +762,7 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
         textOverflow: "ellipsis",
         pointerEvents: "none",
         zIndex: "10",
-        boxShadow: "0 2px 8px rgba(0,0,0,0.12)"
+        boxShadow: bubbleShadow
       });
       const tail = document.createElement("span");
       Object.assign(tail.style, {
@@ -564,7 +774,7 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
         height: "0",
         borderLeft: "7px solid transparent",
         borderRight: "7px solid transparent",
-        borderTop: "10px solid #222"
+        borderTop: `10px solid ${bubbleBorder}`
       });
       bubble.appendChild(tail);
       el.style.overflow = "visible";
@@ -584,6 +794,135 @@ function buildAction(ev, el, s, baseOpts, delayMs, durMs, ast, states, scene, as
       );
       break;
     }
+    // ── pose ────────────────────────────────────────────────────────────────
+    // Sets multiple body parts to target angles simultaneously.
+    // Usage: @1.0: hero.pose(arm_left=45, arm_right=-45, leg_left=10, dur=0.4)
+    case "pose": {
+      const poseParts = ["arm_left", "arm_right", "leg_left", "leg_right", "head", "body"];
+      for (const partName of poseParts) {
+        if (typeof ev.params[partName] !== "number") continue;
+        const pSel = PART_SEL[partName];
+        if (!pSel) continue;
+        const pEl = el.querySelector(pSel);
+        if (!pEl) continue;
+        const fromDeg = readRotation(pEl);
+        const toDeg = ev.params[partName];
+        anims.push(
+          pEl.animate(
+            [
+              { transform: `rotate(${fromDeg}deg)` },
+              { transform: `rotate(${toDeg}deg)` }
+            ],
+            { ...baseOpts, fill: "forwards" }
+          )
+        );
+        pEl.style.transform = pEl.style.transform.replace(
+          /rotate\([^)]*\)/,
+          `rotate(${toDeg}deg)`
+        );
+      }
+      break;
+    }
+    // ── wave ────────────────────────────────────────────────────────────────
+    // Built-in wave gesture: raises arm, oscillates, returns.
+    // Usage: @2.0: hero.wave(side=right, dur=0.8)
+    case "wave": {
+      const wSide = String(ev.params.side ?? "right");
+      const wArmEl = el.querySelector(
+        wSide === "left" ? "[data-fig-arm-l]" : "[data-fig-arm-r]"
+      );
+      if (!wArmEl) break;
+      const wRest = readRotation(wArmEl);
+      const wUp = wSide === "left" ? 70 : -70;
+      const wMid1 = wSide === "left" ? 50 : -50;
+      const wMid2 = wSide === "left" ? 70 : -70;
+      anims.push(
+        wArmEl.animate(
+          [
+            { transform: `rotate(${wRest}deg)`, offset: 0 },
+            { transform: `rotate(${wUp}deg)`, offset: 0.2 },
+            { transform: `rotate(${wMid1}deg)`, offset: 0.4 },
+            { transform: `rotate(${wMid2}deg)`, offset: 0.55 },
+            { transform: `rotate(${wMid1}deg)`, offset: 0.7 },
+            { transform: `rotate(${wMid2}deg)`, offset: 0.85 },
+            { transform: `rotate(${wRest}deg)`, offset: 1 }
+          ],
+          { ...baseOpts, easing: "ease-in-out", fill: "forwards" }
+        )
+      );
+      break;
+    }
+    // ── jump ────────────────────────────────────────────────────────────────
+    // Jumps the actor up with squash/stretch effect.
+    // Usage: @3.0: hero.jump(height=30, dur=0.5)
+    case "jump": {
+      const jHeight = typeof ev.params.height === "number" ? ev.params.height : 30;
+      anims.push(
+        el.animate(
+          [
+            { 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" }
+        )
+      );
+      break;
+    }
+    // ── nod ─────────────────────────────────────────────────────────────────
+    // Nods the head down and back up. Figure actors only.
+    // Usage: @2.0: hero.nod(dur=0.4)
+    case "nod": {
+      const nHeadEl = el.querySelector("[data-fig-head]");
+      if (!nHeadEl) break;
+      const nRest = readRotation(nHeadEl);
+      const nDown = 15;
+      anims.push(
+        nHeadEl.animate(
+          [
+            { transform: `rotate(${nRest}deg)`, offset: 0 },
+            { transform: `rotate(${nDown}deg)`, offset: 0.35 },
+            { transform: `rotate(${nRest}deg)`, offset: 0.65 },
+            { transform: `rotate(${nDown}deg)`, offset: 0.8 },
+            { transform: `rotate(${nRest}deg)`, offset: 1 }
+          ],
+          { ...baseOpts, easing: "ease-in-out", fill: "forwards" }
+        )
+      );
+      break;
+    }
+    // ── bounce ──────────────────────────────────────────────────────────────
+    // Bounces the actor vertically with diminishing amplitude.
+    // Usage: @1.0: hero.bounce(intensity=15, count=3, dur=0.6)
+    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: 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: txFn({ ...s, y: s.y - amp }),
+          offset: peakOffset
+        });
+        if (bi < bCount - 1) {
+          keyframes.push({
+            transform: txFn(s),
+            offset: valleyOffset
+          });
+        }
+      }
+      keyframes.push({ transform: txFn(s), offset: 1 });
+      anims.push(
+        el.animate(keyframes, { ...baseOpts, easing: "ease-out" })
+      );
+      break;
+    }
     // ── throw ───────────────────────────────────────────────────────────────
     case "throw": {
       const assetName = String(ev.params.asset ?? "");
@@ -654,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",
@@ -735,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})`;
@@ -745,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.5.8",
+  "version": "0.7.0",
   "description": "Web Animations API renderer for MarkdyScript scenes.",
   "license": "MIT",
   "type": "module",
@@ -43,15 +43,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@markdy/core": "0.5.8"
+    "@markdy/core": "0.7.0"
   },
   "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"
   }
 }