partforge 0.112.0 → 0.114.0

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

@@ -7,6 +7,7 @@ import { makeSelect, makeRadio } from "./select.js";
 import { makeFont } from "./font.js";
 import { makeImage } from "./image.js";
 import { makeVector } from "./vector.js";
+import { makeCustom } from "./custom.js";
 // Side-effect imports: font-picker.js / image-picker.js call setFontPicker() /
 // setImagePicker() at module scope, so each widget's button finds a picker to
 // open. They live HERE and not in font.js/image.js because the dependency has
@@ -27,4 +28,5 @@ export const WIDGET_FACTORIES = {
   font: makeFont,
   image: makeImage,
   vector: makeVector,
+  custom: makeCustom,
 };

package/src/panel-values.js

@@ -0,0 +1,6 @@
+// Public entry for `partforge/panel-values`: the value contract of a
+// `type: "custom"` control, for hosts that persist panel settings (partforge-
+// cloud rewrites `defaults` with these). Dependency-free, DOM-free, tiny — a
+// host imports this without pulling partforge/lint's rule set into its bundle.
+export { isJsonValue, jsonValueProblem, CUSTOM_VALUE_MAX_BYTES, CUSTOM_VALUE_MAX_DEPTH } from "./framework/panel/json-value.js";
+export { readJsonLiteral, writeJsonLiteral } from "./framework/lint/source-scan.js";

package/types/geometry.d.ts

