@zkmake/three-audit 0.5.0 → 0.6.1

package/README.md

@@ -52,7 +52,10 @@ or a `setupFiles` module:
 ```ts
 import "@zkmake/three-audit/vitest";
 
+import { expect, test } from "vitest";
+
 import budgets from "../src/budgets.ts";
+import { buildKart } from "../src/kart.ts";
 
 test("the kart", () => {
   const kart = buildKart();
@@ -81,10 +84,10 @@ A failure says what to fix, as the CLI does:
 ```
 
 `toFitBudget` takes `{ skip, top }` (meshes listed, default 5). A frame budget's `calls` counts as
-`draws`. The matchers work negated (`.not`) and as asymmetric matchers
-(`expect.toFitBudget(…)`), and their types come with the import. `installMatchers()` registers
-them again, for a setup that resets `expect`; `matchers` is the object for `expect.extend`. The
-entry re-exports `triangles`. Vitest 5 or later.
+`draws`; a budget that sets none of triangles, draws (calls) or meshes throws. The matchers work
+negated (`.not`) and as asymmetric matchers (`expect.toFitBudget(…)`), and their types come with
+the import. `installMatchers()` registers them again, for a setup that resets `expect`; `matchers`
+is the object for `expect.extend`. The entry re-exports `triangles`. Vitest 5 or later.
 
 ## Budgets
 
@@ -94,7 +97,7 @@ place.
 
 ```ts
 // src/budgets.ts
-import { defineBudgets } from "@zkmake/three-audit";
+import { defineBudgets } from "@zkmake/three-audit/budgets";
 
 export default defineBudgets({
   frame: { fps: 60, calls: 150, triangles: 250_000 },
@@ -115,10 +118,13 @@ export default defineBudgets({
 | `parts.*.draws`     | Draw calls one main pass makes for it (`countDraws`)                |
 | `parts.*.meshes`    | Visible meshes in it                                                |
 
+`@zkmake/three-audit/budgets` holds `defineBudgets` and `parseBudgets` (and their types) alone,
+with no imports, so the app's own code can import the file (its HUD reads it) and ship a few hundred
+bytes, not the checks; the main entry exports both too. `frame` is required, `parts` optional.
 `defineBudgets` returns them frozen, with each part in the type: `budgets.parts.truck` is an error
 when no truck is listed. `parseBudgets(value)` checks budgets from anywhere else (JSON) and throws
-on a bad key. `checkBudget(object, budget)` measures an object against one, a row per limit:
-`{ metric, actual, limit, over }`.
+on a bad key. `checkBudget(object, budget, { skip }?)`, in the main entry, measures an object
+against one, a row per limit: `{ metric, actual, limit, over }`.
 
 - In a test: `expect(kart).toFitBudget(budgets.parts.kart)`.
 - In the HUD: `mountPerfHud(monitor, { budgets })` (or `<PerfHud budgets={budgets} />`) applies the
@@ -145,9 +151,11 @@ windmill.glb  4,812 triangles, 14 draws
             …
 ```
 
