@ev-ry/fx 0.1.0-rc.1

package/src/dom-attachment.d.ts

@@ -0,0 +1,78 @@
+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;
+
+
+
+
+
+

package/src/dom-attachment.js

@@ -0,0 +1,187 @@
+import {withRevealOnView} from './dom-reveal.js';
+import {attachSVGSurface} from './dom-svg-surface.js';
+import {swapDOMImage} from './dom-image-swap.js';
+import {animateDOMOnce} from './dom-once.js';
+import {attachImageSurface} from './dom-image-surface.js';
+import {createRenderOwner} from './render-owner.js';
+import {createViewportRenderOwner} from './viewport-render-owner.js';
+import {attachTextSurface} from './dom-text-surface.js';
+import {chooseDOMPresentation} from './dom-auto-route.js';
+
+// One optional visual owner. Application components retain their DOM, values,
+// events, fonts and lifecycle; this module knows nothing about EV or its theme.
+const attached = new WeakMap();
+const rendererOwners=new WeakMap();
+
+// Explicit mixed presentation. Existing owners retain rendering and surface state.
+export function createDOMInstallation(THREE, document, {presentation='local', documentCanvas=true, ...rendererOptions} = {}) {
+  rendererOptions.documentCanvas=documentCanvas;
+  const modes = {local:'local', global:'viewport',auto:'auto'};
+  const validate = mode => { if (!Object.hasOwn(modes, mode)) throw TypeError('Expected local, global or auto presentation'); };
+  validate(presentation);
+  const owners = new Map(), surfaces = new Map(), layers = new Map();
+  let disposed = false;
+  const automatic=new Map(),window=document.defaultView;
+  const routeEvents=['toggle','close','fullscreenchange','compositionend','transitionrun','transitionend','transitioncancel','animationstart','animationend','animationcancel'];
+  let observer=null,routeFrame=null;
+  function schedule(){if(!disposed&&automatic.size&&routeFrame===null){routeFrame=true;queueMicrotask(reconcile);}}
+  function watch(){
+    if(observer)return;
+    observer=new window.MutationObserver(records=>{
+      const owned=node=>node.nodeType===1&&node.matches('[data-thd-viewport-anchor],[data-thd-global-canvas]');
+      if(records.some(r=>!r.target.closest?.('[data-thd-viewport-anchor],[data-thd-global-canvas]')&&!(r.type==='childList'&&[...r.addedNodes,...r.removedNodes].every(owned))))schedule();
+    });
+    observer.observe(document.documentElement,{subtree:true,childList:true,attributes:true,attributeFilter:['class','style','open','hidden','popover']});
+    for(const event of routeEvents)document.addEventListener(event,schedule,true);
+    window.addEventListener('resize',schedule);
+  }
+  function unwatch(){
+    if(automatic.size)return;
+    observer?.disconnect();observer=null;
+    routeFrame=null;
+    for(const event of routeEvents)document.removeEventListener(event,schedule,true);
+    window.removeEventListener('resize',schedule);
+  }
+  function reconcile(){
+    routeFrame=null;
+    if(disposed)return;
+    const styles=new WeakMap(),readStyle=node=>{let value=styles.get(node);if(!value){value=window.getComputedStyle(node);styles.set(node,value);}return value;};
+    for(const [surface,state] of automatic){
+      const target=chooseDOMPresentation(surface.element,layers,readStyle);
+      state.reason=target.reason;state.pending=false;state.error=null;
+      try{handoff(surface,target,true);}
+      catch(error){state.pending=true;state.error=error.message;}
+    }
+  }
+  function follow(surface){automatic.set(surface,{reason:'pending',pending:true,error:null});watch();schedule();surface.ready.then(schedule);}
+  function attach(method, element, {presentation:mode=presentation, layer=null, ...options} = {}) {
+    if (disposed) throw Error('DOM installation disposed');
+    validate(mode);
+    const auto=mode==='auto';
+    if(auto){if(layer!==null)throw TypeError('Auto selects its layer; use global for an explicit layer');const target=chooseDOMPresentation(element,layers);mode=target.presentation;layer=target.layer;}
+    if(layer!==null&&(mode!=='global'||!layers.has(layer)))throw TypeError('Unknown layer or non-global layer request');
+    const key=layer===null?mode:'layer:'+layer;
+    let owner = owners.get(key);
+    if (!owner) {
+      owner = wrapOwner(createViewportRenderOwner(THREE, document, {...rendererOptions, ...(layer===null?{}:layers.get(layer)), local:mode==='local'}));
+      owners.set(key, owner);
+    }
+    let surface;
+    try { surface = owner[method](element, options); }
+    catch (error) {
+      if (!owner.stats().controls) { owners.delete(key); owner.destroy(); }
+      throw error;
+    }
+    surfaces.set(surface, key);
+    if(auto)follow(surface);
+    const destroy = surface.destroy;
+    surface.destroy = () => {
+      if (!surfaces.has(surface)) return;
+      const currentKey=surfaces.get(surface),currentOwner=owners.get(currentKey);
+      surfaces.delete(surface);
+      automatic.delete(surface);unwatch();
+      try { destroy(); }
+      finally {
+        if (!currentOwner.stats().controls && owners.get(currentKey) === currentOwner) {
+          owners.delete(currentKey); currentOwner.destroy();
+        }
+      }
+    };
+    return surface;
+  }
+  function handoff(surface,{presentation:mode='global',layer=null}={},recover=false){
+      if(disposed||!surfaces.has(surface))throw Error('Surface is not owned by this installation');
+      const from=surfaces.get(surface),to=layer===null?mode:'layer:'+layer;
+      if(layer!==null&&(mode!=='global'||!layers.has(layer)))throw TypeError('Unknown layer or non-global layer request');
+      if(from===to)return;
+      const previous=owners.get(from);
+      let next=owners.get(to);
+      if(!next){next=wrapOwner(createViewportRenderOwner(THREE,document,{...rendererOptions,...(layer===null?{}:layers.get(layer)),local:mode==='local'}));owners.set(to,next);}
+      try{rendererOwners.get(previous).transfer(surface,rendererOwners.get(next),{recover});}
+      catch(error){if(!next.stats().controls){owners.delete(to);next.destroy();}throw error;}
+      surfaces.set(surface,to);
+      if(!previous.stats().controls){owners.delete(from);previous.destroy();}
+    }
+  return {
+    transfer(surface,{presentation:mode='global',layer=null}={}){
+      if(disposed||!surfaces.has(surface))throw Error('Surface is not owned by this installation');
+      validate(mode);
+      if(mode==='auto'){if(layer!==null)throw TypeError('Auto selects its layer');follow(surface);return;}
+      handoff(surface,{presentation:mode,layer});automatic.delete(surface);unwatch();
+    },
+    routing(surface){
+      if(!surfaces.has(surface))throw Error('Unknown surface');
+      const key=surfaces.get(surface),state=automatic.get(surface);
+      return {requested:state?'auto':key==='local'?'local':'global',presentation:key==='local'?'local':'global',layer:key.startsWith('layer:')?key.slice(6):null,reason:state?.reason||'explicit',pending:state?.pending||false,error:state?.error||null};
+    },
+    registerLayer(name, {root, zIndex=100} = {}) {
+      if(disposed)throw Error('DOM installation disposed');
+      if(typeof name!=='string'||!name||layers.has(name))throw TypeError('Unique layer name required');
+      if(root?.ownerDocument!==document||root.tagName!=='DIALOG'||!Number.isFinite(zIndex))throw TypeError('Layer requires a dialog in the owner document');
+      layers.set(name,{root,zIndex});
+      schedule();
+    },
+    unregisterLayer(name) {
+      if([...surfaces.values()].includes('layer:'+name))throw Error('Detach layer surfaces before unregistering');
+      layers.delete(name);
+      schedule();
+    },
+    attachText:(element, options) => attach('attachText', element, options),
+    attachImage:(element, options) => attach('attachImage', element, options),
+    attachSVG:(element, options) => attach('attachSVG', element, options),
+    animateOnce:(element, options) => animateDOMOnce(attach,element,options),
+    swapImage:(previous,next,options)=>swapDOMImage((element,settings)=>animateDOMOnce(attach,element,settings),previous,next,options),
+    refresh() {
+      if (disposed) throw Error('DOM installation disposed');
+      for (const owner of owners.values()) owner.refresh();
+      schedule();
+    },
+    stats() {
+      const entries = [...owners].map(([mode, owner]) => [mode, owner.stats()]);
+      return {disposed, controls:surfaces.size, contexts:entries.reduce((n,[,s])=>n+s.contexts,0),
+        copies:entries.reduce((n,[,s])=>n+s.copies,0), owners:Object.fromEntries(entries)};
+    },
+    destroy() {
+      if (disposed) return;
+      disposed = true;
+      const errors = [];
+      for (const surface of [...surfaces.keys()]) try { surface.destroy(); } catch (error) { errors.push(error); }
+      for (const owner of owners.values()) try { owner.destroy(); } catch (error) { errors.push(error); }
+      owners.clear();layers.clear();
+      if (errors.length) throw new AggregateError(errors, 'DOM installation cleanup failed');
+    }
+  };
+}
+
+export function createDOMRenderer(THREE, document, options = {}) {
+  const owner = createRenderOwner(THREE, document, options);
+  return wrapOwner(owner);
+}
+function wrapOwner(owner){
+  function attach(factory, element, options) {
+    if (attached.has(element)) throw new Error('Element already has a THD attachment');
+    const surface = owner.create((element,namespace,settings)=>withRevealOnView(factory,element,namespace,settings), element, options);
+    attached.set(element, surface);
+    const destroy = surface.destroy;
+    surface.destroy = () => {
+      try { destroy(); }
+      finally { if (attached.get(element) === surface) attached.delete(element); }
+    };
+    return surface;
+  }
+  const api={
+    get domElement() { return owner.domElement ?? null; },
+    attachText: (element, options = {}) => attach(attachTextSurface, element, options),
+    attachImage: (element, options = {}) => attach(attachImageSurface, element, options),
+    attachSVG: (element, options = {}) => attach(attachSVGSurface, element, options),
+    stats: owner.stats,
+    refresh: owner.refresh,
+    destroy: owner.destroy
+  };
+  rendererOwners.set(api,owner);return api;
+}
+
+
+
+
+

