design(web): captures sit beside the prose they show; captions say what to look at

§02: the loop takes the wide track with the three rules beside it instead of
running full measure, and the click and frame stills read as an equal pair
under it. §03: the note block and sinks share the wide track with the pins
still alongside, so neither column outruns the other. The build hash stays
in the manifest and leaves the captions; each caption now names the rule the
capture demonstrates.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: angusbezzina

web/src/captures.ts

@@ -18,7 +18,8 @@
 type Base = {
   /** Printed under the frame. Says what the reader is looking at. */
   caption: string;
-  /** Short commit hash of the build the capture was taken from. */
+  /** Short commit hash of the build the capture was taken from. Kept for
+   * re-shoots; the page does not print it. */
   buildHash?: string;
 };
 
@@ -68,7 +69,7 @@ export const annotateLoop: Capture = {
   alt: "AnnotKitDemo, a dark macOS settings window. Annotate is pressed, a control is clicked, a note is typed into the composer and sent; a numbered pin lands on the control.",
   width: 1274,
   height: 820,
-  caption: "AnnotKitDemo: press Annotate, click a control, type a note, send. 22 seconds, muted.",
+  caption: "The whole loop in the demo app: press Annotate, click the name field, type, send. The pin stays on the field.",
   buildHash: LOOP_HASH,
 };
 
@@ -80,7 +81,7 @@ export const annotateClick: Capture = {
   alt: "The demo window after a click on the avatar. A chip above it reads Settings.Profile.Avatar and the composer below holds the note “Change the background color to green”.",
   width: 1428,
   height: 1378,
-  caption: "A click on the avatar. The chip is the resolved selector, `Settings.Profile.Avatar`; the composer opens under it.",
+  caption: "Click. The avatar is the deepest actionable control under the pointer, so the chip reads `Settings.Profile.Avatar` and the composer opens beneath it.",
   buildHash: HASH,
 };
 
@@ -92,7 +93,7 @@ export const annotateFrame: Capture = {
   alt: "The demo window with a frame drawn around the heading and the Profile card. The composer title reads Frame → Settings… and waits for a note.",
   width: 1498,
   height: 1286,
-  caption: "A frame drawn around the heading and the Profile card. The largest element it surrounds wins, not the labels inside.",
+  caption: "Frame. The box takes in the heading and the whole Profile card, so the note binds to the card and not to a field inside it.",
   buildHash: HASH,
 };
 
@@ -104,6 +105,6 @@ export const notesPins: Capture = {
   alt: "The demo window with five numbered blue pins on its controls and the toolbar’s copy button under the pointer, captioned Copy notes (Markdown).",
   width: 1570,
   height: 1350,
-  caption: "Five notes pinned. Save writes them all to one `ANNOTKIT_NOTES.md`; the toolbar copies the same markdown.",
+  caption: "Five notes, five pins. Click a pin to edit its note; Save writes all five to `ANNOTKIT_NOTES.md`, and the copy button puts the same markdown on the clipboard.",
   buildHash: HASH,
 };

web/src/components/Figure.tsx

@@ -53,10 +53,9 @@ export function Figure({ capture }: { capture: Capture }) {
           />
         )}
       </div>
-      <figcaption>
-        {withCode(capture.caption)}
-        {capture.buildHash ? ` · captured at ${capture.buildHash}` : ""}
-      </figcaption>
+      {/* The build hash stays in the manifest, for whoever re-shoots; it is
+       * not printed. A caption is for the reader, and says what to look at. */}
+      <figcaption>{withCode(capture.caption)}</figcaption>
     </figure>
   );
 }

web/src/sections/AgentNotes.tsx

@@ -17,9 +17,9 @@ export function AgentNotes() {
       <div className="section__body section__body--7-5">
         <div className="stack stack--lg">
           <CodeBlock {...agentNotes.sample} />
-          <Figure capture={notesPins} />
+          <TermList terms={agentNotes.sinks} />
         </div>
-        <TermList terms={agentNotes.sinks} />
+        <Figure capture={notesPins} />
       </div>
     </Section>
   );

web/src/sections/Annotate.tsx

@@ -5,9 +5,12 @@ import { annotate } from "../copy";
 import { annotateClick, annotateFrame, annotateLoop } from "../captures";
 
 /**
- * §02 — the targeting rules, led by the one moving figure on the page.
- * The loop sits directly under the hero fold; the two stills, a click and a
- * frame, stand beside the rules they illustrate.
+ * §02 — the targeting rules and the captures that show them.
+ *
+ * The loop takes the wide track with the three rules beside it, so the first
+ * moving figure on the page does not run the full measure and the rules are
+ * read while it plays. The two stills, a click and a frame, sit as a pair
+ * under it: same height, same frame, one rule each.
  */
 export function Annotate() {
   return (
@@ -18,15 +21,15 @@ export function Annotate() {
       lead={annotate.lead}
       modifier="section--annotate"
     >
-      <div className="stack stack--lg">
-        <Figure capture={annotateLoop} />
-        <div className="section__body section__body--5-7">
-          <div className="stack stack--lg">
-            <Figure capture={annotateClick} />
-            <Figure capture={annotateFrame} />
-          </div>
+      <div className="stack stack--xl">
+        <div className="section__body section__body--7-5">
+          <Figure capture={annotateLoop} />
           <TermList terms={annotate.points} />
         </div>
+        <div className="section__body section__body--6-6">
+          <Figure capture={annotateClick} />
+          <Figure capture={annotateFrame} />
+        </div>
       </div>
     </Section>
   );

web/src/styles/base.css

@@ -722,6 +722,13 @@ pre {
     grid-template-columns: minmax(0, 7fr) minmax(0, 5fr);
   }
 
+  /* Two captures of the same shape, read as a pair. Equal on purpose: the
+   * asymmetric spans are for prose beside a figure, and here both tracks hold
+   * a figure. */
+  .section__body--6-6 {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
   /* §04 carries the page's shortest body — one command beside two tools, 125 px
    * of it. At the standard close (4rem) that body was followed by §05's heavier
    * open (6rem), so the WIDEST gap on the page sat under the THINNEST section
@@ -764,6 +771,10 @@ pre {
   gap: var(--space-lg);
 }
 
+.stack--xl {
+  gap: var(--space-xl);
+}
+
 /* ══ CodeBlock — typographic frame, no re-drawn window chrome (gate 47) ══ */
 
 .code {