sketchmark 1.1.6 → 1.2.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { parse, ParseError } from "./parser";
 export type { DiagramAST } from "./parser";
+export type { ParseOptions, SketchmarkPlugin } from "./plugins";
 export { buildSceneGraph, nodeMap, groupMap, markdownMap } from "./scene";
 export type { SceneGraph, SceneNode, SceneEdge, SceneGroup, SceneMarkdown, } from "./scene";
 export { layout, connPoint } from "./layout";
@@ -11,7 +12,7 @@ export { AnimationController, ANIMATION_CSS } from "./animation";
 export type { AnimationEvent, AnimationEventType } from "./animation";
 export { exportSVG, exportPNG, exportCanvasPNG, exportHTML, exportGIF, exportMP4, getSVGBlob, svgToPNGDataURL, } from "./export";
 export type { ExportFormat, ExportOptions } from "./export";
-export type { NodeShape, EdgeConnector, LayoutType, AlignItems, JustifyContent, AnimationAction, AnimationTrigger, StyleProps, StepPace, ASTNode, ASTEdge, ASTGroup, ASTStep, ASTBeat, ASTStepItem, ASTChart, ASTTable, GroupChildRef, RootItemRef, ASTMarkdown, } from "./ast/types";
+export type { NodeShape, EdgeConnector, EdgeAnchor, LayoutType, AlignItems, JustifyContent, AnimationAction, AnimationTrigger, StyleProps, StepPace, ASTNode, ASTEdge, ASTGroup, ASTStep, ASTBeat, ASTStepItem, ASTChart, ASTTable, GroupChildRef, RootItemRef, ASTMarkdown, } from "./ast/types";
 export { hashStr, clamp, lerp, parseHex, sleep, throttle, debounce, EventEmitter, } from "./utils";
 export { render } from "./render";
 export type { RenderOptions, DiagramInstance } from "./render";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC1E,YAAY,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EACL,cAAc,EACd,eAAe,EACf,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtE,OAAO,EACL,SAAS,EACT,SAAS,EACT,eAAe,EACf,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG5D,YAAY,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,OAAO,EACP,OAAO,EACP,QAAQ,EACR,OAAO,EACP,OAAO,EACP,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,OAAO,EACP,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,iCAAiC,GAClC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,GACZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC1E,YAAY,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EACL,cAAc,EACd,eAAe,EACf,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtE,OAAO,EACL,SAAS,EACT,SAAS,EACT,eAAe,EACf,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG5D,YAAY,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,OAAO,EACP,OAAO,EACP,QAAQ,EACR,OAAO,EACP,OAAO,EACP,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,OAAO,EACP,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,iCAAiC,GAClC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,GACZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -144,10 +144,16 @@ function tokenize$1(src) {
                         val += "\n";
                     else if (esc === "t")
                         val += "\t";
+                    else if (esc === "r")
+                        val += "\r";
                     else if (esc === "\\")
                         val += "\\";
+                    else if (esc === q)
+                        val += q;
+                    else if (esc)
+                        val += `\\${esc}`;
                     else
-                        val += esc;
+                        val += "\\";
                 }
                 else
                     val += src[i];
@@ -224,6 +230,47 @@ function tokenize$1(src) {
     return tokens;
 }
 
+function pluginMessage(plugin, stage, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return `Plugin "${plugin.name}" ${stage} failed: ${detail}`;
+}
+function applyPluginPreprocessors(source, plugins = []) {
+    let nextSource = source;
+    for (const plugin of plugins) {
+        if (!plugin.preprocess)
+            continue;
+        try {
+            const transformed = plugin.preprocess(nextSource);
+            if (typeof transformed !== "string") {
+                throw new Error("preprocess must return a string");
+            }
+            nextSource = transformed;
+        }
+        catch (error) {
+            throw new Error(pluginMessage(plugin, "preprocess", error));
+        }
+    }
+    return nextSource;
+}
+function applyPluginAstTransforms(ast, plugins = []) {
+    let nextAst = ast;
+    for (const plugin of plugins) {
+        if (!plugin.transformAst)
+            continue;
+        try {
+            const transformed = plugin.transformAst(nextAst);
+            if (!transformed || transformed.kind !== "diagram") {
+                throw new Error('transformAst must return a DiagramAST with kind="diagram"');
+            }
+            nextAst = transformed;
+        }
+        catch (error) {
+            throw new Error(pluginMessage(plugin, "transformAst", error));
+        }
+    }
+    return nextAst;
+}
+
 // ============================================================
 // sketchmark - Parser  (Tokens -> DiagramAST)
 // ============================================================
