Saurow
← Back to Articles
WEBGPU / TSLBreakdown

Three.js (TSL): Mesh Folding

Engineering interactive 3D card folding, dynamic trigonometric depth curvature, and backface texture correction using Three.js Shading Language (TSL) and WebGPU.

Live Demo ↗GitHub Repository ↗
Saurabh Thapliyal
Saurabh ThapliyalSep 2026 · 7 min read
Three.jsTSLWebGPUReact Three FiberGSAP
Saurow portfolio 3D interactive mesh card folding and TSL deformation
Figure 1: Interactive 3D folding mesh rendered with Three.js TSL WebGPU node materials, featuring dynamic trigonometric depth curvature, pointer falloff, and bilateral UV orientation.

I am Saurabh Thapliyal, and in this breakdown I deconstruct the mathematics and shader architecture behind our 3D Mesh Folding Card—an interactive experience built with Three.js Shading Language (TSL), WebGPU, and React Three Fiber. Here, I examine how we moved beyond rigid CSS transforms to engineer an authentic paper-like folding simulation with dynamic trigonometric depth curvature, bilateral texture orientation, and cursor-reactive surface tension.

Context & Inspiration

The tactile motion and physical aesthetic of this experiment draws direct inspiration from the acclaimed digital craftsmanship of Design Embraced ↗, where physical materiality, weight, and tangible feedback elevate interactive web design into an art form.

In interface design, 3D card flips are commonly implemented using CSS transform: rotateY(180deg) or flat Three.js planes. While functionally adequate, rigid planar rotation feels mechanical and artificial. Real materials—cardstock, parchment, or laminated paper—undergo tensile strain when folded. They bend, bow outwards along their transverse axis, and resist instantaneous angular displacement.

To replicate physical paper, we must displace the mesh's internal vertices along the Z-axis in mid-flip, peaking at 90 degrees before settling completely flat on the reverse face. By offloading this calculation entirely to GPU vertex shaders using Three.js TSL, we achieve buttery smooth 120 FPS deformation across high-density geometries with zero JavaScript main-thread calculation overhead.

Project Architecture

The component structure isolates the declarative R3F scene graph, procedural TSL uniform definitions, and DOM hover event dispatchers into modular layers:

saurow-fold / directory treeTREE
saurow-fold/
├── src/
│   ├── app/
│   │   ├── layout.tsx             # Root layout & dark viewport styling
│   │   └── page.tsx               # Home landing & 3D canvas viewport mount
│   ├── components/
│   │   ├── Header/                # Editorial navigation & branding
│   │   └── Landing/
│   │       ├── index.tsx          # DOM UI overlays, interactive trigger & CTA
│   │       ├── scene.tsx          # WebGPURenderer / R3F Canvas mount
│   │       ├── mesh.tsx           # Plane mesh (256 segments) & TSL material
│   │       └── style.module.scss  # Viewport layout & glassmorphic HUD
│   └── lib/
│       └── Shaders/
│           └── index.ts           # flipVertexNode, createTextureNode, TSL uniforms

The shader graph is maintained inside lib/Shaders/index.ts as standalone node exports. Because TSL nodes are pure composable JavaScript objects, they can be shared directly across materials, tested in isolation, and compiled natively to WGSL (WebGPU) or GLSL (WebGL) without string parsing.

Trigonometric Vertex Node Graph (flipVertexNode)

The core displacement logic operates within positionNode, replacing standard vertex matrix multiplication with a custom parametric deformation pipeline:

src/lib/Shaders/index.ts · TSL Vertex GraphTSL / TS
import {
    positionLocal,
    uv,
    vec2,
    vec3,
    vec4,
    uniform,
    texture,
    sin,
    cos,
    PI,
    length,
    smoothstep,
    select,
    float,
    frontFacing,
} from 'three/tsl';
import * as THREE from 'three';

// Uniforms
export const uBend = uniform(-0.2);
export const uPivot = uniform(0.0);
export const uCurve = uniform(0.35);
export const uMouse = uniform(new THREE.Vector2(0.5, 0.5));
export const uHover = uniform(0.0);
export const uBrightness = uniform(0.75);
export const uHeight = uniform(1.0);
export const uCoverScale = uniform(new THREE.Vector2(1.0, 1.0));

// Backface mouse Y inversion
const isBackFacingAngle = cos(uBend).lessThan(0.0);
const mouseY = select(isBackFacingAngle, float(1.0).sub(uMouse.y), uMouse.y);
const mouse = vec2(uMouse.x, mouseY);

