forgecad 0.9.14 → 0.9.15

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.

package/dist/docs-raw/internals/shape-from-slices.md

@@ -1,152 +0,0 @@
-# Shape.fromSlices — Design Document
-
-## Problem
-
-Users want to define 3D shapes by specifying 2D cross-section profiles on
-different planes (like slicing an object at various positions), then
-interpolating between them to create the solid. Think: "here's what the egg
-looks like from the side, here's what it looks like from the top — build me
-the 3D shape."
-
-Today's `loft()` only handles parallel XY cross-sections at different Z
-heights. There is no way to combine constraints from multiple viewing
-directions (e.g., XY circle + XZ egg-ellipse = egg).
-
-## API
-
-```ts
-Shape.fromSlices(slices: Slice[], options?: FromSlicesOptions): Shape
-```
-
-### Types
-
-```ts
-type SlicePlane = 'xy' | 'xz' | 'yz' | Vec3;
-
-interface Slice {
-  on: SlicePlane;    // plane normal (string shorthand or arbitrary unit vector)
-  at: number;        // signed offset along that normal from the origin
-  profile: Sketch;   // 2D cross-section on that plane
-}
-
-interface FromSlicesOptions {
-  edgeLength?: number;       // mesh resolution (Manifold only)
-  boundsPadding?: number;    // SDF bounding box padding (Manifold only)
-}
-```
-
-### Why `Shape.fromSlices()`?
-
-1. **No new global** — `Shape` already exists in the runtime. Adding a static
-   method adds zero namespace pollution.
-2. **Discoverable** — "I want a Shape, what can I build one from?" leads
-   naturally to `Shape.fromSlices`, `Shape.fromPatch`, etc.
-3. **Precedent** — `Points.distance()`, `sdf.sphere()`, `route.fillet()` all
-   use the namespace-dot-method pattern. This extends it to the core `Shape`
-   class.
-4. **Consistent with broader direction** — new specialized constructors go on
-   `Shape` as static methods instead of polluting the flat global namespace.
-
-## Algorithm
-
-### Core idea: group → interpolate → intersect
-
-1. **Group** slices by normal direction. Two slices with the same (or
-   antiparallel) normal belong to the same group.
-
-2. **Within each group** — build a solid by lofting (ThruSections / level-set)
-   between the profiles, placed on their respective parallel planes.
-   - Single-slice group: extrude the profile along the normal direction,
-     bounded generously (later trimmed by intersection).
-   - Multi-slice group: loft between profiles via ThruSections (OCCT) or
-     level-set (Manifold).
-
-3. **Across groups** — boolean-intersect all group solids. Each group's solid
-   represents a "viewing constraint": the final shape must fit within all of
-   them simultaneously.
-
-### Why intersection?
-
-Each group defines "what the object looks like from one direction." Extruding
-a side-view silhouette gives a prism that contains every possible shape
-matching that silhouette. Intersecting all such prisms carves out the shape
-that satisfies all views simultaneously. This is the *visual hull*
-reconstruction principle.
-
-### Examples
-
-**Egg (two silhouettes):**
-```
-Group 1 (normal=Y, 1 slice): XZ egg-ellipse → extrude along Y → egg prism
-Group 2 (normal=X, 1 slice): YZ egg-ellipse → extrude along X → egg prism
-Intersect → egg solid
-```
-
-**Vase (loft + envelope):**
-```
-Group 1 (normal=Z, 3 slices): circle@0, squircle@40, circle@80 → loft
-Group 2 (normal=Y, 1 slice): vase silhouette → extrude along Y
-Intersect → vase with cross-section transitions
-```
-
-**Pure loft (single group):**
-```
-Group 1 (normal=Z, 3 slices): profiles at different Z heights → loft
-No intersection needed (single group) → equivalent to loft()
-```
-
-## Compile plan
-
-A new `kind: 'fromSlices'` is added to `ShapeCompilePlan`:
-
-```ts
-{
-  kind: 'fromSlices';
-  groups: FromSlicesGroupPlan[];
-  edgeLength: number;
-  boundsPadding: number;
-}
-
-interface FromSlicesGroupPlan {
-  normal: [number, number, number];  // unit normal for this group
-  slices: {
-    offset: number;                   // signed distance along normal
-    profile: ProfileCompilePlan;
-  }[];
-}
-```
-
-### Lowering strategy
-
-**OCCT backend:**
-- Single-slice group → extrude profile, rotate to align with normal, translate
-- Multi-slice group → ThruSections with wires placed on their planes
-  (existing lowerLoftPlan pattern, generalized from Z-only to arbitrary normal)
-- Intersection → `BRepAlgoAPI_Common`
-- Result: exact B-rep, exportable to STEP
-
-**Manifold backend:**
-- Single-slice group → extrude cross-section, transform
-- Multi-slice group → loft via level-set (existing buildLoftLevelSetInput)
-- Intersection → Manifold boolean intersection
-- Result: mesh
-
-### Single-group optimization
-
-When all slices share the same normal (pure loft case), skip the intersection
-entirely and lower as a plain loft. This avoids unnecessary boolean overhead
-and produces identical output to `loft()`.
-
-## Broader API implications
-
-This is the first `Shape` static method. It establishes a pattern for future
-specialized constructors:
-
-| Method | Replaces global | Status |
-|--------|----------------|--------|
-| `Shape.fromSlices()` | (new) | This PR |
-| `Shape.fromPatch()` | `surfacePatch()` | Future |
-
-Existing globals (`loft`, `sweep`, `box`, etc.) remain unchanged — no
-migration, no breakage. New specialized construction goes through
-`Shape.method()`.

