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

package/dist/layout.js

@@ -0,0 +1,152 @@
+/**
+ * Page layouts: pure functions from page sizes to doc-space rects.
+ *
+ * A layout describes where pages SIT, and says nothing about what is visible
+ * or what is rastered — it returns a rect for every page, always, so the host
+ * can hit-test and scroll to a page that has never been rendered.
+ *
+ * Each export is a factory so the tuning parameter (`gap`) is captured once
+ * and the resulting `PdfPageLayout` stays referentially stable in a host that
+ * memoizes on it.
+ *
+ * INVARIANT every layout upholds: a page's rect has exactly the page's own
+ * post-rotation extents. Layouts position pages; they never resize them. The
+ * planner derives raster scale from the rect, so a layout that scaled a page
+ * would silently rescale its bitmap.
+ */
+import { isEmptyRect, rectIntersects } from './geometry.js';
+/**
+ * Every page at the origin, stacked on top of each other.
+ *
+ * Overlap is the point: in a paged viewer, doc space contains ONE page and the
+ * host swaps which page index it draws. Page 4 having the same rect as page 0
+ * is what lets the host page forward without translating its world transform.
+ *
+ * PAIR IT WITH A ONE-PAGE SELECTION — `usePdfLayer({layout: singlePage(),
+ * pages: [n]})` — AND NOTHING ELSE. That is not a style preference; it is the
+ * only configuration in which a stacked layout is correct, and the reason is
+ * that "which pages may hold rasters" is the only thing standing between this
+ * layout and every page in the document:
+ *
+ *  - The raster planner decides what is on screen by intersecting the viewport
+ *    with each page rect. Here every page rect IS the viewport, so with the
+ *    on-screen selection a 400-page document plans 400 bases — measured at
+ *    exactly N times the bytes of one page in `__tests__/single-page.test.ts`.
+ *  - `PdfContentView` draws pages in index order at the rects `content` carries,
+ *    so those bases land on top of each other and the highest index wins. The
+ *    cost is not merely memory: the wrong page is on screen.
+ *
+ * With `pages: [n]` none of that can happen — no page outside the allow-list is
+ * ever rastered, so no page outside it can ever be drawn. `usePdfLayer` warns in
+ * `__DEV__` when it is handed a stacked layout with a selection that admits more
+ * than one page, and `hasOverlappingPages` below is the predicate it uses.
+ */
+export function singlePage() {
+    return pages => pages.map(p => ({ x: 0, y: 0, width: p.width, height: p.height }));
+}
+/**
+ * Does this layout put two pages on top of each other?
+ *
+ * Answered about the RECTS a layout produced for a specific document, never
+ * about the layout function, because it is a property of both: `singlePage()`
+ * over a one-page document stacks nothing, and a bespoke host layout can stack
+ * without being `singlePage()`.
+ *
+ * Overlap is STRICT — `rectIntersects` uses `<`, so a zero-gap continuous layout,
+ * where consecutive pages share an edge exactly, is not a stack. Empty rects are
+ * skipped: a layout that produced two zero-size rects at the same origin has a
+ * different problem than stacking, and reporting this one would send the reader
+ * to the wrong place.
+ *
+ * O(n^2) with an early exit, evaluated once per layout/document change and only
+ * behind a `__DEV__` guard at its one call site. Do not put it on a per-frame
+ * path.
+ */
+export function hasOverlappingPages(rects) {
+    for (let i = 0; i < rects.length; i++) {
+        const a = rects[i];
+        if (a === undefined || isEmptyRect(a))
+            continue;
+        for (let j = i + 1; j < rects.length; j++) {
+            const b = rects[j];
+            if (b === undefined || isEmptyRect(b))
+                continue;
+            if (rectIntersects(a, b))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Pages stacked top to bottom, horizontally centred on the widest page.
+ * Centring (rather than left-aligning) matters in mixed-size documents — a
+ * letter page bound into a set of plans should not hug the left edge.
+ */
+export function continuousVertical(gap = 12) {
+    return pages => {
+        let maxWidth = 0;
+        for (const p of pages)
+            maxWidth = Math.max(maxWidth, p.width);
+        const rects = [];
+        let y = 0;
+        for (const p of pages) {
+            rects.push({
+                x: (maxWidth - p.width) / 2,
+                y,
+                width: p.width,
+                height: p.height,
+            });
+            // The cursor advances by the gap, so no trailing gap exists after the
+            // last page and the content height is exactly the union of the rects.
+            y += p.height + gap;
+        }
+        return rects;
+    };
+}
+/**
+ * Two-up: pages (0,1) form the first row, (2,3) the second, and so on. `gap`
+ * separates both the two pages of a row and consecutive rows.
+ *
+ * No cover-page special case. A viewer that wants page 0 alone can pad its own
+ * page list; baking that convention in here would make the layout lie about
+ * which page sits where for every document that does not follow it.
+ */
+export function spread(gap = 12) {
+    return pages => {
+        let maxRowWidth = 0;
+        for (let i = 0; i < pages.length; i += 2) {
+            const left = pages[i];
+            if (!left)
+                continue;
+            const right = pages[i + 1];
+            const rowWidth = left.width + (right ? gap + right.width : 0);
+            maxRowWidth = Math.max(maxRowWidth, rowWidth);
+        }
+        const rects = [];
+        let y = 0;
+        for (let i = 0; i < pages.length; i += 2) {
+            const left = pages[i];
+            if (!left)
+                continue;
+            const right = pages[i + 1];
+            const rowWidth = left.width + (right ? gap + right.width : 0);
+            const x = (maxRowWidth - rowWidth) / 2;
+            rects.push({ x, y, width: left.width, height: left.height });
+            if (right) {
+                rects.push({
+                    x: x + left.width + gap,
+                    y,
+                    width: right.width,
+                    height: right.height,
+                });
+            }
+            // Rows are top-aligned; the row's height is its taller page. Vertical
+            // centring would break the spine alignment a spread exists to show.
+            y += rowHeight(left, right) + gap;
+        }
+        return rects;
+    };
+}
+function rowHeight(left, right) {
+    return right ? Math.max(left.height, right.height) : left.height;
+}

package/dist/peer-check.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The runtime half of the skia peer-floor gate: a dev-only, once-per-process
+ * warning.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THERE IS A RUNTIME LAYER AT ALL
+ * ------------------------------------------------------------------------
+ *
+ * It is the only layer that catches a drift no install ran. `peerDependencies`
+ * and the `postinstall` check both fire at install time; `yarn add
+ * @shopify/react-native-skia@2.6.2` afterwards, or an OTA update onto a build
+ * whose bundle was made elsewhere, is invisible to both.
+ *
+ * It is also the ecosystem idiom, not an invention. Skia does exactly this for
+ * ITS peer (`sksg/Container.native.ts`): `require(peer + '/package.json')
+ * .version`, compare, then throw in `__DEV__` and `console.error` once in
+ * production. Reanimated does the same via `assertWorkletsVersion`. Measured
+ * against BOLDR's 2020 installed packages, only six have any install hook at all
+ * and NONE of them checks a peer's version — the runtime check is where this
+ * genuinely lives in React Native.
+ *
+ * ------------------------------------------------------------------------
+ * WHY IT WARNS AND DOES NOT THROW, where skia and reanimated both throw
+ * ------------------------------------------------------------------------
+ *
+ * Because their check and ours are not the same kind of claim. Skia's reanimated
+ * mismatch means the feature does not work at all — animations silently freeze —
+ * so a dev throw converts a silent failure into a loud one. Our floor is a
+ * MEMORY POLICY claim about the WEB reconciler. Below it the package still
+ * renders correctly everywhere, and on native it is measurably fine: the full
+ * suite (181 tests, the offscreen CanvasKit pixel tests included) passes against
+ * skia 2.6.2, and BOLDR ships that combination on Android today.
+ *
+ * A throw here would therefore brick a configuration that works, from inside
+ * `imageFromPixels`, surfacing as a `backend-failure` against a raster key —
+ * i.e. reported as a backend bug. Warn once, name the fix, do no harm.
+ *
+ * ------------------------------------------------------------------------
+ * THE FLOOR IS NOT RESTATED HERE
+ * ------------------------------------------------------------------------
+ *
+ * It is read out of this package's own `peerDependencies`, the same single
+ * source of truth `scripts/skia-peer-check.mjs` reads. A floor bump is one line
+ * in package.json and both layers follow.
+ */
+export type PeerCheckDeps = {
+    /** Installed peer version, or null if it could not be read. */
+    readonly peerVersion: () => string | null;
+    /** This package's declared floor range, or null. */
+    readonly floorRange: () => string | null;
+    readonly isDev: () => boolean;
+    readonly warn: (message: string) => void;
+};
+export declare const DEFAULT_PEER_CHECK_DEPS: PeerCheckDeps;
+/**
+ * Below the floor, told apart from "cannot tell".
+ *
+ * `null` means no verdict — an unparseable version, an unparseable floor, or a
+ * manifest that could not be read. It is NOT folded into `false`, because the
+ * caller's only action on `true` is to shout, and shouting on a non-answer is
+ * how a version gate loses its credibility.
+ *
+ * Prerelease handling matches `scripts/skia-peer-check.mjs` exactly, including
+ * the rule that makes it more than a tuple compare: for an EQUAL tuple a
+ * prerelease is BELOW the floor, so `2.8.0-next.1` does not clear `>=2.8.0`
+ * while `2.12.0-next.1` does. `peer-check.test.ts` pins this function, that one
+ * and the real `semver` to the same table.
+ */
+export declare const isBelowFloor: (version: string | null, floorRange: string | null) => boolean | null;
+/**
+ * Called from `ingest.ts` on the first raster, NOT at module scope.
+ *
+ * Module scope would be a side effect in a package that declares
+ * `"sideEffects": false`, which is a licence for a bundler to drop it — and a
+ * check a bundler is free to delete is not a check. First-raster is also the
+ * honest trigger: it is the first moment this package has actually asked Skia
+ * for anything, which is exactly when skia's own `createContainer` check fires.
+ *
+ * Idempotent and cheap after the first call: one boolean read.
+ */
+export declare const warnIfSkiaBelowFloor: (deps?: PeerCheckDeps) => void;
+/** Test seam. Nothing in `src/` outside the suite calls this. */
+export declare const resetPeerCheckForTests: () => void;

package/dist/peer-check.js

@@ -0,0 +1,183 @@
+/**
+ * The runtime half of the skia peer-floor gate: a dev-only, once-per-process
+ * warning.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THERE IS A RUNTIME LAYER AT ALL
+ * ------------------------------------------------------------------------
+ *
+ * It is the only layer that catches a drift no install ran. `peerDependencies`
+ * and the `postinstall` check both fire at install time; `yarn add
+ * @shopify/react-native-skia@2.6.2` afterwards, or an OTA update onto a build
+ * whose bundle was made elsewhere, is invisible to both.
+ *
+ * It is also the ecosystem idiom, not an invention. Skia does exactly this for
+ * ITS peer (`sksg/Container.native.ts`): `require(peer + '/package.json')
+ * .version`, compare, then throw in `__DEV__` and `console.error` once in
+ * production. Reanimated does the same via `assertWorkletsVersion`. Measured
+ * against BOLDR's 2020 installed packages, only six have any install hook at all
+ * and NONE of them checks a peer's version — the runtime check is where this
+ * genuinely lives in React Native.
+ *
+ * ------------------------------------------------------------------------
+ * WHY IT WARNS AND DOES NOT THROW, where skia and reanimated both throw
+ * ------------------------------------------------------------------------
+ *
+ * Because their check and ours are not the same kind of claim. Skia's reanimated
+ * mismatch means the feature does not work at all — animations silently freeze —
+ * so a dev throw converts a silent failure into a loud one. Our floor is a
+ * MEMORY POLICY claim about the WEB reconciler. Below it the package still
+ * renders correctly everywhere, and on native it is measurably fine: the full
+ * suite (181 tests, the offscreen CanvasKit pixel tests included) passes against
+ * skia 2.6.2, and BOLDR ships that combination on Android today.
+ *
+ * A throw here would therefore brick a configuration that works, from inside
+ * `imageFromPixels`, surfacing as a `backend-failure` against a raster key —
+ * i.e. reported as a backend bug. Warn once, name the fix, do no harm.
+ *
+ * ------------------------------------------------------------------------
+ * THE FLOOR IS NOT RESTATED HERE
+ * ------------------------------------------------------------------------
+ *
+ * It is read out of this package's own `peerDependencies`, the same single
+ * source of truth `scripts/skia-peer-check.mjs` reads. A floor bump is one line
+ * in package.json and both layers follow.
+ */
+/**
+ * `require`, in a try, for the same reason `rasterizer/index.native.ts` uses one:
+ * a static import would make this module unloadable somewhere it must load.
+ * Here it is worse than that — a static import of a package's `package.json`
+ * needs a JSON-module assertion that neither Metro nor the tsc config here is
+ * set up for, and a failure to read a manifest must never be worse than not
+ * knowing.
+ *
+ * `@shopify/react-native-skia` declares no `exports` field at any version in the
+ * supported range (verified 2.6.2 through 2.11.0), so the `/package.json`
+ * subpath is reachable. If that ever changes this returns null and the check
+ * goes quiet, which is the correct failure direction.
+ *
+ * MEASURED LIMIT, and it is deliberate rather than repaired. A module-scoped
+ * `require` exists under Metro (native and web) and under vitest, which is every
+ * environment this check is aimed at. It does NOT exist in `dist/peer-check.js`
+ * loaded as real ESM by node: both reads return null there and the whole check
+ * goes silent. That is the safe direction, and the alternatives are worse — an
+ * `import.meta.url` + `createRequire` fallback buys a node-ESM consumer that has
+ * no Skia canvas to protect, at the price of `import.meta` in a file Metro
+ * transpiles to CJS. The INSTALL-time layer, which is where a real gate lives,
+ * is a standalone `.mjs` and has no such constraint.
+ *
+ * THE SPECIFIER IS INLINE, and must stay that way. Metro resolves `require` at
+ * BUILD time from a static string literal; handing it a variable is not a
+ * runtime failure that this try/catch would absorb, it is a bundler error that
+ * takes the whole app down:
+ *
+ *     SyntaxError: dist/peer-check.js: Invalid call at line 71: require(specifier)
+ *
+ * That is not hypothetical — this module reaches a consuming app through
+ * `rasterizer/ingest.ts`, so the first Metro consumer hit it immediately. A
+ * parameterised helper reads as more general and is strictly less usable here;
+ * there has only ever been one specifier to read.
+ */
+const readSkiaVersion = () => {
+    try {
+        const manifest = require('@shopify/react-native-skia/package.json');
+        return typeof manifest.version === 'string' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+};
+const readOwnFloor = () => {
+    try {
+        // From `dist/peer-check.js` and from `src/peer-check.ts` alike, `..` is the
+        // package root — `rootDir: src` flattens onto `dist/`, so the depth matches
+        // in both trees and the test exercises the same path production does.
+        const manifest = require('../package.json');
+        return manifest.peerDependencies?.['@shopify/react-native-skia'] ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * `__DEV__` is a React Native global. It is undefined under node and in a plain
+ * web bundle, so it is read off `globalThis` rather than declared — and a
+ * missing `__DEV__` counts as NOT dev, so nothing in this file can ever emit in
+ * an environment it does not understand.
+ */
+const isDevDefault = () => globalThis.__DEV__ === true;
+export const DEFAULT_PEER_CHECK_DEPS = {
+    peerVersion: readSkiaVersion,
+    floorRange: readOwnFloor,
+    isDev: isDevDefault,
+    warn: message => console.warn(message),
+};
+const TUPLE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/;
+const FLOOR = /^>=\s*(\d+)\.(\d+)\.(\d+)$/;
+/**
+ * Below the floor, told apart from "cannot tell".
+ *
+ * `null` means no verdict — an unparseable version, an unparseable floor, or a
+ * manifest that could not be read. It is NOT folded into `false`, because the
+ * caller's only action on `true` is to shout, and shouting on a non-answer is
+ * how a version gate loses its credibility.
+ *
+ * Prerelease handling matches `scripts/skia-peer-check.mjs` exactly, including
+ * the rule that makes it more than a tuple compare: for an EQUAL tuple a
+ * prerelease is BELOW the floor, so `2.8.0-next.1` does not clear `>=2.8.0`
+ * while `2.12.0-next.1` does. `peer-check.test.ts` pins this function, that one
+ * and the real `semver` to the same table.
+ */
+export const isBelowFloor = (version, floorRange) => {
+    if (version === null || floorRange === null)
+        return null;
+    const v = TUPLE.exec(version.trim());
+    const f = FLOOR.exec(floorRange.trim());
+    if (v === null || f === null)
+        return null;
+    for (let i = 1; i <= 3; i++) {
+        const a = Number(v[i]);
+        const b = Number(f[i]);
+        if (a !== b)
+            return a < b;
+    }
+    return v[4] !== undefined;
+};
+const message = (found, floor) => `[@reekon-tools/react-native-pdf-canvas] @shopify/react-native-skia ` +
+    `${found} is below the required ${floor}.\n` +
+    `  On web, below 2.8.0 the RN Web reconciler leaks one CanvasKit Paint per ` +
+    `drawn tile per frame into the Emscripten heap, which never returns pages ` +
+    `to the OS. This package tiles both the base and the detail layer, so that ` +
+    `leak scales with the number of pieces on screen and its memory policy ` +
+    `cannot hold.\n` +
+    `  Fix:  yarn add @shopify/react-native-skia@^${floor.replace(/^>=\s*/, '')}` +
+    `\n  (dev-only warning, shown once)`;
+let warned = false;
+/**
+ * Called from `ingest.ts` on the first raster, NOT at module scope.
+ *
+ * Module scope would be a side effect in a package that declares
+ * `"sideEffects": false`, which is a licence for a bundler to drop it — and a
+ * check a bundler is free to delete is not a check. First-raster is also the
+ * honest trigger: it is the first moment this package has actually asked Skia
+ * for anything, which is exactly when skia's own `createContainer` check fires.
+ *
+ * Idempotent and cheap after the first call: one boolean read.
+ */
+export const warnIfSkiaBelowFloor = (deps = DEFAULT_PEER_CHECK_DEPS) => {
+    if (warned)
+        return;
+    warned = true;
+    if (!deps.isDev())
+        return;
+    const found = deps.peerVersion();
+    const floor = deps.floorRange();
+    if (isBelowFloor(found, floor) !== true)
+        return;
+    // Non-null by construction: isBelowFloor returns null unless both parsed.
+    deps.warn(message(found, floor));
+};
+/** Test seam. Nothing in `src/` outside the suite calls this. */
+export const resetPeerCheckForTests = () => {
+    warned = false;
+};

package/dist/planner.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 type { DocRect, EpochReason, EpochState, PageGeometry, RasterPlan, RasterPolicy, ViewportSnapshot } from './types.js';
+export declare function planRasters(args: {
+    viewport: ViewportSnapshot;
+    pages: readonly PageGeometry[];
+    pageRects: readonly DocRect[];
+    visiblePages: readonly number[];
+    policy: RasterPolicy;
+}): RasterPlan;
+/**
+ * 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 declare function shouldReraster(args: {
+    next: ViewportSnapshot;
+    previous: ViewportSnapshot | null;
+    epoch: EpochState | null;
+    policy: RasterPolicy;
+    nowMs: number;
+}): {
+    reraster: boolean;
+    reason: EpochReason;
+};