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

package/templates/asset-viewer/src/asset/PLACEHOLDER.ts

@@ -0,0 +1,237 @@
+// Placeholder Asset - procedural Three.js asset.
+// MIT License - Copyright (c) 2026 Genex. Free to use, modify and ship.
+// Units: metres. Y-up, +Z forward. Origin at base centre (y = 0).
+// Requires: three >= r160. No other dependency.
+//
+// This is the module scripts/new-asset.mjs seeds a new asset project with: a
+// revolved pedestal marker that already satisfies every rule in the asset
+// contract, so a freshly scaffolded folder builds, gates and deploys before a
+// single line of the real asset is written. Replace the body - keep the shape.
+
+import * as THREE from 'three';
+
+// --- scaffold parameters ----------------------------------------------------
+// scripts/new-asset.mjs rewrites these four lines from asset.config.json.
+// Keep them on one line each, and keep the names: the scaffolder matches them.
+const SLUG = 'placeholder';
+const NAME = 'Placeholder Asset';
+const SIZE_METERS: [number, number, number] = [0.4, 0.6, 0.4];
+const TARGET_TRIANGLES = 1400;
+// ----------------------------------------------------------------------------
+
+export interface PlaceholderOptions {
+  /** Feeds the in-file PRNG. Same seed and options → identical vertex data. */
+  seed?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  detail?: 'low' | 'standard' | 'high';
+  wireframe?: boolean;
+}
+
+/**
+ * Deterministic PRNG. Contract rule 14: an asset never calls Math.random(), or
+ * every measured number in its manifest is a one-time coincidence.
+ */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * The revolve profile in unit space: radius 0…0.5, height 0…1. Scaling the
+ * finished geometry by SIZE_METERS is what makes the bounding box match the
+ * stated real-world dimensions exactly, rather than approximately.
+ */
+const PROFILE: ReadonlyArray<readonly [number, number]> = [
+  [0.0, 0.0],
+  [0.46, 0.0],
+  [0.5, 0.012],
+  [0.5, 0.06],
+  [0.44, 0.085],
+  [0.3, 0.11],
+  [0.27, 0.15],
+  [0.25, 0.56],
+  [0.29, 0.64],
+  [0.28, 0.7],
+  [0.24, 0.76],
+  [0.2, 0.86],
+  [0.12, 0.945],
+  [0.0, 1.0],
+];
+
+const STUD_COUNT = 8;
+const STUD_TRIANGLES = STUD_COUNT * 12;
+const PROFILE_SEGMENTS = PROFILE.length - 1;
+/** Lathe (2 tris per profile segment) + the collar ring (2 tris), per radial step. */
+const TRIANGLES_PER_RADIAL_STEP = PROFILE_SEGMENTS * 2 + 2;
+
+const DETAIL_SCALE: Record<'low' | 'standard' | 'high', number> = {
+  low: 0.5,
+  standard: 1,
+  high: 2,
+};
+
+function radialSegmentsFor(detail: 'low' | 'standard' | 'high'): number {
+  const budget = (TARGET_TRIANGLES - STUD_TRIANGLES) * DETAIL_SCALE[detail];
+  return Math.min(256, Math.max(12, Math.round(budget / TRIANGLES_PER_RADIAL_STEP)));
+}
+
+/**
+ * A banded surface map built from a typed array. Contract rule 12: procedural
+ * detail comes from geometry plus DataTexture - CanvasTexture needs `document`
+ * and would break the module in a worker and in SSR.
+ */
+function createBandTexture(random: () => number): THREE.DataTexture {
+  const size = 64;
+  const data = new Uint8Array(size * size * 4);
+  for (let y = 0; y < size; y += 1) {
+    const v = y / (size - 1);
+    // Two darker collars, and a slight vertical gradient elsewhere.
+    const band = v > 0.56 && v < 0.68 ? 0.45 : v > 0.2 && v < 0.26 ? 0.62 : 1;
+    for (let x = 0; x < size; x += 1) {
+      const grain = 0.94 + random() * 0.06;
+      const shade = Math.round(255 * band * grain * (0.78 + v * 0.22));
+      const i = (y * size + x) * 4;
+      data[i] = shade;
+      data[i + 1] = Math.round(shade * 0.97);
+      data[i + 2] = Math.round(shade * 0.93);
+      data[i + 3] = 255;
+    }
+  }
+  const texture = new THREE.DataTexture(data, size, size, THREE.RGBAFormat);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.wrapS = THREE.RepeatWrapping;
+  texture.wrapT = THREE.ClampToEdgeWrapping;
+  // DataTexture defaults to NearestFilter with no mipmaps, which reads as
+  // blocky the moment the surface is bigger than a few hundred pixels.
+  texture.magFilter = THREE.LinearFilter;
+  texture.minFilter = THREE.LinearMipmapLinearFilter;
+  texture.generateMipmaps = true;
+  texture.anisotropy = 4;
+  texture.needsUpdate = true;
+  return texture;
+}
+
+/**
+ * Build the placeholder asset.
+ *
+ * Origin sits at the base centre on y = 0, so a game does
+ * `model.position.set(x, groundY, z)` and it stands on the floor.
+ */
+export function createPlaceholderModel(options: PlaceholderOptions = {}): THREE.Group {
+  const {
+    seed = 1,
+    castShadow = true,
+    receiveShadow = true,
+    detail = 'standard',
+    wireframe = false,
+  } = options;
+
+  const random = mulberry32(seed);
+  const [width, height, depth] = SIZE_METERS;
+  const radial = radialSegmentsFor(detail);
+
+  // --- body ----------------------------------------------------------------
+  const bodyGeometry = new THREE.LatheGeometry(
+    PROFILE.map(([r, y]) => new THREE.Vector2(r, y)),
+    radial,
+  );
+  bodyGeometry.scale(width, height, depth);
+  bodyGeometry.name = `${SLUG}-body`;
+
+  const bandTexture = createBandTexture(random);
+  const bodyMaterial = new THREE.MeshStandardMaterial({
+    color: 0xd6dae1,
+    map: bandTexture,
+    roughness: 0.62,
+    metalness: 0.05,
+    wireframe,
+  });
+
+  const body = new THREE.Mesh(bodyGeometry, bodyMaterial);
+  body.name = 'body';
+  body.castShadow = castShadow;
+  body.receiveShadow = receiveShadow;
+
+  // --- collar --------------------------------------------------------------
+  const collarGeometry = new THREE.CylinderGeometry(0.3, 0.3, 0.045, radial, 1, true);
+  collarGeometry.translate(0, 0.62, 0);
+  collarGeometry.scale(width, height, depth);
+  collarGeometry.name = `${SLUG}-collar`;
+
+  const collarMaterial = new THREE.MeshStandardMaterial({
+    color: 0x8d949e,
+    roughness: 0.34,
+    metalness: 0.85,
+    side: THREE.DoubleSide,
+    wireframe,
+  });
+
+  const collar = new THREE.Mesh(collarGeometry, collarMaterial);
+  collar.name = 'collar';
+  collar.castShadow = castShadow;
+  collar.receiveShadow = receiveShadow;
+
+  // --- studs ---------------------------------------------------------------
+  // Contract rule 15: repetition is one InstancedMesh, never N meshes.
+  const studSize = Math.min(width, depth) * 0.09;
+  const studGeometry = new THREE.BoxGeometry(studSize, studSize * 0.6, studSize);
+  studGeometry.name = `${SLUG}-stud`;
+  const studMaterial = new THREE.MeshStandardMaterial({
+    color: 0x5f6570,
+    roughness: 0.45,
+    metalness: 0.6,
+    wireframe,
+  });
+
+  const studs = new THREE.InstancedMesh(studGeometry, studMaterial, STUD_COUNT);
+  studs.name = 'studs';
+  studs.castShadow = castShadow;
+  studs.receiveShadow = receiveShadow;
+  const matrix = new THREE.Matrix4();
+  const position = new THREE.Vector3();
+  const quaternion = new THREE.Quaternion();
+  const scale = new THREE.Vector3(1, 1, 1);
+  for (let i = 0; i < STUD_COUNT; i += 1) {
+    const angle = (i / STUD_COUNT) * Math.PI * 2;
+    const jitter = (random() - 0.5) * 0.05;
+    position.set(Math.sin(angle) * 0.38 * width, 0.038 * height + studSize * 0.3, Math.cos(angle) * 0.38 * depth);
+    quaternion.setFromAxisAngle(new THREE.Vector3(0, 1, 0), angle + jitter);
+    matrix.compose(position, quaternion, scale);
+    studs.setMatrixAt(i, matrix);
+  }
+  studs.instanceMatrix.needsUpdate = true;
+
+  // --- assembly ------------------------------------------------------------
+  const root = new THREE.Group();
+  root.name = SLUG;
+  root.add(body, collar, studs);
+
+  const nodes: Record<string, THREE.Object3D> = { body, collar, studs };
+  const meshes = [body, collar, studs];
+  const materials = [bodyMaterial, collarMaterial, studMaterial];
+  const geometries = [bodyGeometry, collarGeometry, studGeometry];
+  const textures = [bandTexture];
+
+  root.userData.assetRuntime = { nodes, meshes, materials, geometries };
+  root.userData.assetInfo = {
+    slug: SLUG,
+    name: NAME,
+    sizeMeters: [width, height, depth],
+    units: 'meters',
+    license: 'MIT',
+  };
+  root.userData.dispose = () => {
+    for (const geometry of geometries) geometry.dispose();
+    for (const material of materials) material.dispose();
+    for (const texture of textures) texture.dispose();
+  };
+
+  return root;
+}

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

