docs(product): spec Phase L L5 — dock-panel button refinements

Top-toolbar overflow menu for rare capture variants; short button faces + full-name tooltips (drop ReaSampler: prefix); Item/Track x Arrange/Design tag buttons enabled only for the opposite of active mode; remove redundant Toggle; semantic-grouping spacing. Item-level tagging confirmed existing — layout wiring, not feature work. Ungated; sequences after L4; L3 gate intact.

CONTEXT.md

@@ -1558,6 +1558,95 @@ surfaces' hit-testing. The L1 kit draws; the geometry stays pure. **L4 resolves
 against the post-palette-revision `bank_panel`** (build-time inventory once that branch is on
 dev).
 
+## L5 dock-panel button refinements (overflow menu · faces+tooltips · opposite-mode tags · Toggle removal · grouping)
+
+L5 is a **third refinement pass over the same `bank_panel` toolbars L4 built** — it re-homes
+and re-labels buttons for legibility; it **ships no new action and changes no capture/placement
+behavior** (every button fires an existing registered action; "capture ≠ placement" is
+untouched — the buttons only *fire* the split acts). **Ungated by Phase S** (the dock panel is
+on dev) and **independent of the L3 gate.** Drawn through the L1 kit in the DS-2 grey-neutral +
+three-accent-pastel palette (prune stays `warn`); **no palette or font decision is re-opened.**
+L5 sequences AFTER L4 (both rework the same `bank_panel` toolbars).
+
+**1. Top-toolbar overflow menu.** The three less-frequent capture variants — **Batch Items,
+Batch Razor, Capture RT** — leave the visible top bar for a **right-anchored "⋯ / More" menu
+button** (kit-drawn button; on click a `TrackPopupMenu` popup lists the three, each entry
+firing its existing command id via `Main_OnCommand`). The frequent acts stay on the bar:
+Capture Item, Capture Track (Capture); Insert, Insert Conform (Placement); Re-capture,
+Cancel RT (Maintenance). The menu button's rect + hit-test is **pure** (extend/mirror
+`action_bar` / `prune_button`); the popup + dispatch is shell. The menu entries reuse the same
+`resolveBarCommandId` path the bar buttons use, so a keybinding and a menu pick fire identically.
+
+**2. Short faces + full-name tooltips (drop the `ReaSampler:` prefix).** Button *faces* carry
+the terse `ActionBarRow.shortLabel` (already the case since L4) — L5 formalizes the face set and
+adds a **hover tooltip showing the FULL action name with the `ReaSampler:` display prefix
+stripped.** Note the prefix (`actionDisplayPrefix()`) is baked into the *registered gaccel
+action name*, not the button face — so the tooltip derives the full name and strips the prefix
+for display; the button face never carried the prefix. The keybinding stays on the existing
+`micro` sub-row. **Tooltip mechanism is a build-time choice (staff-engineer):** SWELL's tooltip
+control vs. a custom hover-delay kit tooltip. **Recommended: a custom hover-delay kit tooltip** —
+it owns its own hover timer + LICE overlay draw, stays inside the L1 kit (DS-1 "keep drawing in
+the kit"), and avoids attaching a SWELL tooltip control to non-child LICE rects (awkward for
+dynamically-tiled buttons). The hover-timer threshold + overlay draw are the only DAW-bound
+pieces; the "which button, what text" decision stays pure.
+
+**3. Bottom-toolbar Item/Track × Arrange/Design tag buttons, opposite-mode-only.** The current
+`Tag Design` / `Untag` pair is replaced by **four buttons — "Item: Arrange", "Item: Design",
+"Track: Arrange", "Track: Design"** — in the Tagging cluster. **Both action families already
+exist in the model + actions layer** (research-confirmed): the *track* family is
+`doTag`/`doUntag` on the track selection (`VIEW_TAG_DESIGN` and `VIEW_TAG_ARRANGE`, where
+Tag→Arrange == untag); the *item* family is `doMoveItems` on the item selection
+(`VIEW_MOVE_ITEMS_DESIGN` / `VIEW_MOVE_ITEMS_ARRANGE`, driving `planItemRetag` + lane minting).
+**So the four buttons are layout + enablement wiring over existing actions — NOT new feature
+work; no `view_mode_model` / `view` / `actions` change is required.**
+
+**Enablement rule (precise).** Let `active` = `view().activeModeId()` (the SAME read the footer
+`[Arrange|Design]` toggle uses — one source of truth). A tag button's *target mode* is the mode
+in its label (Arrange or Design). A button is **live iff target ≠ active**; otherwise it is
+drawn `Disabled` (kit `InteractionState::Disabled`, `Role::TextDim`) and its click is a no-op.
+Concretely:
+- **Design active** → `Item: Arrange` and `Track: Arrange` are live (they send the selection to
+  Arrange); `Item: Design` and `Track: Design` are disabled (the selection is already there).
+- **Arrange active** → the reverse: the `…: Design` buttons are live; the `…: Arrange` buttons
+  are disabled.
+The disabled predicate is **pure** (active mode → per-button live/disabled, unit-tested); the
+shell reads the active mode once per draw and applies it. Item buttons act on the current media-
+item selection; Track buttons act on the current track selection — matching the existing action
+bodies exactly (no selection semantics change).
+
+**4. Toggle button removed.** `VIEW_TOGGLE_MODE` leaves the bottom toolbar — the footer's
+`[Arrange|Design]` toggle (L4) already covers mode switching. **The action stays registered**
+(keybinding-bound, FOREVER-STABLE id unchanged); only its *button home* is removed.
+
+**Fate of Activate-Arrange / Activate-Design / Show-Both (FORK — Daniel's call).** These three
+`Switching`-cluster buttons overlap the footer toggle to varying degrees:
+- `VIEW_ACTIVATE_ARRANGE` / `VIEW_ACTIVATE_DESIGN` — **direct** mode jumps. With the footer
+  toggle present, they are largely redundant on the bar (the toggle *is* an Arrange/Design
+  switch). **Recommendation: DROP both from the bottom toolbar** (actions stay registered), so
+  the footer toggle is the single mode-switch affordance and the bottom bar is tagging-only.
+- `VIEW_SHOW_BOTH` — the cross-mode "pin visible in every mode" escape hatch. It is **not**
+  covered by the footer toggle (it is a per-track pin, not a mode switch). **Recommendation:
+  KEEP it** — as a lone button, or folded into a small `⋯` bottom-bar menu alongside any other
+  rare view verbs.
+- **Recommended final bottom-toolbar inventory:** `[ Item: Arrange | Item: Design ] · [ Track:
+  Arrange | Track: Design ]  ⟩⟩  [ Show Both ]` — Tagging cluster (four opposite-mode buttons)
+  set apart from a lone `Show Both`. No Toggle, no Activate-Arrange/Design (footer toggle owns
+  switching). **Daniel decides whether to keep Activate-Arrange/Design as bar buttons and
+  whether Show-Both stays a button or moves to a menu.**
+
+**5. Semantic-grouping spacing.** L4's `kBarSpec` is `buttonGap=4` / `clusterGap=16` (4:1). With
+the bottom bar's cluster boundary now more meaningful (four tag buttons vs. the `Show Both`
+remnant) the grouping should read at a glance — **widen the inter-cluster gap: start ≈
+`clusterGap=24` / `buttonGap=4` (6:1), tuned in-DAW.** One `kBarSpec` still serves both
+toolbars (identical button shape top and bottom); only the gap ratio changes.
+
+**Pure/shell discipline (unchanged).** All new geometry — the top-bar overflow menu-button rect
++ hit-test, the opposite-mode enablement predicate, the wider grouping spacing — goes in pure
+CTest-covered modules (extend/mirror `action_bar` / `prune_button`; add a pure enablement
+predicate). The `TrackPopupMenu` popup, the `Main_OnCommand` dispatch, and the tooltip hover-
+timer + LICE overlay draw are the only DAW-bound pieces; the L1 kit draws. **L5 resolves its
+menu/tooltip/action-id specifics against the landed L4 `bank_panel`** (build-time confirmation).
+
 ## The L3 gate + Phase S coordination contract
 
 **L3 (VST editor + embed-strip restyle) is GATED on Phase S landing on dev.** The VST
