Skip to content

fix(sidebar): pin folder headers while scrolling the Sessions list - #14099

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/sidebar-sticky-folder-header
Sep 27, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/sidebar-sticky-folder-header

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Keep each folder's header, and its parents' headers, pinned at the top of the Sessions sidebar while you scroll through that folder's sessions.

In the Sessions sidebar a folder's header scrolls off the top of the list together with its sessions. Scrolled into a long folder, you can't tell which folder you are in. With a nested folder, both headers are gone.

Why it matters

Folders are how people group many sessions. Losing the header mid-scroll means scrolling back up to find the folder name, and the header's own controls (collapse, new session, folder menu) go with it.

Not a goal

  • Pinning headers in the board or column view. Only the Sessions list changes.
  • Capping how many ancestor headers pin in a deep folder tree.
  • Changing the folder header's look, such as adding a divider line under a pinned header.

What changed (motivation → approach → change)

Folder headers now stay pinned to the top of the list while their folder is on screen. The next folder's header takes over when the folder ends. A subfolder's header pins one row below its parent's, so the whole path stays readable.

The header row in ChatSidebar.tsx renderFolderHeader is position: sticky inside its own folder block, offset one 32px row per nesting depth, with shallower headers painted above deeper ones. The .folder-row-sticky rule in index.css gives the pinned row the sidebar card's own surface, so sessions don't show through it. That surface is --bg-elevated by default, --panel in kiro-light, and --bg in the /embed/sessions view, whose wrapper in ChatPage.tsx repaints the card and sets --folder-row-sticky-bg to match. The same rule holds the row at the 32px its offset assumes, because a default-agent badge or the rename input would otherwise make it taller and let the header below overlap it. The offset also subtracts the list's 8px top padding. Without that, the pinned row sat 8px low.

A row the arrow keys move to also lands below the pinned headers rather than behind them. Each folder block sets --folder-pin-stack to the height of the headers pinned above its rows, and session rows use it as scroll-margin-top. Chromium's scrollIntoView({ block: 'nearest' }) ignores that margin for a row already inside the list, so focusSiblingSessionRow in chat/sessionRowNav.ts re-aligns with block: 'start' when the row sits inside the margin band.

Dragging onto a pinned header lands in that header's folder. A pinned header paints over a subfolder block scrolled beneath it, while drag-and-drop still hit-tests the whole block rect. So sidebarCollision in ChatSidebar.tsx now checks first for a folder whose header row is under the pointer, and it measures the nest band from that header's live position.

Nested headers could not pin before: FolderBody.tsx clipped its inner box with overflow: hidden, which made that box the subfolder header's scroll container. It uses overflow: clip now, which clips the same way without creating a scroll container, with min-height: 0 so the collapse animation still works.

Backwards compatibility

Compatible: styling only. No API, stored data or prop contract changes, and the board/column view is untouched.

Tests

  • website/playwright/sidebar-sticky-folder-header.spec.ts (new) measures header positions in Chromium. The parent header sits on the list's top edge, the subfolder header exactly one row below it, the next folder takes over at the boundary, and the pinned row paints exactly the card's background. It runs on three surfaces: the default dark theme, kiro-light, and /embed/sessions. The parent folder has a default agent, so its badge is in the measured row. Without the ChatPage.tsx variable, the embedded case fails with the row one shade lighter than the card. On main this fails: both headers had scrolled 99px and 65px past the top, with a transparent background.
  • The same spec presses ArrowUp eight times inside the scrolled subfolder and checks each focused row sits below the pinned headers. Without the re-align, the fifth row lands 47px under them.
  • website/src/test/ChatSidebar.arrowNav.test.tsx checks that focusSiblingSessionRow re-aligns only a row inside its scroll margin, and leaves a clear row or a row with no margin where nearest put it.
  • website/src/test/ChatSidebar.stickyHeaderCollision.test.tsx (new) puts a subfolder block under its parent's pinned header. It checks that a session drag, a nested-folder drag and a root-folder nest drag on the parent header all resolve to the parent. The header's bottom edge is still a reorder edge, and a row below the headers still resolves to the subfolder. Three of the six cases fail without the collision change.
  • website/src/test/DesignTweakRequestsCov80.test.tsx checked for a collapsed request group by matching any hidden in the body's style, which the old overflow: hidden always satisfied. It now clicks the header twice, because a pending group starts open, and matches visibility: hidden.
  • website/src/test/ChatSidebar.collapsedFolderGhostHeight.test.tsx checks overflow: clip where it checked overflow: hidden.
  • sidebar-folder-alignment.spec.ts and the ChatSidebar vitest files still pass.

