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

package/src/dom-attachment.d.ts

@@ -1,75 +1,75 @@
-export interface SurfaceOptions {
-  /** 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;
-  inputEffectOptions?: {
-    particleShape?: 'triangle' | 'square';
-    duration?: number;
-    exitEffect?: string;
-    formation?: number;
-    chaos?: number;
-    motion?: number;
-    horizontal?: number;
-    vertical?: number;
-    flipX?: boolean;
-    flipY?: boolean;
-    exitFlipX?: boolean;
-    exitFlipY?: boolean;
-    bounceLines?: boolean;
-    seed?: number;
-    recipe?: Record<string, number | boolean | string>;
-  };
-  divisions?: 'auto' | number;
-}
-export interface SurfaceState {
-  disposed: boolean;
-  mode: string;
-  reason?: string | null;
-  committed?: string | null;
-  [key: string]: unknown;
-}
-export interface Surface {
-  element: HTMLElement;
-  ready: Promise<{mode: string; reason?: string | null}>;
-  refresh(): void;
-  update(options: Pick<SurfaceOptions, 'inputEffect' | 'inputEffectOptions' | 'resting'>): void;
-  stats(): SurfaceState;
-  destroy(): void;
-}
-export interface TextSurface extends Surface { cancel?(): void; play(phase?: 'enter' | 'exit'): void; }
-export type DOMPresentation = 'local' | 'global' | 'auto';
-export interface DOMInstallation {
-  swapImage(previous: HTMLImageElement, next: HTMLImageElement, options?: SurfaceOptions & {exitEffect?: string | null; waitForExit?: boolean; enterEffect?: boolean; topImage?: 'previous' | 'next'; presentation?: DOMPresentation}): {finished: Promise<{status: string}>; cancel(): void};
-  attachSVG(element: SVGSVGElement, options?: SurfaceOptions & {presentation?: DOMPresentation}): Omit<TextSurface, 'element'> & {element: SVGSVGElement};
-  animateOnce(element: HTMLElement, options?: SurfaceOptions & {phase?: 'enter' | 'exit'; presentation?: DOMPresentation; layer?: string}): {finished: Promise<{status: string; phase: string}>; cancel(): void};
-  attachImage(element: HTMLImageElement, options?: SurfaceOptions & {presentation?: DOMPresentation; layer?: string}): TextSurface;
-  attachInput(element: HTMLInputElement | HTMLTextAreaElement, options?: SurfaceOptions & {host?: HTMLElement; presentation?: DOMPresentation; layer?: string}): Surface;
-  attachText(element: HTMLElement, options?: SurfaceOptions & {presentation?: DOMPresentation; layer?: string}): TextSurface;
-  registerLayer(name: string, options: {root: HTMLDialogElement; zIndex?: number}): void;
-  unregisterLayer(name: string): void;
-  /** Manual transfer preserving the native editor, scene and effect timeline. */
-  transfer(surface: Surface, destination?: {presentation?: DOMPresentation; layer?: string | null}): void;
-  routing(surface: Surface): {requested: DOMPresentation; presentation: 'local' | 'global'; layer: string | null; reason: string; pending: boolean; error: string | null};
-  refresh(): void;
-  stats(): {disposed: boolean; controls: number; contexts: number; copies: number; owners: Partial<Record<string, ReturnType<DOMRenderer['stats']>>>};
-  destroy(): void;
-}
-/** Explicit or bounded automatic routing; existing native editors remain owned by the host. */
-export function createDOMInstallation(THREE: Parameters<typeof createDOMRenderer>[0], document: Document, options?: {presentation?: DOMPresentation; documentCanvas?: boolean; escapeEffects?: boolean; zIndex?: number}): DOMInstallation;
-export interface DOMRenderer {
-  attachSVG(element: SVGSVGElement, options?: SurfaceOptions): Omit<TextSurface, 'element'> & {element: SVGSVGElement};
-  attachImage(element: HTMLImageElement, options?: SurfaceOptions): TextSurface;
-  readonly domElement: HTMLCanvasElement | null;
-  /** Refresh all attached surfaces after external layout/value changes. */
-  refresh(): void;
-  attachText(element: HTMLElement, options?: SurfaceOptions): TextSurface;
-  attachInput(element: HTMLInputElement | HTMLTextAreaElement, options?: SurfaceOptions & {host?: HTMLElement}): Surface;
-  stats(): {disposed: boolean; lost: boolean; contexts: number; controls: number; leases: number; [key: string]: unknown};
-  destroy(): void;
-}
-/** THREE is injected: the host retains its existing Three.js dependency. */
-export function createDOMRenderer(THREE: {WebGLRenderer: new (...args: any[]) => any; [key: string]: any}, document: Document, options?: {presentation?: 'local' | 'viewport'; escapeEffects?: boolean; zIndex?: number; root?: HTMLDialogElement}): DOMRenderer;
+export interface SurfaceOptions {
+  /** 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;
+  inputEffectOptions?: {
+    particleShape?: 'triangle' | 'square';
+    duration?: number;
+    exitEffect?: string;
+    formation?: number;
+    chaos?: number;
+    motion?: number;
+    horizontal?: number;
+    vertical?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    exitFlipX?: boolean;
+    exitFlipY?: boolean;
+    bounceLines?: boolean;
+    seed?: number;
+    recipe?: Record<string, number | boolean | string>;
+  };
+  divisions?: 'auto' | number;
+}
+export interface SurfaceState {
+  disposed: boolean;
+  mode: string;
+  reason?: string | null;
+  committed?: string | null;
+  [key: string]: unknown;
+}
+export interface Surface {
+  element: HTMLElement;
+  ready: Promise<{mode: string; reason?: string | null}>;
+  refresh(): void;
+  update(options: Pick<SurfaceOptions, 'inputEffect' | 'inputEffectOptions' | 'resting'>): void;
+  stats(): SurfaceState;
+  destroy(): void;
+}
+export interface TextSurface extends Surface { cancel?(): void; play(phase?: 'enter' | 'exit'): void; }
+export type DOMPresentation = 'local' | 'global' | 'auto';
+export interface DOMInstallation {
+  swapImage(previous: HTMLImageElement, next: HTMLImageElement, options?: SurfaceOptions & {exitEffect?: string | null; waitForExit?: boolean; enterEffect?: boolean; topImage?: 'previous' | 'next'; presentation?: DOMPresentation}): {finished: Promise<{status: string}>; cancel(): void};
+  attachSVG(element: SVGSVGElement, options?: SurfaceOptions & {presentation?: DOMPresentation}): Omit<TextSurface, 'element'> & {element: SVGSVGElement};
+  animateOnce(element: HTMLElement, options?: SurfaceOptions & {phase?: 'enter' | 'exit'; presentation?: DOMPresentation; layer?: string}): {finished: Promise<{status: string; phase: string}>; cancel(): void};
+  attachImage(element: HTMLImageElement, options?: SurfaceOptions & {presentation?: DOMPresentation; layer?: string}): TextSurface;
+  attachInput(element: HTMLInputElement | HTMLTextAreaElement, options?: SurfaceOptions & {host?: HTMLElement; presentation?: DOMPresentation; layer?: string}): Surface;
+  attachText(element: HTMLElement, options?: SurfaceOptions & {presentation?: DOMPresentation; layer?: string}): TextSurface;
+  registerLayer(name: string, options: {root: HTMLDialogElement; zIndex?: number}): void;
+  unregisterLayer(name: string): void;
+  /** Manual transfer preserving the native editor, scene and effect timeline. */
+  transfer(surface: Surface, destination?: {presentation?: DOMPresentation; layer?: string | null}): void;
+  routing(surface: Surface): {requested: DOMPresentation; presentation: 'local' | 'global'; layer: string | null; reason: string; pending: boolean; error: string | null};
+  refresh(): void;
+  stats(): {disposed: boolean; controls: number; contexts: number; copies: number; owners: Partial<Record<string, ReturnType<DOMRenderer['stats']>>>};
+  destroy(): void;
+}
+/** Explicit or bounded automatic routing; existing native editors remain owned by the host. */
+export function createDOMInstallation(THREE: Parameters<typeof createDOMRenderer>[0], document: Document, options?: {presentation?: DOMPresentation; documentCanvas?: boolean; escapeEffects?: boolean; zIndex?: number}): DOMInstallation;
+export interface DOMRenderer {
+  attachSVG(element: SVGSVGElement, options?: SurfaceOptions): Omit<TextSurface, 'element'> & {element: SVGSVGElement};
+  attachImage(element: HTMLImageElement, options?: SurfaceOptions): TextSurface;
+  readonly domElement: HTMLCanvasElement | null;
+  /** Refresh all attached surfaces after external layout/value changes. */
+  refresh(): void;
+  attachText(element: HTMLElement, options?: SurfaceOptions): TextSurface;
+  attachInput(element: HTMLInputElement | HTMLTextAreaElement, options?: SurfaceOptions & {host?: HTMLElement}): Surface;
+  stats(): {disposed: boolean; lost: boolean; contexts: number; controls: number; leases: number; [key: string]: unknown};
+  destroy(): void;
+}
+/** THREE is injected: the host retains its existing Three.js dependency. */
+export function createDOMRenderer(THREE: {WebGLRenderer: new (...args: any[]) => any; [key: string]: any}, document: Document, options?: {presentation?: 'local' | 'viewport'; escapeEffects?: boolean; zIndex?: number; root?: HTMLDialogElement}): DOMRenderer;
 
 
 

