320 Commits

Author SHA1 Message Date
Ni Jingzhe c1868f0edd Merge pull request #92 from PhySpace/fix/boolean-clean-and-fillet-check
fix: cut/intersect unify their result, and a blend never returns an invalid solid (#88)
2026-11-12 11:18:20 +08:00
Ni Jingzhe ddafe56379 Merge pull request #91 from PhySpace/fix/readonly-source-dir
fix: model and export STEP from a script in a read-only, unattended run (#89)
2026-11-12 11:17:28 +08:00
Ni Jingzhe 35a4e5efa9 fix(kernel): cut and intersect unify what they leave split, and a blend never returns an invalid solid (#88)
DECISION: three changes, in this order of importance, each independent of the others.
(1) a fillet or chamfer whose result OCCT calls invalid is an error; (2) cut_rsolid, cut_rsolid_list and
intersect_rsolid unify the same-domain faces and edges of their result by default, with `clean=False` to keep the raw
result, as union already does; (3) the diagnosis names split faces instead of blaming the radius. No compatibility
shim for records made before `clean` existed: replay requires the parameter, like every other recorded one.

PROBLEM (reproduced on the issue's two cases, current dev build on Windows, OCCT 7.9.3)
A cut through the side of a box with a cylinder splits the cylinder wall along the cylinder's parametric seam into two
faces, and the top edge of the notch into a long and a short arc. union unified (ShapeUpgrade_UnifySameDomain) and cut
did not. OCCT then fillets that top edge wrongly:
- case A: BRepCheck-invalid solid, volume 28305.59 (should be 29604.46), no error at all: `fillet_rsolid` checked only
  IsDone and volume > 0;
- case B: refusal, and the diagnosis said "the radius exceeds the 2.5 mm of face room" - the half of the wall the seam cut
  off - so the advised radius was not the limit.
Same geometry, other libraries: CadQuery and build123d clean after a boolean by default and give 29604.46 / 29811.31.

(1) THE EXIT CHECK IS THE MOST IMPORTANT
`assert_blend_valid`, next to the volume check in `finish_blend` (fillet and chamfer): BRepCheck_Analyzer on the result;
invalid while the input was valid is a BlendValidityViolation, which leads the error message ("the kernel returned broken
geometry"), like the existing volume violation. Not raised when the input was already invalid (an imported solid is not
the blend's fault). It turns "wrong volume found three operations later" into an error at the operation that caused it,
whatever else is or is not done about cleaning.

(2) CLEAN BY DEFAULT, WITH THE HISTORY FOLLOWING
SDK booleans go through `tracked_cut` / `tracked_intersect`, which ask the kernel's history what became of every face
(that is how tags and lineage survive), so cleaning only the shape would break tracking. `BooleanOptions::clean` makes
`run_boolean` unify the result, merge the unifier's history into the boolean's, and follow the section edges through it;
the section-edge following was lifted out of `fuse_shapes_with_history` into one helper both use (fuse behaves as
before). The unified shape replaces the result only when it has the same number of solids and is valid whenever the raw
result was; otherwise the raw result stands. FreeCAD and build123d fall back the same way, and replicad's unconditional
SimplifyResult has been seen to invalidate results (BarbourSmith/Abundance#1934), so the fallback is not decoration.
`clean` is a keyword of the three functions (default True), recorded as params.clean like union's. C++ `cut_shapes`,
`common_shapes` and `tracked_*` keep `clean=false` as their default so other callers (diagnosis, set booleans, std
parts) are unchanged.
Not done on purpose: OCCT's own SimplifyResult(true, true) that the issue suggests: the explicit unifier already gives
the same merge and history, with a fallback we control.

REPLAY: NO LEGACY BRANCH (owner's rule: do not keep old formats alive)
`flag(p, "clean")` and `ctx.require_params(..., "clean")` fail on a graph recorded before this change, as they do for
any missing parameter. Such a graph has to be recorded again.

(3) THE DIAGNOSIS
`classify_split_faces`, before the face-room probe: unify the solid, carry the selected edges over with the unifier's
history, blend again with the same size; if that works the split faces are the cause, and the message says so and how to
fix it (clean=True, or union_rsolid(clean=True)). The room probe stays for a radius that really is too large (test:
radius 50 on the cleaned case is still reported as too large).

EVIDENCE
- Both cases now give valid fillets with volumes 29604.46 and 29811.31, equal to CadQuery's.
- clean=False: A raises "not a valid solid" (it was returned), B raises "faces ... split on a surface ... clean=True".
- test/test_boolean_clean.py (10 tests): face counts 8 against 9, volume unchanged by cleaning, cut_list and intersect,
  both cases, both clean=False diagnoses, a really-too-large radius, `clean` recorded, replay giving 8 / 9 faces.
- A random sample, 120 cases of the issue's recipe (box minus 2-4 vertical boxes/cylinders on a grid, top edges, r 1-3),
  both modes: 240 results, none invalid and returned (clean=True 84 valid / 36 errors, clean=False 83 / 37).
- Full Python suite on this machine: 2674 passed; 22 failed and 9 errors, none touching booleans (Windows paths,
  encodings, file locks, addon and shell integration, missing OCP, a math-library last digit in test_tolerance).

NOT DONE / NOT KNOWN
- The C++ unit tests (ctest) were not built or run here (SCAD_BUILD_TESTS is off for the wheel build). CutOptions::clean
  defaults to true, so a C++ test that compares a cut's topology may need its expectation updated: CI will say.
- The issue's 16000-case run was not repeated, only the small sample above; it shows that no invalid result is
  returned, not the 0.4% rate of the issue (there is no old binary here to compare with).
- A stored artifact or fingerprint of a model with a cut that left split faces changes: the faces are fewer. That is the
  point of the change; rebuild such models.
- Unifying can still make a later blend worse on rare inputs (the issue saw 6 segfaults after unify in other libraries
  too); here the unify is inside the boolean, so a crash would show in the boolean.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-12 03:31:21 +08:00
Ni Jingzhe 46635ce386 fix(runtime, exporter): a script can model and export STEP in a read-only, unattended run (#89)
DECISION: three changes for the three obstacles of the issue, each the smallest that removes the obstacle. No new
API name, no relocatable state directory, no rewrite of rule R3.

1. A run without the cache touches nothing next to the source (the crash).
   PROBLEM: `run_notebook(path, cache=False)` failed on a read-only source directory (`Errno 30` on Linux, `WinError 5`
   here): `_run` ended with `write_dependencies`, which writes `__marimo__/.../deps.json` beside the notebook, and
   `exclusive()` made the state directory for its lock.
   REPRODUCED on Windows with an ACL that denies creating entries in the directory, on the issue's own notebook:
   PermissionError at runner.py `write_dependencies`. After the change the same run prints `ok` and creates nothing.
   WHY THIS FIX: the dependency record exists for the cache (cache entries are keyed on the files it lists); a run that
   keeps no entries has no reason to move it, and moving it left the record and the entries out of step. The lock exists
   to protect pruning and that record, neither of which a run without the cache does. A run WITH the cache still writes
   its state and still fails loudly when it cannot: asking for persistence and silently not getting it would be worse.
   REJECTED: an environment variable or argument that moves the state directory (more surface, and the problem is that
   there should be no state, not that it is in the wrong place); swallowing the OSError (hides real cache failures).

2. The exporters take a build result (one step, no `.scadpkg` on disk).
   PROBLEM: STEP from a freshly built Part needed `capture(result, path)` and then the exporter on that path, and the
   default capture tessellates a scene nobody reads: 1.85 s against 0.26 s for the issue's 36-hole plate.
   WHY THIS FIX: `build_product_package` already accepts a build result or a definition and can leave the scene out;
   `read_product_package_translation_units`, which every exporter and translator goes through, now builds that package in
   memory when it is given neither a package nor bytes nor a path. So STEP, STL, OBJ, MJCF and FreeCAD all gain the
   one-step form with the same validation, under the existing names. A value that is no product still raises TypeError.
   REJECTED: `exporter.step.export_part(part_or_solid, path)` as the issue suggests: a bare Part or solid has no
   definition (feature graph, topology snapshot, hashes), those come from `@scad.part`; and a second family of names
   beside `export_product_package_to_*` (the tests pin that these live only in `scad.exporter`).

3. The skill lists the plain script as an entry for a single-script task.
   PROBLEM: R3 says a model is a marimo notebook; an agent given "one script, `--output part.step`" read the skill and
   chose another library.
   WHY THIS FIX: R3 keeps its force for everything a person opens or reuses; it gains one exception, a task that itself
   asks for a single script, and the template (which I ran in a read-only directory: STEP written, source untouched)
   lives in the export domain page next to the rule it relaxes. THIS IS A POLICY DECISION OF THE OWNER, made here
   provisionally: R3 was a deliberate rule, and the PR says so.

Not done: the issue's timings were not rerun on Linux, only on this Windows machine (same direction).

Checked: test_notebook_runtime and the cache tests (123 passed), test_product_exporter/packages/capture/assembly pass
with the three new exporter tests, test_skill_lint passes. test_skill_build::test_files_without_directives_copied_verbatim
fails on the base commit as well.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-12 03:00:59 +08:00
Ni Jingzhe 342aae581d fix(artifacts): fingerprint quantization no longer splits a value that sits on a boundary (#87)
DECISION: snap the ratio value/tolerance to a binary grid before rounding it to an integer. Do not pre-round to a fixed
number of decimals, do not make the snapshot validator tolerant of off-by-one integers.

PROBLEM
A body's geometry fingerprint is a hash of every measured value divided by 1e-7 mm and rounded to an integer
(`_q`, artifacts/geometry_interface.py). A design value such as -3.34690815 mm is exactly a boundary of that
rounding, (k + 0.5) * 1e-7. The value computed one way is a unit in the last place under the boundary, the same value
after a BREP round trip is one over it (-3.3469081499999995 against -3.34690815), and `int(round(...))` sends the two to
neighbouring integers. The reporter's body had two such edge centers: its fingerprint changed across the readback and
`restore_topology_snapshot` raised `geometry_mismatch`.

REPRODUCED
- On the attachment of the issue (R02 BREP + recorded snapshot, read in this checkout, without running the attachment's
  own script): the fingerprint after the readback is exactly the issue's B (sha256:d9620b...), and the two edge centers
  quantize to -33469082 and -66530918, the integers the issue lists after the readback.
- A whole solid that changes its fingerprint across a BREP round trip could not be built synthetically: the doubles
  survive the binary BREP unchanged, the one-ulp difference of the issue comes from how the readback shape is measured
  (centers are integrated). So the regression test is at the quantizer, with the issue's two value pairs and 20000
  random values on a boundary with up to three ulps of noise on each side: before this change 6482 of them split, and
  both issue pairs failed.

WHY THIS FIX
- Pre-rounding to a fixed number of decimals either leaves large coordinates (a 1 m part is 1e10 quanta, one ulp is
  2e-6 of a quantum) unprotected or moves 1% of all values to a different integer. The grid follows the ratio's
  magnitude (2**-46 of it, at least 2**-24): a half-integer is exactly on it, noise is well under it, and the window of
  values that change integer is about 1e-5 of a quantum (test: at most 5 of 50000 ordinary values move).
- A tolerant validator (accept an off-by-one integer) would have to be taught every place a label is compared (body,
  face, edge and vertex labels, the topology match keys, the connector hashes); one deterministic quantizer fixes them
  all at the source.

WHAT THIS DOES NOT FIX
- Fingerprints are stored in artifacts. A value that was on a boundary now quantizes (half to even) where it used to
  fall on either side, so such a stored fingerprint changes once; every other value keeps its integer. The reporter's
  recorded snapshot (made on the other side of the boundary) still does not restore: it has to be captured again. It
  could not have been restored before either.
- `exporter/_surface_mesh.py` and `inspect/brep/compare.py` round the same way for mesh welding and BREP comparison;
  they were not part of the report and are left alone.

Checked: test_artifact_*, test_product_*, test_brep_region_snapshot, test_topology_getter_contract, test_part_interface,
test_assembly_builder, test_native_canonical pass. test_scene_contract (generated types) and test_native_without_ocp
fail on the base commit as well (this machine lacks OCP and the pinned generator).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-12 02:55:46 +08:00
Ni Jingzhe 5efd5bb31a tests: do not depend on the order of the names a single cell defines (Python 3.12 CI failed on it)
DECISION: the open solids a notebook leaves are compared as a set of names in the tests, and the docstring of
SeveralOpenBodiesError says the order is the cell order only across cells.

WHY: CI (Python 3.12) failed test_one_solid_part.py::TestNotebookProduct::test_several_open_solids_have_no_product
with `('tool', 'base') != ('base', 'tool')`. Both solids are defined by one cell, and the names a cell defines
come from a set, so their order is not fixed (it differed on 3.12; it can differ on any run). The behaviour that
matters (design-docs/part-holds-one-solid.md: several open solids give no product, and the error names them and
says what to do) does not depend on that order, and the editor's own list (`snapshot()["open"]`) is built from the
cell order and stays deterministic. So the test asserted more than the rule: it now asserts the set of names, in
this test and in the same assertion of test_editor_features.py (which passed locally by luck).

- runtime/projection.py: SeveralOpenBodiesError's docstring no longer says the names come "in cell order"
  without qualification.

Checked: test_one_solid_part.py passes (28 tests). I did not make the order deterministic in the code: nothing
needs it, and the owner's rule is to do only what is necessary.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 04:37:09 +08:00
Ni Jingzhe f60f69846d tests: the editor's API index test expects Part to take body and no bodies
DECISION: update test_editor.py::ApiIndexTest::test_classes_list_their_constructor_without_private_fields to the
one-solid constructor: `part_id` and `body` are required, `bodies` is not a parameter.

WHY: the test said "a Part takes one body or several bodies (multi-body parts), so only part_id is required". A
Part holds exactly one solid since "part: a Part holds exactly one solid" in this series (owner's decision, see
design-docs/part-holds-one-solid.md), so `body` is required and `bodies` must not appear in the editor's index of
the SDK constructor signatures (the index is what the editor's forms and completion read). An earlier commit of
the series ("editor: several open solids have no product ...") fixed the first assertion of this test but left
this one, which a full run of the suite caught (the earlier run of the editor test files had passed it only
because the test then still matched the stale index).

Checked: test_editor.py::ApiIndexTest passes (6 tests).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 04:17:28 +08:00
Ni Jingzhe b56634ee6e tests: the cell-cache test of restored Pieces makes its Part from one piece
DECISION: the notebook in test_cell_cache_store.py::TestPiecesComeBackAsPieces made `make_part_rpart(body=moved)`
from the pieces of a split cut, which was a multi-body Part with bodies body_1 / body_2. A Part holds exactly
one solid now (design-docs/part-holds-one-solid.md), so the last cell makes the Part from one piece.

WHY: the test is about the cell cache restoring `Pieces` as `Pieces` (marimo stores a list as a plain list), not
about multi-body Parts, so what it protects is kept: the restored split still feeds the next cell as pieces
(kind == "Pieces", the translate runs per piece). Only the product cell and the final assertion changed: the
Part is `moved[0]`, and the assertion compares the Part's body (id and the moved height: +1 mm between the
first and the second run) instead of the number of `definition.bodies`, which no longer exists.

Found by running the test files that mention bodies / Pieces after the one-solid change (178 other tests in
those files passed). Checked: test_cell_cache_store.py passes (9 tests).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 04:14:05 +08:00
Ni Jingzhe 0307aaa40f tests: replace the multi-body Part tests by tests of the one-solid rule (and of what the audit found broken)
DECISION: test_multi_body_part.py becomes test_one_solid_part.py (git rename), and test_body_appearance.py is
rewritten for the single body of a Part. The tests now state the rule of this series instead of the withdrawn
design.

WHY - THE DISCUSSION (owner and assistant, 2026-11-10; full account in design-docs/part-holds-one-solid.md)
The owner's need was several solids side by side in one notebook with no assembly constraint (pattern a tool
and cut); the multi-body Part was a wrong way to give it, because it made assembly hard; the agreed rule is
Part = one solid, the editor shows loose solids, an Assembly delivers several. A rule that is not tested
comes back: the audit of 2.2.8 found a multi-body Part refusing connectors and crashing explode_rassembly,
and nothing had said so. So the tests include those two cases, now for every Part.

test_one_solid_part.py
- a Part has one body; several solids / `bodies=` are refused with the guidance; one solid in a list or a
  Body is accepted; pickle keeps body and tags; the mass report has one row; the removed helpers are gone;
- every Part takes connectors, and an assembly of such Parts flattens, explodes (the audit's crash) and
  previews; several solids are delivered as an Assembly of Parts;
- replay: a recorded Part replays, and a model recorded with several solids in one Part is refused;
- preview: compile_open_bodies draws each open solid as its own node and entity namespace (two same-shape
  solids stay two), a Part is one node, nothing to draw is an error;
- notebook: one open solid is the implicit Part; several raise SeveralOpenBodiesError naming them and saying
  what to do; the tool-cut-into-body example of the design leaves one open solid; a Part made of the chosen
  solid is the product, its package holds one solid (profile 2, no solid_cache.bodies) and exports one STEP
  solid, and the cell cache restores it; the live preview shows the open solids (OpenBodies);
- split cuts still give Pieces (they are notebook values): the old Pieces tests are kept, and a Part takes
  one piece, not several.

test_body_appearance.py: the appearance tests of a single body (colour, opacity, name, reset, material kept,
pickle, replay, preview, legacy scene compiler, package scene with ONE node and no child solid nodes, STEP
colour). The multi-body definition test is gone with profile 3.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 04:07:57 +08:00
Ni Jingzhe 910df75260 AGENT.md: record how to rebuild the C++ module here, and why the obvious commands fail
DECISION: write the build experience of this series into AGENT.md, as that file asks ("if you have any
experience during working, write it down here, with detailed reasons").

WHY: the owner asked for a one-solid Part to be implemented urgently (see design-docs/part-holds-one-solid.md),
which needed a rebuilt native module, and the first three build attempts failed for reasons the errors do not
show: a CMakeCache pointing into a deleted temporary build environment, the NMake generator being chosen when
none is configured, a stale OpenCASCADE found in %TEMP%, and the installed .pyd being locked by the owner's
running editor. The next person (or agent) to change src/cpp on this machine should not rediscover them. The
same note records the web UI rebuild, the `npx tsc` trap, `git add -f` for design-docs, and that
docstrings.json shadows source docstrings.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 04:07:16 +08:00
Ni Jingzhe d415647e96 editor: several open solids have no product until the author picks one (use_as_product), and say so
DECISION: the editor keeps letting solids exist side by side (a tool next to its body), but they are no longer
the bodies of one implicit Part. With exactly one open solid the Part is implicit as before; with several the
notebook has no product yet and the editor asks the author which solid is the part.

WHY - THE DISCUSSION (owner and assistant, 2026-11-10; full account in design-docs/part-holds-one-solid.md)
This is the editor need that started the whole multi-body Part: several solids in one notebook with no
assembly constraint (pattern a tool, then cut). The owner's judgement was that solving it inside the Part
makes assembly hard and was wrong; the agreed answer was "a Part is one solid, and the editor supports the
several solids some other way". This commit is that other way at the editor: the solids stay visible and
editable (the preview draws them, commit "runtime + preview"), and the product is chosen, never guessed. A
guess would silently leave a solid out of the exported Part; the author knows which solid is the part.

WHAT CHANGES
- editor/gui_features.py
  - snapshot(): the implicit product exists only for exactly one open solid (and its dict loses `bodies`);
    several open solids give `product: null` while `open` still lists them.
  - use_as_product(): when the notebook has no product, a part notebook and a body that is open, it writes
    the product cell `<stem> = scad.make_part_rpart(part_id=scad.notebook_id(), body=<chosen>)`. Before, it
    refused ("no product cell"), which would have left the author without a way out.
- editor-web
  - FeatureTree: a notice with one "use <solid>" button per open solid while there is no product and
    several solids are open ("N solids are open, and a Part holds exactly one solid. Choose the part:").
    The product badge reads the one product body.
  - features.ts: FeatureState.product loses `bodies`.
  - preview.ts previewSummary: nodes `node/<id>/body:<name>` are now the notebook's open solids, not the
    bodies of a part, so the header says "N open solids" (zh-CN strings added) instead of "1 part · N bodies".
- tests: test_editor / test_editor_features follow the new product dict and the required `body` argument
  of Part; a new test drives the editor flow end to end (two open solids -> no product, a headless run
  raises SeveralOpenBodiesError naming them -> use_as_product -> the Part exists and the notebook runs).

Checked: editor-web vitest (331 tests) and tsc --noEmit pass; the editor test files pass except for the
multi-body fixtures of other files, which are updated in the tests commit of the series.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 04:01:35 +08:00
NiJingzhe 41ae6d5a0e test: untrack the seven pre-port test files again (swept back in by 60fa2a8 and f4cb667; dev removed them with the C++ port, they import names it does not have)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 21:27:16 +08:00
NiJingzhe 08050b1fd8 editor: surfaces from curves and a solid from surfaces
- the face and shell values no later cell reads are drawn with the model (node/surface/<name>: light blue, seen from both sides; a sketch's face stays the sketch layer's) and picked whole in the "sketch / curve / surface" mode, highlighted and shown in the inspector
- picked curves offer Ruled surface (two), Loft surface, Fill (a closed loop: the `fill` feature, make_surface_patch_rface), Flat face (a flat loop: `flat_face`, make_face_from_wire_rface with the loop's normal), Network surface (two families of crossing curves, found from where they cross: Gordon) besides Sweep and Join into a wire (lib/curve-net.ts finds loops, their plane and the families)
- picked surfaces offer Sew (`sew`: sew_faces_rshell of faces and shells) and a shell Close into a solid (`solid_from_shell`), which becomes the part's body; each starts at once with its values filled from the picks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 19:04:16 +08:00
NiJingzhe 6813528ab2 sdk: sew_faces_rshell takes faces and shells (a shell is sewn as its faces; recorded with its pieces, replayed the same), a TypeError for anything else
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 19:04:16 +08:00
NiJingzhe 6f1c2485b7 editor: several curves picked join into a wire (the wire feature: make_wire_from_edges_rwire of the picked curves, in any order), and every form slot that asks for a wire takes a curve (an edge) too
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 06:12:46 +08:00
NiJingzhe f8a13de6e4 sdk: an edge is taken wherever a wire is (a sweep path, a loft section, a face boundary, a binormal guide): the wire of that one edge, made by the recorded make_wire_from_edges_rwire so a graph sees where it came from (as_wire, edges_as_wires; Wire(edge) and an implicit Edge -> Wire conversion in Python). make_wire_from_edges_rwire takes its edges in any order (they are chained by their ends first, then added in turn so each keeps its identity) and an edge that touches none of the others is an error instead of being left out. loft_rshell of open sections (the surface between two curves) no longer fails looking for end wires: only a closed end section is a boundary loop of its own
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 06:12:46 +08:00
NiJingzhe 53de920e81 editor: a 3D curve is one edge: a path drawn in one go becomes one curve feature per line, arc or spline (path, path_2 ...), each starting at the end of the one before (a point end_of another curve: path.get_end_vertex().get_coordinates(), so it follows that curve), a path closed on its start ends at the first curve's start, and a point snapped to an end of another curve is kept at it; all of them are added or none. An older curve cell of several segments is still one wire. The feature list takes each value's kind from the kernel for every feature (a curve is an edge, a sketch a face or a wire)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 05:45:24 +08:00
NiJingzhe 3e6ea0b661 editor: 3D curves are picked with the sketches (the "sketch / curve" selection mode): hovered and picked on screen (within a few pixels of the drawn line), drawn wider and in the selection colour, shown in the inspector (kind, edges, length); a picked curve offers Sweep (op.sweep_rsolid with the curve as its path; a sketch picked with it is the profile, and with both given it starts at once), the selection bar hangs at the curve's middle
The kernel reports the kind of every top-level value (live_value_kinds) and the feature list uses it for cells written as code: a path or a face made in code is no longer taken for a body, so it is not the product and it is offered where a wire or a face is asked for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 05:17:23 +08:00
NiJingzhe 1505ff1f42 editor: shell as an operation in progress: picked faces, Shell, and the cup is there at once with a 1 mm wall; an arrow on the opened face drags the thickness into the body (at least 0.1 mm), the panel lists the openings and takes one out, a click on a face of the model (the shelled body itself) opens it too; Esc undoes the feature with every opening added or taken out meanwhile. Fillet and chamfer take more edges the same way (any operation whose one selection takes several picks)
Server: the feature list carries what each selection slot holds as references (gui.refs), an edit keeps the references it is given for items with no entity on screen (a face a shell opened is not drawn), and a reference given twice is selected once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 04:47:31 +08:00
NiJingzhe 5c2acac1d6 runtime: a notebook with no Part, Assembly or solid yet is no fault: find_product raises NoProductYetError (a ProductNotFoundError, still raised where a product is needed: export, a headless run with a product) and the editor previews it as an empty model ("no solid yet" in the log) instead of reporting ProductNotFoundError; the editor server's own empty-notebook case is gone (the kernel's empty preview covers it), and a notebook's first model is framed when it has one
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 04:29:36 +08:00
NiJingzhe 69ac64025a press_pull_rsolid: one signed distance pulls a planar face out (its prism joined) or presses it in (cut), recorded as its extrude and boolean steps; the editor's Press / pull on a picked flat face replaces Pull face / Push in on the selection bar: an arrow on the face along its normal drags the distance (0.5 mm snap, Shift free) while the panel types it, across zero; the face's frame comes from its triangles on screen, at once
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 03:23:58 +08:00
NiJingzhe 8e01e1908c inset_face_rsolid: a planar face's loops moved inside it are imprinted (the face splits into its inner face and ring, roles inset.inner / inset.ring, tracked as fragments, replayable); the editor's Inset on a picked flat face, tuned in place like every operation, so inset then pull builds steps and bosses without a sketch; the operation panel's Enter handler no longer assumes its target is an element
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 23:13:51 +08:00
NiJingzhe d35c92e951 a new part notebook is empty (sca new and the editor's new; the parametric cylinder is --kind sample); an empty notebook is where it starts, told as info, not a ProductNotFoundError; an operation or drawing started with no notebook open asks for one first and creates it in place
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 21:42:09 +08:00
NiJingzhe 3bacb931c6 editor viewport: level of detail (a part seen up close is tessellated again by the kernel, POST /api/preview/refine, until its chords are under half a pixel; same keys and entities, highlights rebuilt), parts several nodes draw are instanced (faces per colour, edges batched; the nodes stay for picks and visibility), picks go through BVHs (three-mesh-bvh, indirect: the face and edge ranges keep their order), the axis gizmo composited by the output node from its own transparent target
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 16:08:28 +08:00
NiJingzhe 3701e43fcc editor: connectors placed on a face with move/turn handles (the same placer as workplanes), the workspace tab in manual mode too, notebooks deleted from the workspace tab (moved to .sca-editor/trash)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 04:41:21 +08:00
NiJingzhe a69d1ef431 3D curves drawn in the viewport (W: lines, arcs, splines on workplanes, snapped to vertices, edge midpoints, workplane origins; a point on a workplane follows it, a snapped vertex is a scad.ref), wires and edges drawn from kernel samples; a failing step previews the model before it; independent spline handles, anchors added while drawing, Shift+A anchor mode; sketch regions (make_faces_from_sketch_rfacelist: outer loops with their holes); a tag on several entities names a set and keeps its pieces; exact surface normals in preview meshes (smooth shading, shared vertices); SimpleWorkplane.point; scad.ref.of a vertex
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 04:30:26 +08:00
NiJingzhe fabbbe251b editor interaction: workplanes placed with move/turn handles (make_workplane_offset_rworkplane) and chained on the active one; a hole placed with the pointer; pick-intent keys 1-6; sketches drawn only when they are what a click picks; no shape-specific shortcut features, same-name ops labelled with what they make; sketch splines as anchors with two handles (insert/remove/convert anchor SDK ops, pen tool); a sketch can be made into a wire
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 02:26:34 +08:00
NiJingzhe 7d37131e71 make_workplane_offset_rworkplane: a workplane moved and turned relative to a workplane or a named plane (what the editor's handles write)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 01:29:48 +08:00
NiJingzhe 98e24b6aad tags follow their entity as references do: a split names the pieces <tag>.split<i> (numbered when recorded), reported by TagSplitWarning, sca run and the editor's highlight; solids have history (boolean solid witnesses, union merge, one-solid continuation) and scad.ref.solid; references resolve over the pieces of a split body; an ambiguous anchor is told apart by its history
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:53:29 +08:00
NiJingzhe cc2ee95de5 the pieces of a split body flow on: one-shape operations apply to every piece (scad.Pieces), selectors checked over all pieces; the cell cache keeps them as pieces
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 15:10:24 +08:00
NiJingzhe c3368e6ace fillet and chamfer take the pieces of a split body; bigger snap circle and pick tolerance in the sketch; skill page split
- fillet_rsolid / chamfer_rsolid accept the list a splitting cut returns: each piece gets the picked edges on it, the
  selector's cardinality is checked over all pieces, the result is the pieces in order (a Solid stays a Solid). A GUI fillet
  after a cut that split the body failed with a TypeError and the part lost its product.
- Sketch: pick/snap tolerance 9 -> 16 px, the snap mark is a larger ring.
- Skill: the GUI-feature half of editor-collaboration.md is its own page (editor-gui-features.md); the page was over
  the 300-line limit after the workplane and ref sections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 14:38:32 +08:00
NiJingzhe 0399b4963b merge feat/public-refs: scad.ref (readable, parseable stable references), ql.ref; GUI selections are one scad.ref line; ref status and repair
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 14:16:45 +08:00
NiJingzhe a90fb3bcf8 merge feat/workplanes: workplanes are values with recorded constructors (from face, points, axis, midplane, normal to a curve); Space sets the workplane in the editor
Also: the product executor count includes make_set_body_appearance_rpart (27).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 14:05:24 +08:00
NiJingzhe 3bf28ad8fd editor: selections are scad.ref statements; the server names picks in the kernel, shows a reference's status and writes a repair
selection_recipe writes one '_<slot> = scad.ref.<kinds>(...)' statement from the references the server attached to the
picked items (runtime/live_refs.py names them with scad.ref.of on the previewed solid); extract_recipe / extract_refs /
replace_refs read and rewrite it with ast.  An item the kernel cannot name keeps the older recipe; old cells still run.
Feature commands ref_status (badge ok/merged/split/lost, candidates per reference) and ref_repair (a piece of a split
or a look-alike of a lost reference, rewritten into the literal).  The resolver sees through a parent named by a
selection made in another cell (SDK_DEFECTS 43).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 13:52:26 +08:00
NiJingzhe e13a55268d runtime/editor: a cell that only makes workplanes leaves the body it reads open (implicit Part still found)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 13:50:30 +08:00
NiJingzhe c0f29be377 editor: a workplane feature from picked geometry; a sketch plane can be a workplane variable; the kernel reports workplane frames
The 'workplane' spec (role datum, produces workplane) writes
wp = scad.make_workplane_*_rworkplane(...) from a face (offset, flip),
a face + an edge, two parallel faces, three vertices or an edge (angle).
Optional selection slots; recipes for vertices; extract_recipe finds each
slot's recipe in a cell with several. A sketch document's plane may be
{workplane: <variable>, frame}: the cell writes plane=<variable> and reads
it; the frame is the kernel's, for solving and drawing. The snapshot lists
GUI workplanes. After each settle the kernel prints the frames of every
SimpleWorkplane global (runtime.live.workplane_frames) and the server
sends a replayed 'workplanes' envelope when they change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 13:43:23 +08:00
NiJingzhe dc6aabd2ec ref: scad.ref (stable references as code) and ql.ref (a reference as a query predicate)
scad.ref.of(entity, shape) / scad.ref.face(feature, op, role=...) / scad.ref.edge(..., between=(face, face)) make an
ElementRef whose repr() is the code that makes it; .resolve / .one / .all / .choose; scad.ref.faces / edges are the
selections operations take.  ql.ref is a C++ predicate kind ('ref', the record as data) resolved once per run in the
selector's scope by the resolver simplecadapi.ref installs; ElementRefError (split / lost, with candidates) crosses
C++ operations as itself.  A feature cell's key is '<slug>.c<digest>' and node_feature drops the digest, so
references name the feature's slug and survive edits of its code.  Model JSON replay of a reference selection falls
back to the recorded evidence (replay records no history).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 13:28:32 +08:00
NiJingzhe c6f01eb568 sdk: workplanes are recorded values (make_workplane_*_rworkplane); sketch plane=wp; replay follows the geometry
A SimpleWorkplane is now a value: copyable, entered again (`with wp:` in later
cells), picklable for the cell cache (exact frame + metadata/runtime, so it
keeps its graph lineage), with origin/normal/x_dir/y_dir/plane.

Six recorded constructors (C++ ops/geometry/workplanes.cpp, typed bindings):
make_workplane_rworkplane (origin/normal/x_dir in the current system),
_from_face_ (centre or projected origin, outward normal, x along an edge / a
direction / the face's own x, offset, flip), _from_points_ (Vertex or point),
_from_axis_ (straight edge or circle axis, turned by an angle, optional start
face), _midplane_ (two parallel faces), _normal_to_curve_ (edge or wire, at a
fraction of its length). Inputs are recorded as ordered input_refs; replay
(serializer) rebuilds the frame from the replayed geometry.

make_sketch_rsketch(plane=wp) uses the workplane's world frame, records
plane={workplane: true, frame} and the workplane node as an input; replay
takes the frame from the replayed workplane. Inside `with wp:` every recorded
node's context names the workplane node; replay orders it after that node and
uses the replayed frame. types.Plane includes SimpleWorkplane; catalog kind
"workplane".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 13:25:07 +08:00
NiJingzhe 81b1f65e4d test: B-spline trim / extend / crossings (pytest), replay and the editor document round trip
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 13:17:29 +08:00
NiJingzhe f4cb667eba sketch: B-splines in the sketch editor (spline tool B: click control points, Enter makes it, the first point closes it)
The document gets a bspline entity (control point ids, degree) that becomes add_bspline_rsketch; the solve returns each
B-spline as the SDK samples it (sample_curve_rcurvature), so the editor draws the SDK's curve, its control polygon (the
points are the handles: dragging one reshapes the curve) and, for a picked spline, its curvature comb. Loops and faces through
B-splines are the SDK's profiles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 12:29:01 +08:00
NiJingzhe 4900aea4b3 test: untrack seven pre-port test files committed by mistake
They were untracked leftovers from the Python SDK (they import names the C++ port does not have: tracked_cut, _infer,
operators._support, OCP) and were swept into 60fa2a8 by a broad git add. The files stay on disk, untracked, as before;
porting them is separate work.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 11:50:23 +08:00
NiJingzhe 3d62a95d82 merge feat/body-appearance: body colour, opacity and display name (set_body_appearance_rpart); a face's name is a tag
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 11:49:42 +08:00
NiJingzhe 9a84b1d029 Merge branch 'feat/nurbs-edit-ops' into feat/gui-modeling 2026-11-04 11:30:07 +08:00
NiJingzhe f021b33489 surface edits: sub-entity tags follow without a session; stubs, API pages, graph spec, skill page
The edits finish through finalize_tracked with the entries of the rebuild's history (modification_history, the
entries next to modification_delta), so tags on the face and its edges follow with or without a recorder, as for the
tracked solid ops. Stubs regenerated (pybind11-stubgen 2.5.5), API pages generated by tools/auto_docs_gen.py, the
graph JSON spec lists the 14 recorded ops and their params/delta, and the skill gains
references/domains/curve-surface-editing.md (read, convert, edit, check; trimming; tags), linked from
part-modeling.md and references/README.md. CHANGELOG under Unreleased.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 11:21:36 +08:00
NiJingzhe c18d6b9038 editor: a colour slot for display colours; naming a face is the tag op with picked faces
op_specs offer a 'color' slot for Color parameters (set_body_appearance_rpart,
make_material_rmaterial) and an opacity slider in [0, 1]. apply_tag_rselection
returns AnyShape in its signature (it was the one untyped result in the
catalog) and its targets are faces picked in the viewport, so 'name this face'
is the existing tag operation. Fix: the generic op builder dropped every picked
selection (op.fillet_rsolid wrote no edges); a test now checks every op with a
selection passes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 11:19:17 +08:00
NiJingzhe 9df1d77917 sdk: curve/surface edit operations exported, recorded and replayed from model JSON
The 18 operations are exported at the top level and in simplecadapi.surface, with docstrings and module entries.
The 14 recorded edits join the 2.1 canonical core op set and replay through one helper (ordered input ref, params);
inspect/sample are diagnostic. element_ref no longer asks a Face/Shell for solids (SDK_DEFECTS 36), so references
into a surface body resolve. test/test_surface_editing.py: recording + replay of whole edit chains, tags and stable
references through edits, a face picked from a solid, errors, sampling, catalog types.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 11:15:39 +08:00
NiJingzhe 4ff66173c5 feat(product): set_body_appearance_rpart: a display colour, opacity and name per body
A Body carries an optional colour (RGB in [0, 1], typed simplecadapi.types.Color,
catalog kind 'color') and opacity. The material colour is the default; a body
colour overrides it for display only (mass never reads it). The op is recorded
(make_set_body_appearance_rpart) and replayed, pickles for the cell cache, and
reaches the live preview (node color/opacity), the legacy scene compiler
(base_color), the part definition (optional 'appearance' block in profiles 2
and 3; a definition without one keeps its bytes), the package scene (node
properties.color/opacity) and STEP (part colour, or a named and coloured XCAF
sub-shape per body). Material.color is typed Color too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 11:12:12 +08:00
NiJingzhe c8722c37cc fix(tags): a restored value counts a history-derived tag witness once
A value written out (pickle, cell cache) stores the lineage witnesses its history derived; restored with its
graph node, the tag view derives the same witnesses again, so Shape::lineage_witnesses() listed each twice and
a cache-restored body snapshotted to other bytes than a fresh one (test_multi_body_part
test_the_cell_cache_restores_a_multi_body_product: different content hashes).

lineage_witnesses() now skips a derived witness equal (same_witness: binding, derivation, source, target) to a
stored one. Regression tests: test_tagging.cpp (provider + stored witness = one witness), and the cell-cache
test in test_element_ref_history.py asserts a restored value encodes the same topology snapshot and the same
witness count as the fresh one, in a fresh process.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 11:04:30 +08:00
NiJingzhe 814871b868 merge research/stable-geometry-refs: references and tags resolve through recorded history (WIP: one multi-body cache test differs, being fixed) 2026-11-04 05:50:05 +08:00
NiJingzhe 37e6dd86fe merge research/multi-solid: a Part holds one Solid or several named bodies; a cut that splits a body gives its pieces
On top of the merge: the bindings it touched (cut_rsolid on_split, make_part_rpart body/bodies) take the typed signature
vocabulary; a kind = "part" notebook's implicit Part is made of all its open bodies (named by their variables, the pieces of a
split cut <name>_1..n) and is recorded in the definition (one result node, so its content hash is stable across cache hits);
product values are walked through their own children, not as plain dataclasses; the skill says how bodies and the implicit Part
work; the editor marks every body of the implicit Part as the product.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 05:39:13 +08:00