signalk-chiplog 2.5.1 → 2.6.0

package/CHANGELOG.md

@@ -6,6 +6,33 @@ All notable changes to Chiplog are documented here. The format follows
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-09-20
+
+### Changed
+
+- **The animation's date range is kept in the address.** Picking a period updates the page's URL, so reloading the page
+  or sharing the link keeps the same dates.
+- **The boat no longer disappears when a passage leaves from where the last one arrived.** There is then no camera move
+  at all: the boat stays in the frame through the short rest and the next passage starts from it. It is still hidden
+  while the camera flies between two different places.
+- **The animation opens and closes on the whole navigation.** It starts on a view of everything that will be sailed,
+  zooms down to the first position in two seconds, and after the last arrival pulls back out to the whole navigation in
+  two seconds, the boat not drawn during either move: it appears where the sailing begins. The rest at the end of each
+  passage is shortened to a beat (0.3 s at ×1), so the boat no longer stands still for a second or more between
+  passages.
+
+### Added
+
+- **A 3D view of the animation.** The Animation page has a new _View_ switch: the same film, at the map's own scale and
+  with north at the top, seen by a camera tilted down onto a 3D sailboat, with the map laid flat under it. The boat
+  follows the general direction of the track rather than every sampled heading, yet turns with it at a tack or a
+  headland, heels and trims its sails to the wind, rides the waves with a pitch and a light roll, and you can frame it
+  closer or wider than the map and choose the boat's size. Load your own boat as a `.glb` file and it is used instead —
+  with its sails trimmed to the wind too, if their nodes are named `Mainsail` and `Jib` (the README has a guide to
+  preparing a model) — kept in that browser. **Export the video** films whichever view is showing (`-3d` in the file
+  name). The 3D view needs WebGL 2 and is loaded only when asked for; without it, the map view is used. It adds three.js
+  to the vendored libraries (about 600 KB, MIT).
+
 ## [2.5.1] - 2026-09-19
 
 ### Fixed
@@ -325,7 +352,8 @@ First release.
 - REST API under `/plugins/signalk-chiplog/api`, documented in [docs/API.md](docs/API.md).
 - Single SQLite database through Node's built-in `node:sqlite`: no native module to build.
 
