Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
69.5 KB
Raw Blame
export const SECOND = 1_000;
export const MINUTE = 60 * SECOND;
export const HOUR = 60 * MINUTE;
export const DAY = 24 * HOUR;

const MIN_WINDOW = 2 * SECOND;
const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];

export const TIMELINE_CATEGORIES = [
  { id: 'statement', label: 'Claims', short: 'Claims' },
  { id: 'media', label: 'Media dates', short: 'Media' },
  { id: 'case_activity', label: 'Case activity', short: 'Activity' },
];

function clamp(value, low = 0, high = 1) {
  return Math.min(high, Math.max(low, value));
}

// ── the zone the axis is read in ─────────────────────────────────────────────
//
// **Storage is UTC and stays UTC.** Every instant on disk, in a query and in a
// stated value is unchanged by anything below: this is presentation, the way the
// display preferences are (SPEC §9), and the switch moves where the ticks fall and
// what they are called, never what the case holds.
//
// It exists because an investigator argues in the *event's* local time. A photo
// posted at 19:40 is checked against the light at the place it was taken, not
// against a clock in the analyst's own country — and reading a UTC axis while
// thinking in local time is where an hour goes missing in a chronology.
//
// The rule for ticks: **above a day the step is a calendar one**, so a day tick is
// local midnight whatever the offset was doing that week; **below it a fixed
// interval**, so an hour tick keeps its exact spacing and a zone that jumps an hour
// shows the jump — 01:00 then 03:00 — instead of hiding it.

/** The zone every reading defaults to, and the one the case is stored in. */
export const UTC = 'UTC';

/** This machine's own zone, for the analyst who wants their own working day. It is
 *  a legitimate reading and a poor default, which is why UTC is the default. */
export function machineZone() {
  try {
    return Intl.DateTimeFormat().resolvedOptions().timeZone || UTC;
  } catch {
    return UTC;
  }
}

/** Whether this browser can read that zone at all. A zone name carried in from
 *  another machine must never throw the axis away. */
export function knownZone(zone) {
  if (!zone || zone === UTC) return true;
  try {
    partsFor(zone).format(0);
    return true;
  } catch {
    return false;
  }
}

const FORMATTERS = new Map();

function partsFor(zone) {
  let held = FORMATTERS.get(zone);
  if (!held) {
    held = new Intl.DateTimeFormat('en-US', {
      timeZone: zone,
      hourCycle: 'h23',
      year: 'numeric',
      month: '2-digit',
      day: '2-digit',
      hour: '2-digit',
      minute: '2-digit',
      second: '2-digit',
    });
    FORMATTERS.set(zone, held);
  }
  return held;
}

/** The wall-clock reading of an instant in a zone, as plain numbers. */
export function zonedFields(millis, zone = UTC) {
  const date = new Date(millis);
  if (!zone || zone === UTC) {
    return {
      year: date.getUTCFullYear(),
      month: date.getUTCMonth() + 1,
      day: date.getUTCDate(),
      hour: date.getUTCHours(),
      minute: date.getUTCMinutes(),
      second: date.getUTCSeconds(),
    };
  }
  const held = {};
  for (const part of partsFor(zone).formatToParts(date)) {
    if (part.type !== 'literal') held[part.type] = Number(part.value);
  }
  return {
    year: held.year,
    month: held.month,
    day: held.day,
    // Midnight comes back as 24 in some engines even under h23; both spellings mean
    // the start of the day, and only one of them survives arithmetic.
    hour: held.hour === 24 ? 0 : held.hour,
    minute: held.minute,
    second: held.second,
  };
}

/** A wall clock as an instant, built through `Date` rather than `Date.UTC` so a
 *  two-digit year stays itself instead of landing in the twentieth century. */
function fieldsToUtc({ year, month, day, hour = 0, minute = 0, second = 0 }) {
  const date = new Date(0);
  date.setUTCFullYear(year, month - 1, day);
  date.setUTCHours(hour, minute, second, 0);
  return date.getTime();
}

/** How far ahead of UTC the zone runs at that instant, in milliseconds. */
export function zoneOffset(millis, zone = UTC) {
  if (!zone || zone === UTC) return 0;
  return fieldsToUtc(zonedFields(millis, zone)) - Math.floor(millis / SECOND) * SECOND;
}

/**
 * The instant a wall clock names in a zone.
 *
 * Corrected twice, which is what a zone lookup costs when only the inverse is on
 * offer: the first pass lands within an hour of the answer, and the second settles
 * it — including on the two days a year when the offset moves under the guess. A wall
 * clock a spring change skipped over lands an hour later, in the offset now in force,
 * which is what every calendar does with a time that never happened.
 */
export function instantOf(fields, zone = UTC) {
  const wanted = fieldsToUtc(fields);
  if (!zone || zone === UTC) return wanted;
  let millis = wanted - zoneOffset(wanted, zone);
  millis = wanted - zoneOffset(millis, zone);
  return millis;
}

const pad = (value, size = 2) => String(value).padStart(size, '0');

/** The zone as the analyst sees it named: the short abbreviation the zone itself
 *  uses, or its numeric offset where it has no word for the season. */
export function zoneAbbreviation(zone, at = 0) {
  if (!zone || zone === UTC) return 'UTC';
  try {
    const parts = new Intl.DateTimeFormat('en-US', {
      timeZone: zone,
      timeZoneName: 'short',
    }).formatToParts(new Date(at));
    return parts.find((part) => part.type === 'timeZoneName')?.value ?? zone;
  } catch {
    return zone;
  }
}

/**
 * Every zone this browser can name, sorted.
 *
 * An investigation is rarely in the analyst's own zone and often in no zone the case
 * has a saved point for yet, so the reading has to be choosable outright. The list is
 * the platform's own copy of the IANA database — no dependency, nothing fetched — and
 * naming a zone rather than an offset is what makes a stated hour survive the two days
 * a year the offset moves.
 *
 * Empty where the engine will not list them (`supportedValuesOf` landed in 2022), and
 * the picker says so rather than pretending the world is UTC.
 */
export function worldZones() {
  try {
    const held = Intl.supportedValuesOf?.('timeZone') ?? [];
    return [...held].sort((one, other) => one.localeCompare(other));
  } catch {
    return [];
  }
}

/** A zone's offset at an instant, as `UTC+02:00`. What tells two zones of the same
 *  name apart, and what an analyst reads a stated `+03:00` against. */
export function offsetLabel(zone, at = 0) {
  const minutes = Math.round(zoneOffset(at, zone) / MINUTE);
  if (!minutes) return 'UTC';
  const sign = minutes < 0 ? '-' : '+';
  const size = Math.abs(minutes);
  return `UTC${sign}${pad(Math.floor(size / 60))}:${pad(size % 60)}`;
}

/** The zone as a line in a menu: the place part first, since that is what is typed. */
export function zoneWords(zone) {
  const parts = String(zone ?? '').split('/');
  return {
    place: parts.at(-1).replace(/_/g, ' '),
    region: parts.length > 1 ? parts.slice(0, -1).join(' / ').replace(/_/g, ' ') : '',
  };
}

/**
 * Cities the database renamed, and the name an analyst is going to type.
 *
 * Which of the two a platform lists is not ours to decide: this machine's own copy
 * offers `Europe/Kiev` and `Asia/Calcutta` where a current browser offers `Europe/Kyiv`
 * and `Asia/Kolkata`. Both spellings load either way, so the only thing that breaks is
 * the *search* — and someone working Ukraine typing "kyiv" into a list that says Kiev
 * concludes the zone is missing. Matched both directions, so neither spelling hides a
 * zone the other name would have found.
 */
const ZONE_ALIASES = [
  ['kiev', 'kyiv'],
  ['calcutta', 'kolkata'],
  ['saigon', 'ho chi minh'],
  ['rangoon', 'yangon'],
  ['katmandu', 'kathmandu'],
  ['asmera', 'asmara'],
  ['dacca', 'dhaka'],
  ['ujung pandang', 'makassar'],
  ['bombay', 'mumbai'],
  ['madras', 'chennai'],
];

/**
 * Whether a zone answers what was typed.
 *
 * Matched on the whole name, on the city alone, on the offset and across the renames
 * above, so `kyiv`, `europe` and `+03` all reach the zone whichever way this platform
 * spells it. Underscores are not something anyone types.
 */
export function zoneMatches(zone, query, at = 0) {
  const term = String(query ?? '').trim().toLowerCase();
  if (!term) return true;
  const name = String(zone ?? '').toLowerCase().replace(/_/g, ' ');
  if (name.includes(term) || offsetLabel(zone, at).toLowerCase().includes(term)) return true;
  return ZONE_ALIASES.some(
    ([one, other]) =>
      (name.includes(one) && other.includes(term)) ||
      (name.includes(other) && one.includes(term)),
  );
}

/** One instant written out in the zone, for a readout rather than for a tick. */
export function zonedStamp(value, zone = UTC) {
  const millis = value instanceof Date ? value.getTime() : new Date(value).getTime();
  if (!Number.isFinite(millis)) return '';
  const at = zonedFields(millis, zone);
  return (
    `${pad(at.year, 4)}-${pad(at.month)}-${pad(at.day)} ` +
    `${pad(at.hour)}:${pad(at.minute)}:${pad(at.second)}`
  );
}