@@ -310,9 +357,10 @@ function isValueToken(t) {
 function isPropKeyToken(t) {
     return !!t && (t.type === "IDENT" || t.type === "KEYWORD");
 }
-function parse(src) {
+function parse(src, options = {}) {
     resetUid();
-    const tokens = tokenize$1(src).filter((t) => t.type !== "NEWLINE" || t.value === "\n");
+    const preparedSource = applyPluginPreprocessors(src, options.plugins);
+    const tokens = tokenize$1(preparedSource).filter((t) => t.type !== "NEWLINE" || t.value === "\n");
     const flat = [];
     let lastNL = false;
     for (const t of tokens) {
@@ -495,6 +543,7 @@ function parse(src) {
         const toks = lineTokens();
         const id = requireExplicitId(keywordTok, toks);
         const props = parseSimpleProps(toks, 1);
+        const meta = extractNodeMeta(props);
         const node = {
             kind: "node",
             id,
@@ -509,6 +558,7 @@ function parse(src) {
             ...(props.dy ? { dy: parseFloat(props.dy) } : {}),
             ...(props.factor ? { factor: parseFloat(props.factor) } : {}),
             ...(props.theme ? { theme: props.theme } : {}),
+            ...(meta ? { meta } : {}),
             style: propsToStyle(props),
         };
         if (props.url)
@@ -533,12 +583,14 @@ function parse(src) {
             j = 2;
         }
         Object.assign(props, parseSimpleProps(toks, j));
+        const meta = extractNodeMeta(props);
         return {
             kind: "node",
             id,
             shape: "note",
             label: (props.label ?? "").replace(/\\n/g, "\n"),
             theme: props.theme,
+            ...(meta ? { meta } : {}),
             style: propsToStyle(props),
             ...(props.width ? { width: parseFloat(props.width) } : {}),
             ...(props.height ? { height: parseFloat(props.height) } : {}),
@@ -550,6 +602,13 @@ function parse(src) {
             ...(props.factor ? { factor: parseFloat(props.factor) } : {}),
         };
     }
+    function extractNodeMeta(props) {
+        const meta = {};
+        if (props["animation-parent"]) {
+            meta.animationParent = props["animation-parent"];
+        }
+        return Object.keys(meta).length ? meta : undefined;
+    }
     function parseGroup() {
         const keywordTok = cur();
         skip();
@@ -622,6 +681,8 @@ function parse(src) {
             to: toTok.value,
             connector: connector,
             label: props.label,
+            fromAnchor: props["anchor-from"],
+            toAnchor: props["anchor-to"],
             dashed,
             bidirectional,
             style: propsToStyle(props),
@@ -935,6 +996,7 @@ function parse(src) {
             registerAuthoredId(grp.id, "group", t);
             if (isBare) {
                 grp.label = "";
+                grp.padding = grp.padding ?? 0;
                 grp.style = {
                     ...grp.style,
                     fill: grp.style?.fill ?? "none",
@@ -1105,7 +1167,7 @@ function parse(src) {
             node.style = { ...ast.styles[node.id], ...node.style };
         }
     }
-    return ast;
+    return applyPluginAstTransforms(ast, options.plugins);
 }
 
 // ============================================================
@@ -3552,6 +3614,8 @@ function buildSceneGraph(ast) {
         to: e.to,
         connector: e.connector,
         label: e.label,
+        fromAnchor: e.fromAnchor,
+        toAnchor: e.toAnchor,
         dashed: e.dashed ?? false,
         bidirectional: e.bidirectional ?? false,
         style: e.style ?? {},
@@ -4129,28 +4193,13 @@ function connMeta(connector) {
         return { arrowAt: "start", dashed };
     return { arrowAt: "end", dashed };
 }
-// ── Generic rect connection point ────────────────────────────────────────
-function rectConnPoint$1(rx, ry, rw, rh, ox, oy) {
-    const cx = rx + rw / 2, cy = ry + rh / 2;
-    const dx = ox - cx, dy = oy - cy;
-    if (Math.abs(dx) < 0.01 && Math.abs(dy) < 0.01)
-        return [cx, cy];
-    const hw = rw / 2 - 2, hh = rh / 2 - 2;
-    const tx = Math.abs(dx) > 0.01 ? hw / Math.abs(dx) : 1e9;
-    const ty = Math.abs(dy) > 0.01 ? hh / Math.abs(dy) : 1e9;
-    const t = Math.min(tx, ty);
-    return [cx + t * dx, cy + t * dy];
-}
 // ── Resolve an endpoint entity by ID across all maps ─────────────────────
 function resolveEndpoint(id, nm, tm, gm, cm) {
     return nm.get(id) ?? tm.get(id) ?? gm.get(id) ?? cm.get(id) ?? null;
 }
 // ── Get connection point for any entity ──────────────────────────────────
-function getConnPoint(src, dstCX, dstCY) {
-    if ("shape" in src && src.shape) {
-        return connPoint(src, { x: dstCX - 1, y: dstCY - 1, w: 2, h: 2});
-    }
-    return rectConnPoint$1(src.x, src.y, src.w, src.h, dstCX, dstCY);
+function getConnPoint(src, dstCX, dstCY, anchor) {
+    return anchoredConnPoint(src, anchor, dstCX, dstCY);
 }
 // ── Group depth (for paint order) ────────────────────────────────────────
 function groupDepth(g, gm) {
@@ -4585,6 +4634,50 @@ function connPoint(n, other) {
     const t = Math.min(tx, ty);
     return [cx + t * dx, cy + t * dy];
 }
+function clampInset(value) {
+    return Math.max(2, value);
+}
+function anchoredConnPoint(entity, anchor, otherCX, otherCY) {
+    if (!anchor) {
+        if (entity.shape && otherCX != null && otherCY != null) {
+            return connPoint(entity, { x: otherCX - 1, y: otherCY - 1, w: 2, h: 2});
+        }
+        if (otherCX != null && otherCY != null) {
+            return rectConnPoint(entity.x, entity.y, entity.w, entity.h, otherCX, otherCY);
+        }
+        return [entity.x + entity.w / 2, entity.y + entity.h / 2];
+    }
+    const insetX = clampInset(Math.min(10, entity.w / 2));
+    const insetY = clampInset(Math.min(10, entity.h / 2));
+    const left = entity.x + insetX;
+    const right = entity.x + entity.w - insetX;
+    const top = entity.y + insetY;
+    const bottom = entity.y + entity.h - insetY;
+    const cx = entity.x + entity.w / 2;
+    const cy = entity.y + entity.h / 2;
+    switch (anchor) {
+        case "top":
+            return [cx, top];
+        case "right":
+            return [right, cy];
+        case "bottom":
+            return [cx, bottom];
+        case "left":
+            return [left, cy];
+        case "center":
+            return [cx, cy];
+        case "top-left":
+            return [left, top];
+        case "top-right":
+            return [right, top];
+        case "bottom-left":
+            return [left, bottom];
+        case "bottom-right":
+            return [right, bottom];
+        default:
+            return [cx, cy];
+    }
+}
 function rectConnPoint(rx, ry, rw, rh, ox, oy) {
     const cx = rx + rw / 2, cy = ry + rh / 2;
     const dx = ox - cx, dy = oy - cy;
@@ -4616,17 +4709,6 @@ function routeEdges(sg) {
             return c;
         return null;
     }
-    function connPt(src, dstCX, dstCY) {
-        // SceneNode has a .shape field; use the existing connPoint for it
-        if ("shape" in src && src.shape) {
-            return connPoint(src, {
-                x: dstCX - 1,
-                y: dstCY - 1,
-                w: 2,
-                h: 2});
-        }
-        return rectConnPoint(src.x, src.y, src.w, src.h, dstCX, dstCY);
-    }
     for (const e of sg.edges) {
         const src = resolve(e.from);
         const dst = resolve(e.to);
@@ -4636,7 +4718,10 @@ function routeEdges(sg) {
         }
         const dstCX = dst.x + dst.w / 2, dstCY = dst.y + dst.h / 2;
         const srcCX = src.x + src.w / 2, srcCY = src.y + src.h / 2;
-        e.points = [connPt(src, dstCX, dstCY), connPt(dst, srcCX, srcCY)];
+        e.points = [
+            anchoredConnPoint(src, e.fromAnchor, dstCX, dstCY),
+            anchoredConnPoint(dst, e.toAnchor, srcCX, srcCY),
+        ];
     }
 }
 function computeBounds(sg, margin) {
@@ -7777,8 +7862,8 @@ function renderToSVG(sg, container, options = {}) {
             continue;
         const dstCX = dst.x + dst.w / 2, dstCY = dst.y + dst.h / 2;
         const srcCX = src.x + src.w / 2, srcCY = src.y + src.h / 2;
-        const [x1, y1] = getConnPoint(src, dstCX, dstCY);
-        const [x2, y2] = getConnPoint(dst, srcCX, srcCY);
+        const [x1, y1] = getConnPoint(src, dstCX, dstCY, e.fromAnchor);
+        const [x2, y2] = getConnPoint(dst, srcCX, srcCY, e.toAnchor);
         const eg = mkGroup(`edge-${e.from}-${e.to}`, "eg");
         if (e.style?.opacity != null)
             eg.setAttribute("opacity", String(e.style.opacity));
@@ -7855,6 +7940,8 @@ function renderToSVG(sg, container, options = {}) {
         ng.dataset.h = String(n.h);
         if (n.pathData)
             ng.dataset.pathData = n.pathData;
+        if (n.meta?.animationParent)
+            ng.dataset.animationParent = n.meta.animationParent;
         if (n.style?.opacity != null)
             ng.setAttribute("opacity", String(n.style.opacity));
         // ── Static transform (deg, dx, dy, factor) ──────────
@@ -8508,8 +8595,8 @@ function renderToCanvas(sg, canvas, options = {}) {
             continue;
         const dstCX = dst.x + dst.w / 2, dstCY = dst.y + dst.h / 2;
         const srcCX = src.x + src.w / 2, srcCY = src.y + src.h / 2;
-        const [x1, y1] = getConnPoint(src, dstCX, dstCY);
-        const [x2, y2] = getConnPoint(dst, srcCX, srcCY);
+        const [x1, y1] = getConnPoint(src, dstCX, dstCY, e.fromAnchor);
+        const [x2, y2] = getConnPoint(dst, srcCX, srcCY, e.toAnchor);
         if (e.style?.opacity != null)
             ctx.globalAlpha = Number(e.style.opacity);
         const ecol = String(e.style?.stroke ?? palette.edgeStroke);
@@ -9366,6 +9453,13 @@ class AnimationController {
                 this.drawTargetNodes.delete(`node-${s.target}`);
             }
         }
+        this._relatedElementIdsByPrimaryId = this._buildRelatedElementIndex();
+        for (const nodeId of Array.from(this.drawTargetNodes)) {
+            const relatedIds = this._relatedElementIdsByPrimaryId.get(nodeId);
+            if (!relatedIds)
+                continue;
+            relatedIds.forEach((id) => this.drawTargetNodes.add(id));
+        }
         this._drawStepIndexByElementId = this._buildDrawStepIndex();
         const { parentGroupByElementId, groupDescendantIds } = this._buildGroupVisibilityIndex();
         this._parentGroupByElementId = parentGroupByElementId;
@@ -9396,10 +9490,30 @@ class AnimationController {
             const el = resolveNonEdgeDrawEl(this.svg, step.target);
             if (el && !drawStepIndexByElementId.has(el.id)) {
                 drawStepIndexByElementId.set(el.id, stepIndex);
+                this._relatedElementIdsByPrimaryId.get(el.id)?.forEach((relatedId) => {
+                    if (!drawStepIndexByElementId.has(relatedId)) {
+                        drawStepIndexByElementId.set(relatedId, stepIndex);
+                    }
+                });
             }
         });
         return drawStepIndexByElementId;
     }
+    _buildRelatedElementIndex() {
+        const relatedElementIdsByPrimaryId = new Map();
+        this.svg.querySelectorAll(POSITIONABLE_SELECTOR).forEach((el) => {
+            const animationParent = el.dataset.animationParent;
+            if (!animationParent)
+                return;
+            const primaryEl = resolveNonEdgeDrawEl(this.svg, animationParent);
+            if (!primaryEl || primaryEl.id === el.id)
+                return;
+            const related = relatedElementIdsByPrimaryId.get(primaryEl.id) ?? new Set();
+            related.add(el.id);
+            relatedElementIdsByPrimaryId.set(primaryEl.id, related);
+        });
+        return relatedElementIdsByPrimaryId;
+    }
     _buildGroupVisibilityIndex() {
         const parentGroupByElementId = new Map();
         const directChildIdsByGroup = new Map();
@@ -9478,10 +9592,18 @@ class AnimationController {
         const el = resolveEl(this.svg, target);
         if (!el)
             return [];
-        if (!el.id.startsWith("group-"))
-            return [el];
+        if (!el.id.startsWith("group-")) {
+            const ids = new Set([el.id]);
+            this._relatedElementIdsByPrimaryId.get(el.id)?.forEach((id) => ids.add(id));
+            return Array.from(ids)
+                .map((id) => getEl(this.svg, id))
+                .filter((candidate) => candidate != null);
+        }
         const ids = new Set([el.id]);
         this._groupDescendantIds.get(el.id)?.forEach((id) => ids.add(id));
+        Array.from(ids).forEach((id) => {
+            this._relatedElementIdsByPrimaryId.get(id)?.forEach((relatedId) => ids.add(relatedId));
+        });
         return Array.from(ids)
             .map((id) => getEl(this.svg, id))
             .filter((candidate) => candidate != null);
@@ -9890,9 +10012,11 @@ class AnimationController {
     // ── highlight ────────────────────────────────────────────
     _doHighlight(target) {
         this.svg
-            .querySelectorAll(".ng.hl, .tg.hl, .ntg.hl, .cg.hl, .eg.hl")
+            .querySelectorAll(".ng.hl, .gg.hl, .tg.hl, .ntg.hl, .cg.hl, .mdg.hl, .eg.hl")
             .forEach((e) => e.classList.remove("hl"));
-        resolveEl(this.svg, target)?.classList.add("hl");
+        for (const el of this._resolveCascadeTargets(target)) {
+            el.classList.add("hl");
+        }
     }
     // ── fade / unfade ─────────────────────────────────────────
     _doFade(target, doFade) {
@@ -9928,8 +10052,8 @@ class AnimationController {
     }
     // ── move ──────────────────────────────────────────────────
     _doMove(target, step, silent) {
-        const el = resolveEl(this.svg, target);
-        if (!el)
+        const targets = this._resolveCascadeTargets(target);
+        if (!targets.length)
             return;
         const cur = this._transforms.get(target) ?? {
             tx: 0,
@@ -9942,12 +10066,14 @@ class AnimationController {
             tx: cur.tx + (step.dx ?? 0),
             ty: cur.ty + (step.dy ?? 0),
         });
-        this._writeTransform(el, target, silent, step.duration ?? 420);
+        for (const el of targets) {
+            this._writeTransform(el, target, silent, step.duration ?? 420);
+        }
     }
     // ── scale ─────────────────────────────────────────────────
     _doScale(target, step, silent) {
-        const el = resolveEl(this.svg, target);
-        if (!el)
+        const targets = this._resolveCascadeTargets(target);
+        if (!targets.length)
             return;
         const cur = this._transforms.get(target) ?? {
             tx: 0,
@@ -9956,12 +10082,14 @@ class AnimationController {
             rotate: 0,
         };
         this._transforms.set(target, { ...cur, scale: step.factor ?? 1 });
-        this._writeTransform(el, target, silent, step.duration ?? 350);
+        for (const el of targets) {
+            this._writeTransform(el, target, silent, step.duration ?? 350);
+        }
     }
     // ── rotate ────────────────────────────────────────────────
     _doRotate(target, step, silent) {
-        const el = resolveEl(this.svg, target);
-        if (!el)
+        const targets = this._resolveCascadeTargets(target);
+        if (!targets.length)
             return;
         const cur = this._transforms.get(target) ?? {
             tx: 0,
@@ -9973,7 +10101,9 @@ class AnimationController {
             ...cur,
             rotate: cur.rotate + (step.deg ?? 0),
         });
-        this._writeTransform(el, target, silent, step.duration ?? 400);
+        for (const el of targets) {
+            this._writeTransform(el, target, silent, step.duration ?? 400);
+        }
     }
     _doDraw(step, silent) {
         const { target } = step;
@@ -10117,18 +10247,20 @@ class AnimationController {
             return;
         }
         // ── Node draw ──────────────────────────────────────
-        const nodeEl = getNodeEl(this.svg, target);
-        if (!nodeEl)
+        const nodeEls = this._resolveCascadeTargets(target).filter((el) => el.classList.contains("ng"));
+        if (!nodeEls.length)
             return;
-        showDrawEl(nodeEl);
-        if (silent) {
-            revealNodeInstant(nodeEl);
-        }
-        else {
-            if (!nodeGuidePathEl(nodeEl) && !nodeEl.querySelector("path")?.style.strokeDasharray) {
-                prepareNodeForDraw(nodeEl);
+        for (const nodeEl of nodeEls) {
+            showDrawEl(nodeEl);
+            if (silent) {
+                revealNodeInstant(nodeEl);
+            }
+            else {
+                if (!nodeGuidePathEl(nodeEl) && !nodeEl.querySelector("path")?.style.strokeDasharray) {
+                    prepareNodeForDraw(nodeEl);
+                }
+                animateNodeDraw(nodeEl, step.duration ?? ANIMATION.nodeStrokeDur, step.duration ?? ANIMATION.textRevealMs);
             }
-            animateNodeDraw(nodeEl, step.duration ?? ANIMATION.nodeStrokeDur, step.duration ?? ANIMATION.textRevealMs);
         }
     }
     // ── erase ─────────────────────────────────────────────────
@@ -10149,45 +10281,44 @@ class AnimationController {
     }
     // ── pulse ─────────────────────────────────────────────────
     _doPulse(target, duration = 500) {
-        resolveEl(this.svg, target)?.animate([
-            { filter: "brightness(1)" },
-            { filter: "brightness(1.6)" },
-            { filter: "brightness(1)" },
-        ], { duration, iterations: 3 });
+        for (const el of this._resolveCascadeTargets(target)) {
+            el.animate([
+                { filter: "brightness(1)" },
+                { filter: "brightness(1.6)" },
+                { filter: "brightness(1)" },
+            ], { duration, iterations: 3 });
+        }
     }
     // ── color ─────────────────────────────────────────────────
     _doColor(target, color) {
         if (!color)
             return;
-        const el = resolveEl(this.svg, target);
-        if (!el)
-            return;
-        // edge — color stroke
-        if (parseEdgeTarget(target)) {
-            el.querySelectorAll("path, line, polyline").forEach((p) => {
-                p.style.stroke = color;
-            });
-            el.querySelectorAll("polygon").forEach((p) => {
-                p.style.fill = color;
-                p.style.stroke = color;
-            });
-            return;
-        }
-        // everything else — color fill
-        let hit = false;
-        el.querySelectorAll("path, rect, ellipse, polygon").forEach((c) => {
-            const attrFill = c.getAttribute("fill");
-            if (attrFill === "none")
-                return;
-            if (attrFill === null && c.tagName === "path")
-                return;
-            c.style.fill = color;
-            hit = true;
-        });
-        if (!hit) {
-            el.querySelectorAll("text").forEach((t) => {
-                t.style.fill = color;
+        for (const el of this._resolveCascadeTargets(target)) {
+            if (parseEdgeTarget(target)) {
+                el.querySelectorAll("path, line, polyline").forEach((p) => {
+                    p.style.stroke = color;
+                });
+                el.querySelectorAll("polygon").forEach((p) => {
+                    p.style.fill = color;
+                    p.style.stroke = color;
+                });
+                continue;
+            }
+            let hit = false;
+            el.querySelectorAll("path, rect, ellipse, polygon").forEach((c) => {
+                const attrFill = c.getAttribute("fill");
+                if (attrFill === "none")
+                    return;
+                if (attrFill === null && c.tagName === "path")
+                    return;
+                c.style.fill = color;
+                hit = true;
             });
+            if (!hit) {
+                el.querySelectorAll("text").forEach((t) => {
+                    t.style.fill = color;
+                });
+            }
         }
     }
     // ── narration ───────────────────────────────────────────
@@ -10781,7 +10912,7 @@ class EventEmitter {
 }
 
 function render(options) {
-    const { container: rawContainer, dsl, renderer = "svg", injectCSS = true, tts, svgOptions = {}, canvasOptions = {}, onNodeClick, onReady, } = options;
+    const { container: rawContainer, dsl, plugins, 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";
@@ -10797,7 +10928,7 @@ function render(options) {
     else {
         el = rawContainer;
     }
-    const ast = parse(dsl);
+    const ast = parse(dsl, { plugins });
     const scene = buildSceneGraph(ast);
     layout(scene);
     let svg;
@@ -11141,6 +11272,7 @@ class SketchmarkCanvas {
             const instance = render({
                 container: this.diagramWrap,
                 dsl: this.dsl,
+                plugins: this.options.plugins,
                 renderer: this.renderer,
                 svgOptions: { interactive: true, showTitle: true, theme: this.options.svgOptions?.theme ?? this.theme, ...this.options.svgOptions },
                 canvasOptions: this.options.canvasOptions,
@@ -12218,6 +12350,7 @@ class SketchmarkEmbed {
             const instance = render({
                 container: this.diagramWrap,
                 dsl: this.dsl,
+                plugins: this.options.plugins,
                 renderer: "svg",
                 svgOptions: {
                     showTitle: true,