@call-me-sensei/toonlab 0.1.1

package/src/shaders-tsl/chunks/character-roles.js

@@ -0,0 +1,52 @@
+// TSL port of src/shaders/chunks/character-fragment-roles.glsl — material
+// role ids and the role debug view color.
+
+import { select, vec3 } from 'three/tsl';
+
+export const MATERIAL_ROLE_DEFAULT = 0;
+export const MATERIAL_ROLE_COSTUME = 1;
+export const MATERIAL_ROLE_SKIN = 2;
+export const MATERIAL_ROLE_FACE = 3;
+export const MATERIAL_ROLE_HAIR = 4;
+export const MATERIAL_ROLE_EYE = 5;
+export const MATERIAL_ROLE_EYE_HIGHLIGHT = 6;
+export const MATERIAL_ROLE_BLUSH = 7;
+export const MATERIAL_ROLE_TRANSPARENT_OVERLAY = 8;
+export const MATERIAL_ROLE_METAL = 9;
+export const MATERIAL_ROLE_OUTLINE = 10;
+export const MATERIAL_ROLE_IRIS = 11;
+export const MATERIAL_ROLE_PUPIL = 12;
+export const MATERIAL_ROLE_SCLERA = 13;
+export const MATERIAL_ROLE_CATCHLIGHT = 14;
+
+const ROLE_DEBUG_COLORS = [
+  [MATERIAL_ROLE_OUTLINE, [0.02, 0.02, 0.024]],
+  [MATERIAL_ROLE_CATCHLIGHT, [1.0, 0.96, 0.64]],
+  [MATERIAL_ROLE_EYE_HIGHLIGHT, [1.0, 1.0, 1.0]],
+  [MATERIAL_ROLE_PUPIL, [0.08, 0.08, 0.11]],
+  [MATERIAL_ROLE_IRIS, [0.52, 0.28, 1.0]],
+  [MATERIAL_ROLE_SCLERA, [0.7, 0.92, 1.0]],
+  [MATERIAL_ROLE_EYE, [0.18, 0.55, 1.0]],
+  [MATERIAL_ROLE_FACE, [1.0, 0.42, 0.58]],
+  [MATERIAL_ROLE_SKIN, [1.0, 0.73, 0.42]],
+  [MATERIAL_ROLE_HAIR, [0.28, 0.68, 1.0]],
+  [MATERIAL_ROLE_BLUSH, [1.0, 0.32, 0.48]],
+  [MATERIAL_ROLE_TRANSPARENT_OVERLAY, [0.74, 0.45, 1.0]],
+  [MATERIAL_ROLE_METAL, [1.0, 0.77, 0.23]],
+  [MATERIAL_ROLE_COSTUME, [0.44, 0.5, 0.62]],
+];
+
+export function createRolesChunk({ u, flags }) {
+  const debugMaterialRoleColor = () => {
+    if (flags.isOutlinePass) return vec3(0.02, 0.02, 0.024);
+    let color = vec3(0.56, 0.58, 0.62);
+    // Build the GLSL if-chain back-to-front so earlier entries win.
+    for (let i = ROLE_DEBUG_COLORS.length - 1; i >= 0; i -= 1) {
+      const [role, rgb] = ROLE_DEBUG_COLORS[i];
+      color = select(u.materialRole.equal(role), vec3(...rgb), color);
+    }
+    return color;
+  };
+
+  return { debugMaterialRoleColor };
+}

package/src/shaders-tsl/chunks/character-scene-lights.js

