@weasel-js/labkit 1.0.2 → 1.0.3

package/src/instrument/capabilityDetector.ts

@@ -1,5 +1,7 @@
 import type { Instrument } from './types';
 
+/** Which optional capabilities an instrument declared — what the workspace
+ *  consults to decide which chrome to show. */
 export interface CapabilityFlags {
   hasCanvas: boolean;
   hasLayers: boolean;
@@ -7,6 +9,7 @@ export interface CapabilityFlags {
   hasUndo: boolean;
 }
 
+/** Read an instrument's declared capabilities off its definition. */
 export function detectCapabilities(instrument: Instrument<unknown, unknown>): CapabilityFlags {
   return {
     hasCanvas: instrument.canvas != null,

package/src/instrument/defineInstrument.ts

@@ -1,5 +1,7 @@
 import type { Instrument } from './types';
 
+/** Identity at runtime; exists so an instrument's state and config types are
+ *  inferred from the spec rather than having to be written out. */
 export function defineInstrument<TS, TC>(spec: Instrument<TS, TC>): Instrument<TS, TC> {
   return spec;
 }

package/src/instrument/types.ts

@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react';
 import type { ConfigField } from '../controls/types';
 
+/** What an instrument's `render` is handed: its state and config, the setters
+ *  for both, the workspace it is mounted in, and a way to emit named events. */
 export interface RenderContext<TS = unknown, TC = unknown> {
   state: TS;
   config: TC;
@@ -14,20 +16,28 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   emit: (event: string) => void;
 }
 
+/** One 2D canvas layer of an instrument, drawn in declaration order. */
 export interface CanvasLayer<TS = unknown, TC = unknown> {
   id: string;
   draw: (ctx: CanvasRenderingContext2D, args: { state: TS; config: TC; zoom: number }) => void;
 }
 
+/** Declares that an instrument draws to a canvas: its layers, and where the
+ *  view starts. */
 export interface CanvasCapability<TS = unknown, TC = unknown> {
   layers: CanvasLayer<TS, TC>[];
   initialView?: { zoom: number; pan: { x: number; y: number } };
 }
 
+/** Declares which of an instrument's layers the workspace should offer
+ *  show/hide controls for. */
 export interface LayerCapability {
   ids: string[];
 }
 
+/** Declares that an instrument accepts items dragged from a palette: what the
+ *  palette offers, what a drop does to the state, and — optionally — live
+ *  feedback during the drag and the ability to drag existing items back out. */
 export interface DragDropCapability<TS = unknown, TC = unknown> {
   palette: PaletteItem[] | ((state: TS, config: TC) => PaletteItem[]);
   onDrop: (worldPos: Point, item: PaletteItem, state: TS, config: TC) => TS;
@@ -35,20 +45,39 @@ export interface DragDropCapability<TS = unknown, TC = unknown> {
   pickUp?: (hit: HitResult, state: TS, config: TC) => { item: PaletteItem; state: TS } | null;
 }
 
+/** Declares that an instrument's state is undoable: which emitted events
+ *  snapshot it, and how many snapshots to keep. */
 export interface UndoCapability {
   snapshotOn?: string[];
   maxDepth?: number;
 }
 
+/** The name of an event an instrument emits through `RenderContext.emit`. */
 export type SystemEvent = string;
 
+/** A point in world coordinates. */
 export type Point = { x: number; y: number };
+/** What a hit-test found, and where. */
 export type HitResult = { hit: boolean; layerId?: string; pointId?: string };
+/** A workspace's camera. */
 export type ViewTransform = { zoom: number; pan: Point };
+/** A layer as the layer list shows it. `alwaysOn` layers cannot be hidden. */
 export type LayerDescriptor = { id: string; label: string; alwaysOn?: boolean };
+/** One draggable entry in an instrument's palette. */
 export type PaletteItem = { id: string; label: string; data?: unknown };
+/** Whether a drop would be accepted at the current position, and why not if
+ *  it would not. */
 export type DragFeedback = { ok: boolean; reason?: string };
 
+/**
+ * An instrument: one self-contained interactive experiment a lab can host.
+ *
+ * It owns two pieces of data — `config`, the settings the control panel edits,
+ * and `state`, what the experiment is currently doing — and renders from both.
+ * The optional capability fields declare what else it wants from the runtime:
+ * a canvas, a layer list, palette drag-and-drop, undo. Declaring a capability
+ * is what makes the workspace provide the corresponding chrome.
+ */
 export interface Instrument<TS = unknown, TC = unknown> {
   name: string;
   defaultConfig: () => TC;

package/src/instrument/validateConfigSchema.ts

@@ -1,5 +1,7 @@
 import type { ConfigField, ConfigFieldType } from '../controls/types';
 
+/** Whether a config schema is usable, and every problem found rather than
+ *  just the first. */
 export interface ValidationResult {
   valid: boolean;
   errors: string[];
@@ -7,6 +9,9 @@ export interface ValidationResult {
 
 const KNOWN_TYPES: ConfigFieldType[] = ['slider', 'checkbox', 'select', 'number', 'text', 'color'];
 
+/** Check a config schema for the mistakes that would otherwise surface as a
+ *  silently broken control: empty or duplicate keys, unknown field types, and
+ *  fields whose own constraints do not hold. */
 export function validateConfigSchema(fields: ConfigField[]): ValidationResult {
   const errors: string[] = [];
   const seenKeys = new Set<string>();

package/src/lab/Lab.tsx

@@ -19,6 +19,7 @@ import { LabShell } from './LabShell';
 import { useResolvedMode } from './useSystemMode';
 import { WorkspaceGrid } from './WorkspaceGrid';
 
+/** Props for `<Lab>`. */
 export interface LabProps {
   instruments: Instrument[];
   defaultInstrument: string;
@@ -76,6 +77,8 @@ function buildNebula(colors: readonly string[]): string {
   return blobs.join(', ');
 }
 
+/** The lab runtime: creates the store, provides it, and renders one workspace
+ *  per record in a grid. Each workspace runs one of `instruments`. */
 export function Lab({
   instruments,
   defaultInstrument,

package/src/lab/LabContext.ts

@@ -2,6 +2,9 @@ import { createContext, useContext } from 'react';
 import type { Instrument } from '../instrument/types';
 import type { LabMode, SavedSnapshot, WorkspaceRecord } from '../state/types';
 
+/** Lab-wide state and commands: the available instruments, the open
+ *  workspaces and the operations over them, saved snapshots, and the color
+ *  mode. */
 export interface LabContextValue {
   instruments: Instrument[];
   workspaces: WorkspaceRecord[];
@@ -17,8 +20,10 @@ export interface LabContextValue {
   setMode: (m: LabMode) => void;
 }
 
+/** Context carrying the surrounding lab. Prefer `useLabContext`. */
 export const LabContext = createContext<LabContextValue | null>(null);
 
+/** The surrounding lab. Throws outside a `<Lab>`. */
 export function useLabContext(): LabContextValue {
   const ctx = useContext(LabContext);
   if (ctx === null) {

package/src/lab/LabShell.tsx

@@ -4,6 +4,7 @@ import type { LabMode } from '../state/types';
 import { interstellarTheme } from '../theme/interstellar';
 import { useResolvedMode } from './useSystemMode';
 
+/** Props for `<LabShell>`. */
 export interface LabShellProps {
   title: string;
   children: ReactNode;
@@ -15,6 +16,9 @@ export interface LabShellProps {
   mode?: LabMode;
 }
 
+/** Page frame for a lab: a titled header, a body, and an optional footer,
+ *  themed for the resolved color mode. Presentational only — use `<Lab>` when
+ *  the workspace runtime is wanted too. */
 export function LabShell({ title, children, header, footer, mode = 'auto' }: LabShellProps) {
   const resolved = useResolvedMode(mode);
   const outer = useThemeOptional();

package/src/lab/WorkspaceGrid.tsx

@@ -1,10 +1,12 @@
 import { Children, type CSSProperties, type ReactNode } from 'react';
 import { gridDims } from './gridDims';
 
+/** Props for `<WorkspaceGrid>`. */
 export interface WorkspaceGridProps {
   children: ReactNode;
 }
 
+/** Lays its children out in the most nearly square grid that fits them. */
 export function WorkspaceGrid({ children }: WorkspaceGridProps) {
   const count = Children.count(children);
   const { cols, rows } = gridDims(count);

package/src/lab/gridDims.ts

@@ -1,8 +1,10 @@
+/** A grid's column and row counts. */
 export interface GridDims {
   cols: number;
   rows: number;
 }
 
+/** The most nearly square grid that fits `count` items. */
 export function gridDims(count: number): GridDims {
   if (count <= 1) return { cols: 1, rows: 1 };
   const cols = Math.ceil(Math.sqrt(count));

package/src/layers/LayerList.tsx

@@ -1,6 +1,7 @@
 import { type PointerEvent, useRef, useState } from 'react';
 import type { LayerDescriptor } from '../instrument/types';
 
+/** Props for `<LayerList>`. */
 export interface LayerListProps {
   layers: LayerDescriptor[];
   visibility: Record<string, boolean>;
@@ -15,6 +16,8 @@ interface DragState {
   startY: number;
 }
 
+/** A reorderable list of layers with per-layer visibility toggles. Layers
+ *  marked `alwaysOn` are pinned and cannot be reordered or hidden. */
 export function LayerList({ layers, visibility, onReorder, onToggle, className }: LayerListProps) {
   const reorderable = layers.filter((l) => !l.alwaysOn);
   const pinned = layers.filter((l) => l.alwaysOn);

package/src/primitives/FpsMeter.tsx

@@ -3,6 +3,7 @@ import { rollingAverage } from './fpsAverage';
 
 const SAMPLE_WINDOW = 30;
 
+/** A live frame-rate readout, averaged over the last 30 frames. */
 export function FpsMeter() {
   const [fps, setFps] = useState(0);
   const samplesRef = useRef<number[]>([]);

package/src/primitives/ScaleIndicator.tsx

@@ -1,6 +1,7 @@
 import { useContext } from 'react';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
 
+/** Props for `<ScaleIndicator>`. */
 export interface ScaleIndicatorProps {
   /** Current view zoom factor. If omitted, reads from CanvasStackContext. Defaults to 1. */
   zoom?: number;
@@ -25,6 +26,9 @@ function niceNumber(n: number): number {
   return nice * 10 ** exp;
 }
 
+/** A scale bar: a labeled rule showing how far a round number of world units
+ *  is at the current zoom. Reads the zoom from the surrounding canvas stack
+ *  unless one is passed. */
 export function ScaleIndicator({
   zoom,
   pixelsPerUnit = 1,

package/src/primitives/Sidebar.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 
+/** Props for `<Sidebar>`. */
 export interface SidebarProps {
   children: ReactNode;
   title?: string;
@@ -7,6 +8,8 @@ export interface SidebarProps {
   onToggle?: () => void;
 }
 
+/** A collapsible side panel with an optional title. Collapse state is the
+ *  caller's to hold. */
 export function Sidebar({ children, title, collapsed = false, onToggle }: SidebarProps) {
   const className = `lk-sidebar${collapsed ? ' lk-sidebar--collapsed' : ''}`;
   return (

package/src/primitives/StatusBar.tsx

@@ -1,9 +1,11 @@
 import type { ReactNode } from 'react';
 
+/** Props for `<StatusBar>`. */
 export interface StatusBarProps {
   children: ReactNode;
 }
 
+/** A footer strip for readouts. Fill it with `<StatusBar.Section>`. */
 export function StatusBar({ children }: StatusBarProps) {
   return <div className="lk-status-bar">{children}</div>;
 }
@@ -15,4 +17,5 @@ function Section({ children }: SectionProps) {
   return <span className="lk-status-bar-section">{children}</span>;
 }
 
+/** One readout within a status bar. */
 StatusBar.Section = Section;

package/src/primitives/Toolbar.tsx

@@ -1,9 +1,12 @@
 import type { MouseEventHandler, ReactNode } from 'react';
 
+/** Props for `<Toolbar>`. */
 export interface ToolbarProps {
   children: ReactNode;
 }
 
+/** A horizontal bar of controls. Fill it with `<Toolbar.Title>`,
+ *  `<Toolbar.Button>` and `<Toolbar.Spacer>`. */
 export function Toolbar({ children }: ToolbarProps) {
   return <div className="lk-toolbar">{children}</div>;
 }
@@ -39,6 +42,9 @@ function Spacer() {
   return <span className="lk-toolbar-spacer" aria-hidden="true" />;
 }
 
+/** A label within a toolbar. */
 Toolbar.Title = Title;
+/** A button within a toolbar. */
 Toolbar.Button = Button;
+/** Flexible space that pushes what follows to the far end of the toolbar. */
 Toolbar.Spacer = Spacer;

package/src/state/SingletonExperiment.tsx

@@ -5,6 +5,7 @@ import type { StorageAdapter } from './types';
 
 const SINGLETON_INSTRUMENT = '__singleton__';
 
+/** Props for `<SingletonExperimentProvider>`. */
 export interface SingletonExperimentProviderProps<TS, TC> {
   /** Stable id for the synthetic workspace; also doubles as the
    *  WorkspaceIdContext value. */

package/src/state/adapters.ts

@@ -1,6 +1,8 @@
 import { decodeUrlHash, encodeUrlHash } from './helpers';
 import type { StorageAdapter } from './types';
 
+/** Persist to `localStorage` — state survives a reload and a new tab. Falls
+ *  back to no-ops when storage is unavailable. */
 export const localStorageAdapter: StorageAdapter = {
   read: (key) => {
     try {
@@ -25,6 +27,7 @@ export const localStorageAdapter: StorageAdapter = {
   },
 };
 
+/** Persist to `sessionStorage` — state survives a reload but not a new tab. */
 export const sessionStorageAdapter: StorageAdapter = {
   read: (key) => {
     try {
@@ -68,6 +71,8 @@ function writeHashMap(map: Record<string, string>): void {
   window.history.replaceState(null, '', `#${encoded}`);
 }
 
+/** Persist into the URL fragment, so the page's link carries its state and
+ *  can be shared or bookmarked. */
 export const urlHashAdapter: StorageAdapter = {
   read: (key) => readHashMap()[key] ?? null,
   write: (key, value) => {
@@ -82,6 +87,8 @@ export const urlHashAdapter: StorageAdapter = {
   },
 };
 
+/** An in-memory store, discarded on reload. For tests, and for labs that
+ *  should start fresh every time. */
 export function createMemoryAdapter(): StorageAdapter {
   const store = new Map<string, string>();
   return {
@@ -95,6 +102,7 @@ export function createMemoryAdapter(): StorageAdapter {
   };
 }
 
+/** Persists nothing and reads back nothing. */
 export const noneAdapter: StorageAdapter = {
   read: () => null,
   write: () => {},

package/src/state/context.tsx

@@ -5,8 +5,11 @@ import type { LabStoreState } from './types';
 
 type LabStoreCtx = { store: LabStore } | null;
 
+/** Context carrying the lab store. Prefer `useLabStore`; this is exported for
+ *  code that needs to read the context without subscribing. */
 export const LabStoreContext = createContext<LabStoreCtx>(null);
 
+/** Provides a lab store to its subtree. */
 export function LabStoreProvider({
   store,
   children,
@@ -17,14 +20,18 @@ export function LabStoreProvider({
   return <LabStoreContext.Provider value={{ store }}>{children}</LabStoreContext.Provider>;
 }
 
+/** Subscribe to the whole lab store. Throws outside a `<LabStoreProvider>`. */
 export function useLabStore(): LabStoreState & ReturnType<LabStore['getState']> {
   const ctx = useContext(LabStoreContext);
   if (!ctx) throw new Error('[labkit] useLabStore must be used inside <LabStoreProvider>');
   return useStore(ctx.store);
 }
 
+/** Context carrying which workspace the subtree belongs to. */
 export const WorkspaceIdContext = createContext<string | null>(null);
 
+/** Names the workspace its subtree belongs to, so an instrument's hooks can
+ *  find their own record in the store without being passed an id. */
 export function WorkspaceIdProvider({
   workspaceId,
   children,
@@ -35,6 +42,8 @@ export function WorkspaceIdProvider({
   return <WorkspaceIdContext.Provider value={workspaceId}>{children}</WorkspaceIdContext.Provider>;
 }
 
+/** The id of the workspace this component is inside. Throws outside a
+ *  `<WorkspaceIdProvider>`. */
 export function useWorkspaceId(): string {
   const id = useContext(WorkspaceIdContext);
   if (!id) throw new Error('[labkit] useWorkspaceId must be used inside <WorkspaceIdProvider>');

package/src/state/helpers.ts

@@ -1,5 +1,7 @@
 import type { InstrumentSerializers, UndoStack, WorkspaceRecord } from './types';
 
+/** The storage key a lab writes one of its three buckets under. Namespaced by
+ *  `storageKey` so two labs sharing an origin do not collide. */
 export function labStorageKey(
   storageKey: string,
   bucket: 'workspaces' | 'saves' | 'theme',
@@ -7,10 +9,13 @@ export function labStorageKey(
   return `lk:${storageKey}:${bucket}`;
 }
 
+/** Encode a string for the URL fragment. */
 export function encodeUrlHash(value: string): string {
   return btoa(encodeURIComponent(value));
 }
 
+/** Decode a URL fragment written by `encodeUrlHash`, or `null` if it is
+ *  malformed. */
 export function decodeUrlHash(hash: string): string | null {
   if (!hash) return null;
   try {
@@ -20,12 +25,16 @@ export function decodeUrlHash(hash: string): string | null {
   }
 }
 
+/** A fresh, empty undo history. */
 export function emptyUndoStack(): UndoStack {
   return { past: [], future: [] };
 }
 
 type SerializedRecord = Omit<WorkspaceRecord, 'undoStack'>;
 
+/** Serialize workspaces for storage, running each instrument's own serializer
+ *  over its state. Undo history is deliberately dropped — it does not survive
+ *  a reload. */
 export function serializeWorkspaces(
   workspaces: WorkspaceRecord[],
   serializers: InstrumentSerializers,
@@ -40,6 +49,9 @@ export function serializeWorkspaces(
   return JSON.stringify(records);
 }
 
+/** Rebuild workspaces from storage, running each instrument's deserializer
+ *  over its state and starting each with an empty undo history. Returns an
+ *  empty list rather than throwing on malformed input. */
 export function deserializeWorkspaces(
   raw: string,
   deserializers: InstrumentSerializers,

package/src/state/store.ts

@@ -14,6 +14,8 @@ import type {
   WorkspaceRecord,
 } from './types';
 
+/** Every mutation a lab store supports: managing workspaces, saving and
+ *  restoring snapshots, and setting the color mode. */
 export interface LabStoreActions {
   addWorkspace: (record: Omit<WorkspaceRecord, 'undoStack'>) => void;
   removeWorkspace: (id: string) => void;
@@ -34,10 +36,14 @@ export interface LabStoreActions {
   setMode: (mode: LabMode) => void;
 }
 
+/** A lab's store: its state and actions, plus the hook instruments use to
+ *  register how their state is serialized. */
 export type LabStore = StoreApi<LabStoreState & LabStoreActions> & {
   registerSerializers: (s: InstrumentSerializers) => void;
 };
 
+/** Build a lab store, hydrating from storage if anything was saved under the
+ *  same key. Writes back are debounced. */
 export function createLabStore(options: CreateLabStoreOptions): LabStore {
   let serializers: InstrumentSerializers = {};
   let flushTimer: ReturnType<typeof setTimeout> | null = null;

package/src/state/types.ts

@@ -1,8 +1,12 @@
+/** A workspace's undo history, as snapshots of its state either side of the
+ *  present. */
 export interface UndoStack {
   past: unknown[];
   future: unknown[];
 }
 
+/** One workspace as the store holds it: which instrument it runs, that
+ *  instrument's config and state, the camera, and the undo history. */
 export interface WorkspaceRecord<TS = unknown, TC = unknown> {
   id: string;
   instrumentName: string;
@@ -12,6 +16,8 @@ export interface WorkspaceRecord<TS = unknown, TC = unknown> {
   undoStack: UndoStack;
 }
 
+/** A named, saved copy of a workspace's config and state, restorable into any
+ *  workspace running the same instrument. */
 export interface SavedSnapshot {
   id: string;
   name: string;
@@ -25,18 +31,25 @@ export interface SavedSnapshot {
 /** `auto` follows the OS; the other two are an explicit choice. */
 export type LabMode = 'auto' | 'light' | 'dark';
 
+/** Everything a lab persists: its workspaces, its saved snapshots, and the
+ *  chosen color mode. */
 export interface LabStoreState {
   workspaces: WorkspaceRecord[];
   savedSnapshots: SavedSnapshot[];
   mode: LabMode;
 }
 
+/** Where a lab persists itself. Implementations are keyed string storage and
+ *  nothing more, so the same store works against localStorage, the URL hash,
+ *  or memory. */
 export interface StorageAdapter {
   read(key: string): string | null;
   write(key: string, value: string): void;
   delete?(key: string): void;
 }
 
+/** What `useExperimentState` hands an instrument: its state and config, with
+ *  a setter for each. */
 export interface ExperimentStateHandle<TS, TC> {
   state: TS;
   setState: (next: TS | ((prev: TS) => TS)) => void;
@@ -44,12 +57,16 @@ export interface ExperimentStateHandle<TS, TC> {
   setConfig: (key: keyof TC, value: TC[keyof TC]) => void;
 }
 
+/** Options for `createLabStore`. `storageKey` namespaces the keys written, so
+ *  two labs on one origin do not collide. */
 export interface CreateLabStoreOptions {
   storageKey: string;
   storage: StorageAdapter;
   initialMode?: LabMode;
 }
 
+/** Per-instrument serialize/deserialize hooks, keyed by instrument name. An
+ *  instrument whose state is already JSON-safe needs no entry. */
 export type InstrumentSerializers = Record<
   string,
   { serialize?: (state: unknown) => unknown; deserialize?: (data: unknown) => unknown } | undefined

package/src/state/useExperimentState.ts

@@ -3,6 +3,9 @@ import { useStore } from 'zustand/react';
 import { LabStoreContext, WorkspaceIdContext } from './context';
 import type { ExperimentStateHandle } from './types';
 
+/** An instrument's own state and config, plus setters. Reads the surrounding
+ *  workspace id, so an instrument never has to know which workspace it is
+ *  running in. Throws outside a lab store and workspace. */
 export function useExperimentState<TS = unknown, TC = unknown>(): ExperimentStateHandle<TS, TC> {
   const ctx = useContext(LabStoreContext);
   if (!ctx) throw new Error('[labkit] useExperimentState must be used inside <LabStoreProvider>');

package/src/ui/layers/LayerStack.tsx

@@ -1,6 +1,8 @@
 import { type CSSProperties, type ReactNode, type RefCallback, useEffect, useState } from 'react';
 import { dlog, useReorderDragList } from '../../passthrough/weasel-ui';
 
+/** One card in a layer stack: its identity, the label shown when collapsed,
+ *  and the optional select hoisted into its header. */
 export interface LayerStackItem {
   /** Stable id used for keys, onRemove, onReorder. Numeric to match
    *  common id-from-nextId conventions; string ids also work. */
@@ -22,6 +24,7 @@ export interface LayerStackItem {
   defaultExpanded?: boolean;
 }
 
+/** Props for `<LayerStack>`. */
 export interface LayerStackProps {
   title: string;
   items: LayerStackItem[];
@@ -38,6 +41,8 @@ export interface LayerStackProps {
   hideHead?: boolean;
 }
 
+/** A drag-reorderable stack of expandable cards, with a palette in the header
+ *  for adding more. The body of each card is the caller's to render. */
 export function LayerStack({
   title,
   items,

package/src/ui/properties/CurveField.tsx

@@ -1,10 +1,13 @@
 import { useCallback, useMemo } from 'react';
 import { type ControlPoint, CurveEditor, dlog } from '../../passthrough/weasel-ui';
 
+/** An annotation drawn over a curve plot: a shaded band across a range of x,
+ *  or a vertical line at one x. */
 export type CurveMark =
   | { kind: 'band'; x: [number, number]; color?: string }
   | { kind: 'line'; x: number; color?: string };
 
+/** Props for `<CurveField>`. */
 export interface CurveFieldProps {
   /** Flat [x0, y0, x1, y1, …] — matches how curve-as-array configs
    *  serialize in JSON snapshots. */
@@ -91,7 +94,7 @@ export function CurveField({
       <div className="lk-curve-field__plot">
         <CurveEditor
           value={points}
-          onChange={handleChange}
+          onInput={handleChange}
           domain="1d"
           constrain="function"
           xRange={[0, 1]}

package/src/ui/properties/EffectCard.tsx

@@ -5,12 +5,15 @@ import { type CSSProperties, type ReactNode, useState } from 'react';
 // label flanked by a horizontal rule — no background, padding, or border;
 // purely a typographic divider. Ported from speech-balloons styles.css:277-313.
 
+/** Props for `<Subpanel>`. */
 export interface SubpanelProps {
   title: ReactNode;
   children: ReactNode;
   className?: string;
 }
 
+/** A typographic divider inside a property list: a small title flanked by a
+ *  rule. Purely a heading — use `<PropertyGroup>` for a bordered section. */
 export function Subpanel({ title, children, className }: SubpanelProps) {
   const cls = className ? `lk-subpanel ${className}` : 'lk-subpanel';
   return (
@@ -29,6 +32,7 @@ export function Subpanel({ title, children, className }: SubpanelProps) {
 // per-instance recolors the title bar, border-left, and (via re-binding --wzl-accent
 // inside the card) every descendant control that reads from the accent token.
 
+/** Props for `<EffectCard>`. */
 export interface EffectCardProps {
   /** Card title rendered in the title bar (e.g. effect kind label or a select). */
   title: ReactNode;
@@ -59,6 +63,9 @@ export interface EffectCardProps {
   className?: string;
 }
 
+/** An accented, collapsible card for one item in a list of like things —
+ *  effects, layers, tails. The accent color rebinds the theme accent token
+ *  within the card, so its controls pick it up too. */
 export function EffectCard({
   title,
   primary,
@@ -182,10 +189,12 @@ function DragHandleIcon() {
 // onReorder fires with (sourceId, targetId, position) on drop. Mirrors the
 // LayerStack pattern from speech-balloons Lab.tsx:630-707.
 
+/** The minimum an item must carry to appear in an `<EffectCardList>`. */
 export interface EffectCardListItem {
   id: string | number;
 }
 
+/** Props for `<EffectCardList>`. */
 export interface EffectCardListProps<T extends EffectCardListItem> {
   items: ReadonlyArray<T>;
   renderItem: (
@@ -217,6 +226,9 @@ export interface EffectCardListProps<T extends EffectCardListItem> {
   defaultExpandedIds?: ReadonlyArray<T['id']>;
 }
 
+/** A drag-reorderable list of `<EffectCard>`s. Owns the expanded and dragging
+ *  state and hands it back to `renderItem`, so the caller only supplies each
+ *  card's contents. */
 export function EffectCardList<T extends EffectCardListItem>({
   items,
   renderItem,

package/src/ui/properties/PropertyGroup.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 
+/** Props for `<PropertyGroup>`. */
 export interface PropertyGroupProps {
   /** Title rendered between two rules at the top of the group. */
   title: ReactNode;