@paged-media/plugin-api 0.2.27-canary.1 → 0.2.29-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;