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

package/src/globe/globe.ts

@@ -0,0 +1,552 @@
+import {
+  command,
+  driveCommand,
+  easeInOut,
+  node,
+  type Command,
+  type CommandArgs,
+  Canvas3D,
+  Geo,
+  Graphics3D,
+  Mat,
+  Scene3D,
+  property,
+  type Canvas3DProps,
+  type Color,
+  type NodeConfig,
+  type NormalizedColor,
+  type SurfaceTexture3D,
+  type Transform3D,
+} from "@motionscript/sdk"
+
+import {
+  lerpColor3D,
+  resolveColor3D,
+  snapFlag,
+  snapValue,
+  cameraOrbit,
+  orbitProps,
+  type OrbitTarget,
+} from "@motionscript/sdk/component"
+import { atmosphereMaterial } from "./atmosphere"
+import { arcSegments, drawableArcs, drawableMarkers } from "./places"
+import { greatCircle, latLonToPosition } from "./projection"
+import { mapHeight, worldMapGraphics, type WorldMapStyle } from "./world-map"
+
+/**
+ * The globe's radius, in scene units.
+ *
+ * One, and not a prop. Every other length the node takes — a marker's size, an
+ * arc's width and lift, the camera's `zoom` — is a fraction or a multiple of it,
+ * which is what makes those numbers mean the same thing at any framing and is
+ * why there is nothing for a radius prop to be relative *to*. The Protein's
+ * radius is a prop because a molecule's size is a fact about the molecule; the
+ * Earth's is a choice about units.
+ */
+const RADIUS = 1
+
+/** How far off the surface a marker's centre sits, as a fraction of its size. */
+const MARKER_LIFT = 0.35
+
+export interface GlobeProps extends Canvas3DProps {
+  // ── The map ──
+  resolution: number
+  ocean: Color
+  land: Color
+  border: Color
+  borderWidth: number
+  graticule: boolean
+  graticuleColor: Color
+  graticuleStep: number
+  graticuleWidth: number
+
+  // ── The camera ──
+  orbit: number
+  elevation: number
+  zoom: number
+  fov: number
+
+  // ── Lighting ──
+  ambientIntensity: number
+  ambientColor: Color
+  keyIntensity: number
+  keyColor: Color
+
+  // ── The atmosphere ──
+  atmosphere: boolean
+  atmosphereColor: Color
+  atmosphereSize: number
+  atmosphereFalloff: number
+  atmosphereIntensity: number
+
+  // ── What is placed on it ──
+  markers: string
+  arcs: string
+}
+
+/** What the map cache is holding, keyed by the style that produced it. */
+interface BakedMap {
+  texture: SurfaceTexture3D
+}
+
+/**
+ * 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.
+ */
+@node({
+  key: "globe",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    acceptsChildren: false,
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+  },
+  seed: {
+    width: 640,
+    height: 640,
+  },
+})
+export class Globe extends Canvas3D<GlobeProps> {
+  // ── The map ──
+  //
+  // Every prop in this group is part of the texture's cache key, and every one
+  // of them is `animatable: false` in the appearance schema. They are plain
+  // strings rather than resolved colours for the same reason: a tween would need
+  // a mapper, and there is deliberately no tween to have.
+
+  /**
+   * 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.
+   */
+  @property({ default: 2048, tween: snapValue }) declare resolution: number
+
+  @property({ default: "#0b1a2b", tween: snapValue }) declare ocean: Color
+  @property({ default: "#2c3e50", tween: snapValue }) declare 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.
+   */
+  @property({ default: "#4a6076", tween: snapValue }) declare border: Color
+  @property({ default: 1.5, tween: snapValue }) declare borderWidth: number
+
+  @property({ default: true, tween: snapFlag }) declare graticule: boolean
+  @property({ default: "#ffffff20", tween: snapValue })
+  declare graticuleColor: Color
+  @property({ default: 15, tween: snapValue }) declare graticuleStep: number
+  @property({ default: 1, tween: snapValue }) declare graticuleWidth: number
+
+  // ── The camera ──
+
+  /**
+   * 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.
+   */
+  @property({ default: -10 }) declare 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.
+   */
+  @property({ default: 25 }) declare elevation: number
+  /** Distance from the centre, as a multiple of the globe's radius. */
+  @property({ default: 2.8 }) declare zoom: number
+  @property({ default: 45 }) declare fov: number
+
+  // ── Lighting ──
+
+  @property({ default: 0.55 }) declare ambientIntensity: number
+  @property({ default: "#ffffff", mapper: resolveColor3D, tween: lerpColor3D })
+  declare ambientColor: Color
+  @property({ default: 1.9 }) declare keyIntensity: number
+  @property({ default: "#ffffff", mapper: resolveColor3D, tween: lerpColor3D })
+  declare keyColor: Color
+
+  // ── The atmosphere ──
+  //
+  // Shading rather than pixels, so unlike the map group these all animate.
+
+  @property({ default: true, tween: snapFlag }) declare atmosphere: boolean
+  @property({ default: "#4da3ff", mapper: resolveColor3D, tween: lerpColor3D })
+  declare atmosphereColor: Color
+  /** The shell's radius as a multiple of the globe's. */
+  @property({ default: 1.06 }) declare atmosphereSize: number
+  /** How tightly the glow hugs the edge. Higher is a thinner rim. */
+  @property({ default: 3 }) declare atmosphereFalloff: number
+  @property({ default: 1.1 }) declare atmosphereIntensity: number
+
+  // ── What is placed on it ──
+  //
+  // Serialized lists, as the graphs store their equations: an appearance value
+  // is a number, a string or a boolean, so a list arrives as a string a mapper
+  // reads. Parsing is in `places.ts` and is deliberately tolerant — the field is
+  // invalid far more often than valid while somebody is typing into it.
+
+  @property({ default: "[]", tween: snapValue }) declare markers: string
+  @property({ default: "[]", tween: snapValue }) declare arcs: string
+
+  constructor(props?: NodeConfig<Globe, GlobeProps>) {
+    super(props as NodeConfig<Canvas3D<GlobeProps>, 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}.
+   */
+  @command({
+    args: [
+      {
+        key: "target", kind: "orbit", properties: {
+          orbit: { kind: "number", step: 1, unit: "°" },
+          elevation: { kind: "number", min: -89, max: 89, step: 1, unit: "°" },
+          zoom: { kind: "number", min: 0.2, max: 24, step: 0.1, unit: "×" },
+        },
+      },
+    ],
+  })
+  orbitTo(args: CommandArgs<{ target: OrbitTarget }> & { duration: number }): Command<GlobeProps> {
+    return this.to({
+      data: orbitProps(args.data?.target ?? {}) as Partial<GlobeProps>,
+      duration: args.duration,
+      easing: args.easing ?? easeInOut(),
+    })
+  }
+
+  /**
+   * 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**.
+   */
+  @command({ args: [{ key: "latitude", kind: "number", default: 0, min: -89, max: 89, step: 1, unit: "°" }, { key: "longitude", kind: "number", default: 0, min: -180, max: 180, step: 1, unit: "°" }, { key: "framing", kind: "number", default: 2.2, min: 1.05, max: 12, step: 0.1, unit: "×" }, { key: "arc", kind: "number", default: 0.35, min: 0, max: 3, step: 0.05, scale: 100, unit: "%" }] })
+  flyTo(args: CommandArgs<{ latitude: number; longitude: number; framing?: number; arc?: number }> & { duration?: number }): Command<GlobeProps> {
+    const data = args.data ?? { latitude: 0, longitude: 0 }
+    const { latitude, longitude, framing = 2.2, arc = 0.35 } = data
+    const duration = args.duration ?? 1.6
+    const easing = args.easing ?? easeInOut()
+
+    const fromOrbit = this.orbit
+    const fromElevation = this.elevation
+    const fromZoom = this.zoom
+
+    // The globe spins under a fixed camera, so a longitude is reached by
+    // orbiting to its negation — and the shortest signed turn is what keeps a
+    // crossing of the antimeridian from unwinding the long way.
+    const toOrbit = fromOrbit + shortestTurn(fromOrbit, -longitude)
+
+    return driveCommand(duration, (t) => {
+      const eased = easing(t)
+      this.set({
+        orbit: fromOrbit + (toOrbit - fromOrbit) * eased,
+        elevation: fromElevation + (latitude - fromElevation) * eased,
+        // The bow: a half-sine that is 0 at both ends, so the command still
+        // lands exactly on `framing` however large `arc` is.
+        zoom: (fromZoom + (framing - fromZoom) * eased) * (1 + arc * Math.sin(Math.PI * eased)),
+      } as Partial<GlobeProps>)
+    }) as Command<GlobeProps>
+  }
+
+  protected override buildScene3D(): Scene3D {
+    const scene = new Scene3D()
+    const distance = RADIUS * Math.max(1.02, this.zoom)
+
+    // Cut to the globe rather than left to the camera's own derivation from the
+    // scene bounds: the atmosphere shell is the outermost thing in the scene and
+    // sizing the planes to it would spend depth precision on the halo. The near
+    // plane has to survive `zoom` coming right down to the surface, which is
+    // what the fraction of the gap is for.
+    scene.perspective({
+      fov: this.fov,
+      near: Math.max(0.01, (distance - RADIUS) * 0.5),
+      far: distance + RADIUS * 4,
+      // Exactly what every other 3D viewport does — the quarter turn between
+      // the stored zero and the camera's, and nothing else. Anything extra here
+      // is a globe whose canvas drag runs backwards against every other node's;
+      // the longitude convention is handled in the *geometry* instead. See
+      // `projection.ts`.
+      orbit: cameraOrbit(this.orbit),
+      elevation: this.elevation,
+      distance,
+    })
+
+    // The same rig the Protein and the 3D viewport use, at the globe's scale: a
+    // key, a rim that is the key from the other side at a fraction of its
+    // strength, and enough ambient that the night side is a planet rather than a
+    // silhouette. The backdrop is the node's own Fills stack — a `Canvas3D`
+    // composites its 3D pass over its 2D fill layers — so there is no space to
+    // paint here and no clear colour to set.
+    scene
+      .light({
+        type: "ambient",
+        intensity: this.ambientIntensity,
+        color: this.ambientColor,
+      })
+      .light(
+        { type: "directional", intensity: this.keyIntensity, color: this.keyColor },
+        { position: [RADIUS * 3, RADIUS * 2, RADIUS * 3] }
+      )
+      .light(
+        {
+          type: "directional",
+          intensity: this.keyIntensity * 0.35,
+          color: this.keyColor,
+        },
+        { position: [-RADIUS * 3, -RADIUS, -RADIUS * 2] }
+      )
+
+    const g3 = new Graphics3D()
+    this.addPlanet(g3)
+    this.addArcs(g3)
+    this.addMarkers(g3)
+    if (this.atmosphere) this.addAtmosphere(g3)
+
+    scene.draw(g3)
+    return scene
+  }
+
+  /** The sphere, wearing the baked map. */
+  private addPlanet(g3: Graphics3D): void {
+    g3.sphere({
+      radius: RADIUS,
+      // Longitude segments matter more than latitude: the silhouette is a
+      // circle of longitude, and a coarse one shows as a faceted rim against
+      // the atmosphere's own smooth curve.
+      segments: [128, 64],
+      fill: this.bakedMap().texture,
+      // Land and sea are matte at this distance; a specular highlight on an
+      // ocean this size reads as a lens flare rather than as water.
+      roughness: 0.95,
+      metalness: 0,
+    })
+  }
+
+  /** The halo. A shell, kept for its back faces — see `atmosphere.ts`. */
+  private addAtmosphere(g3: Graphics3D): void {
+    g3.sphere({
+      radius: RADIUS * Math.max(1.001, this.atmosphereSize),
+      segments: [96, 48],
+      material: atmosphereMaterial(
+        this.atmosphereColor as unknown as NormalizedColor,
+        this.atmosphereFalloff,
+        this.atmosphereIntensity
+      ),
+    })
+  }
+
+  /**
+   * 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(g3: Graphics3D): void {
+    const markers = drawableMarkers(this.markers)
+    if (markers.length === 0) return
+
+    const placements: Transform3D[] = []
+    const colors: Color[] = []
+
+    for (const marker of markers) {
+      const size = marker.size * RADIUS
+      placements.push({
+        // Lifted by a fraction of its own size so a marker sits *on* the
+        // surface rather than half-buried in it, at any size.
+        position: latLonToPosition(marker, RADIUS + size * MARKER_LIFT),
+        scale: size,
+      })
+      colors.push(marker.color)
+    }
+
+    g3.instances(
+      Geo.sphere({ radius: 1, segments: [16, 12] }),
+      // Unlit, and deliberately: a marker is a signal rather than an object, and
+      // one shaded by the scene's key light would go dark exactly when it
+      // rotated to the night side — which is where it most needs to be seen.
+      Mat.basic({ transparent: true }),
+      placements,
+      { colors }
+    )
+  }
+
+  /** The arcs, one swept tube each. */
+  private addArcs(g3: Graphics3D): void {
+    // Resolved against the marker list, because an end may be *pinned* to one —
+    // which is what keeps an arc attached when the place it points at moves.
+    for (const arc of drawableArcs(this.arcs, this.markers)) {
+      const points = greatCircle(arc.from, arc.to, {
+        radius: RADIUS,
+        lift: arc.lift,
+        segments: arcSegments(arc),
+      })
+
+      // `progress` trims the point list rather than scaling the geometry, so a
+      // half-drawn arc is the first half of the real path — the same shape the
+      // finished arc has, stopping early. Two points is the floor a tube can be
+      // swept along.
+      const drawn = Math.max(2, Math.round(points.length * arc.progress))
+
+      g3.mesh(
+        Geo.tube({
+          points: points.slice(0, drawn),
+          radius: arc.width * RADIUS,
+          segments: [drawn, 8],
+        }),
+        // Unlit for the reason the markers are: an arc is an annotation, and one
+        // that dimmed over the night side would vanish halfway across.
+        Mat.basic({ color: arc.color, transparent: true })
+      )
+    }
+  }
+
+  // --- The map cache -------------------------------------------------------
+
+  /**
+   * 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: { key: string; map: BakedMap } | null = null
+
+  private bakedMap(): BakedMap {
+    const style = this.mapStyle()
+    const key = [
+      style.width,
+      style.ocean,
+      style.land,
+      style.border,
+      style.borderWidth,
+      style.graticule,
+      style.graticuleColor,
+      style.graticuleStep,
+      style.graticuleWidth,
+    ].join("|")
+
+    const cached = this.cache
+    if (cached?.key === key) return cached.map
+
+    const map: BakedMap = {
+      texture: {
+        source: worldMapGraphics(style),
+        width: style.width,
+        height: mapHeight(style.width),
+        static: true,
+        identity: `globe:${key}`,
+      },
+    }
+    this.cache = { key, map }
+    return map
+  }
+
+  /** The style props as the one value the baker takes. Also the cache key. */
+  private mapStyle(): WorldMapStyle {
+    return {
+      // Rounded to an even number so the 2:1 height is a whole one; a half-pixel
+      // buffer height is rounded by the rasterizer and the map then samples a
+      // fraction of a row off, which reads as a seam at the equator.
+      width: Math.max(256, Math.round(this.resolution / 2) * 2),
+      ocean: hexOf(this.ocean),
+      land: hexOf(this.land),
+      border: hexOf(this.border),
+      borderWidth: this.borderWidth,
+      graticule: this.graticule,
+      graticuleColor: hexOf(this.graticuleColor),
+      graticuleStep: this.graticuleStep,
+      graticuleWidth: this.graticuleWidth,
+    }
+  }
+}
+
+/**
+ * The signed turn from `from` to `to` that travels less than half a circle.
+ *
+ * Degrees. What stops a flight from 170° to −170° unwinding 340° the wrong way
+ * when it could cross the antimeridian in 20°.
+ */
+function shortestTurn(from: number, to: number): number {
+  return ((((to - from) % 360) + 540) % 360) - 180
+}
+
+
+/**
+ * A colour prop as the string the baker and the cache key both want.
+ *
+ * These props carry no mapper — they are not animatable, so there is no resolved
+ * form to hold — but a caller writing JSX is still free to hand one a tuple, and
+ * a tuple in a cache key would stringify to something that compares equal for
+ * two different colours.
+ */
+function hexOf(value: Color): string {
+  if (typeof value === "string") return value
+  const [r, g, b, a = 1] = value as unknown as NormalizedColor
+  const byte = (channel: number) =>
+    Math.round(Math.min(1, Math.max(0, channel)) * 255)
+  return `rgba(${byte(r)}, ${byte(g)}, ${byte(b)}, ${a})`
+}

package/src/globe/index.ts

@@ -0,0 +1,16 @@
+/**
+ * The globe: a shaded sphere with borders, graticules, markers and the
+ * great-circle arcs between them.
+ *
+ * These files are what `ms add globe` copies. The Natural Earth outline it
+ * draws is **not** among them, nor `world.ts` that decodes it — it is data, and
+ * it stays behind the package so a copy does not write tens of thousands of
+ * coordinates into your `src/`. A copy reads `world` from `@motionscript/geo`.
+ */
+export * from "./atmosphere";
+export * from "./borders";
+export * from "./globe";
+export * from "./globe-places";
+export * from "./places";
+export * from "./projection";
+export * from "./world-map";

package/src/globe/places.ts

@@ -0,0 +1,132 @@
+/**
+ * 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,
+  type ArcEnd,
+  type GlobeArc,
+  type GlobeMarker,
+} from "./globe-places"
+
+/** A marker with everything the render needs decided. */
+export interface DrawableMarker {
+  id: string
+  lat: number
+  lon: number
+  color: string
+  size: number
+  opacity: number
+}
+
+/** An arc with both ends resolved to real coordinates. */
+export interface DrawableArc {
+  id: string
+  from: { lat: number; lon: number }
+  to: { lat: number; lon: number }
+  color: string
+  width: number
+  lift: number
+  progress: number
+}
+
+/**
+ * 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: string): DrawableMarker[] {
+  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: string,
+  markersValue: string
+): DrawableArc[] {
+  const byId = new Map<string, GlobeMarker>()
+  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: ArcEnd,
+  markers: Map<string, GlobeMarker>
+): { lat: number; lon: number } | null {
+  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: Pick<GlobeArc | DrawableArc, "from" | "to">): number {
+  const from = arc.from as { lat: number; lon: number }
+  const to = arc.to as { lat: number; lon: number }
+  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: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value
+}