@weasel-js/labkit 1.5.0 → 1.5.2

package/src/config/autoConfig.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import { auto } from './auto';
+import { autoPathsOf, resolveAutoConfig } from './autoConfig';
+import { f } from './builder';
+import { resolveConfigSchema } from './resolve';
+
+const schema = f.schema({
+  width: f.number(432),
+  gap: f.number(12).auto((c) => (c.width as number) / 24),
+  cols: f.number(3).initial(auto),
+  grid: f.group({ size: f.number(8).auto(() => 99) }),
+});
+const resolved = resolveConfigSchema(schema);
+const raw = { width: 432, gap: 12, cols: 3, grid: { size: 8 } };
+
+describe('autoPathsOf', () => {
+  it('lists the dotted paths a schema starts auto', () => {
+    expect(autoPathsOf(resolved)).toEqual(['cols']);
+  });
+
+  it('reaches leaves nested under a group', () => {
+    const nested = resolveConfigSchema(
+      f.schema({ grid: f.group({ size: f.number(8).initial(auto) }) }),
+    );
+    expect(autoPathsOf(nested)).toEqual(['grid.size']);
+  });
+});
+
+describe('resolveAutoConfig', () => {
+  it('leaves a config with nothing auto exactly as it was', () => {
+    expect(resolveAutoConfig(resolved, raw, new Set())).toEqual(raw);
+  });
+
+  it('replaces an auto path that has a resolver with the computed value', () => {
+    const out = resolveAutoConfig(resolved, raw, new Set(['gap']));
+    expect(out.gap).toBe(18);
+    expect(out.width).toBe(432);
+  });
+
+  it('deletes an auto path that has no resolver', () => {
+    const out = resolveAutoConfig(resolved, raw, new Set(['cols'])) as Record<string, unknown>;
+    expect('cols' in out).toBe(false);
+  });
+
+  it('resolves a leaf nested under a group', () => {
+    const out = resolveAutoConfig(resolved, raw, new Set(['grid.size'])) as {
+      grid: { size: number };
+    };
+    expect(out.grid.size).toBe(99);
+  });
+
+  it('lets one resolver read another auto path, already resolved', () => {
+    const chained = resolveConfigSchema(
+      f.schema({
+        a: f.number(1).auto(() => 10),
+        b: f.number(2).auto((c) => (c.a as number) * 3),
+      }),
+    );
+    const out = resolveAutoConfig(chained, { a: 1, b: 2 }, new Set(['a', 'b'])) as {
+      a: number;
+      b: number;
+    };
+    expect(out).toEqual({ a: 10, b: 30 });
+  });
+
+  it('resolves a dependency declared after its dependent', () => {
+    const backward = resolveConfigSchema(
+      f.schema({
+        b: f.number(2).auto((c) => (c.a as number) * 3),
+        a: f.number(1).auto(() => 10),
+      }),
+    );
+    const out = resolveAutoConfig(backward, { a: 1, b: 2 }, new Set(['a', 'b'])) as {
+      a: number;
+      b: number;
+    };
+    expect(out).toEqual({ a: 10, b: 30 });
+  });
+
+  it('throws naming the path when resolvers cycle', () => {
+    const cyclic = resolveConfigSchema(
+      f.schema({
+        a: f.number(1).auto((c) => (c.b as number) + 1),
+        b: f.number(2).auto((c) => (c.a as number) + 1),
+      }),
+    );
+    expect(() => resolveAutoConfig(cyclic, { a: 1, b: 2 }, new Set(['a', 'b']))).toThrow(/cycle/i);
+    expect(() => resolveAutoConfig(cyclic, { a: 1, b: 2 }, new Set(['a', 'b']))).toThrow(/"a"/);
+  });
+
+  it('throws on a resolver that reads its own path', () => {
+    const selfish = resolveConfigSchema(
+      f.schema({ a: f.number(1).auto((c) => (c.a as number) + 1) }),
+    );
+    expect(() => resolveAutoConfig(selfish, { a: 1 }, new Set(['a']))).toThrow(/cycle/i);
+  });
+
+  it('ignores an auto path the schema does not have', () => {
+    expect(resolveAutoConfig(resolved, raw, new Set(['gone']))).toEqual(raw);
+  });
+
+  it('does not mutate the config it was given', () => {
+    const before = structuredClone(raw);
+    resolveAutoConfig(resolved, raw, new Set(['gap', 'grid.size']));
+    expect(raw).toEqual(before);
+  });
+});

