qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/references/viewer-development.md

@@ -12,12 +12,12 @@ Source paths below are relative to `assets/viewer/src/`.
 | Change theme, font sizes or line heights | `visual-style.js`, `radix-colors.js` | Radix scales, theme variables, semantic colors, core recognition and dimensions shared by page and export |
 | Change node shapes or internal layout | Matching `diagrams/<type>.js`; shared cards use `diagrams/card.js` | Both page and SVG/PNG nodes |
 | Change shared SVG typography and primitives | `diagrams/drawing.js` | `svgStyles()`, escaping and shared primitives; scoped on the page and reused in export |
-| Change toolbar, details or responsive shell | `ViewerShell.jsx`, `styles.css` | Page shell; no second HTML/CSS implementation of node content |
+| Change toolbar, details or desktop shell | `ViewerShell.jsx`, `styles.css` | Page shell; no second HTML/CSS implementation of node content |
 | Change restrained motion effects | the motion-effects block at the end of `styles.css` | Moving stroke widths and reduced selection halo while flowing; no permanent role/module glow or colored vignette; honors contrast/transparency preferences |
 | Change selection or search | `features/useSelection.js`, `search.js` | Shared selection, feedback, keyboard and dismissal; search ranking is independently testable |
 | Change directional edge motion | `features/useViewerController.js`, `features/usePresentation.js`, `DiagramCanvas.jsx`, `styles.css` | Direction-only animation controlled by its switch and reduced-motion preference; dashed sequence baselines, masks and selection strokes travel together while retaining gaps |
 | Change the reading legend | `ViewerShell.jsx`, `styles.css`; content from `legend.js`, `visual-style.js` | Floating legend popover from actual categories and line styles; retain original symbols, shared `nodeAppearance` colors and core priority |
-| Change panels and focus | `features/usePanels.js` | Mobile mutual exclusion, visibility and focus return; preserve panel preference on view switches |
+| Change panels and focus | `features/usePanels.js` | Desktop panel visibility and focus return; preserve panel preference on view switches |
 | Change canvas fullscreen | `features/useFullscreen.js`, `features/useSelection.js` | Native fullscreen, failure notices and focus return; selection in fullscreen does not open an external Inspector, Escape exits fullscreen first |
 | Change dragging, viewport, lock or spacing | `features/useGraphLayout.js`, `layout-nudge.js` | Current positions and layout operations; D3 remains a bounded nudge |
 | Change presentation state | `features/usePresentation.js` | Project selection and search into nodes and edges without a second state owner |
@@ -29,7 +29,7 @@ Source paths below are relative to `assets/viewer/src/`.
 ## Add a diagram type
 
 1. Add a module in `diagrams/` with a default-exported definition.
-2. Import it in `diagrams/registry.js` and add it to `DIAGRAMS`. Registry order is collection menu order; standalone graphs still have no type menu.
+2. Import it in `diagrams/registry.js` and add it to `DIAGRAMS`. Presentation order comes from `view-identity.js`; standalone graphs still have no type menu.
 3. Update `graph-schema.md`, `visual-contract.md` and the authoring instructions in SKILL so the author knows the type. Registering a type need not change the data structure.
 4. Build the template, generate examples and verify type-specific nodes, relationships and browser interactions.
 
@@ -80,7 +80,7 @@ QA_HEADED=1 QA_ONLY_EXTRAS=1 QA_EXTRAS=fullscreen,fullscreen-errors \
 node scripts/browser-interactions.mjs /tmp/new-viewer /tmp/fullscreen-check
 ```
 
-The browser script covers every supplied type at three sizes, in light and dark themes, with interactions. Use a nine-type collection for the full matrix. `QA_FIXTURE_DIR` adds special-shape fixtures. The script needs adjacent source modules and cannot be copied as a standalone script.
+The browser script covers every supplied type at three sizes, in light and dark themes, with interactions. Use a eleven-view collection for the full matrix. `QA_FIXTURE_DIR` adds special-shape fixtures. The script needs adjacent source modules and cannot be copied as a standalone script.
 
 Details follow the user's selection: `useSelection` owns selection and `useViewerController` derives `inspectedNode`; the quick-look card and Inspector in `ViewerShell` consume it. There is no autoplay, step-by-step reading or flow orchestration. The legend is in a floating button at the canvas's top left; `.inspector-facts` remains the last details section. `DiagramCanvas`'s `has-flow` and `styles.css` control static-layer contrast during edge motion; selection must not fill the moving dash gaps.
 
@@ -89,7 +89,7 @@ QA_ONLY_EXTRAS=1 QA_EXTRAS=flow-contrast,inspector-sync \
 node scripts/browser-interactions.mjs /tmp/new-viewer /tmp/new-viewer-sync-check
 ```
 
-`diagram-modules.test.mjs` adds a tenth test type in a temporary copy, changes only that copy's module and registry, and performs validation, build and generation. The product still supports nine types. Set `MODULE_TEST_OUTPUT=/tmp/new-module-check` to retain the copy and use its `skills/q-flow/scripts/browser-interactions.mjs` to check `page/`. The copy preserves repository hierarchy and root third-party notices to verify actual build dependencies. The directory must not already exist.
+`diagram-modules.test.mjs` adds a tenth test type in a temporary copy, changes only that copy's module and registry, and performs validation, build and generation. The product supports eleven presentation types over nine compatible semantic types. Set `MODULE_TEST_OUTPUT=/tmp/new-module-check` to retain the copy and use its `skills/q-flow/scripts/browser-interactions.mjs` to check `page/`. The copy preserves repository hierarchy and root third-party notices to verify actual build dependencies. The directory must not already exist.
 
 Rebuild `assets/viewer-dist/index.html` after Viewer changes. After installation, check the actual cache and generate acceptance output with the installed version in a new session. Existing standalone HTML embeds old code and must be regenerated.
 
@@ -104,7 +104,7 @@ Rebuild `assets/viewer-dist/index.html` after Viewer changes. After installation
 | Private Viewer package | `codegraph-flow-viewer` | `qgraphflow-viewer` |
 | Default delivery directory | `docs/codegraph-flow/<scope>-<diagram-type>/` | `docs/qgraphflow/<scope>-<diagram-type>/` |
 
