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

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 [EV-RY website](https://ev-ry.com/) and [FX product page](https://ev-ry.com/fx/) are public. This file describes an integration pattern, not a copy of the deployed website or a Free-only live demo. Try the package's separate [interactive Free demo](https://kbaghini.github.io/evry-fx/docs/) for its four fixed effects. 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,57 +1,57 @@
-{
-  "name": "@ev-ry/fx",
-  "version": "0.1.0-rc.2",
-  "private": false,
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./src/dom-free.d.ts",
-      "import": "./src/dom-free.js"
-    },
-    "./script": {
-      "types": "./src/dom-free-loader.d.ts",
-      "import": "./src/dom-free-loader.js"
-    },
-    "./classic-script": "./src/dom-free-script.js"
-  },
-  "files": [
-    "src",
-    "assets",
-    "examples",
-    "README.md",
-    "LICENSE",
-    "NOTICE.md",
-    "QUICKSTART.fa.md",
-    "docs/GUIDE.md",
-    "docs/RELEASE-NOTES.md",
-    "build-report.json"
-  ],
-  "description": "Textured particle effects for existing HTML text, images and SVG. Native when still.",
-  "license": "MIT",
-  "author": {
-    "name": "Kamran Baghini",
-    "url": "https://ev-ry.com"
-  },
-  "keywords": [
-    "animation",
-    "particles",
-    "webgl",
-    "text-effects",
-    "image-effects",
-    "scroll-reveal",
-    "svg",
-    "rtl",
-    "ev-ry"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kbaghini/evry-fx.git"
-  },
-  "bugs": {
-    "url": "https://github.com/kbaghini/evry-fx/issues"
-  },
-  "homepage": "https://kbaghini.github.io/evry-fx/docs/"
-}
+{
+  "name": "@ev-ry/fx",
+  "version": "0.1.0-rc.4",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/dom-free.d.ts",
+      "import": "./src/dom-free.js"
+    },
+    "./script": {
+      "types": "./src/dom-free-loader.d.ts",
+      "import": "./src/dom-free-loader.js"
+    },
+    "./classic-script": "./src/dom-free-script.js"
+  },
+  "files": [
+    "src",
+    "assets",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "QUICKSTART.fa.md",
+    "docs/GUIDE.md",
+    "docs/RELEASE-NOTES.md",
+    "build-report.json"
+  ],
+  "description": "Textured particle effects for existing HTML text, images and SVG. Native when still.",
+  "license": "MIT",
+  "author": {
+    "name": "Kamran Baghini",
+    "url": "https://ev-ry.com"
+  },
+  "keywords": [
+    "animation",
+    "particles",
+    "webgl",
+    "text-effects",
+    "image-effects",
+    "scroll-reveal",
+    "svg",
+    "rtl",
+    "ev-ry"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kbaghini/evry-fx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kbaghini/evry-fx/issues"
+  },
+  "homepage": "https://ev-ry.com/fx/"
+}

package/src/dom-attachment.d.ts

@@ -1,75 +1,75 @@
-export interface SurfaceOptions {
-  /** Text/image/SVG only. Re-arm after complete exit. */
-  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.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,66 @@
+/** 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;
-  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')=>{
-      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();}}
-  });
-}
+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);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();}}
+  });
+}