@ev-ry/fx 0.1.0-rc.1

package/src/text-scene.js

@@ -0,0 +1,272 @@
+import { MOTION_SAMPLES, RadialMotion } from './motion.js';
+import {attachRasterTexture,applyRasterTextureShader} from './raster-texture-material.js';
+
+const vertexShader = `
+  attribute vec3 color;
+  attribute float delay;
+  uniform vec2 angles[${MOTION_SAMPLES}];
+  uniform float radius;
+  uniform float baseline;
+  uniform float effectTime;
+  varying vec3 vColor;
+  varying vec3 vViewPosition;
+  void main() {
+    vec3 p = position + vec3(0.0, baseline, 0.0);
+    float sampleIndex = clamp(length(p.xy) / max(radius, 0.001), 0.0, 1.0) * ${MOTION_SAMPLES - 1}.0;
+    int low = min(${MOTION_SAMPLES - 2}, int(floor(sampleIndex)));
+    vec2 angle = mix(angles[low], angles[low + 1], sampleIndex - float(low));
+    float ry = p.y * cos(angle.x) - p.z * sin(angle.x);
+    float rz = p.y * sin(angle.x) + p.z * cos(angle.x);
+    p = vec3(p.x * cos(angle.y) + rz * sin(angle.y), ry, -p.x * sin(angle.y) + rz * cos(angle.y));
+    float progress = clamp((effectTime - delay) / 0.5, 0.0, 1.0);
+    vColor = color * (1.0 - pow(1.0 - progress, 3.0));
+    vec4 viewPosition = modelViewMatrix * vec4(p, 1.0);
+    vViewPosition = viewPosition.xyz;
+    gl_Position = projectionMatrix * viewPosition;
+  }
+`;
+const fragmentShader = `
+  uniform float brightness;
+  uniform vec3 tint;
+  varying vec3 vColor;
+  varying vec3 vViewPosition;
+  void main() {
+    vec3 faceNormal = normalize(cross(dFdx(vViewPosition), dFdy(vViewPosition)));
+    float facing = abs(faceNormal.z);
+    float diffuse = mix(0.16, 1.0, pow(facing, 0.72));
+    float sheen = 0.16 * pow(facing, 10.0);
+    float coverage = clamp(max(max(vColor.r, vColor.g), vColor.b) * brightness, 0.0, 1.0);
+    // Coverage belongs in alpha only; multiplying RGB by it as well darkens thin strokes twice.
+    gl_FragColor = vec4(tint * min(1.0, diffuse + sheen), coverage);
+    // CSS tint and sampled image RGB are linear in Three's working space.
+    // Encode RGB once for the render target; coverage alpha stays unchanged.
+    #include <colorspace_fragment>
+  }
+`;
+
+export class TextScene {
+  constructor(THREE, engine, scene) {
+    this.THREE = THREE;
+    this.engine = engine;
+    this.scene = scene;
+    this.motion = new RadialMotion();
+    this.resources = new Map();
+    this.lines = [];
+    this.glyphs = [];
+    this.version = 0;
+    this.effectStarted = null;
+    this.uniforms = { angles: { value: this.motion.angles }, radius: { value: 1 }, effectTime: { value: 2 }, brightness: { value: 1.25 }, tint: { value: new THREE.Color(1,1,1) } };
+  }
+
+  setText(text) {
+    const THREE = this.THREE;
+    const entries = this.engine.buildLines(text);
+    const retained = new Map();
+    const available = new Map();
+    for (const line of this.lines) {
+      const queue = available.get(line.entry.mesh) || [];
+      queue.push(line);
+      available.set(line.entry.mesh, queue);
+    }
+    this.glyphs = [];
+    this.triangleCount = 0;
+    this.lines = entries.map(entry => {
+      let geometry = retained.get(entry.mesh) || this.resources.get(entry.mesh);
+      if (!geometry) {
+        geometry = new THREE.BufferGeometry();
+        geometry.setAttribute('position', new THREE.BufferAttribute(entry.mesh.positions, 3));
+        geometry.setAttribute('color', new THREE.BufferAttribute(entry.mesh.colors, 3));
+        geometry.setAttribute('delay', new THREE.BufferAttribute(entry.mesh.delays, 1));
+        geometry.computeBoundingBox();
+      }
+      retained.set(entry.mesh, geometry);
+      let line = available.get(entry.mesh)?.shift();
+      if (!line) {
+        const material = new THREE.ShaderMaterial({
+          uniforms: { ...this.uniforms, baseline: { value: entry.baseline } },
+          vertexShader, fragmentShader, side: THREE.DoubleSide, transparent: true,
+          depthWrite: false, extensions: { derivatives: true },
+        });
+        const mesh = new THREE.Mesh(geometry, material);
+        // Positions move in the vertex shader, outside the undeformed bounding box.
+        mesh.frustumCulled = false;
+        this.scene.add(mesh);
+        line = { mesh };
+      }
+      line.entry = entry;
+      line.mesh.material.uniforms.baseline.value = entry.baseline;
+      for (const glyph of entry.mesh.glyphRects) {
+        this.glyphs.push({ ...glyph, y: glyph.y + entry.baseline, index: glyph.index + entry.offset });
+      }
+      this.triangleCount += entry.mesh.triangleCount;
+      return line;
+    });
+    for (const queue of available.values()) for (const line of queue) {
+      this.scene.remove(line.mesh);
+      line.mesh.material.dispose();
+    }
+    for (const [key, geometry] of this.resources) if (!retained.has(key)) geometry.dispose();
+    this.resources = retained;
+    this.bounds = { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity };
+    for (const { mesh, entry } of this.lines) {
+      if (!entry.mesh.positions.length) continue;
+      const box = mesh.geometry.boundingBox;
+      this.bounds.minX = Math.min(this.bounds.minX, box.min.x);
+      this.bounds.maxX = Math.max(this.bounds.maxX, box.max.x);
+      this.bounds.minY = Math.min(this.bounds.minY, box.min.y + entry.baseline);
+      this.bounds.maxY = Math.max(this.bounds.maxY, box.max.y + entry.baseline);
+    }
+    if (!Number.isFinite(this.bounds.minX)) this.bounds = { minX: -0.5, maxX: 0.5, minY: -0.5, maxY: 0.5 };
+    const b = this.bounds;
+    this.motion.radius = Math.max(0.001, Math.hypot(Math.max(Math.abs(b.minX), Math.abs(b.maxX)), Math.max(Math.abs(b.minY), Math.abs(b.maxY))));
+    this.uniforms.radius.value = this.motion.radius;
+    this.effectStarted = null;
+    this.uniforms.effectTime.value = 2;
+    this.version++;
+  }
+
+  startEffect(now) { this.effectStarted = now; this.uniforms.effectTime.value = 0; }
+
+  caretMaterial() {
+    const material = new this.THREE.ShaderMaterial({
+      uniforms: { ...this.uniforms, baseline: { value: 0 }, effectTime: { value: 2 } },
+      vertexShader, fragmentShader, side: this.THREE.DoubleSide, transparent: true,
+      depthTest: false, depthWrite: false, extensions: { derivatives: true },
+    });
+    material.defaultAttributeValues.delay = [0];
+    return material;
+  }
+
+  caretGeometry(p) {
+    // One column of square cells, at the same sampling density as the font.
+    const rows = this.engine.divisions || 48;
+    const cell = p.height / rows;
+    const positions = [], colors = [];
+    for (let row = 0; row < rows; row++) {
+      for (const [index, [u, v]] of [[0, 0], [1, 0], [1, 1], [0, 0], [1, 1], [0, 1]].entries()) {
+        positions.push(p.x + (u - 0.5) * cell, p.bottom + (row + v) * cell, 0.04);
+        const coverage = index < 3 ? 1 : 0.7;
+        colors.push(coverage, coverage, coverage);
+      }
+    }
+    const geometry = new this.THREE.BufferGeometry();
+    geometry.setAttribute('position', new this.THREE.Float32BufferAttribute(positions, 3));
+    geometry.setAttribute('color', new this.THREE.Float32BufferAttribute(colors, 3));
+    return geometry;
+  }
+
+  overlayMaterial(alpha) {
+    const material = new this.THREE.ShaderMaterial({
+      uniforms: { ...this.uniforms, baseline: { value: 0 }, effectTime: { value: 2 } },
+      vertexShader, fragmentShader: `varying vec3 vColor; void main(){gl_FragColor=vec4(vColor, ${alpha.toFixed(2)});}`,
+      side: this.THREE.DoubleSide, transparent: true, depthTest: false, depthWrite: false,
+    });
+    material.defaultAttributeValues.delay = [0];
+    return material;
+  }
+
+  step(dt, now) {
+    if (this.motion.step(dt)) this.version++;
+    if (this.effectStarted !== null) {
+      this.uniforms.effectTime.value = (now - this.effectStarted) / 1000;
+      if (this.uniforms.effectTime.value >= 1.5) this.effectStarted = null;
+    }
+    return this.motion.active || this.effectStarted !== null;
+  }
+
+  dispose() {
+    for (const line of this.lines) { this.scene.remove(line.mesh); line.mesh.material.dispose(); }
+    for (const geometry of this.resources.values()) geometry.dispose();
+    this.resources.clear();
+    this.lines = [];
+  }
+}
+
+// Shared path: one draw per distinct glyph, with one XY offset per occurrence.
+export class SharedTextScene extends TextScene {
+  setText(text) {
+    const THREE = this.THREE, scale = this.engine.scale;
+    const entries = this.engine.layout(text).entries;
+    const groups = new Map();
+    this.glyphs = []; this.triangleCount = 0;
+    for (const entry of entries) for (const item of entry.metrics.items) {
+      const { glyph, x, ch, i } = item;
+      if (!glyph) continue;
+      const baseline = entry.baseline * scale;
+      this.glyphs.push({ x: (x-glyph.drawOffsetX)*scale, y: baseline-glyph.height*scale,
+        width: glyph.width*scale, height:glyph.height*scale, character:ch,
+        index:entry.offset+entry.metrics.utf16Offsets[i] });
+      const count = glyph.meshData?.triangleCount ?? glyph.triangles?.length ?? 0;
+      if (!count) continue;
+      let offsets = groups.get(glyph);
+      if (!offsets) groups.set(glyph, offsets=[]);
+      offsets.push(x*scale, baseline);
+      this.triangleCount += count;
+    }
+    const previous = this.sharedGroups || new Map(), next = new Map();
+    this.bounds = {minX:Infinity,maxX:-Infinity,minY:Infinity,maxY:-Infinity};
+    this.bufferBytes = 0;this.textureBytes=0;
+    for (const [glyph, offsets] of groups) {
+      let resource = previous.get(glyph);
+      if (resource && resource.scale !== scale) { this.releaseShared(resource); resource=null; }
+      if (!resource) {
+        const local = this.engine.buildLine({items:[{glyph,x:0,ch:'',i:0}],utf16Offsets:[0]});
+        const geometry = new THREE.InstancedBufferGeometry();
+        geometry.setAttribute('position',new THREE.BufferAttribute(local.positions,3));
+        geometry.setAttribute('color',new THREE.BufferAttribute(local.colors,3));
+        geometry.setAttribute('delay',new THREE.BufferAttribute(local.delays,1));
+        geometry.computeBoundingBox();
+        const shader = vertexShader.replace('attribute float delay;', 'attribute float delay; attribute vec2 glyphOffset;')
+          .replace('position + vec3(0.0, baseline, 0.0)', 'position + vec3(glyphOffset, 0.0)')
+          .replace('(effectTime - delay)', '(effectTime - fract(delay + dot(glyphOffset, vec2(0.173, 0.317))))');
+        const material = new THREE.ShaderMaterial({uniforms:{...this.uniforms,baseline:{value:0}},
+          vertexShader:shader,fragmentShader,side:THREE.DoubleSide,transparent:true,depthWrite:false,extensions:{derivatives:true}});
+        let releaseTexture=null;
+        if(glyph.rasterSurface){
+          geometry.setAttribute('rasterUV',new THREE.BufferAttribute(glyph.meshData.uvs,2));
+          applyRasterTextureShader(material,{mask:glyph.rasterSurface.mask!==false});
+          releaseTexture=attachRasterTexture(THREE,material,glyph.rasterSurface);
+        }
+        const mesh = new THREE.Mesh(geometry,material);mesh.frustumCulled=false;this.scene.add(mesh);
+        resource={mesh,scale,releaseTexture};
+      }
+      const geometry=resource.mesh.geometry;
+      let attribute=geometry.getAttribute('glyphOffset');
+      // Keep the same GPU buffer while capacity suffices; edits upload only offsets.
+      if (!attribute || attribute.count < offsets.length/2 ||
+          (attribute.array.length > 32 && offsets.length < attribute.array.length / 4)) {
+        // Replacing a BufferAttribute does not release its old GPU buffer in Three.
+        if (attribute) geometry.dispose();
+        const capacity = 2 ** Math.ceil(Math.log2(Math.max(8, offsets.length)));
+        attribute=new THREE.InstancedBufferAttribute(new Float32Array(capacity),2);
+        geometry.setAttribute('glyphOffset',attribute);
+      }
+      let changed = geometry.instanceCount !== offsets.length / 2 || attribute.version === 0;
+      for (let i=0; i<offsets.length && !changed; i++) changed = attribute.array[i] !== Math.fround(offsets[i]);
+      if (changed) {
+        attribute.array.set(offsets);
+        attribute.updateRange.offset=0; attribute.updateRange.count=offsets.length;
+        attribute.needsUpdate=true;
+      }
+      geometry.instanceCount=offsets.length/2;
+      const box=geometry.boundingBox;
+      for(let i=0;i<offsets.length;i+=2){
+        this.bounds.minX=Math.min(this.bounds.minX,box.min.x+offsets[i]);
+        this.bounds.maxX=Math.max(this.bounds.maxX,box.max.x+offsets[i]);
+        this.bounds.minY=Math.min(this.bounds.minY,box.min.y+offsets[i+1]);
+        this.bounds.maxY=Math.max(this.bounds.maxY,box.max.y+offsets[i+1]);
+      }
+      for(const attr of Object.values(geometry.attributes))this.bufferBytes+=attr.array.byteLength;
+      if(glyph.rasterSurface)this.textureBytes+=glyph.rasterSurface.rgba.byteLength;
+      next.set(glyph,resource);
+    }
+    for(const [glyph,resource] of previous)if(!next.has(glyph))this.releaseShared(resource);
+    this.sharedGroups=next;this.drawCalls=next.size;
+    if(!Number.isFinite(this.bounds.minX))this.bounds={minX:-.5,maxX:.5,minY:-.5,maxY:.5};
+    const b=this.bounds;
+    this.motion.radius=Math.max(.001,Math.hypot(Math.max(Math.abs(b.minX),Math.abs(b.maxX)),Math.max(Math.abs(b.minY),Math.abs(b.maxY))));
+    this.uniforms.radius.value=this.motion.radius;this.effectStarted=null;this.uniforms.effectTime.value=2;this.version++;
+  }
+  releaseShared(resource){this.scene.remove(resource.mesh);resource.mesh.geometry.dispose();resource.mesh.material.dispose();resource.releaseTexture?.();}
+  dispose(){for(const resource of this.sharedGroups?.values() || [])this.releaseShared(resource);this.sharedGroups?.clear();super.dispose();}
+}

package/src/triangle-coverage.js

@@ -0,0 +1,25 @@
+// Ten evenly distributed interior barycentric points (four triangular rows).
+// Approximate coverage for runtime text. These samples cannot prove that a
+// triangle is entirely opaque; geometric merging must use exact integration.
+const patterns=[];
+for(const parity of [0,1])for(const side of [0,1]){
+  const pair=parity===0
+    ? [[[1,0],[0,1],[0,0]],[[1,0],[1,1],[0,1]]]
+    : [[[0,0],[1,1],[1,0]],[[0,0],[0,1],[1,1]]];
+  const points=[];
+  for(let i=0;i<=3;i++)for(let j=0;j<=3-i;j++){
+    const weights=[(i+1/3)/4,(j+1/3)/4,(3-i-j+1/3)/4];
+    points.push(pair[side].reduce((v,p,k)=>v+p[0]*weights[k],0),pair[side].reduce((v,p,k)=>v+p[1]*weights[k],0));
+  }
+  patterns.push(points);
+}
+export function integrateTenSamples(rgba,width,height,rows,columns,cw,ch,sums,counts){
+  for(let row=0;row<rows;row++)for(let column=0;column<columns;column++)for(let side=0;side<2;side++){
+    const points=patterns[((row+column)%2)*2+side];let sum=0;
+    for(let i=0;i<20;i+=2){
+      const x=Math.min(width-1,Math.floor((column+points[i])*cw)),y=Math.min(height-1,Math.floor((row+points[i+1])*ch));
+      sum+=rgba[(y*width+x)*4+3]/255;
+    }
+    const at=(row*columns+column)*2+side;sums[at]=sum;counts[at]=10;
+  }
+}

package/src/triangle-effect.js

@@ -0,0 +1,194 @@
+import {particleCenters} from './particle-centers.js';
+import {textEditMotions} from './text-edit-motions.js';
+import {normalizeTextEffectOptions,cloneTextEffectOptions,textEffectOptionShader} from './text-effect-options.js';
+import {textRecipeUniformShader} from './text-motion-recipes.js';
+import {textEffectPathShader,textEffectApplicationShader} from './text-effect-path.js';
+import {textMotionPrimitives} from './text-motion-primitives.js';
+import {ensureTextMotionContour} from './text-motion-contour.js';
+import {ensureTriangleMotionFrame} from './triangle-motion-frame.js';
+
+
+// Rectangle-driven triangle animation shared by text edits and image surfaces.
+// Editing/range mapping stays in TextEditEffect; existing clocks and paths are unchanged.
+export class TriangleEffect {
+  constructor(THREE,{duration,departing=false,mode='dust-wind',settings={}}={}){
+    const motion=textEditMotions[mode];if(!motion)throw TypeError('Invalid text motion');
+    duration??=motion.duration;this.mode=mode;
+    this.THREE=THREE;this.duration=duration;this.departing=departing;this.active=false;this.jobs=[];this.ghosts=[];this.text=null;this.runs=0;this.exits=0;this.sequence=0;this.lastTime=null;
+    this.settledJobs=[];this.boundView=null;this.boundVersion=null;
+    this.uniforms={dustEnabled:{value:0},dustMotion:{value:motion.id},dustMaskOnly:{value:departing?1:0},dustEm:{value:1},dustSeconds:{value:duration/1000},dustCount:{value:0},dustWidth:{value:1},dustData:{value:null}};
+    this.allocate(1);
+    this.materials=new Set();
+    this.uniforms.dustTransform={value:new THREE.Vector3(1,1,1)};
+    this.uniforms.dustFormation={value:0};this.uniforms.dustChaos={value:1};this.uniforms.dustBounce={value:0};
+    this.uniforms.dustRecipeDirection={value:new THREE.Vector2(1,0)};
+    this.uniforms.dustRecipePalette={value:new THREE.Vector3(-1,-1,-1)};
+    for(const name of ['Depth','Spin','Sway','Shape','Glow','Rebound','Pace'])this.uniforms['dustRecipe'+name]={value:1};
+    this.configure({...settings,...(duration===motion.duration?{}:{duration})});
+  }
+  get pending(){return this.jobs.some(job=>job.started===null);}
+  get exitMode(){return this.settings.exitEffect==='same'?this.mode:this.settings.exitEffect;}
+  setMode(mode){
+    const motion=textEditMotions[mode];if(!motion)throw TypeError('Invalid text motion');
+    if(mode===this.mode)return;
+    this.cancel();this.mode=mode;
+    this.uniforms.dustMotion.value=motion.id;this.configure();
+    for(const material of this.materials)this.syncMaterialDefines(material);
+  }
+  configure(settings={}){
+    const next=normalizeTextEffectOptions(settings,this.mode);
+    if(this.settings&&JSON.stringify(next)===JSON.stringify(this.settings))return;
+    this.cancel();this.settings=next;this.duration=next.duration;
+    this.uniforms.dustSeconds.value=next.duration/1000;
+    const sx=next.flipX!==(this.departing&&next.exitFlipX)?-1:1,sy=next.flipY!==(this.departing&&next.exitFlipY)?-1:1;
+    this.uniforms.dustTransform.value.set(sx*next.motion*next.horizontal,sy*next.motion*next.vertical,next.motion);
+    this.uniforms.dustFormation.value=next.formation;this.uniforms.dustChaos.value=next.chaos*2;this.uniforms.dustBounce.value=next.bounceLines?1:0;
+    const angle=next.recipe.angle*Math.PI/180;
+    const snap=v=>Math.abs(v)<1e-12?0:v;
+    this.uniforms.dustRecipeDirection.value.set(snap(Math.cos(angle)),snap(Math.sin(angle)));
+    for(const name of ['Depth','Spin','Sway','Shape','Glow','Rebound','Pace'])this.uniforms['dustRecipe'+name].value=next.recipe[name.toLowerCase()];
+    this.uniforms.dustRecipePalette.value.fromArray({original:[-1,-1,-1],cool:[.3,.7,1],warm:[1,.5,.2],mint:[.3,1,.7]}[next.recipe.palette]);
+    this.characterView=null;
+    for(const material of this.materials)this.syncMaterialDefines(material);
+  }
+  syncMaterialDefines(material){
+    const scale=this.uniforms.dustTransform.value;
+    const flags={THD_EDIT_MODE:textEditMotions[this.mode].id,THD_EDIT_CHARACTER_FRAME:textEditMotions[this.mode].characterFrame||material.userData.triangleMotionFrame?1:0,THD_EDIT_ADJUST:scale.x!==1||scale.y!==1||scale.z!==1?1:0,THD_EDIT_BOUNCE:this.settings.bounceLines?1:0};
+    if(Object.entries(flags).some(([key,value])=>material.defines?.[key]!==value)){material.defines={...material.defines,...flags};material.needsUpdate=true;}
+  }
+  randomSeed(){return this.settings.seed===null?Math.random():this.settings.seed/4294967296;}
+  allocate(count){
+    if(this.capacity>=count)return;
+    this.capacity=2**Math.ceil(Math.log2(Math.max(1,count)));
+    this.uniforms.dustData.value?.dispose();
+    const THREE=this.THREE,texture=new THREE.DataTexture(new Float32Array(this.capacity*8),this.capacity,2,THREE.RGBAFormat,THREE.FloatType);
+    texture.minFilter=texture.magFilter=THREE.NearestFilter;texture.generateMipmaps=false;
+    this.uniforms.dustData.value=texture;this.uniforms.dustWidth.value=this.capacity;
+  }
+  decorate(view){
+    const THREE=this.THREE;
+    this.materials=new Set(Array.from(view.sharedGroups?.values()||[],({mesh})=>mesh.material));
+    for(const {mesh} of view.sharedGroups?.values()||[]){
+      const geometry=mesh.geometry;
+      if(this.settings.bounceLines&&!geometry.getAttribute('dustCornerA')){
+        const a=geometry.getAttribute('position'),corners=[new Float32Array(a.count*3),new Float32Array(a.count*3),new Float32Array(a.count*3)];
+        for(let i=0;i<a.count;i+=3)for(let c=0;c<3;c++)for(let j=0;j<3;j++)corners[c].set(a.array.subarray((i+c)*3,(i+c+1)*3),(i+j)*3);
+        corners.forEach((values,i)=>geometry.setAttribute(['dustCornerA','dustCornerB','dustCornerC'][i],new THREE.BufferAttribute(values,3)));
+      }
+      if(textEditMotions[this.mode].contour)ensureTextMotionContour(THREE,geometry);
+      particleCenters(THREE,geometry,this.settings.particleShape);
+      const material=mesh.material;
+      // A surface supplies one local frame; text continues to supply measured
+      // per-character attributes. Constant attributes avoid repeating image
+      // bounds for every vertex and preserve the same path/bounce evaluator.
+      const frame=view.motionFrame;
+      material.userData.triangleMotionFrame=!!frame;
+      if(frame){
+        material.defaultAttributeValues.dustCharacterFrame=[frame.x,frame.y,frame.width,frame.height];
+        material.defaultAttributeValues.dustFloor=[frame.y,0];
+        material.defaultAttributeValues.dustCeiling=[frame.y+frame.height,0,0,0];
+        const motion=textEditMotions[this.mode];
+        ensureTriangleMotionFrame(THREE,geometry,frame,{side:motion.characterCenters,floor:motion.characterFloor});
+      }
+      this.syncMaterialDefines(material);
+      if(material.userData.dustWind)continue;
+      material.defaultAttributeValues.dustEdge=[1e6,1e6,1e6];
+      material.defaultAttributeValues.dustCharacterSide=[0];
+      if(!frame){
+        material.defaultAttributeValues.dustCharacterFrame=[0,0,0,0];
+        material.defaultAttributeValues.dustFloor=[0,0];
+        material.defaultAttributeValues.dustCeiling=[0,0,0,0];
+      }
+      for(const name of ['dustCornerA','dustCornerB','dustCornerC'])material.defaultAttributeValues[name]=[0,0,0];
+      material.userData.dustSource={vertexShader:material.vertexShader,fragmentShader:material.fragmentShader};
+      material.userData.dustWind=true;Object.assign(material.uniforms,this.uniforms);
+      material.vertexShader=`attribute vec2 dustCenter; attribute vec3 dustEdge; attribute float dustCharacterSide; attribute vec2 dustFloor; uniform float dustEnabled; uniform float dustMotion; uniform float dustMaskOnly; uniform float dustEm; uniform float dustSeconds; uniform int dustCount; uniform float dustWidth; uniform sampler2D dustData; varying float dustOpacity; varying float dustGlow; varying vec3 dustGlowColor; varying vec3 dustContour; varying float dustOutline;\n${textMotionPrimitives}\n`+material.vertexShader;
+      // Function declarations follow the attributes/uniforms they use.
+      const sourceMarker=material.vertexShader.indexOf('void main');
+      material.vertexShader=material.vertexShader.slice(0,sourceMarker)+`attribute vec4 dustCharacterFrame; attribute vec4 dustCeiling; attribute vec3 dustCornerA; attribute vec3 dustCornerB; attribute vec3 dustCornerC; uniform vec3 dustTransform; uniform float dustFormation; uniform float dustChaos; uniform float dustBounce;\n${textRecipeUniformShader}\n${textEffectOptionShader}\n${textEffectPathShader}\n`+material.vertexShader.slice(sourceMarker);
+      const marker=material.vertexShader.includes('/* THD_TRIANGLE_MOTION */')?'/* THD_TRIANGLE_MOTION */':'float sampleIndex =';
+      material.vertexShader=material.vertexShader.replace(marker,`
+        dustOpacity=1.0-dustMaskOnly;
+        dustGlow=0.0;
+        dustGlowColor=vec3(1.0);
+        dustContour=dustEdge;
+        dustOutline=0.0;
+        vec2 dustTarget=dustCenter+glyphOffset;
+        if(dustEnabled>0.5){
+          for(int k=0;k<dustCount;k++){
+            float u=(float(k)+0.5)/dustWidth;
+            vec4 r=texture2D(dustData,vec2(u,0.25));
+            if(dustTarget.x>=r.x&&dustTarget.x<=r.z&&dustTarget.y>=r.y&&dustTarget.y<=r.w){
+              vec4 clock=texture2D(dustData,vec2(u,0.75));
+              vec2 particle=(dustTarget-r.xy)/dustEm;
+              float seed=fract(sin(dot(particle,vec2(127.1,311.7))+clock.w*53.0)*43758.5453);
+              float drift=fract(sin(dot(particle,vec2(269.5,183.3))+clock.w*91.7)*43758.5453);
+              float pace=fract(sin(dot(particle,vec2(419.2,371.9))+clock.w*73.0)*43758.5453);
+              vec2 travel=thdParticleTravel(seed,drift,pace,dustSeconds);
+              travel.y=thdFormationSeconds(travel.y,dustSeconds,dustFormation);
+              float t=thdMotionPhase(clock,travel.y,dustSeconds);
+              #ifdef THD_HYBRID_GLOBAL_ESCAPE
+                hybridEscaping=1.0-step(0.99999,t);
+              #endif
+              #ifdef THD_RASTER_TEXTURE
+                vRasterQuality=smoothstep(0.9,1.0,t);
+              #endif
+              if(dustChaos!=1.0){
+                seed=clamp(mix(0.5,seed,dustChaos),0.0,1.0);
+                drift=clamp(mix(0.5,drift,dustChaos),0.0,1.0);
+                pace=clamp(mix(0.5,pace,dustChaos),0.0,1.0);
+              }
+              float remain=1.0-t;
+              dustOpacity=smoothstep(0.0,0.1,t);
+              ${textEffectApplicationShader}
+              p.z=thdFrontDepth(position.z,p.z);
+              break;
+            }
+          }
+        }
+        ${marker==='float sampleIndex ='?marker:''}`);
+      material.fragmentShader='uniform float dustEm; varying float dustOpacity; varying float dustGlow; varying vec3 dustGlowColor; varying vec3 dustContour; varying float dustOutline;\n'+material.fragmentShader;
+      material.fragmentShader=material.fragmentShader.replace('coverage);',`coverage * dustOpacity);
+        gl_FragColor.rgb=mix(gl_FragColor.rgb,dustGlowColor,clamp(dustGlow,0.0,1.0));
+        if(dustOutline>0.0){
+          float edge=min(dustContour.x,min(dustContour.y,dustContour.z));
+          float border=1.0-smoothstep(dustEm*0.018,dustEm*0.018+max(fwidth(edge),0.00001),edge);
+          gl_FragColor.a*=mix(1.0,border,dustOutline);
+        }`);material.needsUpdate=true;
+    }
+  }
+  playRegion(view,rectangle,unit,now,{departing=false,seed=this.randomSeed(),fromAge=1}={}){
+    const settings=this.settings;
+    this.cancel();this.departing=departing;this.uniforms.dustMaskOnly.value=departing?1:0;
+    this.settings=null;this.configure(settings);
+    this.decorate(view);this.uniforms.dustEm.value=unit;
+    this.jobs=[{id:++this.sequence,seed,started:now,fromAge,rectangles:[rectangle]}];
+    this.runs++;return this.step(now);
+  }
+  step(now,reducedMotion=false){
+    this.lastTime=now;
+    if(reducedMotion){this.cancel();return false;}
+    this.jobs=this.jobs.filter(job=>{
+      if(job.started===null||now-job.started<this.duration)return true;
+      if(!this.departing)this.settledJobs.push(job);
+      return false;
+    });
+    const rectangles=this.jobs.filter(job=>job.started!==null).flatMap(job=>job.rectangles.map(rect=>({rect,age:Math.max(0,(now-job.started)/this.duration),seed:job.seed||0,fromAge:job.fromAge??1})));
+    this.allocate(rectangles.length);
+    const data=this.uniforms.dustData.value.image.data;
+    rectangles.forEach(({rect:r,age,seed,fromAge},i)=>{
+      data.set([r.x,r.y,r.x+r.width,r.y+r.height],i*4);
+      data.set([age,r.direction==='rtl'?-1:1,this.departing?1+fromAge:0,seed],(this.capacity+i)*4);
+    });
+    this.uniforms.dustData.value.needsUpdate=true;this.uniforms.dustCount.value=rectangles.length;
+    this.ghosts=this.ghosts.filter(ghost=>{
+      // First displayed frame is phase zero, even if shaping delayed that frame.
+      for(const job of ghost.effect.jobs)job.started??=now;
+      if(ghost.effect.step(now))return true;ghost.release();return false;
+    });
+    this.active=rectangles.length>0||this.ghosts.length>0;this.uniforms.dustEnabled.value=rectangles.length?1:0;return this.active;
+  }
+  cancel(){for(const ghost of this.ghosts)ghost.release();this.ghosts=[];this.jobs=[];this.settledJobs=[];this.boundView=null;this.boundVersion=null;this.text=null;this.active=false;this.uniforms.dustEnabled.value=0;this.uniforms.dustCount.value=0;}
+  dispose(){this.cancel();this.materials.clear();this.uniforms.dustData.value.dispose();}
+  stats(){return {mode:this.mode,exitMode:this.exitMode,duration:this.duration,settings:cloneTextEffectOptions(this.settings),active:this.active,pending:this.pending,runs:this.runs,exits:this.exits,departures:this.ghosts.length,departureModes:this.ghosts.map(g=>g.effect.mode),rectangles:this.uniforms.dustCount.value,batches:this.jobs.map(({id,range,started})=>({id,range,started}))};}
+}

package/src/triangle-motion-frame.js

@@ -0,0 +1,38 @@
+// Optional facet metadata for one rectangular surface. Text retains its own
+// measured grapheme layout. Prepare once per geometry/frame, never per tick.
+const prepared=new WeakMap();
+export function ensureTriangleMotionFrame(THREE,geometry,frame,{side=false,floor=false}={}){
+  if(!side&&!floor)return;
+  const position=geometry.getAttribute('position'),centers=geometry.getAttribute('dustCenter');
+  const key=[frame.x,frame.y,frame.width,frame.height].join(':');
+  let cache=prepared.get(geometry);
+  if(!cache||cache.centers!==centers||cache.position!==position||cache.version!==position.version||cache.key!==key){
+    cache={centers,position,version:position.version,key,side:false,floor:false};prepared.set(geometry,cache);
+  }
+  const needSide=side&&!cache.side,needFloor=floor&&!cache.floor;
+  if(!needSide&&!needFloor)return;
+  const sides=needSide?new Float32Array(position.count):null;
+  const floors=needFloor?new Float32Array(position.count*2):null;
+  const ceilings=needFloor?new Float32Array(position.count*4):null;
+  for(let i=0;i<position.count;i+=3){
+    const x=centers.getX(i),y=centers.getY(i);
+    if(sides)sides.fill(Math.max(-1,Math.min(1,2*(x-frame.x)/frame.width-1)),i,i+3);
+    if(floors){
+      const low=y-Math.min(position.getY(i),position.getY(i+1),position.getY(i+2));
+      const high=Math.max(position.getY(i),position.getY(i+1),position.getY(i+2))-y;
+      const left=Math.min(position.getX(i),position.getX(i+1),position.getX(i+2))-x;
+      const right=Math.max(position.getX(i),position.getX(i+1),position.getX(i+2))-x;
+      for(let j=0;j<3;j++){
+        floors.set([frame.y,low],(i+j)*2);
+        ceilings.set([frame.y+frame.height,left,right,high],(i+j)*4);
+      }
+    }
+  }
+  const write=(name,values,size)=>{
+    const old=geometry.getAttribute(name);
+    if(old?.array.length===values.length){old.array.set(values);old.needsUpdate=true;}
+    else geometry.setAttribute(name,new THREE.BufferAttribute(values,size));
+  };
+  if(sides){write('dustCharacterSide',sides,1);cache.side=true;}
+  if(floors){write('dustFloor',floors,2);write('dustCeiling',ceilings,4);cache.floor=true;}
+}

package/src/viewport-clip.js

@@ -0,0 +1,119 @@
+// Rounded ancestor clips supplement the owner's rectangular scissor. Coordinates
+// are absolute CSS viewport pixels; radii run clockwise from the top-left corner.
+export const MAX_VIEWPORT_CLIPS=8;
+const clipsOverflow=value=>/^(auto|scroll|hidden|clip)$/.test(value);
+const cornerNames=['borderTopLeftRadius','borderTopRightRadius','borderBottomRightRadius','borderBottomLeftRadius'];
+
+function radiusLength(value,size){
+  const match=/^(\d*\.?\d+)(px|%)?$/.exec(value);
+  if(!match||!match[2]&&Number(match[1])!==0)throw TypeError('Viewport clipping requires resolved px or percentage border radii');
+  return Number(match[1])*(match[2]==='%'?size/100:1);
+}
+
+export function readViewportClip(node,style,box){
+  // A visible axis does not acquire rounded clipping from the other axis.
+  if(!clipsOverflow(style.overflowX)||!clipsOverflow(style.overflowY))return null;
+  const width=node.offsetWidth,height=node.offsetHeight;
+  if(!(width>0&&height>0&&box.width>0&&box.height>0&&node.clientWidth>0&&node.clientHeight>0))return null;
+  const radii=cornerNames.map(name=>{
+    const pair=(style[name]||'0px').trim().split(/\s+/);
+    if(pair.length>2)throw TypeError('Viewport clipping requires resolved px or percentage border radii');
+    return [radiusLength(pair[0],width),radiusLength(pair[1]||pair[0],height)];
+  });
+  // CSS reduces every outer radius by one common factor before computing the
+  // inner border curve. Do not renormalize inner radii: a thick opposite border
+  // can legitimately truncate an arc to less than a quarter ellipse.
+  const factor=Math.min(1,
+    width/(radii[0][0]+radii[1][0]||1),width/(radii[3][0]+radii[2][0]||1),
+    height/(radii[0][1]+radii[3][1]||1),height/(radii[1][1]+radii[2][1]||1));
+  const left=node.clientLeft,top=node.clientTop,right=Math.max(0,width-left-node.clientWidth),bottom=Math.max(0,height-top-node.clientHeight);
+  const sx=box.width/width,sy=box.height/height;
+  const insets=[[left,top],[right,top],[right,bottom],[left,bottom]];
+  for(let i=0;i<4;i++){
+    radii[i][0]=Math.max(0,radii[i][0]*factor-insets[i][0])*sx;
+    radii[i][1]=Math.max(0,radii[i][1]*factor-insets[i][1])*sy;
+  }
+  if(!radii.some(([x,y])=>x>0&&y>0))return null;
+  // Client dimensions include padding; subtracting content padding here would
+  // incorrectly hide overflow that CSS allows to paint inside that padding.
+  return {left:box.left+left*sx,top:box.top+top*sy,right:box.left+(left+node.clientWidth)*sx,bottom:box.top+(top+node.clientHeight)*sy,radii};
+}
+
+const marker='/* THD_VIEWPORT_ROUNDED_CLIP */';
+const clipMaterials=new WeakSet();
+const clipShader=`${marker}
+uniform int thdViewportClipCount;
+uniform vec4 thdViewportClipRects[${MAX_VIEWPORT_CLIPS}];
+uniform vec4 thdViewportClipRadiiX[${MAX_VIEWPORT_CLIPS}];
+uniform vec4 thdViewportClipRadiiY[${MAX_VIEWPORT_CLIPS}];
+uniform vec3 thdViewportClipOrigin;
+float thdViewportCornerAlpha(vec2 delta,vec2 radius){
+  if(radius.x<=0.0||radius.y<=0.0||delta.x<=0.0||delta.y<=0.0)return 1.0;
+  vec2 q=delta/radius;
+  float edge=dot(q,q)-1.0;
+  // First-order ellipse distance supplies one physical pixel of antialiasing,
+  // without requiring derivative extensions or changing the surface's RGB.
+  float distance=edge/max(2.0*length(q/radius),0.000001);
+  return clamp(0.5-distance/thdViewportClipOrigin.z,0.0,1.0);
+}
+float thdViewportClipAlpha(){
+  vec2 p=vec2(thdViewportClipOrigin.x+gl_FragCoord.x*thdViewportClipOrigin.z,
+    thdViewportClipOrigin.y-gl_FragCoord.y*thdViewportClipOrigin.z);
+  float alpha=1.0;
+  for(int i=0;i<${MAX_VIEWPORT_CLIPS};i++){
+    if(i>=thdViewportClipCount)break;
+    vec4 b=thdViewportClipRects[i],rx=thdViewportClipRadiiX[i],ry=thdViewportClipRadiiY[i];
+    alpha=min(alpha,thdViewportCornerAlpha(vec2(b.x+rx.x-p.x,b.y+ry.x-p.y),vec2(rx.x,ry.x)));
+    alpha=min(alpha,thdViewportCornerAlpha(vec2(p.x-b.z+rx.y,b.y+ry.y-p.y),vec2(rx.y,ry.y)));
+    alpha=min(alpha,thdViewportCornerAlpha(vec2(p.x-b.z+rx.z,p.y-b.w+ry.z),vec2(rx.z,ry.z)));
+    alpha=min(alpha,thdViewportCornerAlpha(vec2(b.x+rx.w-p.x,p.y-b.w+ry.w),vec2(rx.w,ry.w)));
+  }
+  return alpha;
+}
+`;
+
+function decorateMaterial(material){
+  if(material.fragmentShader.includes(marker))return;
+  const source=material.fragmentShader;
+  // Preserve functions following main as well as existing opacity/effect hooks.
+  const clean=source.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g,match=>' '.repeat(match.length));
+  const main=/\bvoid\s+main\s*\(\s*(?:void\s*)?\)\s*\{/.exec(clean);
+  if(!main)throw TypeError('Viewport clipping requires a ShaderMaterial main function');
+  let end=main.index+main[0].length,depth=1;
+  for(;end<clean.length&&depth;end++){if(clean[end]==='{')depth++;else if(clean[end]==='}')depth--;}
+  if(depth)throw TypeError('Viewport clipping requires a complete ShaderMaterial main function');
+  const finish='\nfloat thdClipCoverage=thdViewportClipAlpha();\nif(thdClipCoverage<=0.0)discard;\ngl_FragColor.a *= thdClipCoverage;\n';
+  material.fragmentShader=clipShader+source.slice(0,end-1)+finish+source.slice(end-1);
+  material.needsUpdate=true;
+}
+
+export function applyViewportClips(scene,clips,viewport,dpr){
+  if(clips.length>MAX_VIEWPORT_CLIPS)throw RangeError(`At most ${MAX_VIEWPORT_CLIPS} rounded viewport clips are supported`);
+  if(!(Number.isFinite(dpr)&&dpr>0))throw RangeError('A positive viewport pixel ratio is required');
+  scene.traverse(object=>{
+    for(const material of Array.isArray(object.material)?object.material:[object.material]){
+      if(!material?.isShaderMaterial)continue;
+      if(!clips.length&&!material.fragmentShader.includes(marker))continue;
+      decorateMaterial(material);
+      const uniforms=material.uniforms;
+      // Three's uniform clone can retain typed-array references. Give each new
+      // material its own clip buffers so cloned scenes cannot move a peer's clip.
+      if(!clipMaterials.has(material)){
+        uniforms.thdViewportClipCount={value:0};
+        uniforms.thdViewportClipOrigin={value:new Float32Array(3)};
+        for(const name of ['thdViewportClipRects','thdViewportClipRadiiX','thdViewportClipRadiiY'])uniforms[name]={value:new Float32Array(MAX_VIEWPORT_CLIPS*4)};
+        clipMaterials.add(material);
+      }
+      uniforms.thdViewportClipCount.value=clips.length;
+      uniforms.thdViewportClipOrigin.value.set([viewport.left,viewport.bottom,1/dpr]);
+      for(let i=0;i<clips.length;i++){
+        const clip=clips[i],offset=i*4;
+        uniforms.thdViewportClipRects.value.set([clip.left,clip.top,clip.right,clip.bottom],offset);
+        for(let corner=0;corner<4;corner++){
+          uniforms.thdViewportClipRadiiX.value[offset+corner]=clip.radii[corner][0];
+          uniforms.thdViewportClipRadiiY.value[offset+corner]=clip.radii[corner][1];
+        }
+      }
+    }
+  });
+}