Add a drag-foldable desktop left navigation with rail and focused drawers

[BorisTyshkevich]

Goal

Make the desktop left navigation foldable without adding collapse/expand buttons.

The user controls the navigation width by dragging its vertical frame border. A sufficiently narrow drag converts the current two-panel sidebar into a compact icon rail. Dragging the rail or its focused drawer wider converts it back into the normal two-panel sidebar.

The compact state must remain fully navigable: clicking a rail icon opens that section as a docked, full-height focused drawer beside the rail. The drawer consumes layout width and pushes the SQL/Dashboard work surface inward; it must not float over or obscure the work surface.

Mobile already uses a different navigation model and is explicitly out of scope.

Phases

Added during /ship (2026-07-29). Branch model: one branch and one PR per phase off fresh
main — phases 1 and 2 are additive/inert and land green on their own, phase 3 turns the
feature on, phase 4 closes the issue. The <!-- ship-log --> comment is the state of record.

• 1 — Layout core and preferences (feat(#487): left-navigation layout core and preferences (phase 1) #571)
• 2 — Navigation section registry (feat(#487): navigation section registry (phase 2) #573, shipped)
• 3 — Rail, focused drawer and the resize separator (feat(#487): rail, focused drawer and resize separator (phase 3) #574, in review)
• 4 — Reflow, integration and verification

Desktop shell geometry

The application header owns the complete top row across the viewport.

Below the header, the horizontal shell is:

wide state
  [two-panel sidebar] [main Query/Dashboard surface] [optional right inspector]

rail state, drawer closed
  [rail] [main Query/Dashboard surface] [optional right inspector]

rail state, focused drawer open
  [rail] [focused left drawer] [main Query/Dashboard surface] [optional right inspector]

The rail, sidebar, focused drawer, main surface and right inspector all begin below the header.

The left navigation must participate in normal layout. No left-navigation state uses an overlay or backdrop on desktop.

Two presentation states

Wide state

The compact rail is absent.

Show the established two stacked navigation panes:

upper pane
  Databases | Dashboards

lower pane
  Queries | History

After #427, the lower pane becomes:

Library | History

Requirements:

• preserve the existing upper/lower pane switchers;
• preserve the horizontal divider between the two panes;
• preserve search, expansion, scroll and lazy-loaded schema state;
• preserve the existing sidebar-width preference range unless a new central layout constraint requires a narrower maximum;
• the vertical frame border at the sidebar's right edge is the only primary wide/rail control;
• do not add chevron, hamburger, pin or >|< buttons for folding the left navigation.

Rail state

Show a narrow vertical rail below the header.

Recommended visual width:

48 px

The rail contains four section launchers:

Section	Icon concept	Accessible label
Databases	database cylinder	Open Databases navigation
Dashboards	dashboard/grid	Open Dashboards navigation
Queries/Library	bookmark or saved document	Open Queries navigation before #427, Open Library navigation after #427
History	clock/history	Open query History

Requirements:

• use existing icon primitives where possible;
• show tooltips with section names;
• show hover, keyboard-focus and active-drawer states distinctly;
• keep every rail icon visible when a focused drawer is open;
• the rail width must remain fixed and must not accidentally stretch to the drawer width;
• the rail has no internal text labels in its normal state;
• the rail begins below the full-width application header.

Focused drawer behaviour

Clicking a rail section opens that section as a docked drawer immediately to the right of the rail.

Examples:

[rail: Databases active] [Databases drawer] [SQL editor]
[rail: Dashboards active] [Dashboards drawer] [Dashboard surface]
[rail: Library active]   [Library drawer]   [SQL editor]

The focused drawer:

• uses the remaining vertical height below the header;
• consumes normal layout width;
• pushes the Query/Dashboard surface instead of covering it;
• shows exactly one section;
• contains that section's title, search and content;
• does not repeat Databases | Dashboards or Queries/Library | History switcher buttons;
• remains open after selecting a database, table, Dashboard, query or history item;
• retains the section's expansion, search and scroll state;
• uses the same application navigation commands as the wide sidebar;
• never executes hidden Dashboards merely because the Dashboards section is visible.

Clicking the active rail icon closes the focused drawer and leaves the rail visible.

Clicking a different rail icon switches the drawer content in place without first closing the drawer.

Escape may close the focused drawer when focus is inside it, but must not also cancel a running query or trigger another global Escape action.

Section-specific behaviour

Databases

Show the existing schema search and database/table/column tree with existing click, double-click, Shift-click, drag and documentation actions unchanged.

Dashboards

Show the Dashboard hierarchy from #426 with its search, expansion, keyboard and navigation semantics unchanged.

Queries / Library

Before #427, show the existing Queries collection.

After #427, show only the zero-owner Library projection and update the rail label/tooltip to Library. The foldable shell must not introduce a separate data projection or duplicate ownership logic.

History

Show the existing history search/list and opening behaviour unchanged.

Drag-controlled state transitions

Use the vertical navigation frame border as a resize separator.

The transition must feel deliberate and must not flicker near a single threshold. Use named constants and hysteresis rather than deriving state directly from every pointer pixel.

Recommended starting values, adjustable only through real-browser layout verification:

const LEFT_RAIL_PX = 48;
const LEFT_FOLD_THRESHOLD_PX = 140;
const LEFT_WIDE_THRESHOLD_PX = 260;
const LEFT_PANEL_MIN_PX = 180;
const LEFT_PANEL_MAX_PX = 420;

Wide -> rail

While dragging the wide sidebar border left:

• resize normally within the wide range;
• once the proposed width passes the fold threshold, commit rail mode;
• remember the last useful wide width;
• remove the wide two-pane sidebar from layout and expose the fixed rail;
• do not leave a partially clipped wide sidebar.

Rail -> wide

While dragging the rail's right frame border to the right:

• show deterministic resize feedback;
• once the drag passes the wide threshold, restore wide mode;
• restore the last useful wide width, or the threshold width when no prior width exists;
• the rail disappears completely in wide mode.

Focused drawer resize

When a focused drawer is open, its right border is the active navigation resize separator.

• dragging resizes the focused drawer within the desktop bounds;
• dragging sufficiently narrow folds the focused drawer closed, leaving the rail;
• dragging beyond the wide threshold converts the navigation to the full two-pane wide sidebar;
• conversion must preserve the currently selected upper/lower section and all section UI state.

Do not rely on CSS width alone to decide the semantic mode after every repaint. The mode is explicit application-shell state.

Layout state

Suggested shell state:

type LeftNavigationMode = 'wide' | 'rail';
type LeftNavigationSection = 'databases' | 'dashboards' | 'library' | 'history';

interface DesktopLeftNavigationState {
  mode: LeftNavigationMode;
  wideWidthPx: number;
  focusedDrawerWidthPx: number;
  focusedSection: LeftNavigationSection | null;
}

Persistence:

• mode, wideWidthPx and focusedDrawerWidthPx are browser preferences;
• focusedSection is session UI state and need not reopen automatically after reload;
• none of this state belongs in StoredWorkspaceV3, Dashboard documents or query specs;
• selected Databases/Dashboards and Queries/Library/History roles continue to use their existing UI-state ownership.

The persisted preference decoder must clamp invalid or obsolete values safely.

Shared navigation state

Wide and focused presentations are two views over the same navigation state.

Preserve across transitions:

• schema search text;
• schema database/table expansion;
• loaded-column cache;
• schema scroll position;
• Dashboard search and expansion;
• Dashboard keyboard/current-row state;
• Queries/Library search and editing state where safe;
• History search;
• upper/lower split percentage;
• current application surface and editor/result state.

Do not create separate competing expansion/search stores for wide and focused presentations.

A transition may move DOM focus to the corresponding control in the new presentation, but it must not silently reset the user's state.

Interaction with drag-and-drop assignment

The implementation must remain compatible with #428.

When a Library-query drag is active in rail mode:

• the Dashboards rail icon can be exposed as a valid hover launcher;
• bounded hover may open the docked Dashboards focused drawer;
• the user can then drop on Dashboard, Panels or Filters targets;
• leaving/cancelling the drag clears temporary hover state;
• this must never turn the drawer into an overlay.

This integration may be completed by #428 if #428 has not yet landed, but the left-navigation API must provide a deterministic openFocusedSection('dashboards') seam.

Main-surface resizing

Every width or mode change must notify/reflow the active centre surface correctly:

• CodeMirror/editor geometry;
• result table and virtualised rows;
• Query editor/results splitter;
• Dashboard layout engines and charts;
• sticky Dashboard/filter/toolbars;
• optional right inspector.

Use existing resize observers/layout hooks rather than arbitrary delayed resize events.

Left and right docked panels may be open simultaneously. Clamp widths so the centre retains a documented minimum usable width.

Keyboard and accessibility

The vertical frame border is a keyboard-operable separator:

role="separator"
aria-orientation="vertical"
tabindex="0"
aria-valuemin / aria-valuemax / aria-valuenow

Keys:

• Left/Right Arrow resize by a small step;
• Shift+Left/Right resize by a larger step;
• Home folds to rail;
• End restores wide mode;
• announce semantic mode changes through an appropriate live/status mechanism without excessive chatter.

Rail buttons must expose aria-expanded and aria-controls for the focused drawer.

Closing a focused drawer returns focus to its rail icon. Converting to wide mode restores focus to the corresponding section tab/search/tree when possible.

Mobile

At the existing mobile breakpoint:

• do not render the desktop rail or desktop focused drawer;
• retain the established mobile segmented and bottom navigation;
• ignore desktop folding preferences for effective mobile layout;
• preserve those preferences for the next desktop session.

Suggested code boundaries

App shell layout controller

Owns:

• explicit wide/rail mode;
• widths and thresholds;
• vertical resize separator;
• focused drawer host;
• preference persistence;
• centre-width clamping and resize notifications.

Navigation section registry

Maps rail sections to existing views and labels without duplicating their domain state.

Existing navigation views

Continue to own their tree/list rendering, search and application actions. They must not manipulate shell widths directly.

Delivery phases

Each phase's definition of done is its implement list below, the ## Tests subsections it
names, and the subset of ## Acceptance criteria it claims. ## Non-goals applies to all four.

Phase 1 — Layout core and preferences

Pure layout-decision logic plus its persisted preferences. No visible change.

Implement:

• src/core/left-nav-layout.ts (new, pure, 100% covered): the named constants
  (LEFT_RAIL_PX, LEFT_FOLD_THRESHOLD_PX, LEFT_WIDE_THRESHOLD_PX, LEFT_PANEL_MIN_PX,
  LEFT_PANEL_MAX_PX), the LeftNavigationMode / LeftNavigationSection types, the
  hysteresis reducer mapping (current mode, proposed px) to the next mode and width,
  wide-width clamping, and the keyboard step resolver (small step, large step, Home folds
  to rail, End restores wide);
• src/state.ts: mode, wideWidthPx and focusedDrawerWidthPx as persisted browser
  preferences, focusedSection as session-only UI state, their KEYS entries, and decoders
  that clamp invalid or obsolete values back to the documented defaults;
• src/application/app-preferences.ts: the new keys added to PreferenceKey.

Tests: ## Tests → State and preferences, in full — including the assertion that none of
this state reaches StoredWorkspaceV3, Dashboard documents or query specs.

Also here, because the mobile rule is a layout decision and not a rendering one:
effectiveLeftNavigationLayout(layout, isMobile), the projection that makes mobile ignore
rail mode and any open drawer while leaving both persisted widths untouched.

Moved out of this phase during implementation: the centre-width clamp. Review established
that a single total-width-in/total-width-out signature is the wrong shape — there is no inverse
from a total back to (mode, panel width), so it can return a width no mode can render (220px
is neither the rail, nor a legal wide sidebar, nor rail+drawer). Phase 3 owns it, as
layout-in/layout-out: phase 3 is what turns the feature on, and parking a required safety
constraint in phase 4 would leave a merged interval in which left and right docked panels can
starve the centre surface. Deferring an unused primitive out of phase 1 is CLAUDE.md hard rule
5; deferring a safety constraint past the feature it protects is not. (This paragraph said
"phase 4" until phase 2 reconciled it — the phase 3 and 4 sections below, and the
<!-- ship-log --> comment, have said phase 3 since phase 1 shipped.)

Acceptance subset: claims none of the eight global criteria; all eight defer to phases 3
and 4. This phase's gate is the State-and-preferences list plus 100% coverage of the new core
module.

Phase 2 — Navigation section registry

Make the four navigation sections hostable by any container, over one shared store per
section. The wide sidebar renders exactly as it does today.

Implement:

• the navigation section registry: each LeftNavigationSection mapped to its label, icon,
  accessible label and its persistent host element — built once and never rebuilt,
  extending the buildSidebarUpper pattern (Add a Databases/Dashboards switcher and dashboard hierarchy tree #426) from Databases/Dashboards to the lower
  pane's Library/History;
• src/ui/app-shell.ts: compose today's two-pane sidebar out of the registry's hosts;
• no second competing search/expansion/scroll store — the registry hands out the same hosts
  both presentations will later use, so state survives by construction.

Tests: extend tests/unit/app-shell.test.ts and tests/unit/sidebar-upper.test.ts — the wide
pane composition, and exactly one host instance per section. ## Tests → Wide state
bullets 1–4.

Acceptance subset: claims none; this phase's gate is "existing navigation behaviour is
unchanged".

Phase 3 — Rail, focused drawer and the resize separator

The feature turns on.

Implement:

• src/ui/left-rail.ts: the LEFT_RAIL_PX rail with four launchers reusing the existing
  database / dashboard / layers / history icon primitives, tooltips, distinct hover /
  keyboard-focus / active-drawer states, aria-expanded + aria-controls, a width that
  cannot stretch to the drawer's, and no internal text labels; mounted below the full-width
  header;
• Deviation, shipped instead of a separate src/ui/left-drawer.ts: the existing
  .sidebar element is RE-PRESENTED as the drawer via one data-nav-mode attribute
  ('wide' | 'rail' | 'drawer'), written by one function (app-shell.ts's
  applyEffectiveLeftNavigationLayout) that is the sole authority for every presentation
  attribute. No section host ever moves between containers — phase 2's persistent-host
  guarantee ("wide and focused presentations share and preserve all navigation state") holds
  by construction rather than by a second module's own restoration logic. See the
  <!-- ship-log --> comment's phase-3 handoff for the full rationale;
• openFocusedSection(section) on the app controller — the deterministic seam Add Library drag assignment to Dashboard panels and variables #428 requires;
• src/ui/app-shell.ts: render either the wide sidebar or rail + drawer from the explicit
  shell mode, keeping every section host mounted across the transition;
• Deviation, shipped instead of a new splitters.ts axis: a dedicated
  src/ui/left-nav-separator.ts module REPLACES splitters.ts's old 'col' axis outright
  (deleted, not left beside the new module) — feeding proposed widths through phase 1's
  reducer via a resize session, with safe termination on blur/visibilitychange. A fifth
  competing axis would have kept two sidebar-width authorities (the old bare clamp and the
  new mode reducer) alive at once;
• the separator itself: role="separator", aria-orientation="vertical", tabindex="0",
  aria-valuemin / aria-valuemax / aria-valuenow, Left/Right, Shift+Left/Right, Home,
  End, and a status announcement on semantic mode change only;
• Escape closes the focused drawer when focus is inside it without reaching any global Escape
  action; closing returns focus to the rail icon; converting to wide restores focus to the
  corresponding section tab, search or tree;
• mobile: neither rail nor focused drawer renders below the breakpoint, and the desktop
  preferences are preserved for the next desktop session;
• the centre-width clamp, as a layout-in/layout-out function so its result always names a
  renderable (mode, panel width) rather than a bare total no mode can express. Moved out of
  phase 1 (its caller lives here, and the total-in/total-out shape it had was wrong) but
  deliberately not deferred to phase 4: this is the phase that turns the feature on, and
  shipping activation without it would leave a merged interval where left and right docked
  panels can starve the centre surface. A required safety constraint cannot land after the
  feature it protects;
• mode-aware aria-valuetext on the separator. The numeric range is honest at both
  extremes, but its interior is not continuous (49–179 is no resting width in any mode) and one
  number can mean either a wide sidebar or rail+drawer, so a bare aria-valuenow does not
  communicate position.

Tests: ## Tests → Rail state, Focused drawer and Drag transitions in full, plus
Wide state bullet 5.

Acceptance subset: claims bullets 1–6 and 8. Defers bullet 7 (header, main surface and
optional right inspector resize correctly) to phase 4.

Phase 4 — Reflow, integration and verification

Implement:

• reflow the active centre surface on every width or mode change through the existing
  resize observers and layout hooks — CodeMirror geometry, the result table and its
  virtualised rows, the editor/results splitter, Dashboard layout engines and charts, sticky
  Dashboard/filter toolbars, and the optional right inspector — never arbitrary delayed
  resize events;
• verify the centre-width clamp landed in phase 3 holds up under real reflow;
• the Add Library drag assignment to Dashboard panels and variables #428 integration: during an active Library-query drag in rail mode, bounded hover on the
  Dashboards rail icon opens the docked Dashboards drawer via openFocusedSection('dashboards'),
  drops land on Dashboard / Panels / Filters targets, leaving or cancelling the drag clears the
  temporary hover state, and the drawer never becomes an overlay;
• tests/e2e/left-nav-fold.spec.js and a real-browser verification pass — happy-dom sees no
  CSS layout, so the recommended threshold values are confirmed here.

Tests: ## Tests → Reflow and regressions, in full, plus the new e2e spec.

Acceptance subset: claims bullet 7 and re-verifies 1–8 end to end. This phase closes the
issue.

Tests

State and preferences

• fresh desktop session starts from the documented default;
• valid mode/width preferences restore;
• invalid widths clamp safely;
• left state is never written to workspace JSON;
• mobile ignores desktop effective state while preserving preferences.

Wide state

• rail is absent;
• upper and lower panes render together;
• switchers and horizontal splitter remain;
• existing navigation behaviour is unchanged;
• dragging left below the fold threshold enters rail mode once.

Rail state

• rail starts below the full-width header;
• exactly four section icons remain visible;
• icons remain visible while a drawer is open;
• active icon is marked;
• clicking active icon closes the drawer;
• clicking another icon switches content;
• rail never expands to drawer width.

Focused drawer

• drawer is docked and reduces centre width;
• no overlay/backdrop is created;
• no redundant role switchers render inside it;
• selected resources do not auto-close it;
• search/expansion/scroll state survives section and mode changes;
• Escape and focus restoration are correct.

Drag transitions

• wide -> rail uses hysteresis without oscillation;
• rail -> wide restores the prior width;
• focused drawer can fold closed or expand to wide;
• pointer cancellation and window blur terminate drag safely;
• keyboard separator operations match pointer transitions.

Reflow and regressions

• editor, results and Dashboard resize correctly;
• a running query is not cancelled by folding navigation;
• Query/Dashboard surface state is preserved;
• right inspector can coexist;
• database tree and Dashboard tree gestures are unchanged;
• Add Library drag assignment to Dashboard panels and variables #428 hover-opening can target the docked Dashboards drawer;
• no mobile regression.

Acceptance criteria

• Desktop users can fold the left sidebar into a compact rail solely by dragging the vertical frame border.
• Dragging wider restores the normal two-pane sidebar without a separate expand button.
• Rail icons open Databases, Dashboards, Queries/Library or History as full-height docked drawers.
• Focused drawers push the work surface and never float over it.
• The rail remains visible and correctly sized while a drawer is open.
• Wide and focused presentations share and preserve all navigation state.
• Header, main surface and optional right inspector resize correctly.
• Mobile behaviour is unchanged.

Non-goals

• Changing database, Dashboard, Library or History domain semantics.
• Implementing Separate Library queries from dashboard-owned query copies #427 ownership migration.
• Implementing Add Library drag assignment to Dashboard panels and variables #428 assignment itself.
• Adding touch gestures for desktop folding.
• Persisting shell layout in workspace/export data.
• Floating left navigation over the editor.
• Adding explicit fold/unfold buttons.

[BorisTyshkevich]

sql-browser-shell-prototype.html

[BorisTyshkevich]

Ship log — #487

Branch model: one branch and one PR per phase off fresh main. Phases 1 and 2 are additive
and inert, so each lands on main green and self-consistent on its own; phase 3 turns the
feature on; phase 4 closes the issue. The issue had no declared phases — the four-phase split
was added during /ship (2026-07-29) and is written into the issue body. This comment is the
state of record; the ## Phases checklist in the body is a convenience view.

Phase	Status	PR
1 — Layout core and preferences	shipped	#571
2 — Navigation section registry	shipped	#573
3 — Rail, focused drawer and the resize separator	in review	#574
4 — Reflow, integration and verification	—	—

Phase 1 — handoff

Landed: src/core/left-nav-layout.ts — constants and thresholds, the explicit
'wide' | 'rail' mode, the hysteresis reducer, the keyboard separator resolver, rail
activation, the separator ARIA range, the mobile projection, and the mode/focusedSection
coherence predicate. Plus AppState.leftNavMode / leftNavDrawerPx / leftNavSection, two
KEYS entries, two PreferenceKeys, and a NaN-safe sidebarPx decode. 100/100/100/100.
No user-visible change.

Decisions taken (not in the issue — phase 2 and 3 must not re-derive these):

• wideWidthPx IS AppState.sidebarPx. The issue suggests a new field; asb:sidebarPx
  already persists exactly that width over exactly the [180, 420] range with default 248.
  Two owners of one width is a bug waiting to happen. The only new keys are asb:leftNavMode
  and asb:leftNavDrawerPx. core/left-nav-layout.ts calls it wideWidthPx; map at the
  boundary.
• The reducer's currency is the navigation's TOTAL width, not a per-mode panel width, and
  it does the per-mode subtraction itself (drawer = total − LEFT_RAIL_PX). This is load-bearing
  — see the bug below. Phase 3's pointer handler passes clientX minus any shell left offset
  (zero today); if a left gutter ever appears, every threshold silently shifts by it unless that
  subtraction happens.
• The focused drawer's band is [LEFT_FOLD_THRESHOLD_PX, LEFT_WIDE_THRESHOLD_PX] = [140, 260],
  NOT the wide sidebar's [MIN, MAX]. A drawer drag folds below 140 and converts above 260, so
  the wide range is mostly unreachable for a drawer. MIN/MAX govern the sidebar only.
  Superseded by phase 3 — see below: the floor is now 180, matching the wide sidebar's own.
• A drag follows the pointer; only End restores the remembered width. The issue asks a
  rail → wide drag for both "restore the last useful wide width" and "show deterministic
  resize feedback"; those cannot both hold, because the next pointermove overwrites whatever the
  crossing frame installed, so a restored width lives one frame and reads as a flicker.
• 'library' is this module's section name but NOT the value AppState.sidePanel stores.
  That is still 'saved' (asb:sidePanel, compared against throughout ui/saved-history.ts) —
  Separate Library queries from dashboard-owned query copies #427 renamed the label and deliberately left the persisted value alone. Phase 2's registry
  owns the single 'library' ↔ 'saved' mapping; the other three sections are identical. The
  mapping is deliberately not written yet (no caller until the registry exists).
• resolveRailActivation is a no-op in wide mode, and that is a hard limit. Phase 3's
  wide-mode openFocusedSection(section) must drive the existing upper/lower pane switchers.
  Writing state.leftNavSection directly would break the coherence invariant, and
  leftNavigationWidthPx would then push the centre surface by a width that omits the drawer.
  The invariant lives in the reducers, not in the two independently-settable signals.
• Arrows resize within a band and perform the band edge's semantic transition. An arrow's
  relative step cannot cross a dead zone wider than itself, so a purely relative arrow gets
  stranded at both boundaries: a bare rail (48px, nearest legal wide width 180) and a floored
  sidebar (180px, folds only below 140). A pointer escapes both because clientX is absolute.
  A bare rail's ArrowRight restores the remembered width (like End); a floored sidebar's
  ArrowLeft folds (like Home). Phase 3 needed a THIRD mirror of this for the drawer once
  its floor was raised to 180 — see below.
• resolveRailOpen is the openFocusedSection seam, NOT resolveRailActivation. The
  latter is a click toggle. Add Library drag assignment to Dashboard panels and variables #428's bounded drag-hover re-asserts intent repeatedly, so a toggle
  would flap the drawer open and shut on alternate hover notifications.
• Every reducer normalizes its input, so "a focused drawer exists only in rail mode" is an
  unconditional postcondition, and non-finite or out-of-band widths are lifted into their band.
  This does not make phase 3's atomic-write discipline optional — still write leftNavMode and
  leftNavSection together — but a slip is now corrected on the next interaction instead of
  persisting as an unrenderable shell.
• Persisted widths decode through decodeStoredPx, which requires the whole string to be a
  finite number. parseInt accepted a numeric prefix ('12junk' → 12, '200px' → 200).

One real bug caught in review, worth knowing about: an earlier revision handed the reducer a
mode-relative width. On a monotone rightward drag with the drawer at its 260 maximum and a
remembered wide width of 200, the navigation snapped 108px backwards on the single frame it
converted to the sidebar (occupied 308 → 200 → 310), because the two measurements disagree by
exactly the rail's width at the crossing. Every per-frame assertion passed; each frame's output
was individually defensible and only the sequence was wrong. The tests now sweep a whole
pointer path and assert width-monotonicity in both directions. Phase 3 should keep that habit
for anything geometric.

Deviations from the spec, and why:

• The four decisions above.
• The issue says StoredWorkspaceV3; the current persisted version is V5. Same intent, and
  the isolation test drives the real candidateFrom projection against V5.
• The issue says rail → wide with no prior width restores "the threshold width" (260); the code
  falls back to LEFT_WIDE_DEFAULT_PX (248), the historical default. Unreachable in practice —
  sidebarPx always decodes to a number.

Moved between phases:

• The centre-width clamp moved from phase 1 to phase 3 (first to phase 4, then corrected).
  Its total-in/total-out signature was the wrong shape — there is no inverse from a total back
  to (mode, panel width), so it could return a width no mode renders (220px is neither the
  rail, nor a legal wide sidebar, nor rail+drawer). It belongs in phase 3, as
  layout-in/layout-out: phase 3 is what turns the feature on, and parking a required safety
  constraint in phase 4 would leave a merged interval where left and right docked panels can
  starve the centre surface. Deferring an unused primitive out of phase 1 is hard rule 5;
  deferring a safety constraint past the feature it protects is not.
• effectiveLeftNavigationLayout(layout, isMobile) was added to phase 1 so the issue's
  "mobile ignores desktop effective state while preserving preferences" bullet has a real,
  falsifiable implementation instead of a vacuous test.

Deferred acceptance criteria: all eight. Phase 1 claims none — bullets 1–6 and 8 are phase
3's, bullet 7 is phase 4's.

Known-stale, for phase 3: tests/e2e/sidebar-tabs-narrow.spec.js drags the sidebar to
clientX = 100 and asserts the width clamps to 180. Under the fold rule that gesture becomes a
fold to rail, so phase 3 must re-fixture that spec rather than soften the rule. It passes
today (phase 1 changed no behaviour). Done in phase 3 — see below.

Two open questions phase 3 owns, both raised in review and deliberately NOT settled here:

1. The restore memory is sampling-dependent. From a 300px sidebar, one coarse sample past
   the fold remembers 300, but an intermediate sample inside the 140–179 dead zone rests the
   width at the floor first and remembers 180 — so the same physical gesture yields different
   memory depending on which pointer events the browser delivered. wideWidthPx is serving as
   both the live drag width and the restore memory; those are genuinely different quantities
   (add drag-start snapshot and crossing coordinate and there are four). Fixing it needs
   transient drag-session state, which a pure reducer cannot take — phase 3's pointer
   handler owns it. Current behaviour is pinned by a test so the change has to be deliberate.
   Note this does not argue for a second persisted key: asb:sidebarPx stays the one
   persisted preference; the extra quantities are per-gesture, not persisted. Resolved in
   phase 3 — see below.
2. The drawer's [140, 260] band may have the wrong floor. A 150px drawer is currently
   legal, and it has to hold a section title, a search box, tree indentation and action
   controls. The real alternative is not [180, 420] — it is to mirror the wide sidebar's dead
   zone: fold below 140, hold at a 180 floor through 140–179, resize 180–260, convert above
   260. Add a drag-foldable desktop left navigation with rail and focused drawers #487 says these constants are "adjustable only through real-browser layout
   verification", so this is settled in phase 3/4 at 140, 179, 180 and 260 — not by unit tests.
   Resolved in phase 3 — see below.

Also for phase 3: the separator's ARIA range is honest at both extremes but its interior is
not continuous — 49–179 is no resting width in any mode, and one number can mean either a wide
sidebar or rail+drawer. Inherent to one control spanning two modes, so phase 3 adds mode-aware
aria-valuetext (now listed in the issue body) rather than reshaping the range. Done.

Follow-ups filed: #570 (inbox) — clamp is not NaN-safe, so
editorPct/sideSplitPct/cellDrawerPx/docPanePx each decode a corrupt stored value to
NaN and reach the DOM as width: NaNpx. sidebarPx is fixed in this phase because it is the
wide width; the other four are out of scope.

Reconciled: roadmap #68 (added #487 with the phase breakdown; ticked #427's stale checkbox —
it merged 2026-07-25), the #487 body (phase structure and all four deviations),
CHANGELOG.md [Unreleased].

Review: two independent read-only passes (correctness; repo-fit) plus a ChatGPT second
opinion, which returned "request changes" with six findings — all six reproduced against the
real code and all six are fixed (commit acc7317). The most valuable was the exact mirror of
the bug the first pass caught: plain ArrowLeft could never fold a wide sidebar, stranded at
the 180 floor forever while the equivalent pointer path folded — and the first round's test had
blessed that no-op. Lesson worth carrying into phase 3: a dead end fixed at one boundary
should immediately prompt a check of the opposite boundary.

The correctness pass found the width-flicker bug and four unfalsifiable tests; the repo-fit pass
found the stale duplicate [180, 420] in splitters.ts's 'col' axis (which writes
sidebarPx) and the wrong 'saved' comment.

Sabotage-checked across both rounds — each of these fails a specific test: reverting the
crossing to the remembered width, basing the bare-rail step on wideWidthPx, loosening the
drawer fold comparison to <=, adding a field to the workspace projection, dropping the
wide-floor fold transition, making the open seam a toggle, removing reducer normalization, and
reverting decodeStoredPx to parseInt.

---

Phase 2 — handoff

Landed: src/ui/nav-sections.ts — NAV_SECTION_META (label / icon factory /
accessible label / pane, per section), buildNavSectionRegistry(app, upperHandle) →
{ entries, entry(section), showSection(section) }. app-shell.ts composes both sidebar
panes out of registry.entries filtered by pane and gained one effect that exposes a
lower host from state.sidePanel. saved-history.ts renders into the active section's
own search/list pair and takes its tab labels/icons from the registry; so does
sidebar-upper.ts, whose two hosts also moved to the shared .nav-section-host /
data-section vocabulary. core/left-nav-layout.ts gained the 'library' ↔ 'saved'
bridge (sidePanelKeyFor / sectionForSidePanelKey / SidePanelKey /
LowerNavigationSection), which state.ts applies at the load boundary — narrowing
AppState.sidePanel from Signal<string> to Signal<SidePanelKey>. Two new AppDom
fields (historySearch, historyList). 100/100/100/100 on the new module. No
user-visible change.

Decisions taken (not in the issue — phase 3 must not re-derive these):

• The registry receives Add a Databases/Dashboards switcher and dashboard hierarchy tree #426's upper handle; it does not build it. app-shell.ts
  calls buildSidebarUpper(app, databasesContent) and passes the handle in. The
  alternative — the registry importing buildSidebarUpper — creates a runtime import
  cycle the moment sidebar-upper.ts wants NAV_SECTION_META for its own tab row
  (which it should, and which is the point of the registry). Only SidebarUpperHandle
  is imported here, as a type, which esbuild erases.
• Upper-pane exposure is DELEGATED to showRole, lower-pane exposure sets hidden
  directly. The asymmetry is deliberate: Add a Databases/Dashboards switcher and dashboard hierarchy tree #426 has owned its pair's exposure since it
  was written, and the registry's job is to unify how containers address a section,
  not to reach into another module's DOM. showSection dispatches on
  NAV_SECTION_META[section].pane.
• showSection is scoped to a PANE, not global. The wide sidebar shows one upper
  AND one lower section simultaneously, so a global "exactly one of four" would blank
  half the sidebar. Phase 3's drawer respects this — it shows one of four by
  re-presenting .sidebar itself (see below), NOT by widening this rule.
• The lower pane's two sections now own SEPARATE persistent search/list pairs.
  app.dom.savedSearch/savedList are the Library's; historySearch/historyList
  are new. Before this both sections rendered through the one pair, which is why the
  lower pane could not be moved into a drawer without carrying the other section's
  content along. activeSection(app) in saved-history.ts is the single chooser, and every
  branch in that module goes through it rather than comparing sidePanel to 'saved'.
• A section switch still CLEARS state.libraryFilter and repaints the newly-shown
  section — today's behaviour, unchanged, because phase 2's gate is "existing
  navigation behaviour is unchanged". See the open question below; phase 3 owns it and
  reverses it — see below.
• The 'library' ↔ 'saved' bridge lives in core/left-nav-layout.ts, not in the
  registry, even though phase 1's note said the registry would own it. Ownership does not
  require the file: state.ts applies the decode at the load boundary and must not import
  src/ui/, so the pure half sits beside decodeLeftNavigationMode and the registry
  re-exports it. A test asserts the re-export is the SAME function object, not a copy.
• sectionForSidePanelKey resolves anything that is not 'history' to Library, which
  is that preference's documented default — see the bug below. Do not "fix" this into a
  three-way with a null case, and do not flip the fallback to match the old === 'saved'
  behaviour.
• NAV_SECTION_META[s].icon is a FACTORY, not an element. One SVG node cannot be in
  the wide switcher and the rail launcher at the same time — appending it to the second
  removes it from the first. Phase 3's rail calls icon() — confirmed.
• accessibleLabel holds Add a drag-foldable desktop left navigation with rail and focused drawers #487's own rail-table strings verbatim — Open Databases navigation, Open Dashboards navigation, Open Library navigation, Open query History
  — and is asserted as exact strings, not merely truthy. It is a separate field from label
  because an icon-only launcher has to announce what activating it does while a tab inside
  a labelled switcher does not. Phase 3's rail uses accessibleLabel for aria-label and
  label for title — the two were briefly conflated in an early draft of phase 3's plan and
  caught before implementation.

Deviations from the spec, and why:

• The issue says the registry maps sections "to existing views and labels". It also
  maps pane, because the wide presentation needs to know a section's siblings in
  order to expose one — see the showSection decision above.
• The class rename .upper-role-host → .nav-section-host and data-role →
  data-section is not in the issue. Phase 3's drawer needed to host any of the four
  with no per-section layout rule — this is what made that possible, via re-presentation
  rather than movement. Cost: 10 selector lines in
  tests/e2e/dashboard-tree.spec.js, re-run green on chromium and webkit.
• NAV_SECTION_META is exported separately from the registry instance so
  saved-history.ts's tab row can read a label/icon without holding a registry
  reference. Without it the labels would have stayed duplicated, which is what the
  registry exists to prevent.

Open question phase 3 owns — RESOLVED, but not the way phase 2 expected: "Search state
does not survive a SECTION change, only a host move" (the shared libraryFilter clearing on a
lower-pane tab switch). Phase 3 replaced the shared string with per-section storage and made
BOTH presentations always preserve it — reversing phase 2's pinned "switch clears" behaviour
rather than merely making the drawer path an exception to it. See phase 3's own handoff for
why the narrower "only the drawer preserves" version considered first was wrong.

A latent hazard phase 3 had to handle, raised in review and deliberately not fixed here:
the inactive section's search <input> stays alive inside the hidden host, with listeners that
write the SHARED state.libraryFilter and call renderList() — which now resolves to whatever
section is active. Phase 3's per-section filter storage made this hazard structurally
impossible rather than merely guarded — see below.

Follow-ups filed: #572 (inbox) — the lower switcher renders its tabs with neither
type="button" nor aria-pressed while the upper switcher has both. Closed by phase 3.

One real bug caught in review, worth knowing about: the two halves of the vocabulary
bridge used OPPOSITE fallbacks for an unrecognized sidePanel value. sectionForSidePanelKey
resolved anything not 'history' to Library; saved-history.ts's === 'saved' comparisons
resolved anything not 'saved' to History. So a corrupt or obsolete asb:sidePanel (say
'queries') made the shell expose the Library host while the renderer painted into the
History pair inside the hidden one — a visibly blank pane with the Library tab active.
The fix is structural rather than a patched comparison: state.ts now DECODES asb:sidePanel
at load, so the signal only ever holds 'saved' | 'history'. Lesson for phase 3: the moment
one piece of state gets two independent readers, their fallbacks for an unrepresentable value
have to be the same function, not the same intention. (Phase 3 hit this AGAIN — see below —
the lesson repeated exactly once more before it fully stuck.)

Review: two independent read-only passes plus a ChatGPT second opinion, "request
changes" then, on a second pass, "approve phase 2". 13 sabotage checks, each caught by a
specific named test. The lesson this branch kept re-teaching — FOUR times, worth
recognizing on sight: (1) asserting a rendered value identical whether the code reads the
shared source or hard-codes it; (2) exercising only one side of a two-module invariant; (3)
asserting a table's entries are fresh/truthy rather than pinning their VALUES; (4) asserting
object identity where the risk is detachment. Phase 3 needed this list at least twice more
— see below.

⚠ THE phase-3 invariant, and the real prerequisite

Opening a focused drawer must ALSO select that section in its existing pane state, atomically.
Three mechanisms were independent going into phase 3: leftNavSection says which drawer is
open; upper host exposure derives only from upperRole; lower host exposure AND lower
rendering derive only from sidePanel. Phase 3's application/left-nav.ts solved this with
one function, openFocusedSection, wrapping both writes in a SINGLE batch() call — an
earlier draft composed two independently-batched functions, which a ChatGPT review caught as
NOT atomic (Preact's batch() flushes per top-level call, so two calls can let an effect
observe a mismatched intermediate state). Confirmed fixed and tested.

---

Phase 3 — handoff

Landed, in six committed steps (a1bea7d … be9af64, 12 commits total on
feat/left-rail-focused-drawer-487p3, PR #574):

1. core/left-nav-layout.ts: a resize session (LeftNavigationResizeSession /
   beginLeftNavigationResize / advanceLeftNavigationResize / commitLeftNavigationResize)
   resolving phase 1's open question 1, and clampLeftNavigationToMaximumTotal +
   LEFT_CENTRE_MIN_PX = 480 for the centre-width safety constraint.
2. application/left-nav.ts (new): openFocusedSection/toggleFocusedSection, the
   deterministic seam Add Library drag assignment to Dashboard panels and variables #428 needs, wired onto the app controller.
3. saved-history.ts: per-section lower-navigation filters and independent rendering
   (closing Lower sidebar switcher announces no pressed state (upper pane does) #572 along the way).
4. left-rail.ts + left-nav-separator.ts (new, standalone) then wired into
   app-shell.ts — .sidebar re-presented via data-nav-mode, splitters.ts's old
   'col' axis deleted outright, a real ResizeObserver-backed shell-width seam added to
   app.ts.
5. Escape and focus restoration in app-shell.ts.
6. e2e coverage (Playwright, chromium+webkit) + real-browser settlement of phase 1's
   open question 2 (the drawer floor).

100/100/100/100 on every new module (left-nav.ts, left-rail.ts, left-nav-separator.ts);
app-shell.ts and splitters.ts both landed at 100/100/100/100 too. First user-visible change
of the whole issue: the feature is reachable.

Decisions taken (not in the issue — phase 4 must not re-derive these):

• .sidebar is RE-PRESENTED, never moved. The issue's suggested code boundaries name a new
  left-drawer.ts module; this plan deliberately does not build one. The existing .sidebar
  element becomes the drawer via one attribute, data-nav-mode ('wide' | 'rail' | 'drawer'),
  written by exactly one function, app-shell.ts's applyEffectiveLeftNavigationLayout — the
  sole authority for every presentation attribute (rail/sidebar visibility, width, the drawer's
  title, aria-labelledby, and — critically — hidden on the non-focused pane and both tab
  rows, set unconditionally in every branch). No section host ever detaches or moves between
  containers; phase 2's persistent-host guarantee holds by construction, not by restoration
  logic, exactly as phase 2 intended. Four stale in-repo comments from phases 1–2 that
  described host movement (nav-sections.ts ×2, app-shell.ts, styles.css) were corrected
  in the same commits that changed the behaviour they described. A fifth was found by a later
  independent review pass and fixed too (nav-sections.ts's NavSectionEntry.host field
  comment) — the sweep phases 1–2 asked for missed one field-level comment the first time.
• The separator replaces splitters.ts's 'col' axis outright, not a fifth axis beside
  it — the issue's suggested boundary. Two competing sidebar-width authorities (the old bare
  clamp and the new mode reducer) is exactly the bug class core/left-nav-layout.ts exists to
  prevent. splitters.ts lost 'col', DragState.sidebarPx, and the corresponding branches in
  startDrag; the .col-resize CLASS is kept (unchanged CSS, and tests/e2e/ dashboard-mobile.spec.js's display-state assertion keys off it), only its JS wiring changed.
• A resize session, not continuously-advancing memory — and this took THREE design rounds to
  get right, worth reading in full before touching this code again. Round 1 (a gesture-scoped
  session) fixed the wide band's sampling-dependent restore memory but reproduced the identical
  bug in the drawer band. Round 2 ("continuously update memory on every legal proposal") was
  hand-verified to STILL be sampling-dependent — a dense sample path landing exactly on a band's
  floor commits a different final value than a coarse path that skips over it; a Plan-agent
  review then a ChatGPT review each caught different halves of this before it shipped. Round 3
  (what actually shipped) tracks THREE layouts per session — preferredAtStart (the persisted
  preference, captured once), proposed (the latest RAW reducer output, pre-clamp — the memory
  source commit reads from), and effective (proposed after the viewport clamp — render-only,
  never read by the commit decision). A confirmed, real bug survived even into round 3 and
  shipped for one review cycle: comparing two POST-CLAMP layouts (effective vs an
  effectiveAtStart snapshot) to decide whether a band "changed" is wrong whenever a restore
  command (Home/End/bare-rail ArrowRight) runs while a viewport clamp is active — a
  dormant band's effectiveAtStart passes the preference through unclamped, so the honest
  restored proposal (say 420) gets compared against it, "matches", and then the CLAMPED render
  value (say 313) — not the restored preference — gets persisted, silently downgrading it. Fixed
  by comparing the RAW proposed against preferredAtStart, never anything post-clamp; commit
  2a115f0; regression-tested by driving the real reducer (resolveLeftNavigationKey) through
  the exact scenario, not a hand-constructed fake.
• The keyboard path needed its OWN mirror of the wide sidebar's floor-fold check, and this is
  a DIRECT, mechanical consequence of raising the drawer's floor (see below) — not a phase-3
  design choice on its own. Before the floor was raised, the drawer's floor WAS the fold
  threshold (140), so an ordinary relative arrow step below it was already below the threshold
  too and folded on its own. Once the floor moved to 180 while the fold threshold stayed 140, a
  plain ArrowLeft from the drawer's floor would land in the new 140–179 dead zone and strand
  there forever — the exact bug phase 1's own wide-sidebar keyboard fix (see phase 1's handoff)
  already exists to prevent, now needed a second time for the drawer. Added as a mirror branch
  in resolveLeftNavigationKey.
• One function, applyEffectiveLeftNavigationLayout, is the sole writer of every
  presentation attribute — called by initial mount, a "preferred-state" effect
  (leftNavMode/leftNavSection/isMobile signal changes), the separator's own
  applyEffectiveLayout callback during an active gesture, and an injected ResizeObserver
  seam for a plain browser-window resize with no active gesture. The width observer must
  check leftNavSeparator.isSessionActive() before repainting — it derives from the last
  COMMITTED preference, which is stale for exactly as long as a gesture is in progress, and
  repainting from it mid-drag would visibly snap the sidebar away from the pointer. The
  preferred-state effect is deliberately NOT gated the same way: isMobile flipping mid-drag
  is a real transition it must still force to wide. A narrow, transient visual glitch (one
  stale frame) can still occur if a drag is active exactly across a mobile-breakpoint crossing —
  documented, not fixed; fixing it needs a change to the separator's own session logic to notice
  isMobile, which is bigger than this phase's scope.
• The separator's own ARIA can go stale independently of its own gestures — its internal
  effect only re-runs on leftNavMode/leftNavSection signal changes, never a width-only one
  (sidebarPx/leftNavDrawerPx are plain fields). LeftNavSeparatorHandle gained
  refreshAria(layout), called by applyEffectiveLeftNavigationLayout on every one of ITS OWN
  invocations too — harmless to call redundantly during the separator's own gesture.
• A pointer session is authoritative over a keyboard one, not the other way around, and
  neither may run concurrently. left-nav-separator.ts's onKeyDown ignores a keydown
  entirely (no preventDefault()) while session !== null — Tab-focusing the separator then
  mousedown-ing it too (focus survives a mousedown on an already-focused element) is a real,
  reachable way to have both an active pointer session AND keyboard focus at once; without the
  guard, a keypress mid-drag would commit a second, conflicting session while the original
  pointer session was still installed to overwrite it on its own eventual mouseup.
• The drawer's resize floor is 180px, not phase 1's placeholder 140px — settled, not just
  adjusted. A real-browser check (screenshots, both this phase's own e2e agent and the
  coordinator independently viewed them) confirmed the issue's own suspicion: at 140px the
  Dashboards section's three titles rendered as "Sa...", "O...", "A..." — unreadable and
  indistinguishable — while at 180px they read as "Sales re...", "Ops late...", "A very lo..." —
  still ellipsized, but genuinely usable. clampDrawerWidthPx's floor changed from
  LEFT_FOLD_THRESHOLD_PX (140) to LEFT_PANEL_MIN_PX (180), REUSING the wide sidebar's own
  floor constant rather than a second "180" — which is also what gives the drawer the wide
  band's dead-zone mechanism for free from the plain clamp, no new branch needed for the DRAG
  path (only the keyboard path needed one — see above).
• Both wide-mode switchers' tab buttons now carry data-section (sidebar-upper.ts,
  saved-history.ts) — needed to resolve "the corresponding tab" for focus restoration by a
  LIVE querySelector at the moment of a wide-conversion, never a cached reference, since both
  tab rows rebuild on every repaint.
• Per-section lower-navigation filters — reversed once during design, and the reversal
  matters. A first draft kept the wide sidebar's existing clear-on-switch behaviour and
  preserved state ONLY on the drawer path. A ChatGPT review caught this as producing
  presentation-DEPENDENT state (switch to History via the wide tab and the filter clears;
  switch via the rail and it doesn't; convert presentations and a "cleared" filter can
  resurface) — exactly the kind of bug the issue's "wide and focused presentations share and
  preserve all navigation state" bullet forbids. What shipped: BOTH presentations always
  preserve each section's own filter text; no presentation ever clears it on a plain switch.
  This is the phase's one deliberate, CHANGELOG-documented user-visible behaviour change to
  something phase 2 had pinned as "unchanged" — the phase-3 acceptance bullet supersedes
  phase 2's narrower gate for exactly this state, and phase 2's own handoff said as much.
• Two pre-existing "reveal" actions had to be updated for a hazard THIS phase introduced,
  not one they already had. file-menu.ts's revealDashboard and dashboard-tree.ts's
  revealAssignedPanel both wrote state.upperRole directly — always sufficient before this
  phase, since the sidebar was always the wide two-pane view. Once folding exists, folding the
  nav (or focusing a drawer on a different section) before triggering either action left the
  reveal's own expand/scroll/select work happening inside a hidden pane, invisible to the user.
  An independent post-implementation review caught this; both now route through
  openFocusedSection, which reduces to the identical upperRole write in wide mode (confirmed
  byte-for-byte unchanged there) and additionally opens/switches the drawer when folded.
  Any FUTURE code that reveals a Dashboard/Library/History item into the sidebar must go
  through openFocusedSection, never write upperRole/sidePanel directly — grep for both
  before adding a new caller.

Deviations from the spec, and why:

• No src/ui/left-drawer.ts — see ".sidebar is re-presented" above.
• No fifth splitters.ts axis — see "the separator replaces 'col' outright" above.
• The drawer's floor is 180px, not the issue's LEFT_FOLD_THRESHOLD_PX-adjacent 140px phase 1
  shipped as a placeholder — settled by the real-browser check the issue itself calls for
  ("adjustable only through real-browser layout verification").
• Both wide switchers gained a data-section attribute, not asked for by the issue — needed
  for focus restoration (see above).

Deferred acceptance criteria: bullet 7 (header, main surface and optional right inspector
resize correctly) — phase 4's. All other bullets (1–6, 8) are claimed and tested (unit + e2e).
Note for phase 4: there is no right inspector participating in layout today — the
cell-detail drawer is position: fixed and does not affect centre width — so bullet 7 is
header + centre reflow only, not a three-way interaction.

Both of phase 1's open questions, resolved:

1. Sampling-dependent restore memory — resolved by the three-layout resize session (see
   above). Verified by a dense-vs-coarse sampling sweep test that would have failed against
   BOTH of the two rejected earlier designs.
2. The drawer's floor — resolved at 180px (see above), with the measurement behind it
   recorded here and in the code's own comments.

Phase 2's open question, resolved (reversed, not merely closed): per-section lower filters
— see "Per-section lower-navigation filters" above.

Follow-ups filed: none new. #572 is closed by this PR.

Reconciled: roadmap #68 (phase 2 ticked shipped, phase 3 marked in review with #574), the
#487 body (phase-2 checkbox ticked; phase-3 section's description of left-drawer.ts/a
splitters.ts axis corrected to describe what was actually built), CHANGELOG.md
[Unreleased] (the feature becoming reachable, the drawer-floor change, the lower-filter
behaviour change, #572, the reveal-action fix).

Review — the most heavily reviewed phase of this issue so far: a Plan-agent design
review before any code was written (caught the drawer-band restore-memory gap the first draft
missed, a signal-vs-plain-number width hazard, a matchMedia-absent mobile hole, and a
[hidden]-vs-class-rule CSS footgun — all folded into the design before implementation); a
first ChatGPT PLAN review (caught the round-2 restore-memory design was still sampling-dependent
before a line of code existed for it, a render-architecture claim that didn't hold, and the
path-dependent filter design); three separate ChatGPT CODE reviews at successive
checkpoints, each against the real diff, each followed by verified fixes:

1. Steps 1–3 (the core resize session, the controller seam, the render split): found the
   round-3 restore-memory bug described above (commit 2a115f0).
2. Steps 4a–4b (the rail, the separator, the app-shell wiring): found the CSS cascade bug
   (.side-pane[hidden]/.side-tabs[hidden] had no override — confirmed the exact footgun
   this codebase already guards against elsewhere had been missed for these two classes),
   stale separator ARIA, the ResizeObserver-vs-active-session conflict, and the
   keyboard-vs-pointer session conflict (commit d6d6781).
3. The drawer-floor real-browser settlement pass surfaced a genuine WebKit-only focus bug
   (clicking a rail icon to close its own drawer didn't return focus to the icon on Safari,
   since WebKit doesn't focus a clicked button natively, unlike Chromium/Firefox) — fixed in
   the same commit that raised the drawer floor (7b487cd).
   Then two independent read-only passes (correctness; repo-fit) over the complete phase-3
   diff, post-implementation: repo-fit came back clean (layering, seams, coverage, and both of
   phase 1's open questions genuinely resolved, not just claimed); correctness found the
   reveal-action regression described above, confirmed and fixed (commit be9af64).

Finally, one more ChatGPT review of the complete PR #574 diff as it would actually be merged
(explicitly asked to look for interactions BETWEEN pieces the incremental rounds above each
reviewed separately, and for CHANGELOG/PR-body accuracy) found four more real, confirmed bugs,
each independently verified against the real code before fixing, then fixed together in commit
b80ae21:

1. leftNavSection (session-only, never persisted) could go stale across a visit to mobile
   width. Mobile's own wide-mode switchers write sidePanel/upperRole directly (mobile
   never has a drawer to keep in sync), so opening a drawer on desktop, shrinking to mobile,
   switching sections there, then widening back could show a drawer whose TITLE still named
   the section focused before the trip while its CONTENT reflected whatever the mobile
   switcher picked last.
2. An active resize session had no way to notice a mobile-breakpoint crossing under it — a
   documented, deliberately-deferred gap ("a narrow, transient visual glitch... out of scope
   for this fix") whose own deferral reasoning didn't always hold: if the eventual commit
   reproduced the same mode/section as before the drag, no signal changed, so nothing would
   ever re-correct the stale desktop paint the session's next mousemove could still apply
   over the forced mobile-wide presentation.
3. A resize session ending via blur/visibilitychange (tab-switch, backgrounding) rather
   than mouseup could commit against a budget measured before the viewport shrank mid-drag
   — onMouseUp re-clamps via its own advanceTo immediately before committing; the other two
   termination paths had no coordinate to re-clamp from and never had.
4. A non-monotone drag (past the wide threshold, back to a fold) could move focus on an
   intermediate frame instead of only the transition it actually commits to — the
   wide-conversion focus-restoration bookkeeping updated on every intermediate frame of an
   in-progress drag, not just the final commit, so a wiggling gesture could corrupt it either
   direction (suppressing a wanted restoration, or firing one prematurely mid-gesture).
   Bugs 1 and 2 share one fix location (an isMobile-transition handler that now cancels any
   active session and clears leftNavSection together); bug 3 added a re-clamp inside
   left-nav-separator.ts's endDrag(); bug 4 froze the focus-restoration bookkeeping behind
   leftNavSeparator.isSessionActive(). The same review also caught three CHANGELOG/PR-body
   accuracy issues, fixed directly rather than via a code-fixing agent: the controller seam
   (application/left-nav.ts) mislabeled as "phase 1/2's" when it's this phase's own new work;
   leftNavSection described as a "preference" alongside the genuinely-persisted leftNavMode,
   contradicting state.ts's own "session-only by design" comment; and an obsolete 'col'-axis
   CHANGELOG entry left in place after the axis it described was deleted (the entry pointing at it
   even said so, rather than the stale entry simply being removed). The PR body's checklist also
   overclaimed a README update that never happened — corrected to say why (no dedicated section for
   this feature yet; deferred to phase 4, once the full reflow story is complete).

The lesson this branch has now taught SEVEN times, worth internalizing before phase 4: a test
that asserts a value identical whether the code is right or wrong passes for free. Every review
round above that found something real also found at least one test that would have blessed its
absence, OR — this round's four bugs — a genuine coverage gap where no test exercised the
interaction at all (a mobile crossing mid-gesture, a non-monotone drag, a blur-terminated
session). Phase 4 should both sabotage-check its preservation/regression tests AND explicitly
enumerate cross-cutting interactions (viewport class × gesture state × mode) rather than testing
each dimension in isolation.