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

package/dist/binding-provider.d.ts

@@ -0,0 +1,331 @@
+import type { Disposable, MutationOutcome } from "./host";
+import type { MutationInput } from "./mutations";
+import type { CollectionName, ElementId, PropertyPath, Value } from "./wire";
+/**
+ * WHAT a property resolution addresses. Three variants, one per shape
+ * the proof consumers need — and no more:
+ *
+ *   · `selection` — the host's CURRENT selection in the given scope.
+ *     The default for a panel binding, and the ONLY variant a
+ *     `WidgetValueBinding` produces today (its `scope` field maps here
+ *     1:1). The provider resolves it IN ITS OWN REALM: it already knows
+ *     which raster layer / which cell / which DOCX run is selected, so
+ *     the host never has to name a thing it cannot address.
+ *   · `element` — a core-addressable target the host names explicitly.
+ *     `ElementId` ALREADY models both halves the consumers need: the
+ *     element kinds (`rectangle`, `textFrame`, `group`, …) AND the
+ *     range kinds (`storyRange` carries `{story_id, start, end}`;
+ *     `tableCell` carries the cell address). Range-scoped addressing is
+ *     therefore admitted by core's own type — this contract does not
+ *     invent a parallel one.
+ *   · `row` — a row this provider itself handed out through
+ *     `readCollection`. The id is the PROVIDER's vocabulary, opaque to
+ *     the host, which is what lets plugin-image key rows by its own
+ *     stable layer ids while the editor keys them by `selfId`.
+ *
+ * There is deliberately NO document-scoped target variant: the
+ * document-scoped lanes (`readCollection`, `applyMutation`) take no
+ * target at all, because a swatch list is not "the value of a path for
+ * a thing".
+ */
+export type BindingTarget = {
+    kind: "selection";
+    /** Which selection surface — mirrors `WidgetValueBinding.scope`.
+     *  `"element"` is the page-item selection; `"content"` is the text
+     *  caret / range selection (the Character-panel lane). */
+    scope: "element" | "content";
+} | {
+    kind: "element";
+    id: ElementId;
+} | {
+    kind: "row";
+    /** The collection the row came from — a provider only ever gets a
+     *  row target for a collection it declared. */
+    collection: CollectionName;
+    /** The row's id, in the shape the provider's own rows carry. */
+    id: string;
+};
+/** A property READ: one typed path at one target. */
+export interface BindingPropertyRequest {
+    path: PropertyPath;
+    target: BindingTarget;
+}
+/** A property WRITE: the read request plus the typed payload. The
+ *  payload is a core `Value` — see the vocabulary rule in this file's
+ *  header; a provider that cannot express its own storage as a `Value`
+ *  declines rather than inventing one. */
+export interface BindingPropertyWrite extends BindingPropertyRequest {
+    value: Value;
+}
+/** A collection READ. DOCUMENT-SCOPED: no target, because a swatch list
+ *  or a layer list belongs to the document, not to a selection. */
+export interface BindingCollectionRequest {
+    collection: CollectionName;
+}
+/**
+ * A provider's answer to a property READ. FOUR states, and the
+ * distinctions are load-bearing — collapsing any two of them produces a
+ * user-visible lie:
+ *
+ *   · `value` — a definite value.
+ *   · `mixed` — the target spans SEVERAL values (a multi-format
+ *     character range, a multi-row selection). The panel must show
+ *     "mixed", never pick a winner. This mirrors core's OWN convention
+ *     exactly: `PropertyEntry.value` is `Value | null`, and the wire's
+ *     own comment says `None` signals "mixed / indeterminate — a
+ *     `StoryRange` whose `CharacterRun`s carry conflicting values".
+ *   · `absent` — this provider OWNS the target, but the path does not
+ *     apply to it (a raster text layer with no leading concept). The
+ *     panel blanks / disables the row; it does NOT fall through to
+ *     core, because core has no opinion about a thing it does not hold.
+ *   · `decline` — NOT MINE right now. Resolution continues down the
+ *     active-provider stack and then falls through to core.
+ *
+ * `absent` vs `decline` is the pair most easily conflated and the most
+ * expensive to conflate: fall through on an owned-but-inapplicable path
+ * and the panel shows the CORE text frame's leading while the user is
+ * editing a raster layer.
+ */
+export type BindingRead = BindingResolved | BindingDecline;
+/** The answers that CLAIM the target (everything but `decline`). */
+export type BindingResolved = {
+    kind: "value";
+    value: Value;
+} | {
+    kind: "mixed";
+} | {
+    kind: "absent";
+    reason?: string;
+};
+/** "Not mine" — keep looking (the next active provider, then core). */
+export interface BindingDecline {
+    kind: "decline";
+    reason?: string;
+}
+/**
+ * A provider's answer to a WRITE (property or structural).
+ *
+ * `applied` carries a {@link MutationOutcome} — the SAME type
+ * `host.document.mutate` answers — deliberately, so the host panel has
+ * ONE code path for the provider write and the core fall-through write.
+ * A provider that simply forwards to `host.document.mutate` returns its
+ * outcome unchanged; a provider writing its own storage answers
+ * `{ applied: true, createdId: null, pageIds: [] }` — an empty
+ * `pageIds` is the honest "no engine page changed", not a placeholder.
+ * A refused write (a locked layer) is `{ applied: false, error }`, not
+ * a `decline`: the provider owned it and said no.
+ *
+ * THE UNDO RULE, which the type states and cannot enforce: a provider's
+ * write MUST land through a door that participates in undo — either
+ * `host.document.mutate` (the document stack) or its active context's
+ * OWN op-log when that context owns undo (ADR-012 Tier 1: a context
+ * declaring `onUndo`/`onRedo` has Cmd-Z routed to it while active, and
+ * commit-exit re-lowers the net change as one atomic document step).
+ * Either way the user's Cmd-Z works. A provider that mutates outside
+ * both IS the side channel this contract exists to prevent; the
+ * contract cannot police a callback running in the plugin's realm, so
+ * this is stated as a requirement on the implementer, honestly.
+ */
+export type BindingWrite = {
+    kind: "applied";
+    outcome: MutationOutcome;
+} | BindingDecline;
+/** A provider's answer to a collection READ. `rows` MUST carry CORE's
+ *  row shape for that collection (`LayerSummary` for `"layers"`,
+ *  `SwatchSummary` for `"swatches"`, …) — that is the vocabulary rule
+ *  applied to collections, and it is what lets one host list render
+ *  provider rows and core rows with the same renderer. Extra fields are
+ *  ignored by the host; a field the provider's model has no counterpart
+ *  for carries the provider's honest default, and the honest way to
+ *  suppress a control it cannot serve is to leave that path OUT of
+ *  `provides.paths` (see {@link BindingProviderScope}). */
+export type BindingCollection = {
+    kind: "rows";
+    rows: readonly unknown[];
+} | BindingDecline;
+/** The op names a provider may intercept — core's own mutation
+ *  vocabulary, unchanged (`MutationInput` = the vendored `Mutation`
+ *  union plus the protocol-ahead ops). No new verbs enter here. */
+export type BindingOp = MutationInput["op"];
+/**
+ * WHAT a provider declares it serves. The declaration IS the gate: the
+ * registry never consults a provider about a path / collection / op it
+ * did not declare, so a provider cannot accidentally intercept the
+ * whole panel surface, and the host can read the declaration (through
+ * `activeProviders()`) to decide what a panel may offer at all.
+ *
+ * Every member is optional and every member is a CLOSED core union —
+ * see the vocabulary rule in this file's header.
+ */
+export interface BindingProviderScope {
+    /** Typed property paths this provider READS. (Also the write set unless
+     *  {@link BindingProviderScope.writablePaths} narrows it.) */
+    paths?: readonly PropertyPath[];
+    /**
+     * The subset of {@link BindingProviderScope.paths} this provider accepts
+     * WRITES for. OMITTED means "all of them" — the behaviour before this
+     * member existed, so no existing provider changes.
+     *
+     * WHY IT EXISTS, and why the first two proof consumers did not need it.
+     * The property-WRITE lane was the one lane no consumer had exercised:
+     * Layers writes STRUCTURALLY (`layerMove` / `layerSetVisible` through
+     * `applyMutation`) and Swatches likewise (`editSwatch`), and both of
+     * those are DECLARED in `ops` — so a host panel can ask
+     * "may this control work?" synchronously and DISABLE it, which is
+     * exactly what ADR-023's Swatches slice does. The property lane had no
+     * such declaration: `writeProperty` is an optional CALLBACK, and a
+     * callback's absence is not visible through `activeProviders()`.
+     *
+     * The consequence was a contradiction inside this very file. The op
+     * lane's rule is "an undeclared op must not reach core — the panel is
+     * showing somebody else's rows"; the path lane's rule (below, now
+     * corrected) said the opposite: that an absent `writeProperty` lets
+     * writes fall through to core. Fall-through there is the WRITE-side
+     * form of the `absent` lie — the panel is showing a sheet cell's font
+     * size and the commit lands on whatever core text the caret last
+     * touched.
+     *
+     * So a provider that can READ a path but not WRITE it says so HERE, the
+     * host reads the declaration, and the control renders read-only instead
+     * of being fake-interactive. Forced by paged.sheet as the
+     * Character/Paragraph provider: the sheet engine has no cell-style
+     * write API at all (all spreadsheet semantics live in Rust, and adding
+     * one is a Rust change), so it reads the whole surface and writes none
+     * of it — `writablePaths: []`.
+     */
+    writablePaths?: readonly PropertyPath[];
+    /** Named core collections whose ROWS this provider serves. */
+    collections?: readonly CollectionName[];
+    /** Mutation ops this provider takes first refusal on — the STRUCTURAL
+     *  edits a host panel would otherwise send straight to core
+     *  (`layerMove`, `createSwatch`, …). A `"batch"` declaration takes the
+     *  WHOLE batch: the registry never decomposes one to route children
+     *  separately (that would split one undo step across two authorities). */
+    ops?: readonly BindingOp[];
+}
+/**
+ * The resolver a bundle registers through
+ * `host.contribute.bindingProvider(contextType, provider)`.
+ *
+ * LIFETIME — the whole design rests on this: a provider is consulted
+ * ONLY while the edit context named at registration is ACTIVE. It
+ * borrows `contributeEditContext`'s activation rather than inventing a
+ * parallel notion of "who is active", because the shell's context stack
+ * ALREADY is that notion (it owns the stack, the breadcrumb, the
+ * tool/panel swap and the write-scope narrowing). Concretely the SDK
+ * adapter wraps the context's own `onEnter`/`onExit` hooks, so
+ * activation is derived from the shell's stack rather than reported
+ * alongside it and cannot drift from it.
+ *
+ * The consequence is deliberate and worth stating rather than
+ * discovering: a provider is never consulted while its context is
+ * inactive — INCLUDING for the document-scoped lanes. A plugin's colour
+ * vocabulary shows in the host Swatches panel while you are inside that
+ * plugin's frame and not after you leave it. That is the retargeting
+ * behaviour ADR-023 set out to copy (there is ONE Character panel and it
+ * retargets), applied consistently; a plugin that needs its resources
+ * visible document-wide keeps its own panel.
+ *
+ * Every lane is OPTIONAL. Declaring a lane in `provides` without
+ * implementing its callback is an authoring bug, not a stance, and the
+ * adapter refuses it loudly at registration.
+ */
+export interface BindingProvider {
+    /** What this provider answers for. See {@link BindingProviderScope}. */
+    provides: BindingProviderScope;
+    /** Read one typed path at one target. Required iff `provides.paths`
+     *  is non-empty. */
+    readProperty?(request: BindingPropertyRequest): BindingRead | Promise<BindingRead>;
+    /** Write one typed path at one target. OPTIONAL even with declared
+     *  paths — a read-only provider (a computed readout) is legitimate.
+     *
+     *  CORRECTED 2026-08-05 (the Character/Paragraph consumer). This used
+     *  to say its absence means "writes fall through to core, which is the
+     *  honest behaviour". It is not honest: a provider that CLAIMED the
+     *  read owns the target, and sending the commit to core writes
+     *  whatever core's selection happens to be — the write-side form of
+     *  the `absent` lie the whole seam exists to prevent. A read-only
+     *  provider now DECLARES itself with
+     *  {@link BindingProviderScope.writablePaths}, and the host renders
+     *  those controls read-only rather than routing their writes anywhere.
+     *  A claimed path whose write the registry refuses is DROPPED, never
+     *  re-aimed at core. */
+    writeProperty?(request: BindingPropertyWrite): BindingWrite | Promise<BindingWrite>;
+    /** Serve the rows of a declared collection. Required iff
+     *  `provides.collections` is non-empty. */
+    readCollection?(request: BindingCollectionRequest): BindingCollection | Promise<BindingCollection>;
+    /** Take first refusal on a declared structural op. Required iff
+     *  `provides.ops` is non-empty. */
+    applyMutation?(mutation: MutationInput): BindingWrite | Promise<BindingWrite>;
+}
+/**
+ * What `host.contribute.bindingProvider` returns. Disposing it removes
+ * the provider WITHOUT touching the edit context it borrowed activation
+ * from — which is what makes ADR-023 phase D a migration rather than a
+ * deletion: a duplicate panel retires behind the seam one at a time,
+ * and rolls back by disposing one handle.
+ */
+export interface BindingProviderHandle extends Disposable {
+    /**
+     * Announce that the values this provider serves have CHANGED, so host
+     * panels bound through it re-read.
+     *
+     * This exists because the host's usual refresh signal —
+     * `host.document.onDidChange` — fires on ENGINE mutations, and a
+     * provider's state frequently changes without one (a raster layer
+     * toggled inside plugin-image's own wasm layer graph moves no engine
+     * page). Without this the host panel goes quietly stale, which is the
+     * class of lie this platform refuses. Cheap and coarse by design:
+     * "re-read", not a per-path diff — panels are small and a diff
+     * protocol here would be a second damage-tracking system.
+     */
+    invalidate(): void;
+}
+/** The registry's answer to a property read. `resolved: false` ⇒ the
+ *  host reads core (`document.elementProperties` / its own panel path). */
+export type BindingReadResult = {
+    resolved: true;
+    provider: string;
+    read: BindingResolved;
+} | {
+    resolved: false;
+    reason: string;
+};
+/** The registry's answer to a write (property or structural).
+ *  `handled: false` ⇒ the host writes core (`document.mutate`). */
+export type BindingWriteResult = {
+    handled: true;
+    provider: string;
+    outcome: MutationOutcome;
+} | {
+    handled: false;
+    reason: string;
+};
+/** The registry's answer to a collection read. `resolved: false` ⇒ the
+ *  host reads core (`document.collection(name)`). */
+export type BindingCollectionResult = {
+    resolved: true;
+    provider: string;
+    rows: readonly unknown[];
+} | {
+    resolved: false;
+    reason: string;
+};
+/**
+ * One entry of the ACTIVE provider stack, as the host sees it —
+ * innermost (most recently entered) FIRST, which is the precedence
+ * order. A host panel reads this to decide what it may OFFER at all:
+ * a control whose path no active provider declares, over a row an
+ * active provider owns, is a control that cannot work.
+ */
+export interface ActiveBindingProvider {
+    /** The owning bundle's manifest id. */
+    plugin: string;
+    /** The edit-context type whose activation this provider borrows. */
+    contextType: string;
+    /** The element the context was entered on (the shell's scope root),
+     *  or `null` when the host reported none. */
+    elementId: string | null;
+    /** What it declares it serves. */
+    provides: BindingProviderScope;
+}

