sketchmark 1.3.5 → 1.3.6

package/README.md

@@ -149,7 +149,7 @@ const embed = new SketchmarkEmbed({
 });
 ```
 
-Use `SketchmarkCanvas` for the full playground-style surface, and `SketchmarkEmbed` for fixed-size embeds that clip overflow, auto-fit large diagrams, support drag-to-pan plus wheel/trackpad zoom, and expose built-in zoom, playback, caption, and TTS controls.
+Use `SketchmarkCanvas` for the full playground-style surface, and `SketchmarkEmbed` for fixed-size embeds that clip overflow, auto-fit large diagrams, support drag-to-pan plus wheel/trackpad zoom, and expose built-in zoom, playback, caption, and TTS controls. While autoplay is running, their built-in `Play` control switches to `Stop` so you can hard-stop the sequence immediately.
 
 ---
 
@@ -854,17 +854,19 @@ anim.total            // number of steps
 anim.currentStep      // current step index (-1 = before start)
 anim.canNext          // boolean
 anim.canPrev          // boolean
-anim.atEnd            // boolean
+anim.atEnd            // boolean
+anim.isPlaying        // boolean
 anim.captionElement   // HTMLDivElement | null — the narration caption element
 anim.tts              // boolean — text-to-speech enabled/disabled
 
 // Methods
-anim.next()                // advance one step (returns bool)
-anim.prev()                // go back one step (returns bool)
-anim.reset()               // reset to before step 0
-anim.goTo(index)           // jump to step N
-await anim.play(700)       // play all remaining steps (700ms between)
-anim.destroy()             // remove caption, annotations, pointer from DOM
+anim.next()                // advance one step (returns bool)
+anim.prev()                // go back one step (returns bool)
+anim.reset()               // reset to before step 0
+anim.goTo(index)           // jump to step N
+await anim.play(700)       // play all remaining steps (700ms between)
+anim.stop()                // hard-stop autoplay without resetting the current step
+anim.destroy()             // remove caption, annotations, pointer from DOM
 
 // Toggle TTS programmatically
 anim.tts = true;           // enable browser speech

package/dist/animation/index.d.ts

@@ -19,8 +19,12 @@ export declare class AnimationController {
     private _rc?;
     private _config?;
     private _step;
+    private _isPlaying;
+    private _playRunId;
     private _pendingStepTimers;
     private _pendingNarrationTimers;
+    private _playbackDelayTimerId;
+    private _resolvePlaybackDelay;
     private _transforms;
     private _listeners;
     readonly drawTargetEdges: Set<string>;
@@ -43,6 +47,7 @@ export declare class AnimationController {
     private _pointerType;
     private _tts;
     private _speechDone;
+    private _resolveSpeechDone;
     get drawTargets(): Set<string>;
     constructor(svg: SVGSVGElement, steps: ASTStepItem[], _container?: HTMLElement | undefined, _rc?: any | undefined, _config?: Record<string, string | number | boolean> | undefined);
     private _buildDrawStepIndex;
@@ -62,6 +67,7 @@ export declare class AnimationController {
     get canNext(): boolean;
     get canPrev(): boolean;
     get atEnd(): boolean;
+    get isPlaying(): boolean;
     on(listener: AnimationListener): () => void;
     private emit;
     reset(): void;
@@ -71,11 +77,15 @@ export declare class AnimationController {
     prev(): boolean;
     play(msPerStep?: number): Promise<void>;
     goTo(index: number): void;
+    stop(): void;
+    private _advanceNext;
     private _clearTimerBucket;
     private _clearPendingStepTimers;
     private _cancelNarrationTyping;
     private _scheduleTimer;
     private _scheduleStep;
+    private _waitForPlaybackDelay;
+    private _cancelPlaybackDelay;
     private _stepWaitMs;
     private _playbackWaitMs;
     private _clearAll;

package/dist/animation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/animation/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/animation/index.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -9991,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 ──
@@ -10008,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.
@@ -10231,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 () => {
@@ -10248,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;
@@ -10264,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--;
@@ -10284,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;
@@ -10309,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();
@@ -10334,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);
@@ -10375,6 +10447,7 @@ class AnimationController {
         return this._stepWaitMs(step, fallbackMs);
     }
     _clearAll() {
+        this._cancelPlaybackDelay();
         this._clearPendingStepTimers();
         this._cancelNarrationTyping();
         this._cancelSpeech();
@@ -10986,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 */
@@ -11804,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);
@@ -11868,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();
@@ -11938,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();
@@ -11948,6 +12049,7 @@ class SketchmarkCanvas {
     prevStep() {
         if (!this.instance || this.renderer !== "svg")
             return;
+        this.playInFlight = false;
         this.instance.anim.prev();
         this.syncAnimationUi();
         this.focusCurrentStep();
@@ -11955,6 +12057,7 @@ class SketchmarkCanvas {
     resetAnimation() {
         if (!this.instance || this.renderer !== "svg")
             return;
+        this.playInFlight = false;
         this.instance.anim.reset();
         this.syncAnimationUi();
     }
@@ -11983,6 +12086,7 @@ class SketchmarkCanvas {
         this.render();
     }
     destroy() {
+        this.playInFlight = false;
         this.editorCleanup?.();
         this.animUnsub?.();
         this.instance?.anim?.destroy();
@@ -12057,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;
@@ -12066,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) {
@@ -12972,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));
@@ -13029,6 +13143,7 @@ class SketchmarkEmbed {
         }
         this.clearError();
         this.stopMotion();
+        this.playInFlight = false;
         this.animUnsub?.();
         this.animUnsub = null;
         this.instance?.anim?.destroy();
@@ -13101,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) {
@@ -13113,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) {
@@ -13122,6 +13244,7 @@ class SketchmarkEmbed {
     resetAnimation() {
         if (!this.instance)
             return;
+        this.playInFlight = false;
         this.instance.anim.reset();
         this.syncControls();
     }
@@ -13148,6 +13271,7 @@ class SketchmarkEmbed {
     }
     destroy() {
         this.stopMotion();
+        this.playInFlight = false;
         this.animUnsub?.();
         this.instance?.anim?.destroy();
         this.instance = null;
@@ -13180,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;
         }
@@ -13188,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;