@dxos/app-framework 0.8.4-main.fffef41 → 0.9.0

package/dist/types/src/core/plugin-manifest.d.ts

@@ -0,0 +1,101 @@
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { BaseError } from '@dxos/errors';
+/**
+ * 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 declare const PLUGIN_DEV_SERVER_PORT = 3967;
+declare const PluginManifestError_base: {
+    new (options?: import("@dxos/errors").BaseErrorOptions): {
+        cause?: unknown;
+        stack?: string;
+        name: "PluginManifestError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "PluginManifestError";
+    };
+    isError(error: unknown): error is Error;
+    name: "PluginManifestError";
+    is(error: unknown): error is BaseError;
+    wrap(options?: Omit<import("@dxos/errors").BaseErrorOptions, 'cause'> & {
+        ifTypeDiffers?: boolean;
+    }): (error: unknown) => {
+        cause?: unknown;
+        stack?: string;
+        name: "PluginManifestError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "PluginManifestError";
+    };
+    extend<Name extends string = string>(name: Name, message?: string): any;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+/**
+ * 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 declare class PluginManifestError extends PluginManifestError_base {
+}
+/**
+ * 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 declare const Manifest: Schema.Struct<{
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    version: typeof Schema.String;
+    assets: Schema.Array$<typeof Schema.String>;
+    devEntry: Schema.optional<typeof Schema.String>;
+}>;
+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;
+};
+/**
+ * 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 declare const parse: (manifestUrl: string, payload: unknown) => ResolvedManifest;
+/**
+ * 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 declare const fetchManifest: (manifestUrl: string) => Effect.Effect<ResolvedManifest, PluginManifestError>;
+export {};
+//# sourceMappingURL=plugin-manifest.d.ts.map

package/dist/types/src/core/plugin-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manifest.d.ts","sourceRoot":"","sources":["../../../../src/core/plugin-manifest.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAE3C;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,wBAAqE;CAAG;AAEjH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;;;;;;EAMnB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAmBF;;;;GAIG;AACH,eAAO,MAAM,KAAK,gBAAiB,MAAM,WAAW,OAAO,KAAG,gBAM7D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,gBAAiB,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,mBAAmB,CAuBxC,CAAC"}

package/dist/types/src/core/plugin-manifest.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-manifest.test.d.ts.map

package/dist/types/src/core/plugin-manifest.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manifest.test.d.ts","sourceRoot":"","sources":["../../../../src/core/plugin-manifest.test.ts"],"names":[],"mappings":""}

package/dist/types/src/core/plugin.d.ts

@@ -1,7 +1,52 @@
-import { type MaybePromise } from '@dxos/util';
-import { type AnyCapability, type PluginContext } from './capabilities';
-import { type ActivationEvent, type ActivationEvents } from './events';
-interface PluginModuleInterface {
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Pipeable from 'effect/Pipeable';
+import { BaseError } from '@dxos/errors';
+import { DXN } from '@dxos/keys';
+import type * as ActivationEvent from './activation-event';
+import * as Capability from './capability';
+import type * as PluginManager from './plugin-manager';
+declare const Service_base: Context.TagClass<Service, "@dxos/app-framework/PluginManager", PluginManager.PluginManager>;
+/**
+ * Effect Context.Tag for accessing PluginManager via the Effect layer system.
+ * This allows lifecycle operations to access the plugin manager without having it passed as an argument.
+ */
+export declare class Service extends Service_base {
+}
+/**
+ * Activates plugins based on the activation event.
+ * Accesses the PluginManager via the Effect layer system.
+ * @param event The activation event.
+ * @returns Whether the activation was successful.
+ */
+export declare const activate: (event: ActivationEvent.ActivationEvent) => Effect.Effect<boolean, Error, Service>;
+/**
+ * Re-activates the modules that were activated by the event.
+ * Accesses the PluginManager via the Effect layer system.
+ * @param event The activation event.
+ * @returns Whether the reset was successful.
+ */
+export declare const reset: (event: ActivationEvent.ActivationEvent) => Effect.Effect<boolean, Error, Service>;
+/**
+ * Shuts down the plugin manager, deactivating all active modules and clearing lifecycle state.
+ * Accesses the PluginManager via the Effect layer system.
+ */
+export declare const shutdown: () => Effect.Effect<boolean, Error, Service>;
+/**
+ * Identifier denoting a PluginModule.
+ */
+export declare const PluginModuleTypeId: unique symbol;
+export type PluginModuleTypeId = typeof PluginModuleTypeId;
+/**
+ * Type guard to check if a value is a PluginModule.
+ */
+export declare const isPluginModule: (value: unknown) => value is PluginModule;
+/**
+ * A unit of containment of modular functionality that can be provided to an application.
+ * Activation of a module is async allowing for code to split and loaded lazily.
+ */
+export interface PluginModule {
+    readonly [PluginModuleTypeId]: PluginModuleTypeId;
     /**
      * Unique id of the module.
      */
@@ -9,57 +54,80 @@ interface PluginModuleInterface {
     /**
      * Events for which the module will be activated.
      */
-    activatesOn: ActivationEvents;
+    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[];
+    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[];
+    firesAfterActivation?: ActivationEvent.ActivationEvent[];
     /**
      * Called when the module is activated.
-     * @param context The plugin context.
+     * CapabilityManager is accessed via the Effect layer system (Capability.Service).
+     * PluginManager is accessed via Plugin.Service.
+     * @param props Optional props passed to the module.
      * @returns The capabilities of the module.
      */
-    activate: (context: PluginContext) => MaybePromise<AnyCapability | AnyCapability[]> | Promise<() => Promise<AnyCapability | AnyCapability[]>>;
-}
-/**
- * A unit of containment of modular functionality that can be provided to an application.
- * Activation of a module is async allowing for code to split and loaded lazily.
- */
-export declare class PluginModule implements PluginModuleInterface {
-    readonly id: PluginModuleInterface['id'];
-    readonly activatesOn: PluginModuleInterface['activatesOn'];
-    readonly activatesBefore?: PluginModuleInterface['activatesBefore'];
-    readonly activatesAfter?: PluginModuleInterface['activatesAfter'];
-    readonly activate: PluginModuleInterface['activate'];
-    constructor(options: PluginModuleInterface);
+    activate: (props?: any) => Effect.Effect<Capability.ModuleReturn, Error, Capability.Service | Service | never>;
 }
-/**
- * Helper to define a module.
- */
-export declare const defineModule: (options: PluginModuleInterface) => PluginModule;
-export type PluginMeta = {
+export type PluginModuleOptions = Omit<PluginModule, 'id' | typeof PluginModuleTypeId> & {
+    id?: string;
+};
+export type Meta = {
     /**
-     * Globally unique ID.
-     *
-     * Expected to be in the form of a valid URL.
-     *
-     * @example dxos.org/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.
+     */
+    author?: string;
     /**
      * URL of home page.
      */
@@ -68,6 +136,13 @@ export type PluginMeta = {
      * URL of source code.
      */
     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.
      */
@@ -84,22 +159,207 @@ export type PluginMeta = {
      * 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 declare const makeMeta: (options: MakeMetaOptions) => Meta;
+/**
+ * Identifier denoting a Plugin.
+ */
+export declare const PluginTypeId: unique symbol;
+export type PluginTypeId = typeof PluginTypeId;
+/**
+ * Type guard to check if a value is a Plugin.
+ */
+export declare const isPlugin: (value: unknown) => value is Plugin;
 /**
  * A collection of modules that are be enabled/disabled as a unit.
  * Plugins provide things such as components, state, actions, etc. to the application.
  */
-export declare class Plugin {
-    readonly meta: PluginMeta;
-    readonly modules: PluginModule[];
-    constructor(meta: PluginMeta, modules: PluginModule[]);
+export interface Plugin {
+    readonly [PluginTypeId]: PluginTypeId;
+    readonly meta: Readonly<Meta>;
+    readonly modules: ReadonlyArray<PluginModule>;
+}
+/**
+ * Builder interface for creating plugins incrementally.
+ */
+export interface PluginBuilder<T = void> extends Pipeable.Pipeable {
+    readonly meta: Meta;
+    readonly modules: ReadonlyArray<PluginModuleOptions | ((options: T) => PluginModuleOptions)>;
+    addModule(moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions)): PluginBuilder<T>;
+}
+/**
+ * Creates a new PluginBuilder to start building a plugin.
+ */
+export declare const define: <T = void>(meta: Meta) => PluginBuilder<T>;
+/**
+ * Adds a module to a plugin builder.
+ * Supports both pipeline and direct call styles.
+ * Modules can be either PluginModuleOptions or functions that receive options.
+ */
+export declare function addModule<T>(moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions)): (builder: PluginBuilder<T>) => PluginBuilder<T>;
+export declare function addModule<T>(builder: PluginBuilder<T>, moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions)): PluginBuilder<T>;
+export type PluginFactory<T = void> = ((options: T) => Plugin) & {
+    meta: Meta;
+};
+/**
+ * Creates a Plugin from a builder.
+ * Supports both pipeline and direct call styles.
+ * Always returns a factory function (options: T) => Plugin.
+ * When T is void, the function takes no arguments: () => Plugin.
+ */
+export declare function make<T>(builder: PluginBuilder<T>): PluginFactory<T>;
+/**
+ * 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>;
+}>;
+/**
+ * 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 declare const lazy: <T = void>(meta: Meta, loader: LazyLoader<T>) => PluginFactory<T>;
+/**
+ * Type guard for lazy plugin stubs produced by {@link lazy}.
+ */
+export declare const isLazy: (plugin: Plugin) => boolean;
+declare const LazyPluginError_base: {
+    new (options?: import("@dxos/errors").BaseErrorOptions): {
+        cause?: unknown;
+        stack?: string;
+        name: "LazyPluginError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "LazyPluginError";
+    };
+    isError(error: unknown): error is Error;
+    name: "LazyPluginError";
+    is(error: unknown): error is BaseError;
+    wrap(options?: Omit<import("@dxos/errors").BaseErrorOptions, 'cause'> & {
+        ifTypeDiffers?: boolean;
+    }): (error: unknown) => {
+        cause?: unknown;
+        stack?: string;
+        name: "LazyPluginError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "LazyPluginError";
+    };
+    extend<Name extends string = string>(name: Name, message?: string): any;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+/**
+ * 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 declare class LazyPluginError extends LazyPluginError_base {
 }
-export type PluginFactory<T = void> = ((args: T) => Plugin) & {
-    meta: PluginMeta;
+declare const PluginDependencyError_base: {
+    new (options?: import("@dxos/errors").BaseErrorOptions): {
+        cause?: unknown;
+        stack?: string;
+        name: "PluginDependencyError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "PluginDependencyError";
+    };
+    isError(error: unknown): error is Error;
+    name: "PluginDependencyError";
+    is(error: unknown): error is BaseError;
+    wrap(options?: Omit<import("@dxos/errors").BaseErrorOptions, 'cause'> & {
+        ifTypeDiffers?: boolean;
+    }): (error: unknown) => {
+        cause?: unknown;
+        stack?: string;
+        name: "PluginDependencyError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "PluginDependencyError";
+    };
+    extend<Name extends string = string>(name: Name, message?: string): any;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
 };
 /**
- * Helper to define a 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 declare class PluginDependencyError extends PluginDependencyError_base {
+}
+/**
+ * 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 declare const definePlugin: <T = void>(meta: PluginMeta, provider: (args: T) => PluginModule[]) => PluginFactory<T>;
+export declare const resolveLazy: (plugin: Plugin) => Effect.Effect<Plugin, LazyPluginError>;
 export {};
 //# sourceMappingURL=plugin.d.ts.map

package/dist/types/src/core/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../src/core/plugin.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEvE,UAAU,qBAAqB;IAC7B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,WAAW,EAAE,gBAAgB,CAAC;IAE9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,EAAE,CAAC;IAEpC;;OAEG;IACH,cAAc,CAAC,EAAE,eAAe,EAAE,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,EAAE,CACR,OAAO,EAAE,aAAa,KACnB,YAAY,CAAC,aAAa,GAAG,aAAa,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,aAAa,GAAG,aAAa,EAAE,CAAC,CAAC,CAAC;CAC9G;AAED;;;GAGG;AAEH,qBAAa,YAAa,YAAW,qBAAqB;IACxD,QAAQ,CAAC,EAAE,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IAC3D,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,qBAAqB,CAAC,gBAAgB,CAAC,CAAC;IAClE,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;gBAEzC,OAAO,EAAE,qBAAqB;CAO3C;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,qBAAqB,iBAA8B,CAAC;AAE1F,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AAEH,qBAAa,MAAM;IAEf,QAAQ,CAAC,IAAI,EAAE,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE;gBADvB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,YAAY,EAAE;CAEnC;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEnF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,GAAG,IAAI,EAAE,MAAM,UAAU,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,YAAY,EAAE,KAAG,aAAa,CAAC,CAAC,CAM/G,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../src/core/plugin.ts"],"names":[],"mappings":"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"}

package/dist/types/src/core/registry.d.ts

@@ -0,0 +1,107 @@
+import { Atom, type Registry as AtomRegistry } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+/**
+ * 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;
+    /**
+     * IDs of plugins this entry declares as runtime dependencies. Mirrors
+     * {@link Plugin.Meta.dependsOn}. Surfaced in the catalog so the manager can
+     * resolve and auto-install transitive deps before they are first loaded.
+     */
+    dependsOn?: 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;
+};
+/**
+ * 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 declare class Manager {
+    #private;
+    readonly plugins: Atom.Writable<PluginsState>;
+    constructor(provider: PluginProvider | undefined, atomRegistry: AtomRegistry.Registry);
+    /** Forwards to the underlying provider. */
+    listPlugins(): Effect.Effect<readonly Plugin[], Error>;
+    /** Forwards to the underlying provider. */
+    listVersions(repo: string): Effect.Effect<readonly PluginVersion[], Error>;
+    /** Forwards to the underlying provider. */
+    getPlugin(repo: string, version?: string): Effect.Effect<Plugin, Error>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/src/core/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/core/registry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,KAAK,QAAQ,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAKxC;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,EAAE,KAAK,CAAC,CAAC;IAEvD;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,aAAa,EAAE,EAAE,KAAK,CAAC,CAAC;IAE3E;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACzE;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB,CAAC;AAgBF;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAClB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IAG9C,YAAY,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,YAAY,EAAE,YAAY,CAAC,QAAQ,EAmBpF;IAED,2CAA2C;IAC3C,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,EAAE,KAAK,CAAC,CAErD;IAED,2CAA2C;IAC3C,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,aAAa,EAAE,EAAE,KAAK,CAAC,CAEzE;IAED,2CAA2C;IAC3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAEtE;CACF"}