@weasel-js/labkit 1.2.0 → 1.3.0-pre.0

package/dist/_dts/{DrawCommand-C_XboUpz.d.ts → DrawCommand-DBB45NfN.d.ts}

@@ -208,6 +208,24 @@ interface RecordEntryOptions {
     selectionBefore?: readonly string[];
 }
 
+/**
+ * Path data model. Vector-graphics primitive used kit-wide as the canonical
+ * shape (replacing per-shape ad-hoc poses). SVG-style command stream so we
+ * cover lines, polygons, beziers, and multi-contour shapes (think the inner
+ * hole of an "O") under one type.
+ *
+ * Storage: command codes in a `Uint8Array`, parameters in a `Float32Array`.
+ * Each command consumes a fixed number of float coords from the parameter
+ * array; the parser walks both arrays in lockstep. This keeps interaction
+ * hot loops monomorphic and keeps GC pressure low under heavy edits.
+ *
+ * Two path subtypes are distinguished at the type level so common-case
+ * machinery (selection AABBs, area-select intersection, hit-testing rect
+ * silhouettes) can short-circuit on `RectPath` without paying the polygon
+ * kernel cost. Polymorphic kernels accept either via the `Path` union and
+ * dispatch on `kind`.
+ */
+
 /** Fill rule used by polygon path hit-testing and `ctx.fill()`. */
 type PathFillRule = 'nonzero' | 'evenodd';
 /**
@@ -312,6 +330,20 @@ interface NodeBase<TData, TLayer extends string, TPose> {
     pose: TPose;
     data: TData;
     parent: NodeId | null;
+    /** Nodes whose poses this node's geometry is computed from. Fixed at add
+     *  time. Absent or empty means the node's geometry is authored, which is the
+     *  normal case. */
+    dependsOn?: readonly NodeId[];
+    /** Computes this node's path from its dependencies' poses, in `dependsOn`
+     *  order. A dependency that has been removed arrives as `undefined`.
+     *  Returning `null` means "nothing to draw right now". Re-evaluated when a
+     *  dependency's world pose changes, never authored. Absolute-pose `Scene`
+     *  makes that the dependency's own pose, and an ancestor's move reaches it as
+     *  a `setPose` of its own from the container cascade.
+     *  `node` is deliberately widened: naming `TData`/`TLayer` here puts them in
+     *  a contravariant position, making `Scene` invariant in both and breaking
+     *  assignment kit-wide. The cost is that a `derivePath` casts to read `node.data`. */
+    derivePath?: (node: Node<unknown, string, TPose>, deps: readonly (TPose | undefined)[]) => Path | null;
 }
 /** A node with no children — a shape, a label, an image. */
 interface LeafNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
@@ -366,6 +398,11 @@ interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
     /** Only meaningful when `kind === 'container'`. Attach a clip-path function
      *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */
     clipFromPose?: (pose: TPose) => Path | null;
+    /** Mirrors `SceneNode.dependsOn`. */
+    dependsOn?: readonly NodeId[];
+    /** Mirrors `SceneNode.derivePath`. Taken as a live function; its registry key is
+     *  looked up from it, never passed in. */
+    derivePath?: (node: Node<unknown, string, TPose>, deps: readonly (TPose | undefined)[]) => Path | null;
 }
 /** A custom scene mutation registered with `Scene.registerOp`: how to apply
  *  it and how to undo it. The pair is what makes it participate in history. */
