@ev-ry/fx 0.1.0-rc.1 → 0.1.0-rc.2

package/docs/RELEASE-NOTES.md

@@ -1,40 +1,52 @@
-# EV-RY FX Free 0.1.0-rc.1
-
-Public preview release candidate from EV-RY. The Free edition uses the [MIT license](../LICENSE). Package: `@ev-ry/fx`. Try the [live demo](https://kbaghini.github.io/evry-fx/docs/) or browse the [source and examples](https://github.com/kbaghini/evry-fx).
-
-The product is now EV-RY FX. Existing `THDFree`, `data-thd-*`, `createFree`, `loadFree` and `src/dom-*` names remain compatible. No behavior or API rename is implied by the branding change.
-
-## Included
-
-- Automatic intersection reveal for headings, marked display text and marked images.
-- Manual text, image and supported static SVG attachment, plus simple image swaps.
-- Four fixed presets: dust wind / smoke for text, drifting snow / melt for media. Textured triangular particles, a 2000ms timeline and native resting presentation.
-- Classic script loading, explicit `loadFree()` ES-module initialization, TypeScript declarations and integration examples.
-- Document-connected shared canvas with conservative local routing for special layouts.
-
-## Reliability work
-
-- Early opt-in masking prevents native content flashing before initial reveal, while preserving layout and providing failure recovery.
-- Wrapped headings and ordinary HTML whitespace use browser-measured placement. Initially empty or recoverable unsupported text can resume after valid content/layout and refresh.
-- Reentry during an unfinished reveal preserves its clock. Completed once-only entries are not restarted by minor scrolling or presentation updates.
-- Unsupported content returns to native rendering instead of repeatedly retrying known failures. Repeated local refresh preserves valid attachments.
-- Font loading invalidates shared pixels and refreshes rich-text meshes even when the CSS font name and line metrics stay unchanged.
-- Automatic loader ownership handles browser back/forward-cache returns; manual owners retain explicit lifecycle responsibility.
-- `FreeSurface.cancel()` is required in the declarations, matching the runtime API. The module loader has its own typed export.
-
-## Performance work
-
-- Validated, unchanged text reuses its layout before the expensive per-character placement pass. Character-frame data is collected only when the selected entry/exit effect needs it.
-- Display-text raster pixels use a document-scoped cache capped at 16MiB. This is a cache limit, not total page or GPU memory.
-- Offscreen images prepare near the viewport. Internal image preparation avoids an intermediate PNG encode/decode, and rapid resize requests are coalesced.
-- Geometry settings, visual quality, preset choices and effect duration are preserved. These changes remove redundant work; they do not promise a universal FPS improvement or eliminate all cold WebGL startup cost.
-
-## Validation and limits
-
-Chrome desktop regression checks cover actual entry/exit motion, rapid reentry, plain/rich text rebuilding, whitespace and Persian mixed-text cases, fallback recovery, lifecycle cleanup and cache invalidation. Strict TypeScript consumer checks cover source and packaged declarations, cancellation, module-loader exports and rejected Free-only configuration.
-
-Earlier document-canvas scrolling tests on physical iPhone and Android devices were reported successful by the user. That is not fresh physical-device acceptance of every optimization in this candidate, nor a guarantee for all browsers, GPUs or websites.
-
-The Free build retains native fallback for unsupported content. Complete CSS stacking/clipping reproduction, arbitrary SVG, editable controls, custom effect recipes and dedicated framework component packs are outside this release. Cross-origin media must satisfy browser canvas restrictions. Review the [guide](GUIDE.md) before integration.
-
-[Back to the overview](../README.md)
+# EV-RY FX Free 0.1.0-rc.2
+
+- Fix collapsed whitespace at wrapped line ends triggering native fallback, including Android headings with negative letter spacing.
+- Respect DOM font kerning and text-rendering settings; include them in cache identity and invalidation.
+- Normalize high-resolution raster advances using the actual display font size. Physical iOS width parity remains to be confirmed.
+- Smooth native-rest handoff: native text fades in over 350ms starting 175ms before entry ends; the mesh fades out over the following 350ms. Reduced motion skips this transition.
+- Tie the handoff to the original effect clock to avoid restarting on delayed frames.
+
+No Free API removal or effect expansion. The marketing site's SPA router, loader and staged headlines are site behavior, not package exports.
+
+## Previous release
+
+# EV-RY FX Free 0.1.0-rc.1
+
+Public preview release candidate from EV-RY. The Free edition uses the [MIT license](../LICENSE). Package: `@ev-ry/fx`. Try the [live demo](https://kbaghini.github.io/evry-fx/docs/) or browse the [source and examples](https://github.com/kbaghini/evry-fx).
+
+The product is now EV-RY FX. Existing `THDFree`, `data-thd-*`, `createFree`, `loadFree` and `src/dom-*` names remain compatible. No behavior or API rename is implied by the branding change.
+
+## Included
+
+- Automatic intersection reveal for headings, marked display text and marked images.
+- Manual text, image and supported static SVG attachment, plus simple image swaps.
+- Four fixed presets: dust wind / smoke for text, drifting snow / melt for media. Textured triangular particles, a 2000ms timeline and native resting presentation.
+- Classic script loading, explicit `loadFree()` ES-module initialization, TypeScript declarations and integration examples.
+- Document-connected shared canvas with conservative local routing for special layouts.
+
+## Reliability work
+
+- Early opt-in masking prevents native content flashing before initial reveal, while preserving layout and providing failure recovery.
+- Wrapped headings and ordinary HTML whitespace use browser-measured placement. Initially empty or recoverable unsupported text can resume after valid content/layout and refresh.
+- Reentry during an unfinished reveal preserves its clock. Completed once-only entries are not restarted by minor scrolling or presentation updates.
+- Unsupported content returns to native rendering instead of repeatedly retrying known failures. Repeated local refresh preserves valid attachments.
+- Font loading invalidates shared pixels and refreshes rich-text meshes even when the CSS font name and line metrics stay unchanged.
+- Automatic loader ownership handles browser back/forward-cache returns; manual owners retain explicit lifecycle responsibility.
+- `FreeSurface.cancel()` is required in the declarations, matching the runtime API. The module loader has its own typed export.
+
+## Performance work
+
+- Validated, unchanged text reuses its layout before the expensive per-character placement pass. Character-frame data is collected only when the selected entry/exit effect needs it.
+- Display-text raster pixels use a document-scoped cache capped at 16MiB. This is a cache limit, not total page or GPU memory.
+- Offscreen images prepare near the viewport. Internal image preparation avoids an intermediate PNG encode/decode, and rapid resize requests are coalesced.
+- Geometry settings, visual quality, preset choices and effect duration are preserved. These changes remove redundant work; they do not promise a universal FPS improvement or eliminate all cold WebGL startup cost.
+
+## Validation and limits
+
+Chrome desktop regression checks cover actual entry/exit motion, rapid reentry, plain/rich text rebuilding, whitespace and Persian mixed-text cases, fallback recovery, lifecycle cleanup and cache invalidation. Strict TypeScript consumer checks cover source and packaged declarations, cancellation, module-loader exports and rejected Free-only configuration.
+
+Earlier document-canvas scrolling tests on physical iPhone and Android devices were reported successful by the user. That is not fresh physical-device acceptance of every optimization in this candidate, nor a guarantee for all browsers, GPUs or websites.
+
+The Free build retains native fallback for unsupported content. Complete CSS stacking/clipping reproduction, arbitrary SVG, editable controls, custom effect recipes and dedicated framework component packs are outside this release. Cross-origin media must satisfy browser canvas restrictions. Review the [guide](GUIDE.md) before integration.
+
+[Back to the overview](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ev-ry/fx",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "private": false,
   "type": "module",
   "exports": {

package/src/dom-image-raster.js

@@ -13,6 +13,20 @@ export async function rasterizeDOMImage(element,{maxSide=2048}={}){
     return {x:read(parts[0],box.width),y:read(parts[1]??parts[0],box.height)};
   });
   context.beginPath();context.roundRect(0,0,box.width,box.height,radii);context.clip();
+  // Bake ancestor overflow masks into the texture; moving particles keep the
+  // final image silhouette rather than snapping to a rounded frame at rest.
+  for(let parent=element.parentElement;parent;parent=parent.parentElement){
+    const style=doc.defaultView.getComputedStyle(parent);
+    if(!['hidden','clip','auto','scroll'].includes(style.overflowX)||!['hidden','clip','auto','scroll'].includes(style.overflowY))continue;
+    const rect=parent.getBoundingClientRect();
+    if(style.transform!=='none')continue;
+    const left=parseFloat(style.borderLeftWidth)||0,top=parseFloat(style.borderTopWidth)||0;
+    const right=parseFloat(style.borderRightWidth)||0,bottom=parseFloat(style.borderBottomWidth)||0;
+    const corners=['borderTopLeftRadius','borderTopRightRadius','borderBottomRightRadius','borderBottomLeftRadius'];
+    const borders=[[left,top],[right,top],[right,bottom],[left,bottom]];
+    const clipRadii=corners.map((key,i)=>{const parts=style[key].split(/\s+/);const read=(s,n)=>parseFloat(s)*(s.endsWith('%')?n/100:1);return {x:Math.max(0,read(parts[0],rect.width)-borders[i][0]),y:Math.max(0,read(parts[1]??parts[0],rect.height)-borders[i][1])};});
+    context.beginPath();context.roundRect(rect.left-box.left+left,rect.top-box.top+top,Math.max(0,rect.width-left-right),Math.max(0,rect.height-top-bottom),clipRadii);context.clip();
+  }
   const factor=css.objectFit==='cover'?Math.max(box.width/element.naturalWidth,box.height/element.naturalHeight):Math.min(box.width/element.naturalWidth,box.height/element.naturalHeight);
   const w=css.objectFit==='fill'?box.width:element.naturalWidth*factor,h=css.objectFit==='fill'?box.height:element.naturalHeight*factor;
   context.drawImage(element,(box.width-w)/2,(box.height-h)/2,w,h);

package/src/dom-rich-text.js

@@ -1,119 +1,136 @@
-import {HybridTextFlowEngine} from './hybrid-text-flow.js';
-import {SharedTextScene} from './text-scene.js';
-import {TextEditEffect} from './text-edit-effect.js';
-import {adoptDOMFont,domFontAtSize} from './dom-surface-font.js';
-import {groupDOMTextNodes,setRunRange,prepareFontBoundaries} from './dom-text-runs.js';
-
-// One scene, independent styled text runs. DOM Range supplies line placement;
-// the browser remains responsible for wrapping, links and label semantics.
-export class DOMRichText {
-  constructor(element,THREE,content,canvas,options){Object.assign(this,{element,THREE,content,canvas,options});this.runs=new Map();this.styles=new Map();this.disposed=false;}
-  restore(){for(const [node,values] of this.styles)for(const [name,[original,priority,owned]] of values)if(node.style.getPropertyValue(name)===owned){if(original)node.style.setProperty(name,original,priority);else node.style.removeProperty(name);}this.styles.clear();}
-  hide(){for(const run of this.runs.values())for(const text of run.nodes)for(const [name,value] of [['-webkit-text-fill-color','transparent'],['text-shadow','none']]){
-    const node=text.parentElement;let values=this.styles.get(node);if(!values){values=new Map();this.styles.set(node,values);}
-    if(!values.has(name))values.set(name,[node.style.getPropertyValue(name),node.style.getPropertyPriority(name),value]);
-    if(node.style.getPropertyValue(name)!==value)node.style.setProperty(name,value);
-  }}
-  cancel(){for(const r of this.runs.values())r.effect.cancel();}
-  drop(run){run.effect.dispose();run.view.dispose();run.engine.dispose();run.group.removeFromParent();}
-  dispose(){this.disposed=true;this.restore();for(const r of this.runs.values())this.drop(r);this.runs.clear();}
-  async prepare(cancelled,onRebuild=()=>{}){
-    const {element,canvas,THREE}=this,document=element.ownerDocument,window=document.defaultView;
-    if(element.isContentEditable||element.matches('input,textarea,select,img,svg'))return {reason:'Rich attachment is for display text only'};
-    const raw=[],walker=document.createTreeWalker(element,window.NodeFilter.SHOW_TEXT);
-    while(walker.nextNode()){const node=walker.currentNode;if(!canvas.contains(node)&&node.data.trim())raw.push(node);}
-    const nodes=groupDOMTextNodes(raw,document);
-    if([...element.querySelectorAll('input,textarea,select,img,svg,canvas,[contenteditable="true"]')].some(node=>node!==canvas&&!canvas.contains(node)))return {reason:'Rich text currently accepts text elements only'};
-    // Shaping across styled-node boundaries needs a shared shaping context.
-    if(!prepareFontBoundaries(nodes,document))return {reason:'Unsupported joining boundary uses native shaping'};
-    const box=element.getBoundingClientRect(),width=element.clientWidth||box.width,height=element.clientHeight||box.height;
-    if(!(width>0&&height>0))return {reason:'Text is not visible'};
-    const wanted=new Set(nodes.map(n=>n.first));for(const [node,run] of this.runs)if(!wanted.has(node)){this.restore();this.drop(run);this.runs.delete(node);}
-    const segmenter=new Intl.Segmenter(undefined,{granularity:'grapheme'});
-    for(const node of nodes){
-      if(cancelled()||this.disposed)return null;
-      const parent=node.parentElement,style=window.getComputedStyle(parent),size=parseFloat(style.fontSize);
-      const collapseWhitespace=['normal','nowrap'].includes(style.whiteSpace);
-      if(!(size>0)||style.writingMode!=='horizontal-tb'||style.textTransform!=='none'||style.textAlign==='justify'||node.data.includes('\t')&&!collapseWhitespace)return {reason:'Unsupported rich typography uses native text'};
-      for(let ancestor=parent;ancestor;ancestor=ancestor.parentElement){
-        const css=window.getComputedStyle(ancestor);
-        for(const pseudo of ['::before','::after']){const p=window.getComputedStyle(ancestor,pseudo);if(p.display!=='none'&&!['none','normal','""',"''"].includes(p.content))return {reason:'Generated content uses native text'};}
-        if(ancestor!==element&&(css.transform!=='none'||css.opacity!=='1'||css.overflowX!=='visible'||css.overflowY!=='visible'))return {reason:'Nested transformed, faded or clipped text uses native text'};
-        if(ancestor===element)break;
-      }
-      let run=this.runs.get(node.first);
-      if(!run){const group=new THREE.Group();this.content.add(group);const engine=new HybridTextFlowEngine({scale:.036,divisions:this.options.divisions??'auto',textRendering:'texture'});
-        run={node:node.first,group,engine,view:new SharedTextScene(THREE,engine,group),effect:new TextEditEffect(THREE,{mode:'dust-wind'}),key:null};this.runs.set(node.first,run);}
-      run.nodes=node.nodes;
-      const fontChanged=await adoptDOMFont(run.engine,parent);
-      // A newly loaded font can change glyph pixels without changing CSS names,
-      // advances or line boxes. Rebind the run to the refreshed raster source.
-      if(fontChanged)run.key=null;
-      if(cancelled()||this.disposed)return null;
-      const factor=size/200,context=run.engine.rasterizer.context;context.font=domFontAtSize(run.engine,size);context.direction=style.direction;
-      const spacing=[style.letterSpacing,style.wordSpacing].map(value=>value==='normal'?0:parseFloat(value));
-      if(spacing.some(value=>!Number.isFinite(value))||spacing.some((value,i)=>value!==0&&!(['letterSpacing','wordSpacing'][i] in context)))return {reason:'Canvas spacing unavailable; native text retained'};
-      const spacingKey=JSON.stringify(spacing.map(value=>value/factor));
-      if(run.spacingKey!==spacingKey){run.engine.clearMeshes();run.engine.rasterizer.cache.clear();run.key=null;run.spacingKey=spacingKey;}
-      run.engine.rasterizer.letterSpacing=spacing[0]/factor;run.engine.rasterizer.wordSpacing=spacing[1]/factor;
-      if('letterSpacing' in context)context.letterSpacing=`${spacing[0]}px`;
-      if('wordSpacing' in context)context.wordSpacing=`${spacing[1]}px`;
-      const metrics=context.measureText('Hgآی'),rows=[],characters=[];let row=null;
-      if(!Number.isFinite(metrics.fontBoundingBoxAscent))return {reason:'Native font metrics unavailable'};
-      for(const part of segmenter.segment(node.data)){
-        const range=document.createRange();setRunRange(range,node,part.index,part.index+part.segment.length);
-        const rect=range.getBoundingClientRect();if(!rect.width||!rect.height)continue;
-        const top=rect.top-box.top-element.clientTop;
-        if(!row||Math.abs(row.top-top)>.75){row={start:part.index,end:part.index,top,left:Infinity,right:-Infinity,direction:style.direction,baseline:top+(rect.height+metrics.fontBoundingBoxAscent-metrics.fontBoundingBoxDescent)/2};rows.push(row);}
-        row.end=part.index+part.segment.length;row.left=Math.min(row.left,rect.left-box.left-element.clientLeft);row.right=Math.max(row.right,rect.right-box.left-element.clientLeft);
-        const unit=run.engine.scale/factor;
-        characters.push({x:(rect.left-box.left-element.clientLeft)*unit,y:-(row.baseline+metrics.fontBoundingBoxDescent)*unit,width:rect.width*unit,height:(metrics.fontBoundingBoxAscent+metrics.fontBoundingBoxDescent)*unit,direction:style.direction});
-      }
-      for(const r of rows){
-        // Preserve original offsets for DOM Range/color mapping; normalize only
-        // the raster string when CSS collapses ASCII whitespace. NBSP and
-        // preformatted spacing are deliberately untouched.
-        let text=node.data.slice(r.start,r.end);
-        if(collapseWhitespace)text=text.replace(/[ \t\r\n\f]+/g,' ');
-        r.text=(r.start===0&&node.joinStart?'\u200d':'')+text+(r.end===node.data.length&&node.joinEnd?'\u200d':'');
-        const expected=context.measureText(r.text).width;if(Math.abs(expected-(r.right-r.left))>Math.max(1,expected*.015))return {reason:'Rich run shaping differs from DOM; native text retained'};
-      }
-      run.engine.rasterizer.configure();const layout={rows,factor};
-      const paints=node.nodes.map(text=>({text,color:window.getComputedStyle(text.parentElement).color}));
-      const multicolor=new Set(paints.map(p=>p.color)).size>1;
-      const key=JSON.stringify([node.data,size,run.engine.domFont.key,rows,paints.map(p=>p.color)]);
-      if(key!==run.key){onRebuild();run.effect.cancel();run.engine.setDisplayFontSize(size);await run.engine.prepareRows(layout,{cancelled});if(cancelled()||this.disposed)return null;
-        if(multicolor)for(let i=0;i<rows.length;i++){
-          const row=rows[i],entry=run.engine.flowLayout.entries[i],item=entry.metrics.items[0],glyph=item.glyph;
-          const spans=[];let offset=0;
-          for(const paint of paints){const start=Math.max(row.start,offset),end=Math.min(row.end,offset+paint.text.length);offset+=paint.text.length;if(end<=start)continue;
-            const range=document.createRange();setRunRange(range,node,start,end);
-            const color=new THREE.Color().setStyle(paint.color).convertLinearToSRGB();
-            for(const rect of range.getClientRects())if(Math.abs(rect.top-box.top-element.clientTop-row.top)<.75)spans.push({left:rect.left-box.left-element.clientLeft,right:rect.right-box.left-element.clientLeft,color});
-          }
-          const source=glyph.rasterSurface,rgba=new Uint8ClampedArray(source.rgba);
-          for(let x=0;x<source.width;x++){
-            const px=row.left+(x+.5-glyph.drawOffsetX)*factor;
-            let nearest=null,distance=Infinity;for(const span of spans){const d=Math.max(span.left-px,px-span.right,0);if(d<distance){distance=d;nearest=span;}}
-            if(nearest)for(let y=0;y<source.height;y++){const p=(y*source.width+x)*4;rgba[p]=Math.round(nearest.color.r*255);rgba[p+1]=Math.round(nearest.color.g*255);rgba[p+2]=Math.round(nearest.color.b*255);}
-          }
-          // A presentation-owned copy preserves the engine's reusable alpha raster.
-          item.glyph={...glyph,rasterSurface:{...source,rgba,mask:false}};
-        }
-        run.view.setText(node.data);run.key=key;}
-      run.group.scale.setScalar(factor/run.engine.scale);run.view.uniforms.tint.value.setStyle(multicolor?'white':style.color);run.size=size;run.characters=characters;
-    }
-    return {width,height,size:parseFloat(window.getComputedStyle(element).fontSize),factor:.036,text:nodes.map(n=>n.data).join(''),direction:window.getComputedStyle(element).direction,characters:[]};
-  }
-  play(phase,mode,settings,seed,now){for(const run of this.runs.values()){
-    run.effect.cancel();if(mode==='none')continue;
-    run.effect.setMode(phase==='exit'&&settings.exitEffect!=='same'?settings.exitEffect:mode);run.effect.configure(settings);
-    const b=run.view.bounds;run.effect.playRegion(run.view,{x:b.minX-.001,y:b.minY-.001,width:b.maxX-b.minX+.002,height:b.maxY-b.minY+.002,direction:run.engine.domFont?run.node.parentElement.ownerDocument.defaultView.getComputedStyle(run.node.parentElement).direction:'ltr'},200*run.engine.scale,now,{departing:phase==='exit',seed});
-    run.effect.prepareCharacterCenters(run.view,()=>run.characters);
-  }}
-  step(now,reduced){let active=false;for(const run of this.runs.values())active=run.effect.step(now,reduced)||active;return active;}
-  stats(){return {runs:this.runs.size,triangles:[...this.runs.values()].reduce((n,r)=>n+(r.view.triangleCount??0),0),active:[...this.runs.values()].some(r=>r.effect.active)};}
-}
+import {HybridTextFlowEngine} from './hybrid-text-flow.js';
+import {SharedTextScene} from './text-scene.js';
+import {TextEditEffect} from './text-edit-effect.js';
+import {adoptDOMFont,domFontAtSize} from './dom-surface-font.js';
+import {groupDOMTextNodes,setRunRange,prepareFontBoundaries} from './dom-text-runs.js';
+
+// One scene, independent styled text runs. DOM Range supplies line placement;
+// the browser remains responsible for wrapping, links and label semantics.
+export class DOMRichText {
+  constructor(element,THREE,content,canvas,options){Object.assign(this,{element,THREE,content,canvas,options});this.runs=new Map();this.styles=new Map();this.disposed=false;}
+  restore(){for(const [node,values] of this.styles)for(const [name,[original,priority,owned]] of values)if(node.style.getPropertyValue(name)===owned){if(original)node.style.setProperty(name,original,priority);else node.style.removeProperty(name);}this.styles.clear();}
+  hide(alpha=0){for(const run of this.runs.values())for(const text of run.nodes)for(const [name,value] of [['-webkit-text-fill-color',alpha>0?`color-mix(in srgb, ${text.parentElement.ownerDocument.defaultView.getComputedStyle(text.parentElement).color} ${alpha*100}%, transparent)`:'transparent'],['text-shadow','none']]){
+    const node=text.parentElement;let values=this.styles.get(node);if(!values){values=new Map();this.styles.set(node,values);}
+    if(!values.has(name))values.set(name,[node.style.getPropertyValue(name),node.style.getPropertyPriority(name),value]);
+    values.get(name)[2]=value;
+    if(node.style.getPropertyValue(name)!==value)node.style.setProperty(name,value);
+  }}
+  setPresentationOpacity(value){for(const run of this.runs.values())run.view.uniforms.presentationOpacity.value=value;}
+  cancel(){for(const r of this.runs.values())r.effect.cancel();}
+  drop(run){run.effect.dispose();run.view.dispose();run.engine.dispose();run.group.removeFromParent();}
+  dispose(){this.disposed=true;this.restore();for(const r of this.runs.values())this.drop(r);this.runs.clear();}
+  async prepare(cancelled,onRebuild=()=>{}){
+    const {element,canvas,THREE}=this,document=element.ownerDocument,window=document.defaultView;
+    if(element.isContentEditable||element.matches('input,textarea,select,img,svg'))return {reason:'Rich attachment is for display text only'};
+    const raw=[],walker=document.createTreeWalker(element,window.NodeFilter.SHOW_TEXT);
+    while(walker.nextNode()){const node=walker.currentNode;if(!canvas.contains(node)&&node.data.trim())raw.push(node);}
+    const nodes=groupDOMTextNodes(raw,document);
+    if([...element.querySelectorAll('input,textarea,select,img,svg,canvas,[contenteditable="true"]')].some(node=>node!==canvas&&!canvas.contains(node)))return {reason:'Rich text currently accepts text elements only'};
+    // Shaping across styled-node boundaries needs a shared shaping context.
+    if(!prepareFontBoundaries(nodes,document))return {reason:'Unsupported joining boundary uses native shaping'};
+    this.shapingMismatch=null;
+    const box=element.getBoundingClientRect(),width=element.clientWidth||box.width,height=element.clientHeight||box.height;
+    if(!(width>0&&height>0))return {reason:'Text is not visible'};
+    const wanted=new Set(nodes.map(n=>n.first));for(const [node,run] of this.runs)if(!wanted.has(node)){this.restore();this.drop(run);this.runs.delete(node);}
+    const segmenter=new Intl.Segmenter(undefined,{granularity:'grapheme'});
+    for(const node of nodes){
+      if(cancelled()||this.disposed)return null;
+      const parent=node.parentElement,style=window.getComputedStyle(parent),size=parseFloat(style.fontSize);
+      const collapseWhitespace=['normal','nowrap'].includes(style.whiteSpace);
+      if(!(size>0)||style.writingMode!=='horizontal-tb'||style.textTransform!=='none'||style.textAlign==='justify'||node.data.includes('\t')&&!collapseWhitespace)return {reason:'Unsupported rich typography uses native text'};
+      for(let ancestor=parent;ancestor;ancestor=ancestor.parentElement){
+        const css=window.getComputedStyle(ancestor);
+        for(const pseudo of ['::before','::after']){const p=window.getComputedStyle(ancestor,pseudo);if(p.display!=='none'&&!['none','normal','""',"''"].includes(p.content))return {reason:'Generated content uses native text'};}
+        if(ancestor!==element&&(css.transform!=='none'||css.opacity!=='1'||css.overflowX!=='visible'||css.overflowY!=='visible'))return {reason:'Nested transformed, faded or clipped text uses native text'};
+        if(ancestor===element)break;
+      }
+      let run=this.runs.get(node.first);
+      if(!run){const group=new THREE.Group();this.content.add(group);const engine=new HybridTextFlowEngine({scale:.036,divisions:this.options.divisions??'auto',textRendering:'texture'});
+        run={node:node.first,group,engine,view:new SharedTextScene(THREE,engine,group),effect:new TextEditEffect(THREE,{mode:'dust-wind'}),key:null};this.runs.set(node.first,run);}
+      run.nodes=node.nodes;
+      const fontChanged=await adoptDOMFont(run.engine,parent);
+      // A newly loaded font can change glyph pixels without changing CSS names,
+      // advances or line boxes. Rebind the run to the refreshed raster source.
+      if(fontChanged)run.key=null;
+      if(cancelled()||this.disposed)return null;
+      const factor=size/200,context=run.engine.rasterizer.context;context.font=domFontAtSize(run.engine,size);context.direction=style.direction;
+      const spacing=[style.letterSpacing,style.wordSpacing].map(value=>value==='normal'?0:parseFloat(value));
+      if(spacing.some(value=>!Number.isFinite(value))||spacing.some((value,i)=>value!==0&&!(['letterSpacing','wordSpacing'][i] in context)))return {reason:'Canvas spacing unavailable; native text retained'};
+      const spacingKey=JSON.stringify(spacing.map(value=>value/factor));
+      if(run.spacingKey!==spacingKey){run.engine.clearMeshes();run.engine.rasterizer.cache.clear();run.key=null;run.spacingKey=spacingKey;}
+      run.engine.rasterizer.letterSpacing=spacing[0]/factor;run.engine.rasterizer.wordSpacing=spacing[1]/factor;
+      if('letterSpacing' in context)context.letterSpacing=`${spacing[0]}px`;
+      if('wordSpacing' in context)context.wordSpacing=`${spacing[1]}px`;
+      const metrics=context.measureText('Hgآی'),rows=[],characters=[];let row=null;
+      if(!Number.isFinite(metrics.fontBoundingBoxAscent))return {reason:'Native font metrics unavailable'};
+      for(const part of segmenter.segment(node.data)){
+        const range=document.createRange();setRunRange(range,node,part.index,part.index+part.segment.length);
+        const rect=range.getBoundingClientRect();if(!rect.width||!rect.height)continue;
+        const top=rect.top-box.top-element.clientTop;
+        if(!row||Math.abs(row.top-top)>.75){row={start:part.index,end:part.index,top,left:Infinity,right:-Infinity,direction:style.direction,baseline:top+(rect.height+metrics.fontBoundingBoxAscent-metrics.fontBoundingBoxDescent)/2};rows.push(row);}
+        row.end=part.index+part.segment.length;row.left=Math.min(row.left,rect.left-box.left-element.clientLeft);row.right=Math.max(row.right,rect.right-box.left-element.clientLeft);
+        const unit=run.engine.scale/factor;
+        characters.push({x:(rect.left-box.left-element.clientLeft)*unit,y:-(row.baseline+metrics.fontBoundingBoxDescent)*unit,width:rect.width*unit,height:(metrics.fontBoundingBoxAscent+metrics.fontBoundingBoxDescent)*unit,direction:style.direction});
+      }
+      for(const r of rows){
+        // Preserve original offsets for DOM Range/color mapping; normalize only
+        // the raster string when CSS collapses ASCII whitespace. NBSP and
+        // preformatted spacing are deliberately untouched.
+        // Collapsible whitespace at a visual line end has no native advance.
+        // Range may still report a rectangle for it (notably with negative
+        // letter-spacing on Android), so exclude it before canvas measurement.
+        if(collapseWhitespace&&(r.end<node.data.length||node===nodes.at(-1))){
+          while(r.end>r.start&&/[ \t\r\n\f]/.test(node.data[r.end-1]))r.end--;
+          if(r.end>r.start){
+            const range=document.createRange();setRunRange(range,node,r.start,r.end);
+            const rects=[...range.getClientRects()].filter(rect=>rect.height>0);
+            if(rects.length){r.left=Math.min(...rects.map(rect=>rect.left))-box.left-element.clientLeft;r.right=Math.max(...rects.map(rect=>rect.right))-box.left-element.clientLeft;}
+          }
+        }
+        let text=node.data.slice(r.start,r.end);
+        if(collapseWhitespace)text=text.replace(/[ \t\r\n\f]+/g,' ');
+        r.text=(r.start===0&&node.joinStart?'\u200d':'')+text+(r.end===node.data.length&&node.joinEnd?'\u200d':'');
+        const expected=context.measureText(r.text).width;if(Math.abs(expected-(r.right-r.left))>Math.max(1,expected*.015)){
+          this.shapingMismatch={text:r.text,canvasWidth:expected,domWidth:r.right-r.left,font:context.font,letterSpacing:context.letterSpacing,wordSpacing:context.wordSpacing,kerning:context.fontKerning,textRendering:context.textRendering};
+          return {reason:'Rich run shaping differs from DOM; native text retained'};
+        }
+      }
+      run.engine.rasterizer.displayFontSize=size;run.engine.rasterizer.configure();const layout={rows,factor};
+      const paints=node.nodes.map(text=>({text,color:window.getComputedStyle(text.parentElement).color}));
+      const multicolor=new Set(paints.map(p=>p.color)).size>1;
+      const key=JSON.stringify([node.data,size,run.engine.domFont.key,rows,paints.map(p=>p.color)]);
+      if(key!==run.key){onRebuild();run.effect.cancel();run.engine.setDisplayFontSize(size);await run.engine.prepareRows(layout,{cancelled});if(cancelled()||this.disposed)return null;
+        if(multicolor)for(let i=0;i<rows.length;i++){
+          const row=rows[i],entry=run.engine.flowLayout.entries[i],item=entry.metrics.items[0],glyph=item.glyph;
+          const spans=[];let offset=0;
+          for(const paint of paints){const start=Math.max(row.start,offset),end=Math.min(row.end,offset+paint.text.length);offset+=paint.text.length;if(end<=start)continue;
+            const range=document.createRange();setRunRange(range,node,start,end);
+            const color=new THREE.Color().setStyle(paint.color).convertLinearToSRGB();
+            for(const rect of range.getClientRects())if(Math.abs(rect.top-box.top-element.clientTop-row.top)<.75)spans.push({left:rect.left-box.left-element.clientLeft,right:rect.right-box.left-element.clientLeft,color});
+          }
+          const source=glyph.rasterSurface,rgba=new Uint8ClampedArray(source.rgba);
+          for(let x=0;x<source.width;x++){
+            const px=row.left+(x+.5-glyph.drawOffsetX)*factor;
+            let nearest=null,distance=Infinity;for(const span of spans){const d=Math.max(span.left-px,px-span.right,0);if(d<distance){distance=d;nearest=span;}}
+            if(nearest)for(let y=0;y<source.height;y++){const p=(y*source.width+x)*4;rgba[p]=Math.round(nearest.color.r*255);rgba[p+1]=Math.round(nearest.color.g*255);rgba[p+2]=Math.round(nearest.color.b*255);}
+          }
+          // A presentation-owned copy preserves the engine's reusable alpha raster.
+          item.glyph={...glyph,rasterSurface:{...source,rgba,mask:false}};
+        }
+        run.view.setText(node.data);run.key=key;}
+      run.group.scale.setScalar(factor/run.engine.scale);run.view.uniforms.tint.value.setStyle(multicolor?'white':style.color);run.size=size;run.characters=characters;
+    }
+    return {width,height,size:parseFloat(window.getComputedStyle(element).fontSize),factor:.036,text:nodes.map(n=>n.data).join(''),direction:window.getComputedStyle(element).direction,characters:[]};
+  }
+  play(phase,mode,settings,seed,now){for(const run of this.runs.values()){
+    run.effect.cancel();if(mode==='none')continue;
+    run.effect.setMode(phase==='exit'&&settings.exitEffect!=='same'?settings.exitEffect:mode);run.effect.configure(settings);
+    const b=run.view.bounds;run.effect.playRegion(run.view,{x:b.minX-.001,y:b.minY-.001,width:b.maxX-b.minX+.002,height:b.maxY-b.minY+.002,direction:run.engine.domFont?run.node.parentElement.ownerDocument.defaultView.getComputedStyle(run.node.parentElement).direction:'ltr'},200*run.engine.scale,now,{departing:phase==='exit',seed});
+    run.effect.prepareCharacterCenters(run.view,()=>run.characters);
+  }}
+  step(now,reduced){let active=false;for(const run of this.runs.values())active=run.effect.step(now,reduced)||active;return active;}
+  stats(){return {shapingMismatch:this.shapingMismatch??null,runs:this.runs.size,triangles:[...this.runs.values()].reduce((n,r)=>n+(r.view.triangleCount??0),0),active:[...this.runs.values()].some(r=>r.effect.active)};}
+}
 
 
 

package/src/dom-surface-font.js

@@ -4,8 +4,8 @@ import {domRasterCache} from './dom-raster-cache.js';
 const owners=new WeakMap();
 export function readDOMFont(element){
   const style=element.ownerDocument.defaultView.getComputedStyle(element);
-  const font={family:style.fontFamily,weight:Number(style.fontWeight)||400,style:style.fontStyle};
-  font.key=JSON.stringify([font.family,font.weight,font.style]);return font;
+  const font={family:style.fontFamily,weight:Number(style.fontWeight)||400,style:style.fontStyle,kerning:style.fontKerning,textRendering:style.textRendering};
+  font.key=JSON.stringify([font.family,font.weight,font.style,font.kerning,font.textRendering]);return font;
 }
 export function domFontAtSize(engine,size){
   const font=engine.domFont;
@@ -34,12 +34,12 @@ export async function adoptDOMFont(engine,element){
   rasterizer.canvas=document.createElement('canvas');
   rasterizer.context=rasterizer.canvas.getContext('2d',{willReadFrequently:true});
   if(!rasterizer.context)throw Error('Canvas font rasterization unavailable');
-  rasterizer.font=`${next.style} ${next.weight} 200px ${next.family}`;rasterizer.cache=new Map();rasterizer.configure();
+  rasterizer.font=`${next.style} ${next.weight} 200px ${next.family}`;rasterizer.cache=new Map();rasterizer.fontKerning=next.kerning;rasterizer.textRendering=next.textRendering;rasterizer.configure();
   const metric=rasterizer.context.measureText('آبپچگژهمیABCgj');
   rasterizer.ascent=Math.ceil(Math.max(metric.fontBoundingBoxAscent||0,metric.actualBoundingBoxAscent||0));
   rasterizer.descent=Math.ceil(Math.max(metric.fontBoundingBoxDescent||0,metric.actualBoundingBoxDescent||0));
   rasterizer.raster=function(text,direction='ltr'){
-    const key=JSON.stringify([this.font,this.ascent,this.descent,this.letterSpacing||0,this.wordSpacing||0,direction,text]);
+    const key=JSON.stringify([this.font,this.displayFontSize,this.fontKerning,this.textRendering,this.ascent,this.descent,this.letterSpacing||0,this.wordSpacing||0,direction,text]);
     return shared.raster(key,()=>{this.cache.clear();return FontRasterizer.prototype.raster.call(this,text,direction);});
   };
   owner.epoch=shared.epoch;

package/src/dom-text-fingerprint.js

@@ -1,27 +1,27 @@
-// Validate native layout with whole-node line boxes before the expensive
-// per-grapheme placement pass. Coordinates are relative to the slot, so page
-// scrolling does not invalidate text geometry. Node identity matters: identical
-// replacement markup still needs fresh run references.
-const fields=['display','visibility','fontFamily','fontSize','fontWeight','fontStyle','fontStretch','fontFeatureSettings','fontVariationSettings','fontKerning','fontVariant','fontOpticalSizing','lineHeight','direction','unicodeBidi','whiteSpace','letterSpacing','wordSpacing','verticalAlign','textAlign','textIndent','textTransform','textDecorationLine','writingMode','textOrientation','wordBreak','overflowWrap','hyphens','tabSize','opacity','transform','overflowX','overflowY','color'];
-export function createDOMTextFingerprint(element,canvas){
-  const document=element.ownerDocument,window=document.defaultView,ids=new WeakMap();let sequence=0;
-  const id=node=>{if(!ids.has(node))ids.set(node,++sequence);return ids.get(node);};
-  return ()=>{
-    const box=element.getBoundingClientRect(),left=box.left+element.clientLeft,top=box.top+element.clientTop;
-    const parts=[element.isConnected,element.clientWidth||box.width,element.clientHeight||box.height,element.clientLeft,element.clientTop];
-    function visit(node){
-      if(node===canvas)return;
-      if(node.nodeType===3){
-        const range=document.createRange();range.selectNodeContents(node);
-        parts.push(['text',id(node),node.data,[...range.getClientRects()].map(r=>[r.left-left,r.top-top,r.width,r.height])]);return;
-      }
-      if(node.nodeType!==1)return;
-      const style=window.getComputedStyle(node);
-      parts.push(['element',id(node),node.localName,node.isContentEditable,fields.map(name=>style[name])]);
-      for(const pseudo of ['::before','::after']){const css=window.getComputedStyle(node,pseudo);parts.push([css.display,css.content]);}
-      for(const child of node.childNodes)visit(child);
-      parts.push('end');
-    }
-    visit(element);return JSON.stringify(parts);
-  };
-}
+// Validate native layout with whole-node line boxes before the expensive
+// per-grapheme placement pass. Coordinates are relative to the slot, so page
+// scrolling does not invalidate text geometry. Node identity matters: identical
+// replacement markup still needs fresh run references.
+const fields=['display','visibility','fontFamily','fontSize','fontWeight','fontStyle','fontStretch','fontFeatureSettings','fontVariationSettings','fontKerning','textRendering','fontVariant','fontOpticalSizing','lineHeight','direction','unicodeBidi','whiteSpace','letterSpacing','wordSpacing','verticalAlign','textAlign','textIndent','textTransform','textDecorationLine','writingMode','textOrientation','wordBreak','overflowWrap','hyphens','tabSize','opacity','transform','overflowX','overflowY','color'];
+export function createDOMTextFingerprint(element,canvas){
+  const document=element.ownerDocument,window=document.defaultView,ids=new WeakMap();let sequence=0;
+  const id=node=>{if(!ids.has(node))ids.set(node,++sequence);return ids.get(node);};
+  return ()=>{
+    const box=element.getBoundingClientRect(),left=box.left+element.clientLeft,top=box.top+element.clientTop;
+    const parts=[element.isConnected,element.clientWidth||box.width,element.clientHeight||box.height,element.clientLeft,element.clientTop];
+    function visit(node){
+      if(node===canvas)return;
+      if(node.nodeType===3){
+        const range=document.createRange();range.selectNodeContents(node);
+        parts.push(['text',id(node),node.data,[...range.getClientRects()].map(r=>[r.left-left,r.top-top,r.width,r.height])]);return;
+      }
+      if(node.nodeType!==1)return;
+      const style=window.getComputedStyle(node);
+      parts.push(['element',id(node),node.localName,node.isContentEditable,fields.map(name=>style[name])]);
+      for(const pseudo of ['::before','::after']){const css=window.getComputedStyle(node,pseudo);parts.push([css.display,css.content]);}
+      for(const child of node.childNodes)visit(child);
+      parts.push('end');
+    }
+    visit(element);return JSON.stringify(parts);
+  };
+}