@reekon-tools/react-native-pdf-canvas 0.1.0

package/dist/controller.js

@@ -0,0 +1,1002 @@
+/**
+ * The cadence engine. Framework-free: no React, no reanimated, no Skia calls.
+ *
+ * THE ONE RULE: the transform decides WHEN to rasterize, never WHAT to draw.
+ * Everything this file emits is a plain-number doc-space rect that is constant
+ * for the life of an epoch. The host's <Group transform> does 100% of the pan
+ * and zoom; nothing here reads a shared value.
+ *
+ * Shape of the machine:
+ *
+ *   hint()   continuous input -> restart a trailing quiet timer (or force an
+ *            evaluation once maxStaleMs has elapsed since the last commit)
+ *   settle() discrete end     -> evaluate now, subject to minEpochIntervalMs
+ *
+ * An evaluation asks `planRasters` WHAT should exist and `shouldReraster`
+ * WHETHER it is worth producing, and either does nothing or dispatches one
+ * raster run. A run renders its items through `maxConcurrentRenders` lanes —
+ * one at a time unless the backend says it can do better — and its result is
+ * committed as a brand new frozen PdfContent — identity change is the swap
+ * signal, because RN Skia's shallowEq is reference equality and a handle
+ * mutated in place would never reach the Skia tree.
+ *
+ * There is one thing the machine does for itself: a run that ends with a piece
+ * missing arms a single re-EVALUATION (see `scheduleRepair`), because every
+ * other entry point is host-driven and a host at rest produces none.
+ *
+ * WHAT A COMMIT IS NOT: THE MOMENT THE OLD PIXELS STOP BEING DRAWN. Publishing
+ * `content` only changes what the NEXT render will say; the renderer catches up
+ * later, and on web it re-records its picture from the currently-mounted tree
+ * many times in between. So every release this file makes carries the epoch it
+ * happened at (`cache.release(key, epoch)`) and the flush is fenced on that same
+ * epoch, and a host that can report presentation (`notePresented`) replaces the
+ * guess with the fact. See the fence section of `./cache.js`.
+ *
+ * THIS FILE OWNS NO GEOMETRY AND NO PLANNING. Every rect operation comes from
+ * `./geometry.js` and every decision about what to render, at what scale, under
+ * which key comes from `./planner.js`. A private copy of either is how the two
+ * silently drift until the tested one is testing nothing that runs.
+ */
+import { monotonicNow } from './clock.js';
+import { isEmptyRect, rectIntersects, rectsCover } from './geometry.js';
+import { planRasters, shouldReraster } from './planner.js';
+import { PdfError } from './types.js';
+/* ------------------------------------------------------------------ *
+ * Defaults for the injected seams
+ *
+ * The ONLY place this module touches a real clock. Every other line goes
+ * through `now` / `schedule` so a test can run the whole machine in Node.
+ * ------------------------------------------------------------------ */
+const DEFAULT_NOW = () => Date.now();
+const DEFAULT_SCHEDULE = (fn, ms) => {
+    const id = setTimeout(fn, ms);
+    return {
+        cancel() {
+            clearTimeout(id);
+        },
+    };
+};
+/* ------------------------------------------------------------------ *
+ * Tuning that is genuinely internal (not policy the host should see)
+ * ------------------------------------------------------------------ */
+/** Pages this far outside the plan's window lose their base to the cache. */
+const BASE_PAGE_RADIUS = 2;
+/**
+ * Containment tolerance in doc points. Both rects are the product of float
+ * arithmetic on both sides, and a 1e-9 overhang is not a coverage failure.
+ */
+const CONTAINMENT_EPSILON = 1e-6;
+/**
+ * First delay before the controller re-evaluates an epoch that committed with a
+ * hole in it, and the ceiling the back-off climbs to.
+ *
+ * WHY A BACK-OFF AND NOT A FIXED RETRY. The repair is a re-EVALUATION, not a
+ * retry of a piece: it re-enters `evaluate` against the newest viewport, so every
+ * predicate, the min-interval floor and the identical-plan logic still apply, and
+ * the plan it produces asks for the same geometry-derived keys — so the pieces
+ * that DID land are cache hits and only the hole is re-rendered. But a hole with
+ * a permanent cause (a page PDFium refuses, a piece the budget can never fit)
+ * would otherwise re-render on a fixed timer for the life of the session.
+ * Doubling to a 30s ceiling costs one render a minute in that pathological case
+ * and repairs a transient failure in a quarter of a second, which is the case
+ * that actually happens.
+ *
+ * The counter resets whenever the hole CHANGES (a different plan, or a different
+ * set of missing keys), because that is evidence the situation is still moving.
+ */
+const REPAIR_BASE_MS = 250;
+const REPAIR_MAX_MS = 30000;
+const EMPTY_RASTERS = Object.freeze([]);
+function toPdfError(cause) {
+    if (cause instanceof PdfError)
+        return cause;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new PdfError('backend-failure', message, { cause });
+}
+export function createPdfController(options) {
+    const { handle, policy, ingest, cache, allowedPages } = options;
+    const now = options.now ?? DEFAULT_NOW;
+    const schedule = options.schedule ?? DEFAULT_SCHEDULE;
+    const backendId = options.backendId ?? 'unknown';
+    const renderLanes = Math.max(1, Math.floor(options.maxConcurrentRenders ?? 1) || 1);
+    /**
+     * Diagnostics are OBSERVABILITY, and a host's telemetry callback must never be
+     * able to stop the machine. `emit` is called from inside the render lanes, so
+     * a throw here would reject a lane — see the note on `lane` for what that
+     * costs. Swallowing is the lesser evil, and there is nowhere better to report
+     * it than the callback that just failed.
+     */
+    const emit = (d) => {
+        try {
+            options.onDiagnostic?.(d);
+        }
+        catch {
+            // Deliberately empty.
+        }
+    };
+    /**
+     * `shouldReraster` folds `minEpochIntervalMs` in and reports the reason that
+     * WOULD have fired — which cannot be told apart from "nothing fired", since
+     * both come back as `{reraster: false, reason: 'stale'}`. The controller has
+     * to tell them apart: a blocked predicate re-arms the timer for the remainder
+     * of the floor, whereas nothing-fired stops. So the predicates are asked with
+     * the floor removed and the floor is applied here, next to the re-arm that
+     * implements it.
+     */
+    const predicatePolicy = { ...policy, minEpochIntervalMs: 0 };
+    const geometryByIndex = new Map();
+    for (const geometry of options.pages)
+        geometryByIndex.set(geometry.index, geometry);
+    const pageInfos = options.pageRects.map((pageRect, page) => {
+        const geometry = geometryByIndex.get(page);
+        const raw = geometry !== undefined && geometry.width > 0
+            ? pageRect.width / geometry.width
+            : 1;
+        return {
+            page,
+            pageRect,
+            layoutScale: Number.isFinite(raw) && raw > 0 ? raw : 1,
+        };
+    });
+    const listeners = new Set();
+    const unsubscribeEvictions = cache.subscribeEvictions?.((raster, reason) => {
+        emit({ type: 'evict', key: raster.key, bytes: raster.bytes, reason });
+    });
+    let content = Object.freeze({
+        pages: Object.freeze(pageInfos.map(info => Object.freeze({
+            page: info.page,
+            pageRect: info.pageRect,
+            base: EMPTY_RASTERS,
+            detail: EMPTY_RASTERS,
+            retiring: EMPTY_RASTERS,
+        }))),
+        epoch: 0,
+        settling: false,
+    });
+    let epoch = 0;
+    let epochState = null;
+    /** Viewport of the last COMMITTED run. The look-ahead predicate's origin. */
+    let rasterViewport = null;
+    let committedSignature = null;
+    /** Signature of the most recent plan we acted on, for hint() idempotence. */
+    let plannedSignature = null;
+    let latestViewport = null;
+    let lastSeenScale = null;
+    let suppressed = false;
+    let destroyed = false;
+    /**
+     * One pending evaluation, whatever armed it (quiet timer or min-interval
+     * back-off). Both mean the same thing — "evaluate later against the newest
+     * viewport" — so a second one must replace the first, never stack.
+     */
+    let pending = null;
+    let inFlight = null;
+    /** Queue depth 1, newest wins. Only the viewport matters; we replan on drain. */
+    let queued = null;
+    /**
+     * The hole the last repair was armed for — plan signature plus the sorted
+     * missing keys — and how many times in a row we have seen exactly it. See
+     * `REPAIR_BASE_MS`.
+     */
+    let repairSignature = null;
+    let repairAttempts = 0;
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function cancelPending() {
+        pending?.cancel();
+        pending = null;
+    }
+    function arm(ms) {
+        cancelPending();
+        pending = schedule(() => {
+            pending = null;
+            if (destroyed || latestViewport === null)
+                return;
+            evaluate(latestViewport, false);
+        }, ms);
+    }
+    /* ---------------------------------------------------------------- *
+     * Planning — delegated wholesale to ./planner.js
+     * ---------------------------------------------------------------- */
+    /**
+     * Page INDICES the planner is allowed to consider, which is the intersection
+     * of "on screen" and `allowedPages`. Deriving it here rather than in the
+     * planner is the split the contract asks for: the planner knows geometry, the
+     * controller knows which pages the host is willing to pay for.
+     */
+    function visiblePagesFor(viewport) {
+        const visible = [];
+        for (const info of pageInfos) {
+            if (allowedPages !== undefined && !allowedPages.has(info.page))
+                continue;
+            if (isEmptyRect(info.pageRect))
+                continue;
+            if (!rectIntersects(viewport.visibleDocRect, info.pageRect))
+                continue;
+            visible.push(info.page);
+        }
+        return visible;
+    }
+    function buildPlan(viewport) {
+        return planRasters({
+            viewport,
+            pages: options.pages,
+            pageRects: options.pageRects,
+            visiblePages: visiblePagesFor(viewport),
+            policy,
+        });
+    }
+    const signatureOf = (plan) => plan.items.map(item => item.key).join('|');
+    /**
+     * Did a predicate fire for `viewport`, judged against an already-rastered
+     * state? The floor is deliberately absent — see `predicatePolicy`.
+     */
+    function firedAgainst(state, stateViewport, viewport) {
+        const verdict = shouldReraster({
+            next: viewport,
+            previous: stateViewport,
+            epoch: state,
+            policy: predicatePolicy,
+            nowMs: now(),
+        });
+        return verdict.reraster ? verdict.reason : null;
+    }
+    /**
+     * The doc rect of every page a plan planned — the epoch's coverage
+     * RESPONSIBILITY (see `EpochState.pageRects`). Read off the plan's own items
+     * rather than from the visible set, so a page the plan skipped (outside
+     * `allowedPages`, or off screen) is not a region anything is expected to cover.
+     */
+    function plannedPageRects(plan) {
+        const rects = [];
+        for (const page of new Set(plan.items.map(item => item.page))) {
+            const info = pageInfos[page];
+            if (info !== undefined)
+                rects.push(info.pageRect);
+        }
+        return rects;
+    }
+    /** Does this page have ANYTHING drawable under its detail layer? */
+    function hasBase(page) {
+        return (content.pages[page]?.base.length ?? 0) > 0;
+    }
+    /**
+     * Is this exact base piece mounted?
+     *
+     * Per-PIECE, not per-page, and that matters now the base is a grid: a page
+     * holding three of its four pieces has a base, but the fourth quarter of it is
+     * unpainted. Asking per-page would let that hole sit there until some other
+     * predicate happened to fire.
+     */
+    function hasBasePiece(page, key) {
+        return content.pages[page]?.base.some(r => r.key === key) ?? false;
+    }
+    /* ---------------------------------------------------------------- *
+     * Evaluation and dispatch
+     * ---------------------------------------------------------------- */
+    function evaluate(viewport, forced) {
+        if (destroyed)
+            return;
+        latestViewport = viewport;
+        const plan = buildPlan(viewport);
+        const signature = signatureOf(plan);
+        let reason = firedAgainst(epochState, rasterViewport, viewport);
+        if (reason === null) {
+            // A page has entered the window without a base of its own. Nothing to
+            // compare against, and a page drawn from nothing is the blank frame.
+            // `shouldReraster` cannot see this — it is documented never to return
+            // 'layout', because a layout change is invisible from a viewport
+            // snapshot and its owner has to force the epoch.
+            const missingBase = plan.items.some(item => item.role === 'base' && !hasBasePiece(item.page, item.key));
+            if (missingBase)
+                reason = 'layout';
+        }
+        // maxStaleMs forces the EVALUATION, not the raster: under continued input
+        // the quiet timer never fires, so without this the predicates are never
+        // consulted at all. If they still say nothing changed, honour that.
+        if (reason === null && forced && signature !== committedSignature)
+            reason = 'stale';
+        if (reason === null)
+            return;
+        const elapsed = epochState === null
+            ? Number.POSITIVE_INFINITY
+            : now() - epochState.committedAtMs;
+        if (elapsed < policy.minEpochIntervalMs) {
+            // Not a drop: re-arm for the remainder holding the NEWEST viewport, which
+            // is what collapses a burst of settles into one raster.
+            emit({ type: 'skip', reason: 'min-interval' });
+            arm(policy.minEpochIntervalMs - elapsed);
+            return;
+        }
+        cancelPending();
+        plannedSignature = signature;
+        dispatch(plan, signature, reason, viewport);
+    }
+    function dispatch(plan, signature, reason, viewport) {
+        if (inFlight !== null) {
+            // Already producing exactly this. Aborting it to start it again is the
+            // pinch-nudge failure in its purest form.
+            if (inFlight.signature === signature)
+                return;
+            queued = viewport;
+            // Best effort: PDFKit's draw(with:to:) and Android's PdfRenderer.render
+            // are synchronous and uninterruptible once entered, so this often only
+            // prevents the NEXT piece from starting.
+            inFlight.abort.abort();
+            return;
+        }
+        void run({ plan, signature, viewport, reason, abort: new AbortController() });
+    }
+    /**
+     * Render one plan into rasters, `renderLanes` pieces at a time.
+     *
+     * WHY LANES AND NOT `Promise.all(items.map(...))`. The bound is the backend's
+     * (`RasterizerCapabilities.maxConcurrentRenders`); anything beyond it queues
+     * inside the backend, where the controller can no longer see it, cannot stop
+     * it, and cannot decide it is no longer worth doing. Lanes keep every decision
+     * — abort, supersede, teardown — at the point where the next piece is CLAIMED.
+     *
+     * THREE THINGS THE PARALLEL FORM HAS TO PRESERVE, all of which a naive
+     * `Promise.all` loses:
+     *
+     *  1. ORDER IS PLAN ORDER, NOT COMPLETION ORDER. Results are written into a
+     *     SLOT indexed by plan position and compacted at the end. Pieces OVERLAP
+     *     rather than abut, so the array order is the draw order — and `commit`'s
+     *     `unchanged` test compares the fresh base against the mounted one element
+     *     by element, which a reordered array fails for a set that did not change.
+     *     Completion order must not be observable anywhere.
+     *  2. A FAILING PIECE DOES NOT TAKE OUT ITS SIBLINGS. One rejection records one
+     *     missing key and the lane moves on; only an ABORT stops a lane.
+     *  3. NOTHING IS INGESTED AFTER TEARDOWN. The check between `render` and
+     *     `ingest` is the same one the sequential loop had, and it matters more
+     *     here because `renderLanes` renders can be in flight at once: pixels that
+     *     land after `destroy()` are dropped BEFORE `ingest`, so no SkImage is ever
+     *     created that no content object will release. A piece that got as far as
+     *     `put` + `acquire` is pinned, and `finish`'s destroyed branch releases
+     *     exactly those.
+     *
+     * A superseded epoch never WAITS for work it has not already started: `stopped`
+     * is checked at the top of every claim, so the abort takes effect after at most
+     * the pieces already inside `handle.render` — which are aborted through
+     * `state.abort.signal` and, on a backend that honours it, reject at once.
+     */
+    async function run(state) {
+        inFlight = state;
+        const items = state.plan.items;
+        const slots = new Array(items.length).fill(undefined);
+        const missing = [];
+        let claimed = 0;
+        let stopped = false;
+        const producedSoFar = () => {
+            const out = [];
+            for (const raster of slots)
+                if (raster !== undefined)
+                    out.push(raster);
+            return out;
+        };
+        /**
+         * The part of a piece that is decided WITHOUT suspending: a cache hit, or a
+         * plan item for a page that does not exist. Returns undefined when it
+         * settled the piece, or the promise for the render it started.
+         *
+         * SPLIT OUT ON PURPOSE, and it is not a micro-optimisation. A lane that
+         * `await`s a cache hit yields a turn per hit, and the base grid is USUALLY
+         * all hits — six of them on a tiled letter page — so the first genuine
+         * render would no longer be issued synchronously from `settle()`. Nothing in
+         * production breaks either way, but "dispatch starts the first render before
+         * it returns" is a property the suite's injected clock relies on, and
+         * quietly giving it up would move the whole cadence a scheduler turn later
+         * for no benefit at all.
+         */
+        const claim = (item, slot) => {
+            const hit = cache.acquire(item.key);
+            if (hit !== undefined) {
+                emit({ type: 'cache-hit', key: item.key });
+                slots[slot] = hit;
+                return undefined;
+            }
+            const info = pageInfos[item.page];
+            if (info === undefined)
+                return undefined; // items only come from pageInfos
+            return renderOne(item, slot, info);
+        };
+        const renderOne = async (item, slot, info) => {
+            const startedAt = now();
+            let pixels;
+            try {
+                pixels = await handle.render({
+                    page: item.page,
+                    // Page-LOCAL rect: the planner works in LAYOUT space, but a backend
+                    // renders a page and knows nothing about where the layout put it.
+                    docRect: {
+                        x: (item.docRect.x - info.pageRect.x) / info.layoutScale,
+                        y: (item.docRect.y - info.pageRect.y) / info.layoutScale,
+                        width: item.docRect.width / info.layoutScale,
+                        height: item.docRect.height / info.layoutScale,
+                    },
+                    scale: item.scale * info.layoutScale,
+                    // Never: the Skia layer draws the app's own annotations on top and
+                    // PDF-embedded ones would double-draw.
+                    annotations: false,
+                    background: 'white',
+                }, state.abort.signal);
+            }
+            catch (error) {
+                missing.push(item.key);
+                // An abort stops the whole run; a genuine backend failure is this
+                // piece's problem alone and the other lanes keep going.
+                if (state.abort.signal.aborted) {
+                    stopped = true;
+                    return;
+                }
+                emit({ type: 'error', key: item.key, error: toPdfError(error) });
+                return;
+            }
+            if (destroyed) {
+                // Landed after teardown. NOT ingesting is the release: `pixels` is a
+                // plain buffer nothing native owns yet, so dropping it here is a
+                // collectable allocation — whereas ingesting it mints an SkImage that no
+                // content object exists to free.
+                stopped = true;
+                return;
+            }
+            // INGEST THROWS BY CONTRACT, and this try is what keeps that a piece's
+            // problem rather than the run's. `ingestRaster` raises 'backend-failure'
+            // whenever `Skia.Image.MakeImage` returns null — memory pressure, or a
+            // colour type the active Skia backend refuses — which is exactly the
+            // condition a high-zoom epoch is most likely to hit, and it lands AFTER
+            // the try that covers `handle.render`. Left to escape it rejects the lane,
+            // which is the one failure this whole structure must not have (see `lane`).
+            try {
+                emit({
+                    type: 'raster',
+                    key: item.key,
+                    ms: now() - startedAt,
+                    pixels: item.pixels.width * item.pixels.height,
+                    backend: backendId,
+                });
+                // Measured with the hi-res clock, never `now()`: `now` is injectable so
+                // tests can drive a fake one, and 1 ms quantisation is exactly the wrong
+                // resolution for the term this exists to size.
+                const ingestStartedAt = monotonicNow();
+                const raster = ingest(pixels, {
+                    key: item.key,
+                    page: item.page,
+                    role: item.role,
+                    docRect: item.docRect,
+                    scale: item.scale,
+                    epoch: epoch + 1,
+                });
+                const ingestMs = monotonicNow() - ingestStartedAt;
+                // Emitted only when the BACKEND reported its half of the split. A
+                // backend that does not (the fake one, and therefore the whole vitest
+                // suite) sees no behaviour change at all — and an ingest number with no
+                // transport number beside it would be the same subtraction that made
+                // this measurement necessary.
+                const timings = pixels.timings;
+                if (timings !== undefined) {
+                    emit({
+                        type: 'raster-phases',
+                        key: item.key,
+                        backend: backendId,
+                        bridgeMs: timings.bridgeMs,
+                        decodeMs: timings.decodeMs,
+                        ingestMs,
+                        totalMs: timings.bridgeMs + timings.decodeMs + ingestMs,
+                        payloadChars: timings.payloadChars,
+                        byteLength: pixels.bytes.byteLength,
+                        tight: timings.tight,
+                    });
+                }
+                if (!cache.put(raster)) {
+                    // Refused by the budget. Degrade: this piece simply does not exist and
+                    // the base keeps drawing underneath it. `finish` arms a repair, so the
+                    // refusal is transient — by the next evaluation the commit has released
+                    // a whole retired grid and there is room.
+                    missing.push(item.key);
+                    return;
+                }
+                // Pin immediately. Without this, a later item of the SAME plan can evict
+                // an earlier one to make room for itself — and with lanes, a CONCURRENT
+                // one can too.
+                const owned = cache.acquire(item.key);
+                if (owned === undefined)
+                    missing.push(item.key);
+                else
+                    slots[slot] = owned;
+            }
+            catch (error) {
+                // Same shape as a backend failure: one missing key, coverage genuinely
+                // incomplete, and the repair re-plans the identical geometry-derived key.
+                missing.push(item.key);
+                emit({ type: 'error', key: item.key, error: toPdfError(error) });
+                return;
+            }
+            // Superseded and no longer useful: stop burning renders on it.
+            if (state.abort.signal.aborted &&
+                !stillWorthCommitting(state, producedSoFar()))
+                stopped = true;
+        };
+        /**
+         * A LANE MUST NEVER REJECT. That is the invariant this try exists to make
+         * true unconditionally, rather than leave as something you have to re-derive
+         * from every callee each time one of them changes.
+         *
+         * `Promise.all` rejects on the FIRST lane to fail and hands control straight
+         * back to `run`'s caller, which means two things at once, both bad and
+         * neither visible at the throw site:
+         *
+         *  - `run` never reaches `inFlight = null` or `finish`, so the controller
+         *    believes an abandoned run is still producing. Every later `dispatch`
+         *    takes the in-flight branch and no epoch is ever committed again.
+         *  - the SIBLING lanes keep running, and the pieces they pin with
+         *    `cache.acquire` have lost the only code path that would release them.
+         *
+         * So a throw is recorded the way every other per-piece failure is: one
+         * missing key, coverage genuinely incomplete, the repair re-plans it. The
+         * inner guards in `renderOne` catch the two throws that are actually
+         * expected (the backend's and ingest's) and report them with more context;
+         * this catches everything else, including a host-supplied `RasterCache`.
+         */
+        const lane = async () => {
+            for (;;) {
+                if (stopped || destroyed)
+                    return;
+                const slot = claimed++;
+                const item = items[slot];
+                if (item === undefined)
+                    return;
+                try {
+                    const started = claim(item, slot);
+                    if (started !== undefined)
+                        await started;
+                }
+                catch (error) {
+                    // Deduped: `renderOne` may already have recorded this key before
+                    // something after it threw, and a doubled entry would make the same
+                    // hole look like a different one and reset the repair back-off.
+                    if (!missing.includes(item.key))
+                        missing.push(item.key);
+                    emit({ type: 'error', key: item.key, error: toPdfError(error) });
+                }
+            }
+        };
+        const lanes = Math.max(1, Math.min(renderLanes, items.length));
+        await Promise.all(Array.from({ length: lanes }, () => lane()));
+        inFlight = null;
+        finish(state, producedSoFar(), missing);
+    }
+    /**
+     * Do NOT discard a completed raster whose plan still satisfies the predicates
+     * against the newest viewport. Throwing away a finished 400ms render is the
+     * failure that leaves a user pinch-nudging and never seeing detail.
+     */
+    function stillWorthCommitting(state, produced) {
+        if (produced.length === 0)
+            return false;
+        if (latestViewport === null)
+            return true;
+        // Anti-blank beats freshness: a base for a page that has none outranks any
+        // staleness argument, because the alternative is drawing nothing at all.
+        if (produced.some(raster => raster.role === 'base' && !hasBase(raster.page)))
+            return true;
+        // committedAtMs is `now()` on purpose: this run has not been committed, and
+        // dating it in the past would let the staleness predicate reject work that
+        // has only just finished.
+        //
+        // The PLAN's coverage, deliberately, where `commit` records the PRODUCED
+        // coverage. The question here is "has the viewport moved past what this run
+        // was for", not "did this run come out whole": judging a partial run against
+        // its own holes would answer 'coverage' and throw away the pieces that DID
+        // land, when the right move is to mount them and re-plan the hole.
+        const asEpoch = {
+            detailScale: state.plan.detailScale,
+            pageRects: plannedPageRects(state.plan),
+            coveredRects: state.plan.coveredDocRect === null ? [] : [state.plan.coveredDocRect],
+            committedAtMs: now(),
+        };
+        return firedAgainst(asEpoch, state.viewport, latestViewport) === null;
+    }
+    function finish(state, produced, missing) {
+        const superseded = state.abort.signal.aborted || queued !== null;
+        if (destroyed) {
+            // Torn down mid-run. Nothing is mounted any more, so flushing here is safe
+            // and is the only thing that keeps a late-landing raster from leaking.
+            // NO EPOCH, deliberately, on either call: there is no renderer left to
+            // fence against, and an epoch here would strand these until a commit that
+            // is never coming.
+            for (const raster of produced)
+                cache.release(raster.key);
+            cache.flushRetired();
+            return;
+        }
+        if (produced.length > 0 &&
+            (!superseded || stillWorthCommitting(state, produced))) {
+            commit(state, produced, missing);
+        }
+        else {
+            // Dropped. The pins go back; the entries die at the next commit's flush,
+            // and until then they are still cache hits if the next plan wants them.
+            // Untagged: a dropped run mounted nothing, so no renderer ever saw these.
+            for (const raster of produced)
+                cache.release(raster.key);
+        }
+        if (queued !== null) {
+            const viewport = queued;
+            queued = null;
+            // Re-evaluate rather than replay: the queued plan was built for a viewport
+            // that may itself be stale, and the predicates may now be satisfied by
+            // what we just committed. This IS the next evaluation, so a hole does not
+            // additionally need a repair armed for it.
+            evaluate(viewport, false);
+            return;
+        }
+        scheduleRepair(state, missing);
+    }
+    /* ---------------------------------------------------------------- *
+     * Self-heal
+     * ---------------------------------------------------------------- */
+    /**
+     * THE HOLE THAT NEVER CLOSED.
+     *
+     * `commit` records coverage from what was PRODUCED, so an epoch that lost a
+     * piece leaves a genuine hole in `coveredRects` and the coverage predicate
+     * WOULD fire the instant it were consulted. The design's stated repair — "a
+     * hole re-fires 'coverage' on the next evaluation", with deliberately no retry
+     * timer — is sound only while an evaluation is guaranteed to arrive. At rest
+     * none is: every entry point to `evaluate` is host-driven (`hint`, `settle`),
+     * and a host whose viewport has stopped moving has nothing to report. So the
+     * machine published `settling: true`, stated that it knew it was incomplete,
+     * and stopped. On the phone that is a low-resolution rectangle in the middle of
+     * a sharp page that never sharpens, however long you look at it.
+     *
+     * This is NOT the retry timer the design rules out. It does not re-render a
+     * piece and it holds no reference to one: it arms exactly one re-EVALUATION
+     * against `latestViewport`, through the same `arm` seam the min-interval
+     * back-off already uses, and everything downstream — the predicates, the
+     * min-interval floor, `dispatch`'s identical-signature guard, the cache hits on
+     * every piece that DID land — behaves as it does for a host-driven settle. If
+     * the viewport has moved on, the evaluation plans for where the user is now and
+     * the stale hole was never worth repairing anyway.
+     *
+     * It also closes the BUDGET half of the same symptom without touching
+     * `cacheBudgetBytes` — see the note in `run` on `cache.put` refusal.
+     */
+    function scheduleRepair(state, missing) {
+        if (destroyed)
+            return;
+        if (missing.length === 0) {
+            // A whole epoch. Nothing outstanding, so the next hole starts its back-off
+            // from the beginning rather than inheriting this run's history.
+            repairSignature = null;
+            repairAttempts = 0;
+            return;
+        }
+        if (pending !== null) {
+            // An evaluation is already armed — a quiet timer from a hint, or the
+            // min-interval back-off. It will consult the coverage predicate against
+            // the newest viewport, which is the whole of what a repair does, and it is
+            // due sooner. Replacing it with ours would only postpone it.
+            return;
+        }
+        const signature = `${state.signature}#${[...missing].sort().join(',')}`;
+        if (signature !== repairSignature) {
+            repairSignature = signature;
+            repairAttempts = 0;
+        }
+        const inMs = Math.min(REPAIR_MAX_MS, REPAIR_BASE_MS * 2 ** repairAttempts);
+        repairAttempts += 1;
+        emit({
+            type: 'repair',
+            missing: missing.length,
+            inMs,
+            attempt: repairAttempts,
+        });
+        arm(inMs);
+    }
+    /* ---------------------------------------------------------------- *
+     * Epoch commit
+     * ---------------------------------------------------------------- */
+    /**
+     * May every one of `previous` be dropped now that `next` is mounted?
+     *
+     * Judged against the WHOLE of `next` — see `rectsCover`. The old rule asked
+     * whether each old raster sat inside ONE fresh raster, which a grid can never
+     * satisfy for a piece that straddles a seam: `retiring` became the entire
+     * previous grid on every epoch and the cache held two full grids through every
+     * transition.
+     *
+     * `next` is deliberately what was PRODUCED this run, not what was planned, so a
+     * grid that lost a piece to the budget cannot claim coverage. That is the
+     * no-blank guarantee: an old piece is released only once something mounted in
+     * the same commit paints every point of it.
+     */
+    function fullyCovers(next, previous) {
+        if (previous.length === 0)
+            return true;
+        if (next.length === 0)
+            return false;
+        const fresh = next.map(raster => raster.docRect);
+        return previous.every(old => rectsCover(fresh, old.docRect, CONTAINMENT_EPSILON));
+    }
+    function commit(state, produced, missing) {
+        epoch += 1;
+        const plannedPages = new Set(state.plan.items.map(item => item.page));
+        const detailPlannedPages = new Set(state.plan.items
+            .filter(item => item.role === 'detail')
+            .map(item => item.page));
+        /**
+         * TWO RELEASE LISTS, AND THE SPLIT IS THE WHOLE POINT.
+         *
+         * `releaseMounted` is rasters the OUTGOING content object was drawing. A
+         * renderer may still be holding them — on web it re-records the picture from
+         * the mounted tree several times before React commits this epoch — so these
+         * are released WITH the epoch, and the cache holds them behind its fence
+         * until the renderer has provably moved on (see `RasterCache`).
+         *
+         * `releaseFresh` is rasters this run produced and this commit then declined
+         * to mount. They were never in a content object, so no Skia node ever saw
+         * them and there is nothing to fence: they are released untagged and die at
+         * this flush, exactly as before. Tagging them too would hold a whole refused
+         * grid for an extra epoch for no reason at all.
+         */
+        const releaseMounted = [];
+        const releaseFresh = [];
+        const nextPages = content.pages.map(previous => {
+            // Last epoch's retiring set has now been mounted for a full epoch. This is
+            // the ONLY place it is dropped: retirement never owns a commit or a timer,
+            // it piggybacks on the commit that mounts the next epoch.
+            releaseMounted.push(...previous.retiring);
+            const freshBase = produced.filter(r => r.page === previous.page && r.role === 'base');
+            const freshDetail = produced.filter(r => r.page === previous.page && r.role === 'detail');
+            let base = previous.base;
+            if (freshBase.length > 0) {
+                // Every base piece this run touched was pinned by `run`, and content only
+                // ever holds ONE reference per slot — so whichever set loses below has to
+                // give its pins back. Skipping that leaks a refcount no flush can clear.
+                const unchanged = freshBase.length === base.length &&
+                    freshBase.every((raster, index) => raster === base[index]);
+                if (unchanged) {
+                    // All cache hits, same grid: keep the ARRAY IDENTITY so an untouched
+                    // page can still return its previous object below. These ARE the
+                    // mounted objects — the run took a second reference on each and this
+                    // gives that one back, so the refcount never reaches zero and the
+                    // fence is not consulted either way.
+                    releaseMounted.push(...freshBase);
+                }
+                else if (fullyCovers(freshBase, base)) {
+                    releaseMounted.push(...base);
+                    base = Object.freeze(freshBase);
+                }
+                else {
+                    // The anti-blank invariant, restated for a set: never EMPTIED once
+                    // populated — and, one step stronger, never NARROWED. A fresh grid that
+                    // lost a piece (budget refusal, backend error) would leave a hole in the
+                    // one layer guaranteed to be drawable, so it is dropped and the covering
+                    // set we already have stands. Those keys are already in `missing`, so
+                    // this epoch reports `settling` and the next one re-plans them.
+                    releaseFresh.push(...freshBase);
+                }
+            }
+            let detail = previous.detail;
+            let retiring = EMPTY_RASTERS;
+            const rotating = freshDetail.length > 0 ||
+                // Planned but deliberately detail-free (zoomed back out), or the page
+                // has left the plan's window entirely: either way the old detail is dead
+                // weight. A plan that WANTED detail but produced none keeps what it has
+                // rather than blanking.
+                (plannedPages.has(previous.page) &&
+                    !detailPlannedPages.has(previous.page)) ||
+                !plannedPages.has(previous.page);
+            if (rotating) {
+                detail =
+                    freshDetail.length > 0 ? Object.freeze(freshDetail) : EMPTY_RASTERS;
+                if (policy.retainPreviousDetail ||
+                    !fullyCovers(detail, previous.detail)) {
+                    retiring = previous.detail;
+                }
+                else {
+                    releaseMounted.push(...previous.detail);
+                }
+            }
+            // A page far outside the window loses its base to the cache. "Base is
+            // never emptied" is a promise about the pages you are LOOKING at; holding
+            // 500 of them is how a long document runs out of memory.
+            const nearWindow = Array.from(plannedPages).some(p => Math.abs(p - previous.page) <= BASE_PAGE_RADIUS);
+            if (base.length > 0 && !nearWindow) {
+                releaseMounted.push(...base);
+                base = EMPTY_RASTERS;
+            }
+            if (base === previous.base &&
+                detail === previous.detail &&
+                retiring === previous.retiring &&
+                previous.retiring.length === 0) {
+                return previous; // untouched page keeps its object; only content identity matters
+            }
+            return Object.freeze({
+                page: previous.page,
+                pageRect: previous.pageRect,
+                base,
+                detail,
+                retiring,
+            });
+        });
+        const committedKeys = new Set(produced.map(raster => raster.key));
+        const settling = missing.length > 0 ||
+            queued !== null ||
+            state.plan.items.some(i => !committedKeys.has(i.key));
+        content = Object.freeze({ pages: Object.freeze(nextPages), epoch, settling });
+        // WITH THE EPOCH, and that is the fix for the disposed-SkImage draw. These
+        // rasters have just left `content`, but `content` is not what draws — the
+        // renderer is, and it has not been told yet (`notify` is three lines below,
+        // and React commits later still). The epoch is what lets the cache hold them
+        // until the renderer has demonstrably moved on.
+        for (const raster of releaseMounted)
+            cache.release(raster.key, epoch);
+        // Untagged: never mounted, so nothing can be drawing them. See the split.
+        for (const raster of releaseFresh)
+            cache.release(raster.key);
+        cache.setLiveWindow(Array.from(plannedPages));
+        // Piggybacked on the commit that mounts this epoch — never its own timer —
+        // and fenced ON that epoch, so what it frees is the PREVIOUS commit's
+        // leavings rather than this one's. Flushing what we released above is a delay
+        // of zero, which is what drew corpses.
+        cache.flushRetired(epoch);
+        /**
+         * WHAT THIS EPOCH COVERS IS WHAT IT PRODUCED, never what it planned.
+         *
+         * The plan's `coveredDocRect` is an intention. Recording it would have the
+         * epoch claim coverage of a piece that errored or was refused by the budget,
+         * and the coverage predicate would then never fire for that hole — it would
+         * sit there until some unrelated predicate happened to trigger. Tiling makes
+         * that near-certain rather than rare: there are 8-32 chances per epoch now.
+         *
+         * There is deliberately no retry timer, and there still is not one: a hole
+         * re-fires 'coverage' on the next EVALUATION — the predicate is an exact
+         * union test over each page's visible part, so an INTERIOR hole fires too
+         * (see `EpochState.pageRects` and `coveredRects`) — and the re-plan asks for
+         * the SAME key, because keys are derived from geometry and not from the
+         * epoch, so every piece that landed is a cache hit and only the hole costs a
+         * render.
+         *
+         * WHAT CHANGED: that next evaluation used to be somebody else's problem.
+         * Every entry point is host-driven, and a host at rest produces none — so on
+         * a stationary viewport the hole was permanent and `settling: true` was the
+         * controller announcing it. `scheduleRepair` arms one re-evaluation when this
+         * run ends with `missing` non-empty. `missing` still feeds `settling`, which
+         * remains a report and not a mechanism.
+         */
+        const coveredRects = [];
+        if (state.plan.baseCoveredDocRect !== null)
+            coveredRects.push(state.plan.baseCoveredDocRect);
+        for (const raster of produced)
+            if (raster.role === 'detail')
+                coveredRects.push(raster.docRect);
+        epochState = {
+            detailScale: state.plan.detailScale,
+            pageRects: plannedPageRects(state.plan),
+            coveredRects,
+            committedAtMs: now(),
+        };
+        rasterViewport = state.viewport;
+        committedSignature = state.signature;
+        plannedSignature = state.signature;
+        emit({
+            type: 'epoch',
+            epoch,
+            items: produced.length,
+            reason: state.reason,
+            missing: missing.length,
+        });
+        notify();
+    }
+    /* ---------------------------------------------------------------- *
+     * Public surface
+     * ---------------------------------------------------------------- */
+    return {
+        hint(viewport) {
+            if (destroyed)
+                return;
+            // Still worth recording under suppression: an in-flight result is judged
+            // against the newest viewport, gesture or no gesture.
+            latestViewport = viewport;
+            if (suppressed) {
+                emit({ type: 'skip', reason: 'suppressed' });
+                return;
+            }
+            const zoomed = lastSeenScale !== null && viewport.scale !== lastSeenScale;
+            lastSeenScale = viewport.scale;
+            const signature = signatureOf(buildPlan(viewport));
+            if (signature === plannedSignature) {
+                // A no-op, INCLUDING the timer: restarting it would let a stream of
+                // identical hints postpone a raster forever. Any state change here costs
+                // a full re-record of the consumer's entire scene.
+                emit({ type: 'skip', reason: 'identical-plan' });
+                return;
+            }
+            plannedSignature = signature;
+            // maxStaleMs: under continued input the quiet timer never gets to fire, so
+            // force one evaluation through.
+            if (epochState !== null &&
+                now() - epochState.committedAtMs >= policy.maxStaleMs) {
+                evaluate(viewport, true);
+                return;
+            }
+            arm(zoomed ? policy.quietZoomMs : policy.quietPanMs);
+        },
+        settle(viewport) {
+            if (destroyed)
+                return;
+            // Deliberately NOT gated on `suppressed`: settle is the discrete path, and
+            // a host that forgets resume() must still get its raster.
+            cancelPending();
+            lastSeenScale = viewport.scale;
+            evaluate(viewport, false);
+        },
+        suppress() {
+            suppressed = true;
+            cancelPending();
+        },
+        resume() {
+            suppressed = false;
+        },
+        getContent() {
+            return content;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        notePresented(reportedEpoch) {
+            if (destroyed)
+                return;
+            if (!Number.isFinite(reportedEpoch))
+                return;
+            // CLAMPED to what has actually been published. A host that reports an epoch
+            // we never committed would advance the fence past reality, which is the one
+            // way this seam could reintroduce the bug it exists to close.
+            cache.notePresented?.(Math.min(reportedEpoch, epoch));
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            cancelPending();
+            queued = null;
+            inFlight?.abort.abort();
+            inFlight = null;
+            unsubscribeEvictions?.();
+            // No page is live any more, so nothing is protected from the flush below.
+            // (The cache assumes one controller; a shared one would need a scoped
+            // window instead.)
+            cache.setLiveWindow([]);
+            for (const page of content.pages) {
+                for (const raster of page.base)
+                    cache.release(raster.key);
+                for (const raster of page.detail)
+                    cache.release(raster.key);
+                for (const raster of page.retiring)
+                    cache.release(raster.key);
+            }
+            content = Object.freeze({
+                pages: Object.freeze(content.pages.map(page => Object.freeze({
+                    page: page.page,
+                    pageRect: page.pageRect,
+                    base: EMPTY_RASTERS,
+                    detail: EMPTY_RASTERS,
+                    retiring: EMPTY_RASTERS,
+                }))),
+                epoch,
+                settling: false,
+            });
+            // Safe here, and unfenced on purpose: content no longer references
+            // anything, so nothing freed is still mounted.
+            cache.flushRetired();
+            listeners.clear();
+        },
+    };
+}