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

package/dist/policy.js

@@ -0,0 +1,168 @@
+/**
+ * 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.
+ */
+export const DEFAULT_POLICY = Object.freeze({
+    /**
+     * 1.0 — the base is rendered at exactly the fit-zoom display scale, so at
+     * fit zoom it is pixel-for-pixel and never magnified or minified. Anything
+     * above 1.0 buys sharpness only while zoomed in, which is the DETAIL layer's
+     * job; anything below draws the page minified, which is the aliasing regime
+     * (kStrict_SrcRectConstraint disables mipmaps, so it cannot be filtered
+     * away). A consumer whose base must survive a 2x zoom without the detail
+     * layer landing raises this to ~1.5 and pays for it in `baseMaxPixels`.
+     */
+    baseQuality: 1.0,
+    /**
+     * 4 MP. The base is the anti-blank mechanism and is NEVER released, so it is
+     * resident for the life of the document — one per visible page. At RGBA8888
+     * that is 16 MB per page, which is a sixth of `cacheBudgetBytes` and leaves
+     * room for the two or three pages a continuous layout keeps live. It also
+     * comfortably clears every real fit-zoom target: ARCH-D on a 1170x2532
+     * phone needs 2.05 MP, so the clamp does not bind on the case that matters
+     * and only catches the pathological sheet.
+     */
+    baseMaxPixels: 4000000,
+    /**
+     * 0.25 — a quarter of the visible extent added on EACH side, so a detail
+     * raster is 1.5x the viewport per axis, 2.25x its area. That is the price of
+     * a flick that outruns the quiet timer: a pan of up to a quarter viewport
+     * stays sharp with no new raster at all. Larger multiplies raster cost
+     * quadratically for padding that is usually thrown away.
+     */
+    detailOverflow: 0.25,
+    /**
+     * 4096 is the only near-universal GPU texture limit — it is the floor across
+     * the GLES3 and Metal feature sets this ships to, and exceeding it does not
+     * degrade, it fails the texture upload and draws nothing. Devices reporting
+     * 8192 or 16384 exist; planning to the floor costs one extra piece on a
+     * desktop-sized viewport and removes an entire class of blank-page report.
+     */
+    maxTextureDimension: 4096,
+    /**
+     * 1024 device px — a MEMORY policy, not a hardware one, and the single biggest
+     * low-end lever in the package.
+     *
+     * Measured on the un-tiled detail raster this replaced: 1755x3798 (25.4 MiB of
+     * pixels) had a ~237 MiB whole-flow transient peak across the Java, native and
+     * JS heaps, because one piece's bytes exist at once as a platform bitmap, a
+     * base64 string on the bridge, a JS `Uint8Array` and an `SkData`. Tiling the
+     * same area at 1024 drops that peak to ~29.7 MiB; at 512 to ~7.4 MiB. The
+     * RESIDENT bytes do not change — it is the same pixels either way.
+     *
+     * Why not 512, then: every piece is a separate uninterruptible platform render
+     * with its own fixed overhead, and each interior seam costs an overlap strip,
+     * so halving again quadruples the piece count for a peak that is already well
+     * under any device's budget. 1024 is also comfortably inside
+     * `maxTextureDimension` on every device, so the two caps do not fight.
+     *
+     * Raise it on a big-memory tablet; lower it to 512 on a low-RAM Android device
+     * where the transient, not the total, is what gets the app killed.
+     */
+    maxPieceDimension: 1024,
+    /**
+     * 24 MP for a single detail request, matching the cap the consuming app
+     * already established for its own PDF rendering. It is a TIME budget as much
+     * as a memory one: PDFKit's draw and Android's PdfRenderer.render are
+     * synchronous and uninterruptible once entered, so an oversized request is
+     * an un-abortable stall on whichever thread it runs on.
+     */
+    maxRasterPixels: 24000000,
+    /**
+     * sqrt(2). Re-raster once the on-screen scale has drifted a full half-octave
+     * from what the bytes were rendered at — i.e. tolerate up to 41% magnifi-
+     * cation (mild softness) or 29% minification before spending a raster.
+     * Halving this to 1.2 is correct on a DPR-1 display, where individual pixels
+     * are resolvable before any magnification is applied.
+     */
+    sharpnessBand: 1.414,
+    /**
+     * pdf.js's MOVEMENT_THRESHOLD, adopted verbatim rather than re-derived. Fire
+     * when the padding remaining ahead of the motion falls below half the
+     * padding already consumed behind it — a directional look-ahead that starts
+     * the next raster while the current one still covers the screen.
+     */
+    movementThreshold: 0.5,
+    /**
+     * 250 ms after a scale change. Zoom is coarse and self-correcting — users
+     * overshoot and come back — so rastering mid-pinch is usually wasted, and
+     * the base layer covers the gap at any scale. Long enough that a two-finger
+     * adjust-and-settle produces one raster, not three.
+     */
+    quietZoomMs: 250,
+    /**
+     * 120 ms after a pan-only change, roughly half the zoom delay. Pan is
+     * monotonic: content that scrolls off does not come back, so waiting buys
+     * nothing, and `detailOverflow` has already covered the first quarter
+     * viewport of travel. Comfortably above one 60Hz frame so a wheel notch
+     * train still coalesces.
+     */
+    quietPanMs: 120,
+    /**
+     * 700 ms. Under continued input the quiet timer never fires, so without this
+     * a slow continuous drag shows the base layer indefinitely. Chosen to sit
+     * above `minEpochIntervalMs` plus a typical raster, so the forced raster is
+     * never itself immediately superseded.
+     */
+    maxStaleMs: 700,
+    /**
+     * 300 ms — A PLACEHOLDER for the measured p95 raster time on the target
+     * device, which has not been measured yet. It should be replaced with a real
+     * number, not tuned by feel: the floor exists because an abort cannot
+     * interrupt a synchronous platform render, so setting it below the actual
+     * raster duration means every raster is superseded before it lands and the
+     * detail layer never appears at all.
+     */
+    minEpochIntervalMs: 300,
+    /**
+     * 96 MB. A SOFT cap on cached raster bytes used to pick eviction victims —
+     * not a memory limit, because the base rasters and the live epoch are pinned
+     * regardless.
+     *
+     * THE VALUE IS UNCHANGED AND ITS MEANING HAS TIGHTENED. A raster now books ~2x
+     * its pixels (`PdfRaster.bytes`, and `rasterByteLength` for why), so the same
+     * 96 MB covers half as many pixels as it nominally did before. That is the
+     * point: it was always covering half as many, it just did not know, so
+     * eviction was picking victims on numbers that were wrong by 2x. A 4 MP base
+     * is 32 MB against this budget, not 16 MB.
+     */
+    cacheBudgetBytes: 96 * 1024 * 1024,
+    /**
+     * false. The retiring set is already held across the swap, which is what
+     * prevents a one-frame flash; keeping it mounted beyond that doubles the
+     * resident detail bytes to defend against a case the base layer already
+     * covers. Consumers on a big-memory tablet may prefer true.
+     */
+    retainPreviousDetail: false,
+});
+/**
+ * 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 function resolvePolicy(partial) {
+    if (!partial)
+        return DEFAULT_POLICY;
+    // Spelled out field by field rather than looped: a keyed loop needs an index
+    // signature RasterPolicy does not have, and every escape from that is a
+    // cast. `??` gives the ignore-undefined behaviour for free, and correctly
+    // keeps an explicit `false` for retainPreviousDetail.
+    return Object.freeze({
+        baseQuality: partial.baseQuality ?? DEFAULT_POLICY.baseQuality,
+        baseMaxPixels: partial.baseMaxPixels ?? DEFAULT_POLICY.baseMaxPixels,
+        detailOverflow: partial.detailOverflow ?? DEFAULT_POLICY.detailOverflow,
+        maxTextureDimension: partial.maxTextureDimension ?? DEFAULT_POLICY.maxTextureDimension,
+        maxPieceDimension: partial.maxPieceDimension ?? DEFAULT_POLICY.maxPieceDimension,
+        maxRasterPixels: partial.maxRasterPixels ?? DEFAULT_POLICY.maxRasterPixels,
+        sharpnessBand: partial.sharpnessBand ?? DEFAULT_POLICY.sharpnessBand,
+        movementThreshold: partial.movementThreshold ?? DEFAULT_POLICY.movementThreshold,
+        quietZoomMs: partial.quietZoomMs ?? DEFAULT_POLICY.quietZoomMs,
+        quietPanMs: partial.quietPanMs ?? DEFAULT_POLICY.quietPanMs,
+        maxStaleMs: partial.maxStaleMs ?? DEFAULT_POLICY.maxStaleMs,
+        minEpochIntervalMs: partial.minEpochIntervalMs ?? DEFAULT_POLICY.minEpochIntervalMs,
+        cacheBudgetBytes: partial.cacheBudgetBytes ?? DEFAULT_POLICY.cacheBudgetBytes,
+        retainPreviousDetail: partial.retainPreviousDetail ?? DEFAULT_POLICY.retainPreviousDetail,
+    });
+}

package/dist/rasterizer/android.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The TypeScript half of the Android backend.
+ *
+ * THIN, AND IT USED TO BE THE WHOLE THING. Everything that is not
+ * Android-specific — error mapping, page-geometry marshalling, the transport
+ * negotiation, the base64 decode, the cancellation wiring, the phase timings —
+ * moved to `./native-bridge.ts` when the iOS backend landed, because the two
+ * platforms speak the identical wire format and the spec's claim for the iOS step
+ * is that the seam is a seam. What is left here is the four things that are
+ * genuinely Android's: the id, the capabilities, the alpha encoding, and what
+ * `PdfSource` it can accept.
+ *
+ * The names exported from `./native-bridge.ts` are re-exported below under their
+ * original `Android*` spellings, so nothing that imported them from here breaks.
+ *
+ * PURE ON PURPOSE. Nothing here imports `react-native`, which is what lets the
+ * whole adapter be tested in vitest against a fake native module.
+ * `./index.native.ts` is the only file that resolves the real one, and it does
+ * nothing except hand it to `createAndroidRasterizer`.
+ *
+ * The native side is `android/src/main/java/tools/reekon/pdfcanvas/`, a
+ * React-free Android library that is proven on device by
+ * `./gradlew connectedDebugAndroidTest`. That split is the reason a bug here is
+ * a bug in marshalling and never a bug in rasterizing.
+ */
+import type { NativeRasterizerHandle, NativeRotationSupport, NativeOpenResult, NativePdfPage, NativeRenderRequest, NativeRenderResult, NativeSource, NativeTransport, PdfCanvasNativeModule } from './native-bridge.js';
+import type { PageRasterizer } from '../types.js';
+export { TRANSPORT_PROBE_BYTES, bytesFromResult, decodeBase64, lookupTakePixels, negotiateTransport, toPageGeometry, } from './native-bridge.js';
+export type { NativeRasterizerHandle, NativeRotationSupport, NativeOpenResult, NativePdfPage, NativeRenderRequest, NativeRenderResult, NativeSource, NativeTransport, PdfCanvasNativeModule, TakePixels, } from './native-bridge.js';
+/**
+ * ALIASES, NOT COPIES. These were the shipped names before the wire format was
+ * shared with iOS, and a consumer that imported one should not have to care that
+ * a second backend now speaks it too.
+ */
+export type AndroidRotationSupport = NativeRotationSupport;
+export type AndroidNativePage = NativePdfPage;
+export type AndroidNativeOpenResult = NativeOpenResult;
+export type AndroidNativeRenderResult = NativeRenderResult;
+export type AndroidNativeRenderRequest = NativeRenderRequest;
+export type AndroidNativeSource = NativeSource;
+export type AndroidPdfNativeModule = PdfCanvasNativeModule;
+export type AndroidTransport = NativeTransport;
+export type AndroidRasterizerHandle = NativeRasterizerHandle;
+export interface AndroidRasterizerOptions {
+    /**
+     * Concurrent renders. Clamped to [1, 4] natively — each slot is one more
+     * `PdfRenderer` holding a file descriptor and a parsed document.
+     *
+     * ONE. It is also what the rasterizer reports as
+     * `RasterizerCapabilities.maxConcurrentRenders`, so raising it does two things
+     * at once: it opens more native renderers AND it widens the controller's lane
+     * bound. Both of those are measured below and both come out negative.
+     *
+     * THE POOL DOES NOT PARALLELISE PDFium. AOSP serialises `PdfRenderer` behind a
+     * process-wide PDFium lock, and the lock does not merely serialise, it CONVOYS.
+     * On an LG V60 (Snapdragon 865, 8 cores, API 33) at the field report's scale of
+     * 131.25 device px/pt with 1024 px tiles, over a real field-measure drawing,
+     * four threads inflate the per-tile PDFium phases `openPage` 16.2x,
+     * `PdfRenderer.render` 10.9x and `recycle+close` 33.6x, for a whole-tile
+     * inflation of 5.84x, against 1.1x-5.3x for every non-PDFium phase. On a dense
+     * electrical schematic it is worse still: `render` 30.9x, `openPage` 11.2x.
+     * A pure-Java control on the same threads scales 2.8x. So the native calls do
+     * not overlap, and contending for them makes each one dramatically slower.
+     *
+     * NOTHING ABOUT THIS CARRIES OVER TO iOS, and the iOS option says so on its own
+     * doc comment: the lock being measured here is AOSP's, in
+     * `android_graphics_pdf_PdfRenderer.cpp`, and CoreGraphics has no counterpart
+     * to it that anyone has measured.
+     *
+     * WHY THIS WAS 2, AND WHY THAT REASON IS GONE. The second slot never existed to
+     * rasterize in parallel; it existed to PIPELINE, hiding the JS thread's
+     * `decodeBase64` (~1005 ms per tile, 90.6% of the tile) behind the next tile's
+     * native work. The JSI transport deleted that cost outright — the JS thread's
+     * whole share is now a pointer wrap — so there is nothing left to hide. Worse,
+     * deleting the base64 ENCODE from the Java side deleted the only phase that was
+     * genuinely parallel: on the real drawing a tile was 72.7% parallelisable work
+     * (19.3 ms of encode inside 30.6 ms) and is now 35.6% (4.6 ms of bitmap fill,
+     * pixel copy and JNI store inside 13.0 ms), with the PDFium-serialised part
+     * risen from 25.5% to 60.2%. Amdahl caps that at 1.67x before the convoy is
+     * counted, and the convoy is what turns the remaining headroom negative.
+     *
+     * MEASURED, on the JSI transport, by `laneScheduleOnTheJsiTransport` in
+     * `PdfCanvasPhaseTimingTest` — N lanes over one shared cursor of 6 plan items,
+     * which is the schedule the controller actually runs, 21 interleaved rounds per
+     * lane count. Mean epoch wall clock relative to one lane, higher is better:
+     *
+     *   - real field-measure drawing, 4 independent passes:
+     *     2 lanes 0.82x / 0.81x / 0.95x / 0.76x,
+     *     3 lanes 0.54x / 0.61x / 0.85x / 0.58x,
+     *     4 lanes 0.59x / 0.58x / 0.92x / 0.55x. One lane is never beaten.
+     *   - dense electrical schematic: 2 lanes 0.48x, 3 lanes 0.41x, 4 lanes 0.38x.
+     *   - THE TAIL IS WHERE IT HURTS MOST, and the tail is what a user sees as a
+     *     stutter. Worst-of-21 on the drawing: 126-172 ms at one lane against
+     *     177-238 ms at two. On the schematic: 134 ms against 321 ms.
+     *
+     * ONE IS ALSO THE CHEAPER OBJECT: one file descriptor and one parsed document
+     * instead of two, which on a large drawing is the larger of the two costs.
+     *
+     * DO NOT READ THE SYNTHETIC FIXTURE'S NUMBERS AS AGREEING OR DISAGREEING. With
+     * no `customer.pdf` pushed, `PdfCanvasPhaseTimingTest` falls back to a
+     * vector-rects-and-lines page whose `PdfRenderer.render` is 0.8 ms rather than
+     * 6.5 ms; that shrinks the serialised fraction, and two lanes duly measure
+     * 1.06x-1.25x there. The fixture warns that it is an optimistic bound, and this
+     * is exactly the decision it would have inverted. Push a real drawing before
+     * re-running this.
+     */
+    poolSize?: number;
+    id?: string;
+    /**
+     * How to find the installed JSI host function. Injected only by tests; the
+     * default reads `globalThis`.
+     */
+    lookupTakePixels?: () => import('./native-bridge.js').TakePixels | null;
+}
+/**
+ * Wraps a native module in a `PageRasterizer`.
+ *
+ * The native module is INJECTED rather than imported so this file stays pure.
+ * `getDefaultRasterizer()` in `./index.native.ts` supplies the real one.
+ */
+export declare function createAndroidRasterizer(native: AndroidPdfNativeModule, options?: AndroidRasterizerOptions): PageRasterizer;