-The package keeps only the new skill entry, without old aliases. Its scope remains nine software diagram types. Renaming MapSprig / QMindFlow is outside this migration.
+The package keeps only the new skill entry, without old aliases. Its scope remains eleven presentation diagram types. Renaming MapSprig / QMindFlow is outside this migration.
 
 From the repository root, use the new paths:
 
@@ -129,8 +129,9 @@ Read this section only for Viewer maintenance or interaction audits. Graph autho
 
 - Use the canvas-first React Flow shell: the canvas fills the window and runs under one 52px material toolbar (navigation toggle, view menu for collections, title and subtitle, search with a results popover, a `···` menu with export / reset / layout-lock switch / spacing / appearance, and the Inspector toggle). There is no board header, footer or brand block; the product name appears only in the document title. Graph navigation and the node Inspector are floating panels that slide in from their own edge and start collapsed at every width; clicking a node shows a quick-look card beside it (type, name, responsibility, source anchor, up to four tags, `View details`) instead of opening the Inspector. Let the diagram carry the strongest visual emphasis.
 - The card wash is on by default on every page; the toolbar switch turns it off for the current session only (module washes and the bodies of state tones go plain, frames and chips stay), and no preference is stored. Appearance follows the system `prefers-color-scheme` by default and updates live; the `···` menu offers a `System / Light / Dark` segmented control whose manual choice wins in both directions. Theme changes preserve viewport, search, selection, layout lock, and panel state.
-- Use Radix Colors (MIT) as the shared palette: Slate for cool-neutral surfaces, Iris for core components and interactions, Cyan for data, Red for explicit failures, and eight identity scales (Blue, Orange, Teal, Crimson, Violet, Grass, Plum, Indigo) for `module` names. Every card color is a Radix step or a documented wash of one. Keep copyright and license notices in distributed source, standalone HTML, and SVG; no runtime CDN or component-library dependency is required.
+- Use the fixed botanical palette from `visual-style.js`: Blue, Teal, Lavender, Amber and Sage identify modules; teal marks core components, amber marks data, and red marks failures. Light/dark variants and matching washes keep page and export consistent. Radix Colors (MIT) still supply neutral surfaces, state progression and the eight sequence pair colors. Keep copyright and license notices in distributed source, standalone HTML, and SVG; no runtime CDN or component-library dependency is required.
 - Emphasize an actual business center with `business` or a case-insensitive `core`/`business` tag through a soft Iris 5 ring behind its frame; the frame, chip and wash still belong to its module and the text stays ink. Explicit failures take a Red 11 frame and a Red 5 ring over any module; the chip retains identity. Initial/final symbols keep their notation. Decisions, choices, `alt` and FK references do not imply failure. In a state diagram the states wear a lifecycle tone instead of the module's frame and wash (see State notation). Do not add literal color fields.
+- Component cards (architecture, deployment; `genericCard()`): the icon plate, title and kind tag share the first row, the subtitle and the source anchor (file name and first line) follow in the text column, and the block is centred vertically with 14px above and below; notation in a top-right corner (`cardCorner`) keeps the tag clear. Cards are at most 360 wide and stack tighter than other shapes (`layoutTargets` / `layoutLimits`: 40 between peers with a 32 minimum, layers 48 apart, 24 inside a boundary, 32 between sibling boundaries). `cardTextLayout()` measures it for layout, the quality gate and drawing alike. A view whose stored geometry predates compact cards keeps the classic card (kind row above a full-width title, no source line) until it is laid out again (`compactCards()`), so preserved layouts stay valid and one view never mixes both. A text edit that leaves a card too short for its text grows that card, around its centre, else upward, else downward, whichever the quality gate accepts first, and the boundaries that own it just enough to keep their clearance (`fitCard()`), so the view keeps its card style; what the growth leaves too tight stays for the gate to report.
 - Page, node drawings, MiniMap, Inspector dots, legends, and exports reuse `visual-style.js`. The chip, frame, wash and outgoing lines say whose a node is (module); a ring says it is the business center or a failure; text never follows either. Cards sit on Slate 1, dense ER/class rows on Slate 2; the light canvas is Slate 1 (`#fcfcfd`, near-white), the same step-1 rule as dark mode. Use corresponding dark scales rather than applying light colors unchanged in dark mode.
 - Chrome colors (toolbar, panels, Inspector, canvas controls) are expressed through tokens that `styles.css` derives from the palette variables with `color-mix`: four label levels (`--label`, `--label-2/3/4`), one separator (`--sep`), a three-step fill scale (`--fill`, `--fill-2/3`) and three materials (`--material-thick`, `--material`, `--material-thin`), so dark mode only overrides the material base and shadows. Chrome text uses the 11 / 12 / 13 / 15 / 20 px scale while node SVG typography keeps `TYPOGRAPHY` / `--font-*`; every control has a `:active` press state and the shared `:focus-visible` ring; panels separate with a .5px hairline plus one shadow layer, and `1px solid` stays on canvas glyphs only. Besides `prefers-reduced-motion`, the chrome responds to `prefers-reduced-transparency` (materials become opaque `--panel`, no blur) and `prefers-contrast: more` (separators and secondary text take the label color; floating layers get a 1px outline).
 
@@ -153,7 +154,7 @@ Read this section only for Viewer maintenance or interaction audits. Graph autho
 - `groupAppearanceMap()` gives every boundary the neutral Slate 2 surface with a Slate 5 hairline and steps directly nested boundaries onto Slate 1 (dark Slate 3); there is no colored accent. Fills are opaque to prevent nested accumulation; render parents before children and keep every group below edges/cards. `groupFrameSvg()` shares the same frame across page, minimap and SVG/PNG. Groups do not inherit module/status colors; names and sequence operators retain meaning when slots repeat. Headings and operators use neutral main ink. Verify edge contrast against group fills as well as the canvas.
 - Build the legend from categories and line styles actually present: role swatches for the outlines in view plus one chip-colored entry per module. Use current theme tones. Test diagram text at ≥4.5:1 and meaningful outlines/lines at ≥3:1 against their actual backgrounds, including opacity. Preserve non-color symbols and text for grayscale/color-vision accessibility.
 - Open the reading legend from the `Legend` floating button at the canvas's top-left as a popover that also holds the `Edge animation` switch when directed relationships exist. Keep each original symbol before its label, including its shape, theme colors and solid/dashed line style, as plain inline text that wraps within the popover. The button yields to the right of an open navigation panel; pan/zoom leaves its position and text size unchanged, and Escape or an outside click closes the popover.
