@dxos/plugin-crx 0.0.0

package/src/page-actions.ts

@@ -0,0 +1,171 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Result from 'effect/Result';
+import * as Schema from 'effect/Schema';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import type * as CapabilityManager from '@dxos/app-framework/CapabilityManager';
+import * as AppSpace from '@dxos/app-toolkit/AppSpace';
+import { type Database } from '@dxos/echo';
+import { type SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import * as ClientCapabilities from '@dxos/plugin-client/ClientCapabilities';
+
+import { CrxCapabilities, PageAction, Settings } from '#types';
+
+/**
+ * Dependencies for the invoke handler, injected so the handler can be
+ * unit-tested without a capability manager (the capability module wires the
+ * real implementations).
+ */
+export type InvokeDeps = {
+  getActions: () => PageAction.PageAction[];
+  getSettings: () => Settings.Settings;
+  getTarget: () => Database.Database | undefined;
+  invoke: (
+    operation: PageAction.PageAction['operation'],
+    input: unknown,
+  ) => Promise<{ data?: { id?: string }; error?: unknown }>;
+};
+
+/**
+ * Answer a registry-list request with the currently contributed actions as
+ * serializable descriptors.
+ */
+export const handleListEvent = (detail: unknown, getActions: () => PageAction.PageAction[]): PageAction.ListAck => {
+  const decoded = Schema.decodeUnknownResult(PageAction.ListRequest)(detail);
+  if (Result.isFailure(decoded)) {
+    log.info('rejected invalid page-actions list request');
+    // Best-effort id echo so the extension can correlate the failure ack.
+    const envelope = Schema.decodeUnknownResult(PageAction.Envelope)(detail);
+    const id = Result.isSuccess(envelope) ? (envelope.success.id ?? '') : '';
+    return { version: 1, id, ok: false, error: 'invalidPayload' };
+  }
+  return {
+    version: 1,
+    id: decoded.success.id,
+    ok: true,
+    actions: getActions().map(PageAction.toDescriptor),
+  };
+};
+
+/**
+ * Handle a single invoke request. Two-pass decode (loose envelope, then
+ * strict payload) so newer versions yield `unsupportedVersion` rather than
+ * the generic `invalidPayload`.
+ */
+export const handleInvokeEvent = async (detail: unknown, deps: InvokeDeps): Promise<PageAction.InvokeAck> => {
+  const envelope = Schema.decodeUnknownResult(PageAction.Envelope)(detail);
+  if (Result.isFailure(envelope)) {
+    log.info('rejected invalid page-action envelope');
+    return { version: 1, id: '', ok: false, error: 'invalidPayload' };
+  }
+  // Best-effort id echo so the extension can correlate failure acks.
+  const envelopeId = envelope.success.id ?? '';
+
+  // Master toggle: when off, the bridge acks (so the extension does not time
+  // out) but ignores all extension-initiated actions.
+  if (!Settings.withDefaults(deps.getSettings()).enabled) {
+    log.info('ignored page action: extension actions disabled in settings');
+    return { version: 1, id: envelopeId, ok: false, error: 'disabled' };
+  }
+
+  if (envelope.success.version !== 1) {
+    log.info('rejected unsupported page-action version', { version: envelope.success.version });
+    return { version: 1, id: envelopeId, ok: false, error: 'unsupportedVersion' };
+  }
+
+  const decoded = Schema.decodeUnknownResult(PageAction.InvokeRequest)(detail);
+  if (Result.isFailure(decoded)) {
+    log.info('rejected invalid page-action payload');
+    return { version: 1, id: envelopeId, ok: false, error: 'invalidPayload' };
+  }
+  const request = decoded.success;
+
+  const action = deps.getActions().find((candidate) => candidate.id === request.actionId);
+  if (!action) {
+    log.info('rejected unknown page action', { actionId: request.actionId });
+    return { version: 1, id: request.id, ok: false, error: 'unknownAction' };
+  }
+
+  const target = deps.getTarget();
+  if (!target) {
+    return { version: 1, id: request.id, ok: false, error: 'noSpace' };
+  }
+
+  try {
+    const { data, error } = await deps.invoke(action.operation, { snapshot: request.inputs, target });
+    if (error || !data) {
+      log.info('page-action operation failed', { actionId: action.id, error });
+      return { version: 1, id: request.id, ok: false, error: 'operationFailed' };
+    }
+    log.info('page action invoked', { actionId: action.id, objectId: data.id });
+    return { version: 1, id: request.id, ok: true, objectId: data.id };
+  } catch (err) {
+    log.catch(err);
+    return { version: 1, id: request.id, ok: false, error: 'operationFailed' };
+  }
+};
+
+/**
+ * Attach the page-actions window event listeners. Returns a disposer.
+ * Actions are resolved per-event via `getAll` so late-activating plugins are
+ * always included.
+ */
+export const installPageActionListeners = (
+  capabilities: CapabilityManager.CapabilityManager,
+  invoker: Capabilities.OperationInvoker,
+  onResult?: (ack: PageAction.InvokeAck, label?: string, spaceId?: SpaceId) => void,
+): (() => void) => {
+  const getActions = () => capabilities.getAll(CrxCapabilities.PageAction).flat();
+
+  const onList = (event: Event) => {
+    const ack = handleListEvent((event as CustomEvent).detail, getActions);
+    window.dispatchEvent(new CustomEvent(PageAction.LIST_ACK_EVENT, { detail: ack }));
+  };
+
+  const onInvoke = (event: Event) => {
+    const detail = (event as CustomEvent).detail;
+    // Resolved once so the ack's object is looked up in the space it was created in.
+    let target: Database.Database | undefined;
+    const deps: InvokeDeps = {
+      getActions,
+      getSettings: () => capabilities.get(Capabilities.AtomRegistry).get(capabilities.get(CrxCapabilities.Settings)),
+      getTarget: () => {
+        const client = capabilities.get(ClientCapabilities.Client);
+        target = AppSpace.getActiveSpace(client, capabilities)?.db;
+        return target;
+      },
+      invoke: (operation, input) => invoker.invokePromise(operation, input),
+    };
+    void handleInvokeEvent(detail, deps)
+      .catch((err): PageAction.InvokeAck => {
+        log.catch(err);
+        return { version: 1, id: '', ok: false, error: 'operationFailed' };
+      })
+      .then((ack) => {
+        window.dispatchEvent(new CustomEvent(PageAction.INVOKE_ACK_EVENT, { detail: ack }));
+        try {
+          const actionId = (detail as { actionId?: string } | null)?.actionId;
+          onResult?.(ack, getActions().find((candidate) => candidate.id === actionId)?.label, target?.spaceId);
+        } catch (err) {
+          log.catch(err);
+        }
+      });
+  };
+
+  window.addEventListener(PageAction.LIST_EVENT, onList as EventListener);
+  window.addEventListener(PageAction.INVOKE_EVENT, onInvoke as EventListener);
+
+  // Announce that the page-side listeners are ready so the extension relay
+  // can trigger a registry refresh even when Composer boots after the
+  // content script has already installed.
+  window.dispatchEvent(new CustomEvent(PageAction.READY_EVENT));
+
+  return () => {
+    window.removeEventListener(PageAction.LIST_EVENT, onList as EventListener);
+    window.removeEventListener(PageAction.INVOKE_EVENT, onInvoke as EventListener);
+  };
+};

package/src/plugin.tsx

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Plugin from '@dxos/app-framework/Plugin';
+
+import {
+  CrxSettings,
+  InstallPageActions,
+  OperationHandler,
+  PageActionProvider,
+  PluginAsset,
+  ReactSurface,
+  Translations,
+} from '#capabilities';
+import { meta } from '#meta';
+
+export const CrxPlugin = Plugin.define(meta).pipe(
+  Plugin.addModule(CrxSettings),
+  Plugin.addModule(InstallPageActions),
+  Plugin.addModule(OperationHandler),
+  Plugin.addModule(PageActionProvider),
+  Plugin.addModule(PluginAsset),
+  Plugin.addModule(ReactSurface),
+  Plugin.addModule(Translations),
+  Plugin.make,
+);
+
+export default CrxPlugin;

package/src/stories/Testbench.stories.tsx

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { random } from '@dxos/random';
+import { Image, ScrollArea } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+const DefaultStory = () => {
+  const { title, image, paragraphs } = useMemo(
+    () => ({
+      title: random.lorem.sentence(4),
+      image: random.image.url(),
+      paragraphs: Array.from({ length: 10 }, () => random.lorem.paragraph(3)),
+    }),
+    [],
+  );
+
+  return (
+    <ScrollArea.Root centered padding>
+      <ScrollArea.Viewport classNames='flex flex-col gap-2 py-3'>
+        <h1 className='text-2xl'>{title}</h1>
+        <Image src={image} alt={title} fit='cover' />
+        {paragraphs.map((paragraph, index) => (
+          <p key={index}>{paragraph}</p>
+        ))}
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'plugins/plugin-crx/stories/Testbench',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/translations.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Resource } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+export const translations = [
+  {
+    'en-US': {
+      [meta.profile.key]: {
+        'plugin.name': 'Browser Extension',
+        'settings.description':
+          'Install the browser extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/composer/ahkmmpagcinoehpnmdhoiohmmbikhnmj?pli=1).',
+        'test.title': 'Connection',
+        'test.button.label': 'Test connection',
+        'test.pending.message': 'Contacting extension…',
+        'test.connected.message': 'Connected to {{name}} v{{version}}.',
+        'toast.error.invalidPayload.message': 'Unrecognized payload.',
+        'toast.error.unsupportedVersion.message': 'Unsupported version — update Composer.',
+        'toast.error.disabled.message': 'Extension actions are disabled in settings.',
+        'toast.error.noSpace.message': 'Open a space first.',
+        'toast.page-action.success.title': 'Action complete',
+        'toast.page-action.error.title': 'Action failed',
+        'toast.error.unknownAction.message': 'Unknown action — update Composer or the extension.',
+        'toast.error.operationFailed.message': 'The action failed to run.',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/CrxCapabilities.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as Atom from 'effect/unstable/reactivity/Atom';
+
+import * as Capability from '@dxos/app-framework/Capability';
+
+import { meta } from '#meta';
+
+/**
+ * Writable atom holding the plugin's Settings.
+ */
+export const Settings = Capability.makeSingleton<Atom.Writable<import('./Settings.ts').Settings>>()(
+  `${meta.profile.key}.capability.settings`,
+);
+
+/**
+ * Page actions contributed by plugins for the browser extension to surface.
+ * Multi: each contributor provides one array (e.g. plugin-bookmarks); consumers flatten via `getAll`.
+ */
+export const PageAction = Capability.make<import('./PageAction.ts').PageAction[]>()(
+  `${meta.profile.key}.capability.pageAction`,
+);

package/src/types/CrxEvents.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as ActivationEvent from '@dxos/app-framework/ActivationEvent';
+
+import { meta } from '#meta';
+
+/**
+ * The feature's start event: the plugin's start-gated modules (and cross-plugin
+ * contributions consumed by this feature) activate here. Fired on demand and by the
+ * host's idle trickle.
+ */
+export const Start = ActivationEvent.pluginStart(meta.profile.key);

package/src/types/CrxOperation.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Database, DXN } from '@dxos/echo';
+
+import * as PageAction from './PageAction.ts';
+
+const input = Schema.Struct({
+  snapshot: PageAction.Snapshot,
+  target: Database.Database.annotate({ description: 'The database to add the object to.' }),
+});
+
+const output = Schema.Struct({
+  id: Schema.String,
+});
+
+export const AddPersonFromSnapshot = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.crx.addPersonFromSnapshot'),
+    name: 'Add person',
+    description: 'Create a person from a page snapshot.',
+    icon: 'ph--user--regular',
+  },
+  input,
+  output,
+});
+
+export const AddOrganizationFromSnapshot = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.crx.addOrganizationFromSnapshot'),
+    name: 'Add organization',
+    description: 'Create an organization from a page snapshot.',
+    icon: 'ph--building-office--regular',
+  },
+  input,
+  output,
+});
+
+export const AddNoteFromSnapshot = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.crx.addNoteFromSnapshot'),
+    name: 'Add note',
+    description: 'Create a markdown note from a page snapshot.',
+    icon: 'ph--note--regular',
+  },
+  input,
+  output,
+});

