@papyrus-sdk/ui-react-native 0.2.24 → 0.2.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyrus-sdk/ui-react-native",
-  "version": "0.2.24",
+  "version": "0.2.27",
   "license": "MIT",
   "keywords": [
     "papyrus",
@@ -48,9 +48,11 @@
     "@papyrus-sdk/core": ">=0.2.18",
     "@papyrus-sdk/engine-native": ">=0.2.17",
     "@papyrus-sdk/types": ">=0.2.11",
+    "@react-native-clipboard/clipboard": "^1.16.3",
     "react": ">=18.2.0 <20",
     "react-native": ">=0.81.0",
     "react-native-gesture-handler": ">=2.28.0",
+    "react-native-safe-area-context": "^5.6.2",
     "react-native-webview": ">=13"
   },
   "peerDependenciesMeta": {
@@ -62,9 +64,11 @@
     "@papyrus-sdk/core": "0.2.19",
     "@papyrus-sdk/engine-native": "workspace:*",
     "@papyrus-sdk/types": "0.2.12",
+    "@react-native-clipboard/clipboard": "^1.16.3",
     "@types/react": "19.2.14",
     "react": "^19.1.0",
     "react-native": "^0.81.0",
-    "react-native-gesture-handler": "~2.28.0"
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-safe-area-context": "^5.6.2"
   }
 }

package/runtime/comicRuntime.test.ts

@@ -87,4 +87,155 @@ describe("mobile comic runtime helpers", () => {
     expect(runtime).toContain("file-chunk-request");
     expect(html).toContain("file-chunk-request");
   });
+
+  it("loads local EPUB files through the native chunk bridge", () => {
+    const runtime = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+      "utf8"
+    );
+    const html = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/index.html"),
+      "utf8"
+    );
+
+    expect(runtime).toContain("sourceToArrayBuffer(source),");
+    expect(html).toContain("sourceToArrayBuffer(source),");
+    expect(runtime).not.toContain("data = source.uri;");
+    expect(html).not.toContain("data = source.uri;");
+  });
+
+  it("passes an exact ArrayBuffer to epub.js for base64 sources", () => {
+    const runtime = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+      "utf8"
+    );
+    const html = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/index.html"),
+      "utf8"
+    );
+
+    expect(runtime).toContain("const toExactArrayBuffer = (bytes) =>");
+    expect(html).toContain("const toExactArrayBuffer = (bytes) =>");
+    expect(runtime).toContain("data = toExactArrayBuffer(decodeBase64(source.data));");
+    expect(html).toContain("data = toExactArrayBuffer(decodeBase64(source.data));");
+  });
+
+  it("correlates EPUB diagnostics and load terminals by request id", () => {
+    const runtime = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+      "utf8"
+    );
+    const html = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/index.html"),
+      "utf8"
+    );
+    for (const artifact of [runtime, html]) {
+      expect(artifact).toContain("epub.load.start");
+      expect(artifact).toContain("epub.book.ready");
+      expect(artifact).toContain("epub.display.start");
+      expect(artifact).toContain("epub.load.ready");
+      expect(artifact).toContain("epub.load.error");
+      expect(artifact).toContain("epub.load.timeout");
+      expect(artifact).toContain("loadId");
+      expect(artifact).toContain("document.ready");
+      expect(artifact).toContain("document.error");
+      expect(artifact).toContain("withEpubStageTimeout");
+    }
+  });
+
+  it("invalidates a pending EPUB load when another document starts", () => {
+    const runtime = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+      "utf8"
+    );
+    const loadStart = runtime.indexOf("if (kind === 'load')");
+    const generationInvalidation = runtime.indexOf(
+      "epubLoadGeneration += 1",
+      loadStart
+    );
+    const currentTypeAssignment = runtime.indexOf(
+      "currentType = payload.type",
+      loadStart
+    );
+
+    expect(generationInvalidation).toBeGreaterThan(loadStart);
+    expect(generationInvalidation).toBeLessThan(currentTypeAssignment);
+    expect(runtime).toContain(
+      "const loadEpub = async (source, loadId, generation) =>"
+    );
+    expect(runtime).toContain(
+      "const result = await loadEpub(payload.source, id, generation);"
+    );
+  });
+
+  it("rejects a stale EPUB load after outline resolution", () => {
+    const runtime = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+      "utf8"
+    );
+    const outlineStart = runtime.indexOf("const outline = await withEpubStageTimeout(");
+    const outlineGuard = runtime.indexOf(
+      "if (!isCurrentLoad()) throw new Error('EPUB load superseded by a newer load');",
+      outlineStart
+    );
+    const readyEvent = runtime.indexOf(
+      "sendEpubDiagnostic('epub.load.ready'",
+      outlineStart
+    );
+
+    expect(outlineStart).toBeGreaterThan(-1);
+    expect(outlineGuard).toBeGreaterThan(outlineStart);
+    expect(outlineGuard).toBeLessThan(readyEvent);
+  });
+
+  it("uses continuous scrolling for EPUB rendition", () => {
+    const runtime = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+      "utf8"
+    );
+    const html = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/index.html"),
+      "utf8"
+    );
+
+    expect(runtime).toContain("manager: 'continuous'");
+    expect(html).toContain("manager: 'continuous'");
+    expect(runtime).toContain("flow: 'scrolled-continuous'");
+    expect(html).toContain("flow: 'scrolled-continuous'");
+    expect(runtime).toContain("rendition.on('relocated'");
+    expect(html).toContain("rendition.on('relocated'");
+    expect(runtime).toContain("sendEvent('VIEWER_SCROLL'");
+    expect(html).toContain("sendEvent('VIEWER_SCROLL'");
+    expect(runtime).toContain("sendEvent('VIEWER_TAP'");
+    expect(html).toContain("sendEvent('VIEWER_TAP'");
+    expect(runtime).not.toContain("flow: 'paginated'");
+    expect(html).not.toContain("flow: 'paginated'");
+  });
+
+  it("observes the real EPUB manager queue without changing queue semantics", () => {
+    const runtime = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+      "utf8"
+    );
+    const html = readFileSync(
+      resolve(process.cwd(), "packages/ui-react-native/runtime/index.html"),
+      "utf8"
+    );
+
+    for (const artifact of [runtime, html]) {
+      expect(artifact).toContain("const originalCheck = typeof manager.check");
+      expect(artifact).toContain("manager.check = function (...args)");
+      expect(artifact).toContain("const originalEnqueue = queue && typeof queue.enqueue");
+      expect(artifact).toContain("queue.enqueue = function (...args)");
+      expect(artifact).toContain("manager.queue.enqueue");
+      expect(artifact).toContain("queue.enqueue = originalEnqueue");
+      expect(artifact).toContain("manager.check.request");
+      expect(artifact).toContain("manager.check.start");
+      expect(artifact).toContain("manager.check.end");
+      expect(artifact).toContain("epubSelectionCleanups");
+      expect(artifact).toContain("__papyrusSelectionCleanup");
+      expect(artifact).toContain("setSelectionActive(false)");
+      expect(artifact).not.toContain("String(task)");
+    }
+  });
 });

