@faicad/faijs 0.13.0

package/dist/mesh/knurl/textureLoader.js

@@ -0,0 +1,40 @@
+/**
+ * textureLoader — 滚花纹理加载器
+ *
+ * 浏览器环境：由 host 通过 setKnurlTextureLoader() 注入纹理加载器。
+ * Node 环境：返回 null（由 TextureSampler port 提供纹理）。
+ *
+ * F5 设计意图说明：
+ * _textureLoaderOverride 是环境级单例，不是实例级。
+ * 在整个浏览器页面中，滚花纹理只应加载一次。
+ * 多个 CadRuntime 实例共享同一个纹理加载器是正确的行为。
+ */
+/** 纹理加载器覆盖函数（由浏览器 host 注入） */
+let _textureLoaderOverride = null;
+/**
+ * Set the knurling texture loader (injected by the browser host at startup).
+ *
+ * @param loader - the loader to use, or null to clear the override.
+ */
+export function setKnurlTextureLoader(loader) {
+    _textureLoaderOverride = loader;
+}
+/**
+ * Load the knurling texture. Uses the injected host loader when present;
+ * otherwise returns null (the texture is supplied through the port).
+ *
+ * @returns the texture data, or null when no loader is available.
+ */
+export async function loadKnurlingTexture() {
+    if (_textureLoaderOverride) {
+        return _textureLoaderOverride();
+    }
+    // In the faijs engine the texture is provided through the TextureSampler
+    // port; this function only serves as a fallback when no override is set.
+    return null;
+}
+/** Dispose the knurl preview material; a no-op in the headless engine. */
+export function disposeKnurlPreviewMaterial() {
+    // no-op in headless
+}
+//# sourceMappingURL=textureLoader.js.map

