@ev-ry/fx 0.1.0-rc.1

package/src/font-rasterizer.js

@@ -0,0 +1,65 @@
+// Reuse a single canvas. A common vertical origin keeps all joining forms aligned.
+export class FontRasterizer {
+  constructor(family, weight = 200) {
+    this.canvas = document.createElement('canvas');
+    this.context = this.canvas.getContext('2d', { willReadFrequently: true });
+    this.font = `${weight} 200px "${family}"`;
+    this.configure();
+    const metric = this.context.measureText('آبپچگژهمیABCgj');
+    this.ascent = Math.ceil(Math.max(metric.fontBoundingBoxAscent || 0, metric.actualBoundingBoxAscent || 0));
+    this.descent = Math.ceil(Math.max(metric.fontBoundingBoxDescent || 0, metric.actualBoundingBoxDescent || 0));
+    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 = 'optimizeLegibility';
+    if ('fontKerning' in this.context) this.context.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.
+    this.context.direction = direction; this.context.fillStyle = '#fff';
+  }
+
+  raster(text, direction = 'ltr') {
+    const key = direction + ':' + text;
+    if (this.cache.has(key)) return this.cache.get(key);
+    this.configure(direction);
+    const metric = this.context.measureText(text);
+    const padding = 2;
+    const drawOffsetX = Math.ceil(Math.max(0, metric.actualBoundingBoxLeft || 0)) + 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) + 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.fillText(text, drawOffsetX, baseline);
+    const rgba = this.context.getImageData(0, 0, width, height).data;
+    const result = { width, height, baseline, drawOffsetX, advance: metric.width, rgba };
+    this.cache.set(key, result);
+    return result;
+  }
+}
+
+export async function collectDroppedFiles(dataTransfer) {
+  const entries = Array.from(dataTransfer.items || [], item => item.webkitGetAsEntry?.()).filter(Boolean);
+  const fallback = Array.from(dataTransfer.files || []);
+  async function walk(entry) {
+    if (entry.isFile) return [await new Promise((resolve, reject) => entry.file(resolve, reject))];
+    if (!entry.isDirectory) return [];
+    const reader = entry.createReader(), result = [];
+    for (;;) {
+      const batch = await new Promise((resolve, reject) => reader.readEntries(resolve, reject));
+      if (!batch.length) break;
+      for (const child of batch) result.push(...await walk(child));
+    }
+    return result;
+  }
+  if (!entries.length) return fallback;
+  const result = [];
+  for (const entry of entries) result.push(...await walk(entry));
+  return result;
+}

package/src/hybrid-text-flow.js

@@ -0,0 +1,45 @@
+import {RuntimeFontEngine} from './runtime-font-engine.js';
+import {documentDirection} from './text-direction.js';
+
+// Read the real semantic text node. No mirror editor, layout guesses, or HTML parsing.
+export function measureHybridTextFlow(element,labelNode,engine){
+  const document=element.ownerDocument,style=document.defaultView.getComputedStyle(element),px=value=>parseFloat(value)||0;
+  const fontSize=px(style.fontSize),factor=fontSize/200,context=engine.rasterizer.context,box=element.getBoundingClientRect();
+  context.font=`${engine.weight} ${fontSize}px "${engine.face.family}"`;const metric=context.measureText('Hgآی');engine.rasterizer.configure();
+  const ascent=metric.fontBoundingBoxAscent,descent=metric.fontBoundingBoxDescent;
+  const supported=factor>0&&Number.isFinite(ascent)&&style.fontFamily.includes(engine.face.family)&&Number(style.fontWeight)===engine.weight&&style.fontStyle==='normal'&&style.textTransform==='none'
+    &&['normal','0px'].includes(style.letterSpacing)&&['normal','0px'].includes(style.wordSpacing)&&!labelNode.textContent.includes('\t')&&style.textAlign!=='justify';
+  if(!supported)return {supported:false};
+  const node=labelNode.firstChild,range=document.createRange(),rows=[],text=labelNode.textContent;
+  const segments=new Intl.Segmenter(undefined,{granularity:'grapheme'});let offset=0;
+  for(const paragraph of text.split('\n')){
+    const direction=element.dir==='auto'?documentDirection(paragraph,style.direction):style.direction;let row=null;
+    for(const part of segments.segment(paragraph)){
+      const start=offset+part.index,end=start+part.segment.length;range.setStart(node,start);range.setEnd(node,end);const rects=[...range.getClientRects()];const rect=rects.find(r=>r.height>0);if(!rect)continue;
+      const top=rect.top-box.top-element.clientTop;
+      if(!row||Math.abs(row.top-top)>.75){if(row)rows.push(row);row={start,end,top,left:Infinity,right:-Infinity,direction,baseline:top+(rect.height+ascent-descent)/2};}else row.end=end;
+      for(const r of rects){row.left=Math.min(row.left,r.left-box.left-element.clientLeft);row.right=Math.max(row.right,r.right-box.left-element.clientLeft);}
+    }
+    if(row)rows.push(row);offset+=paragraph.length+1;
+  }
+  for(const row of rows)row.text=text.slice(row.start,row.end);
+  const key=JSON.stringify([text,element.clientWidth,element.clientHeight,fontSize,rows.map(r=>[r.start,r.end,Math.round(r.left*64)/64,Math.round(r.baseline*64)/64,r.direction])]);
+  return {supported:true,rows,factor,key};
+}
+
+// Reuse rasterization, mesh generation, LRU accounting and shared glyph scene.
+// Only line placement is supplied by the DOM's actual wrapping and bidi layout.
+export class HybridTextFlowEngine extends RuntimeFontEngine{
+  async prepareRows(layout,{cancelled=()=>false}={}){
+    const nextCache=new Map(),entries=[];let slice=performance.now();
+    try{for(const row of layout.rows){
+      if(cancelled())return null;const item={ch:row.text,i:0,form:0,key:`flow:${row.direction}:${row.text}`,rasterText:row.text,direction:row.direction};this.ensureGlyph(item);
+      const glyph=this.records.get(item.key+':0'),metrics={text:row.text,items:[{...item,glyph,x:row.left/layout.factor}],utf16Offsets:[0],height:this.fontMetrics.height};
+      nextCache.set(item.key,metrics);entries.push({metrics,offset:row.start,length:row.text.length,baseline:this.fontMetrics.ascent-row.baseline/layout.factor});
+      if(performance.now()-slice>4){await new Promise(r=>setTimeout(r,0));slice=performance.now();}
+    }
+    if(cancelled())return null;this.lineCache=nextCache;this.flowLayout={entries};return this.flowLayout;
+    }finally{this.trimCache();}
+  }
+  layout(){return this.flowLayout||{entries:[]};}
+}

