forgecad 0.9.13 → 0.9.15

package/dist/docs-raw/internals/compiler.md

@@ -1,307 +0,0 @@
----
-skill-group: dev-compiler
-skill-order: 1
----
-
-# Forge Compiler Architecture
-
-This is the durable architecture record for ForgeCAD's multi-backend modeling system.
-
-If you add or refactor geometry features, read this first.
-
-Canonical naming for this area lives in [backend-vocabulary.md](backend-vocabulary.md).
-
-## Core Position
-
-Forge should not invent a new CAD language or a new geometry kernel.
-
-Forge should:
-
-- keep JS/TS as the host language
-- keep Forge's semantic feature model as the source of truth
-- lower that model into different geometry backends intentionally
-- make capability gaps explicit in diagnostics and tests
-
-The unique thing to protect is not backend code. It is Forge's code-first modeling layer:
-
-- browser-first iteration
-- parametric code as the authoring format
-- composable multi-file projects
-- AI-writable design code
-- explicit provenance and backend visibility
-
-## What To Steal
-
-We should steal proven ideas aggressively.
-
-Steal from Fusion 360 / Onshape / FeatureScript:
-
-- semantic feature graphs
-- workplanes and sketch planes as first-class modeling context
-- query/reference systems for faces, edges, bodies, and feature results
-- feature definitions that lower into kernels instead of directly calling them from UI/API code
-
-Steal from CadQuery / build123d / replicad:
-
-- OCCT execution patterns
-- exact solid feature expectations
-- practical scripting ergonomics around sketches, planes, and feature builders
-
-Steal from OCAF-style document systems:
-
-- durable reference identity
-- explicit ownership of topology/reference propagation
-
-Do not steal:
-
-- a separate Forge DSL
-- backend object models as the user-facing API
-- exporter-only side systems that bypass the compiler
-
-## The Make-Or-Break Layer
-
-This is where Forge will likely succeed or fail:
-
-- the semantic feature graph
-- the compiled-scene routing layer
-- the reference / workplane / query system
-
-Why:
-
-- primitives, booleans, extrudes, and revolves are not the hard part
-- real mechanical design depends on downstream face- and edge-driven features
-- those features only stay usable if references survive feature chains predictably
-
-If this layer is weak, the repo will accumulate:
-
-- backend-specific feature code at callsites
-- export-only implementations
-- brittle face-name assumptions
-- features that work in demos but collapse in real parts
-
-If this layer is strong, future features stay additive.
-
-## Success Criteria
-
-We are succeeding only if all of these are true:
-
-1. Forge compile intent is the source of truth for mainstream part-design features.
-2. Scene-level routing is centralized, inspectable, and reused by export/debug/test flows.
-3. New features do not need ad hoc backend decisions at callsites.
-4. Workplane/reference/query semantics are stable enough for ordinary downstream feature chains.
-5. Most normal Design-workspace features can be added by extending one semantic node family and two lowerers.
-6. Tests catch plan drift, routing drift, and backend-output drift before release.
-
-We are failing if any of these become normal:
-
-- "this feature only works in export"
-- "this feature only works in Manifold"
-- "this feature only works if you know the right face name"
-- "just add one more backend escape hatch"
-- "the snapshot changed, probably fine"
-
-## Contributor Contract
-
-When adding a geometry feature:
-
-1. Define the Forge semantic intent first.
-2. Decide which domain owns it.
-3. Add or extend the compile node.
-4. Lower it through Manifold.
-5. Lower it through the maintained export backend, or add explicit unsupported diagnostics.
-6. Route it through the scene compiler.
-7. Add invariants and snapshot coverage.
-8. Update permanent docs and the living mission tracker.
-
-Do not:
-
-- call a concrete backend directly from user-facing feature APIs unless that code is the backend lowerer itself
-- add exporter-only feature behavior that is invisible to the compiler
-- silently widen or narrow exact coverage
-
-## Implementation Path
-
-### Phase 1: Compiler Ownership
-
-Goal:
-
-- every supported feature records Forge intent
-- lowerers consume that intent
-- scene routing is centralized
-
-Deliverables:
-
-- backend-neutral compile nodes
-- compiled-scene routing and diagnostics
-- snapshot and invariant coverage
-
-### Phase 2: Reference / Workplane / Query Model
-
-Goal:
-
-- face-, edge-, and plane-driven features stop depending on brittle synthetic naming
-
-Deliverables:
-
-- first-class workplane representation
-- query/reference API for "what this feature means"
-- propagation rules for downstream feature ownership
-
-This is the highest-leverage next layer. Without it, `shell`, fillet/chamfer, holes, projection, and sheet-metal-style features will all stay fragile.
-
-Initial slice:
-
-- sketches placed with `onFace()` should carry semantic workplane/query metadata, not just a resolved 4x4 matrix
-- downstream feature code should be able to ask "which workplane/query produced this?" without reverse-engineering transforms
-
-Current progress:
-
-- `onFace()` placements now record semantic workplane models on sketches
-- `extrude()` and `revolve()` now preserve that intent in the shape compile graph as a first-class workplane-placement transform instead of collapsing it to an anonymous rigid transform
-- downstream compiler-aware code can now inspect that preserved workplane placement directly
-- that compiler-visible workplane placement now propagates through later shape transforms, so provenance inspection stays aligned with the current transformed feature state
-- both lowerers now execute that preserved workplane-placement intent, and export regression tests exercise the maintained export-backend path end-to-end
-- compile-covered feature results now carry compiler-owned query-owner lineage, so parent-body ownership is no longer implicit runtime state
-- `src/forge/queryModel.ts` now defines the shared query/reference contract for face provenance instead of letting workplane and topology code drift separately
-- workplane sources and `FaceRef` values now share that face-query contract when compiler-owned provenance exists
-- `src/forge/queryModel.ts` now also defines the shared edge-query contract for tracked edges and direct edge refs, including selector semantics for whole-edge vs. `start` / `end` / `midpoint` references
-- tracked-topology flows now preserve that edge-query metadata through clone/translate/workplane-placement transforms, and placement invariants assert that tracked edge selectors stay aligned with the actual transformed edge geometry
-- booleans, shell, split/trim flows, and downstream workplane-driven features now preserve that owner lineage through the compile graph instead of erasing it at each feature boundary
-- mirrored results plus `linearPattern()` / `circularPattern()` helper copies now get fresh compiler-owned repeated-result owners when their source shapes stay compile-covered
-- placement and exact-export invariants now check that owner lineage survives ordinary shell-plus-cut-plus-boolean style part workflows
-- topology-changing compile nodes now also carry an explicit backend-neutral `queryPropagation` contract for preserved/created query meaning instead of leaving post-rewrite semantics implicit
-- that shared propagation contract now models propagated face/edge queries, feature-created query slots, and explicit ambiguity/unsupported diagnostics on rewrite-producing results
-- trim/split-by-plane, shell, hole, cut, boolean, and edge-finish rewrites now also declare descendant contracts on top of that propagation kernel
-- the shared descendant-resolution layer turns those lineage inputs into defended singles, face regions/sets, edge chains, or explicit unsupported results instead of making each caller reverse-engineer rewrite heuristics
-- trim/split-by-plane now expose their plane-cap face plus descendant-region contracts for preserved source surfaces, while hole/cut host-face splits and supported boolean difference/intersection descendants stay reviewable as defended regions instead of disappearing behind one generic ambiguity bucket
-- boolean rewrites now consume that same contract: supported unions still preserve operand label/query lineage when the source owners stay distinct, and coplanar/multi-member descendants can now surface as defended face sets instead of only masked name conflicts
-- shell, hole, and cut now layer defended created-face slots plus defended descendant regions on top of that propagation kernel instead of leaving all post-rewrite face meaning as placeholders
-- compile-covered `Shape.face(name)` resolution now reads from the compile graph plus the descendant layer, so supported shell inner walls, blind-hole floors, cut-created walls, split host faces, and defended boolean face sets can produce real `FaceRef` values after topology rewrites
-- label-based `onFace(shape, 'inner-side-right', ...)` placement now routes through the compiler-owned face resolver, while direct `FaceRef` placements preserve created-face/propagated-face provenance instead of collapsing everything back to anonymous refs
-- `src/forge/kernel.ts` and the compiler inspection surface now expose collected topology-rewrite propagation plus descendant contracts directly, and the placement/compiler invariants assert that those contracts stay inspectable and deterministic through later transforms
-- `forgecad check query-propagation` now snapshots both the propagation surface and the descendant contracts directly, so defended plane-cap faces, split-face regions, face sets, merged-edge chains, and explicit unsupported rewrite boundaries stay reviewable without wading through the full compiler-scene baseline
-
-Still missing:
-
-- universal durable face/edge identity across topology-changing operations
-- mesh/SDF rewrite families still need their own explicit descendant contracts instead of borrowed BREP-style assumptions
-- shared edge-query selectors exist for tracked topology, but topology-changing features still do not produce new single-edge ownership for most rewritten/created edges beyond today's defended preserved-edge and edge-chain subset
-- stable downstream face/edge references beyond today's defended single/region/set/chain subset still need the follow-on work in tasks 180, 190, and 195
-
-### Phase 3: Mainstream Feature Families
-
-Goal:
-
-- dual-lower the ordinary part-design stack
-
-Priority order:
-
-- `shell`
-- fillet / chamfer
-- holes / patterned cuts
-- projection and sketch-on-face refinement
-- mirror / pattern workflows driven by semantic references
-
-Current progress:
-
-- `shell()` is now compiler-owned as the first mainstream exact feature-family slice instead of being left for exporter-only logic
-- both lowerers consume the same semantic `shell` node and rewrite supported cases into backend-native boolean/extrude/cylinder plans
-- `shape.hole()` and `shape.cutout()` now form a compiler-owned hole/cut workflow slice anchored to the shared face-query/workplane model
-- through holes, blind holes, counterbores, countersinks, and planar `upToFace` hole/cut extents now lower through both Manifold and the maintained export backend from that shared semantic node family
-- shell, hole, and cut now expose defended named created-face subsets on top of the topology-rewrite kernel, so downstream features can target inner shell walls, blind-hole floors, and supported cut walls/floors without falling back to anonymous runtime placement
-- richer hole variants now also expose defended `counterbore-floor`, `counterbore-wall`, and `countersink-wall` created-face slots where Forge can model them directly
-- `filletEdge()` and `chamferEdge()` now form a first compiler-owned tracked-edge finishing slice for supported vertical edges on compile-covered `box()` and `rectangle(...).extrude(...)` bodies
-- the post-rewrite edge-query layer now also defends untouched sibling vertical edges after those supported edge-finish rewrites, plus later supported boolean-union descendants when one preserved propagated-edge lineage stays explicit
-- regression coverage now includes compiler snapshots plus exact-export invariants for `shell()`
-- regression coverage now also includes exact/runtime/export checks for the supported hole/cut workflow subset
-- regression coverage now also includes API, placement-owner, query-propagation, compiler-snapshot, exact-plan, corpus, and end-to-end export checks for the broadened tracked-edge fillet/chamfer subset
-- the regression suite now also includes a file-backed ordinary-parts corpus under `examples/compiler-corpus/`, so shell, richer hole/cut workflows, projection replay, trim-created faces, repeated descendants, and finishing flows are exercised together instead of only as isolated unit slices
-- the MLP closeout review surface now lives in that corpus plus `forgecad check compiler`, `forgecad check query-propagation`, and `forgecad check brep`, so the defended subset is reviewable from the repo instead of from tribal knowledge
-- mirrored downstream features and helper-driven linear/circular repetition now preserve repeated-result ownership on top of the shared face-query backbone
-- supported boolean unions now also preserve owner-scoped label queries from repeated descendants, and compiler regressions cover both explicit duplicate-owner merge ambiguity and later boolean chains that inherit those propagated queries
-- exact export regression coverage now includes a repeated-feature part where a mirrored descendant drives a downstream workplane feature inside a boolean chain
-- `projectToPlane()` sketches now keep an explicit projection node in the compiler graph instead of collapsing immediately to anonymous runtime geometry
-- compile-covered `Sketch.onFace(shape, name)` resolution now prefers the defended face-query table on `Shape` targets, so supported boolean-preserved names and explicit repeated-descendant `FaceRef`s stay visible to later features instead of falling back to anonymous heuristics
-- the supported exact subset can now replay projection-driven follow-on features when the source reduces to one defended planar projection basis: placed straight extrusions, compatible shell/hole/cut descendants, and boolean unions of compatible projected operands all stay aligned on matching parallel target planes
-
-Current limits:
-
-- `shell()` v1 only covers compile-covered `box()`, `cylinder()`, and straight `extrude()` bases with optional `top` / `bottom` openings, while defended named created faces currently cover the exact profile families Forge can model directly (`rect`, `roundedRect`, `circle`)
-- `shape.hole()` still only covers circular holes, and `shape.cutout()` still only covers sketches already placed with `onFace(...)`
-- `filletEdge()` / `chamferEdge()` v1 cover tracked vertical edges on compile-covered `box()` and `rectangle(...).extrude(...)` bodies plus preserved propagated sibling edges through supported edge-finish and boolean-union chains; the selected rewritten edge now resolves as an explicit descendant edge-chain for inspection/debug, but not yet as a new single finishable edge target
-- two-sided extents, tapered cutouts, and thread metadata are now supported; combined counterbore+countersink heads, modeled helical threads, and broader durable identity beyond today's defended shell/hole/cut created-face subset are still missing
-- `upToFace` currently requires a planar termination face parallel to the feature direction, but defended split termination faces can now stay queryable as descendant regions where Forge still owns the source plane
-- boolean/pattern propagation currently defends owner-scoped face label lineage through supported unions, and the descendant layer can now expose some post-merge/post-difference results as face sets/regions, but broader durable per-face ownership after arbitrary merged topology changes is still incomplete
-- repeated-feature ownership currently tracks repeated bodies and mirrored descendants, not durable per-face identity after merged pattern topology changes
-- shell, hole/cut, tracked-edge finishing, and repeated-feature workflows now preserve parent-body ownership lineage, but stable downstream face/edge ownership after topology-changing edits is still not solved, which is why richer boolean-difference/intersection targets and broader fillet/chamfer workflows remain harder next layers
-- projection replay still rejects boolean difference/intersection sources, trim/fillet/chamfer silhouette changes, and non-parallel projection bases with explicit compiler diagnostics instead of silently pretending those paths are exact-safe
-
-### Phase 4: Higher-Order Workflows
-
-Goal:
-
-- features like sheet metal, advanced library helpers, and richer manufacturing flows build on the same semantic core
-
-Current progress:
-
-- `sheetMetal()` now exists as the first dedicated higher-order semantic family on top of the descendant-resolution layer
-- one sheet-metal model now lowers to both a folded solid and a flat pattern instead of splitting folded/export logic across backend-specific codepaths
-- named `panel`, `flange-*`, and `bend-*` descendants now flow through the shared face-descendant machinery, so downstream cutouts can still expose honest region/set semantics after topology rewrites
-- the maintained `folded-service-panel-cover` proof part now lives in the API examples, compiler corpus, query-propagation snapshots, API invariants, and exact BREP checks
-
-These higher-order families should keep arriving only after the shared reference/workplane/query layer is credible enough to defend them honestly.
-
-## Current Architectural Boundary
-
-Today, the intended compiler boundary is:
-
-```text
-Forge scripts
-    -> Forge semantic feature graph
-    -> compiled scene + capability routing
-    -> Manifold lowerer / export-backend lowerer / faceted fallback
-```
-
-Future feature work should strengthen this boundary, not route around it.
-
-## Next Achievable CAD Families
-
-Once the descendant-resolution layer is in place, the next credible expansion lanes are:
-
-- richer hole and cut variants
-- broader shell workflows
-- broader fillet/chamfer workflows
-- stronger projection and sketch-on-face flows
-- richer sheet-metal corner and detail workflows on top of the new semantic family
-- manufacturing outputs such as flat patterns and DXF/SVG profile export
-- toolbox and library feature families
-- stronger assembly metadata and exact/faceted route visibility
-
-These are all good fits for the compiler architecture because they can be expressed as Forge-owned semantic intent and lowered intentionally into both backends.
-
-## Bigger Leap Areas
-
-Some CAD-adjacent areas are still important, but they are a bigger leap than the current compiler program:
-
-- arbitrary direct editing over imported or heavily rewritten BReps
-- advanced surfacing or subD/T-spline workflows
-- CAM
-- simulation / FEA
-- full enterprise document/PDM systems
-- full large-assembly and mate-solver parity with major desktop CAD tools
-
-Keep these visible, but do not plan them as if they were just another feature module on the current part-design stack.
-
-## Legacy Cleanup Rule
-
-Yes, the old architecture needs cleanup.
-
-No, that should not happen as a single flag-day rewrite.
-
-The rule is:
-
-1. add compiler-owned replacements first
-2. fence old bypass paths so new work cannot extend them
-3. retire legacy shims once supported features and examples no longer need them
-
-That keeps the repo honest without destabilizing active work.