@@ -0,0 +1,149 @@
+// Viewer bootstrap. Byte-identical in all ten asset projects - the only file
+// that varies is src/asset/<slug>.ts, which this module finds by glob rather
+// than by name so it never has to know which asset it is showing.
+//
+// Copied verbatim into every asset project and hashed by gate G13. Edit it in
+// packages/asset-viewer-template/template/src.
+
+import * as THREE from "three";
+import assetConfig from "../asset.config.json";
+import { createStage } from "./viewer/stage.js";
+import { createHud, showFault } from "./viewer/hud.js";
+import { installGateHooks, isGatesMode, measureStatic } from "./viewer/gates-overlay.js";
+
+const EXPLODE_SPREAD = 0.35;
+
+function resolveFactory() {
+  const modules = import.meta.glob("./asset/*.ts", { eager: true });
+  const paths = Object.keys(modules);
+  if (paths.length !== 1) {
+    throw new Error(`src/asset must hold exactly one module, found ${paths.length}: ${paths.join(", ") || "none"}`);
+  }
+  const module = modules[paths[0]];
+  const names = Object.keys(module).filter((n) => /^create[A-Z][A-Za-z0-9_]*Model$/.test(n));
+  if (names.length !== 1) {
+    throw new Error(`${paths[0]} must export exactly one create<Name>Model function, found ${names.length}`);
+  }
+  return { factory: module[names[0]], entry: names[0], path: paths[0] };
+}
+
+function setupExplode(root) {
+  const nodes = Object.values(root.userData?.assetRuntime?.nodes ?? {}).filter((n) => n && n.isObject3D);
+  const box = new THREE.Box3().setFromObject(root);
+  const centre = box.getCenter(new THREE.Vector3());
+  const diagonal = Math.max(box.getSize(new THREE.Vector3()).length(), 0.2);
+
+  // Push each part away from the model's centre along the direction of ITS OWN
+  // bounds, not its origin: assets are encouraged to bake offsets into geometry,
+  // so every part's `position` is usually (0,0,0) and origin-based directions
+  // would slide the whole model in one lump instead of taking it apart.
+  const parts = nodes.map((node) => {
+    const nodeCentre = new THREE.Box3().setFromObject(node).getCenter(new THREE.Vector3());
+    const direction = nodeCentre.sub(centre);
+    const offCentre = direction.length() > diagonal * 0.02;
+    return {
+      node,
+      home: node.position.clone(),
+      direction: offCentre ? direction.normalize() : null, // null → this part is the core, it stays
+    };
+  });
+  const scale = diagonal * EXPLODE_SPREAD;
+  return (t) => {
+    for (const part of parts) {
+      if (!part.direction) continue;
+      part.node.position.copy(part.home).addScaledVector(part.direction, t * scale);
+    }
+  };
+}
+
+function boot() {
+  const container = document.getElementById("stage");
+  const gates = isGatesMode();
+  const { factory } = resolveFactory();
+
+  const root = factory();
+  if (!root || !root.isObject3D) throw new Error("the asset factory must return a THREE.Group");
+
+  const stage = createStage({ container, deterministic: gates, groundShadow: assetConfig.viewer?.groundShadow !== false });
+  stage.assetRoot.add(root);
+
+  const statics = measureStatic(root);
+  const box = new THREE.Box3().setFromObject(root);
+  stage.fit(box, assetConfig.viewer?.cameraDistanceMul ?? 1);
+
+  document.title = `${assetConfig.name} - Genex asset`;
+  const hud = createHud(document);
+  hud.setAsset({ name: assetConfig.name, summary: assetConfig.summary });
+  hud.setStats({
+    sizeMeters: statics.sizeMeters,
+    triangles: statics.triangles,
+    drawCalls: statics.drawCalls,
+    materials: statics.materials,
+  });
+
+  const applyExplode = setupExplode(root);
+  let explodeTarget = 0;
+  let explode = 0;
+  let wireframe = false;
+
+  window.addEventListener("keydown", (event) => {
+    if (event.metaKey || event.ctrlKey || event.altKey) return;
+    const key = event.key.toLowerCase();
+    if (key === "w") {
+      wireframe = !wireframe;
+      root.traverse((obj) => {
+        const materials = Array.isArray(obj.material) ? obj.material : obj.material ? [obj.material] : [];
+        for (const material of materials) if ("wireframe" in material) material.wireframe = wireframe;
+      });
+      stage.invalidate();
+    } else if (key === "e") {
+      explodeTarget = explodeTarget > 0 ? 0 : 1;
+    } else if (key === " ") {
+      event.preventDefault();
+      stage.toggleTurntable();
+    } else if (key === "r") {
+      explodeTarget = 0;
+      // Snap the parts home BEFORE the bounds are measured below. setFromObject
+      // on a still-exploded model fits the camera to the blown-apart bounds, so
+      // reset left the asset standing smaller in frame than it started. Measured:
+      // pressing R twice fixed it, because the second press ran with the parts
+      // already retracted.
+      explode = 0;
+      applyExplode(0);
+      wireframe = false;
+      root.traverse((obj) => {
+        const materials = Array.isArray(obj.material) ? obj.material : obj.material ? [obj.material] : [];
+        for (const material of materials) if ("wireframe" in material) material.wireframe = false;
+      });
+      stage.fit(new THREE.Box3().setFromObject(root), assetConfig.viewer?.cameraDistanceMul ?? 1);
+    }
+  });
+
+  if (gates) {
+    // Deterministic pose: no turntable, no explode, camera at the framed home.
+    stage.setTurntable(false);
+    stage.renderOnce();
+    installGateHooks({ stage, root, factory, config: assetConfig, statics });
+    return;
+  }
+
+  stage.start((dt) => {
+    if (explode !== explodeTarget) {
+      const step = dt * 2.2;
+      explode = explodeTarget > explode ? Math.min(explodeTarget, explode + step) : Math.max(explodeTarget, explode - step);
+      applyExplode(explode);
+      stage.invalidate();
+      // Re-bake the ground shadow once the parts have settled, not on every
+      // frame of the animation: the turntable moves the camera rather than the
+      // model, so this is the only thing in the viewer that can change it.
+      if (explode === explodeTarget) stage.refreshShadow(new THREE.Box3().setFromObject(root));
+    }
+  });
+}
+
+try {
+  boot();
+} catch (error) {
+  console.error(error);
+  showFault(`Asset viewer failed to start.\n\n${error?.stack ?? error}`);
+}