package/src/image-preparation-queue.js

@@ -0,0 +1,16 @@
+// One expensive DOM-image snapshot/mesh job per frame and document. Decoding
+// happens before this queue, so a slow network image cannot block ready peers.
+const queues=new WeakMap();
+export function queueImagePreparation(window,run){
+  let queue=queues.get(window);
+  if(!queue){queue={jobs:[],frame:null,running:false};queues.set(window,queue);}
+  let resolve,reject;const promise=new Promise((a,b)=>{resolve=a;reject=b;});
+  const job={run,resolve,reject,cancelled:false};queue.jobs.push(job);
+  function request(){if(!queue.running&&queue.frame===null&&queue.jobs.length)queue.frame=window.requestAnimationFrame(pump);}
+  async function pump(){queue.frame=null;const next=queue.jobs.shift();if(!next)return;queue.running=true;
+    try{next.resolve(next.cancelled?false:await next.run());}catch(error){next.reject(error);}
+    finally{queue.running=false;request();}
+  }
+  request();
+  return {promise,cancel(){if(job.cancelled)return;job.cancelled=true;const index=queue.jobs.indexOf(job);if(index>=0){queue.jobs.splice(index,1);resolve(false);if(!queue.jobs.length&&queue.frame!==null){window.cancelAnimationFrame(queue.frame);queue.frame=null;}}}};
+}

package/src/image-source.js

