@ev-ry/fx 0.1.0-rc.1

package/src/dom-image-surface.js

@@ -0,0 +1,109 @@
+import {createImageSurface,IMAGE_EFFECT_MODES} from './image-surface.js';
+import {normalizeTextEffectOptions} from './text-effect-options.js';
+import {rasterizeDOMImage} from './dom-image-raster.js';
+import {queueImagePreparation} from './image-preparation-queue.js';
+
+// Native IMG retains source, alternative text and events. This adapter supplies
+// only a presentation scene to the existing DOM owner and image effect engine.
+export function attachImageSurface(element,THREE,options={}){
+  if(element?.tagName!=='IMG'||!element.parentElement)throw TypeError('A mounted IMG is required');
+  function validate(value){if(!['mesh','native'].includes(value.resting??'mesh'))throw TypeError('Invalid resting presentation');if(!IMAGE_EFFECT_MODES.includes(value.inputEffect??'dust-wind'))throw TypeError('Invalid image effect');normalizeTextEffectOptions(value.inputEffectOptions??{},value.inputEffect??'dust-wind');}validate(options);
+  const document=element.ownerDocument,window=document.defaultView,parent=element.parentElement;
+  const renderer=new THREE.WebGLRenderer({alpha:true,antialias:true}),canvas=renderer.domElement;
+  const scene=new THREE.Scene(),camera=new THREE.OrthographicCamera(-1,1,1,-1,.1,100);camera.position.z=10;
+  const originalOpacity=element.style.opacity,originalPosition=parent.style.position;
+  const ownsPosition=window.getComputedStyle(parent).position==='static';if(ownsPosition)parent.style.position='relative';
+  Object.assign(canvas.style,{position:'absolute',pointerEvents:'none',display:'none'});canvas.setAttribute('aria-hidden','true');parent.append(canvas);
+  renderer.setSurface?.(parent);
+  let pendingSurface=null,baseWidth=1,baseHeight=1;
+  let requested=null,preparing=false,inFlight=false,prepareTimer=null,queueJob=null,committedURL='',resizeStarted=0,failed=false;
+  let disposed=false,frame=null,surface=null,revision=0,source='',mode='native',reason=null,phase='enter',resolve;
+  let queuedPhase=options.initialPhase??null;
+  const ready=new Promise(r=>resolve=r),reduced=window.matchMedia('(prefers-reduced-motion: reduce)');
+  function native(error){mode='native';reason=error||null;element.style.opacity=!disposed&&surface?.stats().state==='hidden'?'0':originalOpacity;canvas.style.display='none';options.onPresentation?.({mode,reason});renderer.invalidate?.();}
+  function request(){if(!disposed&&frame===null)frame=window.requestAnimationFrame(draw);}
+  const runtime={THREE,document,renderer,camera,requestRender:request,register(control){scene.add(control.object);return ()=>scene.remove(control.object);}};
+  function draw(now){frame=null;if(disposed||!surface||failed||queuedPhase!==null&&preparing)return;try{
+    const box=element.getBoundingClientRect(),p=parent.getBoundingClientRect(),css=window.getComputedStyle(element);
+    if(!box.width||!box.height||css.display==='none'||css.visibility!=='visible'){native('Image not visible');resolve({mode,reason});return;}
+    if(css.transform!=='none'||css.objectPosition!=='50% 50%'||!['fill','contain','cover'].includes(css.objectFit)||parseFloat(css.paddingTop)||parseFloat(css.paddingLeft)||parseFloat(css.borderTopWidth)){native('Unsupported image layout');resolve({mode,reason});return;}
+    const s=surface.stats();if(!s.source)return;
+    const w=box.width,h=box.height;
+    surface.object.scale.set(w/baseWidth,h/baseHeight,1);surface.setDisplaySize(w,h);
+    camera.left=-box.width/2;camera.right=box.width/2;camera.top=box.height/2;camera.bottom=-box.height/2;camera.updateProjectionMatrix();
+    Object.assign(canvas.style,{left:(box.left-p.left-parent.clientLeft+parent.scrollLeft)+'px',top:(box.top-p.top-parent.clientTop+parent.scrollTop)+'px',width:box.width+'px',height:box.height+'px',display:'block'});
+        canvas.style.zIndex=css.zIndex;renderer.setSize(box.width,box.height,false);if(queuedPhase!==null&&!preparing){phase=queuedPhase;surface[queuedPhase]();queuedPhase=null;}surface.frame(now,reduced.matches);
+    const state=surface.stats();
+    if(!state.active&&(options.resting==='native'||reduced.matches)){
+      // Submit before handing off: reveal gates acknowledge even reduced motion.
+      renderer.render(scene,camera);
+      native(state.state==='hidden'?'hidden after exit':'native resting presentation');
+      if(state.state==='hidden')element.style.opacity='0';
+      resolve({mode,reason});return;
+    }
+    const handingOffNative=mode==='native';
+    if(element.style.opacity!=='0')element.style.opacity='0';mode='mesh';reason=null;renderer.render(scene,camera);
+    options.onPresentation?.({mode,reason});
+    if(handingOffNative)renderer.flushPresentation?.();
+    resolve({mode,reason});
+  }catch(error){native(error.message);resolve({mode,reason});}}
+  function nearViewport(box){const margin=window.innerHeight*.5;return box.bottom>=-margin&&box.top<=window.innerHeight+margin&&box.right>=0&&box.left<=window.innerWidth;}
+  function measure(){const url=element.currentSrc||element.src,css=window.getComputedStyle(element),box=element.getBoundingClientRect();return {url,css,box,key:JSON.stringify([url,box.width,box.height,css.objectFit,css.objectPosition,css.borderTopLeftRadius,css.borderTopRightRadius,css.borderBottomLeftRadius,css.borderBottomRightRadius])};}
+  function schedule(delay=0){clearTimeout(prepareTimer);if(disposed||inFlight||!requested)return;preparing=true;prepareTimer=setTimeout(prepare,delay);}
+  async function prepare(){
+    prepareTimer=null;if(disposed||inFlight||!requested)return;
+    inFlight=true;preparing=true;const token=revision,current=requested;
+    try{
+      if(!element.complete||!element.naturalWidth)await element.decode();
+      if(disposed||token!==revision)return;
+      queueJob=queueImagePreparation(window,async()=>{
+        if(disposed||token!==revision)return false;
+        // Resize/decode may have changed the measured box without an observer
+        // callback yet. Do not allocate pixels for the stale dimensions.
+        const measured=measure();if(measured.key!==current.key){refresh();return false;}
+        const raster=await rasterizeDOMImage(element,{maxSide:Math.min(2048,renderer.capabilities?.maxTextureSize||2048)});
+        if(disposed||token!==revision)return false;
+        const next=surface??createImageSurface(runtime,{width:raster.width,height:raster.height,effect:options.inputEffect??'dust-wind',settings:options.inputEffectOptions??{}});
+        if(!surface)pendingSurface=next;
+        next.setDisplaySize(current.box.width,current.box.height);
+        await next.setSource(raster.source,{preserveMotion:!!surface&&committedURL===current.url,bounds:{width:raster.width,height:raster.height}});
+        if(disposed||token!==revision){if(next!==surface)next.destroy();return false;}
+        surface=next;pendingSurface=null;baseWidth=raster.width;baseHeight=raster.height;source=current.key;committedURL=current.url;requested=null;resizeStarted=0;return true;
+      });
+      await queueJob.promise;
+    }catch(error){pendingSurface?.destroy();pendingSurface=null;if(!disposed&&token===revision){requested=null;source='';resizeStarted=0;failed=true;native(error.message);resolve({mode,reason});}}
+    finally{queueJob=null;inFlight=false;preparing=false;if(!disposed){if(requested)schedule(surface?50:0);request();}}
+  }
+  function refresh(){
+    if(disposed)return;const current=measure(),{box,css}=current;
+    if(!element.isConnected||!box.width||!box.height||css.display==='none'||css.visibility!=='visible'||!nearViewport(box)){
+      if(requested){revision++;requested=null;queueJob?.cancel();}clearTimeout(prepareTimer);prepareTimer=null;preparing=inFlight;
+      if(!surface||!box.width||!box.height||css.display==='none'||css.visibility!=='visible'){native('Image not visible');resolve({mode,reason});}return;
+    }
+    if(current.key===source){if(requested){revision++;requested=null;queueJob?.cancel();clearTimeout(prepareTimer);prepareTimer=null;preparing=inFlight;}if(surface)request();return;}
+    if(current.key===requested?.key)return;
+    requested=current;revision++;failed=false;queueJob?.cancel();
+    // Keep the current texture/motion during a resize burst. Rebuild the latest
+    // size after 50ms of quiet, with a 150ms bound for continuous transitions.
+    const resizing=surface&&committedURL===current.url;
+    if(resizing&&!resizeStarted)resizeStarted=performance.now();
+    schedule(resizing?Math.max(0,Math.min(50,150-(performance.now()-resizeStarted))):0);
+  }
+  const resize=new window.ResizeObserver(refresh);resize.observe(element);
+  const styleKey=()=>element.style.cssText.replace(/(?:^|;)\s*opacity\s*:[^;]*/g,'');let lastStyle=styleKey();
+  const observer=new window.MutationObserver(records=>{const next=styleKey();if(records.some(r=>r.attributeName!=='style')||next!==lastStyle){lastStyle=next;refresh();}});observer.observe(element,{attributes:true,attributeFilter:['src','srcset','sizes','class','style']});
+  const proximity=window.IntersectionObserver?new window.IntersectionObserver(entries=>{if(entries.some(entry=>entry.isIntersecting))refresh();},{rootMargin:`${window.innerHeight*.5}px 0px`}):null;proximity?.observe(element);
+  const onScroll=()=>{if(mode==='mesh')request();if(!proximity&&!surface)refresh();};
+  reduced.addEventListener('change',request);element.addEventListener('load',refresh);window.addEventListener('resize',refresh);window.addEventListener('scroll',onScroll,true);refresh();
+  return {element,ready,refresh,cancel(){if(disposed)return;phase='enter';queuedPhase=null;surface?.show();request();},play(value='enter'){if(!['enter','exit'].includes(value))throw TypeError('Expected enter or exit');phase=value;queuedPhase=value;request();},
+    update(next={}){const candidate={...options,...next};validate(candidate);options=candidate;surface?.setEffect(options.inputEffect??'dust-wind',options.inputEffectOptions??{});request();},
+    stats:()=>({disposed,mode,reason,phase,preparing,image:surface?.stats()}),
+    destroy(){if(disposed)return;disposed=true;revision++;requested=null;clearTimeout(prepareTimer);queueJob?.cancel();if(frame!==null)window.cancelAnimationFrame(frame);resize.disconnect();observer.disconnect();proximity?.disconnect();reduced.removeEventListener('change',request);element.removeEventListener('load',refresh);window.removeEventListener('resize',refresh);window.removeEventListener('scroll',onScroll,true);surface?.destroy();pendingSurface?.destroy();native();renderer.dispose();renderer.forceContextLoss();canvas.remove();if(ownsPosition&&parent.style.position==='relative')parent.style.position=originalPosition;resolve({mode:'native',reason:'destroyed'});}
+  };
+}
+
+
+
+
+
+

