partforge 0.112.0 → 0.114.0

package/docs/AUTHORING-PARTS.md

@@ -436,6 +436,7 @@ offsetPolygon(outline, -wall, { corners: "sharp" });                     // inse
 const tab = pathProfile([0, -w / 2])
   .lineTo([len, -w / 2])
   .arcTo([len, w / 2], [len + w / 2, 0])   // tip, via the apex
+  // same arc: .arcTo([len, w / 2], { r: w / 2 }) — radius form, no via to compute
   .lineTo([0, w / 2])
   .close();
 k.extrude({ profile: tab, h: 3 });
@@ -445,6 +446,7 @@ const lip = pathProfile([0, 0])
   .lineTo([20, 0]).lineTo([20, 8])
   .cubicTo([0, 8], [14, 16], [6, 16])   // curved top edge
   .close();
+k.extrude({ profile: lip, h: 3 });
 
 // Rounded enclosure: soft vertical edges, a softer lid, a flat base.
 const shell = k.roundedBox({ size: [60, 40, 22], round: { side: 4, top: 2, bottom: 0 } });
@@ -470,7 +472,7 @@ dumbbell past its waist) **throws** a greppable error rather than returning dege
 geometry. Being pure, it works in `derive()` as well as `build()` — the natural home for
 clearance math.
 `pathProfile(start)` is a fluent builder for a curve-native path contour (`lineTo` / `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep spline edges on the OCCT/STEP backend and facet at the mesh LOD on Manifold — the same exact-vs-faceted split as `roundedProfile` arcs.
-`arcTo(to, via)` is a **three-point arc**: `via` is any point on the arc between the current point and `to` (its midpoint is the natural choice), and the sweep is whichever direction passes through it — so an arc's direction is a property of a point you can see, never of a sign. Build the symmetric half of a profile once and `mirrorProfile` it (see "Editing profiles") rather than writing the mirrored arcs by hand. `loft` accepts these contours as rings (every ring with the same segment signature lofts curve-to-curve).
+`arcTo(to, via)` is a **three-point arc**: `via` is any point on the arc between the current point and `to` (its midpoint is the natural choice), and the sweep is whichever direction passes through it — so an arc's direction is a property of a point you can see, never of a sign. `arcTo(to, { r, sweep?, large? })` is the **radius form** for when you know the radius, not a point on the arc: it computes `via` from the current point, `to`, and `r`, emitting the exact same `{to, via}` segment the three-point form does. `sweep` names the direction the arc itself is traversed (default `"ccw"`), so on a counter-clockwise outline `"ccw"` bulges OUTWARD (a convex bump), and inward on a clockwise hole; `"cw"` is the reverse. `large` (default `false`) picks the major arc over the minor one when both are possible. A radius shorter than half the distance between the current point and `to` throws rather than being silently scaled up (the way SVG's arc command does) — the smallest circle joining the two points is a semicircle at `r = d/2`. Build the symmetric half of a profile once and `mirrorProfile` it (see "Editing profiles") rather than writing the mirrored arcs by hand. `loft` accepts these contours as rings (every ring with the same segment signature lofts curve-to-curve).
 **`pathProfile` or an authored vector file?** Reach for `pathProfile` (and the polygon helpers above) when the geometry is **computed from parameters** — a profile whose dimensions come from `p`/`d`, which a JSON file cannot see. Reach for an authored `partforge-vector` document (`k.vector2d`, see "Vector geometry" below) when the geometry is **drawn** — a logo, a faceplate outline, a decorative cutout, where each number means one thing and gets edited on its own. The two are freely composable: both produce ordinary 2-D geometry that the same booleans and editing ops accept.
 **Import geometry helpers from `partforge/geometry`, never from `partforge`** — the main
 entry pulls in the DOM viewer/controls, and your build functions run in a Web Worker
@@ -743,6 +745,7 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"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` |
+| `"custom"` | a widget the part draws itself — see "Custom controls" below | `widget`, `keys` |
 
 Numeric controls always show the number box: drag the slider *or* type an exact
 value. Typed values may be finer than `step` and may sit **outside `[min, max]`**:
@@ -952,6 +955,132 @@ pickers in one section both need to show divergence, give each its own section.
 case per preset name (so every preset gets measured), and a repeated name throws
 there. `duplicate-preset-name` catches it at lint time instead.
 
+### Custom controls
+
+A `type: "custom"` control renders a widget the part draws itself — a clickable hex
+grid, an organizer whose walls toggle on click, a picture of the part's own outline
+with hot regions. Reach for it when the user configures **many similar things
+individually**, or makes a **spatial choice** no slider or select can express.
+Never for a value an existing control already covers: a slider is still a slider.
+
+```js
+// part.js
+import { tilePicker } from "./tile-picker.js";
+
+export default {
+  defaults: {
+    tileSize: 20,
+    tiles: [{ q: 0, r: 0, height: 10 }, { q: 1, r: 0, height: 14 }],
+  },
+  parameters: [{
+    title: "Tiles",
+    controls: [
+      { type: "slider", key: "tileSize", min: 10, max: 40 },
+      { type: "custom", key: "tiles", label: "Tile layout", widget: tilePicker,
+        description: "Click a tile to select it. Drag to move it." },
+    ],
+  }],
+  parts: { tiles: { build: (k, p) => /* p.tiles is the array */ } },
+};
+```
+
+- `key` names the param the widget owns. It may hold a **JSON value**: numbers,
+  strings, booleans, arrays and plain objects of those, at most 16 KB serialized and
+  8 levels deep, never `null` (`custom-default-not-json`). `build()` reads it like any
+  other param. This is the one place the "a control writes one scalar" rule is relaxed.
+- `keys` (optional) lists further scalar params the widget may also write.
+- `widget` is a function `(host) => …`, normally imported from a sibling file so
+  `part.js` stays readable (`custom-control-widget-not-function`).
+- `label`, `description`, `hidden`, `when` and `whenFalse` behave as on any control.
+
+**The widget function.** It runs once per mount and draws into `host.el` with plain
+DOM and SVG. It may return `{ update, dispose }`.
+
+```js
+// tile-picker.js
+export function tilePicker(host) {
+  const svg = host.h("svg", { viewBox: "0 0 200 160", width: "100%" });
+  const detail = host.h("div");
+  host.el.append(svg, detail);
+  let stopDetail = null;
+
+  function draw() {
+    const tiles = host.get();                 // a fresh clone of the owned value
+    const sel = host.state.selected ?? null;  // survives the remount an edit performs
+    svg.replaceChildren(...tiles.map((t, i) => host.h("polygon", {
+      points: hexPoints(t.q, t.r), class: i === sel ? "pf-hit selected" : "pf-hit",
+      onpointerdown: () => { host.setState({ selected: i }); draw(); },
+    })));
+    stopDetail?.();
+    stopDetail = sel === null ? null : host.controls(detail, [
+      { type: "slider", key: "height", label: "Height", min: 4, max: 30 },
+    ], { path: `${sel}` });
+  }
+  draw();
+  return { update: draw, dispose: () => stopDetail?.() };
+}
+```
+
+**The host.**
+
+| Member | Meaning |
+|---|---|
+| `host.el`, `host.doc` | The slot to draw into, and its document. |
+| `host.get(key?)` | A clone of the current value (default: the owned key). Any param is readable. |
+| `host.set(value, {key?, commit?})` | Replace a value with a **new** one — never mutate what `get` returned. Schedules the rebuild and commits, unless `commit: false`; then call `host.commit()` when the gesture ends (a drag). Throws for a key you do not own or a value outside the contract. On a **retired** widget (one whose code already threw) `set`, `commit` and `setState` are silent no-ops. |
+| `host.commit(keys?)` | Ends a deferred gesture. A no-op when nothing changed. |
+| `host.derived` | The latest `derive()` output, the same object readouts show. |
+| `host.state`, `host.setState(patch)` | Transient JSON (a selection, an open panel). Not a param, never persisted, but it **survives a remount**, which every edit performs. |
+| `host.controls(container, controls, {path})` | Mount ordinary built-in controls bound *inside* the owned value at a dotted `path` (`"3"`, `"walls.north"`). Their edits commit the owning key. Returns a disposer. One level: no custom control inside, and no `font`, `image` or `vector` sub-control at a path (their asset lookups are keyed on the part's real param names). |
+| `host.h(tag, attrs, ...children)` | Element builder. SVG tags get the SVG namespace; `on<event>` attrs become listeners; `class` and `style` pass through. |
+| `host.svg(text)` | Parse an SVG string to an element you can append and wire up. |
+| `host.svgFromVector(doc)` | A partforge-vector document → inline `<svg>` (the same renderer the `vector` control uses). |
+| `host.file(pathOrToken)` | Text of one of the part's own files, by path or a `pfc-tree://` token, or null. |
+| `host.disabled` | Whether a `when`/`whenFalse: "disable"` currently disables this control. |
+
+`update({reason, disabled})` is called when your key changes from outside the widget
+(`reason: "sync"` — a preset, undo, `setParams`), when `derived` changes
+(`"derived"`), and once after `host.state` was restored on mount (`"restore"`). It is
+**not** called for your own `set`. `dispose()` runs on teardown.
+
+**Rules that keep it working.**
+
+1. Size SVG with `viewBox` plus `width: 100%`. The rail is 288px wide by default and
+   narrower on a phone, where it is the bottom sheet.
+2. Use pointer events, not mouse events, and put `class="pf-drag"` (or
+   `touch-action: none`) on anything dragged — otherwise a finger scrolls the sheet.
+3. Keep selection and similar state in `host.state`, not in a closure: every edit
+   remounts the part and your function runs again.
+4. Hand `set` a new value. `get` returns a clone precisely so the stored value is never
+   edited in place.
+5. A throw in creation, `update`, or a listener installed through `host.h` replaces
+   the widget with an error card and reports it (a hosting agent sees it in the apply
+   result as `panelErrors`); other controls keep working. A throw in `dispose` is
+   reported the same way but leaves no card — there is nothing left to show it on. A
+   listener you attach yourself with `addEventListener`, rather than through `host.h`,
+   is **not** guarded — wire listeners through `host.h`, or wrap your own in try/catch.
+
+**Looking native.** The slot inherits the rail's font, colours and light/dark theme.
+Bare `<button>`, `<input>` and `<select>` elements pick up the built-in looks
+automatically; the built-in classes are available by name for the exact thing:
+`row`, `seg` (a segmented row of buttons), `action`, `ghost`, `num`, `text-input`,
+`select-input`; and for SVG, `pf-hit` (clickable, with a `selected` state) and
+`pf-drag`. Sub-controls mounted through `host.controls` *are* the built-in widgets.
+
+**Reading the part's own files.** Artwork can live beside the code (the tree is text,
+so an SVG, a `partforge-vector` JSON document or a JSON data file — not a PNG).
+Two routes: store the SVG as a string in a JS module (`assets/emblem.svg.js` exporting
+a template literal) and import it like any sibling file — no framework support
+needed; or read it with `host.file("assets/emblem.svg")` and inline it with
+`host.svg(text)`. Give regions ids and wire `pointerdown` on `#wall-3` to toggle
+`walls[3]` in the owned value.
+
+**What a widget cannot do.** Never `fetch` or otherwise reach the network — a widget
+is a pure function of the part and its params, and a hosted sandbox may refuse the
+request or have no credentials to make it with. Also: no imports beyond the part's
+own files, nothing outside `host.el`, and no reading of `params` except through
+`host`.
+
 ### Legacy section shapes (still supported)
 
 Everything above is what a **new part should write**. The original array-based shapes
@@ -1141,6 +1270,10 @@ defaulting everything to a slider:
   reason for a two-position slider to exist.
 - **A computed value the user should see but not set** → `"readout"`. It costs no
   parameter and answers the "so what did that do?" question in place.
+- **Many similar things configured individually, or a spatial choice** (which tiles
+  exist and how tall each is; which walls of an organizer are present) →
+  `"custom"`: a widget the part draws, holding one JSON value. See "Custom controls"
+  above; use it only when no built-in control expresses the choice.
 
 Then gate what doesn't always apply. A control that is meaningless in the current mode
 should carry a **`when`** rather than sit there inert — hide it by default, or use
@@ -2789,7 +2922,9 @@ previously didn't; that's the fix working as intended, not a regression.
 `preset-key-not-in-defaults`, `mixed-section-shape`,
 `duplicate-preset-name`, `duplicate-node-id`, `select-options-missing`,
 `select-default-not-in-options`, `log-scale-needs-positive-min`,
-`when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type` (errors);
+`when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type`,
+`custom-control-widget-not-function`, `custom-default-not-json`,
+`custom-keys-not-in-defaults` (errors);
 `slider-range-excludes-default`, `unknown-control-field`, `duplicate-control-key`,
 `default-not-exposed`, `readout-unknown-derived-key`, `slider-refinement-invalid`,
 `group-depth`, `section-too-many-controls` (warnings).
@@ -2800,6 +2935,10 @@ can't coexist, since mixing them would make the render order arbitrary. Move
 the legacy entries into `controls` (a toggle becomes a checkbox control,
 `advanced` becomes a nested group, `presets` becomes `{ type: "preset" }`
 nodes), or drop `controls` and stay legacy.
+`custom-default-not-json` is `control-default-not-primitive`'s counterpart for a
+`type: "custom"` control, whose key may hold a JSON value (see "Custom controls"):
+it names the first member that is not one — `null`, a function, a class instance,
+a forbidden key, or a value past the 16 KB / depth-8 caps.
 `duplicate-preset-name` fires when the same preset name is declared twice
 (legacy `presets` and/or `{ type: "preset" }` nodes both count) — preset names
 are global to the part, and `verify()` expands one case per name and throws on

package/docs/ERROR-PATTERNS.md

@@ -316,6 +316,12 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 - **Cause:** A cubic segment is missing `c1` or `c2`, or a control point is not a finite `[x,y]` (e.g. `NaN`, wrong length).
 - **Fix:** Provide both control points as finite `[x,y]`. A cubic Bézier needs two controls between the previous point and `to`.
 
+## arcto-radius-too-short
+
+- **Symptom:** `pathProfile: arcTo r=<r> is shorter than half the chord (<half-chord>) from (<x0>, <y0>) to (<x1>, <y1>) — the smallest arc that can join these points has r=<half-chord> (a semicircle)`
+- **Cause:** `pathProfile().arcTo(to, { r, sweep?, large? })`'s `r` is smaller than half the distance between the current point and `to` — no circle of that radius passes through both points.
+- **Fix:** Raise `r` to at least half the chord (the message states the exact minimum), or move the endpoint closer. Unlike SVG's arc command, partforge refuses rather than silently scaling `r` up to fit — the model should learn the number it wrote was wrong rather than have it quietly corrected.
+
 ## shape2d-simple-not-single-region
 
 - **Symptom:** `Shape2D.simple: result has N regions, not 1 (use toRegions())`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.112.0",
+  "version": "0.114.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",
@@ -58,6 +58,10 @@
       "types": "./types/ingest.d.ts",
       "default": "./src/ingest.js"
     },
