@dxos/app-framework 0.10.0 → 0.11.1

package/dist/lib/chunk-url-loader.mjs

@@ -0,0 +1,347 @@
+import { t as __exportAll } from "./chunk-rolldown-runtime.mjs";
+import { isPlugin } from "./core/plugin.mjs";
+import { n as fetchManifest } from "./chunk-plugin-manifest.mjs";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { log } from "@dxos/log";
+import { BaseError } from "@dxos/errors";
+//#region src/core/plugin-asset-cache.ts
+var plugin_asset_cache_exports = /* @__PURE__ */ __exportAll({
+	PluginAssetCacheError: () => PluginAssetCacheError,
+	noop: () => noop
+});
+/**
+* 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.
+*/
+var PluginAssetCacheError = class extends BaseError.extend("PluginAssetCacheError", "Plugin asset cache operation failed") {};
+/**
+* No-op implementation. Used when no platform cache is registered (tests, unsupported environments).
+* Plugins still load — they just have no offline guarantee.
+*/
+var noop = () => ({
+	cache: () => Effect.void,
+	evict: () => Effect.void,
+	resolve: (_pluginId, url) => Effect.succeed(url),
+	list: () => Effect.succeed([])
+});
+//#endregion
+//#region src/core/url-loader.ts
+var url_loader_exports = /* @__PURE__ */ __exportAll({
+	RemotePluginLoadError: () => RemotePluginLoadError,
+	getInstalledVersion: () => getInstalledVersion,
+	getRemoteEntries: () => getRemoteEntries,
+	isLocalUrl: () => isLocalUrl,
+	make: () => make,
+	preload: () => preload,
+	setInstalledVersion: () => setInstalledVersion,
+	uninstall: () => uninstall
+});
+var __dxlog_file = "/__w/dxos/dxos/packages/sdk/app-framework/src/core/url-loader.ts";
+var 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.
+*/
+var RemotePluginLoadError = class extends BaseError.extend("RemotePluginLoadError", "Failed to load remote plugin") {};
+var defaultStorage = () => ({
+	get: (key) => localStorage.getItem(key),
+	set: (key, value) => localStorage.setItem(key, value)
+});
+var getPersistedRemotePlugins = (storage, key) => {
+	try {
+		const parsed = JSON.parse(storage.get(key) ?? "[]");
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((entry) => typeof entry === "object" && entry !== null && typeof entry.id === "string" && typeof entry.url === "string" && (entry.version === void 0 || typeof entry.version === "string"));
+	} catch {
+		return [];
+	}
+};
+var persistRemotePlugin = (storage, key, entry) => {
+	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
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 99,
+			S: void 0
+		});
+	}
+};
+var removePersistedRemotePlugin = (storage, key, pluginId) => {
+	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
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 108,
+			S: void 0
+		});
+	}
+};
+var isUrl = (locator) => {
+	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).
+*/
+var isLocalUrl = (locator) => {
+	try {
+		const hostname = new URL(locator).hostname.toLowerCase();
+		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).
+*/
+var getRemoteEntries = (options = {}) => {
+	return getPersistedRemotePlugins(options.storage ?? defaultStorage(), options.key ?? DEFAULT_KEY);
+};
+/**
+* Updates the persisted installed version for an already-stored remote plugin entry.
+* Does nothing if the plugin has not been persisted yet.
+*/
+var setInstalledVersion = (id, version, options = {}) => {
+	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
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 161,
+			S: void 0
+		});
+	}
+};
+/**
+* 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.
+*/
+var getInstalledVersion = (id, options = {}) => {
+	return getPersistedRemotePlugins(options.storage ?? defaultStorage(), options.key ?? DEFAULT_KEY).find((entry) => entry.id === id)?.version;
+};
+var normalizePluginExport = (mod) => {
+	const exported = mod.default;
+	if (isPlugin(exported)) return exported;
+	if (typeof exported === "function") {
+		const result = exported();
+		if (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.
+*/
+var loadStylesheets = (manifest, cache) => 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.key, url);
+		if (document.querySelector(`link[data-dxos-plugin-id="${manifest.key}"][href="${resolved}"]`)) continue;
+		const link = document.createElement("link");
+		link.rel = "stylesheet";
+		link.href = resolved;
+		link.dataset.dxosPluginId = manifest.key;
+		document.head.appendChild(link);
+	}
+});
+var loadFromManifest = (manifestUrl, cache) => Effect.gen(function* () {
+	log.info("loading remote plugin", { manifestUrl }, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 220,
+		S: this
+	});
+	const manifest = yield* fetchManifest(manifestUrl).pipe(Effect.mapError((cause) => new RemotePluginLoadError({
+		context: {
+			locator: manifestUrl,
+			reason: "manifest-error"
+		},
+		cause
+	})));
+	const wrapCacheError = Effect.mapError((cause) => new RemotePluginLoadError({
+		context: {
+			locator: manifestUrl,
+			reason: "cache-error"
+		},
+		cause
+	}));
+	if (!manifest.dev) {
+		const cachedUrls = manifest.assetUrls.indexOf(manifestUrl) === -1 ? [manifestUrl, ...manifest.assetUrls] : manifest.assetUrls;
+		yield* cache.cache(manifest.key, cachedUrls).pipe(wrapCacheError);
+	}
+	const entryUrl = manifest.dev ? manifest.entryUrl : yield* cache.resolve(manifest.key, manifest.entryUrl).pipe(wrapCacheError);
+	const plugin = normalizePluginExport(yield* Effect.tryPromise({
+		try: () => import(
+			/* @vite-ignore */
+			entryUrl
+),
+		catch: (cause) => new RemotePluginLoadError({
+			context: {
+				locator: manifestUrl,
+				reason: "import-failed"
+			},
+			cause
+		})
+	}));
+	if (!plugin.meta.profile.key || !plugin.meta.profile.name) return yield* Effect.fail(new RemotePluginLoadError({ context: {
+		locator: manifestUrl,
+		reason: "meta-missing"
+	} }));
+	if (plugin.meta.profile.key !== manifest.key) return yield* Effect.fail(new RemotePluginLoadError({ context: {
+		locator: manifestUrl,
+		reason: "meta-mismatch",
+		metaId: plugin.meta.profile.key,
+		manifestId: manifest.key
+	} }));
+	if (!manifest.dev) 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.
+*/
+var preload = (options = {}) => Effect.gen(function* () {
+	const storage = options.storage ?? defaultStorage();
+	const key = options.key ?? DEFAULT_KEY;
+	const cache = options.cache ?? noop();
+	const onPluginLoaded = options.onPluginLoaded;
+	const entries = getPersistedRemotePlugins(storage, key);
+	if (entries.length === 0) return [];
+	log.info("preloading remote plugins", { count: entries.length }, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 296,
+		S: this
+	});
+	const total = entries.length;
+	let loaded = 0;
+	return (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
+	}, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 302,
+		S: this
+	}))), Effect.option, 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
+	}, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 314,
+		S: this
+	}))), Effect.ignore)))), { concurrency: "unbounded" })).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.
+*/
+var make = (builtinPlugins, options = {}) => {
+	const storage = options.storage ?? defaultStorage();
+	const key = options.key ?? DEFAULT_KEY;
+	const cache = options.cache ?? noop();
+	return (locator) => Effect.gen(function* () {
+		const builtin = builtinPlugins.find((plugin) => plugin.meta.profile.key === locator);
+		if (builtin) return { plugin: builtin };
+		if (!isUrl(locator)) return yield* Effect.fail(new RemotePluginLoadError({ context: {
+			locator,
+			reason: "invalid-locator"
+		} }));
+		const { plugin, manifest } = yield* loadFromManifest(locator, cache);
+		if (!manifest.dev) {
+			if (builtinPlugins.find((existing) => existing.meta.profile.key === plugin.meta.profile.key)) return yield* Effect.fail(new RemotePluginLoadError({ context: {
+				locator,
+				reason: "duplicate-id",
+				id: plugin.meta.profile.key
+			} }));
+			persistRemotePlugin(storage, key, {
+				id: plugin.meta.profile.key,
+				url: locator
+			});
+		}
+		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.
+*/
+var uninstall = (pluginId, options = {}) => Effect.gen(function* () {
+	const storage = options.storage ?? defaultStorage();
+	const key = options.key ?? DEFAULT_KEY;
+	const cache = options.cache ?? 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
+	}, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 389,
+		S: this
+	}))), Effect.ignore);
+});
+//#endregion
+export { make as a, uninstall as c, isLocalUrl as i, url_loader_exports as l, getInstalledVersion as n, preload as o, getRemoteEntries as r, setInstalledVersion as s, RemotePluginLoadError as t, plugin_asset_cache_exports as u };
+
+//# sourceMappingURL=chunk-url-loader.mjs.map

