From fe756a828d8de81a558c2077c40624bb2721b7c9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 26 Aug 2026 09:41:46 +0000
Subject: [PATCH] feat(types): declare the toast trigger-button keys the
 renderer reads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`ToastSchema` now declares `buttonLabel` and `buttonVariant` on both faces —
the TS interface and the `@object-ui/types/zod` mirror. The `toast` renderer
has always read both (`variant={schema.buttonVariant}` and
`{schema.buttonLabel || 'Show Toast'}`) and the registration has always offered
`buttonLabel` as a designer input; only the published type disagreed.

`buttonVariant` is declared as the six Button variants on both faces rather
than as an open string. The renderer passes the value straight into
`<Button variant={...}>`, so `ButtonProps['variant']` is the authority, and an
unrecognised key makes `cva` contribute no variant class at all — a button with
no background and no text colour. The sibling `SonnerSchema` spells the same
key `z.string()` in its mirror and as the six-member union in TS; that
disagreement is filed separately and deliberately not resolved here.

Direction 2 of the finding (`action` / `onDismiss`, declared but read by
nothing) is out of scope and left byte-identical.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011SfZeFWrhGLHmfq61xbz4q
---
 .changeset/6496-toast-button-keys.md          |  62 ++++++
 .../toast-button-variant-parity.test.ts       | 113 ++++++++++
 .../src/__tests__/toast-button-keys.test.ts   | 208 ++++++++++++++++++
 packages/types/src/feedback.ts                |  25 +++
 packages/types/src/zod/feedback.zod.ts        |  14 ++
 5 files changed, 422 insertions(+)
 create mode 100644 .changeset/6496-toast-button-keys.md
 create mode 100644 packages/components/src/__tests__/toast-button-variant-parity.test.ts
 create mode 100644 packages/types/src/__tests__/toast-button-keys.test.ts

