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

package/dist/geometry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Doc-space geometry: PDF points, y-down, origin at the page's top-left.
+ *
+ * Every function here is pure and total — no throws, no NaN propagation that
+ * survives a guard. These are the numbers that end up as a texture allocation
+ * and a draw rect, so a silent NaN here is a blank page or an OOM later.
+ */
+import type { DocRect, DocSize, PixelSize } from './types.js';
+/** The result of aligning a doc rect to the device-pixel grid. */
+export interface SnappedRect {
+    /** The rect actually covered by the bytes. NOT the rect you asked for. */
+    docRect: DocRect;
+    pixels: PixelSize;
+}
+export declare function rectArea(r: DocRect): number;
+/**
+ * The negation is deliberate: `!(w > 0)` treats NaN as empty, where
+ * `w <= 0` would call a NaN rect non-empty and let it reach a texture alloc.
+ */
+export declare function isEmptyRect(r: DocRect): boolean;
+export declare function rectIntersects(a: DocRect, b: DocRect): boolean;
+/**
+ * True when `inner` lies wholly within `outer`. Touching edges count as
+ * contained; `epsilon` widens `outer` to absorb float noise at high zoom,
+ * where a rect is reconstructed from a transform every frame.
+ */
+export declare function rectContains(outer: DocRect, inner: DocRect, epsilon?: number): boolean;
+/**
+ * True when `covers` TOGETHER contain every point of `target`.
+ *
+ * WHY THIS IS NOT `covers.some(c => rectContains(c, target))`. Once a layer is
+ * tiled, the thing replacing an old raster is a GRID, and no single grid cell
+ * contains an old cell that straddles a seam. A per-rect containment test
+ * therefore reports "not covered" for a grid that re-covers the area completely
+ * — which is how the controller ended up retaining an entire previous grid on
+ * every epoch, holding two full grids through every transition.
+ *
+ * WHY NOT THE UNION RECT EITHER. `rectUnion` of an L-shaped set spans the
+ * missing corner, so a union test claims coverage nobody paints. This is an
+ * EXACT rectangle-union coverage test instead, and it is exact for both shapes:
+ * cut the target into vertical slabs at every candidate edge, and inside each
+ * slab merge the y-intervals of the candidates that span it. A slab that cannot
+ * be spanned from `target`'s top edge to its bottom edge without a gap is a
+ * hole, wherever it came from.
+ *
+ * `epsilon` widens each candidate — both rects are the product of float
+ * arithmetic and a 1e-9 overhang is not a coverage failure. O(n^2) over an n in
+ * the low tens (a grid is at most a few dozen pieces), evaluated once per commit.
+ */
+export declare function rectsCover(covers: readonly DocRect[], target: DocRect, epsilon?: number): boolean;
+/** Null rather than an empty rect, so "no overlap" cannot be drawn by accident. */
+export declare function rectIntersection(a: DocRect, b: DocRect): DocRect | null;
+/**
+ * An empty operand is skipped rather than unioned: a zero-size rect still has
+ * an origin, and folding one in would drag the union to (0,0) and make the
+ * coverage predicate think the whole document was covered.
+ */
+export declare function rectUnion(a: DocRect, b: DocRect): DocRect;
+/**
+ * Grow by a FRACTION of the rect's own extents on each side — `fx = 0.25`
+ * adds 25% of the width to the left AND to the right, so the result is 1.5x
+ * wide. Fractions, not absolute points, because the only caller is
+ * `detailOverflow`, which is defined that way and must stay scale-invariant.
+ */
+export declare function inflateRect(r: DocRect, fx: number, fy: number): DocRect;
+/**
+ * Intersection that always returns a rect. A disjoint input collapses to a
+ * zero-size rect on the nearest edge of `bounds` rather than to null, so
+ * callers that only need "clip this to the page" need no null branch.
+ */
+export declare function clampRectTo(r: DocRect, bounds: DocRect): DocRect;
+export declare function rectsEqual(a: DocRect, b: DocRect, epsilon?: number): boolean;
+/**
+ * Device pixels per point at which `content` fits inside `viewport`.
+ *
+ * `padding` is in DEVICE PIXELS (it is inset from a pixel-space box) and is
+ * removed from both sides of each axis. Returns 0 when nothing can fit, which
+ * callers must treat as "do not plan a raster" rather than scaling by zero.
+ */
+export declare function fitScale(content: DocSize, viewport: PixelSize, padding?: number): number;
+export declare function scaleToPixels(rect: DocRect, scale: number): PixelSize;
+/**
+ * Expand `rect` outward until its device-pixel bounds are whole numbers.
+ *
+ * LOAD-BEARING: the returned `docRect` is what the caller must draw at, not
+ * the rect it asked for. A backend renders `round(width * scale)` pixels; if
+ * the request straddled the pixel grid, those bytes cover a slightly larger
+ * area than the requested rect, and drawing them into the requested rect
+ * rescales the bitmap by a sub-pixel fraction. That is not a rounding error
+ * you can ignore — it lands as blur, and as misregistration against the
+ * annotation layer drawn above at exact doc coordinates.
+ *
+ * Always expands (floor the near edge, ceil the far one) so the covered area
+ * is a superset of the request; adjacent pieces therefore overlap, never gap.
+ */
+export declare function snapRectToDevicePixels(rect: DocRect, scale: number): SnappedRect;