-- Directed relationships show one clearly visible moving dash overlay from source to target by default; undirected relationships remain static. Preserve the solid/dashed evidence baseline beneath the overlay. For sequence messages the baseline stays opaque and the 3.2-graph-unit overlay has no glow. Dashed returns / framework / inference messages move the baseline, its same-route `5 5` mask and selection strokes together: the dashes travel from source to target while gaps stay clear at each animation phase. Brightness changes within fixed dash positions are not sufficient. User selection keeps motion running. Switching sequence flow off or reducing motion removes the overlay and stops the baseline's dash phase.
+- With the `Edge animation` switch on (the default), directed relationships show one clearly visible moving dash overlay from source to target; the overlay exists only while it moves, and undirected relationships remain static. Preserve the solid/dashed evidence baseline beneath the overlay. For sequence messages the baseline stays opaque and the 3.2-graph-unit overlay has no glow. Dashed returns / framework / inference messages move the baseline, its same-route `5 5` mask and selection strokes together: the dashes travel from source to target while gaps stay clear at each animation phase. Brightness changes within fixed dash positions are not sufficient. User selection keeps motion running. Switching sequence flow off or reducing motion removes the overlay and stops the baseline's dash phase.
 - Hover and selection emphasis use outlines and shadows without scaling node geometry or replacing semantic fills and borders. User selection adds one shared 760ms outline/glow rebound to the node and its direct incident edges, then retains static emphasis; only stroke width, opacity, and shadow animate.
 - The motion-effects block at the end of `styles.css` supplies clear moving stroke widths without permanent colored glows, tinted node shadows or a colored canvas vignette. All meaningful edge baselines remain opaque. Existing restrained selection feedback remains local; reduced-transparency and high-contrast preferences disable decorative halos without changing notation or baseline contrast.
 - Honor reduced-motion preferences by disabling relationship and selection motion, and applying view changes without animation.
@@ -169,32 +170,32 @@ Read this section only for Viewer maintenance or interaction audits. Graph autho
 - Node clicks and drag start select a node and show its quick look; directory/search and Enter/Space open its Inspector. Selection leaves directed edges flowing. Apply selection feedback and detail positioning once per operation; dragging does not recenter the viewport or move focus away from its target.
 - Clear selection with a canvas click, detail close, or Escape. Search dims non-matching nodes without changing topology.
 - The Inspector retains the selected node and all its facts, fields, nullability, attributes, methods, source anchors and tags until the user changes or clears selection. It never advances automatically or steals focus.
+- A selected relationship shows its translated evidence kind and, when the edge records a `site`, the same `file:lines` path and symbol a node shows for its `source`, in both the relation quick-look card and the Inspector (`anchorText` and `evidenceLabels` in `visual-style.js`).
 - Directed flow must remain visibly distinguishable while its node is selected. Static emphasis must not fill the moving dash gaps with an opaque same-color line. Validate all incident directed edges, not only the first edge or animationPlayState. Reduced motion and the independent flow switch retain priority.
 - Search ignores case and surrounding whitespace. Rank exact names, name prefixes, name substrings, subtitle/tags, then facts/fields/attributes/methods; preserve original order within ties and take eight results after sorting.
 - Layout is locked by default. An explicit control enables dragging; downloads use the current node positions.
-- The `Arrange` action uses bounded D3 nudging after unlocking layout. With a selection it moves that node and its one-hop neighbors; without a selection it moves all nodes. It targets 49px rectangle clearance while staying close to authored positions, keeps contained nodes inside their smallest boundary, and only moves sequence participants horizontally. It is spacing cleanup, not a fresh topology or full automatic layout.
+- The `Arrange` action uses bounded D3 nudging followed by shared route/label refinement after unlocking layout. With a selection it moves that node and its one-hop neighbors; without a selection it moves all nodes. It targets one pixel above the diagram's node gap as rectangle clearance (49px; 33px for component cards, per `layoutLimits`) while staying close to authored positions, keeps contained nodes inside their smallest boundary, and only moves sequence participants horizontally. It is spacing cleanup, not a fresh topology or full automatic layout.
 - Initial canvas budgets are 2400×1600 graph units for architecture / er / deployment / class / usecase / dataflow, 1600×2400 for flowchart / state, and content-adaptive for sequence. These are starting budgets, not minimum borders, export resolutions or aspect-ratio requirements. Preserve full text and type semantics; expand for spacing and routes, keep small graphs compact, and never shrink text or add empty padding to match a ratio. Start with 64 units between peers and 80–96 between layers; expand only the affected label/port corridor. Keep 24 around labels and below measured group headings, with 32 at group sides. Wrap complete long labels instead of spreading every node; sequence messages constrain their own participant span and measured row height. Budgets alone do not rearrange existing geometry.
 - If a boundary cannot fit the preferred header/padding within the 156px movement limit, retain the node's authored position and report remaining layout issues. Unrelated nodes retain their exact coordinates, including fractions. Every operation refreshes the status message and its 4.5s display timer, even when the text repeats.
-- Spacing cleanup never changes graph evidence, edge route hints, groups, selection, viewport, panels, or theme. `Reset` restores authored `graph.json` positions and the reading view, clears search, selection, and old operation messages, and restores the default edge-flow switch. Keep the current theme, panel visibility, and layout lock; announce the completed reset in the existing status region.
+- Spacing cleanup never changes graph evidence, groups, selection, viewport, panels, or theme. Successful movement recomputes route geometry and label positions; saved authored geometry remains exact under `--layout preserve`. `Reset` restores authored `graph.json` positions and the reading view, clears search, selection, and old operation messages, and restores the default edge-flow switch. Keep the current theme, panel visibility, and layout lock; announce the completed reset in the existing status region.
 - Pan, zoom, fit view, reset, SVG download, and PNG download remain available.
