@codincod/ornament 0.0.0-stage → 0.2.0

package/src/shoal.ts

@@ -0,0 +1,1658 @@
+/**
+ * A shoal of fish, wandering, with a reader on the other side of the glass.
+ *
+ * The simulation behind the site's `water.ts`, kept free of the DOM the way `flow_field.ts`
+ * is: what is here is where a fish goes and why, and the canvas half stays a
+ * canvas half.
+ *
+ * The porthole used to draw a shoal as a row of fish sliding across the glass
+ * on one keyframe, which is all a stylesheet can offer and is fine behind a
+ * window the size of a saucer. Across the width of a hero it reads as what it
+ * is, cutouts on a conveyor. So the fish here are steered instead of tweened,
+ * and everything that makes them read as alive comes from that:
+ *
+ *   * A fish eases onto the line it wants and then eases its heading onto that,
+ *     which is two lags in series, so nothing it does has a corner in it.
+ *     Nothing in here ever sets a heading outright.
+ *   * Where it wants to go is its own decision, held for its own stretch of
+ *     seconds and then taken again. See `SWEEP` for why it is not a field.
+ *   * It has a depth. Depth is its own slow field, so a fish wanders off into
+ *     the murk, shrinks, fades, and comes back a minute later without anybody
+ *     having decided that it should.
+ *   * Its tail beats because it is getting somewhere, not the other way round.
+ *     Speed is set in body lengths a second and the beat is whatever covers a
+ *     `STRIDE` at that speed, so a fish that has slowed has slowed its tail
+ *     with it, and the beat that carries it is the beat it is drawn on.
+ *   * It never turns round. See `Fish.facing`, which is the one rule here that
+ *     was arrived at by watching the alternatives fail.
+ *   * It knows whether the pointer is moving. Hold still and one veers over for
+ *     a look on its way past; move, and the ones near you bolt and dive.
+ *   * It may be one of several kinds of animal, which is `SPECIES`.
+ *
+ * Depth is the piece worth arguing for. Fish drawn on one plane are wallpaper
+ * whatever they do, because the eye reads a flat scatter as a pattern; give
+ * them a near and a far and the same handful of fish become water with a volume
+ * to it. It also earns the site's own rule about ornament twice over: a fish in
+ * the distance is fainter, so the copy on top of it is safer, and the reader who
+ * notices anything notices something moving away rather than a decoration
+ * asking to be looked at.
+ *
+ * Everything is seeded, so a shoal handed a seed swims the same way twice. What
+ * the seed itself is, a caller decides; see `freshSeed`.
+ */
+
+import { abreast, type Presence } from "./biome.ts"
+import { mixOf } from "./census.ts"
+import { makeNoise2, makeRandom, type Noise2, stir } from "./perlin.ts"
+import { drawnAt, SWIMMING_OFF } from "./sizes.ts"
+
+export type Kind = "cruiser" | "darter" | "drifter" | "escort" | "swordfish"
+
+/**
+ * What sort of animal a fish is.
+ *
+ * Every field is a multiplier on a number the shoal already had, which is the
+ * whole design of this: there is one set of rules for swimming and the species
+ * only argue about the constants. A kind that needed its own branch in `step`
+ * would be a second simulation wearing the first one's interface, and the two
+ * would drift apart the first time either was tuned.
+ *
+ * What separates them, in order of how much it shows:
+ *
+ *   * `hold`, how long one keeps a line. A drifter picks a heading and stays on
+ *     it for the best part of a minute; a darter changes its mind every second.
+ *     This is the single most legible difference between two animals, more than
+ *     size and much more than speed, because it is the only one you can read
+ *     from a path rather than from a frame.
+ *   * `verve`, whether it bursts and coasts instead of cruising. Small fish do
+ *     not swim, they go and then stop, and a small fish moving at a steady rate
+ *     reads as a large fish far away.
+ *   * `long`, how big it really is, which `sizes.ts` turns into how big it is
+ *     drawn and which carries depth with it, because size and distance are the
+ *     same statement here.
+ *   * `deep`, where in the column it prefers to be. Something long and slow
+ *     belongs in the murk at the back, and putting it there means it never has
+ *     to compete with the shoal for attention.
+ *   * `stride`, how far it goes per beat of its tail. A big slow animal takes
+ *     one long stroke where a small one takes six.
+ */
+export interface Species {
+  /**
+   * Whether it carries a bill, and how long against the drawing's own.
+   *
+   * A drawing fact in a table of swimming facts, and it earns its place: the
+   * only thing that knows a swordfish from a cruiser is this table, and a
+   * renderer asking `SPECIES[fish.kind].bill` needs to know nothing else. The
+   * alternative is every renderer carrying its own list of which names have
+   * bills, which is the same fact written down twice.
+   */
+  readonly bill: number
+  /** Where in the depth field it sits, as `DEPTH_MID` is for a cruiser. */
+  readonly deep: number
+  /** How long it holds a line, against `HOLD_LEAST` and `HOLD_SPAN`. */
+  readonly hold: number
+  /**
+   * Nose to tail in metres, which is what it is rather than how it is drawn.
+   *
+   * The drawing follows from `sizes.ts`. The range the box was given is what a
+   * cruiser gets, and every other kind is the root of how much longer it really
+   * is, so a billfish comes out over a grouper because a billfish is longer and
+   * not because a number here was tuned until it looked right. A reader who
+   * doubts one can look the animal up.
+   */
+  readonly long: number
+  /**
+   * How much it picks up its pace with something hunting about, against
+   * `WARY`. 0 is a fish that carries on regardless.
+   *
+   * A kind's own, and one of them is nothing on purpose. Everything in a sea
+   * reacting to the same shape is a sea with one animal in it wearing several
+   * outlines, and what a reef or an open water actually looks like when a shark
+   * goes through is most things quickening, some things leaving, and a few
+   * carrying on as though nothing had happened. The last of those is not an
+   * oversight anywhere: it is a big enough animal, or a far enough one, or one
+   * that has seen a hundred sharks and been eaten by none of them.
+   */
+  readonly nerve: number
+  /** Its cruising speed, against the water's own. */
+  readonly pace: number
+  /** How steeply it will swim, against `MAX_PITCH`. */
+  readonly pitch: number
+  /** Body lengths per beat, against `STRIDE`. */
+  readonly stride: number
+  /** How hard it bursts and coasts. 0 is a steady swimmer. */
+  readonly verve: number
+}
+
+/**
+ * The animals this water holds.
+ *
+ * A handful, and no more than that. Every kind added past the point where a
+ * glance can tell them apart is a kind nobody can see, and the cost of it is
+ * paid on every frame; what makes a sea look full is a few animals behaving
+ * differently, not many behaving similarly.
+ *
+ * The test for whether one has earned its place is whether it changes the
+ * silhouette or changes the path. A swordfish changes the silhouette. A darter
+ * changes the path. Another cruiser with a different fin would change neither.
+ */
+export const SPECIES: Readonly<Record<Kind, Species>> = {
+  /** The one that was here first. Everything else is described against it. */
+  cruiser: {
+    bill: 0,
+    deep: 0.52,
+    hold: 1,
+    long: 0.3,
+    nerve: 1,
+    pace: 1,
+    pitch: 1,
+    stride: 1,
+    verve: 0,
+  },
+  /** Small, quick, and never going anywhere for long. */
+  darter: {
+    bill: 0,
+    deep: 0.58,
+    hold: 0.3,
+    long: 0.09,
+    nerve: 1.7,
+    pace: 1.5,
+    pitch: 1.4,
+    stride: 0.58,
+    verve: 1,
+  },
+  /**
+   * Long, slow and far back, crossing the murk on one heading.
+   *
+   * The one that does nothing about anything. It is already the largest thing
+   * in this water and it is already at the back of it, and an animal that size
+   * has no business hurrying out of the way of a shape, so a shark goes through
+   * and the drifter carries on exactly as it was. It is the most useful animal
+   * in the shoal for that: without it every crossing makes the whole picture
+   * flinch at once, which is a picture of one animal rather than of a sea.
+   */
+  drifter: {
+    bill: 0,
+    deep: 0.2,
+    hold: 4.5,
+    long: 1.4,
+    nerve: 0,
+    pace: 0.6,
+    pitch: 0.45,
+    stride: 1.7,
+    verve: 0,
+  },
+  /** Comes in twos and holds station with the other. See `Fish.mate`. */
+  escort: {
+    bill: 0,
+    deep: 0.62,
+    hold: 1.4,
+    long: 0.18,
+    nerve: 1.25,
+    pace: 1.1,
+    pitch: 0.9,
+    stride: 0.85,
+    verve: 0,
+  },
+  /**
+   * Big, quick, near the front of the water, and holding one line for a long
+   * time. The bill is most of it, but the rest has to agree with the bill: an
+   * animal built like that and pottering about would read as a drawing error.
+   *
+   * A long stride with real bursts in it, which is what a thunniform swimmer
+   * does. It hardly bends: everything happens at the tail, so the pitch is held
+   * shallow and the body reads as a rigid thing being driven.
+   */
+  swordfish: {
+    bill: 1,
+    deep: 0.72,
+    hold: 3.2,
+    long: 2.6,
+    nerve: 0.25,
+    pace: 1.55,
+    pitch: 0.55,
+    stride: 1.5,
+    verve: 0.45,
+  },
+}
+
+/** Every kind there is, which is what a sea holds when nobody says otherwise. */
+export const KINDS: readonly Kind[] = ["cruiser", "darter", "drifter", "escort", "swordfish"]
+
+/**
+ * What a sea is made of, when nobody has an opinion about it.
+ *
+ * The shares every renderer passes as `species`: the porthole, the water behind
+ * a hero, and the desktop background built from this directory. It is one call
+ * rather than three tables because the point of the ornament being one piece of
+ * code is that a fish looks the same wherever somebody meets it, and a mix that
+ * drifts apart per surface undoes that quietly.
+ *
+ * The shares are `census.ts`'s, which is to say they are what a reef holds
+ * rather than what looks well in a window: mostly the small ones over the
+ * coral, a good few of the middling ones a reef reads as, and a billfish that
+ * turns up in a shoal about as often as one turns up over a reef. A porthole
+ * holds a few fish, so most windows never show that last one. Taking the day
+ * with it is the other half: the same water is a darter week and then a week
+ * with something larger in it.
+ */
+export function wild(seed: number): Readonly<Partial<Record<Kind, number>>> {
+  return mixOf(KINDS, seed)
+}
+
+export interface Fish {
+  /** The line it has decided to hold, in radians off level; see `decide`. */
+  aim: number
+  /** 0 is as far off as this water goes, 1 is up against the glass. */
+  depth: number
+  /**
+   * Which way it is pointed, once and for life: 1 for rightward, -1 for left.
+   *
+   * A drawn fish faces one way, so one swimming the other way has to be
+   * mirrored, and mirroring is what wrecks a shoal. Do it the instant a heading
+   * crosses the vertical and the fish turns inside out between two frames. Ease
+   * it, and the body foreshortens through edge-on, which reads as a sheet of
+   * paper turning over in the wind rather than an animal.
+   *
+   * So no fish ever turns round. Each one is born facing a way, keeps a shallow
+   * pitch either side of it (`MAX_PITCH`), and crosses the picture and comes
+   * back on the far side. That is what a shoal drifting past a window is doing
+   * anyway, and it means nothing ever mirrors, foreshortens or flips.
+   */
+  readonly facing: number
+  /** Radians. 0 is swimming right, and it stays inside the fish's own cone. */
+  heading: number
+  /** Seconds left on that decision, after which it takes another. */
+  hold: number
+  readonly kind: Kind
+  /** Its own lane through the depth field, so no two rise together. */
+  readonly lane: number
+  /** What it is actually steering to, easing onto `aim` and never jumping. */
+  lean: number
+  /** Body length in px at depth 1, before depth takes its share. */
+  readonly length: number
+  /**
+   * The one it is holding station with, or null, which is nearly all of them.
+   *
+   * One-way on purpose: the follower watches the leader and the leader does not
+   * know it is being followed. Two fish each steering at the other is a feedback
+   * loop with no damping in it, and what it produces is a slow orbit that gets
+   * tighter until they are one shape. A leader and a shadow is also what a pair
+   * of fish actually looks like.
+   */
+  mate: Fish | null
+  /**
+   * Its own cruising speed, as a share of the shoal's. A shoal where everything
+   * moves at one speed reads as a conveyor however curved the paths are.
+   */
+  readonly pace: number
+  /**
+   * How long it is drawn, in the box's units, with depth already taken out of
+   * it. What a drawer wants, and what a body length means here.
+   */
+  size: number
+  /** px/s across the picture, depth already in it. */
+  speed: number
+  /**
+   * Where it is in its burst, 0 through 1, for a kind with any `verve`.
+   *
+   * A steady swimmer sits at 0 and never moves off it.
+   */
+  spurt: number
+  /** Tail beat, radians. */
+  tail: number
+  /**
+   * How far to rotate the drawing, in radians, after mirroring it by `facing`.
+   *
+   * Not the heading. A drawing that has been mirrored is in a left-handed
+   * frame, and a rotation applied in one of those goes the opposite way on the
+   * screen from the one it goes on paper: a fish heading down and to the left
+   * came out drawn nose-up while it swam nose-down. Every renderer worked that
+   * out for itself and every one of them got it wrong the same way, which is
+   * the argument for the animal knowing its own angle and handing it over.
+   */
+  tilt: number
+  x: number
+  y: number
+}
+
+export interface Pointer {
+  /** Whether it has moved recently. The whole of the interaction turns on this. */
+  moving: boolean
+  x: number
+  y: number
+}
+
+/** Somewhere in the box. Anything a fish measures itself against is one. */
+interface Place {
+  readonly x: number
+  readonly y: number
+}
+
+/**
+ * Something in the water worth getting away from, that is not a reader.
+ *
+ * A hull going over, a ping going through. It is a push out from a point, felt
+ * to `reach` and no further, and the shoal answers it the way it answers a
+ * moving pointer: veer off out at the edge of it, dive and bolt near the middle
+ * of it. What made it is none of a fish's business, which is why this says
+ * nothing about boats; `passers.ts` hands one over and does the deciding.
+ */
+export interface Startle {
+  /**
+   * How far off it is, or nothing if it is felt through the whole column.
+   *
+   * A hull says nothing, and that is right: a boat going over disturbs the
+   * water under it at every distance, so a fish in the murk feels it as much as
+   * one at the glass. Anything that is a shape rather than a disturbance should
+   * say, or it pushes fish it is nowhere near. See `abreast`.
+   */
+  depth?: number
+  /** How hard it is felt at the middle of it, 0 to 1. */
+  force: number
+  /** How far out it is felt at all, in px. */
+  reach: number
+  x: number
+  y: number
+}
+
+/**
+ * How much of a startle reaches something at `depth`, all of it to none.
+ *
+ * A screen has two distances and this water has three, and the third is most of
+ * the room in it. Something that says where it is in the column is felt by what
+ * is swimming alongside it and not by what is a water away, however neatly the
+ * two line up on the glass. Something that says nothing is felt by everybody,
+ * which is what a hull going over actually does.
+ *
+ * Exported beside `Startle` because it is the other half of that declaration
+ * rather than a fish's private business. Anything handed a startle has the same
+ * question to answer, and `cephalopods.ts` grew its own copy of the answer
+ * before this one was here to take.
+ */
+export function felt(depth: number, startle: Startle): number {
+  return startle.depth == null ? 1 : abreast(depth, startle.depth)
+}
+
+export interface Shoal {
+  /** The one that has come over to look, if the reader has been still. */
+  readonly attentive: Fish | null
+  readonly fish: readonly Fish[]
+  /**
+   * How many should be about, which is not how many are.
+   *
+   * A number to work towards rather than a number to become. The water's one
+   * promise is that nothing appears out of nothing and nothing vanishes in
+   * front of you, and a shoal that resized itself would break both: a fish
+   * would blink into the middle of the picture and another would blink out of
+   * it. So a shoal over its number is one that stops replacing what leaves, and
+   * a shoal under it walks one in from the side at a time.
+   *
+   * It is here because a reef at three in the afternoon is not a reef at three
+   * in the morning. Most of what lives on one is out in the day and sheltering
+   * at night, and the difference is most of what tells the two apart from the
+   * shore.
+   */
+  hold(count: number): void
+  /**
+   * Re-fit to a resized box, carrying the fish across in proportion. When
+   * `count` is given and differs, the shoal grows or thins to it, so a window
+   * dragged wide is not left with a phone's pair of fish in it.
+   */
+  resize(width: number, height: number, count?: number): void
+  /**
+   * Advance by `seconds`. `pointer` is in the box's own coordinates, or null,
+   * and so is `startle`: whatever else the water is doing to them this tick.
+   */
+  step(seconds: number, pointer: Pointer | null, startle?: Startle | null): void
+}
+
+export interface ShoalOptions {
+  /**
+   * What else is in this water, asked for once a step.
+   *
+   * The same optional call the rest of the ornament takes. Nothing is fired at
+   * a fish: it looks, and what it makes of what it sees is its kind's own
+   * business. Left out, the water is empty as far as the shoal can tell, which
+   * is the state a page with nothing crossing it is in anyway.
+   */
+  about?: () => readonly Presence[]
+  count: number
+  /**
+   * How fast this water goes, in body lengths a second; `CRUISE` if left out.
+   *
+   * A framing decides this, not a fish. The same length a second is a shoal
+   * ambling across a hero and a shoal commuting across a porthole, because the
+   * porthole holds a fifth of a fish per unit width and the hero holds a
+   * thirtieth: the animal is the same and the crop is not.
+   */
+  cruise?: number
+  height: number
+  /**
+   * Nose to tail, longest and shortest, in whatever units the box is in.
+   *
+   * A cruiser's range, since every other kind is measured off it. Left out, it
+   * is what `sizes.ts` makes of a real fish at the distance the rest of the
+   * ornament swims at, which is the right answer for any window on open water.
+   * A close-up states its own: a porthole is a hand's breadth of glass and a
+   * fish behind it is not eight metres off.
+   */
+  longest?: number
+  seed: number
+  shortest?: number
+  /**
+   * How the shoal is made up, as relative shares by kind. All cruisers if left
+   * out, which is the water the site opened with and the reason this is opt-in:
+   * a porthole the size of a saucer has three fish in it, and three fish of
+   * three species is a specimen case rather than a shoal.
+   *
+   * Shares rather than counts, so the same mix describes a shoal of five and a
+   * shoal of forty, and a caller never has to know how many fish the box holds.
+   */
+  species?: Partial<Record<Kind, number>>
+  width: number
+}
+
+/** A floor, so a sliver of a window never empties the water completely. */
+const MIN_SHOAL = 1
+
+/** How long the water takes to walk one more fish in, in seconds. */
+const FILL_EVERY = 2.5
+
+/**
+ * How many of the wander field's features fit across the box.
+ *
+ * Reach for this one first if the shoal ever needs retuning. A few in the
+ * picture at once means a fish meets a bend now and then instead of every
+ * second, and two fish swimming together are reading nearly the same part of
+ * the field, which is what makes them look like company.
+ *
+ * Counted across the box and not per pixel, which it was, and that was a bug
+ * with a visible symptom. The number was set on a hero a thousand px wide; a
+ * porthole is two hundred units across, so less than one feature spanned the
+ * whole window and every fish in it was handed the same direction at the same
+ * moment. A shoal steering as one body is not a shoal.
+ */
+const FIELD_CELLS = 3.6
+
+/** How fast the field slides under the fish, so no path ever closes on itself. */
+const DRIFT = 0.06
+
+/**
+ * Cruising speed, in its own body lengths a second.
+ *
+ * Body lengths and not pixels, which is the change that made the shoal read as
+ * animals. A rate in pixels is a rate for one size of fish: the same 26px/s was
+ * two thirds of a body a second for the big ones and most of a body a second
+ * for the small, so the big ones laboured and the small ones were the only ones
+ * getting anywhere, and the picture had no perspective in it at all. Measured
+ * in its own lengths, a fish twice the size crosses twice as fast because it is
+ * twice as long, which is what a shoal at two distances looks like.
+ *
+ * Around one length a second is a fish going nowhere in particular. Sustained
+ * swimming runs to about three, and a bolt is ten, so this is the bottom of the
+ * range on purpose: it is scenery.
+ */
+const CRUISE = 1.05
+
+/**
+ * How far a fish travels for each beat of its tail, in body lengths.
+ *
+ * The one number that ties the drawing to the simulation. A fish's stride is
+ * its own, near enough constant whatever speed it is going: it holds the
+ * amplitude and changes the beat, so speed is stride times frequency and the
+ * frequency here is read back off the speed rather than set.
+ *
+ * Between two thirds and four fifths of a body is what steady swimmers get, and
+ * this is the middle of that. With `fish_shape.ts` sweeping a fifth of a body,
+ * it puts every fish here at a Strouhal number of 0.29, inside the 0.2 to 0.4
+ * band that swimming animals converge on. The beat used to be a constant plus a
+ * slice of the speed, which meant a fish drifting at a third of a length a
+ * second still worked its tail most of once a second: effort with nothing to
+ * show for it, and the first thing anybody said about this ornament.
+ */
+export const STRIDE = 0.7
+
+/** What a startled fish multiplies its cruise by, and how long it keeps it. */
+const DART = 3.4
+
+/**
+ * How much faster a fish swims with something hunting nearby, at its worst.
+ *
+ * A quickening and not a bolt. Everything in this water is peaceful and nothing
+ * in it is hunted, and a shoal scattering from a passing shark would make the
+ * page a picture about danger, which it is not. What it is a picture of is
+ * something large going by and the water noticing, and the water noticing looks
+ * like this: the same fish on the same lines, going at them harder.
+ */
+const WARY = 0.9
+
+/**
+ * How far off a hunting thing is minded from, against how big across it is.
+ *
+ * Wide. A shark is noticed a long way before it is a problem, which is the
+ * difference between a shoal that read the water and a shoal that got a fright.
+ */
+const WARY_REACH = 6
+
+/** How fast a fish can turn, radians/s, at ease and startled. */
+const TURN = 0.85
+
+const TURN_STARTLED = 3.4
+
+/** How fast speed follows the speed it wants, per second. */
+const HASTE = 2.2
+
+/**
+ * How steeply a fish may swim, either side of level.
+ *
+ * This is the price of never mirroring one (`Fish.facing`), and it turns out to
+ * be worth paying twice over. A fish held near level reads as a fish; the same
+ * drawing pointed up at fifty degrees reads as a dart, whatever it is doing,
+ * because a real one climbing that steeply would be doing something urgent.
+ */
+const MAX_PITCH = 0.6
+
+/**
+ * How far from the top or the bottom the water starts turning a fish back, as a
+ * share of the height, and how hard it pushes.
+ *
+ * Both are small on purpose. A reach of a third of the height from each side
+ * leaves no middle at all, so every fish is being shoved at all times and the shove is the only
+ * thing steering; what the shoal does then is bounce between two walls. The
+ * water has to be mostly water.
+ *
+ * Only up and down. Sideways there is no wall at all: a fish that has crossed
+ * the picture carries on out of it and comes back on the far side, which is
+ * what lets every one of them keep the way it faces for life. Turning them at a
+ * side would mean turning them round, and turning them round is the thing this
+ * whole ornament will not do.
+ */
+const EDGE_REACH = 0.18
+
+const EDGE_PUSH = 0.9
+
+/**
+ * How steep a line a fish will pick for itself, in radians either way.
+ *
+ * ## What the field was doing wrong
+ *
+ * Steering used to come straight off a noise field: sample it, point there. A
+ * field is smooth and it is one field, so every fish read the same swell at the
+ * same rate and the shoal went up and down together in the same amounts, on the
+ * same period. Drawn out, the paths were W after W, all the same size. Nothing
+ * alive moves like that, and no amount of retuning a single field fixes it,
+ * because the sameness is the field.
+ *
+ * ## What a fish does instead
+ *
+ * It picks a line and holds it for a while, then picks another. So that is what
+ * this is: an aim, drawn per fish; a stretch of seconds to hold it for, also
+ * drawn per fish; and a small wobble off the field on top, so holding a line
+ * still is not holding a ruler. Two fish now differ in where they are going,
+ * how long they will keep going there, and how soon they will think again.
+ *
+ * The draw is biased toward the shallow, because a steep line is a decision and
+ * decisions are rarer than drifting.
+ */
+const SWEEP = 1.1
+
+/** How much of a fish's own line it gives up to come back toward mid-water. */
+const HOMING = 0.34
+
+/** How long a fish holds a line: at least this, plus up to this again. */
+const HOLD_LEAST = 1.6
+
+const HOLD_SPAN = 6.5
+
+/**
+ * How fast a fish eases onto a line it has just picked, per second.
+ *
+ * A decision is a step and a body is not. Without this the target jumped and
+ * the heading chased it at whatever its turn limit was, which is the corner
+ * anybody watching would report: a fish going one way and then, over about two
+ * frames, going another. Easing the target and then easing the heading toward
+ * it is two lags in a row, so a turn now starts slowly, peaks in the middle and
+ * settles, and there is no frame where the angle jumps.
+ */
+const BEND = 0.85
+
+/** How far off its line the water nudges a fish while it is holding one. */
+const WOBBLE = 0.18
+
+/**
+ * How far past the sides a fish swims before it comes back on the other one, as
+ * a multiple of its own body.
+ *
+ * Its own body rather than a number of pixels, because the two things drawing
+ * these are a hero the width of a page and a porthole the size of a saucer. A
+ * margin wide enough to hide a fish leaving the hero is a third of the glass,
+ * and a shoal that spends a third of its life outside a window it never leaves
+ * is a window with nothing in it.
+ *
+ * A shade under one body, because `x` is the tail joint and the nose reaches
+ * about three quarters of a length past it. That is the whole distance needed
+ * to put the animal out of sight, and any more than that is time it spends
+ * being nowhere.
+ */
+const MARGIN = 0.8
+
+/**
+ * How near two escorts have to be, in body lengths, before they fall in
+ * together in open water.
+ *
+ * Near enough that the pair is already a pair to look at, because that is the
+ * whole of what it has to be: an escort steers at its station rather than at
+ * its leader, and a station half a picture away is a chase nobody asked to
+ * watch. Pairs made while the shoal is being built are exempt; see `pair`.
+ */
+const JOIN_REACH = 5
+
+/** How close two fish get before they part, and how firmly. */
+const NEIGHBOUR_REACH = 70
+
+const NEIGHBOUR_PUSH = 0.8
+
+/** How near a moving pointer has to be before a fish gives way, and how hard. */
+const FLEE_REACH = 340
+
+const FLEE_PUSH = 3.6
+
+/**
+ * The share of that reach inside which a fish does not merely veer off but
+ * bolts: dives, and swims flat out.
+ *
+ * Two distances because they are two things. Fish notice a shape moving well
+ * before it is on top of them and start easing away from it, and that is most
+ * of what a reader sees. Panic is the near half of it. Running both off one
+ * radius meant either nothing reacted until the pointer was almost touching, or
+ * the whole shoal bolted from across the surface.
+ */
+const PANIC = 0.62
+
+/**
+ * How long the pointer has to hold still before a fish will come over, in
+ * seconds.
+ *
+ * Long enough that it never fires while somebody is on their way to a button,
+ * short enough that it happens while they are still reading the sentence they
+ * stopped at.
+ */
+const LOOK_DELAY = 1.1
+
+/** How far a fish will come from, and how strongly the rest of them lean over. */
+const LOOK_REACH = 320
+
+const LOOK_PUSH = 2.2
+
+const LEAN_PUSH = 0.5
+
+/**
+ * How long one fish stays interested, and how long the water waits before
+ * sending another, both in seconds.
+ *
+ * Without these a reader who stops moving has a fish parked on their cursor for
+ * as long as they leave it there, which is a pet rather than a wild animal, and
+ * the ornament's whole claim is that it is doing its own thing and you happen to
+ * be watching. So the visit ends, the shoal has a moment, and then somebody else
+ * comes over: the one that has just been is passed over while there is anybody
+ * else in reach, so a long stillness is a procession rather than the same fish
+ * on a loop.
+ */
+const LOOK_SPAN = 13
+
+const LOOK_REST = 5
+
+/**
+ * How close the curious one settles, in px, and what it does then.
+ *
+ * Inside the stand-off it steers along the tangent instead of inward, which
+ * makes it circle rather than dock. A fish that swims into the cursor and stops
+ * dead is a cursor with a sticker on it; one that comes over, turns, and holds
+ * a loop is a fish having a look at you.
+ */
+const STANDOFF = 70
+
+const HOVER = 0.45
+
+/** How far it may be dragged before it gives up and rejoins the water. */
+const LOSE_INTEREST = 1.8
+
+/** How far the depth field swings either side of a kind's own seat, and how
+ *  fast it slides. Where it is seated is the kind's business; see `Species`. */
+const DEPTH_SWING = 0.46
+
+const DEPTH_DRIFT = 0.035
+
+/** The nearest and furthest a fish is ever drawn. */
+const DEPTH_NEAR = 1
+
+const DEPTH_FAR = 0.06
+
+/** How fast depth follows the depth it wants, at ease and startled. */
+const DEPTH_EASE = 0.5
+
+const DEPTH_DIVE = 1.4
+
+/** What a startled fish aims for: away as well as off, so it leaves twice over. */
+const DIVE = 0.35
+
+/** Where a fish that has come to look sits, however deep it was. */
+const RISE = 0.94
+
+/**
+ * How much of a fish's drawn size is depth, and with it how much of its speed.
+ *
+ * One constant for both, because they are one fact. A fish at the back of the
+ * water is smaller and crosses slower in the same proportion, which is all
+ * perspective is; two knobs for it, which is what this had, means a distant
+ * fish can be given a size that says one distance and a speed that says
+ * another, and the eye picks that apart without being able to say why.
+ *
+ * Since speed is set in body lengths, the second half comes for free: a fish
+ * that has shrunk to a third of the way back is holding the same length a
+ * second and so crossing at a third of the pixels.
+ */
+const DEPTH_SIZE = 0.6
+
+/**
+ * How much of a fish's speed comes and goes with its own tail, either side of
+ * the speed it is holding.
+ *
+ * A fish does not travel at a rate. It beats and glides, and the beat is
+ * already here for the body to swing on, so the same phase drives the travel
+ * and the two cannot drift apart. Held small: when the speed varies by more
+ * than a third of its baseline, the glide turns into a stall and the shoal
+ * starts to look like it is being tugged.
+ *
+ * Twice a beat, not once. Thrust comes off the tail whichever way it is
+ * sweeping, so a fish gets a push at each end of the stroke and coasts through
+ * the middle of it. A once-a-beat surge is a fish being pushed from one side.
+ */
+const SURGE = 0.26
+
+/**
+ * How a fish with `verve` bursts: how long one round takes, how much of that is
+ * the push, and how far above and below its cruise the two halves go.
+ *
+ * Burst-and-coast, which is how nearly every small fish actually gets anywhere.
+ * The push is the short half and the coast is the long one, and the coast falls
+ * well under the cruising speed rather than to it, because a fish coasting is
+ * losing speed to the water the whole way: a coast that held its rate would be a
+ * fish under power with its tail still, which is the one thing the eye reads as
+ * wrong without being able to name.
+ */
+const SPURT_SLOWEST = 0.9
+
+const SPURT_FASTEST = 1.9
+
+const SPURT_SHARE = 0.32
+
+const SPURT_PUSH = 2.4
+
+const SPURT_COAST = 0.22
+
+/**
+ * How far behind and to the side a follower sits, in the leader's own body
+ * lengths, and how hard it holds that.
+ *
+ * Behind and off to one side, never alongside. Two fish level with each other
+ * are one wide fish at any distance where this is worth drawing, and the offset
+ * is what keeps two silhouettes readable as two. It also happens to be where a
+ * second fish actually swims, in the water the first one has already moved.
+ */
+const STATION_BACK = 1.3
+
+const STATION_SIDE = 0.55
+
+const STATION_PUSH = 1.6
+
+/**
+ * How hard a follower works the gap, and the speeds it may reach doing it.
+ *
+ * Steering alone will not keep two fish together, and it took watching them
+ * drift apart to see why: every fish is drawn its own cruising speed, so a
+ * follower slower than its leader points at the right spot for as long as you
+ * like and never arrives. A pair has to agree about pace, so a follower gives
+ * up its own and takes the leader's, trimmed by how far off station it is.
+ *
+ * The bounds are what stop that being a tow rope. Uncapped, a follower that
+ * fell a long way back would come up at any speed at all, which reads as the
+ * second fish being fired out of a gun.
+ */
+const STATION_CATCH = 0.55
+
+const STATION_SLOWEST = 0.35
+
+const STATION_BRISKEST = 2.1
+
+/**
+ * The spread of cruising speeds across a shoal, as shares of its own.
+ *
+ * Wide, and drawn toward the bottom of it. Where every fish is within a third
+ * of one speed the eye picks up the shared rate long before it picks up any
+ * individual path, and what it has then is a conveyor with curved rails. What a
+ * shoal actually looks like is most of them going nowhere in particular and one
+ * with somewhere to be, so the draw is squared: about three in ten come out
+ * above the middle of this range and the rest idle below it.
+ */
+const SLOWEST = 0.45
+
+const FASTEST = 1.9
+
+/** How hard that draw leans on the slow end. */
+const LEISURE = 2
+
+/**
+ * What a cruiser is, nose to tail, at its shortest and at its longest.
+ *
+ * In metres, and everything else in `SPECIES` is measured off the shorter of
+ * them. A box that says nothing about size gets these at `SWIMMING_OFF`, which
+ * is how far off the rest of the ornament's animals swim, so a shoal behind a
+ * hero and a shark crossing the same water are the sizes they are against each
+ * other for free.
+ */
+const CRUISER_SHORT = 0.18
+
+const CRUISER_LONG = 0.42
+
+/** The length every other kind is the root of; see `Species.long`. */
+const BASE = SPECIES.cruiser.long
+
+/**
+ * What a cruiser comes to in a box this wide, at its shortest and its longest.
+ *
+ * Out here rather than inside the water because a surface with a reason to
+ * measure the box differently needs the same sum: a strip behind a hero on a
+ * phone is a crop of a sea rather than a smaller one, and what it hands over is
+ * the width it would be a whole window at. Everything else takes the default
+ * and never asks.
+ */
+export function swimming(width: number): { longest: number; shortest: number } {
+  return {
+    longest: drawnAt(CRUISER_LONG, SWIMMING_OFF) * width,
+    shortest: drawnAt(CRUISER_SHORT, SWIMMING_OFF) * width,
+  }
+}
+
+/**
+ * A seed that differs from one visit to the next, mixed with `from` so two
+ * shoals asking in the same millisecond still get different water.
+ *
+ * Nothing else in here reads a clock, and that is the point of keeping this in
+ * one function: a shoal handed a seed is the same shoal every time, which is
+ * what the tests lean on and what makes anything wrong with it findable. All
+ * the clock decides is which of those shoals a visitor gets.
+ *
+ * It is worth deciding it. A fixed seed was the earlier answer, on the argument
+ * that a page should open the same way every time, and that argument holds for
+ * a layout and not for water: somebody who signs in twice a week gets the same
+ * three fish in the same three places, and a background that repeats stops
+ * reading as water and starts reading as a picture of water.
+ */
+export function freshSeed(from = 0): number {
+  return stir(Date.now() ^ from)
+}
+
+/**
+ * A seed that is the same all day and a different one tomorrow.
+ *
+ * For a sea somebody lives with rather than one they visit. A page is opened
+ * and left, so `freshSeed` is right there: new water every time, and nothing is
+ * owed to what was on screen yesterday. A desktop background is the opposite
+ * case. It is the same rectangle behind everything you do for months, and both
+ * of the obvious answers are wrong for it. Fixed, and the floor never changes,
+ * so whatever that one seed happens to hold is all you ever get: the chest with
+ * the laptop on its lid falls to about one sea in ten, and on a machine whose
+ * number missed it, the joke the site is named after is never told at all.
+ * Fresh every boot, and there is no place to come back to; a wreck seen last
+ * week was somewhere else, and a background that is different every time you
+ * look at it is asking to be looked at.
+ *
+ * A day is the unit that answers both. It is long enough that the sea is a
+ * place while you are working in it, and short enough that the rare things come
+ * round: a year gives you the chest about thirty-five times.
+ *
+ * The calendar is read in local time, so the water turns over at midnight where
+ * the reader is rather than at some hour in Greenwich. Two screens on one
+ * machine, and two machines in one house, agree for free.
+ *
+ * It comes back signed rather than as `freshSeed` does, because the renderer
+ * that wants it holds it in a 32-bit signed integer. Nothing downstream can
+ * tell: every seed here is folded through `| 0` on its way into the generator.
+ */
+export function daySeed(now = new Date(), from = 0): number {
+  const day = now.getFullYear() * 10000 + (now.getMonth() + 1) * 100 + now.getDate()
+  return stir(day ^ from) | 0
+}
+
+export function createShoal(options: ShoalOptions): Shoal {
+  const noise = makeNoise2(options.seed)
+  const depths = makeNoise2(options.seed ^ 0x9e37)
+  const random = makeRandom(options.seed ^ 0x5f3d)
+
+  let width = Math.max(1, options.width)
+  let height = Math.max(1, options.height)
+  let drift = 0
+  let sank = 0
+  let still = 0
+  let attentive: Fish | null = null
+  let visit = 0
+  let rest = 0
+  let last: Fish | null = null
+
+  const cruise = options.cruise ?? CRUISE
+  const mix = weigh(options.species)
+  // Read off the width each time rather than once, so a fish walked into a
+  // window that has been dragged wider is the size the window is now. A box
+  // that stated its own range keeps it, since that range is the caller's.
+  const born = (): Fish => {
+    const spread = swimming(width)
+    return spawn(random, draw(mix, random), {
+      cruise,
+      height,
+      longest: options.longest ?? spread.longest,
+      shortest: options.shortest ?? spread.shortest,
+      width,
+    })
+  }
+
+  const fish: Fish[] = Array.from({ length: Math.max(MIN_SHOAL, options.count) }, born)
+  pair(fish)
+
+  /** How many should be about, and how long since one was walked in. */
+  let asked = fish.length
+  let filled = 0
+
+  /**
+   * What leaves is gone, and what arrives has never been here before.
+   *
+   * A fish used to come off one edge and back on the other, which is a shoal of
+   * `count` animals on a belt: watch a hero for a minute and the same swordfish
+   * comes past at the same size, at the same depth, in the same direction, for
+   * ever. Nobody times it and everybody feels it, because the thing an eye is
+   * best at is noticing that it has seen this before.
+   *
+   * So the slot is refilled rather than the animal reused: a fresh kind, size,
+   * depth, pace and heading out of the same seeded stream, entering from the
+   * side its own facing brings it in from. The water keeps its number and
+   * nothing else about it, which is the point: what a picture of a sea has to
+   * be is a picture of a sea that is bigger than the picture.
+   *
+   * The one that has gone is dropped from everything that was holding it. A
+   * follower's leader, the fish that came over for a look, the fish it was: all
+   * of them are references to an animal that is no longer in the water, and a
+   * follower steering at one would swim at a place nothing is.
+   */
+  /** A fresh animal, on the edge its own heading brings it in from. */
+  function entering(): Fish {
+    const made = born()
+    made.x = made.facing > 0 ? -made.size * MARGIN : width + made.size * MARGIN
+    return made
+  }
+
+  /** The one at `at` is gone and nothing takes its place. */
+  function drop(at: number): void {
+    const going = fish[at]
+    if (!going) return
+
+    fish.splice(at, 1)
+    if (attentive === going) attentive = null
+    if (last === going) last = null
+    for (const one of fish) if (one.mate === going) one.mate = null
+  }
+
+  function renew(at: number): void {
+    const going = fish[at]
+    if (!going) return
+
+    // A follower is the one thing that comes back around, and only while the
+    // fish it is following is still in the water and still outside the picture
+    // itself. It fell behind its station and off the edge; putting it back on
+    // that station is where it was going anyway, and a pair that lost half of
+    // itself at the frame's edge would be a pair for as long as it took to
+    // cross the picture once. A station anybody can see is a fish appearing out
+    // of nothing, so that one is replaced like everything else.
+    const lead = going.mate
+    if (lead && fish.includes(lead)) {
+      const x = lead.x - lead.facing * lead.size * STATION_BACK
+      if (gone(x, width, going.size)) {
+        going.x = x
+        going.y = lead.y + lead.size * STATION_SIDE
+        return
+      }
+    }
+
+    fish[at] = entering()
+
+    if (attentive === going) attentive = null
+    if (last === going) last = null
+    for (const one of fish) if (one.mate === going) one.mate = null
+  }
+
+  return {
+    get attentive() {
+      return attentive
+    },
+    fish,
+
+    hold(count) {
+      asked = Math.max(MIN_SHOAL, Math.round(count))
+    },
+
+    resize(nextWidth, nextHeight, count) {
+      const scaleX = Math.max(1, nextWidth) / width
+      const scaleY = Math.max(1, nextHeight) / height
+      width = Math.max(1, nextWidth)
+      height = Math.max(1, nextHeight)
+
+      for (const one of fish) {
+        one.x *= scaleX
+        one.y *= scaleY
+      }
+
+      if (count == null) return
+      asked = Math.max(MIN_SHOAL, Math.round(count))
+      while (fish.length > count && fish.length > MIN_SHOAL) {
+        const going = fish.at(-1)
+        if (going === attentive) attentive = null
+        // A follower whose leader has just been thinned out of the water would
+        // otherwise steer at an animal nobody is drawing.
+        for (const one of fish) if (one.mate === going) one.mate = null
+        fish.pop()
+      }
+      while (fish.length < count) fish.push(born())
+      pair(fish)
+    },
+
+    step(seconds, pointer, startle = null) {
+      const dt = Math.min(Math.max(seconds, 0), 0.1)
+      const water = options.about?.() ?? []
+      drift += DRIFT * dt
+      sank += DEPTH_DRIFT * dt
+
+      still = pointer && !pointer.moving ? still + dt : 0
+      const looking = still > LOOK_DELAY
+      const fleeing = pointer?.moving === true
+
+      if (!looking || !pointer) {
+        attentive = null
+        last = null
+        rest = 0
+        visit = 0
+      } else if (attentive) {
+        visit += dt
+        const strayed =
+          away(attentive, pointer) > LOOK_REACH * LOSE_INTEREST ||
+          (away(attentive, pointer) > STANDOFF && !ahead(attentive, pointer))
+        if (visit > LOOK_SPAN || strayed) {
+          last = attentive
+          attentive = null
+          visit = 0
+          rest = LOOK_REST
+        }
+      } else if (rest > 0) {
+        rest -= dt
+      } else {
+        attentive = nearest(fish, pointer, LOOK_REACH, last)
+      }
+
+      let arrived = false
+
+      for (let at = 0; at < fish.length; at++) {
+        const one = fish[at]
+        if (!one) continue
+        const sort = SPECIES[one.kind]
+
+        one.hold -= dt
+        if (one.hold <= 0) decide(one, random, height, sort)
+        one.lean = ease(one.lean, one.aim, BEND * dt)
+
+        const startled =
+          (fleeing && pointer != null && away(one, pointer) < FLEE_REACH * PANIC) ||
+          (startle != null &&
+            startle.force * felt(one.depth, startle) > 0 &&
+            away(one, startle) < startle.reach * PANIC)
+
+        const [wantX, wantY] = want(
+          one,
+          fish,
+          noise,
+          drift,
+          looking ? pointer : null,
+          fleeing ? pointer : null,
+          startle,
+          one === attentive,
+          width,
+          height,
+        )
+
+        one.heading = toward(
+          one.heading,
+          steady(one.facing, Math.atan2(wantY, wantX), MAX_PITCH * sort.pitch),
+          startled ? AGILITY_BOLT : AGILITY,
+          startled ? TURN_STARTLED : TURN,
+          dt,
+        )
+        one.tilt = drawnTilt(one.heading, one.facing)
+
+        // A follower takes its leader's depth as well as its pace. Two fish on
+        // different planes are two fish, whatever they are doing about each
+        // other: one is nearer and larger and the other is not, and the eye has
+        // read them as unrelated before it reads anything they have in common.
+        const ambient = one.mate
+          ? one.mate.depth
+          : clamp(sort.deep + DEPTH_SWING * depths(one.lane, sank), DEPTH_FAR, DEPTH_NEAR)
+        const wanted = startled ? ambient * DIVE : one === attentive ? RISE : ambient
+        one.depth = ease(one.depth, wanted, (startled ? DEPTH_DIVE : DEPTH_EASE) * dt)
+        one.size = one.length * (1 - DEPTH_SIZE + DEPTH_SIZE * one.depth)
+
+        const hovering = one === attentive && pointer && away(one, pointer) < STANDOFF
+        const gear = burst(one, sort, dt)
+        const own = cruise * one.pace * one.size * gear
+        const quick = 1 + wary(one, water) * sort.nerve * WARY
+        const wants = station(one, own) * quick * (startled ? DART : hovering ? HOVER : 1)
+        one.speed = ease(one.speed, wants, HASTE * dt)
+
+        one.tail += ((2 * Math.PI * one.speed) / (STRIDE * sort.stride * one.size)) * dt
+
+        const stroke = one.speed * (1 + SURGE * Math.cos(2 * one.tail))
+        one.x += Math.cos(one.heading) * stroke * dt
+        one.y = clamp(one.y + Math.sin(one.heading) * stroke * dt, -EDGE_HOLD, height + EDGE_HOLD)
+
+        // A follower whose leader has left is on its own, and a follower that
+        // has itself gone is replaced like anything else. What is gone is not
+        // brought back around: see `renew`.
+        if (gone(one.x, width, one.size)) {
+          // Over its number, this is where the water gives one up: at the edge,
+          // where a fish leaving is the ordinary thing that happens anyway.
+          if (fish.length > asked && fish.length > MIN_SHOAL) drop(at)
+          else renew(at)
+          arrived = true
+        }
+      }
+
+      // And under it, one is walked in from the side, slowly enough that a
+      // shoal filling out over an afternoon is not a shoal arriving.
+      filled += dt
+      if (fish.length < asked && filled >= FILL_EVERY) {
+        filled = 0
+        fish.push(entering())
+        arrived = true
+      }
+
+      // Somebody has left, so somebody may be short of company. Escorts already
+      // swimming within sight of each other fall in; nothing is moved to make
+      // it happen.
+      if (arrived) pair(fish, JOIN_REACH, false)
+    },
+  }
+}
+
+/**
+ * Where a fish would rather be heading, as everything that has an opinion
+ * summed into one vector.
+ *
+ * Summed rather than ranked, so no rule ever needs a special case in the
+ * steering: the edge of the picture, the fish alongside, and the reader are all
+ * just things the water has an opinion about, and the fish reads the total. The
+ * weights are what order them. The reader outranks the frame, which outranks
+ * the neighbours, which outrank the field the fish would otherwise follow.
+ */
+function want(
+  one: Fish,
+  shoal: readonly Fish[],
+  noise: Noise2,
+  drift: number,
+  looking: Pointer | null,
+  fleeing: Pointer | null,
+  startle: Startle | null,
+  attentive: boolean,
+  width: number,
+  height: number,
+): [number, number] {
+  const scale = FIELD_CELLS / width
+  const nx = one.x * scale + drift * 0.3
+  const ny = one.y * scale + drift
+
+  const pitched = one.lean + noise(nx + one.lane, ny + one.lane) * WOBBLE
+  let x = one.facing * Math.cos(pitched)
+  let y = Math.sin(pitched)
+
+  const reach = height * EDGE_REACH
+  y += edge(one.y, reach) - edge(height - one.y, reach)
+
+  if (one.mate) {
+    // The spot behind and beside the leader, rather than the leader itself. A
+    // follower steering at the animal is a follower steering into it, and the
+    // separation rule below then shoves it off again: the two together make a
+    // pair that jostles the whole way across, which is a fight and not company.
+    const spot = {
+      moving: false,
+      x: one.mate.x - one.mate.facing * one.mate.size * STATION_BACK,
+      y: one.mate.y + one.mate.size * STATION_SIDE,
+    }
+    const [awayX, awayY, distance] = separation(one, spot)
+    x -= (awayX / Math.max(distance, 0.5)) * STATION_PUSH
+    y -= (awayY / Math.max(distance, 0.5)) * STATION_PUSH
+  }
+
+  for (const other of shoal) {
+    // A pair is exempt from separation both ways round: they are meant to be
+    // inside each other's reach, and that is the one place the rule is wrong.
+    if (other === one || other === one.mate || other.mate === one) continue
+    const [awayX, awayY, distance] = separation(one, other)
+    if (distance >= NEIGHBOUR_REACH) continue
+
+    const t = 1 - distance / NEIGHBOUR_REACH
+    const push = (t * t * (3 - 2 * t) * NEIGHBOUR_PUSH) / Math.max(distance, 0.5)
+    x += awayX * push
+    y += awayY * push
+  }
+
+  if (fleeing) {
+    const [awayX, awayY, distance] = separation(one, fleeing)
+    if (distance < FLEE_REACH) {
+      const push = (((FLEE_REACH - distance) / FLEE_REACH) * FLEE_PUSH) / Math.max(distance, 0.5)
+      x += awayX * push
+      y += awayY * push
+    }
+  }
+
+  // The same rule as the reader's, on the reach and the strength whatever sent
+  // it says. A hull is a small hard one and a ping is a wide soft one, and
+  // neither of them needs a rule of its own down here.
+  const force = startle ? startle.force * felt(one.depth, startle) : 0
+  if (startle && force > 0) {
+    const [awayX, awayY, distance] = separation(one, startle)
+    if (distance < startle.reach) {
+      const fall = (startle.reach - distance) / startle.reach
+      const push = (fall * FLEE_PUSH * force) / Math.max(distance, 0.5)
+      x += awayX * push
+      y += awayY * push
+    }
+  }
+
+  if (looking) {
+    const [awayX, awayY, distance] = separation(one, looking)
+    const push = attentive ? LOOK_PUSH : distance < LOOK_REACH ? LEAN_PUSH : 0
+
+    if (push > 0) {
+      x -= (awayX / Math.max(distance, 0.5)) * push
+      y -= (awayY / Math.max(distance, 0.5)) * push
+    }
+  }
+
+  return [x, y]
+}
+
+/** The mix as a list to walk, with the shares run into a total. */
+function weigh(shares: Partial<Record<Kind, number>> | undefined): [Kind, number][] {
+  const wanted = shares ?? { cruiser: 1 }
+  const run: [Kind, number][] = []
+  let total = 0
+
+  for (const kind of ["cruiser", "darter", "drifter", "escort", "swordfish"] as const) {
+    const share = Math.max(0, wanted[kind] ?? 0)
+    if (share <= 0) continue
+    total += share
+    run.push([kind, total])
+  }
+
+  if (run.length === 0) return [["cruiser", 1]]
+  return run.map(([kind, upto]) => [kind, upto / total])
+}
+
+/**
+ * One kind off the mix.
+ *
+ * A mix of one is answered without rolling, and that is load-bearing rather
+ * than an optimisation: every fish afterwards is drawn from the same seeded
+ * stream, so spending a number here would shift the whole sequence and hand a
+ * caller that asked for no mix at all a different shoal than it had before.
+ * Water that changed because a feature it does not use was added is water
+ * nobody can reason about.
+ */
+function draw(mix: readonly [Kind, number][], random: () => number): Kind {
+  if (mix.length <= 1) return mix[0]?.[0] ?? "cruiser"
+  const roll = random()
+  return mix.find(([, upto]) => roll < upto)?.[0] ?? mix[mix.length - 1]![0]
+}
+
+/**
+ * Put every unattached escort behind another one.
+ *
+ * Same way round, since a pair swimming into each other is not a pair, and no
+ * chains: a follower is never given a follower of its own, because what that
+ * makes is a queue, and a queue of fish is a train. Any escort left without a
+ * partner keeps `mate` null and swims as an ordinary fish, which is the right
+ * answer for an odd one out and needs no code of its own.
+ *
+ * Pairs are made twice: once when a shoal is built, and again whenever the
+ * water has taken somebody back. That second one matters because a water that
+ * refills itself loses pairs at the frame's edge, and a mechanic that only ever
+ * ran at the start is a mechanic nobody sees after the first minute.
+ *
+ * `reach` is how near two escorts have to be, in the follower's own lengths,
+ * before they fall in together, and `place` is whether the follower is then put
+ * on its station outright. A shoal being built pairs at any distance and places,
+ * because nobody is looking yet. A shoal in the water pairs only animals
+ * already swimming within sight of each other and never moves one: a fish that
+ * jumped onto another's shoulder is worse than a fish swimming alone.
+ */
+function pair(shoal: readonly Fish[], reach = Number.POSITIVE_INFINITY, place = true): void {
+  const spare = shoal.filter((one) => one.kind === "escort" && !one.mate)
+
+  for (const one of spare) {
+    if (one.mate) continue
+    const led = shoal.some((other) => other.mate === one)
+    if (led) continue
+
+    const leader = spare.find(
+      (other) =>
+        other !== one &&
+        !other.mate &&
+        other.facing === one.facing &&
+        // Ahead of it, in its own direction of travel. A leader astern is a
+        // follower that has to hold back for the rest of the crossing, and the
+        // station rule will not let it slow down that far.
+        (other.x - one.x) * one.facing > 0 &&
+        Math.hypot(other.x - one.x, other.y - one.y) < one.size * reach,
+    )
+    if (!leader) continue
+    if (shoal.some((other) => other.mate === leader)) continue
+
+    one.mate = leader
+    if (!place) continue
+    one.x = leader.x - leader.facing * leader.size * STATION_BACK
+    one.y = leader.y + leader.size * STATION_SIDE
+  }
+}
+
+/**
+ * How much of its cruise a fish is asking for this instant.
+ *
+ * One for a steady swimmer, and for one with `verve` a hard push followed by a
+ * long coast. The gear is what the speed eases toward rather than what it is, so
+ * `HASTE` rounds the corners off both ends of the burst and nothing here has to
+ * shape the curve itself.
+ */
+function burst(one: Fish, sort: Species, dt: number): number {
+  if (sort.verve <= 0) return 1
+
+  // Its own rate, off the fraction of its depth lane, which is a number drawn
+  // per fish and never read for anything but its whole part. Taking it from
+  // here rather than rolling the dice each frame is what makes the burst a
+  // rhythm: a fish drawing a fresh rate every step has no period at all, and
+  // what that looks like is an engine misfiring rather than an animal.
+  const rate = SPURT_SLOWEST + (one.lane % 1) * (SPURT_FASTEST - SPURT_SLOWEST)
+
+  one.spurt += dt * rate
+  if (one.spurt >= 1) one.spurt -= 1
+
+  const gear = one.spurt < SPURT_SHARE ? SPURT_PUSH : SPURT_COAST
+  return 1 + (gear - 1) * sort.verve
+}
+
+/**
+ * The speed a fish is asking for, once keeping company has had its say.
+ *
+ * Its own, unless it is following somebody, in which case it is the leader's
+ * trimmed by how far off station it has fallen: behind and it hurries, in front
+ * and it eases off. That trim is the whole of the station-keeping loop, and it
+ * needs nothing to damp it because `HASTE` already stands between this and the
+ * speed a fish actually has.
+ */
+function station(one: Fish, own: number): number {
+  if (!one.mate) return own
+
+  const behind = (one.mate.x - one.x) * one.facing
+  const slip = (behind - one.mate.size * STATION_BACK) / Math.max(one.mate.size, 1)
+
+  return one.mate.speed * clamp(1 + slip * STATION_CATCH, STATION_SLOWEST, STATION_BRISKEST)
+}
+
+/**
+ * Fish are placed from the seeded PRNG rather than from a noise field, for the
+ * reason `flow_field.ts` gives: noise values cluster around zero, so a shoal
+ * placed that way starts in a knot in the middle of an otherwise empty picture.
+ */
+function spawn(
+  random: () => number,
+  kind: Kind,
+  box: Required<Omit<ShoalOptions, "about" | "count" | "seed" | "species">>,
+): Fish {
+  const sort = SPECIES[kind]
+  const facing = random() < 0.5 ? -1 : 1
+
+  const aim = (random() - 0.5) * SWEEP * sort.pitch
+
+  const depth = DEPTH_FAR + random() * (DEPTH_NEAR - DEPTH_FAR)
+  const length =
+    (box.shortest + random() * (box.longest - box.shortest)) * Math.sqrt(sort.long / BASE)
+  const pace = (SLOWEST + random() ** LEISURE * (FASTEST - SLOWEST)) * sort.pace
+  const size = length * (1 - DEPTH_SIZE + DEPTH_SIZE * depth)
+
+  return {
+    aim,
+    depth,
+    facing,
+    heading: steady(facing, aim, MAX_PITCH * sort.pitch),
+    hold: random() * (HOLD_LEAST + HOLD_SPAN) * sort.hold,
+    kind,
+    lane: random() * 200,
+    lean: aim,
+    length,
+    mate: null,
+    pace,
+    size,
+    speed: box.cruise * pace * size,
+    // Only a kind that bursts spends a draw on where in the burst it starts,
+    // for the reason `draw` gives: a shoal that asked for none of this has to
+    // come out of the seeded stream exactly as it did before there was any.
+    spurt: sort.verve > 0 ? random() : 0,
+    tail: random() * Math.PI * 2,
+    tilt: drawnTilt(steady(facing, aim, MAX_PITCH * sort.pitch), facing),
+    x: random() * box.width,
+    y: random() * box.height,
+  }
+}
+
+/**
+ * Which fish comes over, if any is placed to.
+ *
+ * It has to be near enough to bother and it has to have the reader ahead of it,
+ * because no fish here turns round (`Fish.facing`). That is a happier rule than
+ * it sounds: what a reader gets is one that veers out of the shoal, swims over
+ * for a look and carries on past, which is what a fish does. One that stopped
+ * and hovered on the cursor would be a pet.
+ *
+ * `over` is the one that has just had its look, passed over unless nothing else
+ * qualifies, so holding still meets the shoal rather than one fish.
+ */
+function nearest(
+  shoal: readonly Fish[],
+  to: Pointer,
+  reach: number,
+  over: Fish | null,
+): Fish | null {
+  let closest: Fish | null = null
+  let best = reach
+  let spare: Fish | null = null
+
+  for (const one of shoal) {
+    const distance = away(one, to)
+    if (distance >= best || !ahead(one, to)) continue
+    if (one === over) {
+      spare = one
+      continue
+    }
+    best = distance
+    closest = one
+  }
+
+  return closest ?? spare
+}
+
+/** Whether a point is in front of a fish rather than behind it. */
+function ahead(one: Fish, to: Pointer): boolean {
+  return (to.x - one.x) * Math.cos(one.heading) + (to.y - one.y) * Math.sin(one.heading) > 0
+}
+
+const away = (one: Fish, to: Place): number => Math.hypot(one.x - to.x, one.y - to.y)
+
+/** From `to` toward `one`, and how far that is. */
+function separation(one: Fish, to: Place): [number, number, number] {
+  const x = one.x - to.x
+  const y = one.y - to.y
+  return [x, y, Math.hypot(x, y)]
+}
+
+/**
+ * How much of what a fish can see of the water looks like it hunts.
+ *
+ * Its own reading, taken fresh, and it is only ever about menace: something
+ * merely large going over is what `Startle` is for and the shoal already has an
+ * answer to it. This is the other thing, the one a fish keeps half an eye on
+ * while carrying on with its day.
+ */
+function wary(one: Fish, water: readonly Presence[]): number {
+  let worst = 0
+
+  for (const thing of water) {
+    const menace = thing.menace ?? 0
+    if (menace <= 0) continue
+
+    const reach = thing.size * WARY_REACH
+    const distance = Math.hypot(one.x - thing.x, one.y - thing.y)
+    if (distance >= reach) continue
+
+    worst = Math.max(worst, (1 - distance / reach) * menace * abreast(one.depth, thing.depth))
+  }
+
+  return worst
+}
+
+/**
+ * A fish thinks again: where it is going now, and for how long.
+ *
+ * The aim is a signed square of a flat draw, which crowds it toward level: most
+ * of the time a fish carries on much as it was, and now and then it commits to
+ * a climb. `HOMING` is the only thing here that is not chance, and it is what
+ * stops a shoal collecting along the top and the bottom, since a fish high in
+ * the water is likelier to pick a line that brings it down.
+ *
+ * Every draw is its own, so no two fish are on the same clock. That is the
+ * whole point of this over a field.
+ */
+function decide(one: Fish, random: () => number, height: number, sort: Species): void {
+  const roll = random() * 2 - 1
+  const homing = -((one.y / Math.max(height, 1) - 0.5) * 2) * HOMING
+  const most = MAX_PITCH * sort.pitch
+
+  one.aim = clamp(homing + roll * Math.abs(roll) * SWEEP * sort.pitch, -most, most)
+  one.hold = (HOLD_LEAST + random() * HOLD_SPAN) * sort.hold
+}
+
+/**
+ * Turn from one angle toward another, the short way round.
+ *
+ * How fast is how far it has to go, up to `most` radians a second. That word
+ * "up to" is the whole of it. This used to turn at `most` or not at all, which
+ * is a steering wheel with two positions, and it is exactly what a fish here
+ * looked like: dead straight for a second, one snap, dead straight again. The
+ * measured turn rate was zero half the time and the ceiling the rest.
+ *
+ * Proportional means a fish arriving on a heading slows into it, the way
+ * anything with a body in a fluid does. `AGILITY` is how many times a second
+ * what is left of the error is worked off, and the cap only ever bites on the
+ * first frames of a real change of mind.
+ */
+function toward(from: number, to: number, gain: number, most: number, dt: number): number {
+  let by = (to - from) % (Math.PI * 2)
+  if (by > Math.PI) by -= Math.PI * 2
+  if (by < -Math.PI) by += Math.PI * 2
+
+  const rate = Math.max(-most, Math.min(most, by * gain))
+  return from + rate * dt
+}
+
+/**
+ * How much of the heading it has left to make up a fish works off a second,
+ * cruising and frightened.
+ *
+ * The cap alone is not the answer to how quick a fish is. A cruising one is
+ * lazy about a wrong heading and a bolting one is not, and if both work at one
+ * gain then raising the cap for the fright changes nothing, because the gain is
+ * what it was hitting.
+ */
+const AGILITY = 1.5
+
+const AGILITY_BOLT = 4.2
+
+/**
+ * The nearest heading to `want` that a fish facing this way is allowed to hold.
+ *
+ * Everything the water asks for goes through here, so a fish never has a target
+ * behind it and never has one steeper than `MAX_PITCH`. Asked to turn round it
+ * takes the shallowest way it can toward that answer, which is a fish that
+ * cannot oblige rather than a fish that flips.
+ *
+ * Squashed and not clipped. A clip means every steep request lands on the same
+ * two headings, so a fish spends its life pinned to one edge of its cone and
+ * then crosses to the other, which is a windscreen wiper. Squashing leaves the
+ * cone as an asymptote nothing quite reaches and keeps the shallow requests,
+ * which are most of them, almost untouched.
+ */
+/**
+ * A heading as the angle a mirrored drawing has to be turned by.
+ *
+ * Shared with `cephalopods.ts`, because a squid mirrors the same way a fish
+ * does and got the same thing wrong. `asin(sin(h))` is what folds a leftward
+ * heading of `pi - rel` back onto `rel`, and the `facing` is what undoes the
+ * handedness the mirror introduced.
+ *
+ * **This is the whole angle.** Turn the drawing by it and stop; a renderer that
+ * multiplies it by `facing` again lands a leftward animal at `-rel`, nose up
+ * while it swims down, which is the bug this function was written to end and
+ * which it then caused in every renderer at once. The three of them compose
+ * their transforms the same way, canvas, SVG and Qt alike: the drawing is
+ * mirrored first and the turn is applied to the mirrored thing.
+ */
+export function drawnTilt(heading: number, facing: number): number {
+  return Math.asin(clamp(Math.sin(heading), -1, 1)) * facing
+}
+
+function steady(facing: number, want: number, pitch: number): number {
+  const asked = Math.atan2(Math.sin(want), facing * Math.cos(want))
+  const rel = pitch * Math.tanh(asked / pitch)
+  return facing > 0 ? rel : Math.PI - rel
+}
+
+const ease = (from: number, to: number, rate: number): number =>
+  from + (to - from) * Math.min(1, Math.max(0, rate))
+
+/** One edge's inward shove on a fish `distance` px from it. */
+function edge(distance: number, reach: number): number {
+  if (reach <= 0 || distance >= reach) return 0
+  return ((reach - distance) / reach) * EDGE_PUSH
+}
+
+const clamp = (value: number, low: number, high: number): number =>
+  Math.min(Math.max(value, low), high)
+
+/**
+ * Whether a fish has left the picture, by a body's length beyond the frame.
+ *
+ * Every surface this is drawn on hides its overflow, so the margin is the
+ * distance at which the animal is genuinely out of sight rather than merely
+ * near the edge. It is asked both of a fish that is leaving and of one that has
+ * just been let in, which is how `pair` is told which of them is which.
+ */
+function gone(x: number, span: number, body: number): boolean {
+  const margin = body * MARGIN
+  return x > span + margin || x < -margin
+}
+
+/** How far past the top or the bottom a fish is allowed to get. */
+const EDGE_HOLD = 8