@@ -413,6 +450,57 @@ interface SerializedNode<TData, TLayer extends string, TPose> {
     /** Registry key for the container's clip-path factory.
      *  Containers only; omitted when the container has no clip. */
     clipFromPoseKey?: string;
+    /** Ids this node's geometry derives from. Omitted when it derives from nothing. */
+    dependsOn?: readonly string[];
+    /** Registry key for the node's `derivePath` function. Omitted when it has none. */
+    derivePathKey?: string;
+}
+/**
+ * One node's ephemeral presentation override — what a frame loop wants to say
+ * about a node without saying it about the document.
+ *
+ * Not document content: never recorded in history, never in `toJSON`, and
+ * writing one does not bump `Scene.getVersion()`. Hoist one entry per node and
+ * mutate it in place on a frame loop; `PoseOverrides.commit()` is what makes a
+ * mutation visible.
+ */
+interface PoseOverride<TPose> {
+    /** Replaces the node's document pose everywhere the render and hit-test
+     *  paths read one, including the clip a container derives from its pose.
+     *  Resolved by `effectivePose` — reading `node.pose` directly is how those
+     *  paths came to disagree about where a node is. */
+    pose?: TPose;
+    /** Multiplied into the node's painted alpha, on top of any `alphaFor`. */
+    alpha?: number;
+}
+/**
+ * The scene's ephemeral per-node overrides — see {@link PoseOverride}.
+ *
+ * The intended shape of a frame is: `set` each node once, mutate the entries
+ * in place per frame, `commit()` once. `commit` is not optional bookkeeping —
+ * the painter memo keys on pose *reference*, so a mutation without a commit
+ * paints the previous frame with no error.
+ *
+ * To promote a frame to document state (dropping a drag, baking an animation),
+ * write it once through `Scene.setPose` and `clear` the override.
+ */
+interface PoseOverrides<TPose> {
+    /** Store `entry` for `id` **by reference**; the caller keeps mutating it. */
+    set(id: NodeId, entry: PoseOverride<TPose>): void;
+    get(id: NodeId): PoseOverride<TPose> | undefined;
+    has(id: NodeId): boolean;
+    /** The overridden ids, as a snapshot array. */
+    ids(): readonly NodeId[];
+    clear(id: NodeId): void;
+    clearAll(): void;
+    /** Publish this frame's in-place mutations: invalidate the painter memo for
+     *  every overridden node, then notify subscribers. */
+    commit(): void;
+    /** Notified after every write. The canvas uses this to repaint without a
+     *  scene version bump. */
+    subscribe(fn: () => void): () => void;
+    /** Monotonic write counter. A snapshot for observers that poll. */
+    getGeneration(): number;
 }
 /**
  * The kit-owned scene tree: nodes, layers, and the undo history over both.
@@ -442,10 +530,19 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
      *  not a live view, and not yours to mutate. */
     renderOrderNodes(): readonly Node<TData, TLayer, TPose>[];
     add(spec: AddNodeSpec<TData, TLayer, TPose>): NodeId;
-    /** Delete `id` **and its entire subtree** — every descendant is removed in
-     *  the same operation. Recorded as one undoable step; `undo()` restores the
-     *  whole subtree (root + descendants, child order intact). */
+    /** Delete `id`, its **entire subtree**, and **everything that derives from**
+     *  any of those nodes — a node listing one of them in `dependsOn` goes too,
+     *  along with its own subtree, transitively. A dependent can live anywhere in
+     *  the tree, so this deletes nodes the caller never named and may unlink
+     *  several disjoint subtrees at once. Recorded as one undoable step; `undo()`
+     *  restores every one of them where it was, child order intact. */
     remove(id: NodeId): void;
+    /** {@link remove} over several roots at once, as a **single** undoable step.
+     *  Ids resolve against the tree as it stands at the call, so an id that
+     *  another one would cascade away is absorbed rather than removed twice —
+     *  which is what makes it safe to pass a whole selection. Throws if any id is
+     *  not in the scene; an empty list does nothing and records no step. */
+    removeMany(ids: readonly NodeId[]): void;
     update(id: NodeId, patch: {
         data: TData;
     }): void;
@@ -481,6 +578,9 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
     setLayerVisible(layer: TLayer, visible: boolean): void;
     setLayerLocked(layer: TLayer, locked: boolean): void;
     addLayer(spec: AddLayerSpec<TLayer>): void;
+    /** Drop a user layer and every node tagged to it, as one undoable step.
+     *  Removal cascades, so this also deletes nodes **on other layers** that
+     *  derive from a node on this one. */
     removeLayer(layer: TLayer): void;
     renameLayer(layer: TLayer, name: string): void;
     moveLayer(layer: TLayer, index: number): void;
@@ -522,6 +622,11 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
      *  undo step of its own. */
     getSelection(): readonly NodeId[];
     setSelection(ids: readonly NodeId[]): void;
