@dxos/plugin-registry 0.8.4-main.422d1c7879 → 0.8.4-main.4f23b4e393

package/src/components/PluginDetail/PluginDetail.tsx

@@ -4,12 +4,14 @@
 
 import React from 'react';
 
-import { type Plugin } from '@dxos/app-framework';
-import { Button, Icon, Input, Link, ScrollArea, useTranslation } from '@dxos/react-ui';
+import { type Registry, type Plugin, type PluginManager } from '@dxos/app-framework';
+import { Button, Icon, Input, Link, ScrollArea, Select, useTranslation } from '@dxos/react-ui';
 import { composable, composableProps, getStyles, mx } from '@dxos/ui-theme';
 
 import { meta } from '#meta';
 
+import { PluginFailureBadge } from '../PluginFailureBadge';
+
 export type PluginDetailProps = {
   plugin: Plugin.Plugin;
   enabled?: boolean;
@@ -25,10 +27,54 @@ export type PluginDetailProps = {
    */
   onInstall?: () => void;
   installing?: boolean;
+  /**
+   * 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;
+  /** True when the catalog has a newer version than the one installed. */
+  hasUpdate?: boolean;
+  /** True while an in-flight update is running. Forces the Update button disabled state. */
+  updating?: boolean;
+  /** Available versions of this plugin from the catalog. When non-empty, a version picker is shown. */
+  versions?: readonly Registry.PluginVersion[];
+  /** Currently selected version tag in the picker. */
+  selectedVersionTag?: string;
+  /** Called when the user selects a different version in the picker. */
+  onVersionChange?: (tag: string) => void;
+  /** Called when the user clicks Install on the version picker. */
+  onInstallVersion?: () => void;
+  /** Currently installed version tag (used to mark the matching select option). */
+  installedVersionTag?: 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;
 };
 
 export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
-  ({ plugin, enabled, onEnabledChange, onUninstall, onInstall, installing, ...props }, forwardedRef) => {
+  (
+    {
+      plugin,
+      enabled,
+      onEnabledChange,
+      onUninstall,
+      onInstall,
+      installing,
+      onUpdate,
+      hasUpdate,
+      updating,
+      versions,
+      selectedVersionTag,
+      onVersionChange,
+      onInstallVersion,
+      installedVersionTag,
+      failure,
+      ...props
+    },
+    forwardedRef,
+  ) => {
     const { t } = useTranslation(meta.id);
     const {
       id,
@@ -45,13 +91,16 @@ export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
     return (
       <ScrollArea.Root {...composableProps(props)} orientation='vertical' ref={forwardedRef}>
         <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 className='dx-document grid grid-cols-[min-content_1fr] gap-4 p-4'>
+            <div>
+              <Icon classNames={mx('p-1 rounded-md', styles.fill, styles.foreground)} 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>
+            <div className='flex flex-col gap-6'>
+              <div className='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')}
@@ -63,16 +112,16 @@ export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
                 )}
                 <p className='pt-0.5 text-sm text-description'>{id}</p>
               </div>
-              <div role='none'>
+              <div>
                 <p className='text-description'>{description}</p>
               </div>
               {screenshots && screenshots.length > 0 && (
-                <div role='none' className='flex flex-col gap-2'>
+                <div className='flex flex-col gap-2'>
                   <h2>Preview</h2>
                   <img src={screenshots[0]} alt={name} className='aspect-video object-fit' />
                 </div>
               )}
-              <div role='none' className='flex flex-col gap-2'>
+              <div className='flex flex-col gap-2'>
                 <h2>Resources</h2>
                 <div className='flex gap-2'>
                   {homePage && (
@@ -90,9 +139,50 @@ export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
                   )}
                 </div>
               </div>
-              {onUninstall && (
-                <div role='none'>
-                  <Button onClick={onUninstall}>{t('uninstall.label')}</Button>
+              {versions && versions.length > 0 && (
+                <div className='flex flex-col gap-2'>
+                  <h2>{t('versions.label')}</h2>
+                  <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>
+                </div>
+              )}
+              {(onUninstall || (hasUpdate && onUpdate) || updating) && (
+                <div className='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>

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';

package/src/components/PluginList/PluginItem.tsx

@@ -4,7 +4,7 @@
 
 import React, { type MouseEvent, useCallback, useMemo } from 'react';
 
-import { type Plugin } from '@dxos/app-framework';
+import { type Plugin, type PluginManager } from '@dxos/app-framework';
 import {
   Button,
   type ChromaticPalette,
@@ -23,6 +23,8 @@ import { getStyles } from '@dxos/ui-theme';
 import { meta } from '#meta';
 import { type RegistryTagType } from '#types';
 
+import { PluginFailureBadge } from '../PluginFailureBadge';
+
 export type PluginItemProps = {
   plugin: Plugin.Plugin;
   /** Ids of plugins currently installed (loaded into the manager). */
@@ -31,7 +33,7 @@ export type PluginItemProps = {
   installing?: readonly string[];
   enabled?: readonly string[];
   /**
-   * Derived tags (e.g. `community`, `local`) to display alongside the plugin's own meta.tags.
+   * Derived tags (e.g. `registry`, `local`) to display alongside the plugin's own meta.tags.
    * Not persisted to plugin meta; computed per-render by the container.
    */
   extraTags?: readonly string[];
@@ -42,8 +44,22 @@ export type PluginItemProps = {
    * is rendered in place of the enable switch.
    */
   onInstall?: (id: string) => void;
+  /**
+   * When true and plugin is installed, shows an Update button instead of the enable switch.
+   */
+  hasUpdate?: boolean;
+  /** Called when the user clicks the Update button. */
+  onUpdate?: (id: string) => void;
+  /** Ids of plugins whose update is currently in flight. */
+  updating?: readonly string[];
   hasSettings?: (id: string) => boolean;
   onSettings?: (id: string) => void;
+  /**
+   * Failure record for this plugin, if any. When present a warning badge is
+   * rendered next to the plugin name; clicking it opens a popover with the
+   * phase, reason, and error message.
+   */
+  failure?: PluginManager.PluginFailure;
 };
 
 export const PluginItem = ({
@@ -55,8 +71,12 @@ export const PluginItem = ({
   onClick,
   onChange,
   onInstall,
+  hasUpdate,
+  onUpdate,
+  updating,
   hasSettings: hasSettingsProp,
   onSettings,
+  failure,
 }: PluginItemProps) => {
   const { t } = useTranslation(meta.id);
   const { id, name, description, tags, icon = 'ph--circle--regular', iconHue = 'neutral' } = plugin.meta;
@@ -73,7 +93,9 @@ export const PluginItem = ({
   const isEnabled = enabled.includes(id);
   const isInstalled = installed ? installed.includes(id) : true;
   const isInstalling = installing?.includes(id) ?? false;
+  const isUpdating = updating?.includes(id) ?? false;
   const showInstallButton = !!onInstall && !isInstalled;
+  const showUpdateButton = !!onUpdate && isInstalled && !!hasUpdate;
   const inputId = `${id}-input`;
   const labelId = `${id}-label`;
   const descriptionId = `${id}-description`;
@@ -95,6 +117,14 @@ export const PluginItem = ({
     [id, onInstall],
   );
 
+  const handleUpdate = useCallback(
+    (event: MouseEvent) => {
+      event.stopPropagation();
+      onUpdate?.(id);
+    },
+    [id, onUpdate],
+  );
+
   const hasSettings = hasSettingsProp?.(id) ?? false;
   const handleSettings = useCallback(() => onSettings?.(id), [id, onSettings]);
   const styles = getStyles(iconHue);
@@ -111,7 +141,7 @@ export const PluginItem = ({
     >
       <div className={mx(gridRows, 'justify-center rounded-l-md', styles.surface)}>
         <Icon
-          classNames={mx('row-start-2 cursor-pointer', styles.surfaceText)}
+          classNames={mx('row-start-2 cursor-pointer', styles.foreground)}
           icon={icon}
           size={14}
           onClick={handleClick}
@@ -119,8 +149,9 @@ export const PluginItem = ({
       </div>
 
       <div className={mx(gridRows)}>
-        <div className='flex items-center overflow-hidden cursor-pointer' onClick={handleClick}>
+        <div className='flex items-center gap-2 overflow-hidden cursor-pointer' onClick={handleClick}>
           <span className='text-lg truncate'>{name ?? id}</span>
+          {failure && <PluginFailureBadge failure={failure} />}
         </div>
 
         <div>
@@ -140,7 +171,7 @@ export const PluginItem = ({
             aria-describedby={descriptionId}
             classNames='cursor-pointer'
             icon='ph--gear--regular'
-            label={t('settings.label')}
+            label={t('plugin-settings.label')}
             iconOnly
             size={4}
             onClick={handleSettings}
@@ -153,7 +184,15 @@ export const PluginItem = ({
 
           <div className='grow' />
           <div className='pe-1'>
-            {showInstallButton ? (
+            {isUpdating ? (
+              <Button aria-describedby={descriptionId} density='fine' variant='primary' disabled>
+                {t('updating.label')}
+              </Button>
+            ) : showUpdateButton ? (
+              <Button aria-describedby={descriptionId} density='fine' variant='primary' onClick={handleUpdate}>
+                {t('update.label')}
+              </Button>
+            ) : showInstallButton ? (
               <Button
                 aria-describedby={descriptionId}
                 density='fine'
@@ -182,6 +221,6 @@ const tagColors: Record<RegistryTagType, ChromaticPalette | NeutralPalette> = {
   popular: 'green',
   featured: 'pink',
   experimental: 'amber',
-  community: 'indigo',
+  registry: 'indigo',
   local: 'neutral',
 };

package/src/components/PluginList/PluginList.stories.tsx

@@ -11,9 +11,9 @@ import { ScrollArea } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { getHashHue } from '@dxos/ui-theme';
 
+import { translations } from '#translations';
 import { RegistryTagType } from '#types';
 
-import { translations } from '../../translations';
 import { PluginList } from './PluginList';
 
 random.seed(1);

package/src/components/PluginList/PluginList.tsx

@@ -4,25 +4,48 @@
 
 import React from 'react';
 
-import { type Plugin } from '@dxos/app-framework';
+import { type Plugin, type PluginManager } from '@dxos/app-framework';
 import { List } from '@dxos/react-ui';
 
 import { PluginItem, type PluginItemProps } from './PluginItem';
 
-export type PluginListProps = Omit<PluginItemProps, 'plugin' | 'extraTags'> & {
+export type PluginListProps = Omit<PluginItemProps, 'plugin' | 'extraTags' | 'hasUpdate' | 'failure'> & {
   plugins?: readonly Plugin.Plugin[];
   /**
-   * Map from plugin id → extra tags to display (e.g. `community`, `local`).
+   * Map from plugin id → extra tags to display (e.g. `registry`, `local`).
    * Computed by the container; not persisted to plugin meta.
    */
   extraTagsById?: Record<string, readonly string[]>;
+  /**
+   * Set of plugin ids for which a newer version is available in the catalog.
+   * Causes each matching item to render an Update button instead of the enable switch.
+   */
+  updateAvailableIds?: ReadonlySet<string>;
+  /**
+   * Map from plugin id → most recent failure record. Used to render a warning
+   * badge next to the plugin name. Sourced from `PluginManager.failed`.
+   */
+  failuresById?: Record<string, PluginManager.PluginFailure>;
 };
 
-export const PluginList = ({ plugins = [], extraTagsById, ...props }: PluginListProps) => {
+export const PluginList = ({
+  plugins = [],
+  extraTagsById,
+  updateAvailableIds,
+  failuresById,
+  ...props
+}: PluginListProps) => {
   return (
     <List classNames='grid grid-cols-[repeat(auto-fill,minmax(18rem,1fr))] auto-rows-[max-content] gap-4 p-4'>
       {plugins.map((plugin) => (
-        <PluginItem key={plugin.meta.id} plugin={plugin} extraTags={extraTagsById?.[plugin.meta.id]} {...props} />
+        <PluginItem
+          key={plugin.meta.id}
+          plugin={plugin}
+          extraTags={extraTagsById?.[plugin.meta.id]}
+          hasUpdate={updateAvailableIds?.has(plugin.meta.id)}
+          failure={failuresById?.[plugin.meta.id]}
+          {...props}
+        />
       ))}
     </List>
   );

package/src/components/RegistrySettings/RegistrySettings.tsx

@@ -0,0 +1,120 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useState } from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { log } from '@dxos/log';
+import { Button, Input, Message, useTranslation } from '@dxos/react-ui';
+import { Settings as SettingsForm } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+
+import { type RegistrySettings as RegistrySettingsType } from '../../types';
+
+export type RegistrySettingsProps = AppSurface.SettingsArticleProps<
+  RegistrySettingsType,
+  {
+    activeDevPluginIds: readonly string[];
+    onEnableDev: (url: string) => Promise<void>;
+    onDisableDev: (id: string) => Promise<void>;
+  }
+>;
+
+/**
+ * Settings panel for `@dxos/plugin-registry`. The dev-plugin section lets a
+ * plugin author point Composer at a local Vite dev server (defaults to
+ * `localhost:3967`) and toggle the dev plugin on/off persistently — boot will
+ * re-attach it on the next reload, surviving HMR-triggered reloads. If the
+ * dev server is offline at boot, the toggle stays on and a warning is logged
+ * (the manager's `failed` atom also surfaces a badge on the plugin list).
+ */
+export const RegistrySettings = ({
+  settings,
+  onSettingsChange,
+  activeDevPluginIds,
+  onEnableDev,
+  onDisableDev,
+}: RegistrySettingsProps) => {
+  const { t } = useTranslation(meta.id);
+  const [busy, setBusy] = useState(false);
+  const enabled = !!settings.devPluginEnabled;
+  const url = settings.devPluginUrl ?? '';
+  const trimmedUrl = url.trim();
+  const loadedDevId = activeDevPluginIds[0];
+
+  const handleToggle = useCallback(async () => {
+    if (busy || !onSettingsChange) {
+      return;
+    }
+    setBusy(true);
+    try {
+      if (enabled && loadedDevId) {
+        await onDisableDev(loadedDevId);
+        onSettingsChange((current) => ({ ...current, devPluginEnabled: false }));
+      } else if (enabled) {
+        // Toggle is on but no dev plugin is currently loaded (boot-time load
+        // failed or hasn't finished). Treat the click as "turn it off."
+        onSettingsChange((current) => ({ ...current, devPluginEnabled: false }));
+      } else {
+        if (!trimmedUrl) {
+          return;
+        }
+        // Optimistically persist intent so the next reload retries even if
+        // the page closes mid-load.
+        onSettingsChange((current) => ({ ...current, devPluginEnabled: true }));
+        try {
+          await onEnableDev(trimmedUrl);
+        } catch (error) {
+          // Per product direction: leave the intent on, log the failure. The
+          // user explicitly turns it off if they're done iterating.
+          log.warn('dev plugin enable failed', { url: trimmedUrl, error });
+        }
+      }
+    } finally {
+      setBusy(false);
+    }
+  }, [busy, enabled, loadedDevId, onSettingsChange, onDisableDev, onEnableDev, trimmedUrl]);
+
+  // Button label tracks the persisted intent, not the current load state, so
+  // a transient "intent on but not loaded" combination still reads as
+  // "Disable Dev Plugin" — clicking it turns the intent off cleanly.
+  const buttonLabel = busy
+    ? t('dev-plugin.busy.label')
+    : enabled
+      ? t('dev-plugin.disable.label')
+      : t('dev-plugin.enable.label');
+
+  return (
+    <SettingsForm.Viewport>
+      <SettingsForm.Section title={t('dev-plugin.section.title')}>
+        <Message.Root valence='neutral'>
+          <Message.Content>{t('dev-plugin.description')}</Message.Content>
+        </Message.Root>
+        <SettingsForm.Item title={t('dev-plugin.url.label')} description={t('dev-plugin.url.description')}>
+          <Input.TextInput
+            classNames='ms-2'
+            disabled={!onSettingsChange || enabled || busy}
+            value={url}
+            onChange={(event) => onSettingsChange?.((current) => ({ ...current, devPluginUrl: event.target.value }))}
+          />
+        </SettingsForm.Item>
+        <SettingsForm.Item title={t('dev-plugin.toggle.label')} description={t('dev-plugin.toggle.description')}>
+          <Button
+            variant={enabled ? undefined : 'primary'}
+            disabled={busy || (!enabled && !trimmedUrl)}
+            onClick={() => void handleToggle()}
+          >
+            {buttonLabel}
+          </Button>
+        </SettingsForm.Item>
+        {enabled && !loadedDevId && !busy && (
+          <Message.Root valence='warning'>
+            <Message.Content>{t('dev-plugin.not-loaded.message')}</Message.Content>
+          </Message.Root>
+        )}
+      </SettingsForm.Section>
+    </SettingsForm.Viewport>
+  );
+};

package/src/components/RegistrySettings/index.ts

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

package/src/components/index.ts

@@ -3,4 +3,6 @@
 //
 
 export * from './PluginDetail';
+export * from './PluginFailureBadge';
 export * from './PluginList';
+export * from './RegistrySettings';