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

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-svg-surface.js

@@ -1,42 +1,44 @@
-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'});}};
+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;
+    // The image adapter exposes native pixels before its settled mesh finishes
+    // fading. An explicit hidden:false must win over the remaining mesh mode.
+    if(state.hidden??(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;if(!surface)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){xml='';surface?.destroy();surface=null;restore();reason=error.message;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-paint-mask.js

@@ -0,0 +1,24 @@
+// Hide native text without hiding the canvas or changing layout/raster colors.
+// This temporary owner covers cold rich text before its measured runs exist.
+export function createTextPaintMask(element,canvas){
+  const document=element.ownerDocument,window=document.defaultView,styles=new Map();
+  function hold(){
+    const parents=new Set(),walker=document.createTreeWalker(element,window.NodeFilter.SHOW_TEXT);
+    while(walker.nextNode())if(walker.currentNode.data.trim()&&!canvas?.contains(walker.currentNode))parents.add(walker.currentNode.parentElement);
+    for(const node of parents){
+      let values=styles.get(node);if(!values){values=new Map();styles.set(node,values);}
+      for(const [name,value] of [['-webkit-text-fill-color','transparent'],['text-shadow','none']]){
+        if(!values.has(name))values.set(name,[node.style.getPropertyValue(name),node.style.getPropertyPriority(name),value]);
+        if(node.style.getPropertyValue(name)!==value||node.style.getPropertyPriority(name)!=='important')node.style.setProperty(name,value,'important');
+      }
+    }
+  }
+  function release(){
+    for(const [node,values] of styles)for(const [name,[original,priority,owned]] of values){
+      if(node.style.getPropertyValue(name)!==owned||node.style.getPropertyPriority(name)!=='important')continue;
+      if(original)node.style.setProperty(name,original,priority);else node.style.removeProperty(name);
+    }
+    styles.clear();
+  }
+  return {hold,release};
+}

package/src/dom-text-surface.js

@@ -7,7 +7,8 @@ import {textEditMotions} from './text-edit-motions.js';
 import {normalizeTextEffectOptions} from './text-effect-options.js';
 import {adoptDOMFont,domFontAtSize,matchesDOMFont} from './dom-surface-font.js';
 import {DOMRichText} from './dom-rich-text.js';
-import {createDOMTextFingerprint} from './dom-text-fingerprint.js';
+import {createDOMTextFingerprint} from './dom-text-fingerprint.js';
+import {createTextPaintMask} from './dom-text-paint-mask.js';
 
 // Presentation attachment: the original text node, parent control and semantics
 // remain owned by the host. The deliberately narrow first contract is a plain,
@@ -24,7 +25,8 @@ export function attachTextSurface(element,THREE,options={}){
   let enabled=options.enabled!==false,renderer,canvas,engine,view,effect,scene,content,camera;
   let frame=null,revision=0,preparing=false,dirty=true,layout=null,committed=null,reason=null,fatal=false,intersecting=true;
   let mode='native',draws=0,builds=0,submittedSize='',pendingPhase=options.initialPhase??null,phase='enter',lastSeed=null;
-  let effectStarted=null,pendingStarted=null,settleStarted=null;
+  let effectStarted=null,pendingStarted=null,settleStarted=null;
+  let nativeMask;
   function preserveMotion(){if(pendingPhase===null&&effectStarted!==null&&window.performance.now()-effectStarted<settings.duration){pendingPhase=phase;pendingStarted=effectStarted;}}
   let resolveReady;const ready=new Promise(resolve=>{resolveReady=resolve;});
   let rich=null;
@@ -44,9 +46,12 @@ export function attachTextSurface(element,THREE,options={}){
     }
     ownedStyle.delete(name);originalStyle.delete(name);
   }
-  function native(why=null){
+  function exitOwnsPaint(why=reason){return (pendingPhase??phase)==='exit'&&!fatal&&enabled&&!forced.matches&&(!why||/not visible|not connected|native resting presentation|hidden after exit/i.test(why));}
+  function native(why=null){
+    nativeMask?.release();
     rich?.restore();
-    mode='native';reason=why;restoreStyle('-webkit-text-fill-color');restoreStyle('text-shadow');
+    mode='native';reason=why;restoreStyle('-webkit-text-fill-color');restoreStyle('text-shadow');
+    if(exitOwnsPaint(why))nativeMask?.hold();
     if(canvas)canvas.style.display='none';
     renderer?.invalidate?.();
   }
@@ -56,10 +61,27 @@ export function attachTextSurface(element,THREE,options={}){
     resolveReady({mode,reason});
   }
   function request(){if(!life.disposed&&!fatal&&!document.hidden&&intersecting&&frame===null)frame=window.requestAnimationFrame(render);}
-  function suspend(){if(frame!==null)window.cancelAnimationFrame(frame);frame=null;if(renderer?.globalCanvas)native('not visible');renderer?.invalidate?.();}
-  function refresh(){
-    if(life.disposed)return;revision++;dirty=true;request();
-  }
+  function suspend(){
+    if(pendingPhase!==null&&pendingStarted===null)pendingStarted=window.performance.now();
+    if(frame!==null)window.cancelAnimationFrame(frame);frame=null;
+    const hideExit=exitOwnsPaint();
+    // The last canvas frame and restored native text must not flash on reentry.
+    // A queued/current exit owns native paint even while no frames are drawn.
+    if(renderer?.globalCanvas||hideExit)native(reason??'not visible');
+    if(canvas)canvas.style.display='none';renderer?.invalidate?.();
+  }
+  function refresh(){
+    if(life.disposed)return;revision++;dirty=true;request();
+  }
+  function play(next='enter'){
+    if(life.disposed)throw Error('Text surface disposed');if(!['enter','exit'].includes(next))throw TypeError('Expected enter or exit');
+    pendingPhase=next;if(next==='enter')lastSeed=null;const box=element.getBoundingClientRect();
+    const outside=box.bottom<=0||box.top>=window.innerHeight||box.right<=0||box.left>=window.innerWidth;
+    pendingStarted=document.hidden||!intersecting||outside?window.performance.now():null;
+    // Do not spend a cold preparation frame waiting for IO's first delivery.
+    if(outside&&window.IntersectionObserver)intersecting=false;
+    if(document.hidden||!intersecting)suspend();refresh();
+  }
   function slot(){
     const children=[...element.childNodes].filter(node=>node!==canvas&&node.nodeType!==8);
     if(children.some(node=>node.nodeType!==3)||children.length>1)return null;
@@ -177,26 +199,32 @@ export function attachTextSurface(element,THREE,options={}){
       view.uniforms.tint.value.setStyle(window.getComputedStyle(element).color);
       beginEffect(now);const active=rich?rich.step(now,reduced.matches):effect.step(now,reduced.matches);
       if(!active&&phase==='exit')content.visible=false;
-      let nativeAlpha=0,meshFade=0;
-      if(active&&phase!=='exit'&&resting==='native'&&effectStarted!==null)
-        nativeAlpha=Math.max(0,Math.min(1,(now-(effectStarted+settings.duration-175))/350));
-      if(!active&&phase!=='exit'&&resting==='native'){
-        // Use the effect clock, not the first idle frame. Slow frames must not
-        // restart the handoff or jump native alpha back to its halfway point.
+      let nativeAlpha=0,meshFade=0;
+      if(active&&phase!=='exit'&&resting==='native'&&effectStarted!==null)
+        nativeAlpha=Math.max(0,Math.min(1,(now-(effectStarted+settings.duration-175))/350));
+      if(!active&&phase!=='exit'&&resting==='native'){
+        // Use the effect clock, not the first idle frame. Slow frames must not
+        // restart the handoff or jump native alpha back to its halfway point.
+        // Cancellation/settings refresh have no entry clock. Keep their
+        // restored native paint instead of beginning a second handoff.
+        const instant=effectStarted===null||effectName==='none'||reduced.matches;
         if(settleStarted===null)settleStarted=effectStarted===null?now:effectStarted+settings.duration;
-        meshFade=reduced.matches?1:Math.min(1,(now-settleStarted)/350);
-        nativeAlpha=reduced.matches?1:Math.min(1,(now-settleStarted+175)/350);
-        if(meshFade>=1){renderer.render(scene,camera);native('native resting presentation');resolveReady({mode,reason});return;}
+        meshFade=instant?1:Math.min(1,(now-settleStarted)/350);
+        nativeAlpha=instant?1:Math.min(1,(now-settleStarted+175)/350);
+        if(meshFade>=1){renderer.render(scene,camera);native('native resting presentation');resolveReady({mode,reason});return;}
       }else settleStarted=null;
-      view.uniforms.presentationOpacity.value=1-meshFade;rich?.setPresentationOpacity(1-meshFade);
-      const handingOffNative=mode==='native';
-      renderer.render(scene,camera);draws++;
+      view.uniforms.presentationOpacity.value=1-meshFade;rich?.setPresentationOpacity(1-meshFade);
+      const handingOffNative=mode==='native';
+      renderer.render(scene,camera);draws++;
+      // Transfer temporary offscreen ownership to the regular mesh paint mask
+      // in the same task, before the browser can paint native glyphs.
+      nativeMask?.release();
       canvas.style.display='block';if(!rich)ownStyle('-webkit-text-fill-color',nativeAlpha>0?`color-mix(in srgb, ${window.getComputedStyle(element).color} ${nativeAlpha*100}%, transparent)`:'transparent');ownStyle('text-shadow','none');mode='mesh';reason=null;
       rich?.hide(nativeAlpha);
       // Commit the shared canvas before the browser paints hidden native text.
       if(handingOffNative)renderer.flushPresentation?.();
       renderer.invalidate?.();
-      resolveReady({mode,reason});if(active||meshFade<1&&settleStarted!==null)request();
+      resolveReady({mode,reason});if(active||meshFade<1&&settleStarted!==null)request();
     }catch(error){fail(error);}
   }
   life.own(()=>{if(frame!==null)window.cancelAnimationFrame(frame);frame=null;});
@@ -204,7 +232,8 @@ export function attachTextSurface(element,THREE,options={}){
   try{
     renderer=new THREE.WebGLRenderer({antialias:true,alpha:true});life.own(()=>{renderer.dispose();renderer.forceContextLoss();});
     renderer.setSurface?.(element,{escapeHost:element.closest('button,a,[role="button"]')||element});
-    canvas=renderer.domElement;canvas.setAttribute('aria-hidden','true');canvas.setAttribute('data-thd-text-surface','');
+    canvas=renderer.domElement;canvas.setAttribute('aria-hidden','true');canvas.setAttribute('data-thd-text-surface','');
+    nativeMask=createTextPaintMask(element,canvas);life.own(()=>nativeMask.release());
     fingerprint=createDOMTextFingerprint(element,canvas);
     Object.assign(canvas.style,{position:'absolute',pointerEvents:'none',display:'none',margin:'0',padding:'0',border:'0',maxWidth:'none',maxHeight:'none'});
     element.append(canvas);life.own(()=>canvas.remove());
@@ -237,8 +266,8 @@ export function attachTextSurface(element,THREE,options={}){
     life.listen(window,'resize',refresh);
     for(const event of ['loadingdone','loadingerror'])life.listen(document.fonts,event,()=>{fontRevision++;refresh();});
     life.listen(forced,'change',()=>{native();refresh();});life.listen(reduced,'change',refresh);
-    request();
-  }catch(error){fail(error);}
+    if(pendingPhase!==null)play(pendingPhase);else request();
+  }catch(error){fail(error);}
   return {element,ready,
     refresh,
     update(next={}){
@@ -247,15 +276,17 @@ export function attachTextSurface(element,THREE,options={}){
       validResting(next.resting??resting);resting=next.resting??resting;
       const normalized=normalizeTextEffectOptions(next.inputEffectOptions?{formation:-1,...next.inputEffectOptions}:settings,candidate==='none'?'dust-wind':candidate);
       effectName=candidate;settings=normalized;if('enabled' in next)enabled=next.enabled!==false;
-      effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;refresh();
-    },
-    cancel(){if(life.disposed)return;effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;refresh();},
-    play(next='enter'){
-      if(life.disposed)throw Error('Text surface disposed');if(!['enter','exit'].includes(next))throw TypeError('Expected enter or exit');
-      pendingPhase=next;pendingStarted=null;refresh();
+      effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;native();refresh();
     },
-    stats:()=>({timeline:{phase,started:effectStarted,ends:effectStarted===null?null:effectStarted+settings.duration},disposed:life.disposed,mode,reason,committed,preparing,draws,builds,pending:frame!==null,suspended:document.hidden||!intersecting,triangles:rich?rich.stats().triangles:view?.triangleCount??0,
-      width:layout?.width??0,height:layout?.height??0,fontFamily:engine?.face?.family,displayFontSize:layout?.size,divisions:engine?.divisions,effect:effect?.stats(),rich:rich?.stats()??null}),
+    cancel(){if(life.disposed)return;effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;native();refresh();},
+    play,
+    stats:()=>{const started=pendingPhase!==null?pendingStarted:effectStarted,currentPhase=pendingPhase??phase;
+      const duration=reduced.matches||effectName==='none'?0:settings.duration;
+      const finishAt=started===null?null:started+(duration===0?0:duration+(currentPhase==='enter'&&resting==='native'?350:0));
+      const suspended=document.hidden||!intersecting;
+      const completed=started!==null&&(suspended?window.performance.now()>=finishAt:pendingPhase===null&&(currentPhase==='exit'?content?.visible===false:resting==='mesh'?mode==='mesh'&&!(rich?rich.stats().active:effect?.active):mode==='native'&&reason==='native resting presentation'));
+      return {completed,timeline:{phase:currentPhase,started,ends:started===null?null:started+duration,finishAt},disposed:life.disposed,mode,reason,committed,preparing,draws,builds,pending:frame!==null,suspended:document.hidden||!intersecting,triangles:rich?rich.stats().triangles:view?.triangleCount??0,
+      width:layout?.width??0,height:layout?.height??0,fontFamily:engine?.face?.family,displayFontSize:layout?.size,divisions:engine?.divisions,effect:effect?.stats(),rich:rich?.stats()??null};},
     destroy(){if(life.disposed)return;native('destroyed');resolveReady({mode,reason});life.destroy();}
   };
 }