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

package/templates/asset-viewer/tools/emit-manifest.mjs

@@ -0,0 +1,653 @@
+// The asset manifest - emitted here, stamped by stamp-manifest.mjs, read by the
+// dashboard through GET /api/projects/asset-manifest/:slug.
+//
+// This file is BOTH the Vite plugin (phase 1 of AG-859 §3.4) and the pure
+// helpers gates.mjs and stamp-manifest.mjs import, so the manifest shape, the
+// licence text and the source-scanning rules are defined exactly once.
+//
+// Copied verbatim into every asset project by scripts/new-asset.mjs and hashed
+// by gate G13. Edit it in packages/asset-viewer-template/template/tools - never
+// inside a scaffolded asset folder, or that folder fails its own build.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const SCHEMA_VERSION = 1;
+export const MANIFEST_KIND = "genex-asset";
+export const MANIFEST_FILENAME = "genex-asset.json";
+
+/** §1.1 hard ceiling. Enforced here (G14) and re-checked by the API. */
+export const MANIFEST_MAX_BYTES = 256 * 1024;
+
+/** The three revision every asset is built and gated against. */
+export const BUILT_AGAINST_THREE = "0.185.1";
+
+export const LICENSE_NOTICE =
+  "Free to use, modify and ship, commercially included. Keep the copyright line in the file.";
+
+export function mitLicenseText(holder, year) {
+  return [
+    "MIT License",
+    "",
+    `Copyright (c) ${year} ${holder}`,
+    "",
+    'Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:',
+    "",
+    "The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.",
+    "",
+    'THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.',
+  ].join("\n");
+}
+
+/**
+ * The file set gate G13 hashes. Every one of these is copied verbatim by
+ * scripts/new-asset.mjs; a hand-tweaked light in asset 7 fails its own build.
+ */
+export const SHARED_FILES = [
+  "index.html",
+  "vite.config.js",
+  "src/main.js",
+  "src/viewer/stage.js",
+  "src/viewer/hud.js",
+  "src/viewer/gates-overlay.js",
+  "tools/emit-manifest.mjs",
+  "tools/gates.mjs",
+  "tools/stamp-manifest.mjs",
+];
+
+/** Where new-asset.mjs records the hashes G13 compares against. */
+export const PARITY_FILENAME = "viewer-parity.json";
+
+export function sha256(input) {
+  return createHash("sha256")
+    .update(typeof input === "string" ? Buffer.from(input, "utf8") : input)
+    .digest("hex");
+}
+
+/**
+ * @param {string} projectDir
+ * @returns {Record<string, string | null>} sha256 per shared file; null when absent.
+ */
+export function hashSharedFiles(projectDir) {
+  /** @type {Record<string, string | null>} */
+  const out = {};
+  for (const rel of SHARED_FILES) {
+    const abs = path.join(projectDir, rel);
+    if (!fs.existsSync(abs)) {
+      out[rel] = null;
+      continue;
+    }
+    out[rel] = sha256(fs.readFileSync(abs));
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Source scanning (contract §4, gates G10/G11)
+// ---------------------------------------------------------------------------
+
+/**
+ * Drop line and block comments, leaving string literals intact.
+ * The forbidden-identifier scan runs on the stripped text so the MIT header -
+ * which is a comment - can never trip a gate about `window` or a URL.
+ */
+export function stripComments(code) {
+  let out = "";
+  let state = "code"; // code | line | block | sq | dq | tpl
+  let i = 0;
+  while (i < code.length) {
+    const c = code[i];
+    const d = code[i + 1];
+    if (state === "code") {
+      if (c === "/" && d === "/") {
+        state = "line";
+        i += 2;
+        continue;
+      }
+      if (c === "/" && d === "*") {
+        state = "block";
+        i += 2;
+        continue;
+      }
+      if (c === "'") state = "sq";
+      else if (c === '"') state = "dq";
+      else if (c === "`") state = "tpl";
+      out += c;
+      i += 1;
+      continue;
+    }
+    if (state === "line") {
+      if (c === "\n") {
+        state = "code";
+        out += c;
+      }
+      i += 1;
+      continue;
+    }
+    if (state === "block") {
+      if (c === "*" && d === "/") {
+        state = "code";
+        i += 2;
+      } else {
+        if (c === "\n") out += c;
+        i += 1;
+      }
+      continue;
+    }
+    // inside a string literal
+    if (c === "\\") {
+      out += c + (d ?? "");
+      i += 2;
+      continue;
+    }
+    if ((state === "sq" && c === "'") || (state === "dq" && c === '"') || (state === "tpl" && c === "`")) {
+      state = "code";
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * Every module specifier the file pulls in, static or dynamic. The contract
+ * allows exactly one: 'three'.
+ */
+export function parseImports(code) {
+  const src = stripComments(code);
+  const found = new Set();
+  const patterns = [
+    /\bimport\s[^;]*?\bfrom\s*['"]([^'"]+)['"]/g, // import x from 'y'
+    /\bimport\s*['"]([^'"]+)['"]/g, // import 'y'
+    /\bexport\s[^;]*?\bfrom\s*['"]([^'"]+)['"]/g, // export … from 'y'
+    /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g, // import('y')
+    /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g, // require('y')
+  ];
+  for (const re of patterns) {
+    for (const m of src.matchAll(re)) found.add(m[1]);
+  }
+  return [...found].sort();
+}
+
+/**
+ * G11's banned-construct list, plus G10's "no bare Math.random()".
+ * Scanned on comment-stripped source.
+ */
+const FORBIDDEN = [
+  { id: "document", re: /\bdocument\b/ },
+  { id: "window", re: /\bwindow\b/ },
+  { id: "fetch", re: /\bfetch\s*\(/ },
+  { id: "XMLHttpRequest", re: /\bXMLHttpRequest\b/ },
+  { id: "TextureLoader", re: /\bTextureLoader\b/ },
+  { id: "CanvasTexture", re: /\bCanvasTexture\b/ },
+  { id: "ImageBitmapLoader", re: /\bImageBitmapLoader\b/ },
+  { id: "three/examples", re: /three\/examples/ },
+  { id: "http-url", re: /\bhttps?:\/\// },
+  { id: "ShaderMaterial", re: /\bShaderMaterial\b/ },
+  { id: "onBeforeCompile", re: /\bonBeforeCompile\b/ },
+  { id: "performance", re: /\bperformance\s*\./ },
+];
+
+const NON_ERASABLE = [
+  { id: "enum", re: /(^|[^.\w])(?:const\s+)?enum\s+[A-Za-z_$]/ },
+  { id: "namespace", re: /(^|[^.\w])namespace\s+[A-Za-z_$]/ },
+  { id: "decorator", re: /^\s*@[A-Za-z_$][\w$]*\s*(\(|$)/m },
+];
+
+export function scanForbidden(code) {
+  const src = stripComments(code);
+  const hits = [];
+  for (const rule of FORBIDDEN) if (rule.re.test(src)) hits.push(rule.id);
+  for (const rule of NON_ERASABLE) if (rule.re.test(src)) hits.push(`non-erasable:${rule.id}`);
+  return hits;
+}
+
+export function usesBareMathRandom(code) {
+  return /\bMath\s*\.\s*random\s*\(/.test(stripComments(code));
+}
+
+/**
+ * The single exported factory. Contract §4.4: exactly one
+ * `export function create<PascalCase>Model`, plus its options interface.
+ */
+export function findFactory(code) {
+  const src = stripComments(code);
+  const names = [...src.matchAll(/export\s+function\s+(create[A-Z][A-Za-z0-9_]*Model)\s*\(/g)].map((m) => m[1]);
+  const unique = [...new Set(names)];
+  if (unique.length !== 1) {
+    throw new Error(
+      `expected exactly one "export function create<Name>Model", found ${unique.length}${unique.length ? ` (${unique.join(", ")})` : ""}`,
+    );
+  }
+  const optionsMatch = src.match(/export\s+interface\s+([A-Za-z0-9_]*Options)\b/);
+  return { entry: unique[0], optionsType: optionsMatch ? optionsMatch[1] : null };
+}
+
+/** Locate the one asset module. There is exactly one per project, by contract. */
+export function findAssetSource(projectDir) {
+  const dir = path.join(projectDir, "src", "asset");
+  const entries = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith(".ts")) : [];
+  if (entries.length !== 1) {
+    throw new Error(`src/asset must hold exactly one .ts module, found ${entries.length}: ${entries.join(", ") || "none"}`);
+  }
+  const filename = entries[0];
+  const absPath = path.join(dir, filename);
+  const code = fs.readFileSync(absPath, "utf8");
+  return { absPath, filename, code };
+}
+
+export function readAssetConfig(projectDir) {
+  const abs = path.join(projectDir, "asset.config.json");
+  const config = JSON.parse(fs.readFileSync(abs, "utf8"));
+  const missing = ["slug", "name", "summary", "statedSizeMeters", "triBand"].filter((k) => config[k] == null);
+  if (missing.length) throw new Error(`asset.config.json is missing: ${missing.join(", ")}`);
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// Building the manifest
+// ---------------------------------------------------------------------------
+
+export function pascalCase(slug) {
+  return slug
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((p) => p[0].toUpperCase() + p.slice(1))
+    .join("");
+}
+
+export function camelCase(slug) {
+  const p = pascalCase(slug);
+  return p ? p[0].toLowerCase() + p.slice(1) : p;
+}
+
+export function defaultPlayUrl(slug) {
+  return `https://preview--${slug}.genex.technology/`;
+}
+
+/**
+ * The slug this build is actually SERVED under.
+ *
+ * `asset.config.json` names the asset; the Genex project names the URL, and the two
+ * are not the same string. The project slug is derived from the title at `genex
+ * init` and can pick up a uniquifier on a collision - "Street Fire Hydrant" becomes
+ * `street-fire-hydrant`, not `fire-hydrant`. Composing the play URL from the config
+ * slug therefore pointed 7 of the first 10 assets at an origin that does not exist,
+ * and the dashboard's "look at it turning" link was dead on every one of them.
+ *
+ * `.genex/project.json` is written by the CLI and holds the real slug, so read it
+ * when it is there and fall back to the config only for a project that has not been
+ * created yet. Keeping two slugs in sync by hand is not a fix; not needing to is.
+ */
+export function servedSlug(projectDir, configSlug) {
+  try {
+    const raw = fs.readFileSync(path.join(projectDir, ".genex", "project.json"), "utf8");
+    const slug = JSON.parse(raw)?.slug;
+    if (typeof slug === "string" && slug.length > 0) return slug;
+  } catch {
+    // Not linked yet (or unreadable): the config slug is the best guess available.
+  }
+  return configSlug;
+}
+
+function formatSize(size) {
+  return size.map((n) => n.toFixed(2)).join(" × ") + " m";
+}
+
+export function buildUsage(config, entry, filename) {
+  const varName = camelCase(config.slug);
+  const module = `./${filename.replace(/\.ts$/, "")}`;
+  const snippet = [
+    `import { ${entry} } from '${module}';`,
+    "",
+    `const ${varName} = ${entry}();`,
+    `${varName}.position.set(2, 0, -3);`,
+    `scene.add(${varName});`,
+  ].join("\n");
+  const promptHint =
+    config.promptHint ??
+    `A ${formatSize(config.statedSizeMeters)} ${config.name.toLowerCase()}. Units are metres, Y-up, +Z forward, and the origin sits at the base centre on y = 0 - drop it straight onto your ground plane with position.set(x, groundY, z). Share one instance's materials if you place many, and call root.userData.dispose() when you remove it.`;
+  return { snippet, promptHint };
+}
+
+/**
+ * Phase 1: everything knowable without a browser. `geometry` and the measured
+ * half of `space` stay null until stamp-manifest.mjs writes the gate results in.
+ */
+export function buildBaseManifest({ config, source, entry, optionsType, imports, generatedAt, playUrl }) {
+  const holder = config.license?.holder ?? "Genex";
+  const year = config.license?.year ?? new Date(generatedAt).getUTCFullYear();
+  const usage = buildUsage(config, entry, source.filename);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    kind: MANIFEST_KIND,
+    generatedAt,
+    asset: {
+      slug: config.slug,
+      name: config.name,
+      summary: config.summary,
+      tags: config.tags ?? [],
+      materialClass: config.materialClass ?? "unclassified",
+      geometryClass: config.geometryClass ?? "unclassified",
+      difficulty: config.difficulty ?? "easy",
+      version: config.version ?? "1.0.0",
+    },
+    license: {
+      id: "MIT",
+      holder,
+      year,
+      notice: LICENSE_NOTICE,
+      text: mitLicenseText(holder, year),
+    },
+    source: {
+      filename: source.filename,
+      language: "ts",
+      entry,
+      optionsType,
+      imports,
+      minThreeRevision: config.minThreeRevision ?? 160,
+      builtAgainstThree: BUILT_AGAINST_THREE,
+      bytes: Buffer.byteLength(source.code, "utf8"),
+      sha256: sha256(source.code),
+      code: source.code,
+    },
+    usage,
+    geometry: null,
+    space: {
+      units: "meters",
+      up: "+Y",
+      forward: "+Z",
+      originRule: "base-centre",
+      boundingBox: null,
+      sizeMeters: null,
+      statedSizeMeters: config.statedSizeMeters,
+      sizeDeltaPct: null,
+    },
+    gates: { runAt: null, runner: "asset-gates@1", allPassed: false, results: [] },
+    preview: {
+      playUrl: config.previewPlayUrl ?? playUrl ?? defaultPlayUrl(config.slug),
+      views: ["front", "three-quarter", "side", "top"],
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Validation (G14). Mirrors the API's zod schema: tolerant of unknown keys,
+// strict on required ones, every string length-capped.
+// ---------------------------------------------------------------------------
+
+// INVARIANT: no cap here may be LOOSER than the matching one in the API's
+// assetManifestSchema (apps/api/src/assets/manifest.ts). A manifest that builds must
+// always validate server-side, because the API answers an invalid one with 422 and
+// the dashboard takes BOTH asset buttons off the page - a failure that surfaces in
+// production rather than in the build that caused it. Stricter here is fine and is
+// the safe direction: it fails where the author can see it.
+//
+// Four of these were looser and have been brought in line (filename 160→120,
+// importName 120→80, url 400→300, gateName 64→60). Nothing shipped was near those
+// windows, so this closes a latent gap rather than fixing a live break.
+const CAPS = {
+  slug: 64,
+  name: 120,
+  summary: 400,
+  tag: 32,
+  tags: 8,
+  className: 48,
+  version: 32,
+  holder: 120,
+  notice: 400,
+  licenseText: 8000,
+  filename: 120,
+  entry: 120,
+  optionsType: 120,
+  imports: 8,
+  importName: 80,
+  code: 200_000,
+  snippet: 4000,
+  promptHint: 2000,
+  url: 300,
+  gateId: 8,
+  gateName: 60,
+  gateThreshold: 160,
+  gateResults: 64,
+  views: 12,
+};
+
+function isFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+
+function checkString(errors, value, at, cap, { required = true } = {}) {
+  if (value == null) {
+    if (required) errors.push(`${at}: required`);
+    return;
+  }
+  if (typeof value !== "string") return void errors.push(`${at}: expected string`);
+  if (value.length === 0 && required) errors.push(`${at}: must not be empty`);
+  if (value.length > cap) errors.push(`${at}: longer than ${cap} chars (${value.length})`);
+}
+
+function checkVec3(errors, value, at, { required = true } = {}) {
+  if (value == null) {
+    if (required) errors.push(`${at}: required`);
+    return;
+  }
+  if (!Array.isArray(value) || value.length !== 3 || !value.every(isFiniteNumber)) {
+    errors.push(`${at}: expected 3 finite numbers`);
+  }
+}
+
+function checkCount(errors, value, at, { required = true } = {}) {
+  if (value == null) {
+    if (required) errors.push(`${at}: required`);
+    return;
+  }
+  if (!isFiniteNumber(value) || value < 0 || !Number.isInteger(value)) {
+    errors.push(`${at}: expected a non-negative integer`);
+  }
+}
+
+/**
+ * @param {unknown} manifest
+ * @param {{ requireMeasured?: boolean, requireAllPassed?: boolean, bytes?: number }} [opts]
+ */
+export function validateManifest(manifest, opts = {}) {
+  const errors = [];
+  const requireMeasured = opts.requireMeasured ?? true;
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+    return { ok: false, errors: ["manifest: expected an object"] };
+  }
+  const m = /** @type {Record<string, any>} */ (manifest);
+
+  if (m.schemaVersion !== SCHEMA_VERSION) errors.push(`schemaVersion: expected ${SCHEMA_VERSION}`);
+  if (m.kind !== MANIFEST_KIND) errors.push(`kind: expected "${MANIFEST_KIND}"`);
+  checkString(errors, m.generatedAt, "generatedAt", 40);
+
+  const a = m.asset;
+  if (typeof a !== "object" || a === null) errors.push("asset: required object");
+  else {
+    checkString(errors, a.slug, "asset.slug", CAPS.slug);
+    if (typeof a.slug === "string" && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(a.slug)) {
+      errors.push("asset.slug: expected kebab-case");
+    }
+    checkString(errors, a.name, "asset.name", CAPS.name);
+    checkString(errors, a.summary, "asset.summary", CAPS.summary);
+    if (!Array.isArray(a.tags)) errors.push("asset.tags: expected an array");
+    else if (a.tags.length > CAPS.tags) errors.push(`asset.tags: more than ${CAPS.tags} entries`);
+    else a.tags.forEach((t, i) => checkString(errors, t, `asset.tags[${i}]`, CAPS.tag));
+    checkString(errors, a.materialClass, "asset.materialClass", CAPS.className);
+    checkString(errors, a.geometryClass, "asset.geometryClass", CAPS.className);
+    checkString(errors, a.difficulty, "asset.difficulty", CAPS.className);
+    checkString(errors, a.version, "asset.version", CAPS.version);
+  }
+
+  const l = m.license;
+  if (typeof l !== "object" || l === null) errors.push("license: required object");
+  else {
+    if (l.id !== "MIT") errors.push('license.id: expected "MIT"');
+    checkString(errors, l.holder, "license.holder", CAPS.holder);
+    if (!isFiniteNumber(l.year) || l.year < 2000 || l.year > 2100) errors.push("license.year: expected a plausible year");
+    checkString(errors, l.notice, "license.notice", CAPS.notice);
+    checkString(errors, l.text, "license.text", CAPS.licenseText);
+  }
+
+  const s = m.source;
+  if (typeof s !== "object" || s === null) errors.push("source: required object");
+  else {
+    checkString(errors, s.filename, "source.filename", CAPS.filename);
+    if (s.language !== "ts") errors.push('source.language: expected "ts"');
+    checkString(errors, s.entry, "source.entry", CAPS.entry);
+    checkString(errors, s.optionsType, "source.optionsType", CAPS.optionsType, { required: false });
+    if (!Array.isArray(s.imports)) errors.push("source.imports: expected an array");
+    else if (s.imports.length > CAPS.imports) errors.push(`source.imports: more than ${CAPS.imports} entries`);
+    else s.imports.forEach((v, i) => checkString(errors, v, `source.imports[${i}]`, CAPS.importName));
+    if (!isFiniteNumber(s.minThreeRevision)) errors.push("source.minThreeRevision: expected a number");
+    checkString(errors, s.builtAgainstThree, "source.builtAgainstThree", CAPS.version);
+    checkCount(errors, s.bytes, "source.bytes");
+    if (typeof s.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(s.sha256)) errors.push("source.sha256: expected 64 hex chars");
+    checkString(errors, s.code, "source.code", CAPS.code);
+    if (typeof s.code === "string" && typeof s.bytes === "number" && Buffer.byteLength(s.code, "utf8") !== s.bytes) {
+      errors.push("source.bytes: does not match source.code");
+    }
+    if (typeof s.code === "string" && typeof s.sha256 === "string" && sha256(s.code) !== s.sha256) {
+      errors.push("source.sha256: does not match source.code");
+    }
+  }
+
+  const u = m.usage;
+  if (typeof u !== "object" || u === null) errors.push("usage: required object");
+  else {
+    checkString(errors, u.snippet, "usage.snippet", CAPS.snippet);
+    checkString(errors, u.promptHint, "usage.promptHint", CAPS.promptHint);
+  }
+
+  if (requireMeasured) {
+    const g = m.geometry;
+    if (typeof g !== "object" || g === null) errors.push("geometry: required object once stamped");
+    else {
+      for (const k of ["triangles", "vertices", "meshes", "instancedMeshes", "drawCalls", "materials", "textures", "textureBytes"]) {
+        checkCount(errors, g[k], `geometry.${k}`);
+      }
+    }
+  }
+
+  const sp = m.space;
+  if (typeof sp !== "object" || sp === null) errors.push("space: required object");
+  else {
+    if (sp.units !== "meters") errors.push('space.units: expected "meters"');
+    if (sp.up !== "+Y") errors.push('space.up: expected "+Y"');
+    if (sp.forward !== "+Z") errors.push('space.forward: expected "+Z"');
+    checkString(errors, sp.originRule, "space.originRule", CAPS.className);
+    checkVec3(errors, sp.statedSizeMeters, "space.statedSizeMeters");
+    if (requireMeasured) {
+      checkVec3(errors, sp.sizeMeters, "space.sizeMeters");
+      checkVec3(errors, sp.sizeDeltaPct, "space.sizeDeltaPct");
+      if (typeof sp.boundingBox !== "object" || sp.boundingBox === null) errors.push("space.boundingBox: required once stamped");
+      else {
+        checkVec3(errors, sp.boundingBox.min, "space.boundingBox.min");
+        checkVec3(errors, sp.boundingBox.max, "space.boundingBox.max");
+      }
+    }
+  }
+
+  const gt = m.gates;
+  if (typeof gt !== "object" || gt === null) errors.push("gates: required object");
+  else {
+    if (typeof gt.allPassed !== "boolean") errors.push("gates.allPassed: expected a boolean");
+    checkString(errors, gt.runner, "gates.runner", CAPS.gateName);
+    if (!Array.isArray(gt.results)) errors.push("gates.results: expected an array");
+    else if (gt.results.length > CAPS.gateResults) errors.push(`gates.results: more than ${CAPS.gateResults} entries`);
+    else {
+      gt.results.forEach((r, i) => {
+        if (typeof r !== "object" || r === null) return void errors.push(`gates.results[${i}]: expected an object`);
+        checkString(errors, r.id, `gates.results[${i}].id`, CAPS.gateId);
+        checkString(errors, r.name, `gates.results[${i}].name`, CAPS.gateName);
+        checkString(errors, r.threshold, `gates.results[${i}].threshold`, CAPS.gateThreshold);
+        if (typeof r.passed !== "boolean") errors.push(`gates.results[${i}].passed: expected a boolean`);
+      });
+    }
+    if (opts.requireAllPassed && gt.allPassed !== true) errors.push("gates.allPassed: expected true");
+  }
+
+  const p = m.preview;
+  if (typeof p !== "object" || p === null) errors.push("preview: required object");
+  else {
+    checkString(errors, p.playUrl, "preview.playUrl", CAPS.url);
+    if (typeof p.playUrl === "string" && !/^https:\/\//.test(p.playUrl)) errors.push("preview.playUrl: expected an https URL");
+    if (!Array.isArray(p.views)) errors.push("preview.views: expected an array");
+    else if (p.views.length > CAPS.views) errors.push(`preview.views: more than ${CAPS.views} entries`);
+  }
+
+  const bytes = opts.bytes ?? Buffer.byteLength(JSON.stringify(manifest), "utf8");
+  if (bytes > MANIFEST_MAX_BYTES) errors.push(`manifest: ${bytes} bytes exceeds the ${MANIFEST_MAX_BYTES} byte ceiling`);
+
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// The Vite plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * Writes dist/genex-asset.json at closeBundle with everything knowable without
+ * a browser, and FAILS THE BUILD when the asset module breaks the contract -
+ * a bad import can therefore never reach a manifest.
+ *
+ * @param {{ projectDir?: string, outDir?: string }} [options]
+ */
+export function emitManifest(options = {}) {
+  let resolvedRoot = options.projectDir ?? process.cwd();
+  let resolvedOut = options.outDir ?? "dist";
+  return {
+    name: "genex-emit-asset-manifest",
+    apply: "build",
+    configResolved(config) {
+      if (!options.projectDir) resolvedRoot = config.root;
+      if (!options.outDir) resolvedOut = config.build.outDir;
+    },
+    closeBundle() {
+      const config = readAssetConfig(resolvedRoot);
+      const source = findAssetSource(resolvedRoot);
+
+      const imports = parseImports(source.code);
+      if (imports.length !== 1 || imports[0] !== "three") {
+        this.error(
+          `[genex-asset] ${source.filename} may import 'three' and nothing else (contract §4.2). Found: ${imports.join(", ") || "none"}`,
+        );
+      }
+      const forbidden = scanForbidden(source.code);
+      if (forbidden.length) {
+        this.error(`[genex-asset] ${source.filename} uses banned constructs (contract §4): ${forbidden.join(", ")}`);
+      }
+
+      let factory;
+      try {
+        factory = findFactory(source.code);
+      } catch (err) {
+        return void this.error(`[genex-asset] ${source.filename}: ${err.message}`);
+      }
+
+      const manifest = buildBaseManifest({
+        config,
+        source,
+        entry: factory.entry,
+        optionsType: factory.optionsType,
+        imports,
+        generatedAt: new Date().toISOString(),
+        // The URL must name the slug this build is SERVED under, which the CLI
+        // records in .genex/project.json and which is not necessarily the config's.
+        playUrl: defaultPlayUrl(servedSlug(resolvedRoot, config.slug)),
+      });
+
+      const outDir = path.isAbsolute(resolvedOut) ? resolvedOut : path.join(resolvedRoot, resolvedOut);
+      fs.mkdirSync(outDir, { recursive: true });
+      fs.writeFileSync(path.join(outDir, MANIFEST_FILENAME), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+
+      const shape = validateManifest(manifest, { requireMeasured: false });
+      if (!shape.ok) this.error(`[genex-asset] emitted manifest is invalid: ${shape.errors.join("; ")}`);
+    },
+  };
+}
+
+export default emitManifest;