forgecad 0.9.14 → 0.9.16

package/dist/docs-raw/blueprint-first.md

@@ -1,145 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 3
----
-
-# Blueprint-First Philosophy
-
-## Code Should Read Like a Mechanical Blueprint
-
-ForgeCAD is a **mechanical compiler**. The user inputs design intent — dimensions, constraints, relationships — and the engine handles the geometry. If a mechanical feature can be dimensioned on a 2D drawing without explicit X/Y coordinates, a user should be able to model it in ForgeCAD without calculating those coordinates.
-
-We are building a geometry engine, not a math test.
-
-## The Trigonometry Tax
-
-Every time a user writes `Math.sin()` or `Math.cos()` to place a bolt hole, position a circular pattern, or compute a tangent point, our API has failed them. This is the **Trigonometry Tax** — the cost of translating declarative engineering intent into imperative Cartesian math.
-
-The tax is real and measurable. In our own example library, ~40 of 250+ files contain manual trig. The same patterns repeat: circular positioning, polygon vertex layout, rotation result computation, polar-to-cartesian conversion. Each one is a place where the API should have provided an abstraction but didn't.
-
-## The Core Pillars
-
-### Pillar I: Intent-Driven Constraints over Explicit Coordinates
-
-Traditional CAD-as-code requires calculating exact center points and intersections. ForgeCAD uses **constraint-driven pathing** — users define the knowns (radii, angles, distances), and the solver calculates the implicit intersections.
-
-```javascript
-// The old way — calculating tangent arc intercepts by hand
-const cx = r1 * Math.cos(angle) + offset * Math.sin(angle);
-const cy = r1 * Math.sin(angle) - offset * Math.cos(angle);
-
-// The ForgeCAD way — declare intent, solver handles geometry
-sketch.route([
-  { tangent: circleA },
-  { fillet: 17 },
-  { tangent: circleB },
-]);
-```
-
-### Pillar II: Topological Selection
-
-Hardcoding vertex indices or exact 3D coordinates to apply fillets makes models brittle. If a base dimension changes, the coordinates change, and the build breaks. ForgeCAD borrows from the DOM: **select geometry via topological queries, not hardcoded indices.**
-
-```javascript
-// Brittle — breaks if topology changes
-body.fillet(5, edgeIndex[14]);
-
-// ForgeCAD — semantic edge selection
-fillet(body, 5, { parallel: [0, 0, 1], convex: true });
-fillet(body, 3, selectEdges(body, { atZ: 0 }));
-```
-
-### Pillar III: Mechanical First-Class Citizens
-
-Primitives should not be limited to circles, rectangles, and polygons. Mechanical engineering relies on standard features that are tedious to build from scratch. If a machinist has a specific tool bit for it, the API should have a specific primitive for it.
-
-```javascript
-// Holes with real mechanical features — not raw boolean subtraction
-shape.hole('top', { diameter: 11, depth: 20,
-  counterbore: { diameter: 18, depth: 5 },
-  thread: { designation: 'M10' },
-});
-
-// Standard mechanical profiles
-slot(30, 10);
-arcSlot({ pitchRadius: 50, sweep: 60, width: 12 });
-lib.spurGear({ module: 2, teeth: 24 });
-```
-
-### Pillar IV: Relative Workplanes
-
-Everything in mechanical design is relative. You don't drill a hole at `[15.5, 30.2, 100.0]` in global space. You drill a hole on the top face of the flange, centered on the lug. The API must support dynamic coordinate systems that attach to existing geometry.
-
-```javascript
-// Global coordinates — fragile, unreadable
-const hole = circle2d(5).extrude(20).translate(15.5, 30.2, 100.0);
-
-// Relative to geometry — moves with the parent
-circle2d(5).onFace(flange, 'top', { u: 10, v: 0 }).extrude(-20);
-```
-
-### Pillar V: No Manual Math for Standard Layout
-
-If a user has to import `Math.sin` to place elements in a circle, compute `Math.sqrt(3)` for an equilateral triangle, or manually convert degrees to radians, our API has a gap. Standard layout operations are first-class:
-
-```javascript
-// Circular layout — no trig
-const positions = circularLayout(12, radius);
-
-// Polygon vertex positions — no sqrt(3)
-const vertices = polygonVertices(3, radius);
-
-// Polar positioning — no sin/cos
-shape.translatePolar(radius, angleDeg);
-```
-
-## The Anti-Patterns
-
-### 1. No sin/cos in user code for standard layout
-If a user imports `Math.sin` to place a bolt hole, we have a missing abstraction. We provide polar coordinates, patterns, and layout helpers natively.
-
-### 2. No magic shrinkwraps without explicit control
-Connections between shapes must be explicit. "Connect Shape A to Shape B with a tangent arc of R15" — not a black-box convex hull that guesses intent.
-
-### 3. No silent failures
-If a fillet radius is too large, or a tangent route can't be solved, the API throws a descriptive mechanical error — not a generic engine crash. (See also: CLAUDE.md "No Silent Fallbacks" rule.)
-
-### 4. No coordinate math for relative positioning
-If a feature is defined relative to another feature (a hole on a face, a boss centered on a lug), the API must express that relationship directly — not force the user to compute the absolute position.
-
-## Design Gate
-
-**Every new public API method must pass this test:**
-
-> Can the user accomplish this without `Math.sin`, `Math.cos`, `Math.atan2`, manual degree-to-radian conversion, or computing intermediate Cartesian coordinates from polar/angular intent?
-
-If the answer is no, the API needs a higher-level alternative. The raw math path can still exist for power users, but the common case must be trig-free.
-
-## Ergonomics in JavaScript
-
-JavaScript lacks Python's `with` statement, so ForgeCAD relies on **method chaining** and **callback scopes** for clean, fluid modeling:
-
-```javascript
-// Fluid chaining — sketch to solid to features
-const part = circle2d(50)
-  .extrude(15)
-  .fillet(5, { atZ: 0 });
-
-// Callback workplane — scoped 2D ops on a 3D face
-shape.onFace('top', (face) => {
-  face.subtract(
-    circularPattern(circle2d(5.5), 6, { radius: 32.5 })
-  );
-});
-```
-
-## Architecture Constraints
-
-- **TypeScript native.** Autocomplete and compile-time checking for mechanical parameters are mandatory.
-- **B-Rep capable.** Topological naming and precise filleting require a real CAD kernel (Manifold for mesh, OCCT for B-Rep).
-- **Immutable geometry, mutable builders.** Underlying geometry is immutable for predictable undo/redo. Builder classes maintain state for ergonomic chaining.
-- **Degrees at the API boundary.** All user-facing angles are in degrees. Radians are an internal implementation detail.
-
-## Summary
-
-We are not building a 3D drawing tool. We are building a **mechanical compiler**. The user inputs the blueprint's design intent, and our API handles the geometry.

