archy/.planning/phases/02-ui-performance/02-AIUI-D14.md

AIUI D-14 Embed Contract

Written: 2026-07-30 (Phase 02 Plan 07, Task 1) Amended: 2026-07-30 (Phase 02 Plan 07, Task 2 resume) — the orchestrator supplied the missing fact this document's original Task 1 pass could not obtain from within this environment: AIUI's source repository location. This amendment replaces the "search exhausted" conclusion below with the real contract read directly from source, and records the D-14a/D-14b implementation actually shipped.

Source Location

AIUI's source is now located and was cloned for this plan:

• Repository: https://git.tx1138.com/lfg2025/AIUI (anonymous git ls-remote succeeds; clone succeeded read-only, push is 403 Forbidden anonymously — see Deployment Impact).
• Cloned to: /home/archipelago/Projects/AIUI — the exact sibling path neode-ui/package.json's dev:mock script and scripts/setup-aiui-server.sh both already expected (<parent-of-archy>/AIUI), so no changes to either script were needed once the clone existed.
• Branch used: development, not the repository's default main. Verified via git log main..origin/development vs git log origin/development..main: development is 17 commits ahead of main (including a run of fix(app): security-hardening commits — origin validation, rate limiting, CSP, SSRF protection, dev-server auth — and the feature/content work this session's grep relies on) with zero commits unique to main. main is simply stale here; development is the actual working branch. (AIUI's own CLAUDE.md documents the intended name as dev, but the real remote branch is named development — a doc/reality mismatch noted for AIUI's own maintainers, out of scope to fix from this repository.)
• ThinkPad build server: confirmed reachable this session at 100.69.68.39 (Tailscale), per the orchestrator-supplied fact. Not needed once the git clone succeeded — recorded here for completeness since Task 1's original search treated it as the fallback path.
• Hosting note (context only, not acted on): the user noted AIUI hosting may later be ported to "our main vps2." No action taken on this in this plan; recorded for whoever picks up AIUI's deployment next.

Original Task 1 search (superseded, kept for history)

