sketchmark 1.0.2 → 1.0.3

package/README.md

@@ -587,7 +587,7 @@ step <action> <target> [options]
 | Action | Target | Options | Description |
 |--------|--------|---------|-------------|
 | `highlight` | node/edge/group | — | Pulsing glow highlight (only one element at a time) |
-| `draw` | node/edge/group/table/chart/markdown | `duration=N` | Animated stroke-drawing reveal with text writing effect |
+| `draw` | node/edge/group/table/chart/markdown | `duration=N` | Animated reveal; drawing a group also reveals its subtree unless descendants have their own later draw step |
 | `fade` | node/edge/group | — | Fade to 22% opacity |
 | `unfade` | node/edge/group | — | Restore from fade |
 | `erase` | node/edge/group | `duration=N` | Fade to invisible (opacity 0) |
@@ -805,11 +805,25 @@ config pointer=hand     # hand cursor
 
 The pointer only appears during annotation steps — it follows the guide path as the annotation draws in, then fades out.
 
-### Pre-hidden Elements (Draw Targets)
-
-Any element targeted by a `step draw` action starts **hidden** and only appears when that step fires. Elements NOT targeted by `draw` are always visible.
-
----
+### Pre-hidden Elements (Draw Targets)
+
+Any element targeted by a `step draw` action starts **hidden** and only appears when that step fires. Elements NOT targeted by `draw` are always visible.
+
+For groups, this applies to the whole subtree:
+
+- `step draw group1` pre-hides the group and all descendant nodes, nested groups, tables, charts, notes, and markdown blocks.
+- When the group step fires, descendants without their own later `draw` step are revealed immediately.
+- Descendants with an explicit later `draw` step stay hidden until that later step.
+- Edges are still independent; a group draw does not automatically reveal connected edges.
+
+For group targets, these actions also apply recursively to the same subtree:
+
+- `fade` / `unfade`
+- `show` / `hide`
+- `erase`
+- Edges still remain explicit for these actions too.
+
+---
 
 ## Config Options
 