package/src/config/autoConfig.ts

@@ -0,0 +1,153 @@
+import { isPrefLeaf, type PrefGroup, type PrefLeaf } from '@weasel-js/ui';
+import { isAuto } from './auto';
+import { isRecord, withValueAtPath } from './path';
+import type { ResolvedConfig } from './types';
+
+type Resolver = (config: Record<string, unknown>) => unknown;
+
+/** Reads a labkit-only extra off a resolved leaf. `PrefLeaf` has no field for
+ *  these; they ride as extra keys and survive the resolve walk. */
+function extra<T>(leaf: PrefLeaf, key: string): T | undefined {
+  return (leaf as unknown as Record<string, T | undefined>)[key];
+}
+
+/** Every leaf in a resolved schema, in schema order, with its dotted path. */
+function* leaves(group: PrefGroup, at = ''): Generator<[string, PrefLeaf]> {
+  for (const [key, child] of Object.entries(group.children)) {
+    const path = at === '' ? key : `${at}.${key}`;
+    if (isPrefLeaf(child)) yield [path, child];
+    else yield* leaves(child, path);
+  }
+}
+
+/** The dotted paths a schema declares as starting auto — every leaf that said
+ *  `.initial(auto)`. This is what seeds a new trial's unpinned set. */
+export function autoPathsOf(resolved: ResolvedConfig): string[] {
+  const out: string[] = [];
+  for (const [path, leaf] of leaves(resolved.group)) {
+    if (extra<boolean>(leaf, 'unpinned')) out.push(path);
+  }
+  return out;
+}
+
+/**
+ * The config an instrument reads: the stored one, with every unpinned path
+ * either computed by its resolver or removed.
+ *
+ * Resolution is demand-driven — a resolver reading another unpinned path
+ * forces that one first, whatever order the schema declared them in — so a
+ * cycle is a real cycle and not an ordering accident.
+ */
+export function resolveAutoConfig<TC>(
+  resolved: ResolvedConfig,
+  config: TC,
+  autoPaths: ReadonlySet<string>,
+): TC {
+  if (autoPaths.size === 0) return config;
+
+  const resolvers = new Map<string, Resolver | undefined>();
+  for (const [path, leaf] of leaves(resolved.group)) {
+    if (autoPaths.has(path)) resolvers.set(path, extra<Resolver>(leaf, 'autoResolve'));
+  }
+  if (resolvers.size === 0) return config;
+
+  // Drop first, so a resolver reading a still-unresolved auto path sees
+  // `undefined` rather than a stale pinned value it would silently believe.
+  let out = config as unknown as Record<string, unknown>;
+  for (const path of resolvers.keys()) out = dropAtPath(out, path);
+
+  const inFlight = new Set<string>();
+  const done = new Set<string>();
+
+  const need = (path: string): void => {
+    if (done.has(path)) return;
+    if (inFlight.has(path)) {
+      throw new Error(`[labkit] auto resolver cycle at "${path}"`);
+    }
+    const resolve = resolvers.get(path);
+    if (!resolve) {
+      done.add(path);
+      return;
+    }
+    inFlight.add(path);
+    try {
+      // Read `out` only after the resolver has run: it forces its own
+      // dependencies, and each of those replaced `out`.
+      const value = resolve(demand(() => out, resolvers, need));
+      out = withValueAtPath(out, path, value);
+    } finally {
+      inFlight.delete(path);
+    }
+    done.add(path);
+  };
+
+  for (const path of resolvers.keys()) need(path);
+  return out as unknown as TC;
+}
+
+/**
+ * The config a resolver reads. A top-level key that is itself unpinned is
+ * forced before it is handed back, which is what makes declaration order
+ * irrelevant and turns a genuine loop into a named error.
+ *
+ * Only top-level keys are trapped: a resolver reaching `c.grid.size` gets the
+ * already-dropped branch, and a nested auto path it depends on resolves by
+ * schema order alone.
+ */
+function demand(
+  read: () => Record<string, unknown>,
+  resolvers: ReadonlyMap<string, Resolver | undefined>,
+  need: (path: string) => void,
+): Record<string, unknown> {
+  return new Proxy(read(), {
+    get(_target, key) {
+      if (typeof key === 'string' && resolvers.has(key)) need(key);
+      return Reflect.get(read(), key);
+    },
+    has(_target, key) {
+      return Reflect.has(read(), key);
+    },
+    ownKeys() {
+      return Reflect.ownKeys(read());
+    },
+    getOwnPropertyDescriptor(_target, key) {
+      return Reflect.getOwnPropertyDescriptor(read(), key);
+    },
+  });
+}
+
+/** A copy of `config` with the dotted path removed, copying every record on
+ *  the way down. A path that is not there comes back unchanged. */
+function dropAtPath(config: Record<string, unknown>, path: string): Record<string, unknown> {
+  const [head, ...rest] = path.split('.');
+  if (head === undefined || !(head in config)) return config;
+  if (rest.length === 0) {
+    const { [head]: _dropped, ...kept } = config;
+    return kept;
+  }
+  const child = config[head];
+  if (!isRecord(child)) return config;
+  return { ...config, [head]: dropAtPath(child, rest.join('.')) };
+}
+
+/**
+ * What writing `value` at `path` makes of a trial's raw config and its set of
+ * unpinned paths. `auto` pins nothing and joins the set; any other value is
+ * written and leaves it. Both the store and the chrome go through this, so
+ * they cannot disagree about what a write meant.
+ */
+export function applyConfigWrite<TC>(
+  config: TC,
+  autoPaths: readonly string[],
+  path: string,
+  value: unknown,
+): { config: TC; autoPaths: readonly string[] } {
+  if (isAuto(value)) {
+    if (autoPaths.includes(path)) return { config, autoPaths };
+    return { config, autoPaths: [...autoPaths, path] };
+  }
+  return {
+    config: withValueAtPath(config, path, value),
+    autoPaths: autoPaths.includes(path) ? autoPaths.filter((p) => p !== path) : autoPaths,
+  };
+}

