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

package/dist/react/usePdfLayer.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The React binding for the raster controller.
+ *
+ * THIS HOOK BELONGS ABOVE THE `<Canvas>`, NOT INSIDE IT. Two reasons, and both
+ * are load-bearing:
+ *
+ *  1. React context does not cross the Canvas boundary. RN Skia mounts its own
+ *     reconciler for the Skia subtree, so a provider placed inside a `<Canvas>`
+ *     is invisible to the host's tree — and a provider outside it is invisible to
+ *     the Skia children. Anything shared has to be a prop, which is exactly what
+ *     `content` is.
+ *  2. A magnifier loupe is a SECOND `<Canvas>` looking at the same document. If
+ *     the cache were instantiated inside the canvas subtree there would be two of
+ *     them, live at the same time, each with its own copy of every base raster —
+ *     double the memory for pixels that are identical. Hoisting the hook above
+ *     both canvases and passing the same `content` down is what makes the loupe
+ *     free.
+ *
+ * The hook contributes ZERO Reanimated shared values to the Skia subtree. The
+ * host's transform does the panning and zooming; this hook only ever hears about
+ * the viewport through the `controller` methods the host calls.
+ */
+import type { PdfContent, PdfController, PdfDiagnostic, PdfPageLayout, RasterPolicy } from '../types.js';
+import type { PdfDocument } from './usePdfDocument.js';
+/**
+ * Only the pages the viewport actually intersects may hold rasters.
+ *
+ * THE HONEST SPELLING OF THE DEFAULT, and the one to use. It carries no tuning
+ * number because there is no tuning to do: see `PdfPageWindow` for the knob this
+ * replaces and why that knob was a lie.
+ */
+export interface PdfOnScreenPages {
+    readonly onScreen: true;
+}
+/**
+ * @deprecated THE RADIUS IS NOT IMPLEMENTED. `{window: 3}` behaves exactly like
+ * `{window: 0}` and always has — a window resolves to no allow-list at all (see
+ * `resolveAllowedPages`), so the number has nowhere to go. Use
+ * `{onScreen: true}`, which means what this does; or an explicit `number[]` if
+ * you want a genuine allow-list. Implementing the radius needs
+ * `PdfControllerOptions` to accept a per-viewport allow-list — an
+ * `(visiblePages: readonly number[]) => ReadonlySet<number>` in place of the set,
+ * or a plain `pageWindow` radius the planner applies — and until then this member
+ * exists only so an existing `{window: n}` call site keeps compiling.
+ */
+export interface PdfPageWindow {
+    readonly window: number;
+}
+/**
+ * Which pages may hold rasters: an explicit allow-list, or every page the
+ * viewport is currently over.
+ */
+export type PdfPageSelection = readonly number[] | PdfOnScreenPages | PdfPageWindow;
+/**
+ * THE DEFAULT IS THE PAGES ON SCREEN, NEVER "ALL". A 400-page architectural spec
+ * book at ARCH-D holds roughly 10 MiB in a single base raster; "all" is therefore
+ * about 4 GiB of standing allocation before a single detail raster exists. The
+ * controller retains the bases of pages two either side of the plan's window, so
+ * a page-turn in a continuous layout still lands on an already-warm base.
+ */
+export declare const DEFAULT_PAGE_SELECTION: PdfPageSelection;
+export interface UsePdfLayerOptions {
+    /** From `usePdfDocument`. Null while loading; the hook returns empty content. */
+    document: PdfDocument | null;
+    /**
+     * @default {onScreen: true} — see DEFAULT_PAGE_SELECTION.
+     *
+     * A one-element list is what single-page (paged) mode is made of:
+     * `{layout: singlePage(), pages: [pageIndex]}`. Changing the list REBUILDS the
+     * controller and clears its raster cache, which for a stacked layout is the
+     * correct trade — see the note on the memo below.
+     */
+    pages?: PdfPageSelection;
+    /**
+     * Where pages sit in doc space. The package has no opinion; see `./layout`.
+     *
+     * @default continuousVertical()
+     */
+    layout?: PdfPageLayout;
+    /** Overrides merged over the default `RasterPolicy`. */
+    policy?: Partial<RasterPolicy>;
+    onDiagnostic?: (diagnostic: PdfDiagnostic) => void;
+}
+export interface PdfLayer {
+    /** Pass straight to `<PdfContentView content={...} />`. */
+    content: PdfContent;
+    /**
+     * Drive this from the host's gesture handlers. Identity is stable for the life
+     * of the component — including across document changes — so it can be captured
+     * in a gesture callback without a dependency array.
+     */
+    controller: PdfController;
+}
+export declare function usePdfLayer({ document, pages: pageSelection, layout, policy, onDiagnostic, }: UsePdfLayerOptions): PdfLayer;

