@paged-media/plugin-api 0.2.27-canary.1 → 0.2.29-canary.0

package/dist/host.d.ts

@@ -1,8 +1,10 @@
-import type { CollectionName, DocumentMeta, ElementGeometryItem, ElementId, HitFilter, HitResult, Mutation, PageId, ElementProperties, PathAnchorsResult, SceneTreeNode, SelectionMode } from "./wire";
+import type { CollectionName, DocumentMeta, ElementGeometryItem, ElementId, HitFilter, HitResult, Mutation, PageId, ElementProperties, PathAnchorsResult, PathAnchorTriple, SceneTreeNode, SelectionMode } from "./wire";
 import type { CommandContribution, ExporterContribution, ImporterContribution, KeybindingContribution, OverlayContribution, PagedEditor, PanelContribution, ToolContribution, ToolPreviewShape } from "./editor";
 import type { SceneLayer } from "./wire";
 import type { AssetSurface } from "./assets";
+import type { BindingProvider, BindingProviderHandle } from "./binding-provider";
 import type { ClipboardSurface } from "./clipboard";
+import type { MutationInput } from "./mutations";
 import type { PluginManifest } from "./manifest";
 import type { SchemaPanelContribution } from "./panel-schema";
 import type { WidgetSurface } from "./widgets";
@@ -74,7 +76,25 @@ export interface EditContextContribution {
      *  names. Empty = no restriction (all tools stay available). */
     toolIds?: string[];
     /** Panel ids the cockpit emphasizes / raises on enter (the panel-set
-     *  swap). The shell opens/raises these; it does not hide others. */
+     *  swap).
+     *
+     *  These are the context's OWN panels. There is deliberately no sibling
+     *  field naming the SHARED host panels a context serves (ADR-023), and
+     *  the reason is worth stating because the gap looks like an omission:
+     *  a plugin naming `paged.layers` here would be host-panel IDENTITY in
+     *  plugin code — the exact coupling binding providers removed from the
+     *  value lane — and it could drift from `provides`, which is the only
+     *  declaration that decides who actually answers. The host infers
+     *  "serves" from `BindingProviderScope` instead (DESIGN.md §18.12).
+     *
+     *  WHAT THE HOST GUARANTEES, corrected 2026-08-05: it OPENS these. It
+     *  raises them too, EXCEPT when raising would displace a panel the
+     *  entering context's own binding providers serve — because in a dock
+     *  that shows one panel at a time, "raise mine" IS "hide the shared
+     *  one", and hiding it at the instant it retargets defeats the whole
+     *  point. (This comment used to promise "it does not hide others"
+     *  unconditionally; that was never true in such a dock.) A withheld
+     *  raise still opens the tab, so the surface is reachable either way. */
     panelIds?: string[];
     /** Called when the context becomes active (after the stack push + the
      *  scope narrowing). The element entered on is passed so the hook can
@@ -252,6 +272,35 @@ export interface ContributionSurface {
      * `contributes.exporters[]`.
      */
     exporter(contribution: ExporterContribution): Disposable;
