partforge 0.113.0 → 0.115.0

package/src/framework/geometry/mesh-fillet.js

@@ -670,8 +670,12 @@ function prismTool(k, chain, magnitude, mode, segs, pSegs = segs) {
 // closed-revolve dephase, which are about matching the neighboring tessellation and
 // must not follow the blend cap. `pSegs` is the sagitta-bounded density for the blend
 // cross-section itself (blendSegs above).
-function revolveTool(k, chain, magnitude, mode, segs, pSegs = segs) {
+function revolveTool(k, chain, magnitude, mode, segs, pSegs = segs, flankAt = () => segs) {
   const { O, w, u0, v0, R, span, closed, n1, n2, convex } = chain;
+  // The count the flank's own circle was built at (see apply): the cap on a flat
+  // tier, the per-radius rule on print. Every "matching the neighbouring
+  // tessellation" figure below reads this, never `segs`.
+  const flankSegs = flankAt(R);
   // Seam-grazing guard. The edge circle passes through the flank tessellation's
   // VERTICES (circumradius) while its facets sit at the apothem, so a revolved
   // tool built exactly at R grazes every facet seam tangentially — Manifold
@@ -689,7 +693,7 @@ function revolveTool(k, chain, magnitude, mode, segs, pSegs = segs) {
   // and a radial knife-fin of wall survived both cutters, drawing a line along the
   // band (the label-backing bug). A synthetic corner arc measures nothing — its two
   // points span the whole corner, and its flanks are planes, not a tessellation.
-  const kernelSag = (R + magnitude) * (1 - Math.cos(Math.PI / segs));
+  const kernelSag = (R + magnitude) * (1 - Math.cos(Math.PI / flankSegs));
   let dip = 0;
   if (!chain.synthetic) {
     const pts = chain.points;
@@ -732,7 +736,7 @@ function revolveTool(k, chain, magnitude, mode, segs, pSegs = segs) {
   // with the flank's own tessellation of the same circle (the dephase note below).
   // A SYNTHETIC corner arc (cornerArcAt) is free-standing between planes, so its
   // angular density follows the same sagitta bound as the cross-section.
-  const aSegs = chain.synthetic ? cornerArcSegs(segs, R, magnitude) : segs;
+  const aSegs = chain.synthetic ? cornerArcSegs(segs, R, magnitude) : flankSegs;
   let tool = k.revolve(poly, { degrees, segs: aSegs });
   // pose: Z → w, then twist so the revolve's start azimuth (+X) lands on the
   // chain's start direction (backed off by the angular overshoot)
@@ -749,7 +753,7 @@ function revolveTool(k, chain, magnitude, mode, segs, pSegs = segs) {
   // vertex at every step (the degenerate-needle generator). Half a step lands
   // every crossing mid-facet. Partial arcs have a slightly different pitch
   // (degrees don't divide evenly) and never align in the first place.
-  const dephase = closed ? Math.PI / segs : 0;
+  const dephase = closed ? Math.PI / flankSegs : 0;
   const twist = Math.atan2(dot(w, cross(xImage, startDir)), dot(xImage, startDir)) + dephase;
   if (Math.abs(twist) > 1e-9) tool = tool.rotateAbout({ axis: w, deg: (twist * 180) / Math.PI });
   return tool.translate(O);
@@ -891,7 +895,7 @@ function weldChainPoints(pts, wallNs, closed) {
   return { pts: outP, wallNs: outW };
 }
 
-function planarTool(k, chain, magnitude, mode, segs, pSegs = segs, endTins = null) {
+function planarTool(k, chain, magnitude, mode, segs, pSegs = segs, endTins = null, flankAt = () => segs) {
   const { points, closed, convex, faceN } = chain;
   let { wallNs } = chain;
   let pts = closed ? points.slice(0, -1) : points;   // drop the duplicated closure point
@@ -1095,9 +1099,9 @@ function planarTool(k, chain, magnitude, mode, segs, pSegs = segs, endTins = nul
       tools.push(...buildStretch(path, wallNs[s % nSeg]));
     }
     for (const got of cornerArcs.values()) {
-      tools.push(revolveTool(k, got.arc, magnitude, mode, segs, pSegs));
+      tools.push(revolveTool(k, got.arc, magnitude, mode, segs, pSegs, flankAt));
       if (len(sub(got.vertex, got.arc.O)) - got.arc.R > 0.02 * magnitude)
-        tools.push(cornerHornTool(k, got, magnitude, segs));
+        tools.push(cornerHornTool(k, got, magnitude, segs, flankAt));
     }
     for (const piv of pivots) tools.push(reflexPivotTool(k, piv, magnitude, mode, segs, pSegs));
     return tools;
@@ -1211,7 +1215,7 @@ function cornerArcAt(vertex, f, tin1, tin2, wall1, wall2, len1, len2, magnitude,
 // of its step count, so its apothem ≥ R·cos(π/aSegs) > every horn vertex radius. The
 // cost is a micron-deep extra bite at the corner base, covered near the tangent lines
 // by the neighbors' own overshoot.
-function cornerHornTool(k, { vertex, f, arc }, magnitude, segs) {
+function cornerHornTool(k, { vertex, f, arc }, magnitude, segs, flankAt = () => segs) {
   const { O, w, u0, R, span } = arc;
   const delta = 0.02 * magnitude;
   const rH = R * Math.cos(Math.PI / cornerArcSegs(segs, R, magnitude)) - Math.min(1e-3, 0.02 * magnitude);
@@ -1488,7 +1492,7 @@ function roundSalientCorners(selected, magnitude) {
 // cube's outer walls land inside the material the edge cutters already remove,
 // so the only new surface is the octant. Non-orthogonal corners keep the mitre
 // — the safe, documented default.
-function cornerPatches(k, selected, r, segs) {
+function cornerPatches(k, selected, r, segs, flankAt = () => segs) {
   const byVertex = new Map();
   const push = (pt, dirOut) => {
     const key = pt.map((v) => Math.round(v * 1e4)).join(",");
@@ -1527,7 +1531,7 @@ function cornerPatches(k, selected, r, segs) {
     // is tangent to each flat face at a point and meets the edge-fillet
     // cylinders tangentially at the cube walls, and tessellated tangency
     // produces the same grazing-noise creases the edge tools guard against.
-    const bury = r * (1 - Math.cos(Math.PI / segs)) + 1e-3;
+    const bury = r * (1 - Math.cos(Math.PI / flankAt(r))) + 1e-3; // the kernel sphere below is built at flankAt(r)
     const inward = norm(add(add(e1, e2), e3));
     // corner block: cube spanned by the edge frame, oversized only outward
     let block = k.box({ min: [-dOut, -dOut, -dOut], max: [r, r, r] });
@@ -1554,8 +1558,17 @@ function cornerPatches(k, selected, r, segs) {
 export function meshFillet(k, solid, opts) { return apply(k, solid, "fillet", opts?.r, opts); }
 export function meshChamfer(k, solid, opts) { return apply(k, solid, "chamfer", opts?.d, opts); }
 
-function apply(k, solid, mode, magnitude, { edges, segs = DEFAULT_SEGS, sharpDeg = 20 } = {}) {
+// `segs` is the kernel's per-circle CAP: it bounds the blend densities (blendSegs)
+// and is what every circle was built at on a flat tier. `segsAt(r)` is what a circle
+// of radius r was ACTUALLY built at — the print tier sizes circles by chord tolerance
+// (circle-segs.js), so a flank's facet pitch is no longer the cap. The three places
+// that reason about the neighbouring tessellation (revolveTool's seam-grazing sag and
+// closed-revolve dephase, cornerHornTool's sphere burial) ask it; everything sized
+// from the blend's own sagitta bound keeps the cap. Absent, it is the cap — the
+// pre-print-rule behaviour, and byte-identical at preview either way.
+function apply(k, solid, mode, magnitude, { edges, segs = DEFAULT_SEGS, sharpDeg = 20, segsAt = null } = {}) {
   if (!(magnitude > 0)) throw new Error(`mesh ${mode}: magnitude must be > 0`);
+  const flankAt = segsAt ?? (() => segs);
   const chains = chainEdges(detectSharpEdges(solid.toIndexedMesh(), { sharpDeg }));
   const selected = chains.filter((ch) => matchesSelector(ch, edges));
   if (!selected.length) throw new UnsupportedEdgeError(`${mode} selector matched no sharp edges`);
@@ -1597,13 +1610,15 @@ function apply(k, solid, mode, magnitude, { edges, segs = DEFAULT_SEGS, sharpDeg
   const pSegs = blendSegs(segs, magnitude);
   const toolsFor = (ch) =>
     ch.kind === "planar"
-      ? planarTool(k, ch, magnitude, mode, segs, pSegs, endTins)
-      : [(ch.kind === "arc" ? revolveTool : prismTool)(k, ch, magnitude, mode, segs, pSegs)];
+      ? planarTool(k, ch, magnitude, mode, segs, pSegs, endTins, flankAt)
+      : ch.kind === "arc"
+        ? [revolveTool(k, ch, magnitude, mode, segs, pSegs, flankAt)]
+        : [prismTool(k, ch, magnitude, mode, segs, pSegs)];
   const cutters = [...effective, ...arcs].filter((ch) => ch.convex).flatMap(toolsFor);
-  cutters.push(...horns.map((h) => cornerHornTool(k, h, magnitude, segs)));
+  cutters.push(...horns.map((h) => cornerHornTool(k, h, magnitude, segs, flankAt)));
   cutters.push(...pivots.map((p) => reflexPivotTool(k, p, magnitude, mode, segs, pSegs)));
   const fillers = effective.filter((ch) => !ch.convex).flatMap(toolsFor);
-  if (mode === "fillet") cutters.push(...cornerPatches(k, effective, magnitude, segs));
+  if (mode === "fillet") cutters.push(...cornerPatches(k, effective, magnitude, segs, flankAt));
   let out = solid;
   if (cutters.length) out = out.cutAll(cutters);
   if (fillers.length) out = k.union([out, ...fillers]);

package/src/framework/geometry/profile.js

@@ -79,13 +79,16 @@ export function arcGeometry(p0, via, p1) {
 // three points; the sweep direction is the one whose arc actually passes through `via`
 // (sign-free, winding-free). Facet count scales with the sweep's fraction of the kernel's
 // full-circle resolution `segs`, matching the piePolygon/circleProfile convention, so an
-// arc and a circleProfile of equal radius facet identically. A degenerate (collinear)
-// triple falls back to a single straight segment to p1 — the same "plain line" the OCCT
-// side gets when roundedProfile emits no `via`.
+// arc and a circleProfile of equal radius facet identically. `segs` is either that count
+// or a function of the arc's radius returning one — the mesh backend's print tier sizes
+// circles by chord tolerance (circle-segs.js) and hands the samplers the rule rather
+// than a number. A degenerate (collinear) triple falls back to a single straight segment
+// to p1 — the same "plain line" the OCCT side gets when roundedProfile emits no `via`.
 export function sampleArc(p0, via, p1, segs) {
   const g = arcGeometry(p0, via, p1);
   if (!g) return [[p1[0], p1[1]]];                        // collinear → straight line
-  const steps = Math.max(2, Math.ceil((segs * Math.abs(g.dA)) / (2 * Math.PI)));
+  const n = typeof segs === "function" ? segs(g.r) : segs;
+  const steps = Math.max(2, Math.ceil((n * Math.abs(g.dA)) / (2 * Math.PI)));
   const out = [];
   for (let s = 1; s <= steps; s++) {
     const ang = g.a0 + g.dA * (s / steps);
@@ -102,8 +105,26 @@ export function sampleArc(p0, via, p1, segs) {
 // cubic tracing a circular arc facets like the arc primitive at the same segs. Summing
 // |turn| at BOTH interior control points also catches S-curves a pure endpoint-tangent
 // test would miss. Depth cap guarantees termination. Pure in (args, segs).
+//
+// `segs` may be a function of radius (see sampleArc). A cubic has no single radius, so
+// the budget is decided per sub-curve from the radius it traces, recovered from its
+// chord c and turn t as the circle on which a chord c subtends t: r = c / (2·sin(t/2)).
+// That is EXACT for a circular arc. For any other cubic the control polygon's turn t
+// overstates the curve's, so r errs small and the count errs LOW — a slightly coarser
+// budget, not a finer one. The bias is bounded by the ratio of polygon turn to curve
+// turn, which the recursion drives to 1 as the pieces shrink, and at the turns that
+// pass (≤ 2π/116) it is under 0.02 % of the count. A cubic tracing a circle of radius
+// r therefore facets like the arc primitive of radius r under the same rule.
 export function sampleBezier(p0, c1, c2, p1, segs) {
-  const maxTurn = (2 * Math.PI) / Math.max(3, segs);
+  const segsAt = typeof segs === "function" ? segs : null;
+  const flatTurn = segsAt ? null : (2 * Math.PI) / Math.max(3, segs);
+  const maxTurnFor = (a, d, t) => {
+    if (!segsAt) return flatTurn;
+    const chord = Math.hypot(d[0] - a[0], d[1] - a[1]);
+    const half = Math.sin(t / 2);                    // t ≤ 2π here: two turns of ≤ π each
+    const r = half > 1e-9 ? chord / (2 * half) : Infinity; // straight (t ≈ 0): the cap, and t ≤ budget anyway
+    return (2 * Math.PI) / Math.max(3, segsAt(r));
+  };
   const out = [];
   const mid = (a, b) => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
   const turn = (u, v) => {
@@ -117,7 +138,8 @@ export function sampleBezier(p0, c1, c2, p1, segs) {
     const ab = [b[0] - a[0], b[1] - a[1]];
     const bc = [c[0] - b[0], c[1] - b[1]];
     const cd = [d[0] - c[0], d[1] - c[1]];
-    if (depth >= 12 || turn(ab, bc) + turn(bc, cd) <= maxTurn) { out.push([d[0], d[1]]); return; }
+    const t = turn(ab, bc) + turn(bc, cd);
+    if (depth >= 12 || t <= maxTurnFor(a, d, t)) { out.push([d[0], d[1]]); return; }
     const p01 = mid(a, b), p12 = mid(b, c), p23 = mid(c, d);
     const p012 = mid(p01, p12), p123 = mid(p12, p23), m = mid(p012, p123);
     recurse(a, p01, p012, m, depth + 1);

package/src/framework/lint/rules-schema.js

@@ -4,6 +4,7 @@
 // resolve against `defaults`, which produce a control that silently does nothing.
 import { err, warn } from "./finding.js";
 import { suggest } from "../geometry/op-options.js";
+import { jsonValueProblem } from "../panel/json-value.js";
 import { fieldsFor, authorFieldsFor, WIDGET_TYPES, GROUP_FIELDS, PRESET_FIELDS, SECTION_FIELDS, normalizeOptions } from "../panel/widget-specs.js";
 import { sectionRenders, desugar } from "../panel/legacy.js";
 import { buildTree, WHEN_OPS } from "../panel/model.js";
@@ -253,6 +254,9 @@ export const SCHEMA_RULES = [
       const defaults = part.defaults;
       return collectDescriptors(part)
         .filter(({ container }) => !container)
+        // A custom control's OWN key may hold a JSON value; custom-default-not-json
+        // (below) is its rule. Its `keys` stay under this one via their own controls.
+        .filter(({ d }) => d.type !== "custom")
         .filter(({ d }) => typeof d.key === "string" && Object.hasOwn(defaults, d.key))
         .filter(({ d }) => !isEditableValue(defaults[d.key]))
         .map(({ d, path }) => err("control-default-not-primitive",
@@ -625,4 +629,56 @@ export const SCHEMA_RULES = [
       return out;
     },
   },
+  {
+    // The whole feature is the function: a missing or non-function `widget`
+    // renders the error card in the rail and nothing else, every time.
+    id: "custom-control-widget-not-function",
+    run: ({ part }) => collectDescriptors(part)
+      .filter(({ container, authored, d }) => authored && !container && d.type === "custom" && typeof d.widget !== "function")
+      .map(({ d, path }) => err("custom-control-widget-not-function",
+        `custom control "${d.key}" has no \`widget\` function`,
+        "Set `widget` to a function `(host) => …` — usually imported from a sibling file of the part — that draws into `host.el`. See \"Custom controls\" in AUTHORING-PARTS.md.",
+        `${path}.widget`)),
+  },
+  {
+    // The one relaxation of control-default-not-primitive: a custom control's
+    // key may hold a JSON value (json-value.js), and nothing else — a host that
+    // persists panel settings writes it back as a JSON literal.
+    id: "custom-default-not-json",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      const defaults = part.defaults;
+      return collectDescriptors(part)
+        .filter(({ container, authored, d }) => authored && !container && d.type === "custom")
+        .filter(({ d }) => typeof d.key === "string" && Object.hasOwn(defaults, d.key))
+        .map(({ d }) => ({ d, problem: jsonValueProblem(defaults[d.key]) }))
+        .filter(({ problem }) => problem !== null)
+        .map(({ d, problem }) => err("custom-default-not-json",
+          `\`defaults.${d.key}\` ${problem}`,
+          `Give "${d.key}" a JSON value: numbers, strings, booleans, arrays and plain objects of those, at most 16 KB and 8 levels deep, with no null. A custom control stores and persists its value as JSON, so anything else is silently lost on reload.`,
+          `defaults.${d.key}`));
+    },
+  },
+  {
+    // `keys` are params the widget writes besides its own; each needs a
+    // default or the write lands on a key the build never reads.
+    id: "custom-keys-not-in-defaults",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = defaultKeys(part);
+      const out = [];
+      for (const { d, path, container, authored } of collectDescriptors(part)) {
+        if (!authored || container || d.type !== "custom" || !Array.isArray(d.keys)) continue;
+        d.keys.forEach((k, i) => {
+          if (typeof k === "string" && known.has(k)) return;
+          const hint = typeof k === "string" ? suggest(k, [...known]) : null;
+          out.push(err("custom-keys-not-in-defaults",
+            `custom control "${d.key}" lists key "${k}", which is not in \`defaults\``,
+            `Add "${k}" to \`defaults\`${hint ? `, or correct it to "${hint}"` : ""} — a key the widget writes must exist for the build to read it.`,
+            `${path}.keys[${i}]`));
+        });
+      }
+      return out;
+    },
+  },
 ];

package/src/framework/lint/source-scan.js

@@ -12,6 +12,9 @@
 // closure (test/lint-purity.test.js) so lintPart keeps running in Node, the
 // browser sandbox iframe, and Deno.
 //
+// The one exception is json-value.js, which itself imports nothing — the
+// shared predicate for a `type: "custom"` control's value.
+//
 // KNOWN BLIND SPOT — regex literals are not tokenized: a `/[/*]/` or `/x\/y/`
 // reads as a comment opener and can blank the rest of the file, and a regex
 // containing a quote can likewise derail string skipping.
@@ -19,6 +22,8 @@
 // FALSE NEGATIVES — a derailed scan finds no defaults literal and no tokens,
 // so a rule says nothing rather than something wrong.
 
+import { isJsonValue, CUSTOM_VALUE_MAX_DEPTH } from "../panel/json-value.js";
+
 // Span of the object literal after the first `defaults:` key (indices into
 // `source`, end exclusive, covering `{...}`). String- and comment-aware so a
 // "defaults: {" inside a string or comment can't fool the scan.
@@ -191,8 +196,9 @@ function decodeStringLiteral(raw) {
 // into a different spelling of themselves.
 const NUMBER_RE = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 
-// One value's source text → { value }, or null when it is not a primitive
-// literal this module can read AND write back.
+// One value's source text → { value }, or null when it is not a literal this
+// module can read AND write back. Primitives first; then the JSON-literal
+// grammar a `type: "custom"` control's value is written in.
 function readValue(raw) {
   if (raw === "true") return { value: true };
   if (raw === "false") return { value: false };
@@ -205,6 +211,7 @@ function readValue(raw) {
     const s = decodeStringLiteral(raw);
     return s === null ? null : { value: s };
   }
+  if (q === "[" || q === "{") return readJsonLiteral(raw);
   return null;
 }
 
@@ -220,6 +227,113 @@ function readKey(text, i, end) {
   return m ? { key: m[0], next: i + m[0].length } : null;
 }
 
+// --- JSON literals ----------------------------------------------------------
+//
+// The grammar a custom control's owned value is spelled in inside `defaults`:
+// object and array literals of primitives, nested; bare or quoted keys; JS
+// string escapes (the same decoder as above); decimal numbers; true/false;
+// trailing commas; whitespace. NOTHING else — no comments inside the span, no
+// expressions, identifiers, templates, `null`, computed keys, spreads — so
+// every value this reads, writeJsonLiteral can write back and this can read
+// again. A parse failure is null, never a throw: the entry simply stays
+// unreadable, exactly as an expression does.
+//
+// `depth` is threaded through value/array/object and checked BEFORE
+// recursing into a container, so pathological nesting (thousands of `[`)
+// fails fast during parsing instead of blowing the JS call stack — a
+// RangeError would escape readJsonLiteral's try/catch (it only catches
+// JsonLiteralError) and reach a host outside runRules' own try/catch. The
+// threshold matches json-value.js's own depth check exactly (same "depth at
+// which this container sits" numbering), so this is a fast-fail that agrees
+// with the post-parse isJsonValue call below, never a stricter or looser one.
+
+class JsonLiteralError extends Error {}
+
+function jsonParser(text) {
+  let i = 0;
+  const fail = () => { throw new JsonLiteralError(); };
+  const ws = () => { while (i < text.length && /\s/.test(text[i])) i++; };
+  const value = (depth = 0) => {
+    ws();
+    const c = text[i];
+    if (c === "{") return object(depth);
+    if (c === "[") return array(depth);
+    if (c === '"' || c === "'") {
+      const end = skipQuoted(text, i, text.length);
+      const s = decodeStringLiteral(text.slice(i, end));
+      if (s === null) fail();
+      i = end;
+      return s;
+    }
+    const m = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/.exec(text.slice(i));
+    if (m) { i += m[0].length; const n = Number(m[0]); if (!Number.isFinite(n)) fail(); return n; }
+    if (text.startsWith("true", i)) { i += 4; return true; }
+    if (text.startsWith("false", i)) { i += 5; return false; }
+    return fail();
+  };
+  const array = (depth) => {
+    if (depth >= CUSTOM_VALUE_MAX_DEPTH) fail();
+    i++; // [
+    const out = [];
+    for (;;) {
+      ws();
+      if (text[i] === "]") { i++; return out; }
+      if (out.length) { if (text[i] !== ",") fail(); i++; ws(); if (text[i] === "]") { i++; return out; } }
+      out.push(value(depth + 1));
+    }
+  };
+  const object = (depth) => {
+    if (depth >= CUSTOM_VALUE_MAX_DEPTH) fail();
+    i++; // {
+    const out = {};
+    let n = 0;
+    for (;;) {
+      ws();
+      if (text[i] === "}") { i++; return out; }
+      if (n) { if (text[i] !== ",") fail(); i++; ws(); if (text[i] === "}") { i++; return out; } }
+      const k = readKey(text, i, text.length);
+      if (!k) fail();
+      i = k.next;
+      ws();
+      if (text[i] !== ":") fail();
+      i++;
+      const v = value(depth + 1);
+      Object.defineProperty(out, k.key, { value: v, enumerable: true, writable: true, configurable: true });
+      n++;
+    }
+  };
+  return { value, done: () => { ws(); return i === text.length; } };
+}
+
+// An array or object literal's source text → { value }, or null. Applies the
+// custom-value caps (json-value.js) so a literal lint accepts is one the panel
+// would accept too.
+export function readJsonLiteral(text) {
+  if (typeof text !== "string") return null;
+  const first = text.trimStart()[0];
+  if (first !== "[" && first !== "{") return null;
+  try {
+    const p = jsonParser(text);
+    const v = p.value();
+    if (!p.done()) return null;
+    return isJsonValue(v) ? { value: v } : null;
+  } catch (e) {
+    if (e instanceof JsonLiteralError) return null;
+    throw e;
+  }
+}
+
+// The source text for a JSON value being written into `defaults`: compact
+// when it fits on a line, else indented two spaces deeper than the entry's
+// own indentation (`indent`, the whitespace before the entry's key) so a large
+// layout diffs line by line. Always plain JSON — quoted keys — so the reader
+// above accepts it unchanged.
+export function writeJsonLiteral(value, { indent = "" } = {}) {
+  const compact = JSON.stringify(value);
+  if (compact.length <= 80) return compact;
+  return JSON.stringify(value, null, 2).replace(/\n/g, `\n${indent}`);
+}
+
 // Split `{ … }` into entries in source order. `readable` says whether the
 // value was interpreted; `raw` is its exact source text either way, and
 // valueStart/valueEnd are its span (indices into `text`), which is what a

package/src/framework/mount.js

@@ -63,7 +63,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -101,6 +101,14 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       projection: viewer.getProjection?.() ?? "perspective",
       cutaway: viewer.getCutawayState?.() ?? null,
     }),
+    // Every custom control's transient state (selection, a scroll position),
+    // keyed by param, as plain JSON — the panel's twin of getViewerState. Hand
+    // it back as mount()'s `panelState` and a remount comes up with the same
+    // tile selected. {} when the mount resolved no panel.
+    getPanelState: getPanelState ?? (() => ({})),
+    // What custom controls reported failing this mount ({key, label, phase,
+    // message}), for a host to relay to whoever authored the part.
+    getPanelErrors: getPanelErrors ?? (() => []),
     // Park/unpark the viewer: stops the render loop and frees the drawing
     // buffer and the cached capture target. For an embedder that hides the
     // canvas without unmounting it — `visibility: hidden`, an off-screen tab —
@@ -305,6 +313,13 @@ function createCleanupStack() {
 //                                         // first mount — the viewer then restores its own persisted
 //                                         // camera as before. Restore is best-effort per field: a pose
 //                                         // this part cannot support is dropped, never fatal.
+// panelState: PanelState                 // a previous mount's runtime.getPanelState(): the transient
+//                                         // state of the part's custom controls (a selected tile), keyed
+//                                         // by param. Same remount story as viewerState; omit on a first
+//                                         // mount. Never persisted by partforge.
+// files: { [path]: string }              // the part's own source tree as text, for custom controls'
+//                                         // host.file(path) — an SVG or a vector document that lives
+//                                         // beside the code. Omit and host.file answers null.
 // annotateSend: "viewbar" | "host"       // who owns the Send affordance. "viewbar" (default) puts
 //                                         // Send in the sketch toolbar alongside the other tools.
 //                                         // "host" drops it: the host draws its own send control —
@@ -331,6 +346,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
                               imageCatalog,
                               onAssetUpload,
                               viewerState,
+                              files, panelState,
                               annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
@@ -1017,7 +1033,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       // 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) });
+        declaredSource: declaredSourceLookup(part, params),
+        files, panelState });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {
@@ -1194,6 +1211,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       getView: view,                         // () => tabsCtl.current()
       setView: (name) => tabsCtl.select(name),
       captureView,
+      getPanelState: () => panelRef?.getState() ?? {},
+      getPanelErrors: () => panelRef?.errors() ?? [],
       listExportableParts: () =>
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),

package/src/framework/panel/author.js

@@ -44,6 +44,11 @@ function authoredControl(c) {
     allow: c.allow,
     preview: c.preview,
     sourceField: c.sourceField,
+    // Custom controls (type: "custom"): the author's widget function and the
+    // extra scalar keys it may write. Both are on this allow-list for the same
+    // reason `allow` is (see above) — a field missing here is silently dropped.
+    widget: c.widget,
+    keys: c.keys,
     preserveOn: false,
     marksCustom: true,
   };

package/src/framework/panel/json-value.js

@@ -0,0 +1,55 @@
+//
+// The ONE predicate for the value a `type: "custom"` control may own. The panel
+// (host.set, panel state), lint (custom-default-not-json) and partforge-cloud's
+// persistence (through the `partforge/panel-values` export) all ask this module,
+// so "the linter accepts it" and "the save can write it" cannot drift apart.
+//
+// Imports nothing: it sits inside partforge/lint's pure closure
+// (test/lint-purity.test.js) and inside the sandbox iframe.
+
+export const CUSTOM_VALUE_MAX_BYTES = 16384;
+export const CUSTOM_VALUE_MAX_DEPTH = 8;
+
+// Keys a JSON value may never carry: on a plain object each of these reaches
+// Object.prototype, so a value that round-trips through JSON.parse and a
+// plain-object assignment could change what `params.x.constructor` means.
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+const at = (path) => (path ? ` at ${path}` : "");
+
+function shapeProblem(v, depth, maxDepth, path) {
+  if (v === null) return `is null${at(path)}`;
+  const t = typeof v;
+  if (t === "number") return Number.isFinite(v) ? null : `is a non-finite number${at(path)}`;
+  if (t === "string" || t === "boolean") return null;
+  if (t !== "object") return `is a ${t}${at(path)}`;
+  if (depth >= maxDepth) return `nests deeper than ${maxDepth} levels${at(path)}`;
+  if (Array.isArray(v)) {
+    for (let i = 0; i < v.length; i++) {
+      const p = shapeProblem(v[i], depth + 1, maxDepth, `${path}[${i}]`);
+      if (p) return p;
+    }
+    return null;
+  }
+  const proto = Object.getPrototypeOf(v);
+  if (proto !== Object.prototype && proto !== null) return `is not a plain object${at(path)}`;
+  for (const k of Object.keys(v)) {
+    if (FORBIDDEN_KEYS.has(k)) return `uses the forbidden key "${k}"${at(path)}`;
+    const p = shapeProblem(v[k], depth + 1, maxDepth, path ? `${path}.${k}` : k);
+    if (p) return p;
+  }
+  return null;
+}
+
+// Why `v` is not a JSON value — a sentence fragment that reads after the
+// value's name ("`defaults.tiles` is null at tiles[2].h") — or null when it is.
+export function jsonValueProblem(v, { maxBytes = CUSTOM_VALUE_MAX_BYTES, maxDepth = CUSTOM_VALUE_MAX_DEPTH } = {}) {
+  const shape = shapeProblem(v, 0, maxDepth, "");
+  if (shape) return shape;
+  if (maxBytes === Infinity) return null;
+  const bytes = new TextEncoder().encode(JSON.stringify(v)).length;
+  if (bytes > maxBytes) return `is ${bytes} bytes serialized; the cap is ${maxBytes}`;
+  return null;
+}
+
+export const isJsonValue = (v, opts) => jsonValueProblem(v, opts) === null;