package/dist/contributions.d.ts

@@ -1 +1 @@
-export type { ShellRegistries, ToolRegistry, PanelRegistry, CommandRegistry, KeybindingRegistry, OverlayRegistry, EditContextRegistry, ObjectTypeRegistry, ImporterRegistry, ExporterRegistry, ToolContribution, ToolId, ToolGroupId, ToolSectionId, ToolOptionsSpec, ToolOptionField, CursorSpec, CssCursorToken, GestureHandler, CanvasPointerEvent, OverlayContext, OverlayPrimitive, DeactivateReason, PanelContribution, PanelProps, PanelApi, OverlayContribution, OverlayProps, OverlayPageRect, CommandContribution, KeybindingContribution, ImporterContribution, ImportRequest, ExporterContribution, ExportResult, DockEdge, VisibilityPredicate, PagedEditor, PagedClient, ImageResourceClaim, ResourceTilesNeeded, ToolPreviewShape, ToolPreviewPolyline, ToolPreviewPath, MarqueeRectPageLocal, } from "./editor";
+export type { ShellRegistries, ToolRegistry, PanelRegistry, CommandRegistry, KeybindingRegistry, OverlayRegistry, EditContextRegistry, ObjectTypeRegistry, ImporterRegistry, ExporterRegistry, ToolContribution, ToolId, ToolGroupId, ToolSectionId, ToolOptionsSpec, ToolOptionField, CursorSpec, CssCursorToken, GestureHandler, CanvasPointerEvent, OverlayContext, OverlayPrimitive, DeactivateReason, PanelContribution, PanelProps, PanelApi, OverlayContribution, OverlayProps, OverlayPageRect, CommandContribution, KeybindingContribution, ImporterContribution, ImportRequest, ExporterContribution, ExportResult, DockEdge, VisibilityPredicate, PagedEditor, PagedClient, ImageResourceClaim, ResourceTilesNeeded, ToolPreviewShape, ToolPreviewPolyline, ToolPreviewPath, ToolPreviewText, MarqueeRectPageLocal, } from "./editor";

