Sheetwrite 0.4.0 Release Tracker

[chh-ay]

Tracking issue for Sheetwrite 0.4.0. Two themes — performance and delivery size — plus the rendering-correctness defects found in the macOS / worker-renderer audit.

The sections below are ordered: each one unblocks the next. Nothing here is set in stone — every performance and size item is gated on measurement, and an item whose benchmark or bun run size:report does not show the win is dropped rather than shipped on an estimate.

A prior audit found no dead code and no unused dependencies under the checks run so far (evidence and method limits), so deletion is not currently available as a size lever. Optionality and compiler settings are.

1. Foundations — blocks everything below

• Restore runnable Required CI, retain the matched performance protocol locally, and narrow unit coverage to Chromium (PRs fix(ci): restore a runnable required gate #35, perf: refresh the machine-pinned render baseline #37, and chore(ci): install only Chromium for benchmark smoke #38)
• Gate every pull request against its actual base branch; cut and protect 0.4.0 (PR fix(ci): gate every pull request against its base #39)
• Give the KIND_* wire contract one source of truth (PR refactor(core): share WASM cell-kind wire tags #42)

2. Rendering correctness — blocking

Evidence and acceptance criteria

• Never transfer ArrayBuffers owned by a cached VisibleWindowView (PR fix(core): preserve cached worker view buffers #43)
• Resize and repaint when devicePixelRatio changes without a CSS-size change (PR fix(core): repaint when device pixel ratio changes #46)
• Fall back to the main-thread renderer when the worker cannot acquire a 2D context (PR fix(core): fail closed when paint workers fail #44)
• Define and test an OffscreenCanvas context-loss policy (PR fix(core): fail closed when paint workers fail #44 — fatal fallback)
• Add WebKit + Chromium coverage for worker paint, DPI transitions, and cached-view scroll (PRs fix(core): preserve cached worker view buffers #43, fix(core): fail closed when paint workers fail #44, and fix(core): repaint when device pixel ratio changes #46)

3. Measurement — gate for every item in §4 and §5

Evidence and acceptance criteria

• Land the scenario benchmark set: formula-dense window, text-heavy scroll, fractional scroll, unresized 1M-row geometry (PR #48, results)
• Produce per-function/section byte attribution for the WASM artifact (twiggy, or wasm-opt --print-function-sizes — already in the wasm-pack cache). eval + calc is 238,064 shallow bytes: 79.33% of named Sheetwrite function bytes and 32.34% of the name-preserving Twiggy total (results)

4. Performance — each item ships only if §3 justifies it

• Remove the redundant formula-entry map probes in visible-window decoding
• Profile and cut WASM-to-JS window allocation and copy cost
• Remove per-frame render-signature string building
• Replace clear-everything string-cache eviction — dropped after profiling: cache/window decoding was not the long-text bottleneck
• Make row geometry allocation-free while no row has been resized (PR #49, results)
• Cut paint clipping cost without breaking intentional text spill

5. Delivery size

Baseline numbers and acceptance criteria

Compiler settings — cheapest lever, no code change

• Re-measure the release-profile tradeoff. Interleaved raw-backed captures keep opt-level = 3: 2 saves 2.08% Brotli but slows resolved 100k formula paths 5.72–8.46%; "s" saves 6.72% but slows them 8.60–11.71% (results, PR perf(bench): record wasm profile tradeoff #47)
• Run the build matrix: {crate opt-level 3, "s"} × {wasm-opt -O3, -Os, -Oz}, scored on size:report and the existing bench gates. wasm-opt ([package.metadata.wasm-pack.profile.release]) is a separate post-link knob needing no crate boundary — try it first
• Update the Cargo.toml justification comment with whatever the re-measurement actually shows

Bundle attribution — attribution first, cutover only if proven

• Attribute the Next.js vs Vite initial-bundle gap per module across both fixtures, after confirming they are comparable (mode, minifier, externals)
• Add dedicated subpaths for sync, collaboration, rebase, persistence; measure both fixtures again. An earlier subpath experiment proved a subpath alias alone saved 226 bytes against a 7,680-byte threshold — because GridImpl statically retains the stock chrome. These four modules differ (they are barrel-only, not reachable from GridImpl), which is exactly what the attribution must confirm
• Only if attribution proves the root re-exports are retained in the Next graph: open a follow-up to drop them from index.ts. That is a breaking API cutover — own changeset, migration note, consumer sweep. Not pre-approved here
• Decide the source-map publication policy for @sheetwrite/core
• Split first-paint-only code out of the eager grid.ts import chain
• Regenerate delivery-size reports; raise no existing ceiling

6. Maintainability

• Split store/data-engine.ts (3,691 LOC, fan-in 1 — no public API impact)
• Un-export the 41 internal-only symbols that are not part of the published surface
• Add an unused-export gate (knip or equivalent); neither tsc nor Biome detects unused exports today, so the current finding rests on a heuristic scan

7. Spikes — time-boxed, may not land in 0.4.0

• Store-only WASM artifact via --no-default-features. Gate 1: does it compile (FormulaEntry stores a calc::Ast; store owns eval::DepIndex). Gate 2: what does size:report say. Kill it if gate 1 is expensive
• Cold-crate extraction for a per-package opt-level override. Only if §3 attribution shows enough cold bytes to be worth the dependency inversion. Note lto = "fat" + codegen-units = 1 re-optimizes across crate boundaries and generic monomorphization emits into the instantiating crate, so the boundary is not a guaranteed size lever even after the split

Exit criteria

• Main-thread canvas verified on macOS Safari and Chromium at DPR 2
• Worker rendering either paints correctly or falls back observably (PRs fix(core): preserve cached worker view buffers #43 and fix(core): fail closed when paint workers fail #44)
• Before/after artifacts published for every performance claim
• bun run size:report regenerated; every size number traced to it
• Formula-recalc latency gated by bench/src/formula-bench.ts before any size-oriented compiler setting ships
• No public API or wire-format change ships without its consumers migrated

Explicitly out of scope

• Splitting the WASM crate purely to enable lazy loading. Two crates still link into one artifact; only separately loaded artifacts reduce first load, and that needs a serializable boundary across a cycle recalc crosses constantly. Superseded by the §7 spikes.
• New npm packages for the optional modules. Subpath exports get the same result without version skew across five lockstep packages.
• Decomposing grid.ts (3,146 LOC, fan-out 42). Real debt, and the earlier subpath experiment shows it is what blocks a minimal delivery boundary — but it is a 0.5.0 project. Doing it inside a performance release is how regressions ship.

[chh-ay]

Detail: rendering correctness

Never transfer buffers owned by a cached VisibleWindowView

RenderCoordinator only rebuilds lastPaintView when the data signature changes (packages/core/src/render-coordinator.ts:253-261) and hands that same view to renderer().paint() on every repaint (:274). WorkerRenderer.paint() transfers the view's raw ArrayBuffers (packages/core/src/worker-renderer.ts:199-224), which detaches them on the main thread. The next repaint inside the same data window therefore ships zero-length arrays, and the worker decodes an empty valuesScratch against a full-size window (packages/core/src/worker.ts:126-153).

Qualifiers for whoever reproduces this:

• The SharedArrayBuffer path returns before the transfer (worker-renderer.ts:196), so the bug is invisible under cross-origin isolation. Force canUseSharedMemory() to be false — the default for anyone not serving COOP/COEP.
• retainMainView() re-copies the view (render-coordinator.ts:268), but only when DOM merge anchors need refreshing, so the failure is intermittent and merge-dependent.
• ariaMirror.update(view) runs at :280, after the buffers were detached, so the accessibility mirror reads empty arrays on every worker frame. This is the cheapest assertion point — no canvas needed, just a postMessage stub that actually detaches.

Acceptance: a cached view repaints repeatedly under renderer: "worker" without shared memory, with no blank or stale strips and a populated ARIA mirror. Fix by establishing clear buffer ownership (clone-before-transfer as the safe baseline, worker-owned cached frames or SAB double buffering as the fast path). Do not transfer store-owned or cached-view buffers directly.

DPR change without a CSS-size change

Backing-store size is only recomputed in setViewport() (packages/core/src/canvas-renderer.ts:59-75, packages/core/src/worker-renderer.ts:164-170), and renders are scheduled from scroll, store changes, and the host ResizeObserver (packages/core/src/grid.ts:462-463, :964-971). There is no resolution listener, so moving a window between a Retina and non-Retina display leaves the canvas at the stale raster scale until something else happens to render. The existing DPR check in syncSizer() (grid.ts:1253-1263) only re-measures the scroll clamp.

Acceptance: a self-rearming matchMedia("(resolution: Ndppx)") listener, removed on destroy, that re-measures the clamp, invalidates renderer state, and schedules a frame. Cover 1→2 and 2→1 with no CSS-size change.

Worker 2D-context failure is silent

The worker stores getContext("2d", { alpha: false }) without a null check (packages/core/src/worker.ts:279-284); paintView() then returns false with no acknowledgement (:186-212). The main thread only reacts to construction throws and worker error events (packages/core/src/grid.ts:974-1007, worker-renderer.ts:301-312), so a partial OffscreenCanvas implementation yields a permanently blank canvas instead of the intended fallback. Safari has shipped OffscreenCanvas 2D since 16.4, so "Safari just falls back" is no longer true.

Acceptance: explicit ready/fatal handshake after the context is acquired, bounded readiness timeout, and the existing observable renderer-fallback on failure.

Context loss

OffscreenCanvas emits contextlost / contextrestored; neither is handled. Either treat loss as renderer failure or handle restoration with a guaranteed full repaint — pick one and test it.

Test gaps

packages/core/test/worker-renderer.test.ts:8-19 records the transfer list but never detaches, and test/browser/react-workbench.spec.ts:367-386 proves only that the first worker frame arrives. Neither can catch any of the above.

[chh-ay]

Detail: performance

Benchmarks first. The repo already has the instrumentation to judge these (ffiInputBytes / ffiOutputBytes accounting on the read path, resource-accounting.ts, the bench gates) — add the counter before the fix, and drop any item the counter does not justify.

Scenarios to land before any optimization: formula-dense viewport, text-heavy long scroll, fractional / momentum-style scroll, and a million-row sheet with no resized rows.

Formula-entry map probes

fill_window_cell() calls formula_error_at(), which probes spill_errors then formulas (packages/wasm/src/sheet.rs:1780-1786), and for error-free formulas probes formulas again for value_kind (packages/wasm/src/window.rs:217-242) — up to three probes per formula cell per frame. Fetch the entry once while preserving spill-error precedence.

Do not pack the resolved kind into the high nibble of the wire kind byte. kind crosses the FFI and TypeScript compares it by raw equality (packages/core/src/store/data-engine.ts:111-116, :1503-1510); that is a wire-format migration, not a local Rust edit. A separate dense byte or distinct top-level tags with every consumer updated are the honest options.

WASM-to-JS window transfer

The generated glue .slice()s every typed-array return and frees the WASM allocation (packages/wasm/pkg/sheetwrite_wasm.js:1503-1568). The copy is real; the throughput numbers floating around are not — for a 60×20 window the six per-cell streams are at most ~25 B/cell, about 30 KB/frame. Measure allocation counts and frame timing before designing anything, and note that a persistent scratch region interacts with both worker transfer and WASM memory growth.

Per-frame allocation

• Render signatures are built by join(",") plus two template concatenations every frame, including float-to-decimal formatting of contentTop (packages/core/src/render-coordinator.ts:177-179, :226-233).
• StoreWindowReader drops all 65,536 entries at the cap (packages/core/src/store/window-reader.ts:262-288); the worker mirrors it (packages/core/src/worker.ts:119). Generational eviction only if the text-scroll scenario shows the churn.
• OffsetIndex allocates and fills both Float64Arrays in the constructor (packages/core/src/fenwick.ts:13-20), so an exceptionCount === 0 early return is not enough — it needs a genuinely lazy uniform representation. rowAtOffset() also recomputes its bit-search bound per call (:90-91). Do the lazy representation before considering sparse or blocked structures.

Paint clipping

Per-cell save/clip/restore is expensive, but the clip is load-bearing: paintCell() computes spill bounds so left/right/centre-aligned strings can overflow into eligible neighbours (packages/core/src/canvas-paint.ts:749-770). Any skip must prove the run stays inside its permitted spill region. The numeric path already avoids most exact measureText() calls via the cached digit-width estimate (:713-727).

[chh-ay]

Detail: delivery size

Baseline from the recorded report (scripts/size-report.json, commit dfc77cb, dirty):

Artifact	Raw	Brotli
WASM (@sheetwrite/wasm)	683,490	208,727
core initial JS — Vite	458,055	109,149
core initial JS — Next	—	227,446
@sheetwrite/core tarball	529,490	—
@sheetwrite/core unpacked	2,845,386	—

Source maps

package.@sheetwrite/core.mapsBytes is 1,371,090 of 2,845,386 unpacked bytes — 48% (scripts/size-report.json:574-608). Dropping or relocating them is a packaging-policy decision, not a code change, and it does not affect browser payload. Quote the tarball delta separately from the unpacked delta; "halves install size" is only true of the unpacked number.

Eager import chain

grid.ts statically imports toolbar, context menu, find bar, sheet tabs, clipboard, validation and custom editors, search, and export.ts (packages/core/src/grid.ts:11-49). None are needed for first paint. Profile module attribution first, then lazy-load only the interaction paths, with explicit loading and error behaviour plus bundler-fixture coverage.

Next vs Vite gap

Worth attributing before acting. The usual diagnosis — "the barrel defeats webpack's sideEffects analysis" — does not fit: the package already declares sideEffects and already ships ./adapter, ./browser, ./shell, ./worker, ./testing subpaths (packages/core/package.json:24-63). Also confirm the two fixtures are comparable (mode, minifier, externals) before attributing 2× to tree-shaking at all. Add subpaths only for paths the attribution proves expensive; sync.ts, collaboration.ts, and rebase.ts are the obvious candidates via packages/core/src/index.ts.

Formula-engine separation

The single WASM blob is the largest wire item and formula evaluation is a plausible majority of it, but a split changes initialization, dependency, and data-ownership boundaries — store code and eval share SheetData. Treat this as a design spike for 0.4.0: produce a per-module WASM size breakdown, write the loading/ownership design, and only then decide whether the split (and a per-crate opt-level change) lands in this release or the next.

[chh-ay]

Detail: codebase audit (dead code, coupling, maintainability)

Ran before sequencing this release, so the work is not built on guesses about what can be deleted.

No dead code found by the checks run so far

Check	Result
Exported symbols unreferenced outside their own module (src only)	67
…still unreferenced across tests + all sibling packages + bench/docs/examples/scripts	41
…present in the published API surface (bun run api:report: 384 symbols, 6 packages, 18 entrypoints)	0
…never referenced even inside their own module	0
Declared dependencies with zero references	0
cargo check --target wasm32-unknown-unknown	clean, 0 dead_code warnings
TODO / FIXME / HACK / XXX in packages/*/src	0
bun scripts/check-import-cycles.ts	acyclic

So the 41 are over-exported internals — not public API, not dead. Dropping the export keyword tightens the internal surface and saves zero bytes. tests.rs (3,579 lines) is cfg(test) and never ships.

Consequence for this release: deletion is not currently a size lever. Optionality is.

Method limits — this is not an exhaustive dead-code analysis. The symbol scan is regex word-boundary matching over the repo, cross-validated only by api:report for the public/private split. It cannot see dynamic access, string-keyed dispatch, or re-export chains it failed to resolve. Neither tsc nor Biome detects unused exports, and the repo has no knip/ts-prune. Module reachability from entrypoints is also weak evidence on its own, because the root barrel re-exports most of the tree. Treat the table as “nothing found”, not “nothing exists” — §6 adds a real gate.

Why the WASM crate split is a spike, not a deliverable

calc.rs + eval/* is ~11k of ~19.8k shipped Rust lines, so the instinct is sound. The coupling is not:

• store.rs → calc::Ast, eval::DepIndex (8 references; FormulaEntry stores an Ast)
• eval/* → CellStore, SheetData (8 references; recalc takes &mut CellStore)

That is a type-level cycle. Two consequences:

1. A crate split alone ships zero fewer bytes — both crates link into one wasm-bindgen artifact. Only separately loaded artifacts reduce first load. (Separate modules can share an ordinary WebAssembly.Memory; no cross-origin isolation needed. The real blockers are single-allocator ownership, no stable Rust ABI across separately compiled modules, duplicated bindgen glue, and copy costs on a boundary that recalc crosses constantly.)
2. Even a --no-default-features store-only build must cfg-gate or replace the Ast field and DepIndex ownership plus every API touching them.

Hence the gate: does a store-only build compile at all, then what does size:report say. Kill it cheaply if gate one fails.

Maintainability hotspots

Median core module is 240 LOC. The outliers:

Module	LOC	fan-in	fan-out
store/data-engine.ts	3,691	1	24
grid.ts	3,146	4	42
document-protocol.ts	2,793	8	8
store.rs	3,222	—	—

• data-engine.ts has fan-in 1 (only store.ts) — it can be split without touching one line of public API. Best risk-to-LOC ratio in the repo.
• grid.ts fan-out 42 is the god object, and the same root cause as the eager-import size item. Decomposing it is a 0.5.0 project; doing it inside a performance release is how regressions ship.
• The KIND_* wire contract is defined four times: store/data-engine.ts:112-115, store/window-reader.ts:9-11, worker.ts:88-90, and Rust types.rs. STRING_CACHE_CAP twice. This is exactly why packing a resolved kind into the wire kind byte would have silently broken three consumers — it is sequenced first for that reason.

What argues against a general “this is unmaintainable” read: no TODO debt, acyclic graph, clean cargo, and comments that record why (the local_style_index linear-scan rationale, the fractional-blit note, the measured unchecked-indexing verdicts). Three modules outgrew their boundary; the rest is healthy.

[chh-ay]

CI-compute prerequisite is complete:

• fix(ci): restore a runnable required gate #35 removed the unavailable required self-hosted timing job after the repository runner count reached zero; deterministic smoke/ceiling checks remain in CI and the matched protocol remains fail-closed locally.
• perf: refresh the machine-pinned render baseline #37 refreshed the machine-pinned matched baseline after the PostCSS lockfile fix changed the harness fingerprint; the strict old-limit diagnostic found no regression across all 28 cells.
• chore(ci): install only Chromium for benchmark smoke #38 narrowed unit-coverage to Chromium only; the dedicated browser-smoke job still installs and exercises Chromium, Firefox, and WebKit.

The original conditional perf_required design in #34 was closed as superseded because it could not prevent performance-sensitive PRs from deadlocking with no registered runner. Next bootstrap item is release-branch CI/base-ref changeset gating before cutting 0.4.0.

[chh-ay]

Release-branch bootstrap is complete.

• fix(ci): gate every pull request against its base #39 merged as b8f98c1: CI now runs for every pull request, while push CI remains limited to develop.
• scripts/changeset-ci.ts resolves GITHUB_BASE_REF once and uses it for both package-size-history diffing and Changesets --since, with origin/develop only as the non-PR fallback.
• Branch 0.4.0 was cut at b8f98c1 and has the same strict Required CI protection as develop (admins enforced, linear history, conversation resolution, no force pushes/deletion).
• Disposable test(ci): exercise release branch routing #40 targeted 0.4.0 and passed Preflight, proving positive routing and base resolution; it was closed unmerged.
• Disposable test(ci): reject release PR without changeset #41 targeted 0.4.0 with a package change and no changeset. Preflight invoked changeset status --since=origin/0.4.0 and failed as required; it was closed unmerged.

Stage 0 is complete. The first feature PR can now consolidate the KIND_* wire contract and target 0.4.0.

[chh-ay]

Foundation item complete: PR #42 merged into 0.4.0 as 0e09ecc.

• TypeScript cell-kind tags and NO_STRING now have one internal source in packages/core/src/store/wire-tags.ts.
• Store data engine, window reader, and paint worker import the shared values; Rust points back to the mirror and behavior-backed test.
• Coverage and import-ownership manifests register the new leaf module.
• Required CI run 30208811960 passed all checks, including Unit Tests & Coverage and Browser Smoke.
• Changeset: .changeset/calm-tables-share.md.

[chh-ay]

Rendering-correctness buffer ownership fix is open in #43 against 0.4.0.

• WorkerRenderer now transfers only buffers it allocated across packed, generic, and frozen-pane paths.
• The faithful pre-fix reproduction failed on the second cached-view paint with DataCloneError after the first transfer detached the caller-owned arrays.
• Focused unit coverage passes (10/10), core passes (756/756), and the cached non-SAB browser repaint regression passes in Chromium and Firefox.
• Required CI is in progress; completion evidence and merge SHA will be posted here after merge.

[chh-ay]

Cached-view buffer ownership is complete: PR #43 merged into 0.4.0 as b225783.

• Required CI run https://github.com/chh-ay/sheetwrite/actions/runs/30211990990 passed, including Browser Smoke across Chromium, Firefox, and WebKit.
• Pre-fix faithful transfer reproduction: 7 pass / 1 fail; the second cached-view paint threw DataCloneError after the first transfer detached caller-owned buffers.
• Post-fix: worker-renderer 10/10, core 756/756, typecheck, API policy, lint, import-cycle, and changeset gates passed.
• Root suite: 1270 pass / the same seven known unrelated failures (one compatibility-inventory check and six billion-cell artifact checks), with no additional failures.
• No public API or worker message shape changed; the payload now carries renderer-owned typed-array copies.

The shared WebKit/Chromium coverage tracker item remains open for the remaining worker readiness/context-loss work.

[chh-ay]

Worker readiness and failure handling is open in PR #44 against 0.4.0.

• Paint workers now report ready and fatal initialization/context-loss outcomes.
• The host starts a bounded readiness timer and routes fatal, timeout, and Worker errors through one guarded canvas fallback.
• Pre-fix: the two new fallback reproductions produced 4 pass / 2 fail; both stayed on the worker renderer.
• Post-fix focused tests: 18/18; core: 760/760; root failures remain the same seven known baseline failures.
• Local browser run: 172 passed in Chromium/Firefox; WebKit could not launch because workstation libraries are unavailable, so Required CI is the WebKit gate.
• API note: WorkerAcknowledgement is already published, so adding the required ready/fatal variants necessarily changes the additive public type. PR fix(core): fail closed when paint workers fail #44 updates the API baseline and generated docs rather than claiming the surface is unchanged.

Required CI is in progress.