The initial pass searched the sibling path (<parent-of-archy>/AIUI — not present at that time), a broader filesystem sweep (found only prebuilt dist/ output under /opt/archipelago/web-ui*/aiui, this repo's apps/aiui/demo/aiui, and installer-ISO copies — never source), and the ThinkPad at 192.168.1.116 (ping/ssh both failed at that time — host unreachable from this environment on that address/path). That search was genuinely exhausted with the facts available at the time; the blocker was resolved externally (see Amended note above), not by anything different this pass did on the same inputs.

Embed Parameter Contract

neode-ui/src/views/Chat.vue's aiuiUrl computed (lines ~74-82) sends, unchanged by this plan:

• embedded=true — always present.
• hideClose=true — always present.
• &mockArchy=1&seed=1 — only when IS_DEMO (build-time env var, stable for the life of the bundle).

Read from AIUI source (development branch, commit 9176324 before this plan's changes):

• embedded — packages/app/src/main.ts:34-35. Read once, before router init, via new URLSearchParams(window.location.search).has('embedded') (presence-only check) and stored on window.__AIUI_EMBEDDED__ so it survives SPA navigation. Matches the deployed build's minified behavior exactly (independently confirmed by the diligence pass on the built bundle before source access — see history above).
• mockArchy — packages/app/src/composables/useArchy.ts:83-96. Read via import.meta.env.VITE_MOCK_ARCHY === 'true' || new URLSearchParams(...).has('mockArchy'), but the mock-data branch is only entered if (useMock && !embedded) — i.e. mutually exclusive with embedded in this codebase today. This confirms the inconsistency flagged during the original diligence pass: Chat.vue's demo mode sends embedded=true and mockArchy=1 together, but AIUI only honors mockArchy when NOT embedded. Pre-existing, unrelated to D-14, not fixed here (out of this plan's file scope — flagged for whoever owns the demo-mode AIUI experience next).
• hideClose — confirmed absent from AIUI's source entirely (grep -rn "hideClose" packages/ returns nothing). AIUI does not read or honor this parameter at all today. Not part of D-14; not investigated further.
• seed — confirmed absent from AIUI's source entirely (no URLSearchParams read anywhere references it). Chat.vue's &seed=1 in demo mode currently does nothing on the AIUI side. Pre-existing, unrelated to D-14, not fixed here.

D-14a

Default: the AIUI chat should start EXPANDED rather than requiring the user to expand it.

• Root cause, found in source: packages/app/src/stores/chat.ts:132 (before this plan's change): const chatCollapsed = ref(localStorage.getItem('aiui-chat-collapsed') !== 'false') — defaults to collapsed (true) on any fresh/unset localStorage, i.e. exactly the behavior CONTEXT.md describes ("requiring the user to expand it"). chatCollapsed gates ChatWindow.vue's PromptIndex (collapsed quick-pick view) vs. the full virtualized message list (expanded view) — confirmed at ChatWindow.vue:35 / ChatWindow.vue:249. Once a user manually expands, the choice is written back to localStorage (chat.ts:196-198) and persists — so this bug only bites on a genuinely fresh localStorage, matching the reported "starts collapsed" default.
• Status: implemented, on the AIUI side, gated by a new query parameter — ?chatExpanded. Not something the deployed build already read (see original diligence pass); a source change was required and made.
• Which side implements it: AIUI reads the flag; neode-ui sends it. Implementation: chatCollapsed's initial ref now checks new URLSearchParams(window.location.search).has('chatExpanded') first, defaulting to false (expanded) when present, before falling back to the existing localStorage check. Never written back to localStorage — it is a one-time initial-state override for this session only, so a later manual collapse/expand while embedded still persists exactly as before, and the standalone (non-embedded) app's own default is completely untouched (it never sends ?chatExpanded, so its localStorage-based behavior is unchanged).
• Why a new parameter rather than reusing the existing embedded flag: embedded is already overloaded (transparent background, mock-Archy gating, passphrase-prompt skip); tying chatCollapsed's default to it directly would mean every embedded session forces expanded with no way to decouple the two concerns later. A dedicated flag keeps the contract self-documenting and matches this plan's acceptance criteria (the flag name must be discoverable in the built neode-ui bundle).

D-14b

Default: on a mobile viewport, AIUI should open on its CHAT view rather than its context view.

• Root cause, found in source: packages/app/src/pages/ChatPage.vue:469 already initializes mobileTab to 'chat' (const mobileTab = ref<'chat' | 'content' | 'context'>('chat')) — so a truly fresh mount already defaults correctly. The reported bug is a carry-over, not a wrong default: panelOpen, selectedFilm/selectedBook/etc., and hasDetailOpen (computed from those) are module-scope singleton refs in useContentPanel.ts (ref() calls at module top level, not inside the composable function), shared across every mount of ChatPage.vue within the same AIUI SPA session. If a user previously opened a detail item (making hasDetailOpen true, which ChatPage.vue's own watch(hasDetailOpen, ...) at line ~507 flips mobileTab to 'context' for), and ChatPage.vue later remounts within the same iframe session (e.g. an internal AIUI navigation to /guide and back) without those refs resetting, hasDetailOpen is still true on the new mount and the "opens on chat" default never gets a chance to hold — it's immediately superseded by state carried over from before. Note this is now less likely to surface at all going forward, since Task 2's URL-stability fix (see D-14 URL stability, below) keeps the iframe itself from reloading on an Archipelago tab switch — but it can still happen from AIUI's own internal navigation, independent of Archipelago.
• Status: implemented, on the AIUI side, gated by a new query parameter — ?mobileChat.
• Which side implements it: AIUI reads the flag; neode-ui sends it. Implementation: a new onMounted hook in ChatPage.vue re-asserts mobileTab.value = 'chat' when ?mobileChat is present and isMobile.value is true, at mount time only. This does not touch the panelOpen/hasDetailOpen watchers that drive normal tab-switching in response to actual user taps after the initial paint — those are unchanged, so a user can still navigate to the content/context tabs exactly as before; only the initial tab on a (re)mount is affected.
• Why AIUI decides from its own viewport rather than neode-ui passing a computed boolean: per Task 2's URL-stability constraint, aiuiUrl cannot embed a reactive viewport read (see below). ?mobileChat is sent unconditionally and is unconditionally interpreted by AIUI against its own isMobile computed (windowWidth.value < 1024, read from the iframe's own window.innerWidth) — this is the "let AIUI decide from its own viewport" option named in the plan's Task 2 action, chosen over resolving neode-ui's outer viewport once at setup time, since AIUI's iframe has its own layout breakpoint and is the side that actually owns the mobile/desktop layout switch.

D-14 URL Stability (how neode-ui sends both flags)

Both ?chatExpanded and ?mobileChat are appended unconditionally in Chat.vue's aiuiUrl computed — static strings, not derived from any runtime-varying input (no viewport read, no connection state, no timestamp). This preserves the property Task 2 exists to protect: the iframe src stays byte-identical across re-renders, viewport resizes, and deactivate/reactivate cycles, so the AIUI panel never reloads on an Archipelago tab switch.

Deployment Impact

apps/aiui/manifest.yml still declares a prebuilt container image (localhost/archipelago-aiui:latest, pull_policy: always) — this plan's AIUI-side change does not alter that; shipping it still requires:

1. Merging the AIUI-side commit. Changes are committed locally in the cloned checkout at /home/archipelago/Projects/AIUI on branch feat/d14-embed-defaults (based on development), commit 900c0b9. Anonymous push to origin failed with 403 Forbidden (git push origin feat/d14-embed-defaults) — this account has read-only access to git.tx1138.com/lfg2025/AIUI. The branch and commit exist only in this local checkout until someone with write access pushes it (or opens a PR from a fork/mirror they do have write access to) and merges it into development.
2. Rebuilding AIUI's production bundle from the merged source: cd AIUI/packages/app && VITE_BASE_PATH=/aiui/ npx vite build (per scripts/setup-aiui-server.sh's documented prerequisite).
3. Rebuilding the localhost/archipelago-aiui:latest container image from that build output (a local/on-node image tag, not a registry pull).
4. Redeploying/restarting the aiui app container on the target node(s) so pull_policy: always picks up the new local image.

Per D-15, deployment is dev pair only this phase, no OTA — plan 02-08 owns the deploy step under that constraint, once the AIUI-side commit is actually mergeable (i.e., once a maintainer with push rights lands feat/d14-embed-defaults on development and it's rebuilt/redeployed). Until that push/merge happens, the deployed AIUI build on any node (including archi-dev-box) will NOT carry these two parameters — neode-ui's side is fully forward-compatible with that (both flags are inert query-string additions the current deployed AIUI build simply ignores, per the confirmed absence of hideClose-style unknown params breaking anything), but the two visual defaults (expanded start, mobile-chat-first start) will not be observable against any currently-deployed AIUI build until the AIUI commit ships.