@adobe/data-gpu 0.9.69

package/src/graphics/scene/model/gltf/pack-vertex-buffer.ts

@@ -0,0 +1,116 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Vec3 } from "@adobe/data/math";
+import { stride as vertexStride } from "../../../rendering/standard-vertex/layout.js";
+import { SKINNING_STRIDE } from "../../../rendering/skinning/skinning-attributes/layout.js";
+import { readAccessor } from "./accessor-view.js";
+import type { GltfAsset, GltfPrimitive } from "./gltf-schema.js";
+
+const FLOATS_PER_VERTEX = vertexStride / 4; // 48 / 4 = 12
+
+type MutVec3 = [number, number, number];
+
+export interface PackedPrimitive {
+    vertices: Float32Array;
+    /** Packed skinning attributes (uint32×4 joints, float32×4 weights). Null
+     *  for non-skinned primitives. Size = vertexCount × {@link SKINNING_STRIDE}. */
+    skinningAttributes: ArrayBuffer | null;
+    vertexCount: number;
+    boundsMin: Vec3;
+    boundsMax: Vec3;
+}
+
+/**
+ * Reads POSITION/NORMAL/TANGENT/TEXCOORD_0 from a primitive and interleaves
+ * them into the packed StandardVertex layout (48 bytes / vertex).
+ *
+ * If JOINTS_0 and WEIGHTS_0 are present, also packs them into a separate
+ * skinning attribute buffer with stride {@link SKINNING_STRIDE}.
+ *
+ * Vertices are kept in node-local space — no world transform is applied here.
+ */
+export function packPrimitiveVertices(
+    gltf: GltfAsset,
+    bin: ArrayBuffer,
+    prim: GltfPrimitive,
+): PackedPrimitive {
+    const positions = readAccessor(gltf, bin, prim.attributes.POSITION) as Float32Array;
+    // Normals and UVs are optional in glTF — fall back to defaults when absent.
+    // Skinned demo meshes (e.g. Fox) frequently omit NORMAL.
+    const normals = prim.attributes.NORMAL !== undefined
+        ? readAccessor(gltf, bin, prim.attributes.NORMAL) as Float32Array
+        : null;
+    const uvs = prim.attributes.TEXCOORD_0 !== undefined
+        ? readAccessor(gltf, bin, prim.attributes.TEXCOORD_0) as Float32Array
+        : null;
+    const tangents = prim.attributes.TANGENT !== undefined
+        ? readAccessor(gltf, bin, prim.attributes.TANGENT) as Float32Array
+        : null;
+    // glTF JOINTS_0 is unsigned byte vec4 or unsigned short vec4; readAccessor
+    // returns either Uint8Array or Uint16Array. WEIGHTS_0 is usually float32x4.
+    const joints = prim.attributes.JOINTS_0 !== undefined
+        ? readAccessor(gltf, bin, prim.attributes.JOINTS_0) as Uint8Array | Uint16Array | Uint32Array
+        : null;
+    const weights = prim.attributes.WEIGHTS_0 !== undefined
+        ? readAccessor(gltf, bin, prim.attributes.WEIGHTS_0) as Float32Array
+        : null;
+    const skinned = joints !== null && weights !== null;
+
+    const vertexCount = positions.length / 3;
+    const out = new Float32Array(vertexCount * FLOATS_PER_VERTEX);
+    const skin = skinned ? new ArrayBuffer(vertexCount * SKINNING_STRIDE) : null;
+    const skinJointsView = skin ? new Uint32Array(skin) : null;
+    const skinWeightsView = skin ? new Float32Array(skin) : null;
+
+    const min: MutVec3 = [Infinity, Infinity, Infinity];
+    const max: MutVec3 = [-Infinity, -Infinity, -Infinity];
+
+    for (let i = 0; i < vertexCount; i++) {
+        const px = positions[i * 3], py = positions[i * 3 + 1], pz = positions[i * 3 + 2];
+        const nx = normals ? normals[i * 3]     : 0;
+        const ny = normals ? normals[i * 3 + 1] : 1;
+        const nz = normals ? normals[i * 3 + 2] : 0;
+
+        let tx = 1, ty = 0, tz = 0, tw = 1;
+        if (tangents) {
+            tx = tangents[i * 4]; ty = tangents[i * 4 + 1];
+            tz = tangents[i * 4 + 2]; tw = tangents[i * 4 + 3];
+        }
+
+        const u = uvs ? uvs[i * 2] : 0;
+        const v = uvs ? uvs[i * 2 + 1] : 0;
+
+        const o = i * FLOATS_PER_VERTEX;
+        out[o + 0] = px;  out[o + 1] = py;  out[o + 2] = pz;
+        out[o + 3] = nx;  out[o + 4] = ny;  out[o + 5] = nz;
+        out[o + 6] = tx;  out[o + 7] = ty;  out[o + 8] = tz;  out[o + 9] = tw;
+        out[o + 10] = u; out[o + 11] = v;
+
+        if (skinned) {
+            // 32-byte stride / 4-byte words = 8 words per skinned vertex:
+            //   words 0..3: joints (u32 each)
+            //   words 4..7: weights (f32 each)
+            const so = i * 8;
+            skinJointsView![so + 0] = joints![i * 4 + 0];
+            skinJointsView![so + 1] = joints![i * 4 + 1];
+            skinJointsView![so + 2] = joints![i * 4 + 2];
+            skinJointsView![so + 3] = joints![i * 4 + 3];
+            skinWeightsView![so + 4] = weights![i * 4 + 0];
+            skinWeightsView![so + 5] = weights![i * 4 + 1];
+            skinWeightsView![so + 6] = weights![i * 4 + 2];
+            skinWeightsView![so + 7] = weights![i * 4 + 3];
+        }
+
+        if (px < min[0]) min[0] = px; if (px > max[0]) max[0] = px;
+        if (py < min[1]) min[1] = py; if (py > max[1]) max[1] = py;
+        if (pz < min[2]) min[2] = pz; if (pz > max[2]) max[2] = pz;
+    }
+
+    return {
+        vertices: out,
+        skinningAttributes: skin,
+        vertexCount,
+        boundsMin: min as Vec3,
+        boundsMax: max as Vec3,
+    };
+}

