--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/infinite_canvas/docs/pinning-and-context.md	Mon Aug 17 22:16:14 2026 -0700
@@ -0,0 +1,46 @@
+# Pinning and Visible Context
+
+## Pinning
+
+Pressing `P` toggles the selected entity through
+`Canvas_Scene_Toggle_Selected_Pin()`.
+
+When pinning starts, `Canvas_Entity_Capture_Pin()` records:
+
+- the entity's current screen-space origin;
+- its current screen-space size.
+
+After camera input, `Canvas_Scene_Sync_Pinned()` clamps that screen rectangle to
+the viewport, converts its origin back into world coordinates, and divides its
+screen size by the current zoom. The entity therefore still participates in the
+world renderer and picking system, but appears fixed in the camera view while
+the camera pans or zooms. Pinned entities are marked with the generated Lucide
+`pin` vector, drawn through the same Raylib icon path as the gallery.
+
+Dragging or activating a pinned entity recaptures its screen-space state.
+Notifications are the exception: they use the dedicated animated stack in
+`Canvas_Scene_Update_Notification_Stack()` and cannot be toggled with `P`.
+
+## Visible context
+
+`Canvas_Scene_Build_Visible_Context()` treats the camera viewport as the context
+boundary:
+
+1. Convert the screen viewport to world bounds.
+2. Intersect each entity's semantic bounds with that viewport.
+3. Skip dismissed notifications.
+4. Append identity, type, position, size, pin state, and type-specific state.
+5. Report visible count, bytes written, and truncation.
+
+Zooming out expands the world-space viewport, so more entities become context.
+Panning removes entities that no longer intersect it. The serializer preserves
+scene order and concatenates all visible entries into one provisional text
+snapshot.
+
+Examples of semantic state include text-area content/editing, dropdown
+selection/open state, switch value, selected calendar date or table row, scroll
+offset, image source, browser URL, and Lucide gallery scroll/renderer metadata.
+
+When adding an entity, never leave it on the generic `value=%d` fallback if an
+agent would need richer meaning. Update the serializer and the viewport/context
+tests together.