react-native-roster 0.1.0 → 0.3.0

package/src/components/roster/lanes/lane.tsx

@@ -1,6 +1,7 @@
 import { Fragment } from 'react';
 import { Pressable } from 'react-native';
 import type { Lane, LaneGeometry } from '../../../core';
+import { hasSource } from '../../../core';
 import { pressPoint } from '../../primitives/press-point';
 import type { BodyInput } from '../roster.types';
 import { intervalHoverProps } from './interval-hover';
@@ -56,10 +57,7 @@ export function LaneRow({
                   rect={rect}
                   layer={layer}
                   lane={lane}
-                  highlighted={rect.sources.some(
-                    (source) =>
-                      source.kind === highlightSource?.kind && source.id === highlightSource.id,
-                  )}
+                  highlighted={hasSource(rect.sources, highlightSource)}
                 />
               </Fragment>
             ))}

package/src/components/roster/parts/lane-list.tsx

@@ -1,5 +1,5 @@
 import { LegendList } from '@legendapp/list';
-import { Profiler, type ProfilerOnRenderCallback } from 'react';
+import { Profiler, type ProfilerOnRenderCallback, useState } from 'react';
 import { LaneRow } from '../lanes/lane';
 import type { BodyInput } from '../roster.types';
 import { bodyContentKey } from '../utils/body-content-key';
