partforge 0.125.0 → 0.127.0

package/README.md

@@ -108,6 +108,7 @@ const runtime = mount(part, {
   },
   onBuild: ({ status, ms, error }) => {},   // per accepted build: "success" | "error"
   onPick: ({ selection, label, prompt, token }) => {}, // programmatic click-to-select
+  pickHint: "Click to edit",                // hover-tooltip nudge while onPick is set (null = none)
 });
 await runtime.ready;   // first successful build (rejects on a first-build error)
 runtime.setHostPane("rail");  // narrow layout only: show just the controls
@@ -221,7 +222,10 @@ full contract.
 back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready
 sentence, `token` the compact form, `selection` the raw object. When `onPick` is
 set, the `?pick` / `?pickserver` URL modes are ignored (one click listener ever
-live); hover labels stay always-on.
+live); hover labels stay always-on, and gain a `pickHint` line under the name
+("Click to edit" by default; pass your own wording, or `null` for none). Hover
+never tints the surface under the pointer — a per-face highlight read as "only
+this spot is clickable".
 
 ## Authoring guide
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.125.0",
+  "version": "0.127.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",

package/src/framework/app.css

@@ -1039,6 +1039,10 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 .pf-hover-tip .pf-hover-sub { color: var(--pf-muted); font-size: 11px; margin-left: 7px; }
 #pf-hover-tip .pf-hover-sub:empty,
 .pf-hover-tip .pf-hover-sub:empty { display: none; }
+#pf-hover-tip .pf-hover-hint,
+.pf-hover-tip .pf-hover-hint { color: var(--pf-muted); font-size: 10.5px; margin-top: 1px; }
+#pf-hover-tip .pf-hover-hint:empty,
+.pf-hover-tip .pf-hover-hint:empty { display: none; }
 
 /* request-a-pick: agent prompt banner, floated top-centre well below the part tabs,
    laid out like a chat message (avatar + text). Slides/fades in when shown; themed. */

package/src/framework/materials/patterns.js

@@ -85,23 +85,79 @@ vec3 pfTriplanarNormal(vec3 p, vec3 n, float scale) {
 }
 `;
 
+// Layer lines are 0.2 mm, so at an ordinary viewing distance a layer spans a
+// few pixels or less, and point-sampling the bead profile per pixel aliased
+// into moiré (worst in the specular, through the bead normals). So one layer's
+// profile is baked into a small repeating texture sampled by layer height, and
+// the GPU's mipmaps band-limit it. Channels: R = groove shade, G = bead slope
+// (encoded slope/6 + 0.5), B = slope^2 / 9. A mip level averages G and B
+// separately, so B - G^2 is the slope VARIANCE inside the pixel — the ridges it
+// can no longer show — which widens the specular lobe instead (Toksvig / LEAN
+// mapping), so a far wall keeps its satin sheen rather than turning glossy.
+export const LAYER_PROFILE_WIDTH = 256;
+// Gradient scale on the profile lookup (+0.58 mip). A box-filtered mip chain at
+// 1x still carries the full fundamental at 2 px per layer (its 2-texel level),
+// right at Nyquist, which banded across a whole-part view; 1.5 clears that and
+// keeps the lines crisp close up (2 visibly softened them).
+const LAYER_BLUR = "1.5";
+
+// One layer's bead, t running -1 (a seam) through 0 (the crest) to 1 (the next
+// seam): the groove shade darkens the 35% of each half-bead nearest a seam, and
+// the slope is a round bead's (t / sqrt(1 - t^2)), clamped to ±3 where it goes
+// vertical. (The procedural version darkened the CREST instead — its ridge was
+// |t|, not 1 - |t| — half a layer off the valleys its own normals drew.)
+export function layerProfileData(width = LAYER_PROFILE_WIDTH) {
+  const data = new Uint8Array(width * 4);
+  for (let i = 0; i < width; i++) {
+    const t = ((i + 0.5) / width) * 2 - 1;
+    const g = Math.min(1, (1 - Math.abs(t)) / 0.35);
+    const groove = g * g * (3 - 2 * g);
+    const slope = Math.min(3, Math.max(-3, t / Math.sqrt(Math.max(1 - t * t, 0.04))));
+    data[i * 4] = Math.round(groove * 255);
+    data[i * 4 + 1] = Math.round((slope / 6 + 0.5) * 255);
+    data[i * 4 + 2] = Math.round((slope * slope / 9) * 255);
+    data[i * 4 + 3] = 255;
+  }
+  return data;
+}
+
+// One texture shared by every layer-lines material, built on first use.
+let layerProfileTex = null;
+function layerProfileTexture() {
+  if (layerProfileTex) return layerProfileTex;
+  const t = new THREE.DataTexture(layerProfileData(), LAYER_PROFILE_WIDTH, 1, THREE.RGBAFormat, THREE.UnsignedByteType);
+  t.wrapS = THREE.RepeatWrapping;
+  t.wrapT = THREE.ClampToEdgeWrapping;
+  t.magFilter = THREE.LinearFilter;
+  t.minFilter = THREE.LinearMipmapLinearFilter;
+  t.generateMipmaps = true;
+  t.colorSpace = THREE.NoColorSpace;
+  t.needsUpdate = true;
+  return (layerProfileTex = t);
+}
+
+const FRAG_DECL_LAYERS = "uniform sampler2D pfLayerMap;\n";
+
 // Per-kind fragment code, injected after <roughnessmap_fragment> so it can
 // modulate both diffuseColor (already written by <map_fragment>) and roughnessFactor.
 const FRAG_BODY = {
+  // Declared at main() scope, not in a block: FRAG_NORMAL reads the same
+  // profile sample (pfLayer) rather than looking it up again.
   "layer-lines": `