package/dist/mesh/knurl/textureLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureLoader.js","sourceRoot":"","sources":["../../../src/mesh/knurl/textureLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,8BAA8B;AAC9B,IAAI,sBAAsB,GAA+C,IAAI,CAAA;AAE7E;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAkD;IACtF,sBAAsB,GAAG,MAAM,CAAA;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,IAAI,sBAAsB,EAAE,CAAC;QAC3B,OAAO,sBAAsB,EAAE,CAAA;IACjC,CAAC;IACD,yEAAyE;IACzE,yEAAyE;IACzE,OAAO,IAAI,CAAA;AACb,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,2BAA2B;IACzC,oBAAoB;AACtB,CAAC","sourcesContent":["/**\n * textureLoader — 滚花纹理加载器\n *\n * 浏览器环境：由 host 通过 setKnurlTextureLoader() 注入纹理加载器。\n * Node 环境：返回 null（由 TextureSampler port 提供纹理）。\n *\n * F5 设计意图说明：\n * _textureLoaderOverride 是环境级单例，不是实例级。\n * 在整个浏览器页面中，滚花纹理只应加载一次。\n * 多个 CadRuntime 实例共享同一个纹理加载器是正确的行为。\n */\n\nimport * as THREE from 'three'\n\n/**\n * Raw RGBA pixel data plus the pixel dimensions of a loaded texture.\n */\nexport interface TextureData {\n  data: Uint8ClampedArray\n  width: number\n  height: number\n}\n\n/** 纹理加载器覆盖函数（由浏览器 host 注入） */\nlet _textureLoaderOverride: (() => Promise<TextureData | null>) | null = null\n\n/**\n * Set the knurling texture loader (injected by the browser host at startup).\n *\n * @param loader - the loader to use, or null to clear the override.\n */\nexport function setKnurlTextureLoader(loader: (() => Promise<TextureData | null>) | null): void {\n  _textureLoaderOverride = loader\n}\n\n/**\n * Load the knurling texture. Uses the injected host loader when present;\n * otherwise returns null (the texture is supplied through the port).\n *\n * @returns the texture data, or null when no loader is available.\n */\nexport async function loadKnurlingTexture(): Promise<TextureData | null> {\n  if (_textureLoaderOverride) {\n    return _textureLoaderOverride()\n  }\n  // In the faijs engine the texture is provided through the TextureSampler\n  // port; this function only serves as a fallback when no override is set.\n  return null\n}\n\n/** Dispose the knurl preview material; a no-op in the headless engine. */\nexport function disposeKnurlPreviewMaterial(): void {\n  // no-op in headless\n}\n\n/** Bounds type shared with the knurl preview path (a THREE.Box3). */\nexport type KnurlPreviewBounds = THREE.Box3\n"]}

package/dist/mesh/manifold-loader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * manifold-loader — 环境级单例加载 manifold-3d 核心模块
+ *
+ * F5 设计意图说明：
+ * manifoldPromise 是环境级单例，不是实例级。
+ * 在整个浏览器页面/Node 进程中，manifold-3d WASM 只应初始化一次。
+ * 多个 CadRuntime 实例共享同一个 manifold 模块是正确的行为。
+ *
+ * 浏览器与 Node 共用（node-host 的 Inline 后端与浏览器 Worker 后端都走这里）。
+ * 加载逻辑复刻 manifold-3d lib/wasm.js 的 instantiateManifold：
+ * `Module({ locateFile })` + `module.setup()`，两步缺一不可。
+ *
+ * 必须用根裸导入 `import('manifold-3d')`：Node 的 package.json main、
+ * exports 的 "." 与 importmap 的精确键都解析到同一个 manifold.js。
+ * 若写成子路径导入，build 产物需要 importmap 提供对应的精确键，
+ * 否则以 "Failed to resolve module specifier" 崩掉。
+ */
+import type { ManifoldToplevel } from 'manifold-3d/manifold';
+/**
+ * Specify the URL from which manifold.wasm is loaded.
+ * Must be called before the first getManifoldModule() (module-level cache,
+ * matching the official setWasmUrl semantics).
+ *
+ * @param url - the wasm file URL.
+ */
+export declare function setManifoldWasmUrl(url: string): void;
+/**
+ * Read the currently configured wasm URL (used by the Worker backend during
+ * the initialization handshake).
+ *
+ * @returns the configured wasm URL, or undefined when none was set.
+ */
+export declare function getManifoldWasmUrl(): string | undefined;
+/**
+ * Get (and cache) the Manifold WASM module instance, loaded once per
+ * environment.
+ *
+ * @returns a promise resolving to the initialized Manifold module.
+ */
+export declare function getManifoldModule(): Promise<ManifoldToplevel>;
+//# sourceMappingURL=manifold-loader.d.ts.map

package/dist/mesh/manifold-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifold-loader.d.ts","sourceRoot":"","sources":["../../src/mesh/manifold-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAK5D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAEvD;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAUnE"}

package/dist/mesh/manifold-loader.js

@@ -0,0 +1,56 @@
+/**
+ * manifold-loader — 环境级单例加载 manifold-3d 核心模块
+ *
+ * F5 设计意图说明：
+ * manifoldPromise 是环境级单例，不是实例级。
+ * 在整个浏览器页面/Node 进程中，manifold-3d WASM 只应初始化一次。
+ * 多个 CadRuntime 实例共享同一个 manifold 模块是正确的行为。
+ *
+ * 浏览器与 Node 共用（node-host 的 Inline 后端与浏览器 Worker 后端都走这里）。
+ * 加载逻辑复刻 manifold-3d lib/wasm.js 的 instantiateManifold：
+ * `Module({ locateFile })` + `module.setup()`，两步缺一不可。
+ *
+ * 必须用根裸导入 `import('manifold-3d')`：Node 的 package.json main、
+ * exports 的 "." 与 importmap 的精确键都解析到同一个 manifold.js。
+ * 若写成子路径导入，build 产物需要 importmap 提供对应的精确键，
+ * 否则以 "Failed to resolve module specifier" 崩掉。
+ */
+let wasmUrl;
+let manifoldPromise = null;
+/**
+ * Specify the URL from which manifold.wasm is loaded.
+ * Must be called before the first getManifoldModule() (module-level cache,
+ * matching the official setWasmUrl semantics).
+ *
+ * @param url - the wasm file URL.
+ */
+export function setManifoldWasmUrl(url) {
+    wasmUrl = url;
+}
+/**
+ * Read the currently configured wasm URL (used by the Worker backend during
+ * the initialization handshake).
+ *
+ * @returns the configured wasm URL, or undefined when none was set.
+ */
+export function getManifoldWasmUrl() {
+    return wasmUrl;
+}
+/**
+ * Get (and cache) the Manifold WASM module instance, loaded once per
+ * environment.
+ *
+ * @returns a promise resolving to the initialized Manifold module.
+ */
+export async function getManifoldModule() {
+    if (!manifoldPromise) {
+        manifoldPromise = import('manifold-3d').then(async (m) => {
+            const url = wasmUrl;
+            const mod = await m.default(url ? { locateFile: () => url } : undefined);
+            mod.setup();
+            return mod;
+        });
+    }
+    return manifoldPromise;
+}
+//# sourceMappingURL=manifold-loader.js.map

package/dist/mesh/manifold-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifold-loader.js","sourceRoot":"","sources":["../../src/mesh/manifold-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,IAAI,OAA2B,CAAA;AAC/B,IAAI,eAAe,GAAqC,IAAI,CAAA;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,GAAG,GAAG,CAAA;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,eAAe,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YACvD,MAAM,GAAG,GAAG,OAAO,CAAA;YACnB,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;YACxE,GAAG,CAAC,KAAK,EAAE,CAAA;YACX,OAAO,GAAG,CAAA;QACZ,CAAC,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,eAAe,CAAA;AACxB,CAAC","sourcesContent":["/**\n * manifold-loader — 环境级单例加载 manifold-3d 核心模块\n *\n * F5 设计意图说明：\n * manifoldPromise 是环境级单例，不是实例级。\n * 在整个浏览器页面/Node 进程中，manifold-3d WASM 只应初始化一次。\n * 多个 CadRuntime 实例共享同一个 manifold 模块是正确的行为。\n *\n * 浏览器与 Node 共用（node-host 的 Inline 后端与浏览器 Worker 后端都走这里）。\n * 加载逻辑复刻 manifold-3d lib/wasm.js 的 instantiateManifold：\n * `Module({ locateFile })` + `module.setup()`，两步缺一不可。\n *\n * 必须用根裸导入 `import('manifold-3d')`：Node 的 package.json main、\n * exports 的 \".\" 与 importmap 的精确键都解析到同一个 manifold.js。\n * 若写成子路径导入，build 产物需要 importmap 提供对应的精确键，\n * 否则以 \"Failed to resolve module specifier\" 崩掉。\n */\n\nimport type { ManifoldToplevel } from 'manifold-3d/manifold'\n\nlet wasmUrl: string | undefined\nlet manifoldPromise: Promise<ManifoldToplevel> | null = null\n\n/**\n * Specify the URL from which manifold.wasm is loaded.\n * Must be called before the first getManifoldModule() (module-level cache,\n * matching the official setWasmUrl semantics).\n *\n * @param url - the wasm file URL.\n */\nexport function setManifoldWasmUrl(url: string): void {\n  wasmUrl = url\n}\n\n/**\n * Read the currently configured wasm URL (used by the Worker backend during\n * the initialization handshake).\n *\n * @returns the configured wasm URL, or undefined when none was set.\n */\nexport function getManifoldWasmUrl(): string | undefined {\n  return wasmUrl\n}\n\n/**\n * Get (and cache) the Manifold WASM module instance, loaded once per\n * environment.\n *\n * @returns a promise resolving to the initialized Manifold module.\n */\nexport async function getManifoldModule(): Promise<ManifoldToplevel> {\n  if (!manifoldPromise) {\n    manifoldPromise = import('manifold-3d').then(async (m) => {\n      const url = wasmUrl\n      const mod = await m.default(url ? { locateFile: () => url } : undefined)\n      mod.setup()\n      return mod\n    })\n  }\n  return manifoldPromise\n}\n"]}

package/dist/mesh/primitives.d.ts

@@ -0,0 +1,104 @@
+/**
+ * mesh 基本体 API — 从现有纯函数提取的统一接口
+ *
+ * 提取来源（§5.7）：
+ * - box/sphere/cylinder/cone/wedge ← engine/primitives/mesh-primitives.ts (makePrimitiveGeo)
+ * - text ← engine/components/engraving/EngravingCore.ts (createTextGeometry)
+ * - screw ← engine/primitives/screw/screw.ts (makeScrew)
+ * - svgExtrude ← engine/primitives/svg-extrude/ (svgToExtrudedGeometry)
+ *
+ * 所有函数返回 Shape (ManifoldMeshData)：THREE.BufferGeometry → geoToManifoldMesh 转换。
+ * 坐标系：Z-up、毫米。
+ */
+import type { Shape, BoxParams, SphereParams, CylinderParams, ConeParams, WedgeParams, TextParams, SvgExtrudeParams, SdfParams } from './types.js';
+/**
+ * Create a box solid (brepjs contract, §4.1 A 决策).
+ *
+ * `box(width, depth, height)` — X=width, Y=depth, Z=height — places the
+ * min-corner at the origin by default (`centered:false`). `centered: true`
+ * centers the box at the origin; `at` is CENTER semantics and takes precedence
+ * over `centered`. The `segments` option is consumed by the tessellation
+ * caller (this mesh builder keeps it via clampNRad when present).
+ *
+ * @param params - box parameters (width/depth/height, optional at/centered/segments).
+ * @returns the box shape.
+ */
+export declare function box(params: BoxParams): Shape;
+/**
+ * Create a sphere centered at the origin (or the optional `center`).
+ *
+ * @param params - sphere parameters (radius, optional segments, optional center).
+ * @returns the sphere shape.
+ */
+export declare function sphere(params: SphereParams): Shape;
+/**
+ * Create a cylinder along +Z (`cylinder(radius, height, { at?, centered?,
+ * segments? })` brepjs 契约，§4.3 A 决策；与 brep 路径逐点对齐）。
+ *
+ * 锚点：`at` 是**底面轴心**（BASE）语义（默认 [0,0,0]，底面在原点、+Z 延伸）；
+ * `centered:true` 指底面落到 −h/2（无 at 时居中到原点）——与 `at` 同给时以
+ * `at` 为中心。`segments` 经 clampNRad 消费（P0 §5）。
+ *
+ * @param params - cylinder parameters (radius, height, optional at/centered/segments).
+ * @returns the cylinder shape.
+ */
+export declare function cylinder(params: CylinderParams): Shape;
+/**
+ * Create a cone, or a frustum when the top and bottom radii differ
+ * (`cone(bottomRadius, topRadius, height, { at?, centered?, segments? })` brepjs
+ * 契约，§4.1 P 决策；与 brep 路径逐点对齐）。
+ *
+ * 锚点：`at` 是**底面轴心**（BASE）语义（默认 [0,0,0]，底面在原点、+Z 延伸）；
+ * `centered:true` 指底面落到 −h/2（无 at 时居中到原点）——与 `at` 同给时以
+ * `at` 为中心。`segments` 经 clampNRad 消费（P0 §5）。
+ *
+ * @param params - cone parameters (radiusBottom, radiusTop, height, optional at/centered/segments).
+ * @returns the cone shape.
+ */
+export declare function cone(params: ConeParams): Shape;
+/**
+ * Create a wedge (ramp) solid, fully parameterized and Z-up.
+ *
+ * @param params - wedge parameters (width, height, angle, length, optional center).
+ * @returns the wedge shape.
+ */
+export declare function wedge(params: WedgeParams): Shape;
+/**
+ * Create text geometry. Font loading is asynchronous, so this function is
+ * async; CJK text is rendered with the system font when one is available.
+ *
+ * @param params - text parameters (text, size, depth).
+ * @returns the text shape.
+ */
+export declare function text(params: TextParams): Promise<Shape>;
+/**
+ * Create a screw (threaded) geometry.
+ *
+ * @param params - screw parameters (system, specIdx, thread, length, head, optional pitchCustom and nRad).
+ * @returns the screw shape.
+ */
+export declare function screw(params: {
+    system: 'metric' | 'imperial';
+    specIdx: number;
+    thread: 'coarse' | 'fine' | 'custom' | 'none';
+    pitchCustom?: number;
+    length: number;
+    head: 'hex' | 'chc' | 'none';
+    nRad?: number;
+}): Promise<Shape>;
+/**
+ * Create an extruded geometry from an SVG source.
+ *
+ * @param params - SVG extrude parameters (svg, depth, target size, optional natural size).
+ * @returns the extruded shape.
+ */
+export declare function svgExtrude(params: SvgExtrudeParams): Shape;
+/**
+ * Create a mesh from SDF (signed distance field) code, sampling the field with
+ * marching cubes.
+ *
+ * @param params - SDF parameters (code, optional bounds, params, resolution).
+ * @returns the sampled shape.
+ */
+export declare function sdf(params: SdfParams): Promise<Shape>;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/mesh/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/mesh/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAY/I;;;;;;;;;;;GAWG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,CAsB5C;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAOlD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,KAAK,CAWtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,KAAK,CA8B9C;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CA0DhD;AAED;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAwB7D;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,MAAM,EAAE;IAClC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAA;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAA;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GAAG,OAAO,CAAC,KAAK,CAAC,CAYjB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,KAAK,CAQ1D;AAED;;;;;;GAMG;AACH,wBAAsB,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAc3D"}

package/dist/mesh/primitives.js

@@ -0,0 +1,275 @@
+/**
+ * mesh 基本体 API — 从现有纯函数提取的统一接口
+ *
+ * 提取来源（§5.7）：
+ * - box/sphere/cylinder/cone/wedge ← engine/primitives/mesh-primitives.ts (makePrimitiveGeo)
+ * - text ← engine/components/engraving/EngravingCore.ts (createTextGeometry)
+ * - screw ← engine/primitives/screw/screw.ts (makeScrew)
+ * - svgExtrude ← engine/primitives/svg-extrude/ (svgToExtrudedGeometry)
+ *
+ * 所有函数返回 Shape (ManifoldMeshData)：THREE.BufferGeometry → geoToManifoldMesh 转换。
+ * 坐标系：Z-up、毫米。
+ */
+import * as THREE from 'three';
+import { makePrimitiveGeo } from '../primitives/mesh-primitives.js';
+import { geoToManifoldMesh } from '../boolean/csg-backend.js';
+import { svgToExtrudedGeometry } from '../primitives/svg-extrude.js';
+import { clampNRad } from './types.js';
+// ── 内部工具 ──
+/** THREE.BufferGeometry → Shape (ManifoldMeshData) */
+function geoToShape(geo) {
+    return geoToManifoldMesh(geo);
+}
+// ── 创建 API ──
+/**
+ * Create a box solid (brepjs contract, §4.1 A 决策).
+ *
+ * `box(width, depth, height)` — X=width, Y=depth, Z=height — places the
+ * min-corner at the origin by default (`centered:false`). `centered: true`
+ * centers the box at the origin; `at` is CENTER semantics and takes precedence
+ * over `centered`. The `segments` option is consumed by the tessellation
+ * caller (this mesh builder keeps it via clampNRad when present).
+ *
+ * @param params - box parameters (width/depth/height, optional at/centered/segments).
+ * @returns the box shape.
+ */
+export function box(params) {
+    const { width, depth, height } = params;
+    // THREE.BoxGeometry(a, b, c) is Y-up (X=a, Y=b, Z=c); after the +90° rotateX
+    // the dims map to X=a, Y=c, Z=b. To reach X=width, Y=depth, Z=height the
+    // pre-rotation sizes must be (width, height, depth) — 裁决 7 xyz contract.
+    const geo = new THREE.BoxGeometry(width, height, depth);
+    geo.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2));
+    // brepjs box semantics: corner at origin by default; centered at origin when
+    // `centered` (no `at`); `at` (CENTER semantics) takes precedence.
+    const at = params.at;
+    let tx = 0;
+    let ty = 0;
+    let tz = 0;
+    if (at !== undefined) {
+        ;
+        [tx, ty, tz] = at;
+    }
+    else if (!params.centered) {
+        tx = width / 2;
+        ty = depth / 2;
+        tz = height / 2;
+    }
+    if (tx !== 0 || ty !== 0 || tz !== 0)
+        geo.translate(tx, ty, tz);
+    return geoToShape(geo);
+}
+/**
+ * Create a sphere centered at the origin (or the optional `center`).
+ *
+ * @param params - sphere parameters (radius, optional segments, optional center).
+ * @returns the sphere shape.
+ */
+export function sphere(params) {
+    const segs = clampNRad(params.nRad ?? params.segments);
+    const geo = makePrimitiveGeo('sphere', params.radius * 2, segs);
+    if (params.center) {
+        geo.translate(params.center[0], params.center[1], params.center[2]);
+    }
+    return geoToShape(geo);
+}
+/**
+ * Create a cylinder along +Z (`cylinder(radius, height, { at?, centered?,
+ * segments? })` brepjs 契约，§4.3 A 决策；与 brep 路径逐点对齐）。
+ *
+ * 锚点：`at` 是**底面轴心**（BASE）语义（默认 [0,0,0]，底面在原点、+Z 延伸）；
+ * `centered:true` 指底面落到 −h/2（无 at 时居中到原点）——与 `at` 同给时以
+ * `at` 为中心。`segments` 经 clampNRad 消费（P0 §5）。
+ *
+ * @param params - cylinder parameters (radius, height, optional at/centered/segments).
+ * @returns the cylinder shape.
+ */
+export function cylinder(params) {
+    const segs = clampNRad(params.nRad ?? params.segments);
+    const geo = new THREE.CylinderGeometry(params.radius, params.radius, params.height, segs);
+    geo.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2));
+    // geometry（rotateX 后）沿 z ∈ [-h/2, +h/2]（three 默认 Y-up 居中）：
+    // 目标底面中心 in baseZ = (at?.[2] ?? 0) - (centered ? h/2 : 0) → 平移到 baseZ + h/2。
+    const baseX = params.at?.[0] ?? 0;
+    const baseY = params.at?.[1] ?? 0;
+    const baseZ = (params.at?.[2] ?? 0) - (params.centered === true ? params.height / 2 : 0);
+    geo.translate(baseX, baseY, baseZ + params.height / 2);
+    return geoToShape(geo);
+}
+/**
+ * Create a cone, or a frustum when the top and bottom radii differ
+ * (`cone(bottomRadius, topRadius, height, { at?, centered?, segments? })` brepjs
+ * 契约，§4.1 P 决策；与 brep 路径逐点对齐）。
+ *
+ * 锚点：`at` 是**底面轴心**（BASE）语义（默认 [0,0,0]，底面在原点、+Z 延伸）；
+ * `centered:true` 指底面落到 −h/2（无 at 时居中到原点）——与 `at` 同给时以
+ * `at` 为中心。`segments` 经 clampNRad 消费（P0 §5）。
+ *
+ * @param params - cone parameters (radiusBottom, radiusTop, height, optional at/centered/segments).
+ * @returns the cone shape.
+ */
+export function cone(params) {
+    const segs = clampNRad(params.nRad ?? params.segments);
+    const geo = new THREE.ConeGeometry(Math.max(params.radiusBottom, params.radiusTop), params.height, segs);
+    geo.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2));
+    // radiusTop === 0 → 尖锥（ConeGeometry 顶点在顶）；其余（含 radiusTop ===
+    // radiusBottom 的等径圆柱/圆台）用 CylinderGeometry（radiusTop/bottom 各就各位）。
+    let resultGeo;
+    if (params.radiusTop === 0) {
+        resultGeo = geo;
+    }
+    else {
+        const geo2 = new THREE.CylinderGeometry(params.radiusTop, params.radiusBottom, params.height, segs);
+        geo2.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2));
+        resultGeo = geo2;
+    }
+    // geometry（rotateX 后）沿 z ∈ [-h/2, +h/2]（three 默认 Y-up 居中）：
+    // 目标底面中心 in baseZ = (at?.[2] ?? 0) - (centered ? h/2 : 0) → 平坦平移 baseZ + h/2。
+    const baseX = params.at?.[0] ?? 0;
+    const baseY = params.at?.[1] ?? 0;
+    const baseZ = (params.at?.[2] ?? 0) - (params.centered === true ? params.height / 2 : 0);
+    resultGeo.translate(baseX, baseY, baseZ + params.height / 2);
+    return geoToShape(resultGeo);
+}
+/**
+ * Create a wedge (ramp) solid, fully parameterized and Z-up.
+ *
+ * @param params - wedge parameters (width, height, angle, length, optional center).
+ * @returns the wedge shape.
+ */
+export function wedge(params) {
+    const width = params.width;
+    const height = params.height;
+    const angle = params.angle;
+    const length = params.length;
+    const angleRad = (angle * Math.PI) / 180;
+    const halfExtrude = length / 2;
+    const hw = width / 2;
+    const halfTopWidth = Math.max(0, hw - height / Math.tan(angleRad));
+    // 顶边塌缩（斜坡已在宽度内到顶）→ 三角棱柱（与 brep wedge 的退化处理一致，
+    // 保证 mesh/brep 同参数 bbox 一致；零面积三角形会破坏 manifold）。
+    const degenerate = halfTopWidth <= 1e-12;
+    const positions = degenerate
+        ? new Float32Array([
+            -halfExtrude, -hw, 0,
+            -halfExtrude, hw, 0,
+            -halfExtrude, 0, height,
+            halfExtrude, -hw, 0,
+            halfExtrude, hw, 0,
+            halfExtrude, 0, height,
+        ])
+        : new Float32Array([
+            -halfExtrude, -hw, 0,
+            -halfExtrude, hw, 0,
+            -halfExtrude, halfTopWidth, height,
+            -halfExtrude, -halfTopWidth, height,
+            halfExtrude, -hw, 0,
+            halfExtrude, hw, 0,
+            halfExtrude, halfTopWidth, height,
+            halfExtrude, -halfTopWidth, height,
+        ]);
+    const indices = degenerate
+        ? new Uint32Array([
+            0, 1, 2, 3, 5, 4,
+            0, 3, 4, 0, 4, 1,
+            0, 2, 5, 0, 5, 3,
+            1, 4, 5, 1, 5, 2,
+        ])
+        : new Uint32Array([
+            0, 1, 2, 0, 2, 3,
+            4, 6, 5, 4, 7, 6,
+            0, 4, 5, 0, 5, 1,
+            3, 2, 6, 3, 6, 7,
+            0, 3, 7, 0, 7, 4,
+            1, 5, 6, 1, 6, 2,
+        ]);
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+    geo.setIndex(new THREE.BufferAttribute(indices, 1));
+    if (params.center) {
+        geo.translate(params.center[0], params.center[1], params.center[2]);
+    }
+    return geoToShape(geo);
+}
+/**
+ * Create text geometry. Font loading is asynchronous, so this function is
+ * async; CJK text is rendered with the system font when one is available.
+ *
+ * @param params - text parameters (text, size, depth).
+ * @returns the text shape.
+ */
+export async function text(params) {
+    const { getOpentypeFont, createTextGeometry } = await import('../primitives/text-geometry.js');
+    const { containsCjk, loadSystemCjkFont, createMixedTextGeometry } = await import('../primitives/text/cjk.js');
+    const font = await getOpentypeFont();
+    let geo;
+    if (containsCjk(params.text)) {
+        const cjkFont = await loadSystemCjkFont();
+        if (cjkFont) {
+            geo = await createMixedTextGeometry(params.text, params.size, params.depth, cjkFont.font, font);
+        }
+        else {
+            // No CJK font available: replace CJK chars with '?' so geometry still
+            // can be created (graceful degradation). Without this, createTextGeometry
+            // would throw because CJK glyphs are .notdef in OpenSans Regular.
+            const fallback = params.text.replace(/[\u4E00-\u9FFF\u3400-\u4DBF\u2F800-\u2FA1F\u3000-\u303F\uFF00-\uFFEF]/g, '?');
+            geo = await createTextGeometry(fallback, params.size, params.depth, font);
+        }
+    }
+    else {
+        geo = await createTextGeometry(params.text, params.size, params.depth, font);
+    }
+    return geoToShape(geo);
+}
+/**
+ * Create a screw (threaded) geometry.
+ *
+ * @param params - screw parameters (system, specIdx, thread, length, head, optional pitchCustom and nRad).
+ * @returns the screw shape.
+ */
+export async function screw(params) {
+    const { makeScrew } = await import('../primitives/screw/screw.js');
+    const geo = makeScrew({
+        system: params.system,
+        specIdx: params.specIdx,
+        thread: params.thread,
+        pitchCustom: params.pitchCustom ?? 0,
+        length: params.length,
+        head: params.head,
+        nRad: clampNRad(params.nRad),
+    });
+    return geoToShape(geo);
+}
+/**
+ * Create an extruded geometry from an SVG source.
+ *
+ * @param params - SVG extrude parameters (svg, depth, target size, optional natural size).
+ * @returns the extruded shape.
+ */
+export function svgExtrude(params) {
+    const geo = svgToExtrudedGeometry(params.svg, {
+        depth: params.depth,
+        targetLongSide: params.targetLongSide ?? 20,
+        naturalWidth: params.naturalWidth ?? 0,
+        naturalHeight: params.naturalHeight ?? 0,
+    });
+    return geoToShape(geo);
+}
+/**
+ * Create a mesh from SDF (signed distance field) code, sampling the field with
+ * marching cubes.
+ *
+ * @param params - SDF parameters (code, optional bounds, params, resolution).
+ * @returns the sampled shape.
+ */
+export async function sdf(params) {
+    const { runSdf } = await import('../sdf/sdf-runner.js');
+    const box = params.box ?? [[-10, -10, -10], [10, 10, 10]];
+    const bounds = [
+        box[0][0], box[0][1], box[0][2],
+        box[1][0], box[1][1], box[1][2],
+    ];
+    const mesh = await runSdf(params.code, params.params ?? {}, bounds, params.resolution ?? 1.0);
+    return { positions: mesh.positions, indices: mesh.indices };
+}
+//# sourceMappingURL=primitives.js.map

