@dxos/app-framework 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/dist/types/src/common/operations.d.ts

@@ -0,0 +1,380 @@
+import * as Schema from 'effect/Schema';
+import { Capability } from '../core';
+/**
+ * Layout operations - Operation-based equivalents of LayoutAction intents.
+ * These mirror the LayoutAction namespace but use the Operation pattern.
+ */
+export declare namespace LayoutOperation {
+    const UpdateSidebar: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/update-sidebar";
+            readonly name: "Update Sidebar";
+            readonly description: "Update the sidebar state.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                state: Schema.optional<Schema.Literal<["closed", "collapsed", "expanded"]>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const UpdateComplementary: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/update-complementary";
+            readonly name: "Update Complementary Sidebar";
+            readonly description: "Update the complementary sidebar state.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                state: Schema.optional<Schema.Literal<["closed", "collapsed", "expanded"]>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const UpdateDialog: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/update-dialog";
+            readonly name: "Update Dialog";
+            readonly description: "Open, close, or update the dialog.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                state: Schema.optional<Schema.SchemaClass<boolean, boolean, never>>;
+                type: Schema.optional<Schema.Literal<["default", "alert"]>>;
+                blockAlign: Schema.optional<Schema.Literal<["start", "center", "end"]>>;
+                overlayClasses: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                overlayStyle: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Any>>;
+                props: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Any>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const UpdatePopover: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/update-popover";
+            readonly name: "Update Popover";
+            readonly description: "Open, close, or update a popover.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Union<[Schema.extend<Schema.Union<[Schema.extend<Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<any, any, never>>;
+                side: Schema.optional<Schema.Literal<["top", "right", "bottom", "left"]>>;
+                state: Schema.optional<Schema.SchemaClass<boolean, boolean, never>>;
+                props: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Any>>;
+            }>, Schema.Struct<{
+                kind: Schema.optional<Schema.Literal<["base"]>>;
+            }>>, Schema.extend<Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<any, any, never>>;
+                side: Schema.optional<Schema.Literal<["top", "right", "bottom", "left"]>>;
+                state: Schema.optional<Schema.SchemaClass<boolean, boolean, never>>;
+                props: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Any>>;
+            }>, Schema.Struct<{
+                kind: Schema.Literal<["card"]>;
+                title: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+            }>>]>, Schema.Struct<{
+                variant: Schema.Literal<["virtual"]>;
+                anchor: Schema.SchemaClass<any, any, never>;
+            }>>, Schema.extend<Schema.Union<[Schema.extend<Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<any, any, never>>;
+                side: Schema.optional<Schema.Literal<["top", "right", "bottom", "left"]>>;
+                state: Schema.optional<Schema.SchemaClass<boolean, boolean, never>>;
+                props: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Any>>;
+            }>, Schema.Struct<{
+                kind: Schema.optional<Schema.Literal<["base"]>>;
+            }>>, Schema.extend<Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<any, any, never>>;
+                side: Schema.optional<Schema.Literal<["top", "right", "bottom", "left"]>>;
+                state: Schema.optional<Schema.SchemaClass<boolean, boolean, never>>;
+                props: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Any>>;
+            }>, Schema.Struct<{
+                kind: Schema.Literal<["card"]>;
+                title: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+            }>>]>, Schema.Struct<{
+                variant: Schema.optional<Schema.Literal<["react"]>>;
+                anchorId: Schema.SchemaClass<string, string, never>;
+            }>>]>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const Toast: Schema.Struct<{
+        id: Schema.SchemaClass<string, string, never>;
+        title: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+            ns: typeof Schema.String;
+            count: Schema.optional<typeof Schema.Number>;
+            defaultValue: Schema.optional<typeof Schema.String>;
+        }>>>>]>>;
+        description: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+            ns: typeof Schema.String;
+            count: Schema.optional<typeof Schema.Number>;
+            defaultValue: Schema.optional<typeof Schema.String>;
+        }>>>>]>>;
+        icon: Schema.optional<Schema.SchemaClass<string, string, never>>;
+        duration: Schema.optional<Schema.SchemaClass<number, number, never>>;
+        closeLabel: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+            ns: typeof Schema.String;
+            count: Schema.optional<typeof Schema.Number>;
+            defaultValue: Schema.optional<typeof Schema.String>;
+        }>>>>]>>;
+        actionLabel: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+            ns: typeof Schema.String;
+            count: Schema.optional<typeof Schema.Number>;
+            defaultValue: Schema.optional<typeof Schema.String>;
+        }>>>>]>>;
+        actionAlt: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+            ns: typeof Schema.String;
+            count: Schema.optional<typeof Schema.Number>;
+            defaultValue: Schema.optional<typeof Schema.String>;
+        }>>>>]>>;
+        onAction: Schema.optional<Schema.SchemaClass<any, any, never>>;
+    }>;
+    interface Toast extends Omit<Schema.Schema.Type<typeof Toast>, 'onAction'> {
+        onAction?: () => void;
+    }
+    const AddToast: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/add-toast";
+            readonly name: "Add Toast";
+            readonly description: "Add a toast notification.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                id: Schema.SchemaClass<string, string, never>;
+                title: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+                description: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+                icon: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                duration: Schema.optional<Schema.SchemaClass<number, number, never>>;
+                closeLabel: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+                actionLabel: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+                actionAlt: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+                onAction: Schema.optional<Schema.SchemaClass<any, any, never>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const SetLayoutMode: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/set-layout-mode";
+            readonly name: "Set Layout Mode";
+            readonly description: "Set the layout mode (solo, deck, fullscreen, etc.).";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Union<[Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                mode: Schema.SchemaClass<string, string, never>;
+            }>, Schema.Struct<{
+                revert: Schema.SchemaClass<boolean, boolean, never>;
+            }>]>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const SwitchWorkspace: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/switch-workspace";
+            readonly name: "Switch Workspace";
+            readonly description: "Switch to a different workspace.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.SchemaClass<string, string, never>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const RevertWorkspace: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/revert-workspace";
+            readonly name: "Revert Workspace";
+            readonly description: "Revert to the previous workspace.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: typeof Schema.Void;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const Open: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/open";
+            readonly name: "Open";
+            readonly description: "Open items in the main content area.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.Array$<Schema.SchemaClass<string, string, never>>;
+                state: Schema.optional<Schema.Literal<[true]>>;
+                variant: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                key: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                workspace: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                scrollIntoView: Schema.optional<Schema.SchemaClass<boolean, boolean, never>>;
+                pivotId: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                positioning: Schema.optional<Schema.Union<[Schema.Literal<["start"]>, Schema.Literal<["end"]>]>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const Close: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/close";
+            readonly name: "Close";
+            readonly description: "Close items in the main content area.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.Array$<Schema.SchemaClass<string, string, never>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const Set: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/set";
+            readonly name: "Set";
+            readonly description: "Override items in the main content area.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.Array$<Schema.SchemaClass<string, string, never>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const ScrollIntoView: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/scroll-into-view";
+            readonly name: "Scroll Into View";
+            readonly description: "Scroll an item into view.";
+        };
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                cursor: Schema.optional<Schema.SchemaClass<string, string, never>>;
+                ref: Schema.optional<Schema.SchemaClass<string, string, never>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+    const Expose: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/plugin/layout/operation/expose";
+            readonly name: "Expose";
+            readonly description: "Expose an item in the navigation area.";
+        };
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                subject: Schema.SchemaClass<string, string, never>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+}
+/**
+ * Operations related to undo/history functionality.
+ */
+export declare namespace UndoOperation {
+    /**
+     * Show an undo toast notification.
+     * Fired by HistoryTracker when an undoable operation is tracked.
+     */
+    const ShowUndo: Omit<{
+        readonly meta: {
+            readonly key: "dxos.org/app-framework/undo/operation/show-undo";
+            readonly name: "Show Undo";
+            readonly description: "Show an undo toast notification.";
+        };
+        readonly executionMode: "sync";
+        readonly services: readonly [typeof Capability.Service];
+        readonly schema: {
+            readonly input: Schema.Struct<{
+                message: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Tuple2<typeof Schema.String, Schema.mutable<Schema.Struct<{
+                    ns: typeof Schema.String;
+                    count: Schema.optional<typeof Schema.Number>;
+                    defaultValue: Schema.optional<typeof Schema.String>;
+                }>>>>]>>;
+            }>;
+            readonly output: typeof Schema.Void;
+        };
+    }, "executionMode"> & import("effect/Pipeable").Pipeable & {
+        readonly executionMode: "sync" | "async";
+    };
+}
+//# sourceMappingURL=operations.d.ts.map

