@elabs-ai/components-ui 4.2.0 → 5.1.0

package/src/components/spec-playground/spec-playground.tsx

@@ -0,0 +1,351 @@
+"use client";
+
+import {
+  forwardRef,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ForwardedRef,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { Braces, ChevronDown, CircleAlert, CircleCheck, RotateCcw } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { useControllableState } from "../../lib/use-controllable-state";
+import { Badge } from "../badge";
+import { Button } from "../button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "../dropdown-menu";
+import { Textarea } from "../textarea";
+import { lineOfParseError, locateJsonPath, offsetOfLine } from "./locate-json-path";
+
+/** One problem a validator reports — the shape both the A2UI and DashboardSpec validators use. */
+export interface SpecPlaygroundError {
+  /** JSON-path-like address of the problem (`root.children[2].props.label`, `$.tiles[0]`). */
+  path: string;
+  /** The validator's machine-readable code (`missing-prop`, `overlap`, …). */
+  code: string;
+  message: string;
+}
+
+/** What `validate` returns: the typed spec, or the validator's own errors. */
+export type SpecPlaygroundValidation<TSpec> =
+  | { ok: true; spec: TSpec }
+  | { ok: false; errors: readonly SpecPlaygroundError[] };
+
+/** An entry in the `Load example` menu. */
+export interface SpecPlaygroundExample {
+  id: string;
+  label: string;
+  /** The JSON text loaded into the editor. */
+  value: string;
+}
+
+/** The playground's status: what the last validated text turned out to be. */
+export type SpecPlaygroundStatus = "valid" | "invalid" | "parse-error";
+
+/** Every string the playground renders — pass your own to localize it. */
+export interface SpecPlaygroundLabels {
+  /** Accessible name of the default textarea editor. */
+  editor: string;
+  /** Accessible name of the rendered-result region. */
+  preview: string;
+  /** Accessible name of the error list. */
+  errors: string;
+  /** Trigger of the examples menu. */
+  loadExample: string;
+  /** Resets the editor to its initial text. */
+  reset: string;
+  /** Status chip: the text validates. */
+  valid: string;
+  /** Status chip: the validator reported `count` errors. */
+  errorCount: (count: number) => string;
+  /** Status chip: the text is not JSON. */
+  parseError: string;
+  /** Shown over the render when it is the last valid spec, not the current text. */
+  showingLastValid: string;
+  /** Shown in the render pane before any text has validated. */
+  nothingValid: string;
+  /** Suffix naming the editor line an error points at. */
+  line: (line: number) => string;
+}
+
+export const DEFAULT_SPEC_PLAYGROUND_LABELS: SpecPlaygroundLabels = {
+  editor: "Spec (JSON)",
+  preview: "Rendered result",
+  errors: "Problems",
+  loadExample: "Load example",
+  reset: "Reset",
+  valid: "Valid",
+  errorCount: (count) => (count === 1 ? "1 error" : `${count} errors`),
+  parseError: "Parse error",
+  showingLastValid: "Showing last valid",
+  nothingValid: "Nothing valid to render yet.",
+  line: (line) => `line ${line}`,
+};
+
+export interface SpecPlaygroundProps<TSpec> extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** The JSON text (controlled). */
+  value?: string;
+  /** Initial JSON text (uncontrolled); also what `Reset` restores. Default: the first example. */
+  defaultValue?: string;
+  /** Called with the new text on every edit, example load and reset. */
+  onChange?: (value: string) => void;
+  /** Checks the parsed JSON; the errors shown are exactly the ones it returns. */
+  validate: (json: unknown) => SpecPlaygroundValidation<TSpec>;
+  /** Renders a validated spec. */
+  render: (spec: TSpec) => ReactNode;
+  /** Entries of the `Load example` menu (the menu is hidden without any). */
+  examples?: readonly SpecPlaygroundExample[];
+  /**
+   * The editor. Bind it to `value`/`onChange` yourself. Default: a `Textarea`, so the
+   * playground works without a code editor.
+   */
+  editor?: ReactNode;
+  /**
+   * Called when an error is chosen, with the editor line its path resolves to — move a custom
+   * editor's caret there. The default textarea handles this itself.
+   */
+  onErrorSelect?: (error: SpecPlaygroundError, line: number | undefined) => void;
+  /** Milliseconds between the last edit and validation. Default 250. */
+  debounceMs?: number;
+  labels?: Partial<SpecPlaygroundLabels>;
+}
+
+type Checked<TSpec> =
+  | { status: "valid"; spec: TSpec; errors: readonly SpecPlaygroundError[] }
+  | { status: "invalid" | "parse-error"; errors: readonly SpecPlaygroundError[] };
+
+function check<TSpec>(
+  text: string,
+  validate: (json: unknown) => SpecPlaygroundValidation<TSpec>,
+): Checked<TSpec> {
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { status: "parse-error", errors: [{ path: "", code: "parse-error", message }] };
+  }
+  const result = validate(json);
+  return result.ok
+    ? { status: "valid", spec: result.spec, errors: [] }
+    : { status: "invalid", errors: result.errors };
+}
+
+function SpecPlaygroundInner<TSpec>(
+  {
+    value: valueProp,
+    defaultValue,
+    onChange,
+    validate,
+    render,
+    examples = [],
+    editor,
+    onErrorSelect,
+    debounceMs = 250,
+    labels: labelsProp,
+    className,
+    ...props
+  }: SpecPlaygroundProps<TSpec>,
+  ref: ForwardedRef<HTMLDivElement>,
+) {
+  const labels = { ...DEFAULT_SPEC_PLAYGROUND_LABELS, ...labelsProp };
+  const initial = defaultValue ?? examples[0]?.value ?? "";
+  const [resetValue] = useState(initial);
+  const [value, setValue] = useControllableState(valueProp, initial, onChange);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // Validation trails the text by `debounceMs`; the first render validates immediately.
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    if (settled === value) return;
+    const timer = setTimeout(() => setSettled(value), debounceMs);
+    return () => clearTimeout(timer);
+  }, [value, settled, debounceMs]);
+
+  const checked = useMemo(() => check(settled, validate), [settled, validate]);
+
+  // The last spec that validated — kept on screen while the current text does not.
+  const lastValidRef = useRef<{ spec: TSpec } | null>(null);
+  if (checked.status === "valid") lastValidRef.current = { spec: checked.spec };
+  const shown = checked.status === "valid" ? { spec: checked.spec } : lastValidRef.current;
+  const stale = checked.status !== "valid" && shown !== null;
+
+  const lineOf = (error: SpecPlaygroundError) =>
+    error.code === "parse-error"
+      ? lineOfParseError(settled, error.message)
+      : locateJsonPath(settled, error.path);
+
+  const selectError = (error: SpecPlaygroundError) => {
+    const line = lineOf(error);
+    if (onErrorSelect) return onErrorSelect(error, line);
+    const textarea = textareaRef.current;
+    if (!textarea) return;
+    const offset = line === undefined ? 0 : offsetOfLine(textarea.value, line);
+    textarea.focus();
+    textarea.setSelectionRange(offset, offset);
+  };
+
+  const errorListId = `${props.id ?? "spec-playground"}-errors`;
+  const hasErrors = checked.errors.length > 0;
+
+  return (
+    <div
+      ref={ref}
+      data-slot="spec-playground"
+      data-status={checked.status}
+      className={cn("grid min-w-0 gap-4 lg:grid-cols-2", className)}
+      {...props}
+    >
+      <div data-slot="spec-playground-source" className="flex min-w-0 flex-col gap-3">
+        <div data-slot="spec-playground-toolbar" className="flex flex-wrap items-center gap-2">
+          <span role="status" aria-live="polite" className="me-auto">
+            <Badge
+              data-slot="spec-playground-status"
+              data-status={checked.status}
+              variant={
+                checked.status === "valid"
+                  ? "success"
+                  : checked.status === "invalid"
+                    ? "destructive"
+                    : "warning"
+              }
+              className="gap-1"
+            >
+              {checked.status === "valid" ? (
+                <CircleCheck aria-hidden="true" size={14} />
+              ) : checked.status === "invalid" ? (
+                <CircleAlert aria-hidden="true" size={14} />
+              ) : (
+                <Braces aria-hidden="true" size={14} />
+              )}
+              {checked.status === "valid"
+                ? labels.valid
+                : checked.status === "invalid"
+                  ? labels.errorCount(checked.errors.length)
+                  : labels.parseError}
+            </Badge>
+          </span>
+          {examples.length > 0 ? (
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button variant="outline" size="sm" data-slot="spec-playground-examples">
+                  {labels.loadExample}
+                  <ChevronDown aria-hidden="true" size={14} />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                {examples.map((example) => (
+                  <DropdownMenuItem
+                    key={example.id}
+                    data-example-id={example.id}
+                    onSelect={() => setValue(example.value)}
+                  >
+                    {example.label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          ) : null}
+          <Button
+            variant="ghost"
+            size="sm"
+            data-slot="spec-playground-reset"
+            onClick={() => setValue(resetValue)}
+          >
+            <RotateCcw aria-hidden="true" size={14} />
+            {labels.reset}
+          </Button>
+        </div>
+        <div data-slot="spec-playground-editor" className="min-h-80 min-w-0">
+          {editor ?? (
+            <Textarea
+              ref={textareaRef}
+              data-slot="spec-playground-textarea"
+              aria-label={labels.editor}
+              aria-invalid={hasErrors || undefined}
+              aria-describedby={hasErrors ? errorListId : undefined}
+              spellCheck={false}
+              value={value}
+              onChange={(event) => setValue(event.target.value)}
+              className="h-80 min-h-80 resize-y font-mono text-code"
+            />
+          )}
+        </div>
+        {hasErrors ? (
+          <ol
+            id={errorListId}
+            aria-label={labels.errors}
+            data-slot="spec-playground-errors"
+            className="flex flex-col gap-1"
+          >
+            {checked.errors.map((error) => {
+              const line = lineOf(error);
+              return (
+                <li key={`${error.path}|${error.code}|${error.message}`}>
+                  <button
+                    type="button"
+                    data-slot="spec-playground-error"
+                    data-path={error.path}
+                    data-code={error.code}
+                    onClick={() => selectError(error)}
+                    className="focus-ring flex w-full min-w-0 flex-wrap items-baseline gap-x-2 rounded-md border-s-2 border-s-destructive px-2 py-1 text-start text-caption hover:bg-muted"
+                  >
+                    {error.path ? <code className="font-mono text-code">{error.path}</code> : null}
+                    <span className="font-mono text-code text-destructive-text">{error.code}</span>
+                    <span className="min-w-0 break-words text-muted-foreground">
+                      {error.message}
+                    </span>
+                    {line !== undefined ? (
+                      <span className="text-meta text-muted-foreground">{labels.line(line)}</span>
+                    ) : null}
+                  </button>
+                </li>
+              );
+            })}
+          </ol>
+        ) : null}
+      </div>
+      <section
+        aria-label={labels.preview}
+        data-slot="spec-playground-preview"
+        data-stale={stale ? "" : undefined}
+        className="flex min-w-0 flex-col gap-2"
+      >
+        {stale ? (
+          <Badge variant="outline" data-slot="spec-playground-stale" className="self-start">
+            {labels.showingLastValid}
+          </Badge>
+        ) : null}
+        {shown ? (
+          render(shown.spec)
+        ) : (
+          <p className="text-caption text-muted-foreground">{labels.nothingValid}</p>
+        )}
+      </section>
+    </div>
+  );
+}
+
+/**
+ * A live spec editor: JSON on the left, what it renders on the right (stacked below 1024 px).
+ * Edits are validated after a short pause by the host's own `validate`; its errors are listed
+ * under the editor (`path · code · message`, click to jump to the line) and the render keeps
+ * the last valid spec, marked as such, until the text validates again. The editor, validator
+ * and renderer all come from the host — this component owns only the loop between them.
+ */
+export const SpecPlayground = forwardRef(SpecPlaygroundInner) as <TSpec>(
+  props: SpecPlaygroundProps<TSpec> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement;
+(SpecPlayground as { displayName?: string }).displayName = "SpecPlayground";

package/src/components/state-panel/state-panel.stories.tsx

@@ -84,8 +84,9 @@ export const EmptyNoIcon: Story = {
   },
 };
 
+/** #24 — the empty state gained a spot illustration slot beside title/description. */
 export const WithIllustration: Story = {
-  name: "Empty (with illustration, #24)",
+  name: "Empty (with illustration)",
   args: {
     kind: "empty",
     title: "No projects yet",
@@ -112,8 +113,9 @@ export const NoAccess: Story = {
   },
 };
 
+/** #24 P0-2 — the error state carries the same illustration slot as empty. */
 export const ErrorWithIllustration: Story = {
-  name: "Error (with illustration, #24 P0-2)",
+  name: "Error (with illustration)",
   args: {
     // The one panel `kind` that re-tints the illustration slot (`text-destructive`)
     // — pairing it with an illustration is what surfaces whether the accent

package/src/components/state-panel/state-panel.tsx

@@ -171,7 +171,7 @@ export function StatePanel({
           KEEPS text-destructive: an icon is a mark, so the fill rung is
           correct there — do not "tidy" it onto -text too. */}
       {isError && (
-        <span className="text-meta font-semibold uppercase tracking-widest text-destructive-text">
+        <span className="text-eyebrow uppercase text-destructive-text">
           {t("ui.statePanel.errorEyebrow")}
         </span>
       )}

package/src/components/status-badge/status-badge.stories.tsx

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Ban, ShieldAlert } from "lucide-react";
 import { STATUSES, StatusBadge, StatusIcon } from "./status-badge";
@@ -44,6 +45,15 @@ const meta = {
       control: "boolean",
       table: { category: "Appearance" },
     },
+    appearance: {
+      description:
+        "Explicit fill/border/ink treatment override, meaningful only on the colour-bearing " +
+        "statuses (running/complete/awaiting-approval/failed). `solid` is never honoured on " +
+        "a CustomStatus tone — the out-of-vocabulary hatch stays calm-only.",
+      control: { type: "select" },
+      options: [undefined, "tint", "solid", "outline", "neutral"],
+      table: { category: "Appearance" },
+    },
     children: {
       description: "Override the default status label text.",
       control: "text",
@@ -122,6 +132,49 @@ export const CustomVocabulary: Story = {
   ),
 };
 
+/**
+ * The four explicit `appearance` overrides on every colour-bearing status —
+ * each renders a `data-appearance` attribute regardless of the ancestor
+ * `--badge-appearance` token. `pending`/`denied`/`skipped` are already
+ * neutral pills, so `appearance` has no additional effect there.
+ */
+export const Appearances: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      {(["tint", "solid", "outline", "neutral"] as const).map((appearance) => (
+        <div key={appearance} className="flex flex-wrap items-center gap-2">
+          <span className="w-16 text-caption text-muted-foreground">{appearance}</span>
+          <StatusBadge appearance={appearance} status="running" />
+          <StatusBadge appearance={appearance} status="complete" />
+          <StatusBadge appearance={appearance} status="awaiting-approval" />
+          <StatusBadge appearance={appearance} status="failed" />
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * With no explicit `appearance` prop, an ancestor's `--badge-appearance`
+ * token drives the treatment — including the out-of-vocabulary `tone` hatch,
+ * which never reaches `solid` even here (the calm-only integrity
+ * constraint), so its custom statuses stay on their tint wash.
+ */
+export const TokenDrivenAppearance: Story = {
+  render: () => (
+    <div
+      className="flex flex-wrap gap-2"
+      style={{ "--badge-appearance": "solid" } as CSSProperties}
+    >
+      <StatusBadge status="running" />
+      <StatusBadge status="complete" />
+      <StatusBadge status="awaiting-approval" />
+      <StatusBadge status="failed" />
+      <StatusBadge status={{ label: "Stopped (guardrail)", tone: "warning", icon: ShieldAlert }} />
+    </div>
+  ),
+};
+
 /**
  * The `StatusIcon` atom for tight rows (test results, rail nodes) — the
  * adjacent row text must carry the status name for AT users.

package/src/components/status-badge/status-badge.test.tsx

@@ -65,6 +65,43 @@ describe("StatusBadge", () => {
     expect(icon?.getAttribute("class")).toContain("motion-reduce:animate-none");
   });
 
+  it("renders no data-appearance attribute when appearance is unset", () => {
+    const { container } = render(<StatusBadge status="running" />);
+    expect(container.querySelector('[data-status="running"]')).not.toHaveAttribute(
+      "data-appearance",
+    );
+  });
+
+  it("renders data-appearance when an explicit appearance is passed", () => {
+    const { container } = render(<StatusBadge appearance="outline" status="running" />);
+    expect(container.querySelector('[data-status="running"]')).toHaveAttribute(
+      "data-appearance",
+      "outline",
+    );
+  });
+
+  it("clamps an explicit appearance=solid away on a CustomStatus tone (calm-only hatch)", () => {
+    render(
+      <StatusBadge
+        appearance="solid"
+        status={{ label: "Stopped", tone: "warning", icon: ShieldAlert }}
+      />,
+    );
+    const badge = screen.getByText("Stopped").closest("[data-slot='status-badge']");
+    expect(badge).not.toHaveAttribute("data-appearance");
+  });
+
+  it("honours a non-solid explicit appearance on a CustomStatus tone", () => {
+    render(
+      <StatusBadge
+        appearance="outline"
+        status={{ label: "Stopped", tone: "warning", icon: ShieldAlert }}
+      />,
+    );
+    const badge = screen.getByText("Stopped").closest("[data-slot='status-badge']");
+    expect(badge).toHaveAttribute("data-appearance", "outline");
+  });
+
   it("merges className last and spreads props", () => {
     const { container } = render(
       <StatusBadge className="bg-muted" data-testid="badge" status="pending" />,

package/src/components/status-badge/status-badge.tsx

@@ -47,7 +47,12 @@ import {
   type LucideIcon,
   type LucideProps,
 } from "lucide-react";
-import { badgeVariants } from "../badge/badge";
+import {
+  BADGE_APPEARANCE_RECIPES,
+  BADGE_APPEARANCE_RECIPES_CALM,
+  badgeVariants,
+  type BadgeAppearance,
+} from "../badge/badge";
 import { cn } from "../../lib/cn";
 
 /** The canonical, closed 7-state status enum (research 10 §B.1). */
@@ -220,17 +225,35 @@ export const statusBadgeVariants = cva(
   {
     variants: {
       status: {
-        // calm: neutral fill
+        // calm: neutral fill — structural, not a colour role: `appearance`
+        // has no effect (see badge.tsx's `secondary`/`outline` variants).
         pending: "border-transparent bg-secondary text-secondary-foreground",
         // calm: status alpha-wash (escapes the decoration drawn-not-filled rule)
-        running: "border-info/40 bg-info/10 text-info-text",
-        complete: "border-success/40 bg-success/10 text-success-text",
+        running: cn(
+          "border-info/40 bg-info/10 text-info-text",
+          "[--badge-fill:var(--info)] [--badge-ink:var(--info-text)] [--badge-on:var(--info-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        complete: cn(
+          "border-success/40 bg-success/10 text-success-text",
+          "[--badge-fill:var(--success)] [--badge-ink:var(--success-text)] [--badge-on:var(--success-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
         // ATTENTION: solid fill — must grab the eye
-        "awaiting-approval": "border-transparent bg-warning text-warning-foreground",
-        // calm: de-emphasized neutrals
+        "awaiting-approval": cn(
+          "border-transparent bg-warning text-warning-foreground",
+          "[--badge-fill:var(--warning)] [--badge-ink:var(--warning-text)] [--badge-on:var(--warning-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        // calm: de-emphasized neutrals — structural, `appearance` has no effect.
         denied: "border-transparent bg-muted text-muted-foreground",
         // ATTENTION: solid fill — must grab the eye
-        failed: "border-transparent bg-destructive text-destructive-foreground",
+        failed: cn(
+          "border-transparent bg-destructive text-destructive-foreground",
+          "[--badge-fill:var(--destructive)] [--badge-ink:var(--destructive-text)] [--badge-on:var(--destructive-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        // calm: neutral fill — structural, `appearance` has no effect.
         skipped: "border-transparent bg-secondary text-muted-foreground",
       },
       /**
@@ -238,14 +261,36 @@ export const statusBadgeVariants = cva(
        * same alpha-wash/neutral technique as the calm `status` recipes above).
        * There is deliberately no solid/attention recipe here: the loud fill
        * stays exclusive to the canonical `awaiting-approval`/`failed` states
-       * (integrity constraint 2, see the file docblock).
+       * (integrity constraint 2, see the file docblock). For the same reason,
+       * a non-neutral tone only ever wires `BADGE_APPEARANCE_RECIPES_CALM`
+       * (tint/outline/neutral — never solid), so even a theme's global
+       * `--badge-appearance: solid` cannot loudify the hatch; `StatusBadge`
+       * also clamps an explicit `appearance="solid"` prop away below.
        */
       tone: {
+        // Already a neutral pill — `appearance` has no effect (mirrors
+        // Badge's `secondary`).
         neutral: "border-transparent bg-secondary text-secondary-foreground",
-        info: "border-info/40 bg-info/10 text-info-text",
-        success: "border-success/40 bg-success/10 text-success-text",
-        warning: "border-warning/40 bg-warning/10 text-warning-text",
-        destructive: "border-destructive/40 bg-destructive/10 text-destructive-text",
+        info: cn(
+          "border-info/40 bg-info/10 text-info-text",
+          "[--badge-fill:var(--info)] [--badge-ink:var(--info-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
+        success: cn(
+          "border-success/40 bg-success/10 text-success-text",
+          "[--badge-fill:var(--success)] [--badge-ink:var(--success-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
+        warning: cn(
+          "border-warning/40 bg-warning/10 text-warning-text",
+          "[--badge-fill:var(--warning)] [--badge-ink:var(--warning-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
+        destructive: cn(
+          "border-destructive/40 bg-destructive/10 text-destructive-text",
+          "[--badge-fill:var(--destructive)] [--badge-ink:var(--destructive-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
       },
       /** `md` for inline use; `sm` for rail nodes / dense rows. */
       size: {
@@ -265,20 +310,36 @@ export interface StatusBadgeProps
   status: Status | CustomStatus;
   /** Render label-only (no status icon). */
   hideIcon?: boolean;
+  /**
+   * Explicit per-instance override of the fill/border/ink treatment — see
+   * `Badge`'s own doc. Meaningful only on the colour-bearing statuses
+   * (`running`/`complete`/`awaiting-approval`/`failed`) and tones
+   * (`info`/`success`/`warning`/`destructive`); `pending`/`denied`/`skipped`
+   * and the `neutral` tone are already neutral pills. On a `CustomStatus`
+   * (the out-of-vocabulary hatch), `"solid"` is never honoured — the hatch
+   * is calm-only (integrity constraint 2, file docblock).
+   */
+  appearance?: BadgeAppearance;
 }
 
 export const StatusBadge = forwardRef<HTMLSpanElement, StatusBadgeProps>(function StatusBadge(
-  { status, size, hideIcon = false, className, children, ...props },
+  { status, size, appearance, hideIcon = false, className, children, ...props },
   ref,
 ) {
   if (isCustomStatus(status)) {
     const { label, tone, icon: Icon } = status;
+    // Calm-only hatch: `solid` never reaches a custom tone, even via an
+    // explicit prop (integrity constraint 2) — `statusBadgeVariants`'
+    // `tone` branches also never wire the `solid` recipe, so a theme's
+    // global `--badge-appearance: solid` can't reach it either.
+    const toneAppearance = appearance === "solid" ? undefined : appearance;
     return (
       <span
         ref={ref}
         data-slot="status-badge"
         data-status="custom"
         data-tone={tone}
+        data-appearance={toneAppearance}
         className={cn(statusBadgeVariants({ tone, size }), className)}
         {...props}
       >
@@ -295,6 +356,7 @@ export const StatusBadge = forwardRef<HTMLSpanElement, StatusBadgeProps>(functio
       data-slot="status-badge"
       data-status={status}
       data-tone={STATUS_TONE_MAP[status]}
+      data-appearance={appearance}
       className={cn(statusBadgeVariants({ status, size }), className)}
       {...props}
     >

package/src/components/surface-tour/index.ts

@@ -0,0 +1,11 @@
+export {
+  AffordanceHint,
+  DEFAULT_SURFACE_TOUR_ACTIONS_LABELS,
+  SurfaceTour,
+  SurfaceTourActions,
+  type AffordanceHintProps,
+  type SurfaceTourActionsLabels,
+  type SurfaceTourActionsProps,
+  type SurfaceTourProps,
+  type SurfaceTourTab,
+} from "./surface-tour";