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
21.3 KB
Raw Blame
/**
 * A personal layer followed over time, read at one moment.
 *
 * A tracked feature keeps its `states`, `{ at, geometry, status? }` or
 * `{ at, gone }`, sorted by `at` (`engine/layerediting.py`). Its own geometry is
 * its latest state, so a layer read with no moment (`at` null) is drawn as it is
 * now, exactly as before any of this. A moment is a day, `YYYY-MM-DD`, or a day
 * and a time, `YYYY-MM-DDTHH:MM`, on the layer's one clock, so moments compare as
 * strings and a day holds from its own start. `''` in a state means "since always".
 *
 * Three things are read off a moment, each a feature the map draws apart:
 *
 * - **the features as they stood then**: a state in force, or a plain feature
 *   between its first and last day, or always when it states none;
 * - **the trail** (`$trail`): where a feature stood in the state before, drawn
 *   dashed under it, so a front that moved shows where it moved from;
 * - **gains and losses** (`$change`): for an area, the ground it took and the
 *   ground it gave since a reference, the previous state or a chosen moment.
 *
 * Two more marks say how the moment relates to the features' own days:
 *
 * - **new** (`$new`): what appeared or changed on the moment's own day, which the
 *   map rings so a played layer shows what each day brought;
 * - **an event** (a group's `event` features: a strike, a clash) is there on its
 *   day and faded (`$fade`) after it, for good unless the layer gives it a window
 *   of days. A lasting thing (a position, a checkpoint) stays as it is. With no
 *   moment, events are read against the layer's last change.
 *
 * Nothing is interpolated. Between two states a feature is the first of them,
 * and a front that moved on the 12th did not drift there through the 11th.
 */
import polygonClipping from 'polygon-clipping';
import { dayNumber } from './layerDates.js';

/** The days an event stays when the analyst gives it a window: what the field offers first. */
export const EVENT_DAYS = 7;

const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
const MOMENT = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}))?$/;

/** Whether a layer row is followed over time right now. */
export function isTracked(row) {
  return Boolean(row?.editable && row?.track?.on);
}

/** A moment checked, or null: what a typed or picked value is let through as. */
export function moment(value) {
  const text = String(value ?? '').trim();
  const match = MOMENT.exec(text);
  if (!match) return null;
  const [, year, month, day, hour, minute] = match.map(Number);
  const date = new Date(Date.UTC(year, month - 1, day));
  if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return null;
  if (match[4] !== undefined && (hour > 23 || minute > 59)) return null;
  return text;
}

const CLOCKS = new Map();

/**
 * The moment it is on a layer's clock (`track`: `{ precision, zone }`): today, or
 * today and the minute on a layer dated to the minute. What a cursor nobody moved
 * reads, and what an edit is dated to there.
 */