@@ -1193,4 +1207,4 @@ interface DiagramInstance {
 3. **Animation only works with SVG renderer** — the canvas renderer does not support animated steps.
 4. **`step draw` makes elements start hidden** — any element you intend to `draw` will be invisible until its step fires.
 5. **Node IDs must be unique** — duplicate IDs are silently deduplicated (only first definition kept).
-6. **Group children inherit group's coordinate space** — edges can connect across group boundaries using the node/group ID directly.
+6. **Group children inherit group's coordinate space** — edges can connect across group boundaries using the node/group ID directly.

package/dist/animation/index.d.ts

@@ -29,6 +29,9 @@ export declare class AnimationController {
     readonly drawTargetNotes: Set<string>;
     readonly drawTargetCharts: Set<string>;
     readonly drawTargetMarkdowns: Set<string>;
+    private readonly _drawStepIndexByElementId;
+    private readonly _parentGroupByElementId;
+    private readonly _groupDescendantIds;
     private _captionEl;
     private _captionTextEl;
     private _annotationLayer;
@@ -39,6 +42,12 @@ export declare class AnimationController {
     private _speechDone;
     get drawTargets(): Set<string>;
     constructor(svg: SVGSVGElement, steps: ASTStepItem[], _container?: HTMLElement | undefined, _rc?: any | undefined, _config?: Record<string, string | number | boolean> | undefined);
+    private _buildDrawStepIndex;
+    private _buildGroupVisibilityIndex;
+    private _hideGroupDescendants;
+    private _isDeferredForGroupReveal;
+    private _revealGroupSubtree;
+    private _resolveCascadeTargets;
     /** The narration caption element — mount it anywhere via `yourContainer.appendChild(anim.captionElement)` */
     get captionElement(): HTMLDivElement | null;
     /** Enable/disable browser text-to-speech for narrate steps */

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":"AAIA,OAAO,KAAK,EAAoB,WAAW,EAAE,MAAM,cAAc,CAAC;AAGlE,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,CAAC;AACpB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;AAoZ5D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAQtE;AACD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAOtE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAOvE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAOtE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAOvE;AAsKD,qBAAa,mBAAmB;IA6C5B,OAAO,CAAC,GAAG;aACK,KAAK,EAAE,WAAW,EAAE;IACpC,OAAO,CAAC,UAAU,CAAC;IACnB,OAAO,CAAC,GAAG,CAAC;IACZ,OAAO,CAAC,OAAO,CAAC;IAhDlB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,WAAW,CAQf;IACJ,OAAO,CAAC,UAAU,CAA2B;IAC7C,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAsB;IAChE,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAsB;IAC9D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA2B;IAG/D,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,cAAc,CAAgC;IAGtD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,YAAY,CAAoB;IAGxC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,YAAY,CAA6C;IAGjE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,WAAW,CAA8B;IAEjD,IAAI,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC,CAE7B;gBAGS,GAAG,EAAE,aAAa,EACV,KAAK,EAAE,WAAW,EAAE,EAC5B,UAAU,CAAC,EAAE,WAAW,YAAA,EACxB,GAAG,CAAC,EAAE,GAAG,YAAA,EACT,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,YAAA;IA6D7D,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,0BAA0B;IA4ClC,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,yBAAyB;IAiBjC,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,sBAAsB;IAmB9B,6GAA6G;IAC7G,IAAI,cAAc,IAAI,cAAc,GAAG,IAAI,CAE1C;IAED,8DAA8D;IAC9D,IAAI,GAAG,IAAI,OAAO,CAAsB;IACxC,IAAI,GAAG,CAAC,EAAE,EAAE,OAAO,EAAoD;IAEvE,IAAI,WAAW,IAAI,MAAM,CAExB;IACD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,OAAO,IAAI,OAAO,CAErB;IACD,IAAI,OAAO,IAAI,OAAO,CAErB;IACD,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,EAAE,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAM3C,OAAO,CAAC,IAAI;IAUZ,KAAK,IAAI,IAAI;IAMb,uDAAuD;IACvD,OAAO,IAAI,IAAI;IAWf,IAAI,IAAI,OAAO;IASf,IAAI,IAAI,OAAO;IAST,IAAI,CAAC,SAAS,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAczB,OAAO,CAAC,uBAAuB;IAK/B,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,WAAW;IA8BnB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,SAAS;IAwIjB,OAAO,CAAC,UAAU;IAsBlB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,QAAQ;IA+DhB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,eAAe;IAmCvB,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,OAAO;IA4Kf,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,QAAQ;IAoChB,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,UAAU;IAwBlB,OAAO,CAAC,MAAM;IAed,OAAO,CAAC,aAAa;IAKrB,uFAAuF;IACvF,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,YAAY;IASpB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IA2E1B,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,qBAAqB;IAyB7B,OAAO,CAAC,iBAAiB;IAwCzB,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,oBAAoB;IA+B5B,OAAO,CAAC,YAAY;CAkCrB;AAED,eAAO,MAAM,aAAa,wjCAoCzB,CAAC"}

package/dist/index.cjs

@@ -7703,6 +7703,21 @@ function mkGroup(id, cls) {
         g.setAttribute("class", cls);
     return g;
 }
+function buildParentGroupLookup(sg) {
+    const parentGroups = new Map();
+    for (const g of sg.groups) {
+        if (g.parentId)
+            parentGroups.set(`group:${g.id}`, g.parentId);
+        for (const child of g.children) {
+            parentGroups.set(`${child.kind}:${child.id}`, g.id);
+        }
+    }
+    return parentGroups;
+}
+function setParentGroupData(el, groupId) {
+    if (groupId)
+        el.dataset.parentGroup = groupId;
+}
 // ── Node shapes ───────────────────────────────────────────────────────────
 function renderShape$1(rc, n, palette) {
     const s = n.style ?? {};
@@ -7799,6 +7814,7 @@ function renderToSVG(sg, container, options = {}) {
     }
     // ── Groups ───────────────────────────────────────────────
     const gmMap = new Map(sg.groups.map((g) => [g.id, g]));
+    const parentGroups = buildParentGroupLookup(sg);
     const sortedGroups = [...sg.groups].sort((a, b) => groupDepth(a, gmMap) - groupDepth(b, gmMap));
     const GL = mkGroup("grp-layer");
     for (const g of sortedGroups) {
@@ -7806,6 +7822,7 @@ function renderToSVG(sg, container, options = {}) {
             continue;
         const gs = g.style ?? {};
         const gg = mkGroup(`group-${g.id}`, "gg");
+        setParentGroupData(gg, g.parentId);
         if (gs.opacity != null)
             gg.setAttribute("opacity", String(gs.opacity));
         gg.appendChild(rc.rectangle(g.x, g.y, g.w, g.h, {
@@ -7910,6 +7927,7 @@ function renderToSVG(sg, container, options = {}) {
         const idPrefix = shapeDef?.idPrefix ?? "node";
         const cssClass = shapeDef?.cssClass ?? "ng";
         const ng = mkGroup(`${idPrefix}-${n.id}`, cssClass);
+        setParentGroupData(ng, n.groupId ?? parentGroups.get(`node:${n.id}`));
         ng.dataset.nodeShape = n.shape;
         ng.dataset.x = String(n.x);
         ng.dataset.y = String(n.y);
@@ -7991,6 +8009,7 @@ function renderToSVG(sg, container, options = {}) {
     const TL = mkGroup("table-layer");
     for (const t of sg.tables) {
         const tg = mkGroup(`table-${t.id}`, "tg");
+        setParentGroupData(tg, parentGroups.get(`table:${t.id}`));
         const gs = t.style ?? {};
         const fill = String(gs.fill ?? palette.tableFill);
         const strk = String(gs.stroke ?? palette.tableStroke);
@@ -8091,6 +8110,7 @@ function renderToSVG(sg, container, options = {}) {
     const MDL = mkGroup('markdown-layer');
     for (const m of sg.markdowns) {
         const mg = mkGroup(`markdown-${m.id}`, 'mdg');
+        setParentGroupData(mg, parentGroups.get(`markdown:${m.id}`));
         const gs = m.style ?? {};
         const mFont = resolveStyleFont(gs, diagramFont);
         const baseColor = String(gs.color ?? palette.nodeText);
@@ -8154,7 +8174,9 @@ function renderToSVG(sg, container, options = {}) {
     // ── Charts ────────────────────────────────────────────────
     const CL = mkGroup("chart-layer");
     for (const c of sg.charts) {
-        CL.appendChild(renderRoughChartSVG(rc, c, palette, themeName !== "light"));
+        const cg = renderRoughChartSVG(rc, c, palette, themeName !== "light");
+        setParentGroupData(cg, parentGroups.get(`chart:${c.id}`));
+        CL.appendChild(cg);
     }
     svg.appendChild(CL);
     return svg;
@@ -8867,18 +8889,33 @@ const getTableEl = (svg, id) => getEl(svg, `table-${id}`);
 const getNoteEl = (svg, id) => getEl(svg, `note-${id}`);
 const getChartEl = (svg, id) => getEl(svg, `chart-${id}`);
 const getMarkdownEl = (svg, id) => getEl(svg, `markdown-${id}`);
+const POSITIONABLE_SELECTOR = ".ng, .gg, .tg, .ntg, .cg, .mdg";
+function resolveNonEdgeDrawEl(svg, target) {
+    return (getGroupEl(svg, target) ??
+        getTableEl(svg, target) ??
+        getNoteEl(svg, target) ??
+        getChartEl(svg, target) ??
+        getMarkdownEl(svg, target) ??
+        getNodeEl(svg, target) ??
+        null);
+}
+function hideDrawEl(el) {
+    if (el.classList.contains("ng")) {
+        el.classList.add("hidden");
+        return;
+    }
+    el.classList.add("gg-hidden");
+}
+function showDrawEl(el) {
+    el.classList.remove("hidden", "gg-hidden");
+}
 function resolveEl(svg, target) {
     // check edge first — target contains connector like "a-->b"
     const edge = parseEdgeTarget(target);
     if (edge)
         return getEdgeEl(svg, edge.from, edge.to);
     // everything else resolved by prefixed id
-    return (getNodeEl(svg, target) ??
-        getGroupEl(svg, target) ??
-        getTableEl(svg, target) ??
-        getNoteEl(svg, target) ??
-        getChartEl(svg, target) ??
-        getMarkdownEl(svg, target) ??
+    return (resolveNonEdgeDrawEl(svg, target) ??
         null);
 }
 function pathLength(p) {
@@ -9068,6 +9105,7 @@ function prepareNodeForDraw(el) {
     el.appendChild(guide);
 }
 function revealNodeInstant(el) {
+    showDrawEl(el);
     clearNodeDrawStyles(el);
 }
 // ── Text writing reveal (clipPath) ───────────────────────
@@ -9116,6 +9154,7 @@ function animateTextReveal(textEl, delayMs, durationMs = ANIMATION.textRevealMs)
     }, delayMs);
 }
 function animateNodeDraw(el, strokeDur = ANIMATION.nodeStrokeDur) {
+    showDrawEl(el);
     const guide = nodeGuidePathEl(el);
     if (!guide) {
         const firstPath = el.querySelector("path");
@@ -9170,6 +9209,15 @@ function flattenSteps(items) {
     }
     return out;
 }
+function forEachPlaybackStep(items, visit) {
+    items.forEach((item, stepIndex) => {
+        if (item.kind === "beat") {
+            item.children.forEach((child) => visit(child, stepIndex));
+            return;
+        }
+        visit(item, stepIndex);
+    });
+}
 // ── Draw target helpers ───────────────────────────────────
 function getDrawTargetEdgeIds(steps) {
     const ids = new Set();
@@ -9354,7 +9402,7 @@ class AnimationController {
         for (const s of flattenSteps(steps)) {
             if (s.action !== "draw" || parseEdgeTarget(s.target))
                 continue;
-            if (svg.querySelector(`#group-${s.target}`)) {
+            if (resolveNonEdgeDrawEl(svg, s.target)?.id === `group-${s.target}`) {
                 this.drawTargetGroups.add(`group-${s.target}`);
                 this.drawTargetNodes.delete(`node-${s.target}`);
             }
@@ -9375,6 +9423,10 @@ class AnimationController {
                 this.drawTargetNodes.delete(`node-${s.target}`);
             }
         }
+        this._drawStepIndexByElementId = this._buildDrawStepIndex();
+        const { parentGroupByElementId, groupDescendantIds } = this._buildGroupVisibilityIndex();
+        this._parentGroupByElementId = parentGroupByElementId;
+        this._groupDescendantIds = groupDescendantIds;
         this._clearAll();
         // Init narration caption
         if (this._container)
@@ -9393,6 +9445,104 @@ class AnimationController {
         if (this._tts)
             this._warmUpSpeech();
     }
+    _buildDrawStepIndex() {
+        const drawStepIndexByElementId = new Map();
+        forEachPlaybackStep(this.steps, (step, stepIndex) => {
+            if (step.action !== "draw" || parseEdgeTarget(step.target))
+                return;
+            const el = resolveNonEdgeDrawEl(this.svg, step.target);
+            if (el && !drawStepIndexByElementId.has(el.id)) {
+                drawStepIndexByElementId.set(el.id, stepIndex);
+            }
+        });
+        return drawStepIndexByElementId;
+    }
+    _buildGroupVisibilityIndex() {
+        const parentGroupByElementId = new Map();
+        const directChildIdsByGroup = new Map();
+        this.svg.querySelectorAll(POSITIONABLE_SELECTOR).forEach((el) => {
+            const parentGroupId = el.dataset.parentGroup;
+            if (!parentGroupId)
+                return;
+            const parentGroupElId = `group-${parentGroupId}`;
+            parentGroupByElementId.set(el.id, parentGroupElId);
+            const children = directChildIdsByGroup.get(parentGroupElId) ?? new Set();
+            children.add(el.id);
+            directChildIdsByGroup.set(parentGroupElId, children);
+        });
+        const groupDescendantIds = new Map();
+        const visit = (groupElId) => {
+            if (groupDescendantIds.has(groupElId))
+                return groupDescendantIds.get(groupElId);
+            const descendants = new Set();
+            const directChildren = directChildIdsByGroup.get(groupElId);
+            if (directChildren) {
+                for (const childId of directChildren) {
+                    descendants.add(childId);
+                    if (childId.startsWith("group-")) {
+                        visit(childId).forEach((nestedId) => descendants.add(nestedId));
+                    }
+                }
+            }
+            groupDescendantIds.set(groupElId, descendants);
+            return descendants;
+        };
+        this.svg.querySelectorAll(".gg").forEach((el) => {
+            visit(el.id);
+        });
+        return { parentGroupByElementId, groupDescendantIds };
+    }
+    _hideGroupDescendants(groupElId) {
+        const descendants = this._groupDescendantIds.get(groupElId);
+        if (!descendants)
+            return;
+        for (const descendantId of descendants) {
+            const el = getEl(this.svg, descendantId);
+            if (el)
+                hideDrawEl(el);
+        }
+    }
+    _isDeferredForGroupReveal(elementId, stepIndex, groupElId) {
+        let currentId = elementId;
+        while (currentId) {
+            const firstDrawStep = this._drawStepIndexByElementId.get(currentId);
+            if (firstDrawStep != null && firstDrawStep > stepIndex)
+                return true;
+            if (currentId === groupElId)
+                break;
+            currentId = this._parentGroupByElementId.get(currentId);
+        }
+        return false;
+    }
+    _revealGroupSubtree(groupElId, stepIndex) {
+        const descendants = this._groupDescendantIds.get(groupElId);
+        if (!descendants)
+            return;
+        for (const descendantId of descendants) {
+            if (this._isDeferredForGroupReveal(descendantId, stepIndex, groupElId))
+                continue;
+            const el = getEl(this.svg, descendantId);
+            if (el)
+                showDrawEl(el);
+        }
+    }
+    _resolveCascadeTargets(target) {
+        const edge = parseEdgeTarget(target);
+        if (edge) {
+            const el = getEdgeEl(this.svg, edge.from, edge.to);
+            return el ? [el] : [];
+        }
+        const el = resolveEl(this.svg, target);
+        if (!el)
+            return [];
+        if (!el.id.startsWith("group-"))
+            return [el];
+        const ids = new Set([el.id]);
+        this._groupDescendantIds.get(el.id)?.forEach((id) => ids.add(id));
+        return Array.from(ids)
+            .map((id) => getEl(this.svg, id))
+            .filter((candidate) => candidate != null);
+    }
     /** The narration caption element — mount it anywhere via `yourContainer.appendChild(anim.captionElement)` */
     get captionElement() {
         return this._captionEl;
@@ -9662,6 +9812,9 @@ class AnimationController {
             el.style.opacity = "";
             el.classList.remove("hl", "faded");
         });
+        for (const groupElId of this.drawTargetGroups) {
+            this._hideGroupDescendants(groupElId);
+        }
         // Clear narration caption
         if (this._captionEl) {
             this._captionEl.style.opacity = "0";
@@ -9724,7 +9877,7 @@ class AnimationController {
                 this._doDraw(s, silent);
                 break;
             case "erase":
-                this._doErase(s.target, s.duration);
+                this._doErase(s.target, silent, s.duration);
                 break;
             case "show":
                 this._doShowHide(s.target, true, silent, s.duration);
@@ -9780,7 +9933,9 @@ class AnimationController {
     }
     // ── fade / unfade ─────────────────────────────────────────
     _doFade(target, doFade) {
-        resolveEl(this.svg, target)?.classList.toggle("faded", doFade);
+        for (const el of this._resolveCascadeTargets(target)) {
+            el.classList.toggle("faded", doFade);
+        }
     }
     _writeTransform(el, target, silent, duration = 420) {
         const t = this._transforms.get(target) ?? {
@@ -9879,11 +10034,12 @@ class AnimationController {
         // Check if target is a group (has #group-{target} element)
         const groupEl = getGroupEl(this.svg, target);
         if (groupEl) {
+            showDrawEl(groupEl);
+            this._revealGroupSubtree(groupEl.id, this._step);
             // ── Group draw ──────────────────────────────────────
             if (silent) {
                 clearDrawStyles(groupEl);
                 groupEl.style.transition = "none";
-                groupEl.classList.remove("gg-hidden");
                 groupEl.style.opacity = "1";
                 requestAnimationFrame(() => requestAnimationFrame(() => {
                     groupEl.style.transition = "";
@@ -9891,7 +10047,6 @@ class AnimationController {
                 }));
             }
             else {
-                groupEl.classList.remove("gg-hidden");
                 // Groups use slightly longer stroke-draw (bigger box, dashed border = more paths)
                 const firstPath = groupEl.querySelector("path");
                 if (!firstPath?.style.strokeDasharray)
@@ -10002,6 +10157,7 @@ class AnimationController {
         const nodeEl = getNodeEl(this.svg, target);
         if (!nodeEl)
             return;
+        showDrawEl(nodeEl);
         if (silent) {
             revealNodeInstant(nodeEl);
         }
@@ -10013,20 +10169,20 @@ class AnimationController {
         }
     }
     // ── erase ─────────────────────────────────────────────────
-    _doErase(target, duration = 400) {
-        const el = resolveEl(this.svg, target); // handles edges too now
-        if (el) {
-            el.style.transition = `opacity ${duration}ms`;
+    _doErase(target, silent, duration = 400) {
+        for (const el of this._resolveCascadeTargets(target)) {
+            el.style.transition = silent ? "none" : `opacity ${duration}ms`;
             el.style.opacity = "0";
         }
     }
     // ── show / hide ───────────────────────────────────────────
     _doShowHide(target, show, silent, duration = 400) {
-        const el = resolveEl(this.svg, target);
-        if (!el)
-            return;
-        el.style.transition = silent ? "none" : `opacity ${duration}ms`;
-        el.style.opacity = show ? "1" : "0";
+        for (const el of this._resolveCascadeTargets(target)) {
+            if (show)
+                showDrawEl(el);
+            el.style.transition = silent ? "none" : `opacity ${duration}ms`;
+            el.style.opacity = show ? "1" : "0";
+        }
     }
     // ── pulse ─────────────────────────────────────────────────
     _doPulse(target, duration = 500) {