package/dist/rasterizer/android.js

@@ -0,0 +1,126 @@
+/**
+ * The TypeScript half of the Android backend.
+ *
+ * THIN, AND IT USED TO BE THE WHOLE THING. Everything that is not
+ * Android-specific — error mapping, page-geometry marshalling, the transport
+ * negotiation, the base64 decode, the cancellation wiring, the phase timings —
+ * moved to `./native-bridge.ts` when the iOS backend landed, because the two
+ * platforms speak the identical wire format and the spec's claim for the iOS step
+ * is that the seam is a seam. What is left here is the four things that are
+ * genuinely Android's: the id, the capabilities, the alpha encoding, and what
+ * `PdfSource` it can accept.
+ *
+ * The names exported from `./native-bridge.ts` are re-exported below under their
+ * original `Android*` spellings, so nothing that imported them from here breaks.
+ *
+ * PURE ON PURPOSE. Nothing here imports `react-native`, which is what lets the
+ * whole adapter be tested in vitest against a fake native module.
+ * `./index.native.ts` is the only file that resolves the real one, and it does
+ * nothing except hand it to `createAndroidRasterizer`.
+ *
+ * The native side is `android/src/main/java/tools/reekon/pdfcanvas/`, a
+ * React-free Android library that is proven on device by
+ * `./gradlew connectedDebugAndroidTest`. That split is the reason a bug here is
+ * a bug in marshalling and never a bug in rasterizing.
+ */
+import { createNativeRasterizer } from './native-bridge.js';
+import { PdfError } from '../types.js';
+export { TRANSPORT_PROBE_BYTES, bytesFromResult, decodeBase64, lookupTakePixels, negotiateTransport, toPageGeometry, } from './native-bridge.js';
+/* ------------------------------------------------------------------ *
+ * What is actually Android's
+ * ------------------------------------------------------------------ */
+/**
+ * A CONSTANT AND NOT PART OF THE WIRE RESULT, unlike `format`.
+ *
+ * `format` is per-render because the Java side could in principle hand back
+ * either byte order; the alpha encoding cannot vary, because it is a property of
+ * `Bitmap` itself. `PdfCanvasRasterizer.extract` reads an ARGB_8888 Bitmap, and
+ * Android bitmaps are PREMULTIPLIED unless somebody calls
+ * `setPremultiplied(false)` — which that code deliberately never does, since
+ * un-premultiplying would make a `background: 'transparent'` raster composite
+ * wrongly rather than fail visibly. So there is nothing for the native side to
+ * report and no reason to widen the wire format to carry it.
+ *
+ * IT MATCHES iOS AND THAT IS A COINCIDENCE OF MECHANISM, not a shared choice.
+ * `CGBitmapContext` has no non-premultiplied 8-bit RGBA configuration at all —
+ * Apple's supported-formats table offers premultiplied or alpha-none and nothing
+ * between — so `ios.ts` declares the same value for a completely different
+ * reason. PDFium and pdf.js, meanwhile, both emit STRAIGHT alpha (measured — see
+ * `AlphaEncoding`), which is the whole reason `RasterPixels.alpha` exists rather
+ * than a single `AlphaType.Premul` in `ingest.ts`. Do not "align" any of these
+ * four values with each other.
+ */
+const ANDROID_ALPHA = 'premultiplied';
+const CAPABILITIES = {
+    /**
+     * True in the sense the field means — annotations ARE drawn into the raster.
+     *
+     * What is NOT true, and has no field to say so: they cannot be turned OFF.
+     * `PdfRenderer.Page.render` takes a render mode and no annotation switch, and
+     * PDFium's `FPDF_ANNOT` flag is unreachable through the platform class at
+     * every API level. So `RasterRequest.annotations: false` — which is what the
+     * controller passes for every tile — is recorded and ignored, and an app that
+     * draws its own copy of a PDF-embedded annotation will see it twice on
+     * Android. The fix is a PDFium backend, not a different mode here.
+     *
+     * iOS DOES HONOUR THE FALSE CASE, which is worth knowing when a bug report
+     * says annotations appear twice on one platform only: `ios.ts` picks
+     * `CGContextDrawPDFPage` for `false` and PDFKit for `true`, and the two really
+     * do differ in what they composite.
+     */
+    annotations: true,
+    /**
+     * False, and honestly so. `PdfRenderer.Page.render` is synchronous and
+     * uninterruptible once entered; an abort can only stop the NEXT piece
+     * starting, or discard a finished raster that is no longer wanted.
+     */
+    interruptibleRender: false,
+    text: false,
+    search: false,
+    links: false,
+    // Overwritten per rasterizer with the pool size it was actually opened with —
+    // see `createNativeRasterizer`. The constant carries the conservative value so
+    // a partially-constructed object is never the fast one.
+    maxConcurrentRenders: 1,
+};
+/**
+ * Mirrors `PdfRendererPool.MAX_POOL_SIZE` on the Java side, which is where the
+ * clamp is actually enforced (`PdfRendererPool.open`). Restating it here is not
+ * a second source of truth: it is what makes the DECLARED capability match the
+ * pool the native side will really hand out, rather than promising four lanes to
+ * a pool that silently opened with four... or with one.
+ */
+const MAX_POOL_SIZE = 4;
+const clampPoolSize = (size) => Math.max(1, Math.min(MAX_POOL_SIZE, Math.floor(size) || 1));
+function toNativeSource(source) {
+    const password = source.password;
+    if ('uri' in source) {
+        return password === undefined
+            ? { uri: source.uri }
+            : { uri: source.uri, password };
+    }
+    throw new PdfError('unsupported', 'Passing a document as bytes is not wired through the Android binding yet. ' +
+        'The native side supports it (PdfCanvasRasterizer.openBytes spools to a ' +
+        'file, because PdfRenderer needs a seekable descriptor), but sending the ' +
+        'bytes over the bridge costs a base64 round trip of the whole document. ' +
+        'Pass a `uri` instead.');
+}
+/**
+ * Wraps a native module in a `PageRasterizer`.
+ *
+ * The native module is INJECTED rather than imported so this file stays pure.
+ * `getDefaultRasterizer()` in `./index.native.ts` supplies the real one.
+ */
+export function createAndroidRasterizer(native, options = {}) {
+    return createNativeRasterizer(native, {
+        id: options.id ?? 'android-pdfrenderer',
+        capabilities: CAPABILITIES,
+        alpha: ANDROID_ALPHA,
+        poolSize: clampPoolSize(options.poolSize ?? 1),
+        label: 'Android',
+        toNativeSource,
+        ...(options.lookupTakePixels === undefined
+            ? {}
+            : { lookupTakePixels: options.lookupTakePixels }),
+    });
+}

