dsh-model-everything 0.5.1 → 0.6.0

package/lib/render/svg.js

@@ -104,6 +104,9 @@ const writers = {
             edgeMarks(first, after, before, last, shape.arrow, stroke, colours.background) +
             edgeLabel(shape.label, shape.labelX, shape.labelY, colours));
     },
+    // A junction dot: the visible answer to "is this a join or a crossing?". Filled in the line's own colour, so it
+    // reads as the line thickening where a branch meets it rather than as a new mark on the page.
+    junction: (shape, colours) => '<circle cx="' + n(shape.x) + '" cy="' + n(shape.y) + '" r="2.5" fill="' + colours[shape.colour] + '" />',
     title: (shape, colours) => {
         return '<text x="' + n(shape.x) + '" y="' + n(shape.y) + '" font-size="12" fill="' + colours[shape.colour] + '">' + escape(shape.text) + '</text>';
     },
@@ -112,7 +115,9 @@ const writers = {
         const lines = shape.lines
             .map((line, index) => '<tspan x="' + n(shape.x) + '" dy="' + (index === 0 ? 0 : 15) + '">' + escape(line) + '</tspan>')
             .join('');
-        return '<text x="' + n(shape.x) + '" y="' + n(shape.y + 11) + '" font-size="10" text-anchor="middle" fill="' + colour + '">' + lines + '</text>';
+        // Start-anchored: the caption begins at the margin the title uses, so a long one grows right into the space
+        // the canvas has already reserved for it instead of hanging off the left edge.
+        return '<text x="' + n(shape.x) + '" y="' + n(shape.y + 11) + '" font-size="10" fill="' + colour + '">' + lines + '</text>';
     },
 };
 /** The dash pattern a route's source stated, or nothing for a solid line. */
@@ -215,7 +220,11 @@ export function toSvg(canvas, colours, label) {
             dropped += 1;
             continue;
         }
-        body.push(writer(shape, colours));
+        const drawn = writer(shape, colours);
+        // A node carries its id in the markup, so a card or a board can target one node by delegation, the way a
+        // boundary already carries `data-group-id`, instead of working it out from the click's geometry.
+        const nodeId = shape.id;
+        body.push(shape.kind === 'box' && typeof nodeId === 'string' ? '<g data-node-id="' + escape(nodeId) + '">' + drawn + '</g>' : drawn);
     }
     const header = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ' + n(canvas.width) + ' ' + n(canvas.height) +
         '" width="' + n(canvas.width) + '" height="' + n(canvas.height) + '" role="img"' +

package/lib/render/trunk.js

