@embedpdf/plugin-render 3.0.0-next.5 → 3.0.0-next.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { EngineRenderPolicy, PageImageHandle, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
1
+ import { EngineRenderPolicy, PageImageHandle, PageImageOptions, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
2
2
  import { Rect } from "@embedpdf/core-geometry";
3
3
  //#region src/paint-plan.d.ts
4
4
  /**
@@ -35,7 +35,7 @@ interface TilePaintSource {
35
35
  handle: PageImageHandle;
36
36
  }
37
37
  /**
38
- * What a TileLayer paints right now. `paint` draws ONLY from resolved
38
+ * What a tile plane paints right now. `paint` draws ONLY from resolved
39
39
  * rasters — retained generations live here until the release rules fire;
40
40
  * "loading" never reaches the DOM. `fetching` is diagnostic (badge/tests).
41
41
  */
@@ -48,19 +48,58 @@ interface TilePaintPlan {
48
48
  /** Memoization stamp — a new object appears only when this changes. */
49
49
  stamp: string;
50
50
  }
51
- /** Resolved tiling configuration (renderPlugin options + defaults). */
52
- interface TilingConfig {
53
- /** Tile edge in device px. Default 512. */
54
- tileSize?: number;
51
+ /**
52
+ * The base-plane strategy: the pixel BUDGET and the render points below it.
53
+ * Device px throughout (CSS px × devicePixelRatio).
54
+ */
55
+ interface FullPageOptions {
56
+ /**
57
+ * The budget: no full-page raster ever renders wider. Small by design —
58
+ * the base is the instant backdrop; sharpness past it is the tile plane's
59
+ * job. Default 640.
60
+ */
61
+ maxWidth?: number;
62
+ /**
63
+ * Render points under a `continuous` policy. `'exact'` (default) renders
64
+ * the settled demand precisely — resting pixels are never resampled, the
65
+ * only way ~1px text stems stay crisp on dpr-1 screens. A width ladder
66
+ * opts into rung caching instead (defensible on dpr≥2 embeds). An
67
+ * advertised deployment lattice always wins over either.
68
+ */
69
+ quantize?: 'exact' | readonly number[];
70
+ }
71
+ /** The tile-plane strategy. Pass `tiles: false` to disable the plane. */
72
+ interface TilesOptions {
73
+ /** Tile edge in device px. Default 512 (policy `tileSizes` win when advertised). */
74
+ size?: number;
75
+ /**
76
+ * Tile levels under a `continuous` policy: `'exact'` (default) renders the
77
+ * settled scale precisely; a scale ladder opts into pyramid reuse. An
78
+ * advertised `policy.tiles` block always wins.
79
+ */
80
+ quantize?: 'exact' | readonly number[];
81
+ /**
82
+ * Exact-mode safety clamp on the tile level (device px per point) — the
83
+ * sharpness ceiling. Past `maxScale × pageWidth` device px of demand,
84
+ * tiles CSS-stretch instead of re-rendering. Per-screen tile cost is
85
+ * constant at any level, so this bounds nothing but numeric range.
86
+ * Default 128 (≈ 6,400% zoom on a letter page at dpr 2).
87
+ */
88
+ maxScale?: number;
55
89
  /**
56
- * Client pyramid used while the policy doesn't advertise `tiles`.
57
- * Default `[1, 2, 4, 8, 16, 32]` — ×2 aligned.
90
+ * Overlap neighboring tiles by this many device pixels per shared edge
91
+ * (each tile renders a slightly larger region and is placed to match).
92
+ * Kills hairline seams whenever tiles display at anything other than 1:1 —
93
+ * separate `<img>`s at fractional boundaries each get partial-coverage
94
+ * edge anti-aliasing, and bilinear scaling smears their last row — by
95
+ * making every edge land over the neighbor's identical content instead of
96
+ * the backdrop. Default 1; 0 disables.
58
97
  */
59
- scales?: readonly number[];
98
+ bleed?: number;
60
99
  /**
61
- * Sharpness deficit (desired ÷ supplied-by-base) above which tiles
62
- * engage. Default 1.25 — small CSS upscales read fine; past that the
63
- * ladder cap is visible and the pyramid takes over.
100
+ * Sharpness deficit (desired ÷ supplied-by-base) above which tiles engage.
101
+ * Resolved default: 1.0 when the base is exact (nothing may rest
102
+ * stretched), 1.25 under a lattice.
64
103
  */
65
104
  engageAt?: number;
66
105
  /** Prefetch ring around the visible rect. */
@@ -71,19 +110,53 @@ interface TilingConfig {
71
110
  velocityBias?: boolean;
72
111
  };
73
112
  /**
74
- * Hysteresis for LEVEL changes (a zoom settling between pyramid rungs):
75
- * tile fetches for a NEW level wait this long; pan-driven fetches at the
76
- * current level fire immediately. Default 150ms; 0 disables.
113
+ * Settle gate for LEVEL changes (a zoom in motion): tile fetches for a new
114
+ * level wait this long; pan-driven fetches at the current level fire
115
+ * immediately. Default 150ms; 0 disables.
77
116
  */
78
117
  settleMs?: number;
118
+ /** Optional arrival cross-fade for tiles, in ms. Default 0 (hard pop —
119
+ * clean once painting is decode-gated). */
120
+ fadeMs?: number;
79
121
  }
80
122
  //#endregion
81
123
  //#region src/types.d.ts
82
- /** Options for `renderPlugin()`. Tiling is capability + economics here;
83
- * WHICH view tiles is composition (mount a TileLayer per lens), and
84
- * WHETHER it engages is demand arithmetic — three levels, three owners. */
124
+ /**
125
+ * Options for `renderPlugin()` — the render STRATEGY: what the viewer
126
+ * chooses to spend, and which render points it uses when the engine permits
127
+ * anything. The shape mirrors the deployment policy (`policy.fullPage` /
128
+ * `policy.tiles`), and the one composition rule is: a strategy value
129
+ * applies as written under a `continuous` policy, and the advertised
130
+ * lattice wins when there is one — so the same options run unchanged
131
+ * against local and cloud.
132
+ */
85
133
  interface RenderPluginOptions {
86
- tiling?: TilingConfig;
134
+ /** Base plane: the pixel budget + render points. */
135
+ fullPage?: FullPageOptions;
136
+ /** Tile plane strategy; `false` disables the plane entirely. */
137
+ tiles?: TilesOptions | false;
138
+ /**
139
+ * Encode format for BOTH planes. Unset → engine default (png local, the
140
+ * deployment's format on cloud). `'bmp'` is the local fast path — no
141
+ * compression, no encoder-worker round trip; under a lattice it conforms
142
+ * to `policy.formats`.
143
+ */
144
+ format?: NonNullable<PageImageOptions['format']>;
145
+ /** Encoder quality (webp/png); ignored for bmp. */
146
+ quality?: number;
147
+ /**
148
+ * Diagnostic logging: tile scheduling, settle timing, fetch outcomes —
149
+ * the counters that catch convergence issues in long sessions. Console
150
+ * `debug` level; off by default.
151
+ */
152
+ debug?: boolean;
153
+ }
154
+ /** Layer-facing paint settings (resolved options the view layers need). */
155
+ interface PaintSettings {
156
+ /** Tile arrival cross-fade (ms); 0 = hard pop. */
157
+ fadeMs: number;
158
+ /** Whether the tile plane is enabled at all (`tiles: false` opts out). */
159
+ tiles: boolean;
87
160
  }
88
161
  interface RenderPageOptions {
89
162
  /** Device px per PDF point (use the page transform's `renderScale`). */
@@ -141,21 +214,23 @@ interface RenderCapability {
141
214
  * Render a page (by its durable pon) to an ENCODED image. Abortable. Encoded
142
215
  * output is identical for local & cloud and cheap over the wire (vs. raw RGBA).
143
216
  *
144
- * CONFORMS to the deployment policy's three-layer rule:
145
- * under a lattice the desired `scale` converts to the canonical ladder width
146
- * via `snapFullPageViewport`; under `continuous` it passes through exactly.
147
- * Same-key requests collapse in the plugin's raster store (singleflight +
148
- * LRU), so repeated asks inside one rung cost one engine call.
217
+ * This is the VIEWER door: the desired `scale` conforms through the
218
+ * resolved render points (STRATEGY ∧ POLICY) — the exact demand capped at
219
+ * the pixel budget under `continuous`, the advertised ladder under a
220
+ * lattice — and same-key requests collapse in the plugin's raster store
221
+ * (singleflight + LRU). Scale-precise offline output (export, print)
222
+ * belongs on the engine door: `doc.page(pon).render.image(...)`.
149
223
  */
150
224
  renderPage(pon: PageObjectNumber, options: RenderPageOptions): Promise<PageImageHandle>;
151
225
  /**
152
226
  * The identity of the raster `renderPage` would produce for these options —
153
- * canonical viewport + annotations flag + epoch, as one stable string.
154
- * Layers key their fetch effect on THIS instead of the raw scale: inside a
155
- * rung the key never changes (zoom 1.2→1.5 under a [1,2]-ish lattice is a
156
- * no-op — no refetch, no DOM churn); it changes exactly at rung crossings
157
- * and epoch bumps. Always available: the kernel materializes the policy on
158
- * `DocumentMeta` before the document publishes.
227
+ * conformed width + annotations flag + epoch, as one stable string. Layers
228
+ * key their fetch effect on THIS instead of the raw scale. Under a lattice
229
+ * it moves only at rung crossings; under exact-mode `continuous` it tracks
230
+ * the demand, is constant above the budget (always the budget width), and
231
+ * the LAYER settle-gates adoption so it never refetches mid-gesture.
232
+ * Always available: the kernel materializes the policy on `DocumentMeta`
233
+ * before the document publishes.
159
234
  */
160
235
  renderSourceKey(pon: PageObjectNumber, options: {
161
236
  scale: number;
@@ -163,9 +238,12 @@ interface RenderCapability {
163
238
  }): string;
164
239
  /**
165
240
  * The canonical viewport a desired scale conforms to for this page —
166
- * width-kind on a lattice, the exact scale under `continuous`.
241
+ * always width-kind: the exact demand capped at the budget (exact mode)
242
+ * or the snapped rung (ladder/lattice mode).
167
243
  */
168
244
  conformViewport(pon: PageObjectNumber, scale: number): PageRenderViewport;
245
+ /** Resolved layer-facing paint settings (settle, fade, tiles on/off). */
246
+ paintSettings(): PaintSettings;
169
247
  /** The document's advertised policy (sugar over `DocumentMeta.renderPolicy`). */
170
248
  renderPolicy(): EngineRenderPolicy;
171
249
  /**
@@ -174,21 +252,30 @@ interface RenderCapability {
174
252
  * Memoized: the same object returns until the demand, an epoch, or a
175
253
  * tile resolution actually changes it, so layers can subscribe with
176
254
  * plain `Object.is`. Calling it schedules the want-set fetches (visible
177
- * first, prefetch ring after) — idempotent, store-deduped. Engagement
178
- * is pure arithmetic: it fires only when the policy's ladder caps the
179
- * base below the demand; a thumbnail-sized demand never engages.
255
+ * first, center-out, prefetch ring after) — idempotent, store-deduped.
256
+ * Engagement is pure arithmetic against what the base will ACTUALLY
257
+ * supply (the same `baseAsk` the base layer sizes with): tiles fire when
258
+ * demand exceeds the budget/ladder cap × engageAt — on every engine.
259
+ * A thumbnail-sized demand never engages.
180
260
  */
181
261
  tilePlan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
182
262
  includeAnnotations?: boolean;
183
263
  }): TilePaintPlan;
184
264
  /**
185
- * The painter's decode-boundary report: the `<img>` for this plan key
186
- * actually painted (onload). Retained coarser generations covered by
187
- * painted want-set tiles release on this signal — never on fetch
188
- * completion, which would flash during decode.
265
+ * The painter's report: the image for this plan key had a presentation
266
+ * opportunity. Retained coarser generations covered by painted want-set
267
+ * tiles release on this signal — never on fetch completion or image load,
268
+ * which could drop the backdrop before replacement pixels are presented.
189
269
  */
190
270
  tilePainted(pon: PageObjectNumber, key: string): void;
191
- /** A lens unmounted its TileLayer: abort in-flight tile fetches and drop
271
+ /**
272
+ * The inverse report: this plan key's <img> left the DOM, so its pixels
273
+ * are no longer compositable. Painted is a statement about the SCREEN and
274
+ * must follow the DOM — a remounting tile re-decodes, and until it
275
+ * reports painted again, retention may not count it as coverage.
276
+ */
277
+ tileUnpainted(pon: PageObjectNumber, key: string): void;
278
+ /** A lens unmounted its tile plane: abort in-flight tile fetches and drop
192
279
  * the page's tile bookkeeping (resolved bytes stay cached). */
193
280
  releaseTiles(pon: PageObjectNumber): void;
194
281
  /**
@@ -229,5 +316,5 @@ declare const RenderToken: import("@embedpdf/core").CapabilityToken<RenderCapabi
229
316
  */
230
317
  declare const renderPlugin: (options?: RenderPluginOptions) => import("@embedpdf/core").PluginDef<RenderState, RenderAction, RenderCapability>;
231
318
  //#endregion
232
- export { type InvalidateScope, type PageViewDemand, type RenderCapability, type RenderPluginOptions, type RenderState, RenderToken, type TilePaintPlan, type TilePaintSource, type TilingConfig, renderPlugin };
319
+ export { type FullPageOptions, type InvalidateScope, type PageViewDemand, type PaintSettings, type RenderCapability, type RenderPluginOptions, type RenderState, RenderToken, type TilePaintPlan, type TilePaintSource, type TilesOptions, renderPlugin };
233
320
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { EngineRenderPolicy, PageImageHandle, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
1
+ import { EngineRenderPolicy, PageImageHandle, PageImageOptions, PageObjectNumber, PageRenderViewport } from "@embedpdf/core";
2
2
  import { Rect } from "@embedpdf/core-geometry";
3
3
  //#region src/paint-plan.d.ts
4
4
  /**
@@ -35,7 +35,7 @@ interface TilePaintSource {
35
35
  handle: PageImageHandle;
36
36
  }
37
37
  /**
38
- * What a TileLayer paints right now. `paint` draws ONLY from resolved
38
+ * What a tile plane paints right now. `paint` draws ONLY from resolved
39
39
  * rasters — retained generations live here until the release rules fire;
40
40
  * "loading" never reaches the DOM. `fetching` is diagnostic (badge/tests).
41
41
  */
@@ -48,19 +48,58 @@ interface TilePaintPlan {
48
48
  /** Memoization stamp — a new object appears only when this changes. */
49
49
  stamp: string;
50
50
  }
51
- /** Resolved tiling configuration (renderPlugin options + defaults). */
52
- interface TilingConfig {
53
- /** Tile edge in device px. Default 512. */
54
- tileSize?: number;
51
+ /**
52
+ * The base-plane strategy: the pixel BUDGET and the render points below it.
53
+ * Device px throughout (CSS px × devicePixelRatio).
54
+ */
55
+ interface FullPageOptions {
56
+ /**
57
+ * The budget: no full-page raster ever renders wider. Small by design —
58
+ * the base is the instant backdrop; sharpness past it is the tile plane's
59
+ * job. Default 640.
60
+ */
61
+ maxWidth?: number;
62
+ /**
63
+ * Render points under a `continuous` policy. `'exact'` (default) renders
64
+ * the settled demand precisely — resting pixels are never resampled, the
65
+ * only way ~1px text stems stay crisp on dpr-1 screens. A width ladder
66
+ * opts into rung caching instead (defensible on dpr≥2 embeds). An
67
+ * advertised deployment lattice always wins over either.
68
+ */
69
+ quantize?: 'exact' | readonly number[];
70
+ }
71
+ /** The tile-plane strategy. Pass `tiles: false` to disable the plane. */
72
+ interface TilesOptions {
73
+ /** Tile edge in device px. Default 512 (policy `tileSizes` win when advertised). */
74
+ size?: number;
75
+ /**
76
+ * Tile levels under a `continuous` policy: `'exact'` (default) renders the
77
+ * settled scale precisely; a scale ladder opts into pyramid reuse. An
78
+ * advertised `policy.tiles` block always wins.
79
+ */
80
+ quantize?: 'exact' | readonly number[];
81
+ /**
82
+ * Exact-mode safety clamp on the tile level (device px per point) — the
83
+ * sharpness ceiling. Past `maxScale × pageWidth` device px of demand,
84
+ * tiles CSS-stretch instead of re-rendering. Per-screen tile cost is
85
+ * constant at any level, so this bounds nothing but numeric range.
86
+ * Default 128 (≈ 6,400% zoom on a letter page at dpr 2).
87
+ */
88
+ maxScale?: number;
55
89
  /**
56
- * Client pyramid used while the policy doesn't advertise `tiles`.
57
- * Default `[1, 2, 4, 8, 16, 32]` — ×2 aligned.
90
+ * Overlap neighboring tiles by this many device pixels per shared edge
91
+ * (each tile renders a slightly larger region and is placed to match).
92
+ * Kills hairline seams whenever tiles display at anything other than 1:1 —
93
+ * separate `<img>`s at fractional boundaries each get partial-coverage
94
+ * edge anti-aliasing, and bilinear scaling smears their last row — by
95
+ * making every edge land over the neighbor's identical content instead of
96
+ * the backdrop. Default 1; 0 disables.
58
97
  */
59
- scales?: readonly number[];
98
+ bleed?: number;
60
99
  /**
61
- * Sharpness deficit (desired ÷ supplied-by-base) above which tiles
62
- * engage. Default 1.25 — small CSS upscales read fine; past that the
63
- * ladder cap is visible and the pyramid takes over.
100
+ * Sharpness deficit (desired ÷ supplied-by-base) above which tiles engage.
101
+ * Resolved default: 1.0 when the base is exact (nothing may rest
102
+ * stretched), 1.25 under a lattice.
64
103
  */
65
104
  engageAt?: number;
66
105
  /** Prefetch ring around the visible rect. */
@@ -71,19 +110,53 @@ interface TilingConfig {
71
110
  velocityBias?: boolean;
72
111
  };
73
112
  /**
74
- * Hysteresis for LEVEL changes (a zoom settling between pyramid rungs):
75
- * tile fetches for a NEW level wait this long; pan-driven fetches at the
76
- * current level fire immediately. Default 150ms; 0 disables.
113
+ * Settle gate for LEVEL changes (a zoom in motion): tile fetches for a new
114
+ * level wait this long; pan-driven fetches at the current level fire
115
+ * immediately. Default 150ms; 0 disables.
77
116
  */
78
117
  settleMs?: number;
118
+ /** Optional arrival cross-fade for tiles, in ms. Default 0 (hard pop —
119
+ * clean once painting is decode-gated). */
120
+ fadeMs?: number;
79
121
  }
80
122
  //#endregion
81
123
  //#region src/types.d.ts
82
- /** Options for `renderPlugin()`. Tiling is capability + economics here;
83
- * WHICH view tiles is composition (mount a TileLayer per lens), and
84
- * WHETHER it engages is demand arithmetic — three levels, three owners. */
124
+ /**
125
+ * Options for `renderPlugin()` — the render STRATEGY: what the viewer
126
+ * chooses to spend, and which render points it uses when the engine permits
127
+ * anything. The shape mirrors the deployment policy (`policy.fullPage` /
128
+ * `policy.tiles`), and the one composition rule is: a strategy value
129
+ * applies as written under a `continuous` policy, and the advertised
130
+ * lattice wins when there is one — so the same options run unchanged
131
+ * against local and cloud.
132
+ */
85
133
  interface RenderPluginOptions {
86
- tiling?: TilingConfig;
134
+ /** Base plane: the pixel budget + render points. */
135
+ fullPage?: FullPageOptions;
136
+ /** Tile plane strategy; `false` disables the plane entirely. */
137
+ tiles?: TilesOptions | false;
138
+ /**
139
+ * Encode format for BOTH planes. Unset → engine default (png local, the
140
+ * deployment's format on cloud). `'bmp'` is the local fast path — no
141
+ * compression, no encoder-worker round trip; under a lattice it conforms
142
+ * to `policy.formats`.
143
+ */
144
+ format?: NonNullable<PageImageOptions['format']>;
145
+ /** Encoder quality (webp/png); ignored for bmp. */
146
+ quality?: number;
147
+ /**
148
+ * Diagnostic logging: tile scheduling, settle timing, fetch outcomes —
149
+ * the counters that catch convergence issues in long sessions. Console
150
+ * `debug` level; off by default.
151
+ */
152
+ debug?: boolean;
153
+ }
154
+ /** Layer-facing paint settings (resolved options the view layers need). */
155
+ interface PaintSettings {
156
+ /** Tile arrival cross-fade (ms); 0 = hard pop. */
157
+ fadeMs: number;
158
+ /** Whether the tile plane is enabled at all (`tiles: false` opts out). */
159
+ tiles: boolean;
87
160
  }
88
161
  interface RenderPageOptions {
89
162
  /** Device px per PDF point (use the page transform's `renderScale`). */
@@ -141,21 +214,23 @@ interface RenderCapability {
141
214
  * Render a page (by its durable pon) to an ENCODED image. Abortable. Encoded
142
215
  * output is identical for local & cloud and cheap over the wire (vs. raw RGBA).
143
216
  *
144
- * CONFORMS to the deployment policy's three-layer rule:
145
- * under a lattice the desired `scale` converts to the canonical ladder width
146
- * via `snapFullPageViewport`; under `continuous` it passes through exactly.
147
- * Same-key requests collapse in the plugin's raster store (singleflight +
148
- * LRU), so repeated asks inside one rung cost one engine call.
217
+ * This is the VIEWER door: the desired `scale` conforms through the
218
+ * resolved render points (STRATEGY ∧ POLICY) — the exact demand capped at
219
+ * the pixel budget under `continuous`, the advertised ladder under a
220
+ * lattice — and same-key requests collapse in the plugin's raster store
221
+ * (singleflight + LRU). Scale-precise offline output (export, print)
222
+ * belongs on the engine door: `doc.page(pon).render.image(...)`.
149
223
  */
150
224
  renderPage(pon: PageObjectNumber, options: RenderPageOptions): Promise<PageImageHandle>;
151
225
  /**
152
226
  * The identity of the raster `renderPage` would produce for these options —
153
- * canonical viewport + annotations flag + epoch, as one stable string.
154
- * Layers key their fetch effect on THIS instead of the raw scale: inside a
155
- * rung the key never changes (zoom 1.2→1.5 under a [1,2]-ish lattice is a
156
- * no-op — no refetch, no DOM churn); it changes exactly at rung crossings
157
- * and epoch bumps. Always available: the kernel materializes the policy on
158
- * `DocumentMeta` before the document publishes.
227
+ * conformed width + annotations flag + epoch, as one stable string. Layers
228
+ * key their fetch effect on THIS instead of the raw scale. Under a lattice
229
+ * it moves only at rung crossings; under exact-mode `continuous` it tracks
230
+ * the demand, is constant above the budget (always the budget width), and
231
+ * the LAYER settle-gates adoption so it never refetches mid-gesture.
232
+ * Always available: the kernel materializes the policy on `DocumentMeta`
233
+ * before the document publishes.
159
234
  */
160
235
  renderSourceKey(pon: PageObjectNumber, options: {
161
236
  scale: number;
@@ -163,9 +238,12 @@ interface RenderCapability {
163
238
  }): string;
164
239
  /**
165
240
  * The canonical viewport a desired scale conforms to for this page —
166
- * width-kind on a lattice, the exact scale under `continuous`.
241
+ * always width-kind: the exact demand capped at the budget (exact mode)
242
+ * or the snapped rung (ladder/lattice mode).
167
243
  */
168
244
  conformViewport(pon: PageObjectNumber, scale: number): PageRenderViewport;
245
+ /** Resolved layer-facing paint settings (settle, fade, tiles on/off). */
246
+ paintSettings(): PaintSettings;
169
247
  /** The document's advertised policy (sugar over `DocumentMeta.renderPolicy`). */
170
248
  renderPolicy(): EngineRenderPolicy;
171
249
  /**
@@ -174,21 +252,30 @@ interface RenderCapability {
174
252
  * Memoized: the same object returns until the demand, an epoch, or a
175
253
  * tile resolution actually changes it, so layers can subscribe with
176
254
  * plain `Object.is`. Calling it schedules the want-set fetches (visible
177
- * first, prefetch ring after) — idempotent, store-deduped. Engagement
178
- * is pure arithmetic: it fires only when the policy's ladder caps the
179
- * base below the demand; a thumbnail-sized demand never engages.
255
+ * first, center-out, prefetch ring after) — idempotent, store-deduped.
256
+ * Engagement is pure arithmetic against what the base will ACTUALLY
257
+ * supply (the same `baseAsk` the base layer sizes with): tiles fire when
258
+ * demand exceeds the budget/ladder cap × engageAt — on every engine.
259
+ * A thumbnail-sized demand never engages.
180
260
  */
181
261
  tilePlan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
182
262
  includeAnnotations?: boolean;
183
263
  }): TilePaintPlan;
184
264
  /**
185
- * The painter's decode-boundary report: the `<img>` for this plan key
186
- * actually painted (onload). Retained coarser generations covered by
187
- * painted want-set tiles release on this signal — never on fetch
188
- * completion, which would flash during decode.
265
+ * The painter's report: the image for this plan key had a presentation
266
+ * opportunity. Retained coarser generations covered by painted want-set
267
+ * tiles release on this signal — never on fetch completion or image load,
268
+ * which could drop the backdrop before replacement pixels are presented.
189
269
  */
190
270
  tilePainted(pon: PageObjectNumber, key: string): void;
191
- /** A lens unmounted its TileLayer: abort in-flight tile fetches and drop
271
+ /**
272
+ * The inverse report: this plan key's <img> left the DOM, so its pixels
273
+ * are no longer compositable. Painted is a statement about the SCREEN and
274
+ * must follow the DOM — a remounting tile re-decodes, and until it
275
+ * reports painted again, retention may not count it as coverage.
276
+ */
277
+ tileUnpainted(pon: PageObjectNumber, key: string): void;
278
+ /** A lens unmounted its tile plane: abort in-flight tile fetches and drop
192
279
  * the page's tile bookkeeping (resolved bytes stay cached). */
193
280
  releaseTiles(pon: PageObjectNumber): void;
194
281
  /**
@@ -229,5 +316,5 @@ declare const RenderToken: import("@embedpdf/core").CapabilityToken<RenderCapabi
229
316
  */
230
317
  declare const renderPlugin: (options?: RenderPluginOptions) => import("@embedpdf/core").PluginDef<RenderState, RenderAction, RenderCapability>;
231
318
  //#endregion
232
- export { type InvalidateScope, type PageViewDemand, type RenderCapability, type RenderPluginOptions, type RenderState, RenderToken, type TilePaintPlan, type TilePaintSource, type TilingConfig, renderPlugin };
319
+ export { type FullPageOptions, type InvalidateScope, type PageViewDemand, type PaintSettings, type RenderCapability, type RenderPluginOptions, type RenderState, RenderToken, type TilePaintPlan, type TilePaintSource, type TilesOptions, renderPlugin };
233
320
  //# sourceMappingURL=index.d.ts.map