package/src/dom-image-swap.js

@@ -0,0 +1,27 @@
+// Place the next native image over the previous image; animate transiently.
+export function swapDOMImage(animate,previous,next,{exitEffect=null,waitForExit=false,enterEffect=true,topImage='next',...options}={}){
+  if(!['previous','next'].includes(topImage))throw TypeError('Expected previous or next topImage');
+  if(previous===next||previous?.tagName!=='IMG'||next?.tagName!=='IMG'||!previous.parentElement)throw TypeError('Two different IMG elements are required');
+  const previousVisibility=previous.style.visibility,previousPosition=previous.style.position,previousZ=previous.style.zIndex;let cancelled=false,jobs=[];const parent=previous.parentElement,origin=next.parentNode,sibling=next.nextSibling,css=next.style.cssText,parentPosition=parent.style.position;
+  const finished=(async()=>{try{await Promise.all([previous.decode(),next.decode()]);if(cancelled)return {status:'cancelled'};
+    const view=previous.ownerDocument.defaultView,box=previous.getBoundingClientRect();if(view.getComputedStyle(parent).position==='static')parent.style.position='relative';const bounds=parent.getBoundingClientRect();
+    parent.append(next);Object.assign(next.style,{position:'absolute',left:(box.left-bounds.left-parent.clientLeft+parent.scrollLeft)+'px',top:(box.top-bounds.top-parent.clientTop+parent.scrollTop)+'px',width:box.width+'px',height:box.height+'px',margin:'0',visibility:'hidden'});
+    if(view.getComputedStyle(previous).position==='static')previous.style.position='relative';previous.style.zIndex=topImage==='previous'?'1':'0';next.style.zIndex=topImage==='next'?'1':'0';
+    // Local layers preserve the native next image above a departing canvas too.
+    const layerOptions=(!enterEffect||topImage==='previous')?{...options,presentation:'local'}:options;
+    const beginEntry=()=>{next.style.visibility='visible';if(enterEffect)jobs.push(animate(next,{...layerOptions,phase:'enter'}));};
+    const earlyEntry=!enterEffect||(!waitForExit&&topImage==='previous');if(earlyEntry)beginEntry();
+    if(exitEffect){
+      const exit=animate(previous,{...layerOptions,inputEffect:exitEffect,phase:'exit'});jobs.push(exit);
+      if(waitForExit){const result=await exit.finished;if(cancelled||result.status!=='completed'){rollback();return {status:cancelled?'cancelled':result.status};}}
+    }
+    if(!earlyEntry)beginEntry();
+    const results=await Promise.all(jobs.map(job=>job.finished));const success=!cancelled&&results.every(r=>r.status==='completed');
+    if(success){previous.style.visibility='hidden';return {status:'completed'};}
+    rollback();return {status:cancelled?'cancelled':'unsupported'};
+  }catch(error){jobs.forEach(j=>j.cancel());rollback();throw error;}})();
+  function rollback(){previous.style.position=previousPosition;previous.style.zIndex=previousZ;previous.style.visibility=previousVisibility;next.style.cssText=css;if(origin)origin.insertBefore(next,sibling?.parentNode===origin?sibling:null);parent.style.position=parentPosition;}
+  return {finished,cancel(){cancelled=true;jobs.forEach(j=>j.cancel());}};
+}
+
+

