@dxos/app-framework 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/moon.yml

@@ -20,6 +20,7 @@ tasks:
       - '--entryPoint=src/common/activation-events.ts'
       - '--entryPoint=src/ui/index.ts'
       - '--entryPoint=src/testing/index.ts'
+      - '--entryPoint=src/testing/react.tsx'
       - '--entryPoint=src/core/url-loader.ts'
     deps:
       - compile-plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-framework",
-  "version": "0.8.4-main.9be5663bfe",
+  "version": "0.8.4-main.abd8ff62ef",
   "description": "A framework for building applications from composible plugins.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -77,6 +77,12 @@
       "node": "./dist/lib/node-esm/testing/index.mjs",
       "types": "./dist/types/src/testing/index.d.ts"
     },
+    "./testing-react": {
+      "source": "./src/testing/react.tsx",
+      "browser": "./dist/lib/browser/testing/react.mjs",
+      "node": "./dist/lib/node-esm/testing/react.mjs",
+      "types": "./dist/types/src/testing/react.d.ts"
+    },
     "./ui": {
       "source": "./src/ui/index.ts",
       "browser": "./dist/lib/browser/ui/index.mjs",
@@ -85,80 +91,48 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "ActivationEvent": [
-        "dist/types/src/activation-event/index.d.ts"
-      ],
-      "ActivationEvents": [
-        "dist/types/src/common/activation-events.d.ts"
-      ],
-      "Capabilities": [
-        "dist/types/src/common/capabilities.d.ts"
-      ],
-      "Capability": [
-        "dist/types/src/capability/index.d.ts"
-      ],
-      "Plugin": [
-        "dist/types/src/plugin/index.d.ts"
-      ],
-      "PluginManager": [
-        "dist/types/src/plugin-manager/index.d.ts"
-      ],
-      "UrlLoader": [
-        "dist/types/src/url-loader/index.d.ts"
-      ],
-      "vite-plugin": [
-        "dist/types/src/vite-plugin/index.d.ts"
-      ],
-      "cli": [
-        "dist/types/src/cli/index.d.ts"
-      ],
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ],
-      "ui": [
-        "dist/types/src/ui/index.d.ts"
-      ]
-    }
-  },
   "dependencies": {
     "@effect/cli": "0.73.2",
     "cjs-module-lexer": "^2.2.0",
-    "@dxos/async": "0.8.4-main.9be5663bfe",
-    "@dxos/debug": "0.8.4-main.9be5663bfe",
-    "@dxos/echo": "0.8.4-main.9be5663bfe",
-    "@dxos/invariant": "0.8.4-main.9be5663bfe",
-    "@dxos/errors": "0.8.4-main.9be5663bfe",
-    "@dxos/operation": "0.8.4-main.9be5663bfe",
-    "@dxos/react-error-boundary": "0.8.4-main.9be5663bfe",
-    "@dxos/util": "0.8.4-main.9be5663bfe",
-    "@dxos/log": "0.8.4-main.9be5663bfe",
-    "@dxos/web-context": "0.8.4-main.9be5663bfe",
-    "@dxos/react-hooks": "0.8.4-main.9be5663bfe",
-    "@dxos/web-context-react": "0.8.4-main.9be5663bfe",
-    "@dxos/effect": "0.8.4-main.9be5663bfe"
+    "@dxos/async": "0.8.4-main.abd8ff62ef",
+    "@dxos/debug": "0.8.4-main.abd8ff62ef",
+    "@dxos/compute": "0.8.4-main.abd8ff62ef",
+    "@dxos/effect": "0.8.4-main.abd8ff62ef",
+    "@dxos/errors": "0.8.4-main.abd8ff62ef",
+    "@dxos/invariant": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo": "0.8.4-main.abd8ff62ef",
+    "@dxos/log": "0.8.4-main.abd8ff62ef",
+    "@dxos/operation": "0.8.4-main.abd8ff62ef",
+    "@dxos/protocols": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-hooks": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui": "0.8.4-main.abd8ff62ef",
+    "@dxos/web-context": "0.8.4-main.abd8ff62ef",
+    "@dxos/ui-theme": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-error-boundary": "0.8.4-main.abd8ff62ef",
+    "@dxos/web-context-react": "0.8.4-main.abd8ff62ef",
+    "@dxos/util": "0.8.4-main.abd8ff62ef"
   },
   "devDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
     "@effect/platform": "0.94.4",
