# packages/core/src/lib/manipulation/controller.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/lib/manipulation/controller.ts#L194). [Back to reference](/reference/hooks/use-manipulation/) 
1 import {
2   batch,
3   signal,
4   isSignal,
5   untracked,
6   assertSignalCommandAllowed,
7   assertDirectSignalWriteAllowed,
8 } from "../signals/graph.js";
9 import { resolveSignalValue } from "../signals/resolve-signal-value.js";
10 import { requireHookContext, useHookSlot } from "../hooks/hook-slot.js";
11 import { queueBeginCommand } from "../scheduler/realm-scheduler.js";
12 import type {
13   PibblEventHandlers,
14   PibblEventTarget,
15   PibblPointerEvent,
16   PibblKeyboardEvent,
17 } from "../events/types.js";
18 import type { PibblComponentRefs, PibblInstance } from "../types.js";
19 import type { WritableSignal } from "../signals/types.js";
20 import {
21   observeGestureInputs,
22   claimGeometryGeneration,
23   restoreReleasedGesture,
24 } from "./ownership.js";
25 import { suppressManipulationActivation } from "../events/dispatch.js";
26 import { solveManipulation } from "./solve.js";
27 import {
28   currentRootCoordinateMapping,
29   sameRootCoordinateMapping,
30 } from "./coordinates.js";
31 import type { PibblResizePosition } from "./types.js";
32 import type {
33   PibblManipulationActive,
34   PibblManipulationCancelReason,
35   PibblManipulationController,
36   PibblManipulationEvent,
37   PibblManipulationGeometry,
38   PibblManipulationOperation,
39   PibblManipulationOptions,
40   PibblManipulationSnapshot,
41 } from "./controller-types.js";
42 
43 type PointerSample = Pick<
44   PibblPointerEvent,
45   | "pointerId"
46   | "x"
47   | "y"
48   | "clientX"
49   | "clientY"
50   | "shiftKey"
51   | "altKey"
52   | "ctrlKey"
53   | "metaKey"
54 >;
55 interface Session {
56   operation: PibblManipulationOperation;
57   handle?: PibblResizePosition;
58   pointerId: number;
59   target: PibblEventTarget;
60   before: PibblManipulationGeometry;
61   last: PibblManipulationGeometry;
62   point: DOMPoint;
63   clientX: number;
64   clientY: number;
65   parent: DOMMatrix;
66   started: boolean;
67   angle: number;
68   rotationDelta: number;
69   snapshot: PibblManipulationSnapshot;
70   coordinateMapping: readonly number[];
71   source?: object;
72   releaseObservation?: () => void;
73   sample?: PointerSample;
74 }
75 export interface ManipulationState {
76   controller: PibblManipulationController;
77   options: PibblManipulationOptions;
78   alive: boolean;
79   root: PibblInstance;
80   frame?: PibblComponentRefs<any>;
81   parent: DOMMatrix;
82   coordinateMapping?: readonly number[];
83   session?: Session;
84   active: WritableSignal<PibblManipulationActive | null>;
85   snapshot: WritableSignal<PibblManipulationSnapshot | null>;
86 }
87 const states = new WeakMap<PibblManipulationController, ManipulationState>();
88 const owners = new WeakMap<object, ManipulationState>();
89 const claimedPresses = new WeakSet<Event>();
90 export function manipulationState(
91   controller: PibblManipulationController,
92 ): ManipulationState {
93   const state = states.get(controller);
94   if (!state || !state.alive)
95     throw new Error(
96       "Pibbl manipulation requires a live useManipulation controller.",
97     );
98   return state;
99 }
100 function geometry(state: ManipulationState): PibblManipulationGeometry {
101   return untracked(() =>
102     Object.freeze({
103       box: Object.freeze({ ...state.options.box.get() }),
104       rotation: state.options.rotation?.get() ?? 0,
105     }),
106   );
107 }
108 function same(a: PibblManipulationGeometry, b: PibblManipulationGeometry): boolean {
109   return (
110     a.rotation === b.rotation &&
111     a.box.left === b.box.left &&
112     a.box.top === b.box.top &&
113     a.box.width === b.box.width &&
114     a.box.height === b.box.height
115   );
116 }
117 function event(session: Session): PibblManipulationEvent {
118   return Object.freeze({
119     ...session.snapshot,
120     before: session.before,
121     after: session.last,
122   });
123 }
124 function publish(
125   state: ManipulationState,
126   next: PibblManipulationGeometry,
127 ): void {
128   assertDirectSignalWriteAllowed(state.options.box);
129   if (state.options.rotation)
130     assertDirectSignalWriteAllowed(state.options.rotation);
131   batch(() => {
132     state.options.box.set(next.box);
133     if (state.options.rotation) state.options.rotation.set(next.rotation);
134   });
135 }
136 function release(state: ManipulationState, session: Session): void {
137   if (state.session !== session) return;
138   state.session = undefined;
139   session.releaseObservation?.();
140   session.releaseObservation = undefined;
141   if (state.options.rotation && owners.get(state.options.rotation) === state)
142     owners.delete(state.options.rotation);
143   if (owners.get(state.options.box) === state) owners.delete(state.options.box);
144   if (session.target.hasPointerCapture(session.pointerId))
145     session.target.releasePointerCapture(session.pointerId);
146 }
147 function cancel(
148   state: ManipulationState,
149   reason: PibblManipulationCancelReason,
150 ): void {
151   const session = state.session;
152   if (!session) return;
153   const restore =
154     same(geometry(state), session.last) && reason !== "external-change";
155   release(state, session);
156   batch(() => {
157     if (restore && session.started) publish(state, session.before);
158     state.active.set(null);
159   });
160   if (session.started)
161     state.options.onCancel?.(
162       Object.freeze({ ...event(session), after: geometry(state), reason }),
163     );
164 }
165 /** Release capture synchronously; rollback can defer under renderer write guards. */
166 export function detachManipulationFrame(state: ManipulationState): void {
167   const session = state.session;
168   if (!session) return;
169   const restore = same(geometry(state), session.last);
170   release(state, session);
171   restoreReleasedGesture({
172     box: state.options.box,
173     rotation: state.options.rotation,
174     before: restore ? session.before : geometry(state),
175     active: state.active,
176   });
177 }
178 function dispose(state: ManipulationState): void {
179   if (!state.alive) return;
180   state.alive = false;
181   detachManipulationFrame(state);
182 }
183 /**
184  * Creates a mount-owned controller for moving, resizing, and rotating declared geometry.
185  *
186  * @param options - Target state, enabled operations, constraints, and lifecycle callbacks. See
187  * {@link PibblManipulationOptions} .
188  * @returns Stable controls and state for the mounted manipulation interaction. See
189  * {@link PibblManipulationController} .
190  *
191  * @see {@link PibblManipulationOptions}
192  * @see {@link PibblManipulationController}
193  */
194 export function useManipulation(
195   options: PibblManipulationOptions,
196 ): PibblManipulationController {
197   const { pibblInstance } = requireHookContext();
198   const slot = useHookSlot<ManipulationState>("manipulation", (teardowns) => {
199     const state = {
200       options,
201       root: pibblInstance.eventRoot.rootInstance ?? pibblInstance,
202       alive: true,
203       parent: new DOMMatrix(),
204       active: signal<PibblManipulationActive | null>(null),
205       snapshot: signal<PibblManipulationSnapshot | null>(null),
206     } as ManipulationState;
207     const controller: PibblManipulationController = Object.freeze({
208       active: state.active.asReadonly(),
209       snapshot: state.snapshot.asReadonly(),
210       get frameProps() {
211         return frameProps;
212       },
213       cancel() {
214         if (state.alive) {
215           assertSignalCommandAllowed();
216           cancel(state, "explicit");
217         }
218       },
219     });
220     const frameProps = Object.freeze({ controller, style: options.box });
221     state.controller = controller;
222     states.set(controller, state);
223     teardowns.add(() => dispose(state));
224     return state;
225   });
226   const state = slot.value;
227   if (options.rotate && !options.rotation)
228     throw new Error(
229       "useManipulation rotate requires a writable rotation signal in radians.",
230     );
231   if (
232     options.box !== state.options.box ||
233     options.rotation !== state.options.rotation
234   )
235     throw new Error(
236       "useManipulation geometry signal identity must remain stable.",
237     );
238   state.options = options;
239   if (state.session && !enabled(state, state.session.operation)) {
240     const session = state.session;
241     queueBeginCommand(() => {
242       if (state.alive && state.session === session) cancel(state, "disabled");
243     });
244   }
245   return state.controller;
246 }
247 function enabled(
248   state: ManipulationState,
249   operation: PibblManipulationOperation,
250 ): boolean {
251   const options =
252     operation === "move"
253       ? state.options.move
254       : operation === "resize"
255         ? state.options.resize
256         : state.options.rotate;
257   return options !== undefined && resolveSignalValue(options.enabled ?? true);
258 }
259 function validateSession(state: ManipulationState): Session | undefined {
260   const session = state.session;
261   if (!session) return;
262   if (!same(geometry(state), session.last)) {
263     cancel(state, "external-change");
264     return;
265   }
266   if (!enabled(state, session.operation)) {
267     cancel(state, "disabled");
268     return;
269   }
270   if (
271     !sameRootCoordinateMapping(
272       session.coordinateMapping,
273       currentRootCoordinateMapping(state.root),
274     ) ||
275     (state.coordinateMapping !== undefined &&
276       !sameRootCoordinateMapping(
277         session.coordinateMapping,
278         state.coordinateMapping,
279       ))
280   ) {
281     cancel(state, "coordinate-space-changed");
282     return;
283   }
284   if (
285     ["a", "b", "c", "d", "e", "f"].some(
286       (key) =>
287         Math.abs(state.parent[key as "a"] - session.parent[key as "a"]) >
288         1e-10 *
289           Math.max(
290             1,
291             Math.abs(state.parent[key as "a"]),
292             Math.abs(session.parent[key as "a"]),
293           ),
294     )
295   ) {
296     cancel(state, "coordinate-space-changed");
297     return;
298   }
299   return session;
300 }
301 function resolvedOptions(state: ManipulationState) {
302   const options = state.options;
303   const move = options.move && {
304     ...options.move,
305     snap: options.move.snap && {
306       ...options.move.snap,
307       enabled: resolveSignalValue(options.move.snap.enabled ?? true),
308     },
309   };
310   const resize = options.resize && {
311     ...options.resize,
312     snap: options.resize.snap && {
313       ...options.resize.snap,
314       enabled: resolveSignalValue(options.resize.snap.enabled ?? true),
315     },
316   };
317   const rotate = options.rotate && {
318     ...options.rotate,
319     snap: options.rotate.snap && {
320       ...options.rotate.snap,
321       enabled: resolveSignalValue(options.rotate.snap.enabled ?? true),
322     },
323   };
324   return { move, resize, rotate };
325 }
326 function apply(state: ManipulationState, pointer: PointerSample): void {
327   const session = validateSession(state);
328   if (!session || pointer.pointerId !== session.pointerId) return;
329   session.sample = {
330     pointerId: pointer.pointerId,
331     x: pointer.x,
332     y: pointer.y,
333     clientX: pointer.clientX,
334     clientY: pointer.clientY,
335     shiftKey: pointer.shiftKey,
336     altKey: pointer.altKey,
337     ctrlKey: pointer.ctrlKey,
338     metaKey: pointer.metaKey,
339   };
340   if (!session.started) {
341     if (
342       Math.hypot(
343         pointer.clientX - session.clientX,
344         pointer.clientY - session.clientY,
345       ) < 3
346     )
347       return;
348     session.started = true;
349     suppressManipulationActivation(state.root, session.pointerId);
350     state.active.set(
351       Object.freeze({
352         operation: session.operation,
353         handle: session.handle ?? null,
354         pointerId: session.pointerId,
355       }),
356     );
357     state.options.onStart?.(event(session));
358     if (validateSession(state) !== session) return;
359   }
360   const { move, resize, rotate } = resolvedOptions(state);
361   const currentPoint = session.parent
362     .inverse()
363     .transformPoint(new DOMPoint(pointer.x, pointer.y));
364   if (session.operation === "rotate") {
365     const centerX = session.before.box.left + session.before.box.width / 2;
366     const centerY = session.before.box.top + session.before.box.height / 2;
367     if (currentPoint.x !== centerX || currentPoint.y !== centerY) {
368       const angle = Math.atan2(
369         currentPoint.y - centerY,
370         currentPoint.x - centerX,
371       );
372       const delta = angle - session.angle;
373       session.rotationDelta += Math.atan2(Math.sin(delta), Math.cos(delta));
374       session.angle = angle;
375     }
376   }
377   let result: ReturnType<typeof solveManipulation>;
378   try {
379     result = solveManipulation({
380       operation: session.operation,
381       handle: session.handle,
382       initial: session.before.box,
383       initialPoint: session.point,
384       currentPoint,
385       initialRotation: session.before.rotation,
386       rotationDelta: session.rotationDelta,
387       modifiers: {
388         shift: pointer.shiftKey,
389         alt: pointer.altKey,
390         ctrl: pointer.ctrlKey,
391         meta: pointer.metaKey,
392       },
393       move,
394       resize,
395       rotate,
396     });
397   } catch {
398     // Options can change after activation; the original preview still belongs
399     // to this gesture and must be restored through the normal terminal path.
400     cancel(state, "constraints-unsatisfiable");
401     return;
402   }
403   const next = Object.freeze({
404     box: result.applied,
405     rotation: result.appliedRotation,
406   });
407   const changed = !same(next, session.last);
408   session.last = next;
409   session.snapshot = Object.freeze({
410     operation: session.operation,
411     handle: session.handle ?? null,
412     initial: session.before,
413     proposed: Object.freeze({
414       box: result.proposed,
415       rotation: result.proposedRotation,
416     }),
417     applied: next,
418     snapActive: result.snapActive,
419     snapSatisfied: result.snapSatisfied,
420   });
421   batch(() => {
422     if (changed) publish(state, next);
423     state.snapshot.set(session.snapshot);
424   });
425   if (validateSession(state) !== session) return;
426   if (changed) state.options.onChange?.(event(session));
427 }
428 function applySafely(state: ManipulationState, pointer: PointerSample): void {
429   try {
430     apply(state, pointer);
431   } catch (error) {
432     try {
433       cancel(state, "explicit");
434     } catch (cleanupError) {
435       throw new AggregateError(
436         [error, cleanupError],
437         "Manipulation callback and cleanup failed.",
438         { cause: cleanupError },
439       );
440     }
441     throw error;
442   }
443 }
444 function updateModifiers(
445   state: ManipulationState,
446   key: PibblKeyboardEvent,
447 ): void {
448   const sample = state.session?.sample;
449   if (!sample || !["Shift", "Alt", "Control", "Meta"].includes(key.key)) return;
450   applySafely(state, {
451     ...sample,
452     shiftKey: key.shiftKey,
453     altKey: key.altKey,
454     ctrlKey: key.ctrlKey,
455     metaKey: key.metaKey,
456   });
457 }
458 
459 /** @internal Identifies one private handle source for readout presentation. */
460 export function isManipulationSourceActive(
461   controller: PibblManipulationController,
462   source: object,
463 ): boolean {
464   const state = manipulationState(controller);
465   return state.session?.started === true && state.session.source === source;
466 }
467 
468 export function manipulationHandlers(
469   controller: PibblManipulationController,
470   operation: PibblManipulationOperation,
471   handle?: PibblResizePosition,
472   source?: object,
473 ): PibblEventHandlers {
474   const state = manipulationState(controller);
475   return {
476     onPointerDown(pointer) {
477       if (
478         !state.alive ||
479         state.session ||
480         pointer.defaultPrevented ||
481         claimedPresses.has(pointer.originalEvent) ||
482         pointer.button !== 0 ||
483         !enabled(state, operation)
484       )
485         return;
486       if (
487         owners.has(state.options.box) ||
488         (state.options.rotation && owners.has(state.options.rotation))
489       )
490         throw new Error(
491           "Pibbl manipulation geometry already has an active owner.",
492         );
493       const before = geometry(state);
494       const point = state.parent
495         .inverse()
496         .transformPoint(new DOMPoint(pointer.x, pointer.y));
497       if (!Number.isFinite(point.x) || !Number.isFinite(point.y))
498         throw new Error(
499           "Pibbl manipulation cannot use a singular parent transform.",
500         );
501       assertDirectSignalWriteAllowed(state.options.box);
502       if (state.options.rotation)
503         assertDirectSignalWriteAllowed(state.options.rotation);
504       const resolved = resolvedOptions(state);
505       if (
506         operation === "resize" &&
507         resolved.resize?.snap?.target === "grid" &&
508         (Math.abs(state.parent.b) > 1e-10 || Math.abs(state.parent.c) > 1e-10)
509       ) {
510         throw new Error(
511           "Grid resize snapping requires an aligned parent coordinate mapping.",
512         );
513       }
514       solveManipulation({
515         operation,
516         handle,
517         initial: before.box,
518         initialRotation: before.rotation,
519         initialPoint: point,
520         currentPoint: point,
521         modifiers: {},
522         ...resolved,
523       });
524       pointer.currentTarget.setPointerCapture(pointer.pointerId);
525       if (!pointer.currentTarget.hasPointerCapture(pointer.pointerId)) return;
526       const snapshot = Object.freeze({
527         operation,
528         handle: handle ?? null,
529         initial: before,
530         proposed: before,
531         applied: before,
532         snapActive: false,
533         snapSatisfied: false,
534       });
535       state.session = {
536         operation,
537         handle,
538         pointerId: pointer.pointerId,
539         target: pointer.currentTarget,
540         before,
541         last: before,
542         point,
543         clientX: pointer.clientX,
544         clientY: pointer.clientY,
545         parent: DOMMatrix.fromMatrix(state.parent),
546         started: false,
547         angle: Math.atan2(
548           point.y - before.box.top - before.box.height / 2,
549           point.x - before.box.left - before.box.width / 2,
550         ),
551         rotationDelta: 0,
552         snapshot,
553         coordinateMapping: currentRootCoordinateMapping(state.root),
554         source,
555       };
556       owners.set(state.options.box, state);
557       if (state.options.rotation) owners.set(state.options.rotation, state);
558       claimGeometryGeneration(state.options.box, state.options.rotation);
559       const operationOptions =
560         operation === "move"
561           ? state.options.move
562           : operation === "resize"
563             ? state.options.resize
564             : state.options.rotate;
565       const values: unknown[] = [
566         state.options.box,
567         state.options.rotation,
568         operationOptions?.enabled,
569       ];
570       const inputs = values.filter(isSignal);
571       state.session.releaseObservation = observeGestureInputs(inputs, () => {
572         validateSession(state);
573       });
574       claimedPresses.add(pointer.originalEvent);
575     },
576     onPointerMove(pointer) {
577       applySafely(state, pointer);
578     },
579     onPointerUp(pointer) {
580       if (state.session?.pointerId !== pointer.pointerId) return;
581       applySafely(state, pointer);
582       const session = state.session;
583       if (!session) return;
584       release(state, session);
585       state.active.set(null);
586       if (session.started)
587         state.options.onCommit?.(
588           Object.freeze({
589             ...event(session),
590             changed: !same(session.before, session.last),
591           }),
592         );
593     },
594     onPointerCancel(pointer) {
595       if (state.session?.pointerId === pointer.pointerId)
596         cancel(state, "pointer-cancel");
597     },
598     onLostPointerCapture(pointer) {
599       if (state.session?.pointerId === pointer.pointerId)
600         cancel(state, "capture-lost");
601     },
602     onKeyUp(key) {
603       updateModifiers(state, key);
604     },
605     onKeyDown(key) {
606       if (key.key === "Escape") cancel(state, "escape");
607       else updateModifiers(state, key);
608     },
609   };
610 }
611
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.