@paged-media/plugin-api 0.2.53-canary.0 → 0.2.55-canary.0

package/dist/assets.d.ts

@@ -1,4 +1,5 @@
 import type { Disposable } from "./host";
+import type { PageId } from "./wire";
 /** What `host.assets` can serve. `"fonts"` gates `getFontFace` (W-06);
  *  `"images"` gates `getPlacedImage` (C-5 / I-04 — OPEN since core v42:
  *  the engine serves a placed image's original bytes, so `validate`
@@ -46,6 +47,27 @@ export interface PlacedImageAsset {
     /** Natural pixel height of the placed image. */
     height: number;
 }
+/**
+ * What {@link AssetSurface.registerDocumentFont} did. Never a throw (the
+ * undeclared-`fonts` gate aside, as on every asset door):
+ *
+ * - `registered` — the document holds the face now; `pageIds` are the pages
+ *   the engine laid out again because text there resolves to it;
+ * - `held` — the document already held a face for the family (and style),
+ *   so nothing was sent: the door fills a gap, it never replaces a face;
+ * - `refused` — nothing was registered; `reason` says why (the
+ *   `document.write` gate, the per-face budget, bytes the canvas cannot
+ *   draw, the engine's own refusal or a dead channel).
+ */
+export type DocumentFontOutcome = {
+    status: "registered";
+    pageIds: PageId[];
+} | {
+    status: "held";
+} | {
+    status: "refused";
+    reason: string;
+};
 /**
  * The asset accessor a bundle reaches through `host.assets`. Two reads:
  * DOCUMENT-registered font face bytes by family (+ optional style), and
@@ -54,9 +76,10 @@ export interface PlacedImageAsset {
  * the document already holds, and the host answers from that or
  * `null`. Capability-gated per kind: `getFontFace` requires
  * `capabilities.assets` ∋ `"fonts"`, `getPlacedImage` ∋ `"images"`
- * (the host gate throws in `'enforce'`, warns in `'warn'`). One write
- * sits beside the reads — `registerFont`, scene-layer faces only (W-15);
- * it adds nothing the document can see.
+ * (the host gate throws in `'enforce'`, warns in `'warn'`). Two writes
+ * sit beside the reads — `registerFont`, scene-layer faces only (W-15),
+ * which adds nothing the document can see, and `registerDocumentFont`,
+ * a face for the document where it has none (ADR 328).
  */
 export interface AssetSurface {
     /**
@@ -93,4 +116,33 @@ export interface AssetSurface {
      * inert `Disposable` — scene text keeps its fallback face.
      */
     registerFont(bytes: Uint8Array, family: string, style?: string): Promise<Disposable>;
+    /**
+     * ADR 328 — give the DOCUMENT a face for `family` (+ `style`) when it
+     * holds none: the engine's document registry takes the bytes
+     * (`registerFont` with `scope: "document"`), the text that names the
+     * family is laid out and drawn in them, and the Fonts collection no
+     * longer flags the family missing. For a bundle that writes NATIVE text
+     * in a face the document lacks — paged.web's bake names the face each
+     * run was shaped in — so the text it wrote is drawn as it was shaped.
+     *
+     * It fills a gap and never replaces: when the document already holds a
+     * face for the family in that style (any face of the family when
+     * `style` is omitted), nothing is sent and the outcome is `held`. So a
+     * bundle cannot change how text that already resolves is drawn.
+     *
+     * The face is not undoable and is not written into a saved file (a
+     * document names its fonts; it carries no face bytes): the engine keeps
+     * it for the session, for every document opened after too. A bundle
+     * whose text needs it in a later session provides it again (at
+     * `document.onDidOpen`, or when it writes the text).
+     *
+     * Gates: `capabilities.assets` ∋ `"fonts"` (throws in 'enforce', as on
+     * every asset door) and `capabilities.document.write` (it changes how
+     * the document lays out; refused in 'enforce'). Refused, too: a face
+     * over `ASSET_BUDGETS.maxFontFaceBytes`, bytes that are not a TrueType
+     * or OpenType face (WOFF and WOFF2 included — the canvas reads neither),
+     * an empty family. Never throws otherwise. Calls for one face at the
+     * same time register it once. Probe `supports("assets.documentFont@1")`.
+     */
+    registerDocumentFont(bytes: Uint8Array, family: string, style?: string): Promise<DocumentFontOutcome>;
 }

package/dist/host.d.ts

@@ -794,14 +794,37 @@ export interface WillSaveEvent {
     /** The container being written. */
     format: "paged";
 }