@@ -0,0 +1,270 @@
+// TSL replacement for the three.js classic light uniforms the GLSL character
+// shader consumes via <lights_pars_begin> (directionalLights[0], pointLights,
+// spotLights, hemisphereLights, ambientLightColor).
+//
+// The node renderer has its own light system (LightsNode + LightingModel),
+// but the toon model needs raw ingredients — the first directional light as
+// "the main light", per-light toon bands instead of physical accumulation,
+// and the shadow mask separate from the light color — so the light state is
+// mirrored into shared uniforms instead. `syncToonSceneLights(scene, camera)`
+// runs from the converted meshes' onBeforeRender (both renderers call it),
+// so no per-lab plumbing is needed; every toon material shares these nodes.
+//
+// View-space conventions and attenuation math replicate three's WebGLLights
+// exactly (direction = toward the light, color premultiplied by intensity).
+
+import * as THREE from 'three';
+import {
+  dot,
+  float,
+  Fn,
+  If,
+  max,
+  mix,
+  normalize,
+  pow,
+  smoothstep,
+  uniform,
+  uniformArray,
+  vec3,
+} from 'three/tsl';
+
+export const MAX_TOON_POINT_LIGHTS = 8;
+export const MAX_TOON_SPOT_LIGHTS = 4;
+export const MAX_TOON_HEMI_LIGHTS = 2;
+
+function vectorArray(count) {
+  return Array.from({ length: count }, () => new THREE.Vector3());
+}
+
+export const toonSceneLights = {
+  ambientLightColor: uniform(new THREE.Color(0, 0, 0)),
+  hasMainLight: uniform(0, 'float'),
+  mainLightColor: uniform(new THREE.Color(1, 1, 1)),
+  mainLightDirection: uniform(new THREE.Vector3(0.35, 0.75, 0.55)),
+
+  pointLightColors: uniformArray(vectorArray(MAX_TOON_POINT_LIGHTS), 'vec3'),
+  pointLightCount: uniform(0, 'float'),
+  // x: cutoff distance, y: decay exponent
+  pointLightParams: uniformArray(
+    Array.from({ length: MAX_TOON_POINT_LIGHTS }, () => new THREE.Vector2()),
+    'vec2',
+  ),
+  pointLightPositions: uniformArray(vectorArray(MAX_TOON_POINT_LIGHTS), 'vec3'),
+
+  spotLightColors: uniformArray(vectorArray(MAX_TOON_SPOT_LIGHTS), 'vec3'),
+  spotLightCount: uniform(0, 'float'),
+  spotLightDirections: uniformArray(vectorArray(MAX_TOON_SPOT_LIGHTS), 'vec3'),
+  // x: cutoff distance, y: decay, z: coneCos, w: penumbraCos
+  spotLightParams: uniformArray(
+    Array.from({ length: MAX_TOON_SPOT_LIGHTS }, () => new THREE.Vector4()),
+    'vec4',
+  ),
+  spotLightPositions: uniformArray(vectorArray(MAX_TOON_SPOT_LIGHTS), 'vec3'),
+
+  hemiLightCount: uniform(0, 'float'),
+  hemiLightDirections: uniformArray(vectorArray(MAX_TOON_HEMI_LIGHTS), 'vec3'),
+  hemiLightGroundColors: uniformArray(vectorArray(MAX_TOON_HEMI_LIGHTS), 'vec3'),
+  hemiLightSkyColors: uniformArray(vectorArray(MAX_TOON_HEMI_LIGHTS), 'vec3'),
+};
+
+const workColor = new THREE.Color();
+const workVectorA = new THREE.Vector3();
+const workVectorB = new THREE.Vector3();
+
+function lightIsOn(light) {
+  return light.visible !== false && (light.intensity ?? 0) > 0;
+}
+
+/**
+ * Mirrors the scene's light state into the shared toon light uniforms —
+ * the node-backend equivalent of three's WebGLLights setup for the subset
+ * the character shader reads. Cheap enough to run once per rendered frame.
+ */
+export function syncToonSceneLights(scene, camera) {
+  if (!scene || !camera) return;
+  const viewMatrix = camera.matrixWorldInverse;
+  const s = toonSceneLights;
+
+  let ambientR = 0;
+  let ambientG = 0;
+  let ambientB = 0;
+  let mainLightFound = false;
+  let pointCount = 0;
+  let spotCount = 0;
+  let hemiCount = 0;
+
+  scene.traverse((light) => {
+    if (!light.isLight || !lightIsOn(light)) return;
+
+    if (light.isAmbientLight) {
+      ambientR += light.color.r * light.intensity;
+      ambientG += light.color.g * light.intensity;
+      ambientB += light.color.b * light.intensity;
+      return;
+    }
+
+    if (light.isDirectionalLight) {
+      // First directional light in traversal order is "the main light",
+      // matching directionalLights[0] in the classic pipeline.
+      if (mainLightFound) return;
+      mainLightFound = true;
+      workVectorA.setFromMatrixPosition(light.matrixWorld);
+      workVectorB.setFromMatrixPosition(light.target.matrixWorld);
+      workVectorA.sub(workVectorB).transformDirection(viewMatrix);
+      s.mainLightDirection.value.copy(workVectorA);
+      workColor.copy(light.color).multiplyScalar(light.intensity);
+      s.mainLightColor.value.copy(workColor);
+      return;
+    }
+
+    if (light.isPointLight && pointCount < MAX_TOON_POINT_LIGHTS) {
+      const index = pointCount;
+      pointCount += 1;
+      workVectorA.setFromMatrixPosition(light.matrixWorld).applyMatrix4(viewMatrix);
+      s.pointLightPositions.array[index].copy(workVectorA);
+      workColor.copy(light.color).multiplyScalar(light.intensity);
+      s.pointLightColors.array[index].set(workColor.r, workColor.g, workColor.b);
+      s.pointLightParams.array[index].set(light.distance ?? 0, light.decay ?? 2);
+      return;
+    }
+
+    if (light.isSpotLight && spotCount < MAX_TOON_SPOT_LIGHTS) {
+      const index = spotCount;
+      spotCount += 1;
+      workVectorA.setFromMatrixPosition(light.matrixWorld).applyMatrix4(viewMatrix);
+      s.spotLightPositions.array[index].copy(workVectorA);
+      workVectorA.setFromMatrixPosition(light.matrixWorld);
+      workVectorB.setFromMatrixPosition(light.target.matrixWorld);
+      workVectorA.sub(workVectorB).transformDirection(viewMatrix);
+      s.spotLightDirections.array[index].copy(workVectorA);
+      workColor.copy(light.color).multiplyScalar(light.intensity);
+      s.spotLightColors.array[index].set(workColor.r, workColor.g, workColor.b);
+      s.spotLightParams.array[index].set(
+        light.distance ?? 0,
+        light.decay ?? 2,
+        Math.cos(light.angle),
+        Math.cos(light.angle * (1 - light.penumbra)),
+      );
+      return;
+    }
+
+    if (light.isHemisphereLight && hemiCount < MAX_TOON_HEMI_LIGHTS) {
+      const index = hemiCount;
+      hemiCount += 1;
+      workVectorA.setFromMatrixPosition(light.matrixWorld).transformDirection(viewMatrix);
+      s.hemiLightDirections.array[index].copy(workVectorA);
+      workColor.copy(light.color).multiplyScalar(light.intensity);
+      s.hemiLightSkyColors.array[index].set(workColor.r, workColor.g, workColor.b);
+      workColor.copy(light.groundColor).multiplyScalar(light.intensity);
+      s.hemiLightGroundColors.array[index].set(workColor.r, workColor.g, workColor.b);
+    }
+  });
+
+  s.ambientLightColor.value.setRGB(ambientR, ambientG, ambientB);
+  s.hasMainLight.value = mainLightFound ? 1 : 0;
+  s.pointLightCount.value = pointCount;
+  s.spotLightCount.value = spotCount;
+  s.hemiLightCount.value = hemiCount;
+}
+
+/** getMainLightDirection(): first directional light or the GLSL fallback. */
+export const getMainLightDirection = /*@__PURE__*/ Fn(() => {
+  const fallback = normalize(vec3(0.35, 0.75, 0.55));
+  const main = normalize(toonSceneLights.mainLightDirection);
+  return mix(fallback, main, toonSceneLights.hasMainLight);
+});
+
+/** getMainLightColor(): clamped main light color or white fallback. */
+export function getMainLightColor(mainLightMaxContribution) {
+  const clamped = min3(vec3(mainLightMaxContribution), toonSceneLights.mainLightColor);
+  return mix(vec3(1.0), clamped, toonSceneLights.hasMainLight);
+}
+
+function min3(a, b) {
+  return vec3(a).min(vec3(b));
+}
+
+// three's getDistanceAttenuation (common.glsl) — physically based falloff
+// with the artist cutoff window.
+const distanceAttenuation = /*@__PURE__*/ Fn(([lightDistance, cutoffDistance, decayExponent]) => {
+  const distanceFalloff = float(1.0).div(max(pow(lightDistance, decayExponent), 0.01)).toVar();
+  If(cutoffDistance.greaterThan(0.0), () => {
+    const ratio = lightDistance.div(cutoffDistance);
+    const ratio2 = ratio.mul(ratio);
+    const window1 = ratio2.mul(ratio2).oneMinus().clamp(0.0, 1.0);
+    distanceFalloff.mulAssign(window1.mul(window1));
+  });
+  return distanceFalloff;
+});
+
+/**
+ * evaluateLocalLightFill + evaluateHemisphereFill, assembled per material.
+ * `localLightBand` is the toon band the GLSL applies per local light; the
+ * caller provides it (it depends on material uniforms). Returns
+ * { localLight, strongestLocalLight, hemisphereFill } node factories.
+ */
+export function createLocalLightEvaluators({ localLightBand }) {
+  const s = toonSceneLights;
+
+  const evaluateLocalLightFill = (normal, geometryPosition, localLightIntensity, localLightMaxContribution) => {
+    const localLight = vec3(0.0).toVar();
+
+    for (let i = 0; i < MAX_TOON_POINT_LIGHTS; i += 1) {
+      If(float(i).lessThan(s.pointLightCount), () => {
+        const lVector = s.pointLightPositions.element(i).sub(geometryPosition);
+        const lightDistance = lVector.length();
+        const direction = lVector.div(max(lightDistance, 1e-6));
+        const params = s.pointLightParams.element(i);
+        const attenuation = distanceAttenuation(lightDistance, params.x, params.y);
+        const color = s.pointLightColors.element(i).mul(attenuation).toVar();
+        If(maxComponent3(color).greaterThan(0.0), () => {
+          const band = localLightBand(normal, direction);
+          localLight.addAssign(color.mul(band));
+        });
+      });
+    }
+
+    for (let i = 0; i < MAX_TOON_SPOT_LIGHTS; i += 1) {
+      If(float(i).lessThan(s.spotLightCount), () => {
+        const lVector = s.spotLightPositions.element(i).sub(geometryPosition);
+        const lightDistance = lVector.length();
+        const direction = lVector.div(max(lightDistance, 1e-6));
+        const params = s.spotLightParams.element(i);
+        const angleCos = dot(direction, normalize(s.spotLightDirections.element(i)));
+        const spotAttenuation = smoothstep(params.z, params.w, angleCos);
+        const attenuation = distanceAttenuation(lightDistance, params.x, params.y)
+          .mul(spotAttenuation);
+        const color = s.spotLightColors.element(i).mul(attenuation).toVar();
+        If(maxComponent3(color).greaterThan(0.0), () => {
+          const band = localLightBand(normal, direction);
+          localLight.addAssign(color.mul(band));
+        });
+      });
+    }
+
+    const limited = min3(localLight.mul(localLightIntensity), vec3(localLightMaxContribution)).toVar();
+    const strongestLocalLight = maxComponent3(limited);
+    return { localLight: limited, strongestLocalLight };
+  };
+
+  const evaluateHemisphereFill = (normal, hemisphereLightIntensity) => {
+    const hemisphereFill = vec3(0.0).toVar();
+    for (let i = 0; i < MAX_TOON_HEMI_LIGHTS; i += 1) {
+      If(float(i).lessThan(s.hemiLightCount), () => {
+        const dotNL = dot(normal, normalize(s.hemiLightDirections.element(i)));
+        const hemiDiffuseWeight = dotNL.mul(0.5).add(0.5);
+        hemisphereFill.addAssign(
+          mix(s.hemiLightGroundColors.element(i), s.hemiLightSkyColors.element(i), hemiDiffuseWeight),
+        );
+      });
+    }
+    return hemisphereFill.mul(hemisphereLightIntensity);
+  };
+
+  return { evaluateHemisphereFill, evaluateLocalLightFill };
+}
+
+function maxComponent3(value) {
+  return max(value.r, max(value.g, value.b));
+}

