---

title: Yuu architecture wiki status: canonical audience:

• humans
• AI agents last_reviewed: 2026-08-22 ---

Yuu architecture wiki

Use this tree before changing rendering, entities, pinning, context, persistence, or hydration:

Yuu
├── Rendering surfaces
│   ├── Raylib world primitives and UI components
│   ├── Raylib-generated Lucide vectors
│   ├── Native CEF image/web textures
│   └── WebAssembly DOM image/iframe overlays
├── Entity model and extension path
│   ├── defaults and retained state
│   ├── picking, interaction, and drawing
│   └── semantic context serialization
├── Screen-space behavior
│   ├── camera transforms
│   ├── pinned entities
│   └── notification stacking
├── Spatial agent sessions
│   ├── WebRTC dictation bridge
│   ├── asynchronous Copilot SDK orchestration
│   └── retained conversation entities
├── Spatial persistence and hydration
│   ├── SQLite catalog and R-tree bounds
│   ├── viewport queries and residency
│   ├── per-type hydration
│   ├── camera checkpoints
│   └── portable database exports
├── Architecture decisions
│   ├── local-first source of truth
│   ├── geometry separate from semantic membership
│   └── storage backend boundary
└── Session lineage
    ├── original renderer
    └── scalability, images, pinning, context, and icons

• Rendering surfaces
• Entities and components
• Pinning and visible context
• Dictation and spatial agent sessions
• Spatial persistence and hydration
• Architecture decisions
• Session lineage

Reading routes

Task	Read
Camera, drawing, CEF, or WASM surfaces	Rendering surfaces
Entity types, input, resizing, or lifecycle	Entities and components
Pinning or AI-visible viewport context	Pinning and visible context
Dictation, Copilot routing, or conversations	Dictation and spatial agent sessions
Persistence, viewport loading, hydration, caching, or database upload	Spatial persistence and hydration
Why a boundary or storage choice exists	Architecture decisions

The package README is the user-facing build and controls guide. This wiki is the canonical architecture and implementation-planning surface. Source, BUILD targets, and tests remain authoritative when documentation is stale; update the relevant wiki page in the same change.

Runtime frame order

main.c owns the integration order:

1. Update viewport dimensions.
2. Handle dictation and selected browser chrome.
3. Let native web surfaces translate focused input.
4. Update scene interaction and keyboard focus.
5. Submit or poll asynchronous agent work.
6. Apply camera pan/zoom and reproject pinned entities.
7. Reconcile web/image resources with visible entities.
8. Draw each Raylib entity and its owning native/DOM surface in scene order.
9. Draw world overlays and the developer UI.

Preserve this order. In particular, pinned positions must be synchronized before surface bounds are calculated, and native surface textures must draw after the Raylib entity frames.