-- `Save changes` saves all views' current text and positions in the original single-graph or collection shape, preserving metadata, source anchors, and structured fields. Where the browser offers a directory picker (Chromium, including pages opened from disk), the user picks the page's own folder once and both the sibling `graph.json` and the open page are rewritten in place: the page on disk is re-read and only its embedded `graph-data` element changes, through the same `pageWithGraph()` the generator uses, so reloading shows the edits. Picking a folder that does not contain the page saves nothing and names the page in the status. Otherwise a native file picker or a `graph.json` download preserves the edits for regeneration. Cancellation or write failure preserves edits; reset affects only the current graph and is included in the next save. Browser regression must cover switching away and back, reset isolation, JSON download, and regeneration from that JSON.
+- `Save changes` saves all views' current text and positions, and the sizes a text edit grew, in the original single-graph or collection shape, preserving metadata, source anchors, and structured fields. Where the browser offers a directory picker (Chromium, including pages opened from disk), the user picks the page's own folder once and both the sibling `graph.json` and the open page are rewritten in place: the page on disk is re-read and only its embedded `graph-data` element changes, through the same `pageWithGraph()` the generator uses, so reloading shows the edits. Picking a folder that does not contain the page saves nothing and names the page in the status. Otherwise a native file picker or a `graph.json` download preserves the edits for regeneration. Cancellation or write failure preserves edits; reset affects only the current graph and is included in the next save. Browser regression must cover switching away and back, reset isolation, JSON download, and regeneration from that JSON.
 - Keyboard selection and panel dismissal preserve graph topology; Backspace and Delete do not remove nodes from this Viewer.
-- Desktop opening, resetting, switching views and entering fullscreen fit the whole diagram. Sequence diagrams at ≤700px instead start at zoom .75 around the first core participant (or first participant), with its head below the toolbar. Explicit `Fit canvas` always shows the whole graph at every width. Fit bounds include nodes, groups, routes, labels and ER symbols; exports always use these full bounds.
-- Every overview fit subtracts toolbar and floating-panel chrome using `readingPadding()`; each open desktop side panel occupies 304px + 24px, closed sides reserve 24px. The bottom boundary clears measured visible controls by 12px. Padding uses `px` strings, not numeric ratios. Panels outside fullscreen and full-width mobile panels do not reduce the reading rectangle.
-- Opening navigation or Inspector pans only as needed to reveal the selected node, or sequence participant head/message label, without changing zoom. An already visible or absent selection does not move. Mobile panels do not trigger reveal. Closing panels preserves the current viewport, including user navigation.
-- Directory, search and participant Enter/Space locate ordinary nodes as before. Sequence locate uses `max(currentZoom, .75)` (maximum 2), anchors the visible head near the top of the final reading rectangle, and issues one viewport target. On mobile it prepares the canvas seen after closing the mutually exclusive panel. Clicking or starting a drag does not locate. `occupiedBox()` uses the shared 72px participant / 108px actor head; an actor subtitle adds 22px, without changing the authored lifeline end.
+- Opening, resetting, switching views and entering fullscreen fit the whole diagram while that keeps zoom ≥ `OVERVIEW_ZOOM` (.45, so 16/20px text reads as 7.2/9px or more, like a printed overview). A larger diagram opens at `READABLE_ZOOM` (.75, so 14/16/20px text reads as 10.5/12/15px) on its reading start (`readingStart()`: the first `layout.primaryPath` node, else a `start` / `initial` node, else the business center, else the first node in reading order; a sequence without a path keeps its top-left corner), clamped to the diagram, centred on an axis it does not fill and below the legend button (`readableViewport()`). Explicit `Fit canvas` always shows the whole graph at every width. Fit bounds include nodes, groups, routes, labels and ER symbols; exports always use these full bounds.
+- Every overview fit subtracts toolbar and floating-panel chrome using `readingPadding()`; each open desktop side panel occupies 304px + 24px, closed sides reserve 24px. The bottom boundary clears measured visible controls by 12px. Padding uses `px` strings, not numeric ratios. Fullscreen panels do not reduce the reading rectangle.
+- Opening navigation or Inspector pans only as needed to reveal the selected node, or sequence participant head/message label, without changing zoom. An already visible or absent selection does not move. Closing panels preserves the current viewport, including user navigation.
+- Directory, search and participant Enter/Space locate ordinary nodes as before. Sequence locate uses `max(currentZoom, .75)` (maximum 2), anchors the visible head near the top of the final reading rectangle, and issues one viewport target. Clicking or starting a drag does not locate. `occupiedBox()` uses the shared 72px participant / 108px actor head; an actor subtitle adds 22px, without changing the authored lifeline end.
 - All programmatic viewport moves (fit, locate, reveal) share `cubic-bezier(.32,.72,0,1)` at 320–420ms; panels slide in and out with a CSS transform transition on the same curve (`--base`, 300ms) and unmount when it ends. Reduced motion sets both to zero duration, so panels appear and disappear at their resting position with no painted travel.
 - Zoom and fit scale the complete authored node as one unit. No zoom level hides subtitles, fields, attributes, methods, stereotypes, or other authored node text; fullscreen fit follows the same rule. Centered shape text wraps inside the available rectangle, with narrower areas for diamonds, ellipses, pills and slanted shapes. `layoutText()` never cuts a token (text between spaces) that fits a line, so ordinary text wraps as before; a token wider than the line is cut between CJK characters first, then at an identifier's own separators (`_ . / - = , : ;` and camelCase humps), and only then anywhere, and closing punctuation never starts a line while opening punctuation never ends one (its neighbour travels with it). Shared width estimates reserve space for uppercase identifiers and wide Latin letters. Boundary titles reserve space for fragment notation. The `text-bounds` browser check covers every supported node kind, long fields and members, boundary titles, uppercase edge labels, and all three zoom levels, and fails if any non-empty authored node text has computed opacity zero.
 - Quick look tries right → left → below → above using its actual size. Ordinary graphs retain minimum-overlap fallback. Sequence cards additionally avoid message labels, stroke/arrow bands and branch guards. If no safe candidate fits, hand the same selection to the existing Inspector and pan without shrinking; never place a covering card. Card and Inspector share one editor draft and save validation, including across resize/fallback.
 - Long quick-look content wraps and scrolls. Fullscreen detail handoff exits fullscreen before opening Inspector. A rejected exit preserves selection and reports failure; safe cards stay usable, while unsafe sequence cards remain hidden and the fullscreen exit control provides retry.
-- The legend button and zoom controls move to 328px from the left while the navigation panel is open; the minimap moves to 328px from the right while the Inspector is open (`.workspace.nav-open / .drawer-open`); at 700px and below they stay put.
+- The legend button and zoom controls move to 328px from the left while the navigation panel is open; the minimap moves to 328px from the right while the Inspector is open (`.workspace.nav-open / .drawer-open`).
 - SVG and PNG exports contain the complete diagram rather than only the current viewport.
 
