> 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/phase35-session03-runtime-accessibility-controls/spec.md). # Session Specification **Session ID**: `phase35-session03-runtime-accessibility-controls` **Phase**: 35 - AI Rogue Audit Hardening And Refactor **Status**: Not Started **Created**: 2026-06-26 *** ## 1. Session Overview This session finishes the Phase 35 accessibility and compact-control pass for AI Rogue after the rebaseline and fixed-blocker regression sessions. Sessions 01 and 02 record that the original dynamic summary, compact Inspect and Next target, and Large HUD blocker families are currently fixed, so this session is verify-or-add: preserve the current runtime behavior, add positive missing coverage where the audit still asks for it, and repair only concrete gaps found by those checks. The work is next because the current phase has no active session, Sessions 01 and 02 are complete, and Session 03 is the first unfinished Phase 35 stub. It advances the phase by turning the remaining AR-D6 and AR-D8 accessibility routing into durable implementation evidence before renderer, persistence, and ownership refactors begin. Implementation should stay inside the existing AI Rogue Play, Settings, runtime bridge, render-model, and mobile test surfaces. It must preserve the production default, browser-local state, static Pages demo boundary, and test-only deterministic runtime hooks. *** ## 2. Objectives 1. Verify and preserve a dynamic screen-reader runtime summary on the Play surface that updates with current run state. 2. Verify and preserve compact or touch controls for Inspect and Next target through the existing runtime command union. 3. Prove the Large HUD Labels preference has a bounded visible runtime effect from persistence through renderer output, or remove/disable it if evidence shows it is unsupported. 4. Extend positive unit and mobile coverage for compact Inspect, target cycling, Large HUD behavior, and no-overflow AI Rogue mobile routes. *** ## 3. Prerequisites ### Required Sessions * [x] `phase35-session01-rebaseline-audit-evidence` - Provides the current finding ledger, fixed-versus-live classification, and downstream routing for accessibility/control work. * [x] `phase35-session02-fixed-blocker-regression-coverage` - Confirms direct regression anchors for dynamic assistive summaries and fixed blocker behavior before this positive-coverage pass. * [x] `phase34-session02-accessibility-and-compact-input` - Provides the original implementation of assistive summaries, compact Inspect/Next target controls, and Large HUD render projection. ### Required Tools Or Knowledge * Bun 1.3.14 for Vitest, typecheck, lint, and scripts. * Playwright Chromium for mobile AI Rogue route checks. * React 19, Tailwind CSS 4, PixiJS v8, and the AI Rogue runtime bridge. * Current AI Rogue preference, render-model, renderer, and mobile test patterns. ### Environment Requirements * Local dependencies installed from `bun.lock`. * Playwright browser binaries available for focused Chromium tests. * `src/data/live-data.json` can be seeded by `bun run seed:data` if absent. *** ## 4. Scope ### In Scope (MVP) * AI Rogue Play users using assistive technology can receive current runtime state from the mounted Play surface - verify or repair the `data-ai-rogue-assistive-summary` region and `aria-describedby` bridge in `runtime-canvas.tsx`. * Compact and touch users can trigger Inspect and Next target - verify or repair the compact action buttons that dispatch `inspect` and `target-next` through `dispatchCommand(command, "touch")`. * AI Rogue users who enable Large HUD Labels get a visible bounded runtime effect - verify persistence, Settings UI, runtime mount/update propagation, render-model projection, renderer state, and mobile layout behavior. * AI Rogue mobile users can visit Play, Ledger, Loadout, and Settings without document-level horizontal overflow or accidental bridge requests. * AI Rogue tests provide positive evidence for compact Inspect, target cycling, Large HUD, dynamic summary freshness, and keyboard behavior preservation. ### Out Of Scope (Deferred) * Adding new gameplay commands beyond the existing runtime command union - Reason: compact controls should expose existing actions only. * Redesigning the full AI Rogue Play, Ledger, Loadout, or Settings surfaces - Reason: this session is an accessibility/control hardening pass. * Renderer scheduling, matchMedia, WebGL/Pixi, asset-load, audio, and dispose fallback work - Reason: assigned to Session 04. * Persistence schema, wallet, ledger, save-slot, storage-quota, and reset contract changes - Reason: assigned to Session 05 unless required for the Large HUD preference path. * Runtime, simulation, renderer, React bridge, world, and type module splits - Reason: assigned to Sessions 06-08 after this behavior is protected. * Documentation/media-policy cleanup and final release gate matrix - Reason: assigned to Sessions 09-10. * Hosted writes, collectors, analytics, remote game-content loading, Pages Functions, WebGPU-only behavior, workers, or expanded game content - Reason: requires fresh review and is outside this session. *** ## 5. Technical Approach ### Architecture Start with the existing behavior owners. React owns the DOM accessibility surface and compact controls in `runtime-canvas.tsx`. The save-state and Settings route own persisted preferences and user controls. The renderer owns Pixi canvas output and event summaries, while `render-model.ts` owns pure HUD projection and bounds. Tests should stay beside those owners: RuntimeCanvas and Settings component coverage under `src/extensions/ai-rogue/__tests__/`, projection coverage under `runtime/__tests__/`, and browser/mobile proof under `tests/e2e/ai-rogue-mobile.spec.ts`. Run focused tests before source edits. If current code already satisfies a contract, add evidence and any missing positive assertions without rewriting the feature. If a test exposes unsupported Large HUD behavior, prefer the smallest repair in the preference-to-render path; remove or disable the setting only if bounded runtime support cannot be made true inside this session scope. ### Design Patterns * Verify-or-add hardening: preserve proven Phase 34 behavior and add only missing positive coverage or narrow repairs. * Behavior-owned tests: place assertions next to the UI, runtime, or projection owner they protect. * Existing command union: use `inspect` and `target-next`; do not introduce new gameplay commands. * Product-surface discipline: keep diagnostics in tests or hidden evidence nodes, not primary user-facing copy. * Browser-local boundary: preference and gameplay state stay in local browser-owned storage and committed runtime assets. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase35-session03-runtime-accessibility-controls/implementation-notes.md` | Evidence ledger for accessibility, compact controls, Large HUD, commands, routes | \~260 | ### Files To Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/ai-rogue/views/runtime-canvas.tsx` | Repair only if summary freshness, compact command dispatch, disabled states, or cleanup fail | \~20 | | `src/extensions/ai-rogue/views/settings-view.tsx` | Repair only if Large HUD setting persistence, disabled state, labels, or focus behavior fail | \~20 | | `src/extensions/ai-rogue/runtime/render-model.ts` | Repair only if Large HUD projection is not visibly bounded or deterministic | \~25 | | `src/extensions/ai-rogue/runtime/renderer.ts` | Repair only if runtime preferences or render-summary events fail to reflect Large HUD changes | \~25 | | `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` | Add or refine assistive summary, compact Inspect, target-next, in-flight, and cleanup coverage | \~70 | | `src/extensions/ai-rogue/__tests__/client.test.tsx` | Add or refine Settings Large HUD persistence and product-copy coverage | \~45 | | `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | Add or refine bounded Large HUD projection and summary assertions | \~35 | | `tests/e2e/ai-rogue-mobile.spec.ts` | Add mobile Large HUD, compact Inspect/Next, route no-overflow, and keyboard preservation proof | \~90 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The Play surface exposes a current runtime summary through an associated DOM region that updates after runtime movement and clears on unavailable, reset, load, error, and unmount paths. * [ ] Compact or touch controls dispatch Inspect and Next target through the existing runtime command path, with duplicate-trigger prevention while commands are in-flight. * [ ] Keyboard users retain existing Inspect and target cycling behavior. * [ ] Large HUD Labels either changes bounded runtime layout from persisted Settings state through renderer output or is removed/disabled from settings and persistence-facing UI. * [ ] Mobile Play, Ledger, Loadout, and Settings route checks pass without document-level horizontal overflow or public-demo bridge regressions. ### Testing Requirements * [ ] RuntimeCanvas focused unit tests pass. * [ ] Settings or client focused unit tests pass. * [ ] Render-model focused unit tests pass. * [ ] AI Rogue mobile Playwright coverage passes. * [ ] Typecheck and lint pass after any source or test changes. ### Non-Functional Requirements * [ ] No new hosted write, collector, analytics, remote-loading, worker, WebGPU-only, or public-demo bridge surface is introduced. * [ ] No new dependency, large media asset, or bundle-budget risk is introduced. * [ ] User-facing UI copy remains product-facing; diagnostics remain in tests or hidden evidence surfaces. ### 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 a verify-or-add session, not a broad rewrite: Session 01 classifies AR-D6-001, AR-D6-002, AR-D6-003, and AR-D8-003 as fixed, and Session 02 records dynamic assistive summary coverage as present. It is safe to proceed because the current repo has existing RuntimeCanvas, render-model, and mobile test anchors for these behaviors. * Large HUD Labels should remain exposed unless implementation evidence proves it unsupported: `settings-view.tsx` exposes the preference, `runtime-canvas.tsx` passes it to mount/update preferences, `renderer.ts` tracks it, and `render-model.test.ts` already asserts bounded projection. It is safe to plan positive coverage before considering removal. * This is not a monorepo session: the analysis script reported no monorepo detection, no packages, and no active package. Repo-root-relative paths are sufficient. ### Conflict Resolutions * The Session 03 stub describes remaining accessibility gaps, while completed Session 01 and Session 02 evidence says the same blocker families are fixed with existing coverage. The chosen interpretation is to preserve current Production Go and run Session 03 as positive verification plus targeted coverage, adding source repairs only for concrete failing evidence. This wins because the completed prerequisite artifacts are newer and explicitly route Session 03 to verify and preserve compact Inspect/Next controls, dynamic summaries, Large HUD projection, and mobile no-overflow behavior. * The master PRD still contains Phase 34 historical Session 02 accessibility wording, while Phase 35 names this work as Session 03. The chosen interpretation is to follow Phase 35 state and stubs. This wins because the analysis script reports current Phase 35 with Sessions 01 and 02 complete and Session 03 as the first unfinished candidate. ### Key Considerations * Keep AI Rogue production-enabled by default and preserve `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` as the explicit disable path. * Keep AI Rogue browser-local and static-demo safe. * Keep Pages and AI Rogue release gates bundled in later final validation. * Do not expose deterministic fixtures through product routes. ### Potential Challenges * Mobile Playwright runtime checks can be slower than unit tests: keep new browser assertions focused on positive user paths and reuse existing helpers. * Large HUD visual proof can be brittle if it depends on exact pixels: assert bounded layout, rendered summary, enabled preference state, and no overflow instead of fragile screenshots. * Compact command tests can overfit internal state: assert user-visible button state and controller dispatch contract where possible. ### Relevant Considerations * \[P34] **AI Rogue is production default-enabled**: Preserve the default and explicit `none` opt-out while hardening accessibility and controls. * \[P31-P34] **Pages and AI Rogue CI guards deferred**: Keep route smoke, no-bridge checks, and gameplay validation bundled for later gates. * \[P30/P32/P34] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade; React owns DOM accessibility and mounted imports. * \[P30/P34] **Visibility gates catch real issues**: Pair focused unit/browser tests with type, lint, privacy, and no-bridge evidence. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Assistive summaries can become stale across reset, load, error, unavailable, and unmount paths. * Compact touch controls can double-fire while an async command is in-flight or become reachable in keyboard-only mode. * Large HUD can overflow mobile layouts or appear in Settings without a real runtime effect. *** ## 9. Testing Strategy ### Unit Tests * `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx`: assistive summary freshness and cleanup; compact Inspect and Next target enabled, disabled, and in-flight behavior; keyboard-mode preservation. * `src/extensions/ai-rogue/__tests__/client.test.tsx`: Settings Large HUD persistence and visible product labels. * `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts`: bounded Large HUD projection, deterministic summary text, and no out-of-bounds HUD sprites. ### Integration Tests * `tests/e2e/ai-rogue-mobile.spec.ts`: mobile Play compact controls, Large HUD preference from storage to rendered summary, Play/Ledger/Loadout/Settings no-overflow route checks, and keyboard override preservation. ### Runtime Verification * Run focused Vitest tests for RuntimeCanvas, Settings/client, and render-model behavior. * Run focused Playwright mobile AI Rogue checks in Chromium. * Run `bun run typecheck` and `bun run lint` after source or test edits. ### Edge Cases * Runtime starts unavailable, loading, offline, ready, running, error, reset, load, and unmount. * Compact command buttons are clicked while disabled or while a command is already in-flight. * Settings persistence is busy, denied, unavailable, or optimistic save fails. * Large HUD is enabled on a narrow mobile viewport with compact controls visible. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase35-session01-rebaseline-audit-evidence`, `phase35-session02-fixed-blocker-regression-coverage`, `phase34-session02-accessibility-and-compact-input` * Depended by: `phase35-session04-renderer-robustness-and-scheduling`, `phase35-session07-renderer-and-react-bridge-refactor`, `phase35-session10-final-release-gate` *** ## 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/phase35-session03-runtime-accessibility-controls/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.