cursedbelt 5.96.1 → 5.98.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/dist/react/components/PaneSplit.d.ts +11 -2
  2. package/dist/react/components/PaneSplit.d.ts.map +1 -1
  3. package/dist/react/components/PaneSplit.js +12 -11
  4. package/dist/react/components/PaneSplit.js.map +1 -1
  5. package/dist/react/components/PanelGrid.d.ts +14 -8
  6. package/dist/react/components/PanelGrid.d.ts.map +1 -1
  7. package/dist/react/components/PanelGrid.js +10 -3
  8. package/dist/react/components/PanelGrid.js.map +1 -1
  9. package/dist/react/components/SplitPane.d.ts +3 -9
  10. package/dist/react/components/SplitPane.d.ts.map +1 -1
  11. package/dist/react/components/SplitPane.js +0 -3
  12. package/dist/react/components/SplitPane.js.map +1 -1
  13. package/dist/react/components/paneSplit.css +8 -0
  14. package/dist/react/filter-rail/railResize.d.ts +16 -5
  15. package/dist/react/filter-rail/railResize.d.ts.map +1 -1
  16. package/dist/react/filter-rail/railResize.js +27 -9
  17. package/dist/react/filter-rail/railResize.js.map +1 -1
  18. package/dist/react/filter-rail/railWidth.d.ts +10 -5
  19. package/dist/react/filter-rail/railWidth.d.ts.map +1 -1
  20. package/dist/react/filter-rail/railWidth.js +13 -8
  21. package/dist/react/filter-rail/railWidth.js.map +1 -1
  22. package/dist/react/index.d.ts +1 -0
  23. package/dist/react/index.d.ts.map +1 -1
  24. package/dist/react/index.js +1 -0
  25. package/dist/react/index.js.map +1 -1
  26. package/dist/react/lib/paneReach.d.ts +36 -0
  27. package/dist/react/lib/paneReach.d.ts.map +1 -0
  28. package/dist/react/lib/paneReach.js +72 -0
  29. package/dist/react/lib/paneReach.js.map +1 -0
  30. package/dist/react/master-detail/MasterDetail.d.ts +6 -3
  31. package/dist/react/master-detail/MasterDetail.d.ts.map +1 -1
  32. package/dist/react/master-detail/MasterDetail.js +3 -2
  33. package/dist/react/master-detail/MasterDetail.js.map +1 -1
  34. package/dist/react/media/FocusViewer.d.ts.map +1 -1
  35. package/dist/react/media/FocusViewer.js +3 -2
  36. package/dist/react/media/FocusViewer.js.map +1 -1
  37. package/dist/react/media/ImageOriginalToggle.d.ts +20 -0
  38. package/dist/react/media/ImageOriginalToggle.d.ts.map +1 -0
  39. package/dist/react/media/ImageOriginalToggle.js +16 -0
  40. package/dist/react/media/ImageOriginalToggle.js.map +1 -0
  41. package/dist/react/media/VideoPlayer.d.ts.map +1 -1
  42. package/dist/react/media/VideoPlayer.js +9 -3
  43. package/dist/react/media/VideoPlayer.js.map +1 -1
  44. package/dist/react/media/VideoQualitySelect.d.ts +24 -0
  45. package/dist/react/media/VideoQualitySelect.d.ts.map +1 -0
  46. package/dist/react/media/VideoQualitySelect.js +34 -0
  47. package/dist/react/media/VideoQualitySelect.js.map +1 -0
  48. package/dist/react/media/hlsSource.d.ts +14 -2
  49. package/dist/react/media/hlsSource.d.ts.map +1 -1
  50. package/dist/react/media/hlsSource.js +27 -6
  51. package/dist/react/media/hlsSource.js.map +1 -1
  52. package/dist/react/media/imageOriginal.d.ts +69 -0
  53. package/dist/react/media/imageOriginal.d.ts.map +1 -0
  54. package/dist/react/media/imageOriginal.js +98 -0
  55. package/dist/react/media/imageOriginal.js.map +1 -0
  56. package/dist/react/media/imageOriginalEntry.d.ts +9 -0
  57. package/dist/react/media/imageOriginalEntry.d.ts.map +1 -0
  58. package/dist/react/media/imageOriginalEntry.js +9 -0
  59. package/dist/react/media/imageOriginalEntry.js.map +1 -0
  60. package/dist/react/media/index.d.ts +5 -0
  61. package/dist/react/media/index.d.ts.map +1 -1
  62. package/dist/react/media/index.js +6 -0
  63. package/dist/react/media/index.js.map +1 -1
  64. package/dist/react/media/useImageOriginal.d.ts +21 -0
  65. package/dist/react/media/useImageOriginal.d.ts.map +1 -0
  66. package/dist/react/media/useImageOriginal.js +63 -0
  67. package/dist/react/media/useImageOriginal.js.map +1 -0
  68. package/dist/react/media/videoEnhance.d.ts +1 -1
  69. package/dist/react/media/videoEnhance.js +1 -1
  70. package/dist/react/media/videoPlayer.css +23 -0
  71. package/dist/react/media/videoQuality.d.ts +113 -0
  72. package/dist/react/media/videoQuality.d.ts.map +1 -0
  73. package/dist/react/media/videoQuality.js +185 -0
  74. package/dist/react/media/videoQuality.js.map +1 -0
  75. package/dist/react/media/vidstackQuality.d.ts +27 -0
  76. package/dist/react/media/vidstackQuality.d.ts.map +1 -0
  77. package/dist/react/media/vidstackQuality.js +51 -0
  78. package/dist/react/media/vidstackQuality.js.map +1 -0
  79. package/dist/react/media-gallery/MediaGallery.d.ts.map +1 -1
  80. package/dist/react/media-gallery/MediaGallery.js +42 -10
  81. package/dist/react/media-gallery/MediaGallery.js.map +1 -1
  82. package/dist/react/media-gallery/mediaGallery.css +42 -0
  83. package/dist/react/media-gallery/mediaGalleryModel.d.ts.map +1 -1
  84. package/dist/react/media-gallery/mediaGalleryModel.js +5 -2
  85. package/dist/react/media-gallery/mediaGalleryModel.js.map +1 -1
  86. package/dist/react/media-gallery/types.d.ts +10 -0
  87. package/dist/react/media-gallery/types.d.ts.map +1 -1
  88. package/dist/react/sharing/SharePanel.d.ts.map +1 -1
  89. package/dist/react/sharing/SharePanel.js +2 -1
  90. package/dist/react/sharing/SharePanel.js.map +1 -1
  91. package/dist/scripts/guardrailsEnforce.d.ts.map +1 -1
  92. package/dist/testing/phoneRules.js +3 -3
  93. package/dist/testing/phoneRules.js.map +1 -1
  94. package/package.json +9 -2
  95. package/scripts/guardrailsEnforce.spec.ts +25 -0
  96. package/scripts/guardrailsEnforce.ts +61 -0
  97. package/scripts/paths.ts +1 -1
  98. package/scripts/styleAreas.ts +2 -1
  99. package/src/react/components/PaneSplit.spec.tsx +26 -3
  100. package/src/react/components/PaneSplit.tsx +26 -13
  101. package/src/react/components/PanelGrid.tsx +16 -11
  102. package/src/react/components/SplitPane.spec.tsx +10 -5
  103. package/src/react/components/SplitPane.tsx +3 -12
  104. package/src/react/components/paneSplit.css +8 -0
  105. package/src/react/filter-rail/FilterRail.spec.tsx +7 -3
  106. package/src/react/filter-rail/railResize.spec.tsx +27 -5
  107. package/src/react/filter-rail/railResize.tsx +46 -15
  108. package/src/react/filter-rail/railWidth.ts +13 -8
  109. package/src/react/index.ts +1 -0
  110. package/src/react/lib/paneReach.spec.ts +58 -0
  111. package/src/react/lib/paneReach.ts +65 -0
  112. package/src/react/master-detail/MasterDetail.tsx +10 -5
  113. package/src/react/media/FocusViewer.tsx +9 -1
  114. package/src/react/media/ImageOriginalToggle.tsx +49 -0
  115. package/src/react/media/VideoPlayer.spec.tsx +44 -1
  116. package/src/react/media/VideoPlayer.tsx +17 -3
  117. package/src/react/media/VideoQualitySelect.spec.tsx +47 -0
  118. package/src/react/media/VideoQualitySelect.tsx +81 -0
  119. package/src/react/media/hlsSource.spec.ts +10 -0
  120. package/src/react/media/hlsSource.ts +41 -7
  121. package/src/react/media/imageOriginal.spec.tsx +177 -0
  122. package/src/react/media/imageOriginal.ts +114 -0
  123. package/src/react/media/imageOriginalEntry.ts +8 -0
  124. package/src/react/media/index.ts +9 -0
  125. package/src/react/media/useImageOriginal.ts +97 -0
  126. package/src/react/media/videoEnhance.ts +1 -1
  127. package/src/react/media/videoPlayer.css +23 -0
  128. package/src/react/media/videoQuality.spec.ts +135 -0
  129. package/src/react/media/videoQuality.ts +248 -0
  130. package/src/react/media/vidstackQuality.tsx +65 -0
  131. package/src/react/media-gallery/MediaGallery.spec.tsx +26 -0
  132. package/src/react/media-gallery/MediaGallery.tsx +57 -17
  133. package/src/react/media-gallery/mediaGallery.css +42 -0
  134. package/src/react/media-gallery/mediaGalleryModel.ts +4 -2
  135. package/src/react/media-gallery/types.ts +10 -0
  136. package/src/react/sharing/SharePanel.tsx +2 -1
  137. package/src/testing/phoneRules.ts +2 -2
