dsh-model-everything 0.5.2 → 0.6.1

package/src/diagram-render-tool.ts

@@ -15,7 +15,7 @@ export const DIAGRAM_TOOL_NAME = 'diagram_render'
 export const diagramRenderTool = defineTool({
   name: DIAGRAM_TOOL_NAME,
   description:
-    'Draw a diagram from its source text and get back SVG. Accepts Mermaid (flowchart, stateDiagram) and PlantUML (component, package, state) for the subset this renderer draws, lays out boxes and arrows itself, and reports every line it refused with its line number instead of drawing half a diagram. Pass `out` to write the SVG next to a document. This tool draws; it does not parse a diagram back into a model, and it does not review one - uml_parse and uml_review do that.',
+    'Draw a diagram from its source text and get back SVG. Structure is read from a picture, so reach for this whenever the answer is a layout, a flow, a set of boundaries or a change between two of them - not only when the request says draw. Pass `out` to write the SVG and show it to the reader beside the explanation it carries, and read the model-everything-diagram skill for what this notation subset covers and what it refuses. It accepts Mermaid (flowchart, stateDiagram) and PlantUML (component, package, state), lays out boxes and arrows itself, and reports every line it refused with its line number instead of drawing half a diagram. This tool draws; it does not parse a diagram back into a model, and it does not review one - uml_parse and uml_review do that.',
   parameters: {
     source: {
       type: 'string',
@@ -62,6 +62,18 @@ export const diagramRenderTool = defineTool({
       }
       return [{ type: 'text' as const, text: lines.join('\n') }]
     },
+    // The card a UI shows. The host keeps this on the settled call as `block.meta`, which is the one place a
+    // view can find the drawing's own source: by then the arguments are gone. Measured against how
+    // dsh-deepread's card reads its payload - the same field.
+    presentationMeta(args, value) {
+      const result = value as Record<string, unknown>
+      const asked = args as { source?: unknown; scheme?: unknown }
+      return {
+        source: typeof asked.source === 'string' ? asked.source : '',
+        scheme: typeof asked.scheme === 'string' ? asked.scheme : 'default',
+        caption: typeof result.caption === 'string' ? result.caption : '',
+      }
+    },
   },
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,

package/src/diagram-review-tool.ts

@@ -25,7 +25,7 @@ function limitsOf(args: { maxMembers?: unknown; maxDepth?: unknown; maxNodes?: u
 export const diagramReviewTool = defineTool({
   name: DIAGRAM_REVIEW_TOOL_NAME,
   description:
-    'Review the structure of a diagram from its source text: how wide each boundary is, how deep they nest, and how many nodes the drawing holds, against budgets you can set. Accepts the same Mermaid and PlantUML subset as diagram_render and reports what it measured, so an empty report cannot be mistaken for a clean one. Read `verdict`, never `ok`. This reviews structure; it does not draw (diagram_render does) and it does not check behaviour (model_verify does).',
+    'Review the structure of a diagram from its source text: how wide each boundary is, how deep they nest, and how many nodes the drawing holds, against budgets you can set. Run it before a drawing goes in front of a reader: a picture that needs scrolling is no longer a summary. Accepts the same Mermaid and PlantUML subset as diagram_render and reports what it measured, so an empty report cannot be mistaken for a clean one. Read `verdict`, never `ok`. This reviews structure; it does not draw (diagram_render does) and it does not check behaviour (model_verify does).',
   parameters: {
     source: {
       type: 'string',

package/src/diagram.ts

@@ -11,6 +11,7 @@
  */
 
 import z from '@deepseek-ai/schemastery'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { diagramDiffTool } from './diagram-diff-tool.js'
 import { diagramRenderTool } from './diagram-render-tool.js'
 import { diagramReviewTool } from './diagram-review-tool.js'
@@ -56,6 +57,36 @@ export function apply(ctx: ComponentContext, config: Config): void {
   ctx.tools.register(diagramRenderTool)
   ctx.tools.register(diagramReviewTool)
   ctx.tools.register(diagramDiffTool)
+  registerAnnotateCommand(ctx)
+}
+
+/**
+ * Offer an annotation as a session command, so a page can send one without a composer.
+ *
+ * Optional on purpose, and failure-tolerant on purpose: a host without the commands service keeps the
+ * composer path, and a registration that throws must not take the drawing tools down with it.
+ */
+export function registerAnnotateCommand(ctx: unknown): void {
+  const commands = (ctx as { get?: (name: string) => unknown }).get?.('commands') as { register?: (definition: unknown) => unknown } | undefined
+  if (commands === undefined || typeof commands.register !== 'function') return
+  try {
+    commands.register({
+      name: 'annotate',
+      description: 'Send a diagram annotation to this session',
+      handler: (invocation: { agent?: { followup?: (input: unknown) => unknown }; rawInput?: string; commandId?: unknown; attachments?: unknown; signal?: unknown }) => {
+        const raw = typeof invocation.rawInput === 'string' ? invocation.rawInput.trim().replace(/^\/?annotate\s*/i, '') : ''
+        const agent = invocation.agent
+        const followup = agent?.followup
+        if (raw === '' || typeof followup !== 'function') return { kind: 'error' as const, text: 'this host cannot take a follow-up note' }
+        // A follow-up takes a UserMessage, not a bag of fields: the runtime stamps the id and the time, and a
+        // hand-built object reaches the inbox without them. `createUserMessage` is the host's own constructor.
+        followup.call(agent, createUserMessage({ content: [{ type: 'text', text: raw }], source: { kind: 'user' } }))
+        return { kind: 'success' as const, text: 'annotation sent' }
+      },
+    })
+  } catch {
+    // A host whose command API differs keeps the composer path; the tools above are already registered.
+  }
 }
 
 export const inject = ['tools']

package/src/gate.ts

@@ -10,13 +10,15 @@
  *
  * Why it is a separate row. The plugin's doctrine is that a capability is discoverable
  * through its own tool description or skill text. Injection departs from that, so it is
- * opt-in and mounted as its own component: install it, disable it, or never enable it,
- * without touching the tools or the skills. `enabled` is a live switch, so the Web Plugins
- * page flips it inside a running host.
+ * mounted as its own component: the bundle's patch enables it, and the row can be turned off
+ * or removed without touching the tools or the skills. `enabled` is a live switch, so the Web
+ * Plugins page flips it inside a running host.
  *
- * Why it is off by default. It costs tokens in every session that turns it on, to fix a
- * problem text-only routing was measured not to have once the session engages. A deployment
- * that wants it says so; the default pays nothing.
+ * Why the bundle turns it on. Measured: a session that never decides to load a skill is never
+ * routed, and the catalog line is cut at 500 characters, so a domain the request names can be
+ * invisible at the moment of choosing. The cost is a fixed message in every session, which is
+ * why the switch is live and documented: turn it off where the bundle's default is wrong. The
+ * component's own `enabled` script default is off, so a bare `app.add(gate)` injects nothing.
  *
  * What it does not do. It routes; it checks nothing. It cannot make a skill load, and it
  * does not restate the doctrine - the skill bodies carry that, and duplicating them here
@@ -109,9 +111,9 @@ export function renderGateText(skills: string[] = shippedSkills(), extraGuidance
   const rows = skills.map((skill) => '| ' + (SKILL_ROWS[skill] ?? 'see its catalog line') + ' | `' + skill + '` |')
   const extra = extraGuidance.trim()
   return `<EXTREMELY_IMPORTANT>
-Before answering anything about code, a design or a diagram: load the skill whose row matches and let its tool decide. Do not answer from memory.
+Before answering anything about code, a design or a diagram: load the matching skill and let its tool decide. Do not answer from memory.
 
-dsh-model-everything is active: it checks claims about designs and code - facts against the source, behaviour as a model, structure as a graph.
+dsh-model-everything checks claims about designs and code: facts against the source, behaviour as a model, structure as a graph.
 
 **Unsure which row applies?** Load \`model-everything\` first: it owns the doctrine, the schema and the routing to its siblings.
 
@@ -121,17 +123,19 @@ ${rows.join('\n')}
 
 **Tools** (dsh):
 
-- \`model_verify\` — one state machine: structural checks, adversarial probes, budgets, deadlines, regression.
-- \`model_compose_verify\` — two or more machines: deadlock, a rendezvous that never fires, and - with \`shared\` + \`accesses\` - an unordered write (C4) or a non-atomic update (C5).
-- \`model_datamodel_verify\` — a data model and its migration: keys, domains, coverage, copy consistency, rollback symmetry.
-- \`model_design_review\` — a design against its own declarations: layering, boundaries, substitutability, interface width. Graph shape is reported, not judged.
-- \`model_interleaving_scan\` — finds claims about threads, async and interrupts, names the family and routes each to what decides it. It proves nothing itself.
-- \`model_export\` — UPPAAL, TLA+, PRISM or SPIN input from a model. It exports; it does not check the target.
-- \`uml_render\`, \`uml_parse\`, \`uml_review\` — draw a model, read a diagram into one, audit one. Round-trip fidelity is measured.
-- \`uml_explain_labels\` — the accepted label and comment forms for one notation.
-- \`uml_structure_verify\` — dependency review of a structure drawing, one level or several. It audits the drawing, not the code.
-- \`diagram_render\`, \`diagram_review\`, \`diagram_diff\` — draw, size and compare a Mermaid or PlantUML source. Undrawable lines are refused by number.
-- \`report_diff\` — baseline against current: what a change added, removed or changed.
+- \`model_verify\` — a state machine: structural checks, adversarial probes, budgets, deadlines, regression.
+- \`model_compose_verify\` — several machines: deadlock, a handshake that never fires, an unordered write (C4), a non-atomic update (C5).
+- \`model_datamodel_verify\` — a data model and its migration: keys, domains, coverage, copy consistency, rollback.
+- \`model_design_review\` — a design against its own declarations: layering, boundaries, substitutability, interface width.
+- \`model_interleaving_scan\` — finds concurrency claims, names the family, routes each to what decides it. Proves nothing itself.
+- \`model_export\` — UPPAAL, TLA+, PRISM or SPIN input from a model. It does not check the target.
+- \`uml_render\`, \`uml_parse\`, \`uml_review\` — draw a model, read a diagram into one, audit one; round-trip measured.
+- \`uml_explain_labels\` — the label and comment forms a notation accepts.
+- \`uml_structure_verify\` — dependency review of a structure drawing. It audits the drawing, not the code.
+- \`diagram_render\`, \`diagram_review\`, \`diagram_diff\` — draw, size, compare a Mermaid or PlantUML source. Undrawable lines are refused by number.
+- \`model_automaton_verify\` — an automaton or two: what it accepts, trap states, language relation, with a witness word.
+- \`model_edit\` — one named change to a model file plus the finding delta. Refuses an edit that leaves the model invalid.
+- \`report_diff\` — baseline against current: findings added, removed or changed.
 
 **Read a report**: gate on \`verdict\`, never on \`ok\`. \`verdictReason\` says why and \`nextSteps\` says what to do. \`ran\` says whether it executed, \`checksRun\` how much it examined: a \`skip\` is not a \`pass\`, and a code ending \`_UNDECIDED\` means the search hit its limit and decided nothing. Keys starting with \`_\` are notes: ignored, and left out of the model hash.
 

package/src/render/paint.ts

@@ -52,6 +52,8 @@ export interface Point {
 
 export interface BoxShape {
   kind: 'box'
+  /** Which node this box is. It travels into the markup, so a reader can target one node by delegation. */
+  id: string
   x: number
   y: number
   width: number
@@ -565,6 +567,7 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     const text = textOf(node)
     shapes.push({
       kind: 'box',
+      id: node.id,
       x: box.x,
       y: box.y,
       width: box.width,
@@ -1550,6 +1553,8 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     ...Array.from(groupRects.values(), (rect) => rect.y + rect.height),
   )
   const captionTop = contentBottom + CAPTION_GAP
+  // Anchored at the left margin, where the title is. The writer starts the text there: centred on a left-edge x,
+  // half of a long caption fell outside the drawing and was clipped at the bottom edge of the picture.
   shapes.push({ kind: 'caption', x: MARGIN, y: captionTop, lines: captionLines, colour: captionRole(diagram.caption) })
   const height = captionTop + captionLines.length * CAPTION_LINE + MARGIN / 2
 

package/src/render/svg.ts

@@ -143,7 +143,9 @@ const writers: { [K in Shape['kind']]: Writer<K> } = {
     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>'
   },
 }
 
@@ -258,7 +260,11 @@ export function toSvg(canvas: Canvas, colours: Palette, label?: string): { marku
       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 as { id?: unknown }).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) +

package/src/routing.ts

@@ -78,6 +78,18 @@ export const ROUTES: Record<string, Route> = {
     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. */

package/src/transcript.ts

@@ -0,0 +1,349 @@
+/**
+ * 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))'
+
+export interface TranscriptNode {
+  nodeType?: number
+  nodeValue?: string | null
+  textContent?: string | null
+  style?: Record<string, string | undefined>
+  setAttribute?: (name: string, value: string) => void
+  getAttribute?: (name: string) => string | null
+  addEventListener?: (type: string, handler: () => void) => void
+  querySelectorAll?: (selector: string) => ArrayLike<TranscriptNode>
+  getBoundingClientRect?: () => { left: number; top: number; width: number; height: number }
+  closest?: (selector: string) => TranscriptNode | null
+  childNodes?: ArrayLike<TranscriptNode>
+  nextSibling?: TranscriptNode | null
+  appendChild?: (node: TranscriptNode) => unknown
+  removeChild?: (node: TranscriptNode) => unknown
+  parentNode?: {
+    insertBefore?: (node: TranscriptNode, before: TranscriptNode | null) => unknown
+    removeChild?: (node: TranscriptNode) => unknown
+  } | null
+}
+
+export interface TranscriptDocument {
+  querySelectorAll?: (selector: string) => ArrayLike<TranscriptNode>
+  createElement?: (tag: string) => TranscriptNode
+}
+
+/** One note as the block states it. */
+export interface AnnotationItem {
+  index: number
+  node: string
+  note: string
+}
+
+/** The count in the opening line, for the chip; null when the line says something unexpected. */
+export function annotationCountOf(text: string): number | null {
+  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: string): string {
+  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: string): AnnotationItem[] {
+  const items: AnnotationItem[] = []
+  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: TranscriptNode): TranscriptNode[] {
+  const out: TranscriptNode[] = []
+  const visit = (node: TranscriptNode): void => {
+    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: TranscriptNode[], cut: number): boolean {
+  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: TranscriptNode): boolean {
+  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: TranscriptNode): boolean {
+  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: TranscriptDocument, items: AnnotationItem[], title: string, full: string): TranscriptNode | undefined {
+  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: TranscriptNode, map: Record<string, string | undefined>): void {
+  const decl = node.style as unknown as { setProperty?: (name: string, value: string) => void } | undefined
+  if (typeof decl?.setProperty === 'function') {
+    const target = decl as unknown as { setProperty: (name: string, value: string) => void }
+    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: TranscriptDocument, label: string, title: string, text: string): TranscriptNode | undefined {
+  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 = (): void => {
+    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 = (): void => { 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: TranscriptDocument | undefined, label = 'Notes', title = 'Notes in this message'): number {
+  if (doc === undefined || typeof doc.querySelectorAll !== 'function') return 0
+  let nodes: ArrayLike<TranscriptNode>
+  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: TranscriptDocument | undefined, label = 'Notes', title = 'Notes in this message'): () => void {
+  decorateTranscript(doc, label, title)
+  return () => {}
+}