@genex-ai/cli-demo 1.5.2-dev.398 → 1.6.0

package/templates/asset-viewer/src/viewer/gates-overlay.js

@@ -0,0 +1,521 @@
+// Measurement, and the hooks tools/gates.mjs drives under ?gates=1.
+//
+// This is NOT a debug bypass (AGENTS.md law 19). The viewer IS the product
+// here, the numbers it exposes are the numbers the manifest publishes, and the
+// hooks unlock no behaviour a visitor does not already have - they only ask the
+// scene what it weighs. `measureStatic` is used by the plain viewer too, to
+// fill the HUD.
+//
+// Copied verbatim into every asset project and hashed by gate G13.
+
+import * as THREE from "three";
+
+const SILHOUETTE_SIZE = 320;
+
+export function isGatesMode() {
+  return new URLSearchParams(globalThis.location?.search ?? "").get("gates") === "1";
+}
+
+function textureBytes(texture) {
+  const image = texture.image;
+  if (!image) return 0;
+  if (image.data && typeof image.data.byteLength === "number") return image.data.byteLength;
+  const w = image.width ?? 0;
+  const h = image.height ?? 0;
+  return w * h * 4;
+}
+
+function collectMaterials(material, into) {
+  if (!material) return;
+  if (Array.isArray(material)) material.forEach((m) => collectMaterials(m, into));
+  else into.add(material);
+}
+
+/**
+ * Everything measurable without a render: the numbers gates G1, G3, G4, G5, G6
+ * and G15 read, plus the HUD's.
+ *
+ * @param {THREE.Object3D} root
+ */
+export function measureStatic(root) {
+  root.updateMatrixWorld(true);
+
+  const geometries = new Set();
+  const materials = new Set();
+  const textures = new Set();
+  let triangles = 0;
+  let vertices = 0;
+  let meshes = 0;
+  let instancedMeshes = 0;
+  let staticDrawCalls = 0;
+
+  root.traverse((obj) => {
+    if (!obj.isMesh && !obj.isPoints && !obj.isLine) return;
+    const geometry = obj.geometry;
+    if (!geometry) return;
+    const instances = obj.isInstancedMesh ? obj.count : 1;
+    if (obj.isInstancedMesh) instancedMeshes += 1;
+    else if (obj.isMesh) meshes += 1;
+
+    if (!geometries.has(geometry)) {
+      geometries.add(geometry);
+      vertices += geometry.getAttribute("position")?.count ?? 0;
+    }
+    if (obj.isMesh) {
+      const index = geometry.getIndex();
+      const count = index ? index.count : (geometry.getAttribute("position")?.count ?? 0);
+      triangles += (count / 3) * instances;
+    }
+    // Geometry groups only cost extra draws when the material is an ARRAY -
+    // a BoxGeometry carries six groups and still renders in one call under a
+    // single material, which is what once made the HUD disagree with the
+    // manifest by a factor of two.
+    staticDrawCalls += Array.isArray(obj.material) ? Math.max(1, geometry.groups?.length ?? 1) : 1;
+    collectMaterials(obj.material, materials);
+  });
+
+  for (const material of materials) {
+    for (const value of Object.values(material)) {
+      if (value && value.isTexture) textures.add(value);
+    }
+  }
+
+  const box = new THREE.Box3().setFromObject(root);
+  const size = box.getSize(new THREE.Vector3());
+  const centre = box.getCenter(new THREE.Vector3());
+
+  // G6: a NaN in an attribute, or a non-finite bounding sphere, is what makes a
+  // mesh vanish nondeterministically under frustum culling.
+  const nanAttributes = [];
+  const badBoundingSpheres = [];
+  for (const geometry of geometries) {
+    for (const name of ["position", "normal", "uv"]) {
+      const attribute = geometry.getAttribute(name);
+      if (!attribute) continue;
+      const array = attribute.array;
+      for (let i = 0; i < array.length; i += 1) {
+        if (!Number.isFinite(array[i])) {
+          nanAttributes.push(`${geometry.name || geometry.type}.${name}[${i}]`);
+          break;
+        }
+      }
+    }
+    geometry.computeBoundingSphere();
+    const radius = geometry.boundingSphere?.radius;
+    if (!Number.isFinite(radius) || !(radius > 0)) {
+      badBoundingSpheres.push(geometry.name || geometry.type);
+    }
+  }
+
+  return {
+    triangles: Math.round(triangles),
+    vertices,
+    meshes,
+    instancedMeshes,
+    drawCalls: staticDrawCalls,
+    materials: materials.size,
+    textures: textures.size,
+    textureBytes: [...textures].reduce((sum, t) => sum + textureBytes(t), 0),
+    maxTextureDimension: [...textures].reduce(
+      (max, t) => Math.max(max, t.image?.width ?? 0, t.image?.height ?? 0),
+      0,
+    ),
+    boundingBox: { min: box.min.toArray(), max: box.max.toArray() },
+    sizeMeters: size.toArray(),
+    centre: centre.toArray(),
+    nanAttributes,
+    badBoundingSpheres,
+  };
+}
+
+/**
+ * G10's fingerprint: a stable hash over every geometry's vertex data, in
+ * traverse order. Two fresh page loads producing different hashes means the
+ * factory is not deterministic.
+ */
+export function vertexHash(root) {
+  // FNV-1a, two independent offsets so the digest is 64 bits wide.
+  let a = 0x811c9dc5;
+  let b = 0x01000193;
+  const feed = (bytes) => {
+    for (let i = 0; i < bytes.length; i += 1) {
+      a = ((a ^ bytes[i]) * 0x01000193) >>> 0;
+      b = ((b + bytes[i]) * 0x85ebca6b) >>> 0;
+    }
+  };
+  const seen = new Set();
+  root.traverse((obj) => {
+    const geometry = obj.geometry;
+    if (!geometry || seen.has(geometry)) return;
+    seen.add(geometry);
+    for (const name of ["position", "normal", "uv", "color"]) {
+      const attribute = geometry.getAttribute(name);
+      if (!attribute) continue;
+      feed(new Uint8Array(attribute.array.buffer, attribute.array.byteOffset, attribute.array.byteLength));
+    }
+    const index = geometry.getIndex();
+    if (index) feed(new Uint8Array(index.array.buffer, index.array.byteOffset, index.array.byteLength));
+  });
+  return (a >>> 0).toString(16).padStart(8, "0") + (b >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * G17: does each triangle's WINDING agree with the normal the module supplies?
+ *
+ * This is the gate that actually catches the reversed-ring defect. G16 (below) was
+ * written for it first and measured as insufficient: reversing a CLOSED band does
+ * not empty the render, it just draws the far interior wall instead, so pixel
+ * coverage barely moves. Only an open surface or a cap disappears outright.
+ *
+ * Winding is checked against the shaded normal instead, which needs no renderer at
+ * all: cross(b-a, c-a) . normal(a) must be positive. These modules author analytic
+ * normals, so disagreement means the triangle is drawn facing the opposite way from
+ * the way it is lit - back-face culled where it should be solid, or lit inside-out
+ * where it is double-sided. Verified against a deliberately reversed part: 144 of
+ * 144 triangles disagree, while every intact part scores 0.
+ */
+function windingConsistency(root) {
+  const meshes = [];
+  root.traverse((o) => {
+    if (!o.isMesh || !o.geometry) return;
+    const geometry = o.geometry;
+    const position = geometry.getAttribute("position");
+    const normal = geometry.getAttribute("normal");
+    if (!position || !normal) return;
+    const index = geometry.getIndex();
+    const count = index ? index.count : position.count;
+    const at = (i) => (index ? index.getX(i) : i);
+
+    const a = new THREE.Vector3();
+    const b = new THREE.Vector3();
+    const c = new THREE.Vector3();
+    const ab = new THREE.Vector3();
+    const ac = new THREE.Vector3();
+    const face = new THREE.Vector3();
+    const shaded = new THREE.Vector3();
+    const tmp = new THREE.Vector3();
+
+    let flipped = 0;
+    let tested = 0;
+    for (let i = 0; i + 2 < count; i += 3) {
+      a.fromBufferAttribute(position, at(i));
+      b.fromBufferAttribute(position, at(i + 1));
+      c.fromBufferAttribute(position, at(i + 2));
+      ab.subVectors(b, a);
+      ac.subVectors(c, a);
+      face.crossVectors(ab, ac);
+      if (face.lengthSq() === 0) continue; // degenerate sliver: no opinion
+      // Average all THREE corner normals, not just the first. At a sharp crease the
+      // corners carry very different averaged normals, and on an oblique triangle a
+      // single corner can disagree with a correctly-wound face - measured as 6 of 576
+      // triangles on the step ladder's treads, i.e. 1.04%, just over a 1% line and
+      // entirely an artefact of the measurement. The margin does the same job for the
+      // near-perpendicular case: only a clear disagreement counts.
+      shaded.fromBufferAttribute(normal, at(i));
+      tmp.fromBufferAttribute(normal, at(i + 1));
+      shaded.add(tmp);
+      tmp.fromBufferAttribute(normal, at(i + 2));
+      shaded.add(tmp);
+      if (shaded.lengthSq() === 0) continue; // opposed normals: no usable opinion
+      tested += 1;
+      if (face.normalize().dot(shaded.normalize()) < -0.05) flipped += 1;
+    }
+    meshes.push({
+      name: o.name || "(unnamed)",
+      triangles: tested,
+      flipped,
+      share: tested ? flipped / tested : 0,
+    });
+  });
+  return meshes;
+}
+
+/**
+ * G16: is every named part actually VISIBLE?
+ *
+ * Measured, not theorised: a sub-assembly lofted with its rings in the reverse
+ * order gets face normals pointing inward, so it is entirely back-face culled and
+ * renders as nothing - while still counting its meshes, its triangles and its draw
+ * calls. On the steel drum both bungs were invisible for three build cycles with
+ * G1-G15 reading all-pass throughout. Every count-based gate is structurally blind
+ * to it, because the geometry really is there.
+ *
+ * Each part is judged ALONE, with the camera fitted to that part's own bounds, so
+ * a rivet is held to the same standard as a barrel and a part that is legitimately
+ * enclosed inside another (a lamp inside a lantern) is not punished for it. The
+ * probe material copies each mesh's real `side`, so a deliberately double-sided
+ * shell - fabric, foliage - is judged the way it will actually be drawn rather
+ * than being failed for a convention it never adopted.
+ */
+function partVisibility(stage, root, views) {
+  const { renderer } = stage;
+  const nodes = root.userData?.assetRuntime?.nodes ?? {};
+  const names = Object.keys(nodes);
+  if (names.length === 0) return [];
+
+  const originalVisible = new Map();
+  const originalMaterial = new Map();
+  root.traverse((o) => {
+    originalVisible.set(o, o.visible);
+    if (o.isMesh) {
+      originalMaterial.set(o, o.material);
+      const first = Array.isArray(o.material) ? o.material[0] : o.material;
+      o.material = new THREE.MeshBasicMaterial({ color: 0x000000, side: first?.side ?? THREE.FrontSide });
+    }
+  });
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0xffffff);
+  const parent = root.parent;
+  scene.add(root);
+
+  const target = new THREE.WebGLRenderTarget(SILHOUETTE_SIZE, SILHOUETTE_SIZE);
+  const buffer = new Uint8Array(SILHOUETTE_SIZE * SILHOUETTE_SIZE * 4);
+  const previousTarget = renderer.getRenderTarget();
+  const total = SILHOUETTE_SIZE * SILHOUETTE_SIZE;
+  const results = [];
+
+  for (const name of names) {
+    const part = nodes[name];
+    if (!part || !part.isObject3D) {
+      results.push({ name, bestShare: 0, skipped: "not an Object3D" });
+      continue;
+    }
+    // Hide every named part, then re-open only the path from the root down to this
+    // one: `nodes` may be nested, so blanket-hiding siblings could hide an ancestor.
+    for (const other of names) if (nodes[other]?.isObject3D) nodes[other].visible = false;
+    part.visible = true;
+    for (let a = part.parent; a && a !== root.parent; a = a.parent) a.visible = true;
+
+    const box = new THREE.Box3().setFromObject(part);
+    if (box.isEmpty()) {
+      results.push({ name, bestShare: 0, skipped: "empty bounds" });
+      continue;
+    }
+    const centre = box.getCenter(new THREE.Vector3());
+    const radius = Math.max(box.getSize(new THREE.Vector3()).length() * 0.5, 1e-4);
+    const camera = new THREE.PerspectiveCamera(35, 1, radius * 0.05, radius * 40);
+    const distance = radius / Math.tan(THREE.MathUtils.degToRad(35 / 2));
+    const elevation = THREE.MathUtils.degToRad(20);
+
+    let best = 0;
+    for (let i = 0; i < views; i += 1) {
+      const theta = (i / views) * Math.PI * 2;
+      camera.position.set(
+        centre.x + Math.cos(elevation) * Math.cos(theta) * distance,
+        centre.y + Math.sin(elevation) * distance,
+        centre.z + Math.cos(elevation) * Math.sin(theta) * distance,
+      );
+      camera.lookAt(centre);
+      renderer.setRenderTarget(target);
+      renderer.clear();
+      renderer.render(scene, camera);
+      renderer.readRenderTargetPixels(target, 0, 0, SILHOUETTE_SIZE, SILHOUETTE_SIZE, buffer);
+      let covered = 0;
+      for (let p = 0; p < buffer.length; p += 4) {
+        if (buffer[p] < 200 || buffer[p + 1] < 200 || buffer[p + 2] < 200) covered += 1;
+      }
+      if (covered > best) best = covered;
+    }
+    results.push({ name, bestPixels: best, bestShare: best / total });
+  }
+
+  renderer.setRenderTarget(previousTarget);
+  target.dispose();
+  scene.remove(root);
+  parent?.add(root);
+  root.traverse((o) => {
+    if (originalVisible.has(o)) o.visible = originalVisible.get(o);
+    if (o.isMesh && originalMaterial.has(o)) {
+      o.material.dispose();
+      o.material = originalMaterial.get(o);
+    }
+  });
+  return results;
+}
+
+/**
+ * G9: silhouette pixel area at eight turntable views, rendered flat black on
+ * white so a flat plane wearing a texture cannot fake volume.
+ */
+function silhouetteAreas(stage, root, views) {
+  const { renderer } = stage;
+  const parent = root.parent;
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0xffffff);
+  scene.overrideMaterial = new THREE.MeshBasicMaterial({ color: 0x000000 });
+  scene.add(root);
+
+  const target = new THREE.WebGLRenderTarget(SILHOUETTE_SIZE, SILHOUETTE_SIZE);
+  const box = new THREE.Box3().setFromObject(root);
+  const centre = box.getCenter(new THREE.Vector3());
+  const radius = Math.max(box.getSize(new THREE.Vector3()).length() * 0.5, 0.05);
+  const camera = new THREE.PerspectiveCamera(35, 1, radius * 0.05, radius * 40);
+  const distance = radius / Math.tan(THREE.MathUtils.degToRad(35 / 2));
+  const elevation = THREE.MathUtils.degToRad(14);
+
+  const previousTarget = renderer.getRenderTarget();
+  const buffer = new Uint8Array(SILHOUETTE_SIZE * SILHOUETTE_SIZE * 4);
+  const areas = [];
+  for (let i = 0; i < views; i += 1) {
+    const theta = (i / views) * Math.PI * 2;
+    camera.position.set(
+      centre.x + Math.cos(elevation) * Math.cos(theta) * distance,
+      centre.y + Math.sin(elevation) * distance,
+      centre.z + Math.cos(elevation) * Math.sin(theta) * distance,
+    );
+    camera.lookAt(centre);
+    renderer.setRenderTarget(target);
+    renderer.clear();
+    renderer.render(scene, camera);
+    renderer.readRenderTargetPixels(target, 0, 0, SILHOUETTE_SIZE, SILHOUETTE_SIZE, buffer);
+    let covered = 0;
+    for (let p = 0; p < buffer.length; p += 4) {
+      if (buffer[p] < 200 || buffer[p + 1] < 200 || buffer[p + 2] < 200) covered += 1;
+    }
+    areas.push(covered);
+  }
+  renderer.setRenderTarget(previousTarget);
+  target.dispose();
+  scene.overrideMaterial.dispose();
+
+  scene.remove(root);
+  parent?.add(root);
+  return areas;
+}
+
+/**
+ * G12: build a second instance, upload it, dispose it, and check that the
+ * renderer's geometry and texture counts come back to where they started.
+ */
+function disposalCheck(stage, factory) {
+  const { renderer, scene, camera } = stage;
+  renderer.render(scene, camera);
+  const before = { geometries: renderer.info.memory.geometries, textures: renderer.info.memory.textures };
+
+  const probe = factory();
+  scene.add(probe);
+  renderer.render(scene, camera);
+  const peak = { geometries: renderer.info.memory.geometries, textures: renderer.info.memory.textures };
+
+  const dispose = probe.userData?.dispose;
+  const hasDispose = typeof dispose === "function";
+  if (hasDispose) dispose();
+  scene.remove(probe);
+  renderer.render(scene, camera);
+  const after = { geometries: renderer.info.memory.geometries, textures: renderer.info.memory.textures };
+
+  return {
+    hasDispose,
+    before,
+    peak,
+    after,
+    uploadedGeometries: peak.geometries - before.geometries,
+    passed: hasDispose && after.geometries === before.geometries && after.textures === before.textures,
+  };
+}
+
+/**
+ * Empirical draw calls, counted for the ASSET alone. Three things the stage
+ * draws are excluded, because none of them is the asset's cost to carry and a
+ * game pays none of them:
+ *
+ *  - the shadow pass. renderer.info.render.calls accumulates it, and with it
+ *    counted every asset was reported at exactly double.
+ *  - the viewer's own chrome (the ground-shadow plane).
+ *  - the backdrop, which is drawn into a separate scene by stage.draw() and so
+ *    is already absent from a bare renderer.render(scene, camera) like this one.
+ *
+ * Frustum culling is suspended for the pass, or a part off-camera would flatter
+ * the number.
+ */
+function measureDrawCalls(stage, root) {
+  const culled = [];
+  root.traverse((obj) => {
+    culled.push([obj, obj.frustumCulled]);
+    obj.frustumCulled = false;
+  });
+  const shadows = stage.renderer.shadowMap.enabled;
+  const chromeVisible = stage.chrome ? stage.chrome.visible : false;
+  stage.renderer.shadowMap.enabled = false;
+  if (stage.chrome) stage.chrome.visible = false;
+  stage.renderer.render(stage.scene, stage.camera);
+  const calls = stage.renderer.info.render.calls;
+  stage.renderer.shadowMap.enabled = shadows;
+  if (stage.chrome) stage.chrome.visible = chromeVisible;
+  for (const [obj, value] of culled) obj.frustumCulled = value;
+  stage.renderer.render(stage.scene, stage.camera);
+  return calls;
+}
+
+/**
+ * Publish the measurements on window.__ASSET_GATES__ for tools/gates.mjs.
+ * Only called under ?gates=1.
+ */
+export function installGateHooks({ stage, root, factory, config, statics }) {
+  const measurements = statics ?? measureStatic(root);
+  const api = {
+    ready: true,
+    runner: "asset-gates@1",
+    slug: config.slug,
+    name: config.name,
+    threeRevision: THREE.REVISION,
+    statedSizeMeters: config.statedSizeMeters,
+    geometry: {
+      triangles: measurements.triangles,
+      vertices: measurements.vertices,
+      meshes: measurements.meshes,
+      instancedMeshes: measurements.instancedMeshes,
+      drawCalls: measureDrawCalls(stage, root),
+      materials: measurements.materials,
+      textures: measurements.textures,
+      textureBytes: measurements.textureBytes,
+    },
+    maxTextureDimension: measurements.maxTextureDimension,
+    space: {
+      boundingBox: measurements.boundingBox,
+      sizeMeters: measurements.sizeMeters,
+      centre: measurements.centre,
+    },
+    numeric: {
+      nanAttributes: measurements.nanAttributes,
+      badBoundingSpheres: measurements.badBoundingSpheres,
+    },
+    vertexHash: vertexHash(root),
+    userData: {
+      hasAssetRuntime: !!root.userData?.assetRuntime,
+      hasAssetInfo: !!root.userData?.assetInfo,
+      hasDispose: typeof root.userData?.dispose === "function",
+      nodeNames: Object.keys(root.userData?.assetRuntime?.nodes ?? {}),
+      rootName: root.name,
+    },
+    silhouettes(views = 8) {
+      return silhouetteAreas(stage, root, views);
+    },
+    partVisibility(views = 8) {
+      return partVisibility(stage, root, views);
+    },
+    winding() {
+      return windingConsistency(root);
+    },
+    disposal() {
+      return disposalCheck(stage, factory);
+    },
+    renderViews(views = 8) {
+      // Exercise every angle once so G7 sees any shader or culling warning the
+      // asset only produces from a particular direction.
+      const box = new THREE.Box3().setFromObject(root);
+      for (let i = 0; i < views; i += 1) {
+        stage.orbit.spherical.theta = (i / views) * Math.PI * 2;
+        stage.orbit.spherical.phi = i % 2 === 0 ? Math.PI * 0.42 : Math.PI * 0.2;
+        stage.orbit.apply();
+        stage.renderOnce();
+      }
+      stage.fit(box, config.viewer?.cameraDistanceMul ?? 1);
+      stage.renderOnce();
+      return views;
+    },
+  };
+  globalThis.__ASSET_GATES__ = api;
+  return api;
+}