package/src/shaders-tsl/chunks/character-shadow-color.js

@@ -0,0 +1,61 @@
+// TSL port of src/shaders/chunks/character-fragment-shadow-color.glsl —
+// the tinted/HSV-shifted albedo used inside shadow areas.
+
+import { abs, clamp, max, mix, vec3 } from 'three/tsl';
+
+import { adjustSaturation, applyHSVChange, rgbToHsv } from './character-color.js';
+
+export function createShadowColorChunk({ u }) {
+  const calculateShadowColor = (albedo, finalShadowArea) => {
+    const transitionArea = clamp(
+      abs(finalShadowArea.sub(0.5)).mul(2.0).oneMinus().mul(u.litToShadowTransitionAreaIntensity),
+      0.0,
+      1.0,
+    );
+    const hueOffset = u.selfShadowAreaHueOffset.mul(u.selfShadowAreaHSVStrength)
+      .add(u.litToShadowTransitionAreaHueOffset.mul(transitionArea));
+    const saturationBoost = u.selfShadowAreaSaturationBoost.mul(u.selfShadowAreaHSVStrength)
+      .add(u.litToShadowTransitionAreaSaturationBoost.mul(transitionArea));
+    const valueMul = mix(1.0, u.selfShadowAreaValueMul, u.selfShadowAreaHSVStrength)
+      .mul(mix(1.0, u.litToShadowTransitionAreaValueMul, transitionArea));
+
+    const originalHSV = rgbToHsv(max(albedo, vec3(0.0)));
+    const result = applyHSVChange(albedo, hueOffset, saturationBoost, valueMul).toVar();
+
+    const fallbackColor = albedo.mul(u.lowSaturationFallbackColor.rgb);
+    const fallbackMask = mix(1.0, clamp(originalHSV.y.mul(5.0), 0.0, 1.0), u.lowSaturationFallbackColor.a);
+    result.assign(mix(fallbackColor, result, fallbackMask));
+
+    result.mulAssign(u.selfShadowTintColor);
+    result.mulAssign(mix(vec3(1.0), u.litToShadowTransitionAreaTintColor, transitionArea));
+
+    // Skin/face overrides (uniform-mixed like the GLSL branches — isSkin and
+    // isFace are per-material constants carried as uniforms).
+    const skinShadow = adjustSaturation(
+      albedo.mul(u.skinShadowTintColor).mul(u.skinShadowTintColor2).mul(u.skinShadowBrightness),
+      u.skinShadowSaturation,
+    );
+    result.assign(mix(
+      result,
+      mix(result, skinShadow, u.overrideBySkinShadowTintColor),
+      u.isSkin.select(1.0, 0.0),
+    ));
+
+    const faceShadow = adjustSaturation(
+      albedo.mul(u.faceShadowTintColor).mul(u.faceShadowTintColor2).mul(u.faceShadowBrightness),
+      u.faceShadowSaturation,
+    );
+    result.assign(mix(
+      result,
+      mix(result, faceShadow, u.overrideByFaceShadowTintColor),
+      u.isFace.select(1.0, 0.0),
+    ));
+
+    result.assign(mix(result, result.mul(albedo), u.selfShadowAlbedoMulStrength));
+
+    // enableShadowColor=false → plain albedo (GLSL early return).
+    return mix(albedo, result, u.enableShadowColor.select(1.0, 0.0));
+  };
+
+  return { calculateShadowColor };
+}