package/dist/types/src/common/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../../src/common/operations.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAMrC;;;GAGG;AACH,yBAAiB,eAAe,CAAC;IAKxB,MAAM,aAAa;;;;;;;;;;;;;;;;;KAqBxB,CAAC;IAEI,MAAM,mBAAmB;;;;;;;;;;;;;;;;;KAqB9B,CAAC;IAMI,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;KAkCvB,CAAC;IAyCI,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA+BxB,CAAC;IAMI,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAYhB,CAAC;IAEH,UAAiB,KAAM,SAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,UAAU,CAAC;QAC/E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;KACvB;IAEM,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAYnB,CAAC;IAMI,MAAM,aAAa;;;;;;;;;;;;;;;;;;;KAsBxB,CAAC;IAMI,MAAM,eAAe;;;;;;;;;;;;;;;;KAc1B,CAAC;IAEI,MAAM,eAAe;;;;;;;;;;;;;;KAY1B,CAAC;IAMI,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;KAgCf,CAAC;IAEI,MAAM,KAAK;;;;;;;;;;;;;;;;KAchB,CAAC;IAEI,MAAM,GAAG;;;;;;;;;;;;;;;;KAcd,CAAC;IAMI,MAAM,cAAc;;;;;;;;;;;;;;;;;KAezB,CAAC;IAEI,MAAM,MAAM;;;;;;;;;;;;;;;KAajB,CAAC;CACJ;AAID;;GAEG;AACH,yBAAiB,aAAa,CAAC;IAC7B;;;OAGG;IACI,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;KAcnB,CAAC;CACJ"}

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