package/src/graphics/scene/model/gltf/parse-animations.ts

@@ -0,0 +1,66 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { AnimationTrack } from "../../../animation/animation-track/animation-track.js";
+import type { InterpolationMode } from "../../../animation/interpolation-mode/interpolation-mode.js";
+import { readAccessor } from "./accessor-view.js";
+import type { GltfAsset } from "./gltf-schema.js";
+
+export interface LoadedAnimation {
+    name?: string;
+    duration: number;
+    tracks: AnimationTrack[];
+}
+
+const PATH_TO_COMPONENT: Record<string, string> = {
+    translation: "position",
+    rotation: "rotation",
+    scale: "scale",
+};
+
+const INTERP_MAP: Record<string, InterpolationMode> = {
+    LINEAR: "linear",
+    STEP: "step",
+    CUBICSPLINE: "cubicSpline",
+};
+
+/**
+ * Parses glTF `animations[]` into clip data sized for our AnimationClip
+ * archetype. Each `track.targetIndex` is the **joint index** (position in
+ * `skin.joints`) — the skinning init system places joint entity IDs at those
+ * indices in the AnimationPlayer's `animationTargets` so the clip is portable
+ * across instances.
+ *
+ * Tracks targeting non-joint nodes or unsupported paths (e.g. morph weights)
+ * are skipped.
+ */
+export function parseGltfAnimations(
+    gltf: GltfAsset,
+    bin: ArrayBuffer,
+    jointNodeIndices: readonly number[],
+): LoadedAnimation[] {
+    if (!gltf.animations || gltf.animations.length === 0) return [];
+
+    const nodeToJoint = new Map<number, number>();
+    for (let j = 0; j < jointNodeIndices.length; j++) nodeToJoint.set(jointNodeIndices[j], j);
+
+    return gltf.animations.map(anim => {
+        const tracks: AnimationTrack[] = [];
+        let duration = 0;
+        for (const channel of anim.channels) {
+            const component = PATH_TO_COMPONENT[channel.target.path];
+            if (!component) continue; // skip morph "weights" etc.
+            const jointIdx = nodeToJoint.get(channel.target.node);
+            if (jointIdx === undefined) continue;
+
+            const sampler = anim.samplers[channel.sampler];
+            const times = new Float32Array(readAccessor(gltf, bin, sampler.input) as Float32Array);
+            const values = new Float32Array(readAccessor(gltf, bin, sampler.output) as Float32Array);
+            const interpolation = INTERP_MAP[sampler.interpolation ?? "LINEAR"] ?? "linear";
+
+            tracks.push({ targetIndex: jointIdx, component, times, values, interpolation });
+            const lastTime = times[times.length - 1] ?? 0;
+            if (lastTime > duration) duration = lastTime;
+        }
+        return { name: anim.name, duration, tracks };
+    });
+}

