@volter/editor-sdk 0.5.57

package/src/widgets/inspector-widgets/curve-utils.ts

@@ -0,0 +1,212 @@
+/**
+ * Pure curve math for `CurveEditor` (W1b) — piecewise cubic-bezier
+ * value-over-normalized-time curves, structurally identical to the engine's
+ * `PiecewiseBezier` schema shape (`schema/particles.ts`) and to three.quarks'
+ * own `PiecewiseBezier` JSON: segment `i` spans `[start_i, start_{i+1}]`
+ * (the last segment ends at 1), and `p0..p3` are VALUE control points over
+ * the segment's normalized time — i.e. the plotted curve is an exact SVG
+ * cubic with x-controls at 1/3 and 2/3 of the segment width.
+ *
+ * Kept editor-generic (no particle imports): any future consumer uses the
+ * same helpers.
+ */
+
+export interface CurveBezier {
+  p0: number;
+  p1: number;
+  p2: number;
+  p3: number;
+}
+
+export interface CurveSegment {
+  function: CurveBezier;
+  start: number;
+}
+
+export interface CurveKey {
+  time: number;
+  value: number;
+}
+
+/** End time of segment `i` — the next segment's start, or 1 for the last. */
+export function segmentEnd(segments: CurveSegment[], i: number): number {
+  return i + 1 < segments.length ? segments[i + 1]!.start : 1;
+}
+
+/**
+ * The curve's keys (n segments → n+1 keys): key `i` sits at segment `i`'s
+ * start with value `p0`; the final key sits at t=1 with the last `p3`.
+ */
+export function curveKeys(segments: CurveSegment[]): CurveKey[] {
+  const keys: CurveKey[] = segments.map((s) => ({ time: s.start, value: s.function.p0 }));
+  const last = segments[segments.length - 1];
+  if (last) keys.push({ time: 1, value: last.function.p3 });
+  return keys;
+}
+
+function cloneSegments(segments: CurveSegment[]): CurveSegment[] {
+  return segments.map((s) => ({ start: s.start, function: { ...s.function } }));
+}
+
+const MIN_SEGMENT_WIDTH = 0.01;
+
+/**
+ * Move key `keyIndex` to (time, value). Endpoint keys are time-locked (first
+ * to its own start, last to 1); interior key times clamp between neighbors.
+ * Tangent control values (p1/p2) shift WITH their endpoint so the curve's
+ * local shape is preserved.
+ */
+export function moveKey(
+  segments: CurveSegment[],
+  keyIndex: number,
+  time: number,
+  value: number,
+): CurveSegment[] {
+  const next = cloneSegments(segments);
+  const n = next.length;
+  if (keyIndex < 0 || keyIndex > n) return next;
+
+  if (keyIndex < n) {
+    // Key owns segment keyIndex's start/p0 (and the previous segment's p3).
+    const seg = next[keyIndex]!;
+    const dv = value - seg.function.p0;
+    seg.function.p0 = value;
+    seg.function.p1 += dv;
+    if (keyIndex > 0) {
+      const prev = next[keyIndex - 1]!;
+      const dvPrev = value - prev.function.p3;
+      prev.function.p3 = value;
+      prev.function.p2 += dvPrev;
+      // Interior keys may move in time, clamped between neighbors.
+      const lo = prev.start + MIN_SEGMENT_WIDTH;
+      const hi = segmentEnd(next, keyIndex) - MIN_SEGMENT_WIDTH;
+      seg.start = Math.min(hi, Math.max(lo, time));
+    }
+  } else {
+    // Final key: last segment's p3, time locked at 1.
+    const seg = next[n - 1]!;
+    const dv = value - seg.function.p3;
+    seg.function.p3 = value;
+    seg.function.p2 += dv;
+  }
+  return next;
+}
+
+/**
+ * Move a tangent control value of key `keyIndex`: `out` = its segment's p1
+ * (exists for every key but the last), `in` = the previous segment's p2
+ * (exists for every key but the first).
+ */
+export function moveTangent(
+  segments: CurveSegment[],
+  keyIndex: number,
+  which: 'in' | 'out',
+  value: number,
+): CurveSegment[] {
+  const next = cloneSegments(segments);
+  if (which === 'out' && keyIndex < next.length) {
+    next[keyIndex]!.function.p1 = value;
+  } else if (which === 'in' && keyIndex > 0 && keyIndex <= next.length) {
+    next[keyIndex - 1]!.function.p2 = value;
+  }
+  return next;
+}
+
+function lerp(a: number, b: number, u: number): number {
+  return a + (b - a) * u;
+}
+
+/** Evaluate the curve at normalized time t (matches quarks' genValue). */
+export function sampleCurve(segments: CurveSegment[], t: number): number {
+  for (let i = 0; i < segments.length; i++) {
+    const start = segments[i]!.start;
+    const end = segmentEnd(segments, i);
+    if (t >= start && t <= end) {
+      const u = end > start ? (t - start) / (end - start) : 0;
+      const { p0, p1, p2, p3 } = segments[i]!.function;
+      const b01 = lerp(p0, p1, u);
+      const b12 = lerp(p1, p2, u);
+      const b23 = lerp(p2, p3, u);
+      const b012 = lerp(b01, b12, u);
+      const b123 = lerp(b12, b23, u);
+      return lerp(b012, b123, u);
+    }
+  }
+  return 0;
+}
+
+/**
+ * Insert a key at time `t` by de Casteljau subdivision of the containing
+ * segment — the curve's shape is EXACTLY preserved. Returns the input
+ * unchanged when `t` falls outside the curve or too close to an existing key.
+ */
+export function splitAt(segments: CurveSegment[], t: number): CurveSegment[] {
+  for (let i = 0; i < segments.length; i++) {
+    const start = segments[i]!.start;
+    const end = segmentEnd(segments, i);
+    if (t <= start + MIN_SEGMENT_WIDTH || t >= end - MIN_SEGMENT_WIDTH) continue;
+    if (t < start || t > end) continue;
+    const u = (t - start) / (end - start);
+    const { p0, p1, p2, p3 } = segments[i]!.function;
+    const b01 = lerp(p0, p1, u);
+    const b12 = lerp(p1, p2, u);
+    const b23 = lerp(p2, p3, u);
+    const b012 = lerp(b01, b12, u);
+    const b123 = lerp(b12, b23, u);
+    const mid = lerp(b012, b123, u);
+    const next = cloneSegments(segments);
+    next.splice(
+      i,
+      1,
+      { start, function: { p0, p1: b01, p2: b012, p3: mid } },
+      { start: t, function: { p0: mid, p1: b123, p2: b23, p3 } },
+    );
+    return next;
+  }
+  return segments;
+}
+
+/**
+ * Delete interior key `keyIndex`, merging its two adjacent segments. The
+ * merged bezier keeps both outer endpoints and rescales the outer tangent
+ * controls so endpoint SLOPES are preserved (the interior wiggle is
+ * re-fitted — same approximation Unity's curve editor makes). Endpoint keys
+ * are not deletable; returns the input unchanged for them.
+ */
+export function deleteKey(segments: CurveSegment[], keyIndex: number): CurveSegment[] {
+  if (keyIndex <= 0 || keyIndex >= segments.length) return segments;
+  const left = segments[keyIndex - 1]!;
+  const right = segments[keyIndex]!;
+  const leftDur = right.start - left.start;
+  const rightDur = segmentEnd(segments, keyIndex) - right.start;
+  const total = leftDur + rightDur;
+  if (total <= 0) return segments;
+  const lf = left.function;
+  const rf = right.function;
+  const merged: CurveSegment = {
+    start: left.start,
+    function: {
+      p0: lf.p0,
+      p1: lf.p0 + (lf.p1 - lf.p0) * (leftDur > 0 ? total / leftDur : 1),
+      p2: rf.p3 + (rf.p2 - rf.p3) * (rightDur > 0 ? total / rightDur : 1),
+      p3: rf.p3,
+    },
+  };
+  const next = cloneSegments(segments);
+  next.splice(keyIndex - 1, 2, merged);
+  return next;
+}
+
+/** Min/max over every control value (bezier hull bounds the curve). */
+export function curveValueRange(segments: CurveSegment[]): { min: number; max: number } {
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const s of segments) {
+    for (const v of [s.function.p0, s.function.p1, s.function.p2, s.function.p3]) {
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return { min: 0, max: 1 };
+  return { min, max };
+}

package/src/widgets/inspector-widgets/index.ts

@@ -0,0 +1,24 @@
+/**
+ * The figma-grade inspector widget kit (spec 27 §5 C1). PURE,
+ * contract-driven components — `value` + `onChange` (+ optional
+ * `onChangeEnd` for the commit tick, see `shared.tsx`'s `ChangeHandlers<T>`
+ * doc comment). The kit stays contract-pure: widgets never import editor
+ * state, which is what lets the whole directory sit in the Apache face.
+ *
+ * This is an INTERNAL barrel — `../index.ts` is the published door
+ * (`@volter/editor-sdk/widgets`), and it re-exports this whole surface.
+ */
+
+export * from './AlignmentGrid';
+export * from './AssetSlotPicker';
+export * from './BorderEditor';
+export * from './ColorPicker';
+export * from './CurveEditor';
+export type { ColorFormat } from './color-utils';
+export * from './curve-utils';
+export * from './FilterEditor';
+export * from './FontPicker';
+export * from './GradientEditor';
+export * from './ScrubbableInput';
+export * from './ShadowEditor';
+export * from './shared';

package/src/widgets/inspector-widgets/shared.tsx

@@ -0,0 +1,140 @@
+import { Button } from '../design-system';
+/**
+ * Shared theme + tiny primitives for the inspector widget kit (spec 27 §5
+ * C1). Values are now sourced from `../../theme.ts` (editor-style-polish
+ * U0) — the editor's single canonical token module — rather than
+ * independently retyped here, which is how this kit's accent had drifted
+ * from the app's semantic accent (C-2).
+ * `THEME.accent` now follows whichever palette is composed with the active
+ * material. `FONT` also drops
+ * `'Inter'` (never loaded anywhere — 0 `@font-face` hits — so it only ever
+ * silently fell back to its own fallback chain, per finding I-29); `FONT`/
+ * `FONT_MONO` now resolve through the editor theme variables. Interactive
+ * controls themselves come from the canonical design-system primitives so
+ * this helper module cannot create a competing inline paint recipe.
+ */
+
+import type React from 'react';
+import { themeVars } from '../design-system';
+
+export const THEME = {
+  bg: themeVars.surface.panel,
+  surface: themeVars.surface.chrome,
+  surfaceHover: themeVars.surface.raised,
+  border: themeVars.boundary.default,
+  text: themeVars.content.primary,
+  textMuted: themeVars.content.muted,
+  onAccent: themeVars.content.onAccent,
+  accent: themeVars.accent.default,
+  neutralHover: themeVars.neutralOverlay.hover,
+  radiusSmall: themeVars.shape.small,
+  radiusMedium: themeVars.shape.medium,
+  inputBg: themeVars.surface.inset,
+  dynamic: themeVars.semantic.dynamic,
+  dynamicBg: themeVars.semantic.dynamicMuted,
+} as const;
+
+export const FONT = themeVars.typography.sans;
+export const FONT_MONO = themeVars.typography.mono;
+
+/**
+ * Every widget's change contract (report §"prop shape" for the C2 wiring
+ * step): `onChange` fires on every interaction tick (drag/scrub/keystroke —
+ * the LIVE PREVIEW a caller can apply immediately, mirroring `boxEdit.apply`/
+ * `inspector.set`'s optimistic echo, T0 §2/A4); `onChangeEnd` fires once per
+ * gesture (pointerup/blur/Enter — the COMMIT a caller should push through
+ * `writeStyleAuto`/`inspector.set` as a single undo step, mirroring
+ * `BoxEditProvider.end`). A caller that only cares about single-shot edits
+ * (a `<Select>`, a click) may omit `onChangeEnd` — widgets fall back to
+ * treating `onChange` as the commit in that case.
+ */
+export interface ChangeHandlers<T> {
+  value: T;
+  onChange: (value: T) => void;
+  onChangeEnd?: ((value: T) => void) | undefined;
+  disabled?: boolean | undefined;
+}
+
+export function fireChange<T>(handlers: Pick<ChangeHandlers<T>, 'onChange'>, value: T): void {
+  handlers.onChange(value);
+}
+
+export function fireEnd<T>(
+  handlers: Pick<ChangeHandlers<T>, 'onChange' | 'onChangeEnd'>,
+  value: T,
+): void {
+  (handlers.onChangeEnd ?? handlers.onChange)(value);
+}
+
+export const rowStyle: React.CSSProperties = { display: 'flex', alignItems: 'center', gap: 4 };
+
+/* ------------------------------------------------------------------------ */
+/* Inspector-section style kit (editor-style-polish U3, I-8/I-10/I-12/I-13/  */
+/* I-17/I-22) — the ONE home for the style objects the first-party sections  */
+/* used to hand-duplicate ~15 times each with tiny unintentional drift.      */
+/* ------------------------------------------------------------------------ */
+
+/** Stacked field label ("label on its own line, field below" grammar) —
+ *  replaces the `{fontSize:10, color:'#8c8c8c', marginBottom:2}` literal
+ *  re-authored in nearly every `components/inspectors/*` section (I-8). */
+export const fieldLabelStyle: React.CSSProperties = {
+  fontSize: 'var(--vgai-font-sm)',
+  color: themeVars.content.muted,
+  marginBottom: 2,
+};
+
+/** Sub-header / group label ("label over a related cluster of fields") — the
+ *  ONE treatment for what used to be four (I-12): `Inspector.tsx`'s generic
+ *  group header (11/600/uppercase/ls 0.4/#9aa0a6 — the incumbent this
+ *  standardizes on), `ParticleSection.subHeaderStyle`,
+ *  `PostProcessingSection.effectLabel`, and `MaterialSection`'s Textures. */
+export const groupLabelStyle: React.CSSProperties = {
+  fontSize: 'var(--vgai-font-base)',
+  fontWeight: 600,
+  color: themeVars.content.muted,
+  textTransform: 'uppercase',
+  letterSpacing: 0.4,
+};
+
+/** One label-column width for every label-left/field-right row (I-13 —
+ *  replaces the 56/64/70/76/80 ladder across Inspector.tsx/`Field`/
+ *  `ComponentsSection`). */
+export const LABEL_COL_WIDTH = 72;
+
+export function ToggleButton({
+  label,
+  active,
+  disabled,
+  onClick,
+  testId,
+}: {
+  label: React.ReactNode;
+  active: boolean;
+  disabled?: boolean | undefined;
+  onClick: () => void;
+  testId?: string | undefined;
+}): React.ReactElement {
+  return (
+    <Button
+      variant={active ? 'primary' : 'secondary'}
+      size="compact"
+      aria-pressed={active}
+      disabled={disabled}
+      data-testid={testId}
+      onClick={() => {
+        if (!disabled) onClick();
+      }}
+      style={{ flex: 1 }}
+    >
+      {label}
+    </Button>
+  );
+}
+
+/** `parseNumericValue('12.5px') -> {num: 12.5, unit: 'px'}` (visual-edit :98). */
+export function parseNumericValue(value: string): { num: number; unit: string } {
+  const match = value.match(/^(-?\d+\.?\d*)\s*(px|em|rem|%|vh|vw|deg|s|ms)?$/);
+  if (match) return { num: Number.parseFloat(match[1] ?? '0'), unit: match[2] || '' };
+  const num = Number.parseFloat(value);
+  return { num: Number.isNaN(num) ? 0 : num, unit: '' };
+}

package/src/widgets/interactive-edit-scope.ts

@@ -0,0 +1,33 @@
+/**
+ * Interactive-edit (undo-gesture) scope — the ONE thing the shared input
+ * primitives (`primitives/NumberInput.tsx` / `primitives/ColorInput.tsx`)
+ * need from the editor: "a continuous gesture (scrub / color drag) starts /
+ * ends now, coalesce it into a single undo step".
+ *
+ * Split out of the editor's `EditorContext.tsx`: the widget kit is a public
+ * export (`@volter/editor-sdk/widgets`) that scaffolded PROJECTS typecheck — importing
+ * `EditorContext` (and through it `EditorShellStore` and most of the editor)
+ * from a widget would drag the whole editor source graph into every project's
+ * `tsc`. This module's closure is react-only; `EditorProvider` bridges it to
+ * the real store (`beginInteractiveEdit`/`endInteractiveEdit`).
+ *
+ * Widgets consume it optionally (`useInteractiveEditScope()` returns `null`
+ * outside a provider — e.g. the widget gallery, or a project tool rendered
+ * in some future host): no scope simply means no undo coalescing.
+ */
+
+import { createContext, useContext } from 'react';
+
+/** Begin/end a coalesced interactive edit gesture (one undo step). Both are
+ *  idempotent in the editor's implementation — safe to call defensively. */
+export interface InteractiveEditScope {
+  begin(): void;
+  end(): void;
+}
+
+export const InteractiveEditScopeContext = createContext<InteractiveEditScope | null>(null);
+
+/** The ambient gesture scope, or `null` when no host provides one. */
+export function useInteractiveEditScope(): InteractiveEditScope | null {
+  return useContext(InteractiveEditScopeContext);
+}

package/src/widgets/patterns/Dialog.tsx

@@ -0,0 +1,129 @@
+import { type HTMLAttributes, type LabelHTMLAttributes, type ReactNode, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Actions, Inline, Stack } from '../primitives/Layout';
+import { Text } from '../primitives/Text';
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+export interface DialogProps extends HTMLAttributes<HTMLDivElement> {
+  labelledBy: string;
+  onDismiss?: () => void;
+  size?: 'compact' | 'default' | 'wide';
+  variant?: 'default' | 'command';
+}
+
+/** Modal editor surface. The scrim, sizing, elevation, and spacing are one recipe. */
+export function Dialog({
+  labelledBy,
+  onDismiss,
+  size = 'default',
+  variant = 'default',
+  className,
+  ...props
+}: DialogProps) {
+  // F10/F11 (U6.5): the `position: fixed` scrim must anchor to the window, not
+  // to whatever ancestor happens to be its containing block. Rendered inline it
+  // sat inside `#editor-root` (z-index 10), so the islands-mode footer/session
+  // tray (`#editor-bottom`, z-index 100) painted OVER the scrim (F10); and under
+  // a glass theme a card's `backdrop-filter` became the fixed scrim's containing
+  // block, collapsing `inset: 0` to a ~40px box and shoving the dialog off the
+  // top edge (F11). Portaling to the filter-free theme root — a sibling of
+  // `#editor-bottom` — makes `inset: 0` resolve to the viewport (full-cover
+  // scrim, correctly centered dialog) and lets the scrim's z-index win. Falls
+  // back to inline rendering when no theme root is present (isolated unit tests).
+  //
+  // R2 / 42:608 (P6-U7): resolve the portal root SYNCHRONOUSLY on the first
+  // render (lazy `useState` init) rather than in a post-mount layout effect.
+  // The former effect-based null→portal flip re-committed the scrim ONE render
+  // after mount, which — because switching an element between inline and a
+  // `createPortal` boundary remounts its DOM subtree — destroyed and recreated
+  // any child input right after a consumer's mount-time autofocus ran. That is
+  // exactly why Ctrl+K opened the Command Palette with its search box unfocused
+  // (focus fell to <body>), so typed text and Enter went nowhere and no
+  // document opened. The editor mounts a single `.vgai-editor-theme` root at
+  // app init, long before any Dialog opens, so a plain `document.querySelector`
+  // finds it on render 1 — the scrim portals from the start, the input mounts
+  // once, and focus is preserved.
+  const [portalRoot] = useState<Element | null>(() =>
+    typeof document === 'undefined' ? null : document.querySelector('.vgai-editor-theme'),
+  );
+
+  const scrim = (
+    <div
+      className="vgai-dialog-scrim"
+      data-variant={variant}
+      onPointerDown={(event) => {
+        if (event.target === event.currentTarget) onDismiss?.();
+      }}
+    >
+      <div
+        {...props}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={labelledBy}
+        data-size={size}
+        data-variant={variant}
+        className={classes('vgai-dialog', className)}
+      />
+    </div>
+  );
+
+  return portalRoot ? createPortal(scrim, portalRoot) : scrim;
+}
+
+export function DialogHeader({
+  titleId,
+  title,
+  description,
+}: {
+  titleId: string;
+  title: ReactNode;
+  description?: ReactNode;
+}) {
+  return (
+    <Stack className="vgai-dialog-header" gap={2}>
+      <Text id={titleId} as="h2" variant="heading">
+        {title}
+      </Text>
+      {description && (
+        <Text as="p" tone="muted">
+          {description}
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+export function DialogBody({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <Stack {...props} className={classes('vgai-dialog-body', className)} />;
+}
+
+export function DialogFooter({ children, className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <Actions {...props} className={classes('vgai-dialog-footer', className)}>
+      {children}
+    </Actions>
+  );
+}
+
+export function DialogField({ className, ...props }: LabelHTMLAttributes<HTMLLabelElement>) {
+  return <label {...props} className={classes('vgai-dialog-field', className)} />;
+}
+
+export function DialogFieldLabel({ children }: { children: ReactNode }) {
+  return (
+    <Text variant="label" tone="muted">
+      {children}
+    </Text>
+  );
+}
+
+export function JoinedField({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <Inline {...props} className={classes('vgai-joined-field', className)} />;
+}
+
+export function JoinedFieldSuffix({ className, ...props }: HTMLAttributes<HTMLSpanElement>) {
+  return <span {...props} className={classes('vgai-joined-field-suffix', className)} />;
+}

package/src/widgets/patterns/Fields.tsx

@@ -0,0 +1,44 @@
+import type { HTMLAttributes, LabelHTMLAttributes, ReactNode } from 'react';
+
+function classes(base: string, className?: string): string {
+  return className ? `${base} ${className}` : base;
+}
+
+export function FieldGroup({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div {...props} className={classes('vgai-field-group', className)} />;
+}
+
+export interface FieldRowProps extends HTMLAttributes<HTMLDivElement> {
+  label: ReactNode;
+  htmlFor?: string;
+  hint?: ReactNode;
+  compact?: boolean;
+}
+
+export function FieldRow({
+  label,
+  htmlFor,
+  hint,
+  compact = false,
+  className,
+  children,
+  ...props
+}: FieldRowProps) {
+  return (
+    <div
+      {...props}
+      data-compact={compact || undefined}
+      className={classes('vgai-field-row', className)}
+    >
+      <label htmlFor={htmlFor} className="vgai-field-label">
+        {label}
+      </label>
+      <div className="vgai-field-control">{children}</div>
+      {hint && <div className="vgai-field-hint">{hint}</div>}
+    </div>
+  );
+}
+
+export function FieldLabel({ className, ...props }: LabelHTMLAttributes<HTMLLabelElement>) {
+  return <label {...props} className={classes('vgai-field-label', className)} />;
+}

package/src/widgets/patterns/List.tsx

@@ -0,0 +1,25 @@
+import { type ButtonHTMLAttributes, forwardRef } from 'react';
+
+export interface EditorListButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  selected?: boolean;
+  accent?: 'bar' | 'none';
+}
+
+/** Selectable list row with canonical hover, focus, disabled, and selection paint. */
+export const EditorListButton = forwardRef<HTMLButtonElement, EditorListButtonProps>(
+  function EditorListButton(
+    { selected = false, accent = 'bar', className, type = 'button', ...props },
+    ref,
+  ) {
+    return (
+      <button
+        {...props}
+        ref={ref}
+        type={type}
+        data-selected={selected || undefined}
+        data-accent={accent}
+        className={className ? `vgai-list-button ${className}` : 'vgai-list-button'}
+      />
+    );
+  },
+);

package/src/widgets/patterns/StateSurface.tsx

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+export type StateSurfaceTone = 'neutral' | 'loading' | 'error' | 'success';
+
+export interface StateSurfaceProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  tone?: StateSurfaceTone;
+  icon?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+  action?: ReactNode;
+  compact?: boolean;
+}
+
+export function StateSurface({
+  tone = 'neutral',
+  icon,
+  title,
+  description,
+  action,
+  compact = false,
+  className,
+  ...props
+}: StateSurfaceProps) {
+  const defaultRole =
+    tone === 'error' ? 'alert' : tone === 'loading' || tone === 'success' ? 'status' : undefined;
+  return (
+    <div
+      {...props}
+      role={props.role ?? defaultRole}
+      data-tone={tone}
+      data-compact={compact || undefined}
+      className={className ? `vgai-state-surface ${className}` : 'vgai-state-surface'}
+    >
+      {icon && <div className="vgai-state-surface-icon">{icon}</div>}
+      <strong className="vgai-state-surface-title">{title}</strong>
+      {description && <div className="vgai-state-surface-description">{description}</div>}
+      {action && <div className="vgai-state-surface-action">{action}</div>}
+    </div>
+  );
+}