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

package/src/dom-image-surface.js

@@ -1,106 +1,166 @@
-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();}}
+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;
+  let originalOpacity=element.style.opacity,ownedOpacity=null;
+  const nativeRestOpacity=options.nativeRestOpacity??(originalOpacity===''?1:Number(originalOpacity)),originalPosition=parent.style.position;
+  function captureHostOpacity(){
+    if(ownedOpacity===null||element.style.opacity!==ownedOpacity)originalOpacity=element.style.opacity;
+  }
+  function writeOpacity(value){captureHostOpacity();element.style.opacity=value;ownedOpacity=element.style.opacity;}
+  function restoreOpacity(){
+    captureHostOpacity();
+    if(ownedOpacity!==null&&element.style.opacity===ownedOpacity)element.style.opacity=originalOpacity;
+    ownedOpacity=null;
   }
-  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 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 effectStarted=null,queuedStarted=null,inViewport=true,exitHeld=false,nativeHidden=false;
+  let queuedPhase=options.initialPhase??null;
+  const ready=new Promise(r=>resolve=r),reduced=window.matchMedia('(prefers-reduced-motion: reduce)');
+  function native(error,restore=false){
+    if(restore)exitHeld=false;
+    const hidden=!disposed&&!restore&&(exitHeld||surface?.stats().state==='hidden');
+    nativeHidden=hidden;mode='native';reason=error||null;
+    if(disposed)restoreOpacity();
+    else{captureHostOpacity();writeOpacity(hidden?'0':(options.nativeRestOpacity!==undefined?String(nativeRestOpacity):originalOpacity));}
+    canvas.style.display='none';options.onPresentation?.({mode,reason,hidden});renderer.invalidate?.();
   }
