fix(shell): three VID-build-apps capture blockers — tile collision, truncated grants, icon 404s

[th3-br41n]

Unblocks the VID-build-apps shoot: three of the five polish rungs the capture dry-run filed (POLISH-LAY-6, -7, -8 in the harness plan). LAY-6 is the episode's payoff shot; LAY-8 was the only console-error source in the run. (POLISH-FN-1/FN-2 are a separate agent's app-side work; shell #367's demo-provider manifest fix is unrelated and untouched here.)

POLISH-LAY-6 — a newly installed app's tile landed ON TOP of Notes

Root cause — units vs cells. The renderer stores icon positions in 8px GRID_UNITs and paints an ICON_FOOTPRINT_W × ICON_FOOTPRINT_H (11×14 unit) box per icon — hence the captured fleet Notes@0,0 · Files@11,0 · Database@22,0 · … · Books@0,14. placeDashboardIcon scanned a fictional 12-column grid of 1×1 cells, so cell 1,0 looked free while Notes' box was sitting on it. Replaying the pre-fix scan against that exact fleet returns {col:1,row:0}, overlapping Notes — the reported symptom, reproduced before patching.

Fix — one placer, not two (shared helper). packages/shell/src/shared/dashboard-icon-grid.ts now owns the footprint constants, the overlap test and the first-free-slot scan (pure, no Electron/React — same posture as shared/locale-catalog.ts). The renderer's dashboard/grid.ts and main's dashboard/grid-placement.ts both build on it and re-export under their existing names, so no call site changed shape. Every install/pin path — marketplace, sideload, vault-source install, dev seeder, entity pin, Bin pin — computes its cell through it.

Same-family fix included: the Bin's shell-surface pin wrote {0,0} on the stale premise that "the dashboard's collision layer repositions onto the first free cell". Icon layout is free placement with no collision resolution, so pinning the Bin stacked it on whatever owned the origin. It now takes the first free slot like every other pin.

POLISH-LAY-7 — the grants popover ellipsised the scope

entities.read:brainstorm/Pro… — the panel that exists to answer "what can this app read?" truncated the only part that answers it. The row goes from 1fr auto auto to 1fr auto, stacking capability over "granted via" in one text column (the same shape as the app rows behind the popover — no new chrome), and the capability wraps with overflow-wrap: anywhere instead of ellipsising. It matters beyond the video: this is the surface that proves the sandbox claim.

POLISH-LAY-8 — brainstorm://app-icon/<id> 404s (×4)

Two sides, both root-cause:

• Handler. "Installed, declares no icon" is a normal state — every icon surface already draws a deterministic initials tile for it — so it now answers 204 instead of 404. An id that resolves to nothing installed still 404s, because that is worth surfacing. A declared-but-missing icon file resolves as no-icon too, rather than handing the caller a missing file:// to fetch (which surfaces as ERR_UNEXPECTED in the renderer — the trap the emoji handler already guards). Rules extracted from the 5k-line main/index.ts into a testable main/apps/app-icon-resolver.ts.
• Request side. resolveAppIconSrc has always answered null for a known icon-less app — but the running strip, the window switcher, widget headers and marketplace cards each hand-built their own brainstorm://app-icon/... URL and so opted out of it. They all go through the shared resolver now (it grew an optional epoch arg so the widget header keeps its F-380 re-install retry and gains the suppression). The URL builder moved to shared/app-icon-url.ts, shared by the preload bridge and the renderer — an icon URL is a string, not a privileged operation, so a renderer component no longer needs the whole preload bridge present to name one.

Tests

New / extended, all failing-first against the old behaviour where applicable:

• main/dashboard/grid-placement.test.ts — footprint-stepped placement, the exact captured fleet (asserts no overlap with any existing icon), wrap to the next row, an off-lattice user-dragged icon, hole-filling after an uninstall. The LAY-6 case is called out by name.
• main/dashboard/dashboard-store.test.ts — the install path end to end over the real DashboardStore: seeded fleet → install Client Pulse → install a second app, asserting no overlap with anything, plus the full-first-row wrap case.
• main/apps/app-icon-resolver.test.ts (new) — declared icon, subdirectory icon, no icon, empty/non-string icon, declared-but-missing file, bundle escape, containment of an absolute-looking path, no active bundle, unreadable/unparseable manifest, and the 204/404 status split.
• renderer/dashboard/app-icon-cache.test.ts — epoch appending and icon-less suppression through the epoch path.
• renderer/settings/grants-panel-layout.test.ts (new) — a CSS ratchet: the capability line may not carry text-overflow: ellipsis / white-space: nowrap, must wrap, and the row must keep its two-column shape.

bun run verify ✅ · bun run lint ✅ (all ratchets clean) · bun run typecheck ✅ (packages + per-app) · full bun run test ✅ 1640 files / 16340 tests.

Four-path evidence

• Screenshot — the two visible changes (tile placement, grants row) are re-verified by the VID-build-apps capture re-run this PR unblocks; the placement is additionally pinned numerically by the fleet-overlap tests (a screenshot can't assert "clears every footprint", these do), and the grants layout by the CSS ratchet.
• Keyboard — unchanged. No control was added, removed, reordered or re-parented: the grants row keeps exactly one focusable element (Revoke) in the same tab order; the Bin pin toggle, install flows and icon surfaces keep their existing bindings.
• Screen reader — unchanged and slightly better: the grants row's capability text is now fully wrapped rather than visually truncated (SR text was always complete; sighted parity is what improves), and no aria-*, role or accessible name changed anywhere in the diff. Icon changes are on aria-hidden artwork only.
• Discoverability — improves on two counts: a newly installed app's tile is now visible instead of hidden under an existing one, and an app's granted scopes are legible in the panel that exists to disclose them. Nothing became less reachable.

🤖 Generated with Claude Code