@es3d/es3d 0.0.0-stage → 1.0.0

package/src/render/shaders/wgsl.js

@@ -0,0 +1,252 @@
+// WGSL shaders for the WebGPU backend. They mirror shaders/glsl.js.
+
+import {
+  MAT_FLAG_MAP, MAT_FLAG_NORMAL_MAP, MAT_FLAG_UNLIT, MAT_FLAG_DOUBLE_SIDED, MAT_FLAG_MR_MAP,
+  MAT_FLAG_OCCLUSION, MAT_FLAG_EMISSIVE_MAP, MAT_FLAG_ALPHA_MASK,
+} from '../lighting.js';
+
+const STRUCTS = /* wgsl */ `
+struct Frame {
+  viewProj: mat4x4f,
+  view: mat4x4f,
+  cameraPos: vec4f,
+  sky: vec4f,
+  ground: vec4f,
+  params: vec4f,
+  lightPos: array<vec4f, 16>,
+  lightDir: array<vec4f, 16>,
+  lightColor: array<vec4f, 16>,
+  lightExtra: array<vec4f, 16>,
+};
+struct Material {
+  baseColor: vec4f,
+  emissive: vec4f,
+  params: vec4f,
+  uvScale: vec4f,
+  overlay: vec4f,
+};
+@group(0) @binding(0) var<uniform> frame: Frame;
+@group(1) @binding(0) var<uniform> material: Material;
+@group(1) @binding(1) var samp: sampler;
+@group(1) @binding(2) var baseTex: texture_2d<f32>;
+@group(1) @binding(3) var normalTex: texture_2d<f32>;
+@group(1) @binding(4) var mrTex: texture_2d<f32>;
+@group(1) @binding(5) var occlusionTex: texture_2d<f32>;
+@group(1) @binding(6) var emissiveTex: texture_2d<f32>;
+
+struct VSIn {
+  @location(0) position: vec3f,
+  @location(1) normal: vec3f,
+  @location(2) uv: vec2f,
+  @location(3) m0: vec4f,
+  @location(4) m1: vec4f,
+  @location(5) m2: vec4f,
+  @location(6) m3: vec4f,
+};
+
+const PI = 3.14159265359;
+
+fn linearToSrgb(c0: vec3f) -> vec3f {
+  let c = max(c0, vec3f(0.0));
+  return select(1.055 * pow(c, vec3f(1.0 / 2.4)) - 0.055, c * 12.92, c <= vec3f(0.0031308));
+}
+fn aces(x: vec3f) -> vec3f {
+  return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), vec3f(0.0), vec3f(1.0));
+}
+fn worldNormal(inp: VSIn) -> vec3f {
+  let c0 = inp.m0.xyz;
+  let c1 = inp.m1.xyz;
+  let c2 = inp.m2.xyz;
+  let cof = mat3x3f(cross(c1, c2), cross(c2, c0), cross(c0, c1));
+  let det = dot(c0, cross(c1, c2));
+  return cof * inp.normal * select(1.0, -1.0, det < 0.0);
+}
+`;
+
+/** Vertex stage of the mesh modules; texture coordinates only for textured materials. */
+const meshVertex = (textured) => /* wgsl */ `
+struct VSOut {
+  @builtin(position) pos: vec4f,
+  @location(0) world: vec3f,
+  @location(1) normal: vec3f,
+  ${textured ? '@location(2) uv: vec2f,' : ''}
+};
+
+@vertex
+fn vs_main(inp: VSIn) -> VSOut {
+  let M = mat4x4f(inp.m0, inp.m1, inp.m2, inp.m3);
+  let wp = M * vec4f(inp.position, 1.0);
+  var out: VSOut;
+  out.pos = frame.viewProj * wp;
+  out.world = wp.xyz;
+  out.normal = worldNormal(inp);
+  ${textured ? 'out.uv = inp.uv;' : ''}
+  return out;
+}
+`;
+
+const BRDF = /* wgsl */ `
+fn D_GGX(NdotH: f32, a: f32) -> f32 {
+  let a2 = a * a;
+  let d = NdotH * NdotH * (a2 - 1.0) + 1.0;
+  return a2 / (PI * d * d);
+}
+fn V_Smith(NdotV: f32, NdotL: f32, a: f32) -> f32 {
+  let a2 = a * a;
+  let gv = NdotL * sqrt(NdotV * NdotV * (1.0 - a2) + a2);
+  let gl = NdotV * sqrt(NdotL * NdotL * (1.0 - a2) + a2);
+  return 0.5 / max(gv + gl, 1e-5);
+}
+fn F_Schlick(f0: vec3f, VdotH: f32) -> vec3f {
+  return f0 + (vec3f(1.0) - f0) * pow(1.0 - VdotH, 5.0);
+}
+fn envBRDF(f0: vec3f, roughness: f32, NdotV: f32) -> vec3f {
+  let c0 = vec4f(-1.0, -0.0275, -0.572, 0.022);
+  let c1 = vec4f(1.0, 0.0425, 1.04, -0.04);
+  let r = roughness * c0 + c1;
+  let a004 = min(r.x * r.x, exp2(-9.28 * NdotV)) * r.x + r.y;
+  let AB = vec2f(-1.04, 1.04) * a004 + r.zw;
+  return f0 * AB.x + AB.y;
+}
+// one light's contribution, zero when it is behind the surface
+fn shade(N: vec3f, V: vec3f, L: vec3f, radiance: vec3f, NdotV: f32, f0: vec3f, diffuse: vec3f, a: f32) -> vec3f {
+  let NdotL = dot(N, L);
+  if (NdotL <= 0.0) {
+    return vec3f(0.0);
+  }
+  let H = normalize(V + L);
+  let NdotH = max(dot(N, H), 0.0);
+  let VdotH = max(dot(V, H), 0.0);
+  let F = F_Schlick(f0, VdotH);
+  let spec = D_GGX(NdotH, a) * V_Smith(NdotV, NdotL, a) * F;
+  let kd = (vec3f(1.0) - F) * diffuse / PI;
+  return (kd + spec) * radiance * NdotL;
+}
+`;
+
+/**
+ * Shader module for one material feature set (MAT_FLAG_* bits) and one light
+ * setup (lightTypes() of the frame), as meshFragmentShader() in
+ * glsl.js: everything the material does not use is compiled out, and the
+ * light loop is unrolled. Textures are sampled in uniform control flow (the
+ * double-sided normal flip is a select, not a branch); after an alpha-mask
+ * discard, lookups use explicit gradients taken before it.
+ */
+export function meshShader(flags, lights) {
+  const has = (f) => (flags & f) !== 0;
+  const map = has(MAT_FLAG_MAP), normalMap = has(MAT_FLAG_NORMAL_MAP), mrMap = has(MAT_FLAG_MR_MAP);
+  const occlusion = has(MAT_FLAG_OCCLUSION), emissiveMap = has(MAT_FLAG_EMISSIVE_MAP);
+  const textured = map || normalMap || mrMap || occlusion || emissiveMap;
+  const grad = has(MAT_FLAG_ALPHA_MASK);
+  const sample = (tex) => (grad ? `textureSampleGrad(${tex}, samp, uv, ddx, ddy)` : `textureSample(${tex}, samp, uv)`);
+  const L = [STRUCTS, meshVertex(textured)];
+  if (!has(MAT_FLAG_UNLIT)) L.push(BRDF);
+  L.push('@fragment', 'fn fs_main(inp: VSOut, @builtin(front_facing) frontFacing: bool) -> @location(0) vec4f {');
+  if (textured) L.push('  let uv = inp.uv * material.uvScale.xy;');
+  if ((textured && grad) || normalMap) L.push('  let ddx = dpdx(uv);', '  let ddy = dpdy(uv);');
+  if (normalMap) {
+    // WGSL derivatives use framebuffer y (down); negate dpdy to match GLSL's
+    // window-space dFdy (up) so the cotangent frame has the same handedness
+    L.push('  let dp1 = dpdx(inp.world);', '  let dp2 = -dpdy(inp.world);', '  let duv1 = ddx;', '  let duv2 = -ddy;');
+  }
+  L.push('  var base = material.baseColor;');
+  if (map) L.push(`  base = base * ${sample('baseTex')};`);
+  if (grad) L.push('  if (base.a < material.params.w) {', '    discard;', '  }');
+  L.push('  var emitted = material.emissive.rgb;');
+  if (emissiveMap) L.push(`  emitted = emitted * ${sample('emissiveTex')}.rgb;`);
+  if (has(MAT_FLAG_UNLIT)) {
+    L.push('  return vec4f(linearToSrgb(base.rgb + emitted), base.a);', '}');
+    return L.join('\n');
+  }
+  L.push('  var N = normalize(inp.normal);');
+  if (has(MAT_FLAG_DOUBLE_SIDED)) L.push('  N = select(-N, N, frontFacing);');
+  if (normalMap) {
+    L.push(`  let dp2perp = cross(dp2, N);
+  let dp1perp = cross(N, dp1);
+  let T = dp2perp * duv1.x + dp1perp * duv2.x;
+  let B = dp2perp * duv1.y + dp1perp * duv2.y;
+  let invmax = inverseSqrt(max(max(dot(T, T), dot(B, B)), 1e-20));
+  let n0 = ${sample('normalTex')}.xyz * 2.0 - 1.0;
+  let n = vec3f(n0.xy * material.emissive.w, n0.z);
+  N = normalize(mat3x3f(T * invmax, B * invmax, N) * n);`);
+  }
+  L.push(`  let V = normalize(frame.cameraPos.xyz - inp.world);
+  let NdotV = max(dot(N, V), 1e-4);
+  var rough = clamp(material.params.y, 0.045, 1.0);
+  var metal = clamp(material.params.x, 0.0, 1.0);`);
+  if (mrMap) {
+    L.push(`  let mr = ${sample('mrTex')};
+  rough = clamp(rough * mr.g, 0.045, 1.0);
+  metal = clamp(metal * mr.b, 0.0, 1.0);`);
+  }
+  L.push(`  let a = rough * rough;
+  let f0 = mix(vec3f(0.04), base.rgb, metal);
+  let diffuse = base.rgb * (1.0 - metal);
+  var color = vec3f(0.0);
+  var ambient = vec3f(0.0);`);
+  if (lights) lights.split(',').forEach((type, i) => L.push(lightTerm(Number(type), i)));
+  L.push(`  let envI = frame.sky.w;
+  var hemi = mix(frame.ground.rgb, frame.sky.rgb, N.y * 0.5 + 0.5) * envI + ambient;
+  let R = reflect(-V, N);
+  var envSpec = mix(frame.ground.rgb, frame.sky.rgb, smoothstep(-0.25 - rough, 0.25 + rough, R.y)) * envI;
+  envSpec = mix(envSpec, hemi, rough * rough);`);
+  if (occlusion) {
+    L.push(`  let ao = mix(1.0, ${sample('occlusionTex')}.r, material.uvScale.z);
+  hemi = hemi * ao;
+  envSpec = envSpec * ao;`);
+  }
+  L.push(`  color = color + diffuse * hemi + envSpec * envBRDF(f0, rough, NdotV);
+  color = color + emitted;
+  color = color * frame.ground.w;
+  return vec4f(linearToSrgb(aces(color)), base.a);
+}`);
+  return L.join('\n');
+}
+
+/** WGSL for light i of a known type (lighting.js: 0 directional, 1 point, 2 spot, 3 ambient, 4 hemisphere). */
+function lightTerm(type, i) {
+  if (type === 3) return `  ambient = ambient + frame.lightColor[${i}].rgb;`;
+  if (type === 4) return `  ambient = ambient + mix(frame.lightExtra[${i}].yzw, frame.lightColor[${i}].rgb, N.y * 0.5 + 0.5);`;
+  if (type === 0) return `  color = color + shade(N, V, -frame.lightDir[${i}].xyz, frame.lightColor[${i}].rgb * PI, NdotV, f0, diffuse, a);`;
+  return `  {
+    let Lv = frame.lightPos[${i}].xyz - inp.world;
+    let d = length(Lv);
+    let L = Lv / max(d, 1e-5);
+    var att = 1.0 / max(d * d, 1e-4);
+    let range = frame.lightDir[${i}].w;
+    if (range > 0.0) {
+      let x = d / range;
+      let w = clamp(1.0 - x * x * x * x, 0.0, 1.0);
+      att = att * w * w;
+    }${type === 2 ? `\n    att = att * smoothstep(frame.lightColor[${i}].w, frame.lightExtra[${i}].x, dot(-L, frame.lightDir[${i}].xyz));` : ''}
+    color = color + shade(N, V, L, frame.lightColor[${i}].rgb * PI * att, NdotV, f0, diffuse, a);
+  }`;
+}
+
+export const LINE_WGSL = /* wgsl */ `
+${STRUCTS}
+@vertex
+fn vs_line(inp: VSIn) -> @builtin(position) vec4f {
+  let M = mat4x4f(inp.m0, inp.m1, inp.m2, inp.m3);
+  let wp = M * vec4f(inp.position, 1.0);
+  return frame.viewProj * vec4f(mix(wp.xyz, frame.cameraPos.xyz, frame.params.z), 1.0);
+}
+
+@vertex
+fn vs_normals(inp: VSIn) -> @builtin(position) vec4f {
+  let M = mat4x4f(inp.m0, inp.m1, inp.m2, inp.m3);
+  var wp = M * vec4f(inp.position, 1.0);
+  let n = normalize(worldNormal(inp));
+  wp = vec4f(wp.xyz + n * inp.uv.x * frame.params.y, 1.0);
+  return frame.viewProj * vec4f(mix(wp.xyz, frame.cameraPos.xyz, frame.params.z), 1.0);
+}
+
+@fragment
+fn fs_line() -> @location(0) vec4f {
+  let flags = u32(material.params.z + 0.5);
+  if ((flags & 16u) != 0u) {
+    return material.overlay;
+  }
+  return vec4f(linearToSrgb(material.baseColor.rgb + material.emissive.rgb), material.baseColor.a);
+}
+`;

