@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/esm/geo/osm.js

@@ -0,0 +1,171 @@
+import { boxesOverlap, osmBboxParam, overpassBbox } from "./box.js";
+const OSM_API = "https://api.openstreetmap.org/api/0.6/changesets.json";
+/*
+ * Overpass, and its understudy.
+ *
+ * The main instance rate-limits hard and fast — a second query a minute after
+ * the first came back as an HTML error page, not JSON, with HTTP 200. So
+ * anything that is not JSON is treated as "busy", the mirror is tried once,
+ * and then we stop: a checker that hammers a volunteer service to answer a
+ * question about somebody's bounty is not a checker anybody should run.
+ */
+const OVERPASS = ["https://overpass-api.de/api/interpreter", "https://overpass.kumi.systems/api/interpreter"];
+/**
+ * Who is asking.
+ *
+ * Not decoration: OpenStreetMap's API policy requires a User-Agent that
+ * identifies the application, and it enforces that by throttling anything
+ * generic into the ground. Measured 2026-08-17 — the same query, at the same
+ * moment, answered **200 for curl and 429 for Node's default fetch**, whose
+ * agent string says only that it is Node. Cloudflare Workers send their own
+ * unremarkable string, so without this the checker would have looked broken
+ * in production and fine on a laptop.
+ */
+const USER_AGENT = "OpenhandsNetwork/1.0 (verified work; +https://openhands-network.vercel.app)";
+const withTimeout = async (reach, url, init) => {
+    const call = reach.fetch ?? globalThis.fetch;
+    try {
+        return await call(url, {
+            ...init,
+            headers: { "user-agent": USER_AGENT, ...(init?.headers ?? {}) },
+            signal: AbortSignal.timeout(reach.timeoutMs ?? 30_000)
+        });
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Who edited inside this box, in this window.
+ *
+ * Null means the API did not answer. An empty `changesets` array means it did
+ * answer and nobody edited — a fact, and a different one.
+ */
+export async function changesetsIn(box, window, reach = {}) {
+    const url = `${OSM_API}?bbox=${encodeURIComponent(osmBboxParam(box))}&time=${encodeURIComponent(`${window.from},${window.to}`)}`;
+    const response = await withTimeout(reach, url, { headers: { accept: "application/json" } });
+    if (!response?.ok)
+        return null;
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(body.changesets))
+        return null;
+    const from = Date.parse(window.from);
+    const to = Date.parse(window.to);
+    const changesets = body.changesets
+        .map((raw) => {
+        const entry = raw;
+        const id = Number(entry.id);
+        const user = typeof entry.user === "string" ? entry.user : "";
+        const closedAt = typeof entry.closed_at === "string" ? entry.closed_at : "";
+        if (!Number.isFinite(id) || !user || !closedAt)
+            return null;
+        const bounds = typeof entry.min_lon === "number" && typeof entry.min_lat === "number" && typeof entry.max_lon === "number" && typeof entry.max_lat === "number"
+            ? { west: entry.min_lon, south: entry.min_lat, east: entry.max_lon, north: entry.max_lat }
+            : null;
+        return { id, user, uid: Number(entry.uid) || 0, changes: Number(entry.changes_count) || 0, closedAt, box: bounds };
+    })
+        .filter((changeset) => {
+        if (!changeset)
+            return false;
+        /* The API's `time` filter is generous about which end it matches, and an
+           open changeset can still be edited — so the window is applied here, to
+           the moment the work was actually finished. */
+        const closed = Date.parse(changeset.closedAt);
+        if (!Number.isFinite(closed) || closed < from || closed > to)
+            return false;
+        /* And its own bounds must genuinely meet ours. */
+        return changeset.box ? boxesOverlap(changeset.box, box) : true;
+    });
+    return { changesets, users: [...new Set(changesets.map((changeset) => changeset.user.toLowerCase()))] };
+}
+/** What one person did here, out of everything that happened. */
+export function creditFor(activity, username) {
+    const wanted = username.trim().toLowerCase();
+    const theirs = activity.changesets.filter((changeset) => changeset.user.toLowerCase() === wanted);
+    return { changesets: theirs.length, edits: theirs.reduce((total, changeset) => total + changeset.changes, 0) };
+}
+/**
+ * How many features of a tag the box has gained since a date.
+ *
+ * `out count` rather than the features themselves: a populated city block
+ * would otherwise be megabytes of geometry to answer a question about one
+ * integer, and the courtesy owed to a free service is the whole reason this
+ * asks so narrowly.
+ */
+export async function featureDelta(box, sinceISO, tag, reach = {}) {
+    const query = `[out:json][timeout:25];(way["${tag}"](${overpassBbox(box)})(newer:"${sinceISO}"););out count;`;
+    for (const endpoint of OVERPASS) {
+        const response = await withTimeout(reach, endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams({ data: query }).toString()
+        });
+        if (!response?.ok)
+            continue;
+        /* A busy Overpass answers 200 with an HTML error page. Parsing is the
+           only way to tell that from an answer, so a parse failure means "try the
+           mirror", not "no features". */
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            continue;
+        }
+        const total = body.elements?.[0]?.tags?.total;
+        if (total === undefined)
+            continue;
+        const count = Number(total);
+        if (Number.isFinite(count))
+            return count;
+    }
+    return null;
+}
+export async function measureMapping(args, reach = {}) {
+    const [activity, delta] = await Promise.all([changesetsIn(args.box, args.window, reach), featureDelta(args.box, args.window.from, args.tag, reach)]);
+    const credit = activity && args.username ? creditFor(activity, args.username) : { changesets: 0, edits: 0 };
+    return {
+        username: args.username ?? null,
+        changesetsByUser: credit.changesets,
+        editsByUser: credit.edits,
+        featureDelta: delta,
+        users: activity?.users ?? [],
+        incomplete: !activity || delta === null
+    };
+}
+/**
+ * The OpenStreetMap account a worker asks to be credited.
+ *
+ * Read leniently on purpose: this is the one fact the map reading cannot
+ * supply for itself, and a mapper who wrote their name plainly should not
+ * lose a bounty to a format. Any of these is enough —
+ *
+ *   osm: alice        OSM user alice        @alice
+ *   openstreetmap.org/user/alice
+ *
+ * — and nothing else is guessed. A deliverable that names no account fails
+ * the gate rather than crediting whoever happens to have been mapping there,
+ * which would pay the wrong person for real work.
+ */
+export function osmUsernameIn(deliverable) {
+    const patterns = [
+        /openstreetmap\.org\/user\/([A-Za-z0-9_\-. ]{1,60}?)(?:[/?#\s]|$)/i,
+        /\bosm(?:\s+user(?:name)?)?\s*[:=]\s*@?([A-Za-z0-9_\-.]{1,60})/i,
+        /\bopenstreetmap\s+(?:user(?:name)?\s*)?[:=]?\s*@?([A-Za-z0-9_\-.]{1,60})/i,
+        /\buser(?:name)?\s*[:=]\s*@?([A-Za-z0-9_\-.]{1,60})/i,
+        /(?:^|\s)@([A-Za-z0-9_\-.]{2,60})/
+    ];
+    for (const pattern of patterns) {
+        const found = deliverable.match(pattern)?.[1]?.trim();
+        if (found)
+            return decodeURIComponent(found);
+    }
+    return null;
+}
+//# sourceMappingURL=osm.js.map

package/dist/esm/geo/osm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"osm.js","sourceRoot":"","sources":["../../../src/geo/osm.ts"],"names":[],"mappings":"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"}

package/dist/esm/geo/place.d.ts

@@ -0,0 +1,51 @@
+import { type Geometry } from "./tiles.ts";
+interface Address {
+    road?: string;
+    pedestrian?: string;
+    neighbourhood?: string;
+    quarter?: string;
+    suburb?: string;
+    city?: string;
+    town?: string;
+    village?: string;
+    municipality?: string;
+    county?: string;
+    state?: string;
+    country?: string;
+}
+/**
+ * Two parts at most: something specific, then something everyone knows.
+ *
+ * "Pražakova ulica, Ljubljana" is a place. The full `display_name` —
+ * *"Pražakova ulica, Ledina, Grajski grič, Četrtna skupnost Center, Ljubljana,
+ * Upravna Enota Ljubljana, 1000, Slovenija"* — is a filing cabinet, and it is
+ * what this function exists to avoid putting in a sentence about money.
+ */
+export declare function labelFrom(address: Address | undefined, fallback?: string): string | null;
+/**
+ * Third-party text on a page about money.
+ *
+ * Nominatim's data is whatever a stranger typed into OpenStreetMap, so it is
+ * treated the way every other borrowed string here is: control characters
+ * stripped, whitespace collapsed, length capped. Plain text, never markup.
+ */
+export declare function clean(raw: string | null | undefined): string | null;
+/** How the world is reached. Injected so tests never touch a live service. */
+export interface Reach {
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The name of a point, at a granularity that suits how much ground is meant.
+ *
+ * The zoom is the whole design: asked coarsely it answers "Slovenija", asked
+ * finely it answers a street. Sharing `zoomForMetres` with the map means the
+ * words and the picture always agree about scale.
+ */
+export declare function placeName(point: {
+    lat: number;
+    lon: number;
+}, zoom: number, reach?: Reach): Promise<string | null>;
+/** The name for whatever an ask describes — the one callers actually want. */
+export declare const nameForGeometry: (geometry: Geometry, reach?: Reach) => Promise<string | null>;
+export {};
+//# sourceMappingURL=place.d.ts.map

package/dist/esm/geo/place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.d.ts","sourceRoot":"","sources":["../../../src/geo/place.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,QAAQ,EAAoB,MAAM,YAAY,CAAC;AAsC5E,UAAU,OAAO;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBxF;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMnE;AAED,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB5H;AAED,8EAA8E;AAC9E,eAAO,MAAM,eAAe,GAAI,UAAU,QAAQ,EAAE,QAAO,KAAU,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAA0E,CAAC"}

package/dist/esm/geo/place.js

@@ -0,0 +1,99 @@
+import { zoomForMetres, centreOf, spanOf } from "./tiles.js";
+/**
+ * What somewhere is called.
+ *
+ * `46.0569, 14.5058` is a fact nobody can read. Before this, a poster
+ * committing money to a "be there" ask, and a worker deciding whether to walk
+ * across town for it, both had four decimals and their own judgement.
+ *
+ * **Resolved once, when the ask is posted, and frozen into the terms.** Not at
+ * render, for three reasons that all point the same way:
+ *
+ * - The terms document is content-addressed and immutable. A label resolved at
+ *   posting is part of what was agreed, and it cannot drift afterwards — the
+ *   place will not quietly rename itself between the promise and the payment.
+ * - Rendering then costs nothing: no request, no key, no client JavaScript,
+ *   and it still reads correctly years later when this service is renamed or
+ *   unreachable.
+ * - Nominatim's usage policy is about one request a second. Once per ask is
+ *   nothing; once per page view would be abuse.
+ *
+ * **And it is never the contract.** A gate measures metres from the
+ * coordinates. This is a courtesy, so it is best-effort by construction: every
+ * failure returns null and the ask posts with numbers, exactly as it did
+ * before this existed.
+ */
+/** The same identifying agent the tile proxy and the OSM readers send. */
+const USER_AGENT = "OpenhandsNetwork/1.0 (verified work; +https://openhands-network.vercel.app)";
+const ENDPOINT = "https://nominatim.openstreetmap.org/reverse";
+/** Long enough for a slow answer, short enough that posting never waits on it. */
+const TIMEOUT_MS = 3_000;
+/** A label, not a paragraph — this goes in a sentence a poster reads. */
+const MAX_LENGTH = 60;
+/**
+ * Two parts at most: something specific, then something everyone knows.
+ *
+ * "Pražakova ulica, Ljubljana" is a place. The full `display_name` —
+ * *"Pražakova ulica, Ledina, Grajski grič, Četrtna skupnost Center, Ljubljana,
+ * Upravna Enota Ljubljana, 1000, Slovenija"* — is a filing cabinet, and it is
+ * what this function exists to avoid putting in a sentence about money.
+ */
+export function labelFrom(address, fallback) {
+    if (!address)
+        return clean(fallback);
+    const specific = address.road ?? address.pedestrian ?? address.neighbourhood ?? address.quarter ?? address.suburb;
+    const settlement = address.city ?? address.town ?? address.village ?? address.municipality;
+    /* When there is no settlement — open country, at sea — the wider region is
+       the only useful second half. */
+    const wider = settlement ?? address.county ?? address.state ?? address.country;
+    /* Each part is cleaned BEFORE the join, not after: a field with a trailing
+       space would otherwise be glued into "Main Street , Town", where the comma
+       has drifted away from the word it belongs to. */
+    const parts = [specific, wider].map((part) => clean(part)).filter((part) => Boolean(part));
+    const unique = parts.filter((part, index) => parts.findIndex((other) => other.toLowerCase() === part.toLowerCase()) === index);
+    return clean(unique.join(", ")) ?? clean(fallback);
+}
+/**
+ * Third-party text on a page about money.
+ *
+ * Nominatim's data is whatever a stranger typed into OpenStreetMap, so it is
+ * treated the way every other borrowed string here is: control characters
+ * stripped, whitespace collapsed, length capped. Plain text, never markup.
+ */
+export function clean(raw) {
+    if (!raw)
+        return null;
+    // eslint-disable-next-line no-control-regex -- stripping them is the point
+    const text = raw.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, " ").replace(/\s+/g, " ").trim();
+    if (!text)
+        return null;
+    return text.length <= MAX_LENGTH ? text : `${text.slice(0, MAX_LENGTH - 1).trimEnd()}…`;
+}
+/**
+ * The name of a point, at a granularity that suits how much ground is meant.
+ *
+ * The zoom is the whole design: asked coarsely it answers "Slovenija", asked
+ * finely it answers a street. Sharing `zoomForMetres` with the map means the
+ * words and the picture always agree about scale.
+ */
+export async function placeName(point, zoom, reach = {}) {
+    const call = reach.fetch ?? globalThis.fetch;
+    const url = `${ENDPOINT}?lat=${encodeURIComponent(point.lat)}&lon=${encodeURIComponent(point.lon)}&format=jsonv2&zoom=${encodeURIComponent(zoom)}`;
+    try {
+        const response = await call(url, {
+            headers: { "user-agent": USER_AGENT, accept: "application/json" },
+            signal: AbortSignal.timeout(TIMEOUT_MS)
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return labelFrom(body.address, body.name);
+    }
+    catch {
+        /* A courtesy that cannot be paid is simply not paid. */
+        return null;
+    }
+}
+/** The name for whatever an ask describes — the one callers actually want. */
+export const nameForGeometry = (geometry, reach = {}) => placeName(centreOf(geometry), zoomForMetres(spanOf(geometry)), reach);
+//# sourceMappingURL=place.js.map

package/dist/esm/geo/place.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../../src/geo/place.ts"],"names":[],"mappings":"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"}

package/dist/esm/geo/search.d.ts

@@ -0,0 +1,41 @@
+/** A short list to tap on. More rows than this and the poster is reading a gazetteer. */
+export declare const FOUND_MAX = 5;
+/** A query is a place name, not a paragraph. */
+export declare const QUERY_MAX = 120;
+export interface FoundPlace {
+    lat: number;
+    lon: number;
+    /** What it is called, on its own: "Prešernov trg", "Ljubljana". */
+    name: string;
+    /** The name with what locates it, as the ask will call the place: "Prešernov trg, Ljubljana". */
+    label: string;
+    /** What kind of thing it is, in a word a person would use: "square", "street", "city". */
+    kind: string;
+    /** Where it is, said after the name: "Ljubljana, Slovenija". */
+    region: string;
+    /** How far across it is, in metres, from its bounding box. A square is tens; a city is tens of thousands. */
+    extentMetres: number;
+}
+/**
+ * The rows a poster can choose from, from whatever Nominatim answered.
+ *
+ * Third-party text on a page about money, so every string is cleaned the way
+ * the reverse lookup cleans its labels. Two answers for the same point (a
+ * town and its boundary, a street in two segments) are one row: the poster
+ * is choosing where to stand, not which record to cite.
+ */
+export declare function foundFrom(raw: unknown): FoundPlace[];
+/** How the world is reached. Injected so tests never touch a live service. */
+export interface Reach {
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Places called something like this, best first — or null when the world
+ * could not be asked. An empty list is an answer: nothing is called that.
+ *
+ * Asked in the local language: what a sign in that street says is what a
+ * worker standing in it will read, and one answer per query is what lets
+ * the route in front of this cache it.
+ */
+export declare function searchPlaces(query: string, reach?: Reach): Promise<FoundPlace[] | null>;
+//# sourceMappingURL=search.d.ts.map

package/dist/esm/geo/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/geo/search.ts"],"names":[],"mappings":"AA+BA,yFAAyF;AACzF,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,gDAAgD;AAChD,eAAO,MAAM,SAAS,MAAM,CAAC;AAK7B,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6GAA6G;IAC7G,YAAY,EAAE,MAAM,CAAC;CACtB;AA+HD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,EAAE,CAWpD;AAED,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAU,GAAG,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAiBjG"}

package/dist/esm/geo/search.js

@@ -0,0 +1,182 @@
+import { clean } from "./place.js";
+/**
+ * Finding somewhere by what it is called.
+ *
+ * `place.ts` goes one way: a point, once, at posting, becomes a name. This is
+ * the other way, and it exists because the alternative was typing latitude
+ * and longitude by hand into a form about money. The first live test of that
+ * put a pin in the Mediterranean — a `3` for a `4` in the first digit — and
+ * the map dutifully drew the sea.
+ *
+ * **The coordinates are still the contract.** A search answers with points;
+ * the poster picks one, the gate measures metres from it, and the name the
+ * ask carries is the label they were shown. Nothing here changes what is
+ * frozen into the terms — only how the numbers get into the form.
+ *
+ * Nominatim's usage policy (one request a second, an identifying agent, and
+ * **no search-as-you-type**) is why this answers a submitted query rather
+ * than every keystroke, and why the route that calls it caches each answer.
+ * Every failure is `null`: a search that cannot be made is not an error a
+ * poster can do anything about, and the coordinates path is still there.
+ */
+/** The same identifying agent the tile proxy and the reverse lookup send. */
+const USER_AGENT = "OpenhandsNetwork/1.0 (verified work; +https://openhands-network.vercel.app)";
+const ENDPOINT = "https://nominatim.openstreetmap.org/search";
+/** Long enough for a slow answer, short enough that a person is still waiting. */
+const TIMEOUT_MS = 6_000;
+/** A short list to tap on. More rows than this and the poster is reading a gazetteer. */
+export const FOUND_MAX = 5;
+/** A query is a place name, not a paragraph. */
+export const QUERY_MAX = 120;
+/** Metres per degree of latitude — and of longitude, at the equator. */
+const METRES_PER_DEGREE = 111_320;
+/*
+ * Nominatim's word for a thing, as a person's word for it. Its vocabulary is
+ * OpenStreetMap's tagging — `pedestrian` is a street closed to cars,
+ * `administrative` is a boundary — and neither belongs in a row somebody is
+ * choosing a place from. Anything not listed keeps its own word, with the
+ * underscores taken out.
+ */
+const KINDS = {
+    pedestrian: "street",
+    road: "street",
+    residential: "street",
+    living_street: "street",
+    primary: "street",
+    secondary: "street",
+    tertiary: "street",
+    unclassified: "street",
+    service: "street",
+    footway: "path",
+    path: "path",
+    cycleway: "path",
+    administrative: "area",
+    boundary: "area",
+    city: "city",
+    town: "town",
+    village: "village",
+    hamlet: "hamlet",
+    suburb: "district",
+    quarter: "district",
+    neighbourhood: "neighbourhood",
+    county: "region",
+    state: "region",
+    region: "region",
+    country: "country",
+    square: "square",
+    place: "place"
+};
+const kindOf = (raw) => {
+    const word = clean(raw.addresstype ?? raw.type ?? raw.class) ?? "";
+    return KINDS[word] ?? word.replace(/_/g, " ");
+};
+/**
+ * How far across a thing is.
+ *
+ * The bounding box is `[south, north, west, east]`, in degrees. A degree of
+ * longitude shrinks with latitude, so the east–west side is scaled by the
+ * cosine before the diagonal is taken. Zero for a box that is a point, and
+ * zero for a box that is missing or nonsense — a size nobody could read is
+ * not a size.
+ */
+const extentOf = (raw, lat) => {
+    const box = (raw.boundingbox ?? []).map(Number);
+    if (box.length !== 4 || box.some((edge) => !Number.isFinite(edge)))
+        return 0;
+    const [south, north, west, east] = box;
+    const tall = Math.abs(north - south) * METRES_PER_DEGREE;
+    const wide = Math.abs(east - west) * METRES_PER_DEGREE * Math.cos((lat * Math.PI) / 180);
+    return Math.round(Math.hypot(tall, wide));
+};
+const unique = (parts) => {
+    const kept = [];
+    for (const part of parts) {
+        if (!part)
+            continue;
+        if (kept.some((one) => one.toLowerCase() === part.toLowerCase()))
+            continue;
+        kept.push(part);
+    }
+    return kept;
+};
+/** One row, or null when Nominatim's answer is not a place a pin can stand on. */
+function rowFrom(raw) {
+    const lat = Number(raw.lat);
+    const lon = Number(raw.lon);
+    if (!Number.isFinite(lat) || !Number.isFinite(lon) || Math.abs(lat) > 90 || Math.abs(lon) > 180)
+        return null;
+    /* Its own name first; failing that, the first part of the long form, which
+       is the thing itself before the filing cabinet that locates it. */
+    const name = clean(raw.name) ?? clean(raw.display_name?.split(",")[0]);
+    if (!name)
+        return null;
+    const address = raw.address ?? {};
+    const kind = kindOf(raw);
+    const settlement = clean(address.city ?? address.town ?? address.village ?? address.municipality);
+    /* The state where there is one, never the county: "Upravna Enota
+       Ljubljana" is a filing term, and no sign in the street says it. */
+    const wider = clean(address.state);
+    const country = clean(address.country);
+    const isSettlement = settlement !== null && settlement.toLowerCase() === name.toLowerCase();
+    /* "Prešernov trg, Ljubljana": the name, then the one place that locates
+       it. A city or a town is the locator, so it stands alone; a village or
+       a hamlet, which few people could place, is located by its country. */
+    const locator = settlement && !isSettlement ? settlement : kind === "city" || kind === "town" ? null : (wider ?? country);
+    const label = clean(unique([name, locator]).join(", ")) ?? name;
+    /* What follows the name on the row: the settlement (unless it IS the
+       name), then the country. */
+    const region = unique([isSettlement ? null : settlement, settlement ? null : wider, country].filter((part) => part && part.toLowerCase() !== name.toLowerCase())).join(", ");
+    return { lat, lon, name, label, kind, region, extentMetres: extentOf(raw, lat) };
+}
+/**
+ * The rows a poster can choose from, from whatever Nominatim answered.
+ *
+ * Third-party text on a page about money, so every string is cleaned the way
+ * the reverse lookup cleans its labels. Two answers for the same point (a
+ * town and its boundary, a street in two segments) are one row: the poster
+ * is choosing where to stand, not which record to cite.
+ */
+export function foundFrom(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const rows = [];
+    for (const one of raw) {
+        const row = one && typeof one === "object" ? rowFrom(one) : null;
+        if (!row)
+            continue;
+        if (rows.some((seen) => seen.lat.toFixed(4) === row.lat.toFixed(4) && seen.lon.toFixed(4) === row.lon.toFixed(4)))
+            continue;
+        rows.push(row);
+        if (rows.length === FOUND_MAX)
+            break;
+    }
+    return rows;
+}
+/**
+ * Places called something like this, best first — or null when the world
+ * could not be asked. An empty list is an answer: nothing is called that.
+ *
+ * Asked in the local language: what a sign in that street says is what a
+ * worker standing in it will read, and one answer per query is what lets
+ * the route in front of this cache it.
+ */
+export async function searchPlaces(query, reach = {}) {
+    const asked = query.replace(/\s+/g, " ").trim().slice(0, QUERY_MAX);
+    if (asked.length < 2)
+        return [];
+    const call = reach.fetch ?? globalThis.fetch;
+    const url = `${ENDPOINT}?q=${encodeURIComponent(asked)}&format=jsonv2&limit=${FOUND_MAX}&addressdetails=1`;
+    try {
+        const response = await call(url, {
+            headers: { "user-agent": USER_AGENT, accept: "application/json" },
+            signal: AbortSignal.timeout(TIMEOUT_MS)
+        });
+        if (!response.ok)
+            return null;
+        return foundFrom(await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=search.js.map

package/dist/esm/geo/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/geo/search.ts"],"names":[],"mappings":"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"}

package/dist/esm/geo/sun.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where the sun was, from a place and a moment — with no service at all.
+ *
+ * A person who says "it was getting dark" at local noon in June has said
+ * something the sky can contradict, and contradicting it costs nothing: sunrise
+ * and sunset are arithmetic, not data. So this is about sixty lines of NOAA's
+ * solar-position algorithm rather than an API key, a rate limit and a
+ * dependency that can be down at the moment somebody needs paying.
+ *
+ * The same argument `exif.ts` already makes for its own parser: a small, exact,
+ * offline thing beats a large, general, remote one when the question is this
+ * narrow.
+ *
+ * Accurate to about a minute, which is far inside what any claim about
+ * daylight could hinge on.
+ */
+/** The sun's position in the sky, as angles. */
+export interface SunPosition {
+    /** Degrees above the horizon. Negative is below it. */
+    altitude: number;
+    /** Degrees clockwise from north — where a shadow points away from. */
+    azimuth: number;
+}
+export declare function sunPosition(at: Date, lat: number, lon: number): SunPosition;
+/**
+ * What the sky was doing, in the words a person would use.
+ *
+ * The bands are the standard ones and the boundaries matter: **civil twilight
+ * ends at −6°**, and between 0° and −6° it is genuinely arguable whether
+ * somebody calls it day or night. That band is `dusk`, and no gate should fail
+ * a claim inside it — the whole point of a falsifier is that it only speaks
+ * where the world is unambiguous.
+ */
+export type SkyState = "day" | "dusk" | "night";
+export declare function skyAt(at: Date, lat: number, lon: number): {
+    state: SkyState;
+    altitude: number;
+};
+//# sourceMappingURL=sun.d.ts.map

package/dist/esm/geo/sun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sun.d.ts","sourceRoot":"","sources":["../../../src/geo/sun.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAuB3E;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhD,wBAAgB,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAQ/F"}