package/dist/lib/chunk-url-loader.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-url-loader.mjs","names":[],"sources":["../../src/core/plugin-asset-cache.ts","../../src/core/url-loader.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Effect from 'effect/Effect';\n\nimport { BaseError } from '@dxos/errors';\n\n/**\n * Tagged error for cache operations. Construction sites supply `context.operation`\n * (one of `'cache' | 'evict' | 'resolve' | 'list'`) and `context.pluginId` so\n * downstream handlers can route on the failed call without scanning the message.\n */\nexport class PluginAssetCacheError extends BaseError.extend(\n  'PluginAssetCacheError',\n  'Plugin asset cache operation failed',\n) {}\n\n/**\n * Per-platform offline cache for third-party plugin assets.\n *\n * Implementations live alongside their platform glue (composer-app's\n * `asset-cache/{tauri,service-worker}.ts`); the no-op default is for tests\n * and unsupported environments.\n */\nexport interface Cache {\n  /**\n   * Persist all listed URLs under the namespace of `pluginId`. Idempotent.\n   * The order of `urls` is significant — the first entry is treated as the entry module.\n   */\n  cache(pluginId: string, urls: readonly string[]): Effect.Effect<void, PluginAssetCacheError>;\n\n  /**\n   * Drop all assets for a plugin (uninstall).\n   */\n  evict(pluginId: string): Effect.Effect<void, PluginAssetCacheError>;\n\n  /**\n   * Resolves a plugin asset URL to a platform-specific cached URL when one is available.\n   * Returns the original URL when no cached copy exists or the platform serves cached\n   * responses transparently (e.g. service worker fetch interception on web).\n   */\n  resolve(pluginId: string, url: string): Effect.Effect<string, PluginAssetCacheError>;\n\n  /**\n   * List currently cached plugin ids (diagnostic).\n   */\n  list(): Effect.Effect<readonly string[], PluginAssetCacheError>;\n}\n\n/**\n * No-op implementation. Used when no platform cache is registered (tests, unsupported environments).\n * Plugins still load — they just have no offline guarantee.\n */\nexport const noop = (): Cache => ({\n  cache: () => Effect.void,\n  evict: () => Effect.void,\n  resolve: (_pluginId, url) => Effect.succeed(url),\n  list: () => Effect.succeed([] as readonly string[]),\n});\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Effect from 'effect/Effect';\nimport * as Option from 'effect/Option';\n\nimport { BaseError } from '@dxos/errors';\nimport { log } from '@dxos/log';\n\nimport * as Plugin from './plugin';\nimport * as PluginAssetCache from './plugin-asset-cache';\nimport * as PluginManifest from './plugin-manifest';\n\nconst DEFAULT_KEY = 'org.dxos.composer.remote-plugins';\n\n/**\n * Tagged error for any failure during remote plugin loading. Construction sites\n * set `context.locator` and `context.reason` (one of `'invalid-locator' |\n * 'manifest-error' | 'cache-error' | 'import-failed' | 'meta-missing' |\n * 'meta-mismatch' | 'duplicate-id'`) so handlers can route on the failure mode.\n */\nexport class RemotePluginLoadError extends BaseError.extend('RemotePluginLoadError', 'Failed to load remote plugin') {}\n\n/**\n * Abstraction over key-value storage (defaults to localStorage).\n */\nexport type Storage = {\n  get(key: string): string | null;\n  set(key: string, value: string): void;\n};\n\n/**\n * Options for configuring the URL loader.\n */\nexport type Options = {\n  storage?: Storage;\n  key?: string;\n  /**\n   * Per-platform offline asset cache. Defaults to a no-op cache (no offline support).\n   */\n  cache?: PluginAssetCache.Cache;\n};\n\n/**\n * Options for the preload entry point. Adds an optional progress hook so hosts\n * can drive a boot-loader counter (`Loading plugins (3/12)…`) as remote plugin\n * manifests resolve. Resolution order is *not* deterministic — each entry races\n * its own network fetch — so callers should treat `loaded` as a count, not an\n * index. Failures are still swallowed; `loaded` advances on both success and\n * recoverable failure so the counter always reaches `total`.\n */\nexport type PreloadOptions = Options & {\n  onPluginLoaded?: (loaded: number, total: number) => void;\n};\n\n/**\n * Persisted record of a remote plugin that has been loaded previously.\n *\n * `url` is the URL of the plugin manifest (`plugin.json`), not the entry module.\n */\nexport type RemotePluginView = {\n  id: string;\n  url: string;\n  /** Installed version string, e.g. `v1.0.0`. Populated after install from a community catalog entry. */\n  version?: string;\n};\n\nconst defaultStorage = (): Storage => ({\n  get: (key) => localStorage.getItem(key),\n  set: (key, value) => localStorage.setItem(key, value),\n});\n\nconst getPersistedRemotePlugins = (storage: Storage, key: string): RemotePluginView[] => {\n  try {\n    const parsed: unknown = JSON.parse(storage.get(key) ?? '[]');\n    if (!Array.isArray(parsed)) {\n      return [];\n    }\n    return parsed.filter(\n      (entry): entry is RemotePluginView =>\n        typeof entry === 'object' &&\n        entry !== null &&\n        typeof entry.id === 'string' &&\n        typeof entry.url === 'string' &&\n        (entry.version === undefined || typeof entry.version === 'string'),\n    );\n  } catch {\n    return [];\n  }\n};\n\nconst persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginView): void => {\n  try {\n    const entries = getPersistedRemotePlugins(storage, key).filter((existing) => existing.id !== entry.id);\n    entries.push(entry);\n    storage.set(key, JSON.stringify(entries));\n  } catch (error) {\n    log.warn('failed to persist remote plugin entry', { entry, error });\n  }\n};\n\nconst removePersistedRemotePlugin = (storage: Storage, key: string, pluginId: string): void => {\n  try {\n    const entries = getPersistedRemotePlugins(storage, key).filter((existing) => existing.id !== pluginId);\n    storage.set(key, JSON.stringify(entries));\n  } catch (error) {\n    log.warn('failed to remove remote plugin entry', { pluginId, error });\n  }\n};\n\nconst isUrl = (locator: string): boolean => {\n  try {\n    const url = new URL(locator);\n    return url.protocol === 'http:' || url.protocol === 'https:';\n  } catch {\n    return false;\n  }\n};\n\n/**\n * Returns true when the URL's hostname is the local host (localhost, 127.0.0.1, or ::1).\n */\nexport const isLocalUrl = (locator: string): boolean => {\n  try {\n    const hostname = new URL(locator).hostname.toLowerCase();\n    // WHATWG URL returns '::1' without brackets in Node; some browsers return '[::1]'.\n    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';\n  } catch {\n    return false;\n  }\n};\n\n/**\n * Returns the list of remote plugin entries previously persisted by {@link make}.\n * Useful for UI code that needs to know which loaded plugins were installed from a URL\n * (e.g. to surface a tag on remote or localhost-hosted plugins).\n */\nexport const getRemoteEntries = (options: Options = {}): readonly RemotePluginView[] => {\n  const storage = options.storage ?? defaultStorage();\n  const key = options.key ?? DEFAULT_KEY;\n  return getPersistedRemotePlugins(storage, key);\n};\n\n/**\n * Updates the persisted installed version for an already-stored remote plugin entry.\n * Does nothing if the plugin has not been persisted yet.\n */\nexport const setInstalledVersion = (id: string, version: string, options: Options = {}): void => {\n  const storage = options.storage ?? defaultStorage();\n  const key = options.key ?? DEFAULT_KEY;\n  const entries = getPersistedRemotePlugins(storage, key);\n  const index = entries.findIndex((entry) => entry.id === id);\n  if (index === -1) {\n    return;\n  }\n  entries[index] = { ...entries[index], version };\n  try {\n    storage.set(key, JSON.stringify(entries));\n  } catch (error) {\n    log.warn('failed to update installed version for remote plugin', { id, version, error });\n  }\n};\n\n/**\n * Returns the installed version string for the given plugin id, or `undefined` if\n * the plugin was installed without version tracking (legacy install) or is not found.\n */\nexport const getInstalledVersion = (id: string, options: Options = {}): string | undefined => {\n  const storage = options.storage ?? defaultStorage();\n  const key = options.key ?? DEFAULT_KEY;\n  return getPersistedRemotePlugins(storage, key).find((entry) => entry.id === id)?.version;\n};\n\nconst normalizePluginExport = (mod: Record<string, unknown>): Plugin.Plugin => {\n  const exported = mod.default;\n  if (Plugin.isPlugin(exported)) {\n    return exported;\n  }\n  if (typeof exported === 'function') {\n    const result = (exported as () => unknown)();\n    if (Plugin.isPlugin(result)) {\n      return result;\n    }\n  }\n  throw new Error('Remote module default export is not a Plugin or a zero-arg plugin factory.');\n};\n\n/**\n * Loads stylesheets declared in the manifest by appending `<link rel=\"stylesheet\">` elements to the host document.\n * Each link is tagged with `data-dxos-plugin-id` so `uninstall` can clean them up.\n */\nconst loadStylesheets = (\n  manifest: PluginManifest.ResolvedManifest,\n  cache: PluginAssetCache.Cache,\n): Effect.Effect<void, PluginAssetCache.PluginAssetCacheError> =>\n  Effect.gen(function* () {\n    if (typeof document === 'undefined') {\n      return;\n    }\n    const cssUrls = manifest.assetUrls.filter((url) => url.endsWith('.css'));\n    for (const url of cssUrls) {\n      const resolved = yield* cache.resolve(manifest.key, url);\n      if (document.querySelector(`link[data-dxos-plugin-id=\"${manifest.key}\"][href=\"${resolved}\"]`)) {\n        continue;\n      }\n      const link = document.createElement('link');\n      link.rel = 'stylesheet';\n      link.href = resolved;\n      link.dataset.dxosPluginId = manifest.key;\n      document.head.appendChild(link);\n    }\n  });\n\nconst loadFromManifest = (\n  manifestUrl: string,\n  cache: PluginAssetCache.Cache,\n): Effect.Effect<{ plugin: Plugin.Plugin; manifest: PluginManifest.ResolvedManifest }, RemotePluginLoadError> =>\n  Effect.gen(function* () {\n    log.info('loading remote plugin', { manifestUrl });\n    const manifest = yield* PluginManifest.fetchManifest(manifestUrl).pipe(\n      Effect.mapError(\n        (cause) => new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'manifest-error' }, cause }),\n      ),\n    );\n    const wrapCacheError = Effect.mapError(\n      (cause: PluginAssetCache.PluginAssetCacheError) =>\n        new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'cache-error' }, cause }),\n    );\n    // Dev-mode manifests (served by `vite dev` via composerPlugin) skip the offline\n    // cache: chunks resolve on demand through the dev server, the asset list isn't\n    // enumerable up-front, and CSS arrives via runtime <style> injection rather than\n    // static <link> tags.\n    if (!manifest.dev) {\n      // Cache the manifest URL alongside its declared assets. Without it, `preload` on a\n      // subsequent reload would fetch the manifest from the network — and fail when the\n      // plugin's host is offline, dropping the plugin from the runtime.\n      const cachedUrls =\n        manifest.assetUrls.indexOf(manifestUrl) === -1 ? [manifestUrl, ...manifest.assetUrls] : manifest.assetUrls;\n      yield* cache.cache(manifest.key, cachedUrls).pipe(wrapCacheError);\n    }\n    const entryUrl = manifest.dev\n      ? manifest.entryUrl\n      : yield* cache.resolve(manifest.key, manifest.entryUrl).pipe(wrapCacheError);\n    const mod = yield* Effect.tryPromise({\n      try: () => import(/* @vite-ignore */ entryUrl),\n      catch: (cause) =>\n        new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'import-failed' }, cause }),\n    });\n    const plugin = normalizePluginExport(mod);\n    if (!plugin.meta.profile.key || !plugin.meta.profile.name) {\n      return yield* Effect.fail(\n        new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'meta-missing' } }),\n      );\n    }\n    if (plugin.meta.profile.key !== manifest.key) {\n      return yield* Effect.fail(\n        new RemotePluginLoadError({\n          context: {\n            locator: manifestUrl,\n            reason: 'meta-mismatch',\n            metaId: plugin.meta.profile.key,\n            manifestId: manifest.key,\n          },\n        }),\n      );\n    }\n    // Append stylesheets only after the entry imports cleanly and meta validation\n    // passes. If we did this earlier and the import or meta checks failed, the\n    // `<link>` tags would leak into the host DOM with no plugin to own their\n    // teardown — `uninstall` only runs for plugins the manager actually accepted.\n    // In dev mode, Vite injects styles at runtime via the module graph, so static\n    // <link> tags would duplicate (or 404, since CSS chunks aren't pre-built).\n    if (!manifest.dev) {\n      yield* loadStylesheets(manifest, cache).pipe(wrapCacheError);\n    }\n    return { plugin, manifest };\n  });\n\n/**\n * Preloads previously persisted remote plugins from storage. Per-entry failures\n * are logged and swallowed — the returned effect always succeeds with whichever\n * plugins loaded cleanly, so a single bad entry can't block the host's startup.\n */\nexport const preload = (options: PreloadOptions = {}): Effect.Effect<Plugin.Plugin[], never> =>\n  Effect.gen(function* () {\n    const storage = options.storage ?? defaultStorage();\n    const key = options.key ?? DEFAULT_KEY;\n    const cache = options.cache ?? PluginAssetCache.noop();\n    const onPluginLoaded = options.onPluginLoaded;\n\n    const entries = getPersistedRemotePlugins(storage, key);\n    if (entries.length === 0) {\n      return [];\n    }\n    log.info('preloading remote plugins', { count: entries.length });\n    const total = entries.length;\n    let loaded = 0;\n    const results = yield* Effect.all(\n      entries.map((entry) =>\n        loadFromManifest(entry.url, cache).pipe(\n          Effect.tapError((error) => Effect.sync(() => log.warn('failed to preload remote plugin', { entry, error }))),\n          Effect.option,\n          // Tick the progress hook on both success and recoverable failure so\n          // the counter monotonically reaches `total`. The host-supplied\n          // callback is best-effort: any synchronous throw flows through\n          // `Effect.try` and gets logged + ignored so a buggy hook can't\n          // derail the preload.\n          Effect.tap(() =>\n            Effect.sync(() => {\n              loaded += 1;\n            }).pipe(\n              Effect.andThen(Effect.try(() => onPluginLoaded?.(loaded, total))),\n              Effect.tapError((error) => Effect.sync(() => log.warn('onPluginLoaded threw', { loaded, total, error }))),\n              Effect.ignore,\n            ),\n          ),\n        ),\n      ),\n      { concurrency: 'unbounded' },\n    );\n    return results.flatMap((result) =>\n      Option.match(result, {\n        onNone: () => [],\n        onSome: ({ plugin }) => [plugin],\n      }),\n    );\n  });\n\n/**\n * Creates a plugin loader that resolves built-in plugins by ID or loads remote plugins from URLs.\n *\n * Remote URLs must point at a plugin manifest (`plugin.json`). The loader fetches the manifest,\n * eagerly persists every declared asset via the configured `PluginAssetCache`, then dynamic-imports\n * the entry module.\n */\nexport const make = (builtinPlugins: Plugin.Plugin[], options: Options = {}) => {\n  const storage = options.storage ?? defaultStorage();\n  const key = options.key ?? DEFAULT_KEY;\n  const cache = options.cache ?? PluginAssetCache.noop();\n\n  return (locator: string): Effect.Effect<{ plugin: Plugin.Plugin; dev?: boolean }, RemotePluginLoadError> =>\n    Effect.gen(function* () {\n      const builtin = builtinPlugins.find((plugin) => plugin.meta.profile.key === locator);\n      if (builtin) {\n        return { plugin: builtin };\n      }\n      if (!isUrl(locator)) {\n        return yield* Effect.fail(new RemotePluginLoadError({ context: { locator, reason: 'invalid-locator' } }));\n      }\n      const { plugin, manifest } = yield* loadFromManifest(locator, cache);\n      // Production manifests can't collide with a builtin id — that would make\n      // the registered plugin permanently inaccessible. Dev manifests are\n      // allowed to collide because the manager shadow primitive handles the\n      // overlap (dev plugin takes the id slot for the session, original is\n      // restored on uninstall or page reload).\n      if (!manifest.dev) {\n        const duplicate = builtinPlugins.find((existing) => existing.meta.profile.key === plugin.meta.profile.key);\n        if (duplicate) {\n          return yield* Effect.fail(\n            new RemotePluginLoadError({ context: { locator, reason: 'duplicate-id', id: plugin.meta.profile.key } }),\n          );\n        }\n        persistRemotePlugin(storage, key, { id: plugin.meta.profile.key, url: locator });\n      }\n      return { plugin, dev: manifest.dev };\n    });\n};\n\n/**\n * Removes a previously installed remote plugin: drops the persisted entry, evicts cached\n * assets, and removes any stylesheet `<link>` tags that {@link loadFromManifest} appended.\n *\n * Cache eviction failures are logged and swallowed — the persisted entry has already been\n * dropped so the user-visible state is consistent regardless of whether the platform\n * cache cooperated.\n */\nexport const uninstall = (pluginId: string, options: Options = {}): Effect.Effect<void, never> =>\n  Effect.gen(function* () {\n    const storage = options.storage ?? defaultStorage();\n    const key = options.key ?? DEFAULT_KEY;\n    const cache = options.cache ?? PluginAssetCache.noop();\n\n    removePersistedRemotePlugin(storage, key, pluginId);\n    if (typeof document !== 'undefined') {\n      document.querySelectorAll(`link[data-dxos-plugin-id=\"${pluginId}\"]`).forEach((node) => node.remove());\n    }\n    yield* cache.evict(pluginId).pipe(\n      Effect.tapError((error) => Effect.sync(() => log.warn('failed to evict plugin assets', { pluginId, error }))),\n      Effect.ignore,\n    );\n  });\n"],"mappings":"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"}

package/dist/lib/cli.mjs

@@ -0,0 +1,78 @@
+import { Service } from "./core/capability.mjs";
+import { a as make } from "./chunk-plugin-manager.mjs";
+import { Service as Service$1 } from "./core/plugin.mjs";
+import { AtomRegistry, Command as Command$1, Layer as Layer$1, PluginManager } from "./common/capabilities.mjs";
+import { Startup } from "./common/activation-events.mjs";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { invariant } from "@dxos/invariant";
+import * as Command from "@effect/cli/Command";
+//#region src/cli/cli.ts
+var __dxlog_file = "/__w/dxos/dxos/packages/sdk/app-framework/src/cli/cli.ts";
+var defaultPluginLoader = (plugins) => (id) => Effect.sync(() => {
+	const plugin = plugins.find((plugin) => plugin.meta.profile.key === id);
+	invariant(plugin, `Plugin not found: ${id}`, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 19,
+		S: void 0,
+		A: ["plugin", "`Plugin not found: ${id}`"]
+	});
+	return { plugin };
+});
+/**
+* Creates a CLI application with plugin support.
+* Similar to useApp but for CLI environments.
+*
+* @example
+* const plugins = [ClientPluginCLI()];
+* const manager = await createCliApp({ plugins });
+* const commands = manager.capabilities.getAll(Capabilities.Command);
+*
+* @param options.pluginManager Optional existing PluginManager instance.
+* @param options.pluginLoader Function to load plugins by ID.
+* @param options.plugins All plugins available to the application. Plugins whose `meta.profile.tags` includes `'system'` are treated as core.
+* @param options.enabled Enabled plugins.
+* @param options.safeMode Whether to enable safe mode, which disables optional plugins.
+*/
+var createCliApp = Effect.fn(function* ({ rootCommand, subCommands: subCommandsProp, pluginManager: pluginManagerProp, pluginLoader: pluginLoaderProp, plugins: pluginsProp = [], enabled: enabledProp = [], safeMode = false }) {
+	const plugins = pluginsProp;
+	const pluginLoader = pluginLoaderProp ?? defaultPluginLoader(plugins);
+	const manager = pluginManagerProp ?? make({
+		pluginLoader,
+		plugins,
+		enabled: safeMode ? [] : enabledProp
+	});
+	manager.capabilities.contribute({
+		interface: PluginManager,
+		implementation: manager,
+		module: "org.dxos.app-framework.plugin-manager"
+	});
+	manager.capabilities.contribute({
+		interface: AtomRegistry,
+		implementation: manager.registry,
+		module: "org.dxos.app-framework.atom-registry"
+	});
+	yield* manager.activate(Startup);
+	const layers = manager.capabilities.getAll(Layer$1);
+	const capabilityServiceLayer = Layer.succeed(Service, manager.capabilities);
+	const pluginServiceLayer = Layer.succeed(Service$1, manager);
+	const layer = Layer.mergeAll(capabilityServiceLayer, pluginServiceLayer, ...layers);
+	const pluginCommands = manager.capabilities.getAll(Command$1);
+	const subCommands = subCommandsProp ? [...subCommandsProp, ...pluginCommands] : pluginCommands;
+	invariant(subCommands.length > 0, "No subcommands provided", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 98,
+		S: this,
+		A: ["subCommands.length > 0", "'No subcommands provided'"]
+	});
+	return {
+		command: rootCommand.pipe(Command.withSubcommands(subCommands)),
+		layer
+	};
+});
+//#endregion
+export { createCliApp };
+
+//# sourceMappingURL=cli.mjs.map

