@12ui/design 0.2.71 → 0.2.73

package/scene-kit/starter/camera.js

@@ -0,0 +1,10 @@
+// Paste the "camera.js" line from `12ui scene solve spec.json --out cam.json` here. It uses the same keys and units as cam.json:
+// yawDeg / pitchDeg / rollDeg / vfov are DEGREES (main.js converts to radians). Scene units are yours.
+export const FRAME = { w: 1536, h: 1024 };            // source image size = design frame
+export const CAM = { pos: [0, 2, 6], yawDeg: 0, pitchDeg: -11, rollDeg: 0, vfov: 30 };
+// Depth range: tight. Keep far/near under ~100 or headless GL z-fights (edge-on cylinder walls, decals sitting 1 mm off a
+// surface, shadow-map leaks that show as dotted arcs). The solver prints a "clip" for this camera; also keep coincident
+// surfaces at least ~0.002 x the camera distance apart, and give thin parts real thickness or a chamfered rim.
+export const CLIP = { near: 0.5, far: 60 };
+export const PIVOT = [0, 0, 0];                       // orbit centre: where the optical axis meets the subject
+export const ORBIT_LIMIT = 15;                        // degrees each way for pointer/drag orbit

package/scene-kit/starter/gobo.js

@@ -0,0 +1,60 @@
+// Window light, leaf shadows, dappled patterns: a SpotLight with `.map` (a gobo). The pattern is DRAWN IN SOURCE-IMAGE
+// PIXELS (where the shadows sit in the design) and resampled through the solved camera onto the surface plane, so it lands
+// exactly where drawn at the landing view but is real light: it darkens whatever stands there and moves with the orbit.
+//
+//   const spot = new THREE.SpotLight(0xfff1e0, 900, 0, 0.6, 0.7, 2);  // angle = half-angle: it must cover the whole visible surface
+//   spot.position.set(-2, 8, 3); spot.target.position.set(0.5, 0, 0); spot.castShadow = true;   // .map is ignored unless castShadow is true
+//   scene.add(spot, spot.target);
+//   spot.map = goboTexture(spot, (g, w, h) => { g.fillStyle = '#fff'; g.fillRect(0, 0, w, h);   // white = light, dark = shadow
+//     g.filter = 'blur(38px)'; g.fillStyle = 'rgba(120,98,86,0.5)'; /* draw shadow shapes at source pixel coordinates */ });
+//
+// Orientation, pinned down: texture rows run from the spot's view-bottom (row 0) to view-top, flipY = false, and the pattern
+// is written through CAM (camera.js), not through the light. So DO NOT flip or mirror anything by hand. Verify once by
+// drawing a bright red square at a known source pixel (say the top-left of the sleeve) and checking that it lands there.
+// Draw past the frame edges: outside the source frame the edge value is held, so patterns fade instead of ending in a seam.
+import * as THREE from 'three';
+import { CAM, FRAME } from './camera.js';
+import { rng } from './lib.js';
+
+const D2R = THREE.MathUtils.degToRad;
+
+export function goboTexture(light, draw, { size = 1536, planeY = 0 } = {}) {
+  const src = document.createElement('canvas'); src.width = FRAME.w; src.height = FRAME.h;
+  draw(src.getContext('2d'), FRAME.w, FRAME.h);
+  const sd = src.getContext('2d').getImageData(0, 0, FRAME.w, FRAME.h).data;
+  const P = light.position.clone(), T = light.target.position.clone();
+  const f = T.clone().sub(P).normalize();
+  const right = new THREE.Vector3().crossVectors(f, new THREE.Vector3(0, 1, 0)).normalize(), up = new THREE.Vector3().crossVectors(right, f);
+  const th = Math.tan(light.angle);
+  const q = new THREE.Quaternion().setFromEuler(new THREE.Euler(D2R(CAM.pitchDeg), D2R(CAM.yawDeg), D2R(CAM.rollDeg), 'YXZ')).invert();
+  const F = (FRAME.h / 2) / Math.tan(D2R(CAM.vfov) / 2), cp = new THREE.Vector3(...CAM.pos), d = new THREE.Vector3(), c = new THREE.Vector3();
+  const out = document.createElement('canvas'); out.width = out.height = size;
+  const og = out.getContext('2d'), od = og.createImageData(size, size);
+  for (let j = 0; j < size; j++) for (let i = 0; i < size; i++) {
+    const x = 2 * (i + 0.5) / size - 1, y = 2 * (j + 0.5) / size - 1;
+    d.copy(f).addScaledVector(right, x * th).addScaledVector(up, y * th);
+    let v = 255;
+    if (d.y < -1e-4) {                       // ray from the light hits the plane y = planeY
+      const t = (planeY - P.y) / d.y;
+      c.set(P.x + d.x * t, planeY, P.z + d.z * t).sub(cp).applyQuaternion(q);   // world -> camera
+      const u = FRAME.w / 2 + F * c.x / -c.z, w = FRAME.h / 2 - F * c.y / -c.z;
+      const ux = Math.min(FRAME.w - 1, Math.max(0, Math.round(u))), uy = Math.min(FRAME.h - 1, Math.max(0, Math.round(w)));
+      v = sd[(uy * FRAME.w + ux) * 4];
+    }
+    const o = (j * size + i) * 4; od.data[o] = od.data[o + 1] = od.data[o + 2] = v; od.data[o + 3] = 255;
+  }
+  og.putImageData(od, 0, 0);
+  const t = new THREE.CanvasTexture(out); t.flipY = false; t.colorSpace = THREE.SRGBColorSpace; return t;
+}
+
+// One leaf/frond as ONE path segment set. Call several times between g.beginPath() and a single g.fill() so overlapping
+// leaflets union into one shadow (separate fills stack and read as dark blotches).
+export function frond(g, x, y, ang, len, wid, seed = 4) {
+  const r = rng(seed + Math.round(x + y)); g.save(); g.translate(x, y); g.rotate(ang);
+  g.moveTo(0, 0); g.quadraticCurveTo(len * 0.5, -len * 0.03, len, 0); g.quadraticCurveTo(len * 0.5, len * 0.03, 0, 0);
+  for (let i = 0; i < 6; i++) {
+    const t = 0.2 + i * 0.13, px = len * t, l = len * 0.36 * Math.sin(Math.PI * (0.1 + t * 0.8));
+    for (const s of [-1, 1]) { g.save(); g.translate(px, 0); g.rotate(s * (0.95 + r() * 0.2)); g.moveTo(l, 0); g.ellipse(l / 2, 0, l / 2, wid * (0.8 + r() * 0.4), 0, 0, 7); g.restore(); }
+  }
+  g.restore();
+}

