forgecad 0.9.13 → 0.9.15

package/dist-skill/docs-dev/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-skill/library/forgecad-image-replicator/scripts/compare_images.mjs

@@ -1,289 +0,0 @@
-#!/usr/bin/env node
-
-import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, extname, resolve } from 'node:path';
-import { execFileSync } from 'node:child_process';
-import puppeteer from 'puppeteer-core';
-
-const CHROME_PATHS = [
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
-  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-  '/usr/bin/google-chrome',
-  '/usr/bin/google-chrome-stable',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-  '/snap/bin/chromium',
-];
-
-const MIME_BY_EXT = new Map([
-  ['.png', 'image/png'],
-  ['.jpg', 'image/jpeg'],
-  ['.jpeg', 'image/jpeg'],
-  ['.webp', 'image/webp'],
-  ['.gif', 'image/gif'],
-  ['.bmp', 'image/bmp'],
-  ['.svg', 'image/svg+xml'],
-]);
-
-function usage() {
-  return `Usage:
-  compare_images.mjs <reference-image> <forgecad-render> <output.png> [options]
-
-Options:
-  --height <px>             Panel height in pixels (default: 900)
-  --panel-width <px>        Panel width in pixels (default: max input aspect at --height)
-  --gap <px>                Gap between panels (default: 16)
-  --padding <px>            Outer padding (default: 16)
-  --background <color>      Canvas background (default: #111111)
-  --fit <contain|cover>     Fit mode inside equal panels (default: contain)
-  --labels <left,right>     Labels (default: Reference,ForgeCAD)
-  --no-labels               Disable label band
-  --chrome-path <path>      Chrome or Chromium executable
-  -h, --help                Show help`;
-}
-
-function readValue(argv, index, flag) {
-  const value = argv[index + 1];
-  if (!value || value.startsWith('--')) {
-    throw new Error(`Missing value for ${flag}`);
-  }
-  return value;
-}
-
-function parsePositiveInt(raw, label) {
-  const value = Number.parseInt(raw, 10);
-  if (!Number.isFinite(value) || value <= 0) {
-    throw new Error(`${label} must be a positive integer.`);
-  }
-  return value;
-}
-
-function parseArgs(argv) {
-  if (argv.includes('-h') || argv.includes('--help')) {
-    console.log(usage());
-    process.exit(0);
-  }
-
-  const positionals = [];
-  const options = {
-    height: 900,
-    panelWidth: null,
-    gap: 16,
-    padding: 16,
-    background: '#111111',
-    fit: 'contain',
-    labels: ['Reference', 'ForgeCAD'],
-    chromePath: process.env.CHROME_PATH || null,
-  };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--height') {
-      options.height = parsePositiveInt(readValue(argv, i, arg), '--height');
-      i += 1;
-    } else if (arg === '--panel-width') {
-      options.panelWidth = parsePositiveInt(readValue(argv, i, arg), '--panel-width');
-      i += 1;
-    } else if (arg === '--gap') {
-      options.gap = parsePositiveInt(readValue(argv, i, arg), '--gap');
-      i += 1;
-    } else if (arg === '--padding') {
-      options.padding = parsePositiveInt(readValue(argv, i, arg), '--padding');
-      i += 1;
-    } else if (arg === '--background') {
-      options.background = readValue(argv, i, arg);
-      i += 1;
-    } else if (arg === '--fit') {
-      const fit = readValue(argv, i, arg);
-      if (fit !== 'contain' && fit !== 'cover') {
-        throw new Error('--fit must be contain or cover.');
-      }
-      options.fit = fit;
-      i += 1;
-    } else if (arg === '--labels') {
-      const labels = readValue(argv, i, arg)
-        .split(',')
-        .map((entry) => entry.trim())
-        .filter(Boolean);
-      if (labels.length !== 2) {
-        throw new Error('--labels must contain two comma-separated labels.');
-      }
-      options.labels = labels;
-      i += 1;
-    } else if (arg === '--no-labels') {
-      options.labels = null;
-    } else if (arg === '--chrome-path') {
-      options.chromePath = readValue(argv, i, arg);
-      i += 1;
-    } else if (arg.startsWith('--')) {
-      throw new Error(`Unknown option: ${arg}`);
-    } else {
-      positionals.push(arg);
-    }
-  }
-
-  if (positionals.length !== 3) {
-    throw new Error(`Expected reference, render, and output paths.\n\n${usage()}`);
-  }
-
-  return {
-    referencePath: resolve(positionals[0]),
-    renderPath: resolve(positionals[1]),
-    outputPath: resolve(positionals[2]),
-    ...options,
-  };
-}
-
-function commandPath(name) {
-  try {
-    const found = execFileSync(process.platform === 'win32' ? 'where' : 'which', [name], {
-      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-      .toString()
-      .trim()
-      .split(/\r?\n/)[0];
-    return found || null;
-  } catch {
-    return null;
-  }
-}
-
-function resolveChromePath(explicitPath) {
-  if (explicitPath && existsSync(explicitPath)) return explicitPath;
-  for (const candidate of CHROME_PATHS) {
-    if (existsSync(candidate)) return candidate;
-  }
-  for (const candidate of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'brave-browser', 'microsoft-edge', 'chrome']) {
-    const found = commandPath(candidate);
-    if (found && existsSync(found)) return found;
-  }
-  return null;
-}
-
-async function imageDataUrl(path) {
-  if (!existsSync(path)) {
-    throw new Error(`Image not found: ${path}`);
-  }
-  const ext = extname(path).toLowerCase();
-  const mime = MIME_BY_EXT.get(ext);
-  if (!mime) {
-    throw new Error(`Unsupported image extension "${ext}" for ${path}`);
-  }
-  const bytes = await readFile(path);
-  return `data:${mime};base64,${bytes.toString('base64')}`;
-}
-
-async function main() {
-  const options = parseArgs(process.argv.slice(2));
-  const chromePath = resolveChromePath(options.chromePath);
-  if (!chromePath) {
-    throw new Error('Chrome or Chromium was not found. Pass --chrome-path or set CHROME_PATH.');
-  }
-
-  const [referenceUrl, renderUrl] = await Promise.all([imageDataUrl(options.referencePath), imageDataUrl(options.renderPath)]);
-  const browser = await puppeteer.launch({
-    executablePath: chromePath,
-    headless: true,
-    args: ['--no-sandbox', '--disable-gpu-sandbox'],
-  });
-
-  try {
-    const page = await browser.newPage();
-    const result = await page.evaluate(
-      async (payload) => {
-        const loadImage = (src) =>
-          new Promise((resolveImage, rejectImage) => {
-            const img = new Image();
-            img.onload = () => resolveImage(img);
-            img.onerror = () => rejectImage(new Error('Failed to decode image'));
-            img.src = src;
-          });
-
-        const [reference, render] = await Promise.all([loadImage(payload.referenceUrl), loadImage(payload.renderUrl)]);
-        const panelHeight = payload.height;
-        const maxAspect = Math.max(reference.naturalWidth / reference.naturalHeight, render.naturalWidth / render.naturalHeight);
-        const panelWidth = payload.panelWidth ?? Math.ceil(panelHeight * maxAspect);
-        const labelHeight = payload.labels ? 34 : 0;
-        const canvasWidth = payload.padding * 2 + panelWidth * 2 + payload.gap;
-        const canvasHeight = payload.padding * 2 + labelHeight + panelHeight;
-        const canvas = document.createElement('canvas');
-        canvas.width = canvasWidth;
-        canvas.height = canvasHeight;
-        const ctx = canvas.getContext('2d');
-        ctx.fillStyle = payload.background;
-        ctx.fillRect(0, 0, canvasWidth, canvasHeight);
-
-        const drawLabel = (text, x) => {
-          ctx.fillStyle = 'rgba(255,255,255,0.9)';
-          ctx.font = '600 18px system-ui, -apple-system, BlinkMacSystemFont, sans-serif';
-          ctx.textBaseline = 'top';
-          ctx.fillText(text, x, payload.padding + 4);
-        };
-
-        const drawPanel = (img, x, y) => {
-          const scale =
-            payload.fit === 'cover'
-              ? Math.max(panelWidth / img.naturalWidth, panelHeight / img.naturalHeight)
-              : Math.min(panelWidth / img.naturalWidth, panelHeight / img.naturalHeight);
-          const width = img.naturalWidth * scale;
-          const height = img.naturalHeight * scale;
-          const dx = x + (panelWidth - width) * 0.5;
-          const dy = y + (panelHeight - height) * 0.5;
-
-          ctx.save();
-          ctx.beginPath();
-          ctx.rect(x, y, panelWidth, panelHeight);
-          ctx.clip();
-          ctx.drawImage(img, dx, dy, width, height);
-          ctx.restore();
-
-          ctx.strokeStyle = 'rgba(255,255,255,0.25)';
-          ctx.lineWidth = 1;
-          ctx.strokeRect(x + 0.5, y + 0.5, panelWidth - 1, panelHeight - 1);
-        };
-
-        const leftX = payload.padding;
-        const rightX = payload.padding + panelWidth + payload.gap;
-        const panelY = payload.padding + labelHeight;
-        if (payload.labels) {
-          drawLabel(payload.labels[0], leftX);
-          drawLabel(payload.labels[1], rightX);
-        }
-        drawPanel(reference, leftX, panelY);
-        drawPanel(render, rightX, panelY);
-
-        return {
-          png: canvas.toDataURL('image/png'),
-          width: canvasWidth,
-          height: canvasHeight,
-        };
-      },
-      {
-        referenceUrl,
-        renderUrl,
-        height: options.height,
-        panelWidth: options.panelWidth,
-        gap: options.gap,
-        padding: options.padding,
-        background: options.background,
-        fit: options.fit,
-        labels: options.labels,
-      },
-    );
-
-    const png = Buffer.from(result.png.replace(/^data:image\/png;base64,/, ''), 'base64');
-    await mkdir(dirname(options.outputPath), { recursive: true });
-    await writeFile(options.outputPath, png);
-    console.log(`Wrote ${options.outputPath} (${result.width}x${result.height})`);
-  } finally {
-    await browser.close();
-  }
-}
-
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});