PERF GUARD: require bounded rendering and fail warm blaze on incomplete content (#663) #796

New issue

Open

opened 2026-10-02 13:10:58 +00:00 by kayg · 0 comments

kayg commented

2026-10-02 13:10:58 +00:00

Owner

PERF GUARD: require bounded rendering and fail warm blaze on incomplete content (#663)

Finding and context

origin/dev MailView.svelte:600 renders each thread row. Queued #640 supplies
virtualization and bench/blaze.mjs. At job/maillayouts f9f360e68,
bench/blaze.mjs:394–415 calculates mismatched/incomplete frames and missed
paints, but runBlaze returns the report and the CLI does not assert those
counts. A successfully executed measurement can therefore exit zero with
incomplete content. #641 owns the harness; #640 and #642 own Mail/Settings fixes.
Extend that harness and register all list surfaces; do not duplicate it.

Exact detection and contract tests

For each API-backed {#each} or React array render, resolve the registry surface
and its source. Require a declared finite maximum. A list that can exceed 100
items needs a registered shared virtualizer and a DOM-bound contract test.
A small fixed enum is exempt by a proved finite bound, not a name convention.
100 is a proposed render threshold based on #663 page size, not an existing
DESIGN limit. Calendar day/time grids and grouped photo tiles need their own
virtualization geometry record; checking only top-level groups is insufficient.

Feed 10k synthetic items through the surface's real component/API fixture.
Assert mounted item count <= its declared viewport+overscan bound at start,
middle, end and resize. The registry supplies an exact numeric maximum for
each viewport; missing maximum fails. Resident model row/byte caps are separate
assertions. Change highlight once and assert only old/new row render counters
advance; unchanged item object identities stay stable. Scroll, selection,
screen-reader counts and keyboard access remain correct. CSS
content-visibility alone does not count as virtualization.

Extend the existing blaze runner with a strict correctness mode. Registry maps
each list to an adapter that observes selected stable identity and required
content identity/readiness, not just a container or heading. Hold Down then Up
for at least 200 steps per direction, warm and cold separately, cadences 15/30/
60 ms. Warm pass fails on any mismatchFrames, incompleteFrames or
stepsNeverPaintedComplete >0. Require nonempty sampled frames and expected
step counts. Disabled adapters, missing browsers or skipped required passes
fail as incomplete coverage. Cold incomplete counts are retained and reported
separately; do not apply the warm zero-frame contract to cold network fetches.

Gates and validation

CI runs deterministic virtualizer/row tests plus a warm correctness profile
with content preloaded and controlled input. Keep wall-clock latency/dropped
frames/CPU/RSS thresholds periodic. The production VM run uses Chromium and
WebKit one at a time, 390/820/1440, light/dark and macOS platform emulation.
A fake report with one mismatch/incomplete/missed step must exit nonzero.
Zero frames, dropped/skipped adapters and absent required body nodes fail.
Store failed results too. Long tasks, dropped frames, heap and RSS remain
measured outputs, not substituted for content completeness.

Scope and exception contract

Specification only, from #663 perf-guards. Implement in a later job. Reuse the
shared guard registry and ledger described in the coverage issue. Until it
exists, use this exact contract: an exception has rule ID, repo-relative file,
symbol or route/surface ID, normalized syntax hash (or exact build metric),
owner issue, reason, replacement test and UTC expiry date. No directory globs,
line-number-only entries or ignore all comments. Fail on expired, changed,
duplicate and unused exceptions. Existing debt needs an explicit entry and a
non-growing limit. Print exceptions in CI. An exception does not waive access,
session clearing or accessibility tests. Generated and test fixtures are
excluded by explicit source class, not substring matching. Tests must prove
both violation detection and valid exceptions. No product fix belongs here.

The static/contract command exits 1 for violations, 2 for invalid configuration
or parse/build errors, and 0 only for complete passing coverage. Output includes
rule ID, file:line, symbol/route, actual value and required value. No User content.
Measured host timing stays periodic under CLAUDE.md. Deterministic guards fail
required CI; the dedicated perf-budget runner reports measured budget failures
with nonzero status but is not a required merge check.

# PERF GUARD: require bounded rendering and fail warm blaze on incomplete content (#663) ## Finding and context origin/dev MailView.svelte:600 renders each thread row. Queued #640 supplies virtualization and bench/blaze.mjs. At job/maillayouts f9f360e68, bench/blaze.mjs:394–415 calculates mismatched/incomplete frames and missed paints, but runBlaze returns the report and the CLI does not assert those counts. A successfully executed measurement can therefore exit zero with incomplete content. #641 owns the harness; #640 and #642 own Mail/Settings fixes. Extend that harness and register all list surfaces; do not duplicate it. ## Exact detection and contract tests For each API-backed `{#each}` or React array render, resolve the registry surface and its source. Require a declared finite maximum. A list that can exceed 100 items needs a registered shared virtualizer and a DOM-bound contract test. A small fixed enum is exempt by a proved finite bound, not a name convention. 100 is a proposed render threshold based on #663 page size, not an existing DESIGN limit. Calendar day/time grids and grouped photo tiles need their own virtualization geometry record; checking only top-level groups is insufficient. Feed 10k synthetic items through the surface's real component/API fixture. Assert mounted item count <= its declared viewport+overscan bound at start, middle, end and resize. The registry supplies an exact numeric maximum for each viewport; missing maximum fails. Resident model row/byte caps are separate assertions. Change highlight once and assert only old/new row render counters advance; unchanged item object identities stay stable. Scroll, selection, screen-reader counts and keyboard access remain correct. CSS content-visibility alone does not count as virtualization. Extend the existing blaze runner with a strict correctness mode. Registry maps each list to an adapter that observes selected stable identity and required content identity/readiness, not just a container or heading. Hold Down then Up for at least 200 steps per direction, warm and cold separately, cadences 15/30/ 60 ms. Warm pass fails on any mismatchFrames, incompleteFrames or stepsNeverPaintedComplete >0. Require nonempty sampled frames and expected step counts. Disabled adapters, missing browsers or skipped required passes fail as incomplete coverage. Cold incomplete counts are retained and reported separately; do not apply the warm zero-frame contract to cold network fetches. ## Gates and validation CI runs deterministic virtualizer/row tests plus a warm correctness profile with content preloaded and controlled input. Keep wall-clock latency/dropped frames/CPU/RSS thresholds periodic. The production VM run uses Chromium and WebKit one at a time, 390/820/1440, light/dark and macOS platform emulation. A fake report with one mismatch/incomplete/missed step must exit nonzero. Zero frames, dropped/skipped adapters and absent required body nodes fail. Store failed results too. Long tasks, dropped frames, heap and RSS remain measured outputs, not substituted for content completeness. ## Scope and exception contract Specification only, from #663 perf-guards. Implement in a later job. Reuse the shared guard registry and ledger described in the coverage issue. Until it exists, use this exact contract: an exception has rule ID, repo-relative file, symbol or route/surface ID, normalized syntax hash (or exact build metric), owner issue, reason, replacement test and UTC expiry date. No directory globs, line-number-only entries or `ignore all` comments. Fail on expired, changed, duplicate and unused exceptions. Existing debt needs an explicit entry and a non-growing limit. Print exceptions in CI. An exception does not waive access, session clearing or accessibility tests. Generated and test fixtures are excluded by explicit source class, not substring matching. Tests must prove both violation detection and valid exceptions. No product fix belongs here. The static/contract command exits 1 for violations, 2 for invalid configuration or parse/build errors, and 0 only for complete passing coverage. Output includes rule ID, file:line, symbol/route, actual value and required value. No User content. Measured host timing stays periodic under CLAUDE.md. Deterministic guards fail required CI; the dedicated perf-budget runner reports measured budget failures with nonzero status but is not a required merge check.

kayg referenced this issue

2026-10-02 13:15:00 +00:00

PERF: instant everywhere — app-wide speed architecture rules, audit and shared primitives #663

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/calternal#796

No description provided.

Rows
Columns