package/dist/mesh/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/mesh/primitives.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * mesh 基本体 API — 从现有纯函数提取的统一接口\n *\n * 提取来源（§5.7）：\n * - box/sphere/cylinder/cone/wedge ← engine/primitives/mesh-primitives.ts (makePrimitiveGeo)\n * - text ← engine/components/engraving/EngravingCore.ts (createTextGeometry)\n * - screw ← engine/primitives/screw/screw.ts (makeScrew)\n * - svgExtrude ← engine/primitives/svg-extrude/ (svgToExtrudedGeometry)\n *\n * 所有函数返回 Shape (ManifoldMeshData)：THREE.BufferGeometry → geoToManifoldMesh 转换。\n * 坐标系：Z-up、毫米。\n */\n\nimport * as THREE from 'three'\nimport { makePrimitiveGeo } from '../primitives/mesh-primitives'\nimport { geoToManifoldMesh } from '../boolean/csg-backend'\nimport { svgToExtrudedGeometry } from '../primitives/svg-extrude'\nimport type { Shape, BoxParams, SphereParams, CylinderParams, ConeParams, WedgeParams, TextParams, SvgExtrudeParams, SdfParams } from './types'\nimport { clampNRad } from './types'\n\n// ── 内部工具 ──\n\n/** THREE.BufferGeometry → Shape (ManifoldMeshData) */\nfunction geoToShape(geo: THREE.BufferGeometry): Shape {\n  return geoToManifoldMesh(geo)\n}\n\n// ── 创建 API ──\n\n/**\n * Create a box solid (brepjs contract, §4.1 A 决策).\n *\n * `box(width, depth, height)` — X=width, Y=depth, Z=height — places the\n * min-corner at the origin by default (`centered:false`). `centered: true`\n * centers the box at the origin; `at` is CENTER semantics and takes precedence\n * over `centered`. The `segments` option is consumed by the tessellation\n * caller (this mesh builder keeps it via clampNRad when present).\n *\n * @param params - box parameters (width/depth/height, optional at/centered/segments).\n * @returns the box shape.\n */\nexport function box(params: BoxParams): Shape {\n  const { width, depth, height } = params\n  // THREE.BoxGeometry(a, b, c) is Y-up (X=a, Y=b, Z=c); after the +90° rotateX\n  // the dims map to X=a, Y=c, Z=b. To reach X=width, Y=depth, Z=height the\n  // pre-rotation sizes must be (width, height, depth) — 裁决 7 xyz contract.\n  const geo = new THREE.BoxGeometry(width, height, depth)\n  geo.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2))\n  // brepjs box semantics: corner at origin by default; centered at origin when\n  // `centered` (no `at`); `at` (CENTER semantics) takes precedence.\n  const at = params.at\n  let tx = 0\n  let ty = 0\n  let tz = 0\n  if (at !== undefined) {\n    ;[tx, ty, tz] = at\n  } else if (!params.centered) {\n    tx = width / 2\n    ty = depth / 2\n    tz = height / 2\n  }\n  if (tx !== 0 || ty !== 0 || tz !== 0) geo.translate(tx, ty, tz)\n  return geoToShape(geo)\n}\n\n/**\n * Create a sphere centered at the origin (or the optional `center`).\n *\n * @param params - sphere parameters (radius, optional segments, optional center).\n * @returns the sphere shape.\n */\nexport function sphere(params: SphereParams): Shape {\n  const segs = clampNRad(params.nRad ?? params.segments)\n  const geo = makePrimitiveGeo('sphere', params.radius * 2, segs)\n  if (params.center) {\n    geo.translate(params.center[0], params.center[1], params.center[2])\n  }\n  return geoToShape(geo)\n}\n\n/**\n * Create a cylinder along +Z (`cylinder(radius, height, { at?, centered?,\n * segments? })` brepjs 契约，§4.3 A 决策；与 brep 路径逐点对齐）。\n *\n * 锚点：`at` 是**底面轴心**（BASE）语义（默认 [0,0,0]，底面在原点、+Z 延伸）；\n * `centered:true` 指底面落到 −h/2（无 at 时居中到原点）——与 `at` 同给时以\n * `at` 为中心。`segments` 经 clampNRad 消费（P0 §5）。\n *\n * @param params - cylinder parameters (radius, height, optional at/centered/segments).\n * @returns the cylinder shape.\n */\nexport function cylinder(params: CylinderParams): Shape {\n  const segs = clampNRad(params.nRad ?? params.segments)\n  const geo = new THREE.CylinderGeometry(params.radius, params.radius, params.height, segs)\n  geo.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2))\n  // geometry（rotateX 后）沿 z ∈ [-h/2, +h/2]（three 默认 Y-up 居中）：\n  // 目标底面中心 in baseZ = (at?.[2] ?? 0) - (centered ? h/2 : 0) → 平移到 baseZ + h/2。\n  const baseX = params.at?.[0] ?? 0\n  const baseY = params.at?.[1] ?? 0\n  const baseZ = (params.at?.[2] ?? 0) - (params.centered === true ? params.height / 2 : 0)\n  geo.translate(baseX, baseY, baseZ + params.height / 2)\n  return geoToShape(geo)\n}\n\n/**\n * Create a cone, or a frustum when the top and bottom radii differ\n * (`cone(bottomRadius, topRadius, height, { at?, centered?, segments? })` brepjs\n * 契约，§4.1 P 决策；与 brep 路径逐点对齐）。\n *\n * 锚点：`at` 是**底面轴心**（BASE）语义（默认 [0,0,0]，底面在原点、+Z 延伸）；\n * `centered:true` 指底面落到 −h/2（无 at 时居中到原点）——与 `at` 同给时以\n * `at` 为中心。`segments` 经 clampNRad 消费（P0 §5）。\n *\n * @param params - cone parameters (radiusBottom, radiusTop, height, optional at/centered/segments).\n * @returns the cone shape.\n */\nexport function cone(params: ConeParams): Shape {\n  const segs = clampNRad(params.nRad ?? params.segments)\n  const geo = new THREE.ConeGeometry(\n    Math.max(params.radiusBottom, params.radiusTop),\n    params.height,\n    segs,\n  )\n  geo.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2))\n  // radiusTop === 0 → 尖锥（ConeGeometry 顶点在顶）；其余（含 radiusTop ===\n  // radiusBottom 的等径圆柱/圆台）用 CylinderGeometry（radiusTop/bottom 各就各位）。\n  let resultGeo: THREE.BufferGeometry\n  if (params.radiusTop === 0) {\n    resultGeo = geo\n  } else {\n    const geo2 = new THREE.CylinderGeometry(\n      params.radiusTop,\n      params.radiusBottom,\n      params.height,\n      segs,\n    )\n    geo2.applyMatrix4(new THREE.Matrix4().makeRotationX(Math.PI / 2))\n    resultGeo = geo2\n  }\n  // geometry（rotateX 后）沿 z ∈ [-h/2, +h/2]（three 默认 Y-up 居中）：\n  // 目标底面中心 in baseZ = (at?.[2] ?? 0) - (centered ? h/2 : 0) → 平坦平移 baseZ + h/2。\n  const baseX = params.at?.[0] ?? 0\n  const baseY = params.at?.[1] ?? 0\n  const baseZ = (params.at?.[2] ?? 0) - (params.centered === true ? params.height / 2 : 0)\n  resultGeo.translate(baseX, baseY, baseZ + params.height / 2)\n  return geoToShape(resultGeo)\n}\n\n/**\n * Create a wedge (ramp) solid, fully parameterized and Z-up.\n *\n * @param params - wedge parameters (width, height, angle, length, optional center).\n * @returns the wedge shape.\n */\nexport function wedge(params: WedgeParams): Shape {\n  const width = params.width\n  const height = params.height\n  const angle = params.angle\n  const length = params.length\n\n  const angleRad = (angle * Math.PI) / 180\n  const halfExtrude = length / 2\n  const hw = width / 2\n  const halfTopWidth = Math.max(0, hw - height / Math.tan(angleRad))\n  // 顶边塌缩（斜坡已在宽度内到顶）→ 三角棱柱（与 brep wedge 的退化处理一致，\n  // 保证 mesh/brep 同参数 bbox 一致；零面积三角形会破坏 manifold）。\n  const degenerate = halfTopWidth <= 1e-12\n\n  const positions = degenerate\n    ? new Float32Array([\n        -halfExtrude, -hw, 0,\n        -halfExtrude,  hw, 0,\n        -halfExtrude,   0, height,\n         halfExtrude, -hw, 0,\n         halfExtrude,  hw, 0,\n         halfExtrude,   0, height,\n      ])\n    : new Float32Array([\n        -halfExtrude, -hw, 0,\n        -halfExtrude,  hw, 0,\n        -halfExtrude,  halfTopWidth, height,\n        -halfExtrude, -halfTopWidth, height,\n         halfExtrude, -hw, 0,\n         halfExtrude,  hw, 0,\n         halfExtrude,  halfTopWidth, height,\n         halfExtrude, -halfTopWidth, height,\n      ])\n\n  const indices = degenerate\n    ? new Uint32Array([\n        0, 1, 2,  3, 5, 4,\n        0, 3, 4,  0, 4, 1,\n        0, 2, 5,  0, 5, 3,\n        1, 4, 5,  1, 5, 2,\n      ])\n    : new Uint32Array([\n        0, 1, 2,  0, 2, 3,\n        4, 6, 5,  4, 7, 6,\n        0, 4, 5,  0, 5, 1,\n        3, 2, 6,  3, 6, 7,\n        0, 3, 7,  0, 7, 4,\n        1, 5, 6,  1, 6, 2,\n      ])\n\n  const geo = new THREE.BufferGeometry()\n  geo.setAttribute('position', new THREE.BufferAttribute(positions, 3))\n  geo.setIndex(new THREE.BufferAttribute(indices, 1))\n\n  if (params.center) {\n    geo.translate(params.center[0], params.center[1], params.center[2])\n  }\n  return geoToShape(geo)\n}\n\n/**\n * Create text geometry. Font loading is asynchronous, so this function is\n * async; CJK text is rendered with the system font when one is available.\n *\n * @param params - text parameters (text, size, depth).\n * @returns the text shape.\n */\nexport async function text(params: TextParams): Promise<Shape> {\n  const { getOpentypeFont, createTextGeometry } = await import(\n    '../primitives/text-geometry'\n  )\n  const { containsCjk, loadSystemCjkFont, createMixedTextGeometry } = await import(\n    '../primitives/text/cjk'\n  )\n  const font = await getOpentypeFont()\n  let geo: THREE.BufferGeometry\n  if (containsCjk(params.text)) {\n    const cjkFont = await loadSystemCjkFont()\n    if (cjkFont) {\n      geo = await createMixedTextGeometry(params.text, params.size, params.depth, cjkFont.font, font)\n    } else {\n      // No CJK font available: replace CJK chars with '?' so geometry still\n      // can be created (graceful degradation). Without this, createTextGeometry\n      // would throw because CJK glyphs are .notdef in OpenSans Regular.\n      const fallback = params.text.replace(/[\\u4E00-\\u9FFF\\u3400-\\u4DBF\\u2F800-\\u2FA1F\\u3000-\\u303F\\uFF00-\\uFFEF]/g, '?')\n      geo = await createTextGeometry(fallback, params.size, params.depth, font)\n    }\n  } else {\n    geo = await createTextGeometry(params.text, params.size, params.depth, font)\n  }\n  return geoToShape(geo)\n}\n\n/**\n * Create a screw (threaded) geometry.\n *\n * @param params - screw parameters (system, specIdx, thread, length, head, optional pitchCustom and nRad).\n * @returns the screw shape.\n */\nexport async function screw(params: {\n  system: 'metric' | 'imperial'\n  specIdx: number\n  thread: 'coarse' | 'fine' | 'custom' | 'none'\n  pitchCustom?: number\n  length: number\n  head: 'hex' | 'chc' | 'none'\n  nRad?: number\n}): Promise<Shape> {\n  const { makeScrew } = await import('../primitives/screw/screw')\n  const geo = makeScrew({\n    system: params.system,\n    specIdx: params.specIdx,\n    thread: params.thread,\n    pitchCustom: params.pitchCustom ?? 0,\n    length: params.length,\n    head: params.head,\n    nRad: clampNRad(params.nRad),\n  })\n  return geoToShape(geo)\n}\n\n/**\n * Create an extruded geometry from an SVG source.\n *\n * @param params - SVG extrude parameters (svg, depth, target size, optional natural size).\n * @returns the extruded shape.\n */\nexport function svgExtrude(params: SvgExtrudeParams): Shape {\n  const geo = svgToExtrudedGeometry(params.svg, {\n    depth: params.depth,\n    targetLongSide: params.targetLongSide ?? 20,\n    naturalWidth: params.naturalWidth ?? 0,\n    naturalHeight: params.naturalHeight ?? 0,\n  })\n  return geoToShape(geo)\n}\n\n/**\n * Create a mesh from SDF (signed distance field) code, sampling the field with\n * marching cubes.\n *\n * @param params - SDF parameters (code, optional bounds, params, resolution).\n * @returns the sampled shape.\n */\nexport async function sdf(params: SdfParams): Promise<Shape> {\n  const { runSdf } = await import('../sdf/sdf-runner')\n  const box = params.box ?? [[-10, -10, -10], [10, 10, 10]]\n  const bounds: [number, number, number, number, number, number] = [\n    box[0][0], box[0][1], box[0][2],\n    box[1][0], box[1][1], box[1][2],\n  ]\n  const mesh = await runSdf(\n    params.code,\n    params.params ?? {},\n    bounds,\n    params.resolution ?? 1.0,\n  )\n  return { positions: mesh.positions, indices: mesh.indices }\n}\n"]}

