@weasel-js/labkit 1.6.1 → 1.7.0

package/src/canvas/cameraRegistry.ts

@@ -0,0 +1,86 @@
+import { useActionsRegistry } from '@weasel-js/core';
+import { createContext, useContext, useEffect } from 'react';
+import type { CameraView } from './CameraInput';
+
+/**
+ * Cameras by key, for chrome that acts on a camera it does not contain — the
+ * lab's zoom controls, which drive whichever trial has the focus.
+ */
+export interface CameraRegistry {
+  /** Publish `camera` under `key` and return its release. Registrants for one
+   *  key stack, newest live. */
+  register(key: string, camera: CameraView): () => void;
+  get(key: string): CameraView | null;
+  /** Fires after any register or release. Shaped for `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+}
+
+export function createCameraRegistry(): CameraRegistry {
+  const stacks = new Map<string, CameraView[]>();
+  const listeners = new Set<() => void>();
+  const notify = (): void => {
+    for (const l of listeners) l();
+  };
+  return {
+    register(key, camera) {
+      const stack = stacks.get(key) ?? [];
+      stack.push(camera);
+      stacks.set(key, stack);
+      notify();
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        const cur = stacks.get(key);
+        const i = cur?.lastIndexOf(camera) ?? -1;
+        if (!cur || i === -1) return;
+        cur.splice(i, 1);
+        if (cur.length === 0) stacks.delete(key);
+        notify();
+      };
+    },
+    get: (key) => stacks.get(key)?.at(-1) ?? null,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/** The registry a lab keeps its trials' cameras in. */
+export const CameraRegistryContext = createContext<CameraRegistry | null>(null);
+
+/** Where a camera publishes itself. The host binds the key — a trial provides
+ *  one that registers under its own id — so the camera needs no name. */
+export const CameraPublishContext = createContext<((camera: CameraView) => () => void) | null>(
+  null,
+);
+
+/** Publish `camera` to the host in scope for as long as the caller is mounted,
+ *  and again each time its input scope becomes the active one — a registry
+ *  key stacks newest-live, so the camera last used is the one chrome reaches.
+ *  Call it inside the camera's scope. */
+export function usePublishCamera(camera: CameraView): void {
+  const publish = useContext(CameraPublishContext);
+  const actions = useActionsRegistry();
+  useEffect(() => {
+    if (!publish) return;
+    let release = publish(camera);
+    if (!actions) return release;
+    let was = actions.isActive();
+    const off = actions.subscribe(() => {
+      const now = actions.isActive();
+      if (now && !was) {
+        release();
+        release = publish(camera);
+      }
+      was = now;
+    });
+    return () => {
+      off();
+      release();
+    };
+  }, [publish, camera, actions]);
+}

package/src/canvas/cameraZoom.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import type { CameraView } from './CameraInput';
+import { zoomCameraTo } from './cameraZoom';
+
+function fakeCamera(
+  host: { width: number; height: number } | null,
+  range = { min: 0.1, max: 32 },
+): CameraView & {
+  view: { x: number; y: number; scale: { x: number; y: number } };
+} {
+  const cam = {
+    view: { x: 0, y: 0, scale: { x: 1, y: 1 } },
+    get: () => cam.view,
+    set: (v: { x: number; y: number; scale: { x: number; y: number } }) => {
+      const s = Math.min(range.max, Math.max(range.min, v.scale.x));
+      cam.view = { ...v, scale: { x: s, y: s } };
+    },
+    hostSize: () => host,
+    zoomRange: () => range,
+  };
+  return cam;
+}
+
+describe('zoomCameraTo', () => {
+  it('keeps the middle of the view where it was', () => {
+    const cam = fakeCamera({ width: 200, height: 100 });
+    zoomCameraTo(cam, 2);
+    // The world point under the screen middle (100, 50) is still under it.
+    expect(cam.view.x + 100 / cam.view.scale.x).toBeCloseTo(100);
+    expect(cam.view.y + 50 / cam.view.scale.y).toBeCloseTo(50);
+    expect(cam.view.scale.x).toBe(2);
+  });
+
+  it('anchors at the origin when the camera cannot measure its host', () => {
+    const cam = fakeCamera(null);
+    zoomCameraTo(cam, 2);
+    expect(cam.view).toEqual({ x: 0, y: 0, scale: { x: 2, y: 2 } });
+  });
+
+  it('stops at the edge of the camera range', () => {
+    const cam = fakeCamera({ width: 200, height: 100 }, { min: 0.5, max: 1.2 });
+    zoomCameraTo(cam, 5);
+    expect(cam.view.scale.x).toBe(1.2);
+    expect(cam.view.x + 100 / cam.view.scale.x).toBeCloseTo(100);
+  });
+});

package/src/canvas/cameraZoom.ts

@@ -0,0 +1,24 @@
+import type { View } from '@weasel-js/core';
+import type { CameraView } from './CameraInput';
+
+/** `view` at `scale`, about the screen point `at`. */
+export function atScale(view: View, scale: number, at: { x: number; y: number }): View {
+  return {
+    x: view.x + at.x / view.scale.x - at.x / scale,
+    y: view.y + at.y / view.scale.y - at.y / scale,
+    scale: { x: scale, y: scale },
+  };
+}
+
+/** The middle of the camera's host, in its own screen space; the origin when it cannot measure. */
+export function viewMiddle(camera: CameraView): { x: number; y: number } {
+  const size = camera.hostSize?.();
+  return size ? { x: size.width / 2, y: size.height / 2 } : { x: 0, y: 0 };
+}
+
+/** Zoom `camera` to `zoom` about the middle of its view, within its range. */
+export function zoomCameraTo(camera: CameraView, zoom: number): void {
+  const { min, max } = camera.zoomRange();
+  const scale = Math.min(max, Math.max(min, zoom));
+  camera.set(atScale(camera.get(), scale, viewMiddle(camera)));
+}

package/src/canvas/index.ts

@@ -1,9 +1,14 @@
-export type { CameraContextValue, CameraInputProps, CameraViewOptions } from './CameraInput';
+export type {
+  CameraContextValue,
+  CameraInputProps,
+  CameraView,
+  CameraViewOptions,
+  ZoomRange,
+} from './CameraInput';
 export {
   CameraContext,
   CameraInput,
   CameraScope,
-  CameraScopeContext,
   STAGE_VIEW_ID,
   useCameraView,
 } from './CameraInput';
@@ -15,6 +20,13 @@ export type { CanvasStackContextValue, CanvasStackSurface } from './CanvasStackC
 export { CanvasStackContext } from './CanvasStackContext';
 export type { ZoomAtOptions } from './camera';
 export { centerOn, zoomAt } from './camera';
+export type { CameraRegistry } from './cameraRegistry';
+export {
+  CameraPublishContext,
+  CameraRegistryContext,
+  createCameraRegistry,
+  usePublishCamera,
+} from './cameraRegistry';
 export { clampZoomAbout, frameLocalToWorld, fromCameraView, toCameraView } from './cameraView';
 export { screenToWorld, worldToScreen } from './canvasCoords';
 export { LinkedCursor } from './LinkedCursor';

package/src/canvas/sharedScope.test.tsx

@@ -0,0 +1,94 @@
+/**
+ * Two cameras under one host scope — what a trial gives every canvas inside it,
+ * and what a forge index page puts several of in. Each must answer only for
+ * itself: the newest must not take the others' gestures.
+ */
+
+import { act, render } from '@testing-library/react';
+import { WeaselProvider } from '@weasel-js/core';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import type { ViewTransform } from '../instrument/types';
+import { CanvasStack } from './CanvasStack';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+  const proto = HTMLElement.prototype as unknown as Record<string, unknown>;
+  proto.setPointerCapture = vi.fn();
+  proto.releasePointerCapture = vi.fn();
+  proto.hasPointerCapture = vi.fn(() => true);
+});
+
+function pointer(el: Element, type: string, x: number, y: number, buttons = 1) {
+  el.dispatchEvent(
+    new PointerEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      pointerId: 1,
+      clientX: x,
+      clientY: y,
+      button: 0,
+      buttons,
+    }),
+  );
+}
+
+const VIEW: ViewTransform = { zoom: 1, pan: { x: 0, y: 0 } };
+
+function mountTwo() {
+  const views = [vi.fn(), vi.fn()];
+  const taps = [vi.fn(), vi.fn()];
+  const { container } = render(
+    <WeaselProvider isolate>
+      {(['a', 'b'] as const).map((id, i) => (
+        <CanvasStack
+          key={id}
+          layers={[]}
+          view={VIEW}
+          onViewChange={views[i]}
+          onHitTest={taps[i]}
+          width={100}
+          height={100}
+        />
+      ))}
+    </WeaselProvider>,
+  );
+  const hosts = [...container.querySelectorAll<HTMLElement>('.lk-canvas-stack')];
+  return { hosts, views, taps };
+}
+
+describe('cameras sharing a host scope', () => {
+  it('pans the camera the drag began on, not the newest', () => {
+    const { hosts, views } = mountTwo();
+    act(() => {
+      pointer(hosts[0]!, 'pointerdown', 50, 50);
+      pointer(hosts[0]!, 'pointermove', 60, 55);
+      pointer(hosts[0]!, 'pointermove', 80, 70);
+      pointer(hosts[0]!, 'pointerup', 80, 70, 0);
+    });
+    expect(views[0]).toHaveBeenCalled();
+    expect(views[1]).not.toHaveBeenCalled();
+  });
+
+  it('reports a tap to the canvas it landed on', () => {
+    const { hosts, taps } = mountTwo();
+    act(() => {
+      pointer(hosts[0]!, 'pointerdown', 50, 50);
+      pointer(hosts[0]!, 'pointerup', 50, 50, 0);
+    });
+    expect(taps[0]).toHaveBeenCalledTimes(1);
+    expect(taps[1]).not.toHaveBeenCalled();
+  });
+
+  it('still drives the newest camera from its own canvas', () => {
+    const { hosts, views } = mountTwo();
+    act(() => {
+      pointer(hosts[1]!, 'pointerdown', 50, 50);
+      pointer(hosts[1]!, 'pointermove', 80, 70);
+      pointer(hosts[1]!, 'pointerup', 80, 70, 0);
+    });
+    expect(views[1]).toHaveBeenCalled();
+    expect(views[0]).not.toHaveBeenCalled();
+  });
+});

