@codincod/ornament 0.0.0-stage → 0.2.0

package/src/paint/specimen.ts

@@ -0,0 +1,300 @@
+/**
+ * One animal, alone, with the water held close enough to see it.
+ *
+ * A sea is drawn to be a sea: an animal in it is a few percent of the box
+ * across, because that is what a fish at eight metres actually looks like and
+ * `sizes.ts` is not going to lie about it for the sake of a nice picture. That
+ * is right for a background and useless for a plate, and a plate is what finds
+ * drawing faults. At the weight ornament ships at, a wreck that is upside down
+ * and a wreck that is working look identical.
+ *
+ * So a specimen is not a bigger animal. It is the same animal in the same
+ * water, with the camera brought in until it fills the frame, and `look` is
+ * where to point it. Nothing about the drawing changes, which is the whole
+ * value: a fault seen here is a fault the sea has.
+ *
+ * ## Why the water is bigger than the box it is shown in
+ *
+ * Because the animal has to have somewhere to be. A fish given a box the size
+ * of the view spends its life against an edge it can feel; given room, it swims
+ * about its business and the camera follows. What is shown is a window on a
+ * water that carries on past it.
+ */
+import type { Presence } from "../biome.ts"
+import { createCephalopods } from "../cephalopods.ts"
+import { createJellies, type JellyKind } from "../jellies.ts"
+import { createPuffers, type Puffers } from "../puffers.ts"
+import { createSeabed } from "../seabed.ts"
+import { createShoal, type Kind as FishKind } from "../shoal.ts"
+import { createWalkers } from "../walkers.ts"
+import { paintInklings, paintJellies, paintPuffers, paintShoal, paintWalkers } from "./life.ts"
+import { Pen } from "./pen.ts"
+import type { Box } from "./sky.ts"
+
+/**
+ * The ones the design system shows, one from each family that stays in frame.
+ *
+ * The animals that cross rather than live here are deliberately not among
+ * them. A shark keeps a rest between crossings measured in minutes, so a plate
+ * of one is a plate of empty water for most of the time somebody is looking at
+ * it, and a shark wound on until it is there is a shark on a treadmill.
+ */
+export type Kind = "crab" | "jellyfish" | "octopus" | "pufferfish" | "swordfish"
+
+export const KINDS: readonly Kind[] = ["swordfish", "jellyfish", "octopus", "crab", "pufferfish"]
+
+/** What each one is, for a page that has to say. */
+export const GLOSS: Readonly<Record<Kind, string>> = {
+  crab: "It goes where it decides to go, and the current has no say in it.",
+  jellyfish: "A moon jelly, which gets a second push out of its own refill.",
+  octopus: "The only thing down there with a repertoire rather than a rhythm.",
+  pufferfish: "It is a fish until something crowds it, and then it is a ball of spines.",
+  swordfish: "A billfish over a reef is a visitor from the water beyond it.",
+}
+
+/**
+ * How much bigger the water is than the window on it.
+ *
+ * Enough that the animal is never against a wall, and no more: everything in
+ * this water is stepped whether it is in the frame or not, so room is paid for
+ * every frame.
+ */
+const ROOM = 5
+
+/** How many numbers a plate's frame is given. One animal is not a sea. */
+const BLOCK = 1 << 16
+
+/** How much of the window the animal is meant to take up. */
+const FILLS = 0.72
+
+/**
+ * How far a drawing actually reaches, against the size the animal reports.
+ *
+ * An animal's size is the size of the animal, and a drawing of one is bigger
+ * than that in every case where something trails: an octopus is measured across
+ * its head and drawn with two head-lengths of arms under it, a crab is measured
+ * across its shell and stands on legs half again as wide, a pufferfish is
+ * measured deflated and spends its interesting seconds twice that with its
+ * spines out, and a moon jelly is a bell with a curtain hanging off it. `drop`
+ * is the other half of the same fact, because none of it trails evenly: what
+ * hangs, hangs downwards, so the middle of the drawing is below the middle of
+ * the animal.
+ *
+ * It is only ever a plate's business. A sea draws these at the size they are
+ * and never has to frame one.
+ */
+const REACH: Readonly<Record<Kind, { drop: number; wide: number }>> = {
+  crab: { drop: 0.06, wide: 2.05 },
+  jellyfish: { drop: 0.34, wide: 1.6 },
+  octopus: { drop: 0.28, wide: 1.9 },
+  pufferfish: { drop: 0, wide: 2.15 },
+  swordfish: { drop: 0, wide: 1.15 },
+}
+
+/**
+ * What crowds the pufferfish, and how often.
+ *
+ * A pufferfish at rest is a slightly lumpy fish sculling about, and the drawing
+ * worth judging is the other one. In a sea the thing that comes near is a shark
+ * or a hull; on a plate it is whoever is looking, so that is what this is:
+ * something several times the animal's size, with its whole attention on it,
+ * leaning in for a few seconds out of every `every` and going away again.
+ *
+ * It is the one thing on a plate that is not in the water. It is there because
+ * the drawing this plate exists to show is the ball of spines, and the animal
+ * will not make one to order: it swells at what the water is doing, and a plate
+ * with nothing in it is a plate of water doing nothing.
+ */
+const LOOKING = { every: 24, menace: 1, near: 3, size: 3 }
+
+/** How light it is on a plate. */
+const DAYLIGHT = 1
+
+/** How many numbers stand in front of a frame's count; see `frame.ts`. */
+const HEAD = 6
+
+export interface PlateOptions {
+  height: number
+  seed?: number
+  width: number
+}
+
+export interface Plate {
+  /** The window's own size, which is not the water's. */
+  readonly box: Box
+  readonly geometry: Float32Array
+  /** Where to point the camera, and how far in. */
+  look(): { scale: number; x: number; y: number }
+  over(): number
+  step(seconds: number): void
+  wind(seconds: number): void
+}
+
+/**
+ * A plate of one animal.
+ *
+ * Everything it does not need is left out rather than made and ignored. A crab
+ * and an octopus need a floor, because neither of them is ever off it. Nothing
+ * else here has a bed at all, and a jellyfish in open water is a jellyfish.
+ */
+export function createPlate(kind: Kind, options: PlateOptions): Plate {
+  const box = { height: options.height, width: options.width }
+  const water = { height: box.height * ROOM, width: box.width * ROOM }
+  const seed = options.seed ?? 1
+  const geometry = new Float32Array(BLOCK)
+
+  const grounded = kind === "crab" || kind === "octopus" || kind === "pufferfish"
+  const seabed = grounded ? createSeabed({ ...water, cliffs: 0, ranges: 1, seed, stones: 0 }) : null
+
+  const shoal =
+    kind === "swordfish"
+      ? createShoal({
+          count: 1,
+          cruise: 0.5,
+          height: water.height,
+          seed,
+          species: { swordfish: 1 } as Partial<Record<FishKind, number>>,
+          width: water.width,
+        })
+      : null
+
+  const jellies =
+    kind === "jellyfish"
+      ? createJellies({
+          count: 1,
+          height: water.height,
+          kinds: ["moon"] as readonly JellyKind[],
+          seed,
+          width: water.width,
+        })
+      : null
+
+  const inklings =
+    kind === "octopus" && seabed
+      ? createCephalopods({
+          floor: seabed.floorAt,
+          height: water.height,
+          octopuses: 1,
+          seed,
+          squids: 0,
+          width: water.width,
+        })
+      : null
+
+  let watched = 0
+
+  const looking = (): readonly Presence[] => {
+    const one = puffers?.puffers[0]
+    if (!one || watched % LOOKING.every > LOOKING.near) return []
+    return [
+      {
+        depth: one.depth,
+        menace: LOOKING.menace,
+        size: one.size * LOOKING.size,
+        x: one.x,
+        y: one.y,
+      },
+    ]
+  }
+
+  const puffers: Puffers | null =
+    kind === "pufferfish" && seabed
+      ? createPuffers({
+          about: looking,
+          count: 1,
+          floor: seabed.floorAt,
+          height: water.height,
+          seed,
+          width: water.width,
+        })
+      : null
+
+  const walkers =
+    kind === "crab" && seabed
+      ? createWalkers({
+          crabs: 1,
+          floor: seabed.floorAt,
+          seed,
+          starfish: 0,
+          width: water.width,
+        })
+      : null
+
+  /**
+   * Where the animal is, kept from the last frame it was in.
+   *
+   * A camera that snapped back to the middle of the water whenever the animal
+   * was between two states would be a camera nobody could watch. The last known
+   * place is a better answer than the middle, and it is always nearly right.
+   */
+  let held = { x: water.width / 2, y: water.height / 2 }
+  let across = box.width / 6
+
+  const find = () => {
+    const one =
+      shoal?.fish[0] ??
+      jellies?.jellies[0] ??
+      inklings?.octopuses[0] ??
+      puffers?.puffers[0] ??
+      walkers?.walkers[0]
+    if (!one) return
+
+    held = { x: one.x, y: one.y }
+    if (one.size > 0) across = one.size
+  }
+
+  return {
+    box,
+
+    geometry,
+
+    look() {
+      find()
+      const reach = REACH[kind]
+      const drawn = Math.max(1, across * reach.wide)
+      return {
+        scale: (Math.min(box.height, box.width) * FILLS) / drawn,
+        x: held.x,
+        y: held.y + across * reach.drop,
+      }
+    },
+
+    over(): number {
+      // The same six numbers a sea puts in front of its frame, so one reader
+      // walks either. A plate is not held by anybody: it is a drawing being
+      // looked at, and a drawing that wandered would be a drawing on a boat.
+      geometry[0] = 0
+      geometry[1] = 0
+      geometry[2] = 0
+      geometry[3] = 1
+      geometry[4] = 0
+      geometry[5] = DAYLIGHT
+
+      const pen = new Pen(geometry, HEAD)
+      if (shoal) paintShoal(pen, shoal)
+      // A plate is looked at rather than glanced past, so it is drawn in full
+      // daylight whatever the hour: everything in this water is the theme's own
+      // ink either way, and what the hour changes is a wash over the top, which
+      // on a plate is something to squint through.
+      if (jellies) paintJellies(pen, jellies, DAYLIGHT)
+      if (inklings) paintInklings(pen, inklings)
+      if (puffers) paintPuffers(pen, puffers)
+      if (walkers) paintWalkers(pen, walkers)
+      return pen.close()
+    },
+
+    step(seconds: number): void {
+      shoal?.step(seconds, null, null)
+      jellies?.step(seconds, null)
+      inklings?.step(seconds, null)
+      watched += seconds
+      puffers?.step(seconds)
+      walkers?.step(seconds)
+    },
+
+    wind(seconds: number): void {
+      const step = 1 / 10
+      for (let at = 0; at < Math.round(Math.max(0, seconds) / step); at++) this.step(step)
+    },
+  }
+}

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>`
+  )
+}