@papyrus-sdk/ui-react-native 0.2.35-beta.8 → 0.2.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyrus-sdk/ui-react-native",
-  "version": "0.2.35-beta.8",
+  "version": "0.2.35",
   "license": "MIT",
   "keywords": [
     "papyrus",
@@ -38,17 +38,13 @@
   "bugs": {
     "url": "https://github.com/solrachix/Papyrus/issues"
   },
-  "scripts": {
-    "build": "node runtime/syncComicRuntime.mjs && tsup",
-    "check:ink-worklets": "pnpm run build && node ../../scripts/ci/check-native-ink-worklets.cjs"
-  },
   "dependencies": {
     "react-native-svg": "^15.5.0"
   },
   "peerDependencies": {
-    "@papyrus-sdk/core": ">=0.2.18 || 0.2.23-beta.2",
-    "@papyrus-sdk/engine-native": ">=0.2.17 || 0.2.22-beta.6",
-    "@papyrus-sdk/types": ">=0.2.11 || 0.2.16-beta.2",
+    "@papyrus-sdk/core": "0.2.23",
+    "@papyrus-sdk/engine-native": "0.2.22",
+    "@papyrus-sdk/types": "0.2.16",
     "@react-native-clipboard/clipboard": "^1.16.3",
     "react": ">=18.2.0 <20",
     "react-native": ">=0.81.0",
@@ -63,15 +59,19 @@
     }
   },
   "devDependencies": {
-    "@papyrus-sdk/core": "0.2.23-beta.2",
-    "@papyrus-sdk/engine-native": "0.2.22-beta.6",
-    "@papyrus-sdk/types": "0.2.16-beta.2",
     "@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-safe-area-context": "^5.6.2",
-    "react-native-reanimated": "3.19.5"
+    "react-native-reanimated": "3.19.5",
+    "@papyrus-sdk/core": "0.2.23",
+    "@papyrus-sdk/engine-native": "0.2.22",
+    "@papyrus-sdk/types": "0.2.16"
+  },
+  "scripts": {
+    "build": "node runtime/syncComicRuntime.mjs && tsup",
+    "check:ink-worklets": "pnpm run build && node ../../scripts/ci/check-native-ink-worklets.cjs"
   }
-}
+}

package/runtime/comicRuntime.test.ts

@@ -188,7 +188,7 @@ describe("mobile comic runtime helpers", () => {
     expect(outlineGuard).toBeLessThan(readyEvent);
   });
 
