@faicad/faijs-gears 0.0.0-stage → 0.29.5

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+/**
+ * index — faijs-gears 公共 API 入口（15 个齿轮类 + contractVersion）
+ *
+ * ## 现状（2026-09-13）
+ *
+ * 本包经 `src/kernel/` 的齿轮原语层消费内核（`getGearKernel()`，自 cq-compat
+ * 迁入；occt 内核访问统一归属该层），入口签名（参数名逐字沿用 Python、
+ * 返回 `Result`）保持不变。
+ *
+ * 每个导出函数：
+ * - 参数名**逐字沿用 Python**（module / teeth_number / width / helix_angle …），见 `profile.ts`；
+ * - 返回 `Promise<Result<…>>`：单体齿轮返回 `BrepHandle`；齿轮对/轮系返回具名记录
+ *   （`{gear, pinion}` / `{gear1, gear2}` / `{sun, planets, ring}`）并挂 `fn.outputs`
+ *   （`library-dev-guide.md` §2.6 / 方案 §6.4），宿主据此逐件收编、导出 STEP。
+ * - `GearAssembly`（`{name, solid}[]`）保留为脚本侧逐件导出的形态（`*ExportParts`）。
+ */
+import type { BrepHandle } from '@faicad/faijs';
+import { type Result } from '@faicad/faijs';
+import { type BuildSpurGearOptions } from './spur_gear.js';
+import { type BuildRingGearOptions } from './ring_gear.js';
+import { type BuildRackGearOptions } from './rack_gear.js';
+import { type BuildWormOptions } from './worm_gear.js';
+import { type BuildBevelGearOptions } from './bevel_gear.js';
+import { type BevelGearPairParams, type BuildBevelGearPairOptions } from './pairs.js';
+import { type CrossedGearPairParams, type HyperbolicGearPairParams, type BuildCrossedGearPairOptions } from './crossed_pair.js';
+import { type PlanetaryGearsetParams, type BuildPlanetaryGearsetOptions } from './planetary.js';
+import type { SpurGearParams, RingGearParams, CrossedHelicalGearParams, RackGearParams, WormParams, BevelGearParams, HyperbolicGearParams } from './profile.js';
+/** 库契约版本（与 faijs 引擎对齐，勿硬编码）。 */
+export declare const contractVersion = 3;
+/** 齿轮对/轮系的逐件导出条目（名字进 STEP 产品名，供逐件等价比对）。 */
+export type GearAssembly = Array<{
+    name: string;
+    solid: BrepHandle;
+}>;
+/**
+ * SpurGear（直齿圆柱齿轮）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `SpurGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function spurGear(params: SpurGearParams, options?: BuildSpurGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * HerringboneGear（人字齿圆柱齿轮）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HerringboneGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function herringboneGear(params: SpurGearParams, options?: BuildSpurGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * RingGear（内齿圈）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `RingGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function ringGear(params: RingGearParams, options?: BuildRingGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * HerringboneRingGear（人字内齿圈）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HerringboneRingGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function herringboneRingGear(params: RingGearParams, options?: BuildRingGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * CrossedHelicalGear（交错轴斜齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `CrossedHelicalGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function crossedHelicalGear(params: CrossedHelicalGearParams, options?: BuildSpurGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * HyperbolicGear（双曲面齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HyperbolicGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function hyperbolicGear(params: HyperbolicGearParams, options?: BuildSpurGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * BevelGear（锥齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `BevelGear.__init__`）
+ * @param options 构建选项（齿面策略 / bore_d / trim）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function bevelGear(params: BevelGearParams, options?: BuildBevelGearOptions): Promise<Result<BrepHandle, string>>;
+/** BevelGearPair 逐件输出（`fn.outputs` 指定的具名记录，方案 §6.4）。 */
+export interface BevelGearPairOutput {
+    /** 大轮 solid（未加定位）。 */
+    gear?: BrepHandle;
+    /** 小轮 solid（**已加**定位，除非 `transformPinion: false`）。 */
+    pinion?: BrepHandle;
+}
+/**
+ * BevelGearPair（锥齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `BevelGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / bore_d / trim）
+ * @returns `Result<BevelGearPairOutput>`——具名记录，失败转 `err`
+ */
+export declare function bevelGearPair(params: BevelGearPairParams, options?: BuildBevelGearPairOptions): Promise<Result<BevelGearPairOutput, string>>;
+/**
+ * RackGear（齿条）。
+ *
+ * @param params 齿条参数（逐字沿用 Python `RackGear.__init__`）
+ * @param options 构建选项（齿面策略）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function rackGear(params: RackGearParams, options?: BuildRackGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * HerringboneRackGear（人字齿条）。
+ *
+ * @param params 齿条参数（逐字沿用 Python `HerringboneRackGear.__init__`）
+ * @param options 构建选项（齿面策略；内部强制 `herringbone: true`）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function herringboneRackGear(params: RackGearParams, options?: BuildRackGearOptions): Promise<Result<BrepHandle, string>>;
+/**
+ * Worm（蜗杆）。
+ *
+ * @param params 蜗杆参数（逐字沿用 Python `Worm.__init__`）
+ * @param options 构建选项（策略默认 grid-approx / 缝合与组线容差 / boreD）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export declare function worm(params: WormParams, options?: BuildWormOptions): Promise<Result<BrepHandle, string>>;
+/** CrossedGearPair / HyperbolicGearPair 逐件输出（`fn.outputs` 指定的具名记录，方案 §6.4）。 */
+export interface CrossedGearPairOutput {
+    /** 第一齿轮 solid（未定位）。 */
+    gear1?: BrepHandle;
+    /** 第二齿轮 solid（已按轴交角定位）。 */
+    gear2?: BrepHandle;
+}
+/**
+ * CrossedGearPair（交错轴斜齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `CrossedGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<CrossedGearPairOutput>`——具名记录，失败转 `err`
+ */
+export declare function crossedGearPair(params: CrossedGearPairParams, options?: BuildCrossedGearPairOptions): Promise<Result<CrossedGearPairOutput, string>>;
+/**
+ * HyperbolicGearPair（双曲面齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `HyperbolicGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<CrossedGearPairOutput>`——具名记录，失败转 `err`
+ */
+export declare function hyperbolicGearPair(params: HyperbolicGearPairParams, options?: BuildCrossedGearPairOptions): Promise<Result<CrossedGearPairOutput, string>>;
+/** PlanetaryGearset 逐件输出（`fn.outputs` 指定的具名记录，方案 §6.4）。 */
+export interface PlanetaryGearsetOutput {
+    /** 太阳轮 solid。 */
+    sun?: BrepHandle;
+    /** 行星轮 solid 列表（planet_01…planet_NN）。 */
+    planets: BrepHandle[];
+    /** 内齿圈 solid。 */
+    ring?: BrepHandle;
+}
+/**
+ * PlanetaryGearset（行星轮系，装配体）。
+ *
+ * @param params 轮系参数（逐字沿用 Python `PlanetaryGearset.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<PlanetaryGearsetOutput>`——具名记录，失败转 `err`
+ */
+export declare function planetaryGearset(params: PlanetaryGearsetParams, options?: BuildPlanetaryGearsetOptions): Promise<Result<PlanetaryGearsetOutput, string>>;
+/**
+ * HerringbonePlanetaryGearset（人字行星轮系，装配体）。
+ *
+ * @param params 轮系参数（逐字沿用 Python `HerringbonePlanetaryGearset.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<PlanetaryGearsetOutput>`——具名记录，失败转 `err`
+ */
+export declare function herringbonePlanetaryGearset(params: PlanetaryGearsetParams, options?: BuildPlanetaryGearsetOptions): Promise<Result<PlanetaryGearsetOutput, string>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,223 @@
+/**
+ * index — faijs-gears 公共 API 入口（15 个齿轮类 + contractVersion）
+ *
+ * ## 现状（2026-09-13）
+ *
+ * 本包经 `src/kernel/` 的齿轮原语层消费内核（`getGearKernel()`，自 cq-compat
+ * 迁入；occt 内核访问统一归属该层），入口签名（参数名逐字沿用 Python、
+ * 返回 `Result`）保持不变。
+ *
+ * 每个导出函数：
+ * - 参数名**逐字沿用 Python**（module / teeth_number / width / helix_angle …），见 `profile.ts`；
+ * - 返回 `Promise<Result<…>>`：单体齿轮返回 `BrepHandle`；齿轮对/轮系返回具名记录
+ *   （`{gear, pinion}` / `{gear1, gear2}` / `{sun, planets, ring}`）并挂 `fn.outputs`
+ *   （`library-dev-guide.md` §2.6 / 方案 §6.4），宿主据此逐件收编、导出 STEP。
+ * - `GearAssembly`（`{name, solid}[]`）保留为脚本侧逐件导出的形态（`*ExportParts`）。
+ */
+import { ok, err, CONTRACT_VERSION } from '@faicad/faijs';
+import { getGearKernel } from './kernel/index.js';
+import { buildSpurGearSolid, buildHerringboneGearSolid, buildHyperbolicGearSolid, } from './spur_gear.js';
+import { buildRingGearSolid, buildHerringboneRingGearSolid, } from './ring_gear.js';
+import { buildCrossedHelicalSolid } from './crossed_helical_gear.js';
+import { buildRackGearSolid } from './rack_gear.js';
+import { buildWormSolid } from './worm_gear.js';
+import { buildBevelGearSolid } from './bevel_gear.js';
+import { buildBevelGearPair, } from './pairs.js';
+import { buildCrossedGearPair, buildHyperbolicGearPair, } from './crossed_pair.js';
+import { buildPlanetaryGearset, buildHerringbonePlanetaryGearset, } from './planetary.js';
+/** 库契约版本（与 faijs 引擎对齐，勿硬编码）。 */
+export const contractVersion = CONTRACT_VERSION;
+/**
+ * 统一内核执行包装：取单例内核、运行构建、失败转 `err`。
+ *
+ * @param fn 接收原始内核、返回 solid 或装配
+ * @returns `Result<T>`
+ */
+async function run(fn) {
+    try {
+        const kernel = await getGearKernel();
+        return ok(fn(kernel));
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}
+// ── A 族：直纹/扭纹齿面（网格样条曲面）──────────────────────────────────────────
+/**
+ * SpurGear（直齿圆柱齿轮）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `SpurGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function spurGear(params, options = {}) {
+    return run((k) => buildSpurGearSolid(k, params, options));
+}
+/**
+ * HerringboneGear（人字齿圆柱齿轮）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HerringboneGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function herringboneGear(params, options = {}) {
+    return run((k) => buildHerringboneGearSolid(k, params, options));
+}
+/**
+ * RingGear（内齿圈）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `RingGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function ringGear(params, options = {}) {
+    return run((k) => buildRingGearSolid(k, params, options));
+}
+/**
+ * HerringboneRingGear（人字内齿圈）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HerringboneRingGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function herringboneRingGear(params, options = {}) {
+    return run((k) => buildHerringboneRingGearSolid(k, params, options));
+}
+/**
+ * CrossedHelicalGear（交错轴斜齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `CrossedHelicalGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function crossedHelicalGear(params, options = {}) {
+    return run((k) => buildCrossedHelicalSolid(k, params, options));
+}
+/**
+ * HyperbolicGear（双曲面齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HyperbolicGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function hyperbolicGear(params, options = {}) {
+    return run((k) => buildHyperbolicGearSolid(k, params, options));
+}
+// ── B 族：球面渐开线（BevelGear）───────────────────────────────────────────────
+/**
+ * BevelGear（锥齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `BevelGear.__init__`）
+ * @param options 构建选项（齿面策略 / bore_d / trim）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function bevelGear(params, options = {}) {
+    return run((k) => buildBevelGearSolid(k, params, options));
+}
+/**
+ * BevelGearPair（锥齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `BevelGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / bore_d / trim）
+ * @returns `Result<BevelGearPairOutput>`——具名记录，失败转 `err`
+ */
+export function bevelGearPair(params, options = {}) {
+    return run((k) => {
+        const b = buildBevelGearPair(k, params, options);
+        return { gear: b.gear, pinion: b.pinion };
+    });
+}
+;
+bevelGearPair.outputs = ['gear', 'pinion'];
+// ── C 族：齿条 / 蜗杆 ───────────────────────────────────────────────────────────
+/**
+ * RackGear（齿条）。
+ *
+ * @param params 齿条参数（逐字沿用 Python `RackGear.__init__`）
+ * @param options 构建选项（齿面策略）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function rackGear(params, options = {}) {
+    return run((k) => buildRackGearSolid(k, params, options));
+}
+/**
+ * HerringboneRackGear（人字齿条）。
+ *
+ * @param params 齿条参数（逐字沿用 Python `HerringboneRackGear.__init__`）
+ * @param options 构建选项（齿面策略；内部强制 `herringbone: true`）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function herringboneRackGear(params, options = {}) {
+    return run((k) => buildRackGearSolid(k, params, { ...options, herringbone: true }));
+}
+/**
+ * Worm（蜗杆）。
+ *
+ * @param params 蜗杆参数（逐字沿用 Python `Worm.__init__`）
+ * @param options 构建选项（策略默认 grid-approx / 缝合与组线容差 / boreD）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function worm(params, options = {}) {
+    return run((k) => buildWormSolid(k, params, options));
+}
+/**
+ * CrossedGearPair（交错轴斜齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `CrossedGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<CrossedGearPairOutput>`——具名记录，失败转 `err`
+ */
+export function crossedGearPair(params, options = {}) {
+    return run((k) => {
+        const b = buildCrossedGearPair(k, params, options);
+        return { gear1: b.gear1, gear2: b.gear2 };
+    });
+}
+;
+crossedGearPair.outputs = ['gear1', 'gear2'];
+/**
+ * HyperbolicGearPair（双曲面齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `HyperbolicGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<CrossedGearPairOutput>`——具名记录，失败转 `err`
+ */
+export function hyperbolicGearPair(params, options = {}) {
+    return run((k) => {
+        const b = buildHyperbolicGearPair(k, params, options);
+        return { gear1: b.gear1, gear2: b.gear2 };
+    });
+}
+;
+hyperbolicGearPair.outputs = ['gear1', 'gear2'];
+/**
+ * PlanetaryGearset（行星轮系，装配体）。
+ *
+ * @param params 轮系参数（逐字沿用 Python `PlanetaryGearset.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<PlanetaryGearsetOutput>`——具名记录，失败转 `err`
+ */
+export function planetaryGearset(params, options = {}) {
+    return run((k) => {
+        const b = buildPlanetaryGearset(k, params, options);
+        return { sun: b.sun, planets: b.planets, ring: b.ring };
+    });
+}
+;
+planetaryGearset.outputs = ['sun', 'planets', 'ring'];
+/**
+ * HerringbonePlanetaryGearset（人字行星轮系，装配体）。
+ *
+ * @param params 轮系参数（逐字沿用 Python `HerringbonePlanetaryGearset.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<PlanetaryGearsetOutput>`——具名记录，失败转 `err`
+ */
+export function herringbonePlanetaryGearset(params, options = {}) {
+    return run((k) => {
+        const b = buildHerringbonePlanetaryGearset(k, params, options);
+        return { sun: b.sun, planets: b.planets, ring: b.ring };
+    });
+}
+;
+herringbonePlanetaryGearset.outputs = ['sun', 'planets', 'ring'];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/kernel/gears.d.ts

@@ -0,0 +1,231 @@
+/**
+ * gears — raw-handle primitives for the cq_gears port (E1–E6 companion layer).
+ *
+ * cq_gears' tooth faces are B-spline patches built from (u,v) point grids and
+ * assembled by sewing — these need raw kernel construction primitives that no
+ * Workplane op exposes (bsplineSurface / approximatePoints / interpolatePoints,
+ * tolerant edge chaining, sew+makeSolid). The faijs-gears v1 port probed them
+ * in its own `kernel.ts` / `geom-build.ts` / `spline-face.ts`; per the port
+ * plan (§4) the implementations must live INSIDE cq-compat — this file is that
+ * landing spot. faijs-gears only imports from here; it must not touch
+ * occt-wasm directly.
+ *
+ * Everything here is a verbatim port of the proven v1 implementations (same
+ * kernel call sequence → bit-identical geometry).
+ */
+import type { BrepEngineApi, BrepHandle, BrepVec3 } from '@faicad/faijs';
+import type { Vec3 } from '../math.js';
+/** Rotation/mirror axis (occt-wasm shape). */
+export interface GearAxis {
+    point: BrepVec3;
+    direction: BrepVec3;
+}
+/**
+ * Raw occt-wasm capability surface — superset of `BrepEngineApi`.
+ *
+ * Declares exactly the methods the cq_gears port consumes; the probe test in
+ * faijs-gears asserts each one exists on the live kernel, so a kernel upgrade
+ * that renames a binding turns red immediately instead of failing at runtime
+ * with `undefined is not a function`.
+ */
+export type GearKernel = Omit<BrepEngineApi, 'interpolatePoints'> & {
+    /** `GeomAPI_PointsToBSplineSurface`: point grid → B-spline surface → Face. */
+    bsplineSurface(points: BrepVec3[], rows: number, cols: number): BrepHandle;
+    /** `GeomAPI_PointsToBSpline`: point list → approximated B-spline curve (with Tol3D). */
+    approximatePoints(points: BrepVec3[], tolerance?: number): BrepHandle;
+    /** Cubic B-spline interpolation curve through all points (occt periodic 语义).
+     *  ⚠️ 收窄后（2026-09-24）：type 交叉继承全部 L1 方法，仅 Omit 掉
+     *  `interpolatePoints`（L1 是 brepkit degree 语义）并覆盖为本包 occt 原生
+     *  periodic 语义。运行时 kernel 是 raw occt-wasm 平台面，调用不变。 */
+    interpolatePoints(points: BrepVec3[], periodic?: boolean): BrepHandle;
+    /** `BRepBuilderAPI_Sewing`: faces → sewn shell (cq `make_shell` analogue). */
+    sew(shapes: BrepHandle[], tolerance?: number): BrepHandle;
+    makeSolid(shell: BrepHandle): BrepHandle;
+    /** TopAbs_ShapeEnum type name ("solid" / "shell" / "face" …, for diagnostics/assertions). */
+    getShapeType(shape: BrepHandle): string;
+    buildSolidFromFaces(faces: BrepHandle[], tolerance?: number): BrepHandle;
+    makeNonPlanarFace(wire: BrepHandle): BrepHandle;
+    makeFaceOnSurface(face: BrepHandle, wire: BrepHandle): BrepHandle;
+    outerWire(face: BrepHandle): BrepHandle;
+    healWire(wire: BrepHandle, tolerance?: number): BrepHandle;
+    healFace(face: BrepHandle, tolerance?: number): BrepHandle;
+    rotate(shape: BrepHandle, axis: GearAxis, angleRad: number): BrepHandle;
+    /** `BRepPrimAPI_MakeRevol`: face/wire revolved around `axis` (cq `Workplane.revolve`, 360°=2π). */
+    revolve(shape: BrepHandle, axis: GearAxis, angleRad: number): BrepHandle;
+    mirror(shape: BrepHandle, point: BrepVec3, normal: BrepVec3): BrepHandle;
+    reverseShape(shape: BrepHandle): BrepHandle;
+    vertexPosition(vertex: BrepHandle): BrepVec3;
+    split(shape: BrepHandle, tools: BrepHandle[]): BrepHandle;
+    fillet(solid: BrepHandle, edges: BrepHandle[], radius: number): BrepHandle;
+    shell(solid: BrepHandle, facesToRemove: BrepHandle[], thickness: number, tolerance: number): BrepHandle;
+    thicken(shape: BrepHandle, thickness: number, tolerance: number): BrepHandle;
+    makeCircleArc(center: BrepVec3, normal: BrepVec3, radius: number, startAngle: number, endAngle: number): BrepHandle;
+    makeHelixWire(origin: BrepVec3, axis: BrepVec3, pitch: number, height: number, radius: number): BrepHandle;
+    getSurfaceArea(shape: BrepHandle): number;
+    projectPointOnFace(face: BrepHandle, point: BrepVec3): BrepVec3;
+    surfaceType(face: BrepHandle): string;
+    subShapeCount(shape: BrepHandle, type: 'vertex' | 'edge' | 'wire' | 'face' | 'shell' | 'solid'): number;
+    isFace(shape: BrepHandle): boolean;
+    isWire(shape: BrepHandle): boolean;
+    isShell(shape: BrepHandle): boolean;
+    isEdge(shape: BrepHandle): boolean;
+    /** `BRepOffsetAPI_ThruSections`: wires → shell（occt 平台方法，收窄后不在 L1）。 */
+    loft(wires: BrepHandle[], isSolid?: boolean, ruled?: boolean): BrepHandle;
+};
+/**
+ * Get the raw occt-wasm kernel (process-wide singleton).
+ *
+ * Same instance as `initOcctWasm()` — this only asserts the richer
+ * `GearKernel` type, never constructs a second kernel (handles are indices
+ * into one kernel arena and must not cross instances).
+ *
+ * @returns the raw kernel (promise; initializes wasm on first call)
+ */
+export declare function getGearKernel(): Promise<GearKernel>;
+/** The two endpoints of an edge (order = the edge's parameter direction). */
+export interface GearEdgeEnds {
+    edge: BrepHandle;
+    a: Vec3;
+    b: Vec3;
+}
+/**
+ * Endpoints of an edge, via the curve parameter domain.
+ *
+ * ⚠️ Endpoint red line (probed 2026-09-11): `getSubShapes(edge, 'vertex')`
+ * returns fewer than 2 vertices for **B-spline curve edges** (OCCT stores no
+ * explicit vertices on them), which used to make edge chaining treat every
+ * edge as its own wire. The correct path is `curveParameters(edge)` →
+ * `curvePointAtParam(edge, param)` — valid for ALL edge kinds (line / arc /
+ * B-spline); the vertex fallback only covers degenerate edges without an
+ * underlying curve.
+ *
+ * @param kernel raw OCCT kernel
+ * @param edge edge handle
+ * @returns both endpoints (closed edges: first == last)
+ */
+export declare function gearEdgeEnds(kernel: GearKernel, edge: BrepHandle): GearEdgeEnds;
+/**
+ * TS port of OCCT `ShapeAnalysis_FreeBounds::ConnectEdgesToWires` — chain
+ * unordered edges into wires by endpoint proximity within `tol`.
+ *
+ * faijs/occt-wasm has no such binding and `makeWire(edges)` is
+ * `BRepBuilderAPI_MakeWire` — measured (2026-09-08) to silently drop edges on
+ * unordered input (68 edges → 9-edge broken wire). Endpoint pairing is O(n²)
+ * (n = 4·z teeth, at most a few hundred — fine).
+ *
+ * Gaps above OCCT precision (~1e-7) get a bridging line segment, matching
+ * upstream ConnectEdgesToWires behaviour.
+ *
+ * @param kernel raw OCCT kernel
+ * @param edges unordered edge set
+ * @param tol endpoint pairing tolerance (mm); cq uses `wire_comb_tol = 1e-2`
+ * @returns one or more wires, each with its edges chained head-to-tail
+ */
+export declare function connectEdgesToWires(kernel: GearKernel, edges: BrepHandle[], tol: number): BrepHandle[];
+/**
+ * cq `Face.makeFromWires(outer, holes)` analogue.
+ *
+ * @param kernel raw OCCT kernel
+ * @param outer outer wire
+ * @param holes inner hole wires (may be empty)
+ * @returns face handle
+ */
+export declare function gearFaceFromWires(kernel: GearKernel, outer: BrepHandle, holes?: BrepHandle[]): BrepHandle;
+/**
+ * cq `make_shell(faces, tol)` + `Solid.makeSolid(shell)` analogue.
+ *
+ * A non-shell sew result is NOT silently swallowed — that is a construction
+ * failure signal.
+ *
+ * @param kernel raw OCCT kernel
+ * @param faces faces to sew
+ * @param sewingTol sewing tolerance (mm, cq `shell_sewing_tol`)
+ * @returns solid built from the sewn shell
+ */
+export declare function gearShellToSolid(kernel: GearKernel, faces: BrepHandle[], sewingTol: number): BrepHandle;
+/**
+ * Tooth-face B-spline face strategies (mirrors cq `Face.makeSplineApprox`).
+ *
+ * | strategy | how | semantic delta vs cq |
+ * |---|---|---|
+ * | `grid-approx` | `kernel.bsplineSurface(flat, rows, cols)` (also `GeomAPI_PointsToBSplineSurface`) | OCCT default DegMin/DegMax/Tol3D; cq passes 3/8/1e-2 explicitly |
+ * | `row-approx-loft` | per-row `approximatePoints(row, tol)` → `loft(wires, false, false)` | curve-level tol same name/meaning; surface is skinned, not fitted at once |
+ * | `row-interp-loft` | per-row `interpolatePoints(row)` → `loft` | passes through every sample point (interpolation) |
+ */
+export type GearSplineFaceStrategy = 'grid-approx' | 'row-approx-loft' | 'row-interp-loft';
+/** All selectable strategies (tests iterate in this order for the deviation table). */
+export declare const GEAR_SPLINE_FACE_STRATEGIES: readonly GearSplineFaceStrategy[];
+/**
+ * Default strategy chosen by P0 measurement (2026-09-08).
+ *
+ * Per the measured table in the faijs-gears spike: S2's area relative
+ * deviation is 5.6e-7 / max sample-point distance 2.6e-6 mm — about three
+ * orders of magnitude better than S1/S3. See
+ * `docs/analysis/2026-09-08-fai-cq-gears-spike.md`.
+ */
+export declare const DEFAULT_GEAR_SPLINE_FACE_STRATEGY: GearSplineFaceStrategy;
+/** Face building options (tolerance + degrees, aligned with cq `makeSplineApprox`). */
+export interface GearSplineFaceOptions {
+    /** Approximation tolerance (mm). cq's `spline_approx_tol`, default 1e-2. */
+    tolerance?: number;
+    /** Surface minimum degree (cq: 3) — only meaningful for grid-approx/row-approx-loft. */
+    minDeg?: number;
+    /** Surface maximum degree (cq: 8). */
+    maxDeg?: number;
+}
+/** A row×col point grid with its dimensions (structural — no gear types here). */
+export interface GearSplineGrid {
+    /** `rows` point rows of `cols` points each. */
+    points: Vec3[][];
+    rows: number;
+    cols: number;
+}
+/**
+ * Build a face from a row×col point grid with the given strategy.
+ *
+ * @throws kernel errors propagate verbatim (never swallowed — red line)
+ *
+ * @param kernel raw OCCT kernel
+ * @param grid row×col point grid
+ * @param strategy face building strategy
+ * @param options tolerance/degree options
+ * @returns single face handle (Face)
+ */
+export declare function buildGearSplineFace(kernel: GearKernel, grid: GearSplineGrid, strategy: GearSplineFaceStrategy, options?: GearSplineFaceOptions): BrepHandle;
+/**
+ * Reduce a "single-face shell" to a Face; a Face passes through unchanged.
+ *
+ * @throws when the face count is not 1 (silently taking the first would mask problems)
+ *
+ * @param kernel raw OCCT kernel
+ * @param shape any shape (Face / single-face shell / …)
+ * @returns the sole Face
+ */
+export declare function soleGearFace(kernel: GearKernel, shape: BrepHandle): BrepHandle;
+/** Distance from a point to a face (`projectPointOnFace`).
+ *
+ * @param kernel raw OCCT kernel
+ * @param face target face
+ * @param p query point
+ * @returns euclidean distance (mm)
+ */
+export declare function gearDistanceToFace(kernel: GearKernel, face: BrepHandle, p: Vec3): number;
+/** Distance statistics (max / RMS / sample count). */
+export interface GearDeviationStats {
+    max: number;
+    rms: number;
+    n: number;
+}
+/**
+ * Distance statistics of reference sample points against a face.
+ *
+ * Parameterization-independent: samples come from the cq side's (u,v) grid, so
+ * the two surfaces may have different parameterizations.
+ *
+ * @param kernel raw OCCT kernel
+ * @param face face under test
+ * @param samplePoints reference sample points (3D)
+ * @returns max distance / RMS / sample count
+ */
+export declare function gearFaceDeviation(kernel: GearKernel, face: BrepHandle, samplePoints: Vec3[]): GearDeviationStats;
+//# sourceMappingURL=gears.d.ts.map

package/dist/kernel/gears.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gears.d.ts","sourceRoot":"","sources":["../../src/kernel/gears.ts"],"names":[],"mappings":"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"}