+/**
+ * One committed change to the document's content — one step in its history.
+ * `kind` names what committed it (the engine's own reply kind):
+ *
+ * - `mutationApplied` — a `mutate`: a bundle's write, a panel field, a command;
+ * - `undoApplied` / `redoApplied` — an undo or a redo;
+ * - `gestureCommitted` — a canvas gesture (a frame dragged, resized or
+ *   rotated by its handles) committed on the engine (0.2.55);
+ * - `scriptResult` — a `paged.*` script finished (0.2.55). The engine names
+ *   neither its pages nor whether it wrote, so `pageIds` is empty and
+ *   `pagesUnknown` is set: treat every page as changed.
+ *
+ * A host from before 0.2.55 reports the first three only; probe
+ * `supports("document.onDidChange@2")` for the full set.
+ */
 export interface DocumentChangeEvent {
-    kind: "mutationApplied" | "undoApplied" | "redoApplied";
+    kind: "mutationApplied" | "undoApplied" | "redoApplied" | "gestureCommitted" | "scriptResult";
+    /** The pages whose content the change touched (empty: none, unless
+     *  `pagesUnknown`). */
     pageIds: PageId[];
+    /** Set when the host cannot say which pages changed (a script run):
+     *  `pageIds` is then empty and any page may have changed. */
+    pagesUnknown?: true;
     /** Content-box reflow (protocol v38, C-2/S-05): present ONLY when the
      *  change RESIZED a frame's content box (a `resizeFrame`) — never on a
      *  pure transform (move/scale/rotate is display-only, §8.5). A
      *  pagination consumer re-splits on this and ignores transform-only
-     *  changes (where it is absent). */
+     *  changes (where it is absent). The engine reports it for a
+     *  `resizeFrame` mutation only: a `gestureCommitted` never carries it,
+     *  even for a resize by the handles, so a consumer that follows frame
+     *  sizes re-reads geometry on a gesture commit. */
     reflow?: {
         frameId: string;
         contentBox: [number, number, number, number];
@@ -1081,6 +1104,15 @@ export interface DocumentSurface {
      *  `supports("document.readStory@1")`; a host without the v54 read backend
      *  throws `PluginApiNotImplemented` (a visible seam, never a fake value). */
     storyContent(storyId: string): Promise<StoryContent | null>;
+    /**
+     * Every committed change to the document, whatever committed it: a
+     * mutation, an undo or redo, a canvas gesture's commit, a script run
+     * (see {@link DocumentChangeEvent} for the kinds). A gesture still in
+     * flight, a cancelled one and a script suspended on the host's objects
+     * are not changes. Gated on `capabilities.document.read`. Probe
+     * `supports("document.onDidChange@2")`: a host without it reports
+     * mutations, undos and redos only.
+     */
     onDidChange(listener: (e: DocumentChangeEvent) => void): Disposable;
     /**
      * W-22 — a document became the active one: opened from a file, created
@@ -1178,6 +1210,8 @@ export interface BakeContext {
 }
 export interface SelectionSurface {
     get(): ElementId[];
+    /** Select as a click does: the host's selection AND the selection box
+     *  drawn around it follow. Resolves the ids the engine applied. */
     set(ids: ElementId[], mode?: SelectionMode): Promise<ElementId[]>;
     onDidChange(listener: (ids: ElementId[]) => void): Disposable;
 }

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type { BundleHost, ContributionSurface, SceneLayerSurface, SceneLayerSubm
 export type { PanelSchema, PanelSchemaSection, PanelSchemaRow, SchemaPanelContribution, SchemaPanelRenderer, SchemaPanelRendererProps, WidgetValueBinding, BindingRef, SchemaGate, WidgetCollectionBinding, SchemaRowAction, SchemaListAction, SchemaListSpec, PanelSchemaWidgetRow, PanelSchemaPropertyRow, PropertyFieldAddress, PropertyFieldStyle, PropertyFieldOption, PropertySubField, PropertyListPresentation, } from "./panel-schema";
 export type { WidgetSurface, ColorPickerProps, CodeEditorProps, CodeEditorDiagnostic, CodeEditorLanguage, PropertyFieldProps, PropertyFrameProps, PropertyFieldTarget, } from "./widgets";
 export type { BindingTarget, BindingPropertyRequest, BindingPropertyWrite, BindingCollectionRequest, BindingRead, BindingResolved, BindingDecline, BindingWrite, BindingCollection, BindingOp, BindingProvider, BindingProviderScope, BindingProviderHandle, BindingReadResult, BindingWriteResult, BindingCollectionResult, ActiveBindingProvider, } from "./binding-provider";
-export type { AssetSurface, AssetKind, FontFaceAsset, FontFaceFormat, } from "./assets";
+export type { AssetSurface, AssetKind, DocumentFontOutcome, FontFaceAsset, FontFaceFormat, } from "./assets";
 export type { ProviderTileWire, SnapshotPng } from "./wire";
 export type { SnapPointQuery, SnapPointResult, SnapPointHit, SnapAxisHit, SnapSegmentHit, SnapExclude, SnapSource, SnapSettings, } from "./wire";
 export type { MintedElement } from "./wire";

package/package.json

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