@vscode/component-explorer 0.2.1-18 → 0.2.1-180

package/README.md

@@ -1,6 +1,6 @@
 # @vscode/component-explorer
 
-Core library for the [Component Explorer](../../README.md). Contains the fixture API, property schemas, fixture registry, and the Explorer React UI.
+Core library for the [Component Explorer](../../README.md). Contains the fixture API, input schemas, fixture registry, and the Explorer React UI.
 
 ## Fixture API
 
@@ -10,46 +10,85 @@ Defines a single component fixture.
 
 ```tsx
 import { defineFixture } from '@vscode/component-explorer';
+import { z } from 'zod';
 
 export default defineFixture({
-  properties: [
-    { type: 'string', name: 'label', defaultValue: 'Click me' },
-    { type: 'boolean', name: 'disabled', defaultValue: false },
-  ],
-  render: (container, props) => {
+  inputSchema: z.object({
+    label: z.string().default('Click me'),
+    disabled: z.boolean().default(false),
+  }),
+  render: (container, { input }) => {
     const root = createRoot(container);
-    root.render(<Button label={props.label as string} disabled={props.disabled as boolean} />);
+    root.render(<Button label={input.label} disabled={input.disabled} />);
     return { dispose: () => root.unmount() };
   },
 });
 ```
 
