[IanMayo]

Implements the GramFrame_UI_Control_Panel handoff — turns 5a, 5b, 5c and 2a, which are the agreed design. Turns 1–4 are superseded explorations and are not implemented.

The plot area is unchanged: the gram, the axes and every overlay are drawn exactly as before.

The problem

Five bordered boxes of equal visual weight. Nothing in the panel was the first thing to read, per-mode guidance had nowhere permanent to live, and it was never clear whether the colour slider was setting the style of the next feature or restyling the one just clicked. This is about rank, not content — almost everything that was in the panel is still in it.

The five columns

#	Column	Module
1	Mode rail (154px)	components/ModeButtons.js
2	Guidance (264px, or a 40px rail)	components/GuidancePanel.js
3	Cursor readouts (210px)	components/CursorReadout.js
4	Style (222px)	components/StylePanel.js
5	Annotation tables (the rest)	components/AnnotationTables.js

• Mode rail — five tools stacked, each with a glyph beside its word, and the view controls (zoom out, zoom in, fit) in a footer beneath them where they stay whichever mode is armed: they act on the view, not on the armed tool. They used to sit inside Pan's row, which made one row of five four controls wide. Clear is not here.
• Guidance — permanent, immediately beside the rail. Each line splits into a trigger in a fixed 76px track and an outcome beside it, so a mode's four gestures compare down one column instead of being read out of four sentences. It collapses to a 40px rail, remembered per user. The preference is genuinely three-state (true/false/absent): with no stored choice the column decides by the panel's own width, via a container query rather than a viewport media query, because one page can carry a full-width gram and a half-width one.
• Cursor readouts — the panel's anchor and the only part styled as an instrument. Two targets, named by the kicker: the pointer, or the selected feature's own values. updateUniversalCursorReadouts stands aside while something is selected. No intensity legend — one was drawn and removed.
• Style panel with twin target tabs — state.styleTarget records whether the controls write the defaults or restyle the selection, and arming "New features" does not give up the selection, so an analyst can set what comes next while still nudging the row they are on. One gate, getSelectedFeature in the new core/featureStyle.js, decides, so the tab an analyst can see and what a colour click does cannot disagree. One colour control, not two. The symbol popup shows all seven marks at the size and colour they will take, and houses the temporary size trial. Marker labels are edited here, in a field beside the same marker's colour and symbol; the per-row dialog is deleted.
• Three annotation tables — count chips (hidden at zero) and instructional empty states. The selected row is reversed out whole rather than bordered: an accent border collided with the feature colours the rows themselves carry. Clear all annotations moved to the foot of the sidebands column — it removes annotations, not view state, and a destructive control among three view controls is one slip from an afternoon's work. It is offered on student pages too: "it will be gone tomorrow" is no answer to a student who has mislabelled a gram and wants to start the exercise again today.

Transport bar (5c)

Rebuilt to match, still below the gram, where the scrub track lines up with the time axis it refers to. Gains time bookmarks: Bookmark (or B) flags the playhead, each flag can be clicked to jump, and the "n saved" list removes them. They are playback chrome rather than annotation — a marker says what was measured and belongs to the gram, a bookmark says where to listen again and belongs to the sitting — so they live in memory for the life of the page and never reach the annotation store (asserted in tests/transport-bookmarks.spec.js). The volume slider is kept, though 5c does not draw it: dropping a shipped control would have been a quiet regression.

Follow-ups since the first pass

Four changes asked for once the redesign was on screen, plus one player fix.

