@runtypelabs/persona 4.19.0 → 4.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.19.0",
+  "version": "4.20.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/components/composer-actions.ts

@@ -32,6 +32,7 @@ import type {
   ComposerActionOverflowConfig,
   ComposerActionPlacement,
   ComposerActionPresentation,
+  ComposerActionVisibility,
   ComposerButtonAction,
   ComposerCustomAction,
   ComposerState,
@@ -345,6 +346,28 @@ const evaluate = (
   return typeof value === "function" ? value(state) === true : value === true;
 };
 
+/**
+ * The draft state `sendButton.visibility` reads: text, a pending attachment, or
+ * a live stream all count as "there is something in flight".
+ */
+const hasDraftContent = (state: Readonly<ComposerState>): boolean =>
+  state.phase === "streaming" ||
+  state.text.trim().length > 0 ||
+  state.attachments.length > 0;
+
+/**
+ * `ComposerAction.visibility` against the current draft. Evaluated on every
+ * state-driven pass, so the answer is always render-time, never patched on.
+ */
+export function matchesComposerActionVisibility(
+  visibility: ComposerActionVisibility | undefined,
+  state: Readonly<ComposerState>
+): boolean {
+  if (!visibility || visibility === "always") return true;
+  const drafting = hasDraftContent(state);
+  return visibility === "when-text" ? drafting : !drafting;
+}
+
 const isCustom = (action: ComposerAction): action is ComposerCustomAction =>
   action.kind === "custom";
 
@@ -937,7 +960,10 @@ export function createComposerActionRenderer(
       let entry = entries.get(resolved.id);
       if (!entry) continue;
       const action = resolved.action;
-      const visible = action ? evaluate(action.visible, state, true) : true;
+      const visible = action
+        ? evaluate(action.visible, state, true) &&
+          matchesComposerActionVisibility(action.visibility, state)
+        : true;
       if (entry.visible !== visible) {
         entry.visible = visible;
         // Managed elements leave the DOM when hidden; the node (and any custom

package/src/components/composer-model-picker.ts

@@ -18,6 +18,7 @@ import { createPopover, type PopoverHandle } from "../plugin-kit";
 import type { ComposerCustomAction, ComposerModel } from "../types";
 import { createElement, createNode } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
+import { forwardMenuTokens } from "./composer-parts";
 
 export const COMPOSER_MODEL_PICKER_ACTION_ID = "core:model";
 export const COMPOSER_MODEL_PICKER_ORDER = 700;
@@ -25,9 +26,8 @@ export const COMPOSER_MODEL_PICKER_ORDER = 700;
 const ROW_ICON_SIZE = 16;
 
 /**
- * Tokens the popover panel reads. It is portaled outside the themed mount, so
- * configured values are forwarded onto it on open; unset ones stamp nothing and
- * the stylesheet's fallbacks stand.
+ * Tokens the popover panel reads, forwarded onto the portaled panel on every
+ * open; unset ones clear so the stylesheet's fallbacks stand.
  */
 const MENU_TOKEN_VARS = [
   "--persona-components-composer-modelPicker-menuBackground",
@@ -62,16 +62,6 @@ export interface ComposerModelPicker {
   repaint: () => void;
 }
 
-const forwardMenuTokens = (from: HTMLElement, to: HTMLElement): void => {
-  const view = from.ownerDocument?.defaultView;
-  if (!view) return;
-  const computed = view.getComputedStyle(from);
-  for (const name of MENU_TOKEN_VARS) {
-    const value = computed.getPropertyValue(name).trim();
-    if (value) to.style.setProperty(name, value);
-  }
-};
-
 /** The wrapper both presentations share: one grid cell, control plus chevron. */
 const createWrapper = (): { wrapper: HTMLElement; chevron: HTMLElement } => {
   // `appearance: none` drops the platform chevron, which Chrome draws
@@ -221,7 +211,7 @@ export function createComposerModelPickerAction(
           onDismiss: () => trigger.setAttribute("aria-expanded", "false"),
         });
       }
-      forwardMenuTokens(trigger, menu);
+      forwardMenuTokens(trigger, menu, MENU_TOKEN_VARS);
       popover.open();
       trigger.setAttribute("aria-expanded", "true");
       const ids = [...rows.keys()];

package/src/components/composer-overflow-menu.ts

@@ -19,6 +19,7 @@ import {
   COMPOSER_CONTROL_CLASS,
   COMPOSER_CONTROL_GLYPH_CLASS,
   COMPOSER_CONTROL_ICON_FALLBACK_PX,
+  forwardMenuTokens,
 } from "./composer-parts";
 
 export interface ComposerOverflowMenuOptions {
@@ -54,6 +55,18 @@ export interface ComposerOverflowMenu {
 const focusableSelector =
   'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
 
+/**
+ * Panel surface tokens, forwarded onto the portaled panel on every open; unset
+ * ones clear so the stylesheet's fallbacks stand.
+ */
+const MENU_TOKEN_VARS = [
+  "--persona-components-composer-overflowMenu-background",
+  "--persona-components-composer-overflowMenu-borderColor",
+  "--persona-components-composer-overflowMenu-borderRadius",
+  "--persona-components-composer-overflowMenu-foreground",
+  "--persona-components-composer-overflowMenu-shadow",
+] as const;
+
 /**
  * Set on the menu row that holds keyboard focus. Rows that shade on
  * `:focus-visible` do not need it; wrapper rows around a live control do.
@@ -249,6 +262,7 @@ export function createComposerOverflowMenu(
   const open = (focusIndex = 0, viaKeyboard = false): void => {
     if (destroyed || isOpen()) return;
     keyboardModality = viaKeyboard;
+    forwardMenuTokens(triggerButton, panel, MENU_TOKEN_VARS);
     ensurePopover().open();
     triggerButton.setAttribute("aria-expanded", "true");
     const targets = focusables();

package/src/components/composer-parts.ts

@@ -41,6 +41,26 @@ export const COMPOSER_CONTROL_FALLBACK_PX = 40;
 /** Icon-size token default in CSS pixels, for the same JS-derived cases. */
 export const COMPOSER_CONTROL_ICON_FALLBACK_PX = 24;
 
+/**
+ * Forward theme vars onto a portaled menu panel, which lives outside the
+ * themed mount. The panel is reused across opens, so an unset var must clear
+ * any previously stamped value for the stylesheet fallback to paint again.
+ */
+export const forwardMenuTokens = (
+  from: HTMLElement,
+  to: HTMLElement,
+  names: readonly string[]
+): void => {
+  const view = from.ownerDocument?.defaultView;
+  if (!view) return;
+  const computed = view.getComputedStyle(from);
+  for (const name of names) {
+    const value = computed.getPropertyValue(name).trim();
+    if (value) to.style.setProperty(name, value);
+    else to.style.removeProperty(name);
+  }
+};
+
 export interface ComposerTextareaParts {
   textarea: HTMLTextAreaElement;
   /**

package/src/index-core.ts

@@ -91,6 +91,7 @@ export type {
   ComposerActionBase,
   ComposerActionPlacement,
   ComposerActionPresentation,
+  ComposerActionVisibility,
   ComposerButtonAction,
   ComposerCustomAction,
   ComposerActionContext,
@@ -103,6 +104,7 @@ export type {
   ComposerModelPickerPresentation,
   // Composer modes + mode groups (composer.modes, composer.modeGroups)
   ComposerMode,
+  ComposerModeChipVisibility,
   ComposerModeGroup,
   ComposerModeGroupPresentation,
   // Composer baseline configuration (submit keys, sizing, locks)

package/src/styles/widget-styles.test.ts

@@ -585,6 +585,38 @@ describe("overflow menu row shading", () => {
     );
     expect(widgetCss).toContain(".persona-composer-overflow-menu__slot:hover");
   });
+
+  it("reads every overflowMenu token as a full path over the stock fallback", () => {
+    const at = widgetCss.indexOf(".persona-composer-overflow-menu {");
+    expect(at, "overflow menu panel rule not found").toBeGreaterThan(-1);
+    const panel = widgetCss.slice(at, widgetCss.indexOf("}", at));
+
+    expect(panel).toContain(
+      "--persona-components-composer-overflowMenu-background,"
+    );
+    expect(panel).toContain("var(--persona-surface, #ffffff)");
+    expect(panel).toContain(
+      "--persona-components-composer-overflowMenu-borderColor,"
+    );
+    expect(panel).toContain("var(--persona-border, #e5e7eb)");
+    expect(panel).toContain(
+      "--persona-components-composer-overflowMenu-borderRadius,"
+    );
+    expect(panel).toContain(
+      "--persona-components-composer-overflowMenu-foreground,"
+    );
+    expect(panel).toContain(
+      "--persona-components-composer-overflowMenu-shadow,"
+    );
+  });
+
+  it("keeps the portaled panel rule unprefixed", () => {
+    // createPopover mounts the panel outside the widget root, so a
+    // `[data-persona-root]` prefix would never match it.
+    expect(widgetCss).not.toContain(
+      "[data-persona-root] .persona-composer-overflow-menu"
+    );
+  });
 });
 
 describe("composer control focus rings", () => {
@@ -658,7 +690,11 @@ describe("model picker chevron", () => {
 
   it("colors the chevron from the theme token, never a baked-in hex", () => {
     const rule = ruleFor(".persona-composer-model-picker-chevron");
-    expect(rule).toContain("background-color: var(--persona-button-ghost-fg");
+    // Same chain as the label, so the glyph and the text never diverge.
+    expect(rule).toContain(
+      "--persona-components-composer-modelPicker-labelColor"
+    );
+    expect(rule).toContain("var(--persona-button-ghost-fg");
     // The mask only needs opaque alpha, so the SVG's own stroke is not a color.
     expect(rule).toContain("mask-image");
     expect(rule).toContain("-webkit-mask-image");
@@ -840,6 +876,52 @@ describe("model picker popover", () => {
   });
 });
 
+describe("model picker closed control surface", () => {
+  const ruleFor = (selector: string): string => {
+    const at = widgetCss.indexOf(selector);
+    expect(at, `selector not found: ${selector}`).toBeGreaterThan(-1);
+    return widgetCss.slice(at, widgetCss.indexOf("}", at));
+  };
+
+  it("reads the surface tokens over the ghost button fallbacks", () => {
+    // One vocabulary for both presentations: the native select and the popover
+    // trigger share this rule, so a page that stays native still themes.
+    const rule = ruleFor("[data-persona-root] .persona-composer-model-picker {");
+    expect(rule).toContain(
+      "--persona-components-composer-modelPicker-background,"
+    );
+    expect(rule).toContain("var(--persona-button-ghost-bg, transparent)");
+    expect(rule).toContain(
+      "--persona-components-composer-modelPicker-borderRadius,"
+    );
+    expect(rule).toContain("var(--persona-button-ghost-radius");
+    expect(rule).toContain(
+      "--persona-components-composer-modelPicker-labelColor,"
+    );
+    expect(rule).toContain("var(--persona-button-ghost-fg");
+  });
+
+  it("draws borderColor as an inset ring so the control never resizes", () => {
+    // A real border would eat 1px of the content box under `border-box` sizing
+    // and shift the label on every theme that leaves the token unset.
+    const rule = ruleFor("[data-persona-root] .persona-composer-model-picker {");
+    expect(rule).toContain("border: none");
+    expect(rule).toContain(
+      "box-shadow: inset 0 0 0 1px\n    var(--persona-components-composer-modelPicker-borderColor, transparent)"
+    );
+  });
+
+  it("keeps hover on its own token so a themed fill survives the pointer", () => {
+    const rule = ruleFor(
+      "[data-persona-root] .persona-composer-model-picker:hover:not(:disabled) {"
+    );
+    expect(rule).toContain(
+      "--persona-components-composer-modelPicker-hoverBackground,"
+    );
+    expect(rule).toContain("var(--persona-button-ghost-hover-bg");
+  });
+});
+
 describe("composer motion", () => {
   /** Every `@media (prefers-reduced-motion: no-preference)` block, joined. */
   const reducedMotionSafeCss = (): string => {

package/src/styles/widget.css

@@ -1371,7 +1371,8 @@
  *
  * The panel is mounted by createPopover next to the widget root (or inside the
  * shadow root), so its rules are deliberately un-prefixed by
- * `[data-persona-root]` and must stand on their own. */
+ * `[data-persona-root]` and must stand on their own. It sits outside the themed
+ * mount, so the menu forwards its configured tokens onto the panel on open. */
 .persona-composer-overflow-menu {
   display: flex;
   flex-direction: column;
@@ -1380,11 +1381,27 @@
   max-height: 320px;
   overflow-y: auto;
   padding: 4px;
-  border-radius: var(--persona-radius-lg, 0.5rem);
-  border: 1px solid var(--persona-border, #e5e7eb);
-  background: var(--persona-surface, #ffffff);
-  color: var(--persona-text, #111827);
-  box-shadow: var(--persona-shadow-md, 0 8px 24px rgba(0, 0, 0, 0.12));
+  border-radius: var(
+    --persona-components-composer-overflowMenu-borderRadius,
+    var(--persona-radius-lg, 0.5rem)
+  );
+  border: 1px solid
+    var(
+      --persona-components-composer-overflowMenu-borderColor,
+      var(--persona-border, #e5e7eb)
+    );
+  background: var(
+    --persona-components-composer-overflowMenu-background,
+    var(--persona-surface, #ffffff)
+  );
+  color: var(
+    --persona-components-composer-overflowMenu-foreground,
+    var(--persona-text, #111827)
+  );
+  box-shadow: var(
+    --persona-components-composer-overflowMenu-shadow,
+    var(--persona-shadow-md, 0 8px 24px rgba(0, 0, 0, 0.12))
+  );
   font-family: var(--persona-font-family, inherit);
 }
 
@@ -1598,9 +1615,22 @@
   padding-inline-start: 0.625rem;
   padding-inline-end: 1.75rem;
   border: none;
-  border-radius: var(--persona-button-ghost-radius, var(--persona-radius-md, 0.375rem));
-  background-color: var(--persona-button-ghost-bg, transparent);
-  color: var(--persona-button-ghost-fg, var(--persona-text, #111827));
+  border-radius: var(
+    --persona-components-composer-modelPicker-borderRadius,
+    var(--persona-button-ghost-radius, var(--persona-radius-md, 0.375rem))
+  );
+  background-color: var(
+    --persona-components-composer-modelPicker-background,
+    var(--persona-button-ghost-bg, transparent)
+  );
+  color: var(
+    --persona-components-composer-modelPicker-labelColor,
+    var(--persona-button-ghost-fg, var(--persona-text, #111827))
+  );
+  /* A ring, not a border: `border-box` sizing would pull the label in by 1px on
+     every theme that never sets the token. */
+  box-shadow: inset 0 0 0 1px
+    var(--persona-components-composer-modelPicker-borderColor, transparent);
   font-family: inherit;
   font-size: 0.8125rem;
   cursor: pointer;
@@ -1616,16 +1646,19 @@
   text-align: start;
 }
 
-/* The chevron is a MASK, not a data-URI stroke color: the fill comes from the
-   ghost foreground token, so it themes with every other composer glyph. Same
-   Lucide `chevron-down` geometry as the icon registry draws. */
+/* The chevron is a MASK, not a data-URI stroke color: the fill follows the
+   closed control's own text color, so the glyph and the label never diverge.
+   Same Lucide `chevron-down` geometry as the icon registry draws. */
 .persona-composer-model-picker-chevron {
   justify-self: end;
   margin-inline-end: 0.625rem;
   width: 0.875rem;
   height: 0.875rem;
   pointer-events: none;
-  background-color: var(--persona-button-ghost-fg, var(--persona-text, #111827));
+  background-color: var(
+    --persona-components-composer-modelPicker-labelColor,
+    var(--persona-button-ghost-fg, var(--persona-text, #111827))
+  );
   -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E");
   mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E");
   -webkit-mask-repeat: no-repeat;
@@ -1653,7 +1686,10 @@
 }
 
 [data-persona-root] .persona-composer-model-picker:hover:not(:disabled) {
-  background-color: var(--persona-button-ghost-hover-bg, rgba(0, 0, 0, 0.05));
+  background-color: var(
+    --persona-components-composer-modelPicker-hoverBackground,
+    var(--persona-button-ghost-hover-bg, rgba(0, 0, 0, 0.05))
+  );
 }
 
 [data-persona-root] .persona-composer-model-picker:disabled {

package/src/theme-reference.ts

@@ -173,7 +173,7 @@ export const THEME_TOKEN_DOCS = {
         'Shared scrollbar appearance for every scroller: thumb (default semantic.colors.border), track (default transparent).',
       reasoningBubble: 'shadow: reasoning/thinking row box-shadow.',
       composer:
-        'Message input form: shadow (box-shadow), borderColor, padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type), controlSize (edge of every icon control in the action row: attachment, mention, mic, action buttons, overflow trigger, icon-mode send; default 40px) and controlIconSize (glyph inside them, default 24px). Per-control config keys (sendButton.size, voiceRecognition.iconSize) override controlSize; coarse-pointer devices floor the hit area at 40px. overlayBand paints the band behind an overlaid footer (composer.placement: "overlay"). segmented styles a segmented mode-group track (trackBackground, trackBorderRadius, padding, activeBackground, activeForeground, activeShadow, inactiveForeground, itemPadding); every key is optional and the stylesheet owns the defaults. modelPicker styles the popover model picker (menuBackground, menuBorderRadius, rowHoverBackground, labelColor, descriptionColor, suffixColor), also all optional.',
+        'Message input form: shadow (box-shadow), borderColor, padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type), controlSize (edge of every icon control in the action row: attachment, mention, mic, action buttons, overflow trigger, icon-mode send; default 40px) and controlIconSize (glyph inside them, default 24px). Per-control config keys (sendButton.size, voiceRecognition.iconSize) override controlSize; coarse-pointer devices floor the hit area at 40px. overlayBand paints the band behind an overlaid footer (composer.placement: "overlay"). segmented styles a segmented mode-group track (trackBackground, trackBorderRadius, padding, activeBackground, activeForeground, activeShadow, inactiveForeground, itemPadding); every key is optional and the stylesheet owns the defaults. modelPicker styles the model picker (background, hoverBackground, borderColor, borderRadius and labelColor on the closed control, which the native select and the popover trigger share; menuBackground, menuBorderRadius, rowHoverBackground, descriptionColor and suffixColor on the popover only), also all optional. overflowMenu styles the composer overflow "+" menu panel (background, borderColor, borderRadius, foreground, shadow), also all optional.',
       artifact:
         'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
     },

package/src/types/theme.ts

@@ -663,21 +663,41 @@ export interface ComposerSegmentedTokens {
 }
 
 /**
- * Model picker popover (`composer.modelPicker.presentation: "popover"`).
+ * Model picker chrome (`composer.models`).
+ *
+ * The surface keys (`background`, `hoverBackground`, `borderColor`,
+ * `borderRadius`, `labelColor`) style the CLOSED control, so the native
+ * `<select>` and the `presentation: "popover"` trigger share one vocabulary.
+ * The `menu*`, `rowHoverBackground`, and `descriptionColor` keys style the
+ * popover panel and are inert under the native select, as is `suffixColor`,
+ * which a `<select>` cannot carry either.
  *
  * Every key is optional and unset ones emit nothing: the stylesheet's `var()`
  * fallbacks own the default look, which derives from the surface and ghost
- * button tokens. Inert under the native `<select>` presentation, except
- * `suffixColor`, which the native control cannot carry either.
+ * button tokens.
  */
 export interface ComposerModelPickerTokens {
+  /** Closed control fill. @default the ghost button fill (transparent) */
+  background?: TokenReference<'color'>;
+  /** Closed control fill under hover. @default the ghost hover wash */
+  hoverBackground?: TokenReference<'color'>;
+  /**
+   * Closed control outline, drawn as a 1px inset ring so setting it never
+   * resizes the control. @default none
+   */
+  borderColor?: TokenReference<'color'>;
+  /** Closed control corner radius. @default the ghost button radius */
+  borderRadius?: TokenReference<'radius'>;
   /** Panel fill behind the rows. @default semantic.colors.surface */
   menuBackground?: TokenReference<'color'>;
   /** Panel corner radius. @default palette.radius.lg */
   menuBorderRadius?: TokenReference<'radius'>;
   /** Row fill under hover and the focused option. @default the ghost hover wash */
   rowHoverBackground?: TokenReference<'color'>;
-  /** Row label and closed-control label color. @default inherited text */
+  /**
+   * Row label color, plus the closed control's text and chevron in both
+   * presentations. @default the ghost button foreground
+   */
   labelColor?: TokenReference<'color'>;
   /** Second line under a row label. @default semantic.colors.textMuted */
   descriptionColor?: TokenReference<'color'>;
@@ -685,6 +705,26 @@ export interface ComposerModelPickerTokens {
   suffixColor?: TokenReference<'color'>;
 }
 
+/**
+ * Composer overflow `+` menu panel (`composer.actionOverflow`).
+ *
+ * Every key is optional and unset ones emit nothing: the stylesheet's `var()`
+ * fallbacks own the default look. The panel is portaled outside the themed
+ * mount, so the menu forwards the configured values onto it when it opens.
+ */
+export interface ComposerOverflowMenuTokens {
+  /** Panel fill behind the rows. @default semantic.colors.surface */
+  background?: TokenReference<'color'>;
+  /** Panel border color. @default semantic.colors.border */
+  borderColor?: TokenReference<'color'>;
+  /** Panel corner radius. @default palette.radius.lg */
+  borderRadius?: TokenReference<'radius'>;
+  /** Row text and glyph color. @default semantic.colors.text */
+  foreground?: TokenReference<'color'>;
+  /** Panel elevation (raw CSS box-shadow, `none` allowed). @default palette.shadows.md */
+  shadow?: string;
+}
+
 /** Composer (message input) chrome. */
 export interface ComposerChromeTokens {
   /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
@@ -719,8 +759,10 @@ export interface ComposerChromeTokens {
   overlayBand?: string;
   /** Segmented mode-group track. */
   segmented?: ComposerSegmentedTokens;
-  /** Model picker popover chrome. */
+  /** Model picker chrome (closed control plus popover panel). */
   modelPicker?: ComposerModelPickerTokens;
+  /** Overflow `+` menu panel chrome. */
+  overflowMenu?: ComposerOverflowMenuTokens;
 }
 
 /**

package/src/types.ts

@@ -4007,6 +4007,16 @@ export type ComposerActionPlacement = "start" | "end";
  */
 export type ComposerActionPresentation = "bar" | "overflow" | "auto";
 
+/**
+ * When a composer action is mounted, as a function of the draft.
+ *
+ * - `"always"` (default): the control is always mounted.
+ * - `"when-empty"`: hidden as soon as the draft holds text or an attachment,
+ *   and while a response streams.
+ * - `"when-text"`: the inverse, on the same draft state the send control reads.
+ */
+export type ComposerActionVisibility = "always" | "when-empty" | "when-text";
+
 /**
  * Fields shared by every composer action.
  *
@@ -4022,6 +4032,13 @@ export type ComposerActionBase = {
   presentation?: ComposerActionPresentation;
   order?: number;
   visible?: boolean | ((state: Readonly<ComposerState>) => boolean);
+  /**
+   * Draft-driven visibility, on the same state `sendButton.visibility` reads.
+   * Hidden removes the control from layout and tab order. Combined with
+   * `visible`: both must pass.
+   * @default "always"
+   */
+  visibility?: ComposerActionVisibility;
   disabled?: boolean | ((state: Readonly<ComposerState>) => boolean);
   /** Disable while a response streams, through the composer's own mechanism. */
   disableWhenStreaming?: boolean;
@@ -4180,6 +4197,16 @@ export type ComposerMode = {
  */
 export type ComposerModeGroupPresentation = "buttons" | "segmented";
 
+/**
+ * Whether a group's active modes also render as removable chips.
+ *
+ * - `"auto"` (default): one chip per active mode, except under `"segmented"`
+ *   presentation, where the track already shows the state.
+ * - `"hidden"`: no chips for this group under any presentation. The pressed bar
+ *   button carries the state, and deselection stays on the button.
+ */
+export type ComposerModeChipVisibility = "auto" | "hidden";
+
 /**
  * Selection policy for a set of modes. `"single"` deselects siblings when one
  * is chosen; `"multiple"` toggles independently.
@@ -4189,6 +4216,12 @@ export type ComposerModeGroup = {
   selection: "single" | "multiple";
   /** @default "buttons" */
   presentation?: ComposerModeGroupPresentation;
+  /**
+   * Chip row policy for this group's active modes. The chip row itself is
+   * derived from its children, so a group with no other chips leaves no gap.
+   * @default "auto"
+   */
+  chipVisibility?: ComposerModeChipVisibility;
   /**
    * Accessible name for a segmented track. With it the track is a labelled
    * `role="group"`; without it the segments stand on their own names.