Mercurial

annotate infinite_canvas/docs/entities-and-components.md @ 280:49e9e591c9bb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add persistent dictation, prewarmed WebRTC speech input, Copilot SDK routing, animated conversation lifecycle controls, parking, and architecture coverage.
author MrJuneJune <me@mrjunejune.com>
date Tue, 18 Aug 2026 19:14:53 -0700
parents 8d560f50ed4c
children c57149ad216e
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
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 Open developer dropdowns are modal because Raygui draws their item list beyond
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
64 the panel rectangle and consumes outside clicks to close. While one is open,
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65 neither native web surfaces nor canvas entities receive pointer input behind it.
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67 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
68 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
69 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
70
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71 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
72 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
73 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
74 the same geometry. Ctrl on Windows/Linux and Cmd on macOS drive select/copy/
8d560f50ed4c Improve infinite canvas interactions and browser chrome
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75 cut/paste shortcuts; Ctrl or Option performs word navigation.