parapoly-runtime 1.0.3 → 1.0.5

package/instructions/code3d-project-workspace.instructions.md

@@ -1,3 +1,6 @@
+> ⚠️ 注意：
+> 不要直接调用 Text2CADFacade.ts 的实现或接口信息。所有对 Text2CADFacade 的使用应通过规范化的 API 或文档说明进行，避免直接依赖其源码细节。
+
 ---
 applyTo: "**/code3d-workspace-config.json,**/package.json,**/*.code3d.js,**/.parapoly/**,**/*.part3d"
 description: "Code3D / 国基3D / 国基CAD 项目工作区规范：项目结构、模块编写、编译流程、多色组装等。适用于所有 code3d 3D 建模项目。"
@@ -289,6 +292,9 @@ let main = function(params) {
 2. **入口文件不需要外层包裹** — 根文档本身不会被 `run_node`
 3. **需要 boolean 运算的部件放在 `booleanEnabled=true` 的内层 group**
 4. **每个颜色一个 `push_node(..., true)` group** — 同色部件可合并到一个 group
+5. **有效布尔运算必须使用一个容器** — 也就是把 `union / difference / intersection` 相关几何放进同一个 `push_node(..., true)` 组里；不要把差集/交集拆散到多个独立 group，否则结果不稳定或不生效。
+
+> 经验总结：示例里的布尔运算之所以有效，是因为它把所有布尔体都收拢在同一个容器 group 中执行。后续新建布尔模型时，优先遵循这一模式。
 
 ### 禁止：嵌套 booleanEnabled=true group 做差集
 
@@ -1040,4 +1046,4 @@ if (!is_visible) {
 
 **与 Extrude/Revolve IIFE 的配合**：Extrude/Revolve IIFE 中会先 `node.set_archived(false)` 取消归档（用于 `to_wires_shape()`），操作完成后再 `node.set_archived(true)` 重新归档。即使在 sketch 创建时已设置 `archived=true`，操作 IIFE 的归档流程仍然正确执行。
 
-**`end_sketch()` 后的 `selected_node`**：`PartBlock3dDocument.end_sketch()` 将 `this.selected_node = node`（sketch 节点），因此 `block3d_doc.selected_node.set_archived(true)` 可以正确定位到刚创建的 sketch。
+**`end_sketch()` 后的 `selected_node`**：`PartBlock3dDocument.end_sketch()` 将 `this.selected_node = node`（sketch 节点），因此 `block3d_doc.selected_node.set_archived(true)` 可以正确定位到刚创建的 sketch.

package/instructions/code3d.instructions.md

@@ -1,3 +1,6 @@
+> ⚠️ 注意：
+> 不要直接调用 Text2CADFacade.ts 的实现或接口信息。所有对 Text2CADFacade 的使用应通过规范化的 API 或文档说明进行，避免直接依赖其源码细节。
+
 ---
 applyTo: "**/*.code3d.js"
 ---
@@ -50,6 +53,15 @@ The last parameter is always a color string (typically `"#ffc658"`).
 - `"difference"` — Subtract/cut shape from parent
 - `"intersection"` — Keep only overlapping region
 
+**经验总结（重要）**：有效的布尔运算必须放在同一个容器组内执行。也就是用一层 `push_node(..., true)` 包住需要做 `union / difference / intersection` 的几何，再把子形体放进去；不要把布尔体散落到多个独立 group 里，否则差集/交集往往不会按预期生效。
+
+```javascript
+block3d_doc.push_node("union", "object1", "#ffc658", true)
+  block3d_doc.box("union", 1, 1, 1, "#ffc658")
+  block3d_doc.sphere("difference", 0.6, "#ffc658")
+block3d_doc.pop_node()
+```
+
 ### Grouping (push_node / pop_node)
 
 ```javascript

package/instructions/part3d.instructions.md

@@ -1,3 +1,6 @@
+> ⚠️ 注意：
+> 不要直接调用 Text2CADFacade.ts 的实现或接口信息。所有对 Text2CADFacade 的使用应通过规范化的 API 或文档说明进行，避免直接依赖其源码细节。
+
 ---
 applyTo: "**/*.part3d,**/*.part3d.js,**/Part3dCodeExporter*,**/part3d/**"
 description: "Part3D 编辑器与 .part3d/.part3d.js 导出规范。涵盖 Part3dCodeExporter 架构、特征导出模式、sketch 可见度、颜色格式等。"

package/instructions/sketch3d.instructions.md

@@ -1,3 +1,6 @@
+> ⚠️ 注意：
+> 不要直接调用 Text2CADFacade.ts 的实现或接口信息。所有对 Text2CADFacade 的使用应通过规范化的 API 或文档说明进行，避免直接依赖其源码细节。
+
 ---
 applyTo: "**/*.sketch3d,**/*.sketch3d.js,**/SketchCodeExporter*,**/sketch3d/**,**/sketch_node/**"
 description: "Sketch3D 草图编辑器与 .sketch3d/.sketch3d.js 导出规范。涵盖 SketchCodeExporter 架构、几何导出、约束导出、可见度处理等。"
@@ -245,4 +248,4 @@ sk_node.set_op_feature_node_id(id)
 2. 确认约束类型：`packages/parapoly-runtime/src/types/Constraint.ts` (`ConstraintType` 枚举)
 3. 确认 API：`packages/parapoly-runtime/src/part/PartBlock3dDocument.ts` 中的 sketch 方法
 4. 更新 `SketchCodeExporter.ts` 中对应分支
-5. 注意约束参数的 `second >= 0` 条件判断（区分单目/双目约束）
+5. 注意约束参数的 `second >= 0` 条件判断（区分单目/双目约束)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parapoly-runtime",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "ParaPoly 3D CAD Runtime — CSG modeling, sketch, and project builder",
   "main": "./parapoly_runtime.js",
   "types": "./parapoly_runtime.d.ts",

package/parapoly_runtime.d.ts

@@ -1,5 +1,5 @@
 declare module "parapoly-runtime" {
-  export type BooleanOp = "union" | "cut" | "common";
+  export type BooleanOp = "union" | "difference" | "intersection";
 
   export type AxisDir = "x" | "y" | "z";
 
@@ -33,6 +33,18 @@ declare module "parapoly-runtime" {
     private _parameters: Array<FacadeParameter>;
     private _lastBuildResult: FacadeBuildResult | null;
     constructor();
+    /**
+     * Reset the facade to a fresh empty document.
+     */
+    reset(): this;
+    /**
+     * Load a .part3d JSON payload into the facade document.
+     */
+    loadPart3d(json: string, recompile?: boolean, color?: string): this;
+    /**
+     * Load a .block3d JSON payload into the facade document.
+     */
+    loadBlock3d(json: string): this;
     /**
      * Create a box centered at origin. Parameters: x-size, y-size (height), z-size (depth).
      */
@@ -1735,7 +1747,7 @@ declare module "parapoly-runtime" {
     public getChildByIndex(index: number): Node;
     public clearComponents(): void;
     public clearChildren(): void;
-    public static visit_node(node: Node, preVisitMethod?: any, postVisitMethod?: any): void;
+    public static visit_node(node: Node, preVisitMethod?: ((node: any) => void) | null, postVisitMethod?: ((node: any) => void) | null): void;
     public to_json(options?: ObjectToJsonOptions): any;
     public clone(options?: ObjectToJsonOptions, to_options?: ObjectToJsonOptions): Node;
     public static create(obj?: any, options?: ObjectCreateOptions): Node;
@@ -2958,6 +2970,7 @@ declare module "parapoly-runtime" {
     exportDocData = "exportDocData",
     exportLog = "exportLog",
     exportBlocklyPngs = "exportBlocklyPngs",
+    exportCode3dJs = "exportCode3dJs",
     export3mf = "export3mf",
     exportStep = "exportStep",
     exportIges = "exportIges",