@faicad/faijs 0.19.0 → 0.29.3

package/dist/api/cadquery-selectors/borrow-bridge.js

@@ -0,0 +1,52 @@
+/**
+ * cadquery-selectors/borrow-bridge — compatOp 提升边界归一（等价搬运自 cq-compat）
+ *
+ * 原实现位于 `packages/faijs-cadquery/src/workplane.ts` 的 `asBrepShape`，本文件为
+ * 原样搬运（仅 import 路径改为 core 内部相对路径），零逻辑改动。
+ */
+import { fromHandle } from '../../sdk.js';
+import { isShape } from '../../shape.js';
+// ── compatOp 提升边界归一（GOTCHA：borrowDeep 把实参 Shape 换成借用视图）──
+//
+// 当 cq-compat 命名空间被 registerLib 提升（无 dual-op → autoLift=true）时，
+// 每个裸导出函数的实参先经 borrowDeep：faijs Shape → 借用 brepjs 视图
+// `{ wrapped, disposed, delete, onDispose }`（`isShape=false`、`brepOf=undefined`）。
+// 直接调用（测试进程内）拿到的则是真实 Shape。两个形态都必须能消费：
+//
+//   asBrepShape(v) —
+//   - 真实 Shape → 原样返回；
+//   - 借用视图（有 `.wrapped`）→ 提取原始 OCCT 句柄，fromHandle 还原为真实
+//     Shape（mesh 三角化 + BREP 身份槽登记，brepOf 可恢复），按视图对象缓存
+//     （同句柄多次调用不重复三角化）；
+//   - 其余 → 原样返回（调用方自行判空/报错）。
+//
+// 所有权：归一出的新 Shape 与原 part Shape 的 slot 指向同一 OCCT 句柄，但 slot
+// 按 Shape 对象各自持有（fromBrep 写的是新 Shape 的 slot），无共享释放路径——
+// 与 core fromHandle 收编模式同构，不引入双重释放。
+// 视图 `.wrapped` 是 OcctWasmHandle 对象（{ id, type, __occtWasm }），内核只收
+// 数字 id → 解包方式与 core fromHandle 一致。
+const borrowedShapeCache = new WeakMap();
+/**
+ * 把可能是借用视图的几何输入归一为真实 faijs Shape（见上方注释）。
+ * @param v 真实 Shape、借用视图（`{ wrapped }`）或其他原样透传的输入。
+ * @returns 真实 faijs `Shape`（借用视图经 `fromHandle` 还原并缓存）。
+ */
+export function asBrepShape(v) {
+    if (isShape(v))
+        return v;
+    if (v !== null && typeof v === 'object' && 'wrapped' in v) {
+        const view = v;
+        const hit = borrowedShapeCache.get(view);
+        if (hit)
+            return hit;
+        const wrappedAny = view.wrapped;
+        const handle = typeof wrappedAny === 'object' && wrappedAny !== null && 'id' in wrappedAny
+            ? wrappedAny.id
+            : wrappedAny;
+        const s = fromHandle(handle);
+        borrowedShapeCache.set(view, s);
+        return s;
+    }
+    return v;
+}
+//# sourceMappingURL=borrow-bridge.js.map

package/dist/api/cadquery-selectors/borrow-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"borrow-bridge.js","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/borrow-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAGrC,2DAA2D;AAC3D,EAAE;AACF,gEAAgE;AAChE,qDAAqD;AACrD,kFAAkF;AAClF,uCAAuC;AACvC,EAAE;AACF,qBAAqB;AACrB,uBAAuB;AACvB,wDAAwD;AACxD,sDAAsD;AACtD,uBAAuB;AACvB,6BAA6B;AAC7B,EAAE;AACF,2DAA2D;AAC3D,uDAAuD;AACvD,oCAAoC;AACpC,mEAAmE;AACnE,oCAAoC;AACpC,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAAiB,CAAA;AAEvD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,IAAI,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAU,CAAA;IACjC,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,CAAyB,CAAA;QACtC,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACxC,IAAI,GAAG;YAAE,OAAO,GAAG,CAAA;QACnB,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAA;QAC/B,MAAM,MAAM,GACV,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,IAAI,IAAI,IAAI,UAAU;YACzE,CAAC,CAAE,UAA6B,CAAC,EAAE;YACnC,CAAC,CAAC,UAAU,CAAA;QAChB,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAU,CAAA;QACrC,kBAAkB,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;QAC/B,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,CAAU,CAAA;AACnB,CAAC","sourcesContent":["/**\n * cadquery-selectors/borrow-bridge — compatOp 提升边界归一（等价搬运自 cq-compat）\n *\n * 原实现位于 `packages/faijs-cadquery/src/workplane.ts` 的 `asBrepShape`，本文件为\n * 原样搬运（仅 import 路径改为 core 内部相对路径），零逻辑改动。\n */\n\nimport { fromHandle } from '../../sdk'\nimport { isShape } from '../../shape'\nimport type { Shape } from '../../mesh/types'\n\n// ── compatOp 提升边界归一（GOTCHA：borrowDeep 把实参 Shape 换成借用视图）──\n//\n// 当 cq-compat 命名空间被 registerLib 提升（无 dual-op → autoLift=true）时，\n// 每个裸导出函数的实参先经 borrowDeep：faijs Shape → 借用 brepjs 视图\n// `{ wrapped, disposed, delete, onDispose }`（`isShape=false`、`brepOf=undefined`）。\n// 直接调用（测试进程内）拿到的则是真实 Shape。两个形态都必须能消费：\n//\n//   asBrepShape(v) —\n//   - 真实 Shape → 原样返回；\n//   - 借用视图（有 `.wrapped`）→ 提取原始 OCCT 句柄，fromHandle 还原为真实\n//     Shape（mesh 三角化 + BREP 身份槽登记，brepOf 可恢复），按视图对象缓存\n//     （同句柄多次调用不重复三角化）；\n//   - 其余 → 原样返回（调用方自行判空/报错）。\n//\n// 所有权：归一出的新 Shape 与原 part Shape 的 slot 指向同一 OCCT 句柄，但 slot\n// 按 Shape 对象各自持有（fromBrep 写的是新 Shape 的 slot），无共享释放路径——\n// 与 core fromHandle 收编模式同构，不引入双重释放。\n// 视图 `.wrapped` 是 OcctWasmHandle 对象（{ id, type, __occtWasm }），内核只收\n// 数字 id → 解包方式与 core fromHandle 一致。\nconst borrowedShapeCache = new WeakMap<object, Shape>()\n\n/**\n * 把可能是借用视图的几何输入归一为真实 faijs Shape（见上方注释）。\n * @param v 真实 Shape、借用视图（`{ wrapped }`）或其他原样透传的输入。\n * @returns 真实 faijs `Shape`（借用视图经 `fromHandle` 还原并缓存）。\n */\nexport function asBrepShape(v: unknown): Shape {\n  if (isShape(v)) return v as Shape\n  if (v !== null && typeof v === 'object' && 'wrapped' in v) {\n    const view = v as { wrapped: unknown }\n    const hit = borrowedShapeCache.get(view)\n    if (hit) return hit\n    const wrappedAny = view.wrapped\n    const handle =\n      typeof wrappedAny === 'object' && wrappedAny !== null && 'id' in wrappedAny\n        ? (wrappedAny as { id: number }).id\n        : wrappedAny\n    const s = fromHandle(handle) as Shape\n    borrowedShapeCache.set(view, s)\n    return s\n  }\n  return v as Shape\n}"]}

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