package/src/graphics/scene/model/gltf/parse-glb.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { GltfAsset } from "./gltf-schema.js";
+
+const MAGIC_GLTF = 0x46546c67; // "glTF"
+const CHUNK_JSON = 0x4e4f534a; // "JSON"
+const CHUNK_BIN = 0x004e4942; // "BIN\0"
+
+export interface ParsedGlb {
+    json: GltfAsset;
+    bin: ArrayBuffer;
+}
+
+export function parseGlb(buffer: ArrayBuffer): ParsedGlb {
+    if (buffer.byteLength < 12) {
+        throw new Error("GLB too short to contain header");
+    }
+    const view = new DataView(buffer);
+    const magic = view.getUint32(0, true);
+    if (magic !== MAGIC_GLTF) {
+        throw new Error(`Not a GLB file (magic = 0x${magic.toString(16)})`);
+    }
+    const version = view.getUint32(4, true);
+    if (version !== 2) {
+        throw new Error(`Unsupported GLB version ${version}`);
+    }
+
+    let offset = 12;
+    let json: GltfAsset | null = null;
+    let bin: ArrayBuffer | null = null;
+
+    while (offset < buffer.byteLength) {
+        const chunkLength = view.getUint32(offset, true);
+        const chunkType = view.getUint32(offset + 4, true);
+        const chunkStart = offset + 8;
+        const chunkEnd = chunkStart + chunkLength;
+
+        if (chunkType === CHUNK_JSON) {
+            const bytes = new Uint8Array(buffer, chunkStart, chunkLength);
+            const text = new TextDecoder().decode(bytes);
+            json = JSON.parse(text) as GltfAsset;
+        } else if (chunkType === CHUNK_BIN) {
+            bin = buffer.slice(chunkStart, chunkEnd);
+        }
+
+        offset = chunkEnd;
+    }
+
+    if (!json) throw new Error("GLB missing JSON chunk");
+    return { json, bin: bin ?? new ArrayBuffer(0) };
+}

package/src/graphics/scene/model/gltf/parse-skin.ts

@@ -0,0 +1,67 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Quat, Vec3 } from "@adobe/data/math";
+import { readAccessor } from "./accessor-view.js";
+import type { GltfAsset } from "./gltf-schema.js";
+
+export interface JointTemplate {
+    /** Local-space TRS in glTF node space (relative to joint parent). */
+    position: Vec3;
+    rotation: Quat;
+    scale: Vec3;
+    /** Index into the same joint-template array of this joint's parent joint,
+     *  or -1 when the joint is the rig root (parented to the Model entity). */
+    parentJointIndex: number;
+    /** Human-readable name from the glTF (debug aid). */
+    name?: string;
+}
+
+export interface LoadedSkin {
+    jointTemplate: JointTemplate[];
+    /** Flat N × 16 floats — bind-pose inverse matrices in joint order. */
+    inverseBindMatrices: Float32Array;
+}
+
+/**
+ * Builds a node-index → joint-index map and walks the glTF node hierarchy to
+ * find each joint's parent joint (or -1 if its parent is not itself a joint).
+ */
+function buildJointParentMap(gltf: GltfAsset, jointNodeIndices: readonly number[]): number[] {
+    const nodeToJoint = new Map<number, number>();
+    for (let j = 0; j < jointNodeIndices.length; j++) nodeToJoint.set(jointNodeIndices[j], j);
+
+    const nodeParent = new Map<number, number>(); // child node → parent node
+    for (let n = 0; n < (gltf.nodes ?? []).length; n++) {
+        for (const child of gltf.nodes![n].children ?? []) nodeParent.set(child, n);
+    }
+
+    return jointNodeIndices.map(nodeIdx => {
+        const parentNode = nodeParent.get(nodeIdx);
+        if (parentNode === undefined) return -1;
+        return nodeToJoint.get(parentNode) ?? -1;
+    });
+}
+
+export function parseGltfSkin(gltf: GltfAsset, bin: ArrayBuffer): LoadedSkin | null {
+    const skin = gltf.skins?.[0];
+    if (!skin) return null;
+
+    const parentIndices = buildJointParentMap(gltf, skin.joints);
+
+    const jointTemplate: JointTemplate[] = skin.joints.map((nodeIdx, jointIdx) => {
+        const node = gltf.nodes![nodeIdx];
+        return {
+            position: (node.translation ?? [0, 0, 0]) as Vec3,
+            rotation: (node.rotation ?? [0, 0, 0, 1]) as Quat,
+            scale: (node.scale ?? [1, 1, 1]) as Vec3,
+            parentJointIndex: parentIndices[jointIdx],
+            name: node.name,
+        };
+    });
+
+    const inverseBindMatrices = skin.inverseBindMatrices !== undefined
+        ? new Float32Array(readAccessor(gltf, bin, skin.inverseBindMatrices) as Float32Array)
+        : new Float32Array(skin.joints.length * 16).fill(0).map((_, i) => i % 17 === 0 ? 1 : 0);
+
+    return { jointTemplate, inverseBindMatrices };
+}