package/runtime/documentLoadRuntime.test.ts

@@ -0,0 +1,172 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { JSDOM } from "jsdom";
+import { describe, expect, it, vi } from "vitest";
+
+type RuntimeMessage = {
+  type?: string;
+  id?: string;
+  name?: string;
+  kind?: string;
+  ok?: boolean;
+  data?: { pageCount?: number };
+  error?: { message?: string } | string;
+  loadId?: string;
+};
+
+const runtimeSource = readFileSync(
+  resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
+  "utf8",
+);
+
+const createRuntime = () => {
+  const messages: RuntimeMessage[] = [];
+  const dom = new JSDOM(
+    '<!doctype html><html><body><div id="viewer"></div></body></html>',
+    { runScripts: "outside-only", url: "http://localhost/" },
+  );
+  dom.window.ReactNativeWebView = {
+    postMessage: (raw: string) => messages.push(JSON.parse(raw)),
+  } as never;
+  dom.window.eval(runtimeSource);
+
+  const send = (message: Record<string, unknown>) => {
+    dom.window.dispatchEvent(
+      new dom.window.MessageEvent("message", { data: JSON.stringify(message) }),
+    );
+  };
+
+  return { dom, messages, send };
+};
+
+const waitFor = async (
+  predicate: () => boolean,
+  timeoutMs = 1000,
+): Promise<void> => {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error("runtime message timeout");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+};
+
+describe("document loading runtime", () => {
+  it("publishes an empty TXT document as a completed one-page load", async () => {
+    const runtime = createRuntime();
+
+    runtime.send({
+      id: "empty-1",
+      kind: "load",
+      payload: { type: "text", source: { kind: "text", text: "" } },
+    });
+    await waitFor(() =>
+      runtime.messages.some(
+        (message) => message.type === "response" && message.id === "empty-1",
+      ),
+    );
+
+    expect(runtime.messages).toContainEqual({
+      type: "event",
+      name: "document.ready",
+      payload: { loadId: "empty-1", pageCount: 1 },
+    });
+    expect(runtime.messages).toContainEqual(
+      expect.objectContaining({ type: "response", id: "empty-1", ok: true }),
+    );
+  });
+
+  it("reports an invalid TXT source instead of leaving loading pending", async () => {
+    const runtime = createRuntime();
+
+    runtime.send({
+      id: "invalid-1",
+      kind: "load",
+      payload: { type: "text", source: null },
+    });
+    await waitFor(() =>
+      runtime.messages.some(
+        (message) => message.type === "response" && message.id === "invalid-1",
+      ),
+    );
+
+    expect(runtime.messages).toContainEqual(
+      expect.objectContaining({
+        type: "event",
+        name: "document.error",
+        payload: expect.objectContaining({ loadId: "invalid-1" }),
+      }),
+    );
+    expect(runtime.messages).toContainEqual(
+      expect.objectContaining({ type: "response", id: "invalid-1", ok: false }),
+    );
+  });
+
+  it("marks a pending TXT load stale when another format starts", async () => {
+    const runtime = createRuntime();
+    let resolveText: ((value: string) => void) | undefined;
+    const fetchText = vi.fn(
+      () =>
+        new Promise<string>((resolve) => {
+          resolveText = resolve;
+        }),
+    );
+    runtime.dom.window.fetch = vi.fn(async () => ({
+      text: fetchText,
+    })) as never;
+
+    runtime.send({
+      id: "text-a",
+      kind: "load",
+      payload: {
+        type: "text",
+        source: { kind: "uri", uri: "http://localhost/a.txt" },
+      },
+    });
+    await waitFor(() => fetchText.mock.calls.length === 1);
+
+    runtime.send({
+      id: "new-document-b",
+      kind: "load",
+      payload: {
+        type: "text",
+        source: { kind: "text", text: "new document" },
+      },
+    });
+    await waitFor(() =>
+      runtime.messages.some(
+        (message) => message.type === "response" && message.id === "new-document-b",
+      ),
+    );
+
+    resolveText?.("old document");
+    await waitFor(() =>
+      runtime.messages.some(
+        (message) => message.type === "response" && message.id === "text-a",
+      ),
+    );
+
+    expect(runtime.messages).toContainEqual({
+      type: "event",
+      name: "document.ready",
+      payload: { loadId: "new-document-b", pageCount: 1 },
+    });
+    expect(runtime.messages).toContainEqual(
+      expect.objectContaining({
+        type: "event",
+        name: "document.stale",
+        payload: expect.objectContaining({ loadId: "text-a" }),
+      }),
+    );
+    expect(runtime.messages).toContainEqual(
+      expect.objectContaining({ type: "response", id: "new-document-b", ok: true }),
+    );
+    expect(runtime.messages).toContainEqual(
+      expect.objectContaining({ type: "response", id: "text-a", ok: false }),
+    );
+    expect(
+      runtime.messages.filter(
+        (message) => message.type === "event" && message.name === "document.ready",
+      ),
+    ).toHaveLength(1);
+  });
+});

