grid-apps-cmms/docs/void/plan-geomgraph.md

# Void Geometry Graph Plan (Surfaces + Boundaries)

## Progress Checkpoint (2026-02-13)

1. Completed:
2. `GeometryStore` is persisted in document state and populated from solids runtime snapshots.
3. Selection pipeline was split to `interact/selection_resolver.js` and now emits typed candidates (`profile/solid-face/solid-edge`) with canonical entity descriptors.
4. Extrude targets carry `region_id`; chamfer edge refs carry `boundary_segment_id` + entity metadata.
5. New canonical mapping bridge is active in solids selection:
6. face key -> canonical `surface` id
7. edge key -> canonical `boundary-segment` id
8. loop edge key -> canonical `boundary` id
9. Resolver now consumes these mappings (`resolveCanonicalFaceEntity`, `resolveCanonicalEdgeEntity`) as primary IDs.

## Resume Pointers

1. Canonical mapping source:
2. `src/void/api/solids.js`:
3. `buildGeometryStoreSnapshot()` map population
4. `resolveCanonicalFaceEntity()`
5. `resolveCanonicalEdgeEntity()`
6. Canonical mapping consumer:
7. `src/void/interact/selection_resolver.js`
8. `resolvePrimarySurfaceHit()` entity assignment for face/edge candidates.
9. Canonical hard cutover completed:
10. Extrude profile refs resolve via `region_id` only.
11. Chamfer refs resolve via canonical `segment:*` / `boundary:*` ids only.
12. `input.solids` compatibility branches removed from solid-op edit paths.
13. Boundary-hover correction applied:
14. Face-edge resolution now prioritizes hovered-face boundary lookup before global solid edge intersections.
15. Boundary extraction uses the same crease threshold as rendered edges (`SOLID_CREASE_ANGLE_DEG`) to reduce partial/extra loop mismatches.
16. `getFaceEdgeHit()` now prefers closed-loop boundaries over open seam chains when both are near cursor.
17. Follow-up TODO:
18. During sketch editing, `Use (u)` should derive from other visible sketch entities (not only solids).

## Target Architecture

1. Adopt a single geometric graph centered on `surfaces` and `boundaries`, with solids as derived artifacts only.
2. Treat every selectable thing as one of:
3. `SurfaceRegion` (planar/non-planar bounded patch).
4. `Boundary` (closed loop on a surface).
5. `BoundarySegment` (line/arc/spline edge piece inside a boundary).
6. `BoundaryPoint` (segment endpoint, midpoint, center, intersection, projected point).

## Core Data Model

1. Add `GeometryStore` (document-persisted, versioned):
2. `surface_id`, `type` (`planar|curved`), `frame` (for planar), `source` provenance.
3. `boundary_id`, `surface_id`, ordered `segment_ids`, orientation, closure, area sign, nesting depth.
4. `segment_id`, `kind` (`line|arc|circle|polyline|nurbs`), param data, `owner_boundary_id`.
5. `point_id`, world/local coords, role (`endpoint|midpoint|center|derived|intersection`), references.
6. `region_id`, `surface_id`, boundary rings (`outer + holes`), selectable extrusion/chamfer profile token.
7. Add stable identity layer:
8. Every entity gets deterministic `geom_sig` + persistent `id`.
9. Derived entities keep `origin_ref` and dependency chain for rebind/rebuild.
10. Add `TopologyIndex` (runtime cache):
11. Maps solid mesh triangles/edges to source `surface_id` and `boundary_segment_id`.
12. Supports nearest-hit resolution with tolerance and tie-break rules.

## Selection and Hover System

1. Replace mode-specific picking with one `SelectionResolver` pipeline.
2. Input: ray hits + current mode + intent mask.
3. Output: ranked candidates of `point/segment/boundary/surface/region`.
4. Ranking rules:
5. Point proximity always wins near threshold.
6. Segment wins next when distance-to-curve below threshold.
7. Boundary/region wins when inside region and not near point/segment.
8. Surface wins otherwise.
9. Add per-mode intent masks:
10. Sketch mode: `point,segment,boundary,surface(region projection)`.
11. Extrude mode: `region` only.
12. Chamfer mode: `segment` only (plus face-to-edge expansion helper).
13. Boolean mode: `surface/body` selection groups.
14. Add consistent multi-select semantics:
15. Plain click toggles in active picker.
16. `space/esc` clear picker-local selection.
17. No cross-picker stealing while dialog active.

## Geometry Build Pipeline