package/src/dom-once.js

@@ -0,0 +1,34 @@
+const running=new WeakMap(),hidden=new WeakMap();
+// Transient use of the same surfaces; no second animation implementation.
+export function animateDOMOnce(attach,element,{phase='enter',presentation='global',...options}={}){
+  if(options.revealOnView)throw TypeError('revealOnView is an attachment option, not a transient animation option');
+  if(!['enter','exit'].includes(phase))throw TypeError('Expected enter or exit');
+  if(running.has(element))throw Error('An animation is already running on this element');
+  const previous=hidden.get(element);
+  const paint=element.tagName==='IMG'?'opacity':'-webkit-text-fill-color';
+  const paintValue=element.style.getPropertyValue(paint),paintPriority=element.style.getPropertyPriority(paint);
+  if(phase==='enter')element.style.setProperty(paint,element.tagName==='IMG'?'0':'transparent');
+  if(previous&&element.style.visibility==='hidden'){element.style.setProperty('visibility',previous.value,previous.priority);hidden.delete(element);}
+  let surface,done=false,timer;let resolve,reject;
+  const finished=new Promise((a,b)=>{resolve=a;reject=b;});
+  function finish(status,error){if(done)return;done=true;clearTimeout(timer);running.delete(element);surface?.destroy();
+    if(phase==='enter'){if(paintValue)element.style.setProperty(paint,paintValue,paintPriority);else element.style.removeProperty(paint);}
+    if(status==='completed'&&phase==='exit'){hidden.set(element,{value:element.style.getPropertyValue('visibility'),priority:element.style.getPropertyPriority('visibility')});element.style.visibility='hidden';}
+    if(error)reject(error);else resolve({status,phase});
+  }
+  try{surface=attach(element.tagName==='IMG'?'attachImage':'attachText',element,{...options,presentation,resting:'mesh',initialPhase:phase});}catch(error){if(phase==='enter'){if(paintValue)element.style.setProperty(paint,paintValue,paintPriority);else element.style.removeProperty(paint);}if(previous){element.style.visibility='hidden';hidden.set(element,previous);}throw error;}
+  running.set(element,surface);const started=performance.now();
+  timer=setTimeout(()=>finish('cancelled',Error('Animation preparation timed out')),30000);
+  surface.ready.then(()=>{if(done)return;clearTimeout(timer);if(surface.stats().mode!=='mesh'){finish('unsupported');return;}
+    // Wait for the scheduled render before testing the shared effect's state.
+    let observed=false;
+    function poll(){if(done)return;const s=surface.stats();if(s.disposed){finish('cancelled');return;}
+      const active=!!(s.image?.active||s.rich?.active||s.effect?.active||s.pending);
+      if(active)observed=true;
+      if(!element.isConnected){finish('cancelled');return;}
+      if(!active&&(observed||performance.now()-started>150)){finish(s.mode==='mesh'?'completed':'unsupported');return;}
+      if(performance.now()-started>30000){finish('cancelled');return;}timer=setTimeout(poll,16);
+    }timer=setTimeout(poll,32);
+  }).catch(error=>finish('cancelled',error));
+  return {finished,cancel:()=>finish('cancelled')};
+}

