--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/infinite_canvas/docs/entities-and-components.md	Mon Aug 17 22:16:14 2026 -0700
@@ -0,0 +1,65 @@
+# 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`;
+- 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.
+
+## 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;
+- 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.