release: 2.2.8

CHANGELOG.md

@@ -6,6 +6,10 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and
 
 ## Unreleased
 
+## 2.2.8 — 2026-11-09
+
+User-facing notes: [`docs/updates/2.2.8.md`](docs/updates/2.2.8.md).
+
 ### Added
 - Editing existing curves and surfaces as recorded operations (the SDK half of NURBS control-point editing):
   `inspect_curve_rcurvedata` / `inspect_surface_rsurfacedata` read degree, poles, weights, knots and trimming;

docs/skill/SKILL.md

@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
 license: Apache-2.0
 metadata:
   project: simplecadapi
-  version: 2.2.7
+  version: 2.2.8
   package-name: simplecadapi
-  package-version: 2.2.7
+  package-version: 2.2.8
 ---
 
 # SimpleCAD SDK Skill

docs/skill/references/SDK_OVERVIEW.md

@@ -1,8 +1,8 @@
 # SDK Overview
 
 - Project: `simplecadapi`
-- Version: `2.2.7`
-- Package distribution: `simplecadapi==2.2.7`
+- Version: `2.2.8`
+- Package distribution: `simplecadapi==2.2.8`
 
 ## What this skill bundles
 

docs/updates/2.2.8.md

@@ -0,0 +1,74 @@
+# 2.2.8 Update Notes
+
+This release brings the SDK what an editor and an agent need to work on a model that already exists: workplanes, stable
+references, bodies that split and flow on, and edits to existing curves and surfaces. The editor gets a new viewport. Manual
+modelling in the editor is built but not offered yet; this release ships the editor in code mode.
+
+## Models you can point at
+
+* **Workplanes are values.** `make_workplane_*_rworkplane` (from a face, points, an axis, a midplane, normal to a curve) and
+  `make_workplane_offset_rworkplane` (moved and turned relative to a workplane or a named plane) are recorded and replay from
+  model JSON; `make_sketch_rsketch(plane=wp)` sketches on one.
+* **References are code.** `scad.ref` writes a readable, parseable reference to a face, edge, vertex or solid, and
+  `ql.ref` uses one as a query predicate. A reference resolves through the recorded history (transform, scale, offset, draft,
+  booleans), and a failing one reports its candidates and a repair.
+* **Tags follow their entity.** A tag is a view over the recorded history. When a cut splits a body, the pieces are named
+  `<tag>.split<i>` and a `TagSplitWarning` says so (also in `sca run` and the editor); fillet, chamfer and the other
+  one-shape operations apply to every piece.
+* **A Part holds one solid or several named bodies.** A cut that splits a body gives its pieces. `set_body_appearance_rpart`
+  sets a body's display colour, opacity and name, and a face's name is a tag.
+
+## Operations
+
+* **Edit what exists.** `inspect_curve_rcurvedata` / `inspect_surface_rsurfacedata` read degree, poles, weights, knots and
+  trimming; `set_*_poles`, `move_*_poles`, `set_*_weights`, `insert_*_knot`, `elevate_*_degree`, `convert_to_bspline_*` and
+  `rebuild_curve_*` / `rebuild_surface_*` return a new shape, record a topology delta and replay. `sample_curve_rcurvature`
+  and `sample_surface_risocurves` give an editor a curvature comb and isocurves.
+* **Faces.** `press_pull_rsolid` pulls a flat face out (its prism joined) or presses it in (cut) with one signed distance;
+  `inset_face_rsolid` imprints a face's loops moved inside it, so inset then pull builds steps and bosses without a sketch.
+* **Sketch.** B-splines in the sketch editor, with trim, extend and crossings (also against ellipses);
+  `fillet_corner_rsketch`, `chamfer_corner_rsketch`, `project_rsketch`, `trim_rsketch`, `extend_rsketch`,
+  `diff_sketch_rsketchdiff`; the sketch's profiles and crossings come from the SDK (`inspect_sketch_rsketchprofiles`).
+* **Assemblies.** `explode_rassembly`.
+* **An edge is taken wherever a wire is** (a sweep path, a loft section, a face boundary): the wire of that one edge, recorded
+  as `make_wire_from_edges_rwire`. `loft_rshell` of open sections gives the surface between two curves, and
+  `sew_faces_rshell` takes faces and shells.
+* **Every operation says what its parameters mean.** Signatures use typed meanings (length, angle, point, direction, count,
+  selection, choice), and `simplecadapi.catalog` and `sca ops` read them straight from the bindings.
+
+## The editor
+
+* **A new viewport.** It renders with three's WebGPURenderer (WebGL 2 where WebGPU is missing, or with `?webgl`): one
+  multisampled pass, ambient occlusion, edges drawn over faces with a depth bias along the view ray. A part seen up close is
+  tessellated again by the kernel from its in-memory BREP (`POST /api/preview/refine`) until its chords are under half a pixel;
+  parts several nodes draw are instanced; picks go through BVHs; surfaces are shaded from their exact normals.
+* **English and Chinese**, following the browser unless chosen in the header.
+* **Selections are `scad.ref` lines**, written into the notebook.
+* **Code mode only.** Manual modelling (features, sketches and assemblies by buttons and dialogs) is built and kept in the
+  tree, switched off by `MANUAL_MODE` in `editor-web/src/lib/manual-mode.ts` until it has a plan of its own. This release has no
+  mode switch, command bar or manual keys.
+* A notebook with no part yet is no fault: `find_product` raises `NoProductYetError` (a `ProductNotFoundError`), the editor
+  previews an empty model, and `sca new` and the editor's *new* make an empty part notebook (the parametric cylinder is
+  `--kind sample`).
+
+## Behaviour changes
+
+* `make_wire_from_edges_rwire` takes its edges in any order, and an edge that touches none of the others is an error instead
+  of being left out. The error report of the face operations given an open or non-wire input is now the open-wire report with
+  the measured gap.
+* `sew_faces_rshell` raises `TypeError` for anything that is not a face or a shell.
+
+## Fixed
+
+* A stable reference into a face or shell body (no solid) resolves; it raised `cannot resolve QL selector scope`.
+* A restored value counts a history-derived tag witness once; an input that stays in the result is preserved even when it
+  also generates.
+* A periodic B-spline's crossings are wrapped into one period before cutting.
+* The editor page is served with no cache, so a rebuilt UI loads on the next visit.
+
+## For contributors
+
+* The README is rewritten, with the comparison data and the two arms in the editor; `tools/make_readme_charts.py` draws its
+  charts.
+* Seven test files from before the C++ port that had been committed again by mistake are removed, and the goldens of the
+  edge-as-wire change are updated.