package/dist/docs-raw/internals/constraint-solver-quality.md

@@ -1,161 +0,0 @@
----
-skill-group: dev-solver
-skill-order: 2
----
-
-# Constraint Solver Quality — What's Tunable vs What's Architecture
-
-> For engineers working on the constraint solver. Answers the question: "is the math
-> settled, or do we have magic numbers we need to get right?"
-
----
-
-## The short answer
-
-**The math is settled. The craft is not.**
-
-The core algorithms — LM, CG, the normal equations — are 50-year-old numerical analysis
-with proofs. You cannot implement them wrongly in any meaningful sense. What IS hard:
-
-- Choosing the right initial guess (determines which branch you land on)
-- Handling the cases where the math breaks down (degenerate geometry, redundant constraints)
-- Making solutions persistent across save/reload/sharing
-
-These are not numerical parameters. They are architectural decisions.
-
----
-
-## What you can tune (and what actually happens when you do)
-
-| Parameter | Location | Current value | Effect of changing |
-|---|---|---|---|
-| `tolerance` | `registry.ts` | `1e-3` | Looser → faster but visibly imprecise. Tighter → more iterations, may miss interactive frame budget. |
-| `lambda0` | `registry.ts` | `1e-3` | Starting trust region. Too high → slow. Too low → diverges on ill-conditioned sketches. Standard value. |
-| `nu` (growth factor) | `registry.ts` | `2` | Standard. Changing this rarely helps. |
-| GS escape rounds | `registry.ts` | `3` | More rounds → more expensive. Fewer → LM gets worse warm start. |
-| `restarts` | `registry.ts` | `1` | One retry from scratch. More rarely helps unless null-space perturbation is implemented (task 410). |
-
-**The only parameter with major quality impact is `tolerance`.** The others are in the
-"reasonable defaults from the literature" category. `tolerance = 1e-3` is too loose for
-mm-scale CAD — production solvers use `1e-6` to `1e-10`.
-
----
-
-## What matters more than parameters
-
-### 1. Initial guess quality
-
-LM is a local optimizer. It finds the nearest solution to the starting point. Period.
-If your starting geometry is far from the intended configuration, you get the wrong solution
-even with `tolerance = 1e-10`.
-
-This is why GS warm-up exists: to propagate positions forward from anchor constraints before
-LM runs. It converts "all points at (0,1)" into something LM can work with.
-
-**The limit**: GS warm-up only propagates along constraint chains. Circular sub-graphs
-(closed loops) can't be bootstrapped this way. For these, the starting positions are
-whatever was stored in the file or left over from the previous solve.
-
-### 2. Branch selection
-
-When a constraint system has multiple valid solutions (two circle intersections, mirror
-image triangles, open vs. crossed linkages), the solver returns whichever is nearest to
-the starting point. This is not a solver quality problem — it is a *correct* behavior.
-The issue is that "nearest to starting point" is not the same as "what the user intended."
-
-Production CAD systems (SolidWorks, Siemens NX) solve this via:
-- **Explicit branch hints** stored with the sketch (e.g., signed area of each sub-triangle)
-- **Solution continuity**: track the branch from the previous solve and bias the initial
-  guess toward it
-
-ForgeCAD does solution continuity implicitly through warm-start. It breaks on file reload
-because nothing in the serialization format encodes branch intent. See task 440.
-
-### 3. Degenerate case handling
-
-Several constraints return `residual = 0` (satisfied) when the input entities are degenerate
-(zero-length lines, zero-radius circles, zero-sweep arcs). This is caused by the `len || 1`
-pattern in `helpers.ts`. The result: invalid geometry that passes the constraint check.
-
-This is not a numerical issue. It is a correctness issue: the solver is being asked to
-evaluate a constraint that is mathematically undefined, and it returns a misleading answer
-instead of an error.
-
-### 4. Redundant constraint detection
-
-Overconstrained sketches (more independent constraints than DOF) don't fail — LM minimizes
-the sum of squares and returns a "best fit" that satisfies most constraints but silently
-violates others. Without rank analysis (SVD of J at convergence), the user gets wrong
-geometry with no indication of which constraint caused it.
-
-The rank analysis infrastructure exists in `rigidity.ts` but is not wired into the solve path.
-
----
-
-## The architectural hierarchy of constraint solver quality
-
-```
-1. Mathematical correctness of residuals and Jacobians
-   → If these are wrong, nothing else matters
-   → Status: Largely correct in TS; verify in Rust solver (task 430)
-
-2. Degenerate case handling
-   → Return errors, not silent wrong answers
-   → Status: Known gap (len || 1 pattern). See task 442.
-
-3. Tolerance
-   → 1e-3 is too loose. Should be 1e-6.
-   → Status: Quick win. See task 442.
-
-4. Solution branch architecture
-   → Need to encode branch intent in the file format
-   → Status: Not done. Hard problem. See tasks 440, 441.
-
-5. Initial guess quality (constructive first)
-   → Eliminate cases where LM starts from a degenerate position
-   → Status: In progress. See task 420.
-
-6. Redundant constraint detection
-   → Wire rigidity.ts into the solve path to report over/under-constrained status
-   → Status: Infrastructure exists, not wired. See task 420 requirements section.
-
-7. LM hardening (central diff, Nielsen update, null-space restarts)
-   → Incremental improvements for pathological cases
-   → Status: Task 410.
-```
-
-The most impactful work is at levels 2–4. Levels 5–7 are important but affect edge cases.
-If you are chasing a specific user-visible quality complaint, start by identifying which
-level it belongs to.
-
----
-
-## What the constraint solver *cannot* do well
-
-- **Solve globally overdetermined systems with conflicting constraints gracefully**: LM will
-  find a local minimum of ||r||², which is not necessarily a meaningful answer. The result
-  depends entirely on starting position and constraint ordering. Only solution: detect
-  over-constraint *before* running LM and report it to the user.
-
-- **Guarantee the "correct" assembly branch**: there is no mathematical notion of the correct
-  branch. It is a user intent problem, not a solver problem. The solver can only minimize
-  distance from the initial guess.
-
-- **Handle discontinuous constraint landscapes robustly**: when constraints have discontinuous
-  residual gradients (e.g., a "snap to nearest multiple of 45°" constraint), LM cannot
-  navigate them — GS projectors handle these better. This is why the hybrid LM+GS
-  architecture exists rather than pure LM.
-
----
-
-## Connection to the constraint-solver-from-scratch course
-
-| Quality concern | Chapter that explains the math |
-|---|---|
-| Why tolerance matters | 01 (residuals) — what "solved" means |
-| Why initial guess matters | 03 (Newton-Raphson) — local convergence basin |
-| Branch selection | No chapter yet — potential Chapter 16 |
-| Redundant constraint detection | 11 (SVD/null space) — rank and DOF |
-| Degenerate Jacobians | 11 (SVD) — condition number and near-singularity |
-| GS vs LM trade-off | 05 (Gauss-Seidel) + 06 (LM) |
-| Constructive solving | 12 (graph-based solving) |

