Mercurial

annotate infinite_canvas/docs/entities-and-components.md @ 281:c57149ad216e default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
author MrJuneJune <me@mrjunejune.com>
date Tue, 18 Aug 2026 22:18:15 -0700
parents 49e9e591c9bb
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
278
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 # Entities and Components
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 ## Retained data, immediate drawing
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5 `Canvas_Scene` stores an arena-backed array of `Canvas_Entity`. Each entity has:
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7 - a stable `id` for external resources such as browser views;
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 - `type`, world `position`, and world `size`;
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9 - generic semantic fields: `text`, `value`, and `active`;
280
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
10 - optional rich-context fields such as a conversation title and agent working
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
11 state;
278
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 - interaction/animation state;
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13 - pinning state in both world and screen coordinates.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 The scene is retained, but the draw list is rebuilt every frame. This keeps
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 interaction and context state stable while allowing normal Raylib immediate-mode
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 drawing.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 Each entity also owns lifecycle state. `visibility_amount` eases from zero to
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20 one after creation. Delete and developer Clear mark entities as `removing`, ease
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 them back to zero, then compact the retained array. Raylib colors, native CEF
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22 texture tints, and WebAssembly overlay opacity all consume the same eased value.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23
280
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
24 Treat animation as part of every entity state transition, not optional polish.
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
25 State changes set retained targets; frame updates ease visual geometry and
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
26 opacity toward those targets. Do not snap expandable, collapsible, selected,
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
27 hovered, created, removed, or otherwise stateful entities between layouts.
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
28 Conversation collapse/expand uses the same smoothstep height interpolation as
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
29 accordions, while preserving its final semantic `active` state for context.
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
30
278
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 ## Adding a component
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 Wire every relevant surface, not only drawing:
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 1. Add the enum value in `canvas.h`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36 2. Set useful size, text, and state defaults in `Canvas_Scene_Add()`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37 3. Add bounds/picking behavior in `Canvas_Entity_Bounds()` and
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38 `Canvas_Entity_Contains()`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 4. Add click behavior in `Canvas_Scene_Activate()` and specialized update logic
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 in `Canvas_Scene_Update_Interaction()` when needed.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 5. Draw it in `Canvas_Draw_Entity()` and support selection in
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42 `Canvas_Draw_Selection()`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43 6. Return a readable label from `Canvas_Entity_Type_Name()`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 7. Serialize meaningful state in `Canvas_Context_Append_Entity_State()`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45 8. Add focused tests in `canvas_test.c`.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 9. If it owns external pixels or DOM, extend both web-surface backends and key
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47 resources by stable entity ID.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49 Prefer a single entity for large compound views. The Lucide gallery is one
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50 entity with virtualized internal rows, not 1,767 independently draggable scene
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51 objects.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53 ## Input ownership
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55 Input is resolved from most specialized to most general:
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57 - developer UI;
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
58 - focused native CEF content;
280
49e9e591c9bb Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
MrJuneJune <me@mrjunejune.com>
parents: 278
diff changeset
59 - the canvas URL editor or local dictation bridge;
278
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60 - hovered/pressed scene entity;
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61 - camera.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62
281
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
63 Open developer dropdowns and the snapshot-name editor are modal because Raygui
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
64 consumes keyboard or outside-click input while editing. While either is open,
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
65 native web surfaces, canvas entities, dictation hotkeys, and camera movement do
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
66 not receive that input.
278
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
68 Text editing blocks WASD/arrow camera movement. Scrollable entities consume an
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
69 unmodified wheel. Ctrl/Cmd + wheel remains available to the camera for anchored
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
70 zoom; an unmodified wheel outside a scrollable entity pans vertically.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72 Text areas keep cursor, selection anchor, and vertical scroll state on the
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73 entity. Their visual-line layout is shared by drawing, hit testing, vertical
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74 cursor movement, and caret visibility, so wrapped text and mouse selection use
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75 the same geometry. Ctrl on Windows/Linux and Cmd on macOS drive select/copy/
281
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
76 cut/paste shortcuts; Ctrl or Option performs word navigation. A selected text
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
77 area exposes a bottom-right resize handle. Dragging it changes both dimensions,
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
78 reflows wrapped lines immediately, and keeps the caret within the scrollable
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
79 viewport.
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
80
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
81 ## Snapshot boundary
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
82
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
83 Developer Controls saves named native snapshots under the user state directory
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
84 as versioned `.zmap` files. The encoder writes explicit little-endian fields
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
85 rather than copying `Canvas_Entity` memory, then uses a payload checksum,
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
86 bounded entity count, finite geometry validation, and an atomic temporary-file
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
87 rename. Loading is transactional: the live scene is not cleared until the
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
88 entire snapshot validates.
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
89
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
90 The current snapshot preserves numeric canvas entity IDs because conversation
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
91 routing uses them. Those IDs are canvas-local handles, not final
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
92 cross-workspace identities. Domain data should eventually normalize into
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
93 stable keys such as `conversation_id`, `asset_id`, and `component_id`; an
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
94 entity snapshot should retain only the typed key plus its visual state.
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
95
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
96 Transient pointers, CEF surfaces, Copilot SDK sessions, hover state, active
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
97 agent work, and removal animations are never serialized. Browser and image
c57149ad216e Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
MrJuneJune <me@mrjunejune.com>
parents: 280
diff changeset
98 surfaces reconstruct from their retained HTTP(S) source after load.