Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(design): audit breadcrumb drop-move plan
M604660c08a59
diff --git a/docs/design/gfs-breadcrumb-drop-move.md b/docs/design/gfs-breadcrumb-drop-move.mdindex bd9c48603..0067fa5a9 100644--- a/docs/design/gfs-breadcrumb-drop-move.md+++ b/docs/design/gfs-breadcrumb-drop-move.md@@ -1,4 +1,4 @@-# Breadcrumb drop-move — implementation plan (Control UI, Desktop parity phase 2)+# Breadcrumb drop-move — implementation plan (Control UI)**Sibling doc:** [`gfs-move-forbidden-ux-matrix.md`](./gfs-move-forbidden-ux-matrix.md) —the deny-reason → message/visual matrix. This feature MUST reuse those treatments for@@ -6,7 +6,7 @@ refused breadcrumb drops.**HARD CONSTRAINT — NO BACKEND CHANGES.** The move PATCH, permission model, and policyserver contracts are frozen. Everything here is browser/renderer-side. Allowed areas:-`control-ui/**`, `desktop-app/ui/**` (phase 2), and only surface-agnostic pure additions+`control-ui/**`, this plan document, and only surface-agnostic pure additionsto `packages/gfs-interaction-policy` if genuinely needed. Do **not** touch`control-api`, `external-rest-api`, `gfs-controller`, `deploy/`, or any DB.@@ -26,62 +26,73 @@ draggability ("Drag {name} into a folder to move it", `GfsBrowser.tsx:2372`).| Fact | Where ||---|---|| Breadcrumb = `<nav aria-label="Breadcrumb">` of per-crumb `<button>`s; click = `goToCrumb(index)`; active crumb carries `aria-current="page"`; only active crumb has ⋯ menu | `control-ui/components/GfsBrowser.tsx` (~line 2255) |-| Crumb model: `{ id, rid, gfsUri, name, version, isDriveRoot }`; drive root is synthetic (`id === null`) — `isDriveRootCrumb` | `GfsBrowser.tsx:141-149` |+| Crumb model: `{ id, rid, gfsUri, name, version, isDriveRoot }`; drive root starts synthetic (`id === null`) then receives its real ID and RID from `TreePage.rootResourceId`; `isDriveRoot` remains true — `isDriveRootCrumb` | `GfsBrowser.tsx`, `Crumb`, `createDriveRootCrumb`, root hydration in `load` || Rows: `draggable`, native tooltip, per-row `onDrop` + container `onDrop` → `handleGfsDrop` | `GfsBrowser.tsx:2217, 2372, 2389` || Shared, browser-safe move policy (structure + authority + convergence) already consumed by both UIs | `packages/gfs-interaction-policy/dragPolicy.cjs` |-| One-confirmation move flow with numbered-name toggle + impact copy | `control-ui/components/GfsMoveConfirmDialog/index.tsx`, `GfsMoveDialog/index.tsx` |-| Commit runner re-resolves source, sends version, bounded 409 ladder, honest unknown-outcome handling | `desktop-app/ui/src/gfs/moveCommit.ts` pattern; Control UI equivalent in its drop commit path |+| Folder confirmation with numbered-name toggle + impact copy; Move dialog is a separate keyboard path | `control-ui/components/GfsMoveConfirmDialog/index.tsx`, `GfsMoveDialog/index.tsx` |+| Existing Control UI commit runner sends the listing version and bounds the 409 ladder; it does **not** re-resolve either endpoint or implement Desktop outcome verification | `GfsBrowser.tsx`, `moveResource` |+| Control UI has one local row drag ref and a blue target ID, **no** `hoverVerdict`, authority probes, cold-hover budget, gesture epochs, or reason-aware announcements | `handleResourceDragStart`, `handleFolderDragOver`, `handleFolderDrop` |+| Existing row files move directly; folder drops use one confirmation | `handleFolderDrop`, `GfsMoveConfirmDialog` |## 3. Design-### 3.1 Drop targets-- **Every crumb** becomes a drop target: all ancestor crumbs **and the drive-root- crumb** (`main`). The **active crumb** is also a target but always resolves to- `same-parent` (policy `dragPolicy.cjs:84/118`) → info-level "already here" (matrix- doc §3 A4), never error styling.-- Root crumb (`id === null`): root can never be inside the source's subtree, so the- structural decision is trivially safe; treat as a normal directory target whose- identity is the drive root. Authority: use the drive-root affordances if the session- exposes them; in the admin plane the operator is intrinsic (all bits) so the drop- proceeds. For non-operator desktop parity (phase 2), admit the drop and let the- server be the authority (`server-check-required` semantics) — never fake a deny.--### 3.2 Reuse the existing drag pipeline (do not fork it)-- Crumbs join the **same drag session**: `dragstart` on rows already publishes source- facts; crumbs register as targets with `dragover` (preventDefault + verdict request),- `dragleave`, `drop`.-- Hover: request the same adjudication (`hoverVerdict`) — shared cold-hover budget,- cached/canceled checks cost nothing; verdict states `checking │ allowed │ denied │- unavailable` painted on the crumb via `data-drop-state` (+ `data-drop-reason` per the- matrix doc's implementation notes).-- Drop: same drop-time adjudication (priority check; ownership epoch captured; stale- gestures cannot commit). Then the **same** confirm dialog + commit runner as row- drops — one confirmation, numbered-name suggestion on conflict.--### 3.3 Visual + copy-- Allowed crumb: blue tint (same treatment as `allowed` rows). Denied crumb: never- blue; on refused drop surface the reason message from the matrix doc (§3 A1–A12) —- toast, correct tone (error / info for `same-parent` / warning for `unavailable`).-- SR: announce verdict with reason on the crumb (same one-wording-per-reason contract- as RP-026; Control UI equivalent of `gfsDropVerdictAnnouncement`).-- Keep the native row tooltip; optionally extend it: "Drag {name} into a folder or the- breadcrumb to move it".--### 3.4 Races and gotchas (each already bit this PR once)-- **Crumb click vs drop:** `dragover` must `preventDefault()`; `drop` must- `preventDefault()` + `stopPropagation()` so the container-level `onDrop`- (`GfsBrowser.tsx:2217`) doesn't double-handle; clicks don't fire after a drop, but- verify no navigation happens on `mouseup` during drag.-- **Breadcrumb reconstruction race (R7-M1):** capture the crumb's identity- (`id`/`rid`/`gfsUri`/`version`) at drop time, not the live trail; a late trail- rebuild must not re-anchor an in-flight commit. The commit runner's pre-dispatch- re-resolve must resolve the **target** too, not only the source.-- **Ownership epochs:** dropping on a crumb is a normal drop — the same gesture-epoch- guard applies (a newer gesture supersedes stale work; dragend must not cancel the- drop's own adjudication).-- **After commit:** reuse `planMoveConvergence` (old + new parent child-listing- refetch). The user stays in the current folder; the moved item disappears from the- listing. No auto-navigation.+### 3.1 Drop targets and audit decisions (2026-10-23)+- Every crumb is a drop target: ancestors, the `main` drive root, and the active+ folder. Capture the physical source-parent ID at dragstart; active-crumb drops+ resolve to `same-parent`, with named “already in” info feedback and no PATCH.+- **Root question resolved:** use the hydrated root ID/RID (not null, a made-up ID,+ or an authority denial). It is a directory destination with canonical path `/`.+ If identity is not available yet, show `unavailable` and retry on drop. Control UI+ is the operator plane: authority is intrinsic, including at root. No affordance+ probe is necessary and no permission denial is fabricated.+- A visible crumb is an observed ancestor, not an unconditional ancestry proof:+ stream reconstruction or remote moves can change it. Re-resolve both captured+ endpoint identities before admission and again before drag commit; use fresh+ canonical paths with `decideDragPathStructure`. Missing paths defer structure to+ the atomic server guard; failed resolution prevents dispatch with honest feedback.++### 3.2 Extend the existing drag pipeline+- Crumb and row handlers share one admission function, one drag session/epoch,+ `confirmMoveTarget`, and `moveResource`; do not introduce a separate crumb runner.+- Hover uses cached observed IDs/paths and shared pure structure policy. No cold+ hover requests are needed for these operator listings, so a Desktop-style hover+ budget and its exhausted-budget scenario are inapplicable here. Unknown ancestry+ remains landable (`checking` / `server-check-required`), never a fake denial.+- Existing file-to-row drops keep moving directly. **Both files and folders dropped+ onto crumbs get one confirmation**, as requested. Extend the same confirmation+ with source kind for accurate file impact copy and accessible naming; keep the+ existing folder dialog name and copy. Keep numbered naming in that dialog.+- Drop checks have priority because they are the only network adjudication. A failed+ hover observation does not consume or disable drop-time checking.++### 3.3 Visual and messaging contract+- Paint `data-drop-state` and `data-drop-reason` on crumbs and rows. Only allowed+ targets get blue. Checking is neutral, unavailable warning, ordinary denials error,+ and `same-parent` neutral/info. Use the existing CSS tokens.+- Reuse the sibling matrix §3 wording by reason in an app-local browser-safe helper.+ Share hover announcements and drop refusal copy across row/crumb handlers. Hover+ announces through aria-live without toast spam; refused drops use the toast stack+ (which is itself live). Session loss also stays in a persistent page alert.+- Operator permission denies A6–A8 cannot be produced truthfully from local bits;+ cover their copy mapping in pure tests and surface server refusal honestly. Never+ manufacture missing bits to meet a test. Desktop parity remains out of scope.+- Keep native row tooltips and extend them to mention breadcrumbs.++### 3.4 Races and convergence+- Capture crumb ID/RID/URI/version into a destination value synchronously at drop.+ Stop propagation/default on internal crumb drops so the upload container cannot+ process them. Keep click/keyboard breadcrumb navigation intact.+- A monotonic gesture epoch supersedes pending admission/confirmation/commit reads.+ Dragend clears hover/source presentation but does not invalidate an accepted drop.+ A newer drag invalidates stale reads and confirmation. Unmount invalidates work.+- Immediately before dispatch, resolve **both endpoints by immutable URI**, validate+ returned identities and destination kind, and use the fresh source version. Do+ not consult a rebuilt trail for the destination (R7-M1). Check epoch after reads+ and immediately before every PATCH; already dispatched requests cannot be recalled.+- Preserve existing R5/R7 trail reconstruction. Use `planMoveConvergence` to invalidate+ observed old/new parent caches; refresh the live current location after a drag move,+ keeping the user there instead of navigating to the target. Do not claim a failed+ transport dispatch left the resource unchanged; report an unknown outcome.## 4. Files to touch (allowlist)@@ -91,7 +102,10 @@ draggability ("Drag {name} into a folder to move it", `GfsBrowser.tsx:2372`).| `control-ui/app/globals.css` | `cu-gfs-breadcrumb__button` drop-state styles (`checking/allowed/denied/unavailable` + reason attribute) || `control-ui/e2e/run-gfs-drag-and-drop.mjs` + component tests | cases below || `packages/gfs-interaction-policy` | ONLY if a pure helper (e.g. root-target facts) is genuinely needed; no signature breaks |-| Phase 2: `desktop-app/ui/src/pages/FilesPage.tsx` + `styles.css` | Desktop Files breadcrumb parity (`aria-label="Breadcrumb"` exists there today) |+| `control-ui/lib/gfsDragFeedback*` + colocated types/tests | reason/tone/announcement mapping |+| `control-ui/components/GfsMoveConfirmDialog/**` | source-kind-aware file confirmation |++Desktop Files and the sibling UX matrix document are owned by another task and must not be edited.## 5. Test plan@@ -103,11 +117,11 @@ draggability ("Drag {name} into a folder to move it", `GfsBrowser.tsx:2372`).- ☐ Folder onto ancestor crumb (incl. a crumb above its own parent) → moves;descendant targets are impossible by construction (crumbs are ancestors) — assert no`descendant` case can trigger here.-- ☐ Denied reasons per matrix doc: `destination-write` / `source-write` / /- `source-delete` → crumb not blue, refused drop shows the reason message + SR- announcement.-- ☐ Hover budget exhausted → crumb shows `unavailable`; drop still runs the drop-time- check.+- ☐ Structural refusal and same-parent info have reason attributes, correct styles,+ toasts and SR wording. Pure copy tests cover `destination-write`, `source-write`,+ and `source-delete`; operator hover never fabricates these permission denials.+- ☐ Unavailable endpoint → warning, no PATCH; a later drop retries resolution. No+ cold-hover budget exists in this operator surface (audit decision §3.2).- ☐ Breadcrumb reconstruction mid-drag → drop commits against captured crumb identity;no mis-anchored trail (R5-M1/R7-M1 regression suite stays green).- ☐ Keyboard/access: crumb buttons keep click-navigation; Move dialog unchanged as the@@ -125,3 +139,11 @@ draggability ("Drag {name} into a folder to move it", `GfsBrowser.tsx:2372`).`git diff --stat`).4. All existing drag-and-drop suites (unit, component, property, Playwright spec)remain green; new cases in §5 pass.++## 7. Verification ownership++The runner `e2e/run-gfs-drag-and-drop.mjs` validates Playwright inventory; actual+journeys belong in `e2e/gfs-drag-and-drop.spec.ts`. Extend both so the gate requires+the new breadcrumb cases. Component tests own deferred-read/epoch and reconstruction+races. Live E2E requires configured owned endpoints and credentials; report it+separately from the production build and permission/unit suites.