package/dist/docs-raw/internals/sketch-2d-pipeline.md

@@ -1,108 +0,0 @@
----
-skill-group: dev-compiler
-skill-order: 2
----
-
-# 2D Sketch Pipeline: Runtime Mesh ↔ ProfileCompilePlan ↔ Export Backend
-
-Captured from implementing sketch region selection, planar arrangement detection, and cross-sketch reference geometry (2026-03).
-
----
-
-## The Two-Track Export Model
-
-Every 3D shape in ForgeCAD has two representations:
-
-1. **Runtime mesh** — a watertight triangulated solid used for preview rendering and mesh-domain operations.
-2. **`ProfileCompilePlan`** — a serializable Forge intent description (discriminated union with `kind: 'rect' | 'circle' | 'polygon' | 'boolean' | ...`) that the current export backend reads to produce STEP geometry.
-
-When exporting STEP, the system walks the `ProfileCompilePlan` tree. If a node has no plan (plan is `null`), it falls back to a faceted mesh-to-STEP conversion — useful for interchange, but it loses parametric intent.
-
-**Key invariant**: any sketch API that only calls `polygon()` and boolean ops (`add`/`subtract`) automatically stays on the maintained STEP path. No special backend-specific code is needed.
-
----
-
-## What `Sketch` Is
-
-`Sketch` wraps a Manifold `CrossSection` (2D polygon set). It also carries:
-- An optional `ProfileCompilePlan` for the STEP path.
-- A `Placement3D` for face-mounted sketches (`.onFace()`).
-
-`ConstrainedSketchBuilder` → `.solve()` → `ConstraintSketch extends Sketch` holds the constraint definition alongside the solved `CrossSection`. The solved `CrossSection` is built from explicitly declared loops (`addLoop`); geometry outside loops is not included in the area — only in the constraint definition for arrangement detection.
-
----
-
-## New 2D Sketch Surface-Selection APIs (2026-03)
-
-### 1. `sketch.regions()` / `sketch.region(seed)`
-
-**File**: `src/forge/sketch/regions.ts`
-
-Decomposes a Manifold `CrossSection` into its distinct filled areas.
-
-- `CrossSection.toPolygons()` returns a flat list of contours. Positive signed area → outer boundary; negative → hole.
-- Holes are nested into their smallest containing outer boundary via `pointInPolygon`.
-- Each outer boundary + its holes is reassembled as a `polygon(outerPts, holePts)` sketch.
-- The `region(seed)` variant picks the one face whose outer boundary contains the seed and no hole does.
-
-**STEP export**: uses `polygon()` and potentially `boolean(difference)` for rings — both are handled by the current export backend without extra sketch-specific code.
-
-### 2. `constraintSketch.detectArrangement()` / `detectArrangementRegion(seed)`
-
-**File**: `src/forge/sketch/arrangement.ts`
-
-DCEL-based planar arrangement detection from the raw line segments in a `ConstraintDefinition`.
-
-Algorithm:
-1. Extract non-construction line segments from `def.lines`.
-2. Split segments at all pairwise intersections — both X-crossings (`segSegT`) and **T-junctions** (`pointOnSegT`). T-junction support is critical: when a divider endpoint touches a boundary edge interior, only `pointOnSegT` detects it.
-3. Snap nearby nodes and build a clean planar graph.
-4. Build DCEL half-edges. At each node sort outgoing half-edges by polar angle.
-5. `next(u→v)` = outgoing from v immediately preceding `twin(u→v)` in CCW order at v — i.e., `out[(pos−1+n) % n]`.
-6. Traverse all face cycles; keep CCW faces (positive signed area). CW = unbounded outer face, excluded.
-7. Return each face as a `polygon(pts)` sketch.
-
-No explicit loops needed from the caller. Works on any set of line constraints.
-
-**STEP export**: each face is a `polygon()` — handled by the maintained export path.
-
-### 3. `builderB.referenceFrom(sketchA, entityId)` / `referenceAllFrom(sketchA)`
-
-**File**: `src/forge/sketch/constraints.ts`
-
-Import solved geometry from another `ConstraintSketch` as fixed construction references.
-
-- Fixed points (`fixed: true`) and construction lines (`construction: true`) participate in constraint solving but contribute zero area to the resulting CrossSection profile.
-- `referenceFrom(source, id)` looks up the entity by id in the source's `ConstraintDefinition` and creates a fixed copy in the current builder.
-- Enables constraints like `parallel(bBot, refBase)` to lock relationships between separate sketches.
-
-**STEP export**: construction elements are ignored by `buildSketchFromDefinition` when assembling loops → no impact on export path.
-
----
-
-## Backend Agnosticism
-
-These APIs are fully backend-agnostic because they operate on:
-- **2D coordinates only** — no 3D kernel calls during region/arrangement detection.
-- **`polygon()`** — the lowest-level sketch primitive, available on every backend.
-- **Boolean ops** — available on every backend (Manifold, OCCT, …).
-
-No backend-specific code was added. Adding a new backend (e.g., CGAL, OpenCASCADE directly) automatically inherits all three APIs as long as it handles `polygon` and `boolean` plan kinds.
-
-The only Manifold-specific call is `CrossSection.toPolygons()` in `regions.ts`. If a future backend doesn't use `CrossSection`, `sketchRegions` would need an adapter — but the algorithm and public API shape would be unchanged.
-
----
-
-## Gotchas
-
-### Empty CrossSection for loop-less sketches
-
-`constrainedSketch().solve()` used to throw "at least one closed loop" when called without `addLoop()`. Users calling `.detectArrangement()` never add loops. Fix: return an empty `CrossSection` via `CrossSection.difference([unit, unit])` (not `new CrossSection([])` — Manifold's `polygons2vec` crashes on empty array).
-
-### T-junctions
-
-Interior-only intersection detection (`segSegT`) misses T-junctions entirely. A 3×2 grid yields only 4 cells instead of 6 if T-junctions aren't split. Always run `pointOnSegT` for every endpoint of every other segment against every segment.
-
-### DCEL `next` pointer direction
-
-The formula traces faces to the **LEFT** of each directed half-edge. CW winding = unbounded outer face. Keep only faces with positive signed area (CCW winding = bounded interior face).

package/dist/docs-raw/platform/admin.md

@@ -1,45 +0,0 @@
-# Admin Dashboard & Audit System
-
-The admin dashboard lives at `/admin` and is restricted to users with `role = 'admin'`. The frontend gate is in `src/pages/AdminPage.tsx`; the backend enforces the same role check on `/api/admin/*` routes.
-
-## Dashboard features
-
-- **System health** -- server status, uptime, version (fetched from `/api/health`).
-- **User statistics** -- total users, total projects, active today.
-- **User list** -- all users with name, email, role, and join date.
-- **Audit log** -- recent activity feed (via `/api/admin/audit`).
-
-## Audit log
-
-Every significant user action is recorded in the `audit_log` table. The schema (`server/db/schema.ts`):
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `id` | uuid | Primary key |
-| `user_id` | uuid | FK to `users` |
-| `project_id` | uuid | FK to `projects` (nullable) |
-| `action` | text | Event type (see below) |
-| `details` | jsonb | Arbitrary metadata |
-| `ip_address` | inet | Client IP |
-| `created_at` | timestamptz | When it happened |
-
-### Tracked actions
-
-| Category | Actions |
-|----------|---------|
-| Auth | `user.register`, `user.login`, `user.password_reset`, `user.token_replay_detected` |
-| Projects | `project.create`, `project.update`, `project.delete` |
-| Files | `file.save`, `file.delete` |
-| Shares | `share.publish`, `share.unpublish` |
-
-Audit inserts are inline in each route handler (`server/routes/auth.ts`, `server/routes/projects.ts`, `server/routes/files.ts`, `server/routes/shares.ts`).
-
-## Granting admin access
-
-There is no self-service role escalation. Set the role directly in the database:
-
-```sql
-UPDATE users SET role = 'admin' WHERE email = 'user@example.com';
-```
-
-See [auth.md](auth.md) for the role system and [../runbook.md](../runbook.md) for production database access.

package/dist/docs-raw/platform/architecture.md

@@ -1,82 +0,0 @@
-# System Architecture
-
-ForgeCAD is a browser-based parametric CAD application. The production stack runs as Docker containers on Hetzner, managed by Kamal 2.
-
-## Stack Overview
-
-```
-Internet
-  |
-Cloudflare
-  |
-kamal-proxy (:80/:443)
-  |
-forgecad web container (Fastify / Node.js)
-  |--- serves SPA (Vite-built React frontend)
-  |--- API routes (/api/*)
-  |--- calls forgecad-backend over Docker network
-  |
-PostgreSQL accessory
-```
-
-**Frontend:** React SPA built with Vite. Three.js (via React Three Fiber) powers the 3D viewport. Monaco Editor provides the code editor. The SPA is served by the same Fastify process that handles API routes.
-
-**Server:** Fastify with Drizzle ORM for database access. Serves both the static SPA bundle and the `/api/*` JSON endpoints from a single process.
-
-**Database:** PostgreSQL for user accounts, project metadata, and application state.
-
-**File storage:** User project files are stored on disk (Docker volume `project-data`), not in the database.
-
-## Deployment Topology
-
-Production uses Kamal deploy configs, not Docker Compose:
-
-| File | Purpose |
-|------|---------|
-| `config/deploy.yml` | Kamal config for the ForgeCAD web app |
-| `config/deploy.backend.yml` | Kamal config for the ForgeCAD backend compute service |
-
-Docker Compose remains useful for local/self-hosted setups, but it is not the production control plane.
-
-## Authentication
-
-JWT-based auth with token rotation:
-
-- **Access tokens:** 15-minute expiry
-- **Refresh tokens:** 7-day expiry, rotated on use
-
-See [auth.md](auth.md) for details on OAuth providers, token flow, and session management.
-
-## URL Routes
-
-| Route | Access | Purpose |
-|-------|--------|---------|
-| `/` | Public | Landing page |
-| `/docs`, `/docs/:slug` | Public | API documentation |
-| `/blog`, `/blog/:slug` | Public | Announcements and tutorials |
-| `/app` | Auth-gated | The CAD editor |
-| `/app?gist=<id>` | Public preview | Shared model from GitHub Gist (read-only until login) |
-| `/app?url=<url>` | Public preview | Shared model from external URL |
-| `/app#code/<file>/<compressed>` | Public preview | Shared model with inline code |
-| `/app?embed=1` | Public | Embed-only viewport (no chrome, for iframes) |
-| `/m/:shareId` | Public | Published model preview (code + 3D viewport) |
-| `/m/:shareId?embed=1` | Public | Published model embed (viewport only) |
-| `/admin` | Admin role | User management, system health, audit log |
-| `/auth/callback/*` | Public | OAuth callback handlers |
-
-## Security
-
-- **Rate limiting:** 100 requests/min per IP; 10 auth attempts per 15 minutes
-- **CORS:** Origin whitelist (no wildcard)
-- **CSP:** Content Security Policy headers on all responses
-- **Path traversal:** Server-side validation on all file access paths
-
-## Related Documentation
-
-- [auth.md](auth.md) -- Authentication and authorization
-- [projects.md](projects.md) -- Project storage and management
-- [sharing.md](sharing.md) -- Model sharing and embeds
-- [admin.md](admin.md) -- Admin panel
-- [email.md](email.md) -- Transactional email
-- [../deployment.md](../deployment.md) -- Environment variables and deployment setup
-- [../runbook.md](../runbook.md) -- Operational procedures and troubleshooting