package/src/dom-auto-reveal.d.ts

@@ -0,0 +1,17 @@
+import type {DOMPresentation, DOMInstallation, createDOMRenderer} from './dom-attachment.js';
+export interface AutoRevealOptions {
+  textSelector?: string;
+  imageSelector?: string;
+  presentation?: DOMPresentation;
+  threshold?: number;
+  once?: boolean;
+  intersectionRoot?: Element | null;
+}
+/** Explicit scan. Call refresh after route/content changes; destroy on unmount. */
+export function createAutoReveal(THREE: Parameters<typeof createDOMRenderer>[0], root?: Document | Element, options?: AutoRevealOptions): {
+
+  refresh(): void;
+  stats(): {disposed: boolean; attached: number; failures: {element: Element; message: string}[]; renderer: ReturnType<DOMInstallation['stats']>};
+  destroy(): void;
+};
+

package/src/dom-auto-reveal.js

@@ -0,0 +1,53 @@
+import {createDOMInstallation} from './dom-attachment.js';
+
+// Explicit initialization; importing this module never changes the page.
+export function createAutoReveal(THREE, root = document, options = {}, sharedOwner = null) {
+  const doc = root.nodeType === 9 ? root : root.ownerDocument;
+  const textSelector = options.textSelector ?? 'h1,h2,[data-thd-text]';
+  const imageSelector = options.imageSelector ?? 'img[data-thd-image]';
+  const exclude = '[data-thd-ignore],nav,dialog,[role="dialog"],button,a,[contenteditable]:not([contenteditable="false"])';
+  // Validate selectors before allocating render resources.
+  root.querySelectorAll(textSelector); root.querySelectorAll(imageSelector);
+  if (options.threshold !== undefined && (!Number.isFinite(options.threshold) || options.threshold < 0 || options.threshold > 1)) throw TypeError('Invalid threshold');
+  if (options.once !== undefined && typeof options.once !== 'boolean') throw TypeError('Invalid once');
+  if (options.intersectionRoot != null && (options.intersectionRoot.nodeType !== 1 || options.intersectionRoot.ownerDocument !== doc)) throw TypeError('Invalid intersection root');
+  const owner = sharedOwner ?? createDOMInstallation(THREE, doc, {presentation: options.presentation ?? 'auto'});
+  const entries = new Map();
+  let disposed = false, failures = [];
+  const settings = {
+    resting: 'native',
+    inputEffect: 'dust-wind',
+    inputEffectOptions: {duration: 2000, particleShape: 'triangle'},
+    revealOnView: {threshold: options.threshold ?? 0, once: options.once ?? true, root: options.intersectionRoot ?? null}
+  };
+  function refresh() {
+    if (disposed) throw Error('Auto reveal disposed');
+    failures = [];
+    const candidates = [...root.querySelectorAll(`${textSelector},${imageSelector}`)];
+    if (root.nodeType === 1 && root.matches(`${textSelector},${imageSelector}`)) candidates.unshift(root);
+    const hasForeignContent=el=>[...el.querySelectorAll('input,textarea,button,select,[contenteditable],img,svg,canvas')].some(node=>
+      !node.closest('[data-thd-viewport-anchor],[data-thd-text-surface]'));
+    const eligible = candidates.filter(el => !el.closest(exclude) && !hasForeignContent(el) && (el.matches(imageSelector) ? el.tagName === 'IMG' : !!el.textContent.trim()));
+    // Attach outer text once; never mask overlapping parent/child surfaces.
+    const targets = eligible.filter(el => !eligible.some(parent => parent !== el && parent.contains(el)));
+    for (const [el, surface] of entries) if (!targets.includes(el)) { surface.destroy(); entries.delete(el); }
+    for (const el of targets) {
+      if (entries.has(el)) continue;
+      try {
+        entries.set(el, el.tagName === 'IMG'
+          ? owner.attachImage(el, {...settings, inputEffect: 'drifting-snow'})
+          : owner.attachText(el, settings));
+      } catch (error) { failures.push({element: el, message: String(error.message || error)}); }
+    }
+    // Offscreen surfaces prepare lazily; scanning must not wait for intersection.
+  }
+  const api = {
+    refresh,
+    stats: () => ({disposed, attached: entries.size, failures: [...failures], renderer: owner.stats()}),
+    destroy() { if (disposed) return; disposed = true; if(sharedOwner){for(const surface of entries.values())surface.destroy();}else owner.destroy(); entries.clear(); }
+  };
+  refresh();
+  return api;
+}
+
+