package/dist/geometry.js

@@ -0,0 +1,248 @@
+/**
+ * Doc-space geometry: PDF points, y-down, origin at the page's top-left.
+ *
+ * Every function here is pure and total — no throws, no NaN propagation that
+ * survives a guard. These are the numbers that end up as a texture allocation
+ * and a draw rect, so a silent NaN here is a blank page or an OOM later.
+ */
+/** Comparison tolerance in points. Sub-micron on any real sheet. */
+const DEFAULT_EPSILON = 1e-6;
+export function rectArea(r) {
+    return Math.max(0, r.width) * Math.max(0, r.height);
+}
+/**
+ * The negation is deliberate: `!(w > 0)` treats NaN as empty, where
+ * `w <= 0` would call a NaN rect non-empty and let it reach a texture alloc.
+ */
+export function isEmptyRect(r) {
+    return !(r.width > 0) || !(r.height > 0);
+}
+export function rectIntersects(a, b) {
+    return (a.x < b.x + b.width &&
+        b.x < a.x + a.width &&
+        a.y < b.y + b.height &&
+        b.y < a.y + a.height);
+}
+/**
+ * True when `inner` lies wholly within `outer`. Touching edges count as
+ * contained; `epsilon` widens `outer` to absorb float noise at high zoom,
+ * where a rect is reconstructed from a transform every frame.
+ */
+export function rectContains(outer, inner, epsilon = 0) {
+    return (inner.x >= outer.x - epsilon &&
+        inner.y >= outer.y - epsilon &&
+        inner.x + inner.width <= outer.x + outer.width + epsilon &&
+        inner.y + inner.height <= outer.y + outer.height + epsilon);
+}
+/**
+ * True when `covers` TOGETHER contain every point of `target`.
+ *
+ * WHY THIS IS NOT `covers.some(c => rectContains(c, target))`. Once a layer is
+ * tiled, the thing replacing an old raster is a GRID, and no single grid cell
+ * contains an old cell that straddles a seam. A per-rect containment test
+ * therefore reports "not covered" for a grid that re-covers the area completely
+ * — which is how the controller ended up retaining an entire previous grid on
+ * every epoch, holding two full grids through every transition.
+ *
+ * WHY NOT THE UNION RECT EITHER. `rectUnion` of an L-shaped set spans the
+ * missing corner, so a union test claims coverage nobody paints. This is an
+ * EXACT rectangle-union coverage test instead, and it is exact for both shapes:
+ * cut the target into vertical slabs at every candidate edge, and inside each
+ * slab merge the y-intervals of the candidates that span it. A slab that cannot
+ * be spanned from `target`'s top edge to its bottom edge without a gap is a
+ * hole, wherever it came from.
+ *
+ * `epsilon` widens each candidate — both rects are the product of float
+ * arithmetic and a 1e-9 overhang is not a coverage failure. O(n^2) over an n in
+ * the low tens (a grid is at most a few dozen pieces), evaluated once per commit.
+ */
+export function rectsCover(covers, target, epsilon = 0) {
+    // Nothing to cover. Vacuously true, and the caller's "may I release the old
+    // set" question is answered yes, which is correct for an empty old set.
+    if (isEmptyRect(target))
+        return true;
+    const tx0 = target.x;
+    const tx1 = target.x + target.width;
+    const ty0 = target.y;
+    const ty1 = target.y + target.height;
+    /** Candidates clipped to the target, in edge coordinates. */
+    const clipped = [];
+    for (const c of covers) {
+        if (isEmptyRect(c))
+            continue;
+        const x0 = Math.max(c.x - epsilon, tx0);
+        const x1 = Math.min(c.x + c.width + epsilon, tx1);
+        const y0 = Math.max(c.y - epsilon, ty0);
+        const y1 = Math.min(c.y + c.height + epsilon, ty1);
+        if (x1 - x0 > DEFAULT_EPSILON && y1 - y0 > DEFAULT_EPSILON) {
+            clipped.push({ x0, x1, y0, y1 });
+        }
+    }
+    if (clipped.length === 0)
+        return false;
+    const xs = [tx0, tx1];
+    for (const c of clipped) {
+        if (c.x0 > tx0 && c.x0 < tx1)
+            xs.push(c.x0);
+        if (c.x1 > tx0 && c.x1 < tx1)
+            xs.push(c.x1);
+    }
+    xs.sort((a, b) => a - b);
+    for (let i = 0; i < xs.length - 1; i++) {
+        const from = xs[i] ?? tx0;
+        const to = xs[i + 1] ?? tx1;
+        // Duplicate edges collapse to a zero-width slab. Sub-micron on any real
+        // sheet, and a slab with no width has no area to leave uncovered.
+        if (to - from <= DEFAULT_EPSILON)
+            continue;
+        const spans = [];
+        for (const c of clipped) {
+            if (c.x0 <= from + DEFAULT_EPSILON && c.x1 >= to - DEFAULT_EPSILON) {
+                spans.push({ y0: c.y0, y1: c.y1 });
+            }
+        }
+        if (spans.length === 0)
+            return false;
+        spans.sort((a, b) => a.y0 - b.y0);
+        let reach = ty0;
+        for (const span of spans) {
+            // A gap between the last covered y and this span's top is a hole, and
+            // sorting by y0 means no later span can fill it.
+            if (span.y0 > reach + DEFAULT_EPSILON)
+                break;
+            if (span.y1 > reach)
+                reach = span.y1;
+            if (reach >= ty1 - DEFAULT_EPSILON)
+                break;
+        }
+        if (reach < ty1 - DEFAULT_EPSILON)
+            return false;
+    }
+    return true;
+}
+/** Null rather than an empty rect, so "no overlap" cannot be drawn by accident. */
+export function rectIntersection(a, b) {
+    const x = Math.max(a.x, b.x);
+    const y = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.width, b.x + b.width);
+    const bottom = Math.min(a.y + a.height, b.y + b.height);
+    if (!(right > x) || !(bottom > y))
+        return null;
+    return { x, y, width: right - x, height: bottom - y };
+}
+/**
+ * An empty operand is skipped rather than unioned: a zero-size rect still has
+ * an origin, and folding one in would drag the union to (0,0) and make the
+ * coverage predicate think the whole document was covered.
+ */
+export function rectUnion(a, b) {
+    if (isEmptyRect(a))
+        return { ...b };
+    if (isEmptyRect(b))
+        return { ...a };
+    const x = Math.min(a.x, b.x);
+    const y = Math.min(a.y, b.y);
+    const right = Math.max(a.x + a.width, b.x + b.width);
+    const bottom = Math.max(a.y + a.height, b.y + b.height);
+    return { x, y, width: right - x, height: bottom - y };
+}
+/**
+ * Grow by a FRACTION of the rect's own extents on each side — `fx = 0.25`
+ * adds 25% of the width to the left AND to the right, so the result is 1.5x
+ * wide. Fractions, not absolute points, because the only caller is
+ * `detailOverflow`, which is defined that way and must stay scale-invariant.
+ */
+export function inflateRect(r, fx, fy) {
+    const dx = r.width * fx;
+    const dy = r.height * fy;
+    return {
+        x: r.x - dx,
+        y: r.y - dy,
+        width: r.width + dx * 2,
+        height: r.height + dy * 2,
+    };
+}
+/**
+ * Intersection that always returns a rect. A disjoint input collapses to a
+ * zero-size rect on the nearest edge of `bounds` rather than to null, so
+ * callers that only need "clip this to the page" need no null branch.
+ */
+export function clampRectTo(r, bounds) {
+    const bRight = bounds.x + bounds.width;
+    const bBottom = bounds.y + bounds.height;
+    const x = Math.min(Math.max(r.x, bounds.x), bRight);
+    const y = Math.min(Math.max(r.y, bounds.y), bBottom);
+    const right = Math.min(Math.max(r.x + r.width, bounds.x), bRight);
+    const bottom = Math.min(Math.max(r.y + r.height, bounds.y), bBottom);
+    return {
+        x,
+        y,
+        width: Math.max(0, right - x),
+        height: Math.max(0, bottom - y),
+    };
+}
+export function rectsEqual(a, b, epsilon = DEFAULT_EPSILON) {
+    return (Math.abs(a.x - b.x) <= epsilon &&
+        Math.abs(a.y - b.y) <= epsilon &&
+        Math.abs(a.width - b.width) <= epsilon &&
+        Math.abs(a.height - b.height) <= epsilon);
+}
+/**
+ * Device pixels per point at which `content` fits inside `viewport`.
+ *
+ * `padding` is in DEVICE PIXELS (it is inset from a pixel-space box) and is
+ * removed from both sides of each axis. Returns 0 when nothing can fit, which
+ * callers must treat as "do not plan a raster" rather than scaling by zero.
+ */
+export function fitScale(content, viewport, padding = 0) {
+    if (!(content.width > 0) || !(content.height > 0))
+        return 0;
+    const available = {
+        width: viewport.width - padding * 2,
+        height: viewport.height - padding * 2,
+    };
+    if (!(available.width > 0) || !(available.height > 0))
+        return 0;
+    return Math.min(available.width / content.width, available.height / content.height);
+}
+export function scaleToPixels(rect, scale) {
+    if (!(scale > 0))
+        return { width: 0, height: 0 };
+    return {
+        width: Math.max(0, Math.round(rect.width * scale)),
+        height: Math.max(0, Math.round(rect.height * scale)),
+    };
+}
+/**
+ * Expand `rect` outward until its device-pixel bounds are whole numbers.
+ *
+ * LOAD-BEARING: the returned `docRect` is what the caller must draw at, not
+ * the rect it asked for. A backend renders `round(width * scale)` pixels; if
+ * the request straddled the pixel grid, those bytes cover a slightly larger
+ * area than the requested rect, and drawing them into the requested rect
+ * rescales the bitmap by a sub-pixel fraction. That is not a rounding error
+ * you can ignore — it lands as blur, and as misregistration against the
+ * annotation layer drawn above at exact doc coordinates.
+ *
+ * Always expands (floor the near edge, ceil the far one) so the covered area
+ * is a superset of the request; adjacent pieces therefore overlap, never gap.
+ */
+export function snapRectToDevicePixels(rect, scale) {
+    if (!(scale > 0))
+        return { docRect: { ...rect }, pixels: { width: 0, height: 0 } };
+    const left = Math.floor(rect.x * scale);
+    const top = Math.floor(rect.y * scale);
+    const right = Math.ceil((rect.x + rect.width) * scale);
+    const bottom = Math.ceil((rect.y + rect.height) * scale);
+    const width = Math.max(0, right - left);
+    const height = Math.max(0, bottom - top);
+    return {
+        docRect: {
+            x: left / scale,
+            y: top / scale,
+            width: width / scale,
+            height: height / scale,
+        },
+        pixels: { width, height },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The shared public surface of @reekon-tools/react-native-pdf-canvas.
+ *
+ * `./testing` is deliberately NOT re-exported here — the deterministic fake
+ * rasterizer has its own subpath export so it never ends up in a production
+ * bundle just because someone imported a type from the root.
+ *
+ * Nor is `./rasterizer/index.{native,web}.js`: the platform default backend is
+ * resolved through `setDefaultRasterizer` / `getDefaultRasterizer` on the React
+ * side, and star-exporting a platform file from this platform-agnostic barrel is
+ * how the two entry points start disagreeing about what `getDefaultRasterizer`
+ * means.
+ *
+ * ------------------------------------------------------------------------
+ * AND NEITHER IS THE INGEST SEAM. THIS BARREL MUST STAY SKIA-FREE.
+ * ------------------------------------------------------------------------
+ *
+ * `ingestRaster` / `imageFromPixels` / `rasterByteLength` used to be re-exported
+ * from here, which meant that merely NAMING this package pulled
+ * `@shopify/react-native-skia`'s barrel — and with it `Skia.web.js`, whose
+ * module body is `JsiSkApi(global.CanvasKit)`. On web that call is taken once
+ * and never retaken, so evaluating it before `LoadSkiaWeb` resolves leaves a
+ * permanently broken `Skia` that re-importing cannot repair. rock-desktop is
+ * `{ssr: true}` with `flatRoutes()` and no prerender, so every route module is
+ * evaluated in Node on every request: one root import is enough.
+ *
+ * They now live on the `./skia` subpath, and everything reachable from here is
+ * free of module-scope Skia. That is not a style rule — it is asserted by
+ * `__tests__/module-ordering.test.ts`, which BUNDLES this file and greps the
+ * output for `JsiSkApi(global.CanvasKit)`.
+ */
+/** The frozen type contract, plus the `PdfError` class every seam throws. */
+export * from './types.js';
+/** The React surface: both hooks and the Skia node. */
+export * from './react/index.js';
+/** Page layouts. `layout.ts` is singular — there is no `layouts.js`. */
+export * from './layout.js';
+/** Cadence constants and the ignore-undefined merge over them. */
+export * from './policy.js';
+/**
+ * The cadence engine, for a host that drives it outside React — an export or a
+ * print path, where there is no component to hang a hook on. Its companion types
+ * come with it: an exported factory whose options type is unreachable is a dead
+ * export.
+ */
+export { createPdfController } from './controller.js';
+export type { PdfControllerInstance, PdfControllerOptions, RasterIngestMeta, ScheduledHandle, } from './controller.js';
+/** The cache `createPdfController` requires. */
+export { createRasterCache } from './cache.js';
+export type { EvictionReason, RasterCache, RasterCacheOptions, RasterCacheStats, } from './cache.js';
+/** The two pure decisions, WHAT to raster and WHEN, usable on their own. */
+export { planRasters, shouldReraster } from './planner.js';

package/dist/index.js

@@ -0,0 +1,50 @@
+/**
+ * The shared public surface of @reekon-tools/react-native-pdf-canvas.
+ *
+ * `./testing` is deliberately NOT re-exported here — the deterministic fake
+ * rasterizer has its own subpath export so it never ends up in a production
+ * bundle just because someone imported a type from the root.
+ *
+ * Nor is `./rasterizer/index.{native,web}.js`: the platform default backend is
+ * resolved through `setDefaultRasterizer` / `getDefaultRasterizer` on the React
+ * side, and star-exporting a platform file from this platform-agnostic barrel is
+ * how the two entry points start disagreeing about what `getDefaultRasterizer`
+ * means.
+ *
+ * ------------------------------------------------------------------------
+ * AND NEITHER IS THE INGEST SEAM. THIS BARREL MUST STAY SKIA-FREE.
+ * ------------------------------------------------------------------------
+ *
+ * `ingestRaster` / `imageFromPixels` / `rasterByteLength` used to be re-exported
+ * from here, which meant that merely NAMING this package pulled
+ * `@shopify/react-native-skia`'s barrel — and with it `Skia.web.js`, whose
+ * module body is `JsiSkApi(global.CanvasKit)`. On web that call is taken once
+ * and never retaken, so evaluating it before `LoadSkiaWeb` resolves leaves a
+ * permanently broken `Skia` that re-importing cannot repair. rock-desktop is
+ * `{ssr: true}` with `flatRoutes()` and no prerender, so every route module is
+ * evaluated in Node on every request: one root import is enough.
+ *
+ * They now live on the `./skia` subpath, and everything reachable from here is
+ * free of module-scope Skia. That is not a style rule — it is asserted by
+ * `__tests__/module-ordering.test.ts`, which BUNDLES this file and greps the
+ * output for `JsiSkApi(global.CanvasKit)`.
+ */
+/** The frozen type contract, plus the `PdfError` class every seam throws. */
+export * from './types.js';
+/** The React surface: both hooks and the Skia node. */
+export * from './react/index.js';
+/** Page layouts. `layout.ts` is singular — there is no `layouts.js`. */
+export * from './layout.js';
+/** Cadence constants and the ignore-undefined merge over them. */
+export * from './policy.js';
+/**
+ * The cadence engine, for a host that drives it outside React — an export or a
+ * print path, where there is no component to hang a hook on. Its companion types
+ * come with it: an exported factory whose options type is unreachable is a dead
+ * export.
+ */
+export { createPdfController } from './controller.js';
+/** The cache `createPdfController` requires. */
+export { createRasterCache } from './cache.js';
+/** The two pure decisions, WHAT to raster and WHEN, usable on their own. */
+export { planRasters, shouldReraster } from './planner.js';

package/dist/index.native.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Platform entry point — the shared surface, plus the native Skia resolver.
+ *
+ * This file exists ONLY because Metro applies NO platform-extension expansion to
+ * the targets of a package's `exports` map. Metro will happily resolve
+ * `./foo` to `foo.native.ts` for a normal relative import, but an `exports`
+ * condition is matched literally: `"react-native": "./dist/index.js"` would load
+ * `dist/index.js` and never look for `dist/index.native.js`. So the map points at
+ * the literal `dist/index.native.js` path, and this file is what produces it.
+ *
+ * Keep the EXPORTS a pure re-export. The moment platform-specific wiring is
+ * exported from here, the two entry points can drift and the `types` condition
+ * (which resolves to `index.d.ts`) starts lying about one of them.
+ *
+ * The resolver install below adds no exports and is the one thing that
+ * legitimately differs: on native `Skia` is `global.SkiaApi`, installed
+ * synchronously by RN Skia's own import-time side effect, so importing the
+ * barrel here is both correct and free of the web ordering hazard. `index.web.ts`
+ * installs the CanvasKit-backed resolver instead. See `./skia/skia-api.ts`.
+ */
+export * from './index.js';

package/dist/index.native.js

@@ -0,0 +1,23 @@
+/**
+ * Platform entry point — the shared surface, plus the native Skia resolver.
+ *
+ * This file exists ONLY because Metro applies NO platform-extension expansion to
+ * the targets of a package's `exports` map. Metro will happily resolve
+ * `./foo` to `foo.native.ts` for a normal relative import, but an `exports`
+ * condition is matched literally: `"react-native": "./dist/index.js"` would load
+ * `dist/index.js` and never look for `dist/index.native.js`. So the map points at
+ * the literal `dist/index.native.js` path, and this file is what produces it.
+ *
+ * Keep the EXPORTS a pure re-export. The moment platform-specific wiring is
+ * exported from here, the two entry points can drift and the `types` condition
+ * (which resolves to `index.d.ts`) starts lying about one of them.
+ *
+ * The resolver install below adds no exports and is the one thing that
+ * legitimately differs: on native `Skia` is `global.SkiaApi`, installed
+ * synchronously by RN Skia's own import-time side effect, so importing the
+ * barrel here is both correct and free of the web ordering hazard. `index.web.ts`
+ * installs the CanvasKit-backed resolver instead. See `./skia/skia-api.ts`.
+ */
+import { installNativeSkiaResolver } from './skia/resolve.native.js';
+export * from './index.js';
+installNativeSkiaResolver();

package/dist/index.web.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Web/default entry point — the shared surface, plus the web Skia resolver.
+ *
+ * Same reason as index.native.ts for existing at all: `exports` targets are
+ * matched literally, with no platform-extension expansion, so the `browser` and
+ * `default` conditions need a real `dist/index.web.js` file to point at.
+ *
+ * ------------------------------------------------------------------------
+ * THE INSTALL BELOW DECIDES NOTHING AT IMPORT TIME.
+ * ------------------------------------------------------------------------
+ *
+ * It stores a closure. `globalThis.CanvasKit` is not read, `JsiSkApi` is not
+ * called, and no module that calls it is evaluated — so this file stays safe to
+ * evaluate in Node during rock-desktop's SSR pass, before CanvasKit exists
+ * anywhere. Asserted by `__tests__/module-ordering.test.ts`, which bundles this
+ * exact file and greps for `JsiSkApi(global.CanvasKit)`.
+ *
+ * It exists so that a host which loads CanvasKit its own way (`WithSkiaWeb`
+ * around the canvas, RN Skia's bare `LoadSkiaWeb`, a `<script>` that sets
+ * `globalThis.CanvasKit`) still gets a working `skiaApi()` without knowing this
+ * package has a `./web-init` subpath. `loadPdfCanvasSkiaWeb()` remains the
+ * explicit, awaitable route and is what the README points at.
+ */
+export * from './index.js';

package/dist/index.web.js

@@ -0,0 +1,26 @@
+/**
+ * Web/default entry point — the shared surface, plus the web Skia resolver.
+ *
+ * Same reason as index.native.ts for existing at all: `exports` targets are
+ * matched literally, with no platform-extension expansion, so the `browser` and
+ * `default` conditions need a real `dist/index.web.js` file to point at.
+ *
+ * ------------------------------------------------------------------------
+ * THE INSTALL BELOW DECIDES NOTHING AT IMPORT TIME.
+ * ------------------------------------------------------------------------
+ *
+ * It stores a closure. `globalThis.CanvasKit` is not read, `JsiSkApi` is not
+ * called, and no module that calls it is evaluated — so this file stays safe to
+ * evaluate in Node during rock-desktop's SSR pass, before CanvasKit exists
+ * anywhere. Asserted by `__tests__/module-ordering.test.ts`, which bundles this
+ * exact file and greps for `JsiSkApi(global.CanvasKit)`.
+ *
+ * It exists so that a host which loads CanvasKit its own way (`WithSkiaWeb`
+ * around the canvas, RN Skia's bare `LoadSkiaWeb`, a `<script>` that sets
+ * `globalThis.CanvasKit`) still gets a working `skiaApi()` without knowing this
+ * package has a `./web-init` subpath. `loadPdfCanvasSkiaWeb()` remains the
+ * explicit, awaitable route and is what the README points at.
+ */
+import { installWebSkiaResolver } from './skia/resolve.web.js';
+export * from './index.js';
+installWebSkiaResolver();

package/dist/layout.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 type { DocRect, PdfPageLayout } from './types.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 declare function singlePage(): PdfPageLayout;
+/**
+ * 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 declare function hasOverlappingPages(rects: readonly DocRect[]): boolean;
+/**
+ * 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 declare function continuousVertical(gap?: number): PdfPageLayout;
+/**
+ * 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 declare function spread(gap?: number): PdfPageLayout;