| 1 | # File Browser Modal DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the WebUI file browser workflow for modal and right-canvas Files surface entry points. |
| 6 | |
| 7 | ## Ownership |
| 8 | |
| 9 | - `file-browser.html` owns file list markup, path/search controls, scoped styles, and modal/canvas footer behavior. |
| 10 | - `file-browser-store.js` owns directory loading, remembered-location state, selection, upload/download/delete actions, and surface handoff state. |
| 11 | - `rename-modal.html` owns rename and create-folder prompts that reuse the file-browser store. |
| 12 | |
| 13 | ## Local Contracts |
| 14 | |
| 15 | - Keep `open(path)` as the modal entry point for workflows that await browser close. |
| 16 | - Keep `openSurface(path)` as the right-canvas entry point; it must load files without opening or awaiting a modal. |
| 17 | - The floating file-browser modal must use the shared surface modal chrome so it remains draggable/resizable and exposes Focus mode. |
| 18 | - Preserve remembered-directory behavior: explicit paths win, then remembered path, then `$WORK_DIR`. |
| 19 | - Empty mounted startup states must self-heal to the `$WORK_DIR` default instead of rendering a blank path and empty list. |
| 20 | - Preserve picker modes for Editor Open and Save As: Editor Open selects one or more Markdown or plain text files with a pinned primary action, and Save As selects the current folder plus a `.md` or `.txt` file name. |
| 21 | - Keep the row-level Open in Editor action visible outside the overflow menu for Editor-owned `.md` and `.txt` files. |
| 22 | - Keep Extract available for supported archive files; extraction must create a new sibling folder and reject unsafe member paths and links. |
| 23 | - Keep row action menus visible without disabling file-list scrolling; menus may float outside the scroll container but must still close on outside click, Escape, action click, and list scroll. |
| 24 | - Keep the file list readable in narrow canvas/modal containers by hiding the Modified date column before sacrificing the Name or Size columns. |
| 25 | - Keep New file and New folder controls icon-only across canvas and modal modes while preserving accessible labels. |
| 26 | - Keep narrow mobile controls compact: Up shares the path row, and New file/New folder share the search row. |
| 27 | - Preserve surface actions that route supported files to Browser, Desktop, or Editor. |
| 28 | - Keep native drag moves available outside picker modes: dragging an unselected row moves only that row without changing selection, dragging a selected row moves the selection, folder rows accept drops, and Up moves items to the parent directory. Moves must reject overwrites and self-nesting. |
| 29 | |
| 30 | ## Work Guidance |
| 31 | |
| 32 | - Share markup and store behavior between modal and canvas modes; branch only on explicit component `mode`. |
| 33 | - Keep modal footer relocation compatible with `data-modal-footer` while allowing canvas mode to render inline controls. |
| 34 | |
| 35 | ## Verification |
| 36 | |
| 37 | - Smoke-test opening Files as a modal and from the right-canvas rail. |
| 38 | - Run targeted file-browser tests after behavior changes. |
| 39 | |
| 40 | ## Child DOX Index |
| 41 | |
| 42 | No child DOX files. |