Merge branch 'main' into sameh/photo-without-credit

This commit is contained in:
Sameh Khamis authored and GitHub committed 2026-11-10 14:23:06 -08:00
commit c068dc2290
110 files changed
+18169 -237

No files matched your search

+236
View File
@@ -0,0 +1,236 @@
// Event cards on the globe: a picture, the headline in two lines, and "age ·
// sources · sides", with the severity colour down the left edge and the
// event's marker as a badge on the picture. Painted on a canvas and handed to
// the world overlay as a thumbnail entry, so the overlay places them, keeps
// them apart and draws their leader to the marker, as it does CCTV cards.
//
// The picture is the publisher's own (hotlinked, never copied, credited on
// the card); until it loads, or without one, the card shows a tile in the
// severity colour with the category icon.
import { WORLD_OVERLAY_STYLE } from '../../overlays/worldOverlayTokens.js';
import { NEWS_SEVERITY } from './model.js';
import { paintMarker } from './sprites.js';
/** Card size in CSS pixels. */
export const CARD_W = 168;
export const CARD_H = 136;
const PAD = 4;
const PIC_H = 84;
const EDGE = 3;
const SCALE = 2; // canvas pixels per CSS pixel
const TITLE_FONT = '600 11px Inter, "Noto Sans Arabic", system-ui, sans-serif';
const META_FONT = '9px "JetBrains Mono", "Noto Sans Arabic", monospace';
const CREDIT_FONT = '8px Inter, "Noto Sans Arabic", system-ui, sans-serif';
// The map shows about ten cards plus the clicked one; a few more stay ready
// for a pan back. The least recently drawn card goes, and its picture with it.
export const MAX_CARDS = 24;
const pictures = new Map(); // url → {image, state: 'loading'|'ok'|'failed', waiters}
const cards = new Map(); // event id → {canvas, key, view, look, pic}, oldest first
/** Forget a picture no kept card shows any more. */
function releasePicture(url) {
if (!url || [...cards.values()].some((card) => card.view.image === url))
return;
const entry = pictures.get(url);
if (!entry) return;
entry.waiters.clear();
entry.image.onload = entry.image.onerror = null;
pictures.delete(url);
}
function picture(url, onLoad) {
let entry = pictures.get(url);
if (!entry) {
const image = new Image();
// No referrer: the publisher sees a plain image request, as from a link preview.
image.referrerPolicy = 'no-referrer';
image.decoding = 'async';
entry = { image, state: 'loading', waiters: new Set() };
pictures.set(url, entry);
image.onload = () => {
entry.state = 'ok';
for (const done of entry.waiters) done();
entry.waiters.clear();
};
image.onerror = () => {
entry.state = 'failed';
entry.waiters.clear();
};
image.src = url;
}
if (entry.state === 'loading' && onLoad) entry.waiters.add(onLoad);
return entry;
}
function roundRect(ctx, x, y, w, h, r) {
ctx.beginPath();
ctx.moveTo(x + r, y);
ctx.arcTo(x + w, y, x + w, y + h, r);
ctx.arcTo(x + w, y + h, x, y + h, r);
ctx.arcTo(x, y + h, x, y, r);
ctx.arcTo(x, y, x + w, y, r);
ctx.closePath();
}
/** `text` in at most `lines` lines of `width`, the last cut with an ellipsis. */
export function wrapLines(ctx, text, width, lines) {
const words = String(text || '')
.split(/\s+/)
.filter(Boolean);
const out = [];
let line = '';
for (let i = 0; i < words.length; i++) {
const next = line ? `${line} ${words[i]}` : words[i];
if (ctx.measureText(next).width <= width || !line) {
line = next;
continue;
}
out.push(line);
line = words[i];
if (out.length === lines - 1) {
line = words.slice(i).join(' ');
break;
}
}
if (line) out.push(line);
const last = out.length - 1;
if (last >= 0 && ctx.measureText(out[last]).width > width) {
let cut = out[last];
while (cut && ctx.measureText(`${cut}…`).width > width)
cut = cut.slice(0, -1);
out[last] = `${cut.trimEnd()}…`;
}
return out.slice(0, lines);
}
/** Cover-fit an image into a box. */
function drawCover(ctx, image, x, y, w, h) {
const iw = image.naturalWidth || image.width;
const ih = image.naturalHeight || image.height;
if (!iw || !ih) return;
const s = Math.max(w / iw, h / ih);
const sw = w / s;
const sh = h / s;
ctx.drawImage(image, (iw - sw) / 2, (ih - sh) / 2, sw, sh, x, y, w, h);
}
function paint(canvas, view, look, pic) {
const ctx = canvas.getContext('2d');
ctx.setTransform(SCALE, 0, 0, SCALE, 0, 0);
ctx.clearRect(0, 0, CARD_W, CARD_H);
const color = (NEWS_SEVERITY[look.severity] || NEWS_SEVERITY[0]).color;
roundRect(ctx, 0.5, 0.5, CARD_W - 1, CARD_H - 1, WORLD_OVERLAY_STYLE.radius);
ctx.fillStyle = WORLD_OVERLAY_STYLE.selectedBackground;
ctx.fill();
ctx.strokeStyle = WORLD_OVERLAY_STYLE.border;
ctx.lineWidth = 1;
ctx.stroke();
// Severity down the left edge.
ctx.save();
roundRect(ctx, 0.5, 0.5, CARD_W - 1, CARD_H - 1, WORLD_OVERLAY_STYLE.radius);
ctx.clip();
ctx.fillStyle = color;
ctx.fillRect(0, 0, EDGE, CARD_H);
ctx.restore();
const px = PAD + EDGE;
const pw = CARD_W - px - PAD;
ctx.save();
roundRect(ctx, px, PAD, pw, PIC_H, 3);
ctx.clip();
if (pic?.state === 'ok') {
try {
drawCover(ctx, pic.image, px, PAD, pw, PIC_H);
} catch {
pic.state = 'failed';
}
}
if (pic?.state !== 'ok') {
// No picture: a plain glass tile with the event's marker.
ctx.fillStyle = WORLD_OVERLAY_STYLE.background;
ctx.fillRect(px, PAD, pw, PIC_H);
ctx.fillStyle = 'rgba(255, 255, 255, 0.04)';
ctx.fillRect(px, PAD, pw, PIC_H);
paintMarker(ctx, look, px + pw / 2, PAD + PIC_H / 2, 34);
}
ctx.restore();
// The event's marker as a badge, so the card reads with the map.
if (pic?.state === 'ok') paintMarker(ctx, look, px + 13, PAD + 13, 18);
// The picture's publisher, always named on it.
if (pic?.state === 'ok' && view.credit) {
ctx.font = CREDIT_FONT;
const w = Math.min(pw - 30, ctx.measureText(view.credit).width + 8);
ctx.fillStyle = 'rgba(0, 0, 0, 0.6)';
ctx.fillRect(px + pw - w, PAD + PIC_H - 12, w, 12);
ctx.fillStyle = WORLD_OVERLAY_STYLE.title;
ctx.textBaseline = 'middle';
ctx.fillText(
wrapLines(ctx, view.credit, w - 8, 1)[0] || '',
px + pw - w + 4,
PAD + PIC_H - 6,
);
}
ctx.textBaseline = 'alphabetic';
ctx.fillStyle = WORLD_OVERLAY_STYLE.title;
ctx.font = TITLE_FONT;
wrapLines(ctx, view.title, pw, 2).forEach((line, i) =>
ctx.fillText(line, px, PAD + PIC_H + 14 + i * 13),
);
ctx.fillStyle = WORLD_OVERLAY_STYLE.detail;
ctx.font = META_FONT;
ctx.fillText(wrapLines(ctx, view.meta, pw, 1)[0] || '', px, CARD_H - PAD - 2);
}
/**
* The canvas of an event's card, one per event: a change in what it shows
* (the age in its meta line ticks by the minute) repaints the same canvas.
* `onChange` runs when its picture arrives and the canvas has been repainted
* (ask the scene for a frame).
* @returns {HTMLCanvasElement|null} null where there is no canvas
*/
export function eventCard(id, view, look, onChange) {
const key = `${look.severity}|${look.category}|${look.rim}|${view.image || ''}|${view.credit || ''}|${view.title}|${view.meta}`;
let card = cards.get(id);
if (card) {
// Most recently drawn last.
cards.delete(id);
cards.set(id, card);
if (card.key === key) return card.canvas;
} else {
const canvas = globalThis.document?.createElement?.('canvas');
if (
!canvas?.getContext?.('2d') ||
typeof globalThis.Path2D !== 'function' ||
typeof globalThis.Image !== 'function'
)
return null;
canvas.width = CARD_W * SCALE;
canvas.height = CARD_H * SCALE;
card = { canvas, key: null, view: {}, look, pic: null };
cards.set(id, card);
while (cards.size > MAX_CARDS) {
const [oldest, gone] = cards.entries().next().value;
cards.delete(oldest);
releasePicture(gone.view.image);
}
}
const previous = card.view.image;
card.key = key;
card.view = view;
card.look = look;
const shown = card;
card.pic = view.image
? picture(view.image, () => {
if (cards.get(id) !== shown || shown.view.image !== view.image) return;
paint(shown.canvas, shown.view, shown.look, shown.pic);
onChange?.();
})
: null;
if (previous && previous !== view.image) releasePicture(previous);
paint(card.canvas, view, look, card.pic);
return card.canvas;
}
+120
View File
@@ -0,0 +1,120 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { MAX_CARDS, eventCard } from './cards.js';
const look = { severity: 3, category: 'strike', rim: 'confirmed', size: 20 };
const view = (extra = {}) => ({
title: 'Strike on Kharkiv',
meta: '10 min · 6 sources · UA, RU',
image: 'https://a.test/p.jpg',
credit: 'A',
...extra,
});
// Node has no canvas: a 2D context that accepts every call, and an Image that
// records what was asked for.
function fakeBrowser(t) {
const saved = {
document: globalThis.document,
Path2D: globalThis.Path2D,
Image: globalThis.Image,
};
const images = [];
const ctx = new Proxy(
{},
{
get: (_target, name) =>
name === 'measureText'
? (text) => ({ width: String(text).length * 5 })
: name === 'createLinearGradient'
? () => ({ addColorStop() {} })
: () => {},
set: () => true,
},
);
let canvases = 0;
globalThis.document = {
createElement: () => {
canvases++;
return { getContext: () => ctx };
},
};
globalThis.Path2D = class {};
globalThis.Image = class {
constructor() {
images.push(this);
}
};
t.after(() => {
for (const [name, value] of Object.entries(saved))
if (value === undefined) delete globalThis[name];
else globalThis[name] = value;
});
return { images, canvases: () => canvases };
}
test('a card keeps one canvas per event while its age ticks', (t) => {
const browser = fakeBrowser(t);
const first = eventCard('ev-a', view(), look);
assert.ok(first);
// The meta line's minute-level age changes: the same canvas, repainted.
const later = eventCard('ev-a', view({ meta: '11 min · 6 sources' }), look);
assert.equal(later, first);
assert.equal(browser.canvases(), 1);
// One picture request for the event, however often it is drawn.
assert.equal(browser.images.length, 1);
// Its picture arriving repaints and asks for a frame once; a card with no
// picture never does.
let frames = 0;
const pictured = eventCard(
'ev-b',
view({ image: 'https://b.test/p.jpg' }),
look,
() => frames++,
);
assert.ok(pictured);
browser.images.at(-1).onload();
assert.equal(frames, 1);
assert.ok(eventCard('ev-c', view({ image: null }), look));
});
test('the card cache is bounded and evicts pictures with their cards', (t) => {
const browser = fakeBrowser(t);
const kept = eventCard('keep', view({ image: 'https://k.test/0.jpg' }), look);
for (let i = 0; i < MAX_CARDS * 3; i++) {
eventCard(`ev-${i}`, view({ image: `https://p.test/${i}.jpg` }), look);
// A card drawn every frame stays: the least recently drawn goes first.
assert.equal(
eventCard('keep', view({ image: 'https://k.test/0.jpg' }), look),
kept,
);
}
const requested = browser.images.length;
// The first event was evicted with its picture: drawing it again paints a
// new canvas and asks for the picture anew.
const again = eventCard(
'ev-0',
view({ image: 'https://p.test/0.jpg' }),
look,
);
assert.ok(again);
assert.equal(browser.images.length, requested + 1);
// Evicted pictures are let go: their load handlers are cleared.
assert.equal(browser.images[1].onload, null);
// The recent ones are still cached.
const recent = MAX_CARDS * 3 - 1;
eventCard(
`ev-${recent}`,
view({ image: `https://p.test/${recent}.jpg` }),
look,
);
assert.equal(browser.images.length, requested + 1);
});
test('without a canvas no card is made and nothing is cached', (t) => {
fakeBrowser(t);
globalThis.document = { createElement: () => ({ getContext: () => null }) };
assert.equal(eventCard('none', view(), look), null);
globalThis.document = undefined;
assert.equal(eventCard('none', view(), look), null);
});
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+826
View File
@@ -0,0 +1,826 @@
// Pure presentation model for the news layer: severity, category glyphs,
// attestation, marker looks and placement, the feed's filters and paging, and
// the event cards the News panel and the globe show. No Cesium, no DOM.
import { getLocale, msg, t, tn } from '../../i18n/index.js';
export const NEWS_LAYER_ID = 'news';
export const NEWS_OVERLAY_SOURCE_ID = 'news';
export const NEWS_PICK_PREFIX = 'news:';
export const NEWS_FEED_PAGE = 60;
export const NEWS_MAP_LIMIT = 500;
/** News is real time only: nothing older than a day is shown anywhere. */
export const NEWS_WINDOW_MS = 24 * 3_600_000;
/**
* The window a server serves, in ms: its `windowHours` (a whole number of
* hours up to 24; a host may serve fewer), else the full day.
*/
export function newsWindowMs(hours) {
return Number.isInteger(hours) && hours >= 1 && hours <= 24
? hours * 3_600_000
: NEWS_WINDOW_MS;
}
/** The windows the News panel offers, longest first. */
export const NEWS_WINDOW_CHOICES = Object.freeze([24, 12, 6, 3, 1]);
/**
* The windows offered under a server's own window of `maxHours`: that window
* itself, then each shorter choice.
*/
export function newsWindowChoices(maxHours) {
const cap = newsWindowMs(maxHours) / 3_600_000;
return [cap, ...NEWS_WINDOW_CHOICES.filter((hours) => hours < cap)];
}
// A publish time this far ahead of the clock is skew, not a future story
// (as data/regionalNewsWindow.js).
const NEWS_CLOCK_SKEW_MS = 15 * 60_000;
/** At most this many reports are kept in the feed list, newest first. */
export const NEWS_FEED_MAX = 600;
// Above this camera height the layer shows one beacon per hotspot; below it
// (or once a hotspot is chosen) the outlines and individual reports.
export const NEWS_DETAIL_MAX_HEIGHT_M = 2_500_000;
// "In view": reports near the view centre, only once the camera is low enough
// for "here" to mean a region, read again when it settles in a new cell.
// Near is inside the area the server names there (a country, a large
// country's state, a disputed area), else, at sea, within the radius.
export const NEWS_IN_VIEW_MAX_HEIGHT_M = 3_000_000;
export const NEWS_IN_VIEW_RADIUS_KM = 500;
export const NEWS_IN_VIEW_LIMIT = 12;
/** The Local section lists at most this many reports near the view centre. */
export const NEWS_LOCAL_LIMIT = 40;
/**
* The News panel's sections: Conflicts (the hotspots' significant news, on the
* map whenever the layer is on) and Local (everything near the view centre,
* on the map while the section is chosen).
*/
export const NEWS_SECTIONS = Object.freeze(['conflicts', 'local']);
export const NEWS_SETTLE_MS = 800;
export const NEWS_CELL_DEG = 0.5;
/** A feed card's click flies the camera to this height over the event. */
export const NEWS_FOCUS_HEIGHT_M = 150_000;
// Minor news (a broad outlet's prices, sport, health) is left out unless asked for.
export const NEWS_RELEVANT = 'core,related';
const SOURCE_LABEL = msg('Source');
const DISPUTED = msg('Disputed: {name}');
const VIA = msg('via {source}');
const MEDIA_LABELS = { video: msg('Video'), photo: msg('Photos') };
const CLAIMED_BY = msg('Claimed by {who}');
const CLAIMED = msg('Claimed');
const UNCONFIRMED = msg('Not yet confirmed by others');
const REPORTED_BY_SIDE = msg('Reported by {side} sources');
const REPORTED_BY_SIDES = msg('Reported by {sides}');
const SIDE_SOURCES = msg('{side} sources');
const OFFICIAL = msg('Official');
const OFFICIAL_AFFILIATIONS = new Set(['military', 'state']);
const ATTESTATION = {
'both-sides': msg('Reported by both sides'),
independent: msg('Independently reported'),
single: msg('Single source'),
};
const NEUTRAL_SIDES = Object.freeze({
intl: msg('International'),
independent: msg('Independent'),
unknown: msg('Unattributed'),
external: msg('Outside party'),
});
/**
* Short chip names for the curated hotspots; the API's own English name is
* the fallback for any other.
*/
export const NEWS_HOTSPOT_LABELS = Object.freeze({
'ua-ru-war': msg('Ukraine–Russia'),
'israel-gaza-lebanon': msg('Israel–Gaza–Lebanon'),
'iran-hormuz': msg('Iran–Hormuz'),
yemen: msg('Yemen–Red Sea'),
'sudan-war': msg('Sudan'),
sahel: msg('Sahel'),
elsewhere: msg('Elsewhere'),
// Core's own news (no news server): the world is one hotspot.
worldwide: msg('Worldwide'),
});
/** A hotspot's chip label in the interface language. */
export function hotspotLabel(hotspot) {
const key = NEWS_HOTSPOT_LABELS[hotspot?.id];
if (key) return t(key);
return hotspot?.catchAll ? t(NEWS_HOTSPOT_LABELS.elsewhere) : hotspot?.name;
}
/** A country's name in the interface language, from its ISO code. */
export function countryName(code) {
if (!code) return '';
try {
return (
new Intl.DisplayNames([getLocale(), 'en'], { type: 'region' }).of(code) ||
code
);
} catch {
return code;
}
}
const AREA_IN_COUNTRY = msg('{region}, {country}');
/**
* The Local section's area in the interface language: a country by its code,
* a state with its country, a disputed area by its own name only.
*/
export function areaLabel(area) {
if (!area) return '';
if (area.kind === 'disputed' || !area.country) return area.name;
if (area.kind === 'country') return countryName(area.country);
return t(AREA_IN_COUNTRY, {
region: area.name,
country: countryName(area.country),
});
}
/** Label for a disputed area on the map: its name, marked as disputed. */
export const disputedLabel = (area) => t(DISPUTED, { name: area.name });
// A category is told by its icon (a 16-unit SVG path, filled or stroked). On
// the map and in the feed colour is severity (NEWS_SEVERITY), never the type
// of event or a side.
export const NEWS_CATEGORIES = Object.freeze({
strike: {
label: msg('Strike'),
icon: 'M8 0.8 L9.6 5.2 L14.2 3.6 L11.2 7.6 L15.2 10.6 L10.3 10.6 L8 15.2 L5.7 10.6 L0.8 10.6 L4.8 7.6 L1.8 3.6 L6.4 5.2 Z',
solid: true,
},
// A threat on its way (a drone's course, an air-raid alert): nothing has
// hit yet. Not a physical event, so never a picture card.
alert: {
label: msg('Alert'),
icon: 'M1.5 8 H11.5 M8 4.5 L11.5 8 L8 11.5 M14.5 3.5 V12.5',
},
'air-defence': {
label: msg('Air defence'),
icon: 'M8 1.5 L13.5 3.5 V8 C13.5 11.3 10.8 13.4 8 14.6 C5.2 13.4 2.5 11.3 2.5 8 V3.5 Z M8 4.5 V11',
},
ground: {
label: msg('Ground fighting'),
icon: 'M3 13 L12 4 M8.5 3.5 H12.5 V7.5 M13 13 L4 4 M3.5 7.5 V3.5 H7.5',
},
casualties: {
label: msg('Casualties'),
icon: 'M6.2 2 H9.8 V6.2 H14 V9.8 H9.8 V14 H6.2 V9.8 H2 V6.2 H6.2 Z',
solid: true,
},
humanitarian: {
label: msg('Humanitarian'),
icon: 'M8 2.5 L14.5 13.5 H1.5 Z M8 2.5 V13.5',
},
infrastructure: {
label: msg('Infrastructure'),
icon: 'M9.2 1 L3.2 9 H7.6 L6.6 15 L12.8 6.8 H8.4 Z',
solid: true,
},
disaster: {
label: msg('Disaster'),
icon: 'M1.5 6.5 C3.5 4.5 5.5 4.5 7.5 6.5 S11.5 8.5 14.5 6.5 M1.5 10.5 C3.5 8.5 5.5 8.5 7.5 10.5 S11.5 12.5 14.5 10.5',
},
protest: {
label: msg('Protest'),
icon: 'M2.5 6.2 V9.8 H5 L12.5 13.2 V2.8 L5 6.2 Z',
},
political: {
label: msg('Political'),
icon: 'M2 14 H14 M2.5 5.5 H13.5 M8 1.8 L14 4.8 H2 Z M4.2 6.5 V12 M8 6.5 V12 M11.8 6.5 V12',
},
// Business, trade and industry: a national feed's news in Local.
economy: {
label: msg('Economy'),
icon: 'M2 13.5 H14 M2.5 11 L6 7.5 L8.5 9.5 L13.5 4.5 M10.5 4.5 H13.5 V7.5',
},
other: {
label: msg('Other'),
icon: 'M8 4.5 A3.5 3.5 0 1 0 8.01 4.5 Z',
solid: true,
},
});
// Severity 0–3, in colours GEV already uses: its dim and primary text, the
// military layers' amber and the Cockpit's emergency red. They are drawn on
// a dark disc, so from minor up lightness falls as severity rises and the
// ramp still reads under colour blindness and in greyscale.
export const NEWS_SEVERITY = Object.freeze([
{ label: msg('No physical event'), color: '#7c878d' },
{ label: msg('Minor incident'), color: '#e8eaed' },
{ label: msg('Significant'), color: '#ffb800' },
{ label: msg('Major'), color: '#ff4444' },
]);
/** The feed's default floor: significant and major events. */
export const NEWS_DEFAULT_MIN_SEVERITY = 2;
const PHYSICAL = new Set([
'strike',
'air-defence',
'ground',
'casualties',
'infrastructure',
'disaster',
]);
export const categoryStyle = (category) =>
NEWS_CATEGORIES[category] || NEWS_CATEGORIES.other;
export const categoryLabel = (category) => t(categoryStyle(category).label);
/** Party codes (UA, RU, IL…) are shown as-is; neutral sides are translated. */
export const sideLabel = (side) =>
Object.hasOwn(NEUTRAL_SIDES, side) ? t(NEUTRAL_SIDES[side]) : side;
/**
* A report's severity, 0–3: the server's (the local model's reading, else
* its rules, raised to its event's), or a fallback from the category.
*/
export function reportSeverity(report) {
const own = Number.isInteger(report?.severity) ? report.severity : null;
const event = Number.isInteger(report?.event?.severity)
? report.event.severity
: null;
if (own === null && event === null)
return PHYSICAL.has(report?.category) ? 1 : 0;
return Math.max(own ?? 0, event ?? 0);
}
export const severityStyle = (report) => NEWS_SEVERITY[reportSeverity(report)];
export const severityLabel = (report) => t(severityStyle(report).label);
/** When a report (or its event) was last heard of, in ms; NaN when unknown. */
const lastHeard = (report) =>
Date.parse(report?.event?.lastAt || report?.publishedAt || '');
/**
* Whether a time is inside the window (the last 24 hours unless the server
* serves fewer; the only news shown); one more than 15 minutes ahead of the
* clock is not.
*/
function inWindow(value, now, windowMs = NEWS_WINDOW_MS) {
const at = Date.parse(value || '');
return (
Number.isFinite(at) &&
now - at <= windowMs &&
at - now <= NEWS_CLOCK_SKEW_MS
);
}
/** Whether a report is inside the window (the only news shown). */
export function withinNewsWindow(
report,
now = Date.now(),
windowMs = NEWS_WINDOW_MS,
) {
return inWindow(report?.publishedAt, now, windowMs);
}
/** The event's one-report-per-side list, inside the last 24 hours only. */
const recentSides = (report, now) =>
(report?.event?.sides || []).filter((s) => inWindow(s.publishedAt, now));
/**
* How a report or its event is attested, as a chip: `claimed` (someone's
* claim, named where known), `confirmed` (both sides, or an independent
* source), `side` (one party's own press), `single` (one report), or null.
*/
export function attestation(report) {
const event = report?.event;
const status = event?.status || (report?.claim ? 'claimed' : null);
if (status === 'claimed') {
const who = event?.claimedBy || report?.claim?.by;
return {
kind: 'claimed',
label: who ? t(CLAIMED_BY, { who }) : t(CLAIMED),
};
}
if (status === 'both-sides' || status === 'independent')
return { kind: 'confirmed', label: t(ATTESTATION[status]) };
if (status === 'side' && event.reportedSide)
return {
kind: 'side',
label: t(REPORTED_BY_SIDE, { side: sideLabel(event.reportedSide) }),
};
if (status === 'single')
return { kind: 'single', label: t(ATTESTATION.single) };
return null;
}
/**
* The attestation chip under a report. An official channel's own post is
* already marked Official: "Claimed by" itself would read as doubt about an
* alert. It says only that nobody else has reported it yet, and nothing for
* an alert, which is the channel's own notice.
*/
function ownClaimChip(report) {
const chip = attestation(report);
if (
chip?.kind !== 'claimed' ||
!OFFICIAL_AFFILIATIONS.has(report.affiliation)
)
return chip;
const who = report.event?.claimedBy || report.claim?.by;
if (who && who !== report.sourceName && who !== report.publisher) return chip;
return report.category === 'alert'
? null
: { kind: 'claimed', label: t(UNCONFIRMED) };
}
// The map card is a label, not a reader: long headlines are cut.
export const NEWS_CARD_TITLE_MAX = 90;
/** A headline cut at a word to fit `max` characters. */
export function shortTitle(title, max = NEWS_CARD_TITLE_MAX) {
const text = String(title || '');
if (text.length <= max) return text;
const cut = text.slice(0, max - 1);
const word = cut.lastIndexOf(' ');
return `${word > max * 0.6 ? cut.slice(0, word) : cut}…`;
}
/** The media a post carries ("Video", "Photos"), translated. */
export function mediaLabels(report) {
return (report?.media || [])
.map((m) => (MEDIA_LABELS[m] ? t(MEDIA_LABELS[m]) : ''))
.filter(Boolean);
}
/**
* How long ago, in few words: "now" under a minute, "N min" under an hour,
* "N h" under a day. Older is never shown; it reads
* "24 h".
*/
export function ageWords(at, now = Date.now()) {
const minutes = Math.max(0, Math.floor((now - Date.parse(at)) / 60_000));
if (!Number.isFinite(minutes)) return '';
if (minutes < 1) return t('now', { context: 'age' });
if (minutes < 60) return t('{minutes} min', { minutes });
return t('{hours} h', { hours: Math.min(24, Math.floor(minutes / 60)) });
}
/**
* How a report's marker looks: colour = severity, icon = category, rim =
* attestation (`confirmed` solid, `claimed` dashed, else thin), size =
* sources, opacity = age (fading to 45 % over a day).
*/
export function markerStyle(report, now = Date.now()) {
const kind = attestation(report)?.kind;
const at = lastHeard(report);
const hours = Number.isFinite(at) ? Math.max(0, (now - at) / 3_600_000) : 0;
return {
category: Object.hasOwn(NEWS_CATEGORIES, report?.category)
? report.category
: 'other',
severity: reportSeverity(report),
rim: kind === 'confirmed' || kind === 'claimed' ? kind : 'thin',
size: eventPixelSize(report?.event?.size),
alpha: Math.max(0.45, 1 - (0.55 * Math.min(hours, 24)) / 24),
};
}
function hash(text) {
let h = 2166136261;
for (let i = 0; i < text.length; i++) {
h ^= text.charCodeAt(i);
h = Math.imul(h, 16777619);
}
return h >>> 0;
}
/**
* Trend glyph for a hotspot: ▲/▼ when the last 24 h differ from the 24 h
* before by more than a fifth, nothing when flat or without a prior day.
*/
export function hotspotTrend(last24h, prev24h) {
if (!(prev24h > 0)) return '';
if (last24h > prev24h * 1.2) return '▲';
if (last24h < prev24h * 0.8) return '▼';
return '';
}
/** Beacon size in pixels: grows with the square root of daily activity. */
export const beaconPixelSize = (last24h) =>
Math.round(Math.min(26, 10 + Math.sqrt(Math.max(0, last24h)) * 1.4));
/** Marker size for an event: grows with the number of distinct sources. */
export function eventPixelSize(sources = 1) {
return Math.round(
// No smaller than 24: the category icon is half the disc and unreadable
// below that.
Math.min(36, 24 + 3 * Math.log2(Math.max(1, Number(sources) || 1))),
);
}
// An event several sources report within the last few hours gets a halo.
export const NEWS_PRESSING_SOURCES = 5;
const PRESSING_MS = 3 * 3_600_000;
/** Whether an event is fresh and widely reported, or fresh and major. */
export function isPressing(report, now = Date.now()) {
const event = report?.event;
const fresh = now - lastHeard(report) <= PRESSING_MS;
return Boolean(
fresh &&
((event && event.size >= NEWS_PRESSING_SOURCES) ||
reportSeverity(report) === 3),
);
}
// The big events stand as picture cards over their marker: several
// sources, and major or pressing.
export const NEWS_CARD_LIMIT = 10;
export const NEWS_CARD_MIN_SOURCES = 2;
/** Whether an event gets a card on the map: physical events only, not statements. */
export function isCardEvent(report, now = Date.now()) {
return Boolean(
report?.event?.size >= NEWS_CARD_MIN_SOURCES &&
PHYSICAL.has(report.category) &&
(reportSeverity(report) === 3 || isPressing(report, now)),
);
}
/** The card events among `reports`, most severe, most reported and newest first. */
export function cardEvents(reports, now = Date.now(), limit = NEWS_CARD_LIMIT) {
return reports
.filter((r) => r.pins?.length && isCardEvent(r, now))
.sort(
(a, b) =>
reportSeverity(b) - reportSeverity(a) ||
b.event.size - a.event.size ||
(b.event.lastAt || '').localeCompare(a.event.lastAt || ''),
)
.slice(0, limit);
}
/** The distinct sides an event was reported by in the last day, lead first. */
function eventSides(report, now) {
const sides = recentSides(report, now).map((s) => s.side);
return [...new Set(sides.length ? sides : [report?.side].filter(Boolean))];
}
/**
* "Reported by UA sources · RU sources", or '' when no side is known; an
* unattributed side is left out.
*/
export function sidesLine(report, now = Date.now()) {
const sides = eventSides(report, now).filter((side) => side !== 'unknown');
if (!sides.length) return '';
if (sides.length === 1)
return t(REPORTED_BY_SIDE, { side: sideLabel(sides[0]) });
return t(REPORTED_BY_SIDES, {
sides: sides
.map((side) => t(SIDE_SOURCES, { side: sideLabel(side) }))
.join(' · '),
});
}
/**
* The event's picture, the publisher named, and its clip when it has one. The
* panel shows it for any event; the globe's picture cards are for events of
* two or more sources (isCardEvent).
*/
export function eventPicture(report) {
const image = report?.event?.image;
if (!image) return null;
return {
url: image.url,
credit: image.publisher || '',
...(image.video ? { video: image.video } : {}),
};
}
/** What an event's picture card on the globe shows. */
export function cardView(report, now = Date.now()) {
const event = report.event;
const sides = eventSides(report, now).map(sideLabel);
// A globe card's picture needs two or more sources, as the card does.
const picture =
report?.event?.size >= NEWS_CARD_MIN_SOURCES ? eventPicture(report) : null;
return {
title: report.titleEn || report.title,
meta: [
ageWords(event?.lastAt || report.publishedAt, now),
tn(event?.size || 1, '{count} source', '{count} sources'),
sides.slice(0, 3).join(', ') + (sides.length > 3 ? '…' : ''),
]
.filter(Boolean)
.join(' · '),
image: picture?.url || null,
credit: picture?.credit || '',
};
}
/** "Source: host ↗" line for a report's card; the card opens the article. */
export function sourceLinkLabel(url) {
let host = '';
try {
host = new URL(url).hostname.replace(/^www\./, '');
} catch {
return '';
}
return `${t(SOURCE_LABEL)}: ${host} ↗`;
}
/**
* "via GDELT Project": the service a report was read through, which asks to
* be credited where its reports show; '' when the server names none.
*/
export function attributionLabel(report) {
return report?.attribution ? t(VIA, { source: report.attribution }) : '';
}
/** The places a report is pinned at, joined, or null. */
function placeLine(report) {
return (
(report.pins?.length ? report.pins : [report.geo])
.map((p) => p?.place)
.filter(Boolean)
.join(' · ') || null
);
}
/**
* One event card in the News panel: picture,
* headline, a mono meta line (severity, category, place, sources, age, the
* service it came through), the sides line, then attestation and media chips. Labels and colours are
* resolved here so the panel imports no layer code.
*/
export function feedCardView(report, now = Date.now()) {
const severity = reportSeverity(report);
const style = categoryStyle(report.category);
const size = report.event?.size || 1;
const translated = Boolean(report.titleEn && report.titleEn !== report.title);
return {
id: report.id,
url: report.url,
title: translated ? report.titleEn : report.title,
// The local model's English headline over a post in another language:
// the original stays beside it.
original: translated ? report.title : null,
snippet: report.snippet,
severity,
severityLabel: t(NEWS_SEVERITY[severity].label),
color: NEWS_SEVERITY[severity].color,
icon: style.icon,
solid: Boolean(style.solid),
category: categoryLabel(report.category),
place: placeLine(report),
placedByModel: Boolean(report.geo?.byModel),
mappable: Boolean(report.pins?.length),
sources: tn(size, '{count} source', '{count} sources'),
age: ageWords(report.event?.lastAt || report.publishedAt, now),
publisher: report.publisher,
via: attributionLabel(report),
sides: sidesLine(report, now),
sourceLink: sourceLinkLabel(report.url),
picture: eventPicture(report),
chips: [
// An official channel speaking for itself (a ministry, the armed
// forces, a press service), not an outlet that quotes one.
OFFICIAL_AFFILIATIONS.has(report.affiliation)
? { kind: 'official', label: t(OFFICIAL) }
: null,
ownClaimChip(report),
...mediaLabels(report).map((label) => ({ kind: 'media', label })),
].filter(Boolean),
// The event's first report from each other side, under the lead.
others: recentSides(report, now)
.slice(1)
.map((s) => ({
side: sideLabel(s.side),
publisher: s.publisher,
title: s.title,
url: s.url,
})),
};
}
/**
* Whether a report is placed no closer than a country: it has no spot of its
* own on the map.
*/
export const countryOnly = (report) =>
report.pins?.length > 0 &&
report.pins.every((pin) => pin.precision === 'country');
/**
* Country-only reports as one group per country, in the order met:
* `{key, place, lat, lon, count}`. They are drawn as one badge with a count,
* not as markers piled on the country's centre.
*/
export function countryGroups(reports) {
const groups = new Map();
for (const report of reports) {
if (!countryOnly(report)) continue;
const { lat, lon, place } = report.pins[0];
const key = place || `${lat.toFixed(1)},${lon.toFixed(1)}`;
const group = groups.get(key);
if (group) group.count += 1;
else groups.set(key, { key, place: place || '', lat, lon, count: 1 });
}
return [...groups.values()];
}
/**
* Marker position for a report. Many reports name the same city and would
* stack on one centroid, so each is spread on a small deterministic ring
* (about 1.5 km for a place, 6 km for a region, 28 km for a country) to stay
* individually clickable. The spread is display-only; cards show the place.
*/
export function reportMarkerPosition(report, pin = 0) {
const { lat, lon, precision } = report.pins?.[pin] || report.geo;
const h = hash(pin ? `${report.id}~${pin}` : report.id);
const angle = ((h % 3600) / 3600) * 2 * Math.PI;
const radiusDeg =
(precision === 'country' ? 0.25 : precision === 'region' ? 0.055 : 0.014) *
(0.35 + ((h >>> 12) % 65) / 100);
return {
lat: lat + radiusDeg * Math.sin(angle),
lon: lon + (radiusDeg * Math.cos(angle)) / Math.cos((lat * Math.PI) / 180),
};
}
/**
* Merge a page into the feed, newest first, one row per report id, keeping
* only the window and at most `max` rows (a long session does not grow
* the list). `mode` 'head' refreshes the top and keeps the older cursor;
* 'append' adds an older page and takes its cursor; 'replace' starts over.
* A head page that has older pages behind it and shares no row with the list
* left a gap (more than a page arrived since), so it starts over too.
*/
export function mergeFeedPage(
feed,
page,
mode,
now = Date.now(),
max = NEWS_FEED_MAX,
windowMs = NEWS_WINDOW_MS,
) {
const byId = new Map();
if (mode === 'head' && page.nextBefore && feed.items.length) {
const held = new Set(feed.items.map((item) => item.id));
if (!page.reports.some((item) => held.has(item.id))) mode = 'replace';
}
const items =
mode === 'replace'
? page.reports
: mode === 'append'
? [...feed.items, ...page.reports]
: [...page.reports, ...feed.items];
for (const item of items)
if (!byId.has(item.id) && withinNewsWindow(item, now, windowMs))
byId.set(item.id, item);
return {
items: [...byId.values()]
.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt))
.slice(0, max),
nextBefore:
mode === 'head' && feed.items.length ? feed.nextBefore : page.nextBefore,
};
}
/** Normalised filters; anything unknown falls back to its default. */
export function normalizeFilters(next = {}, hotspots = [], previous = {}) {
const merged = { ...previous, ...next };
const hotspot = hotspots.some((h) => h.id === merged.hotspot)
? merged.hotspot
: 'all';
const category = Object.hasOwn(NEWS_CATEGORIES, merged.category)
? merged.category
: 'all';
const minSeverity =
Number.isInteger(merged.minSeverity) &&
merged.minSeverity >= 0 &&
merged.minSeverity <= 3
? merged.minSeverity
: NEWS_DEFAULT_MIN_SEVERITY;
return {
hotspot,
category,
minSeverity,
section: NEWS_SECTIONS.includes(merged.section)
? merged.section
: 'conflicts',
// A shorter window than the server's; null shows all it serves.
hours: NEWS_WINDOW_CHOICES.includes(merged.hours) ? merged.hours : null,
};
}
/** Whether a report passes the filters the server does not apply. */
export function passesFilters(
report,
filters,
now = Date.now(),
windowMs = NEWS_WINDOW_MS,
) {
return (
withinNewsWindow(report, now, windowMs) &&
reportSeverity(report) >= filters.minSeverity
);
}
/** Whether a report belongs on the map under the current filters. */
export function visibleOnMap(
report,
filters,
now = Date.now(),
windowMs = NEWS_WINDOW_MS,
) {
return (
(filters.hotspot === 'all' ||
(report.hotspotIds || [report.hotspotId]).includes(filters.hotspot)) &&
(filters.category === 'all' || report.category === filters.category) &&
passesFilters(report, filters, now, windowMs)
);
}
/**
* The filters Local applies: every hotspot and every severity, near the view
* centre; the category and the window still hold.
*/
export const localFilters = (filters) => ({
...filters,
hotspot: 'all',
minSeverity: 0,
});
/** API query for the Conflicts feed under the current filters: the window only. */
export function feedQueryFor(filters, extra = {}) {
return {
events: true,
today: true,
relevance: NEWS_RELEVANT,
hotspot: filters.hotspot,
category: filters.category === 'all' ? '' : filters.category,
limit: NEWS_FEED_PAGE,
...extra,
};
}
/** The half-degree cell a point lies in, as a key. */
export function viewCell({ lat, lon }) {
return `${Math.floor(lat / NEWS_CELL_DEG)}:${Math.floor(lon / NEWS_CELL_DEG)}`;
}
/** Great-circle distance in kilometres. */
export function distanceKm(a, b) {
const rad = Math.PI / 180;
const dLat = (b.lat - a.lat) * rad;
const dLon = (b.lon - a.lon) * rad;
const s =
Math.sin(dLat / 2) ** 2 +
Math.cos(a.lat * rad) * Math.cos(b.lat * rad) * Math.sin(dLon / 2) ** 2;
return 2 * 6371 * Math.asin(Math.min(1, Math.sqrt(s)));
}
function inRing(ring, { lat, lon }) {
let inside = false;
for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
const [xi, yi] = ring[i];
const [xj, yj] = ring[j];
if (
yi > lat !== yj > lat &&
lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi
)
inside = !inside;
}
return inside;
}
/** Whether a point lies in an outline's polygons (`{outer, holes}`). */
export function inPolygons(polygons, point) {
return polygons.some(
({ outer, holes }) =>
inRing(outer, point) && !holes.some((hole) => inRing(hole, point)),
);
}
/**
* The reports near `centre` that pass the filters, newest first: any pin
* inside `area` (outline polygons), or without one within
* NEWS_IN_VIEW_RADIUS_KM. Newest, not most severe: an area's own news often
* carries no severity, and the area's fighting would otherwise crowd it out.
*/
export function reportsInView(
reports,
centre,
filters,
now = Date.now(),
limit = NEWS_IN_VIEW_LIMIT,
windowMs = NEWS_WINDOW_MS,
area = null,
) {
if (!centre) return [];
const near = area?.length
? (pin) => inPolygons(area, pin)
: (pin) => distanceKm(pin, centre) <= NEWS_IN_VIEW_RADIUS_KM;
return reports
.filter(
(r) =>
passesFilters(r, filters, now, windowMs) &&
(filters.category === 'all' || r.category === filters.category) &&
r.pins?.some(near),
)
.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt))
.slice(0, limit);
}
+765
View File
@@ -0,0 +1,765 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
normalizeFeedPayload,
normalizeHotspotsPayload,
normalizeOutlinePayload,
} from './records.js';
import {
NEWS_IN_VIEW_RADIUS_KM,
ageWords,
areaLabel,
beaconPixelSize,
cardEvents,
cardView,
distanceKm,
eventPixelSize,
feedCardView,
feedQueryFor,
hotspotLabel,
hotspotTrend,
inPolygons,
isPressing,
markerStyle,
mergeFeedPage,
newsWindowChoices,
newsWindowMs,
normalizeFilters,
passesFilters,
reportMarkerPosition,
reportSeverity,
reportsInView,
sidesLine,
sourceLinkLabel,
viewCell,
visibleOnMap,
withinNewsWindow,
} from './model.js';
import { newsFeedQuery } from './source.js';
const NOW = Date.parse('2026-10-28T10:00:00Z');
const report = (id, publishedAt, extra = {}) => ({
id,
title: `Report ${id}`,
url: `https://example.com/${id}`,
publishedAt,
publisher: 'Example',
side: 'UA',
category: 'strike',
hotspotIds: ['ua'],
geo: {
lat: 50,
lon: 36,
place: 'Kharkiv',
precision: 'city',
mappable: true,
},
pins: [
{ lat: 50, lon: 36, place: 'Kharkiv', precision: 'city', mappable: true },
],
...extra,
});
const event = (extra = {}) => ({
status: 'both-sides',
size: 6,
severity: 3,
lastAt: '2026-10-28T09:30:00Z',
sides: [
{
side: 'UA',
title: 'a',
url: 'https://a.test/',
publisher: 'A',
publishedAt: '2026-10-28T09:00:00Z',
},
{
side: 'RU',
title: 'b',
url: 'https://b.test/',
publisher: 'B',
publishedAt: '2026-10-28T09:20:00Z',
},
],
image: { url: 'https://a.test/p.jpg', publisher: 'A' },
...extra,
});
test('payloads are validated record by record; empty and malformed payloads', () => {
const hotspots = normalizeHotspotsPayload({
hotspots: [
{
id: 'ua',
name: 'UA',
bbox: [22, 44, 42, 56],
parties: ['UA', 'RU', '<x>'],
counts: { last24h: 3 },
},
{ id: 'bad', name: 'Bad', bbox: [42, 44, 22, 56] },
{ id: '../x', name: 'Bad id', bbox: [22, 44, 42, 56] },
],
ingest: { lastRunAt: '2026-10-28T10:00:00Z' },
});
assert.deepEqual(
hotspots.hotspots.map((h) => [h.id, h.parties, h.last24h]),
[['ua', ['UA', 'RU'], 3]],
);
assert.equal(hotspots.lastRunAt, '2026-10-28T10:00:00.000Z');
assert.equal(normalizeHotspotsPayload({}), null);
assert.equal(normalizeHotspotsPayload(null), null);
assert.deepEqual(normalizeHotspotsPayload({ hotspots: [] }).hotspots, []);
const feed = normalizeFeedPayload({
reports: [
{
id: 'r_1',
title: ' Strike on Kharkiv ',
url: 'https://x.test/a',
publishedAt: '2026-10-28T09:00:00Z',
geo: { lat: 50, lon: 36, mappable: true },
media: ['video', 'video', 'audio'],
event: { size: 3, image: { url: 'http://x.test/p.jpg' } },
},
{
id: 'r_2',
title: 'Bad link',
url: 'javascript:alert(1)',
publishedAt: '2026-10-28T09:00:00Z',
},
{
id: 'r_3',
title: 'Bad geo',
url: 'https://user:[email protected]/c',
publishedAt: '2026-10-28T09:00:00Z',
},
{
id: 'r_4',
title: 'Off the globe',
url: 'https://x.test/d',
publishedAt: '2026-10-28T09:00:00Z',
geo: { lat: 200, lon: 36 },
},
],
nextBefore: '2026-10-28T08:00:00Z',
});
assert.deepEqual(
feed.reports.map((r) => [r.id, r.title, Boolean(r.geo), r.pins.length]),
[
['r_1', 'Strike on Kharkiv', true, 1],
['r_4', 'Off the globe', false, 0],
],
);
assert.deepEqual(feed.reports[0].media, ['video']);
// A picture must be HTTPS on the publisher's site.
assert.equal(feed.reports[0].event.image, null);
assert.equal(feed.nextBefore, '2026-10-28T08:00:00.000Z');
assert.equal(normalizeFeedPayload({ reports: 'x' }), null);
assert.deepEqual(normalizeFeedPayload({ reports: [] }), {
reports: [],
nextBefore: null,
});
});
test("an event's clip is kept only as an HTTPS file a browser plays itself", () => {
const clip = (video) =>
normalizeFeedPayload({
reports: [
{
id: 'r',
title: 'T',
url: 'https://x.test/r',
publishedAt: '2026-10-28T09:00:00Z',
event: {
size: 1,
image: { url: 'https://cdn.test/p.jpg', publisher: 'P', video },
},
},
],
}).reports[0].event.image.video;
assert.equal(
clip('https://cdn.test/v.mp4?token=a'),
'https://cdn.test/v.mp4?token=a',
);
assert.equal(clip('https://cdn.test/v.webm'), 'https://cdn.test/v.webm');
assert.equal(clip('http://cdn.test/v.mp4'), undefined);
assert.equal(clip('https://cdn.test/v.m3u8'), undefined);
assert.equal(clip(undefined), undefined);
});
test('outlines keep valid rings, borders and named disputed areas', () => {
const ring = [
[30, 45],
[31, 45],
[31, 46],
];
const outline = normalizeOutlinePayload({
polygons: [{ outer: ring, holes: [[[0, 0]]] }, { outer: [[1, 2]] }],
borders: [ring, 'x'],
disputed: [
{
name: 'Crimea',
kind: 'held',
heldBy: 'RU',
claimedBy: 'UA',
rings: [ring],
},
{ name: 'No rings', rings: [] },
{ name: 'Odd kind', kind: 'zzz', heldBy: 'nope', rings: [ring] },
],
});
assert.equal(outline.polygons.length, 1);
assert.deepEqual(outline.polygons[0].holes, []);
assert.equal(outline.borders.length, 1);
assert.deepEqual(
outline.disputed.map((d) => [d.name, d.kind, d.heldBy]),
[
['Crimea', 'held', 'RU'],
['Odd kind', 'held', null],
],
);
assert.deepEqual(normalizeOutlinePayload(null), {
polygons: [],
borders: [],
disputed: [],
area: null,
});
// Indonesia's 208 islands are all kept.
const islands = Array.from({ length: 208 }, () => ({ outer: ring }));
assert.equal(
normalizeOutlinePayload({ polygons: islands }).polygons.length,
208,
);
});
test('a point outline names its area, and Local keeps to it', () => {
const box = [
[35, 48],
[37, 48],
[37, 50.5],
[35, 50.5],
];
const { area, polygons } = normalizeOutlinePayload({
area: { key: 'US-TX', name: 'Texas', kind: 'region', country: 'US' },
polygons: [{ outer: box, holes: [] }],
});
assert.deepEqual(area, {
key: 'US-TX',
name: 'Texas',
kind: 'region',
country: 'US',
});
assert.equal(areaLabel(area), 'Texas, United States');
assert.equal(
areaLabel({ ...area, kind: 'country', country: 'UA' }),
'Ukraine',
);
// A disputed area is named as itself, never as either side's.
assert.equal(
areaLabel({ key: 'disputed:Crimea', name: 'Crimea', kind: 'disputed' }),
'Crimea',
);
assert.equal(normalizeOutlinePayload({ area: { key: 'X' } }).area, null);
const at = (id, lat, lon) =>
report(id, '2026-10-28T09:00:00Z', {
pins: [{ lat, lon, mappable: true }],
});
const reports = [at('inside', 50, 36), at('beyond', 49, 39)];
const filters = normalizeFilters({ minSeverity: 0 });
const centre = { lat: 49, lon: 36 };
const now = Date.parse('2026-10-28T10:00:00Z');
const ids = (area) =>
reportsInView(reports, centre, filters, now, 10, undefined, area).map(
(r) => r.id,
);
// Within 500 km both; inside the area only the one.
assert.deepEqual(ids(null), ['inside', 'beyond']);
assert.deepEqual(ids(polygons), ['inside']);
assert.ok(inPolygons(polygons, { lat: 49, lon: 36 }));
assert.ok(!inPolygons([{ outer: box, holes: [box] }], { lat: 49, lon: 36 }));
});
test('feed pages merge newest first without duplicates', () => {
const a = report('a', '2026-10-28T10:00:00Z');
const b = report('b', '2026-10-28T09:00:00Z');
const c = report('c', '2026-10-28T08:00:00Z');
let feed = mergeFeedPage(
{ items: [] },
{ reports: [a, b], nextBefore: 'B' },
'replace',
NOW,
);
assert.deepEqual(
[feed.items.map((r) => r.id), feed.nextBefore],
[['a', 'b'], 'B'],
);
feed = mergeFeedPage(
feed,
{ reports: [b, c], nextBefore: null },
'append',
NOW,
);
assert.deepEqual(
[feed.items.map((r) => r.id), feed.nextBefore],
[['a', 'b', 'c'], null],
);
const newer = report('n', '2026-10-28T11:00:00Z');
feed = mergeFeedPage(
{ ...feed, nextBefore: 'C' },
{ reports: [newer, a], nextBefore: 'X' },
'head',
NOW + 3_600_000,
);
assert.deepEqual(
[feed.items.map((r) => r.id), feed.nextBefore],
[['n', 'a', 'b', 'c'], 'C'],
);
assert.deepEqual(
mergeFeedPage({ items: [] }, { reports: [], nextBefore: null }, 'replace'),
{ items: [], nextBefore: null },
);
});
test('a head page that does not reach the rows held starts the list over', () => {
const held = report('h', '2026-10-28T06:00:00Z');
const fresh = report('n', '2026-10-28T09:30:00Z');
// More than a page arrived since the last refresh (a suspended tab): the
// reports between this page and the rows held are behind its cursor.
const feed = mergeFeedPage(
{ items: [held], nextBefore: 'OLD' },
{ reports: [fresh], nextBefore: 'NEW' },
'head',
NOW,
);
assert.deepEqual(
[feed.items.map((r) => r.id), feed.nextBefore],
[['n'], 'NEW'],
);
});
test('the feed list keeps only the last 24 hours and at most its cap', () => {
const fresh = report('f', '2026-10-28T09:00:00Z');
const stale = report('s', '2026-10-27T09:00:00Z');
const ahead = report('x', '2026-10-28T11:00:00Z');
// A long session: yesterday's rows already held fall out on the next merge.
const feed = mergeFeedPage(
{ items: [stale], nextBefore: 'S' },
{ reports: [fresh, ahead], nextBefore: 'F' },
'head',
NOW,
);
assert.deepEqual(
feed.items.map((r) => r.id),
['f'],
);
const many = Array.from({ length: 30 }, (_, i) =>
report(`r${i}`, new Date(NOW - (i + 1) * 60_000).toISOString()),
);
const capped = mergeFeedPage(
{ items: [] },
{ reports: many, nextBefore: null },
'replace',
NOW,
10,
);
assert.equal(capped.items.length, 10);
assert.equal(capped.items[0].id, 'r0');
assert.equal(capped.items.at(-1).id, 'r9');
// Everything outside the window: an empty list, not an error.
assert.deepEqual(
mergeFeedPage(
{ items: [] },
{ reports: [stale], nextBefore: null },
'replace',
NOW,
).items,
[],
);
});
test('filters default to significant news and map to a last-24-hours query', () => {
const hotspots = [{ id: 'ua' }, { id: 'me' }];
const filters = normalizeFilters(
{ hotspot: 'ua', category: 'nope', minSeverity: 9 },
hotspots,
);
assert.deepEqual(filters, {
hotspot: 'ua',
category: 'all',
minSeverity: 2,
section: 'conflicts',
hours: null,
});
assert.equal(
normalizeFilters({ section: 'local' }, hotspots).section,
'local',
);
assert.equal(
normalizeFilters({ section: 'nope' }, hotspots).section,
'conflicts',
);
assert.equal(normalizeFilters({ hours: 6 }, hotspots).hours, 6);
assert.equal(normalizeFilters({ hours: 5 }, hotspots).hours, null);
assert.equal(normalizeFilters({ minSeverity: 0 }, hotspots).minSeverity, 0);
assert.equal(normalizeFilters({ hotspot: 'gone' }, hotspots).hotspot, 'all');
assert.equal(
newsFeedQuery(
feedQueryFor(filters, { before: '2026-10-28T08:00:00.000Z' }),
),
'hotspot=ua&before=2026-10-28T08%3A00%3A00.000Z&limit=60&relevance=core%2Crelated&today=1&events=1',
);
// The Conflicts feed reads the same whichever section is chosen.
assert.equal(
newsFeedQuery(feedQueryFor({ ...filters, section: 'local' })),
newsFeedQuery(feedQueryFor(filters)),
);
});
test('only the last 24 hours pass, and the severity floor applies', () => {
const filters = normalizeFilters();
const fresh = report('f', '2026-10-28T09:00:00Z', { severity: 2 });
const minor = report('m', '2026-10-28T09:00:00Z', { severity: 1 });
const old = report('o', '2026-10-27T09:00:00Z', { severity: 3 });
assert.equal(withinNewsWindow(fresh, NOW), true);
assert.equal(withinNewsWindow(old, NOW), false);
assert.equal(withinNewsWindow({ publishedAt: 'x' }, NOW), false);
// Clock skew up to 15 min ahead passes; further ahead is not news yet.
const skew = report('k', '2026-10-28T10:14:00Z');
const future = report('z', '2026-10-28T10:16:00Z');
assert.equal(withinNewsWindow(skew, NOW), true);
assert.equal(withinNewsWindow(future, NOW), false);
assert.deepEqual(
[fresh, minor, old]
.filter((r) => passesFilters(r, filters, NOW))
.map((r) => r.id),
['f'],
);
assert.equal(visibleOnMap(minor, { ...filters, minSeverity: 0 }, NOW), true);
assert.equal(visibleOnMap(fresh, { ...filters, hotspot: 'me' }, NOW), false);
});
test('ageWords says now, minutes or hours', () => {
assert.equal(ageWords('2026-10-28T09:59:30Z', NOW), 'now');
assert.equal(ageWords('2026-10-28T09:55:00Z', NOW), '5 min');
assert.equal(ageWords('2026-10-28T07:10:00Z', NOW), '2 h');
assert.equal(ageWords('2026-10-26T07:10:00Z', NOW), '24 h');
assert.equal(ageWords('not a date', NOW), '');
});
test('markers spread deterministically near their place; source link line', () => {
const r = report('r_spread', '2026-10-28T10:00:00Z');
const p1 = reportMarkerPosition(r);
assert.deepEqual(reportMarkerPosition(r), p1);
assert.ok(Math.abs(p1.lat - 50) < 0.02 && Math.abs(p1.lon - 36) < 0.04);
assert.notDeepEqual(
reportMarkerPosition(report('r_other', r.publishedAt)),
p1,
);
assert.equal(
sourceLinkLabel('https://www.reliefweb.int/report/x'),
'Source: reliefweb.int ↗',
);
assert.equal(sourceLinkLabel('not a url'), '');
});
test('beacons carry a focus, a size by activity and a trend only against a prior day', () => {
const { hotspots } = normalizeHotspotsPayload({
hotspots: [
{
id: 'a',
name: 'A',
bbox: [20, 40, 40, 50],
focus: { lat: 45, lon: 30 },
counts: { last24h: 120, prev24h: 80 },
},
{
id: 'b',
name: 'B',
bbox: [20, 40, 40, 50],
focus: { lat: 80, lon: 30 },
},
],
});
assert.deepEqual(
hotspots.map((h) => h.focus),
[
{ lat: 45, lon: 30 },
{ lat: 45, lon: 30 },
],
);
assert.equal(hotspotTrend(120, 80), '▲');
assert.equal(hotspotTrend(50, 80), '▼');
assert.equal(hotspotTrend(85, 80), '');
assert.equal(hotspotTrend(40, 0), '');
assert.equal(beaconPixelSize(0), 10);
assert.equal(beaconPixelSize(10_000), 26);
assert.equal(
hotspotLabel({ id: 'ua-ru-war', name: 'Russia–Ukraine war' }),
'Ukraine–Russia',
);
assert.equal(hotspotLabel({ id: 'new-one', name: 'New one' }), 'New one');
assert.equal(
hotspotLabel({ id: 'x', name: 'X', catchAll: true }),
'Elsewhere',
);
assert.equal(
hotspotLabel({ id: 'worldwide', name: 'Worldwide', catchAll: true }),
'Worldwide',
);
});
test('marker style: severity fill, attestation rim, size by sources, fading with age', () => {
const r = report('r_style', '2026-10-28T10:00:00Z', {
severity: 2,
event: event({
status: 'claimed',
size: 4,
lastAt: '2026-10-28T10:00:00Z',
}),
});
const fresh = markerStyle(r, NOW);
assert.equal(fresh.severity, 3); // the event's, when higher than the report's
assert.equal(fresh.rim, 'claimed');
assert.equal(fresh.size, eventPixelSize(4));
// The icon is half the disc: no marker is too small to read it.
assert.equal(eventPixelSize(1), 24);
assert.equal(eventPixelSize(1000), 36);
assert.equal(fresh.alpha, 1);
assert.equal(markerStyle(r, NOW + 48 * 3_600_000).alpha, 0.45);
assert.equal(reportSeverity({ category: 'political' }), 0);
assert.equal(reportSeverity({ category: 'strike' }), 1);
});
test('picture cards: physical, two or more sources, major or pressing, at most ten', () => {
const big = report('big', '2026-10-28T09:30:00Z', { event: event() });
const statement = report('st', '2026-10-28T09:30:00Z', {
category: 'political',
event: event(),
});
const lone = report('lone', '2026-10-28T09:30:00Z', {
event: event({ size: 1 }),
});
const stale = report('stale', '2026-10-28T01:00:00Z', {
event: event({ severity: 2, lastAt: '2026-10-28T01:00:00Z' }),
});
assert.equal(isPressing(big, NOW), true);
assert.deepEqual(
cardEvents([statement, lone, stale, big], NOW).map((r) => r.id),
['big'],
);
const many = Array.from({ length: 14 }, (_, i) =>
report(`m${i}`, '2026-10-28T09:30:00Z', { event: event() }),
);
assert.equal(cardEvents(many, NOW).length, 10);
const view = cardView(big, NOW);
assert.equal(view.image, 'https://a.test/p.jpg');
assert.equal(view.credit, 'A');
assert.equal(view.meta, '30 min · 6 sources · UA, RU');
assert.equal(cardView(lone, NOW).image, null);
});
test('feed cards: headline, meta parts, sides and chips', () => {
const r = report('fc', '2026-10-28T09:00:00Z', {
title: 'Удар по Харкову',
titleEn: 'Strike on Kharkiv',
affiliation: 'military',
media: ['video', 'photo'],
geo: { lat: 50, lon: 36, place: 'Kharkiv', mappable: true, byModel: true },
event: event({ lastAt: '2026-10-28T09:50:00Z' }),
});
const view = feedCardView(r, NOW);
assert.equal(view.title, 'Strike on Kharkiv');
assert.equal(view.original, 'Удар по Харкову');
assert.equal(view.placedByModel, true);
assert.equal(view.severityLabel, 'Major');
assert.equal(view.color, '#ff4444');
assert.equal(view.category, 'Strike');
assert.equal(view.place, 'Kharkiv');
assert.equal(view.sources, '6 sources');
assert.equal(view.age, '10 min');
assert.equal(view.sides, 'Reported by UA sources · RU sources');
assert.deepEqual(view.picture, { url: 'https://a.test/p.jpg', credit: 'A' });
assert.deepEqual(
view.chips.map((c) => [c.kind, c.label]),
[
['official', 'Official'],
['confirmed', 'Reported by both sides'],
['media', 'Video'],
['media', 'Photos'],
],
);
assert.deepEqual(
view.others.map((o) => o.side),
['RU'],
);
// A lone report: its own side, no picture, one source.
const single = feedCardView(report('s', '2026-10-28T09:00:00Z'), NOW);
assert.equal(single.sides, 'Reported by UA sources');
assert.equal(single.picture, null);
// A one-source event (a Telegram post) shows its picture and its clip in
// the panel, though the globe's picture cards need two sources.
const post = report('p', '2026-10-28T09:00:00Z', {
event: {
size: 1,
sides: [],
image: {
url: 'https://cdn4.telesco.pe/file/v.jpg',
publisher: 'Channel',
video: 'https://cdn4.telesco.pe/file/v.mp4?token=x',
},
},
});
assert.deepEqual(feedCardView(post, NOW).picture, {
url: 'https://cdn4.telesco.pe/file/v.jpg',
credit: 'Channel',
video: 'https://cdn4.telesco.pe/file/v.mp4?token=x',
});
assert.equal(single.original, null);
assert.equal(sidesLine({ side: 'unknown' }), '');
});
test('event sides older than a day are left out of the card and its sides line', () => {
const r = report('w', '2026-10-28T09:00:00Z', {
event: event({
sides: [
{
side: 'UA',
title: 'a',
url: 'https://a.test/',
publisher: 'A',
publishedAt: '2026-10-28T08:00:00Z',
},
{
side: 'RU',
title: 'old',
url: 'https://b.test/',
publisher: 'B',
publishedAt: '2026-10-26T08:00:00Z',
},
{
side: 'unknown',
title: 'c',
url: 'https://c.test/',
publisher: 'C',
publishedAt: '2026-10-28T09:10:00Z',
},
// No date: nothing shows it is recent.
{ side: 'IL', title: 'd', url: 'https://d.test/', publisher: 'D' },
],
}),
});
const view = feedCardView(r, NOW);
assert.deepEqual(
view.others.map((o) => [o.side, o.title]),
[['Unattributed', 'c']],
);
// The unattributed side is not named in the sides line.
assert.equal(view.sides, 'Reported by UA sources');
assert.equal(cardView(r, NOW).meta, '30 min · 6 sources · UA, Unattributed');
// All sides outside the window: no others, the report's own side remains.
const stale = report('v', '2026-10-28T09:00:00Z', {
event: event({
sides: [
{
side: 'RU',
title: 'old',
url: 'https://b.test/',
publisher: 'B',
publishedAt: '2026-10-26T08:00:00Z',
},
],
}),
});
assert.deepEqual(feedCardView(stale, NOW).others, []);
assert.equal(feedCardView(stale, NOW).sides, 'Reported by UA sources');
});
test('in view: half-degree cells and reports within 500 km of the centre', () => {
assert.equal(viewCell({ lat: 50.2, lon: 36.7 }), '100:73');
assert.equal(viewCell({ lat: 50.4, lon: 36.9 }), '100:73');
assert.notEqual(viewCell({ lat: 50.6, lon: 36.7 }), '100:73');
assert.ok(
Math.abs(distanceKm({ lat: 0, lon: 0 }, { lat: 0, lon: 1 }) - 111.2) < 0.5,
);
const filters = normalizeFilters({ minSeverity: 0 });
const near = report('near', '2026-10-28T09:00:00Z', { severity: 1 });
const major = report('major', '2026-10-28T08:00:00Z', { severity: 3 });
const far = report('far', '2026-10-28T09:00:00Z', {
pins: [{ lat: 31.5, lon: 34.4, place: 'Gaza', mappable: true }],
});
const old = report('old', '2026-10-27T08:00:00Z');
const centre = { lat: 49, lon: 36 };
assert.ok(distanceKm(centre, far.pins[0]) > NEWS_IN_VIEW_RADIUS_KM);
assert.deepEqual(
reportsInView([near, far, old, major], centre, filters, NOW).map(
(r) => r.id,
),
['near', 'major'],
);
assert.deepEqual(reportsInView([near], null, filters, NOW), []);
assert.deepEqual(reportsInView([], centre, filters, NOW), []);
});
test('a server may serve fewer hours than the day, never more', () => {
assert.equal(newsWindowMs(12), 12 * 3_600_000);
assert.equal(newsWindowMs(24), 24 * 3_600_000);
for (const bad of [0, 25, 12.5, '12', null, undefined])
assert.equal(newsWindowMs(bad), 24 * 3_600_000);
const page = {
reports: [
report('fresh', '2026-10-28T02:00:00Z'),
report('old', '2026-10-27T20:00:00Z'),
],
nextBefore: null,
};
const empty = { items: [], nextBefore: null };
const ids = (windowMs) =>
mergeFeedPage(empty, page, 'replace', NOW, undefined, windowMs).items.map(
(r) => r.id,
);
assert.deepEqual(ids(newsWindowMs(12)), ['fresh']);
assert.deepEqual(ids(newsWindowMs(24)), ['fresh', 'old']);
});
test('the hotspots answer carries the window it was counted over', () => {
const base = {
hotspots: [],
ingest: { lastRunAt: '2026-10-28T09:00:00Z' },
};
assert.equal(
normalizeHotspotsPayload({ ...base, windowHours: 12 }).windowHours,
12,
);
assert.equal(normalizeHotspotsPayload(base).windowHours, null);
assert.equal(
normalizeHotspotsPayload({ ...base, windowHours: 48 }).windowHours,
null,
);
const shorter = normalizeHotspotsPayload({
...base,
windowHours: 3,
maxWindowHours: 12,
});
assert.deepEqual([shorter.windowHours, shorter.maxWindowHours], [3, 12]);
assert.equal(normalizeHotspotsPayload(base).maxWindowHours, null);
});
test('the window choices stop at the window the server serves', () => {
assert.deepEqual(newsWindowChoices(24), [24, 12, 6, 3, 1]);
assert.deepEqual(newsWindowChoices(12), [12, 6, 3, 1]);
assert.deepEqual(newsWindowChoices(8), [8, 6, 3, 1]);
assert.deepEqual(newsWindowChoices(1), [1]);
assert.deepEqual(newsWindowChoices(null), [24, 12, 6, 3, 1]);
});
test('a checked severity keeps saying who set it', () => {
const page = normalizeFeedPayload({
reports: ['label', 'model', 'guess'].map((by, i) => ({
...report(`r${i}`, '2026-10-28T09:00:00Z'),
severity: 2,
severityBy: by,
})),
});
assert.deepEqual(
page.reports.map((r) => r.severityBy),
['label', 'model', 'rules'],
);
});
+366
View File
@@ -0,0 +1,366 @@
// Validate /api/news payloads before they reach the scene or the DOM. Every
// string is bounded, every URL is http(s), every position is finite; a record
// that fails is dropped, a payload that fails is rejected whole. A portable
// export (layers/news/source): no i18n here.
const CATEGORY = /^[a-z][a-z-]{1,31}$/;
const CODE = /^[A-Za-z][A-Za-z0-9-]{0,31}$/;
const ID = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
const EVENT_STATUSES = Object.freeze([
'both-sides',
'independent',
'claimed',
'reported',
'side',
'single',
]);
const text = (value, max) =>
typeof value === 'string' && value.trim()
? value.replace(/\s+/g, ' ').trim().slice(0, max)
: null;
const finite = (value, min, max) =>
Number.isFinite(value) && value >= min && value <= max ? value : null;
const iso = (value) => {
const ms = Date.parse(value);
return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
};
const code = (value) =>
typeof value === 'string' && CODE.test(value) ? value : null;
const severity = (value) =>
Number.isInteger(value) && value >= 0 && value <= 3 ? value : null;
/** An http(s) URL without credentials, as its normalised href, or null. */
export function httpUrl(value) {
try {
const url = new URL(value);
return ['http:', 'https:'].includes(url.protocol) &&
!url.username &&
!url.password
? url.href
: null;
} catch {
return null;
}
}
function normalizeBbox(bbox) {
if (!Array.isArray(bbox) || bbox.length !== 4) return null;
const [west, south, east, north] = bbox;
if (
finite(west, -180, 180) === null ||
finite(east, -180, 180) === null ||
finite(south, -90, 90) === null ||
finite(north, -90, 90) === null ||
west >= east ||
south >= north
)
return null;
return [west, south, east, north];
}
/** Beacon position: the curated focus point, else the bbox centre. */
function normalizeFocus(focus, [west, south, east, north]) {
const lat = finite(focus?.lat, south, north);
const lon = finite(focus?.lon, west, east);
return lat !== null && lon !== null
? { lat, lon }
: { lat: (south + north) / 2, lon: (west + east) / 2 };
}
function normalizeDeveloping(items) {
const out = [];
for (const raw of Array.isArray(items) ? items.slice(0, 16) : []) {
const lat = finite(raw?.focus?.lat, -90, 90);
const lon = finite(raw?.focus?.lon, -180, 180);
const country =
typeof raw?.country === 'string' && /^[A-Z]{2}$/.test(raw.country)
? raw.country
: null;
if (lat === null || lon === null || !country) continue;
// A state where the catch-all flags states ("US-FL"), else the country.
const area =
typeof raw.area === 'string' && /^[A-Z]{2}-[A-Z0-9]{1,3}$/.test(raw.area)
? raw.area
: null;
out.push({
country,
key: area || country,
name: text(raw.name, 80) || country,
events: Math.max(0, Math.floor(Number(raw.events) || 0)),
reports: Math.max(0, Math.floor(Number(raw.reports) || 0)),
focus: { lat, lon },
});
}
return out;
}
const hoursOrNull = (hours) =>
Number.isInteger(hours) && hours >= 1 && hours <= 24 ? hours : null;
/**
* `/api/news/hotspots` → `{hotspots, categories, lastRunAt, windowHours,
* maxWindowHours}`, or null when the payload has no hotspot list.
* `windowHours` is the window the counts cover and `maxWindowHours` the
* longest the server serves this reader; each is null when the server names
* none.
*/
export function normalizeHotspotsPayload(payload) {
if (!Array.isArray(payload?.hotspots)) return null;
const hotspots = [];
for (const raw of payload.hotspots.slice(0, 64)) {
const id = typeof raw?.id === 'string' && ID.test(raw.id) ? raw.id : null;
const name = text(raw?.name, 80);
const bbox = normalizeBbox(raw?.bbox);
if (!id || !name || !bbox) continue;
const counts = raw.counts || {};
hotspots.push({
id,
name,
kind: text(raw.kind, 16) || 'conflict',
catchAll: raw.catchAll === true,
developing: normalizeDeveloping(raw.developing),
bbox,
parties: Array.isArray(raw.parties)
? raw.parties.filter((p) => code(p))
: [],
last24h: Math.max(0, Math.floor(Number(counts.last24h) || 0)),
mapped24h: Math.max(0, Math.floor(Number(counts.mapped24h) || 0)),
prev24h: Number.isFinite(counts.prev24h)
? Math.max(0, Math.floor(counts.prev24h))
: null,
focus: normalizeFocus(raw.focus, bbox),
latestAt: iso(raw.latestAt),
});
}
return {
hotspots,
categories: Array.isArray(payload.categories)
? payload.categories.filter(
(c) => typeof c === 'string' && CATEGORY.test(c),
)
: [],
lastRunAt: iso(payload.ingest?.lastRunAt),
windowHours: hoursOrNull(payload.windowHours),
maxWindowHours: hoursOrNull(payload.maxWindowHours),
};
}
function normalizeGeo(geo) {
if (!geo || typeof geo !== 'object') return null;
const lat = finite(geo.lat, -90, 90);
const lon = finite(geo.lon, -180, 180);
if (lat === null || lon === null) return null;
return {
lat,
lon,
place: text(geo.place, 80),
precision: text(geo.precision, 16) || 'city',
confidence: finite(geo.confidence, 0, 1) ?? 0,
mappable: geo.mappable === true,
byModel: geo.method === 'llm',
};
}
/**
* The event's picture: an HTTPS URL on the publisher's site, and whose it is;
* with the post's own clip when it has one a browser plays itself (an HTTPS
* MP4 or WebM file), the picture then its poster.
*/
function eventImage(image) {
const url = httpUrl(image?.url);
if (!url?.startsWith('https://')) return null;
const video = httpUrl(image.video);
const playable =
video?.startsWith('https://') &&
/\.(?:mp4|m4v|webm)$/i.test(new URL(video).pathname);
return {
url,
publisher: text(image.publisher, 80) || '',
...(playable ? { video } : {}),
};
}
/** An event summary from `/feed?events=1`: size and one report per side. */
function normalizeEvent(event) {
if (!event || typeof event !== 'object') return null;
const count = (value) => Math.max(1, Math.floor(Number(value) || 1));
const sides = [];
for (const side of Array.isArray(event.sides)
? event.sides.slice(0, 8)
: []) {
const url = httpUrl(side?.url);
const title = text(side?.title, 300);
if (!url || !title) continue;
sides.push({
side: code(side.side) || 'unknown',
title,
url,
publisher: text(side.publisher, 80) || '',
publishedAt: iso(side.publishedAt),
});
}
return {
id: typeof event.id === 'string' && ID.test(event.id) ? event.id : null,
status: EVENT_STATUSES.includes(event.status) ? event.status : null,
claimedBy: text(event.claimedBy, 80),
reportedSide: code(event.reportedSide),
size: count(event.size),
reports: count(event.reports),
severity: severity(event.severity),
firstAt: iso(event.firstAt),
lastAt: iso(event.lastAt),
sides,
image: eventImage(event.image),
};
}
function normalizeReport(raw) {
const id = typeof raw?.id === 'string' && ID.test(raw.id) ? raw.id : null;
const title = text(raw?.title, 300);
const url = httpUrl(raw?.url);
const publishedAt = iso(raw?.publishedAt);
if (!id || !title || !url || !publishedAt) return null;
const source = raw.source || {};
const geo = normalizeGeo(raw.geo);
// Map positions: the report's own place plus any other hotspot its title
// names (a roundup is pinned in each).
const pins = [];
for (const place of [
geo,
...(Array.isArray(raw.locations)
? raw.locations.slice(0, 8).map(normalizeGeo)
: []),
])
if (
place?.mappable &&
!pins.some((p) => p.lat === place.lat && p.lon === place.lon)
)
pins.push(place);
const hotspotId = typeof raw.hotspotId === 'string' ? raw.hotspotId : null;
return {
id,
hotspotId,
hotspotIds: Array.isArray(raw.hotspotIds)
? raw.hotspotIds.filter((h) => typeof h === 'string').slice(0, 8)
: [hotspotId].filter(Boolean),
title,
url,
snippet: text(raw.snippet, 400),
publisher: text(raw.publisher, 80) || text(source.name, 80) || '',
sourceName: text(source.name, 80) || text(raw.publisher, 80) || '',
kind: text(raw.kind, 16) || 'rss',
side: code(raw.side) || 'unknown',
affiliation: text(raw.affiliation, 32),
attribution: text(source.attribution, 120),
category:
typeof raw.category === 'string' && CATEGORY.test(raw.category)
? raw.category
: 'other',
publishedAt,
geo,
pins,
event: normalizeEvent(raw.event),
titleEn: text(raw.titleEn, 200),
relevance: ['core', 'related', 'minor'].includes(raw.relevance)
? raw.relevance
: 'related',
severity: severity(raw.severity),
severityBy: ['model', 'label'].includes(raw.severityBy)
? raw.severityBy
: 'rules',
claim:
raw.claim && typeof raw.claim === 'object'
? { by: text(raw.claim.by, 80) }
: null,
media: Array.isArray(raw.media)
? [...new Set(raw.media.filter((m) => m === 'video' || m === 'photo'))]
: [],
};
}
function normalizeRing(ring) {
if (!Array.isArray(ring) || ring.length < 3) return null;
const points = [];
for (const point of ring.slice(0, 20_000)) {
const lon = finite(point?.[0], -180, 180);
const lat = finite(point?.[1], -90, 90);
if (lon !== null && lat !== null) points.push([lon, lat]);
}
return points.length >= 3 ? points : null;
}
/**
* `/api/news/outline` → `{polygons, borders, disputed, area}`: the dissolved
* extent (`{outer, holes}`), the national borders inside it (rings), its
* disputed areas and, answering a point, the area named there (else null),
* invalid parts dropped.
*/
export function normalizeOutlinePayload(payload) {
const polygons = [];
// Above every country's island count (Indonesia's is 208): an outline cut
// short leaves islands outside the area, read again on each settle there.
for (const raw of Array.isArray(payload?.polygons)
? payload.polygons.slice(0, 300)
: []) {
const outer = normalizeRing(raw?.outer);
if (!outer) continue;
const holes = (Array.isArray(raw.holes) ? raw.holes.slice(0, 200) : [])
.map(normalizeRing)
.filter(Boolean);
polygons.push({ outer, holes });
}
const borders = (
Array.isArray(payload?.borders) ? payload.borders.slice(0, 50) : []
)
.map(normalizeRing)
.filter(Boolean);
const KINDS = ['held', 'self', 'un', 'unclaimed'];
const country = (value) =>
typeof value === 'string' && /^[A-Z]{2}$/.test(value) ? value : null;
const disputed = [];
for (const raw of Array.isArray(payload?.disputed)
? payload.disputed.slice(0, 30)
: []) {
const rings = (Array.isArray(raw?.rings) ? raw.rings.slice(0, 20) : [])
.map(normalizeRing)
.filter(Boolean);
const name = text(raw?.name, 60);
if (!rings.length || !name) continue;
disputed.push({
name,
kind: KINDS.includes(raw.kind) ? raw.kind : 'held',
heldBy: country(raw.heldBy),
claimedBy: country(raw.claimedBy),
rings,
});
}
return { polygons, borders, disputed, area: outlineArea(payload?.area) };
}
const AREA_KINDS = ['country', 'region', 'disputed'];
function outlineArea(raw) {
const key = text(raw?.key, 80);
const name = text(raw?.name, 80);
if (!key || !name) return null;
return {
key,
name,
kind: AREA_KINDS.includes(raw.kind) ? raw.kind : 'country',
country:
typeof raw.country === 'string' && /^[A-Z]{2}$/.test(raw.country)
? raw.country
: null,
};
}
/** `/api/news/feed` → `{reports, nextBefore}`, or null without a report list. */
export function normalizeFeedPayload(payload) {
if (!Array.isArray(payload?.reports)) return null;
const reports = [];
for (const raw of payload.reports.slice(0, 500)) {
const report = normalizeReport(raw);
if (report) reports.push(report);
}
return { reports, nextBefore: iso(payload.nextBefore) };
}
+228
View File
@@ -0,0 +1,228 @@
import { readResponseJsonCapped } from '../../sources/httpBody.js';
import { isUnavailableCapability } from '../../sources/capability.js';
import {
normalizeFeedPayload,
normalizeHotspotsPayload,
normalizeOutlinePayload,
} from './records.js';
// A portable export (package.json): no i18n here. Failures stay English data;
// the layer shows them translated.
const msg = (text) => text;
const MAX_BYTES = 4 * 1024 * 1024;
const BASE_PATH = '/api/news';
// The outline geometry version the client draws (disputed areas included).
const OUTLINE_VERSION = '4';
/** The three read routes the news layer calls, for a host's path allowlist. */
export const NEWS_API_PATHS = Object.freeze([
`${BASE_PATH}/hotspots`,
`${BASE_PATH}/feed`,
`${BASE_PATH}/outline`,
]);
const FEED_KEYS = Object.freeze([
'hotspot',
'before',
'since',
'limit',
'category',
'relevance',
'at',
]);
const FLAG_KEYS = Object.freeze(['geo', 'today', 'events']);
const ISO = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/;
const LIST = /^[a-z][a-z,-]{0,127}$/;
// A point to two decimals (~1 km), as areaPoint writes it.
const AT = /^-?\d{1,2}(?:\.\d{1,2})?,-?\d{1,3}(?:\.\d{1,2})?$/;
// A coordinate to two decimals, without trailing zeros ("50.4", "-97.74").
const areaPoint = (value) => String(Math.round(value * 100) / 100);
const FEED_VALUE = {
hotspot: (v) => /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(v),
before: (v) => ISO.test(v),
since: (v) => ISO.test(v),
limit: (v) => /^\d{1,3}$/.test(v) && Number(v) >= 1 && Number(v) <= 500,
category: (v) => LIST.test(v),
relevance: (v) => LIST.test(v),
at: (v) => AT.test(v),
};
/**
* Feed query string from a plain object; unknown keys and empty values are
* dropped. `at` is a point (`{lat, lon}`), the Local section's area there.
*/
export function newsFeedQuery(query = {}) {
const params = new URLSearchParams();
for (const key of FEED_KEYS) {
const value =
key === 'at' && query.at
? `${areaPoint(query.at.lat)},${areaPoint(query.at.lon)}`
: query[key];
if (value !== undefined && value !== null && value !== '')
params.set(key, String(value));
}
for (const key of FLAG_KEYS) if (query[key]) params.set(key, '1');
return params.toString();
}
/**
* Whether a request URL is one this client sends: a known route, known keys
* only, each value in its form. A host proxying the routes can admit exactly
* these and refuse the rest.
* @param {URL} url
*/
export function newsQueryAllowed(url) {
const params = [...url.searchParams];
if (new Set(params.map(([key]) => key)).size !== params.length) return false;
if (url.pathname === `${BASE_PATH}/hotspots`)
return (
params.length === 0 ||
(params.length === 1 &&
params[0][0] === 'hours' &&
/^\d{1,2}$/.test(params[0][1]) &&
Number(params[0][1]) >= 1 &&
Number(params[0][1]) <= 24)
);
if (url.pathname === `${BASE_PATH}/outline`) {
const keys = params.map(([key]) => key).sort();
const value = url.searchParams;
return (
params.length === 2 &&
keys[1] === 'v' &&
value.get('v') === OUTLINE_VERSION &&
((keys[0] === 'hotspot' && FEED_VALUE.hotspot(value.get('hotspot'))) ||
(keys[0] === 'country' &&
/^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$/.test(value.get('country'))) ||
(keys[0] === 'at' && AT.test(value.get('at'))))
);
}
if (url.pathname !== `${BASE_PATH}/feed`) return false;
return params.every(([key, value]) =>
FLAG_KEYS.includes(key)
? value === '1'
: Object.hasOwn(FEED_VALUE, key) && FEED_VALUE[key](value),
);
}
/**
* A failed read: a server without the news routes is a permanent miss; one
* that reads a section from a key it lacks (503 `no_key`, `key_rejected` or,
* its allowance for the day spent, `key_quota`, naming the key registry's id)
* says which, and is asked again later.
*/
async function responseError(response) {
let body = null;
try {
body = await readResponseJsonCapped(response, 16 * 1024);
} catch {
await response.body?.cancel?.().catch?.(() => {});
}
if (
response.status === 503 &&
['no_key', 'key_rejected', 'key_quota'].includes(body?.error) &&
typeof body.key === 'string' &&
/^[a-z][a-z0-9-]{0,31}$/.test(body.key)
)
return Object.assign(new Error(msg('News key required')), {
status: 503,
code: body.error,
keyRequired: true,
keyRejected: body.error === 'key_rejected',
keyQuota: body.error === 'key_quota',
keyId: body.key,
unavailable: false,
retryable: true,
});
const unavailable =
response.status === 404 ||
(response.status === 503 && isUnavailableCapability(body));
return Object.assign(
new Error(
unavailable
? msg('News feed not configured on this server')
: msg('News feed unavailable'),
),
{
status: response.status,
code: unavailable ? 'unavailable' : 'http',
unavailable,
retryable: !unavailable,
},
);
}
/** Read hotspots, reports and outlines from the server's /api/news routes. */
export function createNewsSource({
fetchImpl = (...args) => globalThis.fetch(...args),
timeoutMs = 15_000,
} = {}) {
async function get(path, { signal } = {}) {
signal?.throwIfAborted();
const timeout = AbortSignal.timeout(timeoutMs);
const request = signal ? AbortSignal.any([signal, timeout]) : timeout;
try {
const response = await fetchImpl(`${BASE_PATH}${path}`, {
signal: request,
cache: 'no-store',
redirect: 'error',
});
if (!response.ok) throw await responseError(response);
return await readResponseJsonCapped(response, MAX_BYTES, request);
} catch (cause) {
// Out of time the feed reads unavailable, not the browser's own words
// ("signal timed out"); the caller's own abort stays an abort.
if (timeout.aborted && !signal?.aborted)
throw Object.assign(new Error(msg('News feed unavailable')), {
code: 'timeout',
unavailable: false,
retryable: true,
});
throw cause;
}
}
return {
// `hours` asks for counts over a shorter window than the server's own.
async getHotspots({ signal, hours } = {}) {
const payload = normalizeHotspotsPayload(
await get(hours ? `/hotspots?hours=${hours}` : '/hotspots', {
signal,
}),
);
if (!payload) throw new Error(msg('Malformed news hotspots response'));
return payload;
},
async getOutline(hotspotId, { signal } = {}) {
return normalizeOutlinePayload(
await get(
`/outline?hotspot=${encodeURIComponent(hotspotId)}&v=${OUTLINE_VERSION}`,
{ signal },
),
);
},
async getCountryOutline(country, { signal } = {}) {
return normalizeOutlinePayload(
await get(
`/outline?country=${encodeURIComponent(country)}&v=${OUTLINE_VERSION}`,
{ signal },
),
);
},
// The area the Local section reads at a point, with its outline.
async getAreaOutline({ lat, lon }, { signal } = {}) {
return normalizeOutlinePayload(
await get(
`/outline?at=${areaPoint(lat)},${areaPoint(lon)}&v=${OUTLINE_VERSION}`,
{ signal },
),
);
},
async getFeed(query = {}, { signal } = {}) {
const payload = normalizeFeedPayload(
await get(`/feed?${newsFeedQuery(query)}`, { signal }),
);
if (!payload) throw new Error(msg('Malformed news feed response'));
return payload;
},
};
}
+248
View File
@@ -0,0 +1,248 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
NEWS_API_PATHS,
createNewsSource,
newsFeedQuery,
newsQueryAllowed,
} from './source.js';
const json = (body, status = 200) =>
new Response(JSON.stringify(body), {
status,
headers: { 'Content-Type': 'application/json' },
});
function recorder(respond) {
const calls = [];
return {
calls,
fetchImpl: async (url, init) => {
calls.push({ url, init });
return respond(url, init);
},
};
}
test('reads validated hotspots, feed and outlines from the same-origin routes', async () => {
const { calls, fetchImpl } = recorder((url) => {
if (url.startsWith('/api/news/hotspots'))
return json({
hotspots: [{ id: 'ua', name: 'UA', bbox: [22, 44, 42, 56] }],
});
if (url.startsWith('/api/news/feed'))
return json({
reports: [
{
id: 'r1',
title: 'T',
url: 'https://x.test/',
publishedAt: '2026-10-28T09:00:00Z',
},
],
nextBefore: null,
});
return json({ polygons: [], borders: [], disputed: [] });
});
const source = createNewsSource({ fetchImpl });
assert.equal((await source.getHotspots()).hotspots[0].id, 'ua');
assert.equal(
(await source.getFeed({ hotspot: 'all', today: true, limit: 60 }))
.reports[0].id,
'r1',
);
assert.deepEqual((await source.getOutline('ua')).polygons, []);
await source.getCountryOutline('SD');
await source.getHotspots({ hours: 6 });
await source.getAreaOutline({ lat: 30.26666, lon: -97.7 });
await source.getFeed({ hotspot: 'all', at: { lat: 30.26666, lon: -97.7 } });
assert.deepEqual(
calls.map((c) => c.url),
[
'/api/news/hotspots',
'/api/news/feed?hotspot=all&limit=60&today=1',
'/api/news/outline?hotspot=ua&v=4',
'/api/news/outline?country=SD&v=4',
'/api/news/hotspots?hours=6',
'/api/news/outline?at=30.27,-97.7&v=4',
'/api/news/feed?hotspot=all&at=30.27%2C-97.7',
],
);
for (const { url, init } of calls) {
assert.equal(init.redirect, 'error');
assert.equal(init.cache, 'no-store');
assert.ok(init.signal instanceof AbortSignal);
// Every URL the client sends is one a host's allowlist admits.
assert.equal(newsQueryAllowed(new URL(url, 'http://h')), true, url);
}
});
test('malformed, failed and unconfigured reads reject; a server without news is a permanent miss', async () => {
const malformed = createNewsSource({ fetchImpl: async () => json({}) });
await assert.rejects(malformed.getHotspots(), /Malformed news hotspots/);
await assert.rejects(malformed.getFeed(), /Malformed news feed/);
const down = createNewsSource({
fetchImpl: async () => json({ error: 'upstream' }, 502),
});
await assert.rejects(down.getHotspots(), (error) => {
assert.equal(error.message, 'News feed unavailable');
assert.equal(error.retryable, true);
assert.equal(error.unavailable, false);
return true;
});
const unconfigured = createNewsSource({
fetchImpl: async () =>
json(
{ error: 'news_not_configured', unavailable: true, retryable: false },
503,
),
});
await assert.rejects(unconfigured.getHotspots(), (error) => {
assert.equal(error.message, 'News feed not configured on this server');
assert.equal(error.code, 'unavailable');
assert.equal(error.unavailable, true);
assert.equal(error.retryable, false);
return true;
});
const missing = createNewsSource({
fetchImpl: async () => new Response('Not found', { status: 404 }),
});
await assert.rejects(missing.getFeed(), { unavailable: true });
const broken = createNewsSource({
fetchImpl: async () => new Response('{', { status: 200 }),
});
await assert.rejects(broken.getHotspots(), SyntaxError);
});
test('a section read from a key the server lacks names the key and is asked again', async () => {
const answer = (body) =>
createNewsSource({
fetchImpl: async () =>
new Response(JSON.stringify(body), {
status: 503,
headers: { 'Content-Type': 'application/json' },
}),
});
await assert.rejects(
answer({ error: 'no_key', key: 'liveuamap' }).getHotspots(),
(error) => {
assert.equal(error.keyRequired, true);
assert.equal(error.keyRejected, false);
assert.equal(error.keyId, 'liveuamap');
assert.equal(error.unavailable, false);
assert.equal(error.retryable, true);
return true;
},
);
await assert.rejects(
answer({ error: 'key_rejected', key: 'worldnewsapi' }).getFeed({
at: { lat: 51.13, lon: 71.43 },
}),
{ keyRequired: true, keyRejected: true, keyId: 'worldnewsapi' },
);
// The day's allowance spent: still the key's matter, back tomorrow.
await assert.rejects(
answer({ error: 'key_quota', key: 'worldnewsapi' }).getFeed(),
{
keyRequired: true,
keyRejected: false,
keyQuota: true,
keyId: 'worldnewsapi',
unavailable: false,
},
);
// A key name not in the registry's form is an ordinary failure.
await assert.rejects(
answer({ error: 'no_key', key: '<script>' }).getHotspots(),
(error) => error.keyRequired === undefined && error.code === 'http',
);
});
test('reads time out and follow the caller signal', async () => {
// AbortSignal.timeout does not hold the event loop open: the hanging fetch
// does, until its signal aborts, so the run cannot end before it.
const hang = (_url, { signal }) =>
new Promise((_, reject) => {
const alive = setTimeout(() => {}, 60_000);
signal.addEventListener(
'abort',
() => {
clearTimeout(alive);
reject(signal.reason);
},
{ once: true },
);
});
const slow = createNewsSource({ fetchImpl: hang, timeoutMs: 20 });
// Out of time it reads unavailable, in the app's words, as retryable.
await assert.rejects(slow.getHotspots(), {
message: 'News feed unavailable',
code: 'timeout',
retryable: true,
});
// The caller's abort stays its own, even once the time is up too.
const late = (_url, { signal }) =>
new Promise((_, reject) => {
setTimeout(() => reject(signal.reason), 40);
});
const leaving = new AbortController();
const gone = createNewsSource({ fetchImpl: late, timeoutMs: 20 }).getFeed(
{},
{ signal: leaving.signal },
);
leaving.abort(new Error('gone'));
await assert.rejects(gone, /gone/);
const caller = new AbortController();
const pending = createNewsSource({ fetchImpl: hang }).getFeed(
{},
{ signal: caller.signal },
);
caller.abort(new Error('gone'));
await assert.rejects(pending, /gone/);
await assert.rejects(
createNewsSource({ fetchImpl: hang }).getHotspots({
signal: AbortSignal.abort(new Error('already')),
}),
/already/,
);
});
test('the host allowlist admits the client routes and refuses anything else', () => {
const allowed = (path) => newsQueryAllowed(new URL(path, 'http://h'));
assert.deepEqual(NEWS_API_PATHS, [
'/api/news/hotspots',
'/api/news/feed',
'/api/news/outline',
]);
assert.equal(
allowed(
`/api/news/feed?${newsFeedQuery({ hotspot: 'ua-ru-war', before: '2026-10-28T08:00:00.000Z', limit: 500, category: 'strike', relevance: 'core,related', geo: true, today: true, events: true })}`,
),
true,
);
assert.equal(allowed('/api/news/hotspots?hours=6'), true);
for (const path of [
'/api/news/hotspots?hours=0',
'/api/news/hotspots?hours=25',
'/api/news/hotspots?hours=6&hours=3',
'/api/news/hotspots?hours=6&x=1',
'/api/news/hotspots?x=1',
'/api/news/feed?limit=501',
'/api/news/feed?limit=0',
'/api/news/feed?hotspot=all&hotspot=ua',
'/api/news/feed?since=yesterday',
'/api/news/feed?geo=yes',
'/api/news/feed?side=UA',
'/api/news/air-alerts',
'/api/news/outline?hotspot=ua',
'/api/news/outline?hotspot=ua&v=2',
'/api/news/outline?country=ukraine&v=4',
'/api/news/outline?at=30.267,-97.7&v=4',
'/api/news/outline?at=30.27&v=4',
'/api/news/outline?at=30.27,-97.7&country=US&v=4',
'/api/news/feed?at=30.267,-97.7',
])
assert.equal(allowed(path), false, path);
});
+131
View File
@@ -0,0 +1,131 @@
// Marker sprites for news reports: a dark disc with the category's icon and
// a rim in the severity colour, the rim's form telling attestation. Drawn once per look
// on a canvas and handed to Cesium as a data URL, so its texture atlas keeps
// one copy per look however often the layer re-renders.
import { NEWS_CATEGORIES, NEWS_SEVERITY } from './model.js';
const CANVAS = 64;
const BODY = 52; // disc diameter inside the canvas; the rest is rim and ring
const INK = 'rgba(10, 10, 15, 0.92)';
const SELECTED = '#00d4ff';
const COUNT_INK = '#e8eaed';
/** Canvas pixels per marker pixel: the billboard is drawn at this ratio. */
export const SPRITE_SCALE = CANVAS / BODY;
const cache = new Map();
/**
* Paint one marker look centred at (cx, cy) with a disc of `body` pixels: the
* sprites and the event cards' badges draw the same thing.
*/
export function paintMarker(ctx, { category, severity, rim }, cx, cy, body) {
const k = body / BODY; // the strokes below are tuned for the 52 px body
const r = body / 2;
// A dark edge keeps the lightest fills apart from bright ground.
ctx.beginPath();
ctx.arc(cx, cy, r + 1.5 * k, 0, 2 * Math.PI);
ctx.fillStyle = 'rgba(0, 0, 0, 0.85)';
ctx.fill();
// GEV's dark glass disc, as its HUD buttons are; severity colours the rim
// and the icon rather than filling the disc.
ctx.beginPath();
ctx.arc(cx, cy, r, 0, 2 * Math.PI);
ctx.fillStyle = INK;
ctx.fill();
const color = (NEWS_SEVERITY[severity] || NEWS_SEVERITY[0]).color;
// Attestation is the rim's form, never its colour.
ctx.beginPath();
ctx.arc(cx, cy, r - 3 * k, 0, 2 * Math.PI);
ctx.setLineDash(rim === 'claimed' ? [7 * k, 5 * k] : []);
ctx.lineWidth = (rim === 'thin' ? 2.5 : 6) * k;
ctx.strokeStyle = color;
ctx.stroke();
ctx.setLineDash([]);
const style = NEWS_CATEGORIES[category] || NEWS_CATEGORIES.other;
const icon = body * 0.5;
ctx.save();
ctx.translate(cx - icon / 2, cy - icon / 2);
ctx.scale(icon / 16, icon / 16);
const path = new Path2D(style.icon);
ctx.lineCap = 'round';
ctx.lineJoin = 'round';
ctx.lineWidth = 1.7;
ctx.strokeStyle = color;
if (style.solid) {
ctx.fillStyle = color;
ctx.fill(path);
} else ctx.stroke(path);
ctx.restore();
}
/**
* Data URL of the sprite for a look, or null where there is no canvas (the
* layer then falls back to a plain point).
* @param {{category: string, severity: number, rim: 'confirmed'|'claimed'|'thin', selected?: boolean}} look
*/
export function markerSprite({ category, severity, rim, selected = false }) {
const key = `${category}|${severity}|${rim}|${selected ? 1 : 0}`;
if (cache.has(key)) return cache.get(key);
const canvas = globalThis.document?.createElement?.('canvas');
const ctx = canvas?.getContext?.('2d');
if (!ctx || typeof globalThis.Path2D !== 'function') return null;
canvas.width = canvas.height = CANVAS;
const c = CANVAS / 2;
paintMarker(ctx, { category, severity, rim }, c, c, BODY);
if (selected) {
ctx.beginPath();
ctx.arc(c, c, CANVAS / 2 - 2, 0, 2 * Math.PI);
ctx.lineWidth = 3.5;
ctx.strokeStyle = SELECTED;
ctx.stroke();
}
const url = canvas.toDataURL('image/png');
cache.set(key, url);
return url;
}
/**
* Data URL of a country badge: the dark disc with a light rim and the number
* of reports it stands for, drawn at the pixels it is shown at so the digits
* stay sharp. Null where there is no canvas.
* @param {number} count Reports the badge stands for.
* @param {number} pixels The disc's diameter in drawn pixels.
*/
export function countSprite(count, pixels) {
const body = Math.max(1, Math.round(pixels));
const text = count > 99 ? '99+' : String(count);
const key = `count|${text}|${body}`;
if (cache.has(key)) return cache.get(key);
const canvas = globalThis.document?.createElement?.('canvas');
const ctx = canvas?.getContext?.('2d');
if (!ctx) return null;
const k = body / BODY;
canvas.width = canvas.height = Math.round(CANVAS * k);
const c = canvas.width / 2;
const r = body / 2;
ctx.beginPath();
ctx.arc(c, c, r + 1.5 * k, 0, 2 * Math.PI);
ctx.fillStyle = 'rgba(0, 0, 0, 0.85)';
ctx.fill();
ctx.beginPath();
ctx.arc(c, c, r, 0, 2 * Math.PI);
ctx.fillStyle = INK;
ctx.fill();
ctx.beginPath();
ctx.arc(c, c, r - 2 * k, 0, 2 * Math.PI);
ctx.lineWidth = 3 * k;
ctx.strokeStyle = COUNT_INK;
ctx.stroke();
ctx.fillStyle = COUNT_INK;
ctx.font = `600 ${Math.round(body * (text.length > 2 ? 0.34 : 0.44))}px ui-monospace, Menlo, monospace`;
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(text, c, c + k);
const url = canvas.toDataURL('image/png');
cache.set(key, url);
return url;
}
+123
View File
@@ -0,0 +1,123 @@
import { formatDate, formatNumber, msg, t } from '../../i18n/index.js';
import { EMODNET_PAGE_URL } from './records.js';
export const ERA_LABELS = Object.freeze({
'before-1900': msg('Before 1900'),
'1900-1945': msg('1900–1945'),
'after-1945': msg('After 1945'),
undated: msg('Date unknown'),
});
export const ERA_COLORS = Object.freeze({
'before-1900': '#c79a5b',
'1900-1945': '#ff6b5e',
'after-1945': '#4fc3f7',
undated: '#9aa7b4',
});
function formatDay(date) {
const match = /^(-?\d{4})-(\d{2})-(\d{2})$/.exec(date || '');
if (!match) return '';
return formatDate(
Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])),
{ day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' },
);
}
function meters(value) {
return formatNumber(value, {
maximumFractionDigits: value < 10 ? 1 : 0,
});
}
/** How well the position is known, as one card line (or null). */
export function positionLine(record) {
if (record.positionNote) return t('Position: centre of the protected area');
const accuracy = record.positionAccuracy;
if (!Number.isFinite(accuracy)) return null;
// 1852 m is EMODnet's "within a nautical mile" for old, reported positions.
if (accuracy >= 1000)
return t('Position approximate (within about {km} km)', {
km: formatNumber(accuracy / 1000, { maximumFractionDigits: 1 }),
});
return t('Position surveyed (within about {m} m)', { m: meters(accuracy) });
}
/**
* The link a click on the card opens: the Wikipedia (or Wikidata) page, the
* wreck's own page when EMODnet lists one, else EMODnet's portal.
* @param {object} record
* @returns {string}
*/
export function cardLink(record) {
return record?.url || EMODNET_PAGE_URL;
}
/**
* Title and detail lines for one wreck card: deaths first, then when and
* where, then the ship facts. Victims appear as a count only; free text that
* refers to a person by a title or role is dropped by a keyword filter (see
* records.js), which a bare name can still pass.
* @param {object} record A normalized shipwreck record.
* @returns {{title: string, details: string[], link: string}}
*/
export function describeShipwreck(record) {
const titleParts = [t('Shipwreck')];
if (record.name) titleParts.push(record.name);
const details = [];
// Deaths first, right under the title: the fact readers look for.
const toll = [];
if (Number.isFinite(record.casualties))
toll.push(
t('Fatalities: {count}', { count: formatNumber(record.casualties) }),
);
if (record.survivors)
toll.push(
t('Survivors: {count}', { count: formatNumber(record.survivors) }),
);
if (toll.length) details.push(toll.join(' · '));
const when =
formatDay(record.date) ||
(Number.isInteger(record.year) ? String(record.year) : '') ||
record.dating ||
'';
const where = [when, record.country].filter(Boolean);
if (where.length) details.push(where.join(' · '));
if (record.vesselType)
details.push(t('Vessel: {value}', { value: record.vesselType }));
if (record.cause)
details.push(t('What happened: {value}', { value: record.cause }));
if (Number.isFinite(record.depth))
details.push(
record.depthQuality
? t('Depth: {m} m ({quality})', {
m: meters(record.depth),
quality: record.depthQuality,
})
: t('Depth: {m} m', { m: meters(record.depth) }),
);
const position = positionLine(record);
if (position) details.push(position);
if (record.notes) details.push(t('Notes: {value}', { value: record.notes }));
if (record.cargo)
details.push(t('Cargo or finds: {value}', { value: record.cargo }));
if (record.protected) details.push(t('Protected wreck'));
const sources =
record.source === 'wikidata'
? record.alsoIn === 'emodnet'
? 'Wikidata · EMODnet'
: 'Wikidata'
: record.originator
? `EMODnet (${record.originator})`
: 'EMODnet';
details.push(t('Source: {value}', { value: sources }));
const link = cardLink(record);
details.push(
link === EMODNET_PAGE_URL
? t('Click the card to open EMODnet ↗')
: link.includes('.wikipedia.org/')
? t('Click the card to open the article ↗')
: t('Click the card to open the source ↗'),
);
return { title: titleParts.join(' · '), details, link };
}
+63
View File
@@ -0,0 +1,63 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { describeShipwreck, positionLine } from './cards.js';
import { EMODNET_PAGE_URL } from './records.js';
test('a Wikidata card shows the ship facts and links its article', () => {
const card = describeShipwreck({
source: 'wikidata',
alsoIn: 'emodnet',
name: 'HMS Havant',
vesselType: 'destroyer',
date: '1940-06-01',
year: 1940,
cause: 'Was sunk on 06/01/1940 by the German air force',
casualties: 8,
survivors: 120,
depth: 14.72,
depthQuality: 'Least depth known',
positionAccuracy: 3.1,
notes: '1939 G and H-class destroyer',
country: 'France',
url: 'https://en.wikipedia.org/wiki/HMS_Havant_(H32)',
});
assert.equal(card.title, 'Shipwreck · HMS Havant');
assert.equal(card.link, 'https://en.wikipedia.org/wiki/HMS_Havant_(H32)');
const text = card.details.join('\n');
assert.equal(card.details[0], 'Fatalities: 8 · Survivors: 120');
assert.match(card.details[1], /1940 · France$/);
assert.match(text, /Vessel: destroyer/);
assert.match(text, /What happened: Was sunk/);
assert.match(text, /Depth: 15 m \(Least depth known\)/);
assert.match(text, /Position surveyed \(within about 3\.1 m\)/);
assert.match(text, /Source: Wikidata · EMODnet/);
assert.match(text, /open the article/);
});
test('an EMODnet card without a page links the portal', () => {
const card = describeShipwreck({
source: 'emodnet',
name: null,
year: null,
dating: 'C1st AD',
originator: 'The Oxford Roman Economy Project',
protected: true,
url: null,
});
assert.equal(card.title, 'Shipwreck');
assert.equal(card.link, EMODNET_PAGE_URL);
const text = card.details.join('\n');
assert.equal(card.details[0], 'C1st AD');
assert.match(text, /Protected wreck/);
assert.match(text, /EMODnet \(The Oxford Roman Economy Project\)/);
assert.match(text, /open EMODnet/);
});
test('position lines read the accuracy', () => {
assert.equal(positionLine({}), null);
assert.match(positionLine({ positionAccuracy: 1852 }), /about 1\.9 km/);
assert.match(
positionLine({ positionNote: 'x' }),
/centre of the protected area/,
);
});
+21
View File
@@ -0,0 +1,21 @@
/** Era chips, oldest first; a wreck with no known year sits in its own chip. */
export const SHIPWRECK_ERAS = Object.freeze([
'before-1900',
'1900-1945',
'after-1945',
'undated',
]);
/**
* The era a wreck belongs to. Ancient wrecks dated only by period
* ("Roman Imperial", "C1st AD") count as before 1900.
* @param {{year?: number|null, ancient?: boolean}} record
* @returns {string}
*/
export function eraOf(record) {
const year = Number.isInteger(record?.year) ? record.year : null;
if (year === null) return record?.ancient ? 'before-1900' : 'undated';
if (year < 1900) return 'before-1900';
if (year <= 1945) return '1900-1945';
return 'after-1945';
}
+13
View File
@@ -0,0 +1,13 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { eraOf } from './eras.js';
test('each wreck falls in one era', () => {
assert.equal(eraOf({ year: 1588 }), 'before-1900');
assert.equal(eraOf({ year: null, ancient: true }), 'before-1900');
assert.equal(eraOf({ year: 1900 }), '1900-1945');
assert.equal(eraOf({ year: 1945 }), '1900-1945');
assert.equal(eraOf({ year: 1946 }), 'after-1945');
assert.equal(eraOf({ year: null }), 'undated');
assert.equal(eraOf(null), 'undated');
});
+528
View File
@@ -0,0 +1,528 @@
import * as Cesium from 'cesium';
import { formatNumber, msg, t, tn } from '../../i18n/index.js';
import {
registerSpriteCollection,
restoreSpriteOrder,
unregisterSpriteCollection,
} from '../../data/spriteOrder.js';
import { createHorizonCull } from '../streetLevel/view.js';
import { ERA_COLORS, ERA_LABELS, describeShipwreck } from './cards.js';
import { SHIPWRECK_ERAS, eraOf } from './eras.js';
import {
inPeriod,
normalizePeriod,
periodRange,
yearExtent,
} from './period.js';
export * from './records.js';
export * from './cards.js';
export * from './eras.js';
export * from './period.js';
export { createShipwrecksSource } from './source.js';
export const SHIPWRECKS_LAYER_ID = 'shipwrecks';
export const SHIPWRECKS_OVERLAY_SOURCE_ID = 'shipwrecks';
const PICK_PREFIX = 'shipwreck:';
const CARD_HOST_OPTIONS = Object.freeze({
cohortLimit: 1,
collisionCapacity: 1,
moving: false,
});
const MAX_CARD_LINES = 14;
/** Wrecks not refreshed for this long leave the map (the proxy's own limit). */
const MAX_SHOWN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
/**
* When the shown wrecks leave the map if the page cannot refresh, on this
* page's clock: the age the proxy reports (its own clock) is subtracted from
* the limit, so the two clocks are never compared, and the newest source
* decides. A wreck both sources list is one merged record, so the snapshot
* goes as a whole, not per source. With no age reported, the snapshot counts
* as fresh when it arrives.
*/
export function snapshotDeadline(snapshot, at) {
const limit = snapshot.maxAgeMs ?? MAX_SHOWN_AGE_MS;
const ages = ['emodnet', 'wikidata']
.filter((name) => snapshot.sources?.[name] !== false)
.map((name) => snapshot.ages?.[name] ?? 0);
const newest = ages.length ? Math.min(...ages) : 0;
return at + limit - newest;
}
/**
* Marker size in pixels: grows with the death toll, from 16 px (no deaths known) to 36 px (about a thousand or more).
*/
export function markerPixelSize(casualties) {
const n = Number.isFinite(casualties) && casualties > 0 ? casualties : 0;
return Math.round(16 + Math.min(20, Math.log2(1 + n) * 2));
}
/**
* A round marker in the era's colour with a sinking hull and mast in the
* middle, as an SVG data URL. It is rasterized at 144 px, four times the
* largest marker, so big markers stay sharp on high-density screens.
* @param {string} color CSS colour.
* @returns {string}
*/
export function wreckMarkerImage(color) {
const svg =
`<svg xmlns="http://www.w3.org/2000/svg" width="144" height="144" viewBox="0 0 36 36">` +
`<circle cx="18" cy="18" r="16" fill="${color}" stroke="#ffffff" stroke-width="2"/>` +
`<path d="M8 21h20l-3.5 5h-13z" fill="#0b1420"/>` +
`<path d="M17 8v12M17 9l6 7h-6" fill="none" stroke="#0b1420" stroke-width="2.2" stroke-linejoin="round"/>` +
`</svg>`;
return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
}
/**
* Shipwrecks: EMODnet's European heritage wrecks and Wikidata's notable
* wrecks worldwide, one marker each, with a card and era chips.
*/
export function createShipwrecksLayer({
source,
overlayHost = null,
screenSpaceEventHandlerFactory = null,
picking = null,
pointer = null,
openExternal = null,
now = () => Date.now(),
// One collection for every wreck marker (thousands of them): far cheaper to
// draw and rebuild than an entity each. Tests pass a fake.
createMarkers = (scene) =>
new Cesium.BillboardCollection({
scene,
blendOption: Cesium.BlendOption.TRANSLUCENT,
}),
} = {}) {
if (typeof source?.getSnapshot !== 'function')
throw new TypeError('Shipwrecks require a snapshot source');
let _viewer = null;
let _enabled = false;
let _markers = null;
let _request = null;
let _records = new Map();
let _pins = [];
let _snapshot = null;
let _deadline = null;
let _lastError = null;
let _clickHandler = null;
let _rowListener = null;
let _selectedId = null;
let _selectedCardId = null;
let _selectedLink = null;
let _period = { from: null, to: null };
let _extent = null;
let _range = null;
const _images = Object.fromEntries(
SHIPWRECK_ERAS.map((era) => [era, wreckMarkerImage(ERA_COLORS[era])]),
);
const render = () => _viewer?.scene?.requestRender?.();
const notifyRow = () => _rowListener?.();
const canSelect = () =>
overlayHost && screenSpaceEventHandlerFactory && picking;
// Markers skip the depth test so terrain does not swallow them; the
// horizon cull hides the far side of the planet instead.
const _horizon = createHorizonCull({
getViewer: () => _viewer,
items: () => _pins,
onChange: render,
});
/** Shown: its year is inside the period (undated ones only for all years). */
function visible(record) {
return Boolean(record) && inPeriod(record, _range);
}
function applyPin(pin) {
const show = pin.inFront && visible(pin.record);
if (pin.billboard.show !== show) pin.billboard.show = show;
}
/** Re-apply the period to every marker and the open card. */
function applyFilter() {
for (const pin of _pins) applyPin(pin);
if (_selectedId && !visible(_records.get(_selectedId))) clearSelection();
notifyRow();
render();
}
function rebuild(records) {
_records = new Map(records.map((record) => [record.id, record]));
_extent = yearExtent(records);
_range = periodRange(_period, _extent);
_pins = [];
if (!_markers) return;
_markers.removeAll();
// Within one collection later markers draw on top: add by rising death
// toll so a bigger toll covers smaller neighbours.
const ordered = [...records].sort(
(a, b) => (a.casualties || 0) - (b.casualties || 0),
);
for (const record of ordered) {
const position = Cesium.Cartesian3.fromDegrees(record.lon, record.lat);
const size = markerPixelSize(record.casualties);
const billboard = _markers.add({
id: `${PICK_PREFIX}${record.id}`,
position,
image: _images[eraOf(record)],
width: size,
height: size,
heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
disableDepthTestDistance: Number.POSITIVE_INFINITY,
});
const pin = {
billboard,
record,
position,
inFront: true,
get show() {
return this.inFront;
},
set show(value) {
this.inFront = value;
applyPin(this);
},
};
applyPin(pin);
_pins.push(pin);
}
_horizon.update();
if (_selectedId && !_records.has(_selectedId)) clearSelection();
else if (_selectedId) publishCard();
render();
}
// ---- selection card ----------------------------------------------------
function publishCard() {
if (!canSelect()) return;
const record = _selectedId ? _records.get(_selectedId) : null;
if (!visible(record)) {
clearSelection();
return;
}
const { title, details, link } = describeShipwreck(record);
_selectedLink = link && openExternal ? link : null;
const card = {
id: `shipwreck-card:${record.id}`,
selected: true,
interactive: Boolean(_selectedLink),
title,
details: details.slice(0, MAX_CARD_LINES),
accent: ERA_COLORS[eraOf(record)],
priority: Number.MAX_SAFE_INTEGER,
gapPx: 15,
verticalOnly: true,
placement: 'above',
stateless: true,
horizonCull: true,
position: Cesium.Cartesian3.fromDegrees(record.lon, record.lat),
};
if (card.interactive) {
const target = _selectedLink;
card.accessibilityLabel = t('Open the source for {title}', { title });
card.activate = () => {
openExternal(target);
return true;
};
}
_selectedCardId = card.id;
overlayHost.setEntries(
SHIPWRECKS_OVERLAY_SOURCE_ID,
[card],
CARD_HOST_OPTIONS,
);
overlayHost.setVisible?.(SHIPWRECKS_OVERLAY_SOURCE_ID, true);
}
function clearSelection() {
_selectedId = null;
_selectedCardId = null;
_selectedLink = null;
overlayHost?.setEntries(
SHIPWRECKS_OVERLAY_SOURCE_ID,
[],
CARD_HOST_OPTIONS,
);
}
function pickedRecordId(picked) {
const pickId = picking.resolvePickId(picked);
if (typeof pickId !== 'string' || !pickId.startsWith(PICK_PREFIX))
return null;
const id = pickId.slice(PICK_PREFIX.length);
return _records.has(id) ? id : null;
}
function installClickHandler() {
if (!canSelect() || _clickHandler || !_viewer) return;
picking.registerPickOwner?.(
SHIPWRECKS_LAYER_ID,
(pickedId) =>
typeof pickedId === 'string' && pickedId.startsWith(PICK_PREFIX),
);
_clickHandler = screenSpaceEventHandlerFactory(_viewer);
_clickHandler.setInputAction((click) => {
if (pointer && !pointer.isPointerFree()) return;
const cardHit = overlayHost.hitTest?.(
click.position?.x,
click.position?.y,
{ sourceId: SHIPWRECKS_OVERLAY_SOURCE_ID },
);
if (cardHit && cardHit.entryId === _selectedCardId) {
if (_selectedLink) openExternal(_selectedLink);
return;
}
const picked = _viewer.scene.pick(click.position);
const id = picked ? pickedRecordId(picked) : null;
if (id) {
_selectedId = id;
publishCard();
render();
return;
}
if (picked) {
const pickId = picking.resolvePickId(picked);
if (pickId && picking.isOwnedByOtherLayer(SHIPWRECKS_LAYER_ID, pickId))
return;
}
if (_selectedId) {
clearSelection();
render();
}
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
}
function removeClickHandler() {
_clickHandler?.destroy();
_clickHandler = null;
picking?.unregisterPickOwner?.(SHIPWRECKS_LAYER_ID);
}
/** Wrecks shown per era, in one pass over the records. */
function eraCounts() {
const counts = Object.fromEntries(SHIPWRECK_ERAS.map((era) => [era, 0]));
for (const record of _records.values())
if (inPeriod(record, _range)) counts[eraOf(record)]++;
return counts;
}
/** The years that have a dated wreck, plus `extra` ones, newest first. */
function yearsInData(extra = []) {
const years = new Set(extra);
for (const record of _records.values())
if (Number.isInteger(record.year)) years.add(record.year);
return [...years].sort((a, b) => b - a);
}
/** The start and end year pickers, side by side. */
function periodControls() {
if (!_extent || _extent.min === _extent.max) return {};
const range = periodRange(_period, _extent);
const valueText = range.all
? t('All years')
: range.from === range.to
? String(range.from)
: `${range.from}–${range.to}`;
// Only years with a wreck: a picker of every year since the oldest
// dated wreck would run to well over a thousand entries.
// The chosen ends stay listed even when no wreck sank that year.
const options = yearsInData([range.from, range.to]).map((year) => ({
value: year,
label: String(year),
}));
return {
range: {
id: 'period',
label: t('Period'),
valueText,
from: {
label: t('From'),
ariaLabel: t('First year of the shipwreck period'),
value: range.from,
},
to: {
label: t('To'),
ariaLabel: t('Last year of the shipwreck period'),
value: range.to,
},
options,
params: (end, value) => ({ [end]: Number(value) }),
},
};
}
const layer = {
id: SHIPWRECKS_LAYER_ID,
name: 'Shipwrecks',
icon: '⚓',
source: 'EMODnet · Wikidata',
// The proxy refreshes once a day; this only notices a new snapshot.
updateInterval: 6 * 60 * 60 * 1000,
init(viewer) {
if (_viewer) throw new Error('Shipwrecks layer is already initialized');
_viewer = viewer;
_markers = createMarkers(viewer.scene);
_markers.show = false;
viewer.scene.primitives.add(_markers);
registerSpriteCollection(SHIPWRECKS_LAYER_ID, _markers);
},
enable() {
_enabled = true;
if (_markers) _markers.show = true;
restoreSpriteOrder(_viewer);
installClickHandler();
if (_pins.length) _horizon.update();
},
disable() {
_enabled = false;
_request?.abort();
_request = null;
if (_markers) _markers.show = false;
removeClickHandler();
clearSelection();
_horizon.stop();
render();
},
async update() {
if (!_enabled || !_markers) return false;
_request?.abort();
const request = new AbortController();
_request = request;
try {
const snapshot = await source.getSnapshot({ signal: request.signal });
if (request.signal.aborted || _request !== request || !_enabled)
return false;
// The page checks every 6 h; the proxy refreshes once a day. Only a
// new snapshot rebuilds the markers.
const unchanged =
typeof snapshot.version === 'string' &&
snapshot.version === _snapshot?.version &&
_pins.length > 0;
_snapshot = snapshot;
_deadline = snapshotDeadline(snapshot, now());
_lastError =
snapshot.sources.emodnet && snapshot.sources.wikidata
? null
: snapshot.sources.emodnet
? msg('Wikidata unavailable; showing EMODnet only')
: msg('EMODnet unavailable; showing Wikidata only');
if (!unchanged) rebuild(snapshot.records);
notifyRow();
return true;
} catch (error) {
if (request.signal.aborted || _request !== request || !_enabled)
return false;
console.warn('[Data:Shipwrecks] Fetch error:', error);
_lastError = error?.message || msg('Shipwrecks unavailable');
// What is on the map was not refreshed: say so, and drop it once
// even its newest source is older than the proxy would serve.
if (_snapshot) {
if (now() >= _deadline) {
_snapshot = null;
_deadline = null;
rebuild([]);
} else _snapshot = { ..._snapshot, stale: true };
}
notifyRow();
return false;
} finally {
if (_request === request) _request = null;
}
},
destroy(viewer = _viewer) {
layer.disable();
if (_markers) {
unregisterSpriteCollection(SHIPWRECKS_LAYER_ID, _markers);
const primitives = viewer?.scene?.primitives;
if (primitives && !primitives.isDestroyed?.())
primitives.remove(_markers);
_markers = null;
}
_records = new Map();
_pins = [];
_snapshot = null;
_deadline = null;
_viewer = null;
_rowListener = null;
},
/** The period filter: `from` and `to` are years (null = oldest / latest in the data). */
getParams() {
return { ..._period };
},
setParams(params = {}) {
const next = normalizePeriod(params, _period);
if (next.from === _period.from && next.to === _period.to) return true;
_period = next;
_range = periodRange(_period, _extent);
applyFilter();
return true;
},
setRowControlsListener(listener) {
_rowListener = listener;
},
getRowControls() {
const counts = eraCounts();
return {
chips: [],
...periodControls(),
// The colours are a legend: when the ship sank.
legend: SHIPWRECK_ERAS.map((era) => ({
label: t(ERA_LABELS[era]),
count: counts[era],
color: ERA_COLORS[era],
blurb: tn(counts[era], '{count} wreck', '{count} wrecks', {
count: formatNumber(counts[era]),
}),
})),
info: t('EMODnet (European waters) · Wikidata (worldwide)'),
infoTitle: t(
'European heritage wrecks come from EMODnet Human Activities; notable wrecks worldwide come from Wikidata. Colour shows when the ship sank; marker size grows with deaths. Click a marker for its card.',
),
};
},
getStats() {
let shown = 0;
for (const record of _records.values()) if (visible(record)) shown++;
return {
count: shown,
lastUpdate: _snapshot?.fetchedAt ?? null,
stale: _snapshot?.stale === true,
error: _lastError,
};
},
/** Loaded records as plain JSON-safe objects, for tools and QA. */
getAnalystRecords(maxCount = 2000) {
if (!_enabled) return [];
const out = [];
for (const record of _records.values()) {
if (out.length >= maxCount) break;
if (!visible(record)) continue;
out.push({
id: record.id,
source: record.source,
name: record.name,
vesselType: record.vesselType,
year: record.year,
era: eraOf(record),
lat: record.lat,
lon: record.lon,
depth: record.depth,
casualties: record.casualties,
});
}
return out;
},
};
return layer;
}
+383
View File
@@ -0,0 +1,383 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import * as picking from '../../data/pickRegistry.js';
import {
createShipwrecksLayer,
markerPixelSize,
snapshotDeadline,
} from './index.js';
const wreck = (id, extra = {}) => ({
id,
source: 'wikidata',
name: id,
lat: 50,
lon: -1,
year: 1912,
date: null,
casualties: null,
...extra,
});
const snapshot = (records, version = 'v1') => ({
records,
fetchedAt: 1,
stale: false,
version,
sources: { emodnet: true, wikidata: true },
});
function deferred() {
let resolve;
const promise = new Promise((done) => {
resolve = done;
});
return { promise, resolve };
}
/** A fake billboard collection that records what the layer adds. */
function fakeMarkers() {
const collection = {
show: true,
billboards: [],
rebuilds: 0,
add(options) {
const billboard = { show: true, ...options };
collection.billboards.push(billboard);
return billboard;
},
removeAll() {
collection.rebuilds++;
collection.billboards = [];
},
};
return collection;
}
function harness({ snapshots, now = () => 1 } = {}) {
const markers = fakeMarkers();
const primitives = [];
const cards = [];
const handlers = [];
const opened = [];
let pickResult = null;
const viewer = {
camera: { positionWC: Cesium.Cartesian3.fromDegrees(-1, 50, 2e6) },
scene: {
canvas: {},
requestRender() {},
pick: () => pickResult,
preRender: { addEventListener: () => () => {} },
primitives: {
add: (primitive) => primitives.push(primitive),
remove: (primitive) =>
primitives.splice(primitives.indexOf(primitive), 1),
raiseToTop() {},
contains: (primitive) => primitives.includes(primitive),
},
},
};
const queue = [...(snapshots || [])];
const requests = [];
const layer = createShipwrecksLayer({
source: {
getSnapshot({ signal }) {
requests.push(signal);
const next = queue.shift();
if (next instanceof Error) return Promise.reject(next);
return next instanceof Promise ? next : Promise.resolve(next);
},
},
createMarkers: () => markers,
overlayHost: {
setEntries: (_source, entries) => cards.push(entries),
setVisible() {},
hitTest: () => null,
},
screenSpaceEventHandlerFactory: () => {
const handler = {
setInputAction(callback) {
handler.click = callback;
},
destroy() {
handler.destroyed = true;
},
};
handlers.push(handler);
return handler;
},
picking,
pointer: { isPointerFree: () => true },
openExternal: (url) => opened.push(url),
now: () => now(),
});
layer.init(viewer);
return {
layer,
markers,
primitives,
cards,
handlers,
requests,
opened,
pick(id) {
pickResult = id ? { id: `shipwreck:${id}` } : null;
},
lastCard: () => cards.at(-1),
};
}
test('markers live in one collection, shown only while the layer is on', async () => {
const h = harness({ snapshots: [snapshot([wreck('a'), wreck('b')])] });
assert.deepEqual(h.primitives, [h.markers]);
assert.equal(h.markers.show, false);
h.layer.enable();
assert.equal(h.markers.show, true);
assert.equal(await h.layer.update(), true);
assert.equal(h.markers.billboards.length, 2);
assert.equal(h.layer.getStats().count, 2);
h.layer.disable();
assert.equal(h.markers.show, false);
assert.equal(h.handlers[0].destroyed, true);
h.layer.destroy();
assert.deepEqual(h.primitives, [], 'the collection leaves the scene');
});
test('markers sit on the wreck: no eye offset, bigger toll drawn last', async () => {
const h = harness({
snapshots: [
snapshot([
wreck('big', { casualties: 1500 }),
wreck('none'),
wreck('small', { casualties: 3 }),
]),
],
});
h.layer.enable();
await h.layer.update();
const ids = h.markers.billboards.map((billboard) => billboard.id);
assert.deepEqual(ids, ['shipwreck:none', 'shipwreck:small', 'shipwreck:big']);
for (const billboard of h.markers.billboards)
assert.equal(billboard.eyeOffset, undefined);
assert.equal(h.markers.billboards[2].width, markerPixelSize(1500));
});
test('an unchanged snapshot does not rebuild the markers', async () => {
const records = [wreck('a')];
const h = harness({
snapshots: [
snapshot(records, 'v1'),
snapshot(records, 'v1'),
snapshot([wreck('a'), wreck('b')], 'v2'),
],
});
h.layer.enable();
await h.layer.update();
await h.layer.update();
assert.equal(h.markers.rebuilds, 1);
await h.layer.update();
assert.equal(h.markers.rebuilds, 2);
assert.equal(h.markers.billboards.length, 2);
});
test('a response that arrives after the layer is turned off is ignored', async () => {
const late = deferred();
const h = harness({ snapshots: [late.promise] });
h.layer.enable();
const pending = h.layer.update();
h.layer.disable();
assert.equal(h.requests[0].aborted, true);
late.resolve(snapshot([wreck('a')]));
assert.equal(await pending, false);
assert.equal(h.markers.billboards.length, 0);
});
test('a click opens the card; a period that excludes the wreck closes it', async () => {
const h = harness({
snapshots: [
snapshot([wreck('old', { year: 1850 }), wreck('new', { year: 1990 })]),
],
});
h.layer.enable();
await h.layer.update();
h.pick('old');
h.handlers[0].click({ position: { x: 1, y: 1 } });
const [card] = h.lastCard();
assert.equal(card.id, 'shipwreck-card:old');
h.layer.setParams({ from: 1900, to: 1990 });
assert.deepEqual(h.lastCard(), [], 'the hidden wreck loses its card');
const shown = h.markers.billboards.filter((billboard) => billboard.show);
assert.deepEqual(
shown.map((billboard) => billboard.id),
['shipwreck:new'],
);
assert.equal(h.layer.getStats().count, 1);
});
test('the year pickers list only years with a wreck, and each era is counted', async () => {
const h = harness({
snapshots: [
snapshot([
wreck('a', { year: 300 }),
wreck('b', { year: 1912 }),
wreck('c', { year: 1912 }),
wreck('d', { year: 1990 }),
wreck('e', { year: null }),
]),
],
});
h.layer.enable();
await h.layer.update();
let controls = h.layer.getRowControls();
assert.deepEqual(
controls.range.options.map((option) => option.value),
[1990, 1912, 300],
);
assert.deepEqual(
controls.legend.map((era) => era.count),
[1, 2, 1, 1],
);
h.layer.setParams({ from: 1900, to: 1950 });
controls = h.layer.getRowControls();
assert.deepEqual(
controls.range.options.map((option) => option.value),
[1990, 1950, 1912, 1900, 300],
'the chosen ends are listed too',
);
assert.deepEqual(
controls.legend.map((era) => era.count),
[0, 2, 0, 0],
);
});
test('a source without a version rebuilds on every new snapshot', async () => {
const bare = (records) => {
const value = snapshot(records);
delete value.version;
return value;
};
const h = harness({
snapshots: [
bare([wreck('a')]),
bare([wreck('a'), wreck('b')]),
{ ...snapshot([wreck('a')]), version: null },
{ ...snapshot([wreck('a'), wreck('b'), wreck('c')]), version: null },
],
});
h.layer.enable();
for (const expected of [1, 2, 1, 3]) {
await h.layer.update();
assert.equal(h.markers.billboards.length, expected);
}
});
test('a failed refresh marks the shown wrecks stale, and clears them after seven days', async () => {
const DAY = 24 * 60 * 60 * 1000;
let clock = 1;
const h = harness({
now: () => clock,
snapshots: [
snapshot([wreck('a')]),
new Error('Shipwrecks unavailable (HTTP 502)'),
new Error('Shipwrecks unavailable (HTTP 502)'),
],
});
h.layer.enable();
await h.layer.update();
assert.equal(h.layer.getStats().stale, false);
clock = 1 + 2 * DAY;
assert.equal(await h.layer.update(), false);
assert.equal(h.layer.getStats().stale, true);
assert.equal(h.layer.getStats().count, 1, 'still shown, as stale');
clock = 1 + 8 * DAY;
await h.layer.update();
assert.equal(h.layer.getStats().count, 0, 'expired wrecks leave the map');
assert.equal(h.markers.billboards.length, 0);
});
test('expiry runs on the page clock and keeps every wreck until the newest source is too old', async () => {
const DAY = 24 * 60 * 60 * 1000;
const down = () => new Error('Shipwrecks unavailable (HTTP 502)');
// The page clock is far from the proxy's fetchedAt: only reported ages count.
let clock = 5e12;
const h = harness({
now: () => clock,
snapshots: [
{
...snapshot([
wreck('fresh', { source: 'emodnet' }),
wreck('merged', { source: 'wikidata', alsoIn: 'emodnet' }),
]),
fetchedAt: 1,
ages: { emodnet: 0, wikidata: 6.5 * DAY },
maxAgeMs: 7 * DAY,
},
down(),
down(),
],
});
h.layer.enable();
await h.layer.update();
clock += 1 * DAY;
await h.layer.update();
assert.equal(
h.layer.getStats().count,
2,
'nothing leaves while EMODnet is in date',
);
assert.equal(h.layer.getStats().stale, true);
clock += 6.5 * DAY;
await h.layer.update();
assert.equal(
h.layer.getStats().count,
0,
'all leave once the newest is too old',
);
});
test('a snapshot with no timestamp or ages still expires seven days after it arrived', async () => {
const DAY = 24 * 60 * 60 * 1000;
let clock = 100;
const h = harness({
now: () => clock,
snapshots: [
{ ...snapshot([wreck('a')]), fetchedAt: null },
new Error('down'),
],
});
h.layer.enable();
await h.layer.update();
clock += 8 * DAY;
await h.layer.update();
assert.equal(h.layer.getStats().count, 0);
});
test('the page deadline subtracts the newest available source age from the limit', () => {
const DAY = 24 * 60 * 60 * 1000;
const both = { emodnet: true, wikidata: true };
assert.equal(
snapshotDeadline(
{
sources: both,
ages: { emodnet: 2 * DAY, wikidata: 6.5 * DAY },
maxAgeMs: 5 * DAY,
},
100,
),
100 + 3 * DAY,
);
assert.equal(
snapshotDeadline(
{
sources: { emodnet: false, wikidata: true },
ages: { emodnet: null, wikidata: 4 * DAY },
maxAgeMs: 5 * DAY,
},
0,
),
1 * DAY,
'an unavailable source does not count',
);
assert.equal(snapshotDeadline({ sources: both }, 0), 7 * DAY, 'defaults');
});
+75
View File
@@ -0,0 +1,75 @@
/**
* The sinking year, or null when it is unknown (ancient wrecks dated only by
* period, "C1st AD", have none).
*/
export function recordYear(record) {
return Number.isInteger(record?.year) ? record.year : null;
}
/** First and last year present in the records (null when none is dated). */
export function yearExtent(records) {
let min = Infinity;
let max = -Infinity;
for (const record of records) {
const year = recordYear(record);
if (year === null) continue;
if (year < min) min = year;
if (year > max) max = year;
}
return Number.isFinite(min) ? { min, max } : null;
}
function yearParam(value) {
if (value === null) return null;
const year =
typeof value === 'string' && /^-?\d+$/.test(value) ? Number(value) : value;
return Number.isInteger(year) && Math.abs(year) < 10000 ? year : undefined;
}
/**
* Merge a (partial) period request into the current one. `from: null` means
* the first year in the data and `to: null` the latest; an invalid year keeps
* the current one, and a start after the end is stored as the reverse.
* @param {{from?: number|string|null, to?: number|string|null}} params
* @param {{from: number|null, to: number|null}} current
* @returns {{from: number|null, to: number|null}}
*/
export function normalizePeriod(
params = {},
current = { from: null, to: null },
) {
const next = { ...current };
for (const end of ['from', 'to']) {
if (!(end in params)) continue;
const year = yearParam(params[end]);
if (year !== undefined) next[end] = year;
}
// Stored in the order it is shown, so a later edit to one end (the picker
// sends only that end) changes the end the reader picked, not the other.
if (Number.isInteger(next.from) && Number.isInteger(next.to))
if (next.from > next.to) [next.from, next.to] = [next.to, next.from];
return next;
}
/**
* The inclusive year range a period covers over the data's extent. Years are
* clamped to the data, and a start after the end is read as the reverse.
* @returns {{from: number, to: number, all: boolean}|null}
*/
export function periodRange(period, extent) {
if (!extent) return null;
const clamp = (year, fallback) =>
Math.min(extent.max, Math.max(extent.min, year ?? fallback));
const start = clamp(period.from, extent.min);
const end = clamp(period.to, extent.max);
const from = Math.min(start, end);
const to = Math.max(start, end);
return { from, to, all: from === extent.min && to === extent.max };
}
/** Whether a record falls in the range; undated records only when all years show. */
export function inPeriod(record, range) {
if (!range || range.all) return true;
const year = recordYear(record);
return year !== null && year >= range.from && year <= range.to;
}
+58
View File
@@ -0,0 +1,58 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
inPeriod,
normalizePeriod,
periodRange,
recordYear,
yearExtent,
} from './period.js';
const RECORDS = [
{ year: 1588 },
{ year: 1912 },
{ year: 2012 },
{ year: null, ancient: true },
];
test('years come from the record; the extent ignores undated wrecks', () => {
assert.equal(recordYear(RECORDS[1]), 1912);
assert.equal(recordYear(RECORDS[3]), null);
assert.deepEqual(yearExtent(RECORDS), { min: 1588, max: 2012 });
assert.equal(yearExtent([{ year: null }]), null);
});
test('all years show every wreck; a narrower period hides undated ones', () => {
const extent = yearExtent(RECORDS);
const all = periodRange({ from: null, to: null }, extent);
assert.deepEqual(all, { from: 1588, to: 2012, all: true });
assert.ok(RECORDS.every((record) => inPeriod(record, all)));
const wars = periodRange(normalizePeriod({ from: '1914', to: 1945 }), extent);
assert.deepEqual(
RECORDS.map((record) => inPeriod(record, wars)),
[false, false, false, false],
);
const reversed = periodRange({ from: 1950, to: 1900 }, extent);
assert.deepEqual(reversed, { from: 1900, to: 1950, all: false });
assert.equal(inPeriod(RECORDS[1], reversed), true);
});
test('a reversed period is stored as shown, so editing one end keeps the other', () => {
const reversed = normalizePeriod({ from: 1950, to: 1900 });
assert.deepEqual(reversed, { from: 1900, to: 1950 });
// The picker shows 1900–1950; the reader changes "From" to 1920.
assert.deepEqual(normalizePeriod({ from: 1920 }, reversed), {
from: 1920,
to: 1950,
});
// Moving "From" past "To" reads as the reverse, never an empty range.
assert.deepEqual(normalizePeriod({ from: 1960 }, { from: 1900, to: 1950 }), {
from: 1950,
to: 1960,
});
// One open end stays open.
assert.deepEqual(normalizePeriod({ from: 1960 }, { from: null, to: null }), {
from: 1960,
to: null,
});
});
+455
View File
@@ -0,0 +1,455 @@
// Shared by the server proxy (server/providers/shipwrecks.js) and the browser
// layer, so it must not load the i18n catalogs: values stay data.
/** EMODnet Human Activities "Cultural Heritage – Ship wrecks" (CC BY 4.0). */
export const EMODNET_WFS_URL =
'https://ows.emodnet-humanactivities.eu/wfs?service=WFS&request=GetFeature' +
'&version=2.0.0&typeNames=emodnet:heritageshipwrecks' +
'&outputFormat=application/json&srsName=EPSG:4326';
/** Landing page shown when an EMODnet wreck has no web page of its own. */
export const EMODNET_PAGE_URL =
'https://emodnet.ec.europa.eu/en/human-activities';
export const SHIPWRECK_SOURCES = Object.freeze(['emodnet', 'wikidata']);
/**
* Wikidata (CC0): shipwreck items that have at least one Wikipedia article,
* so the worldwide set stays to notable wrecks and skips bulk register
* imports, plus sinking events ("sinking of the RMS Titanic"), which are where
* Wikidata keeps the death toll. Dates, the end of service (P576) included,
* come with their precision so a month-precise date is not shown as the 1st.
* Only ship and event facts are read: no items about people.
*/
export const WIKIDATA_QUERY = `SELECT ?item ?itemLabel ?itemDescription ?coord ?sunk ?sunkPrecision ?end ?endPrecision ?deaths ?survivors ?typeLabel ?enwiki ?event WHERE {
{
?item wdt:P31/wdt:P279* wd:Q852190 ; wdt:P625 ?coord ; wikibase:sitelinks ?links .
FILTER(?links > 0)
OPTIONAL { ?item p:P793 ?wreck . ?wreck ps:P793 wd:Q906512 ; pqv:P585 [ wikibase:timeValue ?sunk ; wikibase:timePrecision ?sunkPrecision ] }
OPTIONAL { ?item p:P576 [ a wikibase:BestRank ; psv:P576 [ wikibase:timeValue ?end ; wikibase:timePrecision ?endPrecision ] ] }
OPTIONAL { ?item wdt:P31 ?type . FILTER(?type != wd:Q852190) }
} UNION {
?item wdt:P31/wdt:P279* wd:Q906512 ; wdt:P625 ?coord .
BIND("event" AS ?event)
OPTIONAL { ?item p:P585/psv:P585 [ wikibase:timeValue ?sunk ; wikibase:timePrecision ?sunkPrecision ] }
OPTIONAL { ?item wdt:P1561 ?survivors }
}
OPTIONAL { ?item wdt:P1120 ?deaths }
OPTIONAL { ?enwiki schema:about ?item ; schema:isPartOf <https://en.wikipedia.org/> }
SERVICE wikibase:label { bd:serviceParam wikibase:language "en,mul,fr,de,es,it,pt,ru,uk,ja,zh,ar". }
}`;
const MAX_TEXT = 160;
const MAX_NOTE = 260;
/** Same name within this distance: one wreck seen by both sources. */
const SAME_WRECK_KM = 3;
// Free text sometimes names people (owners, masters, divers who reported a
// wreck). The layer is about ships, so text that refers to a person by a title
// or role is dropped whole. This is a keyword filter: a bare name with none of
// these words still passes.
const PERSON_TEXT =
/\b(mr|mrs|ms|dr|capt|captain|master|skipper|owner|owned|crew|body|bodies|drowned|reported by|according to)\b/i;
/** EMODnet writes "n/a" or nothing where a value is unknown. */
function clean(value, max = MAX_TEXT) {
if (typeof value !== 'string') return null;
const text = value
.replace(/[\u0000-\u001f<>]/g, ' ')
.replace(/\s+/g, ' ')
.trim();
if (!text || /^(n\/a|null|unknown|none|-)$/i.test(text)) return null;
return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
}
/** Free text with none of the person keywords in it, or null. */
function impersonalText(value, max) {
const text = clean(value, max);
return text && !PERSON_TEXT.test(text) ? text : null;
}
function positiveNumber(value, max) {
const n = typeof value === 'number' ? value : Number(value);
return Number.isFinite(n) && n > 0 && n <= max ? n : null;
}
function count(value) {
const text = String(value ?? '').replace(/\.0+$/, '');
if (!/^\d{1,6}$/.test(text)) return null;
return Number(text);
}
/** A sinking year from "1917", "1917-1918" or "c. 1917"; null otherwise. */
export function parseYear(value, maxYear = new Date().getUTCFullYear()) {
const match = /(?:^|\D)(\d{3,4})(?:\D|$)/.exec(String(value ?? ''));
if (!match) return null;
const year = Number(match[1]);
return year >= 100 && year <= maxYear ? year : null;
}
function validPoint(lat, lon) {
return (
Number.isFinite(lat) &&
Number.isFinite(lon) &&
Math.abs(lat) <= 90 &&
Math.abs(lon) <= 180 &&
!(lat === 0 && lon === 0)
);
}
function httpUrl(value) {
const text = clean(value, 400);
if (!text) return null;
try {
const url = new URL(text);
return url.protocol === 'https:' || url.protocol === 'http:'
? url.href
: null;
} catch {
return null;
}
}
/** Whether a provenance or link value points at wrecksite.eu, in any form. */
function fromWrecksite(value) {
return typeof value === 'string' && /wrecksite/i.test(value);
}
/**
* Normalize EMODnet's shipwreck GeoJSON. Records the portal took from
* wrecksite.eu, named in the provenance or linked as the record's page, are
* skipped: that site's data is not openly licensed.
* @param {object} payload WFS GeoJSON FeatureCollection.
* @returns {object[]} Shipwreck records.
*/
export function normalizeEmodnetFeatures(payload) {
const features = payload?.features;
if (!Array.isArray(features)) return [];
const out = [];
const ids = new Set();
for (const feature of features) {
const p = feature?.properties || {};
const coords = feature?.geometry?.coordinates;
if (feature?.geometry?.type !== 'Point' || !Array.isArray(coords)) continue;
const lon = Number(coords[0]);
const lat = Number(coords[1]);
if (!validPoint(lat, lon)) continue;
// Checked on the raw values: the shown origin is cut to 80 characters,
// and a long provenance list can name wrecksite.eu after the cut.
if (fromWrecksite(p.source_inf) || fromWrecksite(p.website1)) continue;
const origin = clean(p.source_inf, 80);
const key = clean(String(feature.id ?? p.source_id ?? ''), 80);
if (!key) continue;
const id = `emodnet:${key}`;
if (ids.has(id)) continue;
ids.add(id);
const year = parseYear(p.sink_yr);
const dating = clean(p.dating, 60);
const period = clean(p.period, 60);
const vesselType =
clean(p.obj_type, 60) ||
(() => {
// ship_char is sometimes a short type ("Trawler"), sometimes a long
// history that can name people; only the short form is a type.
const text = clean(p.ship_char, 40);
return text && !/\d/.test(text) && !PERSON_TEXT.test(text)
? text
: null;
})();
out.push({
id,
source: 'emodnet',
lat,
lon,
name: clean(p.name, 100),
vesselType,
year,
date: null,
dating: year ? null : dating,
ancient: !year && Boolean(period || dating),
cause: impersonalText(p.sink_context, MAX_NOTE),
notes: period && dating ? `${period} (${dating})` : period,
cargo: impersonalText(p.artefacts, 120),
protected: /protected/i.test(p.statutory || ''),
depth: positiveNumber(p.least_depth, 11000),
depthQuality: clean(p.depth_prec, 80),
positionAccuracy: positiveNumber(p.loc_prec, 100000),
positionNote: /centroid/i.test(p.point_info || '')
? 'Centre of the protected area'
: null,
casualties: null,
survivors: null,
country: clean(p.country, 60),
originator: origin,
url: httpUrl(p.website1),
});
}
return out;
}
function wikiUrl(value) {
const url = httpUrl(value);
return url && /^https:\/\/[a-z]{2,3}\.wikipedia\.org\/wiki\//.test(url)
? url
: null;
}
/**
* A Wikidata time as a day ("1912-04-15") when it is day-precise, else as a
* year only: a month- or year-precise value reads back as the 1st. A year
* before AD 100 ("-0299", 300 BC) has no place on the year picker, so it is
* kept as ancient with its year as text, like EMODnet's period-dated wrecks.
* @returns {{date: string|null, year: number|null, dating: string|null}}
*/
function wikidataTime(value, precision) {
const none = { date: null, year: null, dating: null };
const match = /^([+-]?)(\d{4,})-(\d{2})-(\d{2})T/.exec(value || '');
if (!match) return none;
// A value without a precision is only trusted to the year.
const p = precision == null ? 9 : Number(precision);
// 11 = day; 10 = month; 9 = year; below 9 is a decade or coarser.
if (!Number.isFinite(p) || p < 9) return none;
const signed = Number(`${match[1] === '-' ? '-' : ''}${match[2]}`);
if (signed < 100) {
// The query service writes XSD 1.1 years: 0000 is 1 BC, -0299 is 300 BC.
const dating = signed <= 0 ? `${1 - signed} BC` : `AD ${signed}`;
return { date: null, year: null, dating };
}
const year = parseYear(String(signed));
if (year === null) return none;
if (p >= 11)
return { date: `${match[2]}-${match[3]}-${match[4]}`, year, dating: null };
return { date: null, year, dating: null };
}
/** Whether a record (or a parsed time) says when the ship sank. */
function hasWhen(when) {
return Boolean(when.date || Number.isInteger(when.year) || when.dating);
}
/** Copy when a ship sank from one record (or parsed time) to another. */
function takeWhen(target, from) {
target.date = from.date ?? null;
target.year = from.year ?? null;
target.dating = from.dating ?? null;
target.ancient = Boolean(from.dating) || Boolean(from.ancient);
}
/** "sinking of the RMS Titanic" → "Sinking of the RMS Titanic". */
function sentenceCase(text) {
return text ? text.charAt(0).toUpperCase() + text.slice(1) : text;
}
/**
* Normalize Wikidata SPARQL results to shipwreck records (one per item).
* Sinking events are folded into the ship they sank when both are listed.
* @param {object} payload SPARQL JSON results.
* @returns {object[]}
*/
export function normalizeWikidataResults(payload) {
const bindings = payload?.results?.bindings;
if (!Array.isArray(bindings)) return [];
const byItem = new Map();
for (const binding of bindings) {
const value = (key) => binding?.[key]?.value;
const qid = /\/entity\/(Q\d{1,12})$/.exec(value('item') || '')?.[1];
if (!qid) continue;
const sunk = wikidataTime(value('sunk'), value('sunkPrecision'));
const ended = wikidataTime(value('end'), value('endPrecision'));
const known = byItem.get(qid);
if (known) {
// Extra rows only add what the first one lacked.
known.vesselType ||= clean(value('typeLabel'), 60);
if (!hasWhen(known)) takeWhen(known, hasWhen(sunk) ? sunk : ended);
known.casualties ??= count(value('deaths'));
known.survivors ??= count(value('survivors'));
continue;
}
const point = /^Point\(([-\d.eE]+) ([-\d.eE]+)\)$/.exec(
value('coord') || '',
);
const lon = point ? Number(point[1]) : NaN;
const lat = point ? Number(point[2]) : NaN;
if (!validPoint(lat, lon)) continue;
const name = clean(value('itemLabel'), 100);
const event = value('event') === 'event';
const when = hasWhen(sunk) ? sunk : ended;
byItem.set(qid, {
id: `wikidata:${qid}`,
source: 'wikidata',
event,
lat,
lon,
// An unlabelled item reads back as its own Q-id; that is no name.
name: name && name !== qid ? (event ? sentenceCase(name) : name) : null,
vesselType: event ? null : clean(value('typeLabel'), 60),
year: when.year,
date: when.date,
dating: when.dating,
ancient: Boolean(when.dating),
cause: null,
notes: impersonalText(value('itemDescription'), MAX_TEXT),
cargo: null,
protected: false,
depth: null,
depthQuality: null,
positionAccuracy: null,
positionNote: null,
casualties: count(value('deaths')),
survivors: count(value('survivors')),
country: null,
originator: null,
url:
// English Wikipedia, else the Wikidata item, which links the
// article in every language that has one.
wikiUrl(value('enwiki')) || `https://www.wikidata.org/wiki/${qid}`,
});
}
return foldSinkingEvents([...byItem.values()]);
}
/** An event this far from a listed ship whose name it contains is that ship's sinking. */
const SAME_SINKING_KM = 50;
/**
* "Sinking of the RMS Titanic" near the RMS Titanic wreck is one marker: the
* ship keeps its article and takes the event's date, deaths and survivors.
*/
function foldSinkingEvents(records) {
// Wikidata sometimes has both the ship and its wreck as items at one spot
// ("Titanic", "wreck of the RMS Titanic"): keep the ship, one marker.
const isWreckItem = (record) => (/^wreck\b/i.test(record.name || '') ? 1 : 0);
const ships = [];
const candidates = records
.filter((record) => !record.event)
.sort((a, b) => isWreckItem(a) - isWreckItem(b));
for (const record of candidates) {
const key = nameKey(record.name);
const twin =
key &&
ships.find(
(ship) =>
nameKey(ship.name) === key &&
distanceKm(ship, record) <= SAME_WRECK_KM,
);
if (!twin) {
ships.push(record);
continue;
}
twin.vesselType ||= record.vesselType;
if (!hasWhen(twin)) takeWhen(twin, record);
twin.casualties ??= record.casualties;
twin.survivors ??= record.survivors;
}
const out = [...ships];
for (const event of records.filter((record) => record.event)) {
const eventKey = ` ${nameKey(event.name)} `;
const ship = ships.find((candidate) => {
const key = nameKey(candidate.name);
return (
key.length >= 3 &&
eventKey.includes(` ${key} `) &&
distanceKm(candidate, event) <= SAME_SINKING_KM
);
});
if (!ship) {
out.push(event);
continue;
}
if (!hasWhen(ship)) {
takeWhen(ship, event);
} else if (!ship.date && event.date && event.year === ship.year) {
ship.date = event.date;
}
ship.casualties ??= event.casualties;
ship.survivors ??= event.survivors;
}
for (const record of out) delete record.event;
return out;
}
function nameKey(name) {
return String(name || '')
.normalize('NFD')
.replace(/[̀-ͯ]/g, '')
.toLowerCase()
.replace(/\([^)]*\)/g, ' ')
.replace(/\b(wreck|sinking|loss|disaster|of)\b/g, ' ')
.replace(
/\b(hms|hmt|hmhs|hmas|sms|ss|ms|mv|rms|uss|hm|s\/s|m\/v|the)\b/g,
' ',
)
.replace(/[^a-z0-9]+/g, ' ')
.trim();
}
function distanceKm(a, b) {
const rad = Math.PI / 180;
const dLat = (b.lat - a.lat) * rad;
const dLon = (b.lon - a.lon) * rad;
const h =
Math.sin(dLat / 2) ** 2 +
Math.cos(a.lat * rad) * Math.cos(b.lat * rad) * Math.sin(dLon / 2) ** 2;
return 12742 * Math.asin(Math.min(1, Math.sqrt(h)));
}
/**
* One list from both sources. A wreck in both (same name, a few km apart)
* keeps the Wikidata record, which links an article, and takes EMODnet's
* survey facts (depth, sinking text, year) that Wikidata lacks.
*/
export function mergeShipwreckRecords(emodnet = [], wikidata = []) {
const byName = new Map();
for (const record of wikidata) {
const key = nameKey(record.name);
if (!key) continue;
if (!byName.has(key)) byName.set(key, []);
byName.get(key).push(record);
}
const kept = [];
for (const record of emodnet) {
const twin = (byName.get(nameKey(record.name)) || []).find(
(candidate) => distanceKm(candidate, record) <= SAME_WRECK_KM,
);
if (!twin) {
kept.push(record);
continue;
}
if (!hasWhen(twin)) takeWhen(twin, record);
twin.vesselType ||= record.vesselType;
twin.cause ||= record.cause;
twin.depth ??= record.depth;
twin.depthQuality ||= record.depthQuality;
twin.positionAccuracy ??= record.positionAccuracy;
twin.country ||= record.country;
twin.protected ||= record.protected;
twin.alsoIn = 'emodnet';
}
return [...wikidata, ...kept];
}
/**
* Validate the proxy's snapshot in the browser.
* @returns {object[]|null} Records, or null when the payload is malformed.
*/
export function normalizeShipwreckSnapshot(payload) {
if (!Array.isArray(payload?.records)) return null;
const rows = [];
const ids = new Set();
for (const record of payload.records) {
if (
!record ||
typeof record.id !== 'string' ||
ids.has(record.id) ||
!SHIPWRECK_SOURCES.includes(record.source) ||
!validPoint(record.lat, record.lon)
)
continue;
ids.add(record.id);
rows.push({
...record,
year: Number.isInteger(record.year) ? record.year : null,
url: httpUrl(record.url),
});
}
return rows;
}
+314
View File
@@ -0,0 +1,314 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
mergeShipwreckRecords,
normalizeEmodnetFeatures,
normalizeShipwreckSnapshot,
normalizeWikidataResults,
parseYear,
WIKIDATA_QUERY,
} from './records.js';
function feature(id, properties, coordinates = [-4.35, 54.13]) {
return {
type: 'Feature',
id,
geometry: { type: 'Point', coordinates },
properties,
};
}
test('EMODnet wrecks keep ship facts and drop text that names people', () => {
const [wreck, roman] = normalizeEmodnetFeatures({
features: [
feature('w.1', {
name: 'MAINA-NUI',
sink_yr: '1987',
sink_context: 'Sank on 07/02/1987',
obj_type: 'Pusher or tug',
least_depth: 12.5,
depth_prec: 'Least depth known',
loc_prec: 50,
country: 'France',
source_inf: 'SHOM',
statutory: 'n/a',
website1: 'n/a',
}),
feature('w.2', {
name: 'Lerici',
sink_yr: '',
dating: 'C1st-2nd AD',
period: 'Roman Imperial',
artefacts: 'Marble, Columns',
obj_type: 'n/a',
ship_char: 'Owned by J. Smith, master was A. Jones',
sink_context: 'Wrecked here, reported by Mr Smith',
}),
feature('w.3', { name: 'Copied', source_inf: 'www.wrecksite.eu' }),
feature('w.4', { name: 'Null island' }, [0, 0]),
],
});
const ids = normalizeEmodnetFeatures({
features: [
feature('w.3', { name: 'Copied', source_inf: 'www.wrecksite.eu' }),
feature('w.5', {
source_inf: `${'SHOM; '.repeat(20)}wrecksite.eu`,
}),
feature('w.6', { website1: 'https://www.wrecksite.eu/wreck.aspx?1' }),
feature('w.7', { website1: 'wrecksite.eu/wreck/1' }),
feature('w.8', { name: 'Kept', source_inf: 'SHOM' }),
],
}).map((record) => record.id);
assert.deepEqual(ids, ['emodnet:w.8'], 'wrecksite.eu rows are all skipped');
assert.equal(wreck.id, 'emodnet:w.1');
assert.equal(wreck.year, 1987);
assert.equal(wreck.vesselType, 'Pusher or tug');
assert.equal(wreck.cause, 'Sank on 07/02/1987');
assert.equal(wreck.depth, 12.5);
assert.equal(wreck.positionAccuracy, 50);
assert.equal(wreck.url, null);
assert.equal(roman.year, null);
assert.equal(roman.ancient, true);
assert.equal(roman.dating, 'C1st-2nd AD');
assert.equal(roman.notes, 'Roman Imperial (C1st-2nd AD)');
assert.equal(roman.cargo, 'Marble, Columns');
assert.equal(roman.vesselType, null, 'a history naming people is no type');
assert.equal(roman.cause, null, 'text naming a person is dropped');
});
test('Wikidata rows fold into one record per item', () => {
const item = 'http://www.wikidata.org/entity/Q1471525';
const records = normalizeWikidataResults({
results: {
bindings: [
{
item: { value: item },
itemLabel: { value: 'HMS Havant' },
itemDescription: { value: '1939 G and H-class destroyer' },
coord: { value: 'Point(2.26 51.13)' },
sunk: { value: '1940-06-01T00:00:00Z' },
sunkPrecision: { value: '11' },
enwiki: { value: 'https://en.wikipedia.org/wiki/HMS_Havant_(H32)' },
},
{
item: { value: item },
typeLabel: { value: 'destroyer' },
deaths: { value: '8' },
coord: { value: 'Point(2.26 51.13)' },
},
{
item: { value: 'http://www.wikidata.org/entity/Q9' },
itemLabel: { value: 'Q9' },
coord: { value: 'Point(10 10)' },
},
],
},
});
assert.equal(records.length, 2);
const [havant, unnamed] = records;
assert.equal(havant.date, '1940-06-01');
assert.equal(havant.year, 1940);
assert.equal(havant.vesselType, 'destroyer');
assert.equal(havant.casualties, 8);
assert.equal(havant.url, 'https://en.wikipedia.org/wiki/HMS_Havant_(H32)');
assert.equal(unnamed.name, null);
assert.equal(unnamed.url, 'https://www.wikidata.org/wiki/Q9');
});
test('a wreck in both sources keeps Wikidata and takes EMODnet survey facts', () => {
const wikidata = [
{
id: 'wikidata:Q1',
source: 'wikidata',
name: 'HMS Havant',
lat: 51.13,
lon: 2.26,
year: null,
depth: null,
},
];
const emodnet = [
{
id: 'emodnet:a',
source: 'emodnet',
name: 'Havant (HMS)',
lat: 51.131,
lon: 2.262,
year: 1940,
depth: 14.7,
},
{
id: 'emodnet:b',
source: 'emodnet',
name: 'HMS Havant',
lat: 45,
lon: -10,
year: 1950,
},
];
const merged = mergeShipwreckRecords(emodnet, wikidata);
assert.deepEqual(
merged.map((record) => record.id),
['wikidata:Q1', 'emodnet:b'],
);
assert.equal(merged[0].year, 1940);
assert.equal(merged[0].depth, 14.7);
assert.equal(merged[0].alsoIn, 'emodnet');
});
test('years and snapshots are validated', () => {
assert.equal(parseYear('1917-1918'), 1917);
assert.equal(parseYear('c. 1588'), 1588);
assert.equal(parseYear(''), null);
assert.equal(parseYear('3000'), null);
assert.equal(normalizeShipwreckSnapshot({}), null);
const rows = normalizeShipwreckSnapshot({
records: [
{ id: 'a', source: 'emodnet', lat: 1, lon: 2, url: 'javascript:x' },
{ id: 'a', source: 'emodnet', lat: 1, lon: 2 },
{ id: 'b', source: 'other', lat: 1, lon: 2 },
{ id: 'c', source: 'wikidata', lat: 91, lon: 2 },
],
});
assert.equal(rows.length, 1);
assert.equal(rows[0].url, null);
});
test('a sinking event folds into its ship; month-precise dates keep the year only', () => {
const entity = (q) => ({ value: `http://www.wikidata.org/entity/${q}` });
const records = normalizeWikidataResults({
results: {
bindings: [
{
item: entity('Q25173'),
itemLabel: { value: 'Titanic' },
coord: { value: 'Point(-49.9469 41.7325)' },
},
{
item: entity('Q3018259'),
itemLabel: { value: 'wreck of the RMS Titanic' },
coord: { value: 'Point(-49.9469 41.7325)' },
},
{
item: entity('Q2577588'),
itemLabel: { value: 'sinking of the RMS Titanic' },
coord: { value: 'Point(-49.9458 41.7319)' },
event: { value: 'event' },
sunk: { value: '1912-04-01T00:00:00Z' },
sunkPrecision: { value: '10' },
deaths: { value: '1501' },
survivors: { value: '712' },
},
{
item: entity('Q1245004'),
itemLabel: { value: 'Costa Concordia disaster' },
coord: { value: 'Point(10.92 42.37)' },
event: { value: 'event' },
sunk: { value: '2012-01-13T00:00:00Z' },
sunkPrecision: { value: '11' },
deaths: { value: '32' },
},
],
},
});
assert.deepEqual(
records.map((record) => record.id),
['wikidata:Q25173', 'wikidata:Q1245004'],
);
const [titanic, concordia] = records;
assert.equal(titanic.date, null);
assert.equal(titanic.year, 1912);
assert.equal(titanic.casualties, 1501);
assert.equal(titanic.survivors, 712);
assert.equal(concordia.name, 'Costa Concordia disaster');
assert.equal(concordia.date, '2012-01-13');
assert.equal('event' in concordia, false);
});
test('a date before AD 100 is kept as ancient text, never read as an AD year', () => {
const entity = (q) => ({ value: `http://www.wikidata.org/entity/${q}` });
const [bc, earlyAd, roman] = normalizeWikidataResults({
results: {
bindings: [
{
item: entity('Q1'),
itemLabel: { value: 'Antikythera wreck' },
coord: { value: 'Point(23.3 35.9)' },
sunk: { value: '-0299-01-01T00:00:00Z' },
sunkPrecision: { value: '11' },
},
{
item: entity('Q2'),
itemLabel: { value: 'Early wreck' },
coord: { value: 'Point(12 40)' },
sunk: { value: '0050-01-01T00:00:00Z' },
sunkPrecision: { value: '9' },
},
{
item: entity('Q3'),
itemLabel: { value: 'Roman wreck' },
coord: { value: 'Point(13 41)' },
sunk: { value: '0300-01-01T00:00:00Z' },
sunkPrecision: { value: '9' },
},
],
},
});
assert.equal(bc.year, null, '300 BC is not the year 300');
assert.equal(bc.date, null, 'no day for a BC date');
assert.equal(bc.dating, '300 BC');
assert.equal(bc.ancient, true);
assert.equal(earlyAd.year, null);
assert.equal(earlyAd.dating, 'AD 50');
assert.equal(earlyAd.ancient, true);
assert.equal(roman.year, 300);
assert.equal(roman.dating, null);
});
test('an end-of-service date keeps its precision: a year-only one is no day', () => {
const entity = (q) => ({ value: `http://www.wikidata.org/entity/${q}` });
const [yearOnly, dayPrecise, unknown] = normalizeWikidataResults({
results: {
bindings: [
{
item: entity('Q11'),
itemLabel: { value: 'Year only' },
coord: { value: 'Point(1 50)' },
end: { value: '1917-01-01T00:00:00Z' },
endPrecision: { value: '9' },
},
{
item: entity('Q12'),
itemLabel: { value: 'Day precise' },
coord: { value: 'Point(2 50)' },
end: { value: '1917-03-04T00:00:00Z' },
endPrecision: { value: '11' },
},
{
item: entity('Q13'),
itemLabel: { value: 'No precision' },
coord: { value: 'Point(3 50)' },
end: { value: '1917-01-01T00:00:00Z' },
},
],
},
});
assert.equal(yearOnly.date, null, 'not shown as 1 Jan 1917');
assert.equal(yearOnly.year, 1917);
assert.equal(dayPrecise.date, '1917-03-04');
assert.equal(unknown.date, null, 'an unknown precision is a year only');
assert.equal(unknown.year, 1917);
});
test('the query reads the end of service with its precision', () => {
assert.match(
WIKIDATA_QUERY,
/psv:P576 \[ wikibase:timeValue \?end ; wikibase:timePrecision \?endPrecision \]/,
);
assert.doesNotMatch(WIKIDATA_QUERY, /wdt:P576/);
});
test('labels and links do not default to one other language', () => {
assert.doesNotMatch(WIKIDATA_QUERY, /ptwiki|pt\.wikipedia/);
assert.match(WIKIDATA_QUERY, /wikibase:language "en,mul,/);
});
+45
View File
@@ -0,0 +1,45 @@
import { readResponseJsonCapped } from '../../sources/httpBody.js';
import { normalizeShipwreckSnapshot } from './records.js';
const age = (value) => (Number.isFinite(value) && value >= 0 ? value : null);
/** Same-origin source for the proxy's EMODnet + Wikidata shipwreck snapshot. */
export function createShipwrecksSource({
fetchImpl = (...args) => globalThis.fetch(...args),
} = {}) {
return {
async getSnapshot({ signal } = {}) {
signal?.throwIfAborted();
const response = await fetchImpl('/api/shipwrecks', { signal });
if (!response.ok)
throw new Error(`Shipwrecks unavailable (HTTP ${response.status})`);
const payload = await readResponseJsonCapped(
response,
16 * 1024 * 1024,
signal,
);
signal?.throwIfAborted();
const records = normalizeShipwreckSnapshot(payload);
if (!records) throw new Error('Malformed shipwrecks response');
return {
records,
fetchedAt: Number.isFinite(payload.fetchedAt)
? payload.fetchedAt
: null,
stale: payload.stale === true,
// Changes whenever either source's data does; null from an older proxy.
version: typeof payload.version === 'string' ? payload.version : null,
// Each source's age on the proxy's clock (null when unknown).
ages: {
emodnet: age(payload.ages?.emodnet),
wikidata: age(payload.ages?.wikidata),
},
maxAgeMs: age(payload.maxAgeMs),
sources: {
emodnet: payload.sources?.emodnet !== false,
wikidata: payload.sources?.wikidata !== false,
},
};
},
};
}
+27
View File
@@ -0,0 +1,27 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createShipwrecksSource } from './source.js';
const respond = (payload) =>
createShipwrecksSource({ fetchImpl: async () => Response.json(payload) });
test('the snapshot keeps valid source ages and drops malformed ones', async () => {
const record = { id: 'a', source: 'emodnet', lat: 50, lon: -1 };
const good = await respond({
records: [record],
version: 'v',
ages: { emodnet: 0, wikidata: 3600 },
maxAgeMs: 604800000,
}).getSnapshot();
assert.deepEqual(good.ages, { emodnet: 0, wikidata: 3600 });
assert.equal(good.maxAgeMs, 604800000);
assert.equal(good.version, 'v');
const bad = await respond({
records: [record],
ages: { emodnet: -5, wikidata: 'x' },
maxAgeMs: Number.NaN,
}).getSnapshot();
assert.deepEqual(bad.ages, { emodnet: null, wikidata: null });
assert.equal(bad.maxAgeMs, null);
assert.equal(bad.version, null);
});