port: attachments (approved mockup) 1/3: images

kayg commented

2026-11-02 09:34:49 +00:00

Owner

Update: first-paint budget (#866)

perf/web.sh --bundle-only --gate (from perf/budgets-per-app, #866, PERF_DIST = this branch's build with #866's vite config) first said first_js_brotli 242.147 KB > 240. The picture widget and the attach code are now out of the entry chunk:

attachments lazy chunk (3.09 KB brotli): add/paste/drop (attach.ts, upload.ts, one page listener for pasted/dropped files), the sizes the server knows (meta.ts), the picture widget class, the viewer's opener, the sizes cache. Loaded when a note with a picture opens, when someone first uses Attach or the Insert grid's Image/File, and once the app is idle after the first paint (like the other lazy screens), so a pasted file is taken at once.
Entry keeps only: a imageWidget facet and a check in hidden.ts that hands a line's text to the app (it draws nothing until the chunk is here), the 60-line shim lib/attachments/lazy.ts (load, widget, pictures, attachMenu), the Attach button, a paperclip icon path, and the wait for the chunk and the sizes before a note with pictures draws (so its boxes have their final shape and nothing jumps).
The camera icon's path comes with the chunk (addIcon); the viewer's state lives in PictureViewer.svelte's module script and the chunk mounts it itself; the "menu from a button at the foot of the screen opens above it" placement moved into ContextMenu (already lazy), so menu.ts/ui.svelte.ts carry nothing new.
Result (brotli KB, entry chunk = first paint): dev 239.517; this PR before 242.147 (over); this PR now 239.943 (under 240, +0.43 over dev). Everything else in the table is ok. The one line the gate still reports is the new chunk name: web.bundle.chunk.attachments (3.088 KB) needs a budget line (I used "p95": 3.25, "initial": false to see it green, not committed since perf/budgets.json is #866's), and total_js_brotli must then equal the new sum of chunk budgets (the measured total, 354.7 KB, is far under the 404.2 limit).
Notes: entry size moves ±100 bytes with chunk-file hashes embedded in it, so the margin is about 60 bytes; moving this PR's stylesheet into the chunk made the entry bigger (the chunk's CSS dependency is listed in the entry), so it stays in the first-paint CSS (first_css is under its limit). Behaviour is unchanged: pictures.spec + bar-stable + phone-bars + editor/links/picker specs pass on Chromium and WebKit at 390 and 1440 (250 each for the pictures set); editor 517 / web 86 unit tests, tsc and svelte-check clean.

port: attachments, slice 1 of 3 (images) · stacked: #1 → 2 → 3

Today a note cannot hold a picture. This adds it: Attach → Photos / Camera / File, drop and paste on the text, an inline picture in the mockup's width, and a viewer on tap. Mockup: review/calendar-2 (blocks/plugins/media.ts, embeds.css, the Attach menu), approved G11/G12, #471/#172.

What it does

Upload through the existing POST /api/v1/attachments?name=&date=. The note gets its line only after the server answers, so the markdown never points at a missing file.
On disk (ADR 0024, nothing invented): ![name](<../Photos/YYYY/YYYY-MM-DD/name.png>) alone on a line. The same bytes twice: the server's dedupe returns the existing path ("Already uploaded"), the line reuses it.
Display (packages/editor/src/syntax/embeds.ts): a line that is only an embed link becomes one atomic piece in default mode; anywhere else (words on the line, web image, code, list, quote) it stays text. The editor asks the app for the address and size through a facet, like links.
Gaps fixed (review feedback): the line has no text height of its own and CodeMirror's empty buffer boxes are gone (.cm-embed-line: line-height:0; font-size:0), so a picture has the same room around it as a paragraph (asserted in the spec: gap ≤ paragraph gap).
Attach menu (review feedback): the app's one in-place menu (ContextMenu), now with an up placement: it grows out of the Attach button's top edge, centred, from a bar at the foot of the screen. Photos and File everywhere; Camera only on a coarse pointer (touch).
Sizes on disk, so the first view never shifts (review feedback): new action attachments.meta (crates/attachments/src/meta.rs): for up to 200 paths in the caller's Home it reads, from the files themselves (same rules as serving: servable shelves only, opened strictly inside the Home, type from content), the size, type, shelf and a picture's width/height from its header (and a PDF's page count, best effort, ≤8 MB). Nothing is stored. The web asks in batches as soon as a note's text is known (peek), a first view waits at most 250 ms for the answer (once per picture on a device, never for notes without pictures), and sizes are remembered on the device. Rust test meta_gives_a_pictures_size_and_skips_what_is_not_servable (a known picture, a missing file, a note path and a .. path). contracts/actions.json and actions.gen.ts regenerated.
Viewer (lazy chunk): grows out of the tapped box and back; Esc, tap or ✕ closes; reduced motion fades. It takes Esc only while a picture is open.
Insert grid: Image and File tiles work (they said "Comes with attachments").

phone-bars limit (review feedback)

The earlier NOTE_PHOTO.chromium 15.7 → 16.0 bump is reverted. Cause: the note tools gained Attach, and rows() took the median of a pixel row that runs through the app's own floating bar, so the bar's width decided the median. The spec now measures that row beside the bar (the bar's own columns left out), and the original 15.7 / 7.8 limits hold unchanged on Chromium and WebKit.

Gates (dev-01 Chromium, dev-02 WebKit, `CI=1 --retries=0`, `~/bin/slot`; head `8643313b`)

editor vitest run 517 pass, tsc --noEmit ok; web vitest run 86 pass; svelte-check 0 errors; cargo test -p calternal-attachments 21 pass; cargo test -p calternal contract ok.
e2e/pictures.spec.ts (4 tests: Attach→Photos + viewer, paste + reload without a jump, same picture twice + source mode, first-frame shape + spacing) + bar-stable + phone-bars, chromium-1440/390: 250 pass; webkit-1440/390: 250 pass (one earlier full WebKit run had 3 intermittent failures in the pictures spec under load; rerun 24/24 and the full set 250/250).
Round trip: the text is never rewritten (unit test: document byte-identical; spec reads the file on the server).

Perf (dev VM, indicative; perf-VM harness not run)

Bundle gz vs dev: first paint +3.3 KB, all +4.7 KB (this slice). Whole stack:

gz bytes	first paint (entry)	all JS+CSS
`dev`	314,236	460,562
slice 1	317,511 (+3.3 KB)	465,238 (+4.7 KB)
slice 2	323,395 (+9.2 KB)	471,534 (+11.0 KB)
slice 3	327,810 (+13.6 KB)	476,079 (+15.5 KB)

Note with 20 paragraphs + 20 × 1200×800 noise PNGs vs 20 paragraphs alone (Chromium 1440, slice 3 head): ready 277–370 vs 270–503 ms, text visible 293–522 vs 283–518 ms, 5 keys typed right after open 255–303 vs 268–277 ms, long tasks 0 vs 0–187 ms, CLS 0.0008–0.0021 vs 0.0016–0.0018; only the 2 on-screen images load (lazy, decoding=async).

Screenshots

Control host: ~/Developer/Worktrees/shots/port-attachments/ (product-* ↔ mockup-*, 1440x900 and 390x844).

Not in this slice

Everything in #2 and #3 (name strip's editing, galleries, files, players, note embeds, mini bar).

🤖 Generated with Claude Code

Budget (kayg approved, 2026-11-08 08:20 IST): kayg approved raising the lazy budget total, up to 543.9 KiB. perf/budgets.json in this PR sets each named lazy line to the largest size measured over the 17 approved ports after trimming (rounded up to 0.01 KiB) and the total to the sum of the lines (543.25 KiB). The same file is in the first PR of every stack, so whichever merges first carries it. First paint is judged separately and has not been raised.

### Update: first-paint budget (#866) `perf/web.sh --bundle-only --gate` (from `perf/budgets-per-app`, #866, `PERF_DIST` = this branch's build with #866's vite config) first said **first_js_brotli 242.147 KB > 240**. The picture widget and the attach code are now out of the entry chunk: - **`attachments` lazy chunk** (3.09 KB brotli): add/paste/drop (`attach.ts`, `upload.ts`, one page listener for pasted/dropped files), the sizes the server knows (`meta.ts`), the picture widget class, the viewer's opener, the sizes cache. Loaded when a note with a picture opens, when someone first uses Attach or the Insert grid's Image/File, and once the app is idle after the first paint (like the other lazy screens), so a pasted file is taken at once. - **Entry keeps** only: a `imageWidget` facet and a check in `hidden.ts` that hands a line's text to the app (it draws nothing until the chunk is here), the 60-line shim `lib/attachments/lazy.ts` (`load`, `widget`, `pictures`, `attachMenu`), the Attach button, a paperclip icon path, and the wait for the chunk and the sizes before a note with pictures draws (so its boxes have their final shape and nothing jumps). - The camera icon's path comes with the chunk (`addIcon`); the viewer's state lives in `PictureViewer.svelte`'s module script and the chunk mounts it itself; the "menu from a button at the foot of the screen opens above it" placement moved into `ContextMenu` (already lazy), so `menu.ts`/`ui.svelte.ts` carry nothing new. - **Result** (brotli KB, entry chunk = first paint): `dev` 239.517; this PR before **242.147** (over); this PR now **239.943** (under 240, +0.43 over `dev`). Everything else in the table is `ok`. The one line the gate still reports is the **new chunk name**: `web.bundle.chunk.attachments` (3.088 KB) needs a budget line (I used `"p95": 3.25, "initial": false` to see it green, not committed since `perf/budgets.json` is #866's), and `total_js_brotli` must then equal the new sum of chunk budgets (the measured total, 354.7 KB, is far under the 404.2 limit). - Notes: entry size moves ±100 bytes with chunk-file hashes embedded in it, so the margin is about 60 bytes; moving this PR's stylesheet into the chunk made the entry *bigger* (the chunk's CSS dependency is listed in the entry), so it stays in the first-paint CSS (first_css is under its limit). Behaviour is unchanged: `pictures.spec` + `bar-stable` + `phone-bars` + editor/links/picker specs pass on Chromium and WebKit at 390 and 1440 (250 each for the pictures set); editor 517 / web 86 unit tests, `tsc` and `svelte-check` clean. ## port: attachments, slice 1 of 3 (images) · stacked: #1 → 2 → 3 Today a note cannot hold a picture. This adds it: **Attach → Photos / Camera / File**, drop and paste on the text, an inline picture in the mockup's width, and a viewer on tap. Mockup: review/calendar-2 (`blocks/plugins/media.ts`, `embeds.css`, the Attach menu), approved G11/G12, #471/#172. ### What it does - **Upload** through the existing `POST /api/v1/attachments?name=&date=`. The note gets its line only after the server answers, so the markdown never points at a missing file. - **On disk** (ADR 0024, nothing invented): `![name](<../Photos/YYYY/YYYY-MM-DD/name.png>)` alone on a line. The same bytes twice: the server's dedupe returns the existing path ("Already uploaded"), the line reuses it. - **Display** (`packages/editor/src/syntax/embeds.ts`): a line that is only an embed link becomes one atomic piece in default mode; anywhere else (words on the line, web image, code, list, quote) it stays text. The editor asks the app for the address and size through a facet, like links. - **Gaps fixed** (review feedback): the line has no text height of its own and CodeMirror's empty buffer boxes are gone (`.cm-embed-line`: `line-height:0; font-size:0`), so a picture has the same room around it as a paragraph (asserted in the spec: gap ≤ paragraph gap). - **Attach menu** (review feedback): the app's one in-place menu (`ContextMenu`), now with an `up` placement: it grows out of the Attach button's top edge, centred, from a bar at the foot of the screen. Photos and File everywhere; Camera only on a coarse pointer (touch). - **Sizes on disk, so the first view never shifts** (review feedback): new action **`attachments.meta`** (`crates/attachments/src/meta.rs`): for up to 200 paths in the caller's Home it reads, from the files themselves (same rules as serving: servable shelves only, opened strictly inside the Home, type from content), the size, type, shelf and a picture's width/height from its header (and a PDF's page count, best effort, ≤8 MB). Nothing is stored. The web asks in batches as soon as a note's text is known (`peek`), a first view waits at most 250 ms for the answer (once per picture on a device, never for notes without pictures), and sizes are remembered on the device. Rust test `meta_gives_a_pictures_size_and_skips_what_is_not_servable` (a known picture, a missing file, a note path and a `..` path). `contracts/actions.json` and `actions.gen.ts` regenerated. - **Viewer** (lazy chunk): grows out of the tapped box and back; Esc, tap or ✕ closes; reduced motion fades. It takes Esc only while a picture is open. - Insert grid: Image and File tiles work (they said "Comes with attachments"). ### phone-bars limit (review feedback) The earlier `NOTE_PHOTO.chromium` 15.7 → 16.0 bump is **reverted**. Cause: the note tools gained Attach, and `rows()` took the median of a pixel row that runs *through* the app's own floating bar, so the bar's width decided the median. The spec now measures that row beside the bar (the bar's own columns left out), and the original 15.7 / 7.8 limits hold unchanged on Chromium and WebKit. ### Gates (dev-01 Chromium, dev-02 WebKit, `CI=1 --retries=0`, `~/bin/slot`; head `8643313b`) - editor `vitest run` 517 pass, `tsc --noEmit` ok; web `vitest run` 86 pass; `svelte-check` 0 errors; `cargo test -p calternal-attachments` 21 pass; `cargo test -p calternal contract` ok. - `e2e/pictures.spec.ts` (4 tests: Attach→Photos + viewer, paste + reload without a jump, same picture twice + source mode, first-frame shape + spacing) + `bar-stable` + `phone-bars`, chromium-1440/390: 250 pass; webkit-1440/390: 250 pass (one earlier full WebKit run had 3 intermittent failures in the pictures spec under load; rerun 24/24 and the full set 250/250). - Round trip: the text is never rewritten (unit test: document byte-identical; spec reads the file on the server). ### Perf (dev VM, indicative; perf-VM harness not run) Bundle gz vs `dev`: first paint +3.3 KB, all +4.7 KB (this slice). Whole stack: | gz bytes | first paint (entry) | all JS+CSS | |---|---|---| | `dev` | 314,236 | 460,562 | | slice 1 | 317,511 (+3.3 KB) | 465,238 (+4.7 KB) | | slice 2 | 323,395 (+9.2 KB) | 471,534 (+11.0 KB) | | slice 3 | 327,810 (+13.6 KB) | 476,079 (+15.5 KB) | Note with 20 paragraphs + 20 × 1200×800 noise PNGs vs 20 paragraphs alone (Chromium 1440, slice 3 head): ready 277–370 vs 270–503 ms, text visible 293–522 vs 283–518 ms, 5 keys typed right after open 255–303 vs 268–277 ms, long tasks 0 vs 0–187 ms, CLS 0.0008–0.0021 vs 0.0016–0.0018; only the 2 on-screen images load (lazy, `decoding=async`). ### Screenshots Control host: `~/Developer/Worktrees/shots/port-attachments/` (`product-*` ↔ `mockup-*`, 1440x900 and 390x844). ### Not in this slice Everything in #2 and #3 (name strip's editing, galleries, files, players, note embeds, mini bar). 🤖 Generated with [Claude Code](https://claude.com/claude-code) **Budget (kayg approved, 2026-11-08 08:20 IST):** kayg approved raising the lazy budget total, up to 543.9 KiB. `perf/budgets.json` in this PR sets each named lazy line to the largest size measured over the 17 approved ports after trimming (rounded up to 0.01 KiB) and the total to the sum of the lines (543.25 KiB). The same file is in the first PR of every stack, so whichever merges first carries it. First paint is judged separately and has not been raised.

kayg added 15 commits

2026-11-02 09:34:49 +00:00

port: attachments slice 1 - pictures in notes (Attach menu, drop, paste, inline image, viewer) 225488efdf

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

port: attachments e2e spec 29c1ff5f46

viewer: silence a11y lint (Esc and the close button are the keyboard path) b21403cd3c

e2e: reach Attach in the bar 29ca9e73a1

e2e: unique picture bytes per test 30642f5db3

e2e: focus the text so the note tools show 11fe409954

e2e: assert paste layout 5b90e39446

attach: one blank line around an inserted picture c1995cbd02

pictures: remember sizes on pagehide; e2e: phone has no focus step 2a4c591469

wip-debug 706d3a3716

e2e: phone attaches with the keyboard down 4dc39b7e06

e2e: tools up before Show markdown faad2615aa

viewer: take Esc only while a picture is open 262ab4ad99

phone-bars: note-photo band follows the wider note tools (Attach) 28550b47aa

pictures: tighter margins, the blank lines are the room

CI / server (pull_request) Has been cancelled

Details

CI / rust (pull_request) Has been cancelled

Details

CI / web (pull_request) Has been cancelled

Details

Markdown extraction contract / markdown-native-contract (pull_request) Has been cancelled

Details

Markdown extraction contract / markdown-editor-contract (pull_request) Has been cancelled

Details

fa35776783

exit	command
0	`cargo fmt -p calternal-attachments -- --check`
0	`cargo check -j4 --locked -p calternal-attachments --all-targets`
0	`cargo clippy -j4 --locked -p calternal-attachments --all-targets -- -D warnings`
0	`cargo test -j4 --locked -p calternal-attachments`

Rows
Columns

port: attachments (approved mockup) 1/3: images #846

Update: first-paint budget (#866)

port: attachments, slice 1 of 3 (images) · stacked: #1 → 2 → 3

What it does

phone-bars limit (review feedback)

Gates (dev-01 Chromium, dev-02 WebKit, CI=1 --retries=0, ~/bin/slot; head 8643313b)

Perf (dev VM, indicative; perf-VM harness not run)

Screenshots

Not in this slice

READY FOR MERGE: attachments 1, pictures (head 2dfcb618d)

Checkout

Merge

Gates (dev-01 Chromium, dev-02 WebKit, `CI=1 --retries=0`, `~/bin/slot`; head `8643313b`)

READY FOR MERGE: attachments 1, pictures (head `2dfcb618d`)