package/src/graphics/scene/model/model-loader-plugin.ts

@@ -0,0 +1,131 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import type { Aabb } from "@adobe/data/math";
+import { pbrCore } from "../../rendering/pbr-core-plugin.js";
+import { animation } from "../../animation/animation-plugin.js";
+import { core } from "../../../core/core-plugin.js";
+import { Model } from "./model.js";
+import { loadGltfPrimitives, type GpuPrimitiveData } from "./gltf/load-gltf-model.js";
+import type { LoadedAnimation } from "./gltf/parse-animations.js";
+import type { JointTemplate } from "./gltf/parse-skin.js";
+
+export interface LoadedArgs {
+    geometry: number;
+    bounds: Aabb;
+    primitives: GpuPrimitiveData[];
+    skinJointTemplate: JointTemplate[];
+    skinInverseBindMatrices: Float32Array | null;
+    animations: LoadedAnimation[];
+    collision: { positions: Float32Array; indices: Uint32Array } | null;
+    skinVertices: { positions: Float32Array; joints: Uint32Array; weights: Float32Array } | null;
+}
+
+/**
+ * modelLoader
+ *   query: Geometry-_bounds
+ *   read:
+ *     modelUrl
+ *   write:
+ *     _bounds: Aabb
+ *     _skinJointTemplate: JointTemplate[]
+ *     _skinInverseBindMatrices: Float32Array | null
+ *     _animationClipRefs: EntityId[]
+ *     _VisibleMaterial
+ *     _PbrPrimitive
+ *     AnimationClip                       // when the glTF carries animations
+ */
+export const modelLoader = Database.Plugin.create({
+    extends: Database.Plugin.combine(pbrCore, Model.plugin, core, animation),
+    components: {
+        _bounds: { default: null as Aabb | null },
+        _skinJointTemplate: { default: [] as JointTemplate[] },
+        _skinInverseBindMatrices: { default: null as Float32Array | null },
+        _animationClipRefs: { default: [] as number[] },
+        // CPU-retained model-space collision geometry (auto-collider source).
+        _cpuPositions: { default: null as Float32Array | null },
+        _cpuIndices: { default: null as Uint32Array | null },
+        // CPU-retained skin (mesh-bind positions + 4 joints + 4 weights per vertex),
+        // for fitting per-bone ragdoll capsules.
+        _cpuSkin: { default: null as { positions: Float32Array; joints: Uint32Array; weights: Float32Array } | null },
+    },
+    transactions: {
+        insertLoadedPrimitives(t, args: LoadedArgs) {
+            for (const p of args.primitives) {
+                const materialId = t.archetypes._VisibleMaterial.insert({
+                    ephemeral: true,
+                    _materialBindGroup: p.pbrMaterialBindGroup,
+                    _geometry: args.geometry,
+                });
+                t.archetypes._PbrPrimitive.insert({
+                    ephemeral: true,
+                    _geometry: args.geometry,
+                    _material: materialId,
+                    _vertexBuffer: p.pbrVertexBuffer,
+                    _skinVertexBuffer: p.pbrSkinVertexBuffer,
+                    _indexBuffer: p.pbrIndexBuffer,
+                    _indexCount: p.pbrIndexCount,
+                    _indexFormat: p.pbrIndexFormat,
+                    _nodeLocalMatrix: p.pbrNodeLocalMatrix,
+                });
+            }
+            const clipRefs: number[] = [];
+            for (const anim of args.animations) {
+                if (anim.tracks.length === 0) continue;
+                const clipId = t.archetypes.AnimationClip.insert({
+                    animationClipTracks: anim.tracks,
+                    animationClipDuration: anim.duration,
+                });
+                clipRefs.push(clipId);
+            }
+            t.update(args.geometry, {
+                _bounds: args.bounds,
+                _skinJointTemplate: args.skinJointTemplate,
+                _skinInverseBindMatrices: args.skinInverseBindMatrices,
+                _animationClipRefs: clipRefs,
+                _cpuPositions: args.collision?.positions ?? null,
+                _cpuIndices: args.collision?.indices ?? null,
+                _cpuSkin: args.skinVertices,
+            });
+        },
+    },
+    systems: {
+        modelLoadSystem: {
+            create: db => {
+                const inFlight = new Set<number>();
+                return () => {
+                    const { device } = db.store.resources;
+                    if (!device) return;
+                    for (const arch of db.store.queryArchetypes(["modelUrl"])) {
+                        const ids = arch.columns.id;
+                        const urls = arch.columns.modelUrl;
+                        for (let i = 0; i < arch.rowCount; i++) {
+                            const id = ids.get(i);
+                            if (inFlight.has(id)) continue;
+                            const url = urls.get(i);
+                            if (!url) continue;   // procedural geometries (shapes) carry no URL
+                            inFlight.add(id);
+                            loadGltfPrimitives(device, url)
+                                .then(loaded => {
+                                    db.transactions.insertLoadedPrimitives({
+                                        geometry: id,
+                                        bounds: loaded.bounds,
+                                        primitives: loaded.primitives,
+                                        skinJointTemplate: loaded.skin?.jointTemplate ?? [],
+                                        skinInverseBindMatrices: loaded.skin?.inverseBindMatrices ?? null,
+                                        animations: loaded.animations,
+                                        collision: loaded.collision,
+                                        skinVertices: loaded.skinVertices,
+                                    });
+                                })
+                                .catch(err => {
+                                    console.error("[modelLoader] Failed to load model", urls.get(i), err);
+                                });
+                        }
+                    }
+                };
+            },
+            schedule: { during: ["preUpdate"] },
+        },
+    },
+});