package/src/dom-free-loader.js

@@ -1,12 +1,18 @@
+/** EV-RY FX Free loader (MIT) — https://ev-ry.com/fx/ */
 import {bootstrapFree} from './dom-free-bootstrap.js';
-
-/** Explicit npm/module entry. The first call selects auto mode; later calls reuse readiness. */
-export function loadFree(options={}){
-  const window=(options.document??globalThis.document)?.defaultView;
-  if(!window)throw TypeError('THD Free needs a browser document');
-  if(window.THDFree)return window.THDFree.ready;
-  const ready=bootstrapFree(options);
-  window.THDFree=Object.freeze({ready});
-  ready.catch(error=>{console.error(error);window.dispatchEvent(new window.CustomEvent('thd:error',{detail:error}));});
-  return ready;
-}
+
+/** Explicit npm/module entry. The first call selects auto mode; later calls reuse readiness. */
+export function loadFree(options={}){
+  const window=(options.document??globalThis.document)?.defaultView;
+  if(!window)throw TypeError('THD Free needs a browser document');
+  if(window.THDFree)return window.THDFree.ready;
+  const ready=bootstrapFree(options);
+  const namespace=Object.freeze({ready});
+  window.THDFree=namespace;
+  ready.catch(error=>{
+    if(window.THDFree===namespace)delete window.THDFree;
+    console.error(error);
+    window.dispatchEvent(new window.CustomEvent('thd:error',{detail:error}));
+  });
+  return ready;
+}