package/src/dom-auto-route.js

@@ -0,0 +1,25 @@
+// Deliberately bounded policy: registered dialog roots, ordinary page, or local
+// CSS composition. Never infer stacking layers from z-index or create new roots.
+export function chooseDOMPresentation(element,layers,readStyle=node=>node.ownerDocument.defaultView.getComputedStyle(node)){
+  const document=element.ownerDocument,window=document.defaultView;
+  let layer=null,reason='ordinary page';
+  if(document.fullscreenElement)return {presentation:'local',layer:null,reason:'fullscreen'};
+  for(let node=element;node;node=node.parentElement){
+    const style=readStyle(node);
+    if(node!==document.body&&node!==document.documentElement){
+      if(['fixed','sticky'].includes(style.position))return {presentation:'local',layer:null,reason:'fixed or sticky container'};
+      if(!node.matches('dialog')&&style.position!=='static'&&style.zIndex!=='auto')return {presentation:'local',layer:null,reason:'explicit stacking context'};
+      if(node!==element&&/(auto|scroll)/.test(style.overflowX+' '+style.overflowY))return {presentation:'local',layer:null,reason:'nested scroll container'};
+    }
+    if(style.transform!=='none'||style.perspective!=='none'||style.rotate&&style.rotate!=='none'&&style.rotate!=='0deg'||style.scale&&style.scale!=='none'||style.clipPath&&style.clipPath!=='none'||style.maskImage&&style.maskImage!=='none')
+      return {presentation:'local',layer:null,reason:'CSS transform or mask'};
+    if(layer===null&&node.matches('dialog')){
+      const entry=[...layers].find(([,value])=>value.root===node);
+      if(!entry||!node.open)return {presentation:'local',layer:null,reason:entry?'closed dialog':'unregistered dialog'};
+      layer=entry[0];reason='registered dialog';
+    }
+    if(node.hasAttribute('popover')&&node.matches(':popover-open'))return {presentation:'local',layer:null,reason:'popover'};
+  }
+  return {presentation:'global',layer,reason};
+}
+