package/templates/asset-viewer/src/viewer/hud.js

@@ -0,0 +1,73 @@
+// The viewer HUD: name, real-world dimensions, budget numbers, MIT chip.
+// Pure CSS out of index.html - this is viewer chrome, not a game HUD, so the
+// sprite-HUD pipeline does not apply.
+//
+// Copied verbatim into every asset project and hashed by gate G13.
+
+const NUM = new Intl.NumberFormat("en-US");
+
+function chip(label, value) {
+  const el = document.createElement("span");
+  el.className = "chip";
+  if (value == null) {
+    el.textContent = label;
+  } else {
+    el.append(`${label} `);
+    const strong = document.createElement("strong");
+    strong.textContent = value;
+    el.append(strong);
+  }
+  return el;
+}
+
+function formatSizeMeters(size) {
+  if (!size) return " - ";
+  return `${size.map((n) => n.toFixed(2)).join(" × ")} m`;
+}
+
+/**
+ * A zero-height flex item that fills the row, so everything after it starts on
+ * a new line. The two groups mean different things - what the object IS (size,
+ * triangles) and what it COSTS to draw - and left to wrap on its own the split
+ * lands wherever this particular asset's digits happen to reach.
+ */
+function lineBreak() {
+  const el = document.createElement("span");
+  el.className = "chip-break";
+  return el;
+}
+
+export function createHud(root) {
+  const nameEl = root.querySelector("#hud-name");
+  const summaryEl = root.querySelector("#hud-summary");
+  const rowsEl = root.querySelector("#hud-rows");
+
+  return {
+    setAsset({ name, summary }) {
+      nameEl.textContent = name;
+      summaryEl.textContent = summary ?? "";
+    },
+    /**
+     * @param {{ sizeMeters: number[]|null, triangles: number, drawCalls: number, materials: number }} stats
+     */
+    setStats(stats) {
+      rowsEl.replaceChildren(
+        chip("size", formatSizeMeters(stats.sizeMeters)),
+        chip("tris", NUM.format(stats.triangles)),
+        lineBreak(),
+        chip("draws", NUM.format(stats.drawCalls)),
+        chip("materials", NUM.format(stats.materials)),
+      );
+      const license = chip("MIT");
+      license.classList.add("chip--license");
+      rowsEl.append(license);
+    },
+  };
+}
+
+export function showFault(message) {
+  const el = document.getElementById("fault");
+  if (!el) return;
+  el.style.display = "grid";
+  el.textContent = message;
+}