🎨 fmt scroll spec

Author: cowboyd

specs/scroll-spec.md

@@ -6,13 +6,13 @@
 
 ## 1. Purpose
 
-This specification defines how clipped elements scroll their children. It
-covers the clip configuration API, the two scroll modes (manual and
-pointer-driven), and the interaction between them.
+This specification defines how clipped elements scroll their children. It covers
+the clip configuration API, the two scroll modes (manual and pointer-driven),
+and the interaction between them.
 
-Scrolling builds on the existing clip infrastructure described in the
-renderer spec (Section 12.2). This specification promotes clip/scroll from
-an elastic surface to a specified contract.
+Scrolling builds on the existing clip infrastructure described in the renderer
+spec (Section 12.2). This specification promotes clip/scroll from an elastic
+surface to a specified contract.
 
 ---
 
@@ -49,17 +49,17 @@ clip?: {
 
 Each axis is independently configured:
 
-- **`undefined`** (or omitted) — No clipping or scrolling on this axis.
-  Children may overflow visually.
-- **`number`** — Clipping is enabled. Children are offset by the given
-  value (in layout-engine units). The caller controls the offset each frame.
-  Typically negative to scroll content upward/leftward.
-- **`"pointer"`** — Clipping is enabled. The offset is managed by the
-  underlying layout engine's scroll system, driven by wheel events passed
-  via `RenderOptions.event`.
+- **`undefined`** (or omitted) — No clipping or scrolling on this axis. Children
+  may overflow visually.
+- **`number`** — Clipping is enabled. Children are offset by the given value (in
+  layout-engine units). The caller controls the offset each frame. Typically
+  negative to scroll content upward/leftward.
+- **`"pointer"`** — Clipping is enabled. The offset is managed by the underlying
+  layout engine's scroll system, driven by wheel events passed via
+  `RenderOptions.event`.
 
-A bare `clip` value is always an object with optional `x` and `y` fields.
-There is no shorthand form.
+A bare `clip` value is always an object with optional `x` and `y` fields. There
+is no shorthand form.
 
 ### 3.1 Examples
 
@@ -69,7 +69,7 @@ Vertical pointer scrolling (typical scroll container):
 open("list", {
   layout: { width: grow(), height: fixed(20) },
   clip: { y: "pointer" },
-})
+});
 ```
 
 Manual horizontal offset (e.g., programmatic scroll-to):
@@ -78,7 +78,7 @@ Manual horizontal offset (e.g., programmatic scroll-to):
 open("viewport", {
   layout: { width: fixed(40), height: fixed(10) },
   clip: { x: -scrollX },
-})
+});
 ```
 
 Mixed — horizontal manual, vertical pointer:
@@ -87,22 +87,22 @@ Mixed — horizontal manual, vertical pointer:
 open("editor", {
   layout: { width: grow(), height: grow() },
   clip: { x: -columnOffset, y: "pointer" },
-})
+});
 ```
 
 ---
 
 ## 4. Pointer-Driven Scrolling
 
-When an axis is set to `"pointer"`, the underlying layout engine manages
-scroll state for that axis across frames.
+When an axis is set to `"pointer"`, the underlying layout engine manages scroll
+state for that axis across frames.
 
 ### 4.1 Wheel scrolling
 
-When a `WheelEvent` is passed via `RenderOptions.event` and the wheel
-event's coordinates fall within a clip element that has a `"pointer"` axis,
-the layout engine applies the scroll delta to that axis. The innermost
-scroll container at the event coordinates takes priority.
+When a `WheelEvent` is passed via `RenderOptions.event` and the wheel event's
+coordinates fall within a clip element that has a `"pointer"` axis, the layout
+engine applies the scroll delta to that axis. The innermost scroll container at
+the event coordinates takes priority.
 
 ### 4.2 Clamping
 
@@ -113,19 +113,19 @@ within the container on a given axis cannot be scrolled on that axis.
 ### 4.3 Future: drag scrolling and momentum
 
 The clip configuration and rendering pipeline are designed to support
-pointer-driven drag scrolling with momentum in the future. The underlying
-layout engine already supports this via `Clay_UpdateScrollContainers`. When
-added, it would be an opt-in behavior — the current wheel-only scrolling
-would remain the default.
+pointer-driven drag scrolling with momentum in the future. The underlying layout
+engine already supports this via `Clay_UpdateScrollContainers`. When added, it
+would be an opt-in behavior — the current wheel-only scrolling would remain the
+default.
 
 ---
 
 ## 5. Input Event Integration
 
-Wheel events reach the scroll system via `RenderOptions.event`, which
-accepts a single `InputEvent` per render transaction. When the event is a
-`WheelEvent` whose coordinates fall within a pointer-driven scroll
-container, the layout engine applies the scroll delta.
+Wheel events reach the scroll system via `RenderOptions.event`, which accepts a
+single `InputEvent` per render transaction. When the event is a `WheelEvent`
+whose coordinates fall within a pointer-driven scroll container, the layout
+engine applies the scroll delta.
 
 The `event` field, its semantics, and the one-event-per-render contract are
 defined in the [Renderer Specification](renderer-spec.md), Section 8.2.3.
@@ -139,8 +139,8 @@ changes to support per-axis modes.
 
 For the clip configuration, the transfer encoding includes:
 
-- A packed word with axis modes: low byte = x mode, next byte = y mode.
-  Mode values: `0` = off, `1` = manual, `2` = pointer.
+- A packed word with axis modes: low byte = x mode, next byte = y mode. Mode
+  values: `0` = off, `1` = manual, `2` = pointer.
 - For each axis in mode `1` (manual): a float32 offset value.
 
 When mode is `2`, no offset value is encoded. The C side reads the scroll
@@ -154,37 +154,36 @@ while the element is open.
 When decoding a clip configuration, the C side:
 
 1. Reads axis modes from the packed word.
-2. Sets `decl.clip.horizontal` / `decl.clip.vertical` to true for any
-   non-zero mode.
+2. Sets `decl.clip.horizontal` / `decl.clip.vertical` to true for any non-zero
+   mode.
 3. For manual axes, reads the offset from the buffer.
 4. For pointer axes, reads the offset from `Clay_GetScrollOffset()`.
 5. Combines both into `decl.clip.childOffset`.
 
-This happens while the element is open (between `Clay__OpenElementWithId`
-and `Clay__ConfigureOpenElement`), so `Clay_GetScrollOffset()` resolves to
-the correct element.
+This happens while the element is open (between `Clay__OpenElementWithId` and
+`Clay__ConfigureOpenElement`), so `Clay_GetScrollOffset()` resolves to the
+correct element.
 
 ---
 
 ## 8. Invariants
 
-**SCROLL-1.** A clip axis set to `undefined` MUST NOT clip children on that
-axis and MUST NOT participate in scroll input handling.
+**SCROLL-1.** A clip axis set to `undefined` MUST NOT clip children on that axis
+and MUST NOT participate in scroll input handling.
 
-**SCROLL-2.** A numeric clip axis MUST clip children and offset them by
-exactly the provided value each frame. The layout engine's internal scroll
-state for that axis MUST NOT affect the rendered offset.
+**SCROLL-2.** A numeric clip axis MUST clip children and offset them by exactly
+the provided value each frame. The layout engine's internal scroll state for
+that axis MUST NOT affect the rendered offset.
 
-**SCROLL-3.** A `"pointer"` clip axis MUST clip children and derive the
-offset from the layout engine's scroll state, which is updated by wheel
-events.
+**SCROLL-3.** A `"pointer"` clip axis MUST clip children and derive the offset
+from the layout engine's scroll state, which is updated by wheel events.
 
-**SCROLL-4.** Manual and pointer modes MAY be mixed on different axes of
-the same element.
+**SCROLL-4.** Manual and pointer modes MAY be mixed on different axes of the
+same element.
 
-**SCROLL-5.** Scroll position on pointer axes MUST be clamped to content
-bounds. A container whose content fits within it on a given axis MUST NOT
-scroll on that axis.
+**SCROLL-5.** Scroll position on pointer axes MUST be clamped to content bounds.
+A container whose content fits within it on a given axis MUST NOT scroll on that
+axis.
 
 **SCROLL-6.** When `RenderOptions.event` carries a `WheelEvent`, the scroll
 delta MUST be applied to the innermost pointer-driven scroll container whose
@@ -238,40 +237,47 @@ logical scroll position as a positive number. Clayterm negates it internally
 before passing to the layout engine.
 
 ```ts
-clip: { y: 20 }  // "show content starting at position 20"
+clip: {
+  y: 20;
+} // "show content starting at position 20"
 ```
 
 Pros:
+
 - Matches `scrollTop` / `scrollLeft` conventions from the browser.
 - More intuitive — "scroll to 20" rather than "offset by -20".
-- Callers never deal with negative values for a conceptually positive
-  quantity.
+- Callers never deal with negative values for a conceptually positive quantity.
 
 Cons:
-- Introduces a sign inversion between the API and the underlying layout
-  engine, which could confuse contributors reading the C code.
+
+- Introduces a sign inversion between the API and the underlying layout engine,
+  which could confuse contributors reading the C code.
 - Inconsistent with Clay's `childOffset` model, which uses negative values
   natively.
-- Clipping without scrolling (`clip: { y: 0 }`) works identically either
-  way, but the mental model differs — 0 means "scroll position zero" vs
-  "zero offset."
+- Clipping without scrolling (`clip: { y: 0 }`) works identically either way,
+  but the mental model differs — 0 means "scroll position zero" vs "zero
+  offset."
 
-**Option B: Negative (raw offset semantics).** The caller provides the raw
-pixel offset, typically negative. Clayterm passes it through to the layout
-engine unchanged.
+**Option B: Negative (raw offset semantics).** The caller provides the raw pixel
+offset, typically negative. Clayterm passes it through to the layout engine
+unchanged.
 
 ```ts
-clip: { y: -20 }  // "offset children by -20 pixels"
+clip: {
+  y: -20;
+} // "offset children by -20 pixels"
 ```
 
 Pros:
+
 - Direct mapping to Clay's `childOffset` — no hidden transformation.
 - Transparent to anyone reading the implementation.
 - Allows positive offsets if the caller genuinely wants to shift content
   downward/rightward (unusual but not impossible).
 
 Cons:
+
 - Unnatural for the common case — scrolling down requires negative numbers.
-- Easy to get the sign wrong, especially for callers unfamiliar with the
-  layout engine internals.
+- Easy to get the sign wrong, especially for callers unfamiliar with the layout
+  engine internals.
 - Every scroll-position calculation needs manual negation.