@@ -0,0 +1,213 @@
+/**
+ * Fan-in trunks: a batch of arrows into one box from one side, drawn as one bundle.
+ *
+ * A node that four relations point at is drawn as four ports along its side and four lines converging on it. Each
+ * line is right on its own, and the picture is wrong: the bundle reads as a comb, and a reader counts ports to count
+ * arrows. The mature layered implementations solve this by merging the edges - ELK's *Merge Edges* with junction
+ * points, Graphviz's `concentrate` - and the shape they produce is one straight run outside the node, with a branch
+ * joining it wherever a separate edge arrives, and one shared stub into the node.
+ *
+ * This module decides only which ends may merge, where the shared run sits and which of the branches becomes the
+ * shared entry. It is pure geometry over boxes and ports, so the rules can be asserted without a canvas; the painter
+ * draws the answer.
+ *
+ * The rules, and why each one exists:
+ *
+ * - **One target, one entry side.** Edges that arrive from different sides are travelling in different directions,
+ *   and a trunk that changed axis would be two trunks.
+ * - **The exit faces the trunk.** A branch arrives at the trunk along the direction its own port leaves by, so the
+ *   trunk is outside the source as well as outside the target. An end that does not face the trunk is not merged: it
+ *   would have to turn before it got there, which is the bend the merge was supposed to save.
+ * - **Distinct sources, three or more.** Two merged edges read as one thick line. A pair of relations about one pair
+ *   has its own, older rule - they stay visibly apart - and that rule is the distinct-source rule here: two
+ *   statements about one pair share their source, so they can never both be a branch of one trunk.
+ * - **One arrow semantics.** A composition and an association are different statements about the relation; drawn on
+ *   one trunk they would be read as one statement. Ends that disagree on their arrow are not merged with each other.
+ * - **Clear of every box.** A trunk that crosses a box is the same defect as a route that does, and it is worse here
+ *   because it is drawn once for the whole bundle.
+ * - **One trunk per line.** Two groups whose trunks would be drawn on one line would read as one bundle between two
+ *   unrelated targets, so the later group is refused.
+ *
+ * The shared entry is the middle of the target's side. A bundle enters the target through one port, and a side that
+ * carries one port is centred on it, so the trunk runs to the middle and every branch joins it there: the branches
+ * that are not in the middle bend, which is the price of one entry that reads as centred rather than one that leans
+ * towards whichever branch happened to arrive straightest.
+ *
+ * Merging forces every branch but one to bend twice, so an unmerged drawing of `k` straight branches costs
+ * `2 * (n - k)` bends and a merged one costs `2 * (n - 1)`; the branch nearest the middle is the lead because it is
+ * the only one that can still reach the shared port without a horizontal leg, and on a target whose middle happens
+ * to fall on a branch's own line that branch is free, as before.
+ *
+ * What this module does not decide: the colour of a branch, the text of its label, and how a branch's own route
+ * reaches the trunk. Those belong to the painter.
+ */
+import { crossesBox, normalOf, ROUTE_STUB } from './route.js';
+/** The least a trunk is worth drawing for: two merged edges read as one thick line. */
+const TRUNK_MIN_EDGES = 3;
+/** Does this side move along the page's vertical axis? A run on it is horizontal. */
+function isVerticalSide(side) {
+    return side === 'top' || side === 'bottom';
+}
+/**
+ * Where the trunk outside a box sits.
+ *
+ * The same stub the router leaves before it turns, so the bundle starts exactly where a single route would have
+ * turned: about `ROUTE_STUB` outside the target, square to the side it enters.
+ */
+function trunkAt(box, side) {
+    if (side === 'top')
+        return box.y - ROUTE_STUB;
+    if (side === 'bottom')
+        return box.y + box.height + ROUTE_STUB;
+    if (side === 'left')
+        return box.x - ROUTE_STUB;
+    return box.x + box.width + ROUTE_STUB;
+}
+/** The coordinate a point takes along the side it sits on: where along that side the port is. */
+function alongSide(point, side) {
+    return isVerticalSide(side) ? point.x : point.y;
+}
+/** The coordinate a point takes on its side's outward normal: the axis a trunk outside that side moves on. */
+function alongNormal(point, side) {
+    return isVerticalSide(side) ? point.y : point.x;
+}
+/** Does the port on `side` travel toward the trunk at `at`? A branch only merges into a trunk it moves toward. */
+function facesTrunk(point, side, at) {
+    const normal = normalOf(side);
+    const outward = isVerticalSide(side) ? normal.y : normal.x;
+    return (at - alongNormal(point, side)) * outward > 0.5;
+}
+/** The group an edge end belongs to: its target, the side it enters by, and the arrow it means. */
+function keyOf(end) {
+    return end.to + '\u0000' + end.entry + '\u0000' + (end.arrow ?? '');
+}
+/** Is this axis-aligned segment clear of every box it does not attach to? */
+function clearSegment(boxes, skip, x1, y1, x2, y2) {
+    for (const box of boxes) {
+        if (skip.includes(box))
+            continue;
+        if (crossesBox(x1, y1, x2, y2, box))
+            return false;
+    }
+    return true;
+}
+/** Would this run lie on the line of an accepted trunk and share a stretch of it? */
+function onOneLine(group, side, at, low, high) {
+    if (isVerticalSide(group.side) !== isVerticalSide(side))
+        return false;
+    if (group.at !== at)
+        return false;
+    return Math.min(group.to, high) - Math.max(group.from, low) > 0.5;
+}
+/**
+ * Decide which ends merge, and where each accepted trunk runs.
+ *
+ * Ends that cannot merge are simply absent from the plan; the painter draws them as it always has. Groups are
+ * ordered by the first member the source wrote, so the answer does not depend on map iteration order.
+ */
+export function planTrunks(input) {
+    const groups = [];
+    const groupOf = new Map();
+    // Per edge first: the cheap rules. An end that fails one of them cannot join any group, so it never reaches the
+    // count that decides whether a group is worth drawing.
+    const buckets = new Map();
+    for (const end of input.ends) {
+        if (end.runY === undefined)
+            continue;
+        // The branch approaches the trunk along its own exit normal, so the two ends must move on one axis: a mixed pair
+        // would have to turn before it reached the trunk, which is the bend the merge exists to save.
+        if (isVerticalSide(end.exit) !== isVerticalSide(end.entry))
+            continue;
+        const source = input.boxOf(end.from);
+        const target = input.boxOf(end.to);
+        if (source === undefined || target === undefined)
+            continue;
+        if (source === target)
+            continue;
+        const exit = input.exitPortOf(end.index);
+        if (exit === undefined)
+            continue;
+        const at = trunkAt(target, end.entry);
+        if (!facesTrunk(exit, end.exit, at))
+            continue;
+        const candidate = { end, source, target, at, exit, branch: alongSide(exit, end.exit) };
+        const key = keyOf(end);
+        const list = buckets.get(key);
+        if (list === undefined)
+            buckets.set(key, [candidate]);
+        else
+            list.push(candidate);
+    }
+    for (const list of buckets.values()) {
+        // A pair of relations about one node is not two branches: the pair's own rule keeps them visibly apart, and both
+        // of them name the same source, so dropping the duplicated source drops the whole pair. Neither joins, and the
+        // group keeps the singles.
+        const bySource = new Map();
+        for (const candidate of list) {
+            const seen = bySource.get(candidate.end.from);
+            if (seen === undefined)
+                bySource.set(candidate.end.from, [candidate]);
+            else
+                seen.push(candidate);
+        }
+        const members = list.filter((candidate) => bySource.get(candidate.end.from).length === 1);
+        if (members.length < TRUNK_MIN_EDGES)
+            continue;
+        const target = members[0].target;
+        const side = members[0].end.entry;
+        const at = members[0].at;
+        // The shared entry is the middle of the target's side. A side that carries one port is centred on it, and a bundle
+        // enters through one port, so the run reaches the middle rather than whichever branch asked for the middle first.
+        const entryAlong = isVerticalSide(side) ? target.x + target.width / 2 : target.y + target.height / 2;
+        // The lead is the branch nearest that middle: the only member that can reach the shared port without a lateral
+        // leg. The source's order breaks a tie, so the answer does not depend on map iteration.
+        let lead = members[0];
+        for (const candidate of members) {
+            if (Math.abs(candidate.branch - entryAlong) < Math.abs(lead.branch - entryAlong) - 1e-9)
+                lead = candidate;
+        }
+        // The run: the whole stretch the branches and the one port span, so every branch joins a line that reaches it.
+        let low = entryAlong;
+        let high = entryAlong;
+        for (const candidate of members) {
+            low = Math.min(low, candidate.branch);
+            high = Math.max(high, candidate.branch);
+        }
+        // Clearance. The run is checked against every box but the target; each branch's own drop is checked against every
+        // box but its source and the target. The drop leaves a port square to its side, so those are the only two boxes it
+        // can legitimately touch.
+        const vertical = isVerticalSide(side);
+        const run = vertical ? [low, at, high, at] : [at, low, at, high];
+        if (!clearSegment(input.boxes, [target], run[0], run[1], run[2], run[3]))
+            continue;
+        let blocked = false;
+        for (const candidate of members) {
+            // The drop: from the branch's own port to the point where it meets the trunk, along its exit normal.
+            const drop = vertical
+                ? [candidate.branch, candidate.exit.y, candidate.branch, at]
+                : [candidate.exit.x, candidate.branch, at, candidate.branch];
+            if (!clearSegment(input.boxes, [candidate.source, target], drop[0], drop[1], drop[2], drop[3]))
+                blocked = true;
+        }
+        if (blocked)
+            continue;
+        // Two trunks on one line would be drawn as one bundle. The first group keeps the line; the later one travels alone.
+        if (groups.some((group) => onOneLine(group, side, at, low, high)))
+            continue;
+        const id = groups.length;
+        groups.push({
+            id,
+            target: members[0].end.to,
+            side,
+            at,
+            entryAlong,
+            from: low,
+            to: high,
+            lead: lead.end.index,
+            members: members.map((candidate) => candidate.end.index),
+        });
+        for (const candidate of members)
+            groupOf.set(candidate.end.index, id);
+    }
+    return { groups, groupOf };
+}

