react-native-roster 0.0.0 → 0.1.0

package/src/core/columns.ts

@@ -0,0 +1,49 @@
+import type { DayColumn, Window } from './types';
+import {
+  dateEpoch,
+  dateString,
+  dayMilliseconds,
+  localDateAt,
+  startOfDate,
+  transitionsBetween,
+} from './zone';
+
+// Unbounded, like the date-start memo: zone data is stable for this runtime,
+// and retaining visited days avoids probing again on pointer and navigation revisits.
+const columns = new Map<string, DayColumn | null>();
+
+export function dayColumnsFor(window: Window, timezone: string): DayColumn[] {
+  const days: DayColumn[] = [];
+  if (window.start >= window.end) return days;
+  let localDate = localDateAt(window.start, timezone);
+  let start = startOfDate(localDate, timezone);
+  // After a rollback across midnight, the wall date can lag the column whose
+  // first instant has already passed. Walk until the next absolute date start.
+  while (start < window.end) {
+    const nextDate = dateString(dateEpoch(localDate) + dayMilliseconds);
+    const end = startOfDate(nextDate, timezone);
+    const key = JSON.stringify([localDate, timezone]);
+    let day = columns.get(key);
+    if (day === undefined) {
+      day =
+        start < end
+          ? {
+              start,
+              end,
+              localDate,
+              label: new Intl.DateTimeFormat('en-US', {
+                timeZone: timezone,
+                weekday: 'short',
+              }).format(start),
+              // Boundary transitions describe wall bands; absolute bounds stay exclusive.
+              transitions: transitionsBetween(start - 1, end + 1, timezone),
+            }
+          : null;
+      columns.set(key, day);
+    }
+    if (day && day.end > window.start) days.push(day);
+    localDate = nextDate;
+    start = end;
+  }
+  return days;
+}

package/src/core/coverage.ts

@@ -0,0 +1,56 @@
+import { counts, coverageCache } from './cache';
+import { laneKey } from './hash';
+import type { Coverage, Lane, LayerRole, Window } from './types';
+
+export function coverageFor(lane: Lane, window: Window): Coverage {
+  const key = laneKey(lane, window);
+  const cached = coverageCache.get(key);
+  if (cached) {
+    counts.coverage.cacheHits++;
+    return cached;
+  }
+  counts.coverage.runs++;
+  const available = union(lane, window, 'availability');
+  const booked = union(lane, window, 'booking');
+  let intersection = 0;
+  let a = 0;
+  let b = 0;
+  while (a < available.length && b < booked.length) {
+    const left = available[a] as Window;
+    const right = booked[b] as Window;
+    intersection += Math.max(0, Math.min(left.end, right.end) - Math.max(left.start, right.start));
+    if (left.end < right.end) a++;
+    else b++;
+  }
+  const availabilityMinutes = duration(available) / 60_000;
+  const result = {
+    availabilityMinutes,
+    bookingMinutes: duration(booked) / 60_000,
+    availabilityMinusBookingMinutes: availabilityMinutes - intersection / 60_000,
+  };
+  coverageCache.set(key, result);
+  return result;
+}
+
+function union(lane: Lane, window: Window, role: LayerRole): Window[] {
+  const spans = lane.layers
+    .filter((layer) => layer.role === role)
+    .flatMap((layer) => layer.intervals)
+    .map(({ start, end }) => ({
+      start: Math.max(start, window.start),
+      end: Math.min(end, window.end),
+    }))
+    .filter(({ start, end }) => start < end)
+    .sort((a, b) => a.start - b.start);
+  const result: Window[] = [];
+  for (const span of spans) {
+    const last = result.at(-1);
+    if (last && span.start <= last.end) last.end = Math.max(last.end, span.end);
+    else result.push(span);
+  }
+  return result;
+}
+
+function duration(spans: Window[]): number {
+  return spans.reduce((sum, span) => sum + span.end - span.start, 0);
+}

package/src/core/flag.ts

@@ -0,0 +1,14 @@
+import type { Lane, LaneFlag, Window } from './types';
+
+export function flagFor(lane: Lane, window: Window): LaneFlag {
+  if (lane.flag !== undefined) return lane.flag;
+  let hasIntervals = false;
+  for (const layer of lane.layers) {
+    for (const interval of layer.intervals) {
+      hasIntervals = true;
+      if (Math.max(interval.start, window.start) < Math.min(interval.end, window.end))
+        return 'none';
+    }
+  }
+  return hasIntervals ? 'empty-in-window' : 'none';
+}

