@zkmake/three-audit 0.2.2 → 0.3.1

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli/main.ts","../src/cli.ts"],"sourcesContent":["/**\n * `three-audit model.glb [more.gltf …]`: load each model in Node and check it for z-fighting and\n * NaN geometry. Exits 1 when a check fails, so it can gate CI; `--json` for machines.\n */\n/* oxlint-disable no-console -- a CLI's output is the console */\nimport { readFileSync } from \"node:fs\";\nimport { basename } from \"node:path\";\nimport { parseArgs } from \"node:util\";\n\nimport { type AuditReport, auditScene } from \"../audit-scene.ts\";\nimport { loadModel } from \"../node/load.ts\";\n\nconst HELP = `Usage: three-audit <model.glb|model.gltf>… [options]\n\nChecks glTF models for z-fighting (faces in one plane, facing the same way, overlapping) and\ngeometry that renders NaN (non-finite positions or normals, zero-length normals). Exits 1 when\nany model fails a check, 2 when a model can't be read.\n\nOptions:\n  --gap <m>       How close two planes count as one, in metres (default 0.004)\n  --self          Also check for z-fighting within each mesh (merged geometry)\n  --skip <regex>  Leave out objects whose name matches, and everything under them (decals)\n  --top <n>       List the n costliest meshes (default 5, 0 for none)\n  --json          Print the reports as JSON\n  --no-fail       Exit 0 even when a check fails\n  -h, --help      Show this help\n  -v, --version   Show the version\n\nDraco and Meshopt models need draco3dgltf / meshoptimizer installed alongside.`;\n\n/** This package's version: its package.json is the nearest one up from here (`src/cli` or `dist`). */\nconst version = () => {\n  for (let up = \"../\"; up.length <= 12; up += \"../\") {\n    try {\n      const pkg = JSON.parse(\n        readFileSync(new URL(`${up}package.json`, import.meta.url), \"utf8\"),\n      ) as {\n        name?: string;\n        version: string;\n      };\n\n      if (pkg.name === \"@zkmake/three-audit\") {\n        return pkg.version;\n      }\n    } catch {\n      // Not here; one more up.\n    }\n  }\n\n  return \"unknown\";\n};\n\nconst count = (value: number) => value.toLocaleString(\"en-US\");\n\nconst printReport = (file: string, report: AuditReport, top: number) => {\n  const lines = [`${basename(file)}  ${count(report.triangles)} triangles`];\n\n  if (report.zFighting.length === 0) {\n    lines.push(\"  ✓ no z-fighting\");\n  } else {\n    lines.push(\n      `  ✗ ${report.zFighting.length} z-fighting pair${report.zFighting.length === 1 ? \"\" : \"s\"}`,\n    );\n\n    for (const row of report.zFighting) {\n      const more = row.planes.length > 1 ? ` (+${row.planes.length - 1} more)` : \"\";\n      const copies = row.count > 1 ? `, ×${row.count} identical pairs` : \"\";\n\n      lines.push(\n        `      ${row.a}`,\n        `    ↔ ${row.b}`,\n        `      ${row.triangles} triangles in ${row.planes[0]}${more}; overlap ${row.overlap.area} m² at (${row.overlap.centre.join(\", \")})${copies}`,\n      );\n    }\n  }\n\n  if (report.badGeometry.length === 0) {\n    lines.push(\"  ✓ no NaN geometry\");\n  } else {\n    lines.push(\n      `  ✗ ${report.badGeometry.length} mesh${report.badGeometry.length === 1 ? \"\" : \"es\"} with NaN geometry`,\n    );\n\n    for (const row of report.badGeometry) {\n      lines.push(\n        `      ${row.mesh}${row.under ? ` (${row.under})` : \"\"}: ${row.nonFinite} non-finite, ${row.zeroNormals} zero normals`,\n      );\n    }\n  }\n\n  if (top > 0 && report.meshes.length > 0) {\n    lines.push(\"  most triangles:\");\n\n    for (const row of report.meshes) {\n      lines.push(\n        `      ${count(row.total).padStart(9)}  ${row.name}${row.instances > 1 ? ` ×${row.instances}` : \"\"}`,\n      );\n    }\n  }\n\n  return lines.join(\"\\n\");\n};\n\nexport const main = async (argv: string[]): Promise<number> => {\n  let parsed;\n\n  try {\n    parsed = parseArgs({\n      args: argv,\n      allowPositionals: true,\n      options: {\n        gap: { type: \"string\" },\n        self: { type: \"boolean\", default: false },\n        skip: { type: \"string\" },\n        top: { type: \"string\" },\n        json: { type: \"boolean\", default: false },\n        \"no-fail\": { type: \"boolean\", default: false },\n        help: { type: \"boolean\", short: \"h\", default: false },\n        version: { type: \"boolean\", short: \"v\", default: false },\n      },\n    });\n  } catch (error) {\n    console.error(`three-audit: ${(error as Error).message}\\n\\n${HELP}`);\n\n    return 2;\n  }\n\n  const { values, positionals } = parsed;\n\n  if (values.help) {\n    console.log(HELP);\n\n    return 0;\n  }\n\n  if (values.version) {\n    console.log(version());\n\n    return 0;\n  }\n\n  if (positionals.length === 0) {\n    console.error(HELP);\n\n    return 2;\n  }\n\n  const gap = values.gap === undefined ? undefined : Number(values.gap);\n  const top = values.top === undefined ? 5 : Number(values.top);\n\n  if ((gap !== undefined && !(gap > 0)) || !(top >= 0)) {\n    console.error(\"three-audit: --gap must be a positive number and --top zero or more\");\n\n    return 2;\n  }\n\n  const skipPattern = values.skip === undefined ? undefined : new RegExp(values.skip);\n  const results: { file: string; report?: AuditReport; error?: string }[] = [];\n\n  for (const file of positionals) {\n    try {\n      const scene = await loadModel(file);\n      const report = auditScene(scene, {\n        top,\n        ...(gap === undefined ? {} : { gap }),\n        ...(values.self ? { self: true } : {}),\n        ...(skipPattern ? { skip: (object) => skipPattern.test(object.name) } : {}),\n      });\n\n      results.push({ file, report });\n    } catch (error) {\n      results.push({ file, error: (error as Error).message });\n    }\n  }\n\n  if (values.json) {\n    console.log(JSON.stringify(results, null, 2));\n  } else {\n    console.log(\n      results\n        .map(({ file, report, error }) =>\n          report\n            ? printReport(file, report, top)\n            : `${basename(file)}\\n  ✗ couldn't read: ${error}`,\n        )\n        .join(\"\\n\\n\"),\n    );\n  }\n\n  if (results.some((result) => result.error !== undefined)) {\n    return 2;\n  }\n\n  const failed = results.some(\n    ({ report }) => report!.zFighting.length > 0 || report!.badGeometry.length > 0,\n  );\n\n  return failed && !values[\"no-fail\"] ? 1 : 0;\n};\n","#!/usr/bin/env node\n/** The `three-audit` bin. The work is in `cli/main.ts`, which the tests import. */\nimport { main } from \"./cli/main.ts\";\n\nprocess.exitCode = await main(process.argv.slice(2));\n"],"mappings":"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"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli/main.ts","../src/cli.ts"],"sourcesContent":["/**\n * `three-audit model.glb [more.gltf …]`: load each model in Node and check it for z-fighting and\n * NaN geometry. Exits 1 when a check fails, so it can gate CI; `--json` for machines.\n */\n/* oxlint-disable no-console -- a CLI's output is the console */\nimport { readFileSync } from \"node:fs\";\nimport { basename } from \"node:path\";\nimport { parseArgs } from \"node:util\";\n\nimport { type AuditReport, auditScene } from \"../audit-scene.ts\";\nimport { loadModel } from \"../node/load.ts\";\n\nconst HELP = `Usage: three-audit <model.glb|model.gltf>… [options]\n\nChecks glTF models for z-fighting (faces in one plane, facing the same way, overlapping) and\ngeometry that renders NaN (non-finite positions or normals, zero-length normals). Exits 1 when\nany model fails a check, 2 when a model can't be read.\n\nOptions:\n  --gap <m>       How close two planes count as one, in metres (default 0.004)\n  --self          Also check for z-fighting within each mesh (merged geometry)\n  --skip <regex>  Leave out objects whose name matches, and everything under them (decals)\n  --top <n>       List the n costliest meshes (default 5, 0 for none)\n  --json          Print the reports as JSON\n  --no-fail       Exit 0 even when a check fails\n  -h, --help      Show this help\n  -v, --version   Show the version\n\nDraco and Meshopt models need draco3dgltf / meshoptimizer installed alongside.`;\n\n/** This package's version: its package.json is the nearest one up from here (`src/cli` or `dist`). */\nconst version = () => {\n  for (let up = \"../\"; up.length <= 12; up += \"../\") {\n    try {\n      const pkg = JSON.parse(\n        readFileSync(new URL(`${up}package.json`, import.meta.url), \"utf8\"),\n      ) as {\n        name?: string;\n        version: string;\n      };\n\n      if (pkg.name === \"@zkmake/three-audit\") {\n        return pkg.version;\n      }\n    } catch {\n      // Not here; one more up.\n    }\n  }\n\n  return \"unknown\";\n};\n\nconst count = (value: number) => value.toLocaleString(\"en-US\");\n\nconst printReport = (file: string, report: AuditReport, top: number) => {\n  const lines = [\n    `${basename(file)}  ${count(report.triangles)} triangles, ${count(report.draws)} draws`,\n  ];\n\n  if (report.zFighting.length === 0) {\n    lines.push(\"  ✓ no z-fighting\");\n  } else {\n    lines.push(\n      `  ✗ ${report.zFighting.length} z-fighting pair${report.zFighting.length === 1 ? \"\" : \"s\"}`,\n    );\n\n    for (const row of report.zFighting) {\n      const more = row.planes.length > 1 ? ` (+${row.planes.length - 1} more)` : \"\";\n      const copies = row.count > 1 ? `, ×${row.count} identical pairs` : \"\";\n\n      lines.push(\n        `      ${row.a}`,\n        `    ↔ ${row.b}`,\n        `      ${row.triangles} triangles in ${row.planes[0]}${more}; overlap ${row.overlap.area} m² at (${row.overlap.centre.join(\", \")})${copies}`,\n      );\n    }\n  }\n\n  if (report.badGeometry.length === 0) {\n    lines.push(\"  ✓ no NaN geometry\");\n  } else {\n    lines.push(\n      `  ✗ ${report.badGeometry.length} mesh${report.badGeometry.length === 1 ? \"\" : \"es\"} with NaN geometry`,\n    );\n\n    for (const row of report.badGeometry) {\n      lines.push(\n        `      ${row.mesh}${row.under ? ` (${row.under})` : \"\"}: ${row.nonFinite} non-finite, ${row.zeroNormals} zero normals`,\n      );\n    }\n  }\n\n  if (report.emptyMeshes.length > 0) {\n    lines.push(\n      `  ! ${report.emptyMeshes.length} empty mesh${report.emptyMeshes.length === 1 ? \"\" : \"es\"} (no vertices)`,\n    );\n\n    for (const row of report.emptyMeshes) {\n      lines.push(`      ${row.mesh}`);\n    }\n  }\n\n  if (top > 0 && report.meshes.length > 0) {\n    lines.push(\"  most triangles:\");\n\n    for (const row of report.meshes) {\n      lines.push(\n        `      ${count(row.total).padStart(9)}  ${row.name}${row.instances > 1 ? ` ×${row.instances}` : \"\"}`,\n      );\n    }\n  }\n\n  return lines.join(\"\\n\");\n};\n\nexport const main = async (argv: string[]): Promise<number> => {\n  let parsed;\n\n  try {\n    parsed = parseArgs({\n      args: argv,\n      allowPositionals: true,\n      options: {\n        gap: { type: \"string\" },\n        self: { type: \"boolean\", default: false },\n        skip: { type: \"string\" },\n        top: { type: \"string\" },\n        json: { type: \"boolean\", default: false },\n        \"no-fail\": { type: \"boolean\", default: false },\n        help: { type: \"boolean\", short: \"h\", default: false },\n        version: { type: \"boolean\", short: \"v\", default: false },\n      },\n    });\n  } catch (error) {\n    console.error(`three-audit: ${(error as Error).message}\\n\\n${HELP}`);\n\n    return 2;\n  }\n\n  const { values, positionals } = parsed;\n\n  if (values.help) {\n    console.log(HELP);\n\n    return 0;\n  }\n\n  if (values.version) {\n    console.log(version());\n\n    return 0;\n  }\n\n  if (positionals.length === 0) {\n    console.error(HELP);\n\n    return 2;\n  }\n\n  const gap = values.gap === undefined ? undefined : Number(values.gap);\n  const top = values.top === undefined ? 5 : Number(values.top);\n\n  if ((gap !== undefined && !(gap > 0)) || !(top >= 0)) {\n    console.error(\"three-audit: --gap must be a positive number and --top zero or more\");\n\n    return 2;\n  }\n\n  const skipPattern = values.skip === undefined ? undefined : new RegExp(values.skip);\n  const results: { file: string; report?: AuditReport; error?: string }[] = [];\n\n  for (const file of positionals) {\n    try {\n      const scene = await loadModel(file);\n      const report = auditScene(scene, {\n        top,\n        ...(gap === undefined ? {} : { gap }),\n        ...(values.self ? { self: true } : {}),\n        ...(skipPattern ? { skip: (object) => skipPattern.test(object.name) } : {}),\n      });\n\n      results.push({ file, report });\n    } catch (error) {\n      results.push({ file, error: (error as Error).message });\n    }\n  }\n\n  if (values.json) {\n    console.log(JSON.stringify(results, null, 2));\n  } else {\n    console.log(\n      results\n        .map(({ file, report, error }) =>\n          report\n            ? printReport(file, report, top)\n            : `${basename(file)}\\n  ✗ couldn't read: ${error}`,\n        )\n        .join(\"\\n\\n\"),\n    );\n  }\n\n  if (results.some((result) => result.error !== undefined)) {\n    return 2;\n  }\n\n  const failed = results.some(\n    ({ report }) => report!.zFighting.length > 0 || report!.badGeometry.length > 0,\n  );\n\n  return failed && !values[\"no-fail\"] ? 1 : 0;\n};\n","#!/usr/bin/env node\n/** The `three-audit` bin. The work is in `cli/main.ts`, which the tests import. */\nimport { main } from \"./cli/main.ts\";\n\nprocess.exitCode = await main(process.argv.slice(2));\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BufferGeometry, Mesh, Object3D } from "three";
+import { BatchedMesh, BufferGeometry, Mesh, Object3D } from "three";
 //#region src/scene.d.ts
 /**
  * Any three.js object, from whichever copy of three's types the app has. The checks take this, so
@@ -10,6 +10,12 @@ type AnyObject3D = {
 };
 /** Leave an object and everything under it out of a check. */
 type Skip = (object: Object3D) => boolean;
