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

package/dist/globe/places.js

@@ -0,0 +1,94 @@
+/**
+ * The marker and arc lists, resolved into the things a frame draws.
+ *
+ * The authored shape and its serialization live in `model/globe-places.ts`,
+ * shared with the inspector's tiles. What is here is the other half: turning a
+ * pinned arc end into a coordinate, dropping what cannot draw, and deciding how
+ * finely a tube is swept. None of it is meaningful to the panel, and all of it
+ * runs on every rebuild — which is why the two halves are separate modules
+ * rather than one with a flag.
+ */
+import { arcsOf, markersOf, markerColorAt, } from "./globe-places.js";
+/**
+ * The markers a frame draws, in list order.
+ *
+ * The palette is applied **here** rather than left to the drawing code, so the
+ * one place that decides what colour an uncoloured marker is also the place the
+ * swatch in the panel reads — see `markerColorAt`. Position in the list is the
+ * palette index, which is why a reorder recolours: the list is a ranking, and
+ * the first place being the loudest is the point.
+ */
+export function drawableMarkers(value) {
+    return markersOf(value).flatMap((marker, index) => marker.enabled && marker.opacity > 0
+        ? [
+            {
+                id: marker.id,
+                lat: marker.lat,
+                lon: marker.lon,
+                color: marker.color === "" ? markerColorAt(index) : marker.color,
+                size: clamp(marker.size, 0.001, 0.5),
+                opacity: marker.opacity,
+            },
+        ]
+        : []);
+}
+/**
+ * The arcs a frame draws, with pinned ends looked up in the marker list.
+ *
+ * An end pinned to a marker that is gone drops the whole arc rather than falling
+ * back to the origin. A line to null island is a picture of something that is
+ * not true, and it is *harder* to notice than a missing one: an arc that
+ * vanishes when its endpoint is deleted reads as a consequence, where one that
+ * swings to the Gulf of Guinea reads as a bug in the projection.
+ *
+ * A **disabled** marker still anchors an arc, deliberately. Switching a dot off
+ * is about the dot; an arc that also wanted to go is switched off itself.
+ */
+export function drawableArcs(arcsValue, markersValue) {
+    const byId = new Map();
+    for (const marker of markersOf(markersValue))
+        byId.set(marker.id, marker);
+    return arcsOf(arcsValue).flatMap((arc) => {
+        if (!arc.enabled || arc.progress <= 0)
+            return [];
+        const from = resolveEnd(arc.from, byId);
+        const to = resolveEnd(arc.to, byId);
+        if (!from || !to)
+            return [];
+        return [
+            {
+                id: arc.id,
+                from,
+                to,
+                color: arc.color,
+                width: clamp(arc.width, 0.0005, 0.1),
+                lift: arc.lift,
+                progress: arc.progress,
+            },
+        ];
+    });
+}
+function resolveEnd(end, markers) {
+    if (end.kind === "place")
+        return { lat: end.lat, lon: end.lon };
+    const marker = markers.get(end.markerId);
+    return marker ? { lat: marker.lat, lon: marker.lon } : null;
+}
+/**
+ * How many segments an arc's tube is swept along.
+ *
+ * Proportional to how far it goes, so a hop between neighbours is not paying for
+ * a pole-to-pole path's resolution and a long haul does not visibly chord. The
+ * floor keeps a very short arc from degenerating into a two-point tube, which
+ * three cannot frame.
+ */
+export function arcSegments(arc) {
+    const from = arc.from;
+    const to = arc.to;
+    const span = Math.abs(to.lat - from.lat) + Math.abs(to.lon - from.lon);
+    return Math.max(8, Math.min(128, Math.round(span * 0.7)));
+}
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+//# sourceMappingURL=places.js.map

