string-tune-3d 0.0.5 → 0.0.7

package/dist/index.d.mts

@@ -1,5 +1,63 @@
 import { StringModule, StringContext, StringObject, StringData } from '@fiddle-digital/string-tune';
 
+type UniformType = "float" | "int" | "vec2" | "vec3" | "vec4" | "color" | "texture" | "mat3" | "mat4";
+type UniformDefinition = {
+    type: UniformType;
+    value: any;
+    css?: string;
+};
+type ShaderInjectionPoint = "vertex_pars" | "vertex_header" | "vertex_transform" | "vertex_output" | "fragment_pars" | "fragment_header" | "fragment_color" | "fragment_normal" | "fragment_emissive" | "fragment_output";
+type ShaderInjection = {
+    point: ShaderInjectionPoint;
+    code: string;
+    order?: number;
+};
+type MaterialBlendMode = "normal" | "additive" | "subtractive" | "multiply";
+type MaterialSide = "front" | "back" | "double";
+type String3DCustomMaterialDefinition = {
+    name: string;
+    extends?: "basic" | "standard" | "physical" | "shader";
+    vertexShader?: string;
+    fragmentShader?: string;
+    injections?: ShaderInjection[];
+    uniforms?: Record<string, UniformDefinition>;
+    properties?: {
+        transparent?: boolean;
+        side?: MaterialSide;
+        depthWrite?: boolean;
+        depthTest?: boolean;
+        blending?: MaterialBlendMode;
+        wireframe?: boolean;
+    };
+    lights?: boolean;
+    parse?: (element: HTMLElement, style: CSSStyleDeclaration) => Record<string, any>;
+};
+declare class String3DCustomMaterialRegistry {
+    private static materials;
+    private static registeredCssVars;
+    static register(definition: String3DCustomMaterialDefinition): void;
+    private static registerCssVarsForMaterial;
+    private static resolveCssSyntax;
+    private static defaultCssInitialValue;
+    static get(name: string): String3DCustomMaterialDefinition | undefined;
+    static has(name: string): boolean;
+    static list(): String3DCustomMaterialDefinition[];
+    static unregister(name: string): boolean;
+}
+
+type MaterialUpdateCallback = (uniforms: Record<string, any>) => void;
+interface IMaterialInstance {
+    material: any;
+    definition: String3DCustomMaterialDefinition;
+    update: MaterialUpdateCallback;
+    dispose: () => void;
+}
+interface IMaterialFactory {
+    supports(definition: String3DCustomMaterialDefinition): boolean;
+    create(definition: String3DCustomMaterialDefinition, initialUniforms?: Record<string, any>): IMaterialInstance;
+    parseUniformsFromCSS(definition: String3DCustomMaterialDefinition, element: HTMLElement, style: CSSStyleDeclaration): Record<string, any>;
+}
+
 interface I3DVector3 {
     x: number;
     y: number;
@@ -74,6 +132,59 @@ interface I3DMaterial {
     opacity?: number;
     transparent?: boolean;
 }
+interface I3DRenderTarget {
+    texture: any;
+    width: number;
+    height: number;
+    setSize(width: number, height: number): void;
+    dispose(): void;
+}
+type ParticleMode = "emitter" | "instanced";
+type ParticleSystemConfig = {
+    mode: ParticleMode;
+    count: number;
+    size: number;
+    color: string;
+    opacity: number;
+    spread: number;
+    seed: number;
+    emitRate: number;
+    emitBurst: number;
+    particleLife: number;
+    particleSpeed: number;
+    particleDirection: [number, number, number];
+    particleGravity: [number, number, number];
+    particleDrag: number;
+    particleSizeVariation: number;
+    particleColorVariation: number;
+    particleShape: "box" | "sphere" | "model";
+    particleModelUrl: string;
+    particleModelLoader: string;
+    particleModelNode: string;
+    instanceShape: "box" | "sphere" | "model";
+    instanceModelUrl: string;
+    instanceModelLoader: string;
+    instanceModelNode: string;
+    instanceScale: number;
+    instanceScaleVariation: number;
+    instanceRotationSpeed: number;
+    instanceJitter: number;
+    instanceFlow: number;
+    instanceDisperse: number;
+    instanceDisperseScatter: number;
+    instanceDisperseScatterX: number;
+    instanceDisperseScatterY: number;
+    instanceDisperseScatterZ: number;
+};
+interface I3DParticleSystem extends I3DObject {
+    update?(dt: number): void;
+    setConfig?(config: ParticleSystemConfig): void;
+    setMaterial?(material: I3DMaterial | null, options?: {
+        points?: boolean;
+        meshes?: boolean;
+    }): void;
+    dispose?(): void;
+}
 interface I3DLight extends I3DObject {
     color: any;
     intensity: number;
@@ -117,10 +228,32 @@ interface I3DRenderer {
         enabled: boolean;
         type: any;
     };
+    setRenderTarget?(target: I3DRenderTarget | null): void;
+    getRenderTarget?(): I3DRenderTarget | null;
+    clear?(color?: boolean, depth?: boolean, stencil?: boolean): void;
 }
 interface I3DTextureLoader {
     load(url: string, onLoad?: (texture: any) => void): any;
 }
+type TextGeometryOptions = {
+    size: number;
+    height: number;
+    curveSegments: number;
+    bevelEnabled: boolean;
+    bevelThickness: number;
+    bevelSize: number;
+    bevelOffset: number;
+    bevelSegments: number;
+    lineHeight: number;
+    letterSpacing: number;
+    align: "left" | "center" | "right";
+    layout?: Array<{
+        char: string;
+        x: number;
+        y: number;
+        scale?: number;
+    }>;
+};
 interface I3DModelLoader {
     load(url: string, onLoad?: (model: any) => void, onProgress?: (progress: any) => void, onError?: (error: any) => void): void;
 }
@@ -147,6 +280,7 @@ interface I3DEngine {
     createCylinderGeometry(radiusTop: number, radiusBottom: number, height: number, segments?: number): I3DGeometry;
     createMeshBasicMaterial(params?: any): I3DMaterial;
     createMeshStandardMaterial(params?: any): I3DMaterial;
+    createShaderMaterial?(params?: any): I3DMaterial;
     createPointLight(color?: string | number, intensity?: number, distance?: number, decay?: number): I3DLight;
     createSpotLight(color?: string | number, intensity?: number, distance?: number, angle?: number, penumbra?: number, decay?: number): I3DLight;
     createHemisphereLight(skyColor?: string | number, groundColor?: string | number, intensity?: number): I3DLight;
@@ -154,6 +288,12 @@ interface I3DEngine {
     createDirectionalLight(color?: string | number, intensity?: number): I3DLight;
     createTextureLoader(): I3DTextureLoader;
     createModelLoader(type: string): I3DModelLoader;
+    createRenderTarget?(width: number, height: number, options?: any): I3DRenderTarget;
+    getMaterialFactory?(): IMaterialFactory | null;
+    createParticleSystem?(config: ParticleSystemConfig): I3DParticleSystem;
+    loadFont?(url: string): Promise<any>;
+    createTextGeometry?(text: string, font: any, options: TextGeometryOptions): I3DGeometry | null;
+    simplifyGeometry?(geometry: I3DGeometry, quality: number): I3DGeometry | null;
     degToRad(degrees: number): number;
     radToDeg(radians: number): number;
     computeBoundingBoxRecursively(object: I3DObject): I3DBox3;
@@ -172,8 +312,8 @@ interface String3DOptions {
     modelLoader?: I3DModelLoader;
     modelLoaderFactory?: (engine: I3DEngine, type?: string) => I3DModelLoader;
     useDirtySync?: boolean;
-    useTransformWorker?: boolean;
-    transformWorkerWasmUrl?: string;
+    styleReadIntervalMs?: number;
+    layoutReadIntervalMs?: number;
 }
 declare class String3D extends StringModule {
     private static provider;
@@ -186,19 +326,14 @@ declare class String3D extends StringModule {
     private isLoading;
     private options;
     private useDirtySync;
-    private dirtyElements;
-    private observedElements;
-    private resizeObserver;
-    private mutationObserver;
+    private dirtySyncManager;
     private lastSyncData;
-    private transformWorker;
-    private workerHasResult;
-    private workerObjectMap;
-    private domVersion;
-    private lastSubmittedVersion;
-    private scrollTicking;
-    private onScrollBound;
+    private filterController;
     static setProvider(provider: I3DEngineProvider): void;
+    static registerFont(name: string, url: string, options?: {
+        default?: boolean;
+    }): void;
+    static setDefaultFont(name: string): void;
     constructor(context: StringContext);
     canConnect(object: StringObject): boolean;
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
@@ -213,22 +348,10 @@ declare class String3D extends StringModule {
     private applyContainerStyles;
     onObjectConnected(object: StringObject): void;
     onFrame(data: StringData): void;
+    private batchReadLayouts;
     private syncRecursive;
     private injectCSS;
     private registerTypedProperties;
-    private setupObservers;
-    private setupScrollListeners;
-    private removeScrollListeners;
-    private handleScroll;
-    private observeElement;
-    private observeSceneElements;
-    private observeRecursive;
-    private markDirty;
-    private markAllDirty;
-    private readNumberStyle;
-    private buildWorkerCameraData;
-    private collectWorkerInputs;
-    private applyWorkerResults;
     destroy(): void;
 }
 
@@ -274,6 +397,8 @@ declare class String3DObject {
     private _bbox;
     el: any;
     private _children;
+    private _flatObjectsCache;
+    private _subtreeCache;
     private engine;
     get children(): String3DObject[];
     constructor(id: string, type: string, object: I3DObject, engine: I3DEngine, options?: {
@@ -303,6 +428,10 @@ declare class String3DObject {
     set geometry(geometry: I3DGeometry | undefined);
     updateBoundingBox(): void;
     destroy(): void;
+    getFlatObjects(): I3DObject[];
+    getSubtreeObjects(): I3DObject[];
+    private invalidateFlatCache;
+    private invalidateSubtreeCache;
     private disposeObjectResources;
 }
 
@@ -315,6 +444,7 @@ declare class String3DScene {
     private _objects;
     private _rootObjects;
     private _elementMap;
+    private _materialInstances;
     private engine;
     private _modelLoader?;
     private _modelLoaderFactory?;
@@ -323,6 +453,7 @@ declare class String3DScene {
     constructor(engine: I3DEngine, options?: String3DSceneOptions);
     getScene(): I3DScene;
     getObject(id: string): String3DObject | undefined;
+    getAllObjects(): String3DObject[];
     hasObject(id: string): boolean;
     deleteObject(id: string): boolean;
     createFromElement(object: StringObject): void;
@@ -334,11 +465,17 @@ declare class String3DScene {
     private createPlane;
     private createCylinder;
     private createModel;
+    private createParticles;
+    private createText;
+    private getGeometryQuality;
     private resolveModelLoader;
     private centerObject;
     private getBoxCenter;
     private createMaterialFromObject;
     private createMaterialFromElement;
+    private tryCreateCustomMaterial;
+    updateMaterialUniforms(objectId: string, uniforms: Record<string, any>): void;
+    getMaterialInstance(objectId: string): IMaterialInstance | undefined;
     private loadTexture;
     private parseFlipY;
     private shouldOverrideModelMaterial;
@@ -346,20 +483,87 @@ declare class String3DScene {
     destroy(): void;
 }
 
+type String3DFilterEffect = {
+    type: "blur";
+    amount: number;
+} | {
+    type: "pixel";
+    size: number;
+} | {
+    type: "bloom";
+    intensity: number;
+    threshold: number;
+} | {
+    type: "brightness";
+    amount: number;
+} | {
+    type: "contrast";
+    amount: number;
+} | {
+    type: "saturate";
+    amount: number;
+} | {
+    type: "grayscale";
+    amount: number;
+} | {
+    type: "sepia";
+    amount: number;
+} | {
+    type: "invert";
+    amount: number;
+} | {
+    type: "hue-rotate";
+    angle: number;
+} | {
+    type: "custom";
+    name: string;
+    uniforms: Record<string, any>;
+};
+type String3DFilterChain = String3DFilterEffect[];
+type String3DFilterTarget = {
+    object: String3DObject;
+    effects: String3DFilterChain;
+    effectsKey: string;
+    dirty: boolean;
+};
+
 declare class String3DRenderer {
     private _container;
     private _renderer;
     private _width;
     private _height;
     private engine;
+    private filterPipeline;
+    private filterCache;
+    private frameId;
+    private lastFrameTime;
+    private avgFrameMs;
+    private qualityScale;
+    private lastQualityChange;
+    private filterLayer;
     constructor(container: HTMLElement, engine: I3DEngine);
     attach(): void;
-    render(scene: String3DScene, camera: String3DCamera): void;
+    render(scene: String3DScene, camera: String3DCamera, filterTargets?: String3DFilterTarget[]): void;
     resize(camera: String3DCamera): void;
     get width(): number;
     get height(): number;
     get renderer(): I3DRenderer;
     destroy(): void;
+    private ensureFilterPipeline;
+    private canCreateFilterPipeline;
+    private collectSubtreeObjects;
+    private setVisible;
+    private getFilterCenter;
+    private injectEffectContext;
+    private updateQuality;
+    private invalidateFilterCache;
+    private evictCache;
+    private supportsLayers;
+    private hasLayers;
+    private applyLayerMask;
+    private restoreLayerMask;
+    private setCameraLayer;
+    private restoreCameraLayer;
 }
 
 declare class String3DSynchronizer {
@@ -368,15 +572,96 @@ declare class String3DSynchronizer {
     viewportHeight: number;
     engine: I3DEngine;
     private strategies;
+    private styleReadIntervalMs;
+    private layoutReadIntervalMs;
     constructor(camera: String3DCamera, viewportWidth: number, viewportHeight: number, engine: I3DEngine);
-    syncElement(el: HTMLElement, object: String3DObject, parentData: any): any;
+    syncElement(el: HTMLElement, object: String3DObject, parentData: any, hints?: {
+        dirtySet?: Set<HTMLElement> | null;
+        forceSync?: boolean;
+    }): any;
+    setSyncOptions(options: {
+        styleReadIntervalMs?: number;
+        layoutReadIntervalMs?: number;
+    }): void;
     updateViewportSize(width: number, height: number): void;
 }
 
+type String3DCustomFilterDefinition = {
+    name: string;
+    fragmentShader: string;
+    uniforms?: Record<string, any>;
+    parse?: (args: string) => Record<string, any> | null;
+};
+declare class String3DCustomFilterRegistry {
+    private static filters;
+    static register(definition: String3DCustomFilterDefinition): void;
+    static get(name: string): String3DCustomFilterDefinition | undefined;
+    static has(name: string): boolean;
+    static list(): String3DCustomFilterDefinition[];
+}
+
+type String3DFontEntry = {
+    name: string;
+    url: string;
+};
+declare class String3DFontRegistry {
+    private static fonts;
+    private static defaultFont;
+    static register(name: string, url: string): void;
+    static setDefault(name: string): void;
+    static get(name: string): String3DFontEntry | undefined;
+    static list(): String3DFontEntry[];
+    static resolveFontFamily(fontFamily: string): String3DFontEntry | null;
+    private static getDefault;
+}
+
+interface FontData {
+    glyphs: Record<string, GlyphData>;
+    familyName: string;
+    ascender: number;
+    descender: number;
+    underlinePosition: number;
+    underlineThickness: number;
+    boundingBox: {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+    resolution: number;
+    original_font_information: Record<string, any>;
+}
+interface GlyphData {
+    ha: number;
+    x_min: number;
+    x_max: number;
+    o: string;
+}
+type FontSource = string | ArrayBuffer | Uint8Array;
+declare class FontConverter {
+    private static cache;
+    private static loadingPromises;
+    static load(source: FontSource): Promise<FontData>;
+    private static doLoad;
+    private static convertToTypeFace;
+    private static pathToOutline;
+    private static round;
+    static isTypefaceJson(url: string): boolean;
+    static isFontFile(url: string): boolean;
+    static clearCache(): void;
+}
+
 declare class ThreeJSEngine implements I3DEngine {
     private THREE;
     private loaders;
+    private materialFactory;
+    private particleModelCache;
+    private particleModelPromiseCache;
+    private fontCache;
+    private fontPromiseCache;
+    private fontMetricsCache;
     constructor(THREE: any, loaders?: Record<string, any>);
+    getMaterialFactory(): IMaterialFactory | null;
     createVector3(x?: number, y?: number, z?: number): I3DVector3;
     createVector2(x?: number, y?: number): I3DVector2;
     createQuaternion(x?: number, y?: number, z?: number, w?: number): I3DQuaternion;
@@ -399,6 +684,7 @@ declare class ThreeJSEngine implements I3DEngine {
     createCylinderGeometry(radiusTop: number, radiusBottom: number, height: number, segments?: number): I3DGeometry;
     createMeshBasicMaterial(params?: any): I3DMaterial;
     createMeshStandardMaterial(params?: any): I3DMaterial;
+    createShaderMaterial(params?: any): I3DMaterial;
     createPointLight(color?: string | number, intensity?: number, distance?: number, decay?: number): I3DLight;
     createSpotLight(color?: string | number, intensity?: number, distance?: number, angle?: number, penumbra?: number, decay?: number): I3DLight;
     createHemisphereLight(skyColor?: string | number, groundColor?: string | number, intensity?: number): I3DLight;
@@ -406,6 +692,36 @@ declare class ThreeJSEngine implements I3DEngine {
     createDirectionalLight(color?: string | number, intensity?: number): I3DLight;
     createTextureLoader(): I3DTextureLoader;
     createModelLoader(type: string): I3DModelLoader;
+    createRenderTarget(width: number, height: number, options?: any): I3DRenderTarget;
+    loadFont(url: string): Promise<any>;
+    private loadFontWithConverter;
+    private loadFontWithLoader;
+    /**
+     * Create a Three.js-compatible Font object from FontData
+     */
+    private createFontFromData;
+    /**
+     * Generate Three.js Shapes from FontData for given text
+     * This generates shapes for a SINGLE character only (used by buildLineShapes)
+     */
+    private generateShapesFromFontData;
+    private parseOutlineToShapes;
+    private reversePath;
+    createTextGeometry(text: string, font: any, options: any): I3DGeometry | null;
+    private buildLineShapes;
+    private getGlyphAdvance;
+    private translateShape;
+    private scaleShape;
+    private buildGlyphShapesFromCanvas;
+    private measureFontMetrics;
+    private traceContoursFromAlpha;
+    private simplifyCollinear;
+    private simplifyRdp;
+    private pointLineDistance;
+    private contoursToShapes;
+    private resolveParticleModelGeometry;
+    createParticleSystem(config: ParticleSystemConfig): I3DParticleSystem;
+    simplifyGeometry(geometry: I3DGeometry, quality: number): I3DGeometry | null;
     degToRad(degrees: number): number;
     radToDeg(radians: number): number;
     computeBoundingBoxRecursively(object: I3DObject): I3DBox3;
@@ -417,4 +733,28 @@ declare class ThreeJSProvider implements I3DEngineProvider {
     getName(): string;
 }
 
-export { type CameraMode, type I3DBox3, type I3DCamera, type I3DEngine, type I3DEngineProvider, type I3DEuler, type I3DGeometry, type I3DLight, type I3DMaterial, type I3DMatrix4, type I3DMesh, type I3DModelLoader, type I3DObject, type I3DOrthographicCamera, type I3DPerspectiveCamera, type I3DQuaternion, type I3DRenderer, type I3DScene, type I3DTextureLoader, type I3DVector2, type I3DVector3, String3D, String3DCamera, String3DObject, type String3DOptions, String3DRenderer, String3DScene, String3DSynchronizer, ThreeJSEngine, ThreeJSProvider };
+declare class ThreeJSMaterialFactory implements IMaterialFactory {
+    private THREE;
+    private textureLoader;
+    private textureCache;
+    constructor(THREE: any);
+    supports(definition: String3DCustomMaterialDefinition): boolean;
+    create(definition: String3DCustomMaterialDefinition, initialUniforms?: Record<string, any>): IMaterialInstance;
+    parseUniformsFromCSS(definition: String3DCustomMaterialDefinition, element: HTMLElement, style: CSSStyleDeclaration): Record<string, any>;
+    private buildUniforms;
+    private convertUniformValue;
+    private loadTexture;
+    private createShaderMaterial;
+    private createExtendedMaterial;
+    private injectVertexShader;
+    private injectFragmentShader;
+    private generateUniformDeclarations;
+    private inferGLSLType;
+    private applyMaterialProperties;
+    private updateUniforms;
+    private getDefaultVertexShader;
+    private getDefaultFragmentShader;
+    dispose(): void;
+}
+
+export { type CameraMode, FontConverter, type FontData, type FontSource, type I3DBox3, type I3DCamera, type I3DEngine, type I3DEngineProvider, type I3DEuler, type I3DGeometry, type I3DLight, type I3DMaterial, type I3DMatrix4, type I3DMesh, type I3DModelLoader, type I3DObject, type I3DOrthographicCamera, type I3DParticleSystem, type I3DPerspectiveCamera, type I3DQuaternion, type I3DRenderTarget, type I3DRenderer, type I3DScene, type I3DTextureLoader, type I3DVector2, type I3DVector3, type IMaterialFactory, type IMaterialInstance, type MaterialBlendMode, type MaterialSide, type ParticleMode, type ParticleSystemConfig, type ShaderInjection, type ShaderInjectionPoint, String3D, String3DCamera, type String3DCustomFilterDefinition, String3DCustomFilterRegistry, type String3DCustomMaterialDefinition, String3DCustomMaterialRegistry, type String3DFontEntry, String3DFontRegistry, String3DObject, type String3DOptions, String3DRenderer, String3DScene, String3DSynchronizer, ThreeJSEngine, ThreeJSMaterialFactory, ThreeJSProvider, type UniformDefinition, type UniformType };