-### Responsive layout
+### Desktop layout
 
 - At every width both floating panels start collapsed and open as 304px overlays (toolbar bottom + 12px to window bottom − 12px) without a backdrop, so the canvas stays pannable beside them. Escape closes an open popover first, then the panel holding focus (returning focus to its toolbar toggle), then the selection. Do not remove evidence access at an intermediate breakpoint.
-- At 700px and below, a panel is the window width minus 24px, opening one closes the other, the minimap is hidden. Selecting a search result opens its details and closes the navigation panel.
-- Keep mobile actions reachable, retain a visible canvas beside an open panel, and prevent horizontal page overflow at 390px. The Inspector still shows complete text and scrolls vertically.
+- Retain the desktop toolbar, panels and minimap at every width; no mobile layout or panel mode is maintained. The Inspector shows complete text and scrolls vertically.
 
 ### Evidence display
 
@@ -204,9 +205,15 @@ Read this section only for Viewer maintenance or interaction audits. Graph autho
 - The detail drawer says `Evidence` rather than claiming every anchor is source code.
 - Facts, subtitles, fields, methods, source symbols, and tags wrap long tokens within the Inspector. Preserve complete text and allow only vertical scrolling.
 
+### Key points
+
+- `meta.notes` shows as a card over the top of the right side: open by default, closable to a `Key points · N` button in the same place. It is not drawn while the details drawer is mounted (including its slide-out). Fullscreen has no panels, so there it floats over the canvas without reserving space until hidden. Hiding or showing hands keyboard focus to the control that replaces the one used.
+- While the card shows, the reading area gives up the right edge as for the drawer: `ViewerShell` sets `data-drawer-open` on the canvas from `drawerOpen || notesShown`, and `readingRect`, `readableViewport`, quick-look placement and reveal all read that attribute, so the opening view, Fit canvas and locate never place the diagram under the card.
+- A graph without notes has no card, no button and no reserved edge. The SVG block (`createDiagramSvg`, heading `Key points`, bullets in the `body` class) sits under the board; the board, offsets and every other element stay as they were. Run `QA_EXTRAS=notes` after changing either.
+
 ### Browser acceptance
 
-- Run the full browser matrix only when Viewer source, edge routing, graph schema, or validation behavior changed. Cover all nine diagram types at 1440×900, 1920×1080, and 390×844 in light and dark themes; check default directed flow, absence of playback controls, stable manual selection with still-moving edges, the independent flow switch, dynamic semantic legends, pan/zoom, ranked search, linked node/edge emphasis without geometry changes or duplicate pulses, complete Inspector wrapping, layout lock and spacing-result feedback, reset, SVG/PNG download without transient effects, keyboard use, reduced motion, and horizontal overflow. Check each type's own notation and core emphasis. Standalone pages have no diagram-type menu; requested collections use a vertical view menu. At 700px and below both panels start collapsed, remain accessible, and open mutually exclusively.
+- Run the full browser matrix only when Viewer source, edge routing, graph schema, or validation behavior changed. Cover all eleven templates at 1440×900, 1920×1080 and 768×1024 in light and dark themes; check default directed flow, absence of playback controls, stable manual selection with still-moving edges, the independent flow switch, dynamic semantic legends, pan/zoom, ranked search, linked node/edge emphasis without geometry changes or duplicate pulses, complete Inspector wrapping, layout lock and spacing-result feedback, reset, SVG/PNG download without transient effects, keyboard use, reduced motion, and horizontal overflow. Check each type's own notation and core emphasis. Standalone pages have no diagram-type menu; requested collections use a vertical view menu. Both desktop panels can remain open together.
 - Open downloaded images to check complete labels, notation, uncropped boundaries, and theme parity. Reuse installed browser tooling and close temporary HTTP servers in `finally`.
 
 ### Sequence rendering and interaction
