refactor(web): centralize touch mouse adapters

apps/web/src/hooks/timelineTouch.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { getTouchPoint, resolveTouchDragDecision } from "./timelineTouch.js";
+import { createTouchMouseDownEvent, getTouchPoint, resolveTouchDragDecision } from "./timelineTouch.js";
 
 describe("timelineTouch", () => {
   it("falls back from active touches to changedTouches and then zeroes", () => {
@@ -72,4 +72,25 @@ describe("timelineTouch", () => {
       shouldHandleDrag: true,
     });
   });
+
+  it("creates a primary-button mouse-down adapter for touch handlers", () => {
+    const currentTarget = new EventTarget();
+
+    expect(createTouchMouseDownEvent({ clientX: 42, clientY: 17 }, currentTarget)).toMatchObject({
+      button: 0,
+      clientX: 42,
+      currentTarget,
+      shiftKey: false,
+    });
+  });
+
+  it("allows missing targets when creating a touch mouse-down adapter", () => {
+    const event = createTouchMouseDownEvent({ clientX: 7, clientY: 9 });
+
+    expect(event.currentTarget).toBeNull();
+    expect(() => {
+      event.preventDefault();
+      event.stopPropagation();
+    }).not.toThrow();
+  });
 });

apps/web/src/hooks/timelineTouch.ts

@@ -9,6 +9,15 @@ export type TouchDecisionState = {
   decided: boolean;
 };
 
+export type TouchMouseDownEvent = {
+  button: number;
+  clientX: number;
+  currentTarget?: EventTarget | null;
+  shiftKey: boolean;
+  preventDefault: () => void;
+  stopPropagation: () => void;
+};
+
 type TouchLike = {
   clientX: number;
   clientY: number;
@@ -27,6 +36,20 @@ export function getTouchPoint(event: TouchEventLike): TouchPoint {
   };
 }
 