package/src/dom-raster-cache.js

@@ -0,0 +1,33 @@
+// Document-scoped, bounded source pixels only. Geometry, tint and motion remain
+// attachment-owned. Live glyph records can outlive an LRU entry safely.
+const documents=new WeakMap();
+const MAX_BYTES=16*1024*1024,MAX_ENTRIES=128,MAX_FONTS=64;
+export function domRasterCache(document){
+  let cache=documents.get(document);if(cache)return cache;
+  const rasters=new Map(),fonts=new Map();let bytes=0,hits=0,misses=0,epoch=0;
+  function invalidate(){epoch++;rasters.clear();fonts.clear();bytes=0;}
+  cache={
+    get epoch(){return epoch;},
+    font(key,load){
+      let promise=fonts.get(key);
+      if(!promise){promise=Promise.resolve().then(load);fonts.set(key,promise);if(fonts.size>MAX_FONTS)fonts.delete(fonts.keys().next().value);promise.catch(()=>{if(fonts.get(key)===promise)fonts.delete(key);});}
+      return promise;
+    },
+    raster(key,build){
+      const old=rasters.get(key);
+      if(old){rasters.delete(key);rasters.set(key,old);hits++;return old;}
+      misses++;const result=build(),size=result.rgba.byteLength;
+      if(size<=MAX_BYTES){
+        while(rasters.size&&(bytes+size>MAX_BYTES||rasters.size>=MAX_ENTRIES)){const first=rasters.keys().next().value;bytes-=rasters.get(first).rgba.byteLength;rasters.delete(first);}
+        rasters.set(key,result);bytes+=size;
+      }
+      return result;
+    },
+    stats:()=>({bytes,entries:rasters.size,hits,misses,epoch,maxBytes:MAX_BYTES}),
+    invalidate
+  };
+  // Font files may finish after an engine first used the CSS fallback font.
+  document.fonts?.addEventListener('loadingdone',invalidate);
+  document.fonts?.addEventListener('loadingerror',invalidate);
+  documents.set(document,cache);return cache;
+}