+  float pfH = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;   // in layers
+  // fract() keeps the texel coordinate small (hundreds of layers x 256 texels
+  // loses sub-texel precision in the sampler); the explicit gradients are the
+  // unwrapped height's, so the wrap at each seam doesn't drop to the 1x1 mip.
+  vec4 pfLayer = textureGrad(pfLayerMap, vec2(fract(pfH), 0.5),
+    vec2(dFdx(pfH) * ${LAYER_BLUR}, 0.0), vec2(dFdy(pfH) * ${LAYER_BLUR}, 0.0));
   {
-    float h = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;
-    float ridge = abs(fract(h) - 0.5) * 2.0;            // 0 at a layer seam, 1 mid-layer
-    float groove = smoothstep(0.0, 0.35, ridge);
-    // Anti-alias: fwidth(h) is layers per pixel. Where a layer spans fewer
-    // than ~6 px the band fades to its mean over a period (0.825: the groove
-    // ramps over 35% of it, the rest is flat), and past ~2.5 px it is gone —
-    // point-sampling finer layers than that is what aliased into moiré.
-    groove = mix(0.825, groove, 1.0 - smoothstep(0.16, 0.4, fwidth(h)));
+    float groove = pfLayer.r;
     diffuseColor.rgb *= mix(0.9, 1.0, groove); // the normal map (FRAG_NORMAL) carries most of the relief
     roughnessFactor = clamp(roughnessFactor + (1.0 - groove) * 0.18, 0.0, 1.0);
     // Filament mottling: a fine grain (~0.17 mm) over slow blotches (~2 mm),
     // fixed to the part, so a print doesn't read as flat injection-moulded plastic.
+    // Hash noise, not a noise volume: a mipmapped 64^3 texture measured ~10%
+    // slower per frame on an M1 Max (a filtered 3D fetch reads 16 texels).
     float mottle = pfNoise(vPfObjPos * 6.0) * 0.6 + pfNoise(vPfObjPos * 0.51) * 0.4;
     diffuseColor.rgb *= mix(0.893, 1.047, mottle);
     roughnessFactor = clamp(roughnessFactor + (mottle - 0.5) * 0.084, 0.0, 1.0);
@@ -149,15 +205,14 @@ const FRAG_BODY = {
 // layer is a round bead, so across one layer the surface normal swings from
 // facing down (bottom of the bead) through straight out to facing up, along
 // the print direction projected onto the surface. Faces parallel to the layers
-// (tops and bottoms) get no ridges, as on a real print. Same fwidth fade as the
-// colour bands, so far-away layers don't alias.
+// (tops and bottoms) get no ridges, as on a real print. The slope comes from the
+// same mip-filtered profile sample as the colour bands, and the slope variance
+// the filter averaged away goes into roughness: alpha^2 += var(tilt).
 const FRAG_NORMAL = {
   "layer-lines": `
   {
-    float h = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;
-    float aa = 1.0 - smoothstep(0.16, 0.4, fwidth(h));
-    float t = fract(h) * 2.0 - 1.0;                       // -1 at a seam, 0 bead crest, 1 next seam
-    float slope = clamp(t / sqrt(max(1.0 - t * t, 0.04)), -3.0, 3.0);
+    float slope = pfLayer.g * 6.0 - 3.0;
+    float slopeVar = max(pfLayer.b * 9.0 - slope * slope, 0.0);
     vec3 up = normalize(vPfPrintUpView);
     // NOT normalised: its length is how steeply the surface cuts across the
     // layers (1 on a vertical wall, 0 on a face parallel to them), so ridges fade
@@ -165,7 +220,10 @@ const FRAG_NORMAL = {
     // full-strength tilt in a direction set by rounding noise, flipping sign
     // wherever the face sat on a layer boundary — a visible patch.
     vec3 along = up - normal * dot(normal, up);
-    normal = normalize(normal + along * slope * 0.35 * aa);
+    normal = normalize(normal + along * slope * 0.35);
+    // tilt = slope * 0.35 * |along|, so var(tilt) = slopeVar * 0.35^2 * |along|^2
+    float a = roughnessFactor * roughnessFactor;
+    roughnessFactor = min(sqrt(sqrt(a * a + slopeVar * 0.1225 * dot(along, along))), 1.0);
   }`,
   // Wood replaces the view-space normal with its triplanar normal map, built in
   // object space and carried to view space through the normal matrix. A
@@ -216,7 +274,11 @@ export function setGrainAxis(material, axis) {
 export function applyPattern(material, { kind, scale = 1, printFrame, texture, normalMap, roughnessMap, roughnessMean = 0.5, normalScale = 1, grain = "u" } = {}) {
   if (!kind || !FRAG_BODY[kind]) return material;
   const wood = kind === "wood";
+  const layers = kind === "layer-lines";
   const uniforms = {
+    ...(layers ? {
+      pfLayerMap: { value: layerProfileTexture() },
+    } : {}),
     pfPatternScale: { value: scale },
     pfPrintFrame: { value: new THREE.Matrix4().fromArray(printFrame ?? new THREE.Matrix4().toArray()) },
     pfPatternMap: { value: texture ?? null },
@@ -236,7 +298,7 @@ export function applyPattern(material, { kind, scale = 1, printFrame, texture, n
       .replace("#include <common>", `#include <common>\n${VERT_DECL}${wood ? VERT_DECL_NM : ""}`)
       .replace("#include <begin_vertex>", `#include <begin_vertex>\n${VERT_BODY}${wood ? VERT_BODY_NM : ""}`);
     shader.fragmentShader = shader.fragmentShader
-      .replace("#include <common>", `#include <common>\n${FRAG_DECL}${wood ? FRAG_DECL_WOOD : ""}`)
+      .replace("#include <common>", `#include <common>\n${FRAG_DECL}${wood ? FRAG_DECL_WOOD : ""}${layers ? FRAG_DECL_LAYERS : ""}`)
       .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>\n${FRAG_BODY[kind]}`)
       .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>\n${FRAG_NORMAL[kind] ?? ""}`);
   };

package/src/framework/mount.js

@@ -419,7 +419,7 @@ function createCleanupStack() {
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit, onAnnotationSend,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, pickHint = "Click to edit", onDownload, onViewChange, onParamsCommit, onAnnotationSend,
                               fontCatalog,
                               imageCatalog,
                               onAssetUpload,
@@ -497,7 +497,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       onRailLayout: () => railChrome.layoutChanged?.(),
     });
     cleanup.defer(() => paneTabs.detach());
-    const hover = attachHoverLabels(viewer, { part, tooltip }); // always-on hover inspection (no-op on touch-only devices)
+    // Always-on hover inspection (no-op on touch-only devices). With onPick the
+    // host acts on a click, so the tooltip nudges toward it with `pickHint`
+    // (a host passes its own wording, or null for none).
+    const hover = attachHoverLabels(viewer, { part, tooltip, hint: onPick ? pickHint : null });
     cleanup.defer(() => hover.detach());
     const ui = createStatusUi({ ...els.status, exports: [els.exports.stl, els.exports.step, els.exports.threeMf] });
     cleanup.defer(() => ui.setStatus(""));

package/src/framework/selection/hover.js

@@ -1,15 +1,19 @@
 // Always-on hover inspection: a cursor-following tooltip naming the feature +
-// sub-part under the pointer, and an overlay mesh highlighting the feature's
-// surface. Feature names come from Solid.label() in the part's build, carried
-// per-triangle in the mesh payload (geometry.userData.featureIds/features).
+// sub-part under the pointer. Feature names come from Solid.label() in the
+// part's build, carried per-triangle in the mesh payload
+// (geometry.userData.featureIds/features).
+//
+// There is deliberately NO surface highlight: tinting just the feature under
+// the pointer read as "only this face is clickable", and people stopped
+// clicking elsewhere on the part. `hint` (e.g. "Click to edit") adds a line
+// under the name when a click does something — mount passes it with onPick.
 import { createTooltipPresenter } from "../tooltip.js";
 import { raycastViewer } from "./raycast.js";
-import { createFeatureHighlight } from "./feature-highlight.js";
 import { runCleanupSteps } from "../teardown.js";
 
 export function attachHoverLabels(
   viewer,
-  { part, schedule = (cb) => requestAnimationFrame(cb), tooltip } = {},
+  { part, schedule = (cb) => requestAnimationFrame(cb), tooltip, hint = null } = {},
 ) {
   // Hover is a mouse idiom — skip entirely on touch-only devices. The stub
   // still answers the WHOLE interface: mount.js calls setSuppressed from the
@@ -25,8 +29,6 @@ export function attachHoverLabels(
   let presentationToken;
   let hasPresented = false;
 
-  const highlight = createFeatureHighlight(viewer);
-
   const subLabel = (name) => part.parts[name]?.label ?? name;
 
   function hide() {
@@ -35,7 +37,6 @@ export function attachHoverLabels(
       tooltipPresenter.hide(presentationToken);
       presentationToken = undefined;
     }
-    highlight.clear();
   }
 
   function show(hit, x, y) {
@@ -45,7 +46,7 @@ export function attachHoverLabels(
     } else {
       content = { title: subLabel(hit.subPart), subtitle: "" };
     }
-    highlight.show(hit);
+    if (hint) content.hint = hint;
     if (hasPresented) {
       hasPresented = false;
       tooltipPresenter.hide(presentationToken);
@@ -119,7 +120,6 @@ export function attachHoverLabels(
         () => viewer.domElement.removeEventListener("pointerup", onUp),
         () => viewer.domElement.removeEventListener("pointerleave", onLeave),
         hide,
-        () => highlight.dispose(),
         () => { if (ownsTooltip) tooltipPresenter.dispose(); },
       ], "feature hover cleanup failed");
     },

package/src/framework/tooltip.js

@@ -14,7 +14,10 @@ export function createTooltipPresenter({ id = "pf-hover-tip" } = {}) {
   const title = document.createElement("b");
   const subtitle = document.createElement("span");
   subtitle.className = "pf-hover-sub";
-  element.append(title, subtitle);
+  // A call-to-action line under the name ("Click to edit"); empty = hidden.
+  const hint = document.createElement("div");
+  hint.className = "pf-hover-hint";
+  element.append(title, subtitle, hint);
   document.body.appendChild(element);
   let disposed = false;
   const claims = [];
@@ -22,6 +25,7 @@ export function createTooltipPresenter({ id = "pf-hover-tip" } = {}) {
   function setContent(content) {
     title.textContent = content.title;
     subtitle.textContent = content.subtitle ?? "";
+    hint.textContent = content.hint ?? "";
   }
 
   function measureVisible(content, anchored) {