vultus-core 0.4.0 → 0.5.0

package/src/argStore.ts

@@ -0,0 +1,49 @@
+/** Whether a write pushes a new history entry or replaces the current one; a store without history ignores it. */
+export type UpdateMethod = 'push' | 'replace';
+
+/** One key's new raw value, or `undefined` to remove it (the key reads back as its default). */
+export interface RawChange {
+  key: string;
+  raw: string | undefined;
+}
+
+/**
+ * A store for argument values kept as strings (moxb's url-arg backends, batched): a URL query,
+ * localStorage, or (here) memory. `read` and `write` move raw strings only — parsing, defaults
+ * and equality live in the value type and in useArg, not here. The hooks call its methods on
+ * the store, never detached, so a store may be a class whose methods use `this`.
+ */
+export interface ArgStore {
+  read(key: string): string | undefined;
+  /** Applies every change, then notifies subscribers once — several keys changed together are one history entry. */
+  write(changes: RawChange[], method: UpdateMethod): void;
+  subscribe(listener: () => void): () => void;
+  /** The href a write of `changes` would produce, where the store has one (a URL store); omitted otherwise. */
+  hrefFor?(changes: RawChange[]): string;
+}
+
+/** An ArgStore over a plain object, for tests and demos. `snapshot()` is a copy, for assertions. */
+export function memoryStore(initial: Record<string, string> = {}): ArgStore & { snapshot(): Record<string, string> } {
+  const data: Record<string, string> = { ...initial };
+  const listeners = new Set<() => void>();
+
+  return {
+    read(key) {
+      return data[key];
+    },
+    write(changes, _method) {
+      for (const { key, raw } of changes) {
+        if (raw === undefined) delete data[key];
+        else data[key] = raw;
+      }
+      listeners.forEach((listener) => listener());
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    snapshot() {
+      return { ...data };
+    },
+  };
+}

package/src/choices.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react';
+import { calculateEnabled } from './field.js';
+import { getReason, getVerdict } from './decision.js';
+import type { Decision } from './types.js';
+
+/**
+ * One choice of a one-of or many-of field, or a tree node (moxb's
+ * BindOneOfChoice). Shared by useOneOfField today; useManyOfField and the
+ * tree hook (later tasks) build on the same shape.
+ */
+export interface OneOfChoice<T extends string = string> {
+  value: T;
+  /** Shown for the choice; default: the value. */
+  label?: string;
+  /** What choosing it does (moxb's `help`), markdown; also the field's current state when it is chosen. */
+  description?: string;
+  /** Shown before the label (or instead of it, for an icon-only widget), like an action's icon. */
+  icon?: ReactNode;
+  /** Choosable? Default true, optionally with a reason. Use `enabled` or `disabled`, not contradicting each other. */
+  enabled?: Decision;
+  disabled?: Decision;
+  /** Shown as the main or a dangerous choice, like an action's variant. Default 'default'. */
+  variant?: 'default' | 'primary' | 'danger';
+  /** A heading the choice is listed under, after the choices without one (OneOfSelect); default none. */
+  group?: string;
+  /** Shown after the label in secondary colour, e.g. a count ("12", "12 · 8%"). Default none. */
+  note?: string;
+  /** Shown faded, e.g. a choice with nothing behind it right now (no matching tasks). Default false. */
+  dimmed?: boolean;
+}
+
+/** A choice as the widgets get it. */
+export interface OneOfChoiceControls<T extends string = string> {
+  value: T;
+  label: string;
+  description: string | undefined;
+  icon: ReactNode | undefined;
+  enabled: boolean;
+  whyDisabled: string | undefined;
+  variant: 'default' | 'primary' | 'danger';
+  group: string | undefined;
+  note: string | undefined;
+  dimmed: boolean;
+}
+
+/** Resolves a choice's `enabled` / `disabled` and defaults, as useOneOfField does for each of its choices. */
+export function resolveChoice<T extends string>(fieldId: string, choice: OneOfChoice<T>): OneOfChoiceControls<T> {
+  const decision = calculateEnabled(`${fieldId}.${choice.value}`, choice.enabled, choice.disabled);
+  const enabled = getVerdict(decision, true);
+  return {
+    value: choice.value,
+    label: choice.label ?? choice.value,
+    description: choice.description,
+    icon: choice.icon,
+    enabled,
+    whyDisabled: enabled ? undefined : getReason(decision),
+    variant: choice.variant ?? 'default',
+    group: choice.group,
+    note: choice.note,
+    dimmed: choice.dimmed ?? false,
+  };
+}

package/src/field.ts

@@ -1,6 +1,7 @@
 import { useState } from 'react';
 import { getReason, getVerdict, invertDecision } from './decision.js';
-import { resolve } from './resolve.js';
+import { useFieldContext } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
 import { useAction } from './useAction.js';
 import type {
   ConfirmationSpec,
@@ -21,6 +22,12 @@ import type {
  * Design notes: unitas docs/2026-10-05-vultus-field-model-design.md.
  */
 
+/** The field kinds (FieldControls.type and a FieldDefinition's `kind`). */
+export type FieldKind = 'boolean' | 'mixed-boolean' | 'oneOf' | 'manyOf' | 'numeric' | 'range' | 'tree' | 'text';
+
+/** The widget to render a field with: a name, or a name with display options overriding its defaults. */
+export type WidgetHint = string | { name: string; [option: string]: unknown };
+
 /** How an immediately committing field stores a change: an action that receives the requested value. */
 export interface FieldCommit<TRequest, RouteId extends string = string> {
   fire: (next: TRequest, ctx: ExecutionContext) => Promise<void> | void;
@@ -32,16 +39,30 @@ export interface FieldCommit<TRequest, RouteId extends string = string> {
 /** The key of a value in `valueDescriptions`: 'true' / 'false' for booleans, the value itself for strings. */
 export type ValueKey<T> = T extends boolean ? `${T}` : T extends string | number ? `${T}` : never;
 
-interface FieldBaseOptions<TValue> {
+/**
+ * What every field has, whatever its storage. `Ctx` is the field context the options' functions
+ * receive (see FieldContextProvider); a function without parameters needs none.
+ */
+export interface FieldBaseOptions<TValue, Ctx = any> {
   id: string;
-  label?: ValueOrFn<string>;
-  description?: ValueOrFn<string | undefined>;
+  /**
+   * The field's kind, as a FieldDefinition carries it (optional here: a hook knows its own
+   * kind). Given and different from the hook's own kind, it throws — a defence against passing
+   * the wrong definition to a kind-specific hook.
+   */
+  kind?: FieldKind;
+  label?: ValueOrFn<string, Ctx>;
+  description?: ValueOrFn<string | undefined, Ctx>;
+  /** Shown while the field is empty (moxb's Value); a widget that has no notion of "empty" ignores it. */
+  placeholder?: ValueOrFn<string | undefined, Ctx>;
+  /** The widget to render this field with: a name, or a name with its display options. Each kind has a default; vultus-antd's `<Field>` applies render-site overrides on top of this. */
+  widget?: WidgetHint;
   /** Shown? Default true. Use `visible` or `hidden`, not contradicting each other. */
-  visible?: ValueOrFn<boolean>;
-  hidden?: ValueOrFn<boolean>;
+  visible?: ValueOrFn<boolean, Ctx>;
+  hidden?: ValueOrFn<boolean, Ctx>;
   /** Changeable? Default true, optionally with a reason. Use `enabled` or `disabled`, not contradicting each other. */
-  enabled?: ValueOrFn<Decision>;
-  disabled?: ValueOrFn<Decision>;
+  enabled?: ValueOrFn<Decision, Ctx>;
+  disabled?: ValueOrFn<Decision, Ctx>;
   /**
    * What each value means right now, keyed by value (for booleans `true` / `false`, and `mixed`
    * where the field can show it). Shown with the current value, next to `description`, which
@@ -55,23 +76,24 @@ interface FieldBaseOptions<TValue> {
  * `TValue` and can be asked for a `TRequest`; usually the same type, but an aggregate can show
  * a state that cannot be requested (a boolean field showing 'mixed').
  */
-export type FieldStorage<TValue, TRequest = TValue, RouteId extends string = string> =
-  /** Inside the field: its own state, starting at `initialValue`. */
-  | { initialValue?: TValue; value?: never; onChange?: never; commit?: never }
+export type FieldStorage<TValue, TRequest = TValue, RouteId extends string = string, Ctx = any> =
+  /** Inside the field: its own state, starting at `initialValue` (resolved once, when the field mounts). */
+  | { initialValue?: ValueOrFn<TValue, Ctx>; value?: never; onChange?: never; commit?: never }
   /** Outside, changed locally: the caller owns the value and applies `onChange`. */
   | { value: TValue; onChange: (value: TRequest) => void; initialValue?: never; commit?: never }
   /** Outside, committed immediately: `commit.fire` stores the change (pending, messages, confirmation). */
   | { value: TValue; commit: FieldCommit<TRequest, RouteId>; initialValue?: never; onChange?: never };
 
-export type FieldOptions<TValue, TRequest = TValue, RouteId extends string = string> =
-  FieldBaseOptions<TValue> & FieldStorage<TValue, TRequest, RouteId>;
+export type FieldOptions<TValue, TRequest = TValue, RouteId extends string = string, Ctx = any> =
+  FieldBaseOptions<TValue, Ctx> & FieldStorage<TValue, TRequest, RouteId, Ctx>;
 
 /** What a field widget receives: everything it shows, and the one way to change the value. */
 export interface FieldControls<TValue, TRequest = TValue> {
-  type: string;
+  type: FieldKind;
   id: string;
   label: string;
   description: string | undefined;
+  placeholder: string | undefined;
   /** What the current value means (from `valueDescriptions`). */
   valueDescription: string | undefined;
   visible: boolean;
@@ -82,10 +104,13 @@ export interface FieldControls<TValue, TRequest = TValue> {
   setValue(next: TRequest): void;
   /** A commit is running. */
   pending: boolean;
+  /** The field stores through `commit` — true exactly in commit storage mode, so a widget can hold back requests while typing. */
+  commits: boolean;
   /** Messages of the last commit. */
   messages: Message[];
   /** The confirmation a widget must obtain before requesting `next`, if any. */
   confirmationFor(next: TRequest): ConfirmationSpec | undefined;
+  widget: WidgetHint | undefined;
 }
 
 export type FieldStorageMode = 'inside' | 'local' | 'commit';
@@ -122,27 +147,38 @@ export function calculateEnabled(id: string, enabled: Decision | undefined, disa
 /**
  * The shared core of every field hook: label and description, visibility and
  * enabled state (with reason), the storage mode, and in commit mode the setter
- * as an action (its pending state and messages become the field's).
+ * as an action (its pending state and messages become the field's). Functions
+ * among the options are resolved with the field context, on every render;
+ * `initialValue` once, when the field mounts. A kind's hook passes its implicit
+ * initial value as a zero-argument function, so that too is computed only then.
  */
-export function useFieldCore<TValue, TRequest extends TValue = TValue, RouteId extends string = string>(
-  type: string,
-  opts: FieldOptions<TValue, TRequest, RouteId>,
+export function useFieldCore<TValue, TRequest extends TValue = TValue, RouteId extends string = string, Ctx = any>(
+  type: FieldKind,
+  opts: FieldOptions<TValue, TRequest, RouteId, Ctx>,
   registry?: ErrorRoutesRegistry<RouteId>,
 ): FieldControls<TValue, TRequest> {
+  if (opts.kind !== undefined && opts.kind !== type) {
+    throw new Error(`Field '${opts.id}': a definition of kind '${opts.kind}' was passed to the '${type}' hook`);
+  }
   const mode = fieldStorageMode(opts.id, opts as FieldStorage<unknown, unknown, string>);
-  const [inner, setInner] = useState<TValue>(opts.initialValue as TValue);
+  const ctx = useFieldContext();
+  const where = (name: string) => `Field '${opts.id}': option '${name}'`;
+  const [inner, setInner] = useState<TValue>(
+    () => resolveIn<TValue | undefined>(opts.initialValue, undefined, ctx, where('initialValue')) as TValue,
+  );
 
-  const label = resolve(opts.label, '');
-  const description = resolve<string | undefined>(opts.description, undefined);
+  const label = resolveIn(opts.label, '', ctx, where('label'));
+  const description = resolveIn<string | undefined>(opts.description, undefined, ctx, where('description'));
+  const placeholder = resolveIn<string | undefined>(opts.placeholder, undefined, ctx, where('placeholder'));
   const visible = calculateVisible(
     opts.id,
-    resolve<boolean | undefined>(opts.visible, undefined),
-    resolve<boolean | undefined>(opts.hidden, undefined),
+    resolveIn<boolean | undefined>(opts.visible, undefined, ctx, where('visible')),
+    resolveIn<boolean | undefined>(opts.hidden, undefined, ctx, where('hidden')),
   );
   const enabledDecision = calculateEnabled(
     opts.id,
-    resolve<Decision | undefined>(opts.enabled, undefined),
-    resolve<Decision | undefined>(opts.disabled, undefined),
+    resolveIn<Decision | undefined>(opts.enabled, undefined, ctx, where('enabled')),
+    resolveIn<Decision | undefined>(opts.disabled, undefined, ctx, where('disabled')),
   );
   const enabled = getVerdict(enabledDecision, true);
   const whyDisabled = enabled ? undefined : getReason(enabledDecision);
@@ -184,6 +220,7 @@ export function useFieldCore<TValue, TRequest extends TValue = TValue, RouteId e
     id: opts.id,
     label,
     description,
+    placeholder,
     valueDescription,
     visible,
     enabled,
@@ -191,7 +228,9 @@ export function useFieldCore<TValue, TRequest extends TValue = TValue, RouteId e
     value,
     setValue,
     pending,
+    commits: mode === 'commit',
     messages: mode === 'commit' ? (setter.messages ?? []) : [],
     confirmationFor,
+    widget: opts.widget,
   };
 }

package/src/index.ts

@@ -6,17 +6,63 @@ export * from './routeApiError.js';
 export { ActionErrorContext, useActionErrorCtx } from './useActionErrorCtx.js';
 export { useAction } from './useAction.js';
 export { useActionList } from './useActionList.js';
+export {
+  FieldContextProvider, createFieldContext, useFieldContext, NO_FIELD_CONTEXT, type FieldCtx,
+} from './FieldContext.js';
 export {
   useFieldCore, fieldStorageMode, calculateVisible, calculateEnabled,
-  type FieldCommit, type FieldControls, type FieldOptions, type FieldStorage, type FieldStorageMode, type ValueKey,
+  type FieldBaseOptions, type FieldCommit, type FieldControls, type FieldOptions, type FieldStorage, type FieldStorageMode,
+  type FieldKind, type WidgetHint, type ValueKey,
 } from './field.js';
-export { useBoolField, type BoolFieldControls, type BoolFieldOptions } from './useBoolField.js';
+export { resolveChoice, type OneOfChoice, type OneOfChoiceControls } from './choices.js';
+export { normalizeText } from './normalizeText.js';
+export { useBoolField, boolInitialValue, type BoolFieldControls, type BoolFieldOptions } from './useBoolField.js';
 export {
-  useMixedBoolField, aggregateBool, type MixedBool, type MixedBoolFieldControls, type MixedBoolFieldOptions,
+  useMixedBoolField, aggregateBool, mixedBoolInitialValue,
+  type MixedBool, type MixedBoolFieldControls, type MixedBoolFieldOptions,
 } from './useMixedBoolField.js';
 export {
-  useOneOfField, type OneOfChoice, type OneOfChoiceControls, type OneOfFieldControls, type OneOfFieldOptions,
+  useOneOfField, oneOfInitialValue, type OneOfFieldControls, type OneOfFieldOptions, type OneOfOwnOptions,
 } from './useOneOfField.js';
+export {
+  useManyOfField, manyOfInitialValue,
+  type ManyOfFieldControls, type ManyOfFieldOptions, type ManyOfOwnOptions, type ManyOfChoiceControls,
+} from './useManyOfField.js';
+export { clamp, resolveNumeric, type NumericBounds, type ResolvedNumeric } from './numeric.js';
+export {
+  useNumericField, numericInitialValue,
+  type NumericFieldControls, type NumericFieldOptions, type NumericOwnOptions,
+} from './useNumericField.js';
+export {
+  useRangeField, rangeInitialValue,
+  type NumberRange, type RangeFieldControls, type RangeFieldOptions, type RangeOwnOptions,
+} from './useRangeField.js';
+export {
+  normalizeTreeValue, coveredNodes, toggleTreeValue, expandedTreeKeys, filterTree,
+  type TreeNode, type TreeNodeControls, type TreeSelection, type TreeExpand,
+} from './tree.js';
+export {
+  useTreeField, treeInitialValue,
+  type TreeFieldControls, type TreeFieldOptions, type TreeOwnOptions,
+} from './useTreeField.js';
+export {
+  useTextField, textInitialValue,
+  type TextFieldControls, type TextFieldOptions, type TextOwnOptions,
+} from './useTextField.js';
+export {
+  booleanType, stringType, stringSetType, numberType, rangeType, type ValueType,
+} from './valueTypes.js';
+export { initialValueOf, valueTypeOf, sanitizeStored, type FieldDefinition } from './kinds.js';
+export { memoryStore, type ArgStore, type RawChange, type UpdateMethod } from './argStore.js';
+export { localStorageStore } from './localStorageStore.js';
+export { ArgStoreProvider, useArgStore } from './ArgStoreContext.js';
+export {
+  useArg, useArgWriter, setArg, resetArg,
+  type ArgDefinition, type ArgControls, type ArgChange,
+} from './useArg.js';
+export {
+  argOf, useStoredField, useStoredFields, type StoredField, type StoredFields,
+} from './useStoredField.js';
 export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';
 export {

package/src/kinds.ts

@@ -0,0 +1,197 @@
+import { resolveChoice, type OneOfChoice, type OneOfChoiceControls } from './choices.js';
+import type { FieldBaseOptions, FieldKind } from './field.js';
+import type { FieldCtx } from './FieldContext.js';
+import { clamp, resolveNumeric } from './numeric.js';
+import { resolveIn } from './resolve.js';
+import { normalizeTreeValue, type TreeNode } from './tree.js';
+import type { ValueOrFn } from './types.js';
+import { boolInitialValue, type useBoolField } from './useBoolField.js';
+import { manyOfInitialValue, type ManyOfOwnOptions, type useManyOfField } from './useManyOfField.js';
+import { mixedBoolInitialValue, type MixedBool, type useMixedBoolField } from './useMixedBoolField.js';
+import { numericInitialValue, type NumericOwnOptions, type useNumericField } from './useNumericField.js';
+import { oneOfInitialValue, type OneOfOwnOptions, type useOneOfField } from './useOneOfField.js';
+import { rangeInitialValue, type NumberRange, type RangeOwnOptions, type useRangeField } from './useRangeField.js';
+import { textInitialValue, type TextOwnOptions, type useTextField } from './useTextField.js';
+import { treeInitialValue, type TreeOwnOptions, type useTreeField } from './useTreeField.js';
+import { booleanType, numberType, rangeType, stringSetType, stringType, type ValueType } from './valueTypes.js';
+
+/**
+ * A definition of kind `K`: the kind's hook options in their inside form, with `kind` required.
+ * It has no `value`, `onChange` or `commit`: where the value lives is chosen by whoever runs the
+ * field, and a store holds the definition's initial value as its default.
+ */
+type Definition<K extends FieldKind, V, Own, Ctx> =
+  { kind: K } & FieldBaseOptions<V, Ctx> & { initialValue?: ValueOrFn<V, Ctx> } & Own;
+
+/**
+ * A field as plain data (a module's filters, a dialog's options), tagged by its kind. Narrowed
+ * by `kind`, a definition is its kind's hook options as they are: `useOneOfField(definition)`.
+ * Its functions receive the field context `Ctx` (see FieldContextProvider).
+ */
+export type FieldDefinition<Ctx = any> =
+  | Definition<'boolean', boolean, {}, Ctx>
+  | Definition<'mixed-boolean', MixedBool, {}, Ctx>
+  | Definition<'oneOf', string, OneOfOwnOptions<string, Ctx>, Ctx>
+  | Definition<'manyOf', string[], ManyOfOwnOptions<string, Ctx>, Ctx>
+  | Definition<'numeric', number, NumericOwnOptions<Ctx>, Ctx>
+  | Definition<'range', NumberRange, RangeOwnOptions<Ctx>, Ctx>
+  | Definition<'tree', string[], TreeOwnOptions<string, Ctx>, Ctx>
+  | Definition<'text', string, TextOwnOptions, Ctx>;
+
+/** Compiles only when `A` is assignable to `B`. */
+type Fits<A extends B, B> = A;
+type DefinitionOf<K extends FieldKind> = Extract<FieldDefinition, { kind: K }>;
+type HookOptions<H extends (...args: any[]) => unknown> = Parameters<H>[0];
+
+/**
+ * A compile-time check, the gate for "a definition is its kind's hook options as they are": if a
+ * hook's options and the definition drift apart, `tsc` fails here.
+ */
+type DefinitionsFitTheirHooks = [
+  Fits<DefinitionOf<'boolean'>, HookOptions<typeof useBoolField>>,
+  Fits<DefinitionOf<'mixed-boolean'>, HookOptions<typeof useMixedBoolField>>,
+  Fits<DefinitionOf<'oneOf'>, HookOptions<typeof useOneOfField>>,
+  Fits<DefinitionOf<'manyOf'>, HookOptions<typeof useManyOfField>>,
+  Fits<DefinitionOf<'numeric'>, HookOptions<typeof useNumericField>>,
+  Fits<DefinitionOf<'range'>, HookOptions<typeof useRangeField>>,
+  Fits<DefinitionOf<'tree'>, HookOptions<typeof useTreeField>>,
+  Fits<DefinitionOf<'text'>, HookOptions<typeof useTextField>>,
+];
+
+const NOT_STORABLE = 'a mixed-boolean field is an aggregate of other data and cannot be stored';
+
+/** A definition whose kind is none of FieldKind's (plain data can carry anything): fail loudly rather than give nothing. */
+function unknownKind(definition: never): never {
+  const { id, kind } = definition as { id: string; kind: unknown };
+  throw new Error(`Field '${id}': unknown kind '${String(kind)}'`);
+}
+
+/** The choices of a one-of or many-of definition, resolved as the hooks resolve them. */
+function choicesOf(definition: { id: string; choices: ValueOrFn<OneOfChoice[]> }, ctx: FieldCtx): OneOfChoiceControls[] {
+  const { id, choices } = definition;
+  return resolveIn<OneOfChoice[]>(choices, [], ctx, `Field '${id}': option 'choices'`).map((c) => resolveChoice(id, c));
+}
+
+/** Every node's value, at any depth. */
+function nodeValues(nodes: TreeNode[], into = new Set<string>()): Set<string> {
+  for (const node of nodes) {
+    into.add(node.value);
+    if (node.children) nodeValues(node.children, into);
+  }
+  return into;
+}
+
+/** A tree definition's nodes, resolved as useTreeField resolves them. */
+function nodesOf(definition: { id: string; nodes: ValueOrFn<TreeNode[]> }, ctx: FieldCtx): TreeNode[] {
+  return resolveIn<TreeNode[]>(definition.nodes, [], ctx, `Field '${definition.id}': option 'nodes'`);
+}
+
+/**
+ * A definition's default: `initialValue` resolved with the field context, else its kind's
+ * implicit initial value (false; the first enabled choice; the empty list; `min`, or 0, clamped
+ * into the bounds; `[min, max]`; the empty string). A tree's comes normalized under its
+ * selection, as the hook shows it, so a value equal to what the field shows by default is equal
+ * to the default too. It is what a store falls back to, what a reset restores, and what "is it
+ * set?" compares against; the kind's hook starts at the same value.
+ */
+export function initialValueOf(definition: FieldDefinition, ctx: FieldCtx): unknown {
+  const { id } = definition;
+  switch (definition.kind) {
+    case 'boolean': return boolInitialValue(definition, ctx, id);
+    case 'mixed-boolean': return mixedBoolInitialValue(definition, ctx, id);
+    case 'oneOf': return oneOfInitialValue(definition, ctx, id, choicesOf(definition, ctx));
+    case 'manyOf': return manyOfInitialValue(definition, ctx, id);
+    case 'numeric': return numericInitialValue(definition, ctx, id);
+    case 'range': return rangeInitialValue(definition, ctx, id);
+    case 'tree':
+      return normalizeTreeValue(nodesOf(definition, ctx), treeInitialValue(definition, ctx, id), definition.selection ?? 'topmost');
+    case 'text': return textInitialValue(definition, ctx, id);
+    default: return unknownKind(definition);
+  }
+}
+
+/** How a kind's value is kept in a store. A mixed-boolean field shows an aggregate of other data, so it has none and throws. */
+export function valueTypeOf(kind: FieldKind): ValueType<any> {
+  switch (kind) {
+    case 'boolean': return booleanType;
+    case 'oneOf':
+    case 'text': return stringType;
+    case 'manyOf':
+    case 'tree': return stringSetType;
+    case 'numeric': return numberType;
+    case 'range': return rangeType;
+    case 'mixed-boolean': throw new Error(NOT_STORABLE);
+    default: throw new Error(`unknown field kind '${String(kind as unknown)}'`);
+  }
+}
+
+function warnDropped(id: string, among: 'choices' | 'nodes', dropped: string[], warn: (message: string) => void): void {
+  if (dropped.length === 0) return;
+  const listed = [...new Set(dropped)].map((v) => `'${v}'`).join(', ');
+  warn(`Field '${id}': dropping stored values that are not among its ${among}: ${listed}`);
+}
+
+/**
+ * A stored value (already parsed by the kind's value type) made fit for the definition as it is
+ * now: choices, nodes and bounds follow the data, and an old URL may not. A one-of value that is
+ * not a choice becomes the initial value; many-of and tree values that are not choices or nodes
+ * are dropped; numbers and ranges are clamped into the bounds. Each such change warns, naming
+ * the field: the value came from outside, so it is not an error. Reordering is silent: lists
+ * come back in choice order or normalized under the tree's selection (a store keeps them
+ * sorted, so a warning would come on every read), and a range's ends in order. The warnings go
+ * to `warn`, console.warn unless a caller that only summarizes (useStoredFields) silences them.
+ */
+export function sanitizeStored(
+  definition: FieldDefinition,
+  value: unknown,
+  ctx: FieldCtx,
+  warn: (message: string) => void = (message) => console.warn(message),
+): unknown {
+  const { id } = definition;
+  switch (definition.kind) {
+    case 'boolean':
+    case 'text':
+      return value;
+    case 'mixed-boolean':
+      throw new Error(`Field '${id}': ${NOT_STORABLE}`);
+    case 'oneOf': {
+      const choices = choicesOf(definition, ctx);
+      if (choices.some((c) => c.value === value)) return value;
+      const fallback = oneOfInitialValue(definition, ctx, id, choices);
+      if (fallback !== value) warn(`Field '${id}': stored value '${value}' is not one of its choices, using '${fallback}'`);
+      return fallback;
+    }
+    case 'manyOf': {
+      const stored = value as string[];
+      const known = choicesOf(definition, ctx).map((c) => c.value);
+      warnDropped(id, 'choices', stored.filter((v) => !known.includes(v)), warn);
+      return known.filter((v) => stored.includes(v));
+    }
+    case 'tree': {
+      const stored = value as string[];
+      const nodes = nodesOf(definition, ctx);
+      const known = nodeValues(nodes);
+      warnDropped(id, 'nodes', stored.filter((v) => !known.has(v)), warn);
+      return normalizeTreeValue(nodes, stored.filter((v) => known.has(v)), definition.selection ?? 'topmost');
+    }
+    case 'numeric': {
+      const stored = value as number;
+      const { min, max } = resolveNumeric(id, definition, ctx);
+      const clamped = clamp(stored, min, max);
+      if (clamped !== stored) warn(`Field '${id}': stored value ${stored} is outside its bounds, using ${clamped}`);
+      return clamped;
+    }
+    case 'range': {
+      const stored = value as NumberRange;
+      const { min, max } = resolveNumeric(id, definition, ctx);
+      const from = clamp(stored[0], min, max);
+      const to = clamp(stored[1], min, max);
+      const sanitized: NumberRange = [Math.min(from, to), Math.max(from, to)];
+      if (from !== stored[0] || to !== stored[1]) {
+        warn(`Field '${id}': stored range ${rangeType.format(stored)} is outside its bounds, using ${rangeType.format(sanitized)}`);
+      }
+      return sanitized;
+    }
+    default: return unknownKind(definition);
+  }
+}

package/src/localStorageStore.ts

@@ -0,0 +1,68 @@
+import type { ArgStore } from './argStore.js';
+
+/**
+ * An ArgStore over `window.localStorage` (Praeceptor's print options), items kept under
+ * `${prefix}.${key}`. Guarded for SSR/Node (`typeof window === 'undefined'`), so creating one
+ * outside a browser does not crash: reads then give `undefined` and writes are no-ops. A browser
+ * may block storage (a sandboxed frame, blocked site data) or refuse a write (quota), and then
+ * reaching or using `localStorage` throws: a read that fails reads as absent and a write that
+ * fails is skipped, with one warning per store rather than one per call.
+ *
+ * A write notifies this store's own subscribers; a `storage` event (another tab changed a key
+ * under the prefix) notifies them too. The store listens for that event on `window` only while
+ * it has subscribers, so a store that is dropped leaves no listener behind; still, create one
+ * once (outside render, or in `useMemo`) rather than on every render.
+ */
+export function localStorageStore(prefix: string): ArgStore {
+  const hasWindow = typeof window !== 'undefined';
+  const listeners = new Set<() => void>();
+  const storageKey = (key: string) => `${prefix}.${key}`;
+  // `null` means "another tab cleared the whole storage" (localStorage.clear()): every key under
+  // the prefix may have changed, so this counts as ours too.
+  const isOwnStorageKey = (key: string | null) => key === null || key.startsWith(`${prefix}.`);
+  const onStorage = (event: StorageEvent) => {
+    if (isOwnStorageKey(event.key)) listeners.forEach((listener) => listener());
+  };
+
+  let warned = false;
+  /** Runs a use of localStorage; if it throws, warns (the first time for this store) and gives `undefined`. */
+  const guarded = <T>(what: string, use: (storage: Storage) => T): T | undefined => {
+    try {
+      return use(window.localStorage);
+    } catch (error) {
+      if (!warned) {
+        warned = true;
+        console.warn(
+          `localStorageStore('${prefix}'): cannot ${what} localStorage (${String(error)}); `
+          + 'failing reads read as absent and failing writes are skipped, without further warnings',
+        );
+      }
+      return undefined;
+    }
+  };
+
+  return {
+    read(key) {
+      if (!hasWindow) return undefined;
+      return guarded('read', (storage) => storage.getItem(storageKey(key))) ?? undefined;
+    },
+    write(changes, _method) {
+      if (!hasWindow) return;
+      for (const { key, raw } of changes) {
+        guarded('write', (storage) => {
+          if (raw === undefined) storage.removeItem(storageKey(key));
+          else storage.setItem(storageKey(key), raw);
+        });
+      }
+      listeners.forEach((listener) => listener());
+    },
+    subscribe(listener) {
+      if (hasWindow && listeners.size === 0) window.addEventListener('storage', onStorage);
+      listeners.add(listener);
+      return () => {
+        if (!listeners.delete(listener)) return;
+        if (hasWindow && listeners.size === 0) window.removeEventListener('storage', onStorage);
+      };
+    },
+  };
+}

package/src/normalizeText.ts

@@ -0,0 +1,7 @@
+/**
+ * A key for accent- and case-insensitive comparison of labels (the tree hook's search,
+ * Taskmaster's): decompose, strip the combining marks, lower-case. No quaesitor dependency.
+ */
+export function normalizeText(text: string): string {
+  return text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
+}