+The `inputSchema` is a [zod](https://zod.dev) schema. It is converted to JSON Schema at define
+time, and `input` (typed as `z.infer<typeof schema>`) is populated with the schema's defaults
+plus any overrides set in the explorer's properties panel.
+
 Options:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `render` | `(container, props) => Disposable` | **(required)** | Renders the component. Must return `{ dispose() }` for cleanup. |
-| `properties` | `PropertySchema[]` | `[]` | Configurable properties shown in the properties panel. |
+| `render` | `(container, context) => Disposable` | **(required)** | Renders the component. Must return `{ dispose() }` for cleanup. |
+| `inputSchema` | `z.ZodType` | — | Zod schema describing `input`. Drives the properties panel controls. |
+| `inputControls` | `Record<inputKey, options>` | — | Places selected boolean/enum inputs in the fixture toolbar, sidebar, or both. |
+| `debugPanels` | `DebugPanelDefinition[]` | — | Statically declares typed, interactive debug panels. |
 | `isolation` | `'shadow-dom' \| 'iframe'` | `'shadow-dom'` | Component isolation strategy. |
 | `displayMode` | `DisplayMode` | `{ type: 'component' }` | `'component'` for natural size, or `'page'` with viewport presets. |
 | `styles` | `StyleDefinition[]` | — | Stylesheets injected into the shadow root (shadow-dom isolation only). |
 | `background` | `'light' \| 'dark'` | `'light'` | Preview canvas background pattern. |
 | `description` | `string` | — | Documentation description. |
 
-### `defineFixtureGroup(entries)`
+The sidebar's **Preview Sizing** dropdown applies to all fixtures and persists across navigation
+and reloads. **Fit** scales down to fit the preview viewport's width and height, **1:1** shows
+natural size, and **Responsive (Pages)** resizes page fixtures while using Fit for components.
+Page fixtures retain their per-fixture toolbar for selecting a viewport preset and editing logical
+width/height. These UI settings do not affect embedded or headless rendering.
+
+Natural-size component fixtures also default to **Fit**, shrinking to the available preview
+width and height without upscaling small components. Both fixed dimensions and dynamically
+changing content retain their natural layout: only the preview presentation is scaled.
+Dynamic size changes and preview resizing update the scale without remounting the fixture.
+Fit uses a shared preview-viewport budget with fixed allowances for padding and fixture chrome.
+It does not depend on a fixture's position, wrapping, neighboring fixtures, or its scaled bounds.
+Small variants can share a row; large variants wrap without shrinking to their toolbar's width.
+
+### Render timeout and diagnostics
+
+Fixtures have a 3,000 ms asynchronous render/readiness budget. Synchronous work
+in an installed V8 `Error.prepareStackTrace` formatter, including source-map
+loading, parsing, and mapping, is excluded from that budget. The formatter's
+result and exceptions are preserved; genuine fixture errors still fail with
+their mapped stacks, and renders that never finish still time out.
 
-Groups multiple fixtures (supports nesting):
+The watchdog uses captured real timers, not a fixture's virtual clock. Diagnostic
+time is shared across same-origin embedded frames, including synchronous fixture
+setup. Overlapping renders keep
+the formatter wrapped until the last render finishes. Headless timing reports
+remain real wall-clock durations, including diagnostics. The browser runner's
+outer timeout remains the limit on total wall-clock work.
+
+### `defineFixtureGroup(entries)` / `defineFixtureGroup(options, entries)`
+
+Groups multiple fixtures (supports nesting). An optional first argument can declare an
+`inputSchema` shared by — and merged into — every descendant fixture, so common input (e.g. a
+`theme` switch) is declared once for the whole group:
 
 ```tsx
 import { defineFixture, defineFixtureGroup } from '@vscode/component-explorer';
+import { z } from 'zod';
 
-export default defineFixtureGroup({
-  Primary: defineFixture({ render: (c) => { /* ... */ } }),
-  Secondary: defineFixture({ render: (c) => { /* ... */ } }),
-  Nested: defineFixtureGroup({
-    Small: defineFixture({ render: (c) => { /* ... */ } }),
-  }),
-});
+export default defineFixtureGroup(
+  { inputSchema: z.object({ theme: z.enum(['light', 'dark']).default('dark') }) },
+  {
+    Primary: defineFixture({ render: (c) => { /* ... */ } }),
+    Secondary: defineFixture({ render: (c) => { /* ... */ } }),
+  },
+);
 ```
 
 ### `defineFixtureVariants(variants)`
@@ -66,16 +105,149 @@ defineFixtureVariants({
 });
 ```
 
-## Property Types
+## Input Schemas
+
+Fixture `input` is described with a [zod](https://zod.dev) schema (`inputSchema`). The explorer
+converts it to JSON Schema and renders a control per property in the properties panel:
+
+| Zod type | Control |
+|---|---|
+| `z.boolean()` | Toggle checkbox |
+| `z.string()` | Text input |
+| `z.number()` / `z.int()` | Number input |
+| `z.enum([...])` | Dropdown select |
+
+Use `.default(...)` to set the initial value and `.describe(...)` to document a property. When
+multiple rendered fixtures share a property of the same name and schema, the panel exposes a
+single control that edits them all at once.
+
+Use `inputControls` with `placement: 'toolbar'` for compact boolean or enum controls beside the
+fixture dimensions. Opt a property into live updates with `watchInput`; changed properties without
+a watcher keep the default full-remount behavior. A fixture can call
+`reportInput(key, value)` after its component changes a watched property itself.
+This updates the sidebar/shared input store without echoing the change to that
+fixture's watcher or remounting it. Reports are coalesced per microtask and
+discarded after disposal; unwatched properties are rejected. This also works
+across iframe isolation.
+
+```ts
+defineFixture({
+  inputSchema: z.object({ showBounds: z.boolean().default(false) }),
+  inputControls: {
+    showBounds: { placement: 'toolbar', label: 'bounds' },
+  },
+  render(container, { watchInput }) {
+    const overlay = createBoundsOverlay(container);
+    watchInput('showBounds', value => overlay.setVisible(value));
+    return overlay;
+  },
+});
+```
+
+## Typed Debug Panels and Output
+
+`defineDebugPanel<TState, TAction>()` defines a custom panel UI. The fixture connects its live
+state/action channel through `context.debug.connect`. The connection callback runs only while that
+panel is visible, so hidden panels do not parse, subscribe, or publish data.
+
+```ts
+const sourcePanel = defineDebugPanel<
+  { source: string },
+  { type: 'setSource'; source: string }
+>({
+  id: 'source',
+  title: 'Source',
+  render: (container, { sendAction }) => createSourceView(container, sendAction),
+});
+
+defineFixture({
+  debugPanels: [sourcePanel],
+  render(container, { debug }) {
+    const model = createModel(container);
+    debug.connect(sourcePanel, channel => {
+      const actions = channel.onAction(action => model.setSource(action.source));
+      const state = model.onDidChange(() => channel.publish({ source: model.source }));
+      channel.publish({ source: model.source });
+      return { dispose: () => { actions.dispose(); state.dispose(); } };
+    });
+    return model;
+  },
+});
+```
+
+Panels default beside a single logical fixture and in the shared bottom workbench for variant rows.
+Set `placement: 'canvas-right'` or `'bottom-panel'` on the panel to override this rule.
+Closed inline panels are grouped in a **Debug panels** dropdown. When a stack's tabs do not fit,
+the active tab remains visible and a **More debug panels** dropdown (`...`) offers the other panels.
+Select a panel, then drag its tab into a split to keep multiple panels visible. During dragging,
+overflowing tabs are revealed; hovering near the tab strip's edges scrolls it. Drop onto a tab
+header to reorder or move tabs between panes.
+
+**Split right** creates a second live view of the selected debug panel, leaving the original open.
+Both copies share fixture state but have independent tab selections and view instances. Close a
+pane using its **Close debug pane** button; its other tabs remain available in the workbench.
+
+Drag the bottom edge of inline debug panes to give them more vertical space independently of the
+fixture. The resize handle also supports Up/Down arrow keys; double-click or press Home to reset.
+**Viewport height** fills the available preview height without stretching or remounting the fixture.
+Open/closed panes, tab order and selection, duplicate views, split ratios, widths, and heights
+survive navigation and reload in this browser. Storage is scoped to the project supplied by the
+Vite/Webpack plugin. Custom hosts can supply `ExplorerAppOptions.storageScope` (the default is the
+Explorer URL path). Storage errors are reported in the sidebar and console.
+
+Enable **Synchronize debug panes** in the properties sidebar to copy the current fixture's
+arrangement into a shared template. Other fixtures use that template with their own live data.
+Missing panel types are temporarily hidden, and empty groups collapse. Navigation and panel
+preference changes do not rewrite the template. An explicit layout edit (including selecting a
+tab or resizing) saves the visible arrangement, discarding hidden groups from the template.
+Turning synchronization off restores the independent fixture layouts and preferences from before
+it was enabled. The aggregated bottom workbench, including Console, persists independently and
+does not participate in synchronization.
+
+### Persistent panel UI state
+
+Panels can opt into validated, versioned, JSON-serializable view preferences without accessing
+browser storage. Call `context.viewState` with a stable schema/version and one state object per
+panel and scope. `get()` restores state before rendering; `set()` validates and saves it; `onChange()`
+subscribes to changes (dispose the subscription with the panel).
+
+```ts
+render(container, context) {
+  const preferences = context.viewState({
+    version: 1,
+    scope: 'pane',
+    schema: z.object({ renderer: z.enum(['cmark-gfm', 'markdown-it']) }),
+    defaultValue: { renderer: 'cmark-gfm' },
+  });
+  const select = document.createElement('select');
+  for (const renderer of ['cmark-gfm', 'markdown-it']) {
+    select.add(new Option(renderer, renderer));
+  }
+  select.value = preferences.get().renderer;
+  select.onchange = () => {
+    preferences.set({ renderer: select.value === 'markdown-it' ? 'markdown-it' : 'cmark-gfm' });
+  };
+  const subscription = preferences.onChange(value => { select.value = value.renderer; });
+  container.append(select);
+  return {
+    update(source) { /* render live fixture data separately */ },
+    dispose() { subscription.dispose(); select.remove(); },
+  };
+}
+```
 
-| Type | Fields | Description |
-|---|---|---|
-| `boolean` | `name`, `defaultValue` | Toggle checkbox |
-| `string` | `name`, `defaultValue`, `multiline?` | Text input (or textarea) |
-| `number` | `name`, `defaultValue`, `min?`, `max?`, `step?` | Number input with optional range |
-| `enum` | `name`, `defaultValue`, `options` | Dropdown select |
+Use `scope: 'pane'` for preferences that follow a synchronized pane between fixtures (for example,
+the Markdown Reference renderer). Use `scope: 'fixture'` for fixture-dependent selections or scroll
+positions. Split right copies the current preferences once; the two tab instances then evolve
+independently. Docking and reordering retain their identities, even when duplicate tabs are placed
+in the same group. Unsupported versions or invalid saved values use the declared default and
+report a warning; bump the version when changing the state shape. Fixture data, actions, and
+headless rendering are unaffected.
 
-All property types support an optional `description` field.
+Any defined `RenderResult.output` gets a built-in read-only JSON panel. Wrap it with
+`interactiveOutput({ getSnapshot, activate })` to opt into JSON editing; output actions update the
+live fixture without remounting. Headless and CLI consumers continue to receive the unwrapped
+snapshot value.
 
 ## Explorer UI Components
 
@@ -96,7 +268,6 @@ The package exports the full Explorer UI as React components:
 |---|---|
 | `FixtureRegistry` | Observable registry of discovered fixtures. |
 | `createFixtureTree` | Builds a `FixtureNode` tree from registered fixtures. |
-| `getDefaultPropertyValues` | Extracts default values from a `PropertySchema[]`. |
 | `VIEWPORT_SIZES` | Built-in viewport preset dimensions (`mobile`, `tablet`, `desktop`). |
 
 ## Styles