package/dist/lib/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../../src/cli/cli.ts"],"sourcesContent":["//\n// Copyright 2025 DXOS.org\n//\n\nimport * as Command from '@effect/cli/Command';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\n\nimport { invariant } from '@dxos/invariant';\n\nimport { ActivationEvents, Capabilities } from '../common';\nimport { Capability, Plugin, PluginManager } from '../core';\n\nconst defaultPluginLoader =\n  (plugins: Plugin.Plugin[]): PluginManager.ManagerOptions['pluginLoader'] =>\n  (id: string) =>\n    Effect.sync(() => {\n      const plugin = plugins.find((plugin) => plugin.meta.profile.key === id);\n      invariant(plugin, `Plugin not found: ${id}`);\n      return { plugin };\n    });\n\ntype SubCommands = [Command.Command<any, any, any, any>, ...Array<Command.Command<any, any, any, any>>];\n\nexport type CreateCliAppOptions = {\n  rootCommand: Command.Command<any, any, any, any>;\n  subCommands?: SubCommands;\n  pluginManager?: PluginManager.PluginManager;\n  pluginLoader?: PluginManager.ManagerOptions['pluginLoader'];\n  plugins?: Plugin.Plugin[];\n  enabled?: string[];\n  safeMode?: boolean;\n};\n\n/**\n * Creates a CLI application with plugin support.\n * Similar to useApp but for CLI environments.\n *\n * @example\n * const plugins = [ClientPluginCLI()];\n * const manager = await createCliApp({ plugins });\n * const commands = manager.capabilities.getAll(Capabilities.Command);\n *\n * @param options.pluginManager Optional existing PluginManager instance.\n * @param options.pluginLoader Function to load plugins by ID.\n * @param options.plugins All plugins available to the application. Plugins whose `meta.profile.tags` includes `'system'` are treated as core.\n * @param options.enabled Enabled plugins.\n * @param options.safeMode Whether to enable safe mode, which disables optional plugins.\n */\nexport const createCliApp = Effect.fn(function* ({\n  rootCommand,\n  subCommands: subCommandsProp,\n  pluginManager: pluginManagerProp,\n  pluginLoader: pluginLoaderProp,\n  plugins: pluginsProp = [],\n  enabled: enabledProp = [],\n  safeMode = false,\n}: CreateCliAppOptions) {\n  const plugins = pluginsProp;\n  const pluginLoader = pluginLoaderProp ?? defaultPluginLoader(plugins);\n  const enabled = safeMode ? [] : enabledProp;\n  const manager =\n    pluginManagerProp ??\n    PluginManager.make({\n      pluginLoader,\n      plugins,\n      enabled,\n    });\n\n  manager.capabilities.contribute({\n    interface: Capabilities.PluginManager,\n    implementation: manager,\n    module: 'org.dxos.app-framework.plugin-manager',\n  });\n\n  manager.capabilities.contribute({\n    interface: Capabilities.AtomRegistry,\n    implementation: manager.registry,\n    module: 'org.dxos.app-framework.atom-registry',\n  });\n\n  // Activate startup event to load CLI commands and Effect layers.\n  yield* manager.activate(ActivationEvents.Startup);\n\n  // Gather all layers and merge them into a single layer.\n  const layers = manager.capabilities.getAll(Capabilities.Layer);\n  const capabilityServiceLayer = Layer.succeed(Capability.Service, manager.capabilities);\n  const pluginServiceLayer = Layer.succeed(Plugin.Service, manager);\n  const layer = (Layer.mergeAll as (...args: Layer.Layer<any, any, any>[]) => Layer.Layer<any, any, never>)(\n    capabilityServiceLayer,\n    pluginServiceLayer,\n    ...layers,\n  );\n\n  // Gather all commands and provide them to the root command.\n  const pluginCommands = manager.capabilities.getAll(Capabilities.Command);\n  const subCommands = subCommandsProp ? [...subCommandsProp, ...pluginCommands] : pluginCommands;\n  invariant(subCommands.length > 0, 'No subcommands provided');\n  const command = rootCommand.pipe(Command.withSubcommands(subCommands as SubCommands));\n\n  return { command, layer };\n});\n"],"mappings":";;;;;;;;;;;AAaA,IAAM,uBACH,aACA,OACC,OAAO,WAAW;CAChB,MAAM,SAAS,QAAQ,MAAM,WAAW,OAAO,KAAK,QAAQ,QAAQ,EAAE;CACtE,UAAU,QAAQ,qBAAqB,MAAG;EAAA,YAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA,KAAA;EAAA,GAAA,CAAA,UAAA,2BAAA;CAAA,CAAC;CAC3C,OAAO,EAAE,OAAO;AAClB,CAAC;;;;;;;;;;;;;;;;AA6BL,IAAa,eAAe,OAAO,GAAG,WAAW,EAC/C,aACA,aAAa,iBACb,eAAe,mBACf,cAAc,kBACd,SAAS,cAAc,CAAC,GACxB,SAAS,cAAc,CAAC,GACxB,WAAW,SACW;CACtB,MAAM,UAAU;CAChB,MAAM,eAAe,oBAAoB,oBAAoB,OAAO;CAEpE,MAAM,UACJ,qBACA,KAAmB;EACjB;EACA;EACA,SANY,WAAW,CAAC,IAAI;CAO9B,CAAC;CAEH,QAAQ,aAAa,WAAW;EAC9B,WAAW;EACX,gBAAgB;EAChB,QAAQ;CACV,CAAC;CAED,QAAQ,aAAa,WAAW;EAC9B,WAAW;EACX,gBAAgB,QAAQ;EACxB,QAAQ;CACV,CAAC;CAGD,OAAO,QAAQ,SAAS,OAAwB;CAGhD,MAAM,SAAS,QAAQ,aAAa,OAAO,OAAkB;CAC7D,MAAM,yBAAyB,MAAM,QAAQ,SAAoB,QAAQ,YAAY;CACrF,MAAM,qBAAqB,MAAM,QAAQ,WAAgB,OAAO;CAChE,MAAM,QAAS,MAAM,SACnB,wBACA,oBACA,GAAG,MACL;CAGA,MAAM,iBAAiB,QAAQ,aAAa,OAAO,SAAoB;CACvE,MAAM,cAAc,kBAAkB,CAAC,GAAG,iBAAiB,GAAG,cAAc,IAAI;CAChF,UAAU,YAAY,SAAS,GAAG,2BAAwB;EAAA,YAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA,CAAA,0BAAA,2BAAA;CAAA,CAAC;CAG3D,OAAO;EAAE,SAFO,YAAY,KAAK,QAAQ,gBAAgB,WAA0B,CAE1E;EAAS;CAAM;AAC1B,CAAC"}