-  it("uses continuous scrolling for EPUB rendition", () => {
+  it("ships the paginated and chapter-scroll EPUB reading policy", () => {
     const runtime = readFileSync(
       resolve(process.cwd(), "packages/ui-react-native/runtime/runtime.js"),
       "utf8"
@@ -198,18 +198,18 @@ describe("mobile comic runtime helpers", () => {
       "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("manager:'default'");
+    expect(html).toContain("manager:'default'");
+    expect(runtime).toContain("'scrolled-doc'");
+    expect(html).toContain("'scrolled-doc'");
     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'");
+    expect(runtime).toContain("sendEvent('EPUB_CONTENT_TAP'");
+    expect(html).toContain("sendEvent('EPUB_CONTENT_TAP'");
+    expect(runtime).toContain("'paginated'");
+    expect(html).toContain("'paginated'");
   });
 
   it("observes the real EPUB manager queue without changing queue semantics", () => {

package/runtime/epubAnnotations.js

@@ -0,0 +1,121 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.PapyrusEpubAnnotations = factory();
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  function validAnchor(anchor) {
+    return anchor && anchor.version === 1 && anchor.kind === 'epub-cfi' &&
+      typeof anchor.cfiRange === 'string' && anchor.cfiRange.length <= 4096 && /^epubcfi\([^\n<>]+\)$/.test(anchor.cfiRange) &&
+      typeof anchor.href === 'string' && !/^(javascript|data):/i.test(anchor.href) &&
+      typeof anchor.quote === 'string' && anchor.quote.length > 0 && anchor.quote.length <= 100000;
+  }
+  function textNodes(document) {
+    var walker = document.createTreeWalker(document.body, 4);
+    var nodes = [], text = '', node;
+    while ((node = walker.nextNode())) {
+      if (node.parentElement.closest('script,style,[data-papyrus-overlay]')) continue;
+      nodes.push({node:node, start:text.length}); text += node.textContent;
+    }
+    return {nodes:nodes,text:text};
+  }
+  function recoverRange(document, anchor) {
+    var source = textNodes(document), match = null, start = source.text.indexOf(anchor.quote);
+    while (start >= 0) {
+      var end = start + anchor.quote.length;
+      if ((!anchor.prefix || source.text.slice(Math.max(0,start-anchor.prefix.length),start) === anchor.prefix) &&
+          (!anchor.suffix || source.text.slice(end,end+anchor.suffix.length) === anchor.suffix)) {
+        if (match) return null; match = {start:start,end:end};
+      }
+      start = source.text.indexOf(anchor.quote,start+1);
+    }
+    if (!match) return null;
+    var range = document.createRange();
+    var first = source.nodes.find(function(n){return n.start+n.node.length > match.start;});
+    var last = source.nodes.find(function(n){return n.start+n.node.length >= match.end;});
+    if (!first || !last) return null;
+    range.setStart(first.node,match.start-first.start); range.setEnd(last.node,match.end-last.start);
+    return range;
+  }
+  function resolveRange(contents, anchor) {
+    if (!validAnchor(anchor)) return null;
+    try { var range = contents.range(anchor.cfiRange); if (range && range.toString() === anchor.quote) return range; } catch (_) {}
+    return recoverRange(contents.document,anchor);
+  }
+  function selection(contents, cfiRange, href, documentId) {
+    var range;
+    try { range = contents.range(cfiRange); } catch (_) { return null; }
+    if (!range || !range.toString()) return null;
+    var before = contents.document.createRange(); before.selectNodeContents(contents.document.body); before.setEnd(range.startContainer,range.startOffset);
+    var after = contents.document.createRange(); after.selectNodeContents(contents.document.body); after.setStart(range.endContainer,range.endOffset);
+    var anchor = {version:1,kind:'epub-cfi',cfiRange:cfiRange,href:href,spineIndex:contents.sectionIndex,documentId:documentId,quote:range.toString(),prefix:before.toString().slice(-48),suffix:after.toString().slice(0,48)};
+    return validAnchor(anchor) ? anchor : null;
+  }
+  function install(contents, options) {
+    var doc = contents.document, win = contents.window, alive = true, frame = 0;
+    var overlay = doc.createElement('div'); overlay.dataset.papyrusOverlay = 'annotations';
+    overlay.style.cssText = 'position:absolute;left:0;top:0;width:100%;height:0;pointer-events:none;z-index:3';
+    var originalPosition=doc.body.style.position;
+    if(win.getComputedStyle(doc.body).position==='static')doc.body.style.position='relative';
+    doc.body.appendChild(overlay);
+    var registry = new Map(), hitRegions = [];
+    function render() {
+      frame = 0; if (!alive || !options.isCurrent()) return;
+      var keep = new Set(), noteGroups = new Map();
+      hitRegions = [];
+      options.annotations().forEach(function(annotation) {
+        var anchor = annotation.anchor;
+        if (!validAnchor(anchor) || anchor.href !== options.href || anchor.documentId && options.documentId && anchor.documentId !== options.documentId) return;
+        var range = resolveRange(contents,anchor); if (!range) return;
+        var rects = Array.from(range.getClientRects()).filter(function(r){return r.width>0 && r.height>0;});
+        if (!rects.length) return;
+        keep.add(annotation.id);
+        var group = registry.get(annotation.id);
+        if (!group) { group = doc.createElement('div'); group.dataset.annotationId = annotation.id; overlay.appendChild(group); registry.set(annotation.id,group); if (!doc.defaultView.matchMedia || !doc.defaultView.matchMedia('(prefers-reduced-motion: reduce)').matches) { if (typeof group.animate === 'function') group.animate([{opacity:0},{opacity:1}],{duration:180,easing:'ease-out'}); } }
+        group.replaceChildren();
+        hitRegions.push({id:annotation.id,rects:rects});
+        var color = /^#[0-9a-f]{6}$/i.test(annotation.color) ? annotation.color : '#FFC928';
+        var style = annotation.markupStyle || annotation.type;
+        var opacity = Number.isFinite(annotation.opacity) ? Math.max(0,Math.min(1,annotation.opacity)) : 0.35;
+        if(style === 'highlight')opacity=Math.min(0.35,opacity);
+        rects.forEach(function(rect) {
+          var mark = doc.createElement('div');
+          var bodyRect=doc.body.getBoundingClientRect();
+          var height = style === 'highlight' ? rect.height : 2;
+          var y = style === 'strikeout' ? rect.top+rect.height/2 : style === 'underline' ? rect.bottom-2 : rect.top;
+          mark.style.cssText = 'position:absolute;pointer-events:none;left:'+(rect.left-bodyRect.left)+'px;top:'+(y-bodyRect.top)+'px;width:'+rect.width+'px;height:'+height+'px;background:'+color+';opacity:'+opacity;
+          if (['highlight','underline','strikeout'].includes(style)) group.appendChild(mark);
+        });
+        var hasNote = annotation.noteContent !== undefined || annotation.type === 'comment' || annotation.type === 'text';
+        if (hasNote) {
+          var last = rects[rects.length-1], button = doc.createElement('button');
+          button.textContent = '●'; button.setAttribute('aria-label',options.labels().comment || '');
+          var pageWidth=Math.max(44, options.pageWidth ? options.pageWidth() : win.innerWidth);
+          var bodyRect=doc.body.getBoundingClientRect(), column=Math.max(0,Math.floor((last.left-bodyRect.left)/pageWidth));
+          button.style.cssText = 'position:absolute;pointer-events:auto;border:0;background:transparent;color:'+color+';width:44px;height:44px;left:'+((column+1)*pageWidth-44)+'px;top:'+(Math.floor(last.top/44)*44-doc.body.getBoundingClientRect().top)+'px';
+          var key = column+":"+Math.floor(last.top/44);
+          var neighbors=noteGroups.get(key);
+          if(!neighbors){neighbors={button:button,ids:[]};noteGroups.set(key,neighbors);group.appendChild(button);}
+          neighbors.ids.push(annotation.id);
+        }
+      });
+      noteGroups.forEach(function(group){
+        group.button.textContent=group.ids.length>1?String(group.ids.length):'●';
+        group.button.addEventListener('click',function(e){e.stopPropagation();if(options.isCurrent())options.onTap(group.ids[0],group.ids);});
+      });
+      registry.forEach(function(group,id){if (!keep.has(id)) {group.remove();registry.delete(id);}});
+    }
+    function schedule() { if (alive && !frame) frame = win.requestAnimationFrame(render); }
+    function tapMarkup(event) {
+      if(!alive || !options.isCurrent() || String(win.getSelection() || '').length || event.target.closest('[data-papyrus-overlay]'))return;
+      var hit=hitRegions.find(function(item){return item.rects.some(function(r){return event.clientX>=r.left && event.clientX<=r.right && event.clientY>=r.top && event.clientY<=r.bottom;});});
+      if(hit) {event.stopPropagation();options.onTap(hit.id);}
+    }
+    doc.addEventListener('click',tapMarkup);
+    var observer = typeof win.ResizeObserver === 'function' ? new win.ResizeObserver(schedule) : null;
+    if (observer) observer.observe(doc.body);
+    win.addEventListener('resize',schedule);win.addEventListener('scroll',schedule); doc.addEventListener('load',schedule,true);
+    if (doc.fonts && doc.fonts.ready) doc.fonts.ready.then(schedule);
+    schedule();
+    return {schedule:schedule, hit:function(x,y){return hitRegions.some(function(item){return item.rects.some(function(r){return x>=r.left && x<=r.right && y>=r.top && y<=r.bottom;});});}, range:function(anchor){return resolveRange(contents,anchor);}, destroy:function(){alive=false;if(frame)win.cancelAnimationFrame(frame);if(observer)observer.disconnect();win.removeEventListener('resize',schedule);win.removeEventListener('scroll',schedule);doc.removeEventListener('load',schedule,true);doc.removeEventListener('click',tapMarkup);overlay.remove();doc.body.style.position=originalPosition;registry.clear();}};
+  }
+  return {validAnchor:validAnchor,recoverRange:recoverRange,resolveRange:resolveRange,selection:selection,install:install};
+});

package/runtime/epubAnnotations.test.ts

@@ -0,0 +1,35 @@
+import {createRequire} from 'node:module';
+import {describe,it,expect} from 'vitest';
+const annotations = createRequire(import.meta.url)('./epubAnnotations.js');
+const anchor = {version:1,kind:'epub-cfi',cfiRange:'epubcfi(/6/2!/4/2:0)',href:'chapter.xhtml',quote:'word'};
+describe('EPUB contextual anchors',()=>{
+ it('rejects malformed CFI and unsafe hrefs',()=>{expect(annotations.validAnchor(anchor)).toBe(true);expect(annotations.validAnchor({...anchor,cfiRange:'bad'})).toBe(false);expect(annotations.validAnchor({...anchor,href:'javascript:alert(1)'})).toBe(false);});
+ it('recovers uniquely in chapter text preserving UTF16 and excludes overlays',()=>{document.body.innerHTML='<p>A 😀 word end</p><div data-papyrus-overlay>word</div>';expect(annotations.recoverRange(document,anchor)?.toString()).toBe('word');});
+ it('leaves ambiguous quotes unresolved unless context distinguishes them',()=>{document.body.innerHTML='<p>one word two word end</p>';expect(annotations.recoverRange(document,anchor)).toBeNull();expect(annotations.recoverRange(document,{...anchor,prefix:'two '})?.toString()).toBe('word');});
+ it('verifies exact CFI quote before controlled recovery',()=>{document.body.innerHTML='<p>other word</p>';const bad=document.createRange();bad.selectNodeContents(document.body);expect(annotations.resolveRange({document,range:()=>bad},anchor)?.toString()).toBe('word');});
+});
+
+it('renders true strikeout, grouped notes and reconciles 120 stable IDs after reflow',()=>{
+ document.body.innerHTML='<p>word</p>';
+ const range=document.createRange();range.selectNodeContents(document.querySelector('p')!);
+ let top=20;Object.defineProperty(range,'getClientRects',{value:()=>[{left:10,right:50,top,bottom:top+20,width:40,height:20}]});
+ let queue:FrameRequestCallback[]=[];
+ const originalRAF=window.requestAnimationFrame;window.requestAnimationFrame=cb=>{queue.push(cb);return queue.length;};
+ let snapshot=Array.from({length:120},(_,i)=>({id:`n${i}`,anchor,color:'#ff0000',opacity:1,markupStyle:'strikeout',noteContent:`note ${i}`}));
+ const taps:string[]=[];
+ const renderer=annotations.install({document,window,range:()=>range},{href:'chapter.xhtml',documentId:undefined,pageWidth:()=>1024,annotations:()=>snapshot,labels:()=>({comment:'Nota'}),isCurrent:()=>true,onTap:(id:string)=>taps.push(id)});
+ const flush=()=>{const tasks=queue;queue=[];tasks.forEach(cb=>cb(0));};flush();
+ expect(document.querySelectorAll('[data-annotation-id]')).toHaveLength(120);
+ expect(document.querySelectorAll('[data-papyrus-overlay] button')).toHaveLength(1);
+ const group=document.querySelector('[data-annotation-id="n0"]')!;
+ expect((group.firstChild as HTMLElement).style.top).toBe('30px');
+ expect((group.lastChild as HTMLElement).style.left).toBe('980px');
+ snapshot=snapshot.map(item=>({...item,markupStyle:'highlight'}));renderer.schedule();flush();
+ expect(Number((group.firstChild as HTMLElement).style.opacity)).toBeLessThanOrEqual(0.35);
+ snapshot=snapshot.map(item=>({...item,markupStyle:'strikeout'}));renderer.schedule();flush();
+ expect((group.lastChild as HTMLElement).textContent).toBe('120');
+ (group.lastChild as HTMLElement).click();expect(taps).toEqual(['n0']);
+ top=80;renderer.schedule();flush();expect(document.querySelector('[data-annotation-id="n0"]')).toBe(group);expect((group.firstChild as HTMLElement).style.top).toBe('90px');
+ snapshot=[];renderer.schedule();flush();expect(document.querySelectorAll('[data-annotation-id]')).toHaveLength(0);
+ renderer.destroy();expect(document.querySelector('[data-papyrus-overlay]')).toBeNull();window.requestAnimationFrame=originalRAF;
+});

package/runtime/epubReader.js

@@ -0,0 +1,58 @@
+(function(root){
+  function mode(value){return value==='chapter-scroll'?'chapter-scroll':'paged';}
+  function validCfi(value){return typeof value==='string' && value.length<=4096 && /^epubcfi\([^\n<>]+\)$/.test(value);}
+  function options(value){return {manager:'default',flow:mode(value)==='paged'?'paginated':'scrolled-doc',spread:'none',width:'100%',height:'100%',allowScriptedContent:false};}
+  function gesture(start,end,state){
+    if(!start || !end || state.selected || state.interactive || state.multitouch)return null;
+    var dx=end.x-start.x,dy=end.y-start.y,elapsed=end.time-start.time;
+    if(state.mode==='paged' && Math.abs(dx)>=48 && Math.abs(dx)>Math.abs(dy)*1.5 && elapsed>=0 && elapsed<1500)return (dx<0)!==Boolean(state.rtl)?'next':'prev';
+    if(elapsed>=0 && elapsed<450 && Math.hypot(dx,dy)<=12)return 'tap';
+    return null;
+  }
+  function location(raw,count,readingMode,geometry){
+    var start=raw && raw.start;if(!start || !validCfi(start.cfi))return null;
+    var displayed=start.displayed||{},chapter=Math.max(1,(Number(start.index)||0)+1);
+    var visualPage=mode(readingMode)==='paged' && Number.isFinite(displayed.page)?displayed.page:null;
+    var total=mode(readingMode)==='paged' && Number.isFinite(displayed.total)?displayed.total:null;
+    var atStart=Boolean(raw.atStart),atEnd=Boolean(raw.atEnd);
+    // Chromium may round a column offset down by a fraction of a CSS pixel.
+    // Keep epub.js authoritative outside a 1px boundary, and for RTL layouts.
+    if(visualPage!==null && total>0 && geometry && geometry.direction==='ltr' && geometry.pageWidth>0 && Number.isFinite(geometry.offset)){
+      var boundary=Math.round(geometry.offset/geometry.pageWidth);
+      if(Math.abs(geometry.offset-boundary*geometry.pageWidth)<=1){
+        visualPage=Math.min(total,Math.max(1,boundary+1));
+        atStart=chapter===(geometry.firstIndex ?? 0)+1 && visualPage===1;
+        atEnd=chapter===(geometry.lastIndex ?? count-1)+1 && visualPage===total;
+      }
+    }
+    var fraction=total?Math.max(0,(visualPage-1)/total):0;
+    return {version:1,cfi:start.cfi,href:start.href||'',chapter:chapter,chapterCount:count,visualPage:visualPage,visualPageCount:total,progress:Math.min(1,Math.max(0,(chapter-1+fraction)/Math.max(1,count))),mode:mode(readingMode),atStart:atStart,atEnd:atEnd};
+  }
+  function installResizeAnchor(manager,readCfi){
+    var original=manager.resize,anchor=null;
+    function resize(width,height,target){
+      if(validCfi(target))anchor=target;
+      if(!anchor){var current=readCfi();if(validCfi(current))anchor=current;}
+      // epub.js accepts a logical target as its third argument. Keep it across
+      // keyboard/dialog reflows instead of adopting each new viewport start.
+      return original.call(this,width,height,anchor || target);
+    }
+    manager.resize=resize;
+    return {cfi:function(){return anchor;},invalidate:function(){anchor=null;},destroy:function(){if(manager.resize===resize)manager.resize=original;anchor=null;}};
+  }
+  function install(contents,config){
+    var doc=contents.document,win=contents.window,start=null,blocked=false;
+    function point(e){var t=e.changedTouches&&e.changedTouches[0]||e.touches&&e.touches[0];return t?{x:t.clientX,y:t.clientY,time:Date.now()}:null;}
+    function selected(){return Boolean(String(win.getSelection()||'').trim()) || config.blocked();}
+    function interactive(target){return Boolean(target && target.closest && target.closest('a,button,input,textarea,select,[contenteditable="true"],[data-papyrus-overlay]'));}
+    function begin(e){start=point(e);blocked=e.touches.length!==1 || selected() || interactive(e.target);}
+    function invalidateScroll(finish){if(config.current() && start && finish && config.mode()==='chapter-scroll' && !blocked && !selected() && Math.abs(finish.y-start.y)>12 && Math.abs(finish.y-start.y)>Math.abs(finish.x-start.x) && config.interact)config.interact();}
+    function move(e){if(e.touches.length!==1)blocked=true;invalidateScroll(point(e));}
+    function end(e){var finish=point(e);invalidateScroll(finish);var action=gesture(start,finish,{mode:config.mode(),rtl:config.rtl(),selected:selected(),interactive:blocked||interactive(e.target)||Boolean(config.annotationHit && config.annotationHit(point(e))),multitouch:blocked});start=null;if(!config.current())return;if(action==='tap')config.tap();else if(action)config.turn(action==='next'?1:-1);}
+    function cancel(){start=null;blocked=true;}
+    function link(e){if(config.current() && e.target?.closest?.('a') && config.interact)config.interact();}
+    doc.addEventListener('touchstart',begin,{passive:true});doc.addEventListener('touchmove',move,{passive:true});doc.addEventListener('touchend',end,{passive:true});doc.addEventListener('touchcancel',cancel,{passive:true});doc.addEventListener('click',link);
+    return function(){doc.removeEventListener('touchstart',begin);doc.removeEventListener('touchmove',move);doc.removeEventListener('touchend',end);doc.removeEventListener('touchcancel',cancel);doc.removeEventListener('click',link);};
+  }
+  root.PapyrusEpubReader={mode:mode,validCfi:validCfi,options:options,gesture:gesture,location:location,installResizeAnchor:installResizeAnchor,install:install};
+})(typeof window==='undefined'?globalThis:window);

package/runtime/epubReader.test.ts

@@ -0,0 +1,74 @@
+import {readFileSync} from 'node:fs';
+import {JSDOM} from 'jsdom';
+import {describe,it,expect} from 'vitest';
+const load=()=>{const d=new JSDOM('',{runScripts:'outside-only'});d.window.eval(readFileSync('packages/ui-react-native/runtime/epubReader.js','utf8'));return (d.window as any).PapyrusEpubReader;};
+describe('EPUB reading policy',()=>{
+ it('defaults to real paginated default manager and one visual page',()=>{const p=load();expect(p.options('paged')).toMatchObject({manager:'default',flow:'paginated',spread:'none'});expect(p.mode()).toBe('paged');expect(p.options('chapter-scroll').flow).toBe('scrolled-doc');});
+ it('recognizes one swipe with RTL reversal, excluding selection/interactivity/multitouch',()=>{const p=load(),start={x:200,y:100,time:0},end={x:40,y:108,time:200};expect(p.gesture(start,end,{mode:'paged'})).toBe('next');expect(p.gesture(start,end,{mode:'paged',rtl:true})).toBe('prev');for(const k of ['selected','interactive','multitouch'])expect(p.gesture(start,end,{mode:'paged',[k]:true})).toBe(null);expect(p.gesture(start,{x:202,y:103,time:600},{mode:'paged'})).toBe(null);expect(p.gesture(start,{x:202,y:103,time:100},{mode:'paged'})).toBe('tap');});
+ it('separates chapter and visual page and never treats spine count as pages',()=>{const p=load();expect(p.location({start:{index:2,cfi:'epubcfi(/6/6!/4/2)',displayed:{page:4,total:12}}},10,'paged')).toMatchObject({chapter:3,chapterCount:10,visualPage:4,visualPageCount:12,cfi:'epubcfi(/6/6!/4/2)'});expect(p.location({start:{index:2,cfi:'epubcfi(/6/6!/4/2)'}},10,'chapter-scroll').visualPage).toBe(null);});
+ it('rejects invalid location CFIs',()=>{expect(load().validCfi('javascript:bad')).toBe(false);expect(load().validCfi('epubcfi(/6/4!/4/2)')).toBe(true);});
+});
+
+describe('EPUB iframe gestures', () => {
+ it('cleans listeners and excludes annotations and links from tap', () => {
+  const d=new JSDOM('<p>text</p><a href="#">link</a>',{runScripts:'outside-only'});
+  d.window.eval(readFileSync('packages/ui-react-native/runtime/epubReader.js','utf8'));
+  const p=(d.window as any).PapyrusEpubReader;
+  let taps=0,hit=true;
+  const cleanup=p.install({document:d.window.document,window:d.window},{mode:()=> 'paged',rtl:()=>false,blocked:()=>false,current:()=>true,annotationHit:()=>hit,tap:()=>taps++,turn:()=>{}});
+  function touch(target:Element){for(const type of ['touchstart','touchend']){const e=new d.window.Event(type,{bubbles:true});Object.defineProperties(e,{touches:{value:type==='touchend'?[]:[{clientX:30,clientY:40}]},changedTouches:{value:[{clientX:30,clientY:40}]}});target.dispatchEvent(e);}}
+  touch(d.window.document.querySelector('p')!);expect(taps).toBe(0);hit=false;touch(d.window.document.querySelector('a')!);expect(taps).toBe(0);touch(d.window.document.querySelector('p')!);expect(taps).toBe(1);cleanup();touch(d.window.document.querySelector('p')!);expect(taps).toBe(1);
+ });
+});
+
+describe('EPUB subpixel column boundaries',()=>{
+ it('normalizes only a nearby LTR boundary and updates start/end',()=>{
+  const p=load(),raw={start:{index:0,cfi:'epubcfi(/6/2!/4/12)',displayed:{page:1,total:17}},atStart:true,atEnd:false};
+  expect(p.location(raw,3,'paged',{offset:411.4285888671875,pageWidth:412,direction:'ltr'})).toMatchObject({visualPage:2,atStart:false});
+  expect(p.location({...raw,start:{...raw.start,index:1}},4,'paged',{offset:0,pageWidth:412,direction:'ltr',firstIndex:1,lastIndex:2})).toMatchObject({atStart:true});
+  expect(p.location(raw,3,'paged',{offset:400,pageWidth:412,direction:'ltr'}).visualPage).toBe(1);
+  expect(p.location(raw,3,'paged',{offset:411.5,pageWidth:412,direction:'rtl'}).visualPage).toBe(1);
+  expect(p.location({...raw,start:{...raw.start,index:2,displayed:{page:16,total:17}}},3,'paged',{offset:6591.5,pageWidth:412,direction:'ltr'})).toMatchObject({visualPage:17,atEnd:true});
+ });
+});
+
+describe('EPUB resize anchors',()=>{
+ it('preserves a logical CFI through transient resize until real interaction',()=>{
+  const p=load(),calls:any[]=[];let current='epubcfi(/6/2!/4/12/1:149)';
+  const original=function(this:any,w:any,h:any,target:any){calls.push([this,w,h,target]);return 'resized';};
+  const manager={resize:original};const anchor=p.installResizeAnchor(manager,()=>current);
+  expect(manager.resize(412,889,undefined)).toBe('resized');
+  current='epubcfi(/6/2!/4/12/1:97)';manager.resize(412,863,undefined);
+  expect(calls.map(c=>c[3])).toEqual(['epubcfi(/6/2!/4/12/1:149)','epubcfi(/6/2!/4/12/1:149)']);
+  expect(anchor.cfi()).toBe('epubcfi(/6/2!/4/12/1:149)');anchor.invalidate();
+  current='epubcfi(/6/2!/4/22/1:149)';manager.resize(863,412,undefined);
+  expect(calls.at(-1)[3]).toBe(current);expect(calls.every(c=>c[0]===manager)).toBe(true);
+  anchor.destroy();expect(manager.resize).toBe(original);
+ });
+ it('honors explicit valid targets and does not pass invalid CFIs',()=>{
+  const p=load(),calls:any[]=[];const manager={resize:(w:any,h:any,target:any)=>calls.push(target)};
+  const anchor=p.installResizeAnchor(manager,()=>null);manager.resize(1,2,undefined);expect(calls[0]).toBeUndefined();
+  manager.resize(1,2,'epubcfi(/6/4!/4/2)');expect(anchor.cfi()).toBe('epubcfi(/6/4!/4/2)');anchor.destroy();
+ });
+});
+
+it('does not discard a resize anchor for tap, selection or note marker',()=>{
+ const d=new JSDOM('<p>text</p><a href="#">link</a><button data-papyrus-overlay>note</button>',{runScripts:'outside-only'});
+ d.window.eval(readFileSync('packages/ui-react-native/runtime/epubReader.js','utf8'));
+ let invalidations=0,readingMode='paged';const p=(d.window as any).PapyrusEpubReader;
+ const cleanup=p.install({document:d.window.document,window:d.window},{mode:()=>readingMode,rtl:()=>false,blocked:()=>false,current:()=>true,tap:()=>{},turn:()=>invalidations++,interact:()=>invalidations++});
+ function touch(target:Element,y=40){for(const type of ['touchstart','touchend']){const point={clientX:30,clientY:type==='touchend'?y:40};const e=new d.window.Event(type,{bubbles:true});Object.defineProperties(e,{touches:{value:type==='touchend'?[]:[point]},changedTouches:{value:[point]}});target.dispatchEvent(e);}}
+ touch(d.window.document.querySelector('p')!);touch(d.window.document.querySelector('button')!);expect(invalidations).toBe(0);
+ readingMode='chapter-scroll';touch(d.window.document.querySelector('p')!,200);expect(invalidations).toBe(1);
+ d.window.document.querySelector('a')!.dispatchEvent(new d.window.Event('click',{bubbles:true}));expect(invalidations).toBe(2);cleanup();
+});
+
+it('invalidates chapter-scroll before relocation and ignores stale iframe callbacks',()=>{
+ const d=new JSDOM('<p>text</p><a href="#">link</a>',{runScripts:'outside-only'});
+ d.window.eval(readFileSync('packages/ui-react-native/runtime/epubReader.js','utf8'));
+ let invalidations=0,current=true;
+ const cleanup=(d.window as any).PapyrusEpubReader.install({document:d.window.document,window:d.window},{mode:()=> 'chapter-scroll',rtl:()=>false,blocked:()=>false,current:()=>current,tap:()=>{},turn:()=>{},interact:()=>invalidations++});
+ function dispatch(type:string,y:number){const point={clientX:30,clientY:y},e=new d.window.Event(type,{bubbles:true});Object.defineProperties(e,{touches:{value:type==='touchend'?[]:[point]},changedTouches:{value:[point]}});d.window.document.querySelector('p')!.dispatchEvent(e);}
+ dispatch('touchstart',40);dispatch('touchmove',120);expect(invalidations).toBe(1);
+ current=false;dispatch('touchend',180);d.window.document.querySelector('a')!.dispatchEvent(new d.window.Event('click',{bubbles:true}));expect(invalidations).toBe(1);cleanup();
+});

package/runtime/epubRuntime.test.ts

@@ -0,0 +1,48 @@
+import {readFileSync} from 'node:fs';
+import {JSDOM} from 'jsdom';
+import {describe,it,expect,vi} from 'vitest';
+
+function runtime() {
+ const dom=new JSDOM('<div id="viewer"></div>',{runScripts:'outside-only'});
+ const messages:any[]=[], renditions:any[]=[];
+ (dom.window as any).ReactNativeWebView={postMessage:(raw:string)=>messages.push(JSON.parse(raw))};
+ for (const helper of ['epubReader.js','epubAnnotations.js']) {
+  dom.window.eval(readFileSync(`packages/ui-react-native/runtime/${helper}`,'utf8'));
+ }
+ const book:any={ready:Promise.resolve(),spine:{items:[{href:'a.xhtml'},{href:'b.xhtml'}]},loaded:{navigation:Promise.resolve({toc:[]})},destroy:vi.fn(),renderTo:vi.fn((_viewer,options)=>{
+  const events:any={};
+  const r:any={options,manager:{resize:vi.fn(),on:vi.fn(),off:vi.fn()},hooks:{content:{register:vi.fn()},unloaded:{register:vi.fn()}},on:(name:string,fn:any)=>events[name]=fn,themes:{fontSize:vi.fn()},destroy:vi.fn(),display:vi.fn(async()=>{}),next:vi.fn(async()=>{}),prev:vi.fn(async()=>{}),emit:(name:string,data:any)=>events[name]?.(data)};
+  renditions.push(r);return r;
+ })};
+ (dom.window as any).ePub=()=>book;
+ dom.window.eval(readFileSync('packages/ui-react-native/runtime/runtime.js','utf8'));
+ const send=async(id:string,kind:string,payload:any)=>{
+  dom.window.dispatchEvent(new dom.window.MessageEvent('message',{data:JSON.stringify({id,kind,payload})}));
+  for(let n=0;n<100;n++){const result=messages.find(m=>m.type==='response'&&m.id===id);if(result)return result;await new Promise(r=>setTimeout(r,1));}
+  throw new Error('No response: '+id);
+ };
+ return {send,messages,renditions,book,dom};
+}
+describe('EPUB runtime bridge',()=>{
+ it('loads paginated by default and emits visual location within the same chapter',async()=>{
+  const r=runtime();expect((await r.send('load','load',{type:'epub',documentSessionId:'s',source:{kind:'base64',data:'AA=='}})).ok).toBe(true);
+  expect(r.renditions[0].options.flow).toBe('paginated');
+  r.renditions[0].emit('relocated',{start:{index:0,href:'a.xhtml',cfi:'epubcfi(/6/2!/4/2:10)',displayed:{page:2,total:8}}});
+  expect(r.messages).toContainEqual(expect.objectContaining({name:'EPUB_LOCATION',payload:expect.objectContaining({location:expect.objectContaining({visualPage:2,chapter:1})})}));
+ });
+ it('rebuilds chapter scroll at the current CFI and rejects a stale session',async()=>{
+  const r=runtime();await r.send('load','load',{type:'epub',documentSessionId:'s',source:{kind:'base64',data:'AA=='}});
+  const cfi='epubcfi(/6/2!/4/2:10)';r.renditions[0].emit('relocated',{start:{index:0,cfi,displayed:{page:2,total:8}}});
+  expect((await r.send('mode','set-epub-view-mode',{epubMode:'chapter-scroll',documentSessionId:'s'})).ok).toBe(true);
+  expect(r.renditions[1].options.flow).toBe('scrolled-doc');expect(r.renditions[1].display).toHaveBeenCalledWith(cfi);
+  expect((await r.send('old','epub-go-to-location',{cfi,documentSessionId:'old'})).ok).toBe(false);
+ });
+ it('serializes rapid mode changes and restores on the rebuilt rendition',async()=>{
+  const r=runtime();await r.send('load','load',{type:'epub',documentSessionId:'s',source:{kind:'base64',data:'AA=='}});
+  const cfi='epubcfi(/6/2!/4/2:10)';
+  await Promise.all([r.send('scroll','set-epub-view-mode',{epubMode:'chapter-scroll',documentSessionId:'s'}),r.send('paged','set-epub-view-mode',{epubMode:'paged',documentSessionId:'s'}),r.send('restore','epub-go-to-location',{cfi,documentSessionId:'s'})]);
+  expect(r.renditions.at(-1).options.flow).toBe('paginated');
+  expect(r.renditions.at(-1).display).toHaveBeenCalledWith(cfi);
+ });
+ it('keeps TXT zoom independent of EPUB state',async()=>{const r=runtime();await r.send('load','load',{type:'text',source:{kind:'text',text:'sample'}});expect((await r.send('zoom','set-zoom',{zoom:1.2})).ok).toBe(true);});
+});

package/runtime/epubSelectionMenu.test.ts

@@ -0,0 +1,39 @@
+import {readFileSync} from 'node:fs';
+import {JSDOM} from 'jsdom';
+import {describe,it,expect} from 'vitest';
+const source=readFileSync('packages/ui-react-native/runtime/runtime.js','utf8');
+function fixture() {
+ const messages:any[]=[];
+ const dom=new JSDOM('<div id="viewer"></div>',{runScripts:'outside-only'});
+ dom.window.ReactNativeWebView={postMessage:(raw:string)=>messages.push(JSON.parse(raw))} as never;
+ // Expose only the setup boundary in the test copy; execute the production handler.
+ dom.window.eval(source.replace("sendMessage({ type: 'ready' });",`
+ window.seedMenu=(session,payload,contents)=>{documentSessionId=session;nativeMenuSelection={payload,contents};};`));
+ const chapter=new JSDOM('<p>one word and a phrase</p>');
+ const text=chapter.window.document.querySelector('p')!.firstChild!;
+ const range=chapter.window.document.createRange();range.setStart(text,4);range.setEnd(text,8);
+ chapter.window.getSelection()!.addRange(range);
+ const payload={documentSessionId:'current',text:'word',pageIndex:1,
+  anchor:{kind:'epub-cfi',version:1,cfiRange:'epubcfi(/6/2!/4/2:4)',href:'one.xhtml',quote:'word'}};
+ (dom.window as any).seedMenu('current',payload,{document:chapter.window.document,window:chapter.window});
+ const send=(key:string,session='current')=>dom.window.dispatchEvent(new dom.window.MessageEvent('message',
+  {data:JSON.stringify({type:'epub-selection-action',id:'selection-menu',key,documentSessionId:session})}));
+ return {messages,chapter,send,dom};
+}
+describe('native EPUB menu dispatch',()=>{
+ it('uses the chapter CFI snapshot even when root selection is empty',()=>{
+  const f=fixture();expect(f.dom.window.getSelection()!.toString()).toBe('');f.send('highlight');
+  expect(f.messages).toContainEqual(expect.objectContaining({name:'EPUB_SELECTION_ACTION',payload:expect.objectContaining({action:'highlight',text:'word',anchor:expect.objectContaining({href:'one.xhtml'})})}));
+  expect(f.chapter.window.getSelection()!.toString()).toBe('');
+ });
+ it('rejects stale document sessions and unknown actions',()=>{
+  const f=fixture();f.send('copy','old');f.send('deleteDocument');expect(f.messages).toHaveLength(0);
+  expect(f.chapter.window.getSelection()!.toString()).toBe('word');
+ });
+ it('selects all inside the chapter, without annotating the previous word',()=>{
+  const f=fixture();f.send('selectAll');expect(f.chapter.window.getSelection()!.toString()).toBe('one word and a phrase');expect(f.messages).toHaveLength(0);
+ });
+ it('consumes each action once',()=>{
+  const f=fixture();f.send('comment');f.send('comment');expect(f.messages).toHaveLength(1);
+ });
+});