@@ -40,6 +40,14 @@
40
40
  min-height: 0;
41
41
  }
42
42
 
43
+ /* A shut pane (dragged to nothing — `lib/paneReach.ts`) draws nothing and takes no focus; its
44
+ content would otherwise spill out of a zero-wide track. The seam beside it is a sibling, so it
45
+ stays to drag the pane open again. */
46
+ .cb-panesplit__cell[data-shut] {
47
+ visibility: hidden;
48
+ overflow: hidden;
49
+ }
50
+
43
51
  .cb-panesplit__seam {
44
52
  flex: 0 0 auto;
45
53
  position: relative;
@@ -580,10 +580,14 @@ describe('FilterRail — resizeKey', () => {
580
580
  expect(globalThis.localStorage?.getItem('test:rail')).toBeNull();
581
581
  });
582
582
 
583
- test('the width is clamped — it cannot be dragged into a sliver', () => {
584
- globalThis.localStorage?.setItem('test:rail', '20');
585
- const { container } = render(<FilterRail {...props} resizeKey='test:rail' />);
583
+ test('a stored sliver is never drawn — it opens at the snap, or shut below half of it', () => {
584
+ globalThis.localStorage?.setItem('test:rail', '120');
585
+ const { container, unmount } = render(<FilterRail {...props} resizeKey='test:rail' />);
586
586
  expect((container.querySelector('nav') as HTMLElement).style.width).toBe('160px');
587
+ unmount();
588
+ globalThis.localStorage?.setItem('test:rail', '20');
589
+ const shut = render(<FilterRail {...props} resizeKey='test:rail' />);
590
+ expect((shut.container.querySelector('nav') as HTMLElement).style.width).toBe('0px');
587
591
  });
588
592
 
589
593
  test('no handle while collapsed', () => {
@@ -49,13 +49,35 @@ describe('useRailResize + RailResizeHandle', () => {
49
49
  expect(aside.style.width).toBe('250px');
50
50
  });
51
51
 
52
- test('a drag past either bound stops at it', () => {
52
+ // The owner, 2026-10-27: "let me drag them as far as I want including shutting a pane completely".
53
+ test('no wall: a drag reaches the whole row one way and shuts the rail the other', () => {
53
54
  const { aside, handle } = parts(render(<Sidebar resizeKey='t:rail' />).container);
54
- fireEvent.pointerDown(handle as HTMLElement, { button: 0, clientX: 0, pointerId: 1 });
55
- fireEvent.pointerMove(handle as HTMLElement, { clientX: 5000, pointerId: 1 });
56
- expect(aside.style.width).toBe('640px');
57
- fireEvent.pointerMove(handle as HTMLElement, { clientX: 10, pointerId: 1 });
55
+ const h = handle as HTMLElement;
56
+ // happy-dom lays nothing out, so the row is the window's width.
57
+ const row = globalThis.innerWidth;
58
+ fireEvent.pointerDown(h, { button: 0, clientX: 0, pointerId: 1 });
59
+ fireEvent.pointerMove(h, { clientX: 5000, pointerId: 1 });
60
+ expect(aside.style.width).toBe(`${row}px`);
61
+ expect(aside.style.maxWidth).toBe('100%');
62
+ // Between half the snap and the snap it holds — no sliver of a rail.
63
+ fireEvent.pointerMove(h, { clientX: 100, pointerId: 1 });
64
+ expect(aside.style.width).toBe('160px');
65
+ fireEvent.pointerMove(h, { clientX: 60, pointerId: 1 });
66
+ fireEvent.pointerUp(h, { clientX: 60, pointerId: 1 });
67
+ expect(aside.style.width).toBe('0px');
68
+ expect(aside.style.visibility).toBe('hidden');
69
+ expect(globalThis.localStorage?.getItem('t:rail')).toBe('0');
70
+ // Shut, the handle is still there to drag it back, and an arrow opens it at the snap.
71
+ expect(h.style.visibility).toBe('visible');
72
+ fireEvent.keyDown(h, { key: 'ArrowRight' });
58
73
  expect(aside.style.width).toBe('160px');
74
+ expect(aside.style.visibility).toBe('');
75
+ });
76
+
77
+ test('a shut rail is remembered shut', () => {
78
+ globalThis.localStorage?.setItem('t:rail', '0');
79
+ const { aside } = parts(render(<Sidebar resizeKey='t:rail' />).container);
80
+ expect(aside.style.width).toBe('0px');
59
81
  });
60
82
 
61
83
  test('a right-button press is not a drag', () => {
@@ -13,15 +13,19 @@
13
13
  * reach;
14
14
  * - **a `separator` role with real `aria-value*`**, the ARIA splitter pattern;
15
15
  * - **double-click resets** to the rail's own default width, and forgets the stored one;
16
- * - remembered on RELEASE — a drag is one decision, not sixty writes a second.
16
+ * - remembered on RELEASE — a drag is one decision, not sixty writes a second;
17
+ * - 🔴 **no wall** (the owner, 2026-10-27): the drag reaches the far side of the row the rail
18
+ * shares, and below half of `MIN_RAIL_PX` the rail SHUTS — `lib/paneReach.ts`, the rule every
19
+ * cursedbelt divider obeys. A shut rail draws nothing but its handle, at the edge, to drag back.
17
20
  *
18
- * Clamp and storage are `railWidth.ts`, so the width is announced through `preferenceSync`
19
- * like every other viewer preference.
21
+ * Storage is `railWidth.ts`, so the width is announced through `preferenceSync` like every other
22
+ * viewer preference.
20
23
  */
21
24
  import type { CSSProperties, KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent, RefObject } from 'react';
22
25
  import { useCallback, useRef, useState } from 'react';
23
26
  import { cn } from '../lib/cn.js';
24
- import { clampRailWidth, MAX_RAIL_PX, MIN_RAIL_PX, readRailWidth, writeRailWidth } from './railWidth.js';
27
+ import { reachSize, stepSize } from '../lib/paneReach.js';
28
+ import { MIN_RAIL_PX, readRailWidth, writeRailWidth } from './railWidth.js';
25
29
 
26
30
  export interface UseRailResizeOptions {
27
31
  /** Where the width is remembered. Absent: not resizable — no handle, no stored width. */
@@ -37,9 +41,15 @@ export interface RailResize<E extends HTMLElement = HTMLElement> {
37
41
  railRef: RefObject<E | null>;
38
42
  /** Whether a handle is drawn: a `resizeKey` was given and `enabled` is true. */
39
43
  active: boolean;
40
- /** The dragged width in px, or `null` for "the rail's own default width". Null while inactive. */
44
+ /** The dragged width in px (0 = shut), or `null` for "the rail's own default width". Null while inactive. */
41
45
  width: number | null;
42
- /** `{ width }` while there is a dragged width, else `undefined` — spread onto the rail's `style`. */
46
+ /** Dragged all the way shut. The rail must then draw nothing but the handle — `style` does it. */
47
+ shut: boolean;
48
+ /**
49
+ * Spread onto the rail's `style` — `undefined` at the default width. 🔴 Spread ALL of it, not
50
+ * just `width`: a shut rail is also borderless and `visibility: hidden` (its content would
51
+ * otherwise spill out of a zero-wide box), and a wide one is held to its row by `maxWidth`.
52
+ */
43
53
  style: CSSProperties | undefined;
44
54
  /** Forget the dragged width (what a double-click on the handle does). */
45
55
  reset: () => void;
@@ -50,6 +60,8 @@ export interface RailResize<E extends HTMLElement = HTMLElement> {
50
60
  onKeyDown: (event: ReactKeyboardEvent<HTMLElement>) => void;
51
61
  /** The rail's current rendered width, for `aria-valuenow` before any drag. */
52
62
  measure: () => number;
63
+ /** The width of the row the rail shares — how far it can grow. */
64
+ room: () => number;
53
65
  };
54
66
  }
55
67
 
@@ -62,6 +74,12 @@ export function useRailResize<E extends HTMLElement = HTMLElement>({
62
74
  const [dragged, setDragged] = useState<number | null>(() => (resizeKey ? readRailWidth(resizeKey) : null));
63
75
  const active = Boolean(resizeKey) && enabled;
64
76
  const measure = useCallback(() => railRef.current?.getBoundingClientRect().width ?? MIN_RAIL_PX, []);
77
+ // The row the rail shares with the page it navigates. A box with no layout (a test DOM, a hidden
78
+ // tab) measures 0, so the window stands in — never 0, which would make every width "shut".
79
+ const room = useCallback(() => {
80
+ const row = railRef.current?.parentElement?.getBoundingClientRect().width ?? 0;
81
+ return row > 0 ? row : globalThis.innerWidth || MIN_RAIL_PX * 4;
82
+ }, []);
65
83
 
66
84
  const onPointerDown = useCallback(
67
85
  (event: ReactPointerEvent<HTMLElement>) => {
@@ -69,10 +87,11 @@ export function useRailResize<E extends HTMLElement = HTMLElement>({
69
87
  const handle = event.currentTarget;
70
88
  const startX = event.clientX;
71
89
  const startWidth = measure();
90
+ const total = room();
72
91
  let latest = startWidth;
73
92
  handle.setPointerCapture?.(event.pointerId);
74
93
  const move = (moveEvent: PointerEvent) => {
75
- latest = clampRailWidth(startWidth + moveEvent.clientX - startX);
94
+ latest = Math.round(reachSize(startWidth + moveEvent.clientX - startX, MIN_RAIL_PX, total));
76
95
  setDragged(latest);
77
96
  };
78
97
  const end = () => {
@@ -87,7 +106,7 @@ export function useRailResize<E extends HTMLElement = HTMLElement>({
87
106
  handle.addEventListener('pointercancel', end);
88
107
  event.preventDefault();
89
108
  },
90
- [resizeKey, measure],
109
+ [resizeKey, measure, room],
91
110
  );
92
111
 
93
112
  const onKeyDown = useCallback(
@@ -97,11 +116,11 @@ export function useRailResize<E extends HTMLElement = HTMLElement>({
97
116
  const delta = event.key === 'ArrowRight' ? step : event.key === 'ArrowLeft' ? -step : 0;
98
117
  if (!delta) return;
99
118
  event.preventDefault();
100
- const next = clampRailWidth((dragged ?? measure()) + delta);
119
+ const next = Math.round(stepSize(dragged ?? measure(), delta, MIN_RAIL_PX, room()));
101
120
  setDragged(next);
102
121
  writeRailWidth(resizeKey, next);
103
122
  },
104
- [resizeKey, dragged, measure],
123
+ [resizeKey, dragged, measure, room],
105
124
  );
106
125
 
107
126
  const reset = useCallback(() => {
@@ -110,16 +129,27 @@ export function useRailResize<E extends HTMLElement = HTMLElement>({
110
129
  }, [resizeKey]);
111
130
 
112
131
  const width = active ? dragged : null;
132
+ const shut = width === 0;
113
133
  return {
114
134
  railRef,
115
135
  active,
116
136
  width,
117
- style: width === null ? undefined : { width },
137
+ shut,
138
+ style: width === null ? undefined : shut ? SHUT_STYLE : { width, maxWidth: '100%' },
118
139
  reset,
119
- handle: { label, onPointerDown, onKeyDown, measure },
140
+ handle: { label, onPointerDown, onKeyDown, measure, room },
120
141
  };
121
142
  }
122
143
 
144
+ /** A shut rail: no width, no padding (a padded box is never narrower than its padding), no border,
145
+ * and nothing drawn but the handle, which opts back in. `overflow: visible`, because a rail that
146
+ * scrolls itself (`overflow-y-auto`) would clip its handle out of a zero-wide box — still in the
147
+ * DOM, never under the pointer; its content is hidden by `visibility` instead. */
148
+ const SHUT_STYLE: CSSProperties = { width: 0, minWidth: 0, padding: 0, borderRightWidth: 0, overflow: 'visible', visibility: 'hidden' };
149
+ /** The shut rail's handle: visible again, and wholly on the page side of the edge, so all 12px of
150
+ * it can be grabbed even when the rail sits against the window's edge. */
151
+ const SHUT_HANDLE_STYLE: CSSProperties = { visibility: 'visible', right: -12 };
152
+
123
153
  /**
124
154
  * The handle itself — a 12px hotspot centered on the rail's right border. The RAIL must be
125
155
  * `position: relative` (the handle is absolutely positioned against it). Renders nothing while
@@ -130,7 +160,7 @@ export function useRailResize<E extends HTMLElement = HTMLElement>({
130
160
  */
131
161
  export function RailResizeHandle({ rail, className, ...rest }: { rail: RailResize; className?: string }) {
132
162
  if (!rail.active) return null;
133
- const { label, onPointerDown, onKeyDown, measure } = rail.handle;
163
+ const { label, onPointerDown, onKeyDown, measure, room } = rail.handle;
134
164
  return (
135
165
  // biome-ignore lint/a11y/useSemanticElements: an <hr> cannot take focus or a drag; a focusable separator is the ARIA splitter pattern.
136
166
  <div
@@ -138,9 +168,10 @@ export function RailResizeHandle({ rail, className, ...rest }: { rail: RailResiz
138
168
  role='separator'
139
169
  aria-orientation='vertical'
140
170
  aria-label={`Resize ${label}`}
141
- aria-valuemin={MIN_RAIL_PX}
142
- aria-valuemax={MAX_RAIL_PX}
171
+ aria-valuemin={0}
172
+ aria-valuemax={Math.round(room())}
143
173
  aria-valuenow={Math.round(rail.width ?? measure())}
174
+ {...(rail.shut ? { style: SHUT_HANDLE_STYLE } : {})}
144
175
  tabIndex={0}
145
176
  data-cb-rail-resize=''
146
177
  onPointerDown={onPointerDown}
@@ -1,5 +1,5 @@
1
1
  /**
2
- * How wide the person dragged a sidebar — the pure half, so the clamp is testable without a
2
+ * How wide the person dragged a sidebar — the pure half, so the storage is testable without a
3
3
  * pointer.
4
4
  *
5
5
  * Owner, 2026-09-24: *"the cb filetree sidebars should allow grabbing their right edge and
@@ -13,22 +13,27 @@
13
13
  */
14
14
  import { announcePreference } from '../media-gallery/preferenceBus.js';
15
15
 
16
- /** Narrower than this and a row is an icon and an ellipsis. */
16
+ /**
17
+ * Narrower than this and a row is an icon and an ellipsis — so it is the SNAP, not a floor:
18
+ * dragged below half of it the rail shuts (width 0), between half and all of it it holds here
19
+ * (`lib/paneReach.ts`). There is no maximum: the owner, 2026-10-27, *"let me drag them as far as
20
+ * I want including shutting a pane completely"* — a rail grows until the page beside it is shut.
21
+ */
17
22
  export const MIN_RAIL_PX = 160;
18
- /** Wider than this and the rail is eating the page it navigates. */
19
- export const MAX_RAIL_PX = 640;
20
23
 
24
+ /** A width as stored: whole pixels, and snapped at the bottom like a drag (0 is a shut rail), so a
25
+ * sliver written by an older build or by hand is never drawn. No top — `maxWidth` holds it to its row. */
21
26
  export const clampRailWidth = (px: number): number =>
22
- Math.round(Math.min(MAX_RAIL_PX, Math.max(MIN_RAIL_PX, px)));
27
+ px < MIN_RAIL_PX / 2 ? 0 : Math.round(Math.max(MIN_RAIL_PX, px));
23
28
 
24
- /** The remembered width, or null for "the rail's default". Wrapped: `localStorage` throws in
25
- * a sandboxed iframe and in Safari's private mode. */
29
+ /** The remembered width (0 = shut), or null for "the rail's default". Wrapped: `localStorage`
30
+ * throws in a sandboxed iframe and in Safari's private mode. */
26
31
  export function readRailWidth(key: string): number | null {
27
32
  try {
28
33
  const raw = globalThis.localStorage?.getItem(key);
29
34
  if (raw == null) return null;
30
35
  const stored = Number(raw);
31
- return Number.isFinite(stored) && stored > 0 ? clampRailWidth(stored) : null;
36
+ return raw.trim() !== '' && Number.isFinite(stored) && stored >= 0 ? clampRailWidth(stored) : null;
32
37
  } catch {
33
38
  return null;
34
39
  }
@@ -674,6 +674,7 @@ export {
674
674
  type SplitPaneItem,
675
675
  type SplitPaneProps,
676
676
  } from './components/SplitPane.js';
677
+ export { reachSize, stepSize } from './lib/paneReach.js';
677
678
  export { Sparkline, type SparklineProps } from './components/Sparkline.js';
678
679
  export { StatStrip, type StatStripItem, type StatStripProps } from './components/StatStrip.js';
679
680
  export {
@@ -0,0 +1,58 @@
1
+ import { describe, expect, test } from 'bun:test';
2
+ import { reachSize, stepSize } from './paneReach.js';
3
+
4
+ // The owner, 2026-10-27: every divider goes as far as the hand takes it, shutting a pane included.
5
+ describe('reachSize — where a pointer drag lands', () => {
6
+ test('has no maximum: the first pane can take the whole axis', () => {
7
+ expect(reachSize(1000, 160, 1000)).toBe(1000);
8
+ expect(reachSize(1400, 160, 1000)).toBe(1000);
9
+ expect(reachSize(0.99, 0.12, 1)).toBe(1);
10
+ });
11
+
12
+ test('shuts a pane dragged below half its minimum, either side of the seam', () => {
13
+ expect(reachSize(79, 160, 1000)).toBe(0);
14
+ expect(reachSize(-40, 160, 1000)).toBe(0);
15
+ expect(reachSize(921, 160, 1000)).toBe(1000);
16
+ });
17
+
18
+ test('holds at the minimum between half and all of it, so no pane is a sliver', () => {
19
+ expect(reachSize(100, 160, 1000)).toBe(160);
20
+ expect(reachSize(900, 160, 1000)).toBe(840);
21
+ });
22
+
23
+ test('passes every size between the two minimums through untouched', () => {
24
+ expect(reachSize(500, 160, 1000)).toBe(500);
25
+ expect(reachSize(160, 160, 1000)).toBe(160);
26
+ });
27
+
28
+ test('a minimum larger than half the axis shrinks to half, so both panes still fit', () => {
29
+ expect(reachSize(300, 800, 1000)).toBe(500);
30
+ });
31
+
32
+ test('a zero-width axis gives nothing rather than NaN or Infinity', () => {
33
+ expect(reachSize(10, 160, 0)).toBe(0);
34
+ expect(reachSize(Number.NaN, 160, 1000)).toBe(0);
35
+ });
36
+ });
37
+
38
+ describe('stepSize — where an arrow key lands', () => {
39
+ test('a step that would cross the minimum stops on it, and the next one shuts', () => {
40
+ expect(stepSize(170, -16, 160, 1000)).toBe(160);
41
+ expect(stepSize(160, -16, 160, 1000)).toBe(0);
42
+ });
43
+
44
+ test('the first step out of shut opens at the minimum, not a sliver', () => {
45
+ expect(stepSize(0, 16, 160, 1000)).toBe(160);
46
+ });
47
+
48
+ test('the far end shuts the other pane the same way, and opens it the same way', () => {
49
+ expect(stepSize(830, 16, 160, 1000)).toBe(840);
50
+ expect(stepSize(840, 16, 160, 1000)).toBe(1000);
51
+ expect(stepSize(1000, -16, 160, 1000)).toBe(840);
52
+ });
53
+
54
+ test('works in shares as well as pixels, through float noise', () => {
55
+ expect(stepSize(0.12000000001, -0.02, 0.12, 1)).toBe(0);
56
+ expect(stepSize(0.5, 0.02, 0.12, 1)).toBeCloseTo(0.52);
57
+ });
58
+ });
@@ -0,0 +1,65 @@
1
+ /**
2
+ * How far a divider may be dragged — the ONE rule every resizable split in cursedbelt obeys.
3
+ *
4
+ * The owner, 2026-10-27: *"For all dividers … that I can drag to size the panes, let me drag them
5
+ * as far as I want including shutting a pane completely … I don't want any panes to block me."*
6
+ * Station's Queue was the worked example: its task list stopped at 36% of the page, so the titles
7
+ * it was opened to read stayed cut off however hard the divider was pulled.
8
+ *
9
+ * So a pane has no MAXIMUM, ever — a pane grows until its neighbor is shut — and its minimum is
10
+ * not a wall but a snap, VS Code's sash and `react-resizable-panels`' collapsible panel alike:
11
+ *
12
+ * - dragged below HALF its minimum, a pane SHUTS (size 0);
13
+ * - between half and the whole minimum it HOLDS at the minimum, so a pane is never drawn as an
14
+ * unreadable sliver and a shut is a deliberate pull, not a twitch;
15
+ * - the same at the far end, for the pane on the other side of the seam.
16
+ *
17
+ * A shut pane opens again the way it closed: drag the seam back out (it is still there, at the
18
+ * edge), or step it with an arrow key. `PanelGrid`/`SplitPane` get the same rule from the library
19
+ * (every leaf is `collapsible`); `PaneSplit` and `useRailResize` draw their own seams and call
20
+ * these. An app that draws a seam of its own calls them too — guardrails' `no-hand-rolled-divider`
21
+ * refuses one that does not.
22
+ *
23
+ * Units are the caller's — pixels or a share of 1 — as long as all three agree.
24
+ */
25
+
26
+ /** Below this share of `total`, two sizes are the same size (a float's last bits are not a gap). */
27
+ const EPSILON = 1e-4;
28
+
29
+ /** The snap a pane gets, never more than half the axis — two minimums must fit side by side. */
30
+ function snapOf(min: number, total: number): number {
31
+ return Math.max(0, Math.min(min, total / 2));
32
+ }
33
+
34
+ /**
35
+ * Where a POINTER drag lands: the size the pointer asks for, with the snap applied at both ends.
36
+ * `size` is the first pane's (the one before the seam); the second pane is `total - size`.
37
+ */
38
+ export function reachSize(size: number, min: number, total: number): number {
39
+ if (!(total > 0) || !Number.isFinite(size)) return 0;
40
+ const snap = snapOf(min, total);
41
+ if (size < snap / 2) return 0;
42
+ if (size < snap) return snap;
43
+ if (size > total - snap / 2) return total;
44
+ if (size > total - snap) return total - snap;
45
+ return size;
46
+ }
47
+
48
+ /**
49
+ * Where a KEYBOARD step lands. A step that would cross a minimum stops ON it, and the next step
50
+ * the same way shuts the pane — so every size, including shut, is reachable from the keys, and
51
+ * a shut pane's first step out opens it at its minimum, not a sliver.
52
+ */
53
+ export function stepSize(size: number, delta: number, min: number, total: number): number {
54
+ if (!(total > 0) || !Number.isFinite(size) || delta === 0) return size;
55
+ const snap = snapOf(min, total);
56
+ const near = (a: number, b: number) => Math.abs(a - b) <= total * EPSILON;
57
+ if (delta < 0) {
58
+ if (near(size, total)) return total - snap;
59
+ if (size <= snap || near(size, snap)) return 0;
60
+ return Math.max(snap, size + delta);
61
+ }
62
+ if (near(size, 0)) return snap;
63
+ if (size >= total - snap || near(size, total - snap)) return total;
64
+ return Math.min(total - snap, size + delta);
65
+ }
@@ -85,13 +85,17 @@ export interface MasterDetailProps {
85
85
  /** Distinct per page — SplitPane persists pane widths under it. */
86
86
  storageKey?: string;
87
87
  /**
88
- * The LIST pane's share of the width — default 30% between 16rem and 44%. A page whose detail is
88
+ * The LIST pane's share of the width — default 30%, snapping at 16rem. A page whose detail is
89
89
  * the thing being read (a task's text, an app's charts) gives the list less: station's Queue at
90
90
  * 1440 drew a 30% list of one-line titles beside a detail pane of four facts, so the text the
91
91
  * owner opened the page for had nowhere to go (forge task station-evolution, 2026-10-20). Any
92
- * CSS length or percentage; the reader can still drag the divider inside `min`/`max`.
92
+ * CSS length or percentage.
93
+ *
94
+ * 🔴 There is no `max`: the reader drags the divider as far as they like, shutting either pane
95
+ * (the owner, 2026-10-27 — station's Queue capped its list at 36% and cut its titles off). `min`
96
+ * is the snap `SplitPane` gives it, not a floor.
93
97
  */
94
- masterSize?: { default?: string; min?: string; max?: string };
98
+ masterSize?: { default?: string; min?: string };
95
99
  /** Rendered above the filters (a "New…" button, a count, a refresh). */
96
100
  listHeader?: ReactNode;
97
101
  className?: string;
@@ -320,8 +324,9 @@ export function MasterDetail({
320
324
  {...(storageKey ? { storageKey } : {})}
321
325
  separatorVariant="line"
322
326
  panels={[
323
- { id: "master", content: list, defaultSize: masterSize?.default ?? "30%", minSize: masterSize?.min ?? "16rem", maxSize: masterSize?.max ?? "44%" },
324
- { id: "detail", content: pane },
327
+ { id: "master", content: list, defaultSize: masterSize?.default ?? "30%", minSize: masterSize?.min ?? "16rem" },
328
+ // The detail snaps too, so the list can take the whole width without a sliver beside it.
329
+ { id: "detail", content: pane, minSize: "16rem" },
325
330
  ]}
326
331
  />
327
332
  </div>
@@ -60,6 +60,7 @@ import { MediaResizeBar, MediaResizeCorner, useMediaResize } from "./MediaResize
60
60
  import { FOCUS_HEIGHT_KEY } from "./stageResize.js";
61
61
  import { PictureControls } from "./PictureControls.js";
62
62
  import { useHlsSource } from "./hlsSource.js";
63
+ import { VideoQualitySelect } from "./VideoQualitySelect.js";
63
64
  import { handOffPlayhead } from "./playheadHandoff.js";
64
65
  import { isPlayPauseSpace } from "./playerSpaceKey.js";
65
66
  import { PLAYBACK_RATES } from "./VideoPlayer.js";
@@ -247,7 +248,7 @@ export function FocusViewer({
247
248
  ...rest
248
249
  }: FocusViewerProps): React.ReactNode {
249
250
  const videoRef = useRef<HTMLVideoElement | null>(null);
250
- useHlsSource(videoRef, { hlsUrl, streamUrl: videoUrl });
251
+ const quality = useHlsSource(videoRef, { hlsUrl, streamUrl: videoUrl });
251
252
  const viewportRef = useRef<HTMLDivElement | null>(null);
252
253
  /*
253
254
  * ── Dragging the picture bigger ───────────────────────────────────────────────────
@@ -998,6 +999,13 @@ export function FocusViewer({
998
999
  value={String(rate)}
999
1000
  />
1000
1001
  </label>
1002
+ {/* Quality beside speed, the same kind of choice about the same picture: a still taken
1003
+ here is only as sharp as the rung on screen, so Max or the original's own rung is a
1004
+ choice this viewer, of all of them, has to offer (task 3868). */}
1005
+ <label className="inspector__speed" htmlFor="inspector-quality">
1006
+ <span className="sr-only">Video quality</span>
1007
+ <VideoQualitySelect control={quality} id="inspector-quality" />
1008
+ </label>
1001
1009
  </div>
1002
1010
 
1003
1011
  <div className="inspector__tools">
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The "Original" toggle every image viewer shows beside its picture (forge task 3873).
3
+ * `imageOriginal.ts` holds what the choice MEANS; this is only how it is pressed.
4
+ *
5
+ * A pressed Button, because the choice is on/off — "always the original", or the web copy with
6
+ * the original once a zoom needs it — and it reads the way the video menu's "2160p · Original"
7
+ * does. 🔴 Never hidden: where the original cannot be drawn (a HEIC, a RAW) it is refused with
8
+ * the reason, which reaches a phone on a tap (`unavailableReason`).
9
+ */
10
+ import type { ComponentPropsWithoutRef } from 'react';
11
+ import { Button } from '../components/Button.js';
12
+ import type { ImageOriginalControl } from './imageOriginal.js';
13
+
14
+ export interface ImageOriginalToggleProps extends Omit<ComponentPropsWithoutRef<'button'>, 'children' | 'onClick'> {
15
+ /** From `useImageOriginal`. Null — the item has no original — draws nothing. */
16
+ control: ImageOriginalControl | null;
17
+ className?: string;
18
+ /** `ghost` inside a toolbar of ghost buttons (photos' zoom bar); `secondary` on its own over a picture. */
19
+ variant?: 'secondary' | 'ghost';
20
+ }
21
+
22
+ /** The hint for a live toggle: what pressing it does from here. */
23
+ function hint(control: ImageOriginalControl): string {
24
+ if (control.pinned) return 'Showing the original at full resolution — press to show the web copy until you zoom past it';
25
+ return control.showing
26
+ ? 'Showing the original, because the zoom needed it — press to always show it'
27
+ : 'Showing the web copy; the original loads when you zoom past it — press to always show it';
28
+ }
29
+
30
+ export function ImageOriginalToggle({ control, className, variant = 'secondary', ...rest }: ImageOriginalToggleProps) {
31
+ if (!control) return null;
32
+ return (
33
+ <Button
34
+ {...rest}
35
+ aria-pressed={control.pinned}
36
+ className={className}
37
+ data-showing={control.showing ? 'original' : 'web'}
38
+ loading={control.loading}
39
+ onClick={control.toggle}
40
+ size='sm'
41
+ tooltip={hint(control)}
42
+ // A refused press is the reason's tap on a phone; a live one's words are already on it.
43
+ {...(control.unavailable ? { unavailableReason: control.unavailable, tooltipMobile: 'tap' as const } : {})}
44
+ variant={variant}
45
+ >
46
+ Original
47
+ </Button>
48
+ );
49
+ }
@@ -19,6 +19,7 @@ import {
19
19
  useLiveScrub,
20
20
  VideoPlayer,
21
21
  } from './VideoPlayer.js';
22
+ import { bindVidstackQuality } from './vidstackQuality.js';
22
23
 
23
24
  afterEach(cleanup);
24
25
 
@@ -654,7 +655,11 @@ describe('🔴 hls.js is served from this bundle, never from a CDN', () => {
654
655
 
655
656
  test('the player wires it — an unwired prop leaves the CDN default in place', () => {
656
657
  const source = readFileSync(join(import.meta.dir, 'VideoPlayer.tsx'), 'utf8');
657
- expect(/onProviderChange=\{preferBundledHls\}/.test(source)).toBe(true);
658
+ // Either the bare prop or a handler whose FIRST act is the call — the quality binding
659
+ // (task 3868) rides the same handler, after it.
660
+ expect(
661
+ /onProviderChange=\{(preferBundledHls\}|\(provider\) => \{\s*preferBundledHls\(provider\);)/.test(source),
662
+ ).toBe(true);
658
663
  });
659
664
 
660
665
  test('hls.js is imported LAZILY — a static import lands it in every consumer\'s entry chunk', () => {
@@ -681,3 +686,41 @@ describe('🔴 an answered source is not a slow one', () => {
681
686
  expect(queryByRole('status')).toBeNull();
682
687
  });
683
688
  });
689
+
690
+ /**
691
+ * 🔴 The stage's quality choice (forge task 3868): Vidstack's hls.js gets the viewer's cap
692
+ * BEFORE it is built, and every engine it builds is bound to the menu's store.
693
+ */
694
+ describe('bindVidstackQuality', () => {
695
+ test("Auto caps Vidstack's hls.js too, Max does not, and each instance is bound", async () => {
696
+ const { createVideoQualityStore, VIDEO_QUALITY_KEY } = await import('./videoQuality.js');
697
+ const store = createVideoQualityStore();
698
+ const bound: unknown[] = [];
699
+ const provider = (): { $$PROVIDER_TYPE: string; config: Record<string, unknown>; onInstance: (cb: unknown) => void } => ({
700
+ $$PROVIDER_TYPE: 'HLS',
701
+ config: { keep: 1 },
702
+ onInstance: (cb) => bound.push(cb),
703
+ });
704
+ localStorage.removeItem(VIDEO_QUALITY_KEY);
705
+ const auto = provider();
706
+ bindVidstackQuality(auto as never, store, true);
707
+ expect(auto.config).toEqual({ keep: 1, capLevelToPlayerSize: true });
708
+ localStorage.setItem(VIDEO_QUALITY_KEY, 'max');
709
+ const max = provider();
710
+ bindVidstackQuality(max as never, store, true);
711
+ expect(max.config.capLevelToPlayerSize).toBe(false);
712
+ expect(bound).toHaveLength(2);
713
+ localStorage.removeItem(VIDEO_QUALITY_KEY);
714
+ });
715
+
716
+ test("Safari's own HLS and the progressive copy say why nothing can be chosen", async () => {
717
+ const { createVideoQualityStore, NATIVE_HLS_REASON, NO_LADDER_REASON } = await import('./videoQuality.js');
718
+ const store = createVideoQualityStore();
719
+ bindVidstackQuality({ $$PROVIDER_TYPE: 'VIDEO' } as never, store, true);
720
+ expect(store.get()?.unavailable).toBe(NATIVE_HLS_REASON);
721
+ bindVidstackQuality({ $$PROVIDER_TYPE: 'VIDEO' } as never, store, false);
722
+ expect(store.get()?.unavailable).toBe(NO_LADDER_REASON);
723
+ bindVidstackQuality(null, store, true);
724
+ expect(store.get()).toBeNull();
725
+ });
726
+ });
@@ -17,7 +17,14 @@ import {
17
17
  type DefaultVideoLayoutSlots,
18
18
  defaultLayoutIcons,
19
19
  } from '@vidstack/react/player/layouts/default';
20
- import { type MouseEvent as ReactMouseEvent, type RefObject, useEffect, useMemo, useRef, useState } from 'react';
20
+ import {
21
+ type MouseEvent as ReactMouseEvent,
22
+ type RefObject,
23
+ useEffect,
24
+ useMemo,
25
+ useRef,
26
+ useState,
27
+ } from 'react';
21
28
  import type { PlayableVideo } from 'cursedbelt-core/media';
22
29
  import {
23
30
  PLAYER_VOLUME_KEY,
@@ -35,6 +42,8 @@ import { BarButton, mergeSlots, sectionSlots } from './controlBar.js';
35
42
  import { takePlayhead } from './playheadHandoff.js';
36
43
  import { isSurfaceControl } from './surfaceGesture.js';
37
44
  import { chapterSpans, type ChapteredVideo, type VideoChapter } from './videoChapters.js';
45
+ import { bindVidstackQuality, qualitySlots } from './vidstackQuality.js';
46
+ import { createVideoQualityStore } from './videoQuality.js';
38
47
 
39
48
  /**
40
49
  * The reusable video player primitive. Consumes a {@link PlayableVideo} (URLs already
@@ -683,14 +692,16 @@ export function VideoPlayer({
683
692
  // Memoized because `slots` holds React elements: a fresh object every render remounts
684
693
  // Vidstack's whole layout, which drops the control bar mid-hover and restarts its
685
694
  // auto-hide timer on every state change the player makes (i.e. constantly, while playing).
695
+ const [qualityStore] = useState(createVideoQualityStore);
686
696
  const slots = useMemo(
687
697
  () =>
688
698
  mergeSlots(
689
699
  stepSlots(onStep, canStep),
690
700
  sectionSlots(video.chapters),
701
+ qualitySlots(qualityStore),
691
702
  fillWindowSlots(fillWindow, onFillWindowChange),
692
703
  ),
693
- [onStep, canStep, video.chapters, fillWindow, onFillWindowChange],
704
+ [onStep, canStep, video.chapters, qualityStore, fillWindow, onFillWindowChange],
694
705
  );
695
706
 
696
707
  return (
@@ -719,7 +730,10 @@ export function VideoPlayer({
719
730
  // 🔴 The hls.js engine is served from this origin, not from jsdelivr. See
720
731
  // `preferBundledHls` — without it an adaptive ladder depends on a third-party CDN
721
732
  // and fails as a permanent spinner when that CDN is unreachable.
722
- onProviderChange={preferBundledHls}
733
+ onProviderChange={(provider) => {
734
+ preferBundledHls(provider);
735
+ bindVidstackQuality(provider, qualityStore, typeof src !== 'string');
736
+ }}
723
737
  /* See {@link hlsErrorIsAnswer}. Typed `unknown` on purpose: `hls.js` is an OPTIONAL
724
738
  peer, so its `ErrorData` must not become a static type dependency of this file. */
725
739
  onHlsError={(detail: unknown) => {