package/src/dom-free-script.js

@@ -1,12 +1,18 @@
+/** EV-RY FX Free classic loader (MIT) — https://ev-ry.com/fx/ */
 (function(){
-  const script=document.currentScript;
-  if(!script?.src)throw Error('THD: use a classic script tag, or import loadFree from @thd/free/script');
-  const base=new URL('.',script.src);
-  if(window.THDFree)return;
-  const ready=(async()=>{
-    const {bootstrapFree}=await import(new URL('./dom-free-bootstrap.js',base).href);
-    return bootstrapFree({document,auto:script.hasAttribute('data-thd-auto')});
-  })();
-  window.THDFree=Object.freeze({ready});
-  ready.catch(error=>{console.error(error);window.dispatchEvent(new CustomEvent('thd:error',{detail:error}));});
-})();
+  const script=document.currentScript;
+  if(!script?.src)throw Error('THD: use a classic script tag, or import loadFree from @thd/free/script');
+  const base=new URL('.',script.src);
+  if(window.THDFree)return;
+  const ready=(async()=>{
+    const {bootstrapFree}=await import(new URL('./dom-free-bootstrap.js',base).href);
+    return bootstrapFree({document,auto:script.hasAttribute('data-thd-auto')});
+  })();
+  const namespace=Object.freeze({ready});
+  window.THDFree=namespace;
+  ready.catch(error=>{
+    if(window.THDFree===namespace)delete window.THDFree;
+    console.error(error);
+    window.dispatchEvent(new CustomEvent('thd:error',{detail:error}));
+  });
+})();

package/src/dom-free.js

@@ -1,11 +1,12 @@
-import {createDOMInstallation} from './dom-attachment.js';
+/** EV-RY FX Free (MIT) — https://ev-ry.com/fx/ */
+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();
+  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}`);
@@ -14,32 +15,32 @@ export function createFree(THREE, root = document, options = {}) {
       ...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;}
+    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;
-    };
+      };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);requestedPlay=true;currentWait?.cancel();
-    },cancel:()=>{surface.cancel();requestedPlay=false;currentWait?.cancel();},refresh:()=>surface.refresh(),stats:()=>surface.stats(),destroy:()=>{currentWait?.cancel();surface.destroy();}});
+      if(!['enter','exit'].includes(phase))throw TypeError('Invalid phase');
+      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()};
@@ -57,7 +58,7 @@ export function createFree(THREE, root = document, options = {}) {
     },
     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();}}
+    destroy(){if(disposed)return;disposed=true;for(const cancel of [...installationWaits])cancel();try{automatic?.destroy();}finally{owner.destroy();}}
   });
 }
 

package/src/dom-image-surface.js

@@ -11,7 +11,17 @@ export function attachImageSurface(element,THREE,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;
+  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;
+  }
   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);
@@ -24,9 +34,12 @@ export function attachImageSurface(element,THREE,options={}){
   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});}
+    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?.();
+  }
+  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();
@@ -55,12 +68,12 @@ export function attachImageSurface(element,THREE,options={}){
       // 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';
+      if(state.state==='hidden')writeOpacity('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});
+    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});}}
@@ -83,10 +96,10 @@ export function attachImageSurface(element,THREE,options={}){
         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}});
+        // 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;
       });
@@ -143,7 +156,7 @@ export function attachImageSurface(element,THREE,options={}){
       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};
+      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,30 +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.
-    // 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'};
+// 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);else next.remove();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-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;
+}