docs/updates/2.2.8.zh-CN.md

@@ -0,0 +1,62 @@
+# 2.2.8 更新说明
+
+这一版让 SDK 具备了编辑器和 agent 在“已经存在的模型”上工作所需要的东西：工作平面、稳定引用、会分裂并继续流转的实体，以及对已有曲线和曲面的编辑。
+编辑器换了新的视口。编辑器里的手动建模已经做出来，但这一版暂不开放；本版本的编辑器只提供代码模式。
+
+## 可以被指到的模型
+
+* **工作平面是值。** `make_workplane_*_rworkplane`（由面、点、轴、中面、曲线法向）和 `make_workplane_offset_rworkplane`
+  （相对某个工作平面或命名平面移动、旋转）都会被记录，并能从模型 JSON 重放；`make_sketch_rsketch(plane=wp)` 在其上画草图。
+* **引用就是代码。** `scad.ref` 写出对面、边、顶点或实体的可读、可解析的引用，`ql.ref` 把引用当作查询谓词使用。引用会沿着记录下来的历史
+  （变换、缩放、偏置、拔模、布尔）解析；失败时会报告候选项和修复方式。
+* **标签跟着它的实体走。** 标签是记录历史之上的一个视图。切割把实体分成几块时，各块命名为 `<tag>.split<i>`，并由
+  `TagSplitWarning` 报告（`sca run` 和编辑器里也会）；圆角、倒角等单形状操作会作用于每一块。
+* **一个 Part 可以持有一个实体，也可以持有多个命名的 body。** 切割把 body 分裂时会给出各块。`set_body_appearance_rpart`
+  设置 body 的显示颜色、透明度和名称，面的名字就是一个标签。
+
+## 操作
+
+* **编辑已有的东西。** `inspect_curve_rcurvedata` / `inspect_surface_rsurfacedata` 读出阶数、控制点、权重、节点和裁剪；
+  `set_*_poles`、`move_*_poles`、`set_*_weights`、`insert_*_knot`、`elevate_*_degree`、`convert_to_bspline_*`、
+  `rebuild_curve_*` / `rebuild_surface_*` 返回新的形状、记录拓扑增量并可重放。`sample_curve_rcurvature` 和
+  `sample_surface_risocurves` 为编辑器提供曲率梳和等参线。
+* **面。** `press_pull_rsolid` 用一个带符号的距离把平面拉出（并上它的棱柱）或压入（切去）；`inset_face_rsolid` 把面的环向内收缩后压印，
+  先收缩再拉伸即可做出台阶和凸台，不需要草图。
+* **草图。** 草图里支持 B 样条，带修剪、延伸和交点（也能与椭圆相交）；`fillet_corner_rsketch`、`chamfer_corner_rsketch`、
+  `project_rsketch`、`trim_rsketch`、`extend_rsketch`、`diff_sketch_rsketchdiff`；草图的轮廓和交点由 SDK 给出
+  （`inspect_sketch_rsketchprofiles`）。
+* **装配。** `explode_rassembly`。
+* **凡是要 wire 的地方也接受 edge**（扫掠路径、放样截面、面的边界）：取这一条边构成的 wire，并按 `make_wire_from_edges_rwire`
+  记录。开放截面的 `loft_rshell` 给出两条曲线之间的曲面，`sew_faces_rshell` 接受面和壳。
+* **每个操作都说明参数的含义。** 签名使用带类型的含义（长度、角度、点、方向、个数、选择、选项），`simplecadapi.catalog` 和
+  `sca ops` 直接从绑定里读出它们。
+
+## 编辑器
+
+* **新的视口。** 使用 three 的 WebGPURenderer 渲染（没有 WebGPU 的地方用 WebGL 2，或加 `?webgl`）：一次多重采样的渲染通道、环境光遮蔽，
+  边线绘制在面之上并沿视线方向做深度偏置。近处看一个零件时，内核会用内存中的 BREP 重新细分
+  （`POST /api/preview/refine`），直到弦高小于半个像素；由多个节点绘制的零件会实例化；拾取走 BVH；曲面按精确法线着色。
+* **中文和英文**，默认跟随浏览器，也可以在顶栏切换。
+* **选择就是 `scad.ref` 行**，写进 notebook。
+* **只有代码模式。** 手动建模（用按钮和对话框做特征、草图和装配）已经做出来并保留在代码树里，由
+  `editor-web/src/lib/manual-mode.ts` 里的 `MANUAL_MODE` 关闭，等它有了自己的规划再开放。这一版没有模式开关、命令栏和手动快捷键。
+* 还没有零件的 notebook 不算错误：`find_product` 抛出 `NoProductYetError`（是 `ProductNotFoundError` 的子类），编辑器预览一个空模型，
+  `sca new` 和编辑器的“新建”会建一个空的零件 notebook（参数化圆柱改用 `--kind sample`）。
+
+## 行为变化
+
+* `make_wire_from_edges_rwire` 接受任意顺序的边，和其余边都不相接的边会报错，而不是被丢掉。面操作遇到开放的或不是 wire 的输入时，
+  报告变成带实测间隙的“wire 未闭合”报告。
+* `sew_faces_rshell` 对既不是面也不是壳的输入抛出 `TypeError`。
+
+## 修复
+
+* 对面或壳（没有实体）的稳定引用可以解析了；之前会抛 `cannot resolve QL selector scope`。
+* 还原出来的值只计一次由历史得出的标签见证；留在结果里的输入即使同时也在生成，仍然保留。
+* 周期 B 样条的交点在切割前先折回一个周期。
+* 编辑器页面不再被缓存，重新构建的界面下次访问就会加载。
+
+## 面向贡献者
+
+* README 已重写，加入了对比数据和编辑器里的两台机械臂；图表由 `tools/make_readme_charts.py` 生成。
+* 移除了 C++ 移植之前、被误提交回来的七个测试文件，并更新了 edge 当 wire 用这一改动对应的黄金文件。

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplecadapi"
-version = "2.2.7"
+version = "2.2.8"
 description = "A simplified OpenCASCADE-native CAD modeling Python API"
 readme = "README.md"
 license = { file = "LICENSE" }