package/src/types/PageAction.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as Operation from '@dxos/compute/Operation';
+import { PageAction as Protocol } from '@dxos/crx-protocol';
+
+// Re-export the serializable wire schemas from the shared protocol package.
+export const {
+  Rect,
+  Source,
+  Selection,
+  Hints,
+  Snapshot,
+  Predicate,
+  ExtractorRef,
+  Context,
+  Descriptor,
+  PageInfo,
+  Envelope,
+  ListRequest,
+  ListAck,
+  InvokeRequest,
+  InvokeAck,
+  READY_EVENT,
+  LIST_EVENT,
+  LIST_ACK_EVENT,
+  INVOKE_EVENT,
+  INVOKE_ACK_EVENT,
+} = Protocol;
+
+export type Source = Protocol.Source;
+export type Selection = Protocol.Selection;
+export type Hints = Protocol.Hints;
+export type Snapshot = Protocol.Snapshot;
+export type Predicate = Protocol.Predicate;
+export type ExtractorRef = Protocol.ExtractorRef;
+export type Context = Protocol.Context;
+export type Descriptor = Protocol.Descriptor;
+export type PageInfo = Protocol.PageInfo;
+export type Envelope = Protocol.Envelope;
+export type ListRequest = Protocol.ListRequest;
+export type ListAck = Protocol.ListAck;
+export type InvokeRequest = Protocol.InvokeRequest;
+export type InvokeAck = Protocol.InvokeAck;
+
+/** A live page-action contribution: the target operation accepts `{ snapshot, target }` and returns `{ id }`. */
+export type PageAction = Omit<Descriptor, 'operation'> & {
+  operation: Operation.Definition.Any;
+};
+
+export const toDescriptor = (action: PageAction): Descriptor => ({
+  ...action,
+  operation: action.operation.meta.key.toString(),
+});

