sketchmark 1.3.4 → 1.3.6

package/dist/index.cjs

@@ -600,6 +600,12 @@ function parse(src, options = {}) {
             id,
             shape,
             label: props.label || "",
+            ...(props["label-dx"] !== undefined
+                ? { labelDx: parseFloat(props["label-dx"]) }
+                : {}),
+            ...(props["label-dy"] !== undefined
+                ? { labelDy: parseFloat(props["label-dy"]) }
+                : {}),
             ...(props.width ? { width: parseFloat(props.width) } : {}),
             ...(props.height ? { height: parseFloat(props.height) } : {}),
             ...(props.x ? { x: parseFloat(props.x) } : {}),
@@ -640,6 +646,12 @@ function parse(src, options = {}) {
             id,
             shape: "note",
             label: (props.label ?? "").replace(/\\n/g, "\n"),
+            ...(props["label-dx"] !== undefined
+                ? { labelDx: parseFloat(props["label-dx"]) }
+                : {}),
+            ...(props["label-dy"] !== undefined
+                ? { labelDy: parseFloat(props["label-dy"]) }
+                : {}),
             theme: props.theme,
             ...(meta ? { meta } : {}),
             style: propsToStyle(props),
@@ -688,6 +700,8 @@ function parse(src, options = {}) {
             kind: "group",
             id,
             label: props.label ?? "",
+            labelDx: props["label-dx"] !== undefined ? parseFloat(props["label-dx"]) : undefined,
+            labelDy: props["label-dy"] !== undefined ? parseFloat(props["label-dy"]) : undefined,
             children: [],
             layout: props.layout,
             columns: props.columns !== undefined ? parseInt(props.columns, 10) : undefined,
@@ -732,6 +746,8 @@ function parse(src, options = {}) {
             to: toTok.value,
             connector: connector,
             label: props.label,
+            labelDx: props["label-dx"] !== undefined ? parseFloat(props["label-dx"]) : undefined,
+            labelDy: props["label-dy"] !== undefined ? parseFloat(props["label-dy"]) : undefined,
             fromAnchor: props["anchor-from"],
             toAnchor: props["anchor-to"],
             dashed,
@@ -1233,6 +1249,7 @@ const LAYOUT = {
 const NODE = {
     minW: 90, // minimum auto-sized node width (px)
     maxW: 300, // maximum auto-sized node width (px)
+    mediaLabelH: 20, // reserved bottom strip for icon/image/line labels (px)
     basePad: 26, // base padding added to label width (px)
 };
 // ── Shape-specific sizing ──────────────────────────────────
@@ -3556,6 +3573,8 @@ function buildSceneGraph(ast) {
             id: n.id,
             shape: n.shape,
             label: n.label,
+            labelDx: n.labelDx,
+            labelDy: n.labelDy,
             style: { ...ast.styles[n.id], ...themeStyle, ...n.style },
             groupId: nodeParentById.get(n.id),
             width: n.width,
@@ -3581,6 +3600,8 @@ function buildSceneGraph(ast) {
         return {
             id: g.id,
             label: g.label,
+            labelDx: g.labelDx,
+            labelDy: g.labelDy,
             parentId: groupParentById.get(g.id),
             children: g.children,
             layout: (g.layout ?? "column"),
@@ -3658,6 +3679,8 @@ function buildSceneGraph(ast) {
         to: e.to,
         connector: e.connector,
         label: e.label,
+        labelDx: e.labelDx,
+        labelDy: e.labelDy,
         fromAnchor: e.fromAnchor,
         toAnchor: e.toAnchor,
         dashed: e.dashed ?? false,
@@ -3999,10 +4022,25 @@ const textShape = {
     },
 };
 
+const MEDIA_LABEL_SHAPES = new Set(["icon", "image", "line"]);
+function usesBottomLabelStrip(shape) {
+    return MEDIA_LABEL_SHAPES.has(shape);
+}
+function getBottomLabelStripHeight(node) {
+    return usesBottomLabelStrip(node.shape) && node.label ? NODE.mediaLabelH : 0;
+}
+function getBottomLabelContentHeight(node) {
+    return node.h - getBottomLabelStripHeight(node);
+}
+function getBottomLabelCenterY(node) {
+    const stripH = getBottomLabelStripHeight(node);
+    return stripH > 0 ? node.y + node.h - stripH / 2 : node.y + node.h / 2;
+}
+
 const iconShape = {
     size(n, labelW) {
         const iconBase = 48;
-        const labelH = n.label ? 20 : 0;
+        const labelH = getBottomLabelStripHeight(n);
         n.w = n.w || Math.max(iconBase, n.label ? labelW : 0);
         n.h = n.h || (iconBase + labelH);
     },
@@ -4015,8 +4053,7 @@ const iconShape = {
             const iconColor = s.color
                 ? encodeURIComponent(String(s.color))
                 : encodeURIComponent(String(palette.nodeStroke));
-            const labelSpace = n.label ? 20 : 0;
-            const iconAreaH = n.h - labelSpace;
+            const iconAreaH = getBottomLabelContentHeight(n);
             const iconSize = Math.min(n.w, iconAreaH) - 4;
             const iconUrl = `https://api.iconify.design/${prefix}/${name}.svg?color=${iconColor}&width=${iconSize}&height=${iconSize}`;
             const img = document.createElementNS(SVG_NS, "image");
@@ -4060,8 +4097,7 @@ const iconShape = {
             const iconColor = s.color
                 ? encodeURIComponent(String(s.color))
                 : encodeURIComponent(String(palette.nodeStroke));
-            const iconLabelSpace = n.label ? 20 : 0;
-            const iconAreaH = n.h - iconLabelSpace;
+            const iconAreaH = getBottomLabelContentHeight(n);
             const iconSize = Math.min(n.w, iconAreaH) - 4;
             const iconUrl = `https://api.iconify.design/${prefix}/${name}.svg?color=${iconColor}&width=${iconSize}&height=${iconSize}`;
             const img = new Image();
@@ -4104,21 +4140,21 @@ const imageShape = {
         const w = n.w || Math.max(MIN_W, Math.min(MAX_W, labelW));
         n.w = w;
         if (!n.h) {
+            const labelH = getBottomLabelStripHeight(n);
             if (labelW > w) {
                 const fontSize = Number(n.style?.fontSize ?? 14);
                 const lines = Math.ceil(labelW / (w - 16));
-                n.h = Math.max(52, lines * fontSize * 1.5 + 20);
+                n.h = Math.max(52, lines * fontSize * 1.5 + labelH);
             }
             else {
-                n.h = 52;
+                n.h = 52 + labelH;
             }
         }
     },
     renderSVG(rc, n, _palette, opts) {
         const s = n.style ?? {};
         if (n.imageUrl) {
-            const imgLabelSpace = n.label ? 20 : 0;
-            const imgAreaH = n.h - imgLabelSpace;
+            const imgAreaH = getBottomLabelContentHeight(n);
             const img = document.createElementNS(SVG_NS, "image");
             img.setAttribute("href", n.imageUrl);
             img.setAttribute("x", String(n.x + 1));
@@ -4150,8 +4186,7 @@ const imageShape = {
     renderCanvas(rc, ctx, n, _palette, opts) {
         const s = n.style ?? {};
         if (n.imageUrl) {
-            const imgLblSpace = n.label ? 20 : 0;
-            const imgAreaH = n.h - imgLblSpace;
+            const imgAreaH = getBottomLabelContentHeight(n);
             const img = new Image();
             img.crossOrigin = "anonymous";
             img.onload = () => {
@@ -4328,17 +4363,17 @@ const noteShape = {
 
 const lineShape = {
     size(n, labelW) {
-        const labelH = n.label ? 20 : 0;
+        const labelH = getBottomLabelStripHeight(n);
         n.w = n.width ?? Math.max(MIN_W, labelW + 20);
         n.h = n.height ?? (6 + labelH);
     },
     renderSVG(rc, n, _palette, opts) {
-        const labelH = n.label ? 20 : 0;
+        const labelH = getBottomLabelStripHeight(n);
         const lineY = n.y + (n.h - labelH) / 2;
         return [rc.line(n.x, lineY, n.x + n.w, lineY, opts)];
     },
     renderCanvas(rc, _ctx, n, _palette, opts) {
-        const labelH = n.label ? 20 : 0;
+        const labelH = getBottomLabelStripHeight(n);
         const lineY = n.y + (n.h - labelH) / 2;
         rc.line(n.x, lineY, n.x + n.w, lineY, opts);
     },
@@ -5584,18 +5619,18 @@ function renderRoughChartSVG(rc, c, palette, isDark) {
         stroke: bgStroke, strokeWidth: Number(s.strokeWidth ?? 1.2),
         ...(s.strokeDash ? { strokeLineDash: s.strokeDash } : {}),
     }));
+    const { px, py, pw, ph, titleH, cx, cy } = chartLayout(c);
     // Title
     if (c.label) {
-        cg.appendChild(mkT(c.label, c.x + c.w / 2, c.y + 14, cFontSize, cFontWeight, lc, 'middle', cFont));
+        cg.appendChild(mkT(c.label, c.x + c.w / 2, c.y + titleH / 2 + 2, cFontSize, cFontWeight, lc, 'middle', cFont));
     }
-    const { px, py, pw, ph, cx, cy } = chartLayout(c);
     // ── Pie / Donut ──────────────────────────────────────────
     if (c.chartType === 'pie' || c.chartType === 'donut') {
         const { segments, total } = parsePie(c.data);
-        const r = Math.min(c.w * 0.38, (c.h - (c.label ? 24 : 8)) * 0.44);
+        const r = Math.min(c.w * 0.38, (c.h - titleH) * 0.44);
         const ir = c.chartType === 'donut' ? r * 0.48 : 0;
         const legendX = c.x + 8;
-        const legendY = c.y + (c.label ? 28 : 12);
+        const legendY = c.y + titleH + 4;
         let angle = -Math.PI / 2;
         for (const seg of segments) {
             const sweep = (seg.value / total) * Math.PI * 2;
@@ -5633,7 +5668,7 @@ function renderRoughChartSVG(rc, c, palette, isDark) {
                 strokeWidth: 1.2,
             }));
         });
-        legend(cg, pts.map(p => p.label), CHART_COLORS, c.x + 8, c.y + (c.label ? 28 : 12), lc, cFont);
+        legend(cg, pts.map(p => p.label), CHART_COLORS, c.x + 8, c.y + titleH + 4, lc, cFont);
         return cg;
     }
     // ── Bar / Line / Area ─────────────────────────────────────
@@ -8379,9 +8414,10 @@ function renderToSVG(sg, container, options = {}) {
         }));
         // ── Group label typography ──────────────────────────
         const gTypo = resolveTypography(gs, { fontSize: GROUP_LABEL.fontSize, fontWeight: GROUP_LABEL.fontWeight, textAlign: "left", padding: GROUP_LABEL.padding }, diagramFont, palette.groupLabel);
-        const gTextX = computeTextX(gTypo, g.x, g.w);
+        const gTextX = computeTextX(gTypo, g.x, g.w) + (g.labelDx ?? 0);
+        const gTextY = g.y + gTypo.padding + (g.labelDy ?? 0);
         if (g.label) {
-            gg.appendChild(mkText(g.label, gTextX, g.y + gTypo.padding, gTypo.fontSize, gTypo.fontWeight, gTypo.textColor, gTypo.textAnchor, gTypo.font, gTypo.letterSpacing));
+            gg.appendChild(mkText(g.label, gTextX, gTextY, gTypo.fontSize, gTypo.fontWeight, gTypo.textColor, gTypo.textAnchor, gTypo.font, gTypo.letterSpacing));
         }
         GL.appendChild(gg);
     }
@@ -8433,8 +8469,8 @@ function renderToSVG(sg, container, options = {}) {
             eg.appendChild(startHead);
         }
         if (e.label) {
-            const mx = (x1 + x2) / 2 - ny * EDGE.labelOffset;
-            const my = (y1 + y2) / 2 + nx * EDGE.labelOffset;
+            const mx = (x1 + x2) / 2 - ny * EDGE.labelOffset + (e.labelDx ?? 0);
+            const my = (y1 + y2) / 2 + nx * EDGE.labelOffset + (e.labelDy ?? 0);
             const tw = Math.max(e.label.length * 7 + 12, 36);
             const bg = se("rect");
             bg.setAttribute("x", String(mx - tw / 2));
@@ -8502,7 +8538,7 @@ function renderToSVG(sg, container, options = {}) {
         // ── Node / text typography ─────────────────────────
         const isText = n.shape === "text";
         const isNote = n.shape === "note";
-        const isMediaShape = n.shape === "icon" || n.shape === "image" || n.shape === "line";
+        const usesBottomStrip = usesBottomLabelStrip(n.shape);
         const typo = resolveTypography(n.style, {
             fontSize: isText ? 13 : isNote ? 12 : 14,
             fontWeight: isText || isNote ? 400 : 500,
@@ -8520,20 +8556,22 @@ function renderToSVG(sg, container, options = {}) {
                     : n.x + typo.padding)
             : computeTextX(typo, n.x, n.w);
         const fontStr = buildFontStr(typo.fontSize, typo.fontWeight, typo.font);
-        const shouldWrap = !isMediaShape && !n.label.includes('\n');
+        const shouldWrap = !usesBottomStrip && !n.label.includes('\n');
         const innerW = shapeInnerTextWidth(n.shape, n.w, typo.padding);
         const lines = shouldWrap
             ? wrapText(n.label, innerW, typo.fontSize, fontStr)
             : n.label.split('\n');
-        const textCY = isMediaShape
-            ? n.y + n.h - 10
+        const textCY = usesBottomStrip
+            ? getBottomLabelCenterY(n)
             : isNote
                 ? computeTextCY(typo, n.y, n.h, lines.length, FOLD + typo.padding)
                 : computeTextCY(typo, n.y, n.h, lines.length);
+        const labelX = textX + (n.labelDx ?? 0);
+        const labelY = textCY + (n.labelDy ?? 0);
         if (n.label) {
             ng.appendChild(lines.length > 1
-                ? mkMultilineText(lines, textX, textCY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAnchor, typo.lineHeight, typo.font, typo.letterSpacing)
-                : mkText(n.label, textX, textCY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAnchor, typo.font, typo.letterSpacing));
+                ? mkMultilineText(lines, labelX, labelY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAnchor, typo.lineHeight, typo.font, typo.letterSpacing)
+                : mkText(n.label, labelX, labelY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAnchor, typo.font, typo.letterSpacing));
         }
         if (options.interactive) {
             ng.style.cursor = "pointer";
@@ -8847,6 +8885,7 @@ function drawRoughChartCanvas(rc, ctx, c, pal, R) {
         strokeWidth: Number(s.strokeWidth ?? 1.2),
         ...(s.strokeDash ? { strokeLineDash: s.strokeDash } : {}),
     });
+    const { px, py, pw, ph, titleH, cx, cy } = chartLayout(c);
     // Title
     if (c.label) {
         ctx.save();
@@ -8854,17 +8893,16 @@ function drawRoughChartCanvas(rc, ctx, c, pal, R) {
         ctx.fillStyle = lc;
         ctx.textAlign = 'center';
         ctx.textBaseline = 'middle';
-        ctx.fillText(c.label, c.x + c.w / 2, c.y + 14);
+        ctx.fillText(c.label, c.x + c.w / 2, c.y + titleH / 2 + 2);
         ctx.restore();
     }
-    const { px, py, pw, ph, cx, cy } = chartLayout(c);
     // ── Pie / Donut ──────────────────────────────────────────
     if (c.chartType === 'pie' || c.chartType === 'donut') {
         const { segments, total } = parsePie(c.data);
-        const r = Math.min(c.w * 0.38, (c.h - (c.label ? 24 : 8)) * 0.44);
+        const r = Math.min(c.w * 0.38, (c.h - titleH) * 0.44);
         const ir = c.chartType === 'donut' ? r * 0.48 : 0;
         const legendX = c.x + 8;
-        const legendY = c.y + (c.label ? 28 : 12);
+        const legendY = c.y + titleH + 4;
         let angle = -Math.PI / 2;
         segments.forEach((seg, i) => {
             const sweep = (seg.value / total) * Math.PI * 2;
@@ -8892,7 +8930,7 @@ function drawRoughChartCanvas(rc, ctx, c, pal, R) {
                 strokeWidth: 1.2,
             });
         });
-        drawLegend(ctx, pts.map(p => p.label), CHART_COLORS, c.x + 8, c.y + (c.label ? 28 : 12), lc, cFont);
+        drawLegend(ctx, pts.map(p => p.label), CHART_COLORS, c.x + 8, c.y + titleH + 4, lc, cFont);
         ctx.globalAlpha = 1;
         return;
     }
@@ -9127,8 +9165,9 @@ function renderToCanvas(sg, canvas, options = {}) {
         });
         if (g.label) {
             const gTypo = resolveTypography(gs, { fontSize: GROUP_LABEL.fontSize, fontWeight: GROUP_LABEL.fontWeight, textAlign: "left", padding: GROUP_LABEL.padding }, diagramFont, palette.groupLabel);
-            const gTextX = computeTextX(gTypo, g.x, g.w);
-            drawText(ctx, g.label, gTextX, g.y + gTypo.padding + 2, gTypo.fontSize, gTypo.fontWeight, gTypo.textColor, gTypo.textAlign, gTypo.font, gTypo.letterSpacing);
+            const gTextX = computeTextX(gTypo, g.x, g.w) + (g.labelDx ?? 0);
+            const gTextY = g.y + gTypo.padding + 2 + (g.labelDy ?? 0);
+            drawText(ctx, g.label, gTextX, gTextY, gTypo.fontSize, gTypo.fontWeight, gTypo.textColor, gTypo.textAlign, gTypo.font, gTypo.letterSpacing);
         }
         if (gs.opacity != null)
             ctx.globalAlpha = 1;
@@ -9166,8 +9205,8 @@ function renderToCanvas(sg, canvas, options = {}) {
         if (arrowAt === 'start' || arrowAt === 'both')
             drawArrowHead(rc, x1, y1, Math.atan2(y1 - y2, x1 - x2), ecol, hashStr$3(e.from + 'back'));
         if (e.label) {
-            const mx = (x1 + x2) / 2 - ny * EDGE.labelOffset;
-            const my = (y1 + y2) / 2 + nx * EDGE.labelOffset;
+            const mx = (x1 + x2) / 2 - ny * EDGE.labelOffset + (e.labelDx ?? 0);
+            const my = (y1 + y2) / 2 + nx * EDGE.labelOffset + (e.labelDy ?? 0);
             // ── Edge label: font, font-size, letter-spacing ──
             // always center-anchored (single line)
             const eFontSize = Number(e.style?.fontSize ?? EDGE.labelFontSize);
@@ -9207,7 +9246,7 @@ function renderToCanvas(sg, canvas, options = {}) {
         // ── Node / text typography ─────────────────────────
         const isText = n.shape === 'text';
         const isNote = n.shape === 'note';
-        const isMediaShape = n.shape === 'icon' || n.shape === 'image' || n.shape === 'line';
+        const usesBottomStrip = usesBottomLabelStrip(n.shape);
         const typo = resolveTypography(n.style, {
             fontSize: isText ? 13 : isNote ? 12 : 14,
             fontWeight: isText || isNote ? 400 : 500,
@@ -9225,23 +9264,25 @@ function renderToCanvas(sg, canvas, options = {}) {
                     : n.x + typo.padding)
             : computeTextX(typo, n.x, n.w);
         const fontStr = buildFontStr(typo.fontSize, typo.fontWeight, typo.font);
-        const shouldWrap = !isMediaShape && !n.label.includes('\n');
+        const shouldWrap = !usesBottomStrip && !n.label.includes('\n');
         const innerW = shapeInnerTextWidth(n.shape, n.w, typo.padding);
         const rawLines = n.label.split('\n');
         const lines = shouldWrap && rawLines.length === 1
             ? wrapText(n.label, innerW, typo.fontSize, fontStr)
             : rawLines;
-        const textCY = isMediaShape
-            ? n.y + n.h - 10
+        const textCY = usesBottomStrip
+            ? getBottomLabelCenterY(n)
             : isNote
                 ? computeTextCY(typo, n.y, n.h, lines.length, FOLD + typo.padding)
                 : computeTextCY(typo, n.y, n.h, lines.length);
+        const labelX = textX + (n.labelDx ?? 0);
+        const labelY = textCY + (n.labelDy ?? 0);
         if (n.label) {
             if (lines.length > 1) {
-                drawMultilineText(ctx, lines, textX, textCY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAlign, typo.lineHeight, typo.font, typo.letterSpacing);
+                drawMultilineText(ctx, lines, labelX, labelY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAlign, typo.lineHeight, typo.font, typo.letterSpacing);
             }
             else {
-                drawText(ctx, lines[0] ?? '', textX, textCY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAlign, typo.font, typo.letterSpacing);
+                drawText(ctx, lines[0] ?? '', labelX, labelY, typo.fontSize, typo.fontWeight, typo.textColor, typo.textAlign, typo.font, typo.letterSpacing);
             }
         }
         if (hasTx)
@@ -9579,7 +9620,7 @@ function buildNodeGuidePath(el) {
                 [x + 1, y + h - 1],
             ]);
         case "line": {
-            const labelH = el.querySelector("text") ? 20 : 0;
+            const labelH = el.querySelector("text") ? NODE.mediaLabelH : 0;
             const lineY = y + (h - labelH) / 2;
             return `M ${x} ${lineY} L ${x + w} ${lineY}`;
         }
@@ -9950,8 +9991,12 @@ class AnimationController {
         this._rc = _rc;
         this._config = _config;
         this._step = -1;
+        this._isPlaying = false;
+        this._playRunId = 0;
         this._pendingStepTimers = new Set();
         this._pendingNarrationTimers = new Set();
+        this._playbackDelayTimerId = null;
+        this._resolvePlaybackDelay = null;
         this._transforms = new Map();
         this._listeners = [];
         // ── Narration caption ──
@@ -9967,6 +10012,7 @@ class AnimationController {
         // ── TTS ──
         this._tts = false;
         this._speechDone = null;
+        this._resolveSpeechDone = null;
         this.drawTargetEdges = getDrawTargetEdgeIds(steps);
         this.drawTargetNodes = getDrawTargetNodeIds(steps);
         // Groups: non-edge draw steps whose target has a #group-{id} element in the SVG.
@@ -10190,6 +10236,9 @@ class AnimationController {
     get atEnd() {
         return this._step === this.steps.length - 1;
     }
+    get isPlaying() {
+        return this._isPlaying;
+    }
     on(listener) {
         this._listeners.push(listener);
         return () => {
@@ -10207,12 +10256,14 @@ class AnimationController {
             l(e);
     }
     reset() {
+        this.stop();
         this._step = -1;
         this._clearAll();
         this.emit("animation-reset");
     }
     /** Remove caption and annotation layer from the DOM */
     destroy() {
+        this.stop();
         this._clearAll();
         this._captionEl?.remove();
         this._captionEl = null;
@@ -10223,16 +10274,11 @@ class AnimationController {
         this._pointerEl = null;
     }
     next() {
-        if (!this.canNext)
-            return false;
-        this._step++;
-        this._applyStep(this._step, false);
-        this.emit("step-change");
-        if (!this.canNext)
-            this.emit("animation-end");
-        return true;
+        this.stop();
+        return this._advanceNext();
     }
     prev() {
+        this.stop();
         if (!this.canPrev)
             return false;
         this._step--;
@@ -10243,18 +10289,33 @@ class AnimationController {
         return true;
     }
     async play(msPerStep = 900) {
+        if (this._isPlaying || !this.canNext)
+            return;
+        const runId = ++this._playRunId;
+        this._isPlaying = true;
         this.emit("animation-start");
-        while (this.canNext) {
-            const nextStep = this.steps[this._step + 1];
-            this.next();
-            // Wait for timer AND speech to finish (whichever is longer)
-            await Promise.all([
-                new Promise((r) => setTimeout(r, this._playbackWaitMs(nextStep, msPerStep))),
-                this._speechDone ?? Promise.resolve(),
-            ]);
+        try {
+            while (this.canNext && this._playRunId === runId) {
+                const nextStep = this.steps[this._step + 1];
+                if (!this._advanceNext())
+                    break;
+                if (this._playRunId !== runId)
+                    break;
+                await Promise.all([
+                    this._waitForPlaybackDelay(this._playbackWaitMs(nextStep, msPerStep)),
+                    this._speechDone ?? Promise.resolve(),
+                ]);
+            }
+        }
+        finally {
+            if (this._playRunId === runId) {
+                this._isPlaying = false;
+                this._cancelPlaybackDelay();
+            }
         }
     }
     goTo(index) {
+        this.stop();
         index = Math.max(-1, Math.min(this.steps.length - 1, index));
         if (index === this._step)
             return;
@@ -10268,6 +10329,30 @@ class AnimationController {
         }
         this.emit("step-change");
     }
+    stop() {
+        if (!this._isPlaying && !this._resolvePlaybackDelay) {
+            this._clearPendingStepTimers();
+            this._cancelNarrationTyping();
+            this._cancelSpeech();
+            return;
+        }
+        this._isPlaying = false;
+        this._playRunId += 1;
+        this._cancelPlaybackDelay();
+        this._clearPendingStepTimers();
+        this._cancelNarrationTyping();
+        this._cancelSpeech();
+    }
+    _advanceNext() {
+        if (!this.canNext)
+            return false;
+        this._step++;
+        this._applyStep(this._step, false);
+        this.emit("step-change");
+        if (!this.canNext)
+            this.emit("animation-end");
+        return true;
+    }
     _clearTimerBucket(bucket) {
         bucket.forEach((id) => window.clearTimeout(id));
         bucket.clear();
@@ -10293,6 +10378,34 @@ class AnimationController {
     _scheduleStep(fn, delayMs) {
         this._scheduleTimer(fn, delayMs, this._pendingStepTimers);
     }
+    _waitForPlaybackDelay(delayMs) {
+        this._cancelPlaybackDelay();
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (this._playbackDelayTimerId !== null) {
+                    window.clearTimeout(this._playbackDelayTimerId);
+                    this._playbackDelayTimerId = null;
+                }
+                if (this._resolvePlaybackDelay === finish) {
+                    this._resolvePlaybackDelay = null;
+                }
+                resolve();
+            };
+            this._resolvePlaybackDelay = finish;
+            if (delayMs <= 0) {
+                finish();
+                return;
+            }
+            this._playbackDelayTimerId = window.setTimeout(finish, delayMs);
+        });
+    }
+    _cancelPlaybackDelay() {
+        this._resolvePlaybackDelay?.();
+    }
     _stepWaitMs(step, fallbackMs) {
         const delay = Math.max(0, step.delay ?? 0);
         const duration = Math.max(0, step.duration ?? 0);
@@ -10334,6 +10447,7 @@ class AnimationController {
         return this._stepWaitMs(step, fallbackMs);
     }
     _clearAll() {
+        this._cancelPlaybackDelay();
         this._clearPendingStepTimers();
         this._cancelNarrationTyping();
         this._cancelSpeech();
@@ -10945,16 +11059,30 @@ class AnimationController {
         utter.rate = 0.95;
         utter.pitch = 1;
         utter.lang = "en-US";
-        // Track when speech actually finishes
+        // Track when speech actually finishes so play() can block until the utterance ends.
         this._speechDone = new Promise((resolve) => {
-            utter.onend = () => resolve();
-            utter.onerror = () => resolve();
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (this._resolveSpeechDone === finish) {
+                    this._resolveSpeechDone = null;
+                    this._speechDone = null;
+                }
+                resolve();
+            };
+            this._resolveSpeechDone = finish;
+            utter.onend = finish;
+            utter.onerror = finish;
         });
         speechSynthesis.speak(utter);
     }
     _cancelSpeech() {
         if (typeof speechSynthesis !== "undefined")
             speechSynthesis.cancel();
+        this._resolveSpeechDone?.();
+        this._resolveSpeechDone = null;
         this._speechDone = null;
     }
     /** Pre-warm the speech engine with a silent utterance to eliminate cold-start delay */
@@ -11763,7 +11891,13 @@ class SketchmarkCanvas {
         this.resetButton.addEventListener("click", () => this.resetAnimation());
         this.prevButton.addEventListener("click", () => this.prevStep());
         this.nextButton.addEventListener("click", () => this.nextStep());
-        this.playButton.addEventListener("click", () => void this.play());
+        this.playButton.addEventListener("click", () => {
+            if (this.playInFlight) {
+                this.stopPlayback();
+                return;
+            }
+            void this.play();
+        });
         this.captionButton.addEventListener("click", () => this.setCaptionVisible(!this.showCaption));
         this.ttsButton.addEventListener("click", () => this.setTtsEnabled(!this.getTtsEnabled()));
         this.viewport.addEventListener("pointerdown", this.onPointerDown);
@@ -11827,6 +11961,7 @@ class SketchmarkCanvas {
             this.dsl = normalizeNewlines(nextDsl);
         this.clearError();
         this.mirroredEditor?.clearError();
+        this.playInFlight = false;
         this.animUnsub?.();
         this.animUnsub = null;
         this.instance?.anim?.destroy();
@@ -11897,9 +12032,16 @@ class SketchmarkCanvas {
             this.syncAnimationUi();
         }
     }
+    stopPlayback() {
+        this.playInFlight = false;
+        if (this.renderer === "svg")
+            this.instance?.anim.stop();
+        this.syncAnimationUi();
+    }
     nextStep() {
         if (!this.instance || this.renderer !== "svg")
             return;
+        this.playInFlight = false;
         this.instance.anim.next();
         this.syncAnimationUi();
         this.focusCurrentStep();
@@ -11907,6 +12049,7 @@ class SketchmarkCanvas {
     prevStep() {
         if (!this.instance || this.renderer !== "svg")
             return;
+        this.playInFlight = false;
         this.instance.anim.prev();
         this.syncAnimationUi();
         this.focusCurrentStep();
@@ -11914,6 +12057,7 @@ class SketchmarkCanvas {
     resetAnimation() {
         if (!this.instance || this.renderer !== "svg")
             return;
+        this.playInFlight = false;
         this.instance.anim.reset();
         this.syncAnimationUi();
     }
@@ -11942,6 +12086,7 @@ class SketchmarkCanvas {
         this.render();
     }
     destroy() {
+        this.playInFlight = false;
         this.editorCleanup?.();
         this.animUnsub?.();
         this.instance?.anim?.destroy();
@@ -12016,6 +12161,9 @@ class SketchmarkCanvas {
             this.prevButton.disabled = true;
             this.nextButton.disabled = true;
             this.resetButton.disabled = true;
+            this.playButton.textContent = "Play";
+            this.playButton.classList.remove("is-active");
+            this.playButton.setAttribute("aria-pressed", "false");
             this.playButton.disabled = true;
             this.syncToggleUi();
             return;
@@ -12025,7 +12173,10 @@ class SketchmarkCanvas {
         this.prevButton.disabled = !anim.canPrev;
         this.nextButton.disabled = !anim.canNext;
         this.resetButton.disabled = false;
-        this.playButton.disabled = this.playInFlight || !anim.canNext;
+        this.playButton.textContent = this.playInFlight ? "Stop" : "Play";
+        this.playButton.classList.toggle("is-active", this.playInFlight);
+        this.playButton.setAttribute("aria-pressed", this.playInFlight ? "true" : "false");
+        this.playButton.disabled = this.playInFlight ? false : !anim.canNext;
         this.syncToggleUi();
     }
     getStepTarget(stepItem) {
@@ -12931,6 +13082,10 @@ class SketchmarkEmbed {
         this.btnPrev.addEventListener("click", () => this.prevStep());
         this.btnNext.addEventListener("click", () => this.nextStep());
         this.btnPlay.addEventListener("click", () => {
+            if (this.playInFlight) {
+                this.stopPlayback();
+                return;
+            }
             void this.play();
         });
         this.btnCaption.addEventListener("click", () => this.setCaptionVisible(!this.showCaption));
@@ -12988,6 +13143,7 @@ class SketchmarkEmbed {
         }
         this.clearError();
         this.stopMotion();
+        this.playInFlight = false;
         this.animUnsub?.();
         this.animUnsub = null;
         this.instance?.anim?.destroy();
@@ -13060,9 +13216,15 @@ class SketchmarkEmbed {
             this.syncControls();
         }
     }
+    stopPlayback() {
+        this.playInFlight = false;
+        this.instance?.anim.stop();
+        this.syncControls();
+    }
     nextStep() {
         if (!this.instance)
             return;
+        this.playInFlight = false;
         this.instance.anim.next();
         this.syncControls();
         if (this.options.autoFocus !== false && this.options.autoFocusOnStep !== false) {
@@ -13072,6 +13234,7 @@ class SketchmarkEmbed {
     prevStep() {
         if (!this.instance)
             return;
+        this.playInFlight = false;
         this.instance.anim.prev();
         this.syncControls();
         if (this.options.autoFocus !== false && this.options.autoFocusOnStep !== false) {
@@ -13081,6 +13244,7 @@ class SketchmarkEmbed {
     resetAnimation() {
         if (!this.instance)
             return;
+        this.playInFlight = false;
         this.instance.anim.reset();
         this.syncControls();
     }
@@ -13107,6 +13271,7 @@ class SketchmarkEmbed {
     }
     destroy() {
         this.stopMotion();
+        this.playInFlight = false;
         this.animUnsub?.();
         this.instance?.anim?.destroy();
         this.instance = null;
@@ -13139,6 +13304,9 @@ class SketchmarkEmbed {
             this.btnRestart.disabled = true;
             this.btnPrev.disabled = true;
             this.btnNext.disabled = true;
+            this.btnPlay.textContent = "Play";
+            this.btnPlay.classList.remove("is-active");
+            this.btnPlay.setAttribute("aria-pressed", "false");
             this.btnPlay.disabled = true;
             return;
         }
@@ -13147,7 +13315,10 @@ class SketchmarkEmbed {
         this.btnRestart.disabled = false;
         this.btnPrev.disabled = !anim.canPrev;
         this.btnNext.disabled = !anim.canNext;
-        this.btnPlay.disabled = this.playInFlight || !anim.canNext;
+        this.btnPlay.textContent = this.playInFlight ? "Stop" : "Play";
+        this.btnPlay.classList.toggle("is-active", this.playInFlight);
+        this.btnPlay.setAttribute("aria-pressed", this.playInFlight ? "true" : "false");
+        this.btnPlay.disabled = this.playInFlight ? false : !anim.canNext;
     }
     syncViewControls() {
         const hasView = !!this.instance?.svg;