dsh-model-everything 0.4.0 → 0.5.0

package/skills/model-everything/references/architecture-domains.md

@@ -0,0 +1,137 @@
+# Architecture by domain: what is decidable, and with what
+
+The same engine is asked different questions in different domains. This file says, per domain, what the
+architecture is made of, which claims decide something at design time, which of this plugin's families
+decides them, and where the claim has to go instead.
+
+Two rules apply everywhere:
+
+- **The verdict is about the model.** A domain's real constraints — schedulability, timing closure,
+  trained-model quality, certification — are outside the model unless they were modelled.
+- **Route the rest.** Every domain below ends with what this plugin cannot decide, and where to send it.
+
+## Layered systems, services and microservices
+
+Made of: modules or services, their allowed dependencies, the direction of those dependencies, and the
+contracts across the boundaries.
+
+Decidable here:
+
+- a dependency cycle, and the shortest one (UML022);
+- an edge between two layers that the declared matrix forbids (UML023, UML024);
+- a service nobody calls, or a required edge that is missing (UML020, UML025);
+- an interface wider than its callers, a responsibility with no owner (`model_design_review`, DES-level).
+
+Where it stops: a distributed transaction, a consistency guarantee, or a failure mode under partial
+availability is not an edge. Those go to `model_compose_verify` when the protocol is modelled, and to a
+saga or retry design review otherwise — the pattern language for that is Hohpe and Woolf's *Enterprise
+Integration Patterns* and, for the failure side, Nygard's *Release It!*.
+
+## Event-driven and streaming
+
+Made of: producers, topics, consumers, delivery guarantees, the order in which things are observed.
+
+Decidable here: event completeness (every event handled), deadlock and livelock in a modelled consumer
+protocol, an ordering hazard when two machines interleave (`model_compose_verify`), duplicate delivery
+when the model declares idempotency.
+
+Where it stops: the guarantee a broker actually provides. Idempotency as a property to model rather than
+assume is Helland's argument (*Idempotence Is Not a Medical Condition*); the clock and ordering
+foundations are Lamport's *Time, Clocks, and the Ordering of Events*.
+
+## Data and analytics
+
+Made of: entities, keys, constraints, migrations, and the invariants the business relies on.
+
+Decidable here: `model_datamodel_verify` — key and domain checks, referential integrity, migration
+coverage, copy consistency, rollback symmetry, before/after preservation.
+
+Where it stops: query performance, storage layout, and the modelling judgement itself. The relational
+foundation is Codd (1970); dimensional design is Kimball and Ross; the distribution and consistency
+vocabulary that a modern data architecture needs is Kleppmann's *Designing Data-Intensive Applications*;
+organisational topology of data ownership is Dehghani's *Data Mesh*.
+
+## Distributed consensus and protocols
+
+Made of: roles, messages, timeouts, elections, and the states each node may be in.
+
+Decidable here: whether a protocol state machine can reach a forbidden state, whether two machines
+deadlock on a handshake, whether an automaton accepts the language it claims, and whether two automata
+accept the same one (`model_automaton_verify`). Export for a second opinion goes to TLA+, SPIN, UPPAAL or
+PRISM.
+
+Where it stops: liveness under fairness, and performance. The practical argument that this is worth doing
+at all is Newcombe et al., *How Amazon Web Services Uses Formal Methods*; the specification language is
+Lamport's *Specifying Systems*; consensus algorithms to read are Paxos (Lamport) and Raft (Ongaro and
+Ousterhout).
+
+## Embedded and real-time
+
+Made of: tasks, interrupts, shared state, modes, and the deadlines that decide whether the design works.
+
+Decidable here: an interrupt handler and a task reaching the same state in an unsafe order
+(`model_compose_verify` with the shared-location checks), a mode machine that can enter an impossible
+combination (`model_verify`), a protocol FSM that drops a message the peer expects.
+
+Where it stops, and this is the important part: **schedulability, worst-case execution time, jitter and
+stack depth are not decided by a state machine.** They need rate-monotonic or response-time analysis
+(Liu and Layland; Liu, *Real-Time Systems*), a timing-aware model (MARTE, timed automata), or measurement
+on target. Architectural modelling standards for the domain are AUTOSAR and ARINC 653; certification
+evidence is DO-178C for airborne software and ISO 26262 for automotive, and no report from this plugin is
+evidence for either.
+
+## Hardware, SoC and platform architecture
+
+Made of: IP blocks, buses, address maps, interrupts, and the hierarchy of subsystems.
+
+Decidable here: an interface protocol described as a state machine, the dependency structure between
+blocks (acyclic, layered), and the handshake between a controller and a peripheral model.
+
+Where it stops: timing closure, power, area, and the register-level correctness of an RTL implementation.
+The description standards worth knowing are IEEE 1685 (IP-XACT) for component descriptions and AMBA AXI
+for the bus protocol; the architectural framing is platform-based design and the computer-architecture
+background is Hennessy and Patterson.
+
+## Machine-learning systems
+
+Made of: data sources, pipelines, features, training, serving, and the feedback loops between them.
+
+Decidable here: the pipeline as a dependency graph (cycles, orphans, undeclared inputs), and the
+data contract between stages as a data model.
+
+Where it stops: whether the model is any good. That is data validation and evaluation, for which the
+*ML Test Score* (Breck et al.) and *Hidden Technical Debt in Machine Learning Systems* (Sculley et al.)
+are the vocabulary; Huyen's *Designing Machine Learning Systems* is the architecture-level treatment.
+
+## Safety, security and compliance architecture
+
+Made of: hazards, controls, trust boundaries, and the evidence each claim needs.
+
+Decidable here: almost nothing directly, and saying so is the point. This plugin can check that a
+control's state machine cannot be bypassed, or that a trust boundary is not crossed by an undeclared
+dependency. It cannot certify anything.
+
+Where it stops: hazard analysis (STPA — Leveson and Thomas), threat modelling (Shostack, *Threat
+Modeling: Designing for Security*), and every certification regime.
+
+## Provenance
+
+| Part | Where it comes from |
+|---|---|
+| the per-domain split, and which family answers which question | this repository's own organisation of its tools |
+| integration patterns and the failure-side vocabulary | Hohpe and Woolf, *Enterprise Integration Patterns* (2003); Nygard, *Release It!* (2007) |
+| idempotency as a property to model | Helland, *Idempotence Is Not a Medical Condition*, ACM Queue (2012) |
+| ordering in distributed systems | Lamport, *Time, Clocks, and the Ordering of Events in a Distributed System*, Communications of the ACM (1978) |
+| the relational model | Codd, *A Relational Model of Data for Large Shared Data Banks*, Communications of the ACM (1970) |
+| dimensional design and modern data architecture | Kimball and Ross, *The Data Warehouse Toolkit* (2013); Kleppmann, *Designing Data-Intensive Applications* (2017); Dehghani, *Data Mesh* (2022) |
+| formal methods in industrial practice | Newcombe et al., *How Amazon Web Services Uses Formal Methods*, Communications of the ACM (2015); Lamport, *Specifying Systems* (2002) |
+| consensus algorithms | Lamport, *The Part-Time Parliament* (1998); Ongaro and Ousterhout, *In Search of an Understandable Consensus Algorithm* (2014) |
+| real-time analysis and the boundary of this plugin | Liu and Layland, *Scheduling Algorithms for Multiprogramming in a Hard-Real-Time Environment*, Journal of the ACM (1973); Liu, *Real-Time Systems* (2000); Kopetz, *Real-Time Systems* (2011) |
+| embedded and safety standards named, not implemented | AUTOSAR; ARINC 653; DO-178C; ISO 26262; UML MARTE |
+| hardware description and bus standards | IEEE 1685 (IP-XACT); AMBA AXI; Hennessy and Patterson, *Computer Architecture* |
+| ML system architecture and its failure modes | Sculley et al., *Hidden Technical Debt in Machine Learning Systems* (2015); Breck et al., *The ML Test Score* (2017); Huyen, *Designing Machine Learning Systems* (2022) |
+| hazard and threat analysis | Leveson and Thomas, *STPA Handbook* (2018); Shostack, *Threat Modeling: Designing for Security* (2014) |
+
+Citations are given without volume and page numbers where those were not verified against the
+publication. Every standard named here is named as a boundary — what the domain requires — not as
+something this plugin implements.

