diff --git a/packages/host/directory-picker-browse/README.i18n.yaml b/packages/host/directory-picker-browse/README.i18n.yaml index f40742fc0d..eea9966b83 100644 --- a/packages/host/directory-picker-browse/README.i18n.yaml +++ b/packages/host/directory-picker-browse/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/directory-picker-browse/README.md -README.md: 9772baa2a6e632a5f0f18cc18b9b55b45cd845ca -README.zh.md: 682495fe10bdeed41f709a438dcd222d612129e3 +README.md: 95d2d66406210f4ba687ef5a45a38b142abd6f26 +README.zh.md: 9da374bec80f80085ff36871c227c496bb1fde7b diff --git a/packages/host/directory-picker-browse/README.md b/packages/host/directory-picker-browse/README.md index 9772baa2a6..95d2d66406 100644 --- a/packages/host/directory-picker-browse/README.md +++ b/packages/host/directory-picker-browse/README.md @@ -6,7 +6,7 @@ The **in-app browsing backend** of the [directory-picker seam](../directory-pick Behavior facts: listings return **directories only**, name-sorted, with symlinks-to-directories followed (broken/cyclic links skipped — the probe `stat` failing means "not enterable") and a host-owned `hidden` flag (POSIX dot convention) left for the client to act on; `crumbs` is the root-to-target ancestor chain, the root crumb labeled by its full path (`/`, `C:\`); an absent `list` path means the host account's home directory. `createDirectory` is non-recursive (a missing parent is a real failure, not a level to invent) and validates the name as a single non-blank segment even when called directly, mirroring the wire schema's fence. Both primitives reject an explicit path that is not fully qualified — relative forms, and on Windows the rooted drive-less forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`) that `isAbsolute` accepts — with `directory-unreadable`/`directory-create-failed`, instead of letting `resolve` rebase it under the host process cwd or current drive. One `list` call returns at most `maxEntries` rows (config, default 1000 — the bound GitHub's web UI applies to directory listings), and the level streams through a bounded window so memory stays O(maxEntries) no matter how many children the directory holds: a cut level keeps the name-sorted head, counts hidden rows against the bound, probes only windowed candidates, and reports `truncated: true` so the client can say the level is incomplete (a windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated); window insertion is binary with an O(1) full-window tail rejection, and `list` threads the caller's `AbortSignal` so a disconnect or timeout stops the scan instead of letting it outlive the caller. Failures throw the seam's typed `DirectoryPickerError`. Policy rationale: [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md). -**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view; breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing, and cancels on Escape or focus loss; a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind). +**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view; breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing (case-insensitively, over the listed — possibly truncated — rows only; Enter still navigates by the exact text), and cancels on Escape or focus loss; a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind). ## Model Experience diff --git a/packages/host/directory-picker-browse/README.zh.md b/packages/host/directory-picker-browse/README.zh.md index 682495fe10..9da374bec8 100644 --- a/packages/host/directory-picker-browse/README.zh.md +++ b/packages/host/directory-picker-browse/README.zh.md @@ -6,7 +6,7 @@ 行为事实：列举**只返回目录**、按名称排序，指向目录的符号链接会被跟随（断链／循环链接被跳过——探测 `stat` 失败即"不可进入"），并携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示决策留给客户端；`crumbs` 是从根到目标的祖先链，根 crumb 以完整路径标注（`/`、`C:\`）；`list` 不带路径即列举宿主账户的家目录。`createDirectory` 不递归（父目录缺失是真实失败，不是要补造的层级），且即便被直接调用也把名称校验为单个非空段，与协议 schema 的栅栏一致。两个原语都拒绝非完全限定的显式路径——相对形态，以及 Windows 上 `isAbsolute` 会放行的无盘符有根形态（`\foo`、`/foo`）与不完整的 UNC 前缀（`\\`、`\\server`）——报 `directory-unreadable`／`directory-create-failed`，而不是任由 `resolve` 把它重定位到宿主进程 cwd 或当前盘符之下。单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端对目录列举采用的同一上限），且层级以流式方式经过一个有界窗口，无论目录有多少子项内存都保持 O(maxEntries)：被截断的层级保留按名排序的头部、隐藏行计入上限、只探测窗口内候选，并报告 `truncated: true`，供客户端提示层级不完整（窗口内的断链符号链接不会从窗口外回填——发生过驱逐本身已把层级标记为截断）；窗口插入为二分查找、满窗尾部单次比较即拒绝，且 `list` 透传调用方的 `AbortSignal`，断连或超时会停止扫描而不是让它在调用方离开后继续。失败抛出 seam 的类型化 `DirectoryPickerError`。策略依据：[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。 -**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤、按 Escape 或失焦即取消；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。 +**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤（不区分大小写，且仅作用于已列出、可能被截断的行；Enter 仍按确切文本导航）、按 Escape 或失焦即取消；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。 ## 模型体验 diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index 444ff19cbf..3b681de32a 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -131,8 +131,8 @@ } /* Miller content: symmetric 16px vertical padding so the divider clears the - * header and footer rules evenly; columns are 256 wide (or full width solo) - * with the hairline divider centered between them; each column scrolls alone. */ + * header and footer rules evenly; each column scrolls alone (column widths + * live at .column). */ .content { display: flex; flex-direction: column; @@ -143,9 +143,10 @@ padding: 16px 16px 16px 24px; } -/* Two-pane columns split the row evenly around the divider; 256px is the - * floor below which the row scrolls (scrollbar hidden, the effect pins the - * child pane into view) instead of squeezing the panes. */ +/* Columns split the row evenly around the divider (a solo column takes the + * whole row); 256px is the floor below which the row scrolls (scrollbar + * hidden, the effect pins the child pane into view) instead of squeezing + * the panes. */ .column { display: flex; flex-direction: column; @@ -158,10 +159,6 @@ padding-right: 8px; } -.columnWide { - width: 100%; -} - .divider { flex: none; width: 1px; diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx index 01e69f314c..b924c072bb 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx @@ -1,10 +1,11 @@ /** * The in-app workspace-directory browser (figma Harness 813-23126 family): a - * 600×420 dialog (clamped to short/narrow viewports — the Miller row scrolls + * 680×500 dialog (clamped to short/narrow viewports — the Miller row scrolls * sideways, the columns scroll down) whose header carries the title, the selection-path * breadcrumb, and a click-to-edit path zone; below it a Miller view — one - * full-width level until a row is selected, then two 256px columns (level | - * selected folder's children) around a hairline divider. Selecting in the + * full-width level until a row is selected, then two columns splitting the + * row evenly (256px floor; level | selected folder's children) around a + * hairline divider. Selecting in the * right column shifts the view one level deeper. "New folder" opens a nested * create dialog targeting the selected folder (or the level itself) and * selects the created folder. Open adopts the selected folder, falling back @@ -63,20 +64,26 @@ function displayCrumbs(listing: DirectoryListing, homeLabel: string): DirectoryE return [{ name: homeLabel, path: listing.home, hidden: false }, ...tail] } -/** The separator a Host path's own platform uses (Windows listings carry backslashes). */ -function separatorOf(path: string): string { - return path.includes('\\') ? '\\' : '/' +/** + * The listing's platform separator, read from the host-stamped home path — + * never sniffed from typed text or entry paths, where a backslash is a legal + * POSIX name character rather than a platform fact. + */ +function separatorOf(listing: DirectoryListing): '\\' | '/' { + return listing.home.includes('\\') ? '\\' : '/' } /** * The path draft's final segment, when its directory part is exactly the * level `listing` lists — the segment the level prefix-filters on while the * user types. Any other draft (no separator yet, or naming some other - * directory) leaves the level unfiltered. + * directory) leaves the level unfiltered. The directory part compares + * exactly (it is the host's own path text, reached by seeding or erasing); + * only the name filter downstream is case-insensitive. */ function draftPrefixFor(listing: DirectoryListing, draft: string | null): string | null { if (draft === null) return null - const sep = separatorOf(draft) + const sep = separatorOf(listing) const cut = draft.lastIndexOf(sep) if (cut === -1) return null const level = listing.path.endsWith(sep) ? listing.path : `${listing.path}${sep}` @@ -84,12 +91,11 @@ function draftPrefixFor(listing: DirectoryListing, draft: string | null): string } /** One column of folder rows (the Miller view renders one or two of these). */ -function LevelColumn({ entries, selectedPath, busy, onPick, wide, showHidden, filterPrefix }: { +function LevelColumn({ entries, selectedPath, busy, onPick, showHidden, filterPrefix }: { entries: readonly DirectoryEntry[] selectedPath: string | null busy: boolean onPick: (entry: DirectoryEntry) => void - wide: boolean showHidden: boolean filterPrefix: string | null }) { @@ -100,7 +106,7 @@ function LevelColumn({ entries, selectedPath, busy, onPick, wide, showHidden, fi return showHidden || !entry.hidden || filterPrefix?.startsWith('.') === true }) return ( -
+
{visible.map((entry) => { const selected = entry.path === selectedPath return ( @@ -112,6 +118,10 @@ function LevelColumn({ entries, selectedPath, busy, onPick, wide, showHidden, fi aria-current={selected || undefined} className={clsx(css.row, selected && css.rowSelected)} disabled={busy} + // Keep focus where it is (the path editor, notably): a focus + // steal on mousedown would blur-cancel the editor, unmount the + // filtered rows mid-gesture, and drop this very click. + onMouseDown={(event) => { event.preventDefault() }} onClick={() => { onPick(entry) }} > {selected @@ -142,7 +152,7 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const [error, setError] = useState(null) // Path-edit state: null = breadcrumb mode; a string = the draft being typed. const [pathDraft, setPathDraft] = useState(null) - // Show-hidden toggle state (pure client-side filter, reset on close). + // Show-hidden toggle state (pure client-side filter, reset on each open). const [showHidden, setShowHidden] = useState(false) // Create-folder state: null = closed; a string = the nested dialog's draft. const [folderDraft, setFolderDraft] = useState(null) @@ -212,6 +222,9 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, /** Select a row of the listed level and preview its children on the right. */ const select = useCallback((entry: DirectoryEntry) => { const { seq, scan } = launchListing(entry.path) + // A pick while the path editor is open adopts the (filtered) row and + // closes the editor — the draft served its purpose. + setPathDraft(null) setSelected(entry) setChild(null) setLoading(true) @@ -402,9 +415,15 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, setLoading(false) // Seed with a trailing separator so typing immediately // continues into child names (and prefix-filters below). - const base = selected?.path ?? parent?.path ?? '' - const sep = separatorOf(base) - setPathDraft(base === '' || base.endsWith(sep) ? base : `${base}${sep}`) + // No listed level means nothing to seed from (the editor + // is the recovery path for a failed home listing). + if (parent === null) { + setPathDraft('') + return + } + const base = selected?.path ?? parent.path + const sep = separatorOf(parent) + setPathDraft(base.endsWith(sep) ? base : `${base}${sep}`) }} /> @@ -441,8 +460,15 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, // Clicking anywhere outside the editor reads as leaving it: // focus loss cancels the edit like Escape. Enter keeps focus // in the input while its navigation is in flight, so a - // submitted path is never withdrawn by this handler. - onBlur={cancelPathEdit} + // submitted path is never withdrawn by this handler; rows and + // the show-hidden toggle suppress focus steal on mousedown so + // a click on them lands before any cancel. Window/tab focus + // loss also fires blur in some engines — only a focus move + // within a focused document reads as leaving the editor. + onBlur={() => { + if (!document.hasFocus()) return + cancelPathEdit() + }} /> )}
@@ -455,7 +481,6 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, selectedPath={selected?.path ?? null} busy={parentInert} onPick={select} - wide={!twoPane} showHidden={showHidden} filterPrefix={draftPrefixFor(parent, pathDraft)} /> @@ -467,7 +492,6 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, selectedPath={null} busy={parentInert} onPick={advance} - wide={false} showHidden={showHidden} filterPrefix={draftPrefixFor(child, pathDraft)} /> @@ -498,6 +522,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, className={clsx(css.showHiddenToggle, showHidden && css.showHiddenToggleActive)} aria-pressed={showHidden} disabled={parentInert} + // The toggle composes with the path editor (dot-led prefixes and + // this filter interleave): don't steal focus, so toggling never + // blur-cancels a draft mid-thought. + onMouseDown={(event) => { event.preventDefault() }} onClick={() => { setShowHidden(prev => !prev) }} > {showHidden && } diff --git a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx index 98f3bd6e4f..af3aff5385 100644 --- a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx +++ b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx @@ -107,9 +107,11 @@ describe('DirectoryBrowser', () => { const b = mount() await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) expect(screen.queryByText('.config')).toBeNull() - // The fixed-label toggle reports its state through aria-pressed. + // The fixed-label toggle reports its state through aria-pressed. Its + // mousedown never steals focus (so it composes with the path editor). const toggle = screen.getByRole('button', { name: 'browser.showHidden' }) expect(toggle.getAttribute('aria-pressed')).toBe('false') + fireEvent.mouseDown(toggle) fireEvent.click(toggle) expect(toggle.getAttribute('aria-pressed')).toBe('true') expect(screen.getByText('.config')).toBeTruthy() @@ -243,6 +245,58 @@ describe('DirectoryBrowser', () => { expect(screen.getByRole('listitem').textContent).toBe('Documents') }) + it('filters the child pane in two-pane mode and follows the draft back up a level', async () => { + mount() + await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) + fireEvent.click(rowButton(screen.getByRole('listitem'))) + await waitFor(() => { expect(columns()).toHaveLength(2) }) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + const input = screen.getByLabelText('browser.editPath') + // The seed comes from the selection, so the draft tail addresses the + // RIGHT pane (the selection's children). + expect(input.value).toBe(`${DOCS}/`) + fireEvent.change(input, { target: { value: `${DOCS}/h` } }) + expect(within(columns()[1]!).getByText('harness')).toBeTruthy() + fireEvent.change(input, { target: { value: `${DOCS}/zzz` } }) + expect(within(columns()[1]!).queryAllByRole('listitem')).toHaveLength(0) + expect(within(columns()[0]!).getByText('Documents')).toBeTruthy() + // Erasing back into the parent's own path moves the filter to the LEFT + // pane and releases the right one. + fireEvent.change(input, { target: { value: `${HOME}/zz` } }) + expect(within(columns()[0]!).queryAllByRole('listitem')).toHaveLength(0) + expect(within(columns()[1]!).getByText('harness')).toBeTruthy() + }) + + it('keeps the path editor open when blur comes from window focus loss', async () => { + mount() + await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + const input = screen.getByLabelText('browser.editPath') + // A blur while the document itself lost focus (window switch, dev-tools + // focus) must not discard the draft. + const hasFocus = vi.spyOn(document, 'hasFocus').mockReturnValue(false) + fireEvent.blur(input) + expect(screen.getByLabelText('browser.editPath', { selector: 'input' })).toBeTruthy() + hasFocus.mockRestore() + }) + + it('picking a filtered row adopts it and closes the path editor', async () => { + mount() + await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + const input = screen.getByLabelText('browser.editPath') + fireEvent.change(input, { target: { value: `${HOME}/do` } }) + // The row suppresses focus steal on mousedown (no blur-cancel unmounts + // the filtered rows mid-gesture), then the click both selects the row + // and closes the editor. + const row = rowButton(screen.getByRole('listitem')) + fireEvent.mouseDown(row) + fireEvent.click(row) + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + await waitFor(() => { expect(columns()).toHaveLength(2) }) + expect(screen.getByRole('button', { name: 'browser.home' })).toBeTruthy() + }) + it('seeds and filters with backslashes on a Windows-rooted listing', async () => { const ROOT = 'C:\\' const windowsListing: DirectoryListing = {