package/src/config/builder.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { auto } from './auto';
 import { f } from './builder';
 import type { ConfigOf, ConfigPath, ValueAtPath } from './types';
 
@@ -154,3 +155,40 @@ describe('builder / nested types', () => {
     expect([size, path, value]).toEqual([20, 'grid.size', 40]);
   });
 });
+
+describe('auto on a node', () => {
+  it('attaches a resolver without changing the default', () => {
+    const n = f.number(12).auto((c) => (c.width as number) / 24);
+    expect(n.default).toBe(12);
+    expect(n.options.autoResolve?.({ width: 432 })).toBe(18);
+  });
+
+  it('.initial(auto) marks the node as starting unpinned', () => {
+    expect(f.number(3).initial(auto).options.unpinned).toBe(true);
+    expect(f.number(3).options.unpinned).toBeUndefined();
+  });
+
+  it('.manual() opts the node out of ever being auto', () => {
+    expect(f.number(1).manual().options.manual).toBe(true);
+  });
+
+  it('clones rather than mutating, like every other chaining method', () => {
+    const base = f.number(3);
+    const unpinned = base.initial(auto);
+    expect(base.options.unpinned).toBeUndefined();
+    expect(unpinned).not.toBe(base);
+  });
+
+  it('keeps the subclass, so kind-specific methods still chain after', () => {
+    const n = f.number(3).initial(auto).range(0, 10).suffix('px');
+    expect(n.annotations.min).toBe(0);
+    expect(n.annotations.suffix).toBe('px');
+    expect(n.options.unpinned).toBe(true);
+  });
+
+  it('rejects anything but the sentinel, for a caller TypeScript is not checking', () => {
+    const n = f.number(3) as unknown as { initial: (value: unknown) => unknown };
+    expect(() => n.initial(5)).toThrow(/takes `auto`/);
+    expect(() => n.initial(Symbol('auto'))).toThrow(/takes `auto`/);
+  });
+});

package/src/config/builder.ts

