@cardstack/boxel-cli 0.11.0-unstable.2 → 0.11.0-unstable.3

package/bundled-realms/pretui/components/work-item.gts

@@ -2,26 +2,103 @@
 import Component from '@glimmer/component';
 import { ProgressBar } from './progress-bar';
 import { Spinner } from './spinner';
+import { StateGlyph } from './state-glyph';
 
 type Tone = 'idle' | 'running' | 'attention' | 'done' | 'failed';
 const TONES: Record<string, Tone> = {
-  pending: 'idle', preparing: 'running', running: 'running', applying: 'running',
-  handoff: 'running', reconnecting: 'running', 'host-attached': 'running',
-  fallback: 'running', ready: 'attention', 'awaiting-approval': 'attention',
-  ask: 'attention', input: 'attention', completed: 'done', kept: 'done',
-  delivered: 'done', failed: 'failed', invalid: 'failed', reverted: 'idle',
+  pending: 'idle',
+  preparing: 'running',
+  running: 'running',
+  applying: 'running',
+  handoff: 'running',
+  starting: 'running',
+  // a reload lost the page that watched the run, not the run: grey, never red
+  reconnecting: 'idle',
+  'host-attached': 'running',
+  fallback: 'running',
+  ready: 'attention',
+  'awaiting-approval': 'attention',
+  ask: 'attention',
+  input: 'attention',
+  completed: 'done',
+  kept: 'done',
+  delivered: 'done',
+  failed: 'failed',
+  invalid: 'failed',
+  reverted: 'idle',
   canceled: 'idle',
+  superseded: 'idle',
+  stopped: 'idle',
+  // staged writes: the preview waits on the reader, the commit runs, a file
+  // that moved since the preview waits again; a partial keep is still done
+  previewed: 'attention',
+  committing: 'running',
+  conflict: 'attention',
+  partial: 'done',
+  resumed: 'running',
+  // a transient failure that will try again by itself is not red yet
+  retrying: 'idle',
+  // the run spent its budget: it stopped with what it had, and can continue
+  budget: 'idle',
+  // the decision belongs to someone else in the room
+  routed: 'idle',
+};
+const GLYPHS: Record<Tone, string> = {
+  idle: '·',
+  running: '',
+  attention: '●',
+  done: '✓',
+  failed: '✕',
 };
-const GLYPHS: Record<Tone, string> = { idle: '·', running: '', attention: '●', done: '✓', failed: '✕' };
 const DEFAULT_STATUS: Record<string, string> = {
-  pending: 'queued', preparing: 'preparing…', running: 'running…',
-  applying: 'applying…', handoff: 'handing off…', reconnecting: 'reconnecting…',
-  'host-attached': 'attached', fallback: 'fallback…', ready: '● needs you',
-  'awaiting-approval': '● needs you', ask: '● needs you', input: '● needs you',
-  completed: 'done', kept: 'kept', delivered: 'delivered', failed: 'failed',
-  invalid: 'invalid', reverted: 'reverted', canceled: 'canceled',
+  pending: 'queued',
+  preparing: 'preparing…',
+  running: 'running…',
+  applying: 'applying…',
+  handoff: 'handing off…',
+  starting: 'starting…',
+  reconnecting: 'reconnecting…',
+  'host-attached': 'attached',
+  fallback: 'fallback…',
+  ready: 'needs you',
+  'awaiting-approval': 'needs you',
+  ask: 'needs you',
+  input: 'needs you',
+  completed: 'done',
+  kept: 'kept',
+  delivered: 'delivered',
+  failed: 'failed',
+  invalid: 'invalid',
+  reverted: 'reverted',
+  canceled: 'canceled',
+  superseded: 'retried below',
+  stopped: 'stopped',
+  previewed: 'review',
+  committing: 'writing…',
+  conflict: 'conflict',
+  partial: 'partly kept',
+  resumed: 'resumed…',
+  retrying: 'retrying soon',
+  budget: 'budget reached',
+  routed: 'waiting on someone',
 };
 
