docs: record gap-adjust wheel chord in input contracts

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

Author: Gnathonic

docs/INPUT-CONTRACTS.md

@@ -112,7 +112,14 @@ Zoom settles carry a `SettleReason` (`zoom-controller.ts`): only
 | Pinch survivor | keeps panning                     | ignored until fresh press               |
 | Tap commit     | immediate                         | deferred (300 ms)                       |
 | Swipe-to-flip  | yes (mobile setting, edge-gated)  | no (panning is the scroll)              |
-| Wheel          | zoom or camera glide              | zoom or (native/strip) scroll           |
+| Wheel          | zoom, gap, or camera glide        | zoom, gap, or (native/strip) scroll     |
+
+Ctrl/meta+shift+wheel is the page-gap adjustment chord on every surface
+(paged writes `pagedGap`; scroll readers write `scrollGap` and sync
+`pageDividers`), checked before the zoom intent. Binding rule: wheel combos
+with a native browser meaning keep that meaning tuned for the reader
+(ctrl+wheel zooms, shift+wheel stays a horizontal pan); the gap chord is
+deliberately one no browser binds.
 
 ## Testing
 

docs/superpowers/plans/2026-07-05-page-gap-234.md

@@ -25,10 +25,12 @@
 ### Task 1: `pagedGap` setting
 
 **Files:**
+
 - Modify: `src/lib/settings/settings.ts:166` (type), `src/lib/settings/settings.ts:313` (default)
 - Test: `src/lib/settings/settings.test.ts`
 
 **Interfaces:**
+
 - Produces: `Settings.pagedGap: number` (default `0`) — read by Tasks 4, 5, 7 as `$settings.pagedGap`.
 
 - [ ] **Step 1: Write the failing test**
@@ -55,8 +57,8 @@ Expected: FAIL — `expected undefined to be 0`
 In `src/lib/settings/settings.ts`, after the `scrollGap` type field (line ~166):
 
 ```typescript
-  scrollGap: number; // Pixels of padding between pages in scroll modes
-  pagedGap: number; // Gap between a paged-mode spread's two pages (image px, scales with zoom)
+scrollGap: number; // Pixels of padding between pages in scroll modes
+pagedGap: number; // Gap between a paged-mode spread's two pages (image px, scales with zoom)
 ```
 
 In `defaultSettings` after `scrollGap: 0,` (line ~313):
@@ -83,10 +85,12 @@ git commit -m "feat(settings): add pagedGap setting"
 ### Task 2: `spreadContentSize` helper
 
 **Files:**
+
 - Modify: `src/lib/reader/paged-zoom-layout.ts` (append after `panEdgeState`)
 - Test: `src/lib/reader/paged-zoom-layout.test.ts`
 
 **Interfaces:**
+
 - Consumes: `Size` (already exported from this module).
 - Produces: `spreadContentSize(first: Size, second: Size | null, gap: number): Size` — used by Task 4 in `Reader.svelte`.
 
@@ -159,11 +163,13 @@ git commit -m "feat(reader): spreadContentSize includes the pair gap in fit math
 ### Task 3: Gap wheel intent helpers
 
 **Files:**
+
 - Modify: `src/lib/reader/zoom-math.ts` (after `normalizeWheelDelta`, line ~120)
 - Test: `src/lib/reader/zoom-math.test.ts`
 - Modify: `docs/superpowers/specs/2026-07-05-page-gap-234-design.md` (amend helper section)
 
 **Interfaces:**
+
 - Consumes: `normalizeWheelDelta`, `WheelAccumulator` (same module).
 - Produces (used by Tasks 5–7):
   - `MAX_PAGE_GAP = 100` (const)
@@ -212,7 +218,10 @@ describe('gapWheelSteps', () => {
     const acc = new WheelAccumulator(GAP_WHEEL_STEP_SIZE);
     let total = 0;
     for (let i = 0; i < 4; i++) {
-      total += gapWheelSteps({ deltaX: 0, deltaY: -6, deltaMode: 0, timeStamp: 1000 + i * 16 }, acc);
+      total += gapWheelSteps(
+        { deltaX: 0, deltaY: -6, deltaMode: 0, timeStamp: 1000 + i * 16 },
+        acc
+      );
     }
     expect(total).toBe(1); // 24 wheel px accumulated -> one 20px step
   });
