@playgenx/components 0.2.0 → 0.2.2

package/README.md

@@ -1,62 +1,444 @@
 # `@playgenx/components`
 
-Default React 19 implementations for every entry in `DEFAULT_REGISTRY`. Pair with `@playgenx/registry` and the parser/validator pipeline.
+Default React 19 implementations for every entry in `DEFAULT_REGISTRY`.
+The components, a per-Provider reactive state store, error boundaries,
+and a CLI for inspecting state snapshots.
 
-## Install
+```bash
+npm install @playgenx/components
+```
+
+React 19 is a peer dependency — your app provides it.
+
+```jsonc
+// package.json (the bits you need)
+{
+  "dependencies": {
+    "@playgenx/components": "^0.2.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  }
+}
+```
+
+> Looking for the **renderer** (parser + tree walker)? That's a
+> separate package — `@playgenx/renderer`. This package is the
+> component library; the renderer consumes it.
+
+---
+
+## Quick start
+
+```tsx
+import {
+  Slider,
+  PlaygroundStateProvider,
+  usePlaygroundState,
+} from '@playgenx/components';
+import { useState } from 'react';
+
+// 1. Standalone, no state — works without a Provider
+export function StaticVolume() {
+  return <Slider min={0} max={10} value={4} label="Volume" />;
+}
+
+// 2. With shared state — wrap your tree
+export function VolumePanel() {
+  return (
+    <PlaygroundStateProvider initial={{ volume: 5 }}>
+      <Slider min={0} max={10} stateKey="volume" label="Volume" />
+      <VolumeReadout />
+    </PlaygroundStateProvider>
+  );
+}
 
-```sh
-pnpm add @playgenx/components react@^19 react-dom@^19
+function VolumeReadout() {
+  const state = usePlaygroundState();
+  return <span>Current: {state.get<number>('volume')}</span>;
+}
 ```
 
-React 19 is a peer dependency; this package does not bundle it.
+---
+
+## What's in the box
+
+### Components (PascalCase, React 19)
+
+Every component accepts JSON-friendly props. See `index.ts` for the
+full surface.
+
+| Component     | Purpose                                    | Notable props                  |
+|---------------|--------------------------------------------|--------------------------------|
+| `Button`      | Headless button                            | `label`, `variant`, `onClick`  |
+| `TextField`   | Controlled / uncontrolled input            | `value`, `onChange`            |
+| `Slider`      | Range input                                | `min`, `max`, `value`, `stateKey` |
+| `Chart`       | bar / line / pie SVG charts                | `kind`, `data`, `title`        |
+| `Container`   | Layout primitive                           | `padding`, `gap`               |
+| `Code`        | Inline code / `<pre><code>`                | `language`                     |
+| `Heading`     | `<h1>`–`<h6>`                              | `level`                        |
+| `Text`        | `<p>` with weight + color                  | `weight`, `color`              |
+| `Stepper`     | Multi-step reveal                          | `steps`, `initial`             |
+| `Card`        | Titled card                                | `title`, `children`            |
+| `List`        | `<ul>` / `<ol>` from array                 | `items`, `ordered`             |
+
+### State store + React glue
+
+| Export                       | What it does                                              |
+|------------------------------|-----------------------------------------------------------|
+| `createPlaygroundState(initial?)` | Create a standalone state store                      |
+| `PlaygroundStateProvider`     | Wrap your tree with a Provider                           |
+| `usePlaygroundState()`        | Read the nearest store                                    |
+| `useBoundValue(key, fb)`      | Get a live `[value, setter]` tuple (re-renders on change) |
+| `useBoundValueOrUndefined(key, fb)` | Same; returns `undefined` if no key/provider       |
+| `useStoreSnapshot()`          | Non-subscribing `{get, set, subscribe, snapshot, ...}`     |
+| `useBoundSelector(key, sel, fb)` | Live bound value with selector transform; only re-renders on slice change |
+| `useMultiBoundValue(bindings)` | Bind multiple keys; returns `Record<key, [value, setter]>` |
+| `useStateAction(action)`      | Build an `onClick` from `{set, toggle}` config             |
+
+### Pure helpers (no React, no Provider)
+
+| Export                | Returns                            |
+|-----------------------|------------------------------------|
+| `dumpState(state)`    | JSON v1 envelope (sorted keys)     |
+| `diffState(a, b)`     | `{added, changed, removed}` or null |
+| `diffSnapshots(prev, next)` | Same as `diffState` but pure  |
+| `validateStateKey(k)` | `null` if valid, error message if not |
+| `clearState(state)`   | (void) — sets every key to undefined |
+| `batch(state, fn)`    | Atomic set commit, per-key dedup    |
+
+### Error handling
 
-## What's in here
+| Export                       | Purpose                            |
+|------------------------------|------------------------------------|
+| `ArtifactErrorBoundary`      | Class-component error boundary     |
+| `ShowSource`                 | Render-prop source-toggle          |
 
-11 components, each matching a name in `@playgenx/registry`:
+### Registry
 
-- `Button` — primary / secondary / ghost variant, disabled state, click handler.
-- `TextField` — labeled controlled-or-uncontrolled input.
-- `Slider` — clamped range input with optional caption.
-- `Chart` — bar / line / pie, hand-rolled SVG, no chart library.
-- `Container` — vertical flex wrapper with padding + gap.
-- `Code` — inline or `<pre><code>` formatting, language data-attribute.
-- `Heading` — `<h1>`..`<h6>` with size-by-level, clamped.
-- `Text` — `<p>` with weight, size, color.
-- `Stepper` — multi-step reveal with previous/current/future states.
-- `Card` — bordered + shadowed wrapper with elevation prop.
-- `List` — `<ul>` or `<ol>` from an array of arbitrary values.
+| Export                  | Purpose                              |
+|-------------------------|--------------------------------------|
+| `componentMap`          | Frozen default registry (11 entries) |
+| `createRegistry(overrides)` | Returns a new frozen map        |
 
-## Use
+---
+
+## Three ways to use the state store
+
+### 1. Standalone, outside React
+
+```ts
+import { createPlaygroundState } from '@playgenx/components';
+
+const state = createPlaygroundState({ count: 0 });
+state.set('count', 5);
+state.get('count');           // 5
+state.snapshot();             // { count: 5 }
+state.subscribe('count', (v) => console.log('count is now', v));
+state.set('count', 10);       // → console.log fires on the next microtask
+```
+
+### 2. React tree with a Provider
 
 ```tsx
