@dxos/app-framework 0.9.1-main.c7dcc2e112 → 0.10.0

package/docs/registry-spec.md

@@ -31,13 +31,13 @@ and will be renamed to a final namespace before promotion (see [Versioning](#ver
 
 The machine-readable lexicons are the canonical definition:
 
-- **Lexicon JSON** — `packages/sdk/edge-protocol/lexicons/org.dxos.experimental/*.json` (edge repo).
+- **Lexicon JSON** — `packages/core/protocols/src/lexicons/org.dxos.experimental/*.json` (dxos repo).
   These are the source of truth.
-- **Effect-Schema validators** — `packages/sdk/edge-protocol/src/registry.ts`
-  (edge repo). Decoders used at the indexing/validation seam to reject malformed records before they
-  enter the store. These mirror the JSON lexicons and live alongside them in the protocol package.
-- **`PluginView`** — `packages/core/protocols/src/edge/registry.ts` (dxos repo). The catalog shape
-  the indexer serves to Composer.
+- **`PluginView` + view schemas** — `packages/core/protocols/src/edge/registry.ts` (dxos repo). The
+  catalog shape the indexer serves to Composer, plus the shared profile/release view schemas.
+- **Effect-Schema validators** — `packages/services/registry-service/src/registry/atproto/schema.ts`
+  (edge repo). Indexer-side decoders that extend the view schemas with the raw ATProto record fields
+  (`pluginKey`, `manifestHash`), used to reject malformed records before they enter the store.
 - **CLI writers** — `packages/plugins/plugin-registry/src/commands/registry/` (dxos repo). The `dx`
   CLI assembles record bodies and writes them via XRPC.
 - **App-view / indexer** — `packages/services/registry-service/src/registry/atproto/{indexer,curator,backfill}.ts`
@@ -59,7 +59,7 @@ The machine-readable lexicons are the canonical definition:
                                    └─────────────┘
 ```
 
-1. A publisher writes `package.profile` / `package.release` records (and a one-time
+1. A publisher writes `plugin.profile` / `plugin.release` records (and a one-time
    `publisher.profile`) to their own PDS using the `dx` CLI.
 2. A verifier writes `publisher.verification` records, one per trusted DID, to their own PDS.
 3. The indexer learns the verified-DID set, then ingests matching records from verified publishers —
@@ -73,8 +73,8 @@ The machine-readable lexicons are the canonical definition:
 | ---------------------------------------------- | ----------------- | --------- | -------------------------------------- |
 | `org.dxos.experimental.publisher.profile`      | `self`            | publisher | Identity-level publisher metadata.     |
 | `org.dxos.experimental.publisher.verification` | `<verified DID>`  | verifier  | A trust attestation about a publisher. |
-| `org.dxos.experimental.package.profile`        | `<key>`           | publisher | Plugin metadata (one per key per DID). |
-| `org.dxos.experimental.package.release`        | `<key>:<version>` | publisher | A versioned artifact of a package.     |
+| `org.dxos.experimental.plugin.profile`         | `<key>`           | publisher | Plugin metadata (one per key per DID). |
+| `org.dxos.experimental.plugin.release`         | `<key>:<version>` | publisher | A versioned artifact of a plugin.      |
 
 All record bodies carry a `$type` field set to the NSID (standard ATProto convention; stamped by
 the CLI on write). All records live in the author's own repo and are therefore mutable by that
@@ -111,7 +111,7 @@ policy applied at indexing time, not a write-time restriction (see [Trust model]
 
 Written by `dx registry verify`.
 
-### `package.profile`
+### `plugin.profile`
 
 Mutable metadata for a discoverable plugin. `rkey = <key>` (reverse-domain NSID, e.g.
 `org.dxos.plugin.excalidraw`). The `key` field is the plugin's globally-unique identifier and
@@ -134,16 +134,16 @@ matches the `key` in `dx.config.ts`.
 Written by `dx registry publish` (from the manifest emitted by `composerPlugin` reading `dx.config.ts`)
 or `dx registry publish-package`.
 
-### `package.release`
+### `plugin.release`
 
-A record for one version of a package. `rkey = <key>:<version>`. Conceptually append-only: a new
+A record for one version of a plugin. `rkey = <key>:<version>`. Conceptually append-only: a new
 version is a new record, and the registry treats the first release seen per `(did, key, version)`
 as canonical — but the author technically retains write access to it (see
 [Integrity & tamper detection](#integrity--tamper-detection)).
 
 | Field          | Required | Type              | Constraints | Notes                                                                                                             |
 | -------------- | -------- | ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
-| `package`      | yes      | string            | ≤63 chars   | Key of the parent `package.profile` authored by the same DID.                                                     |
+| `pluginKey`    | yes      | string            | ≤63 chars   | Key of the parent `plugin.profile` authored by the same DID.                                                      |
 | `version`      | yes      | string            | ≤32 chars   | Semver subset without build metadata; pre-release suffixes allowed (`1.2.3-rc.1`). Taken from `package.json`.     |
 | `moduleUrl`    | yes      | string (uri)      | non-empty   | HTTPS URL of the module entrypoint / `manifest.json`. v0 trusts the publisher; content addressing is a follow-on. |
 | `manifestHash` | no       | string            | ≤256 chars  | Integrity hash of the module manifest, e.g. `sha256-<base64>`.                                                    |
@@ -162,7 +162,7 @@ makes the catalog trustworthy is the **indexing policy**, not a write gate:
 
 - **Today (single verifier).** The indexer is configured with one trusted verifier DID
   (`REGISTRY_CURATOR_DID`) and honors `publisher.verification` records **only** from that DID. The
-  verified-DID set is the set of `subject`s across that verifier's records. A `package.*` or
+  verified-DID set is the set of `subject`s across that verifier's records. A `plugin.*` or
   `publisher.profile` record is indexed only if its author DID is in the verified set. This is a
   deliberate moderation simplification while the registry is young — not a protocol restriction.
 - **Revocation.** Deleting the verification record removes the publisher from the verified set on the
@@ -179,7 +179,7 @@ until a trusted verifier vouches for them.
 ## Integrity & tamper detection
 
 Immutability is an **app-view guarantee, not an AT Protocol one.** Like every AT Protocol repo, a
-publisher owns their PDS records and can mutate or delete any of them — including `package.release` —
+publisher owns their PDS records and can mutate or delete any of them — including `plugin.release` —
 and no protocol mechanism makes a record cryptographically immutable. Enforcement therefore lives at
 the **registry app-view** (the edge service that indexes the firehose and serves the catalog to
 Composer): the PDS is the mutable source, and the app-view is the canonical, immutable view of what
@@ -199,7 +199,7 @@ What the app-view enforces:
 
 What stays mutable (the AT Protocol layer):
 
-- The PDS `package.release` record is written with `putRecord` (upsert), and the publisher can change
+- The PDS `plugin.release` record is written with `putRecord` (upsert), and the publisher can change
   its `moduleUrl` / `manifestHash` at will. That is fine — the app-view's pin means such a change is not
   re-served (the PDS is the mutable source; the app-view is the canonical view).
 
@@ -217,9 +217,9 @@ publisher-trusted at the record level (the hosted bundle itself is already immut
 
 - **Bootstrap / backfill.** On first run (and periodically), the indexer walks the verifier's repo
   for verification records to compute the verified-DID set, then lists each verified publisher's repo
-  for `package.*` records (`runBackfill`). The catalog (`GET /registry/plugins`) collects releases
-  per `(authorDid, package-key)` — grouped by the release's `package` field, **not** by parsing the
-  rkey — newest-first, anchored by `at://<authorDid>/org.dxos.experimental.package.profile/<key>`.
+  for `plugin.*` records (`runBackfill`). The catalog (`GET /registry/plugins`) collects releases
+  per `(authorDid, pluginKey)` — grouped by the release's `pluginKey` field, **not** by parsing the
+  rkey — newest-first, anchored by `at://<authorDid>/org.dxos.experimental.plugin.profile/<key>`.
 - **Live updates.** The indexer subscribes to the Jetstream firehose; commits for the four NSIDs are
   validated (Effect-Schema) and written/deleted in DO storage, keyed by `record:<nsid>|<did>|<rkey>`.
 - **Validation seam.** Malformed records are rejected at ingestion against the Effect-Schema mirrors
@@ -257,7 +257,7 @@ works if it was built against an SDK compatible with what Composer ships. DXOS s
 **Mechanism — the manifest dependency snapshot.** The build (`composerPlugin`) auto-populates a
 `dependencies` map into the plugin's `manifest.json`: every declared dependency resolved to its
 concrete installed version (`{ "@dxos/app-framework": "0.8.3", "react": "19.2.0", … }`). This flows
-into the `package.release` record and the catalog (`PluginRelease.dependencies`). The host computes
+into the `plugin.release` record and the catalog (`PluginRelease.dependencies`). The host computes
 compatibility from the **subset it shares with the plugin** — the externalized `@dxos/*` packages —
 comparing each against its own shipped version under a policy (pre-1.0: **same minor**; post-1.0:
 caret). The remaining (bundled) deps are recorded for transparency/audit. A release with no
@@ -296,9 +296,9 @@ runtime sandbox surface is defined. (rkey conventions now match emdash, includin
 ## Schema reconciliation
 
 The JSON lexicons, the Effect-Schema validators, `PluginView`, and the CLI previously had field-level
-drift on `package.profile`. All items listed here are resolved.
+drift on `plugin.profile`. All items listed here are resolved.
 
-- **`slug` → `key`** — the identity field on `package.profile` is now named `key` everywhere: the
+- **`slug` → `key`** — the identity field on `plugin.profile` is now named `key` everywhere: the
   lexicon, the Effect-Schema validator, `PluginProfileSchema` in `@dxos/protocols`, the CLI flags
   (`--key`), and the runtime `Plugin.Meta.profile.key`.
 - **`homepage` → `homePage`** — camelCase alignment across the lexicon, validator, `PluginProfileSchema`,
@@ -308,12 +308,12 @@ drift on `package.profile`. All items listed here are resolved.
 - **`screenshots`** — unified as `{ light?, dark? }[]` (object-only form) across `dx.config.ts`,
   `PluginProfileSchema`, the validator, and the indexer projection. Plain URL strings are no longer
   accepted at authoring time; use `{ dark: 'url' }` or `{ light: 'url', dark: 'url' }`.
-- **`dependsOn`** — added to `package.profile` (author-declared runtime plugin deps, NSIDs),
+- **`dependsOn`** — added to `plugin.profile` (author-declared runtime plugin deps, NSIDs),
   `PluginProfileSchema`, the validator, and `dx.config.ts`.
-- **`spec`** — added to `package.profile` (relative path to a bundled MDL spec),
+- **`spec`** — added to `plugin.profile` (relative path to a bundled MDL spec),
   `PluginProfileSchema`, the validator, and `dx.config.ts`.
-- **`dependencies`** (SDK-compat snapshot on `package.release`) — `composerPlugin` emits the full
-  resolved dependency map into `manifest.json`; the CLI writes it into the `package.release` record;
+- **`dependencies`** (SDK-compat snapshot on `plugin.release`) — `composerPlugin` emits the full
+  resolved dependency map into `manifest.json`; the CLI writes it into the `plugin.release` record;
   the validator preserves it in storage; `PluginReleaseSchema` in `@dxos/protocols` types it.
 
 ## Open questions & follow-ons

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-framework",
-  "version": "0.9.1-main.c7dcc2e112",
+  "version": "0.10.0",
   "description": "A framework for building applications from composible plugins.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -17,8 +17,13 @@
       "source": "./src/index.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs",
+      "workerd": "./dist/lib/browser/index.mjs",
       "types": "./dist/types/src/index.d.ts"
     },
+    "./workerd": {
+      "types": "./dist/types/src/index.d.ts",
+      "default": "./dist/lib/browser/index.mjs"
+    },
     "./ActivationEvent": {
       "source": "./src/core/activation-event.ts",
       "browser": "./dist/lib/browser/activation-event/index.mjs",
@@ -101,58 +106,59 @@
     "@babel/preset-typescript": "^7.27.1",
     "@effect-atom/atom": "^0.5.3",
     "@effect/cli": "0.75.2",
-    "@effect/platform": "0.96.1",
+    "@effect/platform": "0.96.2",
     "babel-preset-solid": "^1.9.9",
     "cjs-module-lexer": "^2.2.0",
     "esbuild": "0.28.1",
     "idb-keyval": "^6.2.1",
     "solid-js": "^1.9.11",
-    "@dxos/async": "0.9.1-main.c7dcc2e112",
-    "@dxos/compute-runtime": "0.9.1-main.c7dcc2e112",
-    "@dxos/compute": "0.9.1-main.c7dcc2e112",
-    "@dxos/context": "0.9.1-main.c7dcc2e112",
-    "@dxos/debug": "0.9.1-main.c7dcc2e112",
-    "@dxos/edge-client": "0.9.1-main.c7dcc2e112",
-    "@dxos/effect": "0.9.1-main.c7dcc2e112",
-    "@dxos/errors": "0.9.1-main.c7dcc2e112",
-    "@dxos/operation": "0.9.1-main.c7dcc2e112",
-    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
-    "@dxos/keys": "0.9.1-main.c7dcc2e112",
-    "@dxos/log": "0.9.1-main.c7dcc2e112",
-    "@dxos/protocols": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-error-boundary": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-hooks": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/util": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
-    "@dxos/web-context": "0.9.1-main.c7dcc2e112",
-    "@dxos/web-context-react": "0.9.1-main.c7dcc2e112"
+    "@dxos/async": "0.10.0",
+    "@dxos/compute-runtime": "0.10.0",
+    "@dxos/debug": "0.10.0",
+    "@dxos/effect": "0.10.0",
+    "@dxos/edge-client": "0.10.0",
+    "@dxos/errors": "0.10.0",
+    "@dxos/keys": "0.10.0",
+    "@dxos/log": "0.10.0",
+    "@dxos/invariant": "0.10.0",
+    "@dxos/operation": "0.10.0",
+    "@dxos/protocols": "0.10.0",
+    "@dxos/react-error-boundary": "0.10.0",
+    "@dxos/react-hooks": "0.10.0",
+    "@dxos/react-ui": "0.10.0",
+    "@dxos/react-ui-list": "0.10.0",
+    "@dxos/ui-theme": "0.10.0",
+    "@dxos/util": "0.10.0",
+    "@dxos/web-context": "0.10.0",
+    "@dxos/web-context-react": "0.10.0",
+    "@dxos/compute": "0.10.0",
+    "@dxos/context": "0.10.0"
   },
   "devDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
-    "@effect/platform": "0.96.1",
+    "@effect/platform": "0.96.2",
     "@effect/vitest": "0.29.0",
-    "@testing-library/react": "^16.3.0",
-    "@types/react": "~19.2.7",
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "~19.2.17",
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
     "typedoc": "0.28.1",
     "vite": "^8.0.16",
     "vite-plugin-solid": "^2.11.12",
-    "@dxos/brand": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo-client": "0.9.1-main.c7dcc2e112",
-    "@dxos/random": "0.9.1-main.c7dcc2e112",
-    "@dxos/test-utils": "0.9.1-main.c7dcc2e112",
-    "@dxos/storybook-utils": "0.9.1-main.c7dcc2e112"
+    "@dxos/brand": "0.10.0",
+    "@dxos/echo-client": "0.10.0",
+    "@dxos/storybook-utils": "0.10.0",
+    "@dxos/test-utils": "0.10.0",
+    "@dxos/random": "0.10.0"
   },
   "peerDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
-    "@effect/platform": "0.96.1",
-    "@testing-library/react": "^16.3.0",
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3"
+    "@effect/platform": "0.96.2",
+    "@testing-library/react": "^16.3.2",
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7"
   },
   "publishConfig": {
     "access": "public"

package/src/common/capabilities.ts

@@ -13,9 +13,9 @@ import type * as Runtime$ from 'effect/Runtime';
 import type { FC, PropsWithChildren } from 'react';
 
 import type {
+  OperationHandlerSet,
   LayerSpec as LayerSpec$,
   Operation as Operation$,
-  OperationHandlerSet,
   Process as Process$,
   ServiceResolver as ServiceResolver$,
   Trace as Trace$,
@@ -147,7 +147,7 @@ export const TraceSink = Capability$.make<TraceSinkFactory>('org.dxos.app-framew
  * const resolver = yield* Capability.get(Capabilities.ServiceResolver);
  * yield* effect.pipe(
  *   Effect.provide(
- *     ServiceResolver.provide({ space }, Database.Service, Feed.FeedService).pipe(
+ *     ServiceResolver.provide({ space }, Database.Service).pipe(
  *       Layer.provide(Layer.succeed(ServiceResolver.ServiceResolver, resolver)),
  *     ),
  *   ),

package/src/core/capability.ts

@@ -143,13 +143,14 @@ export type ModuleReturn = void | Any | Any[] | readonly Any[] | [Any, ...Any[]]
 
 /**
  * Helper to define the implementation of a capability.
+ * Returns the opaque base type so callers cannot discriminate on capability kind,
+ * keeping d.ts emit portable across packages.
  */
-// TODO(dmaretskyi): Make the return type non-generic so capabilities are non-discernable.
 export const contributes = <I extends InterfaceDef<any>>(
   interfaceDef: I,
   implementation: Capability<InterfaceDef.Implementation<I>>['implementation'],
   deactivate?: Capability<InterfaceDef.Implementation<I>>['deactivate'],
-): Capability<I> => {
+): Any => {
   return {
     interface: interfaceDef,
     implementation,

package/src/testing/react.tsx

@@ -3,7 +3,7 @@
 //
 
 import { RegistryContext } from '@effect-atom/atom-react';
-import { render as rtlRender, type RenderOptions, type RenderResult } from '@testing-library/react';
+import { type RenderOptions, type RenderResult, render as rtlRender } from '@testing-library/react';
 import React, { type FC, Fragment, type PropsWithChildren, type ReactNode } from 'react';
 
 import { ContextProtocolProvider } from '@dxos/web-context-react';

package/src/ui/components/App/App.stories.tsx

@@ -50,9 +50,9 @@ const TestPlugin = Plugin.define<{ error?: boolean }>(
   Plugin.make,
 );
 
-type DefaultStoryProps = { plugins?: Plugin.Plugin[] };
+type StoryArgs = { plugins?: Plugin.Plugin[] };
 
-const DefaultStory = ({ plugins }: DefaultStoryProps) => {
+const DefaultStory = ({ plugins }: StoryArgs) => {
   const App = useApp({ plugins });
 
   return <App />;

package/src/ui/components/Surface/SurfaceComponent.stories.tsx

@@ -6,7 +6,8 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 
 import { random } from '@dxos/random';
-import { List, ListItem, Panel, Toolbar } from '@dxos/react-ui';
+import { Panel, Toolbar } from '@dxos/react-ui';
+import { Listbox } from '@dxos/react-ui-list';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ColorStyles, getHashStyles, mx } from '@dxos/ui-theme';
 
@@ -112,13 +113,15 @@ const DefaultStory = () => {
       <Panel.Content className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
         <SurfaceComponent type={ItemRole} data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
         <div className='overflow-y-auto h-full'>
-          <List>
-            {surfaces.map((surface) => (
-              <ListItem.Root key={surface.id} id={surface.id}>
-                <ListItem.Heading classNames='flex items-center'>{surface.id}</ListItem.Heading>
-              </ListItem.Root>
-            ))}
-          </List>
+          <Listbox.Root>
+            <Listbox.Content aria-label='Surfaces'>
+              {surfaces.map((surface) => (
+                <Listbox.Item key={surface.id} id={surface.id}>
+                  <Listbox.ItemLabel classNames='flex items-center'>{surface.id}</Listbox.ItemLabel>
+                </Listbox.Item>
+              ))}
+            </Listbox.Content>
+          </Listbox.Root>
         </div>
       </Panel.Content>
     </Panel.Root>

package/src/ui/components/Surface/SurfaceComponent.tsx

@@ -20,11 +20,11 @@ import React, {
 import { log } from '@dxos/log';
 import { ErrorBoundary } from '@dxos/react-error-boundary';
 import { useDefaultValue } from '@dxos/react-hooks';
-import { byPosition } from '@dxos/util';
+import { Position } from '@dxos/util';
 
 import { Capabilities } from '../../../common';
 import { type CapabilityManager } from '../../../core';
-import { usePluginManager } from '../PluginManager/PluginManagerProvider';
+import { usePluginManager } from '../PluginManager';
 import { SurfaceContext } from './context';
 import { SurfaceInfo } from './SurfaceInfo';
 import { useSurfaceProfilerCallback } from './SurfaceProfilerContext';
@@ -37,7 +37,7 @@ import {
   type WebComponentDefinition,
 } from './types';
 
-const DEBUG = import.meta.env.VITE_DEBUG;
+const DEBUG = import.meta.env?.VITE_DEBUG;
 
 const DEFAULT_PLACEHOLDER = <Fragment />;
 
@@ -270,7 +270,7 @@ const findCandidates = (surfaces: Definition[], { role, data }: { role: string;
       Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
     )
     .filter(({ filter }) => (filter ? filter(data ?? {}, role) : true))
-    .toSorted(byPosition);
+    .toSorted(Position.compare);
 };
 
 /**
@@ -281,7 +281,7 @@ export const useSurfaces = () => {
   const surfacesByModule = useAtomValue(manager.capabilities.atomByModule(Capabilities.ReactSurface));
   return useMemo(() => {
     const result: Definition[] = [];
-    for (const [moduleId, surfaces] of Object.entries(surfacesByModule)) {
+    for (const [_moduleId, surfaces] of Object.entries(surfacesByModule)) {
       for (const def of surfaces.flat()) {
         result.push(def);
       }
@@ -304,6 +304,7 @@ export function isSurfaceAvailable<TToken extends RoleToken<any>>(
   if (effectiveRole == null) {
     return false;
   }
+
   const surfaces = capabilityManager.getAll(Capabilities.ReactSurface);
   const candidates = findCandidates(surfaces.flat(), {
     role: effectiveRole,

package/src/ui/components/Surface/SurfaceProfilerContext.tsx

@@ -4,8 +4,8 @@
 
 import React, {
   type Context,
-  type PropsWithChildren,
   type ProfilerOnRenderCallback,
+  type PropsWithChildren,
   createContext,
   useContext,
   useMemo,

package/src/ui/components/Surface/context.ts

@@ -11,5 +11,4 @@ export type SurfaceContext = {
   data?: Record<string, any>;
 };
 
-// TODO(burdon): Use @radix-ui/react-context
 export const SurfaceContext: Context<SurfaceContext | undefined> = createContext<SurfaceContext | undefined>(undefined);

package/src/ui/components/Surface/index.ts

@@ -15,10 +15,10 @@ import {
   useSurfaceProfilerStats,
 } from './SurfaceProfilerContext';
 import {
-  type Definition as SurfaceDefinition,
-  type RoleToken as SurfaceRoleToken,
   type SurfaceBinding as SurfaceBindingType,
+  type Definition as SurfaceDefinition,
   type SurfaceFilter as SurfaceFilterType,
+  type RoleToken as SurfaceRoleToken,
   type TokenData as SurfaceTokenData,
   type TypedProps as SurfaceTypedProps,
   create as createSurface,

package/src/ui/components/Surface/types.test.ts

@@ -4,6 +4,8 @@
 
 import { describe, test } from 'vitest';
 
+import { Position } from '@dxos/util';
+
 import { type CapabilityManager } from '../../../core';
 import { isSurfaceAvailable } from './SurfaceComponent';
 import { type RoleToken, type SurfaceFilter, create, isSurfaceFilter, makeFilter, makeType } from './types';
@@ -76,8 +78,8 @@ describe('create', () => {
   test('passes position through untouched', ({ expect }) => {
     const token = makeType<Record<string, any>>('org.dxos.test.role.r');
     const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: token.role, guard: () => true }] };
-    const def = create({ id: 'pos', filter, component: () => null, position: 'last' });
-    expect(def.position).toBe('last');
+    const def = create({ id: 'pos', filter, component: () => null, position: Position.last });
+    expect(def.position).toBe(Position.last);
   });
 });
 

package/src/ui/components/Surface/types.ts

@@ -214,7 +214,7 @@ export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'react';
   id: string;
   role: string | string[];
-  position?: Position;
+  position?: Position.Position;
   component: ComponentFunction<T>;
   filter?: (data: Record<string, unknown>, role?: string) => data is T;
 }>;
@@ -229,7 +229,7 @@ export type WebComponentDefinition<T extends Record<string, any> = any> = Readon
   kind: 'web-component';
   id: string;
   role: string | string[];
-  position?: Position;
+  position?: Position.Position;
   /**
    * The tag name of the Web Component to render.
    * The Web Component will receive the same props as React surfaces via properties/attributes.
@@ -250,7 +250,7 @@ export type TypedReactDefinition<T extends Record<string, any> = any> = Readonly
   id: string;
   filter: SurfaceFilter<T>;
   component: ComponentFunction<T>;
-  position?: Position;
+  position?: Position.Position;
 }>;
 
 /**
@@ -260,7 +260,7 @@ export type TypedWebComponentDefinition<T extends Record<string, any> = any> = R
   id: string;
   filter: SurfaceFilter<T>;
   tagName: string;
-  position?: Position;
+  position?: Position.Position;
 }>;
 
 const expandBindings = <T extends Record<string, any>>(

package/src/ui/hooks/useCapabilities.ts

@@ -15,6 +15,9 @@ import { useOptionalPluginManager, usePluginManager } from '../components';
 /** Stable empty result for capability lookups made outside a plugin manager. */
 const emptyCapabilities = Atom.make(() => [] as const);
 
+/** Stable atom yielding `undefined`, used as the fallback for optional atom-capability lookups. */
+const emptyAtomValue = Atom.make(() => undefined);
+
 /**
  * Hook to request capabilities from the plugin context.
  * @returns An array of capabilities.
@@ -84,6 +87,28 @@ export const useAtomCapabilityState = <T>(
   return [value, update];
 };
 
+/**
+ * Tolerant variant of {@link useAtomCapabilityState}: returns `[undefined, noop]` when the atom
+ * capability is not registered (e.g. the contributing plugin is not installed) rather than
+ * throwing. The updater is a no-op while the capability is absent.
+ */
+export const useOptionalAtomCapabilityState = <T>(
+  atomCapability: Capability.InterfaceDef<Atom.Writable<T>>,
+): [T | undefined, (fn: (current: T) => T) => void] => {
+  const registry = useOptionalCapability(Capabilities.AtomRegistry);
+  const atom = useOptionalCapability(atomCapability);
+  const value = useAtomValue(atom ?? emptyAtomValue);
+  const update = useCallback(
+    (fn: (current: T) => T) => {
+      if (registry && atom) {
+        registry.set(atom, fn(registry.get(atom)));
+      }
+    },
+    [registry, atom],
+  );
+  return [value, update];
+};
+
 /**
  * Hook to get the operation invoker capability.
  */

package/src/vite-plugin/boot-loader/BootLoader.solid-stories.tsx

@@ -148,12 +148,12 @@ const LoaderHarness = () => {
       {/* Float the controls above the loader's `z-index: 10` fixed backdrop. */}
       <div
         style={{
-          position: 'fixed',
-          top: '12px',
-          left: '12px',
+          'position': 'fixed',
+          'top': '12px',
+          'left': '12px',
           'z-index': 9999,
-          display: 'flex',
-          gap: '12px',
+          'display': 'flex',
+          'gap': '12px',
           'align-items': 'center',
         }}
       >
@@ -161,20 +161,20 @@ const LoaderHarness = () => {
           type='button'
           onClick={advance}
           style={{
-            padding: '6px 14px',
+            'padding': '6px 14px',
             'font-size': '13px',
             'font-weight': '600',
-            color: '#fff',
-            background: '#017ab7',
-            border: 'none',
+            'color': '#fff',
+            'background': '#017ab7',
+            'border': 'none',
             'border-radius': '6px',
-            cursor: 'pointer',
+            'cursor': 'pointer',
             'box-shadow': '0 1px 3px rgba(0,0,0,0.25)',
           }}
         >
           {sim() === 'creep' ? 'Start progress' : 'Finish + reset'}
         </button>
-        <span style={{ 'font-family': 'ui-sans-serif, system-ui, sans-serif', 'font-size': '12px', color: '#888' }}>
+        <span style={{ 'font-family': 'ui-sans-serif, system-ui, sans-serif', 'font-size': '12px', 'color': '#888' }}>
           {sim()}
         </span>
       </div>

package/src/vite-plugin/boot-loader/loader.ts

@@ -8,7 +8,7 @@ import * as babel from '@babel/core';
 import babelPresetTypeScript from '@babel/preset-typescript';
 // @ts-ignore — babel-preset-solid ships no .d.ts.
 import babelPresetSolid from 'babel-preset-solid';
-import { build, type Plugin as EsbuildPlugin } from 'esbuild';
+import { type Plugin as EsbuildPlugin, build } from 'esbuild';
 import { basename, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { type Plugin } from 'vite';
@@ -181,8 +181,8 @@ export const bootLoaderPlugin = ({ status, markSvg, include = ['index.html'] }:
           tag: 'div',
           injectTo: 'body-prepend',
           attrs: {
-            id: rootId,
-            role: 'status',
+            'id': rootId,
+            'role': 'status',
             'aria-live': 'polite',
             'aria-label': 'Initializing',
           },

package/src/vite-plugin/composer/index.ts

@@ -6,7 +6,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { type Plugin as VitePlugin } from 'vite';
 
-import { PLUGIN_DEV_SERVER_PORT, Plugin } from '../../core';
+import { Plugin, PLUGIN_DEV_SERVER_PORT } from '../../core';
 import { findDxConfigFile, loadDxConfig } from '../load';
 import { type BuildMeta, ENTRY_FILENAME, MANIFEST_ASSET_NAME, serializeManifest, toBuildMeta } from '../manifest';
 import { DEFAULT_PACKAGES, isSharedPackage } from '../packages';