@weasel-js/prefs 1.9.3 → 1.10.0

package/dist/react.d.ts

@@ -1,4 +1,5 @@
-import { a as PrefGroup, w as PrefPath, c as PrefsStore, z as PrefValueAt } from './store-BU2tRX5H.js';
+import { a as PrefGroup, L as PrefPath, Y as PrefsStore, U as PrefValueAt, X as PrefsOptions } from './open-BEY-aOGe.js';
+import { SyncStorageAdapter } from '@weasel-js/storage';
 import '@weasel-js/quantity';
 
 /** One leaf of `store`, as React state. */
@@ -17,4 +18,27 @@ declare function usePrefsValues<S extends PrefGroup>(store: PrefsStore<S>): {
     reset: (path?: string) => void;
 };
 
-export { usePref, usePrefsValues };
+type SyncOptions = PrefsOptions & {
+    storage: SyncStorageAdapter;
+};
+/**
+ * A store for `schema`, open while the component is mounted: opened during
+ * the first render, so that render has values, and closed, with its queued
+ * writes sent, when the component unmounts.
+ *
+ * Components naming the same `storage`, `prefix`, and `schema` share one
+ * store, which closes when the last of them unmounts. Components naming the
+ * same `storage` and `prefix` with different schemas each get a store of
+ * their own over the same records, so a write through one is read by the
+ * others at once, and each hears it as a `local` change. They must pass the
+ * same `migrations`: the records are migrated once, when the first opens.
+ *
+ * `storage` and `schema` are compared by identity and `prefix` by value, so
+ * keep the first two out of the render body. A change to any of the three
+ * closes the store and returns the one for the new three. The `options`
+ * object itself may be new every render: `migrations` and `validators` are
+ * read when a store opens, and a change to either alone opens nothing.
+ */
+declare function usePrefsStore<S extends PrefGroup>(schema: S, options: SyncOptions): PrefsStore<S>;
+
+export { usePref, usePrefsStore, usePrefsValues };

package/dist/react.js

@@ -1,6 +1,6 @@
+import { openPrefsCacheSync, createPrefsStore } from './chunk-5KB3WBJZ.js';
 import { useCallback, useSyncExternalStore } from 'react';
 
