How OpenChronology was built

#102 · Advise by how long users wait for views; recalibrate comfortable sizes

2026-10-12T05:09:24Z CE

• timeline-app
• pull request

Closes #69. The browser's "consider another platform" advice now measures what users wait for. The comfortable sizes are recalibrated from benchmark runs on GitHub's runners, and CI enforces both. ## 1. Measuring the wait - `src/app.ts` records each navigation input (wheel, drag, pinch, keys, clicks) by its event `timeStamp`. Once a new view is drawn, it records the time from that input to that frame's paint. The capacity advice uses these samples in place of the editor's own drawing time. - Opening is now timed until its first paint, not just until it is drawn. - **Zoom frames lagged.** Measuring this showed that each zoom-animation frame moved the axis and the bounds fields, but drew the moments only in the next frame. Zoom frames now draw the moments together with the axis. - **The benchmark stopped too early.** `bench/ui.mjs` stopped timing at the bounds fields, a frame before the moments were drawn. It now waits for the drawn view, which the editor records on `#markers` as it draws. With that change, the app's own measurement and the benchmark agree to the millisecond on every key press I compared. ## 2. Recalibrating A temporary job, since removed, ran the browser benchmarks on hosted runners at 250 to 4,000 moments, at full speed and throttled 4×. The data is in `docs/benchmarks.md#comfortable-sizes`. - **Full speed:** every interaction meets its budget up to **1,000** moments. Wheel zoom and pinch miss from 2,000. - **Throttled 4×:** navigation misses at **every** size (wheel zoom takes 257 ms even at 250 moments), because each frame redraws the view (#68). Apart from navigation, every interaction meets its budget up to **500** moments. So `COMFORTABLE` changes from 4,000 / 1,000 to **1,000 / 500**. As agreed, slow navigation is advised only from 1,000 moments (`THRESHOLDS.navigationMoments`). Below that, the time goes on per-frame drawing that every platform does in the browser, so moving would not help. Two fixes found by gating the advice: - **Advice disappeared.** The median of the last five waits mixes kinds of navigation, so a few quick pans after slow zooming hid the advice again. Once a device measures a timeline as slow, the advice now holds for that timeline (`Measurements.slow`), and its message quotes the measurement that triggered it. - **Renaming reset the measurements.** For a timeline kept only in the browser, measurements were keyed by title, so renaming it discarded them. They now belong to the open document. Dismissals stay keyed by title, so they still survive reopening the file. ## 3. CI - The new **UI capacity advice** job checks three things: - the 4×-throttled browser at 500 moments, with navigation as a known #68 miss; - that the advice shows wherever an interaction misses just past each comfortable size: 2,000 moments at full speed, and 1,000 throttled 4×. - The existing PostgreSQL-job gate still covers the browser and platform at 1,000 moments. It passed with the stricter timing; the slowest interaction was wheel zoom at 110 ms. ## Tests - `test/capacity.test.mjs`: - navigation medians; - the 1,000-moment rule; - the advice holding once a timeline is measured slow. - `test/capacity-browser.mjs`: a timeline opened at full speed, then zoomed with the CPU throttled, shows "Zooming and panning this timeline take about N ms to show". - Locally: - `npm test` passes (232 tests); - the Chromium suite passes; - the full-speed "past the comfortable size" gate passes with no advice gaps. Before the rename fix, it showed 10 gaps. Docs: `docs/capacity.md` covers the comfortable sizes and advice rules; `docs/benchmarks.md` covers the timing, the calibration data and the gates.

Open #102 · Advise by how long users wait for views; recalibrate comfortable sizes in the timeline