@hyperframes/studio 0.9.15 → 0.9.16

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 (33) hide show
  1. package/dist/assets/{hyperframes-player-bkb0-LEY.js → hyperframes-player-Bb-Fbf5k.js} +1 -1
  2. package/dist/assets/{index-DfsIam9M.js → index-BZuKog_A.js} +137 -137
  3. package/dist/assets/{index-RUPGNyct.css → index-CNZk2EFC.css} +1 -1
  4. package/dist/assets/{index-D5zessN9.js → index-Cap2SGKw.js} +1 -1
  5. package/dist/index.d.ts +17 -7
  6. package/dist/index.html +2 -2
  7. package/dist/index.js +112 -55
  8. package/dist/styles.css +1 -1
  9. package/package.json +8 -8
  10. package/src/components/editor/DomEditOverlay.tsx +3 -1
  11. package/src/components/editor/MarqueeOverlay.tsx +12 -4
  12. package/src/components/editor/marqueeCommit.test.tsx +137 -4
  13. package/src/components/editor/marqueeCommit.ts +30 -16
  14. package/src/components/editor/previewReadOnly.overlay.test.tsx +1 -1
  15. package/src/editorGesturesExports.test.tsx +10 -4
  16. package/src/hooks/useDomSelection.test.ts +90 -9
  17. package/src/hooks/useDomSelection.ts +21 -9
  18. package/src/hooks/useDomSelectionTypes.ts +5 -1
  19. package/src/hooks/useStudioUrlState.ts +3 -2
  20. package/src/hooks/useTimelineSelectionPreviewSync.test.tsx +6 -2
  21. package/src/hooks/useTimelineSelectionPreviewSync.ts +3 -2
  22. package/src/index.ts +6 -1
  23. package/src/player/components/TimelineCanvas.tsx +11 -3
  24. package/src/player/components/TimelineProvider.tsx +2 -2
  25. package/src/player/components/timelineMarquee.test.ts +68 -0
  26. package/src/player/components/timelineMarquee.ts +17 -5
  27. package/src/player/components/timelineMarqueeCommit.ts +74 -0
  28. package/src/player/components/useTimelineRangeSelection.test.tsx +98 -4
  29. package/src/player/components/useTimelineRangeSelection.ts +53 -103
  30. package/src/styles/theme.css +1 -0
  31. package/src/utils/marqueeGeometry.test.ts +18 -1
  32. package/src/utils/marqueeGeometry.ts +20 -0
  33. package/src/utils/studioUrlState.test.ts +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hyperframes/studio",
3
- "version": "0.9.15",
3
+ "version": "0.9.16",
4
4
  "description": "",
5
5
  "repository": {
6
6
  "type": "git",
@@ -60,12 +60,12 @@
60
60
  "dockview-react": "8.3.1",
61
61
  "gsap": "^3.13.0",
62
62
  "mediabunny": "^1.45.3",
63
- "@hyperframes/player": "0.9.15",
64
- "@hyperframes/sdk": "0.9.15",
65
- "@hyperframes/parsers": "0.9.15",
66
- "@hyperframes/shader-transitions": "0.9.15",
67
- "@hyperframes/studio-server": "0.9.15",
68
- "@hyperframes/core": "0.9.15"
63
+ "@hyperframes/core": "0.9.16",
64
+ "@hyperframes/shader-transitions": "0.9.16",
65
+ "@hyperframes/studio-server": "0.9.16",
66
+ "@hyperframes/sdk": "0.9.16",
67
+ "@hyperframes/player": "0.9.16",
68
+ "@hyperframes/parsers": "0.9.16"
69
69
  },
70
70
  "devDependencies": {
71
71
  "@tailwindcss/vite": "^4.3.3",
@@ -82,7 +82,7 @@
82
82
  "vite": "^6.4.2",
83
83
  "vitest": "^4.1.11",
84
84
  "zustand": "^5.0.0",
85
- "@hyperframes/producer": "0.9.15"
85
+ "@hyperframes/producer": "0.9.16"
86
86
  },
