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

package/dist/planner.js

@@ -0,0 +1,530 @@
+/**
+ * The two pure decisions: WHAT to raster (`planRasters`) and WHEN
+ * (`shouldReraster`). No React, no Skia, no clock, no async — `nowMs` is
+ * passed in so the cadence is testable without fake timers.
+ */
+import { fitScale, inflateRect, isEmptyRect, rectContains, rectIntersection, rectUnion, rectsCover, rectsEqual, scaleToPixels, snapRectToDevicePixels, } from './geometry.js';
+/**
+ * Device pixels adjacent detail pieces share along an interior seam. Two is
+ * enough: the seam is already covered by the outward snap on both sides, and
+ * this only has to absorb the half-pixel a bilinear sample reaches across.
+ */
+const PIECE_OVERLAP_PX = 2;
+/**
+ * Headroom subtracted from the piece cap when choosing a piece count.
+ * A piece is grown after it is sized — by the overlap on its interior edges
+ * and by up to a pixel of outward snapping on each edge — so dividing by the
+ * raw limit can land a piece one pixel over it, which is not a soft failure
+ * when the binding cap is the texture limit: the upload fails and the piece
+ * draws nothing.
+ */
+const PIECE_SLACK_PX = 8;
+/** Below this much travel on an axis, treat it as no travel at all. */
+const MOTION_EPSILON_PX = 0.5;
+/**
+ * Relative slack when comparing two scales for "close enough to equal".
+ * Scales arrive quantized to 6 significant digits, so anything tighter than
+ * this compares float noise.
+ */
+const SCALE_EPSILON = 1e-6;
+/**
+ * Six significant digits, RELATIVE. An absolute grid cannot work across the
+ * range in play: 1e-4 is 10% of a plotter sheet's fit scale and invisible at
+ * scale 8. The point is only to stop the same viewport, derived twice through
+ * different float paths, from producing two keys and re-rendering identical
+ * bytes.
+ */
+function quantizeScale(scale) {
+    if (!(scale > 0))
+        return 0;
+    return Number(scale.toPrecision(6));
+}
+function quantize(v) {
+    return Math.round(v * 1000) / 1000;
+}
+function rectKey(r) {
+    return (`${quantize(r.x)},${quantize(r.y)}` +
+        `,${quantize(r.width)},${quantize(r.height)}`);
+}
+/**
+ * Stable and collision-free: page, role, rect and scale together determine the
+ * BYTES, so two epochs that want the same pixels produce the same key and the
+ * second is a cache hit. The epoch number is deliberately absent — including
+ * it would make every key unique and defeat the cache entirely.
+ */
+function itemKey(page, role, rect, scale) {
+    return `p${page}|${role}|${rectKey(rect)}|s${quantizeScale(scale)}`;
+}
+/**
+ * Ceiling on the pieces one axis may be divided into.
+ *
+ * The two caps below are consumer-settable numbers, and `ceil(extent / cap)` has
+ * no upper bound: a cap of 1 asks for 1755 columns and 3798 rows of a phone's
+ * detail target, which is 6.6 MILLION plan items and an out-of-memory crash on
+ * the settle path. 32 is far past anything useful — a 24 MP epoch at a 512 px cap
+ * needs 10 per axis — so a legitimate policy never reaches it, and a nonsense one
+ * degrades to a slow epoch instead of taking the process down.
+ *
+ * A piece may therefore exceed `maxPieceDimension`, which is a MEMORY policy and
+ * soft. It may never exceed `maxTextureDimension`: see `axisPieceCount`.
+ */
+const MAX_PIECES_PER_AXIS = 32;
+/**
+ * The largest pixel dimension a piece may be sized to, on either axis.
+ *
+ * TWO CAPS, DELIBERATELY NOT ONE. `maxTextureDimension` is a HARDWARE ceiling —
+ * exceed it and the texture upload fails and the piece draws nothing.
+ * `maxPieceDimension` is a MEMORY policy: nothing breaks when a piece is bigger,
+ * but the whole-flow transient peak scales with the largest single raster in
+ * flight (platform bitmap + transport + `Uint8Array` + `SkData` all live at
+ * once), so bounding one piece bounds the peak. The effective cap is the smaller
+ * of the two, less the slack every piece is grown by after it is sized.
+ */
+function usablePieceDimension(policy) {
+    const cap = Math.min(policy.maxPieceDimension, policy.maxTextureDimension);
+    return Math.max(1, cap - PIECE_SLACK_PX);
+}
+/** The same, for the hardware ceiling alone — the count that MUST be honoured. */
+function usableTextureDimension(policy) {
+    return Math.max(1, policy.maxTextureDimension - PIECE_SLACK_PX);
+}
+/**
+ * How many pieces one axis of `extent` device pixels is divided into.
+ *
+ * The hardware count wins outright: past `maxTextureDimension` the upload fails
+ * and the piece draws NOTHING, so `MAX_PIECES_PER_AXIS` may not clamp below it.
+ * The memory count is what the clamp applies to, because exceeding
+ * `maxPieceDimension` only costs a bigger transient.
+ */
+function axisPieceCount(extent, policy) {
+    const required = Math.max(1, Math.ceil(extent / usableTextureDimension(policy)));
+    const wanted = Math.max(1, Math.ceil(extent / usablePieceDimension(policy)));
+    const count = Math.max(required, Math.min(wanted, MAX_PIECES_PER_AXIS));
+    // A non-finite policy field (an undefined `maxPieceDimension` from a hand-built
+    // RasterPolicy, say) makes every count above NaN, and `col < NaN` is false — so
+    // the grid loop would emit NOTHING and the page would be blank. Degrade to one
+    // whole piece instead: that is what this code did before it could tile, and a
+    // blank page is the one outcome the package never accepts.
+    return Number.isFinite(count) ? count : 1;
+}
+/**
+ * Bounding rect of a covered set, or null for a set that covers nothing.
+ *
+ * The BOUND is what the look-ahead predicate needs — padding ahead of the motion
+ * against padding behind it is a question about one rect. Coverage itself is
+ * asked of the SET (`rectsCover`), because a bound cannot express a hole.
+ */
+function boundsOf(rects) {
+    let bounds = null;
+    for (const rect of rects) {
+        if (isEmptyRect(rect))
+            continue;
+        bounds = bounds === null ? { ...rect } : rectUnion(bounds, rect);
+    }
+    return bounds;
+}
+/**
+ * `pages` and `pageRects` are parallel arrays; `visiblePages` holds page
+ * indices. They normally coincide, but a host that windows its page array does
+ * not have that luxury, so fall back to a search on `.index`.
+ */
+function positionOf(pages, index) {
+    const direct = pages[index];
+    if (direct && direct.index === index)
+        return index;
+    return pages.findIndex(p => p.index === index);
+}
+export function planRasters(args) {
+    const { viewport, pages, pageRects, visiblePages, policy } = args;
+    const items = [];
+    const seen = new Set();
+    const push = (item) => {
+        if (seen.has(item.key))
+            return;
+        seen.add(item.key);
+        items.push(item);
+    };
+    // The host never states the viewport in pixels. It is exactly the visible
+    // rect at the current scale, and deriving it here keeps the two consistent
+    // by construction — a separately-supplied size could disagree, and the
+    // disagreement would show up as a base raster at the wrong fit scale.
+    const viewportPixels = {
+        width: viewport.visibleDocRect.width * viewport.scale,
+        height: viewport.visibleDocRect.height * viewport.scale,
+    };
+    const inflated = inflateRect(viewport.visibleDocRect, policy.detailOverflow, policy.detailOverflow);
+    const targets = [];
+    /** Base scale actually planned per page, for the base-is-enough test below. */
+    const baseScaleByPage = new Map();
+    for (const pageIndex of visiblePages) {
+        const position = positionOf(pages, pageIndex);
+        if (position < 0)
+            continue;
+        // PageGeometry is read only to confirm the page exists: its width/height
+        // are ALREADY post-rotation, so a /Rotate 90 page is simply a landscape
+        // page here and needs no special handling anywhere below.
+        const geometry = pages[position];
+        const pageRect = pageRects[position];
+        if (!geometry || !pageRect || isEmptyRect(pageRect))
+            continue;
+        // Emitted unconditionally. "Needs one" is decided downstream by key
+        // identity: a base already in the cache has this exact key, so it is a
+        // cache hit and never re-renders. That is the whole reason the key is
+        // derived from geometry rather than from the epoch.
+        const baseScale = planBasePieces(pageIndex, pageRect, viewportPixels, policy, push);
+        if (baseScale > 0)
+            baseScaleByPage.set(pageIndex, baseScale);
+        const target = rectIntersection(inflated, pageRect);
+        if (target && !isEmptyRect(target)) {
+            targets.push({ page: pageIndex, rect: target });
+        }
+    }
+    const detailScale = resolveDetailScale(targets, viewport.scale, policy);
+    /**
+     * Rects that are adequately covered by a base raster alone.
+     *
+     * A page whose base is already at least as dense as the detail would be gets
+     * NO detail: it would be the same pixels at the same resolution, for double
+     * the raster time and double the resident bytes. At fit zoom that is every
+     * page, which on a continuous layout is the difference between one whole-page
+     * raster per page and two.
+     *
+     * These rects still count as COVERED, and that is load-bearing rather than
+     * bookkeeping: `shouldReraster` treats an empty covered set as "nothing is
+     * on screen" and fires 'coverage' unconditionally, so reporting nothing here
+     * would make every settle at fit zoom dispatch an all-cache-hits run and
+     * commit a redundant epoch — a full re-record of the consumer's scene for no
+     * new pixels. They are reported to the controller as
+     * `RasterPlan.baseCoveredDocRect`, separately from the detail items, because
+     * the controller records coverage from what it PRODUCED and no produced raster
+     * accounts for this half.
+     */
+    let baseCoveredRect = null;
+    let sufficientBaseScale = Number.POSITIVE_INFINITY;
+    if (detailScale > 0) {
+        for (const target of targets) {
+            const baseScale = baseScaleByPage.get(target.page) ?? 0;
+            if (baseScale > 0 && detailScale <= baseScale * (1 + SCALE_EPSILON)) {
+                baseCoveredRect =
+                    baseCoveredRect === null
+                        ? { ...target.rect }
+                        : rectUnion(baseCoveredRect, target.rect);
+                sufficientBaseScale = Math.min(sufficientBaseScale, baseScale);
+                continue;
+            }
+            planDetailPieces(target.page, target.rect, detailScale, policy, push);
+        }
+    }
+    const coveredRects = baseCoveredRect === null ? [] : [{ ...baseCoveredRect }];
+    let emittedDetail = false;
+    for (const item of items) {
+        if (item.role !== 'detail')
+            continue;
+        emittedDetail = true;
+        coveredRects.push(item.docRect);
+    }
+    const coveredDocRect = boundsOf(coveredRects);
+    /**
+     * The scale the sharpness predicate compares against must describe what is
+     * actually ON SCREEN. When every page fell back to its base, that is the base
+     * scale — so zooming in past the band still fires and plans real detail.
+     */
+    const effectiveDetailScale = emittedDetail
+        ? detailScale
+        : Number.isFinite(sufficientBaseScale)
+            ? sufficientBaseScale
+            : 0;
+    return {
+        items,
+        detailScale: effectiveDetailScale,
+        coveredDocRect,
+        baseCoveredDocRect: baseCoveredRect,
+    };
+}
+/**
+ * The whole page at fit scale, as a grid of pieces whose union is EXACTLY the
+ * page rect. Returns the scale the pieces were planned at, or 0 for a page that
+ * cannot be based at all.
+ *
+ * WHY THE BASE IS TILED. It is the biggest single raster the package ever asks
+ * for: the base is allowed up to `baseMaxPixels` (4 MP = 15.26 MiB of pixels),
+ * so an un-tiled base's transient peak is roughly 4.8x that of a whole
+ * 1024-tiled detail epoch — the base was the largest remaining hole after detail
+ * was tiled. It also removes a latent blank-page bug: `baseMaxPixels` caps AREA,
+ * so a long thin sheet could clear it while overrunning `maxTextureDimension` on
+ * one axis, and that piece silently draws nothing.
+ *
+ * THE GRID IS CUT ON THE DEVICE-PIXEL GRID, not in doc space, which is why this
+ * does not use `snapRectToDevicePixels` the way the detail path does. Interior
+ * boundaries are whole pixel columns/rows and are converted back to doc space by
+ * dividing by `scale`; the OUTER edges are pinned to the page rect itself. So
+ * every piece's declared pixel size is exactly `round(docRect * scale)` — what a
+ * backend allocates — with no snapping and no drift, the union is the page rect
+ * to the last bit, and a 1x1 grid degenerates to precisely the single whole-page
+ * item this replaced. Snapping instead would push the outer edges OUTSIDE the
+ * page rect, and the base's rect is the one rect that must equal `pageRect`.
+ */
+function planBasePieces(page, pageRect, viewportPixels, policy, push) {
+    const fit = fitScale({ width: pageRect.width, height: pageRect.height }, viewportPixels);
+    if (!(fit > 0))
+        return 0;
+    let scale = fit * policy.baseQuality;
+    const area = pageRect.width * pageRect.height;
+    if (area * scale * scale > policy.baseMaxPixels) {
+        scale = Math.sqrt(policy.baseMaxPixels / area);
+    }
+    scale = quantizeScale(scale);
+    if (!(scale > 0))
+        return 0;
+    // Pixels are ROUNDED, not snapped: the rect is the page rect exactly (there is
+    // nothing outside it to expand into), and rounding is what makes the size —
+    // and therefore the key — immune to the last-bit drift in deriving the same
+    // fit scale twice.
+    const total = {
+        width: Math.max(1, Math.round(pageRect.width * scale)),
+        height: Math.max(1, Math.round(pageRect.height * scale)),
+    };
+    const cols = axisPieceCount(total.width, policy);
+    const rows = axisPieceCount(total.height, policy);
+    const outerRight = pageRect.x + pageRect.width;
+    const outerBottom = pageRect.y + pageRect.height;
+    /** Interior cut, in whole device pixels, with the overlap already applied. */
+    const cut = (index, count, extent, grow) => Math.min(extent, Math.max(0, Math.floor((index * extent) / count) + grow));
+    for (let row = 0; row < rows; row++) {
+        const py0 = row === 0 ? 0 : cut(row, rows, total.height, -PIECE_OVERLAP_PX);
+        const py1 = row === rows - 1
+            ? total.height
+            : cut(row + 1, rows, total.height, PIECE_OVERLAP_PX);
+        if (py1 - py0 < 1)
+            continue;
+        for (let col = 0; col < cols; col++) {
+            const px0 = col === 0 ? 0 : cut(col, cols, total.width, -PIECE_OVERLAP_PX);
+            const px1 = col === cols - 1
+                ? total.width
+                : cut(col + 1, cols, total.width, PIECE_OVERLAP_PX);
+            if (px1 - px0 < 1)
+                continue;
+            const left = col === 0 ? pageRect.x : pageRect.x + px0 / scale;
+            const right = col === cols - 1 ? outerRight : pageRect.x + px1 / scale;
+            const top = row === 0 ? pageRect.y : pageRect.y + py0 / scale;
+            const bottom = row === rows - 1 ? outerBottom : pageRect.y + py1 / scale;
+            const docRect = {
+                x: left,
+                y: top,
+                width: right - left,
+                height: bottom - top,
+            };
+            push({
+                key: itemKey(page, 'base', docRect, scale),
+                page,
+                role: 'base',
+                docRect,
+                scale,
+                pixels: { width: px1 - px0, height: py1 - py0 },
+            });
+        }
+    }
+    return scale;
+}
+/**
+ * One scale for the whole detail set, reduced until the largest single target
+ * fits `maxRasterPixels`.
+ *
+ * Reducing SCALE rather than cropping the rect is the deliberate choice: a
+ * crop leaves part of the screen with nothing but the base layer under it,
+ * which reads as a hard seam of blur, whereas a uniformly softer detail layer
+ * reads as "not sharpened yet". Clamped BEFORE splitting, so the ceiling
+ * bounds the epoch's total cost and not merely one piece of it.
+ */
+function resolveDetailScale(targets, requested, policy) {
+    let scale = quantizeScale(requested);
+    if (!(scale > 0))
+        return 0;
+    for (const target of targets) {
+        // Re-measured against the running scale, so several large pages compound
+        // correctly instead of each computing a factor from the original.
+        const pixels = scaleToPixels(target.rect, scale);
+        const area = pixels.width * pixels.height;
+        if (area > policy.maxRasterPixels) {
+            scale = quantizeScale(scale * Math.sqrt(policy.maxRasterPixels / area));
+        }
+    }
+    return scale;
+}
+/**
+ * Split a target into the coarsest grid that keeps every piece inside the piece
+ * cap — 1x1, 2x1, 1x2, 2x2, NxM. Pieces have no identity and are never reused
+ * across epochs; they exist because a single texture cannot be arbitrarily large
+ * (`maxTextureDimension`) and because one oversized raster in flight dominates
+ * the whole-flow memory peak (`maxPieceDimension`).
+ */
+function planDetailPieces(page, rect, scale, policy, push) {
+    const pixels = scaleToPixels(rect, scale);
+    const cols = axisPieceCount(pixels.width, policy);
+    const rows = axisPieceCount(pixels.height, policy);
+    const overlap = PIECE_OVERLAP_PX / scale;
+    const colWidth = rect.width / cols;
+    const rowHeight = rect.height / rows;
+    const outerRight = rect.x + rect.width;
+    const outerBottom = rect.y + rect.height;
+    for (let row = 0; row < rows; row++) {
+        for (let col = 0; col < cols; col++) {
+            // Outer edges are pinned to the target's own edges rather than computed
+            // from col*width, so accumulated float error cannot leave a sliver of
+            // the requested rect uncovered. Interior edges carry the overlap.
+            const left = col === 0 ? rect.x : rect.x + col * colWidth - overlap;
+            const right = col === cols - 1 ? outerRight : rect.x + (col + 1) * colWidth + overlap;
+            const top = row === 0 ? rect.y : rect.y + row * rowHeight - overlap;
+            const bottom = row === rows - 1
+                ? outerBottom
+                : rect.y + (row + 1) * rowHeight + overlap;
+            const snapped = snapRectToDevicePixels({ x: left, y: top, width: right - left, height: bottom - top }, scale);
+            if (snapped.pixels.width < 1 || snapped.pixels.height < 1)
+                continue;
+            push({
+                key: itemKey(page, 'detail', snapped.docRect, scale),
+                page,
+                role: 'detail',
+                docRect: snapped.docRect,
+                scale,
+                pixels: snapped.pixels,
+            });
+        }
+    }
+}
+/* ------------------------------------------------------------------ *
+ * When
+ * ------------------------------------------------------------------ */
+/**
+ * Evaluate the re-raster predicates. Called at settle (and by the quiet timer
+ * on the continuous path), never per frame.
+ *
+ * When `reraster` is false, `reason` names the predicate that WOULD have fired
+ * had `minEpochIntervalMs` not blocked it — so the caller can log a meaningful
+ * skip — and is `'stale'` as a neutral filler when nothing fired at all.
+ * Callers must branch on `reraster`, never on `reason` alone.
+ *
+ * `'layout'` is never returned: a layout change is not visible from a
+ * viewport snapshot, and the owner of the layout must force the epoch itself.
+ */
+export function shouldReraster(args) {
+    const { next, previous, epoch, policy, nowMs } = args;
+    // Nothing on screen yet. The floor does not apply: it exists to stop a
+    // raster storm between epochs, and there is no previous epoch to space from.
+    if (epoch === null)
+        return { reraster: true, reason: 'initial' };
+    const candidate = evaluate(next, previous, epoch, policy, nowMs);
+    if (candidate === null)
+        return { reraster: false, reason: 'stale' };
+    if (nowMs - epoch.committedAtMs < policy.minEpochIntervalMs) {
+        return { reraster: false, reason: candidate };
+    }
+    return { reraster: true, reason: candidate };
+}
+function evaluate(next, previous, epoch, policy, nowMs) {
+    const covered = boundsOf(epoch.coveredRects);
+    // COVERAGE. Nothing covered at all means nothing is on screen: fire, whatever
+    // else is true.
+    if (covered === null)
+        return 'coverage';
+    const tolerance = next.scale > 0 ? 0.5 / next.scale : 0;
+    if (coverageFallsShort(next.visibleDocRect, epoch, tolerance)) {
+        return 'coverage';
+    }
+    // SHARPNESS, measured against the LAST RASTER's scale — not the scale the
+    // gesture began at. Comparing against gesture start makes a zoom out and
+    // back fire when nothing actually changed.
+    if (epoch.detailScale > 0) {
+        const ratio = next.scale / epoch.detailScale;
+        if (ratio > policy.sharpnessBand || ratio < 1 / policy.sharpnessBand) {
+            return 'sharpness';
+        }
+    }
+    // DIRECTIONAL LOOK-AHEAD. Needs two snapshots to know which way the content
+    // is travelling; with only one, skip the predicate rather than guess a
+    // direction and pre-raster the wrong side.
+    if (previous !== null && looksAhead(next, previous, covered, policy)) {
+        return 'look-ahead';
+    }
+    // STALE. Forces one raster under input that never goes quiet. Gated on the
+    // viewport actually having moved: without that it fires forever on a
+    // stationary view, since elapsed only grows.
+    const moved = previous !== null && !viewportsEqual(next, previous);
+    if (moved && nowMs - epoch.committedAtMs >= policy.maxStaleMs)
+        return 'stale';
+    return null;
+}
+/**
+ * Is anything this epoch was responsible for showing not covered by it?
+ *
+ * TWO QUESTIONS, and both are load-bearing.
+ *
+ * 1. AM I LOOKING SOMEWHERE THE EPOCH NEVER PLANNED? Containment of the visible
+ *    rect in the bounds of the epoch's page rects. Asymmetric on purpose, as the
+ *    old covered-rect containment test was: zooming IN shrinks the visible rect
+ *    inside them and does not fire, while pinching OUT or scrolling onto the next
+ *    page escapes them and always does.
+ *
+ *    It can still fire persistently when the viewport is LARGER than the pages on
+ *    screen (letterboxed at fit zoom, or the margin beside a narrow page in a
+ *    centred layout). That is unchanged and intended: the re-plan is identical
+ *    and the identical-plan check downstream absorbs it without a raster.
+ *
+ * 2. IS ANY PAGE AREA ON SCREEN UNPAINTED? An exact union test of the covered SET
+ *    over each page's visible part. This is what a bounding rect cannot answer: a
+ *    tiled epoch that lost a piece — a backend error, a budget refusal, 8-32
+ *    chances per epoch — keeps its bounds intact, since removing any one cell of
+ *    a 2x2 grid leaves the other three spanning it. A bounds test therefore
+ *    reports full coverage over a hole and the hole is never re-planned; this
+ *    fires on the next evaluation, and the re-plan asks for the same key because
+ *    keys are derived from geometry.
+ *
+ * PER PAGE, NOT OVER THE WHOLE VISIBLE RECT, and that is not a detail: most of
+ * the doc plane is not page. See `EpochState.pageRects`.
+ */
+function coverageFallsShort(visible, epoch, tolerance) {
+    const responsible = boundsOf(epoch.pageRects);
+    if (responsible === null)
+        return true;
+    if (!rectContains(responsible, visible, tolerance))
+        return true;
+    for (const pageRect of epoch.pageRects) {
+        const onScreen = rectIntersection(pageRect, visible);
+        if (onScreen === null || isEmptyRect(onScreen))
+            continue;
+        if (!rectsCover(epoch.coveredRects, onScreen, tolerance))
+            return true;
+    }
+    return false;
+}
+function looksAhead(next, previous, covered, policy) {
+    const now = next.visibleDocRect;
+    const before = previous.visibleDocRect;
+    const dx = now.x + now.width / 2 - (before.x + before.width / 2);
+    const dy = now.y + now.height / 2 - (before.y + before.height / 2);
+    const epsilon = next.scale > 0 ? MOTION_EPSILON_PX / next.scale : MOTION_EPSILON_PX;
+    return (axisLooksAhead(dx, now.x, now.x + now.width, covered.x, covered.x + covered.width, epsilon, policy.movementThreshold) ||
+        axisLooksAhead(dy, now.y, now.y + now.height, covered.y, covered.y + covered.height, epsilon, policy.movementThreshold));
+}
+/**
+ * Fire when the padding left AHEAD of the motion drops below `threshold` times
+ * the padding already consumed BEHIND it. Equivalently: total padding over
+ * remaining padding exceeds (1 + t) / t — 3x at pdf.js's 0.5.
+ */
+function axisLooksAhead(delta, visibleMin, visibleMax, coveredMin, coveredMax, epsilon, threshold) {
+    if (Math.abs(delta) <= epsilon)
+        return false;
+    const forward = delta > 0;
+    const ahead = forward ? coveredMax - visibleMax : visibleMin - coveredMin;
+    const behind = forward ? visibleMin - coveredMin : coveredMax - visibleMax;
+    // No padding consumed behind means the view has not travelled far enough for
+    // the ratio to mean anything (and if it is negative, the view is already
+    // outside the covered rect, which is coverage's call, not ours).
+    if (!(behind > 0))
+        return false;
+    return ahead < threshold * behind;
+}
+function viewportsEqual(a, b) {
+    return (Math.abs(a.scale - b.scale) <= 1e-9 &&
+        rectsEqual(a.visibleDocRect, b.visibleDocRect));
+}

package/dist/policy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The cadence constants, in one place, each with the reasoning that produced
+ * it. None of these are measured on this codebase yet — where a value is a
+ * placeholder for a measurement, the comment says so out loud.
+ */
+import type { RasterPolicy } from './types.js';
+export declare const DEFAULT_POLICY: RasterPolicy;
+/**
+ * Merge a partial override over the defaults. An explicitly-`undefined` field
+ * is IGNORED rather than allowed to erase a default — `{quietPanMs: maybe}`
+ * with an unset `maybe` is the common way a host would otherwise nuke a
+ * constant and get a zero-delay raster storm.
+ */
+export declare function resolvePolicy(partial?: Partial<RasterPolicy>): RasterPolicy;