Retained data, immediate drawing

Canvas_Scene stores an arena-backed array of Canvas_Entity. Each entity has:

• a stable id for external resources such as browser views;
• type, world position, and world size;
• generic semantic fields: text, value, and active;
• optional rich-context fields such as a conversation title and agent working state;
• interaction/animation state;
• pinning state in both world and screen coordinates.

The scene is retained, but the draw list is rebuilt every frame. This keeps interaction and context state stable while allowing normal Raylib immediate-mode drawing.

Each entity also owns lifecycle state. visibility_amount eases from zero to one after creation. Delete and developer Clear mark entities as removing, ease them back to zero, then compact the retained array. Raylib colors, native CEF texture tints, and WebAssembly overlay opacity all consume the same eased value.

Treat animation as part of every entity state transition, not optional polish. State changes set retained targets; frame updates ease visual geometry and opacity toward those targets. Do not snap expandable, collapsible, selected, hovered, created, removed, or otherwise stateful entities between layouts. Conversation collapse/expand uses the same smoothstep height interpolation as accordions, while preserving its final semantic active state for context.

Adding a component

Wire every relevant surface, not only drawing:

1. Add the enum value in canvas.h.
2. Set useful size, text, and state defaults in Canvas_Scene_Add().
3. Add bounds/picking behavior in Canvas_Entity_Bounds() and Canvas_Entity_Contains().
4. Add click behavior in Canvas_Scene_Activate() and specialized update logic in Canvas_Scene_Update_Interaction() when needed.
5. Draw it in Canvas_Draw_Entity() and support selection in Canvas_Draw_Selection().
6. Return a readable label from Canvas_Entity_Type_Name().
7. Serialize meaningful state in Canvas_Context_Append_Entity_State().
8. Add focused tests in canvas_test.c.
9. If it owns external pixels or DOM, extend both web-surface backends and key resources by stable entity ID.

Prefer a single entity for large compound views. The Lucide gallery is one entity with virtualized internal rows, not 1,767 independently draggable scene objects.

Input ownership

Input is resolved from most specialized to most general:

• developer UI;
• focused native CEF content;
• the canvas URL editor or local dictation bridge;
• hovered/pressed scene entity;
• camera.

Open developer dropdowns and the snapshot-name editor are modal because Raygui consumes keyboard or outside-click input while editing. While either is open, native web surfaces, canvas entities, dictation hotkeys, and camera movement do not receive that input.

Text editing blocks WASD/arrow camera movement. Scrollable entities consume an unmodified wheel. Ctrl/Cmd + wheel remains available to the camera for anchored zoom; an unmodified wheel outside a scrollable entity pans vertically.

Text areas keep cursor, selection anchor, and vertical scroll state on the entity. Their visual-line layout is shared by drawing, hit testing, vertical cursor movement, and caret visibility, so wrapped text and mouse selection use the same geometry. Ctrl on Windows/Linux and Cmd on macOS drive select/copy/ cut/paste shortcuts; Ctrl or Option performs word navigation. A selected text area exposes a bottom-right resize handle. Dragging it changes both dimensions, reflows wrapped lines immediately, and keeps the caret within the scrollable viewport.

Snapshot boundary

Developer Controls saves named native snapshots under the user state directory as versioned .zmap files. The encoder writes explicit little-endian fields rather than copying Canvas_Entity memory, then uses a payload checksum, bounded entity count, finite geometry validation, and an atomic temporary-file rename. Loading is transactional: the live scene is not cleared until the entire snapshot validates.

The current snapshot preserves numeric canvas entity IDs because conversation routing uses them. Those IDs are canvas-local handles, not final cross-workspace identities. Domain data should eventually normalize into stable keys such as conversation_id, asset_id, and component_id; an entity snapshot should retain only the typed key plus its visual state.

Transient pointers, CEF surfaces, Copilot SDK sessions, hover state, active agent work, and removal animations are never serialized. Browser and image surfaces reconstruct from their retained HTTP(S) source after load.