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

package/src/dom-free.js

@@ -1,42 +1,65 @@
-import {createDOMInstallation} from './dom-attachment.js';
-import {createAutoReveal} from './dom-auto-reveal.js';
-
-export const FREE_EFFECTS = Object.freeze({textEnter:'dust-wind', textExit:'smoke', imageEnter:'drifting-snow', imageExit:'melt'});
-export function createFree(THREE, root = document, options = {}) {
-  const doc = root.nodeType === 9 ? root : root.ownerDocument;
-  const owner = createDOMInstallation(THREE, doc, {presentation: options.presentation ?? 'auto',zIndex:options.zIndex??1,documentCanvas:options.documentCanvas??options.experimentalDocumentCanvas??true});
-  let automatic, disposed=false;
-  function attach(kind, element, config = {}) {
-    if(disposed)throw Error('Free installation disposed');
-    for(const key of Object.keys(config))if(!['revealOnView','presentation'].includes(key))throw TypeError(`Unsupported Free option: ${key}`);
-    const effectKind=kind==='svg'?'image':kind;
-    const surface=owner[kind==='text'?'attachText':kind==='svg'?'attachSVG':'attachImage'](element,{
-      ...config,resting:'native',inputEffect:FREE_EFFECTS[effectKind+'Enter'],
-      inputEffectOptions:{duration:2000,particleShape:'triangle',exitEffect:FREE_EFFECTS[effectKind+'Exit']}
-    });
-    return Object.freeze({ready:surface.ready,play:(phase='enter')=>{
+import {createDOMInstallation} from './dom-attachment.js';
+import {createAutoReveal} from './dom-auto-reveal.js';
+
+export const FREE_EFFECTS = Object.freeze({textEnter:'dust-wind', textExit:'smoke', imageEnter:'drifting-snow', imageExit:'melt'});
+export function createFree(THREE, root = document, options = {}) {
+  const doc = root.nodeType === 9 ? root : root.ownerDocument;
+  const owner = createDOMInstallation(THREE, doc, {presentation: options.presentation ?? 'auto',zIndex:options.zIndex??1,documentCanvas:options.documentCanvas??options.experimentalDocumentCanvas??true});
+  let automatic, disposed=false;const installationWaits=new Set();
+  function attach(kind, element, config = {}) {
+    if(disposed)throw Error('Free installation disposed');
+    for(const key of Object.keys(config))if(!['revealOnView','presentation'].includes(key))throw TypeError(`Unsupported Free option: ${key}`);
+    const effectKind=kind==='svg'?'image':kind;
+    const surface=owner[kind==='text'?'attachText':kind==='svg'?'attachSVG':'attachImage'](element,{
+      ...config,resting:'native',inputEffect:FREE_EFFECTS[effectKind+'Enter'],
+      inputEffectOptions:{duration:2000,particleShape:'triangle',exitEffect:FREE_EFFECTS[effectKind+'Exit']}
+    });
+    let currentWait=null,requestedPlay=false;
+    const whenFinished=()=>{
+      if(currentWait)return currentWait.promise;
+      const wait={};currentWait=wait;
+      wait.promise=new Promise(resolve=>{
+      let timeoutStarted=null,timer,done=false;
+      const finish=status=>{if(done)return;done=true;clearTimeout(timer);installationWaits.delete(wait.cancel);if(currentWait===wait)currentWait=null;resolve({status});};
+      wait.cancel=()=>finish('cancelled');installationWaits.add(wait.cancel);
+      const poll=()=>{const s=surface.stats();
+        if(s.disposed||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;}
+        const completed=typeof s.completed==='boolean'?s.completed:s.mode==='native'&&['native resting presentation','hidden after exit'].includes(s.reason);
+        if((!s.reveal||s.reveal.count>0||s.reveal.manual)&&completed){finish('completed');return;}
+        // An untouched intersection reveal may legitimately wait minutes.
+        // Bound actual preparation/play, not the time before first visibility.
+        if(requestedPlay||s.timeline?.started!=null||s.preparing&&!s.suspended)timeoutStarted??=Date.now();
+        if(timeoutStarted!==null&&Date.now()-timeoutStarted>30000){finish('cancelled');return;}
+        const remaining=s.timeline?.finishAt-doc.defaultView.performance.now();
+        timer=setTimeout(poll,s.suspended?Math.min(1000,Math.max(100,remaining||1000)):16);
+      };timer=setTimeout(poll,16);
+      });return wait.promise;
+    };
+    return Object.freeze({whenFinished,ready:surface.ready,play:(phase='enter')=>{
       if(!['enter','exit'].includes(phase))throw TypeError('Invalid phase');
-      surface.play(phase);
-    },cancel:()=>surface.cancel(),refresh:()=>surface.refresh(),stats:()=>surface.stats(),destroy:()=>surface.destroy()});
-  }
-  // Automatic and manual surfaces lease the same installation.
-  const autoOwner={attachText:(el,c)=>attach('text',el,{revealOnView:c.revealOnView}),attachImage:(el,c)=>attach('image',el,{revealOnView:c.revealOnView}),stats:()=>owner.stats()};
-  try { if(options.auto!==false)automatic=createAutoReveal(THREE,root,options,autoOwner); }
-  catch(error){owner.destroy();throw error;}
-  return Object.freeze({attachText:(el,c)=>attach('text',el,c),attachImage:(el,c)=>attach('image',el,c),attachSVG:(el,c)=>attach('svg',el,c),
-    swapImage(previous,next,config={}){
-      if(disposed)throw Error('Free installation disposed');
-      for(const key of Object.keys(config))if(!['exit','waitForExit','presentation'].includes(key))throw TypeError(`Unsupported Free swap option: ${key}`);
-      for(const key of ['exit','waitForExit'])if(config[key]!==undefined&&typeof config[key]!=='boolean')throw TypeError(`Invalid ${key}`);
-      return owner.swapImage(previous,next,{presentation:config.presentation??'global',waitForExit:config.waitForExit??false,
-        exitEffect:config.exit===false?null:FREE_EFFECTS.imageExit,inputEffect:FREE_EFFECTS.imageEnter,
-        inputEffectOptions:{duration:2000,particleShape:'triangle'}});
-    },
-    refresh(){if(disposed)throw Error('Free installation disposed');automatic?.refresh();owner.refresh();},
-    stats:()=>({disposed,automatic:automatic?.stats()??null,renderer:owner.stats()}),
-    destroy(){if(disposed)return;disposed=true;try{automatic?.destroy();}finally{owner.destroy();}}
-  });
-}
+      surface.play(phase);requestedPlay=true;currentWait?.cancel();
+    },cancel:()=>{surface.cancel();requestedPlay=false;currentWait?.cancel();},refresh:()=>surface.refresh(),stats:()=>surface.stats(),destroy:()=>{currentWait?.cancel();surface.destroy();}});
+  }
+  // Automatic and manual surfaces lease the same installation.
+  const autoOwner={attachText:(el,c)=>attach('text',el,{revealOnView:c.revealOnView}),attachImage:(el,c)=>attach('image',el,{revealOnView:c.revealOnView}),stats:()=>owner.stats()};
+  try { if(options.auto!==false)automatic=createAutoReveal(THREE,root,options,autoOwner); }
+  catch(error){owner.destroy();throw error;}
+  return Object.freeze({attachText:(el,c)=>attach('text',el,c),attachImage:(el,c)=>attach('image',el,c),attachSVG:(el,c)=>attach('svg',el,c),
+    swapImage(previous,next,config={}){
+      if(disposed)throw Error('Free installation disposed');
+      for(const key of Object.keys(config))if(!['exit','enter','topImage','waitForExit','presentation'].includes(key))throw TypeError(`Unsupported Free swap option: ${key}`);
+      for(const key of ['exit','enter','waitForExit'])if(config[key]!==undefined&&typeof config[key]!=='boolean')throw TypeError(`Invalid ${key}`);
+      if(config.topImage!==undefined&&!['previous','next'].includes(config.topImage))throw TypeError('Invalid topImage');
+      return owner.swapImage(previous,next,{enterEffect:config.enter!==false,topImage:config.topImage??'next',presentation:config.presentation??'global',waitForExit:config.waitForExit??false,
+        exitEffect:config.exit===false?null:FREE_EFFECTS.imageExit,inputEffect:FREE_EFFECTS.imageEnter,
+        inputEffectOptions:{duration:2000,particleShape:'triangle'}});
+    },
+    refresh(){if(disposed)throw Error('Free installation disposed');automatic?.refresh();owner.refresh();},
+    stats:()=>({disposed,automatic:automatic?.stats()??null,renderer:owner.stats()}),
+    destroy(){if(disposed)return;disposed=true;for(const cancel of [...installationWaits])cancel();try{automatic?.destroy();}finally{owner.destroy();}}
+  });
+}
 
 
 

package/src/dom-image-surface.js

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

@@ -8,7 +8,10 @@ export function swapDOMImage(animate,previous,next,{exitEffect=null,waitForExit=
     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;
+    // 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){
@@ -20,7 +23,7 @@ export function swapDOMImage(animate,previous,next,{exitEffect=null,waitForExit=
     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;}
+  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);else next.remove();parent.style.position=parentPosition;}
   return {finished,cancel(){cancelled=true;jobs.forEach(j=>j.cancel());}};
 }
 

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')};
+}