-It exits 1 when any model fails a check (2 when one can't be read), so it can gate CI. Options:
-`--gap <m>`, `--self`, `--skip <regex>` (leave out objects by name, e.g. decals), `--top <n>`,
-`--json`, `--no-fail`.
+It exits 1 when any model fails a check (2 when one can't be read), so it can gate CI. Empty meshes
+are listed (`!`) but don't fail. Options: `--gap <m>`, `--self`, `--skip <regex>` (leave out
+objects by name, e.g. decals), `--top <n>` (default 5, 0 for none), `--json` (an array of
+`{ file, report, budget }`, `report` being `auditScene`'s), `--no-fail`,
+`-h` / `--help`, `-v` / `--version`.
 
 `--budgets <file>` also holds each model to the app's [budgets](#budgets): a JSON file, or a module
 whose default export is them (`.js`, or `.ts` where Node strips types). A model answers to the part
@@ -172,12 +180,18 @@ In a test, load a model the same way:
 ```ts
 import { findZFighting } from "@zkmake/three-audit";
 import { loadModel } from "@zkmake/three-audit/node";
+import { expect, test } from "vitest";
 
 test("windmill.glb has no z-fighting", async () => {
   expect(findZFighting(await loadModel("assets/windmill.glb"))).toEqual([]);
 });
 ```
 
+`parseModel(bytes, directory?)` does the same from bytes already read (GLB or glTF JSON, its
+buffers resolved from `directory`). `createNodeDracoLoader()` is the in-process Draco decoder it
+uses, for your own `GLTFLoader` in Node: it has the two methods `GLTFLoader` calls on a
+`DRACOLoader`, so pass it with a cast (`loader.setDRACOLoader(draco as never)`).
+
 glTF is in metres, which is what `--gap`'s default assumes. Instanced meshes
 (`EXT_mesh_gpu_instancing`) aren't checked for z-fighting; skinned and morphing meshes are
 checked in their rest pose.
@@ -198,23 +212,24 @@ const { scene, gl } = useThree();
 useLayoutEffect(() => installAuditHelpers(scene, { renderer: gl }), [scene, gl]);
 ```
 
-| Global                | Returns                                                                             |
-| --------------------- | ----------------------------------------------------------------------------------- |
-| `summary(tag?)`       | One count per check: the call to run after every edit                               |
-| `tris()`              | Triangles one pass draws: visible meshes, instances and batches counted, no culling |
-| `meshes()`            | Every visible mesh: triangles, instances, total, most first                         |
-| `census({ budget? })` | Geometries by triangles drawn, batches broken down, hidden meshes included          |
-| `audit()`             | Meshes with NaN positions or normals, or zero-length normals                        |
-| `zfight(gap?, self?)` | Pairs of meshes that z-fight                                                        |
-| `report(tag?)`        | Every check in one JSON-safe object                                                 |
-| `bbox(target)`        | An object's world envelope: min, max, size, centre                                  |
-| `clearance(a, b)`     | The gap between two objects, and which of their meshes come closest                 |
-| `ledger(options?)`    | One frame's draw calls by object and pass, and each pass's size (WebGL)             |
-| `beginLedger()`       | `{ end() }`: draw calls between the two, for any span you choose (WebGL)            |
-| `blackFrames(10)`     | Frames in the next 10 s that came out black (WebGL)                                 |
-
-A `tag` or `target` is a `userData.studioObject` value (or your `tagKey`), falling back to an
-object's name; `bbox` and `clearance` also take the object itself.
+| Global                        | Returns                                                                                          |
+| ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `summary(tag?, options?)`     | One count per check: the call to run after every edit. `{ zFighting: false }` skips the slow one |
+| `tris()`                      | Triangles one pass draws: visible meshes, instances and batches counted, no culling              |
+| `meshes()`                    | Every visible mesh: triangles, instances, total, most first                                      |
+| `census({ budget?, label? })` | Geometries by triangles drawn, batches broken down, hidden meshes included                       |
+| `audit()`                     | Meshes with NaN positions or normals, or zero-length normals                                     |
+| `zfight(gap?, self?)`         | Pairs of meshes that z-fight                                                                     |
+| `report(tag?)`                | Every check in one JSON-safe object                                                              |
+| `bbox(target)`                | An object's world envelope: min, max, size, centre                                               |
+| `clearance(a, b)`             | The gap between two objects, and which of their meshes come closest                              |
+| `ledger(options?)`            | One frame's draw calls by object and pass, and each pass's size (WebGL)                          |
+| `beginLedger()`               | `{ end() }`: draw calls between the two, for any span you choose (WebGL)                         |
+| `blackFrames(10)`             | `{ frames, blackFrames }`: frames in the next 10 s that came out black (WebGL)                   |
+| `auditRoot`                   | The root the helpers were installed on                                                           |
+
+A `tag` is a `userData.studioObject` value (or your `tagKey`); a tag nothing carries throws. A
+`target` (`bbox`, `clearance`) is a tag too, falling back to an object's name, or the object itself.
 
 ```js
 threeAudit.summary("bridge");
@@ -225,6 +240,11 @@ threeAudit.clearance("train", "tower");
 
 Each one is also on `threeAudit` (`threeAudit.report()`). Where short names like `report` collide
 with other tooling, `installAuditHelpers(scene, { globals: false })` installs only `threeAudit`.
+The other options: `renderer` (the WebGL renderer `ledger`, `beginLedger` and `blackFrames` need;
+without it they throw), `skip`, `tagKey`, [`bakes`](#baked-groups), and `batchLabel`, which names
+the geometries inside a batch in `census()` (`geometryCensus`'s `label`).
+[three-devtools](../three-devtools) installs them behind `?debug` (its `audit` option), and
+[three-studio](../three-studio)'s pages install them on their own scene.
 
 From a headless browser: `agent-browser eval 'JSON.stringify(threeAudit.report())'`.
 
@@ -268,7 +288,9 @@ between each other instead of over each other's ends.
 ### `findBadGeometry(root, options?)`
 
 Vertices with a non-finite position or normal, and zero-length normals on triangles with area.
-Either lights a pixel NaN, and bloom smears one NaN pixel into a black block.
+Either lights a pixel NaN, and bloom smears one NaN pixel into a black block. Hidden meshes are
+checked too. A row is `{ mesh, under, nonFinite, zeroNormals }`, `under` being the tagged part it
+sits in (or its parent's name). Options: `skip`, `tagKey`, `bakes`.
 
 ### `summarizeScene(root, options?)`
 
@@ -278,10 +300,12 @@ emptyMeshes }`. `tag` narrows it to one tagged object. `zFighting: false` skips
 
 ### `countTriangles`, `listMeshes`, `geometryCensus`, `countDraws`, `triangles`
 
-Where a triangle budget goes. `triangles(target)` is the one a test reaches for: a geometry's own
-triangles (`triangleCount`, within its draw range), or what an object draws (`countTriangles`). Name meshes and geometries (`mesh.name`, `geometry.name`) so the rows
-say something. A mesh row's `name` is its named ancestors, then its own name, or its geometry's name
-or type when it has none (`CharacterHands/left/BoxGeometry`).
+Where a triangle budget goes. `countTriangles` counts what one pass draws, with no culling; a shadow
+pass adds roughly as much again per shadow-casting light. `triangles(target)` is the one a test
+reaches for: a geometry's own triangles (`triangleCount`, within its draw range), or what an object
+draws (`countTriangles`). Name meshes and geometries (`mesh.name`, `geometry.name`) so the rows say
+something. A mesh row's `name` is its named ancestors, then its own name, or its geometry's name or
+type when it has none (`CharacterHands/left/BoxGeometry`).
 
 `geometryCensus` lists a `BatchedMesh` one geometry at a time: visible instances × triangles each,
 which is where a batch's budget actually goes. Rows are `batch#id` unless `label(batch, geometryId)`
@@ -294,29 +318,32 @@ treadmill_belt       570        513  292,410  0.306  true
 treadmill_coupler    570        297  169,290  0.177  false
 ```
 
-`countDraws` counts the draw calls one main pass makes: one per visible mesh, line or point cloud,
-one per material group when a mesh has several. It doesn't cull and doesn't count shadows; the draw
-ledger counts the real thing.
+`countDraws` counts the draw calls one main pass makes: one per visible mesh, line, point cloud or
+sprite, one per material group when a mesh has several. It doesn't cull and doesn't count shadows;
+the draw ledger counts the real thing.
 
-### `findEmptyMeshes(root)`
+### `findEmptyMeshes(root, options?)`
 
 Meshes with no vertices, such as what merging nothing leaves. Each one still costs a draw call and
 a geometry to dispose. A zero draw range doesn't count, since that's usually a pool waiting to fill.
+Hidden meshes are included; it takes `findBadGeometry`'s options.
 
-### `measureBounds(root, target)` / `measureClearance(root, a, b)`
+### `measureBounds(root, target, options?)` / `measureClearance(root, a, b, options?)`
 
 An object's world envelope, and the smallest gap between two objects, from their vertices as drawn:
 instances and batches included, rotations exact. The gap is measured between triangles' bounding
 boxes, which is exact for faces square to the axes and slightly under for sloped ones. So a tower
 merged into one mesh still measures to its crossbar, not to the box around the whole tower. `axis`
-says which way the gap runs when it's straight along one axis. Draw ranges are respected; a shadow pass adds roughly as much again per light.
+says which way the gap runs when it's straight along one axis (`null` when diagonal). Draw ranges
+are respected. A target matching nothing throws; one that draws nothing gives `null`. Options:
+`tagKey`, `bakes`.
 
 ### `recordDrawLedger(renderer)` / `beginDrawLedger(renderer)`
 
 Wraps `WebGLRenderer.renderBufferDirect` and counts every draw by object name, by group (the name up
-to its first `:` or `#`), and by pass: `shadow`, then each `render()` call by scene name, or
-`render 1`, `render 2`… An unnamed object goes by its named ancestors, type and material
-(`CharacterHands/Mesh [skin]`).
+to its first `:` or `#`, or your `groupOf(name)`), and by pass: `shadow`, then each `render()` call
+by scene name, or `render 1`, `render 2`… An unnamed object goes by its named ancestors, type and
+material (`CharacterHands/Mesh [skin]`).
 
 Each row (object or group) carries its draws per pass (`passes`) and its triangles, in all
 (`triangles`) and per pass (`passTriangles`): what a frame really draws of each part, so the city
@@ -325,7 +352,8 @@ pass, after culling them one by one.
 
 `recordDrawLedger` records exactly one animation frame, and fails after `timeout` (2 s) when no
 frame comes. `{ render }` records one call of your own render instead, frames or not.
-`beginDrawLedger` returns `{ end() }` for any span. `printDrawLedger` prints the tables.
+`beginDrawLedger` returns `{ end() }` for any span. `printDrawLedger` prints the tables;
+`ledgerTable(rows, passes)` is one of them as rows for `console.table`.
 
 `passStats` sizes each pass: draws, distinct objects (for `shadow`, the casters), triangles, and
 the targets drawn to in device pixels (`screen 2880×1800` for the canvas). A pass is `fullscreen`
@@ -336,14 +364,17 @@ pass. `fullscreenPasses` and `fullscreenPixels` total them: 8 fullscreen passes
 ### `watchBlackFrames(renderer)`
 
 After each render to the screen, reads a 3 × 3 grid of pixels and counts frames where three or more
-are pure black. Use a visible browser: headless ones haven't reproduced black frames. Each read
-stalls the GPU, so watch, read `blackFrames`, `stop()`.
+are pure black (options `grid` and `threshold` set the two numbers). Use a visible browser:
+headless ones haven't reproduced black frames. Each read stalls the GPU, so watch, read `frames`
+and `blackFrames` (which frames, 1-based), `stop()`; `reset()` starts the count over.
 
 ### `auditScene(root, options?)`
 
-`{ triangles, zFighting, badGeometry, meshes }` in one call. Rows carry the live mesh as a
-non-enumerable property (`row.mesh`, `row.meshes`), so they print and serialise without dragging the
-scene along.
+`{ triangles, draws, zFighting, badGeometry, emptyMeshes, meshes }` in one call, `meshes` the
+costliest `top` (default 10). `tag` narrows it to one tagged object. Rows carry the live mesh as a
+non-enumerable property (`row.mesh` on a mesh row, `row.meshes` and `row.pairs` on a z-fighting
+row, `row.object` on a bad or empty one), so they print and serialise without dragging the scene
+along.
 
 ## Baked groups
 

package/dist/{audit-scene-DHTFd-zs.js → audit-scene-BjB8raDp.js}

@@ -1,4 +1,4 @@
-import { a as countDraws, c as listMeshes, d as findEmptyMeshes, f as asObject3D, i as findZFighting, o as countTriangles, u as findBadGeometry, v as onlyTag } from "./budgets-DQggDhEu.js";
+import { c as findBadGeometry, g as onlyTag, i as countTriangles, l as findEmptyMeshes, n as findZFighting, o as listMeshes, r as countDraws, u as asObject3D } from "./budgets-BtXN-bkX.js";
 // src/audit-scene.ts
 /** The skip every check runs with: the caller's, narrowed to `tag` when given. */
 const scopeOf = (root, options) => options.tag === void 0 ? options.skip : onlyTag(asObject3D(root), options.tag, options.tagKey ?? "studioObject", options.skip);
@@ -66,4 +66,4 @@ const summarizeScene = (root, options = {}) => {
 };
 export { summarizeScene as n, auditScene as t };
 
-//# sourceMappingURL=audit-scene-DHTFd-zs.js.map
+//# sourceMappingURL=audit-scene-BjB8raDp.js.map

package/dist/{audit-scene-DHTFd-zs.js.map → audit-scene-BjB8raDp.js.map}

@@ -1 +1 @@
-{"version":3,"file":"audit-scene-DHTFd-zs.js","names":[],"sources":["../src/audit-scene.ts"],"sourcesContent":["import {\n  type BadGeometryRow,\n  type EmptyMeshRow,\n  findBadGeometry,\n  findEmptyMeshes,\n} from \"./bad-geometry.ts\";\nimport { type AnyObject3D, asObject3D, onlyTag, type Skip } from \"./scene.ts\";\nimport { countDraws, countTriangles, listMeshes, type MeshRow } from \"./triangles.ts\";\nimport { findZFighting, type ZFightingOptions, type ZFightingRow } from \"./z-fighting.ts\";\n\nexport type AuditSceneOptions = Pick<ZFightingOptions, \"bakes\" | \"gap\" | \"self\" | \"tagged\"> & {\n  skip?: Skip | undefined;\n  tagKey?: string;\n  /** Only the object(s) tagged this (`userData[tagKey]`): one studio object out of a scene. */\n  tag?: string | undefined;\n  /** How many of the costliest meshes to list. */\n  top?: number;\n};\n\nexport type AuditReport = {\n  triangles: number;\n  /** Draw calls one main pass makes, before culling and shadows: see `countDraws`. */\n  draws: number;\n  zFighting: ZFightingRow[];\n  badGeometry: BadGeometryRow[];\n  emptyMeshes: EmptyMeshRow[];\n  /** The costliest meshes, most triangles first. */\n  meshes: MeshRow[];\n};\n\n/** The skip every check runs with: the caller's, narrowed to `tag` when given. */\nconst scopeOf = (\n  root: AnyObject3D,\n  options: { skip?: Skip | undefined; tag?: string | undefined; tagKey?: string },\n) =>\n  options.tag === undefined\n    ? options.skip\n    : onlyTag(asObject3D(root), options.tag, options.tagKey ?? \"studioObject\", options.skip);\n\n/**\n * Every check at once, JSON-safe: what a test asserts on or a headless browser prints. A clean\n * scene has `zFighting`, `badGeometry` and `emptyMeshes` all `[]`.\n */\nexport const auditScene = (root: AnyObject3D, options: AuditSceneOptions = {}): AuditReport => {\n  const { tagKey, bakes } = options;\n  const skip = scopeOf(root, options);\n  const keyed = { skip, bakes, ...(tagKey === undefined ? {} : { tagKey }) };\n\n  return {\n    triangles: countTriangles(root, { skip }),\n    draws: countDraws(root, { skip }),\n    zFighting: findZFighting(root, {\n      ...options,\n      skip,\n      ...(options.tag === undefined ? {} : { tagged: true }),\n    }),\n    badGeometry: findBadGeometry(root, keyed),\n    emptyMeshes: findEmptyMeshes(root, keyed),\n    meshes: listMeshes(root, { skip }).slice(0, options.top ?? 10),\n  };\n};\n\nexport type AuditSummaryOptions = Pick<\n  AuditSceneOptions,\n  \"bakes\" | \"gap\" | \"skip\" | \"tag\" | \"tagKey\"\n> & {\n  /** Run the z-fighting check, the slow one. Default true; false gives `null` counts. */\n  zFighting?: boolean;\n};\n\nexport type AuditSummary = {\n  triangles: number;\n  draws: number;\n  meshes: number;\n  /** Pairs of meshes that z-fight, identical pairs counted each. */\n  zFighting: number | null;\n  /** Meshes that z-fight with themselves: merged geometry whose parts overlap. */\n  selfZFighting: number | null;\n  badGeometry: number;\n  emptyMeshes: number;\n};\n\n/**\n * Every check as one count each: the single call to run after every edit. `0` everywhere (and\n * `triangles`, `draws` where you expect them) is a pass. Use `auditScene` to see what failed.\n */\nexport const summarizeScene = (\n  root: AnyObject3D,\n  options: AuditSummaryOptions = {},\n): AuditSummary => {\n  const { tagKey, bakes } = options;\n  const skip = scopeOf(root, options);\n  const keyed = { skip, bakes, ...(tagKey === undefined ? {} : { tagKey }) };\n  let zFighting: number | null = null;\n  let selfZFighting: number | null = null;\n\n  if (options.zFighting !== false) {\n    zFighting = 0;\n    selfZFighting = 0;\n\n    for (const row of findZFighting(root, {\n      ...(options.gap === undefined ? {} : { gap: options.gap }),\n      ...(tagKey === undefined ? {} : { tagKey }),\n      ...(options.tag === undefined ? {} : { tagged: true }),\n      skip,\n      bakes,\n      self: true,\n    })) {\n      if (row.meshes[0] === row.meshes[1]) {\n        selfZFighting += row.count;\n      } else {\n        zFighting += row.count;\n      }\n    }\n  }\n\n  return {\n    triangles: countTriangles(root, { skip }),\n    draws: countDraws(root, { skip }),\n    meshes: listMeshes(root, { skip }).length,\n    zFighting,\n    selfZFighting,\n    badGeometry: findBadGeometry(root, keyed).length,\n    emptyMeshes: findEmptyMeshes(root, keyed).length,\n  };\n};\n"],"mappings":";;;AA+BA,MAAM,WACJ,MACA,YAEA,QAAQ,QAAQ,KAAA,IACZ,QAAQ,OACR,QAAQ,WAAW,IAAI,GAAG,QAAQ,KAAK,QAAQ,UAAU,gBAAgB,QAAQ,IAAI;;;;;AAM3F,MAAa,cAAc,MAAmB,UAA6B,CAAC,MAAmB;CAC7F,MAAM,EAAE,QAAQ,UAAU;CAC1B,MAAM,OAAO,QAAQ,MAAM,OAAO;CAClC,MAAM,QAAQ;EAAE;EAAM;EAAO,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;CAAG;CAEzE,OAAO;EACL,WAAW,eAAe,MAAM,EAAE,KAAK,CAAC;EACxC,OAAO,WAAW,MAAM,EAAE,KAAK,CAAC;EAChC,WAAW,cAAc,MAAM;GAC7B,GAAG;GACH;GACA,GAAI,QAAQ,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,KAAK;EACtD,CAAC;EACD,aAAa,gBAAgB,MAAM,KAAK;EACxC,aAAa,gBAAgB,MAAM,KAAK;EACxC,QAAQ,WAAW,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,OAAO,EAAE;CAC/D;AACF;;;;;AA0BA,MAAa,kBACX,MACA,UAA+B,CAAC,MACf;CACjB,MAAM,EAAE,QAAQ,UAAU;CAC1B,MAAM,OAAO,QAAQ,MAAM,OAAO;CAClC,MAAM,QAAQ;EAAE;EAAM;EAAO,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;CAAG;CACzE,IAAI,YAA2B;CAC/B,IAAI,gBAA+B;CAEnC,IAAI,QAAQ,cAAc,OAAO;EAC/B,YAAY;EACZ,gBAAgB;EAEhB,KAAK,MAAM,OAAO,cAAc,MAAM;GACpC,GAAI,QAAQ,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK,QAAQ,IAAI;GACxD,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;GACzC,GAAI,QAAQ,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,KAAK;GACpD;GACA;GACA,MAAM;EACR,CAAC,GACC,IAAI,IAAI,OAAO,OAAO,IAAI,OAAO,IAC/B,iBAAiB,IAAI;OAErB,aAAa,IAAI;CAGvB;CAEA,OAAO;EACL,WAAW,eAAe,MAAM,EAAE,KAAK,CAAC;EACxC,OAAO,WAAW,MAAM,EAAE,KAAK,CAAC;EAChC,QAAQ,WAAW,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;EACnC;EACA;EACA,aAAa,gBAAgB,MAAM,KAAK,CAAC,CAAC;EAC1C,aAAa,gBAAgB,MAAM,KAAK,CAAC,CAAC;CAC5C;AACF"}
+{"version":3,"file":"audit-scene-BjB8raDp.js","names":[],"sources":["../src/audit-scene.ts"],"sourcesContent":["import {\n  type BadGeometryRow,\n  type EmptyMeshRow,\n  findBadGeometry,\n  findEmptyMeshes,\n} from \"./bad-geometry.ts\";\nimport { type AnyObject3D, asObject3D, onlyTag, type Skip } from \"./scene.ts\";\nimport { countDraws, countTriangles, listMeshes, type MeshRow } from \"./triangles.ts\";\nimport { findZFighting, type ZFightingOptions, type ZFightingRow } from \"./z-fighting.ts\";\n\nexport type AuditSceneOptions = Pick<ZFightingOptions, \"bakes\" | \"gap\" | \"self\" | \"tagged\"> & {\n  skip?: Skip | undefined;\n  tagKey?: string;\n  /** Only the object(s) tagged this (`userData[tagKey]`): one studio object out of a scene. */\n  tag?: string | undefined;\n  /** How many of the costliest meshes to list. */\n  top?: number;\n};\n\nexport type AuditReport = {\n  triangles: number;\n  /** Draw calls one main pass makes, before culling and shadows: see `countDraws`. */\n  draws: number;\n  zFighting: ZFightingRow[];\n  badGeometry: BadGeometryRow[];\n  emptyMeshes: EmptyMeshRow[];\n  /** The costliest meshes, most triangles first. */\n  meshes: MeshRow[];\n};\n\n/** The skip every check runs with: the caller's, narrowed to `tag` when given. */\nconst scopeOf = (\n  root: AnyObject3D,\n  options: { skip?: Skip | undefined; tag?: string | undefined; tagKey?: string },\n) =>\n  options.tag === undefined\n    ? options.skip\n    : onlyTag(asObject3D(root), options.tag, options.tagKey ?? \"studioObject\", options.skip);\n\n/**\n * Every check at once, JSON-safe: what a test asserts on or a headless browser prints. A clean\n * scene has `zFighting`, `badGeometry` and `emptyMeshes` all `[]`.\n */\nexport const auditScene = (root: AnyObject3D, options: AuditSceneOptions = {}): AuditReport => {\n  const { tagKey, bakes } = options;\n  const skip = scopeOf(root, options);\n  const keyed = { skip, bakes, ...(tagKey === undefined ? {} : { tagKey }) };\n\n  return {\n    triangles: countTriangles(root, { skip }),\n    draws: countDraws(root, { skip }),\n    zFighting: findZFighting(root, {\n      ...options,\n      skip,\n      ...(options.tag === undefined ? {} : { tagged: true }),\n    }),\n    badGeometry: findBadGeometry(root, keyed),\n    emptyMeshes: findEmptyMeshes(root, keyed),\n    meshes: listMeshes(root, { skip }).slice(0, options.top ?? 10),\n  };\n};\n\nexport type AuditSummaryOptions = Pick<\n  AuditSceneOptions,\n  \"bakes\" | \"gap\" | \"skip\" | \"tag\" | \"tagKey\"\n> & {\n  /** Run the z-fighting check, the slow one. Default true; false gives `null` counts. */\n  zFighting?: boolean;\n};\n\nexport type AuditSummary = {\n  triangles: number;\n  draws: number;\n  meshes: number;\n  /** Pairs of meshes that z-fight, identical pairs counted each. */\n  zFighting: number | null;\n  /** Meshes that z-fight with themselves: merged geometry whose parts overlap. */\n  selfZFighting: number | null;\n  badGeometry: number;\n  emptyMeshes: number;\n};\n\n/**\n * Every check as one count each: the single call to run after every edit. `0` everywhere (and\n * `triangles`, `draws` where you expect them) is a pass. Use `auditScene` to see what failed.\n */\nexport const summarizeScene = (\n  root: AnyObject3D,\n  options: AuditSummaryOptions = {},\n): AuditSummary => {\n  const { tagKey, bakes } = options;\n  const skip = scopeOf(root, options);\n  const keyed = { skip, bakes, ...(tagKey === undefined ? {} : { tagKey }) };\n  let zFighting: number | null = null;\n  let selfZFighting: number | null = null;\n\n  if (options.zFighting !== false) {\n    zFighting = 0;\n    selfZFighting = 0;\n\n    for (const row of findZFighting(root, {\n      ...(options.gap === undefined ? {} : { gap: options.gap }),\n      ...(tagKey === undefined ? {} : { tagKey }),\n      ...(options.tag === undefined ? {} : { tagged: true }),\n      skip,\n      bakes,\n      self: true,\n    })) {\n      if (row.meshes[0] === row.meshes[1]) {\n        selfZFighting += row.count;\n      } else {\n        zFighting += row.count;\n      }\n    }\n  }\n\n  return {\n    triangles: countTriangles(root, { skip }),\n    draws: countDraws(root, { skip }),\n    meshes: listMeshes(root, { skip }).length,\n    zFighting,\n    selfZFighting,\n    badGeometry: findBadGeometry(root, keyed).length,\n    emptyMeshes: findEmptyMeshes(root, keyed).length,\n  };\n};\n"],"mappings":";;;AA+BA,MAAM,WACJ,MACA,YAEA,QAAQ,QAAQ,KAAA,IACZ,QAAQ,OACR,QAAQ,WAAW,IAAI,GAAG,QAAQ,KAAK,QAAQ,UAAU,gBAAgB,QAAQ,IAAI;;;;;AAM3F,MAAa,cAAc,MAAmB,UAA6B,CAAC,MAAmB;CAC7F,MAAM,EAAE,QAAQ,UAAU;CAC1B,MAAM,OAAO,QAAQ,MAAM,OAAO;CAClC,MAAM,QAAQ;EAAE;EAAM;EAAO,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;CAAG;CAEzE,OAAO;EACL,WAAW,eAAe,MAAM,EAAE,KAAK,CAAC;EACxC,OAAO,WAAW,MAAM,EAAE,KAAK,CAAC;EAChC,WAAW,cAAc,MAAM;GAC7B,GAAG;GACH;GACA,GAAI,QAAQ,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,KAAK;EACtD,CAAC;EACD,aAAa,gBAAgB,MAAM,KAAK;EACxC,aAAa,gBAAgB,MAAM,KAAK;EACxC,QAAQ,WAAW,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,OAAO,EAAE;CAC/D;AACF;;;;;AA0BA,MAAa,kBACX,MACA,UAA+B,CAAC,MACf;CACjB,MAAM,EAAE,QAAQ,UAAU;CAC1B,MAAM,OAAO,QAAQ,MAAM,OAAO;CAClC,MAAM,QAAQ;EAAE;EAAM;EAAO,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;CAAG;CACzE,IAAI,YAA2B;CAC/B,IAAI,gBAA+B;CAEnC,IAAI,QAAQ,cAAc,OAAO;EAC/B,YAAY;EACZ,gBAAgB;EAEhB,KAAK,MAAM,OAAO,cAAc,MAAM;GACpC,GAAI,QAAQ,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK,QAAQ,IAAI;GACxD,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;GACzC,GAAI,QAAQ,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,KAAK;GACpD;GACA;GACA,MAAM;EACR,CAAC,GACC,IAAI,IAAI,OAAO,OAAO,IAAI,OAAO,IAC/B,iBAAiB,IAAI;OAErB,aAAa,IAAI;CAGvB;CAEA,OAAO;EACL,WAAW,eAAe,MAAM,EAAE,KAAK,CAAC;EACxC,OAAO,WAAW,MAAM,EAAE,KAAK,CAAC;EAChC,QAAQ,WAAW,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;EACnC;EACA;EACA,aAAa,gBAAgB,MAAM,KAAK,CAAC,CAAC;EAC1C,aAAa,gBAAgB,MAAM,KAAK,CAAC,CAAC;CAC5C;AACF"}

package/dist/{budgets-DQggDhEu.js → budgets-BtXN-bkX.js}

@@ -676,57 +676,6 @@ const findZFighting = (scene, options = {}) => {
 	return [...rows.values()];
 };
 // src/budgets.ts
-const FRAME_KEYS = [
-	"fps",
-	"calls",
-	"triangles",
-	"textureMB"
-];
-const PART_KEYS = [
-	"triangles",
-	"draws",
-	"meshes"
-];
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** A copy of `value` with only `keys`, each a number ≥ 0, frozen. Throws naming `where`. */
-const limits = (value, keys, where) => {
-	if (!isRecord(value)) throw new TypeError(`three-audit: budgets ${where} must be an object`);
-	const out = {};
-	for (const [key, limit] of Object.entries(value)) {
-		if (!keys.includes(key)) throw new TypeError(`three-audit: budgets ${where} has "${key}"; expected ${keys.map((name) => `"${name}"`).join(", ")}`);
-		if (limit === void 0) continue;
-		if (typeof limit !== "number" || !(limit >= 0) || !Number.isFinite(limit)) throw new TypeError(`three-audit: budgets ${where}.${key} must be a number ≥ 0`);
-		out[key] = limit;
-	}
-	return Object.freeze(out);
-};
-/**
-* Checks budgets read from anywhere (a JSON file, a module) and returns them frozen. Throws a
-* `TypeError` naming the first bad key.
-*/
-const parseBudgets = (value) => {
-	if (!isRecord(value)) throw new TypeError("three-audit: budgets must be an object with `frame` and `parts`");
-	const parts = {};
-	if (value.parts !== void 0) {
-		if (!isRecord(value.parts)) throw new TypeError("three-audit: budgets parts must be an object of part budgets");
-		for (const [name, part] of Object.entries(value.parts)) parts[name] = limits(part, PART_KEYS, `parts.${name}`);
-	}
-	return Object.freeze({
-		frame: limits(value.frame ?? {}, FRAME_KEYS, "frame"),
-		parts: Object.freeze(parts)
-	});
-};
-/**
-* The app's budgets, typed and frozen: one file every reader imports.
-*
-*   export default defineBudgets({
-*     frame: { fps: 60, calls: 150, triangles: 250_000 },
-*     parts: { kart: { triangles: 7_500, draws: 12 } },
-*   });
-*
-* `budgets.parts.kart` is typed, and a part not listed is a type error.
-*/
-const defineBudgets = (budgets) => parseBudgets(budgets);
 /**
 * An object measured against a part budget (or the frame's `triangles` and `calls`), one row per
 * limit the budget sets. Nothing over is a pass.
@@ -751,6 +700,6 @@ const checkBudget = (root, budget, options = {}) => {
 	add("meshes", part.meshes, () => listMeshes(root, options).length);
 	return rows;
 };
-export { meshLabel as _, countDraws as a, triangleCount as b, listMeshes as c, findEmptyMeshes as d, asObject3D as f, isMesh as g, isInstanced as h, findZFighting as i, triangles as l, isBatched as m, defineBudgets as n, countTriangles as o, batchedTriangles as p, parseBudgets as r, geometryCensus as s, checkBudget as t, findBadGeometry as u, onlyTag as v, walk as x, pathOf as y };
+export { pathOf as _, geometryCensus as a, findBadGeometry as c, batchedTriangles as d, isBatched as f, onlyTag as g, meshLabel as h, countTriangles as i, findEmptyMeshes as l, isMesh as m, findZFighting as n, listMeshes as o, isInstanced as p, countDraws as r, triangles as s, checkBudget as t, asObject3D as u, triangleCount as v, walk as y };
 
-//# sourceMappingURL=budgets-DQggDhEu.js.map
+//# sourceMappingURL=budgets-BtXN-bkX.js.map