From 2a23d128905914661eecd25ff970b202f55a5b25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Sat, 5 Sep 2026 10:26:55 +0000 Subject: [PATCH] fix(web): make passthrough composer touch-safe (#2809) (#3303) --- .../task/chat/chat-input-toolbar-mobile.tsx | 17 +- .../chat/chat-input-toolbar-primitives.tsx | 35 ++- .../task/chat/chat-input-toolbar.test.tsx | 60 +++- .../task/chat/chat-input-toolbar.tsx | 3 + .../task/chat/implement-plan-button.test.tsx | 45 +++ .../task/chat/implement-plan-button.tsx | 207 ++++++++----- .../task/passthrough-toolbar.test.tsx | 81 +++-- .../components/task/passthrough-toolbar.tsx | 70 +++-- .../mobile-passthrough-composer.spec.ts | 276 +++++++++++++++++- .../plans/mobile-passthrough-composer/plan.md | 70 +++++ .../task-01-touch-safe-mobile-controls.md | 79 +++++ ...-passthrough-mobile-regression-coverage.md | 80 +++++ docs/specs/cli/README.md | 6 +- .../mobile-passthrough-composer.md | 89 ++++++ .../mobile-passthrough-composer.md | 141 +++++++++ 15 files changed, 1110 insertions(+), 149 deletions(-) create mode 100644 apps/web/components/task/chat/implement-plan-button.test.tsx create mode 100644 docs/plans/mobile-passthrough-composer/plan.md create mode 100644 docs/plans/mobile-passthrough-composer/task-01-touch-safe-mobile-controls.md create mode 100644 docs/plans/mobile-passthrough-composer/task-02-passthrough-mobile-regression-coverage.md create mode 100644 docs/specs/cli/requirements/mobile-passthrough-composer.md create mode 100644 docs/specs/cli/system-design/mobile-passthrough-composer.md diff --git a/apps/web/components/task/chat/chat-input-toolbar-mobile.tsx b/apps/web/components/task/chat/chat-input-toolbar-mobile.tsx index 61eeb8656a..5a63a846b3 100644 --- a/apps/web/components/task/chat/chat-input-toolbar-mobile.tsx +++ b/apps/web/components/task/chat/chat-input-toolbar-mobile.tsx @@ -54,6 +54,7 @@ type MobileToolbarProps = { submitShortcut: (typeof SHORTCUTS)[keyof typeof SHORTCUTS]; composerCapability?: PluginComposerCapability; composerSurface?: "task-chat" | "quick-chat"; + presentation?: "desktop" | "mobile"; }; type MobileLeftActionsProps = MobileToolbarProps & { @@ -61,13 +62,13 @@ type MobileLeftActionsProps = MobileToolbarProps & { onResetConfirmationOpenChange: (open: boolean) => void; }; -function mobileContextButton(contextCount: number) { +function mobileContextButton(contextCount: number, presentation: "desktop" | "mobile") { return ( , + ImplementPlanButton: ({ presentation = "desktop" }: { presentation?: "desktop" | "mobile" }) => ( + + ), })); vi.mock("./reset-context-button", () => ({ @@ -109,6 +113,7 @@ import type { ChatInputToolbarProps } from "./chat-input-toolbar"; const MOBILE_TOOLBAR_TEST_ID = "mobile-chat-input-toolbar"; const CANCEL_AGENT_BUTTON_TEST_ID = "cancel-agent-button"; +const SUBMIT_MESSAGE_BUTTON_TEST_ID = "submit-message-button"; const SESSION_TIMESTAMP = "2026-01-01T00:00:00Z"; function deferred() { @@ -290,7 +295,7 @@ describe("ChatInputToolbar cancel button", () => { renderFullToolbar({ isAgentBusy: true, canCancelAgent: false }); expect(screen.queryByTestId(CANCEL_AGENT_BUTTON_TEST_ID)).toBeNull(); - expect(screen.getByTestId("submit-message-button")).toBeTruthy(); + expect(screen.getByTestId(SUBMIT_MESSAGE_BUTTON_TEST_ID)).toBeTruthy(); expect(screen.getByText("Queue message")).toBeTruthy(); }); @@ -367,12 +372,61 @@ describe("ChatInputToolbar submit button", () => { , ); - expect((screen.getByTestId("submit-message-button") as HTMLButtonElement).disabled).toBe(true); + expect((screen.getByTestId(SUBMIT_MESSAGE_BUTTON_TEST_ID) as HTMLButtonElement).disabled).toBe( + true, + ); expect(screen.getByText("The agent is still being set up.")).toBeTruthy(); }); }); describe("ChatInputToolbar responsive wrapper", () => { + it("gives mobile composer controls 44px touch targets", () => { + responsiveMock.breakpoint = "mobile"; + renderFullToolbar({ + hidePlanMode: false, + isAgentBusy: true, + canCancelAgent: true, + }); + + for (const testId of [ + "plan-mode-toggle-button", + "chat-attachments-button", + "chat-context-button", + "cancel-agent-button", + SUBMIT_MESSAGE_BUTTON_TEST_ID, + ]) { + const control = screen.getByTestId(testId); + expect(control.className).toContain("min-h-11"); + expect(control.className).toContain("min-w-11"); + } + }); + + it("keeps compact composer geometry on desktop", () => { + responsiveMock.breakpoint = "desktop"; + renderFullToolbar({ hidePlanMode: false }); + + for (const testId of [ + "plan-mode-toggle-button", + "chat-attachments-button", + "chat-context-button", + SUBMIT_MESSAGE_BUTTON_TEST_ID, + ]) { + const control = screen.getByTestId(testId); + expect(control.className).toContain("h-7"); + expect(control.className).not.toContain("min-h-11"); + expect(control.className).not.toContain("min-w-11"); + } + }); + + it("passes the touch presentation to plan implementation on tablets", () => { + responsiveMock.breakpoint = "tablet"; + renderFullToolbar({ planModeEnabled: true, onImplementPlan: () => {} }); + + expect(screen.getByTestId("mock-implement-plan-button").getAttribute("data-presentation")).toBe( + "mobile", + ); + }); + it("routes mobile breakpoints to the compact toolbar without a duplicate sessions control", () => { responsiveMock.breakpoint = "mobile"; renderFullToolbar(); diff --git a/apps/web/components/task/chat/chat-input-toolbar.tsx b/apps/web/components/task/chat/chat-input-toolbar.tsx index 2aa5a00806..9d4908b2ff 100644 --- a/apps/web/components/task/chat/chat-input-toolbar.tsx +++ b/apps/web/components/task/chat/chat-input-toolbar.tsx @@ -179,6 +179,9 @@ export const ChatInputToolbar = memo(function ChatInputToolbar(rawProps: ChatInp submitShortcut={submitShortcut} composerCapability={props.composerCapability} composerSurface={props.composerSurface} + presentation={ + responsiveBreakpoint.isMobile || responsiveBreakpoint.isTablet ? "mobile" : "desktop" + } /> ); } diff --git a/apps/web/components/task/chat/implement-plan-button.test.tsx b/apps/web/components/task/chat/implement-plan-button.test.tsx new file mode 100644 index 0000000000..ec72c89088 --- /dev/null +++ b/apps/web/components/task/chat/implement-plan-button.test.tsx @@ -0,0 +1,45 @@ +import { cleanup, render, screen } from "@testing-library/react"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { ImplementPlanButton } from "./implement-plan-button"; + +vi.mock("@kandev/ui/tooltip", () => ({ + Tooltip: ({ children }: { children: React.ReactNode }) => <>{children}, + TooltipContent: ({ children }: { children: React.ReactNode }) => <>{children}, + TooltipTrigger: ({ children }: { children: React.ReactNode }) => <>{children}, +})); + +vi.mock("@kandev/ui/dropdown-menu", () => ({ + DropdownMenu: ({ children }: { children: React.ReactNode }) => <>{children}, + DropdownMenuContent: ({ children }: { children: React.ReactNode }) => <>{children}, + DropdownMenuItem: ({ children }: { children: React.ReactNode }) => <>{children}, + DropdownMenuTrigger: ({ children }: { children: React.ReactNode }) => <>{children}, +})); + +vi.mock("react-i18next", () => ({ + useTranslation: () => ({ t: (key: string) => key }), +})); + +afterEach(cleanup); + +describe("ImplementPlanButton presentation", () => { + it("gives both split-button controls touch-safe geometry on mobile", () => { + render(); + + for (const testId of ["implement-plan-button", "implement-plan-menu-trigger"]) { + const control = screen.getByTestId(testId); + expect(control.className).toContain("min-h-11"); + expect(control.className).toContain("min-w-11"); + } + }); + + it("keeps both split-button controls compact by default", () => { + render(); + + for (const testId of ["implement-plan-button", "implement-plan-menu-trigger"]) { + const control = screen.getByTestId(testId); + expect(control.className).toContain("h-7"); + expect(control.className).not.toContain("min-h-11"); + expect(control.className).not.toContain("min-w-11"); + } + }); +}); diff --git a/apps/web/components/task/chat/implement-plan-button.tsx b/apps/web/components/task/chat/implement-plan-button.tsx index b14aba4c47..b8813d8c7f 100644 --- a/apps/web/components/task/chat/implement-plan-button.tsx +++ b/apps/web/components/task/chat/implement-plan-button.tsx @@ -21,6 +21,7 @@ import { useTranslation } from "react-i18next"; */ type ImplementPlanButtonProps = { onClick: (fresh: boolean) => void | Promise; + presentation?: "desktop" | "mobile"; disabled?: boolean; disabledReason?: string; framed?: boolean; @@ -32,10 +33,28 @@ type ImplementPlanButtonProps = { }; }; +type ImplementPlanPresentation = "desktop" | "mobile"; + function legacyRootTestId(rootId: string) { return rootId === "implement-plan-control" ? undefined : "implement-plan-control"; } +function controlSizeClass(presentation: ImplementPlanPresentation, framed?: boolean): string { + if (presentation === "mobile") return "min-h-11 min-w-11"; + if (framed) return "h-5"; + return "h-7"; +} + +function disabledInteractionClass(disabled?: boolean): string { + return disabled ? "pointer-events-none cursor-not-allowed" : "cursor-pointer"; +} + +function framedRootClass(framed?: boolean): string | undefined { + return framed + ? "border border-violet-400/35 bg-background/40 focus-within:ring-[2px] focus-within:ring-violet-400/25" + : undefined; +} + function DisabledImplementTooltip({ disabledReason, children, @@ -57,95 +76,39 @@ function DisabledImplementTooltip({ export function ImplementPlanButton({ onClick, + presentation = "desktop", disabled, disabledReason, framed, testIds, }: ImplementPlanButtonProps) { - const { t } = useTranslation(); const ids = { root: testIds?.root ?? "implement-plan-control", button: testIds?.button ?? "implement-plan-button", menuTrigger: testIds?.menuTrigger ?? "implement-plan-menu-trigger", freshItem: testIds?.freshItem ?? "implement-fresh-menu-item", }; - const controlHeightClass = framed ? "h-5" : "h-7"; - const primaryButton = ( - - - - ); - const primary = disabledReason ? ( - primaryButton - ) : ( - - {primaryButton} - {t("task:implementThePlanInThisSession")} - - ); + const controlSize = controlSizeClass(presentation, framed); const splitButton = (
- {primary} - - - - - - onClick(true)} - className="cursor-pointer" - > - -
-
{t("task:implementInFreshAgent")}
-
- {t("task:startsANewSessionWithA")} -
-
-
-
-
+ +
); @@ -157,3 +120,101 @@ export function ImplementPlanButton({ ); } + +function ImplementPrimaryButton({ + buttonId, + controlSize, + disabled, + disabledReason, + onClick, +}: { + buttonId: string; + controlSize: string; + disabled?: boolean; + disabledReason?: string; + onClick: (fresh: boolean) => void | Promise; +}) { + const { t } = useTranslation(); + const button = ( + + + + ); + if (disabledReason) return button; + return ( + + {button} + {t("task:implementThePlanInThisSession")} + + ); +} + +function ImplementMenuButton({ + controlSize, + disabled, + freshItemId, + menuTriggerId, + onClick, +}: { + controlSize: string; + disabled?: boolean; + freshItemId: string; + menuTriggerId: string; + onClick: (fresh: boolean) => void | Promise; +}) { + const { t } = useTranslation(); + return ( + + + + + + onClick(true)} + className="cursor-pointer" + > + +
+
{t("task:implementInFreshAgent")}
+
+ {t("task:startsANewSessionWithA")} +
+
+
+
+
+ ); +} diff --git a/apps/web/components/task/passthrough-toolbar.test.tsx b/apps/web/components/task/passthrough-toolbar.test.tsx index a9332068cd..a675d16658 100644 --- a/apps/web/components/task/passthrough-toolbar.test.tsx +++ b/apps/web/components/task/passthrough-toolbar.test.tsx @@ -1,6 +1,10 @@ +/* eslint-disable max-lines -- this suite covers the toolbar's desktop and mobile interaction surfaces. */ import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +afterEach(cleanup); +beforeEach(resetMocks); + // --- Constants declared before vi.mock so factories can reference them --- const TASK_ID = "task-1"; const SESSION_ID = "session-1"; @@ -23,11 +27,15 @@ const TID_PENDING_BANNER = "passthrough-pending-comments-banner"; const TID_PLAN_TOGGLE = "plan-mode-toggle-button"; const TID_ATTACHMENTS = "chat-attachments-button"; const TID_CONTEXT = "chat-context-button"; +const TID_SEND_COMMENTS = "passthrough-send-comments"; // --- Mutable state for per-test overrides --- let mockSessionState: string | null = null; let mockKeyboardShortcuts: Record }> = {}; +const responsiveMock = vi.hoisted(() => ({ + breakpoint: "desktop" as "mobile" | "tablet" | "desktop", +})); let mockPendingByFile: Record = {}; let mockPlanModeEnabled = false; let mockImplementPlanHandler: ((fresh: boolean) => void) | undefined; @@ -113,7 +121,8 @@ vi.mock("@/hooks/use-file-editors", () => ({ vi.mock("@/hooks/use-responsive-breakpoint", () => ({ useResponsiveBreakpoint: () => ({ - isMobile: false, + isMobile: responsiveMock.breakpoint === "mobile", + isTablet: responsiveMock.breakpoint === "tablet", isFinePointer: mockIsFinePointer, }), })); @@ -291,6 +300,7 @@ async function openComposer() { function resetMocks() { mockSessionState = null; mockKeyboardShortcuts = {}; + responsiveMock.breakpoint = "desktop"; mockPendingByFile = {}; mockPlanModeEnabled = false; mockImplementPlanHandler = undefined; @@ -317,8 +327,6 @@ function latestPassthroughTerminalProps(): { enableTouchScroll?: boolean } { // --------------------------------------------------------------------------- describe("PassthroughToolbar – default state", () => { - afterEach(cleanup); - it("renders the toolbar and hides the composer when session is idle", () => { mockSessionState = "IDLE"; renderToolbar(); @@ -353,6 +361,52 @@ describe("PassthroughToolbar – default state", () => { }); }); +function renderStatusRow(breakpoint: "mobile" | "tablet" | "desktop") { + responsiveMock.breakpoint = breakpoint; + mockSessionState = "IDLE"; + mockPendingByFile = { [SRC_FILE]: [makeDiffComment("c1")] }; + mockNextStep = { proceedStepName: "Review", proceed: vi.fn(), isMoving: false }; + renderToolbar(); +} + +function expectTouchSized(testId: string) { + const control = screen.getByTestId(testId); + expect(control.className).toContain("min-h-11"); + expect(control.className).toContain("min-w-11"); +} + +function expectCompactSized(testId: string) { + const control = screen.getByTestId(testId); + expect(control.className).toContain("h-6"); + expect(control.className).not.toContain("min-h-11"); + expect(control.className).not.toContain("min-w-11"); +} + +async function expectCommentSendSize(touchSized: boolean) { + fireEvent.click(screen.getByTestId(TID_TOGGLE_COMMENTS)); + await waitFor(() => expect(screen.getByTestId(TID_COMMENTS_PANEL)).toBeTruthy()); + if (touchSized) expectTouchSized(TID_SEND_COMMENTS); + else expectCompactSized(TID_SEND_COMMENTS); +} + +describe("PassthroughToolbar – mobile touch targets", () => { + it("sizes status and comment-send controls for touch without changing desktop geometry", async () => { + renderStatusRow("mobile"); + for (const testId of [TID_TOGGLE, TID_TOGGLE_COMMENTS, TID_PROCEED]) expectTouchSized(testId); + await expectCommentSendSize(true); + + cleanup(); + renderStatusRow("desktop"); + for (const testId of [TID_TOGGLE, TID_TOGGLE_COMMENTS, TID_PROCEED]) expectCompactSized(testId); + await expectCommentSendSize(false); + }); + + it("sizes status controls for coarse-pointer tablets", () => { + renderStatusRow("tablet"); + for (const testId of [TID_TOGGLE, TID_TOGGLE_COMMENTS, TID_PROCEED]) expectTouchSized(testId); + }); +}); + describe("PassthroughToolbar – touch-scroll activation", () => { beforeEach(resetMocks); afterEach(cleanup); @@ -379,9 +433,6 @@ describe("PassthroughToolbar – touch-scroll activation", () => { // --------------------------------------------------------------------------- describe("PassthroughToolbar – composer toggle", () => { - beforeEach(resetMocks); - afterEach(cleanup); - it("clicking Chat toggle opens and closes the composer", async () => { renderToolbar(); const toggle = screen.getByTestId(TID_TOGGLE); @@ -509,9 +560,6 @@ describe("PassthroughToolbar – composer toggle", () => { // --------------------------------------------------------------------------- describe("PassthroughToolbar – completed session", () => { - beforeEach(resetMocks); - afterEach(cleanup); - it("passes completed session state to the passthrough composer", async () => { mockSessionState = "COMPLETED"; renderToolbar(); @@ -526,9 +574,6 @@ describe("PassthroughToolbar – completed session", () => { // --------------------------------------------------------------------------- describe("PassthroughToolbar – implement plan handler", () => { - beforeEach(resetMocks); - afterEach(cleanup); - it("forwards the implement handler to the composer while plan mode is active", async () => { const implementHandler = vi.fn(); mockPlanModeEnabled = true; @@ -570,9 +615,6 @@ describe("PassthroughToolbar – implement plan handler", () => { // --------------------------------------------------------------------------- describe("PassthroughToolbar – send message", () => { - beforeEach(resetMocks); - afterEach(cleanup); - it("send with no pending comments calls message.add with exact text and closes composer", async () => { renderToolbar(); await openComposer(); @@ -639,9 +681,6 @@ describe("PassthroughToolbar – send message", () => { // --------------------------------------------------------------------------- describe("PassthroughToolbar – pending comment indicators", () => { - beforeEach(resetMocks); - afterEach(cleanup); - it("shows a numeric chip when the composer is collapsed and comments are pending", () => { mockPendingByFile = { [SRC_FILE]: [makeDiffComment("c1"), makeDiffComment("c2"), makeDiffComment("c3")], @@ -666,9 +705,6 @@ describe("PassthroughToolbar – pending comment indicators", () => { // --------------------------------------------------------------------------- describe("PassthroughToolbar – Comments panel", () => { - beforeEach(resetMocks); - afterEach(cleanup); - it("clicking Comments opens a panel with one card per pending comment", async () => { mockPendingByFile = { [SRC_FILE]: [makeDiffComment("c1"), makeDiffComment("c2")], @@ -725,9 +761,6 @@ describe("PassthroughToolbar – Comments panel", () => { // --------------------------------------------------------------------------- describe("PassthroughToolbar – proceed button", () => { - beforeEach(resetMocks); - afterEach(cleanup); - it("is absent when nextStepName is null", () => { mockNextStep = { proceedStepName: null, proceed: vi.fn(), isMoving: false }; mockSessionState = "IDLE"; diff --git a/apps/web/components/task/passthrough-toolbar.tsx b/apps/web/components/task/passthrough-toolbar.tsx index a1c79d3994..dbf66eab74 100644 --- a/apps/web/components/task/passthrough-toolbar.tsx +++ b/apps/web/components/task/passthrough-toolbar.tsx @@ -74,6 +74,25 @@ function usePassthroughComposerShortcut({ ); } +function usePassthroughSendHandler( + sendPassthroughMessage: ReturnType, +) { + const [isSending, setIsSending] = useState(false); + const handleSendMessage = useCallback( + async (...args: Parameters) => { + if (isSending) return; + setIsSending(true); + try { + await sendPassthroughMessage(...args); + } finally { + setIsSending(false); + } + }, + [isSending, sendPassthroughMessage], + ); + return { isSending, handleSendMessage }; +} + /** * PassthroughToolbar wraps the PTY terminal with the kandev surface that the * full ACP `ChatStatusBar` + `ChatInputArea` provide for chat mode: PR status, @@ -96,7 +115,6 @@ export function PassthroughToolbar({ }) { const [composerOpen, setComposerOpen] = useState(false); const [commentsOpenState, setCommentsOpen] = useState(false); - const [isSending, setIsSending] = useState(false); const chatInputRef = useRef(null); const sessionState = useAppStore((state) => @@ -107,7 +125,8 @@ export function PassthroughToolbar({ const isAgentBusy = sessionState === "RUNNING" || sessionState === "STARTING"; const { pendingComments, pendingCount } = usePendingPassthroughComments(sessionId); - const { isFinePointer: finePointer } = useResponsiveBreakpoint(); + const { isMobile, isTablet, isFinePointer: finePointer } = useResponsiveBreakpoint(); + const isTouch = isMobile || isTablet; const { openFile } = useFileEditors(); const panelState = useChatPanelState({ sessionId: sessionId ?? null, onOpenFile: openFile }); const planActions = usePlanActions({ @@ -134,18 +153,7 @@ export function PassthroughToolbar({ setCommentsOpen(false); }, }); - const handleSendMessage = useCallback( - async (...args: Parameters) => { - if (isSending) return; - setIsSending(true); - try { - await sendPassthroughMessage(...args); - } finally { - setIsSending(false); - } - }, - [isSending, sendPassthroughMessage], - ); + const { isSending, handleSendMessage } = usePassthroughSendHandler(sendPassthroughMessage); useEffect(() => { if (!composerOpen) return; @@ -165,6 +173,7 @@ export function PassthroughToolbar({ comments={pendingComments} openFile={openFile} onSend={() => handleSendMessage({ message: "" })} + isTouch={isTouch} /> )} @@ -194,6 +203,7 @@ export function PassthroughToolbar({ commentsOpen={commentsOpen} onToggleComments={() => setCommentsOpen((open) => !open)} pendingCommentsCount={pendingCount} + isTouch={isTouch} /> ); @@ -214,14 +224,22 @@ function usePendingPassthroughComments(sessionId: string | null | undefined) { return { pendingComments, pendingCount: pendingComments.length }; } +const PASSTHROUGH_STATUS_CONTROL_BASE_CLASS = "gap-1 px-2.5 text-xs cursor-pointer"; + +function passthroughStatusControlClass(isTouch: boolean): string { + return `${isTouch ? "min-h-11 min-w-11" : "h-6"} ${PASSTHROUGH_STATUS_CONTROL_BASE_CLASS}`; +} + function ChatToggleButton({ composerOpen, focusShortcut, onToggle, + isTouch, }: { composerOpen: boolean; focusShortcut: KeyboardShortcut; onToggle: () => void; + isTouch: boolean; }) { const { t } = useTranslation(); return ( @@ -231,7 +249,7 @@ function ChatToggleButton({ type="button" variant={composerOpen ? "default" : "outline"} size="sm" - className="h-6 gap-1 px-2.5 text-xs cursor-pointer" + className={passthroughStatusControlClass(isTouch)} onClick={onToggle} data-testid="passthrough-toggle-composer" aria-pressed={composerOpen} @@ -286,22 +304,24 @@ function PassthroughChatShortcutHint({ shortcut }: { shortcut: KeyboardShortcut ); } -function commentsToggleClassName(count: number, commentsOpen: boolean): string { +function commentsToggleClassName(count: number, commentsOpen: boolean, isTouch: boolean): string { // Vivid amber when there are pending comments so the user sees "something // to do" — washes back to plain outline once they're cleared / sent. - if (count === 0) return "h-6 gap-1 px-2.5 text-xs cursor-pointer"; - if (commentsOpen) return "h-6 gap-1 px-2.5 text-xs cursor-pointer"; - return "h-6 gap-1 px-2.5 text-xs cursor-pointer border-amber-500/60 bg-amber-500/15 text-amber-700 hover:bg-amber-500/25 hover:text-amber-700 dark:text-amber-300 dark:hover:text-amber-200"; + if (count === 0) return passthroughStatusControlClass(isTouch); + if (commentsOpen) return passthroughStatusControlClass(isTouch); + return `${passthroughStatusControlClass(isTouch)} border-amber-500/60 bg-amber-500/15 text-amber-700 hover:bg-amber-500/25 hover:text-amber-700 dark:text-amber-300 dark:hover:text-amber-200`; } function CommentsToggleButton({ commentsOpen, onToggle, pendingCommentsCount, + isTouch, }: { commentsOpen: boolean; onToggle: () => void; pendingCommentsCount: number; + isTouch: boolean; }) { const { t } = useTranslation(); const disabled = pendingCommentsCount === 0; @@ -312,7 +332,7 @@ function CommentsToggleButton({ type="button" variant={commentsOpen ? "default" : "outline"} size="sm" - className={commentsToggleClassName(pendingCommentsCount, commentsOpen)} + className={commentsToggleClassName(pendingCommentsCount, commentsOpen, isTouch)} onClick={onToggle} disabled={disabled} data-testid="passthrough-toggle-comments" @@ -371,10 +391,12 @@ function CommentsPanel({ comments, openFile, onSend, + isTouch, }: { comments: DiffComment[]; openFile: (path: string) => void; onSend: () => Promise | void; + isTouch: boolean; }) { const { t } = useTranslation(); const [isSending, setIsSending] = useState(false); @@ -408,7 +430,7 @@ function CommentsPanel({ variant="default" onClick={handleSend} disabled={isSending} - className="h-6 gap-1 px-2.5 text-xs cursor-pointer" + className={`${isTouch ? "min-h-11 min-w-11" : "h-6"} gap-1 px-2.5 text-xs cursor-pointer`} data-testid="passthrough-send-comments" > @@ -506,6 +528,7 @@ type StatusRowProps = { commentsOpen: boolean; onToggleComments: () => void; pendingCommentsCount: number; + isTouch: boolean; }; function PassthroughStatusRow({ @@ -521,6 +544,7 @@ function PassthroughStatusRow({ commentsOpen, onToggleComments, pendingCommentsCount, + isTouch, }: StatusRowProps) { const { t } = useTranslation(); return ( @@ -532,11 +556,13 @@ function PassthroughStatusRow({ composerOpen={composerOpen} focusShortcut={focusShortcut} onToggle={onToggleComposer} + isTouch={isTouch} />
@@ -553,7 +579,7 @@ function PassthroughStatusRow({ type="button" variant="outline" size="sm" - className="h-6 shrink-0 gap-1 px-2.5 text-xs cursor-pointer text-primary" + className={`${isTouch ? "min-h-11 min-w-11" : "h-6"} shrink-0 gap-1 px-2.5 text-xs cursor-pointer text-primary`} onClick={onProceed} disabled={isMoving} data-testid="passthrough-proceed-next-step" diff --git a/apps/web/e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts b/apps/web/e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts index 262468a18f..2c5d8254f2 100644 --- a/apps/web/e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts +++ b/apps/web/e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts @@ -1,5 +1,8 @@ // Filename starts with "mobile-" so this runs in the mobile-chrome project. +import fs from "node:fs"; +import path from "node:path"; import { test, expect } from "../../fixtures/test-base"; +import type { Locator, Page } from "@playwright/test"; import type { ApiClient } from "../../helpers/api-client"; import { seedAvailableCommands } from "../../helpers/session-store"; import { SessionPage } from "../../pages/session-page"; @@ -44,7 +47,132 @@ async function openMobilePassthroughTask( return { task, session }; } +async function expectTouchTarget(control: Locator): Promise { + const box = await control.boundingBox(); + expect(box).not.toBeNull(); + if (!box) return; + expect(box.width).toBeGreaterThanOrEqual(44); + expect(box.height).toBeGreaterThanOrEqual(44); +} + +function passthroughComposer(testPage: Page) { + return testPage.getByTestId("passthrough-composer"); +} + +function passthroughEditor(testPage: Page) { + return passthroughComposer(testPage).locator(".tiptap.ProseMirror"); +} + +async function expectWithinVisualViewport(testPage: Page, control: Locator): Promise { + const box = await control.boundingBox(); + expect(box).not.toBeNull(); + if (!box) return; + const viewport = await testPage.evaluate(() => ({ + width: window.visualViewport?.width ?? window.innerWidth, + height: window.visualViewport?.height ?? window.innerHeight, + })); + expect(box.x).toBeGreaterThanOrEqual(0); + expect(box.y).toBeGreaterThanOrEqual(0); + expect(box.x + box.width).toBeLessThanOrEqual(viewport.width + 1); + expect(box.y + box.height).toBeLessThanOrEqual(viewport.height + 1); +} + +async function expectSingleUserMessage( + apiClient: ApiClient, + sessionId: string, + marker: string, +): Promise { + await expect + .poll( + async () => { + const { messages } = await apiClient.listSessionMessages(sessionId); + return messages.filter((message) => { + return message.author_type === "user" && message.content.includes(marker); + }).length; + }, + { timeout: 15_000, message: `Wait for one persisted user message containing "${marker}"` }, + ) + .toBe(1); +} + +async function expectReadyDraftAttachment( + testPage: Page, + sessionId: string, + fileName: string, +): Promise { + await expect + .poll( + async () => + testPage.evaluate( + ({ sessionId: currentSessionId, fileName: currentFileName }) => { + const raw = sessionStorage.getItem(`kandev.chatDraft.attachments.${currentSessionId}`); + if (!raw) return false; + try { + const attachments = JSON.parse(raw) as Array<{ + attachmentId?: string; + fileName?: string; + }>; + return attachments.some( + (attachment) => + attachment.fileName === currentFileName && Boolean(attachment.attachmentId), + ); + } catch { + return false; + } + }, + { sessionId, fileName }, + ), + { timeout: 15_000, message: `Wait for ready draft attachment "${fileName}"` }, + ) + .toBe(true); +} + test.describe("mobile CLI mode: passthrough composer", () => { + test("keeps passthrough controls touch-sized without document overflow", async ({ + testPage, + apiClient, + seedData, + }) => { + test.setTimeout(90_000); + const { session } = await openMobilePassthroughTask( + testPage, + apiClient, + seedData, + "Mobile CLI Geometry", + "Mobile CLI Geometry Task", + ); + const toolbar = testPage.getByTestId("passthrough-toolbar"); + const statusRow = toolbar.getByTestId("passthrough-status-row"); + + for (const testId of ["passthrough-toggle-composer", "passthrough-toggle-comments"]) { + await expectTouchTarget(statusRow.getByTestId(testId)); + } + const proceed = statusRow.getByTestId("passthrough-proceed-next-step"); + if (await proceed.isVisible()) await expectTouchTarget(proceed); + + await statusRow.getByTestId("passthrough-toggle-composer").tap(); + const composer = toolbar.getByTestId("passthrough-composer"); + await expect(composer).toBeVisible(); + for (const testId of [ + "plan-mode-toggle-button", + "chat-attachments-button", + "chat-context-button", + "submit-message-button", + ]) { + await expectTouchTarget(composer.getByTestId(testId)); + } + + expect( + await testPage.evaluate( + () => document.documentElement.scrollWidth <= document.documentElement.clientWidth, + ), + ).toBe(true); + expect(await statusRow.evaluate((element) => element.scrollWidth <= element.clientWidth)).toBe( + true, + ); + expect(await session.passthroughTerminal.isVisible()).toBe(true); + }); + test("slash remains literal and only passthrough composer controls are available", async ({ testPage, apiClient, @@ -105,7 +233,7 @@ test.describe("mobile CLI mode: passthrough composer", () => { const promptName = `mobile-pt-prompt-${Date.now()}`; const promptContent = "MOBILE_PASSTHROUGH_PROMPT_MARKER"; await apiClient.createPrompt(promptName, promptContent); - const { session } = await openMobilePassthroughTask( + const { task, session } = await openMobilePassthroughTask( testPage, apiClient, seedData, @@ -114,29 +242,153 @@ test.describe("mobile CLI mode: passthrough composer", () => { ); await testPage.getByTestId("passthrough-toggle-composer").tap(); - const composer = testPage.getByTestId("passthrough-composer"); - const editor = composer.locator(".tiptap.ProseMirror"); + const composer = passthroughComposer(testPage); + const editor = passthroughEditor(testPage); await expect(editor).toBeVisible({ timeout: 5_000 }); - await composer - .getByTestId("mobile-chat-toolbar-left-actions") - .getByTestId("chat-context-button") - .tap(); - const searchInput = testPage.getByPlaceholder("Search files and prompts..."); - await expect(searchInput).toBeVisible({ timeout: 5_000 }); - await searchInput.fill(promptName); - await testPage.getByText(promptName, { exact: true }).tap(); + await editor.click(); + await editor.pressSequentially(`mobile context e2e @${promptName}`); + const mentionHeading = testPage.getByText("Mention tasks, files, prompts"); + await expect(mentionHeading).toBeVisible({ timeout: 5_000 }); + await expectWithinVisualViewport(testPage, mentionHeading); + await testPage.getByRole("option", { name: new RegExp(promptName) }).tap(); await expect(composer.getByText(promptName, { exact: true })).toBeVisible({ timeout: 5_000, }); - await editor.fill("mobile context e2e"); await testPage.getByTestId("submit-message-button").tap(); await expect(composer).toBeHidden({ timeout: 10_000 }); await session.expectPassthroughHasText("mobile context e2e", 15_000); await session.expectPassthroughHasText("CONTEXT PROMPTS", 15_000); await session.expectPassthroughHasText(promptContent, 15_000); + if (!task.session_id) throw new Error("expected passthrough task session id"); + await expectSingleUserMessage(apiClient, task.session_id, "mobile context e2e"); + }); + + test("sends a selected mobile attachment once", async ({ + testPage, + apiClient, + seedData, + }, testInfo) => { + test.setTimeout(90_000); + const { task, session } = await openMobilePassthroughTask( + testPage, + apiClient, + seedData, + "Mobile CLI Attachment", + "Mobile CLI Attachment Task", + ); + if (!task.session_id) throw new Error("expected passthrough task session id"); + + fs.mkdirSync(testInfo.outputDir, { recursive: true }); + const attachmentName = "mobile-passthrough-upload.txt"; + const attachmentPath = path.join(testInfo.outputDir, attachmentName); + fs.writeFileSync(attachmentPath, "mobile passthrough attachment body"); + + await testPage.getByTestId("passthrough-toggle-composer").tap(); + const composer = passthroughComposer(testPage); + const fileChooserPromise = testPage.waitForEvent("filechooser"); + await composer.getByTestId("chat-attachments-button").tap(); + const fileChooser = await fileChooserPromise; + await fileChooser.setFiles(attachmentPath); + await expect(composer.getByText(attachmentName, { exact: true })).toBeVisible({ + timeout: 10_000, + }); + await expectReadyDraftAttachment(testPage, task.session_id, attachmentName); + + const message = "mobile attachment e2e"; + await passthroughEditor(testPage).fill(message); + await composer.getByTestId("submit-message-button").tap(); + await expect(composer).toBeHidden({ timeout: 10_000 }); + + await session.expectPassthroughHasText(message, 15_000); + await session.expectPassthroughHasText(attachmentName, 15_000); + await expectSingleUserMessage(apiClient, task.session_id, message); + }); + + test("restores text, context, and a ready attachment per passthrough session", async ({ + testPage, + apiClient, + seedData, + }, testInfo) => { + test.setTimeout(120_000); + const promptName = `mobile-pt-draft-prompt-${Date.now()}`; + await apiClient.createPrompt(promptName, "MOBILE_PASSTHROUGH_DRAFT_PROMPT"); + const first = await openMobilePassthroughTask( + testPage, + apiClient, + seedData, + "Mobile CLI Draft A", + "Mobile CLI Draft A Task", + ); + if (!first.task.session_id) throw new Error("expected first passthrough task session id"); + + const secondProfileId = await createPassthroughProfile(apiClient, "Mobile CLI Draft B"); + const secondTask = await apiClient.createTaskWithAgent( + seedData.workspaceId, + "Mobile CLI Draft B Task", + secondProfileId, + { + description: "initial prompt", + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + repository_ids: [seedData.repositoryId], + }, + ); + if (!secondTask.session_id) throw new Error("expected second passthrough task session id"); + + await testPage.getByTestId("passthrough-toggle-composer").tap(); + const firstComposer = passthroughComposer(testPage); + await firstComposer.getByTestId("chat-context-button").tap(); + const searchInput = testPage.getByPlaceholder("Search files and prompts..."); + await expect(searchInput).toBeVisible({ timeout: 5_000 }); + await searchInput.fill(promptName); + await testPage.getByText(promptName, { exact: true }).tap(); + await expect(firstComposer.getByText(promptName, { exact: true })).toBeVisible({ + timeout: 5_000, + }); + + fs.mkdirSync(testInfo.outputDir, { recursive: true }); + const attachmentName = "mobile-passthrough-draft.txt"; + const attachmentPath = path.join(testInfo.outputDir, attachmentName); + fs.writeFileSync(attachmentPath, "mobile passthrough draft attachment body"); + const fileChooserPromise = testPage.waitForEvent("filechooser"); + await firstComposer.getByTestId("chat-attachments-button").tap(); + const fileChooser = await fileChooserPromise; + await fileChooser.setFiles(attachmentPath); + await expect(firstComposer.getByText(attachmentName, { exact: true })).toBeVisible({ + timeout: 10_000, + }); + await expectReadyDraftAttachment(testPage, first.task.session_id, attachmentName); + await passthroughEditor(testPage).fill("mobile session draft"); + + await testPage.goto(`/t/${secondTask.id}`); + const secondSession = new SessionPage(testPage); + await secondSession.waitForPassthroughLoad(20_000); + await secondSession.waitForPassthroughLoaded(20_000); + await secondSession.expectPassthroughHasText("Processed:", 20_000); + await testPage.getByTestId("passthrough-toggle-composer").tap(); + const secondComposer = passthroughComposer(testPage); + await expect(secondComposer).toBeVisible(); + await expect(secondComposer.locator(".tiptap.ProseMirror")).toHaveText(""); + await expect(secondComposer.getByText(promptName, { exact: true })).toHaveCount(0); + await expect(secondComposer.getByText(attachmentName, { exact: true })).toHaveCount(0); + + await testPage.goto(`/t/${first.task.id}`); + const restoredSession = new SessionPage(testPage); + await restoredSession.waitForPassthroughLoad(20_000); + await restoredSession.waitForPassthroughLoaded(20_000); + await restoredSession.expectPassthroughHasText("Processed:", 20_000); + await testPage.getByTestId("passthrough-toggle-composer").tap(); + const restoredComposer = passthroughComposer(testPage); + await expect(passthroughEditor(testPage)).toHaveText("mobile session draft"); + await expect(restoredComposer.getByText(promptName, { exact: true })).toBeVisible({ + timeout: 5_000, + }); + await expect(restoredComposer.getByText(attachmentName, { exact: true })).toBeVisible({ + timeout: 5_000, + }); }); }); diff --git a/docs/plans/mobile-passthrough-composer/plan.md b/docs/plans/mobile-passthrough-composer/plan.md new file mode 100644 index 0000000000..dc555db98a --- /dev/null +++ b/docs/plans/mobile-passthrough-composer/plan.md @@ -0,0 +1,70 @@ +--- +spec: docs/specs/cli/requirements/mobile-passthrough-composer.md +design: docs/specs/cli/system-design/mobile-passthrough-composer.md +created: 2026-09-02 +status: completed +--- + +# Implementation Plan: Mobile Passthrough Composer + +## Overview + +Make the existing inline passthrough composer safe to operate by touch, then +extend its mobile end-to-end coverage across the flows requested in GitHub +issue `#2809`. Keep passthrough submission, literal slash input, and raw PTY +input as separate contracts. + +## Implementation + +- Add an explicit mobile touch presentation for shared composer controls so + context, attachment, plan, cancel, send, and split Implement targets are at + least 44-by-44 CSS pixels. Retain current desktop geometry. +- Apply the same mobile-only touch geometry to the owned passthrough Chat, + Comments, Proceed, and Send to Agent controls in the status row. Integration + status chips remain governed by their own component contracts. +- Keep the composer inline and preserve the existing `100dvh`, safe-area, + visual-viewport overlay, and single flexible terminal layout. +- Add focused tests for touch geometry and mobile passthrough flows. Do not add + an unsupported slash-command menu or a raw-terminal keybar. + +No backend, WebSocket, persistence, or localization change is expected. + +## Implementation waves + +Wave 1: + +- [x] [Task 01: Touch-safe mobile controls](task-01-touch-safe-mobile-controls.md) + +Wave 2: + +- [x] [Task 02: Passthrough mobile regression coverage](task-02-passthrough-mobile-regression-coverage.md), depends on Task 01. + +## Risks + +- Increasing controls can crowd narrow toolbars. Keep secondary actions in the + existing internal horizontal scroller and assert no document overflow. +- Shared composer primitives also serve ACP chat. Gate geometry by mobile + presentation and run the focused ACP composer tests. +- Mobile Chromium cannot prove iOS software-keyboard behavior. Record iPhone + Safari and Android Chrome smoke results before closing `#2809`. +- One-tap raw PTY keys require routing to the active agent xterm. Track that as + a separate issue instead of coupling it to semantic composer submission. + +## Verification + +```bash +(cd apps/web && pnpm exec vitest run components/task/passthrough-toolbar.test.tsx components/task/chat/chat-input-toolbar.test.tsx) +(cd apps/web && pnpm run typecheck) +(cd apps/web && pnpm run lint) +(cd apps/web && pnpm e2e:run --project mobile-chrome e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts) +python3 scripts/lint-spec-files.py --all +``` + +Complete the issue's manual smoke matrix on iPhone Safari and Android Chrome. +Verify composer focus with the software keyboard open, `@` selection, operating +system file selection, task-switch draft restoration, and explicit send. + +Automated coverage and implementation are complete. Physical-device smoke +remains an explicit environment blocker because this workspace has no iPhone +Safari or Android Chrome device runner. Issue `#2809` remains open for that +manual closure gate. diff --git a/docs/plans/mobile-passthrough-composer/task-01-touch-safe-mobile-controls.md b/docs/plans/mobile-passthrough-composer/task-01-touch-safe-mobile-controls.md new file mode 100644 index 0000000000..b27be585e0 --- /dev/null +++ b/docs/plans/mobile-passthrough-composer/task-01-touch-safe-mobile-controls.md @@ -0,0 +1,79 @@ +--- +id: "01-touch-safe-mobile-controls" +title: "Touch-safe mobile controls" +status: completed +wave: 1 +depends_on: [] +plan: "plan.md" +spec: "../../specs/cli/requirements/mobile-passthrough-composer.md" +design: "../../specs/cli/system-design/mobile-passthrough-composer.md" +--- + +# Task 01: Touch-safe mobile controls + +## Outcome + +Phone users can operate every passthrough status and composer action owned by +this change through a minimum 44-by-44 CSS-pixel touch target without changing +desktop geometry. + +## Scope + +- Add a mobile presentation to the shared context, attachment, plan, cancel, + and send controls. +- Apply mobile-only touch sizing to the owned passthrough Chat, Comments, + Proceed, and Send to Agent controls. +- Preserve the inline composer, internal toolbar scrolling, terminal flex + behavior, and existing translated labels. +- Add focused component coverage for mobile and desktop control geometry. + +## Exclusions + +- No drawer, terminal keybar, raw PTY routing, or slash-command behavior. +- No backend, WebSocket, storage, or localization changes. + +## Traceability + +- `REQ-CLI-MOBILE-PASSTHROUGH-COMPOSER-001` +- `AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.1` +- `AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.2` +- `AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.8` +- `docs/specs/cli/system-design/mobile-passthrough-composer.md` + +## Implementation acceptance + +- Every status-row and composer action owned by this change in the mobile + passthrough surface has a computed width and height of at least 44 CSS + pixels. Integration-owned status chips retain their own component contracts. +- Desktop controls retain their current compact dimensions. +- Narrow mobile toolbars scroll actions internally and do not create document + horizontal overflow. + +## Files likely touched + +- `apps/web/components/task/passthrough-toolbar.tsx` +- `apps/web/components/task/passthrough-toolbar.test.tsx` +- `apps/web/components/task/chat/chat-input-toolbar-mobile.tsx` +- `apps/web/components/task/chat/chat-input-toolbar-primitives.tsx` +- `apps/web/components/task/chat/chat-input-toolbar.test.tsx` + +## Verification + +```bash +(cd apps/web && pnpm exec vitest run components/task/passthrough-toolbar.test.tsx components/task/chat/chat-input-toolbar.test.tsx) +(cd apps/web && pnpm run typecheck) +(cd apps/web && pnpm run lint) +``` + +## Results + +Implemented mobile-only touch presentation for the shared context, attachment, +plan, cancel, and send controls, plus passthrough Chat, Comments, and workflow +controls. Desktop controls retain their compact dimensions. + +Verification passed: + +- Focused Vitest suite: 48 tests passed. +- Web typecheck passed. +- Web lint passed with zero warnings. +- Managed mobile E2E coverage passed as part of Task 02. diff --git a/docs/plans/mobile-passthrough-composer/task-02-passthrough-mobile-regression-coverage.md b/docs/plans/mobile-passthrough-composer/task-02-passthrough-mobile-regression-coverage.md new file mode 100644 index 0000000000..7d4efc5a5a --- /dev/null +++ b/docs/plans/mobile-passthrough-composer/task-02-passthrough-mobile-regression-coverage.md @@ -0,0 +1,80 @@ +--- +id: "02-passthrough-mobile-regression-coverage" +title: "Passthrough mobile regression coverage" +status: completed +wave: 2 +depends_on: ["01-touch-safe-mobile-controls"] +plan: "plan.md" +spec: "../../specs/cli/requirements/mobile-passthrough-composer.md" +design: "../../specs/cli/system-design/mobile-passthrough-composer.md" +--- + +# Task 02: Passthrough mobile regression coverage + +## Outcome + +The mobile browser suite proves the supported passthrough composer flows and +the repository has a concrete real-device sign-off checklist. + +## Scope + +- Extend the existing mobile passthrough Playwright specification instead of + creating a parallel fixture or page model. +- Cover computed touch geometry, composer focus, explicit send, literal slash + text, `@` selection, operating-system file selection, session-scoped draft + restoration, visual-viewport containment, and document overflow. +- Record iPhone Safari and Android Chrome smoke results before the issue closes. + +## Exclusions + +- No ACP slash-command suggestions in passthrough mode. +- No one-tap raw terminal-key controls. Create a follow-up issue if that + capability is still required after the real-device smoke test. +- No changes to the companion remote-access documentation tracked by `#2807`. + +## Traceability + +- `REQ-CLI-MOBILE-PASSTHROUGH-COMPOSER-001` +- `AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.1` through + `AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.8` +- `docs/specs/cli/system-design/mobile-passthrough-composer.md` + +## Implementation acceptance + +- The mobile Chromium specification covers all automated flows in the issue + matrix and fails if a target becomes smaller than 44-by-44 CSS pixels. +- Draft restoration is proven across two sessions, including text, selected + context, and a ready attachment. +- The implementation record contains iPhone Safari and Android Chrome smoke + results or an explicit blocker that prevents issue closure. + +## Files likely touched + +- `apps/web/e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts` +- `docs/plans/mobile-passthrough-composer/plan.md` +- `docs/plans/mobile-passthrough-composer/task-02-passthrough-mobile-regression-coverage.md` + +## Verification + +```bash +(cd apps/web && pnpm e2e:run --project mobile-chrome e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts) +python3 scripts/lint-spec-files.py --all +``` + +## Results + +The mobile passthrough specification now covers touch geometry, composer focus, +explicit single-message send, literal slash text, inline `@` prompt selection, +visual-viewport containment, document overflow, operating-system file +selection, and session-scoped draft restoration with text, context, and a ready +attachment. + +Verification passed: + +- `pnpm e2e:run --project mobile-chrome e2e/tests/cli-mode/mobile-passthrough-composer.spec.ts`: 5 tests passed. +- `python3 scripts/lint-spec-files.py --all`: passed. + +Physical-device smoke is blocked in this environment: no iPhone Safari or +Android Chrome device runner is available. Issue closure still requires the +manual keyboard, `@` selection, file picker, task-switch, and explicit-send +smoke matrix on those devices. diff --git a/docs/specs/cli/README.md b/docs/specs/cli/README.md index 3867176716..7ac8ed5787 100644 --- a/docs/specs/cli/README.md +++ b/docs/specs/cli/README.md @@ -28,16 +28,14 @@ and CLI-specific compatibility behavior. ### Requirements - - - [CLI-Mode Task Parity (Kanban)](requirements/cli-mode-parity.md) +- [Mobile Passthrough Composer](requirements/mobile-passthrough-composer.md) - [Native Kandev CLI](requirements/native-kandev-cli.md) - [Passthrough Launch Defaults](requirements/passthrough-launch-defaults.md) ### System design - - +- [Mobile Passthrough Composer](system-design/mobile-passthrough-composer.md) - [Passthrough Launch Defaults](system-design/passthrough-launch-defaults.md) ## Migration record diff --git a/docs/specs/cli/requirements/mobile-passthrough-composer.md b/docs/specs/cli/requirements/mobile-passthrough-composer.md new file mode 100644 index 0000000000..5e5f032eaa --- /dev/null +++ b/docs/specs/cli/requirements/mobile-passthrough-composer.md @@ -0,0 +1,89 @@ +--- +status: active +system: cli +created: 2026-09-02 +owners: + - web +--- + +# Mobile Passthrough Composer Requirements + +## Overview + +CLI passthrough sessions expose an agent terminal and a Kandev composer in the +same task surface. Phone users and coarse-pointer tablet users must be able to +compose and send a structured follow-up without losing terminal output, drafts, +attachments, or contextual references. The CLI system owns this contract +because submission must preserve the raw PTY delivery semantics of a +passthrough session. + +## Terminology + +- **Passthrough composer:** The Kandev-controlled prompt editor displayed with + an agent's passthrough terminal. +- **Explicit send:** A composer action that records one user message and + delivers its resolved content through the passthrough session's configured + submit behavior. +- **Raw terminal input:** Keystrokes sent directly to the agent PTY without + creating a Kandev user message. + +## Requirements + +### REQ-CLI-MOBILE-PASSTHROUGH-COMPOSER-001: Touch-safe passthrough composition + +**Intent:** Let a phone user prepare and send a structured passthrough prompt +without losing access to the running terminal or current draft. + +**User story:** As a phone user in a CLI passthrough session, I want to compose +and send a follow-up by touch, so that I can continue the session without a +desktop keyboard. + +#### Acceptance criteria + +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.1:** When a user opens a CLI + passthrough session on a phone or coarse-pointer tablet, the system shall + keep the terminal, owned composer and status controls, and open composer + inside the visible application surface without horizontal document overflow. +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.2:** When a shared composer action or + passthrough status-row action owned by this change is shown on a phone or + coarse-pointer tablet, its touch target shall be at least 44 CSS pixels high + and 44 CSS pixels wide. The owned controls are the composer plan, attachment, + context, cancel, send, and split Implement actions, plus the passthrough + Chat, Comments, Proceed, and Send to Agent actions. Integration-owned status + chips, such as dependency and PR/provider chips, retain their own component + contracts. +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.3:** When the user types content and + activates explicit send, the system shall create one user message and deliver + the resolved prompt once through the active passthrough session's configured + submit behavior. +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.4:** When the user types `@` or uses + the context control, the system shall provide the existing prompt, plan, + task, and workspace-file references. A selected suggestion shall remain in + the draft until explicit send, and the suggestion overlay shall follow the + shared [composer overlay requirements](../../ui/requirements/composer-suggestion-overlays.md). +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.5:** When the user selects the + attachment control on a phone, the system shall open the operating system's + file picker and preserve the existing attachment upload, retry, removal, and + error outcomes before explicit send. +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.6:** When the user types `/` in a + passthrough composer, the system shall keep it as literal prompt text and + shall not show ACP slash-command suggestions that the session did not + advertise. +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.7:** When the user leaves a task with + an unsent passthrough draft and later returns to the same session, the system + shall restore its text, selected context, and ready attachments without + exposing that draft in another session. +- **AC-CLI-MOBILE-PASSTHROUGH-COMPOSER-001.8:** When the software keyboard or + mobile browser chrome changes the visual viewport, the system shall keep the + composer and active suggestion overlay reachable while the terminal remains + the only flexible, internally scrollable content region. + +## Out of scope + +- Advertising or synthesizing ACP slash commands for passthrough sessions. +- Treating explicit composer send as a raw Enter keystroke. +- Adding one-tap Ctrl+C, Escape, Enter, or other raw PTY keys to the agent + passthrough surface. That terminal-input contract requires a separate issue. +- Replacing the contextual composer popup with a drawer or full-screen picker. +- The companion mobile remote-access documentation tracked by GitHub issue + `#2807`. diff --git a/docs/specs/cli/system-design/mobile-passthrough-composer.md b/docs/specs/cli/system-design/mobile-passthrough-composer.md new file mode 100644 index 0000000000..cdc3ef403d --- /dev/null +++ b/docs/specs/cli/system-design/mobile-passthrough-composer.md @@ -0,0 +1,141 @@ +--- +status: current +system: cli +requirements: + - REQ-CLI-MOBILE-PASSTHROUGH-COMPOSER-001 +--- + +# Mobile Passthrough Composer System Design + +## Purpose and boundaries + +The CLI system owns the user-visible prompt path for sessions backed by a raw +agent PTY. The web application implements that path with an inline composer, +but it must keep passthrough submission distinct from raw terminal input. This +design uses the UI system's shared composer overlay contract and the Tasks +system's attachment contract without redefining either one. + +The composer remains inline above the passthrough status row. A drawer would +introduce another focus, draft, and viewport owner without solving the measured +touch-target defect. The existing mobile task layout already constrains the +surface with `100dvh`, safe-area padding, and one flexible terminal region. + +## Requirement mapping + +| Requirement | Design sections | +| --- | --- | +| `REQ-CLI-MOBILE-PASSTHROUGH-COMPOSER-001` | [Components and responsibilities](#components-and-responsibilities), [Control flow](#control-flow), [Responsive behavior](#responsive-behavior), [Persistence](#persistence) | + +## Components and responsibilities + +- `PassthroughToolbar` owns the vertical terminal, optional composer, comments, + and passthrough status-row composition. It applies touch geometry to the + owned mobile and coarse-pointer tablet status controls, Chat, Comments, + Proceed, and Send to Agent, while preserving compact desktop controls. +- `PassthroughComposerPanel` configures the shared `ChatInputContainer` for a + passthrough session. It disables unadvertised agent commands and external + entity references while retaining context mentions, attachments, plan + context, and session-scoped draft behavior. +- `MobileChatInputToolbar` owns the mobile and coarse-pointer tablet + presentation of shared composer controls. Its context, attachment, plan, + cancel, send, and split Implement controls use a touch presentation with a + minimum 44-by-44 CSS-pixel target. Desktop toolbar geometry does not change. +- `PassthroughTerminal` remains the raw PTY surface and the only flexible child + in the toolbar. On mobile, it retains touch scrolling. +- The shared suggestion popup remains responsible for visual-viewport + containment, internal result scrolling, and touch selection. + +The current defect comes from fixed `h-6` and `h-7` classes in the passthrough +status row and shared composer primitives. The mobile and tablet layouts reused +those desktop-sized controls without a touch presentation, which produced +measured 24-to-28 CSS-pixel targets. + +## Data and contracts + +No backend, WebSocket, or persisted data contract changes. + +- Composer submission continues to use `message.add` with `task_id`, + `session_id`, a unique `client_message_id`, resolved content, optional + attachments, and optional context-file metadata. +- The backend remains responsible for converting that message into the active + passthrough agent's configured submit sequence. The browser must not send a + raw Enter key as a substitute for this request. +- `hasAgentCommands={false}` remains the passthrough capability declaration. + Literal `/` input is therefore intentional, not a missing mobile menu. +- The existing task attachment contract owns file materialization, retry, + removal, and error behavior. + +## Control flow + +1. The phone user opens Chat from the passthrough status row. +2. `PassthroughToolbar` renders the inline `PassthroughComposerPanel` and moves + focus into its TipTap editor. +3. The user enters text, selects contextual `@` results, or chooses attachments. + These actions update the session-scoped draft and do not submit it. +4. Explicit send resolves selected comments, context files, plans, task + mentions, and attachments into one `message.add` request. +5. After the request succeeds, the composer clears its sent state and closes. + On failure, it stays available with the draft and error feedback intact. + +Escape closes the Kandev composer while it has focus. Raw Ctrl+C, Escape, Enter, +and other terminal keys remain xterm interactions and are not added to the +composer toolbar by this capability. + +## Responsive behavior + +Touch presentation is selected by the existing responsive breakpoint. The +mobile and coarse-pointer tablet branches use touch-sized controls; fine-pointer +desktop branches retain compact controls. The terminal stays `min-h-0` and +flexible; the composer and status row keep their intrinsic height. This +prevents the document from becoming a second scroll container when the composer +opens. + +The shared composer actions and passthrough status-row actions owned by this +change use at least 44-by-44 CSS-pixel hit areas. This includes the composer +plan, attachment, context, cancel, send, and split Implement actions, plus the +passthrough Chat, Comments, Proceed, and Send to Agent actions. Visual glyphs +can remain smaller. Integration-owned status chips, including dependency and +PR/provider chips, keep their own component contracts. A horizontal action +strip can scroll internally when its controls exceed the available width, but +it must not cause document-level horizontal overflow. + +The existing visual-viewport-aware suggestion popup remains attached above the +composer. The implementation does not replace it with a drawer. + +## Failure and recovery + +- If `message.add` fails, the composer keeps the unsent draft and exposes the + existing translated error. It must not clear or close as though the send + succeeded. +- If attachment upload fails, the existing attachment item remains retryable or + removable before send. +- If the Visual Viewport API is unavailable, the shared overlay falls back to + layout-viewport bounds. +- A passthrough session that has no advertised ACP commands continues to accept + literal slash text without showing an empty or misleading command menu. + +## Persistence + +TipTap JSON, selected context, and attachment state continue to use the +session-keyed chat draft store. Switching tasks selects another session key; +returning restores the original session's draft. This change adds no storage, +migration, or retention policy. + +## Verification boundary + +Focused component tests prove the mobile and desktop class contracts. The +mobile passthrough Playwright specification proves touch geometry, explicit +send, literal slash behavior, contextual suggestions, operating-system file +selection, session-scoped draft restoration, and lack of document overflow. + +Automated mobile Chromium coverage is necessary but not sufficient to close the +issue. The final verification records a smoke test on iPhone Safari and Android +Chrome for focus, software-keyboard reachability, suggestion selection, file +selection, and send. + +## Related specifications + +- [CLI-mode task parity](../requirements/cli-mode-parity.md) +- [Composer suggestion overlays](../../ui/requirements/composer-suggestion-overlays.md) +- [Slash command composer selection](../../ui/requirements/slash-command-composer.md) +- [Task prompt attachments](../../tasks/requirements/prompt-attachments.md)