package/dist/rasterizer/buffer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The tight-buffer predicate, stated ONCE.
+ *
+ * `Skia.Data.fromBytes` on native reads `array.getProperty("buffer")` and copies
+ * the WHOLE ArrayBuffer, ignoring `byteOffset` and `byteLength`
+ * (JsiSkDataFactory.h). So a Uint8Array that is a VIEW into something larger
+ * ingests shifted bytes and shears the image, and `ingest.ts` copies it to a
+ * tight buffer first (`tighten`).
+ *
+ * This predicate is also the thing a new TRANSPORT has to satisfy to make that
+ * copy disappear: a native path that hands back an ArrayBuffer which is exactly
+ * the raster and nothing more is tight by construction, and `tighten` becomes a
+ * no-op. That makes the predicate a fact worth REPORTING (the backend puts it in
+ * `RasterPhaseTimings.tight`), not merely a branch — which is why it lives in
+ * its own pure module rather than inline in `tighten`, where the transport work
+ * could not see it without importing Skia.
+ */
+export declare const isTightBuffer: (bytes: Uint8Array) => boolean;

package/dist/rasterizer/buffer.js

@@ -0,0 +1,18 @@
+/**
+ * The tight-buffer predicate, stated ONCE.
+ *
+ * `Skia.Data.fromBytes` on native reads `array.getProperty("buffer")` and copies
+ * the WHOLE ArrayBuffer, ignoring `byteOffset` and `byteLength`
+ * (JsiSkDataFactory.h). So a Uint8Array that is a VIEW into something larger
+ * ingests shifted bytes and shears the image, and `ingest.ts` copies it to a
+ * tight buffer first (`tighten`).
+ *
+ * This predicate is also the thing a new TRANSPORT has to satisfy to make that
+ * copy disappear: a native path that hands back an ArrayBuffer which is exactly
+ * the raster and nothing more is tight by construction, and `tighten` becomes a
+ * no-op. That makes the predicate a fact worth REPORTING (the backend puts it in
+ * `RasterPhaseTimings.tight`), not merely a branch — which is why it lives in
+ * its own pure module rather than inline in `tighten`, where the transport work
+ * could not see it without importing Skia.
+ */
+export const isTightBuffer = (bytes) => bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength;

