@dxos/app-framework 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

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

@@ -0,0 +1,178 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+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* () {
+        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);
+      }),
+    );
+
+    it.effect('fails for unknown non-URL locator', () =>
+      Effect.gen(function* () {
+        const loader = UrlLoader.make([]);
+        const exit = yield* Effect.exit(loader('not-a-url'));
+        assert.isTrue(exit._tag === 'Failure');
+      }),
+    );
+  });
+
+  describe('preload', () => {
+    it('returns empty array when storage has no entries', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => null,
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage has invalid JSON', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '{{invalid json',
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage contains null', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => 'null',
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage contains an object', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '{}',
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when entries are missing required fields', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '[{"title":"no url"}]',
+        set: () => {},
+      };
+      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

@@ -0,0 +1,337 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+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).
+ */
+export type Storage = {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+};
+
+/**
+ * Options for configuring the URL loader.
+ */
+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;
+};
+
+/**
+ * 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),
+  set: (key, value) => localStorage.setItem(key, value),
+});
+
+const getPersistedRemotePlugins = (storage: Storage, key: string): RemotePluginEntry[] => {
+  try {
+    const parsed: unknown = JSON.parse(storage.get(key) ?? '[]');
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(
+      (entry): entry is RemotePluginEntry =>
+        typeof entry === 'object' && entry !== null && typeof entry.id === 'string' && typeof entry.url === 'string',
+    );
+  } catch {
+    return [];
+  }
+};
+
+const persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginEntry): void => {
+  try {
+    const entries = getPersistedRemotePlugins(storage, key).filter((existing) => existing.id !== entry.id);
+    entries.push(entry);
+    storage.set(key, JSON.stringify(entries));
+  } catch (error) {
+    log.warn('failed to persist remote plugin entry', { entry, error });
+  }
+};
+
+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);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * 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)) {
+    return exported;
+  }
+  if (typeof exported === 'function') {
+    const result = (exported as () => unknown)();
+    if (Plugin.isPlugin(result)) {
+      return result;
+    }
+  }
+  throw new Error('Remote module default export is not a Plugin or a zero-arg plugin factory.');
+};
+
+/**
+ * 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. 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 = (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 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, 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 RemotePluginLoadError({ context: { locator, reason: 'invalid-locator' } }));
+      }
+      const { plugin } = yield* loadFromManifest(locator, cache);
+      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 });
+      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/index.ts

@@ -3,8 +3,7 @@
 //
 
 export * from './common';
-export * from './components';
+export * from './context';
 export * from './core';
-export * from './plugin-intent';
-export * from './plugin-settings';
-export * from './react';
+export * from './plugin-operation';
+export * from './plugin-runtime';

package/src/plugin-operation/OperationPlugin.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ActivationEvents } from '../common';
+import { Capability, Plugin } from '../core';
+import { meta } from './meta';
+
+const OperationInvoker = Capability.lazy('OperationInvoker', () => import('./invoker-capability'));
+const HistoryCapabilities = Capability.lazy('HistoryCapabilities', () => import('./history/capability'));
+
+export const OperationPlugin = Plugin.define(meta).pipe(
+  Plugin.addModule({
+    activatesOn: ActivationEvents.ManagedRuntimeReady,
+    firesBeforeActivation: [ActivationEvents.SetupOperationHandler],
+    firesAfterActivation: [ActivationEvents.OperationInvokerReady],
+    activate: OperationInvoker,
+  }),
+  Plugin.addModule({
+    activatesOn: ActivationEvents.OperationInvokerReady,
+    activate: HistoryCapabilities,
+  }),
+  Plugin.make,
+);

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

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { OperationInvoker } from '@dxos/operation';
+
+import { Capabilities } from '../../common';
+import { Capability } from '../../core';
+import * as HistoryTracker from './history-tracker';
+import * as UndoRegistry from './undo-registry';
+
+//
+// Capability Module - contributes both UndoRegistry and HistoryTracker.
+//
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    // Get the context for synchronous access in callbacks.
+    const capabilities = yield* Capability.Service;
+
+    // Create UndoRegistry.
+    const undoRegistry = UndoRegistry.make(() => capabilities.getAll(Capabilities.UndoMapping).flat());
+
+    // Create HistoryTracker (depends on UndoRegistry and OperationInvoker).
+    const invoker = yield* Capability.get(Capabilities.OperationInvoker);
+    // Cast to internal type - the factory always returns OperationInvokerInternal.
+    const historyTracker = HistoryTracker.make(invoker as OperationInvoker.OperationInvokerInternal, undoRegistry);
+
+    return [
+      Capability.contributes(Capabilities.UndoRegistry, undoRegistry),
+      Capability.contributes(Capabilities.HistoryTracker, historyTracker),
+    ];
+  }),
+);

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

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { BaseError } from '@dxos/errors';
+
+export class EmptyHistoryError extends BaseError.extend('EmptyHistoryError', 'Cannot undo: history is empty.') {}