@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/glbCost.ts

@@ -0,0 +1,212 @@
+/** Bounded GLB byte admission shared by build validation and runtime entry.
+ * No product/schema graph is initialized to admit an equipment or skin model. */
+import type { AssetCost } from './product.ts';
+import { glbBuffers, prepareGlbBuffers } from './glbBuffers.ts';
+import { glbImageCost } from './glbImages.ts';
+import { visitGlbGeometry, type GlbVertex } from './glbTriangles.ts';
+import { projectedLayerCoverage, type OverdrawEstimate } from './overdraw.ts';
+
+/** Await compressed-buffer readiness at the asynchronous model boundary. */
+export function prepareGlbCost(): Promise<void> { return prepareGlbBuffers(); }
+
+const MAX_BYTES = 25_000_000;
+const MAX_ELEMENTS = 4_000_000;
+function requireRange(bytes: Uint8Array, offset: number, size: number): void {
+  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(size) || offset < 0 || size < 0 || offset + size > bytes.length) throw new Error('asset truncated or oversized');
+}
+function object(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('asset object required');
+  return value as Record<string, unknown>;
+}
+function list(value: unknown): unknown[] { if (!Array.isArray(value) || value.length > 10_000) throw new Error('asset array required or oversized'); return value; }
+function count(value: unknown, max = MAX_ELEMENTS): number { if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > max) throw new Error('asset count outside cap'); return value; }
+function json(bytes: Uint8Array): unknown { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+
+export function parseGlbData(bytes: Uint8Array, visit?: (triangle: readonly GlbVertex[]) => void, estimate?: OverdrawEstimate): AssetCost {
+  requireRange(bytes, 0, 20); const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.length > MAX_BYTES || view.getUint32(0, true) !== 0x46546c67 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.length) throw new Error('invalid GLB header');
+  const length = view.getUint32(12, true); requireRange(bytes, 20, length);
+  if (length > 2_000_000 || length % 4 !== 0 || view.getUint32(16, true) !== 0x4e4f534a) throw new Error('invalid GLB JSON chunk');
+  const doc = object(json(bytes.subarray(20, 20 + length))); const asset = object(doc['asset']);
+  if (asset['version'] !== '2.0') throw new Error('GLB asset version');
+  let binaryBytes = 0;
+  if (20 + length < bytes.length) {
+    requireRange(bytes, 20 + length, 8); const n = view.getUint32(20 + length, true);
+    if (view.getUint32(24 + length, true) !== 0x004e4942 || n % 4 !== 0 || 28 + length + n !== bytes.length) throw new Error('invalid GLB binary chunk');
+    binaryBytes = n;
+  }
+  const data = glbBuffers(doc, bytes.subarray(28 + length, 28 + length + binaryBytes)), views = data.views;
+  const accessorBytes = new DataView(data.bytes.buffer, data.bytes.byteOffset, data.bytes.byteLength);
+  let gpu = 0, elements = 0;
+  const accessors = list(doc['accessors'] ?? []).map((entry) => {
+    const a = object(entry), components: Record<string, number> = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT4: 16, MAT3: 9, MAT2: 4 };
+    const widths: Record<string, number> = { '5120': 1, '5121': 1, '5122': 2, '5123': 2, '5125': 4, '5126': 4 };
+    const width = widths[String(a['componentType'])], dimension = components[String(a['type'])], n = count(a['count']);
+    if (width === undefined || dimension === undefined || a['sparse'] !== undefined) throw new Error('unsupported GLB accessor');
+    elements += n * dimension;
+    if (elements > MAX_ELEMENTS * 16) throw new Error('GLB aggregate accessor cap');
+    const bufferView = views[count(a['bufferView'], 10_000)]; if (bufferView === undefined) throw new Error('missing GLB accessor view');
+    const size = width * dimension, stride = count(bufferView['byteStride'] ?? size, 252), offset = count(a['byteOffset'] ?? 0, MAX_BYTES);
+    if (stride < size || offset + (n === 0 ? 0 : (n - 1) * stride + size) > count(bufferView['byteLength'], MAX_BYTES)) throw new Error('GLB accessor outside view');
+    gpu += n * size; return { n, type: a['type'], component: a['componentType'], offset: count(bufferView['byteOffset'] ?? 0, MAX_BYTES) + offset, stride, width, dimension, normalized: a['normalized'] === true };
+  });
+  const read = (a: typeof accessors[number], row: number, component: number): number => {
+    const at = a.offset + row * a.stride + component * a.width;
+    switch (a.component) {
+      case 5120: return accessorBytes.getInt8(at);
+      case 5121: return accessorBytes.getUint8(at);
+      case 5122: return accessorBytes.getInt16(at, true);
+      case 5123: return accessorBytes.getUint16(at, true);
+      case 5125: return accessorBytes.getUint32(at, true);
+      case 5126: return accessorBytes.getFloat32(at, true);
+      default: throw new Error('unsupported GLB rig component');
+    }
+  };
+  const checkedPositions = new Set<number>(), maximumIndices = new Map<number, number>();
+  const materials = list(doc['materials'] ?? []).map(object);
+  const imageCost = glbImageCost(doc, views, data.bytes); gpu += imageCost.gpu;
+  const meshCosts = list(doc['meshes'] ?? []).map((mesh) => {
+    let triangles = 0, draws = 0, layers = 0, blendedLayers = 0, maskedLayers = 0;
+    for (const primitive of list(object(mesh)['primitives'])) {
+      const p = object(primitive); if ((p['mode'] ?? 4) !== 4 || p['extensions'] !== undefined) throw new Error('unsupported GLB primitive');
+      const attributes = object(p['attributes']);
+      const positionId = count(attributes['POSITION'], 10_000), position = accessors[positionId];
+      const indexId = count(p['indices'] ?? attributes['POSITION'], 10_000), index = accessors[indexId];
+      // RM8.1: float32, or Int16 on its node's grid (KHR_mesh_quantization, normalized or not; the node dequantizes it)
+      if (position === undefined || position.type !== 'VEC3' || !(position.component === 5126 || position.component === 5122) || index === undefined || index.n % 3 !== 0) throw new Error('invalid GLB triangle accessor');
+      if (!checkedPositions.has(positionId)) {
+        for (let i = 0; i < position.n; i++) for (let c = 0; c < 3; c++) if (!Number.isFinite(read(position, i, c))) throw new Error('nonfinite GLB position');
+        checkedPositions.add(positionId);
+      }
+      if (p['indices'] !== undefined) {
+        if (index.type !== 'SCALAR' || ![5121, 5123, 5125].includes(Number(index.component))) throw new Error('invalid GLB index encoding');
+        let maximum = maximumIndices.get(indexId);
+        if (maximum === undefined) { maximum = -1; for (let i = 0; i < index.n; i++) maximum = Math.max(maximum, read(index, i, 0)); maximumIndices.set(indexId, maximum); }
+        if (maximum >= position.n) throw new Error('GLB index outside positions');
+      }
+      triangles += index.n / 3; draws++;
+      const material = p['material'] === undefined ? undefined : materials[count(p['material'], 10_000)];
+      if (p['material'] !== undefined && material === undefined) throw new Error('missing GLB material');
+      const alpha = material?.['alphaMode'] ?? 'OPAQUE';
+      if (typeof alpha !== 'string' || !['OPAQUE', 'MASK', 'BLEND'].includes(alpha)) throw new Error('unsupported GLB alpha mode');
+      if (estimate !== undefined) {
+        const vertices = position, indices = index;
+        const primitiveGeometry = function* primitiveGeometry(): Generator<readonly GlbVertex[]> {
+          for (let i = 0; i < indices.n; i += 3) yield Array.from({ length: 3 }, (_, offset) => {
+            const row = p['indices'] === undefined ? i + offset : read(indices, i + offset, 0);
+            return { x: read(vertices, row, 0), y: read(vertices, row, 1), z: read(vertices, row, 2) };
+          });
+        };
+        const coverage = projectedLayerCoverage(primitiveGeometry()); layers += coverage;
+        if (alpha === 'BLEND') blendedLayers += coverage; if (alpha === 'MASK') maskedLayers += coverage;
+      }
+      for (const id of Object.values(attributes)) if (accessors[count(id, 10_000)] === undefined) throw new Error('missing GLB attribute');
+    }
+    return { triangles, draws, layers, blendedLayers, maskedLayers };
+  });
+  let triangles = 0, draws = 0, instanceCpu = 0;
+  const nodes = list(doc['nodes'] ?? []).map(object);
+  for (const node of nodes) {
+    if (node['mesh'] === undefined) continue;
+    const cost = meshCosts[count(node['mesh'], 10_000)]; if (cost === undefined) throw new Error('missing GLB mesh');
+    let instances = 1;
+    if (node['extensions'] !== undefined) {
+      const extensions = object(node['extensions']);
+      if (Object.keys(extensions).some((key) => key !== 'EXT_mesh_gpu_instancing')) throw new Error('unsupported GLB node extension');
+      const attributes = object(object(extensions['EXT_mesh_gpu_instancing'])['attributes']);
+      if (attributes['_MATRIX'] !== undefined && ['TRANSLATION', 'ROTATION', 'SCALE'].some(key => attributes[key] !== undefined)) throw new Error('GLB exact matrix cannot mix with TRS');
+      let size: number | undefined;
+      for (const [key, id] of Object.entries(attributes)) {
+        const normalized = object(list(doc['accessors'])[count(id, 10_000)])['normalized'];
+        const a = accessors[count(id, 10_000)], dimension = key === '_MATRIX' ? 16 : key === 'ROTATION' ? 4 : 3;
+        if (!['TRANSLATION', 'ROTATION', 'SCALE', '_MATRIX', '_COLOR_0'].includes(key) || a === undefined || a.component !== 5126 || a.dimension !== dimension || (key === '_MATRIX' && (a.type !== 'MAT4' || (normalized !== undefined && normalized !== false) || a.stride !== 64 || a.offset % 4 !== 0)) || (key === '_COLOR_0' && (a.type !== 'VEC3' || (normalized !== undefined && normalized !== false) || a.stride !== 12 || a.offset % 4 !== 0)) || a.n === 0 || a.n > 10_000 || (size !== undefined && a.n !== size)) throw new Error('invalid GLB instance attribute');
+        size = a.n;
+        for (let i = 0; i < a.n; i++) {
+          let norm = 0;
+          for (let c = 0; c < dimension; c++) {
+            const n = read(a, i, c);
+            if (!Number.isFinite(n) || (key === 'SCALE' && (n <= 0 || n > 1000)) || (key === '_COLOR_0' && (n < 0 || n > 1))) throw new Error('invalid GLB instance transform');
+            norm += n * n;
+          }
+          if (key === '_MATRIX') {
+            const m = (c: number): number => read(a, i, c);
+            if (m(3) !== 0 || m(7) !== 0 || m(11) !== 0 || m(15) !== 1) throw new Error('invalid GLB affine instance matrix');
+            for (const c of [0, 4, 8]) if (m(c) * m(c) + m(c + 1) * m(c + 1) + m(c + 2) * m(c + 2) > 1_000_000.25) throw new Error('invalid GLB instance matrix scale');
+            const determinant = m(0) * (m(5) * m(10) - m(6) * m(9)) - m(4) * (m(1) * m(10) - m(2) * m(9)) + m(8) * (m(1) * m(6) - m(2) * m(5));
+            if (determinant <= 0) throw new Error('invalid GLB instance matrix determinant');
+          }
+          if (key === 'ROTATION' && Math.abs(norm - 1) > 1e-4) throw new Error('invalid GLB instance quaternion');
+        }
+      }
+      if (size === undefined) throw new Error('empty GLB instance list');
+      instances = size; gpu += size * 64; instanceCpu += size * 64;
+    }
+    const shadow = node['extras'] === undefined ? true : object(node['extras'])['castShadow'] ?? true;
+    if (typeof shadow !== 'boolean') throw new Error('invalid GLB shadow flag');
+    triangles += cost.triangles * instances; draws += cost.draws * (shadow ? 2 : 1);
+    if (estimate !== undefined) { estimate.layers += cost.layers * instances; estimate.blendedLayers += cost.blendedLayers * instances; estimate.maskedLayers += cost.maskedLayers * instances; }
+  }
+  // Skins and clips are admitted before GLTFLoader allocates skeletons or animation tracks.
+  const nodeIndex = (value: unknown): number => { const id = count(value, 10000); if (nodes[id] === undefined) throw new Error('missing GLB rig node'); return id; };
+  const parents = new Map<number, number>();
+  nodes.forEach((node, id) => {
+    for (const child of list(node['children'] ?? [])) { const key = nodeIndex(child); if (key === id || parents.has(key)) throw new Error('GLB node hierarchy'); parents.set(key, id); }
+    for (const [key, size] of [['translation', 3], ['rotation', 4], ['scale', 3], ['matrix', 16]] as const) if (node[key] !== undefined) {
+      const values = list(node[key]); if (values.length !== size || values.some((n) => typeof n !== 'number' || !Number.isFinite(n) || Math.abs(n) > 100000)) throw new Error('GLB node transform');
+      if (key === 'rotation' && Math.abs(values.reduce<number>((sum, n) => sum + Number(n) ** 2, 0) - 1) > 1e-4) throw new Error('GLB node quaternion');
+    }
+    if (node['matrix'] !== undefined && ['translation', 'rotation', 'scale'].some((key) => node[key] !== undefined)) throw new Error('GLB matrix and TRS');
+  });
+  for (let id = 0; id < nodes.length; id++) { const seen = new Set<number>(); let parent: number | undefined = id; while (parent !== undefined) { if (seen.has(parent) || seen.size > 128) throw new Error('GLB node cycle or depth'); seen.add(parent); parent = parents.get(parent); } }
+  let rigCpu = 0;
+  const skins = list(doc['skins'] ?? []).map((value) => {
+    const skin = object(value), joints = list(skin['joints']).map(nodeIndex);
+    if (joints.length === 0 || joints.length > 128 || new Set(joints).size !== joints.length) throw new Error('GLB skin joints cap');
+    if (skin['skeleton'] !== undefined) nodeIndex(skin['skeleton']);
+    if (skin['inverseBindMatrices'] !== undefined) {
+      const a = accessors[count(skin['inverseBindMatrices'], 10000)]; if (a === undefined || a.type !== 'MAT4' || a.component !== 5126 || a.n !== joints.length) throw new Error('GLB inverse bind shape');
+      for (let i = 0; i < a.n; i++) for (let c = 0; c < 16; c++) if (!Number.isFinite(read(a, i, c))) throw new Error('GLB inverse bind value');
+    }
+    const textureSize = Math.max(4, Math.ceil(Math.sqrt(joints.length * 4) / 4) * 4);
+    gpu += textureSize * textureSize * 16; rigCpu += textureSize * textureSize * 16 + joints.length * 64;
+    return joints;
+  });
+  if (skins.length > 128) throw new Error('GLB skins cap');
+  const meshes = list(doc['meshes'] ?? []).map(object);
+  for (const node of nodes) if (node['skin'] !== undefined) {
+    const joints = skins[count(node['skin'], 128)], mesh = meshes[count(node['mesh'], 10000)]; if (joints === undefined || mesh === undefined || node['extensions'] !== undefined) throw new Error('GLB skin binding');
+    for (const primitive of list(mesh['primitives'])) {
+      const attrs = object(object(primitive)['attributes']), position = accessors[count(attrs['POSITION'], 10000)], indices = accessors[count(attrs['JOINTS_0'], 10000)], weights = accessors[count(attrs['WEIGHTS_0'], 10000)];
+      if (indices === undefined || weights === undefined || position === undefined || indices.type !== 'VEC4' || weights.type !== 'VEC4' || indices.n !== position.n || weights.n !== position.n || ![5121, 5123].includes(Number(indices.component)) || !(weights.component === 5126 || ([5121, 5123].includes(Number(weights.component)) && weights.normalized))) throw new Error('GLB skin weights shape');
+      for (let i = 0; i < indices.n; i++) { let total = 0; for (let c = 0; c < 4; c++) { const joint = read(indices, i, c), raw = read(weights, i, c), weight = weights.normalized ? raw / (weights.component === 5121 ? 255 : 65535) : raw;
+        if (joint >= joints.length || !Number.isFinite(weight) || weight < 0 || weight > 1) throw new Error('GLB skin weight value'); total += weight;
+      } if (Math.abs(total - 1) > 1e-4) throw new Error('GLB skin weights must sum to one'); }
+    }
+  }
+  const animations = list(doc['animations'] ?? []); if (animations.length > 32) throw new Error('GLB clips cap');
+  for (const value of animations) {
+    const animation = object(value), samplers = list(animation['samplers']).map(object), channels = list(animation['channels']), bindings = new Set<string>();
+    if (typeof animation['name'] !== 'string' || !/^[a-z][a-z0-9.:-]{0,127}$/u.test(animation['name'])) throw new Error('GLB clip name');
+    if (samplers.length === 0 || samplers.length > 512 || channels.length === 0 || channels.length > 512) throw new Error('GLB clip channels cap');
+    for (const entry of channels) {
+      const channel = object(entry), target = object(channel['target']), targetId = nodeIndex(target['node']), path = target['path'], sampler = samplers[count(channel['sampler'], 512)];
+      if (sampler === undefined || !['translation', 'rotation', 'scale'].includes(String(path)) || nodes[targetId]?.['matrix'] !== undefined || bindings.has(`${targetId}/${String(path)}`)) throw new Error('GLB clip target'); bindings.add(`${targetId}/${String(path)}`);
+      const input = accessors[count(sampler['input'], 10000)], output = accessors[count(sampler['output'], 10000)], width = path === 'rotation' ? 4 : 3;
+      if ((sampler['interpolation'] !== undefined && typeof sampler['interpolation'] !== 'string') || !['LINEAR', 'STEP'].includes(typeof sampler['interpolation'] === 'string' ? sampler['interpolation'] : 'LINEAR') || input === undefined || output === undefined || input.type !== 'SCALAR' || input.component !== 5126 || input.n < 2 || input.n > 4097 || output.component !== 5126 || output.dimension !== width || output.n !== input.n) throw new Error('GLB clip accessor shape');
+      let previous = -1;
+      for (let i = 0; i < input.n; i++) { const time = read(input, i, 0); if (!Number.isFinite(time) || time < 0 || time > 60 || time <= previous) throw new Error('GLB clip time order'); previous = time;
+        let norm = 0; for (let c = 0; c < width; c++) { const n = read(output, i, c); if (!Number.isFinite(n) || Math.abs(n) > 100000) throw new Error('GLB clip value'); norm += n * n; }
+        if (path === 'rotation' && Math.abs(norm - 1) > 1e-4) throw new Error('GLB clip quaternion');
+      }
+      rigCpu += (input.n + output.n * width) * 4;
+    }
+  }
+  // Old GLB fixtures omit scene nodes; count their mesh resources conservatively too.
+  if (nodes.length === 0) for (const cost of meshCosts) {
+    triangles += cost.triangles; draws += cost.draws * 2;
+    if (estimate !== undefined) { estimate.layers += cost.layers; estimate.blendedLayers += cost.blendedLayers; estimate.maskedLayers += cost.maskedLayers; }
+  }
+  if (length + binaryBytes + data.decoded + instanceCpu + rigCpu + imageCost.decoded > MAX_BYTES || gpu > MAX_BYTES || triangles > 400_000 || draws > 512) throw new Error('GLB resource cap');
+  if (visit !== undefined) visitGlbGeometry({ nodes, meshes, accessors, parents, read }, visit);
+  return { decoded: length + binaryBytes + data.decoded + instanceCpu + rigCpu + imageCost.decoded, gpu, triangles, draws };
+}

