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

package/src/dom-once.js

@@ -1,34 +1,39 @@
-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')};
-}
+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 imageEntry=element.tagName==='IMG'&&phase==='enter';
+  const nativeRestOpacity=imageEntry?Number(element.ownerDocument.defaultView.getComputedStyle(element).opacity):1;
+  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:imageEntry?'native':'mesh',...(imageEntry?{nativeRestOpacity}:{}),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 view=element.ownerDocument.defaultView,started=view.performance.now();
+  // Completion belongs to the effect clock, not to the first visible frame.
+  // A hidden transient may finish without ever preparing a mesh or resolving
+  // visual readiness; visibility only changes how often we inspect its clock.
+  function poll(){
+    if(done)return;
+    const s=surface.stats();
+    if(s.disposed||!element.isConnected){finish('cancelled');return;}
+    if(!s.preparing&&s.mode==='native'&&s.reason&&!/initializing|not visible|not connected|native resting presentation|hidden after exit/i.test(s.reason)){finish('unsupported');return;}
+    if(s.completed===true){finish('completed');return;}
+    if(view.performance.now()-started>30000){finish('cancelled',Error('Animation preparation timed out'));return;}
+    const remaining=s.timeline?.finishAt-view.performance.now();
+    timer=setTimeout(poll,s.suspended?Math.min(1000,Math.max(100,remaining||1000)):16);
+  }
+  timer=setTimeout(poll,16);
+  surface.ready.then(()=>{if(!done){clearTimeout(timer);poll();}},error=>finish('cancelled',error));
+  return {finished,cancel:()=>finish('cancelled')};
+}

package/src/dom-reveal.js

@@ -1,75 +1,85 @@
-// 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;
+// 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,manual=false;let basePlay;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(manual||running)surface.refresh();else basePlay('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);basePlay=surface.play.bind(surface);
+    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(!manual&&(!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,manual}});
+  // Explicit play owns its clock even before the first intersection. Retain the
+  // initial paint mask, but never let automatic entry restart that request.
+  surface.play=(phase='enter')=>{
+    if(disposed)throw Error('Surface disposed');
+    if(!['enter','exit'].includes(phase))throw TypeError('Expected enter or exit');
+    manual=true;armed=false;clearTimeout(retry);retry=null;
+    revealPending=held;basePlay(phase);
+  };
+  const cancel=surface.cancel?.bind(surface);
+  surface.cancel=()=>{if(disposed)return;manual=true;armed=false;revealPending=false;unmask();cancel?.();};
+  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

@@ -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;