@embedpdf/plugin-render 3.0.0-next.1 → 3.0.0-next.11

package/dist/index.d.ts

@@ -1,220 +1,4 @@
-import { EngineRenderPolicy, PageImageHandle, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
-import { Rect } from "@embedpdf/core-geometry";
-//#region src/paint-plan.d.ts
-/**
- * The demand a page HOST supplies through dependency inversion:
- * plugin-render defines the shape, producers fill it. The Stage's page
- * host knows the camera and supplies `visibleRect`/`velocity`; a
- * stage-less `<PageView>` supplies neither — absent `visibleRect` means
- * "assume the whole page is visible", which a thumbnail-sized demand
- * turns into "no tiles engage" by arithmetic, not configuration.
- */
-interface PageViewDemand {
-  /** Desired device pixels across the page's unrotated content width. */
-  desiredDeviceWidth: number;
-  /** Visible page region — y-down page points. ABSENT = whole page. */
-  visibleRect?: Rect;
-  /** Scroll velocity in page points/s — prefetch direction bias only. */
-  velocity?: {
-    dx: number;
-    dy: number;
-  };
-}
-/**
- * One tile the layer should have in the DOM. `key` is the reconciliation
- * identity (stable across plan recomputes — keyed lists preserve the DOM
- * node, which IS the retention mechanism); `rect` is y-down page points
- * inside the unrotated content box; `z` stacks by resolution so arriving
- * sharper tiles occlude retained coarser ones per region.
- */
-interface TilePaintSource {
-  key: string;
-  scale: number;
-  rect: Rect;
-  z: number;
-  handle: PageImageHandle;
-}
-/**
- * What a TileLayer paints right now. `paint` draws ONLY from resolved
- * rasters — retained generations live here until the release rules fire;
- * "loading" never reaches the DOM. `fetching` is diagnostic (badge/tests).
- */
-interface TilePaintPlan {
-  /** Tiles engaged at all? False = the base rung fully covers demand. */
-  engaged: boolean;
-  paint: TilePaintSource[];
-  /** Keys currently in flight (want-set members not yet resolved). */
-  fetching: string[];
-  /** Memoization stamp — a new object appears only when this changes. */
-  stamp: string;
-}
-/** Resolved tiling configuration (renderPlugin options + defaults). */
-interface TilingConfig {
-  /** Tile edge in device px. Default 512. */
-  tileSize?: number;
-  /**
-   * Client pyramid used while the policy doesn't advertise `tiles`.
-   * Default `[1, 2, 4, 8, 16, 32]` — ×2 aligned.
-   */
-  scales?: readonly number[];
-  /**
-   * Sharpness deficit (desired ÷ supplied-by-base) above which tiles
-   * engage. Default 1.25 — small CSS upscales read fine; past that the
-   * ladder cap is visible and the pyramid takes over.
-   */
-  engageAt?: number;
-  /** Prefetch ring around the visible rect. */
-  prefetch?: {
-    /** Extra coverage per side, in fractions of the visible rect. Default 0.5. */
-    margin?: number;
-    /** Stretch the ring toward scroll direction. Default true. */
-    velocityBias?: boolean;
-  };
-  /**
-   * Hysteresis for LEVEL changes (a zoom settling between pyramid rungs):
-   * tile fetches for a NEW level wait this long; pan-driven fetches at the
-   * current level fire immediately. Default 150ms; 0 disables.
-   */
-  settleMs?: number;
-}
-//#endregion
-//#region src/types.d.ts
-/** Options for `renderPlugin()`. Tiling is capability + economics here;
- *  WHICH view tiles is composition (mount a TileLayer per lens), and
- *  WHETHER it engages is demand arithmetic — three levels, three owners. */
-interface RenderPluginOptions {
-  tiling?: TilingConfig;
-}
-interface RenderPageOptions {
-  /** Device px per PDF point (use the page transform's `renderScale`). */
-  scale: number;
-  /**
-   * Bake annotations into the page bitmap. Default true. Pass false when an
-   * <AnnotationLayer> owns annotation rendering, so they aren't painted twice
-   * (once baked, once by the overlay).
-   */
-  includeAnnotations?: boolean;
-  /** Abort the render (camera moved / layer unmounted). */
-  signal?: AbortSignal;
-}
-/**
- * The two invalidation scopes — every pixel-changing fact is one of them:
- *
- *   'annotations' — only baked APPEARANCES changed (an annotation mutated, a
- *                   form widget re-baked). Base renders keep their pixels.
- *   'content'     — the PAGE ITSELF changed (redaction applied, text edited).
- *                   Invalidates everything: no mutation can change base pixels
- *                   yet leave an annotated raster valid, so content strictly
- *                   contains annotations.
- */
-type InvalidateScope = 'content' | 'annotations';
-/**
- * Per-page versions of the two raster products a page has — base
- * (`includeAnnotations: false`) and annotated. Fed by the document event
- * stream (see effects.ts) and by the `invalidate` verb: a confirmed
- * pixel-changing fact — own or remote — bumps the touched pages, and anything
- * holding a rendered bitmap (a thumbnail rail) refetches.
- */
-interface RenderState {
-  /** Base-raster versions — bumped by CONTENT facts (redaction, text edit). */
-  readonly contentEpochs: Readonly<Record<PageObjectNumber, number>>;
-  /** Appearance versions — bumped by ANNOTATION facts (annotations, form widgets). */
-  readonly annotatedEpochs: Readonly<Record<PageObjectNumber, number>>;
-  /**
-   * Tile paint-plan wake-ups. The tile manager's state (fetch/painted/
-   * retention) lives OUTSIDE the store — it holds live handles and abort
-   * controllers — so resolutions bump this counter to make subscribed
-   * layers recompute `tilePlan`. The value itself carries no meaning.
-   */
-  readonly paintVersions: Readonly<Record<PageObjectNumber, number>>;
-}
-type RenderAction = {
-  type: 'INVALIDATE';
-  scope: InvalidateScope;
-  pons: readonly PageObjectNumber[];
-} | {
-  type: 'PAINT_ADVANCED';
-  pon: PageObjectNumber;
-};
-interface RenderCapability {
-  /**
-   * Render a page (by its durable pon) to an ENCODED image. Abortable. Encoded
-   * output is identical for local & cloud and cheap over the wire (vs. raw RGBA).
-   *
-   * CONFORMS to the deployment policy's three-layer rule:
-   * under a lattice the desired `scale` converts to the canonical ladder width
-   * via `snapFullPageViewport`; under `continuous` it passes through exactly.
-   * Same-key requests collapse in the plugin's raster store (singleflight +
-   * LRU), so repeated asks inside one rung cost one engine call.
-   */
-  renderPage(pon: PageObjectNumber, options: RenderPageOptions): Promise<PageImageHandle>;
-  /**
-   * The identity of the raster `renderPage` would produce for these options —
-   * canonical viewport + annotations flag + epoch, as one stable string.
-   * Layers key their fetch effect on THIS instead of the raw scale: inside a
-   * rung the key never changes (zoom 1.2→1.5 under a [1,2]-ish lattice is a
-   * no-op — no refetch, no DOM churn); it changes exactly at rung crossings
-   * and epoch bumps. Always available: the kernel materializes the policy on
-   * `DocumentMeta` before the document publishes.
-   */
-  renderSourceKey(pon: PageObjectNumber, options: {
-    scale: number;
-    includeAnnotations?: boolean;
-  }): string;
-  /**
-   * The canonical viewport a desired scale conforms to for this page —
-   * width-kind on a lattice, the exact scale under `continuous`.
-   */
-  conformViewport(pon: PageObjectNumber, scale: number): PageRenderViewport;
-  /** The document's advertised policy (sugar over `DocumentMeta.renderPolicy`). */
-  renderPolicy(): EngineRenderPolicy;
-  /**
-   * The tile paint plan for a page under a host-supplied demand. Tiling is a
-   * STRATEGY inside this plugin, not a sibling.
-   * Memoized: the same object returns until the demand, an epoch, or a
-   * tile resolution actually changes it, so layers can subscribe with
-   * plain `Object.is`. Calling it schedules the want-set fetches (visible
-   * first, prefetch ring after) — idempotent, store-deduped. Engagement
-   * is pure arithmetic: it fires only when the policy's ladder caps the
-   * base below the demand; a thumbnail-sized demand never engages.
-   */
-  tilePlan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
-    includeAnnotations?: boolean;
-  }): TilePaintPlan;
-  /**
-   * The painter's decode-boundary report: the `<img>` for this plan key
-   * actually painted (onload). Retained coarser generations covered by
-   * painted want-set tiles release on this signal — never on fetch
-   * completion, which would flash during decode.
-   */
-  tilePainted(pon: PageObjectNumber, key: string): void;
-  /** A lens unmounted its TileLayer: abort in-flight tile fetches and drop
-   *  the page's tile bookkeeping (resolved bytes stay cached). */
-  releaseTiles(pon: PageObjectNumber): void;
-  /**
-   * Version of the raster the given options would produce. Key a long-lived
-   * render on it: when it bumps, refetch. Base renders version on content
-   * facts; annotated renders on content AND annotation facts. Bumps only on
-   * CONFIRMED mutations — never optimistically — so a drag invalidates once,
-   * at commit.
-   */
-  renderEpoch(pon: PageObjectNumber, includeAnnotations?: boolean): number;
-  /**
-   * Declare that page pixels changed — the open door for facts the built-in
-   * event map doesn't know (a plugin's own mutation vocabulary: redaction,
-   * text edit, anything third-party). Call at CONFIRMATION (after the engine
-   * write resolves), never for optimistic previews — those belong in overlay
-   * layers. `pons` omitted = every page; `scope` defaults to 'content'
-   * (repaint everything) because a caller who doesn't say is safest repainted
-   * fully. Redundant with a mapped engine event? Harmless — one extra refetch.
-   */
-  invalidate(opts?: {
-    pons?: readonly PageObjectNumber[];
-    scope?: InvalidateScope;
-  }): void;
-}
-declare const RenderToken: import("@embedpdf/core").CapabilityToken<RenderCapability>;
-//#endregion
+import { a as RenderPluginOptions, c as FullPageOptions, d as TilePaintSource, f as TilesOptions, i as RenderCapability, l as PageViewDemand, n as PaintSettings, o as RenderState, r as RenderAction, s as RenderToken, t as InvalidateScope, u as TilePaintPlan } from "./contract-CWPMd1OW.js";
 //#region src/render.plugin.d.ts
 /**
  * Document-scoped. The ONE policy consumer in the client stack: the doc-bind
@@ -229,5 +13,5 @@ declare const RenderToken: import("@embedpdf/core").CapabilityToken<RenderCapabi
  */
 declare const renderPlugin: (options?: RenderPluginOptions) => import("@embedpdf/core").PluginDef<RenderState, RenderAction, RenderCapability>;
 //#endregion
-export { type InvalidateScope, type PageViewDemand, type RenderCapability, type RenderPluginOptions, type RenderState, RenderToken, type TilePaintPlan, type TilePaintSource, type TilingConfig, renderPlugin };
+export { type FullPageOptions, type InvalidateScope, type PageViewDemand, type PaintSettings, type RenderCapability, type RenderPluginOptions, type RenderState, RenderToken, type TilePaintPlan, type TilePaintSource, type TilesOptions, renderPlugin };
 //# sourceMappingURL=index.d.ts.map