package/src/shaders-tsl/chunks/character-skinning.js

@@ -0,0 +1,140 @@
+// Storage-buffer skinning for the toon character on the forced-WebGL2
+// backend.
+//
+// three r185's built-in SkinningNode stores bone matrices in a uniform
+// buffer; GL_MAX_UNIFORM_BLOCK_SIZE (16KB ≈ 256 bones) makes every MMD-scale
+// skeleton (300-800 bones) fail to link on the WebGL2 backend. This chunk
+// stores the same skeleton.boneMatrices array as a storage attribute with
+// setPBO(true): the GLSL builder emits it as a float DataTexture + texelFetch
+// (the classic boneTexture technique), while WebGPU would emit a real storage
+// buffer. The math replicates three's getSkinnedPosition/NormalAndTangent.
+//
+// ToonAnimeNodeMaterial.setupPosition routes skinned meshes here on the
+// WebGL2 backend only; WebGPU keeps the built-in path.
+
+import * as THREE from 'three';
+import {
+  attribute,
+  mat4,
+  morphReference,
+  normalLocal,
+  positionLocal,
+  storage,
+  uniform,
+  vec4,
+} from 'three/tsl';
+
+// One storage attribute per skeleton, shared by every material/mesh using it.
+const boneStorageBySkeleton = new WeakMap();
+
+function boneStorageEntry(skeleton) {
+  let entry = boneStorageBySkeleton.get(skeleton);
+  if (!entry) {
+    // Make sure the matrices reflect the current pose before the first
+    // texture upload (nothing else updates the skeleton on this path).
+    skeleton.update();
+    // Bone matrices as bones×4 vec4 columns (column-major float array).
+    const attributeBuffer = new THREE.InstancedBufferAttribute(skeleton.boneMatrices, 4);
+    const node = storage(attributeBuffer, 'vec4', skeleton.bones.length * 4)
+      .setPBO(true)
+      .toReadOnly();
+    entry = { attributeBuffer, node };
+    boneStorageBySkeleton.set(skeleton, entry);
+  }
+  return entry;
+}
+
+/**
+ * Applies storage-buffer skinning to positionLocal/normalLocal in place.
+ * Call inside setupPosition (an active stack is required).
+ */
+export function applyToonStorageSkinning(skinnedMesh) {
+  const skeleton = skinnedMesh.skeleton;
+  const bones = boneStorageEntry(skeleton).node;
+
+  const bindMatrix = uniform(skinnedMesh.bindMatrix, 'mat4');
+  const bindMatrixInverse = uniform(skinnedMesh.bindMatrixInverse, 'mat4');
+  const skinIndex = attribute('skinIndex', 'uvec4');
+  const skinWeight = attribute('skinWeight', 'vec4');
+
+  const boneMatrix = (index) => {
+    const base = index.mul(4);
+    return mat4(
+      bones.element(base),
+      bones.element(base.add(1)),
+      bones.element(base.add(2)),
+      bones.element(base.add(3)),
+    );
+  };
+
+  const boneMatX = boneMatrix(skinIndex.x);
+  const boneMatY = boneMatrix(skinIndex.y);
+  const boneMatZ = boneMatrix(skinIndex.z);
+  const boneMatW = boneMatrix(skinIndex.w);
+
+  // Position (three's getSkinnedPosition).
+  const skinVertex = bindMatrix.mul(vec4(positionLocal, 1.0));
+  const skinned = boneMatX.mul(skinVertex).mul(skinWeight.x)
+    .add(boneMatY.mul(skinVertex).mul(skinWeight.y))
+    .add(boneMatZ.mul(skinVertex).mul(skinWeight.z))
+    .add(boneMatW.mul(skinVertex).mul(skinWeight.w));
+  const skinPosition = bindMatrixInverse.mul(skinned).xyz;
+
+  // Normal (three's getSkinnedNormalAndTangent, tangent omitted — the toon
+  // shader derives its TBN from screen derivatives).
+  let skinMatrix = boneMatX.mul(skinWeight.x)
+    .add(boneMatY.mul(skinWeight.y))
+    .add(boneMatZ.mul(skinWeight.z))
+    .add(boneMatW.mul(skinWeight.w));
+  skinMatrix = bindMatrixInverse.mul(skinMatrix).mul(bindMatrix);
+  const skinNormal = skinMatrix.mul(vec4(normalLocal, 0.0)).xyz;
+
+  positionLocal.assign(skinPosition);
+  normalLocal.assign(skinNormal);
+}
+
+/**
+ * Subclasses a node material so skinned meshes skin through the storage/PBO
+ * path on non-WebGPU backends (built-in buffer skinning elsewhere). Used by
+ * the anime material and by the character-pass depth/mask materials, which
+ * render the same MMD-scale skeletons.
+ */
+export function withToonStorageSkinning(BaseNodeMaterial) {
+  return class extends BaseNodeMaterial {
+    setupPosition(builder) {
+      const { object, geometry } = builder;
+      const useStorageSkinning = object.isSkinnedMesh === true &&
+        builder.renderer?.backend?.isWebGPUBackend !== true;
+      if (!useStorageSkinning) return super.setupPosition(builder);
+
+      // Mirrors NodeMaterial.setupPosition for the paths a skinned character
+      // can hit (morphs, then skinning); batching/instancing/displacement do
+      // not apply to skinned toon meshes.
+      if (geometry.morphAttributes.position || geometry.morphAttributes.normal || geometry.morphAttributes.color) {
+        morphReference(object);
+      }
+      applyToonStorageSkinning(object);
+      return positionLocal;
+    }
+  };
+}
+
+/**
+ * Per-frame CPU side: recompute bone matrices and re-upload the PBO texture.
+ * Runs from the converted meshes' onBeforeRender (idempotent per frame).
+ */
+export function updateToonStorageSkinning(skinnedMesh) {
+  const skeleton = skinnedMesh?.skeleton;
+  if (!skeleton) return;
+  const entry = boneStorageBySkeleton.get(skeleton);
+  if (!entry) return;
+  skeleton.update();
+  const attributeBuffer = entry.attributeBuffer;
+  // The GLSL builder's PBO setup REPLACES the attribute array with a padded
+  // copy (pow2 texture dimensions) — mirror the live bone matrices into it
+  // before flagging the wrapping DataTexture (attribute.pbo) for re-upload.
+  if (attributeBuffer.array !== skeleton.boneMatrices) {
+    attributeBuffer.array.set(skeleton.boneMatrices, 0);
+  }
+  if (attributeBuffer.pbo) attributeBuffer.pbo.needsUpdate = true;
+}