@@ -1566,7 +1655,9 @@ Phase S, which is **not on dev yet** (it exists on the phase-s worktree). L3 can
 built on dev until Phase S's editor/embed surfaces (≈ S1 / S6 / S10) merge to dev — **the
 Phase L team must not chase these files on dev; they are not there.** Until then L3 is a
 planned, blocked point; L1, L2, and **L4 (dock-panel button layout enhancement) have all
-landed**. L4 is independent of the L3 gate.
+landed**. L4 is independent of the L3 gate. **L5 (dock-panel button refinements — §L5 above)
+is the live forward Phase L point**: ungated by Phase S, sequences after L4, also independent
+of the L3 gate.
 
 **Coordination contract (load-bearing):** Phase S's S10–S13 build their interaction UX with
 the **current** drawing and **adopt the L1 kit when it is available — they are NOT gated on

PLAN.md

@@ -291,7 +291,10 @@ build:** the `IReaperUIEmbedInterface` contract + embed message/lifecycle agains
 > inventory placed by task cluster, `bank_panel` redesigned through the L1 kit (L2); three-zone
 > layout (top capture/placement/maintenance toolbar, bottom Design-View toolbar, footer toggle +
 > Tail button + Prune), `footer_bar` pure module, `ActionCluster::Tagging`/`Switching` in