+export function createTouchMouseDownEvent(
+  point: TouchPoint,
+  currentTarget?: EventTarget | null,
+): TouchMouseDownEvent {
+  return {
+    button: 0,
+    clientX: point.clientX,
+    currentTarget: currentTarget ?? null,
+    shiftKey: false,
+    preventDefault: () => {},
+    stopPropagation: () => {},
+  };
+}
+
 export function resolveTouchDragDecision(
   state: TouchDecisionState,
   point: TouchPoint,

apps/web/src/hooks/useTimelineDrag.ts

@@ -33,7 +33,7 @@ import {
 } from "./timelineMultiSelect.js";
 import { reconcileOptimisticEntries } from "./timelineOptimisticAllocations.js";
 import { createRangeSelectionState, finalizeRangeSelection, updateRangeSelectionDraft } from "./timelineRangeSelection.js";
-import { getTouchPoint, resolveTouchDragDecision } from "./timelineTouch.js";
+import { createTouchMouseDownEvent, getTouchPoint, resolveTouchDragDecision, type TouchMouseDownEvent } from "./timelineTouch.js";
 
 const DRAG_CLICK_THRESHOLD_PX = 5;
 
@@ -525,7 +525,7 @@ export function useTimelineDrag({
 
   const onProjectBarMouseDown = useCallback(
     (
-      e: React.MouseEvent,
+      e: TouchMouseDownEvent,
       opts: {
         projectId: string;
         projectName: string;
@@ -568,7 +568,7 @@ export function useTimelineDrag({
   // Legacy — kept for backward compat (triggers project shift from allocation block)
   const onBlockMouseDown = useCallback(
     (
-      e: React.MouseEvent,
+      e: TouchMouseDownEvent,
       opts: {
         projectId: string;
         projectName: string;
@@ -606,7 +606,7 @@ export function useTimelineDrag({
 
   const onAllocMouseDown = useCallback(
     (
-      e: React.MouseEvent,
+      e: TouchMouseDownEvent,
       opts: {
         mode: AllocDragMode;
         allocationId: string;
@@ -802,7 +802,7 @@ export function useTimelineDrag({
 
   const onRowMouseDown = useCallback(
     (
-      e: React.MouseEvent,
+      e: TouchMouseDownEvent,
       opts: {
         resourceId: string;
         startDate: Date;
@@ -952,14 +952,7 @@ export function useTimelineDrag({
       e.preventDefault();
       const point = getTouchPoint(e);
       touchStartRef.current = { x: point.clientX, y: point.clientY, decided: true };
-      onProjectBarMouseDown(
+      onProjectBarMouseDown(createTouchMouseDownEvent(point, e.currentTarget), opts);
-        {
-          clientX: point.clientX,
-          preventDefault: () => {},
-          stopPropagation: () => {},
-        } as unknown as React.MouseEvent,
-        opts,
-      );
     },
     [onProjectBarMouseDown],
   );
@@ -984,14 +977,7 @@ export function useTimelineDrag({
       e.preventDefault();
       const point = getTouchPoint(e);
       touchStartRef.current = { x: point.clientX, y: point.clientY, decided: true };
-      onAllocMouseDown(
+      onAllocMouseDown(createTouchMouseDownEvent(point, e.currentTarget), opts);
-        {
-          clientX: point.clientX,
-          preventDefault: () => {},
-          stopPropagation: () => {},
-        } as unknown as React.MouseEvent,
-        opts,
-      );
     },
     [onAllocMouseDown],
   );
@@ -1008,14 +994,7 @@ export function useTimelineDrag({
       e.preventDefault();
       const point = getTouchPoint(e);
       touchStartRef.current = { x: point.clientX, y: point.clientY, decided: false };
-      onRowMouseDown(
+      onRowMouseDown(createTouchMouseDownEvent(point, e.currentTarget), opts);
-        {
-          clientX: point.clientX,
-          preventDefault: () => {},
-          stopPropagation: () => {},
-        } as unknown as React.MouseEvent,
-        opts,
-      );
     },
     [onRowMouseDown],
   );

scripts/check-architecture-guardrails.mjs

@@ -127,6 +127,10 @@ export const rules = [
         pattern: /\bexport function getTouchPoint\b/,
         message: "timeline touch helpers must keep touch coordinate fallback centralized",
       },
+      {
+        pattern: /\bexport function createTouchMouseDownEvent\b/,
+        message: "timeline touch helpers must keep touch-to-mouse adapter wiring centralized",
+      },
       {
         pattern: /\bexport function resolveTouchDragDecision\b/,
         message: "timeline touch helpers must keep scroll-vs-drag disambiguation centralized",
@@ -330,6 +334,10 @@ export const rules = [
         pattern: /\bfunction toClientX\b/,
         message: "timeline drag must not re-inline touch coordinate fallback helpers",
       },
+      {
+        pattern: /as unknown as React\.MouseEvent/,
+        message: "timeline drag must not re-inline synthetic touch mouse-down adapters",
+      },
       {
         pattern: /\bfunction (?:hasAllocationDateChange|shouldTreatAllocationDragAsClick|requiresAllocationFragmentExtraction|buildAllocationMovedSnapshot|reconcileOptimisticEntries)\b/,
         message: "timeline drag must not re-inline extracted optimistic or allocation finalize helper implementations",

scripts/check-architecture-guardrails.test.mjs

@@ -116,6 +116,7 @@ describe("architecture guardrails", () => {
     ]);
 
     assert.deepEqual(evaluateRule(touchRule, "export function getTouchPoint() {}\n"), [
+      "apps/web/src/hooks/timelineTouch.ts: missing guardrail anchor: timeline touch helpers must keep touch-to-mouse adapter wiring centralized",
       "apps/web/src/hooks/timelineTouch.ts: missing guardrail anchor: timeline touch helpers must keep scroll-vs-drag disambiguation centralized",
     ]);
 
@@ -158,5 +159,25 @@ describe("architecture guardrails", () => {
     assert.deepEqual(evaluateRule(projectDragRule, "export function createProjectDragState() {}\n"), [
       "apps/web/src/hooks/timelineProjectDrag.ts: missing guardrail anchor: timeline project drag helpers must keep no-op project-shift mutation gating centralized",
     ]);
+
+    assert.deepEqual(
+      evaluateRule(
+        dragRule,
+        'import { getTouchPoint } from "./timelineTouch.js";\nconst e = {} as unknown as React.MouseEvent;\n',
+      ),
+      [
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep live preview behavior delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep multi-select rectangle lifecycle delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep range preview and finalization delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep optimistic allocation reconciliation delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep allocation drag completion rules delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep allocation click and mutation plan derivation delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep document mouse listener lifecycle delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep allocation multi-drag rules delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep allocation drag bootstrap delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: missing guardrail anchor: timeline drag must keep project drag bootstrap and mutation gating delegated to the extracted helper module",
+        "apps/web/src/hooks/useTimelineDrag.ts: forbidden pattern matched: timeline drag must not re-inline synthetic touch mouse-down adapters",
+      ],
+    );
   });
 });