@paged-media/plugin-api 0.2.32-canary.0 → 0.2.33-canary.0

package/dist/editor.d.ts

@@ -292,6 +292,24 @@ export interface OverlayRegistry {
 /** W3.2 — the edit-context registry (the shell owns the stack + chrome
  *  + write-scope; this narrow contract is just the registration door).
  *  The contribution type lives in ./host (the bundle-facing surface). */
+/** The host's menu registry, narrowed to what a bundle may do with it.
+ *
+ *  `register` only, and the item shape is the HOST's own
+ *  `MenuItemContribution` rather than the plugin-facing
+ *  `MenuContribution` — the SDK translates one into the other, turning
+ *  the declarative `scope` into the `when` predicate the host already
+ *  uses for "does this apply where you are standing". Keeping the
+ *  translation in the SDK is what lets the plugin-facing shape stay
+ *  declarative while the host keeps one vocabulary for visibility. */
+export interface MenuRegistry {
+    register(item: {
+        path: string;
+        command: string;
+        order?: number;
+        group?: string;
+        when?: (state: unknown) => boolean;
+    }): Disposable;
+}
 export interface EditContextRegistry {
     register(contribution: EditContextContribution): Disposable;
 }
@@ -320,6 +338,10 @@ export interface ShellRegistries {
      *  the contract so a host that hasn't wired the registry yet stays
      *  assignable; the SDK adapter falls back to a recording stub. */
     editContexts?: EditContextRegistry;
+    /** Menu entries (`contribute.menu`). Optional for the same reason as
+     *  `editContexts`: a host predating the door stays assignable, and the
+     *  SDK reports the contribution as unavailable rather than throwing. */
+    menus?: MenuRegistry;
     /** W3.2 — object types (W-03). Optional for the same reason. */
     objectTypes?: ObjectTypeRegistry;
     /** K-2 / S-06 — document importers (file → plugin). Optional on the

package/dist/host.d.ts

@@ -246,6 +246,77 @@ export type ObjectTypeDescriptor = ObjectTypeContribution;
  * (ids start with `<manifest.id>.`) and tracks the registration for
  * automatic teardown on deactivate.
  */
+/** A menu entry a plugin places in the host's menu bar.
+ *
+ *  WHY THIS EXISTS. Until it did, the contract had eleven contribution
+ *  types and no way to reach the menu bar, so a plugin command's only
+ *  host-wide home was the command palette — where the row shows the raw
+ *  command id where every other application puts the key, and where
+ *  nobody ever sees two creation verbs side by side. That is how six
+ *  content types came to teach six different creation idioms (Insert /
+ *  Place / Import, plus a `lowerToFrame` that is compiler vocabulary for
+ *  the step that puts the sheet on the page). The host had begun
+ *  hand-curating entries on plugins' behalf, which works and does not
+ *  scale: the host has to know each plugin by name.
+ *
+ *  TWO SCOPES, because there are two different problems and either one
+ *  alone leaves the other standing.
+ *
+ *  `"document"` is the front door: the entry is in the bar whenever a
+ *  document is open, which is what makes a content type discoverable to
+ *  someone who has not met it yet.
+ *
+ *  `{ editContext }` is the in-context surface: the entry exists only
+ *  while that edit context is active. This is the larger gap. Inside a
+ *  `vectorGraphic` the draw plugin has ~92 relevant commands; inside a
+ *  `sheet` the tool rail is deliberately EMPTY and the plugin still has
+ *  sort, find-and-replace and cell-style verbs — and in both the menu
+ *  bar shows the host's own menus, about the document the user stepped
+ *  out of. The shell already scopes the tool rail (`toolIds`) and the
+ *  Window menu (`panelIds`) to the active context; this is the same
+ *  idea applied to the third surface, and it lands on machinery that
+ *  already exists.
+ */
+export interface MenuContribution {
+    /** Slash-separated path, as the host's own menu items use.
+     *  `"Object/Insert web frame…"`, `"Sheet/Sort range…"`. A path whose
+     *  first segment names an existing menu merges into it; a new first
+     *  segment inserts a new top-level menu. */
+    path: string;
+    /** Command id this entry invokes. Must be a command the bundle has
+     *  registered — the host refuses an entry pointing at nothing, on the
+     *  same principle the tool rail refuses a dead slot: an affordance
+     *  that accepts a click and silently does nothing is worse than an
+     *  absent one, because the user reads it as their own mistake. */
+    command: string;
+    /** Lower floats up within the group. Default 100. */
+    order?: number;
+    /** Separator group; items sharing one cluster together. */
+    group?: string;
+    /** When the entry is in the bar.
+     *
+     *  `"document"` — whenever a document is open.
+     *  `{ editContext }` — only while that context is active.
+     *
+     *  Defaults to `"document"`, because an entry nobody can find is the
+     *  problem this exists to solve. */
+    scope?: "document" | {
+        editContext: string;
+    };
+    /** How a context-scoped menu meets the host's own menus.
+     *
+     *  `"augment"` (the default) leaves every host menu live alongside it.
+     *  `"replace"` hides the host's document-level menus that the context
+     *  cannot serve.
+     *
+     *  paged.doc is the case that forces this to exist: it hands the tool
+     *  rail back to the HOST's type and select tools, because a DOCX
+     *  lowers to real text frames and real stories, so the host's Type and
+     *  Edit menus genuinely still apply inside it. A door that only knew
+     *  how to replace would be right for `sheet` and `webFrame` and wrong
+     *  for precisely the one plugin whose content is native. */
+    mode?: "augment" | "replace";
+}
 export interface ContributionSurface {
     tool(contribution: ToolContribution): Disposable;
     panel(contribution: PanelContribution): Disposable;
@@ -262,6 +333,12 @@ export interface ContributionSurface {
     schemaPanel(contribution: SchemaPanelContribution): Disposable;
     command(contribution: CommandContribution): Disposable;
     keybinding(contribution: KeybindingContribution): Disposable;
+    /**
+     * Register a MENU ENTRY. See {@link MenuContribution} for the two
+     * scopes and why both are needed. The path's first segment may name an
+     * existing host menu (merging into it) or a new one.
+     */
+    menu(contribution: MenuContribution): Disposable;
     overlay(contribution: OverlayContribution): Disposable;
     /**
      * Register an EDIT CONTEXT (W3.2, closes B-02): a double-click (or

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, WorkersCapability, SecretsCapability, GpuCapability, } from "./manifest";
 export type { BundleHandle, PagedBundle } from "./bundle";
-export type { BundleHost, ContributionSurface, SceneLayerSurface, ImagesSurface, ImageResourceClaimOptions, TileBytes, WorkersSurface, BundleWorker, SpawnWorkerOptions, SecretsSurface, SecretMaterial, DocumentSurface, SelectionSurface, ViewportSurface, TextSurface, TextMetrics, TextCaret, FrameChainLink, PlanarFace, PlanarRegionsResult, StoryContent, ParagraphContent, RunContent, OverlaySurface, ShellSurface, FilePickerOptions, PickedFile, SaveFileOptions, StorageSurface, BlobSurface, BlobUsage, PartsSurface, NativeDocumentSurface, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, BindingsSurface, Diagnostic, DocumentChangeEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, EditContextDescriptor, ObjectTypeDescriptor, PluginMetadataEnvelope, ObjectTypeBaker, BakeContext, } from "./host";
+export type { BundleHost, ContributionSurface, SceneLayerSurface, ImagesSurface, ImageResourceClaimOptions, TileBytes, WorkersSurface, BundleWorker, SpawnWorkerOptions, SecretsSurface, SecretMaterial, DocumentSurface, SelectionSurface, ViewportSurface, TextSurface, TextMetrics, TextCaret, FrameChainLink, PlanarFace, PlanarRegionsResult, StoryContent, ParagraphContent, RunContent, OverlaySurface, ShellSurface, FilePickerOptions, PickedFile, SaveFileOptions, StorageSurface, BlobSurface, BlobUsage, PartsSurface, NativeDocumentSurface, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, BindingsSurface, Diagnostic, DocumentChangeEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, EditContextDescriptor, ObjectTypeDescriptor, PluginMetadataEnvelope, ObjectTypeBaker, BakeContext, MenuContribution, } from "./host";
 export type { PanelSchema, PanelSchemaSection, PanelSchemaRow, SchemaPanelContribution, SchemaPanelRenderer, SchemaPanelRendererProps, WidgetValueBinding, BindingRef, SchemaGate, WidgetCollectionBinding, SchemaRowAction, SchemaListAction, SchemaListSpec, } from "./panel-schema";
 export type { WidgetSurface, CodeEditorProps, CodeEditorDiagnostic, CodeEditorLanguage, } from "./widgets";
 export type { BindingTarget, BindingPropertyRequest, BindingPropertyWrite, BindingCollectionRequest, BindingRead, BindingResolved, BindingDecline, BindingWrite, BindingCollection, BindingOp, BindingProvider, BindingProviderScope, BindingProviderHandle, BindingReadResult, BindingWriteResult, BindingCollectionResult, ActiveBindingProvider, } from "./binding-provider";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-api",
-  "version": "0.2.32-canary.0",
+  "version": "0.2.33-canary.0",
   "description": "The Paged plugin contract: manifest, bundle lifecycle, the BundleHost surface, and the contribution + engine wire types. Type-only.",
   "license": "MPL-2.0 OR LicenseRef-PMEL",
   "type": "module",