@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/railroadDiagram.js

@@ -0,0 +1,571 @@
+/*
+This is a simplified implementation based on the excellent railroad-diagrams library by Tab Atkins.
+Original project: https://github.com/tabatkins/railroad-diagrams
+*/
+
+export function Diagram(...items) {
+    return new DiagramNode('Diagram', { items: wrapAndFlatten(items) });
+}
+
+export function Sequence(...items) {
+    return new DiagramNode('Sequence', { items: wrapAndFlatten(items) });
+}
+
+export function Choice(normal, ...items) {
+    return new DiagramNode('Choice', { normal, items: wrapAndFlatten(items) });
+}
+
+export function Optional(item, skip) {
+    return new DiagramNode('Optional', { item: wrap(item), skip });
+}
+
+export function OneOrMore(item, repeat) {
+    return new DiagramNode('OneOrMore', { item: wrap(item), repeat: wrap(repeat) });
+}
+
+export function ZeroOrMore(item, repeat, skip) {
+    return new DiagramNode('ZeroOrMore', { item: wrap(item), repeat: wrap(repeat), skip });
+}
+
+export function Terminal(text, href, title) {
+    return new DiagramNode('Terminal', { text, href, title });
+}
+
+export function NonTerminal(text, href, title) {
+    return new DiagramNode('NonTerminal', { text, href, title });
+}
+
+export function Comment(text, href, title) {
+    return new DiagramNode('Comment', { text, href, title });
+}
+
+export function Skip() {
+    return new DiagramNode('Skip');
+}
+
+export function Difference(item1, item2) {
+    return new DiagramNode('Difference', { item1: wrap(item1), item2: wrap(item2) });
+}
+
+
+class DiagramNode {
+    constructor(type, data = {}) {
+        this.type = type;
+        Object.assign(this, data);
+        this.needsSpace = false;
+    }
+
+    format() {
+        // This is a placeholder for a method that would typically handle layout calculations.
+        // In our case, the rendering logic is in the RenderEngine's renderers.
+        return this;
+    }
+
+    walk(cb) {
+        cb(this);
+        for (const key of ['item', 'item1', 'item2', 'repeat']) {
+            if (this[key] && this[key].walk) {
+                this[key].walk(cb);
+            }
+        }
+        if (this.items) {
+            this.items.forEach(item => item.walk && item.walk(cb));
+        }
+    }
+
+    addTo(parent) {
+        if (parent) {
+            parent.items = parent.items || [];
+            parent.items.push(this);
+        }
+        return this;
+    }
+}
+
+function wrap(item) {
+    return typeof item === 'string' ? new Terminal(item) : item;
+}
+
+function wrapAndFlatten(items) {
+    return items.flat(Infinity).map(wrap);
+}
+
+
+/*
+The following are simple stubs for the formatting part of the original library.
+The actual rendering is handled by SVGRenderer and CanvasRenderer.
+*/
+
+// Every node — regardless of which factory function built it (Terminal,
+// Sequence, Choice, ...) — is constructed via `new DiagramNode(type, data)`
+// directly (see the factory functions above), never `new Terminal(...)`
+// etc. So every instance's real prototype is DiagramNode.prototype, full
+// stop; per-type `Terminal.prototype`/`Choice.prototype`/... objects are
+// never actually consulted by JS's own prototype-chain lookup. Dispatch by
+// `.type` explicitly instead, via this table, rather than (as this file
+// used to) aliasing every factory's `.prototype` to the SAME
+// DiagramNode.prototype object and assigning `.format` on it once per
+// type — each such assignment silently overwrote the previous one, so only
+// the last one (Skip's, a complete no-op) ever actually ran, for every
+// node type. `Difference` has no entry — never implemented in this
+// simplified port; hitting it throws a clear error below rather than
+// silently doing nothing.
+const FORMATTERS = {};
+
+
+/*
+This section would normally contain complex SVG path generation logic.
+Since our RenderEngine handles drawing, we can omit the complex parts.
+The classes and their structure are what's important for the EBNFEngine and RenderEngine to work together.
+*/
+
+// A plain object factory, not a `this`-dependent constructor — every call
+// site invokes this as `FakeSVG(...)` (no `new`), and this file is an ES
+// module (strict mode), where a non-`new` call has `this === undefined`;
+// the old `if (text) this.text = text; return this;` body either threw
+// (assigning onto undefined) or returned undefined outright, so the very
+// next `.addTo(...)` in the same expression always failed. Sets attrs
+// BOTH flat on the object (`item.x`, `item.width`, ... — what
+// SVGRenderer.renderDiagram reads) and nested under `.attrs` (`item.attrs.x`,
+// ... — what this file's own DiagramNode.prototype.drawOn Canvas path
+// reads) so both renderer backends work off one shape.
+function FakeSVG(tagName, attrs = {}, text) {
+    // Built on DiagramNode.prototype purely for its generic .addTo() (every
+    // call site immediately does `FakeSVG(...).addTo(parentNode)`) — these
+    // are leaf rendering primitives (rect/text/path/svg/style), never
+    // DiagramNode-tree nodes themselves, so inheriting .format()'s
+    // FORMATTERS dispatch is inert (nothing calls .format() on one).
+    const el = Object.assign(Object.create(DiagramNode.prototype), { type: tagName, tagName, attrs });
+    Object.assign(el, attrs);
+    if (text) el.text = text;
+    return el;
+}
+
+function determineGaps(outer, inner) {
+    var diff = outer - inner;
+    switch (diff % 2) {
+        case 0:
+            return [diff / 2, diff / 2];
+        case 1:
+            return [Math.floor(diff / 2), Math.ceil(diff / 2)];
+    }
+}
+
+function Path(x, y) {
+    this.x = x;
+    this.y = y;
+    this.attrs = {
+        d: "M" + x + " " + y
+    };
+}
+Path.prototype.m = function (x, y) {
+    this.attrs.d += "m" + x + " " + y;
+    return this;
+};
+Path.prototype.h = function (val) {
+    this.attrs.d += "h" + val;
+    return this;
+};
+Path.prototype.right = Path.prototype.h;
+Path.prototype.left = function (val) {
+    return this.h(-val);
+};
+Path.prototype.v = function (val) {
+    this.attrs.d += "v" + val;
+    return this;
+};
+Path.prototype.down = Path.prototype.v;
+Path.prototype.up = function (val) {
+    return this.v(-val);
+};
+// `code` is a 2-letter compass direction pair: code[0] is the direction the
+// path is heading INTO the corner, code[1] is the direction it's heading
+// OUT of the corner (e.g. 'se' = arriving heading south, departing heading
+// east) — always a quarter (90 degree) turn of radius AR.
+//
+// Derived from first principles (not the original upstream library's own
+// convention, and not the previous version of this function, which computed
+// a provably wrong result — see below): for two perpendicular unit
+// direction vectors D_in/D_out, the endpoint offset of the connecting arc is
+// exactly AR*(D_in + D_out) — verified against 3 independently-worked
+// examples (south-to-east, east-to-north, north-to-east) using the
+// standard "rotate the outward radius 90 degrees" identity for circular
+// motion. The turn is a visual right turn (clockwise, SVG sweep-flag 1) if
+// D_out is next after D_in in the N->E->S->W->N sequence, otherwise a left
+// turn (counterclockwise, sweep-flag 0).
+//
+// The previous version of this function set the LARGE-ARC-FLAG to 1 for
+// exactly the 4 codes actually used elsewhere in this file (ne/se/sw/nw) —
+// backwards; a large-arc-flag forces SVG to draw the *major* (270 degree)
+// arc of the circle instead of the intended *minor* (90 degree) one,
+// producing a huge, visually wrong loop that still technically starts/ends
+// at the right two points, which is exactly what a "large arc" bug looks
+// like from the outside. Every quarter-turn in this file is a minor arc, so
+// the large-arc-flag is always 0 here — there is no case that needs 1.
+var COMPASS = { n: [0, -1], s: [0, 1], e: [1, 0], w: [-1, 0] };
+var CLOCKWISE_NEXT = { n: 'e', e: 's', s: 'w', w: 'n' };
+Path.prototype.arc = function (code) {
+    var AR = 10;
+    var din = COMPASS[code[0]];
+    var dout = COMPASS[code[1]];
+    var dx = AR * (din[0] + dout[0]);
+    var dy = AR * (din[1] + dout[1]);
+    var sweepFlag = CLOCKWISE_NEXT[code[0]] === code[1] ? 1 : 0;
+    this.attrs.d += "a" + AR + " " + AR + " 0 0 " + sweepFlag + " " + dx + " " + dy;
+    return this;
+};
+Path.prototype.format = function () {
+    return FakeSVG("path", this.attrs);
+};
+
+function escapeString(s) {
+    if (!s) return "";
+    return s.replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+function drawPath(item, diagram) {
+    var path = new Path(item.x, item.y);
+    var current = item;
+    while (current.type != 'Start') {
+        if (current.type === 'path') {
+            path.attrs.d = current.attrs.d + path.attrs.d;
+        }
+        [path, current] = drawPath(current.from, path);
+    }
+    return [path, current];
+}
+
+function addDefaultStyles() {
+    var style = document.createElement('style');
+    style.innerText = `
+        .railroad-diagram {
+            background-color: hsl(30, 20%, 95%);
+        }
+        .railroad-diagram path {
+            stroke-width: 3;
+            stroke: black;
+            fill: rgba(0,0,0,0);
+        }
+        .railroad-diagram text {
+            font: bold 14px monospace;
+            text-anchor: middle;
+        }
+        /* ... other styles ... */
+    `;
+    return FakeSVG('style', {}, style.innerText);
+}
+
+var options = {
+    VS: 8,
+    AR: 10,
+    DIAGRAM_CLASS: 'railroad-diagram',
+    STROKE_ODD_PIXEL_LENGTH: true,
+    INTERNAL_ALIGNMENT: 'center',
+};
+
+function DiagramNode_format(x, y, width) {
+    // Every format function stores its own x/y — nothing else in this file
+    // did (a separate pre-existing gap from the two bugs already fixed
+    // above), so any caller reading `item.x`/`item.y` after calling
+    // `item.format(...)` (e.g. FORMATTERS.Diagram/.Choice below, which
+    // position siblings relative to a previous item's x) got `undefined`/
+    // NaN instead of a real coordinate.
+    this.x = x; this.y = y;
+    var startX = x; // this.width below must be the DISTANCE traveled, not
+                     // the absolute ending x — see the comment there.
+    // Hook up the two sides if this is a complex diagram.
+    for (var i = 0; i < this.items.length; i++) {
+        var item = this.items[i];
+        if (i > 0) {
+            // 20px gap between adjacent items — same stub width used
+            // everywhere else in this file (e.g. Choice's own x+10 option
+            // indent), doubled since there are two abutting stubs here.
+            x += 20;
+        }
+        item.format(x, y, width);
+        x += item.width;
+    }
+    // This used to be `this.width = x;` — the loop's ABSOLUTE ending
+    // x-coordinate, not the relative width traveled. Barely noticeable for
+    // a Sequence sitting near the diagram's own x=0 origin (a small, easy-
+    // to-miss constant offset), but for a Sequence nested inside Optional/
+    // Choice/ZeroOrMore — which format their children starting from
+    // whatever (large, cumulative) x they themselves were positioned at —
+    // this inflated the reported width by that entire starting offset,
+    // corrupting every sibling positioned after it in the enclosing
+    // Sequence (each subsequent item.x compounds the error further).
+    this.width = x - startX;
+    this.height = this.items.reduce((max, item) => Math.max(max, item.height), 0);
+    this.up = this.items[0].up;
+    this.down = this.items[0].down;
+    // A flat backbone line spanning the whole sequence at y connects every
+    // item (and the gaps between them) into one continuous line. This was
+    // missing entirely before — the only sibling of this code,
+    // FORMATTERS.Diagram, builds an equivalent Path but never adds it to
+    // the node either, so it silently draws nothing — which is why items
+    // floated with no connecting line, and why Choice/Optional's own
+    // connector arcs (which assume they're meeting a line arriving at
+    // their own x) looked like they started from nowhere.
+    new Path(startX, y).h(this.width).format().addTo(this);
+    return this;
+}
+
+FORMATTERS.Diagram = function (x, y, _width) {
+    this.x = x; this.y = y;
+    var path = new Path(x, y);
+    path.h(10);
+    var last = this.items.length - 1;
+    for (var i = 0; i < this.items.length; i++) {
+        var item = this.items[i];
+        if (item.needsSpace) {
+            path.h(10);
+        }
+        // width/height aren't known yet at this point — each item's own
+        // .format() below is what sets them — so this can't use `this.width`
+        // as a constraint the way Choice does; matches this file's existing
+        // single-pass layout approach elsewhere (e.g. Sequence/
+        // DiagramNode_format), not a new limitation introduced here.
+        item.format(path.x, path.y, 0);
+        path.x = item.x + item.width;
+        if (item.needsSpace) {
+            path.h(10);
+        }
+    }
+    path.h(10);
+    // Only computable once every item has actually been formatted (above) —
+    // this used to run BEFORE the loop, reading each item's .width while it
+    // was still unset (undefined), producing NaN.
+    this.width = this.items.reduce((w, i) => w + i.width + (i.needsSpace ? 20 : 0), 0) + 20;
+    this.height = this.items.reduce((h, i) => Math.max(h, i.height), 0);
+    new Path(this.items[0].x, y).right(this.width - 20).format().addTo(this);
+    return this;
+};
+
+FORMATTERS.Sequence = DiagramNode_format;
+
+FORMATTERS.Choice = function (x, y, width) {
+    this.x = x; this.y = y;
+    // Capture the real option count BEFORE the loop below starts appending
+    // connector-arc path primitives onto this.items — those legitimately
+    // belong in .items too (so walk() finds/renders them), but a `for`
+    // loop keyed off the SAME array's live .length, while that array is
+    // growing every iteration past i>0, never terminates (each iteration
+    // appends 2 more entries, so `i < this.items.length` stays true
+    // forever) — same bug already fixed in FORMATTERS.Diagram above.
+    var optionCount = this.items.length;
+    var first = this.items[0];
+    var last = this.items[optionCount - 1];
+
+    // Pass 1: format every option (sets each item's own width/height/x/y).
+    // 20px between option baselines, not 10 — a plain Terminal/NonTerminal
+    // box extends 10px above its own baseline (see FORMATTERS.Terminal's
+    // `up = 10`), so a 10px gap left its top edge exactly touching (0px
+    // clearance from) the line/branch above it instead of sitting on a
+    // clearly separate track below it.
+    var currentY = y;
+    for (var i = 0; i < optionCount; i++) {
+        var item = this.items[i];
+        item.format(x + 10, currentY, 0);
+        currentY += item.height + 20;
+    }
+    // Only computable once every option has actually been formatted.
+    this.width = this.items.slice(0, optionCount).reduce((w, i) => Math.max(w, i.width), 0) + 20;
+    this.height = this.items.slice(0, optionCount).reduce((h, i) => h + i.height, 0) + (optionCount - 1) * 20;
+    this.up = first.up;
+    this.down = last.down;
+
+    // Pass 2: draw each non-first option's connector arcs — needs
+    // this.width (just computed above) to route the "rejoin" arc back to
+    // the right edge, so this can't be folded into pass 1.
+    //
+    // Each connector is a straight run down from the shared entry point
+    // (x, y) followed by a single 'se' (south-then-east) quarter-turn that
+    // lands exactly at the option's own position (x+10, opt.y) — and the
+    // mirror image on the exit side. The previous version of this file
+    // started the vertical run from `y + first.up` and ALSO added the
+    // arc's own dy on top, double-counting first.up (an unrelated
+    // quantity — how far the FIRST option's own box extends upward, not
+    // an offset the branch geometry needs) and overshooting the target y
+    // by 10px every time — while also computing a rejoin point (this.width
+    // - opt.width - 10) that goes negative for the widest option. Both are
+    // why the arcs "failed to correctly connect to boxes." Re-derived from
+    // scratch: the arc's own dx/dy (10,10) already accounts for the full
+    // x-step from x to x+10, so the straight run only needs to cover
+    // whatever vertical distance is left over (opt.y - y - 10), and the
+    // rejoin run needs this.width - opt.width - 20 (verified non-negative
+    // for every option, including the widest one, since this.width
+    // reserves exactly 20px beyond the widest option's own width — 10 for
+    // this stub, 10 for the matching one on the entry side).
+    for (var j = 1; j < optionCount; j++) {
+        var opt = this.items[j];
+        new Path(x, y).v(opt.y - y - 10).arc('se').format().addTo(this);
+        new Path(opt.x + opt.width, opt.y).h(this.width - opt.width - 20).arc('en').v(-(opt.y - y - 10)).format().addTo(this);
+    }
+    return this;
+};
+
+
+FORMATTERS.OneOrMore = function (x, y, width) {
+    this.x = x; this.y = y;
+    this.item.format(x + 10, y, width - 20);
+    this.width = this.item.width + 20;
+    this.height = this.item.height;
+    this.up = this.item.up;
+    this.down = this.item.down;
+    new Path(x, y).h(10).format().addTo(this);
+    new Path(x + 10 + this.item.width, y).h(10).format().addTo(this);
+    new Path(x + 10, y + this.item.up).arc('se').up(this.item.up - 10).arc('wn').h(this.item.width).arc('ne').down(this.item.up - 10).arc('ws').format().addTo(this);
+    return this;
+};
+
+FORMATTERS.ZeroOrMore = function (x, y, width) {
+    // A rounded "repeat" loop below the item — same 4-corner race-track
+    // shape a real railroad diagram uses, built from Path.prototype.arc()
+    // now that its geometry is correct (see the comment above arc()'s own
+    // definition). An earlier version of this used sharp h/v-only corners
+    // instead, specifically because arc() was unverified/believed
+    // degenerate at the time — now that it's derived and checked, there's
+    // no more reason to avoid it here.
+    this.x = x; this.y = y;
+    this.item.format(x + 10, y, 0);
+    this.width = this.item.width + 20;
+    // Must clear 2*AR (20) for the loop's 2 vertical corners to fit;
+    // item.down is always >=10 so this comfortably clears that minimum
+    // while also giving the loop's bottom bar visible separation from the
+    // item's own box (rather than nearly touching its bottom border).
+    var loopDrop = this.item.down + 20;
+    this.height = this.item.height + loopDrop;
+    this.up = this.item.up;
+    this.down = this.item.down + loopDrop;
+    new Path(x, y).h(this.width).format().addTo(this);
+    var straightDrop = loopDrop - 20; // the part of loopDrop not already covered by the 2 corner arcs' own dy
+    new Path(x + 10 + this.item.width, y)
+        .arc('es')
+        .v(straightDrop)
+        .arc('sw')
+        .h(-(this.item.width + 10))
+        .arc('wn')
+        .v(-straightDrop)
+        .arc('ne')
+        .format().addTo(this);
+    return this;
+};
+
+FORMATTERS.Optional = function (x, y, width) {
+    // "Optional" is exactly "choice between nothing and the item" — reuse
+    // FORMATTERS.Choice's already-correct two-pass connector-arc geometry
+    // (verified visually) instead of the bespoke straight-line-plus-
+    // separate-loop math this used to have, which drew the "bypass" line
+    // at the SAME y as the item itself (no vertical room was ever reserved
+    // for it), so it visually overlapped/doubled the item's own content
+    // line instead of arcing around it.
+    this.items = [Skip(), this.item];
+    // walk() checks BOTH `.item` and `.items` (see its own definition
+    // above) — leaving `.item` in place after also setting `.items` to an
+    // array that happens to contain that exact same node reference made
+    // walk() visit (and render) it twice.
+    delete this.item;
+    return FORMATTERS.Choice.call(this, x, y, width);
+};
+
+
+FORMATTERS.Terminal = function (x, y, _width) {
+    this.x = x; this.y = y;
+    this.width = this.text.length * 8 + 20;
+    this.height = 21;
+    this.up = 10;
+    this.down = 11;
+    FakeSVG('rect', { x, y: y - 10, width: this.width, height: this.height, rx: 10, ry: 10 }).addTo(this);
+    FakeSVG('text', { x: x + this.width / 2, y: y + 4 }, this.text).addTo(this);
+    return this;
+};
+
+FORMATTERS.NonTerminal = function (x, y, _width) {
+    this.x = x; this.y = y;
+    this.width = this.text.length * 8 + 20;
+    this.height = 21;
+    this.up = 10;
+    this.down = 11;
+    FakeSVG('rect', { x, y: y - 10, width: this.width, height: this.height }).addTo(this);
+    FakeSVG('text', { x: x + this.width / 2, y: y + 4 }, this.text).addTo(this);
+    return this;
+};
+
+FORMATTERS.Comment = function (x, y, _width) {
+    this.x = x; this.y = y;
+    this.width = this.text.length * 7 + 20;
+    this.height = 21;
+    this.up = 11;
+    this.down = 10;
+    FakeSVG('text', { x: x + this.width / 2, y: y + 5, class: 'comment' }, this.text).addTo(this);
+    return this;
+};
+
+FORMATTERS.Skip = function (x, y, _width) {
+    this.x = x; this.y = y;
+    this.width = 0;
+    this.height = 0;
+    this.up = 0;
+    this.down = 0;
+    return this;
+};
+
+DiagramNode.prototype.format = function (x, y, width) {
+    const formatter = FORMATTERS[this.type];
+    if (!formatter) throw new Error(`railroadDiagram: no format() implementation for node type "${this.type}"`);
+    return formatter.call(this, x, y, width);
+};
+
+DiagramNode.prototype.toSVG = function () {
+    var diagram = new FakeSVG('svg', { class: 'railroad-diagram' });
+    this.format(0, 0).addTo(diagram);
+    return diagram;
+};
+
+DiagramNode.prototype.drawOn = function (ctx) {
+    this.format(20, 20); // Add some padding
+
+    ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+    ctx.canvas.width = this.width + 40;
+    ctx.canvas.height = this.height + 40;
+    ctx.translate(20, 20);
+
+    this.walk(item => {
+        if (item.type === 'rect' || item.tagName === 'rect') {
+            ctx.fillStyle = 'hsl(30, 20%, 95%)';
+            ctx.strokeStyle = 'black';
+            ctx.lineWidth = 2;
+            if (item.attrs.rx) { // Rounded rect for Terminals
+                ctx.beginPath();
+                ctx.moveTo(item.attrs.x + item.attrs.rx, item.attrs.y);
+                ctx.arcTo(item.attrs.x + item.attrs.width, item.attrs.y, item.attrs.x + item.attrs.width, item.attrs.y + item.attrs.height, item.attrs.rx);
+                ctx.arcTo(item.attrs.x + item.attrs.width, item.attrs.y + item.attrs.height, item.attrs.x, item.attrs.y + item.attrs.height, item.attrs.rx);
+                ctx.arcTo(item.attrs.x, item.attrs.y + item.attrs.height, item.attrs.x, item.attrs.y, item.attrs.rx);
+                ctx.arcTo(item.attrs.x, item.attrs.y, item.attrs.x + item.attrs.width, item.attrs.y, item.attrs.rx);
+                ctx.closePath();
+                ctx.fill();
+                ctx.stroke();
+            } else { // Sharp rect for NonTerminals
+                ctx.fillRect(item.attrs.x, item.attrs.y, item.attrs.width, item.attrs.height);
+                ctx.strokeRect(item.attrs.x, item.attrs.y, item.attrs.width, item.attrs.height);
+            }
+        } else if (item.type === 'text' || item.tagName === 'text') {
+            ctx.fillStyle = 'black';
+            ctx.font = 'bold 14px monospace';
+            ctx.textAlign = 'center';
+            ctx.textBaseline = 'middle';
+            ctx.fillText(item.text, item.attrs.x, item.attrs.y);
+        } else if (item.type === 'path' || item.tagName === 'path') {
+            ctx.strokeStyle = 'black';
+            ctx.lineWidth = 3;
+            ctx.lineCap = 'round';
+            const p = new Path2D(item.attrs.d);
+            ctx.stroke(p);
+        }
+    });
+    ctx.translate(-20, -20);
+};

package/src/treeModeCatalog.js

@@ -0,0 +1,16 @@
+import { TreeModeRegistry } from './charting/modelTree/TreeModeRegistry.js';
+import { LayerGroupedTreeMode } from './charting/modelTree/modes/LayerGroupedTreeMode.js';
+import { TypeGroupedTreeMode } from './charting/modelTree/modes/TypeGroupedTreeMode.js';
+import { FlatTreeMode } from './charting/modelTree/modes/FlatTreeMode.js';
+
+export const TREE_MODE_CATALOG = [
+    { key: 'byLayer', TreeModeClass: LayerGroupedTreeMode },
+    { key: 'byType', TreeModeClass: TypeGroupedTreeMode },
+    { key: 'flat', TreeModeClass: FlatTreeMode },
+];
+
+export const treeModeRegistry = new TreeModeRegistry(TREE_MODE_CATALOG);
+
+export function getTreeModeCatalogEntry(key) {
+    return treeModeRegistry.get(key);
+}

package/src/workspace/ContextBus.js

@@ -0,0 +1,79 @@
+/**
+ * ContextBus — the channel layer that lets independently authored parts drive
+ * each other without holding references to each other (the mashup property).
+ *
+ * The load-bearing detail is **retained-value replay**: `publish()` remembers
+ * the last value per channel, and `subscribe()` fires immediately with it. Parts
+ * mount lazily — an inactive tab's part does not exist yet — so without replay,
+ * activating a tab would give you a chart that stays blank until the user
+ * re-clicks whatever drove it. With replay, a part mounting at any point in the
+ * session immediately sees current context.
+ *
+ * Channel names are a convention, not enforced: `selection:<entity>`,
+ * `filter:<name>`, `data:<queryId>`.
+ */
+export class ContextBus {
+    constructor() {
+        /** @type {Map<string, Set<Function>>} */
+        this._subs = new Map();
+        /** @type {Map<string, any>} */
+        this._retained = new Map();
+    }
+
+    /** Publish a value and retain it for later subscribers. */
+    publish(channel, value) {
+        this._retained.set(channel, value);
+        const subs = this._subs.get(channel);
+        if (!subs) return;
+        // Copy before iterating: a handler may unsubscribe itself.
+        for (const fn of [...subs]) this._invoke(fn, value, channel);
+    }
+
+    /**
+     * Subscribe to a channel. Fires immediately if the channel already has a
+     * retained value. Returns an unsubscribe function — `Part` pushes this
+     * straight onto its disposer list.
+     */
+    subscribe(channel, fn) {
+        if (!this._subs.has(channel)) this._subs.set(channel, new Set());
+        this._subs.get(channel).add(fn);
+        if (this._retained.has(channel)) this._invoke(fn, this._retained.get(channel), channel);
+        return () => this.unsubscribe(channel, fn);
+    }
+
+    unsubscribe(channel, fn) {
+        const subs = this._subs.get(channel);
+        if (!subs) return;
+        subs.delete(fn);
+        if (subs.size === 0) this._subs.delete(channel);
+    }
+
+    /** Current retained value without subscribing. */
+    peek(channel) {
+        return this._retained.get(channel);
+    }
+
+    /** Drop a channel's retained value (subscribers stay attached). */
+    clear(channel) {
+        this._retained.delete(channel);
+    }
+
+    /** Every channel with a subscriber or a retained value — for a wiring UI. */
+    channels() {
+        return [...new Set([...this._subs.keys(), ...this._retained.keys()])].sort();
+    }
+
+    dispose() {
+        this._subs.clear();
+        this._retained.clear();
+    }
+
+    /** One bad subscriber must not stop the others from being notified. */
+    _invoke(fn, value, channel) {
+        try {
+            fn(value, channel);
+        } catch (err) {
+            console.error(`ContextBus: subscriber for "${channel}" threw`, err);
+        }
+    }
+}