1. Introduce staged rebuild in worker:
2. Stage A: Feature evaluation -> sketch geometry on target surfaces.
3. Stage B: Boundary graph build per surface (loop extraction, splitting, nesting).
4. Stage C: Region synthesis (`outer/holes`) with fill-rule consistency.
5. Stage D: Solid operations (extrude/boolean/chamfer) from region/surface references.
6. Stage E: Topology annotation back into `GeometryStore` for interaction.
7. Cache keys:
8. `feature_sig`, `surface_sig`, `boundary_sig`, `region_sig`.
9. Recompute only invalidated downstream stages.

## Sketch Integration

1. Sketches bind to `surface_id` + local frame, not transient face index.
2. `Use (u)` creates `derived segment/point` referencing source `segment_id/point_id`.
3. Derived geometry stores transform relation to host surface frame.
4. Midpoints become first-class `point_id` with constraint targetability.
5. Closed-area detection uses `boundary/region` graph directly (no separate ad-hoc fill path).

## Extrude Integration

1. Extrude input stores selected `region_id`s, not ad-hoc loops.
2. Region hover/selection always from boundary graph.
3. Live preview reads from current region snapshots.
4. Targets/tools in add/subtract reference resulting body ids, but source remains region-driven.

## Chamfer Integration

1. Chamfer input stores `boundary_segment_id`s (or section ids for partial edges).
2. Face click expands to boundary segments by adjacency policy.
3. No selection against regenerated transient mesh during edit.
4. Preview and final solve read same boundary refs to avoid drift.

## Projection / Derive Reliability

1. Stop pre-projecting everything.
2. Resolve hovered source entity first.
3. Project only selected/hovered entity into current sketch frame.
4. Keep source and projected visuals separate but linked by shared entity id.

## Planar/Non-Planar Classification

1. Surface classification at creation:
2. Planar stores orthonormal frame and scalar offset.
3. Curved stores param evaluator and principal directions where available.
4. Boundary segments on curved surfaces can still be selected/extruded/chamfered as references.
5. Sketch-on-face initially allowed only on planar surfaces; curved support can be staged later.

## Document Persistence

1. Persist `GeometryStore` plus feature list and timeline.
2. Persist only canonical geometry entities, not transient mesh selections.
3. Add schema version bump and hard reset path (allowed in this project stage).
4. Undo/redo stores deltas against `GeometryStore` entities for atomic operations.

## Migration Strategy

1. Phase 0: Add new store in parallel, keep existing runtime behavior.
2. Phase 1: Route hover/selection to `SelectionResolver` while existing builders stay.
3. Phase 2: Route sketch profiles/areas to `boundary/region`.
4. Phase 3: Route extrude inputs to `region_id`.
5. Phase 4: Route chamfer inputs to `segment_id`.
6. Phase 5: Remove legacy face/edge ad-hoc paths.
7. Forward-only: remove rollout toggles and legacy branching once parity is reached.

## Performance and Worker Plan

1. Keep all heavy geometry graph and topology steps in worker.
2. Main thread receives compact immutable snapshots and draw buffers.
3. Use incremental invalidation by dependency DAG from edited feature forward.
4. Add rebuild budget logging per stage to catch regressions early.

## Testing Plan

1. Unit tests:
2. Boundary extraction and nesting.
3. Region fill-rule behavior (self-intersecting + nested bulls-eye cases).
4. Selection ranking with tolerance.
5. Projection correctness for points/segments/surfaces.
6. Integration tests:
7. Sketch-on-face propagation after upstream edits.
8. Extrude profile row hover maps to produced solids.
9. Chamfer edit stability with multi-select.
10. Undo/redo atomicity in dialogs.
11. Fuzz tests:
12. Random sketch mutations + constraints + rebuild consistency checks.
13. Determinism check: same doc state yields same entity ids/topology signatures.

## Deliverables Sequence

1. `GeometryStore` + ids + schema.
2. `SelectionResolver` + mode masks.
3. `BoundaryGraphBuilder` + `RegionBuilder`.
4. Extrude refactor to `region_id`.
5. Chamfer refactor to `segment_id`.
6. Projection/use refactor to source-first selection.
7. Legacy path removal and cleanup docs.

## Acceptance Criteria

1. Hover/select behavior is identical and predictable across sketch/solid/chamfer modes.
2. Derived sketches follow upstream changes without requiring manual edit-open.
3. Extrude/chamfer operate on stable references, not transient mesh hits.
4. Nested/self-intersecting regions behave correctly for selection and extrusion.
5. No mode where selection silently switches entity class unexpectedly.