> 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/phase30-session09-content-polish-and-mobile/spec.md).

# Session Specification

**Session ID**: `phase30-session09-content-polish-and-mobile` **Phase**: 30 - AI Rogue Game Extension **Status**: Not Started **Created**: 2026-06-22

***

## 1. Session Overview

This session turns the playable AI Rogue slice into a better framed, pointer-friendly, mobile-tolerant game surface without expanding the privacy or runtime boundary. Sessions 07 and 08 already produced a playable PixiJS runtime, committed atlases, browser-local save state, progression loadout, and focused browser coverage. The next executable work is therefore polish: viewport framing, compact controls, seed sharing, stronger runtime feedback, and validation against the locked visual asset checklist.

This is next because Phase 30 Session 10 is the full quality-gate and enablement decision, and that gate depends on the Play route already behaving well across desktop and mobile viewports. The plan keeps audio as a settled no-audio decision for this session: no wrapper dependency and no Web Audio layer are added before a mute/autoplay/preference contract exists.

The session keeps the extension disabled-first and browser-local. It does not add collectors, remote loading, worker simulation, WebGPU, new third-party art, or raw private telemetry to the game.

***

## 2. Objectives

1. Add safe shareable seed handling for AI Rogue runs without exposing private data or unstable URLs.
2. Make compact pointer-first controls practical in the Play surface across desktop, tablet, and portrait mobile layouts.
3. Improve runtime feedback, reward/status presentation, and combat readability using the existing committed atlases and render descriptors.
4. Validate mobile framing, reduced-motion behavior, asset constraints, and no-audio scope with focused tests and documentation.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase30-session07-play-runtime-integration` - Provides the playable PixiJS runtime, committed art rendering, controls, save/load, and route cleanup baseline.
* [x] `phase30-session08-progression-depth` - Provides progression classes, relics, resources, achievements, run history, and current AI Rogue browser coverage.

### Required Tools Or Knowledge

* Bun 1.3.14 project scripts and focused Vitest/Playwright command patterns.
* PixiJS v8 WebGL runtime ownership through `src/extensions/ai-rogue/runtime/renderer.ts`.
* Existing AI Rogue save schemas, preferences, render descriptors, and route-scoped React view patterns.
* Locked AI Rogue art and mobile slot guidance from `docs/extensions/ai-rogue/visual-assets.md`.

### Environment Requirements

* Browser environment with WebGL readPixels support for Playwright runtime canvas checks.
* No new audio package or wrapper dependency.
* AI Rogue remains enabled in tests through existing configured-state e2e fixtures, not by changing default product posture.

***

## 4. Scope

### In Scope (MVP)

* Player can share or replay a bounded AI Rogue seed through the Play route - Implement URL/search-param parsing, copy/fallback feedback, and runtime remount behavior.
* Player can use compact pointer/touch controls on mobile and narrow desktop - Add accessible directional controls and pointer event handling that respect pause, reset, unavailable, and persistence busy states.
* Player can read run state, rewards, hazards, combat status, and progression feedback at smaller viewport sizes - Refine HUD descriptors, runtime panels, and reward icon usage without changing source art.
* Maintainer can verify locked art constraints and no-audio posture - Update docs and run asset-size, focused unit, focused e2e, private-runtime, and encoding checks.

### Out Of Scope (Deferred)

* New sound effects or music - Reason: Session 09 settles no-audio for this slice; a future audio session needs a mute/autoplay/preference contract before direct Web Audio work.
* Large asset packs, unreviewed third-party art, or generated content packs - Reason: Phase 30 locks compact committed atlases and media policy validation.
* Worker simulation, WebGPU verification, pointer lock, gamepad support, or remapping UI - Reason: Current focused evidence does not justify widening runtime ownership before Session 10 gates.
* New gameplay systems beyond readability and input polish - Reason: Session 10 should validate the accepted slice, not absorb new content risk.

***

## 5. Technical Approach

### Architecture

Keep all AI Rogue game runtime changes inside the existing static extension and lazy PixiJS runtime boundary. Add a small seed-share helper under `src/extensions/ai-rogue/` so URL parsing, normalization, private-looking input rejection, and share URL creation are tested outside React. Pass the resolved seed from `PlayView` through `AiRogueRuntimeCanvas` into `mountAiRogueRuntime`, remounting or resetting only when the selected seed materially changes.

Extend the existing runtime controller and renderer instead of adding another input subsystem. Pointer-first controls should call the same bounded command path as keyboard and canvas pointer input, and all commands must remain gated by runtime status. Mobile layout work should use stable CSS constraints in `play-view.tsx` and `runtime-canvas.tsx` so canvas, controls, event summaries, and side panels do not overlap or force horizontal scroll.

### Design Patterns

* Pure helper plus tests: Seed parsing and share URL creation stay deterministic and independently testable.
* Route-scoped runtime ownership: PixiJS listeners, pointer handlers, resize observers, and command dispatch stay owned by the mounted Play route and are cleaned on route exit.
* Existing preference schema: Compact input mode and accessibility toggles stay browser-local through existing AI Rogue persistence.
* Descriptor-driven rendering: Status and readability changes flow through render-model descriptors and renderer layers rather than ad hoc Pixi drawing branches.

***

## 6. Deliverables

### Files To Create

| File                                                      | Purpose                                                                                                                | Est. Lines |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/seed-share.ts`                   | Safe seed normalization, URL parsing, and share URL creation helpers.                                                  | \~130      |
| `src/extensions/ai-rogue/__tests__/seed-share.test.ts`    | Unit coverage for seed bounds, private-text rejection, URL round trips, and fallback behavior.                         | \~150      |
| `tests/e2e/ai-rogue-mobile.spec.ts`                       | Mobile and pointer-first Playwright coverage for portrait framing, compact controls, seed sharing, and reduced motion. | \~240      |
| `docs/extensions/ai-rogue/content-polish-mobile-notes.md` | Session 09 notes for mobile framing evidence, pointer controls, asset validation, and no-audio decision.               | \~120      |

