@elabs-ai/components-ui 4.2.0 → 5.0.0

package/src/__contract__/command-chip.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for CommandChip (`packages/ui/src/components/command-chip/command-chip.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/command-chip/command-chip.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/command-chip/command-chip.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `display-commandchip--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("CommandChip contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="command-chip" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="command-chip"]')).not.toBeNull();
+  });
+});

package/src/__contract__/install-tabs.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for InstallTabs (`packages/ui/src/components/install-tabs/install-tabs.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/install-tabs/install-tabs.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/install-tabs/install-tabs.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `display-installtabs--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("InstallTabs contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="install-tabs" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="install-tabs"]')).not.toBeNull();
+  });
+});

package/src/__contract__/integration-matrix.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for IntegrationMatrix (`packages/ui/src/components/integration-matrix/integration-matrix.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/integration-matrix/integration-matrix.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/integration-matrix/integration-matrix.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `display-integrationmatrix--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("IntegrationMatrix contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="integration-matrix" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="integration-matrix"]')).not.toBeNull();
+  });
+});

package/src/__contract__/meter.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for Meter (`packages/ui/src/components/meter/meter.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/meter/meter.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/meter/meter.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `display-meter--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("Meter contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="meter" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="meter"]')).not.toBeNull();
+  });
+});

package/src/__contract__/parallax-plane.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for ParallaxPlane (`packages/ui/src/components/parallax-plane/parallax-plane.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/parallax-plane/parallax-plane.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/parallax-plane/parallax-plane.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `ground-plane--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("ParallaxPlane contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="parallax-plane" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="parallax-plane"]')).not.toBeNull();
+  });
+});

package/src/__contract__/reveal-on-enter.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for RevealOnEnter (`packages/ui/src/components/reveal-on-enter/reveal-on-enter.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/reveal-on-enter/reveal-on-enter.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/reveal-on-enter/reveal-on-enter.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `once--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("RevealOnEnter contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="reveal-on-enter" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="reveal-on-enter"]')).not.toBeNull();
+  });
+});

package/src/__contract__/spec-playground.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for SpecPlayground (`packages/ui/src/components/spec-playground/spec-playground.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/spec-playground/spec-playground.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/spec-playground/spec-playground.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `launch-checklist--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("SpecPlayground contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="spec-playground" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="spec-playground"]')).not.toBeNull();
+  });
+});

package/src/__contract__/surface-tour.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for SurfaceTour (`packages/ui/src/components/surface-tour/surface-tour.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/surface-tour/surface-tour.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/surface-tour/surface-tour.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `layout-surfacetour--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("SurfaceTour contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="surface-tour" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="surface-tour"]')).not.toBeNull();
+  });
+});

package/src/__contract__/theme-family-switch.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for ThemeFamilySwitch (`packages/ui/src/components/theme-family-switch/theme-family-switch.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/theme-family-switch/theme-family-switch.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/theme-family-switch/theme-family-switch.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `core-themefamilyswitch--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("ThemeFamilySwitch contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="theme-family-switch" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="theme-family-switch"]')).not.toBeNull();
+  });
+});

package/src/__contract__/token-spotlight.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for TokenSpotlight (`packages/ui/src/components/token-spotlight/token-spotlight.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/token-spotlight/token-spotlight.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/token-spotlight/token-spotlight.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `display-tokenspotlight--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("TokenSpotlight contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="token-spotlight" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="token-spotlight"]')).not.toBeNull();
+  });
+});

package/src/blocks-comparison-table.stories.tsx

@@ -146,7 +146,7 @@ function ComparisonTable() {
 }
 
 const meta = {
-  title: "Patterns/Blocks/Comparison Table",
+  title: "Patterns/Blocks/Data Surfaces/Comparison Table",
   parameters: {
     layout: "fullscreen",
     docs: {

package/src/components/accordion/accordion.tsx

@@ -19,24 +19,40 @@ export const AccordionItem = forwardRef<
   );
 });
 
+export interface AccordionTriggerProps extends ComponentPropsWithoutRef<
+  typeof AccordionPrimitive.Trigger
+> {
+  /**
+   * The heading level Radix's `Accordion.Header` renders. Radix hardcodes `h3`,
+   * which skips a level whenever the accordion sits directly under the page
+   * `h1` — so the level is the caller's to set. Visually identical at every
+   * level: the type comes from the trigger, not the heading.
+   * @default 3
+   */
+  headingLevel?: 2 | 3 | 4 | 5 | 6;
+}
+
 export const AccordionTrigger = forwardRef<
   ElementRef<typeof AccordionPrimitive.Trigger>,