@@ -0,0 +1,40 @@
+import type { Shape } from '../../mesh/types.js';
+/**
+ * Resolve a CadQuery EDGE selector string to concrete edge handles, using ONLY
+ * the new selector engine (upstream `selectors.py` semantics):
+ *
+ *   · `|Z` — ParallelDirSelector (edges whose tangent is parallel to the axis)
+ *   · `#Z` — PerpendicularDirSelector (edges whose tangent is perpendicular)
+ *   · `X` / `+X` / `-X` — DirectionSelector (signed tangent angle≈0)
+ *   · `>Z` / `<Z` — DirectionMinMaxSelector (extremal edge center along axis)
+ *   · `%LINE` / `%CIRCLE` — TypeSelector
+ *   · `and` / `or` / `except` / `not` — set algebra
+ *   · empty / missing — all edges (CadQuery `.edges()`)
+ *
+ * @param shape - Shape whose BREP edges are enumerated for selection.
+ * @param sel - CadQuery edge selector, or empty/null/undefined for all edges.
+ * @returns the matched edge handles (kernel identity space; cast to unknown).
+ */
+export declare function resolveEdgeSelection(shape: Shape, sel: string | null | undefined): unknown[];
+/**
+ * Resolve the edges belonging to the face picked by `sel` — upstream
+ * `.faces(">Z").edges()` semantics. The face selector runs first over the
+ * face candidate set, then the survivors' edges are collected (chain widening
+ * to edges, no filter): the selected face's own edges.
+ *
+ * @param shape - the shape whose BREP faces/edges are enumerated.
+ * @param sel - a face direction / type selector (">Z", "+Y", "%PLANE", etc.).
+ * @returns the handles of the edges belonging to the selected face(s).
+ */
+export declare function resolveFaceEdgeSelection(shape: Shape, sel: string): unknown[];
+/**
+ * Resolve a CadQuery vertex selector string to vertex handles (upstream `.vertices()`).
+ * Mirrors the narrowing semantics of the engine: direction-less selectors drop,
+ * cluster-based (`>`, `<`, `>>`, `<<`, `(x,y,z)`) apply.
+ *
+ * @param shape - the shape whose BREP vertices are enumerated.
+ * @param sel - the vertex selector string, or empty/undefined for all vertices.
+ * @returns the matched vertex handles.
+ */
+export declare function resolveVertexSelection(shape: Shape, sel: string | null | undefined): unknown[];
+//# sourceMappingURL=edge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/edge.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAO7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,CAG5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE,CAM7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,CAE9F"}

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

