Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(design): add GFS move-forbidden UX matrix and breadcrumb drop-move plan
Miguelon Peluchon966a3d6473c7
diff --git a/docs/design/gfs-breadcrumb-drop-move.md b/docs/design/gfs-breadcrumb-drop-move.mdnew file mode 100644index 000000000..bd9c48603--- /dev/null+++ b/docs/design/gfs-breadcrumb-drop-move.md@@ -0,0 +1,127 @@+# Breadcrumb drop-move — implementation plan (Control UI, Desktop parity phase 2)++**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+refused breadcrumb drops.++**HARD CONSTRAINT — NO BACKEND CHANGES.** The move PATCH, permission model, and policy+server contracts are frozen. Everything here is browser/renderer-side. Allowed areas:+`control-ui/**`, `desktop-app/ui/**` (phase 2), and only surface-agnostic pure additions+to `packages/gfs-interaction-policy` if genuinely needed. Do **not** touch+`control-api`, `external-rest-api`, `gfs-controller`, `deploy/`, or any DB.++---++## 1. Feature++Users drag a file **or folder** from the listing onto a **breadcrumb crumb** — an+ancestor folder (e.g. `Product` while browsing `main › Product › live tests`) or the+drive root (`main`) — to move it there. Today the only upward-move path is the row ⋯+menu → Move dialog. Crumbs are plain buttons (`GfsBrowser.tsx`,+`cu-gfs-breadcrumb__button`) with no drag handlers, while rows already advertise+draggability ("Drag {name} into a folder to move it", `GfsBrowser.tsx:2372`).++## 2. Current state (receipts)++| 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` |+| 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 |++## 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.++## 4. Files to touch (allowlist)++| Area | Change |+|---|---|+| `control-ui/components/GfsBrowser.tsx` | crumb drag handlers, verdict state per crumb, drop wiring into existing commit path |+| `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) |++## 5. Test plan++- ☐ Drag `abac.md` onto `Product` crumb → confirm dialog shows "Move abac.md to+ Product?" → commit → listing refreshes; file gone from `live tests`, present in+ `Product`.+- ☐ Drag onto drive-root crumb `main` → moves to root (admin plane).+- ☐ Drag onto the ACTIVE crumb → info "already here", no error styling, no PATCH.+- ☐ 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.+- ☐ 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+ keyboard path; verdicts announced via aria-live.+- ☐ Control UI production build + permission suites green; Desktop untouched in+ phase 1.++## 6. Acceptance criteria++1. From any listing row, a file or folder can be moved to any visible ancestor crumb+ (including root) with one confirmation — no ⋯ menu needed.+2. Every refused crumb drop explains WHY in plain language (matrix doc), visually and+ to SRs; nothing is silently ignored.+3. Zero changes outside the allowlist in §4; backend untouched (verifiable via+ `git diff --stat`).+4. All existing drag-and-drop suites (unit, component, property, Playwright spec)+ remain green; new cases in §5 pass.diff --git a/docs/design/gfs-move-forbidden-ux-matrix.md b/docs/design/gfs-move-forbidden-ux-matrix.mdnew file mode 100644index 000000000..40327249e--- /dev/null+++ b/docs/design/gfs-move-forbidden-ux-matrix.md@@ -0,0 +1,135 @@+# EvenDrive move-forbidden UX — full case matrix++**Worktree:** `feat/even-drive-drag-and-drop-fix` · **Scope:** Desktop sidebar tree + Files+panel (Control UI parity noted where it differs)+**Sibling doc:** [`gfs-breadcrumb-drop-move.md`](./gfs-breadcrumb-drop-move.md) — breadcrumb drop targets; refused drops there MUST use this matrix for messaging.+**Goal:** every forbidden-move case tells the user WHAT happened and WHY — visually and+programmatically — instead of the current silent refusal.++---++## 1. Why it is silent today (receipts)++The deny **reason is computed and then thrown away** at the UI layer:++| Layer | File | What it does |+|---|---|---|+| Structure decision | `packages/gfs-interaction-policy/dragPolicy.cjs` → `decideDragStructure` | returns `{kind:'deny', reason:'self'│'cross-drive'│'root-source'│'same-parent'│'descendant'}` or `server-check-required` |+| Authority decision | `dragPolicy.cjs` → `decideDragAuthority` | returns `{kind:'deny', reason:'destination-write'│'source-write'│'source-delete'}`, `checking`, `unavailable`, `observed-allowed` |+| Adjudication | `desktop-app/ui/src/gfs/dragAdjudication.ts` | maps probes/session loss to `session-lost`, `unavailable`, `target-unavailable`, `source-location-unknown` |+| Paint | `FileExplorerTree/index.tsx:314` | row gets `data-drop-state={allowed│denied│checking│unavailable}` — **reason collapsed to a boolean-ish state** |+| Speech | `dropVerdict.ts` (RP-026) | generic only: *"You cannot move into {target}."* — no reason |+| CSS | `styles.css:1987-2010` | **Tree:** `denied` only de-emphasizes the label (1999) — nearly invisible. **Files grid:** `checking`/`allowed` styles exist; **`denied` has NO style at all** → this is the "no blue highlight and no idea why" bug |++**The two symptoms you hit are exactly this:**+- Sidebar tree: `denied` ≈ invisible (label dimming only) → "nothing happens".+- Files panel: `allowed` paints the blue highlight; `denied` has no CSS → no highlight,+ no explanation.++Design rule already in the codebase (RP-026 header comment): *paint the verdict on the+row for sighted users, speak it for SR users*. The fix keeps that shape but carries the+**reason** through and adds a **persistent, readable explanation at drop time** (row+tints alone are too subtle to read a reason from).++---++## 2. The two-phase gate (when is a move forbidden?)++A move must pass BOTH phases. The reason shown must name the phase.++**Phase A — drag adjudication (before confirm):** structure check → authority check+(`decideDragAuthority`: needs `write` + `delete` on the **physical source parent** and+`write` on the destination; bits may be direct/inherited/team).+**Phase B — commit (after confirm):** server re-validates atomically (cycle/self guard,+destination kind, parent permissions) and executes the PATCH (with numbered-name ladder+on 409).++> Verified live example (dev cluster, 2026-10-23): dragging `live tests` → `Assets`+> fails Phase A with `source-write`/`source-delete` because `live tests`' physical+> parent is a nameless folder where the desktop user holds **zero** bits — even though+> the user holds ALL bits on both `live tests` and `Assets` themselves. `gfs_audit`+> shows **no mutation rows** → refused client-side, silently.++---++## 3. Phase-A matrix — every drag-time forbidden case++| # | Reason (code) | Trigger — what the user did | Underlying rule | Sidebar tree feedback | Files panel feedback | Persistent message (drop) | SR announcement |+|---|---|---|---|---|---|---|---|+| A1 | `self` | Drop onto the dragged item itself | `dragPolicy.cjs:73` | row `denied` + tooltip | row `denied` | Banner/toast: "You dropped {name} onto itself. Pick a destination folder." | "You cannot move {name} into itself." |+| A2 | `cross-drive` | Drop across drives | `dragPolicy.cjs:76` | same as A1 | same | "Moving between drives isn't supported." | same, spoken |+| A3 | `root-source` | Source is the drive root (or virtual root item that is physically root) | `dragPolicy.cjs:79` | refused at dragstart: don't start a session, or show `denied` on all targets | same | "This location is the top level — it can't be moved." | spoken |+| A4 | `same-parent` | Target IS the physical parent (no-op move) | `dragPolicy.cjs:84` + path form `:118` | row `denied` | row `denied` | "{name} is already in {target}." — **NOT an error tone; info**. Critical with the flat sidebar: e.g. `Assets` physically lives in `Product`, so dragging Assets→Product is a no-op even though it *looks* like a real move | "{name} is already in {target}." |+| A5 | `descendant` | Folder dropped into its own subtree | `dragPolicy.cjs:92` | row `denied` on the whole subtree | highlight suppressed | "You can't move {name} into a folder inside itself." | spoken |+| A6 | `destination-write` | No `write` on destination (e.g. read-only share) | `dragPolicy.cjs:146` — checked FIRST (surface the user acts on) | row `denied` — this is the case where the blue highlight must NOT appear | row `denied`, no blue | "You don't have permission to move items into {target}. You need edit access to the destination folder." | spoken with reason |+| A7 | `source-write` | No `write` on the physical **source parent** | `dragPolicy.cjs:147` | row `denied` | row `denied`, no blue | "You can move {name} within places you manage, but not out of its current folder — you don't have edit access to the folder that contains it." | spoken |+| A8 | `source-delete` | `write` but no `delete` on the source parent | `dragPolicy.cjs:148` | row `denied` | row `denied`, no blue | "Removing {name} from its current folder needs delete access there. You have edit, but not delete." | spoken |+| A9 | `checking` | Bits not yet known (cold hover) | `dragPolicy.cjs:140` | neutral spinner-tint row | neutral | none (transient) | "Checking whether you can move into {target}…" |+| A10 | `unavailable` / `target-unavailable` / `source-location-unknown` | Probe failed (network/5xx); hover budget exhausted | `dragAdjudication.ts:58-98` | row `unavailable` — must NOT look denied | row `unavailable` | "EvenDrive couldn't verify the move just now. Check your connection and try again — the move is still allowed on drop." (drop-time check remains available by contract) | spoken |+| A11 | `session-lost` | 401 during probe | `dragAdjudication.ts:58` | gesture ends; re-auth prompt | same | "Your session ended. Sign in again to continue moving files." (session revoked per med-probe-401) | spoken |+| A12 | `server-check-required` | Ancestry unproved (grants start below root) | `dragPolicy.cjs:121` | row `checking` — NOT denied; stays landable | neutral | none at hover; drop proceeds to server verdict (Phase B) | "Checking…" |++---++## 4. Phase-B matrix — commit-time outcomes (after "Move" confirm)++Source of truth: `moveCommit.ts` `presentMoveCommitOutcome` (rev-2 §8 toasts) ++`dragAdjudication.ts` verdict reasons.++| # | Outcome | Trigger | Message (toast) | Tone |+|---|---|---|---|---|+| B1 | `committed` (+ optional `renamedTo`) | PATCH 200 | "Moved {source} to {destination}." / "…as {renamed}." | success |+| B2 | numbered-name conflict resolved | 409 → ladder accepted | same as B1 with "as {renamed}" | success |+| B3 | conflict ladder exhausted | 409 × N > limit | "A name collision couldn't be resolved for {source} in {destination}. Try renaming first." | error |+| B4 | source vanished (404 on source re-resolve/dispatch) | rp-027 | "{source} no longer exists — it may have been deleted or moved by someone else." | error |+| B5 | destination vanished (404 on destination) | rp-027 | "The destination folder no longer exists." | error |+| B6 | server structural deny (cycle/kind/parent-permission re-check) | PATCH 403/400 | distinct copy per status; if parent-permission: same wording as A7/A8 + "the change was not made" | error |+| B7 | transport loss, outcome unknown | fetch threw after dispatch | "The connection dropped while moving {source}. EvenDrive is checking whether the move completed…" then verify-by-identity → converge to B1 or "couldn't confirm; refresh Files" | warning→info |+| B8 | 5xx | server error | "EvenDrive couldn't complete the move. Nothing was changed. Try again." | error |+| B9 | `session-lost` | 401 at commit | "Your session ended. Sign in again — the move was not completed." | error |+| B10 | user stopped / canceled dialog | Stop / Esc / backdrop | silent or "Move canceled." (per PR's stop-notice pattern) | info |++---++## 5. Visual spec (what to change)++1. **Carry the reason**: extend `GfsDropVerdict` (dragSession.types) with `reason`;+ `data-drop-reason` attribute next to `data-drop-state` (FileExplorerTree:314, grid+ rows). Tests in `dropVerdict`/RP-026 keep their one-wording-per-verdict contract by+ keying on reason, not surface.+2. **Give `denied` a real treatment in BOTH surfaces** (today: tree = label dim only,+ grid = nothing):+ - Tree row + grid row: red/neutral border tint (match existing `allowed` blue+ treatment, not-blue), reduced-opacity drag ghost.+ - **Do NOT** use error-red for `same-parent` (A4: info) or `unavailable` (A10:+ warning) — reasons map to tones: deny=error, no-op=info, unknown=warning.+3. **Drop-time persistent message**: on a refused DROP, show the reason message from+ the matrix as a toast (reuse `pushToast` from `presentMoveCommitOutcome`) or the+ `StatusBanner` component — banners for `session-lost` (persistent), toasts for+ one-shot denies. Hover-time stays row-tint-only (no toast spam while dragging over+ many rows).+4. **SR**: extend `gfsDropVerdictAnnouncement(state, target)` →+ `(state, target, reason)`; on drop, announce the full reason sentence (RP-026+ contract: same wording per reason on every surface).+5. **Blue highlight rule stays**: only `observed-allowed` (and `checking`→neutral)+ paints blue. The fix is not to show blue more — it's to SAY WHY when it isn't blue.++## 6. Plain-language copy rules (match PR's existing tooltip style)++- Name the **missing access**, not the bit: "edit access" = write, "delete access" =+ delete. Never "source-parent-write".+- Distinguish the **three places** a move touches: the item, the folder it leaves, the+ folder it enters. A7/A8 messages must mention "the folder that contains it".+- No-op moves (A4) get info tone + "already there", never "cannot".+- Unknown (A10) never implies forbidden — say "couldn't verify, try again".++## 7. Manual test matrix (maps to your PR checklist lane 1/3)++- ☐ A4 drag `Assets` onto `Product` (physically already inside) → info "already there", NOT red+- ☐ A7 drag `live tests` onto any folder → refused drop + banner naming "the folder that contains it"+- ☐ A6 read-only destination share → no blue, reason names destination+- ☐ A5 folder into own subfolder → refusal names self-containment+- ☐ A10 kill network mid-hover → warning tone, drop still attempts+- ☐ B4/B5 vanish source/destination via second user → distinct messages+- ☐ B7 drop during network cut → "checking whether it completed", then converge+- ☐ SR: every refused drop announces reason; sighted: every denied row readable