package/scene-kit/starter/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Scene</title>
+<style>
+  html, body { margin: 0; height: 100%; overflow: hidden; background: #000; }
+  canvas#gl { position: fixed; inset: 0; width: 100%; height: 100%; display: block; }
+  /* #stage is the source image's pixel frame; main.js scales it to sit exactly over the contain-fitted canvas */
+  #stage { position: fixed; left: 0; top: 0; width: 1536px; height: 1024px; transform-origin: 0 0; pointer-events: none; }
+  #stage a, #stage button, #stage [data-hit] { pointer-events: auto; }
+  /* real page text goes here, positioned in source pixels, e.g.
+     <h1 style="position:absolute; left:56px; top:232px; font: 800 78px/0.9 'Chivo', sans-serif">TITLE</h1> */
+</style>
+<script type="importmap">{ "imports": { "three": "./vendor/three.module.js", "three/addons/": "./vendor/addons/" } }</script>
+</head>
+<body>
+<canvas id="gl"></canvas>
+<div id="stage"></div>
+<script type="module" src="./main.js"></script>
+</body>
+</html>

package/scene-kit/starter/lib.js

@@ -0,0 +1,84 @@
+// Small helpers that every scene needs. Keep scene code in scene.js and friends, not here.
+import * as THREE from 'three';
+
+export const rng = (seed) => { let s = seed >>> 0; return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296); };
+
+export function canvasTex(w, h, draw, { srgb = true, repeat = null } = {}) {
+  const c = document.createElement('canvas'); c.width = w; c.height = h;
+  draw(c.getContext('2d'), w, h);
+  const t = new THREE.CanvasTexture(c);
+  t.colorSpace = srgb ? THREE.SRGBColorSpace : THREE.NoColorSpace; t.anisotropy = 8;
+  if (repeat) { t.wrapS = t.wrapT = THREE.RepeatWrapping; t.repeat.set(...repeat); }
+  return t;
+}
+
+// Speckle + fibre grain over an already-filled canvas: paper, kraft, plaster, concrete.
+export function grain(g, w, h, { amount = 18, seed = 1 } = {}) {
+  const r = rng(seed), id = g.getImageData(0, 0, w, h), p = id.data;
+  for (let i = 0; i < p.length; i += 4) { const n = (r() - 0.5) * amount; p[i] += n; p[i + 1] += n; p[i + 2] += n; }
+  g.putImageData(id, 0, 0);
+}
+
+// Rounded-rectangle slab (book board, drive, card, phone, sleeve). Cap UVs run 0..1 over the face so a printed
+// texture lands where drawn: u = x/w + .5, v = y/h + .5. Face points +z.
+export function slabGeometry(w, h, t, r, bevel = Math.min(t * 0.3, 0.012)) {
+  const x = -w / 2, y = -h / 2, s = new THREE.Shape();
+  r = Math.min(r, w / 2 - 1e-3, h / 2 - 1e-3);
+  s.moveTo(x + r, y); s.lineTo(x + w - r, y); s.absarc(x + w - r, y + r, r, -Math.PI / 2, 0, false);
+  s.lineTo(x + w, y + h - r); s.absarc(x + w - r, y + h - r, r, 0, Math.PI / 2, false);
+  s.lineTo(x + r, y + h); s.absarc(x + r, y + h - r, r, Math.PI / 2, Math.PI, false);
+  s.lineTo(x, y + r); s.absarc(x + r, y + r, r, Math.PI, Math.PI * 1.5, false);
+  const g = new THREE.ExtrudeGeometry(s, { depth: t - 2 * bevel, bevelEnabled: true, bevelSize: bevel, bevelThickness: bevel, bevelSegments: 3, curveSegments: 12 });
+  g.translate(0, 0, -(t - 2 * bevel) / 2);
+  const pos = g.attributes.position, uv = g.attributes.uv, nor = g.attributes.normal;
+  for (let i = 0; i < pos.count; i++) if (Math.abs(nor.getZ(i)) > 0.9) uv.setXY(i, pos.getX(i) / w + 0.5, pos.getY(i) / h + 0.5);
+  return g;
+}
+
+// Soft dark blob under an object: cheap, always reads as "sitting on" the surface. Add to the scene at floor level.
+export function contactShadow(w, d, { opacity = 0.6, y = 0 } = {}) {
+  const c = document.createElement('canvas'); c.width = c.height = 128; const g = c.getContext('2d');
+  const gr = g.createRadialGradient(64, 64, 8, 64, 64, 64); gr.addColorStop(0, 'rgba(0,0,0,1)'); gr.addColorStop(0.6, 'rgba(0,0,0,0.55)'); gr.addColorStop(1, 'rgba(0,0,0,0)');
+  g.fillStyle = gr; g.fillRect(0, 0, 128, 128);
+  const m = new THREE.Mesh(new THREE.PlaneGeometry(w, d), new THREE.MeshBasicMaterial({ map: new THREE.CanvasTexture(c), transparent: true, depthWrite: false, opacity }));
+  m.rotation.x = -Math.PI / 2; m.position.y = y + 0.002; m.renderOrder = 2; return m;
+}
+
+// Blurred glossy floor reflection without Reflector: mirrored, jittered, fading copies of chosen meshes.
+// Call the returned function every frame (after actions move things). Floor must be y = floorY and must not write depth
+// (mat.depthWrite = false; mesh.renderOrder = -2). blur grows the smear; fade is the height at which it vanishes.
+const TAPS = [[0, 0], [0.9, 0.4], [-0.9, -0.4], [0.5, -0.9], [-0.5, 0.9], [1.4, -0.2], [-1.4, 0.2]];
+export function reflections(sources, scene, floorY, { opacity = 0.5, blur = 0.04, fade = 1.5 } = {}) {
+  const base = new THREE.Matrix4().makeTranslation(0, 2 * floorY, 0).multiply(new THREE.Matrix4().makeScale(1, -1, 1));
+  const perTap = 1 - Math.pow(1 - opacity, 1 / TAPS.length), pairs = [];
+  for (const src of sources) {
+    for (const [tx, tz] of TAPS) {
+      const mats = (Array.isArray(src.material) ? src.material : [src.material]).map((sm) => {
+        const c = sm.clone(); c.transparent = true; c.depthWrite = false; c.bumpMap = null;
+        c.onBeforeCompile = (sh) => {
+          sh.uniforms.uFloorY = { value: floorY }; sh.uniforms.uFade = { value: fade }; sh.uniforms.uOp = { value: perTap };
+          sh.vertexShader = sh.vertexShader.replace('#include <common>', '#include <common>\nvarying float vRefY;').replace('#include <begin_vertex>', '#include <begin_vertex>\nvRefY = (modelMatrix * vec4(transformed,1.0)).y;');
+          sh.fragmentShader = sh.fragmentShader.replace('#include <common>', '#include <common>\nvarying float vRefY; uniform float uFloorY; uniform float uFade; uniform float uOp;')
+            .replace('#include <dithering_fragment>', 'float dd = clamp((uFloorY - vRefY)/uFade, 0.0, 1.0);\n gl_FragColor.a *= uOp * pow(1.0 - dd, 1.6);\n#include <dithering_fragment>');
+        };
+        return c;
+      });
+      const ref = new THREE.Mesh(src.geometry, Array.isArray(src.material) ? mats : mats[0]);
+      ref.matrixAutoUpdate = false; ref.renderOrder = 5; ref.frustumCulled = false; scene.add(ref);
+      const sx = tx * blur, sz = tz * blur;
+      const shear = new THREE.Matrix4().set(1, -sx, 0, sx * floorY, 0, 1, 0, 0, 0, -sz, 1, sz * floorY, 0, 0, 0, 1);
+      pairs.push([src, ref, new THREE.Matrix4().multiplyMatrices(shear, base)]);
+    }
+  }
+  return () => { for (const [s, r, M] of pairs) { s.updateWorldMatrix(true, false); r.matrix.multiplyMatrices(M, s.matrixWorld); r.matrixWorldNeedsUpdate = true; } };
+}
+
+// Small procedural studio for glossy surfaces (vinyl, lacquer, glass, metal): dark room, one big soft window, a strip, a top card.
+// Pass renderer (buildScene receives it). Assign to material.envMap on ONLY the objects that should reflect it, so plaster,
+// paper and floor stay lit by the real lights. Move `win` and `strip` to where the source's highlights come from.
+export function studioEnv(renderer, { win = [4.5, 2.6, -1.2], strip = [-3.5, 2.0, -4] } = {}) {
+  const s = new THREE.Scene(); s.background = new THREE.Color(0x0b0a09);
+  const emit = (w, h, pos, k, tint = 0xffffff) => { const m = new THREE.Mesh(new THREE.PlaneGeometry(w, h), new THREE.MeshBasicMaterial({ color: new THREE.Color(tint).multiplyScalar(k), side: THREE.DoubleSide })); m.position.set(...pos); m.lookAt(0, 0, 0); s.add(m); };
+  emit(4.5, 3.4, win, 14, 0xfff1de); emit(6, 1.0, strip, 7, 0xf4efe8); emit(3, 1.6, [0, 4.5, 2], 3.5);
+  const pm = new THREE.PMREMGenerator(renderer), env = pm.fromScene(s, 0.02).texture; pm.dispose(); return env;
+}

