@ifc-lite/viewer 1.17.6 → 1.18.0

package/src/components/viewer/schedule/schedule-selection.ts

@@ -0,0 +1,163 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * schedule-selection — pure helpers for Gantt ↔ 3D viewport sync.
+ *
+ * Two public surfaces:
+ *
+ *  1. `collectProductLocalIdsForTasks` — given a set of Gantt-selected task
+ *     globalIds, walk the task tree and return the *union* of every
+ *     descendant task's `productExpressIds`. Selecting a parent row in the
+ *     Gantt therefore isolates every leaf below it — matching the mental
+ *     model that a WBS row represents "all the work under this heading".
+ *
+ *  2. `findTaskForProductGlobalId` — reverse lookup used by the viewport →
+ *     Gantt sync: user clicks a product in 3D, we find the first task that
+ *     claims it and highlight that row in the Gantt (expanding ancestors
+ *     so the row is visible).
+ *
+ * All functions are pure and side-effect-free; the React hooks in
+ * `useGanttSelection3DSync` / `useViewportToGanttSync` wire them into the
+ * store.
+ */
+
+import type { ScheduleExtraction, ScheduleTaskInfo } from '@ifc-lite/parser';
+
+/**
+ * Walk the task graph starting at `rootGlobalIds`, collecting every
+ * descendant task's LOCAL product expressIds (including each root itself).
+ *
+ * "Descendants" follows `task.childGlobalIds`. Cycles are defended against
+ * via a visited set — schedule data from `extractScheduleOnDemand` is a
+ * forest in practice, but we don't trust that at this boundary.
+ *
+ * Returns LOCAL expressIds. The caller federation-translates them via
+ * `toGlobalIdFromModels` since the viewport operates on globals.
+ */
+export function collectProductLocalIdsForTasks(
+  data: ScheduleExtraction | null,
+  rootGlobalIds: Iterable<string>,
+): Set<number> {
+  const productIds = new Set<number>();
+  if (!data || data.tasks.length === 0) return productIds;
+
+  const byGlobalId = new Map<string, ScheduleTaskInfo>();
+  for (const task of data.tasks) byGlobalId.set(task.globalId, task);
+
+  const visited = new Set<string>();
+  const queue: string[] = [];
+  for (const g of rootGlobalIds) {
+    if (byGlobalId.has(g) && !visited.has(g)) {
+      queue.push(g);
+      visited.add(g);
+    }
+  }
+
+  while (queue.length > 0) {
+    const gid = queue.shift()!;
+    const task = byGlobalId.get(gid);
+    if (!task) continue;
+    for (const local of task.productExpressIds) {
+      productIds.add(local);
+    }
+    for (const childGid of task.childGlobalIds) {
+      if (!visited.has(childGid) && byGlobalId.has(childGid)) {
+        visited.add(childGid);
+        queue.push(childGid);
+      }
+    }
+  }
+  return productIds;
+}
+
+/**
+ * Find the *first* task in the schedule whose product list contains the
+ * given globalId (renderer-space / federated ID), returning its task
+ * globalId plus the full ancestor chain so the Gantt can expand rows to
+ * reveal it.
+ *
+ * Multi-task assignment is rare but happens — we return the first match in
+ * `data.tasks` iteration order, which is a deterministic function of the
+ * STEP file. Callers that need multi-match behaviour can layer on top.
+ */
+export interface TaskHitForProduct {
+  /** globalId of the task that owns the product. */
+  taskGlobalId: string;
+  /** Ancestor task globalIds from root → direct parent (excludes the hit). */
+  ancestorGlobalIds: string[];
+}
+
+export function findTaskForProductGlobalId(
+  data: ScheduleExtraction | null,
+  productGlobalId: number,
+): TaskHitForProduct | null {
+  if (!data || data.tasks.length === 0) return null;
+
+  // Fast path: generated schedules populate `productGlobalIds` with the
+  // renderer-space IDs, so we can string-match the number directly. For
+  // extracted schedules the field may be empty — in that case we fall back
+  // to a per-model local-id scan (not implemented here; the caller is
+  // expected to have pre-translated productGlobalIds for extracted data).
+  const productIdStr = String(productGlobalId);
+  const hit = data.tasks.find(t => t.productGlobalIds.includes(productIdStr));
+  if (!hit) return null;
+
+  // Walk parent pointers to build the ancestor chain. `parentGlobalId` may
+  // be absent for root tasks — we stop at the first missing link.
+  const byGlobalId = new Map<string, ScheduleTaskInfo>();
+  for (const task of data.tasks) byGlobalId.set(task.globalId, task);
+
+  const ancestors: string[] = [];
+  const seen = new Set<string>([hit.globalId]);
+  let cursor = hit.parentGlobalId;
+  while (cursor && !seen.has(cursor)) {
+    seen.add(cursor);
+    ancestors.unshift(cursor);
+    const parent = byGlobalId.get(cursor);
+    cursor = parent?.parentGlobalId;
+  }
+
+  return { taskGlobalId: hit.globalId, ancestorGlobalIds: ancestors };
+}
+
+/**
+ * Reverse lookup that also handles extracted (non-generated) schedules,
+ * which don't pre-populate `productGlobalIds`. The caller supplies a
+ * `localFromGlobal(globalId) => localExpressId` federation translator.
+ *
+ * If the schedule is generated (has non-empty productGlobalIds), the
+ * cheap string-match path inside `findTaskForProductGlobalId` wins and
+ * this fallback is not reached.
+ */
+export function findTaskForProductGlobalIdWithLocal(
+  data: ScheduleExtraction | null,
+  productGlobalId: number,
+  localFromGlobal: (globalId: number) => number | undefined,
+): TaskHitForProduct | null {
+  const fast = findTaskForProductGlobalId(data, productGlobalId);
+  if (fast) return fast;
+  if (!data) return null;
+
+  const local = localFromGlobal(productGlobalId);
+  if (local === undefined) return null;
+
+  const hit = data.tasks.find(t => t.productExpressIds.includes(local));
+  if (!hit) return null;
+
+  const byGlobalId = new Map<string, ScheduleTaskInfo>();
+  for (const task of data.tasks) byGlobalId.set(task.globalId, task);
+
+  const ancestors: string[] = [];
+  const seen = new Set<string>([hit.globalId]);
+  let cursor = hit.parentGlobalId;
+  while (cursor && !seen.has(cursor)) {
+    seen.add(cursor);
+    ancestors.unshift(cursor);
+    const parent = byGlobalId.get(cursor);
+    cursor = parent?.parentGlobalId;
+  }
+
+  return { taskGlobalId: hit.globalId, ancestorGlobalIds: ancestors };
+}

