sketchmark 1.1.4 → 1.1.5

package/README.md

@@ -84,9 +84,11 @@ end
 `.trim(),
 });
 
-const canvas = new SketchmarkCanvas({
-  container: document.getElementById('viewport'),
-});
+const canvas = new SketchmarkCanvas({
+  container: document.getElementById('viewport'),
+  showCaption: false,
+  tts: true,
+});
 
 canvas.bindEditor(editor);
 ```
@@ -100,13 +102,15 @@ const embed = new SketchmarkEmbed({
   width: 960,
   height: 540,
   playStepDelay: 700,
+  showCaption: false,
+  tts: true,
   fitPadding: 24,
   zoomMin: 0.08,
   zoomMax: 4,
 });
 ```
 
-Use `SketchmarkCanvas` for the full playground-style surface, and `SketchmarkEmbed` for fixed-size embeds that clip overflow, auto-fit large diagrams, and expose built-in `+`, `-`, and reset-to-fit controls alongside step playback.
+Use `SketchmarkCanvas` for the full playground-style surface, and `SketchmarkEmbed` for fixed-size embeds that clip overflow, auto-fit large diagrams, and expose built-in zoom, playback, caption, and TTS controls.
 
 ---
 
@@ -661,9 +665,11 @@ step narrate "Plants need sunlight to make food"
 step narrate "This is the most important step" pace=slow
 ```
 
