@codincod/ornament 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# codin-cod-ornament
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+- [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.
+
+## 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.
+- `src/sizes.ts` and `src/census.ts`: how big things are and how many of them
+  there are.
+
+The package ships its TypeScript source. Import a module by its path:
+
+```ts
+import { createShoal } from "@codincod/ornament/shoal.ts"
+import { createSea } from "@codincod/ornament/paint/sea.ts"
+```
+
+## Commands
+
+```bash
+pnpm install
+pnpm test        # node --test over src/**/*.test.ts
+pnpm check       # tsc, with no DOM
+pnpm fmt         # biome
+```
+
+## Releasing
+
+1. Bump `version`, then `pnpm publish`.
+2. In CodinCod, raise the pin in `assets/package.json`. A caret range on a
+   `0.x` version stops at the next minor, so `^0.1.0` never picks up 0.2.0.
+3. Run `pnpm install` from CodinCod's root, then `mix assets.build`.
+4. In seascape, rebuild the bundle (`js/build.sh`, then `cargo build --release`).
+
+## Licence
+
+[AGPL-3.0](LICENSE), the same as CodinCod.

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@codincod/ornament",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+  "keywords": [
+    "codincod",
+    "generative",
+    "ornament",
+    "simulation"
+  ],
+  "author": "CodinCod <hello@codincod.com>",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@types/node": "^26.6.4",
+    "typescript": "^7.0.2"
+  },
+  "homepage": "https://codincod.com/",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/reeven/codin-cod-ornament"
+  },
+  "scripts": {
+    "check": "tsc --noEmit -p tsconfig.json",
+    "fmt": "biome check --write .",
+    "fmt:check": "biome check .",
+    "test": "node --test \"src/**/*.test.ts\""
+  }
 }

package/src/biome.ts