+/** The tone an agent state collapses to. Exported so components built on the
+ * same vocabulary (ToolRow) map states identically rather than keeping a
+ * second table that drifts. */
+export function workTone(state: string): Tone {
+  return TONES[state] ?? 'idle';
+}
+/** The glyph for a tone; empty for `running`, which shows a Spinner. */
+export function workGlyph(tone: Tone): string {
+  return GLYPHS[tone];
+}
+/** The default status phrase for a state. */
+export function workStatus(state: string): string {
+  return DEFAULT_STATUS[state] ?? state;
+}
+export type WorkTone = Tone;
+
 export interface WorkItemSignature {
   Args: {
     tier?: 'step' | 'action' | 'run';
@@ -33,6 +110,9 @@ export interface WorkItemSignature {
     progressMax?: number;
     count?: string;
     activity?: string;
+    /** whether settled work recedes (default: done or idle states). Only
+     * shows inside a container that sets --pretui-recede-opacity */
+    recede?: boolean;
   };
   Blocks: { default: []; footer: [] };
   Element: HTMLDivElement;
@@ -54,6 +134,9 @@ export class WorkItem extends Component<WorkItemSignature> {
   get isAttention() {
     return this.tone === 'attention';
   }
+  get recedes() {
+    return this.args.recede ?? (this.tone === 'done' || this.tone === 'idle');
+  }
   get statusText() {
     return this.args.status ?? DEFAULT_STATUS[this.state] ?? this.state;
   }
@@ -78,23 +161,47 @@ export class WorkItem extends Component<WorkItemSignature> {
       data-tier={{if @tier @tier 'step'}}
       data-state={{this.state}}
       data-attention={{if this.isAttention 'true'}}
+      data-recede={{if this.recedes 'true'}}
       data-test-pretui-work-item
       ...attributes
     >
       <div class='pretui-workitem-row'>
-        <span class='pretui-disc' data-tone={{this.tone}}>
-          {{#if this.isRunning}}<Spinner @size={{9}} />{{else}}{{this.glyph}}{{/if}}
+        <span
+          class='pretui-disc'
+          data-tone={{this.tone}}
+          data-test-pretui-work-item-disc
+        >
+          {{#if this.isRunning}}<Spinner @size={{9}} />{{else}}<StateGlyph
+              @glyph={{this.glyph}}
+            />{{/if}}
         </span>
-        {{#if @verb}}<span class='pretui-verb'>{{@verb}}</span>{{/if}}
-        <span class='pretui-workitem-title'>{{@title}}</span>
-        <span class='pretui-workitem-status' data-tone={{this.tone}}>{{this.statusText}}</span>
+        {{#if @verb}}<span
+            class='pretui-verb'
+            data-test-pretui-work-item-verb
+          >{{@verb}}</span>{{/if}}
+        <span
+          class='pretui-workitem-title'
+          data-test-pretui-work-item-title
+        >{{@title}}</span>
+        <span
+          class='pretui-workitem-status'
+          data-tone={{this.tone}}
+          data-test-pretui-work-item-status
+        >{{this.statusText}}</span>
       </div>
       {{#if this.hasBody}}
-        <div class='pretui-workitem-body'>
+        <div class='pretui-workitem-body' data-test-pretui-work-item-body>
           {{#if this.hasProgress}}
-            <ProgressBar @value={{this.progressValue}} @max={{@progressMax}} @count={{this.countText}} />
+            <ProgressBar
+              @value={{this.progressValue}}
+              @max={{@progressMax}}
+              @count={{this.countText}}
+            />
           {{/if}}
-          {{#if @activity}}<div class='pretui-activity'>{{@activity}}</div>{{/if}}
+          {{#if @activity}}<div
+              class='pretui-activity'
+              data-test-pretui-work-item-activity
+            >{{@activity}}</div>{{/if}}
           {{yield}}
         </div>
       {{else}}
@@ -105,63 +212,93 @@ export class WorkItem extends Component<WorkItemSignature> {
     <style scoped>
       @layer PretComponent {
         .pretui-workitem {
+          /* the row's inset, disc and gap, which the body's leading edge
+             adds up to so its text lines up under the title */
+          --_workitem-inset: var(--boxel-sp-sm);
+          --_workitem-disc: 1rem;
+          --_workitem-gap: var(--boxel-sp-xs);
           display: flex;
           flex-direction: column;
-          background: var(--card);
-          border-radius: 10px;
+          background-color: var(--card);
+          border-radius: var(--boxel-border-radius);
           box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
-          font-size: var(--text-ui-md, 12.5px);
+          font-size: var(--boxel-font-size-xs);
         }
+        /* needs you: the attention hue tints the face and draws the edge;
+           the status words and the disc's mark take its ink (below) */
         .pretui-workitem[data-attention] {
-          box-shadow: 0 0 0 1px color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 60%, var(--border)),
-            0 2px 10px color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 14%, transparent);
-          background: linear-gradient(
+          box-shadow:
+            0 0 0 1px color-mix(in oklch, var(--attention) 60%, var(--border)),
+            0 0.125rem 0.625rem
+              color-mix(in oklch, var(--attention) 14%, transparent);
+          background-image: linear-gradient(
             180deg,
-            color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 7%, var(--card)),
+            color-mix(in oklch, var(--attention) 7%, var(--card)),
             var(--card) 55%
           );
         }
         .pretui-workitem[data-state='failed'],
         .pretui-workitem[data-state='invalid'] {
-          box-shadow: 0 0 0 1px color-mix(in oklch, var(--destructive) 45%, var(--border));
+          box-shadow: 0 0 0 1px
+            color-mix(in oklch, var(--destructive) 45%, var(--border));
+        }
+        .pretui-workitem[data-recede] > .pretui-workitem-row {
+          opacity: var(--pretui-recede-opacity, 1);
+          transition: opacity 200ms linear;
+        }
+        .pretui-workitem[data-recede]:is(:hover, :focus-within)
+          > .pretui-workitem-row {
+          opacity: 1;
         }
         .pretui-workitem-row {
           display: flex;
           align-items: center;
-          gap: 9px;
-          padding: 7px 11px;
-          min-height: 32px;
+          gap: var(--_workitem-gap);
+          padding: var(--boxel-sp-2xs) var(--_workitem-inset);
+          min-height: 2rem;
         }
         .pretui-workitem-body {
-          padding: 0 11px 9px 36px;
+          padding: 0 var(--_workitem-inset) var(--boxel-sp-xs)
+            calc(
+              var(--_workitem-inset) + var(--_workitem-disc) +
+                var(--_workitem-gap)
+            );
           display: flex;
           flex-direction: column;
-          gap: 8px;
+          gap: var(--boxel-sp-xs);
         }
         .pretui-disc {
-          width: 16px;
-          height: 16px;
+          width: var(--_workitem-disc);
+          height: var(--_workitem-disc);
           border-radius: 50%;
           display: grid;
           place-items: center;
           flex: none;
-          font-size: 9px;
+          font-size: 0.5625rem;
           font-weight: 700;
-          background: var(--inset, var(--boxel-100));
+          background-color: var(--inset);
           color: var(--muted-foreground);
           box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
         }
         .pretui-disc[data-tone='failed'] {
-          background: color-mix(in oklch, var(--destructive) 15%, var(--card));
-          color: var(--pretui-destructive-ink, var(--boxel-danger));
+          background-color: color-mix(
+            in oklch,
+            var(--destructive) 15%,
+            var(--card)
+          );
+          color: var(--destructive-ink);
         }
         .pretui-disc[data-tone='attention'] {
-          background: color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 22%, var(--card));
-          color: var(--pretui-attention-ink, var(--pretui-attention, var(--boxel-fuschia)));
+          background-color: color-mix(
+            in oklch,
+            var(--attention) 22%,
+            var(--card)
+          );
+          color: var(--attention-ink);
         }
         .pretui-verb {
           font-family: var(--font-mono);
-          font-size: 10px;
+          font-size: 0.625rem;
           font-weight: 600;
           letter-spacing: 0.06em;
           color: var(--muted-foreground);
@@ -178,25 +315,25 @@ export class WorkItem extends Component<WorkItemSignature> {
         .pretui-workitem-status {
           margin-left: auto;
           flex: none;
-          font-size: var(--text-ui-sm, 11.5px);
+          font-size: var(--boxel-font-size-xs);
           color: var(--muted-foreground);
           display: flex;
           align-items: center;
-          gap: 6px;
+          gap: var(--boxel-sp-3xs);
           font-variant-numeric: tabular-nums;
         }
         .pretui-workitem-status[data-tone='attention'] {
-          color: var(--pretui-attention-ink, var(--pretui-attention, var(--boxel-fuschia)));
+          color: var(--attention-ink);
           font-weight: 600;
         }
         .pretui-workitem-status[data-tone='failed'] {
-          color: var(--pretui-destructive-ink, var(--boxel-danger));
+          color: var(--destructive-ink);
           font-weight: 500;
         }
         .pretui-activity {
           font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
-          color: var(--ink-3, var(--boxel-400));
+          font-size: var(--boxel-font-size-2xs);
+          color: var(--subtle-foreground);
           white-space: nowrap;
           overflow: hidden;
           text-overflow: ellipsis;

package/bundled-realms/pretui/docs/scroll-anchoring-protocol.md

@@ -0,0 +1,136 @@
+# Scroll anchoring: one protocol for where the reader's view stays
+
+Status: built in StickToBottom (`settle()` and `navigate()` on its API), with seeded property tests in `stick-to-bottom.test.gts`. [ADR 012](../../../docs/adr/012-hold-one-scroll-anchor-per-change-chosen-by-priority-and-read-from-layout.md) states its rules. The settle phase in Choreo's render-pass barrier (below) is not built yet.
+
+## The problem
+
+A transcript changes height all the time, for many causes:
+
+- a reply streams;
+- a row's steps grow;
+- a turn folds or unfolds;
+- a question collapses into its answer;
+- an image or card loads;
+- the cap above the message box grows;
+- the reader opens a disclosure;
+- a motion layer moves things with transforms while their layout has already moved.
+
+Every one of these can move what the reader is looking at. A scroll owner can answer them with one rule per cause:
+
+- following pins the end;
+- a detached reader's top element is put back after a resize;
+- a prepend keeps the first row still;
+- a press in the content counts as the reader's for 500 ms;
+- an upward scroll with no input re-pins when the heights changed;
+- the app has its own scroll-into-view branches.
+
+Each rule is right on its own, but they don't compose. When two causes land in one frame, which rule wins depends on event order: a click that collapses a question while a reply streams, or a turn that folds while the cap grows. That's the yank the reader sees.
+
+The fix is one invariant, held by one owner, at one moment in the frame.
+
+## The invariant
+
+> In every render pass, one element is the **anchor**, and its top edge keeps the same distance from the viewport's top, by layout, from before the pass to after it. The one exception: when the anchor is the **end** (following), the content's bottom edge keeps its distance from the viewport's bottom.
+
+Everything else follows from that:
+
+- Content that changes below the anchor moves nothing the reader sees above it.
+- Content that changes above the anchor is paid for with a scroll correction of exactly the anchor's layout shift.
+- What moves on screen is only what changed between the anchor and the edge the change happened on. That's what the motion layer then animates.
+
+This is an algorithm, not a set of heuristics. The work is choosing the anchor well and correcting at the right moment.
+
+## Choosing the anchor
+
+Each pass picks the first of these that holds:
+
+| Priority | Anchor                | Holds when                                                                                                                                                                                                                                                                 | Why                                                                                                                                                                                                                |
+| -------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1        | **Navigation target** | the app asked to show something: the jump chip, "go to the waiting row", `reveal(id)`, a Quick Look closing back to its source; or focus moved into the content other than by a pointer press (Tab, a skip link, the app's `focus()`), which the browser scrolls into view | the app's intent is explicit; once it arrives, the target becomes the reading anchor                                                                                                                               |
+| 2        | **Pressed element**   | the reader pressed something in the content (pointer, or Enter or Space; focus that code moves does not count) less than 2 s ago and hasn't scrolled since: a toggle, a choice, Undo, a disclosure                                                                         | what they touched stays under their pointer, so an expand grows downward from it and a collapse shrinks toward it (macOS disclosure behaviour)                                                                     |
+| 3        | **End**               | following: the reader is at the end and hasn't left it by their own input                                                                                                                                                                                                  | new content arrives below, and the end stays in view                                                                                                                                                               |
+| 4        | **Reading line**      | otherwise                                                                                                                                                                                                                                                                  | the element crossing a line about a third of the way down the viewport, with its offset from that line: where eye-tracking puts a reader's attention, steadier than the top edge, which half-hidden elements cross |
+
+Priority 2 outranks 3 on purpose. A reader at the end who opens a fold shouldn't be pulled to the new end; they're reading what they opened. The pressed element is the anchor, not a timer that guesses.
+
+**What counts as an element.** Anchor candidates are the elements marked `data-scroll-anchor`: messages, rows, steps, answer blocks. Picking the deepest marked element that crosses the line keeps the anchor small enough to stay still while its parent grows around it (a message that streams below the step being read). In unmarked content, the anchor is the smallest element the line crosses.
+
+**Where the reader is.** Following stops on:
+
+- the reader's scroll input: a wheel, a touch, a scrolling key (also when its target is the body, as after a click on text), a press on the scrollbar;
+- a pressed or focused anchor (priority 1 or 2) that grows the content past the end: the reader caused it, and is reading what grew;
+- `navigate()` or `reveal()`;
+- a scroll the component did not write and no layout change caused (find in page, a stray `scrollIntoView`): it is taken as the reader's, because the next settle would otherwise pull it back to the end.
+
+A layout change alone (content shrank, the viewport grew, a clamp) never stops following; the clamp is corrected. Following starts again when a scroll reaches the end, or by `scrollToEnd()`.
+
+## When to correct: inside the render pass, before motion measures
+
+The correction must land after the DOM for the pass is in, and before anything measures or paints. StickToBottom settles in the render commit of a change it is told about (`@revision`, `@active`), and on resize. A host with a motion layer calls `settle()` after the pass commits and before the motion layer measures.
+
+Choreo's render-pass barrier (`far.ts`) has that moment: `runBarrier()` calls `beforeMeasure()` (Choreo's own mount flush), then every region's `measurePass()`, then MATCH and RUN. The plan adds a **SETTLE** phase there (not built yet):
+
+```
+render pass commits DOM
+  └─ Choreo barrier (afterRender)
+       0. MOUNT    flush pending mounts                      (exists)
+       1. SETTLE   every scroll owner holds its anchor        (planned)
+       2. MEASURE  every region builds its changeset          (exists)
+       3. MATCH    far matching across regions                (exists)
+       4. RUN      every region plays its score               (exists)
+  └─ browser paints
+```
+
+The protocol, per scroll owner:
+
+1. **Record (end of every pass, and on every reader scroll):** the anchor element (by the priority table) and its offset in the viewport, by layout: `layoutTop(anchor) − scrollTop`. For the end anchor, record `scrollHeight − scrollTop − clientHeight`.
+2. **Settle (phase 1 of the next pass):** read the anchor's new layout top and correct the position as below. Then re-record. If the anchor element left the DOM, fall back to its nearest surviving marked ancestor.
+   - Normally the recorded offset is held: `scrollTop += layoutTop(anchor) − scrollTop − recorded`. This also undoes a clamp when content shrank. For the end anchor, pin the end.
+   - While the reader scrolls (their input, or a scroll that follows it such as momentum, within a short window), only what layout moved is held: `scrollTop += layoutTop(anchor) − recordedLayoutTop`. A settle can run between their scroll and its scroll event, and holding the offset would take their step back.
+   - While the component's own smooth scroll is in flight, nothing is written: the smooth scroll's target moves by `layoutTop(anchor) − recordedLayoutTop`, or to the new end while following, so the scroll is not cut short.
+3. **Measure (phase 2):** Choreo measures in the scroller's viewport space after the correction. An element that holds its place on screen reads as not moved and gets no animation. Only what really moved on screen gets a FLIP, from its painted position before to its new one.
+
+**Layout, never paint.** The anchor's position is read from layout offsets (an `offsetTop` chain), which a running FLIP's transforms don't move. Choreo works from painted positions for its starts; the anchor works from layout for its correction. The two never fight: the correction is a layout fact, and the motion is drawn on top of it.
+
+**One pass, one clock.** Every cause that lands in the same frame is settled once, together, against one anchor. A click that collapses a question while a reply streams is one correction, not two that race.
+
+**Outside a render pass.** Some changes don't come from a render: an image decodes, fonts swap, the viewport resizes. The scroll owner's ResizeObserver runs the same settle step on its own (`onResize`), and the next pass's motion sees the result.
+
+## Architecture
+
+| Piece               | Where                                                                                                                                                | Does                                                                                                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ScrollCoordinator` | Pret UI, inside StickToBottom (one per scroller)                                                                                                     | holds the mode (follow or read), the navigation target and the pressed element with their times, and the recorded anchor; runs `record()` and `settle()` |
+| Anchor marks        | `data-scroll-anchor` on messages, rows, steps, answer blocks                                                                                         | bounds anchor candidates; no runtime cost                                                                                                                |
+| Reader input        | the existing wheel, touch, key and scrollbar listeners                                                                                               | the only path that changes the mode                                                                                                                      |
+| Navigation API      | `api.reveal(id)`, `api.scrollToEnd()`, `api.navigate(element, block)`, instead of the app's own `scrollIntoView` calls; focus moved into the content | sets priority 1                                                                                                                                          |
+| Press tracking      | `pointerdown`, and Enter or Space, in the content                                                                                                    | sets priority 2 (element and time)                                                                                                                       |
+| SETTLE phase        | planned: Choreo's barrier, run after MOUNT and before MEASURE                                                                                        | calls each live coordinator's `settle()`                                                                                                                 |
+| Fallback            | the coordinator's ResizeObserver                                                                                                                     | runs `settle()` for changes outside a render pass                                                                                                        |
+
+Prepend is "anchor = reading line" with nothing special about it. Send is "mode = follow". The jump chip is a navigation.
+
+**ADR 007 fit.** Scroll position is state, and it's settled before motion measures, so state never waits on motion (§1.1). One engine reacts (§1.2). ADR 012 records this as a decision.
+
+## Proving it
+
+The invariant is testable without a person watching:
+
+- **Property test** (kit, in the browser). Build a transcript of random rows. Apply random batches of operations in one pass each: insert above, below or inside the anchor; grow or shrink any row; fold or unfold; resize the viewport; press a random element first; scroll by input or by API. After every pass, assert the anchor's viewport offset is unchanged within 0.5 px, the end is pinned exactly when following, and the mode changed only on input. Run a few thousand seeded cases; a failure prints its seed and its operation list.
+- **Motion check.** With Choreo regions on, the same sequences assert that no element's painted top jumps more than its own layout delta in one frame (a probe of each element's painted top, made a test helper), and that `orphanCount()` is 0 after interruptions.
+- **Live probe.** A follow-gap sampler (every 100 ms: mode, gap, heights) as a dev-only overlay, so a reader reporting "it yanked" can turn it on and send the trace.
+
+## Build order
+
+1. **Coordinator in StickToBottom**, with the priority table, anchor marks and property tests. Built.
+2. **SETTLE phase in Choreo**, so the coordinator settles in it when a region is live and motion animates only what moved on screen. Not built. This is a Choreo change, so its PR title takes a conventional-commit prefix (`feat(choreo): …`).
+3. **The app's own scrolling moves onto the API** (`navigate`, `scrollToEnd`). Not in this package.
+4. **ADR**: ADR 012, proposed.
+
+## Open questions
+
+- **The reading line.** One third of the way down is a guess from reading research. It should be a token, tuned by watching where readers' last presses and selections land.
+- **Two scrollers.** When one scroller is inside another (a code block or table inside the transcript), the inner one settles first, then the outer. The barrier runs scroll owners innermost first.
+- **Smooth navigation.** A smooth `navigate` spans several frames. The coordinator moves the smooth scroll's target by what layout moved and writes no position while it is in flight. Whether a settle should also re-aim at the target element when the target's own height changes is open.
+
+[ADR 012](../../../docs/adr/012-hold-one-scroll-anchor-per-change-chosen-by-priority-and-read-from-layout.md) numbers the rules this protocol keeps. A change to scroll or follow behaviour updates ADR 012 in the same change.