@dxos/plugin-crx 0.0.0

package/dx.config.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Config2 } from '@dxos/app-framework/config';
+import { trim } from '@dxos/util';
+
+export default Config2.make({
+  plugin: {
+    key: 'org.dxos.plugin.crx',
+    name: 'Browser Extension',
+    author: 'DXOS',
+    description: trim`
+      Capture content from any web page into your workspace with the Composer browser extension.
+      Highlight a section of a page and save it as a contact, an organization, or a bookmark —
+      the page's title, images, and details are picked up automatically, so a profile page
+      becomes a ready-made Person card and an article becomes a note with its source and text already filled in.
+
+      Saved items land in your active space alongside everything else you're working on,
+      complete with a link back to the original page.
+
+      Install the browser extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/composer/ahkmmpagcinoehpnmdhoiohmmbikhnmj?pli=1).
+    `,
+    source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-crx',
+    icon: { key: 'ph--puzzle-piece--regular', hue: 'orange' },
+    // screenshots: [
+    //   { dark: 'https://raw.githubusercontent.com/dxos/dxos/refs/heads/main/packages/plugins/plugin-crx/assets/images/' },
+    // ],
+    spec: 'PLUGIN.mdl',
+    tags: ['labs'],
+  },
+});

package/package.json

@@ -0,0 +1,162 @@
+{
+  "name": "@dxos/plugin-crx",
+  "version": "0.0.0",
+  "description": "Composer plugin for coordinating with the composer-crx browser extension.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "imports": {
+    "#capabilities": {
+      "source": {
+        "workerd": "./src/capabilities/gen/workerd.ts",
+        "node": "./src/capabilities/gen/node.ts",
+        "default": "./src/capabilities/index.ts"
+      },
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "workerd": "./dist/lib/capabilities.workerd.mjs",
+      "node": "./dist/lib/capabilities.node.mjs",
+      "default": "./dist/lib/capabilities.mjs"
+    },
+    "#containers": {
+      "source": "./src/containers/index.ts",
+      "types": "./dist/types/src/containers/index.d.ts",
+      "default": "./dist/lib/containers.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/meta.mjs"
+    },
+    "#operations": {
+      "source": "./src/operations/index.ts",
+      "types": "./dist/types/src/operations/index.d.ts",
+      "default": "./dist/lib/operations.mjs"
+    },
+    "#plugin": {
+      "source": "./src/plugin.tsx",
+      "types": "./dist/types/src/plugin.d.ts",
+      "default": "./dist/lib/plugin.mjs"
+    },
+    "#translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/translations.mjs"
+    },
+    "#types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "default": "./dist/lib/types.mjs"
+    }
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/lib/index.mjs"
+    },
+    "./assets/PLUGIN.mdl": "./PLUGIN.mdl",
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "import": "./dist/lib/translations.mjs"
+    },
+    "./package.json": "./package.json",
+    "./CrxCapabilities": {
+      "source": "./src/types/CrxCapabilities.ts",
+      "types": "./dist/types/src/types/CrxCapabilities.d.ts",
+      "import": "./dist/lib/CrxCapabilities.mjs"
+    },
+    "./CrxEvents": {
+      "source": "./src/types/CrxEvents.ts",
+      "types": "./dist/types/src/types/CrxEvents.d.ts",
+      "import": "./dist/lib/CrxEvents.mjs"
+    },
+    "./CrxOperation": {
+      "source": "./src/types/CrxOperation.ts",
+      "types": "./dist/types/src/types/CrxOperation.d.ts",
+      "import": "./dist/lib/CrxOperation.mjs"
+    },
+    "./CrxPlugin": {
+      "source": "./src/CrxPlugin.ts",
+      "types": "./dist/types/src/CrxPlugin.d.ts",
+      "import": "./dist/lib/CrxPlugin.mjs"
+    },
+    "./PageAction": {
+      "source": "./src/types/PageAction.ts",
+      "types": "./dist/types/src/types/PageAction.d.ts",
+      "import": "./dist/lib/PageAction.mjs"
+    },
+    "./Settings": {
+      "source": "./src/types/Settings.ts",
+      "types": "./dist/types/src/types/Settings.d.ts",
+      "import": "./dist/lib/Settings.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "CrxCapabilities": [
+        "dist/types/src/types/CrxCapabilities.d.ts"
+      ],
+      "CrxEvents": [
+        "dist/types/src/types/CrxEvents.d.ts"
+      ],
+      "CrxOperation": [
+        "dist/types/src/types/CrxOperation.d.ts"
+      ],
+      "PageAction": [
+        "dist/types/src/types/PageAction.d.ts"
+      ],
+      "Settings": [
+        "dist/types/src/types/Settings.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "dx.config.ts",
+    "src",
+    "PLUGIN.mdl"
+  ],
+  "dependencies": {
+    "effect": "4.0.0-rc.117",
+    "@dxos/app-framework": "0.11.1",
+    "@dxos/compute": "0.11.1",
+    "@dxos/app-toolkit": "0.11.1",
+    "@dxos/crx-protocol": "0.0.0",
+    "@dxos/echo": "0.11.1",
+    "@dxos/effect": "0.11.1",
+    "@dxos/plugin-client": "0.11.1",
+    "@dxos/keys": "0.11.1",
+    "@dxos/log": "0.11.1",
+    "@dxos/plugin-space": "0.11.1",
+    "@dxos/react-ui": "0.11.1",
+    "@dxos/react-ui-form": "0.11.1",
+    "@dxos/plugin-markdown": "0.11.1",
+    "@dxos/util": "0.11.1",
+    "@dxos/types": "0.11.1"
+  },
+  "devDependencies": {
+    "@effect/atom-react": "4.0.0-rc.117",
+    "@storybook/react-vite": "^10.5.8",
+    "@types/react": "~19.2.17",
+    "react": "~19.2.7",
+    "vite": "^8.2.1",
+    "vitest": "4.1.10",
+    "@dxos/random": "0.11.1"
+  },
+  "peerDependencies": {
+    "react": "~19.2.7",
+    "@dxos/react-ui": "^0.11.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/CrxPlugin.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Plugin from '@dxos/app-framework/Plugin';
+
+import { meta as pluginMeta } from '#meta';
+
+/** Plugin metadata, available without loading the plugin body. */
+export const meta = pluginMeta;
+
+/** Constructs the plugin; the body loads on first enable. */
+export const make = Plugin.lazy(meta, () => import('#plugin'));

package/src/capabilities/gen/node.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// GENERATED by dx-plugin — do not edit. Sliced from ../index.ts for the 'node' condition.
+
+import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapability from '@dxos/app-toolkit/AppCapability';
+
+import { translations } from '#translations';
+import { CrxCapabilities, CrxEvents } from '#types';
+
+export const CrxSettings = AppCapability.settings(() => import('../settings.ts'), {
+  activatesOn: ActivationEvents.Idle,
+  provides: [CrxCapabilities.Settings],
+});
+
+export const InstallPageActions = Capability.lazyModule(
+  'InstallPageActions',
+  {
+    requires: [Capabilities.OperationInvoker, Capabilities.AtomRegistry, CrxCapabilities.Settings],
+    provides: [],
+    activatesOn: CrxEvents.Start,
+  },
+  () => import('../install-page-actions.ts'),
+);
+
+export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler.ts'), {
+  activatesOn: ActivationEvents.Idle,
+});
+
+export const PageActionProvider = Capability.lazyModule(
+  'PageActionProvider',
+  { provides: [CrxCapabilities.PageAction], activatesOn: CrxEvents.Start },
+  () => import('../page-action-provider.ts'),
+);
+
+export const Translations = AppCapability.translations(translations);
+
+export const PluginAsset = undefined;
+export const ReactSurface = undefined;

