@faicad/faijs 0.22.2 → 0.29.5

package/dist/api/cadquery-selectors/resolve.d.ts

@@ -0,0 +1,41 @@
+import type { EntityKind, SelStep } from './types.js';
+import type { EntityGeom, ShapeHandle } from './entity.js';
+/** A set of candidate entities with their owning shape (for normal orientation). */
+export interface Selection {
+    owner: ShapeHandle | null;
+    items: EntityGeom[];
+}
+/** A fully-resolved narrowing chain: the surviving kind and kernel handles. */
+export interface ChainResult {
+    kind: EntityKind;
+    handles: ShapeHandle[];
+}
+/**
+ * Multi-step `{kind, sel}` narrowing (plan §4.5). Each step collects the `kind`
+ * sub-entities of every currently-held object, dedups by kernel identity, then
+ * filters by the parsed selector. An empty `sel` collects without filtering
+ * (CadQuery `.vertices()` / `.edges()`, whose `_filter` is a no-op).
+ *
+ *   resolveSelection(shape, [{face,'+Z'},{vertex,'<XY'}])
+ *     → the +Z face's vertices with the smallest x+y, in the order they appear.
+ *
+ * @param owner - The owning shape handle to start from (or `null` for empty).
+ * @param chain - The ordered per-kind narrowing steps to apply.
+ * @returns The final kind and the surviving kernel handles at that kind.
+ */
+export declare function resolveSelection(owner: ShapeHandle | null, chain: SelStep[]): ChainResult;
+/**
+ * Narrow a single step and return the surviving kernel handles. Backs the
+ * `resolveEdgeSelection` / `resolveVertexSelector` / `resolveFaceEdgeSelection`
+ * projections.
+ *
+ * @param owner - The owning shape handle to start from (or `null` for empty).
+ * @param kind - The topological kind of the step.
+ * @param sel - The CadQuery selector string for the step (may be empty).
+ * @returns The surviving kernel handles after the single-step narrowing.
+ */
+export declare function resolveStepHandles(owner: ShapeHandle | null, kind: EntityKind, sel: string): ShapeHandle[];
+/** ValueError-equivalent for an empty input to a N-th selector. */
+export declare class EmptyNthError extends Error {
+}
+//# sourceMappingURL=resolve.d.ts.map

package/dist/api/cadquery-selectors/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/resolve.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAY,UAAU,EAAgB,OAAO,EAAQ,MAAM,SAAS,CAAA;AAChF,OAAO,KAAK,EAAE,UAAU,EAAM,WAAW,EAAE,MAAM,UAAU,CAAA;AAa3D,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IACzB,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAA;IAChB,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,WAAW,CAoBzF;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,GACV,WAAW,EAAE,CAEf;AAoDD,mEAAmE;AACnE,qBAAa,aAAc,SAAQ,KAAK;CAAG"}

package/dist/api/cadquery-selectors/resolve.js

