partforge 0.100.0 → 0.102.0

package/docs/AUTHORING-PARTS.md

@@ -731,9 +731,9 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"checkbox"` | an on/off box: ticked writes `on`, cleared writes `0` | `on` (default `1`) |
 | `"select"` | a dropdown | `options` |
 | `"radio"` | a segmented button row | `options` |
-| `"font"` | a typeface picker (or a URL field with no catalog), plus a drop target | `allow`, `preview` |
-| `"image"` | an image picker (or a URL field with no catalog), plus a drop target | `allow` |
-| `"vector"` | a URL field plus a drop target — no catalog exists | — |
+| `"font"` | a typeface picker with a catalog, else a drop target | `allow`, `preview`, `sourceField` |
+| `"image"` | an image picker with a catalog, else a drop target showing the artwork | `allow`, `sourceField` |
+| `"vector"` | a drop target showing the artwork — no catalog exists | `sourceField` |
 
 Numeric controls always show the number box: drag the slider *or* type an exact
 value. Typed values may be finer than `step` and clamp to `[min, max]` on commit.
@@ -748,6 +748,18 @@ each entry is both value and label — or the long form
 types, `12` is not `"12"`). An option's `description` surfaces as a hover tooltip
 on that one option, not as a ⓘ popover.
 
+**`sourceField: true`** (font/image/vector) adds a raw source text box to the
+control. It is **off by default**: the drop target already carries the preview,
+the drag target and click-to-choose, and where a catalog is wired there is a
+picker too, so on a 288 px rail a text box is the affordance earning its space
+least. Turn it on when typing a source by hand is something your users will
+actually do — pasting an `https:` URL they already have, or a host `pfc-asset:`
+token. Hiding it changes nothing else: the same values are accepted by the same
+allow list, and a source set in `defaults` or by the host still applies.
+
+For a `"font"` control with no `fontCatalog` this is the only text entry there
+is, so a standalone app that expects users to paste font URLs should set it.
+
 **`allow` and `preview`** (font) configure the typeface control. `allow` lists the
 source kinds a **param-supplied** value may use — what the picker writes, or what
 arrives in a share link:
@@ -3405,6 +3417,8 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
   of deliberate clearance, or overshoot the cut. Mesh CSG shrugs; OCCT's boolean
   degenerates, so the part previews instantly and the STEP export runs for minutes
   ([boolean-coincident-faces-hang](ERROR-PATTERNS.md#boolean-coincident-faces-hang)).
+  The exact kernel refuses the common form up front — an `exactly-touching surfaces`
+  build error names the shared radius and this fix menu.
   For the case that causes this most often — a tapped hole — reach for
   `k.tappedBore`, which owns the bore and the thread together and cannot land them
   on the same face.

package/docs/ERROR-PATTERNS.md

@@ -65,6 +65,7 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 
 - **Symptom:** A part previews instantly but a STEP export (or any OCCT-path build) of one sub-part runs for minutes and never finishes, with no error, no warning, and no progress. Cutting each tool on its own is fast; only the combination hangs. Threaded parts are the usual victims.
 - **Cause:** Two cut tools in the same `cutAll` (or a tool and the body) share an *exactly* coincident face — most often a bore whose radius equals a thread's root radius, so the bore wall and the thread root lie on the same cylinder. OCCT's boolean has to classify a surface that is simultaneously on both operands, and the intersection search degenerates. Manifold's mesh CSG does not care, which is why the preview is fine and only the exact kernel suffers. Measured on one real part: bore alone 0.4 s, thread alone 5.4 s, both together did not finish in fifteen minutes; moving the bore 0.05 mm brought the pair to 12.6 s.
+- **Detected:** The exact kernel now refuses the common cylindrical form of this contact up front — several swept faces lying exactly on one cylindrical face fail the boolean immediately with `<op> between exactly-touching surfaces: … (radius <r>)` and the fix menu below, instead of grinding. Scope, honestly: the guard needs the contact to tile the cylinder (a thread does, ~6+ hugging faces per turn; a sub-turn thread can slip under it — that is the old grinding behavior, not a new one), it covers swept-face-on-cylinder contact only (two swept faces mated exactly, or contact with non-cylindrical faces, can still hang), and a hand-sunk thread whose chord-bands happen to hug the wall can be refused even though it would have built — `k.tappedBore` resolves that refusal too, since its internal composition is exempt. The rule below applies everywhere regardless.
 - **Fix:** For a tapped hole — far and away the most common cause — use `k.tappedBore({ d, pitch, turns, depth })`, which returns the bore and its thread as one tool and cannot put them on the same face. Otherwise: give the surfaces a deliberate clearance instead of letting them land on the same number. Derive one from the other with an explicit gap — `const boreD = threadRootD - 2 * boreClearance;` with `boreClearance` around 0.05-0.1 mm — rather than reusing the same expression for both. The gap is far below a printable layer, so the fit is unchanged. The same rule covers a cut that ends exactly flush with a face (overshoot it by a few tenths, as the surrounding examples do with `+ 0.4` / `- 0.2`) and two tools that abut exactly end-to-end.
 
 ## chamfer-rescue-bisection

package/package.json

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

@@ -198,6 +198,101 @@ textarea.text-input { min-height: 64px; resize: vertical; }
 .text-input:focus { outline: none; border-color: var(--pf-accent);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 
+/* ── file drop targets ──────────────────────────────────────────────────────
+   Two forms of the same widget. The LABELLED form is a tile the user is meant
+   to find: it doubles as the thumbnail once there is something to show, so a
+   preview, a drop zone and a click-to-choose occupy one box rather than three.
+   The AMBIENT form is for a control that already has a visible way in (the font
+   control's catalog button) — it covers the control invisibly and only appears
+   while a file is over it, so dropping stays available without spending rail
+   height advertising itself. */
+.file-drop {
+  position: relative; display: flex; flex-direction: column;
+  align-items: center; justify-content: center; gap: 6px;
+  min-height: 56px; margin-top: 6px; padding: 8px;
+  background: var(--pf-input-bg); color: var(--pf-hint);
+  border: 1px dashed var(--pf-border); border-radius: var(--pf-radius-control);
+  text-align: center; cursor: pointer;
+}
+.file-drop:focus-visible { outline: none; border-color: var(--pf-accent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
+.file-drop-hint { font: 11px/1.35 var(--pf-sans); }
+
+/* `contain` rather than `cover` because artwork and depth maps are content, not
+   decoration — cropping one to fill the box would misrepresent what is about to
+   be built. The two preview kinds then diverge, because a photograph and a piece
+   of line art want opposite things from the box around them. */
+.file-drop > svg, .file-drop > img {
+  display: block; max-width: 100%; max-height: 96px; object-fit: contain;
+}
+.file-drop > svg { fill: var(--pf-text-2); }
+/* Once there IS a preview, the frame moves off the tile and onto the artwork.
+   The tile stays full width — it is the drop target, and a full-width one is
+   easier to hit — but goes invisible, so what the eye sees is a rounded box
+   hugging the picture with the hint underneath it, rather than a picture
+   floating inside a much larger box. The border stays at 1px and only loses its
+   colour, so nothing shifts when a thumbnail arrives. */
+.file-drop.has-thumb {
+  border-color: transparent; background: none; padding: 0; gap: 4px;
+}
+.file-drop.has-thumb > img, .file-drop.has-thumb > svg {
+  border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control);
+  background: var(--pf-input-bg);
+}
+/* A RASTER is a filled rectangle, so the border sits directly on the pixels —
+   padding around one reads as a mount around a picture. `border-radius` on an
+   `<img>` clips the image itself, which is what rounds the corners. Sized by
+   `max-height` rather than `height` so a small source is shown at its own size
+   instead of being upscaled into a blur.
+   `width: auto` is load-bearing: this element also carries `.image-preview`,
+   which pins it to `width: 100%` and letterboxes the picture inside a
+   rail-width box with `object-fit`. That is the right behaviour for a preview
+   that fills its container and the wrong one for a frame meant to hug, and it
+   is invisible in the markup — the box just silently stops matching the image. */
+.file-drop.has-thumb > img { max-height: 96px; max-width: 100%; width: auto; margin: 0; }
+/* A VECTOR is line art: strokes running into the border would collide with it
+   rather than be framed by it, so it keeps padding inside its own frame. Sizing
+   by height with `width: auto` lets the viewBox's aspect supply the width, so
+   the frame hugs the drawing instead of the SVG's default 300x150 box. */
+.file-drop.has-thumb > svg { height: 96px; width: auto; max-width: 100%; padding: 8px; }
+
+/* The empty-state hint and the replace hint trade places: exactly one is visible
+   in either state, so a tile is never without an instruction. */
+.file-drop-hint-replace { display: none; }
+.file-drop.has-thumb .file-drop-hint { display: none; }
+.file-drop.has-thumb .file-drop-hint-replace { display: block; }
+
+/* Ambient: no box of its own. Laid over the control, inert to the pointer so
+   every click still reaches the button underneath — the one affordance this
+   form exists to protect. */
+/* Only the controls that actually carry an ambient overlay become positioned —
+   `.slider` is shared by every widget in the rail, and making all of them a
+   containing block to serve one would be a wide change for a narrow need. */
+.slider:has(> .file-drop-ambient) { position: relative; }
+
+.file-drop-ambient {
+  position: absolute; inset: 0; margin: 0; padding: 0;
+  min-height: 0; background: none; border: 0; pointer-events: none;
+}
+/* `dragover` is the only thing that reveals it. Pointer events stay off even
+   then: the drop event still fires on the element, and turning them on would
+   swallow a click that merely passed through mid-drag. */
+.file-drop-ambient.file-drop-over {
+  border: 1px dashed var(--pf-accent); border-radius: var(--pf-radius-control);
+  background: color-mix(in oklab, var(--pf-accent) 12%, transparent);
+}
+
+/* Shared drag feedback for the labelled form. */
+.file-drop.file-drop-over {
+  border-color: var(--pf-accent);
+  background: color-mix(in oklab, var(--pf-accent) 12%, transparent);
+}
+
+.file-drop-error {
+  margin-top: 5px; font: 11px/1.35 var(--pf-sans); color: var(--pf-err);
+}
+
 /* the `type: "font"` control — a button that shows the current face IN it */
 .font-btn { width: 100%; display: flex; align-items: center; gap: 8px; text-align: left; cursor: pointer;
   background: var(--pf-input-bg); color: var(--pf-text-strong);

package/src/framework/geometry/kernel-front.js

@@ -118,7 +118,12 @@ export function finishKernel(k) {
     // swapped, an empty solid). A wrong answer with no error is the worst of the
     // three failure modes, and overhanging is what avoids it.
     const threadLength = pitch * turns;
-    return k.union([
+    // _trustedUnion where the backend offers it (OCCT): this composition is the
+    // coincidence guard's own coached FIX, audited by the identity test and the
+    // guard suite, and its flank chord-bands legitimately hug the bore wall
+    // they overlap — the guard must not second-guess it. Manifold has no guard
+    // and no _trustedUnion; plain union is identical there.
+    return (k._trustedUnion ?? k.union)([
       k.cylinder({ d, h: (depth ?? threadLength) + 2 * overshoot }).translate([0, 0, -overshoot]),
       thread,
     ]);

package/src/framework/geometry/occt-backend.js

@@ -15,6 +15,7 @@
 //     param change (a lid's open angle) therefore re-runs no OCCT op at all.
 //     Ops that need the real B-rep (booleans, fillet/chamfer/shell, exports,
 //     volume, boundingBox) materialize the pending pose through replicad first.
+import { assertNoCoincidentBoolean } from "./occt-coincidence.js";
 import { toEdgeFinder } from "./edge-selector.js";
 import { toFaceFinder } from "./face-selector.js";
 import { addSugar } from "./solid-sugar.js";
@@ -117,6 +118,12 @@ export function createOcctKernel(replicad) {
   // Manifold backend's fillet/chamfer degradation.
   const buildWarnings = [];
   const recordWarning = (msg) => { buildWarnings.push(msg); console.warn(`partforge: ${msg}`); };
+  // The raw OCCT instance, for the coincident-boolean guard (occt-coincidence.js).
+  // Absent (older replicad, or a boot path that skipped setOC) the guard is a no-op —
+  // detection is an upgrade, never a dependency.
+  let occtInstance = null;
+  try { occtInstance = replicad.getOC(); } catch { /* guard disabled */ }
+  const guardBoolean = (opName, solids) => assertNoCoincidentBoolean(occtInstance, opName, solids);
   // Fillet/chamfer/shell failure recovery (skip-on-failure, chamfer binary search) —
   // see occt-repair.js for the policies and why they differ per op.
   const { validChamfer, safeOp } = createOcctRepair(measureVolume, recordWarning);
@@ -223,6 +230,7 @@ export function createOcctKernel(replicad) {
         const key = h("cut", hash, t._hash);
         return cached(key, () => {
           const a = mat(), b = t._mat();
+          guardBoolean("cut", [a._s, b._s]);
           return wrap(a._s.clone().cut(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
         });
       },
@@ -231,6 +239,10 @@ export function createOcctKernel(replicad) {
         return cached(key, () => {
           const a = mat(), bs = tools.map((t) => t._mat());
           if (bs.length === 0) return wrap(a._s.clone(), cloneLabels(a._labels), key);
+          // All pairs, tools included: the cut below first fuses the tools
+          // together, so tool-to-tool contact hangs exactly like target-to-tool
+          // (the measured case WAS two tools — a bore and its thread).
+          guardBoolean("cutAll", [a._s, ...bs.map((b) => b._s)]);
           const fusedTools = bs
             .slice(1)
             .reduce((acc, b) => acc.fuse(b._s.clone()), bs[0]._s.clone());
@@ -245,6 +257,7 @@ export function createOcctKernel(replicad) {
         const key = h("intersect", hash, t._hash);
         return cached(key, () => {
           const a = mat(), b = t._mat();
+          guardBoolean("intersect", [a._s, b._s]);
           return wrap(a._s.clone().intersect(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
         });
       },
@@ -252,6 +265,7 @@ export function createOcctKernel(replicad) {
         const key = h("union", [hash, t._hash]);
         return cached(key, () => {
           const a = mat(), b = t._mat();
+          guardBoolean("union", [a._s, b._s]);
           return wrap(a._s.clone().fuse(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
         });
       },
@@ -628,6 +642,24 @@ export function createOcctKernel(replicad) {
     prism, extrude, revolve, loft: loftOp, sweep, helixSweptTube, heightfield,
     sphere: (r) => cached(h("sphere", r), () => wrap(makeSphere(r), [], h("sphere", r))),
     union: (solids) => {
+      const key = h("union", solids.map((s) => s._hash));
+      return cached(key, () => {
+        const ms = solids.map((s) => s._mat());
+        guardBoolean("union", ms.map((m) => m._s));
+        return wrap(
+          ms.map((m) => m._s.clone()).reduce((a, b) => a.fuse(b)),
+          ms.flatMap((m) => cloneLabels(m._labels)),
+          key,
+        );
+      });
+    },
+    // Union WITHOUT the coincidence guard — for kernel-front compositions that
+    // are audited fixes for the guarded failure (k.tappedBore's bore ∪ thread,
+    // whose flank chord-bands deliberately hug the bore wall they overlap;
+    // measured safe at 3.0s where the tangent form never finishes). `_`-prefixed:
+    // not part of the public kernel surface, and part authors never see it.
+    // Same cache key as union — the geometry is identical either way.
+    _trustedUnion: (solids) => {
       const key = h("union", solids.map((s) => s._hash));
       return cached(key, () => {
         const ms = solids.map((s) => s._mat());

package/src/framework/geometry/occt-coincidence.js

@@ -0,0 +1,197 @@
+// Refuses the boolean OCCT cannot survive, before it runs.
+//
+// The degenerate case (measured on real feedback, 2026-08-31): a swept face —
+// a thread root from screwSweep is the canonical one — lying exactly ON the
+// other operand's cylindrical face. OCCT 7.6 detects same-domain overlap
+// between two ANALYTIC cylinders instantly (flush stacks, re-cut holes and
+// overlapping coaxial rods all fuse in milliseconds), but a BSpline surface
+// coincident with a cylinder has no same-domain shortcut: the intersection
+// walker grinds for minutes with no error, wedging the serial kernel worker,
+// or — on OCCT 8 — "finishes" with corrupt geometry (a negative-volume fuse).
+// Every kernel-level mitigation was measured and ruled out: SetFuzzyValue
+// hangs at 1e-4/1e-3/1e-2, SetUseOBB hangs, glue completes only under a
+// precondition (no volumetric overlap) that cannot be proven in general, and
+// the WASM build binds no progress indicator so the grind cannot be aborted.
+// The only fix is refusing the contact and coaching the author toward real
+// clearance, real overlap, or k.tappedBore.
+//
+// The predicate is AREA contact, not proximity: a freeform face whose sampled
+// points nearly all sit on the cylinder (within the sweep's own approximation
+// band — the swept "cylinder" deviates from the true radius by ~1e-3·r, which
+// is exactly why OCCT cannot classify it as same-domain). Faces that merely
+// CROSS the radius (thread flanks, the tapered lead-in ramps) put only a
+// fraction of their samples in the band and are left alone — measured at 0.5
+// and 0.75 against the 0.9 threshold, and a construction with the documented
+// 0.05 mm of clearance sits far outside the band entirely.
+//
+// Known misses, accepted: freeform-vs-freeform coincidence (two swept
+// surfaces mated exactly) and exact contact with non-cylindrical analytic
+// faces. This guard exists for the case users actually author — a bore plus a
+// thread — not as a proof that every boolean terminates.
+
+const FREEFORM_SURFACES = [
+  "GeomAbs_BSplineSurface",
+  "GeomAbs_BezierSurface",
+  "GeomAbs_SurfaceOfExtrusion",
+  "GeomAbs_SurfaceOfRevolution",
+  "GeomAbs_OffsetSurface",
+  "GeomAbs_OtherSurface",
+];
+
+// Sampled 4×4 across each candidate face; "on the cylinder" means within
+// max(1e-3, 2e-3·r) — twice the measured sweep-approximation band, still an
+// order of magnitude below the 0.05 mm the authoring guidance calls real
+// clearance — and a face is contact only when ≥90% of its samples qualify.
+//
+// A single hugging face is NOT enough to refuse: a twisted extrusion's flank
+// is subdivided into narrow helical chord-bands, and whichever band straddles
+// the wall sits inside the position tolerance over its whole area (measured:
+// r-span 0.010 across the full thread length) — yet OCCT resolves that
+// transversal contact in seconds. Local geometry cannot separate the two
+// cases robustly: the band's radial drift and the coincident face's chord
+// wobble are both ~r·1e-3, and every tangency proxy measured (surface
+// normals: cancellation noise on helical faces; radial gradients: the
+// crossing smears over a ~0.37 circumferential path, g≈0.03 vs wobble 0.01)
+// lands inside the noise. What separates them decisively is EXTENT: a
+// coincident swept surface tiles the cylinder with hugging faces (~6+ per
+// turn, 20 measured on a 3-turn thread), while a crossing contributes the one
+// band that happens to straddle (1–3 with phase luck). Hence
+// MIN_CONTACT_FACES: refuse only when several distinct freeform faces hug the
+// SAME cylinder. A sub-turn thread can slip under the threshold — that is the
+// old behavior, not a new failure — and a hand-sunk thread whose chord-band
+// count reaches it is refused with coaching toward k.tappedBore, whose own
+// internal union is exempt (it is this module's audited fix, not a suspect).
+const GRID = 4;
+const REL_TOL = 2e-3;
+const MIN_TOL = 1e-3;
+const MIN_ON_FRACTION = 0.9;
+const MIN_CONTACT_FACES = 4;
+
+// Above this many faces on one operand, skip detection (fail open): the guard
+// must never cost more than the boolean it protects. A part-authored solid is
+// tens to hundreds of faces; only a large STEP import approaches this.
+const MAX_FACES = 8000;
+
+const enumName = (enumObj, value) =>
+  Object.keys(enumObj).find((n) => enumObj[n] === value || (enumObj[n]?.value !== undefined && enumObj[n].value === value?.value));
+
+// One pass over a solid's faces: analytic cylinders (radius + axis + bbox) and
+// freeform faces (adaptor kept for lazy sampling + bbox). Caller must dispose().
+function faceProfile(oc, topo) {
+  const cylinders = [];
+  const freeforms = [];
+  let faceCount = 0;
+  const explorer = new oc.TopExp_Explorer_2(topo, oc.TopAbs_ShapeEnum.TopAbs_FACE, oc.TopAbs_ShapeEnum.TopAbs_SHAPE);
+  for (; explorer.More(); explorer.Next()) {
+    faceCount += 1;
+    if (faceCount > MAX_FACES) break;
+    const face = oc.TopoDS.Face_1(explorer.Current());
+    const adaptor = new oc.BRepAdaptor_Surface_2(face, true);
+    const surface = enumName(oc.GeomAbs_SurfaceType, adaptor.GetType());
+    const box = new oc.Bnd_Box_1();
+    oc.BRepBndLib.Add(face, box, false);
+    const mn = box.CornerMin(), mx = box.CornerMax();
+    const bbox = [mn.X(), mn.Y(), mn.Z(), mx.X(), mx.Y(), mx.Z()];
+    box.delete();
+    if (surface === "GeomAbs_Cylinder") {
+      const cyl = adaptor.Cylinder();
+      const axis = cyl.Axis(), dir = axis.Direction(), loc = axis.Location();
+      cylinders.push({
+        r: cyl.Radius(),
+        loc: [loc.X(), loc.Y(), loc.Z()],
+        dir: [dir.X(), dir.Y(), dir.Z()],
+        bbox,
+      });
+      adaptor.delete();
+    } else if (FREEFORM_SURFACES.includes(surface)) {
+      freeforms.push({ adaptor, bbox });
+    } else {
+      adaptor.delete();
+    }
+  }
+  explorer.delete();
+  return {
+    cylinders,
+    freeforms,
+    overflow: faceCount > MAX_FACES,
+    dispose: () => { for (const f of freeforms) f.adaptor.delete(); },
+  };
+}
+
+const boxesOverlap = (a, b, pad) =>
+  a[0] <= b[3] + pad && b[0] <= a[3] + pad &&
+  a[1] <= b[4] + pad && b[1] <= a[4] + pad &&
+  a[2] <= b[5] + pad && b[2] <= a[5] + pad;
+
+// Fraction of a freeform face's interior sample grid lying within tol of the
+// cylinder's surface.
+function onCylinderFraction(freeform, cyl, tol) {
+  const ad = freeform.adaptor;
+  const u0 = ad.FirstUParameter(), u1 = ad.LastUParameter();
+  const v0 = ad.FirstVParameter(), v1 = ad.LastVParameter();
+  let hits = 0;
+  for (let i = 0; i < GRID; i++) {
+    for (let j = 0; j < GRID; j++) {
+      const p = ad.Value(u0 + ((i + 0.5) / GRID) * (u1 - u0), v0 + ((j + 0.5) / GRID) * (v1 - v0));
+      const px = p.X() - cyl.loc[0], py = p.Y() - cyl.loc[1], pz = p.Z() - cyl.loc[2];
+      const t = px * cyl.dir[0] + py * cyl.dir[1] + pz * cyl.dir[2];
+      const radial = Math.hypot(px - t * cyl.dir[0], py - t * cyl.dir[1], pz - t * cyl.dir[2]);
+      if (Math.abs(radial - cyl.r) <= tol) hits += 1;
+    }
+  }
+  return hits / (GRID * GRID);
+}
+
+function contactBetween(profileA, profileB) {
+  for (const [cylSide, freeSide] of [[profileA, profileB], [profileB, profileA]]) {
+    for (const cyl of cylSide.cylinders) {
+      const tol = Math.max(MIN_TOL, REL_TOL * cyl.r);
+      let contacts = 0;
+      for (const freeform of freeSide.freeforms) {
+        if (!boxesOverlap(cyl.bbox, freeform.bbox, tol)) continue;
+        if (onCylinderFraction(freeform, cyl, tol) >= MIN_ON_FRACTION) contacts += 1;
+        if (contacts >= MIN_CONTACT_FACES) return { radius: cyl.r };
+      }
+    }
+  }
+  return null;
+}
+
+// The one entry point. `solids` are replicad Shape3D wrappers (`.wrapped` is
+// the TopoDS shape); every unordered pair is checked, because a cutAll fuses
+// its tools together before cutting — the contact can be tool-to-tool as
+// easily as target-to-tool. Throws the coached error on contact; returns
+// silently otherwise. Any internal failure returns silently too: the guard
+// must never break a boolean that would have succeeded.
+export function assertNoCoincidentBoolean(oc, opName, solids) {
+  if (!oc || solids.length < 2) return;
+  const profiles = [];
+  try {
+    for (const s of solids) profiles.push(faceProfile(oc, s.wrapped));
+    for (let i = 0; i < profiles.length; i++) {
+      for (let j = i + 1; j < profiles.length; j++) {
+        const contact = contactBetween(profiles[i], profiles[j]);
+        if (contact) throw coincidentBooleanError(opName, contact.radius);
+      }
+    }
+  } catch (e) {
+    if (e?.code === "COINCIDENT_BOOLEAN") throw e;
+    // Detection is best-effort; a probe failure must not block the build.
+  } finally {
+    for (const p of profiles) { try { p.dispose(); } catch { /* freed with the shape */ } }
+  }
+}
+
+function coincidentBooleanError(opName, radius) {
+  const r = Number(radius.toFixed(4));
+  const err = new Error(
+    `${opName} between exactly-touching surfaces: a swept or curved face of one operand lies ` +
+    `exactly on a cylindrical face of the other (radius ${r}). The exact kernel cannot process ` +
+    `this contact — it grinds for minutes or returns broken geometry — so the build was refused ` +
+    `before trying. Make the surfaces genuinely overlap or genuinely clear each other (0.05 or ` +
+    `more) instead of exactly touching; for an internal thread, replace the bore + screwSweep ` +
+    `pair with k.tappedBore, which builds the same tap as one safe tool.`,
+  );
+  err.code = "COINCIDENT_BOOLEAN";
+  return err;
+}

package/src/framework/mount.js

@@ -4,6 +4,7 @@ import { createViewer } from "./viewer.js";
 import { attachViewerControls } from "./viewer-controls.js";
 import { attachCutawayControls } from "./cutaway-controls.js";
 import { attachRail } from "./rail.js";
+import { declaredSourceLookup } from "./panel/declared-source.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
 import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
 import { loadCamera, loadProjection, saveProjection } from "./view-state.js";
@@ -976,7 +977,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     }, onParamsCommit
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
       : undefined,
-      { fontCatalog, imageCatalog, onAssetUpload });
+      // What the part is actually using for each asset key, so a control opens
+      // showing the bundled default instead of an empty tile. Rebuilt per panel
+      // build, because the declaration is a function of the current params.
+      { fontCatalog, imageCatalog, onAssetUpload,
+        declaredSource: declaredSourceLookup(part, params) });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {

package/src/framework/panel/author.js

@@ -33,6 +33,17 @@ function authoredControl(c) {
     hidden: !!c.hidden,
     when: c.when,
     whenFalse: c.whenFalse,
+    // Asset-control fields. This list is an explicit allow-list, so anything
+    // missing from it is silently dropped rather than failing loudly — which is
+    // how `allow` came to be ignored: an authored `allow: ["asset"]` never
+    // reached the widget, so its own typed-URL check fell back to the default
+    // list and accepted values the worker then refused and reset underneath the
+    // user. The worker-side gate was never affected (imageControlAllows and its
+    // siblings walk the raw authored tree, not this node), so the enforcement
+    // held throughout — but the panel disagreed with it.
+    allow: c.allow,
+    preview: c.preview,
+    sourceField: c.sourceField,
     preserveOn: false,
     marksCustom: true,
   };

package/src/framework/panel/declared-source.js

@@ -0,0 +1,128 @@
+// What a part is ACTUALLY using for an asset key, when the control's own param
+// is empty.
+//
+// The problem this solves is not cosmetic. A part's bundled default lives in the
+// `images`/`vectors` DECLARATION, never in `defaults` — an author cannot move it
+// there, because the allow list passes only `https` and a bundled asset resolves
+// to a `file:`/dev URL, so `defaults: { relief: new URL(…) }` is refused and
+// reset. The declaration is therefore the only home for it, and the panel could
+// not see the declaration at all: `buildControls` receives `part.parameters`.
+// The result was a control that opened empty while the part was plainly building
+// from an image.
+//
+// Main-thread only, and deliberately import-free beyond what a lookup needs: it
+// runs during panel construction, on every rebuild.
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+
+// `images`/`vectors`/`fonts` may each be a plain map or a function of params —
+// the function form is what a control drives. Resolving it can throw (it is
+// author code running on every panel build), and a broken declaration must not
+// take the panel down: the control simply shows nothing, which is the same thing
+// it showed before this existed.
+function resolveDecl(decl, params) {
+  try {
+    return typeof decl === "function" ? decl(params) : decl;
+  } catch {
+    return undefined;
+  }
+}
+
+const FIELD = { image: "images", vector: "vectors", font: "fonts" };
+
+// URL-shaped for the same reason lint's probes are: a declaration may parse the
+// value it is handed, and an arbitrary string would make it throw for reasons
+// that have nothing to do with which asset the key feeds.
+const SENTINEL = "pf-panel-sentinel://declared-source";
+
+/**
+ * Build `(kind, key) => source | undefined` for one part and its current params.
+ *
+ * Returns `undefined` when the param already holds a value: the param IS the
+ * user's choice, and the declaration for that key is derived from it. Only an
+ * empty param falls through to whatever the part declared.
+ */
+export function declaredSourceLookup(part, params) {
+  return (kind, key) => {
+    const own = params?.[key];
+    if (own !== undefined && own !== null && own !== "") return undefined;
+
+    const decl = part?.[FIELD[kind]];
+    const resolved = resolveDecl(decl, params ?? {});
+    if (!resolved || typeof resolved !== "object") return undefined;
+
+    // A control's param key is NOT necessarily the asset's name. emblem.js
+    // declares `vectors: (p) => ({ emblem: p.art || bundled })` — key `art`,
+    // asset `emblem`. relief.js happens to use the same word for both, which is
+    // what makes the assumption look safe until it is not.
+    //
+    // So probe, the way lint's *-control-not-in-* rules already do: resolve the
+    // declaration once with a sentinel in this key and see which asset name it
+    // came out under. A URL-shaped sentinel, because a declaration is free to
+    // parse what it is handed and an arbitrary string would make it throw for
+    // reasons unrelated to the mapping.
+    let name = key;
+    if (typeof decl === "function" && !(key in resolved)) {
+      const probe = resolveDecl(decl, { ...(params ?? {}), [key]: SENTINEL });
+      const hit = probe && typeof probe === "object"
+        && Object.keys(probe).find((n) => probe[n] === SENTINEL);
+      if (!hit) return undefined;   // this key feeds nothing — not our asset
+      name = hit;
+    }
+
+    const source = resolved[name];
+    return source == null || source === "" ? undefined : source;
+  };
+}
+
+/**
+ * A declared image source -> something an `<img>` can load, or `undefined`.
+ *
+ * The allow list gates PARAMS, not author declarations, so a `file:` or dev URL
+ * is perfectly fine to display here — the browser is loading it, nothing is
+ * being accepted from an untrusted link.
+ */
+export async function declaredImageUrl(source) {
+  try {
+    let v = typeof source === "function" ? await source() : source;
+    // A Vite `() => import("./x.png")` resolves to `{ default: url }`.
+    if (v && typeof v === "object" && !(v instanceof URL) && "default" in v) v = v.default;
+    if (v instanceof URL) return v.href;
+    if (typeof v === "string" && v) return v;
+    if (v instanceof ArrayBuffer || ArrayBuffer.isView(v)) {
+      return URL.createObjectURL(new Blob([v], { type: "image/png" }));
+    }
+    return undefined;
+  } catch {
+    return undefined;   // a thunk that rejects shows nothing, it does not propagate
+  }
+}
+
+/**
+ * A declared vector source -> its parsed document, or `undefined`.
+ *
+ * Unlike an image there is nothing to point at: the thumbnail is drawn from the
+ * document's own contours, so the file has to be fetched and parsed. Results are
+ * memoised per source, because a panel rebuild would otherwise refetch on every
+ * slider drag.
+ */
+const vectorDocs = new Map();
+export async function declaredVectorDoc(source) {
+  if (source == null) return undefined;
+  if (typeof source === "object" && !(source instanceof URL) && !("default" in source)) return source;
+  if (vectorDocs.has(source)) return vectorDocs.get(source);
+  const p = (async () => {
+    try {
+      let v = typeof source === "function" ? await source() : source;
+      if (v && typeof v === "object" && !(v instanceof URL) && "default" in v) v = v.default;
+      if (v && typeof v === "object" && !(v instanceof URL)) return v;   // already parsed
+      const res = await fetch(v instanceof URL ? v.href : v);
+      if (!res.ok) return undefined;
+      return await res.json();
+    } catch {
+      return undefined;   // offline, 404, CORS, malformed JSON — all show nothing
+    }
+  })();
+  vectorDocs.set(source, p);
+  return p;
+}

package/src/framework/panel/render.js

@@ -229,6 +229,7 @@ export function buildControls(root, parameters, params, onDirty, onCommit, opts
       fontCatalog: opts.fontCatalog,
       imageCatalog: opts.imageCatalog,
       onAssetUpload: opts.onAssetUpload,
+      declaredSource: opts.declaredSource,
     });
     nodeEls.set(node.id, widget.el);
     if (node.key && !keyToId.has(node.key)) keyToId.set(node.key, node.id);

package/src/framework/panel/widget-specs.js

@@ -36,9 +36,9 @@ export const WIDGET_SPECS = [
   { type: "checkbox", kind: "control", fields: LEGACY_TOGGLE },
   { type: "select", kind: "control", fields: [...AUTHOR_COMMON, "options"] },
   { type: "radio", kind: "control", fields: [...AUTHOR_COMMON, "options"] },
-  { type: "font", kind: "control", fields: [...AUTHOR_COMMON, "allow", "preview"] },
-  { type: "image", kind: "control", fields: [...AUTHOR_COMMON, "allow"] },
-  { type: "vector", kind: "control", fields: [...AUTHOR_COMMON, "allow"] },
+  { type: "font", kind: "control", fields: [...AUTHOR_COMMON, "allow", "preview", "sourceField"] },
+  { type: "image", kind: "control", fields: [...AUTHOR_COMMON, "allow", "sourceField"] },
+  { type: "vector", kind: "control", fields: [...AUTHOR_COMMON, "allow", "sourceField"] },
   { type: "readout", kind: "display", fields: ["type", "label", "description", "unit", "derivedKey", "hidden", "when", "whenFalse"] },
 ];
 
@@ -57,9 +57,9 @@ const AUTHOR_EXTRAS = {
   checkbox: ["on"],
   select: ["options"],
   radio: ["options"],
-  font: ["allow", "preview"],
-  image: ["allow"],
-  vector: ["allow"],
+  font: ["allow", "preview", "sourceField"],
+  image: ["allow", "sourceField"],
+  vector: ["allow", "sourceField"],
 };
 const AUTHOR_FIELDS = new Map(Object.entries(AUTHOR_EXTRAS).map(
   ([type, extra]) => [type, [...AUTHOR_COMMON, ...extra]]));

package/src/framework/panel/widgets/file-drop.js

@@ -86,24 +86,47 @@ function el(tag, className, text) {
   return node;
 }
 
-export function makeFileDrop({ kind, onSource, onError, onAssetUpload }) {
+// `ambient` is for a control that already has a visible way in — the font
+// control's catalog button, say. A labelled drop zone under it would spend rail
+// height repeating the same offer, so the ambient form carries no hint, no click
+// target and no place in the tab order: it is an overlay that shows itself only
+// while a file is over it (see `.file-drop-ambient` in app.css). Dropping still
+// works, it is simply not advertised.
+//
+// The click path is dropped rather than hidden, deliberately: an invisible
+// overlay that still swallowed clicks would eat the button underneath it, which
+// is the one affordance ambient mode exists to protect.
+export function makeFileDrop({ kind, onSource, onError, onAssetUpload, ambient = false }) {
   const row = rowFor(kind);
-  const wrap = el("div", "file-drop");
-  wrap.tabIndex = 0;
-  wrap.setAttribute("role", "button");
-  const hint = el("span", "file-drop-hint", `Drop ${row?.label ?? "a file"} here, or click to choose`);
-  wrap.append(hint);
+  const wrap = el("div", ambient ? "file-drop file-drop-ambient" : "file-drop");
+  if (!ambient) {
+    wrap.tabIndex = 0;
+    wrap.setAttribute("role", "button");
+    // Two hints, swapped by CSS on `.has-thumb`. The empty-state one is the only
+    // thing in an empty tile; the replace one takes over once a preview fills it.
+    // Without the second, a tile showing a part's declared artwork — now the
+    // state a control OPENS in — carried no instruction at all, because the
+    // first is hidden the moment a thumbnail appears.
+    wrap.append(el("span", "file-drop-hint", `Drop ${row?.label ?? "a file"} here, or click to choose`));
+    wrap.append(el("span", "file-drop-hint file-drop-hint-replace", "Drop to replace, or click to choose"));
+  }
 
   // The click/keyboard path to the same handler a drop uses. Hidden rather
   // than absent: a real `<input type="file">` is what gives this a native
   // "Choose File" affordance and OS-level type filtering (`accept`), neither
   // of which is worth hand-rolling.
-  const input = document.createElement("input");
-  input.type = "file";
-  input.className = "file-drop-input";
-  input.hidden = true;
-  if (row?.accepts?.length) input.accept = row.accepts.join(",");
-  wrap.append(input);
+  // Ambient mode has no click path, so it gets no input at all — an unused one
+  // would still be focusable in some browsers and would show up to a screen
+  // reader as a second, unlabelled file control.
+  let input = null;
+  if (!ambient) {
+    input = document.createElement("input");
+    input.type = "file";
+    input.className = "file-drop-input";
+    input.hidden = true;
+    if (row?.accepts?.length) input.accept = row.accepts.join(",");
+    wrap.append(input);
+  }
 
   // The converted artifact from the most recently accepted drop — a Blob (or,
   // for a `convert: null` kind like font, the original File, which already IS
@@ -266,10 +289,15 @@ export function makeFileDrop({ kind, onSource, onError, onAssetUpload }) {
   wrap.addEventListener("drop", onDrop, { signal });
   wrap.addEventListener("dragover", onDragOver, { signal });
   wrap.addEventListener("dragleave", onDragLeave, { signal });
-  wrap.addEventListener("click", onClick, { signal });
-  wrap.addEventListener("keydown", onKeydown, { signal });
   wrap.addEventListener("paste", onPaste, { signal });
-  input.addEventListener("change", onChange, { signal });
+  // Click, keyboard and the input's own change only exist when there is an input
+  // to open — ambient mode is drop-and-paste only, so that the control's real
+  // button keeps every click.
+  if (input) {
+    wrap.addEventListener("click", onClick, { signal });
+    wrap.addEventListener("keydown", onKeydown, { signal });
+    input.addEventListener("change", onChange, { signal });
+  }
 
   return {
     el: wrap,
@@ -295,12 +323,13 @@ export function makeFileDrop({ kind, onSource, onError, onAssetUpload }) {
 // Returns `{ el, errorEl, dispose }` rather than appending anything itself —
 // the caller still owns layout (where the drop target and error line sit
 // relative to the field/button), only the wiring is shared.
-export function mountDrop(kind, { params, node, onAssetUpload, onChange, onCommit, onRender }) {
+export function mountDrop(kind, { params, node, onAssetUpload, onChange, onCommit, onRender, ambient = false }) {
   const errorEl = el("div", "file-drop-error");
   errorEl.hidden = true;
 
   const drop = makeFileDrop({
     kind,
+    ambient,
     onAssetUpload,
     onSource: (source) => {
       errorEl.hidden = true;

package/src/framework/panel/widgets/font.js

@@ -86,7 +86,11 @@ export function makeFont(node, params, { onChange, onCommit, info, fontCatalog,
       onCommit?.();
     });
     paintField();
-    wrap.append(field);
+    // Same opt-in rule as image/vector: the URL box appears only for
+    // `sourceField: true`. This branch has no catalog button, so hiding it
+    // leaves the drop zone as the way in — which is why THIS branch keeps its
+    // labelled drop zone rather than going ambient like the catalog one below.
+    if (node.sourceField === true) wrap.append(field);
 
     const drop = mountDrop("font", {
       params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
@@ -146,7 +150,11 @@ export function makeFont(node, params, { onChange, onCommit, info, fontCatalog,
     picker = openFontPicker?.({ node, params, allow, fontCatalog, anchor: wrap, onPicked: () => { paint(); onChange?.(); onCommit?.(); } }) ?? null;
   });
 
-  const drop = mountDrop("font", { params, node, onAssetUpload, onChange, onCommit, onRender: paint });
+  // Ambient: this branch already has the catalog button as its visible way in, so
+  // the drop covers the control invisibly and reveals itself only while a file is
+  // over it. The no-catalog branch above stays labelled — there, the drop zone is
+  // the only affordance and hiding it would strand the user.
+  const drop = mountDrop("font", { params, node, onAssetUpload, onChange, onCommit, onRender: paint, ambient: true });
   wrap.append(drop.el, drop.errorEl);
 
   return {

package/src/framework/panel/widgets/image.js

@@ -18,6 +18,7 @@
 import { attachInfo } from "../info.js";
 import { IMAGE_ALLOW_DEFAULT, imageSourceAllowed } from "../../image-source.js";
 import { mountDrop } from "./file-drop.js";
+import { declaredImageUrl } from "../declared-source.js";
 
 function el(tag, className, text) {
   const node = document.createElement(tag);
@@ -40,21 +41,70 @@ export function imageLabel(source) {
   return file || source;
 }
 
-// Point (or unpoint) the live preview. A byte-valued param has no URL to hand
-// the browser, so the image stays hidden rather than trying to render it or
-// showing a broken-image glyph — same rule an empty/unset value gets. `onerror`
-// covers the other broken-image case: a URL that 404s or that CORS refuses.
-function paintPreview(img, source) {
-  if (typeof source === "string" && source) {
+// An object URL is a real resource, not a string: the browser pins the blob
+// behind it until it is revoked, and a panel rebuild constructs a fresh widget
+// every time. This owns the whole lifetime — one live URL at a time, the old one
+// revoked before a new one replaces it, and everything released on dispose — so
+// no caller has to remember. Returns `null` for a value that needs no URL.
+function makeObjectUrlSlot() {
+  let current = null;
+  const release = () => {
+    if (current) URL.revokeObjectURL(current);
+    current = null;
+  };
+  return {
+    forBytes(source) {
+      release();
+      if (!isBytes(source)) return null;
+      // Always image/png: `imageToPng` is what produced these bytes, whatever the
+      // user dropped. The type matters — a Blob with none renders nothing.
+      current = URL.createObjectURL(new Blob([source], { type: "image/png" }));
+      return current;
+    },
+    dispose: release,
+  };
+}
+
+// Point (or unpoint) the live preview. A string source is used directly. Bytes —
+// the partforge-cloud sandbox path, where the converted PNG travels in the param
+// because that sandbox cannot fetch URLs — become an object URL, so the cloud
+// gets the same thumbnail as everyone else rather than a blank tile. `onerror`
+// still covers the remaining broken-image case: a URL that 404s or CORS refuses.
+// Resolved ONCE per paint, never per image: the catalog rendering shows the same
+// source in two <img>s, and asking the slot twice would revoke the URL it had
+// just handed the first one, leaving it pointing at a dead blob.
+function previewSrc(source, urls) {
+  return typeof source === "string" && source ? source : urls.forBytes(source);
+}
+
+// When the control's own param is empty, show what the PART is using: its
+// bundled default lives in the `images` declaration, which is the only place it
+// can live (the allow list passes only https, so a file:/dev URL cannot sit in
+// `defaults`). Resolving it is async — a Vite thunk has to be called — so the
+// tile paints empty first and fills in, and a source that never resolves simply
+// leaves it empty. `seq` guards against a slow resolve landing after a newer one.
+function paintDeclared(img, declaredSource, node, apply) {
+  if (!declaredSource) return;
+  const source = declaredSource("image", node.key);
+  if (source === undefined) return;
+  const seq = ++img._pfDeclaredSeq;
+  declaredImageUrl(source).then((url) => {
+    if (url && seq === img._pfDeclaredSeq) apply(url);
+  });
+}
+
+function applyPreview(img, src) {
+  if (src) {
     img.hidden = false;
-    img.src = source;
+    img.src = src;
   } else {
     img.hidden = true;
     img.removeAttribute("src");
   }
 }
 
-export function makeImage(node, params, { onChange, onCommit, info, imageCatalog, onAssetUpload } = {}) {
+export function makeImage(node, params, { onChange, onCommit, info, imageCatalog, onAssetUpload, declaredSource } = {}) {
+  const urls = makeObjectUrlSlot();   // one live preview URL per widget; see makeObjectUrlSlot
   const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : IMAGE_ALLOW_DEFAULT;
   const wrap = el("div", "slider");
   const row = el("div", "row");
@@ -65,12 +115,12 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
 
   const preview = document.createElement("img");
   preview.className = "image-preview";
+  preview._pfDeclaredSeq = 0;
   preview.alt = "";
   preview.hidden = true;
   // A URL that fails to load (404, CORS, revoked link) must degrade to hidden,
   // not the browser's broken-image glyph.
   preview.addEventListener("error", () => { preview.hidden = true; });
-  wrap.append(preview);
 
   if (!imageCatalog) {
     // Degraded path: a URL field. Unlike `text`, it does NOT write on every
@@ -88,7 +138,13 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
       field.value = isBytes(v) ? "" : String(v ?? "");
       field.placeholder = isBytes(v) ? "Uploaded image" : "";
       field.classList.remove("warn");
-      paintPreview(preview, v);
+      const own = previewSrc(v, urls);
+      applyPreview(preview, own);
+      preview.parentElement?.classList.toggle("has-thumb", !preview.hidden);
+      if (!own) paintDeclared(preview, declaredSource, node, (url) => {
+        applyPreview(preview, url);
+        preview.parentElement?.classList.toggle("has-thumb", true);
+      });
     };
     field.addEventListener("change", () => {
       if (!imageSourceAllowed(field.value, allow)) { field.classList.add("warn"); return; }
@@ -98,14 +154,25 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
       onCommit?.();
     });
     paintField();
-    wrap.append(field);
+    // The URL box is OFF unless `sourceField: true`. The tile is already preview,
+    // drop target and click-to-choose in one, so on a 288 px rail a fourth
+    // affordance for the same job is the one earning its space least. Typing a
+    // source by hand is the rarer intent — a host token or an https URL someone
+    // already has — so it is the part that becomes opt-in, rather than the one
+    // every part pays rail height for.
+    if (node.sourceField === true) wrap.append(field);
 
     const drop = mountDrop("image", {
       params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
     });
+    // The tile IS the preview: dropping, clicking to choose, and showing what is
+    // currently selected become one box rather than three stacked ones.
+    // `has-thumb` swaps the dashed empty-state border for a solid frame.
+    drop.el.setAttribute("data-pf-thumb", "");
+    drop.el.prepend(preview);
     wrap.append(drop.el, drop.errorEl);
 
-    return { el: wrap, sync: paintField, dispose: () => drop.dispose() };
+    return { el: wrap, sync: paintField, dispose: () => { drop.dispose(); urls.dispose(); } };
   }
 
   const btn = el("button", "image-btn");
@@ -131,8 +198,15 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
   const paint = () => {
     const src = params[node.key];
     const seq = ++paintSeq;
-    paintPreview(preview, src);
-    paintPreview(thumb, src);
+    const url = previewSrc(src, urls);
+    applyPreview(preview, url);
+    applyPreview(thumb, url);
+    preview.parentElement?.classList.toggle("has-thumb", !preview.hidden);
+    if (!url) paintDeclared(preview, declaredSource, node, (u) => {
+      applyPreview(preview, u);
+      applyPreview(thumb, u);
+      preview.parentElement?.classList.toggle("has-thumb", true);
+    });
     const show = ({ label: text, width, height }) => {
       if (seq !== paintSeq) return;                  // a newer paint already won
       iname.textContent = width && height ? `${text} (${width}×${height})` : text;
@@ -162,12 +236,16 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
   });
 
   const drop = mountDrop("image", { params, node, onAssetUpload, onChange, onCommit, onRender: paint });
+  // Same merge as the degraded branch — the large preview lives in the drop tile;
+  // the catalog button keeps its own small thumb.
+  drop.el.setAttribute("data-pf-thumb", "");
+  drop.el.prepend(preview);
   wrap.append(drop.el, drop.errorEl);
 
   return {
     el: wrap,
     sync: paint,
-    dispose: () => { picker?.close(); picker = null; drop.dispose(); },
+    dispose: () => { picker?.close(); picker = null; drop.dispose(); urls.dispose(); },
   };
 }
 

package/src/framework/panel/widgets/vector-thumb.js

@@ -0,0 +1,136 @@
+// A vector document -> a small inline <svg> preview, for the vector control's
+// thumbnail. MAIN-THREAD ONLY (it builds DOM), but deliberately free of any
+// heavy geometry import: `profile.js` is the one dependency and has no imports
+// of its own. Reaching for `vector-format.js`'s expander instead would pull in
+// contour-ops -> paper-bridge -> paper.js, ~1 MB of curve engine loaded on every
+// page that merely SHOWS a vector control, whether or not anyone drops a file.
+//
+// `tessellateContour` is the geometry's OWN tessellator, which matters more than
+// the saved bytes: a thumbnail that flattened curves its own way could show a
+// shape the kernel would not build. Arcs are the specific trap — the format
+// writes them as a point ON the arc, while SVG's `A` command wants radii and
+// sweep flags, so "just map it to A" is a second interpretation waiting to
+// diverge. At thumbnail size a tessellated arc is pixel-identical anyway.
+import { tessellateContour } from "../../geometry/profile.js";
+
+// Enough segments that a full circle reads as round at ~44 px, cheap enough that
+// a document with hundreds of contours still renders in one frame.
+const ARC_SEGS = 24;
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+const finite = (n) => typeof n === "number" && Number.isFinite(n);
+const finitePoint = (p) => Array.isArray(p) && p.length >= 2 && finite(p[0]) && finite(p[1]);
+
+// The four contour kinds, reduced to a ring of points. The three primitives are
+// sugar the format defines by expansion; `toInternalDocument` normally does this,
+// but it lives behind the paper.js import described above — and these expansions
+// are four lines each, so the thumbnail does them directly rather than paying
+// that cost. `path` delegates to the canonical tessellator.
+function ring(contour) {
+  if (!contour || typeof contour !== "object") return null;
+  switch (contour.kind) {
+    case "circle": {
+      const { center: c, r } = contour;
+      if (!finitePoint(c) || !finite(r) || r <= 0) return null;
+      return Array.from({ length: ARC_SEGS }, (_, i) => {
+        const t = (i / ARC_SEGS) * Math.PI * 2;
+        return [c[0] + Math.cos(t) * r, c[1] + Math.sin(t) * r];
+      });
+    }
+    case "rect": {
+      const { center: c, width: w, height: h } = contour;
+      if (!finitePoint(c) || !finite(w) || !finite(h) || w <= 0 || h <= 0) return null;
+      const hw = w / 2, hh = h / 2;
+      // Corner radius is ignored: at thumbnail scale the rounding is sub-pixel,
+      // and squaring it off never changes what the shape reads as.
+      return [[c[0] - hw, c[1] - hh], [c[0] + hw, c[1] - hh], [c[0] + hw, c[1] + hh], [c[0] - hw, c[1] + hh]];
+    }
+    case "polygon":
+      return Array.isArray(contour.points) && contour.points.length >= 3
+        && contour.points.every(finitePoint) ? contour.points.map((p) => [p[0], p[1]]) : null;
+    case "path":
+    default: {
+      if (!finitePoint(contour.start) || !Array.isArray(contour.segments)) return null;
+      // The FILE format names an arc's midpoint `through`; the internal contour
+      // IR names it `via`, and that is what `tessellateContour` reads. A document
+      // read off disk or returned by `ingestSvg` therefore speaks `through`, and
+      // a segment with neither key is treated as a straight line — so skipping
+      // this rename does not fail loudly, it silently replaces every curve with
+      // its chord. A circle becomes a triangle, which looks like a rendering bug
+      // rather than a parsing one.
+      const segments = contour.segments.map((seg) =>
+        seg && seg.through && !seg.via ? { ...seg, via: seg.through } : seg);
+      const pts = tessellateContour({ ...contour, segments }, ARC_SEGS);
+      return Array.isArray(pts) && pts.length >= 3 && pts.every(finitePoint) ? pts : null;
+    }
+  }
+}
+
+// One subpath. Y is negated because the model frame is y-up and SVG is y-down;
+// the viewBox is negated to match, so the flip is a coordinate convention rather
+// than a transform the caller has to know about.
+const subpath = (pts) =>
+  `M ${pts.map(([x, y], i) => `${i ? "L " : ""}${+x.toFixed(3)} ${+(-y).toFixed(3)}`).join(" ")} Z`;
+
+/**
+ * Render a partforge-vector document as an inline <svg>, or return `null` when
+ * there is nothing renderable — an empty document, or one whose coordinates are
+ * not finite. Returning null rather than throwing keeps a malformed document
+ * from taking the control down with it; the caller falls back to a placeholder.
+ */
+export function vectorThumb(doc) {
+  const shapes = doc?.shapes;
+  if (!shapes || typeof shapes !== "object") return null;
+
+  // Every region from every shape lands in ONE path so `evenodd` composes them:
+  // a `subtract` shape's regions then cut the shapes they overlap, which is what
+  // the document means. The known limitation is that two overlapping regions of
+  // the SAME role also cancel — real composition is a boolean the panel has no
+  // business running. At preview size that trade is invisible, and a missing hole
+  // would be far more misleading than a rare cancelled overlap.
+  const subpaths = [];
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+
+  for (const shape of Object.values(shapes)) {
+    // A shape is either an array of regions, or `{ role, regions }` — §2.3.
+    const regions = Array.isArray(shape) ? shape : shape?.regions;
+    if (!Array.isArray(regions)) continue;
+    for (const region of regions) {
+      for (const contour of [region?.outer, ...(region?.holes ?? [])]) {
+        if (contour === undefined) continue;
+        const pts = ring(contour);
+        if (!pts) return null;   // a bad coordinate anywhere means the preview would lie
+        for (const [x, y] of pts) {
+          if (x < minX) minX = x;
+          if (x > maxX) maxX = x;
+          if (y < minY) minY = y;
+          if (y > maxY) maxY = y;
+        }
+        subpaths.push(subpath(pts));
+      }
+    }
+  }
+  if (!subpaths.length) return null;
+
+  // `bbox` is optional and "recomputed when absent" (§2.1), so a hand-authored
+  // document routinely has none. Trusting it when present keeps the preview
+  // framed the way the document says it should be; deriving it otherwise is what
+  // makes an authored file previewable at all.
+  const b = doc.bbox;
+  const box = b && [b.minX, b.minY, b.maxX, b.maxY].every(finite)
+    ? b : { minX, minY, maxX, maxY };
+  const w = box.maxX - box.minX, h = box.maxY - box.minY;
+  if (!(w > 0) || !(h > 0)) return null;
+
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("viewBox", `${+box.minX.toFixed(3)} ${+(-box.maxY).toFixed(3)} ${+w.toFixed(3)} ${+h.toFixed(3)}`);
+  svg.setAttribute("preserveAspectRatio", "xMidYMid meet");
+  svg.setAttribute("aria-hidden", "true");   // decorative; the control carries the label
+
+  const path = document.createElementNS(SVG_NS, "path");
+  path.setAttribute("d", subpaths.join(" "));
+  path.setAttribute("fill-rule", "evenodd");
+  svg.append(path);
+  return svg;
+}

package/src/framework/panel/widgets/vector.js

@@ -19,6 +19,8 @@
 import { attachInfo } from "../info.js";
 import { VECTOR_ALLOW_DEFAULT, vectorSourceAllowed } from "../../vector-source.js";
 import { mountDrop } from "./file-drop.js";
+import { vectorThumb } from "./vector-thumb.js";
+import { declaredVectorDoc } from "../declared-source.js";
 
 function el(tag, className, text) {
   const node = document.createElement(tag);
@@ -34,7 +36,7 @@ const isBytes = (v) => v instanceof ArrayBuffer || ArrayBuffer.isView(v);
 // byte-valued param.
 const isOpaque = (v) => isBytes(v) || (v != null && typeof v === "object");
 
-export function makeVector(node, params, { onChange, onCommit, info, onAssetUpload } = {}) {
+export function makeVector(node, params, { onChange, onCommit, info, onAssetUpload, declaredSource } = {}) {
   const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : VECTOR_ALLOW_DEFAULT;
   const wrap = el("div", "slider");
   const row = el("div", "row");
@@ -66,12 +68,53 @@ export function makeVector(node, params, { onChange, onCommit, info, onAssetUplo
     onCommit?.();
   });
   paintField();
-  wrap.append(field);
+  // The URL box is OFF unless `sourceField: true` — same reasoning as
+  // widgets/image.js: the tile already carries preview, drop and click-to-choose,
+  // and typing a source by hand is the rarer intent.
+  if (node.sourceField === true) wrap.append(field);
 
+  // The thumbnail IS the drop target. A vector param holds a parsed document, so
+  // there is no URL an <img> could point at — the artwork is drawn inline
+  // instead, and that tile is what a file is dropped on and what opens the file
+  // picker. One element doing all three keeps the rail's 300 px from carrying a
+  // preview, a drop zone and a button that all mean the same thing.
   const drop = mountDrop("vector", {
-    params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
+    params, node, onAssetUpload, onChange, onCommit, onRender: () => { paintField(); paintThumb(); },
   });
-  wrap.append(drop.el, drop.errorEl);
+  const thumb = drop.el;
+  thumb.setAttribute("data-pf-thumb", "");
 
-  return { el: wrap, sync: paintField, dispose: () => drop.dispose() };
+  // `vectorThumb` returns null for a document it cannot draw — malformed, empty,
+  // or carrying a coordinate that is not finite — rather than throwing. The tile
+  // stays either way, because it is the drop target: losing it on a bad document
+  // would strand the user with no way to replace it.
+  let thumbSeq = 0;
+  function showThumb(doc) {
+    const art = thumb.querySelector("svg");
+    if (art) art.remove();
+    const svg = doc ? vectorThumb(doc) : null;
+    thumb.classList.toggle("has-thumb", !!svg);
+    if (svg) thumb.prepend(svg);
+  }
+  function paintThumb() {
+    const own = params[node.key];
+    const seq = ++thumbSeq;
+    if (isOpaque(own)) { showThumb(own); return; }
+    showThumb(null);
+    // Nothing in the param — fall back to what the PART declares, which is where
+    // a bundled default has to live (the allow list passes only https, so a
+    // file:/dev URL cannot sit in `defaults`). Unlike an image there is nothing
+    // to point at: the document must be fetched and parsed before it can be
+    // drawn, so this lands a tick or two later, and a source that never resolves
+    // just leaves the tile empty — it stays a drop target either way.
+    const source = declaredSource?.("vector", node.key);
+    if (source === undefined) return;
+    declaredVectorDoc(source).then((doc) => { if (doc && seq === thumbSeq) showThumb(doc); });
+  }
+  paintThumb();
+
+  wrap.append(thumb, drop.errorEl);
+
+  const sync = () => { paintField(); paintThumb(); };
+  return { el: wrap, sync, dispose: () => drop.dispose() };
 }

package/src/parts/emblem.js

@@ -27,10 +27,14 @@ import plate from "./assets/plate.vector.json" with { type: "json" };
 
 export default {
   meta: { title: "Emblem", units: "mm", background: 0x15181d },
-  vectors: {
-    emblem: new URL("./assets/emblem.vector.json", import.meta.url),
+  // Function form, so the `type: "vector"` control below can drive the artwork.
+  // The bundled file is the default: dropping an SVG replaces it, clearing the
+  // control brings it back, and the part still builds with no network — which is
+  // what CI and `partforge measure` see.
+  vectors: (p) => ({
+    emblem: p.art || new URL("./assets/emblem.vector.json", import.meta.url),
     plate,
-  },
+  }),
   parameters: [
     {
       id: "plate",
@@ -45,15 +49,24 @@ export default {
       id: "art",
       title: "Artwork",
       description: "The embossed vector art. `emblem.svg` carries a filled circle and a stroked bar, so both of ingest's geometry paths are exercised.",
-      advanced: [
-        { key: "emblem_w", label: "Emblem width", unit: "mm", min: 8, max: 70, step: 1,
-          description: "Width of the artwork's **tight bounding box** in mm — not its `viewBox`. Stroke thickness scales with it." },
-        { key: "emboss", label: "Emboss height", unit: "mm", min: 0.4, max: 4, step: 0.2,
-          description: "How far the artwork stands proud of the plate." },
+      // Converted from the legacy `advanced` array to the new shape: a section is
+      // one or the other, never both, because mixing them makes render order
+      // arbitrary (partforge lint's `mixed-section-shape`). `advanced` becomes a
+      // nested group, which renders the same way.
+      controls: [
+        { key: "art", type: "vector", label: "Source",
+          description: "Drop an SVG to replace the bundled emblem — it is converted to "
+            + "partforge-vector once, in the browser, at drop time. Clear it to go back to the bundled file." },
+        { type: "group", title: "Advanced", collapsed: "auto", controls: [
+          { key: "emblem_w", label: "Emblem width", unit: "mm", min: 8, max: 70, step: 1,
+            description: "Width of the artwork's **tight bounding box** in mm — not its `viewBox`. Stroke thickness scales with it." },
+          { key: "emboss", label: "Emboss height", unit: "mm", min: 0.4, max: 4, step: 0.2,
+            description: "How far the artwork stands proud of the plate." },
+        ] },
       ],
     },
   ],
-  defaults: { plate_t: 3, emblem_w: 30, emboss: 1 },
+  defaults: { art: "", plate_t: 3, emblem_w: 30, emboss: 1 },
   parts: {
     plate: {
       label: "Plate",