package/src/chrome/ChromeRegions.stories.tsx

@@ -72,6 +72,7 @@ export default meta;
 type Story = StoryObj<typeof Lab>;
 
 export const EveryRegion: Story = {
+  tags: ['gallery'],
   args: {
     instruments: [FullInstrument],
     defaultInstrument: 'Every Region',

package/src/chrome/regions/PaletteRegion.less

@@ -4,11 +4,4 @@
   padding: var(--wzl-space-xs);
   border-right: var(--wzl-border-w) solid var(--wzl-line-subtle);
   background: var(--wzl-surface-sunken);
-
-  // labkit's `:where(button)` default sets an explicit height, and because
-  // :where() carries no specificity it also wins over ToolButton, which sizes
-  // itself from padding.
-  button {
-    height: auto;
-  }
 }

package/src/chrome/regions/SidebarRegion.less

@@ -23,6 +23,7 @@
   --_s-tone: var(--wzl-tone, var(--_s-surface));
   --_s-accent: var(--wzl-tone);
   --_s-title-font: var(--wzl-font-display);
+  --_s-title-weight: var(--wzl-font-weight-bold);
   --_s-title-size: var(--wzl-font-size-sm);
   --_s-title-case: uppercase;
   --_s-title-tracking: 0.08em;
@@ -36,6 +37,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-scope-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-scope-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-scope-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-scope-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-scope-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-scope-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-scope-title-tracking, 0.08em);
@@ -49,6 +51,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-aside-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-aside-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-aside-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-aside-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-aside-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-aside-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-aside-title-tracking, 0.08em);
@@ -62,6 +65,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-advanced-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-advanced-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-advanced-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-advanced-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-advanced-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-advanced-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-advanced-title-tracking, 0.08em);
@@ -75,6 +79,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-debug-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-debug-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-debug-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-debug-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-debug-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-debug-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-debug-title-tracking, 0.08em);
@@ -88,6 +93,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-danger-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-danger-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-danger-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-danger-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-danger-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-danger-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-danger-title-tracking, 0.08em);
@@ -101,6 +107,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-notice-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-notice-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-notice-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-notice-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-notice-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-notice-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-notice-title-tracking, 0.08em);
@@ -114,6 +121,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-important-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-important-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-important-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-important-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-important-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-important-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-important-title-tracking, 0.08em);
@@ -127,6 +135,7 @@
   --_s-tone: var(--wzl-tone, var(--wzl-stance-preview-tone, var(--_s-surface)));
   --_s-accent: var(--wzl-stance-preview-accent, var(--wzl-tone));
   --_s-title-font: var(--wzl-stance-preview-title-font, var(--wzl-font-display));