package/src/components/viewer/schedule/schedule-utils.ts

@@ -0,0 +1,223 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Helpers for the Gantt UI — date formatting, tick generation, and the
+ * task-tree flattener that feeds the virtualized list.
+ */
+
+import type { ScheduleExtraction, ScheduleTaskInfo } from '@ifc-lite/parser';
+import type { GanttTimeScale } from '@/store';
+import { taskStartEpoch, taskFinishEpoch } from '@/store';
+
+export interface FlattenedTask {
+  task: ScheduleTaskInfo;
+  depth: number;
+  hasChildren: boolean;
+  expanded: boolean;
+}
+
+/**
+ * Flatten a task tree into the display order used by the Gantt list,
+ * honoring the current expanded set. Tasks without parents are treated as
+ * roots; each root and its expanded descendants appear in depth-first order.
+ */
+export function flattenTaskTree(
+  data: ScheduleExtraction | null,
+  expanded: Set<string>,
+  filterScheduleGlobalId?: string,
+): FlattenedTask[] {
+  if (!data) return [];
+  const taskByGlobalId = new Map<string, ScheduleTaskInfo>();
+  for (const t of data.tasks) taskByGlobalId.set(t.globalId, t);
+
+  /**
+   * A task is in-scope when no schedule filter is active, or when it (or any
+   * descendant) is controlled by the filter. Ancestors pass through so the
+   * expand/collapse chain stays visible even when only a leaf matches.
+   */
+  const isVisibleForSchedule = (task: ScheduleTaskInfo): boolean => (
+    !filterScheduleGlobalId
+    || task.controllingScheduleGlobalIds.includes(filterScheduleGlobalId)
+    || descendantsInSchedule(task, taskByGlobalId, filterScheduleGlobalId)
+  );
+
+  const result: FlattenedTask[] = [];
+  const roots = data.tasks.filter(t => !t.parentGlobalId);
+  const filteredRoots = roots.filter(isVisibleForSchedule);
+
+  const visit = (task: ScheduleTaskInfo, depth: number) => {
+    const hasChildren = task.childGlobalIds.length > 0;
+    const isExpanded = expanded.has(task.globalId);
+    result.push({ task, depth, hasChildren, expanded: isExpanded });
+    if (hasChildren && isExpanded) {
+      for (const childGid of task.childGlobalIds) {
+        const child = taskByGlobalId.get(childGid);
+        // Reuse the same predicate so out-of-scope descendants don't leak
+        // through an in-scope ancestor.
+        if (child && isVisibleForSchedule(child)) visit(child, depth + 1);
+      }
+    }
+  };
+  for (const root of filteredRoots) visit(root, 0);
+
+  // Tasks that are not reachable through IfcRelNests from any root — append
+  // at depth 0 so they're not orphaned. Apply the same predicate so the
+  // schedule filter is respected.
+  const seen = new Set(result.map(r => r.task.globalId));
+  for (const task of data.tasks) {
+    if (seen.has(task.globalId)) continue;
+    if (!isVisibleForSchedule(task)) continue;
+    result.push({ task, depth: 0, hasChildren: false, expanded: false });
+  }
+
+  return result;
+}
+
+function descendantsInSchedule(
+  task: ScheduleTaskInfo,
+  index: Map<string, ScheduleTaskInfo>,
+  scheduleGid: string,
+): boolean {
+  for (const childGid of task.childGlobalIds) {
+    const child = index.get(childGid);
+    if (!child) continue;
+    if (child.controllingScheduleGlobalIds.includes(scheduleGid)) return true;
+    if (descendantsInSchedule(child, index, scheduleGid)) return true;
+  }
+  return false;
+}
+
+/**
+ * Compute evenly spaced tick marks across [start..end] matching the given
+ * time scale. Returns tick timestamps in epoch ms.
+ */
+export function computeTicks(
+  start: number,
+  end: number,
+  scale: GanttTimeScale,
+): number[] {
+  const ticks: number[] = [];
+  if (end <= start) return [start];
+  const startDate = new Date(start);
+
+  const addTick = (t: number) => { if (t >= start && t <= end) ticks.push(t); };
+
+  switch (scale) {
+    case 'hour': {
+      const step = 3_600_000;
+      for (let t = Math.ceil(start / step) * step; t <= end; t += step) addTick(t);
+      break;
+    }
+    case 'day': {
+      const d = new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate());
+      while (d.getTime() <= end) {
+        addTick(d.getTime());
+        d.setDate(d.getDate() + 1);
+      }
+      break;
+    }
+    case 'week': {
+      const d = new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate());
+      // Back up to the previous Monday (ISO week anchor).
+      d.setDate(d.getDate() - ((d.getDay() + 6) % 7));
+      while (d.getTime() <= end) {
+        addTick(d.getTime());
+        d.setDate(d.getDate() + 7);
+      }
+      break;
+    }
+    case 'month': {
+      const d = new Date(startDate.getFullYear(), startDate.getMonth(), 1);
+      while (d.getTime() <= end) {
+        addTick(d.getTime());
+        d.setMonth(d.getMonth() + 1);
+      }
+      break;
+    }
+    case 'year': {
+      const d = new Date(startDate.getFullYear(), 0, 1);
+      while (d.getTime() <= end) {
+        addTick(d.getTime());
+        d.setFullYear(d.getFullYear() + 1);
+      }
+      break;
+    }
+  }
+  // Always include endpoints for a clean label frame.
+  if (ticks[0] !== start) ticks.unshift(start);
+  if (ticks[ticks.length - 1] !== end) ticks.push(end);
+  return ticks;
+}
+
+export function formatTickLabel(t: number, scale: GanttTimeScale): string {
+  const d = new Date(t);
+  switch (scale) {
+    case 'hour':
+      return `${d.getHours().toString().padStart(2, '0')}:00`;
+    case 'day':
+    case 'week':
+      return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+    case 'month':
+      return d.toLocaleDateString(undefined, { month: 'short', year: 'numeric' });
+    case 'year':
+      return String(d.getFullYear());
+    default:
+      return d.toLocaleDateString();
+  }
+}
+
+export function formatDateTime(t: number | undefined): string {
+  if (t === undefined) return '—';
+  const d = new Date(t);
+  return d.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
+}
+
+/**
+ * Map an epoch ms to an x pixel given the timeline bounds.
+ */
+export function timeToX(t: number, start: number, end: number, pixelWidth: number): number {
+  if (end <= start) return 0;
+  const clamped = Math.min(Math.max(t, start), end);
+  return ((clamped - start) / (end - start)) * pixelWidth;
+}
+
+/**
+ * Utility for task bars — returns their horizontal start/width in pixels.
+ */
+export function taskBarGeometry(
+  task: ScheduleTaskInfo,
+  rangeStart: number,
+  rangeEnd: number,
+  pixelWidth: number,
+): { x: number; width: number } | null {
+  const start = taskStartEpoch(task);
+  const finish = taskFinishEpoch(task);
+  if (start === undefined || finish === undefined) return null;
+  const x = timeToX(start, rangeStart, rangeEnd, pixelWidth);
+  const x2 = timeToX(finish, rangeStart, rangeEnd, pixelWidth);
+  // Milestones have zero width — render as a diamond 10px wide; other tasks
+  // get at least 2px so they don't disappear at very wide zoom-outs.
+  const width = Math.max(task.isMilestone ? 0 : 2, x2 - x);
+  return { x, width };
+}
+
+/**
+ * Produce a short "5d" / "3h" / "2w" label from an ISO 8601 duration string.
+ */
+export function formatDurationShort(iso: string | undefined): string {
+  if (!iso) return '—';
+  const m = iso.match(/^P(?:(\d+(?:\.\d+)?)Y)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)W)?(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
+  if (!m) return iso;
+  const [, y, mo, w, d, h, mi, s] = m;
+  const parts: string[] = [];
+  if (y) parts.push(`${y}y`);
+  if (mo) parts.push(`${mo}mo`);
+  if (w) parts.push(`${w}w`);
+  if (d) parts.push(`${d}d`);
+  if (h) parts.push(`${h}h`);
+  if (mi) parts.push(`${mi}m`);
+  if (s) parts.push(`${s}s`);
+  return parts.length ? parts.join(' ') : '—';
+}

