@dxos/plugin-assistant 0.10.0 → 0.11.1

package/src/components/ChatThread/widgets/BranchWidget.stories.tsx

@@ -0,0 +1,83 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { MessageThreadContext } from '../sync';
+import { BranchWidget, type BranchWidgetProps } from './BranchWidget';
+
+const MESSAGE_ID = '01JQ0000000000000000000001';
+
+const onRewind = fn();
+
+const baseWidgetProps = {
+  _tag: 'branch',
+  range: { from: 0, to: 1 },
+} satisfies Pick<BranchWidgetProps, '_tag' | 'range'>;
+
+const meta = {
+  title: 'plugins/plugin-assistant/components/ChatWidgets/BranchWidget',
+  component: BranchWidget,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof BranchWidget>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    ...baseWidgetProps,
+    messageId: MESSAGE_ID,
+    created: '2026-07-29T14:32:00.000Z',
+    context: new MessageThreadContext(),
+  },
+};
+
+/** No timestamp: the toolbar still offers the rewind action. */
+export const NoTimestamp: Story = {
+  args: {
+    ...baseWidgetProps,
+    messageId: MESSAGE_ID,
+    context: new MessageThreadContext(),
+  },
+};
+
+/** Without a message id there is nothing to rewind to, so the widget renders nothing. */
+export const NoMessage: Story = {
+  args: {
+    ...baseWidgetProps,
+    created: '2026-07-29T14:32:00.000Z',
+    context: new MessageThreadContext(),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.queryByTestId('chat.rewind')).toBeNull();
+  },
+};
+
+/** Clicking rewind reports the prompt's message id, which is what the thread soft-forks from. */
+export const Clicked: Story = {
+  args: {
+    ...baseWidgetProps,
+    messageId: MESSAGE_ID,
+    created: '2026-07-29T14:32:00.000Z',
+    context: new MessageThreadContext(undefined, { onRewind }),
+  },
+  play: async ({ canvasElement }) => {
+    onRewind.mockClear();
+    const canvas = within(canvasElement);
+    await userEvent.click(await canvas.findByTestId('chat.rewind'));
+    await expect(onRewind).toHaveBeenCalledWith(MESSAGE_ID);
+  },
+};

package/src/components/ChatThread/widgets/BranchWidget.test.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { formatTime } from './format-time';
+
+const NOW = new Date('2026-07-29T12:00:00Z').getTime();
+
+describe('formatTime', () => {
+  test('renders an empty string for an unparseable timestamp', ({ expect }) => {
+    expect(formatTime('not a date', NOW)).toBe('');
+  });
+
+  test('renders sub-minute ages in seconds', ({ expect }) => {
+    expect(formatTime(ago(20 * SECOND), NOW)).toMatch(/20 (seconds?|sec)/i);
+    // Never "0 seconds ago".
+    expect(formatTime(ago(200), NOW)).toMatch(/1 (second|sec)/i);
+  });
+
+  test('renders minutes and hours relatively', ({ expect }) => {
+    expect(formatTime(ago(5 * MINUTE), NOW)).toMatch(/5 min/i);
+    expect(formatTime(ago(3 * HOUR), NOW)).toMatch(/3 (hours?|hr)/i);
+  });
+
+  test('renders the previous day as yesterday', ({ expect }) => {
+    expect(formatTime(ago(26 * HOUR), NOW)).toMatch(/yesterday/i);
+  });
+
+  // Two days is the cut-over: beyond it a date reads better than a growing "N days ago".
+  test('renders anything two days or older as a date', ({ expect }) => {
+    const older = formatTime(ago(2 * DAY), NOW);
+    expect(older).not.toMatch(/ago|yesterday/i);
+    expect(older).toMatch(/\d/);
+    expect(formatTime(ago(400 * DAY), NOW)).not.toMatch(/ago/i);
+  });
+
+  test('stays just inside the relative window below two days', ({ expect }) => {
+    expect(formatTime(ago(2 * DAY - MINUTE), NOW)).toMatch(/ago|yesterday/i);
+  });
+
+  // Clock skew across peers can date a message slightly in the future; a "in 3 minutes" prompt would
+  // read as a bug, so fall back to the absolute date.
+  test('renders a future timestamp as a date', ({ expect }) => {
+    expect(formatTime(new Date(NOW + 5 * MINUTE).toISOString(), NOW)).not.toMatch(/ago|in \d/i);
+  });
+});
+
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const ago = (elapsed: number) => new Date(NOW - elapsed).toISOString();

