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

package/examples/evry-website.md

@@ -0,0 +1,58 @@
+# EV-RY website: product showcase
+
+The EV-RY marketing website is a real integration case: a four-product showcase, animated captions, one shared FX installation across client-side navigation, and native content at rest.
+
+The website is currently a local integration at `http://127.0.0.1:8780/`, not a hosted demo included in this package. The public runnable examples are linked from the package README. The website backend, forms and artwork are not dependencies of FX.
+
+## Initial reveal without a flash
+
+Place `data-thd-pending` on the image and caption elements in the HTML, use the documented boot mask, then let `revealOnView` transfer the mask to the first rendered frame. Keep each returned handle until cleanup. Do not remove the mask manually on attachment readiness.
+
+```js
+const imageSurface = engine.attachImage(image, {
+  presentation: 'global',
+  revealOnView: { threshold: 0, once: true }
+});
+const captionSurfaces = captionLines.map(line => {
+  const surface = engine.attachText(line, {
+    presentation: 'local',
+    revealOnView: { threshold: 0, once: true }
+  });
+  surface.play('enter');
+  return surface;
+});
+```
+
+The captions explicitly start with the slide, even when below the viewport. `play()` takes control from automatic intersection reveal while retaining its initial paint mask until a rendered frame. It does not wait for visibility or restart on reentry. Without explicit `play()`, `revealOnView` continues to wait for the configured intersection and follows its `once` setting.
+
+## Alternate two image transitions
+
+After decoding the next mounted image, alternate between incoming snow over the previous image and outgoing melt above the already visible next image:
+
+```js
+const transition = engine.swapImage(previous, next, {
+  enter: !melt,
+  exit: melt,
+  topImage: melt ? 'previous' : 'next',
+  waitForExit: false,
+  presentation: 'global'
+});
+const result = await transition.finished;
+if (result.status === 'completed') previous.remove();
+```
+
+Use a busy flag to prevent overlapping swaps. Pause scheduling while the document is hidden. On navigation, cancel an outstanding transition, clear the scheduled timeout and destroy page handles; retain the shared engine and refresh its automatic attachments after inserting the new page. Install the boot mask before the new DOM can paint. Destroy the engine only when the application is disposed.
+
+The five-second scheduling interval, caption layout, routing and product artwork belong to the website, not to the FX API. Local caption surfaces share rendering infrastructure; the retained scratch buffer avoids resizing the GPU buffer for each caption line.
+
+Create incoming captions from fresh authored markup rather than cloning a currently attached element: a live attachment can carry temporary engine-owned visibility attributes and styles. Commit the incoming image and caption together only after `transition.finished` reports `completed`. If image decoding, attachment or the swap fails, destroy incoming caption handles, remove their layer, retain the previous caption and image, then retry. Track each acquired handle immediately so partial attachment failures can also be cleaned up.
+
+Schedule one deadline five seconds from each transition start. After completion, wait only for the remaining time. If the transition itself overruns that deadline, start one next transition when available and establish a new deadline; do not discard interval ticks or queue catch-up transitions. Returning from a hidden tab and retrying a failed transition each establish a fresh five-second wait. This keeps start-to-start cadence stable without overlapping jobs.
+
+## Completion
+
+After `surface.play()`, await `surface.whenFinished()`. It returns a status of `completed`, `cancelled`, or `unsupported`. Completion includes the native handoff; avoid fixed cleanup timers or renderer statistics. Destroy page surfaces when navigating away.
+
+Offscreen text and media retain their start time without running per-particle updates or drawing frames. Returning during the effect evaluates its current elapsed time; returning after it ends shows the final state without replay. `whenFinished()` also completes when content remains offscreen, so slider cleanup never depends on scrolling captions into view. It checks the suspended clock infrequently instead of maintaining a render loop. Concurrent waits share a pending promise; starting a new play cancels the previous wait. Cancel or destroy the handle to release an outstanding wait.
+
+When an exit is requested offscreen, the engine immediately suppresses native paint while retaining layout and the DOM content. Native paint also remains hidden if an active departure leaves view. Reentry renders only the remaining departure particles; an expired exit stays hidden. Text, image and SVG attachments own this masking, so the site should not toggle native opacity or visibility to emulate it. Cancel/destroy restores the original presentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ev-ry/fx",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.3",
   "private": false,
   "type": "module",
   "exports": {

package/src/dom-attachment.d.ts

@@ -1,5 +1,5 @@
 export interface SurfaceOptions {
-  /** Text/image/SVG only. Re-arm after complete exit. */
+  /** Text/image/SVG only. Re-arm after complete exit when once is false. Explicit play takes over automatic triggering. */
   revealOnView?: false | {threshold?: number; once?: boolean; root?: Element | null};
   resting?: 'mesh' | 'native';
   inputEffect?: string;

package/src/dom-free.d.ts

@@ -1,16 +1,16 @@
-import type {AutoRevealOptions} from './dom-auto-reveal.js';
-import type {DOMPresentation, SurfaceOptions, TextSurface, createDOMRenderer} from './dom-attachment.js';
-export const FREE_EFFECTS: Readonly<{textEnter:'dust-wind';textExit:'smoke';imageEnter:'drifting-snow';imageExit:'melt'}>;
-export type FreeSurface = Pick<TextSurface,'ready'|'play'|'refresh'|'stats'|'destroy'> & {cancel():void};
-export interface FreeAttachOptions {revealOnView?: SurfaceOptions['revealOnView'];presentation?: DOMPresentation;}
-export function createFree(THREE: Parameters<typeof createDOMRenderer>[0],root?: Document|Element,options?: AutoRevealOptions & {auto?:boolean;zIndex?:number;documentCanvas?:boolean;experimentalDocumentCanvas?:boolean}): {
-  attachText(element:HTMLElement,options?:FreeAttachOptions):FreeSurface;
-  attachImage(element:HTMLImageElement,options?:FreeAttachOptions):FreeSurface;
-  attachSVG(element:SVGSVGElement,options?:FreeAttachOptions):FreeSurface;
-  swapImage(previous:HTMLImageElement,next:HTMLImageElement,options?:{exit?:boolean;waitForExit?:boolean;presentation?:DOMPresentation}):{finished:Promise<{status:string}>;cancel():void};
-  refresh():void;
-  stats():{disposed:boolean;automatic:unknown;renderer:unknown};
-  destroy():void;
-};
+import type {AutoRevealOptions} from './dom-auto-reveal.js';
+import type {DOMPresentation, SurfaceOptions, TextSurface, createDOMRenderer} from './dom-attachment.js';
+export const FREE_EFFECTS: Readonly<{textEnter:'dust-wind';textExit:'smoke';imageEnter:'drifting-snow';imageExit:'melt'}>;
+export type FreeSurface = Pick<TextSurface,'ready'|'play'|'refresh'|'stats'|'destroy'> & {cancel():void;whenFinished():Promise<{status:'completed'|'cancelled'|'unsupported'}>};
+export interface FreeAttachOptions {revealOnView?: SurfaceOptions['revealOnView'];presentation?: DOMPresentation;}
+export function createFree(THREE: Parameters<typeof createDOMRenderer>[0],root?: Document|Element,options?: AutoRevealOptions & {auto?:boolean;zIndex?:number;documentCanvas?:boolean;experimentalDocumentCanvas?:boolean}): {
+  attachText(element:HTMLElement,options?:FreeAttachOptions):FreeSurface;
+  attachImage(element:HTMLImageElement,options?:FreeAttachOptions):FreeSurface;
+  attachSVG(element:SVGSVGElement,options?:FreeAttachOptions):FreeSurface;
+  swapImage(previous:HTMLImageElement,next:HTMLImageElement,options?:{exit?:boolean;enter?:boolean;topImage?:'previous'|'next';waitForExit?:boolean;presentation?:DOMPresentation}):{finished:Promise<{status:string}>;cancel():void};
+  refresh():void;
+  stats():{disposed:boolean;automatic:unknown;renderer:unknown};
+  destroy():void;
+};
 
 

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

@@ -13,6 +13,20 @@ export async function rasterizeDOMImage(element,{maxSide=2048}={}){
     return {x:read(parts[0],box.width),y:read(parts[1]??parts[0],box.height)};
   });
   context.beginPath();context.roundRect(0,0,box.width,box.height,radii);context.clip();
+  // Bake ancestor overflow masks into the texture; moving particles keep the
+  // final image silhouette rather than snapping to a rounded frame at rest.
+  for(let parent=element.parentElement;parent;parent=parent.parentElement){
+    const style=doc.defaultView.getComputedStyle(parent);
+    if(!['hidden','clip','auto','scroll'].includes(style.overflowX)||!['hidden','clip','auto','scroll'].includes(style.overflowY))continue;
+    const rect=parent.getBoundingClientRect();
+    if(style.transform!=='none')continue;
+    const left=parseFloat(style.borderLeftWidth)||0,top=parseFloat(style.borderTopWidth)||0;
+    const right=parseFloat(style.borderRightWidth)||0,bottom=parseFloat(style.borderBottomWidth)||0;
+    const corners=['borderTopLeftRadius','borderTopRightRadius','borderBottomRightRadius','borderBottomLeftRadius'];
+    const borders=[[left,top],[right,top],[right,bottom],[left,bottom]];
+    const clipRadii=corners.map((key,i)=>{const parts=style[key].split(/\s+/);const read=(s,n)=>parseFloat(s)*(s.endsWith('%')?n/100:1);return {x:Math.max(0,read(parts[0],rect.width)-borders[i][0]),y:Math.max(0,read(parts[1]??parts[0],rect.height)-borders[i][1])};});
+    context.beginPath();context.roundRect(rect.left-box.left+left,rect.top-box.top+top,Math.max(0,rect.width-left-right),Math.max(0,rect.height-top-bottom),clipRadii);context.clip();
+  }
   const factor=css.objectFit==='cover'?Math.max(box.width/element.naturalWidth,box.height/element.naturalHeight):Math.min(box.width/element.naturalWidth,box.height/element.naturalHeight);
   const w=css.objectFit==='fill'?box.width:element.naturalWidth*factor,h=css.objectFit==='fill'?box.height:element.naturalHeight*factor;
   context.drawImage(element,(box.width-w)/2,(box.height-h)/2,w,h);

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());}};
 }