@embedpdf/plugin-render 3.0.0-next.10 → 3.0.0-next.12

package/dist/index.d.cts

@@ -1,333 +1,4 @@
-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
+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.cjs";
 //#region src/render.plugin.d.ts
 /**
  * Document-scoped. The ONE policy consumer in the client stack: the doc-bind

package/dist/index.d.ts

@@ -1,333 +1,4 @@
-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
+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

package/dist/index.js

@@ -1,4 +1,5 @@
-import { CONTINUOUS_RENDER_POLICY, PermissionDenied, createCapabilityToken, definePlugin } from "@embedpdf/core";
+import { t as RenderToken } from "./contract-BvwW7rrm.js";
+import { CONTINUOUS_RENDER_POLICY, PermissionDenied, definePlugin } from "@embedpdf/core";
 import { intersectRects } from "@embedpdf/core-geometry";
 //#region src/paint-plan.ts
 const EMPTY_TILE_PLAN = {
@@ -1002,9 +1003,6 @@ const renderReducer = (state, a) => {
 	};
 };
 //#endregion
-//#region src/types.ts
-const RenderToken = createCapabilityToken("render");
-//#endregion
 //#region src/render.plugin.ts
 /**
 * Document-scoped. The ONE policy consumer in the client stack: the doc-bind