package/src/components/ChatThread/widgets/BranchWidget.tsx

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { IconButton, useTranslation } from '@dxos/react-ui';
+import { type XmlWidgetProps } from '@dxos/ui-editor';
+
+import { meta } from '#meta';
+
+import { type MessageThreadContext } from '../sync';
+import { formatTime } from './format-time';
+
+export type BranchWidgetProps = XmlWidgetProps<
+  {
+    /** Id of the message to rewind to. Named to avoid colliding with the widget's own `id` prop. */
+    messageId?: string;
+    /** ISO timestamp of the message. */
+    created?: string;
+  },
+  MessageThreadContext
+>;
+
+/**
+ * Mini toolbar rendered below each user prompt, offering a soft fork ("rewind") back to that prompt
+ * along with when it was sent.
+ */
+export const BranchWidget = ({ messageId, created, context }: BranchWidgetProps) => {
+  const { t } = useTranslation(meta.profile.key);
+
+  const handleRewind = useCallback(() => {
+    if (messageId) {
+      context?.rewind(messageId);
+    }
+  }, [context, messageId]);
+
+  if (!messageId) {
+    return null;
+  }
+
+  return (
+    <div role='toolbar' className='flex items-center p-1 gap-1 justify-end text-xs text-subdued hover:text-inherit'>
+      <IconButton
+        classNames='min-h-0 p-1'
+        icon='ph--clock-counter-clockwise--regular'
+        iconOnly
+        variant='ghost'
+        size={4}
+        label={t('rewind.label')}
+        data-testid='chat.rewind'
+        onClick={handleRewind}
+      />
+      {created && (
+        <time dateTime={created} title={new Date(created).toLocaleString()}>
+          {formatTime(created)}
+        </time>
+      )}
+    </div>
+  );
+};

package/src/components/ChatThread/widgets/FallbackWidget.tsx

