> 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-session03-effective-mode-wiring/spec.md).

# Session Specification

**Session ID**: `phase32-session03-effective-mode-wiring` **Phase**: 32 - AI Rogue Mobile Input Auto-Detect **Status**: Not Started **Created**: 2026-06-24

***

## 1. Session Overview

This session routes the resolved AI Rogue effective input mode through the Play view and Runtime Canvas boundary. Session 02 added the durable raw preference contract (`auto | keyboard | compact`), the effective-mode resolver, and the mounted capability hook. This session makes those pieces drive the live runtime instead of resolving `auto` without browser capability context.

The work is next because Phase 32 cannot satisfy the mobile first-run goal until the mounted Play surface passes only a concrete `keyboard | compact` mode into runtime mount and update calls. It also makes compact controls and canvas pointer input follow the effective mode while preserving explicit user choices.

The session stays within the existing AI Rogue extension, keeps PixiJS lazy behind the Play route/local runtime facade, and does not change extension enablement, Settings copy, public-demo smoke, or gameplay commands.

***

## 2. Objectives

1. Derive `effectiveInputMode` in the mounted Play view from raw preference plus browser capability signals.
2. Pass the concrete effective mode into `AiRogueRuntimeCanvas` through an explicit prop while keeping raw preferences durable-only.
3. Use the effective mode for runtime mount preferences and `controller.updatePreferences`.
4. Use the effective mode for compact controls and canvas pointer-input availability, including already mounted runtime updates.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase32-session01-baseline-validation` - Validated the mobile failure and capability heuristic.
* [x] `phase32-session02-preference-contract` - Added raw/effective input-mode types, resolver, mounted capability hook, schema defaults, and tests.

### Required Tools Or Knowledge

* React 19 component and hook patterns in `src/extensions/ai-rogue/views/`.
* AI Rogue runtime mount/update contract in `src/extensions/ai-rogue/runtime/`.
* 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 open Play with raw `auto` on a coarse/no-hover browser and receive effective `compact` runtime behavior.
* AI Rogue player can choose explicit `keyboard` on a mobile-capable browser and keep compact controls and pointer input disabled.
* AI Rogue player can choose explicit `compact` on a desktop-capable browser and keep compact controls and pointer input enabled.
* Runtime-facing APIs receive only concrete `keyboard | compact` input modes.
* Existing Play route runtime lifecycle, seed replay, save/load, progression loadout, and lazy PixiJS import boundaries remain intact.

### Out Of Scope (Deferred)

* Settings `Auto` UI and copy changes - Reason: Session 04 owns Settings, Loadout, Play, compact-control, and HUD copy alignment.
* Public-demo mobile smoke - Reason: Session 05 owns fresh-state public-demo gameplay coverage.
* New gameplay commands, gamepad, pointer lock, or renderer refactors - Reason: Phase 32 is scoped to existing mobile first-run input mode behavior.
* Default AI Rogue extension enablement - Reason: Active concern P30 keeps AI Rogue explicit opt-in until a separate product decision and gate evidence.

***

## 5. Technical Approach

### Architecture

`PlayView` is the mounted browser UI boundary. It should call `useAiRogueInputModeCapabilities()`, resolve `saveState.preferences.inputMode` with `resolveAiRogueEffectiveInputMode(...)`, and pass `effectiveInputMode` to `AiRogueRuntimeCanvas`.

`AiRogueRuntimeCanvas` should treat raw `preferences` as durable preference state for non-input settings and should treat `effectiveInputMode` as the only runtime-facing input mode. Runtime mount options, runtime preference updates, compact control enablement, and compact status text should all read from the effective mode.

Runtime modules, render-model helpers, and renderer state already use concrete `keyboard | compact` contracts. This session preserves those contracts and keeps capability detection out of schema, persistence, save-state, and PixiJS runtime modules.

### Design Patterns

* Mounted edge resolution: Browser capability reads happen after mount in React, not inside durable schema or runtime modules.
* Concrete runtime boundary: Runtime mount/update calls accept only `AiRogueEffectiveInputMode`.
* Lazy runtime ownership: PixiJS stays imported only through the Play route-local runtime boundary.
* Behavior-first tests: Component tests assert observed mode behavior and runtime call payloads instead of resolver internals alone.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                                   | Est. Lines |
| ---- | --------------------------------------------------------- | ---------- |
| None | No new source files are expected for this wiring session. | 0          |

### Files To Modify

| File                                                        | Changes                                                                                         | Est. Lines |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/views/play-view.tsx`               | Derive mounted effective input mode and pass it to Runtime Canvas.                              | \~20       |
| `src/extensions/ai-rogue/views/runtime-canvas.tsx`          | Require `effectiveInputMode`, use it for mount/update preferences and compact-control gating.   | \~35       |
| `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` | Cover concrete runtime payloads, effective compact controls, and explicit keyboard disablement. | \~90       |
| `src/extensions/ai-rogue/__tests__/client.test.tsx`         | Cover Play view effective-mode derivation from capability signals and explicit overrides.       | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Fresh raw `auto` on coarse/no-hover capability resolves to effective `compact` before Runtime Canvas mount/update.
* [ ] Fresh raw `auto` on fine/hover or unavailable capability resolves to effective `keyboard`.
* [ ] Explicit `keyboard` on a mobile-capable browser disables compact controls and prevents compact touch commands.
* [ ] Explicit `compact` on a desktop-capable browser enables compact controls after Start.
* [ ] Runtime mount and update preferences never receive raw `"auto"`.