-  ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>
->(function AccordionTrigger({ className, children, ...props }, ref) {
+  AccordionTriggerProps
+>(function AccordionTrigger({ className, children, headingLevel = 3, ...props }, ref) {
+  const Heading = `h${headingLevel}` as const;
   return (
-    <AccordionPrimitive.Header className="flex" data-slot="accordion-header">
-      <AccordionPrimitive.Trigger
-        ref={ref}
-        data-slot="accordion-trigger"
-        className={cn(
-          "flex flex-1 items-center justify-between py-4 text-body font-medium transition-all hover:underline focus-ring [&[data-state=open]>svg]:rotate-180",
-          className,
-        )}
-        {...props}
-      >
-        {children}
-        <ChevronDown className="size-4 shrink-0 text-muted-foreground transition-transform duration-base ease-standard" />
-      </AccordionPrimitive.Trigger>
+    <AccordionPrimitive.Header asChild>
+      <Heading className="flex" data-slot="accordion-header">
+        <AccordionPrimitive.Trigger
+          ref={ref}
+          data-slot="accordion-trigger"
+          className={cn(
+            "flex flex-1 items-center justify-between py-4 text-body font-medium transition-all hover:underline focus-ring [&[data-state=open]>svg]:rotate-180",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+          <ChevronDown className="size-4 shrink-0 text-muted-foreground transition-transform duration-base ease-standard" />
+        </AccordionPrimitive.Trigger>
+      </Heading>
     </AccordionPrimitive.Header>
   );
 });

package/src/components/advanced-group/advanced-group.stories.tsx

@@ -123,6 +123,7 @@ export const InsideDialog: Story = {
 };
 
 export const DefaultDark: Story = {
+  tags: ["!dev"],
   name: "Default — dark",
   args: { changedCount: 3 },
   decorators: [
@@ -136,6 +137,7 @@ export const DefaultDark: Story = {
 };
 
 export const DefaultHighDecoration: Story = {
+  tags: ["!dev"],
   name: "Default — high decoration",
   args: { changedCount: 3 },
   globals: { decoration: "10" },

package/src/components/alert/alert.tsx

@@ -47,14 +47,22 @@ export const Alert = forwardRef<
 export interface AlertTitleProps extends HTMLAttributes<HTMLHeadingElement> {
   /**
    * Render at a different heading level to fit the surrounding document
-   * outline (#329). The visual (`mb-1 font-medium leading-none
-   * tracking-tight`) is identical at every level. @default "h5"
+   * outline (#329), or as a `"div"` to stay out of the outline entirely. The
+   * visual (`mb-1 font-medium leading-none tracking-tight`) is identical for
+   * every value. @default "h5"
+   *
+   * `"div"` is for a title whose depth the author cannot know — content rendered
+   * into someone else's page, such as an A2UI surface, where a fixed `h5` breaks
+   * `heading-order` under any host that has no `h4` above it. The alert's own
+   * `role="alert"` announces the title either way, so nothing is lost; `CardTitle`
+   * makes the same default choice for the same reason.
    */
-  as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+  as?: "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 }
 
-// Ref type matches the rendered element (`HTMLHeadingElement` for every `as`
-// value) — previously mismatched to `HTMLParagraphElement` (#329).
+// Ref type matches the rendered element (`HTMLHeadingElement` for every heading
+// `as` value, and structurally interchangeable with `div`) — previously
+// mismatched to `HTMLParagraphElement` (#329).
 export const AlertTitle = forwardRef<HTMLHeadingElement, AlertTitleProps>(function AlertTitle(
   { className, as: Tag = "h5", ...props },
   ref,

package/src/components/alert-dialog/alert-dialog.tsx

@@ -44,7 +44,7 @@ export const AlertDialogContent = forwardRef<
           // (a big diff, a long list of items to confirm) overflows past both
           // viewport edges with its actions unreachable — the `-translate-y-1/2`
           // centring only makes this worse by pushing the top half off-screen.
-          "fixed left-1/2 top-1/2 z-50 grid max-h-[85dvh] w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 overflow-y-auto rounded-xl bg-card p-6 text-card-foreground shadow-ring-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+          "fixed left-1/2 top-1/2 z-50 grid max-h-[85dvh] w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 overflow-y-auto rounded-xl bg-card p-6 text-card-foreground shadow-dialog data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
           className,
         )}
         {...props}