@weasel-js/labkit 1.4.4 → 1.5.1

package/README.md

@@ -36,7 +36,7 @@ Annotations are on the `pre` tag until the next stable release:
 ## A lab
 
 ```tsx
-import { type ConfigOf, defineInstrument, f, Lab, localStorageAdapter } from '@weasel-js/labkit';
+import { type ConfigOf, defineInstrument, f, Lab } from '@weasel-js/labkit';
 import '@weasel-js/labkit/styles.css';
 
 const config = f.schema({
@@ -64,13 +64,24 @@ export function App() {
       instruments={[Histogram]}
       defaultInstrument="Histogram"
       title="Histogram"
-      storage={localStorageAdapter}
       storageKey="histogram-lab"
     />
   );
 }
 ```
 
+`storageKey` makes the lab persist: its trials, snapshots, layout and mode
+survive a reload and stay in step across tabs. It persists to IndexedDB — or
+localStorage, with a warning, where IndexedDB will not open — and `storage`
+names another substrate: `localStorageAdapter`, `sessionStorageAdapter`,
+`urlHashAdapter`, or your own `StorageAdapter` over a server. The lab renders
+`fallback` while it loads. Leave `storageKey` off and nothing persists.
+
+A widget's own state persists the same way through `usePersistedState(name,
+initial)`, which is `useState` whose value survives a reload — kept per trial
+inside one, and plain `useState` wherever no `<Lab>` or `<Persistence>` is
+above it.
+
 `f.schema` states the config once — values, types and controls — and the trial
 renders the settings panel from it. `render` returns the instrument's own DOM;
 returning `null` alongside `canvas` means the canvas layers are the whole
@@ -88,6 +99,43 @@ A stored config missing something its schema has since gained — a whole nested
 group included — is filled from the instrument's defaults as it loads, so
 growing a schema never strands a saved trial or a snapshot.
 
+### Auto
+
+A field can be **auto**: nobody is pinning it, and the instrument decides what
+it should be. Shift-click a row in the settings panel, or click the pin dot
+beside its label, and the control draws ghosted at whatever the value resolved
+to. Shift-click again — or just grab the control — and it pins back at the
+value it was holding all along.
+
+`auto` is a value, so it goes wherever a config value goes:
+
+```ts
+import { auto, f } from '@weasel-js/labkit';
+
+const config = f.schema({
+  width: f.number(432),
+  gap: f.number(12).auto((c) => (c.width as number) / 24),
+  cols: f.number(3).initial(auto),
+  seed: f.number(1).manual(),
+});
+
+setConfig('gap', auto);
+addTrial('demo', { gap: auto });
+```
+
+`.auto(fn)` attaches a resolver: the instrument reads the computed value rather
+than writing `?? compute()` itself, and the ghosted control has a real number to
+draw. Without one, an auto field simply reads `undefined`. `.initial(auto)`
+opens the field auto instead of pinned at its default. **`.manual()` is the one
+worth knowing about** — it opts a field out entirely, no dot and no gesture,
+which is what you want for a value the instrument cannot receive as `undefined`,
+like a color going straight to a uniform.
+
+Nothing stores the sentinel. It is normalized at every boundary into the
+trial's set of unpinned paths, and the pinned value stays in the config
+underneath, so un-pinning loses nothing and Reset returns the trial to the auto
+fields it opened on.
+
 ## Capabilities
 
 A capability is a field on the instrument. Declaring it is what makes the trial
@@ -211,7 +259,7 @@ needs importing, and the token values arrive through the provider:
 import { interstellarTheme } from '@weasel-js/labkit';
 import { ThemeProvider } from '@weasel-js/theme/react';
 
-<ThemeProvider theme={interstellarTheme} mode="dark">…</ThemeProvider>
+<ThemeProvider theme={interstellarTheme} selection={{ mode: 'dark' }}>…</ThemeProvider>
 ```
 
 Style your own surfaces against the `--wzl-*` tokens so they follow the mode the
@@ -292,13 +340,13 @@ npm run build          # dist/ for publish
 npm run docs:dev       # VitePress on docs/ (docs:build to render it)
 ```
 
-Storybook is built at the repo root: `npm run storybook` from there covers every
-package.
+The forge workshop runs at the repo root: `npm run dev:forge` from there covers
+every package's stories, labkit's included.
 
 ## Documentation
 
 - [Docs site](https://orochi235.github.io/weasel/labkit/)
 - [Recipes](https://orochi235.github.io/weasel/labkit/RECIPES) — composition patterns
 - [Agent guide](https://orochi235.github.io/weasel/labkit/AGENTS) — a map of the source
-- [Storybook](https://orochi235.github.io/weasel/docs/ui/storybook/)
+- [Component workshop](https://orochi235.github.io/weasel/docs/ui/forge/)
 - [Design spec](https://github.com/orochi235/weasel/blob/main/packages/labkit/docs/superpowers/specs/2026-04-26-labkit-design.md)

package/dist/_dts/{CanvasStackContext-kTEZvEgE.d.ts → CanvasStackContext-CJNMS6mz.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { RefObject } from 'react';
-import { V as ViewTransform, W as WorldFrame } from './frac-z7ker2Vx.js';
+import { k as ViewTransform, W as WorldFrame } from './frac-B4okC2lX.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */

package/dist/_dts/{PrefsForm.d-DDHFANkc.d.ts → PrefsForm.d-DPy9I8It.d.ts}

@@ -10,6 +10,10 @@ interface PrefRenderContext {
     /** Current value — `values` at `path`, falling back to `pref.default`. */
     value: unknown;
     setValue: (value: unknown) => void;
+    /** Whether this leaf is currently auto — not pinned, computed by the owner. */
+    auto: boolean;
+    /** Toggle this leaf's auto state. */
+    setAuto: (next: boolean) => void;
 }
 /**
  * Renders the control cell for one preference leaf. Returning `null`