> 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-session05-gameplay-test-coverage/spec.md). # Session Specification **Session ID**: `phase32-session05-gameplay-test-coverage` **Phase**: 32 - AI Rogue Mobile Input Auto-Detect **Status**: Not Started **Created**: 2026-06-25 *** ## 1. Session Overview This session locks Phase 32 into automated coverage by proving the first-run AI Rogue Play path works on mobile when no `ai-os.ai-rogue.preferences.v1` record exists. Sessions 02-04 added the raw `auto` preference, concrete effective runtime mode wiring, and product copy; the remaining risk is that tests still prove compact controls mostly through seeded compact preferences or desktop contexts. The work is next because Phase 32 succeeds only when fresh mobile/coarse-pointer sessions can press Start and move on the first run, fresh desktop sessions stay keyboard-first, explicit Keyboard and Compact preferences still override Auto, and public-demo mobile smoke exercises gameplay without local bridge requests. The plan updates focused unit, component, Playwright, and Pages demo tests around those exact boundaries. The session stays inside AI Rogue and public-demo test coverage. It does not add new gameplay content, new settings surfaces, new hosted behavior, or CI wiring for the full public-demo lane. *** ## 2. Objectives 1. Prove the raw `auto` preference default and migration behavior across schema, persistence, save-state, client, and Runtime Canvas tests. 2. Add true mobile/touch Playwright coverage for a fresh AI Rogue Play session with no seeded preferences. 3. Add desktop/fine-pointer Playwright coverage proving Auto remains keyboard-first while explicit Keyboard and Compact choices override Auto. 4. Extend public-demo mobile smoke so `/extensions/ai-rogue/play` starts and advances gameplay without any `/__*` local bridge requests. *** ## 3. Prerequisites ### Required Sessions * [x] `phase32-session01-baseline-validation` - Validated the reported first-run mobile failure and the browser capability signal. * [x] `phase32-session02-preference-contract` - Added durable raw Auto preferences, effective input-mode types, resolver, schema defaults, and migration tests. * [x] `phase32-session03-effective-mode-wiring` - Routed a concrete effective mode through Play and Runtime Canvas without passing raw Auto to runtime APIs. * [x] `phase32-session04-settings-and-copy` - Aligned Settings, Loadout, Play, and Runtime Canvas copy with raw and effective input modes. ### Required Tools Or Knowledge * AI Rogue schema, persistence, save-state, input-mode, client, and Runtime Canvas test patterns under `src/extensions/ai-rogue/__tests__/`. * AI Rogue Playwright helpers in `tests/e2e/ai-rogue-mobile.spec.ts` and `tests/e2e/ai-rogue-runtime.spec.ts`. * Public-demo route smoke patterns in `tests/e2e/pages-demo-mobile.spec.ts` and `scripts/lib/pages-demo-routes.ts`. ### Environment Requirements * Bun 1.3.14 with the existing repo scripts. * Playwright Chromium with mobile context options available. * Local Vite and public-demo Playwright web servers from `playwright.config.ts`. *** ## 4. Scope ### In Scope (MVP) * AI Rogue player starts a fresh mobile/touch Play session with no stored preferences and can move from turn 0 to a later turn. * AI Rogue desktop/fine-pointer Auto defaults to keyboard-first behavior and does not enable compact controls by default. * AI Rogue explicit Keyboard and explicit Compact preferences override Auto in unit, component, and browser coverage. * AI Rogue runtime tests prove raw Auto is never passed to runtime-facing APIs. * Public-demo mobile route smoke starts AI Rogue gameplay and sends a first move on `/extensions/ai-rogue/play`. * Public-demo route smoke continues to fail on any `/__*` local bridge request. * Focused AI Rogue Vitest, Playwright, typecheck, and public-demo smoke gates run locally. ### Out Of Scope (Deferred) * Full repo release closeout - Reason: this is a Phase 32 test-coverage session, not the phase transition audit. * CI pipeline wiring for every public-demo command - Reason: P31 keeps Pages demo CI guard expansion as a separate deferred concern. * Real-device automation - Reason: Playwright mobile/touch context is the available automated gate; residual real-device risk belongs in validation notes. * New gameplay content, input devices, or renderer refactors - Reason: Phase 32 is limited to the existing Auto, Keyboard, and Compact input contract. * Default AI Rogue extension enablement - Reason: P30 keeps AI Rogue explicit opt-in until a separate product decision and fresh gate evidence. *** ## 5. Technical Approach ### Architecture Keep browser capability resolution at mounted UI and Playwright boundaries. Unit and component tests should assert the raw `auto` default in schema, persistence, and save-state layers, then assert concrete `keyboard | compact` runtime payloads inside Runtime Canvas. Browser tests should exercise the real Play route through public controls, not private runtime APIs, and should verify movement through turn or event text in addition to canvas pixel changes. Use Playwright context options for true mobile/touch coverage instead of viewport resize alone. The fresh mobile case should remove or avoid seeding `ai-os.ai-rogue.preferences.v1`, assert coarse/no-hover or touch capability evidence, press Start, issue a compact move control, and assert gameplay advancement. The desktop case should use the default fine-pointer project, assert Auto resolves to Keyboard, keep compact controls disabled, and prove keyboard movement still advances. Public-demo smoke should reuse the existing route request recorder and route matrix. Add AI Rogue-specific gameplay interaction after the Play surface is visible so no-bridge assertions include gameplay, not only route render. ### Design Patterns * Behavior-first tests: Assert player-visible labels, events, turn advancement, and bridge absence rather than implementation details alone. * Boundary checks: Schema and save-state keep raw Auto; Runtime Canvas and Pixi runtime receive only concrete effective modes. * Static demo safety: Public demo tests operate against the public-demo base URL and preserve the `/__*` request failure contract. * Focused gates: Run only AI Rogue and Pages smoke checks needed to validate this session before wider audit work. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---- | --------------------------------------------------------- | ---------- | | None | Existing test files cover the required behavior surfaces. | 0 | ### Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `src/extensions/ai-rogue/__tests__/save-schema.test.ts` | Extend default, migration, malformed, and explicit override assertions for raw Auto. | \~35 | | `src/extensions/ai-rogue/__tests__/persistence.test.ts` | Extend preference read/write recovery tests for Auto defaults and explicit overrides. | \~30 | | `src/extensions/ai-rogue/__tests__/use-save-state.test.tsx` | Extend save-state tests for empty Auto defaults and raw Auto save cycles. | \~35 | | `src/extensions/ai-rogue/__tests__/client.test.tsx` | Update fixtures and component assertions for Auto defaults, mobile resolution, and desktop | \~120 | | `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` | Extend runtime boundary tests proving raw Auto becomes concrete runtime preferences. | \~55 | | `tests/e2e/ai-rogue-mobile.spec.ts` | Add true mobile/touch fresh-state Start plus first-move coverage with gameplay proof. | \~120 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Add desktop/fine-pointer Auto keyboard-first and explicit override browser coverage. | \~90 | | `tests/e2e/pages-demo-mobile.spec.ts` | Add AI Rogue Play gameplay interaction to public-demo mobile route smoke. | \~100 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Fresh mobile/touch Auto can Start and advance AI Rogue gameplay from turn 0 to a later turn. * [ ] Fresh desktop/fine-pointer Auto resolves keyboard-first and does not enable compact controls by default. * [ ] Explicit Keyboard and explicit Compact preferences override Auto on tested contexts. * [ ] Runtime-facing mount and update payloads never contain raw `"auto"`. * [ ] Public-demo mobile smoke exercises AI Rogue Start plus first move. * [ ] Public-demo mobile smoke records no `/__*` local bridge requests. ### Testing Requirements * [ ] Schema, persistence, and save-state tests cover Auto defaults, migration, malformed fallback, partial writes, and explicit overrides. * [ ] Client and Runtime Canvas component tests cover raw/effective labels, concrete runtime payloads, disabled compact controls, and explicit overrides. * [ ] AI Rogue Playwright tests use a true mobile/touch context for fresh mobile coverage. * [ ] AI Rogue Playwright tests assert turn advancement or event text after move input, not only canvas pixel signatures. * [ ] Pages demo mobile Playwright tests cover `/extensions/ai-rogue/play` gameplay and no-bridge behavior. ### Non-Functional Requirements * [ ] Tests remain deterministic under the existing one-worker Playwright config. * [ ] Public-demo tests stay static-only and do not introduce hosted writes, collectors, analytics, bridge calls, or remote loading. * [ ] AI Rogue remains explicit opt-in and browser-local. * [ ] Real-device residual risk is captured in validation notes if Playwright mobile context is the only automated device proof. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. * [ ] No debug UI, diagnostics route, or test-only product copy is added. *** ## 8. Implementation Notes ### Working Assumptions * Existing Session 02-04 work is the implementation baseline for this coverage session. Evidence: the analyzer reports all three sessions completed, and the current code already exposes raw `auto` schema defaults, an input-mode resolver, Play-level effective mode, and Runtime Canvas concrete mode tests. Planning can proceed because Session 05 is a coverage closeout over those shipped boundaries. * `seedConfiguredState(page)` does not seed AI Rogue preferences. Evidence: `tests/e2e/fixtures/live-data.ts` only sets host setup keys and removes setup draft keys; `tests/e2e/ai-rogue-mobile.spec.ts` separately seeds `ai-os.ai-rogue.preferences.v1`. Planning can proceed by omitting that separate AI Rogue preference seed in fresh-state tests. * Public-demo mobile route smoke can be extended in place. Evidence: `playwright.config.ts` already runs `pages-demo-mobile.spec.ts` against the public-demo base URL, and `pages-demo-mobile.spec.ts` already records `/__*` requests through the route visit. Planning can proceed by adding AI Rogue-specific gameplay interaction before the no-bridge assertion. ### Conflict Resolutions * Existing `ai-rogue-mobile.spec.ts` uses a mobile viewport and seeded Compact preferences, while the Phase 32 PRD and Session 05 stub require true mobile/touch fresh-state Auto coverage. The Phase 32 PRD and Session 05 stub win: keep seeded Compact as explicit override coverage, but add a separate true mobile/touch test with no AI Rogue preference key. * Existing Pages demo route smoke checks visibility and no-bridge behavior, while Session 05 requires gameplay input coverage. The chosen interpretation is to preserve the route matrix and add AI Rogue Play-specific Start plus move interaction inside the mobile smoke path. ### Key Considerations * P30 AI Rogue default enablement remains deferred; this session proves input defaults inside the explicit AI Rogue route only. * P31 Pages demo static-only and no-bridge boundaries stay active during public-demo gameplay smoke. * Pixel-signature checks are useful for renderer proof but are not enough for gameplay proof; event text or turn advancement must be asserted. ### Potential Challenges * Browser capability emulation can drift between Playwright versions. Mitigation: assert `matchMedia`, `navigator.maxTouchPoints`, and visible resolved-mode copy before relying on compact controls. * Gameplay movement can be delayed by pending runtime readiness. Mitigation: wait for runtime bridge and status readiness before pressing Start or move controls. * Public-demo smoke may take longer when it starts WebGL. Mitigation: scope the extra gameplay interaction only to the AI Rogue Play route and reuse existing late-request settling. ### Relevant Considerations * \[P30] **AI Rogue default enablement deferred**: Keep the tests scoped to the explicit AI Rogue route; do not widen extension visibility. * \[P31] **Pages demo CI guard deferred**: Run Pages demo build/scan/smoke locally where relevant, but do not add new CI workflow wiring. * \[P31] **Pages demo stays static-only**: Public-demo smoke must not request `/__*`, add Functions, read local runtime state, host collectors, or enable writes. * \[P30] **PixiJS v8 route tests**: Continue using painted canvas checks, runtime event checks, DOM rect checks, and cleanup-friendly route tests for canvas runtime behavior. *** ## 9. Testing Strategy ### Unit Tests * Run focused Vitest coverage for save schema, persistence, save state, client, input-mode, and Runtime Canvas behavior. * Verify raw Auto defaults, migrations, malformed fallbacks, partial writes, and explicit Keyboard/Compact overrides. ### Integration Tests * Run component tests that mount Play, Loadout, Settings, and Runtime Canvas with coarse/no-hover, fine/hover, and unavailable capability states. * Verify Runtime Canvas mount/update calls use concrete effective modes only. ### Runtime Verification * Run focused Playwright coverage for AI Rogue mobile and runtime specs. * Run public-demo mobile Playwright coverage for the Pages demo project. * Verify gameplay advancement through runtime event text or turn evidence after a move command. ### Edge Cases * Missing AI Rogue preferences key on first run. * Malformed preferences record falling back to Auto. * Explicit Keyboard preference on mobile/touch. * Explicit Compact preference on desktop/fine pointer. * Public-demo route gameplay without local bridge requests. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase32-session01-baseline-validation`, `phase32-session02-preference-contract`, `phase32-session03-effective-mode-wiring`, `phase32-session04-settings-and-copy` * Depended by: Phase 32 validation and update PRD closeout *** ## 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-session05-gameplay-test-coverage/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.