The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
import { describe, expect, it } from 'vitest';
import { readFileSync } from 'node:fs';
import { MARKS, axisTicks, layoutTimelineItems } from './timeline.js';
import { TRACK_COLORS } from './timelineTracks.js';
import { PLATE_COLOURS } from './plate.js';
import {
PLATE_CATEGORIES,
PLATE_PLOT,
PLATE_TRACKS,
TIMELINE_PLATE,
fitLabel,
timelineDrawing,
timelineLegend,
timelinePlate,
trackColour,
} from './timelinePlate.js';
const css = readFileSync(new URL('../app.css', import.meta.url), 'utf8');
const FROM = Date.parse('2026-03-01T00:00:00Z');
const TO = Date.parse('2026-03-31T00:00:00Z');
const ITEMS = [
{
id: 't1', label: 'Convoy seen at the roundabout', category: 'statement',
earliest: '2026-03-04T09:00:00Z', latest: '2026-03-04T09:00:00Z',
shape: 'point', sortable: true, raw: '2026-03-04T09:00:00Z',
},
{
id: 't2', label: 'Checkpoint standing', category: 'statement',
earliest: '2026-03-10T00:00:00Z', latest: '2026-03-18T00:00:00Z',
shape: 'interval', approximate: true, sortable: true, raw: '2026-03-10/2026-03-18',
},
{
id: 't3', label: 'IMG_2291.jpg', category: 'media',
earliest: '2026-03-22T00:00:00Z', latest: '2026-03-22T23:59:59Z',
shape: 'point', zone: 'date-only', precision: 'day', sortable: true, raw: '2026-03-22',
},
];
function track(extra = {}) {
const items = extra.items ?? ITEMS;
return {
id: 'events',
label: 'Events',
categories: ['statement'],
total: items.length,
items,
layout: layoutTimelineItems(items, FROM, TO, PLATE_PLOT),
...extra,
};
}
function scene(extra = {}) {
return {
tracks: [track()],
ticks: axisTicks(FROM, TO, PLATE_PLOT),
minorTicks: [],
bands: [{ left: 0, width: 100, label: 'March 2026' }],
nowLeft: null,
scaleWord: 'Days',
clock: 'UTC',
...extra,
};
}
describe('the timeline palette on paper', () => {
it('keeps the category hues the light theme states', () => {
const plain = css.replace(/\/\*[\s\S]*?\*\//g, '');
const light = plain.slice(plain.indexOf(":root[data-theme='light']"));
for (const [category, hue] of Object.entries(PLATE_CATEGORIES)) {
const token = category === 'case_activity' ? 'activity' : category;
expect(light).toContain(`--timeline-${token}: ${hue}`);
}
});
it('steps the six track colours down for white paper', () => {
expect(Object.keys(PLATE_TRACKS)).toEqual(TRACK_COLORS);
for (const hue of Object.values(PLATE_TRACKS)) {
expect(hue).toMatch(/^#[0-9a-f]{6}$/);
// Readable as a mark on white: the screen's own annotation yellow is not.
const [r, g, b] = [1, 3, 5].map((at) => parseInt(hue.slice(at, at + 2), 16) / 255);
expect(0.2126 * r + 0.7152 * g + 0.0722 * b).toBeLessThan(0.55);
}
});
it('gives a coloured track its colour and an unset one its category', () => {
expect(trackColour({ color: 'blue', categories: ['statement'] })).toBe(PLATE_TRACKS.blue);
expect(trackColour({ categories: ['media'] })).toBe(PLATE_CATEGORIES.media);
expect(trackColour({})).toBe(PLATE_CATEGORIES.statement);
});
});
describe('serialising the timeline', () => {
it('draws the ruler, its scale and one lane block per track', () => {
const drawing = timelineDrawing(scene());
expect(drawing.tracks).toBe(1);
expect(drawing.body).toContain('March 2026');
expect(drawing.body).toContain('Days · UTC');
expect(drawing.body).toContain('>Events<');
expect(drawing.width).toBe(TIMELINE_PLATE.width);
expect(drawing.height).toBeGreaterThan(TIMELINE_PLATE.ruler);
});
it('turns a percentage into a place on the axis, never a viewport', () => {
const { body } = timelineDrawing(scene());
const plot = TIMELINE_PLATE.width - TIMELINE_PLATE.names - TIMELINE_PLATE.right;
const item = track().layout.items.find((entry) => entry.id === 't1');
const expected = Math.round((TIMELINE_PLATE.names + item.left * plot / 100) * 100) / 100;
expect(body).toContain(`cx="${expected}"`);
});
it('draws an instant, a period and the span a reduced date covers apart', () => {
const layout = track().layout;
const { body } = timelineDrawing(scene());
expect(layout.items.map((item) => item.mark)).toEqual(['point', 'bar', 'bracket']);
expect(body).toContain('Convoy seen at the roundabout'); // a point, with its name
expect(body).toContain('Checkpoint standing');
// the approximate period is a dashed bar, the day-only media a line with two stops
expect(body).toMatch(/<rect[^>]*stroke-dasharray="4 3"/);
expect(body).toMatch(/<rect[^>]*height="2"[^>]*fill-opacity="0.9"/);
const bracket = layout.items[2];
const stops = [...body.matchAll(/<line x1="([\d.]+)" y1="[\d.]+" x2="\1" y2="[\d.]+" stroke="#1f7669" stroke-width="2"/g)];
expect(stops.map((stop) => Number(stop[1]))).toEqual([
Math.round((TIMELINE_PLATE.names + bracket.left * PLATE_PLOT / 100) * 100) / 100,
Math.round((TIMELINE_PLATE.names + (bracket.left + bracket.width) * PLATE_PLOT / 100) * 100) / 100,
]);
});
it('draws a moment known only between two dates dashed, never as a period', () => {
const filmed = [{ ...ITEMS[1], id: 'w1', label: 'Filmed after the warehouse went up', approximate: false, time_role: 'occurred' }];
const layout = track({ items: filmed }).layout;
const { body } = timelineDrawing(scene({ tracks: [track({ items: filmed })] }));
expect(layout.items.map((item) => item.mark)).toEqual(['window']);
expect(body).toMatch(/<line[^>]*stroke-dasharray="4 3"/);
expect(body).not.toMatch(/<rect[^>]*height="8"/);
expect(body).toContain('between 10 Mar 2026 and 18 Mar 2026');
});
it('marks a proposal hollow, the way every surface draws one', () => {
const suggested = [{ ...ITEMS[0], status: 'suggested' }];
const { body } = timelineDrawing(scene({ tracks: [track({ items: suggested })] }));
expect(body).toContain(`fill="${PLATE_COLOURS.paper}"`);
});
it('says a track is folded instead of drawing lanes it is hiding', () => {
const { body, height } = timelineDrawing(scene({ tracks: [track({ collapsed: true })] }));
const open = timelineDrawing(scene());
expect(body).toContain('>folded<');
expect(body).not.toContain('Checkpoint standing');
expect(height).toBeLessThan(open.height);
});
it('counts what a lane could not hold rather than dropping it quietly', () => {
// Seven entries at one instant: the layout keeps six lanes and clusters the rest.
const crowded = Array.from({ length: 7 }, (_, index) => ({
...ITEMS[0], id: `c${index}`, label: `Entry ${index}`,
}));
const laid = layoutTimelineItems(crowded, FROM, TO, PLATE_PLOT);
const { body } = timelineDrawing(scene({ tracks: [track({ items: crowded, layout: laid })] }));
expect(laid.clusters.length).toBeGreaterThan(0);
expect(body).toContain(`+${laid.clusters[0].count}`);
});
it('says so when the window holds nothing', () => {
const { body } = timelineDrawing(scene({ tracks: [track({ items: [], layout: layoutTimelineItems([], FROM, TO, PLATE_PLOT) })] }));
expect(body).toContain('No entries in this window');
});
it('draws the present as a line only when it falls inside the window', () => {
expect(timelineDrawing(scene({ nowLeft: 40 })).body).toContain('>Now<');
expect(timelineDrawing(scene()).body).not.toContain('>Now<');
});
it('is laid out at its own width, which is the axis it draws', () => {
expect(PLATE_PLOT).toBe(TIMELINE_PLATE.width - TIMELINE_PLATE.names - TIMELINE_PLATE.right);
});
// Two entries stacked on the first day: a card's stem would cross one, so these
// tracks are read by their captions.
const crowd = ['k1', 'k2'].map((id) => ({
...ITEMS[0], id, label: id, earliest: '2026-03-01T06:00:00Z', latest: '2026-03-01T06:00:00Z',
}));
it('holds a label inside the room the layout gave its caption, not the room to the page edge', () => {
// The caption was placed where it covers nothing; written past its width it would
// run under whatever the layout kept it clear of.
const long = [{ ...ITEMS[0], label: 'A convoy of eleven trucks leaving the depot at dawn, then two more at noon' }, ...crowd];
const laid = layoutTimelineItems(long, FROM, TO, PLATE_PLOT);
const { body } = timelineDrawing(scene({ tracks: [track({ items: long, layout: laid })] }));
const written = body.match(/>(A convoy[^<]*)</)[1];
const caption = laid.items.find((item) => item.id === 't1').caption;
expect(written).not.toBe(long[0].label);
expect([...written].length * TIMELINE_PLATE.charWidth).toBeLessThanOrEqual(caption.width);
});
it('labels an entry at the far right leftwards, the way the screen does', () => {
const late = [{
...ITEMS[0], id: 'late', label: 'Last convoy',
earliest: '2026-03-30T12:00:00Z', latest: '2026-03-30T12:00:00Z',
raw: '2026-03-30T12:00:00Z',
}, ...crowd];
const laid = layoutTimelineItems(late, FROM, TO, PLATE_PLOT);
const { body } = timelineDrawing(scene({ tracks: [track({ items: late, layout: laid })] }));
expect(laid.items.find((item) => item.id === 'late').caption.side).toBe('left');
expect(body).toMatch(/<text[^>]*text-anchor="end"[^>]*>Last convoy</);
});
it('hangs cards from their marks when the track has the room, as the screen does', () => {
const laid = track().layout;
const { body } = timelineDrawing(scene());
expect(laid.cards).toBe(true);
expect(body).toContain('>4 Mar 2026, 09:00:00 UTC<');
expect(body).toMatch(new RegExp(`<rect[^>]*height="${MARKS.cardHeight}"`));
});
it('lists every entry under the drawing when some went without a caption, and says so', () => {
const dense = Array.from({ length: 5 }, (_, index) => ({
...ITEMS[0], id: `d${index}`, label: `Convoy sighting number ${index + 1}`,
earliest: `2026-03-1${index}T12:00:00Z`, latest: `2026-03-1${index}T12:00:00Z`,
raw: `2026-03-1${index}T12:00:00Z`,
}));
const items = [...dense, ...crowd];
const laid = layoutTimelineItems(items, FROM, TO, PLATE_PLOT);
expect(laid.labelled).toBeLessThan(items.length);
const page = timelinePlate({ meta: { view: 'Dense' }, ...scene({ tracks: [track({ items, layout: laid })] }) });
expect(page.svg).toContain(`labels shown for ${laid.labelled} of ${items.length}; the full list follows`);
expect(page.svg).toContain('Every entry in this window');
for (const entry of dense) expect(page.svg).toContain(`>${entry.label}<`);
// a page whose every entry is named needs no list
expect(timelinePlate({ meta: { view: 'March window' }, ...scene() }).svg).not.toContain('Every entry in this window');
});
it('keeps a bar that ends with the window inside the axis', () => {
// A short period carries a minimum width of its own, so one closing on the last hour
// of the window would cross the ruler it is being read against.
const tail = [{
id: 'tail', label: 'Standing watch', category: 'statement',
earliest: '2026-03-30T20:00:00Z', latest: '2026-03-31T00:00:00Z',
shape: 'interval', sortable: true, raw: '2026-03-30T20:00:00Z/2026-03-31T00:00:00Z',
}];
const laid = layoutTimelineItems(tail, FROM, TO, PLATE_PLOT);
const { body } = timelineDrawing(scene({ tracks: [track({ items: tail, layout: laid })] }));
const bar = body.match(/<rect[^>]*fill-opacity="0.3"[^>]*>/)[0];
const at = Number(bar.match(/ x="([\d.]+)"/)[1]);
const wide = Number(bar.match(/ width="([\d.]+)"/)[1]);
expect(wide).toBeGreaterThan(0);
expect(at + wide).toBeLessThanOrEqual(TIMELINE_PLATE.width - TIMELINE_PLATE.right);
});
});
describe('the timeline legend', () => {
it('names every track and the conventions the drawing uses', () => {
const { families, strokes } = timelineLegend([
track({ color: 'blue' }),
track({ id: 'media', label: 'Photos', groupLabel: 'Media', categories: ['media'] }),
]);
expect(families[0]).toEqual({ family: 'Events', colour: PLATE_TRACKS.blue });
expect(families[1].family).toBe('Media · Photos');
expect(strokes.map((entry) => entry.label)).toContain('approximate');
// A point is drawn as a mark, not as a stroke: the legend says what it shows.
expect(strokes[0]).toEqual({ label: 'an instant', shape: 'dot' });
});
});
describe('the timeline plate', () => {
it('states the window and the clock it was read on', () => {
const { svg } = timelinePlate({
meta: {
caseName: 'Bakhmut convoy', surface: 'Timeline', view: 'March window',
window: '1 – 31 Mar 2026', clock: 'Asia/Tokyo', at: '2026-08-13T20:10:00Z',
},
...scene(),
});
expect(svg).toContain('March window');
expect(svg).toContain('Fact time 1 – 31 Mar 2026 · Clock Asia/Tokyo');
expect(svg).toContain('an instant');
expect(svg).not.toMatch(/var\(--/);
});
it('counts what the window holds, since the page is one reading of it', () => {
const { svg } = timelinePlate({ meta: { view: 'March window' }, ...scene() });
expect(svg).toContain('1 track · 3 entries in this window');
});
});
describe('fitting a label', () => {
it('cuts to the room beside the marker, and gives up when there is none', () => {
expect(fitLabel('Checkpoint standing', 1000)).toBe('Checkpoint standing');
expect(fitLabel('Checkpoint standing', 30)).toBe('Chec…');
expect(fitLabel('Checkpoint standing', 3)).toBe('');
// Never through a surrogate pair: a plate holding half of one cannot be written.
expect(fitLabel('🏴🏴🏴🏴', 18)).toBe('🏴🏴…');
expect(fitLabel(null, 100)).toBe('');
});
});