+    /**
+     * Register a BINDING PROVIDER (ADR-023 phase A): while the edit
+     * context named by `contextType` is ACTIVE, this bundle resolves what
+     * the HOST's own panels bind to — typed property paths, named
+     * collections, and first refusal on structural mutation ops. Reads and
+     * writes both.
+     *
+     * This is the inversion the panel-duplication problem needs: instead
+     * of minting a fourth Layers panel, a bundle serves the ONE host
+     * Layers panel's values for its own content type. See
+     * binding-provider.ts for the three-lane shape, the core-vocabulary-
+     * only rule, and the precedence model.
+     *
+     * LIFETIME is borrowed, not declared: `contextType` must be a type
+     * this SAME bundle already registered through `contribute.editContext`
+     * (an unregistered type is refused loudly — a provider that can never
+     * activate is a bug, not a stance). The capability gate is that
+     * context's: `contributes.editContexts[]` must declare the type. There
+     * is deliberately NO separate manifest field and NO separate
+     * capability — the authority a provider exercises is the authority the
+     * active context already holds over the selection it owns.
+     *
+     * Always present. When the host wires no shared registry, the door
+     * warns + returns an inert handle (nothing will ever consult the
+     * provider) and `supports("bindings.provider@1")` is false; probe
+     * `supports("contribute.bindingProvider@1")` for whether this SDK has
+     * the door at all.
+     */
+    bindingProvider(contextType: string, provider: BindingProvider): BindingProviderHandle;
     /**
      * Open a SCENE-LAYER surface (C-1): submit vector content that renders
      * INSIDE a frame, in frame-content coordinates — core applies the
@@ -516,8 +565,75 @@ export interface RunContent {
     position?: string | null;
     tracking?: number | null;
 }
+/**
+ * B-22 (protocol v57) — one FACE of a planar arrangement: a connected
+ * region of the plane whose containment signature is constant. This is
+ * the level BELOW element hit-testing (the areas overlapping paths
+ * divide the plane into), which is what a Shape Builder needs.
+ *
+ * Coordinates are in the RAW path space `pathAnchors` reports —
+ * per-element `itemTransform`s are NOT composed in (the arrangement runs
+ * on the anchors as stored, exactly like `pathfinderBoolean`). A consumer
+ * that draws faces on canvas maps them with the frontmost input's
+ * `itemTransform`, the same chain the anchor overlays use.
+ */
+export interface PlanarFace {
+    /** Stable id (`"<signature>#<component>"`, e.g. `"0-1#0"`) — stable
+     *  across calls with the same inputs, which is what lets a hovered
+     *  face's id ride straight into the `pathfinderFaces` mutation
+     *  (mutations.ts) without a second query. */
+    id: string;
+    /** Indices into the REQUEST's `elementIds` whose interior contains
+     *  this face. */
+    signature: number[];
+    /** The face outline (closed). A face with holes carries them as extra
+     *  contours. */
+    anchors: PathAnchorTriple[];
+    /** Per-contour boundaries into `anchors`. */
+    subpathStarts: number[];
+    /** Unsigned area, outer contour minus holes. */
+    area: number;
+    /** A point strictly inside the face — what a hover highlight or a fill
+     *  drop keys off without re-deriving containment. */
+    inside: [number, number];
+}
+/**
+ * B-22 (protocol v57) — the full result of `document.planarRegions`.
+ *
+ * Deliberately NOT a bare face array: the door has THREE distinct
+ * answers a caller must be able to tell apart, and flattening them
+ * would make a refusal indistinguishable from "these paths divide into
+ * nothing":
+ *   · `found: true` — `faces` is the answer (possibly empty: a point
+ *     query outside every input);
+ *   · `found: false` + `reason` — a REFUSAL (no document, an id that
+ *     doesn't resolve, more inputs than the kernel's cap, or a host
+ *     whose engine predates the door). Never a truncated answer;
+ *     surface the engine's own words, never an empty face list.
+ *   · `complete: false` — the listed faces are all REAL but do not tile
+ *     the union of the inputs (the enumeration missed a sliver). Always
+ *     `true` for a point query — one face is not a tiling claim.
+ */
+export interface PlanarRegionsResult {
+    /** `false` ⇒ the query could not be answered at all; read `reason`. */
+    found: boolean;
+    /** Populated when `found`. With a `point` in the request this holds at
+     *  most one face (empty ⇒ the point is outside every input). */
+    faces: PlanarFace[];
+    /** How many inputs the arrangement was built from. */
+    inputCount: number;
+    /** `true` when the resolved faces tile the union of the inputs. */
+    complete: boolean;
+    /** Why `found` is false — the engine's own words (or the host
+     *  adapter's, when no v57 engine answered). Absent on success. */
+    reason?: string | null;
+}
 export interface DocumentSurface {
-    mutate(mutation: Mutation): Promise<MutationOutcome>;
+    /** The single write door. Accepts `MutationInput` — the vendored
+     *  `Mutation` union PLUS the protocol-ahead ops the vendored wire
+     *  hasn't absorbed yet (see mutations.ts). Widening an accepted
+     *  input is additive: every `Mutation` still passes. */
+    mutate(mutation: MutationInput): Promise<MutationOutcome>;
     undo(): Promise<void>;
     redo(): Promise<void>;
     collection<T>(name: CollectionName): Promise<readonly T[]>;
@@ -528,6 +644,33 @@ export interface DocumentSurface {
      *  against). Retires the v0 `host.editor.client.send` escape hatch
      *  the draw fill panel used. `null` for an unknown element. */
     elementProperties(id: ElementId): Promise<ElementProperties | null>;
+    /**
+     * B-22 (protocol v57) — the planar-REGION read door: resolve the faces
+     * of the arrangement `elementIds` forms (the areas the overlapping
+     * paths divide the plane into, one level below element hit-testing).
+     * Retires the v0 `host.editor.client.send({ kind:
+     * "requestPlanarRegions" })` escape hatch paged.draw's Shape Builder
+     * used.
+     *
+     * With `point` (in the RAW path space `pathAnchors` reports) it answers
+     * ONLY the face under it — the hover query, which costs N
+     * point-in-path tests plus one region materialisation instead of a
+     * full enumeration. Without it, every face comes back.
+     *
+     * Pure READ, gated on `capabilities.document.read`. Face ids are stable
+     * for the same inputs, so a hovered id is handed straight to the
+     * `pathfinderFaces` mutation.
+     *
+     * Answers the FULL {@link PlanarRegionsResult} — never a bare face
+     * array — because a refusal (`found: false` + `reason`: input cap,
+     * unresolvable id, or a host whose engine predates the door) must not
+     * be readable as "no regions". A host that cannot answer comes back as
+     * a refusal with a reason — never a throw (the undeclared-capability
+     * gate is the one exception, as on every read door). Probe
+     * `supports("document.planarRegions@1")` for whether the facade
+     * forwards at all.
+     */
+    planarRegions(elementIds: ElementId[], point?: [number, number]): Promise<PlanarRegionsResult>;
     /** D-01 (protocol v43) — enumerate every plugin-tagged placeholder
      *  field in the document, in story order. Offsets are FRESH-READ
      *  addresses (a placeholder is its own tagged run; re-enumerate
@@ -538,6 +681,31 @@ export interface DocumentSurface {
     hitTest(pageId: PageId, point: [number, number], filter?: HitFilter): Promise<HitResult | null>;
     elementGeometry(ids: ElementId[]): Promise<ElementGeometryItem[]>;
     tree(): Promise<SceneTreeNode[]>;
+    /**
+     * C-16 — the per-element PARENTAGE read: the nearest ANCESTOR that is
+     * itself an addressable element (a group today — the only element kind
+     * that nests page items), or `null` when there is none.
+     *
+     * Consumer: paged.draw's `selectParentGroup` command
+     * (`draw-bundle/src/commands/select-parent-group.ts`), which climbs to
+     * the containing group on every press. Without this door it re-read
+     * `tree()` and walked the WHOLE scene tree per invocation — O(document)
+     * per keystroke, a cost its own module header records as a named gap.
+     *
+     * `null` is the honest answer for three distinct cases a caller need
+     * not distinguish: the element is top-level (its container is a Page /
+     * Spread, which is NOT an element and never a selection target), the
+     * id does not resolve, or the address is a story/table range (those
+     * never nest in groups).
+     *
+     * A pure READ gated on `capabilities.document.read`, resolved from the
+     * SAME scene-tree the `tree()` door reads — no extra engine query and
+     * no wire op of its own (DESIGN.md §4.3d). The host keeps a parent
+     * index and rebuilds it when the document changes, so the O(document)
+     * walk happens once per EDIT rather than once per press. It is
+     * therefore exactly as fresh as `tree()` and no fresher.
+     */
+    parentOf(id: ElementId): Promise<ElementId | null>;
     /** Read a text frame's thread topology (protocol v38, C-2/S-05) — the
      *  ordered chain of frames a story flows through, tail-overflow flagged.
      *  Empty when the story has no frame or no document is loaded. A
@@ -629,6 +797,23 @@ export interface TextMetrics {
     /** Face descender at `sizePt` (negative below the baseline). */
     descender: number;
 }