@@ -0,0 +1,157 @@
+/**
+ * The water everything is in, and the register of what is in it.
+ *
+ * Not a conductor. There is no score, nothing here decides what any animal
+ * does, and no call in this file makes anything happen. What it holds is a fact
+ * every animal in a sea has access to and none of them is told: what else is
+ * about, where, and how alarming it looks from a distance.
+ *
+ * ## Why the water needs a register at all
+ *
+ * Because the alternative is a director, and a director is what a sea does not
+ * have. A shark crossing a reef does not notify the clownfish. It swims, and
+ * the reef empties because every fish on it was watching the water and drew its
+ * own conclusion, at its own moment, at its own distance. That is why nothing
+ * in this ornament exposes a call anybody could fire at it. An animal is handed
+ * `about`, looks, and decides.
+ *
+ * The register is what makes that possible without every animal knowing about
+ * every other one. `nemos.ts`, `flora.ts` and `walkers.ts` each grew their own
+ * copy of one small shape while waiting for this, and all three said the same
+ * thing in their comments: a crab should not be importing a type from a
+ * clownfish. `Presence` is that shape, declared once, and a source of them is
+ * anything at all.
+ *
+ * ## A shark at the glass is not near a fish in the murk
+ *
+ * This water has depth and it is the dimension that gets forgotten,
+ * because a screen has only two. Everything in this ornament carries a `depth`:
+ * 0 is as far off as the water goes and 1 is up against the glass, and that
+ * range is most of the room in the scene. Two things can share a point on the
+ * screen and be a long way from each other.
+ *
+ * So a shark cruising past the camera has no business emptying a reef sitting
+ * back in the murk, however neatly the two line up. `abreast` is the share of
+ * that, and every reading in this ornament is weighed by it.
+ *
+ * ## Size and menace are different questions
+ *
+ * `size` decides how far off something is noticed, because that is what being
+ * seen underwater actually depends on. `menace` decides how much it matters
+ * once it has been. A turtle and a shark of the same length are the same
+ * silhouette at the same distance and they are not the same event, and a sea
+ * where they were is a sea where nothing that happens in it means anything.
+ *
+ * What either number turns into is not settled here. A clownfish quickens at
+ * something big and goes home for something hunting; a crab freezes at both; a
+ * crown of tentacles minds only what is nearly on top of it; a starfish never
+ * reacts to anything, because its answer takes hours and nobody is watching
+ * that long. One reading, many answers, and every one of them the animal's own.
+ *
+ * ## Nothing has to enter
+ *
+ * A water nobody entered is open water, and everything reading it goes about
+ * its day. That is not a degenerate case: it is what most of these scenes are,
+ * and it is why every `about` in this ornament is optional.
+ */
+
+/**
+ * Something in the water, as much of it as another animal can make out.
+ *
+ * Where it is, how big it looks, and whether it looks like it hunts. Not what
+ * it is. Nothing reading this register can tell a shark from a turtle except by
+ * these numbers, which is the right amount for an animal to know: a small fish
+ * on a reef has never been told what species anything is either.
+ */
+export interface Presence {
+  /** 0 is as far off as this water goes, 1 is up against the glass. */
+  readonly depth: number
+  /**
+   * How much this looks like something that hunts, 0 through 1.
+   *
+   * 0 is a shape that has never worried anybody, which is most of what crosses
+   * a sea. 1 empties a reef. Left out it is 0, so anything entering the water
+   * without an opinion about itself is merely large.
+   */
+  readonly menace?: number
+  /** How big it is across, in px, which is how far off it is noticed from. */
+  readonly size: number
+  readonly x: number
+  readonly y: number
+}
+
+/**
+ * Something that says where it is when asked.
+ *
+ * A function rather than a list, because everything in a sea is moving and a
+ * list handed over once is a list of where things were. It returns however many
+ * it speaks for: one animal, a pod of them, or none at all this moment.
+ */
+export type Source = () => readonly Presence[]
+
+export interface Biome {
+  /**
+   * Everything in the water at this moment.
+   *
+   * Gathered afresh on every ask, since nothing here keeps a clock and the
+   * answer is only true for as long as nothing has moved. The list belongs to
+   * the water and is refilled on the next ask, so read it and let it go rather
+   * than keeping it.
+   */
+  about(): readonly Presence[]
+  /**
+   * Put something in the water. What comes back takes it out again.
+   *
+   * Whatever built the animal usually does this, and an animal that does it for
+   * itself is better still, since what a thing looks like to something small is
+   * a fact about that thing. Nothing checks. A sea is not a guest list.
+   */
+  enter(source: Source): () => void
+}
+
+/**
+ * How far apart in the water two distances are before they stop mattering.
+ *
+ * A third of the way through, which is generous and meant to be. The depth of
+ * one of these scenes is not measured in anything, so this cannot be a real
+ * distance; what it has to do is stop the far murk and the near glass being the
+ * same place while leaving anything swimming at roughly your own distance
+ * plainly there. Wider than this and depth does nothing. Narrower and animals
+ * pass through each other unnoticed, which is worse than the fault it fixes.
+ */
+const REACH = 0.36
+
+/**
+ * How nearly abreast two things are, 1 side by side and 0 a water apart.
+ *
+ * The one piece of arithmetic in this file, and it is geometry rather than
+ * judgement: how far apart two things are is the water's own business, and what
+ * either of them does about it is not. It falls off rather than cutting off,
+ * because a threshold makes a shark switch from harmless to terrifying between
+ * two frames of swimming gently forward.
+ */
+export function abreast(depth: number, other: number): number {
+  return Math.max(0, 1 - Math.abs(depth - other) / REACH)
+}
+
+export function createBiome(): Biome {
+  const sources = new Set<Source>()
+  const gathered: Presence[] = []
+
+  return {
+    about() {
+      gathered.length = 0
+      for (const source of sources) {
+        for (const one of source()) gathered.push(one)
+      }
+      return gathered
+    },
+
+    enter(source) {
+      sources.add(source)
+      return () => {
+        sources.delete(source)
+      }
+    },
+  }
+}

package/src/caustics.ts

