@dxos/app-framework 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

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

@@ -0,0 +1,75 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as PluginManifest from './plugin-manifest';
+
+describe('PluginManifest', () => {
+  describe('parse', () => {
+    test('resolves entry and assets relative to manifest URL', ({ expect }) => {
+      const resolved = PluginManifest.parse('https://example.com/plugins/foo/manifest.json', {
+        id: 'com.example.foo',
+        name: 'Foo',
+        version: '1.0.0',
+        assets: ['index.mjs', 'style.css', 'chunks/lib-abc.js'],
+      });
+      expect(resolved.id).toBe('com.example.foo');
+      expect(resolved.dev).toBe(false);
+      expect(resolved.entryUrl).toBe('https://example.com/plugins/foo/index.mjs');
+      expect(resolved.assetUrls).toEqual([
+        'https://example.com/plugins/foo/index.mjs',
+        'https://example.com/plugins/foo/style.css',
+        'https://example.com/plugins/foo/chunks/lib-abc.js',
+      ]);
+    });
+
+    test('throws if the canonical entry filename is not listed in assets', ({ expect }) => {
+      expect(() =>
+        PluginManifest.parse('https://example.com/manifest.json', {
+          id: 'a',
+          name: 'A',
+          version: '0.0.1',
+          assets: ['style.css'],
+        }),
+      ).toThrow();
+    });
+
+    test('throws on missing required fields', ({ expect }) => {
+      expect(() =>
+        PluginManifest.parse('https://example.com/manifest.json', {
+          name: 'A',
+          version: '0.0.1',
+          assets: ['index.mjs'],
+        }),
+      ).toThrow();
+    });
+
+    test('devEntry flips dev mode and resolves the entry against the manifest URL', ({ expect }) => {
+      const resolved = PluginManifest.parse('http://localhost:3967/manifest.json', {
+        id: 'com.example.foo',
+        name: 'Foo',
+        version: '0.0.0-dev',
+        assets: [],
+        devEntry: 'src/plugin.tsx',
+      });
+      expect(resolved.dev).toBe(true);
+      expect(resolved.entryUrl).toBe('http://localhost:3967/src/plugin.tsx');
+      expect(resolved.assetUrls).toEqual([]);
+    });
+
+    test('devEntry waives the canonical-entry-in-assets requirement', ({ expect }) => {
+      // No `index.mjs` in assets — would throw without devEntry.
+      expect(() =>
+        PluginManifest.parse('http://localhost:3967/manifest.json', {
+          id: 'a',
+          name: 'A',
+          version: '0.0.0-dev',
+          assets: [],
+          devEntry: 'src/plugin.tsx',
+        }),
+      ).not.toThrow();
+    });
+  });
+});

package/src/core/plugin-manifest.ts

