@weasel-js/prefs 1.9.3 → 1.10.0

package/dist/open-BEY-aOGe.d.ts

@@ -0,0 +1,724 @@
+import { StorageAdapter, SyncStorageAdapter } from '@weasel-js/storage';
+import { UnitEntry, UnitSystem, Unit, Display, InfinityText } from '@weasel-js/quantity';
+
+/** What a condition can compare a leaf's value against. `null` stands for
+ *  nothing held: a missing value as well as a stored `null`. */
+type PrefConditionValue = string | number | boolean | null;
+/**
+ * One leaf's value, tested. `path` is the full path the value is read and
+ * written at (`'windows.paging'`), a field of an `object` or `union` leaf
+ * included (`'stroke.width'`, `'fill.type'`). With `from: 'item'` the path is
+ * read from the entry the test's node is drawn in instead: the entry of the
+ * nearest list or map the node is the `item` of, or sits inside the item of.
+ * `{ from: 'item', path: 'mode' }` on a field of a list's item reads `mode`
+ * of the same entry, and an empty path is the entry itself. The value compared is the one
+ * the leaf's control shows, where an `encoding` stores another. With
+ * several operators it holds while all of them do, so
+ * `{ path: 'count', atLeast: 1, below: 10 }` is a range.
+ *
+ * With no operator it holds while the value is set, which by kind is:
+ * a `boolean` that is on; a `number` other than 0; a `string`, a `color`, a
+ * `field`, or an `enum`'s option that is not the empty string; a `paint`
+ * that is not `null`; a `list` with an entry; a `map` with a key; an
+ * `object` or a `union` holding a field. Nothing held is never set, and the
+ * value of an app-defined kind is set by whichever of those its shape is,
+ * else while it is truthy.
+ */
+interface PrefTest {
+    path: string;
+    /** Where `path` is read from: the entry the node is drawn in. Unset: the schema root. */
+    from?: 'item';
+    is?: PrefConditionValue;
+    isNot?: PrefConditionValue;
+    /** Holds while the value is any of these. */
+    in?: readonly PrefConditionValue[];
+    /** The ordering operators hold only for a number. */
+    above?: number;
+    below?: number;
+    atLeast?: number;
+    atMost?: number;
+}
+/** A condition a schema node holds in `showIf` or `enableIf`. An empty `all`
+ *  holds and an empty `any` does not. */
+type PrefCondition = PrefTest | {
+    all: readonly PrefCondition[];
+} | {
+    any: readonly PrefCondition[];
+} | {
+    not: PrefCondition;
+};
+/** Reads the value a test compares: at `path` from the schema root, or with `from`, from the entry being drawn. */
+type PrefConditionReader = (path: string, from?: 'item') => unknown;
+/** Whether `value` is a well-formed condition, all the way down. */
+declare function isPrefCondition(value: unknown): value is PrefCondition;
+/** Whether `condition` holds, given the value `read` finds at each path it names. */
+declare function prefConditionHolds(condition: PrefCondition, read: PrefConditionReader): boolean;
+/** Whether a node is drawn: its `showIf` holds, or it has none. A node
+ *  answers for itself only; one inside a group that is not shown is not
+ *  drawn either. */
+declare function prefIsShown(node: {
+    showIf?: PrefCondition;
+}, read: PrefConditionReader): boolean;
+/** Whether a node's controls take input: its `enableIf` holds, or it has
+ *  none. As {@link prefIsShown}, a node answers for itself only. */
+declare function prefIsEnabled(node: {
+    enableIf?: PrefCondition;
+}, read: PrefConditionReader): boolean;
+/** Every path `condition` reads from the schema root, or with `from`, from the entry, once each, in the order met. */
+declare function prefConditionPaths(condition: PrefCondition, from?: 'item'): string[];
+/** Whether any test of `condition` reads from the entry, so that it has no answer until an entry is drawn. */
+declare function prefConditionReadsItem(condition: PrefCondition): boolean;
+/**
+ * `condition` with every path it reads put through `move`, for following a
+ * key that was renamed or a leaf that moved. `move` is told where a path is
+ * read from, and what it hands back is read from there too. A condition none
+ * of whose paths change comes back as the object it was given, and so does
+ * each part of one.
+ */
+declare function mapPrefConditionPaths(condition: PrefCondition, move: (path: string, from?: 'item') => string): PrefCondition;
+
+/** What a {@link PrefAction}'s `run` is told. */
+interface PrefActionContext {
+    /** The path the action sits at on the surface drawing it. */
+    path: string;
+}
+/** How a schema-driven UI should present an action leaf. */
+type PrefActionControl = 'button' | 'icon';
+/**
+ * A leaf that holds no value: a button among the rows or in a bar. A store
+ * neither reads nor writes one, and its path is not a {@link PrefPath}.
+ *
+ * It fires one of two things. `action` names an action the host registered,
+ * by key, which keeps the leaf plain data: it survives JSON, so a layout
+ * holding it can be saved and exported. `run` is code the schema carries.
+ * A leaf with both fires `action`. While a promise `run` returned is
+ * pending, the button is disabled.
+ */
+interface PrefAction extends PrefBase<'action', undefined> {
+    /** The key of a registered action to fire: its id, or `id:variant` for one
+     *  variant of a parametric action. The leaf's `name` and `icon` are what
+     *  the button shows, over the registered action's own. */
+    action?: string;
+    /** What to call when no `action` is named. */
+    run?: (ctx: PrefActionContext) => void | Promise<void>;
+    /** The button's text. Default: the leaf's `name`. */
+    label?: string;
+    /** `button` reads its label; `icon` is the icon alone, with the label in
+     *  its tooltip. Unset: a button in a row, an icon in a bar. */
+    control?: PrefActionControl;
+}
+
+/**
+ * A second place for another leaf: its row draws that leaf's control and
+ * reads and writes that leaf's value, so one setting can sit on two pages.
+ * It holds no value of its own. A store neither reads nor writes one, and
+ * its path is not a {@link PrefPath}.
+ *
+ * `name` and `description` left empty are the target's.
+ */
+interface PrefAlias extends PrefBase<'alias', undefined> {
+    /** The leaf shown here, by the full path its value is read and written at (`'view.grid'`). */
+    of: string;
+}
+/**
+ * The leaf an alias stands for and the path its value lives at, following an
+ * alias of an alias to its end. `undefined` when a path along the way names
+ * no leaf, or the aliases lead back to one already passed.
+ */
+declare function prefAliasTarget(alias: PrefAlias, leafAt: (path: string) => PrefLeaf | undefined): {
+    path: string;
+    leaf: PrefLeaf;
+} | undefined;
+/**
+ * What an alias is called wherever one is drawn or named: its own name, else
+ * that of `target`, the leaf it shows, else `Alias` for one that shows
+ * nothing.
+ */
+declare function prefAliasName(alias: PrefAlias, target?: PrefLeaf): string;
+/** A leaf drawn through an alias: the target, under the alias's own name and description where it gives them. */
+declare function prefAliasedLeaf(alias: PrefAlias, target: PrefLeaf): PrefLeaf;
+
+/**
+ * A line of text among the rows, holding no value: `name` is the line and
+ * `description` the note under it. A store neither reads nor writes one, and
+ * its path is not a {@link PrefPath}.
+ */
+type PrefLabel = PrefBase<'label', undefined>;
+/** A rule drawn between the rows, holding no value and drawing none of its own text. */
+type PrefSeparator = PrefBase<'separator', undefined>;
+
+/**
+ * A leaf whose value is an array, every entry described by `item`.
+ *
+ * `item` is an ordinary leaf, built-in or app-defined, so a list of objects,
+ * of lists or of a custom kind is declared the way a list of numbers is, and
+ * each entry is validated and drawn as that leaf would be on its own. Its
+ * `default` is what a new entry starts as, and its `name` names one entry
+ * (`'Phase'` under a list named `'Phases'`).
+ */
+interface PrefList extends PrefBase<'list', readonly unknown[]> {
+    item: PrefLeaf;
+    /** A stored list shorter than this reads as the default, and a UI stops removing at it. */
+    minItems?: number;
+    /** A stored list longer than this reads cut to it, and a UI stops adding at it. */
+    maxItems?: number;
+}
+
+/**
+ * A leaf whose value is an object keyed by strings nobody declared, every
+ * value described by `item`: the keyed counterpart of a {@link PrefList}.
+ * `item` is an ordinary leaf of any kind; its `default` is what a new entry
+ * starts as, and its `name` names one entry's value.
+ */
+interface PrefMap extends PrefBase<'map', Readonly<Record<string, unknown>>> {
+    item: PrefLeaf;
+}
+
+/**
+ * A leaf whose value is one of several object shapes, told apart by the
+ * string its `tag` field holds: `{ type: 'linear', angle: 90 }` or
+ * `{ type: 'radial', radius: 1 }` under `tag: 'type'`.
+ *
+ * Each variant is an `object` leaf keyed by its tag value. Its `children`
+ * are the fields beside the tag, its `name` is what a person chooses, and
+ * its `default` (without the tag) is what the value becomes when they choose
+ * it. A stored value whose tag names no variant reads as the leaf's default.
+ */
+interface PrefUnion extends PrefBase<'union', unknown> {
+    tag: string;
+    variants: Record<string, PrefObject>;
+}
+/** The variant `value` is, or `undefined` when its tag names none. */
+declare function prefVariantOf(leaf: PrefUnion, value: unknown): [key: string, variant: PrefObject] | undefined;
+/** The value a union takes on switching to the variant at `key`: that variant's default, tagged. */
+declare function prefVariantDefault(leaf: PrefUnion, key: string): Record<string, unknown>;
+
+/** What both forms of a unit say about the text around the number. */
+interface PrefUnitText {
+    /** Shown after the input, e.g. `'°'`. */
+    suffix?: string;
+    /** Suffixes a person may type, each mapped to the scale that turns a
+     *  number in that unit into a display number: `{ mm: 0.1, cm: 1 }` for a
+     *  field showing centimeters. A unit that disagrees with the display unit
+     *  about zero carries an `offset` as well. */
+    accepts?: Readonly<Record<string, UnitEntry>>;
+}
+/**
+ * A display unit as data, for a conversion that is linear: `stored = display * scale + offset`, the direction a
+ * `UnitEntry` runs toward its base, so `scale` is what one display unit is worth in stored units. Degrees shown
+ * over radians stored is `{ suffix: '°', scale: Math.PI / 180 }`, and `{ scale: 1 }` changes nothing. Being data,
+ * it is written to JSON, printed in a schema literal, and edited in `PrefSchemaEditor` like any other attribute.
+ */
+interface PrefLinearUnit extends PrefUnitText {
+    /** Stored units per display unit. Never 0. */
+    scale: number;
+    /** The stored value a display of 0 stands for. Absent is 0. */
+    offset?: number;
+    /** Decimal places the shown value is rounded to. Absent, the value shows unrounded and formats to two places.
+     *  What is typed is stored unrounded either way. */
+    precision?: number;
+}
+/** A display unit as code, for a conversion that is not linear. It cannot be written to JSON or edited as data. */
+interface PrefFunctionUnit extends PrefUnitText {
+    toDisplay: (stored: number) => number;
+    fromDisplay: (display: number) => number;
+    /** The stored value as display text, suffix included. */
+    format?: (stored: number) => string;
+}
+/** Display-unit conversion for number leaves whose stored value uses a
+ *  canonical unit the user shouldn't see (e.g. radians stored, degrees
+ *  shown). Read one through {@link resolvePrefUnit}, which answers for both forms. */
+type PrefNumberUnit = PrefLinearUnit | PrefFunctionUnit;
+/** A unit of either form as the functions that convert and format with it. */
+interface ResolvedPrefUnit extends PrefFunctionUnit {
+    format: (stored: number) => string;
+}
+/** Whether `unit` is the data form, and so can be written out and edited. */
+declare function isPrefLinearUnit(unit: PrefNumberUnit): unit is PrefLinearUnit;
+/** How to convert and format with `unit`, whichever form it was written in. */
+declare function resolvePrefUnit(unit: PrefNumberUnit): ResolvedPrefUnit;
+/**
+ * A display unit built from a {@link UnitSystem}: values are stored in the
+ * system's base and shown in `display`, rounded to `precision` places when
+ * given, and every unit in the system is accepted as typed text. `suffix`
+ * defaults to the unit's name and is accepted too. Every unit of a system is
+ * linear, so what comes back is data.
+ */
+declare function prefUnit(system: UnitSystem, display: Unit, opts?: {
+    precision?: number;
+    suffix?: string;
+}): PrefLinearUnit;
+
+/** The value types a built-in pref leaf can hold. */
+type PrefKind = 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint' | 'object' | 'list' | 'map' | 'union' | 'field' | 'action' | 'alias' | 'label' | 'separator';
+/** Leaves that share one row in a compact property UI, declared on the first
+ *  of them. Purely presentational. */
+interface PrefPair {
+    /** The other leaves on the row, by the full path their values are read and
+     *  written at (`'pose.y'`, `'camera.type'`), in order. Each must follow the
+     *  one before it among its siblings. */
+    with: string | readonly string[];
+    /** What the row reads. Default: the declaring leaf's `name`. */
+    label?: string;
+}
+/** The fields every leaf pref shares, keyed by its `kind` and typed by its stored value. */
+interface PrefBase<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;
+    /** Drawn only while this holds. Presentational: the value stays stored
+     *  and readable while the leaf is not drawn. */
+    showIf?: PrefCondition;
+    /** Drawn, and disabled while this does not hold. */
+    enableIf?: PrefCondition;
+    /** Nothing held where this leaf's value is read means `default`, because
+     *  whoever reads the value takes it that way (`pose.rotation ?? 0`). A
+     *  surface over sparse settings reads every leaf so already. One over a
+     *  scene node, where a missing key otherwise means the node has no such
+     *  property, shows the default only for a leaf that says this, and still
+     *  writes nothing until an edit. */
+    absentIsDefault?: 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 this package 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;
+    /** Puts this leaf and the ones it names on one row. */
+    pair?: PrefPair;
+    /** Shorter forms of `name`, longest first. A surface short of room for
+     *  `name` — a strip of controls on one line, a segment in a `pair`ed row —
+     *  shows the longest of them that fits. `name` stays the accessible name, so
+     *  these abbreviate without costing anything. */
+    short?: readonly string[];
+    /** Never auto. A surface that lets a leaf be left for its owner to decide
+     *  (weasel-ui `PrefsForm`'s `onAutoChange`, labkit's `ControlPanel`) gives
+     *  this one no way to. */
+    manual?: boolean;
+    /** Starts auto, where it would start pinned at `default`. */
+    unpinned?: boolean;
+    /** What the leaf reads while it is auto, where its owner computes nothing
+     *  for it. Unset, an auto leaf has no value. */
+    autoValue?: Value;
+    /** The name of the type this leaf was made from, set by `prefType`. A
+     *  schema editor shows such a leaf as one closed thing and prints the name
+     *  in place of its literal. */
+    type?: string;
+}
+/** How a schema-driven UI should present a number pref. */
+type PrefNumberControl = 'input' | 'slider';
+/** How a schema-driven UI should present a boolean pref. */
+type PrefBooleanControl = 'checkbox' | 'switch' | 'toggle';
+/** How a schema-driven UI should present a string pref. */
+type PrefStringControl = 'input' | 'textarea';
+/** How a schema-driven UI should present an enum pref. */
+type PrefEnumControl = 'select' | 'radio' | 'toggle' | 'menu';
+/** A numeric pref, optionally bounded and stepped, and optionally stored in a
+ *  different unit from the one shown. */
+interface PrefNumber extends PrefBase<'number', number> {
+    min?: number;
+    max?: number;
+    step?: number;
+    control?: PrefNumberControl;
+    /** How the value shows, speaks and reads back when typed — `compact()`
+     *  reads `2.00M`. Presentation only: the stored value stays a number. */
+    display?: Display;
+    unit?: PrefNumberUnit;
+    /** Which end of a slider gets a stop for ±Infinity, one step beyond the range. */
+    endless?: 'min' | 'max' | 'both';
+    /** The word infinity shows as — `'never'`, `'uncapped'`. Default `∞`. */
+    infinity?: InfinityText;
+}
+/**
+ * Stored-value bridge for a boolean leaf whose field is not a boolean — the
+ * flag counterpart of {@link PrefEnumEncoding}. `TextStyle.fontStyle` is
+ * the case: it stores `'italic'`, and the control is an Italic toggle.
+ */
+interface PrefBooleanEncoding {
+    /** Whether `stored` reads as on. */
+    read: (stored: unknown, siblings: Record<string, unknown> | undefined) => boolean;
+    /** What to store for `on`. `undefined` removes the field. */
+    write: (on: boolean, siblings: Record<string, unknown> | undefined) => unknown;
+}
+/** An on/off pref. */
+interface PrefBoolean extends PrefBase<'boolean', boolean> {
+    control?: PrefBooleanControl;
+    encoding?: PrefBooleanEncoding;
+}
+/** A free-text pref. */
+interface PrefString extends PrefBase<'string', string> {
+    control?: PrefStringControl;
+}
+/**
+ * Stored-value bridge for an enum leaf whose value is not the option string —
+ * the counterpart of {@link PrefNumberUnit}, 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.
+ */
+interface PrefEnumEncoding<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;
+}
+/** What every enum leaf carries; {@link PrefEnum} adds `clearable`. */
+interface PrefEnumBase<T extends string = string> extends PrefBase<'enum', T | undefined> {
+    /** `short` holds shorter forms of `label`, longest first, for a segmented
+     *  control too narrow for the full one — down to a capital or two. `icon`
+     *  names a glyph in the host UI's set (weasel-ui resolves it against
+     *  `ICON_PATHS`), drawn in place of any text form where it resolves. It is
+     *  a plain string because this package 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?: readonly string[];
+        icon?: string;
+        disabled?: boolean;
+    }[];
+    control?: PrefEnumControl;
+    encoding?: PrefEnumEncoding<T>;
+}
+/**
+ * A pref with a fixed set of labeled choices.
+ *
+ * `clearable` says the field may hold none of the options, and that absence
+ * is a state of its own rather than a missing value — a script that is
+ * neither super nor sub. A toggle control then lets the chosen segment be
+ * clicked off, which removes the field. Such a leaf's `default` is
+ * `undefined`: a missing value is the only stored form of cleared, so a
+ * default would bring an option back the moment the field was cleared.
+ */
+type PrefEnum<T extends string = string> = PrefEnumBase<T> & ({
+    clearable?: false;
+} | {
+    clearable: true;
+    default: undefined;
+});
+/** A single color, stored as a hex string. For a value that may also be a
+ *  gradient or a pattern, use {@link PrefPaint} instead. */
+interface PrefColor extends PrefBase<'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 dispatch it to an app-supplied renderer. Deliberately NOT
+ * index-signatured so concrete app interfaces stay assignable.
+ */
+type PrefCustom = PrefBase<string, unknown>;
+/**
+ * A whole `Paint`, 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 PrefPaint extends PrefBase<'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 as
+ * `children`; every edit commits the parent object whole. Sibling leaves
+ * addressing into the value (`data.stroke.width`, `data.stroke.cap`) would
+ * each write one field of a value they can only half see, and writing into
+ * something that is not an object yet corrupts it.
+ *
+ * `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 PrefSection}, which
+ * organizes the fields under a heading without contributing to the path.
+ */
+interface PrefObject extends PrefBase<'object', unknown> {
+    children: Record<string, PrefLeaf | PrefSection>;
+    /**
+     * 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 an edit
+     * starts from the leaf's `default`.
+     */
+    fromScalar?: (value: unknown) => Record<string, unknown>;
+}
+/**
+ * A reference to another field of the same schema, held as the full path its
+ * value is read and written at (`'camera.type'`) — the currency fields refer
+ * to each other in. A surface offers the fields it draws as the choices.
+ */
+interface PrefField extends PrefBase<'field', string> {
+    /** Only fields of these kinds may be named. Default: any leaf. */
+    kinds?: readonly string[];
+}
+/** One built-in pref leaf. `PrefLeaf` widens this to include
+ *  app-defined kinds. */
+type BuiltinPref = PrefNumber | PrefBoolean | PrefString | PrefEnum | PrefColor | PrefPaint | PrefObject | PrefList | PrefMap | PrefUnion | PrefField | PrefAction | PrefAlias | PrefLabel | PrefSeparator;
+/**
+ * The built-in kinds, as a table. A kind added to {@link PrefKind} is a
+ * compile error here, and from here it is one in every renderer's `never`
+ * guard.
+ */
+declare const PREF_KINDS: Record<PrefKind, true>;
+/** Which row each pairing among `leaves` puts a path on: a `key` the row's
+ *  members share (the declaring leaf's path) and the `label` it reads. A
+ *  path no `pair` names is absent. `leaves` are given by the path each
+ *  surface reads and writes them at, so references resolve in its terms. */
+declare function pairRowsOf(leaves: Iterable<readonly [path: string, leaf: PrefLeaf]>): Map<string, {
+    key: string;
+    label: string;
+}>;
+/**
+ * Narrows a leaf to the built-in union, so a renderer's switch discriminates
+ * on {@link PrefKind} instead of the open `string` that
+ * {@link PrefCustom} widens `kind` to. An app-defined kind answers false
+ * and belongs to the renderer's custom-renderer path.
+ */
+declare function isBuiltinPref(leaf: PrefLeaf): leaf is BuiltinPref;
+/** Built-in or app-defined leaf. */
+type PrefLeaf = BuiltinPref | PrefCustom;
+
+/**
+ * How a {@link PrefGroup} is drawn: `page` gets an entry in a form's rail and
+ * a pane of its own; `tab` shares a tab strip with the `tab` groups beside it;
+ * `panel` is a bordered, titled box; `section` is a heading over its rows;
+ * `fragment` draws nothing of its own, so its rows sit among its neighbors'
+ * as though they were written there. A fragment exists to hold things
+ * together: one key for their values to nest under, one node to move.
+ */
+type PrefGroupAs = 'page' | 'tab' | 'panel' | 'section' | 'fragment' | 'bar';
+/** How a {@link PrefSection} is drawn. */
+type PrefSectionAs = Exclude<PrefGroupAs, 'page'>;
+/**
+ * A group whose key is a path segment: `view` > `gridDensity` is the leaf at
+ * `view.gridDensity`, and its value nests the same way. The shape of a
+ * preferences schema — what `openPrefs` stores, `PrefsForm` renders, and a
+ * tool declares its options as. A key holds no `.`.
+ */
+interface PrefGroup {
+    /** Heading for the group's rows. **Empty means no heading** — for a group
+     *  that exists to organize, 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;
+    /** How the group is drawn. Unset, its depth decides: a top-level group is a
+     *  `page`, and one inside another is a `section`. */
+    as?: PrefGroupAs;
+    /** Drawn, with everything under it, only while this holds. */
+    showIf?: PrefCondition;
+    /** Everything under it is disabled while this does not hold. */
+    enableIf?: PrefCondition;
+    children: Record<string, PrefLeaf | PrefGroup>;
+}
+/**
+ * A heading over leaves that adds nothing to their paths: each member is
+ * addressed by its own key alone, and the section's key only identifies the
+ * section. The shape of a node's property schema, where a leaf's key is the
+ * whole dotted node path (`pose.x`, `data.fill`), and of the headings inside
+ * a {@link PrefObject}, where a key is relative to the object.
+ */
+interface PrefSection {
+    /** Heading for the section's rows. Empty means no heading, as for a
+     *  {@link PrefGroup}. */
+    name: string;
+    description?: string;
+    /** How the section is drawn, as a {@link PrefGroup}'s `as` — without
+     *  `page`, since nothing that draws sections has a rail. Unset: a heading
+     *  over its rows. */
+    as?: PrefSectionAs;
+    /** As a {@link PrefGroup}'s. */
+    showIf?: PrefCondition;
+    /** As a {@link PrefGroup}'s. */
+    enableIf?: PrefCondition;
+    members: Record<string, PrefLeaf | PrefSection>;
+}
+/** Whether a top-level group gets a page of its own, and not a place on the page of the root's own leaves. */
+declare function prefGroupIsPage(group: PrefGroup): boolean;
+
+type Join<A extends string, B extends string> = A extends '' ? B : `${A}.${B}`;
+/** Every value's dotted path in a `PrefGroup` schema, where a group's key is a
+ *  segment; an `object` leaf is one path, its fields are not, and an `action`,
+ *  `alias`, `label`, or `separator` leaf, holding no value, has none. A `PrefSection`
+ *  has no such paths: each of its leaves is addressed by its own key. */
+type PrefPath<G, Prefix extends string = ''> = G extends {
+    children: infer C;
+} ? string extends keyof C ? Join<Prefix, string> : {
+    [K in keyof C & string]: C[K] extends {
+        kind: string;
+    } ? C[K] extends {
+        kind: 'action' | 'alias' | 'label' | 'separator';
+    } ? never : Join<Prefix, K> : C[K] extends {
+        children: Record<string, unknown>;
+    } ? PrefPath<C[K], Join<Prefix, K>> : never;
+}[keyof C & string] : never;
+/** The leaf at `P`. */
+type PrefAtPath<G, P extends string> = G extends {
+    children: infer C;
+} ? P extends `${infer H}.${infer Rest}` ? H extends keyof C ? C[H] extends {
+    kind: string;
+} ? never : PrefAtPath<C[H], Rest> : never : P extends keyof C ? C[P] extends {
+    kind: string;
+} ? C[P] : never : never : never;
+type AllOf<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/** The fields an `object` leaf's `children` describe, sections folded in. Each is optional: an object may omit any. */
+type PrefFieldsOf<C> = {
+    [K in keyof C as C[K] extends {
+        kind: string;
+    } ? K : never]?: PrefValueOf<C[K]>;
+} & AllOf<{
+    [K in keyof C]: C[K] extends {
+        members: infer M;
+    } ? PrefFieldsOf<M> : never;
+}[keyof C]>;
+/** What a leaf holds: its kind's value type for a built-in kind, the type of
+ *  its `default` for an app-defined one. A list holds an array of what its
+ *  `item` holds, a map a record of it, and a union one variant's fields
+ *  under that variant's tag — where the schema keeps `tag` a literal
+ *  (`tag: 'type' as const`); one widened to `string` is typed by its default. */
+type PrefValueOf<L> = L extends {
+    kind: 'number';
+} ? number : L extends {
+    kind: 'boolean';
+} ? boolean : L extends {
+    kind: 'string' | 'color' | 'field';
+} ? string : L extends {
+    kind: 'paint';
+} ? unknown : L extends {
+    kind: 'enum';
+    options: readonly {
+        value: infer T;
+    }[];
+} ? L extends {
+    clearable: true;
+} ? T | undefined : T : L extends {
+    kind: 'list';
+    item: infer I;
+} ? PrefValueOf<I>[] : L extends {
+    kind: 'map';
+    item: infer I;
+} ? Record<string, PrefValueOf<I>> : L extends {
+    kind: 'union';
+    tag: infer T extends string;
+    variants: infer V;
+    default: infer D;
+} ? string extends keyof V | T ? D : {
+    [K in keyof V & string]: {
+        [P in T]: K;
+    } & (V[K] extends {
+        children: infer C;
+    } ? PrefFieldsOf<C> : unknown);
+}[keyof V & string] : L extends {
+    default: infer D;
+} ? D : unknown;
+/** What the leaf at `P` holds. */
+type PrefValueAt<G, P extends string> = PrefValueOf<PrefAtPath<G, P>>;
+
+/** Takes stored values from one version to the next: rename, transform or
+ *  delete entries in `records`, keyed by leaf path. It sees the values, not
+ *  the stamps they are stored under, and only those at its own version. */
+type PrefsMigration = (records: Map<string, unknown>) => void;
+
+/** Decides what a stored value reads as for one kind of leaf: the value to
+ *  read, or `undefined` for "invalid, read the default". */
+type PrefValidator = (stored: unknown, leaf: PrefLeaf) => unknown;
+/** What `stored` reads as for `leaf`. Never writes anything back: a schema
+ *  rolled back finds the original still in storage. */
+declare function repairPrefValue(leaf: PrefLeaf, stored: unknown, validators?: Readonly<Record<string, PrefValidator>>): unknown;
+
+/** One leaf changing, as a store subscriber hears it: the value readers now
+ *  see, and whether this store or another writer made the change. */
+interface PrefChange {
+    path: string;
+    value: unknown;
+    origin: 'local' | 'remote';
+}
+/** Values for one schema, held in memory and persisted behind. */
+interface PrefsStore<S extends PrefGroup> {
+    readonly schema: S;
+    /** The leaf's value, repaired against the schema; its default when unset. */
+    get<P extends PrefPath<S>>(path: P): PrefValueAt<S, P>;
+    set<P extends PrefPath<S>>(path: P, value: PrefValueAt<S, P>): void;
+    /** Unset every leaf at or under `path`; with no path, all. */
+    reset(path?: string): void;
+    /** Whether the leaf has a value of its own rather than following its default. */
+    isSet(path: PrefPath<S>): boolean;
+    /** Every leaf's value as a nested tree. The same object until something changes. */
+    values(): Record<string, unknown>;
+    /** The leaves following their default. The same set until something changes. */
+    unset(): ReadonlySet<string>;
+    /** Every stored record as a nested tree, unrepaired, including records no
+     *  leaf describes. The same object until something changes. */
+    stored(): Record<string, unknown>;
+    /** `changes` is empty when only records no leaf describes changed. */
+    subscribe(listener: (changes: PrefChange[]) => void): () => void;
+    /** False while the store cannot persist: storage has not been read yet, or
+     *  was written by a newer schema. Changes still apply for this session, and
+     *  ones made before a late read lands are persisted when it does. False for
+     *  good once the store is closed. */
+    readonly writable: boolean;
+    /** True once `close` was called. A write after that changes what this store
+     *  reads and reaches neither storage nor its subscribers, and the first one
+     *  warns. */
+    readonly closed: boolean;
+    /** Try again now to read storage that could not be read at open, ahead of
+     *  the store's own retries. Resolves whether storage has been read. */
+    read(): Promise<boolean>;
+    /** Resolves once storage has been read: at once for a store that opened
+     *  with its values, and when a later read lands for one that could not. */
+    whenRead(): Promise<void>;
+    /** Resolves true when every queued write reached storage. */
+    flush(): Promise<boolean>;
+    close(): Promise<void>;
+}
+
+/** Options for `openPrefs` and `openPrefsSync`. */
+interface PrefsOptions {
+    storage: StorageAdapter;
+    /** Prepended to every record's key: `'myapp.prefs.'`. */
+    prefix: string;
+    /** `migrations[i]` takes stored records from version `i` to `i + 1`. The
+     *  current version is `migrations.length`. */
+    migrations?: readonly PrefsMigration[];
+    /** Validators for app-defined kinds, keyed by `kind`. One given for a
+     *  built-in kind replaces that kind's own rule. */
+    validators?: Readonly<Record<string, PrefValidator>>;
+}
+/** Load every stored value for `schema`, migrate it, and return the store. */
+declare function openPrefs<S extends PrefGroup>(schema: S, options: PrefsOptions): Promise<PrefsStore<S>>;
+/** `openPrefs` for an adapter that reads synchronously: the store is ready
+ *  on return, so values can be read before anything renders. */
+declare function openPrefsSync<S extends PrefGroup>(schema: S, options: PrefsOptions & {
+    storage: SyncStorageAdapter;
+}): PrefsStore<S>;
+
+export { isPrefCondition as $, type PrefEnumEncoding as A, type BuiltinPref as B, type PrefField as C, type PrefFunctionUnit as D, type PrefGroupAs as E, type PrefLabel as F, type PrefLinearUnit as G, type PrefNumberControl as H, type PrefNumberUnit as I, type PrefPaint as J, type PrefPair as K, type PrefPath as L, type PrefSectionAs as M, type PrefSeparator as N, type PrefString as O, type PrefLeaf as P, type PrefStringControl as Q, type PrefTest as R, type PrefUnion as S, type PrefValidator as T, type PrefValueAt as U, type PrefValueOf as V, type PrefsMigration as W, type PrefsOptions as X, type PrefsStore as Y, type ResolvedPrefUnit as Z, isBuiltinPref as _, type PrefGroup as a, isPrefLinearUnit as a0, mapPrefConditionPaths as a1, openPrefs as a2, openPrefsSync as a3, pairRowsOf as a4, prefAliasName as a5, prefAliasTarget as a6, prefAliasedLeaf as a7, prefConditionHolds as a8, prefConditionPaths as a9, prefConditionReadsItem as aa, prefGroupIsPage as ab, prefIsEnabled as ac, prefIsShown as ad, prefUnit as ae, prefVariantDefault as af, prefVariantOf as ag, repairPrefValue as ah, resolvePrefUnit as ai, type PrefSection as b, type PrefNumber as c, type PrefList as d, type PrefMap as e, type PrefCondition as f, type PrefConditionReader as g, type PrefAlias as h, type PrefObject as i, type PrefKind as j, PREF_KINDS as k, type PrefAction as l, type PrefActionContext as m, type PrefActionControl as n, type PrefAtPath as o, type PrefBase as p, type PrefBoolean as q, type PrefBooleanControl as r, type PrefBooleanEncoding as s, type PrefChange as t, type PrefColor as u, type PrefConditionValue as v, type PrefCustom as w, type PrefEnum as x, type PrefEnumBase as y, type PrefEnumControl as z };