Skip to content

feat(dashboard): put an open side panel in the segment opposite the transcript beside a fold - #38238

Open
jeeshofone wants to merge 2 commits into
kirodotdev:mainfrom
jeeshofone:feat/fold-companion-pane
Open

jeeshofone wants to merge 2 commits into
kirodotdev:mainfrom
jeeshofone:feat/fold-companion-pane

Conversation

@jeeshofone

@jeeshofone jeeshofone commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #33546 (head 41ee2fd): review only the last commit. The diff includes #33546 until it merges. Merge order: #33463, #33546, this PR. The design decision is RFC #33463 (rfc-foldable-viewport-segments.md, status: draft). A phone-width composer is deferred to the Phase 3 chat page split, keyed on width.

Problem / Motivation

Goal: On a book-style foldable held half open, an open side panel takes the half of the screen opposite the chat, so the person sees the chat and the panel side by side.

With #33546 a folded iPhone Duo shows the list left and the chat right. An opened panel fills the chat column, so the chat is gone; a bottom dock crosses the fold.

Why it matters

On a phone you read what an agent produced while telling it what next. Half folded there are two halves for that; today the panel replaces the chat.

Not a goal

  • Dialogs, sheets, menus and toasts kept inside one segment (RFC Phase 2).
  • The laptop pose (two stacked segments).
  • The transcript's padding past a hinge gap with the panel closed (the chat page split, Phase 3).
  • Any change for a device that reports no fold.

What changed (motivation → approach → change)