export function momentNow(track, now = new Date()) {
  const zone = track?.zone || 'UTC';
  let clock = CLOCKS.get(zone);
  if (!clock) {
    try {
      clock = new Intl.DateTimeFormat('en-US', { timeZone: zone, hourCycle: 'h23', year: 'numeric',
        month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' });
    } catch {
      // a zone this browser does not know reads on UTC, as the backend refuses it
      return momentNow({ ...track, zone: 'UTC' }, now);
    }
    CLOCKS.set(zone, clock);
  }
  const part = Object.fromEntries(clock.formatToParts(now).map(({ type, value }) => [type, value]));
  const day = `${part.year}-${part.month}-${part.day}`;
  return track?.precision === 'time' ? `${day}T${part.hour}:${part.minute}` : day;
}

/** `12 Oct 2026`, or `12 Oct 2026 · 14:00` for a moment with a time. */
export function momentLabel(at) {
  const match = MOMENT.exec(String(at ?? ''));
  if (!match) return at === '' ? 'Always' : '';
  const day = `${Number(match[3])} ${MONTHS[Number(match[2]) - 1]} ${match[1]}`;
  return match[4] === undefined ? day : `${day} · ${match[4]}:${match[5]}`;
}

/** The state a feature is in at `at`: the last one written at or before it. */
export function inForce(states, at) {
  let found = null;
  for (const state of states ?? []) {
    if (state.at > at) break;
    found = state;
  }
  return found;
}

/** The states a feature has, or the one it implies before it has any. */
export function statesOf(feature) {
  const properties = feature?.properties ?? {};
  if (Array.isArray(properties.states) && properties.states.length) return properties.states;
  return [{ at: String(properties.date ?? ''), geometry: feature?.geometry,
    ...(properties.status ? { status: properties.status } : {}) }];
}

/** Whether a feature has a history of its own, beyond the day it states. */
export function hasHistory(feature) {
  return Array.isArray(feature?.properties?.states) && feature.properties.states.length > 0;
}

/**
 * The feature as it stood at `at`, or null when it was not there. Undated plain
 * features are always there; dated ones from their day through their last.
 */
export function stateAt(feature, at) {
  const properties = feature?.properties ?? {};
  if (!hasHistory(feature)) {
    const start = String(properties.date ?? '');
    const end = String(properties.date_end ?? '');
    if ((start && start > at) || (end && end < at.slice(0, 10))) return null;
    return feature;
  }
  const state = inForce(properties.states, at);
  if (!state || state.gone) return null;
  const { states, status, ...rest } = properties;
  return { ...feature, geometry: state.geometry,
    properties: { ...rest, ...(state.status ? { status: state.status } : {}) } };
}

/** The live state before the one in force at `at`, the trail's shape, or null. */
export function previousState(feature, at) {
  if (!hasHistory(feature)) return null;
  const states = feature.properties.states;
  const now = inForce(states, at);
  if (!now || now.gone) return null;
  const before = states.slice(0, states.indexOf(now)).filter((state) => !state.gone);
  return before.at(-1) ?? null;
}

/**
 * Every moment the layer changes at, sorted: each state of a tracked feature,
 * and the first and last day of the plain ones. What the cursor steps through.
 */
export function moments(collection) {
  const found = new Set();
  for (const feature of collection?.features ?? []) {
    const properties = feature?.properties ?? {};
    if (hasHistory(feature)) {
      for (const state of properties.states) if (state.at) found.add(state.at);
    } else {
      if (properties.date) found.add(String(properties.date));
      if (properties.date_end) found.add(String(properties.date_end));
    }
  }
  return [...found].sort();
}

/** The next moment after `at`, or the one before it (`direction` -1), or null. */
export function stepMoment(list, at, direction) {
  if (!list.length) return null;
  if (at === null || at === undefined) return direction < 0 ? list.at(-1) : null;
  if (direction > 0) return list.find((item) => item > at) ?? null;
  return list.findLast((item) => item < at) ?? null;
}

/** The parts of a polygon or multipolygon, as polygon-clipping reads them. */
function polygonsOf(geometry) {
  if (geometry?.type === 'Polygon') return [geometry.coordinates];
  if (geometry?.type === 'MultiPolygon') return geometry.coordinates;
  return null;
}

/** `first` less `second`, as a MultiPolygon, or null when nothing is left. */
function difference(first, second) {
  try {
    const parts = polygonClipping.difference(first, second);
    return parts.length ? { type: 'MultiPolygon', coordinates: parts } : null;
  } catch {
    // A ring that crosses itself is the analyst's drawing, and the map keeps it.
    return null;
  }
}

/**
 * What an area took and gave between `before` and `after`, each a geometry, as
 * up to two features `$change: 'gained' | 'lost'` carrying the area's properties.
 */
export function changes(feature, before, after) {
  const was = polygonsOf(before);
  const is = polygonsOf(after);
  if (!was && !is) return [];
  const out = [];
  const gained = is ? (was ? difference(is, was) : { type: 'MultiPolygon', coordinates: is }) : null;
  const lost = was ? (is ? difference(was, is) : { type: 'MultiPolygon', coordinates: was }) : null;
  if (gained) out.push({ type: 'Feature', geometry: gained, properties: { ...feature.properties, $change: 'gained' } });
  if (lost) out.push({ type: 'Feature', geometry: lost, properties: { ...feature.properties, $change: 'lost' } });
  return out;
}

/**
 * The layer as it stood at `at`, for the map to draw.
 *
 * `trail` adds the previous state of every feature that moved, `$trail`;
 * `since` adds what each area took and gave since then: `'previous'` for its
 * own state before, or a moment. `window` is how many days an event stays after
 * its own, null for good. Null `at` is the layer as last changed, where the
 * trail and the changes still read back from the latest state.
 *
 * A moment where every feature stands as at one read lately hands back that same
 * reading, so a map can tell nothing moved; a reading is never changed in place.
 */
export function asOf(collection, at, { trail = false, since = null, window = null } = {}) {
  const cursor = at ?? '￿';
  // the day events are read against: the moment's, or the layer's last change
  const today = dayNumber((at ?? moments(collection).at(-1) ?? '').slice(0, 10));
  if (!collection || typeof collection !== 'object') return read(collection, at, cursor, today, trail, since, window);
  // two moments where every feature stands as it stood are one reading, handed back as it was
  const phase = `${trail}|${since}|${window}|${phaseOf(collection.features ?? [], at, cursor, today, window)}`;
  let kept = readings.get(collection);
  if (!kept) readings.set(collection, (kept = new Map()));
  const known = kept.get(phase);
  if (known) {
    kept.delete(phase);
    kept.set(phase, known);
    return known;
  }
  const out = read(collection, at, cursor, today, trail, since, window);
  kept.set(phase, out);
  if (kept.size > KEPT_READINGS) kept.delete(kept.keys().next().value);
  return out;
}

/** The last few readings of each layer, by phase: a played or dragged day reads each phase once. */
const readings = new WeakMap();
const KEPT_READINGS = 4;

/**
 * Where each feature stands at the moment, as one key: its state in force (or, with
 * no history, whether it is there), and whether the day marks it new, fades it or
 * lets it go. Everything `asOf` draws follows from that, so an equal key is an
 * equal reading.
 */
function phaseOf(features, at, cursor, today, window) {
  const out = [];
  for (const feature of features) {
    const properties = feature?.properties ?? {};
    let standing;
    let began;
    if (hasHistory(feature)) {
      standing = -1;
      for (const [index, state] of properties.states.entries()) {
        if (state.at > cursor) break;
        standing = index;
      }
      began = standing >= 0 ? properties.states[standing].at : undefined;
    } else {
      standing = stateAt(feature, cursor) ? 1 : 0;
      began = properties.date;
    }
    let marks = 0;
    if (today !== null) {
      const day = dayNumber(String(began ?? '').slice(0, 10));
      if (at !== null && at !== undefined && day !== null && day === today) marks |= 1;
      if (properties.event) {
        const first = dayNumber(String(properties.date ?? '').slice(0, 10));
        if (first !== null && window !== null && today - first > window) marks |= 2;
        if (first !== null && today > first) marks |= 4;
      }
    }
    out.push(standing * 8 + marks);
  }
  return out.join(',');
}

function read(collection, at, cursor, today, trail, since, window) {
  const features = collection?.features ?? [];
  const out = [];
  const extras = [];
  for (const feature of features) {
    let standing = stateAt(feature, cursor);
    if (standing && today !== null) standing = marked(feature, standing, at, today, window);
    if (standing) out.push(standing);
    if (!hasHistory(feature) || (!trail && !since)) continue;
    const previous = previousState(feature, cursor);
    if (trail && standing && previous) {
      extras.push({ type: 'Feature', geometry: previous.geometry,
        properties: { ...standing.properties, ...(previous.status ? { status: previous.status } : {}), $trail: true } });
    }
    if (since === 'previous' && previous) {
      extras.push(...changes(feature, previous.geometry, standing?.geometry ?? null));
    } else if (since && since !== 'previous') {
      // What it was at the reference, or nothing when it was not there yet.
      const then = inForce(feature.properties.states, since);
      extras.push(...changes(feature, then && !then.gone ? then.geometry : null, standing?.geometry ?? null));
    }
  }
  // The trail and the changes go under the features they belong to.
  return { ...collection, features: [...extras, ...out] };
}

/**
 * A standing feature with what the day says of it: `$new` when it appeared or
 * changed on the moment's own day, `$fade` for an event past its day, or null for
 * an event past its window.
 */
function marked(feature, standing, at, today, window) {
  const properties = feature.properties ?? {};
  const began = hasHistory(feature) ? inForce(properties.states, at ?? '￿')?.at : properties.date;
  const day = dayNumber(String(began ?? '').slice(0, 10));
  const extra = {};
  if (at !== null && at !== undefined && day !== null && day === today) extra.$new = true;
  if (properties.event) {
    const first = dayNumber(String(properties.date ?? '').slice(0, 10));
    if (first !== null && window !== null && today - first > window) return null;
    if (first !== null && today > first) extra.$fade = true;
  }
  return Object.keys(extra).length ? { ...standing, properties: { ...standing.properties, ...extra } } : standing;
}

/** What a change of status brought; back to none is said as such, not as a state seen. */
const STATUS_SAID = { '': 'No damage', damaged: 'Damaged', destroyed: 'Destroyed' };

/** What one state brought, said against the live state before it. */
function brought(state, before, point, first) {
  if (state.gone) return 'Gone';
  if (first) return [state.at ? 'Appears' : 'Shown', state.status ? STATUS_SAID[state.status] : ''].filter(Boolean).join(' · ');
  if (!before) return 'Back';
  const said = [];
  if (JSON.stringify(state.geometry) !== JSON.stringify(before.geometry)) said.push(point ? 'Moved' : 'Reshaped');
  if ((state.status ?? '') !== (before.status ?? '')) said.push(STATUS_SAID[state.status ?? ''] ?? state.status);
  return said.join(' · ') || 'No change';
}

/**
 * One feature's history, as the sheet lists it: each state, its moment, what it
 * brought (`Appears`, `Moved`, `Damaged`, `Gone`…), and whether it is the one at
 * the cursor.
 */
export function lifeline(feature, cursor) {
  if (!hasHistory(feature)) return [];
  const now = cursor === null || cursor === undefined ? null : inForce(feature.properties.states, cursor);
  const live = feature.properties.states.filter((state) => !state.gone);
  const point = String(feature.geometry?.type ?? '').includes('Point');
  let before = null;
  return feature.properties.states.map((state, index) => {
    const row = {
      at: state.at,
      gone: Boolean(state.gone),
      status: state.status ?? '',
      what: brought(state, before, point, index === 0),
      current: now ? state === now : state === live.at(-1),
    };
    before = state.gone ? null : state;
    return row;
  });
}

/**
 * The history the sheet draws for one feature, with where a dated edit goes:
 * `editing` on the state it rewrites, or a `ghost` row at the cursor when it
 * starts a new one there. A plain feature reads as its one implied state, so a
 * change about to give it a history shows before it is made. `mode` is the
 * editor's: 'new' dates an edit at the cursor; 'fix' carries no date, and an
 * edit with none changes every day alike, so no row is marked.
 */
export function lifeRows(feature, cursor, mode = 'new') {
  const dated = hasHistory(feature);
  const rows = dated ? lifeline(feature, cursor)
    : [{ at: String(feature?.properties?.date ?? ''), gone: false, status: feature?.properties?.status ?? '',
      what: feature?.properties?.date ? 'Appears' : 'Shown', current: true }];
  const at = cursor ?? null;
  if (at === null || mode === 'fix' || !stateAt(feature, at)) return rows.map((row) => ({ editing: false, ghost: false, ...row }));
  const same = rows.find((row) => row.at === at);
  if (same) {
    same.editing = true;
  } else {
    rows.push({ at, gone: false, status: '', what: 'Next edit', current: false, ghost: true });
    rows.sort((first, second) => (first.at < second.at ? -1 : first.at > second.at ? 1 : 0));
  }
  return rows.map((row) => ({ editing: false, ghost: false, ...row }));
}

/**
 * A long history in a few rows: the first date, the last, and those round the
 * one the next edit goes to (or the one shown), the dates between folded into
 * `{ fold, at }` rows that count them. A history of `limit` rows or fewer, or a
 * run of one date, is never folded.
 */
export function foldRows(rows, { around = 1, limit = 7 } = {}) {
  if (rows.length <= limit) return rows;
  let focus = rows.findIndex((row) => row.ghost || row.editing);
  if (focus < 0) focus = rows.findIndex((row) => row.current);
  if (focus < 0) focus = rows.length - 1;
  const kept = new Set([0, rows.length - 1]);
  for (let index = focus - around; index <= focus + around; index += 1) kept.add(index);
  const shown = [];
  let run = [];
  const close = () => {
    if (run.length === 1) shown.push(run[0]);
    else if (run.length) shown.push({ fold: run.length, at: run[0].at });
    run = [];
  };
  rows.forEach((row, index) => {
    if (kept.has(index)) { close(); shown.push(row); } else run.push(row);
  });
  close();
  return shown;
}

/**
 * When a feature shows, as its sheet and its row in the list say it: `start`
 * ('' for always), `end` ('' while it is still there), `ends` saying whether the
 * end is the moment it is gone ('gone') or a plain feature's last day ('last'),
 * and how many changes it has between.
 */
export function spanOf(feature) {
  const properties = feature?.properties ?? {};
  if (!hasHistory(feature)) {
    const end = String(properties.date_end ?? '');
    return { start: String(properties.date ?? ''), end, ends: 'last', changes: 0, unknown: !end && !!properties.end_unknown };
  }
  const states = properties.states;
  const last = states.at(-1);
  return { start: states[0].at, end: last.gone ? last.at : '', ends: 'gone',
    changes: states.slice(1).filter((state) => !state.gone).length, unknown: !last.gone && !!properties.end_unknown };
}

/** `12 Oct`, with the year when it is not `year`, and the time on a moment that has one. */
export function shortMoment(at, year = new Date().getFullYear()) {
  const match = MOMENT.exec(String(at ?? ''));
  if (!match) return '';
  const day = `${Number(match[3])} ${MONTHS[Number(match[2]) - 1]}${Number(match[1]) === year ? '' : ` ${match[1]}`}`;
  return match[4] === undefined ? day : `${day} ${match[4]}:${match[5]}`;
}

/**
 * A feature's days in a few words, as its row in the list says them: `Always`,
 * `From 12 Oct`, `Until 20 Oct`, `12 Oct → 20 Oct`, `12 Oct → ?` when nobody
 * knows when it left, or the day alone for an event, which fades after it.
 */
export function spanLabel(span, { event = false, year } = {}) {
  const from = shortMoment(span.start, year);
  const to = shortMoment(span.end, year);
  if (event) return from || 'No day';
  if (from && to) return `${from} → ${to}`;
  if (span.unknown) return `${from || 'Always'} → ?`;
  if (from) return `From ${from}`;
  if (to) return `Until ${to}`;
  return 'Always';
}

/**
 * What a feature changed by date: the moment its shape first differs from the
 * one it first had, and the moment its status does, each '' when never. An edit
 * with no date changes every day alike, so it can only touch what never changed.
 */
export function changedBy(feature) {
  if (!hasHistory(feature)) return { shape: '', status: '' };
  const live = feature.properties.states.filter((state) => !state.gone);
  const [first, ...later] = live;
  const shape = later.find((state) => JSON.stringify(state.geometry) !== JSON.stringify(first.geometry))?.at ?? '';
  const status = later.find((state) => (state.status ?? '') !== (first.status ?? ''))?.at ?? '';
  return { shape, status };
}

/** Whether a feature appears, changes or leaves on the day of `at`. */
export function changesOn(feature, at) {
  if (at === null || at === undefined) return false;
  const day = at.slice(0, 10);
  return statesOf(feature).some((state) => state.at && state.at.slice(0, 10) === day)
    || (!hasHistory(feature) && String(feature?.properties?.date_end ?? '') === day);
}

/**
 * The features an editor works on at `at`: each tracked one in the shape and status it
 * had then, its history kept so it can be read and edited, and any feature that was
 * not there then marked `$absent`. Null `at` hands the features back as they are.
 */
export function seenAt(features, at) {
  if (at === null || at === undefined) return features;
  return features.map((feature) => {
    const standing = stateAt(feature, at);
    if (!standing) return { ...feature, properties: { ...feature.properties, $absent: true } };
    if (!hasHistory(feature)) return feature;
    const { status, ...rest } = feature.properties;
    return { ...feature, geometry: standing.geometry,
      properties: { ...rest, ...(standing.properties.status ? { status: standing.properties.status } : {}) } };
  });
}