-    "@effect/vitest": "0.27.0",
+    "@effect/vitest": "0.29.0",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "~19.2.7",
     "effect": "3.20.0",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
     "typedoc": "0.28.1",
-    "vite": "^7.1.11",
-    "@dxos/echo-db": "0.8.4-main.9be5663bfe",
-    "@dxos/random": "0.8.4-main.9be5663bfe",
-    "@dxos/storybook-utils": "0.8.4-main.9be5663bfe",
-    "@dxos/test-utils": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui": "0.8.4-main.9be5663bfe",
-    "@dxos/ui-theme": "0.8.4-main.9be5663bfe"
+    "vite": "^8.0.10",
+    "@dxos/brand": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo-db": "0.8.4-main.abd8ff62ef",
+    "@dxos/storybook-utils": "0.8.4-main.abd8ff62ef",
+    "@dxos/random": "0.8.4-main.abd8ff62ef",
+    "@dxos/test-utils": "0.8.4-main.abd8ff62ef"
   },
   "peerDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
     "@effect/platform": "0.94.4",
+    "@testing-library/react": "^16.3.0",
     "effect": "3.20.0",
     "react": "~19.2.3",
     "react-dom": "~19.2.3"

package/src/common/capabilities.ts

@@ -9,7 +9,8 @@ import type * as Layer$ from 'effect/Layer';
 import type * as ManagedRuntime$ from 'effect/ManagedRuntime';
 import type { FC, PropsWithChildren } from 'react';
 
-import type { OperationInvoker as OperationInvoker$, OperationHandlerSet } from '@dxos/operation';
+import type { OperationHandlerSet } from '@dxos/compute';
+import { OperationInvoker as OperationInvoker$ } from '@dxos/operation';
 
 import { Capability as Capability$, type PluginManager as PluginManager$ } from '../core';
 import type {

package/src/common/operations.ts

@@ -4,7 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Operation } from '@dxos/operation';
+import { Operation } from '@dxos/compute';
 
 import { Capability } from '../core';
 import { Label } from './translations';

package/src/core/capability.ts