@@ -23,9 +23,11 @@ export function RosterLaneList({
   /** Development-only Profiler hook used by the gallery; not a supported customization point. */
   onRowRender?: ProfilerOnRenderCallback;
 }) {
+  const [initialScrollOffset] = useState(() => scroll.y.get());
   return (
     <LegendList
       testID="roster-vertical-scroll"
+      initialScrollOffset={initialScrollOffset}
       data={lanes}
       extraData={bodyContentKey({
         window,

package/src/components/roster/roster.types.ts

@@ -21,6 +21,14 @@ import type {
   WindowSpec,
 } from '../../core';
 import type { GapInput, IntervalInput } from '../layers/layers.types';
+import type { SelectionLayoutProps } from './selection/selection-layout.types';
+
+/** A selected interval: the rect input plus its absolute bounds and the view zone for formatting. */
+export type IntervalDetailInput = IntervalInput & {
+  start: number;
+  end: number;
+  viewTimezone: string;
+};
 
 export type RosterProjection = Extract<Projection, { orientation: 'horizontal' }>;
 export type RosterTick = { time: number; x: number; label: string; kind: 'day' | 'time' };
@@ -35,6 +43,8 @@ export type RosterScroll = {
   labelStyle: StyleProp<ViewStyle>;
 };
 export type RosterInput = {
+  /** Retain interval selection on press, default false. Lives on RosterInput for hook consumers. */
+  selectable?: boolean;
   lanes: Lane[];
   windowSpec: WindowSpec;
   minuteStep?: number;
@@ -52,6 +62,10 @@ export type RosterInput = {
   pxPerMinute?: number;
 };
 export type RosterModel = {
+  /** Current interval with fresh lane, layer, and rect references and its absolute bounds, or null. */
+  selection: Omit<IntervalDetailInput, 'highlighted' | 'viewTimezone'> | null;
+  /** Close the selected interval details. */
+  dismissSelection: () => void;
   window: Window;
   projection: RosterProjection;
   orderedLanes: Lane[];
@@ -129,8 +143,23 @@ export type RosterStyleProps = {
   /** Width of the corner and lane label column, default 180. */
   laneLabelWidth?: number;
 };
-export type RosterProps = RosterInput &
+export type RosterProps = Omit<RosterInput, 'selectable'> &
   RosterStyleProps & {
+    /**
+     * Selected interval content; absent means interval presses retain no selection.
+     * Lives on RosterProps because the chassis mounts content and enables useRoster selection.
+     */
+    intervalDetailComponent?: ComponentType<IntervalDetailInput>;
+    /**
+     * Presentation strategy for the body and selected details; defaults to RosterSelectionPopover.
+     * Lives on RosterProps because only the chassis mounts the layout, not useRoster.
+     */
+    selectionLayout?: ComponentType<SelectionLayoutProps>;
+    /**
+     * Native portal host name; defaults to a unique useId name for this roster.
+     * Lives on RosterProps because only the chassis mounts the layout, not useRoster.
+     */
+    portalHost?: string;
     incompleteLabel?: string;
     neverSetLabel?: string;
     /** Label, differing lane zone, effective flag, and completeness notice. */

package/src/components/roster/selection/selection-layout.tsx

@@ -0,0 +1,90 @@
+import { type ReactNode, useEffect, useId, useState } from 'react';
+import { BackHandler, ScrollView, View } from 'react-native';
+import Animated, { useAnimatedStyle } from 'react-native-reanimated';
+import { Portal, PortalHost } from '../../primitives/portal';
+import type { SelectionLayoutProps } from './selection-layout.types';
+
+const overlay = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 } as const;
+
+/** Native selection presentation with a local portal destination and shared scroll translation. */
+export function RosterSelectionPopover({
+  anchorZone,
+  contentZone,
+  targetBounds,
+  open,
+  onDismiss,
+  portalHost,
+  scroll,
+}: SelectionLayoutProps) {
+  const name = useId();
+  const [viewport, setViewport] = useState({ width: 0, height: 0 });
+  const [content, setContent] = useState({ width: 0, height: 0 });
+  const maxWidth = Math.max(0, viewport.width - 8);
+  const maxHeight = Math.max(0, viewport.height - 8);
+  const size = { maxWidth, maxHeight, flexShrink: 1 };
+  const { x, y } = scroll;
+  const position = useAnimatedStyle(() => {
+    const below = targetBounds ? targetBounds.y + targetBounds.height + 4 - y.get() : 0;
+    const above = targetBounds ? targetBounds.y - content.height - 4 - y.get() : 0;
+    const maxTop = Math.max(0, viewport.height - content.height);
+    return {
+      left: Math.max(0, Math.min((targetBounds?.x ?? 0) - x.get(), viewport.width - content.width)),
+      top: below >= 0 && below <= maxTop ? below : above >= 0 && above <= maxTop ? above : 0,
+    };
+  });
+  useEffect(() => {
+    if (!open) return;
+    const subscription = BackHandler.addEventListener('hardwareBackPress', () => {
+      onDismiss();
+      return true;
+    });
+    return () => subscription.remove();
+  }, [open, onDismiss]);
+  let detailZone: ReactNode = null;
+  if (open && targetBounds && maxWidth > 0 && maxHeight > 0) {
+    detailZone = (
+      <Portal hostName={portalHost} name={name}>
+        <Animated.View style={[{ position: 'absolute', maxWidth, maxHeight }, position]}>
+          <View
+            accessibilityRole="summary"
+            onStartShouldSetResponder={() => true}
+            style={size}
+            onLayout={({ nativeEvent }) =>
+              setContent({
+                width: nativeEvent.layout.width,
+                height: nativeEvent.layout.height,
+              })
+            }
+          >
+            <ScrollView style={size} nestedScrollEnabled>
+              <ScrollView
+                horizontal
+                style={{ maxWidth, flexGrow: 0, flexShrink: 0 }}
+                nestedScrollEnabled
+              >
+                {contentZone}
+              </ScrollView>
+            </ScrollView>
+          </View>
+        </Animated.View>
+      </Portal>
+    );
+  }
+  return (
+    <View
+      style={{ flex: 1, minHeight: 0 }}
+      onLayout={({ nativeEvent }) =>
+        setViewport({
+          width: nativeEvent.layout.width,
+          height: nativeEvent.layout.height,
+        })
+      }
+    >
+      {anchorZone}
+      <View pointerEvents="box-none" style={overlay}>
+        <PortalHost name={portalHost} />
+      </View>
+      {detailZone}
+    </View>
+  );
+}

package/src/components/roster/selection/selection-layout.types.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { RosterScroll } from '../roster.types';
+
+/** Presentation-only contract shared by native, web, and consumer strategies. */
+export type SelectionLayoutProps = {
+  /** Mounted body node, rendered once beneath or beside the details. */
+  anchorZone: ReactNode;
+  /** Mounted detail node, or null when closed. */
+  contentZone: ReactNode;
+  /** Interval bounds in body-content coordinates, before scroll translation. */
+  targetBounds: { x: number; y: number; width: number; height: number } | null;
+  /** Whether the detail presentation is open. */
+  open: boolean;
+  /** Report outside press, hardware back, Escape, or a presentation close action. */
+  onDismiss: () => void;
+  /** Unique native destination name owned by this selection layout. */
+  portalHost: string;
+  /** Shared offsets follow body scrolling without updating React state. */
+  scroll: Pick<RosterScroll, 'x' | 'y' | 'headerStyle' | 'labelStyle'>;
+};

package/src/components/roster/selection/selection-layout.web.tsx

@@ -0,0 +1,88 @@
+import { Anchor, Content, Portal, Root } from '@radix-ui/react-popover';
+import { useEffect, useRef } from 'react';
+import Animated from 'react-native-reanimated';
+import type { SelectionLayoutProps } from './selection-layout.types';
+
+/** Web selection presentation; Radix owns outside press, Escape, and collisions. */
+export function RosterSelectionPopover({
+  anchorZone,
+  contentZone,
+  targetBounds,
+  open,
+  onDismiss,
+  scroll,
+}: SelectionLayoutProps) {
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const returnFocusRef = useRef<Element | null>(null);
+  const keyboardDismissRef = useRef(false);
+  useEffect(() => {
+    if (open && targetBounds && bodyRef.current?.contains(document.activeElement)) {
+      returnFocusRef.current = document.activeElement;
+    }
+  }, [open, targetBounds]);
+  return (
+    <Root
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) onDismiss();
+      }}
+    >
+      <div
+        ref={bodyRef}
+        style={{
+          position: 'relative',
+          display: 'flex',
+          flexDirection: 'column',
+          flex: 1,
+          minHeight: 0,
+        }}
+      >
+        {anchorZone}
+        <Animated.View style={[{ position: 'absolute', top: 0, left: 0 }, scroll.headerStyle]}>
+          <Animated.View style={scroll.labelStyle}>
+            <Anchor asChild>
+              <div
+                data-testid="roster-selection-target"
+                style={{
+                  position: 'absolute',
+                  left: targetBounds?.x ?? 0,
+                  top: targetBounds ? targetBounds.y + targetBounds.height : 0,
+                  width: 0,
+                  height: 0,
+                  pointerEvents: 'none',
+                }}
+              />
+            </Anchor>
+          </Animated.View>
+        </Animated.View>
+      </div>
+      <Portal>
+        <Content
+          onOpenAutoFocus={() => {
+            returnFocusRef.current = document.activeElement;
+            keyboardDismissRef.current = false;
+          }}
+          onEscapeKeyDown={() => {
+            keyboardDismissRef.current = true;
+          }}
+          onCloseAutoFocus={(event) => {
+            event.preventDefault();
+            if (keyboardDismissRef.current && returnFocusRef.current instanceof HTMLElement) {
+              returnFocusRef.current.focus({ preventScroll: true });
+            }
+          }}
+          onInteractOutside={(event) => {
+            if (bodyRef.current?.contains(event.target as Node)) event.preventDefault();
+          }}
+          sideOffset={4}
+          align="start"
+          updatePositionStrategy="always"
+          aria-label="Interval details"
+          style={{ zIndex: 1000 }}
+        >
+          {contentZone}
+        </Content>
+      </Portal>
+    </Root>
+  );
+}

package/src/components/roster/use-roster-press.ts

@@ -0,0 +1,74 @@
+import type { Dispatch, SetStateAction } from 'react';
+import { useRef, useState } from 'react';
+import type { Lane, Window } from '../../core';
+import { layoutLane, snapToStep, timeAtX } from '../../core';
+import { hitTest } from '../../core/hit-test';
+import type { RosterInput, RosterModel, RosterProjection } from './roster.types';
+
+export type SelectedInterval = NonNullable<RosterModel['selection']>;
+
+// Isolate the stable press ref so it does not prevent compilation of derived roster values.
+export function useRosterPress(
+  input: RosterInput,
+  window: Window,
+  projection: RosterProjection,
+  width: number,
+  selection: RosterModel['selection'],
+  setSelected: Dispatch<SetStateAction<SelectedInterval | null>>,
+) {
+  const currentPress = { input, window, projection, width, selection };
+  const pressInput = useRef(currentPress);
+  pressInput.current = currentPress;
+  const [press] = useState(() => {
+    return function press(lane: Lane, pointX: number, pointY: number): void {
+      const { input, window, projection, width, selection } = pressInput.current;
+      const { minuteStep = 60, onIntervalPress, onGapPress, onCellPress } = input;
+      const { rowHeight, viewTimezone } = projection;
+      if (
+        !Number.isFinite(pointX) ||
+        !Number.isFinite(pointY) ||
+        pointX < 0 ||
+        pointX >= width ||
+        pointY < 0 ||
+        pointY >= rowHeight
+      )
+        return;
+      const hit = hitTest(lane, layoutLane(lane, window, projection), pointX, pointY);
+      if (hit?.kind === 'interval') {
+        if (input.selectable) {
+          const layer = lane.layers.find((layer) => layer.id === hit.rect.layerId);
+          // layoutLane supplied the hit rect's layerId, so this should succeed; guard future refactors.
+          if (layer === undefined) return;
+          // Compare reconciled geometry so resizing and cache eviction preserve toggle identity.
+          setSelected(
+            selection?.lane.id === lane.id &&
+              selection.rect.layerId === hit.rect.layerId &&
+              selection.rect.x === hit.rect.x &&
+              selection.rect.width === hit.rect.width
+              ? null
+              : {
+                  rect: hit.rect,
+                  layer,
+                  lane,
+                  start: timeAtX(projection, window, hit.rect.x),
+                  end: timeAtX(projection, window, hit.rect.x + hit.rect.width),
+                },
+          );
+        }
+        onIntervalPress?.(hit.rect, lane);
+        return;
+      }
+      if (selection) setSelected(null);
+      if (hit?.kind === 'gap') {
+        onGapPress?.(hit.rect, lane);
+        return;
+      }
+      const time = Math.max(
+        window.start,
+        snapToStep(timeAtX(projection, window, pointX), minuteStep, viewTimezone),
+      );
+      if (time < window.end) onCellPress?.(lane, time);
+    };
+  });
+  return press;
+}

package/src/components/roster/use-roster.ts

@@ -1,18 +1,10 @@
 import { useRef, useState } from 'react';
 import type { ScrollView } from 'react-native';
 import { makeMutable, useAnimatedStyle } from 'react-native-reanimated';
-import type { Lane, LaneGeometry } from '../../core';
-import {
-  byLabel,
-  coverageFor,
-  flagFor,
-  layoutLane,
-  snapToStep,
-  timeAtX,
-  windowFor,
-} from '../../core';
-import { hitTest } from '../../core/hit-test';
+import type { Lane, LaneGeometry, Rect, Window } from '../../core';
+import { byLabel, coverageFor, flagFor, layoutLane, timeAtX, windowFor } from '../../core';
 import type { RosterInput, RosterModel, RosterProjection } from './roster.types';
+import { type SelectedInterval, useRosterPress } from './use-roster-press';
 import { ticksFor } from './utils/ticks';
 
 export function useRoster(input: RosterInput): RosterModel {
@@ -25,6 +17,10 @@ export function useRoster(input: RosterInput): RosterModel {
     pxPerMinute = 0.5,
     onNavigate,
   } = input;
+  const [selected, setSelected] = useState<SelectedInterval | null>(null);
+  function dismissSelection() {
+    setSelected(null);
+  }
   const [viewport, setViewport] = useState({ width: 0, height: 0 });
   // The pinned compiler lint cannot resolve useSharedValue's built-in type.
   // These shared values only track offsets, so no animation needs cancellation.
@@ -60,40 +56,19 @@ export function useRoster(input: RosterInput): RosterModel {
   function geometryFor(lane: Lane): LaneGeometry {
     return layoutLane(lane, window, projection);
   }
-  const currentPress = { input, window, projection, width: contentWidth };
-  const pressInput = useRef(currentPress);
-  pressInput.current = currentPress;
-  const [press] = useState(() => {
-    return function press(lane: Lane, pointX: number, pointY: number): void {
-      const { input, window, projection, width } = pressInput.current;
-      const { minuteStep = 60, onIntervalPress, onGapPress, onCellPress } = input;
-      const { rowHeight, viewTimezone } = projection;
-      if (
-        !Number.isFinite(pointX) ||
-        !Number.isFinite(pointY) ||
-        pointX < 0 ||
-        pointX >= width ||
-        pointY < 0 ||
-        pointY >= rowHeight
-      )
-        return;
-      const hit = hitTest(lane, layoutLane(lane, window, projection), pointX, pointY);
-      if (hit?.kind === 'interval') {
-        onIntervalPress?.(hit.rect, lane);
-        return;
-      }
-      if (hit?.kind === 'gap') {
-        onGapPress?.(hit.rect, lane);
-        return;
-      }
-      const time = Math.max(
-        window.start,
-        snapToStep(timeAtX(projection, window, pointX), minuteStep, viewTimezone),
-      );
-      if (time < window.end) onCellPress?.(lane, time);
-    };
-  });
+  const selection = reconcileSelection(
+    selected,
+    lanes,
+    window,
+    projection,
+    input.selectable ?? false,
+  );
+  // Discard invalid selection during reconciliation, before rendering any stale detail.
+  if (selected && !selection) setSelected(null);
+  const press = useRosterPress(input, window, projection, contentWidth, selection, setSelected);
   return {
+    selection,
+    dismissSelection,
     window,
     projection,
     orderedLanes,
@@ -131,3 +106,41 @@ export function useRoster(input: RosterInput): RosterModel {
     },
   };
 }
+
+// Match provenance and nearest bounds while preserving the stored display values.
+function reconcileSelection(
+  selected: SelectedInterval | null,
+  lanes: Lane[],
+  window: Window,
+  projection: RosterProjection,
+  enabled: boolean,
+): RosterModel['selection'] {
+  if (selected && enabled) {
+    const lane = lanes.find((lane) => lane.id === selected.lane.id);
+    const layer = lane?.layers.find((layer) => layer.id === selected.layer.id);
+    if (lane && layer) {
+      const sources = new Set(
+        selected.rect.sources.map((source) => JSON.stringify([source.kind, source.id])),
+      );
+      let rect: Rect | undefined;
+      let nearest = 1;
+      for (const candidate of layoutLane(lane, window, projection).rects) {
+        if (candidate.layerId !== layer.id) continue;
+        const identities = new Set(
+          candidate.sources.map((source) => JSON.stringify([source.kind, source.id])),
+        );
+        if (identities.size !== sources.size || ![...identities].every((id) => sources.has(id)))
+          continue;
+        const difference =
+          Math.abs(timeAtX(projection, window, candidate.x) - selected.start) +
+          Math.abs(timeAtX(projection, window, candidate.x + candidate.width) - selected.end);
+        if (difference <= nearest && (!rect || difference < nearest)) {
+          nearest = difference;
+          rect = candidate;
+        }
+      }
+      if (rect) return { rect, layer, lane, start: selected.start, end: selected.end };
+    }
+  }
+  return null;
+}

package/src/components/schedule/days/parts/column.tsx

@@ -1,5 +1,6 @@
 import { Fragment } from 'react';
 import { Pressable } from 'react-native';
+import { hasSource } from '../../../../core';
 import { pressPoint } from '../../../primitives/press-point';
 import type { ScheduleColumnInput } from '../../schedule.types';
 
@@ -24,10 +25,7 @@ export function ScheduleColumn({
                 rect={rect}
                 layer={layer}
                 lane={lane}
-                highlighted={rect.sources.some(
-                  (source) =>
-                    source.kind === highlightSource?.kind && source.id === highlightSource.id,
-                )}
+                highlighted={hasSource(rect.sources, highlightSource)}
               />
             </Fragment>
           ))}

package/src/core/README.md

@@ -6,6 +6,9 @@ no React Native, no dependencies.
 - Public subpath: `react-native-roster/core`; the root entry re-exports it
 - Authoritative types: `types.ts` (`Lane`, `Layer`, `Interval`, `Gap`,
   `Source`, `Window`, `Projection`, `Rect`, `Coverage`, `LaneGeometry`)
+- Interval helpers: `extentOf(segments: readonly Window[]): Window | null`,
+  `intersectionOf(spans: readonly Window[]): Window | null`, and
+  `unionOf(spans: readonly Window[]): Window[]`
 - Barrel: `index.ts` only
 
 | File | Role |
@@ -13,7 +16,8 @@ no React Native, no dependencies.
 | `axis.ts` | window specs, spans, and navigation (`windowFor`, `next`, `prev`, `today`) |
 | `layout.ts` | rect geometry for one lane in either projection |
 | `coverage.ts` | covered and removed minutes per lane |
-| `spans.ts` | the provenance sweep: exact sources per merged span |
+| `source.ts` | `hasSource(sources, source)` matches kind and id, ignoring labels |
+| `spans.ts` | `extentOf`, `intersectionOf`, `unionOf`, and the provenance sweep with exact sources per merged span |
 | `columns.ts` | day columns, transitions, and skipped dates for the columns projection |
 | `zone.ts` | Intl-only timezone math (offsets, first instants, transitions) |
 | `scale.ts`, `snap.ts` | pixel and time conversion, pointer snapping |
@@ -21,5 +25,18 @@ no React Native, no dependencies.
 | `order.ts`, `flag.ts` | lane comparators and lane flags |
 | `cache.ts`, `hash.ts` | layout and coverage caches keyed by lane content |
 
+All interval helpers reuse the bare `{ start, end }` `Window` type with
+end-exclusive epoch millisecond bounds. `extentOf` bridges disjoint segments;
+`intersectionOf` returns only their shared span. Both return `null` for empty
+input; an empty intersection, including touching bounds, also returns `null`.
+`unionOf` merges overlapping or touching windows, sorts by start, and keeps
+disjoint windows separate. It returns `[]` for empty input and new window objects.
+Every input must have finite bounds and `end > start`; otherwise the helpers throw `RangeError`.
+Inputs may be unsorted, overlapping, nested, or duplicated; inputs are not mutated.
+The existing `Span` type names axis choices only.
+
 Reference: [design](../../docs/design.md), [timezones](../../docs/timezones.md),
 [caches](../../docs/caches.md). Tests: `test/core`.
+
+The public entry binds immutable function aliases directly to preserve implementation
+identity while avoiding repeated CommonJS getter wrappers in consumer bundles.

package/src/core/index.ts

@@ -14,6 +14,8 @@ export { layoutLane } from './layout';
 export type { LaneComparator } from './order';
 export { byCoverage, byLabel } from './order';
 export { snapToStep, timeAtX, timeAtY } from './snap';
+export { hasSource } from './source';
+export { extentOf, intersectionOf, unionOf } from './spans';
 export type {
   Coverage,
   DayColumn,

package/src/core/source.ts

@@ -0,0 +1,9 @@
+import type { Source } from './types';
+
+/** Match source identity by kind and id, ignoring display metadata. */
+export function hasSource(sources: readonly Source[], source: Source | undefined): boolean {
+  return (
+    source !== undefined &&
+    sources.some((item) => item.kind === source.kind && item.id === source.id)
+  );
+}

package/src/core/spans.ts

@@ -1,5 +1,6 @@
-// Sweep boundaries once; reference counts preserve provenance through nested
-// intervals and equal-time ends/starts. Labels never affect source identity.
+// Provenance sweep logic and the extentOf, intersectionOf, and unionOf interval helpers.
+// The sweep uses reference counts to 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[] };
@@ -56,3 +57,66 @@ export function sourceSpans(intervals: Interval[], window: Window): Interval[] {
   }
   return spans;
 }
+
+/**
+ * Earliest start through latest end in epoch milliseconds, end-exclusive; empty input returns null.
+ * Throws RangeError for non-finite bounds or end <= start.
+ * Inputs may be unsorted, overlapping, nested, or duplicated; inputs are not mutated.
+ */
+export function extentOf(segments: readonly Window[]): Window | null {
+  let start = Infinity;
+  let end = -Infinity;
+  for (const segment of segments) {
+    validateSpan(segment);
+    start = Math.min(start, segment.start);
+    end = Math.max(end, segment.end);
+  }
+  return start < end ? { start, end } : null;
+}
+
+/**
+ * Shared epoch milliseconds, end-exclusive; empty input or an empty intersection returns null.
+ * Throws RangeError for non-finite bounds or end <= start.
+ * Inputs may be unsorted, overlapping, nested, or duplicated; inputs are not mutated.
+ */
+export function intersectionOf(spans: readonly Window[]): Window | null {
+  if (spans.length === 0) return null;
+  let start = -Infinity;
+  let end = Infinity;
+  for (const span of spans) {
+    validateSpan(span);
+    start = Math.max(start, span.start);
+    end = Math.min(end, span.end);
+  }
+  return start < end ? { start, end } : null;
+}
+
+/**
+ * Merged end-exclusive epoch windows sorted by start; empty input returns an empty array.
+ * Overlapping or touching spans merge; disjoint spans remain separate.
+ * Throws RangeError for non-finite bounds or end <= start.
+ * Returns new objects without mutating inputs.
+ */
+export function unionOf(spans: readonly Window[]): Window[] {
+  const sorted = spans.map((span) => {
+    validateSpan(span);
+    return { start: span.start, end: span.end };
+  });
+  sorted.sort((a, b) => a.start - b.start);
+  const merged: Window[] = [];
+  for (const span of sorted) {
+    const last = merged.at(-1);
+    if (last && span.start <= last.end) {
+      last.end = Math.max(last.end, span.end);
+    } else {
+      merged.push(span);
+    }
+  }
+  return merged;
+}
+
+function validateSpan(span: Window): void {
+  if (!Number.isFinite(span.start) || !Number.isFinite(span.end) || span.end <= span.start) {
+    throw new RangeError('Span bounds must be finite with end greater than start');
+  }
+}