@@ -0,0 +1,81 @@
+/**
+ * Light off a moving surface, landing on the ground.
+ *
+ * A wave is a lens. The top of the water is never flat, so the light coming
+ * through it is focused into bright lines and starved between them, and what
+ * lands on the sand is a net of them sliding about. It is the one thing that
+ * says a sea is lit from a surface rather than merely lighter towards the top.
+ *
+ * ## Why this is a field and not a net
+ *
+ * A caustic drawn from above is the net everybody has seen. This water is seen
+ * from the side, and a floor seen edge on has no room for a net on it: what
+ * reaches the eye is the light on whatever faces upwards, which here is the
+ * ridges. So this is asked a place and answers how much light is on it, and the
+ * painter walks the ridges it has rather than laying a pattern over the box.
+ *
+ * ## Why the noise is ridged
+ *
+ * Smooth noise is cloud. What separates a caustic from a cloud is that it has
+ * lines in it: the focusing is sharp and the dark between two bright lines is
+ * darker than the average, so the thing to fold is the middle of the range up
+ * into a crease and then steepen it. Plain noise put through a curve stays a
+ * cloud however hard it is squeezed.
+ */
+import { makeNoise2 } from "./perlin.ts"
+
+export interface Caustics {
+  /**
+   * How much light is on the ground at a place, 0 to 1.
+   *
+   * `across` is a share of the box and `depth` is how far forward the ground
+   * there is, so two ridges at the same x and different distances are lit
+   * differently. They have to be: the same pattern on every ridge would flatten
+   * the whole bed into one surface, which is the opposite of the errand.
+   */
+  at(across: number, depth: number): number
+  step(seconds: number): void
+}
+
+export interface CausticsOptions {
+  seed: number
+}
+
+/** How many bright lines fit across the box, and across the water's distance. */
+const CELLS = 7.5
+
+const DEEP_CELLS = 2.4
+
+/**
+ * How fast the whole pattern slides, in widths a second.
+ *
+ * Slow. The surface it comes off is moving quickly, but what a caustic does on
+ * the ground is mostly breathe: the lines wander and swell where they are
+ * rather than travelling, and a pattern crossing the picture at a rate reads as
+ * something being projected onto the sand.
+ */
+const DRIFT = 0.045
+
+/** How narrow the bright lines are, and how sharply they give out. */
+const CREASE = 2.1
+
+const SHARP = 3.2
+
+export function createCaustics(options: CausticsOptions): Caustics {
+  const noise = makeNoise2(options.seed ^ 0x6c1f)
+  let slid = 0
+
+  return {
+    at(across: number, depth: number): number {
+      const held = noise(across * CELLS + slid, depth * DEEP_CELLS)
+      const crease = 1 - Math.abs(held) * CREASE
+      if (crease <= 0) return 0
+
+      return Math.min(1, crease) ** SHARP
+    },
+
+    step(seconds: number): void {
+      slid += seconds * DRIFT
+    },
+  }
+}

package/src/census.ts

