@dxos/app-framework 0.11.1 → 1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d

package/API.md

@@ -0,0 +1,275 @@
+# DXOS App Framework API
+
+Companion to [ARCHITECTURE.md](./ARCHITECTURE.md), which covers how the pieces relate. This is the
+API surface.
+
+## Imports
+
+```ts
+import {
+  ActivationEvent, // Runtime activation events (make/oneOf/allOf)
+  ActivationEvents, // Well-known framework events (Startup, ...)
+  Capabilities, // Well-known capability tags (ReactSurface, OperationHandler, ...)
+  Capability, // Capability tags, contributions, module authoring
+  Plugin, // Plugin definition + builder
+  PluginManager, // Manager type (usually obtained, not constructed)
+} from '@dxos/app-framework';
+import { Surface, useApp, useCapabilities, useCapability } from '@dxos/app-framework/ui';
+import { withPluginManager } from '@dxos/app-framework/testing';
+```
+
+---
+
+## Defining a capability
+
+A capability is a typed, NSID-keyed slot. **Arity is chosen at definition** and decides what
+consumers get.
+
+```ts
+// Multi (the default): an open registry many modules contribute to.
+export const Template = Capability.make<Template>()('org.dxos.plugin.projects.capability.template');
+
+// Singleton: exactly one provider.
+export const Client = Capability.makeSingleton<ClientApi>()('org.dxos.plugin.client.capability.client');
+```
+
+Both are curried — `make<T>()(nsid)` — so the NSID string literal is captured and brands the
+identifier. NSIDs must be camelCase (`DXN.Name`). The single-call form `make<T>(nsid)` still compiles
+but widens the NSID to `string`, making the compile-time check vacuous; prefer the curried form.
+
+|                    | `makeSingleton` → `Tag<T>`           | `make` → `MultiTag<T>`                    |
+| ------------------ | ------------------------------------ | ----------------------------------------- |
+| `yield* tag` gives | `T`                                  | `Contributions<T>` (live view)            |
+| Requiring it       | gates activation on its one provider | never gates — the collection may be empty |
+| Two providers      | `DuplicateProviderError`             | normal                                    |
+
+---
+
+## Authoring a module
+
+A module is a body plus a declaration of what it `requires` and `provides`.
+
+```ts
+// Code-split (the common case) — the chunk loads when the module activates.
+export const Coordinator = Capability.lazyModule(
+  'ConnectorCoordinator',
+  { requires: [ClientCapabilities.Client], provides: [ConnectorCoordinator] },
+  () => import('./connector-coordinator'),
+);
+
+// Eager — body defined inline, no separate chunk.
+export const Extractor = Capability.inlineModule(
+  'SummarizeExtractor',
+  { provides: [InboxCapabilities.ObjectExtractor] },
+  () => Effect.succeed(Capability.contribute(InboxCapabilities.ObjectExtractor, extractor)),
+);
+```
+
+The body is written with `Capability.makeModule` and yields its declared requirements:
+
+```ts
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const client = yield* ClientCapabilities.Client; // declared in `requires`
+    const coordinator = new Coordinator(client);
+    return Capability.contribute(ConnectorCoordinator, coordinator);
+  }),
+);
+```
+
+Yielding a tag that is not in `requires` is a type error (it escapes the `R` channel); failing to
+contribute a declared `provides` is also a type error.
+
+**Makers.** Capability owners export a maker so call sites don't repeat `provides`.
+`@dxos/app-toolkit` ships them for the common capabilities:
+
+```ts
+export const ReactSurface = AppCapability.surface(() => import('./react-surface'));
+export const AppGraphBuilder = AppCapability.appGraphBuilder(() => import('./app-graph-builder'), {
+  requires: [SomeCapabilities.Thing],
+});
+```
+
+Build your own with `Capability.moduleMaker(name, tag)`.
+
+---
+
+## Composing a plugin
+
+```ts
+export const FooPlugin = Plugin.define(meta).pipe(
+  Plugin.addModule(ReactSurface),
+  Plugin.addModule(Coordinator),
+  Plugin.addModule(AppCapability.translations(translations)),
+  Plugin.addModule(AppCapability.schema([Foo.Foo])),
+  Plugin.make,
+);
+```
+
+`Plugin.define(meta)` starts a builder; each `addModule` adds one module; `Plugin.make` seals it.
+When the plugin takes options, `addModule` also accepts `(options) => module` and makers accept a
+`props` mapping from plugin options to body props. If every option is optional, calling
+`FooPlugin()` with no argument is allowed.
+
+---
+
+## Consuming capabilities
+
+Three access paths, for three situations.
+
+**1. Inside a module body** — declared, type-checked, ordering-aware.
+
+```ts
+Effect.fnUntraced(function* () {
+  const client = yield* ClientCapabilities.Client; // singleton → T
+  const templates = yield* ProjectCapabilities.Template; // multi → Contributions<T>
+});
+```
+
+**2. Outside a module** (operations, callbacks, non-module code) — dynamic, string-keyed.
+
+```ts
+Effect.gen(function* () {
+  const handlers = yield* Capability.getAll(Capabilities.OperationHandler);
+  const maybe = yield* Capability.getOption(AppCapabilities.ProgressRegistry);
+  const surfaces = yield* Capability.atom(Capabilities.ReactSurface); // reactive
+  const client = yield* Capability.waitFor(ClientCapabilities.Client); // resolves when contributed
+});
+```
+
+**3. React.**
+
+```tsx
+const surfaces = useCapabilities(Capabilities.ReactSurface);
+const client = useCapability(ClientCapabilities.Client);
+```
+
+> In graph-extension atom callbacks always use `Capability.atom`, never a synchronous
+> `Capability.get` — a sync read inside an atom body caches a defect fallback with no reactive
+> dependency.
+
+---
+
+## Contributing values
+
+A module returns its contributions from `activate`. `contribute` carries one value, `contributeAll`
+carries several for the same capability; both produce a single `Contribution`.
+
+```ts
+return [
+  Capability.contribute(Capabilities.ReactSurface, surface),
+  Capability.contributeAll(Capabilities.LayerSpec, [clientSpec, databaseSpec]),
+];
+```
+
+A module providing exactly one capability may return the `Contribution` directly, without the array.
+An optional third argument is a `deactivate` hook, run once when the module is deactivated.
+
+The return is checked against the module's declared `provides`: omitting a declared capability is a
+type error, and contributing an undeclared one fails at runtime.
+
+## Reading a multi capability
+
+A multi capability has no single value, and its membership changes as plugins are enabled and
+disabled. Reading one therefore gives a live `Contributions<T>` view rather than an array:
+
+```ts
+Effect.fnUntraced(function* () {
+  const templates = yield* ProjectCapabilities.Template; // Contributions<Template>
+
+  templates.get(); // readonly Template[] — snapshot as of now
+  templates.subscribe((values) => setTemplates(values)); // → unsubscribe
+  templates.atom; // Atom<Template[]> for Atom-based composition
+});
+```
+
+`get()` is a point-in-time snapshot: hold onto it and it will not reflect capabilities contributed
+later. Consume the collection reactively — via `subscribe`, `atom`, or the React hooks — unless the
+value is used immediately and discarded.
+
+### `Contribution` vs `Contributions`
+
+Two types one letter apart, on either side of the registry:
+
+|             | `Contribution`                            | `Contributions<T>`                                           |
+| ----------- | ----------------------------------------- | ------------------------------------------------------------ |
+| Direction   | what a module **produces**                | what a consumer **reads**                                    |
+| Produced by | `Capability.contribute` / `contributeAll` | `yield*` on a `MultiTag`, or `Capability.contributions(tag)` |
+| Shape       | `{ capability, values, deactivate? }`     | `{ atom, get(), subscribe() }`                               |
+| Scope       | one module's values for one capability    | every module's values for one capability                     |
+
+---
+
+## Activation
+
+A module activates in one of two modes, normalized onto `PluginModule.activation`:
+
+- **Dependency mode** (the default) — declared `requires`/`provides`. The manager topologically
+  orders modules so providers run before consumers. A module with no `requires` is a startup root.
+- **Event mode** — `activatesOn` a genuine runtime event; `requires` are pulled on demand when it
+  fires.
+
+```ts
+Capability.lazyModule(
+  'OnSpaceCreated',
+  { activatesOn: SpaceEvents.SpaceCreated, provides: [] },
+  () => import('./on-space-created'),
+);
+```
+
+Surviving events are runtime occurrences only — `ActivationEvents.Startup`, `SpacesReady`,
+`SpaceCreated`, `IdentityCreated`, `TypeAdded`, plus parameterized `createStateEvent` /
+`createSettingsEvent`. Ordering-only `Setup*`/`*Ready` events were removed; express ordering as
+`requires`/`provides`.
+
+Structural problems isolate rather than abort startup: a dependency cycle, duplicate singleton
+provider, or unsatisfiable requirement puts the owning plugin in an error state
+(`DependencyCycleError`, `DuplicateProviderError`, `MissingProviderError`,
+`ProvidesMismatchError`) and everything else proceeds.
+
+---
+
+## Well-known capabilities
+
+`Capabilities` (framework) — `ReactSurface`, `ReactContext`, `ReactRoot`, `OperationHandler`,
+`OperationInvoker`, `UndoMapping`, `Command`, `Layer`, `LayerSpec`, `TraceSink`, `AtomRegistry`,
+`ServiceResolver`, `ProcessManagerRuntime`, `ProcessMonitor`, `PluginManager`.
+
+`AppCapabilities` (`@dxos/app-toolkit`) — `Translations`, `Schema`, `Settings`, `AppGraph`,
+`AppGraphBuilder`, `SkillDefinition`, `PluginAsset`, `Toolkit`, `NavigationTargetResolver`,
+`NavigationHandler`, `TextContent`, `CommentConfig`, `AnchorSort`, `AnchorResolver`, `Layout`.
+
+---
+
+## Testing
+
+```ts
+withPluginManager({
+  plugins: [ClientPlugin(), FooPlugin()],
+  capabilities: [Capability.contribute(SomeCapability, stub)], // takes Contribution[]
+});
+```
+
+`@dxos/app-framework/testing` also exports `harness` (headless activation assertions) and
+`createComposerTestApp`.
+
+---
+
+## Type reference
+
+| Type                          | Meaning                                                        |
+| ----------------------------- | -------------------------------------------------------------- |
+| `Capability.Tag<T, S>`        | Singleton tag; `yield*` → `T`                                  |
+| `Capability.MultiTag<T, S>`   | Multi tag; `yield*` → `Contributions<T>`                       |
+| `Capability.AnyTag`           | `Tag \| MultiTag`                                              |
+| `Capability.Contribution`     | One branded contribution (capability + n values)               |
+| `Capability.Contributions<T>` | Live view: `{ atom, get(), subscribe() }`                      |
+| `Capability.Any`              | A registry entry: `{ interface, implementation, deactivate? }` |
+| `Capability.Module<Options>`  | An authored module, opaque except for its options type         |
+| `Plugin.Plugin`               | `{ meta, modules }`                                            |
+| `Plugin.PluginModule`         | `{ id, activation, activate() }`                               |
+| `Plugin.ActivationSpec`       | `dependency \| event` discriminated union                      |
+
+`Contribution` → `Capability.Any` is a 1-to-n expansion performed by the manager
+(`CapabilityManager.expandContributions`); see
+[ARCHITECTURE.md](./ARCHITECTURE.md#the-two-layer-split).

package/ARCHITECTURE.md

@@ -0,0 +1,190 @@
+# Architecture
+
+How plugins, modules, capabilities and contributions relate.
+
+The short version: a **plugin** is a bag of **modules**; a module declares which **capabilities** it
+`requires` and `provides`, and its body returns **contributions**; the manager topologically orders
+activation from those declarations and expands each contribution into the flat entries the
+**capability registry** stores.
+
+## Domain model
+
+```mermaid
+classDiagram
+  direction TB
+
+  class Plugin {
+    +Meta meta
+    +PluginModule[] modules
+  }
+
+  class PluginModule {
+    +string id
+    +ActivationSpec activation
+    +activate(props) Effect
+  }
+
+  class ActivationSpec {
+    +mode  dependency | event
+    +AnyTag[] requires
+    +AnyTag[] provides
+    +Events activatesOn
+  }
+
+  class Module {
+    +AnyTag[] requires
+    +AnyTag[] provides
+    +Events activatesOn
+    +call(options) Effect
+  }
+
+  class Tag {
+    +arity  single
+    +yield* gives T
+  }
+
+  class MultiTag {
+    +arity  multi
+    +yield* gives Contributions
+  }
+
+  class Contribution {
+    +AnyTag capability
+    +unknown[] values
+    +deactivate()
+  }
+
+  class CapabilityEntry {
+    +InterfaceDef interface
+    +T implementation
+    +deactivate()
+  }
+
+  class Contributions {
+    +Atom atom
+    +get() T[]
+    +subscribe(cb)
+  }
+
+  class CapabilityManager {
+    +contribute(entry)
+    +get(tag) T
+    +getAll(tag) T[]
+    +atom(tag) Atom
+    +contributions(tag) Contributions
+  }
+
+  class PluginManager {
+    +start()
+    +activate(event)
+  }
+
+  Plugin "1" *-- "0..n" PluginModule : modules
+  PluginModule --> ActivationSpec : activation
+  Module ..> PluginModule : Plugin.addModule()
+  ActivationSpec ..> Tag : requires / provides
+  ActivationSpec ..> MultiTag : requires / provides
+  Tag ..> Contribution : Capability.contribute()
+  MultiTag ..> Contribution : Capability.contributeAll()
+  Contribution ..> CapabilityEntry : expandContributions() 1 to n
+  CapabilityManager "1" o-- "0..n" CapabilityEntry : registry keyed by NSID
+  CapabilityManager ..> Contributions : live view for a MultiTag
+  PluginManager --> PluginModule : orders and activates
+  PluginManager --> CapabilityManager : owns
+```
+
+### The two-layer split
+
+`Contribution` and `CapabilityEntry` (exported as `Capability.Any`) sit on either side of the
+registry boundary — the authoring layer and the storage layer:
+
+|              | `Contribution` (authoring)                                                                     | `Capability.Any` (registry)             |
+| ------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Produced by  | `Capability.contribute` / `contributeAll`                                                      | `CapabilityManager.expandContributions` |
+| Holds        | **n** values for one capability                                                                | exactly **one** implementation          |
+| Identity     | branded by capability identity (NSID + arity) — powers the `EnsureProvides` completeness check | the `InterfaceDef` only                 |
+| Service type | erased to `AnyTag`, so a body's service type never leaks into `.d.ts` emit                     | names `T` directly                      |
+
+`expandContributions` is the one-way bridge: a `contributeAll(tag, [a, b, c])` is one `Contribution`
+that becomes three registry entries, with the `deactivate` hook pinned to the first so it runs
+exactly once.
+
+## Activation
+
+```mermaid
+flowchart TB
+  subgraph authoring["Authoring (compile time)"]
+    A1["Capability.make / makeSingleton<br/>defines a Tag"]
+    A2["Capability.lazyModule / inlineModule<br/>or an AppCapability maker<br/>→ Capability.Module"]
+    A3["Plugin.define(meta).pipe(<br/>Plugin.addModule(...), Plugin.make)<br/>→ Plugin"]
+    A1 --> A2 --> A3
+  end
+
+  subgraph ordering["Ordering (PluginManager.start)"]
+    B1["Collect every enabled plugin's modules"]
+    B2{"activation.mode"}
+    B3["dependency:<br/>edges from requires → provides<br/>Kahn topological waves"]
+    B4["event:<br/>parked until activatesOn fires,<br/>requires pulled on demand"]
+    B1 --> B2
+    B2 -->|dependency| B3
+    B2 -->|event| B4
+  end
+
+  subgraph runtime["Activation + registry"]
+    C1["Build the module's Context<br/>from its requires"]
+    C2["activate(props) → Contribution[]"]
+    C3["Validate against declared provides"]
+    C4["expandContributions → Capability.Any[]"]
+    C5["CapabilityManager.contribute(entry)"]
+    C1 --> C2 --> C3 --> C4 --> C5
+  end
+
+  subgraph consume["Consumption"]
+    D1["In a module body:<br/>yield* Tag"]
+    D2["Dynamically:<br/>Capability.get / getAll / atom"]
+    D3["Reactively:<br/>Contributions.atom"]
+  end
+
+  A3 --> B1
+  B3 --> C1
+  B4 --> C1
+  C5 --> D1
+  C5 --> D2
+  C5 --> D3
+```
+
+Failure modes are structural rather than fatal: a dependency cycle, a duplicate singleton provider,
+or an unsatisfiable `requires` puts the owning plugin into an error state and excludes it from
+further rounds, while everything else proceeds. A consumer whose provider is event-gated **waits**
+rather than erroring, and activates in a later round once the provider contributes.
+
+### Singleton vs multi
+
+Arity is a property of the tag and decides what `yield*` gives you:
+
+- `Capability.makeSingleton<T>()(nsid)` → `Tag`. `yield* tag` gives `T`. Requiring one gates
+  activation on its single provider; two providers is a `DuplicateProviderError`.
+- `Capability.make<T>()(nsid)` → `MultiTag` (the default). `yield* tag` gives a live
+  `Contributions<T>` collection. Providers never gate consumers, so consume it reactively — a
+  one-shot snapshot silently misses late contributions.
+
+Both forms are curried so the NSID string literal is captured and brands the identifier; the NSID
+must be camelCase (`DXN.Name`).
+
+## Where things live
+
+| Concept                                                              | File                                                     |
+| -------------------------------------------------------------------- | -------------------------------------------------------- |
+| Tags, arity, `Contribution`, `contribute`, module makers             | `src/core/capability.ts`                                 |
+| `Plugin`, `PluginModule`, `ActivationSpec`, the builder              | `src/core/plugin.ts`                                     |
+| Public manager API, unit composition, shutdown, failure policy       | `src/core/plugin-manager/plugin-manager.ts`              |
+| Shared substrate: atoms, status channel, fibers (`ManagerState`)     | `src/core/plugin-manager/manager-state.ts`               |
+| Catalog: add/enable/disable, lazy resolution, dependency closure     | `src/core/plugin-manager/plugin-catalog.ts`              |
+| Lifecycle engine: start/activate/deactivate/reset, rounds, waves     | `src/core/plugin-manager/activation-scheduler.ts`        |
+| Ordering logic (runnable selection, waves, cycles), on `@dxos/graph` | `src/core/plugin-manager/activation-graph.ts`            |
+| Memoized module loads, provides validation, deactivation             | `src/core/plugin-manager/module-loader.ts`               |
+| The NSID-keyed registry and its reactive views                       | `src/core/capability-manager.ts`                         |
+| Tagged errors (cycle, missing/duplicate provider, mismatch)          | `src/core/errors.ts`                                     |
+| Per-capability module makers (`surface`, `settings`, …)              | `@dxos/app-toolkit` `src/app-framework/AppCapability.ts` |
+
+Worked examples: `@dxos/plugin-client` and `@dxos/plugin-markdown`.

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @dxos/app-framework
 
+## 1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+
+### Minor Changes
+
+- 0280a6a: Omitting `activatesOn` on a plugin module now puts it in the **idle** wave rather than the startup wave. A module that must run at boot has to declare `activatesOn: ActivationEvents.Startup` explicitly.
+
+  This is a behaviour change for out-of-repo plugin authors: an un-annotated module that previously ran during startup now runs at host idle. Un-annotated modules remain pullable as providers, so one that a startup module `requires` is still activated ahead of its own wave — the change is only visible for modules nothing on the boot path depends on.
+
+  The `@dxos/app-toolkit` maker families that back the app shell — `settings`, `operationHandler`, `reactContext`, `reactRoot`, `navigationResolver` and `navigationHandler` — now state `Startup` explicitly, so modules built with them are unaffected. `appGraphBuilder` (idle) and `skillDefinition` (assistant start) were already explicit.
+
+- 34a8433: Order module activation by capability dependencies instead of hand-wired events.
+  A module declares the capabilities it `requires` and `provides` (or a runtime
+  `activatesOn` event) and the plugin manager topologically orders activation from
+  that graph. Capabilities are yieldable Effect services, so accessing an undeclared
+  capability or omitting a declared one is now a type error, and missing providers,
+  dependency cycles, and duplicate providers fail fast with tagged errors instead of
+  runtime assertions. Plugins compose as a flat chain of `Plugin.addModule` over
+  module bodies authored with `Capability.lazyModule` (code-split) or
+  `Capability.inlineModule` (eager), or with a per-capability maker from the new
+  `AppCapability` namespace (`surface`, `settings`, `appGraphBuilder`, `translations`,
+  `schema`, ...) that bakes in the module name and default provides. A module is an
+  opaque `Capability.Module<Options>`, parameterized only by its options type, so a
+  module export never leaks a foreign capability's type into declaration emit.
+
+  Every plugin in the repository is migrated to this API. The plugins gain no
+  behaviour of their own from the change, but any plugin defined outside the
+  repository must be migrated too — the legacy API is removed, not deprecated.
+
+  Breaking: the legacy event-wiring API is removed — `AppPlugin` and its
+  `addXModule` helpers, `firesBeforeActivation`/`firesAfterActivation`, `compatFires`,
+  and the ordering-only `Setup*`/`*Ready` activation events (genuine runtime events
+  remain). `Capability.provide`/`provideAll` are renamed to
+  `Capability.contribute`/`contributeAll`, and the untyped raw builder
+  `Capability.contributes` is removed. Multi is now the default capability arity:
+  `Capability.make` defines a multi (registry) capability and
+  `Capability.makeSingleton` the single-provider case, both curried
+  (`make<T>()(nsid)`) so the NSID literal brands the identifier. The
+  `withPluginManager` `capabilities` test option now accepts `Contribution[]`.
+
+### Patch Changes
+
+- 4a0b78b: Bundler-plugin entrypoints no longer publish a `source` export condition: `@dxos/app-framework/vite-plugin` and `@dxos/ui-theme/plugin`. These run in Node inside a `vite.config.ts` and reach `node:*`, so a `source` condition let an app's `source`-first resolver pull their Node-only sources into a browser bundle.
+
+  Default resolution is unchanged — both entrypoints already resolved to their built `dist` for ordinary consumers, with the same exports and runtime behaviour. Only resolution under `--conditions=source` changes: it now yields the built output, matching `@dxos/config`'s bundler-plugin entrypoints.
+
+- Updated dependencies [85ad256]
+- Updated dependencies [557e243]
+- Updated dependencies [557e243]
+- Updated dependencies [7c426d4]
+- Updated dependencies [fc83abd]
+- Updated dependencies [77d0026]
+  - @dxos/protocols@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/react-ui@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/compute@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/react-hooks@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/compute-runtime@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/edge-client@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/operation@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/async@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/context@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/debug@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/effect@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/errors@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/graph@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/invariant@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/keys@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/log@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/react-error-boundary@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/ui-theme@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/util@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/web-context@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+  - @dxos/web-context-react@1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d
+
 ## 0.11.1
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,9 @@
 
 A framework for building applications from composible plugins.
 
+See [API.md](./API.md) for the API surface, and [ARCHITECTURE.md](./ARCHITECTURE.md) for how
+plugins, modules, capabilities and contributions relate and how activation is ordered.
+
 ## Installation
 
 ```bash

package/dist/lib/chunk-SurfaceManager.mjs

@@ -1,7 +1,11 @@
 import { ReactSurface } from "./common/capabilities.mjs";
+import { SurfacesRequested } from "./common/activation-events.mjs";
 import { Position } from "@dxos/util";
+import * as Effect from "effect/Effect";
 import { Atom } from "@effect-atom/atom";
+import { EffectEx } from "@dxos/effect";
 import { log } from "@dxos/log";
+import * as Exit from "effect/Exit";
 import { Fragment, Profiler, Suspense, createContext, createElement, memo, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { ErrorBoundary } from "@dxos/react-error-boundary";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
@@ -37,9 +41,8 @@ var PluginManagerContext = createContext(void 0);
 */
 var usePluginManager = () => useContext(PluginManagerContext) ?? raise(/* @__PURE__ */ new Error("Missing PluginManagerContext"));
 /**
-* Get the plugin manager if present, or `undefined` when rendered outside a {@link PluginManagerProvider}
-* (e.g. a standalone component story). Lets components treat plugin capabilities as a progressive
-* enhancement rather than a hard requirement.
+* Get the plugin manager, or undefined outside a provider. Surfaces and activation signals fire
+* demand events opportunistically and must not throw when rendered standalone (stories, tests).
 */
 var useOptionalPluginManager = () => useContext(PluginManagerContext);
 /**
@@ -607,6 +610,16 @@ var emptySnapshot = () => EMPTY_SNAPSHOT;
 //#endregion
 //#region src/ui/components/Surface/SurfaceComponent.tsx
 var DEFAULT_PLACEHOLDER = /* @__PURE__ */ jsx(Fragment, {});
+/**
+* Fires the role's surface demand event so modules gated on it load (see the `roles` option of
+* the surface module maker). Safe to call repeatedly: the surface manager claims the first
+* demand per role, which keeps mount cost flat where Surface instances are numerous (every card
+* in a grid mounts one) instead of re-entering the scheduler.
+*/
+var requestSurfaces = (surfaceManager, manager, role) => {
+	if (!manager || !surfaceManager.requestRole(role)) return;
+	EffectEx.runDetached(manager.activate(SurfacesRequested(role)).pipe(Effect.onExit((exit) => Exit.isFailure(exit) ? Effect.sync(() => surfaceManager.releaseRole(role)) : Effect.void)));
+};
 var WebComponentWrapper = memo(({ id, role, data, limit, definition, ...rest }) => {
 	const containerRef = useRef(null);
 	const elementRef = useRef(null);
@@ -732,7 +745,16 @@ var SurfaceComponent = memo(({ id: _id, type, data: dataProp, limit, placeholder
 	const data = useDefaultValue(dataProp, () => ({}));
 	const surfaceManager = useSurfaceManager();
 	const effectiveRole = type?.role ?? "";
-	const definitions = matchCandidates(useAtomValue(surfaceManager.candidatesAtom(effectiveRole)), effectiveRole, data);
+	const roleCandidates = useAtomValue(surfaceManager.candidatesAtom(effectiveRole));
+	const pluginManager = useOptionalPluginManager();
+	useEffect(() => {
+		requestSurfaces(surfaceManager, pluginManager, effectiveRole);
+	}, [
+		surfaceManager,
+		pluginManager,
+		effectiveRole
+	]);
+	const definitions = matchCandidates(roleCandidates, effectiveRole, data);
 	const candidates = limit != null ? definitions.slice(0, limit) : definitions;
 	const truncated = limit != null && definitions.length > limit;
 	const churnRef = useRef({
@@ -793,12 +815,19 @@ var matchCandidates = (definitions, role, data) => {
 */
 var useIsSurfaceAvailable = () => {
 	const surfaceManager = useSurfaceManager();
+	const pluginManager = useOptionalPluginManager();
 	const registry = useContext(RegistryContext);
 	return useCallback((args) => {
 		const effectiveRole = args.type?.role;
 		if (effectiveRole == null) return false;
-		return matchCandidates(registry.get(surfaceManager.candidatesAtom(effectiveRole)), effectiveRole, args.data).length > 0;
-	}, [surfaceManager, registry]);
+		const candidates = matchCandidates(registry.get(surfaceManager.candidatesAtom(effectiveRole)), effectiveRole, args.data);
+		if (candidates.length === 0) requestSurfaces(surfaceManager, pluginManager, effectiveRole);
+		return candidates.length > 0;
+	}, [
+		surfaceManager,
+		pluginManager,
+		registry
+	]);
 };
 //#endregion
 //#region src/ui/components/Surface/types.ts
@@ -930,6 +959,7 @@ var SurfaceManager = class {
 		return bucket ? Data.array(bucket) : EMPTY_CANDIDATES;
 	}).pipe(Atom.keepAlive));
 	#warnedInvalidIds = /* @__PURE__ */ new Set();
+	#requestedRoles = /* @__PURE__ */ new Set();
 	constructor(capabilities) {
 		this.#capabilities = capabilities;
 	}
@@ -937,6 +967,25 @@ var SurfaceManager = class {
 	candidatesAtom(role) {
 		return this.#candidates(role);
 	}
+	/**
+	* Claims the first surface demand for a role, returning `true` only to that first caller so
+	* it can fire the activation event. Subsequent calls — re-renders, repeated availability
+	* checks — return `false`.
+	*/
+	requestRole(role) {
+		if (role === "" || this.#requestedRoles.has(role)) return false;
+		this.#requestedRoles.add(role);
+		return true;
+	}
+	/**
+	* Returns a claimed role to the pool. The claim is taken before the dispatch is known to have
+	* happened, so a dispatch that fails or is interrupted (shutdown, a failed activation) must give
+	* it back — nothing else re-requests the role, and `useIsSurfaceAvailable`'s own retry is
+	* claimed away too, leaving every surface in that role permanently empty.
+	*/
+	releaseRole(role) {
+		this.#requestedRoles.delete(role);
+	}
 	/** Drops definitions with an invalid local id, warning once per id. */
 	#dropInvalid(definitions) {
 		return definitions.filter((definition) => {
@@ -946,7 +995,7 @@ var SurfaceManager = class {
 				log.warn("dropping surface with invalid id; the final segment must be camelCase (no hyphens or underscores)", { id: definition.id }, {
 					"~LogMeta": "~LogMeta",
 					F: __dxlog_file,
-					L: 88,
+					L: 115,
 					S: this
 				});
 			}