diff --git a/docs/web-ui/shape.md b/docs/web-ui/shape.md
index c0000b7e..56e42eb9 100644
--- a/docs/web-ui/shape.md
+++ b/docs/web-ui/shape.md
@@ -193,6 +193,20 @@ empty state invisible. Builders receive the fragment as their
 returns inside the builder still commit whatever was appended
 before they returned.
 
+**Keyed DOM caching:** for sections whose rows hold interactive state
+(textarea drafts, checkboxes, focused inputs) `paintAtomic` is not
+enough — wiping and rebuilding still destroys the state even if the
+flash is hidden. The keyed pattern keeps a `Map<id, {el, fingerprint}>`
+where the fingerprint is `JSON.stringify({...visible fields...})`.
+On each render: cache-hit rows are reused verbatim (preserving
+textarea draft, checkbox state, and event listeners); only cache-miss
+rows are rebuilt and inserted. Used for: containers (`containerRowCache`),
+rebuild-queue entries (`rebuildQueueRowCache`), and question rows
+(`questionRowCache`). The spawn-form input+focus and meta-input
+checkboxes use a lighter snapshot-then-restore pattern (snapshot
+before `replaceChildren`, restore after) since they are single
+values rather than per-row caches.
+
 **`<details>` open-state preservation:** any collapsible element
 tagged with `data-restore-key="<stable-key>"` survives the
 refresh. `snapshotOpenDetails()` walks managed sections before