> 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/phase34-session02-accessibility-and-compact-input/spec.md). # Session Specification **Session ID**: `phase34-session02-accessibility-and-compact-input` **Phase**: 34 - AI Rogue Audit Remediation **Status**: Not Started **Created**: 2026-06-26 *** ## 1. Session Overview This session fixes the AI Rogue Play accessibility and compact-input blocker set from the Phase 34 audit. It surfaces the existing rich render summary to assistive technology, gives compact/touch users access to Inspect and Next target verbs, and makes the persisted Large HUD Labels preference produce a real runtime effect. It is next because Phase 34 Session 01 completed the prerequisite characterization coverage for dynamic runtime summary exposure and related AI Rogue remediation seams. The work advances the phase's default-enablement remediation without changing default enablement, adding new gameplay verbs, or weakening the static public-demo/browser-local boundary. The implementation should stay focused on existing Play route, runtime bridge, render-model, and tests. Any debug-only proof remains in tests or hidden runtime event surfaces, not in product-facing UI copy. *** ## 2. Objectives 1. Expose `createAiRogueRenderModel(...).summary` through a stable assistive DOM surface that updates after meaningful runtime changes. 2. Add compact/touch controls for `inspect` and `target-next` using existing runtime command dispatch. 3. Thread `largeHudLabels` from persisted preferences into runtime render preferences and make HUD projection visibly larger or more readable with tests. 4. Update focused unit and mobile/browser coverage proving the accessibility, compact command, and Large HUD behavior. *** ## 3. Prerequisites ### Required Sessions * [x] `phase34-session01-characterization-test-harness` - Provides baseline coverage for mounted runtime summary exposure, AI Rogue focused test health, and remediation seams. ### Required Tools Or Knowledge * React 19, TypeScript, Tailwind CSS 4, PixiJS v8 runtime, Vitest, and Playwright. * Existing AI Rogue runtime command contract in `src/extensions/ai-rogue/runtime/types.ts`. * Existing render projection contract in `src/extensions/ai-rogue/runtime/render-model.ts`. ### Environment Requirements * Bun 1.3.14 project tooling. * Local browser-capable Playwright setup for AI Rogue e2e checks when feasible. * No remote services, hosted writes, collectors, or generated private runtime data are required. *** ## 4. Scope ### In Scope (MVP) * AI Rogue Play users using assistive technology can read the current runtime summary from the mounted Play surface - expose `renderModel.summary` through a visually hidden `aria-live`/`aria-describedby` style surface in `runtime-canvas.tsx`. * Compact/touch users can trigger Inspect and Next target - add controls that dispatch the existing `inspect` and `target-next` commands through `AiRogueRuntimeController.dispatchCommand`. * AI Rogue users who enable Large HUD Labels get an implemented runtime effect - pass `largeHudLabels` into mount/update preferences and make render-model HUD projection account for it. * AI Rogue tests cover the changed accessibility bridge, compact verbs, render preference projection, and mobile compact path. * Public-demo AI Rogue remains static/browser-local and does not call `/__*` bridge routes, hosted writes, collectors, analytics, or Functions. ### Out Of Scope (Deferred) * Default enablement - Reason: Phase 34 closeout makes the renewed recommendation after all blockers and gates are complete. * Visual redesign of the AI Rogue Play surface - Reason: the audit scope is accessibility/input remediation, not a new layout. * New gameplay verbs, balance changes, enemies, floors, or content - Reason: compact controls should expose existing commands only. * Simulation correctness and `scenario=combat` production gating - Reason: assigned to Session 03. * Renderer lifecycle, resize coalescing, reduced-motion media-query fallback, and audio fallback hardening - Reason: assigned to Sessions 04 and 07. *** ## 5. Technical Approach ### Architecture Use the existing runtime event bridge instead of making React parse canvas internals. Extend `AiRogueRuntimeFrameEvent` or a narrow runtime event payload to carry the current render summary from `renderer.ts` to `runtime-canvas.tsx`; keep the renderer as the owner of Pixi canvas rendering and React as the owner of DOM accessibility surfaces. Store the latest summary in React state and render it in a visually hidden live region referenced from the runtime section or host wrapper. Extend the existing compact control arrays in `runtime-canvas.tsx` to include `inspect` and `target-next`. These commands already exist in `AiRogueInputCommand`, keyboard mappings, and controller dispatch, so the UI should call the same `dispatchCommand(command, "touch")` path and update the hidden event summary consistently. Add `largeHudLabels?: boolean` to runtime mount and render preferences. `runtime-canvas.tsx` should pass it on initial mount and preference updates; `renderer.ts` should include it in `renderPreferences`; `render-model.ts` should use it to produce a measurable HUD projection difference without overlapping canvas content. ### Design Patterns * Runtime bridge event: Keeps Pixi/browser resource ownership in the runtime while exposing browser-readable state to React. * Existing command dispatch: Reuses `dispatchCommand` for compact verbs instead of adding separate action handlers. * Schema-backed preference threading: Preserves the existing `largeHudLabels` durable preference and adds behavior at the render boundary. * Focused regression tests: Update colocated AI Rogue unit tests and existing mobile e2e coverage without introducing new dependencies. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase34-session02-accessibility-and-compact-input/implementation-notes.md` | Session implementation notes and command evidence populated during `implement`. | \~120 | ### Files To Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/ai-rogue/runtime/types.ts` | Extend runtime event and preference types for assistive summary and Large HUD state. | \~20 | | `src/extensions/ai-rogue/runtime/renderer.ts` | Emit current render summary through the runtime bridge and include Large HUD in render preferences. | \~40 | | `src/extensions/ai-rogue/runtime/render-model.ts` | Add Large HUD render preference handling and measurable HUD projection differences. | \~70 | | `src/extensions/ai-rogue/views/runtime-canvas.tsx` | Store/render assistive summary, wire `largeHudLabels`, and add Inspect/Next target compact controls. | \~140 | | `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | Cover Large HUD projection and summary behavior. | \~40 | | `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` | Cover dynamic assistive summary exposure and compact Inspect/Next target dispatch. | \~90 | | `tests/e2e/ai-rogue-mobile.spec.ts` | Cover mobile compact Inspect/Next target reachability and accessible summary update where stable. | \~45 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Cover desktop Play accessible summary or runtime bridge smoke when useful. | \~35 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The Play surface exposes a screen-reader-visible runtime summary that changes after movement or another meaningful turn update. * [ ] Compact/touch mode exposes Inspect and Next target controls or an equally reachable touch interaction using existing commands. * [ ] Large HUD Labels has a visible, tested runtime effect in HUD projection or is not advertised as an active preference. * [ ] AI Rogue remains browser-local in public-demo mode with no new bridge or hosted write path. ### Testing Requirements * [ ] Unit tests written and passing for runtime summary bridge behavior. * [ ] Unit tests written and passing for compact `inspect` and `target-next` dispatch. * [ ] Unit tests written and passing for Large HUD render preference behavior. * [ ] Mobile or browser smoke coverage updated for compact control reachability. ### Non-Functional Requirements * [ ] No new dependencies, assets, remote loading, or collector behavior. * [ ] Runtime accessibility state updates are bounded to meaningful runtime events and do not add React hot-loop churn. * [ ] Compact control layout remains usable without horizontal overflow on 390px mobile viewport. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. * [ ] `bun run test -- src/extensions/ai-rogue` passes or exact blockers are recorded. * [ ] `bun run typecheck`, `bun run lint`, and `bun run format:check` pass or exact blockers are recorded. *** ## 8. Implementation Notes ### Working Assumptions * The session should implement Large HUD behavior rather than remove the preference: `largeHudLabels` is already persisted in `save-schema.ts`, exposed in `settings-view.tsx`, and echoed in `loadout-view.tsx`, so threading it into runtime preferences is less disruptive than a preference removal/migration. * The runtime summary should flow through renderer events rather than direct DOM mutation inside Pixi code: `renderer.ts` already owns `state.renderModel`, while `runtime-canvas.tsx` owns React DOM, control state, and live regions. ### Key Considerations * Keep the Play route a product surface. Any diagnostic proof belongs in hidden test surfaces, tests, or implementation notes. * Avoid exposing private/generated runtime data. The render summary is derived from browser-local simulation state and existing render preferences. * Preserve explicit opt-in posture and the Phase 34 rule that this session does not flip default enablement. ### Potential Challenges * Summary update frequency: Emit or store summaries on meaningful frame/gameplay points so React does not re-render every animation tick. * HUD layout overlap: Large HUD should change projection dimensions or spacing with bounded coordinates and tests, not only labels in settings. * Compact controls on narrow screens: Add controls without forcing horizontal overflow; prefer wrapping action controls with stable button sizes. ### Relevant Considerations * \[P30/P32] **AI Rogue default enablement deferred**: This session closes accessibility/input blockers but does not make the extension default-enabled. * \[P31-P33] **Pages demo stays static-only**: Public-demo behavior must remain browser-local with no bridge calls, hosted writes, collectors, analytics, Functions, or advanced Workers. * \[P30/P32] **Route-lazy runtime ownership scales**: Pixi stays behind the Play route/runtime facade; React owns DOM accessibility surfaces and coarse state. * \[P30/P32] **PixiJS v8 route and input tests**: Use browser/mobile tests for real input reachability and route cleanup where feasible. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Assistive summary becomes stale or updates too often, so tasks must use scoped state updates tied to meaningful runtime events. * Compact command buttons can double-trigger or dispatch while the runtime is not active, so tasks must preserve disabled-state and in-flight guards. * Large HUD projection can overlap or resize unstable canvas elements, so tasks must include bounded layout and deterministic render-model assertions. *** ## 9. Testing Strategy ### Unit Tests * `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx`: prove the assistive summary appears, updates after a gameplay event, cleans up on unmount, and compact Inspect/Next target buttons dispatch existing commands only when enabled. * `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts`: prove `largeHudLabels` changes HUD projection or descriptor output in a deterministic, bounded way. ### Integration Tests * `tests/e2e/ai-rogue-mobile.spec.ts`: prove compact mobile controls include Inspect and Next target and remain in frame after runtime start. * `tests/e2e/ai-rogue-runtime.spec.ts`: add or adjust a Play runtime smoke proving the accessible summary is present and changes after movement if stable in Chromium. ### Runtime Verification * Run focused AI Rogue unit tests with `bun run test -- src/extensions/ai-rogue`. * Run AI Rogue Play browser tests with `bunx playwright test tests/e2e/ai-rogue-mobile.spec.ts tests/e2e/ai-rogue-runtime.spec.ts` when local browsers are available. * Run `bun run typecheck`, `bun run lint`, and `bun run format:check`. ### Edge Cases * Runtime unavailable, loading, paused, hidden, destroyed, and error states should not announce stale active-run summaries as current state. * Compact controls remain disabled in keyboard mode, before Start, while busy, and after terminal/compile blocking states where command dispatch is unavailable. * Large HUD remains bounded at 640x360 render-model viewport and 390px mobile Play layout. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase34-session01-characterization-test-harness` * Depended by: `phase34-session07-render-performance-and-audio-docs`, `phase34-session08-default-enablement-evidence-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/phase34-session02-accessibility-and-compact-input/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.