@papyrus-sdk/ui-react-native 0.2.8 → 0.2.10

package/README.md

@@ -34,6 +34,56 @@ await engine.load({ type: 'pdf', source: { uri: 'https://example.com/book.pdf' }
 />
 ```
 
+## Topbar Customization
+
+`Topbar` supports replacing the default "Papyrus" text and logo.
+
+```tsx
+<Topbar
+  engine={engine}
+  title="My Reader"
+  logo={<MyLogoIcon />}
+  onLogoPress={() => navigation.goBack()}
+  onOpenSettings={() => setSettingsOpen(true)}
+/>
+```
+
+- `title`: replaces the default brand text.
+- `logo`: custom logo node (can be icon, image, or even a `Pressable`).
+- `onLogoPress`: optional callback to make the logo area act like a button.
+
+## Mobile Tuning Flags
+
+Performance tuning props are available on `Viewer` and `RightSheet`:
+
+```tsx
+<Viewer
+  engine={engine}
+  virtualWindowSize={8}
+  maxToRenderPerBatch={6}
+  removeClippedSubviews
+/>
+
+<RightSheet engine={engine} thumbsInitialCount={4} />
+```
+
+- `virtualWindowSize` (`Viewer`): FlatList window size. Default: `8`.
+- `maxToRenderPerBatch` (`Viewer`): max items per render batch. Default: `6`.
+- `removeClippedSubviews` (`Viewer`): detach offscreen rows. Default: `true`.
+- `thumbsInitialCount` (`RightSheet`): initial thumbnails rendered when opening pages tab. Default: `4`.
+
+Recommended starting points:
+
+- Mid-range Android + large docs (500+ pages): `virtualWindowSize={6}`, `maxToRenderPerBatch={4}`, `thumbsInitialCount={3}`.
+- High-end devices: keep defaults (`8`, `6`, `4`) and tune only if you observe jank or memory pressure.
+
+## Performance Tips (Mobile)
+
+- Keep `Viewer` mounted before calling `engine.load(...)` for EPUB/TXT, so the WebView runtime is already ready.
+- Prefer URI loads (`{ uri }`) for local files instead of pre-converting content to base64.
+- For long documents, reduce `virtualWindowSize` and `maxToRenderPerBatch` first; then tune thumbnail pre-render count.
+- On Android mid-tier devices (around 4 GB RAM), expect temporary memory spikes while parsing EPUB archives and generating first render.
+
 ## Mobile Performance Baseline (Audit Step)
 
 Enable runtime diagnostics before rendering the viewer:
@@ -59,3 +109,15 @@ Recommended baseline run:
 3. Scroll quickly for 10-15 seconds and capture `scroll.*` logs.
 4. Open thumbnails and capture `memory.thumbnails.*`.
 5. Jump between distant pages and check for `setDocumentState.burst`.
+
+## Large Files (EPUB/PDF) Troubleshooting
+
+If large files fail to load or crash on mobile:
+
+- Avoid RN bridge base64 conversion for large local files (OOM risk). Use `{ uri: 'file:///...' }`.
+- EPUB on mobile WebView now fetches local URI content inside the runtime and opens from `ArrayBuffer`.
+- If you see timeout errors:
+  - WebView engine request timeout for `load`: `180000ms`
+  - Runtime EPUB open/ready timeout: `180000ms`
+  - Runtime EPUB display timeout: `30000ms`
+- For very large EPUBs, first-open can take longer on mid-tier Android. This is expected due to zip parsing and spine bootstrapping.

package/dist/index.d.mts

@@ -5,6 +5,9 @@ import { StyleProp, ViewStyle } from 'react-native';
 
 interface ViewerProps {
     engine: DocumentEngine;
+    virtualWindowSize?: number;
+    maxToRenderPerBatch?: number;
+    removeClippedSubviews?: boolean;
 }
 declare const Viewer: React.FC<ViewerProps>;
 
@@ -18,11 +21,15 @@ interface PageRendererProps {
     horizontalPadding?: number;
     spacing?: number;
 }
-declare const PageRenderer: React.FC<PageRendererProps>;
+declare const _default: React.NamedExoticComponent<PageRendererProps>;
 
 interface TopbarProps {
     engine: DocumentEngine;
     onOpenSettings?: () => void;
+    title?: string;
+    logo?: React.ReactNode;
+    onLogoPress?: () => void;
+    logoAccessibilityLabel?: string;
 }
 declare const Topbar: React.FC<TopbarProps>;
 
@@ -30,6 +37,7 @@ declare const ToolDock: React.FC;
 
 interface RightSheetProps {
     engine: DocumentEngine;
+    thumbsInitialCount?: number;
 }
 declare const RightSheet: React.FC<RightSheetProps>;
 
@@ -62,4 +70,4 @@ type CoverPreviewProps = {
 };
 declare const CoverPreview: React.FC<CoverPreviewProps>;
 
-export { AnnotationEditor, BottomBar, CoverPreview, PageRenderer, RightSheet, SettingsSheet, ToolDock, Topbar, Viewer };
+export { AnnotationEditor, BottomBar, CoverPreview, _default as PageRenderer, RightSheet, SettingsSheet, ToolDock, Topbar, Viewer };

package/dist/index.d.ts

@@ -5,6 +5,9 @@ import { StyleProp, ViewStyle } from 'react-native';
 
 interface ViewerProps {
     engine: DocumentEngine;
+    virtualWindowSize?: number;
+    maxToRenderPerBatch?: number;
+    removeClippedSubviews?: boolean;
 }
 declare const Viewer: React.FC<ViewerProps>;
 
@@ -18,11 +21,15 @@ interface PageRendererProps {
     horizontalPadding?: number;
     spacing?: number;
 }
-declare const PageRenderer: React.FC<PageRendererProps>;
+declare const _default: React.NamedExoticComponent<PageRendererProps>;
 
 interface TopbarProps {
     engine: DocumentEngine;
     onOpenSettings?: () => void;
+    title?: string;
+    logo?: React.ReactNode;
+    onLogoPress?: () => void;
+    logoAccessibilityLabel?: string;
 }
 declare const Topbar: React.FC<TopbarProps>;
 
@@ -30,6 +37,7 @@ declare const ToolDock: React.FC;
 
 interface RightSheetProps {
     engine: DocumentEngine;
+    thumbsInitialCount?: number;
 }
 declare const RightSheet: React.FC<RightSheetProps>;
 
@@ -62,4 +70,4 @@ type CoverPreviewProps = {
 };
 declare const CoverPreview: React.FC<CoverPreviewProps>;
 
-export { AnnotationEditor, BottomBar, CoverPreview, PageRenderer, RightSheet, SettingsSheet, ToolDock, Topbar, Viewer };
+export { AnnotationEditor, BottomBar, CoverPreview, _default as PageRenderer, RightSheet, SettingsSheet, ToolDock, Topbar, Viewer };