package/dist/mesh/query.d.ts

@@ -0,0 +1,43 @@
+/**
+ * mesh 查询 API
+ *
+ * 提取来源：transform-store 的 compute*BoundingBox
+ * 这些函数不产生几何，供 GeomRef 求值与面板显示使用。
+ */
+import type { Shape, Vec3, BoundingBox, FaceDescriptor } from './types.js';
+/**
+ * Compute the axis-aligned bounding box of a shape.
+ *
+ * @param shape - the shape to measure.
+ * @returns the min/max bounding box.
+ */
+export declare function boundingBox(shape: Shape): BoundingBox;
+/**
+ * Compute the center of a shape's bounding box.
+ *
+ * @param shape - the shape to measure.
+ * @returns the bounding-box center as a Vec3.
+ */
+export declare function bboxCenter(shape: Shape): Vec3;
+/**
+ * Compute the enclosed volume of a closed triangle mesh using the divergence
+ * theorem.
+ *
+ * @param shape - the shape to measure.
+ * @returns the volume in mm³.
+ */
+export declare function volume(shape: Shape): number;
+/**
+ * Find the face nearest to an anchor (a pick point plus an optional reference
+ * normal). Used for GeomRef faceNormal evaluation: faces whose
+ * normal is closer to the target normal are weighted more favorably.
+ *
+ * @param shape - the shape to search.
+ * @param anchor - the target point with an optional reference normal.
+ * @returns the closest face descriptor, or null when the mesh has no faces.
+ */
+export declare function faceAt(shape: Shape, anchor: {
+    point: Vec3;
+    normal?: Vec3;
+}): FaceDescriptor | null;
+//# sourceMappingURL=query.d.ts.map

package/dist/mesh/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/mesh/query.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEvE;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,CAerD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAO7C;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAc3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG,cAAc,GAAG,IAAI,CAmDlG"}