partforge 0.121.0 → 0.122.0

package/src/materials-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/material-swatches.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/parts/bracket.js

@@ -9,7 +9,7 @@
 import { roundedRectPolygon, circleProfile } from "partforge/geometry";
 
 export default {
-  meta: { title: "Cross bracket", units: "mm", background: 0x15181d },
+  meta: { title: "Cross bracket", units: "mm", background: 0x15181d, environment: "workshop" },
   parameters: [
     {
       id: "size",
@@ -58,6 +58,7 @@ export default {
       label: "Cross bracket",
       views: ["bracket"],
       export: { name: "cross-bracket" },
+      display: { material: "powder-coat", color: 0x2b2f36 },
       build: (k, p) => {
         const barH = k.shape2d(roundedRectPolygon(p.span, p.bar, p.corner));
         const barV = k.shape2d(roundedRectPolygon(p.bar, p.span, p.corner));

package/src/parts/hinged-box.js

@@ -6,7 +6,7 @@
 // before any motion. Also shown: an intro camera + markdown description on
 // `open`, a looping autoplay `cycle`, and per-step cameras on `assemble`.
 export default {
-  meta: { title: "Hinged Box", units: "mm" },
+  meta: { title: "Hinged Box", units: "mm", environment: "workshop" },
   parameters: [
     {
       id: "box",
@@ -41,6 +41,7 @@ export default {
       label: "Base",
       views: ["box"],
       export: { name: "base" },
+      display: { material: "walnut" },
       build: (k, p) =>
         k.box({ min: [0, 0, 0], max: [p.width, p.depth, p.height] })
           .cut(k.box({ min: [p.wall, p.wall, p.wall], max: [p.width - p.wall, p.depth - p.wall, p.height + 1] })),
@@ -49,6 +50,7 @@ export default {
       label: "Lid",
       views: ["box"],
       export: { name: "lid" },
+      display: { material: "walnut" },
       build: (k, p) => k.box({ min: [0, 0, p.height], max: [p.width, p.depth, p.height + p.wall] }),
       // Display: swing about the hinge line (rear top edge, axis +X through
       // [0, depth, height]; negative angle opens upward), then the assembly

package/src/parts/material-swatches.js

@@ -0,0 +1,40 @@
+// Dev-only contact sheet for the material library: one 30 mm sample per preset,
+// laid out in a grid, so a change to a preset or the pattern shader can be
+// judged by eye in every environment (materials.html). Not a reference part.
+import { PRESETS } from "../framework/materials/presets.js";
+
+const ids = Object.keys(PRESETS).filter((id) => id !== "default");
+const COLS = 6, PITCH = 40;
+
+const withHole = (k) =>
+  k.box({ size: [30, 30, 12] }).fillet({ r: 3 }).cut(k.cylinder({ r: 5, h: 20 }).translate([0, 0, -4]));
+
+export default {
+  meta: { title: "Material swatches", units: "mm", environment: "studio" },
+  defaults: {},
+  views: { all: { label: "All presets", default: true }, print: { label: "Layer lines" } },
+  parts: {
+    ...Object.fromEntries(ids.map((id, i) => [id.replaceAll("-", "_"), {
+      label: PRESETS[id].label,
+      views: ["all"],
+      build: (k) => withHole(k).translate([(i % COLS) * PITCH, -Math.floor(i / COLS) * PITCH, 0]),
+      display: { material: id },
+    }])),
+    upright_pla: {
+      label: "PLA, displayed upright, printed flat",
+      views: ["print"],
+      build: (k) => k.box({ size: [30, 12, 40] }),
+      // Displayed standing on its Z-tall face; the export pose lies it flat on
+      // its printed layer plane, which is what the layer-line orientation check
+      // in the "Layer lines" view is for.
+      place: (s, { purpose }) => (purpose === "export" ? s.rotateX(90) : s),
+      display: { material: "pla-print", color: 0xe0592a },
+    },
+    flat_pla: {
+      label: "PLA, same pose both ways",
+      views: ["print"],
+      build: (k) => k.box({ size: [30, 12, 40] }).translate([50, 0, 0]),
+      display: { material: "pla-print", color: 0xe0592a },
+    },
+  },
+};

package/src/parts/planter.js

@@ -24,7 +24,7 @@ const ngon = (R, n) => {
 };
 
 export default {
-  meta: { title: "Faceted Planter", units: "mm", background: 0x15181d },
+  meta: { title: "Faceted Planter", units: "mm", background: 0x15181d, environment: "print-bed" },
   parameters: [
     {
       id: "body",
@@ -100,6 +100,7 @@ export default {
       label: "Planter",
       views: ["planter"],
       export: { name: "planter" },
+      display: { material: "pla-print", color: 0xc4622d },
       build: (k, p, d) => {
         const body = k.prism({ points: d.outerPts, h: p.height, scaleTop: p.taper, twist: p.twist }).label("Faceted wall");
         // Hollow it. The cavity is built from z=0 sharing the body's exact twist RATE and

package/src/parts/propeller.js

@@ -113,7 +113,7 @@ export const bladeSections = (p) =>
   });
 
 export default {
-  meta: { title: "Propeller", units: "mm", background: 0x15181d },
+  meta: { title: "Propeller", units: "mm", background: 0x15181d, environment: "studio" },
   parameters: [
     {
       id: "prop",
@@ -173,6 +173,7 @@ export default {
   parts: {
     propeller: {
       label: "Propeller", views: ["propeller"], export: { name: "propeller" },
+      display: { material: "brushed-aluminum" },
       build: (k, p) => {
         const sections = bladeSections(p);
         const bladeUp = p.smooth

package/src/parts/scott-label.js

@@ -71,6 +71,7 @@ export default {
     title: "Editable Layered Label",
     units: "mm",
     background: 0x171a20,
+    environment: "print-bed",
   },
 
   parameters: [
@@ -185,7 +186,7 @@ export default {
     backing: {
       label: "Lower outer layer",
       views: ["backing", "assembly"],
-      display: { color: 0x1e88e5 },
+      display: { material: "pla-print", color: 0x1e88e5 },
       build: (k, p, d) => {
         const rawTextProfile = k.text2d(d.textValue, {
           size: p.textSize,
@@ -209,7 +210,7 @@ export default {
     lettering: {
       label: "Editable lettering",
       views: ["lettering", "assembly"],
-      display: { color: 0xfdd835 },
+      display: { material: "pla-print", color: 0xfdd835 },
       build: (k, p, d) => {
         const rawLetteringProfile = k.text2d(d.textValue, {
           size: p.textSize,

package/src/parts/screw.js

@@ -3,7 +3,7 @@
 // one screwSweep call yields the whole threaded shank with no boolean against a
 // core. See docs/AUTHORING-PARTS.md "Helical & threaded features".
 export default {
-  meta: { title: "Screw", units: "mm", background: 0x15181d },
+  meta: { title: "Screw", units: "mm", background: 0x15181d, environment: "studio" },
   parameters: [
     {
       id: "thread",
@@ -52,6 +52,7 @@ export default {
       label: "Screw",
       views: ["screw"],
       export: { name: "screw" },
+      display: { material: "brushed-stainless" },
       build: (k, p, d) => {
         // Periodic profile: exactly one pitch tall, first radius == last radius.
         const shank = k.screwSweep({

package/types/index.d.ts

@@ -110,6 +110,10 @@ export interface MountElements {
     measure?: HTMLElement | null;
     annotate?: HTMLElement | null;
     railToggle?: HTMLElement | null;
+    /** Realistic-mode toggle (default id `#realistic`). */
+    realistic?: HTMLButtonElement | null;
+    /** Environment picker, an empty `<select>` the mount fills (default id `#environment`). Shown only while realistic. */
+    environment?: HTMLSelectElement | null;
   };
 }
 
@@ -265,6 +269,20 @@ export interface ViewerState {
   camera: { pos: [number, number, number]; target: [number, number, number] } | null;
   projection: "perspective" | "orthographic";
   cutaway: CutawayState | null;
+  /** Always reported by `getViewerState()` — the mode being headed for, so a realistic switch still loading reads `"realistic"` (a failed one settles to `"cad"`). Optional on the way back in (a state saved by an older partforge has none). */
+  renderMode?: RenderMode;
+  /** The realistic environment id, present only when one was CHOSEN (`environment.set`, the picker) — a merely seeded default is left out so the part's own `meta.environment` still applies on remount. An unknown id falls back to `"studio"`. */
+  environment?: string;
+}
+
+/** The viewer's appearance: the drafting view, or physical materials under an environment. */
+export type RenderMode = "cad" | "realistic";
+
+/** What `renderMode.onChange` listeners receive. `busy` while realistic's assets load; `error` when they failed. */
+export interface RenderModeEvent {
+  mode: RenderMode;
+  busy: boolean;
+  error: string | null;
 }
 
 /** Custom controls' transient state, keyed by the param each control owns. Plain JSON. */
@@ -342,6 +360,14 @@ export interface CaptureCurrentOptions {
    * Default false.
    */
   recenter?: boolean;
+  /**
+   * The look to capture in. Omitted: whatever the live view shows. `"cad"`
+   * always renders CAD. `"realistic"` from a CAD view renders realistic only
+   * once the current environment's assets have loaded (this call is
+   * synchronous and cannot wait); before that it falls back to the live look —
+   * `renderViews` is the async path that guarantees realistic.
+   */
+  renderMode?: RenderMode;
 }
 
 export interface CaptureViewOptions {
@@ -500,13 +526,15 @@ export interface PartRuntime {
   /**
    * Canonical-angle captures (fixed poses, framed to the visible assembly,
    * 1024², grid hidden) — sized for feeding a vision model. Defaults to
-   * `["iso", "front", "top"]`; unknown names are dropped.
+   * `["iso", "front", "top"]`; unknown names are dropped. Always the CAD look,
+   * whatever the live render mode — `renderViews` asks for realistic.
    */
   captureViews(viewNames?: CanonicalView[] | string[]): Array<{ view: string; dataUrl: string }>;
   /**
    * One offscreen render of the user's CURRENT framing at a chosen resolution —
    * the showcase capture. Returns a `data:image/jpeg;base64,…` string, or `null`
-   * when disposed or nothing is built yet. Never throws.
+   * when disposed or nothing is built yet. Never throws. Follows the live
+   * render mode unless `opts.renderMode` pins one.
    */
   captureCurrent(opts?: CaptureCurrentOptions): string | null;
   /** The active view (tab) name. Never null once mounted. */
@@ -527,7 +555,7 @@ export interface PartRuntime {
    */
   setActive(active: boolean): void;
   /**
-   * Snapshot the camera, projection and cutaway so a REMOUNT can resume them —
+   * Snapshot the camera, projection, cutaway, render mode and environment so a REMOUNT can resume them —
    * pass the result as the next `mount()`'s `viewerState`. Read at teardown
    * time, so it is the live pose, unlike the camera the viewer persists for a
    * page reload (which only records the end of an orbit drag, and so misses a
@@ -592,6 +620,23 @@ export interface PartRuntime {
   annotate: AnnotateRuntime;
   /** The pick marker's lifetime — hold it on screen and follow it across the canvas. Always present (a no-op stand-in outside `makeHandle` tests). */
   pickMarker: PickMarkerRuntime;
+  /** Realistic render mode (docs "Materials and appearance"). set() resolves to the mode actually in effect — "cad" if assets failed to load. */
+  renderMode: {
+    get(): RenderMode;
+    set(mode: RenderMode): Promise<RenderMode>;
+    onChange(cb: (e: RenderModeEvent) => void): () => void;
+  };
+  /** The realistic environment. set() resolves to the id in effect — a failed switch while realistic reverts, and onChange hears the revert. */
+  environment: {
+    get(): string;
+    set(id: string): Promise<string>;
+    onChange(cb: (id: string) => void): () => void;
+    list(): Array<{ id: string; label: string }>;
+  };
+  /** True when any sub-part names a display.material. */
+  declaresMaterials: boolean;
+  /** Canonical-view renders in a chosen appearance, without switching the live view; "cad" (the default) is exactly captureViews(), CAD in either live mode. */
+  renderViews(viewNames?: CanonicalView[] | string[], opts?: { renderMode?: RenderMode }): Promise<Array<{ view: string; dataUrl: string }>>;
 }
 
 /** Mount a full parametric-part app from a `PartDefinition`. */

package/types/part.d.ts

@@ -48,6 +48,8 @@ export interface PartMeta {
   units?: string;
   /** Scene background as `0xRRGGBB`. */
   background?: number;
+  /** Realistic-mode lighting/ground preset. See docs/AUTHORING-PARTS.md "Materials and appearance". */
+  environment?: "studio" | "workshop" | "print-bed" | "outdoor" | string;
   /** Pin a backend instead of letting the probe route the part. */
   backend?: BackendName;
 }
@@ -383,8 +385,19 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
    * / `refBboxDelta` gate metrics.
    */
   reference?: string;
-  /** Viewer-only override — `color` is `0xRRGGBB`, `opacity` is 0..1. */
-  display?: { color?: number; opacity?: number };
+  /** Viewer-only appearance. See docs/AUTHORING-PARTS.md "Materials and appearance". */
+  display?: {
+    color?: number;
+    opacity?: number;
+    /** A preset id from docs/AUTHORING-PARTS.md "Materials and appearance". */
+    material?: string;
+    roughness?: number;
+    metalness?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    anisotropy?: number;
+    textureScale?: number;
+  };
   /** Filename / object name on export; defaults to the key. */
   export?: { name: string };
 }