@woosh/meep-engine 3.20.0 → 3.22.0

package/src/engine/physics/cloth/playground/main.js

@@ -0,0 +1,876 @@
+import { cloth_step } from "../solver/cloth_step.js";
+import { CLOTH_SOLVER_TUNING } from "../solver/cloth_solver_constants.js";
+import { find_non_finite_cloth_state } from "../solver/find_non_finite_cloth_state.js";
+import { build_cloth_playground_scene } from "./cloth_playground_build.js";
+import {
+    colour_wheel,
+    draw_cloth,
+    pick_particle,
+    PlaygroundCamera,
+    project,
+    unproject
+} from "./cloth_playground_draw.js";
+
+/**
+ * # Cloth solver playground
+ *
+ * `npm run dev --workspace @woosh/meep-engine`, then
+ * <http://localhost:5173/src/engine/physics/cloth/playground/index.html>.
+ *
+ * The whole page is a `while (true) { cloth_step(...) }` with a canvas attached.
+ * Nothing is faked and nothing is wrapped: the controls write straight into the
+ * arguments `cloth_step` takes, the readouts are computed from `ClothState`'s
+ * own arrays, and the tripwire is the same `find_non_finite_cloth_state` the
+ * step asserts on.
+ *
+ * It exists because M0's findings are all *behavioural* — a soft row that never
+ * settles, a multiplier that makes a fabric inextensible, an `α·γ` that
+ * detonates at 0.5 — and a table of numbers is a poor way to believe any of
+ * them. The presets reproduce the interesting rows of `MEASUREMENTS.md`
+ * one click at a time.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Display rate the fixed step is driven at. */
+const FIXED_STEP = 1 / 60;
+
+/** §17's target, for the budget bar. */
+const BUDGET_MS = 2;
+
+/** How many recent step timings the readout keeps. */
+const TIMING_WINDOW = 120;
+
+/** How many kinetic-energy samples the sparkline keeps. */
+const ENERGY_WINDOW = 250;
+
+const element = (id) => document.getElementById(id);
+
+const canvas = element('view');
+const context = canvas.getContext('2d');
+
+const energy_canvas = element('energy');
+const energy_context = energy_canvas.getContext('2d');
+
+const camera = new PlaygroundCamera();
+
+/**
+ * Everything the page can change. Shape and material rebuild the cloth; the
+ * rest are read afresh every step, which is what makes dragging a slider while
+ * it runs mean something.
+ */
+const control = {
+    shape: 'sheet',
+    width: 24,
+    height: 24,
+    spacing: 0.025,
+    mass: 0.3,
+    pinned: 'top',
+    flat: false,
+
+    // Hard by default. Real fabric barely extends, and — more to the point —
+    // a *soft* stretch row stiffer than a few times `m/h²` does not dissipate:
+    // it sustains a limit cycle and the step adds energy to it. See the
+    // `soft rows` preset, and `MEASUREMENTS.md` §6.
+    hard: true,
+    stretch: 1e4,
+    bend: 1e-5,
+
+    substeps: 2,
+    iterations: 4,
+    gravity: 9.81,
+
+    alpha: CLOTH_SOLVER_TUNING.alpha,
+    gamma: CLOTH_SOLVER_TUNING.gamma,
+    beta: CLOTH_SOLVER_TUNING.beta,
+    k_min_ratio: CLOTH_SOLVER_TUNING.k_min_ratio,
+    k_max_ratio: CLOTH_SOLVER_TUNING.k_max_ratio,
+
+    view: 'shaded',
+    running: true,
+    wind: false
+};
+
+/** @type {import('./cloth_playground_build.js').ClothPlaygroundScene} */
+let scene = null;
+
+/** @type {Uint32Array|null} colour of every particle, for the colours view. */
+let colour_of_particle = null;
+
+let colour_count = 0;
+
+const timing = [];
+const energy_history = [];
+
+let last_ms = 0;
+
+/** Particle the cursor is holding, or -1. */
+let grabbed = -1;
+
+/** Its inverse mass before the grab, restored on release. */
+let grabbed_mass_inverse = 0;
+
+/** Its eye-space depth at the moment of the grab — the plane it slides in. */
+let grabbed_depth = 0;
+
+let wind_phase = 0;
+
+// ---------------------------------------------------------------- the cloth
+
+function rebuild() {
+    scene = build_cloth_playground_scene({
+        shape: control.shape,
+        width: control.width,
+        height: control.height,
+        spacing: control.spacing,
+        mass: control.mass,
+        stretch_stiffness: control.hard ? Infinity : control.stretch,
+        bend_modulus: control.bend,
+        pinned: control.pinned,
+        flat: control.flat
+    });
+
+    // `ClothState` bakes the colouring into a permuted order and does not keep
+    // the per-particle colour, because the step has no use for it — the colour
+    // ranges are the whole of what it needs. Recover it from those ranges for
+    // the sake of looking at it.
+    colour_count = scene.state.colour_count;
+    colour_of_particle = new Uint32Array(scene.state.particle_count);
+
+    for (let colour = 0; colour < colour_count; colour++) {
+        const end = scene.state.colour_offset[colour + 1];
+
+        for (let particle = scene.state.colour_offset[colour]; particle < end; particle++) {
+            colour_of_particle[particle] = colour;
+        }
+    }
+
+    grabbed = -1;
+
+    timing.length = 0;
+    energy_history.length = 0;
+
+    frame_camera();
+    refresh_legend();
+}
+
+/**
+ * Put the camera where the whole cloth is on screen, without moving the angle
+ * the viewer has chosen.
+ */
+function frame_camera() {
+    const position = scene.state.position;
+
+    let min_x = Infinity, min_y = Infinity, min_z = Infinity;
+    let max_x = -Infinity, max_y = -Infinity, max_z = -Infinity;
+
+    for (let i = 0; i < scene.state.particle_count; i++) {
+        min_x = Math.min(min_x, position[i * 3]);
+        max_x = Math.max(max_x, position[i * 3]);
+        min_y = Math.min(min_y, position[i * 3 + 1]);
+        max_y = Math.max(max_y, position[i * 3 + 1]);
+        min_z = Math.min(min_z, position[i * 3 + 2]);
+        max_z = Math.max(max_z, position[i * 3 + 2]);
+    }
+
+    camera.target[0] = (min_x + max_x) * 0.5;
+    camera.target[1] = (min_y + max_y) * 0.5;
+    camera.target[2] = (min_z + max_z) * 0.5;
+
+    const extent = Math.max(max_x - min_x, max_y - min_y, max_z - min_z, 0.05);
+
+    camera.distance = extent * 2.1;
+}
+
+// ---------------------------------------------------------------- the loop
+
+function step_once() {
+    const tuning = {
+        alpha: control.alpha,
+        beta: control.beta,
+        gamma: control.gamma,
+        k_min_ratio: control.k_min_ratio,
+        k_max_ratio: control.k_max_ratio
+    };
+
+    let wind_x = 0;
+    let wind_z = 0;
+
+    if (control.wind) {
+        wind_phase += FIXED_STEP;
+
+        // Not §10's fluid coupling — that is M6. Just a gusting push, so there
+        // is something to watch a hem do.
+        const gust = 6 + 5 * Math.sin(wind_phase * 1.7) + 3 * Math.sin(wind_phase * 4.3);
+
+        wind_x = gust * 0.4;
+        wind_z = gust;
+    }
+
+    const started = performance.now();
+
+    try {
+        cloth_step(
+            scene.state,
+            FIXED_STEP,
+            wind_x, -control.gravity, wind_z,
+            control.substeps, control.iterations,
+            tuning
+        );
+    } catch (error) {
+        // The step asserts its own positive-definiteness and its own
+        // finiteness. If one fires, stop rather than painting over it — that is
+        // the page telling the truth about a tuning the user just chose.
+        control.running = false;
+
+        element('tripwire').textContent = String(error.message).slice(0, 80);
+        element('tripwire').className = 'bad';
+        element('pause').textContent = 'run';
+
+        return;
+    }
+
+    last_ms = performance.now() - started;
+
+    timing.push(last_ms);
+
+    if (timing.length > TIMING_WINDOW) {
+        timing.shift();
+    }
+
+    energy_history.push(kinetic_energy(scene.state));
+
+    if (energy_history.length > ENERGY_WINDOW) {
+        energy_history.shift();
+    }
+}
+
+function frame() {
+    if (control.running) {
+        step_once();
+    }
+
+    if (grabbed >= 0) {
+        // A held particle is pinned, and the solver moves everything around it.
+        // Its own position is written by the pointer handler.
+        scene.state.velocity[grabbed * 3] = 0;
+        scene.state.velocity[grabbed * 3 + 1] = 0;
+        scene.state.velocity[grabbed * 3 + 2] = 0;
+    }
+
+    draw_cloth(context, camera, scene.state, scene.triangle, {
+        view: control.view,
+        colour_of_particle,
+        grabbed
+    });
+
+    refresh_readout();
+
+    requestAnimationFrame(frame);
+}
+
+// ---------------------------------------------------------------- readouts
+
+function kinetic_energy(state) {
+    let energy = 0;
+
+    for (let i = 0; i < state.particle_count; i++) {
+        const inverse_mass = state.mass_inverse[i];
+
+        if (inverse_mass === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        energy += 0.5 / inverse_mass * (
+            state.velocity[p] * state.velocity[p] +
+            state.velocity[p + 1] * state.velocity[p + 1] +
+            state.velocity[p + 2] * state.velocity[p + 2]
+        );
+    }
+
+    return energy;
+}
+
+function stretch_residual(state) {
+    let worst = 0;
+
+    for (let row = 0; row < state.stretch_count; row++) {
+        const a = state.stretch_particle[row * 2] * 3;
+        const b = state.stretch_particle[row * 2 + 1] * 3;
+
+        const length = Math.hypot(
+            state.position[a] - state.position[b],
+            state.position[a + 1] - state.position[b + 1],
+            state.position[a + 2] - state.position[b + 2]
+        );
+
+        const rest = state.stretch_rest[row];
+
+        if (rest > 0) {
+            worst = Math.max(worst, Math.abs(length - rest) / rest);
+        }
+    }
+
+    return worst;
+}
+
+function refresh_readout() {
+    const state = scene.state;
+
+    element('ms').textContent = last_ms.toFixed(3);
+
+    if (timing.length > 0) {
+        const sorted = timing.slice().sort((a, b) => a - b);
+
+        element('ms_min').textContent = `(min ${sorted[0].toFixed(3)})`;
+
+        const bar = element('budget');
+
+        bar.firstElementChild.style.width = `${Math.min(100, sorted[0] / BUDGET_MS * 100)}%`;
+        bar.classList.toggle('over', sorted[0] > BUDGET_MS);
+    }
+
+    element('residual').textContent = (stretch_residual(state) * 100).toFixed(2) + '%';
+
+    const energy = energy_history.length > 0 ? energy_history[energy_history.length - 1] : 0;
+
+    element('kinetic').textContent = energy === 0 ? '0' : energy.toExponential(2) + ' J';
+
+    element('counts').textContent =
+        `${state.particle_count} / ${state.stretch_count}+${state.bend_count}`;
+
+    element('colours').textContent = String(colour_count);
+
+    const offender = find_non_finite_cloth_state(state);
+
+    const tripwire = element('tripwire');
+
+    if (control.running || offender !== "") {
+        tripwire.textContent = offender === "" ? 'ok' : offender.slice(0, 40);
+        tripwire.className = offender === "" ? 'good' : 'bad';
+    }
+
+    draw_energy_sparkline();
+}
+
+/**
+ * Kinetic energy over the last few seconds, on a log scale. It is the single
+ * most informative number on the page: a hard-row cloth walks it off the bottom
+ * and stays there, and a soft-row one flattens out on a limit cycle and never
+ * does (`MEASUREMENTS.md` §6).
+ */
+function draw_energy_sparkline() {
+    const width = energy_canvas.width;
+    const height = energy_canvas.height;
+
+    energy_context.clearRect(0, 0, width, height);
+
+    if (energy_history.length < 2) {
+        return;
+    }
+
+    const floor = -14;
+    const ceiling = 2;
+
+    energy_context.strokeStyle = '#5ad19a';
+    energy_context.lineWidth = 1;
+    energy_context.beginPath();
+
+    for (let i = 0; i < energy_history.length; i++) {
+        const value = energy_history[i];
+
+        const log = value > 0 ? Math.log10(value) : floor;
+
+        const x = i / (ENERGY_WINDOW - 1) * width;
+        const y = height - (Math.max(floor, Math.min(ceiling, log)) - floor) / (ceiling - floor) * height;
+
+        if (i === 0) {
+            energy_context.moveTo(x, y);
+        } else {
+            energy_context.lineTo(x, y);
+        }
+    }
+
+    energy_context.stroke();
+
+    energy_context.fillStyle = '#4a515c';
+    energy_context.fillText('kinetic energy, 1e-14 … 1e2 J', 3, 9);
+}
+
+function refresh_legend() {
+    const legend = element('legend');
+
+    legend.textContent = '';
+
+    if (control.view !== 'colours') {
+        return;
+    }
+
+    const wheel = colour_wheel();
+
+    for (let colour = 0; colour < colour_count; colour++) {
+        const swatch = document.createElement('i');
+
+        swatch.style.background = wheel[colour % wheel.length];
+        swatch.title = `colour ${colour}`;
+
+        legend.appendChild(swatch);
+    }
+}
+
+// ---------------------------------------------------------------- controls
+
+/**
+ * Wire one slider to one field. `map` turns the slider's own units into the
+ * field's — log sliders exist because stiffness ranges over nine decades and a
+ * linear slider would spend 99% of its travel above anything usable.
+ */
+function slider(id, field, { map = (v) => v, unmap = (v) => v, format, rebuilds = false } = {}) {
+    const input = element(id);
+    const output = element(id + '_out');
+
+    input.value = String(unmap(control[field]));
+
+    const show = () => {
+        output.textContent = format(control[field]);
+    };
+
+    input.addEventListener('input', () => {
+        control[field] = map(parseFloat(input.value));
+
+        show();
+
+        if (rebuilds) {
+            rebuild();
+        }
+
+        if (field === 'alpha' || field === 'gamma') {
+            refresh_product();
+        }
+    });
+
+    show();
+
+    return { input, show };
+}
+
+const decimal = (digits) => (v) => v.toFixed(digits);
+const exponent = (v) => v.toExponential(1);
+
+const log_slider = { map: (v) => Math.pow(10, v), unmap: (v) => Math.log10(v) };
+
+const bound = {
+    width: slider('width', 'width', { format: (v) => String(v), map: Math.round, rebuilds: true }),
+    height: slider('height', 'height', { format: (v) => String(v), map: Math.round, rebuilds: true }),
+    spacing: slider('spacing', 'spacing', { format: (v) => (v * 100).toFixed(1) + ' cm', rebuilds: true }),
+    mass: slider('mass', 'mass', { ...log_slider, format: (v) => (v * 1000).toFixed(0) + ' g', rebuilds: true }),
+    stretch: slider('stretch', 'stretch', { ...log_slider, format: exponent, rebuilds: true }),
+    bend: slider('bend', 'bend', { ...log_slider, format: exponent, rebuilds: true }),
+    substeps: slider('substeps', 'substeps', { format: (v) => String(v), map: Math.round }),
+    iterations: slider('iterations', 'iterations', { format: (v) => String(v), map: Math.round }),
+    gravity: slider('gravity', 'gravity', { format: decimal(1) }),
+    alpha: slider('alpha', 'alpha', { format: decimal(2) }),
+    gamma: slider('gamma', 'gamma', { format: decimal(2) }),
+    beta: slider('beta', 'beta', { ...log_slider, format: exponent }),
+    k_min: slider('k_min', 'k_min_ratio', { ...log_slider, format: decimal(2) }),
+    k_max: slider('k_max', 'k_max_ratio', { ...log_slider, format: decimal(2) })
+};
+
+function refresh_product() {
+    const product = control.alpha * control.gamma;
+
+    element('product').value = String(product);
+    element('product_out').textContent = product.toFixed(3) + (product >= 0.5 ? ' ⚠' : '');
+}
+
+function select(id, field, { rebuilds = false } = {}) {
+    const input = element(id);
+
+    input.value = control[field];
+
+    input.addEventListener('change', () => {
+        control[field] = input.value;
+
+        refresh_shape_rows();
+
+        if (rebuilds) {
+            rebuild();
+        }
+    });
+}
+
+function checkbox(id, field, { rebuilds = false } = {}) {
+    const input = element(id);
+
+    input.checked = control[field];
+
+    input.addEventListener('change', () => {
+        control[field] = input.checked;
+
+        if (rebuilds) {
+            rebuild();
+        }
+    });
+}
+
+select('shape', 'shape', { rebuilds: true });
+select('pinned', 'pinned', { rebuilds: true });
+checkbox('flat', 'flat', { rebuilds: true });
+checkbox('hard', 'hard', { rebuilds: true });
+
+/** A chain has no second dimension, no pinning choice and no orientation. */
+function refresh_shape_rows() {
+    const chain = control.shape === 'chain';
+
+    element('height_row').style.display = chain ? 'none' : '';
+    element('pinned_row').style.display = chain ? 'none' : '';
+    element('flat_row').style.display = chain ? 'none' : '';
+    element('width_label').textContent = chain ? 'links' : 'across';
+}
+
+// ---------------------------------------------------------------- buttons
+
+function view_button(id, view) {
+    element(id).addEventListener('click', () => {
+        control.view = view;
+
+        for (const other of ['view_shaded', 'view_wire', 'view_colours']) {
+            element(other).classList.toggle('on', other === id);
+        }
+
+        refresh_legend();
+    });
+}
+
+view_button('view_shaded', 'shaded');
+view_button('view_wire', 'wire');
+view_button('view_colours', 'colours');
+
+element('pause').addEventListener('click', () => {
+    control.running = !control.running;
+
+    element('pause').textContent = control.running ? 'pause' : 'run';
+});
+
+element('single').addEventListener('click', () => {
+    control.running = false;
+
+    element('pause').textContent = 'run';
+
+    step_once();
+});
+
+element('reset').addEventListener('click', () => {
+    control.running = true;
+
+    element('pause').textContent = 'pause';
+
+    rebuild();
+});
+
+element('poke').addEventListener('click', () => {
+    // A random impulse into the velocity, which the next predict step carries
+    // into the inertial target. The fastest way to find out whether a tuning is
+    // stable is to hit it.
+    const state = scene.state;
+
+    for (let i = 0; i < state.particle_count; i++) {
+        if (state.mass_inverse[i] === 0) {
+            continue;
+        }
+
+        for (let axis = 0; axis < 3; axis++) {
+            state.velocity[i * 3 + axis] += (Math.random() * 2 - 1) * 3;
+        }
+    }
+});
+
+element('wind').addEventListener('click', () => {
+    control.wind = !control.wind;
+
+    element('wind').classList.toggle('on', control.wind);
+});
+
+element('defaults').addEventListener('click', () => {
+    control.alpha = CLOTH_SOLVER_TUNING.alpha;
+    control.gamma = CLOTH_SOLVER_TUNING.gamma;
+    control.beta = CLOTH_SOLVER_TUNING.beta;
+    control.k_min_ratio = CLOTH_SOLVER_TUNING.k_min_ratio;
+    control.k_max_ratio = CLOTH_SOLVER_TUNING.k_max_ratio;
+
+    for (const name of ['alpha', 'gamma', 'beta', 'k_min', 'k_max']) {
+        const field = name === 'k_min' ? 'k_min_ratio' : name === 'k_max' ? 'k_max_ratio' : name;
+
+        bound[name].input.value = String(
+            name === 'beta' || name === 'k_min' || name === 'k_max'
+                ? Math.log10(control[field])
+                : control[field]
+        );
+
+        bound[name].show();
+    }
+
+    refresh_product();
+});
+
+// ---------------------------------------------------------------- presets
+
+/**
+ * One click each for the rows of `MEASUREMENTS.md` worth seeing move.
+ */
+const PRESET = [
+    {
+        name: 'cape, hard rows',
+        note: 'settles — watch the sparkline fall off the bottom',
+        control: { shape: 'sheet', width: 24, height: 30, spacing: 0.02, mass: 0.3, pinned: 'top', flat: false, hard: true, bend: 1e-5, substeps: 2, iterations: 4 }
+    },
+    {
+        name: 'cape, soft rows',
+        note: 'a penalty 740× m/h² — the step ADDS energy and it never rests (§6)',
+        control: { shape: 'sheet', width: 24, height: 30, spacing: 0.02, mass: 0.3, pinned: 'top', flat: false, hard: false, stretch: 1e4, bend: 1e-5, substeps: 2, iterations: 4 }
+    },
+    {
+        name: 'cape, soft and slack',
+        note: 'the same row at 1e2 — inside the dissipative band, and it settles',
+        control: { shape: 'sheet', width: 24, height: 30, spacing: 0.02, mass: 0.3, pinned: 'top', flat: false, hard: false, stretch: 1e2, bend: 1e-5, substeps: 2, iterations: 4 }
+    },
+    {
+        name: 'chain, 40 links',
+        note: 'depth is how far a force travels in one sweep',
+        control: { shape: 'chain', width: 40, spacing: 0.02, mass: 0.02, hard: true, substeps: 2, iterations: 4 }
+    },
+    {
+        name: 'flag in the wind',
+        note: 'pinned down one side, wind on',
+        control: { shape: 'sheet', width: 30, height: 20, spacing: 0.02, mass: 0.15, pinned: 'none', flat: false, hard: true, bend: 1e-6, substeps: 2, iterations: 4 },
+        after: (state) => {
+            for (let j = 0; j < 20; j++) {
+                state.mass_inverse[state.source_of_particle.indexOf(j * 30)] = 0;
+            }
+        },
+        wind: true
+    },
+    {
+        name: 'the §17 workload',
+        note: '1024 particles at 2×4 — measured at 3.5 ms against a 2 ms budget',
+        control: { shape: 'sheet', width: 32, height: 32, spacing: 0.02, mass: 0.5, pinned: 'top', flat: false, hard: true, stretch: 1e4, bend: 1e-5, substeps: 2, iterations: 4 }
+    },
+    {
+        name: 'α·γ = 0.6',
+        note: 'past the cliff — a hard chain detonates and the tripwire says so',
+        control: { shape: 'chain', width: 20, spacing: 0.02, mass: 0.01, hard: true, substeps: 2, iterations: 4 },
+        tuning: { alpha: 0.6, gamma: 1 }
+    },
+    {
+        name: 'one iteration',
+        note: 'stable, just softer — §5.1',
+        control: { shape: 'sheet', width: 24, height: 30, spacing: 0.02, mass: 0.3, pinned: 'top', flat: false, hard: true, bend: 1e-5, substeps: 1, iterations: 1 }
+    }
+];
+
+const presets = element('presets');
+
+for (const preset of PRESET) {
+    const button = document.createElement('button');
+
+    button.innerHTML = `${preset.name}<small>${preset.note}</small>`;
+
+    button.addEventListener('click', () => {
+        Object.assign(control, preset.control);
+
+        control.alpha = preset.tuning?.alpha ?? CLOTH_SOLVER_TUNING.alpha;
+        control.gamma = preset.tuning?.gamma ?? CLOTH_SOLVER_TUNING.gamma;
+        control.wind = preset.wind === true;
+
+        control.running = true;
+
+        element('pause').textContent = 'pause';
+        element('wind').classList.toggle('on', control.wind);
+
+        refresh_every_control();
+        refresh_shape_rows();
+
+        rebuild();
+
+        preset.after?.(scene.state);
+    });
+
+    presets.appendChild(button);
+}
+
+/** Push `control` back out into every widget after a preset moves it. */
+function refresh_every_control() {
+    const linear = { width: 'width', height: 'height', spacing: 'spacing', substeps: 'substeps', iterations: 'iterations', gravity: 'gravity', alpha: 'alpha', gamma: 'gamma' };
+    const logarithmic = { mass: 'mass', stretch: 'stretch', bend: 'bend', beta: 'beta', k_min: 'k_min_ratio', k_max: 'k_max_ratio' };
+
+    for (const [id, field] of Object.entries(linear)) {
+        bound[id].input.value = String(control[field]);
+        bound[id].show();
+    }
+
+    for (const [id, field] of Object.entries(logarithmic)) {
+        bound[id].input.value = String(Math.log10(control[field]));
+        bound[id].show();
+    }
+
+    element('shape').value = control.shape;
+    element('pinned').value = control.pinned;
+    element('flat').checked = control.flat;
+    element('hard').checked = control.hard;
+
+    refresh_product();
+}
+
+// ---------------------------------------------------------------- pointer
+
+let drag = null;
+
+const world = new Float64Array(3);
+const screen = new Float64Array(2);
+
+function pointer_position(event) {
+    const rect = canvas.getBoundingClientRect();
+
+    return {
+        x: (event.clientX - rect.left) * (canvas.width / rect.width),
+        y: (event.clientY - rect.top) * (canvas.height / rect.height)
+    };
+}
+
+canvas.addEventListener('pointerdown', (event) => {
+    const { x, y } = pointer_position(event);
+
+    canvas.setPointerCapture(event.pointerId);
+    canvas.classList.add('grabbing');
+
+    if (!event.shiftKey && event.button === 0) {
+        const particle = pick_particle(scene.state, camera, x, y, canvas.width, canvas.height, 12);
+
+        if (particle >= 0) {
+            grabbed = particle;
+            grabbed_mass_inverse = scene.state.mass_inverse[particle];
+
+            // Pinning it is how the solver is told to leave it alone. It keeps
+            // acting on its neighbours through its rows, which is exactly what
+            // makes dragging one corner move the whole sheet.
+            scene.state.mass_inverse[particle] = 0;
+
+            grabbed_depth = project(
+                screen, camera,
+                scene.state.position[particle * 3],
+                scene.state.position[particle * 3 + 1],
+                scene.state.position[particle * 3 + 2],
+                canvas.width, canvas.height
+            );
+
+            drag = { mode: 'particle' };
+
+            return;
+        }
+    }
+
+    drag = {
+        mode: (event.shiftKey || event.button === 2) ? 'pan' : 'orbit',
+        x, y
+    };
+});
+
+canvas.addEventListener('pointermove', (event) => {
+    if (drag === null) {
+        return;
+    }
+
+    const { x, y } = pointer_position(event);
+
+    if (drag.mode === 'particle') {
+        unproject(world, camera, x, y, grabbed_depth, canvas.width, canvas.height);
+
+        scene.state.position[grabbed * 3] = world[0];
+        scene.state.position[grabbed * 3 + 1] = world[1];
+        scene.state.position[grabbed * 3 + 2] = world[2];
+
+        return;
+    }
+
+    const dx = x - drag.x;
+    const dy = y - drag.y;
+
+    drag.x = x;
+    drag.y = y;
+
+    if (drag.mode === 'orbit') {
+        camera.yaw -= dx * 0.006;
+        camera.pitch = Math.max(-1.5, Math.min(1.5, camera.pitch + dy * 0.006));
+
+        return;
+    }
+
+    // Pan moves the target in the camera's own screen plane, so the cloth
+    // tracks the cursor whatever the orbit is.
+    const scale = camera.distance / canvas.height;
+
+    const cos_yaw = Math.cos(camera.yaw);
+    const sin_yaw = Math.sin(camera.yaw);
+
+    camera.target[0] -= (dx * cos_yaw) * scale;
+    camera.target[2] += (dx * sin_yaw) * scale;
+    camera.target[1] += dy * scale;
+});
+
+function release(event) {
+    if (drag !== null && drag.mode === 'particle' && grabbed >= 0) {
+        scene.state.mass_inverse[grabbed] = grabbed_mass_inverse;
+
+        // Let go with the velocity it had, not with the velocity of the hand:
+        // `cloth_step` reads velocity back out of the positions, and a held
+        // particle's positions were written by the pointer.
+        scene.state.velocity[grabbed * 3] = 0;
+        scene.state.velocity[grabbed * 3 + 1] = 0;
+        scene.state.velocity[grabbed * 3 + 2] = 0;
+
+        grabbed = -1;
+    }
+
+    drag = null;
+
+    canvas.classList.remove('grabbing');
+
+    if (event !== undefined && canvas.hasPointerCapture(event.pointerId)) {
+        canvas.releasePointerCapture(event.pointerId);
+    }
+}
+
+canvas.addEventListener('pointerup', release);
+canvas.addEventListener('pointercancel', release);
+canvas.addEventListener('contextmenu', (event) => event.preventDefault());
+
+canvas.addEventListener('wheel', (event) => {
+    event.preventDefault();
+
+    camera.distance = Math.max(0.05, Math.min(50, camera.distance * Math.exp(event.deltaY * 0.0012)));
+}, { passive: false });
+
+// ---------------------------------------------------------------- start
+
+function resize() {
+    const ratio = Math.min(2, window.devicePixelRatio || 1);
+
+    canvas.width = Math.round(canvas.clientWidth * ratio);
+    canvas.height = Math.round(canvas.clientHeight * ratio);
+}
+
+window.addEventListener('resize', resize);
+
+resize();
+refresh_shape_rows();
+refresh_product();
+rebuild();
+
+requestAnimationFrame(frame);
+
+// A handle for a driver script — the browser playgrounds in this tree are
+// screenshot from headless Chrome as often as they are looked at.
+globalThis.cloth_playground = { control, camera, rebuild, step_once, get scene() { return scene; } };