@ixo/openhands-sdk 0.0.0-stage → 0.2.0

package/dist/cjs/geo/place.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nameForGeometry = void 0;
+exports.labelFrom = labelFrom;
+exports.clean = clean;
+exports.placeName = placeName;
+const tiles_ts_1 = require("./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.
+ */
+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.
+ */
+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.
+ */
+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. */
+const nameForGeometry = (geometry, reach = {}) => placeName((0, tiles_ts_1.centreOf)(geometry), (0, tiles_ts_1.zoomForMetres)((0, tiles_ts_1.spanOf)(geometry)), reach);
+exports.nameForGeometry = nameForGeometry;
+//# sourceMappingURL=place.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../../src/geo/place.ts"],"names":[],"mappings":";;;AA6DA,8BAgBC;AASD,sBAMC;AAcD,8BAiBC;AA3HD,yCAA4E;AAE5E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0EAA0E;AAC1E,MAAM,UAAU,GAAG,6EAA6E,CAAC;AAEjG,MAAM,QAAQ,GAAG,6CAA6C,CAAC;AAE/D,kFAAkF;AAClF,MAAM,UAAU,GAAG,KAAK,CAAC;AAEzB,yEAAyE;AACzE,MAAM,UAAU,GAAG,EAAE,CAAC;AAiBtB;;;;;;;GAOG;AACH,SAAgB,SAAS,CAAC,OAA4B,EAAE,QAAiB;IACvE,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAClH,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC;IAC3F;sCACkC;IAClC,MAAM,KAAK,GAAG,UAAU,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAE/E;;uDAEmD;IACnD,MAAM,KAAK,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3G,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC;IAE/H,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,KAAK,CAAC,GAA8B;IAClD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,2EAA2E;IAC3E,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,oCAAoC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChG,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC;AAC1F,CAAC;AAOD;;;;;;GAMG;AACI,KAAK,UAAU,SAAS,CAAC,KAAmC,EAAE,IAAY,EAAE,QAAe,EAAE;IAClG,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAC7C,MAAM,GAAG,GAAG,GAAG,QAAQ,QAAQ,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;IAEnJ,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE;YAC/B,OAAO,EAAE,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE;YACjE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC;SACxC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAE9B,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyC,CAAC;QAC7E,OAAO,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;QACxD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8EAA8E;AACvE,MAAM,eAAe,GAAG,CAAC,QAAkB,EAAE,QAAe,EAAE,EAA0B,EAAE,CAAC,SAAS,CAAC,IAAA,mBAAQ,EAAC,QAAQ,CAAC,EAAE,IAAA,wBAAa,EAAC,IAAA,iBAAM,EAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAA3J,QAAA,eAAe,mBAA4I"}

package/dist/cjs/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/cjs/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/cjs/geo/search.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUERY_MAX = exports.FOUND_MAX = void 0;
+exports.foundFrom = foundFrom;
+exports.searchPlaces = searchPlaces;
+const place_ts_1 = require("./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. */
+exports.FOUND_MAX = 5;
+/** A query is a place name, not a paragraph. */
+exports.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 = (0, place_ts_1.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 = (0, place_ts_1.clean)(raw.name) ?? (0, place_ts_1.clean)(raw.display_name?.split(",")[0]);
+    if (!name)
+        return null;
+    const address = raw.address ?? {};
+    const kind = kindOf(raw);
+    const settlement = (0, place_ts_1.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 = (0, place_ts_1.clean)(address.state);
+    const country = (0, place_ts_1.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 = (0, place_ts_1.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.
+ */
+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 === exports.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.
+ */
+async function searchPlaces(query, reach = {}) {
+    const asked = query.replace(/\s+/g, " ").trim().slice(0, exports.QUERY_MAX);
+    if (asked.length < 2)
+        return [];
+    const call = reach.fetch ?? globalThis.fetch;
+    const url = `${ENDPOINT}?q=${encodeURIComponent(asked)}&format=jsonv2&limit=${exports.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/cjs/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/cjs/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/cjs/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"}

package/dist/cjs/geo/sun.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sunPosition = sunPosition;
+exports.skyAt = skyAt;
+const RAD = Math.PI / 180;
+const DEG = 180 / Math.PI;
+/** Days since the J2000.0 epoch, the zero point every term below is measured from. */
+const daysSinceJ2000 = (at) => at.getTime() / 86_400_000 - 10_957.5;
+function sunPosition(at, lat, lon) {
+    const d = daysSinceJ2000(at);
+    /* The sun's apparent path: mean anomaly, then the ecliptic longitude that
+       the equation of centre corrects it into. */
+    const meanAnomaly = (357.5291 + 0.98560028 * d) * RAD;
+    const centre = (1.9148 * Math.sin(meanAnomaly) + 0.02 * Math.sin(2 * meanAnomaly) + 0.0003 * Math.sin(3 * meanAnomaly)) * RAD;
+    const eclipticLongitude = meanAnomaly + centre + 102.9372 * RAD + Math.PI;
+    /* Onto the equator, which is the frame an observer on the ground shares. */
+    const obliquity = 23.4397 * RAD;
+    const declination = Math.asin(Math.sin(obliquity) * Math.sin(eclipticLongitude));
+    const rightAscension = Math.atan2(Math.cos(obliquity) * Math.sin(eclipticLongitude), Math.cos(eclipticLongitude));
+    /* And into the observer's own sky. */
+    const siderealTime = (280.16 + 360.9856235 * d) * RAD + lon * RAD;
+    const hourAngle = siderealTime - rightAscension;
+    const latRad = lat * RAD;
+    const altitude = Math.asin(Math.sin(latRad) * Math.sin(declination) + Math.cos(latRad) * Math.cos(declination) * Math.cos(hourAngle));
+    const azimuth = Math.atan2(Math.sin(hourAngle), Math.cos(hourAngle) * Math.sin(latRad) - Math.tan(declination) * Math.cos(latRad));
+    return { altitude: altitude * DEG, azimuth: ((azimuth * DEG + 180) % 360 + 360) % 360 };
+}
+function skyAt(at, lat, lon) {
+    const { altitude } = sunPosition(at, lat, lon);
+    /* Above the horizon: daylight, and the sun is visible. */
+    if (altitude > 0)
+        return { state: "day", altitude };
+    /* Civil twilight — bright enough to read by, dark enough to call evening.
+       Neither word is wrong here, so nothing is failed on it. */
+    if (altitude > -6)
+        return { state: "dusk", altitude };
+    return { state: "night", altitude };
+}
+//# sourceMappingURL=sun.js.map

package/dist/cjs/geo/sun.js.map

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

package/dist/cjs/geo/tiles.d.ts

@@ -0,0 +1,89 @@
+import { type GeoBox, type GeoPoint } from "./box.ts";
+export declare const TILE_PIXELS = 256;
+/** How far one pixel reaches on the ground — the number every overlay needs. */
+export declare const metresPerPixel: (lat: number, zoom: number) => number;
+/** Where a coordinate falls in the tile grid, as fractions of a tile. */
+export declare function tileFor(point: GeoPoint, zoom: number): {
+    x: number;
+    y: number;
+};
+/**
+ * How close to look.
+ *
+ * Chosen so the thing being described fills a useful part of the frame: a
+ * doorway-sized radius wants a street, a city-sized box wants a city. The same
+ * ladder decides how specific a place name to ask for, so the words and the
+ * picture always agree about scale.
+ */
+export declare function zoomForMetres(across: number): number;
+/** The two shapes an ask can describe. */
+export type Geometry = {
+    kind: "radius";
+    lat: number;
+    lon: number;
+    meters: number;
+} | {
+    kind: "box";
+    box: GeoBox;
+};
+/** A radius' centre, or a box's — one point to build a frame around. */
+export declare const centreOf: (geometry: Geometry) => GeoPoint;
+/** How wide the thing is, in metres — the input to `zoomForMetres`. */
+export declare const spanOf: (geometry: Geometry) => number;
+export interface Frame {
+    zoom: number;
+    /** The tiles that fall inside the window, each with its offset in it. */
+    tiles: {
+        x: number;
+        y: number;
+        left: number;
+        top: number;
+    }[];
+    /** Frame size in CSS pixels — two tiles square. */
+    width: number;
+    height: number;
+    /** Where the centre lands inside the frame. Always the middle, by construction. */
+    marker: {
+        x: number;
+        y: number;
+    };
+    /** What to draw around it, already in frame pixels. */
+    overlay: {
+        kind: "circle";
+        radius: number;
+    } | {
+        kind: "rect";
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
+/**
+ * The picture, worked out completely before anything is fetched.
+ *
+ * A **window centred on the target**, not a block of tiles the target happens
+ * to fall inside. The difference is the whole quality of the thing: anchoring
+ * a 2×2 block on a floored tile leaves the point anywhere in the middle half
+ * of the frame, and a map whose subject sits up and to the left reads as a
+ * mistake even when every coordinate in it is right. So the window is placed
+ * first, and the tiles that intersect it are worked out afterwards — the
+ * arithmetic every slippy map does, minus the scrolling.
+ *
+ * That costs between four and nine tiles depending on where the point falls
+ * inside its own tile, usually six. Still one small lazy grid per page,
+ * cached for a week at the edge, and still no JavaScript to assemble.
+ *
+ * The zoom steps down while the geometry does not comfortably fit, so a large
+ * area is never clipped by the frame that is supposed to explain it.
+ */
+export declare function frameFor(geometry: Geometry, maxZoom?: number): Frame;
+/** The geometry a gate describes, if it describes one. Shape-only, no imports. */
+export declare function geometryOfGate(gate: {
+    id?: string;
+    lat?: number;
+    lon?: number;
+    meters?: number;
+    box?: GeoBox;
+}): Geometry | null;
+//# sourceMappingURL=tiles.d.ts.map

package/dist/cjs/geo/tiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiles.d.ts","sourceRoot":"","sources":["../../../src/geo/tiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAqBvE,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,gFAAgF;AAChF,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,KAAG,MAAkF,CAAC;AAE9I,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAM/E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED,0CAA0C;AAC1C,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnH,wEAAwE;AACxE,eAAO,MAAM,QAAQ,GAAI,UAAU,QAAQ,KAAG,QACoI,CAAC;AAEnL,uEAAuE;AACvE,eAAO,MAAM,MAAM,GAAI,UAAU,QAAQ,KAAG,MAGmF,CAAC;AAEhI,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7D,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,uDAAuD;IACvD,OAAO,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5H;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,SAAK,GAAG,KAAK,CA2DhE;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,GAAG,IAAI,CAMhI"}