Initial public release of Warp.

Repo-Sync-Origin: warpdotdev/warp-internal@12af1d983b

specs/moirahuang/APP-3830/PRODUCT.md

@@ -0,0 +1,129 @@
+# APP-3830: Worktree Sidecar Selection Semantics
+
+Linear: `APP-3830` (inferred from the branch name)
+Related spec: `specs/moirahuang/APP-3743/PRODUCT.md`
+
+## Summary
+
+Polish the `New worktree config` sidecar so the repo that looks active is always the repo that executes. Mouse hover should take precedence over stale keyboard selection, repo clicks should consistently open a worktree, and keyboard confirmation from the search field should use the same visible selection model.
+
+## Problem
+
+The worktree sidecar currently mixes two concepts of "active repo":
+
+- keyboard selection, which is initialized so the search field can drive arrow-key navigation
+- hover state, which can move to a different repo row without updating the underlying actionable selection
+
+This creates confusing behavior:
+
+- two different repo rows can appear active at once
+- clicking a hovered repo can no-op or execute from stale state
+- `Enter` from the search field and mouse click do not reliably resolve the same repo
+
+The sidecar is intended to be a fast path for worktree creation, so ambiguity in selection makes the feature feel flaky and untrustworthy.
+
+## Goals
+
+- The hovered repo row becomes the active selection as soon as the user moves the mouse over it.
+- Mouse click and keyboard confirmation resolve the same repo the user sees as active.
+- The search field remains keyboard-focused without becoming an actionable repo selection.
+- `+ Add new repo` does not accidentally execute a previously selected repo.
+- Closing behavior remains predictable: selecting a repo closes both the sidecar and the parent menu.
+
+## Non-goals
+
+- Redesigning the unified new-session menu layout.
+- Changing how the default worktree tab config is authored or executed.
+- Reworking all Warp menus to use a new selection model.
+- Removing the search field or the pinned `+ Add new repo` footer.
+
+## Figma / design references
+
+Figma: none provided
+
+## User experience
+
+### Opening the sidecar
+
+When the user opens the `New worktree config` sidecar:
+
+- the search field is focused
+- the first actionable repo row is selected if at least one repo is available
+- if no repos are available, the search field and `+ Add new repo` footer still render and no repo row is selected
+
+### Keyboard behavior
+
+While the search field is focused:
+
+- `Down` moves selection to the next actionable repo row
+- `Up` moves selection to the previous actionable repo row
+- `Enter` opens a worktree for the currently selected repo
+- if no repo is selected but actionable repo rows exist, `Enter` first resolves the first actionable repo and opens it
+- if no actionable repo rows exist, `Enter` does nothing
+- `Escape` closes the sidecar and parent menu as it does today
+
+### Hover precedence
+
+If the user moves the mouse over a repo row:
+
+- that hovered repo row becomes the active selection immediately
+- any previously selected repo row stops being the effective active selection
+- subsequent click or keyboard confirmation uses the hovered repo row unless the user changes selection again
+
+Hover precedence only applies to actionable rows. Non-actionable rows such as the search row do not replace the current repo selection.
+
+### Mouse click behavior
+
+Clicking a repo row:
+
+- opens a worktree for that repo using the default worktree tab config
+- closes the sidecar
+- closes the parent new-session menu
+
+The clicked row should never no-op because of responder-chain routing or stale sidecar state.
+
+### Search behavior
+
+Typing in the search field filters repo rows live.
+
+When filtering changes the available repo list:
+
+- the filtered repo list updates immediately
+- if actionable rows remain, the first actionable repo row becomes selected
+- if no actionable rows remain, repo selection is cleared
+
+### Add new repo footer
+
+The pinned `+ Add new repo` footer remains visible while the repo list scrolls.
+
+Clicking it:
+
+- opens the folder picker
+- does not open a worktree for any repo
+- does not reuse stale repo selection as part of the click handling
+
+## Success criteria
+
+- At most one actionable repo row is treated as active at a time.
+- Hovering a repo row updates the underlying actionable selection, not just the visual hover state.
+- Clicking a repo row consistently opens a worktree for that repo.
+- `Enter` from the search field opens the same repo the UI currently presents as active.
+- The search field does not steal actionable selection when hovered.
+- `+ Add new repo` opens the picker without also opening a repo.
+- The sidecar closes cleanly after repo selection and leaves no stale selection state behind.
+
+## Validation
+
+- Unit-test hover precedence by starting with one selected repo, hovering a different repo row, and asserting the selected row changes to the hovered row.
+- Unit-test the close-via-select path to verify sidecar repo selection executes from `Workspace`.
+- Unit-test keyboard confirmation from the search editor to verify `Enter` opens the selected repo and closes the menu.
+- Manual validation:
+  - open `New worktree config`
+  - move selection with arrow keys
+  - hover a different repo row and confirm the active row updates
+  - click the hovered repo and verify the correct worktree tab opens
+  - click `+ Add new repo` and verify only the picker opens
+
+## Open questions
+
+None currently.