package/dist/rasterizer/fake.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A deterministic PageRasterizer with no Skia, no native module and no PDF.
+ *
+ * It exists to drive the entire pipeline — planner, cadence, epoch swap, cache
+ * — in vitest and in a demo app, and to be the fixture that CATCHES
+ * REGISTRATION BUGS. The pattern is chosen for that second job:
+ *
+ *   - the checkerboard's cell size is in DOC units, not pixels, so two
+ *     correctly-placed pieces show one continuous board across their overlap
+ *     and a piece drawn at the wrong doc rect (or squashed by a src-rect
+ *     mistake) shows an obvious seam;
+ *   - the board is INFINITE in doc space and is not clipped to the page box, so
+ *     a detail piece that overflows the page edge still shows continuous
+ *     checks and an accidental clip is visible as a blank margin;
+ *   - each piece carries a 1px border, so a piece that has been inset or
+ *     stretched shows its border in the wrong place;
+ *   - each piece encodes its own doc rect into a corner swatch, so a test can
+ *     read back what a raster BELIEVES it is without any Skia in the loop.
+ *
+ * Everything here is a pure function of the request, so the same request always
+ * produces byte-identical output.
+ */
+import type { DocRect, DocSize, PageRasterizer, PageRotation, PdfErrorCode, PixelFormat, PixelSize, RasterPixels, RasterRequest } from '../types.js';
+export declare const LETTER: DocSize;
+/** ARCH D, 24x36in — the sheet the base-raster sizing rule is calibrated on. */
+export declare const ARCH_D: DocSize;
+/** ARCH E, 36x48in. */
+export declare const ARCH_E: DocSize;
+export interface FakeFailureModes {
+    /** `open()` rejects with this code. */
+    open?: PdfErrorCode;
+    /**
+     * `render()` rejects with this code. The function form lets a test fail one
+     * page, one scale or one call and let the rest succeed.
+     */
+    render?: PdfErrorCode | ((request: RasterRequest) => PdfErrorCode | null);
+}
+export interface FakeRasterizerOptions {
+    /** Surfaced as `PageRasterizer.id` and in diagnostics. */
+    id?: string;
+    /** Cycled if `pageCount` exceeds its length. Defaults to a single LETTER. */
+    pageSizes?: readonly DocSize[];
+    /** Defaults to `pageSizes.length`, or 3. */
+    pageCount?: number;
+    /**
+     * Cycled, defaults to 0. Informational only: per the contract, page width and
+     * height are already post-rotation, so the fake does not swap them.
+     */
+    pageRotations?: readonly PageRotation[];
+    /** Checker cell size in DOC units. */
+    checkerDocSize?: number;
+    format?: PixelFormat;
+    /** Artificial delay on `render()` only; `open()` always resolves promptly. */
+    latencyMs?: number;
+    /** When set, `open()` enforces it against `source.password`. */
+    password?: string;
+    fail?: FakeFailureModes;
+    /** Refuse absurd requests so a planner bug is a test failure, not an OOM. */
+    maxPixels?: number;
+    /**
+     * Reported as `RasterizerCapabilities.maxConcurrentRenders`.
+     *
+     * DEFAULTS TO 1, which is the honest answer for the pixel loop below: it is
+     * synchronous, so a second `render` cannot make progress while the first is
+     * running whatever the caller does. Raise it in a test or a demo that wants
+     * the controller's LANES exercised — with `latencyMs` set, the fake's awaits
+     * genuinely interleave and the schedule is what is under test, not the pixels.
+     */
+    maxConcurrentRenders?: number;
+}
+/**
+ * The pixel size the fake renders a request at.
+ *
+ * Exported because RasterRequest carries no PixelSize — a backend derives it —
+ * and a test that wants to index into the output needs the same arithmetic.
+ * Rounding (rather than ceiling) keeps the raster closest to the nominal
+ * scale; either is safe, because `PdfRaster.docRect` is the request's doc rect
+ * regardless and `fit="fill"` absorbs the sub-pixel difference.
+ */
+export declare const fakePixelSize: (request: RasterRequest) => PixelSize;
+/**
+ * A distinct flat colour per page. Golden-angle hue rotation puts consecutive
+ * pages maximally far apart in hue, so page 4 is never mistaken for page 5 in a
+ * screenshot of a scrolling document.
+ */
+export declare function fakePageColor(page: number): [number, number, number];
+/**
+ * Read the doc rect a fake raster believes it covers, or null when the raster
+ * was too small to carry a swatch.
+ */
+export declare function decodeFakeDocRect(pixels: RasterPixels): DocRect | null;
+export declare function createFakeRasterizer(options?: FakeRasterizerOptions): PageRasterizer;