@dxos/plugin-crx 0.0.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 DXOS
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/PLUGIN.mdl

@@ -0,0 +1,599 @@
+---
+id: org.dxos.plugin.crx
+name: CrxPlugin
+version: 0.3.0
+---
+
+Coordinates with the `@dxos/composer-crx` browser extension. Owns the Composer
+side of the page-actions bridge: plugins contribute page actions (serializable
+descriptor + target operation) under a plugin-scoped capability; the extension
+caches the descriptors in its registry and invokes them over same-origin
+`window` `CustomEvent`s. This plugin answers registry-list requests, validates
+invoke requests, resolves the active space, executes the target operation, and
+surfaces outcomes as toasts. It also contributes three picker actions
+(Person, Organization, Note) whose operations map a page snapshot to an ECHO
+object, and owns the user-facing settings surface — including the render-proxy
+settings (absorbed from the retired plugin-extension) for the extension's
+page-rendering facility.
+
+The extension owns the DOM picker, popup toolbar, extractors, and bridge
+sender; this plugin owns envelope validation, snapshot → ECHO object mapping,
+and user feedback (toast). The extension keeps a hand-validated mirror of the
+wire types at `packages/apps/composer-crx/src/page-actions/types.ts` which
+must be updated in lockstep.
+
+## Extensions
+
+The following extension dialects are used in this document.
+Each extension is defined in the Appendix or resolved via its URI.
+
+| Term   | URI                            |
+|--------|--------------------------------|
+| `type` | `org.dxos.mdl.type@1.0`        |
+| `feat` | `org.dxos.mdl.feat@1.0`        |
+| `scenario` | `org.dxos.mdl.scenario@1.0`    |
+| `test` | `org.dxos.mdl.test@1.0`        |
+
+## Types
+
+```mdl
+type Settings
+  desc: |
+    User preferences for extension ↔ Composer coordination, persisted via the
+    app-framework settings store. Only user-set values are stored; defaults
+    are applied by consumers when reading the atom. All fields are optional.
+    The fields are a configuration surface; enforcement is owned by whichever
+    consumer reads the atom.
+  fields:
+    enabled?: boolean             # default: true. "Accept extension actions" preference.
+    autoOpenAfterClip?: boolean   # default: false. "Open after action" preference.
+    renderProxyEnabled?: boolean  # default: true. "Use extension to render pages" preference.
+    renderTimeout?: number        # default: 20000. Max ms to wait for a render.
+    renderActiveTab?: boolean     # default: false. Render in a focused tab.
+    developerMode?: boolean       # default: false. Verbose logging / previews.
+```
+
+```mdl
+type Source
+  fields:
+    url: string
+    title: string
+    favicon?: string
+    clippedAt: string           # ISO timestamp
+```
+
+```mdl
+type Selection
+  fields:
+    text: string                # innerText of the picked subtree
+    html?: string               # outerHTML, possibly truncated
+    htmlTruncated?: boolean
+    rect?: { x: number, y: number, width: number, height: number }
+```
+
+```mdl
+type Hints
+  desc: |
+    Cheap signals harvested from the whole page at capture time. The mappings
+    use a subset (h1, og:title, og:description, og:image) as fallbacks; a
+    future agent stage may interpret all of them.
+  fields:
+    ogTitle?: string
+    ogDescription?: string
+    ogImage?: string
+    jsonLd?: unknown[]
+    h1?: string
+    firstImage?: string
+```
+
+```mdl
+type Snapshot
+  desc: |
+    Generic page capture produced by the extension's `snapshot` extractor.
+    Travels as the `inputs` of an invoke request.
+  fields:
+    source: Source
+    selection?: Selection
+    hints?: Hints
+    imageData?: string          # downscaled primary-image thumbnail (data URL),
+                                # captured by the extension's background worker
+    html?: string
+    htmlTruncated?: boolean
+```
+
+```mdl
+type PageActionDescriptor
+  desc: |
+    Serializable descriptor for a plugin-contributed page action, synced to
+    the extension's registry cache. Invocation is correlated by `id`.
+  fields:
+    id: string                  # stable plugin-scoped action id
+    label: string               # human-readable action name
+    icon: string                # phosphor icon identifier
+    urlPatterns: string[]       # match patterns the action applies to
+    predicate?: { exists: string }  # lazy DOM condition (CSS selector)
+    extractor: { name: string, params?: unknown }  # extension-bundled extractor
+    contexts: string[]          # surfaces: popup | page | selection | link | picker
+    operation: string           # operation key, display/diagnostics only
+```
+
+```mdl
+type PageAction
+  desc: |
+    A live page-action contribution: the descriptor fields plus the actual
+    operation definition (serialized to its key string when listed). The
+    target operation must accept `{ snapshot: Snapshot, target: Database }`
+    and return `{ id: string }`.
+```
+
+```mdl
+type ListRequest
+  desc: |
+    Sent by the extension as `composer:page-actions:list`; acked as
+    `composer:page-actions:list:ack`.
+  fields:
+    version: number             # runtime check: only 1 is supported
+    id: string                  # correlation id, echoed in the ack
+```
+
+```mdl
+type ListAck
+  fields:
+    version: number             # always 1
+    id: string
+    ok: boolean
+    actions?: PageActionDescriptor[]  # when ok = true
+    error?: string              # stable error code when ok = false
+```
+
+```mdl
+type InvokeRequest
+  desc: |
+    Sent by the extension as `composer:page-action:invoke`; acked as
+    `composer:page-action:invoke:ack`. Decoded in two passes: a loose
+    envelope ({ version, id? }) first, so newer versions yield
+    `unsupportedVersion` rather than the generic `invalidPayload` and
+    malformed payloads can still echo the request id.
+  fields:
+    version: number             # runtime check: only 1 is supported
+    id: string                  # correlation id, echoed in the ack
+    actionId: string            # id of the registered action to invoke
+    page: { url: string, title: string, favicon?: string }
+    inputs: unknown             # extractor output; `snapshot` yields Snapshot
+    invokedFrom: popup | contextMenu | picker
+```
+
+```mdl
+type InvokeAck
+  fields:
+    version: number             # always 1
+    id: string
+    ok: boolean
+    objectId?: string           # ID of the created object when ok = true
+    error?: string              # stable error code when ok = false:
+                                #   invalidPayload | unsupportedVersion |
+                                #   unknownAction | noSpace | operationFailed
+```
+
+## Features
+
+```mdl
+feat F-1: Settings Capability
+
+  req F-1.1:
+    when: plugin is activated
+    then: |
+      a single `Settings` atom is registered under a plugin-scoped capability
+      and contributed to `AppCapabilities.Settings` so the standard settings
+      UI surfaces it.
+
+  req F-1.2:
+    when: another plugin reads the capability
+    then: it receives the current Settings with defaults applied
+```
+
+```mdl
+feat F-2: Settings Surface
+
+  req F-2.1:
+    when: the app-framework settings panel renders the CRX section
+    then: |
+      a schema-driven form is shown covering all Settings fields, wired to
+      the Settings atom and persisted on change.
+
+  req F-2.2:
+    when: the user presses the Test connection button
+    then: |
+      a ping round-trips over the page → content-script → background path and
+      reports the extension's name and version on success, or the failure
+      reason otherwise.
+```
+
+```mdl
+feat F-2c: Settings Enforcement
+
+  req F-2c.1:
+    when: `enabled` is false and a page-action invoke arrives
+    then: |
+      no object is created; the request is still acked (so the extension does
+      not time out) with the stable error code `disabled`
+
+  req F-2c.2:
+    when: `autoOpenAfterClip` is true and a page action succeeds
+    then: the created object is opened via LayoutOperation.Open
+
+  req F-2c.3:
+    when: `autoOpenAfterClip` is false (default)
+    then: focus is not moved; only the success toast is shown
+```
+
+```mdl
+feat F-3: Page Action Contributions
+  desc: |
+    Plugins contribute `PageAction[]` under the plugin-scoped
+    `CrxCapabilities.PageAction` capability. Other plugins contribute their
+    own actions the same way (e.g. plugin-bookmarks contributes
+    "Add bookmark").
+
+  req F-3.1:
+    when: plugin is activated
+    then: |
+      three picker-only actions are contributed — Person, Organization, and
+      Note — each matching `http(s)://*/*`, using the extension-bundled
+      `snapshot` extractor, and targeting the corresponding
+      AddPersonFromSnapshot / AddOrganizationFromSnapshot /
+      AddNoteFromSnapshot operation.
+
+  req F-3.2:
+    when: the extension lists actions
+    then: |
+      contributions are resolved per-request, so actions from
+      late-activating plugins are included.
+```
+
+```mdl
+feat F-4: Registry Listing
+
+  req F-4.1:
+    when: plugin is activated
+    then: |
+      window event listeners for `composer:page-actions:list` and
+      `composer:page-action:invoke` are installed, and a
+      `composer:page-actions:ready` event is dispatched so the extension
+      relay can refresh its registry even when Composer boots after the
+      content script has already installed.
+
+  req F-4.2:
+    when: a valid list request arrives
+    then: |
+      the ack carries the currently contributed actions as serializable
+      descriptors, with `operation` serialized to the operation's key string.
+
+  req F-4.3:
+    when: a list request fails schema decoding
+    then: |
+      the ack is { ok: false, error: 'invalidPayload' } with a best-effort
+      echo of the request id so the extension can correlate the failure.
+```
+
+```mdl
+feat F-5: Invoke Validation & Dispatch
+
+  req F-5.1:
+    when: an invoke request's envelope fails decoding
+    then: ack is { ok: false, error: 'invalidPayload' } and nothing is invoked
+
+  req F-5.2:
+    when: the envelope has a version other than 1
+    then: |
+      ack is { ok: false, error: 'unsupportedVersion' } with the request id
+      echoed when present.
+
+  req F-5.3:
+    when: the strict payload fails decoding
+    then: ack is { ok: false, error: 'invalidPayload' }
+
+  req F-5.4:
+    when: `actionId` matches no registered action
+    then: ack is { ok: false, error: 'unknownAction' }
+
+  req F-5.5:
+    when: the active space cannot be determined
+    then: nothing is invoked; ack is { ok: false, error: 'noSpace' }
+
+  req F-5.6:
+    when: the request resolves to an action and an active space
+    then: |
+      the action's operation is invoked with
+      { snapshot: inputs, target: activeSpace.db }; on success the ack is
+      { ok: true, objectId } carrying the created object's id.
+
+  req F-5.7:
+    when: the operation returns an error or throws
+    then: ack is { ok: false, error: 'operationFailed' }
+```
+
+```mdl
+feat F-6: Snapshot → Object Mapping
+  desc: |
+    Each contributed operation maps a Snapshot to an ECHO object and adds it
+    to the target database via SpaceOperation.AddObject.
+
+  req F-6.1:
+    when: AddPersonFromSnapshot is invoked
+    then: |
+      a Person is created with best-effort fields:
+        fullName  ← hints.h1 ?? hints.ogTitle ?? firstLine(selection.text)
+        image     ← hints.ogImage
+        notes     ← selection.text (truncated to 4000 chars)
+        urls      ← [{ label: source.title || source.url, value: source.url }]
+
+  req F-6.2:
+    when: AddOrganizationFromSnapshot is invoked
+    then: |
+      an Organization is created with best-effort fields:
+        name        ← hints.ogTitle ?? hints.h1 ?? firstLine(selection.text)
+        description ← hints.ogDescription ?? selection.text (truncated)
+        image       ← hints.ogImage
+        website     ← source.url
+
+  req F-6.3:
+    when: AddNoteFromSnapshot is invoked
+    then: |
+      a Markdown document is created with a small prelude (title, source
+      link, timestamp) followed by the selection's rendered text (truncated
+      to 50000 chars). The title falls back through
+      hints.h1 ?? hints.ogTitle ?? firstLine(selection.text) ?? source.title.
+
+  req F-6.4:
+    when: there is no name/title candidate
+    then: the object is still created; empty name is acceptable
+```
+
+```mdl
+feat F-7: User Feedback
+
+  req F-7.1:
+    when: an invoke ack is produced with ok = true
+    then: a success toast is shown
+
+  req F-7.2:
+    when: an invoke ack is produced with ok = false
+    then: an error toast is shown naming the stable error code
+```
+
+```mdl
+feat F-8: Page Actions Registry & Invocation
+  desc: |
+    Plugins contribute page actions (serializable descriptor + target
+    operation) under a plugin-scoped capability. This plugin answers the
+    extension's registry-list requests (`composer:page-actions:list`) with
+    descriptors and executes invoke requests (`composer:page-action:invoke`)
+    by resolving the active space and invoking the target operation with
+    `{ snapshot, target }`. Every request is acked with stable error codes
+    (invalidPayload, unsupportedVersion, disabled, unknownAction, noSpace,
+    operationFailed); outcomes surface as toasts.
+```
+
+## Acceptance
+
+```mdl
+scenario T-1: Settings atom registered
+  given: plugin activated
+  then:
+    - the Settings capability is available via Capability.get
+    - the default atom value is { enabled: true, autoOpenAfterClip: false,
+      renderProxyEnabled: true, renderTimeout: 20000, renderActiveTab: false,
+      developerMode: false }
+```
+
+```mdl
+scenario T-2: Toggling enabled persists
+  given: settings surface rendered
+  when: user toggles the `enabled` switch off
+  then: subsequent reads of the atom observe enabled === false
+```
+
+```mdl
+scenario T-3: List request returns descriptors
+  given: contributed picker actions (Person, Organization, Note)
+  when: handleListEvent receives { version: 1, id: 'r1' }
+  then:
+    - ack is { ok: true, id: 'r1' }
+    - ack.actions contains one descriptor per action with `operation`
+      serialized to the operation key string
+```
+
+```mdl
+scenario T-4: Invalid list request is rejected
+  given: page-actions listeners installed
+  when: handleListEvent receives a malformed detail (missing id)
+  then: ack is { ok: false, error: 'invalidPayload' }
+```
+
+```mdl
+scenario T-5: Valid person invoke creates Person
+  given: a registered add-person action and an active space
+  when: |
+    handleInvokeEvent receives { version: 1, actionId: <add-person>,
+    inputs: snapshot } with snapshot.hints.h1 = 'Jane Doe'
+  then:
+    - a Person is created with fullName = 'Jane Doe'
+    - ack is { ok: true, objectId: <non-empty> }
+    - a success toast is shown
+```
+
+```mdl
+scenario T-6: Organization mapping falls back to og:title
+  given: a snapshot with hints.ogTitle = 'DXOS' and hints.h1 undefined
+  when: AddOrganizationFromSnapshot is invoked
+  then:
+    - Organization.name === 'DXOS'
+    - Organization.website === source.url
+```
+
+```mdl
+scenario T-7: Missing name is allowed
+  given: a snapshot with no hints and empty selection text
+  when: the add-person action is invoked
+  then:
+    - a Person is created (empty fullName)
+    - ack is { ok: true, objectId: <non-empty> }
+```
+
+```mdl
+scenario T-8: Unsupported envelope version
+  given: page-actions listeners installed
+  when: handleInvokeEvent receives { version: 2, id: 'r2', ... }
+  then:
+    - nothing is invoked
+    - ack is { ok: false, id: 'r2', error: 'unsupportedVersion' }
+```
+
+```mdl
+scenario T-9: Invalid invoke payload is rejected
+  given: page-actions listeners installed
+  when: handleInvokeEvent receives a version-1 detail missing `actionId`
+  then:
+    - nothing is invoked
+    - ack is { ok: false, error: 'invalidPayload' } with the envelope id echoed
+```
+
+```mdl
+scenario T-10: Unknown action
+  given: no action registered with id 'nope'
+  when: handleInvokeEvent receives a valid request with actionId = 'nope'
+  then: ack is { ok: false, error: 'unknownAction' }
+```
+
+```mdl
+scenario T-11: No active space
+  given: the active space cannot be resolved
+  when: a valid invoke request arrives
+  then:
+    - nothing is invoked
+    - ack is { ok: false, error: 'noSpace' }
+```
+
+```mdl
+scenario T-12: Operation failure
+  given: the target operation returns an error (or throws)
+  when: a valid invoke request arrives
+  then:
+    - ack is { ok: false, error: 'operationFailed' }
+    - an error toast is shown
+```
+
+---
+
+## QA
+
+Executable tests. Each step carries a human instruction (`do`) and, where the step maps to an
+invocable operation, an agent binding (`invoke`). Report failures by test and step number.
+
+Note: this document declares no `op` blocks, so the operations below are referenced by their full
+runtime key rather than `[op:...]` — see `src/types/CrxOperation.ts`.
+
+```mdl
+test QA-1: Add a Person from a page snapshot
+  desc: |
+    The core snapshot → object mapping (F-6.1), standing in for the browser extension's picker,
+    which an agent cannot drive — the extension is a separate, unautomatable browser process. This
+    test invokes the target operation directly with a synthetic snapshot, exactly as the plugin's
+    own invoke handler does after resolving `{ snapshot, target }` (F-5.6).
+  actors: agent
+  covers: [F-3.1, F-5.6, F-6.1, T-5]
+  status: unverified
+  given:
+    - an identity exists
+    - space: a space is open
+    - plugin-crx is enabled — it is OFF by default (not in `getDefaults` and not in the dev-only
+      default set; see `packages/apps/composer-app/src/plugin-defs.tsx`)
+    - no Person named "QA Snapshot Person" exists — ABORT rather than reusing one this test did
+      not create
+  steps:
+    - name: Add the person from a snapshot
+      do: |
+        (Real path, not automatable here: with the extension installed, open the popup on a page
+        and choose the "Person" picker action, then select the page region to capture.)
+      invoke: |
+        org.dxos.operation.crx.addPersonFromSnapshot {
+          snapshot: { source: { url: "https://example.com/qa", title: "QA Page", clippedAt: "2026-08-27T00:00:00.000Z" },
+                      hints: { h1: "QA Snapshot Person" } },
+          target: $given.space.db
+        }
+      capture: created
+      expect: a Person named "QA Snapshot Person" now exists in the space
+      assert: return !!$created.id
+  after:
+    - name: Delete the Person
+      do: Right-click "QA Snapshot Person" in the navtree and choose Delete.
+      invoke: org.dxos.operation.space.removeObjects { objects: [{ "/": "echo://$given.space.id/" + $created.id }], target: $given.space }
+      expect: the row leaves the navtree
+      note: |
+        `addPersonFromSnapshot` returns a bare `id`, not a live ref, so the DXN envelope is built
+        by hand for the removal call — see Rule 4 in `op@1.1`'s parent doc about resolving by the
+        invoker path rather than guessing a shortcut.
+```
+
+```mdl
+test QA-2: Accept-extension-actions toggle gates invocation
+  desc: |
+    The settings enforcement path (F-2c.1) — no operation exists for the settings atom itself
+    (it is a plain app-framework settings store), so this step is human-only.
+  actors: human
+  covers: [F-1.1, F-2.1, F-2c.1]
+  status: unverified
+  given:
+    - an identity exists
+    - plugin-crx is enabled — it is OFF by default (see QA-1)
+    - the Settings panel's CRX section is reachable
+  steps:
+    - name: Disable "Accept extension actions"
+      do: Open Settings, find the CRX section, and toggle "Accept extension actions" off.
+      expect: the toggle shows off and the preference persists across a reload
+      note: |
+        NO `invoke` — the Settings atom has no operation binding; per F-2c.1, an invoke request
+        that arrives while this is off is still acked (error `disabled`), which requires the
+        extension itself to exercise and cannot be driven from the debug port alone.
+  after:
+    - name: Re-enable "Accept extension actions"
+      do: Toggle "Accept extension actions" back on.
+      expect: the toggle shows on again
+```
+
+---
+
+## Appendix: Extension Definitions
+
+```mdl
+ext type
+  uri: org.dxos.mdl.type@1.0
+  desc: A named data structure with typed fields and optional literals.
+  fields:
+    desc?: Prose
+    fields?: FieldMap
+    literals?: UnionList
+    extends?: TypeRef[]
+```
+
+```mdl
+ext feat
+  uri: org.dxos.mdl.feat@1.0
+  desc: A named feature grouping one or more requirements.
+  fields:
+    desc?: Prose
+    req: RequirementList
+  nesting: self
+```
+
+```mdl
+ext scenario
+  uri: org.dxos.mdl.scenario@1.0
+  desc: An acceptance scenario expressed as given / when / then steps.
+  fields:
+    given?: Step | Step[]
+    when?: Step | Step[]
+    then: Step | Step[]
+    tags?: TagList
+```