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

package/dist/skia/resolve.web.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The WEB resolver: build the Skia api from `globalThis.CanvasKit`, lazily.
+ *
+ * WEB ONLY. Nothing native ever imports this file — the `react-native`
+ * condition of every `exports` entry points at an `index.native.js` that reaches
+ * `./resolve.native.js` instead — so the whole JsiSk* web implementation stays
+ * out of the RN bundle.
+ *
+ * ------------------------------------------------------------------------
+ * WHY `JsiSkApi(CanvasKit)` AND NOT AN IMPORT OF `Skia`
+ * ------------------------------------------------------------------------
+ *
+ * Because it is the same expression, evaluated at the right time.
+ * `lib/module/skia/Skia.web.js` IS `JsiSkApi(global.CanvasKit)`; the only thing
+ * wrong with it is WHEN it runs. Importing `JsiSkApi` from the deep
+ * `skia/web` path gets the factory without evaluating the module that calls it
+ * too early — VERIFIED by bundling, not by reading imports: a Vite build of
+ * `lib/module/skia/web/index.js` contains no `JsiSkApi(global.CanvasKit)`, while
+ * a build of the bare `@shopify/react-native-skia` specifier does.
+ *
+ * The api this produces is a SECOND JsiSkApi object, distinct from the one
+ * `Skia.web.js` builds for RN Skia's own renderer. That is harmless and was
+ * checked rather than assumed: both come from the same `skia/web` module, so the
+ * classes (`JsiSkImage`, `JsiSkData`, …) are identical objects and an image made
+ * here is exactly the image the reconciler expects. Only the factory wrapper is
+ * duplicated, and it holds no cross-call state that matters here.
+ *
+ * The deep path is legal because `@shopify/react-native-skia` publishes `lib/**`
+ * and declares no `exports` map. Same standing as boldr-utils' import of
+ * `@shopify/react-native-skia/lib/module/web/index.js` for `WithSkiaWeb`. If
+ * they ever add an `exports` map, both break together and the fix is whatever
+ * public entry replaces them.
+ */
+/**
+ * Install the web resolver.
+ *
+ * Idempotent and free: it stores a closure. Nothing reads `globalThis.CanvasKit`
+ * until the first raster is ingested, which is the entire point — a route module
+ * that merely names this package must not decide anything about CanvasKit.
+ */
+export declare function installWebSkiaResolver(): void;

package/dist/skia/resolve.web.js

@@ -0,0 +1,62 @@
+/**
+ * The WEB resolver: build the Skia api from `globalThis.CanvasKit`, lazily.
+ *
+ * WEB ONLY. Nothing native ever imports this file — the `react-native`
+ * condition of every `exports` entry points at an `index.native.js` that reaches
+ * `./resolve.native.js` instead — so the whole JsiSk* web implementation stays
+ * out of the RN bundle.
+ *
+ * ------------------------------------------------------------------------
+ * WHY `JsiSkApi(CanvasKit)` AND NOT AN IMPORT OF `Skia`
+ * ------------------------------------------------------------------------
+ *
+ * Because it is the same expression, evaluated at the right time.
+ * `lib/module/skia/Skia.web.js` IS `JsiSkApi(global.CanvasKit)`; the only thing
+ * wrong with it is WHEN it runs. Importing `JsiSkApi` from the deep
+ * `skia/web` path gets the factory without evaluating the module that calls it
+ * too early — VERIFIED by bundling, not by reading imports: a Vite build of
+ * `lib/module/skia/web/index.js` contains no `JsiSkApi(global.CanvasKit)`, while
+ * a build of the bare `@shopify/react-native-skia` specifier does.
+ *
+ * The api this produces is a SECOND JsiSkApi object, distinct from the one
+ * `Skia.web.js` builds for RN Skia's own renderer. That is harmless and was
+ * checked rather than assumed: both come from the same `skia/web` module, so the
+ * classes (`JsiSkImage`, `JsiSkData`, …) are identical objects and an image made
+ * here is exactly the image the reconciler expects. Only the factory wrapper is
+ * duplicated, and it holds no cross-call state that matters here.
+ *
+ * The deep path is legal because `@shopify/react-native-skia` publishes `lib/**`
+ * and declares no `exports` map. Same standing as boldr-utils' import of
+ * `@shopify/react-native-skia/lib/module/web/index.js` for `WithSkiaWeb`. If
+ * they ever add an `exports` map, both break together and the fix is whatever
+ * public entry replaces them.
+ */
+import { JsiSkApi } from '@shopify/react-native-skia/lib/module/skia/web/index.js';
+import { setSkiaApiResolver } from './skia-api.js';
+/**
+ * Install the web resolver.
+ *
+ * Idempotent and free: it stores a closure. Nothing reads `globalThis.CanvasKit`
+ * until the first raster is ingested, which is the entire point — a route module
+ * that merely names this package must not decide anything about CanvasKit.
+ */
+export function installWebSkiaResolver() {
+    setSkiaApiResolver(() => {
+        const canvasKit = globalThis.CanvasKit;
+        // Null, not a throw: `skiaApi()` owns the one error message, and "CanvasKit
+        // is not loaded yet" is exactly the state that message describes.
+        if (canvasKit === undefined || canvasKit === null) {
+            return null;
+        }
+        // THE CAST IS AN ARTIFACT OF DUPLICATE DECLARATIONS, NOT A LOOSENING.
+        //
+        // RN Skia ships its types twice — `lib/typescript/src/**` (what the bare
+        // specifier resolves to, and what `SkiaApi` is taken from) and co-located
+        // `lib/module/**` copies (what this deep import resolves to). The two are
+        // generated from the same source, but TypeScript treats their `NodeType`
+        // enums as nominally distinct, so the structurally-identical results do not
+        // assign. `unknown` in the middle rather than a direct assertion because TS
+        // rejects even the direct one for the same reason.
+        return JsiSkApi(canvasKit);
+    });
+}