-  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'});}
-  };
-}
+  function holdExit(){exitHeld=true;nativeHidden=true;writeOpacity('0');options.onPresentation?.({mode,reason,hidden:true});}
+  function suspend(){
+    if(queuedPhase!==null&&queuedStarted===null)queuedStarted=window.performance.now();
+    if(queuedPhase==='exit'||queuedPhase===null&&phase==='exit'&&effectStarted!==null)holdExit();
+    if(frame!==null)window.cancelAnimationFrame(frame);frame=null;canvas.style.display='none';renderer.invalidate?.();
+  }
+  function request(){if(!disposed&&inViewport&&!document.hidden&&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;if(!inViewport||document.hidden){suspend();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',true);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;effectStarted=queuedStarted??now;queuedStarted=null;if(phase==='exit'&&surface.stats().state==='entering')surface.frame(effectStarted,reduced.matches);surface.setPresentationOpacity(1);surface[queuedPhase](effectStarted);queuedPhase=null;}surface.frame(now,reduced.matches);
+    const state=surface.stats();
+    const handoff=options.resting==='native'&&phase==='enter'&&effectStarted!==null&&!reduced.matches;
+    const end=effectStarted===null?now:effectStarted+state.duration;
+    // Reveal complete native pixels only once assembly finishes.
+    const nativeAlpha=handoff&&now>=end?1:0;
+    const meshFade=handoff?Math.max(0,Math.min(1,(now-end)/250)):0;
+    surface.setPresentationOpacity(1-meshFade);
+    if(!state.active&&(options.resting==='native'||reduced.matches)&&(!handoff||meshFade>=1)){
+      // 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')writeOpacity('0');
+      resolve({mode,reason});return;
+    }
+    const handingOffNative=mode==='native';
+    writeOpacity(String(nativeAlpha*nativeRestOpacity));nativeHidden=nativeAlpha===0;mode='mesh';reason=null;renderer.render(scene,camera);
+    options.onPresentation?.({mode,reason,hidden:nativeHidden});
+    if(handingOffNative)renderer.flushPresentation?.();
+    resolve({mode,reason});if(handoff&&meshFade<1)request();
+  }catch(error){native(error.message,true);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);
+        // DOM source/paint changes replace pixels, not the caller's animation
+        // intent. Keep a departure hidden and preserve an active clock/seed
+        // across src, srcset and SVG snapshot replacements just as on resize.
+        await next.setSource(raster.source,{preserveMotion:!!surface,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,true);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 visibility=new window.IntersectionObserver(entries=>{
+    inViewport=entries.at(-1)?.isIntersecting!==false;
+    if(inViewport){refresh();request();}
+    else suspend();
+  });visibility.observe(element);
+  const onVisibility=()=>{if(document.hidden)suspend();else{refresh();request();}};
+  document.addEventListener('visibilitychange',onVisibility);
+  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);
+  if(queuedPhase!==null){const box=element.getBoundingClientRect();if(document.hidden||box.bottom<=0||box.top>=window.innerHeight||box.right<=0||box.left>=window.innerWidth){inViewport=false;suspend();}}
+  refresh();
+  return {element,ready,refresh,cancel(){if(disposed)return;phase='enter';effectStarted=null;queuedPhase=null;queuedStarted=null;exitHeld=false;surface?.setPresentationOpacity(1);surface?.show();native();request();},play(value='enter'){
+      if(disposed)throw Error('Surface disposed');
+      if(!['enter','exit'].includes(value))throw TypeError('Expected enter or exit');
+      phase=value;queuedPhase=value;exitHeld=false;
+      const box=element.getBoundingClientRect(),outside=box.bottom<=0||box.top>=window.innerHeight||box.right<=0||box.left>=window.innerWidth;
+      queuedStarted=document.hidden||!inViewport||outside?window.performance.now():null;
+      if(outside)inViewport=false;
+      if(document.hidden||!inViewport)suspend();
+      request();
+    },
+    update(next={}){const candidate={...options,...next};validate(candidate);options=candidate;surface?.setEffect(options.inputEffect??'dust-wind',options.inputEffectOptions??{});request();},
+    stats:()=>{
+      const image=surface?.stats(),started=queuedPhase!==null?queuedStarted:effectStarted,currentPhase=queuedPhase??phase;
+      const duration=image?.duration??options.inputEffectOptions?.duration??2000;
+      const finishAt=started===null?null:started+(reduced.matches?0:duration+(currentPhase==='enter'&&options.resting==='native'?250:0));
+      const suspended=document.hidden||!inViewport;
+      const unsupported=failed||reason==='Unsupported image layout';
+      const completed=!unsupported&&started!==null&&(suspended?window.performance.now()>=finishAt:
+        queuedPhase===null&&(currentPhase==='exit'?image?.state==='hidden':options.resting==='native'?mode==='native'&&reason==='native resting presentation':image?.state==='visible'&&!image.active));
+      return {disposed,mode,reason,phase:currentPhase,preparing,suspended,completed,hidden:exitHeld||nativeHidden,timeline:{phase:currentPhase,started,ends:started===null?null:started+duration,finishAt},handoff:mode==='mesh'&&options.resting==='native'&&phase==='enter'&&effectStarted!==null,image};
+    },
+    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();visibility.disconnect();document.removeEventListener('visibilitychange',onVisibility);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

@@ -1,27 +1,33 @@
-// 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'};
+// 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,settled=false,rolledBack=false,jobs=[];const parent=previous.parentElement,origin=next.parentNode,sibling=next.nextSibling,css=next.style.cssText,parentPosition=parent.style.position;
+  let resolveCancellation;
+  const cancellation=new Promise(resolve=>{resolveCancellation=resolve;});
+  const operation=(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.
+    // A departing previous image can use the shared canvas above the native
+    // next image. Forcing local here clips particles to the rounded host.
+    const departingOverNative=!enterEffect&&topImage==='previous';
+    const layerOptions=!departingOverNative&&(!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());}};
-}
+  const finished=Promise.race([operation,cancellation]).then(result=>{settled=true;return result;},error=>{settled=true;throw error;});
+  function rollback(){if(rolledBack)return;rolledBack=true;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);else next.remove();parent.style.position=parentPosition;}
+  return {finished,cancel(){if(settled||cancelled)return;cancelled=true;jobs.forEach(j=>j.cancel());rollback();resolveCancellation({status:'cancelled'});}};
+}
 
 

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-raster-cache.js

@@ -1,33 +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;
-}
+// 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;
+}