@es3d/es3d 0.0.0-stage → 1.0.0

package/src/render/webgpu/webgpu-backend.js

@@ -0,0 +1,480 @@
+// WebGPU rendering backend.
+//
+// Same architecture as the WebGL2 backend: one shared vertex buffer, one
+// shared uint32 index buffer, one instance buffer, explicit bind group
+// layouts and a cache of pipeline variants (shader specialised per material
+// features and light setup, cull mode, winding, blending, topology). Each
+// batch is one drawIndexed call using firstInstance.
+
+import { meshShader, LINE_WGSL } from '../shaders/wgsl.js';
+import { FRAME_BYTES, MATERIAL_FLOATS, packMaterial, packOverlay, lightTypes } from '../lighting.js';
+import { VERTEX_BYTES } from '../geometry-pool.js';
+import { buildMips } from '../textures.js';
+
+const SAMPLE_COUNT = 4;
+
+const VERTEX_LAYOUTS = [
+  {
+    arrayStride: VERTEX_BYTES,
+    stepMode: 'vertex',
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' },
+      { shaderLocation: 1, offset: 12, format: 'float32x3' },
+      { shaderLocation: 2, offset: 24, format: 'float32x2' },
+    ],
+  },
+  {
+    arrayStride: 64,
+    stepMode: 'instance',
+    attributes: [
+      { shaderLocation: 3, offset: 0, format: 'float32x4' },
+      { shaderLocation: 4, offset: 16, format: 'float32x4' },
+      { shaderLocation: 5, offset: 32, format: 'float32x4' },
+      { shaderLocation: 6, offset: 48, format: 'float32x4' },
+    ],
+  },
+];
+
+const pow2 = (n, min) => {
+  let c = min;
+  while (c < n) c *= 2;
+  return c;
+};
+
+export class WebGPUBackend {
+  /**
+   * @param {HTMLCanvasElement} canvas
+   * @param {{present?: 'canvas'|'readback'}} [opts] 'readback' renders offscreen and
+   *   copies pixels into a 2D canvas (headless testing, screenshots without a swap chain)
+   */
+  constructor(canvas, opts = {}) {
+    this.canvas = canvas;
+    this.present = opts.present || 'canvas';
+    this.kind = 'webgpu';
+    this.zeroToOne = true;
+    this.pipelines = new Map();
+    this.meshModules = new Map();
+    this.materialBindings = new Map();
+    this.overlayBindings = new Map();
+    this.poolGeneration = -1;
+    this.vertexBuffer = null;
+    this.indexBuffer = null;
+    this.instanceBuffer = null;
+    this.gpuBytes = 0;
+    this.lost = false;
+    this.info = '';
+    this.errors = [];
+  }
+
+  async init() {
+    if (!navigator.gpu) throw new Error('WebGPU is not available in this browser.');
+    const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
+    if (!adapter) throw new Error('No WebGPU adapter is available.');
+    this.adapter = adapter;
+    const info = adapter.info || {};
+    this.info = [info.vendor, info.architecture, info.description].filter(Boolean).join(' ') || 'WebGPU adapter';
+    const device = await adapter.requestDevice();
+    this.device = device;
+    device.lost.then((i) => {
+      this.lost = true;
+      this.errors.push(`WebGPU device lost: ${i.message}`);
+    });
+    device.onuncapturederror = (e) => {
+      this.errors.push(e.error && e.error.message ? e.error.message : String(e));
+    };
+    if (this.present === 'readback') {
+      this.format = 'rgba8unorm';
+      this.ctx2d = this.canvas.getContext('2d');
+      if (!this.ctx2d) throw new Error('Cannot create a 2D context for WebGPU readback presentation.');
+    } else {
+      const ctx = this.canvas.getContext('webgpu');
+      if (!ctx) throw new Error('Cannot create a WebGPU canvas context.');
+      this.context = ctx;
+      this.format = navigator.gpu.getPreferredCanvasFormat();
+      // colours are written already encoded as sRGB and tone mapped to 0..1: pin the
+      // colour space and standard range so HDR and wide-gamut screens show them unchanged
+      ctx.configure({ device, format: this.format, alphaMode: 'opaque', colorSpace: 'srgb', toneMapping: { mode: 'standard' } });
+    }
+
+    this.frameLayout = device.createBindGroupLayout({
+      entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } }],
+    });
+    this.materialLayout = device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } },
+        { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
+        { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+        { binding: 3, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+        { binding: 4, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+        { binding: 5, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+        { binding: 6, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+      ],
+    });
+    this.pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [this.frameLayout, this.materialLayout] });
+    device.pushErrorScope('validation');
+    this.lineModule = device.createShaderModule({ code: LINE_WGSL, label: 'es3d lines' });
+    for (const [name, mod] of [['mesh', this.meshModule(0, '0')], ['lines', this.lineModule]]) {
+      const info2 = await mod.getCompilationInfo();
+      const errs = info2.messages.filter((m) => m.type === 'error');
+      if (errs.length) throw new Error(`WGSL ${name} shader error: ${errs.map((m) => `${m.lineNum}:${m.linePos} ${m.message}`).join('; ')}`);
+    }
+    const err = await device.popErrorScope();
+    if (err) throw new Error(`WebGPU initialisation error: ${err.message}`);
+
+    this.frameBuffer = device.createBuffer({ size: FRAME_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    this.frameBindGroup = device.createBindGroup({ layout: this.frameLayout, entries: [{ binding: 0, resource: { buffer: this.frameBuffer } }] });
+    this.sampler = device.createSampler({
+      addressModeU: 'repeat',
+      addressModeV: 'repeat',
+      magFilter: 'linear',
+      minFilter: 'linear',
+      mipmapFilter: 'linear',
+      maxAnisotropy: 8,
+    });
+    this.whiteTex = this.createTexture({ width: 1, height: 1, data: new Uint8Array([255, 255, 255, 255]) }, true);
+    this.flatNormalTex = this.createTexture({ width: 1, height: 1, data: new Uint8Array([128, 128, 255, 255]) }, false);
+    this.matData = new Float32Array(MATERIAL_FLOATS);
+  }
+
+  createTexture(px, srgb) {
+    const levels = px.width > 1 || px.height > 1 ? buildMips(px) : [px];
+    const tex = this.device.createTexture({
+      size: [px.width, px.height],
+      format: srgb ? 'rgba8unorm-srgb' : 'rgba8unorm',
+      mipLevelCount: levels.length,
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    });
+    levels.forEach((lv, i) => {
+      const data = lv.data instanceof Uint8Array ? lv.data : new Uint8Array(lv.data.buffer, lv.data.byteOffset, lv.data.byteLength);
+      this.device.queue.writeTexture({ texture: tex, mipLevel: i }, data, { bytesPerRow: lv.width * 4, rowsPerImage: lv.height }, [lv.width, lv.height]);
+      this.gpuBytes += lv.width * lv.height * 4;
+    });
+    return { texture: tex, view: tex.createView() };
+  }
+
+  destroyTexture(t) {
+    t.texture.destroy();
+  }
+
+  /** The shader module for a material's feature flags under the frame's lights, compiled on first use. */
+  meshModule(flags, lights) {
+    const key = `${flags}|${lights}`;
+    let m = this.meshModules.get(key);
+    if (!m) {
+      m = this.device.createShaderModule({ code: meshShader(flags, lights), label: `es3d mesh ${key}` });
+      this.meshModules.set(key, m);
+    }
+    return m;
+  }
+
+  pipeline(kind, { cull = 'back', frontFace = 'ccw', blend = false, depthWrite = true, depthCompare = 'less-equal', flags = 0, lights = '' } = {}) {
+    const isMesh = kind === 'mesh';
+    const key = `${kind}|${cull}|${frontFace}|${blend}|${depthWrite}|${depthCompare}${isMesh ? `|${flags}|${lights}` : ''}`;
+    let p = this.pipelines.get(key);
+    if (p) return p;
+    const module = isMesh ? this.meshModule(flags, lights) : this.lineModule;
+    const entry = isMesh ? 'vs_main' : kind === 'normals' ? 'vs_normals' : 'vs_line';
+    p = this.device.createRenderPipeline({
+      label: key,
+      layout: this.pipelineLayout,
+      vertex: { module, entryPoint: entry, buffers: VERTEX_LAYOUTS },
+      fragment: {
+        module,
+        entryPoint: isMesh ? 'fs_main' : 'fs_line',
+        targets: [
+          {
+            format: this.format,
+            blend: blend
+              ? {
+                  color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                  alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                }
+              : undefined,
+          },
+        ],
+      },
+      primitive: { topology: isMesh ? 'triangle-list' : 'line-list', cullMode: isMesh ? cull : 'none', frontFace },
+      depthStencil: { format: 'depth24plus', depthWriteEnabled: depthWrite, depthCompare },
+      multisample: { count: SAMPLE_COUNT },
+    });
+    this.pipelines.set(key, p);
+    return p;
+  }
+
+  ensureTargets() {
+    const w = this.canvas.width, h = this.canvas.height;
+    if (this.targetW === w && this.targetH === h && this.msaa) return;
+    if (this.msaa) this.msaa.destroy();
+    if (this.depth) this.depth.destroy();
+    this.msaa = this.device.createTexture({ size: [w, h], sampleCount: SAMPLE_COUNT, format: this.format, usage: GPUTextureUsage.RENDER_ATTACHMENT });
+    this.depth = this.device.createTexture({ size: [w, h], sampleCount: SAMPLE_COUNT, format: 'depth24plus', usage: GPUTextureUsage.RENDER_ATTACHMENT });
+    this.msaaView = this.msaa.createView();
+    this.depthView = this.depth.createView();
+    if (this.present === 'readback') {
+      if (this.offscreen) this.offscreen.destroy();
+      if (this.readBuffer && !this.readPending) this.readBuffer.destroy();
+      this.offscreen = this.device.createTexture({ size: [w, h], format: this.format, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC });
+      this.offscreenView = this.offscreen.createView();
+      this.readStride = Math.ceil((w * 4) / 256) * 256;
+      this.readBuffer = this.device.createBuffer({ size: this.readStride * h, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+    }
+    this.targetW = w;
+    this.targetH = h;
+  }
+
+  /** Copy the offscreen frame into the 2D canvas (readback presentation). */
+  readback(encoder) {
+    if (this.readPending) return false;
+    const w = this.targetW, h = this.targetH;
+    encoder.copyTextureToBuffer({ texture: this.offscreen }, { buffer: this.readBuffer, bytesPerRow: this.readStride }, [w, h]);
+    return true;
+  }
+
+  startReadback() {
+    const buf = this.readBuffer;
+    const w = this.targetW, h = this.targetH, stride = this.readStride;
+    this.readPending = buf.mapAsync(GPUMapMode.READ).then(() => {
+      const raw = new Uint8Array(buf.getMappedRange());
+      const px = new Uint8ClampedArray(w * h * 4);
+      for (let y = 0; y < h; y++) px.set(raw.subarray(y * stride, y * stride + w * 4), y * w * 4);
+      buf.unmap();
+      this.ctx2d.putImageData(new ImageData(px, w, h), 0, 0);
+      this.readPending = null;
+      // A frame drawn while this copy was in flight was not copied. A page that
+      // draws only on change may draw nothing more, so show that frame now.
+      if (!this.lastFrameCopied && this.offscreen && !this.lost) {
+        const encoder = this.device.createCommandEncoder();
+        this.readback(encoder);
+        this.device.queue.submit([encoder.finish()]);
+        this.lastFrameCopied = true;
+        this.startReadback();
+      }
+    });
+  }
+
+  syncPool(pool) {
+    const d = this.device;
+    const vBytes = pool.vertices.byteLength;
+    const iBytes = pool.indices.byteLength;
+    let uploaded = 0;
+    if (pool.generation !== this.poolGeneration || !this.vertexBuffer || this.vertexBuffer.size < vBytes || this.indexBuffer.size < iBytes) {
+      if (this.vertexBuffer) this.vertexBuffer.destroy();
+      if (this.indexBuffer) this.indexBuffer.destroy();
+      this.vertexBuffer = d.createBuffer({ size: pow2(vBytes, 1 << 16), usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+      this.indexBuffer = d.createBuffer({ size: pow2(iBytes, 1 << 16), usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST });
+      this.poolGeneration = pool.generation;
+      pool.uploadedVertices = 0;
+      pool.uploadedIndices = 0;
+    }
+    const p = pool.pending();
+    if (p.vertexEnd > p.vertexStart) {
+      const src = pool.vertices.subarray(p.vertexStart * 8, p.vertexEnd * 8);
+      d.queue.writeBuffer(this.vertexBuffer, p.vertexStart * VERTEX_BYTES, src.buffer, src.byteOffset, src.byteLength);
+      uploaded += src.byteLength;
+    }
+    if (p.indexEnd > p.indexStart) {
+      const src = pool.indices.subarray(p.indexStart, p.indexEnd);
+      d.queue.writeBuffer(this.indexBuffer, p.indexStart * 4, src.buffer, src.byteOffset, src.byteLength);
+      uploaded += src.byteLength;
+    }
+    pool.markUploaded();
+    return uploaded;
+  }
+
+  uploadInstances(data, count) {
+    const bytes = Math.max(64, count * 64);
+    if (!this.instanceBuffer || this.instanceBuffer.size < bytes) {
+      if (this.instanceBuffer) this.instanceBuffer.destroy();
+      this.instanceBuffer = this.device.createBuffer({ size: pow2(bytes, 64 * 256), usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+    }
+    if (count) this.device.queue.writeBuffer(this.instanceBuffer, 0, data.buffer, data.byteOffset, count * 64);
+    return count * 64;
+  }
+
+  readyTexture(entry, srgb) {
+    if (entry && entry.status === 'ready' && !entry.gpu) entry.gpu = this.createTexture(entry.pixels, srgb);
+    return entry && entry.gpu ? entry.gpu : null;
+  }
+
+  materialEntries(buffer, map, normal, mr, occlusion, emissive) {
+    return [
+      { binding: 0, resource: { buffer } },
+      { binding: 1, resource: this.sampler },
+      { binding: 2, resource: map.view },
+      { binding: 3, resource: normal.view },
+      { binding: 4, resource: mr.view },
+      { binding: 5, resource: occlusion.view },
+      { binding: 6, resource: emissive.view },
+    ];
+  }
+
+  materialBinding(material, textures, doubleSided) {
+    const id = doubleSided ? 'ds' : 'ss';
+    let rec = this.materialBindings.get(material);
+    if (!rec) {
+      rec = {};
+      this.materialBindings.set(material, rec);
+    }
+    const mapGpu = this.readyTexture(material.map ? textures.get(material.map, 'color') : null, true);
+    const nrmGpu = this.readyTexture(material.normalMap ? textures.get(material.normalMap, 'normal') : null, false);
+    const mrGpu = this.readyTexture(material.metallicRoughnessMap ? textures.get(material.metallicRoughnessMap, 'linear') : null, false);
+    const occGpu = this.readyTexture(material.occlusionMap ? textures.get(material.occlusionMap, 'linear') : null, false);
+    const emGpu = this.readyTexture(material.emissiveMap ? textures.get(material.emissiveMap, 'color') : null, true);
+    const hasMap = !!mapGpu;
+    const hasNormalMap = !!nrmGpu;
+    const hasMrMap = !!mrGpu;
+    const hasOcclusionMap = !!occGpu;
+    const hasEmissiveMap = !!emGpu;
+    const key = `${hasMap}|${hasNormalMap}|${hasMrMap}|${hasOcclusionMap}|${hasEmissiveMap}`;
+    let b = rec[id];
+    if (!b || b.key !== key) {
+      if (b) b.buffer.destroy();
+      packMaterial(this.matData, material, { hasMap, hasNormalMap, hasMrMap, hasOcclusionMap, hasEmissiveMap, doubleSided: doubleSided || material.doubleSided });
+      const buffer = this.device.createBuffer({ size: MATERIAL_FLOATS * 4, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+      this.device.queue.writeBuffer(buffer, 0, this.matData);
+      const bindGroup = this.device.createBindGroup({
+        layout: this.materialLayout,
+        entries: this.materialEntries(buffer, mapGpu || this.whiteTex, nrmGpu || this.flatNormalTex, mrGpu || this.whiteTex, occGpu || this.whiteTex, emGpu || this.whiteTex),
+      });
+      b = rec[id] = { key, buffer, bindGroup, flags: this.matData[10] };
+    }
+    return b;
+  }
+
+  overlayBinding(name, rgba) {
+    let b = this.overlayBindings.get(name);
+    if (b) return b;
+    packOverlay(this.matData, rgba);
+    const buffer = this.device.createBuffer({ size: MATERIAL_FLOATS * 4, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    this.device.queue.writeBuffer(buffer, 0, this.matData);
+    b = this.device.createBindGroup({
+      layout: this.materialLayout,
+      entries: this.materialEntries(buffer, this.whiteTex, this.flatNormalTex, this.whiteTex, this.whiteTex, this.whiteTex),
+    });
+    this.overlayBindings.set(name, b);
+    return b;
+  }
+
+  releaseMaterials(keep) {
+    for (const [m, rec] of this.materialBindings) {
+      if (keep.has(m)) continue;
+      for (const b of Object.values(rec)) b.buffer.destroy();
+      this.materialBindings.delete(m);
+    }
+  }
+
+  /** What this backend renders with (Renderer.caps). */
+  get caps() {
+    return {
+      msaaSamples: SAMPLE_COUNT,
+      anisotropy: 8,
+      maxTextureSize: this.device ? this.device.limits.maxTextureDimension2D : 0,
+      colorSpace: 'srgb',
+    };
+  }
+
+  resize(width, height) {
+    if (this.canvas.width !== width || this.canvas.height !== height) {
+      this.canvas.width = width;
+      this.canvas.height = height;
+    }
+  }
+
+  render(draw, frameData, ctx) {
+    if (this.lost) return;
+    const d = this.device;
+    this.ensureTargets();
+    d.queue.writeBuffer(this.frameBuffer, 0, frameData.buffer, frameData.byteOffset, frameData.byteLength);
+    this.uploadInstances(draw.instanceData, draw.instanceCount);
+    const encoder = d.createCommandEncoder();
+    const pass = encoder.beginRenderPass({
+      colorAttachments: [
+        {
+          view: this.msaaView,
+          resolveTarget: this.present === 'readback' ? this.offscreenView : this.context.getCurrentTexture().createView(),
+          clearValue: { r: ctx.background[0], g: ctx.background[1], b: ctx.background[2], a: 1 },
+          loadOp: 'clear',
+          storeOp: 'discard',
+        },
+      ],
+      depthStencilAttachment: { view: this.depthView, depthClearValue: 1, depthLoadOp: 'clear', depthStoreOp: 'discard' },
+    });
+    pass.setBindGroup(0, this.frameBindGroup);
+    if (this.vertexBuffer) {
+      pass.setVertexBuffer(0, this.vertexBuffer);
+      pass.setIndexBuffer(this.indexBuffer, 'uint32');
+    }
+    pass.setVertexBuffer(1, this.instanceBuffer);
+    let currentPipeline = null;
+    const setPipe = (p) => {
+      if (p !== currentPipeline) {
+        pass.setPipeline(p);
+        currentPipeline = p;
+      }
+    };
+    if (this.vertexBuffer) {
+      let boundGroup = null;
+      const lights = lightTypes(frameData);
+      for (const b of draw.batches) {
+        const lines = b.kind === 'lines';
+        const binding = this.materialBinding(b.material, ctx.textures, b.doubleSided && !b.material.doubleSided);
+        const pipe = lines
+          ? this.pipeline('lines', { blend: b.transparent, depthWrite: !b.transparent })
+          : this.pipeline('mesh', {
+              cull: b.doubleSided ? 'none' : 'back',
+              frontFace: b.mirrored ? 'cw' : 'ccw',
+              blend: b.transparent,
+              depthWrite: !b.transparent,
+              flags: binding.flags,
+              lights,
+            });
+        setPipe(pipe);
+        const group = binding.bindGroup;
+        if (group !== boundGroup) {
+          pass.setBindGroup(1, group);
+          boundGroup = group;
+        }
+        pass.drawIndexed(b.range.indexCount, b.count, b.range.firstIndex, 0, b.firstInstance);
+      }
+      const ov = draw.overlays;
+      const drawLines = (kind, name, color, list, depthCompare = 'less-equal') => {
+        if (!list.length) return;
+        setPipe(this.pipeline(kind, { blend: true, depthWrite: false, depthCompare }));
+        pass.setBindGroup(1, this.overlayBinding(name, color));
+        for (const o of list) pass.drawIndexed(o.range.indexCount, o.count, o.range.firstIndex, 0, o.firstInstance);
+      };
+      drawLines('lines', 'wireframe', ctx.overlayColors.wireframe, ov.wireframe);
+      drawLines('normals', 'normals', ctx.overlayColors.normals, ov.normals);
+      if (ov.bbox && ov.bbox.count) drawLines('lines', 'bbox', ctx.overlayColors.bbox, [{ ...ov.bbox, range: ctx.cubeRange }]);
+      if (ov.selection && ov.selection.count) drawLines('lines', 'selection', ctx.overlayColors.selection, [{ ...ov.selection, range: ctx.cubeRange }], 'always');
+    }
+    pass.end();
+    const copied = this.present === 'readback' && this.readback(encoder);
+    d.queue.submit([encoder.finish()]);
+    if (copied) this.startReadback();
+    this.lastFrameCopied = copied;
+  }
+
+  async finish() {
+    await this.device.queue.onSubmittedWorkDone();
+    if (this.readPending) await this.readPending;
+    if (this.present === 'readback' && !this.lastFrameCopied && this.offscreen) {
+      // the latest frame was rendered while an older readback was in flight
+      const encoder = this.device.createCommandEncoder();
+      this.readback(encoder);
+      this.device.queue.submit([encoder.finish()]);
+      this.startReadback();
+      await this.readPending;
+      this.lastFrameCopied = true;
+    }
+  }
+
+  dispose() {
+    if (!this.device) return;
+    for (const b of [this.vertexBuffer, this.indexBuffer, this.instanceBuffer, this.frameBuffer]) if (b) b.destroy();
+    for (const rec of this.materialBindings.values()) for (const b of Object.values(rec)) b.buffer.destroy();
+    if (this.msaa) this.msaa.destroy();
+    if (this.depth) this.depth.destroy();
+    this.device.destroy();
+  }
+}

package/src/scene/animation.js

@@ -0,0 +1,171 @@
+// Animation of a transform (and of a camera's target and fov).
+//
+// An animation has a timeline and a value source.
+//
+// Timeline. "time" (the default): nothing happens before `begin`; then the
+// animation plays `repeat` cycles of length `dur` (optionally reversing
+// direction) and holds the end value. "scroll": progress is the page scroll
+// position mapped to 0..1 by the viewer, and dur/begin/repeat are not used.
+// Either way the result is a fraction f in 0..1, shaped by `easing`.
+//
+// Value source. from/to: a straight interpolation. values (+ keyTimes): key
+// values reached at the given fractions, linear or on a centripetal
+// Catmull-Rom curve (smooth). along: a 3D path walked at constant speed, so
+// equal scroll moves the camera an equal distance. This is not SMIL. It is the
+// whole animation model.
+
+import { valueOf } from '../format/schema.js';
+import { spinePolylines } from '../geometry/sweep.js';
+
+const EASINGS = {
+  linear: (t) => t,
+  'ease-in': (t) => t * t,
+  'ease-out': (t) => 1 - (1 - t) * (1 - t),
+  'ease-in-out': (t) => (t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t)),
+};
+
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+export function animationFromElement(el, base) {
+  const attr = valueOf(el, 'attr');
+  const expand = (v) => (attr === 'scale' && v.length === 1 ? [v[0], v[0], v[0]] : v.slice());
+  const v = el.values;
+  const a = {
+    attr,
+    dur: valueOf(el, 'dur') || 1,
+    begin: valueOf(el, 'begin'),
+    repeat: valueOf(el, 'repeat'),
+    alternate: valueOf(el, 'alternate'),
+    ease: EASINGS[valueOf(el, 'easing')] || EASINGS.linear,
+    timeline: valueOf(el, 'timeline'),
+    smooth: valueOf(el, 'smooth'),
+    from: null,
+    to: null,
+    keys: null,
+    keyTimes: null,
+    path: null,
+  };
+  if (v.along) {
+    a.path = arcLengthPath(v.along, a.smooth);
+  } else if (v.values) {
+    a.keys = v.values.map(expand);
+    const n = a.keys.length;
+    a.keyTimes = v.keyTimes && v.keyTimes.length === n ? v.keyTimes.slice() : a.keys.map((_, i) => i / (n - 1));
+  } else {
+    a.from = v.from !== undefined ? expand(v.from) : base[attr];
+    a.to = expand(v.to);
+  }
+  return a;
+}
+
+/** Fraction 0..1 of an animation at a time and scroll progress, or -1 when it has no effect yet. */
+export function animationFraction(a, t, progress = 0) {
+  if (a.timeline === 'scroll') return a.ease(clamp01(progress));
+  const elapsed = t - a.begin;
+  if (elapsed < 0) return -1;
+  const cycles = elapsed / a.dur;
+  let f;
+  if (cycles >= a.repeat) {
+    const whole = Math.ceil(a.repeat) - 1;
+    f = a.repeat - whole;
+    if (a.alternate && whole % 2 === 1) f = 1 - f;
+  } else {
+    const k = Math.floor(cycles);
+    f = cycles - k;
+    if (a.alternate && k % 2 === 1) f = 1 - f;
+  }
+  return a.ease(f);
+}
+
+/** Value of an animation at time t (seconds) and scroll progress, or null when it has no effect yet. */
+export function sampleAnimation(a, t, progress = 0) {
+  const e = animationFraction(a, t, progress);
+  if (e < 0) return null;
+  if (a.path) return samplePath(a.path, e);
+  if (a.keys) return sampleKeys(a, e);
+  const out = new Array(a.from.length);
+  for (let k = 0; k < out.length; k++) out[k] = a.from[k] + (a.to[k] - a.from[k]) * e;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// key values
+
+function sampleKeys(a, e) {
+  const keys = a.keys;
+  const kt = a.keyTimes;
+  const n = keys.length;
+  let i = 0;
+  while (i < n - 2 && e >= kt[i + 1]) i++;
+  const span = kt[i + 1] - kt[i];
+  const u = span > 0 ? clamp01((e - kt[i]) / span) : 1;
+  const p1 = keys[i], p2 = keys[i + 1];
+  if (!a.smooth || n < 3) return p1.map((x, k) => x + (p2[k] - x) * u);
+  // end tangents mirror the neighbouring key, as for sweep spines
+  const p0 = i > 0 ? keys[i - 1] : p1.map((x, k) => 2 * x - p2[k]);
+  const p3 = i + 2 < n ? keys[i + 2] : p2.map((x, k) => 2 * x - p1[k]);
+  return centripetal(p0, p1, p2, p3, u);
+}
+
+/** Point at u (0..1) between p1 and p2 on the centripetal Catmull-Rom curve (Barry-Goldman). */
+function centripetal(p0, p1, p2, p3, u) {
+  const knot = (a, b) => {
+    let d = 0;
+    for (let k = 0; k < a.length; k++) d += (b[k] - a[k]) ** 2;
+    return Math.max(Math.sqrt(Math.sqrt(d)), 1e-9);
+  };
+  const t0 = 0;
+  const t1 = t0 + knot(p0, p1);
+  const t2 = t1 + knot(p1, p2);
+  const t3 = t2 + knot(p2, p3);
+  const t = t1 + (t2 - t1) * u;
+  const lerp = (a, b, ta, tb) => a.map((x, k) => x + ((b[k] - x) * (t - ta)) / (tb - ta));
+  const A1 = lerp(p0, p1, t0, t1), A2 = lerp(p1, p2, t1, t2), A3 = lerp(p2, p3, t2, t3);
+  const B1 = lerp(A1, A2, t0, t2), B2 = lerp(A2, A3, t1, t3);
+  return lerp(B1, B2, t1, t2);
+}
+
+// ---------------------------------------------------------------------------
+// paths
+
+/** Flatten an `along` value into one polyline with cumulative arc lengths. */
+export function arcLengthPath(spine, smooth) {
+  const opts = (tolerance) => ({ tolerance, segmentsPerTurn: 64, smooth, subdivisions: 24 });
+  // path data needs a tolerance relative to its size: measure it coarsely first
+  let lines = spinePolylines(spine, opts(1e-2));
+  if (spine.kind === 'path') {
+    let ext = 0;
+    for (const l of lines) for (let i = 0; i < l.points.length; i++) ext = Math.max(ext, Math.abs(l.points[i]));
+    lines = spinePolylines(spine, opts(Math.max(ext, 1e-6) * 1e-4));
+  }
+  const pts = [];
+  for (const l of lines) {
+    for (let i = 0; i < l.points.length; i++) pts.push(l.points[i]);
+    if (l.closed && l.points.length >= 3) pts.push(l.points[0], l.points[1], l.points[2]);
+  }
+  const n = pts.length / 3;
+  const lengths = new Float64Array(Math.max(n, 1));
+  for (let i = 1; i < n; i++) {
+    lengths[i] = lengths[i - 1] + Math.hypot(pts[i * 3] - pts[i * 3 - 3], pts[i * 3 + 1] - pts[i * 3 - 2], pts[i * 3 + 2] - pts[i * 3 - 1]);
+  }
+  return { points: Float64Array.from(pts), lengths, total: n ? lengths[n - 1] : 0 };
+}
+
+/** Point at fraction e of a path's length. */
+export function samplePath(path, e) {
+  const P = path.points;
+  const L = path.lengths;
+  const n = P.length / 3;
+  if (n === 0) return [0, 0, 0];
+  if (n === 1 || path.total <= 0) return [P[0], P[1], P[2]];
+  const s = clamp01(e) * path.total;
+  let lo = 0, hi = n - 1;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (L[mid] <= s) lo = mid;
+    else hi = mid;
+  }
+  const seg = L[hi] - L[lo];
+  const u = seg > 0 ? (s - L[lo]) / seg : 0;
+  return [P[lo * 3] + (P[hi * 3] - P[lo * 3]) * u, P[lo * 3 + 1] + (P[hi * 3 + 1] - P[lo * 3 + 1]) * u, P[lo * 3 + 2] + (P[hi * 3 + 2] - P[lo * 3 + 2]) * u];
+}