package/src/format/glbImages.ts

@@ -0,0 +1,95 @@
+import { parseStillImage } from './stillImage.ts';
+import { parseKtx2 } from './ktx2Cost.ts';
+
+const record = (value: unknown): Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('GLB image object required');
+  return value as Record<string, unknown>;
+};
+function list(value: unknown, maximum: number): unknown[] {
+  if (!Array.isArray(value) || value.length > maximum) throw new Error('GLB image inventory exceeds cap');
+  return value;
+}
+function count(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > 25_000_000) throw new Error('Invalid GLB image index or range');
+  return value;
+}
+function noExtensions(row: Record<string, unknown>): void {
+  if (row['extensions'] !== undefined && Object.keys(record(row['extensions'])).length > 0) throw new Error('Unsupported GLB image binding extension');
+}
+function mipBytes(width: number, height: number): number {
+  let bytes = 0, w = width, h = height;
+  while (true) {
+    bytes += w * h * 4;
+    if (w === 1 && h === 1) return bytes;
+    w = Math.max(1, Math.floor(w / 2)); h = Math.max(1, Math.floor(h / 2));
+  }
+}
+
+/** Admit bounded embedded WebP or Basis KTX2 through their matching texture extensions; external/data URIs
+ * and other bindings still refuse. Charge decoded images and conservative RGBA8 mips per texture/material use,
+ * conservatively covering loader clones for different material colour spaces. The GLB aggregate cap also applies. */
+export function glbImageCost(doc: Record<string, unknown>, views: readonly Record<string, unknown>[], binary: Uint8Array): { decoded: number; gpu: number } {
+  let decoded = 0;
+  const images = list(doc['images'] ?? [], 16).map(value => {
+    const image = record(value); noExtensions(image);
+    if (image['uri'] !== undefined || (image['mimeType'] !== 'image/webp' && image['mimeType'] !== 'image/ktx2')) throw new Error('GLB images require embedded WebP or Basis KTX2 bytes');
+    const view = views[count(image['bufferView'])];
+    if (view === undefined || view['byteStride'] !== undefined || view['target'] !== undefined) throw new Error('Invalid GLB image view');
+    const offset = count(view['byteOffset'] ?? 0), length = count(view['byteLength']);
+    if (offset + length > binary.length) throw new Error('GLB image outside buffer');
+    const bytes = binary.subarray(offset, offset + length);
+    let parsed: { mime: string; decoded: number; gpu: number };
+    if (image['mimeType'] === 'image/ktx2') {
+      const cost = parseKtx2(bytes), header = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+      const model = header.getUint8(header.getUint32(48, true) + 12);
+      if (header.getUint32(12, true) !== 0 || (model !== 163 && model !== 166)) throw new Error('GLB KTX2 requires Basis LDR encoding');
+      parsed = { mime: 'image/ktx2', decoded: cost.decoded, gpu: cost.gpu };
+    } else {
+      const paint = parseStillImage(bytes);
+      if (paint.mime !== image['mimeType']) throw new Error('GLB image MIME differs from its bytes');
+      parsed = { mime: paint.mime, decoded: paint.decoded, gpu: mipBytes(paint.width, paint.height) };
+    }
+    decoded += parsed.decoded;
+    if (decoded > 25_000_000) throw new Error('GLB image resource cap');
+    return parsed;
+  });
+  const samplers = list(doc['samplers'] ?? [], 32).map(value => {
+    const sampler = record(value); noExtensions(sampler);
+    if (![9728, 9729].includes(count(sampler['magFilter'] ?? 9729))
+      || ![9728, 9729, 9984, 9985, 9986, 9987].includes(count(sampler['minFilter'] ?? 9987))
+      || ![33071, 33648, 10497].includes(count(sampler['wrapS'] ?? 10497))
+      || ![33071, 33648, 10497].includes(count(sampler['wrapT'] ?? 10497))) throw new Error('Invalid GLB image sampler');
+    return sampler;
+  });
+  const textures = list(doc['textures'] ?? [], 32).map(value => {
+    const texture = record(value), extensions = record(texture['extensions']);
+    const extension = extensions['EXT_texture_webp'] === undefined ? 'KHR_texture_basisu' : 'EXT_texture_webp';
+    if (texture['source'] !== undefined || Object.keys(extensions).length !== 1 || extensions[extension] === undefined
+      || !list(doc['extensionsUsed'] ?? [], 32).includes(extension)) throw new Error('GLB texture requires an unambiguous declared image extension');
+    const binding = record(extensions[extension]);
+    if (Object.keys(binding).some(key => key !== 'source')) throw new Error('Unsupported GLB image binding');
+    const image = images[count(binding['source'])];
+    if (image === undefined || (texture['sampler'] !== undefined && samplers[count(texture['sampler'])] === undefined)) throw new Error('Missing GLB texture image or sampler');
+    if (image.mime !== (extension === 'KHR_texture_basisu' ? 'image/ktx2' : 'image/webp')) throw new Error('GLB texture extension differs from image MIME');
+    return { bytes: image.gpu, uses: 0 };
+  });
+  if (images.length === 0 && textures.length === 0) return { decoded: 0, gpu: 0 };
+  const bind = (value: unknown): void => {
+    if (value === undefined) return;
+    const binding = record(value); noExtensions(binding);
+    const texture = textures[count(binding['index'])];
+    if (texture === undefined) throw new Error('Missing GLB material texture');
+    if (count(binding['texCoord'] ?? 0) > 1) throw new Error('Unsupported GLB texture coordinates');
+    texture.uses++;
+  };
+  for (const value of list(doc['materials'] ?? [], 10_000)) {
+    const material = record(value); noExtensions(material);
+    const pbr = material['pbrMetallicRoughness'] === undefined ? {} : record(material['pbrMetallicRoughness']);
+    noExtensions(pbr);
+    bind(pbr['baseColorTexture']); bind(pbr['metallicRoughnessTexture']);
+    bind(material['normalTexture']); bind(material['occlusionTexture']); bind(material['emissiveTexture']);
+  }
+  const gpu = textures.reduce((sum, texture) => sum + texture.bytes * Math.max(1, texture.uses), 0);
+  if (gpu > 25_000_000) throw new Error('GLB image resource cap');
+  return { decoded, gpu };
+}

