@faicad/faijs 0.33.2 → 0.35.8

package/dist/brep/engine/registry.d.ts

@@ -67,18 +67,44 @@ export declare function hasBrepEngine(): boolean;
  */
 export declare function isBrepEngineRegistered(id: string): boolean;
 /**
- * Resolve a BREP engine (asynchronously, resolving its provider; throws when not registered).
- * Omitting id uses the default (the first registrant).
- * @param id - optional engine registration id; defaults to the active engine.
+ * Resolve a **named** BREP engine (asynchronously, resolving its provider; throws
+ * when not registered). Assembly-time and diagnostic use only — library code must
+ * take the neutral surface via `getBrepApi()` or the platform face via
+ * `getOcctKernel()` / `getBrepKitKernel()`, never an engine by id.
+ *
+ * `id` is REQUIRED: this function means exactly one thing — "look up the engine
+ * registered under this id". Taking the current engine is a different intent and
+ * has its own exit, {@link getActiveBrepEngine} (symmetric with
+ * {@link getActiveBrepEngineId}).
+ *
+ * @param id - the engine registration id to resolve.
  * @returns a Promise resolving to the BREP engine instance.
  */
-export declare function getBrepEngine(id?: string): Promise<BrepEngine>;
+export declare function getBrepEngine(id: string): Promise<BrepEngine>;
+/**
+ * Resolve the **current** BREP engine (the first registrant, R8).
+ *
+ * The single way to ask "which engine is this session running on": symmetric with
+ * {@link getActiveBrepEngineId}, which answers the same question with the id only.
+ *
+ * @returns a Promise resolving to the active BREP engine instance.
+ * @throws when no BREP engine is registered (mesh mode / host not assembled).
+ */
+export declare function getActiveBrepEngine(): Promise<BrepEngine>;
 /**
- * Get a mesh engine (throws when not registered). Omitting id uses the default (the first registrant).
- * @param id - optional engine registration id; defaults to the active engine.
+ * Get a **named** mesh engine (throws when not registered). Assembly-time and
+ * diagnostic use; `id` is required for the same reason as {@link getBrepEngine}
+ * — taking the current engine is {@link getActiveMeshEngine}'s job.
+ * @param id - the mesh engine registration id to resolve.
  * @returns the mesh engine instance.
  */
-export declare function getMeshEngine(id?: string): MeshEngine;
+export declare function getMeshEngine(id: string): MeshEngine;
+/**
+ * Get the **current** mesh engine (the first registrant).
+ * @returns the active mesh engine instance.
+ * @throws when no mesh engine is registered.
+ */
+export declare function getActiveMeshEngine(): MeshEngine;
 /**
  * The current default BREP engine id (null when none is registered).
  * @returns the active BREP engine id or null.

package/dist/brep/engine/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/brep/engine/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;CACnC;AAED,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,eAAe,EAAE,gBAAgB,CAAA;CAC9D;AAWD;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CASjF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CASvE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAcpE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,CAOrD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,eAAe,EAAE,gBAAgB,GAAG,IAAI,CAKrF;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAOtD"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/brep/engine/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;CACnC;AAED,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,eAAe,EAAE,gBAAgB,CAAA;CAC9D;AAWD;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CASjF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CASvE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAUnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,UAAU,CAAC,CAK/D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAMpD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CAKhD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,eAAe,EAAE,gBAAgB,GAAG,IAAI,CAKrF;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAOtD"}

package/dist/brep/engine/registry.js

@@ -82,40 +82,71 @@ export function isBrepEngineRegistered(id) {
     return brepEngineProviders.has(id);
 }
 /**
- * Resolve a BREP engine (asynchronously, resolving its provider; throws when not registered).
- * Omitting id uses the default (the first registrant).
- * @param id - optional engine registration id; defaults to the active engine.
+ * Resolve a **named** BREP engine (asynchronously, resolving its provider; throws
+ * when not registered). Assembly-time and diagnostic use only — library code must
+ * take the neutral surface via `getBrepApi()` or the platform face via
+ * `getOcctKernel()` / `getBrepKitKernel()`, never an engine by id.
+ *
+ * `id` is REQUIRED: this function means exactly one thing — "look up the engine
+ * registered under this id". Taking the current engine is a different intent and
+ * has its own exit, {@link getActiveBrepEngine} (symmetric with
+ * {@link getActiveBrepEngineId}).
+ *
+ * @param id - the engine registration id to resolve.
  * @returns a Promise resolving to the BREP engine instance.
  */
 export async function getBrepEngine(id) {
-    const key = id ?? defaultBrepId;
-    if (key === null) {
-        throw new Error('[engine/registry] no BREP engine registered — call registerBrepEngine() during host assembly (R8)');
-    }
-    const cached = brepEngineCache.get(key);
+    const cached = brepEngineCache.get(id);
     if (cached)
         return cached;
-    const provider = brepEngineProviders.get(key);
+    const provider = brepEngineProviders.get(id);
     if (!provider) {
-        throw new Error(`[engine/registry] BREP engine '${key}' not registered`);
+        throw new Error(`[engine/registry] BREP engine '${id}' not registered`);
     }
     const engine = await provider();
-    brepEngineCache.set(key, engine);
+    brepEngineCache.set(id, engine);
     return engine;
 }
 /**
- * Get a mesh engine (throws when not registered). Omitting id uses the default (the first registrant).
- * @param id - optional engine registration id; defaults to the active engine.
+ * Resolve the **current** BREP engine (the first registrant, R8).
+ *
+ * The single way to ask "which engine is this session running on": symmetric with
+ * {@link getActiveBrepEngineId}, which answers the same question with the id only.
+ *
+ * @returns a Promise resolving to the active BREP engine instance.
+ * @throws when no BREP engine is registered (mesh mode / host not assembled).
+ */
+export async function getActiveBrepEngine() {
+    if (defaultBrepId === null) {
+        throw new Error('[engine/registry] no BREP engine registered — call registerBrepEngine() during host assembly (R8)');
+    }
+    return getBrepEngine(defaultBrepId);
+}
+/**
+ * Get a **named** mesh engine (throws when not registered). Assembly-time and
+ * diagnostic use; `id` is required for the same reason as {@link getBrepEngine}
+ * — taking the current engine is {@link getActiveMeshEngine}'s job.
+ * @param id - the mesh engine registration id to resolve.
  * @returns the mesh engine instance.
  */
 export function getMeshEngine(id) {
-    const key = id ?? defaultMeshId;
-    const engine = key === null ? undefined : meshEngines.get(key);
+    const engine = meshEngines.get(id);
     if (!engine) {
-        throw new Error(`[engine/registry] mesh engine '${key ?? '<none>'}' not registered`);
+        throw new Error(`[engine/registry] mesh engine '${id}' not registered`);
     }
     return engine;
 }