package/dist/docs-raw/cli-monetization.md

@@ -1,112 +0,0 @@
-# CLI Monetization Strategy
-
-## The Model: Sublime Text Now, Cursor Later
-
-ForgeCAD follows a phased monetization strategy informed by how real software companies make money — not by how they try to prevent piracy.
-
-### Phase 1: Honor System (Now)
-
-Ship a compiled binary with a local license gate. Production export commands stay free and show a clear commercial-use message; Pro-only render/capture commands show a clear upgrade message.
-
-**Why this works:**
-- Sublime Text makes $5-25M/year with zero enforcement (nag popup only)
-- WinRAR makes $20-40M/year with zero enforcement (40-day trial that never expires)
-- JetBrains makes $593M/year despite being cracked constantly
-- The pattern: individuals who crack it weren't going to pay. Enterprises must pay (legal compliance, audit risk, IT procurement). Pirates who learn ForgeCAD become advocates inside companies that buy licenses.
-
-**What we ship:**
-- Compiled native binary via `bun build --compile --minify` (source not trivially readable)
-- Local JWT license validation at `~/.forgecad/license.json`
-- Production outputs marked with commercial-use guidance, not blocked
-- Pro-only render/capture commands blocked with helpful message + free alternatives
-- `forgecad license activate/deactivate/status` commands
-
-**What we accept:**
-- A developer can bypass the local check in 30 minutes
-- String literals (error messages, API names) are visible via `strings`
-- This is fine. The gate converts honest users; it doesn't stop determined pirates.
-
-### Phase 2: Enterprise Features (Soon)
-
-Add features that enterprises need and individuals don't care about:
-- License server (floating seats, team management, usage reporting)
-- Audit log (who exported what, when)
-- SSO/SAML integration
-- Priority support channel
-
-These features don't need anti-piracy because they're inherently organizational. A solo developer doesn't need a license server.
-
-### Phase 3: Server-Side Pro Features (Later)
-
-Move high-value compute to run on the ForgeCAD server after the security model is ready. The CLI uploads the model, the server processes it, the CLI downloads the result.
-
-**Why this is piracy-proof:** The code for server-only rendering, optimization, and future compute-heavy workflows never ships to the user. You can't crack what you don't have.
-
-**Proven by:**
-- Cursor: $2B ARR — the editor is free, AI calls are server-side
-- Figma: $1B revenue — all rendering is server-side
-- Onshape: acquired for $470M — 100% browser-based, nothing local to crack
-
-## Feature Tiers
-
-| Tier | Price | Features |
-|------|-------|----------|
-| **Free** | $0 | Editor, dev server, run scripts, render PNG, exports including STEP/BREP/report/layout, all checks, debug tools |
-| **Pro** | $15-25/mo | Commercial coverage, render-hq (Blender), capture GIF/MP4, 500 MB cloud storage, support for production workflows |
-| **Team** | $40-60/seat/mo | Everything in Pro + license server, floating seats, audit log, SSO, priority support |
-
-### Why this split?
-
-**Free tier** includes everything needed to learn ForgeCAD, build models, export files, and 3D print. This is the funnel — hobbyists, students, and evaluators use this. It's genuinely useful, not a crippled demo.
-
-**Pro tier** covers the work professionals need to pay for: client work, employer work, funded projects, products for sale, closed commercial IP, larger hosted storage, support, and Pro-only render/capture tools. Exact and manufacturing exports remain free actions with production/commercial reminders.
-
-**Team tier** gates organizational features that individuals don't need.
-
-## What NOT to Do
-
-### Don't rewrite in a compiled language for code protection
-SolidWorks is C++ and it's cracked (SolidSquad). AutoCAD is C++ and it's cracked. The language doesn't matter — Ghidra/IDA Pro can reverse-engineer any native binary. The cost (rewriting years of work, losing the JS API that makes ForgeCAD special) far outweighs the marginal protection gain.
-
-### Don't add aggressive DRM
-Dassault embeds forensic signatures in SolidWorks files and sues pirates — this generates "many millions" in settlements but also generates resentment. For a small product trying to build a community, aggressive enforcement is counterproductive.
-
-### Don't make the free tier useless
-Ondsel (commercial FreeCAD) died in 2 years. Open-source CAD has near-zero commercial traction. But the opposite extreme — locking everything behind a paywall — kills adoption. The free tier must be genuinely useful.
-
-### Don't ship source maps
-Claude Code accidentally shipped `.map` files in npm v2.1.88. Within hours, the entire 1,900-file TypeScript codebase was extracted, mirrored to GitHub (1,100+ stars), and reverse-engineered. `.npmignore` must exclude `*.map`, `*.ts` source, and `tsconfig.json`.
-
-## The Gabe Newell Principle
-
-> "Piracy is almost always a service problem, not a pricing problem."
-
-Steam proved this — Russia went from "don't bother, too much piracy" to Valve's largest European market once they localized and shipped same-day.
-
-**Applied to ForgeCAD:** Make the paid version more convenient than the cracked one:
-- Automatic updates (the binary self-updates, cracked copies don't)
-- Cloud project sync (your models available everywhere)
-- Share links (one-click sharing from the editor)
-- Support (access to help when stuck)
-- Team features (collaboration, permissions)
-
-People pay for convenience and reliability, not because they can't find a crack.
-
-## Distribution
-
-| Channel | Format | Audience |
-|---------|--------|----------|
-| **npm** (`npm install -g forgecad`) | Minified `cli.js` (no source maps) | Primary channel |
-| **forgecad.io** | Web editor (no install) | Evaluators, casual users |
-
-ForgeCAD users write `.forge.js` files — they already have Node.js. npm is the only CLI distribution channel we need to maintain.
-
-A compiled native binary build script exists (`npm run build:binary`) for potential future Homebrew distribution, but compiled binaries offer no additional source protection over minified JS (the source is stored as plain text in the binary's `__BUN` section). The binary is not worth maintaining as a separate channel until user volume justifies it.
-
-### Build
-
-```
-TypeScript source → tsup (ESM bundle, 2.5MB) → dist-cli/forgecad.js
-```
-
-**Never ship source maps.** `.npmignore` must exclude `*.map`, `*.ts` source, and `tsconfig.json`.

package/dist/docs-raw/coding-best-practices.md

@@ -1,120 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 1
----
-
-# Coding Best Practices
-
-## Minimal Implementation
-
-Write only the code needed to solve the problem. No verbose implementations, no speculative features.
-
-## TypeScript
-
-- Use explicit types for function parameters and return values
-- Avoid `any` — use `unknown` or proper types
-- Prefer interfaces for object shapes
-
-## React Components
-
-- Functional components only
-- Inline styles for simplicity (no CSS files unless necessary)
-- Extract reusable logic to custom hooks or store actions
-
-### Stable References in Render Bodies
-
-Never use `?? []`, `?? {}`, or inline fallback literals in a component render body if the value flows (directly or transitively) into a `useMemo`/`useCallback`/`useEffect` dependency array. Each render creates a new reference, which silently invalidates every downstream memo.
-
-```tsx
-// BAD — new [] every render, breaks every useMemo that depends on `items`
-const items = config?.items ?? [];
-
-// GOOD — stable reference across renders
-const items = useMemo(() => config?.items ?? [], [config]);
-```
-
-Use `useMemo` for any derived-with-fallback value that feeds into other hooks.
-
-## State Management
-
-- All global state lives in `forgeStore.ts`
-- Use Zustand selectors to prevent unnecessary re-renders
-- Keep actions pure and synchronous where possible
-
-## Performance
-
-### Geometry Operations
-
-- Manifold operations are expensive — minimize boolean ops
-- Cache geometry results when parameters don't change
-- Use debouncing for real-time updates
-
-### React Rendering
-
-- Use Zustand selectors to prevent unnecessary re-renders
-- Memoize expensive computations with `useMemo`
-- Keep component tree shallow
-
-## Linting & Formatting
-
-[Biome](https://biomejs.dev/) handles both linting and formatting for all TS/JS code.
-
-```bash
-npm run lint          # check for lint issues (no changes)
-npm run lint:fix      # auto-fix lint issues
-npm run format        # auto-format all files
-```
-
-Biome runs as part of `npm run check:suite`. Configuration lives in `biome.json` at the repo root.
-
-## Self-Review Before Commit
-
-1. Remove console.logs and debug code
-2. Check for unused imports
-3. Verify TypeScript has no errors
-4. Test the change works as intended
-5. Read the diff — does it make sense?
-
-### What to Look For
-
-- Does this solve the problem with minimal code?
-- Are there edge cases not handled?
-- Is the code readable without comments?
-- Does it follow existing patterns?
-
-## API Naming: Methods Read Like Sentences
-
-Public API method names must read like natural English. Prefer verbose, intuitive names over short, ambiguous ones. The method name alone should tell you exactly what it does — no options objects or magic strings needed to disambiguate.
-
-```ts
-// BAD — technical jargon, not a sentence
-shape.rotateAxisAngle([0,1,0], 45)
-
-// GOOD — reads like a sentence
-shape.rotateX(45)                               // "rotate X 45 degrees"
-shape.rotateY(45)                               // "rotate Y 45 degrees"
-shape.rotateZ(45)                               // "rotate Z 45 degrees"
-shape.rotate([0, 1, 0], 45)                     // "rotate around axis"
-shape.rotateZ(45, { pivot: [10, 0, 0] })        // "rotate Z at pivot"
-
-shape.scale(2)                                   // "scale by 2" (from center)
-shape.scaleAround(pivot, 2)                      // "scale around pivot"
-
-shape.mirror([1,0,0])                           // "mirror along X" (through center)
-shape.mirrorThrough(point, [1,0,0])             // "mirror through point"
-```
-
-Rules:
-- The **bare method** (`rotate`, `scale`, `mirror`) does the common-sense default (operates relative to the shape's own center)
-- **Longer names** make the reference point explicit — no ambiguity
-- **No string literals** as behavior selectors (`'center'`, `'origin'`)
-- **No options objects** to disambiguate what should be separate methods
-
-## Runtime Global Namespace
-
-Do not add new lowercase injected globals to `.forge.js` scripts. Existing lowercase globals such as `box`, `union`, and `loft` are established core vocabulary; new domain helpers must live under a PascalCase namespace or class such as `Product.materials`, `Product.profiles`, or `Shape.fromSlices`.
-
-The repo enforces this in `npm run check:suite -- --profile smoke`. If a lowercase global truly must be added for compatibility, it needs an explicit API review and an allowlist update in `cli/check-runtime-globals.ts`.
-
-## File length
-Keep files under 200 lines. If a file grows beyond that, consider splitting it into smaller, focused files.