package/src/capabilities/gen/workerd.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// GENERATED by dx-plugin — do not edit. Sliced from ../index.ts for the 'workerd' condition.
+
+import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapability from '@dxos/app-toolkit/AppCapability';
+
+import { translations } from '#translations';
+import { CrxCapabilities, CrxEvents } from '#types';
+
+export const CrxSettings = AppCapability.settings(() => import('../settings.ts'), {
+  activatesOn: ActivationEvents.Idle,
+  provides: [CrxCapabilities.Settings],
+});
+
+export const InstallPageActions = Capability.lazyModule(
+  'InstallPageActions',
+  {
+    requires: [Capabilities.OperationInvoker, Capabilities.AtomRegistry, CrxCapabilities.Settings],
+    provides: [],
+    activatesOn: CrxEvents.Start,
+  },
+  () => import('../install-page-actions.ts'),
+);
+
+export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler.ts'), {
+  activatesOn: ActivationEvents.Idle,
+});
+
+export const PageActionProvider = Capability.lazyModule(
+  'PageActionProvider',
+  { provides: [CrxCapabilities.PageAction], activatesOn: CrxEvents.Start },
+  () => import('../page-action-provider.ts'),
+);
+
+export const Translations = AppCapability.translations(translations);
+
+export const PluginAsset = undefined;
+export const ReactSurface = undefined;

