3draft 26.11.1013 → 26.11.2005

package/dist/gpu.js

@@ -0,0 +1,319 @@
+// WebGPU renderer: flat-colored faces, one simple lit material, one global light.
+// It draws the same scene through the same camera as the SVG renderer, so picking,
+// the cross marks and the framing all stay valid. The pure helpers (viewProjection,
+// buildVertices) need no GPU and are unit tested; createGpu() needs a browser.
+import { dot, norm } from './vec.js';
+import { faceNormal } from './mesh.js';
+import { makeCamera } from './camera.js';
+const FLOATS = 9; // position(3) normal(3) color(3)
+/**
+ * Column-major 4x4 matrix (for WebGPU, z in 0..1) that maps world points exactly
+ * like camera.project(): the same pixels, plus a depth between near and far.
+ */
+export const viewProjection = (cam, near = 0.03, far = 1000) => {
+    const kk = cam.k / (cam.size / 2);
+    const row = (v, s) => [v[0] * s, v[1] * s, v[2] * s, -dot(v, cam.eye) * s];
+    const a = cam.ortho ? 1 / (far - near) : far / (far - near);
+    const zr = row(cam.f, a);
+    zr[3] -= a * near;
+    const rows = [row(cam.r, kk), row(cam.u, kk), zr, cam.ortho ? [0, 0, 0, 1] : row(cam.f, 1)];
+    const m = new Float32Array(16);
+    rows.forEach((r, i) => r.forEach((v, j) => (m[j * 4 + i] = v)));
+    return m;
+};
+const rgb = (color) => {
+    const h = String(color ?? '').replace('#', '');
+    const full = h.length === 3 ? [...h].map((c) => c + c).join('') : h;
+    if (!/^[0-9a-f]{6}$/i.test(full))
+        return [0.78, 0.78, 0.78];
+    return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255);
+};
+/** Triangle list for the GPU: flat face normals and face colors. Float32Array, 9 floats per vertex. */
+export const buildVertices = (mesh) => {
+    let tris = 0;
+    for (const f of mesh.faces)
+        tris += Math.max(0, f.v.length - 2);
+    const out = new Float32Array(tris * 3 * FLOATS);
+    let o = 0;
+    for (const face of mesh.faces) {
+        const pts = face.v.map((k) => mesh.positions[k]);
+        const n = norm(faceNormal(pts));
+        const c = rgb(face.color);
+        for (let j = 1; j < pts.length - 1; j++) {
+            for (const p of [pts[0], pts[j], pts[j + 1]]) {
+                out.set([...p, ...n, ...c], o);
+                o += FLOATS;
+            }
+        }
+    }
+    return out;
+};
+const INSTANCE_FLOATS = 15; // at(3) ex(3) ey(3) ez(3) color(3)
+/**
+ * Per-instance data for drawInstances: one entry { at, axes: [ex, ey, ez], color } per copy of a
+ * prototype mesh (modelled around the origin). Float32Array, 15 floats per instance.
+ */
+export const buildInstances = (items) => {
+    const out = new Float32Array(items.length * INSTANCE_FLOATS);
+    items.forEach((it, i) => out.set([...it.at, ...it.axes[0], ...it.axes[1], ...it.axes[2], ...rgb(it.color)], i * INSTANCE_FLOATS));
+    return out;
+};
+export const defaultLight = { direction: norm([0.5, 0.8, 0.6]), sky: [1, 0.97, 0.92], ground: [0.42, 0.38, 0.36] };
+export const defaultMaterial = { ambient: 0.62, diffuse: 0.78, specular: 0.2, shininess: 30 };
+const SHADER = /* wgsl */ `
+struct U {
+  vp : mat4x4<f32>,
+  light : vec4<f32>,   // xyz: direction towards the light
+  sky : vec4<f32>,
+  ground : vec4<f32>,
+  eye : vec4<f32>,
+  mat : vec4<f32>,     // ambient, diffuse, specular, shininess
+};
+@group(0) @binding(0) var<uniform> u : U;
+
+struct VIn { @location(0) pos : vec3<f32>, @location(1) nrm : vec3<f32>, @location(2) col : vec3<f32> };
+struct VOut {
+  @builtin(position) p : vec4<f32>,
+  @location(0) n : vec3<f32>,
+  @location(1) c : vec3<f32>,
+  @location(2) w : vec3<f32>,
+};
+
+@vertex fn vs(i : VIn) -> VOut {
+  var o : VOut;
+  o.p = u.vp * vec4<f32>(i.pos, 1.0);
+  o.n = i.nrm;
+  o.c = i.col;
+  o.w = i.pos;
+  return o;
+}
+
+struct IIn {
+  @location(0) pos : vec3<f32>, @location(1) nrm : vec3<f32>,
+  @location(3) at : vec3<f32>, @location(4) ex : vec3<f32>, @location(5) ey : vec3<f32>, @location(6) ez : vec3<f32>,
+  @location(7) col : vec3<f32>,
+};
+
+// the same prototype drawn many times: its frame (ex, ey, ez, scaled axes scale it) and position come per instance
+@vertex fn vsi(i : IIn) -> VOut {
+  var o : VOut;
+  let w = i.at + i.ex * i.pos.x + i.ey * i.pos.y + i.ez * i.pos.z;
+  o.p = u.vp * vec4<f32>(w, 1.0);
+  // the axes may be scaled (a thin long bar from the same prototype): normals follow the unit axes
+  o.n = normalize(i.ex) * i.nrm.x + normalize(i.ey) * i.nrm.y + normalize(i.ez) * i.nrm.z;
+  o.c = i.col;
+  o.w = w;
+  return o;
+}
+
+@fragment fn fs(i : VOut, @builtin(front_facing) front : bool) -> @location(0) vec4<f32> {
+  var n = normalize(i.n);
+  if (!front) { n = -n; }
+  let l = normalize(u.light.xyz);
+  let v = normalize(u.eye.xyz - i.w);
+  let hemi = mix(u.ground.rgb, u.sky.rgb, n.y * 0.5 + 0.5) * u.mat.x;
+  let diff = max(dot(n, l), 0.0) * u.mat.y;
+  let h = normalize(l + v);
+  let spec = pow(max(dot(n, h), 0.0), u.mat.w) * u.mat.z * step(0.0, dot(n, l));
+  let lit = i.c * (hemi + vec3<f32>(diff)) + vec3<f32>(spec);
+  return vec4<f32>(clamp(lit, vec3<f32>(0.0), vec3<f32>(1.0)), 1.0);
+}
+`;
+/**
+ * Sets up WebGPU on a canvas. Rejects when WebGPU is not available.
+ * Returns { render(mesh, view, options), destroy() }.
+ * render options: size (CSS px, the canvas is made size x size), fit, instances { mesh, data } (many copies of one
+ * prototype mesh, data from buildInstances; drawn after the mesh), background [r,g,b] 0..1,
+ * light { direction, sky, ground }, material { ambient, diffuse, specular, shininess }, dpr.
+ */
+export const createGpu = async (canvas, { sampleCount = 4 } = {}) => {
+    if (!globalThis.navigator?.gpu)
+        throw new Error('WebGPU is not available in this browser');
+    const adapter = await navigator.gpu.requestAdapter();
+    if (!adapter)
+        throw new Error('No WebGPU adapter found');
+    const device = await adapter.requestDevice();
+    device.addEventListener('uncapturederror', (e) => console.error('WebGPU:', e.error?.message ?? e));
+    device.lost.then((info) => console.error('WebGPU device lost:', info.reason, info.message));
+    const context = canvas.getContext('webgpu');
+    if (!context)
+        throw new Error('Could not get a WebGPU canvas context');
+    const format = navigator.gpu.getPreferredCanvasFormat();
+    context.configure({ device, format, alphaMode: 'opaque', });
+    const module = device.createShaderModule({ code: SHADER });
+    const meshLayout = {
+        arrayStride: FLOATS * 4,
+        attributes: [
+            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+            { shaderLocation: 1, offset: 12, format: 'float32x3' },
+            { shaderLocation: 2, offset: 24, format: 'float32x3' },
+        ],
+    };
+    const instanceLayout = {
+        arrayStride: INSTANCE_FLOATS * 4,
+        stepMode: 'instance',
+        attributes: [3, 4, 5, 6, 7].map((loc, k) => ({ shaderLocation: loc, offset: k * 12, format: 'float32x3' })),
+    };
+    const make = (entry, buffers) => device.createRenderPipeline({
+        layout: 'auto',
+        vertex: { module, entryPoint: entry, buffers },
+        fragment: { module, entryPoint: 'fs', targets: [{ format }] },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        depthStencil: { format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less' },
+        multisample: { count: sampleCount },
+    });
+    const pipeline = make('vs', [meshLayout]);
+    // the instanced pipeline reads position and normal only from the prototype (locations 0, 1)
+    const instPipeline = make('vsi', [{ ...meshLayout, attributes: meshLayout.attributes.slice(0, 2) }, instanceLayout]);
+    const uniforms = device.createBuffer({ size: 144, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    const bind = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: uniforms } }] });
+    const instBind = device.createBindGroup({ layout: instPipeline.getBindGroupLayout(0), entries: [{ binding: 0, resource: { buffer: uniforms } }] });
+    // Geometry that did not change since the last frame is not rebuilt or uploaded again.
+    let uploaded = null; // the mesh now in vertexBuffer
+    let vertexCount = 0;
+    let protoMesh = null;
+    let protoBuffer = null;
+    let protoCount = 0;
+    let instBuffer = null;
+    let instCapacity = 0;
+    let instData = null;
+    let instCount = 0;
+    let vertexBuffer = null;
+    let capacity = 0;
+    let px = 0;
+    let depth = null;
+    let color = null;
+    const targets = (n) => {
+        if (n === px)
+            return;
+        px = n;
+        canvas.width = n;
+        canvas.height = n;
+        depth?.destroy();
+        color?.destroy();
+        depth = device.createTexture({ size: [n, n], format: 'depth24plus', sampleCount, usage: GPUTextureUsage.RENDER_ATTACHMENT });
+        color = sampleCount > 1 ? device.createTexture({ size: [n, n], format, sampleCount, usage: GPUTextureUsage.RENDER_ATTACHMENT }) : null;
+    };
+    const draw = (mesh, view, { size = 400, fit, background = [0.98, 0.98, 0.97], light = {}, material = {}, dpr = globalThis.devicePixelRatio || 1, instances } = {}, readback = false) => {
+        const L = { ...defaultLight, ...light };
+        const M = { ...defaultMaterial, ...material };
+        const cam = makeCamera(view, mesh, size, fit);
+        targets(Math.max(1, Math.round(size * dpr)));
+        if (mesh !== uploaded) {
+            const verts = buildVertices(mesh);
+            if (verts.byteLength > capacity) {
+                vertexBuffer?.destroy();
+                capacity = Math.max(verts.byteLength, 4096);
+                vertexBuffer = device.createBuffer({ size: capacity, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+            }
+            if (verts.byteLength)
+                device.queue.writeBuffer(vertexBuffer, 0, verts);
+            vertexCount = verts.length / FLOATS;
+            uploaded = mesh;
+        }
+        if (instances?.mesh && instances.mesh !== protoMesh) {
+            const v = buildVertices(instances.mesh);
+            protoBuffer?.destroy();
+            protoBuffer = device.createBuffer({ size: Math.max(v.byteLength, 256), usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+            device.queue.writeBuffer(protoBuffer, 0, v);
+            protoCount = v.length / FLOATS;
+            protoMesh = instances.mesh;
+        }
+        if (instances?.data && instances.data !== instData) {
+            const d = instances.data;
+            if (d.byteLength > instCapacity) {
+                instBuffer?.destroy();
+                instCapacity = Math.max(d.byteLength, 4096);
+                instBuffer = device.createBuffer({ size: instCapacity, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+            }
+            if (d.byteLength)
+                device.queue.writeBuffer(instBuffer, 0, d);
+            instData = d;
+            instCount = d.length / INSTANCE_FLOATS;
+        }
+        if (!instances)
+            instCount = 0;
+        const u = new Float32Array(36);
+        u.set(viewProjection(cam), 0);
+        u.set([...(norm(L.direction)), 0], 16);
+        u.set([...L.sky, 0], 20);
+        u.set([...L.ground, 0], 24);
+        u.set([...cam.eye, 0], 28);
+        u.set([M.ambient, M.diffuse, M.specular, M.shininess], 32);
+        device.queue.writeBuffer(uniforms, 0, u);
+        const encoder = device.createCommandEncoder();
+        const offscreen = readback
+            ? device.createTexture({ size: [px, px], format, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC })
+            : null;
+        const target = (offscreen ?? context.getCurrentTexture()).createView();
+        const pass = encoder.beginRenderPass({
+            colorAttachments: [
+                {
+                    view: color ? color.createView() : target,
+                    resolveTarget: color ? target : undefined,
+                    clearValue: { r: background[0], g: background[1], b: background[2], a: 1 },
+                    loadOp: 'clear',
+                    storeOp: color ? 'discard' : 'store',
+                },
+            ],
+            depthStencilAttachment: { view: depth.createView(), depthClearValue: 1, depthLoadOp: 'clear', depthStoreOp: 'discard' },
+        });
+        if (vertexCount) {
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bind);
+            pass.setVertexBuffer(0, vertexBuffer);
+            pass.draw(vertexCount);
+        }
+        if (instCount && protoCount) {
+            pass.setPipeline(instPipeline);
+            pass.setBindGroup(0, instBind);
+            pass.setVertexBuffer(0, protoBuffer);
+            pass.setVertexBuffer(1, instBuffer);
+            pass.draw(protoCount, instCount);
+        }
+        pass.end();
+        if (!offscreen) {
+            device.queue.submit([encoder.finish()]);
+            return null;
+        }
+        const row = Math.ceil((px * 4) / 256) * 256;
+        const out = device.createBuffer({ size: row * px, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+        encoder.copyTextureToBuffer({ texture: offscreen }, { buffer: out, bytesPerRow: row }, [px, px]);
+        device.queue.submit([encoder.finish()]);
+        return out.mapAsync(GPUMapMode.READ).then(() => {
+            const raw = new Uint8Array(out.getMappedRange());
+            const data = new Uint8ClampedArray(px * px * 4);
+            const swap = format.startsWith('bgra');
+            for (let y = 0; y < px; y++) {
+                for (let x = 0; x < px; x++) {
+                    const i = y * row + x * 4;
+                    const o = (y * px + x) * 4;
+                    data[o] = raw[i + (swap ? 2 : 0)];
+                    data[o + 1] = raw[i + 1];
+                    data[o + 2] = raw[i + (swap ? 0 : 2)];
+                    data[o + 3] = 255;
+                }
+            }
+            out.unmap();
+            out.destroy();
+            offscreen.destroy();
+            return { width: px, height: px, data };
+        });
+    };
+    /** Draws a frame onto the canvas. */
+    const render = (mesh, view, options) => {
+        draw(mesh, view, options);
+    };
+    /** Draws a frame into an offscreen texture and reads it back: Promise<{ width, height, data: RGBA }>. */
+    const pixels = (mesh, view, options) => draw(mesh, view, options, true);
+    const destroy = () => {
+        vertexBuffer?.destroy();
+        protoBuffer?.destroy();
+        instBuffer?.destroy();
+        depth?.destroy();
+        color?.destroy();
+        uniforms.destroy();
+        device.destroy();
+    };
+    return { render, pixels, destroy, device, adapter };
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export declare const name: "3draft";
+export declare const version = "26.11.2005";
+export type { Vec3, Face, Mesh, Axes, ViewName, ViewSpec, Fit, Camera, Hit, Mark } from './types.js';
+export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
+export type { BoxOptions } from './mesh.js';
+export { validate } from './check.js';
+export type { Validation } from './check.js';
+export { extrudeFace, moveVertices } from './edit.js';
+export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
+export { pick, crosshair } from './pick.js';
+export { standOn } from './place.js';
+export type { StandOptions, Frame } from './place.js';
+export { paintOrder } from './order.js';
+export type { PaintItem } from './order.js';
+export { createGpu, viewProjection, buildVertices, buildInstances, defaultLight, defaultMaterial } from './gpu.js';
+export type { Gpu, GpuLight, GpuMaterial, GpuRenderOptions, Instance, Pixels } from './gpu.js';
+export { renderView, renderViews, renderSheet } from './svg.js';
+export type { RenderOptions } from './svg.js';
+export { displayVersion } from './version.js';
+export interface Info {
+    name: string;
+    version: string;
+    stage: 'pre-alpha';
+    goals: string[];
+}
+/** Short, machine-readable description of the current state of the package. */
+export declare const info: () => Info;
+export { initKernel } from './kernel.js';
+export type { Kernel } from './kernel.js';

package/{src → dist}/index.js

@@ -3,10 +3,8 @@
 // from four fixed cameras, plus surface picking (point, normal, distance) and
 // a target cross that lies on the surface under the cursor. No textures, no
 // shading yet.
-
 export const name = '3draft';
-export const version = '26.11.1013';
-
+export const version = '26.11.2005';
 export { box, extrude, merge, rotate, bounds, faceNormal, faceCenter } from './mesh.js';
 export { validate } from './check.js';
 export { extrudeFace, moveVertices } from './edit.js';
@@ -14,19 +12,19 @@ export { VIEW_ORDER, makeCamera, orbit, project, ray } from './camera.js';
 export { pick, crosshair } from './pick.js';
 export { standOn } from './place.js';
 export { paintOrder } from './order.js';
-export { createGpu, viewProjection, buildVertices, defaultLight, defaultMaterial } from './gpu.js';
+export { createGpu, viewProjection, buildVertices, buildInstances, defaultLight, defaultMaterial } from './gpu.js';
 export { renderView, renderViews, renderSheet } from './svg.js';
 export { displayVersion } from './version.js';
-
 /** Short, machine-readable description of the current state of the package. */
 export const info = () => ({
-  name,
-  version,
-  stage: 'pre-alpha',
-  goals: [
-    'single palette texture, UVs point at one texel per face',
-    'WASM core (HEXAW / Rust) behind a thin ABI',
-    'WebGPU renderer with WebGL2 fallback',
-    'deterministic SVG preview for AI feedback loops',
-  ],
+    name,
+    version,
+    stage: 'pre-alpha',
+    goals: [
+        'single palette texture, UVs point at one texel per face',
+        'WASM core (HEXAW / Rust) behind a thin ABI',
+        'WebGPU renderer with WebGL2 fallback',
+        'deterministic SVG preview for AI feedback loops',
+    ],
 });
+export { initKernel } from './kernel.js';

package/dist/kernel-bytes.d.ts

@@ -0,0 +1 @@
+export declare const KERNEL_BYTES = "AGFzbQEAAAABDwFgCnx8fHx8fH9/f38BfwMCAQAFBQEBAYACBxECBHBpY2sAAAZtZW1vcnkCAAr/AwH8AwIGfxh8QQAhCkF/IQ9EnHUAiDzkN34hEAJAA0AgCiAITg0BIAcgCkEEdGohCyALKAIAQRhsIAZqIQwgCygCBEEYbCAGaiENIAsoAghBGGwgBmohDgJAIAwrAwAhESAMKwMIIRIgDCsDECETIA0rAwAgEaEhFCANKwMIIBKhIRUgDSsDECAToSEWIA4rAwAgEaEhFyAOKwMIIBKhIRggDisDECAToSEZIAQgGaIgBSAYoqEhGiAFIBeiIAMgGaKhIRsgAyAYoiAEIBeioSEcIBQgGqIgFSAboqAgFiAcoqAhHSAdmUSV1iboCy4RPmMNACAJIB1EAAAAAAAAAABlcQ0ARAAAAAAAAPA/IB2jIR4gACARoSEfIAEgEqEhICACIBOhISEgHiAfIBqiICAgG6KgICEgHKKgoiEiICJEAAAAAAAAAABjICJEAAAAAAAA8D9kcg0AICAgFqIgISAVoqEhIyAhIBSiIB8gFqKhISQgHyAVoiAgIBSioSElIB4gAyAjoiAEICSioCAFICWioKIhJiAmRAAAAAAAAAAAYyAiICagRAAAAAAAAPA/ZHINACAeIBcgI6IgGCAkoqAgGSAloqCiIScgJ0SV1iboCy4RPmUNACAnIBBmDQAgJyEQIAsoAgwhDwsgCkEBaiEKDAALC0EAIBA5AwAgDws=";

package/dist/kernel-bytes.js

@@ -0,0 +1,2 @@
+// Generated by scripts/build-kernel.mjs from kernel/pick.hexaw. Do not edit.
+export const KERNEL_BYTES = 'AGFzbQEAAAABDwFgCnx8fHx8fH9/f38BfwMCAQAFBQEBAYACBxECBHBpY2sAAAZtZW1vcnkCAAr/AwH8AwIGfxh8QQAhCkF/IQ9EnHUAiDzkN34hEAJAA0AgCiAITg0BIAcgCkEEdGohCyALKAIAQRhsIAZqIQwgCygCBEEYbCAGaiENIAsoAghBGGwgBmohDgJAIAwrAwAhESAMKwMIIRIgDCsDECETIA0rAwAgEaEhFCANKwMIIBKhIRUgDSsDECAToSEWIA4rAwAgEaEhFyAOKwMIIBKhIRggDisDECAToSEZIAQgGaIgBSAYoqEhGiAFIBeiIAMgGaKhIRsgAyAYoiAEIBeioSEcIBQgGqIgFSAboqAgFiAcoqAhHSAdmUSV1iboCy4RPmMNACAJIB1EAAAAAAAAAABlcQ0ARAAAAAAAAPA/IB2jIR4gACARoSEfIAEgEqEhICACIBOhISEgHiAfIBqiICAgG6KgICEgHKKgoiEiICJEAAAAAAAAAABjICJEAAAAAAAA8D9kcg0AICAgFqIgISAVoqEhIyAhIBSiIB8gFqKhISQgHyAVoiAgIBSioSElIB4gAyAjoiAEICSioCAFICWioKIhJiAmRAAAAAAAAAAAYyAiICagRAAAAAAAAPA/ZHINACAeIBcgI6IgGCAkoqAgGSAloqCiIScgJ0SV1iboCy4RPmUNACAnIBBmDQAgJyEQIAsoAgwhDwsgCkEBaiEKDAALC0EAIBA5AwAgDws=';

package/dist/kernel.d.ts

@@ -0,0 +1,14 @@
+import type { Camera, Hit, Mesh } from './types.js';
+/**
+ * Starts the kernel. Resolves a picker { pick(mesh, cam, x, y, options), loaded } or rejects when
+ * WebAssembly is not available.
+ */
+/** The HEXAW kernel (kernel/pick.hexaw compiled to WebAssembly): ray picking with the same results as pick(). */
+export interface Kernel {
+    pick(mesh: Mesh, camera: Camera, x: number, y: number, options?: {
+        cull?: boolean;
+    }): Hit | null;
+    readonly loaded: Mesh | null;
+    instance: WebAssembly.Instance;
+}
+export declare const initKernel: () => Promise<Kernel>;

package/dist/kernel.js

@@ -0,0 +1,81 @@
+// The HEXAW kernel: ray picking in WebAssembly written in HEXAW (kernel/pick.hexaw).
+// The mesh is copied into the kernel's linear memory once, as long as it is the same object,
+// then every pick is one call that walks all triangles. Same answers as pick() in pick.ts.
+import { dot, norm, plus, times } from './vec.js';
+import { faceNormal } from './mesh.js';
+import { ray } from './camera.js';
+import { KERNEL_BYTES } from './kernel-bytes.js';
+const POS = 64; // vertices start here, 24 bytes each (f64 x y z)
+const decode = (b64) => {
+    if (typeof Buffer !== 'undefined')
+        return new Uint8Array(Buffer.from(b64, 'base64'));
+    const s = atob(b64);
+    return Uint8Array.from(s, (c) => c.charCodeAt(0));
+};
+export const initKernel = async () => {
+    if (typeof WebAssembly === 'undefined')
+        throw new Error('WebAssembly is not available');
+    const { instance } = (await WebAssembly.instantiate(decode(KERNEL_BYTES)));
+    const { pick: kPick, memory } = instance.exports;
+    let uploaded = null; // the mesh now in the kernel's memory
+    let triBase = 0;
+    let triCount = 0;
+    const upload = (mesh) => {
+        const nv = mesh.positions.length;
+        let nt = 0;
+        for (const f of mesh.faces)
+            nt += Math.max(0, f.v.length - 2);
+        triBase = (POS + nv * 24 + 7) & ~7;
+        const need = Math.ceil((triBase + nt * 16 + 8) / 65536);
+        const have = memory.buffer.byteLength / 65536;
+        if (need > have)
+            memory.grow(need - have);
+        // grow() detaches the old buffer, so the views are made after it
+        const f64 = new Float64Array(memory.buffer, POS, nv * 3);
+        for (let i = 0; i < nv; i++) {
+            const p = mesh.positions[i];
+            f64[i * 3] = p[0];
+            f64[i * 3 + 1] = p[1];
+            f64[i * 3 + 2] = p[2];
+        }
+        // faces are fanned into triangles (v0, vj, vj+1), each remembering its face number
+        const i32 = new Int32Array(memory.buffer, triBase, nt * 4);
+        let at = 0;
+        mesh.faces.forEach((f, face) => {
+            for (let j = 1; j < f.v.length - 1; j++) {
+                i32[at] = f.v[0];
+                i32[at + 1] = f.v[j];
+                i32[at + 2] = f.v[j + 1];
+                i32[at + 3] = face;
+                at += 4;
+            }
+        });
+        triCount = nt;
+        uploaded = mesh;
+    };
+    /**
+     * The nearest surface under panel pixel (x, y), or null: the same result as pick() in pick.js,
+     * { face, distance, point, normal, front, color }.
+     */
+    const pick = (mesh, cam, x, y, { cull = true } = {}) => {
+        if (mesh !== uploaded)
+            upload(mesh);
+        const { origin: o, dir: d } = ray(cam, x, y);
+        const face = kPick(o[0], o[1], o[2], d[0], d[1], d[2], POS, triBase, triCount, cull ? 1 : 0);
+        if (face < 0)
+            return null;
+        const distance = new Float64Array(memory.buffer, 0, 1)[0];
+        const f = mesh.faces[face];
+        const outward = norm(faceNormal(f.v.map((k) => mesh.positions[k])));
+        const front = dot(outward, d) < 0;
+        return {
+            face,
+            distance,
+            point: plus(o)(times(distance)(d)),
+            normal: front ? outward : times(-1)(outward),
+            front,
+            color: f.color,
+        };
+    };
+    return { pick, get loaded() { return uploaded; }, instance };
+};

package/dist/mesh.d.ts

@@ -0,0 +1,40 @@
+import type { Axes, Mesh, Vec3 } from './types.js';
+export interface BoxOptions {
+    size?: Vec3;
+    at?: Vec3;
+    color?: string;
+    /** Orthonormal local x/y/z axes (default: the world axes). */
+    axes?: Axes;
+}
+/** Box: 8 points, 12 edges, 6 quad faces. Axis-aligned unless `axes` turns it. */
+export declare const box: ({ size, at, color, axes }?: BoxOptions) => Mesh;
+/** Concatenate meshes into one, re-indexing the faces. */
+export declare const merge: (...meshes: Mesh[]) => Mesh;
+/** Bounding box center and bounding sphere radius around that center. */
+export declare const bounds: (mesh: Mesh) => {
+    center: Vec3;
+    radius: number;
+};
+/**
+ * Turntable rotation: yaw around Y first, then pitch around X (radians),
+ * both around `center` (default: bounding-box center). Faces are shared.
+ */
+export declare const rotate: (mesh: Mesh, { yaw, pitch }?: {
+    yaw?: number;
+    pitch?: number;
+}, center?: Vec3) => Mesh;
+/** Face normal (not normalized) by Newell's method; points CCW => outward. */
+export declare const faceNormal: (pts: Vec3[]) => Vec3;
+/** Mean of the face points. */
+export declare const faceCenter: (pts: Vec3[]) => Vec3;
+/**
+ * Prism from a convex footprint: `polygon` is [[x, z], ...] on the ground plane (any
+ * winding), it is extruded up from `y` by `height`. Faces: top, bottom, then one
+ * quad per footprint edge, all CCW from outside.
+ */
+export declare const extrude: ({ polygon, height, y, color }: {
+    polygon: [number, number][];
+    height?: number;
+    y?: number;
+    color?: string;
+}) => Mesh;

package/dist/mesh.js

@@ -0,0 +1,130 @@
+// Mesh = { positions: [[x, y, z], ...], faces: [{ v: [i, j, k, ...], color }] }
+// Faces are CCW when seen from outside. No normals, UVs or textures yet.
+import { add, len, scale, sub } from './vec.js';
+/** Box: 8 points, 12 edges, 6 quad faces. Axis-aligned unless `axes` turns it. */
+export const box = ({ size = [1, 1, 1], at = [0, 0, 0], color = '#c8c8c8', axes } = {}) => {
+    const [hx, hy, hz] = size.map((s) => s / 2);
+    // `axes` = [ex, ey, ez], an orthonormal right-handed frame (default: x, y, z)
+    const [ex, ey, ez] = axes ?? [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+    const at3 = (x, y, z) => add(at, add(add(scale(ex, x), scale(ey, y)), scale(ez, z)));
+    const positions = [
+        at3(-hx, -hy, -hz), // 0
+        at3(hx, -hy, -hz), // 1
+        at3(hx, hy, -hz), // 2
+        at3(-hx, hy, -hz), // 3
+        at3(-hx, -hy, hz), // 4
+        at3(hx, -hy, hz), // 5
+        at3(hx, hy, hz), // 6
+        at3(-hx, hy, hz), // 7
+    ];
+    const faces = [
+        [4, 5, 6, 7], // +z
+        [1, 0, 3, 2], // -z
+        [1, 2, 6, 5], // +x
+        [0, 4, 7, 3], // -x
+        [3, 7, 6, 2], // +y
+        [0, 1, 5, 4], // -y
+    ].map((v) => ({ v, color }));
+    return { positions, faces };
+};
+/** Concatenate meshes into one, re-indexing the faces. */
+export const merge = (...meshes) => {
+    const positions = [];
+    const faces = [];
+    for (const m of meshes) {
+        const offset = positions.length;
+        positions.push(...m.positions);
+        for (const f of m.faces)
+            faces.push({ ...f, v: f.v.map((i) => i + offset) });
+    }
+    return { positions, faces };
+};
+/** Bounding box center and bounding sphere radius around that center. */
+export const bounds = (mesh) => {
+    if (!mesh.positions.length)
+        return { center: [0, 0, 0], radius: 0 };
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (const p of mesh.positions) {
+        for (let a = 0; a < 3; a++) {
+            if (p[a] < min[a])
+                min[a] = p[a];
+            if (p[a] > max[a])
+                max[a] = p[a];
+        }
+    }
+    const center = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+    let radius = 0;
+    for (const p of mesh.positions)
+        radius = Math.max(radius, len(sub(p, center)));
+    return { center, radius };
+};
+/**
+ * Turntable rotation: yaw around Y first, then pitch around X (radians),
+ * both around `center` (default: bounding-box center). Faces are shared.
+ */
+export const rotate = (mesh, { yaw = 0, pitch = 0 } = {}, center = bounds(mesh).center) => {
+    const cy = Math.cos(yaw);
+    const sy = Math.sin(yaw);
+    const cp = Math.cos(pitch);
+    const sp = Math.sin(pitch);
+    const positions = mesh.positions.map((p) => {
+        const x = p[0] - center[0];
+        const y = p[1] - center[1];
+        const z = p[2] - center[2];
+        const x1 = cy * x + sy * z;
+        const z1 = -sy * x + cy * z;
+        return [x1 + center[0], cp * y - sp * z1 + center[1], sp * y + cp * z1 + center[2]];
+    });
+    return { positions, faces: mesh.faces };
+};
+/** Face normal (not normalized) by Newell's method; points CCW => outward. */
+export const faceNormal = (pts) => {
+    const n = [0, 0, 0];
+    for (let i = 0; i < pts.length; i++) {
+        const a = pts[i];
+        const b = pts[(i + 1) % pts.length];
+        n[0] += (a[1] - b[1]) * (a[2] + b[2]);
+        n[1] += (a[2] - b[2]) * (a[0] + b[0]);
+        n[2] += (a[0] - b[0]) * (a[1] + b[1]);
+    }
+    return n;
+};
+/** Mean of the face points. */
+export const faceCenter = (pts) => {
+    const s = pts.reduce((acc, p) => add(acc, p), [0, 0, 0]);
+    return [s[0] / pts.length, s[1] / pts.length, s[2] / pts.length];
+};
+/**
+ * Prism from a convex footprint: `polygon` is [[x, z], ...] on the ground plane (any
+ * winding), it is extruded up from `y` by `height`. Faces: top, bottom, then one
+ * quad per footprint edge, all CCW from outside.
+ */
+export const extrude = ({ polygon, height = 1, y = 0, color = '#c8c8c8' }) => {
+    if (!Array.isArray(polygon) || polygon.length < 3)
+        throw new Error('polygon needs at least 3 [x, z] points');
+    if (!(height > 0))
+        throw new Error('height must be positive');
+    let pts = polygon.map((p) => [p[0], p[1]]);
+    const n = pts.length;
+    const turn = (a, b, c) => (b[1] - a[1]) * (c[0] - b[0]) - (b[0] - a[0]) * (c[1] - b[1]); // y of edge cross, + is CCW from above
+    let area = 0;
+    for (let i = 0; i < n; i++)
+        area += pts[i][1] * pts[(i + 1) % n][0] - pts[i][0] * pts[(i + 1) % n][1];
+    if (Math.abs(area) < 1e-12)
+        throw new Error('polygon has no area');
+    if (area < 0)
+        pts = pts.reverse();
+    for (let i = 0; i < n; i++) {
+        if (turn(pts[i], pts[(i + 1) % n], pts[(i + 2) % n]) < -1e-12)
+            throw new Error('polygon must be convex');
+    }
+    const positions = [...pts.map(([x, z]) => [x, y, z]), ...pts.map(([x, z]) => [x, y + height, z])];
+    const ring = [...Array(n).keys()];
+    const faces = [
+        { v: ring.map((i) => n + i), color },
+        { v: [...ring].reverse(), color },
+        ...ring.map((i) => ({ v: [i, (i + 1) % n, n + ((i + 1) % n), n + i], color })),
+    ];
+    return { positions, faces };
+};