package/scene-kit/starter/main.js

@@ -0,0 +1,78 @@
+// Harness: renderer, solved camera, contain-fit frame, orbit about the subject, click actions, capture contract.
+// You should not need to edit this beyond the renderer/tone-mapping settings. Scene work goes in scene.js.
+import * as THREE from 'three';
+import { FRAME, CAM, CLIP, PIVOT, ORBIT_LIMIT } from './camera.js';
+import { buildScene } from './scene.js';
+
+const canvas = document.getElementById('gl'), stage = document.getElementById('stage');
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, preserveDrawingBuffer: true });
+renderer.setPixelRatio(Math.min(devicePixelRatio || 1, 2));
+renderer.shadowMap.enabled = true; renderer.shadowMap.type = THREE.PCFShadowMap;  // PCFSoftShadowMap is removed in three 0.186;
+renderer.toneMapping = THREE.ACESFilmicToneMapping; renderer.toneMappingExposure = 1.0; renderer.outputColorSpace = THREE.SRGBColorSpace;
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(CAM.vfov, FRAME.w / FRAME.h, CLIP.near, CLIP.far);
+const built = buildScene(scene, renderer, camera);   // renderer: PMREM env maps (lib.studioEnv); camera: gobos, overlays
+
+// ---- camera: solved pose, orbit about PIVOT (azimuth about world y, elevation about the camera's right axis)
+const D2R = THREE.MathUtils.degToRad;
+const base = { pos: new THREE.Vector3(...CAM.pos), q: new THREE.Quaternion().setFromEuler(new THREE.Euler(D2R(CAM.pitchDeg), D2R(CAM.yawDeg), D2R(CAM.rollDeg), 'YXZ')) };
+const pivot = new THREE.Vector3(...PIVOT);
+let az = 0, el = 0, azT = 0, elT = 0;
+function applyCamera() {
+  const qy = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), THREE.MathUtils.degToRad(az));
+  const right = new THREE.Vector3(1, 0, 0).applyQuaternion(qy.clone().multiply(base.q));
+  const qe = new THREE.Quaternion().setFromAxisAngle(right, THREE.MathUtils.degToRad(el));
+  const rot = qe.clone().multiply(qy);
+  camera.position.copy(pivot).add(base.pos.clone().sub(pivot).applyQuaternion(rot));
+  camera.quaternion.copy(rot).multiply(base.q);
+  camera.updateMatrixWorld(true);
+}
+// contain-fit: the whole source frame stays visible at any window size; #stage (DOM text) is scaled to match
+function resize() {
+  const w = innerWidth, h = innerHeight; renderer.setSize(w, h, false);
+  const asp = w / h, fa = FRAME.w / FRAME.h, tv = Math.tan(THREE.MathUtils.degToRad(CAM.vfov) / 2);
+  camera.aspect = asp; camera.fov = THREE.MathUtils.radToDeg(2 * Math.atan(asp >= fa ? tv : tv * fa / asp)); camera.updateProjectionMatrix();
+  const s = Math.min(w / FRAME.w, h / FRAME.h);
+  stage.style.width = FRAME.w + 'px'; stage.style.height = FRAME.h + 'px';
+  stage.style.transform = `translate(${(w - FRAME.w * s) / 2}px, ${(h - FRAME.h * s) / 2}px) scale(${s})`;
+}
+addEventListener('resize', resize); resize();
+
+// ---- actions: click a picked mesh to toggle; buttons in #stage can call __scene.toggle(name)
+const actions = built.actions, state = {};
+for (const k of Object.keys(actions)) state[k] = { t: 0, target: 0 };
+const owner = new Map();
+for (const [k, a] of Object.entries(actions)) for (const m of a.pick || []) m.traverse((o) => o.isMesh && owner.set(o, k));
+const ray = new THREE.Raycaster(), ndc = new THREE.Vector2();
+const pick = (e) => { ndc.set((e.clientX / innerWidth) * 2 - 1, -((e.clientY / innerHeight) * 2 - 1)); ray.setFromCamera(ndc, camera); const h = ray.intersectObjects([...owner.keys()], false)[0]; return h && owner.get(h.object); };
+const toggle = (k) => { state[k].target = state[k].target > 0.5 ? 0 : 1; };
+let drag = null;
+addEventListener('pointerdown', (e) => { drag = { x: e.clientX, moved: 0, a: azT }; });
+addEventListener('pointermove', (e) => {
+  if (drag) { drag.moved = Math.max(drag.moved, Math.abs(e.clientX - drag.x)); azT = THREE.MathUtils.clamp(drag.a + (e.clientX - drag.x) * 0.08, -ORBIT_LIMIT, ORBIT_LIMIT); }
+  else canvas.style.cursor = pick(e) ? 'pointer' : 'default';
+});
+addEventListener('pointerup', (e) => { if (drag && drag.moved < 5) { const k = pick(e); if (k) toggle(k); } drag = null; });
+addEventListener('keydown', (e) => { if (e.key === 'ArrowLeft') azT = Math.max(-ORBIT_LIMIT, azT - 5); if (e.key === 'ArrowRight') azT = Math.min(ORBIT_LIMIT, azT + 5); });
+
+const ease = (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2);
+function frame(dt) {
+  az += (azT - az) * Math.min(1, dt * 8); el += (elT - el) * Math.min(1, dt * 8);
+  for (const [k, s] of Object.entries(state)) if (Math.abs(s.target - s.t) > 1e-3) { s.t += Math.sign(s.target - s.t) * Math.min(Math.abs(s.target - s.t), dt * 1.4); actions[k].apply(ease(s.t)); }
+  built.update(dt); applyCamera(); renderer.render(scene, camera);
+}
+let last = performance.now();
+(function loop(now) { frame(Math.min(0.05, (now - last) / 1000)); last = now; requestAnimationFrame(loop); })(last);
+
+// ---- capture contract (`12ui scene capture`)
+window.__scene = {
+  scene, camera, renderer, actions: Object.keys(actions), toggle,
+  setOrbit(a, e = 0) { az = azT = a; el = elT = e; },
+  setAction(k, t) { state[k].t = state[k].target = t; actions[k].apply(t); },
+  // debug/visibility: hide or show scene objects by name substring (name your groups). `12ui scene capture --hide a,b` uses this.
+  setVisible(pattern, on = true) { let n = 0; scene.traverse((o) => { if (o.name && o.name.includes(pattern)) { o.visible = on; n++; } }); return n; },
+  names() { const a = []; scene.traverse((o) => o.name && a.push(o.name)); return a; },
+  reset() { for (const k of Object.keys(actions)) this.setAction(k, 0); this.setOrbit(0, 0); },
+  render() { frame(0); },
+};
+document.fonts.ready.then(() => { window.__ready = true; });

