@embedpdf/plugin-render 3.0.0-next.14 → 3.0.0-next.16

package/dist/contract-CWPMd1OW.d.ts

@@ -1,332 +0,0 @@
-import { EngineRenderPolicy, PageImageHandle, PageImageOptions, 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 tile plane 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;
-}
-/**
- * The base-plane strategy: the pixel BUDGET and the render points below it.
- * Device px throughout (CSS px × devicePixelRatio).
- */
-interface FullPageOptions {
-  /**
-   * The budget: no full-page raster ever renders wider. Small by design —
-   * the base is the instant backdrop; sharpness past it is the tile plane's
-   * job. Default 640.
-   */
-  maxWidth?: number;
-  /**
-   * Render points under a `continuous` policy. `'exact'` (default) renders
-   * the settled demand precisely — resting pixels are never resampled, the
-   * only way ~1px text stems stay crisp on dpr-1 screens. A width ladder
-   * opts into rung caching instead (defensible on dpr≥2 embeds). An
-   * advertised deployment lattice always wins over either.
-   */
-  quantize?: 'exact' | readonly number[];
-}
-/** The tile-plane strategy. Pass `tiles: false` to disable the plane. */
-interface TilesOptions {
-  /** Tile edge in device px. Default 512 (policy `tileSizes` win when advertised). */
-  size?: number;
-  /**
-   * Tile levels under a `continuous` policy: `'exact'` (default) renders the
-   * settled scale precisely; a scale ladder opts into pyramid reuse. An
-   * advertised `policy.tiles` block always wins.
-   */
-  quantize?: 'exact' | readonly number[];
-  /**
-   * Exact-mode safety clamp on the tile level (device px per point) — the
-   * sharpness ceiling. Past `maxScale × pageWidth` device px of demand,
-   * tiles CSS-stretch instead of re-rendering. Per-screen tile cost is
-   * constant at any level, so this bounds nothing but numeric range.
-   * Default 128 (≈ 6,400% zoom on a letter page at dpr 2).
-   */
-  maxScale?: number;
-  /**
-   * Overlap neighboring tiles by this many device pixels per shared edge
-   * (each tile renders a slightly larger region and is placed to match).
-   * Kills hairline seams whenever tiles display at anything other than 1:1 —
-   * separate `<img>`s at fractional boundaries each get partial-coverage
-   * edge anti-aliasing, and bilinear scaling smears their last row — by
-   * making every edge land over the neighbor's identical content instead of
-   * the backdrop. Default 1; 0 disables.
-   */
-  bleed?: number;
-  /**
-   * Sharpness deficit (desired ÷ supplied-by-base) above which tiles engage.
-   * Resolved default: 1.0 when the base is exact (nothing may rest
-   * stretched), 1.25 under a lattice.
-   */
-  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;
-  };
-  /**
-   * Settle gate for LEVEL changes (a zoom in motion): tile fetches for a new
-   * level wait this long; pan-driven fetches at the current level fire
-   * immediately. Default 150ms; 0 disables.
-   */
-  settleMs?: number;
-  /** Optional arrival cross-fade for tiles, in ms. Default 0 (hard pop —
-   *  clean once painting is decode-gated). */
-  fadeMs?: number;
-}
-//#endregion
-//#region src/types.d.ts
-/**
- * Options for `renderPlugin()` — the render STRATEGY: what the viewer
- * chooses to spend, and which render points it uses when the engine permits
- * anything. The shape mirrors the deployment policy (`policy.fullPage` /
- * `policy.tiles`), and the one composition rule is: a strategy value
- * applies as written under a `continuous` policy, and the advertised
- * lattice wins when there is one — so the same options run unchanged
- * against local and cloud.
- */
-interface RenderPluginOptions {
-  /** Base plane: the pixel budget + render points. */
-  fullPage?: FullPageOptions;
-  /** Tile plane strategy; `false` disables the plane entirely. */
-  tiles?: TilesOptions | false;
-  /**
-   * Encode format for BOTH planes. Unset → engine default (png local, the
-   * deployment's format on cloud). `'bmp'` is the local fast path — no
-   * compression, no encoder-worker round trip; under a lattice it conforms
-   * to `policy.formats`.
-   */
-  format?: NonNullable<PageImageOptions['format']>;
-  /** Encoder quality (webp/png); ignored for bmp. */
-  quality?: number;
-  /**
-   * Diagnostic logging: tile scheduling, settle timing, fetch outcomes —
-   * the counters that catch convergence issues in long sessions. Console
-   * `debug` level; off by default.
-   */
-  debug?: boolean;
-}
-/** Layer-facing paint settings (resolved options the view layers need). */
-interface PaintSettings {
-  /** Tile arrival cross-fade (ms); 0 = hard pop. */
-  fadeMs: number;
-  /** Whether the tile plane is enabled at all (`tiles: false` opts out). */
-  tiles: boolean;
-}
-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;
-};
-/**
- * One view's scoped tile surface (see {@link RenderCapability.tilesFor}).
- * Identity (the view) is bound at creation; every call addresses that view's
- * own state for the given page.
- */
-interface ViewTiles {
-  /**
-   * The tile paint plan for a page under this view's 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, center-out, prefetch ring after) — idempotent, store-deduped.
-   * Engagement is pure arithmetic against what the base will ACTUALLY
-   * supply (the same `baseAsk` the base layer sizes with): tiles fire when
-   * demand exceeds the budget/ladder cap × engageAt — on every engine.
-   * A thumbnail-sized demand never engages.
-   */
-  plan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
-    includeAnnotations?: boolean;
-  }): TilePaintPlan;
-  /**
-   * The painter's report: the image for this plan key had a presentation
-   * opportunity. Retained coarser generations covered by painted want-set
-   * tiles release on this signal — never on fetch completion or image load,
-   * which could drop the backdrop before replacement pixels are presented.
-   */
-  painted(pon: PageObjectNumber, key: string): void;
-  /**
-   * The inverse report: this plan key's <img> left the DOM, so its pixels
-   * are no longer compositable. Painted is a statement about the SCREEN and
-   * must follow the DOM — a remounting tile re-decodes, and until it
-   * reports painted again, retention may not count it as coverage.
-   */
-  unpainted(pon: PageObjectNumber, key: string): void;
-  /** This view unmounted its tile plane for the page: abort in-flight tile
-   *  fetches, drop ITS bookkeeping (resolved bytes stay cached). */
-  release(pon: PageObjectNumber): void;
-}
-interface RenderCapability {
-  /**
-   * The twin (permissions.md): would page rasters be served to this session?
-   * Mirrors `doc.render`. When false, `renderPage` and the tile plane refuse
-   * locally (no doomed engine round-trips — the gate case for a capability
-   * whose denial would otherwise 403 on every viewport tile) and a host can
-   * render its "no preview" state instead of error tiles.
-   */
-  canRender(): boolean;
-  /**
-   * 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).
-   *
-   * This is the VIEWER door: the desired `scale` conforms through the
-   * resolved render points (STRATEGY ∧ POLICY) — the exact demand capped at
-   * the pixel budget under `continuous`, the advertised ladder under a
-   * lattice — and same-key requests collapse in the plugin's raster store
-   * (singleflight + LRU). Scale-precise offline output (export, print)
-   * belongs on the engine door: `doc.page(pon).render.image(...)`.
-   */
-  renderPage(pon: PageObjectNumber, options: RenderPageOptions): Promise<PageImageHandle>;
-  /**
-   * The identity of the raster `renderPage` would produce for these options —
-   * conformed width + annotations flag + epoch, as one stable string. Layers
-   * key their fetch effect on THIS instead of the raw scale. Under a lattice
-   * it moves only at rung crossings; under exact-mode `continuous` it tracks
-   * the demand, is constant above the budget (always the budget width), and
-   * the LAYER settle-gates adoption so it never refetches mid-gesture.
-   * 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 —
-   * always width-kind: the exact demand capped at the budget (exact mode)
-   * or the snapped rung (ladder/lattice mode).
-   */
-  conformViewport(pon: PageObjectNumber, scale: number): PageRenderViewport;
-  /** Resolved layer-facing paint settings (settle, fade, tiles on/off). */
-  paintSettings(): PaintSettings;
-  /** The document's advertised policy (sugar over `DocumentMeta.renderPolicy`). */
-  renderPolicy(): EngineRenderPolicy;
-  /**
-   * This view's tile surface — the ONE tile entry point. `view` is the
-   * consuming view's identity (`PageContextValue.view`: a stage lens id, or
-   * a PageView instance id). Tile state is kept PER VIEW × PAGE, so two
-   * views showing the same page plan independently — a thumbnail rail's
-   * never-engaging demand cannot disturb the main view's tiles. Binding the
-   * identity ONCE makes it unforgettable and unmixable: the handle's four
-   * calls can never disagree about whose state they address. Stable per
-   * view — safe as a hook/effect dependency.
-   */
-  tilesFor(view: string): ViewTiles;
-  /**
-   * 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
-export { RenderPluginOptions as a, FullPageOptions as c, TilePaintSource as d, TilesOptions as f, RenderCapability as i, PageViewDemand as l, PaintSettings as n, RenderState as o, RenderAction as r, RenderToken as s, InvalidateScope as t, TilePaintPlan as u };
-//# sourceMappingURL=contract-CWPMd1OW.d.ts.map