### Files To Modify

| File                                                             | Changes                                                                                                             | Est. Lines |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/types.ts`                       | Add bounded controller command dispatch and seed/status metadata types.                                             | \~40       |
| `src/extensions/ai-rogue/runtime/input.ts`                       | Refine pointer command helpers for viewport origins, touch tolerances, and invalid geometry coverage.               | \~50       |
| `src/extensions/ai-rogue/runtime/render-model.ts`                | Improve HUD/readability descriptors for hazards, combat, rewards, input mode, and seed status.                      | \~90       |
| `src/extensions/ai-rogue/runtime/renderer.ts`                    | Wire seed-aware run creation, command dispatch, compact pointer behavior, and cleanup-safe pointer handling.        | \~120      |
| `src/extensions/ai-rogue/views/runtime-canvas.tsx`               | Add mobile control strip, seed/share status, stable responsive canvas framing, and guarded runtime command buttons. | \~180      |
| `src/extensions/ai-rogue/views/play-view.tsx`                    | Resolve seed from URL, surface share controls, pass seed into runtime, and tighten mobile panel order.              | \~120      |
| `src/extensions/ai-rogue/views/settings-view.tsx`                | Clarify compact input preference state and ensure touch-friendly controls remain accessible.                        | \~40       |
| `src/extensions/ai-rogue/views/reward-icon.tsx`                  | Reuse atlas icons for reward/status presentation without new media files.                                           | \~30       |
| `src/extensions/ai-rogue/runtime/__tests__/input.test.ts`        | Add pointer tolerance, compact mode, and invalid geometry cases.                                                    | \~80       |
| `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | Cover readable status/reward descriptors and input-mode summary text.                                               | \~70       |
| `src/extensions/ai-rogue/__tests__/client.test.tsx`              | Cover Play seed/share controls, compact setting, and no runtime mount when unavailable.                             | \~120      |
| `tests/e2e/ai-rogue-runtime.spec.ts`                             | Extend desktop runtime coverage for seed replay and pointer movement.                                               | \~80       |
| `docs/extensions/ai-rogue/visual-assets.md`                      | Record Session 09 validation outcome and unchanged atlas/provenance status.                                         | \~40       |
| `docs/extensions/ai-rogue/README.md`                             | Add the Session 09 polish notes to the AI Rogue document map.                                                       | \~20       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Play route accepts, normalizes, displays, copies, and replays a bounded seed without leaking private-looking text.
* [ ] Compact input mode exposes accessible touch/pointer controls that move the runtime only when the run is ready/running and not busy.
* [ ] Desktop and mobile Play layouts keep the canvas, controls, event summaries, and side panels visible without overlap or horizontal overflow.
* [ ] Runtime feedback makes combat, reward, hazard, seed, and progression status readable using existing atlas frames.
* [ ] Audio remains explicitly no-audio for this session and no new audio dependency or browser audio API surface is introduced.

### Testing Requirements

* [ ] Unit tests cover seed helper behavior, pointer helper edge cases, render descriptors, and component states.
* [ ] Focused Playwright tests cover portrait mobile framing, compact pointer controls, seed sharing, reduced-motion mode, desktop pointer movement, and route cleanup.
* [ ] Asset-size, private-runtime, ASCII/LF, and focused AI Rogue gates complete with recorded evidence.

### Non-Functional Requirements

* [ ] No committed AI Rogue media file exceeds the 200 KB policy.
* [ ] PixiJS remains lazy and route-scoped; no runtime code moves into the static extension registry or shared app shell.
* [ ] No raw prompts, transcripts, commands, private paths, credentials, logs, or private runtime artifacts enter seed, save, share, UI, or docs output.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions

***

## 8. Implementation Notes

### Working Assumptions

* Session 09 is the next executable session: The analyzer reported Phase 30 active, sessions 01-08 completed, no active current session, and Session 10 dependent on Session 09. Planning can proceed without user arbitration because the dependency order is explicit in state and the phase stubs.
* Existing atlases are sufficient for this polish pass: `visual-assets.md` records locked gameplay and UI atlases under the 200 KB policy, and Session 08 validation passed asset-size checks. Planning can focus on descriptors, framing, and docs instead of generating new art.
* Audio is settled as no-audio for this session: The stub permits sound effects only if Web Audio API or no-audio tradeoffs are settled. Current code has no mute/autoplay/audio preference contract, so this session records a no-audio decision and adds no dependency or Web Audio surface.

### Key Considerations

* Keep AI Rogue disabled-first until Session 10 quality gates and enablement decision.
* Preserve existing compact visual assets and palette semantics: cyan currency, green health, orange/red hostile, magenta/acid hazard.
* Use existing Playwright readPixels canvas checks for desktop and mobile runtime proof.
* Keep mobile validation focused on no overlap, no horizontal overflow, visible controls, and stable canvas framing.

### Potential Challenges

* Mobile browser viewport variance: Use explicit viewport tests for 390x844 and 768x1024, and assert DOM rectangles instead of only screenshots.
* Clipboard availability in Playwright or restricted browsers: Provide a visible fallback status when copy is unavailable and test both helper output and UI status.
* Seed changes while the runtime is mounted: Gate remount/reset behavior through React props and controller cleanup so the previous PixiJS app is destroyed before the next seed mounts.
* Pointer commands during busy states: Route mobile controls through the same runtime gating used by start, pause, reset, save, and load.

### Relevant Considerations

* \[P00] **Stack conventions**: The plan stays within Bun, Vite 8, TanStack Start, React 19, PixiJS v8, and Cloudflare Worker compatibility.
* \[P02] **Static extension registry requires code changes**: No dynamic loading, remote code, or runtime package loading is introduced.
* \[P02] **Extension payloads and labels stay bounded**: Seed/share labels and runtime status text stay bounded and browser-safe.
* \[P27] **Repo-wide formatting drift remains**: Use focused formatting/ASCII checks for touched files; Session 10 owns full repo-wide quality gates.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Pointer and touch controls can mutate run state repeatedly or while reset/save/load is in flight.
* Seed/share input can carry malformed or private-looking values into UI, runtime metadata, save summaries, or copied URLs.
* Responsive canvas changes can hide critical actions, create horizontal overflow, or leave stale PixiJS listeners after route exit.

***

## 9. Testing Strategy

### Unit Tests

* `src/extensions/ai-rogue/__tests__/seed-share.test.ts` for seed bounds, URL parsing, private-looking text rejection, and deterministic share URL creation.
* `src/extensions/ai-rogue/runtime/__tests__/input.test.ts` for pointer geometry, compact command behavior, tolerance bounds, and invalid inputs.
* `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` for HUD descriptor readability, reward/status descriptors, and input-mode summary text.
* `src/extensions/ai-rogue/__tests__/client.test.tsx` for Play seed/share controls, compact settings state, unavailable runtime behavior, and accessibility labels.

### Integration Tests

* `tests/e2e/ai-rogue-runtime.spec.ts` for desktop seed replay, pointer movement, and existing nonblank canvas/readPixels checks.
* `tests/e2e/ai-rogue-mobile.spec.ts` for portrait viewport framing, compact controls, no horizontal overflow, reduced-motion behavior, and copy/fallback seed status.

### Runtime Verification

* Run focused AI Rogue unit tests with `bun run test -- $(rg --files src/extensions/ai-rogue | rg '(__tests__/.+\\.(test|spec)\\.(ts|tsx)$)' | sort)`.
* Run focused AI Rogue browser tests with `bunx playwright test $(rg --files tests/e2e | rg 'ai-rogue-.*\\.spec\\.ts$' | sort)`.
* Run `bun run typecheck`, `bun run runtime:check-private`, and `bash scripts/check-asset-sizes.sh`.

### Edge Cases

* Empty seed, overlong seed, URL-encoded seed, private-looking seed, and unsupported clipboard.
* Compact mode pointer down outside world bounds, on the player tile, while paused, while busy, and after route cleanup.
* 390x844 portrait viewport, 768x1024 tablet viewport, and reduced-motion preference enabled.
* Disabled or missing AI Rogue runtime data should not mount PixiJS or expose active controls.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase30-session07-play-runtime-integration`, `phase30-session08-progression-depth`
* Depended by: `phase30-session10-quality-gates-and-enablement`

***

## 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/phase30-session09-content-polish-and-mobile/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.