-> `action_bar` (L4). See `COMPLETED.md`. **L3 remains** — L3 gated on Phase S landing on dev.
+> `action_bar` (L4). See `COMPLETED.md`. **L5 (dock-panel button refinements — overflow menu,
+short-face+tooltip labels, opposite-mode Item/Track tag buttons, Toggle removal, grouping
+spacing) is the live forward point** — ungated by Phase S, sequences after L4. **L3 remains** —
+L3 gated on Phase S landing on dev.
 >
 > **This section is self-contained for a team without Phase S context.** Where a point
 > touches a Phase S surface (the VST editor, the embed strip, the keyboard strip), the
@@ -368,15 +371,101 @@ work.
   state — never a pulse, per the speed constraint) as the signature surface; VST3 class UID
   unchanged. (Gated.)
 
+## L5 — dock-panel button refinements (ungated; sequences after L4)
+**Goal:** Refine the L4 three-zone toolbar so the button faces read cleanly and group
+legibly — an overflow menu for the rare capture variants, short faces with full-name
+tooltips (no `ReaSampler:` prefix), an opposite-mode tag-button set, removal of the now-
+redundant Toggle, and semantic-grouping spacing. **No new capture/placement behavior**;
+every button fires an existing registered action (the "capture ≠ placement" principle is
+untouched). **Ungated by Phase S** (the dock panel is on dev) and **independent of the L3
+gate.** Drawn through the L1 kit in the DS-2 grey-neutral + three-accent-pastel palette
+(prune stays `warn`); **no palette or font decision is re-opened here.** Authoritative
+contract: CONTEXT.md §L5.
+
+**The five refinements:**
+
+1. **Top-toolbar overflow menu.** The three less-frequent capture variants — **Batch Items,
+   Batch Razor, Capture RT** — move OFF the visible top bar into a **"⋯ / More" menu button
+   at the far right of the top toolbar** (a REAPER `TrackPopupMenu` popup listing the three,
+   each firing its existing command id). The frequent acts stay on the bar: **Capture Item,
+   Capture Track** (Capture), **Insert, Insert Conform** (Placement), **Re-capture, Cancel RT**
+   (Maintenance). This is a re-home of existing rows into a menu — no action changes.
+
+2. **Short faces + full-name tooltips; drop the `ReaSampler:` prefix.** Button *faces*
+   already carry a terse label (`ActionBarRow.shortLabel`) — this formalizes them and adds a
+   **hover tooltip carrying the FULL action name** (without the `ReaSampler:` display prefix,
+   which `actionDisplayPrefix()` bakes into the registered gaccel name — the tooltip strips
+   it). The keybinding stays on the existing `micro` sub-row. Tooltip *mechanism* is an
+   implementation choice flagged for staff-engineer (see the sub-item below).
+
+3. **Bottom-toolbar tag buttons — Item/Track × Arrange/Design, opposite-mode-only.** Replace
+   the current `Tag Design` / `Untag` pair with **four buttons: "Item: Arrange", "Item:
+   Design", "Track: Arrange", "Track: Design".** Each is **live only for the OPPOSITE of the
+   active mode** and drawn `Disabled` otherwise: when **Design is active**, only the "…:
+   Arrange" buttons are live (they send the selection to Arrange) and the "…: Design" buttons
+   are disabled; when **Arrange is active**, the reverse. Item buttons fire the existing
+   item-move actions (`VIEW_MOVE_ITEMS_ARRANGE` / a Design item-move); Track buttons fire the
+   existing track-tag actions (`VIEW_TAG_ARRANGE` (= untag) / `VIEW_TAG_DESIGN`). **Both action
+   families already exist** (research confirmed) — this is layout + enablement wiring, not new
+   feature work.
+
+4. **Remove the redundant Toggle button.** `VIEW_TOGGLE_MODE` leaves the bottom toolbar — the
+   footer's `[Arrange|Design]` toggle switch (landed in L4) already covers it. The action stays
+   registered (keybinding-bound); only its button home is removed. **Fate of Activate-Arrange /
+   Activate-Design / Show-Both is a FORK for Daniel** (see below) — recommended resolution
+   captured in CONTEXT.md §L5.
+
+5. **Semantic-grouping spacing.** Inter-cluster gaps must read visibly wider than intra-cluster
+   gaps so clusters parse as groups. Current `kBarSpec` is `buttonGap=4` / `clusterGap=16`
+   (a 4:1 ratio). With the bottom bar's cluster boundaries now more meaningful (four tag
+   buttons vs. the switching remnant), widen the ratio if the groups still don't read — target
+   ≈ `buttonGap=4` / `clusterGap=24` (6:1) as the starting point, tuned in-DAW.
+
+**Verify (in DAW):** the top bar shows only frequent capture/placement/maintenance buttons +
+a right-anchored More menu that fires Batch Items / Batch Razor / Capture RT; button faces
+are short with no `ReaSampler:` prefix and a hover tooltip shows the full action name; the
+bottom bar shows four Item/Track × Arrange/Design tag buttons with only the opposite-mode
+pair live (disabled pair visibly greyed via the kit `Disabled` state) and no Toggle button;
+cluster groups read as groups. All buttons fire the same actions their keybindings do.
+
+**Depends on:** L1 (the kit — `Disabled` interaction state, `kitText`) **AND** L4 (the
+`action_bar` two-toolbar + `footer_bar` layout this refines). **Sequences after L4.** Ungated
+by Phase S; independent of the L3 gate.
+
+- [ ] Top-toolbar overflow: pull Batch Items / Batch Razor / Capture RT off the visible bar
+  into a right-anchored **More menu button** (kit-drawn button + `TrackPopupMenu` popup);
+  each entry fires its existing command id. Pure layout owns the menu-button rect + hit-test
+  (extend/mirror `action_bar` / `prune_button`); the popup + dispatch is shell.
+- [ ] Short faces + drop `ReaSampler:` prefix on the button *face*; keep the keybinding micro
+  sub-row. Define/confirm the terse face label per button.
+- [ ] **Hover tooltip carrying the full action name (prefix stripped).** *Mechanism is a
+  build-time choice for staff-engineer* — SWELL tooltip API vs. a custom hover-delay kit
+  tooltip draw. **Recommend: a custom hover-delay kit tooltip** (owns its own timing + draw,
+  consistent with the LICE kit and DS-1's "keep drawing in the kit"; SWELL's tooltip control
+  is awkward to attach to non-child LICE rects). Final call at build.
+- [ ] Bottom-toolbar four tag buttons: **Item: Arrange / Item: Design / Track: Arrange /
+  Track: Design**, wired to the existing item-move + track-tag actions (no new actions).
+- [ ] **Opposite-mode enablement rule:** a button is live iff its target mode ≠ the active
+  mode; otherwise drawn `Disabled` (kit disabled state, `TextDim`) and its click is a no-op.
+  Pure predicate (active mode → per-button live/disabled) unit-tested; shell reads the active
+  mode and applies. (Layout over existing actions — NOT flagged feature work; item-level
+  tagging already exists in the model.)
+- [ ] Remove the `VIEW_TOGGLE_MODE` button from the bottom toolbar (action stays registered).
+- [ ] Resolve the **Activate-Arrange / Activate-Design / Show-Both** fate per Daniel's call
+  (FORK — see §Handoff / CONTEXT.md §L5); apply the chosen bottom-toolbar inventory.
+- [ ] Semantic-grouping spacing: widen `clusterGap` relative to `buttonGap` so clusters read
+  as groups (start ≈ 24 / 4; tune in-DAW).
+
 ## Phase L — sequencing
 ```
 L1 (shared kit) ──► L2 (dock-panel layout redesign) [LANDED]
         ├─────────► L3 (VST editor + embed-strip restyle; GATED on Phase S landing on dev)
         └─────────► L4 (dock-panel button layout enhancement) [LANDED]
+                            └────► L5 (dock-panel button refinements; ungated, after L4)
 
 Phase S (separate team, ungated): S-work builds with current drawing, adopts L1 when it lands.
 ```