export function isoDay(value) {
  const date = value instanceof Date ? value : new Date(value);
  return Number.isFinite(date.getTime()) ? date.toISOString().slice(0, 10) : '';
}

export function isoInstant(value) {
  const date = value instanceof Date ? value : new Date(value);
  if (!Number.isFinite(date.getTime())) return '';
  return date.toISOString().replace('.000Z', 'Z');
}

function boundaryMillis(value, upper = false) {
  if (!value) return Number.NaN;
  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
    const start = new Date(`${value}T00:00:00Z`).getTime();
    return upper ? start + DAY : start;
  }
  return new Date(value).getTime();
}

export function windowMillis(from, to) {
  const start = boundaryMillis(from);
  const end = boundaryMillis(to, true);
  return Number.isFinite(start) && Number.isFinite(end) && start < end
    ? { start, end, span: end - start }
    : null;
}

export function initialWindow(extent) {
  if (!extent?.from || !extent?.to) return { from: '', to: '' };
  const first = new Date(extent.from).getTime();
  const last = new Date(extent.to).getTime();
  if (!Number.isFinite(first) || !Number.isFinite(last)) return { from: '', to: '' };
  const span = Math.max(last - first, SECOND);
  const padding = Math.max(span <= DAY ? SECOND : DAY, span * 0.035);
  return { from: isoInstant(first - padding), to: isoInstant(last + padding) };
}

function rangeFromMillis(start, end) {
  return { from: isoInstant(start), to: isoInstant(end) };
}

export function shiftWindow(from, to, fraction) {
  const window = windowMillis(from, to);
  if (!window) return { from, to };
  const shift = window.span * fraction;
  return rangeFromMillis(window.start + shift, window.end + shift);
}

export function zoomWindow(from, to, factor, anchor = 0.5) {
  const window = windowMillis(from, to);
  if (!window) return { from, to };
  const nextSpan = Math.max(MIN_WINDOW, window.span * factor);
  const pivot = window.start + window.span * clamp(anchor);
  const start = pivot - nextSpan * clamp(anchor);
  return rangeFromMillis(start, start + nextSpan);
}

/**
 * The window in words, for the control that opens it.
 *
 * One reading replaces two date boxes on the toolbar: the boxes are how a window is
 * *typed*, which is the rare act, and the frequent one is checking what is on screen.
 * Read in the axis's own zone, so it agrees with the ticks under it.
 */
export function windowWords(from, to, zone = UTC) {
  const window = windowMillis(from, to);
  if (!window) return 'All dates';
  const start = zonedFields(window.start, zone);
  const end = zonedFields(window.end, zone);
  const day = (at) => `${at.day} ${MONTHS[at.month - 1]}`;
  const clock = (at) => `${pad(at.hour)}:${pad(at.minute)}`;
  if (start.year === end.year && start.month === end.month && start.day === end.day) {
    return `${day(start)} ${start.year}, ${clock(start)} – ${clock(end)}`;
  }
  // Under two days the hours are the point; above it they are noise, and the year is
  // stated once unless the window crosses one.
  if (window.span < 2 * DAY) {
    return `${day(start)} ${clock(start)} – ${day(end)} ${clock(end)}`;
  }
  const left = start.year === end.year ? day(start) : `${day(start)} ${start.year}`;
  return `${left} – ${day(end)} ${end.year}`;
}

/**
 * The spans the window can be set to, widest last.
 *
 * They replace a pair of zoom buttons: pressing − four times to see a year is
 * counting, and "Year" is the thing being asked for. A month and a year are the
 * round numbers a viewport wants, not calendar arithmetic — the ticks handle the
 * calendar.
 */
export const WINDOW_SPANS = [
  { label: 'Hour', ms: HOUR },
  { label: 'Day', ms: DAY },
  { label: 'Week', ms: 7 * DAY },
  { label: 'Month', ms: 30 * DAY },
  { label: 'Year', ms: 365 * DAY },
];

/** Resize the window around its middle, which is what the analyst is looking at. */
export function resizeWindow(from, to, span) {
  const window = windowMillis(from, to);
  if (!window) return { from, to };
  return zoomWindow(from, to, span / window.span, 0.5);
}

export function windowInputValue(value, zone = UTC) {
  const millis = boundaryMillis(value);
  if (!Number.isFinite(millis)) return '';
  if (!zone || zone === UTC) return new Date(millis).toISOString().slice(0, 19);
  const at = zonedFields(millis, zone);
  return (
    `${pad(at.year, 4)}-${pad(at.month)}-${pad(at.day)}` +
    `T${pad(at.hour)}:${pad(at.minute)}:${pad(at.second)}`
  );
}

/** The other direction: the boundary control holds a wall clock, and which instant
 *  that names depends on the zone the axis is being read in. */
export function inputWindowValue(value, zone = UTC) {
  if (!value) return '';
  const withSeconds = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(value) ? `${value}:00` : value;
  if (!zone || zone === UTC) return `${withSeconds}Z`;
  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$/.exec(withSeconds);
  if (!match) return '';
  const [, year, month, day, hour, minute, second] = match.map(Number);
  return isoInstant(
    instantOf({ year, month, day, hour, minute, second }, zone)
  );
}

export function timeAtRatio(from, to, ratio) {
  const window = windowMillis(from, to);
  if (!window) return '';
  const milliseconds = window.start + window.span * clamp(ratio);
  return isoInstant(Math.round(milliseconds / SECOND) * SECOND);
}

