@codincod/ornament 0.1.0 → 0.2.0

package/README.md

@@ -3,26 +3,36 @@
 The sea behind [CodinCod](https://codincod.com): what lives in it, the weather
 over it, and how each thing is drawn. Published as `@codincod/ornament`.
 
-Nothing here touches a browser. The modules decide where a fish goes, what the
-sky is doing at this hour, and what each drawing looks like, and hand that to a
-renderer. Two renderers read it:
-
-- CodinCod's site, whose `assets/js/ornament/` holds the canvas, SVG and WebGPU
-  halves and the LiveView hooks that start them.
+Outside `src/canvas/`, nothing here touches a browser. The modules decide where
+a fish goes, what the sky is doing at this hour, and what each drawing looks
+like, and hand that to a renderer. Three read it:
+
+- CodinCod's site, whose `assets/js/ornament/` holds the SVG and WebGPU halves
+  and the LiveView hooks that start them, and draws with `src/canvas/` where
+  there is no graphics card.
+- [codin-cod-maintenance](https://codeberg.org/reeven/codin-cod-maintenance),
+  the page codincod.com shows while it is down, which draws with `src/canvas/`
+  and bakes a still with `src/paint/svg.ts`.
 - [seascape](https://github.com/reeveng/seascape), the desktop background, in a
   bare V8 and in Qt's JavaScript engine.
 
 `tsconfig.json` leaves the DOM out of `lib`, so `pnpm check` fails on any
-module that reaches for one.
+module that reaches for one. `src/canvas/` is checked on its own, by
+`tsconfig.canvas.json`, with the DOM.
 
 ## Layout
 
 - `src/*.ts`: one simulation per kind of thing in the water or the sky, each
   with its test beside it.
 - `src/paint/`: what one drawing looks like, and `sea.ts`, which builds a whole
-  frame out of them.
+  frame out of them. `ink.ts` is the colour arithmetic every renderer shares,
+  `colour.ts` reads a theme's colours back out of a stylesheet, and `svg.ts`
+  writes a frame as SVG markup, for a page that has to look right with no
+  script.
 - `src/sizes.ts` and `src/census.ts`: how big things are and how many of them
   there are.
+- `src/canvas/flat.ts`: a frame onto a 2D canvas, the one module here that
+  needs the DOM.
 
 The package ships its TypeScript source. Import a module by its path:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codincod/ornament",
-  "version": "0.1.0",
-  "description": "The sea behind CodinCod: what lives in it, the weather over it, and how each thing is drawn, with no DOM",
+  "version": "0.2.0",
+  "description": "The sea behind CodinCod: what lives in it, the weather over it, how each thing is drawn, and a canvas to draw it on",
   "keywords": [
     "codincod",
     "generative",
@@ -21,7 +21,7 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "typescript": "^7.0.2"
   },
   "homepage": "https://codincod.com/",
@@ -30,7 +30,7 @@
     "url": "https://codeberg.org/reeven/codin-cod-ornament"
   },
   "scripts": {
-    "check": "tsc --noEmit -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.canvas.json",
     "fmt": "biome check --write .",
     "fmt:check": "biome check .",
     "test": "node --test \"src/**/*.test.ts\""

package/src/canvas/flat.ts

@@ -0,0 +1,336 @@
+/**
+ * The sea, onto a canvas, with nothing but the browser's own rasteriser.
+ *
+ * The renderer every machine has. `card.ts` is faster wherever there is a card
+ * to talk to, and this is what draws the water when there is not: an old
+ * browser, a machine without WebGPU, a device that answered the adapter request
+ * with nothing. The picture is the same picture.
+ *
+ * ## Two things a card does per pixel that a canvas cannot
+ *
+ * A fragment shader reads the water's own gradient at the height of every pixel
+ * it fills, and works out how far a light has given out at that same height. A
+ * canvas fill takes one colour, or one gradient built before the fill starts.
+ *
+ * So the height a colour is read at is decided per drawing here. Most of what
+ * swims is small enough that one reading is the truth: a fish is a few dozen px
+ * tall and the water does not change over that. What is not small says so, by
+ * fading down the box or by covering a good share of it, and those are drawn
+ * through a gradient with the same arithmetic sampled along it. Both renderers
+ * agree on the numbers; they disagree on how often they ask.
+ *
+ * ## Why the fill rule matters more than it looks
+ *
+ * An animal is several closed shapes meant to overlap: a body, a tail swung off
+ * its joint, a fin rooted inside the back. Filled as one path with the non-zero
+ * rule they are one silhouette, which is the animal. Filled one after another
+ * they are three shapes painted over each other, and at the weight ornament is
+ * drawn at every overlap shows as a bright seam. A canvas fills non-zero by
+ * default, so this gets it for nothing; the card has to be told.
+ */
+import { FORM, held, OWN, Reader, type View } from "../paint/frame.ts"
+import { css, hueOf, leftAt, type Palette } from "../paint/ink.ts"
+
+/**
+ * How tall a drawing has to be, as a share of the box, before it is worth a
+ * gradient rather than one reading of the water.
+ *
+ * Under this the error is smaller than the step between two neighbouring values
+ * of an eight bit channel, so a gradient would cost a fill and change nothing.
+ */
+const TALL = 0.08
+
+/**
+ * How many places a gradient is sampled at.
+ *
+ * Both the water's colour and how far a light has given out are curves, and a
+ * gradient between two stops is a straight line. This is where the two stop
+ * being told apart on a screen.
+ */
+const STOPS = 7
+
+export interface Box {
+  height: number
+  width: number
+}
+
+export interface FlatOptions {
+  /**
+   * How far past the box a drawing may stand before it is skipped, as a share
+   * of the box.
+   *
+   * Nothing in the water knows where the edge of the picture is, so a fish that
+   * has left is still swum and a plant behind a mass of near rock is still cut.
+   * A renderer is the last chance to not pay for them.
+   */
+  bleed?: number
+}
+
+/** What of the water the box is showing. */
+interface Seen {
+  foot: number
+  left: number
+  right: number
+  top: number
+}
+
+export interface Flat {
+  draw(floats: Float32Array, palette: Palette, box: Box, density?: number, view?: View | null): void
+}
+
+/**
+ * A canvas that will draw a frame of this water whenever it is handed one.
+ *
+ * It keeps no clock and owns no simulation. Something else steps the sea and
+ * hands over the block; all this does is put it on the screen.
+ */
+export function createFlat(canvas: HTMLCanvasElement, options: FlatOptions = {}): Flat | null {
+  const context = canvas.getContext("2d")
+  if (!context) return null
+
+  const bleed = options.bleed ?? 0.25
+
+  // Where each drawing is and how far back it stands, so the solid ones can be
+  // put in order. Kept between frames: a busy sea is a few thousand drawings,
+  // and three arrays of them rebuilt sixty times a second is the sort of
+  // housekeeping that costs more than the work it is for.
+  let places = new Int32Array(4096)
+  let lanes = new Float32Array(4096)
+  let order: number[] = []
+
+  const room = (needed: number) => {
+    if (needed > places.length) {
+      const size = 1 << Math.ceil(Math.log2(Math.max(16, needed)))
+      places = new Int32Array(size)
+      lanes = new Float32Array(size)
+    }
+    while (order.length < needed) order.push(order.length)
+    if (order.length > needed) order.length = needed
+  }
+
+  return {
+    /**
+     * One frame, onto the canvas.
+     *
+     * `box` is the water's own size in the units it was laid out in, which is
+     * not the canvas's size in pixels: a screen at twice the density draws the
+     * same sea out of four times as many of them.
+     */
+    draw(
+      floats: Float32Array,
+      palette: Palette,
+      box: Box,
+      density = 1,
+      view: View | null = null,
+    ): void {
+      const camera = held(floats)
+      const reader = new Reader(floats)
+
+      context.setTransform(density, 0, 0, density, 0, 0)
+      context.clearRect(0, 0, box.width, box.height)
+
+      const middle = { x: box.width / 2, y: box.height / 2 }
+
+      if (view) {
+        context.translate(middle.x, middle.y)
+        context.scale(view.scale, view.scale)
+        context.translate(-view.x, -view.y)
+      } else {
+        // The frame, held by somebody rather than bolted to a tripod. It is
+        // drawn a little larger than its box to pay for the wander, which is
+        // what overscan is for: a frame that has wandered must never be a frame
+        // with the page showing along one edge.
+        context.translate(middle.x + camera.swayX, middle.y + camera.swayY)
+        context.rotate(camera.tilt)
+        context.scale(camera.overscan, camera.overscan)
+        context.translate(-middle.x, -middle.y)
+      }
+
+      // What of the water is actually in the box, which a window on a larger
+      // water sees only a piece of. Nothing in the sea knows where the edge of
+      // the picture is, so this is the last chance not to pay for what is past
+      // it.
+      const seen: Seen = view
+        ? {
+            foot: view.y + box.height / (2 * view.scale),
+            left: view.x - box.width / (2 * view.scale),
+            right: view.x + box.width / (2 * view.scale),
+            top: view.y - box.height / (2 * view.scale),
+          }
+        : { foot: box.height, left: 0, right: box.width, top: 0 }
+
+      room(reader.count)
+
+      // Where everything is, and which of the two it is in. Anything you can
+      // see the water through is laid over what is already there in the order
+      // it arrives, since two lights over one another are a painting rather
+      // than a stack of distances; everything else takes its turn by how far
+      // back it stands, which an infinite lane arranges.
+      let kept = 0
+      while (reader.next()) {
+        const through =
+          reader.alpha < 0.999 || reader.form === FORM.light || reader.form === FORM.wash
+        places[kept] = reader.offset
+        lanes[kept] = through ? Number.POSITIVE_INFINITY : reader.lane
+        kept++
+      }
+
+      // Stable, because equal lanes have to keep the order they were drawn in.
+      order.length = kept
+      for (let at = 0; at < kept; at++) order[at] = at
+      order.sort((a, b) => {
+        const one = lanes[a] ?? 0
+        const two = lanes[b] ?? 0
+        return one === two ? a - b : one - two
+      })
+
+      const paint = new Reader(floats)
+      for (const which of order) {
+        paint.stand(places[which] ?? 0)
+        one(context, paint, palette, box, seen, bleed)
+      }
+
+      context.setTransform(1, 0, 0, 1, 0, 0)
+    },
+  }
+}
+
+/** One drawing, whichever of the four kinds it is. */
+function one(
+  context: CanvasRenderingContext2D,
+  mark: Reader,
+  palette: Palette,
+  box: Box,
+  seen: Seen,
+  bleed: number,
+): void {
+  if (mark.alpha <= 0.002) return
+
+  if (mark.form === FORM.wash) {
+    context.fillStyle = down(context, mark, palette, box, 0, box.height)
+    context.fillRect(0, 0, box.width, box.height)
+    return
+  }
+
+  if (mark.form === FORM.light) {
+    light(context, mark, palette, box)
+    return
+  }
+
+  const floats = mark.floats
+  const shape = new Path2D()
+  let top = Number.POSITIVE_INFINITY
+  let foot = Number.NEGATIVE_INFINITY
+  let left = Number.POSITIVE_INFINITY
+  let right = Number.NEGATIVE_INFINITY
+
+  mark.each((from, points) => {
+    if (points < 2) return
+    for (let i = 0; i < points; i++) {
+      const x = floats[from + i * 2] ?? 0
+      const y = floats[from + i * 2 + 1] ?? 0
+      if (i === 0) shape.moveTo(x, y)
+      else shape.lineTo(x, y)
+      if (y < top) top = y
+      if (y > foot) foot = y
+      if (x < left) left = x
+      if (x > right) right = x
+    }
+    if (mark.form !== FORM.stroke) shape.closePath()
+  })
+
+  if (top > foot) return
+
+  // Off the picture entirely, which happens to a fish that has left and to
+  // every plant standing behind a mass of near rock.
+  const margin = Math.max(seen.right - seen.left, seen.foot - seen.top) * bleed
+  if (right < seen.left - margin || left > seen.right + margin) return
+  if (foot < seen.top - margin || top > seen.foot + margin) return
+
+  const tall = foot - top > box.height * TALL
+  const ink = tall
+    ? down(context, mark, palette, box, top, foot)
+    : flat(mark, palette, box, mark.shade === OWN ? (top + foot) / 2 : mark.shade)
+
+  if (mark.form === FORM.stroke) {
+    context.strokeStyle = ink
+    context.lineWidth = Math.max(0.1, mark.width)
+    context.lineCap = "round"
+    context.lineJoin = "round"
+    context.stroke(shape)
+    return
+  }
+
+  context.fillStyle = ink
+  context.fill(shape)
+}
+
+/**
+ * A round light, as an ellipse with the falling off built into a gradient.
+ *
+ * The card does this per pixel out of a distance from the middle. Here it is a
+ * radial gradient with the same curve sampled along it, which is the one place
+ * a canvas gets the better bargain: a gradient is a gradient however many
+ * pixels it covers.
+ */
+function light(context: CanvasRenderingContext2D, mark: Reader, palette: Palette, box: Box): void {
+  const floats = mark.floats
+  const cx = floats[mark.first + 1] ?? 0
+  const cy = floats[mark.first + 2] ?? 0
+  const across = mark.width
+  if (across <= 0) return
+
+  const hue = hueOf(
+    palette,
+    mark.tone,
+    mark.weight,
+    mark.shade === OWN ? cy : mark.shade,
+    box.height,
+  )
+  // Under 1 this is a streak rather than a disc, which is what a lens does with
+  // a light it cannot quite hold. The gradient is built inside the squash as
+  // well as the shape, since a gradient is read in whatever space it is filled.
+  const thin = Math.max(0.001, mark.thin)
+
+  context.save()
+  context.translate(cx, cy)
+  context.scale(1, thin)
+
+  const glow = context.createRadialGradient(0, 0, 0, 0, 0, across)
+  for (let stop = 0; stop < STOPS; stop++) {
+    const t = stop / (STOPS - 1)
+    glow.addColorStop(t, css(hue, mark.alpha * (1 - t) ** mark.fall))
+  }
+
+  context.fillStyle = glow
+  context.beginPath()
+  context.arc(0, 0, across, 0, Math.PI * 2)
+  context.fill()
+  context.restore()
+}
+
+/** One colour, read at one height. */
+function flat(mark: Reader, palette: Palette, box: Box, y: number): string {
+  const hue = hueOf(palette, mark.tone, mark.weight, y, box.height)
+  return css(hue, leftAt(mark.alpha, mark.fadeTop, mark.fadeSpan, mark.fall, mark.spent, y))
+}
+
+/** The same, sampled down the drawing's own height. */
+function down(
+  context: CanvasRenderingContext2D,
+  mark: Reader,
+  palette: Palette,
+  box: Box,
+  top: number,
+  foot: number,
+): CanvasGradient {
+  const run = context.createLinearGradient(0, top, 0, Math.max(top + 1, foot))
+
+  for (let stop = 0; stop < STOPS; stop++) {
+    const t = stop / (STOPS - 1)
+    const y = top + (foot - top) * t
+    run.addColorStop(t, flat(mark, palette, box, mark.shade === OWN ? y : mark.shade))
+  }
+
+  return run
+}

package/src/paint/colour.ts

@@ -0,0 +1,86 @@
+/**
+ * A theme's colour, as numbers a renderer can mix.
+ *
+ * A renderer is handed its two colours as whatever a page's stylesheet hands
+ * back, and needs them as sRGB in 0 to 1 to mix the water from them.
+ *
+ * ## Why the colours are parsed rather than measured
+ *
+ * The obvious way to turn a theme token into numbers is to fill a pixel with it
+ * and read the pixel back, which is the browser doing the colour conversion for
+ * you. It is also wrong here. A browser with fingerprinting protection on
+ * (Librewolf, Brave, Firefox with `resistFingerprinting`) perturbs canvas
+ * readback on purpose, so the same token comes back a slightly different colour
+ * on every load, and an ornament whose hue wanders between reloads is an
+ * ornament that looks broken.
+ *
+ * Parsing is therefore the only stable answer. Only what a computed style can
+ * actually hand back has to be understood, which is `rgb()` for anything the
+ * page states in sRGB and `oklch()` for the theme tokens, since a computed
+ * colour keeps the space it was authored in. Anything else returns null and the
+ * caller falls back to colours of its own.
+ */
+
+export type Rgb = readonly [number, number, number]
+
+const clamp01 = (value: number): number => Math.min(1, Math.max(0, value))
+
+/**
+ * Oklab to linear sRGB, then to sRGB. Ottosson's matrices, as published.
+ *
+ * Out-of-gamut values are clamped per channel, which is what a browser does
+ * when it paints one.
+ */
+function oklabToRgb(lightness: number, a: number, b: number): Rgb {
+  const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3
+
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ]
+
+  return linear.map((channel) => {
+    const value = clamp01(channel)
+    return value <= 0.0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055
+  }) as unknown as Rgb
+}
+
+const numbers = (css: string): number[] =>
+  css
+    .slice(css.indexOf("(") + 1, css.lastIndexOf(")"))
+    .split(/[\s,/]+/)
+    .filter(Boolean)
+    .map((part) => (part.endsWith("%") ? Number.parseFloat(part) / 100 : Number.parseFloat(part)))
+
+/**
+ * A computed colour as sRGB in 0 to 1, or null for anything not understood,
+ * which includes the transparent an element with no background of its own
+ * reports.
+ */
+export function parseColour(css: string): Rgb | null {
+  const value = css.trim().toLowerCase()
+
+  if (value.startsWith("rgb")) {
+    const [r, g, b, alpha] = numbers(value)
+    if (r == null || g == null || b == null || alpha === 0) return null
+    return [clamp01(r / 255), clamp01(g / 255), clamp01(b / 255)]
+  }
+
+  if (value.startsWith("oklch")) {
+    const [lightness, chroma, hue, alpha] = numbers(value)
+    if (lightness == null || chroma == null || alpha === 0) return null
+    const angle = ((hue ?? 0) * Math.PI) / 180
+    return oklabToRgb(lightness, chroma * Math.cos(angle), chroma * Math.sin(angle))
+  }
+
+  if (value.startsWith("oklab")) {
+    const [lightness, a, b, alpha] = numbers(value)
+    if (lightness == null || a == null || b == null || alpha === 0) return null
+    return oklabToRgb(lightness, a, b)
+  }
+
+  return null
+}

package/src/paint/ink.ts

@@ -0,0 +1,134 @@
+/**
+ * What colour a drawing comes out, and how much of it there is.
+ *
+ * Every colour in this scene is worked out from two: the theme's own ink and
+ * the surface it is standing on. That is what lets a theme switch recolour the
+ * whole sea without a single drawing knowing it happened, and it is why nothing
+ * in `paint/` names a colour. A drawing says how heavy it is and which of the
+ * two it is mixed from, and the answer is worked out here.
+ *
+ * The exceptions are the lights, which are the only colours in the picture that
+ * are not the theme's. A sun is the colour a sun is.
+ *
+ * ## Where it is read
+ *
+ * A card reads it per pixel, in the fragment shader, so a shape spanning half
+ * the box takes the water's own gradient across its whole height. A canvas
+ * cannot: a fill is one colour, or one gradient built before the fill. So the
+ * same arithmetic is here in TypeScript, and `flat.ts` decides how many times to
+ * ask it. The two agree on every number, which is the point of the file.
+ */
+
+import type { Rgb } from "./colour.ts"
+import { TONE } from "./pen.ts"
+
+/**
+ * How much ink is in the water at the surface.
+ *
+ * The water is not the page's background with things drawn on it. It is a
+ * column, lightest at the top where the light comes in and giving out with
+ * depth, and this is how far from the background the lit top of it stands.
+ */
+const LIT = 0.13
+
+/**
+ * How fast the light gives out going down.
+ *
+ * Over 1, so the top half of the box keeps most of it and the bottom goes
+ * quickly, which is what looking down a water column actually looks like. A
+ * straight line reads as a printed gradient.
+ */
+const SINKAGE = 2.1
+
+/** The three lights, which are the only colours here the theme does not own. */
+const SUNLIGHT: Rgb = [1, 0.93, 0.76]
+const MOONLIGHT: Rgb = [0.95, 0.92, 0.85]
+const DUSKLIGHT: Rgb = [0.91, 0.64, 0.3]
+
+export interface Palette {
+  /** The theme's own ink, which everything in the water is drawn towards. */
+  ink: Rgb
+  /** What the water is standing on, which everything fades into. */
+  surface: Rgb
+}
+
+const mix = (a: Rgb, b: Rgb, at: number): Rgb => [
+  a[0] + (b[0] - a[0]) * at,
+  a[1] + (b[1] - a[1]) * at,
+  a[2] + (b[2] - a[2]) * at,
+]
+
+/** The water at a height in the box, lit from above and giving up with depth. */
+export function waterAt(palette: Palette, y: number, height: number): Rgb {
+  const t = Math.min(1, Math.max(0, y / Math.max(1, height)))
+  return mix(palette.surface, mix(palette.surface, palette.ink, LIT), (1 - t) ** SINKAGE)
+}
+
+/**
+ * One drawing's colour: the water where it is, with its own weight mixed in.
+ *
+ * `weight` is how much of the thing stopped the light. A body is one weight,
+ * because a body at this distance is one shape the light did not come back
+ * through, and that is what a silhouette is.
+ */
+export function hueOf(
+  palette: Palette,
+  tone: number,
+  weight: number,
+  y: number,
+  height: number,
+): Rgb {
+  const base = waterAt(palette, y, height)
+  const w = Math.min(1, Math.max(0, weight))
+
+  switch (tone & 0xff) {
+    case TONE.shadow:
+      return mix(base, palette.surface, w)
+    case TONE.sun:
+      return SUNLIGHT
+    case TONE.moon:
+      return MOONLIGHT
+    case TONE.dusk:
+      return DUSKLIGHT
+    case TONE.surface:
+      return palette.surface
+    case TONE.ink:
+      return palette.ink
+    // The water column, which on a page is the page itself: whatever is behind
+    // the canvas is what you see through it, so nothing is painted at all.
+    case TONE.wall:
+      return base
+    default:
+      return mix(base, palette.ink, w)
+  }
+}
+
+export const css = (hue: Rgb, alpha: number): string =>
+  `rgba(${Math.round(hue[0] * 255)},${Math.round(hue[1] * 255)},${Math.round(hue[2] * 255)},${alpha})`
+
+/**
+ * What is left of a shape's own light at a height in the box.
+ *
+ * Two shapes of falling off and no others. Everything that fades down the box
+ * takes the same exponent, because a light in water does not thin in a straight
+ * line and a straight line is what two ends of a gradient draw. `spent` is the
+ * one that does not: it holds most of its strength for the first half of its
+ * length and then goes quickly, which is what a shaft of sunlight does and no
+ * single exponent draws.
+ */
+export function leftAt(
+  alpha: number,
+  fadeTop: number,
+  fadeSpan: number,
+  fall: number,
+  spent: boolean,
+  y: number,
+): number {
+  if (fadeSpan <= 0) return alpha
+  const down = Math.min(1, Math.max(0, (y - fadeTop) / fadeSpan))
+  if (spent) {
+    const held = 1 - down * down
+    return alpha * held * held
+  }
+  return alpha * (1 - down) ** fall
+}

package/src/paint/svg.ts

@@ -0,0 +1,326 @@
+/**
+ * A frame of the water as SVG markup, for somewhere nothing runs.
+ *
+ * The same picture `canvas/flat.ts` puts on a canvas, written out as text
+ * instead: a page that has to look right with scripts off, or a file somebody
+ * asked for. It makes the same decisions in the same order (the camera, the
+ * stable sort by lane, one reading of the water for a small drawing and a
+ * gradient down a tall one), so a still and a canvas of one frame are the same
+ * picture.
+ *
+ * Nothing here touches a browser. The answer is a string, and building it
+ * needs no DOM.
+ *
+ * ## Coloured by the page, not here
+ *
+ * Every colour in the water apart from the three lights is a mix of the
+ * theme's ink and its surface, and `ink.ts` only ever mixes those two in a
+ * straight line, so each one is a single number: how much ink. That number is
+ * what is written down, as a class whose colour is a `color-mix()` of two CSS
+ * colours the caller names. Given `var(--primary)` and `var(--base-100)`, one
+ * still serves every theme a page has, and a theme switch recolours it with
+ * nothing redrawn.
+ */
+import { FORM, held, OWN, Reader } from "./frame.ts"
+import { hueOf, leftAt, type Palette } from "./ink.ts"
+import { TONE } from "./pen.ts"
+
+/** How tall a drawing has to be before it is worth a gradient; see `canvas/flat.ts`. */
+const TALL = 0.08
+
+/** How many places a gradient is sampled at; see `canvas/flat.ts`. */
+const STOPS = 7
+
+/**
+ * How finely the share of ink is written, in steps of the way from surface to
+ * ink. Finer than a channel of eight bits can tell apart on any theme whose two
+ * colours are not black and white.
+ */
+const SHADES = 400
+
+/**
+ * Ink as white and surface as black, so that the colour `ink.ts` answers is
+ * the share of ink itself, in every channel.
+ */
+const UNIT: Palette = { ink: [1, 1, 1], surface: [0, 0, 0] }
+
+const LIGHTS: ReadonlySet<number> = new Set([TONE.dusk, TONE.moon, TONE.sun])
+
+export interface Box {
+  height: number
+  width: number
+}
+
+/** The two colours the water is mixed from, as CSS: any colour, a `var()`, a keyword. */
+export interface Theme {
+  ink: string
+  surface: string
+}
+
+export interface SvgOptions {
+  /**
+   * Attributes for the `<svg>` itself, written as given: a class, a role, how
+   * it should be fitted to its box.
+   */
+  attributes?: Record<string, string>
+  /** How far past the box a drawing may stand before it is skipped, as a share of the box. */
+  bleed?: number
+  /**
+   * How many places after the point a coordinate keeps. A still the width of
+   * a screen needs none; a plate a few hundred pixels across wants one.
+   */
+  digits?: number
+  /**
+   * What every class and gradient id starts with. Two stills on one page need
+   * two, or the second one is coloured and filled from the first one's.
+   */
+  prefix?: string
+}
+
+/** What one reading of the water comes to: a share of ink, or a light of its own. */
+interface Tint {
+  alpha: number
+  light: string | null
+  share: number
+}
+
+const hex = (rgb: readonly number[]): string =>
+  `#${rgb
+    .map((channel) =>
+      Math.round(Math.min(1, Math.max(0, channel)) * 255)
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`
+
+/** A number in as few characters as it will go: `.5`, `-.25`, `3`. */
+const short = (value: number, digits: number): string => {
+  const written = Number(value.toFixed(digits))
+  if (written === 0) return "0"
+  return String(written).replace(/^(-?)0\./, "$1.")
+}
+
+const escape = (value: string): string =>
+  value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;")
+
+/** Numbers one after another, with a space only where a minus sign is not one. */
+const run = (numbers: string[]): string =>
+  numbers.reduce(
+    (line, next) => (line === "" || next.startsWith("-") ? line + next : `${line} ${next}`),
+    "",
+  )
+
+/** One frame, as an `<svg>` element whose user space is the water's own box. */
+export function frameToSvg(
+  floats: Float32Array,
+  theme: Theme,
+  box: Box,
+  options: SvgOptions = {},
+): string {
+  const bleed = options.bleed ?? 0.25
+  const digits = options.digits ?? 1
+  const prefix = options.prefix ?? "sea"
+  const scale = 10 ** digits
+  const camera = held(floats)
+  const n = (value: number) => short(value, digits)
+  const alpha = (value: number) => short(value, 3)
+
+  const defs: string[] = []
+  const body: string[] = []
+  const shares = new Set<number>()
+  let made = 0
+
+  const tint = (mark: Reader, y: number, strength: number): Tint => {
+    const hue = hueOf(UNIT, mark.tone, mark.weight, y, box.height)
+    const light = LIGHTS.has(mark.tone & 0xff) ? hex(hue) : null
+    return { alpha: strength, light, share: Math.round((hue[0] ?? 0) * SHADES) }
+  }
+
+  /** How a drawing names its colour: a class for a share of ink, the light itself otherwise. */
+  const named = (colour: Tint, property: "fill" | "stop-color" | "stroke"): string => {
+    if (colour.light) return ` ${property}="${colour.light}"`
+    shares.add(colour.share)
+    const own = property === "fill" ? "" : ` ${property}="currentColor"`
+    return ` class="${prefix}${colour.share}"${own}`
+  }
+
+  const opacity = (value: number, property: string): string =>
+    value >= 0.999 ? "" : ` ${property}="${alpha(value)}"`
+
+  /** One colour, read at one height. */
+  const reading = (mark: Reader, y: number): Tint =>
+    tint(mark, y, leftAt(mark.alpha, mark.fadeTop, mark.fadeSpan, mark.fall, mark.spent, y))
+
+  const gradient = (open: string, close: string, stops: Tint[]): string => {
+    const id = `${prefix}-${made++}`
+    const written = stops.map(
+      (colour, at) =>
+        `<stop offset="${short(at / (stops.length - 1), 3)}"${named(colour, "stop-color")}${opacity(colour.alpha, "stop-opacity")}/>`,
+    )
+    defs.push(`<${open} id="${id}">${written.join("")}</${close}>`)
+    return `url(#${id})`
+  }
+
+  /** The same reading, sampled down the drawing's own height. */
+  const down = (mark: Reader, top: number, foot: number): string => {
+    const stops: Tint[] = []
+    for (let at = 0; at < STOPS; at++) {
+      const y = top + ((foot - top) * at) / (STOPS - 1)
+      stops.push(reading(mark, mark.shade === OWN ? y : mark.shade))
+    }
+    const bottom = Math.max(top + 1, foot)
+    return gradient(
+      `linearGradient gradientUnits="userSpaceOnUse" x1="0" y1="${n(top)}" x2="0" y2="${n(bottom)}"`,
+      "linearGradient",
+      stops,
+    )
+  }
+
+  const light = (mark: Reader) => {
+    const cx = floats[mark.first + 1] ?? 0
+    const cy = floats[mark.first + 2] ?? 0
+    const across = mark.width
+    if (across <= 0) return
+
+    const y = mark.shade === OWN ? cy : mark.shade
+    const stops: Tint[] = []
+    for (let at = 0; at < STOPS; at++) {
+      stops.push(tint(mark, y, mark.alpha * (1 - at / (STOPS - 1)) ** mark.fall))
+    }
+    const glow = gradient(
+      `radialGradient gradientUnits="userSpaceOnUse" cx="0" cy="0" r="${n(across)}"`,
+      "radialGradient",
+      stops,
+    )
+    // Squashed under 1, the way `canvas/flat.ts` squashes it: the gradient is
+    // read in the same space the circle is drawn in.
+    const thin = Math.max(0.001, mark.thin)
+    body.push(
+      `<circle r="${n(across)}" fill="${glow}" transform="translate(${n(cx)} ${n(cy)}) scale(1 ${short(thin, 3)})"/>`,
+    )
+  }
+
+  const shape = (mark: Reader) => {
+    let path = ""
+    let top = Number.POSITIVE_INFINITY
+    let foot = Number.NEGATIVE_INFINITY
+    let left = Number.POSITIVE_INFINITY
+    let right = Number.NEGATIVE_INFINITY
+
+    // Whole units of the precision asked for, each point written as the step
+    // from the one before, and a step of nothing left out.
+    mark.each((from, points) => {
+      if (points < 2) return
+      let px = 0
+      let py = 0
+      const steps: string[] = []
+      for (let i = 0; i < points; i++) {
+        const x = floats[from + i * 2] ?? 0
+        const y = floats[from + i * 2 + 1] ?? 0
+        if (y < top) top = y
+        if (y > foot) foot = y
+        if (x < left) left = x
+        if (x > right) right = x
+
+        const qx = Math.round(x * scale)
+        const qy = Math.round(y * scale)
+        if (i === 0) {
+          path += `M${run([n(qx / scale), n(qy / scale)])}`
+        } else if (qx !== px || qy !== py) {
+          steps.push(n((qx - px) / scale), n((qy - py) / scale))
+        }
+        px = qx
+        py = qy
+      }
+      if (steps.length > 0) path += `l${run(steps)}`
+      if (mark.form !== FORM.stroke) path += "z"
+    })
+
+    if (top > foot) return
+
+    const margin = Math.max(box.width, box.height) * bleed
+    if (right < -margin || left > box.width + margin) return
+    if (foot < -margin || top > box.height + margin) return
+
+    const stroked = mark.form === FORM.stroke
+    const property = stroked ? "stroke" : "fill"
+    let paint: string
+    if (foot - top > box.height * TALL) {
+      paint = ` ${property}="${down(mark, top, foot)}"`
+    } else {
+      const colour = reading(mark, mark.shade === OWN ? (top + foot) / 2 : mark.shade)
+      paint = named(colour, property) + opacity(colour.alpha, `${property}-opacity`)
+    }
+
+    if (stroked) {
+      body.push(
+        `<path d="${path}" fill="none"${paint} stroke-width="${n(Math.max(0.1, mark.width))}" stroke-linecap="round" stroke-linejoin="round"/>`,
+      )
+      return
+    }
+
+    body.push(`<path d="${path}"${paint}/>`)
+  }
+
+  // Where everything is and how far back it stands, then the same stable sort
+  // `canvas/flat.ts` makes: anything you can see the water through keeps the
+  // order it arrived in, over everything solid.
+  const reader = new Reader(floats)
+  const places: number[] = []
+  const lanes: number[] = []
+  while (reader.next()) {
+    const through = reader.alpha < 0.999 || reader.form === FORM.light || reader.form === FORM.wash
+    places.push(reader.offset)
+    lanes.push(through ? Number.POSITIVE_INFINITY : reader.lane)
+  }
+  const order = places.map((_, at) => at)
+  order.sort((a, b) => {
+    const one = lanes[a] ?? 0
+    const two = lanes[b] ?? 0
+    return one === two ? a - b : one - two
+  })
+
+  const paint = new Reader(floats)
+  for (const which of order) {
+    paint.stand(places[which] ?? 0)
+    if (paint.alpha <= 0.002) continue
+    if (paint.form === FORM.wash) {
+      body.push(
+        `<rect width="${n(box.width)}" height="${n(box.height)}" fill="${down(paint, 0, box.height)}"/>`,
+      )
+    } else if (paint.form === FORM.light) {
+      light(paint)
+    } else {
+      shape(paint)
+    }
+  }
+
+  // A class per share of ink in use, setting `color`, which a fill takes from
+  // the group and a stroke or a stop takes as `currentColor`.
+  const classes = [...shares]
+    .sort((a, b) => a - b)
+    .map(
+      (share) =>
+        `.${prefix}${share}{color:color-mix(in srgb,${theme.ink} ${short((share * 100) / SHADES, 2)}%,${theme.surface})}`,
+    )
+
+  // The frame as the camera holds it, a little larger than its box to pay for
+  // the wander, exactly as `canvas/flat.ts` holds it.
+  const mx = box.width / 2
+  const my = box.height / 2
+  const hold =
+    `translate(${n(mx + camera.swayX)} ${n(my + camera.swayY)}) ` +
+    `rotate(${short((camera.tilt * 180) / Math.PI, 3)}) ` +
+    `scale(${short(camera.overscan, 4)}) translate(${n(-mx)} ${n(-my)})`
+
+  const attributes = Object.entries(options.attributes ?? {})
+    .map(([name, value]) => ` ${name}="${escape(value)}"`)
+    .join("")
+
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${n(box.width)} ${n(box.height)}"${attributes}>` +
+    `<style>${escape(classes.join(""))}</style>` +
+    `<defs>${defs.join("")}</defs>` +
+    `<g fill="currentColor" transform="${hold}">${body.join("")}</g></svg>`
+  )
+}