feat: add two-stage compaction line animation with docs and unit tests

Author: ofriw

website/docs/context-engineering.mdx

@@ -7,6 +7,7 @@ import ContextMechanismMap from '@site/src/components/VisualElements/ContextMech
 import SkillsInvocationDiagram from '@site/src/components/VisualElements/SkillsInvocationDiagram';
 import SubAgentFanoutDiagram from '@site/src/components/VisualElements/SubAgentFanoutDiagram';
 import ContextSqueezeDiagram from '@site/src/components/VisualElements/ContextSqueezeDiagram';
+import CompactionLineDiagram from '@site/src/components/VisualElements/CompactionLineDiagram';
 import MCPToolSchemaDiagram from '@site/src/components/VisualElements/MCPToolSchemaDiagram';
 import UShapeAttentionCurve from '@site/src/components/VisualElements/UShapeAttentionCurve';
 import DiagramFrame from '@site/src/components/VisualElements/DiagramFrame';
@@ -233,6 +234,16 @@ Sub-agents are ideal for heavy research, multi-file analysis, and exploratory ta
 
 **Context effect:** compaction replaces accumulated conversation with a smaller synthetic state, restoring working room while discarding detail. It is lossy summarization guided by your instruction, but it cannot guarantee what survives. Future relevance is unknowable at compaction time: a debugging trace that looks like noise now may be the clue the next step needed.
 
+In practice, the harness usually performs two reductions, not one. First it removes or offloads stale tool traces that no longer need to be replayed. Then it summarizes the surviving sections while leaving the most recent turns intact. The raw transcript may remain available outside the model call, but only the compact working set reaches the next request.
+
+<DiagramFrame kicker="Context management" title="Compaction deletes traces, then summarizes the survivors" size="full" caption={'Stale tool-call/result pairs leave the next request entirely. Surviving sections are summarized one by one, while the recent tail remains verbatim. The raw transcript may persist externally, but only the compact working set reaches the model.'}>
+
+<CompactionLineDiagram />
+
+</DiagramFrame>
+
+Deletion is selection; summarization is transformation. Both reduce the model's working set, but only summarization preserves a synthetic version of the source section.
+
 The reliable alternative is **manual handoff with external checkpointing**. Before starting a new phase, write a brief state file with the current goal, changed files, decisions, unresolved errors, and next step. Files provide exact recall; a fresh context provides inference quality.
 
 ### The Buffer Tax

website/src/components/VisualElements/CompactionLineDiagram.module.css

@@ -0,0 +1,57 @@
+/* Compaction Line story classes. Keyframes are injected by the TSX (inline
+   names bypass CSS Modules renaming); these classes only attach timing. Every
+   story element loops the shared --cycle-ms schedule set on the root svg. */
+.collapse,
+.slide,
+.shrink,
+.threadLabel,
+.eject,
+.survivor,
+.summary,
+.headroom,
+.legend {
+  animation-duration: var(--cycle-ms);
+  animation-timing-function: ease-in-out;
+  animation-iteration-count: infinite;
+  animation-fill-mode: both;
+  animation-delay: var(--delay, 0ms);
+}
+
+/* SVG transforms need a local box or scaleY collapses toward the svg origin. */
+.collapse {
+  transform-box: fill-box;
+  transform-origin: center;
+}
+
+/* Shrink keeps the top edge fixed: the tile compresses toward its Σ slot. */
+.shrink {
+  transform-box: fill-box;
+  transform-origin: 50% 0;
+}
+
+.summary,
+.headroom {
+  opacity: 0; /* placeholder until its act arrives */
+}
+
+/* Static fallback is authoritative: motion disabled = the complete figure.
+   The animated scene swaps for a still of the compacted stack plus the
+   ledger of what was freed (AnimatedTokenFlow dual-render precedent). */
+.staticScene {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animatedScene {
+    display: none;
+  }
+
+  .staticScene {
+    display: initial;
+  }
+
+  .legend {
+    animation: none;
+    opacity: 1;
+  }
+}