@xenosystem/components 0.7.1 → 0.8.1

package/dist/chrome/index.d.ts

@@ -0,0 +1,1181 @@
+import { ReactNode, HTMLAttributes, ReactElement } from 'react';
+
+/**
+ * Frame + strip primitives: `PanelFrame`, `Toolbar`, `ToolbarGroup`, `Divider`, `ScrollArea`.
+ *
+ * `PanelFrame` implements xeno-workflow's CSS contract verbatim (`xeno-panel` / `-header` /
+ * `-title` / `-content`), so a standalone panel gets the canonical floating-panel look with one
+ * component. **Inside `<Workbench>` you do NOT need it** — the Dockview group already paints the
+ * frame; use `Toolbar` + content directly.
+ *
+ * @module
+ */
+
+/** Props for {@link PanelFrame}. */
+interface PanelFrameProps {
+    /** Uppercase title shown in the header bar. Omit (with `showHeader` unset) to render no header. */
+    title?: ReactNode;
+    /** Trailing controls in the header bar. */
+    actions?: ReactNode;
+    /** Force the header on/off. Defaults to "on when `title` or `actions` is present". */
+    showHeader?: boolean;
+    /** Panel body. */
+    children?: ReactNode;
+    /** Extra classes on the outer frame. */
+    className?: string;
+    /** Extra classes on the content well. */
+    contentClassName?: string;
+}
+/**
+ * The canonical standalone panel frame — header bar + content well, separated by the panel gap.
+ *
+ * @example
+ * ```tsx
+ * <PanelFrame title="Layers" actions={<IconButton icon={<PlusIcon />} label="Add layer" />}>
+ *   <RowList>…</RowList>
+ * </PanelFrame>
+ * ```
+ */
+declare function PanelFrame({ title, actions, showHeader, children, className, contentClassName, }: PanelFrameProps): ReactNode;
+/** Props for {@link Toolbar}. */
+interface ToolbarProps {
+    /** Leading cluster (filters, title, counts). */
+    left?: ReactNode;
+    /** Trailing cluster (actions). Right-aligned. */
+    right?: ReactNode;
+    /** Free-form children, rendered between the clusters. */
+    children?: ReactNode;
+    /** Render a hairline under the strip. Default `true`. */
+    divided?: boolean;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A dense horizontal control strip. Height matches the panel header so a toolbar stacked under a
+ * frame header reads as one continuous chrome band.
+ *
+ * @example
+ * ```tsx
+ * <Toolbar left={<SearchField value={q} onChange={setQ} />} right={<IconButton … />} />
+ * ```
+ */
+declare function Toolbar({ left, right, children, divided, className, }: ToolbarProps): ReactNode;
+/** Props for {@link ToolbarGroup}. */
+interface ToolbarGroupProps {
+    /** Cluster contents. */
+    children?: ReactNode;
+    /** Push the cluster to the right edge. */
+    end?: boolean;
+    /** Extra classes. */
+    className?: string;
+}
+/** A cluster of controls inside a {@link Toolbar}. */
+declare function ToolbarGroup({ children, end, className }: ToolbarGroupProps): ReactNode;
+/** Props for {@link Divider}. */
+interface DividerProps {
+    /** Render a short vertical rule (for inline use inside a toolbar). */
+    vertical?: boolean;
+    /** Extra classes. */
+    className?: string;
+}
+/** A hairline rule. Horizontal by default; `vertical` for inline separation inside a strip. */
+declare function Divider({ vertical, className }: DividerProps): ReactNode;
+/** Props for {@link ScrollArea}. */
+interface ScrollAreaProps {
+    /** Scrollable content. */
+    children?: ReactNode;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A flex-filling scroll container with the canonical thin rectangular thumb and an unbroken
+ * height chain (`flex: 1 1 0; min-height: 0`) — the shape DESIGN_SYSTEM §3.1 requires so panels
+ * never reach for `max-height: calc(100vh - N)`.
+ */
+declare function ScrollArea({ children, className }: ScrollAreaProps): ReactNode;
+
+/**
+ * `Section` — the collapsible titled group.
+ *
+ * Lifted from `xeno-post`'s `Section` (title + action slot) and re-cut to the density and feature
+ * set of the only real in-panel implementation in the catalog, the Inspector's: 20px header, a
+ * disclosure twisty, a count badge, action buttons, and an ENABLE toggle that dims the body without
+ * hiding it (the "effect is off but still configured" state every property panel needs).
+ *
+ * ## The header is not a button
+ *
+ * A collapsible header wants to be a `<button>` for keyboard/AT, but actions and a toggle cannot be
+ * nested inside one (interactive content inside a button is invalid and breaks AT). So the header is
+ * a plain row and only the chevron+title span is the `<button>` — actions are its siblings. This is
+ * the standard resolution and it is why `Section` renders three elements rather than one.
+ *
+ * @module
+ */
+
+/** Props for {@link Section}. */
+interface SectionProps {
+    /** Uppercase section label. */
+    title: ReactNode;
+    /** Body. */
+    children?: ReactNode;
+    /** Small chip after the title (a count, a unit, a state word). */
+    badge?: ReactNode;
+    /** Trailing controls (icon buttons, a select). Rendered outside the collapse trigger. */
+    actions?: ReactNode;
+    /** Whether the section can collapse. Default `true`. */
+    collapsible?: boolean;
+    /** Controlled collapsed state. Omit for uncontrolled. */
+    collapsed?: boolean;
+    /** Initial collapsed state when uncontrolled. Default `false`. */
+    defaultCollapsed?: boolean;
+    /** Called with the next collapsed state. Required for the controlled form to do anything. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * Presence of this prop renders the enable toggle. `false` dims the body and blocks pointer
+     * events — the section stays visible and readable, it just stops applying.
+     */
+    enabled?: boolean;
+    /** Called with the next enabled state. */
+    onEnabledChange?: (enabled: boolean) => void;
+    /** Render the body with no vertical padding (for a flush `RowList`). */
+    flush?: boolean;
+    /** Extra classes on the wrapper. */
+    className?: string;
+    /** Extra classes on the body. */
+    bodyClassName?: string;
+}
+/**
+ * A collapsible titled group.
+ *
+ * @example
+ * ```tsx
+ * <Section
+ *   title="Transform"
+ *   badge={<Badge>3</Badge>}
+ *   enabled={fx.enabled}
+ *   onEnabledChange={(on) => host.emit('intent', { kind: 'toggle', on })}
+ *   actions={<IconButton icon={<ResetGlyph />} label="Reset transform" onClick={reset} />}
+ * >
+ *   <FieldGroup>…</FieldGroup>
+ * </Section>
+ * ```
+ */
+declare function Section({ title, children, badge, actions, collapsible, collapsed, defaultCollapsed, onCollapsedChange, enabled, onEnabledChange, flush, className, bodyClassName, }: SectionProps): ReactNode;
+
+/**
+ * The canonical panel-chrome CLASS VOCABULARY — framework-free.
+ *
+ * These are the class names the primitives' stylesheet defines. They are exported as constants (and
+ * as small state→className helpers) so a panel written in ANY framework — or in plain DOM — gets the
+ * canonical chrome without importing React.
+ *
+ * Two naming families live here, deliberately:
+ *
+ * 1. **`xeno-panel*` — the FRAME contract, lifted verbatim from `xeno-workflow`'s `index.css`**
+ *    (`xeno-panel` / `xeno-panel-header` / `xeno-panel-title` / `xeno-panel-content` /
+ *    `xeno-panel-content--no-header`, driven by `--xeno-panel-gap` / `--xeno-panel-radius`).
+ *    The names are byte-identical to workflow's so that repo can delete its local copy and import
+ *    ours with zero markup churn. Note the frame is for panels rendered OUTSIDE a workbench — when
+ *    a panel is mounted in `<Workbench>`, the Dockview GROUP is already the frame (see the theme).
+ *
+ * 2. **`xeno-<primitive>` — the KIT vocabulary, lifted from `xeno-post`'s `ui/kit.tsx`**
+ *    (Section, RowList/Row, Toolbar, StatTile, ProportionBar, EmptyState, LoadingState, ErrorState,
+ *    StatusBadge, IconFrame …), re-cut for dense in-panel density rather than dashboard-page density.
+ *
+ * Modifiers use BEM's double dash (`xeno-row--selected`), matching workflow's existing
+ * `xeno-panel-content--no-header`.
+ *
+ * @module
+ */
+/** Outer frame of a standalone panel. Layout-only; the `::before` paints the page backdrop. */
+declare const CLS_PANEL = "xeno-panel";
+/** The frame's compact header bar. */
+declare const CLS_PANEL_HEADER = "xeno-panel-header";
+/** Uppercase title text inside the frame header. */
+declare const CLS_PANEL_TITLE = "xeno-panel-title";
+/** The frame's content well. */
+declare const CLS_PANEL_CONTENT = "xeno-panel-content";
+/** Applied to the content well when the frame renders no header. */
+declare const CLS_PANEL_CONTENT_NO_HEADER = "xeno-panel-content--no-header";
+/** Horizontal control strip (`left` / `right` clusters). */
+declare const CLS_TOOLBAR = "xeno-toolbar";
+/** A cluster of controls inside a toolbar. */
+declare const CLS_TOOLBAR_GROUP = "xeno-toolbar-group";
+/** Footer strip: counts on the left, state on the right. */
+declare const CLS_STATUSBAR = "xeno-statusbar";
+/** 1px hairline; `--vertical` for an inline separator inside a toolbar. */
+declare const CLS_DIVIDER = "xeno-divider";
+/** Collapsible titled group. */
+declare const CLS_SECTION = "xeno-section";
+/** The section's header row. */
+declare const CLS_SECTION_HEADER = "xeno-section-header";
+/** The `<button>` inside the header that toggles collapse (siblings stay outside it — see `Section`). */
+declare const CLS_SECTION_TRIGGER = "xeno-section-trigger";
+/** Disclosure chevron wrapper (rotates via the `--collapsed` modifier). */
+declare const CLS_SECTION_CHEVRON = "xeno-section-chevron";
+/** Uppercase section label. */
+declare const CLS_SECTION_TITLE = "xeno-section-title";
+/** Trailing cluster in the section header (badge + actions + toggle). */
+declare const CLS_SECTION_ACTIONS = "xeno-section-actions";
+/** The section's body. */
+declare const CLS_SECTION_BODY = "xeno-section-body";
+/** Hairline-divided vertical list container. */
+declare const CLS_ROWLIST = "xeno-rowlist";
+/** A single dense row. */
+declare const CLS_ROW = "xeno-row";
+/** Fixed-width leading icon slot (keeps labels in one column — DESIGN_SYSTEM §5). */
+declare const CLS_ROW_ICON = "xeno-row-icon";
+/** The row's flexible label column. */
+declare const CLS_ROW_LABEL = "xeno-row-label";
+/** Secondary text after the label. */
+declare const CLS_ROW_META = "xeno-row-meta";
+/** Right-aligned trailing slot. */
+declare const CLS_ROW_TRAILING = "xeno-row-trailing";
+/** Square icon-only button. */
+declare const CLS_ICON_BUTTON = "xeno-iconbtn";
+/** Borderless inline text action (`+ Add`, `Clear`, `Unbind`). */
+declare const CLS_TEXT_BUTTON = "xeno-textbtn";
+/** Search / filter input wrapper. */
+declare const CLS_SEARCH = "xeno-search";
+/** The `<input>` inside a search field. */
+declare const CLS_SEARCH_INPUT = "xeno-search-input";
+/** Segmented (radio-group) control. */
+declare const CLS_SEGMENTED = "xeno-segmented";
+/** One segment button. */
+declare const CLS_SEGMENT = "xeno-segment";
+/** The signature XENO toggle (rectangular track, square knob). */
+declare const CLS_TOGGLE = "xeno-toggle";
+/** The toggle's knob. */
+declare const CLS_TOGGLE_KNOB = "xeno-toggle-knob";
+/** Label-column field group (all labels share one width). */
+declare const CLS_FIELD_GROUP = "xeno-fieldgroup";
+/** One label + control row. */
+declare const CLS_FIELD = "xeno-field";
+/** The field's label cell. */
+declare const CLS_FIELD_LABEL = "xeno-field-label";
+/** The field's control cell. */
+declare const CLS_FIELD_CONTROL = "xeno-field-control";
+/** Muted hint under a field. */
+declare const CLS_FIELD_HINT = "xeno-field-hint";
+/** Centered zero-content state. */
+declare const CLS_EMPTY = "xeno-empty";
+/** Centered busy state. */
+declare const CLS_LOADING = "xeno-loading";
+/** Centered failure state. */
+declare const CLS_ERROR = "xeno-error";
+/** Shared container for the three states above. */
+declare const CLS_STATE = "xeno-state";
+/** The state's icon chip. */
+declare const CLS_STATE_ICON = "xeno-state-icon";
+/** The state's headline. */
+declare const CLS_STATE_TITLE = "xeno-state-title";
+/** The state's supporting line — the ACTIONABLE hint. */
+declare const CLS_STATE_HINT = "xeno-state-hint";
+/** Indeterminate progress bar used by the loading state (no spinner — no circles). */
+declare const CLS_STATE_PROGRESS = "xeno-state-progress";
+/** Small rectangular status/metadata chip. */
+declare const CLS_BADGE = "xeno-badge";
+/** 2px-radius square status dot (never a circle). */
+declare const CLS_DOT = "xeno-dot";
+/** Flat outlined icon container. */
+declare const CLS_ICON_FRAME = "xeno-iconframe";
+/** Label + big value tile. */
+declare const CLS_STAT = "xeno-stat";
+/** The stat's uppercase label row. */
+declare const CLS_STAT_LABEL = "xeno-stat-label";
+/** The stat's value. */
+declare const CLS_STAT_VALUE = "xeno-stat-value";
+/** The stat's sub-line. */
+declare const CLS_STAT_SUB = "xeno-stat-sub";
+/** Horizontal stacked proportion bar (replaces a pie/donut — no circles). */
+declare const CLS_BAR = "xeno-bar";
+/** One segment of a proportion bar. */
+declare const CLS_BAR_SEGMENT = "xeno-bar-segment";
+/** Scroll container with the canonical thin rectangular thumb. */
+declare const CLS_SCROLL = "xeno-scroll";
+/**
+ * Semantic tone for badges, dots and states. `neutral` is the default and the only tone that is
+ * purely monochromatic; the other four are the ONLY places DESIGN_SYSTEM permits chromatic color
+ * (§2 "Color is reserved strictly for semantic/status contexts").
+ */
+type PanelTone = 'neutral' | 'info' | 'success' | 'warning' | 'error';
+/** All tones, in severity order. Useful for exhaustive switches and demos. */
+declare const PANEL_TONES: readonly PanelTone[];
+/** Join truthy class fragments. Internal, but exported because vanilla callers want it too. */
+declare function cx(...parts: Array<string | false | null | undefined>): string;
+/** Interaction state shared by row-like elements. */
+interface RowState {
+    /** Row is the current selection. */
+    selected?: boolean;
+    /** Row is non-interactive (dimmed, `aria-disabled`). */
+    disabled?: boolean;
+    /** Row is active/being dragged or edited. */
+    active?: boolean;
+    /** Row participates in click/keyboard interaction. */
+    interactive?: boolean;
+}
+/**
+ * Build the class list for a row.
+ *
+ * @param state - Interaction state.
+ * @param extra - Caller classes appended last.
+ * @returns The space-joined class list.
+ *
+ * @example
+ * ```ts
+ * el.className = rowClass({ selected: id === selectedId, interactive: true })
+ * ```
+ */
+declare function rowClass(state?: RowState, extra?: string): string;
+/**
+ * Build the class list for a badge.
+ *
+ * @param tone - Semantic tone (default `neutral`).
+ * @param extra - Caller classes appended last.
+ * @returns The space-joined class list.
+ */
+declare function badgeClass(tone?: PanelTone, extra?: string): string;
+/**
+ * Build the class list for a status dot.
+ *
+ * @param tone - Semantic tone (default `neutral`).
+ * @param extra - Caller classes appended last.
+ * @returns The space-joined class list.
+ */
+declare function dotClass(tone?: PanelTone, extra?: string): string;
+/**
+ * Build the class list for a section wrapper.
+ *
+ * @param collapsed - Whether the body is hidden.
+ * @param extra - Caller classes appended last.
+ * @returns The space-joined class list.
+ */
+declare function sectionClass(collapsed?: boolean, extra?: string): string;
+/**
+ * Build the class list for an icon button.
+ *
+ * @param state - `active` renders the pressed treatment; `disabled` dims and blocks pointers.
+ * @param extra - Caller classes appended last.
+ * @returns The space-joined class list.
+ */
+declare function iconButtonClass(state?: {
+    active?: boolean;
+    disabled?: boolean;
+}, extra?: string): string;
+
+/**
+ * List primitives: `RowList` + `Row`.
+ *
+ * This is the single most duplicated shape in the ecosystem — every shipped panel hand-rolls a
+ * 22px hover/selected row with a fixed icon gutter. The contract here is deliberately narrow:
+ * a leading icon slot of FIXED width (so labels align in one column across every row and every
+ * panel — DESIGN_SYSTEM §5), a flexible label, optional meta text, and a right-aligned trailing
+ * slot. Indentation for trees is expressed as `depth`, not as caller padding, so a tree row and a
+ * flat row remain the same height and the icon column stays honest.
+ *
+ * @module
+ */
+
+interface RowListProps extends HTMLAttributes<HTMLDivElement> {
+    /** Rows. */
+    children?: ReactNode;
+    /** Draw hairlines between rows. Default `false` (dense lists read better undivided). */
+    divided?: boolean;
+    /** ARIA role for the container. Default `list`; use `listbox` / `tree` for selectable sets. */
+    role?: string;
+}
+/**
+ * A vertical list container for {@link Row}s.
+ *
+ * @example
+ * ```tsx
+ * <RowList role="listbox" aria-label="Layers">
+ *   {items.map((it) => <Row key={it.id} …/>)}
+ * </RowList>
+ * ```
+ */
+declare function RowList({ children, divided, role, className, ...rest }: RowListProps): ReactNode;
+/** Props for {@link Row}. */
+interface RowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+    /** Leading icon/graphic. Rendered in a fixed-width slot even when `undefined`, to hold the column. */
+    icon?: ReactNode;
+    /** Primary text. Truncates with an ellipsis. */
+    label?: ReactNode;
+    /** Secondary text after the label (counts, types, paths). */
+    meta?: ReactNode;
+    /** Right-aligned controls (toggles, badges, icon buttons). */
+    trailing?: ReactNode;
+    /** Free-form content, rendered INSTEAD of the label/meta pair when provided. */
+    children?: ReactNode;
+    /** Nesting depth for trees; each level indents by `PANEL_METRICS.rowIndent`. */
+    depth?: number;
+    /** Row is the current selection (`aria-selected`). */
+    selected?: boolean;
+    /** Row is active — being dragged, renamed, or otherwise operated on. */
+    active?: boolean;
+    /** Row is non-interactive: dimmed, `aria-disabled`, click/keyboard suppressed. */
+    disabled?: boolean;
+    /** Hide the leading icon slot entirely (for lists with no icons at all). */
+    noIcon?: boolean;
+    /** ARIA role for the row. Defaults to `listitem`, or `option` when `selected` is supplied. */
+    role?: string;
+}
+/**
+ * One dense list row.
+ *
+ * Interaction contract: when `onClick` is supplied the row becomes keyboard-operable
+ * (`tabIndex=0`, Enter/Space activate). When `disabled`, pointer and keyboard activation are both
+ * suppressed — the handler is not called, rather than being called and ignored.
+ *
+ * @example
+ * ```tsx
+ * <Row
+ *   icon={<EyeIcon />}
+ *   label={layer.name}
+ *   meta={layer.kind}
+ *   trailing={<Badge>{layer.opacity}%</Badge>}
+ *   depth={layer.depth}
+ *   selected={layer.id === selectedId}
+ *   onClick={() => select(layer.id)}
+ * />
+ * ```
+ */
+declare function Row({ icon, label, meta, trailing, children, depth, selected, active, disabled, noIcon, role, className, style, onClick, onKeyDown, ...rest }: RowProps): ReactNode;
+
+/**
+ * Control primitives: `IconButton`, `SearchField`, `SegmentedControl`, `Toggle`, `FieldGroup`,
+ * `Field`.
+ *
+ * **No icon library is imported here — ever.** Icons are `ReactNode` props and the two glyphs the
+ * primitives need internally (search, clear, chevron) are inline SVG paths at stroke 1.5. That is a
+ * deliberate consequence of the `lucide-react/dynamic` packaged-build incident: a chrome primitive
+ * must never be the thing that drags an icon bundle — or a dynamic-import trap — into every panel.
+ *
+ * @module
+ */
+
+/** Lucide `search` geometry. */
+declare function SearchGlyph(): ReactNode;
+/** Lucide `x` geometry. */
+declare function ClearGlyph(): ReactNode;
+/** Lucide `chevron-right` geometry — rotated by CSS when a section expands. */
+declare function ChevronGlyph(): ReactNode;
+/** Props for {@link IconButton}. */
+interface IconButtonProps {
+    /** The glyph. Any node — the primitives never import an icon library. */
+    icon: ReactNode;
+    /** Accessible name; also used as the native tooltip. Required — an icon alone is not a name. */
+    label: string;
+    /** Click handler. */
+    onClick?: () => void;
+    /** Pressed/latched treatment (`aria-pressed`). */
+    active?: boolean;
+    /** Disabled treatment (`disabled`, `cursor: not-allowed`). */
+    disabled?: boolean;
+    /** `sm` = 20px (inside rows), `md` = 24px (toolbars, default). */
+    size?: 'sm' | 'md';
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A square icon-only button — the toolbar/row workhorse.
+ *
+ * @example
+ * ```tsx
+ * <IconButton icon={<TrashGlyph />} label="Delete layer" onClick={remove} disabled={!selection} />
+ * ```
+ */
+declare function IconButton({ icon, label, onClick, active, disabled, size, className, }: IconButtonProps): ReactNode;
+/** Props for {@link TextButton}. */
+interface TextButtonProps {
+    /** Label. Census copy patterns: `+ Add`, `Clear`, `Cancel`, `Unbind`. */
+    children?: ReactNode;
+    /** Click handler. */
+    onClick?: () => void;
+    /** Disabled treatment. */
+    disabled?: boolean;
+    /** Render at full body brightness instead of muted. */
+    strong?: boolean;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A borderless text action — the inline `+ Add` / `Clear` / `Unbind` affordance. Muted by default so
+ * it reads as secondary; `strong` promotes it. Never a filled button: `DESIGN_SYSTEM.md` §7 allows
+ * exactly one primary action on screen and a panel is rarely the place for it.
+ */
+declare function TextButton({ children, onClick, disabled, strong, className, }: TextButtonProps): ReactNode;
+/** Props for {@link SearchField}. */
+interface SearchFieldProps {
+    /** Current query (controlled). */
+    value: string;
+    /** Called with the new query on every keystroke. */
+    onChange: (value: string) => void;
+    /** Placeholder text. Default `Search…`. */
+    placeholder?: string;
+    /** Accessible name. Default matches the placeholder. */
+    label?: string;
+    /** Called when the clear affordance or Escape empties the field. Defaults to `onChange('')`. */
+    onClear?: () => void;
+    /** Disable the input. */
+    disabled?: boolean;
+    /** Focus on mount. */
+    autoFocus?: boolean;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * The canonical filter input: recessed well, leading glyph, Escape-to-clear, and a clear button
+ * that only appears when there is something to clear.
+ *
+ * @example
+ * ```tsx
+ * <SearchField value={query} onChange={setQuery} placeholder="Filter layers…" />
+ * ```
+ */
+declare function SearchField({ value, onChange, placeholder, label, onClear, disabled, autoFocus, className, }: SearchFieldProps): ReactNode;
+/** One option in a {@link SegmentedControl}. */
+interface SegmentOption<T extends string> {
+    /** The value this segment selects. */
+    value: T;
+    /** Visible label. */
+    label: ReactNode;
+    /** Native tooltip / accessible name when the label is a glyph. */
+    title?: string;
+    /** Disable this segment only. */
+    disabled?: boolean;
+}
+/** Props for {@link SegmentedControl}. */
+interface SegmentedControlProps<T extends string> {
+    /** The options, in display order. */
+    options: ReadonlyArray<SegmentOption<T>>;
+    /** The selected value. */
+    value: T;
+    /** Called with the newly selected value. Not called for the already-selected segment. */
+    onChange: (value: T) => void;
+    /** Accessible name for the group. */
+    label?: string;
+    /** `sm` = 20px, `md` = 24px (default). */
+    size?: 'sm' | 'md';
+    /** Stretch segments to fill the available width. */
+    stretch?: boolean;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A radio group rendered as adjoined segments — the canonical "one of N modes" control (display
+ * units, view modes, sort order).
+ *
+ * Keyboard: arrow keys move the selection, matching the ARIA radiogroup pattern.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedControl
+ *   label="Time display"
+ *   options={[{ value: 'tc', label: 'TC' }, { value: 'frames', label: 'F' }]}
+ *   value={display}
+ *   onChange={setDisplay}
+ * />
+ * ```
+ */
+/**
+ * Resolve the value an arrow key moves to: wraps around, skips disabled segments, and returns the
+ * current value when there is nowhere to go.
+ *
+ * Exported because it is the only non-trivial logic in the control, and logic that only exists
+ * inside a DOM event handler is logic that never gets tested.
+ *
+ * @param options - The segments, in display order.
+ * @param value - The currently selected value.
+ * @param delta - `+1` for next, `-1` for previous.
+ * @returns The next value, or `value` if the move is a no-op.
+ */
+declare function nextSegmentValue<T extends string>(options: ReadonlyArray<SegmentOption<T>>, value: T, delta: number): T;
+declare function SegmentedControl<T extends string>({ options, value, onChange, label, size, stretch, className, }: SegmentedControlProps<T>): ReactNode;
+/** Props for {@link Toggle}. */
+interface ToggleProps {
+    /** On/off state. */
+    checked: boolean;
+    /** Called with the next state. */
+    onChange: (checked: boolean) => void;
+    /** Accessible name. Required — a bare switch has no visible label. */
+    label: string;
+    /** Disabled treatment. */
+    disabled?: boolean;
+    /** `sm` = 16px track height, `md` = 18px (default). */
+    size?: 'sm' | 'md';
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * The signature XENO toggle: a rectangular track with a SQUARE knob whose corner radius softens
+ * when it moves to the ON position (DESIGN_SYSTEM §3 "The Toggle Switch"). Never a pill.
+ */
+declare function Toggle({ checked, onChange, label, disabled, size, className, }: ToggleProps): ReactNode;
+/** Props for {@link FieldGroup}. */
+interface FieldGroupProps {
+    /** {@link Field} children. */
+    children?: ReactNode;
+    /** Width of the shared label column, in px. Default `PANEL_METRICS.fieldLabelWidth` (76). */
+    labelWidth?: number;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A label-column layout: every {@link Field} inside shares ONE label width, so labels start at the
+ * same x and controls end at the same x — the column alignment DESIGN_SYSTEM §5 requires and the
+ * thing hand-rolled property grids always get wrong.
+ *
+ * @example
+ * ```tsx
+ * <FieldGroup labelWidth={64}>
+ *   <Field label="Opacity"><Slider … /></Field>
+ *   <Field label="Blend"><Select … /></Field>
+ * </FieldGroup>
+ * ```
+ */
+declare function FieldGroup({ children, labelWidth, className }: FieldGroupProps): ReactNode;
+/** Props for {@link Field}. */
+interface FieldProps {
+    /** The label text. */
+    label: ReactNode;
+    /** The control. */
+    children?: ReactNode;
+    /** Muted explanatory line under the control. */
+    hint?: ReactNode;
+    /** Id of the control the label points at. Generated when omitted and `children` is a single input. */
+    htmlFor?: string;
+    /** Stack the label above the control instead of beside it. */
+    stacked?: boolean;
+    /** Extra classes. */
+    className?: string;
+}
+/** One label + control row inside a {@link FieldGroup}. */
+declare function Field({ label, children, hint, htmlFor, stacked, className, }: FieldProps): ReactNode;
+
+/**
+ * The three terminal states: `EmptyState`, `LoadingState`, `ErrorState`.
+ *
+ * ## The actionable-hint rule
+ *
+ * The five shipped panels all render empty as a single dim uppercase noun — `No layers`,
+ * `No history`, `Nothing selected`. That tells a user what they can already see. `xeno-canvas`
+ * pioneered the better pattern: a second line that says what the thing IS and how to make one —
+ * *"Bind a text layer's style to one in Properties → Text."*, *"An alias points at another token;
+ * the resolver follows the chain."*
+ *
+ * So {@link EmptyState} splits them: `title` names the state (keeping the shipped typography, so
+ * adopting the primitive changes nothing visually for a panel that passes only a title), and `hint`
+ * carries the instruction. **A hint that merely restates the title is worse than no hint** — write
+ * the sentence that gets the user to a non-empty panel, or omit it.
+ *
+ * @module
+ */
+
+/** Props for {@link EmptyState}. */
+interface EmptyStateProps {
+    /** Names the state. Keep it short: `No layers`, `Nothing selected`. */
+    title: ReactNode;
+    /**
+     * The ACTIONABLE line: what this panel holds and how to put something in it. Omit rather than
+     * restate the title.
+     */
+    hint?: ReactNode;
+    /** Optional glyph, shown in a hairline chip above the title. */
+    icon?: ReactNode;
+    /** Optional call to action (usually a {@link TextButton}). */
+    action?: ReactNode;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * The canonical zero-content state.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   title="No tokens"
+ *   hint="A token is a named value other layers bind to. Add one to start a palette."
+ *   action={<TextButton onClick={createToken}>+ Add token</TextButton>}
+ * />
+ * ```
+ */
+declare function EmptyState({ title, hint, icon, action, className }: EmptyStateProps): ReactNode;
+/** Props for {@link LoadingState}. */
+interface LoadingStateProps {
+    /** What is loading. Default `Loading…`. */
+    label?: ReactNode;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * The canonical busy state — an indeterminate BAR, never a spinner.
+ *
+ * `DESIGN_SYSTEM.md` §3 bans circles and §10 prefers skeletons over spinning indicators; a 2px
+ * indeterminate bar satisfies both and costs one element.
+ */
+declare function LoadingState({ label, className }: LoadingStateProps): ReactNode;
+/** Props for {@link ErrorState}. */
+interface ErrorStateProps {
+    /** Headline. Default `Something went wrong`. */
+    title?: ReactNode;
+    /** The failure detail — the message, not a stack. */
+    message?: ReactNode;
+    /** Retry handler; renders a retry action when supplied. */
+    onRetry?: () => void;
+    /** Label for the retry action. Default `Retry`. */
+    retryLabel?: string;
+    /** Extra classes. */
+    className?: string;
+}
+/** The canonical failure state. The title is the only place a panel renders status red by default. */
+declare function ErrorState({ title, message, onRetry, retryLabel, className, }: ErrorStateProps): ReactNode;
+
+/**
+ * Indicator + data primitives: `Badge`, `StatusDot`, `StatusBadge`, `IconFrame`, `StatTile`,
+ * `ProportionBar`, `StatusBar`.
+ *
+ * Lifted from `xeno-post`'s kit, which is the only place in the ecosystem that solved the
+ * monochromatic data-display problem properly: a proportion BAR instead of a pie/donut (no circles),
+ * a square status dot instead of a round one, and value emphasis carried by size + `tabular-nums`
+ * rather than color. `StatTile` + `ProportionBar` are the two primitives the future `metrics` panel
+ * is built out of, so they land now rather than being invented a sixth time.
+ *
+ * @module
+ */
+
+/** Props for {@link Badge}. */
+interface BadgeProps {
+    /** Contents — a count, a unit, a state word. */
+    children?: ReactNode;
+    /** Semantic tone. Default `neutral` (monochromatic). */
+    tone?: PanelTone;
+    /** `sm` = 12px (in-panel, default), `md` = 18px (DESIGN_SYSTEM §7 standard). */
+    size?: 'sm' | 'md';
+    /** Native tooltip. A chip is often the only place a long value can be read in full. */
+    title?: string;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A small rectangular chip. Never interactive — `DESIGN_SYSTEM.md` §7: "If a badge needs to be
+ * clickable, it's a ghost button, not a badge."
+ */
+declare function Badge({ children, tone, size, title, className, }: BadgeProps): ReactNode;
+/** Props for {@link StatusDot}. */
+interface StatusDotProps {
+    /** Semantic tone. */
+    tone?: PanelTone;
+    /** Accessible label. Supply it when the dot is the ONLY carrier of the state. */
+    label?: string;
+    /** Extra classes. */
+    className?: string;
+}
+/** A 2px-radius SQUARE status dot. Never a circle (`DESIGN_SYSTEM.md` §3 / §13). */
+declare function StatusDot({ tone, label, className }: StatusDotProps): ReactNode;
+/** Props for {@link StatusBadge}. */
+interface StatusBadgeProps {
+    /** The state text. */
+    children?: ReactNode;
+    /** Semantic tone. */
+    tone?: PanelTone;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * Dot + label. Color is never the sole indicator (`DESIGN_SYSTEM.md` §11) — the word carries the
+ * state and the dot reinforces it.
+ */
+declare function StatusBadge({ children, tone, className }: StatusBadgeProps): ReactNode;
+/** Props for {@link IconFrame}. */
+interface IconFrameProps {
+    /** The glyph. */
+    icon: ReactNode;
+    /** Box edge in px. Default 20. */
+    size?: number;
+    /** Extra classes. */
+    className?: string;
+}
+/** A flat outlined icon container — a thumbnail stand-in when there is no thumbnail. */
+declare function IconFrame({ icon, size, className }: IconFrameProps): ReactNode;
+/** Props for {@link StatTile}. */
+interface StatTileProps {
+    /** Uppercase label. */
+    label: ReactNode;
+    /** The value. Rendered with `tabular-nums` so a grid of tiles aligns. */
+    value: ReactNode;
+    /** Supporting line under the value (delta, window, unit). */
+    sub?: ReactNode;
+    /** Trailing glyph in the label row. */
+    icon?: ReactNode;
+    /** Native tooltip — where a metric's longer explanation goes. */
+    title?: string;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * Label + big value tile — the KPI unit of the future `metrics` panel.
+ *
+ * @example
+ * ```tsx
+ * <StatTile label="p95 frame" value="14.2 ms" sub="last 60 s" />
+ * ```
+ */
+declare function StatTile({ label, value, sub, icon, title, className }: StatTileProps): ReactNode;
+/** One slice of a {@link ProportionBar}. */
+interface ProportionSegment {
+    /** Relative magnitude. Non-positive values are skipped. */
+    value: number;
+    /** White alpha for this slice, `0`–`1`. Distinguish slices by OPACITY, not hue. */
+    opacity?: number;
+    /** Native tooltip. */
+    label?: string;
+    /** Stable key when the caller has one. */
+    key?: string;
+}
+/** Props for {@link ProportionBar}. */
+interface ProportionBarProps {
+    /** The slices, in display order. */
+    segments: ReadonlyArray<ProportionSegment>;
+    /** Accessible description of the whole bar. */
+    label?: string;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A horizontal stacked bar — the monochromatic replacement for a pie/donut chart.
+ *
+ * Slices are separated by white ALPHA, not hue: `DESIGN_SYSTEM.md` §13 forbids chromatic color
+ * outside status contexts, and a categorical palette is exactly that. When no `opacity` is supplied
+ * the bar ramps evenly from bright to dim across the slices.
+ */
+declare function ProportionBar({ segments, label, className }: ProportionBarProps): ReactNode;
+/** Props for {@link StatusBar}. */
+interface StatusBarProps {
+    /** Left cluster — counts, selection summary. */
+    left?: ReactNode;
+    /** Right cluster — mode, state. */
+    right?: ReactNode;
+    /** Free-form children (used instead of the clusters). */
+    children?: ReactNode;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * The panel footer strip. Census: layers and history already ship a byte-identical one
+ * (`2px 6px`, 9px, muted, header surface, space-between) — this is that, once.
+ */
+declare function StatusBar({ left, right, children, className }: StatusBarProps): ReactNode;
+/** Props for {@link Sparkline}. */
+interface SparklineProps {
+    /** The series, oldest first. */
+    data: readonly number[];
+    /** Width in px. */
+    width?: number;
+    /** Height in px. */
+    height?: number;
+    /** Accessible description. Without one the mark is decorative and hidden from AT. */
+    label?: string;
+    /** Native tooltip. */
+    title?: string;
+    /** Extra classes. */
+    className?: string;
+}
+/**
+ * A monochrome trend line.
+ *
+ * Lifted from `xeno-post`'s `ui/kit.tsx`, which is the only sparkline implementation in the
+ * ecosystem. It lives here rather than in a panel because three consumers want it — `metrics` (which
+ * shipped a local copy first), `chart`, and the future `runs` panel — and three copies of a mark is
+ * how a design system stops being one.
+ *
+ * Distinct from {@link ProportionBar}: a line is a different MARK, not a variant. The two are not
+ * interchangeable and neither is a special case of the other.
+ *
+ * Degenerate inputs render an empty well rather than throwing: a series of one point has no slope,
+ * and a flat series has no range to normalize against (it draws a centred straight line).
+ */
+declare function Sparkline({ data, width, height, label, title, className, }: SparklineProps): ReactNode;
+
+/**
+ * Zero-config stylesheet injection for the React primitives.
+ *
+ * Every primitive calls {@link usePanelPrimitives} so a panel author needs **no CSS import** — the
+ * canonical stylesheet lands in `<head>` the first time any primitive renders, exactly once per
+ * document. Injection happens in a `useState` LAZY INITIALIZER (during the first render) rather
+ * than in `useEffect`, so the styles are present before paint — an effect would flash unstyled
+ * chrome. The initializer is idempotent and guarded by an element id, so React StrictMode's
+ * double-invoke is harmless.
+ *
+ * @module
+ */
+/**
+ * Ensure the primitives stylesheet is present in the document.
+ *
+ * Safe to call from any number of components and on the server (where it is a no-op).
+ */
+declare function usePanelPrimitives(): void;
+
+/**
+ * The canonical panel GEOMETRY constants — the single source of truth for both the stylesheet and
+ * any panel that needs a measurement as a NUMBER (virtualizers, hit-testing, canvas overlays).
+ *
+ * `PANEL_PRIMITIVES_CSS` is generated by interpolating this object, so the CSS and the JS can never
+ * drift. That matters: a virtualized list computes its scroll geometry from a row height in JS while
+ * the row is sized by CSS — when those two numbers disagree you get a list that scrolls to the wrong
+ * item, and it is invisible until someone changes one of them.
+ *
+ * ## Where these numbers come from
+ *
+ * Every value below was chosen from a census of the five shipped canonical panels (color, layers,
+ * history, inspector, transport) plus `xeno-workflow`'s CSS contract and `xeno-post`'s kit. Where the
+ * five agreed, the consensus value is used verbatim. Where they disagreed, the choice is annotated
+ * with what the alternatives were, so a future reader can see it was a decision and not a guess.
+ *
+ * @module
+ */
+/**
+ * Canonical panel metrics, in CSS pixels.
+ *
+ * @example
+ * ```ts
+ * // A virtualizer that cannot drift from the stylesheet:
+ * const first = Math.floor(scrollTop / PANEL_METRICS.rowHeight)
+ * ```
+ */
+declare const PANEL_METRICS: Readonly<{
+    /**
+     * Dense list row height.
+     *
+     * Census: history 22, layers 24, inspector 20 (as `min-height`). 22 is the median and the value
+     * of the densest *scrolling* list. Override per-list with `--xeno-row-h` — layers can keep 24
+     * without forking the primitive.
+     */
+    readonly rowHeight: 22;
+    /** Indent per tree depth level. Census: layers 10 (the only implementation). */
+    readonly rowIndent: 10;
+    /** Gap between a row's slots. Census: layers 4, inspector 4, history 5. */
+    readonly rowGap: 4;
+    /** Fixed width of a row's leading icon slot — this is what keeps labels in ONE column. */
+    readonly rowIconSlot: 14;
+    /** Horizontal padding inside panel chrome. Census: `0 6px` / `4px 6px`, 6px in 5/5 packages. */
+    readonly gutter: 6;
+    /** Vertical padding of a header/toolbar strip. Census: `4px 6px` in 4/5 packages. */
+    readonly stripPadY: 4;
+    /**
+     * Minimum height of a toolbar strip. Not set by any panel today (all are content-sized); 26 is
+     * what `4 + 18 + 4` already produces, pinned so toolbars align across panels.
+     */
+    readonly toolbarMinHeight: 26;
+    /** Footer / status strip padding-y. Census: `2px 6px`, identical in layers + history. */
+    readonly footerPadY: 2;
+    /** Section header height. Census: inspector 20 (the only real section header in the catalog). */
+    readonly sectionHeaderHeight: 20;
+    /**
+     * Dense control height (inputs, segmented control, toolbar buttons).
+     *
+     * Census: inspector 18, history 18, transport 18, layers 20. **This is BELOW `DESIGN_SYSTEM.md`
+     * §3.1's 24px "compact" floor** — see {@link PANEL_METRICS.controlHeight}. 20 is the largest value
+     * any shipped panel uses, so adopting the primitives never makes a panel denser than it is today.
+     */
+    readonly controlHeightSm: 20;
+    /** Standard control height — the DESIGN_SYSTEM §3.1 "compact controls" value. Use in panel bodies. */
+    readonly controlHeight: 24;
+    /** In-row icon button. Census: inspector 14, layers 14, history 16. 14 is below a usable hit target. */
+    readonly iconButtonSm: 16;
+    /** Toolbar icon button. Census: transport 20×18, color 22. */
+    readonly iconButton: 20;
+    /** Icon glyph inside a `sm` button. Census: 11 is the most common glyph size across four packages. */
+    readonly iconGlyphSm: 11;
+    /** Icon glyph inside an `md` button. Census: layers + transport primary use 12. */
+    readonly iconGlyph: 12;
+    /** Badge height. Census: inspector + history byte-identical at 12. */
+    readonly badgeHeight: 12;
+    /** Standard badge height — the `DESIGN_SYSTEM.md` §7 "Status Badges / Pills" value. */
+    readonly badgeHeightMd: 18;
+    /** Square status dot edge. Never a circle (DESIGN_SYSTEM §3). */
+    readonly dotSize: 6;
+    /** Shared label-column width in a `FieldGroup`. Census: inspector's configurable default is 56. */
+    readonly fieldLabelWidth: 56;
+    /** Base corner radius. Census: `border-radius: 2` appears 38 times across 5/5 packages. */
+    readonly radius: 2;
+    /** Outer-container radius (frames, cards). DESIGN_SYSTEM §7 "small radius". */
+    readonly radiusMd: 6;
+    /** Micro text — badges, units. */
+    readonly fontMicro: 8;
+    /** Label text — uppercase section/panel labels, footers. */
+    readonly fontLabel: 9;
+    /** Secondary text — metadata, empty-state titles. */
+    readonly fontMeta: 10;
+    /** Body text — the default panel size. */
+    readonly fontBody: 11;
+}>;
+/** The type of {@link PANEL_METRICS}. */
+type PanelMetrics = typeof PANEL_METRICS;
+/**
+ * Canonical color literals used by the stylesheet, exported for panels that must compute a color in
+ * JS (canvas overlays, inline gradients) rather than declare it in CSS.
+ *
+ * Every one is either a `DESIGN_SYSTEM.md` token or the census consensus. The two status reds are
+ * spelled once here because the shipped panels currently disagree (`#ef4444` vs
+ * `rgba(239,68,68,0.65)`).
+ */
+declare const PANEL_COLORS: Readonly<{
+    /** Row hover fill. DESIGN_SYSTEM §2 `rowHover`. **No shipped panel has a hover state at all.** */
+    readonly rowHover: "rgba(255,255,255,0.05)";
+    /** Row selected fill. Census: byte-identical in layers + history. */
+    readonly rowSelected: "rgba(255,255,255,0.10)";
+    /** Active/focus ring. Census: byte-identical `inset 0 0 0 1px` in layers + history. */
+    readonly ring: "rgba(255,255,255,0.15)";
+    /** Keyboard focus outline. DESIGN_SYSTEM §11. **No shipped panel has one.** */
+    readonly focus: "rgba(255,255,255,0.25)";
+    /** Recessed well fill for inputs. Census: 4/5 packages. */
+    readonly well: "rgba(0,0,0,0.3)";
+    /** Hairline border. */
+    readonly border: "rgba(255,255,255,0.08)";
+    /** Soft raised fill — chips, ghost buttons. Census: 5/5 packages. */
+    readonly soft: "rgba(255,255,255,0.06)";
+    /** Section-header wash. Census: inspector. */
+    readonly wash: "rgba(255,255,255,0.03)";
+    /** Solid status red (indicators). DESIGN_SYSTEM §2 `error`. */
+    readonly error: "#ef4444";
+    /** Status red for TEXT. DESIGN_SYSTEM §2 `error.text`. */
+    readonly errorText: "rgba(239,68,68,0.65)";
+    /** Status amber for text. */
+    readonly warningText: "rgba(245,158,11,0.65)";
+    /** Status green for text. */
+    readonly successText: "#5a9a6a";
+    /** Info blue-gray for text (the dimmest permitted chroma). */
+    readonly infoText: "#7aa2c4";
+}>;
+/** The type of {@link PANEL_COLORS}. */
+type PanelColors = typeof PANEL_COLORS;
+/**
+ * The opacity a disabled / "off" control drops to.
+ *
+ * Census: the five panels hand-wrote **eleven** different opacity pairs for this; `0.35` is the most
+ * frequent "off" value (layers lock, layers toggle-chip, inspector stopwatch, inspector reset).
+ */
+declare const PANEL_DISABLED_OPACITY = 0.35;
+
+/**
+ * The canonical panel-chrome stylesheet, as a string (the single source of truth).
+ *
+ * Generated by interpolating {@link PANEL_METRICS} / {@link PANEL_COLORS} so the CSS can never drift
+ * from the numbers panels read in JS. `@xenosystem/workbench/primitives.css` is emitted from this at build
+ * time for hosts that prefer a `<link>` / bundler import over runtime injection.
+ *
+ * ## Two invariants, both test-enforced
+ *
+ * 1. **Every `var()` carries a literal fallback.** The primitives must render correctly with NO
+ *    theme injected — a product embedding one canonical panel into its own chrome gets the right
+ *    look without adopting the workbench theme. The `--panel-*` → `--xeno-*` → literal chain is the
+ *    one 4 of the 5 shipped panels already use, so tokens set by either convention win.
+ * 2. **Selectors are flat.** No `:has()`, no multi-level `:not()` chains — `DESIGN_SYSTEM.md` §3.1
+ *    records that Lightning CSS / Turbopack silently drop those rule blocks at build time.
+ *
+ * ## Three gaps this sheet closes
+ *
+ * The census of the five shipped panels found NO hover state, NO focus-visible state, and no shared
+ * disabled treatment (eleven hand-written opacity pairs) anywhere in the catalog. Those are defined
+ * here once, so every panel built on the primitives gets them for free.
+ *
+ * @module
+ */
+/** The canonical panel-chrome stylesheet. */
+declare const PANEL_PRIMITIVES_CSS: string;
+
+/**
+ * Idempotent injector for the panel-primitives stylesheet.
+ *
+ * Mirrors `ensureWorkbenchThemeInjected` (same `StyleInjectTarget` shape, same element-id
+ * idempotency key) but ships the PRIMITIVES sheet, which is independent of the Dockview theme:
+ * a product embedding a single canonical panel outside the workbench needs the primitives and NOT
+ * the dock chrome.
+ *
+ * @module
+ */
+/** The `<style>` element id used for runtime injection (idempotency key). */
+declare const PANEL_PRIMITIVES_STYLE_ID = "xeno-panel-primitives";
+/** Minimal structural shape of the `document` bits the injector needs (for testability/SSR). */
+interface PrimitivesInjectTarget {
+    getElementById(id: string): unknown;
+    createElement(tagName: 'style'): {
+        id: string;
+        textContent: string | null;
+    };
+    head: {
+        appendChild(node: unknown): void;
+    } | null;
+}
+/**
+ * Inject the primitives stylesheet ONCE into a document head (idempotent by element id).
+ *
+ * @param target - The document (defaults to `globalThis.document`; injectable for tests).
+ * @returns `true` if a `<style>` was inserted; `false` if already present or no document.
+ *
+ * @example
+ * ```ts
+ * // Optional: inject early, before any panel renders.
+ * ensurePanelPrimitivesInjected()
+ * ```
+ */
+declare function ensurePanelPrimitivesInjected(target?: PrimitivesInjectTarget): boolean;
+
+/**
+ * `COMPONENTS` — the chrome family's units by their `chrome/Unit` names, for a block declaration's registry
+ * (`@xenosystem/block-sdk`). One map per family, merged by the host; nothing is registered by hand elsewhere.
+ */
+
+declare const COMPONENTS: {
+    readonly 'chrome/IconButton': typeof IconButton;
+    readonly 'chrome/TextButton': typeof TextButton;
+    readonly 'chrome/SearchField': typeof SearchField;
+    readonly 'chrome/SegmentedControl': typeof SegmentedControl;
+    readonly 'chrome/Toggle': typeof Toggle;
+    readonly 'chrome/FieldGroup': typeof FieldGroup;
+    readonly 'chrome/Field': typeof Field;
+    readonly 'chrome/SearchGlyph': typeof SearchGlyph;
+    readonly 'chrome/ClearGlyph': typeof ClearGlyph;
+    readonly 'chrome/ChevronGlyph': typeof ChevronGlyph;
+    readonly 'chrome/PanelFrame': typeof PanelFrame;
+    readonly 'chrome/Toolbar': typeof Toolbar;
+    readonly 'chrome/ToolbarGroup': typeof ToolbarGroup;
+    readonly 'chrome/Divider': typeof Divider;
+    readonly 'chrome/ScrollArea': typeof ScrollArea;
+    readonly 'chrome/Badge': typeof Badge;
+    readonly 'chrome/StatusDot': typeof StatusDot;
+    readonly 'chrome/StatusBadge': typeof StatusBadge;
+    readonly 'chrome/IconFrame': typeof IconFrame;
+    readonly 'chrome/StatTile': typeof StatTile;
+    readonly 'chrome/ProportionBar': typeof ProportionBar;
+    readonly 'chrome/StatusBar': typeof StatusBar;
+    readonly 'chrome/Sparkline': typeof Sparkline;
+    readonly 'chrome/RowList': typeof RowList;
+    readonly 'chrome/Row': typeof Row;
+    readonly 'chrome/Section': typeof Section;
+    readonly 'chrome/EmptyState': typeof EmptyState;
+    readonly 'chrome/LoadingState': typeof LoadingState;
+    readonly 'chrome/ErrorState': typeof ErrorState;
+};
+
+/**
+ * `gallery()` — every unit of the CHROME family in every state, as renderable entries: the toolbar, the
+ * search field, the rows, the empty/loading/error states and the indicators every block is built from.
+ * This is what the workshop renders from source, the library shows read-only, and the gate screenshots.
+ *
+ * `render` is pure: fixture props in, element out, callbacks inert. Nothing here reaches a host.
+ */
+
+interface GalleryEntry {
+    family: 'chrome';
+    unit: string;
+    state: string;
+    /** `form` (a 400 px column) or `door` (fills a box) — the same staging vocabulary as the auth family. */
+    stage: 'form' | 'door';
+    render: () => ReactElement;
+}
+/** The entries, one per unit × state. Adding a unit to {@link COMPONENTS} without an entry here fails the family's test. */
+declare function gallery(): GalleryEntry[];
+
+export { Badge, type BadgeProps, CLS_BADGE, CLS_BAR, CLS_BAR_SEGMENT, CLS_DIVIDER, CLS_DOT, CLS_EMPTY, CLS_ERROR, CLS_FIELD, CLS_FIELD_CONTROL, CLS_FIELD_GROUP, CLS_FIELD_HINT, CLS_FIELD_LABEL, CLS_ICON_BUTTON, CLS_ICON_FRAME, CLS_LOADING, CLS_PANEL, CLS_PANEL_CONTENT, CLS_PANEL_CONTENT_NO_HEADER, CLS_PANEL_HEADER, CLS_PANEL_TITLE, CLS_ROW, CLS_ROWLIST, CLS_ROW_ICON, CLS_ROW_LABEL, CLS_ROW_META, CLS_ROW_TRAILING, CLS_SCROLL, CLS_SEARCH, CLS_SEARCH_INPUT, CLS_SECTION, CLS_SECTION_ACTIONS, CLS_SECTION_BODY, CLS_SECTION_CHEVRON, CLS_SECTION_HEADER, CLS_SECTION_TITLE, CLS_SECTION_TRIGGER, CLS_SEGMENT, CLS_SEGMENTED, CLS_STAT, CLS_STATE, CLS_STATE_HINT, CLS_STATE_ICON, CLS_STATE_PROGRESS, CLS_STATE_TITLE, CLS_STATUSBAR, CLS_STAT_LABEL, CLS_STAT_SUB, CLS_STAT_VALUE, CLS_TEXT_BUTTON, CLS_TOGGLE, CLS_TOGGLE_KNOB, CLS_TOOLBAR, CLS_TOOLBAR_GROUP, COMPONENTS, ChevronGlyph, ClearGlyph, Divider, type DividerProps, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, Field, FieldGroup, type FieldGroupProps, type FieldProps, type GalleryEntry, IconButton, type IconButtonProps, IconFrame, type IconFrameProps, LoadingState, type LoadingStateProps, PANEL_COLORS, PANEL_DISABLED_OPACITY, PANEL_METRICS, PANEL_PRIMITIVES_CSS, PANEL_PRIMITIVES_STYLE_ID, PANEL_TONES, type PanelColors, PanelFrame, type PanelFrameProps, type PanelMetrics, type PanelTone, type PrimitivesInjectTarget, ProportionBar, type ProportionBarProps, type ProportionSegment, Row, RowList, type RowListProps, type RowProps, type RowState, ScrollArea, type ScrollAreaProps, SearchField, type SearchFieldProps, SearchGlyph, Section, type SectionProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Sparkline, type SparklineProps, StatTile, type StatTileProps, StatusBadge, type StatusBadgeProps, StatusBar, type StatusBarProps, StatusDot, type StatusDotProps, TextButton, type TextButtonProps, Toggle, type ToggleProps, Toolbar, ToolbarGroup, type ToolbarGroupProps, type ToolbarProps, badgeClass, cx, dotClass, ensurePanelPrimitivesInjected, gallery, iconButtonClass, nextSegmentValue, rowClass, sectionClass, usePanelPrimitives };