package/dist/skia/skia-api.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The Skia runtime, resolved AT CALL TIME.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: `Skia` ON WEB IS BUILT ONCE, AT IMPORT TIME.
+ * ------------------------------------------------------------------------
+ *
+ * `@shopify/react-native-skia`'s web build is, in its entirety:
+ *
+ *     // lib/module/skia/Skia.web.js
+ *     import {JsiSkApi} from "./web";
+ *     export const Skia = JsiSkApi(global.CanvasKit);
+ *
+ * That is a MODULE-SCOPE call. If the module is evaluated before `LoadSkiaWeb`
+ * has resolved, `global.CanvasKit` is `undefined`, every factory in the returned
+ * object closes over `undefined`, and the damage is PERMANENT and unrecoverable
+ * in-bundle: re-importing the specifier returns the identical broken object,
+ * because ES module evaluation happens once.
+ *
+ * And it is not hard to trigger. `Skia.web.js` is reached from the package root
+ * barrel (`lib/module/index.js` -> `export * from "./skia"` -> `export {Skia}
+ * from "./Skia"`), `@shopify/react-native-skia` declares no `sideEffects: false`
+ * and no `exports` map, so **any** value import from the bare specifier — a
+ * `<Group>`, a `ColorType` — evaluates it. rock-desktop is `{ssr: true}` with no
+ * prerender, so every route module is evaluated in Node on every request; one
+ * route that names a barrel which names Skia's barrel is enough.
+ *
+ * So this module never names `Skia` at module scope. It holds a RESOLVER, and
+ * `skiaApi()` calls it on the first raster and caches the answer.
+ *
+ * ------------------------------------------------------------------------
+ * WHO INSTALLS THE RESOLVER
+ * ------------------------------------------------------------------------
+ *
+ *   native   `./resolve.native.js`, from `src/index.native.ts` and
+ *            `src/skia/index.native.ts`. It DOES import the bare specifier —
+ *            correctly, because on native `Skia` is `global.SkiaApi`, installed
+ *            by RN Skia's own `NativeSetup` side effect at import. There is no
+ *            ordering hazard on native at all; this whole file is a web problem.
+ *   web      `./resolve.web.js`, from `src/index.web.ts` and
+ *            `src/skia/index.web.ts`. It builds the api from
+ *            `globalThis.CanvasKit` on first use, so nothing is decided at
+ *            import time.
+ *   host     `loadPdfCanvasSkiaWeb()` from the `./web-init` subpath installs it
+ *            too, after awaiting CanvasKit. That is the explicit, awaitable
+ *            ordering guarantee a web host should prefer.
+ *
+ * A host with its own arrangement can call `setSkiaApiResolver` directly.
+ */
+import type { Skia as SkiaConst } from '@shopify/react-native-skia';
+/**
+ * The shape of RN Skia's `Skia`, taken from the BARE specifier.
+ *
+ * `import type` is erased entirely — it reaches no module at runtime and is
+ * therefore the one form of `@shopify/react-native-skia` import that is always
+ * safe here. `typeof` rather than a direct type import because the package's
+ * root exports `Skia` as a VALUE (`export {Skia} from "./Skia"`), which shadows
+ * the same-named interface its `./types` star-export carries.
+ *
+ * It must come from the bare specifier and not from a deep `lib/module/...`
+ * path: the package ships its declarations twice (`lib/typescript/src/**`, which
+ * the bare specifier resolves to, and co-located `lib/module/**` copies), and
+ * TypeScript treats the two copies' `NodeType` enums as NOMINALLY distinct. Mix
+ * them and every assignment needs a cast.
+ */
+export type SkiaApi = typeof SkiaConst;
+/**
+ * Produce the Skia api, or null if it is not available YET.
+ *
+ * Returning null rather than throwing matters: an installed resolver that cannot
+ * answer yet falls through to the remaining strategies below instead of
+ * short-circuiting them, and the single error message at the end of the chain is
+ * the one the caller sees.
+ */
+export type SkiaApiResolver = () => SkiaApi | null;
+/**
+ * Install the resolver. Returns the previous one so a test can restore it.
+ *
+ * Installing CLEARS the cache. A resolver swap is a statement that the previous
+ * answer is no longer the right one — the alternative (keeping a stale api that
+ * a `LoadSkiaWeb` retry has just superseded) is the failure this whole module
+ * exists to prevent.
+ */
+export declare function setSkiaApiResolver(next: SkiaApiResolver | null): SkiaApiResolver | null;
+/**
+ * The Skia api, resolved on first use and cached.
+ *
+ * Call this INSIDE the function that needs it, never at module scope — the
+ * moment the result is stored in a module-level `const` this file has
+ * reintroduced the bug it exists to remove.
+ */
+export declare function skiaApi(): SkiaApi;
+/** Drop the cached api AND the installed resolver. Tests only. */
+export declare function resetSkiaApiForTests(): void;