@@ -1,4 +1,5 @@
-import type { PrefLeaf, PrefNumberFormat } from '@weasel-js/ui';
+import type { PrefLeaf, PrefNumberFormat, PrefNumberUnit } from '@weasel-js/ui';
+import { type Auto, isAuto } from './auto';
 import type {
   Annotations,
   BranchAnnotations,
@@ -12,6 +13,7 @@ import type {
   ControlRenderer,
   InferConfig,
   NodeOptions,
+  SectionOption,
 } from './types';
 
 /** Whether a schema entry is a branch rather than a leaf. */
@@ -72,8 +74,9 @@ export abstract class BaseNode<T> implements ConfigNode<T> {
   }
 
   /** Render under a named section heading. `collapsed` opens the section
-   *  folded — say it on any one of the section's leaves. */
-  section(label: string, opts: { collapsed?: boolean } = {}): this {
+   *  folded, and `layout` and `pack` lay out its rows — say each on any one of
+   *  the section's leaves. */
+  section(label: string, opts: Omit<SectionOption, 'label'> = {}): this {
     return this.opt({ section: { label, ...opts } });
   }
 
@@ -87,6 +90,30 @@ export abstract class BaseNode<T> implements ConfigNode<T> {
   render(renderer: ControlRenderer): this {
     return this.opt({ render: renderer });
   }
+
+  /**
+   * Compute this leaf's value while it is auto, instead of leaving it
+   * `undefined`. The resolver is given the config with every other auto path
+   * already resolved.
+   */
+  auto(resolve: (config: Record<string, unknown>) => T): this {
+    return this.opt({ autoResolve: resolve as (c: Record<string, unknown>) => unknown });
+  }
+
+  /**
+   * Start this leaf auto rather than pinned at its default. Takes `auto` and
+   * nothing else — the constructor argument already declares the value, and a
+   * second way to say it would fight with the first.
+   */
+  initial(value: Auto): this {
+    if (!isAuto(value)) throw new Error('[labkit] .initial() takes `auto` and nothing else');
+    return this.opt({ unpinned: true });
+  }
+
+  /** Never auto. The row's label does not toggle. */
+  manual(): this {
+    return this.opt({ manual: true });
+  }
 }
 
 export class NumberNode extends BaseNode<number> {
@@ -113,6 +140,16 @@ export class NumberNode extends BaseNode<number> {
     return this.ann({ format });
   }
 
+  /**
+   * Store the value in one unit and edit it in another — radians stored,
+   * degrees typed. `min`, `max` and `step` are declared in the stored unit
+   * alongside the value, and convert with it. `prefUnit` builds one from a
+   * `UnitSystem`.
+   */
+  unit(unit: PrefNumberUnit): this {
+    return this.ann({ unit });
+  }
+
   /** Force a slider even without both bounds. */
   slider(): this {
     return this.ann({ control: 'slider' });
@@ -127,8 +164,7 @@ export class NumberNode extends BaseNode<number> {
 export class BooleanNode extends BaseNode<boolean> {
   readonly kind = 'boolean';
 
-  /** Ask for a switch. `ControlPanel` still draws a checkbox; weasel-ui's
-   *  `PrefsForm` honors the distinction. */
+  /** Ask for a switch rather than a checkbox. */
   toggle(): this {
     return this.ann({ control: 'switch' });
   }
@@ -153,6 +189,12 @@ export class StringNode extends BaseNode<string> {
 
 export class ColorNode extends BaseNode<string> {
   readonly kind = 'color';
+
+  /** The value carries alpha as `#rrggbbaa`, and the row gets an opacity
+   *  track beside the swatch. */
+  alpha(): this {
+    return this.ann({ alpha: true });
+  }
 }
 
 export class EnumNode<T extends string> extends BaseNode<T> {
@@ -212,15 +254,14 @@ export class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
     return this.with({ ...this.annotations, name }, this.options);
   }
 
-  /** Longer help text. Carried on the resolved `PrefGroup`, where weasel-ui's
-   *  `PrefsForm` draws it under the heading; `ControlPanel` has no place for
-   *  it yet and shows the heading alone. */
+  /** Longer help text. Carried on the resolved `PrefGroup`; both weasel-ui's
+   *  `PrefsForm` and `ControlPanel` draw it under the heading. */
   describe(description: string): GroupNode<S> {
     return this.with({ ...this.annotations, description }, this.options);
   }
 
   /** Render this whole group under a named section heading. */
-  section(label: string, opts: { collapsed?: boolean } = {}): GroupNode<S> {
+  section(label: string, opts: Omit<SectionOption, 'label'> = {}): GroupNode<S> {
     return this.with(this.annotations, { ...this.options, section: { label, ...opts } });
   }
 
@@ -282,8 +323,11 @@ export const f = {
   group: <const S extends ConfigShape>(children: S): GroupNode<S> => new GroupNode(children),
 
   /** A leaf of a kind a lab supplies the control for, through `controls`. */
-  custom: <T>(kind: string, def: T, validate?: (leaf: PrefLeaf) => string[]): CustomNode<T> =>
-    new CustomNode(kind, def, {}, validate ? { validate } : {}),
+  custom: <T>(
+    kind: string,
+    def: T,
+    validate?: (leaf: PrefLeaf, config: Record<string, unknown>) => string[],
+  ): CustomNode<T> => new CustomNode(kind, def, {}, validate ? { validate } : {}),
 
   /** Collect leaves and groups into an instrument's config. */
   schema<S extends ConfigShape>(nodes: S): ConfigSchema<InferConfig<S>> {

package/src/config/index.ts

@@ -1,3 +1,5 @@
+export { type Auto, auto, isAuto } from './auto';
+export { autoPathsOf, resolveAutoConfig } from './autoConfig';
 export {
   BaseNode,
   BooleanNode,
@@ -46,4 +48,5 @@ export type {
   ValueAtPath,
 } from './types';
 export { useConfigSchema } from './useConfigSchema';
+export { useResolvedConfig } from './useResolvedConfig';
 export { isLeafVisible } from './visible';

package/src/config/path.ts

@@ -6,8 +6,13 @@ import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
  * reached by exactly the same call.
  */
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A plain object a config tree can be walked into. An array, a `Date`, a
+ *  `Map` or a class instance is a leaf value: a walk that descended into one
+ *  would rebuild it as a bare `{}`. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
 }
 
 /** The value at a dotted path. `undefined` when a segment is missing or the

package/src/config/resolve.test.ts

@@ -1,5 +1,6 @@
 import type { PrefGroup } from '@weasel-js/ui';
 import { describe, expect, it } from 'vitest';
+import { auto } from './auto';
 import { f } from './builder';
 import { resolveConfigSchema } from './resolve';
 import { titleCase } from './rules';
@@ -207,4 +208,28 @@ describe('resolveConfigSchema / nested groups', () => {
     );
     expect(r.sections).toEqual([{ at: '', label: 'Advanced', paths: ['grid'] }]);
   });
+
+  it('rejects a leaf that is both manual and starts auto', () => {
+    const schema = f.schema({ seed: f.number(1).manual().initial(auto) });
+    expect(() => resolveConfigSchema(schema, [])).toThrow(/seed/);
+    expect(() => resolveConfigSchema(schema, [])).toThrow(/manual/);
+  });
+
+  it('carries autoResolve, unpinned and manual onto the resolved leaf', () => {
+    const r = resolveConfigSchema(
+      f.schema({
+        gap: f.number(12).auto(() => 18),
+        cols: f.number(3).initial(auto),
+        seed: f.number(1).manual(),
+        plain: f.number(0),
+      }),
+      [],
+    );
+    expect(typeof leafAt(r, 'gap').autoResolve).toBe('function');
+    expect(leafAt(r, 'cols').unpinned).toBe(true);
+    expect(leafAt(r, 'seed').manual).toBe(true);
+    expect(leafAt(r, 'plain').autoResolve).toBeUndefined();
+    expect(leafAt(r, 'plain').unpinned).toBeUndefined();
+    expect(leafAt(r, 'plain').manual).toBeUndefined();
+  });
 });

package/src/config/resolve.ts

@@ -76,6 +76,8 @@ function resolveShape(shape: ConfigShape, at: string, name: string, sink: Sink):
       if (section.collapsed !== undefined) {
         spec.collapsed = (spec.collapsed ?? false) || section.collapsed;
       }
+      if (section.layout !== undefined && spec.layout === undefined) spec.layout = section.layout;
+      if (section.pack !== undefined && spec.pack === undefined) spec.pack = section.pack;
     }
     if (predicate) sink.showIf.set(path, predicate);
     if (!isConfigBranch(entry) && entry.options.render) sink.renderers[path] = entry.options.render;
@@ -101,10 +103,24 @@ function resolveEntry(
       ? group
       : { ...group, description: entry.annotations.description };
   }
+  if (entry.options.manual && entry.options.unpinned) {
+    throw new Error(
+      `[labkit] "${path}" is both .manual() and .initial(auto) — a field that can never be auto cannot start auto`,
+    );
+  }
   const seed: LeafPatch = defined({
     ...entry.annotations,
     ...(entry.kind === null ? {} : { kind: entry.kind }),
   });
   const patch = applyRules(seed, { key, path, default: entry.default }, sink.chain);
-  return { ...patch, default: entry.default } as PrefLeaf;
+  const { autoResolve, unpinned, manual } = entry.options;
+  return {
+    ...patch,
+    default: entry.default,
+    // Extra keys survive onto the leaf at runtime; `ControlPanel` reads them
+    // back with its `extra<T>` helper, the same as `min`, `step` and the rest.
+    ...(autoResolve === undefined ? {} : { autoResolve }),
+    ...(unpinned === undefined ? {} : { unpinned }),
+    ...(manual === undefined ? {} : { manual }),
+  } as PrefLeaf;
 }

package/src/config/types.ts

@@ -1,4 +1,10 @@
-import type { PrefGroup, PrefLeaf, PrefNumberFormat, PrefRenderer } from '@weasel-js/ui';
+import type {
+  PrefGroup,
+  PrefLeaf,
+  PrefNumberFormat,
+  PrefNumberUnit,
+  PrefRenderer,
+} from '@weasel-js/ui';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -27,6 +33,11 @@ export interface Annotations {
   suffix?: string;
   /** How a number's value is shown. `compact` abbreviates from a thousand up. */
   format?: PrefNumberFormat;
+  /** Display-unit conversion for a number stored in a canonical unit — the
+   *  value, its bounds and its step all convert at the control's edge. */
+  unit?: PrefNumberUnit;
+  /** A color leaf's value carries alpha (`#rrggbbaa`) and its row edits it. */
+  alpha?: boolean;
   control?: string;
   options?: readonly ConfigOption[];
   placeholder?: string;
@@ -76,6 +87,10 @@ export interface SectionSpec {
    *  whether or not it was given a panel-wide `collapse`; a fold the reader
    *  has since toggled outranks it. */
   collapsed?: boolean;
+  /** Where the section's rows put their labels, over the panel's `layout`. */
+  layout?: 'block' | 'inline';
+  /** How the section packs its rows, over the panel's `pack`. */
+  pack?: 'auto' | 'pairs' | 'one-up';
 }
 
 /** A schema resolved against a set of rules: the vocabulary weasel-ui renders,
@@ -97,12 +112,27 @@ export interface ResolvedConfig {
 export interface SectionOption {
   label: string;
   collapsed?: boolean;
+  /** Where the section's rows put their labels, over the panel's `layout`. */
+  layout?: 'block' | 'inline';
+  /** How the section packs its rows, over the panel's `pack`. */
+  pack?: 'auto' | 'pairs' | 'one-up';
 }
 
 /** Per-node extras that do not belong on a `PrefLeaf`. */
 export interface NodeOptions extends BranchOptions {
   render?: ControlRenderer;
-  validate?: (leaf: PrefLeaf) => string[];
+  /** Errors for this leaf under `config`, the instrument's whole config. */
+  validate?: (leaf: PrefLeaf, config: Record<string, unknown>) => string[];
+  /** Computes this leaf's value while it is auto. Attaching one is what gives
+   *  the row a real value to pin back to and keeps the instrument off
+   *  `?? compute()`. */
+  autoResolve?: (config: Record<string, unknown>) => unknown;
+  /** The leaf starts auto rather than pinned at its default. Set by
+   *  `.initial(auto)`. */
+  unpinned?: boolean;
+  /** The leaf can never be auto: the row's label does not toggle. For a value
+   *  the instrument cannot receive as `undefined`. */
+  manual?: boolean;
 }
 
 /** What a branch can say about itself, beyond its children. */

package/src/config/useResolvedConfig.ts

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+import { resolveAutoConfig } from './autoConfig';
+import type { ResolvedConfig } from './types';
+
+const NONE: ReadonlySet<string> = new Set();
+
+/**
+ * The config an instrument reads: the stored one with every unpinned path
+ * resolved. The single place resolution happens, so `Trial` and
+ * `useTrialState` cannot disagree about what an instrument is looking at.
+ */
+export function useResolvedConfig<TC>(
+  schema: ResolvedConfig | undefined,
+  config: TC,
+  autoPaths: readonly string[] | undefined,
+): { config: TC; auto: ReadonlySet<string> } {
+  const auto = useMemo(
+    () => (autoPaths && autoPaths.length > 0 ? new Set(autoPaths) : NONE),
+    [autoPaths],
+  );
+  const resolvedConfig = useMemo(
+    () => (schema ? resolveAutoConfig(schema, config, auto) : config),
+    [schema, config, auto],
+  );
+  return { config: resolvedConfig, auto };
+}