package/src/types/Settings.test.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Settings from './Settings.ts';
+
+describe('Settings', () => {
+  test('applies documented defaults when fields are absent', ({ expect }) => {
+    expect(Settings.withDefaults({})).toEqual(Settings.defaults);
+    expect(Settings.defaults.enabled).toBe(true);
+    expect(Settings.defaults.autoOpenAfterClip).toBe(false);
+    expect(Settings.defaults.renderProxyEnabled).toBe(true);
+    expect(Settings.defaults.renderTimeout).toBe(20_000);
+    expect(Settings.defaults.renderActiveTab).toBe(false);
+    expect(Settings.defaults.developerMode).toBe(false);
+  });
+
+  test('merges user-set values over defaults', ({ expect }) => {
+    const merged = Settings.withDefaults({ renderProxyEnabled: false, renderTimeout: 5_000, enabled: false });
+    expect(merged.enabled).toBe(false);
+    expect(merged.autoOpenAfterClip).toBe(false);
+    expect(merged.renderProxyEnabled).toBe(false);
+    expect(merged.renderTimeout).toBe(5_000);
+    // Untouched fields fall back to defaults.
+    expect(merged.renderActiveTab).toBe(false);
+    expect(merged.developerMode).toBe(false);
+  });
+});

package/src/types/Settings.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+import * as Struct from 'effect/Struct';
+
+/**
+ * User preferences that govern how Composer coordinates with the composer-crx
+ * browser extension — both the page-actions bridge and the render-proxy. All fields
+ * are optional; defaults are applied by consumers when reading the atom.
+ */
+export const Settings = Schema.Struct({
+  /**
+   * Master toggle. When false, the bridge plugin ignores incoming extension actions.
+   * Defaults to `true`.
+   */
+  enabled: Schema.optional(
+    Schema.Boolean.annotate({
+      title: 'Accept extension actions',
+      description: 'When off, actions sent from the composer-crx browser extension are ignored.',
+    }),
+  ),
+
+  /**
+   * Navigate to the created object after the extension creates one. Defaults to
+   * `false` to avoid yanking focus during active work.
+   */
+  autoOpenAfterClip: Schema.optional(
+    Schema.Boolean.annotate({
+      title: 'Open after action',
+      description: 'Navigate to the created object when the extension creates one.',
+    }),
+  ),
+
+  /**
+   * Master toggle. When false, plugins fall back to the edge HTTP proxy instead of asking the
+   * extension to render pages. Defaults to `true`.
+   */
+  renderProxyEnabled: Schema.optional(
+    Schema.Boolean.annotate({
+      title: 'Use extension to render pages',
+      description: 'Let plugins render pages via the browser extension to scrape client-rendered sites.',
+    }),
+  ),
+
+  /**
+   * Maximum time (ms) to wait for a page to render before aborting. Defaults to `20000`.
+   */
+  renderTimeout: Schema.optional(
+    Schema.Number.annotate({
+      title: 'Render timeout (ms)',
+      description: 'Maximum time to wait for a page to finish rendering before giving up.',
+    }),
+  ),
+
+  /**
+   * Render pages in a focused (foreground) tab. Helps sites that defer loading when backgrounded,
+   * at the cost of stealing focus. Defaults to `false`.
+   */
+  renderActiveTab: Schema.optional(
+    Schema.Boolean.annotate({
+      title: 'Render in focused tab',
+      description: 'Render pages in a focused tab; helps sites that defer loading when backgrounded.',
+    }),
+  ),
+
+  /**
+   * Enable verbose logging and debug previews in the extension. Defaults to `false`.
+   */
+  developerMode: Schema.optional(
+    Schema.Boolean.annotate({
+      title: 'Developer mode',
+      description: 'Enable verbose logging and debug previews in the browser extension.',
+    }),
+  ),
+}).mapFields(Struct.map(Schema.mutableKey));
+
+export interface Settings extends Schema.Schema.Type<typeof Settings> {}
+
+/**
+ * Default values applied when a field is absent. Kept separate from the
+ * schema so `createKvsStore` can store only user-set values while consumers
+ * (this plugin's components, and any downstream reader) see sensible
+ * defaults.
+ */
+export const defaults: Required<Settings> = {
+  enabled: true,
+  autoOpenAfterClip: false,
+  renderProxyEnabled: true,
+  renderTimeout: 20_000,
+  renderActiveTab: false,
+  developerMode: false,
+};
+
+export const withDefaults = (settings: Settings): Required<Settings> => ({
+  ...defaults,
+  ...settings,
+});