package/dist/globe/places.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"places.js","sourceRoot":"","sources":["../../src/globe/places.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The marker and arc lists, resolved into the things a frame draws.\n *\n * The authored shape and its serialization live in `model/globe-places.ts`,\n * shared with the inspector's tiles. What is here is the other half: turning a\n * pinned arc end into a coordinate, dropping what cannot draw, and deciding how\n * finely a tube is swept. None of it is meaningful to the panel, and all of it\n * runs on every rebuild — which is why the two halves are separate modules\n * rather than one with a flag.\n */\n\nimport {\n  arcsOf,\n  markersOf,\n  markerColorAt,\n  type ArcEnd,\n  type GlobeArc,\n  type GlobeMarker,\n} from \"./globe-places\"\n\n/** A marker with everything the render needs decided. */\nexport interface DrawableMarker {\n  id: string\n  lat: number\n  lon: number\n  color: string\n  size: number\n  opacity: number\n}\n\n/** An arc with both ends resolved to real coordinates. */\nexport interface DrawableArc {\n  id: string\n  from: { lat: number; lon: number }\n  to: { lat: number; lon: number }\n  color: string\n  width: number\n  lift: number\n  progress: number\n}\n\n/**\n * The markers a frame draws, in list order.\n *\n * The palette is applied **here** rather than left to the drawing code, so the\n * one place that decides what colour an uncoloured marker is also the place the\n * swatch in the panel reads — see `markerColorAt`. Position in the list is the\n * palette index, which is why a reorder recolours: the list is a ranking, and\n * the first place being the loudest is the point.\n */\nexport function drawableMarkers(value: string): DrawableMarker[] {\n  return markersOf(value).flatMap((marker, index) =>\n    marker.enabled && marker.opacity > 0\n      ? [\n          {\n            id: marker.id,\n            lat: marker.lat,\n            lon: marker.lon,\n            color: marker.color === \"\" ? markerColorAt(index) : marker.color,\n            size: clamp(marker.size, 0.001, 0.5),\n            opacity: marker.opacity,\n          },\n        ]\n      : []\n  )\n}\n\n/**\n * The arcs a frame draws, with pinned ends looked up in the marker list.\n *\n * An end pinned to a marker that is gone drops the whole arc rather than falling\n * back to the origin. A line to null island is a picture of something that is\n * not true, and it is *harder* to notice than a missing one: an arc that\n * vanishes when its endpoint is deleted reads as a consequence, where one that\n * swings to the Gulf of Guinea reads as a bug in the projection.\n *\n * A **disabled** marker still anchors an arc, deliberately. Switching a dot off\n * is about the dot; an arc that also wanted to go is switched off itself.\n */\nexport function drawableArcs(\n  arcsValue: string,\n  markersValue: string\n): DrawableArc[] {\n  const byId = new Map<string, GlobeMarker>()\n  for (const marker of markersOf(markersValue)) byId.set(marker.id, marker)\n\n  return arcsOf(arcsValue).flatMap((arc) => {\n    if (!arc.enabled || arc.progress <= 0) return []\n    const from = resolveEnd(arc.from, byId)\n    const to = resolveEnd(arc.to, byId)\n    if (!from || !to) return []\n    return [\n      {\n        id: arc.id,\n        from,\n        to,\n        color: arc.color,\n        width: clamp(arc.width, 0.0005, 0.1),\n        lift: arc.lift,\n        progress: arc.progress,\n      },\n    ]\n  })\n}\n\nfunction resolveEnd(\n  end: ArcEnd,\n  markers: Map<string, GlobeMarker>\n): { lat: number; lon: number } | null {\n  if (end.kind === \"place\") return { lat: end.lat, lon: end.lon }\n  const marker = markers.get(end.markerId)\n  return marker ? { lat: marker.lat, lon: marker.lon } : null\n}\n\n/**\n * How many segments an arc's tube is swept along.\n *\n * Proportional to how far it goes, so a hop between neighbours is not paying for\n * a pole-to-pole path's resolution and a long haul does not visibly chord. The\n * floor keeps a very short arc from degenerating into a two-point tube, which\n * three cannot frame.\n */\nexport function arcSegments(arc: Pick<GlobeArc | DrawableArc, \"from\" | \"to\">): number {\n  const from = arc.from as { lat: number; lon: number }\n  const to = arc.to as { lat: number; lon: number }\n  const span = Math.abs(to.lat - from.lat) + Math.abs(to.lon - from.lon)\n  return Math.max(8, Math.min(128, Math.round(span * 0.7)))\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/projection.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Where a latitude and a longitude are, in the three spaces the Globe works in:
+ * the unit sphere it draws on, the equirectangular texture it paints, and the
+ * orbit camera it is looked at through.
+ *
+ * All three are fixed by one decision, and it is the decision every other file
+ * in this node depends on, so it is made here and nowhere else.
+ *
+ * ## The convention, and why it is not the obvious one
+ *
+ * Two things have to be true at once, and motion-script's camera lets you have
+ * either but not both by default:
+ *
+ * 1. **The stored `orbit` field reads directly as a longitude.** That would let
+ *    the camera be three appearance numbers *and* the Fly To command be
+ *    arithmetic on two of them with nothing in between.
+ * 2. **East is to the right.** Looking at the Atlantic from space, Africa is
+ *    right of Brazil. A globe that fails this is a mirrored Earth, which no
+ *    amount of convenience elsewhere pays for.
+ *
+ * The clash: `resolveCameraPlacement` puts a camera at azimuth `a` at
+ * `(sin a, ·, cos a)`, and `cameraOrbit` (`view3d-kit/shared.ts`) feeds it
+ * `90 - orbit`, so a camera at stored orbit θ sits at `(cos θ, ·, sin θ)` and its
+ * screen-right is `-Z`. Increasing θ therefore swings the scene **rightward** —
+ * measured, not reasoned: it is what every existing 3D node does, and the globe
+ * has to match or it is the one viewport whose drag goes backwards.
+ *
+ * So (1) is what gives. Longitude runs the *other* way round the Y axis —
+ * {@link latLonToVector} negates Z, which is what puts east on the right — and a
+ * camera at heading θ is consequently centred over longitude −θ. The stored
+ * field is a heading, labelled "Orbit" like every other viewport's, and
+ * {@link orbitForLongitude} is the one place the two are converted.
+ *
+ * The Fly To command is where that conversion earns its keep: its arguments
+ * genuinely are a latitude and a longitude, and it turns them into a heading
+ * here rather than anywhere else.
+ *
+ * ## The texture
+ *
+ * Plain equirectangular, the orientation any world map image already has:
+ * longitude −180…180 left to right, latitude +90…−90 top to bottom. That falls
+ * out of the convention above rather than being chosen — see {@link latLonToUV},
+ * which derives it from three's own sphere generator — and it is the strongest
+ * evidence the convention is right: get the handedness wrong and the map that
+ * wraps correctly is a mirrored one.
+ */
+/** A point on the unit sphere. */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** A position on the globe, in degrees. */
+export interface LatLon {
+    /** Degrees north of the equator, −90…90. */
+    lat: number;
+    /** Degrees east of the prime meridian, −180…180. */
+    lon: number;
+}
+/**
+ * The bounding box every country path is centred against.
+ *
+ * A `Path` centres on its *own* bounding box unless it is given one, so drawing
+ * the world as one path per country and leaving this off stacks all 177 of them
+ * on the origin. Passing the same frame to each is what keeps them in place —
+ * the same reason the LaTeX renderer passes whole-formula bounds to every glyph.
+ */
+export declare const WORLD_BOUNDS: readonly [-180, -90, 180, 90];
+/**
+ * The unit-sphere direction of a latitude and longitude.
+ *
+ * `z` is negated against the textbook spherical formula, which is the whole of
+ * the convention above: it is what puts east on the right.
+ */
+export declare function latLonToVector({ lat, lon }: LatLon): Vec3;
+/** {@link latLonToVector}, scaled off the surface — markers, arc endpoints. */
+export declare function latLonToPosition(at: LatLon, radius: number): [number, number, number];
+/**
+ * Where a latitude and longitude land in the equirectangular texture, as `uv`
+ * in `[0,1]²`.
+ *
+ * Derived rather than chosen, from the two pieces of machinery underneath:
+ *
+ * - three's `SphereGeometry` puts vertex `u` at `(-cos 2πu, ·, sin 2πu)` and
+ *   writes `uv = (u, 1 - v)`, with `v = 0` at the north pole.
+ * - motion-script uploads a rasterized surface with `flipY = true`
+ *   (`skia-render/src/three/handlers/texture.ts`), so the buffer's **first row
+ *   is `uv.y = 1`**.
+ *
+ * Solving `(-cos 2πu, sin 2πu)` against {@link latLonToVector}'s `(x, z)` gives
+ * `2πu = π + λ`, and the latitude falls straight out of `y = cos θ`. The result
+ * is the ordinary world-map layout, which is the point.
+ */
+export declare function latLonToUV({ lat, lon }: LatLon): {
+    u: number;
+    v: number;
+};
+/**
+ * Where a latitude and longitude land in the **drawing space** of the baked
+ * texture: pixels, **y upward**, origin at the buffer's centre.
+ *
+ * Two of motion-script's conventions meet here, and neither is guessable from a
+ * picture that comes out wrong, so both are written down:
+ *
+ * - **The origin is the buffer's centre**, because `SkiaRenderContext.rasterize`
+ *   translates the offscreen canvas by half its size before handing it to the
+ *   source. Drawn from a top-left origin the map lands a quarter of the world
+ *   off the edge — and still wraps onto the sphere without complaint.
+ * - **`y` is up.** A `PathCommand[]`, and a line's `points`, are authored y-up
+ *   and mirrored by the backend on the way to Skia (`flipPathY`, and the
+ *   `points` map beside it in `render-context.ts`). Drawn y-down the world is
+ *   simply upside down — and every continent still has its own shape, so it
+ *   reads as a texture flipped somewhere in the pipeline rather than as a sign
+ *   in the one function that decides.
+ *
+ * Deliberately *not* the raw buffer's own row order. The backend's flip lands
+ * north on the first row, and `flipY` on the uploaded texture maps that row to
+ * `uv.y = 1` — which is where {@link latLonToUV} independently puts the north
+ * pole. A test ties the two together rather than trusting them to agree.
+ */
+export declare function latLonToCanvas({ lat, lon }: LatLon, width: number, height: number): {
+    x: number;
+    y: number;
+};
+/**
+ * The frame every country path is centred against, in that same space.
+ *
+ * See {@link WORLD_BOUNDS} for why passing it to each path matters.
+ */
+export declare function canvasBounds(width: number, height: number): [number, number, number, number];
+/**
+ * The stored `orbit` heading that puts `lon` at the centre of the frame.
+ *
+ * **A negation, and it is the price of two things that matter more than the
+ * field reading as a longitude.**
+ *
+ * `orbit` has to behave exactly as it does on every other 3D node: the canvas
+ * drag adds to it (`orbitByDrag`), and increasing it must swing the scene the
+ * same way it swings a molecule or a surface, or the globe is the one viewport
+ * whose drag goes backwards. That pins `orbit` to `cameraOrbit` with no
+ * conversion in between.
+ *
+ * East also has to be on the right, which pins {@link latLonToVector}'s sign.
+ *
+ * Those two together force the third: a camera at heading θ is centred over
+ * longitude −θ. So the stored field is a **heading**, not a longitude — which is
+ * why the panel labels it "Orbit" like every other viewport's, and why the Fly
+ * To command, whose arguments genuinely are a latitude and a longitude,
+ * converts through here.
+ */
+export declare function orbitForLongitude(lon: number): number;
+/** The longitude a stored `orbit` heading is centred over. Its own inverse. */
+export declare function longitudeForOrbit(orbit: number): number;
+/**
+ * Points along the great circle from `from` to `to`, `segments` spans of them.
+ *
+ * Spherical linear interpolation rather than a lerp of the two lat/lons: the
+ * latter is a rhumb line, which crosses the antimeridian the long way and bulges
+ * badly at high latitudes — a "London to Tokyo" arc drawn that way runs through
+ * Kazakhstan instead of over the pole, which is the one thing the picture exists
+ * to show.
+ *
+ * `lift` raises the middle of the arc off the surface, as a fraction of the
+ * radius, on a sine so both ends meet the sphere flush. Zero draws the path on
+ * the ground.
+ */
+export declare function greatCircle(from: LatLon, to: LatLon, options?: {
+    radius?: number;
+    lift?: number;
+    segments?: number;
+}): [number, number, number][];
+/**
+ * The signed turn from one heading to another, taking whichever way round is
+ * shorter — so 170° to −170° is a 20° nudge east rather than 340° west.
+ *
+ * The same arithmetic `camera-kit`'s unused `shortestTurn` states; it is
+ * duplicated rather than imported because that one is private to a module this
+ * package's 3D nodes do not otherwise depend on, and because a Fly To that got
+ * this wrong would be the command's single most visible failure.
+ */
+export declare function shortestTurn(from: number, to: number): number;
+//# sourceMappingURL=projection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/globe/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,kCAAkC;AAClC,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,2CAA2C;AAC3C,MAAM,WAAW,MAAM;IACrB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,+BAAgC,CAAA;AAIzD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,GAAG,IAAI,CASzD;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GACb,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAG1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAE1B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAElC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAkC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/globe/projection.js

@@ -0,0 +1,215 @@
+/**
+ * Where a latitude and a longitude are, in the three spaces the Globe works in:
+ * the unit sphere it draws on, the equirectangular texture it paints, and the
+ * orbit camera it is looked at through.
+ *
+ * All three are fixed by one decision, and it is the decision every other file
+ * in this node depends on, so it is made here and nowhere else.
+ *
+ * ## The convention, and why it is not the obvious one
+ *
+ * Two things have to be true at once, and motion-script's camera lets you have
+ * either but not both by default:
+ *
+ * 1. **The stored `orbit` field reads directly as a longitude.** That would let
+ *    the camera be three appearance numbers *and* the Fly To command be
+ *    arithmetic on two of them with nothing in between.
+ * 2. **East is to the right.** Looking at the Atlantic from space, Africa is
+ *    right of Brazil. A globe that fails this is a mirrored Earth, which no
+ *    amount of convenience elsewhere pays for.
+ *
+ * The clash: `resolveCameraPlacement` puts a camera at azimuth `a` at
+ * `(sin a, ·, cos a)`, and `cameraOrbit` (`view3d-kit/shared.ts`) feeds it
+ * `90 - orbit`, so a camera at stored orbit θ sits at `(cos θ, ·, sin θ)` and its
+ * screen-right is `-Z`. Increasing θ therefore swings the scene **rightward** —
+ * measured, not reasoned: it is what every existing 3D node does, and the globe
+ * has to match or it is the one viewport whose drag goes backwards.
+ *
+ * So (1) is what gives. Longitude runs the *other* way round the Y axis —
+ * {@link latLonToVector} negates Z, which is what puts east on the right — and a
+ * camera at heading θ is consequently centred over longitude −θ. The stored
+ * field is a heading, labelled "Orbit" like every other viewport's, and
+ * {@link orbitForLongitude} is the one place the two are converted.
+ *
+ * The Fly To command is where that conversion earns its keep: its arguments
+ * genuinely are a latitude and a longitude, and it turns them into a heading
+ * here rather than anywhere else.
+ *
+ * ## The texture
+ *
+ * Plain equirectangular, the orientation any world map image already has:
+ * longitude −180…180 left to right, latitude +90…−90 top to bottom. That falls
+ * out of the convention above rather than being chosen — see {@link latLonToUV},
+ * which derives it from three's own sphere generator — and it is the strongest
+ * evidence the convention is right: get the handedness wrong and the map that
+ * wraps correctly is a mirrored one.
+ */
+/**
+ * The bounding box every country path is centred against.
+ *
+ * A `Path` centres on its *own* bounding box unless it is given one, so drawing
+ * the world as one path per country and leaving this off stacks all 177 of them
+ * on the origin. Passing the same frame to each is what keeps them in place —
+ * the same reason the LaTeX renderer passes whole-formula bounds to every glyph.
+ */
+export const WORLD_BOUNDS = [-180, -90, 180, 90];
+const DEG = Math.PI / 180;
+/**
+ * The unit-sphere direction of a latitude and longitude.
+ *
+ * `z` is negated against the textbook spherical formula, which is the whole of
+ * the convention above: it is what puts east on the right.
+ */
+export function latLonToVector({ lat, lon }) {
+    const phi = lat * DEG;
+    const lambda = lon * DEG;
+    const ring = Math.cos(phi);
+    return {
+        x: ring * Math.cos(lambda),
+        y: Math.sin(phi),
+        z: -ring * Math.sin(lambda),
+    };
+}
+/** {@link latLonToVector}, scaled off the surface — markers, arc endpoints. */
+export function latLonToPosition(at, radius) {
+    const { x, y, z } = latLonToVector(at);
+    return [x * radius, y * radius, z * radius];
+}
+/**
+ * Where a latitude and longitude land in the equirectangular texture, as `uv`
+ * in `[0,1]²`.
+ *
+ * Derived rather than chosen, from the two pieces of machinery underneath:
+ *
+ * - three's `SphereGeometry` puts vertex `u` at `(-cos 2πu, ·, sin 2πu)` and
+ *   writes `uv = (u, 1 - v)`, with `v = 0` at the north pole.
+ * - motion-script uploads a rasterized surface with `flipY = true`
+ *   (`skia-render/src/three/handlers/texture.ts`), so the buffer's **first row
+ *   is `uv.y = 1`**.
+ *
+ * Solving `(-cos 2πu, sin 2πu)` against {@link latLonToVector}'s `(x, z)` gives
+ * `2πu = π + λ`, and the latitude falls straight out of `y = cos θ`. The result
+ * is the ordinary world-map layout, which is the point.
+ */
+export function latLonToUV({ lat, lon }) {
+    return { u: (lon + 180) / 360, v: 0.5 + lat / 180 };
+}
+/**
+ * Where a latitude and longitude land in the **drawing space** of the baked
+ * texture: pixels, **y upward**, origin at the buffer's centre.
+ *
+ * Two of motion-script's conventions meet here, and neither is guessable from a
+ * picture that comes out wrong, so both are written down:
+ *
+ * - **The origin is the buffer's centre**, because `SkiaRenderContext.rasterize`
+ *   translates the offscreen canvas by half its size before handing it to the
+ *   source. Drawn from a top-left origin the map lands a quarter of the world
+ *   off the edge — and still wraps onto the sphere without complaint.
+ * - **`y` is up.** A `PathCommand[]`, and a line's `points`, are authored y-up
+ *   and mirrored by the backend on the way to Skia (`flipPathY`, and the
+ *   `points` map beside it in `render-context.ts`). Drawn y-down the world is
+ *   simply upside down — and every continent still has its own shape, so it
+ *   reads as a texture flipped somewhere in the pipeline rather than as a sign
+ *   in the one function that decides.
+ *
+ * Deliberately *not* the raw buffer's own row order. The backend's flip lands
+ * north on the first row, and `flipY` on the uploaded texture maps that row to
+ * `uv.y = 1` — which is where {@link latLonToUV} independently puts the north
+ * pole. A test ties the two together rather than trusting them to agree.
+ */
+export function latLonToCanvas({ lat, lon }, width, height) {
+    return { x: (lon / 360) * width, y: (lat / 180) * height };
+}
+/**
+ * The frame every country path is centred against, in that same space.
+ *
+ * See {@link WORLD_BOUNDS} for why passing it to each path matters.
+ */
+export function canvasBounds(width, height) {
+    return [-width / 2, -height / 2, width / 2, height / 2];
+}
+/**
+ * The stored `orbit` heading that puts `lon` at the centre of the frame.
+ *
+ * **A negation, and it is the price of two things that matter more than the
+ * field reading as a longitude.**
+ *
+ * `orbit` has to behave exactly as it does on every other 3D node: the canvas
+ * drag adds to it (`orbitByDrag`), and increasing it must swing the scene the
+ * same way it swings a molecule or a surface, or the globe is the one viewport
+ * whose drag goes backwards. That pins `orbit` to `cameraOrbit` with no
+ * conversion in between.
+ *
+ * East also has to be on the right, which pins {@link latLonToVector}'s sign.
+ *
+ * Those two together force the third: a camera at heading θ is centred over
+ * longitude −θ. So the stored field is a **heading**, not a longitude — which is
+ * why the panel labels it "Orbit" like every other viewport's, and why the Fly
+ * To command, whose arguments genuinely are a latitude and a longitude,
+ * converts through here.
+ */
+export function orbitForLongitude(lon) {
+    return -lon;
+}
+/** The longitude a stored `orbit` heading is centred over. Its own inverse. */
+export function longitudeForOrbit(orbit) {
+    return -orbit;
+}
+/**
+ * Points along the great circle from `from` to `to`, `segments` spans of them.
+ *
+ * Spherical linear interpolation rather than a lerp of the two lat/lons: the
+ * latter is a rhumb line, which crosses the antimeridian the long way and bulges
+ * badly at high latitudes — a "London to Tokyo" arc drawn that way runs through
+ * Kazakhstan instead of over the pole, which is the one thing the picture exists
+ * to show.
+ *
+ * `lift` raises the middle of the arc off the surface, as a fraction of the
+ * radius, on a sine so both ends meet the sphere flush. Zero draws the path on
+ * the ground.
+ */
+export function greatCircle(from, to, options = {}) {
+    const radius = options.radius ?? 1;
+    const lift = options.lift ?? 0;
+    const segments = Math.max(1, Math.floor(options.segments ?? 64));
+    const a = latLonToVector(from);
+    const b = latLonToVector(to);
+    const dot = clamp(a.x * b.x + a.y * b.y + a.z * b.z, -1, 1);
+    const omega = Math.acos(dot);
+    const points = [];
+    for (let i = 0; i <= segments; i++) {
+        const t = i / segments;
+        // Antipodal or coincident endpoints leave the plane of the circle
+        // undefined; a straight blend is the honest answer for both, and
+        // renormalising below puts it back on the sphere either way.
+        const [wa, wb] = Math.abs(omega) < 1e-6
+            ? [1 - t, t]
+            : [
+                Math.sin((1 - t) * omega) / Math.sin(omega),
+                Math.sin(t * omega) / Math.sin(omega),
+            ];
+        const x = a.x * wa + b.x * wb;
+        const y = a.y * wa + b.y * wb;
+        const z = a.z * wa + b.z * wb;
+        const length = Math.hypot(x, y, z) || 1;
+        const scale = (radius * (1 + lift * Math.sin(Math.PI * t))) / length;
+        points.push([x * scale, y * scale, z * scale]);
+    }
+    return points;
+}
+/**
+ * The signed turn from one heading to another, taking whichever way round is
+ * shorter — so 170° to −170° is a 20° nudge east rather than 340° west.
+ *
+ * The same arithmetic `camera-kit`'s unused `shortestTurn` states; it is
+ * duplicated rather than imported because that one is private to a module this
+ * package's 3D nodes do not otherwise depend on, and because a Fly To that got
+ * this wrong would be the command's single most visible failure.
+ */
+export function shortestTurn(from, to) {
+    return ((((to - from) % 360) + 540) % 360) - 180;
+}
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+//# sourceMappingURL=projection.js.map

package/dist/globe/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../../src/globe/projection.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where a latitude and a longitude are, in the three spaces the Globe works in:\n * the unit sphere it draws on, the equirectangular texture it paints, and the\n * orbit camera it is looked at through.\n *\n * All three are fixed by one decision, and it is the decision every other file\n * in this node depends on, so it is made here and nowhere else.\n *\n * ## The convention, and why it is not the obvious one\n *\n * Two things have to be true at once, and motion-script's camera lets you have\n * either but not both by default:\n *\n * 1. **The stored `orbit` field reads directly as a longitude.** That would let\n *    the camera be three appearance numbers *and* the Fly To command be\n *    arithmetic on two of them with nothing in between.\n * 2. **East is to the right.** Looking at the Atlantic from space, Africa is\n *    right of Brazil. A globe that fails this is a mirrored Earth, which no\n *    amount of convenience elsewhere pays for.\n *\n * The clash: `resolveCameraPlacement` puts a camera at azimuth `a` at\n * `(sin a, ·, cos a)`, and `cameraOrbit` (`view3d-kit/shared.ts`) feeds it\n * `90 - orbit`, so a camera at stored orbit θ sits at `(cos θ, ·, sin θ)` and its\n * screen-right is `-Z`. Increasing θ therefore swings the scene **rightward** —\n * measured, not reasoned: it is what every existing 3D node does, and the globe\n * has to match or it is the one viewport whose drag goes backwards.\n *\n * So (1) is what gives. Longitude runs the *other* way round the Y axis —\n * {@link latLonToVector} negates Z, which is what puts east on the right — and a\n * camera at heading θ is consequently centred over longitude −θ. The stored\n * field is a heading, labelled \"Orbit\" like every other viewport's, and\n * {@link orbitForLongitude} is the one place the two are converted.\n *\n * The Fly To command is where that conversion earns its keep: its arguments\n * genuinely are a latitude and a longitude, and it turns them into a heading\n * here rather than anywhere else.\n *\n * ## The texture\n *\n * Plain equirectangular, the orientation any world map image already has:\n * longitude −180…180 left to right, latitude +90…−90 top to bottom. That falls\n * out of the convention above rather than being chosen — see {@link latLonToUV},\n * which derives it from three's own sphere generator — and it is the strongest\n * evidence the convention is right: get the handedness wrong and the map that\n * wraps correctly is a mirrored one.\n */\n\n/** A point on the unit sphere. */\nexport interface Vec3 {\n  x: number\n  y: number\n  z: number\n}\n\n/** A position on the globe, in degrees. */\nexport interface LatLon {\n  /** Degrees north of the equator, −90…90. */\n  lat: number\n  /** Degrees east of the prime meridian, −180…180. */\n  lon: number\n}\n\n/**\n * The bounding box every country path is centred against.\n *\n * A `Path` centres on its *own* bounding box unless it is given one, so drawing\n * the world as one path per country and leaving this off stacks all 177 of them\n * on the origin. Passing the same frame to each is what keeps them in place —\n * the same reason the LaTeX renderer passes whole-formula bounds to every glyph.\n */\nexport const WORLD_BOUNDS = [-180, -90, 180, 90] as const\n\nconst DEG = Math.PI / 180\n\n/**\n * The unit-sphere direction of a latitude and longitude.\n *\n * `z` is negated against the textbook spherical formula, which is the whole of\n * the convention above: it is what puts east on the right.\n */\nexport function latLonToVector({ lat, lon }: LatLon): Vec3 {\n  const phi = lat * DEG\n  const lambda = lon * DEG\n  const ring = Math.cos(phi)\n  return {\n    x: ring * Math.cos(lambda),\n    y: Math.sin(phi),\n    z: -ring * Math.sin(lambda),\n  }\n}\n\n/** {@link latLonToVector}, scaled off the surface — markers, arc endpoints. */\nexport function latLonToPosition(\n  at: LatLon,\n  radius: number\n): [number, number, number] {\n  const { x, y, z } = latLonToVector(at)\n  return [x * radius, y * radius, z * radius]\n}\n\n/**\n * Where a latitude and longitude land in the equirectangular texture, as `uv`\n * in `[0,1]²`.\n *\n * Derived rather than chosen, from the two pieces of machinery underneath:\n *\n * - three's `SphereGeometry` puts vertex `u` at `(-cos 2πu, ·, sin 2πu)` and\n *   writes `uv = (u, 1 - v)`, with `v = 0` at the north pole.\n * - motion-script uploads a rasterized surface with `flipY = true`\n *   (`skia-render/src/three/handlers/texture.ts`), so the buffer's **first row\n *   is `uv.y = 1`**.\n *\n * Solving `(-cos 2πu, sin 2πu)` against {@link latLonToVector}'s `(x, z)` gives\n * `2πu = π + λ`, and the latitude falls straight out of `y = cos θ`. The result\n * is the ordinary world-map layout, which is the point.\n */\nexport function latLonToUV({ lat, lon }: LatLon): { u: number; v: number } {\n  return { u: (lon + 180) / 360, v: 0.5 + lat / 180 }\n}\n\n/**\n * Where a latitude and longitude land in the **drawing space** of the baked\n * texture: pixels, **y upward**, origin at the buffer's centre.\n *\n * Two of motion-script's conventions meet here, and neither is guessable from a\n * picture that comes out wrong, so both are written down:\n *\n * - **The origin is the buffer's centre**, because `SkiaRenderContext.rasterize`\n *   translates the offscreen canvas by half its size before handing it to the\n *   source. Drawn from a top-left origin the map lands a quarter of the world\n *   off the edge — and still wraps onto the sphere without complaint.\n * - **`y` is up.** A `PathCommand[]`, and a line's `points`, are authored y-up\n *   and mirrored by the backend on the way to Skia (`flipPathY`, and the\n *   `points` map beside it in `render-context.ts`). Drawn y-down the world is\n *   simply upside down — and every continent still has its own shape, so it\n *   reads as a texture flipped somewhere in the pipeline rather than as a sign\n *   in the one function that decides.\n *\n * Deliberately *not* the raw buffer's own row order. The backend's flip lands\n * north on the first row, and `flipY` on the uploaded texture maps that row to\n * `uv.y = 1` — which is where {@link latLonToUV} independently puts the north\n * pole. A test ties the two together rather than trusting them to agree.\n */\nexport function latLonToCanvas(\n  { lat, lon }: LatLon,\n  width: number,\n  height: number\n): { x: number; y: number } {\n  return { x: (lon / 360) * width, y: (lat / 180) * height }\n}\n\n/**\n * The frame every country path is centred against, in that same space.\n *\n * See {@link WORLD_BOUNDS} for why passing it to each path matters.\n */\nexport function canvasBounds(\n  width: number,\n  height: number\n): [number, number, number, number] {\n  return [-width / 2, -height / 2, width / 2, height / 2]\n}\n\n/**\n * The stored `orbit` heading that puts `lon` at the centre of the frame.\n *\n * **A negation, and it is the price of two things that matter more than the\n * field reading as a longitude.**\n *\n * `orbit` has to behave exactly as it does on every other 3D node: the canvas\n * drag adds to it (`orbitByDrag`), and increasing it must swing the scene the\n * same way it swings a molecule or a surface, or the globe is the one viewport\n * whose drag goes backwards. That pins `orbit` to `cameraOrbit` with no\n * conversion in between.\n *\n * East also has to be on the right, which pins {@link latLonToVector}'s sign.\n *\n * Those two together force the third: a camera at heading θ is centred over\n * longitude −θ. So the stored field is a **heading**, not a longitude — which is\n * why the panel labels it \"Orbit\" like every other viewport's, and why the Fly\n * To command, whose arguments genuinely are a latitude and a longitude,\n * converts through here.\n */\nexport function orbitForLongitude(lon: number): number {\n  return -lon\n}\n\n/** The longitude a stored `orbit` heading is centred over. Its own inverse. */\nexport function longitudeForOrbit(orbit: number): number {\n  return -orbit\n}\n\n/**\n * Points along the great circle from `from` to `to`, `segments` spans of them.\n *\n * Spherical linear interpolation rather than a lerp of the two lat/lons: the\n * latter is a rhumb line, which crosses the antimeridian the long way and bulges\n * badly at high latitudes — a \"London to Tokyo\" arc drawn that way runs through\n * Kazakhstan instead of over the pole, which is the one thing the picture exists\n * to show.\n *\n * `lift` raises the middle of the arc off the surface, as a fraction of the\n * radius, on a sine so both ends meet the sphere flush. Zero draws the path on\n * the ground.\n */\nexport function greatCircle(\n  from: LatLon,\n  to: LatLon,\n  options: { radius?: number; lift?: number; segments?: number } = {}\n): [number, number, number][] {\n  const radius = options.radius ?? 1\n  const lift = options.lift ?? 0\n  const segments = Math.max(1, Math.floor(options.segments ?? 64))\n\n  const a = latLonToVector(from)\n  const b = latLonToVector(to)\n\n  const dot = clamp(a.x * b.x + a.y * b.y + a.z * b.z, -1, 1)\n  const omega = Math.acos(dot)\n\n  const points: [number, number, number][] = []\n  for (let i = 0; i <= segments; i++) {\n    const t = i / segments\n    // Antipodal or coincident endpoints leave the plane of the circle\n    // undefined; a straight blend is the honest answer for both, and\n    // renormalising below puts it back on the sphere either way.\n    const [wa, wb] =\n      Math.abs(omega) < 1e-6\n        ? [1 - t, t]\n        : [\n            Math.sin((1 - t) * omega) / Math.sin(omega),\n            Math.sin(t * omega) / Math.sin(omega),\n          ]\n\n    const x = a.x * wa + b.x * wb\n    const y = a.y * wa + b.y * wb\n    const z = a.z * wa + b.z * wb\n    const length = Math.hypot(x, y, z) || 1\n    const scale = (radius * (1 + lift * Math.sin(Math.PI * t))) / length\n\n    points.push([x * scale, y * scale, z * scale])\n  }\n  return points\n}\n\n/**\n * The signed turn from one heading to another, taking whichever way round is\n * shorter — so 170° to −170° is a 20° nudge east rather than 340° west.\n *\n * The same arithmetic `camera-kit`'s unused `shortestTurn` states; it is\n * duplicated rather than imported because that one is private to a module this\n * package's 3D nodes do not otherwise depend on, and because a Fly To that got\n * this wrong would be the command's single most visible failure.\n */\nexport function shortestTurn(from: number, to: number): number {\n  return ((((to - from) % 360) + 540) % 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/world-map.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The world as a flat drawing — the one `Graphics2D` that becomes the sphere's
+ * texture.
+ *
+ * Baking the map in 2D rather than tessellating it in 3D is the node's central
+ * decision, and it is not a shortcut. A WebGL line ignores any width above one
+ * pixel (motion-script says so outright on `LineStroke3D`), so borders drawn as
+ * 3D lines are hairlines at every zoom and every resolution, and the only way to
+ * thicken one is to sweep a tube along it — three hundred tubes, for a picture
+ * that is flat. Drawn here, a border is an ordinary stroke: any weight, any
+ * colour, joined and antialiased by Skia, and it costs one rasterize rather than
+ * one per frame.
+ *
+ * Everything here is therefore *style*, and the node's cache key is exactly the
+ * arguments below. Nothing that moves — a marker, an arc, the camera — is drawn
+ * into this, because baking something that moves would put every frame of its
+ * animation through a full re-rasterize.
+ *
+ * ## One path per country, and this is the whole performance story
+ *
+ * The obvious shape is one `path` op holding all 289 rings — the nonzero fill
+ * rule sorts out what is land, and it is one op instead of 177. **Do not do
+ * that.** Skia's cost for filling and stroking a single path is badly
+ * superlinear in its *contour* count, and the difference is not marginal:
+ *
+ *     one path, 289 contours, 10,649 commands   10,691 ms
+ *     one path per country (177 of them)           205 ms
+ *
+ * Measured in the browser, on the same data, at the same resolution — a 52×
+ * difference, and the reason adding a Globe to a scene used to lock the app for
+ * ten seconds. It is also almost independent of the texture's resolution (256²
+ * and 2048² are within 10% of each other), which is the tell that the cost is
+ * geometry, not pixels, and that turning the map down would not have saved it.
+ *
+ * Splitting per country is safe for the fill: each country's rings — exterior
+ * and holes together — stay in *its* path, so the nonzero rule still cuts
+ * Lesotho out of South Africa, and Lesotho's own path paints it back.
+ *
+ * ## The lines are a separate pass, and have to be
+ *
+ * The country paths are filled and **not** stroked. Stroking them would draw
+ * every international border twice — once from each side, since both countries
+ * carry it — and a doubly-composited antialiased fringe reads as a line half
+ * again as wide as the coastlines beside it. `borders.ts` deduplicates the
+ * segments and stitches them into runs; this file strokes those instead, so
+ * every line on the map is drawn exactly once at exactly one weight.
+ */
+import { Graphics2D } from "@motionscript/core";
+/** Everything that changes the baked pixels. Also the node's cache key. */
+export interface WorldMapStyle {
+    /** Buffer width in pixels. Height is half of it — the equirectangular ratio. */
+    width: number;
+    ocean: string;
+    land: string;
+    /**
+     * The colour of every coast and border.
+     *
+     * Alpha is fine here, and that is worth saying because it briefly was not:
+     * while the country paths were stroked, a shared border was drawn twice and a
+     * translucent one came out at double density. `drawBoundaries` draws each line
+     * exactly once, so the colour means what it says.
+     */
+    border: string;
+    borderWidth: number;
+    graticule: boolean;
+    graticuleColor: string;
+    /** Degrees between graticule lines. */
+    graticuleStep: number;
+    graticuleWidth: number;
+}
+/** The buffer's height for a given width — equirectangular is always 2:1. */
+export declare function mapHeight(width: number): number;
+/**
+ * The map, drawn.
+ *
+ * **Hoist the result.** motion-script identifies a surface texture by its source
+ * object, so a fresh `Graphics2D` every frame misses the raster cache, redraws
+ * ten thousand paths, reads the buffer back off the GPU and uploads it again —
+ * sixty times a second, to produce the same image. `Globe` holds one against
+ * this style; nothing else should call this.
+ */
+export declare function worldMapGraphics(style: WorldMapStyle): Graphics2D;
+//# sourceMappingURL=world-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"world-map.d.ts","sourceRoot":"","sources":["../../src/globe/world-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EAAE,UAAU,EAAoB,MAAM,oBAAoB,CAAA;AAMjE,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,OAAO,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAuCjE"}