package/src/components/viewer/schedule/useConstructionSequence.ts

@@ -0,0 +1,156 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * useConstructionSequence — computes the 4D animation frame each playback
+ * tick and registers it as the 'animation' overlay layer. The compositor
+ * (`useOverlayCompositor`) does the actual write to the renderer.
+ *
+ * This hook no longer owns visibility reconciliation — that pattern
+ * (`contributedHiddenRef` / `contributedColorsRef`) lived here and was
+ * duplicated across every channel consumer. After P4 the compositor is
+ * the single writer to `hiddenEntities` / `pendingColorUpdates`, so this
+ * hook's only job is to emit its desired state as an overlay layer.
+ *
+ * Invariants:
+ *   • **Federation-awareness.** The animator returns local `productExpressIds`.
+ *     The renderer operates on global IDs. We translate via
+ *     `toGlobalIdFromModels` before registering the layer.
+ *
+ * Playback tick: a requestAnimationFrame loop advances `playbackTime` when
+ * `playbackIsPlaying` && `animationEnabled` are both true.
+ */
+
+import { useEffect } from 'react';
+import {
+  useViewerStore,
+  toGlobalIdFromModels,
+  type ForwardModelMapLike,
+} from '@/store';
+import { resolveScheduleSourceModelId } from '@/store/slices/schedule-edit-helpers';
+import { computeAnimationFrame, type RGBA } from './schedule-animator';
+
+/**
+ * Map the schedule's local product expressIds to renderer global IDs.
+ *
+ * Schedule extraction is per-model (the schedule-adapter caches one
+ * extraction per active model), so every local expressId is attributed to
+ * that model. Federation-aware per-product attribution — tasks whose
+ * `productExpressIds` span multiple models — would require extending
+ * `ScheduleExtraction` with a source-model field; explicit follow-up.
+ */
+function localIdsToGlobal<T>(
+  localMap: Map<number, T> | Set<number>,
+  models: ForwardModelMapLike,
+  activeModelId: string | null | undefined,
+): Map<number, T> | Set<number> {
+  const sourceModelId = resolveScheduleSourceModelId(models, activeModelId);
+
+  if (localMap instanceof Set) {
+    const out = new Set<number>();
+    for (const local of localMap) {
+      out.add(toGlobalIdFromModels(models, sourceModelId, local));
+    }
+    return out;
+  }
+  const out = new Map<number, T>();
+  for (const [local, v] of localMap) {
+    out.set(toGlobalIdFromModels(models, sourceModelId, local), v);
+  }
+  return out;
+}
+
+export function useConstructionSequence(): void {
+  const animationEnabled = useViewerStore(s => s.animationEnabled);
+  const isPlaying = useViewerStore(s => s.playbackIsPlaying);
+  const playbackTime = useViewerStore(s => s.playbackTime);
+  const scheduleData = useViewerStore(s => s.scheduleData);
+  const activeWorkScheduleId = useViewerStore(s => s.activeWorkScheduleId);
+  const advancePlaybackBy = useViewerStore(s => s.advancePlaybackBy);
+  const animationSettings = useViewerStore(s => s.animationSettings);
+
+  // rAF playback loop — ticks the simulated clock.
+  useEffect(() => {
+    if (!isPlaying || !animationEnabled) return;
+    let frame: number | null = null;
+    let last = performance.now();
+    const tick = (now: number) => {
+      const delta = now - last;
+      last = now;
+      advancePlaybackBy(delta);
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+    };
+  }, [isPlaying, animationEnabled, advancePlaybackBy]);
+
+  // Register / update the 'animation' overlay layer on every state change.
+  // The compositor hook picks this up and reconciles it into the renderer.
+  useEffect(() => {
+    const store = useViewerStore.getState();
+
+    // Animation off / no data → remove our layer (compositor will
+    // restore whatever we had hidden/coloured).
+    if (!animationEnabled || !scheduleData) {
+      store.removeOverlayLayer('animation');
+      return;
+    }
+
+    const models: ForwardModelMapLike = store.models;
+    const activeModelId = store.activeModelId;
+
+    // Enumerate the source model's LOCAL expressIds so the animator can
+    // hide coverage-gap products (those with no controlling task). We walk
+    // meshes rather than the full IFC entity table because only meshed
+    // products can visibly "show up" as the material default in the
+    // viewport — non-meshed entities don't render regardless.
+    //
+    // Runs only when the untasked-hide setting is on so we don't pay the
+    // mesh-iteration cost on every playback frame when the feature is off.
+    let allLocalIds: Set<number> | undefined;
+    if (animationSettings.hideUntaskedProducts) {
+      const fullModels = store.models;
+      const sourceModelId = resolveScheduleSourceModelId(fullModels, activeModelId);
+      const sourceModel = sourceModelId ? fullModels.get(sourceModelId) : undefined;
+      const meshes = sourceModel?.geometryResult?.meshes;
+      const idOffset = sourceModel?.idOffset ?? 0;
+      if (meshes && meshes.length > 0) {
+        allLocalIds = new Set<number>();
+        for (const mesh of meshes) {
+          allLocalIds.add(mesh.expressId - idOffset);
+        }
+      }
+    }
+
+    // Animator is a single source of truth — always emits hiddenIds (so
+    // `minimal` still removes demolished products and hides upcoming
+    // ones) and only emits colour overrides when style === 'phased'.
+    const frame = computeAnimationFrame(
+      scheduleData, playbackTime, animationSettings, activeWorkScheduleId || null,
+      allLocalIds,
+    );
+    const nextLocalHidden: Set<number> = frame.hiddenIds;
+    const nextLocalColors: Map<number, RGBA> = frame.colorOverrides;
+
+    const nextHidden = localIdsToGlobal(nextLocalHidden, models, activeModelId) as Set<number>;
+    const nextColors = localIdsToGlobal(nextLocalColors, models, activeModelId) as Map<number, RGBA>;
+
+    store.registerOverlayLayer({
+      id: 'animation',
+      priority: 100,
+      hiddenIds: nextHidden,
+      colorOverrides: nextColors.size > 0 ? nextColors : null,
+    });
+  }, [animationEnabled, playbackTime, scheduleData, activeWorkScheduleId, animationSettings]);
+
+  // Unmount cleanup — drop our layer. The compositor restores whatever
+  // we had contributed to the renderer.
+  useEffect(() => {
+    return () => {
+      useViewerStore.getState().removeOverlayLayer('animation');
+    };
+  }, []);
+}