package/runtime/epubScrollDiagnostics.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import {
+  createEpubScrollStallDetector,
+  getEpubScrollDirection,
+} from "./epubScrollDiagnostics";
+
+describe("EPUB scroll diagnostics", () => {
+  it("classifies upward movement from the scroll offset", () => {
+    expect(getEpubScrollDirection(400, 420)).toBe("up");
+    expect(getEpubScrollDirection(420, 400)).toBe("down");
+    expect(getEpubScrollDirection(400, 400)).toBe("none");
+  });
+
+  it("reports a reverse-scroll stall only after valid consecutive moves", () => {
+    const detector = createEpubScrollStallDetector({
+      minConsecutiveSamples: 3,
+      minDurationMs: 150,
+      movementThresholdPx: 4,
+      offsetEpsilonPx: 1,
+    });
+
+    expect(
+      detector.push({
+        timestamp: 0,
+        scrollTop: 420,
+        previousScrollTop: 420,
+        deltaY: 18,
+        scrollHeight: 2000,
+        clientHeight: 600,
+        scrollEnabled: true,
+        selectionActive: false,
+        gestureLock: false,
+        spineIndex: 4,
+        progress: 0.3,
+      })
+    ).toBeNull();
+
+    expect(
+      detector.push({
+        timestamp: 70,
+        scrollTop: 420,
+        previousScrollTop: 420,
+        deltaY: 18,
+        scrollHeight: 2000,
+        clientHeight: 600,
+        scrollEnabled: true,
+        selectionActive: false,
+        gestureLock: false,
+        spineIndex: 4,
+        progress: 0.3,
+      })
+    ).toBeNull();
+
+    const stall = detector.push({
+      timestamp: 180,
+      scrollTop: 420,
+      previousScrollTop: 420,
+      deltaY: 18,
+      scrollHeight: 2000,
+      clientHeight: 600,
+      scrollEnabled: true,
+      selectionActive: false,
+      gestureLock: false,
+      spineIndex: 4,
+      progress: 0.3,
+    });
+
+    expect(stall).toMatchObject({
+      name: "epub.scroll.stall",
+      direction: "up",
+      scrollTop: 420,
+      consecutiveSamples: 3,
+      durationMs: 180,
+      spineIndex: 4,
+    });
+  });
+
+  it("ignores top, disabled, selected, and genuinely moving samples", () => {
+    const detector = createEpubScrollStallDetector();
+    const base = {
+      timestamp: 0,
+      scrollTop: 0,
+      previousScrollTop: 0,
+      deltaY: 20,
+      scrollHeight: 2000,
+      clientHeight: 600,
+      scrollEnabled: true,
+      selectionActive: false,
+      gestureLock: false,
+      spineIndex: 0,
+      progress: 0,
+    };
+
+    expect(detector.push(base)).toBeNull();
+    expect(detector.push({ ...base, timestamp: 100, scrollEnabled: false })).toBeNull();
+    expect(detector.push({ ...base, timestamp: 200, selectionActive: true })).toBeNull();
+    expect(
+      detector.push({
+        ...base,
+        timestamp: 300,
+        scrollTop: 380,
+        previousScrollTop: 400,
+      })
+    ).toBeNull();
+  });
+
+});