-// src/hooks.ts
 function usePref(store, path) {
   const subscribe = useCallback((onChange) => store.subscribe(onChange), [store]);
   const getSnapshot = () => store.get(path);
@@ -28,7 +28,71 @@ function usePrefsValues(store) {
   const reset = useCallback((path) => store.reset(path), [store]);
   return { values, set, unset, stored, reset };
 }
+var shared = /* @__PURE__ */ new WeakMap();
+function sharedAt(storage, prefix) {
+  let byPrefix = shared.get(storage);
+  if (!byPrefix) shared.set(storage, byPrefix = /* @__PURE__ */ new Map());
+  let entry = byPrefix.get(prefix);
+  if (!entry) byPrefix.set(prefix, entry = { open: null, bySchema: /* @__PURE__ */ new Map() });
+  return entry;
+}
+function heldAt(at, schema) {
+  let entry = at.bySchema.get(schema);
+  if (!entry) at.bySchema.set(schema, entry = { store: null, holders: 0 });
+  return entry;
+}
+var lent = (cache) => Object.create(cache, {
+  close: {
+    value: async () => {
+      await cache.flush();
+    }
+  }
+});
+function closeUnheldSoon(storage, prefix, schema, entry) {
+  queueMicrotask(() => {
+    if (entry.holders > 0) return;
+    void entry.store?.close();
+    entry.store = null;
+    const byPrefix = shared.get(storage);
+    const at = byPrefix?.get(prefix);
+    if (!at || !byPrefix) return;
+    if (at.bySchema.get(schema) === entry) at.bySchema.delete(schema);
+    if (at.bySchema.size > 0) return;
+    at.open?.stop();
+    void at.open?.cache.close();
+    byPrefix.delete(prefix);
+  });
+}
+function acquire(schema, options) {
+  const { storage, prefix } = options;
+  const at = sharedAt(storage, prefix);
+  const entry = heldAt(at, schema);
+  if (!entry.store) {
+    at.open ??= openPrefsCacheSync(options);
+    entry.store = createPrefsStore(
+      schema,
+      lent(at.open.cache),
+      options.validators,
+      void 0,
+      options.migrations?.length ?? 0
+    );
+    if (entry.holders === 0) closeUnheldSoon(storage, prefix, schema, entry);
+  }
+  return entry.store;
+}
+function usePrefsStore(schema, options) {
+  const { storage, prefix } = options;
+  const hold = useCallback(() => {
+    const entry = heldAt(sharedAt(storage, prefix), schema);
+    entry.holders++;
+    return () => {
+      if (--entry.holders === 0) closeUnheldSoon(storage, prefix, schema, entry);
+    };
+  }, [storage, prefix, schema]);
+  const current = () => acquire(schema, options);
+  return useSyncExternalStore(hold, current, current);
+}
 
-export { usePref, usePrefsValues };
+export { usePref, usePrefsStore, usePrefsValues };
 //# sourceMappingURL=react.js.map
 //# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks.ts"],"names":[],"mappings":";;;AAMO,SAAS,OAAA,CACd,OACA,IAAA,EAIA;AACA,EAAA,MAAM,SAAA,GAAY,WAAA,CAAY,CAAC,QAAA,KAAyB,KAAA,CAAM,UAAU,QAAQ,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAC1F,EAAA,MAAM,WAAA,GAAc,MAAM,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA;AACxC,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,SAAA,EAAW,WAAA,EAAa,WAAW,CAAA;AACtE,EAAA,MAAM,GAAA,GAAM,WAAA;AAAA,IACV,CAAC,IAAA,KAA+E;AAC9E,MAAA,KAAA,CAAM,GAAA;AAAA,QACJ,IAAA;AAAA,QACA,OAAO,SAAS,UAAA,GACX,IAAA,CAAwD,MAAM,GAAA,CAAI,IAAI,CAAC,CAAA,GACxE;AAAA,OACN;AAAA,IACF,CAAA;AAAA,IACA,CAAC,OAAO,IAAI;AAAA,GACd;AACA,EAAA,OAAO,CAAC,OAAO,GAAG,CAAA;AACpB;AAKO,SAAS,eAAoC,KAAA,EAMlD;AACA,EAAA,MAAM,SAAA,GAAY,WAAA,CAAY,CAAC,QAAA,KAAyB,KAAA,CAAM,UAAU,QAAQ,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAC1F,EAAA,MAAM,SAAS,oBAAA,CAAqB,SAAA,EAAW,KAAA,CAAM,MAAA,EAAQ,MAAM,MAAM,CAAA;AACzE,EAAA,MAAM,QAAQ,oBAAA,CAAqB,SAAA,EAAW,KAAA,CAAM,KAAA,EAAO,MAAM,KAAK,CAAA;AACtE,EAAA,MAAM,SAAS,oBAAA,CAAqB,SAAA,EAAW,KAAA,CAAM,MAAA,EAAQ,MAAM,MAAM,CAAA;AACzE,EAAA,MAAM,GAAA,GAAM,WAAA;AAAA,IACV,CAAC,IAAA,EAAc,KAAA,KAAmB,KAAA,CAAM,GAAA,CAAI,MAAqB,KAAc,CAAA;AAAA,IAC/E,CAAC,KAAK;AAAA,GACR;AACA,EAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,CAAC,IAAA,KAAkB,KAAA,CAAM,MAAM,IAAI,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AACvE,EAAA,OAAO,EAAE,MAAA,EAAQ,GAAA,EAAK,KAAA,EAAO,QAAQ,KAAA,EAAM;AAC7C","file":"react.js","sourcesContent":["import { useCallback, useSyncExternalStore } from 'react';\nimport type { PrefPath, PrefValueAt } from './paths';\nimport type { PrefGroup } from './schema';\nimport type { PrefsStore } from './store';\n\n/** One leaf of `store`, as React state. */\nexport function usePref<S extends PrefGroup, P extends PrefPath<S>>(\n  store: PrefsStore<S>,\n  path: P,\n): [\n  PrefValueAt<S, P>,\n  (next: PrefValueAt<S, P> | ((prev: PrefValueAt<S, P>) => PrefValueAt<S, P>)) => void,\n] {\n  const subscribe = useCallback((onChange: () => void) => store.subscribe(onChange), [store]);\n  const getSnapshot = () => store.get(path);\n  const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  const set = useCallback(\n    (next: PrefValueAt<S, P> | ((prev: PrefValueAt<S, P>) => PrefValueAt<S, P>)) => {\n      store.set(\n        path,\n        typeof next === 'function'\n          ? (next as (prev: PrefValueAt<S, P>) => PrefValueAt<S, P>)(store.get(path))\n          : next,\n      );\n    },\n    [store, path],\n  );\n  return [value, set];\n}\n\n/** The whole of `store` as React state, shaped for `PrefsForm`: `values`,\n *  `onChange={set}`, `auto={unset}`, and `reset` for `onAutoChange`. `stored`\n *  is `store.stored()`. */\nexport function usePrefsValues<S extends PrefGroup>(store: PrefsStore<S>): {\n  values: Record<string, unknown>;\n  set: (path: string, value: unknown) => void;\n  unset: ReadonlySet<string>;\n  stored: Record<string, unknown>;\n  reset: (path?: string) => void;\n} {\n  const subscribe = useCallback((onChange: () => void) => store.subscribe(onChange), [store]);\n  const values = useSyncExternalStore(subscribe, store.values, store.values);\n  const unset = useSyncExternalStore(subscribe, store.unset, store.unset);\n  const stored = useSyncExternalStore(subscribe, store.stored, store.stored);\n  const set = useCallback(\n    (path: string, value: unknown) => store.set(path as PrefPath<S>, value as never),\n    [store],\n  );\n  const reset = useCallback((path?: string) => store.reset(path), [store]);\n  return { values, set, unset, stored, reset };\n}\n"]}
+{"version":3,"sources":["../src/hooks.ts","../src/usePrefsStore.ts"],"names":["useCallback","useSyncExternalStore"],"mappings":"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","file":"react.js","sourcesContent":["import { useCallback, useSyncExternalStore } from 'react';\nimport type { PrefPath, PrefValueAt } from './paths';\nimport type { PrefGroup } from './groups';\nimport type { PrefsStore } from './store';\n\n/** One leaf of `store`, as React state. */\nexport function usePref<S extends PrefGroup, P extends PrefPath<S>>(\n  store: PrefsStore<S>,\n  path: P,\n): [\n  PrefValueAt<S, P>,\n  (next: PrefValueAt<S, P> | ((prev: PrefValueAt<S, P>) => PrefValueAt<S, P>)) => void,\n] {\n  const subscribe = useCallback((onChange: () => void) => store.subscribe(onChange), [store]);\n  const getSnapshot = () => store.get(path);\n  const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  const set = useCallback(\n    (next: PrefValueAt<S, P> | ((prev: PrefValueAt<S, P>) => PrefValueAt<S, P>)) => {\n      store.set(\n        path,\n        typeof next === 'function'\n          ? (next as (prev: PrefValueAt<S, P>) => PrefValueAt<S, P>)(store.get(path))\n          : next,\n      );\n    },\n    [store, path],\n  );\n  return [value, set];\n}\n\n/** The whole of `store` as React state, shaped for `PrefsForm`: `values`,\n *  `onChange={set}`, `auto={unset}`, and `reset` for `onAutoChange`. `stored`\n *  is `store.stored()`. */\nexport function usePrefsValues<S extends PrefGroup>(store: PrefsStore<S>): {\n  values: Record<string, unknown>;\n  set: (path: string, value: unknown) => void;\n  unset: ReadonlySet<string>;\n  stored: Record<string, unknown>;\n  reset: (path?: string) => void;\n} {\n  const subscribe = useCallback((onChange: () => void) => store.subscribe(onChange), [store]);\n  const values = useSyncExternalStore(subscribe, store.values, store.values);\n  const unset = useSyncExternalStore(subscribe, store.unset, store.unset);\n  const stored = useSyncExternalStore(subscribe, store.stored, store.stored);\n  const set = useCallback(\n    (path: string, value: unknown) => store.set(path as PrefPath<S>, value as never),\n    [store],\n  );\n  const reset = useCallback((path?: string) => store.reset(path), [store]);\n  return { values, set, unset, stored, reset };\n}\n","import type { OwnedRecordCache, StorageAdapter, SyncStorageAdapter } from '@weasel-js/storage';\nimport { useCallback, useSyncExternalStore } from 'react';\nimport type { PrefGroup } from './groups';\nimport { openPrefsCacheSync, type PrefsOptions } from './open';\nimport { createPrefsStore, type PrefsStore } from './store';\n\n/** The store open for one schema, and how many mounted components hold it. */\ninterface Held {\n  store: PrefsStore<PrefGroup> | null;\n  holders: number;\n}\n\n/** The one cache open on a prefix, and a store over it for each schema in use. */\ninterface Shared {\n  open: { cache: OwnedRecordCache; stop: () => void } | null;\n  bySchema: Map<PrefGroup, Held>;\n}\n\ntype SyncOptions = PrefsOptions & { storage: SyncStorageAdapter };\n\nconst shared = new WeakMap<StorageAdapter, Map<string, Shared>>();\n\nfunction sharedAt(storage: StorageAdapter, prefix: string): Shared {\n  let byPrefix = shared.get(storage);\n  if (!byPrefix) shared.set(storage, (byPrefix = new Map()));\n  let entry = byPrefix.get(prefix);\n  if (!entry) byPrefix.set(prefix, (entry = { open: null, bySchema: new Map() }));\n  return entry;\n}\n\nfunction heldAt(at: Shared, schema: PrefGroup): Held {\n  let entry = at.bySchema.get(schema);\n  if (!entry) at.bySchema.set(schema, (entry = { store: null, holders: 0 }));\n  return entry;\n}\n\n/** `cache` for one store among several: closing it sends queued writes and\n *  leaves the cache open for the others. */\nconst lent = (cache: OwnedRecordCache): OwnedRecordCache =>\n  Object.create(cache, {\n    close: {\n      value: async (): Promise<void> => {\n        await cache.flush();\n      },\n    },\n  }) as OwnedRecordCache;\n\n/** Close a store nothing holds, and the cache once no store is over it, a\n *  microtask on: after the remount StrictMode and fast refresh make in the\n *  same tick, which holds it again. */\nfunction closeUnheldSoon(storage: StorageAdapter, prefix: string, schema: PrefGroup, entry: Held): void {\n  queueMicrotask(() => {\n    if (entry.holders > 0) return;\n    void entry.store?.close();\n    entry.store = null;\n    const byPrefix = shared.get(storage);\n    const at = byPrefix?.get(prefix);\n    if (!at || !byPrefix) return;\n    if (at.bySchema.get(schema) === entry) at.bySchema.delete(schema);\n    if (at.bySchema.size > 0) return;\n    at.open?.stop();\n    // `close` sends queued writes before its first await, and a sync adapter's\n    // write lands in that call, so a cache opened next reads them.\n    void at.open?.cache.close();\n    byPrefix.delete(prefix);\n  });\n}\n\nfunction acquire<S extends PrefGroup>(schema: S, options: SyncOptions): PrefsStore<S> {\n  const { storage, prefix } = options;\n  const at = sharedAt(storage, prefix);\n  const entry = heldAt(at, schema);\n  if (!entry.store) {\n    at.open ??= openPrefsCacheSync(options);\n    entry.store = createPrefsStore(\n      schema,\n      lent(at.open.cache),\n      options.validators,\n      undefined,\n      options.migrations?.length ?? 0,\n    ) as unknown as PrefsStore<PrefGroup>;\n    // Opened by a render that may never mount.\n    if (entry.holders === 0) closeUnheldSoon(storage, prefix, schema, entry);\n  }\n  return entry.store as unknown as PrefsStore<S>;\n}\n\n/**\n * A store for `schema`, open while the component is mounted: opened during\n * the first render, so that render has values, and closed, with its queued\n * writes sent, when the component unmounts.\n *\n * Components naming the same `storage`, `prefix`, and `schema` share one\n * store, which closes when the last of them unmounts. Components naming the\n * same `storage` and `prefix` with different schemas each get a store of\n * their own over the same records, so a write through one is read by the\n * others at once, and each hears it as a `local` change. They must pass the\n * same `migrations`: the records are migrated once, when the first opens.\n *\n * `storage` and `schema` are compared by identity and `prefix` by value, so\n * keep the first two out of the render body. A change to any of the three\n * closes the store and returns the one for the new three. The `options`\n * object itself may be new every render: `migrations` and `validators` are\n * read when a store opens, and a change to either alone opens nothing.\n */\nexport function usePrefsStore<S extends PrefGroup>(schema: S, options: SyncOptions): PrefsStore<S> {\n  const { storage, prefix } = options;\n  const hold = useCallback(() => {\n    const entry = heldAt(sharedAt(storage, prefix), schema);\n    entry.holders++;\n    return () => {\n      if (--entry.holders === 0) closeUnheldSoon(storage, prefix, schema, entry);\n    };\n  }, [storage, prefix, schema]);\n  // Read again once held, so a store closed between render and mount is\n  // replaced before anything uses it.\n  const current = () => acquire(schema, options);\n  return useSyncExternalStore(hold, current, current);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/prefs",
-  "version": "1.9.3",
+  "version": "1.10.0",
   "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",
@@ -41,8 +41,9 @@
     "build": "tsup"
   },
   "dependencies": {
-    "@weasel-js/quantity": "1.9.3",
-    "@weasel-js/storage": "1.9.3"
+    "@weasel-js/quantity": "1.10.0",
+    "@weasel-js/registry": "1.10.0",
+    "@weasel-js/storage": "1.10.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/dist/store-BU2tRX5H.d.ts

@@ -1,353 +0,0 @@
-import { Display, UnitEntry, InfinityText, UnitSystem, Unit } from '@weasel-js/quantity';
-
-/** The value types a built-in pref leaf can hold. */
-type PrefKind = 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint' | 'object' | 'field';
-/**
- * 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;
-    /** 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[];
-}
-/** 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';
-/** 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 stands for infinity: the value there is ±Infinity. */
-    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;
-}
-/** A pref with a fixed set of labeled choices. `default` is `undefined` only
- *  for a {@link PrefEnum.clearable} leaf, whose absence is a value. */
-interface PrefEnum<T extends string = string> extends PrefBase<'enum', T | undefined> {
-    /**
-     * 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.
-     */
-    clearable?: boolean;
-    /** `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 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 PrefGroup}, which
- * organises the fields under a heading without contributing to the path —
- * the same rule group keys follow at the top level. A `TextStyle` needs it:
- * its character and paragraph fields belong to one value but read as two
- * lists.
- */
-interface PrefObject extends PrefBase<'object', unknown> {
-    children: Record<string, PrefLeaf | PrefGroup>;
-    /**
-     * Lift a non-object value into the object form, for a consumer field that
-     * may also be held as a scalar. Called before a child edit is applied;
-     * without it a scalar-valued leaf shows its children empty and refuses the
-     * edit.
-     */
-    fromScalar?: (value: unknown) => Record<string, unknown>;
-}
-/**
- * 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 | PrefField;
-/**
- * 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;
-/** Nestable group: branch nodes a tool can use to organize its prefs. */
-interface PrefGroup {
-    /** Heading for the group's rows. **Empty means no heading** — for a group
-     *  that exists to organise, not to name: one whose children are themselves
-     *  groups carrying the labels a reader needs. Give it a name whenever the
-     *  name is the referent (a `Border` group over `Top` / `Right` / `Bottom`
-     *  reads as nothing without it). */
-    name: string;
-    description?: string;
-    children: Record<string, PrefLeaf | PrefGroup>;
-}
-
-type Join<A extends string, B extends string> = A extends '' ? B : `${A}.${B}`;
-/** Every leaf's dotted path in a schema. A group's key is a segment; an
- *  `object` leaf is one path, its fields are not. */
-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;
-    } ? 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;
-/** What a leaf holds: its kind's value type for a built-in kind, the type of
- *  its `default` for an app-defined one. */
-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 {
-    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 when the store cannot persist: storage was unreadable, or written
-     *  by a newer schema. Changes still apply for this session. */
-    readonly writable: boolean;
-    /** Resolves true when every queued write reached storage. */
-    flush(): Promise<boolean>;
-    close(): Promise<void>;
-}
-
-export { type PrefValueOf as A, type BuiltinPref as B, isBuiltinPref as C, pairRowsOf as D, prefUnit as E, type PrefLeaf as P, type PrefGroup as a, type PrefNumber as b, type PrefsStore as c, PREF_KINDS as d, type PrefAtPath as e, type PrefBase as f, type PrefBoolean as g, type PrefBooleanControl as h, type PrefBooleanEncoding as i, type PrefChange as j, type PrefColor as k, type PrefCustom as l, type PrefEnum as m, type PrefEnumControl as n, type PrefEnumEncoding as o, type PrefField as p, type PrefKind as q, type PrefNumberControl as r, type PrefNumberUnit as s, type PrefObject as t, type PrefPaint as u, type PrefPair as v, type PrefPath as w, type PrefString as x, type PrefStringControl as y, type PrefValueAt as z };