+  --_s-title-weight: var(--wzl-stance-preview-title-weight, var(--wzl-font-weight-bold));
   --_s-title-size: var(--wzl-stance-preview-title-size, var(--wzl-font-size-sm));
   --_s-title-case: var(--wzl-stance-preview-title-case, uppercase);
   --_s-title-tracking: var(--wzl-stance-preview-title-tracking, 0.08em);
@@ -174,12 +183,13 @@
 .lk-sidebar-section__head {
   flex: 1;
   width: 100%;
-  padding: var(--wzl-space-xs);
+  padding: var(--wzl-space-xs) var(--wzl-space-sm);
   border: 0;
   background: transparent;
   color: var(--_s-title-color);
   font-family: var(--_s-title-font);
   font-size: var(--_s-title-size);
+  font-weight: var(--_s-title-weight);
   letter-spacing: var(--_s-title-tracking);
   text-align: left;
   text-transform: var(--_s-title-case);
@@ -193,5 +203,5 @@
 // The section body is the only thing that insets a panel — the panels
 // themselves carry no padding, so this is the whole gutter.
 .lk-sidebar-section__body {
-  padding: 0 var(--wzl-space-xs) var(--wzl-space-xs);
+  padding: 0 var(--wzl-space-sm) var(--wzl-space-sm);
 }

package/src/config/builder.test.ts

@@ -1,3 +1,4 @@
+import { compact } from '@weasel-js/quantity';
 import { describe, expect, it } from 'vitest';
 import { auto } from './auto';
 import { f } from './builder';
@@ -37,7 +38,7 @@ describe('builder', () => {
   });
 
   it('annotates a number with a display format', () => {
-    expect(f.number(0).format('compact').annotations.format).toBe('compact');
+    expect(f.number(0).display(compact()).annotations.display).toEqual(compact());
   });
 
   it('keeps a custom node kind across a chain', () => {

package/src/config/builder.ts

@@ -1,4 +1,5 @@
-import type { PrefLeaf, PrefNumberFormat, PrefNumberUnit } from '@weasel-js/ui';
+import type { Display } from '@weasel-js/quantity';
+import type { PrefLeaf, PrefNumberUnit } from '@weasel-js/ui';
 import { type Auto, isAuto } from './auto';
 import type {
   Annotations,
@@ -141,10 +142,10 @@ export class NumberNode extends BaseNode<number> {
     return this.ann({ suffix });
   }
 
-  /** Show the value in a named format — `'compact'` reads `2.00M`. Presentation
-   *  only: the stored value stays a plain number, and a typed `2.5m` reads back. */
-  format(format: PrefNumberFormat): this {
-    return this.ann({ format });
+  /** Show, speak and read the value through a display — `compact()` reads
+   *  `2.00M`. Presentation only: the stored value stays a plain number. */
+  display(display: Display): this {
+    return this.ann({ display });
   }
 
   /**
@@ -286,6 +287,12 @@ export class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
   showIf(predicate: (config: Record<string, unknown>) => boolean): GroupNode<S> {
     return this.with(this.annotations, { ...this.options, showIf: predicate });
   }
+
+  /** Put a button on the group's heading that returns every value beneath it
+   *  to its default, leaving the rest of the config alone. */
+  resettable(): GroupNode<S> {
+    return this.with(this.annotations, { ...this.options, resettable: true });
+  }
 }
 
 /** Every default in a shape, nested the way the shape is. */

package/src/config/fromConfigField.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import type { ConfigField } from '../controls/types';
 import { fromConfigFields } from './fromConfigField';
+import { schemaNodeAtPath } from './path';
 import { isLeafVisible } from './visible';
 
 const leaf = (fields: ConfigField[], k: string) =>
@@ -76,6 +77,19 @@ describe('fromConfigFields', () => {
     ]);
     expect(Object.keys(r.group.children)).toEqual(['z', 'a']);
   });
+
+  it('files a dotted key at the path it names, the one config reads and writes use', () => {
+    const r = fromConfigFields([
+      { type: 'number', key: 'pose.x', label: 'X', default: 0 },
+      { type: 'number', key: 'pose.y', label: 'Y', default: 0 },
+      { type: 'checkbox', key: 'on', label: 'On', default: true },
+    ]);
+    expect(schemaNodeAtPath(r.group, 'pose.x')).toMatchObject({ kind: 'number', name: 'X' });
+    expect(schemaNodeAtPath(r.group, 'pose.y')).toMatchObject({ kind: 'number', name: 'Y' });
+    // The intermediate is headless: a flat field list never asked for a heading.
+    expect(schemaNodeAtPath(r.group, 'pose')).toMatchObject({ name: '' });
+    expect(Object.keys(r.group.children)).toEqual(['pose', 'on']);
+  });
 });
 
 describe('isLeafVisible', () => {

package/src/config/fromConfigField.ts

@@ -1,4 +1,4 @@
-import type { PrefLeaf } from '@weasel-js/ui';
+import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
 import type { ConfigField } from '../controls/types';
 import type { LeafPatch, ResolvedConfig } from './types';
 
@@ -53,9 +53,13 @@ function toLeaf(field: ConfigField): LeafPatch {
  *
  * Rules do not run here: a hand-written `ConfigField` already states its label
  * and control, which is everything the rule chain would have inferred.
+ *
+ * A dotted `key` is a config path, as it is to every read and write, so its
+ * leaf is filed under headless groups at that path rather than as one child
+ * whose name contains dots — which no path lookup would find.
  */
 export function fromConfigFields(fields: readonly ConfigField[]): ResolvedConfig {
-  const children: Record<string, PrefLeaf> = {};
+  const root: PrefGroup = { name: '', children: {} };
   for (const field of fields) {
     const patch = toLeaf(field);
     for (const key of Object.keys(patch)) {
@@ -63,10 +67,20 @@ export function fromConfigFields(fields: readonly ConfigField[]): ResolvedConfig
         delete (patch as Record<string, unknown>)[key];
       }
     }
-    children[field.key] = { ...patch, default: field.default } as PrefLeaf;
+    const segments = field.key.split('.');
+    const leafKey = segments.pop() as string;
+    let group = root;
+    for (const segment of segments) {
+      const existing = group.children[segment];
+      if (existing === undefined || !('children' in existing) || 'kind' in existing) {
+        group.children[segment] = { name: '', children: {} };
+      }
+      group = group.children[segment] as PrefGroup;
+    }
+    group.children[leafKey] = { ...patch, default: field.default } as PrefLeaf;
   }
   return {
-    group: { name: '', children },
+    group: root,
     sections: [],
     showIf: new Map(),
     renderers: {},

package/src/config/path.ts

@@ -1,3 +1,4 @@
+import { isPlainObject } from '@weasel-js/core';
 import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
 
 /**
@@ -9,11 +10,7 @@ import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
 /** 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;
-}
+export const isRecord = isPlainObject;
 
 /** The value at a dotted path. `undefined` when a segment is missing or the
  *  walk hits something that is not a record. */

package/src/config/resolve.ts

@@ -27,6 +27,7 @@ interface Sink {
   showIf: Map<string, (config: Record<string, unknown>) => boolean>;
   renderers: Record<string, ControlRenderer>;
   dialogs: Record<string, DialogSpec>;
+  resettable: Set<string>;
   chain: readonly ConfigRule[];
 }
 
@@ -48,6 +49,7 @@ export function resolveConfigSchema<TC>(
     showIf: new Map(),
     renderers: {},
     dialogs: {},
+    resettable: new Set(),
     chain: [...rules, ...builtinRules],
   };
   const group = resolveShape(schema.nodes, '', '', sink);
@@ -57,6 +59,7 @@ export function resolveConfigSchema<TC>(
     showIf: sink.showIf,
     renderers: sink.renderers,
     dialogs: sink.dialogs,
+    resettable: sink.resettable,
   };
 }
 
@@ -89,6 +92,7 @@ function resolveShape(shape: ConfigShape, at: string, name: string, sink: Sink):
       if (section.pack !== undefined && spec.pack === undefined) spec.pack = section.pack;
     }
     if (predicate) sink.showIf.set(path, predicate);
+    if (isConfigBranch(entry) && entry.options.resettable) sink.resettable.add(path);
     if (!isConfigBranch(entry) && entry.options.render) sink.renderers[path] = entry.options.render;
     if (!isConfigBranch(entry) && entry.options.dialog) sink.dialogs[path] = entry.options.dialog;
   }

package/src/config/types.ts

@@ -1,10 +1,5 @@
-import type {
-  PrefGroup,
-  PrefLeaf,
-  PrefNumberFormat,
-  PrefNumberUnit,
-  PrefRenderer,
-} from '@weasel-js/ui';
+import type { Display } from '@weasel-js/quantity';
+import type { PrefGroup, PrefLeaf, PrefNumberUnit, PrefRenderer } from '@weasel-js/ui';
 import type { ReactNode } from 'react';
 
 /**
@@ -18,6 +13,9 @@ export type ControlRenderer = PrefRenderer;
 export interface ConfigOption {
   value: string;
   label: string;
+  /** A glyph in weasel-ui's icon set (`IconName`). A segmented row draws it in
+   *  place of `label`, which stays the accessible name and becomes the tooltip. */
+  icon?: string;
 }
 
 /** Everything a leaf can carry beyond its kind and default. A flat union of
@@ -32,8 +30,8 @@ export interface Annotations {
   max?: number;
   step?: number;
   suffix?: string;
-  /** How a number's value is shown. `compact` abbreviates from a thousand up. */
-  format?: PrefNumberFormat;
+  /** How a number's value shows, speaks and reads back — `compact()` reads `2.00M`. */
+  display?: Display;
   /** 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;
@@ -107,6 +105,9 @@ export interface ResolvedConfig {
   renderers: Readonly<Record<string, ControlRenderer>>;
   /** Node-level `.dialog` rows, keyed by path. */
   dialogs: Readonly<Record<string, DialogSpec>>;