package/runtime/epubScrollDiagnostics.ts

@@ -0,0 +1,127 @@
+export type EpubScrollDirection = "up" | "down" | "none";
+
+export type EpubScrollSample = {
+  timestamp: number;
+  scrollTop: number;
+  previousScrollTop: number;
+  deltaY: number;
+  scrollHeight: number;
+  clientHeight: number;
+  scrollEnabled: boolean;
+  selectionActive: boolean;
+  gestureLock: boolean;
+  spineIndex: number | null;
+  progress: number | null;
+};
+
+export type EpubScrollStall = {
+  name: "epub.scroll.stall";
+  direction: "up";
+  scrollTop: number;
+  scrollHeight: number;
+  clientHeight: number;
+  consecutiveSamples: number;
+  durationMs: number;
+  deltaY: number;
+  scrollEnabled: boolean;
+  selectionActive: boolean;
+  gestureLock: boolean;
+  spineIndex: number | null;
+  progress: number | null;
+};
+
+export type EpubScrollStallDetectorOptions = {
+  minConsecutiveSamples?: number;
+  minDurationMs?: number;
+  maxDurationMs?: number;
+  movementThresholdPx?: number;
+  offsetEpsilonPx?: number;
+  topThresholdPx?: number;
+};
+
+const DEFAULT_OPTIONS: Required<EpubScrollStallDetectorOptions> = {
+  minConsecutiveSamples: 3,
+  minDurationMs: 150,
+  maxDurationMs: 1000,
+  movementThresholdPx: 4,
+  offsetEpsilonPx: 1,
+  topThresholdPx: 2,
+};
+
+export const getEpubScrollDirection = (
+  scrollTop: number,
+  previousScrollTop: number,
+  epsilon = 0.5
+): EpubScrollDirection => {
+  const delta = scrollTop - previousScrollTop;
+  if (delta < -epsilon) return "up";
+  if (delta > epsilon) return "down";
+  return "none";
+};
+
+export const createEpubScrollStallDetector = (
+  options: EpubScrollStallDetectorOptions = {}
+) => {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+  let samples: EpubScrollSample[] = [];
+  let reported = false;
+
+  const reset = () => {
+    samples = [];
+    reported = false;
+  };
+
+  const push = (sample: EpubScrollSample): EpubScrollStall | null => {
+    const expectedUpwardMovement = sample.deltaY >= config.movementThresholdPx;
+    const awayFromTop = sample.scrollTop > config.topThresholdPx;
+    const noActualMovement =
+      Math.abs(sample.scrollTop - sample.previousScrollTop) <=
+      config.offsetEpsilonPx;
+    const valid =
+      expectedUpwardMovement &&
+      awayFromTop &&
+      sample.scrollEnabled &&
+      !sample.selectionActive &&
+      !sample.gestureLock &&
+      noActualMovement;
+
+    if (!valid) {
+      reset();
+      return null;
+    }
+
+    samples.push(sample);
+    const first = samples[0];
+    const durationMs = sample.timestamp - first.timestamp;
+    if (durationMs > config.maxDurationMs) {
+      samples = [sample];
+      return null;
+    }
+    if (
+      reported ||
+      samples.length < config.minConsecutiveSamples ||
+      durationMs < config.minDurationMs
+    ) {
+      return null;
+    }
+
+    reported = true;
+    return {
+      name: "epub.scroll.stall",
+      direction: "up",
+      scrollTop: sample.scrollTop,
+      scrollHeight: sample.scrollHeight,
+      clientHeight: sample.clientHeight,
+      consecutiveSamples: samples.length,
+      durationMs,
+      deltaY: sample.deltaY,
+      scrollEnabled: sample.scrollEnabled,
+      selectionActive: sample.selectionActive,
+      gestureLock: sample.gestureLock,
+      spineIndex: sample.spineIndex,
+      progress: sample.progress,
+    };
+  };
+
+  return { push, reset };
+};