package/src/capabilities/index.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapability from '@dxos/app-toolkit/AppCapability';
+
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { CrxCapabilities, CrxEvents } from '#types';
+
+// eslint-disable-next-line import/no-relative-packages
+import pluginSpec from '../../PLUGIN.mdl?raw';
+
+export const CrxSettings = AppCapability.settings(() => import('./settings.ts'), {
+  activatesOn: ActivationEvents.Idle,
+  provides: [CrxCapabilities.Settings],
+});
+export const InstallPageActions = Capability.lazyModule(
+  'InstallPageActions',
+  {
+    requires: [Capabilities.OperationInvoker, Capabilities.AtomRegistry, CrxCapabilities.Settings],
+    provides: [],
+    activatesOn: CrxEvents.Start,
+  },
+  () => import('./install-page-actions.ts'),
+);
+export const OperationHandler = AppCapability.operationHandler(() => import('./operation-handler.ts'), {
+  activatesOn: ActivationEvents.Idle,
+});
+export const PageActionProvider = Capability.lazyModule(
+  'PageActionProvider',
+  { provides: [CrxCapabilities.PageAction], activatesOn: CrxEvents.Start },
+  () => import('./page-action-provider.ts'),
+);
+export const PluginAsset = AppCapability.pluginAsset({
+  pluginId: meta.profile.key,
+  path: 'PLUGIN.mdl',
+  content: pluginSpec,
+  mimeType: 'application/x-mdl',
+});
+export const ReactSurface = AppCapability.surface(() => import('./react-surface.ts'), {
+  roles: ['org.dxos.role.article'],
+});
+export const Translations = AppCapability.translations(translations);

package/src/capabilities/install-page-actions.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
+import * as NavigationOperation from '@dxos/app-toolkit/NavigationOperation';
+import { EID, EntityId } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { meta } from '#meta';
+import { CrxCapabilities, Settings } from '#types';
+
+import { installPageActionListeners } from '../page-actions.ts';
+
+const openObject = async (invoker: Capabilities.OperationInvoker, uri: EID.EID) => {
+  const { data } = await invoker.invokePromise(NavigationOperation.ResolveNavigationTargets, { query: { uri } });
+  const path = data?.targets[0]?.path;
+  if (path) {
+    await invoker.invokePromise(LayoutOperation.Open, { subject: [path] });
+  }
+};
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilityManager = yield* Capability.Service;
+    const invoker = yield* Capabilities.OperationInvoker;
+    const registry = yield* Capabilities.AtomRegistry;
+    const settingsAtom = yield* CrxCapabilities.Settings;
+
+    // NOTE: The `Label` tuple only supports `ns`/`count`/`defaultValue`, so the
+    // success toast uses a plain key rather than interpolating the action label.
+    installPageActionListeners(capabilityManager, invoker, (ack, _label, spaceId) => {
+      if (ack.ok) {
+        void invoker.invokePromise(LayoutOperation.AddToast, {
+          id: `${meta.profile.key}.page-action-${ack.objectId ?? ack.id}`,
+          title: ['toast.page-action.success.title', { ns: meta.profile.key }],
+        });
+        const entityId = ack.objectId;
+        if (
+          spaceId &&
+          entityId &&
+          EntityId.isValid(entityId) &&
+          Settings.withDefaults(registry.get(settingsAtom)).autoOpenAfterClip
+        ) {
+          void openObject(invoker, EID.make({ spaceId, entityId }));
+        }
+      } else {
+        void invoker.invokePromise(LayoutOperation.AddToast, {
+          id: `${meta.profile.key}.page-action-error-${Date.now()}`,
+          title: ['toast.page-action.error.title', { ns: meta.profile.key }],
+          description: [`toast.error.${ack.error}.message`, { ns: meta.profile.key }],
+        });
+      }
+    });
+
+    log.info('CRX page-actions bridge installed');
+
+    return [];
+  }),
+);

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+
+import { CrxOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contribute(Capabilities.OperationHandler, CrxOperationHandlerSet);
+  }),
+);

package/src/capabilities/page-action-provider.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capability from '@dxos/app-framework/Capability';
+
+import { meta } from '#meta';
+import { CrxCapabilities, CrxOperation, PageAction } from '#types';
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    // Picker-only: these actions back the extension's DOM-picker toolbar and
+    // are not surfaced in the popup or context menu.
+    const actions: PageAction.PageAction[] = [
+      {
+        id: `${meta.profile.key}/page-action/add-person`,
+        label: 'Person',
+        icon: 'ph--user--regular',
+        urlPatterns: ['http://*/*', 'https://*/*'],
+        extractor: { name: 'snapshot' },
+        contexts: ['picker'],
+        operation: CrxOperation.AddPersonFromSnapshot,
+      },
+      {
+        id: `${meta.profile.key}/page-action/add-organization`,
+        label: 'Organization',
+        icon: 'ph--building-office--regular',
+        urlPatterns: ['http://*/*', 'https://*/*'],
+        extractor: { name: 'snapshot' },
+        contexts: ['picker'],
+        operation: CrxOperation.AddOrganizationFromSnapshot,
+      },
+      {
+        id: `${meta.profile.key}/page-action/add-note`,
+        label: 'Note',
+        icon: 'ph--note--regular',
+        urlPatterns: ['http://*/*', 'https://*/*'],
+        extractor: { name: 'snapshot' },
+        contexts: ['picker'],
+        operation: CrxOperation.AddNoteFromSnapshot,
+      },
+    ];
+    return Capability.contribute(CrxCapabilities.PageAction, actions);
+  }),
+);

