PERF: show the first PDF page before loading every page size (#663)

kayg commented

2026-10-02 13:12:33 +00:00

Owner

Parent: #663. Non-blocking loading finding. Related: #741 (PDF accessibility), #35 (viewer).

Source: origin/dev c4a61e8cf0. packages/ui/src/components/viewer/PdfView.svelte:32–55 imports pdf.js lazily, then loops from 1 through loaded.numPages and awaits loaded.getPage(index) for every page before assigning pages = sizes. The template renders canvases from pages. IntersectionObserver limits raster work only after this complete metadata pass. Round 7a and the relevant round 7b queue do not change PdfView.

Impact is reasoned, not timed: first-page display waits for O(total pages) metadata retrieval, even though only the first viewport is needed. The comment at :2–6 claims a 400-page PDF opens as fast as a 4-page PDF, but this code does not guarantee that. pdf.js itself is correctly outside the initial route closure (120,340 B gzip plus a separate worker asset).

Concrete fix: publish the first visible page dimensions and canvas as soon as available. Resolve other dimensions in bounded, yielding batches; use safe reserved geometry for pending pages and preserve scroll position as actual sizes arrive. Keep cancellation and retries correct when the selected PDF changes. Reuse #741's eventual text layer; do not create another PDF viewer.

Test: a controlled multi-page document or pdf.js test double with delayed off-screen getPage responses. Assert the first page renders before the final metadata response; measure a 4-page and a 400-page real PDF with first visible page ready as the boundary. Assert later pages, cancellation, scroll stability, errors and keyboard navigation still work. Record ≥5 perf VM samples under /root/perf.lock, median/p95/max, CPU/RSS. Search before filing: all PDF issues; #741 concerns absent text, #547 concerns server thumbnails; no first-page metadata owner found.

Parent: #663. Non-blocking loading finding. Related: #741 (PDF accessibility), #35 (viewer). Source: origin/dev c4a61e8cf090170f35b1bed3350d9de20c83ecd5. packages/ui/src/components/viewer/PdfView.svelte:32–55 imports pdf.js lazily, then loops from 1 through loaded.numPages and awaits loaded.getPage(index) for every page before assigning pages = sizes. The template renders canvases from pages. IntersectionObserver limits raster work only after this complete metadata pass. Round 7a and the relevant round 7b queue do not change PdfView. Impact is reasoned, not timed: first-page display waits for O(total pages) metadata retrieval, even though only the first viewport is needed. The comment at :2–6 claims a 400-page PDF opens as fast as a 4-page PDF, but this code does not guarantee that. pdf.js itself is correctly outside the initial route closure (120,340 B gzip plus a separate worker asset). Concrete fix: publish the first visible page dimensions and canvas as soon as available. Resolve other dimensions in bounded, yielding batches; use safe reserved geometry for pending pages and preserve scroll position as actual sizes arrive. Keep cancellation and retries correct when the selected PDF changes. Reuse #741's eventual text layer; do not create another PDF viewer. Test: a controlled multi-page document or pdf.js test double with delayed off-screen getPage responses. Assert the first page renders before the final metadata response; measure a 4-page and a 400-page real PDF with first visible page ready as the boundary. Assert later pages, cancellation, scroll stability, errors and keyboard navigation still work. Record ≥5 perf VM samples under /root/perf.lock, median/p95/max, CPU/RSS. Search before filing: all PDF issues; #741 concerns absent text, #547 concerns server thumbnails; no first-page metadata owner found.

pdf-viewer-first-page-phone-light.png

75 KiB

pdf-viewer-first-page-phone-dark.png

121 KiB

pdf-viewer-first-page-tablet-light.png

35 KiB

pdf-viewer-first-page-tablet-dark.png

40 KiB

pdf-viewer-first-page-desktop-light.png

39 KiB

pdf-viewer-first-page-desktop-dark.png

46 KiB

kayg referenced this issue

2026-10-02 13:14:40 +00:00

PERF: initial JS is 322 kB gzip before route code (budget 200 kB), +20–25% since 2026-09-27 #497

kayg referenced this issue

2026-10-02 13:21:20 +00:00

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

kayg commented

2026-10-02 13:25:59 +00:00

Author

Owner

Starting work on job/webperf, based on 2f4482ded066d9c5d9c59130377907f7fd2916c9 (job/merge-round-7a). I am reading the matching audit evidence and will report the concrete finding, regression coverage, measurements, and gate output here when finished.

Starting work on `job/webperf`, based on `2f4482ded066d9c5d9c59130377907f7fd2916c9` (`job/merge-round-7a`). I am reading the matching audit evidence and will report the concrete finding, regression coverage, measurements, and gate output here when finished.

kayg commented

2026-10-02 14:24:58 +00:00

Author

Owner

Finding for #805: The viewer reserved all page geometry before rendering page one, so opening a large PDF waited on off-screen metadata. The controlled component check reproduced this: page 1 getPage completed, but the first canvas remained absent and the viewer stayed at “Opening the PDF…”. I moved PDF.js loading behind a lazy loader and publish page one geometry immediately, then refine later page sizes in batches of eight while preserving the visible scroll anchor and fencing replaced documents. The helper regression test verifies first publish, bounded calls, later geometry, and cancellation. Commit: a3bb642a5. The focused test passed; bun run check is still in progress.

Finding for #805: The viewer reserved all page geometry before rendering page one, so opening a large PDF waited on off-screen metadata. The controlled component check reproduced this: page 1 getPage completed, but the first canvas remained absent and the viewer stayed at “Opening the PDF…”. I moved PDF.js loading behind a lazy loader and publish page one geometry immediately, then refine later page sizes in batches of eight while preserving the visible scroll anchor and fencing replaced documents. The helper regression test verifies first publish, bounded calls, later geometry, and cancellation. Commit: a3bb642a5. The focused test passed; `bun run check` is still in progress.

kayg commented

2026-10-02 17:28:13 +00:00

Author

Owner

Finding: PDF Quick Look waited for later pages' dimensions before painting page one. It now renders page one from its own dimensions and reads later dimensions after the first page is visible. Added a focused regression test and a macOS-emulated screenshot path for 390/820/1440 in light and dark. Production build passed; screenshot artifacts were not captured in this run.

kayg referenced this issue

2026-10-02 17:40:30 +00:00

SECURITY: update locked JavaScript packages with known advisories #810

kayg commented

2026-10-02 17:41:27 +00:00

Author

Owner

F3 — P1: PDF loading subscribes to its own document state

Owner: #805. Introduced by a3bb642a5.
Evidence: packages/ui/src/components/viewer/PdfView.svelte:64, :77, :101.
The effect calls load(src). Before the first await, load reads doc into
previous. Svelte tracks synchronous reads in called functions, so the effect
now depends on doc as well as src. When loading assigns doc = loaded, the
effect runs again, destroys that document, clears its pages and starts another
load. A normal PDF can stay in a load/destroy cycle. The helper-only regression
does not mount this component and cannot detect the cycle.
This is inferred from source and the Svelte dependency rule;
no browser run is claimed.

Fix: track src and headers explicitly in the effect; run document cleanup and
load setup inside untrack. Preserve cancellation when the User changes files.
Rule: DESIGN §15 requires PDF preview; §34 requires content when data exists.
Test idea: mount PdfView with a controlled loader, resolve page one, flush more
than one effect cycle and assert one load, no destroy and a retained canvas.
Then change src and check exactly one cleanup and one replacement load.
Search before reporting: PDF, PDF reload and #805. Use #805 for this fix.

F4 — P2: PDF size batches repeat whole-document work

Owner: #805. Introduced by a3bb642a5.
Evidence: packages/ui/src/components/viewer/pdf-page-sizes.ts:41 and
PdfView.svelte:34, :35, :58.
Every eight pages copy the full N-page array, publish it into the full keyed
list and query all page canvases. Scroll-anchor lookup also reads rectangles
from the first page to the visible page. At page 400, about 50 batches copy
20,000 references and can read about 20,000 page rectangles. At N pages the
work is O(N squared), even though each batch reads only eight new PDF pages.
These are source operation counts, not measured frame times or forced reflow.

Fix: update only the changed page geometry. Keep the visible anchor with the
existing IntersectionObserver or an indexed geometry model, then read at most
the anchor element. Do not scan every previous page for each metadata batch.
Rule: CLAUDE.md makes performance the first priority; #805 asks for bounded
yielding batches and stable scroll position.
Test idea: count array/page updates and DOM reads for 400 and 4,000 pages while
the final page is visible. Require linear total work and a stable viewport.
Search before reporting: PDF, page sizes and #805. Group with F3 under #805.

## F3 — P1: PDF loading subscribes to its own document state Owner: #805. Introduced by `a3bb642a5`. Evidence: `packages/ui/src/components/viewer/PdfView.svelte:64`, `:77`, `:101`. The effect calls `load(src)`. Before the first await, load reads `doc` into `previous`. Svelte tracks synchronous reads in called functions, so the effect now depends on `doc` as well as `src`. When loading assigns `doc = loaded`, the effect runs again, destroys that document, clears its pages and starts another load. A normal PDF can stay in a load/destroy cycle. The helper-only regression does not mount this component and cannot detect the cycle. This is inferred from source and the [Svelte dependency rule](https://svelte.dev/docs/svelte/$effect#Understanding-dependencies); no browser run is claimed. Fix: track src and headers explicitly in the effect; run document cleanup and load setup inside `untrack`. Preserve cancellation when the User changes files. Rule: DESIGN §15 requires PDF preview; §34 requires content when data exists. Test idea: mount PdfView with a controlled loader, resolve page one, flush more than one effect cycle and assert one load, no destroy and a retained canvas. Then change src and check exactly one cleanup and one replacement load. Search before reporting: `PDF`, `PDF reload` and #805. Use #805 for this fix. ## F4 — P2: PDF size batches repeat whole-document work Owner: #805. Introduced by `a3bb642a5`. Evidence: `packages/ui/src/components/viewer/pdf-page-sizes.ts:41` and `PdfView.svelte:34`, `:35`, `:58`. Every eight pages copy the full N-page array, publish it into the full keyed list and query all page canvases. Scroll-anchor lookup also reads rectangles from the first page to the visible page. At page 400, about 50 batches copy 20,000 references and can read about 20,000 page rectangles. At N pages the work is O(N squared), even though each batch reads only eight new PDF pages. These are source operation counts, not measured frame times or forced reflow. Fix: update only the changed page geometry. Keep the visible anchor with the existing IntersectionObserver or an indexed geometry model, then read at most the anchor element. Do not scan every previous page for each metadata batch. Rule: CLAUDE.md makes performance the first priority; #805 asks for bounded yielding batches and stable scroll position. Test idea: count array/page updates and DOM reads for 400 and 4,000 pages while the final page is visible. Require linear total work and a stable viewport. Search before reporting: `PDF`, `page sizes` and #805. Group with F3 under #805.

kayg referenced this issue

2026-10-02 17:45:11 +00:00

PERF: bound Calendar drag geometry reads and snap candidate lookup (#663) #751

kayg commented

2026-10-02 23:01:50 +00:00

Author

Owner

Findings F3/F4: the PDF load effect tracked the document it cleaned up, which could restart loading and destroy the new document. Page-size batches also recopied the full page list and scanned canvases to find the scroll anchor.

Fix: the effect now tracks source and header values explicitly and runs load setup untracked. A mounted component regression checks one load, retained first page, one cleanup on source/password change, and correct replacement. Page metadata now publishes one initial list then only changed ranges of at most eight pages; the visible page index selects one anchor canvas for scroll correction. Tests cover 400- and 4,000-page update counts and bounded anchor reads.

Verification: bun run check passed with svelte-check found 0 errors and 0 warnings. The targeted Calendar/PDF component run passed: Test Files 2 passed (2); Tests 13 passed (13). The other three focused files passed 35 tests. Fix commit: facfab38d.

Findings F3/F4: the PDF load effect tracked the document it cleaned up, which could restart loading and destroy the new document. Page-size batches also recopied the full page list and scanned canvases to find the scroll anchor. Fix: the effect now tracks source and header values explicitly and runs load setup untracked. A mounted component regression checks one load, retained first page, one cleanup on source/password change, and correct replacement. Page metadata now publishes one initial list then only changed ranges of at most eight pages; the visible page index selects one anchor canvas for scroll correction. Tests cover 400- and 4,000-page update counts and bounded anchor reads. Verification: `bun run check` passed with `svelte-check found 0 errors and 0 warnings`. The targeted Calendar/PDF component run passed: `Test Files 2 passed (2); Tests 13 passed (13)`. The other three focused files passed 35 tests. Fix commit: `facfab38d`.

kayg commented

2026-10-03 00:22:06 +00:00

Author

Owner

Production PDF Quick Look screenshots (macOS platform emulation; production SPA, real local server and PDF fixture) cover phone, tablet and desktop in light and dark:

Phone light:
Phone dark:
Tablet light:
Tablet dark:
Desktop light:
Desktop dark:

Production PDF Quick Look screenshots (macOS platform emulation; production SPA, real local server and PDF fixture) cover phone, tablet and desktop in light and dark: - Phone light: ![PDF Quick Look, phone, light](https://git.kayg.org/attachments/88916a8f-807e-4db5-aefc-9b414f251e91) - Phone dark: ![PDF Quick Look, phone, dark](https://git.kayg.org/attachments/cf09e657-4951-49ba-9e6b-9af816f939bf) - Tablet light: ![PDF Quick Look, tablet, light](https://git.kayg.org/attachments/ddf5842f-7b7b-49e4-b0dd-f5eddea44228) - Tablet dark: ![PDF Quick Look, tablet, dark](https://git.kayg.org/attachments/7a7995c6-634c-4ad7-a2ae-9c951ea0f72e) - Desktop light: ![PDF Quick Look, desktop, light](https://git.kayg.org/attachments/e94bbeb3-4f3e-4627-9dd3-05e04c94ec1d) - Desktop dark: ![PDF Quick Look, desktop, dark](https://git.kayg.org/attachments/32ed65e1-d89b-41ef-838e-fbb8a677df95)

kayg referenced this issue

2026-10-03 00:33:38 +00:00

PERF: bound Calendar drag geometry reads and snap candidate lookup (#663) #751

kayg referenced this issue

2026-10-03 13:07:15 +00:00

Plan: merge order and conflicts for merge round 7b #867

kayg referenced this issue

2026-10-03 13:18:59 +00:00

Plan: merge order and conflicts for merge round 7b #867

kayg referenced this issue

2026-10-03 13:41:49 +00:00

Plan: merge order and conflicts for merge round 7b #867