@weasel-js/core 1.9.3 → 1.10.0

package/dist/test-seams-CuIxe0xY.d.ts

@@ -1,356 +0,0 @@
-import { FillStyle, GradientUnits, GradStop, ColorSpace, MarkerKey, Stroke } from '@weasel-js/paint';
-import { ComponentType } from 'react';
-import { Reflection } from '@weasel-js/registry';
-import { c as ShaderProgram, G as GlMat3, P as ProgramSource } from './registerProgram-BMZRDgrh.js';
-import { Path } from '@weasel-js/geom';
-
-/**
- * Resolve a `units: 'bounds'` gradient into the frame its node is painted in.
- *
- * Node painters bake the pose into their geometry (`pathInPoseFrame`) rather
- * than emitting a per-node transform, so by the time the renderer sees a
- * scene node there is no node-local space left for a gradient to refer to.
- * This is the paint-side counterpart: it maps box-relative gradient geometry
- * onto the same box the path was just projected into, so the two arrive in
- * the renderer in one frame.
- */
-
-/** The box a `'bounds'` gradient's normalized geometry is mapped onto —
- *  usually a node's bounds. */
-interface FillPoseBox {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/**
- * Map a `'bounds'` gradient's `0..1` geometry onto `box`, returning it in the
- * box's own frame (`units: 'local'`). Any other fill — solid, pattern, or a
- * gradient in another space — is returned untouched.
- *
- * Radii scale by the box's normalized diagonal, SVG's rule for a percentage
- * radius against `objectBoundingBox`: `sqrt(w² + h²) / sqrt(2)`, which is
- * exactly `w` for a square box. The renderer's radial gradient is circular,
- * so a non-square box cannot make it the ellipse SVG would — this keeps the
- * radius proportionate instead.
- */
-declare function fillInPoseFrame(fill: FillStyle, box: FillPoseBox): FillStyle;
-/**
- * Inverse of {@link fillInPoseFrame}: express a gradient already positioned
- * in `box`'s frame as `0..1` fractions of that box (`units: 'bounds'`), so
- * it follows the node when moved or resized.
- *
- * The importer's counterpart — SVG `userSpaceOnUse` coordinates arrive in
- * page space, and normalizing them here makes an imported gradient behave
- * exactly like one drawn in the app.
- *
- * A zero-width or zero-height box has no frame to normalize against; the
- * fill is returned untouched rather than divided by zero.
- */
-declare function fillToBoundsFrame(fill: FillStyle, box: FillPoseBox): FillStyle;
-
-/**
- * The paint-kind registry — what makes `FillStyle` open.
- *
- * A consumer registers a sixth kind and it renders, converts between the
- * bounds and pose frames, and serializes, with no kit edits. The five built-in
- * kinds are registered here at module load so an editor's kind bar can
- * enumerate every kind through one list.
- *
- * Each kit layer consults this registry for a kind it does not recognize and
- * otherwise runs its own built-in branch. That split is not laziness: a built-in
- * kind's render slot lives in the GL renderer, its serialize slot lives in
- * `@weasel-js/svg`, and neither can be imported from here without inverting a
- * package dependency.
- */
-
-/** A compiled GL program. A paint kind gets one from
- *  {@link PaintBindContext.program} and hands it back from `bind`. */
-type PaintProgram = ShaderProgram;
-/**
- * `FillStyle`'s discriminant, open on the string the way `ChromeId` is: the
- * five kinds the kit ships, plus whatever a consumer registers.
- */
-type PaintKind = 'solid' | 'linear-gradient' | 'radial-gradient' | 'conic-gradient' | 'pattern' | (string & {});
-/** What a registered kind's editor renders. `PaintInput` in `@weasel-js/ui`
- *  is the control that mounts it. */
-interface PaintKindEditorProps {
-    value: FillStyle;
-    onInput?(next: FillStyle): void;
-    onChange(next: FillStyle): void;
-}
-/**
- * The lifetime a paint kind's GPU state belongs to: one renderer on one live
- * context. The object itself is the key — a kind caches textures in a
- * `WeakMap` on it, so two renderers sharing a context never trade them — and
- * `onRelease` is where it frees them.
- */
-interface PaintResources {
-    /** Run `release` once, when this lifetime ends: the renderer is disposed, or
-     *  its context was lost and restored. Free every GL object made under it
-     *  there. */
-    onRelease(release: () => void): void;
-}
-/**
- * The renderer surface a paint kind binds against, narrowed to what a paint
- * needs. The full `DrawContext` is not consumer surface.
- */
-interface PaintBindContext {
-    readonly gl: WebGL2RenderingContext;
-    /** The group alpha this draw inherits — multiply it into the paint's own. */
-    readonly alpha: number;
-    /**
-     * The compiled program for a `registerProgram` id, compiled against this
-     * renderer on first use. `null` when no source is registered under `id` or
-     * compilation failed.
-     */
-    program(id: string): PaintProgram | null;
-    /** Send `u_proj` and `u_model`, which every kit vertex shader takes. */
-    setProjAndModel(program: PaintProgram): void;
-    /**
-     * `u_worldInv` for a paint declaring `units` — the inverse of the transform
-     * from the paint's space to the frame the geometry arrives in. Paired with
-     * the vertex shader's `v_world` varying this is *the* paint-space
-     * convention; it is not gradient-specific.
-     *
-     * `null` when that space has no inverse — a transform or view that flattens
-     * an axis. Nothing the paint draws there means anything, so `bind` should
-     * return `null` and draw nothing.
-     */
-    spaceInverse(units: GradientUnits | undefined): GlMat3 | null;
-    /**
-     * The transform from the space `units` names to device pixels of the target
-     * this draw lands in — screen pixels times the pixel ratio on screen, output
-     * pixels in a headless render. It is what a paint baking a texture measures
-     * its resolution against. `null` where `spaceInverse` is.
-     */
-    spaceToDevice(units: GradientUnits | undefined): GlMat3 | null;
-    /** The largest texture side this context accepts, `MAX_TEXTURE_SIZE`. */
-    readonly maxTextureSize: number;
-    /** The lifetime GPU state made for this draw belongs to. Stable across the
-     *  frames of one renderer, so it is the key for a kind's texture cache. */
-    readonly resources: PaintResources;
-    /**
-     * Bake a stop ramp into the frame's ramp atlas, bind that atlas to a texture
-     * unit, and return the `v` the ramp's own row sits at — every ramp in a
-     * frame shares one texture, so a paint must sample at the returned `v` and
-     * not at a constant.
-     *
-     * `space` is the blend the stops are baked through, defaulting to `'rgb'`.
-     * It is part of the atlas key, so the same stops under two spaces take two
-     * rows rather than colliding.
-     */
-    bindRamp(stops: GradStop[], unit: number, space?: ColorSpace): number;
-}
-/**
- * One paint kind.
- *
- * `seed`, `label` and `colorOf` are the editor's slots and every kind has
- * them. The rest are optional because a kind may not need them — but
- * `inPoseFrame` and `toBoundsFrame` come as a pair or not at all: a kind that
- * converts one direction and not the other paints correctly once and then
- * drifts on the next resize.
- */
-interface PaintKindEntry {
-    id: string;
-    label: string;
-    /** Glyph naming this kind in an editor's kind bar, as an icon name the UI
-     *  layer resolves — the same indirection `ToolPrefBase.icon` uses. A kind
-     *  without one is named by its `label`. */
-    icon?: string;
-    /** A paint of this kind seeded from a color — what an editor writes when a
-     *  consumer switches a solid to this kind. */
-    seed(fromColor: string): FillStyle;
-    /** The single color this paint shows, or `undefined` when it has none. */
-    colorOf(paint: FillStyle): string | undefined;
-    /** Editor slot. */
-    Editor?: ComponentType<PaintKindEditorProps>;
-    /**
-     * The stop list this paint reads as. With `fromStops`, it is what makes a
-     * kind a gradient: `listGradientKinds` returns the kinds carrying both, and
-     * `switchGradientKind` converts between any two of them through the list.
-     */
-    stopsOf?(paint: FillStyle): GradStop[];
-    /** A paint of this kind built from a stop list, in `bounds` units. The
-     *  converse of `stopsOf`; supply both or neither. */
-    fromStops?(stops: GradStop[]): FillStyle;
-    /**
-     * Render slot: bind program, uniforms and textures for `fill` and return the
-     * bound program; `null` declines the paint.
-     *
-     * Binding is split from drawing on purpose — a caller owning its own stencil
-     * state (an inner/outer-aligned stroke, an even-odd fill) must issue its own
-     * draw call, and the kit's draw wrapper would clobber that state. Shader
-     * output must be premultiplied: `outColor = vec4(rgb * a, a)`.
-     *
-     * The geometry is not always the node's own. Text below the outline tier
-     * paints by drawing a quad over its glyphs' screen box into an offscreen
-     * buffer and masking that with glyph coverage, so a paint must come from
-     * `v_world` through `spaceInverse`, not from where `a_position` happens to
-     * lie.
-     */
-    bind?(ctx: PaintBindContext, fill: FillStyle): PaintProgram | null;
-    /** Bounds frame → the frame the node is painted in. */
-    inPoseFrame?(fill: FillStyle, box: FillPoseBox): FillStyle;
-    /** The inverse. Required whenever `inPoseFrame` is supplied. */
-    toBoundsFrame?(fill: FillStyle, box: FillPoseBox): FillStyle;
-    /**
-     * The `<defs>` entry backing a `url(#id)` reference.
-     *
-     * SVG has paint servers for two gradients and a pattern and nothing else, so
-     * a kind beyond those has no element to target: write a foreign-namespaced
-     * one under the `wzl:` prefix `@weasel-js/svg` declares on the root whenever
-     * a document holds such a paint. That package emits the fallback color
-     * beside the reference on its own, from `colorOf`.
-     */
-    toSvg?(id: string, fill: FillStyle): string;
-    /**
-     * Shader programs `bind` looks up through `ctx.program`, keyed by program
-     * id; registering the kind registers them. Declaring them here rather than
-     * calling `registerProgram` at import keeps a kind loaded by
-     * {@link registerPaintKindLoader} free of core's registries.
-     */
-    programs?: Readonly<Record<string, ProgramSource>>;
-}
-/** Every registered paint kind, with the overrides each displaced. */
-declare const paintKindRegistry: Reflection<PaintKindEntry>;
-/**
- * A consumer's own paint, typed as a `FillStyle`.
- *
- * `FillStyle` stays a closed union: opening its discriminant would widen every
- * built-in member and break the narrowing the kit's own branches depend on.
- * A registered kind declares its own interface instead and passes it through
- * here — the kit reads only `fill` and hands the whole object back to that
- * kind's slots.
- */
-declare function asPaint<T extends {
-    fill: string;
-}>(paint: T): FillStyle;
-/** Register a paint kind. Returns a disposer that removes it. Re-registering an
- *  existing id is an override; disposing it uncovers whatever it displaced. */
-declare function registerPaintKind(entry: PaintKindEntry): () => void;
-/** The entry for `kind`, or `undefined`. A lookup that misses on a kind with
- *  a loader starts that load; see {@link registerPaintKindLoader}. */
-declare function getPaintKind(kind: string | undefined): PaintKindEntry | undefined;
-/** Resolves with the entry for a kind that is loaded on first use. */
-type PaintKindLoader = () => Promise<PaintKindEntry>;
-/**
- * Declare a paint kind that is loaded the first time something looks it up,
- * so its code stays out of the bundle until a paint of it appears — typically
- * `() => import('./myKind').then((m) => m.myKindEntry)`.
- *
- * Until it lands the kind is unregistered: the renderer draws nothing for its
- * paints, and every other reader treats it as unknown. Registering it fires
- * `paintKindRegistry`'s subscribers, which is what `<SceneCanvas>` repaints
- * on. Call {@link warmPaintKinds} to load ahead of the first frame instead.
- *
- * A kind that is already registered never calls its loader. Returns a
- * disposer that removes the loader.
- */
-declare function registerPaintKindLoader(id: string, load: PaintKindLoader): () => void;
-/** Is `id` registered, or declared with a loader? */
-declare function isPaintKindKnown(id: string): boolean;
-/**
- * Load paint kinds ahead of their first use, so the first frame that meets
- * one draws it rather than a blank. With no list, loads every kind that has a
- * loader — the kit's lazily loaded built-ins (`mesh-gradient`) plus any a
- * consumer declared with {@link registerPaintKindLoader}.
- *
- * Resolves once every kind is registered; a kind already registered counts
- * as loaded. Rejects when a load fails, or for a kind that is neither
- * registered nor loadable.
- */
-declare function warmPaintKinds(kinds?: readonly string[]): Promise<void>;
-/** Every registered kind, built-ins first, in registration order. The same
- *  array until the registry changes. */
-declare function listPaintKinds(): readonly PaintKindEntry[];
-/** Every registered gradient kind — the ones that read as and build from a
- *  stop list — in registration order. The same array until the registry
- *  changes. */
-declare function listGradientKinds(): readonly PaintKindEntry[];
-/**
- * `paint` retargeted to gradient kind `kind`, or `undefined` when either side
- * is not a gradient kind.
- *
- * Between two of the stop gradients this is `withGradientKind`, which carries
- * the geometry. Any other pair goes through the stop list — `stopsOf` on the
- * way out, `fromStops` on the way in — keeping `interpolate` and `opacity`.
- * Lossy wherever the kinds hold different information; an editor that wants a
- * switch to be undoable should keep the original paint.
- */
-declare function switchGradientKind(paint: FillStyle, kind: PaintKind): FillStyle | undefined;
-/** The registry entry for a paint, or `undefined` when its kind is unknown. */
-declare function paintKindOf(fill: FillStyle): PaintKindEntry | undefined;
-/** @internal Test helper — do not call from product code. */
-declare function _resetPaintKindsForTests(): void;
-
-/**
- * The stroke-marker registry — arrowheads and other line terminators.
- *
- * Keyed by string, because a key is what sits in `stroke.markerEnd`. That is
- * the difference from `registerNodeShape`, which resolves by first-matching
- * predicate and whose `id` is only a label.
- *
- * A built-in's SVG slot lives in `@weasel-js/svg` and cannot be imported here
- * without inverting a package dependency, so an entry carries `toSvg` for that
- * package to consume — the same split `PaintKindEntry` uses.
- */
-
-/** What an entry's `path` is given. Entries that ignore it may return a
- *  constant path. */
-interface MarkerCtx {
-    /** One geometry unit, in the same world units the ribbon is tessellated in.
-     *  Defaults to the resolved stroke width. */
-    readonly size: number;
-    /** The stroke this marker belongs to, already width-resolved. */
-    readonly stroke: Stroke;
-}
-/** `'line'` means the stroke's own paint — SVG 2's `context-stroke`, as the
- *  default rather than an opt-in. */
-type MarkerPaint = FillStyle | 'line' | 'none';
-/** A stroke-marker registry entry: a terminator's geometry, paint and inset. */
-interface MarkerEntry {
-    /** `'kit:'`-free for built-ins so the key matches the SVG attribute value;
-     *  consumers should prefix (`'app-my-head'`). A key becomes the `id` of the
-     *  emitted `<marker>` def, so it must be a valid XML name — no colons. */
-    id: MarkerKey;
-    /** Geometry with its anchor at the origin, pointing +X, in units of
-     *  `ctx.size`. An arbitrary anchor is expressed by where the geometry is
-     *  drawn, which is why there is no `refX`/`refY`. */
-    path(ctx: MarkerCtx): Path;
-    /** Default `'line'`. */
-    fill?: MarkerPaint;
-    /** Outline width is in the same units as `path`. `false` (the default)
-     *  means no outline. */
-    outline?: {
-        width: number;
-        paint?: MarkerPaint;
-    } | false;
-    /** How far back along the line the stroke stops, in units of `ctx.size`.
-     *  Default 0. A property of the shape, not a setting on the stroke: an open
-     *  V needs 0 or its arms stop meeting the line. */
-    inset?: number;
-    /** `'auto'` (default) follows the line; a number is a fixed angle in
-     *  radians, ignoring the line — SVG's `orient="<angle>"`. */
-    orient?: 'auto' | number;
-    /** The stroke fields `path` reads besides `ctx.size` — `[]` for a shape
-     *  drawn from size alone. Declared, a head is reused across stroke objects
-     *  whose listed fields are equal; omitted, only across frames that pass the
-     *  same stroke object, since `path` might read any of it. */
-    reads?: readonly (keyof Stroke)[];
-    /** Emits the `<marker>` def. Consumed by `@weasel-js/svg`. */
-    toSvg?(id: string, entry: MarkerEntry): string;
-}
-/** Every registered marker, with the overrides each displaced. */
-declare const markerRegistry: Reflection<MarkerEntry>;
-/** Register a marker. Returns a disposer. Re-registering an existing id is an
- *  override; disposing it uncovers whatever it displaced rather than deleting the key. */
-declare function registerMarker(entry: MarkerEntry): () => void;
-/** The entry for `key`, or `undefined`. */
-declare function getMarker(key: string | undefined): MarkerEntry | undefined;
-/** Every registered marker, built-ins first, in registration order. */
-declare function listMarkers(): readonly MarkerEntry[];
-/** Test helper. Do not call from product code. */
-declare function _resetMarkersForTests(): void;
-
-export { type FillPoseBox as F, type MarkerEntry as M, type PaintKindEntry as P, _resetMarkersForTests as _, type MarkerCtx as a, type MarkerPaint as b, type PaintBindContext as c, type PaintKind as d, type PaintKindEditorProps as e, type PaintKindLoader as f, type PaintProgram as g, type PaintResources as h, asPaint as i, fillInPoseFrame as j, fillToBoundsFrame as k, getMarker as l, getPaintKind as m, isPaintKindKnown as n, listGradientKinds as o, listMarkers as p, listPaintKinds as q, markerRegistry as r, paintKindOf as s, paintKindRegistry as t, registerMarker as u, registerPaintKind as v, registerPaintKindLoader as w, switchGradientKind as x, warmPaintKinds as y, _resetPaintKindsForTests as z };

package/dist/tools/prefs.js

@@ -1,62 +0,0 @@
-import { formatUnit as e, unitScale as t } from "@weasel-js/quantity";
-//#region src/tools/prefs.ts
-function n(n, r, i) {
-	let a;
-	try {
-		a = t(n, r);
-	} catch (e) {
-		throw Error(`prefUnit: ${e instanceof Error ? e.message : String(e)}`);
-	}
-	let o = i?.precision === void 0 ? void 0 : 10 ** i.precision, s = i?.suffix ?? r, c = { [s]: 1 };
-	for (let e of Object.keys(n.units)) {
-		let r = t(n, e), i = r.factor / a.factor, o = (r.offset - a.offset) / a.factor;
-		c[e] = o === 0 ? i : {
-			factor: i,
-			offset: o
-		};
-	}
-	return {
-		toDisplay: (e) => {
-			let t = (e - a.offset) / a.factor;
-			return o === void 0 ? t : Math.round(t * o) / o;
-		},
-		fromDisplay: (e) => e * a.factor + a.offset,
-		suffix: s,
-		accepts: c,
-		format: (t) => `${e(t, r, n, {
-			precision: i?.precision ?? 2,
-			suffix: !1
-		})}${s}`
-	};
-}
-var r = {
-	number: !0,
-	boolean: !0,
-	string: !0,
-	enum: !0,
-	color: !0,
-	paint: !0,
-	object: !0,
-	field: !0
-};
-function i(e) {
-	let t = /* @__PURE__ */ new Map();
-	for (let [n, r] of e) {
-		if (!r.pair || t.has(n)) continue;
-		let e = {
-			key: n,
-			label: r.pair.label ?? r.name
-		};
-		t.set(n, e);
-		let i = typeof r.pair.with == "string" ? [r.pair.with] : r.pair.with;
-		for (let n of i) t.has(n) || t.set(n, e);
-	}
-	return t;
-}
-function a(e) {
-	return Object.hasOwn(r, e.kind);
-}
-//#endregion
-export { r as TOOL_PREF_KINDS, a as isBuiltinToolPref, i as pairRowsOf, n as prefUnit };
-
-//# sourceMappingURL=prefs.js.map

package/dist/tools/prefs.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"prefs.js","names":["prefUnit","self","unitScale","system","display","scale","opts","suffix","accepts","name","other","factor","offset","shown","stored","formatUnit","TOOL_PREF_KINDS","pairRowsOf","rows","path","leaf","leaves","row","partners","partner","isBuiltinToolPref"],"sources":["../../src/tools/prefs.ts"],"sourcesContent":["// src/tools/prefs.ts\n//\n// Minimal pref descriptor for tools that want to expose user-facing\n// settings (commit-on-close, snap thresholds, etc.). Host apps compose\n// these into their own preferences registry; the kit ships no storage\n// or UI of its own. The shape is intentionally narrow — number,\n// boolean, string, enum, plus rendering hints — so it's a clean\n// structural subset of whatever a host app already has.\n\nimport { formatUnit, unitScale } from '@weasel-js/quantity';\nimport type { Display, InfinityText, Unit, UnitEntry, UnitScale, UnitSystem } from '@weasel-js/quantity';\n\n/** The value types a built-in pref leaf can hold. */\nexport type ToolPrefKind =\n  | 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint' | 'object' | 'field';\n\n/**\n * Leaves that share one row in a compact property UI (weasel-ui\n * `SelectionPanel`, labkit's `ControlPanel`), declared on the first of them.\n * Purely presentational.\n */\nexport interface ToolPrefPair {\n  /** The other leaves on the row, by the full path their values are read and\n   *  written at (`'pose.y'`, `'camera.type'`), in order. Each must follow the\n   *  one before it among its siblings. */\n  with: string | readonly string[];\n  /** What the row reads. Default: the declaring leaf's `name`. */\n  label?: string;\n}\n\n/** The fields every leaf pref shares, keyed by its `kind` and typed by its stored value. */\nexport interface ToolPrefBase<K extends string, Value> {\n  kind: K;\n  /** Human-readable label. */\n  name: string;\n  /** Longer help text — shown in tooltips / a settings pane. */\n  description: string;\n  /** Fallback when nothing is persisted. */\n  default: Value;\n  /** Hide from a host app's settings UI by default. */\n  hidden?: boolean;\n  /** Render full-width with no label row in schema-driven settings UIs\n   *  (weasel-ui `PrefsForm` honors this for leaves whose control brings\n   *  its own chrome). */\n  block?: boolean;\n  /** Glyph naming this leaf in a host UI's icon set (weasel-ui resolves it\n   *  against `ICON_PATHS`). A plain string because core ships no icon set and\n   *  cannot depend on one. Read where a leaf's `name` has nowhere to go — a\n   *  `pair`ed row is labeled by the pair, so its fields have only the glyph\n   *  to tell them apart. */\n  icon?: string;\n  /** Puts this leaf and the ones it names on one row. */\n  pair?: ToolPrefPair;\n  /** Shorter forms of `name`, longest first. A surface short of room for\n   *  `name` — a strip of controls on one line, a segment in a `pair`ed row —\n   *  shows the longest of them that fits. `name` stays the accessible name, so\n   *  these abbreviate without costing anything. */\n  short?: readonly string[];\n}\n\n/** How a schema-driven UI should present a number pref. */\nexport type ToolPrefNumberControl = 'input' | 'slider';\n/** How a schema-driven UI should present a boolean pref. */\nexport type ToolPrefBooleanControl = 'checkbox' | 'switch' | 'toggle';\n/** How a schema-driven UI should present a string pref. */\nexport type ToolPrefStringControl = 'input' | 'textarea';\n/** How a schema-driven UI should present an enum pref. */\nexport type ToolPrefEnumControl = 'select' | 'radio' | 'toggle';\n\n/** Display-unit conversion for number leaves whose stored value uses a\n *  canonical unit the user shouldn't see (e.g. radians stored, degrees\n *  shown). The stored value stays canonical; UIs convert at the edge. */\nexport interface ToolPrefNumberUnit {\n  toDisplay: (stored: number) => number;\n  fromDisplay: (display: number) => number;\n  /** Shown after the input, e.g. `'°'`. */\n  suffix?: string;\n  /** Suffixes a person may type, each mapped to the scale that turns a\n   *  number in that unit into a display number: `{ mm: 0.1, cm: 1 }` for a\n   *  field showing centimeters. A unit that disagrees with the display unit\n   *  about zero carries an `offset` as well. */\n  accepts?: Readonly<Record<string, UnitEntry>>;\n  /** The stored value as display text, suffix included. */\n  format?: (stored: number) => string;\n}\n\n/**\n * A display unit built from a {@link UnitSystem}: values are stored in the\n * system's base and shown in `display`, rounded to `precision` places when\n * given, and every unit in the system is accepted as typed text. `suffix`\n * defaults to the unit's name and is accepted too.\n */\nexport function prefUnit(\n  system: UnitSystem,\n  display: Unit,\n  opts?: { precision?: number; suffix?: string },\n): ToolPrefNumberUnit {\n  let self: Required<UnitScale>;\n  try {\n    self = unitScale(system, display);\n  } catch (e) {\n    throw new Error(`prefUnit: ${e instanceof Error ? e.message : String(e)}`);\n  }\n  const scale = opts?.precision === undefined ? undefined : 10 ** opts.precision;\n  const suffix = opts?.suffix ?? display;\n  const accepts: Record<string, UnitEntry> = { [suffix]: 1 };\n  for (const name of Object.keys(system.units)) {\n    const other = unitScale(system, name);\n    // A number typed in `name` reaches display units through base:\n    // `(n * factor + offset - self.offset) / self.factor`.\n    const factor = other.factor / self.factor;\n    const offset = (other.offset - self.offset) / self.factor;\n    accepts[name] = offset === 0 ? factor : { factor, offset };\n  }\n  const toDisplay = (stored: number) => {\n    const shown = (stored - self.offset) / self.factor;\n    return scale === undefined ? shown : Math.round(shown * scale) / scale;\n  };\n  return {\n    toDisplay,\n    fromDisplay: (shown) => shown * self.factor + self.offset,\n    suffix,\n    accepts,\n    format: (stored) =>\n      `${formatUnit(stored, display, system, {\n        precision: opts?.precision ?? 2,\n        suffix: false,\n      })}${suffix}`,\n  };\n}\n\n/** A numeric pref, optionally bounded and stepped, and optionally stored in a\n *  different unit from the one shown. */\nexport interface ToolPrefNumber extends ToolPrefBase<'number', number> {\n  min?: number;\n  max?: number;\n  step?: number;\n  control?: ToolPrefNumberControl;\n  /** How the value shows, speaks and reads back when typed — `compact()`\n   *  reads `2.00M`. Presentation only: the stored value stays a number. */\n  display?: Display;\n  unit?: ToolPrefNumberUnit;\n  /** Which end of a slider stands for infinity: the value there is ±Infinity. */\n  endless?: 'min' | 'max' | 'both';\n  /** The word infinity shows as — `'never'`, `'uncapped'`. Default `∞`. */\n  infinity?: InfinityText;\n}\n/**\n * Stored-value bridge for a boolean leaf whose field is not a boolean — the\n * flag counterpart of {@link ToolPrefEnumEncoding}. `TextStyle.fontStyle` is\n * the case: it stores `'italic'`, and the control is an Italic toggle.\n */\nexport interface ToolPrefBooleanEncoding {\n  /** Whether `stored` reads as on. */\n  read: (stored: unknown, siblings: Record<string, unknown> | undefined) => boolean;\n  /** What to store for `on`. `undefined` removes the field. */\n  write: (on: boolean, siblings: Record<string, unknown> | undefined) => unknown;\n}\n\n/** An on/off pref. */\nexport interface ToolPrefBoolean extends ToolPrefBase<'boolean', boolean> {\n  control?: ToolPrefBooleanControl;\n  encoding?: ToolPrefBooleanEncoding;\n}\n/** A free-text pref. */\nexport interface ToolPrefString extends ToolPrefBase<'string', string> {\n  control?: ToolPrefStringControl;\n}\n/**\n * Stored-value bridge for an enum leaf whose value is not the option string —\n * the counterpart of {@link ToolPrefNumberUnit}, which does the same for a\n * number stored in a canonical unit.\n *\n * A dash array is the case that needs it: `Stroke.dash` stores lengths, and\n * the thing a person chooses is a style. The presets scale by the stroke's\n * width, so both directions are given the object's other fields — a style is\n * meaningless without the width it is a multiple of.\n */\nexport interface ToolPrefEnumEncoding<T extends string = string> {\n  /**\n   * The option `stored` reads as, or `undefined` for none — which a UI shows\n   * the way it shows a mixed selection, by selecting nothing.\n   *\n   * `siblings` is the object the leaf is a field of, or `undefined` when the\n   * node does not hold that object (and for a top-level leaf, which has none).\n   */\n  read: (stored: unknown, siblings: Record<string, unknown> | undefined) => T | undefined;\n  /** What to store for `option`. `undefined` removes the field. */\n  write: (option: T, siblings: Record<string, unknown> | undefined) => unknown;\n}\n\n/** A pref with a fixed set of labeled choices. `default` is `undefined` only\n *  for a {@link ToolPrefEnum.clearable} leaf, whose absence is a value. */\nexport interface ToolPrefEnum<T extends string = string>\n  extends ToolPrefBase<'enum', T | undefined> {\n  /**\n   * The field may hold none of the options, and that absence is a state of\n   * its own rather than a missing value — a script that is neither super nor\n   * sub. A toggle control then lets the chosen segment be clicked off, which\n   * removes the field.\n   */\n  clearable?: boolean;\n  /** `short` holds shorter forms of `label`, longest first, for a segmented\n   *  control too narrow for the full one — down to a capital or two. `icon`\n   *  names a glyph in the host UI's set (weasel-ui resolves it against\n   *  `ICON_PATHS`), drawn in place of any text form where it resolves. It is\n   *  a plain string because core ships no icon set and cannot depend on one.\n   *  The full `label` stays the accessible name, so\n   *  neither the abbreviation nor the glyph becomes the only thing naming\n   *  the option.\n   *\n   *  `disabled` marks an option a control reports but cannot author — the\n   *  value a stored form reads as when it matches nothing offered. Dropping it\n   *  from the list instead would leave the control selecting nothing and\n   *  claiming the field is unset. */\n  options: readonly {\n    value: T;\n    label: string;\n    short?: readonly string[];\n    icon?: string;\n    disabled?: boolean;\n  }[];\n  control?: ToolPrefEnumControl;\n  encoding?: ToolPrefEnumEncoding<T>;\n}\n\n/** A single color, stored as a hex string. For a value that may also be a\n *  gradient or a pattern, use {@link ToolPrefPaint} instead. */\nexport interface ToolPrefColor extends ToolPrefBase<'color', string> {\n  /** Value is `#rrggbb`, or `#rrggbbaa` when `alpha` is set (UIs then\n   *  offer an opacity control). */\n  alpha?: boolean;\n}\n\n/**\n * Open leaf: any node with a `kind` outside the built-ins. Schema-driven\n * UIs (weasel-ui `PrefsForm` / `SelectionPanel`) dispatch it to an\n * app-supplied renderer. Deliberately NOT index-signatured so concrete\n * app interfaces stay assignable. Mirrors weasel-ui's `PrefCustom`.\n */\nexport type ToolPrefCustom = ToolPrefBase<string, unknown>;\n\n/**\n * A whole `FillStyle`, not a color inside one. Use it wherever the value is\n * the tagged paint union — a solid color, a pattern, a gradient — rather\n * than a hex string.\n *\n * Addressing `…fill.color` instead reads `undefined` off a gradient (so the\n * control shows its default and claims the text is black) and writes a\n * hybrid `{ fill: 'gradient', stops, color }` that the renderer's structural\n * `'color' in paint` checks then paint flat solid. The union has to be\n * edited as a union.\n */\nexport interface ToolPrefPaint extends ToolPrefBase<'paint', unknown> {\n  /** Offer an opacity control alongside the color. */\n  alpha?: boolean;\n}\n\n/**\n * A leaf whose value is one object, with its own fields hanging off it.\n *\n * A compound value — a stroke, a shadow, a pattern spec — could be described\n * as several sibling leaves addressing into it (`data.stroke.width`,\n * `data.stroke.cap`). It shouldn't be: each control would then write one field\n * of a value it can only half see, and writing into something that is not an\n * object yet corrupts it. Here the fields are `children` of one leaf, and\n * every edit commits the parent object whole.\n *\n * `children` paths are relative to the object. They are ordinary leaves, so a\n * field that is itself a union (a stroke's `paint`) declares the kind that\n * edits that union. A child may also be a {@link ToolPrefGroup}, which\n * organises the fields under a heading without contributing to the path —\n * the same rule group keys follow at the top level. A `TextStyle` needs it:\n * its character and paragraph fields belong to one value but read as two\n * lists.\n */\nexport interface ToolPrefObject extends ToolPrefBase<'object', unknown> {\n  children: Record<string, ToolPrefLeaf | ToolPrefGroup>;\n  /**\n   * Lift a non-object value into the object form, for a consumer field that\n   * may also be held as a scalar. Called before a child edit is applied;\n   * without it a scalar-valued leaf shows its children empty and refuses the\n   * edit.\n   */\n  fromScalar?: (value: unknown) => Record<string, unknown>;\n}\n\n/**\n * A reference to another field of the same schema, held as the full path its\n * value is read and written at (`'camera.type'`) — the currency fields refer\n * to each other in. A surface offers the fields it draws as the choices.\n */\nexport interface ToolPrefField extends ToolPrefBase<'field', string> {\n  /** Only fields of these kinds may be named. Default: any leaf. */\n  kinds?: readonly string[];\n}\n\n/** One built-in pref leaf. `ToolPrefLeaf` widens this to include\n *  app-defined kinds. */\nexport type ToolPref =\n  | ToolPrefNumber\n  | ToolPrefBoolean\n  | ToolPrefString\n  | ToolPrefEnum\n  | ToolPrefColor\n  | ToolPrefPaint\n  | ToolPrefObject\n  | ToolPrefField;\n\n// Compile-time tie: every built-in leaf kind must appear in ToolPrefKind\n// and vice versa (ToolPrefBase's K is open for ToolPrefCustom's sake, so\n// the union no longer enforces it).\ntype _BuiltinKindsExact = [ToolPref['kind']] extends [ToolPrefKind]\n  ? [ToolPrefKind] extends [ToolPref['kind']] ? true : never\n  : never;\nconst _builtinKindsExact: _BuiltinKindsExact = true;\nvoid _builtinKindsExact;\n\n/**\n * The built-in kinds, as a table. A kind added to {@link ToolPrefKind} is a\n * compile error here, and from here it is one in every renderer's `never`\n * guard — the only thing standing between a new kind and rendering as\n * nothing in four places at once.\n */\nexport const TOOL_PREF_KINDS: Record<ToolPrefKind, true> = {\n  number: true,\n  boolean: true,\n  string: true,\n  enum: true,\n  color: true,\n  paint: true,\n  object: true,\n  field: true,\n};\n\n/** Which row each pairing among `leaves` puts a path on: a `key` the row's\n *  members share (the declaring leaf's path) and the `label` it reads. A\n *  path no `pair` names is absent. `leaves` are given by the path each\n *  surface reads and writes them at, so references resolve in its terms. */\nexport function pairRowsOf(\n  leaves: Iterable<readonly [path: string, leaf: ToolPrefLeaf]>,\n): Map<string, { key: string; label: string }> {\n  const rows = new Map<string, { key: string; label: string }>();\n  for (const [path, leaf] of leaves) {\n    if (!leaf.pair || rows.has(path)) continue;\n    const row = { key: path, label: leaf.pair.label ?? leaf.name };\n    rows.set(path, row);\n    const partners = typeof leaf.pair.with === 'string' ? [leaf.pair.with] : leaf.pair.with;\n    for (const partner of partners) if (!rows.has(partner)) rows.set(partner, row);\n  }\n  return rows;\n}\n\n/**\n * Narrows a leaf to the built-in union, so a renderer's switch discriminates\n * on {@link ToolPrefKind} instead of the open `string` that\n * {@link ToolPrefCustom} widens `kind` to. An app-defined kind answers false\n * and belongs to the renderer's custom-renderer path.\n */\nexport function isBuiltinToolPref(leaf: ToolPrefLeaf): leaf is ToolPref {\n  return Object.hasOwn(TOOL_PREF_KINDS, leaf.kind);\n}\n\n/** Built-in or app-defined leaf. */\nexport type ToolPrefLeaf = ToolPref | ToolPrefCustom;\n\n/** Nestable group: branch nodes a tool can use to organize its prefs. */\nexport interface ToolPrefGroup {\n  /** Heading for the group's rows. **Empty means no heading** — for a group\n   *  that exists to organise, not to name: one whose children are themselves\n   *  groups carrying the labels a reader needs. Give it a name whenever the\n   *  name is the referent (a `Border` group over `Top` / `Right` / `Bottom`\n   *  reads as nothing without it). */\n  name: string;\n  description?: string;\n  children: Record<string, ToolPrefLeaf | ToolPrefGroup>;\n}\n"],"mappings":";;AA4FA,SAAgBA,EACd,GACA,GACA,GACoB;CACpB,IAAIC;CACJ,IAAI;EACF,IAAOC,EAAUC,GAAQC,CAAO;CAClC,SAAS,GAAG;EACV,MAAU,MAAM,aAAa,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,GAAG;CAC3E;CACA,IAAMC,IAAQC,GAAM,cAAc,KAAA,IAAY,KAAA,IAAY,MAAMA,EAAK,WAC/DC,IAASD,GAAM,UAAUF,GACzBI,IAAqC,GAAGD,IAAS,EAAE;CACzD,KAAK,IAAME,KAAQ,OAAO,KAAKN,EAAO,KAAK,GAAG;EAC5C,IAAMO,IAAQR,EAAUC,GAAQM,CAAI,GAG9BE,IAASD,EAAM,SAAST,EAAK,QAC7BW,KAAUF,EAAM,SAAST,EAAK,UAAUA,EAAK;EACnD,EAAQQ,KAAQG,MAAW,IAAID,IAAS;GAAE;GAAQ;EAAO;CAC3D;CAKA,OAAO;EACL,YALiB,MAAmB;GACpC,IAAME,KAASC,IAASb,EAAK,UAAUA,EAAK;GAC5C,OAAOI,MAAU,KAAA,IAAYQ,IAAQ,KAAK,MAAMA,IAAQR,CAAK,IAAIA;EACnE;EAGE,cAAc,MAAUQ,IAAQZ,EAAK,SAASA,EAAK;EACnD;EACA;EACA,SAAS,MACP,GAAGc,EAAWD,GAAQV,GAASD,GAAQ;GACrC,WAAWG,GAAM,aAAa;GAC9B,QAAQ;EACV,CAAC,IAAIC;CACT;AACF;AAmMA,IAAaS,IAA8C;CACzD,QAAQ;CACR,SAAS;CACT,QAAQ;CACR,MAAM;CACN,OAAO;CACP,OAAO;CACP,QAAQ;CACR,OAAO;AACT;AAMA,SAAgBC,EACd,GAC6C;CAC7C,IAAMC,oBAAO,IAAI,IAA4C;CAC7D,KAAK,IAAM,CAACC,GAAMC,MAASC,GAAQ;EACjC,IAAI,CAACD,EAAK,QAAQF,EAAK,IAAIC,CAAI,GAAG;EAClC,IAAMG,IAAM;GAAE,KAAKH;GAAM,OAAOC,EAAK,KAAK,SAASA,EAAK;EAAK;EAC7D,EAAK,IAAID,GAAMG,CAAG;EAClB,IAAMC,IAAW,OAAOH,EAAK,KAAK,QAAS,WAAW,CAACA,EAAK,KAAK,IAAI,IAAIA,EAAK,KAAK;EACnF,KAAK,IAAMI,KAAWD,GAAU,AAAKL,EAAK,IAAIM,CAAO,KAAGN,EAAK,IAAIM,GAASF,CAAG;CAC/E;CACA,OAAOJ;AACT;AAQA,SAAgBO,EAAkB,GAAsC;CACtE,OAAO,OAAO,OAAOT,GAAiBI,EAAK,IAAI;AACjD"}