package/dist/skia/skia-api.js

@@ -0,0 +1,113 @@
+/**
+ * The Skia runtime, resolved AT CALL TIME.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: `Skia` ON WEB IS BUILT ONCE, AT IMPORT TIME.
+ * ------------------------------------------------------------------------
+ *
+ * `@shopify/react-native-skia`'s web build is, in its entirety:
+ *
+ *     // lib/module/skia/Skia.web.js
+ *     import {JsiSkApi} from "./web";
+ *     export const Skia = JsiSkApi(global.CanvasKit);
+ *
+ * That is a MODULE-SCOPE call. If the module is evaluated before `LoadSkiaWeb`
+ * has resolved, `global.CanvasKit` is `undefined`, every factory in the returned
+ * object closes over `undefined`, and the damage is PERMANENT and unrecoverable
+ * in-bundle: re-importing the specifier returns the identical broken object,
+ * because ES module evaluation happens once.
+ *
+ * And it is not hard to trigger. `Skia.web.js` is reached from the package root
+ * barrel (`lib/module/index.js` -> `export * from "./skia"` -> `export {Skia}
+ * from "./Skia"`), `@shopify/react-native-skia` declares no `sideEffects: false`
+ * and no `exports` map, so **any** value import from the bare specifier — a
+ * `<Group>`, a `ColorType` — evaluates it. rock-desktop is `{ssr: true}` with no
+ * prerender, so every route module is evaluated in Node on every request; one
+ * route that names a barrel which names Skia's barrel is enough.
+ *
+ * So this module never names `Skia` at module scope. It holds a RESOLVER, and
+ * `skiaApi()` calls it on the first raster and caches the answer.
+ *
+ * ------------------------------------------------------------------------
+ * WHO INSTALLS THE RESOLVER
+ * ------------------------------------------------------------------------
+ *
+ *   native   `./resolve.native.js`, from `src/index.native.ts` and
+ *            `src/skia/index.native.ts`. It DOES import the bare specifier —
+ *            correctly, because on native `Skia` is `global.SkiaApi`, installed
+ *            by RN Skia's own `NativeSetup` side effect at import. There is no
+ *            ordering hazard on native at all; this whole file is a web problem.
+ *   web      `./resolve.web.js`, from `src/index.web.ts` and
+ *            `src/skia/index.web.ts`. It builds the api from
+ *            `globalThis.CanvasKit` on first use, so nothing is decided at
+ *            import time.
+ *   host     `loadPdfCanvasSkiaWeb()` from the `./web-init` subpath installs it
+ *            too, after awaiting CanvasKit. That is the explicit, awaitable
+ *            ordering guarantee a web host should prefer.
+ *
+ * A host with its own arrangement can call `setSkiaApiResolver` directly.
+ */
+import { PdfError } from '../types.js';
+let resolver = null;
+let cached = null;
+/**
+ * Install the resolver. Returns the previous one so a test can restore it.
+ *
+ * Installing CLEARS the cache. A resolver swap is a statement that the previous
+ * answer is no longer the right one — the alternative (keeping a stale api that
+ * a `LoadSkiaWeb` retry has just superseded) is the failure this whole module
+ * exists to prevent.
+ */
+export function setSkiaApiResolver(next) {
+    const previous = resolver;
+    resolver = next;
+    cached = null;
+    return previous;
+}
+/**
+ * The native JSI global, read the way RN Skia itself reads it.
+ *
+ * `lib/module/skia/Skia.js` — the NATIVE half of the same platform pair — is
+ * literally `export const Skia = SkiaApi;`, i.e. a read of the global that
+ * `NativeSetup` installs. Consulting it here is not a guess about internals; it
+ * is the same one-liner, deferred. It exists so that a native consumer who
+ * reached this module through a shared submodule (rather than through
+ * `index.native.ts`) still gets a working api instead of an error about web
+ * initialisation.
+ *
+ * On web and under vitest the global is absent, so this contributes nothing.
+ */
+function nativeGlobalSkia() {
+    const global = globalThis;
+    return global.SkiaApi ?? null;
+}
+const UNAVAILABLE = 'The Skia runtime is not available yet. On web, CanvasKit is loaded ' +
+    'asynchronously and `Skia` is built from it ONCE, so it must be loaded ' +
+    'before the first raster: await `loadPdfCanvasSkiaWeb()` from ' +
+    "'@reekon-tools/react-native-pdf-canvas/web-init' (or RN Skia's own " +
+    '`LoadSkiaWeb`) during startup. On native this means ' +
+    '@shopify/react-native-skia never installed its JSI bindings — rebuild the ' +
+    'app rather than reloading the bundle.';
+/**
+ * The Skia api, resolved on first use and cached.
+ *
+ * Call this INSIDE the function that needs it, never at module scope — the
+ * moment the result is stored in a module-level `const` this file has
+ * reintroduced the bug it exists to remove.
+ */
+export function skiaApi() {
+    if (cached !== null) {
+        return cached;
+    }
+    const resolved = resolver?.() ?? nativeGlobalSkia();
+    if (resolved === null || resolved === undefined) {
+        throw new PdfError('unsupported', UNAVAILABLE);
+    }
+    cached = resolved;
+    return resolved;
+}
+/** Drop the cached api AND the installed resolver. Tests only. */
+export function resetSkiaApiForTests() {
+    resolver = null;
+    cached = null;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `@reekon-tools/react-native-pdf-canvas/testing` subpath.
+ *
+ * SKIA-FREE BY CONTRACT. Nothing reachable from this file may import
+ * `@shopify/react-native-skia`, react-native or reanimated — it is imported by
+ * vitest suites running in a bare node environment, where any of those would
+ * fail at module load. In particular it reaches `../rasterizer/fake.js`
+ * directly and never `../rasterizer/index.js`, which pulls in the Skia ingest
+ * path.
+ */
+export { ARCH_D, ARCH_E, LETTER, createFakeRasterizer, decodeFakeDocRect, fakePageColor, fakePixelSize, } from '../rasterizer/fake.js';
+export type { FakeFailureModes, FakeRasterizerOptions, } from '../rasterizer/fake.js';
+/**
+ * The reference scenes BUILD STEP 1 produced: the composition contract as data,
+ * for a backend suite to replay against its own rasterizer. Pure — it reaches
+ * `planRasters` and nothing else.
+ */
+export { buildReferenceScenes, docRectToCanvas, docToCanvas, referenceScene, sceneRasterMeta, sceneRasterRequest, } from './scenes.js';
+export type { CanvasPoint, ProbeExpectation, ReferenceScene, SceneProbe, SceneRaster, SceneTransform, } from './scenes.js';
+import type { DocRect, DocSize, PageGeometry, PageRotation, ViewportSnapshot } from '../types.js';
+export declare function makePageGeometry(index: number, size: DocSize, rotation?: PageRotation): PageGeometry;
+/**
+ * `scale` is DEVICE PIXELS PER PDF POINT — zoom multiplied by pixel ratio,
+ * already combined. Passing a bare zoom here is the single easiest way to write
+ * a test that agrees with itself and disagrees with the device.
+ */
+export declare function makeViewport(visibleDocRect: DocRect, scale: number): ViewportSnapshot;

package/dist/testing/index.js

@@ -0,0 +1,28 @@
+/**
+ * The `@reekon-tools/react-native-pdf-canvas/testing` subpath.
+ *
+ * SKIA-FREE BY CONTRACT. Nothing reachable from this file may import
+ * `@shopify/react-native-skia`, react-native or reanimated — it is imported by
+ * vitest suites running in a bare node environment, where any of those would
+ * fail at module load. In particular it reaches `../rasterizer/fake.js`
+ * directly and never `../rasterizer/index.js`, which pulls in the Skia ingest
+ * path.
+ */
+export { ARCH_D, ARCH_E, LETTER, createFakeRasterizer, decodeFakeDocRect, fakePageColor, fakePixelSize, } from '../rasterizer/fake.js';
+/**
+ * The reference scenes BUILD STEP 1 produced: the composition contract as data,
+ * for a backend suite to replay against its own rasterizer. Pure — it reaches
+ * `planRasters` and nothing else.
+ */
+export { buildReferenceScenes, docRectToCanvas, docToCanvas, referenceScene, sceneRasterMeta, sceneRasterRequest, } from './scenes.js';
+export function makePageGeometry(index, size, rotation = 0) {
+    return { index, width: size.width, height: size.height, rotation };
+}
+/**
+ * `scale` is DEVICE PIXELS PER PDF POINT — zoom multiplied by pixel ratio,
+ * already combined. Passing a bare zoom here is the single easiest way to write
+ * a test that agrees with itself and disagrees with the device.
+ */
+export function makeViewport(visibleDocRect, scale) {
+    return { visibleDocRect, scale };
+}

package/dist/testing/scenes.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 type { RasterIngestMeta } from '../controller.js';
+import type { DocRect, PageGeometry, PixelSize, RasterPlan, RasterPlanItem, RasterPolicy, RasterRequest, ViewportSnapshot } from '../types.js';
+/**
+ * The host's doc -> canvas mapping: `canvas = doc * scale + translate`.
+ *
+ * Deliberately NOT a Skia matrix. `src/testing/` may not import Skia, and the
+ * package is transform-agnostic anyway — this is the arithmetic a consumer's
+ * own world transform performs, whatever type it stores it in.
+ */
+export interface SceneTransform {
+    scale: number;
+    translateX: number;
+    translateY: number;
+}
+export interface CanvasPoint {
+    x: number;
+    y: number;
+}
+export declare function docToCanvas(transform: SceneTransform, docX: number, docY: number): CanvasPoint;
+export declare function docRectToCanvas(transform: SceneTransform, rect: DocRect): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * What must be true at a doc-space point once the scene is composited.
+ *
+ * Colour-free on purpose: a probe that named an RGB value would only ever be
+ * checkable against the fake. 'raster' means SOMETHING opaque was painted;
+ * 'nothing' means the surface was never touched. Those two hold for every
+ * backend and catch the placement bugs that matter.
+ */
+export type ProbeExpectation = 'raster' | 'nothing';
+export interface SceneProbe {
+    docX: number;
+    docY: number;
+    expect: ProbeExpectation;
+    /** Which bug flips this probe. Not decoration — see the suite. */
+    why: string;
+}
+/** One raster the scene needs, in both the shapes a backend harness wants. */
+export interface SceneRaster {
+    item: RasterPlanItem;
+    request: RasterRequest;
+    meta: RasterIngestMeta;
+}
+export interface ReferenceScene {
+    id: string;
+    description: string;
+    /** Offscreen surface size, in canvas pixels. */
+    canvas: PixelSize;
+    transform: SceneTransform;
+    pages: PageGeometry[];
+    /** Parallel to `pages`. */
+    pageRects: DocRect[];
+    viewport: ViewportSnapshot;
+    policy: RasterPolicy;
+    plan: RasterPlan;
+    rasters: SceneRaster[];
+    probes: SceneProbe[];
+}
+/**
+ * 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 declare function sceneRasterRequest(item: RasterPlanItem, over?: Partial<RasterRequest>): RasterRequest;
+export declare function sceneRasterMeta(item: RasterPlanItem, epoch?: number): RasterIngestMeta;
+export declare function buildReferenceScenes(): ReferenceScene[];
+export declare function referenceScene(id: string): ReferenceScene;