lfg2025/archy
1
0
Fork 0
Code Issues 27 Pull Requests 5 Actions Packages Projects Releases 4 Wiki Activity
Files
520b93d58e776d2fa0737a7f964e63204037f771
archy/.planning/phases/02-ui-performance/02-07-SUMMARY.md
T

410 lines
35 KiB
Markdown
Raw Blame History

---
phase: 02-ui-performance
plan: 07
subsystem: ui
tags: [vue, aiui, iframe, embed-url, keepalive, postmessage, d14]
# Dependency graph
requires:
- phase: 02-ui-performance/02-04
provides: "Chat.vue's window-message listener and ContextBroker following onActivated/onDeactivated; KEEP_ALIVE_PATHS including /dashboard/chat; the AIUI dev-mode blank-screen finding carried forward as this plan's own scope"
provides:
- "Stable, unconditional AIUI embed URL construction in Chat.vue (aiuiUrl computed) — no reactive/runtime-varying input, so the iframe src is byte-identical across re-renders, viewport resizes, and KeepAlive deactivate/reactivate cycles"
- "Two new presentation-only query params on the embed URL: chatExpanded (D-14a) and mobileChat (D-14b), both read by AIUI, both no-ops if the deployed AIUI build predates them"
- "02-AIUI-D14.md: the recorded AIUI source location, its full embed-parameter contract read from source, and which side implements each D-14 default"
- "AIUI-side commit 900c0b9 on the AIUI repository's development branch (now upstream, see Decisions) implementing both D-14 defaults"
affects: [02-08]
# Tech tracking
tech-stack:
added: []
patterns:
- "Presentation flags into an embedded iframe's URL must be static strings with zero reactive dependency — Vue's computed has no way to know a plain closure read (env var, build-time constant) is 'stable' except that nothing reactive was touched, so the discipline is structural: don't reference a ref/reactive/computed inside the URL-building computed"
- "A default-state bug reported as 'the embedded app opens wrong' can be a fresh-load default (D-14a: localStorage-backed default with no override) or a stale-carryover default (D-14b: a correct initial ref value clobbered by module-singleton state surviving an internal remount) — the fix differs (new persisted-default override vs. a one-time onMounted re-assertion) even though both present identically to the user as 'opens on the wrong view'"
- "When an external repo's own doc says one branch name (CLAUDE.md: 'dev') but the actual remote branch has a different name ('development') with zero commits unique to the documented default branch ('main'), verify via git log A..B / B..A both directions before picking a base, rather than trusting either the doc or the default branch alone"
key-files:
created:
- .planning/phases/02-ui-performance/02-AIUI-D14.md
- neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts
modified:
- neode-ui/src/views/Chat.vue
external:
- path: packages/app/src/stores/chat.ts
repo: AIUI (git.tx1138.com/lfg2025/AIUI)
commit: 900c0b9
branch: feat/d14-embed-defaults (merged/pushed onto development, now upstream)
- path: packages/app/src/pages/ChatPage.vue
repo: AIUI (git.tx1138.com/lfg2025/AIUI)
commit: 900c0b9
branch: feat/d14-embed-defaults (merged/pushed onto development, now upstream)
key-decisions:
- "AIUI source located mid-plan (previously unreachable — see Deviations): cloned to /home/archipelago/Projects/AIUI from git.tx1138.com/lfg2025/AIUI, base branch chosen was `development` not `main` — verified via git log main..development (17 commits ahead) vs development..main (0 commits unique to main); main was simply stale."
- "D-14a root cause: chat.ts's chatCollapsed ref defaulted to collapsed (true) on any fresh localStorage — exactly 'requires the user to expand it'. Fixed with a new ?chatExpanded query param read once at store init as an override, deliberately never written back to localStorage so the standalone (non-embedded) app's own persisted default is untouched."
- "D-14b root cause: ChatPage.vue's mobileTab ref already defaulted correctly to 'chat' — the reported bug is module-singleton content-panel selection state (useContentPanel.ts's top-level refs) surviving an internal AIUI remount and immediately flipping mobileTab to 'context' via ChatPage's own hasDetailOpen watcher. Fixed with a new ?mobileChat query param that re-asserts mobileTab='chat' once, on mount, without touching the watchers that drive normal tab-switching in response to real user taps."
- "Chose new dedicated query params (chatExpanded, mobileChat) over overloading the existing embedded flag — embedded already carries multiple unrelated meanings (transparent background, mock-Archy gating, passphrase-prompt skip) and every embedded session already sends it, so tying D-14's defaults to it directly would remove any future ability to decouple the two concerns; a dedicated flag is self-documenting and matches the plan's own acceptance criteria (flag names must be grep-able in the built bundle)."
- "D-14b lets AIUI decide against its OWN viewport width (its own isMobile computed) rather than neode-ui passing a resolved boolean — the option the plan's Task 2 action explicitly named as satisfying the URL-stability constraint, since AIUI's iframe owns its own mobile/desktop layout breakpoint."
- "Pre-existing, unrelated-to-D-14 findings surfaced during source inspection, deliberately NOT fixed (out of file scope): AIUI's mockArchy handling is mutually exclusive with embedded (useArchy.ts's `useMock && !embedded` gate), so Chat.vue's demo-mode `&mockArchy=1` currently does nothing while embedded=true is also sent; and AIUI never reads the `&seed=1` param Chat.vue sends in demo mode at all. Neither touches this plan's files_modified."
- "AIUI-side commit (900c0b9) was pushed upstream by the orchestrator using a user-supplied write token partway through this plan's close-out — it now lives on the AIUI repo's development branch (fast-forwarded 9176324..900c0b9) and a mirrored feat/d14-embed-defaults branch, both confirmed via git fetch. The remaining handoff to 02-08 is purely operational: rebuild AIUI's production bundle from development and redeploy the dev pair's aiui container — no merge/push step remains blocked."
requirements-completed: [PERF-02]
coverage:
- id: D1
description: "Switching away from the Chat tab and back leaves the AIUI panel loaded — the iframe is not re-created and does not reload"
requirement: PERF-02
verification:
- kind: unit
ref: "neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts#is string-equal before and after a deactivate/reactivate cycle"
status: pass
- kind: manual_procedural
ref: "Task 3 checkpoint:human-verify, approved on the restored :8100 dev-mock session (AIUI dev server on :5173 built from feat/d14-embed-defaults)"
status: pass
human_judgment: true
rationale: "Visual/perceptual confirmation that the panel truly did not reload (no flash, no lost typed text, no scroll reset) is a judgment call a unit test on the URL alone cannot fully prove, consistent with 02-02/02-04's precedent for this class of checkpoint."
- id: D2
description: "The iframe src is stable for the lifetime of the Chat view instance: no runtime-varying value (viewport width, connection state, timestamp) is part of the URL"
requirement: PERF-02
verification:
- kind: unit
ref: "neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts#is string-equal before and after a simulated viewport resize across the mobile breakpoint"
status: pass
human_judgment: false
- id: D3
description: "D-14a: the AIUI chat opens in its expanded state rather than requiring the user to expand it"
requirement: PERF-02
verification:
- kind: unit
ref: "neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts#carries embedded=true, hideClose=true, and both D-14 flags (confirms neode-ui sends chatExpanded=true)"
status: pass
- kind: manual_procedural
ref: "Task 3 checkpoint:human-verify — user observed the expanded default on the :5173 AIUI dev server built from feat/d14-embed-defaults before approving"
status: pass
human_judgment: true
rationale: "The flag's effect lives entirely in AIUI's own source (a separate repository) — only a human observing the actual rendered AIUI panel can confirm the receiving half behaves as intended; a neode-ui-side unit test can only prove the flag is sent, not that it's honored."
- id: D4
description: "D-14b: on a mobile viewport, AIUI opens on its chat view rather than its context view"
requirement: PERF-02
verification:
- kind: unit
ref: "neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts#carries embedded=true, hideClose=true, and both D-14 flags (confirms neode-ui sends mobileChat=true)"
status: pass
- kind: manual_procedural
ref: "Task 3 checkpoint:human-verify — user observed the mobile-chat-first default on the :5173 AIUI dev server before approving"
status: pass
human_judgment: true
rationale: "Same as D3 — the behavior is implemented and owned by AIUI's own source; only human observation of the actual mobile layout confirms it."
- id: D5
description: "The mechanism carrying both D-14 defaults across the neode-ui/AIUI boundary is recorded in writing, including which side implements which half"
requirement: PERF-02
verification:
- kind: other
ref: ".planning/phases/02-ui-performance/02-AIUI-D14.md (all five required headings present, contract read from source)"
status: pass
human_judgment: false
- id: D6
description: "The existing postMessage origin validation still rejects messages from any origin other than the AIUI URL's own"
requirement: PERF-02
verification:
- kind: unit
ref: "neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts#does not set aiuiConnected for a message from a foreign origin"
status: pass
human_judgment: false
- id: D7
description: "The connected state established by AIUI's ready message is not reset when the Chat tab is deactivated"
requirement: PERF-02
verification:
- kind: unit
ref: "neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts#aiuiConnected survives a deactivate/reactivate cycle once set by a same-origin ready message"
status: pass
human_judgment: false
- id: D8
description: "Neither D-14 default regresses AIUI's desktop layout or its non-embedded standalone mode"
requirement: PERF-02
verification: []
human_judgment: true
rationale: "Backstop truth per the plan's own must_haves — both AIUI-side changes are gated behind new query params that are absent (and therefore no-ops) in every non-embedded/standalone load, and chatCollapsed's override is never written back to localStorage; full confirmation that desktop/standalone AIUI is visually unaffected requires a human looking at the standalone app, which was out of this plan's checkpoint scope (desktop/mobile embedded verification only) and is deferred to whoever next touches AIUI's standalone UX."
duration: ~75min
completed: 2026-07-30
status: complete
---
# Phase 02 Plan 07: Chat/AIUI Embed Stability + D-14 UX Defaults Summary
**AIUI's embed URL construction in `Chat.vue` made fully static (no reactive input) so the panel survives tab switches without reloading, plus both D-14 UX defaults (expanded chat, mobile-chat-first) implemented in AIUI's own source via two new presentation-only query params — the AIUI-side commit now lives upstream on `development`**
## Performance
- **Duration:** ~75 min (Task 1 investigation + doc, a mid-plan pause when AIUI's source was initially unreachable, a resumed Task 1 amendment once the source location was supplied, Task 2 implementation across both repositories, and a Task 3 checkpoint round-trip)
- **Started:** 2026-07-30T21:55Z (approx, first Task 1 investigation)
- **Completed:** 2026-07-30T22:40Z
- **Tasks:** 3 (Task 1 auto, Task 2 auto/tdd, Task 3 checkpoint:human-verify)
- **Files modified:** 3 in `archy` (1 new doc, 1 new test, 1 modified view) + 2 in the AIUI checkout
## Accomplishments
- **`02-AIUI-D14.md`** records AIUI's real source location (`git.tx1138.com/lfg2025/AIUI`, `development` branch), its full embed-parameter contract read directly from source (`embedded`, `mockArchy`, and the two pre-existing-but-unhonored `hideClose`/`seed` params), and the exact root cause + fix for each D-14 default.
- **`Chat.vue`'s `aiuiUrl` computed** now appends `chatExpanded=true&mobileChat=true` as static strings alongside the pre-existing `embedded=true&hideClose=true` — zero reactive dependency, so the computed's value never changes after first evaluation. This is the load-bearing property that keeps the iframe `src` byte-identical across re-renders, viewport resizes, and KeepAlive deactivate/reactivate cycles.
- **D-14a fix (AIUI, `stores/chat.ts`):** `chatCollapsed`'s initial ref now checks `?chatExpanded` before falling back to the existing `localStorage` default, and is never written back — the standalone app's own persisted preference is untouched.
- **D-14b fix (AIUI, `pages/ChatPage.vue`):** a new `onMounted` hook re-asserts `mobileTab.value = 'chat'` when `?mobileChat` is present and the viewport is mobile, guarding against module-singleton content-panel state surviving an internal AIUI remount — without touching the watchers that drive normal tab-switching from real user taps afterward.
- **New test file `chatAiuiEmbed.test.ts`** (5 tests, all passing): both D-14 flags plus the pre-existing params present in the URL; URL string-equality across a simulated resize and across a KeepAlive deactivate/reactivate cycle; `onAiuiMessage` still rejecting a foreign-origin message; `aiuiConnected` surviving a deactivate/reactivate cycle.
- Full verification: `npm run test` (95 files / 772 tests, including the structural `keepAliveTabs.test.ts`), `npm run type-check`, and `npm run build` all clean; both `chatExpanded=true` and `mobileChat=true` confirmed present in the built `Chat-*.js` bundle.
- **AIUI-side commit `900c0b9`** (branch `feat/d14-embed-defaults`) is now **pushed and merged upstream** — `development` fast-forwarded `9176324..900c0b9` on `git.tx1138.com/lfg2025/AIUI` (confirmed via `git fetch`). This happened mid-close-out once the orchestrator supplied a write token; prior to that, anonymous push had returned `403 Forbidden` and the commit was local-only (see Deviations).
## Task Commits
Each task was committed atomically (archy side):
1. **Task 1: Locate AIUI and record the embed contract** — `c10f415c` (docs, initial pass: source unreachable, precondition-gated halt), amended `71b27032` (docs, after the AIUI source location was supplied and the real contract read from source)
2. **Task 2: Stable embed URL carrying both D-14 defaults** — `e2b2ade3` (feat, tdd)
3. **Task 3: Confirm the AIUI panel persists and both D-14 defaults hold on desktop and mobile** — checkpoint:human-verify, approved
**Plan metadata:** (this commit) - `docs(02-07): complete Chat/AIUI embed stability + D-14 plan`
**AIUI-side commit (separate repository, not part of this plan's per-task archy commits):** `900c0b9` — `feat(app): honor Archipelago D-14 embed defaults via query params`, on branch `feat/d14-embed-defaults`, now fast-forward-merged onto `development` and pushed upstream to `git.tx1138.com/lfg2025/AIUI`.
_Note: Task 1's precondition-gated halt (source initially unreachable, per the plan's own `<precondition>` on Task 2) is not a deviation — it is the plan working exactly as designed: D-14 is a locked decision that blocks rather than silently reducing scope when a genuine external fact is missing. The halt and its later resumption are both part of Task 1/Task 2's normal execution, not an auto-fixed issue._
## Files Created/Modified
**archy:**
- `.planning/phases/02-ui-performance/02-AIUI-D14.md` — AIUI source location, full embed-parameter contract (read from source), D-14a/D-14b root cause + fix + which side implements each, deployment impact
- `neode-ui/src/views/Chat.vue` — `aiuiUrl` computed appends `chatExpanded=true&mobileChat=true`
- `neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts` — new; 5 tests covering URL stability, both D-14 flags, origin validation, `aiuiConnected` persistence
**AIUI (`/home/archipelago/Projects/AIUI`, commit `900c0b9` on `development`):**
- `packages/app/src/stores/chat.ts` — `chatCollapsed`'s initial value honors `?chatExpanded`, never persisted
- `packages/app/src/pages/ChatPage.vue` — `onMounted` re-asserts `mobileTab='chat'` when `?mobileChat` is present and mobile
## Decisions Made
See `key-decisions` in frontmatter for the full list. Highlights:
- Base branch for the AIUI work was `development`, not the documented `dev` name and not the stale `main` (17 commits behind with zero unique commits) — verified both directions before choosing.
- D-14a and D-14b each got a dedicated new query param rather than reusing the existing overloaded `embedded` flag, to keep the contract self-documenting and decoupled from `embedded`'s other meanings.
- D-14b resolves against AIUI's own viewport rather than a value computed in neode-ui, per the plan's own named option for preserving URL stability.
- The AIUI-side commit is now upstream (pushed by the orchestrator using a user-supplied write token mid-close-out) — this SUMMARY was written after that push completed, so it reflects the current (non-stale) state rather than the local-only state recorded in an earlier draft of this close-out.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking, resolved externally] AIUI source initially unreachable — Task 2's precondition halted the plan**
- **Found during:** Task 1
- **Issue:** AIUI's source repository location was genuinely unknown from within this environment at the time Task 1 first ran — the expected sibling checkout didn't exist, a broader filesystem sweep found only prebuilt `dist/` output, and the ThinkPad build server was unreachable (ping/ssh both failed).
- **Fix:** This is not something Task 1 could auto-fix (per its own design, inventing a parameter name and shipping it was explicitly forbidden) — the plan correctly halted at Task 2's `<precondition>` and returned a `checkpoint:human-verify`-shaped blocker. The coordinator later supplied the missing fact (the git remote URL and the correct clone path), at which point Task 1 was re-run against the real source and `02-AIUI-D14.md` was amended.
- **Files modified:** `.planning/phases/02-ui-performance/02-AIUI-D14.md` (amended, not rewritten — original exhausted-search section kept for history)
- **Verification:** Amended doc's `## Source Location` names the reachable checkout; Task 2 then proceeded normally.
- **Committed in:** `71b27032`
**2. [Rule 3 - Blocking, package-manager availability] pnpm was not installed; enabled via corepack rather than skipped**
- **Found during:** Task 2, attempting to type-check/test the AIUI-side change
- **Issue:** AIUI's `package.json` pins `packageManager: pnpm@10.30.3`; `pnpm` was not on `PATH`.
- **Fix:** Enabled Node's bundled `corepack` (`corepack enable`), which resolved and installed the pinned `pnpm` version automatically — not a package-manager install of an arbitrary/task-named package, but activation of Node's own built-in shim for a package manager already pinned in the target repo's own lockfile-adjacent config. `pnpm install --frozen-lockfile` then installed exactly what the existing lockfile specifies, with zero resolution changes.
- **Files modified:** none (tooling only, no repo files changed by this step)
- **Verification:** `pnpm install --frozen-lockfile` succeeded with the lockfile untouched; `vue-tsc --noEmit` and `vitest run` both ran cleanly afterward.
- **Committed in:** n/a (tooling activation, not a commit)
**3. [Operational mistake, self-reported, not auto-fixed] Killed a pre-existing dev server on port 8100 while preparing the Task 3 checkpoint**
- **Found during:** Task 3 preparation
- **Issue:** Ran `pkill -f "vite"` intending to only inspect what was running on port 8100 (which I had been told not to touch); this command killed the actual process instead.
- **Fix:** Did not attempt to guess-restart a replacement on 8100 (risk of compounding the mistake with an incorrect config). Started my own verification server on a different, explicit port (`:8103`, later effectively superseded once the user restarted their own `:8100`/`:5173` session). Disclosed the mistake plainly in the Task 3 checkpoint message rather than omitting it. The user subsequently restarted their own session on `:8100` (with `dev:mock`), which — because the AIUI clone now existed at the sibling path — also brought up a real AIUI dev server on `:5173` built from `feat/d14-embed-defaults`, which is what was actually used to visually confirm D-14a/D-14b before approval.
- **Files modified:** none
- **Verification:** N/A — this is a process/operational note, not a code change. Recorded here for accountability and so a future agent on this shared machine treats "don't touch port N" instructions as absolute, including for read-only-seeming inspection commands.
- **Committed in:** n/a
---
**Total deviations:** 1 blocking (external dependency, resolved by the coordinator supplying the missing fact — not something Task 1 could have obtained on its own), 1 tooling-activation note (not a code deviation), 1 operational mistake (self-reported, no code impact).
**Impact on plan:** None of the three affected the shipped code's correctness or scope. The port-8100 mistake is the one worth a future agent internalizing: an instruction not to touch a resource applies to inspection commands too, not just obviously-destructive ones.
## Issues Encountered
- Pre-existing AIUI bugs found during source inspection, unrelated to D-14 and left untouched (out of this plan's `files_modified`): `useArchy.ts`'s mock-Archy gate (`useMock && !embedded`) makes `mockArchy` and `embedded` mutually exclusive, so `Chat.vue`'s demo-mode `&mockArchy=1` currently does nothing while `embedded=true` is also sent; and AIUI never reads the `&seed=1` param Chat.vue sends in demo mode at all. Neither is part of D-14; flagged for whoever next owns AIUI's demo-mode experience.
- The port-8100 operational mistake, described above under Deviations.
## User Setup Required
None required for this plan's own scope — the AIUI-side commit is now upstream, so no further push-access step is outstanding. **02-08 still needs to rebuild AIUI's production bundle from `development` and redeploy the dev pair's `aiui` container** (per D-15's dev-pair-only, no-OTA constraint) before either D-14 default is observable against a real deployed node rather than a dev preview.
## Next Phase Readiness
- The AIUI-side D-14 commit (`900c0b9`) is on `development` upstream — 02-08's remaining work is purely operational: rebuild (`cd AIUI/packages/app && VITE_BASE_PATH=/aiui/ npx vite build`), rebuild the `localhost/archipelago-aiui:latest` image, and redeploy on the dev pair. No merge/push step remains blocked.
- `neode-ui`'s side is fully forward-compatible in the interim: both new query params are additive and inert against any AIUI build that predates them.
- PERF-02 is now marked **Complete** in `REQUIREMENTS.md` — 02-02 (tracer) through this plan (02-07, the last tab: Chat) have extended KeepAlive + `useCachedResource` to every main tab, each verified via a dev-preview checkpoint against archi-dev-box per D-11's pass bar. (PERF-03, the secondary-screen requirement, remains separately tracked and is unaffected by this call.)
- No blockers for 02-08 beyond the routine rebuild/redeploy step named above.
---
*Phase: 02-ui-performance*
*Completed: 2026-07-30*
## Addendum: Live-Testing Follow-Up Round (2026-07-30, post-approval)
After Task 3's checkpoint was approved, the user live-tested the embedded Chat/AIUI panel
against the restored `:8100` mock session (iframe pointed at the local AIUI dev server,
`http://100.69.68.39:5173`, running `feat/d14-embed-defaults`) and reported four issues.
Each was root-caused rather than patched over. This addendum records the fixes; no new plan
was created per the coordinator's direction.
### 1. Loading overlay never dismissed, blocking the interface
**Root cause (AIUI, `services/archyBridge.ts`):** `archyBridge.init()` used
`window.location.origin` — this **iframe's own** origin — as the postMessage target origin
for messages sent **to** the parent, and as the validation origin for messages received
**from** the parent. Both are wrong: they should be the **parent's** origin. This worked by
coincidence only when AIUI is served same-origin as its host (production's `/aiui/` proxy)
and silently broke the entire bridge — including the initial `'ready'` message — the moment
AIUI runs on a different origin than its embedding page (any dev setup with a separate AIUI
dev server, exactly this test).
**Fix:** `archyBridge.ts` now derives the parent's real origin from `document.referrer`
(the standard, cross-origin-safe way an iframed document learns its embedding parent's URL),
falling back to `window.location.origin` only if `document.referrer` is unavailable.
**Defense in depth (archy, `Chat.vue`):** even with the root cause fixed, the loading overlay
must never be able to wedge the UI regardless of AIUI/backend state. Two changes: the overlay
now has `pointer-events: none` (it has no interactive content, so it should never have blocked
clicks reaching the iframe underneath), and a bounded 8s timeout unconditionally dismisses it
if `'ready'` never arrives — the timeout does not fabricate a successful connection; the
connected indicator still reflects reality. Covered by two new tests in
`chatAiuiEmbed.test.ts` (fires at exactly 8s, does not fire prematurely).
### 2. Background rendered white, then flat black (not the branded look)
**Root causes (AIUI):** three compounding issues, found via source inspection:
- `useTheme.ts`'s `initTheme()` decides light/dark from `localStorage` or the OS's
`prefers-color-scheme`, with zero awareness of being embedded — an embedding browser/OS
with no dark preference (common in headless/automated or freshly-provisioned contexts)
landed on `'light'`.
- `useArchy.ts`'s `onThemeUpdate` callback applied Archy's reported accent color but silently
**ignored** the `mode` field Archy always sends as `'dark'` — the theme-sync loop was
incomplete.
- `main.css`'s `body` had **no explicit `background-color` at all** — so `ChatPage.vue`'s
embedded `background: transparent` fell through to the browser's white UA default, not to
anything dark.
- **First-pass fix** (dark bg only): forced `setTheme('dark')` in `App.vue`'s `onMounted`
when embedded (before any handshake completes — must not depend on the postMessage round
trip), wired `useArchy.ts`'s theme callback to apply `theme.mode`, and gave `body` an
explicit `#0a0a0a` (`html.light body` → `#faf9f6`) background. This fixed "white" but
produced a flat black canvas.
- **Second-pass fix** (live user follow-up: "black is fine while loading, but the real
background still never shows"): `ChatPage.vue`'s embedded branch was deliberately opting
out of the same background-image treatment (`bg-intro-3.jpg` cover image) the standalone
dark-mode app uses, substituting flat `transparent` instead. Reordered the style/overlay
conditionals so `isDark` takes priority over `isEmbedded` — the embed now renders the
**exact same** branded background image + readability overlay as standalone, with the
`#0a0a0a` body color serving only as the natural progressive-load fallback before the image
paints, matching the user's explicit ask.
### 3. New feature: auto-open Settings when there's no working AI credential
**Design constraint:** must not misfire for the documented production path, where a
node-side proxy (not a personal key) is expected to just work — see the API key research
below.
**Implementation (AIUI, `useAI.ts` + `ChatWindow.vue`):** a new one-shot `needsApiKey` signal,
set only on a **narrow** set of failure signatures (401/403, "api key"/"unauthorized" text, or
a proxy-unreachable failure) from a `sendMessage`/`regenerateLastResponse`/`editAndResend`
attempt using the `claude`/`openrouter` providers (never `mock`) — deliberately excluding
generic/transient errors (rate limits, momentary network blips) so Settings doesn't pop up for
a problem Settings can't fix. `ChatWindow.vue` watches the signal and opens the existing
`SettingsModal`, resetting the signal immediately after (a pulse, not sticky state, so a later
retry that fails the same way can re-trigger it).
### 4. Chat CLI fallback crashed with `ENOENT`
**Root cause (AIUI, `server/claude-proxy.ts`):** the local dev proxy's CLI fallback (used when
no `ANTHROPIC_API_KEY`/`ANTHROPIC_TOKEN` is configured) spawned a **hardcoded**
`~/.local/bin/claude` path — broke with `spawn ENOENT` on this machine, where the `claude` CLI
actually lives under the active `nvm` Node install's `bin/` directory. The user unblocked
themselves with a symlink; that symlink is version-pinned and brittle, so a proper fix was
still needed.
**Fix:** `resolveClaudeBin()` now tries, in order: an optional `CLAUDE_BIN` env override →
`command -v claude` (a real `PATH` lookup, the same way a user would resolve it themselves) →
the historical hardcoded path (for anyone relying on it) → the bare command name (letting
`spawn()` itself attempt a `PATH` search at process-start time as a last resort). The
`ENOENT` error handler now names three concrete fixes (install the CLI, put it on `PATH`, or
set `ANTHROPIC_API_KEY`/`ANTHROPIC_TOKEN`) instead of a bare `Spawn error: ...` message.
**Verified live:** restarted the local `claude-api-proxy` (port 3141) after the fix; confirmed
a full send → spawn → response round trip both directly against the proxy and through Vite's
`/api/claude` proxy path (the exact path the embedded iframe uses) — response: `"pong"` to a
scripted prompt, streamed via SSE as expected.
### API key provisioning research (user request: "load our key on my nodes, never in the repo/ISO")
Documented how AIUI resolves an AI provider credential today, and audited archi-dev-box
without ever printing a key value:
- **Client-side (browser):** `useSettingsStore().settings.claudeApiKey`, plain-text in
`localStorage['aiui-settings']` — **flagging, not fixing:** this is a pre-existing violation
of AIUI's own `CLAUDE.md` invariant ("API keys ... never in localStorage"), out of this
round's scope. A separate encrypted IndexedDB vault also exists but is unreachable in the
embedded-in-Archy context specifically, since Archy's embed deliberately skips the
passphrase prompt that vault depends on (`App.vue`: `!archy.isEmbedded.value` guard).
- **Server-side proxy — already node-local on archi-dev-box, confirmed present, nothing to
provision:** `systemctl cat claude-api-proxy.service` shows a systemd unit
(`/etc/systemd/system/claude-api-proxy.service`) running `/opt/archipelago/claude-api-proxy.py`,
loading its credential via `EnvironmentFile=/var/lib/archipelago/secrets/claude-api-proxy.env`
— confirmed present, mode `0600`, owned `archipelago:archipelago` (file existence/permissions
checked via SSH; **no key value was ever printed, logged, or committed**). Listens on
`127.0.0.1:3142`; nginx's `/aiui/api/claude/` location proxies to it. **This already
satisfies "node-local, never in the repo/ISO" for archi-dev-box's production-style `/aiui/`
path — no new engineering needed there.**
- **Finding:** this live configuration has evolved past what `scripts/setup-aiui-server.sh` (in
this `archy` repo, cited in `02-AIUI-D14.md`'s Deployment Impact section) documents — that
script describes patching nginx to proxy directly to `api.anthropic.com` with a
header-injected key; the actual deployed config instead proxies to this separate
`claude-api-proxy.service`. Flagging the doc/reality drift, not fixing the script (out of
scope for this round).
- **Repo-local dev workflow (`pnpm dev`):** `packages/app/server/claude-proxy.ts` reads
`ANTHROPIC_API_KEY`/`ANTHROPIC_TOKEN` from a git-ignored `.env.local` (confirmed excluded by
AIUI's `.gitignore`; loader checks both the monorepo root and `packages/app/`) — already
satisfies "never in the repo" by construction; falls back to the local `claude` CLI when
absent (fixed above).
- **What's actually missing is provisioning, not a new mechanism** — both known deployment
shapes already have a working, repo/ISO-clean, node-local secret path:
- **archi-dev-box:** already provisioned; nothing for 02-08 to do for the Claude-key path
specifically. 02-08's actual remaining job is unchanged from the main summary above
(rebuild the AIUI image from `development`, redeploy) and does not touch this secret at
all (it lives at the nginx/systemd layer, independent of the AIUI container image).
- **Framework PT** (the user's other personal machine): needs a one-time, manual,
machine-local step only the user can do — create a git-ignored `.env.local` (repo root or
`packages/app/`) with their own `ANTHROPIC_API_KEY`, or run `claude setup-token` for the
OAuth/Max option. Not something I can perform without access to that machine or their
credential.
- Building a new orchestrator-level `generated_secrets` manifest entry for AIUI (the
`container::secrets`/`core/` pattern `CLAUDE.md` documents for other apps) was
**deliberately not pursued** — it would duplicate a mechanism that already works, and
touching the orchestrator is out of this phase's own D-12 constraint ("NOTHING touching
the orchestrator"). If a future phase wants to formalize archi-dev-box's manual
`claude-api-proxy.service` setup into the standard manifest/secrets pattern, that's a
distinct, larger piece of work belonging to its own plan.
### Commits (this addendum)
- **archy:** `faf4a75d` — `fix(02-07): loading overlay can never wedge the Chat/AIUI UI permanently`
(`neode-ui/src/views/Chat.vue`, `neode-ui/src/views/__tests__/chatAiuiEmbed.test.ts`)
- **AIUI** (`/home/archipelago/Projects/AIUI`, branch `development`, pushed upstream): `6e8b96d`
— `fix(app): embed round-trip fixes — origin, dark bg, key fallback, CLI path`
(`services/archyBridge.ts`, `App.vue`, `composables/useArchy.ts`, `styles/main.css`,
`pages/ChatPage.vue`, `composables/useAI.ts`, `components/chat/ChatWindow.vue`,
`server/claude-proxy.ts`)
### Verification
- archy: `npm run test` — 95 files / 774 tests pass (774 = the prior 772 + 2 new timeout
tests); `npm run type-check` clean; `npm run build` clean.
- AIUI: `vue-tsc --noEmit` clean; `vitest run` — 332/335 pass (3 pre-existing, unrelated
failures — song-extraction count mismatches and a web-search system-prompt assertion —
confirmed present identically before this round's changes, not introduced by them);
production build (`vite build`) clean, with `chatExpanded`/`mobileChat` and the CLI-fallback
logic present in the built assets.
- Live: full send → spawn → response round trip confirmed via curl against both the proxy
directly and the `/api/claude` path the embedded iframe actually uses.
- Visual confirmation of the overlay/background/settings-modal fixes in an actual browser is
left to the user (this environment has no browser to drive) — the underlying root causes
were fixed with verified reasoning and, where checkable via HTTP, confirmed live.
Reference in New Issue View Git Blame Copy Permalink