-[Unreleased]: https://github.com/ricard33/signalk-chiplog/compare/v2.5.1...HEAD
+[Unreleased]: https://github.com/ricard33/signalk-chiplog/compare/v2.6.0...HEAD
+[2.6.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.5.1...v2.6.0
 [2.5.1]: https://github.com/ricard33/signalk-chiplog/compare/v2.5.0...v2.5.1
 [2.5.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.3.1...v2.4.0

package/README.md

@@ -227,13 +227,19 @@ Open **Chiplog** from the Signal K webapps, or `/signalk-chiplog/`. Reading need
   distance and time, the flags of the countries visited, and the top 5 passages by duration, distance, average speed,
   top speed and wind. Countries come from the place names, so they need geocoding enabled and the boat online now and
   then; places named before this existed fill in by themselves.
-- **Animation** — pick a period and every passage in it replays on the map, one after another, the port time skipped.
-  The map follows the boat at a scale chosen for each passage — a short hop kept readable rather than magnified, a long
-  crossing allowed a wider view but never so wide the boat crawls across empty water — while a bubble shows the speed,
-  the distance covered since the start and the date. Play, pause and a slider over the animation's own time, at ×0,5,
-  ×1, ×2 or ×4. **Export MP4** saves it as a video in one of five shapes (Mobile 9:16, Portrait 3:4, Square 1:1,
-  Landscape 4:3, Widescreen 16:9). Everything happens in the browser: nothing is rendered or encoded on the Signal K
-  server, and the map tiles are the only thing downloaded.
+- **Animation** — pick a period (kept in the page's address, so a reload or a shared link keeps it) and every passage in
+  it replays on the map, one after another, the port time skipped. The film opens on the whole navigation and zooms down
+  to the first position in two seconds, and pulls back out to the whole navigation at the end. The map follows the boat
+  at a scale chosen for each passage — a short hop kept readable rather than magnified, a long crossing allowed a wider
+  view but never so wide the boat crawls across empty water — while a bubble shows the speed, the distance covered since
+  the start and the date. Play, pause and a slider over the animation's own time, at ×0,5, ×1, ×2 or ×4. **Export MP4**
+  saves it as a video in one of five shapes (Mobile 9:16, Portrait 3:4, Square 1:1, Landscape 4:3, Widescreen 16:9).
+  Everything happens in the browser: nothing is rendered or encoded on the Signal K server, and the map tiles are the
+  only thing downloaded. **View → 3D** shows the same film, at the map's own scale and with north still at the top, as a
+  camera tilted down onto a 3D sailboat that heels and trims its sails to the wind and rides the waves, with the map
+  laid flat under it; frame it closer or wider than the map and pick the boat's size if you like, and load your own boat
+  as a `.glb` file — sails included — if you would rather see it (see
+  [Your own boat](#your-own-boat-in-the-3d-animation-)). The MP4 export then films the 3D view.
 - **Export** — download the whole logbook or a date range as a PDF logbook to print, JSON, CSV or GPX, and write the
   abandon-ship copy to the USB drive now (admin). The PDF is written in the webapp's language and the device's time
   zone.
@@ -246,6 +252,85 @@ shortcuts beside it; where any date is allowed, the calendar has an _Any date_ b
 
 **Helm entry** in the top bar opens the tablet entry app.
 
+### Your own boat in the 3D animation ⛵
+
+The 3D view draws a generic sailboat. To see yours instead, use **Boat → Use my own boat…** under the animation and pick
+a `.glb` file. The model is kept in **that browser only** (it is never sent to the logbook or the Signal K server), so
+it has to be loaded again on another device; **Use the default boat** puts the generic one back.
+
+**The file**
+
+|               |                                                                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Format        | Binary glTF 2.0 (`.glb`), one self-contained file — textures embedded                                                             |
+| Size          | 30 MB at most (a few MB is plenty: the boat is small on the film)                                                                 |
+| Not supported | Draco, Meshopt or KTX2 compression. Animations, cameras and lights inside the file are ignored — the view lights the scene itself |
+| Materials     | Ordinary glTF materials. Make the sails **double-sided**, or one face vanishes as they swing                                      |
+
+**Orientation, size and waterline**
+
+- **Y is up and the bow points towards +Z** — the glTF convention. Nothing else says which end is the front, so a boat
+  that sails backwards needs a half turn about the vertical axis before it is exported.
+- **Any unit.** The model is scaled so that its longest horizontal extent — length, or width if that is larger,
+  including a boom or a bowsprit — is one boat length, and centred in plan. A stray helper object far from the boat (a
+  ground plane, a light) enlarges that box and shrinks the boat: delete them before exporting.
+- **The lowest point of the model is taken as the bottom of the keel** and placed a twentieth of the boat's length under
+  the waterline, everything else above. The sea is drawn behind the boat and never cuts into it, so the hull is always
+  whole.
+- **The whole boat turns, heels, pitches and rides the waves** with no work on your part. Its size on screen is set by
+  the _Boat size_ buttons, not by the model.
+
+**Sails that move to the wind**
+
+Name the sail nodes and the view trims them like the default boat's: let out as the wind comes aft, and on the side away
+from it.
+
+| Sail     | Names recognised                                                    | Origin of the node                   | Turns by            |
+| -------- | ------------------------------------------------------------------- | ------------------------------------ | ------------------- |
+| Mainsail | `Mainsail`, `Main`, `Sail_Main`, `GrandVoile`, `GV`                 | On the mast, at the foot of the sail | The full sail angle |
+| Headsail | `Jib`, `Genoa`, `Headsail`, `Foresail`, `Sail_Jib`, `Foc`, `Génois` | On the forestay, at the tack         | 0.8 of it           |
+
+Case, spaces, punctuation and the number a modelling tool adds to a copy (`Mainsail.001`) do not matter.
+
+- **The sail is rotated about the vertical axis through the origin of its node.** Put that origin where the sail should
+  pivot — the mast, or the bow fitting for a jib — not at the middle of the cloth, or it will swing sideways.
+- **Model it at rest on the centreline**, the boom pointing aft (−Z). The view adds the trim angle to whatever rotation
+  the node already has.
+- **The angle** is about half the apparent wind angle, at least 4° and at most 88°, smoothed like the boat's heading.
+  The wind on the starboard side puts the sail to port, and the other way round. Where the track has no wind reading the
+  sails stay on the centreline.
+- **Put the boom, the sail and its fittings inside the sail node** so they turn together. Only the outermost node with a
+  recognised name is turned; anything nested in it goes along.
+- **The cloth is rigid.** It does not billow, and a camber does not swap sides with the tack: model it flat or
+  symmetrical.
+- **Nothing else is animated** — no flag, rudder or propeller.
+
+**From Blender**
+
+1. Model the boat with its bow towards **−Y** and Z up — Blender's own front — so it comes out towards +Z with Y up.
+2. Name the sail objects `Mainsail` and `Jib`.
+3. For each sail, put the 3D cursor on the mast foot (or the tack) and use **Object ▸ Set Origin ▸ Origin to 3D
+   Cursor**. Apply rotation and scale (**Ctrl+A**).
+4. Set the sail material to double-sided (**Backface Culling** off).
+5. **File ▸ Export ▸ glTF 2.0**, format **glTF Binary (.glb)**, **+Y Up** ticked, compression off; lights and cameras
+   need not be included.
+6. Load the file in the animation. The line under the boat says which sails were found — _Sails trimmed to the wind:
+   mainsail, jib_ — or _No sail recognised_ if a name is off.
+
+**When something is wrong**
+
+| What you see                     | Why, and what to do                                                                                           |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| The boat sails backwards         | The bow points towards −Z. Turn the model 180° about the vertical axis and export again                       |
+| The boat lies on its side        | Exported with Z up. Export with **+Y Up**                                                                     |
+| The boat is tiny                 | Something far from it is in the file — a ground plane, a light. Remove it                                     |
+| _No sail recognised_             | The nodes are not named as in the table, or a wrapper node above them has a sail name and hides them          |
+| The sails do not move            | The track has no wind readings (there is no apparent wind angle), or the sail nodes are called something else |
+| A sail swings about an odd point | Its origin is not on the mast or the tack                                                                     |
+| One face of a sail disappears    | The material is single-sided                                                                                  |
+| _That file could not be read_    | It is not a `.glb`, or it uses Draco, Meshopt or KTX2 compression                                             |
+| The model is gone next time      | The browser's site data was cleared, or it is another browser or device. Load it again                        |
+
 ## The tablet entry app 📱
 
 Open `/signalk-chiplog/entry/` on the tablet, or follow **Helm entry** from the logbook. For an app-like, full-screen
@@ -565,6 +650,9 @@ between attempts; nothing is lost, it just takes longer to resolve.
 - **Offline charts** are not provided; the animation draws the tracks on a blank sea when there is no connection.
 - **The MP4 export needs a browser with WebCodecs** — Chrome, Edge, Safari 17 or Firefox 130 and later. Without it the
   animation still plays on screen, and the export button is simply not offered.
+- **The 3D view needs WebGL 2.** Without it the switch is greyed out and the map view is used. Heel, pitch and sail trim
+  are estimated from the wind — the logbook records none of them — and a boat model you load stays in that browser only,
+  so it has to be loaded again on another device.
 - **A long animation takes a while to export**: every frame waits for its map before it is drawn, so the video is the
   same whatever the connection was doing, but a long range means a lot of tiles. Turning the seamarks off halves them.
 - **One vessel per Signal K server**, and no per-crew-member authorship.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-chiplog",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Nautical logbook for Signal K: automatic entries, handwritten notes",
   "main": "index.js",
   "files": [
@@ -65,6 +65,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "esbuild": "0.28.2",
     "eslint": "^10.10.0",
     "eslint-config-prettier": "^10.1.8",
     "express": "^4.22.2",
@@ -75,6 +76,7 @@
     "lint-staged": "^17.5.1",
     "mediabunny": "1.58.0",
     "preact": "^10.29.8",
-    "prettier": "^3.9.6"
+    "prettier": "^3.9.6",
+    "three": "0.186.0"
   }
 }

package/public/app.css

@@ -1171,6 +1171,56 @@ button.preset-on {
   color: var(--accent-contrast);
 }
 
+.animation-modes {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.6rem 1.2rem;
+  margin-bottom: 0.75rem;
+}
+
+.animation-modes-group {
+  display: flex;
+  align-items: center;
+  gap: 0.3rem;
+}
+
+.animation-modes-label {
+  color: var(--muted);
+  margin-right: 0.2rem;
+}
+
+.animation-mode {
+  padding: 0.35rem 0.6rem;
+  background: none;
+  color: var(--accent);
+}
+
+.animation-mode[aria-pressed='true'] {
+  background: var(--accent);
+  color: var(--accent-contrast);
+}
+
+.animation-mode:disabled {
+  opacity: 0.5;
+}
+
+.animation-boat {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem 0.8rem;
+  margin-top: 0.75rem;
+}
+
+.animation-boat-file {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  opacity: 0;
+  overflow: hidden;
+}
+
 .animation-facts {
   grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
   margin: 0.75rem 0 0;

package/public/js/animation/boat-model.mjs

@@ -0,0 +1,370 @@
+// The boat of the 3D view: a sailboat built in code, or the crew's own model.
+//
+// Both are one unit long, bow towards +z, y up, with the waterline at y = 0, so
+// the renderer scales either to whatever the camera needs. Nothing is a file:
+// the default boat is generated, so there is no asset to ship or to credit.
+
+import * as THREE from '../../vendor/three.min.mjs';
+import { findSails, SAIL_ROLES } from './boat-parts.mjs';
+
+const HULL_STATIONS = [
+  // u: along the hull from the stern; half beam; deck height above the water.
+  { u: 0, beam: 0.108, deck: 0.078 },
+  { u: 0.12, beam: 0.136, deck: 0.072 },
+  { u: 0.3, beam: 0.152, deck: 0.068 },
+  { u: 0.5, beam: 0.153, deck: 0.07 },
+  { u: 0.68, beam: 0.132, deck: 0.078 },
+  { u: 0.84, beam: 0.084, deck: 0.09 },
+  { u: 0.95, beam: 0.032, deck: 0.102 },
+  { u: 1, beam: 0.002, deck: 0.108 }
+];
+
+// One half of a cross-section, from the deck edge down to the keel, as fractions
+// of the half beam and of the draught.
+const SECTION = [
+  { x: 1, y: 'deck' },
+  { x: 0.99, y: 0.25 },
+  { x: 0.93, y: 0 },
+  { x: 0.78, y: -0.42 },
+  { x: 0.52, y: -0.78 },
+  { x: 0.2, y: -0.97 }
+];
+const DRAUGHT = 0.05;
+
+const HULL_LENGTH = 1;
+const COLOURS = {
+  topsides: new THREE.Color('#f4f1ea'),
+  stripe: new THREE.Color('#1d4ed8'),
+  bottom: new THREE.Color('#7a1f1f'),
+  deck: new THREE.Color('#c9a26b'),
+  cabin: new THREE.Color('#f4f1ea'),
+  glass: new THREE.Color('#1b2733'),
+  metal: new THREE.Color('#9aa5b1'),
+  sail: new THREE.Color('#fbfaf5')
+};
+
+function interpolateStation(u, key) {
+  for (let i = 0; i < HULL_STATIONS.length - 1; i += 1) {
+    const a = HULL_STATIONS[i];
+    const b = HULL_STATIONS[i + 1];
+    if (u <= b.u) {
+      const t = (u - a.u) / (b.u - a.u);
+      const eased = t * t * (3 - 2 * t);
+      return a[key] + (b[key] - a[key]) * eased;
+    }
+  }
+  return HULL_STATIONS[HULL_STATIONS.length - 1][key];
+}
+
+function hullColour(y, deck) {
+  if (y < -0.004) {
+    return COLOURS.bottom;
+  }
+  // A blue stripe just under the rail, white above and below it.
+  return y > deck - 0.02 && y < deck - 0.008 ? COLOURS.stripe : COLOURS.topsides;
+}
+
+function buildHull() {
+  const stations = 34;
+  const positions = [];
+  const colours = [];
+  const indices = [];
+  let ringSize = 0;
+
+  for (let s = 0; s <= stations; s += 1) {
+    const u = s / stations;
+    const z = (u - 0.5) * HULL_LENGTH;
+    const beam = interpolateStation(u, 'beam');
+    const deck = interpolateStation(u, 'deck');
+    // Starboard is -x. The ring runs down the starboard side, up the port one,
+    // and closes across the deck.
+    const half = SECTION.map((point) => ({
+      x: point.x * beam,
+      y: point.y === 'deck' ? deck : point.y * (point.y < 0 ? DRAUGHT : deck)
+    }));
+    const ring = [
+      ...half.map((point) => ({ x: -point.x, y: point.y })),
+      ...half
+        .slice()
+        .reverse()
+        .map((point) => ({ x: point.x, y: point.y }))
+    ];
+    ringSize = ring.length;
+    for (const point of ring) {
+      positions.push(point.x, point.y, z);
+      const colour = hullColour(point.y, deck);
+      colours.push(colour.r, colour.g, colour.b);
+    }
+  }
+  for (let s = 0; s < stations; s += 1) {
+    for (let i = 0; i < ringSize; i += 1) {
+      const a = s * ringSize + i;
+      const b = s * ringSize + ((i + 1) % ringSize);
+      const c = (s + 1) * ringSize + i;
+      const d = (s + 1) * ringSize + ((i + 1) % ringSize);
+      indices.push(a, c, b, b, c, d);
+    }
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  geometry.setAttribute('color', new THREE.Float32BufferAttribute(colours, 3));
+  geometry.setIndex(indices);
+  geometry.computeVertexNormals();
+  return geometry;
+}
+
+// The deck follows the sheer of the hull, a hair above it.
+function buildDeck() {
+  const stations = 34;
+  const positions = [];
+  const indices = [];
+  for (let s = 0; s <= stations; s += 1) {
+    const u = s / stations;
+    const z = (u - 0.5) * HULL_LENGTH;
+    const beam = interpolateStation(u, 'beam') * 0.94;
+    const deck = interpolateStation(u, 'deck') + 0.0015;
+    positions.push(-beam, deck, z, beam, deck, z);
+  }
+  for (let s = 0; s < stations; s += 1) {
+    const a = s * 2;
+    indices.push(a, a + 2, a + 1, a + 1, a + 2, a + 3);
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  geometry.setIndex(indices);
+  geometry.computeVertexNormals();
+  return geometry;
+}
+
+function material(colour, options = {}) {
+  return new THREE.MeshStandardMaterial({
+    color: colour,
+    roughness: 0.6,
+    metalness: 0,
+    ...options
+  });
+}
+
+function mesh(geometry, colour, options) {
+  const result = new THREE.Mesh(geometry, material(colour, options));
+  return result;
+}
+
+const MAST_Z = 0.1;
+const DECK_AT_MAST = 0.082;
+const MAST_HEIGHT = 0.62;
+const BOOM_LENGTH = 0.3;
+const FORESTAY_Z = 0.44;
+const FORESTAY_DECK = 0.1;
+
+// A triangle of sail as a small grid, so it can belly. Vertices are in the
+// sail's own plane; `camber` moves the middle out of it, to leeward.
+function sailGeometry(corners, camber, rows = 6) {
+  const [tack, head, clew] = corners;
+  const positions = [];
+  const indices = [];
+  for (let r = 0; r <= rows; r += 1) {
+    for (let c = 0; c <= rows - r; c += 1) {
+      // Barycentric: r along the leech from the clew, c along the foot.
+      const a = r / rows;
+      const b = c / rows;
+      const w = 1 - a - b;
+      const point = [0, 1, 2].map((k) => tack[k] * w + head[k] * a + clew[k] * b);
+      // Fullest in the middle of the cloth, none on its edges.
+      point[0] +=
+        camber * Math.sin(Math.PI * Math.min(1, a * 1.6)) * Math.sin(Math.PI * (b * 0.8 + 0.1));
+      positions.push(...point);
+    }
+  }
+  const at = (r, c) => {
+    let offset = 0;
+    for (let i = 0; i < r; i += 1) {
+      offset += rows - i + 1;
+    }
+    return offset + c;
+  };
+  for (let r = 0; r < rows; r += 1) {
+    for (let c = 0; c < rows - r; c += 1) {
+      indices.push(at(r, c), at(r + 1, c), at(r, c + 1));
+      if (c < rows - r - 1) {
+        indices.push(at(r, c + 1), at(r + 1, c), at(r + 1, c + 1));
+      }
+    }
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  geometry.setIndex(indices);
+  geometry.computeVertexNormals();
+  return geometry;
+}
+
+function sailMaterial() {
+  return new THREE.MeshStandardMaterial({
+    color: COLOURS.sail,
+    roughness: 0.85,
+    side: THREE.DoubleSide
+  });
+}
+
+export function createProceduralBoat() {
+  const root = new THREE.Group();
+
+  const hull = mesh(buildHull(), 0xffffff, {
+    vertexColors: true,
+    roughness: 0.4,
+    side: THREE.DoubleSide
+  });
+  root.add(hull);
+  root.add(mesh(buildDeck(), COLOURS.deck, { roughness: 0.8, side: THREE.DoubleSide }));
+
+  const cabin = mesh(new THREE.BoxGeometry(0.15, 0.045, 0.26), COLOURS.cabin);
+  cabin.position.set(0, DECK_AT_MAST + 0.022, -0.06);
+  root.add(cabin);
+  for (const side of [-1, 1]) {
+    const glass = mesh(new THREE.BoxGeometry(0.004, 0.018, 0.16), COLOURS.glass, {
+      roughness: 0.2
+    });
+    glass.position.set(side * 0.0755, DECK_AT_MAST + 0.028, -0.06);
+    root.add(glass);
+  }
+  const hatch = mesh(new THREE.BoxGeometry(0.1, 0.008, 0.07), COLOURS.glass, { roughness: 0.3 });
+  hatch.position.set(0, DECK_AT_MAST + 0.048, 0.02);
+  root.add(hatch);
+
+  const mast = mesh(new THREE.CylinderGeometry(0.004, 0.005, MAST_HEIGHT, 8), COLOURS.metal, {
+    metalness: 0.6,
+    roughness: 0.4
+  });
+  mast.position.set(0, DECK_AT_MAST + MAST_HEIGHT / 2, MAST_Z);
+  root.add(mast);
+
+  // The mainsail turns about the mast; the boom goes with it.
+  const mainPivot = new THREE.Group();
+  mainPivot.position.set(0, DECK_AT_MAST, MAST_Z);
+  const boom = mesh(new THREE.CylinderGeometry(0.0032, 0.0032, BOOM_LENGTH, 6), COLOURS.metal, {
+    metalness: 0.6
+  });
+  boom.rotation.x = Math.PI / 2;
+  boom.position.set(0, 0.05, -BOOM_LENGTH / 2);
+  mainPivot.add(boom);
+  const mainCamber = 0.03;
+  const mainsail = new THREE.Mesh(
+    sailGeometry(
+      [
+        [0, 0.052, 0],
+        [0, MAST_HEIGHT - 0.01, 0],
+        [0, 0.056, -BOOM_LENGTH + 0.01]
+      ],
+      mainCamber
+    ),
+    sailMaterial()
+  );
+  mainPivot.add(mainsail);
+  root.add(mainPivot);
+
+  // The jib is fixed at the bow and the masthead; only its clew swings, so it
+  // is rebuilt when the angle changes, and the boat's own frame stays put.
+  const jibTack = [0, FORESTAY_DECK + 0.02, FORESTAY_Z - 0.02];
+  const jibHead = [0, DECK_AT_MAST + MAST_HEIGHT - 0.04, MAST_Z + 0.012];
+  const jibClewLength = 0.3;
+  const jib = new THREE.Mesh(new THREE.BufferGeometry(), sailMaterial());
+  root.add(jib);
+  const stay = new THREE.Mesh(
+    new THREE.CylinderGeometry(0.0012, 0.0012, 1, 4),
+    material(COLOURS.metal, { metalness: 0.6 })
+  );
+  const stayFrom = new THREE.Vector3(...jibTack);
+  const stayTo = new THREE.Vector3(...jibHead);
+  stay.position.copy(stayFrom).add(stayTo).multiplyScalar(0.5);
+  stay.scale.y = stayFrom.distanceTo(stayTo);
+  stay.quaternion.setFromUnitVectors(
+    new THREE.Vector3(0, 1, 0),
+    stayTo.clone().sub(stayFrom).normalize()
+  );
+  root.add(stay);
+
+  let lastAngle = null;
+  function trimJib(angle) {
+    if (lastAngle !== null && Math.abs(angle - lastAngle) < 1e-4) {
+      return;
+    }
+    lastAngle = angle;
+    const clew = [
+      -Math.sin(angle) * jibClewLength,
+      FORESTAY_DECK + 0.03,
+      jibTack[2] - Math.cos(angle) * jibClewLength
+    ];
+    jib.geometry.dispose();
+    // Bellying to leeward, the same side as the boom.
+    jib.geometry = sailGeometry([jibTack, jibHead, clew], -Math.sign(angle || 1) * 0.022);
+  }
+  trimJib(0);
+
+  // The pulpit and stanchions would be lost at this size; a rudder and a
+  // little cockpit coaming are not.
+  const coaming = mesh(new THREE.BoxGeometry(0.11, 0.014, 0.1), COLOURS.deck, { roughness: 0.8 });
+  coaming.position.set(0, DECK_AT_MAST + 0.006, -0.36);
+  root.add(coaming);
+
+  function update(pose) {
+    mainPivot.rotation.y = pose.sail;
+    // The cloth bellies to leeward: the side the boom is on.
+    mainsail.scale.x = pose.sail <= 0 ? 1 : -1;
+    trimJib(pose.sail * 0.8);
+  }
+
+  function dispose() {
+    root.traverse((child) => {
+      child.geometry?.dispose();
+      child.material?.dispose();
+    });
+  }
+
+  return { root, update, dispose };
+}
+
+// The crew's model, sized to one unit long, its lowest point just under the
+// waterline and its middle on the origin. Its bow must be towards +z with y up
+// — the glTF convention — because nothing else says which end is the front.
+export function normaliseCustomModel(scene) {
+  const holder = new THREE.Group();
+  holder.add(scene);
+  const box = new THREE.Box3().setFromObject(scene);
+  const size = box.getSize(new THREE.Vector3());
+  const centre = box.getCenter(new THREE.Vector3());
+  const length = Math.max(size.x, size.z, 1e-6);
+  const scale = HULL_LENGTH / length;
+  scene.position.set(-centre.x, -box.min.y, -centre.z);
+  holder.scale.setScalar(scale);
+  // Its keel below the waterline, its topsides above.
+  holder.position.y = -DRAUGHT;
+  const wrapper = new THREE.Group();
+  wrapper.add(holder);
+  return wrapper;
+}
+
+// The sails a crew's model has, by the names of its nodes: what the boat will
+// trim, as `[{ node, role }]`.
+export function customSails(scene) {
+  return findSails(scene);
+}
+
+export function createCustomBoat(template) {
+  const root = template.clone(true);
+  // Each sail turns about the vertical axis through its own origin, from where the
+  // model has it at rest: the crew put the origin on the mast (or the forestay).
+  const sails = customSails(root).map(({ node, role }) => ({
+    node,
+    factor: SAIL_ROLES[role].factor,
+    rest: node.rotation.y
+  }));
+  return {
+    root,
+    update(pose) {
+      for (const { node, factor, rest } of sails) {
+        node.rotation.y = rest + pose.sail * factor;
+      }
+    },
+    dispose() {}
+  };
+}

package/public/js/animation/boat-parts.mjs

@@ -0,0 +1,57 @@
+// Which parts of a crew-supplied boat model are its sails.
+//
+// The default boat sets its own sails from the wind; a model loaded from a .glb
+// can have the same done to it, provided its sails are named so they can be found
+// (README, "Your own boat"). Nothing here touches the 3D library, so plain Node
+// can test it; the boat model does the rotating.
+
+// What each kind of sail does, relative to the wind-driven angle the boat is given
+// (see boat-pose.mjs `sailAngle`): the mainsail follows it, the headsail a little
+// less, as it is sheeted in closer.
+export const SAIL_ROLES = {
+  main: { factor: 1 },
+  jib: { factor: 0.8 }
+};
+
+// Names are compared without case, punctuation or the number a modelling tool adds
+// to a duplicate (Mainsail.001 arrives as Mainsail001), and in English or French.
+const NAMES = {
+  main: ['main', 'mainsail', 'sailmain', 'grandvoile', 'gv'],
+  jib: ['jib', 'genoa', 'headsail', 'foresail', 'sailjib', 'foc', 'genois']
+};
+
+function normalise(name) {
+  return String(name ?? '')
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]/g, '')
+    .replace(/\d+$/, '');
+}
+
+// 'main', 'jib' or null.
+export function sailRole(name) {
+  const key = normalise(name);
+  if (!key) {
+    return null;
+  }
+  return Object.keys(NAMES).find((role) => NAMES[role].includes(key)) ?? null;
+}
+
+// The sails of a model, given its nodes as { name, children }: each sail found,
+// leaving out any node inside another sail (the outermost one is what turns).
+export function findSails(root) {
+  const found = [];
+  const visit = (node) => {
+    const role = sailRole(node.name);
+    if (role) {
+      found.push({ node, role });
+      return;
+    }
+    for (const child of node.children ?? []) {
+      visit(child);
+    }
+  };
+  visit(root);
+  return found;
+}