package/src/graphics/scene/model/model-plugin.ts

@@ -0,0 +1,46 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { Quat, type Vec3 } from "@adobe/data/math";
+import { Node } from "../node/node.js";
+
+/**
+ * Authored renderable scene. A `Geometry` is an asset identified by URL; a
+ * `Model` is a placed instance of a Geometry — a Node plus a reference to
+ * the Geometry it draws.
+ *
+ * Loading is performed by `modelLoader`, which reads the `modelUrl` and
+ * produces the GPU primitives the renderers consume.
+ */
+export const model = Database.Plugin.create({
+    extends: Node.plugin,
+    components: {
+        modelUrl: { type: "string" },
+        geometry: Entity.schema,
+    },
+    archetypes: {
+        Geometry: ["modelUrl"],
+        Model:    ["geometry", "position", "rotation", "scale", "visible", "parent"],
+    },
+    transactions: {
+        insertGeometry(t, args: { modelUrl: string }): number {
+            return t.archetypes.Geometry.insert({ modelUrl: args.modelUrl });
+        },
+        insertModel(t, args: {
+            geometry: number;
+            position?: Vec3;
+            rotation?: Quat;
+            scale?: Vec3;
+            parent?: number;
+        }): number {
+            return t.archetypes.Model.insert({
+                geometry: args.geometry,
+                position: args.position ?? [0, 0, 0],
+                rotation: args.rotation ?? Quat.identity,
+                scale:    args.scale    ?? [1, 1, 1],
+                visible:  true,
+                parent:   args.parent   ?? 0,
+            });
+        },
+    },
+});