package/dist/docs-raw/internals/constraint-solver.md

@@ -1,176 +0,0 @@
----
-skill-group: dev-solver
-skill-order: 1
----
-
-# Constraint Solver Internals
-
-> For a new team member. This covers the solver architecture, the key design
-> decisions behind it, and the pitfalls we've already hit and solved.
-
-## Architecture overview
-
-The constraint solver lives in `src/forge/sketch/constraints/`. Each constraint
-type is a file in `defs/` that calls `registerConstraint()` at module load time.
-The central registry (`registry.ts`) drives the solver.
-
-### Solver pipeline
-
-When the user calls `sk.solve()`, the pipeline is:
-
-```
-1.  Clone the definition (preserve originals for undo/compare)
-2.  Build Maps for fast lookup (points, lines, circles, arcs, shapes)
-3.  PRESOLVE — call constraint.presolve() once per constraint
-4.  GS WARM-UP — 5 cheap Gauss-Seidel iterations to propagate positions
-5.  NEWTON-RAPHSON — up to N iterations (if every constraint has a residual)
-6.  GS FALLBACK — if NR wasn't available or didn't converge, run full GS loop
-7.  Arc enforcement — scale arc endpoints to consistent radius
-8.  Status — compute DOF, detect over/under constraint, find redundancies
-```
-
-### Constraint definition anatomy
-
-Every constraint def file exports a `ConstraintDef` with these methods:
-
-| Method | Called by | Purpose |
-|---|---|---|
-| `presolve` | Once, before iterations | One-shot initialisation (pin fixed points, snap angles, enforce winding) |
-| `solve` | Each GS iteration | Move points to satisfy this constraint (returns error magnitude) |
-| `residual` | Each NR iteration | Return equation residual(s) for Gauss-Newton step |
-| `computeDof` | Status computation | Declare which points this constraint "touches" for DOF counting |
-| `displayPosition` | UI rendering | Where to place the constraint label in the viewport |
-
-## The three solver phases, and why we need all of them
-
-### Presolve
-
-Each constraint can optionally run a one-shot setup before any iterations.
-The `fixed` constraint uses this to pin points (`pt.fixed = true`).  Angle
-constraints use it to snap endpoints into the correct half-plane so NR doesn't
-start near a degenerate configuration.
-
-### GS warm-up (Gauss-Seidel)
-
-**Why this exists:** Fresh points often start at degenerate positions (all at
-`(0, 1)`, creating zero-length lines). Newton-Raphson needs a reasonable
-starting point — if the Jacobian is near-singular at the starting position, NR
-can't compute a useful step.
-
-The warm-up runs 5 cheap GS iterations: for each constraint in definition
-order, call `solve()` which directly pushes points toward the target. For a
-chain of angle-constrained lines, this propagates positions forward:
-
-```
-GS iteration 1:
-  absoluteAngle(line1, -90°)  → anchors line1.a, moves line1.b downward
-  absoluteAngle(line2,   0°)  → anchors line2.a = line1.b, moves line2.b right
-  absoluteAngle(line3,  90°)  → anchors line3.a = line2.b, moves line3.b up
-  ...
-```
-
-After a few passes, all points are near their final positions. NR takes over
-for fine convergence.
-
-### Newton-Raphson (NR)
-
-The main solver for precision. Uses numerical Jacobian (forward finite
-differences, step = 1e-6) and Gauss-Newton least-squares with Armijo
-backtracking line search. All free point coordinates are variables; all
-constraint residuals form the equation system.
-
-NR only runs if **every** constraint defines a `residual()` function.
-Constraints with `equations: 0` (like `fixed` and `ccw`) return `[]` from
-`residual()` — this is fine; they just don't contribute equations.
-
-### GS fallback
-
-If NR wasn't available (some constraint missing residual) or didn't converge
-below tolerance, a full Gauss-Seidel loop runs for up to N iterations.
-
-## Key design pitfalls (and how we handle them)
-
-### The "modulo-180°" ambiguity
-
-**Problem:** A line from `a` to `b` has angle `θ` from the positive X-axis.
-The same line traversed from `b` to `a` has angle `θ + 180°`. A naïve residual
-like `sin(angle − target) = 0` is satisfied at **both** `θ = target` and
-`θ = target + 180°`, so the solver can converge to the wrong orientation.
-
-**Solution:** Use `normalizeAngle(angle − target)` as the residual. This has:
-- A unique zero at `angle = target`
-- Gradient ≈ 1 everywhere (unlike `1 − cos` which has gradient 0 at the target)
-- A discontinuity at `±π`, which `presolve` avoids by snapping points into the
-  correct half-plane before NR starts.
-
-We tried two other formulations before landing on this:
-
-| Residual | Unique zero? | Gradient at target |
-|---|---|---|
-| `sin(angle − t)` | No (also zero at t+π) | 1 (good) |
-| `1 − cos(angle − t)` | Yes | **0** (NR stalls!) |
-| `normalizeAngle(angle − t)` | Yes | 1 (good) |
-
-### The "reference-count heuristic" for which point to move
-
-**Problem:** When `absoluteAngle.solve()` runs, it needs to decide which
-endpoint to anchor and which to move. If neither point is explicitly `fixed`,
-the wrong choice corrupts shared points. Example: the last line in a chain
-closes back to a triangle vertex — moving the triangle vertex breaks the
-triangle.
-
-**Solution:** Count how many lines each point appears in (`pointLineRefs`).
-The point referenced by more lines is more constrained by the rest of the
-system — anchor it, move the other one.
-
-```
-Line closing back to triangle:
-  a = chain endpoint (2 line refs)  → LESS constrained → MOVE this one
-  b = triangle vertex (3 line refs) → MORE constrained → ANCHOR this
-```
-
-### The "unconditional presolve snap"
-
-**Problem:** Fresh points often start at `(0, 1)`, creating zero-length lines.
-`angleOfLine(a, b)` returns 0 for a zero-length line (atan2(0,0) = 0). If this
-bogus angle happens to equal the target, presolve skips the line. Then NR starts
-with a degenerate Jacobian (zero-length lines have undefined angular gradients)
-and can't converge.
-
-**Solution:** `absoluteAngle.presolve()` unconditionally snaps the free
-endpoint to `(anchor + cos/sin(target) * max(len, 1))`. This ensures every
-line starts with a meaningful direction and nonzero length.
-
-### The "discrete orientation ambiguity" (CCW constraint)
-
-**Problem:** An equilateral triangle with a fixed vertex and `absoluteAngle` on
-one side has its shape fully determined — except the third vertex can be on
-either side of the first line (mirror image). Both solutions satisfy all
-continuous constraints. Nothing in the equation-based solver prefers one over
-the other.
-
-**Solution:** The `ccw` constraint (0 equations, presolve + solve only). It
-computes the signed polygon area and, if negative (clockwise), reflects the
-last non-fixed vertex across the line formed by the first two vertices. Since it
-runs in presolve (before NR) and in solve (during GS), the triangle is always
-pushed to CCW. NR respects this because its steps are small — it won't swing a
-vertex through the opposite side in a single step.
-
-Usage:
-```js
-const t = eqilateralTriangle(origin, sk.point(1, 1), sk.point(0, 5));
-sk.ccw(origin, sk.point(1, 1), sk.point(0, 5)); // lock CCW winding
-```
-
-## Builder rejection protocol
-
-When a user calls `sk.absoluteAngle(line, 90)`, the builder doesn't just
-record the constraint — it does a **test solve** (30 iterations) to check
-feasibility. If `maxError > tolerance × 5`, the constraint is rejected and
-stored in `rejectedConstraints[]`. This is why solver convergence from cold
-start matters: a constraint that is mathematically satisfiable can still get
-rejected if the solver can't reach the solution in 30 iterations from the
-initial point positions.
-
-The GS warm-up phase was added specifically to address this: it gets points
-close enough that NR can finish the job within the iteration budget.