Manual verification

Checked on an isolated gateway in dark mode, kiro-light and /embed/sessions: scrolled through a parent folder, its subfolder and the next folder, moved through the subfolder with the arrow keys, and ran session-tags-folders.spec.ts for folder drag and drop. The spec saves lane stills when STICKY_EVIDENCE_DIR is set, which is how the screenshots below were taken. The spec restores the gateway's saved theme after each run. Header rows measure 32px with a badge, in an empty folder, on hover and while renaming.

Screenshots / video

Scrolled into the subfolder (dark): the parent and subfolder headers are both pinned.

Nested headers pinned, dark

Inside the next folder (dark): its header has taken the top.

Next folder takes over, dark

kiro-light, scrolled into the subfolder: the pinned rows use the card's --panel surface.

Nested headers pinned, kiro-light

/embed/sessions, scrolled into the subfolder: the pinned rows use the view's --bg surface.

Pinned headers in /embed/sessions

Related Issues

Fixes #14098

Pattern harvest

Not generalizable: a new sticky row needs a scroll container with no clipping ancestor in between. That is a layout property of this one tree, not a code pattern a rule could catch.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@Pearcekieser
Pearcekieser requested review from a team and pepmach September 26, 2026 03:09
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Intent: Keep the folder you are scrolling through identifiable in the Sessions sidebar list: its header, and every ancestor folder's header, stays pinned at the top until the folder's rows have scrolled past.
Not a goal: Pinning anything in the board/column view, changing folder row content or controls, or adding a breadcrumb.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 343d3296453781ed1da9cffe0af86f8ef93a0d45 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify pinned headers in Firefox/Safari once — every measurement and screenshot here is Chromium-only, and sticky-inside-overflow: clip is where engines diverge.

[DESIGN-REVIEWED] 343d329

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 343d3296453781ed1da9cffe0af86f8ef93a0d45 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 343d329

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — 🟡 CONCERNS

UX-level review of 343d3296453781ed1da9cffe0af86f8ef93a0d45 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

No blind reader has seen the pinned header stack, and the pinning/hand-off motion is evidenced only by static stills.

Watch

  • The pinned-header scroll behavior (pin, nested stack push-out, hand-off at a folder boundary) is scroll-linked motion a still cannot show; the mechanism in the diff is native position: sticky on the same node, so continuity is plausible, but a human has only measurements to go on. Frequency: every scroll of a foldered list; impact: low if native sticky behaves. Fix: attach a short recording of scrolling through the seeded A/B/C folders (the repo ships a browser-recording skill).
  • Collapsing a folder from its now-reachable pinned header while scrolled deep into its sessions is a new path this PR creates (the PR's own motivation names the collapse control), and no evidence shows where the lane's scroll lands after the block collapses. Occasional action, momentary disorientation if it jumps. Fix: verify manually and note the result in the description.

[UX-REVIEWED] 343d329

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 26, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/sidebar-sticky-folder-header branch from b467d4e to 51d020a Compare September 26, 2026 12:02
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Rendered evidence not admitted for a reshaped sidebar surface

fixed in 51d020a: the description now carries four github.com/user-attachments/assets images, replacing the fork-ref raw links the evidence step could not admit.
They show the parent and nested headers pinned and the next folder taking over (dark), the pinned stack in kiro-light, and the pinned stack in /embed/sessions.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • kiro-light pinned surface unverified

fixed in 51d020a: sidebar-sticky-folder-header.spec.ts runs on three surfaces (default dark, kiro-light, /embed/sessions) and asserts the pinned row's computed background equals the .sidebar-inner card's.
kiro-light passes as shipped. /embed/sessions did not: its wrapper repaints the card with --bg, so ChatPage.tsx now sets --folder-row-sticky-bg to match. Without that variable the embedded case fails, with the row one shade lighter than the card.
A kiro-light screenshot is in the description.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 343d3296453781ed1da9cffe0af86f8ef93a0d45 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

overflow: clip in FolderBody also reaches the board view and DesignTweak request groups — their collapse animation is only string-asserted, worth one manual look.

Not justified as shipped

  • Item 8 — rides along: the STICKY_EVIDENCE_DIR screenshot hook is evidence capture, not the fix; declared, opt-in, test-only, harm-free.

What this change ships

Inventory (9 items) — 8 justified

Intent: keep a folder's header (and its ancestors') visible while scrolling that folder's sessions — a FIX (linked issue #14098, spec fails on base with measured offsets).

  1. Folder headers pin to the Sessions list top; nested headers stack one row deeper per level — justified
  2. Pinned headers paint the card's own opaque surface on dark, kiro-light and /embed/sessions — justified
  3. Header rows held at 32px even with an agent badge or the rename input — justified
  4. Arrow-key and reveal focus land rows below the pinned headers, not behind them — justified
  5. Dropping on a pinned header files into that folder, not the one scrolled beneath — justified
  6. Folder bodies clip with overflow: clip in all three FolderBody render sites — justified
  7. New Playwright spec measuring the pins on three surfaces — justified
  8. Opt-in STICKY_EVIDENCE_DIR saves lane stills during the spec — rides along (evidence capture, not the fix)
  9. DesignTweak collapse test clicks twice and matches visibility: hidden exactly — justified