package/src/graphics/scene/model/model.ts

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Entity } from "@adobe/data/ecs";
+import type { Node } from "../node/node.js";
+
+/**
+ * One row of the `Model` archetype — a placed instance of a Geometry. A
+ * Node (transform + visibility + parent) plus a reference to the Geometry
+ * the renderer should draw.
+ */
+export interface Model extends Node {
+    geometry: Entity;
+}
+
+export * as Model from "./public.js";

package/src/graphics/scene/model/public.ts

@@ -0,0 +1 @@
+export { model as plugin } from "./model-plugin.js";

package/src/graphics/scene/model/shape/convex-hull.test.ts

@@ -0,0 +1,72 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { hullFaces, convexHullMesh } from "./convex-hull.js";
+
+const f32 = (pts: number[][]) => new Float32Array(pts.flat());
+
+describe("convexHull", () => {
+    const px = (p: Float32Array, i: number) => [p[i * 3], p[i * 3 + 1], p[i * 3 + 2]] as const;
+
+    // every input point lies on the inner side of every face plane (within tol),
+    // and every face normal points away from the cloud centroid (outward).
+    const assertValidHull = (points: Float32Array) => {
+        const faces = hullFaces(points);
+        expect(faces).not.toBeNull();
+        const n = points.length / 3;
+        let gx = 0, gy = 0, gz = 0;
+        for (let i = 0; i < n; i++) { const [x, y, z] = px(points, i); gx += x; gy += y; gz += z; }
+        gx /= n; gy /= n; gz /= n;
+        for (const fc of faces!) {
+            const [ax, ay, az] = px(points, fc.a);
+            for (let p = 0; p < n; p++) { // no point strictly outside this face
+                const [x, y, z] = px(points, p);
+                expect(fc.nx * (x - ax) + fc.ny * (y - ay) + fc.nz * (z - az)).toBeLessThan(1e-4);
+            }
+            // outward: normal agrees with (face vertex − cloud centroid)
+            expect(fc.nx * (ax - gx) + fc.ny * (ay - gy) + fc.nz * (az - gz)).toBeGreaterThan(0);
+        }
+        return faces!;
+    };
+
+    it("tetrahedron → 4 faces", () => {
+        expect(assertValidHull(f32([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]])).length).toBe(4);
+    });
+
+    it("octahedron → 8 faces", () => {
+        expect(assertValidHull(f32([[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]])).length).toBe(8);
+    });
+
+    it("cube → a valid closed hull using all 8 corners", () => {
+        const cube = f32([[-1, -1, -1], [1, -1, -1], [1, 1, -1], [-1, 1, -1], [-1, -1, 1], [1, -1, 1], [1, 1, 1], [-1, 1, 1]]);
+        const faces = assertValidHull(cube);
+        const used = new Set<number>();
+        for (const f of faces) { used.add(f.a); used.add(f.b); used.add(f.c); }
+        expect(used.size).toBe(8); // every corner is a hull vertex
+        // V − E + F = 2 (Euler), with all triangular faces ⇒ E = 3F/2 ⇒ F = 12
+        expect(faces.length).toBe(12);
+    });
+
+    it("interior points are discarded", () => {
+        const withInterior = f32([
+            [-1, -1, -1], [1, -1, -1], [1, 1, -1], [-1, 1, -1], [-1, -1, 1], [1, -1, 1], [1, 1, 1], [-1, 1, 1],
+            [0, 0, 0], [0.5, 0.2, -0.3], // inside — must not appear on the hull
+        ]);
+        const faces = assertValidHull(withInterior);
+        const used = new Set<number>();
+        for (const f of faces) { used.add(f.a); used.add(f.b); used.add(f.c); }
+        expect(used.has(8)).toBe(false);
+        expect(used.has(9)).toBe(false);
+    });
+
+    it("degenerate clouds → null (< 4 points, or coplanar)", () => {
+        expect(hullFaces(f32([[0, 0, 0], [1, 0, 0], [0, 1, 0]]))).toBeNull();          // 3 points
+        expect(hullFaces(f32([[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]))).toBeNull(); // coplanar (z=0)
+    });
+
+    it("convexHullMesh emits flat-shaded StandardVertex triangles (12 floats/vert, 3 verts/tri)", () => {
+        const mesh = convexHullMesh(f32([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]]));
+        expect(mesh.indices.length).toBe(12);          // 4 faces × 3
+        expect(mesh.vertices.length).toBe(12 * 12);     // 12 verts × 12 floats
+    });
+});