+/**
+ * What a check sees of a bake (`@zkmake/three-batch`'s `bake` and `<Baked>`), which hides its
+ * parts and draws one merged mesh per material instead. `sources`: the parts, as if shown, and not
+ * the merge, so rows name real parts. `merged`: what the renderer draws.
+ */
+type Bakes = "sources" | "merged";
 /** Triangles one draw of this geometry makes: indexed or not, within its draw range. */
 export declare const triangleCount: (geometry: BufferGeometry) => number;
 //#endregion
@@ -18,6 +24,8 @@ type BadGeometryOptions = {
   skip?: Skip | undefined;
   /** `userData` key naming the part a mesh belongs to, for the `under` column. */
   tagKey?: string;
+  /** A bake's parts (default), or its merged meshes: see `Bakes`. Not both, or each counts twice. */
+  bakes?: Bakes | undefined;
 };
 type BadGeometryRow = {
   mesh: string;
@@ -32,6 +40,18 @@ type BadGeometryRow = {
 };
 /** Meshes with geometry that renders NaN, hidden ones included. `[]` is a pass. */
 export declare const findBadGeometry: (root: AnyObject3D, options?: BadGeometryOptions) => BadGeometryRow[];
+type EmptyMeshRow = {
+  /** `path/to/mesh [material]`. */
+  mesh: string;
+  /** Not enumerable: kept out of JSON and `console.table`. */
+  readonly object: Mesh;
+};
+/**
+ * Meshes with no vertices, hidden ones included: what a merge of nothing leaves behind. They draw
+ * nothing, but each one is still a draw call and a leak to dispose. A draw range of zero doesn't
+ * count: that's usually a pool waiting to fill.
+ */
+export declare const findEmptyMeshes: (root: AnyObject3D, options?: BadGeometryOptions) => EmptyMeshRow[];
 //#endregion
 //#region src/triangles.d.ts
 type TriangleOptions = {
@@ -41,7 +61,7 @@ type MeshRow = {
   /** `path/to/mesh`: its named ancestors, then its name (or its geometry's name or type). */
   name: string;
   material: string;
-  /** Triangles in one copy (a batch's average). */
+  /** Triangles in one copy. A batch's is an average: `geometryCensus` breaks it down. */
   triangles: number;
   instances: number;
   total: number;
@@ -49,12 +69,28 @@ type MeshRow = {
   readonly mesh: Mesh;
 };
 type GeometryRow = {
-  /** `geometry.name`, or its type and the start of its uuid. */
+  /**
+   * `geometry.name`, or its type and the start of its uuid. For a geometry in a batch, the batch's
+   * `label` for it, or `batch#id`.
+   */
   geometry: string;
   /** Copies drawn: every mesh using it, instances counted. */
   uses: number;
   triangles: number;
   total: number;
+  /** Its part of the census's total, 0–1. */
+  share: number;
+  /** With `budget`: whether `share` is over it. */
+  overBudget?: boolean;
+};
+type CensusOptions = TriangleOptions & {
+  /**
+   * Names a geometry inside a batch, e.g. from the app's own table of what it added. Default
+   * `batch#id`, the batch named by its path.
+   */
+  label?: ((batch: BatchedMesh, geometryId: number) => string | undefined) | undefined;
+  /** Flag rows whose share of the total is over this, 0–1: `0.2` for anything over 20%. */
+  budget?: number | undefined;
 };
 /**
  * Triangles one pass draws: visible meshes, instances counted, no frustum culling. A shadow pass
@@ -65,10 +101,16 @@ export declare const countTriangles: (root: AnyObject3D, options?: TriangleOptio
 export declare const listMeshes: (scene: AnyObject3D, options?: TriangleOptions) => MeshRow[];
 /**
  * Geometries by triangles drawn, hidden meshes included, most first. Name geometries
- * (`geometry.name`) to make this readable. Batches are left out: their shared buffer is not one
- * geometry; `listMeshes` counts them.
+ * (`geometry.name`) to make this readable. A batch counts each geometry in it separately, by its
+ * visible instances: the row a budget is really spent on.
+ */
+export declare const geometryCensus: (root: AnyObject3D, options?: CensusOptions) => GeometryRow[];
+/**
+ * Draw calls one main pass makes: one per visible mesh, line or point cloud, or one per material
+ * group for a mesh with several materials. Before frustum culling; each shadow-casting light adds
+ * one per caster. `recordDrawLedger` counts the real thing.
  */
-export declare const geometryCensus: (root: AnyObject3D, options?: TriangleOptions) => GeometryRow[];
+export declare const countDraws: (root: AnyObject3D, options?: TriangleOptions) => number;
 //#endregion
 //#region src/z-fighting.d.ts
 type ZFightingOptions = {
@@ -86,6 +128,11 @@ type ZFightingOptions = {
   tagged?: boolean;
   tagKey?: string;
   skip?: Skip | undefined;
+  /**
+   * A bake's parts (default), or its merged meshes: see `Bakes`. The parts name what to fix; the
+   * merge is the same faces under one name.
+   */
+  bakes?: Bakes | undefined;
 };
 type ZFightingRow = {
   /** `path/to/mesh [material] @ (x, y, z)`: named ancestors, and the centre in world space. */
@@ -114,24 +161,49 @@ type ZFightingRow = {
 export declare const findZFighting: (scene: AnyObject3D, options?: ZFightingOptions) => ZFightingRow[];
 //#endregion
 //#region src/audit-scene.d.ts
-type AuditSceneOptions = Pick<ZFightingOptions, "gap" | "self" | "tagged"> & {
+type AuditSceneOptions = Pick<ZFightingOptions, "bakes" | "gap" | "self" | "tagged"> & {
   skip?: Skip | undefined;
   tagKey?: string;
+  /** Only the object(s) tagged this (`userData[tagKey]`): one studio object out of a scene. */
+  tag?: string | undefined;
   /** How many of the costliest meshes to list. */
   top?: number;
 };
 type AuditReport = {
   triangles: number;
+  /** Draw calls one main pass makes, before culling and shadows: see `countDraws`. */
+  draws: number;
   zFighting: ZFightingRow[];
   badGeometry: BadGeometryRow[];
+  emptyMeshes: EmptyMeshRow[];
   /** The costliest meshes, most triangles first. */
   meshes: MeshRow[];
 };
 /**
  * Every check at once, JSON-safe: what a test asserts on or a headless browser prints. A clean
- * scene has `zFighting` and `badGeometry` both `[]`.
+ * scene has `zFighting`, `badGeometry` and `emptyMeshes` all `[]`.
  */
 export declare const auditScene: (root: AnyObject3D, options?: AuditSceneOptions) => AuditReport;
+type AuditSummaryOptions = Pick<AuditSceneOptions, "bakes" | "gap" | "skip" | "tag" | "tagKey"> & {
+  /** Run the z-fighting check, the slow one. Default true; false gives `null` counts. */
+  zFighting?: boolean;
+};
+type AuditSummary = {
+  triangles: number;
+  draws: number;
+  meshes: number;
+  /** Pairs of meshes that z-fight, identical pairs counted each. */
+  zFighting: number | null;
+  /** Meshes that z-fight with themselves: merged geometry whose parts overlap. */
+  selfZFighting: number | null;
+  badGeometry: number;
+  emptyMeshes: number;
+};
+/**
+ * Every check as one count each: the single call to run after every edit. `0` everywhere (and
+ * `triangles`, `draws` where you expect them) is a pass. Use `auditScene` to see what failed.
+ */
+export declare const summarizeScene: (root: AnyObject3D, options?: AuditSummaryOptions) => AuditSummary;
 //#endregion
 //#region src/black-frames.d.ts
 /** The `WebGLRenderer` methods the probe uses, typed loosely to fit any copy of three's types. */
@@ -170,6 +242,10 @@ export declare const watchBlackFrames: (renderer: ProbeRenderer, options?: Black
 type LedgerRenderer = {
   render(scene: AnyObject3D, camera: object): void;
   renderBufferDirect(camera: object, scene: object | null, geometry: object, material: object, object: AnyObject3D, group: unknown): void;
+  /** For pass sizes: the target being drawn to, `null` for the screen. */
+  getRenderTarget?(): unknown;
+  /** For pass sizes: the screen's drawing buffer, device pixels. */
+  getContext?(): unknown;
 };
 type DrawLedgerOptions = {
   /**
@@ -193,6 +269,18 @@ type LedgerRow = {
   /** Draws per pass name. */
   passes: Record<string, number>;
 };
+type PassRow = {
+  name: string;
+  draws: number;
+  /** Distinct objects drawn: for `shadow`, the casters. */
+  objects: number;
+  /** Triangles drawn, instances counted. */
+  triangles: number;
+  /** Sizes drawn to, in device pixels: `2880×1800`, or `screen 2880×1800`. */
+  targets: string[];
+  /** Every call was one small mesh through an orthographic camera: a post-processing pass. */
+  fullscreen: boolean;
+};
 type DrawLedger = {
   /**
    * Pass names in the order they first drew: `shadow`, then each `render()` call as its scene's
@@ -204,6 +292,11 @@ type DrawLedger = {
   /** By object name, most draws first. */
   objects: LedgerRow[];
   draws: number;
+  /** Each pass's draws, triangles, casters and target sizes, in `passes` order. */
+  passStats: PassRow[];
+  /** `render()` calls that drew one fullscreen pass, and the pixels they shaded between them. */
+  fullscreenPasses: number;
+  fullscreenPixels: number;
 };
 type DrawLedgerRecording = {
   /** Restore the renderer and return what was drawn since `beginDrawLedger`. */
@@ -234,6 +327,10 @@ type AuditHelpersOptions = {
   renderer?: (LedgerRenderer & ProbeRenderer) | undefined;
   skip?: Skip | undefined;
   tagKey?: string;
+  /** What checks see of a bake: its parts (default) or its merged meshes. See `Bakes`. */
+  bakes?: Bakes | undefined;
+  /** Names geometries inside a batch in `census()`: see `geometryCensus`'s `label`. */
+  batchLabel?: ((batch: BatchedMesh, geometryId: number) => string | undefined) | undefined;
   /**
    * Also put each helper on `globalThis` under its short name (`tris`, `report`…). Default true;
    * false leaves only `threeAudit`, for pages where short names collide with other tooling.
@@ -250,5 +347,40 @@ type AuditHelpersOptions = {
  */
 export declare const installAuditHelpers: (root: AnyObject3D, options?: AuditHelpersOptions) => () => void;
 //#endregion
-export type { AuditHelpersOptions, AuditReport, AuditSceneOptions, BadGeometryOptions, BadGeometryRow, BlackFrameOptions, BlackFrameWatch, DrawLedger, DrawLedgerOptions, DrawLedgerRecording, GeometryRow, LedgerRenderer, LedgerRow, MeshRow, ProbeRenderer, Skip, TriangleOptions, ZFightingOptions, ZFightingRow };
+//#region src/measure.d.ts
+type MeasureOptions = {
+  /** `userData` key a string target is looked up by. Default `studioObject`. */
+  tagKey?: string;
+  /** A bake's parts (default), or its merged meshes: see `Bakes`. The same space either way. */
+  bakes?: Bakes | undefined;
+};
+/** What to measure: an object, or a tag (`userData[tagKey]`), or failing that an object name. */
+type Target = string | AnyObject3D;
+type Bounds = {
+  min: [number, number, number];
+  max: [number, number, number];
+  size: [number, number, number];
+  centre: [number, number, number];
+};
+type Clearance = {
+  /**
+   * The smallest gap between the two, in world units. Measured between triangles' bounding boxes:
+   * exact for faces square to the axes, a slight underestimate for sloped ones. 0 when they touch
+   * or intersect.
+   */
+  gap: number;
+  /** The axis the gap is measured along, when it's straight along one; `null` when diagonal. */
+  axis: "x" | "y" | "z" | null;
+  /** The closest meshes, one from each side. */
+  between: [string, string];
+};
+/** A target's world envelope, from its visible meshes' vertices; `null` when it draws nothing. */
+export declare const measureBounds: (root: AnyObject3D, target: Target, options?: MeasureOptions) => Bounds | null;
+/**
+ * The gap between two targets, and which of their meshes come closest. Throws when a target
+ * matches nothing; `null` when either draws nothing. Meshes in both targets are left out of `a`.
+ */
+export declare const measureClearance: (root: AnyObject3D, a: Target, b: Target, options?: MeasureOptions) => Clearance | null;
+//#endregion
+export type { AnyObject3D, AuditHelpersOptions, AuditReport, AuditSceneOptions, AuditSummary, AuditSummaryOptions, BadGeometryOptions, BadGeometryRow, Bakes, BlackFrameOptions, BlackFrameWatch, Bounds, CensusOptions, Clearance, DrawLedger, DrawLedgerOptions, DrawLedgerRecording, EmptyMeshRow, GeometryRow, LedgerRenderer, LedgerRow, MeasureOptions, MeshRow, PassRow, ProbeRenderer, RecordDrawLedgerOptions, Skip, Target, TriangleOptions, ZFightingOptions, ZFightingRow };
 //# sourceMappingURL=index.d.ts.map