package/src/components/viewer/schedule/useGanttBarDrag.test.ts

@@ -0,0 +1,90 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Unit tests for the pure math inside the bar-drag hook. Drag interaction
+ * itself is inherently manual-QA (pointer events + rAF), so the machinery
+ * that matters for correctness lives in these two pure helpers —
+ * `snapDeltaMs` and `pxPerMs`. Both are exercised on the round-trip
+ * pattern the hook uses at runtime: pixel delta → ms delta → snap.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type { ScheduleTimeRange } from '@/store';
+import { snapDeltaMs, pxPerMs } from './useGanttBarDrag';
+
+const DAY = 86_400_000;
+const HOUR = 3_600_000;
+
+describe('snapDeltaMs', () => {
+  it('snaps to the nearest unit', () => {
+    assert.strictEqual(snapDeltaMs(1.4 * HOUR, HOUR), 1 * HOUR);
+    assert.strictEqual(snapDeltaMs(1.6 * HOUR, HOUR), 2 * HOUR);
+  });
+
+  it('rounds half-way values up (Math.round semantics)', () => {
+    assert.strictEqual(snapDeltaMs(0.5 * HOUR, HOUR), 1 * HOUR);
+  });
+
+  it('handles negative deltas symmetrically', () => {
+    assert.strictEqual(snapDeltaMs(-0.4 * HOUR, HOUR), 0);
+    assert.strictEqual(snapDeltaMs(-1.6 * HOUR, HOUR), -2 * HOUR);
+  });
+
+  it('is a no-op when unit is 0 or negative (Shift-held path)', () => {
+    assert.strictEqual(snapDeltaMs(1234.5, 0), 1234.5);
+    assert.strictEqual(snapDeltaMs(1234.5, -10), 1234.5);
+  });
+
+  it('returns 0 for 0 delta regardless of unit', () => {
+    assert.strictEqual(snapDeltaMs(0, HOUR), 0);
+    assert.strictEqual(snapDeltaMs(0, 0), 0);
+  });
+});
+
+describe('pxPerMs', () => {
+  const thirtyDayRange: ScheduleTimeRange = {
+    start: 0,
+    end: 30 * DAY,
+    synthetic: false,
+  };
+
+  it('divides pixel width by time span', () => {
+    // 1500 px over 30 days → 50 px/day → 50 / 86_400_000 ms.
+    const ratio = pxPerMs(1500, thirtyDayRange);
+    assert.ok(Math.abs(ratio - 1500 / (30 * DAY)) < 1e-12);
+  });
+
+  it('returns 0 when the range is degenerate', () => {
+    assert.strictEqual(pxPerMs(1000, { start: 10, end: 10, synthetic: false }), 0);
+    assert.strictEqual(pxPerMs(1000, { start: 100, end: 0, synthetic: false }), 0);
+  });
+
+  it('returns 0 when pixel width is zero or negative', () => {
+    assert.strictEqual(pxPerMs(0, thirtyDayRange), 0);
+    assert.strictEqual(pxPerMs(-50, thirtyDayRange), 0);
+  });
+});
+
+describe('drag math — round-trip pattern the hook uses', () => {
+  // The hook does: rawDeltaMs = (clientX - startClientX) / pxPerMs(...)
+  // This guards the division: at sane widths + ranges, a 100-px drag
+  // yields a sensible ms delta which then snaps to a day-ish unit.
+  it('100 px drag over a 30-day schedule at 1500 px → ~2 days', () => {
+    const range: ScheduleTimeRange = { start: 0, end: 30 * DAY, synthetic: false };
+    const ratio = pxPerMs(1500, range);
+    const ms = 100 / ratio;
+    const snappedToDay = snapDeltaMs(ms, DAY);
+    // 100 / (1500 / (30*DAY)) = 2 days exactly.
+    assert.strictEqual(snappedToDay, 2 * DAY);
+  });
+
+  it('1 px drag over a 30-day schedule snaps to 0 with a day unit', () => {
+    const range: ScheduleTimeRange = { start: 0, end: 30 * DAY, synthetic: false };
+    const ratio = pxPerMs(1500, range);
+    const ms = 1 / ratio;
+    assert.strictEqual(snapDeltaMs(ms, DAY), 0);
+  });
+});