package/dist/react/usePdfLayer.js

@@ -0,0 +1,388 @@
+/**
+ * The React binding for the raster controller.
+ *
+ * THIS HOOK BELONGS ABOVE THE `<Canvas>`, NOT INSIDE IT. Two reasons, and both
+ * are load-bearing:
+ *
+ *  1. React context does not cross the Canvas boundary. RN Skia mounts its own
+ *     reconciler for the Skia subtree, so a provider placed inside a `<Canvas>`
+ *     is invisible to the host's tree — and a provider outside it is invisible to
+ *     the Skia children. Anything shared has to be a prop, which is exactly what
+ *     `content` is.
+ *  2. A magnifier loupe is a SECOND `<Canvas>` looking at the same document. If
+ *     the cache were instantiated inside the canvas subtree there would be two of
+ *     them, live at the same time, each with its own copy of every base raster —
+ *     double the memory for pixels that are identical. Hoisting the hook above
+ *     both canvases and passing the same `content` down is what makes the loupe
+ *     free.
+ *
+ * The hook contributes ZERO Reanimated shared values to the Skia subtree. The
+ * host's transform does the panning and zooming; this hook only ever hears about
+ * the viewport through the `controller` methods the host calls.
+ */
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
+import { createRasterCache } from '../cache.js';
+import { createPdfController } from '../controller.js';
+import { continuousVertical, hasOverlappingPages } from '../layout.js';
+import { resolvePolicy } from '../policy.js';
+// Through the `./skia` barrel, not `../rasterizer/ingest.js` directly: that
+// barrel is the documented home of the ingest seam, and routing every internal
+// consumer through it is what keeps "which modules can touch Skia" a list of one
+// directory rather than a grep. Nothing is paid for it — ingest itself no longer
+// names `Skia` at module scope (see `../skia/skia-api.ts`), so this hook stays
+// safe to evaluate before CanvasKit exists.
+import { ingestRaster } from '../skia/index.js';
+/** Same derivation as `PdfContentView`'s, restated rather than imported: that
+ * module reaches RN Skia's leaf components, and this hook must stay able to be
+ * evaluated before CanvasKit exists. */
+const IS_DEV = typeof __DEV__ !== 'undefined'
+    ? __DEV__ === true
+    : typeof process !== 'undefined' &&
+        process.env?.['NODE_ENV'] !== 'production';
+/**
+ * THE DEFAULT IS THE PAGES ON SCREEN, NEVER "ALL". A 400-page architectural spec
+ * book at ARCH-D holds roughly 10 MiB in a single base raster; "all" is therefore
+ * about 4 GiB of standing allocation before a single detail raster exists. The
+ * controller retains the bases of pages two either side of the plan's window, so
+ * a page-turn in a continuous layout still lands on an already-warm base.
+ */
+export const DEFAULT_PAGE_SELECTION = Object.freeze({
+    onScreen: true,
+});
+const isPageList = (selection) => Array.isArray(selection);
+/**
+ * An explicit list becomes a static allow-list, clamped to the pages the document
+ * actually has — an out-of-range index would otherwise plan a raster the backend
+ * can only reject.
+ *
+ * THE ON-SCREEN SELECTION RESOLVES TO `undefined`, i.e. no allow-list at all —
+ * the pages it names depend on the viewport, and no viewport exists when the
+ * controller is constructed. `undefined` is not "all": the controller plans only
+ * the pages intersecting the snapshot it is handed, and retains their bases two
+ * pages either side, so the standing cost is bounded by the screen.
+ *
+ * "Bounded by the screen" assumes page rects are DISJOINT. Under `singlePage()`
+ * every page rect is the same rect, every page is therefore on screen, and this
+ * returning `undefined` means the whole document is planned — N pages of bytes to
+ * draw one page, measured in `__tests__/single-page.test.ts`. That is what the
+ * `__DEV__` warning below is for, and why a stacked layout must be paired with a
+ * one-element list.
+ */
+function resolveAllowedPages(selection, pageCount) {
+    if (!isPageList(selection)) {
+        return undefined;
+    }
+    const allowed = new Set();
+    for (const page of selection) {
+        if (Number.isInteger(page) && page >= 0 && page < pageCount) {
+            allowed.add(page);
+        }
+    }
+    return allowed;
+}
+/* ------------------------------------------------------------------ *
+ * Owned resources
+ * ------------------------------------------------------------------ */
+/**
+ * `continuousVertical()` builds a fresh closure per call, and `layout` is a
+ * dependency of the controller. One module-level instance keeps the DEFAULT from
+ * looking like a layout change on every render and tearing the raster cache down
+ * with it.
+ *
+ * IT USED TO BE `singlePage()`, AND THAT WAS WRONG AS A DEFAULT. A stacked layout
+ * is correct only alongside a one-element `pages` list, and the default selection
+ * is the pages on screen — under `singlePage()` that is every page in the
+ * document, at one doc rect, drawn on top of each other. The two defaults
+ * contradicted each other, and nothing exercised the pair: both dev probes pass an
+ * explicit `continuousVertical(12)`. A continuous layout is safe with every
+ * selection, which is the only property a default needs to have.
+ */
+const DEFAULT_LAYOUT = continuousVertical();
+/**
+ * Idempotent by requirement, not by Skia's grace: on web a second
+ * `SkImage.dispose()` THROWS where native tolerates it. The cache guards its own
+ * paths, but this callback is the last thing holding the image and has to survive
+ * being reached twice — an eviction racing a teardown flush, or the same image
+ * somehow reaching two caches.
+ *
+ * Keyed on the SkImage rather than the PdfRaster, because the image is the thing
+ * that can be freed twice.
+ */
+const disposedImages = new WeakSet();
+function disposeRaster(raster) {
+    if (disposedImages.has(raster.image)) {
+        return;
+    }
+    disposedImages.add(raster.image);
+    raster.image.dispose();
+}
+/** Intrinsic geometry for every page, in page order. Cheap: loads no page. */
+function allPageGeometry(document) {
+    const geometry = [];
+    for (let index = 0; index < document.pageCount; index += 1) {
+        geometry.push(document.pageGeometry(index));
+    }
+    return geometry;
+}
+/* ------------------------------------------------------------------ *
+ * Empty state
+ * ------------------------------------------------------------------ */
+const EMPTY_PAGES = Object.freeze([]);
+/**
+ * Returned before a document exists. A STABLE frozen reference: `getSnapshot`
+ * handing back a fresh `{pages: [], epoch: 0}` on every call is the classic
+ * useSyncExternalStore infinite-render loop.
+ */
+const EMPTY_CONTENT = Object.freeze({
+    pages: EMPTY_PAGES,
+    epoch: 0,
+    settling: false,
+});
+const NOOP_UNSUBSCRIBE = () => { };
+const NOOP_SUBSCRIBE = () => NOOP_UNSUBSCRIBE;
+const getEmptyContent = () => EMPTY_CONTENT;
+/* ------------------------------------------------------------------ *
+ * Hook
+ * ------------------------------------------------------------------ */
+/**
+ * Stable structural key for a page selection, so an inline literal does not tear
+ * down and rebuild the controller (and its whole raster cache) every render.
+ *
+ * A list is SORTED and DEDUPED first, because the allow-list it resolves to is a
+ * Set and cannot tell `[3, 2]` from `[2, 3]`. Page navigation is exactly where a
+ * host builds these arrays programmatically, and rebuilding a controller over a
+ * reordering it cannot observe is a raster cache thrown away for nothing.
+ *
+ * Every window spelling collapses to the same key, since they all resolve to the
+ * same thing: no allow-list. `{window: 3}` and `{onScreen: true}` are the same
+ * controller.
+ */
+function pageSelectionKey(pages) {
+    if (!isPageList(pages)) {
+        return 'on-screen';
+    }
+    const sorted = [...new Set(pages)].sort((a, b) => a - b);
+    return `l:${sorted.join(',')}`;
+}
+/** Same, for a policy override object. Every RasterPolicy field is a number or a
+ * boolean, so a sorted key/value join is a complete description. */
+function policyKey(policy) {
+    if (policy === undefined) {
+        return '';
+    }
+    const keys = Object.keys(policy).sort();
+    let out = '';
+    for (const key of keys) {
+        out += `${key}=${String(policy[key])};`;
+    }
+    return out;
+}
+export function usePdfLayer({ document, 
+// The PUBLIC name stays `pages`; locally it is the SELECTION, and the
+// controller's own `pages` is the per-page geometry. Two very different things
+// one rename apart.
+pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, onDiagnostic, }) {
+    // The diagnostic callback is almost always an inline arrow. Route it through a
+    // ref so a fresh identity on every render never counts as a reason to rebuild
+    // the controller.
+    const onDiagnosticRef = useRef(onDiagnostic);
+    useEffect(() => {
+        onDiagnosticRef.current = onDiagnostic;
+    }, [onDiagnostic]);
+    const emitDiagnostic = useCallback((diagnostic) => {
+        onDiagnosticRef.current?.(diagnostic);
+    }, []);
+    const pagesKey = pageSelectionKey(pageSelection);
+    const policySignature = policyKey(policy);
+    /**
+     * Split out of the controller memo so the `__DEV__` check below can see the
+     * rects without re-running the layout, and so a warning lives in an EFFECT
+     * rather than inside a memo React is free to invoke twice.
+     */
+    const pageRects = useMemo(() => document === null
+        ? null
+        : (layout ?? DEFAULT_LAYOUT)(document.pageSizes()), [document, layout]);
+    /**
+     * A stacked layout (`singlePage()`) is correct ONLY with a one-element `pages`
+     * list. Any other selection lets every page hold a base at the same doc rect,
+     * and `PdfContentView` draws them in page order — so the memory is N pages and
+     * the page on screen is the highest allowed index, not the one the host meant.
+     *
+     * A warning and not a correction: silently narrowing the selection would make a
+     * host's `pages` prop mean something it does not say, and silently swapping the
+     * layout would move doc space under the host's transform.
+     */
+    useEffect(() => {
+        if (!IS_DEV || pageRects === null || document === null) {
+            return;
+        }
+        if (!hasOverlappingPages(pageRects)) {
+            return;
+        }
+        const allowed = resolveAllowedPages(pageSelection, document.pageCount);
+        if (allowed !== undefined && allowed.size === 1) {
+            return;
+        }
+        console.warn('[react-native-pdf-canvas] usePdfLayer was given a layout that STACKS pages ' +
+            `(${pageRects.length} page rects overlap in doc space, e.g. singlePage()) ` +
+            `together with a page selection of ${allowed === undefined
+                ? 'every page on screen'
+                : `${allowed.size} pages`}. Every page whose rect is on screen will be rastered at that same rect ` +
+            'and drawn on top of the others, so the visible page is the highest ' +
+            'allowed index and the cost is one base per page. Pass a one-element list ' +
+            '— usePdfLayer({layout: singlePage(), pages: [pageIndex]}) — or use ' +
+            'continuousVertical() / spread().');
+    }, [document, pageRects, pageSelection]);
+    const layer = useMemo(() => {
+        if (document === null || pageRects === null) {
+            return null;
+        }
+        const resolvedPolicy = resolvePolicy(policy);
+        const cache = createRasterCache({
+            budgetBytes: resolvedPolicy.cacheBudgetBytes,
+            dispose: disposeRaster,
+        });
+        const controller = createPdfController({
+            handle: document.handle,
+            pageRects,
+            pages: allPageGeometry(document),
+            policy: resolvedPolicy,
+            ingest: ingestRaster,
+            cache,
+            allowedPages: resolveAllowedPages(pageSelection, document.pageCount),
+            // The BACKEND's number, never a constant here. Absent (a backend written
+            // before the field existed) means 1, which is the sequential behaviour
+            // every backend was proven against.
+            maxConcurrentRenders: document.capabilities.maxConcurrentRenders,
+            onDiagnostic: emitDiagnostic,
+            backendId: document.rasterizerId,
+        });
+        return { controller, cache };
+    }, 
+    // `pageSelection` and `policy` are intentionally NOT deps: they are object
+    // literals at every realistic call site, and rebuilding the controller
+    // discards the entire raster cache. Their structural keys stand in for them,
+    // which is stronger than identity — a caller who memoises AND mutates gets
+    // the correct rebuild.
+    //
+    // A PAGE TURN THEREFORE REBUILDS EVERYTHING, AND THAT IS DELIBERATE. `pages`
+    // going from [2] to [3] changes `pagesKey`, so the controller is destroyed and
+    // the cache cleared: page 3 is rendered from scratch and turning back to 2
+    // re-renders it rather than hitting the cache. Keeping the controller alive
+    // across the change (a mutable allow-list the controller reads per plan) would
+    // buy that hit, and was rejected — the pages inside the controller's base
+    // retention radius stay MOUNTED, so in a stacked layout the page you left is
+    // still painted at the rect of the page you turned to, and even in a continuous
+    // layout the resident cost goes from one page to as many as five. The measured
+    // cost of the teardown is one page's rasters, which is the page you are turning
+    // to and would have paid for anyway. See `__tests__/single-page.test.ts`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [document, pageRects, pagesKey, policySignature, emitDiagnostic]);
+    const instance = layer?.controller ?? null;
+    useEffect(() => {
+        if (layer === null) {
+            return;
+        }
+        return () => {
+            // Ordering: this cleanup runs after the render that replaced `layer` has
+            // already committed, so the Skia tree is no longer drawing anything the
+            // cache holds and freeing is safe.
+            layer.controller.destroy();
+            // destroy() flushes what it had referenced; clear() also takes the entries
+            // that were cached but never referenced (a put whose acquire lost a race),
+            // which nothing else will ever free. The hook owns this cache exclusively.
+            layer.cache.clear();
+            // The DOCUMENT is deliberately untouched. The controller only borrowed its
+            // handle, and the document may outlive it — a thumbnail strip on the same
+            // handle — so closing it here would pull the file descriptor out from
+            // under a live consumer. `usePdfDocument` owns that.
+        };
+    }, [layer]);
+    const subscribe = useMemo(() => {
+        if (instance === null) {
+            return NOOP_SUBSCRIBE;
+        }
+        // Wrapped rather than passed as `instance.subscribe`, so the controller is
+        // free to implement it as a class method without losing `this`. The wrapper
+        // identity is stable per instance, which is what useSyncExternalStore needs.
+        return (listener) => instance.subscribe(listener);
+    }, [instance]);
+    const getSnapshot = useMemo(() => {
+        if (instance === null) {
+            return getEmptyContent;
+        }
+        // MUST return a cached reference. React calls getSnapshot during render and
+        // again after every store notification, and compares with Object.is — a freshly
+        // built object here is an infinite render loop, not a stale-data bug. The
+        // controller guarantees one frozen PdfContent per epoch.
+        return () => instance.getContent();
+    }, [instance]);
+    const content = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    // A facade whose identity never changes, so hosts can wire it into gesture
+    // callbacks and animation completion handlers without dependency arrays. It
+    // reads the live instance through a ref rather than closing over one.
+    const instanceRef = useRef(instance);
+    instanceRef.current = instance;
+    /**
+     * The last viewport the host handed us, whichever entry point it used.
+     *
+     * A REF AND NOT STATE: it is written from a gesture callback at gesture rate and
+     * nothing renders from it.
+     */
+    const lastViewportRef = useRef(null);
+    const controller = useMemo(() => ({
+        hint(viewport) {
+            lastViewportRef.current = viewport;
+            instanceRef.current?.hint(viewport);
+        },
+        settle(viewport) {
+            lastViewportRef.current = viewport;
+            instanceRef.current?.settle(viewport);
+        },
+        suppress() {
+            instanceRef.current?.suppress();
+        },
+        resume() {
+            instanceRef.current?.resume();
+        },
+    }), []);
+    /**
+     * A FRESH CONTROLLER HAS NEVER SEEN A VIEWPORT, AND NOTHING ELSE WILL TELL IT.
+     *
+     * Every entry point is host-driven, and a host drives them from viewport CHANGES
+     * — a gesture, a wheel tick, a re-fit. Change `pages`, `layout` or `policy` while
+     * the viewport sits still and the memo above builds a new controller with an
+     * empty cache, no `latestViewport` and no epoch: it plans nothing, commits
+     * nothing, and the canvas goes BLANK until the user happens to touch the
+     * document. MEASURED in rock-desktop's probe before this replay existed: turning
+     * from page 0 to page 1 in single-page mode left `epoch 0`, `mounted: none`,
+     * `rasters` unchanged and an empty canvas, indefinitely — a page turn is exactly
+     * the case where the viewport must NOT move, so nothing ever arrived.
+     *
+     * The host cannot fix this itself. That the controller was rebuilt is an
+     * internal detail of this hook — the `controller` facade's identity is
+     * deliberately stable across the swap — so a host has nothing to react to.
+     *
+     * `settle` and not `hint`: this IS the discrete event (the layer changed under a
+     * stationary viewport), and a hint would only arm the quiet timer. It is skipped
+     * on the very first controller, where `lastViewportRef` is still null and the
+     * host's own first settle is what starts things.
+     *
+     * DELIBERATELY NOT GATED ON THE DOCUMENT BEING THE SAME ONE. A new document
+     * usually arrives with a re-frame, which supersedes this epoch and makes it a
+     * wasted raster — but a host that swaps a same-sized document and keeps its
+     * viewport gets exactly the right one, and for that host the alternative is the
+     * blank page above. One superseded epoch is the cheaper mistake of the two.
+     */
+    useEffect(() => {
+        if (instance === null) {
+            return;
+        }
+        const viewport = lastViewportRef.current;
+        if (viewport === null) {
+            return;
+        }
+        instance.settle(viewport);
+    }, [instance]);
+    return { content, controller };
+}

package/dist/skia/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@reekon-tools/react-native-pdf-canvas/skia` — THE SKIA-ONLY SUBPATH.
+ *
+ * Everything in this package that needs a live Skia runtime is reached from
+ * here, and nothing that is reachable from the ROOT barrel needs one at import
+ * time. That split is the point of the subpath, not tidiness:
+ *
+ *   root (`.`)      pure core, layouts, policy, controller, cache, planner, the
+ *                   React hooks, `PdfContentView`. Safe to name from a module
+ *                   that is evaluated in Node during SSR — no CanvasKit, no
+ *                   `Skia.web.js`, no decision taken at import.
+ *   `./skia`        `ingestRaster` / `imageFromPixels` / `rasterByteLength`, and
+ *                   the `skiaApi()` accessor they use.
+ *
+ * IMPORTING THIS SUBPATH IS STILL SAFE BEFORE CANVASKIT IS LOADED. The accessor
+ * defers to first use (see `./skia-api.ts`), so a route module may import it at
+ * the top and only pay for it when a raster is actually ingested. The subpath
+ * boundary is a second line of defence, not the only one — belt and braces,
+ * because the failure it guards is silent and permanent.
+ *
+ * On web, load CanvasKit first with `loadPdfCanvasSkiaWeb()` from the
+ * `./web-init` subpath.
+ */
+export { ingestRaster, imageFromPixels, rasterByteLength, colorTypeFor, alphaTypeFor, BYTES_PER_PIXEL, } from '../rasterizer/ingest.js';
+export { skiaApi, setSkiaApiResolver } from './skia-api.js';
+export type { SkiaApi, SkiaApiResolver } from './skia-api.js';

package/dist/skia/index.js

@@ -0,0 +1,25 @@
+/**
+ * `@reekon-tools/react-native-pdf-canvas/skia` — THE SKIA-ONLY SUBPATH.
+ *
+ * Everything in this package that needs a live Skia runtime is reached from
+ * here, and nothing that is reachable from the ROOT barrel needs one at import
+ * time. That split is the point of the subpath, not tidiness:
+ *
+ *   root (`.`)      pure core, layouts, policy, controller, cache, planner, the
+ *                   React hooks, `PdfContentView`. Safe to name from a module
+ *                   that is evaluated in Node during SSR — no CanvasKit, no
+ *                   `Skia.web.js`, no decision taken at import.
+ *   `./skia`        `ingestRaster` / `imageFromPixels` / `rasterByteLength`, and
+ *                   the `skiaApi()` accessor they use.
+ *
+ * IMPORTING THIS SUBPATH IS STILL SAFE BEFORE CANVASKIT IS LOADED. The accessor
+ * defers to first use (see `./skia-api.ts`), so a route module may import it at
+ * the top and only pay for it when a raster is actually ingested. The subpath
+ * boundary is a second line of defence, not the only one — belt and braces,
+ * because the failure it guards is silent and permanent.
+ *
+ * On web, load CanvasKit first with `loadPdfCanvasSkiaWeb()` from the
+ * `./web-init` subpath.
+ */
+export { ingestRaster, imageFromPixels, rasterByteLength, colorTypeFor, alphaTypeFor, BYTES_PER_PIXEL, } from '../rasterizer/ingest.js';
+export { skiaApi, setSkiaApiResolver } from './skia-api.js';

package/dist/skia/index.native.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Native entry point for `./skia`.
+ *
+ * Same mechanism as `rasterizer/index.native.ts`: an `exports` condition is
+ * matched LITERALLY, with no platform-extension expansion, so the `react-native`
+ * condition needs a real `dist/skia/index.native.js` to point at.
+ *
+ * The one thing it adds over the shared barrel is installing the native
+ * resolver, so a consumer who imports ONLY this subpath still gets a working
+ * `skiaApi()`. The call is a statement using an imported binding, not a bare
+ * `import './x.js'` — this package declares `sideEffects: false`, and a bare
+ * side-effect import is exactly what that flag licenses a bundler to delete.
+ */
+export * from './index.js';

package/dist/skia/index.native.js

@@ -0,0 +1,16 @@
+/**
+ * Native entry point for `./skia`.
+ *
+ * Same mechanism as `rasterizer/index.native.ts`: an `exports` condition is
+ * matched LITERALLY, with no platform-extension expansion, so the `react-native`
+ * condition needs a real `dist/skia/index.native.js` to point at.
+ *
+ * The one thing it adds over the shared barrel is installing the native
+ * resolver, so a consumer who imports ONLY this subpath still gets a working
+ * `skiaApi()`. The call is a statement using an imported binding, not a bare
+ * `import './x.js'` — this package declares `sideEffects: false`, and a bare
+ * side-effect import is exactly what that flag licenses a bundler to delete.
+ */
+import { installNativeSkiaResolver } from './resolve.native.js';
+export * from './index.js';
+installNativeSkiaResolver();

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

@@ -0,0 +1,12 @@
+/**
+ * Web/default entry point for `./skia`.
+ *
+ * Installs the web resolver so a consumer who imports only this subpath still
+ * gets a working `skiaApi()` — provided CanvasKit has been loaded by then. The
+ * install itself decides nothing: it stores a closure, and
+ * `globalThis.CanvasKit` is not read until the first raster.
+ *
+ * See `index.native.ts` for why this is a statement and not a bare
+ * `import './resolve.web.js'`.
+ */
+export * from './index.js';

package/dist/skia/index.web.js

@@ -0,0 +1,14 @@
+/**
+ * Web/default entry point for `./skia`.
+ *
+ * Installs the web resolver so a consumer who imports only this subpath still
+ * gets a working `skiaApi()` — provided CanvasKit has been loaded by then. The
+ * install itself decides nothing: it stores a closure, and
+ * `globalThis.CanvasKit` is not read until the first raster.
+ *
+ * See `index.native.ts` for why this is a statement and not a bare
+ * `import './resolve.web.js'`.
+ */
+import { installWebSkiaResolver } from './resolve.web.js';
+export * from './index.js';
+installWebSkiaResolver();

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

@@ -0,0 +1,18 @@
+/**
+ * The NATIVE resolver: RN Skia's own `Skia`, imported normally.
+ *
+ * NATIVE ONLY, and the bare-specifier import below is deliberate. On native
+ * `lib/module/skia/Skia.js` is `export const Skia = SkiaApi;` — a read of the
+ * JSI global that the package's `NativeSetup` side effect installs during that
+ * same import — so there is no asynchronous initialisation and therefore no
+ * ordering hazard. Importing the barrel here is what GUARANTEES `NativeSetup`
+ * has run, which is stronger than reading `globalThis.SkiaApi` and hoping
+ * somebody else imported it.
+ *
+ * The web build never resolves this file: every `exports` entry that reaches it
+ * does so through a `react-native` condition. That is the same mechanism
+ * `rasterizer/index.native.ts` uses to keep `require('react-native')` out of a
+ * browser bundle.
+ */
+/** Install the native resolver. Idempotent. */
+export declare function installNativeSkiaResolver(): void;

package/dist/skia/resolve.native.js

@@ -0,0 +1,22 @@
+/**
+ * The NATIVE resolver: RN Skia's own `Skia`, imported normally.
+ *
+ * NATIVE ONLY, and the bare-specifier import below is deliberate. On native
+ * `lib/module/skia/Skia.js` is `export const Skia = SkiaApi;` — a read of the
+ * JSI global that the package's `NativeSetup` side effect installs during that
+ * same import — so there is no asynchronous initialisation and therefore no
+ * ordering hazard. Importing the barrel here is what GUARANTEES `NativeSetup`
+ * has run, which is stronger than reading `globalThis.SkiaApi` and hoping
+ * somebody else imported it.
+ *
+ * The web build never resolves this file: every `exports` entry that reaches it
+ * does so through a `react-native` condition. That is the same mechanism
+ * `rasterizer/index.native.ts` uses to keep `require('react-native')` out of a
+ * browser bundle.
+ */
+import { Skia } from '@shopify/react-native-skia';
+import { setSkiaApiResolver } from './skia-api.js';
+/** Install the native resolver. Idempotent. */
+export function installNativeSkiaResolver() {
+    setSkiaApiResolver(() => Skia);
+}