--- a/infinite_canvas/docs/entities-and-components.md	Mon Aug 17 22:22:36 2026 -0700
+++ b/infinite_canvas/docs/entities-and-components.md	Tue Aug 18 19:14:53 2026 -0700
@@ -7,6 +7,8 @@
 - 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.
 
@@ -19,6 +21,13 @@
 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:
@@ -47,6 +56,7 @@
 
 - developer UI;
 - focused native CEF content;
+- the canvas URL editor or local dictation bridge;
 - hovered/pressed scene entity;
 - camera.