package/src/dom-free-bootstrap.js

@@ -0,0 +1,42 @@
+import {createFree,FREE_EFFECTS} from './dom-free.js';
+
+// Shared initialization for the classic loader and explicit module loader.
+// Importing this module does not attach content or access a browser document.
+const dependencies=new WeakMap();
+export async function bootstrapFree({document=globalThis.document,THREE,auto=false}={}){
+  const window=document?.defaultView;
+  if(!window)throw TypeError('THD Free needs a browser document');
+  if(typeof auto!=='boolean')throw TypeError('THD Free auto must be a boolean');
+  let three=THREE??window.THREE;
+  if(!three){
+    let loading=dependencies.get(document);
+    if(!loading){
+      loading=new Promise((resolve,reject)=>{
+        const script=document.createElement('script');
+        script.src=new URL('../assets/vendor/three.min.js',import.meta.url).href;
+        script.onload=()=>{script.onload=script.onerror=null;resolve(window.THREE);};
+        script.onerror=()=>{script.remove();reject(Error('THD: Three.js failed to load'));};
+        document.head.append(script);
+      });
+      dependencies.set(document,loading);
+      loading.catch(()=>{if(dependencies.get(document)===loading)dependencies.delete(document);});
+    }
+    three=await loading;
+  }
+  const api={create:(root=document,options={})=>createFree(three,root,options),effects:FREE_EFFECTS};
+  if(auto){
+    if(document.readyState==='loading')await new Promise(resolve=>document.addEventListener('DOMContentLoaded',resolve,{once:true}));
+    const instance=api.instance=api.create();
+    const stop=()=>{window.removeEventListener('pagehide',leave);window.removeEventListener('pageshow',restore);};
+    const leave=event=>{if(!event.persisted){stop();instance.destroy();}};
+    const restore=event=>{
+      if(instance.stats().disposed){stop();return;}
+      if(event.persisted)instance.refresh();
+    };
+    // BFCache suspends the page. Keep the same owner/once state for return;
+    // dispose only when the page is actually discarded.
+    window.addEventListener('pagehide',leave);
+    window.addEventListener('pageshow',restore);
+  }
+  return Object.freeze(api);
+}