package/src/core/hash.ts

@@ -0,0 +1,28 @@
+// Canonical structural keys retain the full encoding to avoid hash collisions.
+// Only layers participate without a version; lane display metadata never does.
+import type { Lane, Projection, Window } from './types';
+
+export function structuralKey(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(structuralKey).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, item]) => `${JSON.stringify(key)}:${structuralKey(item)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) as string;
+}
+
+export function laneKey(lane: Lane, window: Window): string {
+  return JSON.stringify([
+    lane.id,
+    lane.version === undefined ? ['layers', structuralKey(lane.layers)] : ['version', lane.version],
+    window.start,
+    window.end,
+  ]);
+}
+
+export function projectionKey(projection: Projection): string {
+  return structuralKey(projection);
+}

package/src/core/hit-test.ts

@@ -0,0 +1,27 @@
+import type { Lane, LaneGeometry, Rect } from './types';
+
+export function hitTest(
+  lane: Lane,
+  geometry: LaneGeometry,
+  x: number,
+  y: number,
+): { kind: 'interval' | 'gap'; rect: Rect } | undefined {
+  for (const kind of ['interval', 'gap'] as const) {
+    const rects = kind === 'interval' ? geometry.rects : geometry.gapRects;
+    let hit: Rect | undefined;
+    for (const rect of rects) {
+      if (x < rect.x || x >= rect.x + rect.width || y < rect.y || y >= rect.y + rect.height)
+        continue;
+      const previous = hit;
+      if (
+        !previous ||
+        rect.z > previous.z ||
+        (rect.z === previous.z &&
+          lane.layers.findIndex((layer) => layer.id === rect.layerId) >
+            lane.layers.findIndex((layer) => layer.id === previous.layerId))
+      )
+        hit = rect;
+    }
+    if (hit) return { kind, rect: hit };
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,34 @@
+export type { Span, WindowSpec } from './axis';
+export { next, prev, today, windowFor } from './axis';
+export {
+  clearCoverageCache,
+  clearLayoutCache,
+  coverageStats,
+  layoutStats,
+  resetStats,
+} from './cache';
+export { dayColumnsFor } from './columns';
+export { coverageFor } from './coverage';
+export { flagFor } from './flag';
+export { layoutLane } from './layout';
+export type { LaneComparator } from './order';
+export { byCoverage, byLabel } from './order';
+export { snapToStep, timeAtX, timeAtY } from './snap';
+export type {
+  Coverage,
+  DayColumn,
+  Gap,
+  Interval,
+  Lane,
+  LaneFlag,
+  LaneGeometry,
+  Layer,
+  LayerRole,
+  LayerStyle,
+  Projection,
+  Rect,
+  Source,
+  Transition,
+  Weekday,
+  Window,
+} from './types';

package/src/core/layout.ts

@@ -0,0 +1,101 @@
+import { counts, layoutCache } from './cache';
+import { coverageFor } from './coverage';
+import { flagFor } from './flag';
+import { laneKey, projectionKey } from './hash';
+import { type ScalePiece, scalePieces } from './scale';
+import { sourceSpans } from './spans';
+import type { Interval, Lane, LaneGeometry, Layer, Projection, Rect, Window } from './types';
+
+export function layoutLane(lane: Lane, window: Window, projection: Projection): LaneGeometry {
+  const key = `${laneKey(lane, window)}|${projectionKey(projection)}`;
+  let cached = layoutCache.get(key);
+  const coverage = coverageFor(lane, window);
+  const flag = flagFor(lane, window);
+  if (cached) {
+    counts.layout.cacheHits++;
+  } else {
+    counts.layout.runs++;
+    const pieces =
+      projection.orientation === 'columns'
+        ? projection.days.map((day) => scalePieces(day, projection.viewTimezone))
+        : [];
+    const rects: Rect[] = [];
+    const gapRects: Rect[] = [];
+    for (const layer of lane.layers) {
+      project(sourceSpans(layer.intervals, window), layer, window, projection, pieces, rects);
+      project(sourceSpans(layer.gaps ?? [], window), layer, window, projection, pieces, gapRects);
+    }
+    cached = { rects, gapRects, assemblies: new WeakMap() };
+    layoutCache.set(key, cached);
+  }
+  // Read the current flag and coverage above, then retain each complete assembly
+  // by reference, including when a consumer revisits an earlier explicit flag.
+  let assemblies = cached.assemblies.get(coverage);
+  if (!assemblies) {
+    assemblies = new Map();
+    cached.assemblies.set(coverage, assemblies);
+  }
+  const previous = assemblies.get(flag);
+  if (previous) return previous;
+  const result = {
+    laneId: lane.id,
+    rects: cached.rects,
+    gapRects: cached.gapRects,
+    coverage,
+    flag,
+  };
+  assemblies.set(flag, result);
+  return result;
+}
+
+function project(
+  spans: Interval[],
+  layer: Layer,
+  window: Window,
+  projection: Projection,
+  columns: ScalePiece[][],
+  rects: Rect[],
+): void {
+  const inset = layer.style.inset ?? 0;
+  if (projection.orientation === 'horizontal') {
+    for (const span of spans) {
+      rects.push({
+        x: ((span.start - window.start) / 60_000) * projection.pxPerMinute,
+        y: inset,
+        width: ((span.end - span.start) / 60_000) * projection.pxPerMinute,
+        height: Math.max(0, projection.rowHeight - 2 * inset),
+        layerId: layer.id,
+        z: layer.z,
+        sources: span.sources,
+      });
+    }
+    return;
+  }
+  // Both lists are ordered in absolute time; advance once through the columns.
+  let firstSpan = 0;
+  for (const [column, pieces] of columns.entries()) {
+    for (const piece of pieces) {
+      while (firstSpan < spans.length && (spans[firstSpan] as Interval).end <= piece.start)
+        firstSpan++;
+      for (let i = firstSpan; i < spans.length; i++) {
+        const span = spans[i] as Interval;
+        if (span.start >= piece.end) break;
+        const start = Math.max(span.start, piece.start);
+        const end = Math.min(span.end, piece.end);
+        rects.push({
+          x: inset,
+          y:
+            ((piece.minute + ((start - piece.start) / 60_000) * piece.scale) *
+              projection.pxPerHour) /
+            60,
+          width: Math.max(0, projection.columnWidth - 2 * inset),
+          height: (((end - start) / 60_000) * piece.scale * projection.pxPerHour) / 60,
+          layerId: layer.id,
+          z: layer.z,
+          sources: span.sources,
+          column,
+        });
+      }
+    }
+  }
+}

package/src/core/order.ts

@@ -0,0 +1,18 @@
+import type { Coverage, Lane } from './types';
+
+export type LaneComparator = (a: Lane, b: Lane, coverage: ReadonlyMap<string, Coverage>) => number;
+
+export function byLabel(a: Lane, b: Lane): number {
+  return a.label.localeCompare(b.label);
+}
+
+export function byCoverage({
+  measure,
+}: {
+  measure: 'availability' | 'availabilityMinusBooking';
+}): LaneComparator {
+  const field =
+    measure === 'availability' ? 'availabilityMinutes' : 'availabilityMinusBookingMinutes';
+  return (a, b, coverage) =>
+    (coverage.get(b.id)?.[field] ?? 0) - (coverage.get(a.id)?.[field] ?? 0) || byLabel(a, b);
+}

package/src/core/scale.ts

@@ -0,0 +1,45 @@
+// A rect must never cross a scale boundary. Repeats have three boundaries:
+// T - |delta|, T, and T + |delta|. Pieces serve layout and pointer inversion
+// together so that both halves select the same absolute occurrence.
+import type { DayColumn } from './types';
+import { dateEpoch, wallTime } from './zone';
+
+export type ScalePiece = { start: number; end: number; minute: number; scale: number };
+
+export function scalePieces(day: DayColumn, timezone: string): ScalePiece[] {
+  const boundaries = new Set([day.start, day.end]);
+  const addBoundary = (time: number) =>
+    boundaries.add(Math.max(day.start, Math.min(day.end, time)));
+  for (const { at, deltaMinutes } of day.transitions) {
+    addBoundary(at);
+    if (deltaMinutes < 0) {
+      const delta = -deltaMinutes * 60_000;
+      addBoundary(at - delta);
+      addBoundary(at + delta);
+    }
+  }
+  const ordered = [...boundaries].sort((a, b) => a - b);
+  const pieces: ScalePiece[] = [];
+  const midnight = dateEpoch(day.localDate);
+  for (let i = 0; i < ordered.length - 1; i++) {
+    const start = ordered[i] as number;
+    const end = ordered[i + 1] as number;
+    let minute = (wallTime(start, timezone) - midnight) / 60_000;
+    let scale = 1;
+    for (const { at, deltaMinutes } of day.transitions) {
+      const delta = -deltaMinutes * 60_000;
+      if (delta > 0 && start >= at - delta && start < at + delta) {
+        const repeatedStart = (wallTime(at, timezone) - midnight) / 60_000;
+        // Clamp a repeat crossing midnight to the top edge. Compress its
+        // surviving absolute span into the remaining wall-clock region so
+        // layout and inversion agree where ordinary wall time resumes.
+        const clipped = Math.max(0, -repeatedStart);
+        const repeatStart = at - delta + clipped * 60_000;
+        scale = (deltaMinutes + clipped) / (2 * deltaMinutes + clipped);
+        minute = repeatedStart + clipped + ((start - repeatStart) / 60_000) * scale;
+      }
+    }
+    pieces.push({ start, end, minute, scale });
+  }
+  return pieces;
+}

package/src/core/snap.ts

@@ -0,0 +1,52 @@
+import { dayColumnsFor } from './columns';
+import { scalePieces } from './scale';
+import type { Projection, Window } from './types';
+import { wallTime } from './zone';
+
+export function snapToStep(time: number, minuteStep: number, timezone: string): number {
+  if (!Number.isInteger(minuteStep) || minuteStep <= 0 || 60 % minuteStep !== 0) {
+    throw new RangeError('minuteStep must be a positive divisor of 60');
+  }
+  const step = minuteStep * 60_000;
+  const wall = wallTime(time, timezone);
+  let result = time - (wall - Math.floor(wall / step) * step);
+  const days = dayColumnsFor({ start: time, end: time + 1 }, timezone);
+  for (const day of days) {
+    for (const { at } of day.transitions) {
+      if (at <= time) result = Math.max(result, at);
+    }
+  }
+  return result;
+}
+
+export function timeAtY(
+  projection: Extract<Projection, { orientation: 'columns' }>,
+  columnIndex: number,
+  y: number,
+): number | null {
+  const day = projection.days[columnIndex];
+  if (!day || y < 0 || y >= 24 * projection.pxPerHour) return null;
+  const minute = (y * 60) / projection.pxPerHour;
+  for (const piece of scalePieces(day, projection.viewTimezone)) {
+    if (
+      minute >= piece.minute &&
+      minute < piece.minute + ((piece.end - piece.start) / 60_000) * piece.scale
+    ) {
+      // Epoch addition can round an interior pointer to the exclusive boundary.
+      return Math.min(
+        piece.end - 1,
+        piece.start + ((minute - piece.minute) * 60_000) / piece.scale,
+      );
+    }
+  }
+  return null;
+}
+
+/** Absolute time at true elapsed length; the window supplies the projection's origin. */
+export function timeAtX(
+  projection: Extract<Projection, { orientation: 'horizontal' }>,
+  window: Window,
+  x: number,
+): number {
+  return window.start + (x * 60_000) / projection.pxPerMinute;
+}

package/src/core/spans.ts

@@ -0,0 +1,58 @@
+// Sweep boundaries once; reference counts preserve provenance through nested
+// intervals and equal-time ends/starts. Labels never affect source identity.
+import type { Interval, Source, Window } from './types';
+
+type Boundary = { at: number; delta: number; sources: Source[] };
+
+export function sourceSpans(intervals: Interval[], window: Window): Interval[] {
+  const boundaries: Boundary[] = [];
+  for (const interval of intervals) {
+    const start = Math.max(interval.start, window.start);
+    const end = Math.min(interval.end, window.end);
+    if (start >= end) continue;
+    boundaries.push({ at: start, delta: 1, sources: interval.sources });
+    boundaries.push({ at: end, delta: -1, sources: interval.sources });
+  }
+  boundaries.sort((a, b) => a.at - b.at);
+  const active = new Map<string, { count: number; source: Source }>();
+  const spans: Interval[] = [];
+  let depth = 0;
+  let previous = window.start;
+  let lastKeys = new Set<string>();
+  let sourceDifference = 0;
+  for (let i = 0; i < boundaries.length; ) {
+    const at = (boundaries[i] as Boundary).at;
+    if (depth > 0 && previous < at) {
+      const last = spans.at(-1);
+      if (last && last.end === previous && sourceDifference === 0) {
+        last.end = at;
+      } else {
+        spans.push({
+          start: previous,
+          end: at,
+          sources: [...active.values()].map((item) => item.source),
+        });
+        lastKeys = new Set(active.keys());
+        sourceDifference = 0;
+      }
+    }
+    while (i < boundaries.length && (boundaries[i] as Boundary).at === at) {
+      const boundary = boundaries[i++] as Boundary;
+      depth += boundary.delta;
+      for (const source of boundary.sources) {
+        const key = JSON.stringify([source.kind, source.id]);
+        const item = active.get(key);
+        const count = (item?.count ?? 0) + boundary.delta;
+        // Track set differences incrementally so redundant overlap boundaries
+        // do not copy or compare the full source set on an unchanged span.
+        if ((count === 0) !== (item === undefined)) {
+          sourceDifference += lastKeys.has(key) ? -boundary.delta : boundary.delta;
+        }
+        if (count === 0) active.delete(key);
+        else active.set(key, { count, source: item?.source ?? source });
+      }
+    }
+    previous = at;
+  }
+  return spans;
+}

package/src/core/types.ts

@@ -0,0 +1,92 @@
+/** Identity is (kind, id). `label` is display metadata and never participates in equality, merging, or highlighting. */
+export type Source = { kind: string; id: string; label?: string };
+
+/** Covered time. `sources` lists the contributors that cover this exact span (for the rrule adapter: the includes). */
+export type Interval = { start: number; end: number; sources: Source[] }; // epoch ms, end-exclusive
+
+/** Removed time. `sources` lists what removed it (for the rrule adapter: the excludes). Survives complete subtraction. */
+export type Gap = { start: number; end: number; sources: Source[] };
+
+export type LayerRole = 'availability' | 'booking' | 'custom';
+/** `inset` is a cross-axis distance in px (vertical in the horizontal projection, horizontal in columns), applied by the engine. */
+export type LayerStyle = {
+  color: string;
+  highlightColor?: string;
+  inset?: number;
+  opacity?: number;
+};
+export type Layer = {
+  id: string;
+  role: LayerRole;
+  z: number;
+  style: LayerStyle;
+  intervals: Interval[];
+  gaps?: Gap[];
+  label?: string;
+};
+
+export type LaneFlag = 'none' | 'never-set' | 'empty-in-window';
+export type Lane = {
+  id: string;
+  /** Bumped by the consumer when layer content changes; the engine hashes layer content when absent. */
+  version?: string | number;
+  label: string;
+  timezone?: string;
+  flag?: LaneFlag;
+  /** False when the lane's intervals are known to be incomplete (an adapter cap bit, #4). Default true. The hooks (#5, #11) show the incomplete label (#8) when false; the engine never infers it. */
+  complete?: boolean;
+  layers: Layer[];
+  meta?: unknown;
+};
+
+/** A span of absolute time. No span kind, no resolution; those are axis and component concerns (#6). */
+export type Window = { start: number; end: number };
+
+/** RFC 5545 weekday numbering: 0 = Monday through 6 = Sunday. Used by `wkst`, `byweekday`, and `windowFor`. */
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/** A UTC-offset change inside a column, from `dayColumnsFor` (#6). Any size, any count. */
+export type Transition = { at: number; deltaMinutes: number }; // positive = clocks moved forward (time skipped)
+
+/** One day column in the view zone. Always projected as 24 equal wall-clock hour bands. `localDate` is the column's calendar date in the view zone ('YYYY-MM-DD'); a local date with no instants (`Pacific/Apia`, 2011-12-30) produces no column at all (#6). */
+export type DayColumn = {
+  start: number;
+  end: number;
+  localDate: string;
+  label: string;
+  transitions: Transition[];
+};
+
+export type Projection =
+  | { orientation: 'horizontal'; viewTimezone: string; pxPerMinute: number; rowHeight: number }
+  | {
+      orientation: 'columns';
+      viewTimezone: string;
+      pxPerHour: number;
+      columnWidth: number;
+      days: DayColumn[];
+    };
+
+/** Final visible bounds, inset already applied; also the hit-test bounds (#8). */
+export type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  layerId: string;
+  z: number;
+  sources: Source[];
+  column?: number;
+};
+export type Coverage = {
+  availabilityMinutes: number;
+  bookingMinutes: number;
+  availabilityMinusBookingMinutes: number;
+};
+export type LaneGeometry = {
+  laneId: string;
+  rects: Rect[];
+  gapRects: Rect[];
+  coverage: Coverage;
+  flag: LaneFlag;
+};

package/src/core/zone.ts

@@ -0,0 +1,100 @@
+// Intl supplies offsets; UTC Date arithmetic supplies local-date arithmetic.
+// Hourly probes bracket IANA transitions, then binary search keeps exact epoch
+// boundaries, including historical second offsets. No host-local Date methods.
+import type { Transition } from './types';
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+const starts = new Map<string, number>();
+const minute = 60_000;
+export const dayMilliseconds = 86_400_000;
+
+export function wallTime(time: number, timezone: string): number {
+  let formatter = formatters.get(timezone);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat('en-US-u-ca-gregory-nu-latn', {
+      timeZone: timezone,
+      era: 'short',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hourCycle: 'h23',
+    });
+    formatters.set(timezone, formatter);
+  }
+  const parts: Record<string, string> = {};
+  for (const part of formatter.formatToParts(time)) parts[part.type] = part.value;
+  const date = new Date(0);
+  const year = parts.era === 'BC' ? 1 - Number(parts.year) : Number(parts.year);
+  date.setUTCFullYear(year, Number(parts.month) - 1, Number(parts.day));
+  date.setUTCHours(Number(parts.hour) % 24, Number(parts.minute), Number(parts.second), 0);
+  return date.getTime() + (((time % 1000) + 1000) % 1000);
+}
+
+export function offsetAt(time: number, timezone: string): number {
+  return wallTime(time, timezone) - time;
+}
+
+export function localDateAt(time: number, timezone: string): string {
+  return dateString(wallTime(time, timezone));
+}
+
+export function dateString(time: number): string {
+  return new Date(time).toISOString().slice(0, 10);
+}
+
+export function dateEpoch(localDate: string): number {
+  const time = Date.parse(`${localDate}T00:00:00.000Z`);
+  if (
+    !/^\d{4}-\d{2}-\d{2}$/.test(localDate) ||
+    !Number.isFinite(time) ||
+    dateString(time) !== localDate
+  ) {
+    throw new RangeError('Expected a valid YYYY-MM-DD local date');
+  }
+  return time;
+}
+
+export function transitionsBetween(start: number, end: number, timezone: string): Transition[] {
+  const transitions: Transition[] = [];
+  let cursor = start;
+  let offset = offsetAt(cursor, timezone);
+  while (cursor < end) {
+    const probe = Math.min(cursor + 60 * minute, end);
+    const nextOffset = offsetAt(probe, timezone);
+    if (nextOffset !== offset) {
+      let low = cursor;
+      let high = probe;
+      while (high - low > 1) {
+        const middle = Math.floor((low + high) / 2);
+        if (offsetAt(middle, timezone) === offset) low = middle;
+        else high = middle;
+      }
+      if (high < end) transitions.push({ at: high, deltaMinutes: (nextOffset - offset) / minute });
+    }
+    cursor = probe;
+    offset = nextOffset;
+  }
+  return transitions;
+}
+
+export function startOfDate(localDate: string, timezone: string): number {
+  const key = JSON.stringify([localDate, timezone]);
+  const cached = starts.get(key);
+  if (cached !== undefined) return cached;
+  const target = dateEpoch(localDate);
+  const start = target - 2 * dayMilliseconds;
+  const end = target + 2 * dayMilliseconds;
+  const boundaries = [start, ...transitionsBetween(start, end, timezone).map(({ at }) => at), end];
+  let result = Infinity;
+  for (let i = 0; i < boundaries.length - 1; i++) {
+    const left = boundaries[i] as number;
+    const right = boundaries[i + 1] as number;
+    const candidate = Math.max(left, target - offsetAt(left, timezone));
+    if (candidate < right) result = Math.min(result, candidate);
+  }
+  starts.set(key, result);
+  return result;
+}