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

package/src/dom-text-surface.js

@@ -7,8 +7,8 @@ import {textEditMotions} from './text-edit-motions.js';
 import {normalizeTextEffectOptions} from './text-effect-options.js';
 import {adoptDOMFont,domFontAtSize,matchesDOMFont} from './dom-surface-font.js';
 import {DOMRichText} from './dom-rich-text.js';
-import {createDOMTextFingerprint} from './dom-text-fingerprint.js';
-import {createTextPaintMask} from './dom-text-paint-mask.js';
+import {createDOMTextFingerprint} from './dom-text-fingerprint.js';
+import {createTextPaintMask} from './dom-text-paint-mask.js';
 
 // Presentation attachment: the original text node, parent control and semantics
 // remain owned by the host. The deliberately narrow first contract is a plain,
@@ -25,8 +25,8 @@ export function attachTextSurface(element,THREE,options={}){
   let enabled=options.enabled!==false,renderer,canvas,engine,view,effect,scene,content,camera;
   let frame=null,revision=0,preparing=false,dirty=true,layout=null,committed=null,reason=null,fatal=false,intersecting=true;
   let mode='native',draws=0,builds=0,submittedSize='',pendingPhase=options.initialPhase??null,phase='enter',lastSeed=null;
-  let effectStarted=null,pendingStarted=null,settleStarted=null;
-  let nativeMask;
+  let effectStarted=null,pendingStarted=null,settleStarted=null;
+  let nativeMask;
   function preserveMotion(){if(pendingPhase===null&&effectStarted!==null&&window.performance.now()-effectStarted<settings.duration){pendingPhase=phase;pendingStarted=effectStarted;}}
   let resolveReady;const ready=new Promise(resolve=>{resolveReady=resolve;});
   let rich=null;
@@ -46,12 +46,12 @@ export function attachTextSurface(element,THREE,options={}){
     }
     ownedStyle.delete(name);originalStyle.delete(name);
   }
