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

package/dist/testing/scenes.js

@@ -0,0 +1,267 @@
+/**
+ * Reference scenes: the composition contract, stated as DATA.
+ *
+ * BUILD STEP 1 pixel-snapshots the composition of a set of rasters offscreen and
+ * calls the result the reference every backend is later checked against. The
+ * IMAGES cannot be that reference on their own — they are specific to whichever
+ * document produced the bytes, so a PDFium suite and a PDFKit suite would never
+ * agree byte for byte. What generalises is the SCENE: which rasters the planner
+ * asked for, where the host transform puts them, and which canvas coordinates
+ * must be covered by what.
+ *
+ * A backend suite therefore uses this module as follows:
+ *
+ *   1. `buildReferenceScenes()` and pick a scene.
+ *   2. For each `scene.rasters`, hand `.request` to your own `RasterizerHandle`
+ *      and `.meta` to your `ingest`.
+ *   3. Compose them into a `PdfContent`, draw it through `PdfContentView` inside
+ *      `<Group transform={referenceTransform(scene.transform)}>` on a
+ *      `scene.canvas`-sized surface.
+ *   4. Assert `scene.probes`: every 'raster' probe must be opaque, every
+ *      'nothing' probe must be untouched.
+ *
+ * SKIA-FREE, like the rest of `src/testing/`. It reaches `planRasters` (pure) and
+ * nothing else — the plan is DERIVED here rather than hand-written, so a change
+ * to the splitting rule shows up as a changed scene rather than as a scene that
+ * quietly stops describing what the planner does.
+ */
+import { planRasters } from '../planner.js';
+import { resolvePolicy } from '../policy.js';
+import { LETTER } from '../rasterizer/fake.js';
+export function docToCanvas(transform, docX, docY) {
+    return {
+        x: docX * transform.scale + transform.translateX,
+        y: docY * transform.scale + transform.translateY,
+    };
+}
+export function docRectToCanvas(transform, rect) {
+    const origin = docToCanvas(transform, rect.x, rect.y);
+    return {
+        x: origin.x,
+        y: origin.y,
+        width: rect.width * transform.scale,
+        height: rect.height * transform.scale,
+    };
+}
+/**
+ * Plan item -> backend request.
+ *
+ * `annotations: false` and `background: 'white'` match what the tile path asks
+ * for in production (the app draws its own annotations above, and an unfilled
+ * buffer composites as black — see `ingest.ts`).
+ */
+export function sceneRasterRequest(item, over = {}) {
+    return {
+        page: item.page,
+        docRect: item.docRect,
+        scale: item.scale,
+        annotations: false,
+        background: 'white',
+        ...over,
+    };
+}
+export function sceneRasterMeta(item, epoch = 1) {
+    return {
+        key: item.key,
+        page: item.page,
+        role: item.role,
+        docRect: item.docRect,
+        scale: item.scale,
+        epoch,
+    };
+}
+function toSceneRasters(plan, epoch = 1) {
+    return plan.items.map(item => ({
+        item,
+        request: sceneRasterRequest(item),
+        meta: sceneRasterMeta(item, epoch),
+    }));
+}
+function letterPage() {
+    return {
+        pages: [
+            { index: 0, width: LETTER.width, height: LETTER.height, rotation: 0 },
+        ],
+        pageRects: [{ x: 0, y: 0, width: LETTER.width, height: LETTER.height }],
+    };
+}
+/**
+ * Scene 1 — a whole LETTER page at fit zoom, drawn under a translated,
+ * downscaled host transform.
+ *
+ * The planner emits a BASE and no detail here (the base is already at the
+ * display scale, so detail would be the same pixels twice), which makes this the
+ * scene that proves the base layer alone paints the page and paints it inside
+ * the page rect.
+ */
+function fitScene() {
+    const { pages, pageRects } = letterPage();
+    const policy = resolvePolicy();
+    const viewport = {
+        visibleDocRect: { x: 0, y: 0, width: LETTER.width, height: LETTER.height },
+        scale: 0.5,
+    };
+    const plan = planRasters({
+        viewport,
+        pages,
+        pageRects,
+        visiblePages: [0],
+        policy,
+    });
+    const transform = {
+        scale: 0.5,
+        translateX: 20,
+        translateY: 20,
+    };
+    return {
+        id: 'letter-fit',
+        description: 'One LETTER page at fit zoom under a translated 0.5x host transform. ' +
+            'Base raster only — the planner suppresses detail when the base is ' +
+            'already at the display scale.',
+        canvas: { width: 400, height: 440 },
+        transform,
+        pages,
+        pageRects,
+        viewport,
+        policy,
+        plan,
+        rasters: toSceneRasters(plan),
+        probes: [
+            {
+                docX: LETTER.width / 2,
+                docY: LETTER.height / 2,
+                expect: 'raster',
+                why: 'the base raster must cover the middle of the page',
+            },
+            {
+                docX: 1,
+                docY: 1,
+                expect: 'raster',
+                why: 'the top-left of the page is inside the base rect; a base drawn ' +
+                    'letterboxed (fit="contain") or offset by the host translate leaves ' +
+                    'it blank',
+            },
+            {
+                docX: LETTER.width - 1,
+                docY: LETTER.height - 1,
+                expect: 'raster',
+                why: 'the bottom-right corner of the page, same reasoning',
+            },
+            {
+                docX: -20,
+                docY: -20,
+                expect: 'nothing',
+                why: 'outside the page rect. A base that ignored its doc rect and filled ' +
+                    'the canvas would paint here.',
+            },
+        ],
+    };
+}
+/**
+ * Scene 2 — a detail set the planner SPLITS into a 2x2 grid, over a base that
+ * stays ONE piece.
+ *
+ * `maxTextureDimension` is lowered so the split is the PLANNER's decision, driven
+ * by the same code path a 4096-limited device takes on a large sheet. The canvas
+ * is 1:1 with the detail scale, so a correctly-placed piece lands on whole canvas
+ * pixels and the composite can be compared against the same region rastered as a
+ * single piece.
+ *
+ * THE NUMBER IS 512 BECAUSE THE SHAPE IS CHOSEN, NOT INHERITED. It was 320, and
+ * `min(maxPieceDimension, maxTextureDimension)` therefore tiled the BASE into two
+ * pieces as well (the base is 309x400 device px here) — a change no probe in this
+ * scene could see, because the second base piece begins at doc y ~394 and the
+ * canvas stops at doc y 360. A backend suite is diffed against these scenes, so
+ * how many rasters one asks for is part of the contract and may not drift out of
+ * a default. 512 divides the 600px detail target and leaves the base whole; the
+ * detail grid is byte-for-byte the one 320 produced, because both give
+ * `ceil(600 / usable) == 2`. `composition.test.ts` pins both counts.
+ *
+ * The host translate is POSITIVE and the canvas is larger than the detail
+ * target, which is what buys the scene a 'nothing' probe. With the target
+ * mapped exactly onto the canvas — the obvious framing — every canvas pixel is
+ * inside the page, the whole-page base paints all of them, and no coordinate is
+ * left for "must be untouched" to describe. A scene with only 'raster' probes
+ * asserts nothing about a raster that overruns its rect.
+ */
+function splitDetailScene() {
+    const { pages, pageRects } = letterPage();
+    const policy = resolvePolicy({ maxTextureDimension: 512 });
+    const viewport = {
+        visibleDocRect: { x: 100, y: 100, width: 200, height: 200 },
+        scale: 2,
+    };
+    const plan = planRasters({
+        viewport,
+        pages,
+        pageRects,
+        visiblePages: [0],
+        policy,
+    });
+    // detailOverflow 0.25 inflates {100,100,200,200} to {50,50,300,300}, entirely
+    // inside the page, so the covered rect is exactly that. The translate puts
+    // doc (0,0) at canvas (20,20), so the target occupies canvas [120, 720) on
+    // both axes and a 20px margin of NEGATIVE doc space stays visible.
+    const transform = {
+        scale: 2,
+        translateX: 20,
+        translateY: 20,
+    };
+    return {
+        id: 'letter-split-detail',
+        description: 'A 300x300pt detail target at scale 2, split into a 2x2 grid by a ' +
+            '512px texture limit, over a single whole-page base. Canvas is 1:1 with ' +
+            'the detail scale, with a margin of off-page canvas around it.',
+        canvas: { width: 740, height: 740 },
+        transform,
+        pages,
+        pageRects,
+        viewport,
+        policy,
+        plan,
+        rasters: toSceneRasters(plan),
+        probes: [
+            {
+                docX: 50.25,
+                docY: 50.25,
+                expect: 'raster',
+                why: 'top-left corner of the detail target',
+            },
+            {
+                docX: 349.75,
+                docY: 349.75,
+                expect: 'raster',
+                why: 'bottom-right corner of the detail target',
+            },
+            {
+                docX: 200,
+                docY: 200,
+                expect: 'raster',
+                why: 'the interior seam. Pieces OVERLAP rather than abut, so no doc ' +
+                    'coordinate inside the target may be uncovered.',
+            },
+            {
+                docX: -5,
+                docY: -5,
+                expect: 'nothing',
+                why: 'off the page entirely, and the only kind of point that can be ' +
+                    'unpainted in this scene — the base covers the whole sheet. A base ' +
+                    'or a detail piece that ignored its doc rect and filled the canvas ' +
+                    'paints here, and every other probe in this scene would still pass.',
+            },
+        ],
+    };
+}
+export function buildReferenceScenes() {
+    return [fitScene(), splitDetailScene()];
+}
+export function referenceScene(id) {
+    const scene = buildReferenceScenes().find(s => s.id === id);
+    if (!scene) {
+        throw new Error(`No reference scene '${id}'. Known: ` +
+            buildReferenceScenes()
+                .map(s => s.id)
+                .join(', '));
+    }
+    return scene;
+}