@weasel-js/labkit 1.4.2 → 1.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -110,15 +110,15 @@
     "dev:annotate": "LABKIT_EXAMPLE=annotate-lab vite"
   },
   "peerDependencies": {
+    "@weasel-js/core": "1.4.4",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/core": "1.4.2",
-    "@weasel-js/loupe": "1.4.2",
-    "@weasel-js/svg": "1.4.2",
-    "@weasel-js/theme": "1.4.2",
-    "@weasel-js/ui": "1.4.2",
+    "@weasel-js/loupe": "1.4.4",
+    "@weasel-js/svg": "1.4.4",
+    "@weasel-js/theme": "1.4.4",
+    "@weasel-js/ui": "1.4.4",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -129,7 +129,7 @@
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "1.4.2",
+    "@weasel-js/modes": "1.4.4",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/ExportMenu.test.tsx

@@ -75,6 +75,22 @@ describe('<ExportMenu>', () => {
     );
   });
 
+  // jsdom resolves neither var() nor color-mix(), so where the panel mounted
+  // is the proxy for whether it reads the lab's tokens at all.
+  it('opens inside the lab root, not on the body', () => {
+    const { store } = spied();
+    render(
+      <div className="lk-root" data-wzl-portal-host="" data-testid="lk-root">
+        <AnnotationsContext.Provider value={store}>
+          <ExportMenu />
+        </AnnotationsContext.Provider>
+      </div>,
+    );
+    open();
+    const panel = document.querySelector('.lk-export__panel');
+    expect(panel?.closest('[data-testid="lk-root"]')).toBe(screen.getByTestId('lk-root'));
+  });
+
   it('says so when a capture fails rather than doing nothing visible', async () => {
     const { store, capture } = spied();
     capture.mockRejectedValueOnce(new Error('the capture canvas is tainted'));

package/src/annotations/ExportMenu.tsx

@@ -51,10 +51,6 @@ async function copy(result: CaptureResult): Promise<void> {
  */
 export function ExportMenu() {
   const marks = useAnnotationsOptional();
-  // The anchor doubles as the portal target lookup: a React Aria popover
-  // portals to `document.body` by default, which is outside the element
-  // labkit paints its theme tokens onto — `--wzl-surface` does not exist
-  // there and the panel renders unthemed.
   const [anchor, setAnchor] = useState<HTMLSpanElement | null>(null);
   const [open, setOpen] = useState(false);
   const [target, setTarget] = useState<string | null>(null);
@@ -99,7 +95,6 @@ export function ExportMenu() {
         onOpenChange={setOpen}
         onDismiss={() => setOpen(false)}
         placement="bottom end"
-        UNSTABLE_portalContainer={anchor?.closest('.lk-root') ?? undefined}
         aria-labelledby={titleId}
       >
         <div className="lk-export__panel">

package/src/annotations/frac.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { fracContains, fracIntersects, fracToWorld, roundFrac, worldToFrac } from './frac';
+import { fracContains, fracEncloses, fracToWorld, roundFrac, worldToFrac } from './frac';
 import type { FracRect } from './types';
 
 const CONTENT = { w: 256, h: 170 };
@@ -51,9 +51,9 @@ describe('fraction hit geometry', () => {
     expect(fracContains(box, { x: 0.18, y: 0.3 }, 0.05)).toBe(true);
   });
 
-  it('intersects only a box that wholly contains it', () => {
-    expect(fracIntersects({ x: 0, y: 0, w: 1, h: 1 }, box)).toBe(true);
+  it('encloses only a box that lies wholly inside', () => {
+    expect(fracEncloses({ x: 0, y: 0, w: 1, h: 1 }, box)).toBe(true);
     // Overlapping is not containing: a marquee takes what it encloses.
-    expect(fracIntersects({ x: 0.4, y: 0.4, w: 0.4, h: 0.4 }, box)).toBe(false);
+    expect(fracEncloses({ x: 0.4, y: 0.4, w: 0.4, h: 0.4 }, box)).toBe(false);
   });
 });

package/src/annotations/frac.ts

@@ -55,8 +55,9 @@ export function fracContains(box: FracRect, pt: FracPoint, tol = 0): boolean {
 }
 
 /** Whether `outer` wholly encloses `inner`. A marquee takes what it encloses,
- *  not what it grazes — brushing selection is a different gesture. */
-export function fracIntersects(outer: FracRect, inner: FracRect): boolean {
+ *  not what it grazes — brushing selection is a different gesture, and this
+ *  answers false for two rects that merely overlap. */
+export function fracEncloses(outer: FracRect, inner: FracRect): boolean {
   return (
     inner.x >= outer.x &&
     inner.y >= outer.y &&

package/src/annotations/index.ts

@@ -4,7 +4,7 @@ export type { MarkDrawOptions } from './drawOne';
 export { createMarkDrawOne, resolveMarkStyle } from './drawOne';
 export { ExportMenu } from './ExportMenu';
 export type { WorldRect } from './frac';
-export { fracContains, fracIntersects, fracToWorld, roundFrac, worldToFrac } from './frac';
+export { fracContains, fracEncloses, fracToWorld, roundFrac, worldToFrac } from './frac';
 export type { HistoryScene } from './history';
 export { MarkHistory } from './history';
 export type { MarkListProps } from './MarkList';

package/src/annotations/store.ts

@@ -7,7 +7,7 @@ import {
 } from '@weasel-js/core';
 import { captureTarget } from './capture';
 import type { WorldRect } from './frac';
-import { fracContains, fracIntersects, fracToWorld, roundFrac, worldToFrac } from './frac';
+import { fracContains, fracEncloses, fracToWorld, roundFrac, worldToFrac } from './frac';
 import { MarkHistory } from './history';
 import { isStale as isStaleAgainst, seenFrom } from './staleness';
 import type {
@@ -197,7 +197,7 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
     },
 
     within(target, box: FracRect) {
-      return marksOn(target).filter((a) => fracIntersects(box, a.frac));
+      return marksOn(target).filter((a) => fracEncloses(box, a.frac));
     },
 
     isStale(a, config) {

package/src/annotations/svgNodes.ts

@@ -1,5 +1,4 @@
 import type { DrawCommand, FillStyle, Stroke } from '@weasel-js/core';
-import { resolveStrokeWidth } from '@weasel-js/core';
 import type { SvgNode, SvgPaint, SvgStroke } from '@weasel-js/svg';
 import { type MarkStyle, markCommands, type PaintableMark } from './paint';
 
@@ -23,7 +22,7 @@ function toSvgPaint(paint: FillStyle | undefined): SvgPaint {
 function toSvgStroke(stroke: Stroke): SvgStroke {
   return {
     paint: toSvgPaint(stroke.paint),
-    width: resolveStrokeWidth(stroke.width ?? 1, 1),
+    width: stroke.width ?? 1,
     ...(stroke.cap ? { cap: stroke.cap } : {}),
     ...(stroke.join ? { join: stroke.join } : {}),
     ...(stroke.dash ? { dash: [...stroke.dash] } : {}),

package/src/config/builder.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { f } from './builder';
+import type { ConfigOf, ConfigPath, ValueAtPath } from './types';
 
 describe('builder', () => {
   it('carries kind and default', () => {
@@ -63,7 +64,7 @@ describe('builder', () => {
       .section('Advanced')
       .showIf((c) => c.showGrid === true)
       .render(() => null);
-    expect(n.options.section).toBe('Advanced');
+    expect(n.options.section).toEqual({ label: 'Advanced' });
     expect(n.options.showIf?.({ showGrid: true })).toBe(true);
     expect(n.options.render).toBeTypeOf('function');
     expect(n.annotations).toEqual({});
@@ -91,8 +92,61 @@ describe('builder / node option collisions', () => {
     ];
     for (const node of nodes) {
       expect(typeof node.options).toBe('object');
-      expect(node.section('S').options.section).toBe('S');
+      expect(node.section('S').options.section).toEqual({ label: 'S' });
       expect(node.render(() => null).options.render).toBeTypeOf('function');
     }
   });
 });
+
+describe('builder / groups', () => {
+  it('f.group nests its children under the key', () => {
+    const s = f.schema({
+      showGrid: f.boolean(true),
+      grid: f.group({ size: f.number(20), color: f.color('#fff') }),
+    });
+    expect(s.defaults()).toEqual({
+      showGrid: true,
+      grid: { size: 20, color: '#fff' },
+    });
+  });
+
+  it('nests groups within groups', () => {
+    const s = f.schema({ a: f.group({ b: f.group({ c: f.number(1) }) }) });
+    expect(s.defaults()).toEqual({ a: { b: { c: 1 } } });
+  });
+
+  it('chains a group label and description immutably', () => {
+    const base = f.group({ size: f.number(20) });
+    const a = base.label('Grid').describe('How the grid is drawn');
+    expect(a.annotations.name).toBe('Grid');
+    expect(a.annotations.description).toBe('How the grid is drawn');
+    expect(base.annotations.name).toBeUndefined();
+  });
+
+  it('holds a group section and showIf off the annotation bag', () => {
+    const g = f
+      .group({ size: f.number(20) })
+      .section('Advanced')
+      .showIf((c) => c.showGrid === true);
+    expect(g.options.section).toEqual({ label: 'Advanced' });
+    expect(g.options.showIf?.({ showGrid: true })).toBe(true);
+    expect(g.annotations).toEqual({});
+  });
+});
+
+describe('builder / nested types', () => {
+  // Compile-level: these annotations are the assertion, and tsc is what runs
+  // it. A flat `InferConfig` would not give `c.grid.size` a type at all.
+  it('infers a nested config type and the paths into it', () => {
+    const schema = f.schema({
+      showGrid: f.boolean(true),
+      grid: f.group({ size: f.number(20), color: f.color('#fff') }),
+    });
+    type Config = ConfigOf<typeof schema>;
+    const c: Config = schema.defaults();
+    const size: number = c.grid.size;
+    const path: ConfigPath<Config> = 'grid.size';
+    const value: ValueAtPath<Config, 'grid.size'> = 40;
+    expect([size, path, value]).toEqual([20, 'grid.size', 40]);
+  });
+});

package/src/config/builder.ts

@@ -1,14 +1,24 @@
 import type { PrefLeaf } from '@weasel-js/ui';
 import type {
   Annotations,
+  BranchAnnotations,
+  BranchOptions,
+  ConfigBranch,
+  ConfigEntry,
   ConfigNode,
   ConfigOption,
   ConfigSchema,
+  ConfigShape,
   ControlRenderer,
   InferConfig,
   NodeOptions,
 } from './types';
 
+/** Whether a schema entry is a branch rather than a leaf. */
+export function isConfigBranch(entry: ConfigEntry): entry is ConfigBranch {
+  return 'children' in entry;
+}
+
 /** 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> {
@@ -61,9 +71,10 @@ abstract class BaseNode<T> implements ConfigNode<T> {
     return this.ann({ pair });
   }
 
-  /** Render under a named section heading. */
-  section(section: string): this {
-    return this.opt({ section });
+  /** 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 {
+    return this.opt({ section: { label, ...opts } });
   }
 
   /** Show this row only while the predicate holds. Presentational — the value
@@ -174,6 +185,55 @@ class CustomNode<T> extends BaseNode<T> {
   }
 }
 
+/**
+ * A branch of the schema: its children nest under its key, so a leaf inside
+ * 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> {
+  constructor(
+    readonly children: S,
+    readonly annotations: Readonly<BranchAnnotations> = {},
+    readonly options: Readonly<BranchOptions> = {},
+  ) {}
+
+  private with(annotations: BranchAnnotations, options: BranchOptions): GroupNode<S> {
+    return new GroupNode(this.children, annotations, options);
+  }
+
+  /** Heading for the group's rows. Defaults to the key, title-cased. */
+  label(name: string): GroupNode<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. */
+  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> {
+    return this.with(this.annotations, { ...this.options, section: { label, ...opts } });
+  }
+
+  /** Show this group only while the predicate holds. Presentational — every
+   *  value beneath it stays in config and the instrument still reads it. */
+  showIf(predicate: (config: Record<string, unknown>) => boolean): GroupNode<S> {
+    return this.with(this.annotations, { ...this.options, showIf: predicate });
+  }
+}
+
+/** Every default in a shape, nested the way the shape is. */
+function shapeDefaults(shape: ConfigShape): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(shape)) {
+    out[key] = isConfigBranch(entry) ? shapeDefaults(entry.children) : entry.default;
+  }
+  return out;
+}
+
 const expand = <T extends string>(
   options: readonly T[] | readonly ConfigOption[],
 ): readonly ConfigOption[] =>
@@ -187,6 +247,8 @@ const expand = <T extends string>(
  * const config = f.schema({
  *   showGrid: f.boolean(true),
  *   cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing'),
+ *   // Nested: read and written at `grid.color`.
+ *   grid: f.group({ color: f.color('#ffffff') }),
  * })
  * ```
  */
@@ -208,19 +270,17 @@ export const f = {
    *  states a convention like "every `*Color` key is a color picker". */
   value: <T>(def: T): ValueNode<T> => new ValueNode(def),
 
+  /** A branch: its children nest under this key, so `grid: f.group({ size })`
+   *  puts the value at `config.grid.size` and addresses it as `'grid.size'`.
+   *  Groups nest as deeply as the schema wants. */
+  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 } : {}),
 
-  /** Collect leaves into an instrument's config. */
-  schema<S extends Record<string, ConfigNode>>(nodes: S): ConfigSchema<InferConfig<S>> {
-    return {
-      nodes,
-      defaults: () => {
-        const out: Record<string, unknown> = {};
-        for (const [key, node] of Object.entries(nodes)) out[key] = node.default;
-        return out as InferConfig<S>;
-      },
-    };
+  /** Collect leaves and groups into an instrument's config. */
+  schema<S extends ConfigShape>(nodes: S): ConfigSchema<InferConfig<S>> {
+    return { nodes, defaults: () => shapeDefaults(nodes) as InferConfig<S> };
   },
 };

package/src/config/index.ts

@@ -1,22 +1,37 @@
-export { f } from './builder';
+export { f, isConfigBranch } from './builder';
 export { fromConfigFields } from './fromConfigField';
+export {
+  fillConfigDefaults,
+  hasConfigPath,
+  schemaNodeAtPath,
+  valueAtPath,
+  withValueAtPath,
+} from './path';
 export { resolveConfigSchema } from './resolve';
 export { applyRules, builtinRules, titleCase } from './rules';
 export type {
   Annotations,
+  BranchAnnotations,
+  BranchOptions,
+  ConfigBranch,
+  ConfigEntry,
   ConfigNode,
   ConfigOf,
   ConfigOption,
+  ConfigPath,
   ConfigRule,
   ConfigRuleContext,
   ConfigSchema,
+  ConfigShape,
   ControlRenderer,
+  EntryValue,
   InferConfig,
   LeafPatch,
   NodeOptions,
   NodeValue,
   ResolvedConfig,
   SectionSpec,
+  ValueAtPath,
 } from './types';
 export { useConfigSchema } from './useConfigSchema';
 export { isLeafVisible } from './visible';

package/src/config/path.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { fillConfigDefaults, hasConfigPath, valueAtPath, withValueAtPath } from './path';
+
+describe('valueAtPath', () => {
+  it('reads a single segment', () => {
+    expect(valueAtPath({ a: 1 }, 'a')).toBe(1);
+  });
+
+  it('reads down a nested path', () => {
+    expect(valueAtPath({ grid: { size: 20 } }, 'grid.size')).toBe(20);
+  });
+
+  it('returns undefined for a missing segment', () => {
+    expect(valueAtPath({ grid: {} }, 'grid.size')).toBeUndefined();
+    expect(valueAtPath({}, 'grid.size')).toBeUndefined();
+  });
+
+  it('returns undefined when the walk hits a non-object', () => {
+    expect(valueAtPath({ grid: 3 }, 'grid.size')).toBeUndefined();
+    expect(valueAtPath(null, 'a')).toBeUndefined();
+  });
+});
+
+describe('hasConfigPath', () => {
+  it('tells a missing key from one holding undefined', () => {
+    expect(hasConfigPath({ a: undefined }, 'a')).toBe(true);
+    expect(hasConfigPath({}, 'a')).toBe(false);
+  });
+
+  it('walks a nested path', () => {
+    expect(hasConfigPath({ grid: { size: 20 } }, 'grid.size')).toBe(true);
+    expect(hasConfigPath({ grid: { size: 20 } }, 'grid.color')).toBe(false);
+    expect(hasConfigPath({ grid: 3 }, 'grid.size')).toBe(false);
+  });
+});
+
+describe('withValueAtPath', () => {
+  it('writes a single segment without touching the input', () => {
+    const before = { a: 1, b: 2 };
+    const after = withValueAtPath(before, 'a', 99);
+    expect(after).toEqual({ a: 99, b: 2 });
+    expect(before).toEqual({ a: 1, b: 2 });
+  });
+
+  it('copies every object on the way down', () => {
+    const before = { grid: { size: 20, color: '#fff' }, other: { keep: true } };
+    const after = withValueAtPath(before, 'grid.size', 40);
+    expect(after.grid).toEqual({ size: 40, color: '#fff' });
+    expect(before.grid.size).toBe(20);
+    expect(after.grid).not.toBe(before.grid);
+    // Untouched branches keep their identity, so a memo keyed on one holds.
+    expect(after.other).toBe(before.other);
+  });
+
+  it('creates a missing intermediate branch', () => {
+    expect(withValueAtPath({} as Record<string, unknown>, 'grid.size', 40)).toEqual({
+      grid: { size: 40 },
+    });
+  });
+
+  it('replaces a non-object standing where a branch belongs', () => {
+    expect(withValueAtPath({ grid: 3 } as Record<string, unknown>, 'grid.size', 40)).toEqual({
+      grid: { size: 40 },
+    });
+  });
+});
+
+describe('fillConfigDefaults', () => {
+  it('takes the stored value wherever it has one', () => {
+    expect(fillConfigDefaults({ a: 1 }, { a: 0, b: 2 })).toEqual({ a: 1, b: 2 });
+  });
+
+  it('fills a whole branch a stored config never had', () => {
+    expect(fillConfigDefaults({ showGrid: false }, { showGrid: true, grid: { size: 20 } })).toEqual(
+      {
+        showGrid: false,
+        grid: { size: 20 },
+      },
+    );
+  });
+
+  it('fills a gap inside a branch the stored config half-holds', () => {
+    expect(
+      fillConfigDefaults({ grid: { size: 40 } }, { grid: { size: 20, color: '#fff' } }),
+    ).toEqual({ grid: { size: 40, color: '#fff' } });
+  });
+
+  it('keeps a key the defaults no longer mention', () => {
+    expect(fillConfigDefaults({ gridSize: 40 }, { grid: { size: 20 } })).toEqual({
+      gridSize: 40,
+      grid: { size: 20 },
+    });
+  });
+
+  it('leaves the stored config untouched', () => {
+    const stored = { grid: { size: 40 } };
+    fillConfigDefaults(stored, { grid: { size: 20, color: '#fff' } });
+    expect(stored).toEqual({ grid: { size: 40 } });
+  });
+
+  it('takes a stored array whole rather than merging it element-wise', () => {
+    expect(fillConfigDefaults({ tags: ['a'] }, { tags: ['x', 'y'] })).toEqual({ tags: ['a'] });
+  });
+
+  it('fills from defaults when the stored config is not a record', () => {
+    expect(fillConfigDefaults(undefined, { a: 1 })).toEqual({ a: 1 });
+    expect(fillConfigDefaults(7, { a: 1 })).toEqual({ a: 1 });
+  });
+});

package/src/config/path.ts

@@ -0,0 +1,76 @@
+import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
+
+/**
+ * Reading and writing a config tree by dotted path. A schema's leaves address
+ * their values this way, so a leaf nested under `f.group` and a flat one are
+ * reached by exactly the same call.
+ */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The value at a dotted path. `undefined` when a segment is missing or the
+ *  walk hits something that is not a record. */
+export function valueAtPath(config: unknown, path: string): unknown {
+  let cur = config;
+  for (const segment of path.split('.')) {
+    if (!isRecord(cur)) return undefined;
+    cur = cur[segment];
+  }
+  return cur;
+}
+
+/** Whether a dotted path is actually present, which a `undefined` value is
+ *  not enough to tell you. */
+export function hasConfigPath(config: unknown, path: string): boolean {
+  let cur = config;
+  for (const segment of path.split('.')) {
+    if (!isRecord(cur) || !(segment in cur)) return false;
+    cur = cur[segment];
+  }
+  return true;
+}
+
+function writeIn(node: unknown, segments: readonly string[], value: unknown): unknown {
+  const [head, ...rest] = segments;
+  if (head === undefined) return value;
+  const base = isRecord(node) ? node : {};
+  return { ...base, [head]: rest.length === 0 ? value : writeIn(base[head], rest, value) };
+}
+
+/** A copy of `config` with `value` written at a dotted path. Every record on
+ *  the way down is copied and the input is left alone; a missing — or
+ *  non-record — intermediate is replaced with the branch the path implies. */
+export function withValueAtPath<T>(config: T, path: string, value: unknown): T {
+  return writeIn(config, path.split('.'), value) as T;
+}
+
+/**
+ * `stored` with every gap filled from `defaults`, down the whole tree.
+ *
+ * This is how a config written before its schema grew a branch still loads:
+ * the branch arrives at its defaults instead of `undefined`, and a key the
+ * defaults no longer mention is kept rather than dropped, so nothing is lost
+ * to a schema change the author has not finished making.
+ */
+export function fillConfigDefaults<T>(stored: unknown, defaults: T): T {
+  if (!isRecord(defaults)) return (stored === undefined ? defaults : stored) as T;
+  const base = isRecord(stored) ? stored : {};
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(defaults)) {
+    out[key] = fillConfigDefaults(base[key], value);
+  }
+  return out as T;
+}
+
+/** A node in a resolved schema tree, by dotted path. Structural rather than
+ *  `isPrefLeaf` so this stays free of a runtime import. */
+export function schemaNodeAtPath(group: PrefGroup, path: string): PrefLeaf | PrefGroup | undefined {
+  let node: PrefLeaf | PrefGroup | undefined = group;
+  for (const segment of path.split('.')) {
+    if (node === undefined || !('children' in node)) return undefined;
+    node = node.children[segment];
+  }
+  return node;
+}