-  function exitOwnsPaint(why=reason){return (pendingPhase??phase)==='exit'&&!fatal&&enabled&&!forced.matches&&(!why||/not visible|not connected|native resting presentation|hidden after exit/i.test(why));}
-  function native(why=null){
-    nativeMask?.release();
+  function exitOwnsPaint(why=reason){return (pendingPhase??phase)==='exit'&&!fatal&&enabled&&!forced.matches&&(!why||/not visible|not connected|native resting presentation|hidden after exit/i.test(why));}
+  function native(why=null){
+    nativeMask?.release();
     rich?.restore();
-    mode='native';reason=why;restoreStyle('-webkit-text-fill-color');restoreStyle('text-shadow');
-    if(exitOwnsPaint(why))nativeMask?.hold();
+    mode='native';reason=why;restoreStyle('-webkit-text-fill-color');restoreStyle('text-shadow');
+    if(exitOwnsPaint(why))nativeMask?.hold();
     if(canvas)canvas.style.display='none';
     renderer?.invalidate?.();
   }
@@ -61,27 +61,27 @@ export function attachTextSurface(element,THREE,options={}){
     resolveReady({mode,reason});
   }
   function request(){if(!life.disposed&&!fatal&&!document.hidden&&intersecting&&frame===null)frame=window.requestAnimationFrame(render);}
-  function suspend(){
-    if(pendingPhase!==null&&pendingStarted===null)pendingStarted=window.performance.now();
-    if(frame!==null)window.cancelAnimationFrame(frame);frame=null;
-    const hideExit=exitOwnsPaint();
-    // The last canvas frame and restored native text must not flash on reentry.
-    // A queued/current exit owns native paint even while no frames are drawn.
-    if(renderer?.globalCanvas||hideExit)native(reason??'not visible');
-    if(canvas)canvas.style.display='none';renderer?.invalidate?.();
-  }
-  function refresh(){
-    if(life.disposed)return;revision++;dirty=true;request();
-  }
-  function play(next='enter'){
-    if(life.disposed)throw Error('Text surface disposed');if(!['enter','exit'].includes(next))throw TypeError('Expected enter or exit');
-    pendingPhase=next;if(next==='enter')lastSeed=null;const box=element.getBoundingClientRect();
-    const outside=box.bottom<=0||box.top>=window.innerHeight||box.right<=0||box.left>=window.innerWidth;
-    pendingStarted=document.hidden||!intersecting||outside?window.performance.now():null;
-    // Do not spend a cold preparation frame waiting for IO's first delivery.
-    if(outside&&window.IntersectionObserver)intersecting=false;
-    if(document.hidden||!intersecting)suspend();refresh();
-  }
+  function suspend(){
+    if(pendingPhase!==null&&pendingStarted===null)pendingStarted=window.performance.now();
+    if(frame!==null)window.cancelAnimationFrame(frame);frame=null;
+    const hideExit=exitOwnsPaint();
+    // The last canvas frame and restored native text must not flash on reentry.
+    // A queued/current exit owns native paint even while no frames are drawn.
+    if(renderer?.globalCanvas||hideExit)native(reason??'not visible');
+    if(canvas)canvas.style.display='none';renderer?.invalidate?.();
+  }
+  function refresh(){
+    if(life.disposed)return;revision++;dirty=true;request();
+  }
+  function play(next='enter'){
+    if(life.disposed)throw Error('Text surface disposed');if(!['enter','exit'].includes(next))throw TypeError('Expected enter or exit');
+    pendingPhase=next;if(next==='enter')lastSeed=null;const box=element.getBoundingClientRect();
+    const outside=box.bottom<=0||box.top>=window.innerHeight||box.right<=0||box.left>=window.innerWidth;
+    pendingStarted=document.hidden||!intersecting||outside?window.performance.now():null;
+    // Do not spend a cold preparation frame waiting for IO's first delivery.
+    if(outside&&window.IntersectionObserver)intersecting=false;
+    if(document.hidden||!intersecting)suspend();refresh();
+  }
   function slot(){
     const children=[...element.childNodes].filter(node=>node!==canvas&&node.nodeType!==8);
     if(children.some(node=>node.nodeType!==3)||children.length>1)return null;
@@ -202,23 +202,23 @@ export function attachTextSurface(element,THREE,options={}){
       let nativeAlpha=0,meshFade=0;
       if(active&&phase!=='exit'&&resting==='native'&&effectStarted!==null)
         nativeAlpha=Math.max(0,Math.min(1,(now-(effectStarted+settings.duration-175))/350));
-      if(!active&&phase!=='exit'&&resting==='native'){
+      if(!active&&phase!=='exit'&&resting==='native'){
         // Use the effect clock, not the first idle frame. Slow frames must not
         // restart the handoff or jump native alpha back to its halfway point.
-        // Cancellation/settings refresh have no entry clock. Keep their
-        // restored native paint instead of beginning a second handoff.
-        const instant=effectStarted===null||effectName==='none'||reduced.matches;
-        if(settleStarted===null)settleStarted=effectStarted===null?now:effectStarted+settings.duration;
-        meshFade=instant?1:Math.min(1,(now-settleStarted)/350);
-        nativeAlpha=instant?1:Math.min(1,(now-settleStarted+175)/350);
+        // Cancellation/settings refresh have no entry clock. Keep their
+        // restored native paint instead of beginning a second handoff.
+        const instant=effectStarted===null||effectName==='none'||reduced.matches;
+        if(settleStarted===null)settleStarted=effectStarted===null?now:effectStarted+settings.duration;
+        meshFade=instant?1:Math.min(1,(now-settleStarted)/350);
+        nativeAlpha=instant?1:Math.min(1,(now-settleStarted+175)/350);
         if(meshFade>=1){renderer.render(scene,camera);native('native resting presentation');resolveReady({mode,reason});return;}
       }else settleStarted=null;
       view.uniforms.presentationOpacity.value=1-meshFade;rich?.setPresentationOpacity(1-meshFade);
-      const handingOffNative=mode==='native';
-      renderer.render(scene,camera);draws++;
-      // Transfer temporary offscreen ownership to the regular mesh paint mask
-      // in the same task, before the browser can paint native glyphs.
-      nativeMask?.release();
+      const handingOffNative=mode==='native';
+      renderer.render(scene,camera);draws++;
+      // Transfer temporary offscreen ownership to the regular mesh paint mask
+      // in the same task, before the browser can paint native glyphs.
+      nativeMask?.release();
       canvas.style.display='block';if(!rich)ownStyle('-webkit-text-fill-color',nativeAlpha>0?`color-mix(in srgb, ${window.getComputedStyle(element).color} ${nativeAlpha*100}%, transparent)`:'transparent');ownStyle('text-shadow','none');mode='mesh';reason=null;
       rich?.hide(nativeAlpha);
       // Commit the shared canvas before the browser paints hidden native text.
@@ -232,8 +232,8 @@ export function attachTextSurface(element,THREE,options={}){
   try{
     renderer=new THREE.WebGLRenderer({antialias:true,alpha:true});life.own(()=>{renderer.dispose();renderer.forceContextLoss();});
     renderer.setSurface?.(element,{escapeHost:element.closest('button,a,[role="button"]')||element});
-    canvas=renderer.domElement;canvas.setAttribute('aria-hidden','true');canvas.setAttribute('data-thd-text-surface','');
-    nativeMask=createTextPaintMask(element,canvas);life.own(()=>nativeMask.release());
+    canvas=renderer.domElement;canvas.setAttribute('aria-hidden','true');canvas.setAttribute('data-thd-text-surface','');
+    nativeMask=createTextPaintMask(element,canvas);life.own(()=>nativeMask.release());
     fingerprint=createDOMTextFingerprint(element,canvas);
     Object.assign(canvas.style,{position:'absolute',pointerEvents:'none',display:'none',margin:'0',padding:'0',border:'0',maxWidth:'none',maxHeight:'none'});
     element.append(canvas);life.own(()=>canvas.remove());
@@ -266,8 +266,8 @@ export function attachTextSurface(element,THREE,options={}){
     life.listen(window,'resize',refresh);
     for(const event of ['loadingdone','loadingerror'])life.listen(document.fonts,event,()=>{fontRevision++;refresh();});
     life.listen(forced,'change',()=>{native();refresh();});life.listen(reduced,'change',refresh);
-    if(pendingPhase!==null)play(pendingPhase);else request();
-  }catch(error){fail(error);}
+    if(pendingPhase!==null)play(pendingPhase);else request();
+  }catch(error){fail(error);}
   return {element,ready,
     refresh,
     update(next={}){
@@ -276,16 +276,16 @@ export function attachTextSurface(element,THREE,options={}){
       validResting(next.resting??resting);resting=next.resting??resting;
       const normalized=normalizeTextEffectOptions(next.inputEffectOptions?{formation:-1,...next.inputEffectOptions}:settings,candidate==='none'?'dust-wind':candidate);
       effectName=candidate;settings=normalized;if('enabled' in next)enabled=next.enabled!==false;
-      effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;native();refresh();
+      effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;native();refresh();
     },
-    cancel(){if(life.disposed)return;effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;native();refresh();},
-    play,
+    cancel(){if(life.disposed)return;effect?.cancel();rich?.cancel();pendingPhase=null;pendingStarted=null;effectStarted=null;phase='enter';if(content)content.visible=true;native();refresh();},
+    play,
     stats:()=>{const started=pendingPhase!==null?pendingStarted:effectStarted,currentPhase=pendingPhase??phase;
-      const duration=reduced.matches||effectName==='none'?0:settings.duration;
-      const finishAt=started===null?null:started+(duration===0?0:duration+(currentPhase==='enter'&&resting==='native'?350:0));
+      const duration=reduced.matches||effectName==='none'?0:settings.duration;
+      const finishAt=started===null?null:started+(duration===0?0:duration+(currentPhase==='enter'&&resting==='native'?350:0));
       const suspended=document.hidden||!intersecting;
-      const completed=started!==null&&(suspended?window.performance.now()>=finishAt:pendingPhase===null&&(currentPhase==='exit'?content?.visible===false:resting==='mesh'?mode==='mesh'&&!(rich?rich.stats().active:effect?.active):mode==='native'&&reason==='native resting presentation'));
-      return {completed,timeline:{phase:currentPhase,started,ends:started===null?null:started+duration,finishAt},disposed:life.disposed,mode,reason,committed,preparing,draws,builds,pending:frame!==null,suspended:document.hidden||!intersecting,triangles:rich?rich.stats().triangles:view?.triangleCount??0,
+      const completed=started!==null&&(suspended?window.performance.now()>=finishAt:pendingPhase===null&&(currentPhase==='exit'?content?.visible===false:resting==='mesh'?mode==='mesh'&&!(rich?rich.stats().active:effect?.active):mode==='native'&&reason==='native resting presentation'));
+      return {completed,timeline:{phase:currentPhase,started,ends:started===null?null:started+duration,finishAt},disposed:life.disposed,mode,reason,committed,preparing,draws,builds,pending:frame!==null,suspended:document.hidden||!intersecting,triangles:rich?rich.stats().triangles:view?.triangleCount??0,
       width:layout?.width??0,height:layout?.height??0,fontFamily:engine?.face?.family,displayFontSize:layout?.size,divisions:engine?.divisions,effect:effect?.stats(),rich:rich?.stats()??null};},
     destroy(){if(life.disposed)return;native('destroyed');resolveReady({mode,reason});life.destroy();}
   };

package/src/font-rasterizer.js

@@ -11,14 +11,14 @@ export class FontRasterizer {
     this.cache = new Map();
   }
 
-  configure(direction = 'ltr') {
-    this.context.font = this.font;
-    // Build the cached source for legibility, independently of the GPU's cheaper
-    // moving-particle sampler. Reapply after canvas resize resets drawing state.
-    if ('textRendering' in this.context) this.context.textRendering = this.textRendering ?? 'optimizeLegibility';
-    if ('fontKerning' in this.context) this.context.fontKerning = this.fontKerning ?? 'normal';
-    if ('letterSpacing' in this.context) this.context.letterSpacing = `${this.letterSpacing || 0}px`;
-    if ('wordSpacing' in this.context) this.context.wordSpacing = `${this.wordSpacing || 0}px`;
+  configure(direction = 'ltr') {
+    this.context.font = this.font;
+    // Build the cached source for legibility, independently of the GPU's cheaper
+    // moving-particle sampler. Reapply after canvas resize resets drawing state.
+    if ('textRendering' in this.context) this.context.textRendering = this.textRendering ?? 'optimizeLegibility';
+    if ('fontKerning' in this.context) this.context.fontKerning = this.fontKerning ?? 'normal';
+    if ('letterSpacing' in this.context) this.context.letterSpacing = `${this.letterSpacing || 0}px`;
+    if ('wordSpacing' in this.context) this.context.wordSpacing = `${this.wordSpacing || 0}px`;
     this.context.textAlign = 'left'; this.context.textBaseline = 'alphabetic';
     // Layout already resolves bidi and mirrors punctuation. Do not mirror it again
     // when Canvas draws an isolated, direction-neutral glyph such as a bracket.
@@ -29,24 +29,24 @@ export class FontRasterizer {
     const key = direction + ':' + text;
     if (this.cache.has(key)) return this.cache.get(key);
     this.configure(direction);
-    const metric = this.context.measureText(text);
-    let horizontalScale = 1;
-    if (this.displayFontSize > 0 && metric.width > 0) {
-      const factor = this.displayFontSize / 200;
-      this.context.font = this.font.replace('200px', `${this.displayFontSize}px`);
-      if ('letterSpacing' in this.context) this.context.letterSpacing = `${(this.letterSpacing || 0) * factor}px`;
-      if ('wordSpacing' in this.context) this.context.wordSpacing = `${(this.wordSpacing || 0) * factor}px`;
-      const advance = this.context.measureText(text).width / factor;
-      if (Number.isFinite(advance) && advance > 0) horizontalScale = advance / metric.width;
-      this.configure(direction);
-    }
+    const metric = this.context.measureText(text);
+    let horizontalScale = 1;
+    if (this.displayFontSize > 0 && metric.width > 0) {
+      const factor = this.displayFontSize / 200;
+      this.context.font = this.font.replace('200px', `${this.displayFontSize}px`);
+      if ('letterSpacing' in this.context) this.context.letterSpacing = `${(this.letterSpacing || 0) * factor}px`;
+      if ('wordSpacing' in this.context) this.context.wordSpacing = `${(this.wordSpacing || 0) * factor}px`;
+      const advance = this.context.measureText(text).width / factor;
+      if (Number.isFinite(advance) && advance > 0) horizontalScale = advance / metric.width;
+      this.configure(direction);
+    }
     const padding = 2;
     const drawOffsetX = Math.ceil(Math.max(0, (metric.actualBoundingBoxLeft || 0)*horizontalScale)) + padding;
     const baseline = Math.ceil(Math.max(this.ascent, metric.actualBoundingBoxAscent || 0)) + padding;
     const width = Math.max(2, Math.ceil(Math.max(metric.width, metric.actualBoundingBoxRight || 0)*horizontalScale + drawOffsetX + padding));
     const height = Math.max(2, Math.ceil(baseline + Math.max(this.descent, metric.actualBoundingBoxDescent || 0) + padding));
     this.canvas.width = width; this.canvas.height = height; this.configure(direction);
-    this.context.save();this.context.translate(drawOffsetX,baseline);this.context.scale(horizontalScale,1);
+    this.context.save();this.context.translate(drawOffsetX,baseline);this.context.scale(horizontalScale,1);
     this.context.fillText(text,0,0);this.context.restore();
     const rgba = this.context.getImageData(0, 0, width, height).data;
     const result = { width, height, baseline, drawOffsetX, advance: metric.width*horizontalScale, rgba };

package/src/insertion-range.js

@@ -1,29 +1,29 @@
-// UTF-16 edit range shared by both adapters. The selection disambiguates repeats.
-export function insertedRange(before,after,inputType='insertText'){
-  if(!before||!after||!/^insert/.test(inputType)||before.text===after.text)return null;
-  const start=before.start??0,end=before.end??start;
-  const length=after.text.length-(before.text.length-(end-start));
-  if(length>0&&after.text.slice(0,start)===before.text.slice(0,start)&&after.text.slice(start+length)===before.text.slice(end))return {start,end:start+length};
-  let left=0,right=0;
-  while(left<before.text.length&&left<after.text.length&&before.text[left]===after.text[left])left++;
-  while(right<before.text.length-left&&right<after.text.length-left&&before.text[before.text.length-1-right]===after.text[after.text.length-1-right])right++;
-  return after.text.length-right>left?{start:left,end:after.text.length-right}:null;
-}
-
-// Keep the surviving pieces of an older insertion when a later edit shifts it.
-export function remapInsertionRange(range,start,oldEnd,delta){
-  const pieces=[];
-  if(range.start<start)pieces.push({start:range.start,end:Math.min(range.end,start)});
-  if(range.end>oldEnd)pieces.push({start:Math.max(range.start,oldEnd)+delta,end:range.end+delta});
-  return pieces.filter(piece=>piece.end>piece.start);
-}
-
-export function removedRange(before,after,inputType=''){
-  if(!before||!after||!/^delete/.test(inputType))return null;
-  const length=before.text.length-after.text.length;if(length<=0)return null;
-  const caret=before.start??0;
-  const start=before.end>caret?caret:/Backward$/.test(inputType)?Math.max(0,caret-length):caret;
-  if(before.text.slice(0,start)+before.text.slice(start+length)===after.text)return {start,end:start+length};
-  let left=0;while(left<after.text.length&&before.text[left]===after.text[left])left++;
-  return {start:left,end:left+length};
-}
+// UTF-16 edit range shared by both adapters. The selection disambiguates repeats.
+export function insertedRange(before,after,inputType='insertText'){
+  if(!before||!after||!/^insert/.test(inputType)||before.text===after.text)return null;
+  const start=before.start??0,end=before.end??start;
+  const length=after.text.length-(before.text.length-(end-start));
+  if(length>0&&after.text.slice(0,start)===before.text.slice(0,start)&&after.text.slice(start+length)===before.text.slice(end))return {start,end:start+length};
+  let left=0,right=0;
+  while(left<before.text.length&&left<after.text.length&&before.text[left]===after.text[left])left++;
+  while(right<before.text.length-left&&right<after.text.length-left&&before.text[before.text.length-1-right]===after.text[after.text.length-1-right])right++;
+  return after.text.length-right>left?{start:left,end:after.text.length-right}:null;
+}
+
+// Keep the surviving pieces of an older insertion when a later edit shifts it.
+export function remapInsertionRange(range,start,oldEnd,delta){
+  const pieces=[];
+  if(range.start<start)pieces.push({start:range.start,end:Math.min(range.end,start)});
+  if(range.end>oldEnd)pieces.push({start:Math.max(range.start,oldEnd)+delta,end:range.end+delta});
+  return pieces.filter(piece=>piece.end>piece.start);
+}
+
+export function removedRange(before,after,inputType=''){
+  if(!before||!after||!/^delete/.test(inputType))return null;
+  const length=before.text.length-after.text.length;if(length<=0)return null;
+  const caret=before.start??0;
+  const start=before.end>caret?caret:/Backward$/.test(inputType)?Math.max(0,caret-length):caret;
+  if(before.text.slice(0,start)+before.text.slice(start+length)===after.text)return {start,end:start+length};
+  let left=0;while(left<after.text.length&&before.text[left]===after.text[left])left++;
+  return {start:left,end:left+length};
+}

package/src/raster-texture-material.js

@@ -1,79 +1,79 @@
-// Text and image surfaces share one texture per raster (not per triangle).
-// References include deletion ghosts, which can outlive their source scene mesh.
-const surfaces=new WeakMap(),materials=new WeakMap();
-export function attachRasterTexture(THREE,material,raster,{lodBias=raster.mask===false?0:-.75}={}){
-  if(!Number.isFinite(lodBias))throw TypeError('A finite raster LOD bias is required');
-  let surface=surfaces.get(raster);
-  if(!surface){
-    const texture=new THREE.DataTexture(raster.rgba,raster.width,raster.height,THREE.RGBAFormat,THREE.UnsignedByteType);
-    if(raster.mask===false)texture.colorSpace=THREE.SRGBColorSpace;
-    // One bilinear mip fetch while moving; the shader adds the adjacent mip only
-    // near the resting pose. Sampling policy never mutates a shared texture.
-    texture.minFilter=THREE.LinearMipmapNearestFilter;texture.magFilter=THREE.LinearFilter;texture.generateMipmaps=true;texture.needsUpdate=true;
-    surface={texture,refs:0,raster};surfaces.set(raster,surface);
-  }
-  material.uniforms.rasterMap={value:surface.texture};
-  material.uniforms.rasterSize={value:new THREE.Vector2(raster.width,raster.height)};
-  material.uniforms.rasterLodBias={value:lodBias};
-  return lease(material,surface);
-}
-// Derivatives describe this triangle's current projected texture footprint.
-// Explicit LOD is core in WebGL2 (Three aliases texture2DLodEXT) and optional in
-// WebGL1. Without it, keep a single conventional texture lookup as a safe fallback.
-const rasterSamplingShader=`
-uniform vec2 rasterSize;
-uniform float rasterLodBias;
-varying float vRasterQuality;
-vec4 thdRasterSample(vec2 uv){
-  #if __VERSION__ >= 300 || defined(GL_EXT_shader_texture_lod)
-    vec2 dx=dFdx(uv*rasterSize),dy=dFdy(uv*rasterSize);
-    float footprint=max(max(dot(dx,dx),dot(dy,dy)),0.00000001);
-    float lastLevel=floor(log2(max(max(rasterSize.x,rasterSize.y),1.0)));
-    float lod=clamp(0.5*log2(footprint)+rasterLodBias,0.0,lastLevel);
-    float primary=floor(lod+0.5);
-    vec4 sampleColor=texture2DLodEXT(rasterMap,uv,primary);
-    float weight=abs(lod-primary)*clamp(vRasterQuality,0.0,1.0);
-    if(weight>0.0){
-      float adjacent=primary<lod?primary+1.0:primary-1.0;
-      sampleColor=mix(sampleColor,texture2DLodEXT(rasterMap,uv,adjacent),weight);
-    }
-    return sampleColor;
-  #else
-    return texture2D(rasterMap,uv);
-  #endif
-}
-`;
-
-/** Add the shared sampler to text/image shaders that already declare rasterMap
- * and vRasterUV. The default is settled; TriangleEffect supplies each facet's
- * existing phase without another clock, attribute buffer or per-frame JS work. */
-export function applyRasterSamplingShader(material){
-  material.defines={...material.defines,THD_RASTER_TEXTURE:1};
-  material.extensions={...material.extensions,derivatives:true,shaderTextureLOD:true};
-  material.vertexShader='varying float vRasterQuality;\n'+material.vertexShader;
-  material.vertexShader=material.vertexShader.replace(/void main\(\)\s*\{/,'void main(){ vRasterQuality=1.0;');
-  const main=material.fragmentShader.indexOf('void main');
-  material.fragmentShader=material.fragmentShader.slice(0,main)+rasterSamplingShader+material.fragmentShader.slice(main);
-  material.fragmentShader=material.fragmentShader.replace('texture2D(rasterMap,vRasterUV)','thdRasterSample(vRasterUV)');
-}
-function lease(material,surface){
-  surface.refs++;materials.set(material,surface);let released=false;
-  return ()=>{if(released)return;released=true;materials.delete(material);if(--surface.refs===0){surface.texture.dispose();surfaces.delete(surface.raster);}};
-}
-export function retainRasterTexture(source,target){
-  const surface=materials.get(source);if(!surface)return null;
-  // ShaderMaterial.clone clones texture uniforms. Use the shared source instead
-  // of uploading an identical new image for each partial deletion.
-  if(target.uniforms.rasterMap.value!==surface.texture)target.uniforms.rasterMap.value.dispose();
-  target.uniforms.rasterMap.value=surface.texture;
-  return lease(target,surface);
-}
-export function applyRasterTextureShader(material,{mask=true}={}){
-  material.vertexShader='attribute vec2 rasterUV; varying vec2 vRasterUV;\n'+material.vertexShader;
-  material.vertexShader=material.vertexShader.replace('void main() {','void main() { vRasterUV=rasterUV;');
-  material.fragmentShader='uniform sampler2D rasterMap; varying vec2 vRasterUV;\n'+material.fragmentShader;
-  material.fragmentShader=material.fragmentShader.replace('float coverage =', 'vec4 rasterSample=texture2D(rasterMap,vRasterUV); float coverage =');
-  material.fragmentShader=material.fragmentShader.replace('max(max(vColor.r, vColor.g), vColor.b) * brightness','rasterSample.a * max(max(vColor.r, vColor.g), vColor.b) * min(brightness, 1.0)');
-  if(!mask)material.fragmentShader=material.fragmentShader.replace('vec4(tint * min(1.0, diffuse + sheen), coverage)', 'vec4(rasterSample.rgb * tint * min(1.0, diffuse + sheen), coverage)');
-  applyRasterSamplingShader(material);
-}
+// Text and image surfaces share one texture per raster (not per triangle).
+// References include deletion ghosts, which can outlive their source scene mesh.
+const surfaces=new WeakMap(),materials=new WeakMap();
+export function attachRasterTexture(THREE,material,raster,{lodBias=raster.mask===false?0:-.75}={}){
+  if(!Number.isFinite(lodBias))throw TypeError('A finite raster LOD bias is required');
+  let surface=surfaces.get(raster);
+  if(!surface){
+    const texture=new THREE.DataTexture(raster.rgba,raster.width,raster.height,THREE.RGBAFormat,THREE.UnsignedByteType);
+    if(raster.mask===false)texture.colorSpace=THREE.SRGBColorSpace;
+    // One bilinear mip fetch while moving; the shader adds the adjacent mip only
+    // near the resting pose. Sampling policy never mutates a shared texture.
+    texture.minFilter=THREE.LinearMipmapNearestFilter;texture.magFilter=THREE.LinearFilter;texture.generateMipmaps=true;texture.needsUpdate=true;
+    surface={texture,refs:0,raster};surfaces.set(raster,surface);
+  }
+  material.uniforms.rasterMap={value:surface.texture};
+  material.uniforms.rasterSize={value:new THREE.Vector2(raster.width,raster.height)};
+  material.uniforms.rasterLodBias={value:lodBias};
+  return lease(material,surface);
+}
+// Derivatives describe this triangle's current projected texture footprint.
+// Explicit LOD is core in WebGL2 (Three aliases texture2DLodEXT) and optional in
+// WebGL1. Without it, keep a single conventional texture lookup as a safe fallback.
+const rasterSamplingShader=`
+uniform vec2 rasterSize;
+uniform float rasterLodBias;
+varying float vRasterQuality;
+vec4 thdRasterSample(vec2 uv){
+  #if __VERSION__ >= 300 || defined(GL_EXT_shader_texture_lod)
+    vec2 dx=dFdx(uv*rasterSize),dy=dFdy(uv*rasterSize);
+    float footprint=max(max(dot(dx,dx),dot(dy,dy)),0.00000001);
+    float lastLevel=floor(log2(max(max(rasterSize.x,rasterSize.y),1.0)));
+    float lod=clamp(0.5*log2(footprint)+rasterLodBias,0.0,lastLevel);
+    float primary=floor(lod+0.5);
+    vec4 sampleColor=texture2DLodEXT(rasterMap,uv,primary);
+    float weight=abs(lod-primary)*clamp(vRasterQuality,0.0,1.0);
+    if(weight>0.0){
+      float adjacent=primary<lod?primary+1.0:primary-1.0;
+      sampleColor=mix(sampleColor,texture2DLodEXT(rasterMap,uv,adjacent),weight);
+    }
+    return sampleColor;
+  #else
+    return texture2D(rasterMap,uv);
+  #endif
+}
+`;
+
+/** Add the shared sampler to text/image shaders that already declare rasterMap
+ * and vRasterUV. The default is settled; TriangleEffect supplies each facet's
+ * existing phase without another clock, attribute buffer or per-frame JS work. */
+export function applyRasterSamplingShader(material){
+  material.defines={...material.defines,THD_RASTER_TEXTURE:1};
+  material.extensions={...material.extensions,derivatives:true,shaderTextureLOD:true};
+  material.vertexShader='varying float vRasterQuality;\n'+material.vertexShader;
+  material.vertexShader=material.vertexShader.replace(/void main\(\)\s*\{/,'void main(){ vRasterQuality=1.0;');
+  const main=material.fragmentShader.indexOf('void main');
+  material.fragmentShader=material.fragmentShader.slice(0,main)+rasterSamplingShader+material.fragmentShader.slice(main);
+  material.fragmentShader=material.fragmentShader.replace('texture2D(rasterMap,vRasterUV)','thdRasterSample(vRasterUV)');
+}
+function lease(material,surface){
+  surface.refs++;materials.set(material,surface);let released=false;
+  return ()=>{if(released)return;released=true;materials.delete(material);if(--surface.refs===0){surface.texture.dispose();surfaces.delete(surface.raster);}};
+}
+export function retainRasterTexture(source,target){
+  const surface=materials.get(source);if(!surface)return null;
+  // ShaderMaterial.clone clones texture uniforms. Use the shared source instead
+  // of uploading an identical new image for each partial deletion.
+  if(target.uniforms.rasterMap.value!==surface.texture)target.uniforms.rasterMap.value.dispose();
+  target.uniforms.rasterMap.value=surface.texture;
+  return lease(target,surface);
+}
+export function applyRasterTextureShader(material,{mask=true}={}){
+  material.vertexShader='attribute vec2 rasterUV; varying vec2 vRasterUV;\n'+material.vertexShader;
+  material.vertexShader=material.vertexShader.replace('void main() {','void main() { vRasterUV=rasterUV;');
+  material.fragmentShader='uniform sampler2D rasterMap; varying vec2 vRasterUV;\n'+material.fragmentShader;
+  material.fragmentShader=material.fragmentShader.replace('float coverage =', 'vec4 rasterSample=texture2D(rasterMap,vRasterUV); float coverage =');
+  material.fragmentShader=material.fragmentShader.replace('max(max(vColor.r, vColor.g), vColor.b) * brightness','rasterSample.a * max(max(vColor.r, vColor.g), vColor.b) * min(brightness, 1.0)');
+  if(!mask)material.fragmentShader=material.fragmentShader.replace('vec4(tint * min(1.0, diffuse + sheen), coverage)', 'vec4(rasterSample.rgb * tint * min(1.0, diffuse + sheen), coverage)');
+  applyRasterSamplingShader(material);
+}

package/src/raster-texture-mesh.js

@@ -1,35 +1,35 @@
-// Shared raster -> UV triangle grid for font masks and RGBA images. No color
-// averaging, alpha quantization or triangle merging. All filtering is on the GPU.
-export function rasterToTextureMesh(rgba,width,height,divisions,{filterRadius=.5,aspect=width/height}={}){
-  if(!Number.isInteger(width)||width<1||!Number.isInteger(height)||height<1||rgba.length!==width*height*4)throw RangeError('Invalid raster');
-  if(!Number.isInteger(divisions)||divisions<1||divisions>256)throw RangeError('Invalid divisions');
-  if(!Number.isFinite(filterRadius)||filterRadius<.5)throw RangeError('Invalid texture filter support');
-  if(!Number.isFinite(aspect)||aspect<=0)throw RangeError('Invalid grid aspect');
-  const rows=divisions,columns=Math.max(1,Math.round(aspect*rows));
-  const cw=width/columns,ch=height/rows,occupied=new Uint8Array(rows*columns);
-  // Conservative filter support: half a texel for bilinear filtering by default;
-  // image surfaces may request the wider footprint used by minified mipmaps.
-  // A thin line or isolated pixel cannot be lost to sparse point sampling.
-  for(let y=0;y<height;y++)for(let x=0;x<width;x++){
-    if(!rgba[(y*width+x)*4+3])continue;
-    const x0=Math.max(0,x-filterRadius),x1=Math.min(width,x+1+filterRadius),y0=Math.max(0,y-filterRadius),y1=Math.min(height,y+1+filterRadius);
-    for(let row=Math.floor(y0/ch);row<=Math.min(rows-1,Math.floor(y1/ch));row++)for(let col=Math.floor(x0/cw);col<=Math.min(columns-1,Math.floor(x1/cw));col++){
-      const at=row*columns+col;if(occupied[at]===3)continue;
-      const left=Math.max(0,x0/cw-col),right=Math.min(1,x1/cw-col),top=Math.max(0,y0/ch-row),bottom=Math.min(1,y1/ch-row);
-      const even=(row+col)%2===0;
-      if(even?left+top<=1:top<=right)occupied[at]|=1;
-      if(even?right+bottom>=1:bottom>=left)occupied[at]|=2;
-    }
-  }
-  let triangleCount=0;for(const bits of occupied)triangleCount+=(bits&1?1:0)+(bits&2?1:0);
-  const coordinates=new Float64Array(triangleCount*6),uvs=new Float32Array(triangleCount*6),coverage=new Uint8Array(triangleCount).fill(6);
-  let at=0;
-  for(let row=0;row<rows;row++)for(let col=0;col<columns;col++){
-    const left=col*cw,right=(col+1)*cw,top=row*ch,bottom=(row+1)*ch,even=(row+col)%2===0;
-    for(let side=0;side<2;side++)if(occupied[row*columns+col]&(1<<side)){
-      const points=even?[right,top,side?right:left,bottom,left,side?bottom:top]:[left,top,side?left:right,bottom,right,side?bottom:top];
-      coordinates.set(points,at);for(let i=0;i<6;i++)uvs[at+i]=points[i]/(i%2?height:width);at+=6;
-    }
-  }
-  return {coordinates,uvs,coverage,triangleCount};
-}
+// Shared raster -> UV triangle grid for font masks and RGBA images. No color
+// averaging, alpha quantization or triangle merging. All filtering is on the GPU.
+export function rasterToTextureMesh(rgba,width,height,divisions,{filterRadius=.5,aspect=width/height}={}){
+  if(!Number.isInteger(width)||width<1||!Number.isInteger(height)||height<1||rgba.length!==width*height*4)throw RangeError('Invalid raster');
+  if(!Number.isInteger(divisions)||divisions<1||divisions>256)throw RangeError('Invalid divisions');
+  if(!Number.isFinite(filterRadius)||filterRadius<.5)throw RangeError('Invalid texture filter support');
+  if(!Number.isFinite(aspect)||aspect<=0)throw RangeError('Invalid grid aspect');
+  const rows=divisions,columns=Math.max(1,Math.round(aspect*rows));
+  const cw=width/columns,ch=height/rows,occupied=new Uint8Array(rows*columns);
+  // Conservative filter support: half a texel for bilinear filtering by default;
+  // image surfaces may request the wider footprint used by minified mipmaps.
+  // A thin line or isolated pixel cannot be lost to sparse point sampling.
+  for(let y=0;y<height;y++)for(let x=0;x<width;x++){
+    if(!rgba[(y*width+x)*4+3])continue;
+    const x0=Math.max(0,x-filterRadius),x1=Math.min(width,x+1+filterRadius),y0=Math.max(0,y-filterRadius),y1=Math.min(height,y+1+filterRadius);
+    for(let row=Math.floor(y0/ch);row<=Math.min(rows-1,Math.floor(y1/ch));row++)for(let col=Math.floor(x0/cw);col<=Math.min(columns-1,Math.floor(x1/cw));col++){
+      const at=row*columns+col;if(occupied[at]===3)continue;
+      const left=Math.max(0,x0/cw-col),right=Math.min(1,x1/cw-col),top=Math.max(0,y0/ch-row),bottom=Math.min(1,y1/ch-row);
+      const even=(row+col)%2===0;
+      if(even?left+top<=1:top<=right)occupied[at]|=1;
+      if(even?right+bottom>=1:bottom>=left)occupied[at]|=2;
+    }
+  }
+  let triangleCount=0;for(const bits of occupied)triangleCount+=(bits&1?1:0)+(bits&2?1:0);
+  const coordinates=new Float64Array(triangleCount*6),uvs=new Float32Array(triangleCount*6),coverage=new Uint8Array(triangleCount).fill(6);
+  let at=0;
+  for(let row=0;row<rows;row++)for(let col=0;col<columns;col++){
+    const left=col*cw,right=(col+1)*cw,top=row*ch,bottom=(row+1)*ch,even=(row+col)%2===0;
+    for(let side=0;side<2;side++)if(occupied[row*columns+col]&(1<<side)){
+      const points=even?[right,top,side?right:left,bottom,left,side?bottom:top]:[left,top,side?left:right,bottom,right,side?bottom:top];
+      coordinates.set(points,at);for(let i=0;i<6;i++)uvs[at+i]=points[i]/(i%2?height:width);at+=6;
+    }
+  }
+  return {coordinates,uvs,coverage,triangleCount};
+}