partforge 0.121.0 → 0.122.0

package/docs/AUTHORING-PARTS.md

@@ -69,7 +69,7 @@ A part is a default-exported object. Full shape (optional fields marked `?`):
 
 ```js
 export default {
-  meta: { title, units, background? },     // title string; units e.g. "mm"; background = 0xRRGGBB scene colour
+  meta: { title, units, background?, environment? },     // title string; units e.g. "mm"; background = 0xRRGGBB scene colour
   parameters,                              // the control-panel schema (array of sections — see below)
   defaults,                                // flat { paramKey: value } — seeds params + control values
   fonts?,                                  // { name: source } — or (p) => ({ name: source }) when a control drives the typeface
@@ -83,7 +83,7 @@ export default {
       place?: (solid, { view, purpose, p, d }) => Solid,   // optional reposition; default identity
       views,                               // string[] — which views show this sub-part
       enabled?: (p) => boolean,            // optional — gate a conditional sub-part
-      display?: { color?, opacity? },      // optional viewer-only override (0xRRGGBB / 0..1) — e.g. a reference/ghost part
+      display?: { color?, opacity?, material?, …overrides }, // viewer-only appearance — see "Materials and appearance"
       export?: { name },                   // filename/object name on export; defaults to the key
       reference?: string,                  // name of a declared import — measure() computes a deviation fact against it (see below)
     },
@@ -294,6 +294,97 @@ and asks for the existing positional view argument
 
 ---
 
+## Materials and appearance
+
+A sub-part's `display` block says how it LOOKS. Appearance never changes
+geometry, exports (other than 3MF colour, below), `measure` or `verify`, and a
+mistake in it never fails a build — lint warns and the viewer falls back.
+
+```js
+parts: {
+  body:   { build: …, display: { material: "anodized-aluminum", color: 0xb3261e } },
+  knob:   { build: …, display: { material: "abs-plastic", color: 0x111111, roughness: 0.25 } },
+  gasket: { build: …, display: { material: "rubber" } },
+},
+meta: { title: "…", units: "mm", environment: "studio" },
+```
+
+- `material` — a preset id from the table below. Without one the sub-part keeps
+  the default look.
+- `color` — the base colour (`0xRRGGBB`). With a preset it is the TINT. Presets
+  marked tintable are normally coloured this way (anodizing, plastic, paint);
+  the others have an intrinsic colour (brass) but still accept one.
+- Overrides — each clamped to its range: `roughness` (0–1), `metalness` (0–1),
+  `clearcoat` (0–1), `clearcoatRoughness` (0–1), `anisotropy` (0–1), `textureScale` (0.01–1000).
+  Transmission, index of refraction, sheen and iridescence come only from a preset.
+- `opacity` — unchanged: a ghost stays a ghost and casts no shadow.
+- **One material per sub-part.** Something that needs two finishes (a knurled
+  grip in rubber on an aluminium body) is two sub-parts.
+
+**Where it shows.** The CAD view (with feature lines) shows each material's
+colour, flattened so dark materials stay readable. **Realistic** mode — the
+viewer's toggle — shows the full material under environment lighting, with a
+ground and soft shadow and no feature lines. The part never moves when the
+mode changes.
+
+**3D-print layer lines** (`pla-print`, `petg-print`) run perpendicular to the
+**export** pose's +Z — the way the part will be printed, not the way it is
+displayed. If the lines run the wrong way, fix the export pose with `place()`
+(`purpose: "export"`), not the material. Wood, carbon fibre and SLS grain are
+fixed to the sub-part, so they never slide when the camera or an animation
+moves.
+
+**`textureScale` is millimetres, and what it measures depends on the preset's
+pattern** — so a value copied from one preset family is wrong on another (0.2
+on oak shrinks the grain to a 0.2 mm tile, i.e. invisible noise):
+
+| Pattern | Presets | `textureScale` means | Default |
+| --- | --- | --- | --- |
+| layer lines | `pla-print`, `petg-print` | layer height | 0.2 |
+| SLS grain | `nylon-sls` | grain size | 0.15 |
+| wood | `oak`, `walnut` | size of one texture tile (the grain repeats every this many mm) | 250 (`oak`), 400 (`walnut`) |
+| carbon weave | `carbon-fiber` | size of one texture tile | 48 |
+
+Presets without a pattern ignore it.
+
+**3MF export** carries each sub-part's colour (its `color`, else its preset's
+colour), so a multi-colour print opens in a slicer already split and coloured.
+A part with no `color` or `material` exports exactly as before.
+
+| Preset | Name | Tintable | Use |
+| --- | --- | --- | --- |
+| `machined-aluminum` | Machined aluminium | — | Bare CNC-milled aluminium, fine tool marks, satin sheen. |
+| `brushed-aluminum` | Brushed aluminium | — | Directionally brushed aluminium panels and enclosures. |
+| `anodized-aluminum` | Anodized aluminium | yes | Dyed anodized aluminium; tint with `color` (e.g. red, black, blue). |
+| `bead-blasted-aluminum` | Bead-blasted aluminium | — | Matte, even-textured aluminium (laptop-shell finish). |
+| `brushed-stainless` | Brushed stainless steel | — | Brushed 304 stainless: kitchen, marine and fastener hardware. |
+| `polished-chrome` | Polished chrome | — | Mirror chrome plating; shows the environment strongly. |
+| `black-oxide-steel` | Black-oxide steel | — | Blackened steel tooling and fasteners with a slight oily sheen. |
+| `cast-iron` | Cast iron | — | Raw sand-cast iron: dark, rough and matte. |
+| `titanium` | Titanium | — | Bare titanium: slightly warm grey, satin. |
+| `brass` | Brass | — | Yellow brass fittings and decorative hardware. |
+| `copper` | Copper | — | Bare copper: busbars, heat sinks, decorative parts. |
+| `bronze` | Bronze | — | Cast bronze bushings and sculpture. |
+| `powder-coat` | Powder coat | yes | Durable textured paint over metal; tint with `color`. |
+| `painted-metal` | Painted metal | yes | Glossy enamel or automotive-style paint; tint with `color`. |
+| `pla-print` | PLA print | yes | FDM-printed PLA with visible layer lines; tint with `color`. |
+| `petg-print` | PETG print | yes | FDM-printed PETG: glossier than PLA, visible layers; tint with `color`. |
+| `resin-print` | Resin print | yes | SLA/MSLA resin print: smooth, faintly waxy; tint with `color`. |
+| `nylon-sls` | Nylon SLS | yes | Powder-bed nylon: matte, grainy, usually white or dyed black. |
+| `abs-plastic` | ABS plastic | yes | Injection-moulded ABS housings and knobs; tint with `color`. |
+| `clear-acrylic` | Clear acrylic | yes | Transparent PMMA/polycarbonate windows and covers; tint for coloured acrylic. |
+| `rubber` | Rubber | yes | Matte elastomer: gaskets, feet, grips; tint with `color`. |
+| `oak` | Oak | — | Light oak with open grain. |
+| `walnut` | Walnut | — | Dark oiled walnut. |
+| `carbon-fiber` | Carbon fibre | — | 2x2 twill carbon fibre under clear coat. |
+
+**Environments** (`meta.environment`, default `studio`; viewers can switch):
+`studio` (neutral soft boxes, paper sweep), `workshop` (warm interior, unfinished
+maple table), `print-bed` (a dim, hard-lit enclosure over a standard-size PEI build plate (180, 220, 256 or 350 mm) marked with its size), `outdoor` (overcast sky,
+concrete).
+
+---
+
 ## Geometry: the kernel / `Solid` API
 
 `build` receives a backend-agnostic `kernel` (`k`). It returns and combines `Solid`
@@ -2498,7 +2589,7 @@ stylesheet). `mount` looks up these element IDs:
 | `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` and opens the resolved default (see the "Which view the viewer opens on" rule above) |
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
-| `#viewbar` with `#annotate` / `#measure` / `#cutaway` / `#reframe` / `#theme` | optional viewer controls (omit any you don't want) |
+| `#viewbar` with `#annotate` / `#measure` / `#cutaway` / `#reframe` / `#realistic` / `#environment` / `#theme` | optional viewer controls (omit any you don't want) |
 | `#panel` | the full-height controls rail (`class="pf-rail"`); programmatic hosts pass `elements.rail` instead |
 | `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#reframe`/`#theme`. A sibling of `#viewbar`, not a child of it: give it `class="pf-float-rail-toggle"` and it floats at the stage's top right |
 
@@ -2506,6 +2597,17 @@ Copy `demo.html` and change the title, the panel heading, and the `<script src>`
 workers are spawned from your one worker entry (`name` = `"manifold"` for preview/STL/3MF,
 `"occt"` for STEP — handled for you).
 
+**`#realistic` (a `<button>`) / `#environment` (an empty `<select>`) are the
+realistic-mode viewbar controls**, resolved by id or as `elements.chrome.realistic`
+/ `elements.chrome.environment`. Both optional and independent: supply `#realistic`
+alone for a bare toggle, or add `#environment` too and `mount` fills it with the
+part's available environments (see "Materials and appearance" above) and keeps it
+in sync — hidden while the view is in CAD mode, showing the environment in effect
+once realistic lands. Omit either and drive `runtime.renderMode` /
+`runtime.environment` from your own UI instead (see below). Both preferences
+persist across reloads the same way the theme does, and are carried in
+`viewerState` (below), which outranks what is stored.
+
 **`#reframe` is supported but no longer shipped.** The framework's own pages dropped
 the button on 2026-08-20: clicking a face, edge or corner on the view cube reframes
 too, so a separate control was one more thing in a crowded bottom-right corner. The
@@ -2660,6 +2762,58 @@ them, and the sketch that gets sent is misaligned, not merely mis-labelled.
 Deliberately unguarded, the same way it's always been free to call
 `setCameraState` during Sketch.
 
+### `runtime.renderMode`, `runtime.environment`, `runtime.renderViews`, `runtime.declaresMaterials`
+
+For an embedder driving realistic mode from its own UI instead of (or in
+addition to) the `#realistic` / `#environment` viewbar controls above:
+
+- `runtime.renderMode` — `{ get(), set(mode), onChange(cb) }` where `mode` is
+  `"cad"` or `"realistic"`. `set()` resolves to the mode actually in effect —
+  `"cad"` if the realistic environment's assets fail to load — and
+  `onChange` receives `{ mode, busy, error }` so a host can show its own
+  loading/error state. Same shape as `runtime.projection`. It drives the live
+  view, and `runtime.captureCurrent()` follows it by default (a "capture from
+  viewer" captures what the user sees). It never changes what an agent sees:
+  `runtime.captureViews()` is always CAD, in either live mode, and a
+  realistic agent render is only ever an explicit
+  `renderViews(…, { renderMode: "realistic" })`.
+- `runtime.captureCurrent({ renderMode })` — pins the showcase capture's look
+  instead of following the live view. `"cad"` always works. `"realistic"` from
+  a CAD view works only once the current environment's assets have loaded
+  (the call is synchronous and can't wait for them); before that it falls
+  back to the live look. Use `renderViews` when realistic must be guaranteed.
+- `runtime.environment` — `{ get(), set(id), onChange(cb), list() }` for the
+  realistic environment (`"studio"` | `"workshop"` | `"print-bed"` |
+  `"outdoor"`, per "Materials and appearance" above). `list()` returns every
+  environment as `[{ id, label }]`, for building your own picker. `set()`
+  resolves to the id actually in effect; a failed switch while realistic is
+  showing reverts to the environment still on screen, and `onChange` hears the
+  revert too.
+- `runtime.declaresMaterials` — `true` when any sub-part names a
+  `display.material`. A part with none still supports realistic mode (every
+  sub-part just renders under the library's `default` look), so use this to
+  decide whether to surface the realistic toggle at all, not whether it works.
+- `await runtime.renderViews(viewNames, { renderMode? })` — the appearance-aware
+  sibling of `runtime.captureViews` (canonical angles, framed to the visible
+  assembly, grid hidden): `{ renderMode: "cad" }` (the default) is exactly
+  `captureViews` — CAD whatever the live view shows — and `{ renderMode: "realistic" }` borrows the realistic look
+  for the capture — waiting on the chosen environment's assets — **without**
+  switching the live view. Rejects if the realistic assets fail to load.
+
+Both preferences round-trip through `mount()`'s `viewerState`: a
+previous mount's `runtime.getViewerState()` carries `viewerState.renderMode`
+(`"cad"` or `"realistic"`) and, only when the viewer's environment was
+actually CHOSEN rather than merely defaulted from `meta.environment`,
+`viewerState.environment`. `renderMode` reports the mode the user is **headed
+for**, not only the one on screen: a realistic restore or switch that's still
+loading reports `"realistic"`, so a host that remounts on every edit (as an
+embedder applying edits by remounting typically does) doesn't drop the
+in-flight choice — a load that ultimately fails still settles back to
+`"cad"`. Pass `viewerState` back into the next `mount()` call to resume both
+where the previous mount left them; omit it on a first mount and the viewer
+restores its own persisted choice instead, the same way it does for the
+camera and projection.
+
 ### The annotation payload's camera block
 
 `onAnnotationSend(payload)` receives a `camera` block in two frames — `world`
@@ -3121,6 +3275,13 @@ motion — translate/rotate — never a reshape) (both errors). An untrusted pro
 nothing either way and stays silent, matching `animation-track-rebuilds`'s own
 trust handling.
 
+**Appearance** (all warnings) — `unknown-material` (a `display.material` the
+library does not know; the viewer shows the default look), `unknown-environment`
+(`meta.environment` not known; realistic mode uses `studio`),
+`material-key-unknown` (a `display` key that is not colour, opacity, material
+or one of the six overrides; ignored), `material-override-clamped` (an override
+outside its range, or not a number; clamped).
+
 **Geometry imports** — `import-unknown-name` (a build calls `k.import` with a
 name the part's `imports` field doesn't declare — this throws at build time;
 lint reaches it in microseconds instead), `import-mesh-on-occt` (a declared

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.121.0",
+  "version": "0.122.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -132,11 +132,13 @@
     "@eslint/js": "^10.0.1",
     "@fontsource-variable/geist": "^5.3.0",
     "@fontsource-variable/geist-mono": "^5.3.0",
+    "@monogrid/gainmap-js": "^3.4.0",
     "eslint": "^10.10.0",
     "globals": "^17.12.0",
     "happy-dom": "^20.10.6",
     "knip": "^6.35.1",
     "playwright": "^1.49.0",
+    "sharp": "^0.35.4",
     "typescript": "^5.9.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9"

package/src/app-materials.js

@@ -0,0 +1,23 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import materialSwatchesPart from "./parts/material-swatches.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only contact sheet app for the material library (parts/material-swatches.js).
+// Identical wiring to app.js — the only thing that differs per part is which
+// definition you import and which worker entry you point at. `npm run dev`, then
+// open /materials.html. Not part of the production build — check materials.html
+// by eye after any preset or shader change (see AGENTS.md "Architecture").
+// Dev-only: the handle is stashed on window so scripts/check-app.mjs can drive
+// the embedding contract (runtime.captureCurrent) the way an embedder would.
+window.__pfRuntime = mount(materialSwatchesPart, {
+  createWorker: (name) =>
+    new Worker(new URL("./materials-worker.js", import.meta.url), { type: "module", name }),
+  onAnnotationSend: (payload) => {
+    window.__pfLastAnnotation = payload;
+    console.log("annotation payload", payload);
+  },
+});

package/src/framework/app.css

@@ -476,7 +476,7 @@ button.action:disabled { opacity: .5; cursor: default; }
 /* keyboard focus ring shared across the panel's interactive controls */
 .seg button:focus-visible, select.preset:focus-visible, .dl-row button:focus-visible,
 button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible, #viewbar button:focus-visible,
-.pf-view-select:focus-visible,
+#viewbar select:focus-visible, .pf-view-select:focus-visible,
 .pf-viewcube-toggle:focus-visible, .pf-float-rail-toggle:focus-visible, .pf-sketch-toolbar button:focus-visible {
   outline: none;
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
@@ -595,6 +595,21 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 #viewbar button:disabled:hover { color: var(--pf-muted-2); background: transparent; }
 #viewbar button:hover { color: var(--pf-text); background: var(--pf-surface-2); }
 #viewbar button.on { background: var(--pf-accent); color: var(--pf-on-accent); }
+/* Realistic view (realistic-controls.js). The toggle is an ordinary viewbar
+   button that pulses while its environment loads; the environment picker is a
+   native <select> — the accessible choice on a phone — dressed as a viewbar
+   button, shown only while realistic. Keyed on `#viewbar select` rather than
+   an id so a host's own element in the pill gets the same look. */
+#viewbar button[data-busy] { animation: pf-busy-pulse .8s ease-in-out infinite alternate; }
+@keyframes pf-busy-pulse { from { opacity: 1; } to { opacity: .45; } }
+@media (prefers-reduced-motion: reduce) { #viewbar button[data-busy] { animation: none; opacity: .6; } }
+#viewbar select {
+  height: 34px; padding: 0 8px; border: 0; border-radius: var(--pf-radius-control);
+  background: transparent; color: var(--pf-muted-2); cursor: pointer;
+  font: inherit; font-size: 13px;
+}
+#viewbar select:hover { color: var(--pf-text); background: var(--pf-surface-2); }
+#viewbar select[hidden] { display: none; }
 
 /* Sketch-mode toolbar: the #viewbar pill idiom, top-centre, owning the mode
    while the viewbar itself is hidden (mount toggles both).

package/src/framework/cutaway.js

@@ -493,6 +493,17 @@ export function createCutaway({
     return true;
   }
 
+  // Swap one sub-part's SOURCE material (realistic mode). The render set
+  // re-derives its clipped clone and cap colour from it and reassigns
+  // mesh.material for the current enabled state.
+  function refreshSubpartMaterial(name, meshMaterial) {
+    if (disposed) return false;
+    const entry = renderSets.get(name);
+    if (!entry) return false;
+    entry.renderSet.refreshSourceMaterial(meshMaterial);
+    return true;
+  }
+
   // Per-frame maintenance while the cutaway is on: the gizmo rescales for the
   // camera, and every visible section re-slices its outline if anything it
   // depends on moved. Both are cheap no-ops when nothing changed.
@@ -581,6 +592,7 @@ export function createCutaway({
     setVisible,
     setEnabled,
     resyncSubpart,
+    refreshSubpartMaterial,
     reset,
     flip,
     getState,

package/src/framework/geometry/arc-math.js

@@ -0,0 +1,27 @@
+// Pure arc math, paper-free: circumcircle center + signed sweep for the arc through three
+// points. Split out of paper-bridge.js so callers that only need this number crunching (the
+// oracle's shape-probe.js, contour-ops.js's corner/tangent math) don't pull in paper-core —
+// paper-bridge.js still re-exports arcCenterAndSweep so every existing importer of it is
+// unaffected.
+
+// Circumcircle center + signed sweep for the arc through (p0, via, to) — the sweep is the
+// one passing through `via` (sign-free, winding-free), same recovery as profile.js's
+// sampleArc. Returns null for a collinear (degenerate) triple. Shared by arcToCubicSegments
+// (paper-bridge.js) and contour-ops.js's jointTangents (arc tangents are ⊥ radius, oriented by dA's sign).
+export function arcCenterAndSweep(p0, via, to) {
+  const [ax, ay] = p0, [bx, by] = via, [cx, cy] = to;
+  const d = 2 * (ax * (by - cy) + bx * (cy - ay) + cx * (ay - by));
+  if (Math.abs(d) < 1e-12) return null;
+  const sa = ax*ax + ay*ay, sb = bx*bx + by*by, sc = cx*cx + cy*cy;
+  const ux = (sa * (by - cy) + sb * (cy - ay) + sc * (ay - by)) / d;
+  const uy = (sa * (cx - bx) + sb * (ax - cx) + sc * (bx - ax)) / d;
+  const r = Math.hypot(ax - ux, ay - uy);
+  const a0 = Math.atan2(ay - uy, ax - ux);
+  const av = Math.atan2(by - uy, bx - ux);
+  const a1 = Math.atan2(cy - uy, cx - ux);
+  const twoPi = 2 * Math.PI;
+  const ccw = (x) => { let v = x % twoPi; if (v < 0) v += twoPi; return v; };
+  const dCCW = ccw(a1 - a0), vCCW = ccw(av - a0);
+  const dA = vCCW <= dCCW ? dCCW : dCCW - twoPi;
+  return { center: [ux, uy], r, dA };
+}

package/src/framework/geometry/contour-corners.js

@@ -0,0 +1,130 @@
+// Paper-free corner/tangent math for the contour IR, split out of contour-ops.js so the
+// oracle's shape-probe.js (and anything else that only needs a shape's corners/tangents, not
+// its booleans/transforms) doesn't pull in paper-core through contour-ops.js's own
+// paper-bridge.js import. Imports only profile.js, shape2d-regions.js and arc-math.js — never
+// paper-bridge.js or contour-ops.js, which is what keeps this leaf paper-free.
+import { isPathContour, tessellateContour, pointsToContour, closeContourGap } from "./profile.js";
+import { ringArea } from "./shape2d-regions.js";
+import { arcCenterAndSweep } from "./arc-math.js";
+
+export const WINDING_SEGS = 64;   // tessellation LOD for orientation/containment sampling
+
+export const isPointList = (x) => Array.isArray(x) && x.length > 0 && Array.isArray(x[0]);
+// pointsToContour always closes explicitly; a raw {start,segments} contour (hand-authored
+// via pathProfile, or handed back from a Shape2D's own stored regions) might not —
+// closeContourGap is a no-op when it's already closed, so every ring liftProfile hands to
+// contour-ops' corner/transform/query functions is guaranteed explicitly closed.
+export const liftContour = (c) => (isPointList(c) ? pointsToContour(c) : closeContourGap(c));
+
+export function liftProfile(input) {
+  if (input && input._shape2d) return { kind: "regions", regions: input.toContours() };
+  if (isPointList(input)) return { kind: "points", regions: [{ outer: pointsToContour(input), holes: [] }] };
+  if (isPathContour(input)) return { kind: "contour", regions: [{ outer: closeContourGap(input), holes: [] }] };
+  if (Array.isArray(input) && input.every((r) => r && r.outer))
+    return { kind: "regions", regions: input.map((r) => ({ outer: liftContour(r.outer), holes: (r.holes ?? []).map(liftContour) })) };
+  if (input && input.outer)
+    return { kind: "region", regions: [{ outer: liftContour(input.outer), holes: (input.holes ?? []).map(liftContour) }] };
+  throw new Error("contour-ops: input must be [[x,y],…], a {start,segments} contour, {outer,holes}, or a region array");
+}
+
+export const contourIsCCW = (c) => ringArea(tessellateContour(c, WINDING_SEGS)) >= 0;
+
+// ── Corner model ────────────────────────────────────────────────────────────
+// profileCorners() walks a contour's joints and reports each non-smooth one: the interior
+// angle, whether it's convex (material-relative — see below), and the segment kinds either
+// side of it. jointTangents() is the shared per-vertex tangent computation, reused by Task 6.
+
+export const SMOOTH_JOINT_DEG = 1;
+
+// Unit tangent of segment `s` (from `from`) at its start (dir=+1) or end (dir=-1 → arrival direction).
+// Exported for contour-winding.js's _chain: junction ordering at a curved pinch point needs
+// the exact endpoint tangent, not an approximation (via/c1/c2 are NOT control points that
+// happen to sit near the tangent — via in particular is a THROUGH point near mid-sweep, so
+// from->via is systematically biased by about sweep/4). This recovers it exactly for arcs
+// (perpendicular to the radius at the recovered center, oriented by the sweep's sign) and
+// cubics (including the degenerate c1===from case, where the true tangent comes from c2).
+export function segTangent(from, s, atStart) {
+  const norm = ([x, y]) => { const L = Math.hypot(x, y) || 1; return [x / L, y / L]; };
+  if (s.c1) {
+    if (atStart) {
+      const d = [s.c1[0] - from[0], s.c1[1] - from[1]];
+      return norm(Math.hypot(d[0], d[1]) > 1e-9 ? d : [s.c2[0] - from[0], s.c2[1] - from[1]]);
+    }
+    const d = [s.to[0] - s.c2[0], s.to[1] - s.c2[1]];
+    return norm(Math.hypot(d[0], d[1]) > 1e-9 ? d : [s.to[0] - s.c1[0], s.to[1] - s.c1[1]]);
+  }
+  if (s.via) {
+    // tangent ⊥ radius, oriented along the sweep (recover center like arcToCubicSegments)
+    const c = arcCenterAndSweep(from, s.via, s.to);          // {center:[x,y], dA} or null
+    if (!c) return norm([s.to[0] - from[0], s.to[1] - from[1]]);
+    const p = atStart ? from : s.to;
+    const r = [p[0] - c.center[0], p[1] - c.center[1]];
+    const t = c.dA >= 0 ? [-r[1], r[0]] : [r[1], -r[0]];
+    return norm(t);
+  }
+  return norm([s.to[0] - from[0], s.to[1] - from[1]]);
+}
+
+export function jointTangents(contour) {  // per vertex i: tangent arriving at and leaving vertex i
+  const n = contour.segments.length;
+  const pts = [contour.start, ...contour.segments.map((s) => s.to)];
+  return contour.segments.map((_, i) => {
+    const prevSeg = contour.segments[(i - 1 + n) % n];
+    const prevFrom = pts[(i - 1 + n) % n];
+    return {
+      point: pts[i],
+      inTan: segTangent(prevFrom, prevSeg, false),
+      outTan: segTangent(pts[i], contour.segments[i], true),
+    };
+  });
+}
+
+export const segType = (s) => (s.c1 ? "cubic" : s.via ? "arc" : "line");
+
+export function contourCorners(contour) {
+  const ccw = contourIsCCW(contour);
+  const n = contour.segments.length;
+  const out = [];
+  jointTangents(contour).forEach(({ point, inTan, outTan }, i) => {
+    const cross = inTan[0] * outTan[1] - inTan[1] * outTan[0];
+    const dot = Math.min(1, Math.max(-1, inTan[0] * outTan[0] + inTan[1] * outTan[1]));
+    const turnDeg = (Math.atan2(Math.abs(cross), dot) * 180) / Math.PI;
+    if (turnDeg < SMOOTH_JOINT_DEG) return;
+    const leftTurn = cross > 0;
+    out.push({
+      index: i, point: [point[0], point[1]],
+      interiorAngleDeg: ccw === leftTurn ? 180 - turnDeg : 180 + turnDeg,
+      convex: leftTurn === ccw,
+      segTypes: [segType(contour.segments[(i - 1 + n) % n]), segType(contour.segments[i])],
+    });
+  });
+  return out;
+}
+
+// Two numbers on every corner, and they are NOT interchangeable. `index` is the joint's
+// vertex number within its own contour (what buildCornerOpRing, simplify and the lofts
+// key on); `position` is the corner's place in THIS returned list — the one
+// `{corners: {indices}}` selects by. They diverge as soon as a contour has a smooth
+// joint (a collinear midpoint, a G1 arc-line join), and on region input `index`
+// restarts per ring while `position` runs on through the flattened order.
+const withPositions = (corners) => corners.map((c, position) => ({ ...c, position }));
+
+export function profileCorners(input) {
+  const { kind, regions } = liftProfile(input);
+  if (kind === "points" || kind === "contour") return withPositions(contourCorners(regions[0].outer));
+  const out = [];
+  regions.forEach((rg, regionIndex) => {
+    for (const c of contourCorners(rg.outer)) out.push({ regionIndex, ring: "outer", ...c });
+    rg.holes.forEach((h, hi) => { for (const c of contourCorners(h)) out.push({ regionIndex, ring: { hole: hi }, ...c }); });
+  });
+  return withPositions(out);
+}
+
+export function cubicAt(p0, c1, c2, p1, t) {
+  const u = 1 - t;
+  return [0, 1].map((k) => u * u * u * p0[k] + 3 * u * u * t * c1[k] + 3 * u * t * t * c2[k] + t * t * t * p1[k]);
+}
+export function cubicDeriv(p0, c1, c2, p1, t) {
+  const u = 1 - t;
+  return [0, 1].map((k) => 3 * u * u * (c1[k] - p0[k]) + 6 * u * t * (c2[k] - c1[k]) + 3 * t * t * (p1[k] - c2[k]));
+}

package/src/framework/geometry/contour-ops.js

@@ -1,32 +1,19 @@
-import { isPathContour, tessellateContour, pointsToContour, reverseContour, closeContourGap } from "./profile.js";
+import { reverseContour, closeContourGap } from "./profile.js";
 import { ringArea, pointInRing } from "./shape2d-regions.js";
 import { arcToCubicSegments, arcCenterAndSweep, paperScope, toPaperPath, toContour, toOpenContour } from "./paper-bridge.js";
+import { liftProfile, contourIsCCW, contourCorners, cubicAt, cubicDeriv } from "./contour-corners.js";
 
 // Re-exported so existing importers (test/contour-ops-lift.test.js and others) keep
-// working unchanged — the definitions live in profile.js (the contour-IR home) so
-// paper-bridge.js can use them without importing this module (which already imports
+// working unchanged — the definition lives in profile.js (the contour-IR home) so
+// paper-bridge.js can use it without importing this module (which already imports
 // paper-bridge.js; importing back would cycle).
-export { pointsToContour, reverseContour };
-
-const WINDING_SEGS = 64;   // tessellation LOD for orientation/containment sampling
-
-const isPointList = (x) => Array.isArray(x) && x.length > 0 && Array.isArray(x[0]);
-// pointsToContour always closes explicitly; a raw {start,segments} contour (hand-authored
-// via pathProfile, or handed back from a Shape2D's own stored regions) might not —
-// closeContourGap is a no-op when it's already closed, so every ring liftProfile hands to
-// contour-ops' corner/transform/query functions is guaranteed explicitly closed.
-const liftContour = (c) => (isPointList(c) ? pointsToContour(c) : closeContourGap(c));
-
-export function liftProfile(input) {
-  if (input && input._shape2d) return { kind: "regions", regions: input.toContours() };
-  if (isPointList(input)) return { kind: "points", regions: [{ outer: pointsToContour(input), holes: [] }] };
-  if (isPathContour(input)) return { kind: "contour", regions: [{ outer: closeContourGap(input), holes: [] }] };
-  if (Array.isArray(input) && input.every((r) => r && r.outer))
-    return { kind: "regions", regions: input.map((r) => ({ outer: liftContour(r.outer), holes: (r.holes ?? []).map(liftContour) })) };
-  if (input && input.outer)
-    return { kind: "region", regions: [{ outer: liftContour(input.outer), holes: (input.holes ?? []).map(liftContour) }] };
-  throw new Error("contour-ops: input must be [[x,y],…], a {start,segments} contour, {outer,holes}, or a region array");
-}
+export { reverseContour };
+
+// The paper-free corner/tangent/lift math now lives in contour-corners.js — so the oracle's
+// shape-probe.js can use profileCorners()/cubicAt() without pulling in paper-core through
+// this module's own paper-bridge.js import below — re-exported here so every existing
+// importer of these names from contour-ops.js keeps working unchanged.
+export { liftProfile, contourIsCCW, SMOOTH_JOINT_DEG, segTangent, jointTangents, profileCorners, cubicAt } from "./contour-corners.js";
 
 export function restoreProfile(kind, regions) {
   if (kind === "regions") return regions;
@@ -43,8 +30,6 @@ export function restoreProfile(kind, regions) {
   return outer;   // curves were introduced — upgrade to a contour
 }
 
-export const contourIsCCW = (c) => ringArea(tessellateContour(c, WINDING_SEGS)) >= 0;
-
 export function ensureRegionWinding(region) {
   return {
     outer: contourIsCCW(region.outer) ? region.outer : reverseContour(region.outer),
@@ -116,97 +101,6 @@ export function mirrorProfile(input, axis) {
   return transformProfile(input, [a, b, b, -a, px - a * px - b * py, py - b * px + a * py]);
 }
 
-// ── Corner model ────────────────────────────────────────────────────────────
-// profileCorners() walks a contour's joints and reports each non-smooth one: the interior
-// angle, whether it's convex (material-relative — see below), and the segment kinds either
-// side of it. jointTangents() is the shared per-vertex tangent computation, reused by Task 6.
-
-export const SMOOTH_JOINT_DEG = 1;
-
-// Unit tangent of segment `s` (from `from`) at its start (dir=+1) or end (dir=-1 → arrival direction).
-// Exported for contour-winding.js's _chain: junction ordering at a curved pinch point needs
-// the exact endpoint tangent, not an approximation (via/c1/c2 are NOT control points that
-// happen to sit near the tangent — via in particular is a THROUGH point near mid-sweep, so
-// from->via is systematically biased by about sweep/4). This recovers it exactly for arcs
-// (perpendicular to the radius at the recovered center, oriented by the sweep's sign) and
-// cubics (including the degenerate c1===from case, where the true tangent comes from c2).
-export function segTangent(from, s, atStart) {
-  const norm = ([x, y]) => { const L = Math.hypot(x, y) || 1; return [x / L, y / L]; };
-  if (s.c1) {
-    if (atStart) {
-      const d = [s.c1[0] - from[0], s.c1[1] - from[1]];
-      return norm(Math.hypot(d[0], d[1]) > 1e-9 ? d : [s.c2[0] - from[0], s.c2[1] - from[1]]);
-    }
-    const d = [s.to[0] - s.c2[0], s.to[1] - s.c2[1]];
-    return norm(Math.hypot(d[0], d[1]) > 1e-9 ? d : [s.to[0] - s.c1[0], s.to[1] - s.c1[1]]);
-  }
-  if (s.via) {
-    // tangent ⊥ radius, oriented along the sweep (recover center like arcToCubicSegments)
-    const c = arcCenterAndSweep(from, s.via, s.to);          // {center:[x,y], dA} or null
-    if (!c) return norm([s.to[0] - from[0], s.to[1] - from[1]]);
-    const p = atStart ? from : s.to;
-    const r = [p[0] - c.center[0], p[1] - c.center[1]];
-    const t = c.dA >= 0 ? [-r[1], r[0]] : [r[1], -r[0]];
-    return norm(t);
-  }
-  return norm([s.to[0] - from[0], s.to[1] - from[1]]);
-}
-
-export function jointTangents(contour) {  // per vertex i: tangent arriving at and leaving vertex i
-  const n = contour.segments.length;
-  const pts = [contour.start, ...contour.segments.map((s) => s.to)];
-  return contour.segments.map((_, i) => {
-    const prevSeg = contour.segments[(i - 1 + n) % n];
-    const prevFrom = pts[(i - 1 + n) % n];
-    return {
-      point: pts[i],
-      inTan: segTangent(prevFrom, prevSeg, false),
-      outTan: segTangent(pts[i], contour.segments[i], true),
-    };
-  });
-}
-
-const segType = (s) => (s.c1 ? "cubic" : s.via ? "arc" : "line");
-
-function contourCorners(contour) {
-  const ccw = contourIsCCW(contour);
-  const n = contour.segments.length;
-  const out = [];
-  jointTangents(contour).forEach(({ point, inTan, outTan }, i) => {
-    const cross = inTan[0] * outTan[1] - inTan[1] * outTan[0];
-    const dot = Math.min(1, Math.max(-1, inTan[0] * outTan[0] + inTan[1] * outTan[1]));
-    const turnDeg = (Math.atan2(Math.abs(cross), dot) * 180) / Math.PI;
-    if (turnDeg < SMOOTH_JOINT_DEG) return;
-    const leftTurn = cross > 0;
-    out.push({
-      index: i, point: [point[0], point[1]],
-      interiorAngleDeg: ccw === leftTurn ? 180 - turnDeg : 180 + turnDeg,
-      convex: leftTurn === ccw,
-      segTypes: [segType(contour.segments[(i - 1 + n) % n]), segType(contour.segments[i])],
-    });
-  });
-  return out;
-}
-
-// Two numbers on every corner, and they are NOT interchangeable. `index` is the joint's
-// vertex number within its own contour (what buildCornerOpRing, simplify and the lofts
-// key on); `position` is the corner's place in THIS returned list — the one
-// `{corners: {indices}}` selects by. They diverge as soon as a contour has a smooth
-// joint (a collinear midpoint, a G1 arc-line join), and on region input `index`
-// restarts per ring while `position` runs on through the flattened order.
-const withPositions = (corners) => corners.map((c, position) => ({ ...c, position }));
-
-export function profileCorners(input) {
-  const { kind, regions } = liftProfile(input);
-  if (kind === "points" || kind === "contour") return withPositions(contourCorners(regions[0].outer));
-  const out = [];
-  regions.forEach((rg, regionIndex) => {
-    for (const c of contourCorners(rg.outer)) out.push({ regionIndex, ring: "outer", ...c });
-    rg.holes.forEach((h, hi) => { for (const c of contourCorners(h)) out.push({ regionIndex, ring: { hole: hi }, ...c }); });
-  });
-  return withPositions(out);
-}
-
 // ── Fillet / chamfer ─────────────────────────────────────────────────────────
 // Resolve opts.corners against a flat corner list (contourCorners()'s order, or
 // profileCorners()'s flattened order for region/regions input — {indices} always
@@ -280,14 +174,6 @@ const normalize2 = ([x, y]) => { const L = Math.hypot(x, y) || 1; return [x / L,
 const rot90 = ([x, y]) => [-y, x];
 const addScaled = (p, v, s) => [p[0] + v[0] * s, p[1] + v[1] * s];
 
-export function cubicAt(p0, c1, c2, p1, t) {
-  const u = 1 - t;
-  return [0, 1].map((k) => u * u * u * p0[k] + 3 * u * u * t * c1[k] + 3 * u * t * t * c2[k] + t * t * t * p1[k]);
-}
-function cubicDeriv(p0, c1, c2, p1, t) {
-  const u = 1 - t;
-  return [0, 1].map((k) => 3 * u * u * (c1[k] - p0[k]) + 6 * u * t * (c2[k] - c1[k]) + 3 * t * t * (p1[k] - c2[k]));
-}
 // Exact de Casteljau split of cubic (p0,c1,c2,p1) at t → two exact cubic pieces.
 export function splitCubic(p0, c1, c2, p1, t) {
   const lerp = (a, b) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];