@paged-media/plugin-api 0.2.32-canary.0 → 0.2.34-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
@@ -1158,6 +1235,40 @@ export interface DiagnosticsSurface {
     get(key: string): Diagnostic[];
     onDidChange(listener: (key: string) => void): Disposable;
 }
+/** One entry a bundle contributes to the host's journal.
+ *
+ *  The host stamps `plugin`, `seq`, `t` and `origin` — a bundle cannot forge
+ *  attribution, the same provenance rule `contribute.panel` already applies. */
+export interface JournalRecord {
+    /** Dotted, and MUST be namespaced under the manifest id — the same
+     *  chokepoint as every other contribution id, so an entry is always
+     *  attributable. e.g. `media.paged.draw.boolean.union`. */
+    code: string;
+    severity?: "debug" | "info" | "warn" | "error";
+    durMs?: number;
+    /** Bounded scalars. String values MUST match
+     *  `/^[a-z0-9][a-z0-9._:-]{0,63}$/` — a sentence, a file path, a font
+     *  family or any user text CANNOT pass, BY DESIGN. There is deliberately no
+     *  free-text field anywhere on this type: that is the field through which
+     *  PII leaks in every telemetry system ever built. A rejected value is
+     *  dropped and COUNTED, never silently truncated (a truncated path is still
+     *  a path). Keep the human sentence in `host.log`, which goes to the
+     *  console and is not part of any exported artifact. */
+    data?: Record<string, number | boolean | string>;
+}
+/** The JOURNAL door — a local, in-memory flight recorder.
+ *
+ *  With no host buffer wired this surface is INERT and
+ *  `supports("journal@1")` is false. That means "recording goes nowhere",
+ *  never "calling this throws": an instrumentation door that can break the
+ *  plugin it instruments is worse than no door. */
+export interface JournalSurface {
+    record(entry: JournalRecord): void;
+    /** Time a thunk (sync or async) and record one entry carrying `durMs` and
+     *  `data.ok`. The thunk's own result and exceptions pass through unchanged
+     *  — instrumenting a call must not alter what it returns or hide a throw. */
+    time<T>(code: string, fn: () => T | Promise<T>): Promise<T>;
+}
 export interface BindingsSurface {
     /** Publish (or update) a named reactive value. Schema rows reading
      *  `{ bind: name }` re-render on every change. JSON only. */
@@ -1233,6 +1344,9 @@ export interface BundleHost {
      *  `supports("dataProviders@1")` is false (the honest no-registry posture). */
     readonly dataProviders: DataProvidersSurface;
     readonly diagnostics: DiagnosticsSurface;
+    /** ADR 025 — the local flight recorder. Probe `supports("journal@1")`
+     *  before relying on it reaching a buffer; calling it is always safe. */
+    readonly journal: JournalSurface;
     /** Published reactive values (W3.1) — the dynamic half of schema
      *  panels: a bundle publishes named booleans (and JSON values) that
      *  schema rows reference for `visible`/`enabled`. The plugin owns the

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, JournalSurface, JournalRecord, 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.34-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",