@@ -14,8 +14,8 @@ export const FallbackWidget = ({ _tag, ...props }: XmlWidgetProps<MessageThreadC
   return (
     <TogglePanel.Root>
       <TogglePanel.Content>
-        <TogglePanel.Header classNames='bg-group-surface'>{_tag}</TogglePanel.Header>
-        <TogglePanel.Body classNames='bg-modal-surface'>
+        <TogglePanel.Header classNames='dx-group-surface'>{_tag}</TogglePanel.Header>
+        <TogglePanel.Body classNames='dx-modal-surface'>
           <TogglePanel.Viewport>
             <JsonHighlighter classNames='p-2! text-sm' data={props} />
           </TogglePanel.Viewport>

package/src/components/ChatThread/widgets/ReasoningWidget.ts

@@ -47,7 +47,7 @@ export class ReasoningWidget extends WidgetType {
           .append(
             Domino.of('div')
               .classNames(
-                'relative z-10 bg-base-surface rounded-sm text-sm text-subdued py-1',
+                'relative z-10 dx-base-surface rounded-sm text-sm text-subdued py-1',
                 'grid grid-cols-[24px_1fr] gap-x-0.5 items-start',
               )
               .append(

package/src/components/ChatThread/widgets/ReferenceWidget.ts

@@ -23,11 +23,6 @@ export class ReferenceWidget extends WidgetType {
   override toDOM() {
     return Domino.of('div')
       .classNames(styles.padding)
-      .append(
-        Domino.of('dx-anchor' as any)
-          .classNames('dx-tag--anchor')
-          .attributes({ dxn: this.dxn })
-          .text(this.text),
-      ).root;
+      .append(Domino.of('dx-anchor').classNames('dx-tag--anchor').attributes({ dxn: this.dxn }).text(this.text)).root;
   }
 }

package/src/components/ChatThread/widgets/SuggestionWidget.ts

@@ -20,18 +20,27 @@ export class SuggestionWidget extends WidgetType {
 
   override toDOM() {
     // NOTE: Container must have `dx-inline-size-container` (or `dx-size-container`) to support cqi.
+    //
+    // Inline-level root so consecutive suggestions flow onto one wrapped line rather than stacking —
+    // the tag is registered `block: false` and the renderer omits the usual block separator between
+    // them.
+    //
+    // Vertical space must be **padding, never margin**: CodeMirror measures a widget from its own box,
+    // and a margin sits outside what it can see, so the height model drifts from what is rendered, the
+    // error accumulates down the document, and the turn-fold gutter markers end up visibly misaligned.
+    // Adjacent chips are likewise spaced with trailing padding rather than a margin.
     return Domino.of('span')
-      .classNames(mx('inline-flex max-w-[calc(100cqi-8px)] my-1 pe-2 overflow-hidden'))
+      .classNames(mx('inline-flex max-w-[calc(100cqi-8px)] py-1 pe-1 overflow-hidden'))
       .append(
         Domino.of('button')
           .attributes({
-            'data-action': 'submit',
             'data-density': 'md',
+            'data-action': 'submit',
             'data-value': this.text,
           })
           .classNames(mx('dx-button gap-2 w-full overflow-hidden'))
           .append(
-            Domino.of('dx-icon' as any).attributes({
+            Domino.of('dx-icon').attributes({
               icon: 'ph--lightning--regular',
             }),
             Domino.of('span').classNames('flex-1 truncate min-w-0').text(this.text),

package/src/components/ChatThread/widgets/SummaryWidget.tsx

@@ -19,7 +19,7 @@ export const SummaryWidget = ({ children }: XmlWidgetProps<MessageThreadContext>
   return (
     <TogglePanel.Root>
       <TogglePanel.Content classNames={styles.border}>
-        <TogglePanel.Header classNames='text-sm bg-group-surface'>{t('summary.label')}</TogglePanel.Header>
+        <TogglePanel.Header classNames='text-sm dx-group-surface'>{t('summary.label')}</TogglePanel.Header>
         <TogglePanel.Body>
           <div className='p-1 text-sm text-subdued'>{children}</div>
         </TogglePanel.Body>

package/src/components/ChatThread/widgets/ToolWidget.tsx

@@ -5,19 +5,15 @@
 import type * as Tool from '@effect/ai/Tool';
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-import { Icon, useTranslation } from '@dxos/react-ui';
+import { Icon, IconBlock, useTranslation } from '@dxos/react-ui';
 import { NumericTabs, TextCrawl, TogglePanel, type TogglePanelRootProps } from '@dxos/react-ui-components';
 import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
-import { type ContentBlock, type Message } from '@dxos/types';
+import { type ContentBlock } from '@dxos/types';
 import { type XmlWidgetProps } from '@dxos/ui-editor';
 import { isNonNullable, safeParseJson } from '@dxos/util';
 
 import { meta } from '#meta';
 
-export const isToolMessage = (message: Message.Message) => {
-  return message.blocks.some((block: ContentBlock.Any) => block._tag === 'toolCall' || block._tag === 'toolResult');
-};
-
 export type ToolWidgetProps = XmlWidgetProps<{
   blocks: ContentBlock.Any[];
 }>;
@@ -143,9 +139,19 @@ const ToolPanel = ({ items, onChangeOpen }: ToolPanelProps) => {
   return (
     <TogglePanel.Root open={open} onChangeOpen={setOpen}>
       <TogglePanel.Content>
-        <TogglePanel.Header classNames='flex items-center gap-2 text-sm text-placeholder'>
-          <Icon icon={headerIcon} size={4} classNames='shrink-0 opacity-70' />
-          <TextCrawl key='status-roll' lines={items.map((item) => item.title)} autoAdvance greedy />
+        <TogglePanel.Header classNames='flex items-center gap-2 text-sm'>
+          <div className='w-full grid grid-cols-[1fr_auto] items-center gap-2'>
+            <TextCrawl
+              key='status-roll'
+              classNames='text-description'
+              lines={items.map((item) => item.title)}
+              autoAdvance
+              greedy
+            />
+            <IconBlock>
+              <Icon icon={headerIcon} size={4} />
+            </IconBlock>
+          </div>
         </TogglePanel.Header>
         <TogglePanel.Body>
           <TogglePanel.Viewport classNames='grid grid-cols-[32px_1fr]'>

package/src/components/ChatThread/widgets/defaults.ts

@@ -3,6 +3,12 @@
 //
 
 export const styles = {
-  padding: 'my-4',
+  /**
+   * Vertical rhythm for block widgets. Padding, never margin: CodeMirror measures a widget from its own
+   * box, so a margin sits outside what it can see and its height model drifts from what is rendered —
+   * the error accumulates down the document until the turn-fold gutter markers are visibly misaligned.
+   * Note padding does not collapse between adjacent siblings the way margins do
+   */
+  padding: 'pt-2 pb-4',
   border: 'border border-subdued-separator rounded-sm',
 };

package/src/components/ChatThread/widgets/format-time.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Kept out of `BranchWidget.tsx`: react-refresh only fast-refreshes a module whose
+// exports are all components, so values exported beside them force a full page reload on
+// every edit.
+
+/**
+ * Relative ("5 min ago", "yesterday") within two days, absolute date beyond that. The exact
+ * timestamp is always available via the `title` tooltip.
+ *
+ * Recent prompts are the ones a reader places by elapsed time; older ones by date.
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export const formatTime = (created: string, now = Date.now()): string => {
+  const date = new Date(created);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+
+  const elapsed = now - date.getTime();
+  if (elapsed < 0 || elapsed >= 2 * DAY_MS) {
+    return date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+  }
+
+  const format = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+  const minutes = Math.round(elapsed / 60_000);
+  if (minutes < 1) {
+    // Seconds rather than `format(0, 'minute')`, which renders as "this minute".
+    return format.format(-Math.max(1, Math.round(elapsed / 1000)), 'second');
+  }
+  if (minutes < 60) {
+    return format.format(-minutes, 'minute');
+  }
+
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) {
+    return format.format(-hours, 'hour');
+  }
+
+  // `numeric: 'auto'` renders -1 day as "yesterday".
+  return format.format(-Math.round(hours / 24), 'day');
+};

package/src/components/ChatThread/widgets/index.ts

@@ -2,13 +2,16 @@
 // Copyright 2026 DXOS.org
 //
 
+export * from './format-time';
+export * from './BranchWidget';
 export * from './FallbackWidget';
 export * from './ReasoningWidget';
 export * from './ReferenceWidget';
 export * from './SelectWidget';
 export * from './StatsWidget';
 export * from './StatusWidget';
+export * from './SuggestionWidget';
 export * from './SummaryWidget';
 export * from './SurfaceWidget';
-export * from './SuggestionWidget';
+export * from './is-tool-message';
 export * from './ToolWidget';

package/src/components/ChatThread/widgets/is-tool-message.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ContentBlock, type Message } from '@dxos/types';
+
+// Kept out of `ToolWidget.tsx`: react-refresh only fast-refreshes a module whose
+// exports are all components, so values exported beside them force a full page reload on
+// every edit.
+
+export const isToolMessage = (message: Message.Message) => {
+  return message.blocks.some((block: ContentBlock.Any) => block._tag === 'toolCall' || block._tag === 'toolResult');
+};

package/src/components/ConnectorAuthMenu/ConnectorAuthMenu.stories.tsx

@@ -0,0 +1,177 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import React, { useContext, useMemo } from 'react';
+
+import { Capability } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+import { Filter, Obj, Ref } from '@dxos/echo';
+import { useQuery } from '@dxos/echo-react';
+import { AccessToken, Cursor } from '@dxos/link';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { Connection, Connector, type ConnectorEntry, connectorAuthActions } from '@dxos/plugin-connector';
+import { translations as connectorTranslations } from '@dxos/plugin-connector/translations';
+import { Graph } from '@dxos/plugin-graph';
+import { useActionRunner } from '@dxos/plugin-graph/hooks';
+import { corePlugins } from '@dxos/plugin-testing';
+import { useSpaces } from '@dxos/react-client/echo';
+import { Menu, isToolbarAction, useGraphMenuActions } from '@dxos/react-ui-menu';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Expando } from '@dxos/schema';
+
+import { translations } from '#translations';
+
+import { ConnectorAuthMenu } from './ConnectorAuthMenu';
+
+/** `connector-b` already has a Connection below, so it renders as a "reuse" entry; `connector-a` has
+ * none, so it renders as a "Connect" entry — together they exercise both item kinds and the
+ * separator between them. `Default` renders the `ConnectorAuthMenu` component. `Toolbar` feeds the
+ * same `connectorAuthActions` atom into an object toolbar the way studio/ibkr/inbox do. */
+const CredentialSchema = Schema.Struct({ apiKey: Schema.String.annotations({ title: 'API key' }) });
+
+const makeCredentialForm = (connectorId: string) => ({
+  schema: CredentialSchema,
+  onSubmit: () => {
+    const accessToken = AccessToken.make({ source: `${connectorId}.example`, token: 'mock-token' });
+    return Effect.succeed({
+      kind: 'complete' as const,
+      accessToken,
+      connection: Connection.make({ connectorId, accessToken: Ref.make(accessToken) }),
+    });
+  },
+});
+
+const testConnectors: ConnectorEntry[] = [
+  {
+    id: 'connector-a',
+    source: 'connector-a.example',
+    label: 'Connector A',
+    credentialForm: makeCredentialForm('connector-a'),
+  },
+  {
+    id: 'connector-b',
+    source: 'connector-b.example',
+    label: 'Connector B',
+    credentialForm: makeCredentialForm('connector-b'),
+  },
+];
+
+const CONNECTOR_IDS = ['connector-a', 'connector-b'];
+
+const ComponentStory = () => {
+  const [space] = useSpaces();
+  const targets = useQuery(space?.db, Filter.type(Expando.Expando));
+  const target = targets[0];
+
+  if (!space || !target) {
+    return <Loading />;
+  }
+
+  return (
+    <div className='p-4'>
+      <ConnectorAuthMenu connectorIds={CONNECTOR_IDS} db={space.db} existingTarget={Ref.make(target)} />
+    </div>
+  );
+};
+
+const TOOLBAR_NODE_ID = 'story-toolbar-target';
+
+const ToolbarStory = () => {
+  const [space] = useSpaces();
+  const registry = useContext(RegistryContext);
+  const runAction = useActionRunner();
+  const allConnectors = useCapabilities(Connector).flat();
+  const allConnections = useQuery(space?.db, Filter.type(Connection.Connection));
+  const targets = useQuery(space?.db, Filter.type(Expando.Expando));
+  const target = targets[0];
+
+  const graph = useMemo(() => {
+    if (!space?.db || !target) {
+      return undefined;
+    }
+    const actions = connectorAuthActions({
+      connectorIds: CONNECTOR_IDS,
+      db: space.db,
+      spaceId: space.db.spaceId,
+      existingTarget: Ref.make(target),
+      allConnectors,
+      allConnections,
+    });
+    const nextGraph = Graph.make({ registry });
+    nextGraph.pipe(
+      Graph.addNodes([{ id: TOOLBAR_NODE_ID, type: 'story/toolbar-target', data: null, properties: {}, actions }]),
+    );
+    return nextGraph;
+  }, [registry, space, target, allConnectors, allConnections]);
+
+  const menuActions = useGraphMenuActions(graph, TOOLBAR_NODE_ID, { filter: isToolbarAction });
+
+  if (!space || !target) {
+    return <Loading />;
+  }
+
+  return (
+    <div className='p-4 border border-separator rounded-sm'>
+      <Menu.Root {...menuActions} onAction={runAction} attendableId={TOOLBAR_NODE_ID} alwaysActive>
+        <Menu.Toolbar />
+      </Menu.Root>
+    </div>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/components/ConnectorAuthMenu',
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column' }),
+    withPluginManager({
+      setupEvents: [AppActivationEvents.SetupSettings],
+      capabilities: [Capability.contributes(Connector, testConnectors)],
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Connection.Connection, Cursor.Cursor, Expando.Expando],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              yield* initializeIdentity(client);
+              const [space] = client.spaces.get();
+              yield* Effect.promise(() => space.waitUntilReady());
+
+              // `connector-b` already has a connection — offered for reuse.
+              const accessToken = AccessToken.make({ source: 'connector-b.example', token: 'mock-token' });
+              space.db.add(
+                Connection.make({
+                  name: 'Existing Connector B',
+                  connectorId: 'connector-b',
+                  accessToken: Ref.make(accessToken),
+                }),
+              );
+              // Local target the reuse/connect flow would bind a new sync target to.
+              space.db.add(Obj.make(Expando.Expando, { name: 'Target Object' }));
+
+              yield* Effect.promise(() => space.db.flush({ indexes: true }));
+            }),
+        }),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations: [...translations, ...connectorTranslations],
+  },
+} satisfies Meta<React.ComponentType>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { render: ComponentStory };
+
+export const Toolbar: Story = { render: ToolbarStory };

package/src/components/ConnectorAuthMenu/ConnectorAuthMenu.tsx

@@ -0,0 +1,82 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import React, { useContext, useMemo } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type Database, Filter, type Obj, type Ref } from '@dxos/echo';
+import { useQuery } from '@dxos/echo-react';
+import { Connection, Connector, CONNECTOR_AUTH_GROUP_ID, connectorAuthActions } from '@dxos/plugin-connector';
+import { Graph } from '@dxos/plugin-graph';
+import { useActionRunner } from '@dxos/plugin-graph/hooks';
+import { IconButton, useTranslation } from '@dxos/react-ui';
+import { Menu, useGraphMenuActions } from '@dxos/react-ui-menu';
+
+import { meta } from '#meta';
+
+/** Root node the connector-auth group hangs off in the component's local graph. */
+const NODE_ID = 'connector-auth-root';
+
+export type ConnectorAuthMenuProps = {
+  /** Stable ids of the {@link Connector} entries this menu offers: existing connections from any of
+   * them are offered for reuse, and each (with an auth flow) gets a "Connect X" entry. */
+  connectorIds: readonly string[];
+  /** Omitted when there is no active database yet (e.g. no space selected) — nothing is offered. */
+  db: Database.Database | undefined;
+  /** Existing local object to wire up as the new connection's first sync target. */
+  existingTarget?: Ref.Ref<Obj.Unknown>;
+};
+
+/**
+ * Standalone connector-auth menu: a trigger button that opens a dropdown of the same
+ * {@link connectorAuthActions} owning plugins contribute to object toolbars. Existing
+ * {@link Connection}s are offered for reuse (bind inline) alongside a "Connect X" entry per connector
+ * with an auth flow. Renders nothing when there is nothing to offer.
+ */
+export const ConnectorAuthMenu = ({ connectorIds, db, existingTarget }: ConnectorAuthMenuProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const registry = useContext(RegistryContext);
+  const runAction = useActionRunner();
+  const allConnectors = useCapabilities(Connector).flat();
+  const allConnections = useQuery(db, Filter.type(Connection.Connection));
+
+  const graph = useMemo(() => {
+    if (!db) {
+      return undefined;
+    }
+    const actions = connectorAuthActions({
+      connectorIds,
+      db,
+      spaceId: db.spaceId,
+      existingTarget,
+      allConnectors,
+      allConnections,
+    });
+    if (actions.length === 0) {
+      return undefined;
+    }
+    const nextGraph = Graph.make({ registry });
+    nextGraph.pipe(Graph.addNodes([{ id: NODE_ID, type: NODE_ID, data: null, properties: {}, actions }]));
+    return nextGraph;
+  }, [registry, connectorIds, db, existingTarget, allConnectors, allConnections]);
+
+  // Read the group's children (reuse / connect entries) as the menu content.
+  const menuActions = useGraphMenuActions(graph, CONNECTOR_AUTH_GROUP_ID);
+
+  if (!graph) {
+    return null;
+  }
+
+  return (
+    <Menu.Root {...menuActions} onAction={runAction} attendableId={NODE_ID} alwaysActive>
+      <Menu.Trigger asChild>
+        <IconButton variant='ghost' icon='ph--plugs--regular' label={t('connect.label')} />
+      </Menu.Trigger>
+      <Menu.Content />
+    </Menu.Root>
+  );
+};
+
+ConnectorAuthMenu.displayName = 'ConnectorAuthMenu';