docs: record the transcript-scan and footprint measurements
Two measurements a future reader would otherwise re-break: the sidebar's
subagent badge used to parse every parent transcript (1,380 MB cold on a
1,349-file agent dir, 1,148 MB RSS after one console load) and now streams and
saves the verdict; and a Bun process's RSS is not the memory it uses (752 MB
RSS against a 70.6 MB physical footprint, with `Bun.gc(true)` moving nothing),
which is why the sweep and the health payload read the OS's footprint.
docs(composer): record why the stretched glass card is 92% paper
The 58% surface is a property of the DOCKED style, where there is nothing
behind it. Stretched over the transcript it has to win the overlap, and the
measurement that decided 92% belongs next to the rule so a future pass does not
"restore" the docked alpha across both states.
docs(sidebar): record the modern chrome's two density facts and the 32px rhythm
The phone drawer's folder band and its row height were both desktop values
carried to the touch density, so the page states the two numbers, why they are
density-dependent, and what was rejected:
- the sticky header paints the surface it sits on (`bg-paper` desktop,
`bg-canvas` drawer), measured as `rgb(250,248,243)` over `rgb(244,241,234)`;
- a touch row is 32px, the header's own `h-8`, reached by `py-0.5` around the
28px trailing action box — padding, not a fixed height, so a second line can
grow it; header, rows and skeleton are now one height;
- the 6px gap was tried and rejected, and the classic drawer's 2px is why.
Also corrects the skeleton's stale "32/44 touch" heights to 32/32.
docs(layout): record the SVG preview's definite-width requirement
A viewBox-only SVG draws at 0x0 unless something above it has a definite
width: the wrapper was a flex item (shrink-to-fit) and the picture's
default `width:100%` resolved against itself. Records the measurement
that made it visible — markup in the DOM, viewer kind correct, unit test
green, box 0x0 — and why only a browser can catch it, so the next viewer
gets a measured box assertion instead of a markup one.
docs(sidebar): record batch archive as the bar's reversible sibling
Notes why archive is session-only (a workspace has no archive state), why the
action row switches between a 2- and 3-column grid, why the route is idempotent
`INSERT OR IGNORE` with only the two structural refusals, and why there is no
confirmation dialog — plus the measured reason delete and archive keep separate
in-flight flags: a shared one printed `Deleting…` during an archive.
docs(settings): record the Chats grouping and its two totals
The category is a master/detail sidebar now, and the failure it prevents is a
section that exists but cannot be reached: the detail pane renders
`group.sections`, so a section missing from every group is invisible while its
file and unit tests still pass, and one listed twice renders twice. The
`Record<ChatSectionId, …>` plus `groups.test.ts` are what close both.
Records the phone measurement too (412x915: 398x53 rows, 410x849 detail, 26px
back bar, no horizontal overflow) and the modal's `p-0` list, which the pane
depends on for its own padding.
docs(chat): record the composer's five styles and the two bugs they exposed
`Chats › Composer` now picks classic | calm | console | stage | glass, and the
entry states the rule the implementation is built on: the style table names the
card's ROW ORDER, never a row's presence, because a style able to omit the
access-mode selector would be able to send a write-capable turn from a card that
said read-only.
Two measurements are recorded with their numbers rather than as conclusions:
- A style's radius written as a Tailwind class LOST to the expansion frame's
`rounded-xl` (measured 12px on console), because two utilities of one property
resolve by emission order. The style's pixels are plain CSS keyed by
`data-composer-style` for that reason.
- A plain-CSS radius then beat the frame's `rounded-none`, so a stretched phone
card kept its corners over `fixed inset-0` (glass 20px, console 6px). The card
now carries `data-composer-expanded` and one rule zeroes the radius; re-measured
docked 12/16/6/12/20px, stretched 0px for all five.
`glass` is documented as the one style that leaves the paper identity, including
why its reference render's coloured glow was dropped (chroma is reserved for
`--theme-error`) and why it needs an opaque `@supports` fallback.
docs(layout): record the sidebar's two chromes and their measured columns
The sidebar now has a `classic` and a `modern` chrome behind one setting, and
three of the rules that keep them consistent are the kind a future reader would
otherwise re-break silently: the icon, title and trailing columns are shared
between the workspace header and the rows numerically (4px inset, 16/18px slot,
8px before the text, a 22/28px trailing box 4px inside the content edge); the
filter row never wraps and only Select is right-aligned; and the modern skeleton
draws only the list, at the live row heights.
Each entry carries the measurement that produced it — the 4px/6px/9px gaps
between the header and the rows, the 265px of four chips against 256px of
content at the 280px default, and the two `ml-auto` mistakes that were tried
before Select became a sibling of the filter group.
Also corrects the sidebar's documented default from 268px to the 280px
`DEFAULT_LEFT_PANEL_WIDTH` that actually ships, and names the floor (264) and
ceiling (500).
docs(memory): record the byte budget and the canvas frame sink
Both entries carry the measurement that found the defect, so the next
reader can re-derive the numbers instead of trusting a constant.
The editor's cache was bounded by tab count alone, which is not a memory
bound: a text file's ceiling is 32 MiB, so twelve of them is up to 384 MB
of document text plus each tab's undo history. It now also holds an 8 MiB
budget, and the document being opened is never the one evicted.
The screencast handed every frame to an `<img>`; WebKit never releases the
decoded image behind a replaced `src` — measured at ~76 KB of WebContent
footprint per frame (148 MB for 1 760 frames) against 28 MB for the same
frames decoded to an ImageBitmap, drawn and closed.
docs(layout): record the chat column's width modes
One variable (`--chat-column-max`), one class (`chat-column`), one attribute
(`data-chat-width` on `<html>`): the fact that used to be an `max-w-[970px]`
literal at eight call sites. The page states the three widths, why `full`
widens the composer too, why the default is removed from the attribute rather
than written, why the overrides are `:root[data-chat-width=…]`, and why the
choice is global instead of per-session.
Codebase-Rules gets the one rule a future reader would otherwise re-break: a
width that belongs to the chat column is a READING width, not one of the
remembered panel widths — the chat is the layout's filler column, so it has no
px and no fraction to remember.
docs(editor): record the lint, conflict bands and hunk stepper
Three behaviours a future reader would otherwise re-break, each with the
measurement that settled it:
- `Decoration.line` returned from `MatchDecorator` is placed over the matched
range and rendered the marker lines as blank rows in a real browser, so the
conflict band is a viewport walk like `indent-guide.ts`.
- The lint parsers are 46 KB gzip together and load through literal `import()`;
a template specifier never resolves in the dev server.
- `getChunks` is a function that answers `null` without a merge extension, the
side decides which document a chunk offset means, and the package's own
`goToNextChunk` does not scroll a read-only reader.
docs(editor): record how line blame reads, caches and draws
Nine rules with their measurements, so the next reader does not re-derive them:
one whole-file `--porcelain` read per tab instead of one per hover (39 ms
average over 20 sequential spawns vs 30–110 ms once), the cache key carrying
mtime and HEAD because both change every answer, `runGit`'s 1 MiB default
buffer truncating a 1.7 MB payload silently, the dirty buffer hiding its labels
because line numbers moved, the gutter as the second hover target with its
listeners on the scroller rather than the content, and the state field fed by a
bridge plugin because replacing a plugin's decorations outside a transaction
leaves the DOM showing the previous set.
docs(shell): the sidebar opens a workspace that hides a live or new row
Records the auto-expand rule with its measurements: a collapsed `omptest`
with one `stream` row went `is_expanded 0 -> 1` and rendered its 75 rows
after a sidebar refresh, and "New session in general" wrote the same flag
before the chat was sent in. Also names why the write is edge-triggered per
session id (a tool call republishes the structure several times a minute)
and why the render-side force-open exists beside it (the row must be
visible on the frame the spinner appears).
docs: split the manual into a wiki