+    /** Per-node pose / alpha overrides the render and hit-test paths read
+     *  through. Like {@link Scene.getSelection} this is not document content:
+     *  writes are never recorded, never serialized, and do not bump
+     *  {@link Scene.getVersion}. See {@link PoseOverrides}. */
+    readonly overrides: PoseOverrides<TPose>;
     undo(): boolean;
     redo(): boolean;
     canUndo(): boolean;
@@ -631,29 +736,11 @@ interface ViewportDims {
 }
 
 /**
- * 2D affine matrix utilities. Column-major 9-element Float32Array, matching
- * `WebGL2RenderingContext.uniformMatrix3fv` byte order so we can pass the
- * array directly without a transpose flag.
- *
- * Layout (column-major):
- *   [m00, m10, 0,
- *    m01, m11, 0,
- *    tx,  ty,  1]
- *
- * `apply(m, x, y)` returns `[m * (x, y, 1)] = [m00*x + m01*y + tx,
- *                                              m10*x + m11*y + ty]`.
- */
-type Mat3 = Float32Array;
-
-/**
- * registerTexture — accepts an image source, assigns an opaque id, stores in
- * a module-level registry. Actual GL upload happens lazily at draw time in
- * drawShader() via GLTextureCache.upload (which is idempotent).
+ * A registered texture, named by the registry that holds it.
  *
- * Lifecycle: textures live for the renderer's lifetime. No unregister in v1.
- *
- * Convention §9: this registry stores image data only — no per-renderer state.
- * Each WeaselRenderer's GLTextureCache does its own dedup via has(id).
+ * The handle is here rather than beside the registry because `FillStyle`'s
+ * pattern variant names it, and paint is a leaf: the registry lives in the
+ * renderer and imports this back.
  */
 interface TextureHandle {
     readonly id: string;
@@ -811,6 +898,26 @@ interface GradStop {
  * typically use a stencil mask of the stroked path against the geometry.
  */
 type StrokeAlign = 'center' | 'inner' | 'outer';
+/**
+ * The kit's built-in marker vocabulary, open on the string the way
+ * `PaintKind` is so a consumer's registered key typechecks.
+ */
+type KitMarkerKey = 'arrow' | 'arrow-open' | 'arrow-concave' | 'diamond' | 'diamond-hollow' | 'circle' | 'square' | 'bar';
+type MarkerKey = KitMarkerKey | (string & {});
+/**
+ * A marker on one end (or every interior vertex) of a stroke.
+ *
+ * `size` reuses `Stroke.width`'s unit system: a bare number scales with the
+ * resolved stroke width, `{ px }` pins screen pixels. That is SVG's
+ * `markerUnits` in the idiom this codebase already resolves at draw time.
+ * Omitted, the marker is one stroke width per unit.
+ */
+type MarkerRef = MarkerKey | {
+    key: MarkerKey;
+    size?: number | {
+        px: number;
+    };
+};
 /** Stroke style: a FillStyle plus structural line parameters. */
 interface Stroke {
     paint: FillStyle;
@@ -822,6 +929,14 @@ interface Stroke {
     };
     /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */
     dash?: number[];
+    /** Marker at the first vertex of each open subpath, rotated to point back
+     *  along the line (SVG's `auto-start-reverse`, as the only behavior). */
+    markerStart?: MarkerRef;
+    /** Marker at every interior authored vertex, on the bisector of the
+     *  incoming and outgoing directions. Never insets the stroke. */
+    markerMid?: MarkerRef;
+    /** Marker at the last vertex of each open subpath. */
+    markerEnd?: MarkerRef;
     cap?: 'butt' | 'round' | 'square';
     join?: 'miter' | 'round' | 'bevel';
     /**
@@ -864,17 +979,41 @@ interface Stroke {
     varyingWidthJoinThreshold?: number;
 }
 
+/**
+ * 2D affine matrix utilities. Column-major 9-element Float32Array, matching
+ * `WebGL2RenderingContext.uniformMatrix3fv` byte order so we can pass the
+ * array directly without a transpose flag.
+ *
+ * Layout (column-major):
+ *   [m00, m10, 0,
+ *    m01, m11, 0,
+ *    tx,  ty,  1]
+ *
+ * `apply(m, x, y)` returns `[m * (x, y, 1)] = [m00*x + m01*y + tx,
+ *                                              m10*x + m11*y + ty]`.
+ */
+type Mat3 = Float32Array;
+
 /**
  * Typography for `TextPose` and friends. Every field is optional; consumers
  * pass `{}` or override the few they care about. Defaults live in
  * `DEFAULT_TEXT_STYLE` and are applied at render/measure time, never written
  * back to the pose.
  *
- * `fill` follows the kit-wide `FillStyle` model — solid color or pattern. The
- * contenteditable edit overlay flattens non-solid fills to `'#000'` for CSS
- * since the browser can't paint with a texture handle.
+ * Paint is not typography and does not live here. A text node carries its
+ * fill and stroke in `data.fill` / `data.stroke`, the slots every other node
+ * kind uses; `resolveTextStyle` takes them as its second argument and
+ * `StyledRun.fill` / `.stroke` override them per range.
  */
 
+/**
+ * Horizontal alignment. `start` / `end` resolve against the reading direction;
+ * `left` / `right` are absolute. Same five values as CSS `text-align`, with
+ * the same split between the relative pair and the absolute pair.
+ */
+type TextAlign = 'left' | 'center' | 'right' | 'start' | 'end';
+/** Reading direction, which is what gives `start` / `end` their meaning. */
+type TextDirection = 'ltr' | 'rtl';
 /** User-facing text style. All fields optional; defaults applied at render time via `resolveTextStyle`. */
 interface TextStyle {
     /** Font size in world units. Default 16. */
@@ -885,15 +1024,15 @@ interface TextStyle {
     fontWeight?: number | string;
     /** Default `'normal'`. */
     fontStyle?: 'normal' | 'italic';
-    /** Default `'left'`. */
-    align?: 'left' | 'center' | 'right';
+    /** Default `'left'`. Pass `'start'` to align by reading order instead. */
+    align?: TextAlign;
+    /** Reading direction, resolving `align: 'start' | 'end'`. Default `'ltr'`. */
+    direction?: TextDirection;
     /** Multiplier applied to `fontSize`. Default 1.2. */
     lineHeight?: number;
-    /** Default `{ fill: 'solid', color: '#000' }`. */
-    fill?: FillStyle;
     /**
-     * Caret color used by the edit overlay. Defaults to the text color when
-     * `fill` is solid; falls back to `#000` for non-solid paints.
+     * Caret color used by the edit overlay. Defaults to the node's fill when
+     * that fill is solid; falls back to `#000` for non-solid paints.
      */
     caretColor?: string;
     /**
@@ -910,19 +1049,8 @@ interface TextStyle {
     underline?: boolean;
     /** Default `false`. */
     strikethrough?: boolean;
-    /**
-     * Outline painted over the glyph fill. Omitted (the default) means no
-     * outline — there is no such thing as a default text stroke.
-     *
-     * Only glyphs on the outline tier are stroked: above
-     * `textOutlineMinScreenSize` a glyph is a real `PolygonPath`, so it gets
-     * the ordinary tessellated ribbon with real joins, caps and miters, in any
-     * paint. Below it a glyph is a sampled distance field with no geometry to
-     * stroke, and it renders unstroked rather than approximated. `width` is in
-     * world units, like every other stroke in the kit — it does not scale with
-     * `fontSize`.
-     */
-    stroke?: Stroke;
+    /** Default `false`. */
+    overline?: boolean;
 }
 
 /**
@@ -937,10 +1065,15 @@ interface TextStyle {
  * override the node-level value (`letterSpacing: 0` on a run is an override,
  * not an absence — it zeroes inherited tracking).
  *
- * `underline` / `strikethrough` are *additive*, like `bold`/`italic`: a run
- * can turn a decoration on but never off, so they resolve as
- * `run.x || style.x` and not `run.x ?? style.x`. See the header of
+ * `underline` / `strikethrough` / `overline` are *additive*, like
+ * `bold`/`italic`: a run can turn a decoration on but never off, so they
+ * resolve as `run.x || style.x` and not `run.x ?? style.x`. See the header of
  * `runs/rangeStyle.ts` for why the model collapses the tri-state.
+ *
+ * `script` is folded the same way the toggles are, into the two primitives it
+ * is a preset over: `baselineShift` and `fontScale`. Both come out as one
+ * world-unit `baselineShift` and a final `fontSize`, so layout never learns
+ * that superscripts exist — it places a run against a baseline and an offset.
  */
 
 /** A run with every style resolved against the node's text style — no
@@ -961,6 +1094,17 @@ interface ResolvedRun {
     underline: boolean;
     /** Draw a rule through this run's x-height. Additive over the node style. */
     strikethrough: boolean;
+    /** Draw a rule above this run's ascent. Additive over the node style. */
+    overline: boolean;
+    /**
+     * How far this run sits off the line's shared baseline, in world units;
+     * positive raises. 0 for ordinary text.
+     *
+     * Already multiplied out against the inherited font size, and already
+     * carrying whatever `script` asked for — layout adds it to a baseline and
+     * asks nothing about where it came from.
+     */
+    baselineShift: number;
 }
 
 /**
@@ -979,7 +1123,7 @@ type TextVerticalAlign = 'top' | 'center' | 'bottom';
  * calls getProgramSource() and compiles the result. This keeps registerProgram
  * GL-context-agnostic — identical pattern to registerFont storing ImageBitmap.
  *
- * Convention §9: module-level state = source strings only; compiled GL
+ * Module-level state = source strings only; compiled GL
  * programs live on each renderer's programRegistry (Map<id, ShaderProgram>).
  *
  * Lifecycle: program sources live for the module lifetime. No unregister in v1.
@@ -1129,4 +1273,4 @@ interface ShaderDrawCommand {
     };
 }
 
-export type { Bounds as B, DrawCommand as D, History as H, Node as N, Op as O, PathDrawCommand as P, Scene as S, View as V, ViewportDims as a, NodeId as b, Path as c };
+export type { Bounds as B, DrawCommand as D, History as H, Node as N, Op as O, Path as P, Scene as S, View as V, ViewportDims as a, PathDrawCommand as b, NodeId as c };

package/dist/_dts/PrefsForm-BYa6cWnO.d.ts

@@ -0,0 +1,201 @@
+import { ReactNode } from 'react';
+
+/** The value types a built-in pref leaf can hold. */
+type ToolPrefKind = 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint' | 'object';
+interface ToolPrefBase<K extends string, Value> {
+    kind: K;
+    /** Human-readable label. */
+    name: string;
+    /** Longer help text — shown in tooltips / a settings pane. */
+    description: string;
+    /** Fallback when nothing is persisted. */
+    default: Value;
+    /** Hide from a host app's settings UI by default. */
+    hidden?: boolean;
+    /** Render full-width with no label row in schema-driven settings UIs
+     *  (weasel-ui `PrefsForm` honors this for leaves whose control brings
+     *  its own chrome). */
+    block?: boolean;
+    /** Glyph naming this leaf in a host UI's icon set (weasel-ui resolves it
+     *  against `ICON_PATHS`). A plain string because core ships no icon set and
+     *  cannot depend on one. Read where a leaf's `name` has nowhere to go — a
+     *  `pair`ed row is labeled by the pair, so its fields have only the glyph
+     *  to tell them apart. */
+    icon?: string;
+    /** Row-pairing hint for compact property UIs (weasel-ui
+     *  `SelectionPanel`): leaves sharing a `pair` id render side-by-side
+     *  on one row labeled with the `pair` string (e.g. `'Position'` for
+     *  `pose.x` / `pose.y`). Purely presentational. */
+    pair?: string;
+}
+/** How a schema-driven UI should present a number pref. */
+type ToolPrefNumberControl = 'input' | 'slider';
+/** How a schema-driven UI should present a boolean pref. */
+type ToolPrefBooleanControl = 'checkbox' | 'switch';
+/** How a schema-driven UI should present a string pref. */
+type ToolPrefStringControl = 'input' | 'textarea';
+/** How a schema-driven UI should present an enum pref. */
+type ToolPrefEnumControl = 'select' | 'radio' | 'toggle';
+/** Display-unit conversion for number leaves whose stored value uses a
+ *  canonical unit the user shouldn't see (e.g. radians stored, degrees
+ *  shown). The stored value stays canonical; UIs convert at the edge. */
+interface ToolPrefNumberUnit {
+    toDisplay: (stored: number) => number;
+    fromDisplay: (display: number) => number;
+    /** Shown after the input, e.g. `'°'`. */
+    suffix?: string;
+}
+/** A numeric pref, optionally bounded and stepped, and optionally stored in a
+ *  different unit from the one shown. */
+interface ToolPrefNumber extends ToolPrefBase<'number', number> {
+    min?: number;
+    max?: number;
+    step?: number;
+    control?: ToolPrefNumberControl;
+    unit?: ToolPrefNumberUnit;
+}
+/** An on/off pref. */
+interface ToolPrefBoolean extends ToolPrefBase<'boolean', boolean> {
+    control?: ToolPrefBooleanControl;
+}
+/** A free-text pref. */
+interface ToolPrefString extends ToolPrefBase<'string', string> {
+    control?: ToolPrefStringControl;
+}
+/**
+ * Stored-value bridge for an enum leaf whose value is not the option string —
+ * the counterpart of {@link ToolPrefNumberUnit}, which does the same for a
+ * number stored in a canonical unit.
+ *
+ * A dash array is the case that needs it: `Stroke.dash` stores lengths, and
+ * the thing a person chooses is a style. The presets scale by the stroke's
+ * width, so both directions are given the object's other fields — a style is
+ * meaningless without the width it is a multiple of.
+ */
+interface ToolPrefEnumEncoding<T extends string = string> {
+    /**
+     * The option `stored` reads as, or `undefined` for none — which a UI shows
+     * the way it shows a mixed selection, by selecting nothing.
+     *
+     * `siblings` is the object the leaf is a field of, or `undefined` when the
+     * node does not hold that object (and for a top-level leaf, which has none).
+     */
+    read: (stored: unknown, siblings: Record<string, unknown> | undefined) => T | undefined;
+    /** What to store for `option`. `undefined` removes the field. */
+    write: (option: T, siblings: Record<string, unknown> | undefined) => unknown;
+}
+/** A pref with a fixed set of labeled choices. */
+interface ToolPrefEnum<T extends string = string> extends ToolPrefBase<'enum', T> {
+    /** `short` is the label a segmented control uses when a full one would not
+     *  fit — a capital or two. `icon` names a glyph in the host UI's set
+     *  (weasel-ui resolves it against `ICON_PATHS`) and outranks `short` where
+     *  it resolves. It is a plain string because core ships no icon set and
+     *  cannot depend on one. The full `label` stays the accessible name, so
+     *  neither the abbreviation nor the glyph becomes the only thing naming
+     *  the option.
+     *
+     *  `disabled` marks an option a control reports but cannot author — the
+     *  value a stored form reads as when it matches nothing offered. Dropping it
+     *  from the list instead would leave the control selecting nothing and
+     *  claiming the field is unset. */
+    options: readonly {
+        value: T;
+        label: string;
+        short?: string;
+        icon?: string;
+        disabled?: boolean;
+    }[];
+    control?: ToolPrefEnumControl;
+    encoding?: ToolPrefEnumEncoding<T>;
+}
+/** A single color, stored as a hex string. For a value that may also be a
+ *  gradient or a pattern, use {@link ToolPrefPaint} instead. */
+interface ToolPrefColor extends ToolPrefBase<'color', string> {
+    /** Value is `#rrggbb`, or `#rrggbbaa` when `alpha` is set (UIs then
+     *  offer an opacity control). */
+    alpha?: boolean;
+}
+/**
+ * Open leaf: any node with a `kind` outside the built-ins. Schema-driven
+ * UIs (weasel-ui `PrefsForm` / `SelectionPanel`) dispatch it to an
+ * app-supplied renderer. Deliberately NOT index-signatured so concrete
+ * app interfaces stay assignable. Mirrors weasel-ui's `PrefCustom`.
+ */
+type ToolPrefCustom = ToolPrefBase<string, unknown>;
+/**
+ * A whole `FillStyle`, not a color inside one. Use it wherever the value is
+ * the tagged paint union — a solid color, a pattern, a gradient — rather
+ * than a hex string.
+ *
+ * Addressing `…fill.color` instead reads `undefined` off a gradient (so the
+ * control shows its default and claims the text is black) and writes a
+ * hybrid `{ fill: 'gradient', stops, color }` that the renderer's structural
+ * `'color' in paint` checks then paint flat solid. The union has to be
+ * edited as a union.
+ */
+interface ToolPrefPaint extends ToolPrefBase<'paint', unknown> {
+    /** Offer an opacity control alongside the color. */
+    alpha?: boolean;
+}
+/**
+ * A leaf whose value is one object, with its own fields hanging off it.
+ *
+ * A compound value — a stroke, a shadow, a pattern spec — could be described
+ * as several sibling leaves addressing into it (`data.stroke.width`,
+ * `data.stroke.cap`). It shouldn't be: each control would then write one field
+ * of a value it can only half see, and writing into something that is not an
+ * object yet corrupts it. Here the fields are `children` of one leaf, and
+ * every edit commits the parent object whole.
+ *
+ * `children` paths are relative to the object. They are ordinary leaves, so a
+ * field that is itself a union (a stroke's `paint`) declares the kind that
+ * edits that union. A child may also be a {@link ToolPrefGroup}, which
+ * organises the fields under a heading without contributing to the path —
+ * the same rule group keys follow at the top level. A `TextStyle` needs it:
+ * its character and paragraph fields belong to one value but read as two
+ * lists.
+ */
+interface ToolPrefObject extends ToolPrefBase<'object', unknown> {
+    children: Record<string, ToolPrefLeaf | ToolPrefGroup>;
+    /**
+     * Lift a non-object value into the object form, for a consumer field that
+     * may also be held as a scalar. Called before a child edit is applied;
+     * without it a scalar-valued leaf shows its children empty and refuses the
+     * edit.
+     */
+    fromScalar?: (value: unknown) => Record<string, unknown>;
+}
+/** One built-in pref leaf. `ToolPrefLeaf` widens this to include
+ *  app-defined kinds. */
+type ToolPref = ToolPrefNumber | ToolPrefBoolean | ToolPrefString | ToolPrefEnum | ToolPrefColor | ToolPrefPaint | ToolPrefObject;
+/** Built-in or app-defined leaf. */
+type ToolPrefLeaf = ToolPref | ToolPrefCustom;
+/** Nestable group: branch nodes a tool can use to organize its prefs. */
+interface ToolPrefGroup {
+    /** Heading for the group's rows. **Empty means no heading** — for a group
+     *  that exists to organise, not to name: one whose children are themselves
+     *  groups carrying the labels a reader needs. Give it a name whenever the
+     *  name is the referent (a `Border` group over `Top` / `Right` / `Bottom`
+     *  reads as nothing without it). */
+    name: string;
+    description?: string;
+    children: Record<string, ToolPrefLeaf | ToolPrefGroup>;
+}
+
+/** What a {@link PrefRenderer} is given for the leaf it is rendering. */
+interface PrefRenderContext {
+    /** Dotted path of the leaf within the schema root. */
+    path: string;
+    /** The schema node. App renderers narrow this to their own kind shape. */
+    pref: ToolPrefLeaf;
+    /** Current value — `values` at `path`, falling back to `pref.default`. */
+    value: unknown;
+    setValue: (value: unknown) => void;
+}
+/**
+ * Renders the control cell for one preference leaf. Returning `null`
+ * collapses the row.
+ */
+type PrefRenderer = (ctx: PrefRenderContext) => ReactNode;
+
+export type { PrefRenderer as P, ToolPrefLeaf as T, ToolPrefGroup as a, ToolPref as b, ToolPrefBoolean as c, ToolPrefBooleanControl as d, ToolPrefColor as e, ToolPrefCustom as f, ToolPrefEnum as g, ToolPrefEnumControl as h, ToolPrefEnumEncoding as i, ToolPrefKind as j, ToolPrefNumber as k, ToolPrefNumberControl as l, ToolPrefNumberUnit as m, ToolPrefObject as n, ToolPrefPaint as o, PrefRenderContext as p, ToolPrefString as q, ToolPrefStringControl as r };