Skip to content

refactor(website): split ChatSidebar into composed chat-sidebar owners - #15094

Merged
chenmingwei23 merged 1 commit into
mainfrom
refactor/f07-chat-sidebar
Sep 30, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
refactor/f07-chat-sidebar

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The Sessions sidebar behaves exactly as it does today, while its code is split into small owners that each hold one job, so a person changing one sidebar behaviour reads and edits one file instead of an 11,000-line module.

website/src/pages/ChatSidebar.tsx was 11,197 lines, and one component function in it was 7,620 lines. That one function held every sidebar job inline:

  • the browser-stored view preferences;
  • the row sources, search, filters and lanes;
  • folders and the tag board;
  • drag and drop, reveal and session creation.

Twenty-two open PRs touched the file at the last audit, and a change to one behaviour means reading all of them.

Why it matters

Every sidebar fix today starts with reading the whole component and ends in merge conflicts with unrelated sidebar work. With one owner per job, a fix is found in one file, reviewed as one file, and conflicts only with work on the same job.

Not a goal

  • No behaviour, DOM, styling, copy, storage key, or keyboard/drag change. Every existing sidebar test passes unmodified except the five source-pin tests listed below, which now read the moved code in its new file.
  • No change to shared helpers the sidebar composes (pages/chat/*, utils/*, hooks/*, components/*), to ChatPage.tsx, or to the Redux store.
  • No move of SessionRow, the row and folder render functions, or the JSX: source pins, the restyle ratchet and the paint-order row stamp read them in ChatSidebar.tsx.
  • No baseline, locale, CSS or CI file edits.

What changed (motivation → approach → change)

Before After
ChatSidebar.tsx (on today's main) 11,272 lines, one 7,645-line function 6,822 lines, the component a 4,429-line composition
Owners none 23 modules under pages/chat-sidebar/ (largest 508 lines)
Public surface default memo(ChatSidebar), SIDEBAR_MIN/MAX, sidebarCollision, isFolderNestBand, boardSidebarWidth, label tables, sessionRowRenderProbe the same names, from the same path

The sidebar keeps running the same code in the same order. Each owner hook is the block that used to sit in the component, called where that block sat, so React runs every effect in the order it always did. A new test pins that call order, and pins that owners never import the facade, form no import cycle, and are imported by nothing outside the sidebar. That keeps every vi.mock('../pages/ChatSidebar') in the page tests replacing the whole sidebar.

Where a moved block reached into state another owner holds, that owner now offers one named action instead of handing out its setter: clearBoardCollapse for the board's per-column fold, widenForBoard and restorePreBoardWidth for the sidebar width. Their statements are the ones the call sites ran before.

What stays in ChatSidebar.tsx, and why:

  • SessionRow, the render closures, the filter-dimension registry, the peer adopt, the idle cleanup, the bulk model switch and the JSX.
  • Tests read them in that file: the switchSlot call-site count, list-shell parity, the bulk-switcher pin, the filter registry, the restyle ratchet.
  • The render closures also stamp rows in paint order, which the row memo depends on.

The owner map, and the pin behind each block that stays, are in docs/system-specs/modules/history.md ("The Sessions sidebar (frontend)"). The feature map names the new owner directory.

Backwards compatibility

Compatible: every exported name, the default export, and every mc-* storage key keep their spelling, values, defaults and migration; nothing that imports pages/ChatSidebar changes.

Tests

  • New characterization tests, written before the move and green on the base:
    • ChatSidebar.persistenceContract: every storage key, default, validator, legacy migration and throwing-storage fallback.
    • ChatSidebar.hapticTaps: each drag or reorder that taps, and each refusal or cancel that stays silent.
    • ChatSidebar.revealTimeline: when a reveal is consumed, filters cleared and the scroll lands.
    • ChatSidebar.collisionPinned: pinned-row collision winners.
    • ChatSidebar.unreadDrainFilter: the unread auto-drain under a filter.
  • test/ChatSidebar.ownerComposition.test.ts pins the owner graph, the hook call order, the re-exported bindings, that every storage key lives in persistence.ts (bar the four status-chip keys), and which owners read storage.
  • Five source-pin tests read the moved code where it now lives, at equal or wider strength, each red-checked:
    • laneFolderHideParity reads the lane union from types.ts.
    • revealFilterDimensions reads the reveal effect from reveal.ts.
    • dragSensors, chevronGrammar and hiddenFolderBoardTrace scan the facade plus every owner file.
  • Local results:
    • Related frontend set (run_scoped_tests.py): 406 files / 10,221 tests passed; sidebar integration 4 files / 69 passed.
    • Per-file line coverage: 93.7% for the facade, 88.9–100% for each owner.
    • tsc, eslint, jscpd, i18n, phantom-class, restyle ratchet, build, bundle-size and chunk-cycle checks, docs-lint and feature-map all pass; mypy is clean; Semgrep with CI's configs reports 0 findings.
    • npm run test:electron could not run here: this host has no website/electron/node_modules, and the diff touches no Electron file.
    • scripts/local-gate.py --dry-run selects 704 backend and 403 frontend files. The frontend set ran in full; the backend set is over this host's cap and the diff has no Python, so CI runs it.

Manual verification

N/A — unit coverage sufficient: the change moves code without changing behaviour. The characterization tests above were written against the unsplit file and pass unchanged after the move.

Screenshots / video

Why no screenshot: internal code move; the rendered sidebar, its DOM and its styling are byte-identical (the JSX and every row/folder render function are unchanged in ChatSidebar.tsx).

Related Issues

no linked issue: part of the frontend component-refactor campaign; builds on #14665 (chat Redux split) and precedes the ChatPage split.

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

@bolichen97
bolichen97 requested a review from a team September 29, 2026 18:53
@bolichen97
bolichen97 requested a review from a team as a code owner September 29, 2026 18:53
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the five characterization tests were green on the base commit as claimed — behaviour-preservation rests on that, and CI on this branch cannot re-check it.

[DESIGN-REVIEWED] 683e1ac

Description read

[DESCRIPTION-READ] 226038c4e0390f96c92830e5ac1b3f26b1d58a4966bd9a063a733b4b00b2adad

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 683e1ac

Description read

[DESCRIPTION-READ] 759000632ede284f7186778fc86617f6b3bd7d1b05757b8c6fdb046c4d0c1e18

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c — 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

Verify the no-behaviour-change claim's one unprovable premise: that the five characterization tests were green on the base commit before the move.

What this change ships

Inventory (7 items) — 7 justified

Intent: split the 11,197-line Sessions sidebar into one-job owner modules with zero behaviour change — an ADDITION of structure (a refactor), not a fix; harm is measured (22 open PRs touching one file).

  1. Sidebar blocks now live in 23 owner modules under pages/chat-sidebar/, composed by the same facade — justified
  2. Cross-owner setter handoffs replaced by three named actions (clearBoardCollapse, widenForBoard, restorePreBoardWidth; 2–5 counted consumers each) — justified
  3. Every exported name, default export and mc-* storage key keeps its spelling and import path — justified
  4. Five new characterization test files pin storage, haptics, reveal, drag-collision and unread-drain behaviour — justified
  5. A new composition test pins the owner graph, the 42-hook call order, and storage-key placement — justified
  6. Five existing source-pin tests re-read moved code in its new files, widened to scan the facade plus every owner (equal or wider, none weakened) — justified
  7. history.md gains the owner map; the feature map re-points its file references — justified (same-commit doc invariant)

[FIRST-PRINCIPLES-REVIEWED] 683e1ac

Description read

[DESCRIPTION-READ] 541dc683e49675e4ba398cc367bdb1326a9b4ad9a44041d0f8546c2c238d7551

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 683e1ac

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c: <one-sentence reason>

@bolichen97

Copy link
Copy Markdown
Contributor Author

First Principles note: evidence that the characterization tests pass on the base.

These five characterization files were run against the base commit's unsplit website/src/pages/ChatSidebar.tsx (df0ea79, 11,234 lines):

  • ChatSidebar.persistenceContract.test.tsx
  • ChatSidebar.hapticTaps.test.tsx
  • ChatSidebar.revealTimeline.test.tsx
  • ChatSidebar.collisionPinned.test.ts
  • ChatSidebar.unreadDrainFilter.test.tsx

They import only from ../pages/ChatSidebar, never from an owner module, so they run the same way against either tree.

git show df0ea7909:website/src/pages/ChatSidebar.tsx > website/src/pages/ChatSidebar.tsx
npx vitest run src/test/ChatSidebar.persistenceContract.test.tsx src/test/ChatSidebar.hapticTaps.test.tsx \
  src/test/ChatSidebar.revealTimeline.test.tsx src/test/ChatSidebar.collisionPinned.test.ts \
  src/test/ChatSidebar.unreadDrainFilter.test.tsx
 Test Files  5 passed (5)
      Tests  61 passed (61)
git checkout HEAD -- website/src/pages/ChatSidebar.tsx

The same 61 tests pass on this head, 7ee9671. ChatSidebar.ownerComposition.test.ts is not a characterization test. It pins the new owner layout, so by design it has no base counterpart.

The five retargeted source-pin tests (laneFolderHideParity, revealFilterDimensions, dragSensors, chevronGrammar, hiddenFolderBoardTrace) were each red-checked on this branch. A planted violation in an owner file makes each one fail.

@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 29, 2026
@bolichen97
bolichen97 force-pushed the refactor/f07-chat-sidebar branch from 7ee9671 to 617a025 Compare September 29, 2026 21:09
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 683e1ac

Verdict parsed from the review's SHA-scoped output markers for commit 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 683e1acbdafffb42dadbbf9fbb9c7cfa762f439c: <one-sentence reason>

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no

  • span=00c8d5ae639f rebutted: the three bare storage reads are main's existing behaviour, moved byte-for-byte; changing them is out of this refactor's goal

The same reads are on main in the unsplit file: 6d3ec50 website/src/pages/ChatSidebar.tsx:3475, 3477, 3618 and 4157.
They moved verbatim to persistence.ts:124/126, resize.ts:15 and filters.tsx:54, and the effect order is unchanged.
The frozen goal is "behaves exactly as it does today", and Not a goal lists "No behaviour ... storage key ... change".
Wrapping these reads would change what a storage-denied browser sees, so it is a behaviour change.
ChatSidebar.persistenceContract pins today's throwing-read fallbacks exactly as they were on main. It does not invent new ones.
Hardening the three initializers through safeGetItem is a separate fix PR, and it would add its own throwing-read cases.

@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 29, 2026
@bolichen97
bolichen97 force-pushed the refactor/f07-chat-sidebar branch from 617a025 to ab92334 Compare September 29, 2026 22:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 29, 2026
ChatSidebar.tsx was an 11,196-line module whose one component held the
sidebar's storage schema, row sources, filters, lanes, folder and board
state, drag and drop, reveal and session creation inline. Those
responsibilities now live in 23 owners under pages/chat-sidebar/, and
ChatSidebar.tsx composes them.

Each owner hook is the block that used to sit in the component, called
where the block was, so React runs the effects in the order it always
did. Where a block reached into state another owner holds, that owner
exposes one action instead of its setter: clearBoardCollapse for the
board's per-column fold, widenForBoard and restorePreBoardWidth for the
sidebar width. Deps arrays gained only stable setters and refs that
exhaustive-deps cannot see through a hook boundary. The facade keeps
its public surface (default memo(ChatSidebar), SIDEBAR_MIN/MAX,
sidebarCollision, isFolderNestBand, boardSidebarWidth and the rest) and
keeps SessionRow, the render closures, the filter-dimension registry,
the peer adopt, the cleanup, the bulk model switch and the JSX where
source pins and the restyle ratchet read them.

Characterization tests pin the storage contract, the haptic taps,
the reveal timeline, pinned-target collision and the unread drain;
ChatSidebar.ownerComposition pins the owner graph and the call order.
The source-pin tests that read moved code now read the owner files at
the same strength. The history spec gains the sidebar owner map, and
the feature map names the new owner directory.
@bolichen97
bolichen97 force-pushed the refactor/f07-chat-sidebar branch from ab92334 to 683e1ac Compare September 30, 2026 00:36
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 30, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 30, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Infra reruns under the campaign's SD21 rule: two jobs on 683e1ac failed before producing a verdict, and each run was rerun once with --failed.

  • Build, "Resolve desktop matrix" (run 36651162069, job 109685375388). The step dorny/paths-filter failed with "API rate limit exceeded for installation", request ID 3CE0:30C3:17B38BD:4E3276F:6ABC59D0, 2026-09-30 00:37:36 UTC.
  • Screenshot Evidence (run 36651162141, job 109685375221). "Could not read this PR's description from the API after 3 attempts, so the check cannot judge whether it carries evidence. This is a read failure, not missing evidence -- re-run this job."

Both reruns started after waiting more than 20 minutes for the installation rate limit to reset.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 30, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 30, 2026 01:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants