@motionscript/geo 0.0.0-stage → 0.1.0-alpha.0

package/dist/globe/globe-places.d.ts

@@ -0,0 +1,140 @@
+/**
+ * What an author places on a Globe — the marked points, and the arcs between
+ * them — as the panel edits them and the stored field holds them.
+ *
+ * Beside `graph-equations.ts` and shaped like it, because it is the same
+ * problem: an appearance value is `number | string | boolean`, so a *list* has
+ * to arrive as one string that a mapper reads. What lives here is the authored
+ * shape and its serialization, shared by the inspector's tiles and the node's
+ * builder; what a frame actually draws is `nodes/globe/impl/places.ts`, which
+ * resolves this into coordinates and clamps it to what the render can use.
+ *
+ * The split matters in one direction: **reading must be faithful and must not
+ * mint identity**. The panel reads on every render and the builder on every
+ * rebuild, so a random id here would be a different id every time — and two
+ * things key off it (a tile's React key, and which arc endpoint points at which
+ * marker). {@link createMarker} mints ids; the readers derive a positional one
+ * and never invent.
+ */
+/**
+ * A marked point on the surface.
+ *
+ * `label` is **not drawn**. It names the tile in the inspector and the entries
+ * in an arc's endpoint menus, which is the whole of its job today — a label
+ * rendered against the globe is a separate problem (it has to face the camera,
+ * hide when it rotates behind the planet, and not collide with its neighbours),
+ * and storing the text now is what lets that arrive without a migration.
+ */
+export interface GlobeMarker {
+    /** Identity across list edits — a tween matches like with like. */
+    id: string;
+    /** A name for this place. Editor-facing only; see the note above. */
+    label: string;
+    /** Degrees north, −90…90. */
+    lat: number;
+    /** Degrees east, −180…180. */
+    lon: number;
+    /** Any colour string the fill parser takes. Empty means the palette entry. */
+    color: string;
+    /** Radius as a fraction of the globe's own. */
+    size: number;
+    /** 0–1. A fade, unlike {@link enabled}, which is a switch. */
+    opacity: number;
+    /** Whether it draws. Off keeps the tile in place, editable, with its colour. */
+    enabled: boolean;
+}
+/**
+ * One end of an arc: a marker it is pinned to, or a place of its own.
+ *
+ * The pinned form is the one the tile offers first, and it is not merely
+ * convenient — an arc between two *marked* places moves when the place does,
+ * where a copied pair of coordinates silently stops matching the dot it was
+ * drawn to. That is the same reasoning a state machine's connection names its
+ * ends by state id rather than by position.
+ *
+ * The free form stays because not every end wants a dot on it, and because a
+ * list written by hand or by an agent reaches for a coordinate pair first.
+ */
+export type ArcEnd = {
+    readonly kind: "marker";
+    readonly markerId: string;
+} | {
+    readonly kind: "place";
+    readonly lat: number;
+    readonly lon: number;
+};
+/** A great-circle path between two ends. */
+export interface GlobeArc {
+    id: string;
+    from: ArcEnd;
+    to: ArcEnd;
+    color: string;
+    /** Tube radius as a fraction of the globe's own. */
+    width: number;
+    /** How far the middle lifts off the surface, as a fraction of the radius. */
+    lift: number;
+    /**
+     * How much of the path is drawn, 0–1 — a line that draws itself on.
+     *
+     * A fraction of the *path* rather than a time, so it means the same thing
+     * whatever the arc's length and is the author's to tween from wherever they
+     * like. Zero draws nothing and is not an error.
+     */
+    progress: number;
+    enabled: boolean;
+}
+/**
+ * The palette an uncoloured marker takes its colour from, by position.
+ *
+ * Warm-to-cool rather than a spectrum: markers are read against a dark ocean and
+ * usually mean something ranked — the first is the subject and the rest are
+ * context — so the order runs from the one that carries furthest to the one that
+ * recedes. Six, then it wraps; a seventh place that has to stand out sets its
+ * own colour.
+ */
+export declare const DEFAULT_MARKER_COLORS: readonly ["#ff3b30", "#ff9f0a", "#ffd60a", "#30d158", "#5ac8fa", "#bf5af2"];
+/** The colour a marker at `index` is drawn in when it names none. */
+export declare function markerColorAt(index: number): string;
+/** The colour an arc falls back to. */
+export declare const DEFAULT_ARC_COLOR = "#ffd60a";
+/** A new marker tile: showing, opaque, and at the given place. */
+export declare function createMarker(at?: {
+    lat: number;
+    lon: number;
+}): GlobeMarker;
+/** A new arc tile, between two ends. */
+export declare function createArc(from: ArcEnd, to: ArcEnd): GlobeArc;
+/** An end pinned to a marker. */
+export declare function markerEnd(markerId: string): ArcEnd;
+/** An end at a place of its own. */
+export declare function placeEnd(lat: number, lon: number): ArcEnd;
+/**
+ * Reads a stored marker list, defensively.
+ *
+ * Never throws, and drops only what it genuinely cannot place: the field is
+ * edited a keystroke at a time by hand as well as through the tiles, so it is
+ * invalid far more often than it is valid, and a reader that threw would blank
+ * the canvas on the way from `[` to `[{`.
+ *
+ * A row with **no position at all** is the one thing that is dropped rather than
+ * defaulted. Every other field has an honest default; a latitude does not, and
+ * putting an unplaced marker on the equator would draw a dot somewhere nobody
+ * asked for and call it the author's.
+ */
+export declare function markersOf(value: unknown): GlobeMarker[];
+/** Reads a stored arc list, on the same terms as {@link markersOf}. */
+export declare function arcsOf(value: unknown): GlobeArc[];
+/** Serializes a marker list into the stored string form. */
+export declare function markersToValue(markers: readonly GlobeMarker[]): string;
+/**
+ * Serializes an arc list, writing each end back in the shape it was authored in.
+ *
+ * A pinned end is a bare **string** and a free one a `[lat, lon]` **pair**,
+ * rather than the tagged union this module works in. Two reasons, and the second
+ * is the load-bearing one: those are the two shapes somebody writing this list
+ * by hand reaches for, and a stored document is read by whatever version opens
+ * it later — so the wire form is public API and a discriminant that only exists
+ * to make the TypeScript convenient does not belong in it.
+ */
+export declare function arcsToValue(arcs: readonly GlobeArc[]): string;
+//# sourceMappingURL=globe-places.d.ts.map

package/dist/globe/globe-places.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globe-places.d.ts","sourceRoot":"","sources":["../../src/globe/globe-places.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAA;IACV,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1E,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,6EAOxB,CAAA;AAEV,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,YAAY,CAAA;AAuB1C,kEAAkE;AAClE,wBAAgB,YAAY,CAC1B,EAAE,GAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAuB,GACpD,WAAW,CAWb;AAED,wCAAwC;AACxC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAW5D;AAED,iCAAiC;AACjC,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,oCAAoC;AACpC,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,EAAE,CAoBvD;AAED,uEAAuE;AACvE,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,CAkBjD;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAEtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAI7D"}

package/dist/globe/globe-places.js

@@ -0,0 +1,262 @@
+/**
+ * What an author places on a Globe — the marked points, and the arcs between
+ * them — as the panel edits them and the stored field holds them.
+ *
+ * Beside `graph-equations.ts` and shaped like it, because it is the same
+ * problem: an appearance value is `number | string | boolean`, so a *list* has
+ * to arrive as one string that a mapper reads. What lives here is the authored
+ * shape and its serialization, shared by the inspector's tiles and the node's
+ * builder; what a frame actually draws is `nodes/globe/impl/places.ts`, which
+ * resolves this into coordinates and clamps it to what the render can use.
+ *
+ * The split matters in one direction: **reading must be faithful and must not
+ * mint identity**. The panel reads on every render and the builder on every
+ * rebuild, so a random id here would be a different id every time — and two
+ * things key off it (a tile's React key, and which arc endpoint points at which
+ * marker). {@link createMarker} mints ids; the readers derive a positional one
+ * and never invent.
+ */
+/**
+ * The palette an uncoloured marker takes its colour from, by position.
+ *
+ * Warm-to-cool rather than a spectrum: markers are read against a dark ocean and
+ * usually mean something ranked — the first is the subject and the rest are
+ * context — so the order runs from the one that carries furthest to the one that
+ * recedes. Six, then it wraps; a seventh place that has to stand out sets its
+ * own colour.
+ */
+export const DEFAULT_MARKER_COLORS = [
+    "#ff3b30",
+    "#ff9f0a",
+    "#ffd60a",
+    "#30d158",
+    "#5ac8fa",
+    "#bf5af2",
+];
+/** The colour a marker at `index` is drawn in when it names none. */
+export function markerColorAt(index) {
+    const palette = DEFAULT_MARKER_COLORS;
+    return palette[((index % palette.length) + palette.length) % palette.length];
+}
+/** The colour an arc falls back to. */
+export const DEFAULT_ARC_COLOR = "#ffd60a";
+const DEFAULT_MARKER_SIZE = 0.02;
+const DEFAULT_ARC_WIDTH = 0.004;
+const DEFAULT_ARC_LIFT = 0.25;
+/**
+ * A fresh id for a tile.
+ *
+ * A counter plus a short random suffix rather than `crypto.randomUUID`, exactly
+ * as `graph-equations.ts` explains: this package loads in a bare Node process
+ * with no DOM and no assumed globals, and an id only has to be unique within one
+ * node's list. The suffix is what stops two clients editing the same scene
+ * colliding on `mk-3`.
+ *
+ * Never called during a build — only when an author adds a tile.
+ */
+let placeSeq = 0;
+function nextId(prefix) {
+    placeSeq += 1;
+    return `${prefix}-${placeSeq}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/** A new marker tile: showing, opaque, and at the given place. */
+export function createMarker(at = { lat: 0, lon: 0 }) {
+    return {
+        id: nextId("mk"),
+        label: "",
+        lat: at.lat,
+        lon: at.lon,
+        color: "",
+        size: DEFAULT_MARKER_SIZE,
+        opacity: 1,
+        enabled: true,
+    };
+}
+/** A new arc tile, between two ends. */
+export function createArc(from, to) {
+    return {
+        id: nextId("arc"),
+        from,
+        to,
+        color: DEFAULT_ARC_COLOR,
+        width: DEFAULT_ARC_WIDTH,
+        lift: DEFAULT_ARC_LIFT,
+        progress: 1,
+        enabled: true,
+    };
+}
+/** An end pinned to a marker. */
+export function markerEnd(markerId) {
+    return { kind: "marker", markerId };
+}
+/** An end at a place of its own. */
+export function placeEnd(lat, lon) {
+    return { kind: "place", lat, lon };
+}
+// --- Reading ---------------------------------------------------------------
+/**
+ * Reads a stored marker list, defensively.
+ *
+ * Never throws, and drops only what it genuinely cannot place: the field is
+ * edited a keystroke at a time by hand as well as through the tiles, so it is
+ * invalid far more often than it is valid, and a reader that threw would blank
+ * the canvas on the way from `[` to `[{`.
+ *
+ * A row with **no position at all** is the one thing that is dropped rather than
+ * defaulted. Every other field has an honest default; a latitude does not, and
+ * putting an unplaced marker on the equator would draw a dot somewhere nobody
+ * asked for and call it the author's.
+ */
+export function markersOf(value) {
+    return rowsOf(value).flatMap((row, index) => {
+        const lat = finite(row.lat ?? row.latitude);
+        const lon = finite(row.lon ?? row.lng ?? row.longitude);
+        if (lat === null || lon === null)
+            return [];
+        return [
+            {
+                id: idOf(row.id, `mk:${index}`),
+                label: text(row.label ?? row.name) ?? "",
+                lat: clamp(lat, -90, 90),
+                lon: wrapLongitude(lon),
+                color: text(row.color) ?? "",
+                size: positive(row.size, DEFAULT_MARKER_SIZE),
+                opacity: unit(row.opacity),
+                // Absent means on, as everywhere else a switch is stored: only an
+                // explicit `false` turns a tile off.
+                enabled: row.enabled !== false,
+            },
+        ];
+    });
+}
+/** Reads a stored arc list, on the same terms as {@link markersOf}. */
+export function arcsOf(value) {
+    return rowsOf(value).flatMap((row, index) => {
+        const from = endOf(row.from);
+        const to = endOf(row.to);
+        if (!from || !to)
+            return [];
+        return [
+            {
+                id: idOf(row.id, `arc:${index}`),
+                from,
+                to,
+                color: text(row.color) ?? DEFAULT_ARC_COLOR,
+                width: positive(row.width, DEFAULT_ARC_WIDTH),
+                lift: clamp(finite(row.lift) ?? DEFAULT_ARC_LIFT, 0, 4),
+                progress: unit(row.progress),
+                enabled: row.enabled !== false,
+            },
+        ];
+    });
+}
+/** Serializes a marker list into the stored string form. */
+export function markersToValue(markers) {
+    return JSON.stringify(markers);
+}
+/**
+ * Serializes an arc list, writing each end back in the shape it was authored in.
+ *
+ * A pinned end is a bare **string** and a free one a `[lat, lon]` **pair**,
+ * rather than the tagged union this module works in. Two reasons, and the second
+ * is the load-bearing one: those are the two shapes somebody writing this list
+ * by hand reaches for, and a stored document is read by whatever version opens
+ * it later — so the wire form is public API and a discriminant that only exists
+ * to make the TypeScript convenient does not belong in it.
+ */
+export function arcsToValue(arcs) {
+    return JSON.stringify(arcs.map((arc) => ({ ...arc, from: endToValue(arc.from), to: endToValue(arc.to) })));
+}
+function endToValue(end) {
+    return end.kind === "marker" ? end.markerId : [end.lat, end.lon];
+}
+/**
+ * One end, from any of the three shapes a stored list holds it in.
+ *
+ * A **string** is a marker id; a **pair** is `[lat, lon]`, which is how a
+ * coordinate is written everywhere outside a program; an **object** with `lat`
+ * and `lon` is the long form. Refusing any of them would make the field's most
+ * obvious content its most surprising failure.
+ */
+function endOf(value) {
+    if (typeof value === "string") {
+        return value.trim() === "" ? null : markerEnd(value);
+    }
+    if (Array.isArray(value)) {
+        const lat = finite(value[0]);
+        const lon = finite(value[1]);
+        return lat === null || lon === null
+            ? null
+            : placeEnd(clamp(lat, -90, 90), wrapLongitude(lon));
+    }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const row = value;
+    if (typeof row.markerId === "string")
+        return markerEnd(row.markerId);
+    const lat = finite(row.lat ?? row.latitude);
+    const lon = finite(row.lon ?? row.lng ?? row.longitude);
+    return lat === null || lon === null
+        ? null
+        : placeEnd(clamp(lat, -90, 90), wrapLongitude(lon));
+}
+function rowsOf(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((row) => typeof row === "object" && row !== null);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * A row's identity, or one derived from where it sits.
+ *
+ * Positional rather than random, and the difference is the whole point: a random
+ * id here would be a different one on every read, and both the tile's React key
+ * and an arc's pin to a marker would change under the author's hands.
+ */
+function idOf(value, positional) {
+    return text(value) ?? positional;
+}
+function text(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/** A stored 0–1 value; anything unreadable is fully on. */
+function unit(value) {
+    const n = finite(value);
+    return n === null ? 1 : clamp(n, 0, 1);
+}
+/** A stored size, which must be above zero to draw at all. */
+function positive(value, fallback) {
+    const n = finite(value);
+    return n === null || n <= 0 ? fallback : n;
+}
+/**
+ * A longitude into −180…180.
+ *
+ * Wrapped rather than clamped, unlike latitude: 190°E is a real place (170°W)
+ * and clamping would put it on the antimeridian, where there is nothing north of
+ * the north pole for a latitude to mean.
+ *
+ * A value already in range is returned untouched — the modulo round-trip is not
+ * exact in binary floating point (139.7 comes back as 139.70000000000005), and a
+ * stored longitude that differs from the one the author typed shows up later as
+ * a diff nobody made.
+ */
+function wrapLongitude(value) {
+    if (value >= -180 && value <= 180)
+        return value;
+    return ((((value + 180) % 360) + 360) % 360) - 180;
+}
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+//# sourceMappingURL=globe-places.js.map

package/dist/globe/globe-places.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"globe-places.js","sourceRoot":"","sources":["../../src/globe/globe-places.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an author places on a Globe — the marked points, and the arcs between\n * them — as the panel edits them and the stored field holds them.\n *\n * Beside `graph-equations.ts` and shaped like it, because it is the same\n * problem: an appearance value is `number | string | boolean`, so a *list* has\n * to arrive as one string that a mapper reads. What lives here is the authored\n * shape and its serialization, shared by the inspector's tiles and the node's\n * builder; what a frame actually draws is `nodes/globe/impl/places.ts`, which\n * resolves this into coordinates and clamps it to what the render can use.\n *\n * The split matters in one direction: **reading must be faithful and must not\n * mint identity**. The panel reads on every render and the builder on every\n * rebuild, so a random id here would be a different id every time — and two\n * things key off it (a tile's React key, and which arc endpoint points at which\n * marker). {@link createMarker} mints ids; the readers derive a positional one\n * and never invent.\n */\n\n/**\n * A marked point on the surface.\n *\n * `label` is **not drawn**. It names the tile in the inspector and the entries\n * in an arc's endpoint menus, which is the whole of its job today — a label\n * rendered against the globe is a separate problem (it has to face the camera,\n * hide when it rotates behind the planet, and not collide with its neighbours),\n * and storing the text now is what lets that arrive without a migration.\n */\nexport interface GlobeMarker {\n  /** Identity across list edits — a tween matches like with like. */\n  id: string\n  /** A name for this place. Editor-facing only; see the note above. */\n  label: string\n  /** Degrees north, −90…90. */\n  lat: number\n  /** Degrees east, −180…180. */\n  lon: number\n  /** Any colour string the fill parser takes. Empty means the palette entry. */\n  color: string\n  /** Radius as a fraction of the globe's own. */\n  size: number\n  /** 0–1. A fade, unlike {@link enabled}, which is a switch. */\n  opacity: number\n  /** Whether it draws. Off keeps the tile in place, editable, with its colour. */\n  enabled: boolean\n}\n\n/**\n * One end of an arc: a marker it is pinned to, or a place of its own.\n *\n * The pinned form is the one the tile offers first, and it is not merely\n * convenient — an arc between two *marked* places moves when the place does,\n * where a copied pair of coordinates silently stops matching the dot it was\n * drawn to. That is the same reasoning a state machine's connection names its\n * ends by state id rather than by position.\n *\n * The free form stays because not every end wants a dot on it, and because a\n * list written by hand or by an agent reaches for a coordinate pair first.\n */\nexport type ArcEnd =\n  | { readonly kind: \"marker\"; readonly markerId: string }\n  | { readonly kind: \"place\"; readonly lat: number; readonly lon: number }\n\n/** A great-circle path between two ends. */\nexport interface GlobeArc {\n  id: string\n  from: ArcEnd\n  to: ArcEnd\n  color: string\n  /** Tube radius as a fraction of the globe's own. */\n  width: number\n  /** How far the middle lifts off the surface, as a fraction of the radius. */\n  lift: number\n  /**\n   * How much of the path is drawn, 0–1 — a line that draws itself on.\n   *\n   * A fraction of the *path* rather than a time, so it means the same thing\n   * whatever the arc's length and is the author's to tween from wherever they\n   * like. Zero draws nothing and is not an error.\n   */\n  progress: number\n  enabled: boolean\n}\n\n/**\n * The palette an uncoloured marker takes its colour from, by position.\n *\n * Warm-to-cool rather than a spectrum: markers are read against a dark ocean and\n * usually mean something ranked — the first is the subject and the rest are\n * context — so the order runs from the one that carries furthest to the one that\n * recedes. Six, then it wraps; a seventh place that has to stand out sets its\n * own colour.\n */\nexport const DEFAULT_MARKER_COLORS = [\n  \"#ff3b30\",\n  \"#ff9f0a\",\n  \"#ffd60a\",\n  \"#30d158\",\n  \"#5ac8fa\",\n  \"#bf5af2\",\n] as const\n\n/** The colour a marker at `index` is drawn in when it names none. */\nexport function markerColorAt(index: number): string {\n  const palette = DEFAULT_MARKER_COLORS\n  return palette[((index % palette.length) + palette.length) % palette.length]!\n}\n\n/** The colour an arc falls back to. */\nexport const DEFAULT_ARC_COLOR = \"#ffd60a\"\n\nconst DEFAULT_MARKER_SIZE = 0.02\nconst DEFAULT_ARC_WIDTH = 0.004\nconst DEFAULT_ARC_LIFT = 0.25\n\n/**\n * A fresh id for a tile.\n *\n * A counter plus a short random suffix rather than `crypto.randomUUID`, exactly\n * as `graph-equations.ts` explains: this package loads in a bare Node process\n * with no DOM and no assumed globals, and an id only has to be unique within one\n * node's list. The suffix is what stops two clients editing the same scene\n * colliding on `mk-3`.\n *\n * Never called during a build — only when an author adds a tile.\n */\nlet placeSeq = 0\nfunction nextId(prefix: string): string {\n  placeSeq += 1\n  return `${prefix}-${placeSeq}-${Math.random().toString(36).slice(2, 8)}`\n}\n\n/** A new marker tile: showing, opaque, and at the given place. */\nexport function createMarker(\n  at: { lat: number; lon: number } = { lat: 0, lon: 0 }\n): GlobeMarker {\n  return {\n    id: nextId(\"mk\"),\n    label: \"\",\n    lat: at.lat,\n    lon: at.lon,\n    color: \"\",\n    size: DEFAULT_MARKER_SIZE,\n    opacity: 1,\n    enabled: true,\n  }\n}\n\n/** A new arc tile, between two ends. */\nexport function createArc(from: ArcEnd, to: ArcEnd): GlobeArc {\n  return {\n    id: nextId(\"arc\"),\n    from,\n    to,\n    color: DEFAULT_ARC_COLOR,\n    width: DEFAULT_ARC_WIDTH,\n    lift: DEFAULT_ARC_LIFT,\n    progress: 1,\n    enabled: true,\n  }\n}\n\n/** An end pinned to a marker. */\nexport function markerEnd(markerId: string): ArcEnd {\n  return { kind: \"marker\", markerId }\n}\n\n/** An end at a place of its own. */\nexport function placeEnd(lat: number, lon: number): ArcEnd {\n  return { kind: \"place\", lat, lon }\n}\n\n// --- Reading ---------------------------------------------------------------\n\n/**\n * Reads a stored marker list, defensively.\n *\n * Never throws, and drops only what it genuinely cannot place: the field is\n * edited a keystroke at a time by hand as well as through the tiles, so it is\n * invalid far more often than it is valid, and a reader that threw would blank\n * the canvas on the way from `[` to `[{`.\n *\n * A row with **no position at all** is the one thing that is dropped rather than\n * defaulted. Every other field has an honest default; a latitude does not, and\n * putting an unplaced marker on the equator would draw a dot somewhere nobody\n * asked for and call it the author's.\n */\nexport function markersOf(value: unknown): GlobeMarker[] {\n  return rowsOf(value).flatMap((row, index) => {\n    const lat = finite(row.lat ?? row.latitude)\n    const lon = finite(row.lon ?? row.lng ?? row.longitude)\n    if (lat === null || lon === null) return []\n    return [\n      {\n        id: idOf(row.id, `mk:${index}`),\n        label: text(row.label ?? row.name) ?? \"\",\n        lat: clamp(lat, -90, 90),\n        lon: wrapLongitude(lon),\n        color: text(row.color) ?? \"\",\n        size: positive(row.size, DEFAULT_MARKER_SIZE),\n        opacity: unit(row.opacity),\n        // Absent means on, as everywhere else a switch is stored: only an\n        // explicit `false` turns a tile off.\n        enabled: row.enabled !== false,\n      },\n    ]\n  })\n}\n\n/** Reads a stored arc list, on the same terms as {@link markersOf}. */\nexport function arcsOf(value: unknown): GlobeArc[] {\n  return rowsOf(value).flatMap((row, index) => {\n    const from = endOf(row.from)\n    const to = endOf(row.to)\n    if (!from || !to) return []\n    return [\n      {\n        id: idOf(row.id, `arc:${index}`),\n        from,\n        to,\n        color: text(row.color) ?? DEFAULT_ARC_COLOR,\n        width: positive(row.width, DEFAULT_ARC_WIDTH),\n        lift: clamp(finite(row.lift) ?? DEFAULT_ARC_LIFT, 0, 4),\n        progress: unit(row.progress),\n        enabled: row.enabled !== false,\n      },\n    ]\n  })\n}\n\n/** Serializes a marker list into the stored string form. */\nexport function markersToValue(markers: readonly GlobeMarker[]): string {\n  return JSON.stringify(markers)\n}\n\n/**\n * Serializes an arc list, writing each end back in the shape it was authored in.\n *\n * A pinned end is a bare **string** and a free one a `[lat, lon]` **pair**,\n * rather than the tagged union this module works in. Two reasons, and the second\n * is the load-bearing one: those are the two shapes somebody writing this list\n * by hand reaches for, and a stored document is read by whatever version opens\n * it later — so the wire form is public API and a discriminant that only exists\n * to make the TypeScript convenient does not belong in it.\n */\nexport function arcsToValue(arcs: readonly GlobeArc[]): string {\n  return JSON.stringify(\n    arcs.map((arc) => ({ ...arc, from: endToValue(arc.from), to: endToValue(arc.to) }))\n  )\n}\n\nfunction endToValue(end: ArcEnd): string | [number, number] {\n  return end.kind === \"marker\" ? end.markerId : [end.lat, end.lon]\n}\n\n/**\n * One end, from any of the three shapes a stored list holds it in.\n *\n * A **string** is a marker id; a **pair** is `[lat, lon]`, which is how a\n * coordinate is written everywhere outside a program; an **object** with `lat`\n * and `lon` is the long form. Refusing any of them would make the field's most\n * obvious content its most surprising failure.\n */\nfunction endOf(value: unknown): ArcEnd | null {\n  if (typeof value === \"string\") {\n    return value.trim() === \"\" ? null : markerEnd(value)\n  }\n  if (Array.isArray(value)) {\n    const lat = finite(value[0])\n    const lon = finite(value[1])\n    return lat === null || lon === null\n      ? null\n      : placeEnd(clamp(lat, -90, 90), wrapLongitude(lon))\n  }\n  if (typeof value !== \"object\" || value === null) return null\n  const row = value as Record<string, unknown>\n  if (typeof row.markerId === \"string\") return markerEnd(row.markerId)\n  const lat = finite(row.lat ?? row.latitude)\n  const lon = finite(row.lon ?? row.lng ?? row.longitude)\n  return lat === null || lon === null\n    ? null\n    : placeEnd(clamp(lat, -90, 90), wrapLongitude(lon))\n}\n\n// --- Reading helpers -------------------------------------------------------\n\ntype Row = Record<string, unknown>\n\nfunction rowsOf(value: unknown): Row[] {\n  if (typeof value !== \"string\" || value.trim() === \"\") return []\n  try {\n    const parsed: unknown = JSON.parse(value)\n    if (!Array.isArray(parsed)) return []\n    return parsed.filter(\n      (row): row is Row => typeof row === \"object\" && row !== null\n    )\n  } catch {\n    return []\n  }\n}\n\n/**\n * A row's identity, or one derived from where it sits.\n *\n * Positional rather than random, and the difference is the whole point: a random\n * id here would be a different one on every read, and both the tile's React key\n * and an arc's pin to a marker would change under the author's hands.\n */\nfunction idOf(value: unknown, positional: string): string {\n  return text(value) ?? positional\n}\n\nfunction text(value: unknown): string | null {\n  return typeof value === \"string\" && value.trim() !== \"\" ? value : null\n}\n\nfunction finite(value: unknown): number | null {\n  return typeof value === \"number\" && Number.isFinite(value) ? value : null\n}\n\n/** A stored 0–1 value; anything unreadable is fully on. */\nfunction unit(value: unknown): number {\n  const n = finite(value)\n  return n === null ? 1 : clamp(n, 0, 1)\n}\n\n/** A stored size, which must be above zero to draw at all. */\nfunction positive(value: unknown, fallback: number): number {\n  const n = finite(value)\n  return n === null || n <= 0 ? fallback : n\n}\n\n/**\n * A longitude into −180…180.\n *\n * Wrapped rather than clamped, unlike latitude: 190°E is a real place (170°W)\n * and clamping would put it on the antimeridian, where there is nothing north of\n * the north pole for a latitude to mean.\n *\n * A value already in range is returned untouched — the modulo round-trip is not\n * exact in binary floating point (139.7 comes back as 139.70000000000005), and a\n * stored longitude that differs from the one the author typed shows up later as\n * a diff nobody made.\n */\nfunction wrapLongitude(value: number): number {\n  if (value >= -180 && value <= 180) return value\n  return ((((value + 180) % 360) + 360) % 360) - 180\n}\n\nfunction clamp(value: number, min: number, max: number): number {\n  return value < min ? min : value > max ? max : value\n}\n"]}

package/dist/globe/globe.d.ts

@@ -0,0 +1,193 @@
+import { type Command, type CommandArgs, Canvas3D, Scene3D, type Canvas3DProps, type Color, type NodeConfig } from "@motionscript/core";
+import { type OrbitTarget } from "@motionscript/core/component";
+export interface GlobeProps extends Canvas3DProps {
+    resolution: number;
+    ocean: Color;
+    land: Color;
+    border: Color;
+    borderWidth: number;
+    graticule: boolean;
+    graticuleColor: Color;
+    graticuleStep: number;
+    graticuleWidth: number;
+    orbit: number;
+    elevation: number;
+    zoom: number;
+    fov: number;
+    ambientIntensity: number;
+    ambientColor: Color;
+    keyIntensity: number;
+    keyColor: Color;
+    atmosphere: boolean;
+    atmosphereColor: Color;
+    atmosphereSize: number;
+    atmosphereFalloff: number;
+    atmosphereIntensity: number;
+    markers: string;
+    arcs: string;
+}
+/**
+ * A globe: country boundaries on a lit sphere, flown by an orbit camera.
+ *
+ *   <Globe width="fill" height="fill" orbit={20} elevation={25} zoom={2.6} />
+ *
+ * Like the Protein and unlike the Canvas 3D viewport, it draws **one subject**
+ * derived from its own props rather than being a room the author fills. Four
+ * things about it are worth knowing before reading the parts:
+ *
+ * **The map is a texture, drawn in 2D.** See `world-map.ts`: a WebGL line
+ * ignores any width above one pixel, so borders drawn as 3D lines are hairlines
+ * forever. Baked, a border is an ordinary Skia stroke at any weight.
+ *
+ * **That texture is cached against its style, and the cache is not an
+ * optimisation.** motion-script re-rasterizes a surface every frame unless the
+ * descriptor says otherwise, and re-rasterizing this one means redrawing ten
+ * thousand paths, stalling on a GPU read-back and re-uploading a few megabytes —
+ * sixty times a second, for an identical image. {@link bakedMap} holds one
+ * descriptor per style and marks it `static`; the schema then refuses to animate
+ * any field that style is made of, so an export cannot mint a raster per frame.
+ *
+ * **The camera is three tweenable numbers, and two of them are places.** `orbit`
+ * is a longitude and `elevation` is a latitude — see `projection.ts`, which is
+ * where that convention is established and defended. There is no `OrbitControls`
+ * here for the reason the other 3D nodes have none: a rendered timeline has no
+ * pointer, and every frame has to be reproducible under scrubbing and export.
+ *
+ * **Markers and arcs are real 3D, never baked.** They are the animated content;
+ * putting them in the texture would run every frame of a marker's fade through a
+ * full re-rasterize.
+ */
+export declare class Globe extends Canvas3D<GlobeProps> {
+    /**
+     * Texture width in pixels; the height is half of it.
+     *
+     * Structural, and capped in the schema rather than here. The buffer is
+     * re-uploaded to the GPU every frame even when its pixels are cached, so this
+     * is a per-frame bandwidth number as much as a sharpness one — 2048 is 8 MB a
+     * frame and already finer than the 110m boundaries it draws.
+     */
+    resolution: number;
+    ocean: Color;
+    land: Color;
+    /**
+     * The colour of every coast and border.
+     *
+     * Alpha works. It did not while the country paths carried the stroke — a
+     * border belongs to two countries, so it was drawn twice and came out at
+     * double density beside the coastlines. `borders.ts` deduplicates the lines
+     * and `world-map.ts` strokes them once.
+     */
+    border: Color;
+    borderWidth: number;
+    graticule: boolean;
+    graticuleColor: Color;
+    graticuleStep: number;
+    graticuleWidth: number;
+    /**
+     * The camera's heading, in degrees, in exactly the sense every other 3D node
+     * uses it — which is what keeps the canvas drag consistent with them.
+     *
+     * It is *not* a longitude: a camera at heading θ is centred over longitude −θ
+     * (see `orbitForLongitude` in `projection.ts`). Unbounded, like every other
+     * viewport's, because the drag wraps it into `[0, 360)` and a range here would
+     * clamp half of them.
+     */
+    orbit: number;
+    /**
+     * Degrees above the equator, which on a globe *is* the latitude the camera
+     * stands over — no conversion, unlike the heading. Held short of the poles by
+     * the schema, as every orbit camera's is.
+     */
+    elevation: number;
+    /** Distance from the centre, as a multiple of the globe's radius. */
+    zoom: number;
+    fov: number;
+    ambientIntensity: number;
+    ambientColor: Color;
+    keyIntensity: number;
+    keyColor: Color;
+    atmosphere: boolean;
+    atmosphereColor: Color;
+    /** The shell's radius as a multiple of the globe's. */
+    atmosphereSize: number;
+    /** How tightly the glow hugs the edge. Higher is a thinner rim. */
+    atmosphereFalloff: number;
+    atmosphereIntensity: number;
+    markers: string;
+    arcs: string;
+    constructor(props?: NodeConfig<Globe, GlobeProps>);
+    /**
+     * Frame the scene at a spherical camera placement. Every axis is optional,
+     * so "pull back" and "spin round" stay separate intentions — see
+     * {@link OrbitTarget}.
+     */
+    orbitTo(args: CommandArgs<{
+        target: OrbitTarget;
+    }> & {
+        duration: number;
+    }): Command<GlobeProps>;
+    /**
+     * Fly the camera to a place on the globe. `latitude`/`longitude` are the
+     * point to bring under the camera and `framing` the distance to settle at.
+     *
+     * **`arc` is what makes it a flight rather than a pan** — above `0` the
+     * distance bows outward at the midpoint by that fraction, so a long journey
+     * rises off the surface and settles back down rather than scraping the
+     * horizon the whole way. Longitude takes the **short way round**.
+     */
+    flyTo(args: CommandArgs<{
+        latitude: number;
+        longitude: number;
+        framing?: number;
+        arc?: number;
+    }> & {
+        duration?: number;
+    }): Command<GlobeProps>;
+    protected buildScene3D(): Scene3D;
+    /** The sphere, wearing the baked map. */
+    private addPlanet;
+    /** The halo. A shell, kept for its back faces — see `atmosphere.ts`. */
+    private addAtmosphere;
+    /**
+     * The markers, as one instanced draw.
+     *
+     * Instanced rather than a mesh apiece because a marker list is the one thing
+     * here with no ceiling — a network map is thousands of points, and a draw call
+     * each would not keep up. One geometry, one material, one upload.
+     *
+     * Note the material carries **no** `vertexColors`: an instanced mesh that asks
+     * for it makes the shader read a per-vertex `color` attribute the geometry does
+     * not have, gets zeroes, and every marker renders black. The per-instance
+     * colours ride the `colors` option instead, which is a different channel.
+     */
+    private addMarkers;
+    /** The arcs, one swept tube each. */
+    private addArcs;
+    /**
+     * The baked map, and the descriptor that lets it be baked once.
+     *
+     * Two caches are being kept in step here, and the key is what keeps them in
+     * step. This one holds the `Graphics2D` and its descriptor so the node hands
+     * the renderer the *same object* every frame — surface identity is object
+     * identity, so a fresh one each frame would defeat the texture cache and
+     * orphan a GPU texture per frame. The renderer's own `staticRasters` holds the
+     * rasterized pixels against the `identity` string below.
+     *
+     * They share one key, which is the point: edit a colour and this cache misses
+     * (a new `Graphics2D`) *and* that one misses (a new identity string). Derive
+     * the identity from anything else — a counter, the node id — and a colour
+     * change would serve the old pixels forever, because nothing invalidates
+     * `staticRasters` short of tearing down the render context.
+     *
+     * The descriptor is written out rather than built with `Tex.surface` because
+     * the builder's options do not include `static` or `identity`. Handing a bare
+     * `Graphics2D` to `fill` instead takes `resolveFill3D`'s surface path, which
+     * sets neither — and that is the per-frame read-back this whole arrangement
+     * exists to avoid.
+     */
+    private cache;
+    private bakedMap;
+    /** The style props as the one value the baker takes. Also the cache key. */
+    private mapStyle;
+}
+//# sourceMappingURL=globe.d.ts.map

package/dist/globe/globe.d.ts.map

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