@@ -0,0 +1,70 @@
+/**
+ * cadquery-selectors/edge — CadQuery edge/vertex 选择器（hoild core 引擎 adapter）
+ *
+ * These are thin projections over the selector engine (plan §4.6). The heavy
+ * lifting (direction rules, Nth clustering, set algebra, type filtering) lives
+ * in `resolve.ts`; this file only bridges a faijs `Shape` into the engine's
+ * kernel-handle space and adapts the result back to the cq-compat-consumed
+ * `unknown[]` handle form.
+ *
+ * The legacy bbox-heuristic implementations (edn.g. `#Z` interpreted as "max
+ * along axis", `|Z` from relative extents) were removed in favour of the
+ * upstream `cadquery/selectors.py` semantics validated by
+ * `selectors.test.ts`.
+ */
+import { resolveSelection, resolveStepHandles } from './resolve.js';
+import { brepOf } from '../../shape.js';
+/** faijs BREP handle for a shape (numeric id space shared with occt-wasm). */
+function ownerHandle(shape) {
+    return brepOf(shape);
+}
+/**
+ * Resolve a CadQuery EDGE selector string to concrete edge handles, using ONLY
+ * the new selector engine (upstream `selectors.py` semantics):
+ *
+ *   · `|Z` — ParallelDirSelector (edges whose tangent is parallel to the axis)
+ *   · `#Z` — PerpendicularDirSelector (edges whose tangent is perpendicular)
+ *   · `X` / `+X` / `-X` — DirectionSelector (signed tangent angle≈0)
+ *   · `>Z` / `<Z` — DirectionMinMaxSelector (extremal edge center along axis)
+ *   · `%LINE` / `%CIRCLE` — TypeSelector
+ *   · `and` / `or` / `except` / `not` — set algebra
+ *   · empty / missing — all edges (CadQuery `.edges()`)
+ *
+ * @param shape - Shape whose BREP edges are enumerated for selection.
+ * @param sel - CadQuery edge selector, or empty/null/undefined for all edges.
+ * @returns the matched edge handles (kernel identity space; cast to unknown).
+ */
+export function resolveEdgeSelection(shape, sel) {
+    const selStr = sel ?? '';
+    return resolveStepHandles(ownerHandle(shape), 'edge', selStr);
+}
+/**
+ * Resolve the edges belonging to the face picked by `sel` — upstream
+ * `.faces(">Z").edges()` semantics. The face selector runs first over the
+ * face candidate set, then the survivors' edges are collected (chain widening
+ * to edges, no filter): the selected face's own edges.
+ *
+ * @param shape - the shape whose BREP faces/edges are enumerated.
+ * @param sel - a face direction / type selector (">Z", "+Y", "%PLANE", etc.).
+ * @returns the handles of the edges belonging to the selected face(s).
+ */
+export function resolveFaceEdgeSelection(shape, sel) {
+    const owner = ownerHandle(shape);
+    return resolveSelection(owner, [
+        { kind: 'face', sel },
+        { kind: 'edge', sel: '' },
+    ]).handles;
+}
+/**
+ * Resolve a CadQuery vertex selector string to vertex handles (upstream `.vertices()`).
+ * Mirrors the narrowing semantics of the engine: direction-less selectors drop,
+ * cluster-based (`>`, `<`, `>>`, `<<`, `(x,y,z)`) apply.
+ *
+ * @param shape - the shape whose BREP vertices are enumerated.
+ * @param sel - the vertex selector string, or empty/undefined for all vertices.
+ * @returns the matched vertex handles.
+ */
+export function resolveVertexSelection(shape, sel) {
+    return resolveStepHandles(ownerHandle(shape), 'vertex', sel ?? '');
+}
+//# sourceMappingURL=edge.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,8EAA8E;AAC9E,SAAS,WAAW,CAAC,KAAY;IAC/B,OAAO,MAAM,CAAC,KAAK,CAAY,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY,EAAE,GAA8B;IAC/E,MAAM,MAAM,GAAG,GAAG,IAAI,EAAE,CAAA;IACxB,OAAO,kBAAkB,CAAC,WAAW,CAAC,KAAK,CAAU,EAAE,MAAM,EAAE,MAAM,CAAc,CAAA;AACrF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAY,EAAE,GAAW;IAChE,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAU,CAAA;IACzC,OAAO,gBAAgB,CAAC,KAAK,EAAE;QAC7B,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;QACrB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE;KAC1B,CAAC,CAAC,OAAoB,CAAA;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY,EAAE,GAA8B;IACjF,OAAO,kBAAkB,CAAC,WAAW,CAAC,KAAK,CAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAc,CAAA;AAC1F,CAAC","sourcesContent":["/**\n * cadquery-selectors/edge — CadQuery edge/vertex 选择器（hoild core 引擎 adapter）\n *\n * These are thin projections over the selector engine (plan §4.6). The heavy\n * lifting (direction rules, Nth clustering, set algebra, type filtering) lives\n * in `resolve.ts`; this file only bridges a faijs `Shape` into the engine's\n * kernel-handle space and adapts the result back to the cq-compat-consumed\n * `unknown[]` handle form.\n *\n * The legacy bbox-heuristic implementations (edn.g. `#Z` interpreted as \"max\n * along axis\", `|Z` from relative extents) were removed in favour of the\n * upstream `cadquery/selectors.py` semantics validated by\n * `selectors.test.ts`.\n */\nimport { resolveSelection, resolveStepHandles } from './resolve'\nimport { brepOf } from '../../shape'\nimport type { Shape } from '../../mesh/types'\n\n/** faijs BREP handle for a shape (numeric id space shared with occt-wasm). */\nfunction ownerHandle(shape: Shape): unknown {\n  return brepOf(shape) as unknown\n}\n\n/**\n * Resolve a CadQuery EDGE selector string to concrete edge handles, using ONLY\n * the new selector engine (upstream `selectors.py` semantics):\n *\n *   · `|Z` — ParallelDirSelector (edges whose tangent is parallel to the axis)\n *   · `#Z` — PerpendicularDirSelector (edges whose tangent is perpendicular)\n *   · `X` / `+X` / `-X` — DirectionSelector (signed tangent angle≈0)\n *   · `>Z` / `<Z` — DirectionMinMaxSelector (extremal edge center along axis)\n *   · `%LINE` / `%CIRCLE` — TypeSelector\n *   · `and` / `or` / `except` / `not` — set algebra\n *   · empty / missing — all edges (CadQuery `.edges()`)\n *\n * @param shape - Shape whose BREP edges are enumerated for selection.\n * @param sel - CadQuery edge selector, or empty/null/undefined for all edges.\n * @returns the matched edge handles (kernel identity space; cast to unknown).\n */\nexport function resolveEdgeSelection(shape: Shape, sel: string | null | undefined): unknown[] {\n  const selStr = sel ?? ''\n  return resolveStepHandles(ownerHandle(shape) as never, 'edge', selStr) as unknown[]\n}\n\n/**\n * Resolve the edges belonging to the face picked by `sel` — upstream\n * `.faces(\">Z\").edges()` semantics. The face selector runs first over the\n * face candidate set, then the survivors' edges are collected (chain widening\n * to edges, no filter): the selected face's own edges.\n *\n * @param shape - the shape whose BREP faces/edges are enumerated.\n * @param sel - a face direction / type selector (\">Z\", \"+Y\", \"%PLANE\", etc.).\n * @returns the handles of the edges belonging to the selected face(s).\n */\nexport function resolveFaceEdgeSelection(shape: Shape, sel: string): unknown[] {\n  const owner = ownerHandle(shape) as never\n  return resolveSelection(owner, [\n    { kind: 'face', sel },\n    { kind: 'edge', sel: '' },\n  ]).handles as unknown[]\n}\n\n/**\n * Resolve a CadQuery vertex selector string to vertex handles (upstream `.vertices()`).\n * Mirrors the narrowing semantics of the engine: direction-less selectors drop,\n * cluster-based (`>`, `<`, `>>`, `<<`, `(x,y,z)`) apply.\n *\n * @param shape - the shape whose BREP vertices are enumerated.\n * @param sel - the vertex selector string, or empty/undefined for all vertices.\n * @returns the matched vertex handles.\n */\nexport function resolveVertexSelection(shape: Shape, sel: string | null | undefined): unknown[] {\n  return resolveStepHandles(ownerHandle(shape) as never, 'vertex', sel ?? '') as unknown[]\n}"]}

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