package/src/dom-reveal-boot.js

@@ -0,0 +1,11 @@
+// Load synchronously in <head>, before body paint. No JavaScript = native content.
+(function(){
+  const style=document.createElement('style');
+  style.textContent='[data-thd-pending]{opacity:0!important}';
+  document.head.append(style);
+  function release(){style.remove();}
+  // Fail open even when the main module never loads or a target is unsupported.
+  const timer=setTimeout(release,8000);
+  window.addEventListener('thd:error',()=>{clearTimeout(timer);release();},{once:true});
+  window.addEventListener('pagehide',()=>{clearTimeout(timer);release();},{once:true});
+})();

package/src/dom-reveal.js

@@ -0,0 +1,75 @@
+// Presentation-only masking: SVG snapshots retain their original paint opacity.
+export const revealOpacity=new WeakMap();
+let sequence=0;
+export function withRevealOnView(factory,element,THREE,options){
+  // Transfer the boot mask in this same task, before paint and opacity capture.
+  element.removeAttribute('data-thd-pending');
+  const {revealOnView:config,...settings}=options;
+  if(config===undefined||config===false)return factory(element,THREE,settings);
+  if(!config||typeof config!=='object'||Array.isArray(config))throw TypeError('revealOnView requires an options object');
+  const {threshold=0,once=true,root=null}=config,document=element.ownerDocument,window=document.defaultView;
+  if(Object.keys(config).some(k=>!['threshold','once','root'].includes(k))||!Number.isFinite(threshold)||threshold<0||threshold>1||typeof once!=='boolean'||root!==null&&(root.ownerDocument!==document||root.nodeType!==1))throw TypeError('Invalid revealOnView options');
+  if(!window.IntersectionObserver)throw Error('IntersectionObserver unavailable');
+  const attribute='data-thd-reveal',previous=element.getAttribute(attribute),id=String(++sequence);
+  const style=document.createElement('style');style.textContent=`[${attribute}="${id}"]{opacity:0!important}`;
+  const originalOpacity=window.getComputedStyle(element).opacity;revealOpacity.set(element,originalOpacity);
+  element.setAttribute(attribute,id);document.head.append(style);
+  let held=true,disposed=false,ready=false,eligible=false,armed=true,count=0,fallback=false;let retry=null,attempts=0;
+  const empty=new THREE.Scene(),renderers=new Set();let revealPending=false;
+  const namespace={...THREE,WebGLRenderer:class extends THREE.WebGLRenderer{
+    constructor(...args){super(...args);renderers.add(this);}
+    render(scene,camera){this.revealCamera=camera;if(revealPending&&eligible){revealPending=false;count++;unmask();if(once)observer?.disconnect();}super.render(held?empty:scene,camera);
+      // Readiness is not permanently determined by an empty/unsupported first
+      // layout. A later successful render can complete the pending first entry.
+      if((count===0||fallback)&&armed&&eligible&&(!once||count===0))queueMicrotask(()=>{if(disposed||!armed||!eligible||once&&count!==0)return;fallback=false;ready=true;if(!held)mask();trigger();});
+    }
+    clearReveal(){if(this.revealCamera)super.render(empty,this.revealCamera);}
+  }};
+  let surface,observer,sizeObserver;
+  function mask(){clearTimeout(retry);retry=null;held=true;revealPending=false;revealOpacity.set(element,originalOpacity);if(!style.isConnected)document.head.append(style);for(const renderer of renderers)renderer.clearReveal();}
+  function unmask(){clearTimeout(retry);retry=null;held=false;style.remove();revealOpacity.delete(element);}
+  function isFallback(state){return state.mode!=='mesh'&&!state.preparing&&!!state.reason&&!/native resting presentation|not visible|not connected|hidden after exit/i.test(state.reason);}
+  function showFallback(){fallback=true;revealPending=false;armed=true;unmask();}
+  function cleanup(){disposed=true;observer?.disconnect();sizeObserver?.disconnect();unmask();if(previous===null)element.removeAttribute(attribute);else element.setAttribute(attribute,previous);}
+  // Only supervise an eligible reveal until its first rendered frame.
+  // A cancelled preparation/visibility frame must not consume the request.
+  function ensureFrame(){
+    clearTimeout(retry);retry=null;
+    if(disposed||!eligible||!held)return;
+    if(isFallback(surface.stats())){showFallback();return;}
+    if(++attempts>100){surface.destroy();return;}
+    if(!surface.stats().preparing){surface.refresh();if(revealPending)requestEntry();}
+    retry=setTimeout(ensureFrame,100);
+  }
+  function requestEntry(){
+    const state=surface.stats(),timeline=state.timeline;
+    const running=timeline?timeline.phase==='enter'&&timeline.ends>window.performance.now():state.image?.state==='entering'&&state.image?.active;
+    // Re-entering view resumes an unfinished entry; do not reset its clock.
+    if(running)surface.refresh();else surface.play('enter');
+  }
+  function trigger(){
+    if(disposed||!ready||!eligible||!armed)return;
+    if(isFallback(surface.stats())){showFallback();return;}
+    armed=false;revealPending=true;requestEntry();attempts=0;clearTimeout(retry);retry=setTimeout(ensureFrame,100);
+  }
+  try{
+    surface=factory(element,namespace,settings);
+    observer=new window.IntersectionObserver(entries=>{
+      for(const entry of entries){
+        const visible=entry.isIntersecting&&entry.intersectionRect.width>0&&entry.intersectionRect.height>0;
+        if(!visible){eligible=false;clearTimeout(retry);retry=null;if(!once||count===0){armed=true;mask();}continue;}
+        eligible=entry.intersectionRatio>=threshold;if(eligible&&armed){surface.refresh();attempts=0;clearTimeout(retry);retry=setTimeout(ensureFrame,100);}trigger();
+      }
+    },{root,threshold:[...new Set([0,threshold===0?0.000001:threshold])]});observer.observe(element);
+    // A zero-area intersection may already have ratio 1. Growing to a real
+    // box need not cross an IO threshold, so request a fresh observation once.
+    let hadArea=element.getBoundingClientRect().width>0&&element.getBoundingClientRect().height>0;
+    sizeObserver=new window.ResizeObserver(()=>{const box=element.getBoundingClientRect(),hasArea=box.width>0&&box.height>0;if(hasArea&&!hadArea&&(!once||count===0)){observer.unobserve(element);observer.observe(element);}hadArea=hasArea;});sizeObserver.observe(element);
+  }catch(error){cleanup();surface?.destroy();throw error;}
+  const destroy=surface.destroy,stats=surface.stats;
+  surface.stats=()=>({...stats(),reveal:{waiting:held,count,threshold,once}});
+  surface.destroy=()=>{if(disposed)return;cleanup();destroy();};
+  surface.ready.then(()=>{if(disposed)return;ready=true;const state=surface.stats();if(isFallback(state)){showFallback();return;}if(eligible)surface.refresh();trigger();},()=>{if(!disposed){unmask();observer.disconnect();}});
+  return surface;
+}
+

