@dxos/app-framework 0.8.4-main.c85a9c8dae → 0.8.4-main.cb12b3f963

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

package/src/core/registry.ts

@@ -0,0 +1,157 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, type Registry as AtomRegistry } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { runAndForwardErrors } from '@dxos/effect';
+import { log } from '@dxos/log';
+
+/**
+ * A registry plugin entry as seen by the plugin manager layer.
+ * Populated from the registry catalog; represents the latest available version of a plugin.
+ *
+ * Independently defined from @dxos/protocols PluginEntry — similar shape but not the same type.
+ * Implementations of {@link PluginProvider} (e.g. {@link EdgeRegistryPluginProvider})
+ * are responsible for mapping their wire-format entries to this shape.
+ */
+export type Plugin = {
+  id: string;
+  name: string;
+  description?: string;
+  homePage?: string;
+  source?: string;
+  screenshots?: string[];
+  tags?: string[];
+  icon?: string;
+  iconHue?: string;
+  /** URL to dynamic-import the latest version of this plugin module. */
+  moduleUrl: string;
+  /** GitHub repository slug, e.g. `owner/name`. Used to fetch version history. */
+  repo: string;
+  /**
+   * Latest known version string, e.g. `v1.2.0`.
+   * Corresponds to releaseTag in the wire-format PluginEntry; named `version` here
+   * because the plugin manager layer speaks versions, not release tags.
+   */
+  version: string;
+};
+
+/**
+ * A single installable version of a registry plugin.
+ */
+export type PluginVersion = {
+  /** Version string, e.g. `v1.2.0`. */
+  tag: string;
+  /** URL to dynamic-import this specific version of the plugin module. */
+  moduleUrl: string;
+  /** Unix ms of when this version was published (optional; omitted when unknown). */
+  releasedAt?: number;
+};
+
+/**
+ * Abstraction over the plugin registry catalog backend.
+ * Implementations may call Edge, a local cache, or a stub.
+ *
+ * The interface itself is transport-agnostic; concrete implementations live
+ * alongside it in this package (see {@link EdgeRegistryPluginProvider}) so we
+ * avoid `app-framework ↔ edge-client` cycles, but they only need to satisfy
+ * this shape — callers can substitute their own.
+ */
+export interface PluginProvider {
+  /**
+   * Returns all healthy registry plugins (latest version of each).
+   */
+  listPlugins(): Effect.Effect<readonly Plugin[], Error>;
+
+  /**
+   * Returns all known versions of a plugin identified by its GitHub repo slug.
+   * Until the backend implements a versions endpoint, implementations MUST
+   * return at least one entry representing the current/latest release.
+   */
+  listVersions(repo: string): Effect.Effect<readonly PluginVersion[], Error>;
+
+  /**
+   * Returns a single plugin entry for the given repo.
+   * If `version` is omitted, returns the latest.
+   * Fails if the specified version is not found.
+   */
+  getPlugin(repo: string, version?: string): Effect.Effect<Plugin, Error>;
+}
+
+/**
+ * Atomic snapshot of the registry catalog as observed by the host.
+ * Exposed via {@link Manager.plugins} so consumers can subscribe reactively
+ * (loading state, list contents, last error).
+ */
+export type PluginsState = {
+  entries: readonly Plugin[];
+  loading: boolean;
+  error: Error | null;
+};
+
+/**
+ * Default no-op provider used when no `PluginProvider` is supplied at construction
+ * time (e.g. tests, stories, environments without an Edge connection).
+ *
+ * `listPlugins` returns an empty list (so `Manager.plugins` settles to a stable
+ * empty state). `listVersions` and `getPlugin` fail with an explicit error so
+ * callers know they need to configure a real provider.
+ */
+const NULL_PROVIDER: PluginProvider = {
+  listPlugins: () => Effect.succeed([] as readonly Plugin[]),
+  listVersions: () => Effect.fail(new Error('No plugin registry provider configured')),
+  getPlugin: () => Effect.fail(new Error('No plugin registry provider configured')),
+};
+
+/**
+ * Owns the cached registry catalog state and forwards `listVersions` / `getPlugin`
+ * calls to the underlying {@link PluginProvider}. Lives on the `PluginManager`
+ * (as `manager.pluginRegistry`) so consumers can reach it through the manager
+ * without a separate capability lookup.
+ *
+ * On construction the manager kicks off a background fetch via `provider.listPlugins()`
+ * and writes the result into the {@link plugins} atom. Subscribers see `loading: true`
+ * during the fetch and `loading: false` once it settles.
+ */
+export class Manager {
+  readonly plugins: Atom.Writable<PluginsState>;
+  readonly #provider: PluginProvider;
+
+  constructor(provider: PluginProvider | undefined, atomRegistry: AtomRegistry.Registry) {
+    this.#provider = provider ?? NULL_PROVIDER;
+    const initialLoading = provider !== undefined;
+    this.plugins = Atom.make<PluginsState>({ entries: [], loading: initialLoading, error: null }).pipe(Atom.keepAlive);
+
+    if (provider !== undefined) {
+      // Fire-and-forget initial load. Errors are surfaced via the atom's `error` field.
+      void runAndForwardErrors(
+        provider.listPlugins().pipe(
+          Effect.match({
+            onSuccess: (entries) => atomRegistry.set(this.plugins, { entries, loading: false, error: null }),
+            onFailure: (error) => {
+              log.catch(error);
+              atomRegistry.set(this.plugins, { entries: [], loading: false, error });
+            },
+          }),
+        ),
+      );
+    }
+  }
+
+  /** Forwards to the underlying provider. */
+  listPlugins(): Effect.Effect<readonly Plugin[], Error> {
+    return this.#provider.listPlugins();
+  }
+
+  /** Forwards to the underlying provider. */
+  listVersions(repo: string): Effect.Effect<readonly PluginVersion[], Error> {
+    return this.#provider.listVersions(repo);
+  }
+
+  /** Forwards to the underlying provider. */
+  getPlugin(repo: string, version?: string): Effect.Effect<Plugin, Error> {
+    return this.#provider.getPlugin(repo, version);
+  }
+}