adventure-codex-unknown — FRICTION.md

# Friction log

## 1. `create-yage` package resolution stalled

- **Trying to do:** Read `create-yage --help` before scaffolding so the game used the intended template and feature flags.
- **What happened:** `npx --yes create-yage --help` produced no output for about one minute inside the restricted sandbox. The same command completed immediately once package-network access was allowed.
- **Category:** test-infra gap

## 2. The recommended scaffold omitted the game manifest

- **Trying to do:** Follow the repository's required handoff recipe by reading the generated game's `GAME.md` before implementation.
- **What happened:** The recommended `create-yage` template did not create `GAME.md`, even though the local YAGE game-development guidance requires every generated game to maintain one.
- **Category:** recipe gap

## 3. UI text rejects normal JSX interpolation shapes

- **Trying to do:** Render evidence labels and counters with YAGE React UI using ordinary JSX text plus interpolated values.
- **What happened:** `Text` accepts only one string child. JSX such as `{icon}{label}` or `Boats: {count}/3` becomes an array of string and number children and fails type-checking. Every mixed label has to be assembled into one template string first.
- **Category:** API friction

## 4. Renderer text-style example does not match the type

- **Trying to do:** Set crisp text resolution through `RendererPlugin.defaultTextStyle`, following the renderer LLM documentation.
- **What happened:** The documentation shows `defaultTextStyle: { fontFamily, fill, resolution }`, but `resolution` is not accepted by the plugin's `TextStyleOptions` type. Resolution can only be set on individual text components.
- **Category:** docs ambiguity

## 5. The effects intensity recipe does not apply to color grading

- **Trying to do:** Increase the ending color grade through the documented common `setIntensity` control.
- **What happened:** The effects documentation calls `setIntensity` the canonical control for every preset, but `ColorGradeHandle` exposes only `setPreset` beyond the base effect methods. The ending can change grade presets but cannot adjust the grade amount through the returned handle.
- **Category:** docs ambiguity

## 6. The Playwright wrapper also stalls during sandboxed package resolution

- **Trying to do:** Open the running game with the repository's required real-browser verification workflow.
- **What happened:** The Playwright CLI wrapper waited for 30 seconds without output while `npx` tried to resolve its package inside the restricted sandbox. Browser verification required package-network access outside that sandbox, matching the earlier `create-yage` behavior.
- **Category:** test-infra gap

## 7. An idle audio plugin emits autoplay warnings on launch

- **Trying to do:** Keep YAGE's standard audio channels installed while the game used browser-synthesized sounds that start on player input.
- **What happened:** `AudioPlugin` created or resumed its audio context on startup and produced three browser autoplay warnings before any sound was requested. Removing the unused plugin left the procedural, gesture-triggered sound path clean.
- **Category:** API friction

## 8. Inspector input is not a browser audio gesture

- **Trying to do:** Verify movement deterministically with `inspector.input.hold` while keeping footstep sound enabled.
- **What happened:** Synthetic Inspector input advances gameplay but does not count as a browser user gesture, so creating the procedural `AudioContext` from the resulting footstep produced an autoplay warning. The audio context now unlocks from a real key or pointer event; synthetic movement remains silent until that happens.
- **Category:** test-infra gap

## 9. UI overflow warnings do not identify the element

- **Trying to do:** Remove small Yoga overflow warnings found in the journal, final dialogue, and ending.
- **What happened:** The warning reports the overflow amount and general fixes but does not identify the UI entity, component, JSX element, or layout path. Matching the 8-pixel warning to the journal card, two 12-pixel warnings to the choice buttons, and 2-pixel warning to the ending required correlating server timestamps with screenshots.
- **Category:** test-infra gap

## 10. The scaffold shipped genre-specific assets and guidance

- **Trying to do:** Replace the recommended starter with a code-drawn top-down mystery, based on the run prompt's statement that the scaffold ships no assets.
- **What happened:** The generated folder included platformer sprites, sound effects, credits, and an `AGENTS.md` that described platformer controls and files. The game does not reference those assets, and the final agent guide had to be rewritten so future work does not follow stale platformer instructions.
- **Category:** asset gap

## 11. The virtual-controls add-on was easy to miss

- **Trying to do:** Assess whether the finished game supported mobile controls.
- **What happened:** YAGE provides `@yagejs-addons/virtual-controls` v0.1.0, with a touch-first virtual stick and action buttons that drive existing input actions. The game scaffold did not install it, and the main LLM documentation only mentioned it indirectly in renderer and input notes instead of routing game authors to its add-on guide.
- **Category:** recipe gap