> 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/phases/phase_30/session_03_pixijs_runtime_boundary.md).

# Session 03: PixiJS Runtime Boundary

**Session ID**: `phase30-session03-pixijs-runtime-boundary` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Prove the lazy PixiJS v8 renderer boundary inside the extension host without committing to full gameplay yet.

***

## Scope

### In Scope (MVP)

* Use the installed `pixi.js@8.19.0` package; do not add `@pixi/react` unless a later Pixi UI layer proves it needs declarative composition.
* Implement the lazy runtime mount, WebGL renderer configuration, resize handling, ticker loop, disposal lifecycle, and route cleanup.
* Use `preserveDrawingBuffer: true` for WebGL pixel-read verification, or add a screenshot non-blank fallback if the renderer path changes.
* Add start, pause, reset, hidden-tab throttling, reduced-motion handling, and coarse runtime events back to React.
* Measure lazy chunk output and adjust bundle-budget classification only if the PixiJS chunk requires the watched vendor allowance.

### Out of Scope

* Full simulation, combat, and asset wiring (Sessions 06-07).
* WebGPU renderer adoption.

***

## Prerequisites

* [ ] Session 02 route shell in place.

***

## Deliverables

1. Runtime modules for renderer ownership, loop lifecycle, input sampling, and asset-loading placeholders.
2. Playwright canvas coverage for nonblank paint, resize, keyboard input smoke behavior, and route-away cleanup.
3. Bundle-budget evidence showing PixiJS remains outside shared app chunks.

***

## Reference Code (`EXAMPLES/`)

Both examples mount PixiJS, drive a ticker, and tear down -- the lifecycle this session has to prove. Translate the shape to PixiJS v8 (async `Application.init`, no global `SCALE_MODE`); do not copy v4/v5 calls verbatim.

* `EXAMPLES/frogue/src/fae/engine.cljs` is the cleanest mount/teardown model:
  * `init-canvas` builds the stage, renderer, and a `PIXI.Ticker`, then starts the loop -- the bind-to-canvas-on-mount pattern.
  * `init-render-loop` only steps the sim `when (started? @state)` -- the start/pause gate this session needs (and the hook for hidden-tab throttling and reduced-motion).
  * `cancel-render-loop` calls `.destroy` on the ticker -- the disposal step that prevents leaked tickers on route-away.
  * `set-stage-offset`/`sort-by-z-index` show stage pivot + z-order handling.
* `EXAMPLES/Rotten-Soup/src/assets/js/game/GameDisplay.js`:
  * Renderer config worth mirroring: `antialias: false`, `powerPreference: 'high-performance'`, `transparent: true`, and `PIXI.settings.SCALE_MODE = NEAREST` for crisp pixel art (v8 sets scale mode per-texture instead).
  * `rescale(ratio)` is a minimal resize/zoom handler driving `app.stage.scale`.
  * `Game.js` calls `PIXI.utils.skipHello()` to silence the banner.

## Locked Visual Assets (`visual-assets.md`)

Concrete runtime targets from `docs/extensions/ai-rogue/visual-assets.md`:

* Render at a **2x nearest-neighbor display baseline** (16x16 source -> 32 CSS px/tile). In PixiJS v8 set nearest scaling per-texture; keep integer zoom so pixel art stays crisp.
* The real atlases already exist at `src/assets/ai-rogue/gameplay-atlas.{png,json}` and `ui-atlas.{png,json}` -- even before full asset wiring (Session 07), the boundary's loader placeholder and nonblank-paint test can load one committed atlas instead of a synthetic texture.

## Success Criteria

* [ ] Visiting Play lazily loads the runtime, paints a nonblank canvas, resizes correctly, and disposes without leaked listeners or tickers.
* [ ] Dashboard, extension index, and unrelated routes do not pay the PixiJS runtime cost.
* [ ] Build and budget checks identify no unexpected shared chunk growth from the game runtime.


---

# 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/phases/phase_30/session_03_pixijs_runtime_boundary.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.