@@ -0,0 +1,243 @@
+/**
+ * cadquery-selectors/resolve — evaluate a parsed `SelectorExpr` against a set
+ * of candidate entities (plan §4.5). Clean-room re-encoding of
+ * `cadquery/selectors.py`:
+ *
+ *   · `_SimpleStringSyntaxSelector._chooseSelector` — atom → selector object
+ *   · `_NthSelector.cluster`/`filter` — center-projection sort + cluster
+ *   · `BaseDirSelector.filter` — linear edges / planar faces only, else drop
+ *   · `BinarySelector` set algebra (`AndSelector`/`SumSelector`/
+ *     `SubtractSelector`/`InverseSelector`) from the expression grammar.
+ *
+ * Every child of a set operation is applied to the SAME full input list and its
+ * results combined (upstream `BinarySelector.filter`), so operands do not chain
+ * into each other.
+ *
+ * Validated against the LOCKED cadquery 2.8.0 probe (C:\cqenv\sel_probe.py)
+ * — cube_off ground truth recorded in plan §5.2.
+ *
+ * @platform occt — narrowing evaluates kernel `ShapeHandle`s through the
+ * native occt-kernel (`getKernel()`: isSame identity dedup etc.), so this
+ * module is occt-coupled by nature.
+ */
+import { getKernel } from '../../occt-kernel/occtKernel.js';
+import { faceGeom, edgeGeom, vertexGeom, subShapeHandles } from './entity.js';
+import { parseSelector } from './grammar.js';
+import { NTH_TOLERANCE, isAligned, isDirectionCandidate, isParallel, isPerpendicular, typeMatches, entityDirection, } from './predicates.js';
+/** Project a kernel handle of the given kind into its `EntityGeom`. */
+function project(handle, kind) {
+    if (kind === 'face')
+        return faceGeom(handle);
+    if (kind === 'edge')
+        return edgeGeom(handle);
+    return vertexGeom(handle);
+}
+/**
+ * Multi-step `{kind, sel}` narrowing (plan §4.5). Each step collects the `kind`
+ * sub-entities of every currently-held object, dedups by kernel identity, then
+ * filters by the parsed selector. An empty `sel` collects without filtering
+ * (CadQuery `.vertices()` / `.edges()`, whose `_filter` is a no-op).
+ *
+ *   resolveSelection(shape, [{face,'+Z'},{vertex,'<XY'}])
+ *     → the +Z face's vertices with the smallest x+y, in the order they appear.
+ *
+ * @param owner - The owning shape handle to start from (or `null` for empty).
+ * @param chain - The ordered per-kind narrowing steps to apply.
+ * @returns The final kind and the surviving kernel handles at that kind.
+ */
+export function resolveSelection(owner, chain) {
+    if (chain.length === 0) {
+        return { kind: 'face', handles: owner ? subShapeHandles(owner, 'face') : [] };
+    }
+    let candidates = owner ? [owner] : [];
+    let kind = chain[0].kind;
+    for (const step of chain) {
+        // ① collect: sub-entities of each candidate, union/ordered, dedup by identity.
+        const gathered = dedupByIsSame(candidates.flatMap((o) => subShapeHandles(o, step.kind)));
+        // ② filter: resolve the selector over the gathered views.
+        const items = gathered.map((h) => project(h, step.kind));
+        candidates =
+            step.sel.trim() === ''
+                ? gathered
+                : evalExpr({ owner, items }, parseSelector(step.sel)).map((g) => g._handle);
+        kind = step.kind;
+    }
+    return { kind, handles: candidates };
+}
+/** Deduplicate kernel handles by KERNEL identity (isSame), preserving order. */
+function dedupByIsSame(handles) {
+    const out = [];
+    for (const h of handles) {
+        if (!out.some((o) => kernOf().isSame(o, h)))
+            out.push(h);
+    }
+    return out;
+}
+function kernOf() {
+    return getKernel();
+}
+// ─── single-kind conveniences (plan §4.6) ────────────────────────────────
+/**
+ * Narrow a single step and return the surviving kernel handles. Backs the
+ * `resolveEdgeSelection` / `resolveVertexSelector` / `resolveFaceEdgeSelection`
+ * projections.
+ *
+ * @param owner - The owning shape handle to start from (or `null` for empty).
+ * @param kind - The topological kind of the step.
+ * @param sel - The CadQuery selector string for the step (may be empty).
+ * @returns The surviving kernel handles after the single-step narrowing.
+ */
+export function resolveStepHandles(owner, kind, sel) {
+    return resolveSelection(owner, [{ kind, sel }]).handles;
+}
+/** Center dot direction — the ordering key for the N-th selectors. */
+function projKey(g, axis) {
+    const c = g.center();
+    return c.x * axis.x + c.y * axis.y + c.z * axis.z;
+}
+/**
+ * `_NthSelector.cluster` + `filter`: sort by key, cluster consecutive items
+ * within `NTH_TOLERANCE`, then return the cluster at index `n` of the list
+ * reversed when `max` is false. An empty input raises (upstream
+ * `_NthSelector.filter` ValueError); an out-of-range `n` raises IndexError.
+ */
+function nthCluster(items, axis, max, n) {
+    if (items.length === 0) {
+        throw new EmptyNthError('Can not return the Nth element of an empty list');
+    }
+    const keyed = items
+        .map((g) => ({ g, key: projKey(g, axis) }))
+        .sort((a, b) => a.key - b.key);
+    const clusters = [];
+    let cur = [keyed[0].g];
+    let start = keyed[0].key;
+    for (let i = 1; i < keyed.length; i++) {
+        const { g, key } = keyed[i];
+        if (Math.abs(key - start) <= NTH_TOLERANCE) {
+            cur.push(g);
+        }
+        else {
+            clusters.push(cur);
+            cur = [g];
+            start = key;
+        }
+    }
+    clusters.push(cur);
+    // `_NthSelector.filter`: descending requires reversing the cluster list first.
+    if (!max)
+        clusters.reverse();
+    // Python-style negative index (e.g. `>Z[-2]` ⇔ `clusters[-2]`).
+    const idx = n < 0 ? clusters.length + n : n;
+    const out = clusters[idx];
+    if (out === undefined) {
+        throw new RangeError(`Attempted to access index ${n} of a list with length ${clusters.length}`);
+    }
+    return out;
+}
+/** ValueError-equivalent for an empty input to a N-th selector. */
+export class EmptyNthError extends Error {
+}
+// ── set operations (BinarySelector) ────────────────────────────────────────
+/** `AndSelector`: intersection by kernel identity. */
+function intersect(a, b) {
+    const bs = new Set(b.map((g) => g.hash()));
+    return a.filter((g) => bs.has(g.hash()));
+}
+/** `SumSelector`: union (no duplicates) by kernel identity. */
+function union(a, b) {
+    const seen = new Set();
+    const out = [];
+    for (const g of a.concat(b)) {
+        const h = g.hash();
+        if (!seen.has(h)) {
+            seen.add(h);
+            out.push(g);
+        }
+    }
+    return out;
+}
+/** `SubtractSelector`: set difference by kernel identity. */
+function subtract(a, b) {
+    const bs = new Set(b.map((g) => g.hash()));
+    return a.filter((g) => !bs.has(g.hash()));
+}
+// ── atom application ──────────────────────────────────────────────────────
+/** BaseDirSelector filter: the direction test over allowed entity kinds. */
+function filterByTest(items, owner, test) {
+    const out = [];
+    for (const g of items) {
+        if (!isDirectionCandidate(g))
+            continue;
+        const d = entityDirection(g, owner ?? undefined);
+        if (d !== null && test(d))
+            out.push(g);
+    }
+    return out;
+}
+/** Apply one atom to the full candidate list, mirroring each selector.filter. */
+function applyAtom(items, owner, desc) {
+    switch (desc.kind) {
+        case 'dir':
+            // `DirectionSelector` (bare `X` or `(x,y,z)`): angle≈0, signed — same as
+            // the `+` operator (upstream `only_dir` maps to DirectionSelector).
+            return filterByTest(items, owner, (d) => isAligned(d, desc.vec, 1));
+        case 'signed':
+            return filterByTest(items, owner, (d) => isAligned(d, desc.vec, desc.sign));
+        case 'parallel':
+            return filterByTest(items, owner, (d) => isParallel(d, desc.vec));
+        case 'perpendicular':
+            return filterByTest(items, owner, (d) => isPerpendicular(d, desc.vec));
+        case 'type':
+            return items.filter((g) => typeMatches(g, desc.name));
+        case 'minmax':
+            // `DirectionMinMaxSelector` = CenterNthSelector(n=-1, max) — no pre-filter.
+            return nthCluster(items, desc.vec, desc.max, -1);
+        case 'minmaxNth': {
+            // `DirectionNthSelector`: parallel pre-filter, then Nth cluster.
+            const parallel = filterByTest(items, owner, (d) => isParallel(d, desc.vec));
+            return nthCluster(parallel, desc.vec, desc.max, desc.n);
+        }
+        case 'centerNth': {
+            // `CenterNthSelector`: no pre-filter, arbitrary index (n=-1 when absent).
+            const n = desc.n ?? -1;
+            return nthCluster(items, desc.vec, desc.max, n);
+        }
+    }
+}
+// ── expression evaluation ─────────────────────────────────────────────────
+/** Evaluate an expression over the candidate list (upstream `Selector.filter`). */
+function evalExpr(sel, expr) {
+    const { items, owner } = sel;
+    switch (expr.op) {
+        case 'atom':
+            return applyAtom(items, owner, expr.desc);
+        case 'and': {
+            let acc = null;
+            for (const t of expr.terms) {
+                const r = evalExpr({ items, owner }, t);
+                acc = acc === null ? r : intersect(acc, r);
+            }
+            return acc ?? [];
+        }
+        case 'or': {
+            let acc = [];
+            for (const t of expr.terms) {
+                acc = union(acc, evalExpr({ items, owner }, t));
+            }
+            return acc;
+        }
+        case 'exc': {
+            let acc = evalExpr({ items, owner }, expr.terms[0]);
+            for (let i = 1; i < expr.terms.length; i++) {
+                acc = subtract(acc, evalExpr({ items, owner }, expr.terms[i]));
+            }
+            return acc;
+        }
+        case 'not': {
+            // `InverseSelector`: complement of the operand within the full list.
+            const r = evalExpr({ items, owner }, expr.term);
+            return subtract(items, r);
+        }
+    }
+}
+//# sourceMappingURL=resolve.js.map