The RFC gains "Book pose with the side panel open" and Phase 3b. An open panel takes the segment opposite the transcript and the list steps aside. Every rule needs a reported fold; the layout rules also need the full chat page, while the dock lock holds on any route and width, as a bottom dock crosses the fold anywhere.

  • lib/foldCompanion.ts: the rule, the panel width and fold gap, the layout on screen from the render a fold arrives (useFoldCompanionLayout), and the flag the shell reads.
  • page/sessionsDrawer.ts: sidebarOpen reads false while the layout shows. The stored pin is untouched.
  • page/paneLayout.tsx, page/ChatSidePanels.tsx: the panel never fills the chat column; it takes the trailing segment's width (panelFoldWidth), with no width reveal, and keeps a reported fold gap clear (panelFoldInset, plus the 8px reclaim in RTL). Widths stay inside the safe-area box (segmentContentWidth).
  • hooks/useSidePanelDock.ts, SidePanel.tsx: while folded the dock reads right, the stored mc-side-panel-dock is never written, and no dock toggle.
  • lib/layoutFormTransition.ts, styles/layout-morph.css: runPaneAllocationChange moves the transcript and composer inside the existing morph; the layout trails the store one render for the old snapshot; reduced motion snaps.
  • shell/appShell.tsx, sidebarWidth.ts: the rail stays compact; the transcript keeps 320px. The safe-inset change to foldSidebarWidth/foldHoldsRailCompact (feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546's split) is this PR's.
  • WebPreviewPanel.tsx: no expand toggle, since the segment sets the width; an expanded preview keeps Collapse.
  • messageActions.ts, sessionsDrawer.ts: the sessions toggle and a new reveal request close the panel and pin the list (foldYieldToList).
  • The panel's host across a fold (panelInlineHost) is in feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546's commit; here the inline panel takes the trailing segment.

Why not the panel in the leading segment: it would sit left of the chat (RFC alternatives).

Why a one-render lag: several store actions open the panel; one lag covers them.

Changed since review

Removed the phone composer form beside a fold (foldPhoneFormApplies, the phoneForm prop and hook argument, the edit-box rule, their four test files and the RFC lines). The composer, the edit box and the send key are #33546's on every fold.

Backwards compatibility

Every rule needs a reported fold. Chrome 138 and later report one on a book-style foldable without a flag, Android included; Safari needs its flags. With no fold, everything takes today's values.

Removes no value, key or path; the stored dock, pin and list width are read and kept. Take-aways for folded users: the dock toggle (a stored bottom dock is drawn at the right; both come back on unfold); with the panel open, the resize handle and the preview's expand control (back when the panel closes or on unfold) and the sessions list beside the panel (back when the panel closes).

Tests

  • src/test/foldCompanion.test.tsx: the rule; panel widths (tab, web app, RTL); fill suppressed, fold width and inset; the morph, the fold's first render, the touch-first sequence; the rail hold; reveals and the yield.
  • src/test/ChatPage.foldAppFrame.test.tsx: folded, the sessions toggle and a folder reveal close the panel so the list comes back (each fails without its yield).
  • src/test/App.foldRailHold.test.tsx: the real shell holds the rail compact with the panel open, not closed (fails without paneMin).
  • src/test/foldSafeInsets.test.tsx: a turn moving the inset re-sizes the list.
  • src/test/sidePanelDockFoldLock.test.ts, sidePanelDockToggleFold.test.tsx: folded, the dock reads right, storage untouched, no dock toggle; flat, both return.
  • src/lib/layoutFormTransition.test.ts: the morph's markers, the closing marker after the old snapshot, reduced motion and no API snap.
  • src/test/WebPreviewPanel.test.tsx: the expand toggle with and without the layout; an expanded preview keeps Collapse.
  • src/test/viewportSegmentsParity.test.ts: pins the closing rule to the fold two-pane query.
  • playwright/fold-companion-pane.spec.ts, playwright/helpers/fold.ts (CDP fold emulation; fold and unfold polled up to 2 s; MIN_EXECUTED_SPECS 257): meeting segments, a 20px hinge, RTL. Closed and open, each pane stays in its segment and nothing crosses the fold; a bottom dock stays stored. Fails with the rule off. A touch-first phone's Preview frame keeps its node, window and typed value across fold and unfold.

Proof: not provable -- frontend test (prove.py runs Python only)

Real-machine verification

N/A -- no physical foldable here. The Phase 0 probe readings and test table are in RFC #33463. A local run of playwright/fold-companion-pane.spec.ts was refused with 403 (no test token for this machine's gateway); CI run 44889049287 ran its 4 tests under MIN_EXECUTED_SPECS 257 with no skips allowed.

Manual verification

iPhone Duo simulator (iOS 27.2, Safari 27.2, flags on), demo data, book pose in a Safari tab, panel closed and open (shots below). The Preview shots use Chromium fold emulation.

Screenshots / video

Phase 3b's Home Screen capture is pending: there is no physical foldable here and the simulator rig's console is locked.

Recording (Chromium fold emulation, 951x537): Changes opens and closes, with reduced motion, then the sessions toggle.

book-pose-companion-pane.webm

Book pose, panel closed (the chat page split):

Book pose, panel closed

Book pose, panel open:

Book pose, panel open

Book pose with a Preview tab open (Chromium fold emulation): the panel starts at the fold, with no expand toggle.

Book pose, Preview tab open, no expand toggle

A preview expanded before folding, then folded: it keeps its Collapse control.

Book pose, preview expanded before folding, Collapse kept

Related Issues

Part of #29143

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

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@jeeshofone
jeeshofone requested review from a team and KiroCrewCaptain as code owners November 17, 2026 03:09
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Nov 17, 2026
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 5b8e80626a3a56c84578356270d2dc24f205f54d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: every rule is gated on a reported fold, the stored dock, pin and list width are read but never written, and screenshots plus a recording of this revision are attached.

Notes

[DESIGN-REVIEWED] 5b8e806

Description read

[DESCRIPTION-READ] 1f489343712b22c77058ad845aeec2fec2edd9d3edb797fb5e3eb65701698b4d

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 Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🔴 BLOCK

Premise-level review of 5b8e80626a3a56c84578356270d2dc24f205f54d 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 does not.

First-Principles-Verdict: BLOCK

product-shape change without accepted RFC: on unflagged Chrome 138+ foldables this changes where an open side panel goes and takes away the dock toggle, resize handle and preview expand. The only decision cited, rfc-foldable-viewport-segments.md, is draft on base.

What this change ships

Inventory (8 items) — 7 justified

Intent: on a half-open book-style foldable, show the chat and an open side panel side by side instead of the panel replacing the chat. ADDITION.

  1. With a fold reported and the panel open, the panel takes the trailing segment, the transcript the leading one, and the sessions list steps aside — justified
  2. Folded, the dock is forced to the right and the dock toggle is gone, with the stored dock kept — justified
  3. Folded, the panel's resize handle and the web preview's expand toggle are gone — justified
  4. The sessions toggle, the rail's chat item, the shortcut and list reveals close the panel and pin the list — justified
  5. The transcript and composer animate when the panel opens or closes beside a fold, and snap under reduced motion — justified
  6. The nav rail stays compact so the transcript keeps 320px — justified
  7. The panel keeps clear of a reported hinge gap — justified
  8. The RFC gains the "Book pose" section and Phase 3b — rides along, same-PR doc

Blockers

product-shape change without accepted RFC — Items 1–3
Trigger: "Folded, a stored bottom dock is drawn at the right with no dock toggle; with the panel open, no resize handle or preview expand". Chrome 138+ reports a fold "without a flag, Android included". The base RFC list has rfc-foldable-viewport-segments.md:status: draft.
Outcome: users on those devices get a new panel layout and lose three existing controls, with no maintainer decision recorded.
Clears when: an RFC covering the book-pose side-panel allocation and the withheld controls is merged non-draft on base, then you push or rebase; or a maintainer posts /ai-review override first-principles 5b8e80626a3a56c84578356270d2dc24f205f54d product-shape: <decision>.

[FIRST-PRINCIPLES-REVIEWED] 5b8e806

Description read

[DESCRIPTION-READ] 2c9eb445c6274a9bcd69650b7ef089c65fc1716dc7d2846ee601264936004ba4

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 Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of 5b8e80626a3a56c84578356270d2dc24f205f54d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. Screenshots cover the closed and open panel and both Preview states, and a recording covers the morph. This lane has no blind read; pushing the branch to this repository gets one.

Notes

  • RailBrandToggle with locked: the disabled brand mark still carries title/aria-label "Expand sidebar", which promises an action it won't do. Swap in a label that says the rail stays compact while the screen is folded, or drop the tip while it's locked.

[UX-REVIEWED] 5b8e806

Description read

[DESCRIPTION-READ] a7730a2c035b6a667a75a960fa447942fffd1dfc63c7769509701d7a4f3229ba

That sha256 names everything this verdict read: the PR description, plus the 7 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 Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 5b8e806

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 5b8e806

@jeeshofone
jeeshofone force-pushed the feat/fold-companion-pane branch from 4f48c6d to d6afe44 Compare November 17, 2026 04:26
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Rebased onto current main; the head is now d6afe44 (two commits: #33546's commit, then this PR's).

Why: on 4f48c6d the SAST (Semgrep) job reported five semgrep.kirocrew.test-shared-tmp-dir findings in test/test_acp_node_compile_cache_engine.py and test/test_mcp_footprint_stub_probe.py. Neither file is in this PR or in #33546. The diff-scoped scan compared against the old merge-base, so main's own later changes to those test files were scanned under a rule newer than that base.

Nothing in either commit changed: git range-diff shows only surrounding context lines from main moving, with no added or removed line of either patch changed. On the rebased head: type-check clean, the fold and nearby vitest suites pass (17 files, 299 tests), the Playwright fold spec passes (segments that meet, a masked hinge, right to left), and Semgrep with the repository rules, scoped to the changed lines, reports 0 findings.

@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 Nov 17, 2026
@jeeshofone
jeeshofone force-pushed the feat/fold-companion-pane branch from d6afe44 to ca1ed3d Compare November 17, 2026 05:33
@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 Nov 17, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Round 2, head ca1ed3d. #33546's commit is unchanged in the stack (range-diff =); this PR's commit changes only the hunks below.

Opus 5.5, BLOCKING fold-companion-pane.spec.ts, transcript read while the list animates: fixed. The panel-closed phase no longer reads once. It polls until the sessions list's fold-side edge sits at the fold (the list's animated width has settled), then polls until the transcript sits inside the trailing segment, the same way the open and closed-again phases already did. No fixed waits. The spec passed 9 of 9 local runs (three fold cases, three times).

GPT 6.1, F2 (sessionsDrawer.ts:442, the preview-expand end re-unpinning the list after a yield): fixed. The yield is now foldYieldToList in lib/foldCompanion.ts: it clears sidebarAutoHidden.current, then pins the list and closes the panel, as the title-menu, folder-chip and toggle paths already clear it. foldCompanion.test.tsx pins it; the test fails with the clearing line removed.

GPT 6.1, F1 (foldCompanion.ts, a folder reveal queued before the chat page mounts): declined, as the adjudication costed it. The hook records the request already in the store when the companion layout appears and does not replay it. That is what stops a stale request from closing every panel opened beside the fold. Telling a request dispatched just before navigating apart from an old one needs new state for that one path. The miss is a visible no-op: picking the folder again, or the sessions toggle, shows the list.

UX, recording of the transcript moving between halves and of the sessions toggle with the panel open. Attached to the description (https://github.com/user-attachments/assets/a9488836-f216-45ff-adc7-a2458da22cc9): a recording with the fold emulated in Chromium (CDP display features, the same harness as the Playwright spec) at the iPhone Duo's 951 by 537 book pose. It shows Changes opening and closing, the same with reduced motion on (the panes snap), and the sessions toggle with the panel open (the panel closes and the list returns). The simulator's console was unavailable for a capture on the device itself; that recording follows as a comment. The hover-tip note on the rail toggle is about RailBrandToggle's lock, which #33546 adds, so it is answered there.

First Principles, BLOCK on the premise (product-shape change without an accepted RFC). Facts for the maintainers:

This cannot be cleared in code. It waits on the maintainers' ruling on the RFC, alongside #33546.

First-pass check: R1-R8 OK.

@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 Nov 17, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the careful fold work. One thing must be fixed on this head before it can move forward.

  1. website/src/components/WebPreviewPanel.tsx:648: the preview toolbar's expand toggle is now wrapped in (!foldHoldsWidth || expanded). Beside a fold the toggle is hidden, and a preview that was already expanded keeps only Minimize. This is a user-visible control the PR changes, and nobody has seen it rendered. The UX review on this head says "cannot evaluate: missing the web preview toolbar in the fold layout". The two committed images (book-tab-panel-closed.png, book-tab-panel-open.png) both show the Changes tab, and the recording never opens a preview. Under the coverage rule in docs/ci/ci-and-reviews.md, a missing screenshot of a changed control is an evidence gap, so that review blocks. Smallest fix: add a book-pose screenshot with a Preview tab open and the expand toggle gone, plus one of a preview expanded before folding that still shows Minimize, under temp-screenshots/fold-companion-pane/. Reference both in the body. No code change is needed.

Optional:

  • This branch carries all of #33546. Please land #33546 first, then rebase so this diff is only the last commit. The design also waits on a maintainer's ruling on the draft fold-layout RFC, as you noted.
  • A test where the preview is already expanded when the fold layout appears, asserting that Minimize stays, would pin the expanded half of the condition.
  • The body says the Home Screen web-app capture will follow as a comment, and that comment has not been posted yet.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 17, 2026
@jeeshofone
jeeshofone force-pushed the feat/fold-companion-pane branch from ca1ed3d to 033a208 Compare November 17, 2026 23:02
@jeeshofone

Copy link
Copy Markdown
Contributor Author

@KiroCrewCaptain, answering your review of ca1ed3d (CHANGES_REQUESTED, 17 Nov 08:01 UTC). New head: 033a208.

Required (WebPreviewPanel.tsx:648, the preview toolbar's expand toggle beside a fold): done. Two captures are committed under temp-screenshots/fold-companion-pane/ and referenced in the description:

  • book-preview-no-expand.png: book pose with a Preview tab open. The panel starts at the fold and the toolbar has no expand toggle.
  • book-preview-expanded-keeps-collapse.png: a preview expanded while flat, then folded. It keeps its pressed Collapse control, so the expanded state can still be left.

Both rules sit behind the fold gate: the toggle is hidden only while the companion layout holds, and that layout needs a reported fold, which no shipping browser reports without its feature flag. With no fold the toolbar is unchanged. The simulator's console is still locked, so these were taken in Chromium with CDP fold emulation at the iPhone Duo's 951 by 537 book pose, as the recording was.

Taking the second capture found a real defect, fixed in the same commit. In the render a fold arrived, useFoldCompanionLayout still returned the old layout, so the open panel was drawn hidden for that render and the preview dropped its expanded state. The hook now returns the new layout in the render where the viewport moved. foldCompanion.test.tsx pins it and fails with the fix reverted.

Optional, a test with the preview already expanded when the fold layout appears: taken. WebPreviewPanel.test.tsx expands the preview, then turns the layout on, and asserts the pressed Collapse stays and no expand toggle appears. It fails with the expanded half of the condition removed.

Optional, land #33546 first and rebase: declined for now. #33546 waits on the maintainers' own ruling on its fold-at-640 precedence rule, so this branch stays stacked; only the last commit is this PR's. It will be rebased onto main once #33546 lands.

Optional, the Home Screen web-app capture: still owed. The rig's console is locked, so the capture is blocked. It follows as a comment once the console is available.

Please take another look when you have a moment.

@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 readiness: checking Automated validation is still running labels Nov 17, 2026
@jeeshofone
jeeshofone force-pushed the feat/fold-companion-pane branch from a42f383 to e993585 Compare November 20, 2026 19:33
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Restacked on #33546's 41ee2fd after main moved. Main's #23215 moved the touch Return rule into useComposerSendMode, so this commit now passes phoneForm into useComposerSendMode, which yields the phone Return key on a touch foldable, instead of setting sendOnEnter in ComposerDockView. Tests: ChatPage.foldSendKey.test.tsx (the phoneForm prop reaches the composer with the panel open and leaves with it closed) and composerSendMode.phoneForm.test.ts (the hook gives a new-line Return for a phone-width host on a touch device). The First Principles draft-RFC block remains the maintainers' decision on #39436.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 20, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Thanks for the steady follow-up. I checked the earlier review items on this head (e993585):

  • WebPreviewPanel.tsx:648, captures of the hidden expand toggle: fixed.
  • touchLayoutForm.ts, a fold reloads a live app in the side panel: fixed. The fix is in feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546's commit, and it is pinned by the same-iframe test.
  • rfc-foldable-viewport-segments.md, the RFC text contradicting the code: fixed.
  • Backwards compatibility text: fixed.
  • The RFC is still status: draft: still stands (see below).

This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

The decision is docs/request-for-change/rfc-foldable-viewport-segments.md:3, which is still status: draft with implementation-prs: []. On any book-style foldable on Chrome 138 or later in book pose, which report a fold with no flag, opening the panel moves the transcript and hides the sessions list. The dock is held at the right, and the dock toggle, the panel resize handle and the preview Expand control are hidden. A maintainer has to accept the RFC on main or record a decision on this head. Your 20 Nov comment points the decision at #39436, which is a different RFC. Please point maintainers at this RFC (#33463 / rfc-foldable-viewport-segments.md) instead.

The review found no correctness or security defect in this PR's own commit. The fold overrides read the stored dock, pin and width and never write them, so flattening the device restores the earlier layout.

Optional:

  • The phone composer form (sessionsDrawer.ts:746, lib/foldCompanion.ts:70-86, ChatInput.tsx:412 and :575) is still the part the First Principles lane objects to. With the panel open and every segment under 768px, Return inserts a newline instead of following the saved send key, and the composer changes form. With the panel closed at the same width it does not, so opening the panel flips what Return does. The Goal holds without it. Removing the phoneForm prop and the foldPhoneForm wiring, and proposing a phone-width composer with the Phase 3 chat page split, would make the maintainer's decision smaller.
  • The body has no ## Real-machine verification section, not even N/A -- <why>. The Phase 3b Home Screen web-app capture is still pending.
  • The dock lock in useSidePanelDock.ts:47-50 applies on any route and at any width while a fold is reported. The body says every rule needs the full chat page, so please correct that line.
  • No test covers the dock toggle that !dockLocked hides in SidePanel.tsx. One render test with a fold mocked would pin it.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Correction: my 20 Nov restack note pointed the design decision at #39436, which is a different RFC. The decision for this PR is RFC #33463, docs/request-for-change/rfc-foldable-viewport-segments.md, which is status: draft.

On head 61151d0:

  • The body now names docs(rfc): record the foldable layout's Phase 0 probe readings and test table #33463 as the decision.
  • The body's rule line now says what useSidePanelDock does. The dock lock holds on any route and at any width while a fold is reported, because a bottom dock crosses the fold wherever the panel is. The layout rules are the ones that need the full chat page.
  • The body has a ## Real-machine verification section: N/A, with no physical foldable here. The Phase 0 probe readings are in docs(rfc): record the foldable layout's Phase 0 probe readings and test table #33463, and the Phase 3b Home Screen capture is pending.
  • New test src/test/sidePanelDockToggleFold.test.tsx: the dock toggle is drawn with no fold and not drawn while a fold is reported, even with a stored bottom dock. It fails with !dockLocked removed from SidePanel.tsx. No other code changed.

@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 Nov 20, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Thanks for the 20 Nov follow-up. I checked my earlier review items on this head (61151d0):

  • WebPreviewPanel.tsx:648, captures of the hidden expand toggle: fixed.
  • touchLayoutForm.ts, a fold reloads a live app in the side panel: fixed in feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546's commit. The same-iframe test pins it.
  • rfc-foldable-viewport-segments.md, the RFC text contradicting the code: fixed.
  • Backwards compatibility text about reach without a flag: fixed.
  • The RFC is still status: draft: still stands. Editing the PR cannot clear this.

From my last comment, the body now names #33463 as the decision and says the dock lock holds on any route. It also has a ## Real-machine verification line. The new sidePanelDockToggleFold.test.tsx pins the hidden dock toggle.

This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Review result: this PR's own commit has no correctness or security defect. Every fold rule checks for a reported fold first. The dock, pin and width overrides read what is stored and never write it, so flattening the device brings back the earlier layout. The new tests wait on signals and never sleep. The Playwright spec binds port 0 and checks real pane geometry for three fold shapes. The merge order is still #33463, then #33546, then this PR.

Optional:

@jeeshofone
jeeshofone force-pushed the feat/fold-companion-pane branch from 61151d0 to e8383fb Compare November 21, 2026 02:16
@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 Nov 21, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Follow-up to @KiroCrewCaptain's review. The new head is e8383fb, restacked on #33546's 41ee2fd.

  • Restack SHA: the body now names 41ee2fd as the parent, replacing the stale 712bebb.
  • sidebarWidth.ts: the body now says that the safe-inset change to foldSidebarWidth and foldHoldsRailCompact belongs to this PR's commit, even though it changes feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546's list split.
  • Edit box Return (UserMessage.tsx): fixed. useReturnInsertsNewline(phoneForm) now holds the one rule, and useComposerSendMode derives from it. The edit box of an earlier message applies foldPhoneFormApplies to the companion state the full chat page publishes. Beside a fold on touch, Return now inserts a new line in both the composer and the edit box. ThreadPanel is unchanged because it renders only on the Members page. src/test/UserMessage.foldReturn.test.tsx fails if the edit box goes back to the plain hook. composerSendMode.phoneForm.test.ts pins the hook rule.

The design decision is still the maintainers' on RFC #33463 (status: draft).

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Nov 21, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Thanks for the 21 Nov follow-up. I checked my earlier review items on this head (e8383fb):

  • WebPreviewPanel.tsx:648, captures of the hidden expand toggle: fixed.
  • touchLayoutForm.ts, a fold reloads a live app in the side panel: fixed in feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546's commit. The same-iframe test pins it.
  • rfc-foldable-viewport-segments.md, the RFC text contradicting the code: fixed.
  • Backwards compatibility text about reach without a flag: fixed.
  • The RFC is still status: draft: still stands. Editing the PR cannot clear this.

This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Review result: this PR's own commit has no correctness or security defect. Every fold rule checks for a reported fold first. The dock, pin and width overrides read what is stored and never write it, so flattening the device brings back the earlier layout. The edit box now follows the same Return rule as the composer. The merge order is still #33463, then #33546, then this PR, and this head should be rebased to its last commit once #33546 lands.

For the maintainer's decision: the phone composer form (lib/foldCompanion.ts:74-86, sessionsDrawer.ts:746, ChatInput.tsx:412 and :575, UserMessage.tsx) is the part of the design that is hardest to justify. On a touch foldable whose segments are both under 768px, the transcript is one phone-width segment whether the panel is open or not. But only opening the panel switches the composer form and turns Return into a newline. Closing it brings the saved send key back. The trigger is panel state, not width. The Goal holds without it. Dropping it would remove one of the four items behind the First Principles block, and it could be proposed with the Phase 3 chat page split instead.

Optional:

  • src/test/ChatPage.foldSendKey.test.tsx:159 mocks ChatInput, so it only shows that the prop arrives. Reverting useComposerSendMode(phoneForm) at ChatInput.tsx:412 or || phoneForm at :575 leaves every test green. One render test of the real ChatInput that presses Enter would pin it.
  • playwright/helpers/fold.ts:43 and :53 read matches() once and skip the spec on a miss. Polling before you skip, or posting a run on this head that shows the 4 tests passed rather than skipped, would show the panel placement is checked.
  • The Phase 3b exit criteria need a Home Screen web app capture, and only the Safari tab and Chromium captures are committed. Add it, or narrow the criterion.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Follow-up to @KiroCrewCaptain's review. Round 24 changes only tests, the fold helper and the body; there is no production-code change.

  • src/test/ChatInput.foldPhoneForm.test.tsx: renders the real ChatInput, with no mock. On a touch device in the folded phone form, Enter inserts a new line and nothing is sent, and the trailing controls leave the control row. With no fold, Enter sends and the desktop form holds. Each revert fails its own test: dropping phoneForm from useComposerSendMode(phoneForm) (ChatInput.tsx:412) and dropping || phoneForm (:575).
  • playwright/helpers/fold.ts: both fold checks now poll the media query for up to 2 s at 100 ms before a route counts as inert. A late fold report no longer skips the spec.
  • Phase 3b Home Screen capture: still pending. There is no physical foldable here and the simulator rig's console is locked. The criterion is unchanged.
  • Phone composer trigger: the body now says the phone composer form follows the companion-panel state, not viewport width, because the composer's width is its pane's. It is flagged for RFC docs(rfc): record the foldable layout's Phase 0 probe readings and test table #33463, where that choice is decided.

The design decision is still the maintainers' on RFC #33463 (status: draft).

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Thanks for round 24. I checked this head (2641a70). One item needs a maintainer, and one item is a strong recommendation.

Earlier review items, checked on this head:

  • WebPreviewPanel.tsx, captures of the hidden expand toggle: fixed.
  • touchLayoutForm.ts, a fold reloads a live app in the side panel: fixed in the feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546 commit. The same iframe test pins it.
  • The RFC text contradicting the code: fixed.
  • Backwards compatibility text about reach without a flag: fixed.
  • ChatPage.foldSendKey.test.tsx mocked ChatInput: fixed. ChatInput.foldPhoneForm.test.tsx renders the real composer, and each revert fails its own case.
  • playwright/helpers/fold.ts skipped the spec on one missed read: fixed for withFold, which now polls.
  • The RFC is still status: draft: still stands. Only a maintainer can clear it.

docs/request-for-change/rfc-foldable-viewport-segments.md:3: the RFC is still status: draft. This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Review result: this PR's own commit has no correctness or security defect. Every fold rule checks for a reported fold first. The dock, pin and width overrides read what is stored and never write it, so flattening the device brings back the earlier layout. The merge order is still #33463, then #33546, then this PR. Rebase to the last commit once #33546 lands.

Optional:

  • Strongly recommended, not required (it was optional in earlier rounds, so it stays optional): website/src/lib/foldCompanion.ts:70-86: the phone composer form and the Return override go beyond the Goal. Trigger: a touch foldable on Chrome 138 or later, in book pose, with both segments under 768px, and the person opens any side panel on the full chat page. Outcome: foldPhoneFormApplies returns true, so sessionsDrawer.ts:746 passes foldPhoneForm through ChatPage.tsx and ComposerDockView.tsx to ChatInput. There, useComposerSendMode(phoneForm) (ChatInput.tsx:412) replaces the saved send key with a new line on Return, and useIsMobile() || phoneForm (:575) switches the composer to its phone form. UserMessage.tsx:202-205 applies the same rule to the edit box. With the panel closed, feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546 already gives the transcript one phone-width segment, and there the composer keeps the desktop form and the saved key. So at the same width, opening or closing the panel changes what Return does, and nothing on screen tells the person. I read your reason that the composer's width is its pane's width. The panel-closed state has the same pane width, so that reason does not explain why the trigger is the panel. The Goal is the panel sitting opposite the chat, and it holds without this. Smallest fix: delete foldPaneIsPhoneWidth and foldPhoneFormApplies, the foldPhoneForm value and its wiring, the phoneForm prop in ChatInput.tsx and chat-input/props.ts, the phoneForm parameter of useReturnInsertsNewline and useComposerSendMode, the fold lines in UserMessage.tsx, their four test files, the RFC bullet and the Backwards compatibility sentence about Return. The phone-width composer can then be proposed with the Phase 3 chat page split, keyed on width.
  • playwright/helpers/fold.ts:72: withoutFold reads the media query once after clearing the fold, but withFold polls for up to 2 s. A late unfold report would fail expect(await withoutFold(page)).toBeNull(). Polling for !matches before the clearDeviceMetricsOverride fallback would match withFold.
  • test/test_playwright_e2e.py:63: MIN_EXECUTED_SPECS is still 253. Raising it by the 4 new fold tests keeps the floor tracking them.
  • No test fails if the paneMin argument at appShell.tsx:534 or the useFoldCompanionYieldsToReveal call in sessionsDrawer.ts is removed. One ChatPage.foldAppFrame case that sends requestFolderReveal with the panel open would pin the yield.

…ranscript beside a fold

On a book-style foldable held half open, the chat page has three panes and
two segments. The transcript always holds one segment. An open side panel
takes the other at that segment's reported width, and the sessions list
steps aside without its pin changing. With the panel closed, the sessions
list and the transcript split at the fold as before.

While a fold is reported the panel never fills the chat column, docks right
without writing the stored dock, and is placed with no width reveal. The
transcript and composer move between segments inside the existing view
transition, which snaps under reduced motion. The rail stays compact so the
transcript keeps its minimum, a reported hinge gap is kept clear before
the panel, the preview's expand toggle is
not offered (an expanded preview keeps Collapse), and asking for the
sessions list closes the panel. The render a fold arrives in already
shows the new layout, so an open panel is never drawn hidden.

The panel picks its host from the form the device would have without a
fold, as of useIsMobile's last commit. A touch-first phone takes the desktop form when folded, and its
panel stays inline instead of moving to the shell's column, so folding
and unfolding keep the same panel and every live frame in it.

Pane widths beside a fold are each segment's part inside the shell's
safe-area box, so a safe-area inset never pushes a pane across the hinge.

The fold-aware layout RFC records the allocation and the rejected
alternative. With no fold reported nothing changes.

Part of kirodotdev#29143
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Follow-up to @KiroCrewCaptain's review. Round 25 removes the phone composer form.

  • Phone composer form: removed. That covers foldPaneIsPhoneWidth and foldPhoneFormApplies, the foldPhoneForm wiring through sessionsDrawer.ts, ChatPage.tsx and ComposerDockView.tsx, the phoneForm prop in ChatInput.tsx and chat-input/props.ts, the phoneForm parameter of useReturnInsertsNewline and useComposerSendMode (both files now match feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546's head), and the fold lines in UserMessage.tsx. The four test files that pinned it are gone, along with the RFC lines and the Backwards compatibility sentence about Return. Beside a fold, the composer, the edit box and the send key now behave as in feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546, panel open or closed. A phone-width composer is left to the Phase 3 chat page split, keyed on width.
  • playwright/helpers/fold.ts: withoutFold now polls for the unfold for up to 2 s before the clearDeviceMetricsOverride fallback, the same way withFold polls for the fold.
  • test/test_playwright_e2e.py: MIN_EXECUTED_SPECS is 257, which counts the 4 fold tests.
  • Yield pins: ChatPage.foldAppFrame.test.tsx has a case that sends requestFolderReveal with the panel open, and it fails without the useFoldCompanionYieldsToReveal call. ChatPage does not render the shell, so src/test/App.foldRailHold.test.tsx renders the real shell and nav rail instead. It fails without the paneMin argument to foldHoldsRailCompact.

The design decision is still the maintainers' on RFC #33463 (status: draft).

@jeeshofone

Copy link
Copy Markdown
Contributor Author

On the First Principles review's product-shape item: round 25 removes the send-key half. The phone composer form beside a fold is gone. The phoneForm prop and hook argument, the edit-box rule, their tests and the RFC lines were all removed. On a touch foldable the saved send key and the desktop composer now apply with the panel open or closed, as in #33546. A phone-width composer is left to the Phase 3 chat page split, keyed on width.

The remaining fold rules (the panel in the trailing segment, the dock drawn right, no resize handle or preview expand beside the fold) are still for the maintainers to decide on RFC #33463 (status: draft). No override is asked.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Earlier review items, checked on this head (5b8e806):

  • WebPreviewPanel.tsx, captures of the hidden expand toggle: fixed.
  • touchLayoutForm.ts, a fold reloads a live app in the side panel: fixed. The same-iframe tests pin it.
  • The RFC text contradicting the code: fixed.
  • The Backwards compatibility text about reach without a flag: fixed.
  • The phone composer form and the Return override: removed. No foldPhoneForm or foldPaneIsPhoneWidth is left in website/src.
  • withoutFold reading the fold once: fixed. It now polls, the same way withFold does. MIN_EXECUTED_SPECS is 257.
  • rfc-foldable-viewport-segments.md:3, the RFC is still status: draft: still stands. Only a maintainer can clear it, by accepting the RFC on main or by recording a decision on this head.

Review result: this head has no correctness or security defect. Every fold rule checks for a reported fold first. The dock, pin and list width are read and never written, so flattening the device brings back the earlier layout. The Playwright spec checks real pane geometry in LTR, RTL and with a hinge gap. The merge order is still #33463, then #33546, then this PR. The second of #40358 and this stack to merge will need to pass the fold width into the single kept SidePanel in ChatSidePanels.tsx.

Optional:

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Follow-up to @KiroCrewCaptain's review. The head is unchanged; this round edits only the body.

  • Backwards compatibility: it no longer says "Compatible". It now lists what folded users lose: the dock toggle (a stored bottom dock is drawn at the right) and, with the panel open, the resize handle, the preview's expand control and the sessions list beside the panel.
  • Real-machine verification: still N/A, because there is no physical foldable here. A local run of fold-companion-pane.spec.ts was refused with 403, since this machine's gateway has no test token. The body cites CI run 44889049287, which ran the spec's 4 tests under MIN_EXECUTED_SPECS 257 with no skips allowed.
  • sidebarWidth.ts inset: it stays in this PR. It imports segmentContentWidth from this PR's lib/foldCompanion.ts (sidebarWidth.ts:8), so it cannot move to feat(dashboard): add the fold-detection primitives from the foldable layout RFC #33546 on its own.

The design decision is still the maintainers' on RFC #33463 (status: draft).

This branch has not been deployed

No deployments
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) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants