@ev-ry/fx 0.1.0-rc.1

package/src/text-edit-effect.js

@@ -0,0 +1,101 @@
+import {TriangleEffect} from './triangle-effect.js';
+import {insertedRange,remapInsertionRange} from './insertion-range.js';
+import {textEditMotions} from './text-edit-motions.js';
+import {setTextMotionCharacterCenters} from './text-motion-character-centers.js';
+import {retainRasterTexture} from './raster-texture-material.js';
+import {ensureTextMotionContour} from './text-motion-contour.js';
+
+// Text-specific ranges and deletion ghosts adapt the shared triangle timeline.
+export class TextEditEffect extends TriangleEffect {
+  prepareCharacterCenters(view,characterRectangles){
+    const frame=textEditMotions[this.mode].characterFrame;
+    if(!textEditMotions[this.mode].characterCenters&&!frame&&!this.settings.bounceLines)return;
+    const floor=textEditMotions[this.mode].characterFloor||this.settings.bounceLines;
+    if(this.characterView===view&&this.characterVersion===view.version&&this.characterFloor===floor&&this.characterFrame===frame)return;
+    this.decorate(view);
+    setTextMotionCharacterCenters(this.THREE,view,characterRectangles?.()||[],{floor,frame});
+    this.characterView=view;this.characterVersion=view.version;this.characterFloor=floor;this.characterFrame=frame;
+  }
+  enqueue(before,after,inputType){
+    const range=insertedRange(before,after,inputType);if(!range)return false;
+    if(this.text!==null&&this.text!==before.text)this.cancel();
+    const delta=after.text.length-before.text.length,oldEnd=range.end-delta;
+    this.jobs=this.jobs.flatMap(job=>remapInsertionRange(job.range,range.start,oldEnd,delta).map(piece=>({...job,range:piece})));
+    this.jobs.push({id:++this.sequence,seed:this.randomSeed(),range,started:null,rectangles:[]});
+    this.text=after.text;this.runs++;return true;
+  }
+  bind(view,rectanglesForRange,em,now,characterRectangles){
+    // Retain only seeds/rectangles for the current layout, never a mesh/history.
+    // A reshape invalidates old origins; active jobs are rebound below.
+    if(this.boundView!==view||this.boundVersion!==view.version)this.settledJobs=[];
+    this.boundView=view;this.boundVersion=view.version;
+    this.decorate(view);this.uniforms.dustEm.value=em;
+    this.prepareCharacterCenters(view,characterRectangles);
+    for(const job of this.jobs){job.rectangles=rectanglesForRange(job.range);job.started??=now;}
+    this.jobs=this.jobs.filter(job=>job.rectangles.length);
+    this.step(now);return this.active;
+  }
+  remove(before,after,range,view,rectangles,em,now,characterRectangles){
+    const exitMode=this.exitMode,samePath=exitMode===this.mode;
+    // Preserve the last visible timeline and random paths, including arrivals
+    // that settled in this layout. Initial/programmatic text has no prior path.
+    const settled=this.boundView===view&&this.boundVersion===view.version?this.settledJobs:[];
+    const interrupted=[...this.jobs,...settled].filter(job=>job.rectangles.some(r=>rectangles.some(s=>r.x<s.x+s.width&&r.x+r.width>s.x&&r.y<s.y+s.height&&r.y+r.height>s.y))).map(job=>({...job,started:null,fromAge:job.started===null?0:Math.max(0,Math.min(1,((this.lastTime??now)-job.started)/this.duration))}));
+    const delta=after.text.length-before.text.length;
+    this.jobs=this.jobs.flatMap(job=>remapInsertionRange(job.range,range.start,range.end,delta).map(piece=>({...job,range:piece})));
+    this.settledJobs=[];
+    this.text=after.text;
+    if(!rectangles.length||!view.scene.parent)return false;
+    this.decorate(view);
+    this.prepareCharacterCenters(view,characterRectangles);
+    // A different removal preset starts from the complete retained facets. Its
+    // metadata must use the original full character, before filtering deletions.
+    if(!samePath){
+      const motion=textEditMotions[exitMode];
+      if(motion.characterCenters||motion.characterFrame||this.settings.bounceLines)
+        setTextMotionCharacterCenters(this.THREE,view,characterRectangles?.()||[],{floor:motion.characterFloor||this.settings.bounceLines,frame:motion.characterFrame});
+      // Extra attributes are shared by both modes; invalidate the arrival cache
+      // so a subsequent layout bind can refresh any requested metadata.
+      this.characterView=null;
+    }
+    const THREE=this.THREE,group=new THREE.Group(),sharedGroups=new Map();
+    group.position.copy(view.scene.position);group.quaternion.copy(view.scene.quaternion);group.scale.copy(view.scene.scale);
+    for(const [key,{mesh}] of view.sharedGroups){
+      // Retain only departing triangles, not another complete copy of the paragraph.
+      const original=mesh.geometry,position=original.getAttribute('position'),offsets=original.getAttribute('glyphOffset');
+      if(textEditMotions[exitMode].contour)ensureTextMotionContour(THREE,original);
+      const names=['position','color','delay'];if(original.getAttribute('dustEdge'))names.push('dustEdge');
+      if(original.getAttribute('rasterUV'))names.push('rasterUV');
+      if(original.getAttribute('dustCharacterSide'))names.push('dustCharacterSide');
+      if(original.getAttribute('dustCharacterFrame'))names.push('dustCharacterFrame');
+      if(original.getAttribute('dustFloor'))names.push('dustFloor');
+      if(original.getAttribute('dustCeiling'))names.push('dustCeiling');
+      for(const name of ['dustCornerA','dustCornerB','dustCornerC'])if(original.getAttribute(name))names.push(name);
+      const values=Object.fromEntries([...names,'glyphOffset'].map(name=>[name,[]]));
+      for(let instance=0;instance<original.instanceCount;instance++){
+        const ox=offsets.getX(instance),oy=offsets.getY(instance),box=original.boundingBox;
+        if(box&&!rectangles.some(r=>box.max.x+ox>=r.x&&box.min.x+ox<=r.x+r.width&&box.max.y+oy>=r.y&&box.min.y+oy<=r.y+r.height))continue;
+        for(let i=0;i<position.count;i+=3){
+          const x=(position.getX(i)+position.getX(i+1)+position.getX(i+2))/3+ox,y=(position.getY(i)+position.getY(i+1)+position.getY(i+2))/3+oy;
+          if(!rectangles.some(r=>x>=r.x&&x<=r.x+r.width&&y>=r.y&&y<=r.y+r.height))continue;
+          for(let j=0;j<3;j++){
+            for(const name of names){const a=original.getAttribute(name);for(let c=0;c<a.itemSize;c++)values[name].push(a.array[(i+j)*a.itemSize+c]);}
+            values.glyphOffset.push(ox,oy);
+          }
+        }
+      }
+      if(!values.position.length)continue;
+      const geometry=new THREE.BufferGeometry();for(const [name,array] of Object.entries(values))geometry.setAttribute(name,new THREE.Float32BufferAttribute(array,name==='glyphOffset'?2:original.getAttribute(name).itemSize));
+      const material=mesh.material.clone(),source=mesh.material.userData.dustSource||mesh.material;
+      const releaseTexture=retainRasterTexture(mesh.material,material);
+      material.vertexShader=source.vertexShader;material.fragmentShader=source.fragmentShader;
+      delete material.userData.dustWind;delete material.userData.dustSource;
+      for(const name of Object.keys(material.uniforms))if(name.startsWith('dust'))delete material.uniforms[name];
+      const copy=new THREE.Mesh(geometry,material);copy.frustumCulled=false;group.add(copy);sharedGroups.set(key,{mesh:copy,releaseTexture});
+    }
+    const effect=new TextEditEffect(THREE,{departing:true,mode:exitMode,settings:this.settings});
+    effect.jobs=[...(samePath?interrupted:[]),{id:0,seed:this.randomSeed(),range,started:null,fromAge:1,rectangles}];effect.decorate({sharedGroups});effect.uniforms.dustEm.value=em;
+    const release=()=>{group.removeFromParent();for(const {mesh,releaseTexture} of sharedGroups.values()){mesh.geometry.dispose();mesh.material.dispose();releaseTexture?.();}effect.dispose();};
+    view.scene.parent.add(group);this.ghosts.push({effect,release});this.exits++;this.active=true;return true;
+  }
+}

package/src/text-edit-motions.js

@@ -0,0 +1,15 @@
+// Public catalogue contains metadata only. Paths come from shared recipes.
+import {compileTextMotionRecipe,textMotionRecipes,textMotionAliases} from './text-motion-recipes.js';
+export const DEFAULT_TEXT_EFFECT_DURATION=2000;
+const definitions=[{"key":"dust-wind","id":0,"label":"باد و گردوخاک","description":"ذرات با باد می‌آیند و هنگام حذف همان مسیر را برمی‌گردند. تنظیم قبلی باد حفظ شده است."},{"key":"smoke","id":4,"label":"دود و پراکندگی","description":"قطعه‌ها هنگام حذف رو به بالا می‌پیچند، ریز و محو می‌شوند. تایپ همان حرکت را برعکس می‌کند."},{"key":"melt","id":10,"label":"ذوب و انجماد","description":"هنگام حذف، وجه‌ها کش می‌آیند و مثل قطره پایین می‌روند؛ ورود متن، جمع‌شدن و انجماد همان قطره‌هاست."},{"key":"drifting-snow","id":28,"label":"برف معلق","description":"مثلث‌ها مثل دانه‌های برف با چرخش و نوسان جانبی آرام پایین می‌آیند و می‌نشینند؛ حذف، همان حرکت را برمی‌گرداند."}];
+const catalogue=Object.assign(Object.create(null),Object.fromEntries(definitions.map(({key,id,label,description,contour=false,characterCenters=false,characterFloor=false,characterFrame=false})=>[key,Object.freeze({id,label,description,contour,characterCenters,characterFloor,characterFrame,duration:DEFAULT_TEXT_EFFECT_DURATION})])));
+for(const [key,alias] of Object.entries(textMotionAliases))Object.defineProperty(catalogue,key,{value:catalogue[alias.base],enumerable:false});
+export const textEditMotions=Object.freeze(catalogue);
+export const isInputEffect=value=>typeof value==='string'&&(value==='none'||Object.hasOwn(textEditMotions,value));
+export const additionalTextMotion=definitions.map(({id,key})=>`
+#if THD_EDIT_MODE == ${id}
+{
+${compileTextMotionRecipe(textMotionRecipes[key])}
+}
+#endif
+`).join('');

package/src/text-effect-options.js

@@ -0,0 +1,29 @@
+// Public intent controls; the engine derives particle ranges and timing from them.
+import {normalizeTextMotionRecipe,textMotionAliases} from './text-motion-recipes.js';
+import {textEditMotions} from './text-edit-motions.js';
+export const TEXT_EFFECT_DEFAULTS=Object.freeze({particleShape:'triangle',exitEffect:'same',duration:2000,motion:1,formation:0,chaos:0.5,horizontal:1,vertical:1,flipX:false,flipY:false,exitFlipX:false,exitFlipY:false,bounceLines:false,seed:null,recipe:normalizeTextMotionRecipe()});
+export const cloneTextEffectOptions=value=>({...value,...(value.recipe?{recipe:{...value.recipe}}:{})});
+const limits={duration:[200,8000],motion:[0.25,2],formation:[-1,1],chaos:[0,1],horizontal:[0,2],vertical:[0,2],seed:[0,4294967295]};
+export function normalizeTextEffectOptions(value={},mode='dust-wind'){
+  if(!value||typeof value!=='object'||Array.isArray(value))throw TypeError('Effect settings must be an object');
+  for(const [key,v] of Object.entries(value)){
+    if(!Object.hasOwn(TEXT_EFFECT_DEFAULTS,key))throw TypeError('Unknown effect setting: '+key);
+    if(key==='exitEffect'){if(v!=='same'&&(typeof v!=='string'||!Object.keys(textEditMotions).includes(v)))throw TypeError('Invalid exitEffect');continue;}
+    if(key==='particleShape'){if(!['triangle','square'].includes(v))throw TypeError('Invalid particleShape');continue;}
+    if(key==='recipe'){normalizeTextMotionRecipe(v,mode);continue;}
+    if(key==='seed'&&v===null)continue;
+    if(limits[key]){const [lo,hi]=limits[key];if(typeof v!=='number'||!Number.isFinite(v)||v<lo||v>hi||(key==='seed'&&!Number.isInteger(v)))throw RangeError('Invalid effect setting: '+key);}
+    else if(typeof v!=='boolean')throw TypeError(key+' must be boolean');
+  }
+  return Object.freeze({...TEXT_EFFECT_DEFAULTS,bounceLines:textMotionAliases[mode]?.bounceLines??(mode==='dust-wind-upward'),...value,recipe:normalizeTextMotionRecipe(value.recipe,mode)});
+}
+
+export const textEffectOptionShader=`
+  // The distance/speed ratio retains the wind distribution at formation=0.
+  // A continuous exponent adjusts arrival spread; no fixed particle cohorts.
+  float thdFormationSeconds(float seconds,float duration,float formation){
+    if(formation==0.0)return seconds;
+    return duration*pow(clamp(seconds/duration,0.0,1.0),exp2(formation));
+  }
+`;
+

package/src/text-effect-path.js

@@ -0,0 +1,61 @@
+import {motionEnvelopeShader} from './motion-envelope.js';
+import {additionalTextMotion} from './text-edit-motions.js';
+
+// One evaluator allows optional rigid facet reflection for every preset. Only
+// the selected preset compiles; extra corner evaluations run only with bounce.
+export const textEffectPathShader=`${motionEnvelopeShader}
+vec3 thdPresetPosition(vec3 p,vec2 dustTarget,vec2 particle,vec4 r,vec4 clock,vec2 travel,float t,float seed,float drift,float pace){
+  float remain=1.0-t;
+  vec3 recipeOrigin=p;
+  vec2 cellSize=vec2(max(dustEm,0.0001));
+  vec2 cellMin=thdMotionCell(dustTarget,r.xy,dustEm);
+  #if THD_EDIT_CHARACTER_FRAME == 1
+  if(dustCharacterFrame.z>0.0&&dustCharacterFrame.w>0.0){
+    cellMin=dustCharacterFrame.xy+glyphOffset;
+    cellSize=dustCharacterFrame.zw;
+  }
+  #endif
+  vec2 cellCenter=cellMin+cellSize*0.5;
+  vec2 cellUV=clamp((dustTarget-cellMin)/cellSize,0.0,1.0);
+  float across=cellUV.x;
+  if(clock.y<0.0)across=1.0-across;
+  {${additionalTextMotion}}
+  if(dustRecipeDirection!=vec2(1.0,0.0)){
+    vec2 delta=p.xy-recipeOrigin.xy;
+    float sine=clock.y*dustRecipeDirection.y;
+    p.xy=recipeOrigin.xy+vec2(dustRecipeDirection.x*delta.x-sine*delta.y,sine*delta.x+dustRecipeDirection.x*delta.y);
+  }
+  if(dustRecipeDepth!=1.0)p.z=recipeOrigin.z+(p.z-recipeOrigin.z)*dustRecipeDepth;
+  dustGlow*=dustRecipeGlow;
+  if(dustRecipePalette.x>=0.0)dustGlowColor=dustRecipePalette;
+  return p;
+}
+`;
+export const textEffectApplicationShader=`
+  vec3 original=p;
+  p=thdPresetPosition(original,dustTarget,particle,r,clock,travel,t,seed,drift,pace);
+  // Regulate the shared triangle centre, preserving facet shape and orientation.
+  vec3 center=vec3(dustTarget,original.z);
+  float savedGlow=dustGlow,savedOutline=dustOutline;vec3 savedGlowColor=dustGlowColor;
+  vec3 moved=thdPresetPosition(center,dustTarget,particle,r,clock,travel,t,seed,drift,pace);
+  dustGlow=savedGlow;dustOutline=savedOutline;dustGlowColor=savedGlowColor;
+  vec3 delta=moved-center;
+  vec3 regulated=thdRegulateMotion(delta,dustEm);
+  vec3 adjustment=regulated-delta;
+  #if THD_EDIT_ADJUST == 1
+  adjustment+=regulated*(dustTransform-vec3(1.0));
+  #endif
+  p+=adjustment;
+  #if THD_EDIT_BOUNCE == 1
+  if(dustBounce>0.5 && t<1.0){
+    vec3 a=thdPresetPosition(dustCornerA+vec3(glyphOffset,0.0),dustTarget,particle,r,clock,travel,t,seed,drift,pace)+adjustment;
+    vec3 b=thdPresetPosition(dustCornerB+vec3(glyphOffset,0.0),dustTarget,particle,r,clock,travel,t,seed,drift,pace)+adjustment;
+    vec3 c=thdPresetPosition(dustCornerC+vec3(glyphOffset,0.0),dustTarget,particle,r,clock,travel,t,seed,drift,pace)+adjustment;
+    float centerY=(a.y+b.y+c.y)/3.0;
+    float low=dustFloor.x+glyphOffset.y+centerY-min(a.y,min(b.y,c.y));
+    float high=dustCeiling.x+glyphOffset.y-max(a.y,max(b.y,c.y))+centerY;
+    float span=high-low;
+    if(span>0.000001)p.y+=low+span-abs(mod(centerY-low,2.0*span)-span)-centerY;
+  }
+  #endif
+`;

package/src/text-mesh-density.js

@@ -0,0 +1,36 @@
+import {DIVISIONS} from './mesh-generator-core.js';
+
+// Density is measured in CSS pixels, independent of DPR, text length and color.
+// One nominal 16px em uses 16 rows. Above that, square-root density growth
+// makes a full 2D grid grow linearly with font size, not its square.
+export function normalizeTextMeshOptions({textRendering='texture',divisions=textRendering==='texture'?'auto':36}={}){
+  if(!['coverage','texture'].includes(textRendering))throw TypeError('Invalid textRendering');
+  const valid=textRendering==='texture'?(divisions==='auto'||Number.isInteger(divisions)&&divisions>=1&&divisions<=256):DIVISIONS.includes(divisions);
+  if(!valid)throw TypeError('Invalid text mesh divisions');
+  return {textRendering,divisions};
+}
+
+export function textDivisionsForSize(fontSize,current=null){
+  if(!Number.isFinite(fontSize)||fontSize<=0)return current??16;
+  // Small text never retains a denser grid through hysteresis. One row is the
+  // minimum valid grid, including for subpixel em sizes.
+  if(fontSize<16)return Math.max(1,Math.floor(fontSize));
+  const target=Math.min(72,16*Math.sqrt(fontSize/16));
+  if(current>=16&&current<=72&&Math.abs(target-current)<=Math.max(1,current*.10))return current;
+  return Math.min(72,2*Math.round(target/2));
+}
+
+// A transformed local em projected into the current viewport, in CSS pixels.
+// Reuse scratch vectors: this helper is evaluated on requested frames only.
+export function createProjectedTextSize(THREE){
+  const origin=new THREE.Vector3(),x=new THREE.Vector3(),y=new THREE.Vector3();
+  return (object,camera,canvas,em)=>{
+    const width=canvas.clientWidth,height=canvas.clientHeight;if(!width||!height)return 0;
+    object.updateWorldMatrix(true,false);camera.updateMatrixWorld(true);
+    origin.set(0,0,0).applyMatrix4(object.matrixWorld).project(camera);
+    if(origin.z< -1||origin.z>1)return 0;
+    x.set(em,0,0).applyMatrix4(object.matrixWorld).project(camera);
+    y.set(0,em,0).applyMatrix4(object.matrixWorld).project(camera);
+    return Math.max(Math.hypot((x.x-origin.x)*width/2,(x.y-origin.y)*height/2),Math.hypot((y.x-origin.x)*width/2,(y.y-origin.y)*height/2));
+  };
+}

package/src/text-motion-character-centers.js

@@ -0,0 +1,74 @@
+// Optional per-facet position and frame within a measured grapheme. Whole lines
+// may share one mesh, so its bounding-box center is not a character center.
+// Prepared on layout changes, never in the render loop. Ghosts retain this data.
+export function setTextMotionCharacterCenters(THREE,view,rectangles,{floor=false,frame=false}={}){
+  const rows=new Map();
+  for(const r of rectangles){
+    if(!(r.width>0&&r.height>0))continue;
+    const key=r.y+':'+r.height;
+    if(!rows.has(key))rows.set(key,{bottom:r.y,top:r.y+r.height,cells:[]});
+    rows.get(key).cells.push({left:r.x,right:r.x+r.width,mid:r.x+r.width/2});
+  }
+  const ordered=[...rows.values()].sort((a,b)=>a.bottom-b.bottom);
+  for(const row of ordered)row.cells.sort((a,b)=>a.left-b.left||a.right-b.right);
+  for(const {mesh} of view.sharedGroups?.values()||[]){
+    const g=mesh.geometry,centers=g.getAttribute('dustCenter'),offset=g.getAttribute('glyphOffset');
+    if(!centers||!offset||!centers.count)continue;
+    const ox=offset.getX(0),oy=offset.getY(0),values=new Float32Array(centers.count);
+    const frames=frame?new Float32Array(centers.count*4):null;
+    const floors=floor?new Float32Array(centers.count*2):null,position=g.getAttribute('position');
+    const ceilings=floor?new Float32Array(centers.count*4):null;
+    const box=g.boundingBox||(g.computeBoundingBox(),g.boundingBox);
+    const fallbackMid=(box.min.x+box.max.x)/2,fallbackWidth=box.max.x-box.min.x;
+    // Identical instanced glyphs use the same local character layout. Row choice
+    // is made using their first instance; offsets are not baked into the result.
+    const baseline=oy+(box.min.y+box.max.y)/2;
+    let row=ordered.find(r=>baseline>=r.bottom&&baseline<=r.top);
+    if(!row&&ordered.length)row=ordered.reduce((a,b)=>Math.abs((a.bottom+a.top)/2-baseline)<Math.abs((b.bottom+b.top)/2-baseline)?a:b);
+    for(let i=0;i<centers.count;i+=3){
+      const x=centers.getX(i)+ox,cells=row?.cells;let cell;
+      if(cells?.length){
+        let lo=0,hi=cells.length;
+        while(lo<hi){const mid=(lo+hi)>>>1;if(cells[mid].left<=x)lo=mid+1;else hi=mid;}
+        cell=cells[Math.max(0,lo-1)];
+        if(x>cell.right&&lo<cells.length&&Math.abs(cells[lo].mid-x)<Math.abs(cell.mid-x))cell=cells[lo];
+      }
+      const side=cell?(x-cell.mid)/Math.max((cell.right-cell.left)/2,.000001):(centers.getX(i)-fallbackMid)/Math.max(fallbackWidth/2,.000001);
+      values.fill(Math.max(-1,Math.min(1,side)),i,i+3);
+      if(frames){
+        // A single measured grapheme/line frame, not a square grid through its
+        // ink. Keep it local so identical instances and deletion ghosts agree.
+        const bounds=[cell?cell.left-ox:box.min.x,row?row.bottom-oy:box.min.y,
+          Math.max(cell?cell.right-cell.left:fallbackWidth,.000001),
+          Math.max(row?row.top-row.bottom:box.max.y-box.min.y,.000001)];
+        for(let j=0;j<3;j++)frames.set(bounds,(i+j)*4);
+      }
+      if(floors){
+        // Contact uses the lowest vertex, not the centroid. Keep facets rigid,
+        // and preserve the measured font-line bottom through partial deletion.
+        const support=centers.getY(i)-Math.min(position.getY(i),position.getY(i+1),position.getY(i+2));
+        for(let j=0;j<3;j++){floors[(i+j)*2]=row?row.bottom-oy:box.min.y;floors[(i+j)*2+1]=support;}
+        const left=Math.min(position.getX(i),position.getX(i+1),position.getX(i+2))-centers.getX(i);
+        const right=Math.max(position.getX(i),position.getX(i+1),position.getX(i+2))-centers.getX(i);
+        const upper=Math.max(position.getY(i),position.getY(i+1),position.getY(i+2))-centers.getY(i);
+        for(let j=0;j<3;j++)ceilings.set([row?row.top-oy:box.max.y,left,right,upper],(i+j)*4);
+      }
+    }
+    const existing=g.getAttribute('dustCharacterSide');
+    if(existing?.count===values.length){existing.array.set(values);existing.needsUpdate=true;}
+    else g.setAttribute('dustCharacterSide',new THREE.BufferAttribute(values,1));
+    if(frames){
+      const previous=g.getAttribute('dustCharacterFrame');
+      if(previous?.count===centers.count){previous.array.set(frames);previous.needsUpdate=true;}
+      else g.setAttribute('dustCharacterFrame',new THREE.BufferAttribute(frames,4));
+    }
+    if(floors){
+      const previous=g.getAttribute('dustFloor');
+      if(previous?.count===centers.count){previous.array.set(floors);previous.needsUpdate=true;}
+      else g.setAttribute('dustFloor',new THREE.BufferAttribute(floors,2));
+      const ceiling=g.getAttribute('dustCeiling');
+      if(ceiling?.count===centers.count){ceiling.array.set(ceilings);ceiling.needsUpdate=true;}
+      else g.setAttribute('dustCeiling',new THREE.BufferAttribute(ceilings,4));
+    }
+  }
+}

package/src/text-motion-contour.js

@@ -0,0 +1,22 @@
+// Optional contour distances on the existing de-indexed triangle mesh. No font
+// rasterization, geometry copies or frame-time work. Opposite-edge distances
+// interpolate into a continuous border, excluding internal shared diagonals.
+export function ensureTextMotionContour(THREE,geometry){
+  if(geometry.getAttribute('dustEdge'))return geometry.getAttribute('dustEdge');
+  const positions=geometry.getAttribute('position'),edges=new Map(),keys=[];
+  for(let i=0;i<positions.count;i++)keys.push(`${positions.getX(i)},${positions.getY(i)}`);
+  const edgeKey=(a,b)=>keys[a]<keys[b]?keys[a]+'|'+keys[b]:keys[b]+'|'+keys[a];
+  for(let i=0;i<positions.count;i+=3)for(let k=0;k<3;k++){
+    const key=edgeKey(i+(k+1)%3,i+(k+2)%3);edges.set(key,(edges.get(key)||0)+1);
+  }
+  const distances=new Float32Array(positions.count*3).fill(1e6);
+  for(let i=0;i<positions.count;i+=3)for(let k=0;k<3;k++){
+    const a=i+(k+1)%3,b=i+(k+2)%3;
+    if(edges.get(edgeKey(a,b))!==1)continue;
+    const dx=positions.getX(b)-positions.getX(a),dy=positions.getY(b)-positions.getY(a),length=Math.hypot(dx,dy);
+    if(length===0)continue;
+    const altitude=Math.abs(dx*(positions.getY(i+k)-positions.getY(a))-dy*(positions.getX(i+k)-positions.getX(a)))/length;
+    for(let vertex=0;vertex<3;vertex++)distances[(i+vertex)*3+k]=vertex===k?altitude:0;
+  }
+  const attribute=new THREE.BufferAttribute(distances,3);geometry.setAttribute('dustEdge',attribute);return attribute;
+}

package/src/text-motion-primitives.js

@@ -0,0 +1,91 @@
+// Small GPU building blocks shared by edit motions. All paths run from scattered
+// (t=0) to the untouched mesh (t=1); removal only reverses the captured phase.
+export const textMotionPrimitives=`
+  // Text effects live above their resting surface. Reflect inward depth instead
+  // of letting the opaque control body cut off a still-visible particle. This
+  // same path is reversed for removal; normal scene depth testing stays enabled.
+  float thdFrontDepth(float resting,float animated){
+    return resting+abs(animated-resting);
+  }
+  // A fixed one-em cell: longer edits add cells instead of stretching a path.
+  // All vertices of a triangle choose the cell using their shared centroid.
+  vec2 thdMotionCell(vec2 target,vec2 origin,float em){
+    float size=max(em,0.0001);
+    return origin+floor((target-origin)/size)*size;
+  }
+  // Preserve the tuned wind distribution for EVERY preset: no particle cohorts,
+  // no per-motion lifetime. Time = randomized distance / randomized speed.
+  vec2 thdParticleTravel(float seed,float drift,float pace,float seconds){
+    float spread=fract(seed*7.31+drift*13.71);
+    float distanceJitter=mix(0.8,1.2,spread);
+    float distance=mix(0.0,7.8,seed)*distanceJitter;
+    float speed=(7.8*1.2/max(seconds,0.001))*mix(1.0,4.0,pace);
+    return vec2(distance,distance/speed);
+  }
+  float thdMotionPhase(vec4 clock,float travelSeconds,float seconds){
+    float progress=travelSeconds>0.0?clamp(clock.x*seconds/travelSeconds,0.0,1.0):1.0;
+    float initial=travelSeconds>0.0?clamp(max(0.0,clock.z-1.0)*seconds/travelSeconds,0.0,1.0):1.0;
+    return clock.z>0.5?max(0.0,initial-progress):progress;
+  }
+  float thdStagger(float t,float order,float spread){
+    if(t>=1.0)return 1.0;
+    if(t<=0.0)return 0.0;
+    float delay=clamp(order,0.0,1.0)*spread;
+    return clamp((t-delay)/max(1.0-delay,0.001),0.0,1.0);
+  }
+  vec2 thdTurn(vec2 v,float angle){
+    return vec2(v.x*cos(angle)-v.y*sin(angle),v.x*sin(angle)+v.y*cos(angle));
+  }
+  vec3 thdFold(vec3 v,vec3 axis,float angle){
+    return v*cos(angle)+cross(axis,v)*sin(angle)+axis*dot(axis,v)*(1.0-cos(angle));
+  }
+  // Linear projected opening, while preserving each preset's initial angle.
+  // A linear angle looks almost flat too early because its projection is cosine.
+  float thdOpeningAngle(float progress,float initialAngle){
+    // Some GPU acos approximations leave a tiny angle at 1. Return exact ends.
+    if(progress>=1.0)return 0.0;
+    if(progress<=0.0)return initialAngle;
+    return acos(clamp(mix(cos(initialAngle),1.0,progress),-1.0,1.0));
+  }
+  vec3 thdHinge(vec3 point,vec3 pivot,vec3 axis,float angle){
+    return pivot+thdFold(point-pivot,axis,angle);
+  }
+  vec2 thdCurve(vec2 a,vec2 b,vec2 c,vec2 d,float t){
+    float q=1.0-t;
+    return q*q*q*a+3.0*q*q*t*b+3.0*q*t*t*c+t*t*t*d;
+  }
+  float thdPulse(float t){return 4.0*t*(1.0-t);}
+  // Bounded sinusoidal drift anchored at zero, so a shared path joins the text
+  // exactly without per-effect offsets or a separate deletion implementation.
+  float thdSway(float progress,float phase,float turns){
+    return sin(phase+progress*turns*6.2831853)-sin(phase);
+  }
+  // Ballistic drop + four diminishing rebounds. One drop time is the unit;
+  // restitution scales vertical speed at each impact (energy scales by e^2).
+  // Horizontal friction reduces speed after every impact. Result: height as
+  // a fraction of the original drop, and accumulated horizontal travel [0,1].
+  // This evaluates a pose directly, so reverse playback needs no simulation.
+  vec2 thdGravityBounce(float departure,float restitution,float friction){
+    float total=1.0,totalX=1.0,speed=restitution,slide=friction;
+    for(int i=0;i<4;i++){
+      total+=2.0*speed;totalX+=2.0*speed*slide;
+      speed*=restitution;slide*=friction;
+    }
+    float time=clamp(departure,0.0,1.0)*total;
+    if(time<=1.0)return vec2(max(0.0,1.0-time*time),time/totalX);
+    time-=1.0;
+    float distance=1.0;speed=restitution;slide=friction;
+    for(int i=0;i<4;i++){
+      float flight=2.0*speed;
+      if(time<=flight)return vec2(max(0.0,2.0*speed*time-time*time),(distance+slide*time)/totalX);
+      time-=flight;distance+=slide*flight;
+      speed*=restitution;slide*=friction;
+    }
+    return vec2(0.0,1.0);
+  }
+  float thdSpring(float t){return (1.0-t)*cos(t*10.9955743);}
+  float thdFall(float t){
+    if(t<0.64){float f=t/0.64;return 1.0-f*f;}
+    return 0.14*sin((t-0.64)/0.36*3.1415927);
+  }
+`;

package/src/text-motion-programs.js

@@ -0,0 +1 @@
+export const motionPrograms={"dust-wind":{"channels":["angle","depth","shape","sway"],"operations":[{"op":"let","type":"vec2","name":"windOrigin","value":"p.xy"},{"op":"let","type":"float","name":"windReach","value":"0.5"},{"op":"let","type":"float","name":"amplitude","value":"0.06+0.24*drift"},{"op":"let","type":"vec2","name":"face","value":"p.xy-dustTarget"},{"op":"deform","target":"face","value":"vec2(mix(1.0,2.4,remain),mix(1.0,0.32,remain))"},{"op":"set","target":"p.xy","value":"dustTarget+face"},{"op":"add","target":"p.x","value":"windReach*clock.y*dustEm*travel.x*remain"},{"op":"let","type":"float","name":"gust","value":"sin(t*12.0+particle.y*2.0+clock.w*6.283)","parameter":"sway"},{"op":"let","type":"float","name":"eddy","value":"sin(seed*6.283+t*(18.0+seed*12.0))","parameter":"sway"},{"op":"add","target":"p.y","value":"windReach*1.5*dustEm*remain*((drift-0.5)*0.55+amplitude*(gust+eddy*0.3))"},{"op":"add","target":"p.z","value":"windReach*dustEm*remain*(seed-0.5)*0.12"}],"ownFace":true},"smoke":{"channels":["angle","depth","sway","shape","spin"],"operations":[{"op":"let","type":"float","name":"phase","value":"drift*6.2831853"},{"op":"let","type":"float","name":"curl","value":"sin(remain*7.0+phase)-sin(phase)","parameter":"sway"},{"op":"deform","target":"face","value":"mix(1.0,0.65,remain)"},{"op":"turn","target":"face.xy","vector":"face.xy","angle":"(seed-0.5)*remain*6.0"},{"op":"set","target":"p","value":"vec3(dustTarget,p.z)+face"},{"op":"add","target":"p.x","value":"dustEm*remain*((drift-0.5)*1.2+clock.y*0.22+curl*0.22)"},{"op":"add","target":"p.y","value":"dustEm*remain*(0.2+seed*0.85)+dustEm*remain*curl*0.08"},{"op":"add","target":"p.z","value":"dustEm*remain*(seed-0.5)*0.28"}]},"drifting-snow":{"channels":["angle","depth","sway","shape","spin","glow","palette"],"operations":[{"op":"let","type":"float","name":"phase","value":"drift*6.2831853"},{"op":"let","type":"float","name":"sway","value":"thdSway(remain,phase,0.65+0.6*seed)","parameter":"sway"},{"op":"deform","target":"face","value":"1.0-0.35*remain"},{"op":"turn","target":"face.xy","vector":"face.xy","angle":"remain*((seed-0.5)*2.0+sway*0.6)"},{"op":"turn","target":"face.xz","vector":"face.xz","angle":"remain*0.75*sin(phase+remain*8.0)"},{"op":"set","target":"p","value":"vec3(dustTarget,p.z)+face"},{"op":"add","target":"p.x","value":"clock.y*dustEm*remain*(0.18+0.08*seed+sway*(0.18+0.12*drift))"},{"op":"add","target":"p.y","value":"dustEm*(remain*(0.75+0.85*pace)+0.07*thdPulse(t)*sin(phase+remain*7.0))"},{"op":"add","target":"p.z","value":"dustEm*remain*0.04"},{"op":"set","target":"dustGlow","value":"0.16*thdPulse(t)*remain"},{"op":"set","target":"dustGlowColor","value":"vec3(0.88,0.96,1.0)"}]},"melt":{"channels":["angle","depth","shape","glow","palette"],"operations":[{"op":"let","type":"float","name":"local","value":"thdStagger(t,seed,0.25)"},{"op":"let","type":"float","name":"flow","value":"(1.0-local)*(1.0-local)"},{"op":"deform","target":"face.xy","value":"vec2(1.0-0.76*flow,1.0+2.6*flow)"},{"op":"set","target":"p","value":"vec3(dustTarget,p.z)+face"},{"op":"subtract","target":"p.y","value":"dustEm*flow*(0.35+0.65*drift)"},{"op":"add","target":"p.x","value":"dustEm*flow*0.08*sin(particle.y*4.0+seed*6.2831853)"},{"op":"add","target":"p.z","value":"dustEm*flow*0.035"},{"op":"set","target":"dustGlow","value":"0.13*thdPulse(local)"}]}};

package/src/text-motion-recipes.js

@@ -0,0 +1,71 @@
+import {motionPrograms} from './text-motion-programs.js';
+
+const freeze=value=>{if(value&&typeof value==='object'&&!Object.isFrozen(value)){Object.values(value).forEach(freeze);Object.freeze(value);}return value;};
+// Trusted internal operation graphs. Public settings accept bounded values,
+// never expressions, GLSL, or executable source.
+export const textMotionRecipes=freeze(motionPrograms);
+export const textMotionAliases=freeze({});
+export const textRecipeControls=freeze({
+  angle:{label:'جهت حرکت',default:0,min:-180,max:180,step:15,choices:{'0':'اصلی','45':'مورب بالا','-45':'مورب پایین','90':'چرخش بالا','-90':'چرخش پایین','180':'معکوس'}},
+  depth:{label:'عمق',default:1,min:0,max:2,step:.1},
+  spin:{label:'پیچش',default:1,min:0,max:2,step:.1},
+  sway:{label:'موج و نوسان',default:1,min:0,max:2,step:.1},
+  shape:{label:'تغییر شکل مثلث‌ها',default:1,min:0,max:1.5,step:.1},
+  glow:{label:'درخشش',default:1,min:0,max:2,step:.1},
+  palette:{label:'رنگ درخشش',default:'original',choices:{original:'اصلی',cool:'آبی',warm:'گرم',mint:'نعنایی'}},
+  rebound:{label:'قدرت جهش',default:1,min:.25,max:1.5,step:.05},
+  pace:{label:'ریتم جهش',default:1,min:.25,max:2,step:.05}
+});
+export function normalizeTextMotionRecipe(value={},mode='dust-wind'){
+  if(!value||typeof value!=='object'||Array.isArray(value))throw TypeError('Recipe settings must be an object');
+  const result=Object.fromEntries(Object.entries(textRecipeControls).map(([key,control])=>[key,control.default]));
+  result.angle=textMotionAliases[mode]?.angle??(mode==='dust-wind-upward'?45:0);
+  for(const [key,v] of Object.entries(value)){
+    if(!Object.hasOwn(textRecipeControls,key))throw TypeError('Unknown recipe setting: '+key);
+    const control=textRecipeControls[key];
+    if(key==='palette'){if(typeof v!=='string'||!Object.hasOwn(control.choices,v))throw TypeError('Invalid recipe palette');}
+    else if(typeof v!=='number'||!Number.isFinite(v)||v<control.min||v>control.max)throw RangeError('Invalid recipe setting: '+key);
+    result[key]=v;
+  }
+  return Object.freeze(result);
+}
+
+// Shared compiler: expressions describe math, operations describe composition,
+// uniforms supply the bounded public intent controls.
+export function compileTextMotionRecipe(recipe){
+  if(!recipe||!Array.isArray(recipe.operations)||!recipe.operations.length)throw TypeError('Invalid motion recipe');
+  const types={face:recipe.ownFace?'vec2':'vec3'};
+  const lines=recipe.ownFace?[]:['vec3 face=p-vec3(dustTarget,p.z);'];
+  const expression=value=>{if(typeof value!=='string'||!value||/[;{}#]/.test(value))throw TypeError('Invalid recipe expression');return value;};
+  const target=value=>{if(typeof value!=='string'||!/^\w+(?:\.[xyzwrgba]{1,4})?$/.test(value))throw TypeError('Invalid recipe target');return value;};
+  for(const step of recipe.operations){
+    const v=step.value===undefined?'':expression(step.value);
+    if(step.op==='let'){
+      if(!['float','vec2','vec3','vec4','bool'].includes(step.type)||!/^\w+$/.test(step.name))throw TypeError('Invalid recipe declaration');
+      types[step.name]=step.type;lines.push(`${step.type} ${step.name}=${v};`);
+      if(step.parameter==='sway')lines.push(`${step.name}*=dustRecipeSway;`);
+      else if(step.parameter==='rebound')lines.push(`if(dustRecipeRebound!=1.0)${step.name}=clamp(${step.name}*dustRecipeRebound,0.05,0.95);`);
+      else if(step.parameter)throw TypeError('Unsupported recipe parameter');
+    }else if(['set','add','subtract','multiply'].includes(step.op)){
+      lines.push(`${target(step.target)}${{set:'=',add:'+=',subtract:'-=',multiply:'*='}[step.op]}${v};`);
+    }else if(step.op==='turn')lines.push(`${target(step.target)}=thdTurn(${expression(step.vector)},(${expression(step.angle)})*dustRecipeSpin);`);
+    else if(step.op==='hinge')lines.push(`${target(step.target)}=thdHinge(${expression(step.point)},${expression(step.pivot)},${expression(step.axis)},(${expression(step.angle)})*dustRecipeShape);`);
+    else if(step.op==='deform'){
+      const to=target(step.target),type=to.includes('.')?(to.split('.')[1].length===1?'float':'vec'+to.split('.')[1].length):types[to];
+      if(!type||type==='bool')throw TypeError('Invalid deformation type');
+      lines.push(`if(dustRecipeShape==1.0)${to}*=${v};else ${to}*=max(${type}(0.01),mix(${type}(1.0),${type}(${v}),dustRecipeShape));`);
+    }else throw TypeError('Unsupported recipe operation: '+step.op);
+  }
+  return lines.join('\n');
+}
+export const textRecipeUniformShader=`
+uniform vec2 dustRecipeDirection;
+uniform float dustRecipeDepth;
+uniform float dustRecipeSpin;
+uniform float dustRecipeSway;
+uniform float dustRecipeShape;
+uniform float dustRecipeGlow;
+uniform vec3 dustRecipePalette;
+uniform float dustRecipeRebound;
+uniform float dustRecipePace;
+`;