// Cursor proximity falloff & bidirectional hover offset
const dist = length(uv().sub(mouse));
const falloff = smoothstep(0.25, 0.0, dist);
const faceDir = select(cos(uBend).greaterThanEqual(0.0), float(1.0), float(-1.0));
const hoverOffset = falloff.mul(0.2).mul(uHover).mul(faceDir);

// Mid-flight harmonic curvature
const flex = sin(uv().y.mul(PI)).mul(uCurve).mul(sin(uBend));
const initialZ = positionLocal.z.add(hoverOffset).sub(flex);

// Axial rotation relative to pivot point
const distY = positionLocal.y.sub(uPivot);
const distZ = initialZ;

const newY = uPivot.add(distY.mul(cos(uBend))).sub(distZ.mul(sin(uBend)));
const newZ = distY.mul(sin(uBend)).add(distZ.mul(cos(uBend)));

export const flipVertexNode = vec3(positionLocal.x, newY, newZ);

The vertex node computes displacement in three sequential stages:

  • Cursor Spring Offset: Calculates radial Euclidean distance from UV cursor coordinates with smoothstep interpolation, displacing vertices forward along the active face normal.
  • Mid-Flight Flex Curvature: Injects a parabolic sine-wave Z-depth displacement that scales dynamically with the folding angle (uBend).
  • Pivot Axis Rotation: Translates coordinates relative to uPivot, applies standard 2D rotation matrix math along Y and Z, and returns the final transformed 3D vector.

The Mathematics of Mid-Flight Flex

The signature visual element of the fold is its organic, rubber-sheet curvature during transit. This is achieved through a harmonic compound trigonometric function:

Trigonometric Surface Bow Formula
flex = sin(uv.y * π) * uCurve * sin(uBend)

This equation exhibits critical physical properties:

  • Zero Boundary Displacement: At the card's top edge (uv.y = 0.0) and bottom edge (uv.y = 1.0), sin(uv.y * π) equals 0.0. The edges remain pinned in space, preventing geometry detachment.
  • Cylindrical Arch Profile: At the vertical midpoint (uv.y = 0.5), sin(0.5 * π) = 1.0, producing maximal outward protrusion that mimics natural elastic sheet tension.
  • Dynamic Angular Gating: sin(uBend) acts as an automatic envelope generator. At rest on the front face (uBend = 0), sin(0) = 0. Mid-flip at 90 degrees (uBend = π/2), sin(π/2) = 1.0, unlocking full curvature. When the fold completes (uBend = π), sin(π) = 0, flattening the card completely against its destination.
Initial Angle & Curvature Tuning

The uCurve uniform sets the depth of the arc (configured to 0.35 for balanced physical tension). Notice also that uBend initializes at -0.2 rather than a completely flat 0.0. This deliberate resting offset introduces subtle 3D perspective and tactile depth the instant the page mounts.

Fragment Shading, Backface UV Orientation & Object-Fit Cover

A notorious issue in double-sided 3D planes is UV mirroring. When rotating 180 degrees around the Y-axis, the viewer observes the geometric backside of the polygons. Because standard texture coordinates run from left-to-right on the front face, viewing the rear face reverses the horizontal axis, rendering text and typography backwards.

Furthermore, textures loaded onto dynamically sized planes often suffer from stretching. In traditional CSS, we rely on object-fit: cover. In Three.js TSL, we solve both challenges inside a singleMeshBasicNodeMaterial by combining dynamic aspect ratio scaling with the built-in frontFacing conditional node:

src/lib/Shaders/index.ts · Fragment Texture NodeTSL / TS
// Fragment shader texture node with object-fit cover and automatic backface UV flip
export const createTextureNode = (map: THREE.Texture) => {
    const centeredUv = uv().sub(vec2(0.5, 0.5));
    const coverUv = centeredUv.mul(uCoverScale).add(vec2(0.5, 0.5));
    const backUv = vec2(coverUv.x, float(1.0).sub(coverUv.y));
    const correctedUv = select(frontFacing, coverUv, backUv);
    const sampled = texture(map, correctedUv);
    return vec4(sampled.rgb.mul(uBrightness), sampled.a);
};

In mesh.tsx, a useEffect listener compares the mesh aspect ratio (w / h) with the image natural aspect ratio (imgWidth / imgHeight):

  • If meshAspect < imageAspect, we set uCoverScale.value.set(meshAspect / imageAspect, 1.0).
  • Otherwise, we set uCoverScale.value.set(1.0, imageAspect / meshAspect).