+  /** Paths of the groups marked `.resettable()`, whose heading carries a
+   *  button that puts every value beneath it back to its default. */
+  resettable?: ReadonlySet<string>;
 }
 
 /** Options for a row drawn as a button that opens a dialog. */
@@ -162,6 +163,9 @@ export interface BranchOptions {
   /** Show this node only while the predicate holds. On a group it hides the
    *  whole subtree; the values stay in config either way. */
   showIf?: (config: Record<string, unknown>) => boolean;
+  /** Put a button on this group's heading that returns every value beneath it
+   *  to its default. Groups only. */
+  resettable?: boolean;
 }
 
 /** A group's own annotations: what it is called and, optionally, why. */

package/src/controls/ControlPanel.less

@@ -17,7 +17,7 @@
 .lk-pair-cell {
   display: inline-flex;
   align-items: center;
-  gap: var(--wzl-space-3, 6px);
+  gap: var(--wzl-space-3);
   min-width: 0;
 }
 

package/src/controls/ControlPanel.stories.tsx

@@ -1,5 +1,6 @@
 import { ANGLE_RADIANS, prefUnit } from '@weasel-js/core';
 import type { Meta, StoryObj } from '@weasel-js/forge';
+import { compact } from '@weasel-js/quantity';
 import { type PrefNumberUnit, PropertyRow } from '@weasel-js/ui';
 import { useState } from 'react';
 import { f } from '../config/builder';