• The view scrolls back to the very start of a recording. The top edge of the plot area is the playhead and drag-seek resumes from whatever time that edge shows, so a lower bound of one window made the opening seconds of every recording impossible to put under the playhead — visible at the bottom of the view, but unreachable by dragging. clampViewTop's floor is now 0, and Pan opts into off-image pointer delivery so the drag does not stall once the press point falls into the blank it is creating. The window below the start is blank, which is the same blankness the opening seconds already showed while the first window played.
• The cross-mode gestures appear in every mode. Wheel zoom and pan, the wheel-button drag and Shift + drag region zoom are resolved centrally, ahead of mode delegation, so they have always worked everywhere — but they were listed in Pan's guidance alone, because Pan is the initial mode and the old panel had room for them nowhere else. An analyst who armed Cross Cursor first therefore never learnt that Shift + drag zooms. withNavigationGuidance appends them beneath each mode's own lines.
• Selecting a feature scrolls a player's view to it. A recording is one tall gram read through a window a few tens of seconds high, so a feature ten minutes in is usually off screen: selecting its row lit up a row, wrote two readouts and pointed the style panel at something the analyst could not see. revealTime moves the view only when the time is off screen, and only while paused, since the follow loop owns the view during playback. It moves the view, never the playhead.
• The selected feature is marked on the gram. Selection was visible only in the control row, so the panel could read "Selected: Marker 3" while three identical crosses sat on the plot with nothing to tell them apart. rendering/selectionHalo.js redraws the feature's own geometry beneath itself, wider and in translucent white — the only treatment that generalises to a crosshair, a shaped symbol and a stack of forty pin lines alike, and one that is independent of the feature's colour. Labels invert instead (dark plate, light text), the same reversal the table row performs, for markers and pin-set number plates alike. Rejected: corner brackets (fine on a marker, poor on a tall pin set), dimming every other feature (unmissable, but it destroys the comparison between features), a pulse (faded by the time the eye arrives).
• More contrast across the panel. Ground #161826 → #0d0e18, surface #232532 → #171926, ink #e9e9ed → #f7f7fa, muted .62 → .70. Body text on the surface goes from ~13:1 to ~16:1 and muted text from ~5.4:1 to ~8.5:1. Recesses deepen to match.

Structure

Splits that came with it, each because two things were sharing a module by accident rather than by design:

• core/featureStyle.js — restyling, out of keyboardControl.js
• core/selection.js — setting and clearing the selection and the consequences that follow, also out of keyboardControl.js, which is about arrow keys: selection is what they act on, not part of how they work. With core/selectionTarget.js, a leaf that describes what is selected so the readout column and the player can both ask without a cycle, this took keyboardControl.js from 698 lines to 415
• core/panelRefresh.js — one copy of "redraw the tables", not three
• core/preferences.js — the two chrome preferences, out of the annotation store
• core/pointerScope.js — the image-bounds gate on pointer delivery, where the one mode that opts out of it is explained
• rendering/selectionHalo.js — what a selected feature looks like on the gram
• player/transportKeys.js, player/bookmarks.js, components/tableScroll.js, components/SymbolSizeTrial.js, utils/guidanceContent.js

A MarkerOwner capability joins PinSetOwner so the panel's Delete finds what to remove without naming a mode (ADR-017). Six module caps fall; state.js and types.js rise, each with the reason recorded in hygiene-baseline.json. instanceStateReachIns falls 144 → 141, specTypeErrors 509 → 503 and uncoveredUnitLines 411 → 409.

Checks

• yarn typecheck — clean
• yarn lint — clean
• yarn hygiene — passes
• yarn test:unit — 298 passed
• yarn test — 516 passed, 0 failed
• WebKit smoke (playwright.smoke.config.ts) — runs in CI and passes

New coverage: tests/style-panel.spec.js (twin tabs, readout retarget, inverted row, chips and empty states), tests/transport-bookmarks.spec.js, tests/selection-highlight.spec.js and tests/unit/guidance-content.test.js. tests/control-row.spec.js is rewritten for the rail and the guidance collapse.

Two test-helper fixes are behavioural, not cosmetic: drags now scrollIntoViewIfNeeded() first, because the panel's fixed 250px height puts the lower half of the component below the fold on a 720px viewport, where boundingBox() returns coordinates the mouse cannot reach and a drag quietly does nothing rather than failing.

Worth a look before merge

• The panel is now a fixed 250px rather than shrinking to its content. On a page whose guidance is short it used to be ~184px, so the gram sits ~66px lower there. That is the design's stated height and the product owner's decision, but it is a real cost to the gram on those pages.
• A selected pin set inverts every one of its visible number plates, which on a dense set is a dozen or more chips changing at once — a much larger change in the gram than a selected marker's single label. It is what was asked for and it reverses on deselect, but it is the part of the highlight most worth judging on screen.
• docs/Control-Panel.md is new and records what was decided and what was rejected (onboarding, docking the transport, an accent tint for the selected row).
• The four new mode glyphs are the handoff's own line drawings rather than Phosphor icons, which the handoff offered as an alternative.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CKL4JMQaFw5TmDSpASuV5L

---

Generated by Claude Code

[github-actions]

PR Preview

Preview deployment is ready! View Preview

Last updated: 2026-09-18T09:24:46.286Z