@dxos/app-framework 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

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

@@ -5,19 +5,133 @@
 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('setInstalledVersion / getInstalledVersion', () => {
+    it('stores and retrieves an installed version', ({ expect }) => {
+      const stored: Record<string, string> = {};
+      const storage: UrlLoader.Storage = {
+        get: (key) => stored[key] ?? null,
+        set: (key, value) => {
+          stored[key] = value;
+        },
+      };
+
+      // Seed a remote entry without a version.
+      storage.set('test-key', JSON.stringify([{ id: 'org.dxos.plugin.foo', url: 'http://example.com/p.mjs' }]));
+
+      UrlLoader.setInstalledVersion('org.dxos.plugin.foo', 'v1.0.0', { storage, key: 'test-key' });
+
+      expect(UrlLoader.getInstalledVersion('org.dxos.plugin.foo', { storage, key: 'test-key' })).toBe('v1.0.0');
+    });
+
+    it('returns undefined when plugin is not persisted', ({ expect }) => {
+      const storage: UrlLoader.Storage = { get: () => null, set: () => {} };
+      expect(UrlLoader.getInstalledVersion('org.dxos.plugin.missing', { storage })).toBeUndefined();
+    });
+
+    it('overwrites an existing version when called again', ({ expect }) => {
+      const stored: Record<string, string> = {};
+      const storage: UrlLoader.Storage = {
+        get: (key) => stored[key] ?? null,
+        set: (key, value) => {
+          stored[key] = value;
+        },
+      };
+      storage.set(
+        'test-key',
+        JSON.stringify([{ id: 'org.dxos.plugin.foo', url: 'http://example.com/p.mjs', version: 'v1.0.0' }]),
+      );
+
+      UrlLoader.setInstalledVersion('org.dxos.plugin.foo', 'v2.0.0', { storage, key: 'test-key' });
+      expect(UrlLoader.getInstalledVersion('org.dxos.plugin.foo', { storage, key: 'test-key' })).toBe('v2.0.0');
+    });
+  });
+
   describe('make', () => {
     it.effect('resolves built-in plugins by meta.id', () =>
       Effect.gen(function* () {
         const testPlugin = Plugin.make(Plugin.define(testMeta))();
         const loader = UrlLoader.make([testPlugin]);
         const result = yield* loader(testMeta.id);
-        assert.strictEqual(result.meta.id, testMeta.id);
+        assert.strictEqual(result.plugin.meta.id, testMeta.id);
+        // Builtins are not dev plugins.
+        assert.notOk(result.dev);
       }),
     );
 
@@ -36,7 +150,7 @@ describe('UrlLoader', () => {
         get: () => null,
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
 
@@ -45,7 +159,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 +168,7 @@ describe('UrlLoader', () => {
         get: () => 'null',
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
 
@@ -63,7 +177,7 @@ describe('UrlLoader', () => {
         get: () => '{}',
         set: () => {},
       };
-      const result = await UrlLoader.preload({ storage });
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
       expect(result).toEqual([]);
     });
 
@@ -72,8 +186,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,35 @@ 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;
+};
+
+/**
+ * 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;
 };
 
-type RemotePluginEntry = { id: string; url: string };
+/**
+ * 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;
+  /** Installed version string, e.g. `v1.0.0`. Populated after install from a community catalog entry. */
+  version?: string;
+};
 
 const defaultStorage = (): Storage => ({
   get: (key) => localStorage.getItem(key),
@@ -58,6 +96,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 +114,60 @@ 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);
+};
+
+/**
+ * Updates the persisted installed version for an already-stored remote plugin entry.
+ * Does nothing if the plugin has not been persisted yet.
+ */
+export const setInstalledVersion = (id: string, version: string, options: Options = {}): void => {
+  const storage = options.storage ?? defaultStorage();
+  const key = options.key ?? DEFAULT_KEY;
+  const entries = getPersistedRemotePlugins(storage, key);
+  const index = entries.findIndex((entry) => entry.id === id);
+  if (index === -1) {
+    return;
+  }
+  entries[index] = { ...entries[index], version };
+  try {
+    storage.set(key, JSON.stringify(entries));
+  } catch (error) {
+    log.warn('failed to update installed version for remote plugin', { id, version, error });
+  }
+};
+
+/**
+ * Returns the installed version string for the given plugin id, or `undefined` if
+ * the plugin was installed without version tracking (legacy install) or is not found.
+ */
+export const getInstalledVersion = (id: string, options: Options = {}): string | undefined => {
+  const storage = options.storage ?? defaultStorage();
+  const key = options.key ?? DEFAULT_KEY;
+  return getPersistedRemotePlugins(storage, key).find((entry) => entry.id === id)?.version;
+};
+
 const normalizePluginExport = (mod: Record<string, unknown>): Plugin.Plugin => {
   const exported = mod.default;
   if (Plugin.isPlugin(exported)) {
@@ -81,68 +182,207 @@ 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 }),
+      ),
+    );
+    const wrapCacheError = Effect.mapError(
+      (cause: PluginAssetCache.PluginAssetCacheError) =>
+        new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'cache-error' }, cause }),
+    );
+    // Dev-mode manifests (served by `vite dev` via composerPlugin) skip the offline
+    // cache: chunks resolve on demand through the dev server, the asset list isn't
+    // enumerable up-front, and CSS arrives via runtime <style> injection rather than
+    // static <link> tags.
+    if (!manifest.dev) {
+      // 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;
+      yield* cache.cache(manifest.id, cachedUrls).pipe(wrapCacheError);
+    }
+    const entryUrl = manifest.dev
+      ? manifest.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.
+    // In dev mode, Vite injects styles at runtime via the module graph, so static
+    // <link> tags would duplicate (or 404, since CSS chunks aren't pre-built).
+    if (!manifest.dev) {
+      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.Plugin; dev?: boolean }, RemotePluginLoadError> =>
     Effect.gen(function* () {
       const builtin = builtinPlugins.find((plugin) => plugin.meta.id === locator);
       if (builtin) {
-        return builtin;
+        return { plugin: 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 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.`),
-        );
+      const { plugin, manifest } = yield* loadFromManifest(locator, cache);
+      // Production manifests can't collide with a builtin id — that would make
+      // the registered plugin permanently inaccessible. Dev manifests are
+      // allowed to collide because the manager shadow primitive handles the
+      // overlap (dev plugin takes the id slot for the session, original is
+      // restored on uninstall or page reload).
+      if (!manifest.dev) {
+        const duplicate = builtinPlugins.find((existing) => existing.meta.id === plugin.meta.id);
+        if (duplicate) {
+          return yield* Effect.fail(
+            new RemotePluginLoadError({ context: { locator, reason: 'duplicate-id', id: plugin.meta.id } }),
+          );
+        }
+        persistRemotePlugin(storage, key, { id: plugin.meta.id, url: locator });
       }
-      persistRemotePlugin(storage, key, { id: plugin.meta.id, url: locator });
-      return plugin;
+      return { plugin, dev: manifest.dev };
     });
 };
+
+/**
+ * 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({

package/src/plugin-operation/history/capability.ts

@@ -4,7 +4,7 @@
 
 import * as Effect from 'effect/Effect';
 
-import { type OperationInvoker } from '@dxos/operation';
+import { OperationInvoker } from '@dxos/operation';
 
 import { Capabilities } from '../../common';
 import { Capability } from '../../core';

package/src/plugin-operation/history/history-tracker.test.ts

@@ -10,7 +10,8 @@ import * as ManagedRuntime from 'effect/ManagedRuntime';
 import * as TestClock from 'effect/TestClock';
 import { describe, expect } from 'vitest';
 
-import { Operation, OperationInvoker } from '@dxos/operation';
+import { Operation } from '@dxos/compute';
+import { OperationInvoker } from '@dxos/operation';
 
 const testRuntime = ManagedRuntime.make(Layer.empty) as unknown as ManagedRuntime.ManagedRuntime<any, any>;
 

package/src/plugin-operation/history/history-tracker.ts

@@ -7,7 +7,7 @@ import * as Stream from 'effect/Stream';
 
 import { runAndForwardErrors } from '@dxos/effect';
 import { log } from '@dxos/log';
-import { type OperationInvoker } from '@dxos/operation';
+import { OperationInvoker } from '@dxos/operation';
 
 import { UndoOperation } from '../../common';
 import { EmptyHistoryError } from './errors';

package/src/plugin-operation/history/types.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { Operation } from '@dxos/operation';
+import type { Operation } from '@dxos/compute';
 
 /**
  * History entry stored by HistoryTracker.

package/src/plugin-operation/history/undo-mapping.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { Operation } from '@dxos/operation';
+import type { Operation } from '@dxos/compute';
 
 /**
  * Label type for translatable text (canonical definition in @dxos/app-toolkit).

package/src/plugin-operation/history/undo-registry.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { Operation } from '@dxos/operation';
+import type { Operation } from '@dxos/compute';
 
 import type * as UndoMapping from './undo-mapping';