package/lib/routing.js

@@ -70,6 +70,18 @@ export const ROUTES = {
         owns: 'a dependency graph as a graph - cycles, layers, dangling edges - from a drawing or a source tree',
         notFor: { when: 'the question is a rule the design declared for itself, not an edge that exists', tool: 'model_design_review' },
     },
+    diagram_render: {
+        owns: 'one drawing: source text in, a laid-out SVG out, every refused line named',
+        notFor: { when: 'the drawing has to fit a budget or a pane before a reader sees it', tool: 'diagram_review' },
+    },
+    diagram_review: {
+        owns: 'the structure of one drawing against budgets: boundary width, nesting depth, node count',
+        notFor: { when: 'the diagram has to be read as a model, and its modelling judged', tool: 'uml_review' },
+    },
+    diagram_diff: {
+        owns: 'what moved between two drawings: boundaries added, removed, renamed or re-parented',
+        notFor: { when: 'two reports have to be compared rather than two drawings', tool: 'report_diff' },
+    },
 };
 /** The route for a tool, or undefined when the tool has none. */
 export function routeFor(tool) {

package/lib/transcript.js

@@ -0,0 +1,327 @@
+/**
+ * What an annotation message looks like after it has been sent.
+ *
+ * The message is one block of plain lines: a fixed opening, numbered items, a question line, then the reader's
+ * own words. That is the right thing for the model and the wrong thing to read as a human - the reader wrote one
+ * note about one node, and what landed is a page of protocol.
+ *
+ * The host renders a user message as text inside elements it owns and re-renders. So this never assigns an
+ * element's text: that deletes its children, React reconciles from a tree that no longer matches, and whole
+ * turns come back mangled. It edits the text NODES instead - trim the run before the cut, remove the runs that
+ * held the block - and puts the chip in as a sibling, exactly the way the shipped annotation plugin does it.
+ *
+ * Everything here is defensive: a page without the elements, an element without text nodes, an element already
+ * handled. A decorator that throws would take a render pass with it.
+ */
+/** The first words of every annotation block, used to recognise one in the transcript. */
+export const TRANSCRIPT_MARKER = 'Diagram annotations -';
+/** Where the block hands over to the reader's own question. */
+const QUESTION = 'Question:';
+/** Marks an element the decorator has handled, and remembers the block it came from. */
+const HANDLED = 'data-dme-annotated';
+const ORIGINAL = 'data-dme-annotation-text';
+/** Elements whose text can be the message. Nested containers are excluded by the descendant test below. */
+const SELECTOR = 'div, p, span, li';
+/**
+ * Another plugin's territory, which this one must never touch.
+ *
+ * The shipped annotation plugin marks its own nodes `data-annotation-*` and folds its own blocks by their own
+ * markers. Two plugins doing DOM work in the same transcript collide in exactly three ways: they fight over the
+ * same message element, they overwrite each other's chip, and they both react to the other's mutations. The
+ * rules this file follows, and that a future change here has to keep:
+ *
+ * 1. only our own marker starts work - `Diagram annotations -`, never a generic word like "annotation";
+ * 2. every attribute we add is `data-dme-*`, and anything already carrying `data-annotation-*` is skipped;
+ * 3. our inserted nodes carry `data-dme-own`, so a neighbouring plugin can skip them as easily as we skip its;
+ * 4. one pass over a message, marked, so a second plugin's re-render cannot make us fold the same block twice.
+ *
+ * The draft is the fourth surface: both plugins write it through the host's `setDraft`, and a blind overwrite
+ * would drop the other's block. `placeBlock` re-reads the draft immediately before writing and prepends,
+ * keeping the rest verbatim - never a replace.
+ */
+const FOREIGN = '[data-annotation-for-dsh], [data-annotation-overlay], [data-annotation-chip], [data-annotation-tip-layer]';
+const BORDER = '1px solid var(--dsw-alias-border-l1, rgba(127,127,127,0.35))';
+/** The count in the opening line, for the chip; null when the line says something unexpected. */
+export function annotationCountOf(text) {
+    const found = /Diagram annotations - (\d+)/.exec(text);
+    return found === null ? null : Number(found[1]);
+}
+/** The reader's own words: what follows the question line, or nothing when the note was the whole message. */
+export function questionOf(text) {
+    const at = text.lastIndexOf(QUESTION);
+    return at === -1 ? '' : text.slice(at + QUESTION.length).trim();
+}
+/** The notes the block carries, read back out of its lines, so a reader sees what the model saw. */
+export function itemsOf(text) {
+    const items = [];
+    for (const raw of text.split(String.fromCharCode(10))) {
+        const line = raw.trim();
+        const head = /^Diagram note \[(\d+)\] node (.+)$/.exec(line);
+        if (head !== null) {
+            const rest = head[2];
+            const dash = rest.lastIndexOf(' - ');
+            items.push({ index: Number(head[1]), node: dash === -1 ? rest : rest.slice(0, dash), note: dash === -1 ? '' : rest.slice(dash + 3) });
+            continue;
+        }
+        const note = /^Note: (.*)$/.exec(line);
+        if (note !== null && items.length > 0)
+            items[items.length - 1].note = note[1];
+    }
+    return items;
+}
+/** Every text node inside an element, in document order. */
+function textNodesOf(root) {
+    const out = [];
+    const visit = (node) => {
+        const children = node.childNodes;
+        if (children === undefined || children === null || children.length === 0) {
+            if (typeof node.nodeValue === 'string')
+                out.push(node);
+            return;
+        }
+        for (let index = 0; index < children.length; index += 1)
+            visit(children[index]);
+    };
+    visit(root);
+    return out;
+}
+/**
+ * Drop everything before the cut from the text nodes, and leave the reader's own words.
+ *
+ * The nodes are the only thing written: an element's `textContent` would take its child elements with it.
+ */
+export function cutTextNodes(nodes, cut) {
+    let position = 0;
+    let done = false;
+    for (const node of nodes) {
+        const value = typeof node.nodeValue === 'string' ? node.nodeValue : '';
+        const length = value.length;
+        if (done) {
+            position += length;
+            continue;
+        }
+        if (cut <= position + length) {
+            node.nodeValue = value.slice(cut - position).replace(/^\s+/, '');
+            done = true;
+        }
+        else {
+            node.nodeValue = '';
+        }
+        position += length;
+    }
+    return done;
+}
+/** Whether another plugin owns this node, or any of its ancestors. */
+/**
+ * Whether this element IS another plugin's node.
+ *
+ * Only the element itself counts. An ancestor test looked safer and was wrong: that plugin marks the message
+ * container it has folded, so every message it touched also carried an ancestor marker - and this plugin then
+ * skipped the very message it was looking for.
+ */
+function isForeign(node) {
+    for (const name of ['data-annotation-for-dsh', 'data-annotation-overlay', 'data-annotation-chip', 'data-annotation-tip-layer']) {
+        const value = node.getAttribute?.(name);
+        if (value !== undefined && value !== null)
+            return true;
+    }
+    return false;
+}
+/** Kept for the tests that assert the selector exists; the ancestor walk is deliberately not used. */
+export const FOREIGN_SELECTOR = FOREIGN;
+function holdsAnotherBlock(node) {
+    const inner = node.querySelectorAll?.(SELECTOR);
+    if (inner === undefined || inner === null)
+        return false;
+    for (let index = 0; index < inner.length; index += 1) {
+        const text = inner[index].textContent;
+        if (typeof text === 'string' && text.indexOf(TRANSCRIPT_MARKER) !== -1)
+            return true;
+    }
+    return false;
+}
+/** The card listing the notes, styled from the host's tokens so it reads as part of the page. */
+function cardFor(doc, items, title, full) {
+    const card = doc.createElement?.('div');
+    if (card === undefined)
+        return undefined;
+    styleOf(card, {
+        position: 'fixed', zIndex: '40', display: 'none', maxWidth: '360px', padding: '8px 10px', borderRadius: '10px',
+        background: 'var(--dsw-alias-bg-overlay, var(--dsw-alias-bg-layer-1, Canvas))',
+        border: BORDER, boxShadow: '0 10px 30px rgba(0,0,0,0.28)',
+        color: 'var(--dsw-alias-label-primary, CanvasText)', font: '12px system-ui, sans-serif',
+    });
+    const head = doc.createElement?.('div');
+    if (head !== undefined) {
+        head.textContent = title;
+        styleOf(head, {
+            color: 'var(--dsw-alias-label-secondary, GrayText)', paddingBottom: '6px', marginBottom: '4px',
+            borderBottom: BORDER, fontSize: '11px',
+        });
+        card.appendChild?.(head);
+    }
+    for (const item of items) {
+        const row = doc.createElement?.('div');
+        if (row === undefined)
+            continue;
+        styleOf(row, { display: 'flex', gap: '6px', alignItems: 'flex-start', padding: '3px 0' });
+        const badge = doc.createElement?.('span');
+        if (badge !== undefined) {
+            badge.textContent = String(item.index);
+            styleOf(badge, {
+                flex: '0 0 auto', width: '16px', height: '16px', lineHeight: '16px', textAlign: 'center',
+                borderRadius: '8px', fontSize: '10px',
+                background: 'var(--dsw-alias-brand-primary, #2563eb)', color: '#fff',
+            });
+            row.appendChild?.(badge);
+        }
+        const body = doc.createElement?.('div');
+        if (body !== undefined) {
+            body.textContent = item.node + (item.note === '' ? '' : String.fromCharCode(10) + item.note);
+            styleOf(body, { flex: '1 1 auto', whiteSpace: 'pre-wrap', wordBreak: 'break-word' });
+            row.appendChild?.(body);
+        }
+        card.appendChild?.(row);
+    }
+    const more = doc.createElement?.('div');
+    if (more !== undefined) {
+        more.textContent = full;
+        styleOf(more, {
+            display: 'none', marginTop: '6px', paddingTop: '6px', borderTop: BORDER, fontSize: '11px',
+            whiteSpace: 'pre-wrap', color: 'var(--dsw-alias-label-secondary, GrayText)', maxHeight: '40vh', overflow: 'auto',
+        });
+        card.appendChild?.(more);
+    }
+    return card;
+}
+/**
+ * Apply a style map to a real element.
+ *
+ * Assigning an object to element.style applies nothing on a real element - the browser keeps its own
+ * CSSStyleDeclaration - which is why a chip built that way rendered as plain words. Each property goes through
+ * setProperty; a fake node without one keeps the map so a test can read it back.
+ */
+function styleOf(node, map) {
+    const decl = node.style;
+    if (typeof decl?.setProperty === 'function') {
+        const target = decl;
+        for (const key of Object.keys(map)) {
+            const value = map[key];
+            if (value === undefined)
+                continue;
+            target.setProperty(key.replace(/[A-Z]/g, (letter) => '-' + letter.toLowerCase()), value);
+        }
+        return;
+    }
+    node.style = map;
+}
+function chipFor(doc, label, title, text) {
+    const chip = doc.createElement?.('div');
+    if (chip === undefined)
+        return undefined;
+    chip.textContent = label;
+    chip.setAttribute?.('role', 'button');
+    // A pill that sits in the reader's line, not a block that pushes it: the conversation is theirs, and the chip
+    // is a footnote to it.
+    styleOf(chip, {
+        display: 'inline-flex', alignItems: 'center', height: '20px', padding: '0 8px', margin: '4px 0 0',
+        fontSize: '11px', lineHeight: '20px', borderRadius: '10px', verticalAlign: 'middle', userSelect: 'none',
+        border: BORDER, background: 'var(--dsw-alias-bg-layer-2, rgba(127,127,127,0.10))',
+        color: 'var(--dsw-alias-label-secondary, GrayText)', cursor: 'pointer', maxWidth: '100%',
+    });
+    const card = cardFor(doc, itemsOf(text), title, text);
+    if (card === undefined)
+        return chip;
+    const place = () => {
+        const box = chip.getBoundingClientRect?.();
+        styleOf(card, box === undefined
+            ? { display: 'block' }
+            : { display: 'block', left: String(Math.max(8, box.left)) + 'px', top: String(box.top + box.height + 6) + 'px' });
+    };
+    const hide = () => { styleOf(card, { display: 'none' }); };
+    chip.addEventListener?.('mouseenter', place);
+    chip.addEventListener?.('mouseleave', hide);
+    chip.addEventListener?.('click', () => {
+        if ((card.style ?? {}).display === 'block') {
+            hide();
+        }
+        else {
+            place();
+        }
+    });
+    // The card travels with the chip, so a bubble that re-renders cannot leave one behind.
+    chip.appendChild?.(card);
+    return chip;
+}
+/**
+ * Fold every annotation message in the transcript behind its count, and answer how many were folded.
+ *
+ * Idempotent: an element that already carries the marker is skipped, so the observer can call this on every
+ * change without stacking chips. Only the element whose text is the message is touched, and only its text nodes.
+ */
+export function decorateTranscript(doc, label = 'Notes', title = 'Notes in this message') {
+    if (doc === undefined || typeof doc.querySelectorAll !== 'function')
+        return 0;
+    let nodes;
+    try {
+        nodes = doc.querySelectorAll(SELECTOR);
+    }
+    catch {
+        return 0;
+    }
+    let folded = 0;
+    for (let index = 0; index < nodes.length; index += 1) {
+        const element = nodes[index];
+        const text = typeof element.textContent === 'string' ? element.textContent : '';
+        if (!text.includes(TRANSCRIPT_MARKER))
+            continue;
+        if (element.getAttribute?.(HANDLED) === '1')
+            continue;
+        // Another plugin's node: it may be folding its own block in the same message, and two folders would take
+        // turns rewriting each other's text.
+        if (isForeign(element))
+            continue;
+        if (holdsAnotherBlock(element))
+            continue;
+        const texts = textNodesOf(element);
+        if (texts.length === 0)
+            continue;
+        const joined = texts.map((node) => (typeof node.nodeValue === 'string' ? node.nodeValue : '')).join('');
+        if (!joined.includes(TRANSCRIPT_MARKER))
+            continue;
+        const at = joined.lastIndexOf(QUESTION);
+        const cut = at === -1 ? joined.length : at + QUESTION.length;
+        const count = annotationCountOf(joined);
+        const chip = chipFor(doc, label + (count === null ? '' : ' ×' + String(count)), title, joined);
+        if (chip === undefined)
+            continue;
+        try {
+            if (!cutTextNodes(texts, cut))
+                continue;
+            element.setAttribute?.(ORIGINAL, joined);
+            element.setAttribute?.(HANDLED, '1');
+            const parent = element.parentNode;
+            if (parent?.insertBefore !== undefined)
+                parent.insertBefore(chip, element.nextSibling ?? null);
+            else
+                element.appendChild?.(chip);
+            folded += 1;
+        }
+        catch {
+            // A page that refuses the write keeps the plain message, which reads on its own.
+        }
+    }
+    return folded;
+}
+/**
+ * One pass, and nothing that keeps running.
+ *
+ * There is deliberately no observer and no timer here. Both were tried: an observer over the document plus a
+ * one-second interval turns every DOM change into a full selector scan, and a streaming conversation changes the
+ * DOM many times a second - the container stopped responding. A caller that wants the fold has to decide when
+ * to run it, on a container it chose.
+ */
+export function startTranscriptDecoration(doc, label = 'Notes', title = 'Notes in this message') {
+    decorateTranscript(doc, label, title);
+    return () => { };
+}