@@ -232,7 +232,7 @@ export const getModuleTag = (capability: unknown): string | undefined => {
  * export default Capability.makeModule(
  *   Effect.fnUntraced(function* (props: { observability: boolean }) {
  *     const invoker = yield* Capability.get(Capabilities.OperationInvoker);
- *     return contributes(Capabilities.IntentResolver, ...);
+ *     return contributes(Capabilities.OperationHandler, ...);
  *   })
  * );
  * ```

package/src/core/index.ts

@@ -6,5 +6,7 @@ export * as ActivationEvent from './activation-event';
 export * as Capability from './capability';
 export * as CapabilityManager from './capability-manager';
 export * as Plugin from './plugin';
+export * as PluginAssetCache from './plugin-asset-cache';
 export * as PluginManager from './plugin-manager';
+export * as PluginManifest from './plugin-manifest';
 export * as UrlLoader from './url-loader';

package/src/core/plugin-asset-cache.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { BaseError } from '@dxos/errors';
+
+/**
+ * Tagged error for cache operations. Construction sites supply `context.operation`
+ * (one of `'cache' | 'evict' | 'resolve' | 'list'`) and `context.pluginId` so
+ * downstream handlers can route on the failed call without scanning the message.
+ */
+export class PluginAssetCacheError extends BaseError.extend(
+  'PluginAssetCacheError',
+  'Plugin asset cache operation failed',
+) {}
+
+/**
+ * Per-platform offline cache for third-party plugin assets.
+ *
+ * Implementations live alongside their platform glue (composer-app's
+ * `asset-cache/{tauri,service-worker}.ts`); the no-op default is for tests
+ * and unsupported environments.
+ */
+export interface Cache {
+  /**
+   * Persist all listed URLs under the namespace of `pluginId`. Idempotent.
+   * The order of `urls` is significant — the first entry is treated as the entry module.
+   */
+  cache(pluginId: string, urls: readonly string[]): Effect.Effect<void, PluginAssetCacheError>;
+
+  /**
+   * Drop all assets for a plugin (uninstall).
+   */
+  evict(pluginId: string): Effect.Effect<void, PluginAssetCacheError>;
+
+  /**
+   * Resolves a plugin asset URL to a platform-specific cached URL when one is available.
+   * Returns the original URL when no cached copy exists or the platform serves cached
+   * responses transparently (e.g. service worker fetch interception on web).
+   */
+  resolve(pluginId: string, url: string): Effect.Effect<string, PluginAssetCacheError>;
+
+  /**
+   * List currently cached plugin ids (diagnostic).
+   */
+  list(): Effect.Effect<readonly string[], PluginAssetCacheError>;
+}
+
+/**
+ * No-op implementation. Used when no platform cache is registered (tests, unsupported environments).
+ * Plugins still load — they just have no offline guarantee.
+ */
+export const noop = (): Cache => ({
+  cache: () => Effect.void,
+  evict: () => Effect.void,
+  resolve: (_pluginId, url) => Effect.succeed(url),
+  list: () => Effect.succeed([] as readonly string[]),
+});

package/src/core/plugin-manager.test.ts

@@ -76,9 +76,10 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       const added = yield* manager.add(testMeta.id);
-      assert.isTrue(added);
+      assert.strictEqual(added, testPlugin);
       assert.deepStrictEqual(manager.getPlugins(), [testPlugin]);
-      const removed = manager.remove(testMeta.id);
+      assert.deepStrictEqual(manager.getEnabled(), []);
+      const removed = yield* manager.remove(testMeta.id);
       assert.isTrue(removed);
       assert.deepStrictEqual(manager.getPlugins(), []);
     }),
@@ -99,8 +100,10 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader: urlLoader });
       const added = yield* manager.add(urlLocator);
-      assert.isTrue(added);
+      assert.strictEqual(added, testPlugin);
       assert.deepStrictEqual(manager.getPlugins(), [testPlugin]);
+      assert.deepStrictEqual(manager.getEnabled(), []);
+      yield* manager.enable(added.meta.id);
       assert.deepStrictEqual(manager.getEnabled(), [testMeta.id]);
     }),
   );
@@ -219,6 +222,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       const error = yield* Effect.flip(manager.activate(FailEvent));
       assert.strictEqual(error.message, 'test');
     }),
@@ -251,6 +255,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       const error = yield* Effect.flip(manager.activate(DefectEvent));
 
       // Verify the error was caught and propagated.
@@ -297,6 +302,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       const error = yield* Effect.flip(manager.activate(DefectEvent));
 
       // Verify the error was caught and propagated.
@@ -361,6 +367,7 @@ describe('PluginManager', () => {
       );
 
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       yield* manager.activate(ActivationEvents.Startup);
       yield* activating.await;
       yield* activated.await;
@@ -411,6 +418,7 @@ describe('PluginManager', () => {
 
       {
         yield* manager.add(testMeta.id);
+        yield* manager.enable(testMeta.id);
         const result = yield* manager.activate(ActivationEvents.Startup);
         assert.isTrue(result);
         assert.deepStrictEqual(manager.getActive(), [testPlugin.modules[0].id]);
@@ -475,16 +483,19 @@ describe('PluginManager', () => {
       assert.strictEqual(manager.capabilities.getAll(Number).length, 0);
 
       yield* manager.add(Plugin1.meta.id);
+      yield* manager.enable(Plugin1.meta.id);
       yield* manager.activate(CountEvent);
       assert.deepStrictEqual(manager.getActive(), [plugin1.modules[0].id]);
       assert.strictEqual(manager.capabilities.getAll(Number).length, 1);
 
       yield* manager.add(Plugin2.meta.id);
+      yield* manager.enable(Plugin2.meta.id);
       yield* manager.activate(CountEvent);
       assert.deepStrictEqual(manager.getActive(), [plugin1.modules[0].id, plugin2.modules[0].id]);
       assert.strictEqual(manager.capabilities.getAll(Number).length, 2);
 
       yield* manager.add(Plugin3.meta.id);
+      yield* manager.enable(Plugin3.meta.id);
       yield* manager.activate(CountEvent);
       assert.deepStrictEqual(manager.getActive(), [
         plugin1.modules[0].id,
@@ -515,6 +526,7 @@ describe('PluginManager', () => {
       assert.strictEqual(manager.capabilities.getAll(String).length, 0);
 
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       yield* manager.activate(ActivationEvents.Startup);
       assert.deepStrictEqual(manager.getActive(), []);
       assert.strictEqual(manager.capabilities.getAll(String).length, 0);
@@ -548,6 +560,7 @@ describe('PluginManager', () => {
       assert.strictEqual(count, 0);
 
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       yield* manager.activate(CountEvent);
       assert.deepStrictEqual(manager.getActive(), [testPlugin.modules[0].id]);
       assert.strictEqual(manager.capabilities.getAll(String).length, 1);
@@ -572,7 +585,7 @@ describe('PluginManager', () => {
         Plugin.addModule({
           id: 'Count',
           activatesOn: ActivationEvents.Startup,
-          activatesBefore: [CountEvent],
+          firesBeforeActivation: [CountEvent],
           activate: Effect.fnUntraced(function* () {
             const capabilityManager = yield* Capability.Service;
             computeTotal(capabilityManager);
@@ -607,7 +620,9 @@ describe('PluginManager', () => {
       const manager = PluginManager.make({ pluginLoader });
       {
         yield* manager.add(Test.meta.id);
+        yield* manager.enable(Test.meta.id);
         yield* manager.add(Count.meta.id);
+        yield* manager.enable(Count.meta.id);
         yield* manager.activate(ActivationEvents.Startup);
         assert.deepStrictEqual(manager.getActive(), [
           ...testPlugin.modules.map((m) => m.id),
@@ -690,6 +705,7 @@ describe('PluginManager', () => {
       assert.strictEqual(pendingResetUpdates.count, 0);
 
       yield* manager.add(Plugin1.meta.id);
+      yield* manager.enable(Plugin1.meta.id);
       assert.strictEqual(pluginUpdates.count, 1);
       assert.strictEqual(enabledUpdates.count, 1);
       assert.strictEqual(modulesUpdates.count, 1);
@@ -706,6 +722,7 @@ describe('PluginManager', () => {
       assert.strictEqual(pendingResetUpdates.count, 0);
 
       yield* manager.add(Plugin2.meta.id);
+      yield* manager.enable(Plugin2.meta.id);
       assert.strictEqual(pluginUpdates.count, 2);
       assert.strictEqual(enabledUpdates.count, 2);
       assert.strictEqual(modulesUpdates.count, 2);
@@ -722,6 +739,7 @@ describe('PluginManager', () => {
       assert.strictEqual(pendingResetUpdates.count, 2);
 
       yield* manager.add(Plugin3.meta.id);
+      yield* manager.enable(Plugin3.meta.id);
       assert.strictEqual(pluginUpdates.count, 3);
       assert.strictEqual(enabledUpdates.count, 3);
       assert.strictEqual(modulesUpdates.count, 3);
@@ -746,7 +764,7 @@ describe('PluginManager', () => {
       assert.strictEqual(eventsFiredUpdates.count, 1);
       assert.strictEqual(pendingResetUpdates.count, 4);
 
-      manager.remove(Plugin1.meta.id);
+      yield* manager.remove(Plugin1.meta.id);
       assert.strictEqual(pluginUpdates.count, 4);
       assert.strictEqual(enabledUpdates.count, 4);
       assert.strictEqual(modulesUpdates.count, 4);
@@ -793,6 +811,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(SlowPlugin.meta.id);
+      yield* manager.enable(SlowPlugin.meta.id);
 
       // Fork the activation so we can control time with TestClock.
       const activationFiber = yield* Effect.fork(manager.activate(SlowEvent));
@@ -841,6 +860,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(ConcurrentPlugin.meta.id);
+      yield* manager.enable(ConcurrentPlugin.meta.id);
 
       // Fork two concurrent activations with DIFFERENT events.
       // Both events trigger the same module, so both will try to call _loadModule.
@@ -889,7 +909,9 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(Plugin1.meta.id);
+      yield* manager.enable(Plugin1.meta.id);
       yield* manager.add(Plugin2.meta.id);
+      yield* manager.enable(Plugin2.meta.id);
       yield* manager.activate(ActivationEvents.Startup);
       assert.strictEqual(manager.getActive().length, 2);
       assert.strictEqual(manager.capabilities.getAll(String).length, 1);
@@ -926,6 +948,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       yield* manager.activate(ActivationEvents.Startup);
       assert.isFalse(deactivated);
 
@@ -971,7 +994,9 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(Plugin1.meta.id);
+      yield* manager.enable(Plugin1.meta.id);
       yield* manager.add(Plugin2.meta.id);
+      yield* manager.enable(Plugin2.meta.id);
       yield* manager.activate(ActivationEvents.Startup);
 
       yield* manager.shutdown();
@@ -994,6 +1019,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       yield* manager.activate(ActivationEvents.Startup);
       assert.isTrue(manager.getEventsFired().length > 0);
 
@@ -1026,6 +1052,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
 
       const activationFiber = yield* Effect.fork(manager.activate(ActivationEvents.Startup));
       yield* activationStarted.await;
@@ -1062,6 +1089,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       yield* manager.activate(ActivationEvents.Startup);
 
       const pluginsBefore = manager.getPlugins();
@@ -1097,6 +1125,7 @@ describe('PluginManager', () => {
 
       const manager = PluginManager.make({ pluginLoader });
       yield* manager.add(testMeta.id);
+      yield* manager.enable(testMeta.id);
       yield* manager.activate(ActivationEvents.Startup);
       assert.strictEqual(activateCount, 1);
       assert.deepStrictEqual(manager.getActive(), [testPlugin.modules[0].id]);
@@ -1110,4 +1139,216 @@ describe('PluginManager', () => {
       assert.strictEqual(manager.capabilities.getAll(String).length, 1);
     }),
   );
+
+  describe('Plugin.lazy', () => {
+    const lazyMeta = { id: 'org.dxos.plugin.lazy', name: 'Lazy' };
+
+    it('exposes meta synchronously without invoking the loader', () => {
+      let loaderCalls = 0;
+      const Real = Plugin.make(Plugin.define<void>(lazyMeta));
+      const LazyTest = Plugin.lazy(lazyMeta, () => {
+        loaderCalls++;
+        return Promise.resolve({ default: Real });
+      });
+
+      assert.strictEqual(LazyTest.meta.id, lazyMeta.id);
+      assert.strictEqual(LazyTest.meta.name, 'Lazy');
+      assert.strictEqual(loaderCalls, 0);
+
+      const stub = LazyTest();
+      assert.strictEqual(stub.meta.id, lazyMeta.id);
+      assert.deepStrictEqual([...stub.modules], []);
+      assert.isTrue(Plugin.isLazy(stub));
+      assert.strictEqual(loaderCalls, 0);
+    });
+
+    it.effect('resolves the loader on enable and registers the real plugin modules', () =>
+      Effect.gen(function* () {
+        let loaderCalls = 0;
+        const Real = Plugin.define(lazyMeta).pipe(
+          Plugin.addModule({
+            id: 'Hello',
+            activatesOn: ActivationEvents.Startup,
+            activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+          }),
+          Plugin.make,
+        );
+        const LazyTest = Plugin.lazy(lazyMeta, () => {
+          loaderCalls++;
+          return Promise.resolve({ default: Real });
+        });
+
+        const lazyStub = LazyTest();
+        plugins = [lazyStub];
+
+        const manager = PluginManager.make({ pluginLoader });
+        yield* manager.add(lazyMeta.id);
+        // Loader has not been invoked yet — only meta is exposed.
+        assert.strictEqual(loaderCalls, 0);
+        assert.deepStrictEqual(manager.getModules(), []);
+
+        yield* manager.enable(lazyMeta.id);
+        assert.strictEqual(loaderCalls, 1);
+        // After enable the registered plugin should be the real one (not the stub),
+        // and its modules should be registered with the manager.
+        const registered = manager.getPlugins().find((p) => p.meta.id === lazyMeta.id);
+        assert.isDefined(registered);
+        assert.isFalse(Plugin.isLazy(registered!));
+        assert.strictEqual(registered!.modules.length, 1);
+
+        yield* manager.activate(ActivationEvents.Startup);
+        assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+      }),
+    );
+
+    it.effect('does not invoke the loader if the plugin is never enabled', () =>
+      Effect.gen(function* () {
+        let loaderCalls = 0;
+        const Real = Plugin.make(Plugin.define<void>(lazyMeta));
+        const LazyTest = Plugin.lazy(lazyMeta, () => {
+          loaderCalls++;
+          return Promise.resolve({ default: Real });
+        });
+        const lazyStub = LazyTest();
+        plugins = [lazyStub];
+
+        const manager = PluginManager.make({ pluginLoader });
+        yield* manager.add(lazyMeta.id);
+
+        // Activate an event that has no listeners — the lazy plugin must not load.
+        yield* manager.activate(ActivationEvents.Startup);
+        assert.strictEqual(loaderCalls, 0);
+      }),
+    );
+
+    it.effect('forwards factory options to the real plugin factory', () =>
+      Effect.gen(function* () {
+        type Opts = { greeting: string };
+        const RealFactory = (opts: Opts) =>
+          Plugin.define(lazyMeta).pipe(
+            Plugin.addModule({
+              id: 'Hello',
+              activatesOn: ActivationEvents.Startup,
+              activate: () => Effect.succeed(Capability.contributes(String, { string: opts.greeting })),
+            }),
+            Plugin.make,
+          )(undefined as void);
+
+        const RealFactoryWithMeta = Object.assign(RealFactory, { meta: lazyMeta });
+
+        const LazyTest = Plugin.lazy<Opts>(lazyMeta, () => Promise.resolve({ default: RealFactoryWithMeta }));
+        const lazyStub = LazyTest({ greeting: 'hola' });
+        plugins = [lazyStub];
+
+        const manager = PluginManager.make({ pluginLoader });
+        yield* manager.add(lazyMeta.id);
+        yield* manager.enable(lazyMeta.id);
+        yield* manager.activate(ActivationEvents.Startup);
+
+        const all = manager.capabilities.getAll(String);
+        assert.strictEqual(all.length, 1);
+        assert.strictEqual(all[0].string, 'hola');
+      }),
+    );
+
+    it.effect('wraps loader rejections in a descriptive error', () =>
+      Effect.gen(function* () {
+        const LazyTest = Plugin.lazy(lazyMeta, () =>
+          Promise.reject<{ default: Plugin.PluginFactory }>(new Error('boom')),
+        );
+        const lazyStub = LazyTest();
+        plugins = [lazyStub];
+
+        const manager = PluginManager.make({ pluginLoader });
+        yield* manager.add(lazyMeta.id);
+
+        const exit = yield* Effect.exit(manager.enable(lazyMeta.id));
+        assert.isTrue(Exit.isFailure(exit));
+        if (Exit.isFailure(exit)) {
+          const failure = Cause.failureOption(exit.cause);
+          assert.isTrue(failure._tag === 'Some');
+          if (failure._tag === 'Some') {
+            assert.isTrue(Plugin.LazyPluginError.is(failure.value));
+            assert.strictEqual((failure.value as Plugin.LazyPluginError).context.id, lazyMeta.id);
+            assert.strictEqual((failure.value as Plugin.LazyPluginError).context.reason, 'load-failed');
+          }
+        }
+      }),
+    );
+
+    it.effect('publishes a lazy:<id> error message when resolution fails', () =>
+      Effect.gen(function* () {
+        const LazyTest = Plugin.lazy(lazyMeta, () =>
+          Promise.reject<{ default: Plugin.PluginFactory }>(new Error('boom')),
+        );
+        const lazyStub = LazyTest();
+        plugins = [lazyStub];
+
+        const manager = PluginManager.make({ pluginLoader });
+        // Subscribe first so we don't miss the activating/error pair.
+        const queue = yield* PubSub.subscribe(manager.activation);
+        yield* manager.add(lazyMeta.id);
+        yield* Effect.exit(manager.enable(lazyMeta.id));
+        const messages = yield* Queue.takeAll(queue);
+
+        const errorMessage = [...messages].find((m) => m.module === `lazy:${lazyMeta.id}` && m.state === 'error');
+        assert.isDefined(errorMessage);
+        assert.isDefined(errorMessage!.error);
+      }).pipe(Effect.scoped),
+    );
+
+    it.effect('coalesces concurrent lazy resolutions of the same plugin id', () =>
+      Effect.gen(function* () {
+        let factoryCalls = 0;
+        const Real = (() => {
+          const inner = Plugin.make(
+            Plugin.define<void>(lazyMeta).pipe(
+              Plugin.addModule({
+                id: 'Hello',
+                activatesOn: ActivationEvents.Startup,
+                activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+              }),
+            ),
+          );
+          const factory = (() => {
+            factoryCalls++;
+            return inner();
+          }) as Plugin.PluginFactory;
+          return Object.assign(factory, { meta: lazyMeta });
+        })();
+        const LazyTest = Plugin.lazy(lazyMeta, () => Promise.resolve({ default: Real }));
+        const lazyStub = LazyTest();
+        // `manager.enable(id)` is implicitly called twice — once from the
+        // constructor's core/enabled chain, once from our explicit call. With
+        // coalescing, the underlying factory should still run exactly once.
+        plugins = [lazyStub];
+        const manager = PluginManager.make({ pluginLoader, plugins, core: [lazyMeta.id] });
+        yield* manager.enable(lazyMeta.id);
+        assert.strictEqual(factoryCalls, 1);
+      }),
+    );
+
+    it.effect('fails with a tagged error when the factory output is not a Plugin', () =>
+      Effect.gen(function* () {
+        const BadFactory = Object.assign(() => ({ not: 'a plugin' }) as any, { meta: lazyMeta });
+        const LazyTest = Plugin.lazy(lazyMeta, () => Promise.resolve({ default: BadFactory }));
+        const lazyStub = LazyTest();
+        plugins = [lazyStub];
+
+        const manager = PluginManager.make({ pluginLoader });
+        yield* manager.add(lazyMeta.id);
+
+        const exit = yield* Effect.exit(manager.enable(lazyMeta.id));
+        assert.isTrue(Exit.isFailure(exit));
+        if (Exit.isFailure(exit)) {
+          const failure = Cause.failureOption(exit.cause);
+          assert.isTrue(failure._tag === 'Some');
+          if (failure._tag === 'Some') {
+            assert.isTrue(Plugin.LazyPluginError.is(failure.value));
+            assert.strictEqual((failure.value as Plugin.LazyPluginError).context.reason, 'invalid-plugin');
+          }
+        }
+      }),
+    );
+  });
 });