+/**
+ * Get the **current** mesh engine (the first registrant).
+ * @returns the active mesh engine instance.
+ * @throws when no mesh engine is registered.
+ */
+export function getActiveMeshEngine() {
+    if (defaultMeshId === null) {
+        throw new Error('[engine/registry] mesh engine \'<none>\' not registered');
+    }
+    return getMeshEngine(defaultMeshId);
+}
 /**
  * The current default BREP engine id (null when none is registered).
  * @returns the active BREP engine id or null.

package/dist/brep/engine/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/brep/engine/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyBH,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAA8B,CAAA;AACjE,MAAM,eAAe,GAAG,IAAI,GAAG,EAAsB,CAAA;AACrD,IAAI,aAAa,GAAkB,IAAI,CAAA;AAEvC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAsB,CAAA;AACjD,IAAI,aAAa,GAAkB,IAAI,CAAA;AAEvC,IAAI,MAAM,GAAG,KAAK,CAAA;AAElB;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,GAAG,IAAI,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU,EAAE,QAA4B;IACzE,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,oEAAoE,EAAE,uBAAuB,CAAC,CAAA;IAChH,CAAC;IACD,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,kCAAkC,EAAE,sBAAsB,CAAC,CAAA;IAC7E,CAAC;IACD,mBAAmB,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;IACrC,IAAI,aAAa,KAAK,IAAI;QAAE,aAAa,GAAG,EAAE,CAAA;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU,EAAE,MAAkB;IAC/D,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,oEAAoE,EAAE,uBAAuB,CAAC,CAAA;IAChH,CAAC;IACD,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,kCAAkC,EAAE,sBAAsB,CAAC,CAAA;IAC7E,CAAC;IACD,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;IAC3B,IAAI,aAAa,KAAK,IAAI;QAAE,aAAa,GAAG,EAAE,CAAA;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAU;IAC/C,OAAO,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,aAAa,KAAK,IAAI,CAAA;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAU;IAC/C,OAAO,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAW;IAC7C,MAAM,GAAG,GAAG,EAAE,IAAI,aAAa,CAAA;IAC/B,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,mGAAmG,CAAC,CAAA;IACtH,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACvC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAA;IACzB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,kBAAkB,CAAC,CAAA;IAC1E,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAA;IAC/B,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAChC,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,MAAM,GAAG,GAAG,EAAE,IAAI,aAAa,CAAA;IAC/B,MAAM,MAAM,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,IAAI,QAAQ,kBAAkB,CAAC,CAAA;IACtF,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IACjC,KAAK,MAAM,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,IAAI,MAAM,CAAC,SAAS;YAAE,OAAO,MAAM,CAAC,SAAS,CAAA;IAC/C,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B;IAC7C,mBAAmB,CAAC,KAAK,EAAE,CAAA;IAC3B,eAAe,CAAC,KAAK,EAAE,CAAA;IACvB,WAAW,CAAC,KAAK,EAAE,CAAA;IACnB,aAAa,GAAG,IAAI,CAAA;IACpB,aAAa,GAAG,IAAI,CAAA;IACpB,MAAM,GAAG,KAAK,CAAA;AAChB,CAAC","sourcesContent":["/**\n * engine/registry — BREP / mesh 双槽位注册表（§6.2，R8 构建时切换）\n *\n *\n * 首个注册者为默认，但两张表、两套 getter——\n * 这是 R2（双槽位正交：mesh 引擎与 BREP 引擎独立注册、单独切换）的直接落地。\n *\n * BREP 槽以「异步 provider」注册：引擎可能需异步初始化（occt-wasm 加载、\n * 外部内核 wasm 下载等），provider 只解析一次，结果缓存。\n *\n * 注册只发生在宿主启动装配期（R8）：构建时选定的适配器包在初始化时完成注册，\n * 之后注册表运行期只读。不提供运行时的 unregister / setDefault / 切换 API；\n * 装配完成后调用 freezeEngineRegistries() 冻结，冻结后任何注册尝试抛错（E2 验收）。\n */\n\nimport type { BrepEngineApi } from './primitives'\n\n/** BREP 引擎实例（槽位 1）：原语契约。引擎能做什么由实现本身决定，没有能力声明面。 */\nexport interface BrepEngine {\n  readonly id: string\n  readonly primitives: BrepEngineApi\n}\n\n/** BREP 引擎异步提供者（宿主装配时注册；引擎初始化完成后 resolve）。 */\nexport type BrepEngineProvider = () => Promise<BrepEngine>\n\n/**\n * mesh 引擎实例（槽位 2）——与 BREP 槽完全独立（R2）。\n *\n * `meshSolid`：可选的**网格实体后端**（方案 2026-10-01 §3.3）。提供它的 mesh\n * 引擎才能把网格文件导入成\"网格实体 + 近似拓扑\"。缺省（未提供）= 该 mesh 后端\n * 只做裸网格布尔，`load` 的 mesh 路径保持\"裸网格、无拓扑\"的历史行为。\n */\nexport interface MeshEngine {\n  readonly id: string\n  readonly meshSolid?: import('../mesh-solid').MeshSolidBackend\n}\n\nconst brepEngineProviders = new Map<string, BrepEngineProvider>()\nconst brepEngineCache = new Map<string, BrepEngine>()\nlet defaultBrepId: string | null = null\n\nconst meshEngines = new Map<string, MeshEngine>()\nlet defaultMeshId: string | null = null\n\nlet frozen = false\n\n/**\n * 冻结注册表：宿主启动装配完成后调用（R8）。\n * 冻结后任何 registerBrepEngine / registerMeshEngine 尝试抛错。\n * 已解析的引擎实例仍可读取（运行期只读，不冻结读取）。\n */\nexport function freezeEngineRegistries(): void {\n  frozen = true\n}\n\n/**\n * Register a BREP engine (slot 1). The first registrant automatically becomes the default.\n * @param id - the engine registration id.\n * @param provider - the async provider that resolves the engine instance.\n */\nexport function registerBrepEngine(id: string, provider: BrepEngineProvider): void {\n  if (frozen) {\n    throw new Error(`[engine/registry] registry frozen — cannot register BREP engine '${id}' after assembly (R8)`)\n  }\n  if (brepEngineProviders.has(id)) {\n    throw new Error(`[engine/registry] BREP engine '${id}' already registered`)\n  }\n  brepEngineProviders.set(id, provider)\n  if (defaultBrepId === null) defaultBrepId = id\n}\n\n/**\n * Register a mesh engine (slot 2). The first registrant automatically becomes the default.\n * @param id - the engine registration id.\n * @param engine - the engine instance to register.\n */\nexport function registerMeshEngine(id: string, engine: MeshEngine): void {\n  if (frozen) {\n    throw new Error(`[engine/registry] registry frozen — cannot register mesh engine '${id}' after assembly (R8)`)\n  }\n  if (meshEngines.has(id)) {\n    throw new Error(`[engine/registry] mesh engine '${id}' already registered`)\n  }\n  meshEngines.set(id, engine)\n  if (defaultMeshId === null) defaultMeshId = id\n}\n\n/**\n * Whether the given mesh engine is registered (used for idempotent adapter registration).\n * @param id - the mesh engine registration id to look up.\n * @returns true when the engine is registered.\n */\nexport function isMeshEngineRegistered(id: string): boolean {\n  return meshEngines.has(id)\n}\n\n/**\n * Whether a default BREP engine is registered (none → mesh mode, i.e. no BREP engine at all).\n * @returns true when a default BREP engine is registered.\n */\nexport function hasBrepEngine(): boolean {\n  return defaultBrepId !== null\n}\n\n/**\n * Whether the given BREP engine is registered (used for idempotent adapter registration).\n * @param id - the engine registration id to look up.\n * @returns true when the engine is registered.\n */\nexport function isBrepEngineRegistered(id: string): boolean {\n  return brepEngineProviders.has(id)\n}\n\n/**\n * Resolve a BREP engine (asynchronously, resolving its provider; throws when not registered).\n * Omitting id uses the default (the first registrant).\n * @param id - optional engine registration id; defaults to the active engine.\n * @returns a Promise resolving to the BREP engine instance.\n */\nexport async function getBrepEngine(id?: string): Promise<BrepEngine> {\n  const key = id ?? defaultBrepId\n  if (key === null) {\n    throw new Error('[engine/registry] no BREP engine registered — call registerBrepEngine() during host assembly (R8)')\n  }\n  const cached = brepEngineCache.get(key)\n  if (cached) return cached\n  const provider = brepEngineProviders.get(key)\n  if (!provider) {\n    throw new Error(`[engine/registry] BREP engine '${key}' not registered`)\n  }\n  const engine = await provider()\n  brepEngineCache.set(key, engine)\n  return engine\n}\n\n/**\n * Get a mesh engine (throws when not registered). Omitting id uses the default (the first registrant).\n * @param id - optional engine registration id; defaults to the active engine.\n * @returns the mesh engine instance.\n */\nexport function getMeshEngine(id?: string): MeshEngine {\n  const key = id ?? defaultMeshId\n  const engine = key === null ? undefined : meshEngines.get(key)\n  if (!engine) {\n    throw new Error(`[engine/registry] mesh engine '${key ?? '<none>'}' not registered`)\n  }\n  return engine\n}\n\n/**\n * The current default BREP engine id (null when none is registered).\n * @returns the active BREP engine id or null.\n */\nexport function getActiveBrepEngineId(): string | null {\n  return defaultBrepId\n}\n\n/**\n * The current default mesh engine id (null when none is registered).\n * @returns the active mesh engine id or null.\n */\nexport function getActiveMeshEngineId(): string | null {\n  return defaultMeshId\n}\n\n/**\n * 已装配的网格实体后端（方案 2026-10-01 §3.3）。\n *\n * 按**注册顺序**返回第一个声明了 `meshSolid` 的 mesh 引擎——不要求它就是\n * \"默认\" mesh 引擎（默认槽位今天无人注册，直接看默认槽会永远拿不到后端）。\n * 一个都没有 → `null`：这是宿主装配事实，不是错误。\n *\n * @returns the assembled mesh-solid backend, or null when none is available.\n */\nexport function getMeshSolidBackend(): import('../mesh-solid').MeshSolidBackend | null {\n  for (const engine of meshEngines.values()) {\n    if (engine.meshSolid) return engine.meshSolid\n  }\n  return null\n}\n\n/**\n * 仅测试用：重置注册表状态。\n *\n * R8 不提供运行期的 unregister / setDefault；此函数仅供 registry.test.ts\n * 重置模块级单例，不进入任何公共导出面（index/browser/node/sdk 均不 re-export）。\n */\nexport function __resetEngineRegistriesForTests(): void {\n  brepEngineProviders.clear()\n  brepEngineCache.clear()\n  meshEngines.clear()\n  defaultBrepId = null\n  defaultMeshId = null\n  frozen = false\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/brep/engine/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * engine/registry — BREP / mesh 双槽位注册表（§6.2，R8 构建时切换）\n *\n *\n * 首个注册者为默认，但两张表、两套 getter——\n * 这是 R2（双槽位正交：mesh 引擎与 BREP 引擎独立注册、单独切换）的直接落地。\n *\n * BREP 槽以「异步 provider」注册：引擎可能需异步初始化（occt-wasm 加载、\n * 外部内核 wasm 下载等），provider 只解析一次，结果缓存。\n *\n * 注册只发生在宿主启动装配期（R8）：构建时选定的适配器包在初始化时完成注册，\n * 之后注册表运行期只读。不提供运行时的 unregister / setDefault / 切换 API；\n * 装配完成后调用 freezeEngineRegistries() 冻结，冻结后任何注册尝试抛错（E2 验收）。\n */\n\nimport type { BrepEngineApi } from './primitives'\n\n/** BREP 引擎实例（槽位 1）：原语契约。引擎能做什么由实现本身决定，没有能力声明面。 */\nexport interface BrepEngine {\n  readonly id: string\n  readonly primitives: BrepEngineApi\n}\n\n/** BREP 引擎异步提供者（宿主装配时注册；引擎初始化完成后 resolve）。 */\nexport type BrepEngineProvider = () => Promise<BrepEngine>\n\n/**\n * mesh 引擎实例（槽位 2）——与 BREP 槽完全独立（R2）。\n *\n * `meshSolid`：可选的**网格实体后端**（方案 2026-10-01 §3.3）。提供它的 mesh\n * 引擎才能把网格文件导入成\"网格实体 + 近似拓扑\"。缺省（未提供）= 该 mesh 后端\n * 只做裸网格布尔，`load` 的 mesh 路径保持\"裸网格、无拓扑\"的历史行为。\n */\nexport interface MeshEngine {\n  readonly id: string\n  readonly meshSolid?: import('../mesh-solid').MeshSolidBackend\n}\n\nconst brepEngineProviders = new Map<string, BrepEngineProvider>()\nconst brepEngineCache = new Map<string, BrepEngine>()\nlet defaultBrepId: string | null = null\n\nconst meshEngines = new Map<string, MeshEngine>()\nlet defaultMeshId: string | null = null\n\nlet frozen = false\n\n/**\n * 冻结注册表：宿主启动装配完成后调用（R8）。\n * 冻结后任何 registerBrepEngine / registerMeshEngine 尝试抛错。\n * 已解析的引擎实例仍可读取（运行期只读，不冻结读取）。\n */\nexport function freezeEngineRegistries(): void {\n  frozen = true\n}\n\n/**\n * Register a BREP engine (slot 1). The first registrant automatically becomes the default.\n * @param id - the engine registration id.\n * @param provider - the async provider that resolves the engine instance.\n */\nexport function registerBrepEngine(id: string, provider: BrepEngineProvider): void {\n  if (frozen) {\n    throw new Error(`[engine/registry] registry frozen — cannot register BREP engine '${id}' after assembly (R8)`)\n  }\n  if (brepEngineProviders.has(id)) {\n    throw new Error(`[engine/registry] BREP engine '${id}' already registered`)\n  }\n  brepEngineProviders.set(id, provider)\n  if (defaultBrepId === null) defaultBrepId = id\n}\n\n/**\n * Register a mesh engine (slot 2). The first registrant automatically becomes the default.\n * @param id - the engine registration id.\n * @param engine - the engine instance to register.\n */\nexport function registerMeshEngine(id: string, engine: MeshEngine): void {\n  if (frozen) {\n    throw new Error(`[engine/registry] registry frozen — cannot register mesh engine '${id}' after assembly (R8)`)\n  }\n  if (meshEngines.has(id)) {\n    throw new Error(`[engine/registry] mesh engine '${id}' already registered`)\n  }\n  meshEngines.set(id, engine)\n  if (defaultMeshId === null) defaultMeshId = id\n}\n\n/**\n * Whether the given mesh engine is registered (used for idempotent adapter registration).\n * @param id - the mesh engine registration id to look up.\n * @returns true when the engine is registered.\n */\nexport function isMeshEngineRegistered(id: string): boolean {\n  return meshEngines.has(id)\n}\n\n/**\n * Whether a default BREP engine is registered (none → mesh mode, i.e. no BREP engine at all).\n * @returns true when a default BREP engine is registered.\n */\nexport function hasBrepEngine(): boolean {\n  return defaultBrepId !== null\n}\n\n/**\n * Whether the given BREP engine is registered (used for idempotent adapter registration).\n * @param id - the engine registration id to look up.\n * @returns true when the engine is registered.\n */\nexport function isBrepEngineRegistered(id: string): boolean {\n  return brepEngineProviders.has(id)\n}\n\n/**\n * Resolve a **named** BREP engine (asynchronously, resolving its provider; throws\n * when not registered). Assembly-time and diagnostic use only — library code must\n * take the neutral surface via `getBrepApi()` or the platform face via\n * `getOcctKernel()` / `getBrepKitKernel()`, never an engine by id.\n *\n * `id` is REQUIRED: this function means exactly one thing — \"look up the engine\n * registered under this id\". Taking the current engine is a different intent and\n * has its own exit, {@link getActiveBrepEngine} (symmetric with\n * {@link getActiveBrepEngineId}).\n *\n * @param id - the engine registration id to resolve.\n * @returns a Promise resolving to the BREP engine instance.\n */\nexport async function getBrepEngine(id: string): Promise<BrepEngine> {\n  const cached = brepEngineCache.get(id)\n  if (cached) return cached\n  const provider = brepEngineProviders.get(id)\n  if (!provider) {\n    throw new Error(`[engine/registry] BREP engine '${id}' not registered`)\n  }\n  const engine = await provider()\n  brepEngineCache.set(id, engine)\n  return engine\n}\n\n/**\n * Resolve the **current** BREP engine (the first registrant, R8).\n *\n * The single way to ask \"which engine is this session running on\": symmetric with\n * {@link getActiveBrepEngineId}, which answers the same question with the id only.\n *\n * @returns a Promise resolving to the active BREP engine instance.\n * @throws when no BREP engine is registered (mesh mode / host not assembled).\n */\nexport async function getActiveBrepEngine(): Promise<BrepEngine> {\n  if (defaultBrepId === null) {\n    throw new Error('[engine/registry] no BREP engine registered — call registerBrepEngine() during host assembly (R8)')\n  }\n  return getBrepEngine(defaultBrepId)\n}\n\n/**\n * Get a **named** mesh engine (throws when not registered). Assembly-time and\n * diagnostic use; `id` is required for the same reason as {@link getBrepEngine}\n * — taking the current engine is {@link getActiveMeshEngine}'s job.\n * @param id - the mesh engine registration id to resolve.\n * @returns the mesh engine instance.\n */\nexport function getMeshEngine(id: string): MeshEngine {\n  const engine = meshEngines.get(id)\n  if (!engine) {\n    throw new Error(`[engine/registry] mesh engine '${id}' not registered`)\n  }\n  return engine\n}\n\n/**\n * Get the **current** mesh engine (the first registrant).\n * @returns the active mesh engine instance.\n * @throws when no mesh engine is registered.\n */\nexport function getActiveMeshEngine(): MeshEngine {\n  if (defaultMeshId === null) {\n    throw new Error('[engine/registry] mesh engine \\'<none>\\' not registered')\n  }\n  return getMeshEngine(defaultMeshId)\n}\n\n/**\n * The current default BREP engine id (null when none is registered).\n * @returns the active BREP engine id or null.\n */\nexport function getActiveBrepEngineId(): string | null {\n  return defaultBrepId\n}\n\n/**\n * The current default mesh engine id (null when none is registered).\n * @returns the active mesh engine id or null.\n */\nexport function getActiveMeshEngineId(): string | null {\n  return defaultMeshId\n}\n\n/**\n * 已装配的网格实体后端（方案 2026-10-01 §3.3）。\n *\n * 按**注册顺序**返回第一个声明了 `meshSolid` 的 mesh 引擎——不要求它就是\n * \"默认\" mesh 引擎（默认槽位今天无人注册，直接看默认槽会永远拿不到后端）。\n * 一个都没有 → `null`：这是宿主装配事实，不是错误。\n *\n * @returns the assembled mesh-solid backend, or null when none is available.\n */\nexport function getMeshSolidBackend(): import('../mesh-solid').MeshSolidBackend | null {\n  for (const engine of meshEngines.values()) {\n    if (engine.meshSolid) return engine.meshSolid\n  }\n  return null\n}\n\n/**\n * 仅测试用：重置注册表状态。\n *\n * R8 不提供运行期的 unregister / setDefault；此函数仅供 registry.test.ts\n * 重置模块级单例，不进入任何公共导出面（index/browser/node/sdk 均不 re-export）。\n */\nexport function __resetEngineRegistriesForTests(): void {\n  brepEngineProviders.clear()\n  brepEngineCache.clear()\n  meshEngines.clear()\n  defaultBrepId = null\n  defaultMeshId = null\n  frozen = false\n}\n"]}

package/dist/brep/handle-bridge.d.ts

@@ -13,24 +13,23 @@
 import type { Shape } from '../mesh/types.js';
 import { fromBrep } from '../shape.js';
 import type { BrepEngineApi } from './engine/primitives.js';
-/**
- * Get the currently injected BREP kernel instance (untyped escape hatch).
- * @deprecated D12: this exit predates the engine-neutral L1 surface and its name
- * ("OCCT kernel") no longer matches what it returns — the current engine's raw
- * kernel, whatever engine that is. Prefer `getBrepApi()` (typed, engine-neutral,
- * same file) for neutral ops; platform-only code (L2 face) should use
- * `getOcctKernel()` (D3). Kept for compat-face bridging and existing tests.
- * @returns the current BREP engine's kernel instance.
- * @throws when the kernel is not ready (mesh mode or uninitialized) — never silently returns null.
- */
-export declare function getKernel(): unknown;
 /**
  * Get the current BREP engine as the **L1 core surface** (`BrepEngineApi`).
  *
- * 2026-09-24 narrowing plan（D12）：中立 op 的取内核唯一出口——取代
- * `getBackends().kernel.brep as BrepEngineApi` 的逐点断言。本文件是 L1 契约
- * 的注册点（`registerBrepEngine` 注入的就是 `BrepEngineApi` 实例），此处断言
- * 诚实；平台面（L1 之外的 occt 独有能力）仍走 `getOcctKernel()`（D3）。
+ * The one exit for neutral op code to reach the kernel: replaces the
+ * `getBackends().kernel.brep as BrepEngineApi` assertion at every call site.
+ *
+ * Why the `as` here is honest (and stays): this file is the L1 contract's
+ * registration point — `registerBrepEngine(id, provider)` is only ever handed a
+ * `BrepEngineApi` instance (`brep/engine/adapters/occt.ts` and `.../brepkit.ts`
+ * build theirs via `createOcctPrimitives()` / `createBrepkitPrimitives()`, both
+ * typed against `BrepEngineApi`), and `brep-chain.ts` stores exactly
+ * `engine.primitives` into the slot this reads. So the slot's value IS the L1
+ * surface; the cast removes the `unknown` the zero-dependency slot type must use.
+ * Platform-only code (whatever L1 does not expose) goes through
+ * `getOcctKernel()` / `getBrepKitKernel()` instead.
+ *
+ * The slot restriction above is pinned by `test/brep/l1-slot-provenance.test.ts`.
  *
  * @returns the current engine's L1 contract surface (`BrepEngineApi`) — typed, engine-neutral.
  * @throws when no BREP engine is registered (uninitialized) — never silently returns null.

package/dist/brep/handle-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-bridge.d.ts","sourceRoot":"","sources":["../../src/brep/handle-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAUxD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAMnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,IAAI,aAAa,CAQ1C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEhD;AAyBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAW3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAGjG"}
+{"version":3,"file":"handle-bridge.d.ts","sourceRoot":"","sources":["../../src/brep/handle-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAyCxD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,IAAI,aAAa,CAQ1C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEhD;AAyBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAW3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAGjG"}

package/dist/brep/handle-bridge.js

@@ -12,36 +12,56 @@
  */
 import { getBackends } from '../runtime-state.js';
 import { fromBrep } from '../shape.js';
+/** The slot value as stored by the runtime — `unknown` because the slot type is dependency-free. */
+function rawKernelOrNull() {
+    return getBackends().kernel.brep;
+}
 /**
- * Get the currently injected BREP kernel instance (untyped escape hatch).
- * @deprecated D12: this exit predates the engine-neutral L1 surface and its name
- * ("OCCT kernel") no longer matches what it returns — the current engine's raw
- * kernel, whatever engine that is. Prefer `getBrepApi()` (typed, engine-neutral,
- * same file) for neutral ops; platform-only code (L2 face) should use
- * `getOcctKernel()` (D3). Kept for compat-face bridging and existing tests.
+ * The current engine's raw kernel instance (untyped) — **internal to this file**.
+ *
+ * This is NOT an exit. The "current engine's raw kernel" is whatever the current
+ * engine happens to be (occt today, brepkit in a weapp session) and carries no
+ * contract; the former exported `getKernel()` was deleted (2026-10-14) because its
+ * name claimed OCCT while its value was engine-dependent, colliding with
+ * `occt-kernel/occtKernel.ts`'s `getKernel()` (the real OCCT platform face). The
+ * error message below was engine-neutralised for the same reason.
+ *
+ * Only `meshHandle` uses it, to call the kernel's own `meshShape` — a kernel-level
+ * method every engine must have (it is what materialises a handle into a Shape).
+ *
  * @returns the current BREP engine's kernel instance.
  * @throws when the kernel is not ready (mesh mode or uninitialized) — never silently returns null.
  */
-export function getKernel() {
-    const kernel = getBackends().kernel.brep;
+function requireRawKernel() {
+    const kernel = rawKernelOrNull();
     if (!kernel) {
-        throw new Error('[faijs/bridge] OCCT kernel not available: BREP operations require an initialized kernel');
+        throw new Error('[faijs/bridge] BREP kernel not available: tessellating a handle requires an initialized kernel');
     }
     return kernel;
 }
 /**
  * Get the current BREP engine as the **L1 core surface** (`BrepEngineApi`).
  *
- * 2026-09-24 narrowing plan（D12）：中立 op 的取内核唯一出口——取代
- * `getBackends().kernel.brep as BrepEngineApi` 的逐点断言。本文件是 L1 契约
- * 的注册点（`registerBrepEngine` 注入的就是 `BrepEngineApi` 实例），此处断言
- * 诚实；平台面（L1 之外的 occt 独有能力）仍走 `getOcctKernel()`（D3）。
+ * The one exit for neutral op code to reach the kernel: replaces the
+ * `getBackends().kernel.brep as BrepEngineApi` assertion at every call site.
+ *
+ * Why the `as` here is honest (and stays): this file is the L1 contract's
+ * registration point — `registerBrepEngine(id, provider)` is only ever handed a
+ * `BrepEngineApi` instance (`brep/engine/adapters/occt.ts` and `.../brepkit.ts`
+ * build theirs via `createOcctPrimitives()` / `createBrepkitPrimitives()`, both
+ * typed against `BrepEngineApi`), and `brep-chain.ts` stores exactly
+ * `engine.primitives` into the slot this reads. So the slot's value IS the L1
+ * surface; the cast removes the `unknown` the zero-dependency slot type must use.
+ * Platform-only code (whatever L1 does not expose) goes through
+ * `getOcctKernel()` / `getBrepKitKernel()` instead.
+ *
+ * The slot restriction above is pinned by `test/brep/l1-slot-provenance.test.ts`.
  *
  * @returns the current engine's L1 contract surface (`BrepEngineApi`) — typed, engine-neutral.
  * @throws when no BREP engine is registered (uninitialized) — never silently returns null.
  */
 export function getBrepApi() {
-    const kernel = getBackends().kernel.brep;
+    const kernel = rawKernelOrNull();
     if (!kernel) {
         throw new Error('[faijs/bridge] BREP engine API not available: BREP operations require an initialized engine');
     }
@@ -88,7 +108,7 @@ function requireHandle(handle, caller) {
  */
 export function meshHandle(handle, opts) {
     requireHandle(handle, 'meshHandle');
-    const kernel = getKernel();
+    const kernel = requireRawKernel();
     const mesh = kernel.meshShape(handle, {
         linearDeflection: opts?.linearDeflection ?? 0.1,
         angularDeflection: (2 * Math.PI) / Math.max(3, opts?.segments ?? 32),

package/dist/brep/handle-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"handle-bridge.js","sourceRoot":"","sources":["../../src/brep/handle-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAWnC;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAA;IACxC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAA;IAC5G,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAA;IACxC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,6FAA6F,CAC9F,CAAA;IACH,CAAC;IACD,OAAO,MAAuB,CAAA;AAChC,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAA8B,CAAC,UAAU,KAAK,IAAI,CAAA;AACnG,CAAC;AAED;0CAC0C;AAC1C,SAAS,YAAY,CAAC,CAAU;IAC9B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA;AACjD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,MAAe,EAAE,MAAc;IACpD,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,kBAAkB,MAAM,yDAAyD;YAC/E,kCAAkC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,IAAI;YAC9E,wDAAwD,CAC3D,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe,EAAE,IAAwB;IAClE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,SAAS,EAAoB,CAAA;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE;QACpC,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,IAAI,GAAG;QAC/C,iBAAiB,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC;KACrE,CAAC,CAAA;IACF,OAAO;QACL,SAAS,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,SAA8B,CAAC;QAChE,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,OAA4B,CAAC;KAC5D,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe,EAAE,IAAwB;IAClE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AAC9D,CAAC","sourcesContent":["/**\n * handle-bridge — OCCT 句柄 → faijs Shape 的 SDK 桥接（B1）\n *\n *\n * 第三方库要造 BREP 产物，需要\"OCCT handle → mesh\"。SDK 绝不能 import\n * heavy 几何库（会把它们拉进 SDK bundle，违反 `src/sdk.test.ts` 的零 heavy\n * 依赖守卫）。本文件在**新建的零依赖模块**中实现，直接调运行时注入的\n * `kernel.meshShape`。\n *\n * 依赖约束（硬性）：只允许 import `runtime-state`、`api/shape`、type-only\n * `mesh/types`——任何新增依赖必须保持 dist/sdk.js 零 heavy 依赖守卫通过。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBackends } from '../runtime-state'\nimport { fromBrep } from '../shape'\nimport type { BrepEngineApi } from './engine/primitives'\n\n/** 结构化内核接口（不 import occt-wasm，只做结构匹配，避免 heavy 依赖） */\ninterface MeshableKernel {\n  meshShape(\n    handle: unknown,\n    opts: { linearDeflection: number; angularDeflection: number },\n  ): { positions: ArrayLike<number>; indices: ArrayLike<number> }\n}\n\n/**\n * Get the currently injected BREP kernel instance (untyped escape hatch).\n * @deprecated D12: this exit predates the engine-neutral L1 surface and its name\n * (\"OCCT kernel\") no longer matches what it returns — the current engine's raw\n * kernel, whatever engine that is. Prefer `getBrepApi()` (typed, engine-neutral,\n * same file) for neutral ops; platform-only code (L2 face) should use\n * `getOcctKernel()` (D3). Kept for compat-face bridging and existing tests.\n * @returns the current BREP engine's kernel instance.\n * @throws when the kernel is not ready (mesh mode or uninitialized) — never silently returns null.\n */\nexport function getKernel(): unknown {\n  const kernel = getBackends().kernel.brep\n  if (!kernel) {\n    throw new Error('[faijs/bridge] OCCT kernel not available: BREP operations require an initialized kernel')\n  }\n  return kernel\n}\n\n/**\n * Get the current BREP engine as the **L1 core surface** (`BrepEngineApi`).\n *\n * 2026-09-24 narrowing plan（D12）：中立 op 的取内核唯一出口——取代\n * `getBackends().kernel.brep as BrepEngineApi` 的逐点断言。本文件是 L1 契约\n * 的注册点（`registerBrepEngine` 注入的就是 `BrepEngineApi` 实例），此处断言\n * 诚实；平台面（L1 之外的 occt 独有能力）仍走 `getOcctKernel()`（D3）。\n *\n * @returns the current engine's L1 contract surface (`BrepEngineApi`) — typed, engine-neutral.\n * @throws when no BREP engine is registered (uninitialized) — never silently returns null.\n */\nexport function getBrepApi(): BrepEngineApi {\n  const kernel = getBackends().kernel.brep\n  if (!kernel) {\n    throw new Error(\n      '[faijs/bridge] BREP engine API not available: BREP operations require an initialized engine',\n    )\n  }\n  return kernel as BrepEngineApi\n}\n\n/**\n * Options controlling how a handle is tessellated.\n */\nexport interface MeshHandleOptions {\n  /** linear deflection (mm), default 0.1 — matches the built-in ops (src/brep/brep-ops.ts:27). */\n  linearDeflection?: number\n  /** angular segment count, default 32 — angularDeflection = 2π / segments. */\n  segments?: number\n}\n\n/**\n * OCC 句柄身份契约判别（单一真源）。\n *\n * occt-wasm 的 `handle()` 工厂（occtWasm helpers.ts:25）构造的句柄对象\n * 统一携带 `__occtWasm: true`。本叶子是 faijs 侧唯一允许的判据：\n * define-op 的 `wrapBrepOne` 用它区分\"几何句柄\"与\"纯数据记录\"，本文件\n * `fromHandle`/`meshHandle` 入口用它做形态断言。禁止在其他文件硬编码\n * `'__occtWasm' in v` 字符串直查——句柄/数据判定的任何新消费点都必须引用本叶子。\n * @param v - 待判别的值。\n * @returns `true` 当且仅当 `v` 是携带 `__occtWasm: true` 标记的句柄对象。\n */\nexport function isOcctHandle(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && (v as { __occtWasm?: unknown }).__occtWasm === true\n}\n\n/** 合法句柄输入：branded numeric id（occt-wasm 的 `ShapeHandle` 运行时形态）或\n *  `__occtWasm` 标记对象（`handle()` 工厂产物）。 */\nfunction isHandleLike(v: unknown): boolean {\n  return typeof v === 'number' || isOcctHandle(v)\n}\n\n/**\n * 入口形态断言：拒绝把纯数据记录当句柄三角化。\n * 纯数据记录（无 `__occtWasm` 标记的 plain object，如 sheetmetal part 数据）\n * 必须在 SDK 边界被显式拒绝（E_BAD_HANDLE），而不是在 kernel 深处以\n * `OcctError: meshShape: Invalid shape ID 0` 崩溃——define-op 的 wrapBrepOne\n * 已在第一道透传过滤，本断言是第二道防线（防未来未带标记的新句柄形态漏网）。\n */\nfunction requireHandle(handle: unknown, caller: string): void {\n  if (!isHandleLike(handle)) {\n    throw new Error(\n      `[faijs/bridge] ${caller}: E_BAD_HANDLE: expected an OCCT handle (numeric id or ` +\n        `__occtWasm-tagged object); got ${handle === null ? 'null' : typeof handle}. ` +\n        `Plain data records must not be tessellated as handles.`,\n    )\n  }\n}\n\n/**\n * Tessellate an OCCT handle into a Shape (without registering a BREP slot).\n * @param handle - the OCCT solid handle to tessellate (numeric id or `__occtWasm`-tagged object).\n * @param opts - optional tessellation options.\n * @returns the tessellated Shape.\n */\nexport function meshHandle(handle: unknown, opts?: MeshHandleOptions): Shape {\n  requireHandle(handle, 'meshHandle')\n  const kernel = getKernel() as MeshableKernel\n  const mesh = kernel.meshShape(handle, {\n    linearDeflection: opts?.linearDeflection ?? 0.1,\n    angularDeflection: (2 * Math.PI) / Math.max(3, opts?.segments ?? 32),\n  })\n  return {\n    positions: new Float32Array(mesh.positions as ArrayLike<number>),\n    indices: new Uint32Array(mesh.indices as ArrayLike<number>),\n  }\n}\n\n/**\n * Default path (recommended): tessellate + register the BREP slot in one step.\n * Equivalent to meshHandle(h) + fromBrep(sh, { solid: h }).\n * Library authors only fall back to the meshHandle + fromBrep combination when\n * they need custom tessellation precision.\n * @param handle - the OCCT solid handle to bridge (numeric id or `__occtWasm`-tagged object).\n * @param opts - optional tessellation options.\n * @returns the registered Shape, as returned by fromBrep.\n */\nexport function fromHandle(handle: unknown, opts?: MeshHandleOptions): ReturnType<typeof fromBrep> {\n  requireHandle(handle, 'fromHandle')\n  return fromBrep(meshHandle(handle, opts), { solid: handle })\n}\n"]}
+{"version":3,"file":"handle-bridge.js","sourceRoot":"","sources":["../../src/brep/handle-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAWnC,oGAAoG;AACpG,SAAS,eAAe;IACtB,OAAO,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAA;AAClC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,gBAAgB;IACvB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAA;IAChC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAA;IAChC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,6FAA6F,CAC9F,CAAA;IACH,CAAC;IACD,OAAO,MAAuB,CAAA;AAChC,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAA8B,CAAC,UAAU,KAAK,IAAI,CAAA;AACnG,CAAC;AAED;0CAC0C;AAC1C,SAAS,YAAY,CAAC,CAAU;IAC9B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA;AACjD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,MAAe,EAAE,MAAc;IACpD,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,kBAAkB,MAAM,yDAAyD;YAC/E,kCAAkC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,IAAI;YAC9E,wDAAwD,CAC3D,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe,EAAE,IAAwB;IAClE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,gBAAgB,EAAoB,CAAA;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE;QACpC,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,IAAI,GAAG;QAC/C,iBAAiB,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC;KACrE,CAAC,CAAA;IACF,OAAO;QACL,SAAS,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,SAA8B,CAAC;QAChE,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,OAA4B,CAAC;KAC5D,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe,EAAE,IAAwB;IAClE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AAC9D,CAAC","sourcesContent":["/**\n * handle-bridge — OCCT 句柄 → faijs Shape 的 SDK 桥接（B1）\n *\n *\n * 第三方库要造 BREP 产物，需要\"OCCT handle → mesh\"。SDK 绝不能 import\n * heavy 几何库（会把它们拉进 SDK bundle，违反 `src/sdk.test.ts` 的零 heavy\n * 依赖守卫）。本文件在**新建的零依赖模块**中实现，直接调运行时注入的\n * `kernel.meshShape`。\n *\n * 依赖约束（硬性）：只允许 import `runtime-state`、`api/shape`、type-only\n * `mesh/types`——任何新增依赖必须保持 dist/sdk.js 零 heavy 依赖守卫通过。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBackends } from '../runtime-state'\nimport { fromBrep } from '../shape'\nimport type { BrepEngineApi } from './engine/primitives'\n\n/** 结构化内核接口（不 import occt-wasm，只做结构匹配，避免 heavy 依赖） */\ninterface MeshableKernel {\n  meshShape(\n    handle: unknown,\n    opts: { linearDeflection: number; angularDeflection: number },\n  ): { positions: ArrayLike<number>; indices: ArrayLike<number> }\n}\n\n/** The slot value as stored by the runtime — `unknown` because the slot type is dependency-free. */\nfunction rawKernelOrNull(): unknown {\n  return getBackends().kernel.brep\n}\n\n/**\n * The current engine's raw kernel instance (untyped) — **internal to this file**.\n *\n * This is NOT an exit. The \"current engine's raw kernel\" is whatever the current\n * engine happens to be (occt today, brepkit in a weapp session) and carries no\n * contract; the former exported `getKernel()` was deleted (2026-10-14) because its\n * name claimed OCCT while its value was engine-dependent, colliding with\n * `occt-kernel/occtKernel.ts`'s `getKernel()` (the real OCCT platform face). The\n * error message below was engine-neutralised for the same reason.\n *\n * Only `meshHandle` uses it, to call the kernel's own `meshShape` — a kernel-level\n * method every engine must have (it is what materialises a handle into a Shape).\n *\n * @returns the current BREP engine's kernel instance.\n * @throws when the kernel is not ready (mesh mode or uninitialized) — never silently returns null.\n */\nfunction requireRawKernel(): unknown {\n  const kernel = rawKernelOrNull()\n  if (!kernel) {\n    throw new Error(\n      '[faijs/bridge] BREP kernel not available: tessellating a handle requires an initialized kernel',\n    )\n  }\n  return kernel\n}\n\n/**\n * Get the current BREP engine as the **L1 core surface** (`BrepEngineApi`).\n *\n * The one exit for neutral op code to reach the kernel: replaces the\n * `getBackends().kernel.brep as BrepEngineApi` assertion at every call site.\n *\n * Why the `as` here is honest (and stays): this file is the L1 contract's\n * registration point — `registerBrepEngine(id, provider)` is only ever handed a\n * `BrepEngineApi` instance (`brep/engine/adapters/occt.ts` and `.../brepkit.ts`\n * build theirs via `createOcctPrimitives()` / `createBrepkitPrimitives()`, both\n * typed against `BrepEngineApi`), and `brep-chain.ts` stores exactly\n * `engine.primitives` into the slot this reads. So the slot's value IS the L1\n * surface; the cast removes the `unknown` the zero-dependency slot type must use.\n * Platform-only code (whatever L1 does not expose) goes through\n * `getOcctKernel()` / `getBrepKitKernel()` instead.\n *\n * The slot restriction above is pinned by `test/brep/l1-slot-provenance.test.ts`.\n *\n * @returns the current engine's L1 contract surface (`BrepEngineApi`) — typed, engine-neutral.\n * @throws when no BREP engine is registered (uninitialized) — never silently returns null.\n */\nexport function getBrepApi(): BrepEngineApi {\n  const kernel = rawKernelOrNull()\n  if (!kernel) {\n    throw new Error(\n      '[faijs/bridge] BREP engine API not available: BREP operations require an initialized engine',\n    )\n  }\n  return kernel as BrepEngineApi\n}\n\n/**\n * Options controlling how a handle is tessellated.\n */\nexport interface MeshHandleOptions {\n  /** linear deflection (mm), default 0.1 — matches the built-in ops (src/brep/brep-ops.ts:27). */\n  linearDeflection?: number\n  /** angular segment count, default 32 — angularDeflection = 2π / segments. */\n  segments?: number\n}\n\n/**\n * OCC 句柄身份契约判别（单一真源）。\n *\n * occt-wasm 的 `handle()` 工厂（occtWasm helpers.ts:25）构造的句柄对象\n * 统一携带 `__occtWasm: true`。本叶子是 faijs 侧唯一允许的判据：\n * define-op 的 `wrapBrepOne` 用它区分\"几何句柄\"与\"纯数据记录\"，本文件\n * `fromHandle`/`meshHandle` 入口用它做形态断言。禁止在其他文件硬编码\n * `'__occtWasm' in v` 字符串直查——句柄/数据判定的任何新消费点都必须引用本叶子。\n * @param v - 待判别的值。\n * @returns `true` 当且仅当 `v` 是携带 `__occtWasm: true` 标记的句柄对象。\n */\nexport function isOcctHandle(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && (v as { __occtWasm?: unknown }).__occtWasm === true\n}\n\n/** 合法句柄输入：branded numeric id（occt-wasm 的 `ShapeHandle` 运行时形态）或\n *  `__occtWasm` 标记对象（`handle()` 工厂产物）。 */\nfunction isHandleLike(v: unknown): boolean {\n  return typeof v === 'number' || isOcctHandle(v)\n}\n\n/**\n * 入口形态断言：拒绝把纯数据记录当句柄三角化。\n * 纯数据记录（无 `__occtWasm` 标记的 plain object，如 sheetmetal part 数据）\n * 必须在 SDK 边界被显式拒绝（E_BAD_HANDLE），而不是在 kernel 深处以\n * `OcctError: meshShape: Invalid shape ID 0` 崩溃——define-op 的 wrapBrepOne\n * 已在第一道透传过滤，本断言是第二道防线（防未来未带标记的新句柄形态漏网）。\n */\nfunction requireHandle(handle: unknown, caller: string): void {\n  if (!isHandleLike(handle)) {\n    throw new Error(\n      `[faijs/bridge] ${caller}: E_BAD_HANDLE: expected an OCCT handle (numeric id or ` +\n        `__occtWasm-tagged object); got ${handle === null ? 'null' : typeof handle}. ` +\n        `Plain data records must not be tessellated as handles.`,\n    )\n  }\n}\n\n/**\n * Tessellate an OCCT handle into a Shape (without registering a BREP slot).\n * @param handle - the OCCT solid handle to tessellate (numeric id or `__occtWasm`-tagged object).\n * @param opts - optional tessellation options.\n * @returns the tessellated Shape.\n */\nexport function meshHandle(handle: unknown, opts?: MeshHandleOptions): Shape {\n  requireHandle(handle, 'meshHandle')\n  const kernel = requireRawKernel() as MeshableKernel\n  const mesh = kernel.meshShape(handle, {\n    linearDeflection: opts?.linearDeflection ?? 0.1,\n    angularDeflection: (2 * Math.PI) / Math.max(3, opts?.segments ?? 32),\n  })\n  return {\n    positions: new Float32Array(mesh.positions as ArrayLike<number>),\n    indices: new Uint32Array(mesh.indices as ArrayLike<number>),\n  }\n}\n\n/**\n * Default path (recommended): tessellate + register the BREP slot in one step.\n * Equivalent to meshHandle(h) + fromBrep(sh, { solid: h }).\n * Library authors only fall back to the meshHandle + fromBrep combination when\n * they need custom tessellation precision.\n * @param handle - the OCCT solid handle to bridge (numeric id or `__occtWasm`-tagged object).\n * @param opts - optional tessellation options.\n * @returns the registered Shape, as returned by fromBrep.\n */\nexport function fromHandle(handle: unknown, opts?: MeshHandleOptions): ReturnType<typeof fromBrep> {\n  requireHandle(handle, 'fromHandle')\n  return fromBrep(meshHandle(handle, opts), { solid: handle })\n}\n"]}

package/dist/brep/primitives-brep.js

@@ -18,7 +18,7 @@
  *
  * 坐标系：Z-up、毫米，与 mesh 路径一致。
  */
-import { getBrepEngine } from './engine/registry.js';
+import { getActiveBrepEngine } from './engine/registry.js';
 import { primitiveToBrepSolid } from '../primitives/brep-primitives.js';
 import { clampNRad } from '../mesh/types.js';
 import { DEFAULT_LINEAR_DEFLECTION } from '../tolerance.js';
@@ -45,7 +45,7 @@ function segmentsToAngularDeflection(segments) {
  * @returns Shape（三角化 mesh，供显示用）
  */
 async function brepToShape(type, params, segments) {
-    const kernel = (await getBrepEngine()).primitives;
+    const kernel = (await getActiveBrepEngine()).primitives;
     // 用升级后的 primitiveToBrepSolid 构造 OCCT 精确实体
     const result = primitiveToBrepSolid(kernel, type, params);
     const solid = result.solid;

package/dist/brep/primitives-brep.js.map

@@ -1 +1 @@
-{"version":3,"file":"primitives-brep.js","sourceRoot":"","sources":["../../src/brep/primitives-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAWpE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAA;AAE7B,eAAe;AAEf;;;;;GAKG;AACH,SAAS,2BAA2B,CAAC,QAAiB;IACpD,MAAM,IAAI,GAAG,QAAQ,IAAI,EAAE,CAAA,CAAC,wCAAwC;IACpE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,WAAW,CACxB,IAAuD,EACvD,MAA4E,EAC5E,QAAiB;IAEjB,MAAM,MAAM,GAAkB,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,UAAU,CAAA;IAEhE,0CAA0C;IAC1C,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;IACzD,MAAM,KAAK,GAAe,MAAM,CAAC,KAAK,CAAA;IAEtC,IAAI,CAAC;QACH,cAAc;QACd,MAAM,iBAAiB,GAAG,2BAA2B,CAAC,QAAQ,CAAC,CAAA;QAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE;YACnC,gBAAgB,EAAE,yBAAyB,CAAC,EAAE,CAAC,EAAE,CAAC;YAClD,iBAAiB;SAClB,CAAC,CAAA;QAEF,0BAA0B;QAC1B,OAAO;YACL,SAAS,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC;YAC3C,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;SACvC,CAAA;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACvB,CAAC;AACH,CAAC;AAED,sBAAsB;AAEtB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAiB;IAC7C,OAAO,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAoB;IACrD,OAAO,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;AAC/E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAsB;IACzD,OAAO,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;AACjF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAkB;IACjD,OAAO,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAmB;IACjD,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AACrC,CAAC","sourcesContent":["/**\n * mesh BREP 基本体 API — 使用 OCCT 精确实体构造\n *\n * See docs/api-contract.md §8 (dual-path geometry contract: BREP / Mesh).\n *\n * 与 `primitives.ts`（mesh 路径）的对照：\n * - mesh 路径：THREE 参数几何 → geoToManifoldMesh → Shape（三角网格近似）\n * - BREP 路径：OCCT 精确实体 → meshShape 三角化 → Shape（显示用 mesh，但底层是精确 BREP）\n *\n * 两条路径返回的 Shape 都是 { positions, indices }，显示管线一致。\n * 差异仅在：BREP 路径的 Shape 由 OCCT 精确实体三角化得到，曲面精度更高；\n * 且导出 STEP 时可短路为原生 ADVANCED_FACE（而非 faceted 重建）。\n *\n * segments 参数的处理：\n * - mesh 路径：segments 直接控制 THREE 几何体的分段数\n * - BREP 路径：segments 转换为 angularDeflection（≈2π/segments）控制 OCCT 三角化精度\n *   BREP 实体本身是精确的，segments 只影响显示 mesh 的精度\n *\n * 坐标系：Z-up、毫米，与 mesh 路径一致。\n */\n\nimport { getBrepEngine } from './engine/registry'\nimport { primitiveToBrepSolid } from '../primitives/brep-primitives'\nimport type { BrepHandle } from './engine/types'\nimport type { BrepEngineApi } from './engine/primitives'\nimport type {\n  Shape,\n  BoxParams,\n  SphereParams,\n  CylinderParams,\n  ConeParams,\n  WedgeParams,\n} from '../mesh/types'\nimport { clampNRad } from '../mesh/types'\nimport { DEFAULT_LINEAR_DEFLECTION } from '../tolerance'\nimport { mm } from '../units'\n\n// ─── 内部工具 ───\n\n/**\n * 将 segments 数转换为 OCCT meshShape 的 angularDeflection。\n *\n * segments=32 → angularDeflection≈2π/32≈0.196 rad\n * segments 越大，三角化越精细。\n */\nfunction segmentsToAngularDeflection(segments?: number): number {\n  const segs = segments ?? 64 // 缺省 64（= brepjs standard 等效，§5.0/§5.1）\n  return (2 * Math.PI) / Math.max(3, segs)\n}\n\n/**\n * 用 OCCT 构造 BREP 实体并三角化为 Shape。\n *\n * 内部流程：注册表取当前 BREP 引擎 → primitiveToBrepSolid（引擎精确构造）→ meshShape → release → Shape\n *\n * @param type      primitive 类型（cube/sphere/cylinder/cone/wedge）\n * @param params    完整参数对象\n * @param segments  可选分段数（影响三角化精度，不影响 BREP 实体精度）\n * @returns Shape（三角化 mesh，供显示用）\n */\nasync function brepToShape(\n  type: 'cube' | 'sphere' | 'cylinder' | 'cone' | 'wedge',\n  params: BoxParams | SphereParams | CylinderParams | ConeParams | WedgeParams,\n  segments?: number,\n): Promise<Shape> {\n  const kernel: BrepEngineApi = (await getBrepEngine()).primitives\n\n  // 用升级后的 primitiveToBrepSolid 构造 OCCT 精确实体\n  const result = primitiveToBrepSolid(kernel, type, params)\n  const solid: BrepHandle = result.solid\n\n  try {\n    // 三角化为显示 mesh\n    const angularDeflection = segmentsToAngularDeflection(segments)\n    const mesh = kernel.meshShape(solid, {\n      linearDeflection: DEFAULT_LINEAR_DEFLECTION.as(mm),\n      angularDeflection,\n    })\n\n    // 返回 Shape（与 mesh 路径格式一致）\n    return {\n      positions: new Float32Array(mesh.positions),\n      indices: new Uint32Array(mesh.indices),\n    }\n  } finally {\n    kernel.release(solid)\n  }\n}\n\n// ─── BREP 创建 API ───\n\n/**\n * Create a box with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the box parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function boxBrep(params: BoxParams): Promise<Shape> {\n  return brepToShape('cube', params)\n}\n\n/**\n * Create a sphere with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the sphere parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function sphereBrep(params: SphereParams): Promise<Shape> {\nreturn brepToShape('sphere', params, clampNRad(params.nRad ?? params.segments))\n}\n\n/**\n * Create a cylinder with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the cylinder parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function cylinderBrep(params: CylinderParams): Promise<Shape> {\nreturn brepToShape('cylinder', params, clampNRad(params.nRad ?? params.segments))\n}\n\n/**\n * Create a cone with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the cone parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function coneBrep(params: ConeParams): Promise<Shape> {\nreturn brepToShape('cone', params, clampNRad(params.nRad ?? params.segments))\n}\n\n/**\n * Create a wedge with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the wedge parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function wedgeBrep(params: WedgeParams): Promise<Shape> {\n  return brepToShape('wedge', params)\n}\n"]}
+{"version":3,"file":"primitives-brep.js","sourceRoot":"","sources":["../../src/brep/primitives-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAWpE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAA;AAE7B,eAAe;AAEf;;;;;GAKG;AACH,SAAS,2BAA2B,CAAC,QAAiB;IACpD,MAAM,IAAI,GAAG,QAAQ,IAAI,EAAE,CAAA,CAAC,wCAAwC;IACpE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,WAAW,CACxB,IAAuD,EACvD,MAA4E,EAC5E,QAAiB;IAEjB,MAAM,MAAM,GAAkB,CAAC,MAAM,mBAAmB,EAAE,CAAC,CAAC,UAAU,CAAA;IAEtE,0CAA0C;IAC1C,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;IACzD,MAAM,KAAK,GAAe,MAAM,CAAC,KAAK,CAAA;IAEtC,IAAI,CAAC;QACH,cAAc;QACd,MAAM,iBAAiB,GAAG,2BAA2B,CAAC,QAAQ,CAAC,CAAA;QAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE;YACnC,gBAAgB,EAAE,yBAAyB,CAAC,EAAE,CAAC,EAAE,CAAC;YAClD,iBAAiB;SAClB,CAAC,CAAA;QAEF,0BAA0B;QAC1B,OAAO;YACL,SAAS,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC;YAC3C,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;SACvC,CAAA;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACvB,CAAC;AACH,CAAC;AAED,sBAAsB;AAEtB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAiB;IAC7C,OAAO,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAoB;IACrD,OAAO,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;AAC/E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAsB;IACzD,OAAO,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;AACjF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAkB;IACjD,OAAO,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAmB;IACjD,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AACrC,CAAC","sourcesContent":["/**\n * mesh BREP 基本体 API — 使用 OCCT 精确实体构造\n *\n * See docs/api-contract.md §8 (dual-path geometry contract: BREP / Mesh).\n *\n * 与 `primitives.ts`（mesh 路径）的对照：\n * - mesh 路径：THREE 参数几何 → geoToManifoldMesh → Shape（三角网格近似）\n * - BREP 路径：OCCT 精确实体 → meshShape 三角化 → Shape（显示用 mesh，但底层是精确 BREP）\n *\n * 两条路径返回的 Shape 都是 { positions, indices }，显示管线一致。\n * 差异仅在：BREP 路径的 Shape 由 OCCT 精确实体三角化得到，曲面精度更高；\n * 且导出 STEP 时可短路为原生 ADVANCED_FACE（而非 faceted 重建）。\n *\n * segments 参数的处理：\n * - mesh 路径：segments 直接控制 THREE 几何体的分段数\n * - BREP 路径：segments 转换为 angularDeflection（≈2π/segments）控制 OCCT 三角化精度\n *   BREP 实体本身是精确的，segments 只影响显示 mesh 的精度\n *\n * 坐标系：Z-up、毫米，与 mesh 路径一致。\n */\n\nimport { getActiveBrepEngine } from './engine/registry'\nimport { primitiveToBrepSolid } from '../primitives/brep-primitives'\nimport type { BrepHandle } from './engine/types'\nimport type { BrepEngineApi } from './engine/primitives'\nimport type {\n  Shape,\n  BoxParams,\n  SphereParams,\n  CylinderParams,\n  ConeParams,\n  WedgeParams,\n} from '../mesh/types'\nimport { clampNRad } from '../mesh/types'\nimport { DEFAULT_LINEAR_DEFLECTION } from '../tolerance'\nimport { mm } from '../units'\n\n// ─── 内部工具 ───\n\n/**\n * 将 segments 数转换为 OCCT meshShape 的 angularDeflection。\n *\n * segments=32 → angularDeflection≈2π/32≈0.196 rad\n * segments 越大，三角化越精细。\n */\nfunction segmentsToAngularDeflection(segments?: number): number {\n  const segs = segments ?? 64 // 缺省 64（= brepjs standard 等效，§5.0/§5.1）\n  return (2 * Math.PI) / Math.max(3, segs)\n}\n\n/**\n * 用 OCCT 构造 BREP 实体并三角化为 Shape。\n *\n * 内部流程：注册表取当前 BREP 引擎 → primitiveToBrepSolid（引擎精确构造）→ meshShape → release → Shape\n *\n * @param type      primitive 类型（cube/sphere/cylinder/cone/wedge）\n * @param params    完整参数对象\n * @param segments  可选分段数（影响三角化精度，不影响 BREP 实体精度）\n * @returns Shape（三角化 mesh，供显示用）\n */\nasync function brepToShape(\n  type: 'cube' | 'sphere' | 'cylinder' | 'cone' | 'wedge',\n  params: BoxParams | SphereParams | CylinderParams | ConeParams | WedgeParams,\n  segments?: number,\n): Promise<Shape> {\n  const kernel: BrepEngineApi = (await getActiveBrepEngine()).primitives\n\n  // 用升级后的 primitiveToBrepSolid 构造 OCCT 精确实体\n  const result = primitiveToBrepSolid(kernel, type, params)\n  const solid: BrepHandle = result.solid\n\n  try {\n    // 三角化为显示 mesh\n    const angularDeflection = segmentsToAngularDeflection(segments)\n    const mesh = kernel.meshShape(solid, {\n      linearDeflection: DEFAULT_LINEAR_DEFLECTION.as(mm),\n      angularDeflection,\n    })\n\n    // 返回 Shape（与 mesh 路径格式一致）\n    return {\n      positions: new Float32Array(mesh.positions),\n      indices: new Uint32Array(mesh.indices),\n    }\n  } finally {\n    kernel.release(solid)\n  }\n}\n\n// ─── BREP 创建 API ───\n\n/**\n * Create a box with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the box parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function boxBrep(params: BoxParams): Promise<Shape> {\n  return brepToShape('cube', params)\n}\n\n/**\n * Create a sphere with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the sphere parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function sphereBrep(params: SphereParams): Promise<Shape> {\nreturn brepToShape('sphere', params, clampNRad(params.nRad ?? params.segments))\n}\n\n/**\n * Create a cylinder with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the cylinder parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function cylinderBrep(params: CylinderParams): Promise<Shape> {\nreturn brepToShape('cylinder', params, clampNRad(params.nRad ?? params.segments))\n}\n\n/**\n * Create a cone with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the cone parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function coneBrep(params: ConeParams): Promise<Shape> {\nreturn brepToShape('cone', params, clampNRad(params.nRad ?? params.segments))\n}\n\n/**\n * Create a wedge with an OCCT exact solid and tessellate it into a Shape.\n * @param params - the wedge parameters.\n * @returns a Promise resolving to the tessellated Shape.\n */\nexport async function wedgeBrep(params: WedgeParams): Promise<Shape> {\n  return brepToShape('wedge', params)\n}\n"]}

package/dist/brep/text/text-to-solid.d.ts

@@ -6,7 +6,8 @@
  *
  * 与 brepjs 的差异：
  * - brepjs 用 BlueprintSketcher 构造 wire → 本项目直接用 kernel.makeLineEdge / makeBezierEdge
- * - brepjs 用 organiseBlueprints 处理孔洞 → 本项目用 makeFace 直接构建（OCCT 自动处理内孔）
+ * - brepjs 用 organiseBlueprints 处理孔洞 → 本项目用 makeFace + addHolesInFace 构建
+ *   （分类复用 `primitives/svg/svg-path.ts` 的共享 classifyNested，与 svg-to-solid 同源）
  * - brepjs 用 sketchOnPlane → 本项目直接在 XY 平面构造然后按需变换
  *
  * opentype.js 路径命令 → OCCT edge 映射：
@@ -15,9 +16,40 @@
  * - C (cubicBezier) → kernel.makeBezierEdge([p0, cp1, cp2, p1])
  * - Q (quadraticBezier) → 转换为三次贝塞尔后用 makeBezierEdge
  * - Z (closePath) → 闭合 wire
+ *
+ * 孔洞与组合（2026-10-13 修复，见 .agents/notes/ 对应 Agent Note）：
+ * - 旧实现把每个闭合轮廓独立 makeFace+extrude 后**逐个 fuse**：带孔字符（如 'o'）
+ *   的外轮廓体与内孔体被布尔并成一个实心体，孔被填实（与 mesh 路径的 evenodd
+ *   分类不一致）；且 fuse 次数 = 轮廓数，'Hello' ≈ 8-12 次 OCCT 布尔是文字建模
+ *   10 秒级耗时的主因。
+ * - 新实现：轮廓按包含关系分组（外轮廓 + 其孔，复用 classifyNested）→ 每组
+ *   makeFace(outer) + addHolesInFace(holes) 挖孔 → extrude；字符间互不重叠，
+ *   **用 makeCompound 组合（零布尔成本）**，不再逐轮廓 fuse。
  */
 import type { BrepHandle } from '../engine/types.js';
 import type { BrepEngineApi } from '../engine/primitives.js';
+import { type SvgPoint2 } from '../../primitives/svg/svg-path.js';
+/**
+ * 将文字转换为 OCCT wire 数组（每个闭合轮廓一个 wire），并带各轮廓的
+ * 采样点集（供 classifyNested 做外轮廓/孔洞分类）。
+ *
+ * 采样点：L 端点、Q/C 按 CURVE_SAMPLES 段离散化 —— 与 mesh 路径
+ * `opentypePathToContours` 的曲线折线化同一用途（bbox/质心/射线判定精度足够）。
+ *
+ * @param kernel OCCT 内核
+ * @param text 文字字符串
+ * @param options 配置选项
+ * @returns 每个闭合轮廓的 { wire, points }（points 为 Y-up 采样点）
+ */
+export declare function textBlueprintsDetailed(kernel: BrepEngineApi, text: string, options?: {
+    startX?: number;
+    startY?: number;
+    fontSize?: number;
+    fontFamily?: string;
+}): {
+    wire: BrepHandle;
+    points: SvgPoint2[];
+}[];
 /**
  * 将文字转换为 OCCT wire 数组（每个闭合轮廓一个 wire）。
  *
@@ -33,12 +65,17 @@ export declare function textBlueprints(kernel: BrepEngineApi, text: string, opti
     fontFamily?: string;
 }): BrepHandle[];
 /**
- * 将文字转换为 OCCT 3D solid（face → extrude → fuse）。
+ * 将文字转换为 OCCT 3D solid（face → 挖孔 → extrude → compound）。
+ *
+ * 每个「外轮廓 + 其孔」分组生成一个空心 solid（makeFace + addHolesInFace）；
+ * 分组之间（字符 / 互不重叠的独立轮廓，如 'i' 的点）**用 makeCompound 组合**，
+ * 不做布尔融合 —— 字符水平排列互不重叠，compound 语义正确且零布尔成本
+ * （旧实现逐个 fuse 是文字建模慢的根因，也是 'o' 孔被填实的成因）。
  *
  * @param kernel OCCT 内核
  * @param text 文字字符串
  * @param options 配置选项
- * @returns BrepHandle（合并后的 solid）
+ * @returns BrepHandle（单组时为 solid，多组时为 compound）
  */
 export declare function textToSolid(kernel: BrepEngineApi, text: string, options: {
     fontSize?: number;

package/dist/brep/text/text-to-solid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-to-solid.d.ts","sourceRoot":"","sources":["../../../src/brep/text/text-to-solid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAwDzD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACf,GACL,UAAU,EAAE,CAwHd;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;CACd,GACA,UAAU,CAqCZ"}
+{"version":3,"file":"text-to-solid.d.ts","sourceRoot":"","sources":["../../../src/brep/text/text-to-solid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAIzD,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,+BAA+B,CAAA;AAuEtC;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACf,GACL;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,EAAE,CA6I7C;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACf,GACL,UAAU,EAAE,CAEd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;CACd,GACA,UAAU,CAmDZ"}