package/skills/model-everything/references/architecture-views.md

@@ -0,0 +1,119 @@
+# Architecture views, hierarchy, and conformance
+
+The doctrine behind the design-time and as-is modes: what an architecture description is, why a level
+tree is the unit a reviewer reads, and how a drawing is reconciled with code. Per-domain concerns are in
+`architecture-domains.md`; the checks themselves live in the tools.
+
+## A view is what a reader acts on
+
+An architecture is not one picture. It is a set of **views**, each answering one stakeholder's question,
+and each written against a **viewpoint** that fixes what may appear in it. That framing is standardised
+in ISO/IEC/IEEE 42010:2011 and predates it in practice: Kruchten's 4+1 model made the point that
+logical, process, development and physical views are all "the architecture" and none of them is the
+whole.
+
+Two consequences for this plugin:
+
+- **A report is a view.** A dependency graph, a state machine and a data model are three views of the
+  same system, and a verdict about one is not a verdict about the others.
+- **The reader is fixed.** A view written for the architect who must decide is short and about
+  consequences; a view written for the team who must implement is longer and about interfaces. The
+  architecture-description literature keeps these apart deliberately — Clements et al. organise the
+  whole of *Documenting Software Architectures* around choosing the view for the audience, and Rozanski
+  and Woods write a viewpoint catalogue for exactly that reason.
+
+Simon Brown's C4 model is the pragmatic version most working architects actually use: four zoom levels
+(context, container, component, code), each one a different audience. It is not a formal method, and it
+does not claim to decide anything — which is precisely the gap this plugin fills.
+
+## Why hierarchy is not an optional feature
+
+Herbert Simon's *The Architecture of Complexity* (1962) is the argument: complex systems are
+**nearly decomposable**, and their subsystems interact far more strongly internally than across
+boundaries. That is why a level tree is how people describe and review them, and why a flat graph of a
+large system is not a simplification but a different, less useful object.
+
+The hierarchy literature supplies the semantics that makes a parent/child pair checkable rather than
+decorative:
+
+- **UML composite structure** describes a part inside a whole, with ports and connectors — the modelling
+  vocabulary for "this box expands".
+- **Event-B (Abrial)** and the CSP/CCS refinement tradition (Hoare; Milner) give refinement as a relation
+  between levels: a child may decide more, and may not contradict the parent.
+- Hierarchical graphs and algebraic graph transformation (Ehrig et al.) make containment itself the
+  morphism, which is what a parent/child diagram is.
+
+This plugin takes three rules from that and nothing more:
+
+1. **Containment** — a child's scope is one node in the parent, and that node is expanded exactly once.
+2. **Refinement** — a child may not introduce a cross-boundary edge the parent does not have. It may
+   introduce everything internal to its scope.
+3. **Budget** — a level past the drawing threshold must be decomposed. The limit is not a rendering
+   apology; it is the point at which a view stops being reviewable.
+
+## Reconciling the drawing with the code
+
+The as-is mode answers a question the design-time mode cannot: does the code still have the architecture
+we say it has? The established name for the technique is **reflexion modelling** (Murphy, Notkin and
+Sullivan): extract the implementation graph, declare the intended graph, and classify every edge as
+agreed, absent, or convergent — the third category being the interesting one, because convergence is
+usually a deliberate violation nobody wrote down.
+
+Related traditions worth knowing, and what each adds:
+
+- **Dependency Structure Matrix** (Steward; Browning) — cycles and layering read off a matrix instead of
+  a picture. A DSM is what tells you *which* edges to cut, where a graph tells you *that* there is a
+  cycle.
+- **Software architecture reconstruction** (Kazman and Carriere) — recovering the conceptual
+  architecture from artefacts when no declaration exists. Our `repoPath` scan is the cheap end of this:
+  imports only, no clustering, no inference about intent.
+- **Conformance tests in code** (ArchUnit and its descendants) — a rule checked by the build. That is the
+  right home for a rule once it is settled; this plugin is for deciding whether the rule is right.
+- **Architecture erosion and drift** (Perry and Wolf for the vocabulary) — the observation that the
+  implemented architecture decays unless something keeps checking it.
+
+The acyclic-dependencies and stable-dependencies principles (Martin) are the usual declared rules in this
+space; they are what a matrix encodes, and the engine judges them as edges rather than as opinions.
+
+## Drawing a level
+
+Layered graph drawing (Sugiyama, Tagawa and Toda) is the only layout this plugin needs to consider: place
+nodes in ranks, order within a rank to reduce crossings, then route edges. The general reference is Di
+Battista, Eades, Tamassia and Tollis, *Graph Drawing*.
+
+Two aesthetic findings shape the choices here rather than taste: edge crossings and bends dominate how
+quickly a reader parses a graph (Purchase's experiments on aesthetic criteria), and past a few dozen
+nodes comprehension of any layout collapses. That is the evidence behind a fixed drawing budget: the
+answer for a large level is a smaller level, not a cleverer layout.
+
+## Recording the decision
+
+An architecture decision record is the artefact that survives the meeting. The practice is described by
+Tyree and Akerman (*Architecture Decisions: Demystifying Architecture*, IEEE Software 2005) and
+popularised by Nygard's *Documenting Architecture Decisions* (2011): context, decision, status,
+consequences. arc42 is the document template most European teams use to hold them.
+
+A record generated from a verified model has one property a hand-written one does not: every consequence
+it states can name the check that produced it.
+
+## Provenance
+
+| Part | Where it comes from |
+|---|---|
+| views and viewpoints as the unit of description | ISO/IEC/IEEE 42010:2011; Kruchten, *The 4+1 View Model of Architecture*, IEEE Software (1995) |
+| choosing the view for its audience | Clements et al., *Documenting Software Architectures: Views and Beyond* (2010); Rozanski and Woods, *Software Systems Architecture* (2011) |
+| zoom levels as a practical hierarchy | Brown, *The C4 Model for Visualising Software Architecture* (2018) |
+| near-decomposability as the reason for levels | Simon, *The Architecture of Complexity* (1962) |
+| containment and refinement semantics | UML 2.5 composite structure; Abrial, *Modeling in Event-B* (2010); Hoare, *Communicating Sequential Processes* (1985); Milner, *Communication and Concurrency* (1989) |
+| the three hierarchy rules and the node budget | this repository's own decision, from the theory above |
+| reflexion modelling as the as-is method | Murphy, Notkin and Sullivan, *Software Reflexion Models*, IEEE Transactions on Software Engineering (2001) |
+| matrix view of cycles and layering | Steward, *The Design Structure System* (1981); Browning (2001) |
+| reconstruction from artefacts | Kazman and Carriere, *Playing Detective: Reconstructing Software Architecture from Available Evidence* (1999) |
+| erosion and drift | Perry and Wolf, *Foundations for the Study of Software Architecture* (1992) |
+| acyclic and stable dependency principles | Martin, *Agile Software Development* (2002) |
+| layered layout | Sugiyama, Tagawa and Toda, *Methods for Visual Understanding of Hierarchical System Structures* (1981); Di Battista et al., *Graph Drawing* (1999) |
+| crossing and size limits | Purchase's studies of aesthetic criteria; the specific threshold is this repository's |
+| decision records | Tyree and Akerman, *Architecture Decisions: Demystifying Architecture*, IEEE Software (2005); Nygard, *Documenting Architecture Decisions* (2011); arc42 |
+
+Citations are given without volume and page numbers where those were not verified against the
+publication. The argument does not depend on them; the reader who needs them can find the work by title.

package/skills/model-everything-diagram/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: model-everything-diagram
+description: "Use when drawing a diagram from its source text or checking its structure: Mermaid and PlantUML subsets, structure budgets, and containment diffs. Every line it cannot draw is refused by number. The drawing proves layout, not design. Doctrine: the model-everything skill.""
+---
+
+# Model Everything — Drawing
+
+A drawing is how a design is read, and a drawing that quietly drops a lifeline is worse than no drawing, because
+it looks complete. This skill covers the drawing half: it renders the subset it can actually draw, refuses the rest
+**by line**, measures the structure against budgets, and compares two drawings by what contains what.
+
+The doctrine it inherits — say what a result does and does not prove, read `verdict` and never `ok` — lives in the
+`model-everything` skill. Load that one when the question is whether a design is *correct*; load this one when the
+question is what the picture shows.
+
+## When This Skill Applies
+
+| The task involves… | What it does |
+|---|---|
+| "draw this mermaid", "render this PlantUML", "make a diagram of this flow" | `diagram_render`: source text to SVG, laid out and painted here, with `out` to write a file and `scheme` for the palette |
+| "is this diagram too dense", "how deep do the packages nest" | `diagram_review`: group width, nesting depth and node count against budgets you set, plus **what it measured** |
+| "what changed between these two diagrams", "did this package move" | `diagram_diff`: boundaries added, removed, renamed or re-parented, and nodes that changed owner |
+| A source in a notation the plugin does not draw | Refused with the line number; `diagram_render` still draws everything else and reports what it skipped |
+| A diagram already in a file, to link from a document | `diagram_render` with `out`, then link the SVG |
+
+## The two notations, and where each one stops
+
+| Notation | Drawn | Refused by name |
+|---|---|---|
+| Mermaid | `graph`/`flowchart` (TD/TB/LR), node shapes `[..]`, `(..)`, `{..}`, `((..))`, `[(..)]`, `[[..]]`, `<<..>>`; edges `-->`, `---`, `-.->`, `==>`, labels `-->\|text\|` and `-- text -->`; `stateDiagram`/`-v2` with `[*]` start and end markers and `state "text" as id`; `subgraph … end` including nesting | `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `journey`, `mindmap`, `timeline`, `quadrantChart`, `gitGraph`, `C4Context`, and the `click`/`style`/`classDef` directives |
+| PlantUML | `component`, `package`, `node`, `folder`, `cloud`, `database`, `state`, `artifact`, `rectangle` blocks and `[bracketed]` components; `-->`, `--->`, `..>`, either direction, `: label`; `[*] -->` start markers; `skinparam`/`!theme` ignored | `actor`, `participant`, `usecase`, `class`, `object`, `note`, `legend`, and the `alt`/`opt`/`loop`/`par` fragments |
+
+A refusal is one line in `refused`, phrased `line N: …`. The drawing you get does not show the refused lines, and
+the tool says so rather than leaving you to notice.
+
+## What the structure review reports
+
+| Code | Severity | What it means |
+|---|---|---|
+| `B1_GROUP_TOO_WIDE` | error | A boundary holds more direct children than the budget. A package with twenty boxes has stopped reading as a package. |
+| `B2_TOO_DEEP` | error | Nesting past the budget. Beyond three levels a reader needs the source, not the picture. |
+| `B3_EMPTY_GROUP` | error | A boundary with nothing drawable inside it: it claims a containment the drawing cannot show. |
+| `B4_SINGLE_MEMBER` | warning | A boundary around one thing. Often a layer that was never split, sometimes exactly right. |
+| `B5_TOO_MANY_NODES` | error | The whole drawing past its node budget. |
+| `D0_NO_SOURCE` | error | Nothing to review. |
+
+`measured` is printed next to `findings` on purpose: an empty finding list from a source that never parsed would
+otherwise read as a clean bill of health.
+
+## What the diff reports
+
+| Code | Kind | What changed |
+|---|---|---|
+| `H1_GROUP_ADDED` | info | A boundary that did not exist, saying what contains it when it is nested |
+| `H2_GROUP_REMOVED` | info | A boundary that is gone |
+| `H3_GROUP_RENAMED` | info | Same id, different text |
+| `H4_GROUP_MOVED` | warning | A boundary that changed parent, both sides named |
+| `H5_NODE_ADDED` / `H6_NODE_REMOVED` | info | A node that appeared or disappeared |
+| `H7_NODE_REGROUPED` | warning | A node that changed which group holds it |
+| `D1_SIDE_UNREADABLE` | error | One side produced no drawing, so there was nothing to compare |
+
+A rename is only a rename when the id survived. A vanished id beside a new one is an unrelated removal and
+addition, because the ids are what a caller tracks across versions.
+
+**It judges movement, not merit.** Whether a component belongs in its new package is the reader's call; the diff
+reports that the move happened and nothing more.
+
+## The whiteboard
+
+The right sidebar has a **Diagram** tab: paste a source, get the drawing. It scales to the pane, switches colour
+scheme (`default`, `github`, `high-contrast`, `print`), follows the page's light or dark surface, and folds a group
+into a single box when you click it. It reads no tool result, so it keeps working whatever changes on the tool side.
+
+## What this does not do
+
+- **It does not verify behaviour.** A drawing of a machine says nothing about whether the machine is safe; that is
+  `model_verify` on the model the drawing came from.
+- **It does not read a diagram back into a model.** `uml_parse` does that for the families it owns.
+- **It does not audit dependencies.** `uml_structure_verify` reads a component diagram as a dependency graph and
+  judges the edges; `diagram_review` only measures the shape.
+- **It does not draw everything.** A notation outside the subset above is refused by line; a picture that looks
+  complete and quietly lost half its arrows is the failure this whole subset exists to avoid.

package/src/client.ts

@@ -0,0 +1,307 @@
+/**
+ * The Client half: a lazy factory the page binds to this package's name.
+ *
+ * Everything that decides anything lives in `render/`; this file only turns shapes into React elements and
+ * registers them where the page offers a seat. Two seats are used, and they fail independently:
+ *
+ * - `tool.call.toolview` replaces the card of a tool whose result this package can draw;
+ * - `sidebar.right.pane.tab` is the whiteboard: a tab that renders whatever the reader pastes, with no tool
+ *   and no host data at all, so it keeps working when the card seat does not.
+ *
+ * This module is not a page script: it exports the factory, and `scripts/build-client.mjs` wraps the
+ * compiled output in `window.__ModuleLoader__.load(...)`, which is the loader contract itself.
+ */
+
+import { paintWith } from './render/paint.js'
+import { schemeNames, type Palette, type PaletteMode, type PaletteScheme } from './render/palette.js'
+import { render } from './render/index.js'
+import { toSvg } from './render/svg.js'
+import { viewModel } from './render/viewmodel.js'
+
+export interface ReactLike {
+  createElement: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown
+  useState?: <T>(initial: T) => [T, (next: T) => void]
+}
+
+export interface SlotContext {
+  slots: {
+    inject: (slot: string, callback: () => unknown) => unknown
+    register: (options: Record<string, unknown>, component: unknown) => unknown
+  }
+  get?: (service: string) => unknown
+}
+
+export interface PluginShape {
+  inject: string[]
+  apply: (ctx: SlotContext) => void
+  /** The whiteboard mount, with its scheduler injectable. `apply` calls this with the default. */
+  mount: (ctx: SlotContext, options?: MountOptions) => unknown
+}
+
+/** A settled tool call, as the host hands it to a view. */
+export interface ToolCallProps {
+  phase?: string
+  toolName?: string
+  block?: { args?: unknown; result?: unknown }
+}
+
+/** Tool names this package answers. A key that never dispatches simply never renders. */
+export const TOOL_NAMES: string[] = ['model_verify']
+
+/**
+ * Which surface the page is painting the drawing on.
+ *
+ * The host publishes its palette as private CSS variables, so naming them here would break on the next theme.
+ * The one fact that cannot drift is the rendered background: read it, and fall back to the media query, then
+ * to light. Never throws - a view that cannot read the document still draws.
+ */
+export function themeMode(): PaletteMode {
+  try {
+    // Reached through a loose view of the globals: this module is also loaded in Node by the bundle suite,
+    // where `document` does not exist at all.
+    const scope = globalThis as unknown as {
+      document?: { body?: unknown }
+      getComputedStyle?: (element: unknown) => { backgroundColor?: string }
+    }
+    const body = scope.document?.body
+    const computed = typeof scope.getComputedStyle === 'function' && body !== undefined ? scope.getComputedStyle(body) : undefined
+    const colour = computed?.backgroundColor ?? ''
+    const rgb = /rgba?\((\d+),\s*(\d+),\s*(\d+)/.exec(colour)
+    if (rgb !== null) {
+      const [r, g, b] = [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])]
+      // Rec. 601 luma: good enough to tell a light surface from a dark one, and cheap.
+      return (0.299 * r + 0.587 * g + 0.114 * b) / 255 < 0.5 ? 'dark' : 'light'
+    }
+  } catch {
+    // A document that refuses to be read is not a reason to fail a render.
+  }
+  return 'light'
+}
+
+/** The background a drawing sits on, so a card does not paint dark lines on a dark page. */
+function surfaceStyle(colours: Palette): Record<string, string> {
+  return { background: colours.background, color: colours.text, padding: '4px 0', overflowX: 'auto' }
+}
+
+
+/** The whiteboard's seat key, in both the tab registry and the body slot. */
+export const WHITEBOARD_ID = 'model-everything-diagram'
+
+/** What the whiteboard opens with: a diagram the reader can edit rather than an empty box. */
+export const WHITEBOARD_SAMPLE = ['graph TD', '  a[Idea] --> b{Feasible?}', '  b -->|yes| c[Build]', '  b -->|no| d[Revise]', '  d --> a'].join('\n')
+
+/**
+ * The view for one tool name.
+ *
+ * The drawing is emitted as markup, so React receives it through `dangerouslySetInnerHTML`. That is safe
+ * only because the writer escapes every value that came from a report or a model, which the render suite
+ * pins with an injection case.
+ */
+export function viewFor(React: ReactLike, overrides: Partial<Palette> = {}): (props: ToolCallProps) => unknown {
+  return (props: ToolCallProps): unknown => {
+    // The whole block goes to the view model: the host shapes it differently per phase (a lazy arguments
+    // view while running, content blocks once settled), and only that module knows how to read it.
+    const diagram = viewModel({ phase: props.phase, toolName: props.toolName, block: props.block })
+    const { canvas, colours } = paintWith(diagram, overrides, { mode: themeMode() })
+    const written = toSvg(canvas, colours, diagram.kind === 'none' ? diagram.caption : diagram.title + ': ' + diagram.caption)
+    return React.createElement('div', {
+      style: surfaceStyle(colours),
+      dangerouslySetInnerHTML: { __html: written.markup },
+    })
+  }
+}
+
+/**
+ * The whiteboard: paste a diagram, get a drawing, zoom it.
+ *
+ * It holds no host data, which is the point: it is a place to think about a diagram while writing one, and
+ * it cannot be broken by a change to any tool's result shape. The source it draws is whatever is in its own
+ * box.
+ */
+export function whiteboardFor(React: ReactLike, overrides: Partial<Palette> = {}): () => unknown {
+  const h = (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]): unknown => React.createElement(type, props, ...children)
+  return function Whiteboard(): unknown {
+    const useState = React.useState as (<T>(initial: T) => [T, (next: T) => void]) | undefined
+    if (useState === undefined) {
+      // A host without hooks: the same board, read-only. It still draws, which is the part that matters.
+      return h(
+        'div',
+        { style: { padding: '8px' } },
+        h('textarea', {
+          value: WHITEBOARD_SAMPLE,
+          readOnly: true,
+          spellcheck: false,
+          rows: WHITEBOARD_SAMPLE.split('\n').length,
+          style: { width: '100%', font: '12px ui-monospace, SFMono-Regular, Menlo, monospace' },
+        }),
+        // The picker is present but inert: a host without hooks cannot hold the choice, and hiding the
+        // option would make the board look like it has none.
+        h('select', { disabled: true, style: { margin: '4px 0', fontSize: '12px' } },
+          ...schemeNames().map((name) => h('option', { value: name, selected: name === 'default' }, name))),
+        whiteboardBody(React, overrides, WHITEBOARD_SAMPLE, 1),
+      )
+    }
+    const [source, setSource] = useState(WHITEBOARD_SAMPLE)
+    const [zoom, setZoom] = useState(1)
+    const [scheme, setScheme] = useState<PaletteScheme>('default')
+    const [fit, setFit] = useState(true)
+    const [folded, setFolded] = useState<string[]>([])
+    const drawn = drawSample(React, overrides, source, fit ? 0 : zoom, scheme, folded)
+    const textarea = h('textarea', {
+      value: source,
+      spellcheck: false,
+      rows: Math.min(12, Math.max(4, String(source).split('\n').length)),
+      style: { width: '100%', font: '12px ui-monospace, SFMono-Regular, Menlo, monospace', padding: '6px', resize: 'vertical' },
+      onInput: (event: { target?: { value?: unknown } }) => setSource(String(event?.target?.value ?? '')),
+    })
+    const controls = h(
+      'div',
+      { style: { display: 'flex', gap: '6px', alignItems: 'center', padding: '4px 0', flexWrap: 'wrap' } },
+      h('button', { type: 'button', onClick: () => { setFit(false); setZoom(Math.max(0.5, Math.round((Number(zoom) - 0.25) * 100) / 100)) } }, '−'),
+      h('span', { style: { fontSize: '12px', opacity: 0.7 } }, fit ? 'fit' : String(Math.round(Number(zoom) * 100)) + '%'),
+      h('button', { type: 'button', onClick: () => { setFit(false); setZoom(Math.min(3, Math.round((Number(zoom) + 0.25) * 100) / 100)) } }, '+'),
+      h('button', { type: 'button', onClick: () => { setFit(false); setZoom(1) } }, 'reset'),
+      h('button', { type: 'button', title: 'Scale to the pane width', onClick: () => setFit(!fit) }, fit ? 'fit: on' : 'fit: off'),
+      folded.length === 0
+        ? null
+        : h('button', { type: 'button', title: 'Unfold every group', onClick: () => setFolded([]) }, 'unfold ' + String(folded.length)),
+      h(
+        'select',
+        {
+          value: scheme,
+          title: 'Colour scheme',
+          style: { marginLeft: 'auto', fontSize: '12px' },
+          onChange: (event: { target?: { value?: unknown } }) => setScheme(String(event?.target?.value ?? 'default') as PaletteScheme),
+        },
+        ...schemeNames().map((name) => h('option', { value: name, selected: name === scheme }, name)),
+      ),
+    )
+    return h(
+      'div',
+      { style: { display: 'flex', flexDirection: 'column', gap: '4px', height: '100%', boxSizing: 'border-box', padding: '8px' } },
+      textarea,
+      controls,
+      // The drawing takes the rest of the pane and scrolls inside it, so an expanded tab uses its room.
+      h(
+        'div',
+        {
+          style: { flex: '1 1 auto', minHeight: '0', overflow: 'auto' },
+          // A boundary carries its id in the markup, so one listener on the container is enough: no per-rect
+          // handler, and the handling survives a re-render that replaced the whole SVG.
+          onClick: (event: { target?: { closest?: (selector: string) => { getAttribute?: (name: string) => string | null } | null } }) => {
+            const hit = event?.target?.closest?.('[data-group-id]')
+            const id = hit?.getAttribute?.('data-group-id')
+            if (typeof id !== 'string' || id === '') return
+            setFolded(folded.includes(id) ? folded.filter((entry) => entry !== id) : [...folded, id])
+          },
+        },
+        drawn,
+      ),
+    )
+  }
+}
+
+function drawSample(React: ReactLike, overrides: Partial<Palette>, source: string, zoom: number, scheme: PaletteScheme, folded: string[] = []): unknown {
+  return whiteboardBody(React, overrides, source, zoom, scheme, folded)
+}
+
+/** Render one source at one zoom, or say why it could not be drawn. */
+function whiteboardBody(React: ReactLike, overrides: Partial<Palette>, source: string, zoom: number, scheme: PaletteScheme = 'default', folded: string[] = []): unknown {
+  if (String(source).trim() === '') {
+    return React.createElement('p', { style: { fontSize: '12px', opacity: 0.7 } }, 'Paste Mermaid or PlantUML above.')
+  }
+  const drawn = render({ source: String(source), folded }, overrides, { mode: themeMode(), scheme })
+  // Zoom 0 is "fill the pane": the SVG scales to the width it is given, which is what an expanded tab wants.
+  const zoomed =
+    zoom === 0
+      ? drawn.markup.replace('<svg ', '<svg style="width: 100%; height: auto; display: block" ')
+      : drawn.markup.replace('<svg ', '<svg style="zoom: ' + String(zoom) + '; display: block" ')
+  const refused = drawn.refused.length === 0 ? null : React.createElement('pre', {
+    style: { fontSize: '11px', color: '#b7791f', whiteSpace: 'pre-wrap', margin: '6px 0' },
+  }, drawn.refused.join('\n'))
+  return React.createElement(
+    'div',
+    { style: { background: drawn.colours.background, color: drawn.colours.text, borderRadius: '6px' } },
+    React.createElement('div', { dangerouslySetInnerHTML: { __html: zoomed } }),
+    refused,
+  )
+}
+
+
+/** How long to wait for the optional services, and how often. A page that never offers them registers nothing. */
+const SIDEBAR_POLL_MS = 250
+const SIDEBAR_POLL_ATTEMPTS = 40
+
+interface SidebarTabsService {
+  register?: (options: Record<string, unknown>) => unknown
+}
+
+export interface MountOptions {
+  /** Injected so the suite can drive the poll without waiting. Defaults to `setTimeout`. */
+  schedule?: (run: () => void, delay: number) => unknown
+}
+
+/**
+ * Register the whiteboard tab once the sidebar's optional services are ready.
+ *
+ * The slot can be declared before `sidebarRightTabs` exists - the host composes services and seats in an
+ * order this plugin does not control - and a single `ctx.get` there is a race that loses the tab silently.
+ * So it polls, like the reference implementation does, and stops after a bounded number of attempts.
+ */
+export function mountWhiteboard(React: ReactLike, ctx: SlotContext, options: MountOptions = {}): unknown {
+  const schedule =
+    options.schedule ??
+    ((run: () => void, delay: number) => {
+      // A host (or a test sandbox) without timers simply gets no retry, rather than an exception.
+      const timer = (globalThis as unknown as { setTimeout?: (f: () => void, ms: number) => unknown }).setTimeout
+      return typeof timer === 'function' ? timer(run, delay) : undefined
+    })
+  let attempts = 0
+
+  const attempt = (): unknown => {
+    attempts += 1
+    const tabs = typeof ctx.get === 'function' ? (ctx.get('sidebarRightTabs') as SidebarTabsService | undefined) : undefined
+    if (tabs === undefined || typeof tabs.register !== 'function') {
+      if (attempts < SIDEBAR_POLL_ATTEMPTS) schedule(attempt, SIDEBAR_POLL_MS)
+      return undefined
+    }
+    tabs.register({
+      id: WHITEBOARD_ID,
+      kind: 'panel',
+      keepMounted: true,
+      title: () => 'Diagram',
+      guide: [
+        {
+          id: 'diagram-whiteboard',
+          order: 120,
+          title: () => 'Diagram',
+          description: () => 'Paste Mermaid or PlantUML and read the drawing',
+        },
+      ],
+    })
+    return ctx.slots.register({ name: 'sidebar.right.pane.tab', key: WHITEBOARD_ID }, whiteboardFor(React))
+  }
+
+  return attempt()
+}
+
+export default function factory(require: (name: string) => unknown): PluginShape {
+  // Captured under a plain name: a static `require('react')` would be rewritten by the bundler and then
+  // resolve against a scope the factory body does not have. A call through this alias stays a call.
+  const hostRequire = require
+  const React = hostRequire('react') as ReactLike
+  return {
+    inject: ['slots'],
+    mount: (ctx: SlotContext, options: MountOptions = {}) => mountWhiteboard(React, ctx, options),
+    apply(ctx: SlotContext) {
+      for (const name of TOOL_NAMES) {
+        // Only the options a keyed slot declares: `key`. An extra `id` is not part of this slot's
+        // registration schema, and the working community reference (dsh-deepread) passes exactly this much.
+        ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: name }, viewFor(React)))
+      }
+      // The whiteboard seat only exists on a host with the official right sidebar. Presence of the slot is
+      // the capability check: if the callback never runs, this host has no sidebar and nothing is lost.
+      ctx.slots.inject('sidebar.right.pane.tab', () => mountWhiteboard(React, ctx))
+    },
+  }
+}