@@ -278,7 +279,7 @@ export const Presentation: Story = {
 
 const inline = f.schema({
   folderPad: f.number(1.1).range(0, 4).step(0.1).label('Folder pad'),
-  glyphs: f.number(1_000_000).range(0, 2_000_000).format('compact'),
+  glyphs: f.number(1_000_000).range(0, 2_000_000).display(compact()),
   names: f.number(60).range(0, 100),
   labels: f.number(0).range(0, 100),
   placement: f.enum('spread', ['spread', 'stack', 'ring']),
@@ -337,7 +338,7 @@ const sidebarSliders = f.schema({
   pad: f.number(0.5).range(0, 4).step(0.25).label('Window pad'),
   folderPad: f.number(1).range(0, 4).step(0.1).label('Folder pad'),
   levels: f.number(2).range(0, 6).step(1).label('Levels'),
-  glyphs: f.number(1_000_000).range(0, 2_000_000).step(2000).format('compact').label('Glyphs'),
+  glyphs: f.number(1_000_000).range(0, 2_000_000).step(2000).display(compact()).label('Glyphs'),
   names: f.number(40).range(0, 200).step(5).label('Names'),
   labels: f.number(0).range(0, 30).step(1).label('Labels'),
   text: f.number(100).range(50, 250).step(5).unit(shownIn('%')).label('Text'),