@@ -229,7 +236,7 @@ State colors come from the lifecycle, not from the module (one machine is one mo
 
 Nodes, routes, arrows and stroke widths scale together. Sequence screen dash periods have a 6 CSS px minimum to avoid low-DPI aliasing; baseline, mask and phase share this adjustment. Static SVG/PNG exports retain graph-unit notation. Sequence motion uses a 3.2-unit stroke over a 1.6-unit baseline; other directed edges use 2.8 units. Both the main rules and the motion-effects block at the end of `styles.css` participate. The graph collection owns the user's flow choice so switching diagrams preserves it. Keep live reduced-motion behavior. Sync uses a solid baseline independently of evidence; non-sequence notation and undirected kinds remain unchanged. Default include/extend labels sit beside their path so short use-case relationships remain visible; explicit label positions still win.
 
-Run `node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs`, build the Viewer, generate the sample and use `QA_ONLY_EXTRAS=1 QA_EXTRAS=motion-matrix node skills/q-flow/scripts/browser-interactions.mjs GENERATED REPORT` for actual screenshot profiles and video. Nine types × two themes × three viewports give 54 cases. Check default and selected overview plus readable local paths for every actual line kind, opposite directions and self messages. ER is a static control. A CSS clock or structure validation does not prove perceptible movement. Preserve historical media recording hashes; write a new report.
+Run `node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs`, build the Viewer, generate the sample and use `QA_ONLY_EXTRAS=1 QA_EXTRAS=motion-matrix node skills/q-flow/scripts/browser-interactions.mjs GENERATED REPORT` for actual screenshot profiles and video. Eleven views × two themes × three viewports give 66 cases. Check default and selected overview plus readable local paths for every actual line kind, opposite directions and self messages. ER is a static control. A CSS clock or structure validation does not prove perceptible movement. Preserve historical media recording hashes; write a new report.
 
 Use `QA_EXTRAS=motion-preferences` for user flow choice, live reduced motion, diagram switching, high contrast and reduced transparency. `QA_TYPES` and `QA_WIDTHS` narrow matrix retries. Frame sampling excludes labels, overlaid edges and bends; correlate the changing ink across 0/70/140 ms and retain the actual images for review.
 
@@ -237,15 +244,15 @@ Use `QA_EXTRAS=motion-preferences` for user flow choice, live reduced motion, di
 
 Initial canvas budgets are 2400×1600 graph units for architecture / er / deployment / class / usecase / dataflow, 1600×2400 for flowchart / state, and content-adaptive for sequence. These are starting budgets, not minimum borders, export resolutions or aspect-ratio requirements. Preserve full text and type semantics; expand for spacing and routes, keep small graphs compact, and never shrink text or add empty padding to match a ratio. Start with 64 units between peers and 80–96 between layers; expand only the affected label/port corridor. Keep 24 around labels and below measured group headings, with 32 at group sides. Wrap complete long labels instead of spreading every node; sequence messages constrain their own participant span and measured row height. Budgets alone do not rearrange existing geometry.
 
-Generation and validation share `layoutComposition.canvasBudget`. Sequence reports `canvasBudget`, `targetRatio`, `fit`, `aspectBand` and `withinBand` as null. `aspectBand` is 1.6, `bandSlack` is 1.1 and `withinBand` says whether the width/height ratio sits within that slack of the band 1/1.6–1.6; a small graph may legitimately sit outside, so the report stays informational and never triggers an aspect-ratio warning. Actual content bounds still control fit and SVG/PNG dimensions; reporting the budget does not perform automatic layout or certify readability.
+Generation and validation share `layoutComposition.canvasBudget`. Sequence reports `canvasBudget`, `targetRatio`, `fit`, `aspectBand` and `withinBand` as null. `aspectBand` is 1.6, `bandSlack` is 1.1 and `withinBand` says whether the width/height ratio sits within that slack of the band 1/1.6–1.6; a small graph may legitimately sit outside, so the report stays informational and never triggers an aspect-ratio warning. Actual content bounds still control fit and SVG/PNG dimensions; reporting the budget does not perform automatic layout or certify readability. Readability is judged separately by `view.oversized` (`overviewWarnings()`): generation prints it when a view needs more than 4 reading rectangles at zoom .75.
 
 Nodes, routes, arrows and stroke widths scale together. Sequence screen dash periods have a 6 CSS px minimum to avoid low-DPI aliasing; baseline, mask and phase share this adjustment. Static SVG/PNG exports retain graph-unit notation.
 
 - Automation handle: a page opened with `?automation=1` exposes `window.__qgraphflowAutomation = { getViewport, setViewport, setCenter, ease }` (the React Flow viewport API plus the shared easing) for recording and QA drivers. Ordinary pages expose nothing; it never changes rendering.
 
-## adaptive-v2
+## adaptive-v3
 
-`adaptive-v2`: generation defaults to `--layout auto` and accepts semantic inputs without positions or sizes. Declare real ownership with node `groupId` and group `parentId`; color `module` is not ownership. Optional node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing order only. `--layout preserve` checks existing geometry without rearranging it. Ambiguous old containment requires an explicit author decision. `--input-only` checks semantics; source, geometry and browser rendering have separate statuses. `--force` only permits replacing outputs and never bypasses quality checks. A layered result whose width/height ratio leaves the accepted band 1/1.6–1.6 by more than 10% is folded (2–5 segments): a top-down layout that is too tall cuts its layer sequence into columns with aligned tops, a left-to-right layout that is too wide cuts it into rows with aligned starts, so every segment keeps its reading direction and continues at the start of the next one. Geometry and routes inside a segment are kept; cuts prefer boundary changes and avoid a decision's branches; an edge across a cut runs through the channel between its segments, or through the corridor before or after them when a neighbour or heading is in the way. A boundary spread over several segments is rebuilt around its members and must not cover foreign nodes. The fewest segments that pass the quality gate within 10% of the band win, so a balanced fold is not passed over for a ragged one; a fold the gate rejects is skipped for the next one, and otherwise the nearest valid shape competes with the unfolded result. The type budget only breaks ties towards its preferred orientation. Declared `layout.rank` layouts and state charts with branches or loops never fold.
+`adaptive-v3`: generation defaults to `--layout auto` and accepts semantic inputs without positions or sizes. Declare real ownership with node `groupId` and group `parentId`; color `module` is not ownership. Optional node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing order only. `--layout preserve` checks existing geometry without rearranging it. Ambiguous old containment requires an explicit author decision. `--input-only` checks semantics; source, geometry and browser rendering have separate statuses. `--force` only permits replacing outputs and never bypasses quality checks. A layered result whose width/height ratio leaves the accepted band 1/1.6–1.6 by more than 10% is folded (2–5 segments): a top-down layout that is too tall cuts its layer sequence into columns with aligned tops, a left-to-right layout that is too wide cuts it into rows with aligned starts, so every segment keeps its reading direction and continues at the start of the next one. Geometry and routes inside a segment are kept; cuts prefer boundary changes and avoid a decision's branches; an edge across a cut runs through the channel between its segments, or through the corridor before or after them when a neighbour or heading is in the way. A boundary spread over several segments is rebuilt around its members and must not cover foreign nodes. The fewest segments that pass the quality gate within 10% of the band win, so a balanced fold is not passed over for a ragged one; a fold the gate rejects is skipped for the next one, and otherwise the nearest valid shape competes with the unfolded result. The type budget only breaks ties towards its preferred orientation. Declared `layout.rank` layouts and state charts with branches or loops never fold. Architecture views are laid out both top-down and left-to-right; after crossings, the direction whose whole view fits one 1392×688 screen at the larger zoom wins, and the compiler records it in `layout.direction` (`down` / `right`), which a later compilation keeps.
 
 Edge labels sit on their own line (ELK places them inline; the shared router centres them on the clearest segment), except sequence messages, which stay above the arrow. Keep full text at 20/16/14px. Minimum clearances: nodes 48px; labels to nodes/labels 24px; labels to unrelated edges 6px; below measured group heading 24px, other insets 32px; sibling groups 48px; parallel channels 24px; straight endpoint segments 12px, ER 28px. Readable point crossings, including nonplanar graphs, are allowed. Prefer fewer repeated crossings between the same pair and reject long collinear overlaps. Layout generation also removes crossings that a different order would avoid: while a candidate still crosses, a bounded search (`REFINE_*` in `compile-layout.mjs`) swaps the ports of the crossing relations within a node side, the side a decision branch or actor relation leaves on, sibling node order and fold lanes, and keeps a swap only when the candidate scores better, so only the crossings a topology forces remain (a full 3×3 mesh keeps 9). Authors never need to reorder edges or add hints for this. Canvas ratios are informational; never remove relationships or shrink text to pass. Ordering rules (main path, class hierarchy, state endpoints) accept a successor that continues at the top of the next column.
 
@@ -256,3 +263,9 @@ node scripts/validate-graph.mjs graph.json --input-only
 node scripts/generate-viewer.mjs graph.json output-directory --layout auto
 node scripts/validate-graph.mjs output-directory/graph.json
 ```
+
+## Shared compact layout and routing
+
+See [layout-routing.md](layout-routing.md) when maintaining layout, movement, editing or exports. This applies to all eleven templates over nine compatible semantic types; generation and the Viewer use the same source.
+
+The eleven-template catalog is in `view-identity.js`; measured composition strategies are in `layout-templates.js`. The type selector lives at the toolbar right. Template order constraints also apply to local Arrange operations.

package/skills/q-flow/references/visual-contract.md

@@ -5,25 +5,25 @@ Composition and colour contract for Viewer development and audits. The authoring
 - Initial canvas budgets are 2400×1600 graph units for architecture / er / deployment / class / usecase / dataflow, 1600×2400 for flowchart / state, and content-adaptive for sequence. These are starting budgets, not minimum borders, export resolutions or aspect-ratio requirements. Preserve full text and type semantics; expand for spacing and routes, keep small graphs compact, and never shrink text or add empty padding to match a ratio. Start with 64 units between peers and 80–96 between layers; expand only the affected label/port corridor. Keep 24 around labels and below measured group headings, with 32 at group sides. Wrap complete long labels instead of spreading every node; sequence messages constrain their own participant span and measured row height. Budgets alone do not rearrange existing geometry.
 - Edge labels sit on their own line in every type except sequence: centred on the segment with the most clearance from both endpoints, backed by the canvas colour so the line reads as interrupted by its label. Sequence messages keep their names above the arrow.
 - Keep full text at 20/16/14px. Minimum clearances: nodes 48px; labels to nodes/labels 24px; labels to unrelated edges 6px; below measured group heading 24px, other insets 32px; sibling groups 48px; parallel channels 24px; straight endpoint segments 12px, ER 28px. Readable point crossings, including nonplanar graphs, are allowed. Prefer fewer repeated crossings between the same pair and reject long collinear overlaps. Layout generation also removes crossings that a different order would avoid: while a candidate still crosses, a bounded search (`REFINE_*` in `compile-layout.mjs`) swaps the ports of the crossing relations within a node side, the side a decision branch or actor relation leaves on, sibling node order and fold lanes, and keeps a swap only when the candidate scores better, so only the crossings a topology forces remain (a full 3×3 mesh keeps 9). Authors never need to reorder edges or add hints for this. Canvas ratios are informational; never remove relationships or shrink text to pass.
-- `adaptive-v2`: generation defaults to `--layout auto` and accepts semantic inputs without positions or sizes. Declare real ownership with node `groupId` and group `parentId`; color `module` is not ownership. Optional node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing order only. `--layout preserve` checks existing geometry without rearranging it. Ambiguous old containment requires an explicit author decision. `--input-only` checks semantics; source, geometry and browser rendering have separate statuses. `--force` only permits replacing outputs and never bypasses quality checks. A layered shape more than 10% outside the accepted width/height band 1/1.6–1.6 is folded by cutting its layer sequence: top-down layouts into columns when too tall, left-to-right layouts into rows when too wide, each segment keeping its reading direction and continuing at the start of the next (never with declared ranks, nor for state charts with branches or loops). The fewest segments that pass the gate within 10% of the band win; folds that would cover foreign nodes or fail the gate are dropped for the next.
+- `adaptive-v3`: generation defaults to `--layout auto` and accepts semantic inputs without positions or sizes. Declare real ownership with node `groupId` and group `parentId`; color `module` is not ownership. Optional node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing order only. `--layout preserve` checks existing geometry without rearranging it. Ambiguous old containment requires an explicit author decision. `--input-only` checks semantics; source, geometry and browser rendering have separate statuses. `--force` only permits replacing outputs and never bypasses quality checks. A layered shape more than 10% outside the accepted width/height band 1/1.6–1.6 is folded by cutting its layer sequence: top-down layouts into columns when too tall, left-to-right layouts into rows when too wide, each segment keeping its reading direction and continuing at the start of the next (never with declared ranks, nor for state charts with branches or loops). Architecture views are laid out both top-down and left-to-right; after crossings, the direction whose whole view fits one 1392×688 screen at the larger zoom wins, and the compiler records it in `layout.direction` (`down` / `right`), which a later compilation keeps. The fewest segments that pass the gate within 10% of the band win; folds that would cover foreign nodes or fail the gate are dropped for the next.
 - Make the requested question answerable from the first reading view. Use one clear path, real component/responsibility names, and action/message/data names on edges. Keep boundaries behind nodes and labels clear of group headings.
 - Emphasize the actual business center through a valid `business` kind or `core`/`business` tag. The Viewer supplies cool-neutral Slate surfaces, Iris core/interaction, Cyan data, and Red explicit failures. Cards stay near-white; identity and emphasis live on the frame, the icon chip and a soft ring, never in the text. Do not add color fields or invent a `core` kind.
 - Color supplements labels and notation. A collection may reuse a non-empty `module` name across views so the Viewer can give its cards one identity: a saturated icon chip with a white glyph, a matching 1.5px frame, a faint wash, and the color of every relationship that leaves the card. The business center adds a soft Iris ring behind its frame; an explicit failure keeps a Red frame and ring over any module; data keeps its glyph and a Cyan frame only when it has no module. Module color never replaces node shapes, labels, relationship symbols or evidence styles, and authors never provide literal colors. Framework/inference edges retain dashed evidence styling unless a diagram's notation determines its line style. Preserve exact protocols, multiplicities, guards, and source anchors.
 - Size individual boxes and corridors for complete text; uniformly enlarging the layout cancels readability gains when fitted. Follow the dimensions, automatic lanes, endpoint clearances, and route-hint rules in [graph-schema.md](graph-schema.md#routing-and-spacing). Move nodes before adding route hints; no route may enter a node interior.
-- On desktop, the Viewer fits the whole diagram on opening, reset, view switching and fullscreen entry. Mobile sequence diagrams (≤700px) start with a readable local view at zoom ≥.75; explicit fit always shows the whole drawing. Scale each complete authored node without hiding fields, members, subtitles or other text at lower zoom. Zoom, pan and the minimap reach detail. SVG/PNG exports cover the full diagram; graph data must retain complete content.
+- The Viewer fits the whole diagram on opening, reset, view switching and fullscreen entry while that keeps zoom ≥.45 (20/16px text at 9/7.2px or more); a larger diagram opens at .75 on the start of its reading flow (its primary path or start node, else its business center, else its first node). Explicit fit always shows the whole drawing. Scale each complete authored node without hiding fields, members, subtitles or other text at lower zoom. Zoom, pan and the minimap reach detail. SVG/PNG exports cover the full diagram; graph data must retain complete content.
 - Author from the requested domain's own evidence. Preview models, facts, and source paths are examples only.
 
-## Color rules for all nine types
+## Color rules for all eleven templates
 
-- Boundaries are containers, not information: large system, deployment and sequence boundaries use one neutral Slate surface with a 1px hairline, no colored accent, and directly nested boundaries step one surface apart. Nested fills do not accumulate; labels and `alt`/`opt`/`loop`/`par` remain the source of meaning. Ordinary cards keep a faint (5%, dark 9%) wash of their chip color; ER/class headers take a 10% (dark 16%) wash while dense field/member rows stay neutral. Do not recolor nodes merely because they connect: shared module identity and call/return pairs must remain consistent.
-- Reuse the exact `module` name for the same evidenced domain across views. Its name selects a stable theme slot, independent of view order or unrelated module additions/removals. The eight identity scales (Blue, Orange, Teal, Crimson, Violet, Grass, Plum, Indigo) use Radix step 9 for chips and washes and step 10 for frames and lines, sit clear of the Cyan / Red role strokes and can repeat; names, shapes and line notation remain mandatory. Aim for 4–6 meaningful categories in one reading region rather than inventing a module for every node. This is authoring guidance, not a node or palette limit.
+- Boundaries are containers, not information: large system, deployment and sequence boundaries use one neutral Slate surface with a 1px hairline (dashed for a `security` trust boundary), no colored accent, and directly nested boundaries step one surface apart. Nested fills do not accumulate; labels and `alt`/`opt`/`loop`/`par` remain the source of meaning. Ordinary cards keep a faint (5%, dark 9%) wash of their chip color; ER/class headers take a 10% (dark 16%) wash while dense field/member rows stay neutral. Do not recolor nodes merely because they connect: shared module identity and call/return pairs must remain consistent.
+- Reuse the exact `module` name for the same evidenced domain across views. Its name selects a stable theme slot, independent of view order or unrelated module additions/removals. The fixed palette uses Blue, Teal, Lavender, Amber and Sage for module identity, with theme-specific text contrast and faint matching washes. Core accents use teal, data uses amber and failures retain red; names, shapes and notation remain mandatory. Sequence call/reply pairs retain eight distinct notation colors. Aim for 4–6 meaningful categories in one reading region rather than inventing a module for every node. This is authoring guidance, not a node or palette limit.
 - Keep identity, explicit failure and interaction separate. A failure frame/edge wins over module color; its chip may still identify ownership. Ordinary relationships wear the color of the card they leave; sequence call/return pairs keep their shared pair color and executions. Selection adds a temporary outline without changing semantic color. Decision diamonds, `alt`, FK references, negative guards and terminal states are not automatically failures or successes.
 - Use discrete colors for categories. Do not imply magnitude, security levels, trust zones or data classifications with a gradient unless the source and schema explicitly model that meaning. Do not add literal color fields.
 - Use theme-specific tones and shared page/export styling. Normal diagram text must reach 4.5:1 and meaningful strokes 3:1 against their actual rendered surface; opacity matters. Keep group fills distinct from card fills and retain at least 3:1 edge contrast on them; saturated large-area fills and permanent colored glows are excluded. Nine region tones may repeat in larger diagrams; labels retain meaning. Color never substitutes for readable names, PK/FK, multiplicities, guards, dash patterns, arrow shapes or call IDs; inspect grayscale readability as well.
 
 | Type | Color emphasis |
 | --- | --- |
-| Architecture | Near-white cards with a module chip, frame and faint wash; relationships wear the source card's color; the business center adds a soft Iris ring, text stays ink. |
+| Architecture | Near-white compact cards with a module chip, frame and faint wash: icon plate, title and kind tag on the first row, then the subtitle and the source anchor (file name and first line); relationships wear the source card's color; the business center adds a soft Iris ring, text stays ink. |
 | Flowchart | Pale module/semantic process and decision fills; explicit failure paths only use the failure accent. |
 | Sequence | Same color and C number for each call/return pair and its execution; neutral hairline fragments, nested one surface apart, operators and guards as the only distinction. |
 | ER | Module-washed headers inside a module frame, neutral field rows, readable PK/FK/UK text; FK is a reference, not a warning. |
@@ -52,3 +52,9 @@ Read the row for the selected type; its legal kinds and required fields are in t
 For a requested collection, author every view from the same verified domain vocabulary, use the canonical nine-type order, and validate the whole collection before generation. A failure in one view blocks delivery of the collection.
 
 Nodes, routes, arrows and stroke widths scale together. Sequence screen dash periods have a 6 CSS px minimum to avoid low-DPI aliasing; baseline, mask and phase share this adjustment. Static SVG/PNG exports retain graph-unit notation.
+
+## Dedicated layout templates
+
+The generator measures complete content before choosing positions. Eleven presentation templates share the same routing, geometry checks, browser editing and exports. Platform capabilities use section matrices; engineering uses layers with parallel support; component relations cluster related components within real ownership; flowcharts use a main spine and side branches; sequence uses participant spans and event rows; ER uses related-entity matrices; deployment uses runtime tiers inside actual boundaries; class uses contract hierarchies; state uses lifecycle branches; use cases place actors outside the system; data flow separates processing and storage.
+
+Template placement never creates ownership, relationships or evidence. Authored ranks and direction remain authoritative. Dense inputs keep a quality-valid layered candidate when templates add crossings, worsen the aspect band, fail validation or cost more than 25% extra in normalized area/routing; `--verbose` reports the template, attempts and fallback. No supported facts are removed. Small layouts use their content bounds rather than a fixed canvas. The fixed botanical palette supports light/dark themes and stable module colors across views; it introduces no authored color field.