package/src/format/glbTriangles.ts

@@ -0,0 +1,95 @@
+/** A renderer-independent vertex in the admitted GLB scene's local frame. */
+export interface GlbVertex { x: number; y: number; z: number }
+interface Accessor { n: number; component: unknown; type: unknown; offset: number; stride: number; width: number; dimension: number; normalized: boolean }
+interface GeometryData {
+  nodes: readonly Record<string, unknown>[]; meshes: readonly Record<string, unknown>[];
+  accessors: readonly Accessor[]; parents: ReadonlyMap<number, number>;
+  read: (accessor: Accessor, row: number, component: number) => number;
+}
+const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+function object(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('GLB geometry object');
+  return value as Record<string, unknown>;
+}
+function list(value: unknown): unknown[] { if (!Array.isArray(value)) throw new Error('GLB geometry array'); return value; }
+function number(value: unknown): number { if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error('GLB geometry number'); return value; }
+function at(matrix: readonly number[], i: number): number { return number(matrix[i]); }
+function multiply(a: readonly number[], b: readonly number[]): number[] {
+  return Array.from({ length: 16 }, (_, i) => {
+    let sum = 0; for (let k = 0; k < 4; k++) sum += at(a, i % 4 + k * 4) * at(b, k + Math.floor(i / 4) * 4);
+    return sum;
+  });
+}
+/** Affine GLB TRS, including instance transforms, without a Three.js dependency. */
+export function glbTransform(input: { translation?: unknown; rotation?: unknown; scale?: unknown; matrix?: unknown }): number[] {
+  if (input.matrix !== undefined) {
+    const matrix = list(input.matrix).map(number);
+    if (matrix.length !== 16 || matrix[3] !== 0 || matrix[7] !== 0 || matrix[11] !== 0 || matrix[15] !== 1) throw new Error('GLB geometry requires an affine matrix');
+    return matrix;
+  }
+  const translation = input.translation === undefined ? [0, 0, 0] : list(input.translation).map(number);
+  const rotation = input.rotation === undefined ? [0, 0, 0, 1] : list(input.rotation).map(number);
+  const scale = input.scale === undefined ? [1, 1, 1] : list(input.scale).map(number);
+  const x = at(rotation, 0), y = at(rotation, 1), z = at(rotation, 2), w = at(rotation, 3);
+  const sx = at(scale, 0), sy = at(scale, 1), sz = at(scale, 2);
+  return [(1 - 2 * (y * y + z * z)) * sx, 2 * (x * y + z * w) * sx, 2 * (x * z - y * w) * sx, 0,
+    2 * (x * y - z * w) * sy, (1 - 2 * (x * x + z * z)) * sy, 2 * (y * z + x * w) * sy, 0,
+    2 * (x * z + y * w) * sz, 2 * (y * z - x * w) * sz, (1 - 2 * (x * x + y * y)) * sz, 0,
+    at(translation, 0), at(translation, 1), at(translation, 2), 1];
+}
+/** Apply an admitted affine scene transform to an actual binary position. */
+export function glbPoint(matrix: readonly number[], p: GlbVertex): GlbVertex {
+  const result = { x: at(matrix, 0) * p.x + at(matrix, 4) * p.y + at(matrix, 8) * p.z + at(matrix, 12),
+    y: at(matrix, 1) * p.x + at(matrix, 5) * p.y + at(matrix, 9) * p.z + at(matrix, 13),
+    z: at(matrix, 2) * p.x + at(matrix, 6) * p.y + at(matrix, 10) * p.z + at(matrix, 14) };
+  if (![result.x, result.y, result.z].every(Number.isFinite)) throw new Error('Nonfinite GLB geometry');
+  return result;
+}
+/** Walk admitted static triangles, respecting hierarchy, indices and GPU instancing; never trust accessor bounds. */
+export function visitGlbGeometry(data: GeometryData, visit: (triangle: readonly GlbVertex[]) => void): void {
+  const { nodes, meshes, accessors, parents, read } = data, worlds = new Map<number, readonly number[]>();
+  const accessor = (value: unknown): Accessor => {
+    const a = accessors[number(value)]; if (a === undefined) throw new Error('Missing GLB geometry accessor'); return a;
+  };
+  const world = (id: number): readonly number[] => {
+    const existing = worlds.get(id); if (existing !== undefined) return existing;
+    const node = nodes[id]; if (node === undefined) throw new Error('Missing GLB geometry node');
+    const parent = parents.get(id), local = glbTransform(node), result = parent === undefined ? local : multiply(world(parent), local);
+    worlds.set(id, result); return result;
+  };
+  const mesh = (id: number, matrix: readonly number[]) => {
+    const row = meshes[id]; if (row === undefined) throw new Error('Missing GLB geometry mesh');
+    for (const value of list(row['primitives'])) {
+      const primitive = object(value), position = accessor(object(primitive['attributes'])['POSITION']);
+      if (!(position.component === 5126 || position.component === 5122)) throw new Error('Static GLB positions must be floats or Int16 grid steps');
+      // a normalized Int16 position is a fraction of its node's scale (KHR_mesh_quantization)
+      const coordinate = (index: number, c: number): number => { const v = read(position, index, c); return position.normalized ? Math.max(v / 32767, -1) : v; };
+      const indices = primitive['indices'] === undefined ? undefined : accessor(primitive['indices']);
+      for (let i = 0; i < (indices?.n ?? position.n); i += 3) {
+        const triangle = Array.from({ length: 3 }, (_, j) => {
+          const index = indices === undefined ? i + j : read(indices, i + j, 0);
+          if (!Number.isSafeInteger(index) || index < 0 || index >= position.n) throw new Error('GLB geometry index outside positions');
+          return glbPoint(matrix, { x: coordinate(index, 0), y: coordinate(index, 1), z: coordinate(index, 2) });
+        });
+        visit(triangle);
+      }
+    }
+  };
+  nodes.forEach((node, id) => {
+    if (node['mesh'] === undefined) return;
+    if (node['skin'] !== undefined) throw new Error('Static prop footprint cannot use a deforming skin');
+    const transform = world(id);
+    if (node['extensions'] === undefined) { mesh(number(node['mesh']), transform); return; }
+    const attributes = object(object(object(node['extensions'])['EXT_mesh_gpu_instancing'])['attributes']);
+    const entries = Object.entries(attributes).map(([key, value]) => ({ key, a: accessor(value) })), count = entries[0]?.a.n ?? 0;
+    for (let i = 0; i < count; i++) {
+      const instance: Record<string, unknown> = {};
+      for (const { key, a } of entries) {
+        if (key === '_COLOR_0') continue;
+        instance[key === '_MATRIX' ? 'matrix' : key.toLowerCase()] = Array.from({ length: key === '_MATRIX' ? 16 : key === 'ROTATION' ? 4 : 3 }, (_, c) => read(a, i, c));
+      }
+      mesh(number(node['mesh']), multiply(transform, glbTransform(instance)));
+    }
+  });
+  if (nodes.length === 0) meshes.forEach((_mesh, id) => mesh(id, identity));
+}

