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

package/src/core/plugin.ts

@@ -7,6 +7,7 @@ import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
 import * as Pipeable from 'effect/Pipeable';
 
+import { BaseError } from '@dxos/errors';
 import { invariant } from '@dxos/invariant';
 
 import type * as ActivationEvent from './activation-event';
@@ -89,16 +90,33 @@ export interface PluginModule {
   activatesOn: ActivationEvent.Events;
 
   /**
-   * Events which the plugin depends on being activated.
-   * Plugin is marked as needing reset a plugin activated by a dependent event is removed.
-   * Events are automatically activated before activation of the plugin.
+   * Events that this module fires *before* its own activation runs.
+   *
+   * When this module is asked to activate (via {@link activatesOn}), the
+   * plugin manager first activates every event listed here, ensuring any
+   * other modules that contribute to those events have completed before
+   * this module's {@link activate} body executes. These events are fired
+   * by the framework on this module's behalf — the module does not need
+   * to wait for some other code to fire them.
+   *
+   * The module is marked as needing reset if a module activated by one
+   * of these events is later removed.
+   *
+   * Read as: "this module fires these events before [its] activation".
    */
-  activatesBefore?: ActivationEvent.ActivationEvent[];
+  firesBeforeActivation?: ActivationEvent.ActivationEvent[];
 
   /**
-   * Events which this plugin triggers upon activation.
+   * Events that this module fires *after* its own activation completes.
+   *
+   * Once this module's {@link activate} body has finished executing, the
+   * plugin manager activates every event listed here, causing any modules
+   * listening on those events to run. These events are fired by the
+   * framework on this module's behalf as part of this module's lifecycle.
+   *
+   * Read as: "this module fires these events after [its] activation".
    */
-  activatesAfter?: ActivationEvent.ActivationEvent[];
+  firesAfterActivation?: ActivationEvent.ActivationEvent[];
 
   /**
    * Called when the module is activated.
@@ -116,15 +134,15 @@ class PluginModuleImpl implements PluginModule {
   readonly [PluginModuleTypeId]: PluginModuleTypeId = PluginModuleTypeId;
   readonly id: PluginModule['id'];
   readonly activatesOn: PluginModule['activatesOn'];
-  readonly activatesBefore?: PluginModule['activatesBefore'];
-  readonly activatesAfter?: PluginModule['activatesAfter'];
+  readonly firesBeforeActivation?: PluginModule['firesBeforeActivation'];
+  readonly firesAfterActivation?: PluginModule['firesAfterActivation'];
   readonly activate: PluginModule['activate'];
 
   constructor(options: Omit<PluginModule, typeof PluginModuleTypeId>) {
     this.id = options.id;
     this.activatesOn = options.activatesOn;
-    this.activatesBefore = options.activatesBefore;
-    this.activatesAfter = options.activatesAfter;
+    this.firesBeforeActivation = options.firesBeforeActivation;
+    this.firesAfterActivation = options.firesAfterActivation;
     this.activate = options.activate;
   }
 }
@@ -149,6 +167,11 @@ export type Meta = {
    */
   description?: string;
 
+  /**
+   * Name of the author or organization that created the plugin.
+   */
+  author?: string;
+
   /**
    * URL of home page.
    */
@@ -331,3 +354,105 @@ export function make<T>(builder: PluginBuilder<T>): PluginFactory<T> {
 
   return Object.assign(factory, { meta });
 }
+
+//
+// Lazy plugin loading
+//
+
+/**
+ * Symbol used to tag lazy plugin stubs with their loader closure.
+ * Hidden from enumeration so plugin manager iteration / serialization paths
+ * don't trip over it.
+ */
+const LazyTag: unique symbol = Symbol.for('@dxos/app-framework/Plugin/Lazy');
+
+/**
+ * Async loader for a lazy plugin's real implementation.
+ * The default export of the loaded module must be a `PluginFactory<T>` —
+ * i.e. the same shape `Plugin.make` produces.
+ */
+export type LazyLoader<T = void> = () => Promise<{ default: PluginFactory<T> }>;
+
+/** Internal: payload carried on a lazy stub. */
+type LazyPayload = { loader: LazyLoader<any>; options: unknown };
+
+/**
+ * Defines a lazy plugin whose body is loaded on first enable.
+ *
+ * The returned factory produces a stub `Plugin` that exposes `meta`
+ * synchronously (so callers can read `Plugin.meta.id` for free) but defers
+ * loading the real plugin's modules until the manager calls
+ * `Plugin.resolveLazy`. This lets the plugin's main entry point ship as a
+ * tiny meta-only chunk — the heavy capabilities, schema, React surfaces,
+ * etc. live behind the dynamic `import()` and become a separate Rollup
+ * chunk that is only fetched when the plugin is enabled.
+ *
+ * @example
+ * ```ts
+ * // plugin-markdown/src/index.ts
+ * import { Plugin } from '@dxos/app-framework';
+ * import { meta } from './meta';
+ *
+ * export const MarkdownPlugin = Plugin.lazy(meta, () => import('./MarkdownPlugin'));
+ *
+ * // plugin-markdown/src/MarkdownPlugin.tsx
+ * export const MarkdownPlugin = Plugin.define(meta).pipe(...heavy modules..., Plugin.make);
+ * export default MarkdownPlugin;
+ * ```
+ */
+export const lazy = <T = void>(meta: Meta, loader: LazyLoader<T>): PluginFactory<T> => {
+  const factory = (options: T): Plugin => {
+    const stub = new PluginImpl(meta, []);
+    Object.defineProperty(stub, LazyTag, {
+      value: { loader, options } satisfies LazyPayload,
+      enumerable: false,
+    });
+    return stub;
+  };
+  return Object.assign(factory, { meta });
+};
+
+/**
+ * Type guard for lazy plugin stubs produced by {@link lazy}.
+ */
+export const isLazy = (plugin: Plugin): boolean => LazyTag in plugin;
+
+/**
+ * Tagged error for failures during lazy plugin resolution. `context.id` is
+ * the lazy plugin's `meta.id`; `context.reason` discriminates the failure
+ * mode (`'load-failed' | 'missing-default' | 'invalid-plugin' |
+ * 'meta-mismatch'`) so callers can route on it.
+ */
+export class LazyPluginError extends BaseError.extend('LazyPluginError', 'Failed to resolve lazy plugin') {}
+
+/**
+ * Resolves a lazy plugin stub to its real plugin.
+ * Returns the plugin unchanged if it is not lazy. Failures surface as
+ * {@link LazyPluginError} with `context.reason` indicating the failure mode
+ * and (for loader failures) `cause` set to the original error.
+ */
+export const resolveLazy = (plugin: Plugin): Effect.Effect<Plugin, LazyPluginError> =>
+  Effect.gen(function* () {
+    if (!isLazy(plugin)) {
+      return plugin;
+    }
+    const id = plugin.meta.id;
+    const { loader, options } = (plugin as unknown as { [LazyTag]: LazyPayload })[LazyTag];
+    const mod = yield* Effect.tryPromise({
+      try: loader,
+      catch: (error) => new LazyPluginError({ context: { id, reason: 'load-failed' }, cause: error }),
+    });
+    if (!mod || typeof mod.default !== 'function') {
+      return yield* Effect.fail(new LazyPluginError({ context: { id, reason: 'missing-default' } }));
+    }
+    const result = mod.default(options);
+    if (!isPlugin(result)) {
+      return yield* Effect.fail(new LazyPluginError({ context: { id, reason: 'invalid-plugin' } }));
+    }
+    if (result.meta.id !== id) {
+      return yield* Effect.fail(
+        new LazyPluginError({ context: { id, reason: 'meta-mismatch', returnedId: result.meta.id } }),
+      );
+    }
+    return result;
+  });

package/src/core/url-loader.test.ts

@@ -5,12 +5,83 @@
 import { assert, describe, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 
+import { runAndForwardErrors } from '@dxos/effect';
+
 import * as Plugin from './plugin';
+import * as PluginAssetCache from './plugin-asset-cache';
 import * as UrlLoader from './url-loader';
 
 const testMeta = { id: 'org.dxos.plugin.test', name: 'Test' };
 
+const memoryStorage = (initial: string | null = null): UrlLoader.Storage => {
+  let value = initial;
+  return {
+    get: () => value,
+    set: (_key, next) => {
+      value = next;
+    },
+  };
+};
+
+type CacheCall = { method: 'cache' | 'evict' | 'resolve'; pluginId: string; urls?: readonly string[]; url?: string };
+
+const recordingCache = (): { cache: PluginAssetCache.Cache; calls: CacheCall[] } => {
+  const calls: CacheCall[] = [];
+  return {
+    calls,
+    cache: {
+      cache: (pluginId, urls) =>
+        Effect.sync(() => {
+          calls.push({ method: 'cache', pluginId, urls });
+        }),
+      evict: (pluginId) =>
+        Effect.sync(() => {
+          calls.push({ method: 'evict', pluginId });
+        }),
+      resolve: (pluginId, url) =>
+        Effect.sync(() => {
+          calls.push({ method: 'resolve', pluginId, url });
+          return url;
+        }),
+      list: () => Effect.succeed([] as readonly string[]),
+    },
+  };
+};
+
 describe('UrlLoader', () => {
+  describe('isLocalUrl', () => {
+    it('matches localhost, 127.0.0.1, and ::1', ({ expect }) => {
+      expect(UrlLoader.isLocalUrl('http://localhost:5173/plugin.mjs')).toBe(true);
+      expect(UrlLoader.isLocalUrl('https://LOCALHOST/plugin.mjs')).toBe(true);
+      expect(UrlLoader.isLocalUrl('http://127.0.0.1:8080/plugin.mjs')).toBe(true);
+      expect(UrlLoader.isLocalUrl('http://[::1]:8080/plugin.mjs')).toBe(true);
+    });
+
+    it('rejects public and malformed URLs', ({ expect }) => {
+      expect(UrlLoader.isLocalUrl('https://example.com/plugin.mjs')).toBe(false);
+      expect(UrlLoader.isLocalUrl('https://192.168.1.10/plugin.mjs')).toBe(false);
+      expect(UrlLoader.isLocalUrl('not a url')).toBe(false);
+      expect(UrlLoader.isLocalUrl('')).toBe(false);
+    });
+  });
+
+  describe('getRemoteEntries', () => {
+    it('returns persisted entries from storage', ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '[{"id":"p1","url":"http://localhost:5173/p.mjs"}]',
+        set: () => {},
+      };
+      expect(UrlLoader.getRemoteEntries({ storage })).toEqual([{ id: 'p1', url: 'http://localhost:5173/p.mjs' }]);
+    });
+
+    it('returns an empty array when storage is empty or malformed', ({ expect }) => {
+      const empty: UrlLoader.Storage = { get: () => null, set: () => {} };
+      const malformed: UrlLoader.Storage = { get: () => '{not json', set: () => {} };
+      expect(UrlLoader.getRemoteEntries({ storage: empty })).toEqual([]);
+      expect(UrlLoader.getRemoteEntries({ storage: malformed })).toEqual([]);
+    });
+  });
+
   describe('make', () => {
     it.effect('resolves built-in plugins by meta.id', () =>
       Effect.gen(function* () {
@@ -36,7 +107,7 @@ describe('UrlLoader', () => {
         get: () => null,
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
 
@@ -45,7 +116,7 @@ describe('UrlLoader', () => {
         get: () => '{{invalid json',
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
 
@@ -54,7 +125,7 @@ describe('UrlLoader', () => {
         get: () => 'null',
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
 
@@ -63,7 +134,7 @@ describe('UrlLoader', () => {
         get: () => '{}',
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
 
@@ -72,8 +143,36 @@ describe('UrlLoader', () => {
         get: () => '[{"title":"no url"}]',
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
   });
+
+  describe('uninstall', () => {
+    it('removes the persisted entry and evicts cached assets', async ({ expect }) => {
+      const storage = memoryStorage('[{"id":"p1","url":"https://x/p1.json"},{"id":"p2","url":"https://x/p2.json"}]');
+      const { cache, calls } = recordingCache();
+      await runAndForwardErrors(UrlLoader.uninstall('p1', { storage, cache }));
+      expect(UrlLoader.getRemoteEntries({ storage })).toEqual([{ id: 'p2', url: 'https://x/p2.json' }]);
+      expect(calls).toEqual([{ method: 'evict', pluginId: 'p1' }]);
+    });
+
+    it('still removes entry when cache eviction fails', async ({ expect }) => {
+      const storage = memoryStorage('[{"id":"p1","url":"https://x/p1.json"}]');
+      const cache: PluginAssetCache.Cache = {
+        cache: () => Effect.void,
+        evict: () =>
+          Effect.fail(
+            new PluginAssetCache.PluginAssetCacheError({
+              context: { operation: 'evict', pluginId: 'p1' },
+              cause: 'boom',
+            }),
+          ),
+        resolve: (_id, url) => Effect.succeed(url),
+        list: () => Effect.succeed([] as readonly string[]),
+      };
+      await runAndForwardErrors(UrlLoader.uninstall('p1', { storage, cache }));
+      expect(UrlLoader.getRemoteEntries({ storage })).toEqual([]);
+    });
+  });
 });

package/src/core/url-loader.ts

@@ -3,13 +3,25 @@
 //
 
 import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
 
+import { BaseError } from '@dxos/errors';
 import { log } from '@dxos/log';
 
 import * as Plugin from './plugin';
+import * as PluginAssetCache from './plugin-asset-cache';
+import * as PluginManifest from './plugin-manifest';
 
 const DEFAULT_KEY = 'org.dxos.composer.remote-plugins';
 
+/**
+ * Tagged error for any failure during remote plugin loading. Construction sites
+ * set `context.locator` and `context.reason` (one of `'invalid-locator' |
+ * 'manifest-error' | 'cache-error' | 'import-failed' | 'meta-missing' |
+ * 'meta-mismatch' | 'duplicate-id'`) so handlers can route on the failure mode.
+ */
+export class RemotePluginLoadError extends BaseError.extend('RemotePluginLoadError', 'Failed to load remote plugin') {}
+
 /**
  * Abstraction over key-value storage (defaults to localStorage).
  */
@@ -24,9 +36,33 @@ export type Storage = {
 export type Options = {
   storage?: Storage;
   key?: string;
+  /**
+   * Per-platform offline asset cache. Defaults to a no-op cache (no offline support).
+   */
+  cache?: PluginAssetCache.Cache;
 };
 
-type RemotePluginEntry = { id: string; url: string };
+/**
+ * Options for the preload entry point. Adds an optional progress hook so hosts
+ * can drive a boot-loader counter (`Loading plugins (3/12)…`) as remote plugin
+ * manifests resolve. Resolution order is *not* deterministic — each entry races
+ * its own network fetch — so callers should treat `loaded` as a count, not an
+ * index. Failures are still swallowed; `loaded` advances on both success and
+ * recoverable failure so the counter always reaches `total`.
+ */
+export type PreloadOptions = Options & {
+  onPluginLoaded?: (loaded: number, total: number) => void;
+};
+
+/**
+ * Persisted record of a remote plugin that has been loaded previously.
+ *
+ * `url` is the URL of the plugin manifest (`plugin.json`), not the entry module.
+ */
+export type RemotePluginEntry = {
+  id: string;
+  url: string;
+};
 
 const defaultStorage = (): Storage => ({
   get: (key) => localStorage.getItem(key),
@@ -58,6 +94,15 @@ const persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginE
   }
 };
 
+const removePersistedRemotePlugin = (storage: Storage, key: string, pluginId: string): void => {
+  try {
+    const entries = getPersistedRemotePlugins(storage, key).filter((existing) => existing.id !== pluginId);
+    storage.set(key, JSON.stringify(entries));
+  } catch (error) {
+    log.warn('failed to remove remote plugin entry', { pluginId, error });
+  }
+};
+
 const isUrl = (locator: string): boolean => {
   try {
     const url = new URL(locator);
@@ -67,6 +112,30 @@ const isUrl = (locator: string): boolean => {
   }
 };
 
+/**
+ * Returns true when the URL's hostname is the local host (localhost, 127.0.0.1, or ::1).
+ */
+export const isLocalUrl = (locator: string): boolean => {
+  try {
+    const hostname = new URL(locator).hostname.toLowerCase();
+    // WHATWG URL returns '::1' without brackets in Node; some browsers return '[::1]'.
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Returns the list of remote plugin entries previously persisted by {@link make}.
+ * Useful for UI code that needs to know which loaded plugins were installed from a URL
+ * (e.g. to surface a tag on remote or localhost-hosted plugins).
+ */
+export const getRemoteEntries = (options: Options = {}): readonly RemotePluginEntry[] => {
+  const storage = options.storage ?? defaultStorage();
+  const key = options.key ?? DEFAULT_KEY;
+  return getPersistedRemotePlugins(storage, key);
+};
+
 const normalizePluginExport = (mod: Record<string, unknown>): Plugin.Plugin => {
   const exported = mod.default;
   if (Plugin.isPlugin(exported)) {
@@ -81,68 +150,188 @@ const normalizePluginExport = (mod: Record<string, unknown>): Plugin.Plugin => {
   throw new Error('Remote module default export is not a Plugin or a zero-arg plugin factory.');
 };
 
-const loadRemotePlugin = async (url: string): Promise<Plugin.Plugin> => {
-  log.info('loading remote plugin', { url });
-  const mod = await import(/* @vite-ignore */ url);
-  const plugin = normalizePluginExport(mod);
-  if (!plugin.meta.id || !plugin.meta.name) {
-    throw new Error(`Remote plugin at ${url} is missing required meta.id or meta.name.`);
-  }
-  return plugin;
-};
+/**
+ * Loads stylesheets declared in the manifest by appending `<link rel="stylesheet">` elements to the host document.
+ * Each link is tagged with `data-dxos-plugin-id` so `uninstall` can clean them up.
+ */
+const loadStylesheets = (
+  manifest: PluginManifest.ResolvedManifest,
+  cache: PluginAssetCache.Cache,
+): Effect.Effect<void, PluginAssetCache.PluginAssetCacheError> =>
+  Effect.gen(function* () {
+    if (typeof document === 'undefined') {
+      return;
+    }
+    const cssUrls = manifest.assetUrls.filter((url) => url.endsWith('.css'));
+    for (const url of cssUrls) {
+      const resolved = yield* cache.resolve(manifest.id, url);
+      if (document.querySelector(`link[data-dxos-plugin-id="${manifest.id}"][href="${resolved}"]`)) {
+        continue;
+      }
+      const link = document.createElement('link');
+      link.rel = 'stylesheet';
+      link.href = resolved;
+      link.dataset.dxosPluginId = manifest.id;
+      document.head.appendChild(link);
+    }
+  });
+
+const loadFromManifest = (
+  manifestUrl: string,
+  cache: PluginAssetCache.Cache,
+): Effect.Effect<{ plugin: Plugin.Plugin; manifest: PluginManifest.ResolvedManifest }, RemotePluginLoadError> =>
+  Effect.gen(function* () {
+    log.info('loading remote plugin', { manifestUrl });
+    const manifest = yield* PluginManifest.fetchManifest(manifestUrl).pipe(
+      Effect.mapError(
+        (cause) => new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'manifest-error' }, cause }),
+      ),
+    );
+    // Cache the manifest URL alongside its declared assets. Without it, `preload` on a
+    // subsequent reload would fetch the manifest from the network — and fail when the
+    // plugin's host is offline, dropping the plugin from the runtime.
+    const cachedUrls =
+      manifest.assetUrls.indexOf(manifestUrl) === -1 ? [manifestUrl, ...manifest.assetUrls] : manifest.assetUrls;
+    const wrapCacheError = Effect.mapError(
+      (cause: PluginAssetCache.PluginAssetCacheError) =>
+        new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'cache-error' }, cause }),
+    );
+    yield* cache.cache(manifest.id, cachedUrls).pipe(wrapCacheError);
+    const entryUrl = yield* cache.resolve(manifest.id, manifest.entryUrl).pipe(wrapCacheError);
+    const mod = yield* Effect.tryPromise({
+      try: () => import(/* @vite-ignore */ entryUrl),
+      catch: (cause) =>
+        new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'import-failed' }, cause }),
+    });
+    const plugin = normalizePluginExport(mod);
+    if (!plugin.meta.id || !plugin.meta.name) {
+      return yield* Effect.fail(
+        new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'meta-missing' } }),
+      );
+    }
+    if (plugin.meta.id !== manifest.id) {
+      return yield* Effect.fail(
+        new RemotePluginLoadError({
+          context: {
+            locator: manifestUrl,
+            reason: 'meta-mismatch',
+            metaId: plugin.meta.id,
+            manifestId: manifest.id,
+          },
+        }),
+      );
+    }
+    // Append stylesheets only after the entry imports cleanly and meta validation
+    // passes. If we did this earlier and the import or meta checks failed, the
+    // `<link>` tags would leak into the host DOM with no plugin to own their
+    // teardown — `uninstall` only runs for plugins the manager actually accepted.
+    yield* loadStylesheets(manifest, cache).pipe(wrapCacheError);
+    return { plugin, manifest };
+  });
 
 /**
- * Preloads previously persisted remote plugins from storage.
+ * Preloads previously persisted remote plugins from storage. Per-entry failures
+ * are logged and swallowed — the returned effect always succeeds with whichever
+ * plugins loaded cleanly, so a single bad entry can't block the host's startup.
  */
-export const preload = async (options: Options = {}): Promise<Plugin.Plugin[]> => {
-  const storage = options.storage ?? defaultStorage();
-  const key = options.key ?? DEFAULT_KEY;
+export const preload = (options: PreloadOptions = {}): Effect.Effect<Plugin.Plugin[], never> =>
+  Effect.gen(function* () {
+    const storage = options.storage ?? defaultStorage();
+    const key = options.key ?? DEFAULT_KEY;
+    const cache = options.cache ?? PluginAssetCache.noop();
+    const onPluginLoaded = options.onPluginLoaded;
 
-  const entries = getPersistedRemotePlugins(storage, key);
-  if (entries.length === 0) {
-    return [];
-  }
-  log.info('preloading remote plugins', { count: entries.length });
-  const results = await Promise.allSettled(entries.map((entry) => loadRemotePlugin(entry.url)));
-  const plugins: Plugin.Plugin[] = [];
-  for (let index = 0; index < results.length; index++) {
-    const result = results[index];
-    if (result.status === 'fulfilled') {
-      plugins.push(result.value);
-    } else {
-      log.warn('failed to preload remote plugin', { entry: entries[index], error: result.reason });
+    const entries = getPersistedRemotePlugins(storage, key);
+    if (entries.length === 0) {
+      return [];
     }
-  }
-  return plugins;
-};
+    log.info('preloading remote plugins', { count: entries.length });
+    const total = entries.length;
+    let loaded = 0;
+    const results = yield* Effect.all(
+      entries.map((entry) =>
+        loadFromManifest(entry.url, cache).pipe(
+          Effect.tapError((error) => Effect.sync(() => log.warn('failed to preload remote plugin', { entry, error }))),
+          Effect.option,
+          // Tick the progress hook on both success and recoverable failure so
+          // the counter monotonically reaches `total`. The host-supplied
+          // callback is best-effort: any synchronous throw flows through
+          // `Effect.try` and gets logged + ignored so a buggy hook can't
+          // derail the preload.
+          Effect.tap(() =>
+            Effect.sync(() => {
+              loaded += 1;
+            }).pipe(
+              Effect.andThen(Effect.try(() => onPluginLoaded?.(loaded, total))),
+              Effect.tapError((error) => Effect.sync(() => log.warn('onPluginLoaded threw', { loaded, total, error }))),
+              Effect.ignore,
+            ),
+          ),
+        ),
+      ),
+      { concurrency: 'unbounded' },
+    );
+    return results.flatMap((result) =>
+      Option.match(result, {
+        onNone: () => [],
+        onSome: ({ plugin }) => [plugin],
+      }),
+    );
+  });
 
 /**
  * Creates a plugin loader that resolves built-in plugins by ID or loads remote plugins from URLs.
+ *
+ * Remote URLs must point at a plugin manifest (`plugin.json`). The loader fetches the manifest,
+ * eagerly persists every declared asset via the configured `PluginAssetCache`, then dynamic-imports
+ * the entry module.
  */
 export const make = (builtinPlugins: Plugin.Plugin[], options: Options = {}) => {
   const storage = options.storage ?? defaultStorage();
   const key = options.key ?? DEFAULT_KEY;
+  const cache = options.cache ?? PluginAssetCache.noop();
 
-  return (locator: string): Effect.Effect<Plugin.Plugin, Error> =>
+  return (locator: string): Effect.Effect<Plugin.Plugin, RemotePluginLoadError> =>
     Effect.gen(function* () {
       const builtin = builtinPlugins.find((plugin) => plugin.meta.id === locator);
       if (builtin) {
         return builtin;
       }
       if (!isUrl(locator)) {
-        return yield* Effect.fail(new Error(`Plugin not found and locator is not a URL: ${locator}`));
+        return yield* Effect.fail(new RemotePluginLoadError({ context: { locator, reason: 'invalid-locator' } }));
       }
-      const plugin = yield* Effect.tryPromise({
-        try: () => loadRemotePlugin(locator),
-        catch: (error) => new Error(`Failed to load remote plugin from ${locator}: ${error}`),
-      });
+      const { plugin } = yield* loadFromManifest(locator, cache);
       const duplicate = builtinPlugins.find((existing) => existing.meta.id === plugin.meta.id);
       if (duplicate) {
         return yield* Effect.fail(
-          new Error(`Remote plugin ${plugin.meta.id} conflicts with built-in plugin of the same id.`),
+          new RemotePluginLoadError({ context: { locator, reason: 'duplicate-id', id: plugin.meta.id } }),
         );
       }
       persistRemotePlugin(storage, key, { id: plugin.meta.id, url: locator });
       return plugin;
     });
 };
+
+/**
+ * Removes a previously installed remote plugin: drops the persisted entry, evicts cached
+ * assets, and removes any stylesheet `<link>` tags that {@link loadFromManifest} appended.
+ *
+ * Cache eviction failures are logged and swallowed — the persisted entry has already been
+ * dropped so the user-visible state is consistent regardless of whether the platform
+ * cache cooperated.
+ */
+export const uninstall = (pluginId: string, options: Options = {}): Effect.Effect<void, never> =>
+  Effect.gen(function* () {
+    const storage = options.storage ?? defaultStorage();
+    const key = options.key ?? DEFAULT_KEY;
+    const cache = options.cache ?? PluginAssetCache.noop();
+
+    removePersistedRemotePlugin(storage, key, pluginId);
+    if (typeof document !== 'undefined') {
+      document.querySelectorAll(`link[data-dxos-plugin-id="${pluginId}"]`).forEach((node) => node.remove());
+    }
+    yield* cache.evict(pluginId).pipe(
+      Effect.tapError((error) => Effect.sync(() => log.warn('failed to evict plugin assets', { pluginId, error }))),
+      Effect.ignore,
+    );
+  });

package/src/plugin-operation/OperationPlugin.ts

@@ -12,8 +12,8 @@ const HistoryCapabilities = Capability.lazy('HistoryCapabilities', () => import(
 export const OperationPlugin = Plugin.define(meta).pipe(
   Plugin.addModule({
     activatesOn: ActivationEvents.ManagedRuntimeReady,
-    activatesBefore: [ActivationEvents.SetupOperationHandler],
-    activatesAfter: [ActivationEvents.OperationInvokerReady],
+    firesBeforeActivation: [ActivationEvents.SetupOperationHandler],
+    firesAfterActivation: [ActivationEvents.OperationInvokerReady],
     activate: OperationInvoker,
   }),
   Plugin.addModule({