+/**
+ * C-9 — the user's text caret: the story + insertion offset a
+ * text-inserting plugin should target (paged.data first-insert
+ * placement — without this door a freshly-placed variable field lands
+ * at story start, offset 0).
+ *
+ * `offset` is a story-local content offset in the SAME convention the
+ * engine's text mutations consume (`insertText.offset`,
+ * `deleteRange.start/end` — the `ContentSelection` addressing: run
+ * bytes plus one synthetic `\n` per inter-paragraph boundary), so the
+ * value can be passed straight to `host.document.mutate`.
+ */
+export interface TextCaret {
+    storyId: string;
+    /** Insertion offset (see the offset-convention note above). */
+    offset: number;
+}
 /**
  * Text measurement against the loaded document's fonts (S-13). A read
  * door — no capability gate (like {@link ViewportSurface}); it wraps the
@@ -640,12 +825,51 @@ export interface TextMetrics {
  */
 export interface TextSurface {
     measureString(family: string, style: string | null, text: string, sizePt: number): Promise<TextMetrics>;
+    /**
+     * C-9 — read the user's text caret (the active `ContentSelection`),
+     * or `null` when no text caret is active OR the host injects no
+     * caret reader (probe `supports("text.caret@1")` to tell the two
+     * apart). For a collapsed selection this is the caret offset; for a
+     * RANGE selection it answers the range START (where a replace
+     * inserts). Honest v1 gap: a caret inside a TABLE CELL
+     * (cell-qualified selection) answers `null` — cell-local offsets
+     * would be misread as story-local body offsets.
+     */
+    caret(): TextCaret | null;
 }
 /** The v0 overlay channel: the shared tool-preview signal (polyline /
- *  rect). Retained plugin scene layers are the P2 channel — reserved,
- *  not faked. */
+ *  rect / path — and, with `supports("overlay.text@1")`, the TEXT
+ *  primitive `ToolPreviewText` for on-canvas readouts). Retained
+ *  plugin scene layers are the P2 channel — reserved, not faked. */
 export interface OverlaySurface {
     setToolPreview(shape: ToolPreviewShape | null): void;
+    /**
+     * K-9 — publish MANY preview shapes at once (DESIGN.md §4.5a). The
+     * single-slot `setToolPreview` is last-write-wins, so a tool could
+     * show geometry OR a label, never both: paged.draw's **Measure** trades
+     * the frozen line for the frozen readout at pointer-up, and its region
+     * **Shape Builder** can highlight one hovered face but not shade the
+     * whole collected set. Both trades are named in that bundle's code;
+     * this door retires them.
+     *
+     * ONE SLOT, two writers: this REPLACES whatever the tool-preview slot
+     * holds with `shapes` (rendered in array order, first = bottom-most);
+     * `null` — or an empty array — clears it, exactly like
+     * `setToolPreview(null)`. It is not a second overlay layer (that would
+     * resurrect z-ordering and double the teardown paths).
+     *
+     * Shapes may address DIFFERENT pages: each carries its own `pageId`
+     * and the host resolves the page rect per shape.
+     *
+     * Same `capabilities.rendering` ∋ `"overlay"` gate as
+     * `setToolPreview` — one channel, one gate. Probe
+     * `supports("overlay.multiPreview@1")`: it is DYNAMIC (unlike the
+     * static `overlay.text@1`), true only when the host wired a real
+     * multi-shape sink. When it is false the door still works and never
+     * throws — it forwards the FIRST shape through the single slot, which
+     * is precisely the pre-K-9 behaviour a bundle used to hand-code.
+     */
+    setToolPreviews(shapes: readonly ToolPreviewShape[] | null): void;
 }
 /**
  * Shell actions the HOST APP injects at `loadBundle` time (the
@@ -653,6 +877,11 @@ export interface OverlaySurface {
  * function over the editor handle). When the host app provides no
  * implementation, calls warn and no-op — probe with
  * `host.supports("shell.openPanel@1")`.
+ *
+ * The two FILE doors are a pair: `pickFile` reads bytes IN (K-5 / S-11),
+ * `saveFile` hands bytes OUT (K-10). Both are byte-level by design —
+ * no DOM `File`/`Blob` ever crosses the contract — and both answer an
+ * honest "nothing happened" value rather than throwing.
  */
 export interface ShellSurface {
     /** Open a REGISTERED panel as the active dock tab (the
@@ -665,6 +894,42 @@ export interface ShellSurface {
      *  the user cancels OR no picker is wired (the honest no-picker door);
      *  probe `host.supports("shell.pickFile@1")` for the latter. */
     pickFile(options?: FilePickerOptions): Promise<readonly PickedFile[]>;
+    /**
+     * K-10 — the WRITE half of the picker door: hand the host bytes to
+     * deliver to the user's filesystem under `suggestedName` (DESIGN.md
+     * §4.5c). The mirror of `pickFile`: bytes cross, never a DOM `File`
+     * or a `Blob`, so a bundle stays isolate-ready.
+     *
+     * Consumer: **paged.image**, which can compute an adjusted
+     * PSD/PNG/JPEG but — with `pickFile` READ-only — could only deliver it
+     * through the Export Center's exporter registry, so "Save adjusted
+     * copy…" was unofferable from the bundle's own panel.
+     *
+     * Answers `true` when the host ACCEPTED the bytes and handed them to
+     * its save path, `false` when it did not — no saver wired (probe
+     * `supports("shell.saveFile@1")` to know that up front), the user
+     * declined, or the host refused. Never throws: a refused save is a
+     * result, like a refused mutation. Honest ceiling: a host backed by
+     * the browser's anchor-download cannot observe a user cancel, so
+     * `true` means "delivered to the browser's download path", not "a file
+     * exists on disk"; a File System Access backing can answer a real
+     * `false`.
+     */
+    saveFile(options: SaveFileOptions): Promise<boolean>;
+}
+/** What `ShellSurface.saveFile` delivers (K-10) — the inverse of
+ *  {@link PickedFile}, field-for-field, so bytes picked from disk can be
+ *  handed straight back after an edit. */
+export interface SaveFileOptions {
+    /** File name incl. extension the host proposes to the user (it may
+     *  sanitize or de-duplicate it — the name is a suggestion, not a
+     *  path; a bundle can never target a location). */
+    suggestedName: string;
+    /** The bytes to write. */
+    bytes: Uint8Array;
+    /** MIME type for the saved file (same field name as `PickedFile`).
+     *  Absent ⇒ the host uses `application/octet-stream`. */
+    mimeType?: string;
 }
 /** Filter + multiplicity for `ShellSurface.pickFile` (K-5 / S-11). */
 export interface FilePickerOptions {

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 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, FrameChainLink, StoryContent, ParagraphContent, RunContent, OverlaySurface, ShellSurface, FilePickerOptions, PickedFile, 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 { PanelSchema, PanelSchemaSection, PanelSchemaRow, SchemaPanelContribution, SchemaPanelRenderer, SchemaPanelRendererProps, WidgetValueBinding, BindingRef, SchemaGate, } from "./panel-schema";
+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 { 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";
 export type { AssetSurface, AssetKind, FontFaceAsset, FontFaceFormat, } from "./assets";
 export type { ProviderTileWire } from "./wire";
 export type { ClipboardSurface, ClipboardPayload, TabularClipboard, } from "./clipboard";

package/dist/mutations.d.ts

@@ -1 +1,275 @@
+import type { ElementId, 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";
+/** 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).
+ *  Coincident endpoints — the duplicated pair a cut leaves — merge back
+ *  into one anchor; endpoints apart gain the implicit closing edge. */
+export type ClosePathMutation = {
+    op: "closePath";
+    args: {
+        elementId: ElementId;
+        subpath?: number | null;
+    };
+};
+/** v56 (Wave B) — weld two OPEN single-contour path elements into one
+ *  (InDesign's Join): connect the NEAREST endpoints of `elementId` and
+ *  `otherId`, then delete `otherId`. Both endpoint pairs coincident
+ *  closes the result into a ring. Non-path / closed / multi-contour
+ *  inputs are rejected with an honest error (no-op). One undo step
+ *  restores BOTH elements. */
+export type JoinPathsMutation = {
+    op: "joinPaths";
+    args: {
+        elementId: ElementId;
+        otherId: ElementId;
+    };
+};
+/** v56 (B-18) — InDesign paste-into: nest an existing TOP-LEVEL page
+ *  item inside a container Rectangle / Oval / Polygon. The child keeps
+ *  its document-space geometry (nothing moves on canvas) and renders
+ *  clipped by the container's outline. Grouped / already-nested
+ *  children and non-container hosts are rejected with an honest error.
+ *  One undo pops the child back to its exact stacking slot. */
+export type PasteIntoMutation = {
+    op: "pasteInto";
+    args: {
+        containerId: ElementId;
+        childId: ElementId;
+    };
+};
+/** v56 (B-18) — the inverse gesture: pop a pasted-in child back to top
+ *  level (stacks on top), world transform preserved. One undo re-nests
+ *  it at the same child index. */
+export type ReleaseFromMutation = {
+    op: "releaseFrom";
+    args: {
+        childId: ElementId;
+    };
+};
+/** v57 (B-22) — every face of the arrangement becomes its own object,
+ *  keeping the attributes of the topmost input covering it. */
+export type PathfinderDivideMutation = {
+    op: "pathfinderDivide";
+    args: {
+        elementIds: ElementId[];
+    };
+};
+/** v57 (B-22) — each input is clipped to the part nothing above it
+ *  covers, and loses its stroke. Inputs entirely hidden are deleted. */
+export type PathfinderTrimMutation = {
+    op: "pathfinderTrim";
+    args: {
+        elementIds: ElementId[];
+    };
+};
+/** v57 (B-22) — Trim, then coalesce: inputs that share a fill colour
+ *  merge into one object. */
+export type PathfinderMergeMutation = {
+    op: "pathfinderMerge";
+    args: {
+        elementIds: ElementId[];
+    };
+};
+/** v57 (B-22) — keep only what falls inside the TOPMOST input, coloured
+ *  by the objects beneath it; the topmost input is consumed as the
+ *  cookie cutter and disappears. */
+export type PathfinderCropMutation = {
+    op: "pathfinderCrop";
+    args: {
+        elementIds: ElementId[];
+    };
+};
+/** v57 (B-22) — fills become strokes: every arrangement edge (split at
+ *  each crossing) becomes an open `GraphicLine` stroked with the fill of
+ *  the input that contributed it. All inputs are consumed. */
+export type PathfinderOutlineMutation = {
+    op: "pathfinderOutline";
+    args: {
+        elementIds: ElementId[];
+    };
+};
+/** v57 (B-22) — the BACKMOST object minus every object in front of it. */
+export type PathfinderMinusBackMutation = {
+    op: "pathfinderMinusBack";
+    args: {
+        elementIds: ElementId[];
+    };
+};
+/** v57 (B-22) — whether `pathfinderFaces` KEEPS the named faces or
+ *  REMOVES them (Shape Builder's drag vs alt-drag). */
+export type FaceSelectMode = "keep" | "remove";
+/** v57 (B-22) — Shape Builder's click/drag output: unite the named faces
+ *  of the arrangement into one result element. `faces` carries the
+ *  STABLE ids `host.document.planarRegions` reported for the SAME
+ *  `elementIds` (ids are only stable per input set); `mode` picks
+ *  whether they are the faces kept or the faces removed. An unknown id
+ *  is REFUSED, not ignored — a stale face set fails loudly. */
+export type PathfinderFacesMutation = {
+    op: "pathfinderFaces";
+    args: {
+        elementIds: ElementId[];
+        faces: string[];
+        mode: FaceSelectMode;
+    };
+};
+/** v58 (C-28) — how the mask artwork's coverage is read. `luminosity`
+ *  is Illustrator's default and PDF's `/S /Luminosity`; `alpha` reads
+ *  the artwork's alpha channel instead. Unpainted area means HIDDEN for
+ *  both (PDF's black backdrop). Omitted = `luminosity`. */
+export type OpacityMaskType = "luminosity" | "alpha";
+/** v58 (C-28) — **Make Opacity Mask**: `maskId`'s artwork becomes a soft
+ *  mask over `targetId`. The mask item leaves the page's z-order (its
+ *  slot is captured) and one undo pops it back exactly.
+ *
+ *  RENDERS EVERYWHERE. An earlier revision of this comment warned that
+ *  the mask was honoured by the CPU rasterizer and PDF export but NOT by
+ *  the Vello/WebGPU backend the editor canvas uses, so a plugin must not
+ *  imply WYSIWYG. **That is no longer true, and it was never as
+ *  fundamental as it read**: the claim rested on the belief that Vello
+ *  lacked a coverage-buffer API, when the pinned version has
+ *  `Scene::push_luminance_mask_layer` (an unrelated 0.3.0 entry in
+ *  `Cargo.lock`, belonging to a spike crate, was misread as the resolved
+ *  version). Alpha masks need no mask layer at all — `Compose::DestIn`
+ *  IS `dst · src.a`.
+ *
+ *  Vello output is now byte-identical to the CPU rasterizer across
+ *  luminosity, alpha and both inverted forms. Safe to build WYSIWYG UI
+ *  over. */
+export type ApplyOpacityMaskMutation = {
+    op: "applyOpacityMask";
+    args: {
+        targetId: ElementId;
+        maskId: ElementId;
+        maskType?: OpacityMaskType | null;
+        invert?: boolean | null;
+    };
+};
+/** v58 (C-28) — drop the mask relation; the artwork returns to top level
+ *  with its geometry untouched. One undo re-applies the mask with its
+ *  original mode/invert at the same z slot. */
+export type ReleaseOpacityMaskMutation = {
+    op: "releaseOpacityMask";
+    args: {
+        targetId: ElementId;
+    };
+};
+/** v58 (C-29) — **Type on a Path**: flow an existing story along an
+ *  existing path element. The engine could already RENDER type on a path
+ *  loaded from an IDML; until v58 nothing could create one.
+ *
+ *  Hosts are Rectangle / GraphicLine / Polygon. A TextFrame is refused
+ *  WITH a reason: its glyphs are emitted by the story pass, so accepting
+ *  it would produce a visible lie. `pathTypeAlignment` (Baseline /
+ *  Center honoured), `flipPathEffect` and the `startBracket`/`endBracket`
+ *  range are all live. `PathEffect` is deliberately NOT exposed — only
+ *  `RainbowPathEffect` actually renders. */
+export type AttachTextToPathMutation = {
+    op: "attachTextToPath";
+    args: {
+        elementId: ElementId;
+        storyId: string;
+        pathTypeAlignment?: string | null;
+        flipPathEffect?: string | null;
+        startBracket?: number | null;
+        endBracket?: number | null;
+    };
+};
+/** v58 (C-29) — unlink the text from the path; the exact inverse. */
+export type DetachTextFromPathMutation = {
+    op: "detachTextFromPath";
+    args: {
+        elementId: ElementId;
+    };
+};
+/** v59 (Arrange) — where `reorderElement` puts its target inside the
+ *  sibling list it already belongs to. `0` is the BACKMOST slot (painted
+ *  first). Prefer the four verbs: they are evaluated against the order
+ *  the engine holds at apply time, so a concurrent insert or delete
+ *  cannot make them restack the wrong item. `{ index }` is absolute and
+ *  therefore CAN go stale — an out-of-range index is refused with an
+ *  honest error, never clamped. */
+export type ZOrderTarget = "front" | "back" | "forward" | "backward" | {
+    index: number;
+};
+/** v59 (Arrange) — **the z-order door**: restack an element within the
+ *  sibling list it already belongs to. Nothing on the wire could change
+ *  stacking before v59, which is why so many bundles carry "inserted
+ *  items land on top of the z-order" as an accepted limit — that
+ *  sentence is retired by this op.
+ *
+ *  The sibling list is DERIVED from where the element already is: a
+ *  top-level item restacks in the spread's z table, a group member
+ *  inside its group, a pasted-in child inside its container. There is no
+ *  parent argument, so a reorder can never move an element between those
+ *  scopes — for that use `createGroup` / `dissolveGroup` /
+ *  `pasteInto` / `releaseFrom`. An opacity-mask artwork is painted from
+ *  no list at all and is refused. One undo restores the previous order
+ *  exactly (the engine's inverse carries the slot the item came from).
+ *
+ *  CREATE-THEN-ARRANGE in one undo step — the Live Paint shape (fill a
+ *  face, then put the fill UNDER the strokes bounding it) — is a batch
+ *  of `[insert…, bindCreated { handle }, reorderElement
+ *  { elementId: "$h:<handle>", to: "back" }]`. The `bindCreated` is
+ *  required: the bare `$created` sentinel is understood by
+ *  `setPluginMetadata` / `setElementProperty` only, while the generic
+ *  handle resolver — the one that rewrites any id position of any op —
+ *  is armed by a `bindCreated` child being present.
+ *
+ *  HONEST LIMIT 1 — Arrange is WITHIN a layer. The renderer sorts by
+ *  `ItemLayer` before it paints, so bring-to-front cannot lift an
+ *  element above one on a higher layer. That is InDesign's model:
+ *  crossing layers is a property write, not an Arrange.
+ *
+ *  HONEST LIMIT 2 — the new order shows on canvas and survives a
+ *  `.paged` save, but NOT an `.idml` export: the IDML writer re-emits
+ *  existing source elements byte-for-byte and only places new ones, so a
+ *  reorder reverts on an export/reopen round trip. Do not present
+ *  Arrange as durable across IDML interchange yet. */
+export type ReorderElementMutation = {
+    op: "reorderElement";
+    args: {
+        elementId: ElementId;
+        to: ZOrderTarget;
+    };
+};
+/** The protocol-ahead ops, as one union — the delta between the
+ *  vendored `Mutation` (protocol 51) and core's protocol 59. Empties
+ *  itself on the next `sync-wire.mjs` run. */
+/** v57 (C-15) — name the id a creating sibling is about to mint, so a
+ *  LATER child of the same batch can address it as `"$h:<handle>"`.
+ *
+ *  This is what collapses a two-batch flow into ONE undo step. Before it,
+ *  a bundle that inserted geometry and then painted or grouped it had to
+ *  issue two batches, because a batch op could not reference an id minted
+ *  in the same batch — paged.draw's appearance bake, pattern bake and
+ *  re-plan, compound-path release, symbol place, image trace and
+ *  live-paint fill all pay two undo steps for exactly that reason.
+ *
+ *  Three rules, each of which was measured against the engine rather than
+ *  assumed, because getting any of them wrong fails in a confusing way:
+ *
+ *  1. **Order matters.** The bind must come AFTER the creating child.
+ *     Placed before, the batch is refused BY NAME (an honest error, not a
+ *     silent no-op).
+ *  2. **It is its own op, not a field.** Passing a handle inside a
+ *     creating op's own `args` is SILENTLY IGNORED — which is what made
+ *     an early probe read as "the engine doesn't support this".
+ *  3. **Scope is the declaring batch**, visible to its own later children
+ *     including nested batches, never outward. A `$h:` appearing in TEXT
+ *     content is content and is never rewritten.
+ *
+ *  Generalises the v34 `$created` sentinel — which only two mutation
+ *  kinds understood — to any number of live names addressable from any
+ *  mutation kind. */
+export type BindCreatedMutation = {
+    op: "bindCreated";
+    args: {
+        handle: string;
+    };
+};
+export type PendingMutation = BindCreatedMutation | ClosePathMutation | JoinPathsMutation | PasteIntoMutation | ReleaseFromMutation | PathfinderDivideMutation | PathfinderTrimMutation | PathfinderMergeMutation | PathfinderCropMutation | PathfinderOutlineMutation | PathfinderMinusBackMutation | PathfinderFacesMutation | ApplyOpacityMaskMutation | ReleaseOpacityMaskMutation | AttachTextToPathMutation | DetachTextFromPathMutation | ReorderElementMutation;
+/** What `host.document.mutate` ACCEPTS: the vendored op union plus the
+ *  protocol-ahead ops. Widening an accepted-input type is additive —
+ *  every existing `Mutation` call site still compiles. */
+export type MutationInput = Mutation | PendingMutation;