When frontFacing evaluates to false on flip, select() effortlessly switches UV coordinates to the corrected back-face UV mapping (vec2(coverUv.x, 1.0 - coverUv.y)), multiplying sampled color by uBrightness (0.75) for a tailored editorial contrast.

Interactive Pointer Tracking & Scroll Parallax

To make the card feel alive between folding states, we combine pointer proximity deformation with momentum scroll parallax:

TSL Pointer Parity & FalloffTSL
// Cursor proximity falloff & bidirectional hover offset
const dist = length(uv().sub(mouse));
const falloff = smoothstep(0.25, 0.0, dist);
const faceDir = select(cos(uBend).greaterThanEqual(0.0), float(1.0), float(-1.0));
const hoverOffset = falloff.mul(0.2).mul(uHover).mul(faceDir);

Additionally, useFrame continuously samples window scroll progress:

src/components/Landing/mesh.tsx · Scroll ParallaxTSX
useFrame(() => {
  if (!meshRef.current) return;
  const scrollY = typeof window !== 'undefined' ? window.scrollY : 0;
  const vh = typeof window !== 'undefined' ? window.innerHeight : 800;
  const progress = Math.min(1.5, Math.max(0, scrollY / (vh || 1)));
  meshRef.current.rotation.x = -progress * 0.15;
  meshRef.current.position.y = -progress * 0.1;
});

As the visitor scrolls through the viewport, the mesh tilts gently forward and shifts downward, creating tactile cinematic depth that synchronizes with the typography.

GSAP Timeline Choreography: Anticipation & Flip Explosion

A convincing 3D flip animation requires dramatic timing. Rather than a linear flip, the animation employs classical Disney animation principles—specifically anticipation:

src/components/Landing/mesh.tsx · Component & TimelineTSX
'use client';

import React, { useRef, useMemo, useEffect } from 'react';
import * as THREE from 'three';
import { extend, useThree, ThreeEvent, ThreeElement, useFrame } from '@react-three/fiber';
import { useTexture } from '@react-three/drei';
import { MeshBasicNodeMaterial } from 'three/webgpu';
import gsap from 'gsap';
import { useGSAP } from '@gsap/react';
import {
    flipVertexNode,
    createTextureNode,
    uBend,
    uHover,
    uMouse,
    uCoverScale,
} from '@/lib/Shaders';

extend({ MeshBasicNodeMaterial });

declare module '@react-three/fiber' {
    interface ThreeElements {
        meshBasicNodeMaterial: ThreeElement<typeof MeshBasicNodeMaterial>;
    }
}

interface TextureImage {
    naturalWidth?: number;
    naturalHeight?: number;
    videoWidth?: number;
    videoHeight?: number;
    width?: number;
    height?: number;
}

function getCardDimensions(width: number) {
    if (width <= 480) return { w: 130, h: 143 };
    if (width <= 768) return { w: 150, h: 165 };
    if (width <= 1024) return { w: 175, h: 192 };
    return { w: 200, h: 220 };
}

function getTargetScale(width: number) {
    if (width <= 480) return 2.1;
    if (width <= 768) return 2.2;
    if (width <= 1024) return 2.3;
    return 2.5;
}