+    "./panel-values": {
+      "types": "./types/panel-values.d.ts",
+      "default": "./src/panel-values.js"
+    },
     "./tokens.css": "./src/framework/tokens.css",
     "./chrome.css": "./src/framework/chrome.css"
   },
@@ -83,6 +87,9 @@
       ],
       "ingest": [
         "./types/ingest.d.ts"
+      ],
+      "panel-values": [
+        "./types/panel-values.d.ts"
       ]
     }
   },

package/src/framework/app.css

@@ -64,8 +64,10 @@ canvas { display: block; }
    Condition-hidden sections (.hidden, a `when` that evaluated false) are excluded
    for the same reason. Do not simplify this to `.section:first-child { border-top: 0 }` — that
    matches DOM position rather than visibility, and leaves a stray divider
-   floating at the top whenever applyRelevance hides the first section. */
-.section:not(.section-hidden):not(.hidden) ~ .section:not(.section-hidden):not(.hidden) {
+   floating at the top whenever applyRelevance hides the first section. A bare
+   sub-panel section (host.controls inside a custom control) never gets the divider
+   because the widget owns its framing. */
+.section:not(.section-hidden):not(.hidden) ~ .section:not(.section-hidden):not(.hidden):not(.bare) {
   border-top: 1px solid var(--pf-border);
 }
 /* Section disclosure header: the whole row is the click target (render.js
@@ -382,6 +384,52 @@ button.ghost { background: transparent; border: 1px solid var(--pf-border); colo
 button.ghost:hover:not(:disabled) { background: var(--pf-surface-2); }
 button.action:disabled { opacity: .5; cursor: default; }
 
+/* Custom controls (type: "custom"): a part-authored widget in the rail. The
+   slot inherits the rail's cascade (font, colours, --pf-* tokens); these rules
+   give BARE elements the built-in controls' look so a widget written with
+   plain <button>/<input>/<select> still reads as native, and provide two
+   opt-in classes for SVG: .pf-hit (a clickable region) and .pf-drag (a
+   dragged one — touch-action: none is what lets a finger drag it on a phone
+   instead of scrolling the sheet). */
+.pf-custom { margin: 9px 0; }
+.pf-custom.hidden { display: none; }
+.pf-custom-slot { display: flow-root; }
+/* Every selector in this block is wrapped so the WHOLE thing resolves to
+   (0,0,0) — including the :not([type=...]) chain, which is otherwise an
+   attribute selector per :not() and would still out-specify a class rule
+   like .text-input (0,1,0) or .row .num (0,2,0). At true zero specificity,
+   any class rule wins, so a named built-in class (.seg button, .text-input,
+   select.select-input, …) always beats these bare-element defaults. */
+:where(.pf-custom) :where(svg) { display: block; max-width: 100%; height: auto; }
+:where(.pf-custom) :where(button) {
+  font: inherit; font-size: 12px; padding: 5px 9px; cursor: pointer;
+  background: transparent; border: 1px solid var(--pf-border); color: var(--pf-text-2);
+  border-radius: var(--pf-radius-control);
+}
+:where(.pf-custom) :where(button:hover:not(:disabled)) { background: var(--pf-surface-2); }
+:where(.pf-custom) :where(button:disabled) { opacity: .5; cursor: default; }
+:where(.pf-custom) :where(input:not([type="range"]):not([type="checkbox"]):not([type="radio"]), select) {
+  font: 12px/1.4 var(--pf-mono);
+  background: var(--pf-input-bg); color: var(--pf-text-strong);
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 6px 8px;
+}
+:where(.pf-custom) :where(input:focus, select:focus, button:focus-visible) {
+  outline: none; border-color: var(--pf-accent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
+}
+.pf-custom .pf-hit { cursor: pointer; }
+.pf-custom .pf-hit:hover { fill: color-mix(in oklab, var(--pf-accent) 25%, transparent); }
+.pf-custom .pf-hit.selected { fill: color-mix(in oklab, var(--pf-accent) 45%, transparent); stroke: var(--pf-accent); }
+.pf-custom .pf-drag { touch-action: none; }
+.pf-custom-error {
+  margin: 4px 0; padding: 6px 8px; border: 1px solid var(--pf-err); border-radius: var(--pf-radius-control);
+  color: var(--pf-err); font-family: var(--pf-mono); font-size: 11px; line-height: 1.4; word-break: break-word;
+}
+.pf-custom-error-title { font-weight: 600; margin-bottom: 2px; }
+/* A sub-panel inside a custom control (host.controls): no header, no indent. */
+.section.bare > .sec-body { padding: 0; }
+.section.bare { padding: 0; border: 0; }
+
 .dl { margin-top: 14px; }
 .dl-head {
   font-family: var(--pf-mono); font-size: 10px; font-weight: 600;

package/src/framework/geometry/polygon.js

@@ -157,8 +157,9 @@ export function filletPolygon(points, r, { segs = 8 } = {}) {
 }
 
 // Fluent builder for a curve-native path contour { start, segments }. Segment kinds:
-// lineTo → {to}, arcTo → {to,via} (three-point arc), cubicTo → {to,c1,c2} (cubic Bézier).
-// close() returns the plain contour object (feeds extrude/revolve/prism), not a Solid.
+// lineTo → {to}, arcTo → {to,via} (three-point arc) or {to,via} computed from a radius
+// spec, cubicTo → {to,c1,c2} (cubic Bézier). close() returns the plain contour object
+// (feeds extrude/revolve/prism), not a Solid.
 export function pathProfile(start) {
   const fin2 = (p, what) => {
     if (!Array.isArray(p) || p.length < 2 || !Number.isFinite(p[0]) || !Number.isFinite(p[1]))
@@ -166,12 +167,73 @@ export function pathProfile(start) {
     return [p[0], p[1]];
   };
   const s = fin2(start, "start");
+  let cur = s;
   const segments = [];
   const api = {
-    lineTo(to) { segments.push({ to: fin2(to, "lineTo point") }); return api; },
-    arcTo(to, via) { segments.push({ to: fin2(to, "arcTo point"), via: fin2(via, "arcTo via") }); return api; },
+    lineTo(to) {
+      const p = fin2(to, "lineTo point");
+      segments.push({ to: p });
+      cur = p;
+      return api;
+    },
+    // arcTo(to, via) is the three-point form: `via` is any point on the arc.
+    // arcTo(to, { r, sweep?, large? }) is the radius form: `via` is computed here
+    // from the current point, `to`, and the radius spec so the emitted segment is
+    // byte-for-byte what the three-point form emits (see docs/AUTHORING-PARTS.md).
+    arcTo(to, second) {
+      const p1 = fin2(to, "arcTo point");
+      if (Array.isArray(second)) {
+        const via = fin2(second, "arcTo via");
+        segments.push({ to: p1, via });
+        cur = p1;
+        return api;
+      }
+      if (second !== null && typeof second === "object") {
+        const ARC_SPEC_KEYS = ["r", "sweep", "large"];
+        const unknownKeys = Object.keys(second).filter((k) => !ARC_SPEC_KEYS.includes(k));
+        if (unknownKeys.length > 0)
+          throw new Error(
+            `pathProfile: arcTo arc spec has unknown ${unknownKeys.length > 1 ? "keys" : "key"} ${unknownKeys.map((k) => JSON.stringify(k)).join(", ")} — the keys are r, sweep, large`,
+          );
+        const { r, sweep = "ccw", large = false } = second;
+        // Cheap key/enum/boolean checks run BEFORE the numeric ones below, so a
+        // typo'd sweep/large is reported on its own rather than being masked by
+        // an unrelated radius complaint on the same call.
+        if (sweep !== "ccw" && sweep !== "cw")
+          throw new Error(`pathProfile: arcTo sweep must be "ccw" or "cw", got ${JSON.stringify(sweep)}`);
+        if (typeof large !== "boolean")
+          throw new Error("pathProfile: arcTo large must be a boolean");
+        const [x0, y0] = cur;
+        const [x1, y1] = p1;
+        const dx = x1 - x0, dy = y1 - y0;
+        const d = Math.hypot(dx, dy);
+        if (d < 1e-9)
+          throw new Error(`pathProfile: arcTo to (${x1}, ${y1}) coincides with the current point`);
+        if (!(r > 0) || !Number.isFinite(r))
+          throw new Error(`pathProfile: arcTo r must be > 0 and finite, got ${JSON.stringify(r)}`);
+        if (r < d / 2 - 1e-9)
+          throw new Error(
+            `pathProfile: arcTo r=${r} is shorter than half the chord (${(d / 2).toFixed(4)}) from (${x0}, ${y0}) to (${x1}, ${y1}) — the smallest arc that can join these points has r=${(d / 2).toFixed(4)} (a semicircle)`,
+          );
+        const rr = Math.max(r, d / 2);                    // absorb the 1e-9 tolerance so h is never NaN
+        const h = Math.sqrt(rr * rr - (d / 2) * (d / 2));  // centre's distance from the chord midpoint
+        const ux = dx / d, uy = dy / d;                    // unit chord direction
+        const nx = -uy, ny = ux;                           // unit LEFT normal of the direction of travel
+        const mx = (x0 + x1) / 2, my = (y0 + y1) / 2;
+        const side = sweep === "ccw" ? -1 : 1;             // which side of the chord the arc bulges to
+        const sgn = large ? side : -side;
+        const cx = mx + nx * h * sgn, cy = my + ny * h * sgn;
+        const via = [cx + nx * rr * side, cy + ny * rr * side]; // the arc's midpoint
+        segments.push({ to: p1, via });
+        cur = p1;
+        return api;
+      }
+      throw new Error("pathProfile: arcTo needs a via [x,y] or an { r, sweep?, large? } arc spec");
+    },
     cubicTo(to, c1, c2) {
-      segments.push({ to: fin2(to, "cubicTo point"), c1: fin2(c1, "cubicTo c1"), c2: fin2(c2, "cubicTo c2") });
+      const p = fin2(to, "cubicTo point");
+      segments.push({ to: p, c1: fin2(c1, "cubicTo c1"), c2: fin2(c2, "cubicTo c2") });
+      cur = p;
       return api;
     },
     close() {

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