@@ -0,0 +1,134 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import * as HttpClientResponse from '@effect/platform/HttpClientResponse';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { BaseError } from '@dxos/errors';
+import { PLUGIN_ENTRY_FILENAME } from '@dxos/protocols';
+
+/**
+ * Default port the Vite plugin (`composerPlugin`) binds the dev server to.
+ *
+ * Shared single source of truth — `composerPlugin` reads it as the default
+ * port, and the host's "Load Dev Plugin" affordance pre-fills the manifest URL
+ * with `http://localhost:${PLUGIN_DEV_SERVER_PORT}/manifest.json`. Lives in
+ * app-framework rather than `@dxos/protocols` because the constant is a
+ * client-side convention (host loader + Vite plugin) rather than a wire-level
+ * protocol.
+ */
+export const PLUGIN_DEV_SERVER_PORT = 3967;
+
+/**
+ * Tagged error for manifest fetch / parse failures. Construction sites set
+ * `context.manifestUrl` and `context.reason` (one of `'fetch-failed' |
+ * 'http-error' | 'parse-failed' | 'invalid'`) so handlers can route on the
+ * specific failure mode.
+ */
+export class PluginManifestError extends BaseError.extend('PluginManifestError', 'Plugin manifest is invalid') {}
+
+/**
+ * Schema for a third-party plugin manifest.
+ *
+ * Production manifests are published as a sibling of the plugin's entry module
+ * ({@link PLUGIN_ENTRY_FILENAME}) and advertise every file the plugin needs at
+ * runtime so the host can eagerly cache them for offline use.
+ *
+ * Dev manifests (served by `vite dev` via {@link composerPlugin}) set `devEntry`
+ * to point at the unbundled source entry. The host's loader treats the presence
+ * of `devEntry` as the dev-mode signal: it imports the entry directly from the
+ * dev server, skips eager asset caching, and skips static stylesheet injection
+ * (Vite handles CSS via runtime `<style>` injection during HMR). `assets` is not
+ * required to enumerate every file in dev mode — chunks and styles flow through
+ * the dev server on demand.
+ */
+export const Manifest = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  version: Schema.String,
+  assets: Schema.Array(Schema.String),
+  devEntry: Schema.String.pipe(Schema.optional),
+});
+
+export type Manifest = Schema.Schema.Type<typeof Manifest>;
+
+/**
+ * Resolved manifest with all asset paths converted to absolute URLs.
+ *
+ * `dev` reflects whether the source manifest declared a `devEntry`. Loaders branch
+ * on this to skip offline caching and stylesheet injection — both are no-ops (or
+ * actively wrong) when the plugin is being served by a Vite dev server.
+ */
+export type ResolvedManifest = {
+  id: string;
+  name: string;
+  version: string;
+  entryUrl: string;
+  assetUrls: readonly string[];
+  dev: boolean;
+};
+
+/**
+ * Resolves a parsed manifest's relative asset paths against the manifest's URL.
+ * In dev mode the entry comes from `devEntry`; otherwise it's the canonical
+ * {@link PLUGIN_ENTRY_FILENAME} sitting next to the manifest.
+ */
+const resolve = (manifestUrl: string, manifest: Manifest): ResolvedManifest => {
+  const dev = manifest.devEntry !== undefined;
+  return {
+    id: manifest.id,
+    name: manifest.name,
+    version: manifest.version,
+    entryUrl: new URL(dev ? manifest.devEntry! : PLUGIN_ENTRY_FILENAME, manifestUrl).toString(),
+    assetUrls: manifest.assets.map((asset) => new URL(asset, manifestUrl).toString()),
+    dev,
+  };
+};
+
+/**
+ * Synchronous decode + validate + resolve for an in-memory manifest payload. Used
+ * by tests and tooling that have the manifest body already loaded; the runtime
+ * path goes through {@link fetchManifest}.
+ */
+export const parse = (manifestUrl: string, payload: unknown): ResolvedManifest => {
+  const manifest = Schema.decodeUnknownSync(Manifest)(payload);
+  if (manifest.devEntry === undefined && !manifest.assets.includes(PLUGIN_ENTRY_FILENAME)) {
+    throw new Error(`Manifest at ${manifestUrl} does not list ${PLUGIN_ENTRY_FILENAME} in assets.`);
+  }
+  return resolve(manifestUrl, manifest);
+};
+
+/**
+ * Fetches and parses a manifest from the given URL via Effect's HTTP client and
+ * Schema-driven JSON decoding. All failure modes surface as a single tagged
+ * {@link PluginManifestError}; callers route on `error.context.reason`.
+ */
+export const fetchManifest = (manifestUrl: string): Effect.Effect<ResolvedManifest, PluginManifestError> =>
+  Effect.gen(function* () {
+    const response = yield* HttpClientRequest.get(manifestUrl).pipe(
+      HttpClient.execute,
+      Effect.mapError((cause) => new PluginManifestError({ context: { manifestUrl, reason: 'fetch-failed' }, cause })),
+    );
+    if (response.status >= 400) {
+      return yield* Effect.fail(
+        new PluginManifestError({ context: { manifestUrl, reason: 'http-error', status: response.status } }),
+      );
+    }
+    const manifest = yield* HttpClientResponse.schemaBodyJson(Manifest)(response).pipe(
+      Effect.mapError((cause) => new PluginManifestError({ context: { manifestUrl, reason: 'parse-failed' }, cause })),
+    );
+    if (manifest.devEntry === undefined && !manifest.assets.includes(PLUGIN_ENTRY_FILENAME)) {
+      return yield* Effect.fail(
+        new PluginManifestError({
+          context: { manifestUrl, reason: 'invalid' },
+          cause: `assets does not include ${PLUGIN_ENTRY_FILENAME}`,
+        }),
+      );
+    }
+    return resolve(manifestUrl, manifest);
+  }).pipe(Effect.scoped, Effect.provide(FetchHttpClient.layer));

package/src/core/plugin.ts

@@ -7,7 +7,9 @@ import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
 import * as Pipeable from 'effect/Pipeable';
 
+import { BaseError } from '@dxos/errors';
 import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
 
 import type * as ActivationEvent from './activation-event';
 import * as Capability from './capability';
@@ -45,6 +47,13 @@ export const activate = (event: ActivationEvent.ActivationEvent): Effect.Effect<
 export const reset = (event: ActivationEvent.ActivationEvent): Effect.Effect<boolean, Error, Service> =>
   Effect.flatMap(Service, (manager) => manager.reset(event));
 
