@readium/helpers 1.0.0 → 1.1.0

package/README.md

@@ -1,11 +1,11 @@
 # @readium/helpers
 
-General-purpose browser helpers for Readium packages: color parsing/contrast utilities and OS/browser detection.
+General-purpose browser helpers for Readium packages: color parsing/contrast utilities, OS/browser detection, and WICG Text Fragment parsing/resolution/generation.
 
 ## Installation
 
 ```ts
-import { colorToRgba, checkContrast, isDarkColor, isLightColor, getContrastingTextColor, adjustColorForContrast, getLuminance, sML, sMLWithRequest } from "@readium/helpers";
+import { colorToRgba, checkContrast, isDarkColor, isLightColor, getContrastingTextColor, adjustColorForContrast, getLuminance, sML, sMLWithRequest, decodeTextFragmentDirective, processTextFragmentDirective, generateFragmentFromRange } from "@readium/helpers";
 ```
 
 ## Color utilities
@@ -45,6 +45,24 @@ sMLWithRequest.iOSRequest // "mobile" | "desktop" | undefined — iPadOS "Reques
 
 `sML` is a bundled subset of [sML.js](https://github.com/satorumurmur/sML) by Satoru Matsushima, MIT licensed. Falls back safely when `navigator` is unavailable (SSR).
 
+## Text Fragments
+
+```ts
+// Parses a "text=[prefix-,]textStart[,textEnd][,-suffix]" directive out of a URL fragment/hash
+decodeTextFragmentDirective("#some-id:~:text=hello,world"): TextFragmentDirective | undefined
+
+// Resolves a TextFragmentDirective to zero or more Ranges in a document
+processTextFragmentDirective(directive, document, root?): Range[]
+
+// Generates a TextFragmentDirective that uniquely resolves back to the given Range
+generateFragmentFromRange(range): { status: GenerateFragmentStatusValue; fragment?: TextFragment }
+```
+
+`processTextFragmentDirective` and `generateFragmentFromRange` come from a vendored [text-fragments-polyfill](https://github.com/GoogleChromeLabs/text-fragments-polyfill) — see [Third-party licenses](#third-party-licenses).
+
 ## Third-party licenses
 
-This package is BSD-3-Clause, except for `src/sML.ts`, which vendors code from [sML.js](https://github.com/satorumurmur/sML), Copyright (c) Satoru Matsushima, licensed under the MIT license (see the header of that file for the full notice).
+This package is BSD-3-Clause, except for:
+
+- `src/sML.ts`, which vendors code from [sML.js](https://github.com/satorumurmur/sML), Copyright (c) Satoru Matsushima, licensed under the MIT license (see the header of that file for the full notice)
+- `src/vendor/text-fragments-polyfill/`, ported from [text-fragments-polyfill](https://github.com/GoogleChromeLabs/text-fragments-polyfill), licensed under the Apache License 2.0 (see that directory's `LICENSE` and `README.MD`)

package/dist/index.js

@@ -1 +1 @@
-import{adjustColorForContrast as r,checkContrast as e,colorToRgba as s,getContrastingTextColor as a,getLuminance as C,isDarkColor as i,isLightColor as n}from"./color.js";import{sML as l,sMLWithRequest as c}from"./sML.js";export{r as adjustColorForContrast,e as checkContrast,s as colorToRgba,a as getContrastingTextColor,C as getLuminance,i as isDarkColor,n as isLightColor,l as sML,c as sMLWithRequest};
+import{adjustColorForContrast as r,checkContrast as o,colorToRgba as n,getContrastingTextColor as a,getLuminance as g,isDarkColor as i,isLightColor as m}from"./color.js";import{sML as F,sMLWithRequest as c}from"./sML.js";import{decodeTextFragmentDirective as l}from"./textFragmentDirective.js";import{forTesting as f,internal as p,processTextFragmentDirective as T}from"./vendor/text-fragments-polyfill/textFragmentMatcher.js";import{GenerateFragmentStatus as d,generateFragment as L,generateFragmentFromRange as R,isValidRangeForFragmentGeneration as h,setFragmentGenerationTimeout as D}from"./vendor/text-fragments-polyfill/textFragmentGenerator.js";export{d as GenerateFragmentStatus,r as adjustColorForContrast,o as checkContrast,n as colorToRgba,l as decodeTextFragmentDirective,f as forTesting,L as generateFragment,R as generateFragmentFromRange,a as getContrastingTextColor,g as getLuminance,p as internal,i as isDarkColor,m as isLightColor,h as isValidRangeForFragmentGeneration,T as processTextFragmentDirective,F as sML,c as sMLWithRequest,D as setFragmentGenerationTimeout};

package/dist/textFragmentDirective.js

@@ -0,0 +1 @@
+const r=":~:text=";function d(n){if(!n)return;const i=n.indexOf(r);if(i===-1)return;const o=n.slice(i+r.length).split("&")[0];if(o)try{let t=o.split(",");const e={textStart:""};return t.length>1&&t[0].endsWith("-")&&(e.prefix=decodeURIComponent(t[0].slice(0,-1)),t=t.slice(1)),t.length>1&&t[t.length-1].startsWith("-")&&(e.suffix=decodeURIComponent(t[t.length-1].slice(1)),t=t.slice(0,-1)),t.length===0||t[0]===""?void 0:(e.textStart=decodeURIComponent(t[0]),t.length>1&&(e.textEnd=decodeURIComponent(t[1])),e)}catch{return}}export{d as decodeTextFragmentDirective};

package/dist/vendor/text-fragments-polyfill/textFragmentGenerator.js

@@ -0,0 +1 @@
+import{internal as a,processTextFragmentDirective as W}from"./textFragmentMatcher.js";const X=300,F=20,Y=1,C=3,b=1,G=1e4,V=500;let R=500,P;class L extends Error{constructor(){super(...arguments),this.isTimeout=!0}}const ft=e=>{R=e},x={SUCCESS:0,INVALID_SELECTION:1,AMBIGUOUS:2,TIMEOUT:3,EXECUTION_FAILED:4},at=(e,t=Date.now())=>q(e,t),ot=(e,t=Date.now())=>{try{return U(e,t)}catch(s){return s instanceof L?{status:x.TIMEOUT}:{status:x.EXECUTION_FAILED}}},ct=e=>{if(!e.toString().substring(0,G).match(a.NON_BOUNDARY_CHARS))return!1;try{if(e.startContainer.ownerDocument.defaultView!==window.top)return!1}catch{return!1}let t=e.commonAncestorContainer,s=0;for(;t;){if(t.nodeType==Node.ELEMENT_NODE){const r=t;if(["TEXTAREA","INPUT"].includes(r.tagName.toUpperCase()))return!1;const n=r.attributes.getNamedItem("contenteditable");if(n&&n.value!=="false"||(s++,s>=V))return!1}t=t.parentNode}return!0},q=(e,t)=>{let s;try{s=e.getRangeAt(0)}catch{return{status:x.INVALID_SELECTION}}return U(s,t)},U=(e,t)=>{K(t);const s=e.startContainer.ownerDocument,r=j(s);et(e),nt(e);const n=e.cloneRange();if(st(e),e.collapsed)return{status:x.INVALID_SELECTION};let i;if(Q(e)){const h=a.normalizeString(e.toString()),o={textStart:h};if(h.length>=F&&y(o,s,r))return{status:x.SUCCESS,fragment:o};i=new k(s,r).setExactTextMatch(h)}else{const h=B(e),o=I(e);h&&o?i=new k(s,r).setStartAndEndSearchSpace(h,o):i=new k(s,r).setSharedSearchSpace(e.toString().trim())}const f=s.createRange();f.selectNodeContents(r);const l=f.cloneRange();f.setEnd(n.startContainer,n.startOffset),l.setStart(n.endContainer,n.endOffset);const O=I(f),c=B(l);(O||c)&&i.setPrefixAndSuffixSearchSpace(O,c),i.useSegmenter(a.makeNewSegmenter(s));let T=!1;do{d(),T=i.embiggen();const h=i.tryToMakeUniqueFragment();if(h!=null)return{status:x.SUCCESS,fragment:h}}while(T);return{status:x.AMBIGUOUS}},j=e=>e.querySelector("body")??e.documentElement,d=()=>{if(R===null)return;const e=Date.now()-P;if(e>R)throw new L(`Fragment generation timed out after ${e} ms.`)},K=e=>{P=e},B=e=>{let t=p(e);const s=g(t,e.endContainer);if(!s)return;const r=new Set;e.startContainer.nodeType===Node.ELEMENT_NODE&&e.startOffset===e.startContainer.childNodes.length&&r.add(e.startContainer);const n=t,i=new H(e,!0),f=e.cloneRange();for(;!f.collapsed&&t!=null;){if(d(),t.contains?.(n)?f.setStartAfter(t):f.setStartBefore(t),i.appendNode(t),i.textInBlock!==null)return i.textInBlock;t=a.forwardTraverse(s,r)}},I=e=>{let t=_(e);const s=g(t,e.startContainer);if(!s)return;const r=new Set;e.endContainer.nodeType===Node.ELEMENT_NODE&&e.endOffset===0&&r.add(e.endContainer);const n=t,i=new H(e,!1),f=e.cloneRange();for(;!f.collapsed&&t!=null;){if(d(),t.contains?.(n)?f.setEnd(t,0):f.setEndAfter(t),i.appendNode(t),i.textInBlock!==null)return i.textInBlock;t=a.backwardTraverse(s,r)}},z={ALL_PARTS:1,SHARED_START_AND_END:2,CONTEXT_ONLY:3};class k{constructor(t,s){this.Mode=z,this.startOffset=null,this.endOffset=null,this.prefixOffset=null,this.suffixOffset=null,this.prefixSearchSpace="",this.backwardsPrefixSearchSpace="",this.suffixSearchSpace="",this.numIterations=0,this.doc=t,this.root=s}tryToMakeUniqueFragment(){let t;if(this.mode===this.Mode.CONTEXT_ONLY?t={textStart:this.exactTextMatch}:t={textStart:this.getStartSearchSpace().substring(0,this.startOffset).trim(),textEnd:this.getEndSearchSpace().substring(this.endOffset).trim()},this.prefixOffset!=null){const s=this.getPrefixSearchSpace().substring(this.prefixOffset).trim();s&&(t.prefix=s)}if(this.suffixOffset!=null){const s=this.getSuffixSearchSpace().substring(0,this.suffixOffset).trim();s&&(t.suffix=s)}return y(t,this.doc,this.root)?t:void 0}embiggen(){let t=!0;if(this.mode===this.Mode.SHARED_START_AND_END?this.startOffset>=this.endOffset&&(t=!1):this.mode===this.Mode.ALL_PARTS?this.startOffset===this.getStartSearchSpace().length&&this.backwardsEndOffset()===this.getEndSearchSpace().length&&(t=!1):this.mode===this.Mode.CONTEXT_ONLY&&(t=!1),t){const r=this.getNumberOfRangeWordsToAdd();if(this.startOffset<this.getStartSearchSpace().length){let n=0;if(this.getStartSegments()!=null)for(;n<r&&this.startOffset<this.getStartSearchSpace().length;)this.startOffset=this.getNextOffsetForwards(this.getStartSegments(),this.startOffset,this.getStartSearchSpace()),n++;else{let i=this.startOffset;do{d();const f=this.getStartSearchSpace().substring(this.startOffset+1).search(a.BOUNDARY_CHARS);f===-1?this.startOffset=this.getStartSearchSpace().length:this.startOffset=this.startOffset+1+f,this.getStartSearchSpace().substring(i,this.startOffset).search(a.NON_BOUNDARY_CHARS)!==-1&&(i=this.startOffset,n++)}while(this.startOffset<this.getStartSearchSpace().length&&n<r)}this.mode===this.Mode.SHARED_START_AND_END&&(this.startOffset=Math.min(this.startOffset,this.endOffset))}if(this.backwardsEndOffset()<this.getEndSearchSpace().length){let n=0;if(this.getEndSegments()!=null)for(;n<r&&this.endOffset>0;)this.endOffset=this.getNextOffsetBackwards(this.getEndSegments(),this.endOffset),n++;else{let i=this.backwardsEndOffset();do{d();const f=this.getBackwardsEndSearchSpace().substring(this.backwardsEndOffset()+1).search(a.BOUNDARY_CHARS);f===-1?this.setBackwardsEndOffset(this.getEndSearchSpace().length):this.setBackwardsEndOffset(this.backwardsEndOffset()+1+f),this.getBackwardsEndSearchSpace().substring(i,this.backwardsEndOffset()).search(a.NON_BOUNDARY_CHARS)!==-1&&(i=this.backwardsEndOffset(),n++)}while(this.backwardsEndOffset()<this.getEndSearchSpace().length&&n<r)}this.mode===this.Mode.SHARED_START_AND_END&&(this.endOffset=Math.max(this.startOffset,this.endOffset))}}let s=!1;if((!t||this.startOffset+this.backwardsEndOffset()<F||this.numIterations>=Y)&&(this.backwardsPrefixOffset()!=null&&this.backwardsPrefixOffset()!==this.getPrefixSearchSpace().length||this.suffixOffset!=null&&this.suffixOffset!==this.getSuffixSearchSpace().length)&&(s=!0),s){const r=this.getNumberOfContextWordsToAdd();if(this.backwardsPrefixOffset()<this.getPrefixSearchSpace().length){let n=0;if(this.getPrefixSegments()!=null)for(;n<r&&this.prefixOffset>0;)this.prefixOffset=this.getNextOffsetBackwards(this.getPrefixSegments(),this.prefixOffset),n++;else{let i=this.backwardsPrefixOffset();do{d();const f=this.getBackwardsPrefixSearchSpace().substring(this.backwardsPrefixOffset()+1).search(a.BOUNDARY_CHARS);f===-1?this.setBackwardsPrefixOffset(this.getBackwardsPrefixSearchSpace().length):this.setBackwardsPrefixOffset(this.backwardsPrefixOffset()+1+f),this.getBackwardsPrefixSearchSpace().substring(i,this.backwardsPrefixOffset()).search(a.NON_BOUNDARY_CHARS)!==-1&&(i=this.backwardsPrefixOffset(),n++)}while(this.backwardsPrefixOffset()<this.getPrefixSearchSpace().length&&n<r)}}if(this.suffixOffset<this.getSuffixSearchSpace().length){let n=0;if(this.getSuffixSegments()!=null)for(;n<r&&this.suffixOffset<this.getSuffixSearchSpace().length;)this.suffixOffset=this.getNextOffsetForwards(this.getSuffixSegments(),this.suffixOffset,this.getSuffixSearchSpace()),n++;else{let i=this.suffixOffset;do{d();const f=this.getSuffixSearchSpace().substring(this.suffixOffset+1).search(a.BOUNDARY_CHARS);f===-1?this.suffixOffset=this.getSuffixSearchSpace().length:this.suffixOffset=this.suffixOffset+1+f,this.getSuffixSearchSpace().substring(i,this.suffixOffset).search(a.NON_BOUNDARY_CHARS)!==-1&&(i=this.suffixOffset,n++)}while(this.suffixOffset<this.getSuffixSearchSpace().length&&n<r)}}}return this.numIterations++,t||s}setStartAndEndSearchSpace(t,s){return this.startSearchSpace=t,this.endSearchSpace=s,this.backwardsEndSearchSpace=A(s),this.startOffset=0,this.endOffset=s.length,this.mode=this.Mode.ALL_PARTS,this}setSharedSearchSpace(t){return this.sharedSearchSpace=t,this.backwardsSharedSearchSpace=A(t),this.startOffset=0,this.endOffset=t.length,this.mode=this.Mode.SHARED_START_AND_END,this}setExactTextMatch(t){return this.exactTextMatch=t,this.mode=this.Mode.CONTEXT_ONLY,this}setPrefixAndSuffixSearchSpace(t,s){return t&&(this.prefixSearchSpace=t,this.backwardsPrefixSearchSpace=A(t),this.prefixOffset=t.length),s&&(this.suffixSearchSpace=s,this.suffixOffset=0),this}useSegmenter(t){return t==null?this:(this.mode===this.Mode.ALL_PARTS?(this.startSegments=t.segment(this.startSearchSpace),this.endSegments=t.segment(this.endSearchSpace)):this.mode===this.Mode.SHARED_START_AND_END&&(this.sharedSegments=t.segment(this.sharedSearchSpace)),this.prefixSearchSpace&&(this.prefixSegments=t.segment(this.prefixSearchSpace)),this.suffixSearchSpace&&(this.suffixSegments=t.segment(this.suffixSearchSpace)),this)}getNumberOfContextWordsToAdd(){return this.backwardsPrefixOffset()===0&&this.suffixOffset===0?C:b}getNumberOfRangeWordsToAdd(){return this.startOffset===0&&this.backwardsEndOffset()===0?C:b}getNextOffsetForwards(t,s,r){let n=t.containing(s);for(;n!=null;){d();const i=n.index+n.segment.length;if(n.isWordLike)return i;n=t.containing(i)}return r.length}getNextOffsetBackwards(t,s){let r=t.containing(s);for((!r||s==r.index)&&(r=t.containing(s-1));r!=null;){if(d(),r.isWordLike)return r.index;r=t.containing(r.index-1)}return 0}getStartSearchSpace(){return this.mode===this.Mode.SHARED_START_AND_END?this.sharedSearchSpace:this.startSearchSpace}getStartSegments(){return this.mode===this.Mode.SHARED_START_AND_END?this.sharedSegments:this.startSegments}getEndSearchSpace(){return this.mode===this.Mode.SHARED_START_AND_END?this.sharedSearchSpace:this.endSearchSpace}getEndSegments(){return this.mode===this.Mode.SHARED_START_AND_END?this.sharedSegments:this.endSegments}getBackwardsEndSearchSpace(){return this.mode===this.Mode.SHARED_START_AND_END?this.backwardsSharedSearchSpace:this.backwardsEndSearchSpace}getPrefixSearchSpace(){return this.prefixSearchSpace}getPrefixSegments(){return this.prefixSegments}getBackwardsPrefixSearchSpace(){return this.backwardsPrefixSearchSpace}getSuffixSearchSpace(){return this.suffixSearchSpace}getSuffixSegments(){return this.suffixSegments}backwardsEndOffset(){return this.getEndSearchSpace().length-this.endOffset}setBackwardsEndOffset(t){this.endOffset=this.getEndSearchSpace().length-t}backwardsPrefixOffset(){return this.prefixOffset==null?null:this.getPrefixSearchSpace().length-this.prefixOffset}setBackwardsPrefixOffset(t){this.prefixOffset!=null&&(this.prefixOffset=this.getPrefixSearchSpace().length-t)}}class H{constructor(t,s){this.textFound=!1,this.textNodes=[],this.textInBlock=null,this.searchRange=t,this.isForwardTraversal=s}appendNode(t){if(this.textInBlock!==null)return;if(N(t)){this.textFound?(this.isForwardTraversal||this.textNodes.reverse(),this.textInBlock=this.textNodes.map(r=>r.textContent).join("").trim()):this.textNodes=[];return}if(!D(t))return;const s=this.getNodeIntersectionWithRange(t);this.textFound=this.textFound||(s.textContent??"").trim()!=="",this.textNodes.push(s)}getNodeIntersectionWithRange(t){let s=null,r=null;const n=(t.textContent??"").length;return t===this.searchRange.startContainer&&this.searchRange.startOffset!==0&&(s=this.searchRange.startOffset),t===this.searchRange.endContainer&&this.searchRange.endOffset!==n&&(r=this.searchRange.endOffset),s!==null||r!==null?{textContent:(t.textContent??"").substring(s??0,r??n)}:t}}const y=(e,t,s)=>W(e,t,s).length===1,A=e=>[...e||""].reverse().join(""),Q=e=>e.toString().length>X?!1:!Z(e),p=e=>{let t=e.startContainer;return t.nodeType==Node.ELEMENT_NODE&&e.startOffset<t.childNodes.length&&(t=t.childNodes[e.startOffset]),t},_=e=>{let t=e.endContainer;return t.nodeType==Node.ELEMENT_NODE&&e.endOffset>0&&(t=t.childNodes[e.endOffset-1]),t},$=e=>{const t=p(e);if(D(t)&&a.isNodeVisible(t))return t;const s=a.makeTextNodeWalker(e);return s.currentNode=t,s.nextNode()},J=e=>{const t=_(e);if(D(t)&&a.isNodeVisible(t))return t;const s=a.makeTextNodeWalker(e);return s.currentNode=t,a.backwardTraverse(s,new Set)},Z=e=>{const t=e.cloneRange();let s=p(t);const r=g(s);if(!r)return!1;const n=new Set;for(;!t.collapsed&&s!=null;){if(N(s))return!0;s!=null&&t.setStartAfter(s),s=a.forwardTraverse(r,n),d()}return!1},M=(e,t)=>{if(e.nodeType!==Node.TEXT_NODE)return-1;const s=e,r=t??s.data.length;if(r<s.data.length&&a.BOUNDARY_CHARS.test(s.data[r]))return r;const n=s.data.substring(0,r),i=A(n).search(a.BOUNDARY_CHARS);return i!==-1?r-i:-1},tt=(e,t)=>{if(e.nodeType!==Node.TEXT_NODE)return-1;const s=e,r=t??0;if(r<s.data.length&&r>0&&a.BOUNDARY_CHARS.test(s.data[r-1]))return r;const i=s.data.substring(r).search(a.BOUNDARY_CHARS);return i!==-1?r+i:-1},g=(e,t)=>{if(!e)return;let s=e;const r=t??e;for(;!s.contains?.(r)||!N(s);)s.parentNode&&(s=s.parentNode);const i=(s.ownerDocument??s).createTreeWalker(s,NodeFilter.SHOW_ELEMENT|NodeFilter.SHOW_TEXT,{acceptNode:f=>a.acceptNodeIfVisibleInRange(f)});return i.currentNode=e,i},et=e=>{const t=a.makeNewSegmenter(e.startContainer.ownerDocument??void 0);if(t){const s=p(e);s!==e.startContainer&&e.setStartBefore(s),v(t,!1,e)}else{const s=M(e.startContainer,e.startOffset);if(s!==-1){e.setStart(e.startContainer,s);return}if(N(e.startContainer)&&e.startOffset===0)return;const r=g(e.startContainer);if(!r)return;const n=new Set;let i=a.backwardTraverse(r,n);for(;i!=null;){const f=M(i);if(f!==-1){e.setStart(i,f);return}if(N(i)){i.contains?.(e.startContainer)?e.setStart(i,0):e.setStartAfter(i);return}i=a.backwardTraverse(r,n),e.collapse()}}},st=e=>{const t=$(e);if(t==null){e.collapse();return}p(e)!==t&&e.setStart(t,0);const r=_(e),n=J(e);r!==n&&e.setEnd(n,(n.textContent??"").length)},v=(e,t,s)=>{const r=t?{node:s.endContainer,offset:s.endOffset}:{node:s.startContainer,offset:s.startOffset},n=rt(r.node);if(!n)return;const i=n.preNodes.reduce((S,u)=>S.concat(u.textContent??""),""),f=n.innerNodes.reduce((S,u)=>S.concat(u.textContent??""),"");let l=i.length;r.node.nodeType===Node.TEXT_NODE?l+=r.offset:t&&(l+=f.length);const O=n.postNodes.reduce((S,u)=>S.concat(u.textContent??""),""),c=[...n.preNodes,...n.innerNodes,...n.postNodes];if(c.length==0)return;const T=i.concat(f,O),o=e.segment(T).containing(l);if(!o){t?s.setEndAfter(c[c.length-1]):s.setEndBefore(c[0]);return}if(!o.isWordLike||l===o.index||l===o.index+o.segment.length)return;const E=t?o.index+o.segment.length:o.index;let m=0;for(const S of c){const u=(S.textContent??"").length;if(m<=E&&E<m+u){const w=E-m;t?w>=u?s.setEndAfter(S):s.setEnd(S,w):w>=u?s.setStartAfter(S):s.setStart(S,w);return}m+=u}t?s.setEndAfter(c[c.length-1]):s.setStartBefore(c[0])},rt=e=>{const t=[],s=g(e);if(!s)return;const r=new Set;let n=a.backwardTraverse(s,r);for(;n!=null&&!N(n);)d(),n.nodeType===Node.TEXT_NODE&&t.push(n),n=a.backwardTraverse(s,r);t.reverse();const i=[];if(e.nodeType===Node.TEXT_NODE)i.push(e);else{const h=(e.ownerDocument??e).createTreeWalker(e,NodeFilter.SHOW_ELEMENT|NodeFilter.SHOW_TEXT,{acceptNode:E=>a.acceptNodeIfVisibleInRange(E)});h.currentNode=e;let o=h.nextNode();for(;o!=null;)d(),o.nodeType===Node.TEXT_NODE&&i.push(o),o=h.nextNode()}const f=[],l=g(e);if(!l)return;const O=new Set([e]);let c=a.forwardTraverse(l,O);for(;c!=null&&!N(c);)d(),c.nodeType===Node.TEXT_NODE&&f.push(c),c=a.forwardTraverse(l,O);return{preNodes:t,innerNodes:i,postNodes:f}},nt=e=>{const t=a.makeNewSegmenter(e.endContainer.ownerDocument??void 0);if(t){const s=_(e);s!==e.endContainer&&e.setEndAfter(s),v(t,!0,e)}else{let s=e.endOffset,r=e.endContainer;r.nodeType===Node.ELEMENT_NODE&&e.endOffset<r.childNodes.length&&(r=r.childNodes[e.endOffset]);const n=g(r);if(!n)return;const i=new Set([r]);for(;r!=null;){d();const f=tt(r,s);if(s=null,f!==-1){e.setEnd(r,f);return}if(N(r)){r.contains?.(e.endContainer)?e.setEnd(r,r.childNodes.length):e.setEndBefore(r);return}r=a.forwardTraverse(n,i)}e.collapse()}},N=e=>e.nodeType===Node.ELEMENT_NODE&&(a.BLOCK_ELEMENTS.includes(e.tagName.toUpperCase())||e.tagName.toUpperCase()==="HTML"||e.tagName.toUpperCase()==="BODY"),D=e=>e.nodeType===Node.TEXT_NODE;export{x as GenerateFragmentStatus,at as generateFragment,ot as generateFragmentFromRange,ct as isValidRangeForFragmentGeneration,ft as setFragmentGenerationTimeout};

package/dist/vendor/text-fragments-polyfill/textFragmentMatcher.js

@@ -0,0 +1 @@
+const O=["ADDRESS","ARTICLE","ASIDE","BLOCKQUOTE","BR","DETAILS","DIALOG","DD","DIV","DL","DT","FIELDSET","FIGCAPTION","FIGURE","FOOTER","FORM","H1","H2","H3","H4","H5","H6","HEADER","HGROUP","HR","LI","MAIN","NAV","OL","P","PRE","SECTION","TABLE","UL","TR","TH","TD","COLGROUP","COL","CAPTION","THEAD","TBODY","TFOOT"],f=/[\t-\r -#%-\*,-\/:;\?@\[-\]_\{\}\x85\xA0\xA1\xA7\xAB\xB6\xB7\xBB\xBF\u037E\u0387\u055A-\u055F\u0589\u058A\u05BE\u05C0\u05C3\u05C6\u05F3\u05F4\u0609\u060A\u060C\u060D\u061B\u061E\u061F\u066A-\u066D\u06D4\u0700-\u070D\u07F7-\u07F9\u0830-\u083E\u085E\u0964\u0965\u0970\u0AF0\u0DF4\u0E4F\u0E5A\u0E5B\u0F04-\u0F12\u0F14\u0F3A-\u0F3D\u0F85\u0FD0-\u0FD4\u0FD9\u0FDA\u104A-\u104F\u10FB\u1360-\u1368\u1400\u166D\u166E\u1680\u169B\u169C\u16EB-\u16ED\u1735\u1736\u17D4-\u17D6\u17D8-\u17DA\u1800-\u180A\u1944\u1945\u1A1E\u1A1F\u1AA0-\u1AA6\u1AA8-\u1AAD\u1B5A-\u1B60\u1BFC-\u1BFF\u1C3B-\u1C3F\u1C7E\u1C7F\u1CC0-\u1CC7\u1CD3\u2000-\u200A\u2010-\u2029\u202F-\u2043\u2045-\u2051\u2053-\u205F\u207D\u207E\u208D\u208E\u2308-\u230B\u2329\u232A\u2768-\u2775\u27C5\u27C6\u27E6-\u27EF\u2983-\u2998\u29D8-\u29DB\u29FC\u29FD\u2CF9-\u2CFC\u2CFE\u2CFF\u2D70\u2E00-\u2E2E\u2E30-\u2E44\u3000-\u3003\u3008-\u3011\u3014-\u301F\u3030\u303D\u30A0\u30FB\uA4FE\uA4FF\uA60D-\uA60F\uA673\uA67E\uA6F2-\uA6F7\uA874-\uA877\uA8CE\uA8CF\uA8F8-\uA8FA\uA8FC\uA92E\uA92F\uA95F\uA9C1-\uA9CD\uA9DE\uA9DF\uAA5C-\uAA5F\uAADE\uAADF\uAAF0\uAAF1\uABEB\uFD3E\uFD3F\uFE10-\uFE19\uFE30-\uFE52\uFE54-\uFE61\uFE63\uFE68\uFE6A\uFE6B\uFF01-\uFF03\uFF05-\uFF0A\uFF0C-\uFF0F\uFF1A\uFF1B\uFF1F\uFF20\uFF3B-\uFF3D\uFF3F\uFF5B\uFF5D\uFF5F-\uFF65]|\uD800[\uDD00-\uDD02\uDF9F\uDFD0]|\uD801\uDD6F|\uD802[\uDC57\uDD1F\uDD3F\uDE50-\uDE58\uDE7F\uDEF0-\uDEF6\uDF39-\uDF3F\uDF99-\uDF9C]|\uD804[\uDC47-\uDC4D\uDCBB\uDCBC\uDCBE-\uDCC1\uDD40-\uDD43\uDD74\uDD75\uDDC5-\uDDC9\uDDCD\uDDDB\uDDDD-\uDDDF\uDE38-\uDE3D\uDEA9]|\uD805[\uDC4B-\uDC4F\uDC5B\uDC5D\uDCC6\uDDC1-\uDDD7\uDE41-\uDE43\uDE60-\uDE6C\uDF3C-\uDF3E]|\uD807[\uDC41-\uDC45\uDC70\uDC71]|\uD809[\uDC70-\uDC74]|\uD81A[\uDE6E\uDE6F\uDEF5\uDF37-\uDF3B\uDF44]|\uD82F\uDC9F|\uD836[\uDE87-\uDE8B]|\uD83A[\uDD5E\uDD5F]/u,b=/[^\t-\r -#%-\*,-\/:;\?@\[-\]_\{\}\x85\xA0\xA1\xA7\xAB\xB6\xB7\xBB\xBF\u037E\u0387\u055A-\u055F\u0589\u058A\u05BE\u05C0\u05C3\u05C6\u05F3\u05F4\u0609\u060A\u060C\u060D\u061B\u061E\u061F\u066A-\u066D\u06D4\u0700-\u070D\u07F7-\u07F9\u0830-\u083E\u085E\u0964\u0965\u0970\u0AF0\u0DF4\u0E4F\u0E5A\u0E5B\u0F04-\u0F12\u0F14\u0F3A-\u0F3D\u0F85\u0FD0-\u0FD4\u0FD9\u0FDA\u104A-\u104F\u10FB\u1360-\u1368\u1400\u166D\u166E\u1680\u169B\u169C\u16EB-\u16ED\u1735\u1736\u17D4-\u17D6\u17D8-\u17DA\u1800-\u180A\u1944\u1945\u1A1E\u1A1F\u1AA0-\u1AA6\u1AA8-\u1AAD\u1B5A-\u1B60\u1BFC-\u1BFF\u1C3B-\u1C3F\u1C7E\u1C7F\u1CC0-\u1CC7\u1CD3\u2000-\u200A\u2010-\u2029\u202F-\u2043\u2045-\u2051\u2053-\u205F\u207D\u207E\u208D\u208E\u2308-\u230B\u2329\u232A\u2768-\u2775\u27C5\u27C6\u27E6-\u27EF\u2983-\u2998\u29D8-\u29DB\u29FC\u29FD\u2CF9-\u2CFC\u2CFE\u2CFF\u2D70\u2E00-\u2E2E\u2E30-\u2E44\u3000-\u3003\u3008-\u3011\u3014-\u301F\u3030\u303D\u30A0\u30FB\uA4FE\uA4FF\uA60D-\uA60F\uA673\uA67E\uA6F2-\uA6F7\uA874-\uA877\uA8CE\uA8CF\uA8F8-\uA8FA\uA8FC\uA92E\uA92F\uA95F\uA9C1-\uA9CD\uA9DE\uA9DF\uAA5C-\uAA5F\uAADE\uAADF\uAAF0\uAAF1\uABEB\uFD3E\uFD3F\uFE10-\uFE19\uFE30-\uFE52\uFE54-\uFE61\uFE63\uFE68\uFE6A\uFE6B\uFF01-\uFF03\uFF05-\uFF0A\uFF0C-\uFF0F\uFF1A\uFF1B\uFF1F\uFF20\uFF3B-\uFF3D\uFF3F\uFF5B\uFF5D\uFF5F-\uFF65]|\uD800[\uDD00-\uDD02\uDF9F\uDFD0]|\uD801\uDD6F|\uD802[\uDC57\uDD1F\uDD3F\uDE50-\uDE58\uDE7F\uDEF0-\uDEF6\uDF39-\uDF3F\uDF99-\uDF9C]|\uD804[\uDC47-\uDC4D\uDCBB\uDCBC\uDCBE-\uDCC1\uDD40-\uDD43\uDD74\uDD75\uDDC5-\uDDC9\uDDCD\uDDDB\uDDDD-\uDDDF\uDE38-\uDE3D\uDEA9]|\uD805[\uDC4B-\uDC4F\uDC5B\uDC5D\uDCC6\uDDC1-\uDDD7\uDE41-\uDE43\uDE60-\uDE6C\uDF3C-\uDF3E]|\uD807[\uDC41-\uDC45\uDC70\uDC71]|\uD809[\uDC70-\uDC74]|\uD81A[\uDE6E\uDE6F\uDEF5\uDF37-\uDF3B\uDF44]|\uD82F\uDC9F|\uD836[\uDE87-\uDE8B]|\uD83A[\uDD5E\uDD5F]/u,U=(u,e,t)=>{const n=[],D=e.createRange();for(D.selectNodeContents(t??e);!D.collapsed&&n.length<2;){let F;if(u.prefix){const r=a(u.prefix,D);if(r==null)break;c(D,r.startContainer,r.startOffset);const i=e.createRange();if(i.setStart(r.endContainer,r.endOffset),i.setEnd(D.endContainer,D.endOffset),B(i),i.collapsed||(F=a(u.textStart,i),F==null))break;if(F.compareBoundaryPoints(Range.START_TO_START,i)!==0)continue}else{if(F=a(u.textStart,D),F==null)break;c(D,F.startContainer,F.startOffset)}if(u.textEnd){const r=e.createRange();r.setStart(F.endContainer,F.endOffset),r.setEnd(D.endContainer,D.endOffset);let i=!1;for(;!r.collapsed&&n.length<2;){const s=a(u.textEnd,r);if(s==null)break;if(c(r,s.startContainer,s.startOffset),F.setEnd(s.endContainer,s.endOffset),u.suffix){const o=R(u.suffix,F,D,e);if(o===E.NO_SUFFIX_MATCH)break;if(o===E.SUFFIX_MATCH){i=!0,n.push(F.cloneRange());continue}else if(o===E.MISPLACED_SUFFIX)continue}else i=!0,n.push(F.cloneRange())}if(!i)break}else if(u.suffix){const r=R(u.suffix,F,D,e);if(r===E.NO_SUFFIX_MATCH)break;if(r===E.SUFFIX_MATCH){n.push(F.cloneRange()),c(D,D.startContainer,D.startOffset);continue}else if(r===E.MISPLACED_SUFFIX)continue}else n.push(F.cloneRange())}return n},E={NO_SUFFIX_MATCH:0,SUFFIX_MATCH:1,MISPLACED_SUFFIX:2},R=(u,e,t,n)=>{const D=n.createRange();D.setStart(e.endContainer,e.endOffset),D.setEnd(t.endContainer,t.endOffset),B(D);const F=a(u,D);return F==null?E.NO_SUFFIX_MATCH:F.compareBoundaryPoints(Range.START_TO_START,D)!==0?E.MISPLACED_SUFFIX:E.SUFFIX_MATCH},c=(u,e,t)=>{try{u.setStart(e,t+1)}catch{u.setStartAfter(e)}},B=u=>{const e=g(u);let t=e.nextNode();for(;!u.collapsed&&t!=null;){if(t!==u.startContainer&&u.setStart(t,0),t.textContent.length>u.startOffset&&!t.textContent[u.startOffset].match(/\s/))return;try{u.setStart(t,u.startOffset+1)}catch{t=e.nextNode(),t==null?u.collapse():u.setStart(t,0)}}},g=u=>(u.commonAncestorContainer.ownerDocument??u.commonAncestorContainer).createTreeWalker(u.commonAncestorContainer,NodeFilter.SHOW_TEXT|NodeFilter.SHOW_ELEMENT,{acceptNode:t=>N(t,u)}),H=u=>{if(u.hidden==="until-found")return!0;const e=u.attributes;return!!(e&&e.hidden&&e.hidden.value==="until-found")},T=u=>{let e=u;for(;e!=null&&!(e instanceof HTMLElement);)e=e.parentNode;const t=e?.ownerDocument?.defaultView;if(e!=null&&t!=null){if(H(e))return!0;const n=t.getComputedStyle(e);if(n.visibility==="hidden"||n.display==="none"||parseInt(n.height,10)===0&&n.overflowY!="visible"||parseInt(n.width,10)===0&&n.overflowX!="visible"||parseInt(n.opacity,10)===0)return!1}return!0},I=(u,e)=>e!=null&&!e.intersectsNode(u)?NodeFilter.FILTER_REJECT:T(u)?NodeFilter.FILTER_ACCEPT:NodeFilter.FILTER_REJECT,N=(u,e)=>e!=null&&!e.intersectsNode(u)||!T(u)?NodeFilter.FILTER_REJECT:u.nodeType===Node.TEXT_NODE?NodeFilter.FILTER_ACCEPT:NodeFilter.FILTER_SKIP,p=(u,e)=>{const t=[];let n=[];const D=Array.from(M(u,F=>I(F,e)));for(const F of D)F.nodeType===Node.TEXT_NODE?n.push(F):F instanceof HTMLElement&&O.includes(F.tagName.toUpperCase())&&n.length>0&&(t.push(n),n=[]);return n.length>0&&t.push(n),t},v=(u,e,t)=>{let n="";return u.length===1?n=u[0].textContent.substring(e,t):n=u[0].textContent.substring(e)+u.slice(1,-1).reduce((D,F)=>D+F.textContent,"")+u.slice(-1)[0].textContent.substring(0,t),n.replace(/[\t\n\r ]+/g," ")};function*M(u,e){const n=(u.ownerDocument??u).createTreeWalker(u,NodeFilter.SHOW_ELEMENT|NodeFilter.SHOW_TEXT,{acceptNode:e}),D=new Set;for(;h(n,D)!==null;)yield n.currentNode}const a=(u,e)=>{const t=p(e.commonAncestorContainer,e),n=S(e.commonAncestorContainer.ownerDocument??void 0);for(const D of t){const F=_(u,e,D,n);if(F!==void 0)return F}},_=(u,e,t,n)=>{if(!u||!e||!(t||[]).length)return;const D=t[0]===e.startContainer?e.startOffset:0,F=A(v(t,D,void 0)),r=A(u);let i=0,s,o;for(;i<F.length;){const C=F.indexOf(r,i);if(C===-1)return;if(m(F,C,r.length,n)){const l=A(t[0].data.slice(0,D)).length;s=d(l+C,t,!1),o=d(l+C+r.length,t,!0)}if(s!=null&&o!=null){const l=new Range;if(l.setStart(s.node,s.offset),l.setEnd(o.node,o.offset),e.compareBoundaryPoints(Range.START_TO_START,l)<=0&&e.compareBoundaryPoints(Range.END_TO_END,l)>=0)return l}i=C+1}},d=(u,e,t)=>{let n=0,D;for(let F=0;F<e.length;F++){const r=e[F];D||(D=A(r.data));let i=n+D.length;if(t&&(i+=1),i>u){const s=u-n;let o=Math.min(u-n,r.data.length);const C=t?D.substring(0,s):D.substring(s);let l=A(t?r.data.substring(0,o):r.data.substring(o));const L=(t?-1:1)*(C.length>l.length?-1:1);for(;o>=0&&o<=r.data.length;){if(l.length===C.length)return{node:r,offset:o};o+=L,l=A(t?r.data.substring(0,o):r.data.substring(o))}}if(n+=D.length,F+1<e.length){const s=A(e[F+1].data);D.slice(-1)===" "&&s.slice(0,1)===" "&&(n-=1),D=s}}},m=(u,e,t,n)=>{if(e<0||e>=u.length||t<=0||e+t>u.length)return!1;if(n){const D=n.segment(u),F=D.containing(e);if(!F||F.isWordLike&&F.index!=e)return!1;const r=e+t,i=D.containing(r);if(i&&i.isWordLike&&i.index!=r)return!1}else if(u[e].match(f)&&(++e,--t,!t)||u[e+t-1].match(f)&&(--t,!t)||e!==0&&!u[e-1].match(f)||e+t!==u.length&&!u[e+t].match(f))return!1;return!0},A=u=>(u||"").normalize("NFKD").replace(/\s+/g," ").replace(/[\u0300-\u036f]/g,"").toLowerCase(),S=u=>{if(Intl.Segmenter){const e=u?.documentElement?.lang||u?.defaultView?.navigator?.language||void 0;return new Intl.Segmenter(e,{granularity:"word"})}},h=(u,e)=>{if(!e.has(u.currentNode)){const D=u.firstChild();if(D!==null)return D}const t=u.nextSibling();if(t!==null)return t;const n=u.parentNode();return n!==null&&e.add(n),n},x=(u,e)=>{if(!e.has(u.currentNode)){const D=u.lastChild();if(D!==null)return D}const t=u.previousSibling();if(t!==null)return t;const n=u.parentNode();return n!==null&&e.add(n),n},w={advanceRangeStartPastOffset:c,advanceRangeStartToNonWhitespace:B,findRangeFromNodeList:_,findTextInRange:a,getBoundaryPointAtIndex:d,isWordBounded:m,makeNewSegmenter:S,normalizeString:A,forwardTraverse:h,backwardTraverse:x,getAllTextNodes:p,acceptTextNodeIfVisibleInRange:N},y={BLOCK_ELEMENTS:O,BOUNDARY_CHARS:f,NON_BOUNDARY_CHARS:b,acceptNodeIfVisibleInRange:I,normalizeString:A,makeNewSegmenter:S,forwardTraverse:h,backwardTraverse:x,makeTextNodeWalker:g,isNodeVisible:T};export{w as forTesting,y as internal,U as processTextFragmentDirective};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/helpers",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "General-purpose browser helpers for Readium packages",
   "author": "readium",
@@ -31,10 +31,6 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "clean": "rimraf types dist",
-    "build": "pnpm clean && tsc && vite build"
-  },
   "dependencies": {
     "user-agent-data-types": "^0.4.2"
   },
@@ -43,5 +39,9 @@
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "vite": "^7.3.1"
+  },
+  "scripts": {
+    "clean": "rimraf types dist",
+    "build": "pnpm clean && tsc && vite build"
   }
-}
+}

package/src/index.ts

@@ -1,2 +1,5 @@
 export * from "./color.ts";
 export * from "./sML.ts";
+export * from "./textFragmentDirective.ts";
+export * from "./vendor/text-fragments-polyfill/textFragmentMatcher.ts";
+export * from "./vendor/text-fragments-polyfill/textFragmentGenerator.ts";

package/src/textFragmentDirective.ts

@@ -0,0 +1,44 @@
+// Parses a WICG Text Fragment directive string:
+// text=[prefix-,]textStart[,textEnd][,-suffix]
+// https://wicg.github.io/scroll-to-text-fragment/
+
+const TEXT_DIRECTIVE_MARK = ":~:text=";
+
+export interface TextFragmentDirective {
+  textStart: string;
+  textEnd?: string;
+  prefix?: string;
+  suffix?: string;
+}
+
+// Locates ":~:text=" anywhere in the input — it's a suffix appended onto
+// whatever fragment (e.g. an element id) already precedes it, never the
+// whole string.
+export function decodeTextFragmentDirective(textref: string | undefined): TextFragmentDirective | undefined {
+  if (!textref) return undefined;
+  const markIndex = textref.indexOf(TEXT_DIRECTIVE_MARK);
+  if (markIndex === -1) return undefined;
+  const raw = textref.slice(markIndex + TEXT_DIRECTIVE_MARK.length).split("&")[0];
+  if (!raw) return undefined;
+
+  try {
+    let parts = raw.split(",");
+    const result: TextFragmentDirective = { textStart: "" };
+
+    if (parts.length > 1 && parts[0]!.endsWith("-")) {
+      result.prefix = decodeURIComponent(parts[0]!.slice(0, -1));
+      parts = parts.slice(1);
+    }
+    if (parts.length > 1 && parts[parts.length - 1]!.startsWith("-")) {
+      result.suffix = decodeURIComponent(parts[parts.length - 1]!.slice(1));
+      parts = parts.slice(0, -1);
+    }
+    if (parts.length === 0 || parts[0] === "") return undefined;
+
+    result.textStart = decodeURIComponent(parts[0]!);
+    if (parts.length > 1) result.textEnd = decodeURIComponent(parts[1]!);
+    return result;
+  } catch {
+    return undefined;
+  }
+}

package/src/vendor/text-fragments-polyfill/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/src/vendor/text-fragments-polyfill/README.MD

@@ -0,0 +1,8 @@
+The code in this module has been ported from `text-fragments-polyfill@6.7.0` (https://github.com/GoogleChromeLabs/text-fragments-polyfill/tree/v6.7.0/src), released under the Apache License, Version 2.0.
+
+Two files, both converted from JSDoc-typed JavaScript to TypeScript:
+
+- `textFragmentMatcher.ts` (from `text-fragment-utils.js`): resolves a WICG text-fragment directive to `Range`s in a document (`processTextFragmentDirective`). Dropped only the live CSS highlighting/marking exports (not resolution-related) and the closure-compiler/`goog` module-id interop block, which is dead code in this build. The `internal`/`forTesting` export bundles are kept intact, since `textFragmentGenerator.ts` depends on `internal` directly.
+- `textFragmentGenerator.ts` (from `fragment-generation-utils.js`): the inverse direction — generates a WICG text-fragment directive from a `Range` (`generateFragmentFromRange`), verifying uniqueness by calling back into `textFragmentMatcher.ts`'s `processTextFragmentDirective`/`internal`. Dropped only its own `forTesting` bundle (test-only, per its own upstream comment) and the same `goog` interop block. Renamed its `setTimeout` export to `setFragmentGenerationTimeout` to avoid shadowing the global `setTimeout`.
+
+Both files are kept together deliberately: generation is not independent of matching — it calls directly into matching's internals to verify a candidate directive resolves unambiguously before returning it. Splitting them across packages would mean either duplicating matching's internals elsewhere or generation depending on an incomplete/trimmed copy of it.