Verified against base: renderFolderHeader has exactly one call site (ChatSidebar.tsx:8406), no prior sticky mechanism exists (0 hits for sticky/folder-row-sticky in website/src), and the rewritten test's old assertion (toContain('hidden')) matched the ever-present overflow: hidden vacuously — the two-click cycle it now follows is already pinned on base by DesignTweakProjectRailCov80.test.tsx:751, so no prior decision is reversed. FolderBody consumer count: 3 render sites (ChatSidebar.tsx:7672, ChatSidebar.tsx:8408, DesignTweakPage.tsx:397), all receiving the clip change, hence the punchline.

[FIRST-PRINCIPLES-REVIEWED] 343d329

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 26, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/sidebar-sticky-folder-header branch from 51d020a to 7bafb43 Compare September 26, 2026 12:32
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

CI note for 7bafb43: on the previous head, two Frontend Tests failures were inherited from main. Both fail the same way on a detached origin/main at f6d8b7f, which is also this branch's base, and main's own CI run 36228967406 is red on the first one:

  • src/components/commandPalette/providers/settingsRegistry.test.ts (checked-in registry out of date, npm run gen:settings)
  • src/test/ChatPanel.railRegistry.test.tsx (page tags on Chat rail entries)

The third failure was this PR's. DesignTweakRequestsCov80.test.tsx "collapses/expands a request group" only passed because toContain('hidden') matched FolderBody's old overflow: hidden, so it never checked the collapse. It now clicks twice, because a pending group starts open, and asserts visibility: hidden.

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 343d3296453781ed1da9cffe0af86f8ef93a0d45 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 343d329

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 26, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Uncapped ancestor stacking with nesting depth

rebutted: a folder-depth bound exists. renderFolderBlock in website/src/pages/ChatSidebar.tsx returns [] when depth > 10, so nothing renders deeper than depth 10.
The sticky zIndex is FOLDER_ROW_STICKY_Z - depth = 20 - depth, so its floor is 10 and never reaches zero. Session rows set no z-index, so they cannot paint over any header.
The pinned stack at that bound is 11 rows (352px). That only happens while the user is scrolled inside an 11-level-deep folder, where the stack is the path they are in.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Drag onto a pinned header is only unit-tested with stubbed rects

accepted, with a manual check requested: ChatSidebar.stickyHeaderCollision.test.tsx fails 3 of its 6 cases without the collision change and passes all 6 with it. The existing folder drag-and-drop e2e specs, 15 tests in real Chromium, still pass on this head. None of them drags onto a header while it is pinned, so that path has no end-to-end coverage yet. A reviewer can check by hand: scroll into a subfolder until both headers pin, drag a session onto the parent's pinned header, and confirm it files into the parent.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Design Tweak request group needs two clicks to collapse