export function dateAtRatio(from, to, ratio, tz = null) {
  const instant = timeAtRatio(from, to, ratio);
  if (!instant) return '';
  if (!tz) return instant.slice(0, 10);
  // A day stated in a zone is that zone's day: the pointer's instant is read on
  // its calendar, or dragging an edge near midnight would land a day off.
  const { year, month, day } = zonedFields(new Date(instant).getTime(), tz);
  return `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
}

/** A calendar year on average, for choosing a precision; nothing is dated with it. */
const YEAR = 365.2425 * DAY;

/**
 * The date a click or a drag on the axis proposes, as precise as the window can mean.
 *
 * A pointer lands on a pixel, and a pixel is worth a few minutes on a day's axis and a
 * week on a decade's. So the proposal is cut to what the analyst could have been
 * pointing at: a zoned time under three days, a day up to about a year, a month up to
 * twelve years, a year beyond. A drag gives the range between two such values, and a
 * drag too short to be one is a click.
 */
export function draftWhen(from, to, startRatio, endRatio) {
  const window = windowMillis(from, to);
  if (!window) return '';
  const low = Math.min(startRatio, endRatio);
  const high = Math.max(startRatio, endRatio);
  const click = high - low < .004;
  if (window.span <= 3 * DAY) {
    const start = timeAtRatio(from, to, low);
    const end = timeAtRatio(from, to, high);
    return click ? start : `${start}/${end}`;
  }
  const cut = window.span <= 400 * DAY ? 10 : window.span <= 12 * YEAR ? 7 : 4;
  const a = timeAtRatio(from, to, low).slice(0, cut);
  const b = timeAtRatio(from, to, click ? low : high).slice(0, cut);
  if (!a || !b) return '';
  return a === b ? a : `${a}/${b}`;
}

const DATE_TOKEN = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?([~?%])?$/;
const TIMESTAMP_TOKEN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(Z|([+-])(\d{2}):(\d{2}))?$/;

function makeUtc(year, month, day) {
  const value = new Date(0);
  value.setUTCHours(0, 0, 0, 0);
  value.setUTCFullYear(year, month - 1, day);
  return value;
}

function validDateParts(year, month = 1, day = 1) {
  if (year < 1 || year > 9998 || month < 1 || month > 12 || day < 1) return false;
  const value = makeUtc(year, month, day);
  return value.getUTCFullYear() === year && value.getUTCMonth() === month - 1 && value.getUTCDate() === day;
}

function dateBounds(match) {
  const year = Number(match[1]);
  const month = match[2] ? Number(match[2]) : 1;
  const day = match[3] ? Number(match[3]) : 1;
  if (!validDateParts(year, month, day)) return null;
  const first = makeUtc(year, month, day);
  const last = new Date(first);
  if (match[3]) last.setUTCDate(last.getUTCDate() + 1);
  else if (match[2]) last.setUTCMonth(last.getUTCMonth() + 1);
  else last.setUTCFullYear(last.getUTCFullYear() + 1);
  return { first: first.getTime(), last: last.getTime() };
}

function validateDate(raw) {
  const match = DATE_TOKEN.exec(raw);
  return match ? dateBounds(match) : null;
}

function validateTimestamp(raw) {
  const match = TIMESTAMP_TOKEN.exec(raw);
  if (!match) return false;
  const [, year, month, day, hour, minute, second, , zone, , offsetHour, offsetMinute] = match;
  if (!validDateParts(Number(year), Number(month), Number(day))) return false;
  if (Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59) return false;
  if (zone && zone !== 'Z') {
    const h = Number(offsetHour);
    const m = Number(offsetMinute);
    if (h > 14 || m > 59 || (h === 14 && m > 0)) return false;
  }
  return true;
}

function sortableTimestamp(raw) {
  return validateTimestamp(raw) && /(Z|[+-]\d{2}:\d{2})$/.test(raw);
}

export function validateTemporalValue(raw) {
  if (raw === '') return { valid: true, empty: true, error: '' };
  if (typeof raw !== 'string' || raw !== raw.trim()) {
    return { valid: false, empty: false, error: 'Remove spaces around the value.' };
  }
  if (!raw.includes('/')) {
    const valid = Boolean(validateDate(raw)) || validateTimestamp(raw);
    return {
      valid,
      empty: false,
      error: valid ? '' : 'Use a supported date or timestamp.',
    };
  }
  if (raw.split('/').length !== 2) {
    return { valid: false, empty: false, error: 'A range needs two dates.' };
  }
  const [start, end] = raw.split('/');
  const first = validateDate(start);
  const last = validateDate(end);
  if (first && last) {
    if (first.first >= last.last) {
      return { valid: false, empty: false, error: 'The end must come after the start.' };
    }
    return { valid: true, empty: false, error: '' };
  }
  if (!sortableTimestamp(start) || !sortableTimestamp(end)) {
    return { valid: false, empty: false, error: 'Use two dates or two times with timezones.' };
  }
  if (new Date(start).getTime() >= new Date(end).getTime()) {
    return { valid: false, empty: false, error: 'The end must come after the start.' };
  }
  return { valid: true, empty: false, error: '' };
}

function dateLabel(raw) {
  const match = DATE_TOKEN.exec(raw);
  if (!match) return raw;
  const year = Number(match[1]);
  if (!match[2]) return String(year);
  const month = MONTHS[Number(match[2]) - 1];
  if (!match[3]) return `${month} ${year}`;
  return `${Number(match[3])} ${month} ${year}`;
}

function timestampLabel(raw, tz = null) {
  const match = TIMESTAMP_TOKEN.exec(raw);
  if (!match) return raw;
  const date = `${Number(match[3])} ${MONTHS[Number(match[2]) - 1]} ${match[1]}`;
  // A camera writes its clock to the microsecond, and `17:07:16.000000` is six zeros
  // nobody reads beside a date. Kept to the millisecond when it says something.
  const milli = (match[7] ?? '').slice(0, 3);
  const fraction = /[1-9]/.test(milli) ? `.${milli}` : '';
  // A time with no offset of its own reads on the clock of the zone it was stated
  // in, when there is one; without it the words say nothing is known. An offset
  // written for a named zone says both, since the name is what was picked.
  const zone = match[8] === 'Z' ? ' UTC'
    : match[8] ? (tz ? ` ${tz} (UTC${match[8]})` : ` UTC${match[8]}`)
      : tz ? ` ${tz}` : ' local time';
  return `${date}, ${match[4]}:${match[5]}:${match[6]}${fraction}${zone}`;
}

function qualifierLabels(raw) {
  const labels = [];
  if (raw.includes('~') || raw.includes('%')) labels.push('Approximate');
  if (raw.includes('?') || raw.includes('%')) labels.push('Uncertain');
  return labels;
}

const KIND_LABELS = {
  captured: 'Captured',
  published: 'Published',
  imagery: 'Imagery',
  'imagery-a': 'Imagery A',
  'imagery-b': 'Imagery B',
  collected: 'Collected',
  added: 'Added to case',
  filed: 'Filed in case',
  claim: 'Claim',
  taken: 'Taken',
};

/** What a temporal row's kind is called on the Time panel and the Timeline. */
export function temporalKindLabel(kind) {
  return KIND_LABELS[kind] ?? kind ?? '';
}

/**
 * The span a change seen between two pictures happened in, as a Claim's date.
 *
 * Two UTC instants stay an exact range. Otherwise both are read as days, since a
 * range does not mix a day with a time, and an estimate keeps its `~` on the end
 * it belongs to. Empty when the two do not make a range.
 *
 * @param {string} first a picture's date, as the Time panel carries it
 * @param {string} second the other picture's
 */
export function changeInterval(first, second) {
  if (!first || !second) return '';
  const instant = (value) => sortableTimestamp(value) && value.endsWith('Z');
  const [a, b] = instant(first) && instant(second)
    ? [first, second]
    : [first, second].map((value) => value.replace(/T.*$/, ''));
  const key = (value) => value.replace(/[~?%]$/, '');
  if (key(a) === key(b)) return '';
  const raw = key(a) < key(b) ? `${a}/${b}` : `${b}/${a}`;
  return validateTemporalValue(raw).valid ? raw : '';
}

/**
 * The clock a row's value is read on, in words for the Timeline's facts. A day
 * stated in no zone spans UTC's day, which is what the case has always done and
 * what the analyst could not see; saying so is what lets them correct it.
 */
export function temporalZoneWords(item) {
  if (item?.tz) return item.tz;
  switch (item?.zone) {
    case 'date-only': return 'Not stated, read as UTC days';
    case 'utc': return 'UTC';
    case 'offset': return 'The offset written in the value';
    case 'local': return 'Not stated';
    case 'mixed': return 'Mixed';
    default: return 'Not set';
  }
}

/**
 * The time roles whose range is a window, not a duration: what occurred, or was seen,
 * happened once, somewhere between the two dates. Only `valid` (a state that held)
 * and a range with no role, such as a recording's own start and end, last.
 */
export const WINDOW_ROLES = new Set(['occurred', 'observed']);

/** Whether a row's range is a window around one moment rather than a period. */
export function isWindow(item) {
  return item?.shape === 'interval' && WINDOW_ROLES.has(item?.time_role);
}

/**
 * A stored value in words. `tz` is the zone it was stated in, when it was: a day
 * then names that zone, since the 12th in Kyiv is not UTC's 12th, and a time with
 * no offset of its own reads on that zone's clock. A value stated in no zone reads
 * as it always has. `role` is the statement's time role: a range that occurred or
 * was observed reads "between A and B", since it happened once, not for that long.
 */
export function formatTemporalValue(raw, tz = null, role = null) {
  const check = validateTemporalValue(raw ?? '');
  if (!raw) return { ...check, label: 'Undated', qualifiers: [] };
  if (!check.valid) return { ...check, label: raw, qualifiers: [] };
  const parts = raw.split('/');
  const words = (part) => (DATE_TOKEN.test(part) ? dateLabel(part) : timestampLabel(part, tz));
  const range = WINDOW_ROLES.has(role)
    ? `between ${words(parts[0])} and ${words(parts[1])}`
    : `${words(parts[0])} to ${words(parts[1])}`;
  const base = parts.length === 2 ? range : words(raw);
  const label = tz && parts.some((part) => DATE_TOKEN.test(part)) ? `${base} (${tz})` : base;
  return { ...check, label, qualifiers: qualifierLabels(raw) };
}

function moveDateToken(raw, deltaMs) {
  const match = DATE_TOKEN.exec(raw);
  if (!match) return null;
  const marker = match[4] ?? '';
  if (match[3]) {
    const date = makeUtc(Number(match[1]), Number(match[2]), Number(match[3]));
    date.setUTCDate(date.getUTCDate() + Math.round(deltaMs / DAY));
    return `${isoDay(date)}${marker}`;
  }
  if (match[2]) {
    const date = makeUtc(Number(match[1]), Number(match[2]), 1);
    date.setUTCMonth(date.getUTCMonth() + Math.round(deltaMs / (DAY * 30.4375)));
    return `${date.toISOString().slice(0, 7)}${marker}`;
  }
  const year = Number(match[1]) + Math.round(deltaMs / (DAY * 365.2425));
  return year >= 1 && year <= 9998 ? `${String(year).padStart(4, '0')}${marker}` : null;
}

export function canDragTemporal(item) {
  // a layer marker's day is edited on its layer, not on a claim it is not
  if (item?.category !== 'statement' || !item.raw || item.kind === 'layer') return false;
  const parts = item.raw.split('/');
  const dates = parts.every((part) => DATE_TOKEN.test(part));
  const timestamps = parts.every((part) => sortableTimestamp(part));
  return parts.length <= 2 && (dates || timestamps);
}

const bareDate = (part) => part.replace(/[~?%]$/, '');

function ordered(parts) {
  return parts.length < 2 || validateTemporalValue(parts.join('/')).valid;
}

function timestampOffset(raw) {
  if (raw.endsWith('Z')) return { suffix: 'Z', minutes: 0 };
  const match = raw.match(/([+-])(\d{2}):(\d{2})$/);
  if (!match) return null;
  const minutes = Number(match[2]) * 60 + Number(match[3]);
  return { suffix: match[0], minutes: match[1] === '-' ? -minutes : minutes };
}

function shiftedTimestamp(raw, deltaMs) {
  const match = TIMESTAMP_TOKEN.exec(raw);
  const zone = timestampOffset(raw);
  if (!match || !zone) return null;
  const fraction = match[7] ?? '';
  const resolution = fraction ? Math.max(1, 10 ** (3 - Math.min(3, fraction.length))) : SECOND;
  const shifted = new Date(raw).getTime() + Math.round(deltaMs / resolution) * resolution;
  if (!Number.isFinite(shifted)) return null;
  const wall = new Date(shifted + zone.minutes * MINUTE);
  const base = wall.toISOString().slice(0, 19);
  let heldFraction = '';
  if (fraction) {
    const millis = String(wall.getUTCMilliseconds()).padStart(3, '0');
    heldFraction = `.${fraction.length <= 3 ? millis.slice(0, fraction.length) : millis + fraction.slice(3)}`;
  }
  return `${base}${heldFraction}${zone.suffix}`;
}

function timestampAtZone(value, template) {
  const millis = new Date(value).getTime();
  const original = new Date(template).getTime();
  return Number.isFinite(millis) && Number.isFinite(original)
    ? shiftedTimestamp(template, millis - original)
    : null;
}

export function moveTemporalRaw(item, deltaMs) {
  if (!canDragTemporal(item)) return null;
  const timestamp = item.raw.includes('T');
  const parts = item.raw.split('/').map((part) => timestamp ? shiftedTimestamp(part, deltaMs) : moveDateToken(part, deltaMs));
  if (parts.some((part) => part === null) || !ordered(parts)) return null;
  return parts.join('/');
}

export function resizeTemporalRaw(item, edge, value) {
  if (!canDragTemporal(item) || item.shape !== 'interval') return null;
  const [start, end] = item.raw.split('/');
  if (item.raw.includes('T')) {
    const template = edge === 'start' ? start : end;
    const restated = timestampAtZone(value, template);
    if (!restated) return null;
    const parts = edge === 'start' ? [restated, end] : [start, restated];
    return ordered(parts) ? parts.join('/') : null;
  }
  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return null;
  const marker = (edge === 'start' ? start : end).match(/[~?%]$/)?.[0] ?? '';
  const parts = edge === 'start' ? [`${value}${marker}`, end] : [start, `${value}${marker}`];
  return ordered(parts) ? parts.join('/') : null;
}

export function nudgeTemporalRaw(item, mode, direction) {
  if (!canDragTemporal(item) || ![-1, 1].includes(direction)) return null;
  if (item.raw.includes('T')) {
    if (mode === 'move') return moveTemporalRaw(item, SECOND * direction);
    if (item.shape !== 'interval') return null;
    const parts = item.raw.split('/');
    const index = mode === 'start' ? 0 : 1;
    parts[index] = shiftedTimestamp(parts[index], SECOND * direction);
    return parts[index] && ordered(parts) ? parts.join('/') : null;
  }
  if (mode === 'move') {
    const unit = item.raw.match(/^\d{4}(?!-)/) ? 365.2425 * DAY
      : item.raw.match(/^\d{4}-\d{2}(?:[~?%]|\/|$)/) ? 30.4375 * DAY : DAY;
    return moveTemporalRaw(item, unit * direction);
  }
  if (item.shape !== 'interval') return null;
  const parts = item.raw.split('/');
  const index = mode === 'start' ? 0 : 1;
  const moved = moveDateToken(parts[index], DAY * direction);
  if (!moved) return null;
  parts[index] = moved;
  return ordered(parts) ? parts.join('/') : null;
}

/**
 * How an entry is drawn on a track, in screen pixels.
 *
 * One rule decides the shape: **a point is an instant, a bracket is a reduced date, a
 * window is a moment known only between two dates, a bar is a period, and a box is
 * never an instant.** A date stated to the day, the month or the year covers that whole
 * period, so once the period is wide enough to see it is drawn across it; narrower than
 * `bracket` pixels it is as good as an instant and drawn as one, in the middle of what
 * it covers. A window is read the same way: a video filmed somewhere between two dates
 * did not last that long, so it is never a bar. A mark never moves because of its
 * neighbours or of what is selected: only its row does, and only when two marks would
 * overlap.
 */
export const MARKS = {
  top: 14,
  row: 18,
  bottom: 10,
  /** The room one point takes across the axis; two points closer than this stack. */
  column: 10,
  dot: 8,
  /** Between a mark and the caption beside it. */
  gap: 5,
  caption: 180,
  /** What one character of the 10px caption face costs. Fixed rather than measured:
   *  the layout has to come out the same under a test and on a plate. */
  charWidth: 5.6,
  /** A reduced date narrower than this is drawn as a point. */
  bracket: 6,
  /** The narrowest a period is drawn, however short it is. */
  bar: 2,
  cardWidth: 220,
  cardMin: 120,
  cardHeight: 40,
  cardGap: 8,
  cardRows: 3,
  /** A track with more marks than this in the window stays on captions. */
  cardMax: 12,
  /** Overflow closer than this joins one `+N`. */
  cluster: 28,
};

function markOf(item, window, width) {
  const first = new Date(item.earliest).getTime();
  const last = new Date(item.latest ?? item.earliest).getTime();
  if (!Number.isFinite(first) || !Number.isFinite(last)) return null;
  const a = ((first - window.start) / window.span) * width;
  const b = ((Math.max(first, last) - window.start) / window.span) * width;
  // Half-open like the window it is read against: a period ending where the window
  // starts is not in it, and neither is one starting where it ends.
  if (b <= 0 && a < 0) return null;
  if (a >= width) return null;
  const clipped = { openStart: a < 0, openEnd: b > width };
  const period = item.shape === 'interval' && !isWindow(item);
  if (period || b - a >= MARKS.bracket) {
    const left = clamp(a, 0, width);
    const right = Math.max(clamp(b, 0, width), left + MARKS.bar);
    const mark = period ? 'bar' : isWindow(item) ? 'window' : 'bracket';
    return { mark, left, right, x: left, ...clipped };
  }
  const x = clamp((a + b) / 2, 0, width);
  return { mark: 'point', left: x, right: x, x, openStart: false, openEnd: false };
}

/** The pixels a mark keeps to itself on its row. */
function extentOf(geo) {
  return geo.mark === 'point'
    ? [geo.x - MARKS.column / 2, geo.x + MARKS.column / 2]
    : [geo.left - 1.5, geo.right + 1.5];
}

const overlaps = (a, b) => a[0] < b[1] && b[0] < a[1];

function freeRow(rows, extent, ignore = null) {
  for (let row = 0; ; row += 1) {
    const taken = rows[row];
    if (!taken || !taken.some((one) => one.id !== ignore && overlaps(one.extent, extent))) return row;
  }
}

function byTime(a, b) {
  return String(a.earliest).localeCompare(String(b.earliest))
    || String(a.id).localeCompare(String(b.id));
}

/** How wide a caption is, at the caption face's own metric. */
export function captionWidth(text) {
  return Math.min(MARKS.caption, Math.ceil([...String(text ?? '')].length * MARKS.charWidth) + 4);
}

function captionFor(entry, width) {
  const { geo } = entry;
  const room = captionWidth(entry.item.label);
  if (!String(entry.item.label ?? '').trim()) return [];
  const half = geo.mark === 'point' ? MARKS.dot / 2 : 0;
  const tries = [];
  // Inside a period its name may run the period's length: the room is its own.
  const whole = Math.ceil([...String(entry.item.label)].length * MARKS.charWidth) + 4;
  const inside = Math.min(whole, geo.right - geo.left - 16);
  if (geo.mark !== 'point' && inside >= room) {
    tries.push({ side: 'inside', from: geo.left + 6, room: inside });
  }
  tries.push({ side: 'right', from: geo.right + half + MARKS.gap, room });
  tries.push({ side: 'left', from: geo.left - half - MARKS.gap - room, room });
  return tries
    .filter((one) => one.from >= 0 && one.from + one.room <= width)
    .map((one) => ({ ...one, extent: [one.from, one.from + one.room], width: one.room }));
}

/**
 * Cards hang under the marks when a track has the room: few enough marks, each card
 * at most `cardWidth` wide, none of them overlapping, and no stem crossing another
 * mark or card on its way down. Decided for the whole track at once, so a track reads
 * one way.
 */
function placeCards(placed, rowsTaken, width) {
  if (!placed.length || placed.length > MARKS.cardMax) return null;
  const cardRows = [];
  const cards = new Map();
  const anchored = [...placed].sort((a, b) => a.geo.x - b.geo.x || byTime(a.item, b.item));
  for (const entry of anchored) {
    const { geo, item, row } = entry;
    const anchor = geo.mark === 'point' ? geo.x : geo.left + Math.min(8, (geo.right - geo.left) / 2);
    // The stem runs down from the mark, so every mark under this one in its rows must
    // leave that line clear.
    for (let below = row + 1; below < rowsTaken.length; below += 1) {
      if ((rowsTaken[below] ?? []).some((one) => one.id !== item.id
        && one.extent[0] <= anchor && anchor <= one.extent[1])) return null;
    }
    const thumb = item.category === 'media' && item.thumb;
    // The card holds the name and, under it, the date as written in the 9px mono face.
    const said = Math.ceil(formatTemporalValue(item.raw ?? '', null, item.time_role).label.length * 5.5);
    const wide = clamp(
      Math.max(captionWidth(item.label), said) + 20 + (thumb ? 38 : 0),
      MARKS.cardMin,
      MARKS.cardWidth
    );
    const left = clamp(anchor - 14, 0, Math.max(0, width - wide));
    const extent = [left - MARKS.cardGap / 2, left + wide + MARKS.cardGap / 2];
    let chosen = -1;
    for (let cardRow = 0; cardRow < MARKS.cardRows; cardRow += 1) {
      const taken = cardRows[cardRow] ?? [];
      if (taken.some((one) => overlaps(one, extent))) continue;
      // A stem down to a lower row passes the cards above it.
      const crossed = cardRows.slice(0, cardRow).some((row) =>
        row.some((one) => one[0] <= anchor && anchor <= one[1]));
      if (crossed) continue;
      chosen = cardRow;
      break;
    }
    if (chosen === -1) return null;
    (cardRows[chosen] ??= []).push(extent);
    cards.set(item.id, { row: chosen, left, width: wide, anchor });
  }
  return { cards, rows: cardRows.length };
}

/**
 * Lay a track's entries out against an axis `axisWidth` pixels wide.
 *
 * Marks first, in a stable order (pinned, then time), each on the first row where it
 * overlaps no other mark: points stack down in their column, brackets and bars take
 * the first row free across their whole span. Past `maxItemRows` an entry joins a
 * `+N` instead, unless it is pinned. Captions come second, in the order selected,
 * pinned, time: each tries the right of its mark, then the left (a period first tries
 * inside itself), and is left out when every side would cover something already
 * there. The mark stays either way.
 */
export function layoutTimelineItems(items, from, to, axisWidth = 1000, maxItemRows = 6, options = {}) {
  const window = windowMillis(from, to);
  const empty = {
    items: [], clusters: [], rows: 1, cards: false, cardRows: 0, labelled: 0,
    height: MARKS.top + MARKS.row + MARKS.bottom,
  };
  if (!window) return empty;
  const width = Math.max(320, axisWidth);
  const { selectedId = null } = options;
  const entries = [];
  for (const item of items) {
    const geo = markOf(item, window, width);
    if (geo) entries.push({ item, geo });
  }
  entries.sort((a, b) =>
    Number(Boolean(b.item.pinned)) - Number(Boolean(a.item.pinned))
    || Number(a.geo.mark !== 'point') - Number(b.geo.mark !== 'point')
    || byTime(a.item, b.item));

  const rowsTaken = [];
  const placed = [];
  const overflow = [];
  for (const entry of entries) {
    const extent = extentOf(entry.geo);
    const row = freeRow(rowsTaken, extent);
    if (row >= maxItemRows && !entry.item.pinned) {
      overflow.push(entry);
      continue;
    }
    (rowsTaken[row] ??= []).push({ id: entry.item.id, extent });
    placed.push({ ...entry, row });
  }

  const groups = [];
  for (const entry of [...overflow].sort((a, b) => a.geo.x - b.geo.x || byTime(a.item, b.item))) {
    const at = entry.geo.mark === 'point' ? entry.geo.x : (entry.geo.left + entry.geo.right) / 2;
    const group = groups.find((one) => Math.abs(one.at - at) < MARKS.cluster);
    if (group) {
      group.items.push(entry.item);
      group.at = (group.at * (group.items.length - 1) + at) / group.items.length;
    } else groups.push({ at, items: [entry.item] });
  }
  const markRows = Math.max(1, rowsTaken.length);
  const clusters = groups.map((group, index) => ({
    id: `cluster:${index}:${group.items[0].id}`,
    row: markRows,
    left: (group.at / width) * 100,
    count: group.items.length,
    items: [...group.items].sort(byTime),
    earliest: [...group.items].sort(byTime)[0]?.earliest ?? '',
  }));
  const rows = markRows + (clusters.length ? 1 : 0);

  const carded = clusters.length ? null : placeCards(placed, rowsTaken, width);
  const captions = new Map();
  if (!carded) {
    const taken = rowsTaken.map((row) => [...row]);
    const order = [...placed].sort((a, b) =>
      Number(b.item.id === selectedId) - Number(a.item.id === selectedId)
      || Number(Boolean(b.item.pinned)) - Number(Boolean(a.item.pinned))
      || byTime(a.item, b.item));
    for (const entry of order) {
      const row = taken[entry.row];
      const fit = captionFor(entry, width).find((one) =>
        !row.some((other) => other.id !== entry.item.id && overlaps(other.extent, one.extent)));
      if (!fit) continue;
      row.push({ id: `${entry.item.id}:caption`, extent: fit.extent });
      captions.set(entry.item.id, fit);
    }
  }

  const laid = [...placed].sort((a, b) => byTime(a.item, b.item)).map(({ item, geo, row }) => {
    const box = geo.mark === 'point'
      ? { from: geo.x - MARKS.column / 2, to: geo.x + MARKS.column / 2 }
      : { from: geo.left, to: geo.right };
    const caption = captions.get(item.id);
    const card = carded?.cards.get(item.id);
    return {
      ...item,
      mark: geo.mark,
      row,
      /** Where the instant, or the start of the span, falls: a percentage of the axis. */
      left: (geo.x / width) * 100,
      /** How much of the axis the mark covers: nothing for a point. */
      width: geo.mark === 'point' ? 0 : ((geo.right - geo.left) / width) * 100,
      openStart: geo.openStart,
      openEnd: geo.openEnd,
      caption: caption
        ? { side: caption.side, offset: caption.from - box.from, width: caption.width, left: caption.from }
        : null,
      card: card
        ? {
          row: card.row,
          offset: card.left - box.from,
          width: card.width,
          left: card.left,
          stem: card.anchor - box.from,
          anchor: card.anchor,
        }
        : null,
    };
  });
  const cardRows = carded?.rows ?? 0;
  const marksHeight = MARKS.top + rows * MARKS.row;
  return {
    items: laid,
    clusters,
    rows,
    cards: Boolean(carded),
    cardRows,
    labelled: laid.filter((item) => item.caption || item.card).length,
    height: marksHeight + (cardRows ? 6 + cardRows * (MARKS.cardHeight + 6) : 0) + MARKS.bottom,
  };
}

/**
 * How many rows of marks each lane may take before the rest go to a `+N`, out of the
 * `room` rows the axis has. `needs` is what each lane would take uncapped, `null` for
 * one that is not shared out (opened, or folded). A lane that needs little takes only
 * that; the rest is split evenly among those that need more, and none gets under
 * `floor`, so a short axis reads as it always did.
 */
export function shareItemRows(needs, room, floor = 6) {
  const caps = needs.map(() => null);
  const order = needs
    .map((need, index) => ({ need, index }))
    .filter((one) => one.need !== null)
    .sort((a, b) => a.need - b.need);
  let left = Math.max(0, Math.floor(room));
  order.forEach(({ need, index }, at) => {
    const fair = Math.floor(left / (order.length - at));
    const cap = Math.max(floor, Math.min(need, fair));
    caps[index] = cap;
    // A lane under the floor keeps the floor but only uses what it needs.
    left = Math.max(0, left - Math.min(need, cap));
  });
  return caps;
}

/** The top of a card row under a track's marks, in pixels from the top of the track. */
export function cardTop(layout, row) {
  return MARKS.top + layout.rows * MARKS.row + 6 + row * (MARKS.cardHeight + 6);
}

const TICK_STEPS = [
  ['second', 1, SECOND], ['second', 5, 5 * SECOND], ['second', 10, 10 * SECOND],
  ['second', 30, 30 * SECOND], ['minute', 1, MINUTE], ['minute', 5, 5 * MINUTE],
  ['minute', 15, 15 * MINUTE], ['minute', 30, 30 * MINUTE], ['hour', 1, HOUR],
  ['hour', 3, 3 * HOUR], ['hour', 6, 6 * HOUR], ['hour', 12, 12 * HOUR],
  ['day', 1, DAY], ['day', 2, 2 * DAY], ['day', 7, 7 * DAY], ['day', 14, 14 * DAY],
  ['month', 1, 30.4375 * DAY], ['month', 3, 91.3125 * DAY], ['month', 6, 182.625 * DAY],
  ['year', 1, 365.25 * DAY], ['year', 2, 730.5 * DAY], ['year', 5, 1826.25 * DAY],
  ['year', 10, 3652.5 * DAY], ['year', 25, 9131.25 * DAY], ['year', 50, 18262.5 * DAY],
  ['year', 100, 36525 * DAY],
].map(([unit, step, ms]) => ({ unit, step, ms }));

function tickChoice(span, width = 1000) {
  const target = clamp(Math.round(width / 100), 8, 12);
  return TICK_STEPS.reduce((best, choice) => {
    const distance = Math.abs(span / choice.ms - target);
    return distance < best.distance ? { choice, distance } : best;
  }, { choice: TICK_STEPS.at(-1), distance: Infinity }).choice;
}

/** A whole number of local days added to a date, normalised through UTC so a month
 *  end and a leap day are the calendar's problem rather than this file's. */
function addDays(fields, count) {
  const date = new Date(fieldsToUtc({ ...fields, hour: 0, minute: 0, second: 0 }));
  date.setUTCDate(date.getUTCDate() + count);
  return {
    year: date.getUTCFullYear(),
    month: date.getUTCMonth() + 1,
    day: date.getUTCDate(),
    hour: 0,
    minute: 0,
    second: 0,
  };
}

/**
 * Where the first tick falls, as an instant.
 *
 * Aligned to an anchor that does not depend on the window, or the ticks would slide
 * under a pan: a year to a multiple of the step, a month to an absolute month
 * number, a day to a local day number, and anything shorter to a multiple of its own
 * length off the zone's midnight.
 */
function alignTick(window, choice, zone) {
  const at = zonedFields(window.start, zone);
  if (choice.unit === 'year') {
    const year = Math.ceil(at.year / choice.step) * choice.step;
    return instantOf({ year, month: 1, day: 1 }, zone);
  }
  if (choice.unit === 'month') {
    const absolute = at.year * 12 + (at.month - 1);
    const aligned = Math.ceil(absolute / choice.step) * choice.step;
    return instantOf(
      { year: Math.floor(aligned / 12), month: (aligned % 12) + 1, day: 1 },
      zone,
    );
  }
  const shift = zoneOffset(window.start, zone);
  if (choice.unit === 'day') {
    const days = Math.ceil((window.start + shift) / DAY / choice.step) * choice.step;
    const midnight = new Date(days * DAY);
    return instantOf(
      {
        year: midnight.getUTCFullYear(),
        month: midnight.getUTCMonth() + 1,
        day: midnight.getUTCDate(),
      },
      zone,
    );
  }
  return Math.ceil((window.start + shift) / choice.ms) * choice.ms - shift;
}

function advanceTick(millis, choice, zone) {
  if (choice.unit === 'year' || choice.unit === 'month') {
    const at = zonedFields(millis, zone);
    const absolute =
      at.year * 12 + (at.month - 1) + (choice.unit === 'year' ? choice.step * 12 : choice.step);
    return instantOf(
      { year: Math.floor(absolute / 12), month: (absolute % 12) + 1, day: 1 },
      zone,
    );
  }
  if (choice.unit === 'day') {
    return instantOf(addDays(zonedFields(millis, zone), choice.step), zone);
  }
  return millis + choice.ms;
}

function tickLabel(millis, unit, zone) {
  const at = zonedFields(millis, zone);
  if (unit === 'year') return String(at.year);
  if (unit === 'month') return `${MONTHS[at.month - 1]} ${at.year}`;
  if (unit === 'day') return `${at.day} ${MONTHS[at.month - 1]}`;
  // An hour tick is on the hour in UTC and on the half hour in a zone whose offset
  // is not a whole one, so the minutes are printed rather than assumed to be zero.
  if (unit === 'hour') return `${pad(at.hour)}:${pad(at.minute)}`;
  if (unit === 'minute') return `${pad(at.hour)}:${pad(at.minute)}`;
  return `${pad(at.minute)}:${pad(at.second)}`;
}

function generateTicks(window, choice, labelled, zone) {
  let cursor = alignTick(window, choice, zone);
  const ticks = [];
  for (let guard = 0; cursor <= window.end && guard < 500; guard++) {
    if (cursor >= window.start) {
      ticks.push({
        at: new Date(cursor).toISOString(),
        left: ((cursor - window.start) / window.span) * 100,
        label: labelled ? tickLabel(cursor, choice.unit, zone) : '',
      });
    }
    const next = advanceTick(cursor, choice, zone);
    // A calendar step that fails to move — an hour a zone skipped, a guard against
    // any future unit — would spin the loop out on its own guard instead of drawing.
    if (next <= cursor) break;
    cursor = next;
  }
  return ticks;
}

export function axisTicks(from, to, width = 1000, zone = UTC) {
  const window = windowMillis(from, to);
  return window ? generateTicks(window, tickChoice(window.span, width), true, zone) : [];
}

export function axisMinorTicks(from, to, width = 1000, zone = UTC) {
  const window = windowMillis(from, to);
  if (!window) return [];
  const major = tickChoice(window.span, width);
  const index = TICK_STEPS.indexOf(major);
  const minor = TICK_STEPS[Math.max(0, index - 1)];
  if (window.span / minor.ms > 64 || minor === major) return [];
  const majorTimes = new Set(generateTicks(window, major, false, zone).map((tick) => tick.at));
  return generateTicks(window, minor, false, zone).filter((tick) => !majorTimes.has(tick.at));
}

export function axisScale(from, to, width = 1000) {
  const window = windowMillis(from, to);
  if (!window) return '';
  const unit = tickChoice(window.span, width).unit;
  return `${unit[0].toUpperCase()}${unit.slice(1)}s`;
}

export function axisBands(from, to, width = 1000, zone = UTC) {
  const window = windowMillis(from, to);
  if (!window) return [];
  const unit = tickChoice(window.span, width).unit;
  const bandUnit = ['second', 'minute', 'hour'].includes(unit) ? 'day' : unit === 'day' ? 'month' : 'year';
  const at = zonedFields(window.start, zone);
  // The band a window opens inside starts before it, so it is floored rather than
  // aligned: half a day at the left edge is still that day.
  let head =
    bandUnit === 'day'
      ? { year: at.year, month: at.month, day: at.day }
      : bandUnit === 'month'
        ? { year: at.year, month: at.month, day: 1 }
        : { year: at.year, month: 1, day: 1 };
  const bands = [];
  for (let guard = 0; guard < 200; guard++) {
    const cursor = instantOf(head, zone);
    if (cursor >= window.end) break;
    const after =
      bandUnit === 'day'
        ? addDays(head, 1)
        : bandUnit === 'month'
          ? { year: head.month === 12 ? head.year + 1 : head.year, month: head.month === 12 ? 1 : head.month + 1, day: 1 }
          : { year: head.year + 1, month: 1, day: 1 };
    const next = instantOf(after, zone);
    const start = Math.max(cursor, window.start);
    const end = Math.min(next, window.end);
    const label = bandUnit === 'day'
      ? `${head.day} ${MONTHS[head.month - 1]} ${head.year}`
      : bandUnit === 'month' ? `${MONTHS[head.month - 1]} ${head.year}`
        : String(head.year);
    if (end > start) {
      bands.push({
        label,
        left: ((start - window.start) / window.span) * 100,
        width: ((end - start) / window.span) * 100,
      });
    }
    if (next <= cursor) break;
    head = after;
  }
  return bands;
}

export function nowPosition(from, to, now = Date.now()) {
  const window = windowMillis(from, to);
  return window && now >= window.start && now <= window.end
    ? ((now - window.start) / window.span) * 100
    : null;
}

/** The instants a bucket key opens and closes: `2026`, `2026-08`, `2026-08-02`, `2026-08-02T14`. */
function bucketBounds(start) {
  const tail = { 4: '-01-01T00:00:00Z', 7: '-01T00:00:00Z', 10: 'T00:00:00Z', 13: ':00:00Z' };
  const suffix = tail[String(start ?? '').length];
  if (suffix === undefined) return null;
  const first = new Date(`${start}${suffix}`);
  if (!Number.isFinite(first.getTime())) return null;
  const last = new Date(first);
  if (start.length === 4) last.setUTCFullYear(last.getUTCFullYear() + 1);
  else if (start.length === 7) last.setUTCMonth(last.getUTCMonth() + 1);
  else if (start.length === 10) last.setUTCDate(last.getUTCDate() + 1);
  else last.setUTCHours(last.getUTCHours() + 1);
  return { first: first.getTime(), last: last.getTime() };
}

/**
 * Where clicking a bar takes the axis: onto what that bar holds.
 *
 * The entries themselves rather than the period they were counted under, so the
 * window the click opens is the one the bar draws — landing on the period would put
 * six entries from the first week of August under a window a month wide, and the
 * brush would come to rest somewhere other than on the bar that was clicked. A margin
 * on each side keeps the outermost entry off the very edge of the axis.
 */
export function bucketWindow(bucket) {
  const held = typeof bucket === 'string' ? null : bucketSpan(bucket);
  const start = typeof bucket === 'string' ? bucket : bucket?.start ?? '';
  if (held && held.last > held.first) {
    const margin = (held.last - held.first) * 0.06;
    return rangeFromMillis(held.first - margin, held.last + margin);
  }
  if (held) return rangeFromMillis(held.first - 12 * HOUR, held.first + 12 * HOUR);
  const bounds = bucketBounds(start);
  if (!bounds) return null;
  if (start.length === 10) return rangeFromMillis(bounds.first - 3 * DAY, bounds.first + 4 * DAY);
  return rangeFromMillis(bounds.first, bounds.last);
}

/**
 * How tall a bucket's column stands, against the fullest one.
 *
 * On the square root of the share rather than the share itself: a scraped batch puts
 * two hundred entries in one week and the rest of the case holds ones and twos, and
 * read straight those all sit on the floor together, indistinguishable. The exact
 * count is a hover away, which is what the minimap says it is for.
 */
export function bucketScale(buckets) {
  const max = Math.max(1, ...buckets.map((bucket) => bucket.count));
  return buckets.map((bucket) => ({
    ...bucket,
    height: Math.max(12, Math.sqrt(Math.max(0, bucket.count) / max) * 100),
  }));
}

/**
 * Where a bucket's entries actually sit, which is what its bar is drawn across.
 *
 * The period a bucket is named after is the coarse thing: six rows in the first week
 * of August are not "August". The server reports the inner span with the counts, so a
 * bar marks the days something happened on. The period is the fallback for a reading
 * that predates that — a captured snapshot, mostly.
 */
export function bucketSpan(bucket) {
  const first = new Date(bucket?.first ?? '').getTime();
  const last = new Date(bucket?.last ?? '').getTime();
  if (Number.isFinite(first)) {
    return { first, last: Number.isFinite(last) && last > first ? last : first };
  }
  const bounds = bucketBounds(bucket?.start);
  return bounds ? { first: bounds.first, last: bounds.last } : null;
}

/**
 * The instants the overview draws between: the whole of what the case holds.
 *
 * The bars, the date scale and the visible-range brush are all placed on this one
 * mapping from instant to position, which is the only way the three can agree. Held
 * as the union of the extent and every bar, so nothing the overview draws can fall
 * off the end of the scale it is drawn on.
 */
export function densityScale(buckets, extent) {
  const from = new Date(extent?.from ?? '').getTime();
  const to = new Date(extent?.to ?? '').getTime();
  const bins = (buckets ?? []).map((bucket) => bucketBounds(bucket?.start)).filter(Boolean);
  const starts = [...bins.map((bin) => bin.first), ...(Number.isFinite(from) ? [from] : [])];
  const ends = [...bins.map((bin) => bin.last), ...(Number.isFinite(to) ? [to] : [])];
  if (!starts.length || !ends.length) return null;
  const start = Math.min(...starts);
  const end = Math.max(...ends);
  return end > start ? { first: start, last: end, span: end - start } : null;
}

/**
 * One column per bin, across the bin it counts.
 *
 * A histogram's columns are as wide as its bins, which is what makes the heights
 * comparable — and it is honest here only because the bins are cut fine enough to be
 * columns (`densityUnit`). Cut coarse, the same rule drew a month-wide block for six
 * entries in one week, and a mark at the month's opening claimed a date nothing
 * happened on: a January bucket holding the 14th and the 27th marked the 1st, ahead
 * of a window that opened on the 6th, so the bar for two entries on screen sat
 * outside the brush that was showing them.
 */
export function layoutDensityBuckets(buckets, extent) {
  const scale = densityScale(buckets, extent);
  if (!scale) return [];
  const { first, span } = scale;
  return bucketScale(buckets).flatMap((bucket) => {
    const bounds = bucketBounds(bucket.start);
    if (!bounds) return [];
    const left = clamp((bounds.first - first) / span) * 100;
    const right = clamp((bounds.last - first) / span) * 100;
    // A bin thinner than a hairline still has to be visible; the floor is a
    // `min-width` in the stylesheet, so the geometry here stays honest.
    return [{ ...bucket, left, width: right - left }];
  });
}

function stepPeriod(millis, unit) {
  const at = new Date(millis);
  if (unit === 'year') at.setUTCFullYear(at.getUTCFullYear() + 1);
  else if (unit === 'month') at.setUTCMonth(at.getUTCMonth() + 1);
  else if (unit === 'hour') at.setUTCHours(at.getUTCHours() + 1);
  else at.setUTCDate(at.getUTCDate() + 1);
  return at.getTime();
}

function floorPeriod(millis, unit) {
  const at = new Date(millis);
  if (unit === 'hour') at.setUTCMinutes(0, 0, 0);
  else at.setUTCHours(0, 0, 0, 0);
  if (unit === 'month' || unit === 'year') at.setUTCDate(1);
  if (unit === 'year') at.setUTCMonth(0);
  return at.getTime();
}

/**
 * How finely to cut the overview, so it reads as a histogram rather than as a stroke.
 *
 * The finest cut whose bins still have a column's width on screen. Cut by the period
 * a case happens to span — months, because the case runs over months — every bar was
 * a month wide, and two hundred entries in one week drew the same mark as one entry
 * that could be anywhere in May. Counted by day instead, that week is five columns
 * and May is one, which is the shape the case actually has.
 */
export function densityUnit(extent, width = 800) {
  const first = new Date(extent?.from ?? '').getTime();
  const last = new Date(extent?.to ?? '').getTime();
  if (!Number.isFinite(first) || !Number.isFinite(last) || last <= first) return 'day';
  const span = last - first;
  // Around two pixels a bin — the floor the stylesheet gives a column — held between
  // a readable minimum and the server's ceiling on how many buckets a reading carries.
  const room = Math.min(500, Math.max(60, Math.round(width / 2)));
  for (const [unit, length] of [['hour', HOUR], ['day', DAY], ['month', 28 * DAY]]) {
    if (span / length <= room) return unit;
  }
  return 'year';
}

/** Room for the longest label a scale prints, so two never land on each other. */
const TICK_ROOM = 56;

/**
 * The scale under the minimap: one slot per period, named in the middle of its own.
 *
 * A bucket counts a period rather than an instant, so its name belongs under the
 * middle of the block that draws it. Named at the instant the period opens — which is
 * how the continuous ruler on the axis is labelled, and the wrong rule here — every
 * name sat to the right of the bar it named, and the reader had to pair each block
 * with the label after it.
 *
 * Only as many names as fit, so two years of months read as a scale rather than a
 * crowd; the unnamed slots still carry their share of the width. Read in UTC because
 * that is how the buckets themselves are cut, and naming them in another zone would
 * rename them.
 */
export function densityTicks(buckets, extent, width = 800) {
  const scale = densityScale(buckets, extent);
  if (!scale) return [];
  // Its own unit, not the bins': the bins are cut as fine as they can be drawn, and a
  // scale reading "3 Jan, 4 Jan, 5 Jan…" across eight months would name the columns
  // rather than the case. Months for a case that runs over months, hours for a day.
  const unit = scale.span <= 2 * DAY ? 'hour'
    : scale.span <= 62 * DAY ? 'day'
      : scale.span <= 6 * 365 * DAY ? 'month' : 'year';
  const slots = [];
  // Floored to the period the scale opens inside, so the slots are whole calendar
  // months rather than months counted from whatever day the case starts on. The two
  // outermost are clipped to the scale, which is what a period the case only holds
  // part of looks like.
  let cursor = floorPeriod(scale.first, unit);
  for (let guard = 0; cursor < scale.last && guard < 400; guard++) {
    const next = stepPeriod(cursor, unit);
    if (next <= cursor) break;
    slots.push({
      at: cursor,
      first: Math.max(cursor, scale.first),
      last: Math.min(next, scale.last),
    });
    cursor = next;
  }
  if (!slots.length) return [];
  const every = Math.max(1, Math.ceil(TICK_ROOM / Math.max(1, width / slots.length)));
  const last = slots.length - 1 - ((slots.length - 1) % every);
  let named = '';
  return slots.map((slot, index) => {
    const at = zonedFields(slot.at, UTC);
    const year = String(at.year);
    const names = index % every === 0;
    // The wider unit is stated when it changes, not on every slot: eight months in one
    // year do not need the year eight times, and the hours of one day need its date
    // once.
    const context = unit === 'hour' ? `${at.day} ${MONTHS[at.month - 1]}` : year;
    const label = !names ? ''
      : unit === 'year' ? year
        : unit === 'hour'
          ? (context === named ? `${pad(at.hour)}:00` : `${pad(at.hour)}:00 · ${context}`)
          : unit === 'day' ? `${at.day} ${MONTHS[at.month - 1]}`
            : year === named ? MONTHS[at.month - 1] : `${MONTHS[at.month - 1]} ${year}`;
    if (names) named = context;
    return {
      key: String(slot.at),
      left: ((slot.first - scale.first) / scale.span) * 100,
      width: ((slot.last - slot.first) / scale.span) * 100,
      label,
      // The outermost names are pinned to their own edge instead of centred, so a
      // label wider than its slot leans inward rather than off the minimap.
      anchor: !names ? '' : index === 0 ? 'start' : index === last ? 'end' : 'middle',
    };
  });
}

/**
 * Spans of absolute time as bands across the visible window.
 *
 * Used for the daylight ribbon (`/api/geo/daylight`), and it is deliberately not
 * zone-aware: when the sun was up is a fact about instants, so it is placed on the
 * axis the same way whichever clock the axis is labelled with. Clipped rather than
 * dropped, so the run that opens before the window still fills the left edge.
 */
export function ribbonBands(spans, from, to) {
  const window = windowMillis(from, to);
  if (!window || !Array.isArray(spans)) return [];
  const bands = [];
  for (const span of spans) {
    const first = new Date(span?.from ?? '').getTime();
    const last = new Date(span?.to ?? '').getTime();
    if (!Number.isFinite(first) || !Number.isFinite(last)) continue;
    const left = clamp((first - window.start) / window.span);
    const right = clamp((last - window.start) / window.span);
    if (right <= left) continue;
    bands.push({ key: span.from, left: left * 100, width: (right - left) * 100 });
  }
  return bands;
}

// ── how far apart two entries are ────────────────────────────────────────────
//
// The one figure a chronology is read for and the one it never printed: an axis
// shows that two things are near each other, and the finding is *four hours and
// twelve minutes*, measured by hand off two tooltips.
//
// It is arithmetic over the **bounds the case derived**, never over the words a
// source used, and that is what keeps it honest. A stated day is a window a day
// wide (``engine/temporal``: bounds are half-open, ``earliest`` inclusive and
// ``latest`` exclusive), so two dated statements are not a number apart — they are a
// *range* apart, and printing the difference of the two midnights as a fact is how a
// chronology ends up claiming precision nobody has. Two exact timestamps do give one
// number, and then it is given.

/** The window an entry occupies, or null when it has no place on the axis. */
export function itemWindow(item) {
  const first = new Date(item?.earliest ?? '').getTime();
  const last = new Date(item?.latest ?? '').getTime();
  if (!Number.isFinite(first) || !Number.isFinite(last)) return null;
  return { first, last: Math.max(first, last) };
}

/** Whether a window is tight enough to be read as one instant. A second-precision
 *  timestamp carries a one-second window, which is a point for every purpose here. */
const isInstant = (window) => window.last - window.first <= SECOND;

/**
 * How much of an entry's width is *not knowing*, as opposed to lasting.
 *
 * The distinction the gap arithmetic turns on. A point dated to the day is a day-wide
 * window of ignorance, and everything measured from it inherits that. An interval's
 * two bounds are what the analyst stated its extent to be — vagueness about either
 * end is carried by the value's own `~`/`?` qualifier, which the panel shows
 * separately — so its edges are taken as given. Without this, two exact periods four
 * hours apart came back as "between 2 h and 12 h", which is the invented uncertainty
 * this whole file exists to avoid.
 */
function slackOf(item, window) {
  if (item?.shape === 'interval') return 0;
  const width = window.last - window.first;
  return width <= SECOND ? 0 : width;
}

/**
 * What an entry's own width means: a period lasts, a point is merely imprecise.
 *
 * The distinction the panel exists to keep: *this closure ran for three days* and
 * *this photo is dated to some point in one day* are the same three-day-ish number on
 * screen and opposite readings of the case.
 */
export function itemExtent(item) {
  const window = itemWindow(item);
  if (!window) return null;
  const ms = window.last - window.first;
  if (item.shape === 'interval') return { ms, kind: 'duration', precision: item.precision ?? '' };
  if (isInstant(window)) return null;
  return { ms, kind: 'precision', precision: item.precision ?? '' };
}

/**
 * Where two entries stand relative to each other.
 *
 * ``gap.min``/``gap.max`` bracket what the bounds allow, ``gap.stated`` is the
 * difference between the two values as written, and ``gap.exact`` says whether the
 * three are the same number. Overlapping windows report the overlap and refuse to
 * order the pair: either could be first, and saying which would be invention.
 */
export function compareTimelineItems(a, b) {
  const one = itemWindow(a);
  const other = itemWindow(b);
  if (!one || !other || a?.id === b?.id) return null;
  const forwards = one.first <= other.first;
  const [early, late] = forwards ? [one, other] : [other, one];
  const [earlyItem, lateItem] = forwards ? [a, b] : [b, a];
  const apart = early.last <= late.first;
  // Measured from where the first one **ends** to where the second one **starts**,
  // which is the same thing as instant-to-instant once both are points, and the only
  // right reading once either is a period.
  const slack = { early: slackOf(earlyItem, early), late: slackOf(lateItem, late) };
  const ends = early.first + (earlyItem.shape === 'interval' ? early.last - early.first : 0);
  return {
    order: apart ? 'sequence' : 'overlap',
    earlier: earlyItem,
    later: lateItem,
    gap: apart
      ? {
          min: Math.max(0, late.first - early.last),
          max: late.first + slack.late - ends,
          // As the two values were written, ignoring what each one leaves open. Only
          // ever shown beside a range, and there it is the number the analyst expects
          // to see: the difference between the two dates on the page.
          stated: late.first - ends,
          exact: !slack.early && !slack.late,
        }
      : null,
    overlap: apart ? null : Math.min(early.last, late.last) - late.first,
    extents: [
      { item: earlyItem, extent: itemExtent(earlyItem) },
      { item: lateItem, extent: itemExtent(lateItem) },
    ].filter((row) => row.extent),
  };
}

const SPAN_UNITS = [
  { ms: 365.2425 * DAY, word: 'year' },
  { ms: DAY, word: 'day' },
  { ms: HOUR, word: 'hour' },
  { ms: MINUTE, word: 'minute' },
  { ms: SECOND, word: 'second' },
];

/**
 * A length of time as its parts: at most two, largest first.
 *
 * Two rather than all of them because the second one is where the reading stops being
 * useful: *2 days 6 hours* is a fact and *2 days 6 hours 14 minutes 3 seconds* is a
 * serial number.
 */
function spanParts(ms) {
  const total = Math.max(0, Math.round(Number(ms) || 0));
  const parts = [];
  let rest = total;
  for (const unit of SPAN_UNITS) {
    if (parts.length === 2) break;
    const count = Math.floor(rest / unit.ms);
    if (!count && !parts.length) continue;
    if (!count) break;
    parts.push({ count, word: unit.word });
    rest -= count * unit.ms;
  }
  return parts;
}

/** Words, not symbols. A panel that reads *2 d 6 h* is a panel written for whoever
 *  already knew what it said. */
const spanWords = (parts) =>
  parts.map(({ count, word }) => `${count} ${word}${count === 1 ? '' : 's'}`).join(' ');

/** A length of time in plain words, or an honest shrug under one second. */
export function formatSpan(ms) {
  const parts = spanParts(ms);
  return parts.length ? spanWords(parts) : 'under a second';
}

/**
 * A gap the dates only pin down to a range, as one phrase.
 *
 * *Between 2 and 4 days* rather than *2 days to 4 days*: the unit is factored out when
 * both ends land on the same one, which is the common case and the only version that
 * reads like a sentence. A minimum of nothing is not a range at all — *up to 4 days*
 * is what two consecutive dates actually license, where "between 0 and 4" invites the
 * reader to average it.
 */
export function formatSpanRange(min, max) {
  const low = spanParts(min);
  const high = spanParts(max);
  if (!low.length) return `up to ${formatSpan(max)}`;
  if (low.length === 1 && high.length === 1 && low[0].word === high[0].word) {
    return `between ${low[0].count} and ${spanWords(high)}`;
  }
  return `between ${spanWords(low)} and ${spanWords(high)}`;
}

/** How coarse a value is, in the words the panel uses for it. */
const PRECISION_READS = {
  year: 'to the year',
  month: 'to the month',
  day: 'to the day',
  second: 'to the second',
  subsecond: 'to the fraction',
  mixed: 'unevenly',
};

/**
 * The pair as the inspector reads it out: one headline, one supporting clause and
 * the notes that stop the headline being read as more than it is.
 *
 * The wording lives here rather than in the component for the reason every other
 * count in this app states its own caveat: a figure printed bare is true and
 * misleading in the same breath.
 */
export function describePair(a, b) {
  const read = compareTimelineItems(a, b);
  if (!read) {
    return {
      ok: false,
      headline: 'Nothing to measure',
      detail: 'One of these two has no place on the UTC axis.',
      notes: [],
      extents: [],
    };
  }
  const notes = read.extents.map(({ item, extent }) =>
    extent.kind === 'duration'
      ? `${item.label} runs for ${formatSpan(extent.ms)}.`
      : `${item.label} is dated ${PRECISION_READS[extent.precision] ?? 'coarsely'}.`
  );
  if (read.order === 'overlap') {
    return {
      ok: true,
      headline: read.overlap > 0 ? `Overlapping by ${formatSpan(read.overlap)}` : 'Overlapping',
      detail: 'Either could come first, so these dates do not order them.',
      notes,
      extents: read.extents,
    };
  }
  const { min, max, stated, exact } = read.gap;
  const first = `${read.earlier.label} first`;
  if (exact) {
    return {
      ok: true,
      headline: stated === 0 ? 'At the same instant' : `${formatSpan(stated)} apart`,
      detail: stated === 0 ? 'Both are the same timestamp.' : first,
      notes,
      extents: read.extents,
    };
  }
  const range = formatSpanRange(min <= SECOND ? 0 : min, max);
  return {
    ok: true,
    // Capitalised here rather than in the phrase, which is also read mid-sentence.
    headline: `${range[0].toUpperCase()}${range.slice(1)} apart`,
    detail: first,
    notes: [`As written, ${formatSpan(stated)} apart.`, ...notes],
    extents: read.extents,
  };
}