package/dist/lib/common/activation-events.mjs

@@ -0,0 +1,35 @@
+import { t as __exportAll } from "../chunk-rolldown-runtime.mjs";
+import { make } from "../core/activation-event.mjs";
+//#region src/common/activation-events.ts
+var activation_events_exports = /* @__PURE__ */ __exportAll({
+	ProcessManagerReady: () => ProcessManagerReady,
+	SetupProcessManager: () => SetupProcessManager,
+	SetupReactSurface: () => SetupReactSurface,
+	Startup: () => Startup
+});
+/**
+* Fired when the app is started.
+*/
+var Startup = make("org.dxos.app-framework.event.startup");
+/**
+* Fired to load any newly available surfaces.
+*/
+var SetupReactSurface = make("org.dxos.app-framework.event.setupReactSurface");
+/**
+* Fired before the process manager is created.
+* Plugins should contribute their {@link Capabilities.LayerSpec} entries and
+* {@link Capabilities.OperationHandler} sets before this event fires so the
+* process manager's {@link ServiceResolver} and {@link OperationInvoker} pick
+* them up at construction time.
+*/
+var SetupProcessManager = make("org.dxos.app-framework.event.setupProcessManager");
+/**
+* Fired after the process manager runtime is ready and its derived capabilities
+* (`ProcessManagerRuntime`, `ServiceResolver`, `ProcessMonitor`, `OperationInvoker`)
+* have been contributed.
+*/
+var ProcessManagerReady = make("org.dxos.app-framework.event.processManagerReady");
+//#endregion
+export { ProcessManagerReady, SetupProcessManager, SetupReactSurface, Startup, activation_events_exports as t };
+
+//# sourceMappingURL=activation-events.mjs.map

