# Entities and Components

## 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 are modal because Raygui draws their item list beyond
the panel rectangle and consumes outside clicks to close. While one is open,
neither native web surfaces nor canvas entities receive pointer input behind it.

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.