@@ -86,6 +86,8 @@ export interface PathProfileBuilder {
   lineTo(to: Point2): PathProfileBuilder;
   /** A circular arc to `to` passing through `via`. */
   arcTo(to: Point2, via: Point2): PathProfileBuilder;
+  /** A circular arc to `to` of radius `r`; `via` is computed from the current point. */
+  arcTo(to: Point2, arc: { r: number; sweep?: "ccw" | "cw"; large?: boolean }): PathProfileBuilder;
   /** A cubic Bézier to `to` with control points `c1`/`c2`. */
   cubicTo(to: Point2, c1: Point2, c2: Point2): PathProfileBuilder;
   /** Close the contour and return it. Needs at least one segment. */

package/types/index.d.ts

@@ -199,6 +199,17 @@ export interface MountOptions {
    * part cannot support is dropped, never fatal.
    */
   viewerState?: ViewerState | null;
+  /**
+   * 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.
+   */
+  panelState?: PanelState | null;
+  /**
+   * The part's own source tree as text, for custom controls' `host.file(path)`.
+   * Omit and `host.file` answers null.
+   */
+  files?: Record<string, string>;
   /**
    * A provider backing every `type: "font"` control in the part. partforge
    * ships none — without one, a font control renders as a plain URL field.
@@ -256,6 +267,57 @@ export interface ViewerState {
   cutaway: CutawayState | null;
 }
 
+/** Custom controls' transient state, keyed by the param each control owns. Plain JSON. */
+export type PanelState = Record<string, Record<string, unknown>>;
+
+export interface PanelError {
+  /** The param the failing control owns. */
+  key: string;
+  label: string;
+  phase: "create" | "update" | "event" | "dispose" | "state";
+  message: string;
+}
+
+/** What a `type: "custom"` control's `widget(host)` receives. */
+export interface CustomControlHost {
+  /** The slot to draw into, inside the rail. */
+  el: HTMLElement;
+  doc: Document;
+  /** The param this control owns. */
+  key: string;
+  /** A structured clone of the current value of `key` (default: the owned key). */
+  get(key?: string): unknown;
+  /**
+   * Replace a value. Refused (throws TypeError) for a key the control does not
+   * own or a value outside the contract (owned key: a JSON value; `keys`: a
+   * scalar). Stores a clone, schedules a rebuild, and commits unless
+   * `commit: false` — then call `commit()` when the gesture ends.
+   */
+  set(value: unknown, opts?: { key?: string; commit?: boolean }): void;
+  commit(keys?: string[]): void;
+  /** The latest `derive()` output. */
+  derived: Record<string, unknown>;
+  /** Transient JSON state that survives a remount; never a param. */
+  state: Record<string, unknown>;
+  setState(patch: Record<string, unknown>): void;
+  /** Mount built-in controls bound at `path` inside the owned value. Returns a disposer. */
+  controls(container: HTMLElement, controls: import("./part.js").PanelEntry[], opts?: { path?: string }): () => void;
+  /** Element builder; SVG tags get the SVG namespace, `on*` attrs become listeners. */
+  h(tag: string, attrs?: Record<string, unknown>, ...children: unknown[]): Element;
+  /** Parse an SVG string to its root element, or null. */
+  svg(text: string): SVGSVGElement | null;
+  /** Render a partforge-vector document to an inline `<svg>`, or null. */
+  svgFromVector(doc: unknown): SVGSVGElement | null;
+  /** Text of one of the part's own files, by path or `pfc-tree://` token, or null. */
+  file(pathOrToken: string): string | null;
+  readonly disabled: boolean;
+}
+
+export interface CustomControlInstance {
+  update?(ctx: { reason: "sync" | "derived" | "restore"; disabled: boolean }): void;
+  dispose?(): void;
+}
+
 export interface ExportPartsOptions {
   /** Sub-part names, as `listExportableParts()` reports them. */
   parts: string[];
@@ -472,6 +534,10 @@ export interface PartRuntime {
    * view-cube click, Reframe, or an animation cue).
    */
   getViewerState(): ViewerState;
+  /** Every custom control's non-empty transient state, keyed by param. Hand back as `panelState`. */
+  getPanelState(): PanelState;
+  /** What custom controls reported failing this mount, in order. */
+  getPanelErrors(): PanelError[];
   /**
    * Subscribe to WebGL context loss — i.e. the GPU or the OS gave up — so a host
    * can say so rather than showing a dead canvas. The listener takes no

package/types/panel-values.d.ts

@@ -0,0 +1,18 @@
+// partforge/panel-values — the value contract of a `type: "custom"` control.
+
+export const CUSTOM_VALUE_MAX_BYTES: 16384;
+export const CUSTOM_VALUE_MAX_DEPTH: 8;
+
+export interface JsonValueLimits { maxBytes?: number; maxDepth?: number }
+
+/** A string, boolean, finite number, or an array / plain object of those. */
+export type JsonValue = string | number | boolean | JsonValue[] | { [key: string]: JsonValue };
+
+/** Why `v` is not a JSON value within the caps (a fragment such as `is null at tiles[2].h`), or null. */
+export function jsonValueProblem(v: unknown, limits?: JsonValueLimits): string | null;
+export function isJsonValue(v: unknown, limits?: JsonValueLimits): v is JsonValue;
+
+/** Parse an array/object literal's source text (bare or quoted keys, trailing commas, JS string escapes). Null on anything else. */
+export function readJsonLiteral(text: string): { value: JsonValue } | null;
+/** Source text for a value: compact under 80 chars, else indented JSON relative to `indent`. */
+export function writeJsonLiteral(value: JsonValue, opts?: { indent?: string }): string;

package/types/part.d.ts

@@ -58,7 +58,7 @@ export interface PartMeta {
 export type ControlKind = "slider" | "number" | "text" | "textarea";
 
 /** Every control type the panel can render. */
-export type ControlType = "slider" | "number" | "text" | "textarea" | "checkbox" | "select" | "radio";
+export type ControlType = "slider" | "number" | "text" | "textarea" | "checkbox" | "select" | "radio" | "font" | "image" | "vector" | "custom";
 
 /** A declarative visibility condition, evaluated against raw parameters. */
 export type WhenCondition =
@@ -94,6 +94,15 @@ export interface PanelControlEntry {
   snap?: boolean;
   /** slider: [lo, hi] band drawn on the track; outside it the value box takes a warning tint. */
   recommended?: [number, number];
+  /**
+   * custom: the widget function. Called once per mount with a host object
+   * (see `CustomControlHost` in index.d.ts); draws into `host.el`. The key
+   * this control owns may hold a JSON value (arrays and plain objects of
+   * primitives, ≤16 KB, depth ≤8).
+   */
+  widget?: (host: import("./index.js").CustomControlHost) => import("./index.js").CustomControlInstance | void;
+  /** custom: further scalar params the widget may write besides `key`. */
+  keys?: string[];
   hidden?: boolean;
   when?: WhenCondition;
   whenFalse?: "disable";