package/src/capabilities/react-surface.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+
+import { CrxSettings } from '#containers';
+import { meta } from '#meta';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contribute(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'pluginSettings',
+        filter: AppSurface.settings(AppSurface.Article, meta.profile.key),
+        component: CrxSettings,
+        props: ({ data: { subject } }) => ({ subject }),
+      }),
+    ]),
+  ),
+);

package/src/capabilities/settings.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import { createKvsStore } from '@dxos/effect';
+
+import { meta } from '#meta';
+import { CrxCapabilities, Settings } from '#types';
+
+/**
+ * Contributes the Settings atom both under the plugin-scoped capability (so
+ * other plugins can read it) and under `AppCapabilities.Settings` (so the
+ * standard settings panel surfaces it).
+ */
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.profile.key,
+      schema: Settings.Settings,
+      defaultValue: () => Settings.defaults,
+    });
+
+    return [
+      Capability.contribute(CrxCapabilities.Settings, settingsAtom),
+      Capability.contribute(AppCapabilities.Settings, {
+        prefix: meta.profile.key,
+        schema: Settings.Settings,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/containers/CrxSettings/CrxSettings.stories.tsx

@@ -0,0 +1,99 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Decorator, type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Atom from 'effect/unstable/reactivity/Atom';
+import React, { useEffect, useMemo } from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Proxy } from '@dxos/crx-protocol';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+import { Settings } from '#types';
+
+import { CrxSettings } from './CrxSettings.tsx';
+
+/**
+ * Stand in for the extension's content relay so the connection test succeeds: set the readiness
+ * dataset marker and ack each ping with a fake identity. Without this the test button always
+ * reports "Extension not detected" — storybook is not a Composer origin with the extension relay.
+ */
+const withFakeExtension: Decorator = (Story) => {
+  useEffect(() => {
+    document.documentElement.dataset[Proxy.RENDER_READY_DATASET_KEY] = '1';
+    const listener = (event: Event) => {
+      const detail = (event as CustomEvent).detail as { id: string };
+      window.dispatchEvent(
+        new CustomEvent(Proxy.PING_ACK_EVENT, {
+          detail: {
+            version: 1,
+            id: detail.id,
+            ok: true,
+            extensionVersion: '0.0.0-story',
+            extensionName: 'Fake',
+          },
+        }),
+      );
+    };
+    window.addEventListener(Proxy.PING_EVENT, listener);
+    return () => {
+      delete document.documentElement.dataset[Proxy.RENDER_READY_DATASET_KEY];
+      window.removeEventListener(Proxy.PING_EVENT, listener);
+    };
+  }, []);
+  return <Story />;
+};
+
+// The container reads and writes the contributed settings entry, so the story owns one per render.
+const DefaultStory = ({ initial, readonly }: { initial?: Settings.Settings; readonly?: boolean }) => {
+  const subject = useMemo(
+    () => ({
+      prefix: pluginMeta.profile.key,
+      schema: Settings.Settings,
+      atom: Atom.make<Settings.Settings>(initial ?? Settings.defaults).pipe(Atom.keepAlive),
+    }),
+    [initial],
+  );
+
+  return <CrxSettings subject={subject} readonly={readonly} />;
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'plugins/plugin-crx/containers/CrxSettings',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withPluginManager()],
+  parameters: {
+    translations,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withFakeExtension],
+};
+
+export const Readonly: Story = {
+  decorators: [withFakeExtension],
+  args: {
+    readonly: true,
+  },
+};
+
+/**
+ * No fake relay — the connection test talks to the real composer-crx extension. For development:
+ * load the dev extension (`moon run composer-crx:build`, load unpacked from `out/composer-crx`),
+ * then add this storybook's origin (e.g. `http://localhost:9009/*`) to the extension's Composer
+ * URLs in its options page so the content relay installs here.
+ *
+ * NOTE: The extension's content script runs only in the top frame,
+ * so the story must be opened OUTSIDE the storybook manager's preview iframe:
+ * `http://localhost:9009/iframe.html?id=plugins-plugin-crx-crxsettings--live`.
+ * Without that setup the test reports "Extension not detected".
+ */
+export const Live: Story = {};