package/src/dom-rich-text.js

@@ -0,0 +1,119 @@
+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)};}
+}
+
+
+

package/src/dom-surface-font.js

@@ -0,0 +1,50 @@
+import {FontRasterizer} from './font-rasterizer.js';
+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;
+}
+export function domFontAtSize(engine,size){
+  const font=engine.domFont;
+  return font?`${font.style} ${font.weight} ${size}px ${font.family}`:`${engine.weight} ${size}px "${engine.face.family}"`;
+}
+export function matchesDOMFont(engine,style){
+  return engine.domFont?engine.domFont.family===style.fontFamily&&engine.domFont.weight===(Number(style.fontWeight)||400)&&engine.domFont.style===style.fontStyle
+    :style.fontFamily.includes(engine.face.family)&&Number(style.fontWeight)===engine.weight;
+}
+
+// Borrow the host's CSS font stack. Never register, replace or delete its FontFace.
+export async function adoptDOMFont(engine,element){
+  let owner=owners.get(engine);
+  if(!owner){
+    owner={sequence:0,disposed:false};owners.set(engine,owner);
+    const dispose=engine.dispose.bind(engine);
+    engine.dispose=()=>{owner.disposed=true;owner.sequence++;if(engine.domFont)engine.face=null;dispose();};
+  }
+  const next=readDOMFont(element);
+  const document=element.ownerDocument,shared=domRasterCache(document);
+  if(owner.disposed||next.key===engine.domFont?.key&&owner.epoch===shared.epoch)return false;
+  const sequence=++owner.sequence,started=performance.now();
+  await shared.font(next.key,()=>document.fonts?.load(`${next.style} ${next.weight} 16px ${next.family}`,'ABCآبپچگژهمی'));
+  if(owner.disposed||sequence!==owner.sequence||readDOMFont(element).key!==next.key)return false;
+  const rasterizer=Object.create(FontRasterizer.prototype);
+  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();
+  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]);
+    return shared.raster(key,()=>{this.cache.clear();return FontRasterizer.prototype.raster.call(this,text,direction);});
+  };
+  owner.epoch=shared.epoch;
+  engine.domFont=next;engine.face={family:next.family};engine.weight=next.weight;engine.rasterizer=rasterizer;engine.clearMeshes();
+  const ascent=rasterizer.ascent+2,descent=rasterizer.descent+2;
+  engine.fontMetrics={ascent,descent,height:ascent+descent};engine.lineAdvance=engine.fontMetrics.height*Math.max(1,engine.lineHeight);
+  engine.fontLoadMs=performance.now()-started;return true;
+}