-import { Button, Container, Heading, Text, componentMap } from '@playgenx/components';
-import { DEFAULT_REGISTRY, findSchema } from '@playgenx/registry';
+import { PlaygroundStateProvider, useBoundValue } from '@playgenx/components';
 
-function App() {
+function VolumeControl() {
+  // Live-bound: writes to state on change, re-renders on external writes
+  const [volume, setVolume] = useBoundValue<number>('volume', 50);
   return (
-    <Container>
-      <Heading level={2}>Hello</Heading>
-      <Text>A short description.</Text>
-      <Button label="Continue" variant="primary" />
-    </Container>
+    <input
+      type="range"
+      min={0}
+      max={100}
+      value={volume}
+      onChange={(e) => setVolume(Number(e.currentTarget.value))}
+    />
   );
 }
 
-// Render-time lookup:
-const HeadingC = componentMap['Heading'];
-return <HeadingC level={2}>title</HeadingC>;
+export function App() {
+  return (
+    <PlaygroundStateProvider initial={{ volume: 50 }}>
+      <VolumeControl />
+    </PlaygroundStateProvider>
+  );
+}
+```
+
+### 3. State-bound component (the simple path)
+
+```tsx
+// No need to write your own useBoundValue — Slider + stateKey does it.
+<PlaygroundStateProvider initial={{ volume: 50 }}>
+  <Slider min={0} max={100} stateKey="volume" />
+</PlaygroundStateProvider>
+```
+
+---
+
+## Flexibility patterns — pick the right hook for the job
+
+v0.2.2 ships five hooks for binding components to state. They differ
+in **what triggers a re-render**, **what they assume about Providers**,
+and **how they expose state to your code**. Pick the lowest-cost one
+that fits.
+
+| Hook                   | Subscribes? | Needs Provider? | SSR-safe? | Use when…                              |
+|------------------------|-------------|------------------|-----------|-----------------------------------------|
+| `useBoundValue`        | yes         | yes (throws)     | yes       | You need to re-render on state changes and a Provider is mandatory |
+| `useBoundValueOrUndefined` | yes     | no (graceful)    | yes       | `stateKey` is optional; no Provider = no-op binding |
+| `useStoreSnapshot`     | **no**      | yes (throws)     | n/a       | You read/write state in handlers but don't want re-renders |
+| `useBoundSelector`     | yes (filtered) | yes (throws)  | yes       | One key holds an object; you only care about one slice |
+| `useMultiBoundValue`   | yes (1 per key) | yes (throws) | yes       | A form/dashboard binds 5-10 keys; you want a Record |
+
+### `useStoreSnapshot` — for non-subscribing reads
+
+When you need state in event handlers but don't want the component to
+re-render on every change:
+
+```tsx
+import { useStoreSnapshot } from '@playgenx/components';
+
+function SaveButton() {
+  const { get, set, snapshot } = useStoreSnapshot();
+  return (
+    <button onClick={() => {
+      // Read multiple keys atomically, write back, no re-render
+      const form = snapshot();
+      if (form.dirty) {
+        set('savedAt', Date.now());
+        api.save(form);
+      }
+    }}>
+      Save
+    </button>
+  );
+}
 ```
 
-## Determinism
+The hook returns `{ state, get, set, subscribe, snapshot, replaceAll }` —
+all stable references for the Provider's lifetime.
 
-Components are render-only and **never** reference `Math.random`, `Date.now`, or runtime-crypto APIs. Hashing inputs (validation, storage) is fully reproducible — `<Chart kind="bar" data={...} />` renders the same SVG every time given the same data.
+### `useBoundSelector` — slice-aware subscriptions
 
-If you mount these in an environment where a renderer may pass non-deterministic callbacks, run inside a sandboxed iframe that the LLM never controls.
+When one key holds an object and you only care about one field:
+
+```tsx
+import { useBoundSelector } from '@playgenx/components';
+
+interface User { name: string; age: number; email: string; }
+
+function CurrentUserBadge() {
+  // Only re-renders when `name` changes, not when `age` changes.
+  const [name] = useBoundSelector<User, string>(
+    'currentUser',
+    (u) => u?.name ?? 'guest',
+    'guest',
+  );
+  return <span>Hi, {name}!</span>;
+}
+```
+
+**Important**: write selectors that return primitives or stable refs.
+A selector that returns a fresh object (`u => ({...u})`) defeats the
+slice-detection and re-renders on every store change.
+
+### `useMultiBoundValue` — bind many keys at once
+
+For forms and dashboards where you have several bound inputs in one
+component:
+
+```tsx
+import { useMultiBoundValue } from '@playgenx/components';
+
+function SettingsForm() {
+  const form = useMultiBoundValue({
+    name:  { fallback: '' },
+    email: { fallback: '' },
+    age:   { fallback: 0 },
+    role:  { fallback: 'user' },
+  });
+  return (
+    <>
+      <input value={form.name[0]}  onChange={e => form.name[1](e.target.value)} />
+      <input value={form.email[0]} onChange={e => form.email[1](e.target.value)} />
+      <input type="number" value={form.age[0]} onChange={e => form.age[1](+e.target.value)} />
+      <select value={form.role[0]} onChange={e => form.role[1](e.target.value)}>
+        <option value="user">User</option>
+        <option value="admin">Admin</option>
+      </select>
+    </>
+  );
+}
+```
+
+The hook subscribes once per key (so 5 keys = 5 subscriptions). For
+50+ rows of dynamic data, use `useStoreSnapshot` + manual `get`/`set`
+calls instead — the hook count is bounded.
+
+### SSR — state is reflected in the first render
+
+All `useBoundValue*` hooks use React 19's `useSyncExternalStore` so
+the **server-rendered HTML matches the live store value**, not a
+fallback. `renderToString(<Slider stateKey="v" />)` inside a Provider
+with `initial={{ v: 7 }}` produces `<input value="7" ... />` — no
+hydration mismatch.
+
+```ts
+// Server
+import { renderToString } from 'react-dom/server';
+import { Slider, PlaygroundStateProvider } from '@playgenx/components';
+
+const html = renderToString(
+  <PlaygroundStateProvider initial={{ volume: 50 }}>
+    <Slider min={0} max={100} stateKey="volume" />
+  </PlaygroundStateProvider>
+);
+// html contains `value="50"` — not `value="0"` (the local fallback)
+```
+
+If your framework has a `renderToReadableStream` or similar, the same
+guarantee holds. The hook count is **3** (down from 5 in 0.2.1)
+thanks to `useSyncExternalStore` collapsing the previous
+`useState + useState + useEffect` trio.
+
+---
+
+## Slider — the three operating modes
+
+The `Slider` component accepts `value` and/or `stateKey`. They mean
+different things:
+
+| Pass                | Mode                     | Behavior                              |
+|---------------------|--------------------------|---------------------------------------|
+| Neither             | **Uncontrolled**         | Owns its own local state              |
+| `value={50}` only   | **Controlled, read-only** | User input is ignored (no onChange wired) |
+| `stateKey="volume"` | **Bound to state**       | Reads/writes via the Provider         |
+
+The bound mode wins when both are present. `value` is clamped to
+`[min, max]` on read; NaN clamps to `min`; `min === max` disables the
+slider.
+
+---
+
+## The CLI: `playgenx-state`
+
+After `npm install @playgenx/components`, you get a `playgenx-state`
+binary on your PATH (via npm's `bin` field). It operates on JSON
+snapshots on stdin/stdout.
+
+```bash
+# Pretty-print a snapshot in the v1 envelope format
+$ echo '{"volume":5,"user":{"name":"a"}}' | playgenx-state snapshot
+{
+  "version": 1,
+  "keys": [
+    "user",
+    "volume"
+  ],
+  "values": {
+    "volume": 5,
+    "user": { "name": "a" }
+  }
+}
+
+# Validate stateKey strings before using them in a body
+$ echo '["good","bad key","has/slash"]' | playgenx-state validate
+[
+  { "key": "good", "ok": true },
+  { "key": "bad key", "ok": false, "error": "stateKey must not contain whitespace" },
+  { "key": "has/slash", "ok": false, "error": "stateKey contains forbidden characters..." }
+]
+# exit code 3 (validation failed)
+
+# Diff two snapshots
+$ echo '{"prev":{"a":1},"next":{"a":2,"b":3}}' | playgenx-state diff
+{ "added": ["b"], "changed": ["a"], "removed": [] }
+
+# Inspect keys / count
+$ echo '{"b":1,"a":2,"c":3}' | playgenx-state keys
+[ "a", "b", "c" ]
+$ echo '{"b":1,"a":2,"c":3}' | playgenx-state count
+{ "keys": 3 }
+```
+
+**Exit codes:** `0` ok, `1` unknown subcommand, `2` bad input, `3`
+validation failure.
+
+These are the same helpers exported from the package as library
+functions (`dumpState`, `diffSnapshots`, `validateStateKey`, etc.) —
+the CLI is a thin wrapper. Use whichever fits.
+
+---
+
+## Architecture notes
+
+- **Per-Provider scope.** Each `PlaygroundStateProvider` creates an
+  independent store. Nested Providers create nested scopes (a child
+  Provider does not see the parent's keys).
+- **HMR-safe.** Subscribers are cleared on Provider unmount, so a
+  hot-reload that re-mounts the Provider doesn't leak subscribers to
+  the old store.
+- **Microtask batched.** `set()` schedules subscriber fires on the
+  next microtask. Multiple sets in the same tick produce one fire
+  per affected key. Use `batch(state, fn)` if you want each
+  subscriber to see only the LAST value set in a group.
+- **No deep clone.** Values are stored by reference. Don't mutate
+  objects after `set()`-ing them — use a fresh object instead.
+- **`Object.is` equality.** Setting a value that `Object.is`-equals
+  the current value is a no-op (no subscriber fire, no flush). This
+  means `set('x', NaN)` twice fires once, and `set('x', undefined)`
+  on an unset key is a no-op (since `Object.is(undefined, undefined)`
+  is `true`).
+- **Sub-Provider remount drops old subscribers.** Subscribers from a
+  unmounted Provider's tree do not fire for sets on a NEW Provider's
+  store, even with the same key name. (Verified by the A.7 hardening
+  test.)
+
+---
+
+## TypeScript
+
+This package is written in TypeScript with strict types. The
+`dist/index.d.mts` declarations are exhaustive — you can `import
+type { SliderProps, PlaygroundState, StateDiff }` etc.
+
+Common imports:
+
+```ts
+import type {
+  SliderProps,
+  ButtonProps,
+  PlaygroundState,
+  StateAction,
+  StateDiff,
+  StateEnvelope,
+  RenderBodyOptions,
+} from '@playgenx/components';
+```
+
+---
 
 ## Versioning
 
-This package follows PlayGenX's overall version policy (mirror `playgenx` core). A component's prop signature is part of the public contract; new optional props are non-breaking, removing/renaming is a breaking change.
+- **0.1.x** — Component-only, no state store. `Slider` had no
+  `stateKey` prop.
+- **0.2.0** — Adds `PlaygroundStateProvider`, `useBoundValue*`,
+  `useStateAction`, `ArtifactErrorBoundary`, `ShowSource`,
+  `createRegistry`, the pure helpers (`dumpState` etc.), and the
+  `playgenx-state` CLI binary. The `stateKey` prop on `Slider` is
+  fully wired and uses the new state store.
+- **0.2.1** — Exposes the CLI binary via the package's `bin` field
+  so `npx playgenx-state` works after a fresh install.
+- **0.2.2** — SSR fix: `useBoundValueOrUndefined` now uses React 19's
+  `useSyncExternalStore` so `renderToString` reflects the Provider's
+  live value (no more "fallback on server, real value after hydration"
+  mismatch). Adds three flexibility hooks: `useStoreSnapshot`
+  (non-subscribing), `useBoundSelector` (slice-aware subscription),
+  `useMultiBoundValue` (batch key binding). 108 tests passing.
+
+---
 
 ## License
 
-MIT — see [LICENSE](../../LICENSE).
+MIT — same as the parent project.

package/bin/state-cli.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+/**
+ * playgenx-state — CLI for inspecting and operating on
+ * PlaygroundState snapshots.
+ *
+ * Pure ESM, no extra deps. Reads JSON from stdin (or argv),
+ * writes JSON to stdout.
+ *
+ * Subcommands:
+ *
+ *   snapshot    Pretty-print a snapshot in the v1 envelope format.
+ *               Accepts a JSON object on stdin (the snapshot you
+ *               captured from `state.snapshot()` or a DebugSurface).
+ *
+ *   validate    Validate one or more stateKey strings from stdin.
+ *               Reads a JSON array of strings, returns the per-key
+ *               verdict.
+ *
+ *   diff        Diff two snapshots. Reads `{prev, next}` from stdin
+ *               and returns the structured {added, changed, removed}
+ *               diff (or null when equal).
+ *
+ *   keys        List the sorted keys of a snapshot from stdin.
+ *
+ *   count       Count the keys in a snapshot from stdin.
+ *
+ * Usage examples (run from the components package root):
+ *
+ *   echo '{"volume": 5}' | node bin/state-cli.mjs snapshot
+ *   echo '["volume","user.name","bad key"]' | node bin/state-cli.mjs validate
+ *   echo '{"prev":{"a":1},"next":{"a":2,"b":3}}' | node bin/state-cli.mjs diff
+ *
+ * Exit codes:
+ *
+ *   0  success
+ *   1  bad subcommand
+ *   2  bad input (not parseable as JSON, wrong shape, etc.)
+ *   3  validation failure (one or more keys rejected)
+ *
+ * @packageDocumentation
+ */
+
+import {
+  dumpState,
+  diffSnapshots,
+  validateStateKey,
+} from '../dist/index.mjs';
+
+/**
+ * Read all of stdin into a string. Node-only.
+ */
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    // Interactive / no pipe — return empty; the caller will treat
+    // this as "no input" and print usage.
+    return '';
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function usage() {
+  return [
+    'Usage: playgenx-state <subcommand> [input]',
+    '',
+    'Subcommands:',
+    '  snapshot    Pretty-print a state snapshot (JSON on stdin)',
+    '  validate    Validate an array of stateKey strings (JSON array on stdin)',
+    '  diff        Diff two snapshots ({prev, next} on stdin)',
+    '  keys        List sorted keys of a snapshot (JSON on stdin)',
+    '  count       Count keys in a snapshot (JSON on stdin)',
+    '',
+    'Reads from stdin when no arg is given.',
+  ].join('\n');
+}
+
+function ok(payload) {
+  process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+}
+
+function fail(code, msg) {
+  process.stderr.write(`error: ${msg}\n`);
+  process.exit(code);
+}
+
+/**
+ * Convert an arbitrary snapshot to the StateEnvelope shape. The
+ * input is whatever the caller passed; we expect a plain object.
+ */
+function envelope(input) {
+  const keys = Object.keys(input).sort();
+  return { version: 1, keys, values: { ...input } };
+}
+
+async function main(argv) {
+  const sub = argv[0];
+  if (!sub || sub === '-h' || sub === '--help') {
+    process.stdout.write(usage() + '\n');
+    return 0;
+  }
+  const stdinPayload = (await readStdin()).trim();
+  const argPayload = argv[1];
+
+  switch (sub) {
+    case 'snapshot': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      // Re-use the library's envelope so the CLI output matches the
+      // canonical dumpState shape. (We don't have a real store to
+      // pass to dumpState; envelope() builds the same structure.)
+      const env = envelope(input);
+      process.stdout.write(JSON.stringify(env, null, 2) + '\n');
+      // Reference dumpState so it's not tree-shaken — the import
+      // is documented as the canonical envelope producer.
+      void dumpState;
+      return 0;
+    }
+
+    case 'validate': {
+      const input = parseArray(argPayload ?? stdinPayload);
+      const results = input.map((k) => {
+        if (typeof k !== 'string') {
+          return { key: String(k), ok: false, error: 'must be a string' };
+        }
+        const err = validateStateKey(k);
+        return err === null
+          ? { key: k, ok: true }
+          : { key: k, ok: false, error: err };
+      });
+      const anyFailed = results.some((r) => !r.ok);
+      ok(results);
+      return anyFailed ? 3 : 0;
+    }
+
+    case 'diff': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      if (!('prev' in input) || !('next' in input)) {
+        fail(2, 'diff expects {prev, next}');
+      }
+      const prev = input.prev;
+      const next = input.next;
+      if (typeof prev !== 'object' || prev === null) fail(2, 'prev must be an object');
+      if (typeof next !== 'object' || next === null) fail(2, 'next must be an object');
+      const d = diffSnapshots(prev, next);
+      ok(d);
+      return 0;
+    }
+
+    case 'keys': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      ok(Object.keys(input).sort());
+      return 0;
+    }
+
+    case 'count': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      ok({ keys: Object.keys(input).length });
+      return 0;
+    }
+
+    default:
+      process.stderr.write(usage() + '\n');
+      return 1;
+  }
+}
+
+function parseObject(raw) {
+  if (raw === '') fail(2, 'expected a JSON object on stdin or as argv[1]');
+  try {
+    const v = JSON.parse(raw);
+    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+      fail(2, 'expected a JSON object');
+    }
+    return v;
+  } catch (err) {
+    fail(2, `JSON parse error: ${err.message}`);
+  }
+}
+
+function parseArray(raw) {
+  if (raw === '') fail(2, 'expected a JSON array on stdin or as argv[1]');
+  try {
+    const v = JSON.parse(raw);
+    if (!Array.isArray(v)) fail(2, 'expected a JSON array');
+    return v;
+  } catch (err) {
+    fail(2, `JSON parse error: ${err.message}`);
+  }
+}
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => fail(2, err.message ?? String(err)));