package/src/shaders-tsl/chunks/environment-color.js

@@ -0,0 +1,47 @@
+// TSL port of src/shaders/chunks/environment-fragment-color.glsl — color
+// helpers for the environment shader: Rec.709 luma, saturation remap, and the
+// blue/cyan window-pane detector used by the open-windows cutout.
+//
+// Leaf node→node helpers, exported as Fn() per docs/tsl-conventions.md.
+
+import {
+  dot,
+  Fn,
+  max,
+  min,
+  mix,
+  smoothstep,
+  vec3,
+} from 'three/tsl';
+
+/** GLSL envLuma(color): Rec.709 luminance. */
+export const envLuma = /*@__PURE__*/ Fn(([color]) => {
+  return dot(color, vec3(0.2126, 0.7152, 0.0722));
+});
+
+/** GLSL applySaturation(color, amount): lerp from grayscale luma. */
+export const applySaturation = /*@__PURE__*/ Fn(([color, amount]) => {
+  const luma = dot(color, vec3(0.2126, 0.7152, 0.0722));
+  return mix(vec3(luma), color, amount);
+});
+
+/**
+ * GLSL windowPaneMask(color): 1 where the texel reads as a blue/cyan glass
+ * pane, guarded against bright cloth/paper. Same smoothstep windows.
+ */
+export const windowPaneMask = /*@__PURE__*/ Fn(([color]) => {
+  const maxChannel = max(color.r, max(color.g, color.b));
+  const minChannel = min(color.r, min(color.g, color.b));
+  const colorSpread = maxChannel.sub(minChannel);
+  const bluePane = smoothstep(0.03, 0.16, color.b.sub(color.r))
+    .mul(smoothstep(0.00, 0.10, color.g.sub(color.r)))
+    .mul(smoothstep(0.24, 0.54, color.b))
+    .mul(smoothstep(0.03, 0.22, colorSpread));
+  const cyanPane = smoothstep(0.02, 0.14, color.g.sub(color.r))
+    .mul(smoothstep(0.02, 0.14, color.b.sub(color.r)))
+    .mul(smoothstep(0.24, 0.52, max(color.g, color.b)))
+    .mul(smoothstep(0.02, 0.18, colorSpread));
+  const clothOrPaperGuard = smoothstep(1.48, 2.15, color.r.add(color.g).add(color.b)).oneMinus();
+
+  return max(bluePane, cyanPane).mul(clothOrPaperGuard);
+});