87
87
  "peerDependencies": {
88
88
  "react": "19",
@@ -5,6 +5,7 @@ import { type DomEditSelection } from "./domEditing";
5
5
  import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
6
6
  import { useMarqueeGestures } from "./marqueeCommit";
7
7
  import { MarqueeOverlay } from "./MarqueeOverlay";
8
+ import type { MarqueeSelectionMode } from "../../utils/marqueeGeometry";
8
9
  import { resolveDomEditGroupOverlayRect } from "./domEditOverlayGeometry";
9
10
  import { useZOrderCrossedFlash, ZOrderCrossedFlash } from "./useZOrderCrossedFlash";
10
11
  import { useCanvasContextMenuState } from "./useCanvasContextMenuState";
@@ -103,7 +104,7 @@ export interface DomEditOverlayProps {
103
104
  onToggleRecording?: () => void;
104
105
  onMarqueeSelect?: (
105
106
  selections: DomEditSelection[],
106
- additive: boolean,
107
+ mode: MarqueeSelectionMode,
107
108
  ) => DomSelectionResult | void;
108
109
  /**
109
110
  * Delete the selected canvas element.
@@ -341,6 +342,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
341
342
  activeCompositionPathRef,
342
343
  onMarqueeSelectRef,
343
344
  selectionRef,
345
+ groupSelectionsRef,
344
346
  gestures,
345
347
  });
346
348
 
@@ -1,10 +1,10 @@
1
- import type { Rect } from "../../utils/marqueeGeometry";
1
+ import type { MarqueeBand, Rect } from "../../utils/marqueeGeometry";
2
2
 
3
3
  export interface MarqueeOverlayProps {
4
4
  /** Elements the marquee currently intersects — outlined live before mouse-up. */
5
5
  candidateRects: Rect[];
6
6
  /** The marquee drag rectangle itself, or null when not marquee-selecting. */
7
- marqueeRect: Rect | null;
7
+ marqueeRect: MarqueeBand | null;
8
8
  }
9
9
 
10
10
  /**
@@ -13,20 +13,28 @@ export interface MarqueeOverlayProps {
13
13
  * DomEditOverlay to keep that file under the 600-line cap.
14
14
  */
15
15
  export function MarqueeOverlay({ candidateRects, marqueeRect }: MarqueeOverlayProps) {
16
+ const subtracting = marqueeRect?.mode === "subtract";
17
+ const candidateClass = subtracting
18
+ ? "border-danger bg-danger/5"
19
+ : "border-studio-accent bg-studio-accent/5";
20
+ const bandClass = subtracting
21
+ ? "border-danger bg-danger/10"
22
+ : "border-studio-accent bg-studio-accent/10";
16
23
  return (
17
24
  <>
18
25
  {candidateRects.map((r, i) => (
19
26
  <div
20
27
  key={i}
21
28
  aria-hidden="true"
22
- className="pointer-events-none absolute rounded-xs border border-studio-accent bg-studio-accent/5"
29
+ className={`pointer-events-none absolute rounded-xs border ${candidateClass}`}
23
30
  style={{ left: r.left, top: r.top, width: r.width, height: r.height }}
24
31
  />
25
32
  ))}
26
33
  {marqueeRect && (
27
34
  <div
28
35
  aria-hidden="true"
29
- className="pointer-events-none absolute border border-dashed border-studio-accent bg-studio-accent/10"
36
+ data-marquee-mode={marqueeRect.mode}
37
+ className={`pointer-events-none absolute border border-dashed ${bandClass}`}
30
38
  style={{
31
39
  left: marqueeRect.left,
32
40
  top: marqueeRect.top,
@@ -2,9 +2,15 @@
2
2
  import { act, useRef, type RefObject } from "react";
3
3
  import type { Root } from "react-dom/client";
4
4
  import { afterEach, beforeEach, expect, it, vi } from "vitest";
5
- import { installReactActEnvironment, mountReactHarness } from "../../hooks/domSelectionTestHarness";
5
+ import {
6
+ installReactActEnvironment,
7
+ makeSelection,
8
+ mountReactHarness,
9
+ } from "../../hooks/domSelectionTestHarness";
10
+ import type { DomEditSelection } from "./domEditing";
6
11
  import { trackStudioEvent } from "../../utils/studioTelemetry";
7
12
  import type { DomSelectionResult } from "../../hooks/useDomSelectionTypes";
13
+ import type { MarqueeSelectionMode } from "../../utils/marqueeGeometry";
8
14
  import { useMarqueeGestures } from "./marqueeCommit";
9
15
 
10
16
  vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
@@ -39,7 +45,13 @@ function Overlay() {
39
45
  onPointerMove={marquee.onPointerMove}
40
46
  onPointerUp={marquee.onPointerUp}
41
47
  >
42
- {marquee.marqueeRect && <div data-band data-width={marquee.marqueeRect.width} />}
48
+ {marquee.marqueeRect && (
49
+ <div
50
+ data-band
51
+ data-width={marquee.marqueeRect.width}
52
+ data-mode={marquee.marqueeRect.mode}
53
+ />
54
+ )}
43
55
  </div>
44
56
  );
45
57
  }
@@ -55,6 +67,7 @@ function MarqueeSurface({
55
67
  <div
56
68
  ref={overlayRef}
57
69
  data-band-overlay
70
+ data-candidates={marquee.candidateRects.length}
58
71
  onPointerDown={marquee.begin}
59
72
  onPointerMove={marquee.onPointerMove}
60
73
  onPointerUp={marquee.onPointerUp}
@@ -66,10 +79,12 @@ function TestMarquee({
66
79
  iframeRef,
67
80
  onSelect,
68
81
  resolveHits,
82
+ groupSelectionsRef,
69
83
  }: {
70
84
  iframeRef: RefObject<HTMLIFrameElement | null>;
71
- onSelect: (selections: HTMLElement[], additive: boolean) => DomSelectionResult | void;
85
+ onSelect: (selections: HTMLElement[], mode: MarqueeSelectionMode) => DomSelectionResult | void;
72
86
  resolveHits: (elements: HTMLElement[]) => HTMLElement[] | Promise<HTMLElement[]>;
87
+ groupSelectionsRef?: RefObject<DomEditSelection[]>;
73
88
  }) {
74
89
  const overlayRef = useRef<HTMLDivElement>(null);
75
90
  const marquee = useMarqueeGestures({
@@ -78,16 +93,27 @@ function TestMarquee({
78
93
  activeCompositionPathRef: useRef<string | null>("index.html"),
79
94
  onMarqueeSelectRef: { current: onSelect },
80
95
  resolveHits,
96
+ groupSelectionsRef,
81
97
  });
82
98
  return <MarqueeSurface overlayRef={overlayRef} marquee={marquee} />;
83
99
  }
84
100
 
101
+ function previewWithTwoElements() {
102
+ const iframe = document.createElement("iframe");
103
+ const doc = document.implementation.createHTMLDocument("preview");
104
+ doc.body.innerHTML =
105
+ '<div data-composition-id="main"><h1 id="title">Title</h1><p id="subtitle">Subtitle</p></div>';
106
+ Object.defineProperty(iframe, "contentDocument", { value: doc });
107
+ return { iframe, doc };
108
+ }
109
+
85
110
  const pointer = (
86
111
  type: string,
87
112
  clientX: number,
88
113
  clientY: number,
89
114
  selector = "[data-overlay]",
90
115
  shiftKey = false,
116
+ altKey = false,
91
117
  ) =>
92
118
  act(() => {
93
119
  document.querySelector(selector)!.dispatchEvent(
@@ -99,6 +125,7 @@ const pointer = (
99
125
  clientX,
100
126
  clientY,
101
127
  shiftKey,
128
+ altKey,
102
129
  }),
103
130
  );
104
131
  });
@@ -214,7 +241,10 @@ it.each([
214
241
  doc.body.innerHTML =
215
242
  '<div data-composition-id="main"><h1 id="title">Title</h1><p id="subtitle">Subtitle</p></div>';
216
243
  Object.defineProperty(iframe, "contentDocument", { value: doc });
217
- const apply = vi.fn((_selections: HTMLElement[], _additive: boolean) => ({ changed, count }));
244
+ const apply = vi.fn((_selections: HTMLElement[], _mode: MarqueeSelectionMode) => ({
245
+ changed,
246
+ count,
247
+ }));
218
248
  const band = mountReactHarness(
219
249
  <TestMarquee
220
250
  iframeRef={{ current: iframe }}
@@ -244,3 +274,106 @@ it.each([
244
274
  }
245
275
  },
246
276
  );
277
+
278
+ it.each([
279
+ ["no modifier", false, false, "replace"],
280
+ ["Shift", true, false, "add"],
281
+ ["Alt", false, true, "subtract"],
282
+ ["Shift and Alt", true, true, "subtract"],
283
+ ] as const)("a band released with %s commits in %s mode", async (_, shiftKey, altKey, mode) => {
284
+ const iframe = document.createElement("iframe");
285
+ const doc = document.implementation.createHTMLDocument("preview");
286
+ doc.body.innerHTML = '<div data-composition-id="main"><h1 id="title">Title</h1></div>';
287
+ Object.defineProperty(iframe, "contentDocument", { value: doc });
288
+ const apply = vi.fn((_selections: HTMLElement[], _mode: MarqueeSelectionMode) => undefined);
289
+ const band = mountReactHarness(
290
+ <TestMarquee
291
+ iframeRef={{ current: iframe }}
292
+ onSelect={apply}
293
+ resolveHits={(elements) => elements}
294
+ />,
295
+ );
296
+ const fire = (type: string, x: number, y: number) =>
297
+ pointer(type, x, y, "[data-band-overlay]", shiftKey, altKey);
298
+ try {
299
+ fire("pointerdown", 0, 0);
300
+ fire("pointermove", 120, 90);
301
+ await act(async () => {
302
+ fire("pointerup", 120, 90);
303
+ });
304
+ expect(apply).toHaveBeenCalledTimes(1);
305
+ expect(apply.mock.calls[0]![1]).toBe(mode);
306
+ } finally {
307
+ act(() => band.unmount());
308
+ }
309
+ });
310
+
311
+ it("the modifiers held at release decide: a band dragged with Alt but released without commits a replace", async () => {
312
+ const { iframe } = previewWithTwoElements();
313
+ const apply = vi.fn((_selections: HTMLElement[], _mode: MarqueeSelectionMode) => undefined);
314
+ const band = mountReactHarness(
315
+ <TestMarquee iframeRef={{ current: iframe }} onSelect={apply} resolveHits={(e) => e} />,
316
+ );
317
+ try {
318
+ pointer("pointerdown", 0, 0, "[data-band-overlay]", false, true);
319
+ pointer("pointermove", 120, 90, "[data-band-overlay]", false, true);
320
+ await act(async () => {
321
+ pointer("pointerup", 120, 90, "[data-band-overlay]", false, false);
322
+ });
323
+ expect(apply.mock.calls[0]![1]).toBe("replace");
324
+ } finally {
325
+ act(() => band.unmount());
326
+ }
327
+ });
328
+
329
+ it("while subtracting, only elements already in the selection are outlined as candidates", () => {
330
+ const { iframe, doc } = previewWithTwoElements();
331
+ const title = doc.getElementById("title")!;
332
+ const groupSelectionsRef = { current: [makeSelection("Title", title)] };
333
+ const band = mountReactHarness(
334
+ <TestMarquee
335
+ iframeRef={{ current: iframe }}
336
+ onSelect={() => undefined}
337
+ resolveHits={(e) => e}
338
+ groupSelectionsRef={groupSelectionsRef}
339
+ />,
340
+ );
341
+ const candidates = () =>
342
+ document.querySelector<HTMLElement>("[data-band-overlay]")?.dataset.candidates;
343
+ try {
344
+ pointer("pointerdown", 0, 0, "[data-band-overlay]");
345
+ pointer("pointermove", 120, 90, "[data-band-overlay]");
346
+ expect(candidates()).toBe("2");
347
+ pointer("pointermove", 130, 90, "[data-band-overlay]", false, true);
348
+ expect(candidates()).toBe("1");
349
+ pointer("pointermove", 140, 90, "[data-band-overlay]", true, false);
350
+ expect(candidates()).toBe("2");
351
+ } finally {
352
+ act(() => band.unmount());
353
+ }
354
+ });
355
+
356
+ it("the band reports the mode its modifiers select while it is drawn", () => {
357
+ const mode = () => document.querySelector<HTMLElement>("[data-band]")?.dataset.mode;
358
+ pointer("pointerdown", 10, 10);
359
+ pointer("pointermove", 120, 90);
360
+ expect(mode()).toBe("replace");
361
+ pointer("pointermove", 130, 90, "[data-overlay]", true);
362
+ expect(mode()).toBe("add");
363
+ pointer("pointermove", 140, 90, "[data-overlay]", false, true);
364
+ expect(mode()).toBe("subtract");
365
+ });
366
+
367
+ it("a plain click with no band in flight replaces the selection with nothing", () => {
368
+ const apply = vi.fn((_selections: HTMLElement[], _mode: MarqueeSelectionMode) => undefined);
369
+ const band = mountReactHarness(
370
+ <TestMarquee iframeRef={{ current: null }} onSelect={apply} resolveHits={(e) => e} />,
371
+ );
372
+ try {
373
+ pointer("pointerdown", 0, 0, "[data-band-overlay]", false, true);
374
+ pointer("pointerup", 0, 0, "[data-band-overlay]", false, true);
375
+ expect(apply).toHaveBeenCalledWith([], "replace");
376
+ } finally {
377
+ act(() => band.unmount());
378
+ }
379
+ });
@@ -7,7 +7,13 @@ import type { DomEditSelection } from "./domEditing";
7
7
  import { collectDomEditLayerItems, resolveDomEditSelection } from "./domEditingLayers";
8
8
  import { isElementComputedVisible } from "./domEditingElement";
9
9
  import { coversComposition } from "../../utils/studioPreviewHelpers";
10
- import { rectsOverlap, type Rect } from "../../utils/marqueeGeometry";
10
+ import {
11
+ rectsOverlap,
12
+ resolveMarqueeMode,
13
+ type MarqueeBand,
14
+ type MarqueeSelectionMode,
15
+ type Rect,
16
+ } from "../../utils/marqueeGeometry";
11
17
  import { toVisibleOverlayRect } from "./domEditOverlayGeometry";
12
18
  import { movesGesture } from "./domEditOverlayGestures";
13
19
 
@@ -117,11 +123,12 @@ export interface MarqueeGesturesDeps<T = DomEditSelection> {
117
123
  overlayRef: React.RefObject<HTMLDivElement | null>;
118
124
  activeCompositionPathRef: React.RefObject<string | null>;
119
125
  onMarqueeSelectRef: React.RefObject<
120
- ((selections: T[], additive: boolean) => DomSelectionResult | void) | undefined
126
+ ((selections: T[], mode: MarqueeSelectionMode) => DomSelectionResult | void) | undefined
121
127
  >;
122
128
  /** Turns the elements a drag touched into picks; without it, Studio's edit selections. */
123
129
  resolveHits?: (elements: HTMLElement[]) => T[] | Promise<T[]>;
124
130
  selectionRef?: React.RefObject<DomEditSelection | null>;
131
+ groupSelectionsRef?: React.RefObject<DomEditSelection[]>;
125
132
  /** Studio's pointer handling, for the events that are not part of a marquee. */
126
133
  gestures?: {
127
134
  onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
@@ -131,7 +138,7 @@ export interface MarqueeGesturesDeps<T = DomEditSelection> {
131
138
  }
132
139
 
133
140
  export interface MarqueeGestures {
134
- marqueeRect: Rect | null;
141
+ marqueeRect: MarqueeBand | null;
135
142
  candidateRects: Rect[];
136
143
  /** Starts a marquee at this press; the host has decided it landed on empty canvas. */
137
144
  begin: (event: React.PointerEvent<HTMLElement>) => void;
@@ -161,7 +168,7 @@ export function useMarqueeGestures<T>(
161
168
  // fallow-ignore-next-line complexity
162
169
  export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGestures {
163
170
  const marqueeRef = useRef<MarqueeState | null>(null);
164
- const [marqueeRect, setMarqueeRect] = useState<Rect | null>(null);
171
+ const [marqueeRect, setMarqueeRect] = useState<MarqueeBand | null>(null);
165
172
  // Live "candidate" highlight: the elements the marquee currently touches,
166
173
  // shown before mouse-up so you can see what you're about to select. The
167
174
  // iframe DOM doesn't mutate during a drag, so a sync intersection per move
@@ -171,10 +178,7 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
171
178
  const candidatesRef = useRef<MarqueeHit[] | null>(null);
172
179
 
173
180
  const commitMarquee = useCallback(
174
- async (
175
- rect: { left: number; top: number; width: number; height: number },
176
- additive: boolean,
177
- ) => {
181
+ async (rect: Rect, mode: MarqueeSelectionMode) => {
178
182
  const iframe = deps.iframeRef.current;
179
183
  const overlay = deps.overlayRef.current;
180
184
  if (!iframe || !overlay || !deps.onMarqueeSelectRef.current) return;
@@ -187,7 +191,7 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
187
191
  : ((await resolveDomEditSelections(elements, acp)) as T[]);
188
192
  const applySelection = deps.onMarqueeSelectRef.current;
189
193
  if (!applySelection) return;
190
- const result = applySelection(picks, additive);
194
+ const result = applySelection(picks, mode);
191
195
  trackMarqueeSelection(result);
192
196
  },
193
197
  [
@@ -244,16 +248,25 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
244
248
  window.removeEventListener("keydown", cancelBandBeforeHostEscape, { capture: true });
245
249
  }, [cancel]);
246
250
 
251
+ const isSelectedElement = useCallback(
252
+ (element: HTMLElement) =>
253
+ deps.selectionRef?.current?.element === element ||
254
+ (deps.groupSelectionsRef?.current ?? []).some((s) => s.element === element),
255
+ [deps.selectionRef, deps.groupSelectionsRef],
256
+ );
257
+
247
258
  const showCandidates = useCallback(
248
- (rect: Rect) => {
259
+ (rect: Rect, mode: MarqueeSelectionMode) => {
249
260
  const iframe = deps.iframeRef.current;
250
261
  const overlay = deps.overlayRef.current;
251
262
  if (!iframe || !overlay) return;
252
263
  const acp = deps.activeCompositionPathRef.current ?? "index.html";
253
264
  candidatesRef.current ??= collectMarqueeCandidates(iframe, overlay, acp);
254
- setCandidateRects(hitsWithin(rect, candidatesRef.current).map((h) => h.rect));
265
+ let hits = hitsWithin(rect, candidatesRef.current);
266
+ if (mode === "subtract") hits = hits.filter((h) => isSelectedElement(h.element));
267
+ setCandidateRects(hits.map((h) => h.rect));
255
268
  },
256
- [deps.overlayRef, deps.iframeRef, deps.activeCompositionPathRef],
269
+ [deps.overlayRef, deps.iframeRef, deps.activeCompositionPathRef, isSelectedElement],
257
270
  );
258
271
 
259
272
  const onPointerMove = useCallback(
@@ -278,8 +291,9 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
278
291
  width: Math.abs(m.currentX - m.startX),
279
292
  height: Math.abs(m.currentY - m.startY),
280
293
  };
281
- setMarqueeRect(rect);
282
- showCandidates(rect);
294
+ const mode = resolveMarqueeMode(event);
295
+ setMarqueeRect({ ...rect, mode });
296
+ showCandidates(rect, mode);
283
297
  return;
284
298
  }
285
299
  deps.gestures?.onPointerMove(event);
@@ -300,10 +314,10 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
300
314
  width: Math.abs(m.currentX - m.startX),
301
315
  height: Math.abs(m.currentY - m.startY),
302
316
  },
303
- event.shiftKey,
317
+ resolveMarqueeMode(event),
304
318
  );
305
319
  } else {
306
- deps.onMarqueeSelectRef.current?.([], false);
320
+ deps.onMarqueeSelectRef.current?.([], "replace");
307
321
  }
308
322
  reset();
309
323
  return;
@@ -329,7 +329,7 @@ describe("DomEditOverlay with canvasInput host", () => {
329
329
  const off = fixture({ selection: null });
330
330
  fire(off.overlay, "pointerdown");
331
331
  fire(off.overlay, "pointerup");
332
- expect(off.spies.onMarqueeSelect).toHaveBeenCalledWith([], false);
332
+ expect(off.spies.onMarqueeSelect).toHaveBeenCalledWith([], "replace");
333
333
  act(() => root.unmount());
334
334
  const { spies, overlay } = fixture({ ...HOST, selection: null });
335
335
  fire(overlay, "pointerdown");
@@ -98,10 +98,16 @@ describe("marquee package export, driven by a host", () => {
98
98
  act(() => marquee().begin(at(1, 1)));
99
99
  expect(overlay.setPointerCapture).toHaveBeenCalledWith(7);
100
100
  act(() => marquee().onPointerMove(at(20, 20)));
101
- expect(marquee().marqueeRect).toEqual({ left: 1, top: 1, width: 19, height: 19 });
101
+ expect(marquee().marqueeRect).toEqual({
102
+ left: 1,
103
+ top: 1,
104
+ width: 19,
105
+ height: 19,
106
+ mode: "replace",
107
+ });
102
108
  expect(marquee().candidateRects).toEqual([rects.get("a")]);
103
109
  await act(async () => marquee().onPointerUp(at(20, 20, true)));
104
- expect(onSelect).toHaveBeenCalledWith(["a"], true);
110
+ expect(onSelect).toHaveBeenCalledWith(["a"], "add");
105
111
  expect(overlay.releasePointerCapture).toHaveBeenCalledWith(7);
106
112
  expect(marquee().marqueeRect).toBeNull();
107
113
  });
@@ -120,7 +126,7 @@ describe("marquee package export, driven by a host", () => {
120
126
  const { onSelect, at, marquee } = mountMarquee<string>({ resolveHits });
121
127
  act(() => marquee().begin(at(1, 1)));
122
128
  await act(async () => marquee().onPointerUp(at(2, 2)));
123
- expect(onSelect).toHaveBeenCalledWith([], false);
129
+ expect(onSelect).toHaveBeenCalledWith([], "replace");
124
130
  expect(resolveHits).not.toHaveBeenCalled();
125
131
  });
126
132
 
@@ -167,7 +173,7 @@ describe("marquee package export, driven by a host", () => {
167
173
  document.getElementById("a"),
168
174
  expect.objectContaining({ skipSourceProbe: true }),
169
175
  );
170
- expect(onSelect).toHaveBeenCalledWith([{ id: "a" }], false);
176
+ expect(onSelect).toHaveBeenCalledWith([{ id: "a" }], "replace");
171
177
  });
172
178
 
173
179
  it("passes pointer events that are not a marquee to Studio's gestures, and needs none", () => {
@@ -137,7 +137,7 @@ describe("useDomSelection marquee", () => {
137
137
  it("announces every marquee'd element to the timeline, anchored on the primary", () => {
138
138
  const { harness, card, chip } = renderCardAndChip();
139
139
 
140
- act(() => harness.current().applyMarqueeSelection([card, chip], false));
140
+ act(() => harness.current().applyMarqueeSelection([card, chip], "replace"));
141
141
 
142
142
  expect(harness.current().domEditGroupSelections).toHaveLength(2);
143
143
  expect(harness.timeline.setTimelineSelectionSet).toHaveBeenCalledWith(
@@ -165,7 +165,7 @@ describe("useDomSelection marquee", () => {
165
165
  .current()
166
166
  .applyMarqueeSelection(
167
167
  [makeSelection("Canvas only", canvasOnly), makeSelection("Card", card)],
168
- false,
168
+ "replace",
169
169
  ),
170
170
  );
171
171
 
@@ -207,11 +207,11 @@ describe("useDomSelection additive", () => {
207
207
  ] as const)("publishes the smaller set when %s", (_, shrink) => {
208
208
  const { harness, card, chip } = renderCardAndChip();
209
209
 
210
- act(() => harness.current().applyMarqueeSelection([card, chip], false));
210
+ act(() => harness.current().applyMarqueeSelection([card, chip], "replace"));
211
211
  act(() =>
212
212
  shrink === "toggle"
213
213
  ? harness.current().applyDomSelection(chip, { additive: true })
214
- : harness.current().applyMarqueeSelection([card], false),
214
+ : harness.current().applyMarqueeSelection([card], "replace"),
215
215
  );
216
216
 
217
217
  expect(harness.current().domEditGroupSelections).toHaveLength(1);
@@ -225,7 +225,7 @@ describe("useDomSelection additive", () => {
225
225
  it("keeps the live set when a single member is re-announced", () => {
226
226
  const { harness, card, chip } = renderCardAndChip();
227
227
 
228
- act(() => harness.current().applyMarqueeSelection([card, chip], false));
228
+ act(() => harness.current().applyMarqueeSelection([card, chip], "replace"));
229
229
  act(() => harness.current().applyDomSelection(chip));
230
230
 
231
231
  expect(harness.timeline.setTimelineSelectionSet).toHaveBeenLastCalledWith(
@@ -449,22 +449,103 @@ it("reports unchanged marquee membership and one new additive member", () => {
449
449
  act(() => harness.current().applyDomSelection(card));
450
450
  let receipt!: ReturnType<ReturnType<typeof useDomSelection>["applyMarqueeSelection"]>;
451
451
  act(() => {
452
- receipt = harness.current().applyMarqueeSelection([chip], true);
452
+ receipt = harness.current().applyMarqueeSelection([chip], "add");
453
453
  });
454
454
  expect(receipt).toEqual({ changed: true, count: 2 });
455
455
  act(() => {
456
- receipt = harness.current().applyMarqueeSelection([card, chip], true);
456
+ receipt = harness.current().applyMarqueeSelection([card, chip], "add");
457
457
  });
458
458
  expect(receipt).toEqual({ changed: false, count: 2 });
459
459
  act(() => {
460
- receipt = harness.current().applyMarqueeSelection([], true);
460
+ receipt = harness.current().applyMarqueeSelection([], "add");
461
461
  });
462
462
  expect(receipt).toEqual({ changed: false, count: 2 });
463
463
  act(() => {
464
- receipt = harness.current().applyMarqueeSelection([], false);
464
+ receipt = harness.current().applyMarqueeSelection([], "replace");
465
465
  });
466
466
  expect(receipt).toEqual({ changed: true, count: 0 });
467
467
  } finally {
468
468
  harness.cleanup();
469
469
  }
470
470
  });
471
+
472
+ describe("useDomSelection subtract", () => {
473
+ it("drops the covered members and announces the smaller set", () => {
474
+ const { harness, card, chip } = renderCardAndChip();
475
+ try {
476
+ act(() => harness.current().applyMarqueeSelection([card, chip], "replace"));
477
+ let receipt!: ReturnType<ReturnType<typeof useDomSelection>["applyMarqueeSelection"]>;
478
+ act(() => {
479
+ receipt = harness.current().applyMarqueeSelection([chip], "subtract");
480
+ });
481
+
482
+ expect(receipt).toEqual({ changed: true, count: 1 });
483
+ expect(harness.current().domEditGroupSelections).toHaveLength(1);
484
+ expect(harness.current().domEditSelection?.element).toBe(card.element);
485
+ expect(harness.timeline.setTimelineSelectionSet).toHaveBeenLastCalledWith(new Set(["card"]));
486
+ expect(harness.timeline.setSelectedTimelineElementId).toHaveBeenLastCalledWith("card", {
487
+ preserveSet: true,
488
+ });
489
+ } finally {
490
+ harness.cleanup();
491
+ }
492
+ });
493
+
494
+ it("re-anchors on a survivor when the primary is subtracted", () => {
495
+ const { harness, card, chip } = renderCardAndChip();
496
+ try {
497
+ act(() => harness.current().applyMarqueeSelection([card, chip], "replace"));
498
+ expect(harness.current().domEditSelection?.element).toBe(card.element);
499
+
500
+ act(() => harness.current().applyMarqueeSelection([card], "subtract"));
501
+
502
+ expect(harness.current().domEditSelection?.element).toBe(chip.element);
503
+ expect(harness.current().domEditGroupSelections).toHaveLength(1);
504
+ expect(harness.timeline.setSelectedTimelineElementId).toHaveBeenLastCalledWith("chip", {
505
+ preserveSet: true,
506
+ });
507
+ } finally {
508
+ harness.cleanup();
509
+ }
510
+ });
511
+
512
+ it("clears the selection when every member is subtracted", () => {
513
+ const { harness, card, chip } = renderCardAndChip();
514
+ try {
515
+ act(() => harness.current().applyMarqueeSelection([card, chip], "replace"));
516
+ let receipt!: ReturnType<ReturnType<typeof useDomSelection>["applyMarqueeSelection"]>;
517
+ act(() => {
518
+ receipt = harness.current().applyMarqueeSelection([chip, card], "subtract");
519
+ });
520
+
521
+ expect(receipt).toEqual({ changed: true, count: 0 });
522
+ expect(harness.current().domEditSelection).toBeNull();
523
+ expect(harness.current().domEditGroupSelections).toHaveLength(0);
524
+ } finally {
525
+ harness.cleanup();
526
+ }
527
+ });
528
+
529
+ it("leaves the selection alone when the band covers nothing or only outsiders", () => {
530
+ const { harness, card, chip } = renderCardAndChip();
531
+ const other = makeSelection(
532
+ "Other",
533
+ Object.assign(document.createElement("div"), { id: "other" }),
534
+ );
535
+ try {
536
+ act(() => harness.current().applyMarqueeSelection([card], "replace"));
537
+ let receipt!: ReturnType<ReturnType<typeof useDomSelection>["applyMarqueeSelection"]>;
538
+ act(() => {
539
+ receipt = harness.current().applyMarqueeSelection([], "subtract");
540
+ });
541
+ expect(receipt).toEqual({ changed: false, count: 1 });
542
+ act(() => {
543
+ receipt = harness.current().applyMarqueeSelection([chip, other], "subtract");
544
+ });
545
+ expect(receipt).toEqual({ changed: false, count: 1 });
546
+ expect(harness.current().domEditSelection?.element).toBe(card.element);
547
+ } finally {
548
+ harness.cleanup();
549
+ }
550
+ });
551
+ });