@embedpdf/plugin-render 3.0.0-next.13 → 3.0.0-next.15

package/dist/host-contract-CTOQn0Xz.d.cts

@@ -0,0 +1,127 @@
+import { _ as PageViewDemand, i as PageLayerOptions, r as PageImage, s as RenderCapability, v as TilePaintPlan } from "./contract-uc5nOice.cjs";
+import { AnnotationAppearanceImage, AnnotationRef, EventHook, OperationOptions, PageLayerRights, PageRef, PageRenderViewport, PluginErrorInfo } from "@embedpdf/core";
+//#region src/host-contract.d.ts
+/** Layer-facing paint settings (resolved config the view layers need). Reference-stable. */
+interface PaintSettings {
+  /** Whether the tile plane is enabled at all (`tiles: false` opts out). */
+  readonly tiles: boolean;
+}
+interface RenderSourceOptions extends PageLayerOptions {
+  /** Device px per PDF point (the page transform's `renderScale`). */
+  scale: number;
+  /**
+   * The view the picture is for (the page context's `view`): the engine ranks
+   * the render by where the page is in that view (`doc.with({ view })`).
+   */
+  view?: string;
+}
+/**
+ * One view's tile surface. Identity (the view) is bound at creation; every
+ * call addresses that view's own state for the given page, so two views
+ * showing the same page plan independently — a thumbnail rail's
+ * never-engaging demand cannot disturb the main view's tiles.
+ *
+ * Reads are pure: `setDemand` is the one call that schedules fetches and
+ * re-plans; `getPlan` returns the paint plan that demand produced (memoized: the
+ * same object until the demand, an epoch, or a tile arrival changes it, so
+ * layers subscribe with plain `Object.is`). Handles are reference-stable per
+ * view id and reference-counted: every `createViewDemand` pairs with one
+ * `dispose`.
+ */
+interface ViewDemand {
+  /** What this view wants for a page right now. Idempotent; schedules the want set. */
+  setDemand(page: PageRef, demand: PageViewDemand, options?: PageLayerOptions): void;
+  /** The current paint plan for a page under this view's demand. Pure. */
+  getPlan(page: PageRef): TilePaintPlan;
+  /** The image for this plan key had a presentation opportunity. */
+  markPainted(page: PageRef, key: string): void;
+  /** The inverse report: this plan key's element left the DOM. */
+  markUnpainted(page: PageRef, key: string): void;
+  /** This view unmounted its tile plane for the page: abort in-flight tile
+   *  fetches, drop its own bookkeeping (resolved bytes stay cached). */
+  release(page: PageRef): void;
+  /** Release every page of this view and drop the handle's reference. */
+  dispose(): void;
+}
+/** Whose pictures: a page's annotations, or its form widgets. */
+type AppearanceFamily = 'annotations' | 'widgets';
+/** One of an owner's items on a page, at the version of its picture. */
+interface AppearanceItem {
+  readonly ref: AnnotationRef;
+  /** Moves when the engine draws the item again (`pictureVersion`): its pictures are fetched again. */
+  readonly version: number;
+}
+/** What {@link RenderHostCapability.renderAppearances} takes. */
+interface AppearancesOptions extends OperationOptions {
+  readonly family: AppearanceFamily;
+  /** Device px per PDF point, conformed through {@link RenderHostCapability.getAppearanceScale}. */
+  readonly scale: number;
+  /** The owner's items on the page whose pictures it wants, each at its version. */
+  readonly items: readonly AppearanceItem[];
+}
+/** The engine's picture of an item in one of its states, and the version of the item it shows. */
+interface AppearancePicture extends AnnotationAppearanceImage {
+  readonly version: number;
+}
+interface RenderCompletedEvent {
+  readonly page: PageRef;
+  readonly key: string;
+}
+interface RenderFailedEvent {
+  readonly page: PageRef;
+  readonly key: string;
+  readonly error: PluginErrorInfo;
+}
+interface RenderHostCapability extends RenderCapability {
+  /**
+   * The viewer door: render a page at the scale a view shows it, conformed
+   * through the resolved render points (strategy ∧ policy): the exact
+   * demand capped at the pixel budget under `continuous`, the advertised
+   * ladder under a lattice — with same-key asks collapsing in the raster
+   * store. Layers key their fetch on {@link getSourceKey}.
+   */
+  renderSource(page: PageRef, options: RenderSourceOptions & OperationOptions): Promise<PageImage>;
+  /**
+   * The identity of the raster `renderSource` would produce — conformed
+   * width + the parts it draws + epoch (+ format), as one stable string.
+   * Under a lattice it moves only at rung crossings; under exact-mode
+   * `continuous` it tracks the demand and is constant above the budget.
+   */
+  getSourceKey(page: PageRef, options: RenderSourceOptions): string;
+  /** The canonical viewport a desired scale conforms to for this page (always width-kind). */
+  conformViewport(page: PageRef, scale: number): PageRenderViewport;
+  getPaintSettings(): PaintSettings;
+  /**
+   * What the user may read of the parts a picture draws beside the page
+   * content, so a view that leaves one part to a layer of its own can still
+   * ask for the other. The same object until a right changes.
+   */
+  getLayerRights(): PageLayerRights;
+  /** This view's tile surface. Stable per view id; pair with `dispose`. */
+  createViewDemand(viewId: string): ViewDemand;
+  /**
+   * The engine's pictures of the owner's items on a page (`family`): each
+   * item's look at rest, in every state it stores, each labelled with its
+   * state and tagged with the item's version, so a checkbox switches picture
+   * with no request, and a layer can tell a picture older than its item.
+   * The owner keys the ask on its items' versions: asks for the same page,
+   * family, scale and items share one fetch, and the last few sets of each
+   * page are kept. Rejects `permission-denied` without `doc.annotate.read`
+   * (annotations) or `doc.forms.read` (widgets).
+   */
+  renderAppearances(page: PageRef, options: AppearancesOptions): Promise<readonly AppearancePicture[]>;
+  /**
+   * An item's last pictures, every state, kept a while after it left its page:
+   * an undo that brings it back shows them at once. Empty for one never drawn.
+   */
+  keptAppearances(family: AppearanceFamily, item: AnnotationRef): readonly AppearancePicture[];
+  /** The appearance scale a render scale conforms to under the deployment's policy. */
+  getAppearanceScale(renderScale: number): number;
+  /** A base raster resolved / failed (the conforming and exact doors alike). */
+  readonly onRenderCompleted: EventHook<RenderCompletedEvent>;
+  readonly onRenderFailed: EventHook<RenderFailedEvent>;
+}
+declare const RenderToken: import("@embedpdf/core").CapabilityToken<RenderHostCapability>;
+//#endregion
+export { PaintSettings as a, RenderHostCapability as c, ViewDemand as d, AppearancesOptions as i, RenderSourceOptions as l, AppearanceItem as n, RenderCompletedEvent as o, AppearancePicture as r, RenderFailedEvent as s, AppearanceFamily as t, RenderToken as u };
+//# sourceMappingURL=host-contract-CTOQn0Xz.d.cts.map