package/scene-kit/starter/scene.js

@@ -0,0 +1,33 @@
+// Replace this demo with the recreation. Contract with main.js: build the scene, return
+// Name groups and key meshes (obj.name = 'vinyl') so `12ui scene capture --hide vinyl` can isolate them when debugging.
+//   { actions: { name: { label, apply(t) /* t in 0..1, pose ONE object */, pick: [meshes] } },
+//     update(dt) /* per-frame extras: reflections, animated bits */ }
+import * as THREE from 'three';
+import { canvasTex, grain, contactShadow } from './lib.js';
+
+export function buildScene(scene, renderer, camera) {   // renderer for PMREM (studioEnv), camera for gobos
+  scene.background = new THREE.Color(0x14110f);
+  const key = new THREE.DirectionalLight(0xfff1e0, 2.4); key.position.set(-3, 5, 4); key.castShadow = true;
+  key.shadow.mapSize.set(2048, 2048); key.shadow.bias = -0.0004; key.shadow.normalBias = 0.02;
+  Object.assign(key.shadow.camera, { left: -4, right: 4, top: 4, bottom: -4, near: 0.5, far: 20 });
+  scene.add(key, new THREE.HemisphereLight(0x9aa4b4, 0x30231a, 0.5));
+
+  const floor = new THREE.Mesh(new THREE.PlaneGeometry(40, 40), new THREE.MeshStandardMaterial({
+    color: 0xffffff, roughness: 0.9,
+    map: canvasTex(512, 512, (g, w, h) => { g.fillStyle = '#7d7268'; g.fillRect(0, 0, w, h); grain(g, w, h, { amount: 22 }); }, { repeat: [8, 8] }),
+  }));
+  floor.rotation.x = -Math.PI / 2; floor.receiveShadow = true; scene.add(floor);
+
+  // demo object: a lidded box with a hinge action
+  const body = new THREE.Mesh(new THREE.BoxGeometry(1.2, 0.5, 0.8), new THREE.MeshStandardMaterial({ color: 0x8a6a4a, roughness: 0.8 }));
+  body.position.y = 0.25; body.castShadow = body.receiveShadow = true; scene.add(body);
+  const hinge = new THREE.Group(); hinge.position.set(0, 0.5, -0.4); scene.add(hinge);
+  const lid = new THREE.Mesh(new THREE.BoxGeometry(1.2, 0.06, 0.8), new THREE.MeshStandardMaterial({ color: 0x9a7a58, roughness: 0.7 }));
+  lid.position.set(0, 0.03, 0.4); lid.castShadow = true; hinge.add(lid);
+  scene.add(contactShadow(2.2, 1.8, { opacity: 0.55 }));
+
+  return {
+    actions: { lid: { label: 'Open the lid', pick: [lid], apply: (t) => { hinge.rotation.x = -t * 1.9; } } },
+    update() {},
+  };
+}