package/dist/api/cadquery-selectors/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/resolve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * cadquery-selectors/resolve — evaluate a parsed `SelectorExpr` against a set\n * of candidate entities (plan §4.5). Clean-room re-encoding of\n * `cadquery/selectors.py`:\n *\n *   · `_SimpleStringSyntaxSelector._chooseSelector` — atom → selector object\n *   · `_NthSelector.cluster`/`filter` — center-projection sort + cluster\n *   · `BaseDirSelector.filter` — linear edges / planar faces only, else drop\n *   · `BinarySelector` set algebra (`AndSelector`/`SumSelector`/\n *     `SubtractSelector`/`InverseSelector`) from the expression grammar.\n *\n * Every child of a set operation is applied to the SAME full input list and its\n * results combined (upstream `BinarySelector.filter`), so operands do not chain\n * into each other.\n *\n * Validated against the LOCKED cadquery 2.8.0 probe (C:\\cqenv\\sel_probe.py)\n * — cube_off ground truth recorded in plan §5.2.\n *\n * @platform occt — narrowing evaluates kernel `ShapeHandle`s through the\n * native occt-kernel (`getKernel()`: isSame identity dedup etc.), so this\n * module is occt-coupled by nature.\n */\nimport { getKernel } from '../../occt-kernel/occtKernel'\nimport type { OcctKernel } from 'occt-wasm'\nimport type { AtomDesc, EntityKind, SelectorExpr, SelStep, Vec3 } from './types'\nimport type { EntityGeom, P3, ShapeHandle } from './entity'\nimport { faceGeom, edgeGeom, vertexGeom, subShapeHandles } from './entity'\nimport { parseSelector } from './grammar'\nimport {\n  NTH_TOLERANCE,\n  isAligned,\n  isDirectionCandidate,\n  isParallel,\n  isPerpendicular,\n  typeMatches,\n  entityDirection,\n} from './predicates'\n\n/** A set of candidate entities with their owning shape (for normal orientation). */\nexport interface Selection {\n  owner: ShapeHandle | null\n  items: EntityGeom[]\n}\n\n/** A fully-resolved narrowing chain: the surviving kind and kernel handles. */\nexport interface ChainResult {\n  kind: EntityKind\n  handles: ShapeHandle[]\n}\n\n/** Project a kernel handle of the given kind into its `EntityGeom`. */\nfunction project(handle: ShapeHandle, kind: EntityKind): EntityGeom {\n  if (kind === 'face') return faceGeom(handle)\n  if (kind === 'edge') return edgeGeom(handle)\n  return vertexGeom(handle)\n}\n\n/**\n * Multi-step `{kind, sel}` narrowing (plan §4.5). Each step collects the `kind`\n * sub-entities of every currently-held object, dedups by kernel identity, then\n * filters by the parsed selector. An empty `sel` collects without filtering\n * (CadQuery `.vertices()` / `.edges()`, whose `_filter` is a no-op).\n *\n *   resolveSelection(shape, [{face,'+Z'},{vertex,'<XY'}])\n *     → the +Z face's vertices with the smallest x+y, in the order they appear.\n *\n * @param owner - The owning shape handle to start from (or `null` for empty).\n * @param chain - The ordered per-kind narrowing steps to apply.\n * @returns The final kind and the surviving kernel handles at that kind.\n */\nexport function resolveSelection(owner: ShapeHandle | null, chain: SelStep[]): ChainResult {\n  if (chain.length === 0) {\n    return { kind: 'face', handles: owner ? subShapeHandles(owner, 'face') : [] }\n  }\n  let candidates: ShapeHandle[] = owner ? [owner] : []\n  let kind: EntityKind = chain[0].kind\n  for (const step of chain) {\n    // ① collect: sub-entities of each candidate, union/ordered, dedup by identity.\n    const gathered: ShapeHandle[] = dedupByIsSame(\n      candidates.flatMap((o) => subShapeHandles(o, step.kind)),\n    )\n    // ② filter: resolve the selector over the gathered views.\n    const items = gathered.map((h) => project(h, step.kind))\n    candidates =\n      step.sel.trim() === ''\n        ? gathered\n        : evalExpr({ owner, items }, parseSelector(step.sel)).map((g) => g._handle)\n    kind = step.kind\n  }\n  return { kind, handles: candidates }\n}\n\n/** Deduplicate kernel handles by KERNEL identity (isSame), preserving order. */\nfunction dedupByIsSame(handles: ShapeHandle[]): ShapeHandle[] {\n  const out: ShapeHandle[] = []\n  for (const h of handles) {\n    if (!out.some((o) => kernOf().isSame(o as never, h as never))) out.push(h)\n  }\n  return out\n}\n\nfunction kernOf(): OcctKernel {\n  return getKernel() as unknown as OcctKernel\n}\n\n// ─── single-kind conveniences (plan §4.6) ────────────────────────────────\n\n/**\n * Narrow a single step and return the surviving kernel handles. Backs the\n * `resolveEdgeSelection` / `resolveVertexSelector` / `resolveFaceEdgeSelection`\n * projections.\n *\n * @param owner - The owning shape handle to start from (or `null` for empty).\n * @param kind - The topological kind of the step.\n * @param sel - The CadQuery selector string for the step (may be empty).\n * @returns The surviving kernel handles after the single-step narrowing.\n */\nexport function resolveStepHandles(\n  owner: ShapeHandle | null,\n  kind: EntityKind,\n  sel: string,\n): ShapeHandle[] {\n  return resolveSelection(owner, [{ kind, sel }]).handles\n}\n\n/** Center dot direction — the ordering key for the N-th selectors. */\nfunction projKey(g: EntityGeom, axis: Vec3): number {\n  const c = g.center()\n  return c.x * axis.x + c.y * axis.y + c.z * axis.z\n}\n\n/**\n * `_NthSelector.cluster` + `filter`: sort by key, cluster consecutive items\n * within `NTH_TOLERANCE`, then return the cluster at index `n` of the list\n * reversed when `max` is false. An empty input raises (upstream\n * `_NthSelector.filter` ValueError); an out-of-range `n` raises IndexError.\n */\nfunction nthCluster(items: EntityGeom[], axis: Vec3, max: boolean, n: number): EntityGeom[] {\n  if (items.length === 0) {\n    throw new EmptyNthError('Can not return the Nth element of an empty list')\n  }\n\n  const keyed = items\n    .map((g) => ({ g, key: projKey(g, axis) }))\n    .sort((a, b) => a.key - b.key)\n\n  const clusters: EntityGeom[][] = []\n  let cur = [keyed[0].g]\n  let start = keyed[0].key\n  for (let i = 1; i < keyed.length; i++) {\n    const { g, key } = keyed[i]\n    if (Math.abs(key - start) <= NTH_TOLERANCE) {\n      cur.push(g)\n    } else {\n      clusters.push(cur)\n      cur = [g]\n      start = key\n    }\n  }\n  clusters.push(cur)\n\n  // `_NthSelector.filter`: descending requires reversing the cluster list first.\n  if (!max) clusters.reverse()\n\n  // Python-style negative index (e.g. `>Z[-2]` ⇔ `clusters[-2]`).\n  const idx = n < 0 ? clusters.length + n : n\n  const out = clusters[idx]\n  if (out === undefined) {\n    throw new RangeError(\n      `Attempted to access index ${n} of a list with length ${clusters.length}`,\n    )\n  }\n  return out\n}\n\n/** ValueError-equivalent for an empty input to a N-th selector. */\nexport class EmptyNthError extends Error {}\n\n// ── set operations (BinarySelector) ────────────────────────────────────────\n\n/** `AndSelector`: intersection by kernel identity. */\nfunction intersect(a: EntityGeom[], b: EntityGeom[]): EntityGeom[] {\n  const bs = new Set(b.map((g) => g.hash()))\n  return a.filter((g) => bs.has(g.hash()))\n}\n\n/** `SumSelector`: union (no duplicates) by kernel identity. */\nfunction union(a: EntityGeom[], b: EntityGeom[]): EntityGeom[] {\n  const seen = new Set<number>()\n  const out: EntityGeom[] = []\n  for (const g of a.concat(b)) {\n    const h = g.hash()\n    if (!seen.has(h)) {\n      seen.add(h)\n      out.push(g)\n    }\n  }\n  return out\n}\n\n/** `SubtractSelector`: set difference by kernel identity. */\nfunction subtract(a: EntityGeom[], b: EntityGeom[]): EntityGeom[] {\n  const bs = new Set(b.map((g) => g.hash()))\n  return a.filter((g) => !bs.has(g.hash()))\n}\n\n// ── atom application ──────────────────────────────────────────────────────\n\n/** BaseDirSelector filter: the direction test over allowed entity kinds. */\nfunction filterByTest(\n  items: EntityGeom[],\n  owner: ShapeHandle | null,\n  test: (d: P3) => boolean,\n): EntityGeom[] {\n  const out: EntityGeom[] = []\n  for (const g of items) {\n    if (!isDirectionCandidate(g)) continue\n    const d = entityDirection(g, owner ?? undefined)\n    if (d !== null && test(d)) out.push(g)\n  }\n  return out\n}\n\n/** Apply one atom to the full candidate list, mirroring each selector.filter. */\nfunction applyAtom(items: EntityGeom[], owner: ShapeHandle | null, desc: AtomDesc): EntityGeom[] {\n  switch (desc.kind) {\n    case 'dir':\n      // `DirectionSelector` (bare `X` or `(x,y,z)`): angle≈0, signed — same as\n      // the `+` operator (upstream `only_dir` maps to DirectionSelector).\n      return filterByTest(items, owner, (d) => isAligned(d, desc.vec, 1))\n    case 'signed':\n      return filterByTest(items, owner, (d) => isAligned(d, desc.vec, desc.sign))\n    case 'parallel':\n      return filterByTest(items, owner, (d) => isParallel(d, desc.vec))\n    case 'perpendicular':\n      return filterByTest(items, owner, (d) => isPerpendicular(d, desc.vec))\n    case 'type':\n      return items.filter((g) => typeMatches(g, desc.name))\n    case 'minmax':\n      // `DirectionMinMaxSelector` = CenterNthSelector(n=-1, max) — no pre-filter.\n      return nthCluster(items, desc.vec, desc.max, -1)\n    case 'minmaxNth': {\n      // `DirectionNthSelector`: parallel pre-filter, then Nth cluster.\n      const parallel = filterByTest(items, owner, (d) => isParallel(d, desc.vec))\n      return nthCluster(parallel, desc.vec, desc.max, desc.n)\n    }\n    case 'centerNth': {\n      // `CenterNthSelector`: no pre-filter, arbitrary index (n=-1 when absent).\n      const n = desc.n ?? -1\n      return nthCluster(items, desc.vec, desc.max, n)\n    }\n  }\n}\n\n// ── expression evaluation ─────────────────────────────────────────────────\n\n/** Evaluate an expression over the candidate list (upstream `Selector.filter`). */\nfunction evalExpr(sel: Selection, expr: SelectorExpr): EntityGeom[] {\n  const { items, owner } = sel\n  switch (expr.op) {\n    case 'atom':\n      return applyAtom(items, owner, expr.desc)\n    case 'and': {\n      let acc: EntityGeom[] | null = null\n      for (const t of expr.terms) {\n        const r = evalExpr({ items, owner }, t)\n        acc = acc === null ? r : intersect(acc, r)\n      }\n      return acc ?? []\n    }\n    case 'or': {\n      let acc: EntityGeom[] = []\n      for (const t of expr.terms) {\n        acc = union(acc, evalExpr({ items, owner }, t))\n      }\n      return acc\n    }\n    case 'exc': {\n      let acc: EntityGeom[] = evalExpr({ items, owner }, expr.terms[0])\n      for (let i = 1; i < expr.terms.length; i++) {\n        acc = subtract(acc, evalExpr({ items, owner }, expr.terms[i]))\n      }\n      return acc\n    }\n    case 'not': {\n      // `InverseSelector`: complement of the operand within the full list.\n      const r = evalExpr({ items, owner }, expr.term)\n      return subtract(items, r)\n    }\n  }\n}"]}

package/dist/api/cadquery-selectors/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * cadquery-selectors/types — shared types for the CadQuery selector subsystem.
+ *
+ * Companion to `2026-10-02-cadquery-selector-parity-plan.md`. These types are
+ * the machine-readable description of the CadQuery string-syntax selector
+ * grammar (upstream `cadquery/selectors.py` `_makeGrammar` /
+ * `_makeExpressionGrammar`), so faijs' string selectors can be *verified*
+ * against the reference implementation rather than approximated.
+ */
+/** A topological entity kind that selectors can target. */
+export type EntityKind = 'face' | 'edge' | 'vertex';
+/** A single narrowing step: pick `kind` sub-entities, then filter by `sel`. */
+export interface SelStep {
+    kind: EntityKind;
+    sel: string;
+}
+/** A 3-D vector (component-wise, arbitrary scale). Kept non-normalised to
+ * mirror CadQuery's `axes` table which stores `(1,1,0)` for `XY` etc. */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * A parse atom. Every string-syntax atom maps to exactly one descriptor,
+ * mirroring upstream `_SimpleStringSyntaxSelector._chooseSelector`.
+ */
+export type AtomDesc = {
+    kind: 'dir';
+    vec: Vec3;
+} | {
+    kind: 'parallel';
+    vec: Vec3;
+} | {
+    kind: 'perpendicular';
+    vec: Vec3;
+} | {
+    kind: 'signed';
+    vec: Vec3;
+    sign: 1 | -1;
+} | {
+    kind: 'minmax';
+    vec: Vec3;
+    max: boolean;
+} | {
+    kind: 'minmaxNth';
+    vec: Vec3;
+    max: boolean;
+    n: number;
+} | {
+    kind: 'centerNth';
+    vec: Vec3;
+    max: boolean;
+    n: number | null;
+} | {
+    kind: 'type';
+    name: string;
+};
+/**
+ * Abstract syntax tree produced by the string grammar. Mirrors the pyparsing
+ * `infix_notation` node shape: `and`/`or`/`exc` are n-ary left folds of their
+ * (odd-indexed) operands; `not` is unary, right-associative, highest precedence.
+ */
+export type SelectorExpr = {
+    op: 'atom';
+    desc: AtomDesc;
+} | {
+    op: 'and' | 'or' | 'exc';
+    terms: SelectorExpr[];
+} | {
+    op: 'not';
+    term: SelectorExpr;
+};
+/**
+ * The geometry quantities a lifted entity exposes to predicates. Projected
+ * lazily (each field is a function so a predicate only pays for what it reads).
+ * `center` mirrors CadQuery's `Shape.Center()` — for faces this is the
+ * area-weighted surface center of mass, NOT the bounding-box center.
+ */
+export interface EntityProj {
+    /** Stable identity for de-dup / set keys (kernel hashCode). */
+    hash: number;
+    /** CadQuery `Shape.Center()`: vertex point / linear COM / surface COM. */
+    center: Vec3;
+    /** `Face.Center()` normal — oriented outward via owning solid. Null for non-faces. */
+    surfaceNormal?: Vec3;
+    /** `Edge.tangentAt(0.5)` — oriented along the edge's parameter direction. */
+    tangent?: Vec3;
+    /** `Face/Edge.geomType()` upcased, e.g. 'PLANE' / 'LINE' / 'CIRCLE'. */
+    geomType?: string;
+    /** Only used for edge `%type` ordering of LUT (results present when edge). */
+    isEdge: boolean;
+    isFace: boolean;
+    isVertex: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/cadquery-selectors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEnD,+EAA+E;AAC/E,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,UAAU,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;yEACyE;AACzE,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAElC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,GACnD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAA;AAErC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,MAAM,EAAE,IAAI,CAAA;IACZ,sFAAsF;IACtF,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;CAClB"}

package/dist/api/cadquery-selectors/types.js

@@ -0,0 +1,11 @@
+/**
+ * cadquery-selectors/types — shared types for the CadQuery selector subsystem.
+ *
+ * Companion to `2026-10-02-cadquery-selector-parity-plan.md`. These types are
+ * the machine-readable description of the CadQuery string-syntax selector
+ * grammar (upstream `cadquery/selectors.py` `_makeGrammar` /
+ * `_makeExpressionGrammar`), so faijs' string selectors can be *verified*
+ * against the reference implementation rather than approximated.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/cadquery-selectors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * cadquery-selectors/types — shared types for the CadQuery selector subsystem.\n *\n * Companion to `2026-10-02-cadquery-selector-parity-plan.md`. These types are\n * the machine-readable description of the CadQuery string-syntax selector\n * grammar (upstream `cadquery/selectors.py` `_makeGrammar` /\n * `_makeExpressionGrammar`), so faijs' string selectors can be *verified*\n * against the reference implementation rather than approximated.\n */\n\n/** A topological entity kind that selectors can target. */\nexport type EntityKind = 'face' | 'edge' | 'vertex'\n\n/** A single narrowing step: pick `kind` sub-entities, then filter by `sel`. */\nexport interface SelStep {\n  kind: EntityKind\n  sel: string\n}\n\n/** A 3-D vector (component-wise, arbitrary scale). Kept non-normalised to\n * mirror CadQuery's `axes` table which stores `(1,1,0)` for `XY` etc. */\nexport interface Vec3 {\n  x: number\n  y: number\n  z: number\n}\n\n/**\n * A parse atom. Every string-syntax atom maps to exactly one descriptor,\n * mirroring upstream `_SimpleStringSyntaxSelector._chooseSelector`.\n */\nexport type AtomDesc =\n  | { kind: 'dir'; vec: Vec3 } // bare axis `X` / `(x,y,z)` — DirectionSelector\n  | { kind: 'parallel'; vec: Vec3 } // `|A` — ParallelDirSelector\n  | { kind: 'perpendicular'; vec: Vec3 } // `#A` — PerpendicularDirSelector\n  | { kind: 'signed'; vec: Vec3; sign: 1 | -1 } // `+A` / `-A` — DirectionSelector\n  | { kind: 'minmax'; vec: Vec3; max: boolean } // `>A` / `<A` — DirectionMinMaxSelector\n  | { kind: 'minmaxNth'; vec: Vec3; max: boolean; n: number } // `>A[k]` — DirectionNthSelector\n  | { kind: 'centerNth'; vec: Vec3; max: boolean; n: number | null } // `>>A` / `<<A[k]` — CenterNthSelector\n  | { kind: 'type'; name: string } // `%TYPE` — TypeSelector (name already upper-cased)\n\n/**\n * Abstract syntax tree produced by the string grammar. Mirrors the pyparsing\n * `infix_notation` node shape: `and`/`or`/`exc` are n-ary left folds of their\n * (odd-indexed) operands; `not` is unary, right-associative, highest precedence.\n */\nexport type SelectorExpr =\n  | { op: 'atom'; desc: AtomDesc }\n  | { op: 'and' | 'or' | 'exc'; terms: SelectorExpr[] }\n  | { op: 'not'; term: SelectorExpr }\n\n/**\n * The geometry quantities a lifted entity exposes to predicates. Projected\n * lazily (each field is a function so a predicate only pays for what it reads).\n * `center` mirrors CadQuery's `Shape.Center()` — for faces this is the\n * area-weighted surface center of mass, NOT the bounding-box center.\n */\nexport interface EntityProj {\n  /** Stable identity for de-dup / set keys (kernel hashCode). */\n  hash: number\n  /** CadQuery `Shape.Center()`: vertex point / linear COM / surface COM. */\n  center: Vec3\n  /** `Face.Center()` normal — oriented outward via owning solid. Null for non-faces. */\n  surfaceNormal?: Vec3\n  /** `Edge.tangentAt(0.5)` — oriented along the edge's parameter direction. */\n  tangent?: Vec3\n  /** `Face/Edge.geomType()` upcased, e.g. 'PLANE' / 'LINE' / 'CIRCLE'. */\n  geomType?: string\n  /** Only used for edge `%type` ordering of LUT (results present when edge). */\n  isEdge: boolean\n  isFace: boolean\n  isVertex: boolean\n}"]}

package/dist/api/chamfer.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib chamfer — chamfer 倒角库函数（BREP-only，directEdit 能力）
+ * api chamfer — chamfer 倒角库函数（BREP-only，directEdit 能力）
  *
  * 平台分层（2026-09-26 B 批降级）：**中立 op**（不再声明 `engines:['occt']`）。
  * equal 分支按引擎能力**静态定轨**（与 intersect 同构，读 `dispatchPath` 同源的能力集）：
@@ -26,10 +26,15 @@ import type { BrepEngineApi } from '../brep/engine/primitives.js';
 import type { ResolutionContext } from '../topology/naming/index.js';
 /**
  * Validate chamfer parameters: `edges` must be a non-empty array of EdgeTopoRef,
- * each with kind key "edge" and a two-entry faces pair.
+ * each with kind key "edge" and a two-entry faces pair — or of 1-based ordinals
+ * when `opts.allowOrdinals` (the mesh chain, which has no role layer to match
+ * edges against).
  * @param params the raw chamfer operation parameters.
+ * @param opts the selector-form options (mesh chain allows ordinals).
  */
-export declare function assertChamferParams(params: Record<string, unknown>): void;
+export declare function assertChamferParams(params: Record<string, unknown>, opts?: {
+    readonly allowOrdinals?: boolean;
+}): void;
 /**
  * twoDistances 单边换算：width1/width2 + β（§3.5）→ (dF, θ) 供一次 chamferDistAngle。
  * 参考面由内核自选（refOrdinal 的面）；width1 对应 faces[0] 侧、width2 对应 faces[1] 侧。
@@ -48,13 +53,15 @@ export declare function twoDistParams(kernel: BrepEngineApi, ctx: ResolutionCont
     angleDeg: number;
 };
 /**
- * 在几何体上倒角（等距 / 双距 / 距角）。仅 BREP 可用。
+ * 在几何体上倒角（等距 / 双距 / 距角）。
  * @group 特征
  * @inputs 1
  * @async true
  * @qual ok
  * @name chamfer
- * @note 倒角是 BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。参考面由内核自选，`width1` 沿 faces[0] 侧、`width2` 沿 faces[1] 侧。
+ * @note BREP 输入走完整三形态；**网格实体**输入只支持 `equal` / `distanceAngle`
+ *       （`twoDistances` 需要 role 可解析的邻面，近似拓扑没有 role）。
+ *       `width1` 沿 faces[0] 侧、`width2` 沿 faces[1] 侧（BREP 路径）。
  * @returns Shape 倒角后的几何。
  * @param input - 目标几何。type:Shape required:true
  * @param params.edges - 参与倒角的边（EdgeTopoRef[]，条目为相邻两面的 role 线路）。type:EdgeTopoRef[] required:true
@@ -65,6 +72,7 @@ export declare function twoDistParams(kernel: BrepEngineApi, ctx: ResolutionCont
  * @param params.angle - type=distanceAngle: 与参考面夹角（度，(0,90)）。type:number
  * @example
  * const p = await cad.chamfer(part0, { edges: [{ kind:'edge', faces:[{ origin:'box', role:'box:top' }, { origin:'box', role:'box:front' }], hint:{ kind:'edge' } }], type:'equal', width:1 })
+ * const q = await cad.chamfer(meshPart, { edges: [3], type:'equal', width:1 })
  */
 export declare const chamfer: ((input: Shape, params: Record<string, unknown>) => Promise<Shape>) & {
     __faijs__dualOp?: import("../define-op.js").DualOpMeta;

package/dist/api/chamfer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chamfer.d.ts","sourceRoot":"","sources":["../../src/api/chamfer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAQ1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAE9D,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAQxE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuCzE;AAyCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,iBAAiB,EACtB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAgBxC;AAwHD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,OAAO;;CAQlB,CAAA"}
+{"version":3,"file":"chamfer.d.ts","sourceRoot":"","sources":["../../src/api/chamfer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAQ1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAE9D,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAUxE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1C,IAAI,CA6CN;AAyCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,iBAAiB,EACtB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAgBxC;AAsKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,OAAO;;CAclB,CAAA"}

package/dist/api/chamfer.js

@@ -1,5 +1,5 @@
 /**
- * stdlib chamfer — chamfer 倒角库函数（BREP-only，directEdit 能力）
+ * api chamfer — chamfer 倒角库函数（BREP-only，directEdit 能力）
  *
  * 平台分层（2026-09-26 B 批降级）：**中立 op**（不再声明 `engines:['occt']`）。
  * equal 分支按引擎能力**静态定轨**（与 intersect 同构，读 `dispatchPath` 同源的能力集）：
@@ -30,19 +30,30 @@ import { fromBrep, brepOf, inputRoleTable } from '../shape.js';
 import { defineOp } from '../sdk.js';
 import { resolveTopoRef, facesForQualifier, TopoRefError } from '../topology/naming/index.js';
 import { buildEdgeResolutionContext, buildEdgeContextFromSolid } from './topo-resolve.js';
+import { OpError } from './internal/result-unwrap.js';
+import { meshKernelFailure, meshSolidEntry, meshSolidProduct, resolveMeshEdges } from './internal/mesh-solid-op.js';
 import { angleBetweenNormals, materialDihedralFromNormalAngle, chamferAngleFromDistances } from './chamfer-math.js';
-// ── 参数自校验（stdlib 被直接 import 时的防御层）──
+// ── 参数自校验（api 层被直接 import 时的防御层）──
 /**
  * Validate chamfer parameters: `edges` must be a non-empty array of EdgeTopoRef,
- * each with kind key "edge" and a two-entry faces pair.
+ * each with kind key "edge" and a two-entry faces pair — or of 1-based ordinals
+ * when `opts.allowOrdinals` (the mesh chain, which has no role layer to match
+ * edges against).
  * @param params the raw chamfer operation parameters.
+ * @param opts the selector-form options (mesh chain allows ordinals).
  */
-export function assertChamferParams(params) {
+export function assertChamferParams(params, opts) {
     const edges = params.edges;
     if (!Array.isArray(edges) || edges.length === 0) {
         throw new Error('E_CHAMFER_NO_EDGES: chamfer requires at least one edge');
     }
     for (const e of edges) {
+        if (opts?.allowOrdinals && typeof e === 'number') {
+            if (!Number.isInteger(e) || e < 1) {
+                throw new Error('E_CHAMFER_BAD_EDGE_REF: an edge ordinal must be a positive integer (1-based)');
+            }
+            continue;
+        }
         if (!e || typeof e !== 'object' || e.kind !== 'edge') {
             throw new Error('E_CHAMFER_BAD_EDGE_REF: every edge entry must be an EdgeTopoRef with kind:"edge"');
         }
@@ -177,7 +188,7 @@ function chamferBrep(input, params) {
     const kernel = getBrepApi();
     const solid = brepOf(input);
     if (!solid)
-        throw new Error('[stdlib/chamfer] E_CHAMFER_NO_BREP: input is not BREP');
+        throw new Error('[api/chamfer] E_CHAMFER_NO_BREP: input is not BREP');
     const edges = params.edges ?? [];
     const type = params.type;
     const ctx = buildEdgeResolutionContext(kernel, input);
@@ -242,13 +253,51 @@ function chamferBrep(input, params) {
     return fromBrep(solidToShape(kernel, resultSolid), faceEvolution ? { solid: resultSolid, faceEvolution, roleTable } : { solid: resultSolid, roleTable });
 }
 /**
- * 在几何体上倒角（等距 / 双距 / 距角）。仅 BREP 可用。
+ * 网格实体路径：对近似拓扑里识别出的边倒角（方案 2026-10-01 §3.5 三明治）。
+ *
+ * 支持的形态与 BREP 路径的差异：
+ * - `equal` → L1 裸 `kernel.chamfer`；`distanceAngle` → `kernel.chamferDistAngle`；
+ * - `twoDistances` **不支持**：它要把 `faces[0]/faces[1]` 两个 role 限定符解析到面，
+ *   再由内核选中的参考面决定 width1/width2 各归哪一侧。近似拓扑没有 role 层，
+ *   这两个限定符无从解析——如实拒绝，不猜一个参考面（猜错 = 倒角落在错误的一侧）。
+ *
+ * 与 fillet 同一条 GOTCHA：一次请求里的全部边交给内核会在共面边链上被整体拒绝，
+ * 本实现如实失败，不自动拆成逐边重试。
+ *
+ * @param input - the mesh-solid input.
+ * @param params - the validated chamfer parameters.
+ * @returns the chamfered mesh solid as a new mesh part.
+ */
+function chamferMeshSolid(input, params) {
+    const type = params.type;
+    const edges = params.edges ?? [];
+    if (type === 'twoDistances') {
+        throw new OpError('chamfer', 'E_MESH_SOLID_UNSUPPORTED', '[api/chamfer] twoDistances needs role-resolvable adjacent faces to decide which side ' +
+            'carries width1/width2; a mesh solid has no role layer — use type:"equal" or "distanceAngle"');
+    }
+    const entry = meshSolidEntry(input, 'chamfer');
+    const edgeHandles = resolveMeshEdges(entry, edges, 'chamfer');
+    let result;
+    try {
+        result = type === 'distanceAngle'
+            ? entry.kernel.chamferDistAngle(entry.solid, edgeHandles, params.width, params.angle)
+            : entry.kernel.chamfer(entry.solid, edgeHandles, params.width);
+    }
+    catch (cause) {
+        throw meshKernelFailure('chamfer', 'E_CHAMFER_FAILED', `chamfer(type=${type}) on ${edgeHandles.length} edge(s)`, cause);
+    }
+    return meshSolidProduct(entry, result);
+}
+/**
+ * 在几何体上倒角（等距 / 双距 / 距角）。
  * @group 特征
  * @inputs 1
  * @async true
  * @qual ok
  * @name chamfer
- * @note 倒角是 BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。参考面由内核自选，`width1` 沿 faces[0] 侧、`width2` 沿 faces[1] 侧。
+ * @note BREP 输入走完整三形态；**网格实体**输入只支持 `equal` / `distanceAngle`
+ *       （`twoDistances` 需要 role 可解析的邻面，近似拓扑没有 role）。
+ *       `width1` 沿 faces[0] 侧、`width2` 沿 faces[1] 侧（BREP 路径）。
  * @returns Shape 倒角后的几何。
  * @param input - 目标几何。type:Shape required:true
  * @param params.edges - 参与倒角的边（EdgeTopoRef[]，条目为相邻两面的 role 线路）。type:EdgeTopoRef[] required:true
@@ -259,10 +308,17 @@ function chamferBrep(input, params) {
  * @param params.angle - type=distanceAngle: 与参考面夹角（度，(0,90)）。type:number
  * @example
  * const p = await cad.chamfer(part0, { edges: [{ kind:'edge', faces:[{ origin:'box', role:'box:top' }, { origin:'box', role:'box:front' }], hint:{ kind:'edge' } }], type:'equal', width:1 })
+ * const q = await cad.chamfer(meshPart, { edges: [3], type:'equal', width:1 })
  */
 export const chamfer = defineOp({
     // 中立 op（2026-09-26 B 批）：不再声明 engines——equal 路径按引擎能力静态分派
     // （occt→chamferWithHistory 历史路径；brepkit→裸 kernel.chamfer 无演化降级）。
+    // meshEngines：网格实体路径由 brepkit 网格后端提供（方案 2026-10-01 §3.4）。
+    meshEngines: ['brepkit'],
+    mesh(input, params) {
+        assertChamferParams(params, { allowOrdinals: true });
+        return chamferMeshSolid(input, params);
+    },
     brep(input, params) {
         assertChamferParams(params);
         return chamferBrep(input, params);