### Testing Requirements

* [ ] Runtime Canvas component tests cover mount and update payloads.
* [ ] Runtime Canvas component tests cover compact-control enablement from the effective mode.
* [ ] Play view/client tests cover mobile auto and explicit override behavior.
* [ ] Focused Vitest and TypeScript checks pass for touched AI Rogue files.

### Non-Functional Requirements

* [ ] PixiJS and AI Rogue runtime imports remain lazy and route-local.
* [ ] No browser capability reads are added to schema, persistence, or save-state modules.
* [ ] 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 02 is complete and its utilities are the authoritative input-mode foundation. Evidence: the analyzer lists `phase32-session02-preference-contract` as completed, and `src/extensions/ai-rogue/input-mode.ts` exports raw/effective types, the pure resolver, and `useAiRogueInputModeCapabilities()`. Planning can proceed because Session 03 only wires these existing utilities through mounted Play and Runtime Canvas code.
* `PlayView` is the correct mounted browser boundary for effective-mode resolution. Evidence: the PRD says the phase resolves `auto` at the mounted browser UI boundary, and `play-view.tsx` already owns `useAiRogueSaveState()` and passes `preferences` into `AiRogueRuntimeCanvas`. Planning can proceed because this keeps schema and runtime modules free of browser global reads.

### Conflict Resolutions

* Session 02 implementation already added a `resolveRuntimeInputMode(...)` adapter inside `runtime-canvas.tsx` that resolves `auto` with null capabilities, while Phase 32 requires mobile auto to become compact when the mounted browser reports coarse pointer and no hover. The Phase 32 PRD and Session 03 stub win: replace the null-capability adapter at the runtime boundary with an explicit `effectiveInputMode` prop derived in Play.

### Key Considerations

* Do not change Settings segmented controls or visible Auto copy in this session; Session 04 owns that product copy.
* Keep diagnostics inside tests or spec artifacts, not visible product UI.
* Preserve existing seed replay, save/load, runtime cleanup, and lazy import behavior while changing input-mode plumbing.

### Potential Challenges

* Capability change after mount may not remount the runtime. Mitigation: include `effectiveInputMode` in the preference-update effect dependencies so an already mounted controller receives the new concrete mode.
* Raw preference and effective mode can diverge by design. Mitigation: name the prop `effectiveInputMode`, keep raw preference use durable-only, and test both explicit overrides and raw auto resolution.

### 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, 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:

* Mounted capability changes do not reach an already mounted runtime.
* Raw `auto` leaks into runtime mount/update payloads and disables mobile input.
* Compact controls enable from raw preference instead of effective mode, causing explicit override regressions.

***

## 9. Testing Strategy

### Unit Tests

* Extend `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` to assert mount and update payloads contain concrete `inputMode` values.
* Extend `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` to assert compact controls follow `effectiveInputMode`.

### Integration Tests

* Extend `src/extensions/ai-rogue/__tests__/client.test.tsx` to render Play with mocked media queries and raw `auto`, then assert the Runtime Canvas surface behaves as effective compact on mobile capability and effective keyboard on desktop or explicit keyboard.

### Runtime Verification

* Run focused Vitest coverage for input-mode, Runtime Canvas, and AI Rogue client tests.
* Run TypeScript typecheck to prove runtime-facing types reject raw `auto`.

### Edge Cases

* Raw `auto` plus unavailable media APIs falls back to keyboard.
* Explicit `keyboard` wins over mobile capability.
* Explicit `compact` wins over desktop capability.
* Media query changes after mount trigger runtime preference update without a Pixi remount.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase32-session01-baseline-validation`, `phase32-session02-preference-contract`
* Depended by: `phase32-session04-settings-and-copy`, `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-session03-effective-mode-wiring/spec.md?ask=<question>&goal=<endgoal>
```

`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.