package/dist/lib/common/activation-events.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-events.mjs","names":[],"sources":["../../../src/common/activation-events.ts"],"sourcesContent":["//\n// Copyright 2025 DXOS.org\n//\n\nimport { ActivationEvent as ActivationEvent$ } from '../core';\n\n/**\n * Fired when the app is started.\n */\nexport const Startup = ActivationEvent$.make('org.dxos.app-framework.event.startup');\n\n//\n// Dependent Events\n//\n\n/**\n * Fired to load any newly available surfaces.\n */\nexport const SetupReactSurface = ActivationEvent$.make('org.dxos.app-framework.event.setupReactSurface');\n\n/**\n * Fired before the process manager is created.\n * Plugins should contribute their {@link Capabilities.LayerSpec} entries and\n * {@link Capabilities.OperationHandler} sets before this event fires so the\n * process manager's {@link ServiceResolver} and {@link OperationInvoker} pick\n * them up at construction time.\n */\nexport const SetupProcessManager = ActivationEvent$.make('org.dxos.app-framework.event.setupProcessManager');\n\n//\n// Triggered Events\n//\n\n/**\n * Fired after the process manager runtime is ready and its derived capabilities\n * (`ProcessManagerRuntime`, `ServiceResolver`, `ProcessMonitor`, `OperationInvoker`)\n * have been contributed.\n */\nexport const ProcessManagerReady = ActivationEvent$.make('org.dxos.app-framework.event.processManagerReady');\n"],"mappings":";;;;;;;;;;;;AASA,IAAa,UAAU,KAAsB,sCAAsC;;;;AASnF,IAAa,oBAAoB,KAAsB,gDAAgD;;;;;;;;AASvG,IAAa,sBAAsB,KAAsB,kDAAkD;;;;;;AAW3G,IAAa,sBAAsB,KAAsB,kDAAkD"}