@@ -0,0 +1,262 @@
+/**
+ * How much of each animal a sea holds.
+ *
+ * The other half of `sizes.ts`, and it is here for the same fault. That file
+ * was written because every drawing had picked a size that looked right on its
+ * own and a boat had come out the size of a turtle. This one is the same story
+ * told about how many: every renderer picked a density that read well where it
+ * was written, and the water ended up with more crabs on the sand than fish in
+ * the column. A crab at eleven per thousand pixels of bed is defensible where
+ * it stands. A fish at one per sixty thousand square pixels is defensible where
+ * it stands. What lies between them is a sea nobody has ever swum in, and
+ * nothing catches it, because the two numbers are never read side by side.
+ *
+ * So every animal says how many of it a stretch of reef holds, in the unit a
+ * survey would report it in, and this turns that into how many to draw.
+ *
+ * ## Why the numbers are not used as they stand
+ *
+ * A reef carries upwards of a hundred fish over every hundred square metres of
+ * it, and most of them are small ones hanging above the coral. Drawn as
+ * counted, that is a screen of fish with a sea somewhere behind them, and
+ * everything else in the water is lost among them. Thin the whole table until
+ * the fish are countable and the crab, the octopus and the starfish all round
+ * to none, which leaves a bare floor under a busy column.
+ *
+ * The root is the compression that settles it, and it is the same bargain
+ * `sizes.ts` strikes over length. Something commoner is still drawn commoner,
+ * so the order is never wrong; the ends are pulled in far enough that the rare
+ * animal is still in the water somewhere. What is kept is which is commoner,
+ * rather than by how much.
+ *
+ * ## The mix comes out of the same table
+ *
+ * How common a moon jelly is against a comb jelly is the question of how common
+ * a jellyfish is against a fish, asked inside one family. A file that answered
+ * it in its own column would answer it a second way by the end of the year, so
+ * the shares a family draws its next animal from are these numbers normalised.
+ * A family after a count and a family after a mix read one statement.
+ *
+ * ## A day of its own
+ *
+ * `plenty.ts` decides how good a year the whole sea is having. This decides
+ * which animal is having it. Every kind swings from one day to the next on its
+ * own draw, and how far it swings is its own business: blooming is what a
+ * jellyfish does and a grouper does not. So `swings` is a column, and a week of
+ * water is a comb jelly week and then a moon jelly one.
+ *
+ * ## What it does not decide
+ *
+ * Where anything goes, when it turns up, or whether a renderer can afford it.
+ * A shark and a manta are in here for their share against each other and for
+ * nothing else, because what actually puts one in the water is a rest between
+ * crossings (`visitors.ts`); a bed with a thousand plants on it is capped by
+ * whoever has to draw them. This is what the sea holds, and the appetite is
+ * still `plenty.ts`.
+ */
+
+import { stir } from "./perlin.ts"
+import { thriving } from "./plenty.ts"
+
+export type Kind =
+  | "barrel"
+  | "box"
+  | "comb"
+  | "crab"
+  | "crown"
+  | "cruiser"
+  | "darter"
+  | "dolphin"
+  | "drifter"
+  | "eel"
+  | "escort"
+  | "mane"
+  | "manowar"
+  | "manta"
+  | "mermaid"
+  | "moon"
+  | "octopus"
+  | "puffer"
+  | "shark"
+  | "squid"
+  | "starfish"
+  | "stinger"
+  | "swordfish"
+  | "turtle"
+
+interface Held {
+  /**
+   * How many of it live over a hundred square metres of reef.
+   *
+   * The unit a transect is counted in, so a number here can be argued with by
+   * somebody who has swum one. It is what stands in the water at a given
+   * moment rather than what passes through in a season: a shark is scarce here
+   * because a shark is scarce at any one moment, and it is scarce in the
+   * picture for the same reason.
+   */
+  readonly holds: number
+  /**
+   * How hard a day is allowed to swing it, as a power of the day's own draw.
+   *
+   * At 0 a kind is as common today as it was yesterday, which is what holding a
+   * territory looks like from outside. At 1 it rises and falls with the year
+   * `plenty.ts` decided. Past that it blooms: the draw is weighted low, so a
+   * high power leaves most weeks ordinary or thin and now and then fills the
+   * water with one animal, which is the only shape a bloom comes in.
+   */
+  readonly swings: number
+}
+
+/**
+ * What a reef holds, animal by animal.
+ *
+ * Read down the `holds` column rather than across a row: the column is the
+ * whole point of the file, and every number in it was chosen against its
+ * neighbours rather than against how much of the picture the animal deserves.
+ * Where a figure is a range in the wild it is the ordinary end of that range,
+ * since `swings` is what carries the rest.
+ */
+const SEA: Readonly<Record<Kind, Held>> = {
+  /** A dustbin lid of a jelly, in on a season rather than resident. */
+  barrel: { holds: 0.09, swings: 1.8 },
+  /** Small, scarce, and inshore for part of the year. */
+  box: { holds: 0.025, swings: 1.6 },
+  /** Comb jellies outnumber everything else adrift in the water. */
+  comb: { holds: 0.66, swings: 2 },
+  /** Most crabs on a reef are under it. This is the few that are out. */
+  crab: { holds: 3, swings: 0.4 },
+  /** Deep water, and up here only where cold water is. */
+  crown: { holds: 0.03, swings: 1.4 },
+  /** Snapper, surgeon, parrot: the fish a reef reads as at a glance. */
+  cruiser: { holds: 24, swings: 0.35 },
+  /** Damsels and anthias over the coral, which is most of what a reef holds. */
+  darter: { holds: 90, swings: 0.5 },
+  /** They pass along a coast rather than live on one stretch of it. */
+  dolphin: { holds: 0.04, swings: 0.5 },
+  /** A grouper holds a hole and there are only so many holes. */
+  drifter: { holds: 1.1, swings: 0.15 },
+  /** Where there is a bed of them there are hundreds, and where there is not
+   *  there are none. The colony's own arithmetic thins it to what fits. */
+  eel: { holds: 140, swings: 1.2 },
+  /** Butterflyfish, which go about in twos and are never far apart. */
+  escort: { holds: 6, swings: 0.35 },
+  /** A cold water animal, and in warm water a rarity worth the day. */
+  mane: { holds: 0.06, swings: 1.8 },
+  /** It goes where the wind puts it, so it arrives in a fleet or not at all. */
+  manowar: { holds: 0.015, swings: 2.6 },
+  /** Scarcest of the large ones, and tied to the few places they gather. */
+  manta: { holds: 0.012, swings: 0.7 },
+  /** Not an animal and not on a density; `visitors.ts` keeps her calendar. */
+  mermaid: { holds: 0, swings: 0 },
+  /** The jelly anybody can name, and it is common enough to earn that. */
+  moon: { holds: 0.45, swings: 2 },
+  /** One to a den, and a den is a find. */
+  octopus: { holds: 0.5, swings: 0.25 },
+  /** Solitary, territorial, and one to a stretch of reef this size. */
+  puffer: { holds: 0.4, swings: 0.4 },
+  /** A reef shark works a stretch of reef that is larger than this one. */
+  shark: { holds: 0.09, swings: 0.4 },
+  /** Reef squid keep company, so where there is one there are a few. */
+  squid: { holds: 0.6, swings: 0.8 },
+  /** Slow, obvious, and lying in the open, which is why they read as common. */
+  starfish: { holds: 4, swings: 0.5 },
+  /** The sea nettle, in on the season the way the barrel is. */
+  stinger: { holds: 0.18, swings: 1.8 },
+  /** A billfish over a reef is a visitor from the water beyond it. */
+  swordfish: { holds: 0.05, swings: 0.6 },
+  /** They graze a reef and sleep under its ledges, so one is about. */
+  turtle: { holds: 0.12, swings: 0.35 },
+}
+
+/**
+ * How hard the range is pulled in.
+ *
+ * The root `sizes.ts` takes of a length, taken here of a density, and picked
+ * the same way: at this it is the small fish that carry the water and the crab
+ * and the octopus are still in it. Nearer 1 and the darters bury everything
+ * else; nearer 0 and every animal in the sea is about as common as every other,
+ * which is the picture this file exists to prevent.
+ */
+const ROOT = 0.55
+
+/**
+ * How wide a stretch of sea the box is a window on, in metres.
+ *
+ * It follows from `sizes.ts` rather than being chosen here. A fish of a third
+ * of a metre swimming at eight comes out at a fortieth of the box, and a window
+ * that fits forty of those across it is a window on about this much water. It
+ * is worth knowing that the answer is a room and not an ocean: everything in
+ * this scene is close enough to touch, which is why a shark crossing it is an
+ * event.
+ */
+const ACROSS = 13
+
+/**
+ * How many the sea is drawn with, against how many it holds.
+ *
+ * The one number the file is tuned by, and it was fixed by the shoal: the
+ * desktop's water held about forty fish before any of this was written down, so
+ * it holds about forty now, and every other animal moved to meet them.
+ */
+const SCALE = 2.1
+
+/** Square metres of reef in view, which a taller window sees more of. */
+function seaIn(width: number, height: number): number {
+  return ACROSS * ACROSS * (height / Math.max(1, width))
+}
+
+/**
+ * A number of this kind's own, so no two kinds have the same day.
+ *
+ * Off the name rather than off a position in the table, because a position
+ * moves when something is added above it, and a sea that changed everywhere
+ * because a jellyfish was added is a sea nobody can reason about.
+ */
+function own(kind: Kind): number {
+  let run = 0
+  for (let at = 0; at < kind.length; at++) run = stir(run + kind.charCodeAt(at))
+  return run & 0xffff
+}
+
+/**
+ * How common this kind is drawn today: compressed, and then given its day.
+ *
+ * That order is the whole of it. Compressed first and swung afterwards, a bloom
+ * is a bloom; swung first and compressed afterwards, the root takes most of the
+ * day back off it again and a week of water is a week of the same water.
+ */
+function drawnHolds(kind: Kind, seed: number): number {
+  const held = SEA[kind]
+  if (held.holds <= 0) return 0
+  return held.holds ** ROOT * thriving(seed, own(kind)) ** held.swings
+}
+
+/**
+ * How many of these kinds to draw in a box this size, on this day.
+ *
+ * Comes back as it falls out rather than rounded, since a caller with a floor
+ * and a ceiling of its own wants the raw appetite to apply them to.
+ */
+export function manyIn(
+  kinds: readonly Kind[],
+  width: number,
+  height: number,
+  seed: number,
+): number {
+  let sum = 0
+  for (const kind of kinds) sum += drawnHolds(kind, seed)
+  return (SCALE * sum * seaIn(width, height)) / 100
+}
+
+/**
+ * The shares to draw one of these kinds from, on this day.
+ *
+ * Weights against each other rather than chances, which is the shape every
+ * family in this ornament already wanted. They are not normalised, because
+ * nothing that draws from them needs them to be.
+ */
+export function mixOf<K extends Kind>(kinds: readonly K[], seed: number): Record<K, number> {
+  const mix = {} as Record<K, number>
+  for (const kind of kinds) mix[kind] = drawnHolds(kind, seed)
+  return mix
+}