package/src/dom-svg-surface.js

@@ -0,0 +1,43 @@
+import {revealOpacity} from './dom-reveal.js';
+import {attachImageSurface} from './dom-image-surface.js';
+function snapshot(element){
+  if(element.querySelector('script,foreignObject,use,image,text,animate,animateTransform,animateMotion'))throw Error('Unsupported SVG content');
+  const view=element.ownerDocument.defaultView,clone=element.cloneNode(true),nodes=[element,...element.querySelectorAll('*')],copies=[clone,...clone.querySelectorAll('*')];
+  for(let i=0;i<nodes.length;i++){
+    const css=view.getComputedStyle(nodes[i]),copy=copies[i];
+    if(css.filter!=='none'||css.clipPath!=='none'||css.maskImage!=='none'||css.transform!=='none'&&!nodes[i].hasAttribute('transform'))throw Error('Unsupported SVG geometry');
+    copy.removeAttribute('class');copy.removeAttribute('style');
+    for(const prop of ['fill','stroke','stroke-width','stroke-linecap','stroke-linejoin','stroke-miterlimit','stroke-dasharray','stroke-dashoffset','fill-rule','fill-opacity','stroke-opacity','opacity','color','paint-order','vector-effect','display']){const value=prop==='opacity'&&i===0&&revealOpacity.has(element)?revealOpacity.get(element):css.getPropertyValue(prop);if(/url\(/i.test(value))throw Error('SVG paint references unsupported');if(value)copy.style.setProperty(prop,value);}
+  }
+  clone.querySelectorAll('style').forEach(e=>e.remove());clone.setAttribute('xmlns','http://www.w3.org/2000/svg');const r=element.getBoundingClientRect();clone.setAttribute('width',r.width);clone.setAttribute('height',r.height);return new view.XMLSerializer().serializeToString(clone);
+}
+export function attachSVGSurface(element,THREE,options={}){
+  if(element?.localName!=='svg'||!element.parentElement)throw TypeError('A mounted SVG is required');
+  const document=element.ownerDocument,view=document.defaultView,parent=element.parentElement,oldVisibility=element.style.visibility;
+  const image=document.createElement('img');image.alt='';image.setAttribute('aria-hidden','true');Object.assign(image.style,{position:'absolute',pointerEvents:'none',opacity:'0'});parent.append(image);
+  let disposed=false,revision=0,timer=null,reason=null,xml='',surface,resolve;const ready=new Promise(r=>resolve=r);
+  function restore(){if(element.style.visibility==='hidden')element.style.visibility=oldVisibility;}
+  function present(state){
+    if(disposed)return;
+    if(state.mode==='mesh'||state.reason==='hidden after exit'){if(element.style.visibility!=='hidden')element.style.visibility='hidden';}else restore();
+    reason=state.reason;
+    if(state.mode==='mesh'||state.reason)resolve(state);
+  }
+  async function refresh(){if(disposed)return;const token=++revision;clearTimeout(timer);
+    try{const next=snapshot(element),r=element.getBoundingClientRect(),p=parent.getBoundingClientRect();if(!(r.width>0&&r.height>0))throw Error('SVG not visible');
+      Object.assign(image.style,{left:(r.left-p.left-parent.clientLeft+parent.scrollLeft)+'px',top:(r.top-p.top-parent.clientTop+parent.scrollTop)+'px',width:r.width+'px',height:r.height+'px'});
+      if(next!==xml){xml=next;restore();image.src='data:image/svg+xml;charset=utf-8,'+encodeURIComponent(xml);}
+      if(!surface)surface=attachImageSurface(image,THREE,{...options,onPresentation:present});
+      await surface.refresh();if(disposed||token!==revision)return;
+      const settle=()=>{if(disposed||token!==revision)return;const s=surface.stats();if(s.mode==='mesh'||s.reason)present(s);else timer=setTimeout(settle,16);};settle();
+    }catch(error){reason=error.message;xml='';surface?.destroy();surface=null;restore();resolve({mode:'native',reason});}
+  }
+  const styleKey=()=>element.style.cssText.replace(/(?:^|;)\s*visibility\s*:[^;]*/g,'');let lastStyle=styleKey();
+  const observer=new view.MutationObserver(records=>{const next=styleKey();if(records.some(r=>r.target!==element||r.attributeName!=='style')||next!==lastStyle){lastStyle=next;refresh();}});
+  observer.observe(element,{subtree:true,attributes:true,childList:true,characterData:true});for(let a=parent;a;a=a.parentElement)observer.observe(a,{attributes:true,attributeFilter:['class','style']});
+  const resize=new view.ResizeObserver(refresh);resize.observe(element);refresh();
+  return {element,ready,refresh,cancel:()=>surface?.cancel(),play(phase='enter'){if(!['enter','exit'].includes(phase))throw TypeError('Expected enter or exit');if(phase==='enter'&&surface?.stats().image?.source)element.style.visibility='hidden';surface?.play(phase);},update(next){options={...options,...next};surface?.update(next);},stats:()=>({...surface?.stats(),disposed,reason:reason||surface?.stats().reason,mode:reason?'native':surface?.stats().mode||'native'}),destroy(){if(disposed)return;disposed=true;revision++;clearTimeout(timer);observer.disconnect();resize.disconnect();surface?.destroy();image.remove();restore();resolve({mode:'native',reason:'destroyed'});}};
+}
+
+
+

package/src/dom-text-fingerprint.js

@@ -0,0 +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);
+  };
+}