@@ -0,0 +1,201 @@
+import type * as Command$ from '@effect/cli/Command';
+import { type Type } from '@dxos/echo';
+import { Plugin as Plugin$ } from '../core';
+import { Capability } from './capability';
+import { type Resource } from './translations';
+type PluginModuleOptions = Partial<Pick<Plugin$.PluginModuleOptions, 'id' | 'activatesOn' | 'activatesBefore' | 'activatesAfter'>> & Pick<Plugin$.PluginModuleOptions, 'activate'>;
+/**
+ * Helper functions for creating common plugin module patterns.
+ */
+export declare namespace Plugin {
+    type OperationResolverModuleOptions = PluginModuleOptions;
+    /**
+     * Creates a module that contributes operation handlers.
+     *
+     * @param options Module options including the activate function and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addOperationResolverModule({
+     *     activate: (context) =>
+     *       Capability.contributes(Common.Capability.OperationResolver, [{
+     *         operation: MyOperation,
+     *         handler: (input) => Effect.succeed(...)
+     *       }])
+     *   })
+     * )
+     * ```
+     */
+    function addOperationResolverModule<T = void>(options: OperationResolverModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type SurfaceModuleOptions = PluginModuleOptions;
+    /**
+     * Creates a module that contributes React surfaces.
+     *
+     * @param options Module options including the activate function and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addSurfaceModule({
+     *     activate: (context) =>
+     *       Capability.contributes(Common.Capability.ReactSurface, [
+     *         Common.createSurface({ id: `${meta.id}/my-surface`, ... })
+     *       ])
+     *   })
+     * )
+     * ```
+     */
+    function addSurfaceModule<T = void>(options: SurfaceModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type ReactRootModuleOptions = PluginModuleOptions;
+    /**
+     * Creates a module that contributes a React root.
+     */
+    function addReactRootModule<T = void>(options: ReactRootModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type ReactContextModuleOptions = PluginModuleOptions;
+    /**
+     * Creates a module that contributes a React context.
+     */
+    function addReactContextModule<T = void>(options: ReactContextModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type AppGraphModuleOptions = PluginModuleOptions;
+    /**
+     * Creates a module that contributes app graph builder extensions.
+     *
+     * @param options Module options including the activate function and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addAppGraphModule({
+     *     activate: Effect.fnUntraced(function* () {
+     *       const extensions = yield* GraphBuilder.createExtension({
+     *         id: meta.id,
+     *         match: NodeMatcher.whenRoot,
+     *         // All callbacks must return Effects.
+     *         actions: () => Effect.succeed([{
+     *           id: 'my-action',
+     *           // Action data returns Effect for automatic context access.
+     *           data: Effect.fnUntraced(function* () {
+     *             yield* Operation.invoke(MyOperation, { ... });
+     *           }),
+     *           properties: { label: 'My Action', icon: 'ph--icon' },
+     *         }]),
+     *         connector: (node, get) => Effect.succeed([{ id: 'child', ... }]),
+     *       });
+     *       return Capability.contributes(Common.Capability.AppGraphBuilder, extensions);
+     *     })
+     *   })
+     * )
+     * ```
+     */
+    function addAppGraphModule<T = void>(options: AppGraphModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type TranslationsModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+        translations: Resource | Resource[];
+    };
+    /**
+     * Creates a module that contributes translations.
+     *
+     * @param options Module options including translations and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addTranslationsModule({
+     *     translations: translations
+     *   })
+     * )
+     * ```
+     */
+    function addTranslationsModule<T = void>(options: TranslationsModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type MetadataModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+        metadata: Capability.Metadata | Capability.Metadata[];
+    };
+    /**
+     * Creates a module that contributes metadata.
+     *
+     * @param options Module options including metadata and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addMetadataModule({
+     *     metadata: {
+     *       id: MyType.typename,
+     *       metadata: { icon: 'ph--icon', ... }
+     *     }
+     *   })
+     * )
+     * ```
+     */
+    function addMetadataModule<T = void>(options: MetadataModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type SettingsModuleOptions = PluginModuleOptions;
+    /**
+     * Creates a module that contributes settings.
+     */
+    function addSettingsModule<T = void>(options: SettingsModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type BlueprintDefinitionModuleOptions = PluginModuleOptions;
+    /**
+     * Creates a module that contributes blueprint definitions.
+     *
+     * @param options Module options including the activate function and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addBlueprintDefinitionModule({
+     *     activate: (context) =>
+     *       Capability.contributes(Common.Capability.BlueprintDefinition, [
+     *         BlueprintDefinition.make({ key: 'my-blueprint', ... })
+     *       ])
+     *   })
+     * )
+     * ```
+     */
+    function addBlueprintDefinitionModule<T = void>(options: BlueprintDefinitionModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type SchemaModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+        schema: ReadonlyArray<Type.Entity.Any>;
+    };
+    /**
+     * Creates a module that contributes schemas.
+     *
+     * @param options Module options including schema array and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addSchemaModule({
+     *     schema: [MyType.Type, AnotherType.Type]
+     *   })
+     * )
+     * ```
+     */
+    function addSchemaModule<T = void>(options: SchemaModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+    type CommandModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+        commands: ReadonlyArray<Command$.Command<any, any, any, any>>;
+    };
+    /**
+     * Creates a module that contributes CLI commands.
+     *
+     * @param options Module options including commands and optional configuration
+     * @returns A function that can be used with Plugin.addModule() in a pipe chain
+     *
+     * @example
+     * ```ts
+     * Plugin.define(meta).pipe(
+     *   Common.Plugin.addCommandModule({
+     *     commands: [myCommand, anotherCommand]
+     *   })
+     * )
+     * ```
+     */
+    function addCommandModule<T = void>(options: CommandModuleOptions): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T>;
+}
+export {};
+//# sourceMappingURL=plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../src/common/plugin.ts"],"names":[],"mappings":"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"}

package/dist/types/src/common/surface.d.ts

@@ -1,6 +1,6 @@
-import type { ComponentType, PropsWithChildren, ReactNode } from 'react';
-import { type MakeOptional, type Position } from '@dxos/util';
-import { type ErrorBoundary } from '../react';
+import type { PropsWithChildren, ReactNode, RefCallback } from 'react';
+import type { MakeOptional, Position } from '@dxos/util';
+import type { ErrorBoundary } from '../react';
 /**
  * SurfaceProps are the props that are passed to the Surface component.
  */
@@ -46,15 +46,18 @@ export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unkn
      */
     limit?: number | undefined;
 }>;
-export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> & Record<string, any>;
+export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> & {
+    ref?: RefCallback<HTMLElement>;
+} & Record<string, any>;
 /**
  * React component used to render a surface once is has matched.
  */
-export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = ComponentType<SurfaceComponentProps<T>>;
+export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = (props: SurfaceComponentProps<T>) => ReactNode;
 /**
- * Definition of when a SurfaceComponent should be rendered.
+ * Definition of when a React SurfaceComponent should be rendered.
  */
-export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+export type ReactSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+    kind: 'react';
     id: string;
     role: string | string[];
     position?: Position;
@@ -62,7 +65,30 @@ export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
     filter?: (data: Record<string, unknown>) => data is T;
 }>;
 /**
- * Creates a surface definition.
+ * Definition of when a Web Component surface should be rendered.
  */
-export declare const createSurface: <T extends Record<string, any> = any>(definition: SurfaceDefinition<T>) => SurfaceDefinition<T>;
+export type WebComponentSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+    kind: 'web-component';
+    id: string;
+    role: string | string[];
+    position?: Position;
+    /**
+     * The tag name of the Web Component to render.
+     * The Web Component will receive the same props as React surfaces via properties/attributes.
+     */
+    tagName: string;
+    filter?: (data: Record<string, unknown>) => data is T;
+}>;
+/**
+ * Definition of when a surface (React or Web Component) should be rendered.
+ */
+export type SurfaceDefinition<T extends Record<string, any> = any> = ReactSurfaceDefinition<T> | WebComponentSurfaceDefinition<T>;
+/**
+ * Creates a React surface definition.
+ */
+export declare const createSurface: <T extends Record<string, any> = any>(definition: Omit<ReactSurfaceDefinition<T>, "kind">) => ReactSurfaceDefinition<T>;
+/**
+ * Creates a Web Component surface definition.
+ */
+export declare const createWebSurface: <T extends Record<string, any> = any>(definition: Omit<WebComponentSurfaceDefinition<T>, "kind">) => WebComponentSurfaceDefinition<T>;
 //# sourceMappingURL=surface.d.ts.map