-- Caption is rendered as a fixed-position `<div>` on `document.body` (independent of diagram pan/zoom).
-- Access via `anim.captionElement` to reparent it anywhere.
-- Supports built-in browser text-to-speech (see [TTS](#text-to-speech)).
+- Caption is rendered as a fixed-position `<div>` on `document.body` (independent of diagram pan/zoom).
+- Access via `anim.captionElement` to reparent it anywhere.
+- `SketchmarkCanvas` and `SketchmarkEmbed` support `showCaption: false` to hide the caption bar UI.
+- Both widget UIs also include a built-in caption toggle button by default.
+- Supports built-in browser text-to-speech (see [TTS](#text-to-speech)).
 
 ### Annotations
 
@@ -799,10 +805,14 @@ anim.destroy()             // remove caption, annotations, pointer from DOM
 
 // Toggle TTS programmatically
 anim.tts = true;           // enable browser speech
-anim.tts = false;          // disable (stops current speech)
-
-// Reparent the narration caption to a custom container
-myDiv.appendChild(anim.captionElement);
+anim.tts = false;          // disable (stops current speech)
+
+// Reparent the narration caption to a custom container
+myDiv.appendChild(anim.captionElement);
+
+// UI widgets can suppress the visible caption bar
+const embed = new SketchmarkEmbed({ container, dsl, showCaption: false });
+embed.setCaptionVisible(true);
 
 // Event listener
 const unsub = anim.on((event) => {
@@ -814,22 +824,31 @@ const unsub = anim.on((event) => {
 unsub(); // unsubscribe
 ```
 
-### Text-to-Speech
-
-Enable browser-native speech synthesis for narrate steps:
-
-```
-# In DSL
-config tts=on
-```
-
-```javascript
-// Or via API
-anim.tts = true;
-
-// Custom TTS (e.g. ElevenLabs) via event listener
-anim.tts = false; // disable built-in
-anim.on((e) => {
+### Text-to-Speech
+
+Enable browser-native speech synthesis for narrate steps. You can drive it from the diagram config or from the JS API. If both are provided, the JS option wins. `SketchmarkCanvas` and `SketchmarkEmbed` also include a built-in TTS toggle button by default.
+
+```
+# In DSL
+config tts=on
+```
+
+```javascript
+// Direct render option
+const instance = render({ container, dsl, tts: true });
+
+// Widget options
+const canvas = new SketchmarkCanvas({ container, dsl, tts: true });
+const embed = new SketchmarkEmbed({ container, dsl, tts: true });
+
+// Or toggle at runtime
+anim.tts = true;
+canvas.setTtsEnabled(false);
+embed.setTtsEnabled(true);
+
+// Custom TTS (e.g. ElevenLabs) via event listener
+anim.tts = false; // disable built-in
+anim.on((e) => {
   if (e.step?.kind === 'step' && e.step.action === 'narrate') {
     myTTSService.speak(e.step.value);
   }
@@ -1211,14 +1230,15 @@ end
 ```typescript
 render(options: RenderOptions): DiagramInstance
 
-interface RenderOptions {
-  container:      string | HTMLElement | SVGSVGElement; // CSS selector or element
-  dsl:            string;                               // DSL source text
-  renderer?:      'svg' | 'canvas';                    // default: 'svg'
-  injectCSS?:     boolean;                              // inject animation CSS (default: true)
-  svgOptions?:    SVGRendererOptions;
-  canvasOptions?: CanvasRendererOptions;
-  onNodeClick?:   (nodeId: string) => void;            // click handler
+interface RenderOptions {
+  container:      string | HTMLElement | SVGSVGElement; // CSS selector or element
+  dsl:            string;                               // DSL source text
+  renderer?:      'svg' | 'canvas';                    // default: 'svg'
+  injectCSS?:     boolean;                              // inject animation CSS (default: true)
+  tts?:           boolean;                              // override diagram TTS config
+  svgOptions?:    SVGRendererOptions;
+  canvasOptions?: CanvasRendererOptions;
+  onNodeClick?:   (nodeId: string) => void;            // click handler
   onReady?:       (anim, svg?) => void;                // callback after render
 }
 

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

@@ -9443,8 +9443,17 @@ class AnimationController {
     }
     /** Enable/disable browser text-to-speech for narrate steps */
     get tts() { return this._tts; }
-    set tts(on) { this._tts = on; if (!on)
-        this._cancelSpeech(); }
+    set tts(on) {
+        const next = !!on;
+        const changed = next !== this._tts;
+        this._tts = next;
+        if (!next) {
+            this._cancelSpeech();
+            return;
+        }
+        if (changed)
+            this._warmUpSpeech();
+    }
     get currentStep() {
         return this._step;
     }
@@ -10723,7 +10732,7 @@ class EventEmitter {
 }
 
 function render(options) {
-    const { container: rawContainer, dsl, renderer = "svg", injectCSS = true, svgOptions = {}, canvasOptions = {}, onNodeClick, onReady, } = options;
+    const { container: rawContainer, dsl, renderer = "svg", injectCSS = true, tts, svgOptions = {}, canvasOptions = {}, onNodeClick, onReady, } = options;
     if (injectCSS && !document.getElementById("ai-diagram-css")) {
         const style = document.createElement("style");
         style.id = "ai-diagram-css";
@@ -10772,6 +10781,9 @@ function render(options) {
         const containerEl = el instanceof SVGSVGElement ? undefined : el;
         anim = new AnimationController(svg, ast.steps, containerEl, rc, ast.config);
     }
+    if (typeof tts === "boolean") {
+        anim.tts = tts;
+    }
     onReady?.(anim, svg);
     return {
         scene,
@@ -10823,13 +10835,14 @@ function toError(error) {
 const CANVAS_STYLE_ID = "sketchmark-canvas-ui";
 const CANVAS_CSS = `
 .skm-canvas{display:flex;flex-direction:column;width:100%;height:100%;min-height:320px;overflow:hidden;border:1px solid #caba98;border-radius:10px;background:#f8f4ea;color:#3a2010;font-family:"Courier New",monospace}
-.skm-canvas__animbar{display:flex;align-items:center;gap:6px;padding:6px 10px;background:#eee7d8;border-bottom:1px solid #caba98;flex-shrink:0}
+.skm-canvas__animbar{display:flex;align-items:center;gap:6px;padding:6px 10px;background:#eee7d8;border-bottom:1px solid #caba98;flex-shrink:0;flex-wrap:wrap}
 .skm-canvas__status{min-width:96px;text-align:center;color:#6a4820;font-size:11px}
 .skm-canvas__label{color:#8a6040;font-size:11px;font-style:italic}
 .skm-canvas__spacer{flex:1}
 .skm-canvas__stats{color:#9a7848;font-size:10px}
 .skm-canvas__button{border:1px solid #caba98;background:#f5eedd;color:#3a2010;border-radius:6px;padding:4px 9px;font:inherit;font-size:11px;cursor:pointer;transition:background .12s ease,border-color .12s ease,color .12s ease}
 .skm-canvas__button:hover:not(:disabled){background:#c8a060;border-color:#c8a060;color:#fff}
+.skm-canvas__button.is-active{background:#c8a060;border-color:#c8a060;color:#fff}
 .skm-canvas__button:disabled{opacity:.45;cursor:default}
 .skm-canvas__error{display:none;padding:8px 12px;background:#280a0a;border-bottom:1px solid #5a1818;color:#f07070;font-size:11px;line-height:1.4;white-space:pre-wrap;flex-shrink:0}
 .skm-canvas__error.is-visible{display:block}
@@ -10851,6 +10864,8 @@ class SketchmarkCanvas {
         this.instance = null;
         this.emitter = new EventEmitter();
         this.dsl = "";
+        this.showCaption = true;
+        this.ttsOverride = null;
         this.panX = 60;
         this.panY = 60;
         this.zoom = 1;
@@ -10938,6 +10953,8 @@ class SketchmarkCanvas {
         this.options = options;
         this.renderer = options.renderer ?? "svg";
         this.theme = options.theme ?? "light";
+        this.showCaption = options.showCaption !== false;
+        this.ttsOverride = typeof options.tts === "boolean" ? options.tts : null;
         this.dsl = normalizeNewlines(options.dsl ?? "");
         injectStyleOnce(CANVAS_STYLE_ID, CANVAS_CSS);
         const host = resolveContainer(options.container);
@@ -10956,6 +10973,8 @@ class SketchmarkCanvas {
         <span class="skm-canvas__status">No steps</span>
         <button type="button" class="skm-canvas__button" data-action="next">Next</button>
         <button type="button" class="skm-canvas__button" data-action="play">Play</button>
+        <button type="button" class="skm-canvas__button" data-action="toggle-caption">Caption On</button>
+        <button type="button" class="skm-canvas__button" data-action="toggle-tts">TTS Off</button>
         <span class="skm-canvas__label"></span>
         <span class="skm-canvas__spacer"></span>
         <span class="skm-canvas__stats"></span>
@@ -10990,6 +11009,8 @@ class SketchmarkCanvas {
         this.prevButton = this.root.querySelector('[data-action="prev"]');
         this.nextButton = this.root.querySelector('[data-action="next"]');
         this.resetButton = this.root.querySelector('[data-action="reset"]');
+        this.captionButton = this.root.querySelector('[data-action="toggle-caption"]');
+        this.ttsButton = this.root.querySelector('[data-action="toggle-tts"]');
         this.gridPattern = this.root.querySelector(`#${patternId}`);
         this.gridDot = this.gridPattern.querySelector("circle");
         this.root.querySelector('[data-action="fit"]')?.addEventListener("click", () => this.fitContent());
@@ -11000,6 +11021,8 @@ class SketchmarkCanvas {
         this.prevButton.addEventListener("click", () => this.prevStep());
         this.nextButton.addEventListener("click", () => this.nextStep());
         this.playButton.addEventListener("click", () => 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);
         this.viewport.addEventListener("pointermove", this.onPointerMove);
         this.viewport.addEventListener("pointerup", this.onStopPanning);
@@ -11021,6 +11044,16 @@ class SketchmarkCanvas {
         if (renderNow)
             this.render();
     }
+    setCaptionVisible(visible) {
+        this.showCaption = visible;
+        this.applyCaptionVisibility(this.instance);
+        this.syncToggleUi();
+    }
+    setTtsEnabled(enabled) {
+        this.ttsOverride = enabled;
+        this.applyTtsSetting(this.instance);
+        this.syncToggleUi();
+    }
     bindEditor(editor, options = {}) {
         this.editorCleanup?.();
         const renderOnRun = options.renderOnRun !== false;
@@ -11065,6 +11098,8 @@ class SketchmarkCanvas {
                 onNodeClick: this.options.onNodeClick,
             });
             this.instance = instance;
+            this.applyCaptionVisibility(instance);
+            this.applyTtsSetting(instance);
             this.statsLabel.textContent = `${instance.scene.nodes.length}n / ${instance.scene.edges.length}e / ${instance.scene.groups.length}g`;
             if (this.renderer === "svg") {
                 this.animUnsub = instance.anim.on((event) => {
@@ -11197,6 +11232,37 @@ class SketchmarkCanvas {
         this.zoom = clampedZoom;
         this.applyTransform();
     }
+    applyCaptionVisibility(instance) {
+        const caption = instance?.anim.captionElement;
+        if (!caption)
+            return;
+        caption.style.display = this.showCaption ? "" : "none";
+        caption.setAttribute("aria-hidden", this.showCaption ? "false" : "true");
+    }
+    applyTtsSetting(instance) {
+        if (!instance || this.ttsOverride === null)
+            return;
+        instance.anim.tts = this.ttsOverride;
+    }
+    getTtsEnabled() {
+        if (this.ttsOverride !== null)
+            return this.ttsOverride;
+        return !!this.instance?.anim.tts;
+    }
+    syncToggleUi() {
+        const canToggleCaption = this.renderer === "svg" && !!this.instance;
+        const canToggleTts = canToggleCaption &&
+            typeof speechSynthesis !== "undefined";
+        const ttsEnabled = this.getTtsEnabled();
+        this.captionButton.textContent = this.showCaption ? "Caption On" : "Caption Off";
+        this.captionButton.classList.toggle("is-active", this.showCaption);
+        this.captionButton.setAttribute("aria-pressed", this.showCaption ? "true" : "false");
+        this.captionButton.disabled = !canToggleCaption;
+        this.ttsButton.textContent = ttsEnabled ? "TTS On" : "TTS Off";
+        this.ttsButton.classList.toggle("is-active", ttsEnabled);
+        this.ttsButton.setAttribute("aria-pressed", ttsEnabled ? "true" : "false");
+        this.ttsButton.disabled = !canToggleTts;
+    }
     syncAnimationUi() {
         const anim = this.instance?.anim;
         const canAnimate = this.renderer === "svg" && !!anim && anim.total > 0;
@@ -11207,6 +11273,7 @@ class SketchmarkCanvas {
             this.nextButton.disabled = true;
             this.resetButton.disabled = true;
             this.playButton.disabled = true;
+            this.syncToggleUi();
             return;
         }
         this.stepDisplay.textContent = anim.currentStep < 0 ? `${anim.total} steps` : `${anim.currentStep + 1} / ${anim.total}`;
@@ -11215,6 +11282,7 @@ class SketchmarkCanvas {
         this.nextButton.disabled = !anim.canNext;
         this.resetButton.disabled = false;
         this.playButton.disabled = this.playInFlight || !anim.canNext;
+        this.syncToggleUi();
     }
     getStepTarget(stepItem) {
         if (!stepItem)
@@ -11914,6 +11982,12 @@ const EMBED_CSS = `
   color: #fff;
 }
 
+.skm-embed__button.is-active {
+  background: #c8a060;
+  border-color: #c8a060;
+  color: #fff;
+}
+
 .skm-embed--dark .skm-embed__button {
   border-color: #4a3520;
   background: #22190e;
@@ -11960,6 +12034,8 @@ class SketchmarkEmbed {
         this.emitter = new EventEmitter();
         this.animUnsub = null;
         this.playInFlight = false;
+        this.showCaption = true;
+        this.ttsOverride = null;
         this.zoom = 1;
         this.offsetX = 0;
         this.offsetY = 0;
@@ -11969,6 +12045,8 @@ class SketchmarkEmbed {
         this.options = options;
         this.dsl = normalizeNewlines(options.dsl);
         this.theme = options.theme ?? "light";
+        this.showCaption = options.showCaption !== false;
+        this.ttsOverride = typeof options.tts === "boolean" ? options.tts : null;
         injectStyleOnce(EMBED_STYLE_ID, EMBED_CSS);
         const host = resolveContainer(options.container);
         host.innerHTML = "";
@@ -11996,6 +12074,10 @@ class SketchmarkEmbed {
           <button type="button" class="skm-embed__button" data-action="next">Next</button>
           <button type="button" class="skm-embed__button" data-action="play">Play</button>
         </div>
+        <div class="skm-embed__controls-group">
+          <button type="button" class="skm-embed__button" data-action="toggle-caption">Caption On</button>
+          <button type="button" class="skm-embed__button" data-action="toggle-tts">TTS Off</button>
+        </div>
         <span class="skm-embed__step">No steps</span>
       </div>
     `;
@@ -12013,6 +12095,8 @@ class SketchmarkEmbed {
         this.btnPrev = this.root.querySelector('[data-action="prev"]');
         this.btnNext = this.root.querySelector('[data-action="next"]');
         this.btnPlay = this.root.querySelector('[data-action="play"]');
+        this.btnCaption = this.root.querySelector('[data-action="toggle-caption"]');
+        this.btnTts = this.root.querySelector('[data-action="toggle-tts"]');
         this.controlsElement.classList.toggle("is-hidden", options.showControls === false);
         this.btnFit.addEventListener("click", () => this.resetView());
         this.btnZoomIn.addEventListener("click", () => this.zoomIn());
@@ -12023,6 +12107,8 @@ class SketchmarkEmbed {
         this.btnPlay.addEventListener("click", () => {
             void this.play();
         });
+        this.btnCaption.addEventListener("click", () => this.setCaptionVisible(!this.showCaption));
+        this.btnTts.addEventListener("click", () => this.setTtsEnabled(!this.getTtsEnabled()));
         if (typeof ResizeObserver !== "undefined") {
             this.resizeObserver = new ResizeObserver(() => {
                 this.positionViewport(false);
@@ -12040,6 +12126,16 @@ class SketchmarkEmbed {
         if (renderNow)
             this.render();
     }
+    setCaptionVisible(visible) {
+        this.showCaption = visible;
+        this.applyCaptionVisibility(this.instance);
+        this.syncToggleControls();
+    }
+    setTtsEnabled(enabled) {
+        this.ttsOverride = enabled;
+        this.applyTtsSetting(this.instance);
+        this.syncToggleControls();
+    }
     setSize(width, height) {
         this.applySize(width, height);
         this.positionViewport(false);
@@ -12084,6 +12180,8 @@ class SketchmarkEmbed {
                 onNodeClick: this.options.onNodeClick,
             });
             this.instance = instance;
+            this.applyCaptionVisibility(instance);
+            this.applyTtsSetting(instance);
             this.animUnsub = instance.anim.on((event) => {
                 this.syncControls();
                 if (event.type === "step-change") {
@@ -12188,6 +12286,7 @@ class SketchmarkEmbed {
     syncControls() {
         this.syncAnimationControls();
         this.syncViewControls();
+        this.syncToggleControls();
     }
     syncAnimationControls() {
         const anim = this.instance?.anim;
@@ -12349,6 +12448,37 @@ class SketchmarkEmbed {
         this.applyTransform();
         this.syncViewControls();
     }
+    applyCaptionVisibility(instance) {
+        const caption = instance?.anim.captionElement;
+        if (!caption)
+            return;
+        caption.style.display = this.showCaption ? "" : "none";
+        caption.setAttribute("aria-hidden", this.showCaption ? "false" : "true");
+    }
+    applyTtsSetting(instance) {
+        if (!instance || this.ttsOverride === null)
+            return;
+        instance.anim.tts = this.ttsOverride;
+    }
+    getTtsEnabled() {
+        if (this.ttsOverride !== null)
+            return this.ttsOverride;
+        return !!this.instance?.anim.tts;
+    }
+    syncToggleControls() {
+        const hasView = !!this.instance?.svg;
+        const canToggleTts = hasView &&
+            typeof speechSynthesis !== "undefined";
+        const ttsEnabled = this.getTtsEnabled();
+        this.btnCaption.textContent = this.showCaption ? "Caption On" : "Caption Off";
+        this.btnCaption.classList.toggle("is-active", this.showCaption);
+        this.btnCaption.setAttribute("aria-pressed", this.showCaption ? "true" : "false");
+        this.btnCaption.disabled = !hasView;
+        this.btnTts.textContent = ttsEnabled ? "TTS On" : "TTS Off";
+        this.btnTts.classList.toggle("is-active", ttsEnabled);
+        this.btnTts.setAttribute("aria-pressed", ttsEnabled ? "true" : "false");
+        this.btnTts.disabled = !canToggleTts;
+    }
     getTargetBox(target, viewportRect) {
         if (target instanceof SVGGraphicsElement) {
             try {