+/**
+ * Shuts down the plugin manager, deactivating all active modules and clearing lifecycle state.
+ * Accesses the PluginManager via the Effect layer system.
+ */
+export const shutdown = (): Effect.Effect<boolean, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.shutdown());
+
 /**
  * Computes a module ID from plugin ID and export name.
  */
@@ -82,16 +91,33 @@ export interface PluginModule {
   activatesOn: ActivationEvent.Events;
 
   /**
-   * Events which the plugin depends on being activated.
-   * Plugin is marked as needing reset a plugin activated by a dependent event is removed.
-   * Events are automatically activated before activation of the plugin.
+   * Events that this module fires *before* its own activation runs.
+   *
+   * When this module is asked to activate (via {@link activatesOn}), the
+   * plugin manager first activates every event listed here, ensuring any
+   * other modules that contribute to those events have completed before
+   * this module's {@link activate} body executes. These events are fired
+   * by the framework on this module's behalf — the module does not need
+   * to wait for some other code to fire them.
+   *
+   * The module is marked as needing reset if a module activated by one
+   * of these events is later removed.
+   *
+   * Read as: "this module fires these events before [its] activation".
    */
-  activatesBefore?: ActivationEvent.ActivationEvent[];
+  firesBeforeActivation?: ActivationEvent.ActivationEvent[];
 
   /**
-   * Events which this plugin triggers upon activation.
+   * Events that this module fires *after* its own activation completes.
+   *
+   * Once this module's {@link activate} body has finished executing, the
+   * plugin manager activates every event listed here, causing any modules
+   * listening on those events to run. These events are fired by the
+   * framework on this module's behalf as part of this module's lifecycle.
+   *
+   * Read as: "this module fires these events after [its] activation".
    */
-  activatesAfter?: ActivationEvent.ActivationEvent[];
+  firesAfterActivation?: ActivationEvent.ActivationEvent[];
 
   /**
    * Called when the module is activated.
@@ -109,39 +135,60 @@ class PluginModuleImpl implements PluginModule {
   readonly [PluginModuleTypeId]: PluginModuleTypeId = PluginModuleTypeId;
   readonly id: PluginModule['id'];
   readonly activatesOn: PluginModule['activatesOn'];
-  readonly activatesBefore?: PluginModule['activatesBefore'];
-  readonly activatesAfter?: PluginModule['activatesAfter'];
+  readonly firesBeforeActivation?: PluginModule['firesBeforeActivation'];
+  readonly firesAfterActivation?: PluginModule['firesAfterActivation'];
   readonly activate: PluginModule['activate'];
 
   constructor(options: Omit<PluginModule, typeof PluginModuleTypeId>) {
     this.id = options.id;
     this.activatesOn = options.activatesOn;
-    this.activatesBefore = options.activatesBefore;
-    this.activatesAfter = options.activatesAfter;
+    this.firesBeforeActivation = options.firesBeforeActivation;
+    this.firesAfterActivation = options.firesAfterActivation;
     this.activate = options.activate;
   }
 }
 
 export type Meta = {
   /**
-   * Globally unique ID.
-   *
-   * Expected to be in the form of a valid URL.
-   *
-   * @example org.dxos.plugin.example
+   * Bare NSID (the name portion of {@link key}, e.g. `org.dxos.plugin.example`).
+   * Stable across versions; used for module-id namespacing, i18n namespaces,
+   * enable/disable, and registry lookups. Derived from `key` by {@link makeMeta} —
+   * do not set directly.
    */
   id: string;
 
+  /**
+   * Canonical identity DXN, including version when published
+   * (e.g. `dxn:org.dxos.plugin.example:0.8.3`). The validated source of truth
+   * from which {@link id} and {@link version} are derived.
+   *
+   * @example DXN.make('org.dxos.plugin.example', '0.8.3')
+   */
+  key: DXN.DXN;
+
   /**
    * Human-readable name.
    */
   name: string;
 
+  /**
+   * Semver version string of the plugin, typically the publishing package's
+   * `package.json` version. Derived from the version segment of {@link key} by
+   * {@link makeMeta} — do not set directly.
+   */
+  version?: string;
+
   /**
    * Short description of plugin functionality.
    */
   description?: string;
 
+  /**
+   * Name of the author or organization that created the plugin.
+   */
+  // TODO(burdon): DID or domain name?
+  author?: string;
+
   /**
    * URL of home page.
    */
@@ -152,6 +199,14 @@ export type Meta = {
    */
   source?: string;
 
+  /**
+   * Relative path (inside the published package) to the plugin's bundled MDL
+   * specification file — e.g. `'PLUGIN.mdl'` or `'docs/PLUGIN.mdl'`. The file
+   * is shipped via the package's `files` entry and resolved by registry
+   * surfaces to render an in-app viewer and/or external link.
+   */
+  spec?: string;
+
   /**
    * URL of screenshot.
    */
@@ -171,8 +226,48 @@ export type Meta = {
    * Icon hue (ChromaticPalette).
    */
   iconHue?: string;
+
+  /**
+   * IDs of plugins this plugin functionally depends on.
+   *
+   * Treated as a convenience by the default `PluginManager` flow:
+   * - Enabling this plugin auto-enables the transitive closure of `dependsOn`
+   *   (installing missing entries from the plugin registry when possible).
+   * - Disabling a depended-upon plugin surfaces dependents to the caller; the
+   *   `PluginManager.disable` API supports an opt-in cascade.
+   *
+   * Not an invariant: low-level `PluginManager` APIs accept opt-outs
+   * (`resolveDependencies: false`, `ignoreDependents: true`) so a caller may
+   * substitute an alternative implementation that satisfies the dependent's
+   * capability needs in its own way.
+   */
+  dependsOn?: string[];
 };
 
+/**
+ * Options for {@link makeMeta}: a {@link Meta} minus the fields derived from `key`.
+ * Identity and version are specified solely through the `key` DXN — `id` and
+ * `version` cannot be passed directly.
+ */
+export type MakeMetaOptions = Omit<Meta, 'id' | 'version'>;
+
+/**
+ * Constructs a plugin {@link Meta} from a single canonical DXN. The `key` DXN is
+ * the one source of truth; `id` (bare NSID) and `version` (semver) are derived
+ * from it so each datum has exactly one home and cannot drift out of sync.
+ *
+ * @example
+ * export const meta = Plugin.makeMeta({
+ *   key: DXN.make('org.dxos.plugin.example', '0.8.3'),
+ *   name: 'Example',
+ * });
+ */
+export const makeMeta = (options: MakeMetaOptions): Meta => ({
+  ...options,
+  id: DXN.getName(options.key),
+  version: DXN.getVersion(options.key),
+});
+
 /**
  * Identifier denoting a Plugin.
  */
@@ -294,14 +389,15 @@ const resolveModule = (
   options?: any,
 ): PluginModuleImpl => {
   const moduleOptions = typeof module === 'function' ? module(options) : module;
+  const pluginName = meta.id;
   const id = Option.fromNullable(moduleOptions.id).pipe(
     Option.match({
       onNone: () => {
         const exportName = Capability.getModuleTag(moduleOptions.activate);
         invariant(exportName, `Plugin module missing name. Plugin: ${meta.id}`);
-        return computeModuleId(meta.id, exportName);
+        return computeModuleId(pluginName, exportName);
       },
-      onSome: (id) => computeModuleId(meta.id, id),
+      onSome: (id) => computeModuleId(pluginName, id),
     }),
   );
   return new PluginModuleImpl({ ...moduleOptions, id });
@@ -316,6 +412,8 @@ const resolveModule = (
 export function make<T>(builder: PluginBuilder<T>): PluginFactory<T>;
 export function make<T>(builder: PluginBuilder<T>): PluginFactory<T> {
   const meta = builder.meta;
+  // `dependsOn` entries and `id` are both bare NSIDs, so compare directly.
+  invariant(!meta.dependsOn?.includes(meta.id), `Plugin ${meta.id} declares itself as a dependency.`);
 
   const factory = (options: T) => {
     const modules = builder.modules.map((module) => resolveModule(meta, module, options));
@@ -324,3 +422,123 @@ export function make<T>(builder: PluginBuilder<T>): PluginFactory<T> {
 
   return Object.assign(factory, { meta });
 }
+
+//
+// Lazy plugin loading
+//
+
+/**
+ * Symbol used to tag lazy plugin stubs with their loader closure.
+ * Hidden from enumeration so plugin manager iteration / serialization paths
+ * don't trip over it.
+ */
+const LazyTag: unique symbol = Symbol.for('@dxos/app-framework/Plugin/Lazy');
+
+/**
+ * Async loader for a lazy plugin's real implementation.
+ * The default export of the loaded module must be a `PluginFactory<T>` —
+ * i.e. the same shape `Plugin.make` produces.
+ */
+export type LazyLoader<T = void> = () => Promise<{ default: PluginFactory<T> }>;
+
+/** Internal: payload carried on a lazy stub. */
+type LazyPayload = { loader: LazyLoader<any>; options: unknown };
+
+/**
+ * Defines a lazy plugin whose body is loaded on first enable.
+ *
+ * The returned factory produces a stub `Plugin` that exposes `meta`
+ * synchronously (so callers can read `Plugin.meta.id` for free) but defers
+ * loading the real plugin's modules until the manager calls
+ * `Plugin.resolveLazy`. This lets the plugin's main entry point ship as a
+ * tiny meta-only chunk — the heavy capabilities, schema, React surfaces,
+ * etc. live behind the dynamic `import()` and become a separate Rollup
+ * chunk that is only fetched when the plugin is enabled.
+ *
+ * @example
+ * ```ts
+ * // plugin-markdown/src/index.ts
+ * import { Plugin } from '@dxos/app-framework';
+ * import { meta } from './meta';
+ *
+ * export const MarkdownPlugin = Plugin.lazy(meta, () => import('./MarkdownPlugin'));
+ *
+ * // plugin-markdown/src/MarkdownPlugin.tsx
+ * export const MarkdownPlugin = Plugin.define(meta).pipe(...heavy modules..., Plugin.make);
+ * export default MarkdownPlugin;
+ * ```
+ */
+export const lazy = <T = void>(meta: Meta, loader: LazyLoader<T>): PluginFactory<T> => {
+  const factory = (options: T): Plugin => {
+    const stub = new PluginImpl(meta, []);
+    Object.defineProperty(stub, LazyTag, {
+      value: { loader, options } satisfies LazyPayload,
+      enumerable: false,
+    });
+    return stub;
+  };
+  return Object.assign(factory, { meta });
+};
+
+/**
+ * Type guard for lazy plugin stubs produced by {@link lazy}.
+ */
+export const isLazy = (plugin: Plugin): boolean => LazyTag in plugin;
+
+/**
+ * Tagged error for failures during lazy plugin resolution. `context.id` is
+ * the lazy plugin's `meta.id`; `context.reason` discriminates the failure
+ * mode (`'load-failed' | 'missing-default' | 'invalid-plugin' |
+ * 'meta-mismatch'`) so callers can route on it.
+ */
+export class LazyPluginError extends BaseError.extend('LazyPluginError', 'Failed to resolve lazy plugin') {}
+
+/**
+ * Tagged error for plugin-level dependency resolution failures.
+ *
+ * `context.id` is the plugin id the manager was acting on. `context.reason`
+ * discriminates the failure mode:
+ *  - `'missing'` — declared dep is neither registered nor in the catalog.
+ *    `context.missing` lists offending ids.
+ *  - `'install-failed'` — dep was found in the catalog but `add()` failed.
+ *    `cause` carries the original error.
+ *  - `'cycle'` — closure walk detected a cycle. `context.path` is the cycle path.
+ *  - `'core-dependent'` — cascade-disable would have to disable a core plugin.
+ *    `context.coreDependent` is the blocking id.
+ */
+export class PluginDependencyError extends BaseError.extend(
+  'PluginDependencyError',
+  'Plugin dependency resolution failed',
+) {}
+
+/**
+ * Resolves a lazy plugin stub to its real plugin.
+ * Returns the plugin unchanged if it is not lazy. Failures surface as
+ * {@link LazyPluginError} with `context.reason` indicating the failure mode
+ * and (for loader failures) `cause` set to the original error.
+ */
+export const resolveLazy = (plugin: Plugin): Effect.Effect<Plugin, LazyPluginError> =>
+  Effect.gen(function* () {
+    if (!isLazy(plugin)) {
+      return plugin;
+    }
+    const id = plugin.meta.id;
+    const { loader, options } = (plugin as unknown as { [LazyTag]: LazyPayload })[LazyTag];
+    const mod = yield* Effect.tryPromise({
+      try: loader,
+      catch: (error) => new LazyPluginError({ context: { id, reason: 'load-failed' }, cause: error }),
+    });
+    if (!mod || typeof mod.default !== 'function') {
+      return yield* Effect.fail(new LazyPluginError({ context: { id, reason: 'missing-default' } }));
+    }
+    const result = mod.default(options);
+    if (!isPlugin(result)) {
+      return yield* Effect.fail(new LazyPluginError({ context: { id, reason: 'invalid-plugin' } }));
+    }
+    if (result.meta.id !== id) {
+      return yield* Effect.fail(
+        new LazyPluginError({ context: { id, reason: 'meta-mismatch', returnedId: result.meta.id } }),
+      );
+    }
+    return result;
+  });