@agent-native/toolkit 0.227.0 → 0.228.0-nightly-20261110212400

package/src/app/chat/AgentSidebar.tsx

@@ -73,7 +73,7 @@ import React, {
   lazy,
   Suspense,
 } from "react";
-import { flushSync } from "react-dom";
+import { createPortal, flushSync } from "react-dom";
 
 import { setComposerReferenceEventTarget } from "../../composer/runtime-adapters.js";
 import { Skeleton } from "../../ui/skeleton.js";
@@ -296,6 +296,12 @@ export interface AgentSidebarProps {
   forceOverlay?: boolean;
   defaultOpen?: boolean;
   disableChatShortcut?: boolean;
+  /**
+   * Draws the panel inside this element instead of beside the page, for an app
+   * whose own sidebar holds the agent. The app then owns the panel's width,
+   * motion and close button, and the key that toggles the sidebar.
+   */
+  panelHost?: HTMLElement | null;
   showCollapseButton?: boolean;
   animateMobile?: boolean;
   animateDesktop?: boolean;
@@ -376,6 +382,7 @@ export function AgentSidebar({
   forceOverlay = false,
   defaultOpen,
   disableChatShortcut = false,
+  panelHost,
   showCollapseButton = true,
   animateMobile = true,
   animateDesktop = true,
@@ -644,9 +651,18 @@ export function AgentSidebar({
     !isPerAppChatHosted &&
     !presentationMode &&
     (!frameCodeMode || !shouldParentFrameOwnAgentPanel());
+  const hostedPanel = ownsPanel && panelHost ? panelHost : null;
+  // A host switches between the agent and its other sections, so the chat
+  // stays mounted behind them once it has opened.
+  const [hostedPanelOpened, setHostedPanelOpened] = useState(false);
+  useEffect(() => {
+    if (!hostedPanel) setHostedPanelOpened(false);
+    else if (open) setHostedPanelOpened(true);
+  }, [hostedPanel, open]);
   const shouldMountPanel =
     ownsPanel &&
     (open ||
+      hostedPanelOpened ||
       backgroundPanelActive ||
       runningTabIds.size > 0 ||
       hasPendingPanelEvents);
@@ -978,10 +994,12 @@ export function AgentSidebar({
           : !presentationMode && (frameOwned ? frameSidebarOpen : open)),
       source: frameOwned ? "frame" : "app",
       mode: frameOwned ? "code" : "app",
+      hosted: Boolean(hostedPanel),
     });
   }, [
     frameCodeMode,
     frameSidebarOpen,
+    hostedPanel,
     open,
     presentationMode,
     hasFrameSidebarState,
@@ -1468,14 +1486,22 @@ export function AgentSidebar({
   useEffect(() => {
     if (!enabled) return;
     const handleKeyDown = (e: KeyboardEvent) => {
-      if (isAgentSidebarToggleShortcut(e)) {
+      // A host's element that isn't on the page yet, such as one a loading
+      // page's skeleton holds, has no panel to answer ⌘\, so the shell does.
+      if (!panelHost?.isConnected && isAgentSidebarToggleShortcut(e)) {
         e.preventDefault();
         window.dispatchEvent(
           new CustomEvent("agent-panel:toggle", { detail: { focus: true } }),
         );
         return;
       }
-      if (!disableChatShortcut && isAgentPanelChatShortcut(e)) {
+      // A Mac reports ⇧⌘I with a lowercase key, and a hosting page's panel
+      // owns that key.
+      if (
+        !disableChatShortcut &&
+        isAgentPanelChatShortcut(e) &&
+        !(panelHost && e.shiftKey)
+      ) {
         e.preventDefault();
         let selectionText = "";
         try {
@@ -1500,7 +1526,7 @@ export function AgentSidebar({
     };
     document.addEventListener("keydown", handleKeyDown);
     return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [disableChatShortcut, enabled]);
+  }, [disableChatShortcut, enabled, panelHost]);
 
   useEffect(() => {
     const handler = (event: MessageEvent) => {
@@ -1602,12 +1628,12 @@ export function AgentSidebar({
   }, [persistWidth]);
 
   const isLeft = effectivePosition === "left";
-  const isOverlay = isMobile || forceOverlay;
-  const wideDrawerEnabled = isWideDrawer && !isOverlay;
+  const isOverlay = !hostedPanel && (isMobile || forceOverlay);
+  const wideDrawerEnabled = isWideDrawer && !isOverlay && !hostedPanel;
   const mobileAnimationEnabled =
     !presentationMode && isOverlay && animateMobile;
   const desktopAnimationEnabled =
-    !presentationMode && !isOverlay && effectiveAnimateDesktop;
+    !presentationMode && !isOverlay && !hostedPanel && effectiveAnimateDesktop;
   const sidebarAnimationEnabled =
     mobileAnimationEnabled || desktopAnimationEnabled;
   const [renderAnimatedPanel, setRenderAnimatedPanel] =
@@ -1713,7 +1739,119 @@ export function AgentSidebar({
     };
   }
 
-  const sidebar = shouldRenderPanel ? (
+  const panelBody = (
+    <LazyChunkErrorBoundary
+      fallback={<LazyChunkRetryFallback />}
+      shouldHandleError={isPanelImportError}
+      onError={onPanelLoadFailed}
+    >
+      <Suspense
+        fallback={
+          <div
+            aria-hidden="true"
+            className="flex min-h-0 flex-1 flex-col gap-3 p-3"
+          >
+            <Skeleton className="h-8 w-full" />
+            <div className="flex-1" />
+            <Skeleton className="h-28 w-full rounded-xl" />
+          </div>
+        }
+      >
+        <AgentSidebarPanel
+          onReadyChange={onPanelReadyChange}
+          onReferenceTargetChange={onReferenceTargetChange}
+          onNavigationChange={onNavigationChange}
+          onTabsClosing={onTabsClosing}
+          emptyStateText={emptyStateText}
+          mcpSuggestionExcludedIntegrationIds={
+            mcpSuggestionExcludedIntegrationIds
+          }
+          suggestions={suggestions}
+          dynamicSuggestions={dynamicSuggestions}
+          suggestionPlacement="context-chips"
+          composerToolbarSlot={composerToolbarSlot}
+          composerSlot={composerSlot}
+          // A host's tab opens the chat without taking focus from the tab.
+          {...(hostedPanel ? { composerAutoFocus: false } : {})}
+          composerContextProvider={composerContextProvider}
+          onComposerTextChange={onComposerTextChange}
+          imageModelMenu={imageModelMenu}
+          availableAgents={effectiveAvailableAgents}
+          availableModels={availableModels}
+          modelListLoading={modelListLoading}
+          selectedAgent={effectiveSelectedAgent}
+          onAgentChange={effectiveOnAgentChange}
+          hostedHarness={hostedHarnessEnabled}
+          onConnectProvider={onConnectProvider}
+          builderConnectTransport={builderConnectTransport}
+          onConnectLocalRuntime={onConnectLocalRuntime}
+          runtime={runtime}
+          adapterReloadKey={adapterReloadKey}
+          threadFooterSlot={threadFooterSlot}
+          apiUrl={apiUrl}
+          agentChatSurface={agentChatSurface}
+          desktopIdentityUnauthenticated={desktopIdentityUnauthenticated}
+          desktopIdentityAuthenticated={desktopIdentityAuthenticated}
+          showTabBar={effectiveShowTabBar}
+          suppressInlineOpenApp={suppressInlineOpenApp}
+          composerPlaceholder={composerPlaceholder}
+          showMissingApiKeySetup={showMissingApiKeySetup}
+          setupCardOwner={setupCardOwner}
+          showGuidedQuestions={showGuidedQuestions}
+          missingApiKeySetupLayout="sidebar"
+          defaultMode={defaultMode}
+          onCollapse={() => setOpenPersisted(false)}
+          showCollapseButton={!hostedPanel && showCollapseButton}
+          onSnapTo75Percent={
+            isOverlay || hostedPanel ? undefined : snapTo75Percent
+          }
+          isWideDrawer={wideDrawerEnabled}
+          onExitWideDrawer={
+            isOverlay || hostedPanel ? undefined : exitWideDrawer
+          }
+          onFullViewRequest={onFullscreenRequest}
+          onOpenSettings={onOpenSettings}
+          onNewCliTab={onNewCliTab}
+          onNewUiTab={onNewUiTab}
+          renderCliTab={renderCliTab}
+          newTabMode={newTabMode}
+          newCliTabLabel={newCliTabLabel}
+          newUiTabLabel={newUiTabLabel}
+          storageKey={storageKey}
+          restoreActiveThread={restoreActiveThread}
+          scope={scope}
+          {...(chatHistory ? { chatHistory } : {})}
+          isolateHistoryByScope={isolateHistoryByScope}
+          showScopeBadge={showScopeBadge}
+          browserTabId={resolvedBrowserTabId}
+          threadUrlSync={threadUrlSync}
+          agentPageHref={agentPageHref}
+          thinkingDisplay={thinkingDisplay}
+          showModelSelector={showModelSelector}
+          chatOnly={chatOnly}
+        />
+      </Suspense>
+    </LazyChunkErrorBoundary>
+  );
+
+  const sidebar = !shouldRenderPanel ? null : hostedPanel ? (
+    createPortal(
+      <div
+        className="agent-sidebar-panel agent-kit-density flex min-h-0 flex-1 flex-col overflow-hidden"
+        data-agent-sidebar-layout="hosted"
+        data-agent-sidebar-state={panelOpen ? "open" : "closed"}
+        inert={!panelOpen || undefined}
+      >
+        <div
+          ref={panelElementRef}
+          className="agent-sidebar-panel-inner relative flex min-h-0 flex-1 flex-col"
+        >
+          {panelBody}
+        </div>
+      </div>,
+      hostedPanel,
+    )
+  ) : (
     <>
       {showResizeHandle && !isLeft && (
         <ResizeHandle
@@ -1766,92 +1904,7 @@ export function AgentSidebar({
           ref={panelElementRef}
           className="agent-sidebar-panel-inner relative flex min-h-0 flex-1 flex-col"
         >
-          <LazyChunkErrorBoundary
-            fallback={<LazyChunkRetryFallback />}
-            shouldHandleError={isPanelImportError}
-            onError={onPanelLoadFailed}
-          >
-            <Suspense
-              fallback={
-                <div
-                  aria-hidden="true"
-                  className="flex min-h-0 flex-1 flex-col gap-3 p-3"
-                >
-                  <Skeleton className="h-8 w-full" />
-                  <div className="flex-1" />
-                  <Skeleton className="h-28 w-full rounded-xl" />
-                </div>
-              }
-            >
-              <AgentSidebarPanel
-                onReadyChange={onPanelReadyChange}
-                onReferenceTargetChange={onReferenceTargetChange}
-                onNavigationChange={onNavigationChange}
-                onTabsClosing={onTabsClosing}
-                emptyStateText={emptyStateText}
-                mcpSuggestionExcludedIntegrationIds={
-                  mcpSuggestionExcludedIntegrationIds
-                }
-                suggestions={suggestions}
-                dynamicSuggestions={dynamicSuggestions}
-                suggestionPlacement="context-chips"
-                composerToolbarSlot={composerToolbarSlot}
-                composerSlot={composerSlot}
-                composerContextProvider={composerContextProvider}
-                onComposerTextChange={onComposerTextChange}
-                imageModelMenu={imageModelMenu}
-                availableAgents={effectiveAvailableAgents}
-                availableModels={availableModels}
-                modelListLoading={modelListLoading}
-                selectedAgent={effectiveSelectedAgent}
-                onAgentChange={effectiveOnAgentChange}
-                hostedHarness={hostedHarnessEnabled}
-                onConnectProvider={onConnectProvider}
-                builderConnectTransport={builderConnectTransport}
-                onConnectLocalRuntime={onConnectLocalRuntime}
-                runtime={runtime}
-                adapterReloadKey={adapterReloadKey}
-                threadFooterSlot={threadFooterSlot}
-                apiUrl={apiUrl}
-                agentChatSurface={agentChatSurface}
-                desktopIdentityUnauthenticated={desktopIdentityUnauthenticated}
-                desktopIdentityAuthenticated={desktopIdentityAuthenticated}
-                showTabBar={effectiveShowTabBar}
-                suppressInlineOpenApp={suppressInlineOpenApp}
-                composerPlaceholder={composerPlaceholder}
-                showMissingApiKeySetup={showMissingApiKeySetup}
-                setupCardOwner={setupCardOwner}
-                showGuidedQuestions={showGuidedQuestions}
-                missingApiKeySetupLayout="sidebar"
-                defaultMode={defaultMode}
-                onCollapse={() => setOpenPersisted(false)}
-                showCollapseButton={showCollapseButton}
-                onSnapTo75Percent={isOverlay ? undefined : snapTo75Percent}
-                isWideDrawer={isOverlay ? false : isWideDrawer}
-                onExitWideDrawer={isOverlay ? undefined : exitWideDrawer}
-                onFullViewRequest={onFullscreenRequest}
-                onOpenSettings={onOpenSettings}
-                onNewCliTab={onNewCliTab}
-                onNewUiTab={onNewUiTab}
-                renderCliTab={renderCliTab}
-                newTabMode={newTabMode}
-                newCliTabLabel={newCliTabLabel}
-                newUiTabLabel={newUiTabLabel}
-                storageKey={storageKey}
-                restoreActiveThread={restoreActiveThread}
-                scope={scope}
-                chatHistory={chatHistory}
-                isolateHistoryByScope={isolateHistoryByScope}
-                showScopeBadge={showScopeBadge}
-                browserTabId={resolvedBrowserTabId}
-                threadUrlSync={threadUrlSync}
-                agentPageHref={agentPageHref}
-                thinkingDisplay={thinkingDisplay}
-                showModelSelector={showModelSelector}
-                chatOnly={chatOnly}
-              />
-            </Suspense>
-          </LazyChunkErrorBoundary>
+          {panelBody}
         </div>
       </div>
       {showResizeHandle && isLeft && (
@@ -1866,7 +1919,7 @@ export function AgentSidebar({
         />
       )}
     </>
-  ) : null;
+  );
 
   const drawerPlaceholder =
     wideDrawerEnabled && !presentationMode && panelOpen ? (
@@ -1928,7 +1981,9 @@ export function AgentSidebar({
           className="agent-sidebar-main-surface flex flex-1 flex-col overflow-auto min-w-0"
           data-agent-sidebar-main-position={effectivePosition}
           data-agent-sidebar-main-state={
-            !isOverlay && !presentationMode && panelOpen ? "open" : "closed"
+            !isOverlay && !hostedPanel && !presentationMode && panelOpen
+              ? "open"
+              : "closed"
           }
           data-agent-sidebar-resizing={isResizing ? "true" : undefined}
         >

package/src/app/chat/chat/surface-types.ts

@@ -195,7 +195,7 @@ export interface AssistantChatAdapterContext {
 
 export interface AssistantChatProps {
   /** API endpoint URL. Default: "/_agent-native/agent-chat" */
-  apiUrl?: string;
+  apiUrl?: string | undefined;
   /** Optional Nitro response-streaming endpoint, usually supplied by VITE_AGENT_NATIVE_AGENT_CHAT_STREAM_URL. */
   streamingUrl?: string;
   /** Stable tab identifier passed to the adapter for event correlation */
@@ -218,21 +218,21 @@ export interface AssistantChatProps {
    * Identifies which surface hosts this chat. Defaults to "app", which keeps
    * dev filesystem/bash code-editing tools out of in-product sidebars.
    */
-  agentChatSurface?: AgentChatSurfaceKind;
+  agentChatSurface?: AgentChatSurfaceKind | undefined;
   /** Whether the desktop host is currently showing its unauthenticated identity gate. */
-  desktopIdentityUnauthenticated?: boolean;
+  desktopIdentityUnauthenticated?: boolean | undefined;
   /** Whether the desktop host has just established its authenticated identity session. */
-  desktopIdentityAuthenticated?: boolean;
+  desktopIdentityAuthenticated?: boolean | undefined;
   /** Route completed first-party open_app calls through the host app pane. */
-  suppressInlineOpenApp?: boolean;
+  suppressInlineOpenApp?: boolean | undefined;
   /** Placeholder text for empty state */
-  emptyStateText?: string;
+  emptyStateText?: string | undefined;
   /** Initial empty-thread starters. Completed turns use the runtime's model-authored suggestions. */
-  suggestions?: AgentSuggestionInput[];
+  suggestions?: AgentSuggestionInput[] | undefined;
   /** Initial empty-thread suggestion behavior; never disables or replaces runtime follow-ups. */
-  dynamicSuggestions?: AgentDynamicSuggestionsOption;
+  dynamicSuggestions?: AgentDynamicSuggestionsOption | undefined;
   /** Exclude providers whose connection flow is handled by the host app. */
-  mcpSuggestionExcludedIntegrationIds?: readonly string[];
+  mcpSuggestionExcludedIntegrationIds?: readonly string[] | undefined;
   /** Where suggestions appear. Context chips use a next-action bar at the thread base. */
   suggestionPlacement?:
     | "empty-state"
@@ -298,7 +298,9 @@ export interface AssistantChatProps {
   /** Optional ordering policy for assistant message text and attached widgets. */
   resolveMessageContentOrder?: AgentMessageContentOrderResolver;
   /** App-owned context controller, mounted separately for each chat thread. */
-  composerContextProvider?: React.ComponentType<AssistantChatComposerContextProviderProps>;
+  composerContextProvider?:
+    | React.ComponentType<AssistantChatComposerContextProviderProps>
+    | undefined;
   /** Optional home content rendered above the composer on an empty chat. */
   homeIntroSlot?: React.ReactNode;
   /** Optional content rendered below the composer on an empty chat. */
@@ -309,17 +311,17 @@ export interface AssistantChatProps {
    * Host apps can use this to render contextual, non-destructive affordances
    * beside the shared composer without replacing the composer stack.
    */
-  onComposerTextChange?: (text: string) => void;
+  onComposerTextChange?: ((text: string) => void) | undefined;
   /** Class applied to the shared composer area for host-specific sizing/skin. */
   composerAreaClassName?: string;
   /** Placeholder for the shared composer in its normal idle state. */
-  composerPlaceholder?: string;
+  composerPlaceholder?: string | undefined;
   /** Controls the compactness of the provider setup panel attached above the composer. */
   missingApiKeySetupLayout?: BuilderSetupCardLayout;
   /** Hide the provider setup panel when another host surface owns that prompt. */
-  showMissingApiKeySetup?: boolean;
+  showMissingApiKeySetup?: boolean | undefined;
   /** Keep chat-owned recovery cards hidden when the host renders the setup card. */
-  setupCardOwner?: "chat" | "host";
+  setupCardOwner?: "chat" | "host" | undefined;
   /** Visual density for the shared composer shell. */
   composerLayoutVariant?: AgentComposerLayoutVariant;
   /** Center the composer on a fresh empty chat instead of pinning it low. */
@@ -331,7 +333,7 @@ export interface AssistantChatProps {
   /** Optional action rendered beside the voice/send controls. */
   composerExtraActionButton?: React.ReactNode;
   /** Show the framework model picker in the shared composer. Defaults to true. */
-  showModelSelector?: boolean;
+  showModelSelector?: boolean | undefined;
   /** Disable the composer for capability-gated surfaces while still showing history. */
   composerDisabled?: boolean;
   /** Block sending while keeping the composer editable. */
@@ -357,14 +359,16 @@ export interface AssistantChatProps {
   /** Selected effort override for this conversation */
   selectedEffort?: ReasoningEffort;
   /** Available engine/model list for the model picker */
-  availableModels?: Array<{
-    engine: string;
-    label: string;
-    models: string[];
-    configured: boolean;
-  }>;
+  availableModels?:
+    | Array<{
+        engine: string;
+        label: string;
+        models: string[];
+        configured: boolean;
+      }>
+    | undefined;
   /** Whether the model list is still being resolved. */
-  modelListLoading?: boolean;
+  modelListLoading?: boolean | undefined;
   /** Whether the model list failed to load. */
   modelListError?: boolean;
   /** Retry loading a host-managed model list. */
@@ -374,24 +378,24 @@ export interface AssistantChatProps {
   /** Callback when user picks an effort from the picker */
   onEffortChange?: (effort: ReasoningEffort) => void;
   /** Local or hosted agent runtimes shown above the model list. */
-  availableAgents?: ComposerAgentOption[];
+  availableAgents?: ComposerAgentOption[] | undefined;
   /** Selected agent runtime identifier. */
-  selectedAgent?: string;
+  selectedAgent?: string | undefined;
   /** Mark the selected runtime as the hosted tools-only harness mode. */
   hostedHarness?: boolean;
   /** Callback when the user picks an agent runtime. */
-  onAgentChange?: (agent: string) => void;
+  onAgentChange?: ((agent: string) => void) | undefined;
   /**
    * Optional secondary model menu (e.g. an image-generation model) shown inside
    * the composer's model picker. Opt-in; chat-only apps omit it.
    */
-  imageModelMenu?: ComposerImageModelMenu;
+  imageModelMenu?: ComposerImageModelMenu | undefined;
   /** Callback when user clicks "Fork Chat" in the message actions menu */
   onForkChat?: () => void | boolean | Promise<void | boolean>;
   /** Override Builder/provider connect routing for embedded hosts. */
-  onConnectProvider?: () => void;
+  onConnectProvider?: (() => void) | undefined;
   /** Route local runtime setup through the host's native bridge. */
-  onConnectLocalRuntime?: (engine: string) => void;
+  onConnectLocalRuntime?: ((engine: string) => void) | undefined;
   /**
    * Controls the shared composer + menu. Sidebar keeps the full menu by default;
    * hosts without the sidebar provider stack can use upload-only.
@@ -400,13 +404,13 @@ export interface AssistantChatProps {
   /** Replace the built-in transport with an AgentKit-native BYO transport. */
   createTransport?: (context: AssistantChatAdapterContext) => AgentTransport;
   /** Hide the default guided-question card when another host owns its flow. */
-  showGuidedQuestions?: boolean;
+  showGuidedQuestions?: boolean | undefined;
   /**
    * Bring-your-own agent runtime. When supplied, AssistantChat keeps the
    * standard composer/transcript/tool rendering shell but sends turns through
    * this runtime instead of the built-in Agent-Native SSE endpoint.
    */
-  runtime?: AgentChatRuntime;
+  runtime?: AgentChatRuntime | undefined;
   /**
    * Explicitly recreate an injected adapter or runtime when its identity
    * changes. Omit for the production sidebar so parent rerenders do not reset
@@ -446,5 +450,5 @@ export interface AssistantChatProps {
    * let the reader's own preference apply, which is what surfaces the in-chat
    * control — a pinned mode hides it rather than leaving a dead menu item.
    */
-  thinkingDisplay?: ThinkingDisplay;
+  thinkingDisplay?: ThinkingDisplay | undefined;
 }

package/src/app/sharing/ShareButton.tsx

@@ -130,6 +130,8 @@ export interface ShareButtonProps {
     copiedLabel: string;
     onCopy: () => Promise<boolean | void> | boolean | void;
     size?: "default" | "sm";
+    /** `plain` draws Share as text, set apart from Copy link. */
+    appearance?: "joined" | "plain";
     className?: string;
   };
   /** Tooltip for the Copy link button: which link it copies. */
@@ -413,10 +415,11 @@ export function ShareButton(props: ShareButtonProps) {
     controller.handleShareTabChange,
   ]);
   const triggerLabel = t("agentChat.share.share", { defaultValue: "Share" });
+  const plainQuickCopy = props.quickCopy?.appearance === "plain";
   const trigger = (
     <ShareTrigger
       label={
-        props.quickCopy ? (
+        props.quickCopy && !plainQuickCopy ? (
           <span className="flex items-center gap-2">
             <IconUserPlus aria-hidden="true" />
             <span>{props.triggerContent ?? triggerLabel}</span>
@@ -428,8 +431,10 @@ export function ShareButton(props: ShareButtonProps) {
       className={props.triggerClassName}
       aria-label={triggerLabel}
       title={triggerLabel}
-      intent={props.quickCopy ? "primary" : undefined}
-      emphasis={props.quickCopy ? "solid" : undefined}
+      intent={props.quickCopy && !plainQuickCopy ? "primary" : undefined}
+      emphasis={
+        plainQuickCopy ? "ghost" : props.quickCopy ? "solid" : undefined
+      }
     />
   );
   if (isSmallScreen) {
@@ -442,6 +447,7 @@ export function ShareButton(props: ShareButtonProps) {
             copiedLabel={props.quickCopy.copiedLabel}
             onCopy={props.quickCopy.onCopy}
             size={props.quickCopy.size}
+            appearance={props.quickCopy.appearance}
             className={props.quickCopy.className}
           />
         ) : (
@@ -482,6 +488,7 @@ export function ShareButton(props: ShareButtonProps) {
             copiedLabel={props.quickCopy.copiedLabel}
             onCopy={props.quickCopy.onCopy}
             size={props.quickCopy.size}
+            appearance={props.quickCopy.appearance}
             className={props.quickCopy.className}
           />
         </PopoverAnchor>

package/src/composer/TiptapComposer.tsx

@@ -4824,6 +4824,8 @@ function TiptapComposerSurface({
         (e.metaKey || e.ctrlKey) &&
         !e.altKey;
       if (isToggleCombo) {
+        // A page that has already used the key keeps it.
+        if (e.defaultPrevented) return;
         e.preventDefault();
         if (voiceChatActiveRef.current) return;
         if (voice.state === "recording" || voice.state === "starting") {

package/src/composer/TiptapComposer.voice-toolbar.spec.tsx

@@ -559,6 +559,22 @@ describe("TiptapComposer voice chat", () => {
     expect(voice.start).not.toHaveBeenCalled();
   });
 
+  it("leaves the dictation key to a page that has already used it", async () => {
+    await act(async () => root.render(<Harness />));
+
+    const event = new KeyboardEvent("keydown", {
+      key: "m",
+      metaKey: true,
+      shiftKey: true,
+      cancelable: true,
+    });
+    event.preventDefault();
+    act(() => {
+      window.dispatchEvent(event);
+    });
+    expect(voice.start).not.toHaveBeenCalled();
+  });
+
   it("shows a failed session as an amber composer notice with a retry", async () => {
     activate("error");
     realtime.errorMessage = "The realtime voice connection failed.";

package/src/sharing/ShareControls.tsx

@@ -13,6 +13,8 @@ export interface JoinedShareControlProps {
   copiedLabel: string;
   onCopy: () => Promise<boolean | void> | boolean | void;
   size?: "default" | "sm";
+  /** `plain` sets the two apart, as quiet controls in a toolbar. */
+  appearance?: "joined" | "plain";
   disabled?: boolean;
   blocked?: boolean;
   className?: string;
@@ -29,6 +31,7 @@ export const JoinedShareControl = forwardRef<
     copiedLabel,
     onCopy,
     size = "default",
+    appearance = "joined",
     disabled,
     blocked,
     className,
@@ -55,6 +58,46 @@ export const JoinedShareControl = forwardRef<
   };
 
   const label = copied ? copiedLabel : copyLabel;
+  const plain = appearance === "plain";
+  const copyButton = (
+    // A click closes a tooltip, so the confirmation holds it open.
+    <Tooltip {...(copied ? { open: true } : {})}>
+      <TooltipTrigger asChild>
+        <Button
+          type="button"
+          size="sm"
+          variant={plain ? "ghost" : "default"}
+          className={cn(
+            "w-8 shrink-0 px-0 shadow-none",
+            plain && "text-muted-foreground hover:text-foreground",
+            blocked && "opacity-50",
+          )}
+          aria-label={label}
+          disabled={disabled}
+          data-blocked={blocked ? "" : undefined}
+          onClick={() => void copy()}
+        >
+          {copied ? (
+            <IconCheck aria-hidden="true" />
+          ) : (
+            <IconLink aria-hidden="true" />
+          )}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">{label}</TooltipContent>
+    </Tooltip>
+  );
+  if (plain) {
+    return (
+      <div
+        ref={ref}
+        className={cn("flex shrink-0 items-center gap-0.5", className)}
+      >
+        {trigger}
+        {copyButton}
+      </div>
+    );
+  }
   const segmentHeightClass =
     size === "sm"
       ? "[&>*:not([data-slot=button-group-separator]):not([data-button-group-ignore]):not(select[aria-hidden=true])]:!h-8"
@@ -69,30 +112,7 @@ export const JoinedShareControl = forwardRef<
       )}
     >
       {trigger}
-      <Tooltip>
-        <TooltipTrigger asChild>
-          <Button
-            type="button"
-            size="sm"
-            variant="default"
-            className={cn(
-              "w-8 shrink-0 px-0 shadow-none",
-              blocked && "opacity-50",
-            )}
-            aria-label={label}
-            disabled={disabled}
-            data-blocked={blocked ? "" : undefined}
-            onClick={() => void copy()}
-          >
-            {copied ? (
-              <IconCheck aria-hidden="true" />
-            ) : (
-              <IconLink aria-hidden="true" />
-            )}
-          </Button>
-        </TooltipTrigger>
-        <TooltipContent side="bottom">{label}</TooltipContent>
-      </Tooltip>
+      {copyButton}
     </ButtonGroup>
   );
 });