@dxos/plugin-registry 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/capabilities/settings.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability, PLUGIN_DEV_SERVER_PORT } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { createKvsStore } from '@dxos/effect';
+
+import { meta } from '#meta';
+
+import { RegistryCapabilities, RegistrySettingsSchema } from '../types';
+
+const DEFAULT_DEV_PLUGIN_URL = `http://localhost:${PLUGIN_DEV_SERVER_PORT}/manifest.json`;
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.id,
+      schema: RegistrySettingsSchema,
+      defaultValue: () => ({ devPluginUrl: DEFAULT_DEV_PLUGIN_URL }),
+    });
+
+    return [
+      Capability.contributes(RegistryCapabilities.Settings, settingsAtom),
+      Capability.contributes(AppCapabilities.Settings, {
+        prefix: meta.id,
+        schema: RegistrySettingsSchema,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/components/DisableDependentsAlert/DisableDependentsAlert.tsx

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { AlertDialog, Button, useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+export type DisableDependentsAlertProps = {
+  /** Id of the plugin the user requested to disable. */
+  pluginId: string;
+  /** Ids of the currently-enabled dependents that would also be disabled. */
+  dependents: readonly string[];
+  /**
+   * Resolves a plugin id to its display name. The component delegates this so
+   * the parent can choose how to source names (typically the registered
+   * `Plugin.Meta.name`). Falls back to the id when omitted.
+   */
+  onResolvePluginName?: (pluginId: string) => string;
+  onConfirm: () => void;
+};
+
+/**
+ * Confirmation prompt shown when a user toggles off a plugin that has
+ * currently-enabled dependents. Rendered inside the layout's dialog surface
+ * (via `LayoutOperation.UpdateDialog` with `type: 'alert'`), which provides
+ * the `AlertDialog.Root` / `Overlay` wrappers — this component renders only
+ * the content. `onConfirm` runs the cascade disable and closes the dialog;
+ * cancel is handled by the layout's open-change wiring.
+ */
+export const DisableDependentsAlert = ({
+  pluginId,
+  dependents,
+  onResolvePluginName,
+  onConfirm,
+}: DisableDependentsAlertProps) => {
+  const { t } = useTranslation(meta.id);
+  const resolveName = onResolvePluginName ?? ((id: string) => id);
+  return (
+    <AlertDialog.Content>
+      <AlertDialog.Body>
+        <AlertDialog.Title>{t('disable-dependents-dialog.title')}</AlertDialog.Title>
+        <AlertDialog.Description>
+          {t('disable-dependents-dialog.description', { plugin: resolveName(pluginId) })}
+        </AlertDialog.Description>
+        <ul className='mt-2 list-disc pl-6 text-sm text-description'>
+          {dependents.map((dependentId) => (
+            <li key={dependentId} title={dependentId}>
+              {resolveName(dependentId)}
+            </li>
+          ))}
+        </ul>
+      </AlertDialog.Body>
+      <AlertDialog.ActionBar>
+        <div className='grow' />
+        <AlertDialog.Cancel asChild>
+          <Button>{t('cancel.label')}</Button>
+        </AlertDialog.Cancel>
+        <AlertDialog.Action asChild>
+          <Button variant='primary' onClick={onConfirm}>
+            {t('disable-dependents-dialog.confirm.label')}
+          </Button>
+        </AlertDialog.Action>
+      </AlertDialog.ActionBar>
+    </AlertDialog.Content>
+  );
+};

package/src/components/DisableDependentsAlert/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './DisableDependentsAlert';

package/src/components/PluginDetail/PluginDetail.stories.tsx

@@ -5,10 +5,10 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 
 import { Plugin } from '@dxos/app-framework';
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
-import { translations } from '../../translations';
+import { translations } from '#translations';
 
 import { PluginDetail } from './PluginDetail';
 
@@ -29,9 +29,10 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     plugin: Plugin.define({
-      id: 'example.com/plugin/test-plugin',
+      id: 'com.example.plugin.test',
       name: 'Test Plugin',
-      description: faker.lorem.paragraphs(2),
+      author: 'DXOS',
+      description: random.lorem.paragraphs(2),
       icon: 'ph--bug--regular',
       iconHue: 'sky',
       homePage: 'https://example.com',

package/src/components/PluginDetail/PluginDetail.tsx

@@ -2,80 +2,338 @@
 // Copyright 2025 DXOS.org
 //
 
-import React from 'react';
+import React, { type PropsWithChildren } from 'react';
 
-import { type Plugin } from '@dxos/app-framework';
-import { Icon, Input, Link, useTranslation } from '@dxos/react-ui';
-import { ScrollArea } from '@dxos/react-ui';
-import { getStyles, mx } from '@dxos/ui-theme';
+import { type Plugin, type PluginManager, type Registry } from '@dxos/app-framework';
+import {
+  Button,
+  Carousel,
+  Icon,
+  Input,
+  Link,
+  ScrollArea,
+  Select,
+  Tag,
+  ThemedClassName,
+  useTranslation,
+} from '@dxos/react-ui';
+import { composable, composableProps, getStyles, mx } from '@dxos/ui-theme';
 
-import { meta } from '../../meta';
+import { meta } from '#meta';
+
+import { PluginFailureBadge } from '../PluginFailureBadge';
 
 export type PluginDetailProps = {
   plugin: Plugin.Plugin;
   enabled?: boolean;
+  /** True while an in-flight install is running. Disables the install button. */
+  installing?: boolean;
+  /** True while an in-flight update is running. Disables the update button. */
+  updating?: boolean;
+  /** True when the catalog has a newer version than the one installed. */
+  hasUpdate?: boolean;
+  /** Currently installed version tag (used to mark the matching select option). */
+  installedVersionTag?: string;
+  /** Currently selected version tag in the picker. */
+  selectedVersionTag?: string;
+  /** Available versions of this plugin from the catalog. When non-empty, a version picker is shown. */
+  versions?: readonly Registry.PluginVersion[];
+  /**
+   * Ids of plugins this plugin declares as dependencies (direct only). Rendered
+   * under a "Requires" heading so the user can see what enabling this plugin
+   * will auto-enable.
+   */
+  dependencies?: readonly string[];
+  /**
+   * Ids of plugins that declare this plugin as a dependency (direct only).
+   * Rendered under a "Required by" heading so the user understands the
+   * downstream impact of disabling this plugin.
+   */
+  dependents?: readonly string[];
+  /**
+   * Failure record for this plugin, if any. When present a warning badge is
+   * rendered next to the plugin name in the header.
+   */
+  failure?: PluginManager.PluginFailure;
   onEnabledChange?: (enabled: boolean) => void;
+  /**
+   * When provided, the plugin is not installed and an Install button is shown
+   * in place of the enable Switch.
+   */
+  onInstall?: () => void;
+  /**
+   * Called when the user clicks Install on the version picker.
+   */
+  onInstallVersion?: () => void;
+  /**
+   * Called when the user activates a dependency / dependent chip. When
+   * provided, chips are rendered as buttons that fire this handler with the
+   * target plugin id; when omitted, chips are non-interactive labels.
+   */
+  onNavigateToPlugin?: (pluginId: string) => void;
+  /**
+   * Called when the user activates the in-app spec viewer link. When provided
+   * (i.e. the plugin bundles its MDL via `Plugin.Meta.specContent`), a second
+   * "View specification" link is rendered next to the external spec link.
+   */
+  onOpenSpec?: () => void;
+  /**
+   * Resolves a plugin id to its display name for dependency / dependent
+   * chip labels. The component delegates the lookup to the parent so each
+   * surface can decide how to source names (e.g. `Plugin.Meta.name` from the
+   * registered plugin set). When omitted, chips render the raw id.
+   */
+  onResolvePluginName?: (pluginId: string) => string;
+  /**
+   * When provided, an Uninstall button is rendered. Leave undefined for core
+   * or non-removable plugins.
+   */
+  onUninstall?: () => void;
+  /**
+   * When provided and the plugin is installed with a newer catalog version available,
+   * an Update button is shown in place of the enable Switch.
+   */
+  onUpdate?: () => void;
+  /**
+   * Called when the user selects a different version in the picker.
+   */
+  onVersionChange?: (tag: string) => void;
 };
 
-export const PluginDetail = ({ plugin, enabled, onEnabledChange }: PluginDetailProps) => {
-  const { t } = useTranslation(meta.id);
-  const {
-    id,
-    name,
-    description,
-    homePage,
-    source,
-    screenshots,
-    icon = 'ph--circle--regular',
-    iconHue = 'neutral',
-  } = plugin.meta;
-  const styles = getStyles(iconHue);
-
-  return (
-    <ScrollArea.Root orientation='vertical'>
-      <ScrollArea.Viewport>
-        <div role='none' className='dx-document grid grid-cols-[min-content_1fr] gap-4 p-4'>
-          <div role='none'>
-            <Icon classNames={mx('p-1 rounded-md', styles.fill, styles.surfaceText)} icon={icon} size={14} />
-          </div>
-          <div role='none' className='flex flex-col gap-6'>
-            <div role='none' className='grid grid-cols-[1fr_min-content] gap-x-3 w-full pt-1'>
-              <h2 className='text-xl'>{name}</h2>
-              <Input.Root>
-                <Input.Switch classNames='self-center' checked={enabled} onCheckedChange={onEnabledChange} />
-              </Input.Root>
-              <p className='pt-0.5 text-sm text-description'>{id}</p>
-            </div>
-            <div role='none'>
-              <p className='text-description'>{description}</p>
+export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
+  (
+    {
+      plugin,
+      enabled,
+      installing,
+      updating,
+      hasUpdate,
+      installedVersionTag,
+      selectedVersionTag,
+      versions,
+      dependencies,
+      dependents,
+      failure,
+      onEnabledChange,
+      onInstall,
+      onInstallVersion,
+      onNavigateToPlugin,
+      onOpenSpec,
+      onResolvePluginName,
+      onUninstall,
+      onUpdate,
+      onVersionChange,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(meta.id);
+    const {
+      id,
+      name,
+      author,
+      description,
+      homePage,
+      source,
+      screenshots,
+      icon = 'ph--circle--regular',
+      iconHue = 'neutral',
+    } = plugin.meta;
+    const styles = getStyles(iconHue);
+
+    return (
+      <ScrollArea.Root {...composableProps(props)} orientation='vertical' ref={forwardedRef}>
+        <ScrollArea.Viewport>
+          {/*
+           * 3-column grid: [icon/prev | content/viewport | next].
+           * Most sections occupy `col-start-2 col-span-2` so they stretch from
+           * the centre column out to the trailing edge. The carousel uses
+           * `display: contents` to flatten its children into this grid so
+           * `Carousel.Previous` lands in col 1, `Carousel.Viewport` aligns
+           * with the rest of the content in col 2, and `Carousel.Next` sits
+           * in col 3.
+           */}
+          <div className='dx-document grid grid-cols-[4rem_minmax(0,1fr)_4rem] gap-x-4 p-4 items-start'>
+            <Icon classNames={mx('row-start-1 p-1 rounded-md', styles.fill, styles.foreground)} icon={icon} size={14} />
+
+            <div className='row-start-1 col-start-2 col-span-2 grid grid-cols-[1fr_min-content] gap-x-3 w-full pt-1'>
+              <div className='flex items-center gap-2'>
+                <h2 className='text-xl'>{name}</h2>
+                {failure && <PluginFailureBadge failure={failure} size={5} />}
+              </div>
+              {onInstall ? (
+                <Button density='fine' variant='primary' disabled={installing} onClick={onInstall}>
+                  {installing ? t('installing.label') : t('install.label')}
+                </Button>
+              ) : (
+                <Input.Root>
+                  <Input.Switch classNames='self-center' checked={enabled} onCheckedChange={onEnabledChange} />
+                </Input.Root>
+              )}
+              <div className='flex items-center gap-1 pt-0.5 text-sm text-description'>
+                {id}
+                {author && <span className='dx-tag dx-tag--info'>{author}</span>}
+              </div>
             </div>
+
+            <Section.Root>
+              <Section.Heading title='Description' />
+              <Section.Body>
+                <p className='text-description'>{description}</p>
+              </Section.Body>
+            </Section.Root>
+
             {screenshots && screenshots.length > 0 && (
-              <div role='none' className='flex flex-col gap-2'>
-                <h2>Preview</h2>
-                <img src={screenshots[0]} alt={name} className='aspect-video object-fit' />
-              </div>
+              <Section.Root>
+                <Section.Heading title='Preview' />
+                <Section.Body>
+                  <Carousel.Root classNames='contents' count={screenshots.length}>
+                    <Carousel.Viewport>
+                      {screenshots.map((src, index) => (
+                        <Carousel.Slide key={src} index={index} src={src} alt={name} />
+                      ))}
+                    </Carousel.Viewport>
+                    <Carousel.Indicators />
+                  </Carousel.Root>
+                </Section.Body>
+              </Section.Root>
+            )}
+
+            <Section.Root>
+              <Section.Heading title={t('resources.label')} />
+              <Section.Body>
+                <div className='flex gap-3 items-center'>
+                  {homePage && (
+                    <Link href={homePage} classNames='text-sm text-description'>
+                      {t('home-page.label')}
+                      <Icon icon='ph--arrow-square-out--regular' size={3} classNames='ml-1 dx-icon-inline' />
+                    </Link>
+                  )}
+
+                  {source && (
+                    <Link href={source} classNames='text-sm text-description'>
+                      {t('source.label')}
+                      <Icon icon='ph--arrow-square-out--regular' size={3} classNames='ml-1 dx-icon-inline' />
+                    </Link>
+                  )}
+
+                  {onOpenSpec && <Chip id={id} name={t('open-spec.label')} onClick={onOpenSpec} />}
+                </div>
+              </Section.Body>
+            </Section.Root>
+
+            {dependencies && dependencies.length > 0 && (
+              <Section.Root>
+                <Section.Heading title={t('dependencies.label')} />
+                <Section.Body>
+                  <div className='flex flex-wrap gap-1'>
+                    {dependencies.map((depId) => (
+                      <Chip
+                        key={depId}
+                        id={depId}
+                        name={onResolvePluginName?.(depId) ?? depId}
+                        onClick={onNavigateToPlugin}
+                      />
+                    ))}
+                  </div>
+                </Section.Body>
+              </Section.Root>
+            )}
+
+            {dependents && dependents.length > 0 && (
+              <Section.Root>
+                <Section.Heading title={t('dependents.label')} />
+                <Section.Body>
+                  <div className='flex flex-wrap gap-1'>
+                    {dependents.map((dependentId) => (
+                      <Chip
+                        key={dependentId}
+                        id={dependentId}
+                        name={onResolvePluginName?.(dependentId) ?? dependentId}
+                        onClick={onNavigateToPlugin}
+                      />
+                    ))}
+                  </div>
+                </Section.Body>
+              </Section.Root>
             )}
-            <div role='none' className='flex flex-col gap-2'>
-              <h2>Resources</h2>
-              <div className='flex gap-2'>
-                {homePage && (
-                  <Link href={homePage} target='_blank' rel='noreferrer' classNames='text-sm text-description'>
-                    {t('home page label')}
-                    <Icon icon='ph--arrow-square-out--bold' size={3} classNames='inline-block leading-none mx-1' />
-                  </Link>
-                )}
-
-                {source && (
-                  <Link href={source} target='_blank' rel='noreferrer' classNames='text-sm text-description'>
-                    {t('source label')}
-                    <Icon icon='ph--arrow-square-out--bold' size={3} classNames='inline-block leading-none mx-1' />
-                  </Link>
-                )}
+
+            {versions && versions.length > 0 && (
+              <Section.Root>
+                <Section.Heading title={t('versions.label')} />
+                <Section.Body>
+                  <div className='flex gap-2 items-center'>
+                    <Select.Root value={selectedVersionTag} onValueChange={onVersionChange}>
+                      <Select.TriggerButton classNames='min-w-32' />
+                      <Select.Portal>
+                        <Select.Content>
+                          <Select.Viewport>
+                            {versions.map((versionEntry) => (
+                              <Select.Option key={versionEntry.tag} value={versionEntry.tag}>
+                                {versionEntry.tag}
+                                {installedVersionTag === versionEntry.tag ? ` (${t('installed.label')})` : ''}
+                              </Select.Option>
+                            ))}
+                          </Select.Viewport>
+                        </Select.Content>
+                      </Select.Portal>
+                    </Select.Root>
+                    {onInstallVersion && (
+                      <Button
+                        density='fine'
+                        variant='primary'
+                        disabled={installing || selectedVersionTag === installedVersionTag}
+                        onClick={onInstallVersion}
+                      >
+                        {installing ? t('installing.label') : t('install-version.label')}
+                      </Button>
+                    )}
+                  </div>
+                </Section.Body>
+              </Section.Root>
+            )}
+
+            {(onUninstall || (hasUpdate && onUpdate) || updating) && (
+              <div className='col-start-2 col-span-2 flex gap-2'>
+                {updating ? (
+                  <Button variant='primary' disabled>
+                    {t('updating.label')}
+                  </Button>
+                ) : hasUpdate && onUpdate ? (
+                  <Button variant='primary' onClick={onUpdate}>
+                    {t('update.label')}
+                  </Button>
+                ) : null}
+                {onUninstall && <Button onClick={onUninstall}>{t('uninstall.label')}</Button>}
               </div>
-            </div>
+            )}
           </div>
-        </div>
-      </ScrollArea.Viewport>
-    </ScrollArea.Root>
-  );
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+    );
+  },
+);
+
+PluginDetail.displayName = 'PluginDetail';
+
+const SectionRoot = ({ children }: PropsWithChildren<{}>) => <>{children}</>;
+
+const SectionHeading = ({ title }: { title: string }) => (
+  <h2 className='col-start-2 col-span-2 pt-6 pb-2 uppercase text-sm font-medium text-subdued'>{title}</h2>
+);
+
+const SectionBody = ({ classNames, children }: ThemedClassName<PropsWithChildren>) => (
+  <div className={mx('col-start-2 flex flex-col gap-2', classNames)}>{children}</div>
+);
+
+const Section = {
+  Root: SectionRoot,
+  Heading: SectionHeading,
+  Body: SectionBody,
 };
+
+const Chip = ({ id, name, onClick }: { id: string; name: string; onClick?: (pluginId: string) => void }) => (
+  <Tag title={id} onClick={onClick ? () => onClick(id) : undefined} classNames='dx-hover'>
+    {name}
+  </Tag>
+);

package/src/components/PluginFailureBadge/PluginFailureBadge.tsx

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { type PluginManager } from '@dxos/app-framework';
+import { IconButton, Popover, useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+// Mirrors react-ui `Icon`'s `size` prop literal subset; kept inline so we don't
+// have to add `@dxos/ui-types` as a dep just for one type alias.
+type IconSize = 4 | 5 | 6 | 8;
+
+export type PluginFailureBadgeProps = {
+  failure: PluginManager.PluginFailure;
+  /** Optional override for the trigger icon's tailwind classes. */
+  iconClassNames?: string;
+  /** Visual size of the warning icon (passed through to react-ui `<Icon />`). */
+  size?: IconSize;
+};
+
+/**
+ * Compact warning glyph rendered next to a plugin's name when it has failed
+ * to load or activate. Clicking the icon opens a popover that names the phase
+ * (load / activation), the reason (timeout / error), and the underlying error
+ * message — enough for an operator to tell "remote host is offline" apart
+ * from "the plugin crashed".
+ */
+export const PluginFailureBadge = ({ failure, iconClassNames, size = 4 }: PluginFailureBadgeProps) => {
+  const { t } = useTranslation(meta.id);
+
+  const phaseLabel = failure.phase === 'load' ? t('failure-phase-load.label') : t('failure-phase-activation.label');
+  const reasonLabel =
+    failure.reason === 'timeout' ? t('failure-reason-timeout.label') : t('failure-reason-error.label');
+
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <IconButton
+          variant='ghost'
+          iconOnly
+          noTooltip
+          icon='ph--warning--bold'
+          size={size}
+          iconClassNames={iconClassNames}
+          label={t('failure-badge.label')}
+          data-testid={`pluginFailureBadge.${failure.id}`}
+          // Don't bubble up to row click handlers (e.g. the card's `onClick`
+          // that opens the details pane). The popover is the action here.
+          onClick={(event) => event.stopPropagation()}
+        />
+      </Popover.Trigger>
+      <Popover.Content>
+        <Popover.Viewport>
+          <div className='px-3 py-2 min-w-[18rem] max-w-[28rem] flex flex-col gap-1'>
+            <p className='font-medium text-sm'>
+              {t('failure-title.label', { phase: phaseLabel, reason: reasonLabel })}
+            </p>
+            <p className='text-description text-sm break-words'>{failure.error.message}</p>
+          </div>
+        </Popover.Viewport>
+        <Popover.Arrow />
+      </Popover.Content>
+    </Popover.Root>
+  );
+};

package/src/components/PluginFailureBadge/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './PluginFailureBadge';