@weasel-js/prefs 1.9.4 → 1.10.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { P as PrefLeaf, a as PrefGroup, b as PrefSection, c as PrefNumber, d as PrefObject, e as PrefsStore, f as PrefKind } from './store-CNFnA_3c.js';
-export { B as BuiltinPref, g as PREF_KINDS, h as PrefAction, i as PrefActionContext, j as PrefActionControl, k as PrefAlias, l as PrefAtPath, m as PrefBase, n as PrefBoolean, o as PrefBooleanControl, p as PrefBooleanEncoding, q as PrefChange, r as PrefColor, s as PrefCustom, t as PrefEnum, u as PrefEnumBase, v as PrefEnumControl, w as PrefEnumEncoding, x as PrefField, y as PrefGroupAs, z as PrefLabel, A as PrefList, C as PrefMap, D as PrefNumberControl, E as PrefNumberUnit, F as PrefPaint, G as PrefPair, H as PrefPath, I as PrefSectionAs, J as PrefSeparator, K as PrefString, L as PrefStringControl, M as PrefUnion, N as PrefValueAt, O as PrefValueOf, Q as isBuiltinPref, R as pairRowsOf, S as prefAliasTarget, T as prefAliasedLeaf, U as prefGroupIsPage, V as prefUnit, W as prefVariantDefault, X as prefVariantOf } from './store-CNFnA_3c.js';
-import { StorageAdapter, SyncStorageAdapter } from '@weasel-js/storage';
+import { P as PrefLeaf, a as PrefGroup, b as PrefSection, c as PrefNumber, d as PrefList, e as PrefMap, f as PrefCondition, g as PrefConditionReader, h as PrefBoolean, i as PrefString, j as PrefColor, k as PrefEnumBase, l as PrefSelection, m as PrefLocus, n as PrefAlias, o as PrefObject, p as PrefKind } from './open-C83pU7Va.js';
+export { B as BuiltinPref, q as PREF_BLENDS, r as PREF_KINDS, s as PrefAction, t as PrefActionContext, u as PrefActionControl, v as PrefAtPath, w as PrefBarOverflow, x as PrefBase, y as PrefBlend, z as PrefBooleanControl, A as PrefBooleanEncoding, C as PrefChange, D as PrefConditionValue, E as PrefCustom, F as PrefEnum, G as PrefEnumControl, H as PrefEnumEncoding, I as PrefField, J as PrefFunctionUnit, K as PrefGroupAs, L as PrefLabel, M as PrefLinearUnit, N as PrefNumberControl, O as PrefNumberUnit, Q as PrefPaint, R as PrefPair, S as PrefPath, T as PrefSectionAs, U as PrefSeparator, V as PrefStringControl, W as PrefTest, X as PrefUnion, Y as PrefValidator, Z as PrefValueAt, _ as PrefValueOf, $ as PrefWeighted, a0 as PrefWeights, a1 as PrefsMigration, a2 as PrefsOptions, a3 as PrefsStore, a4 as ResolvedPrefUnit, a5 as isBuiltinPref, a6 as isPrefCondition, a7 as isPrefLinearUnit, a8 as isPrefLocus, a9 as mapPrefConditionPaths, aa as openPrefs, ab as openPrefsSync, ac as pairRowsOf, ad as prefAliasName, ae as prefAliasTarget, af as prefAliasedLeaf, ag as prefConditionHolds, ah as prefConditionPaths, ai as prefConditionReadsItem, aj as prefGroupIsPage, ak as prefIsEnabled, al as prefIsShown, am as prefLocusMember, an as prefLocusSelectors, ao as prefUnit, ap as prefVariantDefault, aq as prefVariantOf, ar as repairPrefValue, as as resolvePrefUnit } from './open-C83pU7Va.js';
+import '@weasel-js/storage';
 import '@weasel-js/quantity';
 
 /**
@@ -59,17 +59,356 @@ declare function prefLeaves(schema: PrefGroup): Map<string, PrefLeaf>;
 declare function flattenPrefValues(schema: PrefGroup, tree: unknown): [string, unknown][];
 /**
  * Drop every leaf that does not answer to `query`, pruning groups left empty.
- * A group whose own name matches keeps all of its leaves — a reader who typed
- * the group's name is asking for the group, not for leaves repeating it.
- *
- * An empty or whitespace query matches everything, so a cleared field restores
- * the tree rather than emptying it.
+ * A group whose own name matches keeps all of its leaves. An empty or
+ * whitespace query matches everything.
  *
  * An alias answers as the row it draws: its target's name and description
- * where it gives none. `leafAt` finds that target, and defaults to looking in
- * `node`; pass one over the whole schema when `node` is a part of it.
+ * where it gives none. That target is looked for in `over`, and in `node`
+ * without it; pass the whole schema when `node` is a part of it.
+ */
+declare function filterPrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, query: string, path?: string, over?: PrefGroup | PrefSection): T | null;
+
+/** One step of a walk over a group's children: a child on its own, or the neighboring `tab` children that share one strip. */
+type PrefTabRun<T> = {
+    item: T;
+    tabs?: undefined;
+} | {
+    tabs: readonly T[];
+    item?: undefined;
+};
+/**
+ * `items` in order, each run of neighbors `isTab` holds for folded into one step. What a surface leaves out of
+ * `items` neither joins a run nor ends one, and what it keeps and then declines to draw still holds its run together.
+ */
+declare function prefTabRuns<T>(items: readonly T[], isTab: (item: T) => boolean): PrefTabRun<T>[];
+
+/** One thing wrong with a condition: it is not one, it reads a path no leaf
+ *  holds a value at, it compares a leaf against a value it never holds, it
+ *  never holds whatever the leaf does, as an `in` of no values, it is the
+ *  `showIf` of a list's or a map's item, which is drawn with each entry, or
+ *  it reads from the entry on a node that no list or map draws. */
+interface PrefConditionProblem {
+    code: 'malformed' | 'no-leaf' | 'no-value' | 'value' | 'never' | 'item-show' | 'no-item';
+    /** The path read, where the problem is with one. */
+    path?: string;
+    problem: string;
+}
+/** A {@link PrefConditionProblem} and the node whose condition has it. */
+interface PrefSchemaConditionProblem extends PrefConditionProblem {
+    /**
+     * Where the node sits: a key per step from the root, `''` for the root
+     * itself. An object leaf's fields and sections, a union's variants, and a
+     * list's or a map's `item` are steps too, so this is not always a path a
+     * value is read at.
+     */
+    at: string;
+    field: 'showIf' | 'enableIf';
+}
+/** Where the node holding a condition sits, for what a condition alone does not say. */
+interface PrefConditionSite {
+    /** The nearest list or map the node is inside an entry of: the one it is the `item` of, or one above it. */
+    within?: PrefList | PrefMap;
+    /** The condition is the `showIf` of that list's or map's `item` itself. */
+    itemShowIf?: boolean;
+}
+/**
+ * What is wrong with `condition` as one of `schema`'s: every part of it that
+ * is not a condition, every path it reads that no leaf holds a value at,
+ * every comparison against a value the leaf's kind or options rule out, and
+ * every `in` of no values.
+ * `null` is never ruled out, and neither is anything under an app-defined
+ * kind or inside a list, a map, or a paint, which the schema does not
+ * describe. Takes `unknown`, since a schema read from JSON or built without
+ * types may hold anything where a condition goes. `site` says where the
+ * condition's node sits; without it the node is taken to be outside every
+ * list and map. A path read from the entry is held to the `item` of
+ * `site.within`, and is a problem where there is none. `over` is the schema
+ * `schema` is drawn over: a path no leaf of `schema` holds is held to it,
+ * and is a problem only where it holds none either.
+ */
+declare function checkPrefCondition(condition: unknown, schema: PrefGroup | PrefSection, site?: PrefConditionSite, over?: PrefGroup | PrefSection): PrefConditionProblem[];
+/** {@link checkPrefCondition} over every `showIf` and `enableIf` in `schema`, in schema order, each held to `over` as well. */
+declare function checkPrefConditions(schema: PrefGroup | PrefSection, over?: PrefGroup | PrefSection): PrefSchemaConditionProblem[];
+
+/** Which of a node's two conditions a {@link PrefConditionJudge} is asked about. */
+type PrefConditionField = 'showIf' | 'enableIf';
+/**
+ * Says whether one condition holds. {@link prefJudge} makes one from a value
+ * reader; a surface drawing several values at once writes its own, to say
+ * what a condition that holds for some and not for others comes to.
+ */
+type PrefConditionJudge = (condition: PrefCondition, field: PrefConditionField) => boolean;
+/** One entry of a list or a map: the `item` leaf describing it, and what it holds. */
+interface PrefEntry {
+    item: PrefLeaf;
+    value: unknown;
+}
+/**
+ * A judge over one set of values, read by path. A condition compares each
+ * value as the control over its leaf in `schema` shows it
+ * ({@link prefShownReader}), so `read` hands back what is stored. A test
+ * that reads from the entry (`from: 'item'`) reads `entry`, and finds nothing
+ * held where none is given. `over` is the schema `schema` is drawn over: a
+ * path no leaf of `schema` holds is compared as the leaf of `over` there
+ * shows it.
+ */
+declare function prefJudge(schema: PrefGroup | PrefSection, read: (path: string) => unknown, entry?: PrefEntry, over?: PrefGroup | PrefSection): PrefConditionJudge;
+/**
+ * Reads a value by path the way a form over `schema` shows it: what `values`
+ * holds there, else the default of the leaf at that path, or the part of a
+ * leaf's default the rest of the path names. `over` is the schema `schema`
+ * is drawn over: a path no leaf of `schema` holds takes its default there.
+ */
+declare function prefReader(schema: PrefGroup | PrefSection, values: unknown, over?: PrefGroup | PrefSection): (path: string) => unknown;
+
+/** Whether a node is drawn and whether it takes input, with what is above it counted. */
+interface PrefScope {
+    shown: boolean;
+    enabled: boolean;
+}
+/** The step that stands for any entry of a `list` or a `map` in a path: `'phases.*.hold'` answers for that field of
+ *  each, by every condition that comes to the same for every entry. */
+declare const PREF_ENTRY = "*";
+/** The scope a schema's root sits in. */
+declare const PREF_SCOPE: PrefScope;
+/** The scope of `node`, which sits directly under something whose scope is `above`. */
+declare function prefScopeUnder(above: PrefScope, node: {
+    showIf?: PrefCondition;
+    enableIf?: PrefCondition;
+}, holds: PrefConditionJudge): PrefScope;
+/** What {@link prefScopeAt} is told beyond the schema. */
+interface PrefScopeAtOptions {
+    /** The schema an alias's `of` names a leaf of. Default: the schema asked. */
+    aliasOver?: PrefGroup | PrefSection;
+    /** Says which conditions of `aliasOver` hold, where its values are not the ones `holds` reads. Default: `holds`. */
+    aliasHolds?: PrefConditionJudge;
+}
+/**
+ * The scope of the node at `path`: a group, a leaf, a field of an `object`
+ * or a `union` leaf, or an entry of a `list` or a `map`, whose step may be
+ * any key. Under a {@link PrefSection} schema a leaf's key is its whole
+ * path. A path that runs past the schema answers for the last node it
+ * reaches. An alias answers for itself and for the leaf it shows, as
+ * `applyPrefConditions` has it. Inside an entry, a condition that reads the
+ * entry (`from: 'item'`) is not asked and counts as holding, there being no
+ * entry here to read: `applyPrefEntryConditions` answers it.
+ */
+declare function prefScopeAt(schema: PrefGroup | PrefSection, path: string, holds: PrefConditionJudge, { aliasOver, aliasHolds }?: PrefScopeAtOptions): PrefScope;
+
+/** A schema with its conditions applied. */
+interface PrefConditionsApplied<T> {
+    /** The schema without the nodes that are not shown. The schema itself when
+     *  that is all of it, and `null` when its root is not shown. */
+    shown: T | null;
+    /**
+     * The value path of every leaf that is disabled, a field of an `object` or
+     * a `union` leaf included (`'stroke.width'`), and under a {@link PrefGroup}
+     * schema the path of every group that is. A `list`'s or a `map`'s item is
+     * named once for every entry, with {@link PREF_ENTRY} as the entry's step:
+     * `'phases.*'`, and `'phases.*.hold'` for a field of it.
+     */
+    disabled: ReadonlySet<string>;
+    /**
+     * With `keepHidden`, the path of everything `shown` holds that is not
+     * shown, named as `disabled` names what is disabled. Empty without it,
+     * since `shown` then holds none.
+     */
+    hidden: ReadonlySet<string>;
+}
+/** How {@link applyPrefConditions} treats what it would leave out. */
+interface PrefConditionsOptions {
+    /** Keep a group or a section that leaves with nothing to draw. */
+    keepEmpty?: boolean;
+    /**
+     * Keep every node whose `showIf` fails, and name it in `hidden`: for a
+     * surface that edits the schema, where a node not drawn cannot be picked.
+     */
+    keepHidden?: boolean;
+    /** The schema an alias's `of` names a leaf of. Default: the schema walked. */
+    aliasOver?: PrefGroup | PrefSection;
+    /** Says which conditions of `aliasOver` hold, where its values are not the ones `holds` reads. Default: `holds`. */
+    aliasHolds?: PrefConditionJudge;
+}
+/**
+ * `schema` as it is drawn while `holds` says which conditions hold. A node
+ * whose `showIf` fails is dropped with everything under it, unless
+ * `keepHidden`, and so is a group or a section that leaves with nothing to
+ * draw, unless `keepEmpty`. A node
+ * whose `enableIf` fails is disabled with everything under it. The item of
+ * a `list` or a `map` is walked as its entries are drawn: its fields hide and
+ * disable by their conditions, and its own `enableIf` disables every entry.
+ * A condition there that reads the entry (`from: 'item'`) has no one answer
+ * for every entry and is left holding: {@link applyPrefEntryConditions}
+ * answers it for each.
+ * An alias is shown only while it and the leaf it shows both are, and enabled
+ * only while both are, with everything above that leaf counted. That leaf is
+ * looked for in `aliasOver`, and its side is asked of `aliasHolds`.
+ * Parts with nothing dropped come back as the objects they were.
+ */
+declare function applyPrefConditions<T extends PrefGroup | PrefSection>(schema: T, holds: PrefConditionJudge, { keepEmpty, keepHidden, aliasOver, aliasHolds }?: PrefConditionsOptions): PrefConditionsApplied<T>;
+/** One entry of a list or a map with the conditions that read it applied. */
+interface PrefEntryApplied {
+    /** The item as this entry draws it: without the fields not shown, and the item itself when that is all of them. */
+    item: PrefLeaf;
+    /** The path of the entry, and of every field in it, that is disabled, named as {@link PrefConditionsApplied} names them. */
+    disabled: ReadonlySet<string>;
+    /** With `keepHidden`, the path of every field of the entry that is not shown. */
+    hidden: ReadonlySet<string>;
+}
+/**
+ * The conditions {@link applyPrefConditions} leaves unanswered, answered for
+ * one entry: `item`, as that pass left it, drawn for the entry at `path`
+ * (`'phases.2'`) while `holds` says which conditions hold. `holds` reads the
+ * entry: `prefJudge` given it. Only a condition that reads the entry is
+ * asked, the rest being applied already, and one inside a list or a map
+ * within the entry is left for that one's own entries.
  */