package/src/format/graphArmsRows.ts

@@ -0,0 +1,200 @@
+import * as v from 'valibot';
+import { PrivateSceneSchema } from './clientChannels.ts';
+import { WorldScenePoolSchema, type WorldScenePoolRowInput, type WorldScenePoolRow } from './worldScenes.ts';
+
+const finite = v.pipe(v.number(), v.finite());
+const name = v.pipe(v.string(), v.minLength(1), v.maxLength(512));
+const names: v.GenericSchema<string[], string[]> & { readonly pipe: readonly [unknown, unknown, unknown, v.CheckAction<string[], undefined>] } = v.pipe(v.array(name), v.minLength(1), v.maxLength(64),
+  v.check(rows => new Set(rows).size === rows.length));
+const count = v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(4096));
+const bounded = <T extends v.GenericSchema>(schema: T, max: number) => v.pipe(v.array(schema), v.maxLength(max));
+/** G475 held arms drawn in graph looks: a skinned rig played by the shared arm player (its blade row is the hit sweep's
+ * and the swing trail's), its meshes dressed from rows, the trail sampled along the blade during each swing, and the
+ * per-frame look writes as named sources. Client-only presentation; ids only, no callbacks. */
+export const GraphArmsSchema: v.StrictObjectSchema<{ readonly rig: v.GenericSchema<GraphArmsRowInput['rig'], GraphArmsRow['rig']> & { readonly entries: { readonly sockets: typeof names } }; readonly blade: v.GenericSchema<GraphArmsRowInput['blade'], GraphArmsRow['blade']>; readonly trail: v.GenericSchema<GraphArmsRowInput['trail'], GraphArmsRow['trail']>; readonly claw: v.GenericSchema<GraphArmsRowInput['claw'], GraphArmsRow['claw']>; readonly params: v.GenericSchema<GraphArmsRowInput['params'], GraphArmsRow['params']>; readonly meshes: v.GenericSchema<GraphArmsRowInput['meshes'], GraphArmsRow['meshes']>; readonly maps: v.GenericSchema<GraphArmsRowInput['maps'], GraphArmsRow['maps']>; readonly weave: v.GenericSchema<GraphArmsRowInput['weave'], GraphArmsRow['weave']>; readonly decal: v.GenericSchema<GraphArmsRowInput['decal'], GraphArmsRow['decal']>; readonly back: v.GenericSchema<GraphArmsRowInput['back'], GraphArmsRow['back']>; readonly additive: v.GenericSchema<GraphArmsRowInput['additive'], GraphArmsRow['additive']>; readonly pendants: v.GenericSchema<GraphArmsRowInput['pendants'], GraphArmsRow['pendants']>; readonly frame: v.GenericSchema<GraphArmsRowInput['frame'], GraphArmsRow['frame']>; }, undefined> = v.strictObject({
+  rig: v.strictObject({ url: name, skeleton: name, sockets: names, joints: bounded(names, 8), holdRight: bounded(name, 32), holdLeft: bounded(name, 32),
+    walkRate: finite, lag: v.strictObject({ max: finite, pitch: finite, yaw: finite }) }),
+  /** the blade on its socket: base and tip along the socket's +Y (rig units) */
+  blade: v.strictObject({ socket: name, base: finite, tip: finite }),
+  /** the swing trail: ribbon profile, its look and seed param, its life as a share of the clip (or `total` s), sampled from `from` of the blade */
+  trail: v.strictObject({ look: name, seed: name, samples: count, subdivisions: count, movementSq: finite, life: finite, total: finite, from: finite, order: finite }),
+  /** meshes whose name starts with this show with the claw */
+  claw: name,
+  /** every look's params, by look id; a frame source with no look writes each look that declares its param */
+  params: v.record(name, bounded(name, 128)),
+  meshes: bounded(v.strictObject({ name, channels: v.record(name, name), look: name, maps: v.exactOptional(name), hull: v.boolean(), doubleSide: v.boolean() }), 64),
+  /** per-mesh map pairs: `<base><maps>-<kind>.webp` (or its KTX2 stand-in) lent to the mesh look's params */
+  maps: v.strictObject({ base: name, names, kinds: v.strictObject({ maps: name, nrm: name }), anisotropy: finite }),
+  /** an R8 repeating weave and per-tier lossless decal images, all named product files */
+  weave: v.strictObject({ file: name, size: count, param: name }),
+  decal: v.strictObject({ files: v.strictObject({ phone: name, desktop: name }), param: name }),
+  back: bounded(name, 64), additive: bounded(name, 64),
+  /** The pendants: the existing verified world-scene GLB pools and a private scene on its socket. */
+  pendants: v.strictObject({ socket: name, scene: PrivateSceneSchema, materials: bounded(name, 64),
+    geometry: bounded(WorldScenePoolSchema, 16) }),
+  frame: bounded(v.strictObject({ look: v.exactOptional(name), param: name, source: v.picklist(['time', 'buffer', 'pixels', 'projection']),
+    scale: v.exactOptional(finite), min: v.exactOptional(finite) }), 32),
+});
+
+/** Build-only admission of the named held-view file, before any native binding reads it. */
+export function parseGraphArms(input: unknown): GraphArmsRow { return v.parse(GraphArmsSchema, input); }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface GraphArmsRowInputFields {
+    rig: {
+        url: string;
+        skeleton: string;
+        sockets: (string)[];
+        joints: ((string)[])[];
+        holdRight: (string)[];
+        holdLeft: (string)[];
+        walkRate: number;
+        lag: {
+            max: number;
+            pitch: number;
+            yaw: number;
+        };
+    };
+    blade: {
+        socket: string;
+        base: number;
+        tip: number;
+    };
+    trail: {
+        look: string;
+        seed: string;
+        samples: number;
+        subdivisions: number;
+        movementSq: number;
+        life: number;
+        total: number;
+        from: number;
+        order: number;
+    };
+    claw: string;
+    params: Record<string, (string)[]>;
+    meshes: ({
+        name: string;
+        channels: Record<string, string>;
+        look: string;
+        maps?: string;
+        hull: boolean;
+        doubleSide: boolean;
+    })[];
+    maps: {
+        base: string;
+        names: (string)[];
+        kinds: {
+            maps: string;
+            nrm: string;
+        };
+        anisotropy: number;
+    };
+    weave: {
+        file: string;
+        size: number;
+        param: string;
+    };
+    decal: {
+        files: {
+            phone: string;
+            desktop: string;
+        };
+        param: string;
+    };
+    back: (string)[];
+    additive: (string)[];
+    pendants: {
+        socket: string;
+        scene: v.InferInput<typeof PrivateSceneSchema>;
+        materials: (string)[];
+        geometry: WorldScenePoolRowInput[];
+    };
+    frame: ({
+        look?: string;
+        param: string;
+        source: 'time' | 'buffer' | 'pixels' | 'projection';
+        scale?: number;
+        min?: number;
+    })[];
+}
+export type GraphArmsRowInput = { [Key in keyof GraphArmsRowInputFields]: GraphArmsRowInputFields[Key] };
+interface GraphArmsRowFields {
+    rig: {
+        url: string;
+        skeleton: string;
+        sockets: (string)[];
+        joints: ((string)[])[];
+        holdRight: (string)[];
+        holdLeft: (string)[];
+        walkRate: number;
+        lag: {
+            max: number;
+            pitch: number;
+            yaw: number;
+        };
+    };
+    blade: {
+        socket: string;
+        base: number;
+        tip: number;
+    };
+    trail: {
+        look: string;
+        seed: string;
+        samples: number;
+        subdivisions: number;
+        movementSq: number;
+        life: number;
+        total: number;
+        from: number;
+        order: number;
+    };
+    claw: string;
+    params: Record<string, (string)[]>;
+    meshes: ({
+        name: string;
+        channels: Record<string, string>;
+        look: string;
+        maps?: string;
+        hull: boolean;
+        doubleSide: boolean;
+    })[];
+    maps: {
+        base: string;
+        names: (string)[];
+        kinds: {
+            maps: string;
+            nrm: string;
+        };
+        anisotropy: number;
+    };
+    weave: {
+        file: string;
+        size: number;
+        param: string;
+    };
+    decal: {
+        files: {
+            phone: string;
+            desktop: string;
+        };
+        param: string;
+    };
+    back: (string)[];
+    additive: (string)[];
+    pendants: {
+        socket: string;
+        scene: v.InferOutput<typeof PrivateSceneSchema>;
+        materials: (string)[];
+        geometry: WorldScenePoolRow[];
+    };
+    frame: ({
+        look?: string;
+        param: string;
+        source: 'time' | 'buffer' | 'pixels' | 'projection';
+        scale?: number;
+        min?: number;
+    })[];
+}
+export type GraphArmsRow = { [Key in keyof GraphArmsRowFields]: GraphArmsRowFields[Key] };