refactor(header): collapse the panel header by container width, not viewport

[tlgimenes]

Stacked on #5230 — review that one first; this PR is the two commits on top.

The problem, for anyone not on a big monitor

The panel header collapsed its controls on viewport media queries (lg, 1024px). But the header doesn't span the viewport — it lives inside one panel. So screen width tells you almost nothing about the room it actually has:

Situation	Screen	Main panel header
Chat closed	1074px	826px
Chat open	1180px	605px

That second row is the bug. At a 1180px screen the viewport rule says "plenty of room, show every label" — while the strip is actually 605px and out of space. The labels stayed full-width, the tab budget got squeezed, and view tabs fell into the ⋯ overflow menu earlier than they needed to.

It also meant the same screen behaved differently depending on where you dragged the splitter, which is impossible to reason about — and it's why this looked fine on a wide monitor and bad on a laptop.

Reported as: "the screen is 882px wide and I'm still seeing the chat and preview labels."

What changed

PanelHeader now declares @container/panel-header and every control inside queries its own panel's width:

Control	Collapses below	Was
Chat, system tabs (Preview/Code), Library, Tasks, CMS	768px of header	viewport 768px / none
Dynamic tabs (files, pinned views, expanded tools)	576px of header	viewport 768px
Branch pill, branch picker, Develop/Live, Publish	768px of header	viewport 1024px
Preview's URL group (CMS · refresh · page select · open-in-new-tab)	448px of header	JS measurement, ~668px

Two tiers rather than one, because the icon has to carry the button once the label goes. Chat/Preview/Code/Library/Tasks have fixed, distinctive icons and collapse first. Dynamic tabs can resolve to a generic fallback glyph (resolve-tab-icon.ts), so several open files would become mutually indistinguishable — they hold their text longest.

Small screens keep the Preview controls much longer: the old JS rule hid the whole URL group below ~668px of header; it now survives to 448px.

Tabs finally have tooltips

HeaderTabButton had no Tooltip at all, while its own docstring claimed "every button is wrapped in a Tooltip." Below md the tabs were already collapsing to bare icons — so on a small screen you got an unlabelled icon with nothing identifying it but aria-label. That's the part that actually hurt. Tooltips are now real, which is what makes collapsing labels safe in the first place.

preview.tsx wrapped one of these in its own Tooltip; that's replaced by a tooltip prop so the two don't nest.

Screenshots

1. 1440px, chat closed — header 1192px, everything labelled.
2. 1000px, chat closed — header ~752px, labels collapsed to icon + tooltip, page selector still there.
3. 1180px, chat open — header 605px. The point of the PR: a large screen where the panel is narrow, so the strip collapses. Under the old rule this showed full labels and ran out of room.

Trade-off worth a reviewer's opinion

The URL group's 448px cutoff is deliberately later than the old ~668px. Between roughly 448 and 530px the page selector has less than HEADER_W.middle (232px) and degrades toward a bare chevron instead of showing the page name — measured 220px at a 530px header, 150px at 460px.

That squish is the accepted cost of keeping the controls reachable on narrow panels; the old code hid them instead. Documented at the call site. Easy to move to 576px (@xl) if it reads badly in practice.

Dead code removed

headerLayout no longer returns showPageSelector — CSS owns that now, so keeping it would be dead. maxTabs stays in JS, because it changes which items render in the bar vs the overflow popover and CSS can't express that. Its tests were inverted rather than appended to, plus one asserting the field doesn't come back. HEADER_W.middle's docstring no longer claims to gate the centre's visibility.

Testing

• bun run check clean across all workspaces; bun run lint 0 errors; bun run fmt applied.
• 1029 unit tests pass (apps/web layouts, sandbox, chat).
• Verified in the running app by driving the container's inline size directly and sweeping the thresholds:

Forced header	Chat label	Centre group
820, 780	shown	visible (397, 379px)
767	collapsed	visible (361px)
700	collapsed	visible (361px)
530	collapsed	visible (220px — into the squish band)
460	collapsed	visible (150px)
447	collapsed	hidden

• Confirmed all four right-cluster components (BranchPill, BranchPicker, DevAgentControl, HeaderActions) render only inside a PanelHeader, so the container always resolves. Outside one the query finds no container and the label simply stays — the safe direction.
• Mobile (MobileTaskWorkspace) doesn't render the branch selector or publish actions at all; Preview's inline fallback bar declares the same container so its queries still work on that path.

Also in here: the CMS toggle gets its own icon

Edit05 was doing double duty as the new-chat affordance (task-groups-list.tsx, shell-breadcrumb.tsx) and the header's CMS toggle — two unrelated actions, one pencil-square. That collision matters more once the label collapses and the icon is the only thing identifying the button. Now PuzzlePiece01 (the page-builder "blocks" metaphor, unused elsewhere), applied to both entry points: the toolbar button and the ⋯ menu fallback.

🤖 Generated with Claude Code

---

Summary by cubic

Collapse the panel header by its own container width instead of the viewport to fix cramped layouts and inconsistent behavior when chat narrows the header. Adds tooltip-backed icon-only states and simplifies headerLayout to only manage tab count.

• Refactors

  • Switched all header controls to @container/panel-header; labels collapse by panel width with two tiers (Chat/system tabs/CMS and right actions at 768px; dynamic tabs at 576px). Preview’s URL group hides at 448px; the mobile inline toolbar declares the same container.
  • Simplified headerLayout to return { maxTabs } only; center visibility now uses a container query. Updated tests and docs.
  • Gave the CMS toggle a distinct icon (PuzzlePiece01) to avoid the pencil icon collision.

• Bug Fixes

  • Header now collapses based on actual panel width, preventing early tab overflow and inconsistent behavior across splitter positions.
  • Tabs finally have tooltips, so icon-only buttons are identifiable; preview uses the new tooltip prop to avoid nested tooltips.

^{Written for commit 41158c5. Summary will update on new commits.}