feat(graph): color-coded flows and compact nodes #325

Umbrella issue for the graph readability milestone. Wide graphs should let a reader tell flows apart at a glance, as in the Machinations reference screens. Two changes go together: a user-chosen accent colour on nodes and edges, and denser nodes that keep every piece of information and every control.

Each pull request writes "Part of" this issue. The issue stays open until the last pull request is verified in production. Sub-issues are not opened; this checklist tracks the work.

Design rules

• Colour never replaces the node kind. Source, Pool, Gate, Converter, Drain and End keep their shapes and marks, and kind, selection, error and run state stay distinguishable with no colour at all.
• No automatic flow inference. The user colours the nodes and edges they select, and a multi-selection takes one colour at once. Colouring a whole connected path automatically is out of scope.
• An uncoloured graph looks as it does today. The node body stays neutral; an accent colour is limited to a thin outline, the kind mark, and the edge path, arrow and label.
• Product state signals win over a user colour: selection, keyboard focus, errors and warnings, run, arrival and evaluation states, connectable and not connectable, and Focus mode emphasis and dimming. Weight, dashes, outlines, icons and motion are kept, not only colour.
• A flow colour is a decorative grouping aid. Every node keeps its silhouette and its neutral structure line; the colour is a separate band inside that line, so even a colour with no contrast never erases a node's edge.
• Colour choice: five palette swatches (Slate, Sage, Gold, Violet, Rose) and Default, the recently used colours and the colours already used in the document, a hex field, and the browser's own colour input. No built-in colour grid, no transparency.
• The stored colour is drawn unchanged in the light and the dark theme. A colour that is hard to see where it is drawn (edges and the low-zoom dot against the canvas; a node's band and chip against the node face and the canvas around it), or that is close to a state colour, gets a notice; it is still applied. The palette colours never get one.
• Selection, focus, errors and warnings, run cues and Focus-mode dimming keep their own channels and are never overridden by a flow colour. The node selection ring moves outside the silhouette, as the visual-language contract already specifies, and a selected edge gets an underlay instead of a recolour; this applies to existing files too.
• Under forced colours no flow colour is drawn.

Data rules

• Nodes and edges get an optional data.accent, stored as upper-case #RRGGBB; the field is omitted when no colour is set. Input accepts #rgb, #rrggbb, with or without #, in any case; alpha, colour names and anything else are not applied. An invalid value in a file drops that field only and keeps the node or edge.
• Existing files open as they are, with no migration. A colour change does not reset the run and does not mark a Monte-Carlo result stale. accent is outside the engine and structure digest and inside the full revision digest (loop-revision/9).
• Recent colours: at most 8, a per-browser preference, memory only in a temporary session, removed by Reset all data.
• Boundaries to cover: save and reopen, autosave, undo and redo, module insert, templates, the portable file and the installed app, export and import, share links, revision files, an invalid colour value, and files from earlier versions.
• Copy and paste: the product has no copy and paste of nodes or edges today, so it is not part of this milestone.

Slices

• Slice 0: baseline and contract. Before-screenshots on the latest main (a three-node graph, the Coffee, Gacha and MMO templates; light and dark; 100 %, a middle zoom and the low-zoom levels of detail), node size and spacing measurements per kind, the visual priority of selection, focus, error and run states, the list of storage boundaries a colour must cross, a design contract, a data model proposal and a pull request split. No code changes. Done on main 72c7f1a in Chrome: the contract is settled and lands with PR 1 as docs/flow-colour-and-compact-nodes.md; the screenshots stay outside the repository.
• Slice 1: accent colour data on nodes and edges, through every boundary above. Done in feat(graph): flow colours on nodes and edges, and a selection that stays clear on any colour (v0.19.0) #326 (v0.19.0). Covered by colour-specific tests: save and reopen, autosave, undo and redo, module insert, Graph JSON export and import, share links, revision files (loop-revision/9), an invalid value, and an earlier version's reading of a coloured file (measured on v0.18.2). Coverage notes: the portable file and the installed app use the same file reader and passed their existing suites, without a colour-specific test; template colours are Slice 5 work.
• Slice 2: a colour section in the Inspector with the palette, Default, recent and in-document colours, a hex field and the browser's colour input, applied to every selected element as one undo step, the notices, a mixed state for a mixed selection, and full keyboard use. Phone editing follows the existing product contract. Done in feat(graph): flow colours on nodes and edges, and a selection that stays clear on any colour (v0.19.0) #326 (v0.19.0): read-only on the phone and on a locked canvas.
• Slice 3: the same accent on the minimap mark and on a coloured Pool or Register in the timeline; edge colours are not passed to the timeline, the Register dashed line and the Pool solid line stay, and CSV and simulation data are unaffected. Done in feat(graph): flow colours in the minimap, the timeline and three templates, each colour offered once (v0.20.0) #327 (v0.20.0): the minimap mark and the line, legend mark and endpoint of a coloured Pool or Register series; every other mark and series keeps its colour; no flow colour under forced colours; the run CSV byte-identical with and without colours.
• Slice 4: compact nodes. A typical one-line node about 10 to 15 % denser (the exact figure after Slice 0), long titles in any language still grow, the real click, drag and port hit areas do not shrink, and no saved coordinate moves. Done in feat(graph): compact nodes, so more of a large graph fits in view (v0.21.0) #328 (v0.21.0), measured on all 386 nodes of a sample of every kind and the three templates (MMO also in German and Korean): a typical one-line node goes from 64 to 56 px tall, 12.5 % shorter, so about 14.3 % more of them fit in the same height; a one-line Pool goes from 64 to 58 px, about 9.4 % shorter and 10.3 % denser; standard side padding is 12 px instead of 16; Source and Drain use 22 px at their pointed end (was 26), Gate uses 26 px (was 30), and End keeps its 24 px right padding. Of the 386 nodes, 235 got shorter (about 60.9 %), 151 kept their height and none got taller. Long titles and content (two-line titles, capacity rows, every Parameter and Register) still grow as needed; saved coordinates and the real port, click and drag areas are unchanged (the ports keep their 18 px hit area).
• Slice 5: restrained colour in the templates (Gacha, Coffee, MMO), about three accents per screen, with unchanged simulation results. Done in feat(graph): flow colours in the minimap, the timeline and three templates, each colour offered once (v0.20.0) #327 (v0.20.0): three colours each, as data in the shipped files (Coffee: Sage green beans, Gold roasted beans, Rose desserts; Gacha: each zone its frame colour; MMO: Sage items and loot, Gold gold, Violet experience and level); Parameters and Registers uncoloured; each template’s engine digest unchanged.

Pull requests

• PR 1: data model, save and restore, undo and redo, the Inspector colour controls, base node and edge rendering, the design contract document, automated tests. feat(graph): flow colours on nodes and edges, and a selection that stays clear on any colour (v0.19.0) #326, merged as 5e3ee18 (v0.19.0, 2026-10-06); PR and main CI green, production checked.
• PR 2: minimap, timeline, restrained template colours, visual regression tests. feat(graph): flow colours in the minimap, the timeline and three templates, each colour offered once (v0.20.0) #327, merged as 36937f5 (v0.20.0, 2026-10-07); PR and main CI green, production checked.
  • Recommended after PR 1: on the phone, the read-only Colour section shrinks to one summary line (a colour dot with its name or hex) instead of the disabled editor. Done in feat(graph): flow colours in the minimap, the timeline and three templates, each colour offered once (v0.20.0) #327.
  • Recommended after PR 1: a colour already shown in an earlier row (Palette, then Recent, then In this document) is not repeated in a later row, so the current colour's ring appears once. Done in feat(graph): flow colours in the minimap, the timeline and three templates, each colour offered once (v0.20.0) #327.
• PR 3: compact nodes and level-of-detail tuning, visible size separated from hit area, multilingual and large-graph checks, before and after screenshots. feat(graph): compact nodes, so more of a large graph fits in view (v0.21.0) #328, merged as 6de1852 (v0.21.0, 2026-10-07); PR and main CI green, production checked. Compact nodes completed. LOD thresholds were not tuned; existing LOD behaviour was regression-checked against the compact geometry.

Each pull request can be reverted on its own.

Out of scope

Automatic path or branch colouring, transparency, gradients, per-edge animation colours, automatic layout or repositioning, changes to simulation meaning, timeline curve interpolation, and new manual screen-reader checks.

Done when

• A user can select nodes and edges and group them under one accent colour.
• The colour survives save, restore, undo, redo and import.
• Existing files look and behave as before.
• Selection, focus, warning and run signals stay clearer than any user colour.
• Representative graphs read denser and faster on the same screen.
• Automated checks pass for light, dark, forced colours, multiple languages, phone and large graphs.
• Each pull request's CI and the post-merge main and production checks pass.