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

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { EngineRenderPolicy, PageImageHandle, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
+import { EngineRenderPolicy, PageImageHandle, PageImageOptions, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
 import { Rect } from "@embedpdf/core-geometry";
 //#region src/paint-plan.d.ts
 /**
@@ -35,7 +35,7 @@ interface TilePaintSource {
   handle: PageImageHandle;
 }
 /**
- * What a TileLayer paints right now. `paint` draws ONLY from resolved
+ * 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).
  */
@@ -48,19 +48,58 @@ interface TilePaintPlan {
   /** 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;
+/**
+ * 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;
   /**
-   * Client pyramid used while the policy doesn't advertise `tiles`.
-   * Default `[1, 2, 4, 8, 16, 32]` — ×2 aligned.
+   * 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.
    */
-  scales?: readonly number[];
+  bleed?: 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.
+   * 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. */
@@ -71,19 +110,53 @@ interface TilingConfig {
     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.
+   * 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()`. 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. */
+/**
+ * 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 {
-  tiling?: TilingConfig;
+  /** 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`). */
@@ -136,26 +209,75 @@ type RenderAction = {
   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).
    *
-   * 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.
+   * 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 —
-   * 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.
+   * 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;
@@ -163,34 +285,25 @@ interface RenderCapability {
   }): string;
   /**
    * The canonical viewport a desired scale conforms to for this page —
-   * width-kind on a lattice, the exact scale under `continuous`.
+   * 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;
   /**
-   * 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.
+   * 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.
    */
-  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;
+  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
@@ -229,5 +342,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.cts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EngineRenderPolicy, PageImageHandle, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
+import { EngineRenderPolicy, PageImageHandle, PageImageOptions, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
 import { Rect } from "@embedpdf/core-geometry";
 //#region src/paint-plan.d.ts
 /**
@@ -35,7 +35,7 @@ interface TilePaintSource {
   handle: PageImageHandle;
 }
 /**
- * What a TileLayer paints right now. `paint` draws ONLY from resolved
+ * 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).
  */
@@ -48,19 +48,58 @@ interface TilePaintPlan {
   /** 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;
+/**
+ * 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;
   /**
-   * Client pyramid used while the policy doesn't advertise `tiles`.
-   * Default `[1, 2, 4, 8, 16, 32]` — ×2 aligned.
+   * 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.
    */
-  scales?: readonly number[];
+  bleed?: 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.
+   * 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. */
@@ -71,19 +110,53 @@ interface TilingConfig {
     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.
+   * 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()`. 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. */
+/**
+ * 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 {
-  tiling?: TilingConfig;
+  /** 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`). */
@@ -136,26 +209,75 @@ type RenderAction = {
   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).
    *
-   * 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.
+   * 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 —
-   * 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.
+   * 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;
@@ -163,34 +285,25 @@ interface RenderCapability {
   }): string;
   /**
    * The canonical viewport a desired scale conforms to for this page —
-   * width-kind on a lattice, the exact scale under `continuous`.
+   * 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;
   /**
-   * 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.
+   * 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.
    */
-  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;
+  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
@@ -229,5 +342,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