diff --git a/.changeset/6496-toast-button-keys.md b/.changeset/6496-toast-button-keys.md
new file mode 100644
index 0000000000..a5281eb24d
--- /dev/null
+++ b/.changeset/6496-toast-button-keys.md
@@ -0,0 +1,62 @@
+---
+'@object-ui/types': minor
+---
+
+`ToastSchema` now declares the two trigger-button keys the `toast` renderer actually reads
+(objectui#6496, triage scope cut 2026-08-26 — the same declare-what-runs family as
+objectui#6170).
+
+`renderers/feedback/toast.tsx` renders a `<Button>` that raises the toast, and reads two
+keys off the node to do it: `variant={schema.buttonVariant}` and
+`{schema.buttonLabel || 'Show Toast'}`. `ToastSchema` declared **neither**, on the TS face
+or in the `@object-ui/types/zod` mirror. The registration's own designer `inputs` offered
+`buttonLabel` (with `defaultValue: 'Show Toast'`), so the designer shipped a control for a
+key the published type did not have; `buttonVariant` was read by the renderer and named by
+nothing at all. `SonnerSchema` — the sibling with the identical trigger mechanism —
+declared both all along, so only one of the two components was expressible.
+
+The visible cost was on objectui#6250: with `buttonLabel` undeclared, its seven corrected
+toast demos could not author a per-demo trigger label the way the corrected sonner demos
+could, and all seven render the default `Show Toast`. Those demos are unblocked by this.
+
+**`buttonVariant` is declared as the six Button variants, on both faces.** The model this
+card was told to copy disagrees with itself: `SonnerSchema` spells the key `z.string()` in
+the zod mirror and `'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'`
+in TS. Matching by symmetry picks nothing, so the shape was taken from what the value
+*reaches* — the renderer passes it straight into `<Button variant={…}>`, whose prop type is
+`VariantProps<typeof buttonVariants>['variant']`, exactly those six. The TS face is the
+correct one and both faces here carry it.
+
+An open `string` is not merely under-validation. Measured on `cva` 0.7.1: an unrecognised
+variant key contributes **no** variant class, and `defaultVariants` applies only when the
+value is *absent* — so `buttonVariant: 'primary'` renders a button with no background and
+no text colour, silently, while `buttonVariant: undefined` renders the default look
+correctly. `primary` is the likeliest wrong spelling precisely because the default
+variant's own class is `bg-primary`. And `buttonVariant: ''` is silently resolved to
+`default` by the same falsy fallback — the one wrong value that does not *look* wrong,
+which an open `string` would accept and never signal. That the declared six are the Button's own vocabulary
+is pinned in both directions in `components/src/__tests__/toast-button-variant-parity.test.ts`
+— `@object-ui/types` has zero deps and cannot import the Button, so the list there is
+necessarily hand-copied, and that file is what stops it being a copy that can drift.
+
+**`SonnerSchema`'s own two faces are left disagreeing.** Its mirror stays `z.string()`.
+That is a real defect on a published surface, and it is filed as objectui#6541 rather than
+fixed here —
+this card's face is `ToastSchema`, and narrowing a second published key is its own
+accept-set change with its own consumers to measure.
+
+**Direction 2 of the finding is untouched.** `action` and `onDismiss` are declared on
+`ToastSchema` and read by no renderer; they sit immediately adjacent to this edit and are
+byte-identical after it. They are enforce-or-remove on a published type and belong to the
+objectui#6124 unsatisfiable-mirror census feeding the objectui#6182 handler-dialect
+decision; they are deliberately not pinned here either, so that family's ruling lands
+without a test of this card's to negotiate with.
+
+Accept-set note for consumers: both keys are **optional** and materialise no default, so
+nothing that renders today stops rendering and no stored toast JSON becomes invalid. Two
+keys that previously resolved as `any` through `BaseSchema`'s index signature are now
+typed, so `buttonLabel: 42` and a `buttonVariant` outside the six are a type error and a
+Zod rejection where they used to pass silently — values that never rendered correctly in
+the first place. `BaseSchema` is untouched, so an *undeclared* key is still accepted by
+both halves (objectui#5155 / objectui#6269 own that ceiling); declaring these two bought
+validation of the declared keys, not rejection of misspellings.
diff --git a/packages/components/src/__tests__/toast-button-variant-parity.test.ts b/packages/components/src/__tests__/toast-button-variant-parity.test.ts
new file mode 100644
index 0000000000..832b272a43
--- /dev/null
+++ b/packages/components/src/__tests__/toast-button-variant-parity.test.ts
@@ -0,0 +1,113 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * `ToastSchema['buttonVariant']` ↔ Button vocabulary parity (objectui#6496).
+ *
+ * objectui#6496 declared `buttonLabel` / `buttonVariant` on `ToastSchema`, and
+ * the shape of the second one was the card's whole judgement call. The sibling
+ * it was told to copy disagrees with ITSELF — `SonnerSchema` spells
+ * `buttonVariant` as `z.string()` in the zod mirror and as a six-member union
+ * in TS — so "match the sibling" picks nothing. The ground truth is what the
+ * value REACHES: `renderers/feedback/toast.tsx:30` passes it straight into
+ * `<Button variant={…}>`, so `ButtonProps['variant']` is the authority.
+ *
+ * `@object-ui/types` has zero deps and cannot import the Button, so the
+ * declaration there is necessarily a hand-copied list. THIS file is what stops
+ * that list being a copy: it lives where both are visible and compares them.
+ * Add a seventh variant to `buttonVariants` and the type-level half below goes
+ * red naming the gap, instead of the schema quietly refusing a real look.
+ *
+ * The runtime half measures the thing that makes an open `string` wrong. `cva`
+ * contributes NO variant class for an unrecognised key, and falls back to
+ * `defaultVariants` only when the value is ABSENT — so a string outside the six
+ * does not render "some other style", it renders a button with no background
+ * and no text colour. That is the concrete cost the enum buys out, and it is
+ * measured here rather than asserted in prose.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { ToastSchema } from '@object-ui/types';
+import { buttonVariants, type ButtonProps } from '../ui/button';
+
+/** The six as `ToastSchema` declares them. */
+const DECLARED = ['default', 'secondary', 'destructive', 'outline', 'ghost', 'link'] as const;
+
+/**
+ * What `buttonVariants` emits for a value it does not recognise: the base
+ * classes and nothing else. Every "this is not a real variant" assertion below
+ * is measured against this string rather than against a hand-written class list.
+ */
+const NO_VARIANT_CLASSES = buttonVariants({ variant: '__not-a-variant__' as never });
+
+describe('the declared `buttonVariant` vocabulary is the Button’s own', () => {
+  it('every declared value is a real Button variant (it contributes a class)', () => {
+    const inert = DECLARED.filter((v) => buttonVariants({ variant: v }) === NO_VARIANT_CLASSES);
+    expect(inert, 'declared, but the Button draws nothing for them').toEqual([]);
+  });
+
+  it('every declared value is DISTINCT — no two collapse to the same look', () => {
+    const rendered = DECLARED.map((v) => buttonVariants({ variant: v }));
+    expect(new Set(rendered).size).toBe(DECLARED.length);
+  });
+
+  it('the declared list matches `ButtonProps["variant"]` in BOTH directions', () => {
+    // The exhaustiveness pin, and the one that cannot be satisfied by copying.
+    // `NonNullable` strips the `null | undefined` that `VariantProps` adds.
+    //   - `declaredIsAccepted` fails if the schema declares a value the Button
+    //     does not accept (the schema would invite a look that renders blank);
+    //   - `acceptedIsDeclared` fails if the Button accepts a value the schema
+    //     does not declare (a real look the schema refuses — what a seventh
+    //     variant would cause).
+    type Accepted = NonNullable<ButtonProps['variant']>;
+    type Declared = NonNullable<ToastSchema['buttonVariant']>;
+
+    const declaredIsAccepted: Accepted = null as unknown as Declared;
+    const acceptedIsDeclared: Declared = null as unknown as Accepted;
+
+    expect([declaredIsAccepted, acceptedIsDeclared]).toHaveLength(2);
+  });
+
+  it('the runtime list and the declared TYPE are the same six', () => {
+    // Guards the array literal above against drifting from the type it claims
+    // to enumerate — the array is what the runtime assertions iterate.
+    const typed: NonNullable<ToastSchema['buttonVariant']>[] = [...DECLARED];
+    expect(typed).toHaveLength(6);
+  });
+});
+
+describe('why the mirror is an enum and not `z.string()`', () => {
+  it('an unrecognised variant renders NO colour — it is not merely unusual', () => {
+    // `primary` is the likeliest wrong spelling: the DEFAULT variant's own class
+    // is `bg-primary`, so the name reads correct and produces a blank button.
+    for (const bogus of ['primary', 'danger', 'warning', 'Default']) {
+      expect(buttonVariants({ variant: bogus as never }), bogus).toBe(NO_VARIANT_CLASSES);
+    }
+    expect(NO_VARIANT_CLASSES).not.toContain('bg-primary');
+  });
+
+  it('an EMPTY variant is silently reinterpreted as `default` — cva’s falsy fallback', () => {
+    // Measured, and worth its own pin because it is the one wrong value that
+    // does NOT look wrong. `cva` resolves
+    // `falsyToString(props.variant) || falsyToString(defaultVariants.variant)`,
+    // so `''` never reaches the variant table: it takes the default look. Under
+    // an open `z.string()` an author could write `buttonVariant: ''`, see a
+    // correctly styled button, and never learn the value meant nothing. The
+    // enum refuses it instead — pinned on the mirror side in
+    // `types/src/__tests__/toast-button-keys.test.ts`.
+    expect(buttonVariants({ variant: '' as never })).toBe(buttonVariants({ variant: 'default' }));
+    expect(buttonVariants({ variant: '' as never })).not.toBe(NO_VARIANT_CLASSES);
+  });
+
+  it('an ABSENT variant still gets the default look — so optional stays safe', () => {
+    // This is why both keys are declared OPTIONAL rather than defaulted in the
+    // schema: omission already has a defined, styled outcome downstream.
+    expect(buttonVariants({ variant: undefined })).toBe(buttonVariants({ variant: 'default' }));
+    expect(buttonVariants({ variant: undefined })).not.toBe(NO_VARIANT_CLASSES);
+  });
+});
diff --git a/packages/types/src/__tests__/toast-button-keys.test.ts b/packages/types/src/__tests__/toast-button-keys.test.ts
new file mode 100644
index 0000000000..deb859fe15
--- /dev/null
+++ b/packages/types/src/__tests__/toast-button-keys.test.ts
@@ -0,0 +1,208 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Declaration pin — the two trigger-button keys the `toast` renderer reads that
+ * `ToastSchema` did not declare (objectui#6496).
+ *
+ * ## What was wrong
+ *
+ * `renderers/feedback/toast.tsx` renders a `<Button>` that raises the toast:
+ * `variant={schema.buttonVariant}` on :30, `{schema.buttonLabel || 'Show Toast'}`
+ * on :31. The registration's own `inputs` offered `buttonLabel` as an authoring
+ * control (with `defaultValue: 'Show Toast'`), and `ToastSchema` declared
+ * NEITHER key — on the TS face or in the zod mirror. So the designer offered a
+ * control for a key the shipped type did not have, and `buttonVariant` was read
+ * by the renderer and named by nothing at all.
+ *
+ * `SonnerSchema` — the sibling component with the same trigger mechanism —
+ * declared both all along. This card is the declare-what-runs half only;
+ * `action` / `onDismiss` (declared-but-unread, the other direction the finding
+ * recorded) are deliberately untouched here and stay with the objectui#6124 /
+ * objectui#6182 handler-dialect family.
+ *
+ * ## Why `buttonVariant` is an enum and not `z.string()`
+ *
+ * The two faces of `SonnerSchema` disagree — `z.string()` in the mirror,
+ * a six-member union in TS — so "match the sibling" does not pick a shape. The
+ * ground truth is what the value REACHES: the renderer passes it straight to
+ * `<Button variant={…}>`, whose prop type is
+ * `VariantProps<typeof buttonVariants>['variant']`. Measured, `cva` contributes
+ * NO variant class for an unrecognised key and falls back to `defaultVariants`
+ * only when the value is ABSENT:
+ *
+ *     buttonVariants({ variant: undefined }) -> "base … bg-primary …"
+ *     buttonVariants({ variant: 'ghost'   }) -> "base … hover:bg-accent …"
+ *     buttonVariants({ variant: 'primary' }) -> "base …"          (no colour)
+ *
+ * So an open `string` does not merely under-validate — it admits values that
+ * render a button with no background and no text colour, silently. The TS face
+ * is the correct one and both faces here carry it. That the six ARE exactly the
+ * Button's own vocabulary is pinned where the Button is visible, in
+ * `components/src/__tests__/toast-button-variant-parity.test.ts`; this package
+ * has zero deps and cannot see it.
+ *
+ * ## What this pin has teeth against, and what it does not
+ *
+ * Same ceiling as objectui#6170's timeline pin and objectui#5903's gantt pin.
+ * `BaseSchema` is `.passthrough()` on the zod side and carries `[key: string]:
+ * any` on the TS side, so:
+ *
+ *   - an UNDECLARED key is still ACCEPTED by both halves. Declaring these two
+ *     did not buy rejection of a misspelling, and the pin below says so;
+ *   - a DECLARED key IS validated. `buttonVariant: 'primary'` parsed green
+ *     before this card and is refused now — that narrowing is the whole change.
+ *
+ * That asymmetry is also what makes this file a real reverse-verification and
+ * not a round-trip that would have passed anyway: a pin asserting `safeParse`
+ * SUCCEEDS on `{ buttonLabel, buttonVariant }` passes against the undeclared
+ * tree too, because passthrough keeps the keys rather than refusing them. The
+ * assertions with teeth are the REFUSALS (`itRefuses…`) and the
+ * `@ts-expect-error` block; both were run against the undeclared tree and both
+ * fail there. See the PR for the recorded red.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ToastSchema } from '../zod/feedback.zod.js';
+import type { ToastSchema as ToastSchemaTS } from '../feedback';
+
+const MINIMAL = { type: 'toast' } as const;
+
+/** The six the Button accepts, in the order `SonnerSchema`'s TS face spells them. */
+const BUTTON_VARIANTS = ['default', 'secondary', 'destructive', 'outline', 'ghost', 'link'] as const;
+
+/** Each declared key with a value its declared type refuses. */
+const DECLARED: ReadonlyArray<readonly [string, unknown]> = [
+  ['buttonLabel', 42],
+  ['buttonVariant', 'primary'],
+];
+
+describe('ToastSchema — the two trigger-button keys are declared (objectui#6496)', () => {
+  it('the mirror declares both of them', () => {
+    const shape = Object.keys(ToastSchema.shape);
+    for (const [key] of DECLARED) expect(shape, `mirror is missing ${key}`).toContain(key);
+  });
+
+  it('declares them OPTIONAL — a bare `{ type: "toast" }` still parses', () => {
+    // Requiredness is the half the zod-mirror-parity ratchet compares against
+    // `../feedback.ts`, where both are `?:`. A mirror that required one would
+    // reject every toast already published, including the seven fixtures in
+    // `examples/schema-catalog/src/schemas/components-feedback-toast/`.
+    const result = ToastSchema.safeParse(MINIMAL);
+    expect(result.success ? null : result.error.issues).toBe(null);
+  });
+
+  it('materialises NO defaults — an omitted key stays absent after parse', () => {
+    // `buttonLabel` defaults IN THE RENDERER, by `||` (`schema.buttonLabel ||
+    // 'Show Toast'`), and `buttonVariant` defaults inside `cva`. A `.default()`
+    // here would arrive downstream as an explicit author choice; the spellings
+    // are not interchangeable.
+    const result = ToastSchema.safeParse(MINIMAL);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    for (const [key] of DECLARED) expect(key in result.data, `${key} must stay absent`).toBe(false);
+  });
+
+  it('refuses a wrong-typed value on each declared key (declared-key validation under passthrough)', () => {
+    // ⚠️ THE reverse-verifiable assertion. Against the undeclared tree both keys
+    // are stripped by passthrough and `.success` stays `true`, so this block is
+    // red there and green here.
+    for (const [key, bad] of DECLARED) {
+      const result = ToastSchema.safeParse({ ...MINIMAL, [key]: bad });
+      expect(result.success, `${key} accepted ${JSON.stringify(bad)}`).toBe(false);
+      if (result.success) continue;
+      const issue = result.error.issues.find((i) => i.path[0] === key);
+      expect(issue, `${key} failed, but not on the ${key} path`).toBeTruthy();
+    }
+  });
+
+  it('accepts a well-typed value on each declared key', () => {
+    // Counter-probe for the assertion above: it must be the VALUE being refused,
+    // not the key. A pin that only ever sees red proves nothing.
+    const result = ToastSchema.safeParse({ ...MINIMAL, buttonLabel: 'Undo', buttonVariant: 'outline' });
+    expect(result.success ? null : result.error.issues).toBe(null);
+  });
+
+  it('`buttonVariant` accepts exactly the Button vocabulary and nothing else', () => {
+    for (const value of BUTTON_VARIANTS) {
+      const result = ToastSchema.safeParse({ ...MINIMAL, buttonVariant: value });
+      expect(result.success, `refused real Button variant '${value}'`).toBe(true);
+    }
+    // Plausible misspellings. `primary` is the likeliest — the default variant's
+    // own class is `bg-primary`, so the name reads correct and is not; it and
+    // the next three render an UNSTYLED button today. `''` is the one that does
+    // not look wrong: `cva`'s falsy fallback silently resolves it to `default`,
+    // so under an open `z.string()` it would render correctly and mean nothing.
+    // Both behaviours are measured in the components parity pin.
+    for (const value of ['primary', 'danger', 'warning', 'Default', '']) {
+      const result = ToastSchema.safeParse({ ...MINIMAL, buttonVariant: value });
+      expect(result.success, `accepted non-variant '${value}'`).toBe(false);
+    }
+  });
+
+  it('is NOT `z.string()` — the shape `SonnerSchema`’s mirror uses for the same key', () => {
+    // Stated as a pin because the obvious way to write this card was to copy the
+    // sibling mirror verbatim. Sonner's two faces disagree with each other
+    // (`z.string()` vs the six-member union); that disagreement is filed as
+    // objectui#6541 and deliberately NOT resolved here.
+    expect(ToastSchema.safeParse({ ...MINIMAL, buttonVariant: 'anything-at-all' }).success).toBe(false);
+  });
+
+  it('does NOT reject an undeclared key — objectui#5155’s ceiling, measured not assumed', () => {
+    // Declaring the two bought validation of DECLARED keys, not rejection of
+    // undeclared ones: `BaseSchema` is `.passthrough()`. Anyone reading this
+    // card as "misspellings now fail" is reading it wrong, and this pin says so
+    // in the one place that cannot rot.
+    const misspelled = ToastSchema.safeParse({ ...MINIMAL, buttonlabel: 'Undo', buttonVarient: 'ghost' });
+    expect(misspelled.success).toBe(true);
+  });
+});
+
+describe('ToastSchema (TS) — compile-time pin on the same keys', () => {
+  it('accepts the authoring form the renderer has always supported', () => {
+    const toastSchema: ToastSchemaTS = {
+      type: 'toast',
+      title: 'Saved',
+      variant: 'success',
+      buttonLabel: 'Save record',
+      buttonVariant: 'outline',
+    };
+    expect(toastSchema.buttonLabel).toBe('Save record');
+  });
+
+  it('refuses a wrong-typed value on every declared key', () => {
+    // Each directive below fails the build (TS2578, "unused '@ts-expect-error'")
+    // the moment its key stops being declared, because the member then resolves
+    // to `any` through `BaseSchema`'s index signature and the assignment starts
+    // succeeding. That failure is the signal this card exists to create, and it
+    // is real enforcement rather than decoration because `tsconfig.test.json`
+    // compiles this file (objectui#3009).
+
+    // @ts-expect-error — `buttonLabel` is declared `string | undefined`.
+    const buttonLabel: ToastSchemaTS['buttonLabel'] = 42;
+    // @ts-expect-error — `buttonVariant` is declared as the six Button variants.
+    const buttonVariant: ToastSchemaTS['buttonVariant'] = 'primary';
+
+    expect([buttonLabel, buttonVariant]).toHaveLength(2);
+  });
+
+  it('accepts the well-typed value on every declared key', () => {
+    // Counter-probe for the directives above: without this, a declaration
+    // narrowed to `never` would satisfy both of them.
+    const buttonLabel: ToastSchemaTS['buttonLabel'] = 'Show Toast';
+    const buttonVariant: ToastSchemaTS['buttonVariant'] = 'ghost';
+    expect([buttonLabel, buttonVariant]).toEqual(['Show Toast', 'ghost']);
+  });
+
+  it('offers every one of the six, and only those six', () => {
+    const every: NonNullable<ToastSchemaTS['buttonVariant']>[] = [...BUTTON_VARIANTS];
+    // @ts-expect-error — the type is closed; a seventh look is not authorable.
+    const extra: ToastSchemaTS['buttonVariant'] = 'primary';
+    expect([...every, extra]).toHaveLength(7);
+  });
+});
diff --git a/packages/types/src/feedback.ts b/packages/types/src/feedback.ts
index 7db886e1f3..b25068bea1 100644
--- a/packages/types/src/feedback.ts
+++ b/packages/types/src/feedback.ts
@@ -148,6 +148,31 @@ export interface ToastSchema extends BaseSchema {
    * Dismiss handler
    */
   onDismiss?: () => void;
+  /**
+   * Label for the trigger button this component renders in place.
+   *
+   * The `toast` node renders a `<Button>`; clicking it raises the toast. The
+   * renderer has always read this key (`renderers/feedback/toast.tsx`) and the
+   * registration has always offered it as an authoring input — this
+   * declaration is the third surface catching up (objectui#6496).
+   * @default 'Show Toast'
+   */
+  buttonLabel?: string;
+  /**
+   * Variant for the trigger button this component renders in place.
+   *
+   * The renderer passes this value STRAIGHT THROUGH to `<Button variant={…}>`,
+   * so the vocabulary is `ButtonProps['variant']` — the six keys of
+   * `buttonVariants`' `variant` group (`components/src/ui/button.tsx`) — and
+   * not an open string. A value outside the six is not merely unusual: `cva`
+   * contributes NO variant class for an unrecognised key and falls back to
+   * `defaultVariants` only when the value is absent OR falsy, so
+   * `buttonVariant: 'primary'` renders a button with no background and no text
+   * colour while `buttonVariant: ''` silently renders the default look. Pinned against the
+   * Button itself in
+   * `components/src/__tests__/toast-button-variant-parity.test.ts`.
+   */
+  buttonVariant?: 'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';
 }
 
 /**
diff --git a/packages/types/src/zod/feedback.zod.ts b/packages/types/src/zod/feedback.zod.ts
index 50eee04fde..a7ddd7470c 100644
--- a/packages/types/src/zod/feedback.zod.ts
+++ b/packages/types/src/zod/feedback.zod.ts
@@ -74,6 +74,20 @@ export const ToastSchema = BaseSchema.extend({
   ]).optional().describe('Toast position'),
   action: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Action button'),
   onDismiss: z.function().optional().describe('Dismiss handler'),
+  // The trigger button the `toast` renderer draws in place. `buttonVariant`
+  // is an ENUM and not `z.string()`: the renderer hands the value straight to
+  // `<Button variant={…}>`, whose vocabulary is the six keys of
+  // `buttonVariants`. `cva` contributes no variant class for an unrecognised
+  // key, so a non-empty string outside the six renders an unstyled button —
+  // and `''` is silently resolved to `default` by cva's falsy fallback
+  // (objectui#6496). ⚠️ `SonnerSchema` below spells the same key
+  // `z.string()` while its TS face declares the six-member union — that
+  // disagreement is filed as objectui#6541, NOT resolved here.
+  buttonLabel: z.string().optional().describe('Trigger button label'),
+  buttonVariant: z
+    .enum(['default', 'secondary', 'destructive', 'outline', 'ghost', 'link'])
+    .optional()
+    .describe('Trigger button variant'),
 });
 
 /**