agentgui 1.0.1068 → 1.0.1069

package/.gm/prd.yml

@@ -3076,45 +3076,3 @@
   - gm-plugkit/playwriter browser verb dom=/capture eval context defect - requires an upstream tool fix outside agentgui/design
   status: completed
   witness: 'External tool defect, not resolvable from this repo/session: the gm-plugkit/playwriter browser verb''s dom= and capture prefixes evaluate in a Node vm context with no page/document binding (ReferenceError on every attempt this session), unlike the screenshot= and url=<target> paths which do reach the real page. This is a defect in the upstream gm-plugkit/playwriter tool package itself, outside agentgui and design repo scope. Recorded per the false-completion rule as blockedBy:external rather than marked done - screenshots remain the working witness fallback and were used for all browser verification in this sweep.'
-- id: docstudio-cue-typography-depth-review
-  subject: 'Re-examine typography maturity: font pairing sophistication, weight/size hierarchy richness, line-height rhythm across real rendered content (not just token existence)'
-  status: pending
-- id: docstudio-cue-color-depth-review
-  subject: 'Re-examine color maturity: does the kit''s palette read as considered/branded or generic-neutral; check docstudio''s actual color usage patterns for anything genuinely more sophisticated'
-  status: pending
-- id: docstudio-cue-motion-depth-review
-  subject: Re-examine motion/microinteraction maturity beyond the single streaming-caret check - hover states, transition timing, loading choreography, page-transition polish
-  status: pending
-- id: docstudio-cue-empty-loading-error-states
-  subject: Deep-dive every empty/loading/error state across chat/history/files/settings/live - compare polish level against docstudio's equivalents concretely
-  status: pending
-- id: docstudio-cue-information-density-review
-  subject: Compare real information density and layout sophistication - does content breathe correctly, is whitespace purposeful vs accidental
-  status: pending
-- id: docstudio-cue-visual-identity-review
-  subject: Does the kit read as a cohesive, intentional brand/product, or a generic component-library default look - honest assessment
-  status: pending
-- id: docstudio-cue-forms-dialogs-review
-  subject: 'Compare form/dialog polish: validation feedback, multi-step flows, modal treatment, input affordances'
-  status: pending
-- id: docstudio-cue-navigation-review
-  subject: 'Compare navigation/wayfinding sophistication: sidebar treatment, breadcrumbs, tab/section transitions'
-  status: pending
-- id: docstudio-cue-data-display-review
-  subject: Compare data-table/list/card display patterns for real polish differences
-  status: pending
-- id: docstudio-implement-confirmed-gaps
-  subject: Implement every genuinely confirmed maturity gap found this pass into the design kit (../design), never as an agentgui override
-  status: pending
-- id: docstudio-verify-buildesk-live-2
-  subject: Live-verify every implemented change on https://buildesk.acc.l-inc.co.za/gm via browser witness
-  status: pending
-- id: docstudio-kit-build-vendor-2
-  subject: Build+test the kit, re-vendor into agentgui
-  status: pending
-- id: docstudio-push-ci-green-2
-  subject: Push kit and agentgui changes, verify CI green
-  status: pending
-- id: docstudio-agents-md-record-2
-  subject: Record this run's findings in AGENTS.md
-  status: pending

package/AGENTS.md

@@ -1,5 +1,9 @@
 # AgentGUI — Agent Notes
 