package/src/dom-text-runs.js

@@ -0,0 +1,45 @@
+import {JOINING_FORMS} from './font-mesh-engine.js';
+// Color may differ: shape together, then paint the shared raster by native ranges.
+// Keeping real Text nodes allows Range to remain the placement oracle.
+export function groupDOMTextNodes(nodes,document){
+  const fields=['fontFamily','fontSize','fontWeight','fontStyle','fontStretch','fontFeatureSettings','fontVariationSettings','direction','unicodeBidi','whiteSpace','letterSpacing','wordSpacing','verticalAlign','opacity','transform','overflowX','overflowY','textDecorationLine'];
+  const groups=[];
+  for(const node of nodes){
+    const style=document.defaultView.getComputedStyle(node.parentElement),key=fields.map(k=>style[k]).join('|'),previous=groups.at(-1);
+    let adjacent=false;
+    if(previous&&previous.key===key){
+      const last=previous.nodes.at(-1),a=last.parentElement,b=node.parentElement;
+      const sameContainer=a===b||a.parentElement===b.parentElement&&style.display==='inline'&&document.defaultView.getComputedStyle(a).display==='inline';
+      if(sameContainer){const gap=document.createRange();gap.setStart(last,last.length);gap.setEnd(node,0);const fragment=gap.cloneContents();adjacent=!fragment.textContent&&!fragment.querySelector('br,hr,img,svg');}
+    }
+    if(adjacent){previous.nodes.push(node);previous.data+=node.data;}
+    else groups.push({first:node,parentElement:node.parentElement,nodes:[node],data:node.data,key});
+  }
+  return groups;
+}
+// Bounded Persian font and weight boundaries: preserve joining form without altering DOM.
+// Ligatures spanning the boundary and unknown letters stay native.
+export function prepareFontBoundaries(groups,document){
+  for(let i=1;i<groups.length;i++){
+    const a=groups[i-1],b=groups[i];
+    if(!/[\u0600-\u06ff]$/.test(a.data)||! /^[\u0600-\u06ff]/.test(b.data))continue;
+    const left=Array.from(a.data.replace(/\p{Mark}+$/u,'')).at(-1),right=Array.from(b.data)[0];
+    const x=document.defaultView.getComputedStyle(a.parentElement),y=document.defaultView.getComputedStyle(b.parentElement);
+    const ak=a.key.split('|'),bk=b.key.split('|');ak[0]=bk[0]=ak[2]=bk[2]='';
+    const range=document.createRange();range.setStart(a.nodes.at(-1),a.nodes.at(-1).length);range.setEnd(b.first,0);const gap=range.cloneContents();
+    if(ak.join('|')!==bk.join('|')||x.fontWeight===y.fontWeight&&x.fontFamily===y.fontFamily||x.display!=='inline'||y.display!=='inline'||a.parentElement.parentElement!==b.parentElement.parentElement||gap.textContent||gap.querySelector('br,hr,img,svg')||!JOINING_FORMS[left]||!JOINING_FORMS[right]||left==='ل'&&'اأإآ'.includes(right))return false;
+    if(JOINING_FORMS[left].length>2){a.joinEnd=true;b.joinStart=true;}
+  }
+  return true;
+}
+export function setRunRange(range,group,start,end){
+  let offset=0,startSet=false;
+  for(const node of group.nodes){const next=offset+node.length;
+    if(!startSet&&start<next){range.setStart(node,start-offset);startSet=true;}
+    if(startSet&&end<=next){range.setEnd(node,end-offset);return;}
+    offset=next;
+  }
+  throw RangeError('Text run range is outside its native nodes');
+}
+
+