package/dist/host-contract-CsjZjWjb.d.ts

@@ -0,0 +1,127 @@
+import { _ as PageViewDemand, i as PageLayerOptions, r as PageImage, s as RenderCapability, v as TilePaintPlan } from "./contract-uc5nOice.js";
+import { AnnotationAppearanceImage, AnnotationRef, EventHook, OperationOptions, PageLayerRights, PageRef, PageRenderViewport, PluginErrorInfo } from "@embedpdf/core";
+//#region src/host-contract.d.ts
+/** Layer-facing paint settings (resolved config the view layers need). Reference-stable. */
+interface PaintSettings {
+  /** Whether the tile plane is enabled at all (`tiles: false` opts out). */
+  readonly tiles: boolean;
+}
+interface RenderSourceOptions extends PageLayerOptions {
+  /** Device px per PDF point (the page transform's `renderScale`). */
+  scale: number;
+  /**
+   * The view the picture is for (the page context's `view`): the engine ranks
+   * the render by where the page is in that view (`doc.with({ view })`).
+   */
+  view?: string;
+}
+/**
+ * One view's tile surface. Identity (the view) is bound at creation; every
+ * call addresses that view's own state for the given page, so two views
+ * showing the same page plan independently — a thumbnail rail's
+ * never-engaging demand cannot disturb the main view's tiles.
+ *
+ * Reads are pure: `setDemand` is the one call that schedules fetches and
+ * re-plans; `getPlan` returns the paint plan that demand produced (memoized: the
+ * same object until the demand, an epoch, or a tile arrival changes it, so
+ * layers subscribe with plain `Object.is`). Handles are reference-stable per
+ * view id and reference-counted: every `createViewDemand` pairs with one
+ * `dispose`.
+ */
+interface ViewDemand {
+  /** What this view wants for a page right now. Idempotent; schedules the want set. */
+  setDemand(page: PageRef, demand: PageViewDemand, options?: PageLayerOptions): void;
+  /** The current paint plan for a page under this view's demand. Pure. */
+  getPlan(page: PageRef): TilePaintPlan;
+  /** The image for this plan key had a presentation opportunity. */
+  markPainted(page: PageRef, key: string): void;
+  /** The inverse report: this plan key's element left the DOM. */
+  markUnpainted(page: PageRef, key: string): void;
+  /** This view unmounted its tile plane for the page: abort in-flight tile
+   *  fetches, drop its own bookkeeping (resolved bytes stay cached). */
+  release(page: PageRef): void;
+  /** Release every page of this view and drop the handle's reference. */
+  dispose(): void;
+}
+/** Whose pictures: a page's annotations, or its form widgets. */
+type AppearanceFamily = 'annotations' | 'widgets';
+/** One of an owner's items on a page, at the version of its picture. */
+interface AppearanceItem {
+  readonly ref: AnnotationRef;
+  /** Moves when the engine draws the item again (`pictureVersion`): its pictures are fetched again. */
+  readonly version: number;
+}
+/** What {@link RenderHostCapability.renderAppearances} takes. */
+interface AppearancesOptions extends OperationOptions {
+  readonly family: AppearanceFamily;
+  /** Device px per PDF point, conformed through {@link RenderHostCapability.getAppearanceScale}. */
+  readonly scale: number;
+  /** The owner's items on the page whose pictures it wants, each at its version. */
+  readonly items: readonly AppearanceItem[];
+}
+/** The engine's picture of an item in one of its states, and the version of the item it shows. */
+interface AppearancePicture extends AnnotationAppearanceImage {
+  readonly version: number;
+}
+interface RenderCompletedEvent {
+  readonly page: PageRef;
+  readonly key: string;
+}
+interface RenderFailedEvent {
+  readonly page: PageRef;
+  readonly key: string;
+  readonly error: PluginErrorInfo;
+}
+interface RenderHostCapability extends RenderCapability {
+  /**
+   * The viewer door: render a page at the scale a view shows it, conformed
+   * through the resolved render points (strategy ∧ policy): the exact
+   * demand capped at the pixel budget under `continuous`, the advertised
+   * ladder under a lattice — with same-key asks collapsing in the raster
+   * store. Layers key their fetch on {@link getSourceKey}.
+   */
+  renderSource(page: PageRef, options: RenderSourceOptions & OperationOptions): Promise<PageImage>;
+  /**
+   * The identity of the raster `renderSource` would produce — conformed
+   * width + the parts it draws + epoch (+ format), as one stable string.
+   * Under a lattice it moves only at rung crossings; under exact-mode
+   * `continuous` it tracks the demand and is constant above the budget.
+   */
+  getSourceKey(page: PageRef, options: RenderSourceOptions): string;
+  /** The canonical viewport a desired scale conforms to for this page (always width-kind). */
+  conformViewport(page: PageRef, scale: number): PageRenderViewport;
+  getPaintSettings(): PaintSettings;
+  /**
+   * What the user may read of the parts a picture draws beside the page
+   * content, so a view that leaves one part to a layer of its own can still
+   * ask for the other. The same object until a right changes.
+   */
+  getLayerRights(): PageLayerRights;
+  /** This view's tile surface. Stable per view id; pair with `dispose`. */
+  createViewDemand(viewId: string): ViewDemand;
+  /**
+   * The engine's pictures of the owner's items on a page (`family`): each
+   * item's look at rest, in every state it stores, each labelled with its
+   * state and tagged with the item's version, so a checkbox switches picture
+   * with no request, and a layer can tell a picture older than its item.
+   * The owner keys the ask on its items' versions: asks for the same page,
+   * family, scale and items share one fetch, and the last few sets of each
+   * page are kept. Rejects `permission-denied` without `doc.annotate.read`
+   * (annotations) or `doc.forms.read` (widgets).
+   */
+  renderAppearances(page: PageRef, options: AppearancesOptions): Promise<readonly AppearancePicture[]>;
+  /**
+   * An item's last pictures, every state, kept a while after it left its page:
+   * an undo that brings it back shows them at once. Empty for one never drawn.
+   */
+  keptAppearances(family: AppearanceFamily, item: AnnotationRef): readonly AppearancePicture[];
+  /** The appearance scale a render scale conforms to under the deployment's policy. */
+  getAppearanceScale(renderScale: number): number;
+  /** A base raster resolved / failed (the conforming and exact doors alike). */
+  readonly onRenderCompleted: EventHook<RenderCompletedEvent>;
+  readonly onRenderFailed: EventHook<RenderFailedEvent>;
+}
+declare const RenderToken: import("@embedpdf/core").CapabilityToken<RenderHostCapability>;
+//#endregion
+export { PaintSettings as a, RenderHostCapability as c, ViewDemand as d, AppearancesOptions as i, RenderSourceOptions as l, AppearanceItem as n, RenderCompletedEvent as o, AppearancePicture as r, RenderFailedEvent as s, AppearanceFamily as t, RenderToken as u };
+//# sourceMappingURL=host-contract-CsjZjWjb.d.ts.map