@dxos/plugin-crx 0.0.0

package/src/containers/CrxSettings/CrxSettings.tsx

@@ -0,0 +1,100 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useState } from 'react';
+
+import { useSettingsState } from '@dxos/app-framework/ui';
+import { type AppSurface, SettingsScope } from '@dxos/app-toolkit/ui';
+import { Flex, IconButton, useTranslation } from '@dxos/react-ui';
+import { Form } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { Settings } from '#types';
+
+import { pingExtension } from '../../util/index.ts';
+
+type TestState =
+  | { kind: 'idle' }
+  | { kind: 'pending' }
+  | { kind: 'ok'; message: string }
+  | { kind: 'error'; message: string };
+
+export type CrxSettingsProps = AppSurface.SettingsData<{ readonly?: boolean }>;
+
+/**
+ * Settings panel for the browser extension: edits the plugin's schema-driven settings and offers a
+ * round-trip connection test against the extension's content relay.
+ */
+export const CrxSettings = ({ subject, readonly }: CrxSettingsProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const { settings, updateSettings } = useSettingsState<Settings.Settings>(subject.atom);
+  const [test, setTest] = useState<TestState>({ kind: 'idle' });
+
+  // Round-trip a ping to the extension and report its identity (or why it failed).
+  const handleTest = useCallback(async () => {
+    setTest({ kind: 'pending' });
+    try {
+      const info = await pingExtension();
+      setTest({
+        kind: 'ok',
+        message: t('test.connected.message', { name: info.extensionName, version: info.extensionVersion }),
+      });
+    } catch (err) {
+      setTest({ kind: 'error', message: err instanceof Error ? err.message : String(err) });
+    }
+  }, [t]);
+
+  return (
+    <Form.Root
+      schema={Settings.Settings}
+      values={settings}
+      variant='settings'
+      readonly={readonly}
+      onValuesChanged={(values) => updateSettings((current) => ({ ...current, ...values }))}
+    >
+      <Form.Viewport scroll>
+        <Form.Content>
+          <Form.FieldSet
+            label={meta.profile.name ?? meta.profile.key}
+            description={t('settings.description')}
+            actions={readonly ? undefined : <SettingsScope prefix={subject.prefix} />}
+          >
+            <Form.Fields />
+          </Form.FieldSet>
+
+          <Form.FieldSet label={t('test.title')}>
+            <Flex gap='sm'>
+              <IconButton
+                disabled={test.kind === 'pending'}
+                icon='ph--plug--regular'
+                label={t('test.button.label')}
+                onClick={handleTest}
+              />
+
+              {/* role=status + aria-live so screen readers announce the async outcome. */}
+              <Flex align='center'>
+                <span
+                  role='status'
+                  aria-live='polite'
+                  className={
+                    test.kind === 'ok'
+                      ? 'text-sm text-success-text'
+                      : test.kind === 'error'
+                        ? 'text-sm text-error-text'
+                        : 'text-sm text-description'
+                  }
+                >
+                  {test.kind === 'ok' || test.kind === 'error' ? test.message : ''}
+                  {test.kind === 'pending' ? t('test.pending.message') : ''}
+                </span>
+              </Flex>
+            </Flex>
+          </Form.FieldSet>
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};
+
+CrxSettings.displayName = 'CrxSettings';

package/src/containers/CrxSettings/index.ts

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

package/src/containers/index.ts

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

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as CrxPlugin from './CrxPlugin.ts';
+export * from '#meta';
+export * from '#types';

package/src/mapping.test.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { PageAction } from '#types';
+
+import { toNote, toOrganization, toPerson } from './mapping.ts';
+
+const baseSource: PageAction.Source = {
+  url: 'https://www.linkedin.com/in/ricburdon',
+  title: 'Rich Burdon | LinkedIn',
+  clippedAt: '2026-04-23T12:00:00.000Z',
+};
+
+const baseSelection: PageAction.Selection = {
+  text: 'Rich Burdon\nFounder, DXOS\nBrooklyn, NY',
+};
+
+const makeSnapshot = (overrides: Partial<PageAction.Snapshot> = {}): PageAction.Snapshot => ({
+  source: baseSource,
+  selection: baseSelection,
+  ...overrides,
+});
+
+describe('mapping', () => {
+  test('Person prefers h1 for fullName', ({ expect }) => {
+    const person = toPerson(makeSnapshot({ hints: { h1: 'Rich Burdon', ogTitle: 'LinkedIn' } }));
+    expect(person.fullName).toBe('Rich Burdon');
+    expect(person.urls?.[0]?.value).toBe(baseSource.url);
+  });
+
+  test('Person falls back to og:title, then first line of text', ({ expect }) => {
+    const fromOg = toPerson(makeSnapshot({ hints: { ogTitle: 'Jane Doe' } }));
+    expect(fromOg.fullName).toBe('Jane Doe');
+
+    const fromText = toPerson(makeSnapshot({ hints: {} }));
+    expect(fromText.fullName).toBe('Rich Burdon');
+  });
+
+  test('Person allows empty name when no candidate is present', ({ expect }) => {
+    const person = toPerson(makeSnapshot({ hints: {}, selection: { text: '' } }));
+    expect(person.fullName).toBeUndefined();
+  });
+
+  test('Organization prefers og:title, then h1', ({ expect }) => {
+    const fromOg = toOrganization(makeSnapshot({ hints: { ogTitle: 'DXOS', h1: 'Ignored' } }));
+    expect(fromOg.name).toBe('DXOS');
+
+    const fromH1 = toOrganization(makeSnapshot({ hints: { h1: 'DXOS' } }));
+    expect(fromH1.name).toBe('DXOS');
+  });
+
+  test('Organization sets website from source URL and description from og:description', ({ expect }) => {
+    const org = toOrganization(
+      makeSnapshot({
+        source: { ...baseSource, url: 'https://example.com' },
+        hints: { ogTitle: 'Example', ogDescription: 'An example company.' },
+      }),
+    );
+    expect(org.website).toBe('https://example.com');
+    expect(org.description).toBe('An example company.');
+  });
+
+  test('Note prefers h1 for title, then og:title, then first line, then source title', ({ expect }) => {
+    const fromH1 = toNote(makeSnapshot({ hints: { h1: 'From H1', ogTitle: 'From OG' } }));
+    expect(fromH1.name).toBe('From H1');
+
+    const fromOg = toNote(makeSnapshot({ hints: { ogTitle: 'From OG' } }));
+    expect(fromOg.name).toBe('From OG');
+
+    const fromText = toNote(makeSnapshot({ hints: {} }));
+    expect(fromText.name).toBe('Rich Burdon');
+
+    const fromSource = toNote(makeSnapshot({ hints: {}, selection: { text: '' } }));
+    expect(fromSource.name).toBe(baseSource.title);
+  });
+
+  test('mappers tolerate a snapshot without selection', ({ expect }) => {
+    const person = toPerson(makeSnapshot({ selection: undefined, hints: {} }));
+    expect(person.fullName).toBeUndefined();
+
+    const note = toNote(makeSnapshot({ selection: undefined, hints: { h1: 'Title' } }));
+    expect(note.content.target?.content).toContain('# Title');
+  });
+});

package/src/mapping.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Markdown from '@dxos/plugin-markdown/Markdown';
+import { Organization, Person } from '@dxos/types';
+
+import { PageAction } from '#types';
+
+const MAX_NOTES_LENGTH = 4000;
+
+/**
+ * Maximum length of the markdown body we write for a Note. Larger than
+ * the embedded `notes` field on Person/Organization because a Markdown
+ * document is the whole content, not a secondary annotation.
+ */
+const MAX_NOTE_BODY_LENGTH = 50_000;
+
+const firstLine = (text: string | undefined): string | undefined => {
+  if (!text) {
+    return undefined;
+  }
+  const line = text
+    .split('\n')
+    .map((s) => s.trim())
+    .find((s) => s.length > 0);
+  return line && line.length > 0 ? line : undefined;
+};
+
+const truncate = (text: string | undefined, max: number): string | undefined => {
+  if (!text) {
+    return undefined;
+  }
+  return text.length > max ? text.slice(0, max) : text;
+};
+
+/**
+ * Best-effort mapping from an incoming page snapshot to a Person.
+ * Every field is optional on the schema, so an empty name is acceptable.
+ */
+export const toPerson = (snapshot: PageAction.Snapshot) => {
+  const hints = snapshot.hints ?? {};
+  const fullName = hints.h1 ?? hints.ogTitle ?? firstLine(snapshot.selection?.text);
+  return Person.make({
+    fullName,
+    image: hints.ogImage,
+    notes: truncate(snapshot.selection?.text, MAX_NOTES_LENGTH),
+    urls: [
+      {
+        label: snapshot.source.title || snapshot.source.url,
+        value: snapshot.source.url,
+      },
+    ],
+  });
+};
+
+/**
+ * Best-effort mapping from an incoming page snapshot to an Organization.
+ */
+export const toOrganization = (snapshot: PageAction.Snapshot) => {
+  const hints = snapshot.hints ?? {};
+  const name = hints.ogTitle ?? hints.h1 ?? firstLine(snapshot.selection?.text);
+  return Organization.make({
+    name,
+    description: hints.ogDescription ?? truncate(snapshot.selection?.text, MAX_NOTES_LENGTH),
+    image: hints.ogImage,
+    website: snapshot.source.url,
+  });
+};
+
+/**
+ * Best-effort mapping from an incoming page snapshot to a Markdown document.
+ *
+ * Builds a small prelude (title + source link + date) followed by the
+ * picked subtree's rendered text. We deliberately don't attempt HTML →
+ * Markdown conversion here — the picker's `innerText` already preserves
+ * paragraph structure, and a full converter belongs in the pipeline
+ * (where a future agent stage can take over) rather than baked into the
+ * receiver.
+ */
+export const toNote = (snapshot: PageAction.Snapshot) => {
+  const hints = snapshot.hints ?? {};
+  const title = hints.h1 ?? hints.ogTitle ?? firstLine(snapshot.selection?.text) ?? snapshot.source.title;
+  const body = truncate(snapshot.selection?.text, MAX_NOTE_BODY_LENGTH) ?? '';
+
+  const sourceLabel = snapshot.source.title || snapshot.source.url;
+  const clippedAt = snapshot.source.clippedAt;
+  const preludeLines = [
+    title ? `# ${title}` : undefined,
+    '',
+    `_Clipped from [${sourceLabel}](${snapshot.source.url}) on ${clippedAt}._`,
+    '',
+    body,
+  ].filter((line): line is string => line !== undefined);
+  const content = preludeLines.join('\n');
+
+  return Markdown.make({
+    name: title ?? undefined,
+    content,
+  });
+};

package/src/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Plugin from '@dxos/app-framework/Plugin';
+
+import config from '../dx.config.ts';
+
+export const meta = Plugin.getMetaFromConfig(config);

package/src/operations/add-note-from-snapshot.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+import * as SpaceOperation from '@dxos/plugin-space/SpaceOperation';
+
+import { CrxOperation } from '#types';
+
+import { toNote } from '../mapping.ts';
+
+const handler: Operation.WithHandler<typeof CrxOperation.AddNoteFromSnapshot> = CrxOperation.AddNoteFromSnapshot.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ snapshot, target }) {
+      const note = toNote(snapshot);
+      const { id } = yield* Operation.invoke(SpaceOperation.AddObject, { object: note }, { spaceId: target.spaceId });
+      return { id };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/add-organization-from-snapshot.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+import * as SpaceOperation from '@dxos/plugin-space/SpaceOperation';
+
+import { CrxOperation } from '#types';
+
+import { toOrganization } from '../mapping.ts';
+
+const handler: Operation.WithHandler<typeof CrxOperation.AddOrganizationFromSnapshot> =
+  CrxOperation.AddOrganizationFromSnapshot.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ snapshot, target }) {
+        const organization = toOrganization(snapshot);
+        const { id } = yield* Operation.invoke(
+          SpaceOperation.AddObject,
+          { object: organization },
+          { spaceId: target.spaceId },
+        );
+        return { id };
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/add-person-from-snapshot.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+import * as SpaceOperation from '@dxos/plugin-space/SpaceOperation';
+
+import { CrxOperation } from '#types';
+
+import { toPerson } from '../mapping.ts';
+
+const handler: Operation.WithHandler<typeof CrxOperation.AddPersonFromSnapshot> =
+  CrxOperation.AddPersonFromSnapshot.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ snapshot, target }) {
+        const person = toPerson(snapshot);
+        const { id } = yield* Operation.invoke(
+          SpaceOperation.AddObject,
+          { object: person },
+          { spaceId: target.spaceId },
+        );
+        return { id };
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Operation from '@dxos/compute/Operation';
+import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
+
+import { CrxOperation } from '#types';
+
+export const CrxOperationHandlerSet = OperationHandlerSet.lazy([
+  CrxOperation.AddPersonFromSnapshot.pipe(Operation.lazyHandler(() => import('./add-person-from-snapshot.ts'))),
+  CrxOperation.AddOrganizationFromSnapshot.pipe(
+    Operation.lazyHandler(() => import('./add-organization-from-snapshot.ts')),
+  ),
+  CrxOperation.AddNoteFromSnapshot.pipe(Operation.lazyHandler(() => import('./add-note-from-snapshot.ts'))),
+]);

package/src/page-actions.test.ts

@@ -0,0 +1,164 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Message, request } from '@dxos/crx-protocol';
+import { createMockPeer } from '@dxos/crx-protocol/testing';
+import { DXN } from '@dxos/keys';
+
+import { PageAction } from '#types';
+
+import { handleInvokeEvent, handleListEvent } from './page-actions.ts';
+
+const TestOp = Operation.make({
+  meta: { key: DXN.make('com.example.operation.test.pageAction'), name: 'Test' },
+  input: Schema.Struct({ snapshot: PageAction.Snapshot, target: Schema.Any }),
+  output: Schema.Struct({ id: Schema.String }),
+});
+
+const action: PageAction.PageAction = {
+  id: 'org.dxos.test/page-action/test',
+  label: 'Test',
+  icon: 'ph--bookmark-simple--regular',
+  urlPatterns: ['https://*/*'],
+  extractor: { name: 'snapshot' },
+  contexts: ['popup'],
+  operation: TestOp,
+};
+
+const snapshot = {
+  source: { url: 'https://example.com', title: 'Example', clippedAt: '2026-06-09T00:00:00Z' },
+};
+
+const invokeRequest = {
+  version: 1,
+  id: 'req-1',
+  actionId: action.id,
+  page: { url: 'https://example.com', title: 'Example' },
+  inputs: snapshot,
+  invokedFrom: 'popup',
+};
+
+const deps = (overrides: Partial<Parameters<typeof handleInvokeEvent>[1]> = {}) => ({
+  getActions: () => [action],
+  getSettings: () => ({}),
+  getTarget: () => ({}) as any, // Stub database; never dereferenced by the handler.
+  invoke: async () => ({ data: { id: 'obj-1' }, error: undefined }),
+  ...overrides,
+});
+
+describe('page-actions', () => {
+  test('list returns serializable descriptors', ({ expect }) => {
+    const ack = handleListEvent({ version: 1, id: 'list-1' }, () => [action]);
+    expect(ack).toEqual({
+      version: 1,
+      id: 'list-1',
+      ok: true,
+      actions: [{ ...action, operation: TestOp.meta.key.toString() }],
+    });
+  });
+
+  test('list rejects malformed request', ({ expect }) => {
+    const ack = handleListEvent({ nope: true }, () => [action]);
+    expect(ack.ok).toBe(false);
+  });
+
+  test('invoke happy path returns objectId', async ({ expect }) => {
+    const ack = await handleInvokeEvent(invokeRequest, deps());
+    expect(ack).toEqual({ version: 1, id: 'req-1', ok: true, objectId: 'obj-1' });
+  });
+
+  test('invoke is ignored when extension actions are disabled', async ({ expect }) => {
+    let invoked = false;
+    const ack = await handleInvokeEvent(
+      invokeRequest,
+      deps({
+        getSettings: () => ({ enabled: false }),
+        invoke: async () => {
+          invoked = true;
+          return { data: { id: 'obj-1' }, error: undefined };
+        },
+      }),
+    );
+    expect(ack).toEqual({ version: 1, id: 'req-1', ok: false, error: 'disabled' });
+    expect(invoked).toBe(false);
+  });
+
+  test('invoke honors an explicit enabled=true', async ({ expect }) => {
+    const ack = await handleInvokeEvent(invokeRequest, deps({ getSettings: () => ({ enabled: true }) }));
+    expect(ack).toMatchObject({ ok: true, objectId: 'obj-1' });
+  });
+
+  test('invoke rejects unsupported version', async ({ expect }) => {
+    const ack = await handleInvokeEvent({ ...invokeRequest, version: 2 }, deps());
+    expect(ack).toMatchObject({ ok: false, error: 'unsupportedVersion' });
+  });
+
+  test('invoke rejects unknown action', async ({ expect }) => {
+    const ack = await handleInvokeEvent({ ...invokeRequest, actionId: 'nope' }, deps());
+    expect(ack).toMatchObject({ ok: false, error: 'unknownAction' });
+  });
+
+  test('invoke maps missing space to noSpace', async ({ expect }) => {
+    const ack = await handleInvokeEvent(invokeRequest, deps({ getTarget: () => undefined }));
+    expect(ack).toMatchObject({ ok: false, error: 'noSpace' });
+  });
+
+  test('invoke maps operation error to operationFailed', async ({ expect }) => {
+    const ack = await handleInvokeEvent(
+      invokeRequest,
+      deps({ invoke: async () => ({ data: undefined, error: new Error('boom') }) }),
+    );
+    expect(ack).toMatchObject({ ok: false, error: 'operationFailed' });
+  });
+
+  test('invoke echoes request id when payload is invalid', async ({ expect }) => {
+    const { page: _page, ...withoutPage } = invokeRequest;
+    const ack = await handleInvokeEvent(withoutPage, deps());
+    expect(ack).toEqual({ version: 1, id: 'req-1', ok: false, error: 'invalidPayload' });
+  });
+
+  test('invoke maps a rejecting operation to operationFailed', async ({ expect }) => {
+    const ack = await handleInvokeEvent(
+      invokeRequest,
+      deps({
+        invoke: async () => {
+          throw new Error('boom');
+        },
+      }),
+    );
+    expect(ack).toMatchObject({ ok: false, error: 'operationFailed' });
+  });
+
+  test('invoke accepts picker-originated requests', async ({ expect }) => {
+    const ack = await handleInvokeEvent({ ...invokeRequest, invokedFrom: 'picker' }, deps());
+    expect(ack).toEqual({ version: 1, id: 'req-1', ok: true, objectId: 'obj-1' });
+  });
+
+  test('list serializes picker contexts', ({ expect }) => {
+    const pickerAction: PageAction.PageAction = { ...action, contexts: ['picker'] };
+    const ack = handleListEvent({ version: 1, id: 'list-2' }, () => [pickerAction]);
+    expect(ack.ok).toBe(true);
+    expect(ack.ok && ack.actions[0].contexts).toEqual(['picker']);
+  });
+});
+
+describe('page-actions over the mock protocol peer', () => {
+  test('a list request is answered by the real handler', async ({ expect }) => {
+    const { extension, composer } = createMockPeer();
+    composer.handle((message) => {
+      if (message._tag === 'page-actions.list') {
+        const ack = handleListEvent({ version: 1, id: message.id }, () => []);
+        return ack.ok
+          ? Message.make('page-actions.list-ack', { id: ack.id, ok: true, actions: ack.actions })
+          : Message.make('page-actions.list-ack', { id: ack.id, ok: false, error: ack.error });
+      }
+    });
+    const reply = await request(extension, Message.make('page-actions.list', { id: 'r1' }));
+    expect(reply).toMatchObject({ _tag: 'page-actions.list-ack', id: 'r1', ok: true });
+  });
+});