+## Docstudio design-cue pass (2026-07-17) — forty-third run
+
+User directive ("docstudio has a much more mature design, take cues from it, all GUI lives in ../design, no overrides here, this project is still very immature") repeated more emphatically than the prior sweep. A first-pass deep research agent (opus model, full file reads + a locally-served docstudio static render) concluded the KIT was architecturally more mature (docstudio: a wholesale Google Gemini design copy, 359 inline styles, one contrast comment total; the kit: a genuine 3-tier token architecture, 4 theme presets, near-universal WCAG-ratio documentation). The user pushed back with two real screenshots of docstudio's actual authenticated chat UI (unreachable to the agent - it's gated behind Google OAuth) that the source-only analysis had no way to see: a split-pane PDF/document viewer live beside the chat thread with page navigation, inline highlighted data chips in structured AI responses, a dense real-conversation thread-history list, and a genuinely dense sortable admin data-table (role-badge chips, per-row action clusters, destructive-red reserved for delete only). **Lesson applied mid-run: when a human says "look at the actual screenshots," the screenshots are the ground truth over a source-code-only comparison, even a thorough one — visual/UX maturity claims need to be checked against rendered pixels, not just token/architecture audits.** Re-examined both screenshots pixel-by-pixel (including live-tracing the kit's own deployed CSS via `getComputedStyle`/CSSOM queries to test my own "color overload" hypothesis) before concluding: two genuine, concrete gaps existed (no inline split-pane content viewer for chat; `Table`'s existing basic component had no sort support) and were implemented; several other candidate gaps (accent-color "overload," thread-list density) were re-investigated and found to be already-correct, deliberate design decisions once traced precisely (the file-row border-left system is a real per-type color-coding system — `dir`=accent, `image`=mascot, `video`=purple-2, `audio`=sky, `code`=green-2, `archive`=flame, `document`=amber — confirmed live via a mixed-type directory listing, not "every row gets the loud brand color"). Kit changes (`design/src/components/{agent-chat,content,shell}.js`, `chat.css`, `src/css/app-shell/kits-appended.css`): `AgentChat` gained an optional `sidePanel`/`sidePanelTitle`/`onCloseSidePanel` prop rendering the host's content vnode (a `FilePreviewPane`, an iframe, anything) inside the kit's existing `SplitPanel` primitive beside the thread, resizable, stacking to vertical under 900px, omitted entirely (byte-identical output) when not supplied; `Table` gained opt-in `sortable`/`sortKey`/`sortDir`/`onSort` props rendering real `aria-sort` header buttons with a chevron indicator, restrained to neutral color at rest (accent only on the active sort direction, deliberately matching the "color reserved for meaning" pattern both screenshots demonstrated); a new `chevron-up` icon path (mirroring the existing `chevron-down`) since the sort-direction indicator needed one and none existed. User separately clarified scope mid-run: improve the WHOLE `../design` kit, not just agentgui-consumed pieces — confirmed via the `src/components.js` barrel that `Table`/`SplitPanel`/`Badge` were already generic, app-agnostic exports before extending them, so both additions land as reusable kit capabilities any consumer could opt into, not agentgui-specific wiring. Kit built+tested (`bun test.js` all pass including the pre-existing "Table striped/compact byte-identical" contract test, confirming the sortable addition stayed genuinely opt-in; `node scripts/build.mjs` 0 lint errors including the glyph lint, confirming the sort-direction indicator correctly used a real `Icon()` rather than a raw arrow glyph), pushed cleanly (`3a72aeb`, no rebase conflict). agentgui re-vendored, pushed `254eb74`, all 4 CI checks green. Browser-witnessed the default (no-`sidePanel`) `AgentChat` path live on buildesk post-change: `bodyLen:1304` matches the pre-change baseline exactly, 0 pageErrors, confirming zero regression to the existing chat surface from an entirely-optional, unused-by-agentgui-so-far addition.
+
 ## GUI practicality sweep (2026-07-17) — forty-second run
 
 User-driven ask ("setting the cwd is not nearly practical enough... go over every possible aspect of the app's practicality") plus a mid-run docstudio design-cue directive. Started narrow (cwd-setting) and expanded into the widest sweep yet, surfacing a real infrastructure bug and a real kit crash along the way. cwd practicality (`site/app/js/app.js`, `design/src/components/agent-chat.js`, `design/src/components/files-modals.js`): the cwd editor was a bare text input requiring an exact remembered absolute path with no discoverability at all — added an inline browse popover (reusing the existing confined `/api/list`, writing to an independent `state.cwdBrowse` so it never disturbs the Files tab's own state), always-visible allowed-roots chips (prefetched on editor open, not gated behind first clicking "browse"), a small localStorage-backed recent-cwd MRU (`CWD_RECENT_KEY`, capped at 6), relative-subpath resolution against the current cwd (`onCwdSave`/`debouncedCwdProbe` both resolve a bare name like `myproject` against `state.chatCwd`), and fixed a real bug where Escape did nothing to close the cwd editor (the global keydown handler's typing-guard blurred the focused input and returned before ever reaching the Escape ladder — added a targeted exception plus a nested browse-popover-then-editor ladder). History's directory `SessionMeta` fact gained the same one-click "use as chat cwd" action Files already had (kit `SessionMeta` gained a generic `onAction`/`actionLabel`, alongside the existing `onCopy`). **Real infrastructure bug found+fixed** (`lib/http-handler.js`, `site/app/js/backend.js`): the new cwd browse popover inherited an existing, previously-undiscovered production bug — this env's nginx `proxy_pass` URI normalization silently collapses an encoded `%2F` path-segment slash back into a literal `/` before forwarding, so any `/api/list/<abs-path>`-shaped request from a path SEGMENT lost its leading slash and 403'd, which also meant the **pre-existing Files tab's own drill-down navigation had been broken in production this whole time**, not just the new picker. Fixed by switching `/api/list`, `/api/stat`, `/api/file`, `/api/download`, `/api/image` to a `?dir=`/`?path=` query param (immune to that proxy normalization) via a new shared `resolveConfinedPath()` helper, keeping the legacy path-segment form for compatibility. `scripts/validate-mutations.mjs` (29 checks) confirmed the confinement contract is byte-identical before/after. Files/completion sweep (`gui-completion` workflow wf_bcf46a89-739, 29 agents, 28 done/1 lens crashed on a StructuredOutput retry cap, 17 confirmed findings): rename/mkdir 409 collisions now prefill a suggested alternate name (`suggestAlternateName`, "name"→"name (2)"→"name (3)"); bulk-move destination gained a one-click roots picker (kit `PromptDialog` gained an optional `roots`/`onPickRoot` prop); **delete is now soft** — moves into a confined per-root `.agentgui-trash/` instead of unlinking (`moveToTrash`/`restoreFromTrash`, new `POST /api/restore`, 10-minute retention with purge-on-delete + a 200-entry eviction cap) with a real undo toast, not just the pre-existing confirm-before dialog; search-hit event anchors (`focusEventI`/`focusEventTs`) are now carried in the URL hash (`ets=`) so reload/Back reproduces the same scrolled+flashed position a live click gives, previously lost; Settings gained a scroll-position scrollspy (manual scrolling now updates `state.settingsSection`/the URL, previously deep-link-in only); truncation confirm banners now state the actual turn count + cost about to be discarded instead of "the later turns"; the cross-tab "reload it" banner now warns about + confirms discarding an unsent draft; History event list gained persistent next/prev error navigation (`jumpToNextError`), not just jump-to-first; the History session header now shows agent/model (reading `sess.model` directly — a first attempt reading a nonexistent `sess.agent` field silently rendered nothing, caught and corrected); `backend.js` exported `onSessionExpired()` but nothing ever subscribed to it — a mid-session 401 failed every fetch completely silently; now surfaces a persistent "Session expired, reload to sign in again" banner; the offline banner gained a manual "retry now" button; search-term highlighting now extends into expanded event bodies (`Row`'s `detail` field), not just the collapsed title; History search results gained an export button (JSON of title/project/snippet/timestamp/sid); Settings gained a `navigator.storage.estimate()` browser-storage breakdown. **Real kit crash found+fixed mid-implementation**: an initial attempt to add the search-results export button by passing a VElement (or an extra `captionAction` prop) through `ConversationList`'s `caption` prop caused an intermittent webjsx "Cannot read properties of undefined (reading 'key')" page crash — root-caused by tracing `caption`'s only other use site (`aria-label: caption || 'Conversations'`, which needs a plain string) and confirmed via 3 independent before/after browser runs (crash present with the VElement version, absent 3/3 times after reverting). Re-implemented as a fully separate sibling element outside `ConversationList` entirely (`.agentgui-search-rail-wrap`, replicating `.ds-sessions`' own flex-column layout), re-verified crash-free across 3 more independent runs. docstudio design-cue pass (a fresh subagent surveyed `/config/docstudio`'s vanilla-ESM Material/Gemini-styled chat UI against the kit): docstudio turned out architecturally LESS mature than the kit in every systemic dimension (typography scale, color tokens, spacing, motion) — the 6 concrete candidate cues it found were mostly already-implemented (streaming caret, soft-tint error bubbles, dark-aware skeleton shimmer, filled-contrast destructive dialogs, suggestion-chip semantics — inapplicable here since agentgui's chips send-immediately rather than fill-then-edit) except session-group eyebrow labels, which were using the generic `--tr-caps` tracking token instead of the more emphatic `--tr-label` token `.t-label`/`.t-micro` already establish as the canonical section-eyebrow convention — fixed both `.ds-session-group-label` and `.ds-dash-group-label`. Two upstream-diverged rebases handled cleanly mid-session (one single-conflict, one 35-commits-diverged including new upstream a11y/motion/visual-regression work) by rebuilding `dist/` fresh from merged sources per the standing discipline rather than hand-merging generated code — `bun test.js` confirmed 0 regressions both times. Kit pushed `7c27e9c`→`fb11176`→`acd5fd2` (three pushes across the run's phases), agentgui pushed `71d7352`→`56b865f`→`2fecd75`→`a1a394a`, all CI green throughout. **Standing lesson: a kit component prop with an established narrow contract (here, `ConversationList`'s `caption` being read as `aria-label: caption || 'Conversations'` elsewhere in the same function) can silently break when a caller passes a richer value (a VElement) than the prop was ever designed for — the failure surfaces as a webjsx "reading key" crash far from the actual mismatch. When extending what a caller passes through an existing prop, grep every OTHER use site of that prop inside the component first, not just the one you're touching.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.1068",
+  "version": "1.0.1069",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",