package/src/render/stage.js

@@ -0,0 +1,352 @@
+// A stage: an ES3D document on a canvas, ready for a web page.
+//
+//   const stage = await createStage(canvas, { scroll: document.querySelector('#tour') });
+//   stage.show(source);
+//
+// It compiles the document, draws it with the renderer, and handles what a
+// page needs around that:
+//
+// - Draws only when something visible changed (camera, animation, size, a
+//   texture arriving), and not at all while the canvas is scrolled away.
+// - Applies the document's <controls>: orbit limits, collision with the scene,
+//   no dragging (mode="none") or a camera driven by page scroll (mode="scroll").
+// - Drives timeline="scroll" animations from the scroll position of a page
+//   section (see ScrollTimeline), and builds the meshes the scroll path will
+//   need while the browser is idle, so scrolling does not stutter later.
+// - Keeps geometry between documents: show() reuses the previous document's
+//   geometry cache, so swapping a colour re-tessellates and re-uploads nothing.
+// - Keeps geometry between visits: the meshes a document's shapes produced
+//   are stored in the browser (IndexedDB, src/cache/geometry-store.js) once
+//   the page is idle, and read back instead of tessellated on the next visit.
+//
+// Reduced motion (prefers-reduced-motion) stops clock animations and the
+// automatic orbit; scroll-driven cameras jump between stops.
+
+import { compile } from '../pipeline.js';
+import { updateDynamic } from '../scene/flatten.js';
+import { pick } from '../scene/picking.js';
+import { createRenderer, PROGRESSIVE_BUDGET_MS } from './renderer.js';
+import { openGeometryStore, persistGeometry } from '../cache/geometry-store.js';
+import { Camera } from './camera.js';
+import { OrbitControls } from './orbit-controls.js';
+import { ScrollTimeline } from './scroll-timeline.js';
+
+const reducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+const idle = (fn) => (typeof requestIdleCallback === 'function' ? requestIdleCallback(fn, { timeout: 500 }) : setTimeout(fn, 16));
+
+/** Names (name or id) on an element and its ancestors, nearest first. */
+export function ancestorNames(doc, uid) {
+  const names = [];
+  let el = doc && doc.byUid.get(uid);
+  while (el) {
+    const n = el.values && (el.values.name || el.values.id);
+    if (n) names.push(n);
+    el = el.parent;
+  }
+  return names;
+}
+
+/** Views sampled along a scroll path to warm up its meshes. */
+const PREFETCH_SAMPLES = 24;
+
+/** How long a new document waits for its stored meshes before drawing without them (ms). */
+const RESTORE_WAIT_MS = 50;
+
+/**
+ * @param {HTMLCanvasElement} canvas sized by its parent element
+ * @param {object} [opts]
+ * @param {boolean} [opts.playing=true] play clock animations
+ * @param {boolean} [opts.autoOrbit=true] turn slowly around the target until someone drags
+ * @param {number} [opts.orbitSpeed=0.22] radians per second
+ * @param {boolean} [opts.interactive=true] false: no dragging, whatever the document says
+ * @param {HTMLElement} [opts.scroll] section whose scroll position drives timeline="scroll"
+ *   animations (default: the whole page)
+ * @param {string} [opts.backend] 'auto' | 'webgpu' | 'webgl2'
+ * @param {(dt:number, stage:object) => void} [opts.onFrame] called every animation frame
+ * @param {(hit: object|null) => void} [opts.onPick] click on the scene; hit.names lists name/id up the tree
+ * @param {() => void} [opts.onInteract] the visitor moved the camera
+ * @param {(message: string, result: object) => void} [opts.onError] the document did not compile
+ * @param {object|Promise<object>|false} [opts.geometryStore] where generated meshes are kept
+ *   between visits (default: IndexedDB, openGeometryStore()); false keeps nothing
+ */
+export async function createStage(canvas, opts = {}) {
+  // opened while the renderer starts, so the first show() rarely waits for it
+  const persist = persistGeometry(opts.geometryStore === false ? null : opts.geometryStore || openGeometryStore());
+  const renderer = await createRenderer(canvas, { backend: opts.backend });
+  renderer.options.tessellationBudget = PROGRESSIVE_BUDGET_MS;
+  const parent = canvas.parentElement;
+  const target = renderer.canvas || canvas;
+  target.style.display = 'block';
+  const camera = new Camera();
+  const controls = new OrbitControls(target, camera);
+  const motion = !reducedMotion();
+  const state = {
+    result: null,
+    time: 0,
+    progress: 0,
+    last: 0,
+    disposed: false,
+    playing: opts.playing !== false && motion,
+    auto: opts.autoOrbit !== false && motion,
+    orbitSpeed: opts.orbitSpeed ?? 0.22,
+    onScreen: true,
+    // A frame is drawn only when something visible changed: the camera, the
+    // animation time or scroll progress, the size, the scene or a texture.
+    dirty: true,
+    sceneTime: NaN, // time and progress the animated instances were last evaluated at
+    sceneProgress: NaN,
+    width: 0,
+    height: 0,
+    timeline: null,
+    generation: 0, // bumps on show(), to cancel stale idle work
+    holdUntil: 0, // no drawing before this time: a new document's stored meshes are on their way
+  };
+  const invalidate = () => {
+    state.dirty = true;
+  };
+  renderer.textures.onReady = invalidate;
+
+  // Camera state at the last drawn frame; onFrame callbacks move the camera directly.
+  const seen = new Float64Array(15).fill(NaN);
+  let moved = false;
+  const see = (i, v) => {
+    if (seen[i] !== v) {
+      seen[i] = v;
+      moved = true;
+    }
+  };
+  const cameraMoved = () => {
+    const c = camera;
+    moved = false;
+    for (let k = 0; k < 3; k++) {
+      see(k, c.position[k]);
+      see(3 + k, c.target[k]);
+      see(6 + k, c.up[k]);
+    }
+    see(9, c.fov);
+    see(10, c.orthoHeight);
+    see(11, c.type === 'orthographic' ? 1 : 0);
+    see(12, c.near ?? -1);
+    see(13, c.refAspect);
+    see(14, c.fit === 'cover' ? 1 : c.fit === 'width' ? 2 : c.fit === 'height' ? 3 : 0);
+    return moved;
+  };
+
+  const meshOf = (entry, lod) => state.result.cache.mesh(entry, lod);
+  const lodVisible = (scene) => {
+    const lods = renderer.frames.lodStates(scene, camera.position, (p) => Math.hypot(p[0] - camera.position[0], p[1] - camera.position[1], p[2] - camera.position[2]));
+    return (i) => {
+      const ln = scene.lodNode[i];
+      return ln < 0 || (lods.visible[ln] && lods.active[ln] === scene.lodChild[i]);
+    };
+  };
+  const world = () => (state.result ? { scene: state.result.scene, meshOf, isVisible: lodVisible(state.result.scene) } : null);
+
+  controls.onChange = () => {
+    state.auto = false;
+    state.dirty = true;
+    if (opts.onInteract) opts.onInteract();
+  };
+  controls.onClick = (x, y) => {
+    if (!state.result || !opts.onPick) return;
+    const w = target.clientWidth;
+    const h = target.clientHeight;
+    if (!w || !h) return;
+    const scene = state.result.scene;
+    camera.update(w / h, renderer.backend.zeroToOne, scene.bounds);
+    const ray = camera.ray(x, y, w, h, renderer.backend.zeroToOne);
+    const hit = pick(scene, meshOf, ray.origin, ray.dir, lodVisible(scene));
+    opts.onPick(hit ? { ...hit, names: ancestorNames(state.result.doc, hit.uid) } : null);
+  };
+
+  const io = new IntersectionObserver(([entry]) => {
+    state.onScreen = entry.isIntersecting;
+    if (state.onScreen) state.dirty = true;
+  }, { threshold: 0.02 });
+  io.observe(parent || target);
+  // Size comes from the observer, so frames never read layout.
+  const ro = new ResizeObserver(([entry]) => {
+    const box = entry.contentBoxSize && entry.contentBoxSize[0];
+    const w = Math.round(box ? box.inlineSize : entry.contentRect.width);
+    const h = Math.round(box ? box.blockSize : entry.contentRect.height);
+    if (w === state.width && h === state.height) return;
+    state.width = w;
+    state.height = h;
+    target.style.width = `${w}px`;
+    target.style.height = `${h}px`;
+    state.dirty = true;
+  });
+  ro.observe(parent || target);
+
+  const mode = () => (state.result && state.result.scene.controls ? state.result.scene.controls.mode : 'orbit');
+  // in scroll and none modes the document's first camera is the view
+  const followsDocument = () => mode() !== 'orbit' && state.result && state.result.scene.cameras.length > 0;
+  const view = () => ({ width: state.width, height: state.height, dpr: typeof devicePixelRatio === 'number' ? devicePixelRatio : 1 });
+
+  /** Build, while the browser is idle, the meshes for views sampled along the scroll path. */
+  const prefetchScrollPath = () => {
+    const gen = state.generation;
+    let k = 0;
+    const step = () => {
+      const res = state.result;
+      if (state.disposed || gen !== state.generation || !res || k > PREFETCH_SAMPLES) return;
+      if (!state.width || !state.height) return void setTimeout(() => idle(step), 200);
+      const p = k / PREFETCH_SAMPLES;
+      k++;
+      updateDynamic(res.scene, res.graph, state.time, p);
+      const cam = followsDocument() ? new Camera().fromSpec(res.scene.cameras[0]) : camera;
+      renderer.prepare(cam, view());
+      // put the scene back where the page is
+      updateDynamic(res.scene, res.graph, state.sceneTime, state.sceneProgress);
+      persist.changed(res.cache);
+      idle(step);
+    };
+    idle(step);
+  };
+
+  const configureScroll = () => {
+    const scene = state.result.scene;
+    if (!scene.animation.scroll) {
+      if (state.timeline) state.timeline.dispose();
+      state.timeline = null;
+      return;
+    }
+    if (!state.timeline) {
+      const section = opts.scroll || document.scrollingElement || document.documentElement;
+      state.timeline = new ScrollTimeline(section);
+    }
+    state.timeline.update(0);
+    state.progress = state.timeline.value;
+  };
+
+  const api = {
+    camera,
+    renderer,
+    controls,
+    kind: renderer.kind,
+    get time() {
+      return state.time;
+    },
+    set time(v) {
+      state.time = v;
+    },
+    /** Scroll timeline position 0..1; set it to drive scroll animations without a page section. */
+    get progress() {
+      return state.progress;
+    },
+    set progress(v) {
+      if (state.timeline) {
+        state.timeline.dispose();
+        state.timeline = null;
+      }
+      state.progress = Math.min(1, Math.max(0, v));
+    },
+    get playing() {
+      return state.playing;
+    },
+    set playing(v) {
+      state.playing = !!v;
+    },
+    /** Draw the next frame even if nothing the stage tracks has changed. */
+    invalidate,
+    get result() {
+      return state.result;
+    },
+    /**
+     * Compile and show a document. Returns the compile result; on errors the
+     * previous document stays on screen.
+     * @param {string} source
+     * @param {{keepCamera?: boolean, time?: number}} [showOpts]
+     */
+    show(source, showOpts = {}) {
+      if (showOpts.time !== undefined) state.time = showOpts.time;
+      // Reusing the cache keeps every mesh whose definition did not change
+      // (a new wrap or paint only changes materials), so nothing is re-tessellated
+      // and the renderer finds those meshes already on the GPU.
+      const result = compile(source, { time: state.time, progress: state.progress, cache: state.result ? state.result.cache : undefined });
+      if (!result.ok) {
+        const msg = result.diagnostics.map((d) => d.format()).join('\n\n');
+        if (opts.onError) opts.onError(msg, result);
+        else console.error(msg);
+        return result;
+      }
+      state.result = result;
+      state.generation++;
+      renderer.setScene(result.scene, meshOf);
+      configureScroll();
+      if (state.progress !== 0) updateDynamic(result.scene, result.graph, state.time, state.progress);
+      state.sceneTime = state.time;
+      state.sceneProgress = state.progress;
+      state.dirty = true;
+      const spec = result.scene.controls;
+      controls.configure(spec, { world });
+      if (opts.interactive === false) controls.enabled = false;
+      if (spec && spec.mode !== 'orbit') state.auto = false;
+      if (!showOpts.keepCamera || followsDocument()) {
+        if (result.scene.cameras.length) camera.fromSpec(result.scene.cameras[0]);
+        else camera.frame(result.scene.bounds);
+      }
+      // draw once the stored meshes are in, or without them after a short wait;
+      // the scroll path is prepared after that, so it only builds what was not stored
+      const gen = state.generation;
+      state.holdUntil = performance.now() + RESTORE_WAIT_MS;
+      persist.restore(result.cache).finally(() => {
+        if (gen !== state.generation) return;
+        state.holdUntil = 0;
+        state.dirty = true;
+        if (result.scene.animation.scroll) prefetchScrollPath();
+      });
+      return result;
+    },
+    dispose() {
+      state.disposed = true;
+      io.disconnect();
+      ro.disconnect();
+      if (state.timeline) state.timeline.dispose();
+      controls.dispose();
+      renderer.dispose();
+    },
+  };
+
+  const frame = (now) => {
+    if (state.disposed) return;
+    requestAnimationFrame(frame);
+    const dt = state.last ? Math.min(0.05, (now - state.last) / 1000) : 0;
+    state.last = now;
+    if (!state.result || !state.onScreen) return;
+    if (!state.width || !state.height) return;
+    const res = state.result;
+    const scene = res.scene;
+    // a scene without clock animations looks the same at every time
+    if (state.playing && scene.animation.time) state.time += dt;
+    if (state.timeline && state.timeline.update(dt)) state.progress = state.timeline.value;
+    if (opts.onFrame) opts.onFrame(dt, api);
+    if (state.auto) {
+      const prev = controls.snapshot();
+      const dx = camera.position[0] - camera.target[0];
+      const dz = camera.position[2] - camera.target[2];
+      const a = state.orbitSpeed * dt;
+      const co = Math.cos(a);
+      const si = Math.sin(a);
+      camera.position[0] = camera.target[0] + dx * co - dz * si;
+      camera.position[2] = camera.target[2] + dx * si + dz * co;
+      controls.constrain(prev);
+    }
+    if (scene.dynamic.length && (state.time !== state.sceneTime || state.progress !== state.sceneProgress)) {
+      updateDynamic(scene, res.graph, state.time, state.progress);
+      state.sceneTime = state.time;
+      state.sceneProgress = state.progress;
+      if (followsDocument()) camera.fromSpec(scene.cameras[0]);
+      state.dirty = true;
+    }
+    if (cameraMoved()) state.dirty = true;
+    if (!state.dirty || (state.holdUntil && now < state.holdUntil)) return;
+    state.dirty = false;
+    renderer.render(camera, { ...view(), time: state.time });
+    // levels drawn coarser than wanted: refine them on the next frame
+    if (renderer.stats.refining) state.dirty = true;
+    persist.changed(res.cache);
+  };
+  requestAnimationFrame(frame);
+  return api;
+}