@@ -0,0 +1,61 @@
+const TYPES=new Set(['image/png','image/jpeg','image/webp','image/svg+xml']);
+// Internal, branded snapshots avoid encoding already decoded DOM pixels. An
+// arbitrary object passed to the public loader cannot bypass source validation.
+const snapshots=new WeakMap();
+export function imageRasterSource(raster){const source=Object.freeze({});snapshots.set(source,raster);return source;}
+
+function validateSVG(text,document){
+  const xml=new document.defaultView.DOMParser().parseFromString(text,'image/svg+xml');
+  if(xml.querySelector('parsererror')||xml.documentElement.localName!=='svg')throw Error('Invalid SVG');
+  // This first image adapter accepts static, self-contained SVG only.
+  for(const element of xml.querySelectorAll('*')){
+    if(['script','foreignObject','animate','animateMotion','animateTransform','set'].includes(element.localName))throw Error('SVG must be static and self-contained');
+    for(const attribute of element.attributes){
+      const value=attribute.value.trim();
+      if(attribute.localName==='href'&&value&&!value.startsWith('#')&&!/^data:image\/(png|jpeg|webp);base64,/i.test(value))throw Error('SVG external resources are not supported');
+      if(/^on/i.test(attribute.localName))throw Error('SVG event handlers are not supported');
+    }
+  }
+  if(/@import|url\(\s*['"]?\s*(?!#)[^\s'"\)]/i.test(text))throw Error('SVG external styles and resources are not supported');
+}
+
+// Decode once into sRGB RGBA. Browser-supported static files only; no font engine.
+export async function loadImageRaster(source,{document=globalThis.document,signal,maxSide=2048,maxPixels=2097152}={}){
+  const start=performance.now();signal?.throwIfAborted();
+  const snapshot=source&&typeof source==='object'?snapshots.get(source):null;
+  if(snapshot)return snapshot;
+  let blob;
+  if(source instanceof Blob)blob=source;
+  else{
+    const url=new URL(source,document.baseURI);
+    if(!['http:','https:','blob:','data:'].includes(url.protocol))throw Error('Unsupported image URL');
+    const response=await fetch(url,{signal});if(!response.ok)throw Error('Image request failed: '+response.status);
+    blob=await response.blob();
+  }
+  const type=blob.type.split(';')[0].toLowerCase();
+  if(!TYPES.has(type))throw Error('Choose a PNG, JPEG, WebP or static SVG image');
+  if(blob.size>20*1024*1024)throw Error('Image file must be smaller than 20 MB');
+  if(type==='image/svg+xml')validateSVG(await blob.text(),document);
+  signal?.throwIfAborted();
+  const window=document.defaultView,image=new window.Image(),url=URL.createObjectURL(blob);
+  try{
+    await new Promise((resolve,reject)=>{
+      const cleanup=()=>{image.onload=image.onerror=null;signal?.removeEventListener('abort',abort);};
+      const abort=()=>{cleanup();image.src='';reject(signal.reason||new DOMException('Aborted','AbortError'));};
+      image.onload=()=>{cleanup();resolve();};image.onerror=()=>{cleanup();reject(Error('The image could not be decoded'));};
+      signal?.addEventListener('abort',abort,{once:true});image.src=url;
+    });
+    signal?.throwIfAborted();
+    const originalWidth=image.naturalWidth,originalHeight=image.naturalHeight;
+    if(!originalWidth||!originalHeight||originalWidth*originalHeight>67108864)throw Error('Invalid or oversized image dimensions');
+    const scale=Math.min(1,maxSide/Math.max(originalWidth,originalHeight),Math.sqrt(maxPixels/(originalWidth*originalHeight)));
+    const width=Math.max(1,Math.floor(originalWidth*scale)),height=Math.max(1,Math.floor(originalHeight*scale));
+    const canvas=document.createElement('canvas');canvas.width=width;canvas.height=height;
+    try{
+      const context=canvas.getContext('2d',{willReadFrequently:true,colorSpace:'srgb'});
+      context.drawImage(image,0,0,width,height);
+      const rgba=context.getImageData(0,0,width,height).data;
+      return {width,height,rgba,mask:false,type,originalWidth,originalHeight,decodeMs:performance.now()-start};
+    }finally{canvas.width=canvas.height=0;}
+  }finally{URL.revokeObjectURL(url);image.src='';}
+}

package/src/image-surface.js

@@ -0,0 +1,162 @@
+import {imageMotionPixels} from './motion-envelope.js';
+import {loadImageRaster} from './image-source.js';
+import {rasterToTextureMesh} from './raster-texture-mesh.js';
+import {attachRasterTexture,applyRasterSamplingShader} from './raster-texture-material.js';
+import {textDivisionsForSize,createProjectedTextSize} from './text-mesh-density.js';
+import {TriangleEffect} from './triangle-effect.js';
+import {normalizeTextEffectOptions} from './text-effect-options.js';
+import {textEditMotions} from './text-edit-motions.js';
+
+export const IMAGE_EFFECT_MODES=Object.freeze(Object.keys(textEditMotions));
+// Images and text use the same effect recipe defaults.
+export function normalizeImageEffectOptions(settings={},mode='dust-wind'){
+  return normalizeTextEffectOptions({formation:-1,...settings},mode);
+}
+
+// Images use twice the text-derived rows: half-size cells, with a bounded grid.
+export function imageDivisions(width,height,displayHeight,current=null,maxTriangles=80000){
+  let rows=2*textDivisionsForSize(displayHeight,current===null?null:current/2);
+  while(rows>1&&2*rows*Math.max(1,Math.round(width*rows/height))>maxTriangles)rows--;
+  if(2*rows*Math.max(1,Math.round(width*rows/height))>maxTriangles)throw Error('Image aspect ratio exceeds the triangle budget');
+  return rows;
+}
+
+const vertexShader=`
+attribute vec2 rasterUV;
+attribute vec2 glyphOffset;
+varying vec2 vRasterUV;
+void main(){
+  vRasterUV=rasterUV;
+  vec3 p=position+vec3(glyphOffset,0.0);
+  /* THD_TRIANGLE_MOTION */
+  gl_Position=projectionMatrix*modelViewMatrix*vec4(p,1.0);
+}`;
+const fragmentShader=`
+uniform sampler2D rasterMap;
+varying vec2 vRasterUV;
+void main(){
+  vec4 rasterSample=texture2D(rasterMap,vRasterUV);
+  float coverage=rasterSample.a;
+  gl_FragColor=vec4(rasterSample.rgb, coverage);
+  #include <colorspace_fragment>
+}`;
+
+// One image object in an existing runtime. No renderer, input or font ownership.
+export function createImageSurface(runtime,{source,width=6,height=3.8,effect='dust-wind',settings={},direction='ltr'}={}){
+  if(runtime.disposed)throw Error('Spatial runtime disposed');
+  if(!Number.isFinite(width)||!Number.isFinite(height)||width<=0||height<=0)throw RangeError('Positive image bounds required');
+  const validMode=mode=>{if(!IMAGE_EFFECT_MODES.includes(mode))throw TypeError('Unsupported image effect');};
+  const validDirection=value=>{if(!['ltr','rtl'].includes(value))throw TypeError('Invalid direction');};
+  validMode(effect);validDirection(direction);
+  const {THREE}=runtime,document=runtime.renderer.domElement.ownerDocument,object=new THREE.Group();
+  const motion=new TriangleEffect(THREE,{mode:effect,settings:normalizeImageEffectOptions(settings,effect)}),measure=createProjectedTextSize(THREE);
+  let requestedSettings=settings,entryMode=effect,entrySettings=motion.settings;
+  let disposed=false,asset=null,controller=null,revision=0,loading=false,error=null,state='empty',intent=null;
+  let displaySize=null;
+  let lastSeed=null,builds=0,loadMs=0,buildMs=0;
+  const view={sharedGroups:new Map(),version:0};
+  function releaseAsset(){
+    motion.cancel();motion.uniforms.dustMaskOnly.value=0;motion.materials.clear();view.sharedGroups.clear();
+    if(asset){object.remove(asset.mesh);asset.mesh.geometry.dispose();asset.mesh.material.dispose();asset.releaseTexture();asset=null;}
+  }
+  function geometry(raster,rows,w,h,filterRadius,aspect){
+    const mesh=rasterToTextureMesh(raster.rgba,raster.width,raster.height,rows,{filterRadius,aspect}),positions=new Float32Array(mesh.triangleCount*9);
+    for(let i=0;i<mesh.coordinates.length;i+=2){const at=i/2*3;positions[at]=(mesh.coordinates[i]/raster.width-.5)*w;positions[at+1]=(.5-mesh.coordinates[i+1]/raster.height)*h;}
+    const result=new THREE.BufferGeometry();result.setAttribute('position',new THREE.BufferAttribute(positions,3));
+    result.setAttribute('rasterUV',new THREE.BufferAttribute(mesh.uvs,2));result.computeBoundingBox();
+    return result;
+  }
+  function meshSettings(raster,h,current=null){
+    const displayHeight=displaySize?.height??measure(object,runtime.camera,runtime.renderer.domElement,h);
+    const aspect=displaySize?displaySize.width/displaySize.height:raster.width/raster.height;
+    // Mipmap/bilinear filtering sees beyond the original opaque texel. Retain
+    // that support too, especially when a wide image is displayed very small.
+    const ratio=raster.height/Math.max(1,displayHeight*(runtime.renderer.getPixelRatio?.()||1));
+    const filterRadius=displayHeight>0?Math.max(.5,2**Math.ceil(Math.log2(Math.max(1,ratio)))):.5;
+    return {rows:imageDivisions(aspect,1,displayHeight,current),filterRadius,aspect};
+  }
+  function resizeMesh(){
+    if(!asset||motion.active)return;
+    const next=meshSettings(asset.raster,asset.h,asset.rows);if(next.rows===asset.rows&&next.filterRadius===asset.filterRadius&&next.aspect===asset.aspect)return;
+    const start=performance.now(),replacement=geometry(asset.raster,next.rows,asset.w,asset.h,next.filterRadius,next.aspect);
+    asset.mesh.geometry.dispose();asset.mesh.geometry=replacement;asset.rows=next.rows;asset.aspect=next.aspect;asset.filterRadius=next.filterRadius;view.version++;builds++;buildMs=performance.now()-start;
+    motion.decorate(view);
+  }
+  async function setSource(value,{preserveMotion=false,bounds=null}={}){
+    if(disposed)throw Error('Image surface disposed');
+    const token=++revision;controller?.abort();controller=new AbortController();loading=true;error=null;
+    try{
+      const raster=await loadImageRaster(value,{document,signal:controller.signal,maxSide:Math.min(2048,runtime.renderer.capabilities?.maxTextureSize||2048)});
+      if(disposed||token!==revision)return false;
+      if(bounds){width=bounds.width;height=bounds.height;}
+      const start=performance.now(),factor=Math.min(width/raster.width,height/raster.height),w=raster.width*factor,h=raster.height*factor;
+      const {rows,filterRadius,aspect}=meshSettings(raster,h),g=geometry(raster,rows,w,h,filterRadius,aspect);
+      const material=new THREE.ShaderMaterial({vertexShader,fragmentShader,side:THREE.DoubleSide,transparent:true,depthWrite:false,toneMapped:false,extensions:{derivatives:true}});
+      applyRasterSamplingShader(material);
+      material.defaultAttributeValues.glyphOffset=[0,0];
+      const releaseTexture=attachRasterTexture(THREE,material,raster),mesh=new THREE.Mesh(g,material);mesh.frustumCulled=false;
+      // Replacement of DOM pixels/size must not restart an existing effect or
+      // reveal an image that has already completed its exit.
+      const previousState=state,job=motion.jobs[0],seed=lastSeed;
+      const previousIntent=preserveMotion?(intent??(motion.active&&job?{departing:motion.departing,fromAge:job.fromAge,started:job.started,seed}:null)):null;
+      releaseAsset();asset={raster,w,h,rows,filterRadius,aspect,mesh,releaseTexture};object.add(mesh);view.sharedGroups.set('image',{mesh});view.version++;
+      view.motionFrame={x:-w/2,y:-h/2,width:w,height:h};
+      state=preserveMotion?previousState:'visible';intent=previousIntent;lastSeed=preserveMotion?seed:null;mesh.visible=state!=='hidden';builds++;loadMs=raster.decodeMs;buildMs=performance.now()-start;runtime.requestRender();return true;
+    }catch(e){if(disposed||token!==revision||e.name==='AbortError')return false;error=e.message;throw e;}
+    finally{if(token===revision){loading=false;runtime.requestRender();}}
+  }
+  function play(departing){
+    if(disposed||!asset)return false;
+    if(departing&&(state==='hidden'||state==='leaving'||intent?.departing))return false;
+    const fromAge=state==='entering'&&motion.jobs[0]?Math.max(0,Math.min(1,((motion.lastTime??motion.jobs[0].started)-motion.jobs[0].started)/motion.duration)):1;
+    intent={departing,fromAge};runtime.requestRender();return true;
+  }
+  const control={object,
+    frame(now,reducedMotion){
+      if(disposed||!asset)return;
+      resizeMesh();
+      if(intent){
+        const {departing,fromAge,started,seed}=intent;intent=null;asset.mesh.visible=true;state=departing?'leaving':'entering';
+        const exitMode=entrySettings.exitEffect==='same'?entryMode:entrySettings.exitEffect;
+        const activeMode=departing?exitMode:entryMode;
+        motion.setMode(activeMode);motion.configure(normalizeImageEffectOptions(requestedSettings,activeMode));
+        if(seed!==undefined)lastSeed=seed;else if(!departing||lastSeed===null)lastSeed=motion.randomSeed();
+        // DOM image coordinates are source pixels, unlike the spatial runtime's
+        // world units. Keep travel at a stable 32 CSS px for DOM presentations.
+        const shownHeight=displaySize?.height??measure(object,runtime.camera,runtime.renderer.domElement,asset.h);
+        const shownWidth=displaySize?.width??shownHeight*asset.w/asset.h;
+        const motionUnit=shownHeight>0?imageMotionPixels(shownWidth,shownHeight)*asset.h/shownHeight:.65;
+        motion.playRegion(view,{x:-asset.w/2,y:-asset.h/2,width:asset.w,height:asset.h,direction},motionUnit,started??now,{departing,seed:lastSeed,fromAge:departing&&exitMode!==entryMode?1:fromAge});
+      }
+      if(motion.active){
+        motion.step(now,reducedMotion);
+        // This surface reuses one material for both directions. Refresh its
+        // dynamic clock/mask uniforms on the first draw after a transition too.
+        asset.mesh.material.uniformsNeedUpdate=true;
+        // Upload this frame's region data before reusing the same sampler.
+        runtime.renderer.initTexture?.(motion.uniforms.dustData.value);
+        if(motion.active)runtime.requestRender();
+        else{state=motion.departing?'hidden':'visible';asset.mesh.visible=!motion.departing;}
+      }
+      resizeMesh();
+    },
+    invalidate(){runtime.requestRender();},
+    destroy(){if(disposed)return;disposed=true;revision++;controller?.abort();unregister();releaseAsset();motion.dispose();state='disposed';},
+  };
+  const unregister=runtime.register(control);
+  return {object,ready:source===undefined?Promise.resolve(false):setSource(source),setSource,
+    enter:()=>play(false),exit:()=>play(true),
+    setEffect(mode,options={}){validMode(mode);const next=normalizeImageEffectOptions(options,mode);if(disposed)return;requestedSettings=options;entryMode=mode;entrySettings=next;motion.setMode(mode);motion.configure(next);motion.cancel();motion.uniforms.dustMaskOnly.value=0;intent=null;if(asset){asset.mesh.visible=true;state='visible';}runtime.requestRender();},
+    setDisplaySize(width,height){if(!(Number.isFinite(width)&&Number.isFinite(height)&&width>0&&height>0))throw RangeError('Positive display dimensions required');displaySize={width,height};},
+    setDirection(value){validDirection(value);direction=value;},
+    show(){if(disposed||!asset)return;intent=null;motion.cancel();motion.uniforms.dustMaskOnly.value=0;asset.mesh.visible=true;state='visible';runtime.requestRender();},
+    frame:control.frame,destroy:control.destroy,
+    stats(){const raster=asset?.raster,g=asset?.mesh.geometry;return {disposed,loading,error,state,active:motion.active,mode:entryMode,activeMode:motion.mode,exitMode:entrySettings.exitEffect==='same'?entryMode:entrySettings.exitEffect,duration:motion.duration,settings:{...motion.settings,recipe:{...motion.settings.recipe}},direction,motionFrame:asset?{...view.motionFrame}:null,divisions:asset?.rows,gridAspect:asset?.aspect,gridColumns:asset?Math.max(1,Math.round(asset.rows*asset.aspect)):0,triangles:g?g.getAttribute('position').count/3:0,builds,loadMs,buildMs,rasterBytes:raster?.rgba.byteLength||0,estimatedTextureBytes:raster?Math.ceil(raster.rgba.byteLength*4/3):0,geometryBytes:g?Object.values(g.attributes).reduce((n,a)=>n+a.array.byteLength,0):0,source:raster?{type:raster.type,width:raster.width,height:raster.height,originalWidth:raster.originalWidth,originalHeight:raster.originalHeight}:null};},
+  };
+}
+
+
+
+
+
+

package/src/insertion-range.js

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

package/src/mesh-generator-core.js

@@ -0,0 +1,149 @@
+import { JOINING_FORMS } from './font-mesh-engine.js';
+import { integrateTenSamples } from './triangle-coverage.js';
+
+export const DIVISIONS = [24, 36, 48, 60, 72];
+export const PERSIAN_ALPHABET = 'آابپتثجچحخدذرزژسشصضطظعغفقکگلمنوهی';
+export const EXTRA_CHARACTERS = ['أ', 'إ', 'ؤ', 'ئ', 'هٔ', 'اً'];
+export const SAMPLE_TEXT = 'آ ا ب پ ت ث ج چ ح خ د ذ ر ز ژ\nس ش ص ض ط ظ ع غ ف ق ک گ ل م ن و ه ی\nپدر، پنجره، سپید، توپ؛ چشمه، پژوهش و زندگی\nخانۀ ما، خانهٔ ما؛ لطفاً، واقعاً، سؤال، مسئول\n۰۱۲۳۴۵۶۷۸۹  ٠١٢٣٤٥٦٧٨٩  0123456789\nABCDEFGHIJKLMNOPQRSTUVWXYZ\nabcdefghijklmnopqrstuvwxyz';
+
+export function repertoire(extras = true) {
+  const chars = [...new Set(Array.from(PERSIAN_ALPHABET + 'ء' + '۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩' +
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789' +
+    ' `~!@#$%^&*()-_=+[]{}\\|;:\'",.<>/?،؛؟«»٪٫٬'))];
+  if (extras) chars.push(...EXTRA_CHARACTERS);
+  return chars.flatMap(character => {
+    const base = Array.from(character)[0];
+    const marks = Array.from(character).slice(1).join('');
+    const variants = JOINING_FORMS[base] || [base];
+    return variants.map((form, formIndex) => ({ character, formIndex,
+      rasterText: (formIndex === 0 ? base : form) + marks }));
+  });
+}
+
+// Exact antialiased coverage by default; runtime text can opt into the tested
+// ten-point approximation. Both paths share the same grid and output format.
+export function rasterToTriangles(rgba, width, height, divisions, packed = false, coverageSamples = 0) {
+  if (!DIVISIONS.includes(divisions)) throw new Error('تقسیمات نامعتبر است.');
+  if (coverageSamples !== 0 && coverageSamples !== 10) throw new RangeError('Coverage samples must be 0 (all pixels) or 10');
+  const rows = divisions, columns = Math.max(1, Math.round(width / (height / rows)));
+  const cellWidth = width / columns, cellHeight = height / rows;
+  const sums = new Float64Array(rows * columns * 2);
+  const counts = new Uint32Array(sums.length);
+  // Keep exact integration for export and for cells already smaller than the
+  // sample budget. Runtime callers opt into ten-point coverage explicitly.
+  if (coverageSamples === 10 && cellWidth * cellHeight > 20) integrateTenSamples(rgba,width,height,rows,columns,cellWidth,cellHeight,sums,counts);
+  else if (width > 1024) integrateWideRaster(rgba,width,height,rows,columns,cellWidth,cellHeight,sums,counts);
+  else for (let y = 0; y < height; y++) {
+    const gy = (y + 0.5) / cellHeight, row = Math.min(rows - 1, Math.floor(gy)), fy = gy - row;
+    for (let x = 0; x < width; x++) {
+      const gx = (x + 0.5) / cellWidth, column = Math.min(columns - 1, Math.floor(gx)), fx = gx - column;
+      const side = (row + column) % 2 === 0 ? (fx + fy <= 1 ? 0 : 1) : (fy <= fx ? 0 : 1);
+      const slot = (row * columns + column) * 2 + side;
+      sums[slot] += rgba[(y * width + x) * 4 + 3] / 255;
+      counts[slot]++;
+    }
+  }
+  let triangleCount = 0;
+  if (packed) for (let at = 0; at < sums.length; at++) if (sums[at] >= 0.08) triangleCount++;
+  // Float64 preserves font-space arithmetic until the final GPU Float32 write.
+  const coordinates = packed ? new Float64Array(triangleCount * 6) : null;
+  const coverage = packed ? new Uint8Array(triangleCount) : null;
+  const triangles = packed ? null : [];
+  let triangleIndex = 0;
+  for (let row = 0; row < rows; row++) for (let column = 0; column < columns; column++) {
+    const left = column * cellWidth, right = (column + 1) * cellWidth;
+    const top = row * cellHeight, bottom = (row + 1) * cellHeight;
+    const even = (row + column) % 2 === 0;
+    const pair = packed ? null : even
+      ? [[[right, top], [left, bottom], [left, top]], [[right, top], [right, bottom], [left, bottom]]]
+      : [[[left, top], [right, bottom], [right, top]], [[left, top], [left, bottom], [right, bottom]]];
+    for (let side = 0; side < 2; side++) {
+      const at = (row * columns + column) * 2 + side;
+      if (sums[at] < 0.08) continue;
+      const level = Math.max(1, Math.min(6, Math.round(sums[at] / counts[at] * 6)));
+      if (packed) {
+        const at = triangleIndex * 6;
+        coordinates[at] = even ? right : left;
+        coordinates[at + 1] = top;
+        coordinates[at + 2] = even ? (side ? right : left) : (side ? left : right);
+        coordinates[at + 3] = bottom;
+        coordinates[at + 4] = even ? left : right;
+        coordinates[at + 5] = side ? bottom : top;
+        coverage[triangleIndex++] = level;
+      } else triangles.push({ points: pair[side], average: level / 6 });
+    }
+  }
+  return packed ? { coordinates, coverage, triangleCount } : triangles;
+}
+
+// Long paragraphs have many pixels per grid cell. Resolve each axis once and
+// accumulate locally instead of dividing and writing two arrays per pixel.
+// Within each triangle pixels retain the reference's y/x order and /255 sum;
+// grid boundaries, threshold decisions and quantized coverage remain identical.
+function integrateWideRaster(rgba,width,height,rows,columns,cellWidth,cellHeight,sums,counts){
+  function axis(size,step,bins){
+    const starts=new Uint32Array(bins+1),fractions=new Float64Array(size);let previous=0;
+    for(let pixel=0;pixel<size;pixel++){
+      const grid=(pixel+.5)/step,bin=Math.min(bins-1,Math.floor(grid));fractions[pixel]=grid-bin;
+      while(previous<bin)starts[++previous]=pixel;
+    }
+    starts.fill(size,previous+1);return {starts,fractions};
+  }
+  const x=axis(width,cellWidth,columns),y=axis(height,cellHeight,rows);
+  for(let row=0;row<rows;row++){
+    const top=y.starts[row],bottom=y.starts[row+1];if(top===bottom)continue;
+    for(let column=0;column<columns;column++){
+      const left=x.starts[column],right=x.starts[column+1];if(left===right)continue;
+      const even=(row+column)%2===0;let sum0=0,sum1=0,count0=0,count1=0;
+      for(let py=top;py<bottom;py++){
+        const fy=y.fractions[py];let alpha=(py*width+left)*4+3;
+        for(let px=left;px<right;px++,alpha+=4){
+          if(even?x.fractions[px]+fy<=1:fy<=x.fractions[px]){sum0+=rgba[alpha]/255;count0++;}
+          else {sum1+=rgba[alpha]/255;count1++;}
+        }
+      }
+      const slot=(row*columns+column)*2;
+      sums[slot]=sum0;sums[slot+1]=sum1;counts[slot]=count0;counts[slot+1]=count1;
+    }
+  }
+}
+
+export function encodeTMG(records) {
+  const size = 12 + records.reduce((sum, r) => sum + 20 + Array.from(r.character).length * 4 + r.triangles.length * 13, 0);
+  const bytes = new Uint8Array(size), view = new DataView(bytes.buffer);
+  bytes.set([84, 77, 71, 53, 1, 0, 0, 0]);
+  view.setUint32(8, records.length, true);
+  let offset = 12;
+  for (const r of records) {
+    const codePoints = Array.from(r.character, ch => ch.codePointAt(0));
+    view.setUint8(offset++, codePoints.length);
+    for (const cp of codePoints) { view.setUint32(offset, cp, true); offset += 4; }
+    view.setUint8(offset++, r.formIndex);
+    for (const value of [r.width, r.height]) { view.setUint16(offset, value, true); offset += 2; }
+    for (const value of [r.advance, r.baseline]) { view.setFloat32(offset, value, true); offset += 4; }
+    view.setUint16(offset, r.drawOffsetX, true); offset += 2;
+    view.setUint32(offset, r.triangles.length, true); offset += 4;
+    for (const t of r.triangles) {
+      for (const [x, y] of t.points) {
+        view.setUint16(offset, Math.round(x / r.width * 65535), true);
+        view.setUint16(offset + 2, Math.round(y / r.height * 65535), true); offset += 4;
+      }
+      view.setUint8(offset++, Math.round(t.average * 6));
+    }
+  }
+  if (offset !== size) throw new Error('اندازهٔ خروجی با رکوردها سازگار نیست.');
+  return bytes;
+}
+
+export async function compressTMG(records) {
+  return new Blob([await new Response(new Blob([encodeTMG(records)]).stream().pipeThrough(new CompressionStream('gzip'))).arrayBuffer()], { type: 'application/gzip' });
+}
+
+export function assertCoverage(records, extras = true) {
+  const map = new Map(records.map(r => [`${r.character}:${r.formIndex}`, r]));
+  const missing = repertoire(extras).filter(r => {
+    const found = map.get(`${r.character}:${r.formIndex}`);
+    return !found || (r.character.trim() && !found.triangles.length);
+  });
+  return missing.map(r => `${r.character}:${r.formIndex}`);
+}

package/src/motion-envelope.js

@@ -0,0 +1,22 @@
+// CSS display pixels, independent of source resolution and triangle density.
+// 32px at a 200px short side; sublinear growth with bounded extremes.
+export function imageMotionPixels(width,height){
+  const side=Math.max(1,Math.min(width,height));
+  return Math.min(64,Math.max(8,32*Math.sqrt(side/200)));
+}
+// Identity inside the normal envelope, C1-continuous outside it; no hard clamp.
+export function regulatedMotionLength(length,unit){
+  const radius=4*Math.max(unit,0.0001);
+  if(length<=radius)return length;
+  const excess=length-radius;
+  return radius+radius*excess/(radius+excess);
+}
+export const motionEnvelopeShader=`
+vec3 thdRegulateMotion(vec3 delta,float unit){
+  float radius=4.0*max(unit,0.0001);
+  float distance=length(delta);
+  if(distance<=radius)return delta;
+  float excess=distance-radius;
+  return delta*((radius+radius*excess/(radius+excess))/distance);
+}
+`;

package/src/motion.js

@@ -0,0 +1,52 @@
+export const MOTION_SAMPLES = 32;
+
+// A fixed-size radial lookup replaces one CPU rotation calculation per vertex.
+// The vertex shader and pointer projection interpolate the same samples.
+export class RadialMotion {
+  constructor() {
+    this.angles = new Float32Array(MOTION_SAMPLES * 2);
+    this.targetX = 0;
+    this.targetY = 0;
+    this.radius = 1;
+    this.active = false;
+  }
+
+  rotate(x, y) {
+    this.targetX += x;
+    this.targetY += y;
+    this.active = true;
+  }
+
+  step(dt) {
+    if (!this.active) return false;
+    let error = 0;
+    for (let i = 0; i < MOTION_SAMPLES; i++) {
+      const factor = 1 - Math.exp(-(11.9 - i / (MOTION_SAMPLES - 1) * 8.8) * dt);
+      for (let axis = 0; axis < 2; axis++) {
+        const at = i * 2 + axis;
+        const target = axis ? this.targetY : this.targetX;
+        this.angles[at] += (target - this.angles[at]) * factor;
+        error = Math.max(error, Math.abs(target - this.angles[at]));
+      }
+    }
+    this.active = error >= 0.0005;
+    if (!this.active) {
+      for (let i = 0; i < MOTION_SAMPLES; i++) {
+        this.angles[i * 2] = this.targetX;
+        this.angles[i * 2 + 1] = this.targetY;
+      }
+    }
+    return true;
+  }
+
+  transform(x, y, out, z = 0) {
+    const sample = Math.min(1, Math.hypot(x, y) / Math.max(this.radius, 0.001)) * (MOTION_SAMPLES - 1);
+    const low = Math.min(MOTION_SAMPLES - 2, Math.floor(sample));
+    const t = sample - low;
+    const ax = this.angles[low * 2] * (1 - t) + this.angles[(low + 1) * 2] * t;
+    const ay = this.angles[low * 2 + 1] * (1 - t) + this.angles[(low + 1) * 2 + 1] * t;
+    const ry = y * Math.cos(ax) - z * Math.sin(ax);
+    const rz = y * Math.sin(ax) + z * Math.cos(ax);
+    return out.set(x * Math.cos(ay) + rz * Math.sin(ay), ry, -x * Math.sin(ay) + rz * Math.cos(ay));
+  }
+}