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

package/src/globe/globe-places.ts

@@ -0,0 +1,352 @@
+/**
+ * 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 const DEFAULT_MARKER_COLORS = [
+  "#ff3b30",
+  "#ff9f0a",
+  "#ffd60a",
+  "#30d158",
+  "#5ac8fa",
+  "#bf5af2",
+] as const
+
+/** The colour a marker at `index` is drawn in when it names none. */
+export function markerColorAt(index: number): string {
+  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: string): string {
+  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: number; lon: number } = { lat: 0, lon: 0 }
+): GlobeMarker {
+  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: ArcEnd, to: ArcEnd): GlobeArc {
+  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: string): ArcEnd {
+  return { kind: "marker", markerId }
+}
+
+/** An end at a place of its own. */
+export function placeEnd(lat: number, lon: number): ArcEnd {
+  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: unknown): GlobeMarker[] {
+  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: unknown): GlobeArc[] {
+  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: readonly GlobeMarker[]): string {
+  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: readonly GlobeArc[]): string {
+  return JSON.stringify(
+    arcs.map((arc) => ({ ...arc, from: endToValue(arc.from), to: endToValue(arc.to) }))
+  )
+}
+
+function endToValue(end: ArcEnd): string | [number, number] {
+  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: unknown): ArcEnd | null {
+  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 as Record<string, unknown>
+  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))
+}
+
+// --- Reading helpers -------------------------------------------------------
+
+type Row = Record<string, unknown>
+
+function rowsOf(value: unknown): Row[] {
+  if (typeof value !== "string" || value.trim() === "") return []
+  try {
+    const parsed: unknown = JSON.parse(value)
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter(
+      (row): row is 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: unknown, positional: string): string {
+  return text(value) ?? positional
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" && value.trim() !== "" ? value : null
+}
+
+function finite(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+/** A stored 0–1 value; anything unreadable is fully on. */
+function unit(value: unknown): number {
+  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: unknown, fallback: number): number {
+  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: number): number {
+  if (value >= -180 && value <= 180) return value
+  return ((((value + 180) % 360) + 360) % 360) - 180
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value
+}