> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase32-session04-settings-and-copy/spec.md). # Session Specification **Session ID**: `phase32-session04-settings-and-copy` **Phase**: 32 - AI Rogue Mobile Input Auto-Detect **Status**: Not Started **Created**: 2026-06-24 *** ## 1. Session Overview This session aligns the visible AI Rogue controls language with the raw input preference contract and the resolved effective runtime mode. Sessions 02 and 03 added durable `auto | keyboard | compact` preferences and wired the mounted Play surface to pass only concrete `keyboard | compact` values into Runtime Canvas. The remaining gap is product copy and Settings controls that still present only Keyboard and Compact, and in one place still promise keyboard plus canvas input. The work is next because Session 05 test coverage depends on stable user-facing labels for fresh mobile auto behavior, explicit overrides, and compact control status. Settings must be able to save Auto, Loadout and Play must not collapse raw Auto into Compact, and Runtime Canvas status copy must agree with the effective mode actually sent to the runtime. The session stays inside the existing AI Rogue extension. It does not add new diagnostics panels, new input devices, runtime renderer refactors, public-demo smoke coverage, or default AI Rogue enablement. *** ## 2. Objectives 1. Add an Auto option to AI Rogue Settings while preserving explicit Keyboard and Compact choices. 2. Show raw Auto plus its resolved effective mode consistently in Settings, Loadout, Play, compact-control status, and runtime readiness copy. 3. Remove `Keyboard and canvas` copy unless canvas pointer input is available for keyboard mode. 4. Add focused component tests proving Auto selection, resolved labels, and explicit override copy across affected views. *** ## 3. Prerequisites ### Required Sessions * [x] `phase32-session01-baseline-validation` - Validated the mobile failure and capability heuristic. * [x] `phase32-session02-preference-contract` - Added durable raw Auto preferences, effective input-mode types, resolver, hook, schema defaults, and tests. * [x] `phase32-session03-effective-mode-wiring` - Routed effective input mode through Play and Runtime Canvas without passing raw Auto into runtime APIs. ### Required Tools Or Knowledge * React 19 component patterns in `src/extensions/ai-rogue/views/`. * AI Rogue input-mode utilities in `src/extensions/ai-rogue/input-mode.ts`. * Focused Vitest component tests under `src/extensions/ai-rogue/__tests__/`. ### Environment Requirements * Bun 1.3.14 with existing project scripts available. * Happy DOM Vitest environment for component and hook coverage. *** ## 4. Scope ### In Scope (MVP) * AI Rogue player can choose Auto, Keyboard, or Compact in Settings, and each choice remains visibly distinct. * AI Rogue player sees Auto resolved as `Auto (compact)` on coarse/no-hover capability and `Auto (keyboard)` on desktop or unavailable capability. * AI Rogue player sees Loadout and Play summaries that report raw Auto without collapsing it to Compact. * AI Rogue player no longer sees `Keyboard and canvas` copy for keyboard mode unless keyboard-mode canvas pointer input is implemented. * AI Rogue compact-control status copy agrees with the effective mode used by Runtime Canvas. * Existing Settings accessibility, responsive segmented-control behavior, optimistic preference saving, and focus handling remain intact. ### Out Of Scope (Deferred) * New settings diagnostics panels - Reason: Session 04 is a product copy and control alignment session, not a debug surface. * New input devices such as gamepad, pointer lock, or keyboard-mode canvas movement - Reason: Phase 32 is scoped to the existing auto, keyboard, and compact controls contract. * Default AI Rogue extension enablement - Reason: Active concern P30 keeps AI Rogue explicit opt-in until a separate product decision and gate evidence. * Public-demo mobile gameplay smoke - Reason: Session 05 owns fresh-state mobile and public-demo gameplay coverage. * Runtime renderer refactors - Reason: Session 03 already established the concrete runtime boundary. *** ## 5. Technical Approach ### Architecture Use `input-mode.ts` as the shared source for raw/effective label formatting so Settings, Loadout, Play, Runtime Canvas copy, and tests do not duplicate string rules. Settings and Loadout are mounted browser views, so they can use `useAiRogueInputModeCapabilities()` plus `resolveAiRogueEffectiveInputMode(...)` to show the same Auto resolution language as Play. Settings should render the raw choices from `AI_ROGUE_RAW_INPUT_MODES`, save the raw preference value, and show a resolved label only when raw mode is Auto. Loadout and Play should continue to read browser-local save state, but their summary rows should distinguish the durable raw preference from the concrete effective runtime mode. Runtime Canvas should keep receiving the existing `preferences` and `effectiveInputMode` props, and its compact-control status should use both values only for visible copy. Runtime mount/update payloads must remain concrete. ### Design Patterns * Shared copy helper: Centralize Auto label formatting near the input-mode resolver. * Mounted edge resolution: Capability reads stay in React views, not in schema, persistence, save-state, renderer, or runtime modules. * Product-surface copy: Labels describe controls the player can use; diagnostics stay in tests and session notes. * Behavior-first tests: Tests assert visible labels and saved raw values rather than implementation details alone. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---- | ------------------------------------------------------- | ---------- | | None | No new source files are expected for this copy session. | 0 | ### Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- | | `src/extensions/ai-rogue/input-mode.ts` | Add shared raw/effective label helpers for Auto, Keyboard, and Compact copy. | \~45 | | `src/extensions/ai-rogue/views/settings-view.tsx` | Add Auto controls choice, resolved Auto label, and corrected Settings controls copy. | \~70 | | `src/extensions/ai-rogue/views/loadout-view.tsx` | Update persistent-state summaries so raw Auto is not collapsed to Compact. | \~25 | | `src/extensions/ai-rogue/views/play-view.tsx` | Update Play readiness and runtime-boundary copy to show raw and effective controls. | \~35 | | `src/extensions/ai-rogue/views/runtime-canvas.tsx` | Update compact-control status copy to agree with raw Auto and effective mode. | \~25 | | `src/extensions/ai-rogue/__tests__/input-mode.test.tsx` | Cover shared label helper behavior. | \~35 | | `src/extensions/ai-rogue/__tests__/client.test.tsx` | Cover Settings Auto selection plus Loadout and Play raw/effective labels. | \~110 | | `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` | Cover compact-control status copy for raw Auto and explicit overrides. | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Settings can save Auto, Keyboard, and Compact raw preferences. * [ ] Auto copy reports the current resolved mode consistently across Settings, Loadout, Play, and compact-control status. * [ ] Keyboard copy no longer promises canvas input. * [ ] Explicit Keyboard and Compact choices remain visibly distinct from Auto. * [ ] Runtime-facing APIs and renderer/render-model contracts still never receive raw `"auto"`. ### Testing Requirements * [ ] Input-mode helper tests cover Auto, Keyboard, Compact, and unavailable capability labels. * [ ] Settings component tests cover Auto selection, saved value, resolved label, explicit choices, and corrected keyboard copy. * [ ] Loadout and Play component tests cover raw Auto plus effective label and explicit override labels. * [ ] Runtime Canvas component tests cover compact-control status copy for raw Auto with effective Compact and explicit Keyboard behavior. * [ ] Focused Vitest and TypeScript checks pass for touched AI Rogue files. ### Non-Functional Requirements * [ ] Capability reads remain browser-view scoped and do not move into schema, persistence, save-state, renderer, or runtime modules. * [ ] No new public-demo bridge calls, hosted writes, collectors, analytics, or remote loading are introduced. * [ ] AI Rogue remains explicit opt-in and browser-local. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * Session 03 is the authoritative runtime input boundary for this copy work. Evidence: the analyzer lists `phase32-session03-effective-mode-wiring` as completed, `PlayView` already derives `effectiveInputMode`, and `AiRogueRuntimeCanvas` already receives `effectiveInputMode` while runtime types accept only `keyboard | compact`. Planning can proceed because Session 04 only changes visible copy and controls around that established contract. * Settings and Loadout may use the existing mounted capability hook for resolved Auto labels. Evidence: both are React browser views under `src/extensions/ai-rogue/views/`, `input-mode.ts` already exposes `useAiRogueInputModeCapabilities()`, and Session 04 explicitly requires Settings and Loadout copy to match raw/effective mode. Planning can proceed because this keeps capability reads out of durable storage and runtime code. ### Conflict Resolutions * Existing Settings copy says `Keyboard and canvas`, while the Phase 32 PRD says canvas pointer movement is ignored outside compact mode and Session 04 says to replace that copy unless keyboard-mode canvas pointer input is implemented. The Phase 32 PRD and Session 04 stub win: use Keyboard copy that does not promise canvas movement. * Session 04 asks HUD/runtime summaries to agree with effective mode, while Session 03 requires runtime-facing APIs to never receive raw Auto. The chosen interpretation is to keep renderer and render-model summaries effective-only and update React Runtime Canvas status copy using raw preference plus effective mode at the UI boundary. ### Key Considerations * Do not add diagnostics or implementation language to product UI. * Keep Settings controls accessible as buttons with stable dimensions and clear `aria-pressed` state. * Preserve optimistic preference saves and reset focus handling. ### Potential Challenges * Auto labels can drift across views. Mitigation: add a shared formatting helper and focused visible-copy tests. * Capability values are unavailable during initial render or unsupported browser APIs. Mitigation: default Auto labels to keyboard, matching `resolveAiRogueEffectiveInputMode(...)` fallback behavior. * Raw and effective modes intentionally diverge for Auto. Mitigation: keep copy explicit, such as `Auto (compact)`, and keep runtime payloads concrete. ### Relevant Considerations * \[P30] **AI Rogue default enablement deferred**: This session must not make AI Rogue default-enabled or broaden extension activation. * \[P31] **Pages demo stays static-only**: Public-demo behavior must not add bridge calls, hosted writes, collectors, analytics, or Pages Functions. * \[P30] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade; React owns coarse state while Pixi owns frames and cleanup. * \[P30] **Schema-backed browser-local state works**: Keep raw preferences in the existing browser-local schema and resolve effective behavior outside durable storage. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Settings saves may double-trigger or appear stale while preference writes are in flight. * Auto copy may collapse to Compact or Keyboard in one view and confuse explicit override behavior. * Capability-unavailable environments may show a label that disagrees with the resolver fallback. *** ## 9. Testing Strategy ### Unit Tests * Cover shared input-mode label helper cases in `src/extensions/ai-rogue/__tests__/input-mode.test.tsx`. ### Integration Tests * Cover Settings, Loadout, and Play visible copy in `src/extensions/ai-rogue/__tests__/client.test.tsx`. * Cover Runtime Canvas compact-control status copy in `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx`. ### Runtime Verification * Run focused Vitest files for input-mode, client, and runtime-canvas behavior. * Run `bun run typecheck` after the source changes. ### Edge Cases * Raw Auto on coarse/no-hover capability resolves to compact copy. * Raw Auto on desktop or unavailable capability resolves to keyboard copy. * Explicit Keyboard on mobile-capable browser remains Keyboard. * Explicit Compact on desktop-capable browser remains Compact. * Persistence unavailable or mutating states keep controls disabled and readable. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase32-session01-baseline-validation`, `phase32-session02-preference-contract`, `phase32-session03-effective-mode-wiring` * Depended by: `phase32-session05-gameplay-test-coverage` *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase32-session04-settings-and-copy/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.