package/src/dom-free-loader.d.ts

@@ -0,0 +1,13 @@
+import type {createFree,FREE_EFFECTS} from './dom-free.js';
+export interface FreeLoaderOptions {
+  auto?: boolean;
+  document?: Document;
+  THREE?: Parameters<typeof createFree>[0];
+}
+export interface FreeLoaderAPI {
+  create(root?: Document|Element,options?: Parameters<typeof createFree>[2]):ReturnType<typeof createFree>;
+  effects: typeof FREE_EFFECTS;
+  readonly instance?: ReturnType<typeof createFree>;
+}
+/** Browser initialization; imports are inert. Repeated calls reuse the first initialization. */
+export function loadFree(options?:FreeLoaderOptions):Promise<Readonly<FreeLoaderAPI>>;

package/src/dom-free-loader.js

@@ -0,0 +1,12 @@
+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;
+}

package/src/dom-free-script.js

@@ -0,0 +1,12 @@
+(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}));});
+})();

package/src/dom-free.d.ts

@@ -0,0 +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;
+};
+
+

package/src/dom-free.js

@@ -0,0 +1,42 @@
+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();}}
+  });
+}
+
+
+

package/src/dom-image-raster.js

@@ -0,0 +1,22 @@
+import {imageRasterSource} from './image-source.js';
+// Capture the supported native image box, including cover/contain and radii.
+export async function rasterizeDOMImage(element,{maxSide=2048}={}){
+  const start=performance.now();
+  const doc=element.ownerDocument,css=doc.defaultView.getComputedStyle(element),box=element.getBoundingClientRect();
+  if(!box.width||!box.height)throw Error('Image not visible');
+  const scale=Math.min(2,maxSide/Math.max(box.width,box.height),Math.sqrt(2097152/(box.width*box.height))),canvas=doc.createElement('canvas');
+  canvas.width=Math.max(1,Math.round(box.width*scale));canvas.height=Math.max(1,Math.round(box.height*scale));
+  const context=canvas.getContext('2d',{willReadFrequently:true,colorSpace:'srgb'});context.scale(canvas.width/box.width,canvas.height/box.height);
+  try{
+  const radii=['borderTopLeftRadius','borderTopRightRadius','borderBottomRightRadius','borderBottomLeftRadius'].map(key=>{
+    const parts=css[key].split(/\s+/),read=(s,n)=>parseFloat(s)*(s.endsWith('%')?n/100:1);
+    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();
+  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);
+  const width=canvas.width,height=canvas.height,rgba=context.getImageData(0,0,width,height).data;
+  return {source:imageRasterSource({width,height,rgba,mask:false,type:'image/png',originalWidth:width,originalHeight:height,decodeMs:performance.now()-start}),width,height};
+  }finally{canvas.width=canvas.height=0;}
+}