package/src/shaders-tsl/chunks/environment-debug.js

@@ -0,0 +1,79 @@
+// TSL port of src/shaders/chunks/environment-fragment-debug.glsl —
+// environment debug views. Mode ids must match ENVIRONMENT_DEBUG_MODES in
+// environmentSettings.js.
+//
+// On the node backends the debug table is always compiled in (it adds zero
+// bindings — every input is already in the graph), so the GLSL
+// ENV_DEBUG_VIEWS define flip becomes a pure write of the shared envDebugMode
+// uniform (docs/tsl-conventions.md, debug-views precedent). The GLSL if-chain
+// becomes a masked arithmetic sum: deep nested select() chains trip the GLSL
+// builder's detached type-resolution fallback, and the fragment root must not
+// be a ConditionalNode.
+
+import {
+  float,
+  floor,
+  select,
+  vec3,
+  vec4,
+} from 'three/tsl';
+
+/**
+ * environmentDebugColor(...) — returns finalColor when mode matches no table
+ * entry (including mode 0 / off), else the selected debug view.
+ */
+export function environmentDebugColor({
+  mode,
+  albedo,
+  litColor,
+  ambient,
+  directLight,
+  pointLight,
+  spotLight,
+  sunlightVisibility,
+  aoMul,
+  bakedGi,
+  normal,
+  vertexAo,
+  specular,
+  emissiveMask,
+  windowMask,
+  roomOcclusion,
+  alpha,
+  finalColor,
+}) {
+  const m = floor(mode.add(0.5)); // GLSL: int m = int(mode + 0.5)
+
+  const entries = [
+    [1, vec4(albedo, 1.0)],
+    [2, vec4(litColor, 1.0)],
+    [3, vec4(ambient, 1.0)],
+    [4, vec4(directLight, 1.0)],
+    [5, vec4(vec3(sunlightVisibility), 1.0)],
+    [6, vec4(pointLight, 1.0)],
+    [7, vec4(spotLight, 1.0)],
+    [8, vec4(aoMul, 1.0)],
+    [9, vec4(bakedGi, 1.0)],
+    [10, vec4(normal.mul(0.5).add(0.5), 1.0)],
+    [11, vec4(vec3(vertexAo), 1.0)],
+    [12, vec4(specular, 1.0)],
+    [13, vec4(vec3(emissiveMask), 1.0)],
+    [14, vec4(vec3(windowMask), 1.0)],
+    [15, vec4(vec3(roomOcclusion.oneMinus()), 1.0)],
+    [16, vec4(vec3(alpha), 1.0)],
+  ];
+
+  // 1 when the mode matches any table entry, else 0 — keeps the finalColor
+  // fallback for off/unknown modes without a conditional chain.
+  let knownMask = float(0.0);
+  for (const [id] of entries) {
+    knownMask = knownMask.add(select(m.equal(float(id)), float(1.0), float(0.0)));
+  }
+  knownMask = knownMask.min(1.0);
+
+  let result = vec4(finalColor).mul(knownMask.oneMinus());
+  for (const [id, value] of entries) {
+    result = result.add(vec4(value).mul(select(m.equal(float(id)), float(1.0), float(0.0))));
+  }
+  return result;
+}