package/scene-kit/vendor/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright © 2010-2026 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/scene-kit/vendor/addons/geometries/RoundedBoxGeometry.js

@@ -0,0 +1,216 @@
+import {
+	BoxGeometry,
+	Vector3
+} from 'three';
+
+const _tempNormal = new Vector3();
+
+function getUv( faceDirVector, normal, uvAxis, projectionAxis, radius, sideLength ) {
+
+	const totArcLength = 2 * Math.PI * radius / 4;
+
+	// length of the planes between the arcs on each axis
+	const centerLength = Math.max( sideLength - 2 * radius, 0 );
+	const halfArc = Math.PI / 4;
+
+	// Get the vector projected onto the Y plane
+	_tempNormal.copy( normal );
+	_tempNormal[ projectionAxis ] = 0;
+	_tempNormal.normalize();
+
+	// total amount of UV space alloted to a single arc
+	const arcUvRatio = 0.5 * totArcLength / ( totArcLength + centerLength );
+
+	// the distance along one arc the point is at
+	const arcAngleRatio = 1.0 - ( _tempNormal.angleTo( faceDirVector ) / halfArc );
+
+	if ( Math.sign( _tempNormal[ uvAxis ] ) === 1 ) {
+
+		return arcAngleRatio * arcUvRatio;
+
+	} else {
+
+		// total amount of UV space alloted to the plane between the arcs
+		const lenUv = centerLength / ( totArcLength + centerLength );
+		return lenUv + arcUvRatio + arcUvRatio * ( 1.0 - arcAngleRatio );
+
+	}
+
+}
+
+/**
+ * A special type of box geometry with rounded corners and edges.
+ *
+ * ```js
+ * const geometry = new RoundedBoxGeometry();
+ * const material = new THREE.MeshStandardMaterial( { color: 0x00ff00 } );
+ * const cube = new THREE.Mesh( geometry, material );
+ * scene.add( cube );
+ * ```
+ *
+ * @augments BoxGeometry
+ * @three_import import { RoundedBoxGeometry } from 'three/addons/geometries/RoundedBoxGeometry.js';
+ */
+class RoundedBoxGeometry extends BoxGeometry {
+
+	/**
+	 * Constructs a new rounded box geometry.
+	 *
+	 * @param {number} [width=1] - The width. That is, the length of the edges parallel to the X axis.
+	 * @param {number} [height=1] - The height. That is, the length of the edges parallel to the Y axis.
+	 * @param {number} [depth=1] - The depth. That is, the length of the edges parallel to the Z axis.
+	 * @param {number} [segments=2] - Number of segments that form the rounded corners.
+	 * @param {number} [radius=0.1] - The radius of the rounded corners.
+	 */
+	constructor( width = 1, height = 1, depth = 1, segments = 2, radius = 0.1 ) {
+
+		// calculate total segments needed &
+		// ensure it's odd so that we have a plane connecting the rounded corners
+		const totalSegments = segments * 2 + 1;
+
+		// ensure radius isn't bigger than shortest side
+		radius = Math.min( width / 2, height / 2, depth / 2, radius );
+
+		// start with a unit box geometry, its vertices will be modified to form the rounded box
+		super( 1, 1, 1, totalSegments, totalSegments, totalSegments );
+
+		this.type = 'RoundedBoxGeometry';
+
+		/**
+		 * Holds the constructor parameters that have been
+		 * used to generate the geometry. Any modification
+		 * after instantiation does not change the geometry.
+		 *
+		 * @type {Object}
+		 */
+		this.parameters = {
+			width: width,
+			height: height,
+			depth: depth,
+			segments: segments,
+			radius: radius,
+		};
+
+		// if totalSegments is 1, no rounding is needed - return regular box
+		if ( totalSegments === 1 ) return;
+
+		const geometry2 = this.toNonIndexed();
+
+		this.index = null;
+		this.attributes.position = geometry2.attributes.position;
+		this.attributes.normal = geometry2.attributes.normal;
+		this.attributes.uv = geometry2.attributes.uv;
+
+		//
+
+		const position = new Vector3();
+		const normal = new Vector3();
+
+		const box = new Vector3( width, height, depth ).divideScalar( 2 ).subScalar( radius );
+
+		const positions = this.attributes.position.array;
+		const normals = this.attributes.normal.array;
+		const uvs = this.attributes.uv.array;
+
+		const faceTris = positions.length / 6;
+		const faceDirVector = new Vector3();
+		const halfSegmentSize = 0.5 / totalSegments;
+
+		for ( let i = 0, j = 0; i < positions.length; i += 3, j += 2 ) {
+
+			position.fromArray( positions, i );
+			normal.copy( position );
+			normal.x -= Math.sign( normal.x ) * halfSegmentSize;
+			normal.y -= Math.sign( normal.y ) * halfSegmentSize;
+			normal.z -= Math.sign( normal.z ) * halfSegmentSize;
+			normal.normalize();
+
+			positions[ i + 0 ] = box.x * Math.sign( position.x ) + normal.x * radius;
+			positions[ i + 1 ] = box.y * Math.sign( position.y ) + normal.y * radius;
+			positions[ i + 2 ] = box.z * Math.sign( position.z ) + normal.z * radius;
+
+			normals[ i + 0 ] = normal.x;
+			normals[ i + 1 ] = normal.y;
+			normals[ i + 2 ] = normal.z;
+
+			const side = Math.floor( i / faceTris );
+
+			switch ( side ) {
+
+				case 0: // right
+
+					// generate UVs along Z then Y
+					faceDirVector.set( 1, 0, 0 );
+					uvs[ j + 0 ] = getUv( faceDirVector, normal, 'z', 'y', radius, depth );
+					uvs[ j + 1 ] = 1.0 - getUv( faceDirVector, normal, 'y', 'z', radius, height );
+					break;
+
+				case 1: // left
+
+					// generate UVs along Z then Y
+					faceDirVector.set( - 1, 0, 0 );
+					uvs[ j + 0 ] = 1.0 - getUv( faceDirVector, normal, 'z', 'y', radius, depth );
+					uvs[ j + 1 ] = 1.0 - getUv( faceDirVector, normal, 'y', 'z', radius, height );
+					break;
+
+				case 2: // top
+
+					// generate UVs along X then Z
+					faceDirVector.set( 0, 1, 0 );
+					uvs[ j + 0 ] = 1.0 - getUv( faceDirVector, normal, 'x', 'z', radius, width );
+					uvs[ j + 1 ] = getUv( faceDirVector, normal, 'z', 'x', radius, depth );
+					break;
+
+				case 3: // bottom
+
+					// generate UVs along X then Z
+					faceDirVector.set( 0, - 1, 0 );
+					uvs[ j + 0 ] = 1.0 - getUv( faceDirVector, normal, 'x', 'z', radius, width );
+					uvs[ j + 1 ] = 1.0 - getUv( faceDirVector, normal, 'z', 'x', radius, depth );
+					break;
+
+				case 4: // front
+
+					// generate UVs along X then Y
+					faceDirVector.set( 0, 0, 1 );
+					uvs[ j + 0 ] = 1.0 - getUv( faceDirVector, normal, 'x', 'y', radius, width );
+					uvs[ j + 1 ] = 1.0 - getUv( faceDirVector, normal, 'y', 'x', radius, height );
+					break;
+
+				case 5: // back
+
+					// generate UVs along X then Y
+					faceDirVector.set( 0, 0, - 1 );
+					uvs[ j + 0 ] = getUv( faceDirVector, normal, 'x', 'y', radius, width );
+					uvs[ j + 1 ] = 1.0 - getUv( faceDirVector, normal, 'y', 'x', radius, height );
+					break;
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Factory method for creating an instance of this class from the given
+	 * JSON object.
+	 *
+	 * @param {Object} data - A JSON object representing the serialized geometry.
+	 * @returns {RoundedBoxGeometry} A new instance.
+	 */
+	static fromJSON( data ) {
+
+		return new RoundedBoxGeometry(
+			data.width,
+			data.height,
+			data.depth,
+			data.segments,
+			data.radius
+		);
+
+	}
+
+
+}
+
+export { RoundedBoxGeometry };