export default function MeshComponent() {
    const { viewport, size } = useThree();
    const texture = useTexture('/images/a.png');
    const meshRef = useRef<THREE.Mesh>(null!);
    const matRef = useRef<MeshBasicNodeMaterial>(null!);
    const card = useMemo(() => getCardDimensions(size.width), [size.width]);
    const w = viewport.width * (card.w / (size.width || 1));
    const h = viewport.height * (card.h / (size.height || 1));

    useEffect(() => {
        if (!texture) return;
        texture.colorSpace = THREE.SRGBColorSpace;

        const img = texture.image as TextureImage | undefined;
        const imgWidth = img?.naturalWidth || img?.videoWidth || img?.width || 1254;
        const imgHeight = img?.naturalHeight || img?.videoHeight || img?.height || 1254;
        const imageAspect = imgWidth / (imgHeight || 1);
        const meshAspect = w / (h || 1);

        if (meshAspect < imageAspect) {
            uCoverScale.value.set(meshAspect / imageAspect, 1.0);
        } else {
            uCoverScale.value.set(1.0, imageAspect / meshAspect);
        }
    }, [texture, w, h]);

    const colorNode = useMemo(() => createTextureNode(texture), [texture]);

    const handlePointerMove = (e: ThreeEvent<PointerEvent>) => {
        if (!meshRef.current) return;
        if (e.uv) {
            uMouse.value.set(e.uv.x, e.uv.y);
        }
    };

    const handlePointerEnter = () => {
        document.body.style.cursor = 'pointer';
        gsap.to(uHover, {
            value: 1,
            duration: 0.4,
            ease: 'power2.out',
        });
    };

    const handlePointerLeave = () => {
        document.body.style.cursor = 'default';
        gsap.to(uHover, {
            value: 0,
            duration: 0.6,
            ease: 'power2.out',
        });
    };

    useFrame(() => {
        if (!meshRef.current) return;
        const scrollY = typeof window !== 'undefined' ? window.scrollY : 0;
        const vh = typeof window !== 'undefined' ? window.innerHeight : 800;
        const progress = Math.min(1.5, Math.max(0, scrollY / (vh || 1)));
        meshRef.current.rotation.x = -progress * 0.15;
        meshRef.current.position.y = -progress * 0.1;
    });

    useGSAP(() => {
        if (!meshRef.current) return;

        const targetScale = getTargetScale(size.width);
        const tl = gsap.timeline({ delay: 1 });

        tl.to(meshRef.current.scale, {
            x: 0.85,
            y: 0.85,
            duration: 0.8,
            ease: 'power2.out',
        })
            .to(
                uBend,
                {
                    value: Math.PI,
                    duration: 1.8,
                    ease: 'power3.inOut',
                },
                'flip'
            )
            .to(
                meshRef.current.scale,
                {
                    x: targetScale,
                    y: targetScale,
                    duration: 1.8,
                    ease: 'power3.inOut',
                },
                'flip'
            );
    }, { scope: meshRef });

    return (
        <mesh
            ref={meshRef}
            scale={[1, 1, 1]}
            onPointerMove={handlePointerMove}
            onPointerEnter={handlePointerEnter}
            onPointerLeave={handlePointerLeave}
        >
            <planeGeometry args={[w, h, 128, 256]} />
            <meshBasicNodeMaterial
                ref={matRef}
                side={THREE.DoubleSide}
                transparent
                positionNode={flipVertexNode}
                colorNode={colorNode}
            />
        </mesh>
    );
};

The choreography unfolds in two distinct stages:

  • 1. Anticipation Recoil: Over 0.8s, the card scales down to 0.85, compressing slightly inward like a coiled spring.
  • 2. Simultaneous Flip & Scale Surge: Using the shared 'flip' timeline label, uBend rotates from 0 to π over 1.8s with power3.inOut easing, while the mesh scale expands outward from 0.85 to its viewport-responsive targetScale (up to 2.5x).

Rendered with <planeGeometry args={[w, h, 128, 256]} /> (128 horizontal x 256 vertical subdivisions), the resulting bend exhibits zero polygonal faceted seams.

Architectural Comparison: TSL vs. GLSL vs. CSS 3D

Evaluating how modern WebGPU node shaders improve upon legacy graphics techniques and DOM transforms:

Three.js TSL Node System

• Native WebGPU & WebGL compilation
• Type-safe shader graphs in pure TypeScript
• Zero runtime GLSL string parsing overhead
• Built-in dynamic frontFacing branching
• Uniforms animate directly via GSAP

Legacy GLSL ShaderMaterial

• Fragile raw string templates without linting
• Requires manual dual-plane mesh hacks for text
• WebGL 2 boilerplate & no WebGPU WGSL export
• Difficult to compose and share shader nodes

CSS 3D (transform-style)

• Rigid planar surfaces without vertex deformation
• Zero tensile bow or paper flex dynamics
• Layout thrashing and paint invalidation on low-end devices
• Unnatural digital feel

Performance & Frame Pacing

• Displaces 65,000+ vertices at 120 FPS
• 0ms JavaScript frame calculation cost
• Pure GPU compute execution
• Responsive layout scaling across all viewports

Saurabh Thapliyal
Saurabh Thapliyal

Creative developer based in Uttarakhand, India. Building interactive, motion-driven web experiences with a focus on WebGPU, Three.js, shaders, and smooth scroll architectures.

Portfolio ↗GitHub ↗X (Twitter) ↗
← Back to All ArticlesHome ↗