@@ -14,15 +14,14 @@ The v4 rewrite: a columnar model and a WebGPU renderer, per
1414- ** Rewrite when a round closes** — by re-reading the record and restating it,
1515 never by appending.
1616- ** Point form only.** Short points, high level, readable in five minutes.
17- - ** Week by week, and headline changes only.** Each week is a list of what
18- changed and ** what it buys** — the benefit, not the implementation. A change
19- earns a line only if it changed what the library * is* or what it can do; most
20- do not.
17+ - ** Day by day, headline changes only.** Each day is a list of what changed and
18+ ** what it buys** — the benefit, not the implementation. A change earns a line
19+ only if it changed what the library * is* or what it can do; most do not.
2120- ** No round narrative.** Rounds, file names, sub-round numbering and
2221 implementation detail belong in ` PLAN.md ` . Round numbers appear here only
2322 where one is the sole handle on an open question.
24- - ** Restate, don't append.** Later rounds routinely change what an earlier
25- decision meant, so earlier weeks need correcting too.
23+ - ** Restate, don't append.** Later work routinely changes what an earlier
24+ decision meant, so earlier days need correcting too.
2625- ** Facts, not judgement.** The numbers table below stays current; assessments
2726 of how close a release is, what is "left", or whether the work is on track do
2827 not belong here — they need information this file does not carry.
@@ -49,74 +48,110 @@ The v4 rewrite: a columnar model and a WebGPU renderer, per
4948
5049---
5150
52- ## Week 1 — 22–24 July
53-
54- - ** A columnar, CPU-canonical model** — typed-array columns, stable slots,
55- coalesced dirty spans, a CSR adjacency index. Buys the whole performance
56- case: the graph is already in the shape the GPU wants.
57- - ** Reads stay synchronous.** Buys a public API that did not have to become
58- async to get the model.
59- - ** A WebGPU renderer** — SDF shapes, compute culling, indirect draws, GPU
60- picking, GPU text. Buys interaction on graphs that stall v3: ** 33 ms frames
61- where v3 takes 4,460** .
62- - ** A co-signed model↔renderer contract in one file.** Buys a layout change
63- that cannot happen by accident on one side only.
64- - ** Structured queries instead of a selector language.** Buys queries that are
65- data — composable, inspectable, no parser.
66- - ** A serializable mapper DSL for style.** Buys paint channels evaluated on the
67- GPU, and style that can cross a wire.
68-
69- ## Week 2 — 27 July – 2 August
70-
71- - ** Visible-behaviour parity with v3** — curves, compounds, labels, images,
72- animation. Buys an existing app the same picture.
73- - ** Goldens * plus* live v3-vs-v4 parity diffs.** Buys the answer to * is it
74- right* , which a golden alone cannot give: goldens compare v4 against its own
75- past.
76- - ** Benchmarks with an HTML report.** Buys claims that are numbers.
77- - ** Design sittings, decisions recorded when taken.** Buys a migration guide
78- that could later be compiled rather than reconstructed.
79-
80- ## Week 3 — 3–8 August
81-
82- - ** Error and documentation contracts gated at zero tolerance.** Buys a guard
83- no test has ever fired failing the build, and a public member without docs
84- failing it too.
85- - ** The repository split: v4 is the package, v3 lives whole in ` v3/ ` .** Buys a
86- v4 that ships alone, and a real v3 to keep measuring parity against.
87- - ** Packaging gate, migration guide, soak tier, status site.** Buys release
88- mechanics that are testable before there is a release.
89- - ** CI made honest.** Buys a green run that means something: every defect found
90- was in something never executed on a fresh checkout, on a runner, or in a
91- browser nobody could launch locally.
92-
93- ## Week 4 — 9–11 August
94-
95- - ** Both long-standing API decisions taken, each by declining the surface its
96- own homework had priced.** Buys a smaller library and a recorded reason.
97- - ** The force layout rebuilt on published methods.** Buys a layout that stays
98- numerically stable past node degree ~ 20, and lays out the 465k-edge network
99- live in ** 1.3 s** .
100- - ** The nine expensive whole-graph algorithms went async with GPU executors.**
101- Buys Markov clustering at up to ** 642×** its CPU reference, k-medoids 146×,
102- Floyd–Warshall 28×; the traversal tier stays synchronous.
103- - ** Per-element bypasses returned as a first-class stylesheet section.** Buys
104- v3's ergonomics without v3's cost — id-keyed, surviving re-add, carried by
105- ` cy.json() ` (v3 loses them), twice as fast.
106- - ** Cross-commit benchmark comparison pages.** Buys regressions caught by the
107- archive rather than by a user: one four-day-old regression on first use.
108- - ** The load path measured, then taken apart.** Buys ** 1.9×** on the 465k-edge
109- load with a byte-identical rendered frame, and initialisation of that network
110- in ** ~ 0.95 s against v3's ~ 19 s** .
111-
112- ## Week 5 — 12 August
113-
114- - ** The benchmark runner runs jobs concurrently.** Buys a publishing run of the
115- ` all ` profile in ** 8.4 minutes instead of ~ 55** , so re-measuring stops being
116- a reason not to measure.
117- - ** Concurrency folded into the harness fingerprint, and the published archive
118- kept serial.** Buys the guarantee that a faster * instrument* can never be
119- read as a faster * library* .
51+ ## Day by day
52+
53+ - ** 22 Jul** — the whole stack, stood up in one day
54+ - Columnar store, model↔renderer contract, core facade, collections, events,
55+ viewport, compiled style engine, grid layout, WebGPU pipeline, GPU picking,
56+ pointer interaction, SDF labels, debug harness.
57+ - Buys the architecture proved end to end before any of it was polished.
58+ - ** 23 Jul** — the model earns its shape
59+ - Packed numeric keys for set operations, columnar flag scans, id-index
60+ selector resolution, slot-native traversal.
61+ - Buys v3's own API measuring faster on v4, not just its drawing.
62+ - ** 24 Jul** — style becomes data
63+ - Mapper spec compile, scale programs, OKLab colour and named schemes,
64+ ordinal dictionaries, GPU evaluation of scalar and colour channels.
65+ - Buys paint that never round-trips through the CPU, and style that can cross
66+ a wire.
67+ - ** 27 Jul** — visible-behaviour parity, in one sitting
68+ - Search, path, structure and centrality algorithms; polygon shapes; line
69+ styles; label visuals; edge labels; one easing layer; the gesture family
70+ (cxttap, taphold, dbltap, drag-all-selected); mount/unmount; device-loss
71+ recovery.
72+ - Buys an existing app the same picture and the same interactions.
73+ - ** 28 Jul** — measurement infrastructure
74+ - A single-page benchmark report, and browser renderer benchmarks putting v3
75+ canvas against v4 WebGPU.
76+ - Buys claims that are numbers.
77+ - ** 29 Jul** — memory comes back
78+ - String-dictionary and id-blob compaction, CSR adjacency rebuild.
79+ - Buys a long-running session that does not keep the graph it removed.
80+ - ** 30 Jul** — curved edges
81+ - Curve parameters, route pipeline, arrows on end tangents, labels at route
82+ midpoints, exact accessors, haystack and manual endpoints.
83+ - Buys v3's whole edge vocabulary.
84+ - ** 31 Jul** — compound graphs
85+ - Hierarchy model, lifecycle, auto-bounds, ancestor-gated visibility, event
86+ bubbling, parent draw/cull/pick, compound layouts and loop edges; end
87+ labels on v3's 3×3 grid.
88+ - Buys nested graphs, which most real applications use.
89+ - ** 1 Aug** — the layout leaves the main thread
90+ - The force layout on the extension contract with a GPU integrator; touch
91+ gestures; the display/visibility split; style transitions; slot compaction.
92+ - Buys layout that does not freeze the page, and a hide that costs only
93+ paint.
94+ - ** 2 Aug** — the visual vocabulary completed
95+ - Every remaining v3 node shape and arrowhead, v3's nonlinear arrow sizing,
96+ size/width/font/padding tweens, shipped TypeScript declarations.
97+ - Buys a stylesheet that ports without a lookup table of what is missing.
98+ - ** 3 Aug** — contracts gated, hot paths fixed
99+ - Documentation and error contracts gated at zero tolerance; the style read
100+ path's 150-case switch became a dispatch table; memoized collections;
101+ O(1) ` indexOf ` .
102+ - Buys a build that fails on an undocumented member or an untested guard, and
103+ a worst-case style read 2.6× faster.
104+ - ** 4 Aug** — v4 becomes the package
105+ - The repository split so v4 is the package and v3 lives whole in ` v3/ ` ; v4's
106+ own event emitter; packaging gates; the docs generator; the debug harness
107+ rebuilt.
108+ - Buys a v4 that ships alone, and a real v3 to keep measuring against.
109+ - ** 5 Aug** — robustness and publication
110+ - The soak tier (leaks, churn, wire fuzzing, multi-instance isolation); the
111+ status site; machine provenance and a tracked benchmark archive; fixtures
112+ shipped in v4's binary wire format.
113+ - Buys a deployable preview of the branch, and a benchmark history that
114+ survives the machine that produced it.
115+ - ** 6 Aug** — CI made honest
116+ - Fresh-checkout failures fixed, bundles built before the suite; v3's arrow
117+ gap and spacing constants ported; feature pipelines built on first draw.
118+ - Buys a green run that means something, and a first frame of 2.7 s where it
119+ had been 4.6.
120+ - ** 7 Aug** — parity found by measuring, not by looking
121+ - Numeric routing parity (geometry, not pixels); the arrow gap; element state
122+ (` :selected ` , ` :active ` , ` :grabbed ` ) as ordinary style condition rather than
123+ a shader constant; v3's selection colours.
124+ - Buys differences 400× below the pixel bound being caught, and every
125+ affordance being restyleable or disableable by an application.
126+ - ** 8 Aug** — the things you click
127+ - v3's hit halos, arrowheads as hit targets, ` :active ` on edge press;
128+ border-style and outline-style on every shape; minified WGSL; directional
129+ fit bounds.
130+ - Buys edges that are clickable again, and smaller shipped shaders.
131+ - ** 9 Aug** — every benchmark pair reads v4-faster
132+ - State flips write the diff rather than the element; the force layout made
133+ stable by construction; cross-commit benchmark comparison pages.
134+ - Buys performance visible across commits — the pages caught a four-day-old
135+ regression on first use.
136+ - ** 10 Aug** — the expensive algorithms go async, onto the GPU
137+ - Nine whole-graph algorithms return promises and take
138+ ` executor: 'cpu' | 'gpu' | 'auto' ` , with WGSL kernels and a performance
139+ pass; per-element bypasses returned as a stylesheet section;
140+ ` cy.collection() ` throws on an argument, ` cy.$() ` and ` cy.byId() ` return.
141+ - Buys Markov clustering at up to ** 642×** its CPU reference, and v3's bypass
142+ ergonomics at twice v3's speed.
143+ - ** 11 Aug** — the load path taken apart
144+ - Definition-form payloads convert to columns before ingest; mapped style
145+ costs per distinct value; a run of identically styled edges is written once;
146+ the benchmark comparison learned harness epochs, repeat medians and
147+ screened movers.
148+ - Buys ** 1.9×** on a 465k-edge load with a byte-identical frame, and a
149+ comparison page that can tell a change from its own noise.
150+ - ** 12 Aug** — the instrument
151+ - The benchmark runner runs jobs concurrently; concurrency is folded into the
152+ harness fingerprint and the published archive stays serial.
153+ - Buys a publishing run in ** 8.4 minutes instead of ~ 55** , with no way to
154+ mistake a faster instrument for a faster library.
120155
121156---
122157
@@ -134,9 +169,6 @@ The v4 rewrite: a columnar model and a WebGPU renderer, per
134169 ` executor: 'cpu' | 'gpu' | 'auto' ` .
135170- ** ` cy.collection() ` throws if passed an argument** ; ** ` cy.$() ` and
136171 ` cy.byId() ` ** restored as aliases.
137- - ** Element state** (` :selected ` , ` :active ` , ` :grabbed ` , …) is ordinary style
138- condition rather than a shader constant, so an application can restyle or
139- disable every affordance.
140172
141173## Open decisions
142174
0 commit comments