-L1, L2, and L4 have landed. L3 waits for Phase S to reach dev.
+L1, L2, and L4 have landed. L5 sequences after L4 (ungated). L3 waits for Phase S to reach dev.
 Phase S feature work runs in parallel, ungated by Phase L.
 
 ## Phase L — must-verify-before-build
@@ -397,6 +486,14 @@ Phase S feature work runs in parallel, ungated by Phase L.
 - **L4 re-home surface (L4)** — resolved at L4 build: three-zone layout confirmed against the
   post-palette-revision `bank_panel`; `action_bar` extended with `ActionCluster::Tagging` +
   `Switching`; new pure `footer_bar` module covers footer layout/hit-test.
+- **L5 refinement surface (L5)** — resolve at L5 build: (a) confirm `TrackPopupMenu` popup +
+  right-anchored menu-button geometry for the top-bar overflow; (b) **tooltip mechanism**
+  (SWELL tooltip vs. custom hover-delay kit tooltip — recommended custom) — pick and confirm
+  the hover-timer + LICE overlay draw at build; (c) confirm the item-move action ids the four
+  tag buttons fire (`VIEW_MOVE_ITEMS_ARRANGE` + the Design item-move; `VIEW_TAG_ARRANGE` /
+  `VIEW_TAG_DESIGN` for track) resolve on this channel; (d) confirm the active-mode read the
+  opposite-mode enablement predicate consumes is the same `view().activeModeId()` the footer
+  toggle reads (one source of truth for "which mode is active").
 
 ---