package/src/types/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as CrxCapabilities from './CrxCapabilities.ts';
+export * as CrxEvents from './CrxEvents.ts';
+export * as CrxOperation from './CrxOperation.ts';
+export * as PageAction from './PageAction.ts';
+export * as Settings from './Settings.ts';

package/src/util/index.ts

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

package/src/util/pingExtension.test.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { Proxy } from '@dxos/crx-protocol';
+
+import { isExtensionAvailable, pingExtension } from './pingExtension.ts';
+
+const setAvailable = (available: boolean) => {
+  if (available) {
+    document.documentElement.dataset[Proxy.RENDER_READY_DATASET_KEY] = '1';
+  } else {
+    delete document.documentElement.dataset[Proxy.RENDER_READY_DATASET_KEY];
+  }
+};
+
+// Stand in for the extension content relay: ack each ping with the given outcome.
+const installFakeRelay = (respond: (id: string) => unknown) => {
+  const listener = (event: Event) => {
+    const detail = (event as CustomEvent).detail as { id: string };
+    window.dispatchEvent(new CustomEvent(Proxy.PING_ACK_EVENT, { detail: respond(detail.id) }));
+  };
+  window.addEventListener(Proxy.PING_EVENT, listener);
+  return () => window.removeEventListener(Proxy.PING_EVENT, listener);
+};
+
+describe('pingExtension', () => {
+  beforeEach(() => setAvailable(false));
+  afterEach(() => setAvailable(false));
+
+  test('isExtensionAvailable reflects the dataset marker', ({ expect }) => {
+    expect(isExtensionAvailable()).toBe(false);
+    setAvailable(true);
+    expect(isExtensionAvailable()).toBe(true);
+  });
+
+  test('resolves with the extension identity on a successful ack', async ({ expect }) => {
+    setAvailable(true);
+    const uninstall = installFakeRelay((id) => ({
+      version: 1,
+      id,
+      ok: true,
+      extensionVersion: '0.8.3',
+      extensionName: 'Composer',
+    }));
+    await expect(pingExtension()).resolves.toEqual({ extensionVersion: '0.8.3', extensionName: 'Composer' });
+    uninstall();
+  });
+
+  test('rejects when the extension is not detected', async ({ expect }) => {
+    setAvailable(false);
+    await expect(pingExtension()).rejects.toThrow(/not detected/);
+  });
+
+  test('rejects on a non-ok ack', async ({ expect }) => {
+    setAvailable(true);
+    const uninstall = installFakeRelay((id) => ({ version: 1, id, ok: false, error: 'forbiddenOrigin' }));
+    await expect(pingExtension()).rejects.toThrow(/forbiddenOrigin/);
+    uninstall();
+  });
+
+  test('rejects on timeout when no ack arrives', async ({ expect }) => {
+    setAvailable(true);
+    await expect(pingExtension(50)).rejects.toThrow(/did not respond/);
+  });
+});