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

package/src/components/PluginList/PluginItem.tsx

@@ -2,37 +2,100 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type MouseEvent, useCallback } from 'react';
+import React, { type MouseEvent, useCallback, useMemo } from 'react';
 
-import { type Plugin } from '@dxos/app-framework';
-import { type ChromaticPalette, Icon, IconButton, Input, Link, ListItem, Tag, useTranslation } from '@dxos/react-ui';
+import { type Plugin, type PluginManager } from '@dxos/app-framework';
+import {
+  Button,
+  type ChromaticPalette,
+  Icon,
+  IconButton,
+  Input,
+  Link,
+  ListItem,
+  type NeutralPalette,
+  Tag,
+  useTranslation,
+} from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
 import { getStyles } from '@dxos/ui-theme';
 
-import { meta } from '../../meta';
-import { type RegistryTagType } from '../../types';
+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). */
   installed?: readonly string[];
+  /** Ids of plugins whose install is in flight. */
+  installing?: readonly string[];
   enabled?: readonly string[];
+  /**
+   * 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[];
   onClick?: (id: string) => void;
   onChange?: (id: string, enabled: boolean) => void;
+  /**
+   * Install handler. When provided and the plugin is not installed, an Install button
+   * 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 = ({
   plugin,
+  installed,
+  installing,
   enabled = [],
+  extraTags,
   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;
+  const displayTags = useMemo(() => {
+    if (!extraTags || extraTags.length === 0) {
+      return tags ?? [];
+    }
+    const set = new Set<string>(tags ?? []);
+    for (const tag of extraTags) {
+      set.add(tag);
+    }
+    return Array.from(set);
+  }, [tags, extraTags]);
   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`;
@@ -46,6 +109,22 @@ export const PluginItem = ({
     [id, isEnabled, onChange],
   );
 
+  const handleInstall = useCallback(
+    (event: MouseEvent) => {
+      event.stopPropagation();
+      onInstall?.(id);
+    },
+    [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);
@@ -58,11 +137,11 @@ export const PluginItem = ({
       labelId={labelId}
       data-testid={`pluginList.${id}`}
       aria-describedby={descriptionId}
-      classNames={mx(gridCols, 'h-[12rem] w-full gap-3 pe-2 bg-modal-surface rounded-md overflow-hidden')}
+      classNames={mx(gridCols, 'h-[14rem] w-full gap-3 pe-2 bg-modal-surface rounded-md overflow-hidden')}
     >
       <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}
@@ -70,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>
@@ -79,7 +159,7 @@ export const PluginItem = ({
         </div>
 
         <div className='flex -ms-0.5 overflow-x-auto scrollbar-none'>
-          {tags?.map((tag) => (
+          {displayTags.map((tag) => (
             <Tag key={tag} palette={tagColors[tag as RegistryTagType]} classNames='text-xs uppercase font-thin'>
               {tag}
             </Tag>
@@ -91,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}
@@ -99,14 +179,34 @@ export const PluginItem = ({
           />
 
           <Link aria-describedby={descriptionId} classNames='text-description cursor-pointer' onClick={handleClick}>
-            {t('details label')}
+            {t('details.label')}
           </Link>
 
           <div className='grow' />
           <div className='pe-1'>
-            <Input.Root id={inputId}>
-              <Input.Switch classNames='self-center' checked={isEnabled} onClick={handleChange} />
-            </Input.Root>
+            {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'
+                variant='primary'
+                disabled={isInstalling}
+                onClick={handleInstall}
+              >
+                {isInstalling ? t('installing.label') : t('install.label')}
+              </Button>
+            ) : (
+              <Input.Root id={inputId}>
+                <Input.Switch classNames='self-center' checked={isEnabled} onClick={handleChange} />
+              </Input.Root>
+            )}
           </div>
         </div>
       </div>
@@ -114,11 +214,13 @@ export const PluginItem = ({
   );
 };
 
-const tagColors: Record<RegistryTagType, ChromaticPalette> = {
+const tagColors: Record<RegistryTagType, ChromaticPalette | NeutralPalette> = {
   new: 'rose',
   beta: 'teal',
   labs: 'blue',
   popular: 'green',
   featured: 'pink',
   experimental: 'amber',
+  registry: 'indigo',
+  local: 'neutral',
 };

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

@@ -6,17 +6,17 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';
 
 import { type Plugin, Plugin as PluginNS } from '@dxos/app-framework';
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 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 { RegistryTagType } from '#types';
 
 import { PluginList } from './PluginList';
 
-faker.seed(1);
+random.seed(1);
 
 const icons = [
   'ph--bug--regular',
@@ -29,17 +29,17 @@ const icons = [
 
 const DefaultStory = () => {
   const [plugins] = useState<Plugin.Plugin[]>(
-    faker.helpers.multiple(
+    random.helpers.multiple(
       () =>
         PluginNS.define({
-          id: `org.dxos.plugin.plugin-${faker.string.uuid()}`,
-          name: `${faker.commerce.productName()}`,
-          description: faker.lorem.sentences(Math.ceil(Math.random() * 3)),
-          tags: faker.helpers.uniqueArray(RegistryTagType.literals as any, Math.floor(Math.random() * 3)),
-          icon: faker.helpers.arrayElement(icons),
-          iconHue: getHashHue(faker.string.uuid()),
-          homePage: faker.datatype.boolean({ probability: 0.5 }) ? faker.internet.url() : undefined,
-          source: faker.internet.url(),
+          id: `org.dxos.plugin.plugin-${random.string.uuid()}`,
+          name: `${random.commerce.productName()}`,
+          description: random.lorem.sentences(Math.ceil(Math.random() * 3)),
+          tags: random.helpers.uniqueArray(RegistryTagType.literals as any, Math.floor(Math.random() * 3)),
+          icon: random.helpers.arrayElement(icons),
+          iconHue: getHashHue(random.string.uuid()),
+          homePage: random.datatype.boolean({ probability: 0.5 }) ? random.internet.url() : undefined,
+          source: random.internet.url(),
         }).pipe(PluginNS.make)(),
       { count: 32 },
     ),
@@ -73,7 +73,10 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'bg-deck-surface' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
 };
 
 export const FullScreen: Story = {

package/src/components/PluginList/PluginList.tsx

@@ -4,20 +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'> & {
+export type PluginListProps = Omit<PluginItemProps, 'plugin' | 'extraTags' | 'hasUpdate' | 'failure'> & {
   plugins?: readonly Plugin.Plugin[];
+  /**
+   * 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 = [], ...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} {...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

@@ -2,5 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './DisableDependentsAlert';
 export * from './PluginDetail';
+export * from './PluginFailureBadge';
 export * from './PluginList';
+export * from './RegistrySettings';

package/src/containers/BaseRegistryArticle/BaseRegistryArticle.tsx

@@ -0,0 +1,178 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { type ReactNode, useCallback, useMemo, useState } from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { useCapabilities, useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
+import { AppCapabilities, LayoutOperation, SettingsOperation } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+import { Input, Panel, ScrollArea, Toolbar, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/ui-theme';
+
+import { PluginList, type PluginListProps } from '#components';
+import { getPluginPath, meta } from '#meta';
+
+import { useDisableConfirmation } from '../../hooks';
+
+const matchesFilter = (plugin: Plugin.Plugin, query: string) => {
+  const haystack = `${plugin.meta.name ?? ''} ${plugin.meta.id}`.toLowerCase();
+  return haystack.includes(query);
+};
+
+export type BaseRegistryArticleProps = {
+  /** Article id used as the pivotId when opening a plugin's detail surface. */
+  id: string;
+  /** Plugins to display, pre-sorted by the caller. */
+  plugins: readonly Plugin.Plugin[];
+  /**
+   * Distinguishes the source of toggle events for observability
+   * (e.g. `'registry'` for the public registry surface).
+   */
+  source?: string;
+  /** Rendered in place of the list when no plugins match the current filter. */
+  empty?: ReactNode;
+} & Pick<
+  PluginListProps,
+  | 'installed'
+  | 'installing'
+  | 'updating'
+  | 'updateAvailableIds'
+  | 'extraTagsById'
+  | 'failuresById'
+  | 'onInstall'
+  | 'onUpdate'
+>;
+
+export const BaseRegistryArticle = composable<HTMLDivElement, BaseRegistryArticleProps>(
+  (
+    {
+      id,
+      plugins,
+      source,
+      empty,
+      installed,
+      installing,
+      updating,
+      updateAvailableIds,
+      extraTagsById,
+      failuresById,
+      onInstall,
+      onUpdate,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(meta.id);
+    const manager = usePluginManager();
+    const { invoke, invokePromise } = useOperationInvoker();
+    const allSettings = useCapabilities(AppCapabilities.Settings);
+    const enabled = useAtomValue(manager.enabled);
+    const [filter, setFilter] = useState('');
+
+    const filtered = useMemo(() => {
+      const query = filter.trim().toLowerCase();
+      return query.length === 0 ? plugins : plugins.filter((plugin) => matchesFilter(plugin, query));
+    }, [plugins, filter]);
+
+    const dispatchToggle = useCallback(
+      (pluginId: string, nextEnabled: boolean) =>
+        Effect.gen(function* () {
+          if (nextEnabled) {
+            yield* manager.enable(pluginId);
+          } else {
+            yield* manager.disable(pluginId);
+          }
+          yield* invoke(ObservabilityOperation.SendEvent, {
+            name: 'plugins.toggle',
+            properties: source
+              ? { plugin: pluginId, enabled: nextEnabled, source }
+              : { plugin: pluginId, enabled: nextEnabled },
+          });
+        }).pipe(runAndForwardErrors),
+      [invoke, manager, source],
+    );
+
+    const requestDisable = useDisableConfirmation(manager, (id) => void dispatchToggle(id, false));
+
+    const handleChange = useCallback(
+      (pluginId: string, nextEnabled: boolean) => {
+        if (nextEnabled) {
+          void dispatchToggle(pluginId, true);
+          return;
+        }
+        requestDisable(pluginId);
+      },
+      [dispatchToggle, requestDisable],
+    );
+
+    const handleClick = useCallback(
+      (pluginId: string) =>
+        invokePromise(LayoutOperation.Open, {
+          subject: [getPluginPath(pluginId)],
+          pivotId: id,
+          positioning: 'end',
+        }),
+      [invokePromise, id],
+    );
+
+    const hasSettings = useCallback(
+      (pluginId: string) => allSettings.some((setting) => setting.prefix === pluginId),
+      [allSettings],
+    );
+
+    const handleSettings = useCallback(
+      (pluginId: string) => invokePromise(SettingsOperation.Open, { plugin: pluginId }),
+      [invokePromise],
+    );
+
+    return (
+      <Panel.Root {...composableProps(props)} ref={forwardedRef}>
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <Input.Root>
+              <Input.Label srOnly>{t('filter.label')}</Input.Label>
+              <Input.TextInput
+                placeholder={t('filter.placeholder')}
+                value={filter}
+                onChange={(event) => setFilter(event.target.value)}
+              />
+            </Input.Root>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <ScrollArea.Root orientation='vertical'>
+            <ScrollArea.Viewport>
+              {filtered.length > 0 ? (
+                <PluginList
+                  plugins={filtered}
+                  enabled={enabled}
+                  installed={installed}
+                  installing={installing}
+                  updating={updating}
+                  updateAvailableIds={updateAvailableIds}
+                  extraTagsById={extraTagsById}
+                  failuresById={failuresById}
+                  onClick={handleClick}
+                  onChange={handleChange}
+                  onInstall={onInstall}
+                  onUpdate={onUpdate}
+                  hasSettings={hasSettings}
+                  onSettings={handleSettings}
+                />
+              ) : (
+                empty
+              )}
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </Panel.Content>
+      </Panel.Root>
+    );
+  },
+);
+
+BaseRegistryArticle.displayName = 'BaseRegistryArticle';

package/src/containers/BaseRegistryArticle/index.ts

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