@@ -0,0 +1,121 @@
+/**
+ * cadquery-selectors/entity — projection of kernel handles into the geometric
+ * quantities the selector predicates need.
+ *
+ * Each helper mirrors the CadQuery shape method it stands in for (plan §4.3):
+ *   · `Vertex.Center()`      → vertex position
+ *   · `Edge.Center()`        → linear centre of mass (LinearProperties centroid)
+ *   · `Face.Center()`        → surface centre of mass (SurfaceProperties centroid)
+ *   · `Face.normalAt(None)`  → parametric surface normal at the uv midpoint,
+ *                              oriented outward via `containsPoint` on the owner
+ *   · `Edge.tangentAt()`     → curve tangent at the parameter midpoint,
+ *                              oriented along the edge parameter direction
+ *   · `Face/Edge.geomType()` → kernel surface/curve kind mapped to the CadQuery
+ *                              geom_LUT uppercased names
+ *
+ * These are deliberately decoupled from any single entity type so the
+ * predicates (predicates.ts) and the narrowing engine (resolve.ts) stay
+ * type-agnostic. All quantities are computed lazily by the caller via the
+ * projection object below.
+ *
+ * @platform occt — the projection resolves occt-wasm `ShapeHandle`s via the
+ * native kernel (`getKernel()`: getSubShapes / hashCode / isSame / bounds /
+ * surface & curve queries), so this module is occt-coupled by nature.
+ */
+import type { OcctKernel, ShapeHandle } from 'occt-wasm';
+/** Resolve the kernel geometry-kind → CadQuery LUT upcased name. */
+export interface GeomKindMap {
+    surface: Record<string, string>;
+    curve: Record<string, string>;
+}
+/**
+ * Map a kernel surface-kind string to the CadQuery `geomType()` name.
+ *
+ * @param kind - The kernel surface kind (e.g. `plane`, `cylinder`, `torus`).
+ * @returns The uppercased CadQuery geometry name, or `OTHER` when unmapped.
+ */
+export declare function faceGeomType(kind: string): string;
+/**
+ * Map a kernel curve-kind string to the CadQuery `geomType()` name.
+ *
+ * @param kind - The kernel curve kind (e.g. `line`, `circle`, `bspline`).
+ * @returns The uppercased CadQuery geometry name, or `OTHER` when unmapped.
+ */
+export declare function edgeGeomType(kind: string): string;
+/** World-space cartesian coordinates of an entity center point. */
+export interface EntityCenter {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Plain 3-D vector in faijs' internal convention. */
+export type P3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type { ShapeHandle };
+/**
+ * The lazily-evaluable geometry of one candidate entity. Predicates only access
+ * the fields they need so the heavy computation (surface normal, etc.) is only
+ * paid for when a direction/parallel filter is actually applied.
+ */
+export interface EntityGeom {
+    kind: 'face' | 'edge' | 'vertex';
+    /** Internal kernel handle for identity comparison (not part of the public surface). */
+    _handle: ShapeHandle;
+    /** Kernel handle box-identity hash (stable key across narrowing). */
+    hash(): number;
+    /** Kernel handle `isSame(...)` equality predicate. */
+    same(other: EntityGeom): boolean;
+    /** CadQuery `Shape.Center()` for this entity kind. */
+    center(): P3;
+    /**
+     * The direction used by direction-motivated selectors: the outward normal for
+     * a face (requires the owning shape for orientation) or the mid-parameter
+     * tangent for an edge. Null for vertices (no usable direction, upstream
+     * `BaseSelector` drops them).
+     */
+    direction(owner: ShapeHandle): P3 | null;
+    /** Face/Edge geometry type (upcased LUT name), or undefined for vertices. */
+    geomType(): string | undefined;
+}
+/**
+ * Project a face handle into its `EntityGeom`.
+ *
+ * @param face - The kernel face handle to project.
+ * @returns The lazily-evaluable face geometry (normal oriented on demand).
+ */
+export declare function faceGeom(face: ShapeHandle): EntityGeom;
+/**
+ * Orient a parametric face normal outward: offset probe → inside ⇒ flip.
+ *
+ * @param k - The active kernel instance used for surface/containment queries.
+ * @param face - The kernel face handle whose normal is oriented.
+ * @param owner - The owning shape handle used for the containment probe.
+ * @returns The outward-facing unit normal of `face`.
+ */
+export declare function orientedFaceNormal(k: OcctKernel, face: ShapeHandle, owner: ShapeHandle): P3;
+/**
+ * Project an edge handle into its `EntityGeom`.
+ *
+ * @param edge - The kernel edge handle to project.
+ * @returns The lazily-evaluable edge geometry (mid-parameter tangent).
+ */
+export declare function edgeGeom(edge: ShapeHandle): EntityGeom;
+/**
+ * Project a vertex handle into its `EntityGeom`.
+ *
+ * @param vertex - The kernel vertex handle to project.
+ * @returns The lazily-evaluable vertex geometry (no direction / type).
+ */
+export declare function vertexGeom(vertex: ShapeHandle): EntityGeom;
+/**
+ * Get the sub-entity handles of the given topological type from a shape.
+ *
+ * @param shape - The kernel handle to query.
+ * @param type - The topological type to enumerate.
+ * @returns The ordered kernel sub-shape handles of that type.
+ */
+export declare function subShapeHandles(shape: ShapeHandle, type: 'face' | 'edge' | 'vertex'): ShapeHandle[];
+//# sourceMappingURL=entity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAQ,MAAM,WAAW,CAAA;AAE9D,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9B;AA2BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,sDAAsD;AACtD,MAAM,MAAM,EAAE,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD,YAAY,EAAE,WAAW,EAAE,CAAA;AAM3B;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAA;IAChC,uFAAuF;IACvF,OAAO,EAAE,WAAW,CAAA;IACpB,qEAAqE;IACrE,IAAI,IAAI,MAAM,CAAA;IACd,sDAAsD;IACtD,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAA;IAChC,sDAAsD;IACtD,MAAM,IAAI,EAAE,CAAA;IACZ;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,EAAE,GAAG,IAAI,CAAA;IACxC,6EAA6E;IAC7E,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAA;CAC/B;AAID;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAWtD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,UAAU,EACb,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,GACjB,EAAE,CAgBJ;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAetD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,CAY1D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,EAAE,CAGnG"}

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

@@ -0,0 +1,167 @@
+/**
+ * cadquery-selectors/entity — projection of kernel handles into the geometric
+ * quantities the selector predicates need.
+ *
+ * Each helper mirrors the CadQuery shape method it stands in for (plan §4.3):
+ *   · `Vertex.Center()`      → vertex position
+ *   · `Edge.Center()`        → linear centre of mass (LinearProperties centroid)
+ *   · `Face.Center()`        → surface centre of mass (SurfaceProperties centroid)
+ *   · `Face.normalAt(None)`  → parametric surface normal at the uv midpoint,
+ *                              oriented outward via `containsPoint` on the owner
+ *   · `Edge.tangentAt()`     → curve tangent at the parameter midpoint,
+ *                              oriented along the edge parameter direction
+ *   · `Face/Edge.geomType()` → kernel surface/curve kind mapped to the CadQuery
+ *                              geom_LUT uppercased names
+ *
+ * These are deliberately decoupled from any single entity type so the
+ * predicates (predicates.ts) and the narrowing engine (resolve.ts) stay
+ * type-agnostic. All quantities are computed lazily by the caller via the
+ * projection object below.
+ *
+ * @platform occt — the projection resolves occt-wasm `ShapeHandle`s via the
+ * native kernel (`getKernel()`: getSubShapes / hashCode / isSame / bounds /
+ * surface & curve queries), so this module is occt-coupled by nature.
+ */
+import { getKernel } from '../../occt-kernel/occtKernel.js';
+const NAMED_GEOM = {
+    surface: {
+        plane: 'PLANE',
+        cylinder: 'CYLINDER',
+        cone: 'CONE',
+        sphere: 'SPHERE',
+        torus: 'TORUS',
+        bspline: 'BSPLINE',
+        bezier: 'BEZIER',
+        offset: 'OFFSET',
+        revolution: 'REVOLUTION',
+        extrusion: 'EXTRUSION',
+    },
+    curve: {
+        line: 'LINE',
+        circle: 'CIRCLE',
+        ellipse: 'ELLIPSE',
+        hyperbola: 'HYPERBOLA',
+        parabola: 'PARABOLA',
+        bspline: 'BSPLINE',
+        bezier: 'BEZIER',
+        offset: 'OFFSET',
+    },
+};
+/**
+ * Map a kernel surface-kind string to the CadQuery `geomType()` name.
+ *
+ * @param kind - The kernel surface kind (e.g. `plane`, `cylinder`, `torus`).
+ * @returns The uppercased CadQuery geometry name, or `OTHER` when unmapped.
+ */
+export function faceGeomType(kind) {
+    return NAMED_GEOM.surface[kind] ?? 'OTHER';
+}
+/**
+ * Map a kernel curve-kind string to the CadQuery `geomType()` name.
+ *
+ * @param kind - The kernel curve kind (e.g. `line`, `circle`, `bspline`).
+ * @returns The uppercased CadQuery geometry name, or `OTHER` when unmapped.
+ */
+export function edgeGeomType(kind) {
+    return NAMED_GEOM.curve[kind] ?? 'OTHER';
+}
+function v(v) {
+    return { x: v.x, y: v.y, z: v.z };
+}
+const kern = () => getKernel();
+/**
+ * Project a face handle into its `EntityGeom`.
+ *
+ * @param face - The kernel face handle to project.
+ * @returns The lazily-evaluable face geometry (normal oriented on demand).
+ */
+export function faceGeom(face) {
+    const k = kern();
+    return {
+        kind: 'face',
+        _handle: face,
+        hash: () => k.hashCode(face, 1e9),
+        same: (other) => k.isSame(face, other._handle),
+        center: () => v(k.getSurfaceCenterOfMass(face)),
+        direction: (owner) => orientedFaceNormal(k, face, owner),
+        geomType: () => faceGeomType(k.surfaceType(face)),
+    };
+}
+/**
+ * Orient a parametric face normal outward: offset probe → inside ⇒ flip.
+ *
+ * @param k - The active kernel instance used for surface/containment queries.
+ * @param face - The kernel face handle whose normal is oriented.
+ * @param owner - The owning shape handle used for the containment probe.
+ * @returns The outward-facing unit normal of `face`.
+ */
+export function orientedFaceNormal(k, face, owner) {
+    const uv = k.uvBounds(face);
+    const u = (uv.uMin + uv.uMax) / 2;
+    const vv = (uv.vMin + uv.vMax) / 2;
+    const n = k.surfaceNormal(face, u, vv);
+    const db = k.getBoundingBox(face);
+    const ext = [db.xmax - db.xmin, db.ymax - db.ymin, db.zmax - db.zmin];
+    const minExt = Math.min(...ext, 1);
+    const eps = minExt * 1e-3 + 1e-6;
+    const center = k.pointOnSurface(face, u, vv);
+    const probe = { x: center.x + n.x * eps, y: center.y + n.y * eps, z: center.z + n.z * eps };
+    // inside owner ⇒ the candidate normal points inward, so flip it.
+    if (k.containsPoint(owner, probe, 1e-9)) {
+        return { x: -n.x, y: -n.y, z: -n.z };
+    }
+    return v(n);
+}
+/**
+ * Project an edge handle into its `EntityGeom`.
+ *
+ * @param edge - The kernel edge handle to project.
+ * @returns The lazily-evaluable edge geometry (mid-parameter tangent).
+ */
+export function edgeGeom(edge) {
+    const k = kern();
+    const midParams = () => {
+        const cp = k.curveParameters(edge);
+        return (cp.first + cp.last) / 2;
+    };
+    return {
+        kind: 'edge',
+        _handle: edge,
+        hash: () => k.hashCode(edge, 1e9),
+        same: (other) => k.isSame(edge, other._handle),
+        center: () => v(k.curvePointAtParam(edge, midParams())),
+        direction: () => v(k.curveTangent(edge, midParams())),
+        geomType: () => edgeGeomType(k.curveType(edge)),
+    };
+}
+/**
+ * Project a vertex handle into its `EntityGeom`.
+ *
+ * @param vertex - The kernel vertex handle to project.
+ * @returns The lazily-evaluable vertex geometry (no direction / type).
+ */
+export function vertexGeom(vertex) {
+    const k = kern();
+    const p = k.vertexPosition(vertex);
+    return {
+        kind: 'vertex',
+        _handle: vertex,
+        hash: () => k.hashCode(vertex, 1e9),
+        same: (other) => k.isSame(vertex, other._handle),
+        center: () => v(p),
+        direction: () => null,
+        geomType: () => undefined,
+    };
+}
+/**
+ * Get the sub-entity handles of the given topological type from a shape.
+ *
+ * @param shape - The kernel handle to query.
+ * @param type - The topological type to enumerate.
+ * @returns The ordered kernel sub-shape handles of that type.
+ */
+export function subShapeHandles(shape, type) {
+    const k = kern();
+    return k.getSubShapes(shape, type);
+}
+//# sourceMappingURL=entity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/entity.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * cadquery-selectors/entity — projection of kernel handles into the geometric\n * quantities the selector predicates need.\n *\n * Each helper mirrors the CadQuery shape method it stands in for (plan §4.3):\n *   · `Vertex.Center()`      → vertex position\n *   · `Edge.Center()`        → linear centre of mass (LinearProperties centroid)\n *   · `Face.Center()`        → surface centre of mass (SurfaceProperties centroid)\n *   · `Face.normalAt(None)`  → parametric surface normal at the uv midpoint,\n *                              oriented outward via `containsPoint` on the owner\n *   · `Edge.tangentAt()`     → curve tangent at the parameter midpoint,\n *                              oriented along the edge parameter direction\n *   · `Face/Edge.geomType()` → kernel surface/curve kind mapped to the CadQuery\n *                              geom_LUT uppercased names\n *\n * These are deliberately decoupled from any single entity type so the\n * predicates (predicates.ts) and the narrowing engine (resolve.ts) stay\n * type-agnostic. All quantities are computed lazily by the caller via the\n * projection object below.\n *\n * @platform occt — the projection resolves occt-wasm `ShapeHandle`s via the\n * native kernel (`getKernel()`: getSubShapes / hashCode / isSame / bounds /\n * surface & curve queries), so this module is occt-coupled by nature.\n */\n\nimport { getKernel } from '../../occt-kernel/occtKernel'\nimport type { OcctKernel, ShapeHandle, Vec3 } from 'occt-wasm'\n\n/** Resolve the kernel geometry-kind → CadQuery LUT upcased name. */\nexport interface GeomKindMap {\n  surface: Record<string, string>\n  curve: Record<string, string>\n}\n\nconst NAMED_GEOM: { surface: Record<string, string>; curve: Record<string, string> } = {\n  surface: {\n    plane: 'PLANE',\n    cylinder: 'CYLINDER',\n    cone: 'CONE',\n    sphere: 'SPHERE',\n    torus: 'TORUS',\n    bspline: 'BSPLINE',\n    bezier: 'BEZIER',\n    offset: 'OFFSET',\n    revolution: 'REVOLUTION',\n    extrusion: 'EXTRUSION',\n  },\n  curve: {\n    line: 'LINE',\n    circle: 'CIRCLE',\n    ellipse: 'ELLIPSE',\n    hyperbola: 'HYPERBOLA',\n    parabola: 'PARABOLA',\n    bspline: 'BSPLINE',\n    bezier: 'BEZIER',\n    offset: 'OFFSET',\n  },\n}\n\n/**\n * Map a kernel surface-kind string to the CadQuery `geomType()` name.\n *\n * @param kind - The kernel surface kind (e.g. `plane`, `cylinder`, `torus`).\n * @returns The uppercased CadQuery geometry name, or `OTHER` when unmapped.\n */\nexport function faceGeomType(kind: string): string {\n  return NAMED_GEOM.surface[kind] ?? 'OTHER'\n}\n\n/**\n * Map a kernel curve-kind string to the CadQuery `geomType()` name.\n *\n * @param kind - The kernel curve kind (e.g. `line`, `circle`, `bspline`).\n * @returns The uppercased CadQuery geometry name, or `OTHER` when unmapped.\n */\nexport function edgeGeomType(kind: string): string {\n  return NAMED_GEOM.curve[kind] ?? 'OTHER'\n}\n\n/** World-space cartesian coordinates of an entity center point. */\nexport interface EntityCenter {\n  x: number\n  y: number\n  z: number\n}\n\n/** Plain 3-D vector in faijs' internal convention. */\nexport type P3 = { x: number; y: number; z: number }\n\nexport type { ShapeHandle }\n\nfunction v(v: Vec3 | P3): P3 {\n  return { x: v.x, y: v.y, z: v.z }\n}\n\n/**\n * The lazily-evaluable geometry of one candidate entity. Predicates only access\n * the fields they need so the heavy computation (surface normal, etc.) is only\n * paid for when a direction/parallel filter is actually applied.\n */\nexport interface EntityGeom {\n  kind: 'face' | 'edge' | 'vertex'\n  /** Internal kernel handle for identity comparison (not part of the public surface). */\n  _handle: ShapeHandle\n  /** Kernel handle box-identity hash (stable key across narrowing). */\n  hash(): number\n  /** Kernel handle `isSame(...)` equality predicate. */\n  same(other: EntityGeom): boolean\n  /** CadQuery `Shape.Center()` for this entity kind. */\n  center(): P3\n  /**\n   * The direction used by direction-motivated selectors: the outward normal for\n   * a face (requires the owning shape for orientation) or the mid-parameter\n   * tangent for an edge. Null for vertices (no usable direction, upstream\n   * `BaseSelector` drops them).\n   */\n  direction(owner: ShapeHandle): P3 | null\n  /** Face/Edge geometry type (upcased LUT name), or undefined for vertices. */\n  geomType(): string | undefined\n}\n\nconst kern = (): OcctKernel => getKernel() as unknown as OcctKernel\n\n/**\n * Project a face handle into its `EntityGeom`.\n *\n * @param face - The kernel face handle to project.\n * @returns The lazily-evaluable face geometry (normal oriented on demand).\n */\nexport function faceGeom(face: ShapeHandle): EntityGeom {\n  const k = kern()\n  return {\n    kind: 'face',\n    _handle: face,\n    hash: () => k.hashCode(face, 1e9),\n    same: (other: EntityGeom) => k.isSame(face, other._handle),\n    center: () => v(k.getSurfaceCenterOfMass(face)),\n    direction: (owner: ShapeHandle) => orientedFaceNormal(k, face, owner),\n    geomType: () => faceGeomType(k.surfaceType(face)),\n  }\n}\n\n/**\n * Orient a parametric face normal outward: offset probe → inside ⇒ flip.\n *\n * @param k - The active kernel instance used for surface/containment queries.\n * @param face - The kernel face handle whose normal is oriented.\n * @param owner - The owning shape handle used for the containment probe.\n * @returns The outward-facing unit normal of `face`.\n */\nexport function orientedFaceNormal(\n  k: OcctKernel,\n  face: ShapeHandle,\n  owner: ShapeHandle,\n): P3 {\n  const uv = k.uvBounds(face)\n  const u = (uv.uMin + uv.uMax) / 2\n  const vv = (uv.vMin + uv.vMax) / 2\n  const n = k.surfaceNormal(face, u, vv)\n  const db = k.getBoundingBox(face)\n  const ext = [db.xmax - db.xmin, db.ymax - db.ymin, db.zmax - db.zmin]\n  const minExt = Math.min(...ext, 1)\n  const eps = minExt * 1e-3 + 1e-6\n  const center = k.pointOnSurface(face, u, vv)\n  const probe = { x: center.x + n.x * eps, y: center.y + n.y * eps, z: center.z + n.z * eps }\n  // inside owner ⇒ the candidate normal points inward, so flip it.\n  if (k.containsPoint(owner, probe, 1e-9)) {\n    return { x: -n.x, y: -n.y, z: -n.z }\n  }\n  return v(n)\n}\n\n/**\n * Project an edge handle into its `EntityGeom`.\n *\n * @param edge - The kernel edge handle to project.\n * @returns The lazily-evaluable edge geometry (mid-parameter tangent).\n */\nexport function edgeGeom(edge: ShapeHandle): EntityGeom {\n  const k = kern()\n  const midParams = () => {\n    const cp = k.curveParameters(edge)\n    return (cp.first + cp.last) / 2\n  }\n  return {\n    kind: 'edge',\n    _handle: edge,\n    hash: () => k.hashCode(edge, 1e9),\n    same: (other: EntityGeom) => k.isSame(edge, other._handle),\n    center: () => v(k.curvePointAtParam(edge, midParams())),\n    direction: () => v(k.curveTangent(edge, midParams())),\n    geomType: () => edgeGeomType(k.curveType(edge)),\n  }\n}\n\n/**\n * Project a vertex handle into its `EntityGeom`.\n *\n * @param vertex - The kernel vertex handle to project.\n * @returns The lazily-evaluable vertex geometry (no direction / type).\n */\nexport function vertexGeom(vertex: ShapeHandle): EntityGeom {\n  const k = kern()\n  const p = k.vertexPosition(vertex)\n  return {\n    kind: 'vertex',\n    _handle: vertex,\n    hash: () => k.hashCode(vertex, 1e9),\n    same: (other: EntityGeom) => k.isSame(vertex, other._handle),\n    center: () => v(p),\n    direction: () => null,\n    geomType: () => undefined,\n  }\n}\n\n/**\n * Get the sub-entity handles of the given topological type from a shape.\n *\n * @param shape - The kernel handle to query.\n * @param type - The topological type to enumerate.\n * @returns The ordered kernel sub-shape handles of that type.\n */\nexport function subShapeHandles(shape: ShapeHandle, type: 'face' | 'edge' | 'vertex'): ShapeHandle[] {\n  const k = kern()\n  return k.getSubShapes(shape, type) as ShapeHandle[]\n}"]}

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

@@ -0,0 +1,33 @@
+/**
+ * cadquery-selectors/face — CadQuery face 字符串选择器
+ *
+ * 等价搬运自 `packages/faijs-cadquery/src/workplane.ts` 的 `resolveFaceSelector`
+ * （含其私有 `NAMED_VIEW_TO_AXIS`、`bboxMax`/`bboxMin`、`cad` 单例）。仅 import
+ * 路径改为 core 内部相对路径，逻辑逐行不变，零功能增减。
+ *
+ * @platform occt — face 选择对 BREP 面做枚举/比较，经 `getKernel()` 与
+ * `getBrepApi()` 访问 occt 原生内核（getSubShapes / surface 查询等）。
+ */
+import type { Shape } from '../../mesh/types.js';
+/**
+ * Resolve a CadQuery-style face selector string to the selected face's center
+ * point and outward normal.
+ *
+ * Supported forms: ">Z", "<Z", ">X", "<X", ">Y", "<Y", each with an optional
+ * CadQuery-style index suffix like ">Z[-2]", plus the six named views
+ * ("front"/"back"/"left"/"right"/"top"/"bottom") which are aliases for the
+ * corresponding axis selectors per cadquery/selectors.py:687-694.
+ * @param shape - Shape whose BREP faces are enumerated for selection.
+ * @param sel - Selector string, e.g. ">Z", "front", ">Z[-2]".
+ * @param centerOption - Optional center computation option forwarded to the
+ *   face-center evaluation.
+ * @returns Promise resolving to the selected face's center point and outward
+ *   normal.
+ * @throws Error when the selector matches no face or has unknown syntax
+ *   (never falls back silently).
+ */
+export declare function resolveFaceSelector(shape: Shape, sel: string, centerOption?: string): Promise<{
+    center: [number, number, number];
+    normal: [number, number, number];
+}>;
+//# sourceMappingURL=face.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"face.d.ts","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/face.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAuE7C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAsQjF"}