@woosh/meep-engine 2.163.10 → 2.164.0

package/src/core/geom/GEOMETRY_REVIEW_002_NAMING.md

@@ -0,0 +1,684 @@
+# GEOMETRY_REVIEW_002 — naming convention & rename plan
+
+`app/src/mir-engine/meep/src/core/geom`
+
+> Companion to **GEOMETRY_REVIEW_002_API_ISSUES.md**. This document proposes a single naming
+> convention for the whole geometry package, catalogues the overarching mismatches it resolves,
+> records the choices that need a human decision, and gives the full old→new rename table that
+> drives the refactor.
+
+## Why
+
+The package mixes (at least) three naming worlds: a dominant **type-prefix snake** style
+(`v3_`, `aabb3_`, `m4_`, `plane3_`, `quat3_`, `tm_`, `bt_`), a **verbose snake** style
+(`compute_triangle_area_3d`, `line_segment_compute_line_segment_intersection_array_2d`), and a
+**legacy camelCase** style (`computeConeBoundingBox`, `serializeAABB3`, `randomPointInBox`,
+`simplifyTopoMesh`). The user's flagship pair captures it: `line2_distance_to_point_sqr` and
+`line_segment_compute_line_segment_intersection_array_2d` both operate on 2D segments yet share
+no convention — and the first even lies (it clamps `t∈[0,1]`, so it is a *segment* distance, not
+a *line* distance).
+
+## Migration strategy (deprecated shims)
+
+Rename/move to the new name, then **leave a shim file at the old path** that re-exports the new
+symbol under the old name with an `@deprecated` JSDoc — matching the house style already used in
+e.g. `3d/shape/UnitCubeShape3D.js`. `meep` is a library: unreferenced exports are public
+surface, so we alias rather than delete. Shim shape:
+
+```js
+// 2d/line/line2_distance_to_point_sqr.js  (shim)
+import { line2_compute_segment_point_distance_sqr } from "./line2_compute_segment_point_distance_sqr.js";
+
+/**
+ * @deprecated Renamed to {@link line2_compute_segment_point_distance_sqr}. This function
+ * measures distance to a SEGMENT (it clamps t to [0,1]), not an infinite line.
+ */
+export const line2_distance_to_point_sqr = line2_compute_segment_point_distance_sqr;
+```
+
+Each shim is one-line + JSDoc; the move + shim is mechanical and reversible. Renames that **also**
+fix a correctness bug or change a signature (see the API-issues doc) must land the behavior fix
+and the shim together, and the shim must preserve the **old** signature where it differs.
+
+---
+
+## Status — applied vs deferred
+
+**Applied this session (~175 renames, every old name kept as an `@deprecated` re-export shim; `core/geom`
+test suite green — 302 suites / 1780 tests, including new regression specs):**
+
+- The **134 clean 1:1 renames** — the bulk: dimension tokens (`triangle2d_*`/`compute_*_3d` → `tri2_`/`tri3_`),
+  the `_array` overload split, `nearest`→`closest`, camelCase islands (`mat4`, `morton`, the triangle ray island),
+  redundant-token de-stutter, predicate/producer fixes, and the flagship `line2_distance_to_point_sqr` →
+  `line2_compute_segment_point_distance_sqr` and `line_segment_…_array_2d` → `segment2_segment_compute_intersection_array_2d`.
+- **34 family renames** — `random/`, `packing/max-rect/` (+`cost/`), `tm_vert*`/`tm_kill_only_*`, `bt_vert*`,
+  `computeTopoMesh*`, frustum `*_matrix4_project` → `frustum3_*`, `bt_face_get_{attached,neighbour}_faces`,
+  the `compute_tetrahedron_*` mesh-form dedup, `aabb3_project_to_2d`→`aabb3_projected_area`, `aabb3_raycast`→`aabb3_raycast_hit_point`, etc.
+- **~8 manual** — same-file export renames (`aabb_build_frustum`→`aabb3_build_frustum`, `sphere_matrix4_project`→
+  `sphere_matrix4_transform`, `bt_mesh_face_poke`→`bt_face_poke`), file-only renames (`m3_make_rotation.js`→
+  `m3_make_rotation_TBN.js`, `encode_unit3_hemioct.js`→`encode_unit_to_hemioct.js`), exporting the two dead
+  bug-functions (`compare_edges`, `aabb3_score_boxes_SAH_delta`), `aabb2_validate_packing`, and `fill_in_a_cavity`→`tetrahedral_mesh_fill_cavity`.
+- **8 multi-export file splits** (breaking changes, no shims — all importers were inside geom and were
+  rewritten): `lamber_azimuth/transform.js` → `lambert_azimuth/{encode_unit_to_azimuth,decode_azimuth_to_unit}.js`
+  (folder typo fixed); `spherical/sphere_map_transform.js` → `{encode_unit_to_spheremap,decode_spheremap_to_unit}.js`
+  (dead decode now exported); `build_face_graph_from_mesh.js` (split out `graph_create_off_mesh_links`);
+  `validate_tetrahedral_mesh.js` → 3 files; `bt_mesh_build_boundary_euclidean_distance_field.js` → 3 files
+  (the generic point-distance helper moved to `3d/line/segment3_point_distance_to_segments.js`);
+  `triangle_encode_rasterized_depth.js` → `{triangle_rasterized_depth_sample_index,triangle_decode_depth}.js`;
+  `collapseEdge.js` → `{collapse_edge,partial_edge_collapse}.js`;
+  `build_vertex_quadratics.js` → 4 files (`quadratics`→`quadrics`, shared border-penalty helper promoted).
+- The **6 correctness bugs + 2 latent traps** fixed at root with regression tests (see API_ISSUES §0).
+
+**Deferred (with reason):**
+
+- **Class methods/fields (~18)** — per decision, the OO value-type classes (`Vector*`, `Quaternion`, `AABB2/3`,
+  `Rectangle`, `ConicRay`, `StaticR2Tree`, `ConvexHullShape3D`, and the `TopoMesh.setFacedUnindexed` typo) keep
+  camelCase. Not renamed.
+- **Signature/param-only entries (~10)** — where the name is unchanged and only the signature needs work
+  (`quat3_integrate`/`gjk_epa_penetration`/`ray3_compose_array` add `out_offset`, `aabb3_expand_array` /
+  `polygon2_clip_axis_halfplane` output-first, `m3_determinant` array form, `vector_*_offset` param casing,
+  `v3_rigid_align_*`/`aabb3_transform_oriented_inverse` arg order). These are API-shape fixes tracked in
+  **GEOMETRY_REVIEW_002_API_ISSUES.md**, not renames.
+- **Pipeline consolidations (design, not mechanical)** — `simplifyTopoMesh`/`simplifyTopoMesh2` →
+  `_quadric`/`_decimate` (consolidate duplicate entry points), `qt_match_data_by_circle` → merge into
+  `qt_collect_by_circle` with an optional predicate. (These three files — plus
+  `decimate_edge_collapse_snap.js` — remain multi-export on purpose: they are the duplicate
+  decimation pipeline slated for consolidation, so splitting them piecemeal would be undone.)
+- **Debug-only** — `3d/tetrahedra/delaunay/debug/validate_cavity_boundary.js` (2 exports) left as-is.
+- **Windows case-only (cosmetic)** — `aabb3_score_boxes_SAH`→`sah`, `aabb3_*_mapping`→`AABB3_*_MAPPING`
+  constUpper. Need a git case-rename two-step on a case-insensitive filesystem; low value.
+- **Dead file** — `compute_legendre_polynomial.js` (0 bytes, exports nothing) — delete or implement.
+
+---
+
+## Part A — Proposed convention
+
+### A1. Type+dimension token and placement
+
+**Rule.** Use a single scheme for ALL free functions: <typetoken><verb_or_noun>_<qualifier>, where the type token is a glued lowercase abbreviation with the dimension digit glued directly to the type letter(s) and a trailing underscore: v2_ v3_ v4_ m2_ m3_ m4_ aabb2_ aabb3_ quat3_ line2_ line3_ ray3_ box3_ tri2_ tri3_ sphere_ circle_ capsule_ cone_ plane3_ frustum3_ tm_ bt_ sh3_/sh_ shape3_. The digit always means SPATIAL DIMENSION (or, for quat3_, the dimension of the rotated space), never 'number of operands' nor 'squared' nor a version. NEVER use a spelled-out _3d / _2d suffix on a typed primitive (so compute_triangle_area_3d -> tri3_area, triangle2d_* -> tri2_*). The glued-digit prefix WINS over the suffix form everywhere.
+
+*Why:* The glued-digit prefix (v3_, aabb3_, quat3_) is already the overwhelming majority across vec3/, mat*/, 3d/aabb/, 3d/quaternion/, 3d/topology/struct/binary/ and is what callers grep for. A single placement rule lets a reader predict the name and the arg-count from the token. Mixing _3d-suffix, prefix-digit, and bare tokens (the triangle/polygon mess) is the single largest source of unpredictability.
+
+- Good: `v3_distance_sqr`, `aabb3_intersects_ray`, `tri3_compute_area`, `line2_compute_segment_point_distance_sqr`, `quat3_multiply`
+- Current violators: `compute_triangle_area_3d`, `triangle2d_compute_area`, `orientation3_array (3=points not dim)`, `StaticR2Tree (R2 not 2)`, `spline_bezier2_2d (double dim token)`
+
+### A2. How non-vec primitives (triangle/line/ray/segment/box/sphere) carry dimension
+
+**Rule.** Every geometric primitive gets the same glued-digit prefix as vectors: tri2_/tri3_, line2_/line3_, ray2_/ray3_, box3_, plane3_, frustum3_, circle_ (2d-only, digit omitted because the type is inherently planar), sphere_/capsule_/cone_ (3d-only, digit omitted because inherently volumetric). When a primitive is mathematically tied to one dimension (circle=2d, sphere=3d), omit the digit; when it exists in both (triangle, line, ray, aabb), the digit is mandatory. A SEGMENT is named with the token 'segment' inside the line family, never as a bare 'line'.
+
+*Why:* Resolves the flagship 'line vs segment' lie and the triangle2d_/triangle3_/triangle_/compute_*_3d sprawl. Tying inherently-mono-dimensional types (circle/sphere) to a digitless token avoids meaningless tokens like circle2_ while keeping triangle/line/ray unambiguous.
+
+- Good: `tri3_compute_signed_volume`, `line3_compute_segment_point_distance_sqr`, `sphere_intersects_ray`, `circle_area`
+- Current violators: `line2_distance_to_point_sqr (actually a segment)`, `triangle_compute_signed_volume (no dim digit, is 3d)`, `orientation3_array`
+
+### A3. Verb prefix: compute_ vs bare noun vs bare verb
+
+**Rule.** PRODUCERS that derive a value/geometry use compute_ ONLY when the work is non-trivial computation that isn't already obvious from the noun; pure 'getter-like' derived quantities (area, length, centroid, surface_area, distance) use a BARE NOUN with no compute_. Rule of thumb: a scalar metric named by its physical quantity drops compute_ (v3_length, aabb3_surface_area, tri3_area, circle_area); an operation that builds a structured result or runs an algorithm keeps compute_ (aabb3_compute_from_triangle, quat3_compute_swing_twist, tri3_compute_barycentric). Apply uniformly within a family: do not have aabb2_compute_area next to aabb2_distance_to_point. PREDICATES never take a verb prefix.
+
+*Why:* The catalogs show compute_ applied arbitrarily (aabb2_compute_area vs aabb2_distance_to_point; m4_compute_normal_matrix3 vs m4_rotation_translation; box3_projected_half_extent vs aabb3_compute_projected_area). A 'metric=bare noun, algorithm/builder=compute_' rule is teachable and collapses the variance.
+
+- Good: `aabb3_surface_area`, `v3_length`, `tri3_compute_barycentric`, `aabb3_compute_from_triangle`
+- Current violators: `aabb2_compute_area`, `aabb3_compute_surface_area`, `m4_compute_normal_matrix3 (inconsistent with m4_rotation_translation)`, `triangle2d_get_barycentric (uses get_)`
+
+### A4. Predicate vs producer naming (bool vs geometry vs bare verb)
+
+**Rule.** THREE distinct shapes, three distinct name forms. (1) BOOLEAN predicate -> present-tense verb phrase: X_intersects_Y, X_contains_Y, X_is_<property>; returns a plain boolean, no output arg. Standardize box-vs-box overlap on intersects (aabb2_intersects_aabb2), NOT overlap_exists / compute_overlap. (2) GEOMETRY producer (writes a point/region/normal) -> X_compute_<thing>_intersection or X_<noun> writing into a leading (result, result_offset); may return a boolean 'did it exist' flag in addition to writing. (3) The BARE verb 'intersect' is BANNED as a public name (ambiguous between predicate and producer). Functions that return a 3-state / degree / classification are NOT predicates: name them X_classify_<thing> or X_<thing>_side / X_<thing>_containment, never intersects_*_degree.
+
+*Why:* Directly resolves the prompt's mandate. The catalogs show overlap_exists vs intersects_circle vs compute_overlap all meaning boolean overlap; and intersects_frustum_degree / aabb3_array_intersects_frustum_degree lying about returning a bool. A reader must be able to infer return shape from the verb.
+
+- Good: `aabb2_intersects_aabb2`, `sphere_contains_point`, `aabb3_classify_against_frustum`, `plane3_compute_3_plane_intersection`, `tm_edge_is_boundary`
+- Current violators: `aabb2_overlap_exists`, `aabb2_compute_overlap`, `aabb3_intersects_frustum_degree`, `sphere_intersects_point (is containment)`, `circle_intersects_point`
+
+### A5. nearest vs closest
+
+**Rule.** Pick CLOSEST everywhere; 'nearest' is banned as a public token. closest_point, closest_point_on_surface, line3_closest_points_segment_segment, aabb3_closest_point_on_surface, qt_query_closest_to_point. Rename every *nearest* symbol.
+
+*Why:* The repo already uses 'closest' in its load-bearing physics seam (closestHit/anyHit, gjk closest-feature) per project memory, and 50 files use nearest vs 30 closest — but the keystone API is 'closest', so converging on closest aligns the geom library with the physics/raycast contract it feeds. One word, package-wide.
+
+- Good: `aabb3_closest_point_on_surface`, `tri3_closest_point_barycentric`, `qt_query_closest_to_point`
+- Current violators: `aabb3_nearest_point_on_surface`, `AABB2.computeNearestPointToPoint`, `line3_compute_nearest_point_to_point`, `frustum3_computeNearestPointToPoint`, `tetrahedral_mesh_find_tets... (n/a)`
+
+### A6. _sqr placement
+
+**Rule.** _sqr is always the FINAL token of the name, after the full quantity-and-operands phrase: <prefix>_distance_sqr, <prefix>_distance_sqr_to_point, <prefix>_length_sqr, <prefix>_signed_distance_sqr_to_point. Never bury it mid-name as Sqr-before-To (distanceSqrTo) and never spell it 'Squared'/'2'. On class methods follow the same trailing rule: lengthSqr, distanceSqrTo is acceptable only because 'To<operand>' is the operand phrase; prefer distance_to_point_sqr style on free functions. The squared variant is the primitive; the non-sqr wrapper calls it and sqrt's.
+
+*Why:* The package already trends to trailing _sqr on free functions (v3_length_sqr, v3_distance_sqr, aabb2_signed_distance_sqr_to_point). The drift is in class methods (lengthSq/distanceToSquared) and the 'dist2_array'/'2'=squared abuse in convex-hull. One trailing-token rule removes the 'is the companion called _sqr or Squared or 2' guessing.
+
+- Good: `v3_distance_sqr`, `aabb2_signed_distance_sqr_to_point`, `bt_vertex_distance_to_vertex_sqr`
+- Current violators: `Vector3.distanceToSquared`, `Vector3.lengthSq`, `convex-hull dist2_array`
+
+### A7. Abbreviation policy for type tokens
+
+**Rule.** KEEP the established short type prefixes: v2_ v3_ v4_ m2_ m3_ m4_ aabb2_ aabb3_ quat3_ (these are universal, grep-stable, and documented). KEEP domain-mesh prefixes tm_ (TopoMesh ops) and bt_ (binary-topology ops) — they are large, internally-consistent families and renaming them would churn hundreds of call sites for no clarity gain; document them once at the module level. REPLACE qt_ -> keep (quad-tree is a coherent family) but FIX its verbs (see clusters). REPLACE shg_ -> keep (spatial-hash-grid family is consistent) and document. ELIMINATE the 'three'-as-count-or-vendor ambiguity, 'vert' abbreviation, and the m4-vs-mat3 param abbreviation drift. Spell out 'vertex' (not vert/verts), 'matrix' params as m2/m3/m4 (not mat3).
+
+*Why:* tm_/bt_/qt_/shg_ are not noise: each is a well-populated, internally-consistent namespace and meep is a library where churning public surface is costly (project memory: 'meep is a library'). The real abbreviation harm is the inconsistent ones (vert/verts/vertex; mat3 vs m4; aabb vs aabb2 in rectangle_to_aabb).
+
+- Good: `v3_dot`, `aabb3_intersects_ray`, `tm_edge_kill`, `bt_edge_collapse`, `shg_query_elements_circle`
+- Current violators: `tm_vert_kill (abbrev)`, `bt_merge_verts_by_distance`, `v3_matrix3_rotate param 'mat3'`, `rectangle_to_aabb (drops the 2)`
+
+### A8. camelCase -> snake_case migration
+
+**Rule.** All FREE FUNCTIONS are snake_case with the type prefix. Migrate every camelCase free-function island: 3d/random/* (randomPointInBox -> random_point_in_box ... but see open question on the 'In/On' token), packing/max-rect/* (packMaxRectangles -> pack_max_rectangles, costByRemainingArea -> cost_by_remaining_area), 3d/mat4/eulerAnglesFromMatrix -> m4_euler_angles, the morton camelHybrid (mortonEncode_magicbits -> v3_morton_encode_magicbits), the topology camelCase layer (simplifyTopoMesh, computeTopoMeshBoundingSphere, collapseEdge), the cone camel island (computeConePlaneSide -> cone_compute_plane_side), the camelCase triangle ray island (computeTriangleRayIntersection* -> tri3_ray_intersection*), the harmonics sh3 serializers stay snake. CLASSES remain PascalCase with camelCase methods IF they are engine-facing OO types (Vector3, Quaternion, AABB3, TetrahedralMesh) — that is the deliberate OO layer; but NEW data-structure classes should use snake_case methods to match the free-function layer (BVH2D, SpatialHashGrid already do). Do not mix casings WITHIN one class (fix StaticR2Tree, Cavity).
+
+*Why:* snake_case is the package norm for the perf/free-function layer; camelCase survives only as legacy islands and the deliberate OO vector/matrix/quaternion classes. The line is 'free functions + new struct methods = snake; established mutable OO value types = camelCase methods'. Mixed-casing within a single class is never acceptable.
+
+- Good: `random_point_in_box`, `m4_euler_angles`, `cone_compute_plane_side`, `Vector3.lengthSqr (OO method, camel ok)`
+- Current violators: `randomPointInBox`, `eulerAnglesFromMatrix`, `computeConePlaneSide`, `StaticR2Tree (mixed setBuffer + sort_morton)`, `simplifyTopoMesh`
+
+### A9. Vendor token (three vs threejs vs geometry)
+
+**Rule.** Use the single vendor token 'three' (not 'threejs') wherever a three.js type genuinely crosses a boundary, and CONFINE it to clearly adapter-named functions/modules (project memory: confine vendor imports to boundaries). Prefer the neutral token 'geometry' / 'buffer_geometry' when the function consumes an indexed/unindexed triangle buffer rather than a literal THREE type. Do NOT embed 'three' to disambiguate from the literal count three — rename plane3_three_compute_* to plane3_compute_3_plane_intersection_from_planes (object adapter) so 'three' never collides with '3'.
+
+*Why:* Catalogs show three/threejs/geometry used interchangeably (aabb3_from_threejs_geometry vs three_buffer_geometry_to_topo_mesh) and 'three' colliding with the count-3 in plane3_three_*. One spelling + boundary-confinement matches the existing project rule.
+
+- Good: `aabb3_from_three_geometry`, `three_buffer_geometry_to_topo_mesh`, `shape_mesh_from_geometry`
+- Current violators: `aabb3_from_threejs_geometry`, `plane3_three_compute_convex_3_plane_intersection`, `Vector4.threeApplyMatrix4`
+
+### A10. Disambiguating the overloaded _array suffix
+
+**Rule.** _array is RESERVED for exactly one meaning: 'this operand (the typed-array-of-scalars it qualifies) is accessed at a caller-supplied (buffer, offset)'. Apply consistently as a SUFFIX on the operand it describes, with the operand-type token preceding it (v3_*_array means the v3 operands are at offsets). FORBIDDEN alternate meanings: (a) 'returns a freshly allocated array' — name those *_to_new_array or just let them return and document the allocation, never bare _array; (b) 'array of MANY vectors / a batch' — use an explicit count param and a _batch or _v3_buffer token, e.g. aabb3_from_v3_buffer; (c) 'a packed single primitive [cx,cy,cz,r]' for sphere_array_* — rename to sphere_packed_* . The DOUBLE _array_array is banned: a single _array already implies offset operands (v3_dot_array, not v3_dot_array_array). PREFER suffix placement (v3_normalize_array) over prefix (v3_array_normalize) uniformly.
+
+*Why:* The prompt's mandate. _array carries 3-4 contradictory meanings across vec3/, aabb/, line/, mat4/. Pinning it to 'offset-addressed operand' (the dominant intent) and giving the other meanings their own tokens removes the ambiguity that makes the flagship name unreadable.
+
+- Good: `v3_dot_array`, `v3_normalize_array`, `aabb3_from_v3_buffer`, `sphere_packed_intersects_point`
+- Current violators: `v3_dot_array_array`, `v3_array_normalize (prefix)`, `line_segment_compute_line_segment_intersection_vectors_array_2d (allocates)`, `aabb3_array_compute_from_sphere (prefix)`, `sphere_array_intersects_point (packed)`
+
+### A11. Eliminating redundant token repetition
+
+**Rule.** A token that is already implied by the type prefix must not be repeated. circle_compute_circle_intersection -> circle_compute_intersection; sphere_projected_sphere_radius_sqr -> sphere_projected_radius_sqr; plane3_compute_plane_intersection -> plane3_compute_intersection; line_segment_compute_line_segment_intersection_* -> segment_segment_intersection_* (the operands are two segments; say segment once per operand role, not 'line_segment' twice). For class methods, the class IS the type token: Vector3.projectOntoVector3 -> projectOnto, computeNearestPointToPoint -> compute_closest_point (no PointToPoint doubling), tetrahedral_mesh_tet_get_neighbours -> tetrahedral_mesh_get_neighbours.
+
+*Why:* The flagship #2 (line_segment...line_segment) and many siblings stutter the type. Removing the repetition shortens names and is mechanically checkable (token appears twice).
+
+- Good: `segment_segment_intersection_2d`, `circle_compute_intersection`, `plane3_compute_intersection`, `Vector3.projectOnto`
+- Current violators: `line_segment_compute_line_segment_intersection_array_2d`, `circle_compute_circle_intersection`, `sphere_projected_sphere_radius_sqr`, `Vector3.projectOntoVector3`
+
+### A12. Output-argument placement and the (out, out_offset) pair
+
+**Rule.** For free functions that WRITE into a caller buffer: the output is ALWAYS the first parameter, immediately followed by its offset: (out, out_offset, ...inputs). Every such writer takes an out_offset even if it currently hardcodes 0. The output param is named 'result' for geometry/value writers and 'out' is also acceptable but pick ONE per family — standardize on 'result'/'result_offset'. Reducers (return a scalar) take NO output arg. Serializers/(de)serializers are the documented exception: (buffer, target) with buffer first. Batch/source-then-dest helpers that genuinely have one input and one output may use (output, output_offset, input, input_offset). The Vector3-object sink form (result.set(...)) is allowed only as a thin, separately-named wrapper (suffix _v3), never mixed into the flat-array family.
+
+*Why:* Output-first is already the strong majority and is the one thing most areas get right; the violations (mat4 apply_* output-3rd, aabb3_expand_array output-2nd, flip_23/flip_32 output-last, distance-field builders mesh-second) are the exceptions. Mandating out_offset everywhere kills the 'this sibling can't write at an offset' trap (ray3_array_compose, aabb3_nearest_point_on_surface, quat3_integrate, aabb2_from_v2_array).
+
+- Good: `v3_cross(result, result_offset, ...)`, `aabb3_array_set(result, result_offset, ...)`, `quat3_multiply(out, out_offset, ...)`
+- Current violators: `aabb3_expand_array(input, output, distance)`, `tetrahedral_mesh_flip_23(mesh,t1,t2,out)`, `quat3_createFromAxisAngle(axis,angle,result)`, `bt_mesh_build_boundary_distance_field(map, mesh, ...)`, `read_three_planes_to_array(planes, array)`
+
+### A13. Parameter naming uniformity
+
+**Rule.** The same role uses the same name across all siblings. Output buffer + offset: result, result_offset (not out/output/destination/target/r/data/array). Source buffer + offset: input, input_offset (not source/data/in). Element count: count (not n/length/dimensions/dimension_count — pick 'count' for item count, 'dimension_count' only when it literally means components-per-item). Queried point: point_x/point_y/point_z (not px/py/pz or ref_x or r_x). Plane 4th component: plane_constant (not w/dist/plane_offset/constant). Mesh handle: mesh (not tet_mesh/tetrahedra/data). Vertex: vertex / vertex_id (not v/vert/verts). Tet id: tet_id. Scalar multiplier sits immediately before its vector operand (BLAS axpy order).
+
+*Why:* Every catalog flagged 3-5 spellings for the identical concept. A fixed vocabulary is the cheapest, highest-leverage consistency win and is enforceable by lint.
+
+- Good: `(result, result_offset, input, input_offset, count)`, `point_x, point_y, point_z`, `plane_constant`
+- Current violators: `vector_copy 'length' vs vector_dot 'n' vs vector_scale_array 'dimensions'`, `aabb2 px/py vs point_x/point_y`, `plane 'w'/'dist'/'plane_offset'/'constant'`
+
+### A14. One export per file, file name matches export
+
+**Rule.** Each file exports exactly one public symbol whose name equals the filename (the established meep convention). Fix every filename/export mismatch (aabb3_build_frustum.js -> aabb_build_frustum, sphere_matrix4_transform.js -> sphere_matrix4_project, bt_face_poke.js -> bt_mesh_face_poke, m3_make_rotation.js -> m3_make_rotation_TBN, aabb3_compute_projected_area.js -> aabb3_project_to_2d). Split multi-export files (validate_tetrahedral_mesh.js, bt_mesh_build_boundary_euclidean_distance_field.js, build_face_graph_from_mesh.js, decimate_edge_collapse_snap.js, the lambert_azimuth/transform.js, triangle_encode_rasterized_depth.js). An export that is declared but never exported (aabb3_score_boxes_SAH_delta, decode_spheremap_to_unit, compareEdges, aabb2_validate_packing's 'validate') is a bug: either export it (it is public surface in a library) or delete if truly dead.
+
+*Why:* Discoverability-by-filename is a core meep convention; mismatches and multi-export files break grep-by-path and hide public surface. Library semantics (per memory) mean unexported-but-intended symbols are bugs to fix, not delete.
+
+- Good: `v3_cross.js exports v3_cross`
+- Current violators: `aabb3_build_frustum.js exports aabb_build_frustum`, `aabb3_score_boxes_SAH_delta.js exports nothing`, `compute_legendre_polynomial.js (0 bytes)`
+
+### A15. Casing of constants and acronyms
+
+**Rule.** Module-level frozen sentinels/identities are constUpper (M4_IDENTITY, NULL_POINTER, INVALID_NEIGHBOUR). Exported lookup tables that are conceptually constant data use constUpper too (AABB3_CORNER_EDGE_MAPPING). Embedded acronyms inside a snake_case function name are lowercased (aabb3_score_boxes_sah, not _SAH). Sentinel names for the same concept are unified across structures (one of NULL_POINTER) rather than NULL_NODE / NULL_POINTER / QT_NULL_POINTER.
+
+*Why:* Mixed-case SAH inside snake names and three different null-sentinel names are gratuitous variance; constUpper for true constants is already established (M2_IDENTITY, M4_IDENTITY).
+
+- Good: `M4_IDENTITY`, `aabb3_score_boxes_sah`, `NULL_POINTER`
+- Current violators: `aabb3_score_boxes_SAH`, `aabb3_corner_edge_mapping (lowercase data table)`, `NULL_NODE vs QT_NULL_POINTER`
+
+---
+
+## Part B — Overarching inconsistency clusters
+
+The convention mismatches across the package, by theme.
+
+### B1. array-token-overload — *major*
+
+The _array token carries 3-4 contradictory meanings (offset-addressed single operand as prefix vs suffix; returns-a-new-array; batch-of-many-vectors; packed single primitive) plus a double _array_array. Reserve _array=offset-addressed operand (suffix), and give the other meanings distinct tokens (_to_new_array, _buffer/_batch, _packed).
+
+Examples: `v3_array_normalize vs v3_negate_array vs v3_dot_array_array` · `line_segment_compute_line_segment_intersection_vectors_array_2d (allocates)` · `aabb3_array_compute_from_sphere (prefix) vs aabb3_expand_array (suffix=offset-0)` · `sphere_array_intersects_point (packed) vs sphere_radius_sqr_from_v3_array_transformed (batch)`
+
+### B2. dimension-token-placement — *major*
+
+Dimension is encoded five ways: glued prefix-digit (v3_/aabb3_), glued suffix (triangle2d_), verb-first _3d suffix (compute_triangle_area_3d), bare/no-digit-though-3d (triangle_compute_signed_volume), and digit-means-not-dimension (orientation3_array=3 points, StaticR2Tree=R2). Converge on glued prefix-digit; digit always = spatial dimension; omit digit only for inherently-mono-dimensional types (circle/sphere/capsule/cone).
+
+Examples: `triangle2d_compute_area / tri3 / triangle_compute_signed_volume / compute_triangle_area_3d` · `orientation3_array` · `spline_bezier2_2d` · `StaticR2Tree`
+
+### B3. misleading-name-lies-about-behavior — *major*
+
+Names that contradict behavior: segment functions named 'line'; transform functions named 'project'; predicates named 'intersects' that return a degree/number; 'create' that doesn't allocate; 'nearest' surface helpers that are containment; serializer 'quantize' comment on a dequantizer; quadric tensors named 'quadratics'.
+
+Examples: `line2_distance_to_point_sqr (segment)` · `sphere_matrix4_project (transforms)` · `aabb3_intersects_frustum_degree (returns 0/1/2)` · `quat3_createFromAxisAngle (no alloc)` · `sphere_intersects_point / circle_intersects_point (containment)` · `compute_*_vertex_quadratics (Quadric3)`
+
+### B4. redundant-token-repetition — *major*
+
+The type token is stuttered: line_segment...line_segment, circle_compute_circle_*, sphere_projected_sphere_*, plane3_compute_plane_*, NearestPointToPoint, projectOntoVector3, tetrahedral_mesh_tet_get_*.
+
+Examples: `line_segment_compute_line_segment_intersection_array_2d` · `circle_compute_circle_intersection` · `sphere_projected_sphere_radius_sqr` · `Vector3.projectOntoVector3`
+
+### B5. camelCase-legacy-islands — *major*
+
+Whole folders/files in camelCase against the snake_case norm: random/, packing/max-rect/, the topology camelCase layer, cone camel island, the camelCase triangle ray island, mat4 eulerAnglesFromMatrix, morton camel-hybrid. Migrate free functions to snake_case; keep deliberate OO value-type classes (Vector*/Quaternion/AABB3) camelCase-methoded but never mix casings within one class.
+
+Examples: `randomPointInBox` · `packMaxRectangles` · `simplifyTopoMesh` · `computeConePlaneSide` · `computeTriangleRayIntersection` · `eulerAnglesFromMatrix` · `StaticR2Tree (mixed within class)`
+
+### B6. predicate-vs-producer-vs-degree — *major*
+
+Boolean overlap tests have three names (intersects_/overlap_exists/compute_overlap); degree/classification functions wear the boolean 'intersects' prefix; bare verb 'intersect' is ambiguous. Standardize: intersects_/contains_/is_=bool, compute_*_intersection=geometry, classify_/_side=multi-state.
+
+Examples: `aabb2_overlap_exists vs aabb2_intersects_circle vs aabb2_compute_overlap` · `aabb3_intersects_frustum_degree` · `aabb3_array_intersects_frustum_degree` · `Rectangle.intersects vs Rectangle.overlaps`
+
+### B7. output-arg-placement-and-missing-offset — *major*
+
+Output buffer position flips (first/second/third/last) and many writers hardcode offset 0 with no out_offset param, breaking the pack-into-shared-buffer use case. Mandate (result, result_offset, ...) first, always with an offset.
+
+Examples: `aabb3_expand_array (output 2nd)` · `tetrahedral_mesh_flip_23/_32 (output last)` · `quat3_integrate (no offset)` · `ray3_array_compose (no offset)` · `aabb2_from_v2_array (hardcoded 0)` · `ray3_shift_origin_along_direction (offset-0 bug)`
+
+### B8. param-name-vocabulary-drift — *major*
+
+Identical roles get many names: count=n/length/dimensions/dimension_count; output=out/output/result/target/data/r/destination; queried point=px/ref_x/r_x/point_x; plane 4th=w/dist/plane_offset/constant; mesh=mesh/tet_mesh/tetrahedra/data; vertex=v/vert/verts/vertex; tet id has 5 spellings.
+
+Examples: `vector_copy length / vector_dot n / vector_scale_array dimensions` · `aabb2 px/py vs signed point_x/point_y` · `plane3 w/dist/plane_offset/constant` · `tet_index/tet/tet_id/tetrahedron_index/containing_tetra`
+
+### B9. filename-export-mismatch-and-multi-export — *major*
+
+Files whose single export name differs from the filename, files exporting 3-4 symbols, and declared-but-never-exported functions (dead public surface or latent bugs).
+
+Examples: `aabb3_build_frustum.js->aabb_build_frustum` · `sphere_matrix4_transform.js->sphere_matrix4_project` · `bt_face_poke.js->bt_mesh_face_poke` · `aabb3_score_boxes_SAH_delta (no export)` · `compute_legendre_polynomial.js (0 bytes)` · `validate_tetrahedral_mesh.js (3 exports)`
+
+### B10. correctness-bugs-surfaced-by-audit — *major*
+
+Genuine defects found while auditing names — must be fixed at root, not renamed around: y/x mix-ups, dead early returns, signed-distance-as-bool, unexported functions, offset-0 hardcoding bugs.
+
+Examples: `circle_intersects_point v2_distance(cx,cx,...)` · `circle_compute_circle_penetration dy=by-ax` · `aabb3_transformed_compute_plane_side signed-dist-as-bool` · `ray3_shift_origin_along_direction offset-0` · `aabb3_score_boxes_SAH_delta half-vs-full-area 2x` · `compareEdges compares v0 twice`
+
+> Note: a cataloguer also flagged a "dead `return indices_0`" in `triangle_encode_rasterized_depth`; on verification that claim was **false** (all three index branches are reachable) and has been dropped. The file still warrants the *naming* fix below (the export returns a vertex index, not encoded depth) and the multi-export split.
+
+### B11. nearest-vs-closest-synonym — *minor*
+
+'nearest' and 'closest' used interchangeably for the same closest-point/feature concept across line/ray/aabb/frustum/triangle/quad-tree. Converge on 'closest' to match the physics closestHit seam.
+
+Examples: `aabb3_nearest_point_on_surface vs line3_closest_points_segment_segment` · `frustum3_computeNearestPointToPoint` · `computeTriangleClosestPointToPointBarycentric` · `qt_query_data_nearest_to_point`
+
+### B12. sqr-placement-and-companion-coverage — *minor*
+
+_sqr buried mid-name on class methods (distanceToSquared/lengthSq) vs trailing on free functions; '2'-means-squared abuse; asymmetric sqr/non-sqr companion coverage. Trailing _sqr everywhere; the squared form is the primitive.
+
+Examples: `Vector3.distanceToSquared / lengthSq` · `convex-hull dist2_array` · `aabb3_signed_distance_sqr_to_point (no sqrt companion) vs aabb3_signed_distance_to_aabb3 (no sqr)`
+
+### B13. verb-prefix-inconsistency — *minor*
+
+compute_ / build_ / make_ / from_ / get_ applied arbitrarily to producers; bare-noun metrics sometimes carry compute_, sometimes not; m3 from_translation vs m4 make_translation.
+
+Examples: `aabb2_compute_area vs aabb2_distance_to_point` · `m3_cm_from_translation vs m4_make_translation` · `tetrahedral_mesh_build_* vs _compute_* vs _find_*` · `triangle2d_get_barycentric (get_)`
+
+### B14. out-param-and-return-shape-divergence — *minor*
+
+Sibling writers disagree on return shape (void vs return-out vs bool) and on Vector3-object-sink vs flat-array-sink; degree/scalar/bool returns hide behind shared prefixes; some methods return this, siblings return undefined.
+
+Examples: `m2_add void vs m2_transpose returns out vs m4_invert returns bool` · `Vector4.multiplyVector3 returns undefined` · `plane3 Vector3-sink vs flat-array-sink` · `qt_collect_* (count) vs qt_query_data_nearest (single datum)`
+
+### B15. vendor-token-three-vs-threejs-vs-geometry — *minor*
+
+three.js token spelled three/threejs/geometry and embedded where it collides with the literal count three; some vendor imports not confined to adapter boundaries.
+
+Examples: `aabb3_from_threejs_geometry vs three_buffer_geometry_to_topo_mesh` · `plane3_three_compute_convex_3_plane_intersection` · `Vector4.threeApplyMatrix4`
+
+### B16. abbreviation-vert-and-matrix-param — *minor*
+
+vertex abbreviated vert/verts/vertex; matrix params m4 vs mat3; quat vs qt vs Quaternion; immediate/in_place opaque tokens for add accumulate.
+
+Examples: `tm_vert_kill vs tm_vertex_compute_normal` · `bt_merge_verts_by_distance` · `v3_matrix3_rotate param mat3 vs m4` · `v3_array_immediate_add vs v3_array_add_in_place`
+
+---
+
+## Part C — Open questions (need a decision before mass-rename)
+
+Each of these is a genuine fork with churn implications; the rename table assumes the
+*recommended* option but they are called out so the direction can be confirmed.
+
+### C1. Should geometric primitives use a glued prefix-digit token (tri3_, line3_, box3_, plane3_) or keep some types digitless because they read fine without it (e.g. should the existing aabb3_/quat3_ digit style be forced onto sphere_/capsule_/cone_/circle_)?
+
+- A: glued prefix-digit on EVERYTHING, even inherently-mono-dimensional types (circle2_, sphere3_, capsule3_)
+- B: prefix-digit only for types that exist in multiple dimensions (triangle, line, ray, aabb, box, plane); digitless for inherently-mono-dimensional types (circle, sphere, capsule, cone)
+
+**Recommendation:** B. circle2_/sphere3_ add a meaningless token (a circle is always 2d, a sphere always 3d), and sphere_/capsule_/cone_ are already established digitless. Reserve the digit to disambiguate genuinely multi-dimensional families.
+
+### C2. How aggressively should the camelCase OO value-type classes (Vector2/3/4, Quaternion, AABB2/3, Matrix wrappers) be migrated? Their METHODS are camelCase while the entire free-function layer is snake_case.
+
+- A: Leave class methods camelCase forever (deliberate OO layer; matches three.js muscle memory and is huge call-site churn)
+- B: Migrate class methods to snake_case to match the free-function layer (one casing package-wide)
+- C: Freeze existing classes as camelCase but mandate snake_case methods on all NEW structure classes (BVH2D/SpatialHashGrid already do this)
+
+**Recommendation:** C. Full migration (B) is enormous churn on the most-referenced types for little gain and fights three.js familiarity; A leaves the rule unstated. C draws a clear, low-churn line: established mutable value types stay camelCase, new struct classes are snake_case — and bans within-class mixing (StaticR2Tree, Cavity).
+
+### C3. random/ samplers encode surface-vs-volume as an In/On preposition (randomPointInBox vs randomPointOnBox). Under snake_case, do we keep in/on or switch to explicit volume/surface tokens?
+
+- A: random_point_in_box / random_point_on_box (keep In/On preposition)
+- B: random_point_in_volume_box / random_point_on_surface_box (explicit)
+- C: box_sample_random_in_volume / box_sample_random_on_surface (type-first, mirrors AbstractShape3D.sample_random_point_in_volume)
+
+**Recommendation:** C for long-term consistency with the shape API (which already says sample_random_point_in_volume), but it is the highest-churn option and arguably over-engineered for a tiny self-contained folder; if churn is a concern, A is an acceptable minimal fix (snake the names, keep In/On). Flagging because the tradeoff is real.
+
+### C4. Output-argument convention for WRITERS: standardize on output-FIRST (result, result_offset, ...) everywhere, or keep the serializer/source-then-dest exceptions documented?
+
+- A: output-first universally; serializers are a single documented exception (buffer, target)
+- B: output-first for value/geometry writers, but allow (output, output_offset, input, input_offset) for pure transform/batch helpers and (dst, src) for copy-likes
+
+**Recommendation:** A with the serializer carve-out. Output-first is already the dominant, teachable rule; the (input,...,output) and output-last violations are pure inconsistency, not principled. Keep the serializer (buffer-first) exception because the buffer genuinely is both the medium and conventionally leads.
+
+### C5. Should the large domain-mesh prefixes tm_ (TopoMesh) and bt_ (binary topology) be spelled out or kept abbreviated, given the package otherwise spells out tokens (triangle->tri only as a proposal)?
+
+- A: Keep tm_/bt_ abbreviated (large internally-consistent families; meep is a library so renaming churns hundreds of call sites)
+- B: Spell out to topo_mesh_ / binary_topo_ for self-documentation
+
+**Recommendation:** A. These are coherent, heavily-used namespaces; per the 'meep is a library' rule, churning public surface for marginal readability is not worth it. Document the prefixes once at module level instead. (Contrast: 'vert' abbreviation IS worth fixing because it's applied inconsistently.)
+
+### C6. For the bounding-volume-of-N family, which canonical shape: <type>_compute_bounding_box / <type>_compute_bounding_of_N_<types>, or compute_bounding_<type>_of_N_<types>?
+
+- A: type-token-first: sphere_compute_bounding_of_2_spheres, cone_compute_bounding_of_2_cones, circle3_compute_bounding_box
+- B: verb-first: compute_bounding_sphere_of_2_spheres, compute_bounding_box (current mixed state, mostly verb-first)
+
+**Recommendation:** A (type-token-first) to match the package-wide prefix rule and make these greppable alongside the rest of each type's family. This contradicts the current verb-first majority in this corner, so it is a genuine choice with churn cost — flagging rather than silently picking.
+
+---
+
+## Part D — Rename table
+
+208 symbols violate the convention. Grouped by cluster; `[move]` marks a file relocation.
+
+### dimension-token-placement (30)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `compose_matrix4_array` | `m4_compose` | [3d/mat4/compose_matrix4_array.js](3d/mat4/compose_matrix4_array.js) <br>*[move → 3d/mat4/m4_compose.js]* | Normalize to m4_ prefix; drop redundant _array (a mat4 is always an array here). |
+| `decompose_matrix_4_array` | `m4_decompose` | [3d/mat4/decompose_matrix_4_array.js](3d/mat4/decompose_matrix_4_array.js) <br>*[move → 3d/mat4/m4_decompose.js]* | Normalize to m4_ prefix; mirror m4_compose stem; also stop calling private __setFromRotationMatrix (promote a public quat3_from_matrix3). |
+| `allocate_m4` | `m4_allocate` | [3d/mat4/allocate_m4.js](3d/mat4/allocate_m4.js) <br>*[move → 3d/mat4/m4_allocate.js]* | Type token must lead; matches v3_allocate. |
+| `rectangle_to_aabb` | `aabb2_from_rectangle` | [2d/rectangle_to_aabb.js](2d/rectangle_to_aabb.js) <br>*[move → 2d/aabb/aabb2_from_rectangle.js]* | Use the aabb2_ type prefix (mirrors aabb2_from_v2_buffer); produced type is AABB2 not 'aabb'; document the negative-size clamp. |
+| `aabb3_estimate_projected_area2` | `aabb3_estimate_projected_area` | [3d/aabb/aabb3_estimate_projected_area2.js](3d/aabb/aabb3_estimate_projected_area2.js) <br>*[move → 3d/aabb/aabb3_estimate_projected_area.js]* | Trailing '2' is a meaningless version suffix (no base name exists). |
+| `compute_aabb_from_points` | `aabb_nd_from_points` | [3d/aabb/compute_aabb_from_points.js](3d/aabb/compute_aabb_from_points.js) <br>*[move → 3d/aabb/aabb_nd_from_points.js]* | n-dimensional (controlled by d) — use aabb_nd_ token; type token must lead. |
+| `compute_triangle_group_aabb3` | `aabb3_from_triangle_group` | [3d/aabb/compute_triangle_group_aabb3.js](3d/aabb/compute_triangle_group_aabb3.js) <br>*[move → 3d/aabb/aabb3_from_triangle_group.js]* | aabb3 token must be a PREFIX not suffix; rename output/output_offset params to result/result_offset. |
+| `compute_bounding_sphere_of_2_spheres` | `sphere_compute_bounding_of_2_spheres` | [3d/sphere/compute_bounding_sphere_of_2_spheres.js](3d/sphere/compute_bounding_sphere_of_2_spheres.js) <br>*[move → 3d/sphere/sphere_compute_bounding_of_2_spheres.js]* | Type token must lead; unify with the bounding-volume naming rule; also use closed-form (drop per-call Miniball alloc). |
+| `compute_circle_bounding_box` | `circle3_compute_bounding_box` | [3d/compute_circle_bounding_box.js](3d/compute_circle_bounding_box.js) <br>*[move → 3d/circle3_compute_bounding_box.js]* | Operates in 3d (takes a normal) but name reads 2d; add dimension token. |
+| `compute_bounding_cone_of_2_cones` | `cone_compute_bounding_of_2_cones` | [3d/cone/compute_bounding_cone_of_2_cones.js](3d/cone/compute_bounding_cone_of_2_cones.js) <br>*[move → 3d/cone/cone_compute_bounding_of_2_cones.js]* | Type token leads; mirror sphere bounding naming. |
+| `spherical_from_cartesian` | `sphere_spherical_from_cartesian` | [3d/sphere/spherical_from_cartesian.js](3d/sphere/spherical_from_cartesian.js) <br>*[move → 3d/sphere/sphere_spherical_from_cartesian.js]* | Add sphere_ family prefix for discoverability (optional but consistent). |
+| `triangle2d_compute_area` | `tri2_signed_area` | [2d/triangle2d_compute_area.js](2d/triangle2d_compute_area.js) <br>*[move → 2d/triangle/tri2_signed_area.js]* | Glued-prefix-digit token tri2_; returns SIGNED area (encode sign); drop compute_ (bare metric). |
+| `triangle2d_get_barycentric` | `tri2_compute_barycentric` | [2d/triangle2d_get_barycentric.js](2d/triangle2d_get_barycentric.js) <br>*[move → 2d/triangle/tri2_compute_barycentric.js]* | tri2_ token; 'get_'->'compute_' (it solves); emit canonical [u,v,w] order. |
+| `triangle2d_contains_point` | `tri2_contains_point` | [2d/triangle2d_contains_point.js](2d/triangle2d_contains_point.js) <br>*[move → 2d/triangle/tri2_contains_point.js]* | tri2_ token; fix [u,v,w] read order to match producer. |
+| `compute_polygon_area_2d` | `polygon2_signed_area` | [2d/compute_polygon_area_2d.js](2d/compute_polygon_area_2d.js) <br>*[move → 2d/polygon/polygon2_signed_area.js]* | Glued prefix-digit polygon2_; drop compute_/2d suffix; signed. |
+| `fixed_convex_hull_humus` | `convex_hull_fixed_count_2d_bruteforce` | [2d/convex-hull/fixed_convex_hull_humus.js](2d/convex-hull/fixed_convex_hull_humus.js) <br>*[move → 2d/convex-hull/convex_hull_fixed_count_2d_bruteforce.js]* | Add dimension token; remove proper-noun 'humus'; describe behavior. |
+| `fixed_convex_hull_relaxation` | `convex_hull_fixed_count_2d_relaxation` | [2d/convex-hull/fixed_convex_hull_relaxation.js](2d/convex-hull/fixed_convex_hull_relaxation.js) <br>*[move → 2d/convex-hull/convex_hull_fixed_count_2d_relaxation.js]* | Add dimension token; fix JSDoc Float64/Float32 mismatch. |
+| `triangle_compute_signed_volume` | `tri3_compute_signed_volume` | [3d/triangle/triangle_compute_signed_volume.js](3d/triangle/triangle_compute_signed_volume.js) <br>*[move → 3d/triangle/tri3_compute_signed_volume.js]* | Bare 'triangle_' (no digit, is 3d) -> tri3_ prefix. |
+| `triangle_mesh_compute_signed_volume` | `tri3_mesh_compute_signed_volume` | [3d/triangle/triangle_mesh_compute_signed_volume.js](3d/triangle/triangle_mesh_compute_signed_volume.js) <br>*[move → 3d/triangle/tri3_mesh_compute_signed_volume.js]* | tri3_ token for the 3d triangle family. |
+| `compute_triangle_area_3d` | `tri3_area` | [3d/triangle/compute_triangle_area_3d.js](3d/triangle/compute_triangle_area_3d.js) <br>*[move → 3d/triangle/tri3_area.js]* | _3d suffix -> tri3_ prefix; bare-metric drops compute_; document UNSIGNED. |
+| `compute_triangle_normal` | `tri3_compute_normal_v3_objects` | [3d/triangle/compute_triangle_normal.js](3d/triangle/compute_triangle_normal.js) <br>*[move → 3d/triangle/tri3_compute_normal_v3_objects.js]* | Object-arg wrapper over v3_compute_triangle_normal; tri3_ prefix; add result_offset. |
+| `v3_compute_triangle_normal` | `tri3_compute_normal` | [3d/triangle/v3_compute_triangle_normal.js](3d/triangle/v3_compute_triangle_normal.js) <br>*[move → 3d/triangle/tri3_compute_normal.js]* | Canonical scalar core; move to tri3_ family (it produces a triangle normal, not a generic v3 op). |
+| `aabb3_compute_from_triangle` | `aabb3_compute_from_triangle` | [3d/triangle/aabb3_compute_from_triangle.js](3d/triangle/aabb3_compute_from_triangle.js) <br>*[move → 3d/triangle/aabb3_compute_from_triangle.js]* | Conforms; listed as exemplar of indexed-vertex calling convention. |
+| `triangle_intersects_clipping_volume` | `tri3_intersects_clipping_volume` | [3d/triangle/triangle_intersects_clipping_volume.js](3d/triangle/triangle_intersects_clipping_volume.js) <br>*[move → 3d/triangle/tri3_intersects_clipping_volume.js]* | tri3_ prefix. |
+| `triangle_compute_plane_side` | `tri3_compute_plane_side` | [3d/triangle/triangle_compute_plane_side.js](3d/triangle/triangle_compute_plane_side.js) <br>*[move → 3d/triangle/tri3_compute_plane_side.js]* | tri3_ prefix; fix 'ave' typo. |
+| `triangle3_incenter` | `tri3_incenter` | [3d/triangle/triangle3_incenter.js](3d/triangle/triangle3_incenter.js) <br>*[move → 3d/triangle/tri3_incenter.js]* | Standardize the spelled-out 'triangle3' -> tri3_ token used across the family. |
+| `shape_mesh_from_geometry` | `shape3_mesh_from_geometry` | [3d/shape/shape_mesh_from_geometry.js](3d/shape/shape_mesh_from_geometry.js) <br>*[move → 3d/shape/shape3_mesh_from_geometry.js]* | Optional dimension token for the shape family; keep 'geometry' (neutral, indexed-buffer). |
+| `shape3d_voxelize_to_grid` | `shape3_voxelize_to_grid` | [3d/shape/util/shape3d_voxelize_to_grid.js](3d/shape/util/shape3d_voxelize_to_grid.js) <br>*[move → 3d/shape/util/shape3_voxelize_to_grid.js]* | Use tri3_/aabb3_-style glued-prefix-digit token shape3_ (not shape3d_). |
+| `spline_bezier2_2d` | `spline2_quadratic_bezier` | [2d/spline_bezier2_2d.js](2d/spline_bezier2_2d.js) <br>*[move → 2d/spline2_quadratic_bezier.js]* | Double dimension token (bezier2 + _2d) and clashing order with spline2_bezier; use spline2_ prefix + spell quadratic. |
+| `normalize_angle_rad` | `normalize_angle_rad` | [normalize_angle_rad.js](normalize_angle_rad.js) <br>*[move → 1d/normalize_angle_rad.js]* | Name OK; relocate from geom root into a 1d/ (or math) subfolder for discoverability — the _rad unit token is fine. |
+
+### misleading-name-lies-about-behavior (26)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `line2_distance_to_point_sqr` | `line2_compute_segment_point_distance_sqr` | [2d/line/line2_distance_to_point_sqr.js](2d/line/line2_distance_to_point_sqr.js) <br>*[move → 2d/line/line2_compute_segment_point_distance_sqr.js]* | FLAGSHIP: clamp01 proves it measures distance to a SEGMENT, not an infinite line. Mirror the correctly-named 3d sibling line3_compute_segment_point_distance_sqr. |
+| `line_segment_intersection_fraction_2d` | `line2_segment_intersection_fraction_2d` | [2d/line/line_segment_intersection_fraction_2d.js](2d/line/line_segment_intersection_fraction_2d.js) <br>*[move → 2d/line/line2_segment_intersection_fraction_2d.js]* | First operand is an unbounded line, second a segment; encode both honestly (line2 + segment). |
+| `line3_compute_nearest_point_to_point` | `line3_compute_segment_closest_point` | [3d/line/line3_compute_nearest_point_to_point.js](3d/line/line3_compute_nearest_point_to_point.js) <br>*[move → 3d/line/line3_compute_segment_closest_point.js]* | Delegates to the SEGMENT variant (clamp01) so 'line' lies; 'nearest'->'closest'; drop PointToPoint stutter. |
+| `ray3_distance_to_point` | `ray3_compute_point_projection_t` | [3d/ray/ray3_distance_to_point.js](3d/ray/ray3_distance_to_point.js) <br>*[move → 3d/ray/ray3_compute_point_projection_t.js]* | Returns the projection parameter t (signed distance ALONG the ray), not perpendicular distance — name lies. |
+| `ConicRay.angle (field)` | `ConicRay.halfAngle` | [ConicRay.js](ConicRay.js) <br>*[move → ConicRay.js]* | Field stores a half-angle; bare 'angle' under-specifies. |
+| `v3_angle_atan2_between` | `v3_angle_stable` | [vec3/v3_angle_atan2_between.js](vec3/v3_angle_atan2_between.js) <br>*[move → vec3/v3_angle_stable.js]* | atan2 leaks implementation into the name; expose public meaning (numerically stable angle). |
+| `v3_matrix4_rotate` | `v3_matrix4_rotate_unit` | [vec3/v3_matrix4_rotate.js](vec3/v3_matrix4_rotate.js) <br>*[move → vec3/v3_matrix4_rotate_unit.js]* | Always renormalizes output; name should signal unit-length result. |
+| `Vector4.add3` | `Vector4.add` | [Vector4.js](Vector4.js) <br>*[move → Vector4.js]* | add3 confusingly reads as '3d add'; it is the element-wise add. Match Vector2/Vector3 add. |
+| `m3_multiply_vec3` | `m3_scale_columns_by_vec3` | [mat3/m3_multiply_vec3.js](mat3/m3_multiply_vec3.js) <br>*[move → mat3/m3_scale_columns_by_vec3.js]* | Name LIES: it is not a matrix*vector product (would yield a vec3); it column-scales and writes a 3x3. |
+| `m3_cm_invert` | `m3_invert` | [mat3/m3_cm_invert.js](mat3/m3_cm_invert.js) <br>*[move → mat3/m3_invert.js]* | Inversion is layout-agnostic; cm_ tag implies a non-existent rm_ counterpart. |
+| `aabb2_intersects_point` | `aabb2_contains_point` | [2d/aabb/aabb2_intersects_point.js](2d/aabb/aabb2_intersects_point.js) <br>*[move → 2d/aabb/aabb2_contains_point.js]* | It is a containment test, not surface intersection; reconcile with AABB2.containsPoint and delegate. |
+| `aabb3_project_to_2d (file aabb3_compute_projected_area.js)` | `aabb3_projected_area` | [3d/aabb/aabb3_compute_projected_area.js](3d/aabb/aabb3_compute_projected_area.js) <br>*[move → 3d/aabb/aabb3_projected_area.js]* | Name LIES (returns a scalar AREA, not a 2D box) AND mismatches filename; bare-metric drops compute_. |
+| `aabb3_combined_surface_area` | `aabb3_union_half_surface_area` | [3d/aabb/aabb3_combined_surface_area.js](3d/aabb/aabb3_combined_surface_area.js) <br>*[move → 3d/aabb/aabb3_union_half_surface_area.js]* | Returns HALF surface area of the union (off by 2x vs full); name must say half. |
+| `aabb3_box_surface_area_2` | `aabb3_half_surface_area` | [3d/aabb/aabb3_box_surface_area_2.js](3d/aabb/aabb3_box_surface_area_2.js) <br>*[move → 3d/aabb/aabb3_half_surface_area.js]* | Returns HALF area; '_2' is a meaningless disambiguator (no _1). |
+| `Quaternion.__setFromEuler` | `(remove; typed per-order methods)` | [Quaternion.js](Quaternion.js) <br>*[move → Quaternion.js]* | String-order dispatcher violates typed-over-magic; also fix 'bust be' typo. Keep typed fromEulerAngles<ORDER>. |
+| `Quaternion.process` | `Quaternion.watch` | [Quaternion.js](Quaternion.js) <br>*[move → Quaternion.js]* | Opaque name for 'invoke + subscribe onChanged'. |
+| `sphere_matrix4_project (file sphere_matrix4_transform.js)` | `sphere_matrix4_transform` | [3d/sphere/sphere_matrix4_transform.js](3d/sphere/sphere_matrix4_transform.js) <br>*[move → 3d/sphere/sphere_matrix4_transform.js]* | Export name LIES ('project' but it transforms) AND mismatches filename; transform is correct. |
+| `sphere_intersects_point` | `sphere_contains_point` | [3d/sphere/sphere_intersects_point.js](3d/sphere/sphere_intersects_point.js) <br>*[move → 3d/sphere/sphere_contains_point.js]* | Tests point-inside (containment), not surface intersection. |
+| `orientation3_array` | `orient2d_indexed` | [2d/convex-hull/orientation3_array.js](2d/convex-hull/orientation3_array.js) <br>*[move → 2d/convex-hull/orient2d_indexed.js]* | 'orientation3' LIES about dimension (it is 2D; 3=points). Use orient2d + _indexed for index-into-flat-array inputs. |
+| `plane3_compute_convex_3_plane_intersection` | `plane3_compute_3_plane_intersection` | [3d/plane/plane3_compute_convex_3_plane_intersection.js](3d/plane/plane3_compute_convex_3_plane_intersection.js) <br>*[move → 3d/plane/plane3_compute_3_plane_intersection.js]* | 'convex' lies (only non-degeneracy required). |
+| `bt_mesh_compute_vertex_quadratics` | `bt_mesh_compute_vertex_quadrics` | [3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadratics.js](3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadratics.js) <br>*[move → 3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js]* | Returns Quadric3 (quadric error metric), not quadratics; align with class name Quadric3. |
+| `bt_face_get_attached_faces / bt_face_get_neighbour_faces` | `bt_face_get_vertex_adjacent_faces / bt_face_get_edge_adjacent_faces` | [3d/topology/struct/binary/query/bt_face_get_attached_faces.js](3d/topology/struct/binary/query/bt_face_get_attached_faces.js) <br>*[move → 3d/topology/struct/binary/query/bt_face_get_vertex_adjacent_faces.js]* | attached(vertex-adj) vs neighbour(edge-adj) distinction must be in the name, not an easily-swapped noun. |
+| `computeTopoMeshBoundiningBox` | `compute_topo_mesh_bounding_box` | [3d/topology/bounds/computeTopoMeshBoundiningBox.js](3d/topology/bounds/computeTopoMeshBoundiningBox.js) <br>*[move → 3d/topology/bounds/compute_topo_mesh_bounding_box.js]* | FIX typo 'Boundining'; camelCase->snake (topology compute layer). |
+| `build_vertex_quadratics / deep_copy_vertex_quadratics / compute_edge_collapse_cost_quadratic` | `build_vertex_quadrics / deep_copy_vertex_quadrics / compute_edge_collapse_cost_quadric` | [3d/topology/simplify/quadratic/(various)](3d/topology/simplify/quadratic/(various)) <br>*[move → 3d/topology/simplify/quadric/(various)]* | Pervasive 'quadratics' misnomer for Quadric3; unify on 'quadric'. |
+| `compute_tetrahedron_volume / compute_tetrahedron_quality` | `tetrahedral_mesh_compute_tet_volume / tetrahedral_mesh_compute_tet_quality` | [3d/tetrahedra/compute_tetrahedron_volume.js](3d/tetrahedra/compute_tetrahedron_volume.js) <br>*[move → 3d/tetrahedra/tetrahedral_mesh_compute_tet_volume.js]* | Resolve the compute_tetrahedron_X (mesh) vs tetrahedron_compute_X (indexed) token-order collision: mesh-forms join the tetrahedral_mesh_ family; indexed primitives keep tetrahedron_compute_*. Also compute_tetrahedron_volume returns SIGNED — say so. |
+| `TopoMesh.setFacedUnindexed` | `TopoMesh.setFacesUnindexed` | [3d/topology/struct/TopoMesh.js](3d/topology/struct/TopoMesh.js) <br>*[move → 3d/topology/struct/TopoMesh.js]* | Typo 'Faced'->'Faces'. |
+
+### camelCase-legacy-islands (21)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `eulerAnglesFromMatrix` | `m4_euler_angles` | [3d/mat4/eulerAnglesFromMatrix.js](3d/mat4/eulerAnglesFromMatrix.js) <br>*[move → 3d/mat4/m4_euler_angles.js]* | camelCase island -> snake m4_ prefix. |
+| `quat3_createFromAxisAngle` | `quat3_from_axis_angle` | [3d/quaternion/quat3_createFromAxisAngle.js](3d/quaternion/quat3_createFromAxisAngle.js) <br>*[move → 3d/quaternion/quat3_from_axis_angle.js]* | camelCase-in-snake hybrid + 'create' lies (no alloc); move output to first (out,out_offset), take scalar axis. |
+| `computeBoundingSphereOfSpheres` | `sphere_compute_bounding_of_spheres` | [packing/computeBoundingSphereOfSpheres.js](packing/computeBoundingSphereOfSpheres.js) <br>*[move → packing/sphere_compute_bounding_of_spheres.js]* | camelCase island -> snake; align with the of_2_spheres sibling; fix sqr_distance_to_center mislabel (holds linear distance). |
+| `computeConePlaneSide` | `cone_compute_plane_side` | [3d/cone/computeConePlaneSide.js](3d/cone/computeConePlaneSide.js) <br>*[move → 3d/cone/cone_compute_plane_side.js]* | camelCase island -> snake cone_ prefix; fix mixed plane_normal_x/originX param casing. |
+| `computeConeBoundingBox` | `cone_compute_bounding_box` | [3d/cone/computeConeBoundingBox.js](3d/cone/computeConeBoundingBox.js) <br>*[move → 3d/cone/cone_compute_bounding_box.js]* | camelCase island -> snake; align token order with circle3_compute_bounding_box. |
+| `computeTriangleRayIntersection` | `tri3_ray_intersection` | [3d/triangle/computeTriangleRayIntersection.js](3d/triangle/computeTriangleRayIntersection.js) <br>*[move → 3d/triangle/tri3_ray_intersection.js]* | camelCase island -> snake tri3_; fix finate/triange typos. |
+| `computeTriangleRayIntersectionBarycentric` | `tri3_ray_intersection_barycentric` | [3d/triangle/computeTriangleRayIntersectionBarycentric.js](3d/triangle/computeTriangleRayIntersectionBarycentric.js) <br>*[move → 3d/triangle/tri3_ray_intersection_barycentric.js]* | camelCase->snake tri3_; fix [t,u,v] doc/impl mismatch. |
+| `computeTriangleRayIntersectionBarycentricEdge` | `tri3_ray_intersection_barycentric_edge` | [3d/triangle/computeTriangleRayIntersectionBarycentricEdge.js](3d/triangle/computeTriangleRayIntersectionBarycentricEdge.js) <br>*[move → 3d/triangle/tri3_ray_intersection_barycentric_edge.js]* | camelCase->snake tri3_. |
+| `rayTriangleIntersection` | `tri3_ray_intersection_v3_objects` | [3d/triangle/rayTriangleIntersection.js](3d/triangle/rayTriangleIntersection.js) <br>*[move → 3d/triangle/tri3_ray_intersection_v3_objects.js]* | camelCase + reversed word order; snake tri3_; mark the Vector3-object wrapper. |
+| `computeTriangleClosestPointToPointBarycentric` | `tri3_closest_point_barycentric` | [3d/triangle/computeTriangleClosestPointToPointBarycentric.js](3d/triangle/computeTriangleClosestPointToPointBarycentric.js) <br>*[move → 3d/triangle/tri3_closest_point_barycentric.js]* | camelCase->snake tri3_; drop PointToPoint stutter; keep 'closest'. |
+| `frustum3_computeNearestPointToPoint` | `frustum3_compute_closest_point` | [3d/frustum/frustum3_computeNearestPointToPoint.js](3d/frustum/frustum3_computeNearestPointToPoint.js) <br>*[move → 3d/frustum/frustum3_compute_closest_point.js]* | Only camelCase export here -> snake; nearest->closest; drop PointToPoint; FIX inverted boolean return semantics. |
+| `mortonEncode_LUT` | `v3_morton_encode_lut` | [3d/morton/mortonEncode_LUT.js](3d/morton/mortonEncode_LUT.js) <br>*[move → 3d/morton/v3_morton_encode_lut.js]* | camelHybrid -> snake v3_ prefix. |
+| `mortonEncode_magicbits` | `v3_morton_encode_magicbits` | [3d/morton/mortonEncode_magicbits.js](3d/morton/mortonEncode_magicbits.js) <br>*[move → 3d/morton/v3_morton_encode_magicbits.js]* | camelHybrid -> snake v3_ prefix; v3_morton_encode default-alias becomes a thin re-export. |
+| `randomPointInBox` | `random_point_in_box` | [random/randomPointInBox.js](random/randomPointInBox.js) <br>*[move → random/random_point_in_box.js]* | camelCase folder -> snake. (See open question on In/On token.) |
+| `randomPointOnBox` | `random_point_on_box` | [random/randomPointOnBox.js](random/randomPointOnBox.js) <br>*[move → random/random_point_on_box.js]* | camelCase -> snake. |
+| `randomPointInSphere / OnSphere / InCircle / InPoint` | `random_point_in_sphere (etc.)` | [random/randomPointInSphere.js](random/randomPointInSphere.js) <br>*[move → random/random_point_in_sphere.js]* | camelCase -> snake across the random/ family; rename destination_offset->result_offset in random_point_in_point. |
+| `packMaxRectangles / packOneBox / findBestContainer / cutArea / removeRedundantBoxes / costBy*` | `pack_max_rectangles / pack_one_box / find_best_container / cut_area / remove_redundant_boxes / cost_by_*` | [packing/max-rect/packMaxRectangles.js](packing/max-rect/packMaxRectangles.js) <br>*[move → packing/max-rect/pack_max_rectangles.js]* | Entire camelCase folder -> snake. |
+| `computeTopoMeshBoundingSphere / computeTopoMeshVertexDuplicates / computeTriangleClusterNormalBoundingCone` | `compute_topo_mesh_bounding_sphere / compute_topo_mesh_vertex_duplicates / compute_triangle_cluster_normal_bounding_cone` | [3d/topology/bounds/computeTopoMeshBoundingSphere.js](3d/topology/bounds/computeTopoMeshBoundingSphere.js) <br>*[move → 3d/topology/bounds/compute_topo_mesh_bounding_sphere.js]* | camelCase topology layer -> snake. |
+| `simplifyTopoMesh / simplifyTopoMesh2` | `simplify_topo_mesh_quadric / simplify_topo_mesh_decimate` | [3d/topology/simplify/simplifyTopoMesh.js](3d/topology/simplify/simplifyTopoMesh.js) <br>*[move → 3d/topology/simplify/simplify_topo_mesh_quadric.js]* | camelCase->snake; numeric '2' suffix carries no semantics — name by algorithm; consolidate duplicate entry points. |
+| `computeEdgeCollapseCost / collapseEdge / partialEdgeCollapse / EdgeCollapseCandidate` | `compute_edge_collapse_cost / collapse_edge / partial_edge_collapse / EdgeCollapseCandidate(class kept)` | [3d/topology/simplify/(various)](3d/topology/simplify/(various)) <br>*[move → 3d/topology/simplify/(various)]* | camelCase free fns -> snake; reconcile the duplicate cost functions (camel vs snake) into one. |
+| `StaticR2Tree (mixed casing methods)` | `StaticRTree2D (snake_case methods)` | [2d/r-tree/StaticR2Tree.js](2d/r-tree/StaticR2Tree.js) <br>*[move → 2d/r-tree/StaticRTree2D.js]* | 'R2'->'2D' dimension token; unify mixed camel/snake methods onto snake (matches BVH2D/SpatialHashGrid). |
+
+### redundant-token-repetition (17)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `line_segment_compute_line_segment_intersection_array_2d` | `segment2_segment_compute_intersection_array_2d` | [2d/line/line_segment_compute_line_segment_intersection_array_2d.js](2d/line/line_segment_compute_line_segment_intersection_array_2d.js) <br>*[move → 2d/line/segment2_segment_compute_intersection_array_2d.js]* | FLAGSHIP: 'line_segment' stuttered twice + verbose. One segment token per operand role; _array kept (it is the offset-addressed flat-array writer, the correct meaning). |
+| `line_segment_compute_line_segment_intersection_2d` | `segment2_segment_compute_intersection_v2_2d` | [2d/line/line_segment_compute_line_segment_intersection_2d.js](2d/line/line_segment_compute_line_segment_intersection_2d.js) <br>*[move → 2d/line/segment2_segment_compute_intersection_v2_2d.js]* | Vector2-sink wrapper; de-stutter and mark the v2-object sink with _v2; move output to first (result,...) per convention. |
+| `line_segment_compute_line_segment_intersection_vectors_2d` | `segment2_segment_compute_intersection_v2_objects_2d` | [2d/line/line_segment_compute_line_segment_intersection_vectors_2d.js](2d/line/line_segment_compute_line_segment_intersection_vectors_2d.js) <br>*[move → 2d/line/segment2_segment_compute_intersection_v2_objects_2d.js]* | De-stutter; clarify it takes Vector2 objects for both operands. |
+| `v3_triple_cross_product` | `v3_triple_cross` | [vec3/v3_triple_cross_product.js](vec3/v3_triple_cross_product.js) <br>*[move → vec3/v3_triple_cross.js]* | Drop _product to match v3_cross / v3_cross_array. |
+| `v3_angle_between` | `v3_angle` | [vec3/v3_angle_between.js](vec3/v3_angle_between.js) <br>*[move → vec3/v3_angle.js]* | Drop redundant infix 'between' (two operands implied). |
+| `v3_angle_cos_between` | `v3_cos_angle` | [vec3/v3_angle_cos_between.js](vec3/v3_angle_cos_between.js) <br>*[move → vec3/v3_cos_angle.js]* | Drop 'between'; lead with the returned quantity (cos). |
+| `Vector3.projectOntoVector3` | `Vector3.projectOnto` | [Vector3.js](Vector3.js) <br>*[move → Vector3.js]* | Redundant Vector3 token (class is the type). |
+| `aabb2_array_combine` | `aabb2_union_array` | [2d/aabb/aabb2_array_combine.js](2d/aabb/aabb2_array_combine.js) <br>*[move → 2d/aabb/aabb2_union_array.js]* | Box-union has 3 names (combine/expandToFit/resizeToFit); standardize on union; suffix _array (offset operands). |
+| `AABB2.overlapExists / expandToFit` | `AABB2.intersects / union` | [2d/aabb/AABB2.js](2d/aabb/AABB2.js) <br>*[move → 2d/aabb/AABB2.js]* | Align class with free-fn intersects + union vocabulary. |
+| `aabb3_near_distance_to_intersection_ray_segment` | `aabb3_ray_segment_entry_distance` | [3d/aabb/aabb3_near_distance_to_intersection_ray_segment.js](3d/aabb/aabb3_near_distance_to_intersection_ray_segment.js) <br>*[move → 3d/aabb/aabb3_ray_segment_entry_distance.js]* | 'near_distance_to_intersection' verbose/redundant; entry distance IS the intersection distance. |
+| `sphere_projected_sphere_radius_sqr` | `sphere_projected_radius_sqr` | [3d/sphere/sphere_projected_sphere_radius_sqr.js](3d/sphere/sphere_projected_sphere_radius_sqr.js) <br>*[move → 3d/sphere/sphere_projected_radius_sqr.js]* | Redundant 'sphere' repeated; also unify param order with sphere_project (sphere,matrix,focal_length). |
+| `circle_compute_circle_intersection` | `circle_compute_intersection` | [2d/circle/circle_compute_circle_intersection.js](2d/circle/circle_compute_circle_intersection.js) <br>*[move → 2d/circle/circle_compute_intersection.js]* | Redundant circle repetition. |
+| `plane3_compute_plane_intersection` | `plane3_compute_intersection_objects` | [3d/plane/plane3_compute_plane_intersection.js](3d/plane/plane3_compute_plane_intersection.js) <br>*[move → 3d/plane/plane3_compute_intersection_objects.js]* | Redundant 'plane' repetition; mark as the object-adapter (TODO says consolidate with plane3_intersect_plane); stop calling private __setFromRotationMatrix. |
+| `hexahedron_from_aabb` | `frustum3_from_aabb` | [3d/frustum/hexahedron_from_aabb.js](3d/frustum/hexahedron_from_aabb.js) <br>*[move → 3d/frustum/frustum3_from_aabb.js]* | Same 6-plane layout as frustum family; unify the noun to frustum (drop hexahedron). |
+| `frustum_matrix4_project / clipping_volume_matrix4_project` | `frustum3_matrix4_project / frustum3_matrix4_project_n` | [3d/frustum/frustum_matrix4_project.js](3d/frustum/frustum_matrix4_project.js) <br>*[move → 3d/frustum/frustum3_matrix4_project.js]* | Add dimension digit; unify noun (clipping_volume = n-plane frustum); standardize matrix-last param order. |
+| `bt_faces_shared_loop` | `bt_face_get_shared_loop` | [3d/topology/struct/binary/query/bt_faces_shared_loop.js](3d/topology/struct/binary/query/bt_faces_shared_loop.js) <br>*[move → 3d/topology/struct/binary/query/bt_face_get_shared_loop.js]* | Singularize face token + match bt_face_get_* query family. |
+| `tetrahedral_mesh_tet_get_neighbours` | `tetrahedral_mesh_get_neighbours` | [3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.js](3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.js) <br>*[move → 3d/tetrahedra/tetrahedral_mesh_get_neighbours.js]* | Redundant tet token (tetrahedral_mesh already implies tet); also move (out,out_offset) to front. |
+
+### array-token-overload (16)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `line_segment_compute_line_segment_intersection_vectors_array_2d` | `segment2_segment_compute_intersection_to_new_array_2d` | [2d/line/line_segment_compute_line_segment_intersection_vectors_array_2d.js](2d/line/line_segment_compute_line_segment_intersection_vectors_array_2d.js) <br>*[move → 2d/line/segment2_segment_compute_intersection_to_new_array_2d.js]* | This one ALLOCATES and returns a new array — _array previously lied. Use _to_new_array to signal allocation, removing the contradictory _array meaning. |
+| `v3_array_normalize` | `v3_normalize_array` | [vec3/v3_array_normalize.js](vec3/v3_array_normalize.js) <br>*[move → vec3/v3_normalize_array.js]* | Standardize _array as SUFFIX (offset operand) everywhere. |
+| `v3_array_scale` | `v3_scale_array` | [vec3/v3_array_scale.js](vec3/v3_array_scale.js) <br>*[move → vec3/v3_scale_array.js]* | Suffix _array; also unify scale verb (drop multiply_scalar split). |
+| `v3_array_copy` | `v3_copy_array` | [vec3/v3_array_copy.js](vec3/v3_array_copy.js) <br>*[move → vec3/v3_copy_array.js]* | Suffix _array; rename params target/source -> result/input. |
+| `v3_array_centroid` | `v3_centroid_v3_buffer` | [vec3/v3_array_centroid.js](vec3/v3_array_centroid.js) <br>*[move → vec3/v3_centroid_v3_buffer.js]* | Here _array meant a BATCH of many vectors (loops count*3), a different meaning — use _v3_buffer; also return void to match siblings. |
+| `v3_array_matrix4_rotate` | `v3_matrix4_rotate_array` | [vec3/v3_array_matrix4_rotate.js](vec3/v3_array_matrix4_rotate.js) <br>*[move → vec3/v3_matrix4_rotate_array.js]* | Suffix _array; align with v3_matrix4_multiply (which reads at offset without the token). |
+| `v3_array_equals` | `v3_equals_array` | [vec3/v3_array_equals.js](vec3/v3_array_equals.js) <br>*[move → vec3/v3_equals_array.js]* | Suffix _array (offset operands). |
+| `v3_array_displace_in_direction` | `v3_displace_in_direction_to_array` | [vec3/v3_array_displace_in_direction.js](vec3/v3_array_displace_in_direction.js) <br>*[move → vec3/v3_displace_in_direction_to_array.js]* | Inputs are SCALARS, only output is an array; the prefix array_ lied. _to_array marks the array output. |
+| `v3_cross_array` | `v3_cross_array` | [vec3/v3_cross_array.js](vec3/v3_cross_array.js) <br>*[move → vec3/v3_cross_array.js]* | Already conforms (suffix _array, both operands at offsets) — kept; listed only as the canonical exemplar siblings should match. |
+| `v3_dot_array_array` | `v3_dot_array` | [vec3/v3_dot_array_array.js](vec3/v3_dot_array_array.js) <br>*[move → vec3/v3_dot_array.js]* | Double _array_array banned; a single _array already implies both operands at offsets (matches v3_cross_array). |
+| `v3_negate_array` | `v3_negate_array` | [vec3/v3_negate_array.js](vec3/v3_negate_array.js) <br>*[move → vec3/v3_negate_array.js]* | Already conforms (suffix _array). Listed as exemplar; no change. |
+| `vector_scale_array` | `vector_scale_offset` | [vec/vector_scale_array.js](vec/vector_scale_array.js) <br>*[move → vec/vector_scale_offset.js]* | _array lies (it is the offset-taking scale primitive, no array-of-vectors); rename count param dimensions->n. |
+| `sphere_array_intersects_point` | `sphere_packed_contains_point` | [3d/sphere/sphere_array_intersects_point.js](3d/sphere/sphere_array_intersects_point.js) <br>*[move → 3d/sphere/sphere_packed_contains_point.js]* | _array meant packed single sphere [cx,cy,cz,r] (not offset operand); containment fix too. |
+| `sphere_array_intersects_ray` | `sphere_packed_intersects_ray` | [3d/sphere/sphere_array_intersects_ray.js](3d/sphere/sphere_array_intersects_ray.js) <br>*[move → 3d/sphere/sphere_packed_intersects_ray.js]* | _array=packed sphere; use _packed token. |
+| `sphere_radius_sqr_from_v3_array_transformed` | `sphere_radius_sqr_from_v3_buffer_transformed` | [3d/sphere/sphere_radius_sqr_from_v3_array_transformed.js](3d/sphere/sphere_radius_sqr_from_v3_array_transformed.js) <br>*[move → 3d/sphere/sphere_radius_sqr_from_v3_buffer_transformed.js]* | _array here = batch of vec3 points; use _v3_buffer; fix JSDoc typos bonding/foe. |
+| `removeRedundantBoxesArray` | `remove_redundant_boxes_from_array` | [packing/max-rect/removeRedundantBoxesArray.js](packing/max-rect/removeRedundantBoxesArray.js) <br>*[move → packing/max-rect/remove_redundant_boxes_from_array.js]* | camelCase->snake; '_Array' overload meant 'plain Array container' -> spell it _from_array. |
+
+### verb-prefix-inconsistency (14)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `line3_closest_points_segment_segment` | `line3_compute_segment_segment_closest_points` | [3d/line/line3_closest_points_segment_segment.js](3d/line/line3_closest_points_segment_segment.js) <br>*[move → 3d/line/line3_compute_segment_segment_closest_points.js]* | Add compute_ verb to match line3_compute_* siblings; add result_offset; reorder operand tokens. |
+| `v3_multiply_scalar` | `v3_scale` | [vec3/v3_multiply_scalar.js](vec3/v3_multiply_scalar.js) <br>*[move → vec3/v3_scale.js]* | Two verbs (multiply_scalar vs array_scale) for one op; standardize on scale (scalar-in) + v3_scale_array (offset-in). |
+| `v3_compute_interior_angle` | `v3_interior_angle` | [vec3/v3_compute_interior_angle.js](vec3/v3_compute_interior_angle.js) <br>*[move → vec3/v3_interior_angle.js]* | Lone compute_ user and lone object-arg taker; drop compute_ (bare metric) and take scalar triples. |
+| `m3_cm_from_translation` | `m3_cm_make_translation` | [mat3/m3_cm_from_translation.js](mat3/m3_cm_from_translation.js) <br>*[move → mat3/m3_cm_make_translation.js]* | Standardize translation-matrix builder verb on make_ (matches m4_make_translation). |
+| `m4_compute_normal_matrix3` | `m4_normal_matrix3` | [3d/mat4/m4_compute_normal_matrix3.js](3d/mat4/m4_compute_normal_matrix3.js) <br>*[move → 3d/mat4/m4_normal_matrix3.js]* | Bare-metric: drop compute_ to match m4_rotation_translation etc. |
+| `aabb2_compute_area` | `aabb2_area` | [2d/aabb/aabb2_compute_area.js](2d/aabb/aabb2_compute_area.js) <br>*[move → 2d/aabb/aabb2_area.js]* | Bare-metric: drop compute_ (consistent with aabb2_distance_to_point). |
+| `aabb2_compute_center_from_multiple` | `aabb2_center_from_aabb2_buffer` | [2d/aabb/aabb2_compute_center_from_multiple.js](2d/aabb/aabb2_compute_center_from_multiple.js) <br>*[move → 2d/aabb/aabb2_center_from_aabb2_buffer.js]* | Drop compute_; clarify input is a batch; add result out-param to stop per-call allocation. |
+| `aabb3_compute_surface_area` | `aabb3_surface_area` | [3d/aabb/aabb3_compute_surface_area.js](3d/aabb/aabb3_compute_surface_area.js) <br>*[move → 3d/aabb/aabb3_surface_area.js]* | Bare-metric drops compute_. |
+| `aabb3_compute_half_surface_area` | `aabb3_half_surface_area_extents` | [3d/aabb/aabb3_compute_half_surface_area.js](3d/aabb/aabb3_compute_half_surface_area.js) <br>*[move → 3d/aabb/aabb3_half_surface_area_extents.js]* | Bare-metric drops compute_; note collision with the renamed single-box helper — keep the extents-primitive distinct (scalar x0..z1 in). |
+| `Quaternion.setFromRotationMatrix` | `Quaternion.fromRotationMatrix` | [Quaternion.js](Quaternion.js) <br>*[move → Quaternion.js]* | Match the from* converter family (drop set prefix). |
+| `is_point_within_planes` | `plane3_contains_point_within_set` | [3d/plane/is_point_within_planes.js](3d/plane/is_point_within_planes.js) <br>*[move → 3d/plane/plane3_contains_point_within_set.js]* | Add plane3_ prefix; remove contradictory @private on an export. |
+| `fill_in_a_cavity` | `tetrahedral_mesh_fill_cavity` | [3d/topology/delaunay/fill_in_a_cavity.js](3d/topology/delaunay/fill_in_a_cavity.js) <br>*[move → 3d/topology/delaunay/tetrahedral_mesh_fill_cavity.js]* | Prose-style name with articles; use domain-token verb_noun. |
+| `qt_match_data_by_circle` | `qt_collect_by_circle (merge w/ optional predicate)` | [2d/quad-tree/qt_match_data_by_circle.js](2d/quad-tree/qt_match_data_by_circle.js) <br>*[move → 2d/quad-tree/qt_collect_by_circle.js]* | match_=collect_+predicate; collapse the three-verb sprawl (collect_/match_/query_data_) onto one collect_ verb. |
+| `make_justified_point_grid` | `aabb3_emit_point_grid` | [3d/util/make_justified_point_grid.js](3d/util/make_justified_point_grid.js) <br>*[move → 3d/util/aabb3_emit_point_grid.js]* | 'make_' verb is a lone outlier; it iterates over an AABB3 emitting points via callback — encode the type and the emit semantics. |
+
+### output-arg-placement-and-missing-offset (14)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `ray3_array_compose` | `ray3_compose_array` | [3d/ray/ray3_array_compose.js](3d/ray/ray3_array_compose.js) <br>*[move → 3d/ray/ray3_compose_array.js]* | Suffix _array (offset convention); ADD missing output_offset param to match ray3 array family. |
+| `v3_rigid_align_paired_unit_vectors (out_quaternion last)` | `v3_rigid_align_paired_unit_vectors` | [vec3/v3_rigid_align_paired_unit_vectors.js](vec3/v3_rigid_align_paired_unit_vectors.js) <br>*[move → vec3/v3_rigid_align_paired_unit_vectors.js]* | Name acceptable; move out_quaternion to FIRST param to match output-first rule. |
+| `apply_mat4_transform_to_v3_array` | `m4_transform_v3_buffer` | [3d/mat4/apply_mat4_transform_to_v3_array.js](3d/mat4/apply_mat4_transform_to_v3_array.js) <br>*[move → 3d/mat4/m4_transform_v3_buffer.js]* | m4_ prefix; _v3_buffer = batch of vectors (distinct from offset-operand _array); move output to first. |
+| `apply_mat4_transform_to_direction_v3_array` | `m4_transform_direction_v3_buffer` | [3d/mat4/apply_mat4_transform_to_direction_v3_array.js](3d/mat4/apply_mat4_transform_to_direction_v3_array.js) <br>*[move → 3d/mat4/m4_transform_direction_v3_buffer.js]* | Same as above; 'direction' kept (normalizes result). |
+| `aabb2_from_v2_array` | `aabb2_from_v2_buffer` | [2d/aabb/aabb2_from_v2_array.js](2d/aabb/aabb2_from_v2_array.js) <br>*[move → 2d/aabb/aabb2_from_v2_buffer.js]* | Input is a batch of points (not offset operand); ADD missing result_offset (currently hardcodes 0). |
+| `aabb3_expand_array` | `aabb3_expand_array` | [3d/aabb/aabb3_expand_array.js](3d/aabb/aabb3_expand_array.js) <br>*[move → 3d/aabb/aabb3_expand_array.js]* | Name OK; FIX output-arg placement (output is 2nd) to output-first; rename param distance->margin. |
+| `quat3_integrate (param result_q, no offset)` | `quat3_integrate` | [3d/quaternion/quat3_integrate.js](3d/quaternion/quat3_integrate.js) <br>*[move → 3d/quaternion/quat3_integrate.js]* | Name OK; rename result_q->out and ADD out_offset to match quat3 family. |
+| `polygon2_clip_axis_halfplane` | `polygon2_clip_axis_halfplane` | [2d/polygon/polygon2_clip_axis_halfplane.js](2d/polygon/polygon2_clip_axis_halfplane.js) <br>*[move → 2d/polygon/polygon2_clip_axis_halfplane.js]* | Name OK; FIX output-arg (points_out is 3rd) to output-first and add output_offset. |
+| `slice_frustum_linear_to_points` | `frustum3_slice_linear_to_points` | [3d/frustum/slice_frustum_linear_to_points.js](3d/frustum/slice_frustum_linear_to_points.js) <br>*[move → 3d/frustum/frustum3_slice_linear_to_points.js]* | Verb-first -> noun-first frustum3_ family; FIX output-last to output-first. |
+| `read_three_planes_to_array` | `frustum3_planes_to_flat_from_three` | [3d/frustum/read_three_planes_to_array.js](3d/frustum/read_three_planes_to_array.js) <br>*[move → 3d/frustum/frustum3_planes_to_flat_from_three.js]* | Output-last -> output-first; vendor token to adapter suffix; _array ambiguous (it is to-flat). |
+| `octahedral_uv_to_direction / octahedral_direction_to_uv` | `octahedral_uv_to_direction / octahedral_direction_to_uv` | [3d/octahedra/octahedral_uv_to_direction.js](3d/octahedra/octahedral_uv_to_direction.js) <br>*[move → 3d/octahedra/octahedral_uv_to_direction.js]* | Names OK; align equirectangular_* to THIS output-first (out,out_offset,in,in_offset) shape (the equirect functions are the ones to change). |
+| `equirectangular_uv_to_direction / equirectangular_direction_to_uv` | `equirectangular_uv_to_direction / equirectangular_direction_to_uv` | [3d/equirectangular/equirectangular_uv_to_direction.js](3d/equirectangular/equirectangular_uv_to_direction.js) <br>*[move → 3d/equirectangular/equirectangular_uv_to_direction.js]* | Names OK; FIX output placement to output-first to match octahedral_* siblings. |
+| `gjk_epa_penetration (out, no offset)` | `gjk_epa_penetration` | [3d/gjk/gjk_epa_penetration.js](3d/gjk/gjk_epa_penetration.js) <br>*[move → 3d/gjk/gjk_epa_penetration.js]* | Name OK; add out_offset to match mpr/minkowski_support; reconcile MTV encoding with mpr. |
+| `bvh2d_query_all_data_by_circle` | `bvh2d_query_all_data_by_circle` | [2d/bvh/bvh2d_query_all_data_by_circle.js](2d/bvh/bvh2d_query_all_data_by_circle.js) <br>*[move → 2d/bvh/bvh2d_query_all_data_by_circle.js]* | Name OK; reorder params to (result, result_offset, bvh, root, ...) to match shg_/qt_ query convention. |
+
+### abbreviation-vert-and-matrix-param (14)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `v3_array_immediate_add` | `v3_add_array` | [vec3/v3_array_immediate_add.js](vec3/v3_array_immediate_add.js) <br>*[move → vec3/v3_add_array.js]* | 'immediate' is opaque; this is array(offset)+=array(offset). Mirror dot/cross array convention. |
+| `v3_array_add_in_place` | `v3_add` | [vec3/v3_array_add_in_place.js](vec3/v3_array_add_in_place.js) <br>*[move → vec3/v3_add.js]* | 'in_place' redundant (every writer mutates); this is the scalar-source add primitive. |
+| `v3_quat3_apply` | `v3_quaternion_apply` | [vec3/v3_quat3_apply.js](vec3/v3_quat3_apply.js) <br>*[move → vec3/v3_quaternion_apply.js]* | quat3 token misleads (3 reads as quat dim); use full 'quaternion' to match Quaternion class. |
+| `v3_quat3_apply_inverse` | `v3_quaternion_apply_inverse` | [vec3/v3_quat3_apply_inverse.js](vec3/v3_quat3_apply_inverse.js) <br>*[move → vec3/v3_quaternion_apply_inverse.js]* | Same quat3 token fix. |
+| `v3_matrix3_rotate (param mat3)` | `v3_matrix3_rotate` | [vec3/v3_matrix3_rotate.js](vec3/v3_matrix3_rotate.js) <br>*[move → vec3/v3_matrix3_rotate.js]* | Function name OK; rename matrix param mat3 -> m3 to match m4 convention. |
+| `v4_multiply_mat4` | `v4_matrix4_multiply` | [vec4/v4_multiply_mat4.js](vec4/v4_multiply_mat4.js) <br>*[move → vec4/v4_matrix4_multiply.js]* | Align matrix token with v3_matrix4_multiply (m4 family) and reorder to noun-first. |
+| `aabb3_intersects_line_segment (camelCase params)` | `aabb3_intersects_segment3` | [3d/aabb/aabb3_intersects_line_segment.js](3d/aabb/aabb3_intersects_line_segment.js) <br>*[move → 3d/aabb/aabb3_intersects_segment3.js]* | Two endpoints => segment; rename startX/endX -> start_x/end_x (snake). |
+| `quat_encode_to_uint32` | `quat3_encode_to_uint32` | [3d/quaternion/quat_encode_to_uint32.js](3d/quaternion/quat_encode_to_uint32.js) <br>*[move → 3d/quaternion/quat3_encode_to_uint32.js]* | Unify type token on quat3_ (the family majority). |
+| `quat_decode_from_uint32` | `quat3_decode_from_uint32` | [3d/quaternion/quat_decode_from_uint32.js](3d/quaternion/quat_decode_from_uint32.js) <br>*[move → 3d/quaternion/quat3_decode_from_uint32.js]* | Unify token quat3_; rename output/output_offset -> out/out_offset. |
+| `sh3_rotate_bl` | `sh3_rotate` | [3d/sphere/harmonics/sh3_rotate_bl.js](3d/sphere/harmonics/sh3_rotate_bl.js) <br>*[move → 3d/sphere/harmonics/sh3_rotate.js]* | '_bl' (BakerLab) provenance token is opaque public surface; add (array,offset) params for parity. |
+| `sh_compute_K` | `sh_normalization_factor` | [3d/sphere/harmonics/sh_compute_K.js](3d/sphere/harmonics/sh_compute_K.js) <br>*[move → 3d/sphere/harmonics/sh_normalization_factor.js]* | Capital K reads like a constant; verb+single-letter inconsistent with sh_index. |
+| `tm_vert_kill / tm_kill_only_vert / tm_vert_splice / tm_vert_fuse_duplicate_edges` | `tm_vertex_kill / tm_vertex_kill_only / tm_vertex_splice / tm_vertex_fuse_duplicate_edges` | [3d/topology/(various)](3d/topology/(various)) <br>*[move → 3d/topology/(various)]* | Standardize vertex token to 'vertex'; element-first kill order (tm_vertex_kill_only) matches tm_vertex_kill. |
+| `tm_kill_only_edge / tm_kill_only_face` | `tm_edge_kill_only / tm_face_kill_only` | [3d/topology/io/(various)](3d/topology/io/(various)) <br>*[move → 3d/topology/io/(various)]* | Element-first to match tm_edge_kill / tm_face_kill (verb-then-element was inverted). |
+| `bt_vert_kill / bt_vert_fuse_duplicate_edges / bt_kill_only_vert / bt_merge_verts_by_distance` | `bt_vertex_kill / bt_vertex_fuse_duplicate_edges / bt_vertex_kill_only / bt_merge_vertices_by_distance` | [3d/topology/struct/binary/io/vertex/(various)](3d/topology/struct/binary/io/vertex/(various)) <br>*[move → 3d/topology/struct/binary/io/vertex/(various)]* | Unify vertex token to 'vertex' (matches BinaryTopology vertex_* accessors); element-first kill order. |
+
+### predicate-vs-producer-vs-degree (10)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `line_segment_line_segment_intersection_exists_2d` | `segment2_intersects_segment2_2d` | [2d/line/line_segment_line_segment_intersection_exists_2d.js](2d/line/line_segment_line_segment_intersection_exists_2d.js) <br>*[move → 2d/line/segment2_intersects_segment2_2d.js]* | Boolean predicate -> intersects form; drop doubled token and _exists. |
+| `intersect_ray_2d` | `ray2_ray2_compute_intersection_array_2d` | [2d/intersect_ray_2d.js](2d/intersect_ray_2d.js) <br>*[move → 2d/line/ray2_ray2_compute_intersection_array_2d.js]* | Verb-first name breaks noun/type-first rule; bare verb 'intersect' banned; move under 2d/line/; fix JSDoc 'coplanar' (a 3D term). |
+| `aabb2_overlap_exists` | `aabb2_intersects_aabb2` | [2d/aabb/aabb2_overlap_exists.js](2d/aabb/aabb2_overlap_exists.js) <br>*[move → 2d/aabb/aabb2_intersects_aabb2.js]* | Standardize boolean box-box test on intersects_<other>. |
+| `aabb2_compute_overlap` | `aabb2_compute_intersection` | [2d/aabb/aabb2_compute_overlap.js](2d/aabb/aabb2_compute_overlap.js) <br>*[move → 2d/aabb/aabb2_compute_intersection.js]* | It writes the overlap REGION (geometry producer) -> compute_*_intersection form; reserve overlap/intersects for the bool. |
+| `Rectangle.intersects / Rectangle.overlaps` | `Rectangle.intersects (one method, documented closed-interval)` | [2d/Rectangle.js](2d/Rectangle.js) <br>*[move → 2d/Rectangle.js]* | Two methods read as synonyms but differ in boundary semantics; collapse to one with documented semantics (delegate to aabb2_intersects_aabb2). |
+| `aabb3_intersects_frustum_degree` | `aabb3_classify_against_frustum` | [3d/aabb/aabb3_intersects_frustum_degree.js](3d/aabb/aabb3_intersects_frustum_degree.js) <br>*[move → 3d/aabb/aabb3_classify_against_frustum.js]* | Returns a 3-state degree, not a bool; intersects_ prefix lies about return shape. |
+| `aabb3_array_intersects_frustum_degree` | `aabb3_classify_against_frustum_array` | [3d/aabb/aabb3_array_intersects_frustum_degree.js](3d/aabb/aabb3_array_intersects_frustum_degree.js) <br>*[move → 3d/aabb/aabb3_classify_against_frustum_array.js]* | Same degree-not-bool fix; suffix _array (offset aabb). |
+| `aabb3_detailed_volume_intersection` | `aabb3_compute_clipping_volume_intersection` | [3d/aabb/aabb3_detailed_volume_intersection.js](3d/aabb/aabb3_detailed_volume_intersection.js) <br>*[move → 3d/aabb/aabb3_compute_clipping_volume_intersection.js]* | Producer named with bare noun 'intersection' among intersects predicates; also FIX JSDoc param order (plane_mask/planes swapped). |
+| `plane3_intersect_plane` | `plane3_compute_intersection` | [3d/plane/plane3_intersect_plane.js](3d/plane/plane3_intersect_plane.js) <br>*[move → 3d/plane/plane3_compute_intersection.js]* | Bare verb 'intersect' banned; this is the canonical scalar producer. |
+| `bt_query_edge_is_boundary` | `bt_edge_is_boundary` | [3d/topology/struct/binary/query/bt_query_edge_is_boundary.js](3d/topology/struct/binary/query/bt_query_edge_is_boundary.js) <br>*[move → 3d/topology/struct/binary/query/bt_edge_is_boundary.js]* | Lone bt_query_ prefix; sibling predicates (bt_edge_has_vertex, bt_face_is_degenerate) omit it. |
+
+### filename-export-mismatch-and-multi-export (10)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `m3_make_rotation_TBN (file m3_make_rotation.js)` | `m3_make_rotation_TBN` | [mat3/m3_make_rotation.js](mat3/m3_make_rotation.js) <br>*[move → mat3/m3_make_rotation_TBN.js]* | Rename FILE to match export (one-file-one-export convention). |
+| `aabb_build_frustum (file aabb3_build_frustum.js)` | `aabb3_build_frustum` | [3d/aabb/aabb3_build_frustum.js](3d/aabb/aabb3_build_frustum.js) <br>*[move → 3d/aabb/aabb3_build_frustum.js]* | Export missing the dimension digit; align with filename and aabb3_ family. |
+| `aabb3_score_boxes_SAH_delta (not exported)` | `aabb3_score_boxes_sah_delta (ADD export)` | [3d/aabb/aabb3_score_boxes_SAH_delta.js](3d/aabb/aabb3_score_boxes_SAH_delta.js) <br>*[move → 3d/aabb/aabb3_score_boxes_sah_delta.js]* | Declared but never exported (dead public surface); export it and reconcile half-vs-full-area math. |
+| `compute_legendre_polynomial (0-byte file)` | `(delete or implement as sh_legendre_polynomial)` | [3d/sphere/harmonics/compute_legendre_polynomial.js](3d/sphere/harmonics/compute_legendre_polynomial.js) <br>*[move → 3d/sphere/harmonics/sh_legendre_polynomial.js]* | Empty/dead file exporting nothing; third naming style. Delete or implement under sh_ band-generic prefix. |
+| `validate (file aabb2_validate_packing.js, not exported)` | `aabb2_validate_packing (ADD export)` | [packing/max-rect/aabb2_validate_packing.js](packing/max-rect/aabb2_validate_packing.js) <br>*[move → packing/max-rect/aabb2_validate_packing.js]* | File promises a public aabb2_ validator; inner fn is unnamed-by-convention and unexported. |
+| `encode_unit_to_hemioct (file encode_unit3_hemioct.js)` | `encode_unit_to_hemioct` | [3d/normal/hemioct/encode_unit3_hemioct.js](3d/normal/hemioct/encode_unit3_hemioct.js) <br>*[move → 3d/normal/hemioct/encode_unit_to_hemioct.js]* | Rename FILE to match export (one-file-one-export). |
+| `encode_unit_to_azimuth / decode_azimuth_to_unit (folder lamber_azimuth, file transform.js)` | `encode_unit_to_azimuth / decode_azimuth_to_unit` | [3d/normal/lamber_azimuth/transform.js](3d/normal/lamber_azimuth/transform.js) <br>*[move → 3d/normal/lambert_azimuth/encode_unit_to_azimuth.js]* | Fix folder typo lamber->lambert; split the 2-export transform.js into per-export files. |
+| `encode_unit_to_spheremap (file sphere_map_transform.js) + dead decode_spheremap_to_unit` | `encode_unit_to_spheremap / decode_spheremap_to_unit (ADD export, split files)` | [3d/normal/spherical/sphere_map_transform.js](3d/normal/spherical/sphere_map_transform.js) <br>*[move → 3d/normal/spherical/encode_unit_to_spheremap.js]* | File name mismatch; the decode companion is declared but NOT exported (asymmetric public surface) — export it. |
+| `bt_mesh_face_poke (file bt_face_poke.js)` | `bt_face_poke` | [3d/topology/struct/binary/io/face/bt_face_poke.js](3d/topology/struct/binary/io/face/bt_face_poke.js) <br>*[move → 3d/topology/struct/binary/io/face/bt_face_poke.js]* | Wrong object token (single-face op, not bt_mesh_) AND export mismatches filename. |
+| `bt_collect_boundary_segments / bt_point_distance_to_segments (in euclidean field file)` | `bt_collect_boundary_segments / segment3_point_distance_to_segments (split files)` | [3d/topology/struct/binary/query/bt_mesh_build_boundary_euclidean_distance_field.js](3d/topology/struct/binary/query/bt_mesh_build_boundary_euclidean_distance_field.js) <br>*[move → 3d/topology/struct/binary/query/bt_collect_boundary_segments.js]* | Multi-export file; the point-distance helper has no mesh handle and belongs in the segment/line geometry module, not bt_. |
+
+### correctness-bugs-surfaced-by-audit (8)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `ray3_shift_origin_along_direction` | `ray3_shift_origin_along_direction_array` | [3d/ray/ray3_shift_origin_along_direction.js](3d/ray/ray3_shift_origin_along_direction.js) <br>*[move → 3d/ray/ray3_shift_origin_along_direction_array.js]* | FIX BUG: origin written at hardcoded offset 0 while direction at output_offset+3; honor output_offset throughout. Suffix _array for offset convention. |
+| `Vector4.multiplyVector3` | `Vector4.multiply` | [Vector4.js](Vector4.js) <br>*[move → Vector4.js]* | Match Vector2/Vector3 multiply; also FIX missing 'return this' (breaks fluent contract). |
+| `aabb3_transformed_compute_plane_side (plane_offset, box-first)` | `aabb3_transformed_compute_plane_side` | [3d/aabb/aabb3_transformed_compute_plane_side.js](3d/aabb/aabb3_transformed_compute_plane_side.js) <br>*[move → 3d/aabb/aabb3_transformed_compute_plane_side.js]* | FIX BUG (signed distance used as truthy bool) + rename plane_offset->plane_constant + make plane-first to match aabb3_compute_plane_side. |
+| `circle_intersects_point` | `circle_contains_point` | [2d/circle/circle_intersects_point.js](2d/circle/circle_intersects_point.js) <br>*[move → 2d/circle/circle_contains_point.js]* | Containment, not intersection; ALSO FIX BUG v2_distance(cx,cx,...) ignoring cy. |
+| `circle_compute_circle_penetration` | `circle_compute_penetration` | [2d/circle/circle_compute_circle_penetration.js](2d/circle/circle_compute_circle_penetration.js) <br>*[move → 2d/circle/circle_compute_penetration.js]* | Redundant circle repetition; ALSO FIX BUG dy = by - ax (should be by - ay). |
+| `TransformedShape3D.isTransformedShape3D (on constructor)` | `TransformedShape3D.prototype.isTransformedShape3D` | [3d/shape/TransformedShape3D.js](3d/shape/TransformedShape3D.js) <br>*[move → 3d/shape/TransformedShape3D.js]* | Marker must be on the prototype like every sibling so instance-side dispatch works. |
+| `triangle_encode_rasterized_depth + triangle_decode_depth (2 exports)` | `triangle_rasterized_depth_sample_index + tri_decode_rasterized_depth (split)` | [3d/tetrahedra/triangle/triangle_encode_rasterized_depth.js](3d/tetrahedra/triangle/triangle_encode_rasterized_depth.js) <br>*[move → 3d/tetrahedra/triangle/triangle_rasterized_depth_sample_index.js]* | 'encode' is misleading (returns a vertex index, not encoded depth); split the mismatched 2nd export (`triangle_decode_depth`) into its own file. (No correctness bug — the "dead return" claim was verified false.) |
+| `compareEdges (not exported, v0 compared twice)` | `compare_edges (ADD export, FIX v1 bug)` | [3d/topology/compareEdges.js](3d/topology/compareEdges.js) <br>*[move → 3d/topology/compare_edges.js]* | Dead (unexported) AND buggy (compares a.v0,b.v0 twice, never v1); export and fix. |
+
+### param-name-vocabulary-drift (7)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `vector_copy` | `vector_copy_offset` | [vec/vector_copy.js](vec/vector_copy.js) <br>*[move → vec/vector_copy_offset.js]* | Takes offsets but carried no _offset; align with vector_dot_offset family; rename param length->n. |
+| `vector_dot_offset (params aOff/bOff)` | `vector_dot_offset` | [vec/vector_dot_offset.js](vec/vector_dot_offset.js) <br>*[move → vec/vector_dot_offset.js]* | Name OK; rename camelCase offsets aOff/bOff -> a_offset/b_offset (codebase is snake_case). |
+| `vector_axpy_offset (params yOff/xOff)` | `vector_axpy_offset` | [vec/vector_axpy_offset.js](vec/vector_axpy_offset.js) <br>*[move → vec/vector_axpy_offset.js]* | Name OK; rename yOff/xOff -> y_offset/x_offset. |
+| `m3_determinant (9 scalars)` | `m3_determinant` | [mat3/m3_determinant.js](mat3/m3_determinant.js) <br>*[move → mat3/m3_determinant.js]* | Name OK; change signature to take a 9-element array to match m2_determinant and the rest of mat3 (calling-convention consistency). |
+| `aabb3_transform_oriented_inverse (out/world_aabb/pos_/rot_)` | `aabb3_transform_oriented_inverse` | [3d/aabb/aabb3_transform_oriented_inverse.js](3d/aabb/aabb3_transform_oriented_inverse.js) <br>*[move → 3d/aabb/aabb3_transform_oriented_inverse.js]* | Name OK; align with forward twin: same input form (scalars), result/result_offset names, qx..qw. |
+| `convex_hull_monotone_2d` | `convex_hull_monotone_2d` | [2d/convex-hull/convex_hull_monotone_2d.js](2d/convex-hull/convex_hull_monotone_2d.js) <br>*[move → 2d/convex-hull/convex_hull_monotone_2d.js]* | Name OK; rename param input/points -> points uniformly across hull siblings. |
+| `uv_map_square_to_circle (params x,y)` | `uv_map_square_to_circle` | [2d/uv_map_square_to_circle.js](2d/uv_map_square_to_circle.js) <br>*[move → 2d/uv_map_square_to_circle.js]* | Name OK; rename input params x,y -> u,v to match the inverse uv_map_circle_to_square. |
+
+### nearest-vs-closest-synonym (6)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `line3_compute_segment_nearest_point_to_point_t` | `line3_compute_segment_closest_point_t` | [3d/line/line3_compute_segment_nearest_point_to_point_t.js](3d/line/line3_compute_segment_nearest_point_to_point_t.js) <br>*[move → 3d/line/line3_compute_segment_closest_point_t.js]* | nearest->closest; drop to_point stutter; keep _t (returns parameter). |
+| `line3_compute_segment_nearest_point_to_aabb3_t` | `line3_compute_segment_closest_point_to_aabb3_t` | [3d/line/line3_compute_segment_nearest_point_to_aabb3_t.js](3d/line/line3_compute_segment_nearest_point_to_aabb3_t.js) <br>*[move → 3d/line/line3_compute_segment_closest_point_to_aabb3_t.js]* | nearest->closest for consistency. |
+| `ray3_compute_nearest_point_to_point` | `ray3_compute_closest_point` | [3d/ray/ray3_compute_nearest_point_to_point.js](3d/ray/ray3_compute_nearest_point_to_point.js) <br>*[move → 3d/ray/ray3_compute_closest_point.js]* | nearest->closest; drop PointToPoint stutter; provide flat-array+offset sink (v3-object only as wrapper). |
+| `AABB2.computeNearestPointToPoint` | `AABB2.computeClosestPoint` | [2d/aabb/AABB2.js](2d/aabb/AABB2.js) <br>*[move → 2d/aabb/AABB2.js]* | nearest->closest; drop PointToPoint stutter. |
+| `aabb3_nearest_point_on_surface` | `aabb3_closest_point_on_surface` | [3d/aabb/aabb3_nearest_point_on_surface.js](3d/aabb/aabb3_nearest_point_on_surface.js) <br>*[move → 3d/aabb/aabb3_closest_point_on_surface.js]* | nearest->closest; add result_offset; rename r_x/r_y/r_z -> point_x/point_y/point_z. |
+| `qt_query_data_nearest_to_point` | `qt_query_closest_to_point` | [2d/quad-tree/qt_query_data_nearest_to_point.js](2d/quad-tree/qt_query_data_nearest_to_point.js) <br>*[move → 2d/quad-tree/qt_query_closest_to_point.js]* | nearest->closest; drop redundant 'data'. |
+
+### out-param-and-return-shape-divergence (5)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `Vector4.readFromArray / writeToArray / setFromArray` | `Vector4.fromArray / toArray` | [Vector4.js](Vector4.js) <br>*[move → Vector4.js]* | Standardize on fromArray/toArray like Vector2/Vector3; remove setFromArray duplicate and the define-then-clobber toArray trap. |
+| `m4_multiply_alphatensor` | `m4_multiply_alphatensor (@deprecated)` | [3d/mat4/m4_multiply_alphatensor.js](3d/mat4/m4_multiply_alphatensor.js) <br>*[move → 3d/mat4/m4_multiply_alphatensor.js]* | Strictly slower duplicate of m4_multiply; mark experimental/deprecated and fix JSDoc params (a_in/b_in). |
+| `box3_raycast vs aabb3_raycast` | `aabb3_raycast_hit_point` | [3d/aabb/aabb3_raycast.js](3d/aabb/aabb3_raycast.js) <br>*[move → 3d/aabb/aabb3_raycast_hit_point.js]* | Disambiguate the legacy bool+position+quantized-normal variant from the canonical distance+exact-normal box3_raycast; encode the contract in the name. |
+| `sphere_raycast` | `sphere_raycast` | [3d/sphere/sphere_raycast.js](3d/sphere/sphere_raycast.js) <br>*[move → 3d/sphere/sphere_raycast.js]* | Keep 'raycast' as the documented distance+normal producer family (box3_raycast/capsule_raycast share it); no rename, listed to lock the family — but document it is the producer counterpart of sphere_intersects_ray. |
+| `ConvexHullShape3D.recompute` | `ConvexHullShape3D.recompute_cached` | [3d/shape/ConvexHullShape3D.js](3d/shape/ConvexHullShape3D.js) <br>*[move → 3d/shape/ConvexHullShape3D.js]* | Match MeshShape3D.recompute_cached for the same derived-state refresh role. |
+
+### sqr-placement-and-companion-coverage (4)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `Vector3.lengthSq` | `Vector3.lengthSqr` | [Vector3.js](Vector3.js) <br>*[move → Vector3.js]* | Trailing-_sqr spelling; drop the lengthSq alias. |
+| `Vector3.distanceToSquared` | `Vector3.distanceSqrTo` | [Vector3.js](Vector3.js) <br>*[move → Vector3.js]* | Standardize on _sqr token (distanceSqrTo); drop distanceToSquared alias. |
+| `aabb3_signed_distance_sqr_to_point` | `aabb3_signed_distance_sqr_to_point` | [3d/aabb/aabb3_signed_distance_sqr_to_point.js](3d/aabb/aabb3_signed_distance_sqr_to_point.js) <br>*[move → 3d/aabb/aabb3_signed_distance_sqr_to_point.js]* | Conforms (trailing _sqr); listed as exemplar — add missing aabb3_signed_distance_to_point companion. |
+| `convex_hull_jarvis_2d` | `convex_hull_jarvis_2d` | [2d/convex-hull/convex_hull_jarvis_2d.js](2d/convex-hull/convex_hull_jarvis_2d.js) <br>*[move → 2d/convex-hull/convex_hull_jarvis_2d.js]* | Name OK; rename private dist2_array -> dist_sqr_indexed (2 means squared, banned). |
+
+### vendor-token-three-vs-threejs-vs-geometry (4)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `Vector4.threeApplyMatrix4` | `(remove / @deprecated)` | [Vector4.js](Vector4.js) <br>*[move → Vector4.js]* | Vendor-coupled (three.js Matrix4); applyMatrix4 already takes a flat array. Confine vendor types to boundaries. |
+| `aabb3_from_threejs_geometry` | `aabb3_from_three_geometry` | [3d/aabb/aabb3_from_threejs_geometry.js](3d/aabb/aabb3_from_threejs_geometry.js) <br>*[move → 3d/aabb/aabb3_from_three_geometry.js]* | Single vendor token 'three'. |
+| `computeTriangleRayIntersectionBarycentricGeometry` | `tri3_ray_intersection_indexed` | [3d/triangle/computeTriangleRayIntersectionBarycentricGeometry.js](3d/triangle/computeTriangleRayIntersectionBarycentricGeometry.js) <br>*[move → 3d/triangle/tri3_ray_intersection_indexed.js]* | camelCase->snake; 'Geometry' vendor token -> 'indexed' (it takes indices+positions). |
+| `plane3_three_compute_convex_3_plane_intersection` | `plane3_compute_3_plane_intersection_from_three` | [3d/plane/plane3_three_compute_convex_3_plane_intersection.js](3d/plane/plane3_three_compute_convex_3_plane_intersection.js) <br>*[move → 3d/plane/plane3_compute_3_plane_intersection_from_three.js]* | Move vendor token to a clear adapter suffix so 'three' doesn't collide with the count 3; drop 'convex'. |
+
+### casing-of-constants-and-acronyms (2)
+
+| old | → new | file | why |
+|-----|-------|------|-----|
+| `aabb3_score_boxes_SAH` | `aabb3_score_boxes_sah` | [3d/aabb/aabb3_score_boxes_SAH.js](3d/aabb/aabb3_score_boxes_SAH.js) <br>*[move → 3d/aabb/aabb3_score_boxes_sah.js]* | Lowercase the embedded acronym to match snake convention; switch to inline export function. |
+| `aabb3_corner_edge_mapping / aabb3_edge_corner_mapping / aabb3_edge_plane_mapping` | `AABB3_CORNER_EDGE_MAPPING (etc.)` | [3d/aabb/aabb3_corner_edge_mapping.js](3d/aabb/aabb3_corner_edge_mapping.js) <br>*[move → 3d/aabb/AABB3_CORNER_EDGE_MAPPING.js]* | Constant lookup tables -> constUpper, matching M4_IDENTITY. |
+