chore: archive v0.2 phase directories to milestones/v0.2-phases/

Moves phases 08–11 execution artifacts from .planning/phases/ to .planning/milestones/v0.2-phases/ to keep .planning/phases/ clean for the next milestone. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-17 14:34:52 +02:00
parent e008bf7dae
commit 123ae5b29b
101 changed files with 759 additions and 4 deletions
@@ -0,0 +1,393 @@
+---
+phase: 10-ux-interaction
+plan: 13
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - frontend/src/components/ui/TreeItem.vue
+  - frontend/src/components/storage/StorageBrowser.vue
+  - frontend/src/App.vue
+  - frontend/src/components/documents/SearchBar.vue
+  - frontend/src/components/layout/OsDragOverlay.vue
+  - frontend/src/__tests__/keyboard.test.js
+  - frontend/src/components/ui/__tests__/TreeItem.test.js
+  - frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js
+autonomous: true
+requirements: [UX-02, UX-03, UX-05, UX-06, UX-07, UX-08, UX-09]
+gap_closure: true
+
+must_haves:
+  truths:
+    - "Sidebar Cloud/Folder sections show animated shimmer rows while async data loads — no 'Loading…' text visible"
+    - "Admin routes (/admin/*) render with no AppSidebar — AdminLayout is the sole layout component"
+    - "Pressing '/', 'U', or 'N' in the file manager dispatches to the actual FileManagerView instance — not a RouterView proxy"
+    - "Pressing Escape in the search input clears the field and preserves focus — no browser-native blur"
+    - "Dropping an OS file on the drag overlay triggers upload — capture-phase window listener fires before folder-row handlers"
+    - "Search bar and sort controls are visible at the root of both local and cloud file browsers"
+  artifacts:
+    - path: "frontend/src/components/ui/TreeItem.vue"
+      provides: "Three animate-pulse shimmer rows in the v-if='loading' branch"
+      contains: "animate-pulse"
+    - path: "frontend/src/components/storage/StorageBrowser.vue"
+      provides: "showSearch computed returns true for mode === 'local' OR mode === 'cloud'"
+    - path: "frontend/src/App.vue"
+      provides: "Third template branch for admin routes (no AppSidebar); getFileManagerInstance() via matched.find for keyboard dispatch"
+    - path: "frontend/src/components/documents/SearchBar.vue"
+      provides: "@keydown.escape.prevent.stop suppresses browser native blur on type='search'"
+    - path: "frontend/src/components/layout/OsDragOverlay.vue"
+      provides: "window drop listener registered with capture=true; removeEventListener also passes true"
+  key_links:
+    - from: "frontend/src/App.vue (onKeydown)"
+      to: "FileManagerView.focusSearch / triggerUpload / startNewFolder"
+      via: "router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default"
+      pattern: "instances\\.default"
+    - from: "frontend/src/components/layout/OsDragOverlay.vue"
+      to: "window drop event"
+      via: "addEventListener('drop', handler, true)"
+      pattern: "addEventListener.*drop.*true"
+---
+
+<objective>
+Close all 6 UAT gaps from 10-UAT.md that block Phase 10 sign-off: sidebar shimmer (Gap 1), search-at-root visibility (Gap 2), admin sidebar bleed (Gap 3), keyboard shortcuts broken by RouterView proxy (Gap 4 — covers tests 11, 12, 13), Escape-breaks-search (Gap 5), and OS drag-drop not uploading (Gap 6).
+
+Purpose: Phase 10 is recorded complete in ROADMAP.md but UAT (10-UAT.md) shows 9 issues with 6 distinct root causes diagnosed. These targeted fixes close all 6 causes with minimal code change, restoring full UAT pass.
+
+Output: Five production files modified, three test files added. No new dependencies. No regressions.
+</objective>
+
+<execution_context>
+@/Users/nik/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/nik/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@/Users/nik/Documents/Progamming/document_scanner/.planning/PROJECT.md
+@/Users/nik/Documents/Progamming/document_scanner/.planning/ROADMAP.md
+@/Users/nik/Documents/Progamming/document_scanner/.planning/STATE.md
+@/Users/nik/Documents/Progamming/document_scanner/.planning/phases/10-ux-interaction/10-UAT.md
+
+<interfaces>
+<!-- Key contracts the executor needs. Extracted from codebase. No codebase exploration needed. -->
+
+From frontend/src/App.vue (current full state — relevant sections):
+```html
+<!-- Template — only two branches today: -->
+<AuthLayout v-if="route.meta.layout === 'auth'" />
+<div v-else class="flex h-screen overflow-hidden">
+  <AppSidebar />
+  <main class="flex-1 overflow-y-auto">
+    <router-view ref="routeViewRef" />   <!-- resolves to RouterView proxy, NOT FileManagerView -->
+  </main>
+</div>
+<ToastContainer />
+<OsDragOverlay @files-dropped="onOsFilesDropped" />
+```
+```js
+// script setup
+import { ref, onMounted, onUnmounted } from 'vue'
+import { useRoute } from 'vue-router'
+const route = useRoute()
+const routeViewRef = ref(null)         // ← remove this
+
+function onOsFilesDropped(files) {
+  routeViewRef.value?.handleOsDrop?.(files)  // ← fix to use getFileManagerInstance()
+}
+function onKeydown(e) {
+  // guard: INPUT/TEXTAREA/SELECT/contentEditable + dialog check omitted here
+  routeViewRef.value?.focusSearch?.()    // line 37 ← fix
+  routeViewRef.value?.clearSearch?.()    // line 40 ← fix
+  routeViewRef.value?.triggerUpload?.()  // line 43 ← fix
+  routeViewRef.value?.startNewFolder?.() // line 46 ← fix
+}
+```
+
+From frontend/src/router/index.js — admin route meta:
+```js
+{
+  path: '/admin',
+  component: () => import('../layouts/AdminLayout.vue'),
+  meta: { requiresAdmin: true },   // only on parent; children resolved via matched.some()
+  children: [/* AdminOverviewView, AdminUsersView, AdminQuotasView, AdminAiView, AdminAuditView */]
+}
+```
+
+From frontend/src/components/ui/TreeItem.vue — loading branch to replace (lines 48-52):
+```html
+<div
+  v-if="loading"
+  class="text-xs text-gray-400 py-1"
+  :style="{ paddingLeft: `${(depth + 1) * 12 + 8}px` }"
+>
+  Loading…
+</div>
+```
+
+Shimmer pattern to replicate (from AppSidebar.vue lines 60-64):
+```html
+<div v-if="loadingRoots" class="pl-7 py-1 space-y-1">
+  <div v-for="n in 3" :key="`sk-f-${n}`" class="flex items-center gap-2 py-1">
+    <div class="w-4 h-4 bg-gray-100 rounded animate-pulse shrink-0"></div>
+    <div class="h-3 bg-gray-100 rounded animate-pulse" :style="{ width: (50 + n * 15) + 'px' }"></div>
+  </div>
+</div>
+```
+
+From frontend/src/components/storage/StorageBrowser.vue line 287:
+```js
+const showSearch = computed(() => props.mode === 'local' && props.breadcrumb.length > 0)
+// TARGET STATE:
+const showSearch = computed(() => props.mode === 'local' || props.mode === 'cloud')
+```
+
+From frontend/src/components/documents/SearchBar.vue line 11:
+```html
+@keydown.escape="emit('update:modelValue', '')"
+<!-- TARGET STATE: -->
+@keydown.escape.prevent.stop="emit('update:modelValue', '')"
+```
+
+From frontend/src/components/layout/OsDragOverlay.vue (Options API — lines 52-63):
+```js
+mounted() {
+  window.addEventListener('dragenter', this.onDragEnter)
+  window.addEventListener('dragleave', this.onDragLeave)
+  window.addEventListener('dragover', this.onDragOver)
+  window.addEventListener('drop', this.onDrop)            // ← bubble phase; must become capture
+},
+beforeUnmount() {
+  window.removeEventListener('dragenter', this.onDragEnter)
+  window.removeEventListener('dragleave', this.onDragLeave)
+  window.removeEventListener('dragover', this.onDragOver)
+  window.removeEventListener('drop', this.onDrop)         // ← must match with true
+}
+```
+
+From frontend/src/views/FileManagerView.vue defineExpose (lines 190-196):
+```js
+// These ARE correct — all methods are exposed. The problem is App.vue never reaches this instance.
+defineExpose({
+  focusSearch: () => browserRef.value?.focusSearch?.(),
+  triggerUpload: () => browserRef.value?.triggerUpload?.(),
+  startNewFolder: () => browserRef.value?.startNewFolder?.(),
+  clearSearch: () => browserRef.value?.clearSearch?.(),
+  handleOsDrop: (files) => onFilesSelected({ files, autoClassify: true }),
+})
+```
+
+From frontend/src/__tests__/keyboard.test.js (existing structure):
+Uses mountFileManager() helper, vi.mock('../api/client.js', ...), vi.mock('../stores/auth.js', ...),
+vi.mock('../stores/topics.js', ...), setActivePinia(createPinia()), createRouter+createMemoryHistory.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Sidebar shimmer rows (TreeItem.vue) and search-at-root (StorageBrowser.vue)</name>
+  <files>
+    frontend/src/components/ui/TreeItem.vue
+    frontend/src/components/storage/StorageBrowser.vue
+  </files>
+  <action>
+    TreeItem.vue — replace the v-if="loading" div (lines 48-52) with a shimmer block. The replacement wraps three shimmer rows in a single container div. Apply the indent :style on the container (same binding the removed div had: `{ paddingLeft: \`\${(depth + 1) * 12 + 8}px\` }`). The container also gets `class="py-1 space-y-1"`. Each of the three inner rows uses `class="flex items-center gap-2 py-1"` and contains two children:
+    - Icon placeholder: `class="w-4 h-4 bg-gray-100 rounded animate-pulse shrink-0"`
+    - Text placeholder: `class="h-3 bg-gray-100 rounded animate-pulse"` with `:style="{ width: (50 + n * 15) + 'px' }"`
+    Use `v-for="n in 3"` with `:key="\`sk-t-\${n}\`"` on the inner row div.
+    Do not change any other branch (v-else-if loadError, v-else-if children.length===0, slot children) or any script section.
+
+    StorageBrowser.vue — change line 287 only. Change:
+      `const showSearch = computed(() => props.mode === 'local' && props.breadcrumb.length > 0)`
+    to:
+      `const showSearch = computed(() => props.mode === 'local' || props.mode === 'cloud')`
+    No template changes needed — SearchBar and SortControls already share v-if="showSearch".
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep -c "animate-pulse" src/components/ui/TreeItem.vue && grep "showSearch" src/components/storage/StorageBrowser.vue | grep "cloud"</automated>
+  </verify>
+  <done>
+    - `grep -c "animate-pulse" src/components/ui/TreeItem.vue` returns at least 2
+    - `grep -c "Loading" src/components/ui/TreeItem.vue` returns 0
+    - `grep "showSearch" src/components/storage/StorageBrowser.vue` contains `props.mode === 'cloud'`
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Admin sidebar bleed and keyboard instance resolution (App.vue)</name>
+  <files>frontend/src/App.vue</files>
+  <action>
+    Two root causes, one file. Apply both changes together.
+
+    CHANGE A — Admin sidebar bleed (Gap 3):
+    Insert a v-else-if branch in the template between the auth branch and the user-layout div. The new branch condition is `route.matched.some(r => r.meta.requiresAdmin)`. When true it renders only `<router-view />` — no AppSidebar, no main wrapper. The complete corrected template root (inside the component root, excluding ToastContainer and OsDragOverlay which stay unchanged):
+
+      1. `<AuthLayout v-if="route.meta.layout === 'auth'" />`
+      2. `<router-view v-else-if="route.matched.some(r => r.meta.requiresAdmin)" />`
+      3. `<div v-else class="flex h-screen overflow-hidden">` ... AppSidebar + main + router-view (no ref attribute) ... `</div>`
+
+    Note: the router-view in branch 3 must NOT carry `ref="routeViewRef"` — refs on router-view resolve to the RouterView proxy (same root cause as Gap 4). Remove the ref attribute.
+
+    CHANGE B — Keyboard instance resolution (Gap 4, also fixes tests 12 and 13):
+    The `routeViewRef` ref and its usage must be replaced with a direct instance lookup:
+    1. Add `useRouter` to the `vue-router` import: `import { useRoute, useRouter } from 'vue-router'`
+    2. Add `const router = useRouter()` after `const route = useRoute()`
+    3. Add helper: `function getFileManagerInstance() { return router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default ?? null }`
+    4. Remove `const routeViewRef = ref(null)` — no longer used
+    5. Remove `ref` from the `ref` import if it is now unused (check — ref was only used for routeViewRef)
+    6. Replace all `routeViewRef.value?.X?.()` calls in onKeydown with `getFileManagerInstance()?.X?.()`
+    7. Replace `routeViewRef.value?.handleOsDrop?.(files)` in onOsFilesDropped with `getFileManagerInstance()?.handleOsDrop?.(files)`
+
+    After both changes, `ref` from vue should be removed from the import line if nothing else uses it (check first — if ToastContainer or OsDragOverlay use a local ref, keep it; otherwise remove to avoid lint warnings).
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep "routeViewRef" src/App.vue; echo "exit:$?"; grep "instances.default" src/App.vue; grep "requiresAdmin" src/App.vue</automated>
+  </verify>
+  <done>
+    - `grep "routeViewRef" src/App.vue` returns no output (fully removed)
+    - `grep "instances.default" src/App.vue` returns the getFileManagerInstance() line
+    - `grep "requiresAdmin" src/App.vue` returns the v-else-if template branch
+    - `grep "useRouter" src/App.vue` appears in import and instantiation
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Escape modifier (SearchBar.vue) and capture-phase drop (OsDragOverlay.vue)</name>
+  <files>
+    frontend/src/components/documents/SearchBar.vue
+    frontend/src/components/layout/OsDragOverlay.vue
+  </files>
+  <action>
+    SearchBar.vue — one character change on line 11. Add `.prevent.stop` modifiers to `@keydown.escape`:
+    Before: `@keydown.escape="emit('update:modelValue', '')"`
+    After:  `@keydown.escape.prevent.stop="emit('update:modelValue', '')"`
+    `.prevent` stops the browser's native clear+blur behavior on type="search" inputs. `.stop` stops bubbling to App.vue's global keydown handler (which would call clearSearch() a second time). No other changes.
+
+    OsDragOverlay.vue — two lines change in the Options API lifecycle hooks:
+    In mounted(): change `window.addEventListener('drop', this.onDrop)` to `window.addEventListener('drop', this.onDrop, true)`
+    In beforeUnmount(): change `window.removeEventListener('drop', this.onDrop)` to `window.removeEventListener('drop', this.onDrop, true)`
+
+    The third argument `true` registers the listener in capture phase, meaning it runs before any bubble-phase handlers on child elements (including `@drop.prevent` on folder rows in StorageBrowser.vue). The removeEventListener MUST also pass `true` — EventTarget tracks bubble-phase and capture-phase registrations separately, so without `true` the cleanup call would fail silently and the listener would leak.
+
+    Do not change dragenter, dragleave, or dragover listeners — those remain in bubble phase and work correctly.
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep "keydown.escape" src/components/documents/SearchBar.vue && grep -n "addEventListener.*drop\|removeEventListener.*drop" src/components/layout/OsDragOverlay.vue</automated>
+  </verify>
+  <done>
+    - `grep "keydown.escape" src/components/documents/SearchBar.vue` shows `.prevent.stop` in the modifier chain
+    - `grep "addEventListener.*drop" src/components/layout/OsDragOverlay.vue` shows `true` as third argument
+    - `grep "removeEventListener.*drop" src/components/layout/OsDragOverlay.vue` shows `true` as third argument
+  </done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 4: Regression tests for all 6 gaps</name>
+  <files>
+    frontend/src/__tests__/keyboard.test.js
+    frontend/src/components/ui/__tests__/TreeItem.test.js
+    frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js
+  </files>
+  <behavior>
+    TreeItem shimmer:
+    - When loading=true and expanded=true → rendered HTML contains elements with class "animate-pulse"
+    - When loading=true and expanded=true → text "Loading" does not appear in rendered HTML
+
+    StorageBrowser showSearch:
+    - mode='local', breadcrumb=[] → showSearch is true (root-level local, previously false)
+    - mode='local', breadcrumb=[{name:'Folder'}] → showSearch is true (non-root local)
+    - mode='cloud', breadcrumb=[] → showSearch is true (cloud root, previously always false)
+    - mode='shared' → showSearch is false
+
+    App.vue keyboard dispatch:
+    - matched.find(r => r.instances?.default)?.instances?.default on a mounted FileManagerView router returns an object with focusSearch defined
+  </behavior>
+  <action>
+    keyboard.test.js — append a new describe block at the end of the existing file (do not modify or move existing describes):
+
+    "Gap 4: getFileManagerInstance resolves to actual component, not RouterView proxy" — using the existing mountFileManager() helper and makeRouter(), after mounting FileManagerView and flushing promises, access `router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default` and assert that it is not null and has a `focusSearch` property. This proves the resolution mechanism the refactored App.vue uses is correct. Import `useRouter` from vue-router at the top if not already imported — check existing imports first.
+
+    TreeItem.test.js — create at `frontend/src/components/ui/__tests__/TreeItem.test.js`:
+    - Import: `describe, it, expect, vi` from vitest; `mount, flushPromises` from @vue/test-utils; TreeItem from the component
+    - Mock AppIcon: `vi.mock('../AppIcon.vue', () => ({ default: { template: '<span/>' } }))`
+    - Helper: `mountExpanded(overrides = {})` — mounts TreeItem with `label="Test"`, `loadChildren: vi.fn().mockResolvedValue([])`, `expandable: true` and spreads overrides. After mount, call `w.vm.toggleExpand()` via `w.vm.$.setupState.toggleExpand()` (or trigger the expand button click) and flush promises to reach expanded state with children loaded.
+    - For the loading=true test: mount with a loadChildren that returns a promise that never resolves (`new Promise(() => {})`). Click the expand button to trigger load. Before flushing, assert the HTML. The loading ref will be true while the promise is pending.
+    - describe "Gap 1: sidebar shimmer rows": two tests as per behavior block above.
+    - describe "Gap 1 regression: non-loading branches unchanged": one test asserting that with loadChildren resolving to [] and expanded, the "Empty" text appears (sibling v-else-if branch guard).
+
+    StorageBrowser.showSearch.test.js — create at `frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js`:
+    - Heavy stub setup: all child components that StorageBrowser imports must be stubbed (SearchBar, SortControls, DocumentCard, FolderRow, EmptyState, AppIcon, BreadcrumbBar, DropZone, etc.) — use `stubs: { SearchBar: true, SortControls: true, ... }` in global mount options or individual vi.mock calls.
+    - Mock all API calls used on mount (listDocuments, listFolders, etc.) via vi.mock('../../../api/client.js', ...).
+    - After mount with given props, access `w.vm.showSearch` directly as a computed.
+    - Props for mount: at minimum `mode`, `breadcrumb`, `documents: []`, `folders: []`, `topicColorFn: () => '#000'`, `loading: false`.
+    - Four it() blocks as per behavior block above.
+    - Wrap in `describe("Gap 2: showSearch visible at root for local and cloud modes", ...)`.
+
+    All new tests run as part of `npm run test -- --run` without additional flags.
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && npm run test -- --reporter=verbose --run 2>&1 | grep -E "(PASS|FAIL|SKIP| ✓ | × | ✗ )" | tail -50</automated>
+  </verify>
+  <done>
+    - All new describe blocks appear in output with passing test indicators
+    - `npm run test -- --run` exits 0 with zero failures
+    - `grep -c "animate-pulse" src/components/ui/__tests__/TreeItem.test.js` returns at least 1
+    - `grep -c "showSearch" src/components/storage/__tests__/StorageBrowser.showSearch.test.js` returns at least 4
+  </done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| OS file drag → window drop (capture) | Files arrive via browser DataTransfer API — browser-enforced; no network boundary crossed; payload handled only client-side before going through existing authenticated upload flow |
+| Admin route layout selection | Template branch selection is display-only — backend enforces admin access via get_current_admin dep on every admin endpoint; changing template rendering creates no auth regression |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-10gc-01 | Tampering | OsDragOverlay capture-phase drop handler | accept | Handler reads only e.dataTransfer.files (browser-controlled), resets overlay state, emits to parent — no direct server interaction; upload goes through existing authenticated API path unchanged |
+| T-10gc-02 | Spoofing | router.currentRoute.value.matched.find().instances.default | accept | Read-only Vue internals lookup; no user-supplied data flows through this path; cannot be spoofed via URL manipulation — Vue populates instances after component mount, not from route params |
+| T-10gc-03 | Elevation of Privilege | App.vue v-else-if admin branch | accept | Branch adds a missing layout guard (removes AppSidebar for admin); it does not grant or deny route access — navigation guard in router/index.js is unchanged and continues to enforce requiresAdmin check |
+| T-10gc-SC | Tampering | npm/pip/cargo installs | accept | No new packages installed — all fixes are template/script edits to existing files |
+</threat_model>
+
+<verification>
+Manual UAT re-run checklist (all must pass before marking complete):
+
+Gap 1 — Sidebar shimmer: Expand a cloud provider tree item in the sidebar while data loads. Animated shimmer rows appear; "Loading…" text is absent.
+
+Gap 2 — Search at root: Navigate to / (file manager root, no folder entered). Search bar and sort controls are visible in the content area header.
+
+Gap 3 — Admin sidebar: Navigate to /admin/users in a logged-in admin session. Only the AdminLayout and AdminSidebar render — AppSidebar (user nav) is absent.
+
+Gap 4 — Keyboard shortcuts: With the file manager at root, press '/'. Search bar receives cursor focus. Press 'U'. File picker dialog opens. Press 'N'. New folder inline input appears.
+
+Gap 5 — Escape behavior: Type text into the search bar. Press Escape. Field clears. Cursor remains in the field. Type again immediately — new characters appear (no re-click required).
+
+Gap 6 — OS drag-drop: Drag a file from Finder/Explorer over the browser window. Overlay appears. Release the file. Upload begins (progress visible or toast appears).
+
+Automated gate:
+`cd frontend && npm run test -- --run` — exits 0, zero failures, no skipped tests regressed.
+</verification>
+
+<success_criteria>
+- All 6 UAT gaps confirmed closed by manual re-run of the 6 scenarios above
+- `npm run test -- --run` exits 0 with zero failures across the full suite (baseline: 211 passing)
+- Five production files modified with surgical changes only — no refactors, no feature additions
+- Three new test files committed with passing tests covering each gap
+- `grep -c "Loading" frontend/src/components/ui/TreeItem.vue` returns 0
+- `grep "showSearch" frontend/src/components/storage/StorageBrowser.vue` matches the `|| props.mode === 'cloud'` form
+- `grep "routeViewRef" frontend/src/App.vue` returns empty
+- `grep "requiresAdmin" frontend/src/App.vue` returns the v-else-if template branch line
+- `grep "addEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vue` returns a match
+- `grep "removeEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vue` returns a match
+- `grep "prevent.stop" frontend/src/components/documents/SearchBar.vue` returns the escape handler line
+</success_criteria>
+
+<output>
+Create `/Users/nik/Documents/Progamming/document_scanner/.planning/phases/10-ux-interaction/10-13-SUMMARY.md` when done.
+</output>
@@ -0,0 +1,42 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 1
+type: execute
+wave: 0
+depends_on: [10-complete]
+requirements: [PERF-02]
+files_modified:
+  - frontend/vite.config.js
+  - .planning/phases/11-visual-design-responsive-layout-cleanup/11-RESEARCH.md
+  - .planning/perf/phase11-baseline.html
+  - .planning/perf/phase11-baseline-summary.md
+autonomous: true
+---
+
+# Plan 11-01 — Bundle Baseline & UI Audit
+
+## Objective
+
+Capture the Phase 11 pre-optimization bundle baseline before any lazy-loading or visual cleanup begins, then record a targeted audit of the visual/responsive issues Phase 11 will address.
+
+## Tasks
+
+1. Wire existing `rollup-plugin-visualizer` into `frontend/vite.config.js` behind an opt-in environment flag such as `ANALYZE=true`. The dependency already exists in `frontend/package.json`.
+2. Run a production build with analysis enabled and write the baseline report to `.planning/perf/phase11-baseline.html`.
+3. Add `.planning/perf/phase11-baseline-summary.md` with bundle size, largest chunks, route/component observations, and the exact command used.
+4. Update `11-RESEARCH.md` if execution discovers facts that differ from the refresh research.
+5. Audit the frontend for Phase 11 targets:
+   - synchronous non-critical route imports
+   - responsive sidebar/admin sidebar gaps
+   - tables or grids that overflow below `sm`/`md`
+   - modal overflow below 640px
+   - inconsistent form, hover, focus, active, spacing, and typography patterns
+   - unreferenced files and imports
+
+## Acceptance Criteria
+
+- Baseline bundle report exists before any Phase 11 optimization commits.
+- `vite.config.js` does not generate analyzer output unless explicitly requested.
+- `11-RESEARCH.md` remains accurate after the baseline build.
+- Audit notes are concrete enough that plans 11-02 through 11-06 can execute without rediscovering scope.
+- `cd frontend && npm run build` succeeds with and without analysis enabled.
@@ -0,0 +1,43 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 2
+type: execute
+wave: 1
+depends_on: [11-01]
+requirements: [PERF-03]
+files_modified:
+  - frontend/src/router/index.js
+  - frontend/src/router/__tests__/router.guard.test.js
+autonomous: true
+---
+
+# Plan 11-02 — Lazy-Load Non-Critical Routes
+
+## Objective
+
+Satisfy PERF-03 by lazy-loading every route component that is not needed for the initial render, while preserving auth/admin guard behavior.
+
+## Tasks
+
+1. Keep `FileManagerView` synchronous for `/` as the critical first authenticated surface unless the baseline report shows a strong reason to split it. Document this in `router/index.js` near the import.
+2. Replace synchronous imports in `frontend/src/router/index.js` for non-initial routes:
+   - `TopicsView`
+   - `DocumentView`
+   - `SettingsView`
+   - `CloudStorageView`
+   - `CloudFolderView`
+3. Keep `/folders/:folderId` on the same `FileManagerView` component for behavior parity with `/`; it is already in the initial chunk because `/` uses the same component.
+4. Preserve existing lazy auth/admin/shared route imports.
+5. Extend router tests so guard behavior is verified with lazy route components:
+   - non-admin cannot enter `/admin/*`
+   - admin redirects away from non-admin routes
+   - refresh-before-guard still runs when access token is absent
+   - `/topics`, `/document/:id`, `/settings`, `/cloud`, and `/cloud/:provider/:folderId` still resolve
+6. Build once and confirm route chunks are emitted.
+
+## Acceptance Criteria
+
+- `rg "import .*View" frontend/src/router/index.js` only returns `FileManagerView` unless a new initial-render route is explicitly justified.
+- Admin child routes remain lazy-loaded.
+- Router guard tests pass.
+- `cd frontend && npm run build` succeeds and emits split route chunks.
@@ -0,0 +1,52 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 3
+type: execute
+wave: 2
+depends_on: [11-02]
+requirements: [RESP-01, RESP-02, RESP-03, RESP-05]
+files_modified:
+  - frontend/src/App.vue
+  - frontend/src/layouts/AdminLayout.vue
+  - frontend/src/components/layout/AppSidebar.vue
+  - frontend/src/components/admin/AdminSidebar.vue
+  - frontend/src/components/storage/StorageBrowser.vue
+  - frontend/src/__tests__/keyboard.test.js
+  - frontend/src/components/storage/__tests__/StorageBrowser.skeleton.test.js
+autonomous: true
+---
+
+# Plan 11-03 — Responsive Shells & Storage Rows
+
+## Objective
+
+Make both user and admin layouts usable below `lg`, and make storage rows fit smaller viewports without losing core actions.
+
+## Tasks
+
+1. Use layout-local drawer refs, not a new Pinia store:
+   - `App.vue` owns user drawer state.
+   - `AdminLayout.vue` owns admin drawer state.
+   - Watch route changes in each layout root and close the drawer after navigation.
+   - Do not put drawer state in `AppSidebar.vue` or `AdminSidebar.vue`.
+2. Add a mobile-only header with a hamburger button for the user layout.
+3. Hide `AppSidebar` below `lg`; open it in a slide-in overlay drawer with backdrop tap, route-change close, and `translate-x-0` / `-translate-x-full` transition.
+4. Apply the same responsive shell behavior to `AdminLayout` and `AdminSidebar`.
+5. Update `StorageBrowser` row/grid classes so:
+   - Size column hides below `md`
+   - Modified column hides below `sm`
+   - icon, name, and actions remain visible
+   - grid templates do not reserve hidden column widths on mobile
+6. Ensure inline icon action buttons have at least `36px` touch targets below `md`.
+7. Add or update tests for drawer open/close, route-change close, admin drawer behavior, responsive column classes, and touch target classes.
+8. Verify with browser screenshots or Playwright at 375px, 768px, 1024px, and desktop width.
+
+## Acceptance Criteria
+
+- User sidebar is hidden below 1024px and accessible through a hamburger drawer.
+- Admin sidebar has matching mobile behavior.
+- Drawer closes on backdrop tap and navigation tap.
+- Storage rows satisfy RESP-02 without horizontal overflow at 375px.
+- Icon actions satisfy RESP-03.
+- Drawer state is owned only by `App.vue` and `AdminLayout.vue`.
+- Frontend tests and build pass.
@@ -0,0 +1,40 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 4
+type: execute
+wave: 3
+depends_on: [11-03]
+requirements: [VISUAL-02, RESP-04]
+files_modified:
+  - frontend/tailwind.config.js
+  - frontend/src/components/**/*.vue
+  - frontend/src/views/**/*.vue
+autonomous: true
+---
+
+# Plan 11-04 — Forms Baseline & Mobile-Safe Modals
+
+## Objective
+
+Normalize form controls through `@tailwindcss/forms` and make every modal scroll safely on mobile viewports.
+
+## Tasks
+
+1. Confirm `@tailwindcss/forms` remains installed and active in `tailwind.config.js`; it is already wired today, so this should be a verification step unless execution finds drift.
+2. Audit inputs, selects, textareas, checkboxes, and radio buttons for conflicting per-component browser-reset styles.
+3. Normalize form classes to the smallest consistent Tailwind pattern already used by the app.
+4. Update modal shells so content below 640px is scrollable and never exceeds viewport height:
+   - `ShareModal.vue`: centered panel gets mobile `max-h` and `overflow-y-auto`.
+   - `CloudCredentialModal.vue`: tall WebDAV/Nextcloud form gets mobile `max-h` and `overflow-y-auto`.
+   - `FolderDeleteModal.vue`: adopt the same mobile-safe panel pattern.
+   - `DocumentPreviewModal.vue`: preserve full-screen preview but verify header/content sizing at narrow widths.
+   - any auth/account confirmation modal-like surfaces found in the audit
+5. Add focused tests or DOM assertions for mobile-safe modal classes and form baseline coverage.
+
+## Acceptance Criteria
+
+- Forms plugin is active and relied on consistently.
+- No modal content overflows a 375x667 viewport.
+- No modal text or action row is clipped below 640px.
+- The desktop modal appearance remains behaviorally unchanged.
+- `npm run test -- --run` and `npm run build` pass.
@@ -0,0 +1,46 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 5
+type: execute
+wave: 4
+depends_on: [11-04]
+requirements: [VISUAL-01, VISUAL-03, VISUAL-04]
+files_modified:
+  - frontend/src/components/**/*.vue
+  - frontend/src/views/**/*.vue
+autonomous: true
+---
+
+# Plan 11-05 — Visual Consistency Pass
+
+## Objective
+
+Make spacing, typography, hover, focus-visible, and active states consistent across the frontend without introducing a component-library rewrite.
+
+## Tasks
+
+1. Preserve legitimate data-driven inline styles:
+   - topic color swatches
+   - quota/progress widths
+   - Teleport dropdown coordinates
+   - tree indentation
+2. Remove arbitrary spacing and decorative inline styles unless they are data-driven layout values with no Tailwind equivalent.
+3. Normalize typography to this app scale:
+   - page title: `text-2xl font-semibold`
+   - section title: `text-lg font-semibold`
+   - panel/table heading: `text-sm font-semibold`
+   - body: `text-sm`
+   - caption/metadata: `text-xs`
+4. Replace generic `focus:ring-*` only patterns on interactive elements with this keyboard focus convention: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-1`.
+5. Ensure buttons, links, card rows, table rows, menu items, and icon actions have coherent hover and active states.
+6. Avoid broad palette changes; preserve the current DocuVault identity while removing one-off visual drift.
+7. Add focused tests or static checks for the agreed invariants where practical.
+
+## Acceptance Criteria
+
+- No unnecessary `px-[...]`, margin `style=`, or one-off typography overrides remain.
+- Interactive elements have hover plus keyboard-visible focus states.
+- Typography reads as one app scale, not per-component choices.
+- Data-driven inline styles remain where they carry runtime values.
+- Visual changes are behavior-preserving.
+- Frontend tests and build pass.
@@ -0,0 +1,45 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 6
+type: execute
+wave: 5
+depends_on: [11-05]
+requirements: [CODE-07, PERF-02]
+files_modified:
+  - frontend/src/**/*
+  - .planning/perf/phase11-final.html
+  - .planning/perf/phase11-final-summary.md
+  - .planning/phases/11-visual-design-responsive-layout-cleanup/11-VERIFICATION.md
+autonomous: true
+---
+
+# Plan 11-06 — Dead-Code Cleanup & Final Measurement
+
+## Objective
+
+Delete unreferenced frontend code and capture the final bundle report after all Phase 11 optimizations are complete.
+
+## Tasks
+
+1. Run dead-code searches for unreferenced components, stores, helpers, imports, and old route views.
+2. Explicitly classify these known suspects before deleting or retaining:
+   - `frontend/src/views/AccountView.vue` (`/account` currently redirects to `/settings`)
+   - `frontend/src/components/admin/__tests__/AdminAiConfigTab.test.js`
+   - `frontend/src/components/admin/__tests__/AdminQuotasTab.test.js`
+   - `frontend/src/components/admin/__tests__/AdminUsersTab.test.js`
+3. Confirm `HomeView.vue`, `FolderView.vue`, and `AdminView.vue` remain absent.
+4. Delete files with no active route and no active import in the same commit as their references are removed.
+5. Remove unused imports and stale tests that target deleted files; keep behavior tests that still protect live surfaces.
+6. Run the final analyzer build and write `.planning/perf/phase11-final.html`.
+7. Add `.planning/perf/phase11-final-summary.md` comparing baseline vs final bundle size, chunk count, and largest chunks.
+8. Produce `11-VERIFICATION.md` mapping every Phase 11 requirement to code/test/build evidence.
+
+## Acceptance Criteria
+
+- CODE-07 is satisfied: no dead files, unused route components, unused stores, or unused imports remain.
+- Known suspects are each documented as deleted or intentionally retained.
+- Final bundle report and summary are committed under `.planning/perf/`.
+- Baseline and final reports are both present.
+- `cd frontend && npm run test -- --run` passes.
+- `cd frontend && npm run build` passes.
+- Phase 11 verification maps VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, and PERF-03 to concrete evidence.
@@ -39,7 +39,7 @@ This phase is **purely frontend** — no backend changes, no new features.
 ### Performance (PERF-02, PERF-03)

 - **D-09:** Bundle baseline captured in Plan 11-01 (before any changes). Final measurement in Plan 11-06 (after all changes). Both reports committed to `.planning/perf/`.
- **D-10:** Login/Register route (`/login`, `/register`) may stay synchronous if needed for first-paint — document the rationale in the router. All other authenticated routes (Topics, Document detail, Settings, Cloud, admin subtree) must be lazy.
+- **D-10:** `FileManagerView` may stay synchronous for `/` as the critical first authenticated surface — document the rationale in the router. Auth routes and admin routes are already lazy-loaded. All other authenticated routes (Topics, Document detail, Settings, Cloud) must be lazy.

 ### Claude's Discretion

@@ -75,7 +75,7 @@ This phase is **purely frontend** — no backend changes, no new features.
 - `frontend/src/components/admin/AdminSidebar.vue` — admin sidebar; same responsive behavior
 - `frontend/src/components/storage/StorageBrowser.vue` — responsive column hiding: Size below `md`, Modified below `sm`; touch targets (RESP-03)
 - `frontend/src/router/index.js` — add `() => import(...)` lazy loading for non-initial routes (PERF-03)
- `frontend/tailwind.config.js` — add `@tailwindcss/forms` plugin (VISUAL-02)
+- `frontend/tailwind.config.js` — verify `@tailwindcss/forms` plugin remains active (VISUAL-02)
 - `frontend/vite.config.js` — add `rollup-plugin-visualizer` behind `ANALYZE=true` env flag (PERF-02)

 ### Phase 10 Patterns (carry forward)
@@ -102,7 +102,7 @@ This phase is **purely frontend** — no backend changes, no new features.
 - `App.vue` — user layout root; hamburger button + sidebar drawer mount here. Phase 10 already added `<Teleport>`-based toast container and drag overlay here.
 - `AdminLayout.vue` — admin layout root; separate hamburger button needed for admin nav drawer (RESP-05); same structural pattern as `App.vue`
 - `frontend/src/router/index.js` — lazy-load additions happen here; preserve all existing `meta: { requiresAuth, requiresAdmin }` guards
- `frontend/tailwind.config.js` — add `@tailwindcss/forms` plugin; do not break existing utility classes
+- `frontend/tailwind.config.js` — `@tailwindcss/forms` is already active; do not break existing utility classes

 ### PERF-02 Bundle Workflow
 - Plan 11-01 adds `rollup-plugin-visualizer` behind `ANALYZE=true` and captures baseline in `.planning/perf/phase11-baseline.html`
@@ -118,7 +118,7 @@ This phase is **purely frontend** — no backend changes, no new features.
 - Backdrop for drawer: semi-transparent overlay, tap to close. Use `<Teleport to="body">` consistent with existing overlay pattern.
 - Touch target minimum: `min-w-[36px] min-h-[36px]` or equivalent padding on icon action buttons below `md`.
 - Modal scroll: `max-h-[90vh] overflow-y-auto` pattern on modal content container for viewports below 640px.
- `@tailwindcss/forms` strategy: install plugin, audit all form elements for conflicting per-component reset styles, normalize to smallest consistent Tailwind class set already used in the app.
+- `@tailwindcss/forms` strategy: verify plugin remains active, audit all form elements for conflicting per-component reset styles, normalize to smallest consistent Tailwind class set already used in the app.

 </specifics>

@@ -0,0 +1,94 @@
+# Phase 11 Research Refresh — Visual Design, Responsive Layout & Cleanup
+
+**Researched:** 2026-06-16
+**Inputs:** Phase 11 context, roadmap, requirements, pitfall notes, live frontend code.
+
+## Executive Summary
+
+The six-plan Phase 11 sequence is structurally sound: measure first, lazy-load routes, fix responsive shells, normalize forms/modals, do the visual consistency pass, then delete dead code and measure again. The second review found several places where the plans needed sharper implementation constraints, especially because `11-CONTEXT.md` contains locked decisions that were not fully reflected in the first review.
+
+## Current Code Findings
+
+### Performance
+
+- `frontend/package.json` already includes `rollup-plugin-visualizer@^7.0.1`.
+- `frontend/vite.config.js` currently has only `vue()` in `plugins`; analyzer wiring still needs to be added behind an opt-in flag.
+- `frontend/src/router/index.js` still synchronously imports:
+  - `FileManagerView`
+  - `TopicsView`
+  - `DocumentView`
+  - `SettingsView`
+  - `CloudFolderView`
+  - `CloudStorageView`
+- Auth routes, admin layout, admin child views, and `SharedView` are already lazy-loaded.
+- Recommendation: keep `FileManagerView` synchronous only for `/` as the critical first authenticated surface. Lazy-load `TopicsView`, `DocumentView`, `SettingsView`, `CloudStorageView`, and `CloudFolderView`. Reuse the synchronous `FileManagerView` for `/folders/:folderId` unless the bundle baseline proves it should be split later.
+
+### Responsive Shells
+
+- `App.vue` renders a desktop-only `flex h-screen overflow-hidden` shell with permanent `AppSidebar`.
+- `AdminLayout.vue` mirrors that desktop-only shell with permanent `AdminSidebar`.
+- `AppSidebar.vue` and `AdminSidebar.vue` are presentational enough to stay drawer-agnostic.
+- Recommendation: use layout-local refs in `App.vue` and `AdminLayout.vue`, not a new Pinia store. Nav link close behavior can be handled by watching route changes in each layout root; no child component needs global drawer state.
+
+### Storage Rows
+
+- `StorageBrowser.vue` already hides Size below `md` and Modified below `sm` via `hidden md:block` and `hidden sm:block`.
+- The grid template remains fixed at `grid-cols-[2rem_1fr_6rem_8rem_6rem]`, so responsive column sizing still needs explicit adjustment to avoid empty tracks and mobile overflow.
+- Existing row action buttons use `p-1.5`, which may not guarantee 36x36 touch targets below `md`.
+
+### Forms
+
+- `@tailwindcss/forms` is already installed and active in `frontend/tailwind.config.js`.
+- Many controls still carry repeated full border/focus class stacks. Plan 11-04 should normalize those without introducing a new component library.
+
+### Modals
+
+Mobile overflow risk is concrete:
+
+- `ShareModal.vue`: fixed overlay, centered panel, `rounded-2xl`, no `max-h` or `overflow-y-auto`.
+- `CloudCredentialModal.vue`: fixed overlay, centered panel, `max-w-md p-6`, no `max-h` or `overflow-y-auto`; form can become tall with advanced Nextcloud fields.
+- `FolderDeleteModal.vue`: smaller but should still receive the shared mobile-safe panel pattern.
+- `DocumentPreviewModal.vue`: full-screen preview is structurally different; it should preserve full-screen behavior and ensure header/content do not overflow on narrow screens.
+
+Recommended modal shell pattern: overlay uses `p-4 sm:p-6`; panel uses `max-h-[calc(100vh-2rem)] overflow-y-auto` below `sm`, with desktop styling preserved.
+
+### Visual Consistency
+
+- Current frontend heavily uses `focus:ring-2` but rarely `focus-visible:`.
+- `rounded-xl` and `rounded-2xl` appear on several ordinary panels/modals even though AGENTS.md prefers cards at 8px radius unless the design system requires otherwise.
+- There are data-driven inline styles that should remain:
+  - topic color swatches
+  - quota/progress bar widths
+  - Teleport dropdown coordinates
+  - tree indentation
+- There are skeleton width styles such as `:style="{ width: (50 + n * 15) + 'px' }"` that are decorative and can be converted to static Tailwind widths during the visual pass.
+
+Recommended convention:
+
+- Page title: `text-2xl font-semibold`
+- Section title: `text-lg font-semibold`
+- Panel/table heading: `text-sm font-semibold`
+- Body: `text-sm`
+- Caption/metadata: `text-xs`
+- Focus ring: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-1`
+
+### Dead Code Signals
+
+- `HomeView.vue` and `FolderView.vue` remain absent, satisfying AGENTS.md.
+- Legacy admin-tab test names still exist under `frontend/src/components/admin/__tests__/`:
+  - `AdminAiConfigTab.test.js`
+  - `AdminQuotasTab.test.js`
+  - `AdminUsersTab.test.js`
+- These tests may still cover current components via renamed imports or may be stale; Plan 11-06 should explicitly classify them.
+- `AccountView.vue` exists but `/account` redirects to `/settings`. It may be dead unless imported outside the router. Plan 11-06 should confirm before deleting.
+
+## Review Verdict
+
+The plan set remains valid after review, but it should be refined with:
+
+- a documented layout-local drawer-state decision
+- exact route lazy-loading scope
+- exact modal overflow targets
+- a locked focus-ring and typography convention
+- explicit dead-code suspects for Plan 11-06
+
--- a/Show More
+++ b/Show More