@weasel-js/prefs 0.0.0-stage → 1.9.4

package/dist/store-CNFnA_3c.d.ts

@@ -0,0 +1,572 @@
+import { Display, UnitEntry, InfinityText, UnitSystem, Unit } from '@weasel-js/quantity';
+
+/** 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;
+/** 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>;
+
+/** 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 (weasel-ui
+ * `SelectionPanel`, labkit's `ControlPanel`), 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;
+    /** 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';
+/** Display-unit conversion for number leaves whose stored value uses a
+ *  canonical unit the user shouldn't see (e.g. radians stored, degrees
+ *  shown). The stored value stays canonical; UIs convert at the edge. */
+interface PrefNumberUnit {
+    toDisplay: (stored: number) => number;
+    fromDisplay: (display: number) => number;
+    /** 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>>;
+    /** The stored value as display text, suffix included. */
+    format?: (stored: number) => string;
+}
+/**
+ * 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.
+ */
+declare function prefUnit(system: UnitSystem, display: Unit, opts?: {
+    precision?: number;
+    suffix?: string;
+}): PrefNumberUnit;
+/** 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 — a style is
+ * meaningless without the width it is a multiple of.
+ */
+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 (weasel-ui `PrefsForm` / `SelectionPanel`) dispatch it to an
+ * app-supplied renderer. Deliberately NOT index-signatured so concrete
+ * app interfaces stay assignable. Mirrors weasel-ui's `PrefCustom`.
+ */
+type PrefCustom = PrefBase<string, unknown>;
+/**
+ * A whole `FillStyle`, not a color inside one. Use it wherever the value is
+ * the tagged paint union — a solid color, a pattern, a gradient — rather
+ * than a hex string.
+ *
+ * Addressing `…fill.color` instead reads `undefined` off a gradient (so the
+ * control shows its default and claims the text is black) and writes a
+ * hybrid `{ fill: 'gradient', stops, color }` that the renderer's structural
+ * `'color' in paint` checks then paint flat solid. The union has to be
+ * edited as a union.
+ */
+interface 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.
+ *
+ * A compound value — a stroke, a shadow, a pattern spec — could be described
+ * as several sibling leaves addressing into it (`data.stroke.width`,
+ * `data.stroke.cap`). It shouldn't be: each control would then write one field
+ * of a value it can only half see, and writing into something that is not an
+ * object yet corrupts it. Here the fields are `children` of one leaf, and
+ * every edit commits the parent object whole.
+ *
+ * `children` paths are relative to the object. They are ordinary leaves, so a
+ * field that is itself a union (a stroke's `paint`) declares the kind that
+ * edits that union. A child may also be a {@link PrefSection}, which
+ * organizes the fields under a heading without contributing to the path. A
+ * `TextStyle` needs it: its character and paragraph fields belong to one
+ * value but read as two lists.
+ */
+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 — the only thing standing between a new kind and rendering as
+ * nothing in four places at once.
+ */
+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;
+    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;
+    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>>;
+
+/** 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. */
+    readonly writable: 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>;
+}
+
+export { type PrefList as A, type BuiltinPref as B, type PrefMap as C, type PrefNumberControl as D, type PrefNumberUnit as E, type PrefPaint as F, type PrefPair as G, type PrefPath as H, type PrefSectionAs as I, type PrefSeparator as J, type PrefString as K, type PrefStringControl as L, type PrefUnion as M, type PrefValueAt as N, type PrefValueOf as O, type PrefLeaf as P, isBuiltinPref as Q, pairRowsOf as R, prefAliasTarget as S, prefAliasedLeaf as T, prefGroupIsPage as U, prefUnit as V, prefVariantDefault as W, prefVariantOf as X, type PrefGroup as a, type PrefSection as b, type PrefNumber as c, type PrefObject as d, type PrefsStore as e, type PrefKind as f, PREF_KINDS as g, type PrefAction as h, type PrefActionContext as i, type PrefActionControl as j, type PrefAlias as k, type PrefAtPath as l, type PrefBase as m, type PrefBoolean as n, type PrefBooleanControl as o, type PrefBooleanEncoding as p, type PrefChange as q, type PrefColor as r, type PrefCustom as s, type PrefEnum as t, type PrefEnumBase as u, type PrefEnumControl as v, type PrefEnumEncoding as w, type PrefField as x, type PrefGroupAs as y, type PrefLabel as z };

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@weasel-js/prefs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.9.4",
+  "description": "A preferences schema, a store that loads, validates, migrates and persists values against it, and React hooks over the store.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/prefs"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "dependencies": {
+    "@weasel-js/quantity": "1.9.4",
+    "@weasel-js/registry": "1.9.4",
+    "@weasel-js/storage": "1.9.4"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}