@weasel-js/labkit 1.4.4 → 1.5.1

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';
 
@@ -35,6 +36,10 @@ describe('builder', () => {
     expect(n.annotations.suffix).toBe('px');
   });
 
+  it('annotates a number with a display format', () => {
+    expect(f.number(0).format('compact').annotations.format).toBe('compact');
+  });
+
   it('keeps a custom node kind across a chain', () => {
     const n = f.custom('vector2', { x: 0 }).label('Offset');
     expect(n.kind).toBe('vector2');
@@ -150,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 } 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. */
@@ -21,7 +23,7 @@ export function isConfigBranch(entry: ConfigEntry): entry is ConfigBranch {
 
 /** Shared chaining surface. Every method clones, so a node can be reused as a
  *  base for several leaves without one bleeding into the next. */
-abstract class BaseNode<T> implements ConfigNode<T> {
+export abstract class BaseNode<T> implements ConfigNode<T> {
   abstract readonly kind: string | null;
 
   // `default` is a reserved word in a parameter position, so the field is
@@ -72,8 +74,9 @@ 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,9 +90,33 @@ 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 takes no pin dot and ignores the gesture. */
+  manual(): this {
+    return this.opt({ manual: true });
+  }
 }
 
-class NumberNode extends BaseNode<number> {
+export class NumberNode extends BaseNode<number> {
   readonly kind = 'number';
 
   /** Bound the value. A number with both bounds renders as a slider. */
@@ -107,6 +134,22 @@ class NumberNode extends BaseNode<number> {
     return this.ann({ suffix });
   }
 
+  /** Show the value in a named format — `'compact'` reads `2.0M`. Presentation
+   *  only: the stored value stays a plain number, and a typed `2.5m` reads back. */
+  format(format: PrefNumberFormat): this {
+    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' });
@@ -118,17 +161,16 @@ class NumberNode extends BaseNode<number> {
   }
 }
 
-class BooleanNode extends BaseNode<boolean> {
+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' });
   }
 }
 
-class StringNode extends BaseNode<string> {
+export class StringNode extends BaseNode<string> {
   readonly kind = 'string';
 
   placeholder(placeholder: string): this {
@@ -145,11 +187,17 @@ class StringNode extends BaseNode<string> {
   }
 }
 
-class ColorNode 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 });
+  }
 }
 
-class EnumNode<T extends string> extends BaseNode<T> {
+export class EnumNode<T extends string> extends BaseNode<T> {
   readonly kind = 'enum';
 
   /** Render as a segmented control rather than a select. */
@@ -165,12 +213,12 @@ class EnumNode<T extends string> extends BaseNode<T> {
 }
 
 /** A leaf whose kind the rule chain decides. */
-class ValueNode<T> extends BaseNode<T> {
+export class ValueNode<T> extends BaseNode<T> {
   readonly kind = null;
 }
 
 /** A leaf of a kind labkit does not ship a row for. */
-class CustomNode<T> extends BaseNode<T> {
+export class CustomNode<T> extends BaseNode<T> {
   constructor(
     readonly kind: string,
     defaultValue: T,
@@ -190,7 +238,7 @@ class CustomNode<T> extends BaseNode<T> {
  * one is read and written at a dotted path. Distinct from `.section()`, which
  * puts a heading over sibling leaves and leaves their paths alone.
  */
-class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
+export class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
   constructor(
     readonly children: S,
     readonly annotations: Readonly<BranchAnnotations> = {},
@@ -214,7 +262,7 @@ class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
   }
 
   /** 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 } });
   }
 
@@ -276,8 +324,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/declarationEmit.fixture.ts

@@ -0,0 +1,11 @@
+import { f } from './builder';
+
+export const flat = f.schema({ n: f.number(1).range(0, 4), s: f.string('x').label('S') });
+
+export const grouped = f.schema({
+  g: f.group({ on: f.boolean(true).toggle(), e: f.enum('a', ['a', 'b']).radio() }).label('G'),
+});
+
+export const node = f.number(1).slider();
+
+export const group = f.group({ c: f.color('#fff'), v: f.value(1), k: f.custom('k', 'x') });

package/src/config/declarationEmit.test.ts

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+const root = resolve(__dirname, '../../../..');
+const fixture = resolve(__dirname, 'declarationEmit.fixture.ts');
+
+/** Emits declarations for one file under the root tsconfig and returns every diagnostic, formatted. */
+function declarationDiagnostics(file: string): string[] {
+  const parsed = ts.getParsedCommandLineOfConfigFile(
+    resolve(root, 'tsconfig.json'),
+    {},
+    {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic: (d) => {
+        throw new Error(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+      },
+    },
+  );
+  if (!parsed) throw new Error('could not read the root tsconfig');
+  const options: ts.CompilerOptions = {
+    ...parsed.options,
+    noEmit: false,
+    declaration: true,
+    emitDeclarationOnly: true,
+    declarationMap: false,
+    sourceMap: false,
+    incremental: false,
+    tsBuildInfoFile: undefined,
+    types: [],
+  };
+  const program = ts.createProgram({ rootNames: [file], options });
+  const source = program.getSourceFile(file);
+  if (!source) throw new Error(`${file} is not in the program`);
+  const emitted = program.emit(source, () => {}, undefined, true);
+  const diagnostics = [
+    ...program.getSyntacticDiagnostics(source),
+    ...program.getSemanticDiagnostics(source),
+    ...emitted.diagnostics,
+  ];
+  return diagnostics.map((d) => {
+    const text = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+    return d.file ? `${d.file.fileName}: TS${d.code} ${text}` : `TS${d.code} ${text}`;
+  });
+}
+
+describe('config schema declarations', () => {
+  it('emit for exported schemas, groups and nodes', () => {
+    expect(declarationDiagnostics(fixture)).toEqual([]);
+  }, 60_000);
+});

package/src/config/entry.test.ts

@@ -0,0 +1,46 @@
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const IMPORT =
+  /^\s*(?:import|export)\s+(?!type\b)[^'"]*from\s+['"]([^'"]+)['"]|^\s*import\s+['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)/gm;
+
+const isFile = (path: string) => statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
+
+function walk(file: string, seen = new Set<string>()): Set<string> {
+  if (seen.has(file)) return seen;
+  seen.add(file);
+  const source = readFileSync(file, 'utf8');
+  for (const match of source.matchAll(IMPORT)) {
+    const spec = match[1] ?? match[2] ?? match[3];
+    if (!spec?.startsWith('.')) continue;
+    const base = resolve(dirname(file), spec.replace(/\.js$/, ''));
+    const candidates = [
+      resolve(dirname(file), spec),
+      `${base}.ts`,
+      `${base}.tsx`,
+      resolve(base, 'index.ts'),
+      resolve(base, 'index.tsx'),
+    ];
+    const hit = candidates.find(isFile);
+    // An import the walk cannot follow would let a stylesheet behind it pass unseen.
+    if (!hit) throw new Error(`${file}: cannot resolve ${spec}`);
+    walk(hit, seen);
+  }
+  return seen;
+}
+
+describe('@weasel-js/labkit/config', () => {
+  it('reaches no stylesheet', () => {
+    const files = [...walk(resolve(__dirname, 'index.ts'))];
+    expect(files.filter((f) => /\.(less|css)$/.test(f))).toEqual([]);
+  });
+
+  it('is published as an entry', async () => {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
+    expect(pkg.exports['./config']).toEqual({
+      types: './dist/config/index.d.ts',
+      import: './dist/config/index.js',
+    });
+  });
+});

package/src/config/index.ts

@@ -1,4 +1,18 @@
-export { f, isConfigBranch } from './builder';
+export { type Auto, auto, isAuto } from './auto';
+export { autoPathsOf, resolveAutoConfig } from './autoConfig';
+export {
+  BaseNode,
+  BooleanNode,
+  ColorNode,
+  CustomNode,
+  EnumNode,
+  f,
+  GroupNode,
+  isConfigBranch,
+  NumberNode,
+  StringNode,
+  ValueNode,
+} from './builder';
 export { fromConfigFields } from './fromConfigField';
 export {
   fillConfigDefaults,
@@ -34,4 +48,5 @@ export type {
   ValueAtPath,
 } from './types';
 export { useConfigSchema } from './useConfigSchema';
+export { useResolvedConfig } from './useResolvedConfig';
 export { isLeafVisible } from './visible';

package/src/config/nodeClasses.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { f, GroupNode, NumberNode } from './index';
+
+describe('config node classes', () => {
+  it('are exported as values', () => {
+    expect(typeof NumberNode).toBe('function');
+    expect(typeof GroupNode).toBe('function');
+    expect(f.number(1)).toBeInstanceOf(NumberNode);
+    expect(f.group({ n: f.number(1) })).toBeInstanceOf(GroupNode);
+  });
+
+  it('can be extended', () => {
+    class Mine extends NumberNode {}
+    const node = new Mine(2);
+    expect(node).toBeInstanceOf(NumberNode);
+    expect(node.default).toBe(2);
+  });
+});

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;
 }