deferred: the dead first click comes from toggleReq in DesignTweakPage.tsx, a file this PR does not change. It exists on main today. The old toContain('hidden') assertion only hid it because it matched overflow: hidden. This PR's test change stops masking it and records the two-click cycle that main already has. The fix, passing the effective open state into the toggle, belongs to the Design Tweak app. It can land as its own small PR so this one doesn't re-run its lanes during the rate-limit window. Owner: Pearcekieser. Due: 2026-10-04.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

The code checks that still fail on 9f6fe0d are inherited from main. This PR only changes sidebar frontend files.

  • Backend Tests (3.12, 3) and Backend Tests (Windows) (3) fail in test_review_repair_routing_skill.py::test_slim_skills_do_not_regrow_duplicate_guidance_or_wire_model_ids[prepare-pr-68000] (68015 > 68000). Main's own CI run on this PR's base commit 94bcda2 (run 36299508386) fails the same shards.
  • Frontend Tests (1) fails in CrewWebviewContainment.test.tsx ("dates the retained document by the version on screen"). It fails the same way locally on a clean checkout of 94bcda2. Frontend Coverage Merge and Coverage Gate fail because that shard failed.

The PR description now has the Goal line and the "Not a goal" section that main's template requires, and PR Hygiene passes.

@Pearcekieser
Pearcekieser force-pushed the fix/sidebar-sticky-folder-header branch from 9f6fe0d to 5850d1b Compare September 27, 2026 08:54
@Pearcekieser
Pearcekieser requested a review from a team as a code owner September 27, 2026 08:54
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto current main as 5850d1b, which includes #14398, so the two inherited test failures should clear. The code is unchanged. CrewWebviewContainment.test.tsx and this PR's own test files pass locally on the new base (98 tests).

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 27, 2026
… scrolling

Folder header rows are position: sticky, stacked one row lower per nesting depth, with an opaque sidebar background. FolderBody clips with overflow: clip instead of hidden so nested headers stick to the scroll container.
@Pearcekieser
Pearcekieser force-pushed the fix/sidebar-sticky-folder-header branch from 5850d1b to 343d329 Compare September 27, 2026 10:26
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto current main as 343d329 to re-run CI. The code is unchanged. On 5850d1b, Backend Tests (3.12, 2) failed in test_ai_review_workflows.py::TestReviewLanesPublishOnlyTheReview::test_the_trim_and_count_execute_as_written. That test passes locally on both heads, and this PR only changes sidebar frontend files. All five review lanes passed on 5850d1b.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 27, 2026
@iamwhatever
iamwhatever enabled auto-merge (squash) September 27, 2026 17:32
@iamwhatever
iamwhatever merged commit db7d420 into kirodotdev:main Sep 27, 2026
100 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 27, 2026
NicholasRBowers pushed a commit that referenced this pull request Sep 27, 2026
FolderBody's grid item switched to overflow: clip in #14099 so nested
sticky headers pin to the lane. A clip box is not a scroll container, so
its automatic minimum width became the content's min-content width, and
the rows' single-line titles made every row in a folder as wide as its
longest title. Add min-width: 0 beside the existing min-height: 0.

Adds a real-Chromium spec for a long-titled row in a root folder, a
nested folder and unfiled, and raises the E2E executed-spec floor by one.

Fixes #14534
NicholasRBowers pushed a commit that referenced this pull request Sep 28, 2026
FolderBody's grid item switched to overflow: clip in #14099 so nested
sticky headers pin to the lane. A clip box is not a scroll container, so
its automatic minimum width became the content's min-content width, and
the rows' single-line titles made every row in a folder as wide as its
longest title. Add min-width: 0 beside the existing min-height: 0.

Adds a real-Chromium spec for a long-titled row in a root folder, a
nested folder and unfiled, and raises the E2E executed-spec floor by one.

Fixes #14534
NicholasRBowers added a commit that referenced this pull request Sep 28, 2026
FolderBody's grid item switched to overflow: clip in #14099 so nested
sticky headers pin to the lane. A clip box is not a scroll container, so
its automatic minimum width became the content's min-content width, and
the rows' single-line titles made every row in a folder as wide as its
longest title. Add min-width: 0 beside the existing min-height: 0.

Adds a real-Chromium spec for a long-titled row in a root folder, a
nested folder and unfiled, and raises the E2E executed-spec floor by one.

Fixes #14534

Co-authored-by: Nick Bowers <nrb@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Sessions sidebar: pin folder headers while scrolling a folder

2 participants