package/src/render/texture-cache.js

@@ -0,0 +1,40 @@
+// Backend-independent texture bookkeeping: each distinct texture spec (by key
+// and usage) is generated or downloaded once; backends turn ready pixel data
+// into GPU textures. Failures are reported, never silently ignored.
+
+import { texturePixels } from './textures.js';
+
+export class TextureCache {
+  constructor() {
+    this.entries = new Map(); // `${kind}:${key}` -> {status, pixels, error, gpu, spec, kind}
+    this.onReady = null; // called when an async texture finishes (request a redraw)
+    this.onError = null;
+  }
+
+  /** Get (and start loading) a texture; returns the entry (status 'pending'|'ready'|'failed'). */
+  get(spec, kind) {
+    const id = `${kind}:${spec.key}`;
+    let e = this.entries.get(id);
+    if (e) return e;
+    e = { id, spec, kind, status: 'pending', pixels: null, error: null, gpu: null };
+    this.entries.set(id, e);
+    texturePixels(spec, kind).then(
+      (px) => {
+        e.pixels = px;
+        e.status = 'ready';
+        if (this.onReady) this.onReady(e);
+      },
+      (err) => {
+        e.status = 'failed';
+        e.error = err;
+        if (this.onError) this.onError(e, err);
+      },
+    );
+    return e;
+  }
+
+  clear(destroy) {
+    for (const e of this.entries.values()) if (e.gpu && destroy) destroy(e.gpu);
+    this.entries.clear();
+  }
+}