-declare function filterPrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, query: string, path?: string, leafAt?: (path: string) => PrefLeaf | undefined): T | null;
+declare function applyPrefEntryConditions(item: PrefLeaf, path: string, holds: PrefConditionJudge, { keepEmpty, keepHidden }?: Pick<PrefConditionsOptions, 'keepEmpty' | 'keepHidden'>): PrefEntryApplied;
+
+/** What the control over `leaf` shows for `stored`: what its `encoding` reads it as, else `stored` itself.
+ *  `siblings` is the object the leaf is a field of. */
+declare function prefShownValue(leaf: PrefLeaf, stored: unknown, siblings?: Record<string, unknown>): unknown;
+/**
+ * `read` with each value handed back as {@link prefShownValue} gives it, for
+ * the leaf of `schema` at that path, a field of an `object` or a `union` leaf
+ * included. A field's siblings are what `read` finds at its leaf's path. A
+ * path read from the entry is held to `item`, the leaf describing that entry.
+ * A path no leaf of `schema` holds is held to `over`, the schema it is drawn
+ * over.
+ */
+declare function prefShownReader(schema: PrefGroup | PrefSection, read: PrefConditionReader, item?: PrefLeaf, over?: PrefGroup | PrefSection): PrefConditionReader;
+
+/** One thing wrong with a leaf's `splitBy`. */
+interface PrefSplitProblem {
+    code: 'valueless' | 'no-leaf' | 'not-enum' | 'encoded' | 'clearable' | 'split' | 'twice' | 'default';
+    /** The path of the leaf whose `splitBy` it is. */
+    at: string;
+    /** The entry of `splitBy` the problem is with, where it is with one. */
+    path?: string;
+    problem: string;
+}
+/** Everything wrong with the `splitBy` lists of `schema`'s leaves, in schema order. */
+declare function checkPrefSplits(schema: PrefGroup): PrefSplitProblem[];
+
+/** What a builder takes after the leaf's name and default: any of the leaf's other fields. */
+type Rest<L> = Partial<Omit<L, 'kind' | 'name' | 'default'>>;
+/** One option of an enum, or its value alone, which is labeled with the value's first letter raised. */
+type OptionOf<T extends string> = T | PrefEnumBase<T>['options'][number];
+/**
+ * Builders for a preferences schema, each returning what the literal would
+ * hold. `pref.group('View', { grid: pref.boolean('Grid', true) })` is
+ * `{ name: 'View', children: { grid: { kind: 'boolean', name: 'Grid', description: '', default: true } } }`,
+ * and its paths and value types are read from it the same way.
+ */
+declare const pref: {
+    /** A group: `children` nest under its key, which is a segment of their paths. */
+    group<const C extends Record<string, PrefLeaf | PrefGroup>>(name: string, children: C, options?: Omit<PrefGroup, "name" | "children">): Omit<PrefGroup, "children"> & {
+        children: C;
+    };
+    /** A section: a heading over `members`, whose key adds nothing to their paths. */
+    section<const M extends Record<string, PrefLeaf | PrefSection>>(name: string, members: M, options?: Omit<PrefSection, "name" | "members">): Omit<PrefSection, "members"> & {
+        members: M;
+    };
+    number: (name: string, def: number, rest?: Rest<PrefNumber>) => PrefNumber;
+    boolean: (name: string, def: boolean, rest?: Rest<PrefBoolean>) => PrefBoolean;
+    string: (name: string, def: string, rest?: Rest<PrefString>) => PrefString;
+    color: (name: string, def: string, rest?: Rest<PrefColor>) => PrefColor;
+    /** A fixed set of choices. An option given as its value alone is labeled with that value, its first letter raised. */
+    enum<const T extends string>(name: string, def: NoInfer<T>, options: readonly OptionOf<T>[], rest?: Omit<Rest<PrefEnumBase<T>>, "options">): PrefEnumBase<T> & {
+        default: T;
+        clearable?: false;
+    };
+};
+
+/** How {@link prefsCss} names and writes things. */
+interface PrefsCssOptions {
+    /** The selector of the element the properties are set on, and the selectors' attributes read from. Default `:root`. */
+    root?: string;
+    /** The custom property a leaf is written as, or `null` to leave the leaf out. Default: `--`, then the path with
+     *  each `.` and each capital turned into a `-` (`look.gridGap` is `--look-grid-gap`). */
+    property?: (path: string, leaf: PrefLeaf) => string | null;
+    /** The attribute a selector's option is read from. Default: `data-`, then the path as a property spells it. */
+    attribute?: (selector: string) => string;
+    /** The CSS text of a value, `null` to leave it out, or `undefined` for what its kind writes by itself. */
+    value?: (value: unknown, leaf: PrefLeaf, path: string) => string | null | undefined;
+}
+/** What {@link prefsCss} reads of a store: any `PrefsStore` is one. */
+interface PrefsCssSource {
+    schema: PrefGroup;
+    values(read?: {
+        at?: PrefSelection;
+    }): Record<string, unknown>;
+    locus(path: string): PrefLocus | undefined;
+    get(path: string): unknown;
+}
+/**
+ * The store's values as CSS custom properties.
+ *
+ * The first block sets every leaf on `root`, a split one at the member the
+ * selectors' defaults name, so a page that sets no attribute still has a
+ * value for each. A block follows for each choice of options some value tells
+ * apart, matched by an attribute per selector on that same element; a selector
+ * is written under each of its own options too. Every block is inside
+ * `:where()`, so none outranks another by how many attributes it names, and a
+ * rule of the page's own wins. Blocks naming more selectors come later.
+ *
+ * A number is written in its display unit where the unit's suffix is a CSS
+ * unit, and bare otherwise; a boolean as `1` or `0`; a color as it is held; an
+ * enum's option as an identifier; a string quoted. A leaf of any other kind is
+ * left out unless `value` writes it.
+ */
+declare function prefsCss(store: PrefsCssSource, options?: PrefsCssOptions): string;
+/**
+ * The attribute for each selector and the option it is set to: what to set
+ * on the `root` element for the blocks of {@link prefsCss} to match the
+ * store's own choice.
+ */
+declare function prefsCssAttributes(store: Pick<PrefsCssSource, 'schema' | 'get'>, options?: Pick<PrefsCssOptions, 'attribute'>): Record<string, string>;
+
+/**
+ * The schema that answers for the value at `path`: `schema` where a leaf of
+ * it describes that value, else `over`, the schema `schema` is drawn over.
+ * So a path both hold is `schema`'s. Every reader of a condition's paths
+ * that takes a second schema asks here which one to read.
+ */
+declare function prefSchemaHolding(schema: PrefGroup | PrefSection, path: string, over?: PrefGroup | PrefSection): PrefGroup | PrefSection;
+
+/** What an alias row reads of the leaf it shows: the schema that leaf is in, as that schema's own conditions leave it. */
+interface PrefAliasTargets {
+    /** Says which conditions of that schema hold. */
+    holds: PrefConditionJudge;
+    /** The leaf at a path of that schema, without the fields the surface would leave out of the leaf's own row: one
+     *  marked `hidden`, and one a `showIf` hides, unless the surface draws those. */
+    leafAt: (path: string) => PrefLeaf | undefined;
+    /** The leaf `alias` is drawn as, under the alias's own name and description where it gives them, and the path
+     *  its value is read and written at. `undefined` for an alias of nothing. */
+    shown: (alias: PrefAlias) => {
+        path: string;
+        leaf: PrefLeaf;
+    } | undefined;
+    /** Whether the field at a path of that schema is one an `enableIf` disables. */
+    disabledAt: (path: string) => boolean;
+    /** Whether the field at a path of that schema is one a `showIf` hides, on a surface that draws those. */
+    hiddenAt?: (path: string) => boolean;
+    /** An entry of a list or a map of that schema, as the conditions that read the entry leave it. */
+    entryAt: (item: PrefLeaf, path: string, value: unknown) => PrefEntryApplied;
+}
+/** What a surface draws beyond the default, which its alias rows follow. */
+interface PrefAliasTargetsOptions {
+    /** The surface draws fields marked `hidden`. */
+    showHidden?: boolean;
+    /** The surface draws what a `showIf` hides, marked. */
+    markHidden?: boolean;
+}
+/**
+ * {@link PrefAliasTargets} over `over`, the schema a surface's aliases point
+ * into: the surface's own, or another's. `judge` answers `over`'s conditions
+ * as the surface reads values, for one entry of a list or a map where it is
+ * given one: `prefJudge` over `over`. A surface's own pass drops a leaf it
+ * leaves out and keeps no path of another schema, so the leaves aliases show
+ * are conditioned here, the first time one is asked for.
+ */
+declare function prefAliasTargets(over: PrefGroup | PrefSection, judge: (entry?: PrefEntry) => PrefConditionJudge, { showHidden, markHidden }?: PrefAliasTargetsOptions): PrefAliasTargets;
 
 /**
  * The object a write to one field of an `object` leaf starts from: `held` itself where it is one. Where it is
@@ -93,37 +432,31 @@ declare function prefType<L extends PrefLeaf>(name: string, leaf: L): L & {
     type: string;
 };
 
-/** 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;
-
-/** 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>;
+/** Whether a leaf's control fits beside a heading's words: a built-in `boolean`'s or `enum`'s does. */
+declare function prefFitsHeading(leaf: PrefLeaf): boolean;
+/**
+ * The key of the leaf a group or a section draws in its heading: the first
+ * directly in it that is marked `heading` and whose control fits there.
+ * Undefined for a node with no name, which has no heading to draw it in.
+ */
+declare function prefHeadingKey(node: PrefGroup | PrefSection): string | undefined;
+
+/** Neighboring items one row draws, in {@link pairRuns}' answer. */
+interface PairRun<T> {
+    items: T[];
+    /** The pairing the items share: the path of the leaf that declared it, and what the row reads. Absent on a
+     *  run of one, which is no pair. */
+    pair?: {
+        key: string;
+        label: string;
+    };
+}
+/**
+ * `items` as the rows they draw, in order: each leaf a `pair` names joins the row of the leaf naming it where
+ * the two are neighbors, and every other item is a run of its own. `leafOf` gives an item's leaf and the path a
+ * `pair` would name it by, or nothing for an item that shares no row, which ends a run.
+ */
+declare function pairRuns<T>(items: readonly T[], leafOf: (item: T) => readonly [path: string, leaf: PrefLeaf] | undefined): PairRun<T>[];
 
 /** What a surface has to know about a kind before it can lay its control out. */
 interface PrefKindTraits {
@@ -150,4 +483,4 @@ declare function prefDrawsSeveral(leaf: {
     kind: string;
 }): boolean;
 
-export { PREF_KIND_TRAITS, PrefGroup, PrefKind, type PrefKindTraits, PrefLeaf, PrefNumber, PrefObject, PrefSection, type PrefValidator, type PrefsMigration, type PrefsOptions, PrefsStore, VERSION_RECORD, filterPrefSubtree, flattenPrefValues, isPrefLeaf, isPrefSection, openPrefs, openPrefsSync, prefDisplayBounds, prefDrawsSeveral, prefHoldsValue, prefIsCompound, prefLeafAt, prefLeaves, prefObjectBase, prefObjectWithField, prefSectionLeaves, prefType, prefValueAtPath, repairPrefValue, visiblePrefSubtree };
+export { PREF_ENTRY, PREF_KIND_TRAITS, PREF_SCOPE, type PairRun, PrefAlias, type PrefAliasTargets, type PrefAliasTargetsOptions, PrefBoolean, PrefColor, PrefCondition, type PrefConditionField, type PrefConditionJudge, type PrefConditionProblem, PrefConditionReader, type PrefConditionSite, type PrefConditionsApplied, type PrefConditionsOptions, type PrefEntry, type PrefEntryApplied, PrefEnumBase, PrefGroup, PrefKind, type PrefKindTraits, PrefLeaf, PrefList, PrefLocus, PrefMap, PrefNumber, PrefObject, type PrefSchemaConditionProblem, type PrefScope, type PrefScopeAtOptions, PrefSection, PrefSelection, type PrefSplitProblem, PrefString, type PrefTabRun, type PrefsCssOptions, type PrefsCssSource, VERSION_RECORD, applyPrefConditions, applyPrefEntryConditions, checkPrefCondition, checkPrefConditions, checkPrefSplits, filterPrefSubtree, flattenPrefValues, isPrefLeaf, isPrefSection, pairRuns, pref, prefAliasTargets, prefDisplayBounds, prefDrawsSeveral, prefFitsHeading, prefHeadingKey, prefHoldsValue, prefIsCompound, prefJudge, prefLeafAt, prefLeaves, prefObjectBase, prefObjectWithField, prefReader, prefSchemaHolding, prefScopeAt, prefScopeUnder, prefSectionLeaves, prefShownReader, prefShownValue, prefTabRuns, prefType, prefValueAtPath, prefsCss, prefsCssAttributes, visiblePrefSubtree };