@paged-media/plugin-api 0.2.42-canary.0 → 0.2.45-canary.0

package/dist/host.d.ts

@@ -8,6 +8,7 @@ import type { MutationInput } from "./mutations";
 import type { PluginManifest } from "./manifest";
 import type { SchemaPanelContribution } from "./panel-schema";
 import type { WidgetSurface } from "./widgets";
+import type { ObjectModelContribution, ObjectModelHandle, ObjectsSurface } from "./object-model";
 /** Everything a bundle registers is disposable; the host ALSO tracks
  *  it, so deactivation teardown is structural, not conventional. */
 export interface Disposable {
@@ -474,6 +475,21 @@ export interface ContributionSurface {
      * layer it submitted.
      */
     sceneLayer(): SceneLayerSurface;
+    /**
+     * Contribute this bundle's OBJECT MODEL (ADR 323, DESIGN.md §21): its
+     * object kinds — typed schema rows plus `list` / `get` / `set` / `batch`
+     * handlers — and typed commands. Every kind becomes addressable as
+     * `plugin:<manifest.id>/<kind>/<id>` through `host.objects` (and so from
+     * bindings, Boa, the Node CLI and schema-driven panel fields), headless
+     * and outside any edit context.
+     *
+     * Capability-gated: every kind must be declared in
+     * `contributes.objectModel.kinds[]` and every command in
+     * `contributes.objectModel.commands[]`; a kind with no schema rows, a row
+     * whose type is not a `ValueType`, or a duplicate path is refused loudly.
+     * Probe `supports("contribute.objectModel@1")`.
+     */
+    objectModel(model: ObjectModelContribution): ObjectModelHandle;
 }
 /** The scene-layer surface (C-1) returned by `contribute.sceneLayer()`.
  *  `elementId` is the host `Self` id of the frame to render into. */
@@ -726,6 +742,11 @@ export type MutationOutcome = {
     createdId: ElementId | null;
     pageIds: PageId[];
     minted?: MintedElement[];
+    /** The engine's sequence number of this write (the wire's
+     *  `mutationApplied.appliedSeq`), when the host knows it. A script
+     *  host bridge reports it back as `HostObjectsResult.committed` so
+     *  the write folds into the script's undo step (protocol 71). */
+    appliedSeq?: number;
 } | {
     applied: false;
     error: unknown;
@@ -1138,6 +1159,55 @@ export interface ViewportSurface {
     /** Screen px → document pt at the current zoom (the constant-
      *  screen-tolerance idiom every tool needs). */
     pxToPt(px: number): number;
+    /** v70 — bring a page into view, fitted to the viewport (a slide
+     *  sorter's click, a link to a page). `false` when the page is unknown
+     *  or the host can't navigate: probe `supports("viewport.pages@1")`. */
+    goToPage(pageId: PageId, options?: {
+        fit?: "page" | "width";
+    }): Promise<boolean>;
+    /** v70 — the page the user is on: the one the viewport's centre is
+     *  over, else the nearest (the same page `host.document.meta()`
+     *  reports as `activePage`). `null` with no document or no host
+     *  backend. */
+    activePage(): PageId | null;
+    /** v70 — fires when the active page changes (scrolling, zooming,
+     *  `goToPage`, a page deleted under it). Never fires without a host
+     *  backend. */
+    onDidChangeActivePage(listener: (pageId: PageId | null) => void): Disposable;
+}
+/** v70 — what `host.render.snapshot` renders. */
+export interface RenderSnapshotOptions {
+    /** Width of the image in device pixels, 1 to 8192; the height follows
+     *  the page's aspect. The engine renders at a resolution derived from
+     *  it, so the image can be a pixel off: `RenderedPage.widthPx` is exact. */
+    widthPx: number;
+    /** Items to leave out of this image only (a build step whose shapes
+     *  have not appeared yet). The document is not changed and no undo
+     *  step is recorded. */
+    hideItems?: ElementId[];
+}
+/** v70 — one rendered page. */
+export interface RenderedPage {
+    pageId: PageId;
+    /** The image's own size, within a pixel of the requested width. */
+    widthPx: number;
+    heightPx: number;
+    /** PNG bytes; `createImageBitmap(new Blob([png]))` draws them. */
+    png: Uint8Array;
+    /** The engine's layout generation the image shows: an image with an
+     *  older generation than a page's current one is stale. */
+    layoutGeneration: number;
+}
+/**
+ * v70 — render a page to an image with the engine's own renderer (CPU),
+ * the same pixels the canvas shows: slide thumbnails, a slideshow's
+ * frames, a build step's frames. A READ: gated on
+ * `capabilities.document.read`. `supports("render.snapshot@1")`.
+ */
+export interface RenderSurface {
+    /** The page as a PNG, or `null` when the page is unknown or the
+     *  engine refused (an invalid width). */
+    snapshot(pageId: PageId, options: RenderSnapshotOptions): Promise<RenderedPage | null>;
 }
 /** Font advance + vertical metrics, in document points (pt). */
 export interface TextMetrics {
@@ -1660,6 +1730,9 @@ export interface BundleHost {
     readonly document: DocumentSurface;
     readonly selection: SelectionSurface;
     readonly viewport: ViewportSurface;
+    /** v70 — page images from the engine's renderer (thumbnails, slideshow
+     *  frames). `supports("render.snapshot@1")`; gated on document read. */
+    readonly render: RenderSurface;
     /** Font measurement against the document's fonts (S-13). A read door,
      *  no capability gate; `supports("text.measure@1")` reports whether the
      *  host wired the engine shaper (it is false under a host that injects
@@ -1777,6 +1850,13 @@ export interface BundleHost {
      *  subscription. Always present; `supports("tools.settings@1")`
      *  reports whether a host store is wired. */
     readonly tools: ToolsSurface;
+    /** The OBJECT registry (ADR 323): one `query` / `get` / `set` / `batch` /
+     *  `schema` over core addresses and every plugin's contributed kinds.
+     *  Always present. Reads are gated on `capabilities.document.read`,
+     *  writes on `capabilities.document.write` (a refused write answers
+     *  `{ applied: false }`). `supports("objects@1")`; cross-plugin routing
+     *  (a SHARED registry the host injected) is `supports("objects.shared@1")`. */
+    readonly objects: ObjectsSurface;
     /** Capability detection over version sniffing: feature strings of
      *  the form `"area.member@major"` (see HOST_FEATURES in plugin-sdk). */
     supports(feature: string): boolean;

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, WorkersCapability, SecretsCapability, DocumentsCapability, GpuCapability, } from "./manifest";
+export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, WorkersCapability, SecretsCapability, DocumentsCapability, GpuCapability, ObjectModelDeclaration, } from "./manifest";
+export type { Address, Selector, PropertyPathName, PageItemKind, StyleFamily, ParsedAddress, AddressKind, ValueType, StructField, ValueTypeKind, PropertySchema, ContentSchema, ObjectErrorCode, ObjectValue, ObjectOp, PartChange, ObjectWrite, ObjectQuery, ObjectPredicate, ObjectKindContribution, TypedCommandContribution, ObjectModelContribution, ObjectModelHandle, ObjectWriteResult, ObjectCommandResult, ObjectChange, ObjectKindInfo, ObjectCommandInfo, ObjectsSurface, ListEdit, StructEdit, ValueEdit, } from "./object-model";
 export type { BundleHandle, PagedBundle } from "./bundle";
-export type { BundleHost, ContributionSurface, SceneLayerSurface, SceneLayerSubmitResult, SceneImage, SceneImageTile, SceneImageSubmitOptions, WillSaveEvent, ToolsSurface, ToolSettingValue, ImagesSurface, ImageResourceClaimOptions, TileBytes, WorkersSurface, BundleWorker, SpawnWorkerOptions, SecretsSurface, SecretMaterial, DocumentSurface, MutateWithBytesOptions, SelectionSurface, ViewportSurface, TextSurface, TextMetrics, TextCaret, FrameChainLink, PlanarFace, PlanarRegionsResult, StoryContent, ParagraphContent, RunContent, OverlaySurface, OverlayLayer, ShellSurface, FilePickerOptions, PickedFile, SaveFileOptions, StorageSurface, BlobSurface, BlobUsage, PartsSurface, NativeDocumentSurface, DocumentsSurface, OpenDocumentOptions, OpenDocumentResult, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, JournalSurface, JournalRecord, BindingsSurface, Diagnostic, DocumentChangeEvent, DocumentOpenedEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, ContentWheelEvent, 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, ColorPickerProps, CodeEditorProps, CodeEditorDiagnostic, CodeEditorLanguage, } from "./widgets";
+export type { BundleHost, ContributionSurface, SceneLayerSurface, SceneLayerSubmitResult, SceneImage, SceneImageTile, SceneImageSubmitOptions, WillSaveEvent, ToolsSurface, ToolSettingValue, ImagesSurface, ImageResourceClaimOptions, TileBytes, WorkersSurface, BundleWorker, SpawnWorkerOptions, SecretsSurface, SecretMaterial, DocumentSurface, MutateWithBytesOptions, SelectionSurface, ViewportSurface, RenderSurface, RenderSnapshotOptions, RenderedPage, TextSurface, TextMetrics, TextCaret, FrameChainLink, PlanarFace, PlanarRegionsResult, StoryContent, ParagraphContent, RunContent, OverlaySurface, OverlayLayer, ShellSurface, FilePickerOptions, PickedFile, SaveFileOptions, StorageSurface, BlobSurface, BlobUsage, PartsSurface, NativeDocumentSurface, DocumentsSurface, OpenDocumentOptions, OpenDocumentResult, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, JournalSurface, JournalRecord, BindingsSurface, Diagnostic, DocumentChangeEvent, DocumentOpenedEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, ContentWheelEvent, EditContextDescriptor, ObjectTypeDescriptor, PluginMetadataEnvelope, ObjectTypeBaker, BakeContext, MenuContribution, } from "./host";
+export type { PanelSchema, PanelSchemaSection, PanelSchemaRow, SchemaPanelContribution, SchemaPanelRenderer, SchemaPanelRendererProps, WidgetValueBinding, BindingRef, SchemaGate, WidgetCollectionBinding, SchemaRowAction, SchemaListAction, SchemaListSpec, PanelSchemaWidgetRow, PanelSchemaPropertyRow, PropertyFieldAddress, PropertyFieldStyle, PropertyFieldOption, PropertySubField, PropertyListPresentation, } from "./panel-schema";
+export type { WidgetSurface, ColorPickerProps, CodeEditorProps, CodeEditorDiagnostic, CodeEditorLanguage, PropertyFieldProps, PropertyFrameProps, PropertyFieldTarget, } from "./widgets";
 export type { BindingTarget, BindingPropertyRequest, BindingPropertyWrite, BindingCollectionRequest, BindingRead, BindingResolved, BindingDecline, BindingWrite, BindingCollection, BindingOp, BindingProvider, BindingProviderScope, BindingProviderHandle, BindingReadResult, BindingWriteResult, BindingCollectionResult, ActiveBindingProvider, } from "./binding-provider";
 export type { AssetSurface, AssetKind, FontFaceAsset, FontFaceFormat, } from "./assets";
-export type { ProviderTileWire } from "./wire";
+export type { ProviderTileWire, SnapshotPng } from "./wire";
 export type { SnapPointQuery, SnapPointResult, SnapPointHit, SnapAxisHit, SnapSegmentHit, SnapExclude, SnapSource, SnapSettings, } from "./wire";
 export type { MintedElement } from "./wire";
 export type { ClipboardSurface, ClipboardPayload, TabularClipboard, } from "./clipboard";

package/dist/manifest.d.ts

@@ -2,6 +2,7 @@ import type { AssetKind } from "./assets";
 /** Reverse-DNS plugin identity, e.g. `media.paged.draw`. Doubles as
  *  the namespace prefix for every contribution id the bundle
  *  registers (`media.paged.draw.tool.pen`). */
+import type { PropertySchema, ValueType } from "./object-model";
 export type PluginId = string;
 export interface PluginManifest {
     id: PluginId;
@@ -337,6 +338,14 @@ export interface PluginContributions {
      *  WITHOUT central blessing of each data type. The bytes are read/written
      *  through the `host.parts` door into the plugin's own `paged/<plugin-id>/`
      *  namespace. Purely DECLARATIVE — no runtime behaviour rides on this. */
+    /** ADR 323 — the OBJECT MODEL this bundle contributes through
+     *  `host.contribute.objectModel`. Declaring it is the capability gate: a
+     *  kind or typed command registered at runtime must be listed here. Each
+     *  `schema` / `args` is either the rows / value type INLINE or a
+     *  bundle-relative path to a JSON file holding them (plugin-cli reads
+     *  it). `plugin-cli validate` fails a kind with no schema rows, a row
+     *  whose type is not a `ValueType`, and a command with no `args`. */
+    objectModel?: ObjectModelDeclaration;
     partTypes?: Array<{
         /** A plugin-local type name (e.g. "sheet", "imageStack", "barcode"). */
         type: string;
@@ -351,3 +360,19 @@ export interface PluginContributions {
         linkable?: boolean;
     }>;
 }
+/** `contributes.objectModel` (ADR 323). */
+export interface ObjectModelDeclaration {
+    kinds: Array<{
+        kind: string;
+        title: string;
+        /** Inline schema rows, or a bundle-relative path to a JSON array. */
+        schema: string | readonly PropertySchema[];
+    }>;
+    commands?: Array<{
+        id: string;
+        title: string;
+        /** Inline value type, or a bundle-relative path to a JSON file. */
+        args: string | ValueType;
+        result?: string | ValueType;
+    }>;
+}

package/dist/mutations.d.ts

@@ -1,5 +1,5 @@
 import type { Mutation } from "./wire";
-export type { ElementId, PageId, NodeId, NodeSpec, Mutation, Operation, PropertyPath, Value, PathAnchorSpec, PathAnchorTriple, PathAnchorsResult, PathPointAddress, PathPointRole, PathfinderKind, HitFilter, HitResult, CollectionName, DocumentMeta, ElementGeometryItem, SceneTreeNode, SelectionMode, ContentSelection, MainToWorker, MainToWorkerKind, WorkerToMain, SceneLayer, SceneItem, ScenePathSeg, ScenePaint, GestureType, GestureHandle, GestureModifiers, SwatchSpec, GradientSpec, GradientStopSpec, SwatchSummary, GradientSummary, LayerSummary, } from "./wire";
+export type { ElementId, PageId, NodeId, NodeSpec, Mutation, Operation, PropertyPath, Value, PathAnchorSpec, PathAnchorTriple, PathAnchorsResult, PathPointAddress, PathPointRole, PathfinderKind, HitFilter, HitResult, CollectionName, DocumentMeta, ElementGeometryItem, SceneTreeNode, SelectionMode, ContentSelection, MainToWorker, MainToWorkerKind, WorkerToMain, SceneLayer, SceneItem, ScenePathSeg, ScenePaint, GestureType, GestureHandle, GestureModifiers, SwatchSpec, GradientSpec, GradientStopSpec, SwatchSummary, GradientSummary, LayerSummary, PageSummary, StorySummary, } from "./wire";
 /** v56 (Wave B) — close an OPEN subpath of a path element: the inverse
  *  gesture of `pathOpenAt`'s scissors cut. `subpath` picks the contour
  *  by index; omit for the default (the single/last open subpath).