package/dist/editor.d.ts

@@ -363,7 +363,43 @@ export interface ToolPreviewPath {
     /** Dashed stroke instead of the default solid (preview vocabulary). */
     dashed?: boolean;
 }
-export type ToolPreviewShape = MarqueeRectPageLocal | ToolPreviewPolyline | ToolPreviewPath;
+/**
+ * A text tool-preview (the overlay TEXT primitive). Closes the RFI
+ * gap "the overlay channel carries shapes only, no text primitive" —
+ * consumer: paged.draw's Measure tool readout (an on-canvas
+ * length/angle HUD was impossible with shapes alone); future
+ * consumers: the Dimension tool, crop HUDs, Ruler markers.
+ *
+ * `x`/`y` are the text anchor position in page-local pt — the SAME
+ * space every other preview variant uses. The host renders the label
+ * at a constant SCREEN size (like its page captions), so `size` is a
+ * screen-px font size (default host-chosen, ~11), not a document pt
+ * size that would scale with zoom. `anchor` is SVG `text-anchor`
+ * semantics relative to `x`. `background` opts into a small backing
+ * plate behind the label for legibility over page content.
+ *
+ * PLAIN TEXT ONLY — the host sanitizes (control characters stripped,
+ * no markup interpreted). Probe `supports("overlay.text@1")`.
+ */
+export interface ToolPreviewText {
+    /** Explicit discriminant — the first in this vocabulary (the older
+     *  variants discriminate structurally; new primitives get a `kind`). */
+    kind: "text";
+    pageId: PageId;
+    /** Text anchor x, page-local pt. */
+    x: number;
+    /** Text BASELINE y, page-local pt. */
+    y: number;
+    /** The label. Plain text; the host sanitizes + may truncate. */
+    text: string;
+    /** Font size in screen px (constant under zoom). Host default ~11. */
+    size?: number;
+    /** Horizontal anchoring relative to `x` (SVG text-anchor). Default "start". */
+    anchor?: "start" | "middle" | "end";
+    /** Render a small backing plate behind the label for legibility. */
+    background?: boolean;
+}
+export type ToolPreviewShape = MarqueeRectPageLocal | ToolPreviewPolyline | ToolPreviewPath | ToolPreviewText;
 export interface PagedClient {
     mutate(mutation: Mutation): Promise<WorkerToMain>;
     undo(): Promise<WorkerToMain>;
@@ -430,6 +466,15 @@ export interface PagedEditor {
     };
     overlaySignals: {
         setToolPreview(value: ToolPreviewShape | null): void;
+        /** K-9 — the MULTI-shape tool-preview sink. `undefined` when the host
+         *  build's overlay renderer predates the multi-shape channel (older
+         *  editor / a headless host that wires only the single slot); the
+         *  `host.overlay.setToolPreviews` door then degrades to the first
+         *  shape on `setToolPreview` and
+         *  `supports("overlay.multiPreview@1")` is false. Same slot as
+         *  `setToolPreview` — this REPLACES the slot's content with the
+         *  list; `null` clears it. */
+        setToolPreviews?(value: readonly ToolPreviewShape[] | null): void;
     };
     tool: {
         setBaseTool(id: ToolId): void;

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;

package/dist/panel-schema.d.ts

@@ -25,6 +25,71 @@ export interface BindingRef {
  *  (and a missing name reads as `false` — a visible seam, never a
  *  throw). */
 export type SchemaGate = boolean | BindingRef;
+/** Where a `list` row's items come from. Two sources, mirroring the
+ *  two live-collection lanes the host already has:
+ *    · `documentCollection` — a named engine collection (the same
+ *      `host.document.collection(name)` lane the editor's own panels
+ *      read);
+ *    · `binding` — an ARRAY the plugin publishes through
+ *      `host.bindings.publish(name, rows)` (the §12.2 published-
+ *      bindings door, now carrying rows instead of a boolean). */
+export type WidgetCollectionBinding = {
+    kind: "documentCollection";
+    collection: string;
+} | {
+    kind: "binding";
+    bind: string;
+};
+/** G3 — a schema row ACTION. Either dispatches a registered command
+ *  with the row id as payload, or the `applyEntity` write kind: apply
+ *  the row's entity id (style / swatch self-id) to the current
+ *  selection through the SAME `setElementProperty` mutation channel the
+ *  scalar widgets commit on. `valueType` picks the wire payload
+ *  (`text` for applied-style paths, `colorRef` for swatch/gradient
+ *  paths) — the collection-select leaf's convention. Note the ceiling
+ *  holds: an action writes ONE typed PropertyPath, it does not compute. */
+export type SchemaRowAction = {
+    kind: "command";
+    command: string;
+} | {
+    kind: "applyEntity";
+    /** Selection surface to write to (defaults to `"element"`). */
+    scope?: "element" | "content";
+    /** The applied-entity PropertyPath (e.g. `frameFillColor`,
+     *  `appliedParagraphStyle`). */
+    path: PropertyPath;
+    /** Wire payload variant; defaults to `"text"`. */
+    valueType?: "text" | "colorRef";
+};
+/** One per-row action button on a `list` widget. */
+export interface SchemaListAction {
+    /** Button label (sentence case, no emoji — brand content rules). */
+    label: string;
+    action: SchemaRowAction;
+    /** Gate the button on a published binding (absent = enabled;
+     *  `applyEntity` actions additionally disable while the target
+     *  selection is empty — the honest no-write-path rule). */
+    enabled?: SchemaGate;
+}
+/** The `list` widget spec (widget id `paged.list`). Renders rows from a
+ *  collection binding; publishes the clicked row's id back through
+ *  `selectionBinding` so other rows/sections can gate on it — which is
+ *  how a list participates in §12.2 without a DSL. */
+export interface SchemaListSpec {
+    items: WidgetCollectionBinding;
+    /** Dot-path into a row object for the primary label ("name"). */
+    labelField: string;
+    /** Optional secondary line (mono), e.g. "kind". */
+    secondaryField?: string;
+    /** Dot-path carrying the row's stable id; defaults to "selfId" (the
+     *  summary-shape convention every document collection uses). */
+    idField?: string;
+    /** Published binding name that receives the selected row id on click
+     *  (string). Absent = the list keeps private selection. */
+    selectionBinding?: string;
+    /** Per-row action buttons. */
+    actions?: SchemaListAction[];
+}
 export interface PanelSchemaRow {
     /** Catalog widget id (a curated primitive-leaf id the host
      *  registered). An unknown id renders a visible "unknown widget"
@@ -38,6 +103,9 @@ export interface PanelSchemaRow {
      *  (`literal | selectionProperty`). Absent = a layout-only / display
      *  leaf (label, section). */
     value?: WidgetValueBinding;
+    /** ADDITIVE (schema v1.1) — present iff `widget` is the list widget
+     *  (`paged.list`). Scalar rows ignore it; a v1 schema never sets it. */
+    list?: SchemaListSpec;
     /** Show the row only when this gate is truthy. Absent = always. */
     visible?: SchemaGate;
     /** Enable the row's control only when this gate is truthy. Absent =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-api",
-  "version": "0.2.27-canary.1",
+  "version": "0.2.28-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",