@@ -302,9 +311,11 @@ git commit -m "feat(reader): gap-adjust wheel intent helpers"
 ### Task 4: Paged rendering + fit math
 
 **Files:**
+
 - Modify: `src/lib/components/Reader/Reader.svelte:376-389` (pagedContentSize), `:1204-1211` (flex row), imports at top of `<script>`.
 
 **Interfaces:**
+
 - Consumes: `spreadContentSize` (Task 2), `$settings.pagedGap` (Task 1).
 - Produces: paged spread renders with `column-gap`; `pagedContentSize` includes the gap (PagedViewport re-fits automatically via its `contentSize` signature).
 
@@ -367,10 +378,12 @@ git commit -m "feat(reader): render pagedGap between spread pages (#234)"
 ### Task 5: Paged surface wheel chord + toast
 
 **Files:**
+
 - Modify: `src/lib/components/Reader/PagedViewport.svelte` (Props, imports, `handleWheel`)
 - Modify: `src/lib/components/Reader/Reader.svelte` (`handleGapChange` near `showNotification` line ~887; `onGapChange` prop at the `<PagedViewport` usage line ~1171)
 
 **Interfaces:**
+
 - Consumes: `wheelIntentIsGapAdjust`, `gapWheelSteps`, `WheelAccumulator`, `GAP_WHEEL_STEP_SIZE`, `MAX_PAGE_GAP` (Task 3); `updateSetting` from `$lib/settings`.
 - Produces: `PagedViewport` prop `onGapChange?: (px: number) => void`; Reader's `handleGapChange(px: number)` (reused by Task 6).
 
@@ -406,34 +419,34 @@ and add `onGapChange` to the destructuring.
 Above `handleWheel`, add:
 
 ```typescript
-  const gapAccumulator = new WheelAccumulator(GAP_WHEEL_STEP_SIZE);
+const gapAccumulator = new WheelAccumulator(GAP_WHEEL_STEP_SIZE);
 
-  function adjustGap(delta: number) {
-    if (delta === 0) return;
-    const next = Math.max(0, Math.min(MAX_PAGE_GAP, ($settings.pagedGap ?? 0) + delta));
-    updateSetting('pagedGap', next);
-    onGapChange?.(next);
-  }
+function adjustGap(delta: number) {
+  if (delta === 0) return;
+  const next = Math.max(0, Math.min(MAX_PAGE_GAP, ($settings.pagedGap ?? 0) + delta));
+  updateSetting('pagedGap', next);
+  onGapChange?.(next);
+}
 ```
 
 At the TOP of `handleWheel` (before `const modifier = …`):
 
 ```typescript
-    if (wheelIntentIsGapAdjust(e)) {
-      e.preventDefault();
-      adjustGap(gapWheelSteps(e, gapAccumulator));
-      return;
-    }
+if (wheelIntentIsGapAdjust(e)) {
+  e.preventDefault();
+  adjustGap(gapWheelSteps(e, gapAccumulator));
+  return;
+}
 ```
 
 - [ ] **Step 2: Wire the toast in Reader**
 
 In `src/lib/components/Reader/Reader.svelte`, after the `showNotification` function (line ~901):
 
 ```typescript
-  function handleGapChange(px: number) {
-    showNotification(`Page gap: ${px}px`, 'page-gap');
-  }
+function handleGapChange(px: number) {
+  showNotification(`Page gap: ${px}px`, 'page-gap');
+}
 ```
 
 At the `<PagedViewport` usage (line ~1171), add the prop:
@@ -468,11 +481,13 @@ git commit -m "feat(reader): ctrl+shift+scroll adjusts pagedGap in paged mode"
 ### Task 6: Scroll surfaces wheel chord
 
 **Files:**
+
 - Modify: `src/lib/components/Reader/HorizontalScrollReader.svelte` (Props line ~21, imports, `handleWheel` line ~346)
 - Modify: `src/lib/components/Reader/VerticalScrollReader.svelte` (Props line ~21, imports, `handleWheel` line ~343)
 - Modify: `src/lib/components/Reader/Reader.svelte` (pass `onGapChange={handleGapChange}` to both usages, lines ~1140-1166)
 
 **Interfaces:**
+
 - Consumes: Task 3 helpers; Reader's `handleGapChange` (Task 5); `updateSetting` from `$lib/settings` (both files already import `settings`; extend that import).
 - Produces: both scroll readers accept `onGapChange?: (px: number) => void`; the chord writes `scrollGap` and syncs `pageDividers = gap > 0`.
 
