Skip to content

Commit c2d24c2

Browse files
committed
docs: the summary goes day by day, from the commit record
The weeks were wrong — grouped from memory of the rounds rather than from what actually landed when, which put the repository split, the soak tier and the CI work in the wrong buckets. Days are checked against `git log`: 20 active days between 2026-07-22 and 2026-08-12, all 20 listed, none invented (25–26 July and 1–2 August weekends have no commits and no entries). Each day is one point with its headline changes nested under it and what they buy: 22 July stood the whole stack up, 27 July took visible-behaviour parity in one sitting, 4 August made v4 the package, 10 August put the expensive algorithms on the GPU, 11 August took the load path apart. Rendered: three tables, 95 points, zero prose blocks. Claude-Session: https://claude.ai/code/session_01CZuBgFBGSDy6QtAYFL5sE3
1 parent c234ae7 commit c2d24c2

1 file changed

Lines changed: 109 additions & 77 deletions

File tree

EXECUTIVE_SUMMARY.md

Lines changed: 109 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)