@@ -492,28 +507,28 @@ Add to `interface Props` (after `onOverlayToggle?`) and to the `$props()` destru
 Add above `handleWheel`:
 
 ```typescript
-  const gapAccumulator = new WheelAccumulator(GAP_WHEEL_STEP_SIZE);
-
-  // The chord drives the continuous-mode dividers: gap > 0 means dividers on,
-  // reaching 0 turns them off (the M toggle keeps working independently).
-  function adjustGap(delta: number) {
-    if (delta === 0) return;
-    const next = Math.max(0, Math.min(MAX_PAGE_GAP, $settings.scrollGap + delta));
-    updateSetting('scrollGap', next);
-    const dividers = next > 0;
-    if ($settings.pageDividers !== dividers) updateSetting('pageDividers', dividers);
-    onGapChange?.(next);
-  }
+const gapAccumulator = new WheelAccumulator(GAP_WHEEL_STEP_SIZE);
+
+// The chord drives the continuous-mode dividers: gap > 0 means dividers on,
+// reaching 0 turns them off (the M toggle keeps working independently).
+function adjustGap(delta: number) {
+  if (delta === 0) return;
+  const next = Math.max(0, Math.min(MAX_PAGE_GAP, $settings.scrollGap + delta));
+  updateSetting('scrollGap', next);
+  const dividers = next > 0;
+  if ($settings.pageDividers !== dividers) updateSetting('pageDividers', dividers);
+  onGapChange?.(next);
+}
 ```
 
 In `handleWheel`, directly after the `if (!scrollContainer) return;` guard (both files):
 
 ```typescript
-    if (wheelIntentIsGapAdjust(e)) {
-      e.preventDefault();
-      adjustGap(gapWheelSteps(e, gapAccumulator));
-      return;
-    }
+if (wheelIntentIsGapAdjust(e)) {
+  e.preventDefault();
+  adjustGap(gapWheelSteps(e, gapAccumulator));
+  return;
+}
 ```
 
 (In VerticalScrollReader the `preventDefault` matters doubly: the surface scrolls natively, and without it the browser would treat ctrl+wheel as page zoom.)
@@ -541,9 +556,11 @@ git commit -m "feat(reader): ctrl+shift+scroll adjusts dividers in continuous mo
 ### Task 7: Settings UI
 
 **Files:**
+
 - Modify: `src/lib/components/Settings/Reader/ReaderSettings.svelte` (isPaged block line ~90-104; divider slider label line ~127)
 
 **Interfaces:**
+
 - Consumes: `$settings.pagedGap`, `updateSetting` (already imported), `MAX_PAGE_GAP` (Task 3), `Range`/`Label` (already imported).
 
 - [ ] **Step 1: Add the paged gap slider**
@@ -574,10 +591,10 @@ Inside the `{#if isPaged}` block, after the page-view-mode `</div>` (line ~103),
 Change the divider-size label (line ~127) to:
 
 ```svelte
-          <Label class="text-gray-900 dark:text-white">
-            Divider size: {$settings.scrollGap}px
-            <span class="ml-2 text-xs text-gray-500 dark:text-gray-400">(Ctrl+Shift+Scroll)</span>
-          </Label>
+<Label class="text-gray-900 dark:text-white">
+  Divider size: {$settings.scrollGap}px
+  <span class="ml-2 text-xs text-gray-500 dark:text-gray-400">(Ctrl+Shift+Scroll)</span>
+</Label>
 ```
 
 and change that slider's `max={100}` to `max={MAX_PAGE_GAP}`.
@@ -599,14 +616,15 @@ git commit -m "feat(settings): page gap slider + chord hints"
 ### Task 8: Input contracts doc + full verification
 
 **Files:**
+
 - Modify: `docs/INPUT-CONTRACTS.md:115` (wheel row) + new paragraph after the matrix
 
 - [ ] **Step 1: Update the contracts doc**
 
 Change the wheel row of the per-surface policy matrix:
 
 ```markdown
-| Wheel          | zoom, gap, or camera glide        | zoom, gap, or (native/strip) scroll     |
+| Wheel | zoom, gap, or camera glide | zoom, gap, or (native/strip) scroll |
 ```
 
 After the matrix table, add: