@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/src/environment/toonLabSurfaceLighting.js

@@ -118,6 +118,8 @@ export const TOONLAB_SURFACE_LIGHTING_CONTRACT = Object.freeze({
   directDiffuse: 'radiance * BRDFData.diffuse (no 1/PI)',
   indirectDiffuse: 'bakedGI * BRDFData.diffuse (no 1/PI)',
   directSpecular: 'TOONLAB DirectBRDFSpecular optimized GGX',
+  shadowFill:
+    'authored fraction of the sun retained where the package sun-shadow pass reports occlusion (0 = TOONLAB literal)',
   defaultInputAdapter: DEFAULT_INPUT_ADAPTER.id,
   inputNormalization:
     'direct radiance and cosine-convolved indirect irradiance are normalized independently',
@@ -149,6 +151,7 @@ const frozenColor = (value) => Object.freeze([...value]);
 /** CPU oracle for the diffuse-only direct/indirect input decomposition. */
 export function evaluateToonLabSurfaceDiffuseDecomposition({
   brdfDiffuse = [1, 1, 1],
+  directStrength = 1,
   directInput = [0, 0, 0],
   indirectInput = [0, 0, 0],
   inputAdapter = DEFAULT_INPUT_ADAPTER.id,
@@ -161,8 +164,9 @@ export function evaluateToonLabSurfaceDiffuseDecomposition({
   const sourceCosine = Number(nDotL);
   if (!Number.isFinite(sourceCosine)) throw new TypeError('nDotL must be finite.');
   const cosine = Math.min(1, Math.max(0, sourceCosine));
+  const resolvedDirectStrength = Math.max(Number(directStrength) || 0, 0);
   const directRadiance = direct.map(
-    (channel) => channel * adapter.directNormalization * cosine,
+    (channel) => channel * adapter.directNormalization * resolvedDirectStrength * cosine,
   );
   const indirectBakedGi = indirect.map(
     (channel) => channel * adapter.indirectNormalization,
@@ -224,21 +228,46 @@ function toonLabBrdfInputs(workflow, specularF0Node, diffuseAlphaNode = float(1)
 export class ToonLabSurfaceLightingModel extends PhysicalLightingModel {
   constructor({
     diffuseAlphaNode = float(1),
+    directStrength = 1,
     indirectStrength = 1,
     indirectTint = [1, 1, 1],
+    indirectTintNode = null,
+    indirectReplaceTintNode = null,
+    indirectTintBlendNode = null,
+    indirectTintMode = 'multiply',
     inputAdapter = DEFAULT_INPUT_ADAPTER.id,
     perceptualRoughnessNode = materialRoughness,
+    shadowFill = 0,
+    shadowFillTint = [1, 1, 1],
+    useSharedSunShadow = true,
     specularF0Node = materialSpecularColor,
     workflow = 'metallic',
   } = {}) {
     super(false, false, false, false, false, false);
     this.diffuseAlphaNode = diffuseAlphaNode;
+    this.directStrength = float(Math.max(Number(directStrength) || 0, 0));
     this.indirectStrength = float(Math.max(Number(indirectStrength) || 0, 0));
-    this.indirectTint = vec3(...indirectTint);
+    // A static tint is sufficient for authored indoor materials, but outdoor
+    // surfaces need the active sky colour to remain live as time-of-day and
+    // weather change. Accepting a node here lets callers bind that scene state
+    // without rebuilding the material or baking a permanent daylight-blue cast.
+    this.indirectTint = indirectTintNode
+      ? vec3(indirectTintNode)
+      : vec3(...indirectTint);
+    this.indirectReplaceTint = indirectReplaceTintNode
+      ? vec3(indirectReplaceTintNode)
+      : this.indirectTint;
+    this.indirectTintBlend = indirectTintBlendNode ?? float(0);
+    this.indirectTintMode = ['replace-chroma', 'sky-adaptive'].includes(indirectTintMode)
+      ? indirectTintMode
+      : 'multiply';
     this.inputAdapter = resolveToonLabSurfaceInputAdapter(inputAdapter);
     this.perceptualRoughnessNode = perceptualRoughnessNode;
-    this.specularF0Node = specularF0Node;
+    this.shadowFill = Math.min(Math.max(Number(shadowFill) || 0, 0), 1);
+    this.shadowFillTint = shadowFillTint;
+    this.useSharedSunShadow = useSharedSunShadow !== false;
     this.workflow = workflow === 'specular' ? 'specular' : 'metallic';
+    this.specularF0Node = specularF0Node;
   }
 
   direct({ lightDirection, lightColor, lightNode, reflectedLight }) {
@@ -248,12 +277,33 @@ export class ToonLabSurfaceLightingModel extends PhysicalLightingModel {
     // TOONLAB's no-PI BRDF convention.
     // Three can carry analytic light attenuation as RGBA for transmitted
     // coloured shadows. TOONLAB's Light.color is RGB, so consume RGB explicitly.
-    const sharedSunVisibility = lightNode?.light?.shadow?.toonLabLightingContract
+    // The package sun-shadow sample is a hard 0/1 mask. Applied raw it removes
+    // the ENTIRE direct term on an occluded fragment, and a Call Me Sensei rig
+    // has no ambient light behind it — only the SH sky probe, whose measured
+    // radiance is R:G:B ~ 1 : 2.2 : 5.3. A fully occluded ToonLab surface
+    // therefore renders as saturated navy with no value structure at all
+    // (D19-062). `shadowFill` keeps an authored, tintable fraction of the sun
+    // in shadow, which is the shadow-lift the environment node material has
+    // always had and this bridge did not. Default 0 — an existing caller
+    // resolves to exactly the previous expression.
+    const hasToonLabSunContract = Boolean(
+      lightNode?.light?.shadow?.toonLabLightingContract,
+    );
+    const sunVisibility = hasToonLabSunContract && this.useSharedSunShadow
       ? sampleEnvironmentSunShadow(positionWorld)
-        .mul(sampleEnvironmentCloudShadow(positionWorld, 1))
       : float(1);
+    // Cloud transmittance remains shared even when a material relies on the
+    // native directional shadow. This avoids double/self-shadowing while every
+    // outdoor surface still sees the same moving cloud field.
+    const rawSunVisibility = hasToonLabSunContract
+      ? sunVisibility.mul(sampleEnvironmentCloudShadow(positionWorld, 1))
+      : float(1);
+    const sharedSunVisibility = this.shadowFill > 0
+      ? mix(float(this.shadowFill).mul(vec3(...this.shadowFillTint)), vec3(1), rawSunVisibility)
+      : rawSunVisibility;
     const toonLabLightColor = vec3(lightColor)
       .mul(this.inputAdapter.directNormalization)
+      .mul(this.directStrength)
       .mul(sharedSunVisibility);
     const nDotL = clamp(dot(normalView, lightDirection), 0, 1);
     // Materialize the shadowed light once. CSM attenuation contains mutable
@@ -307,12 +357,24 @@ export class ToonLabSurfaceLightingModel extends PhysicalLightingModel {
       this.specularF0Node,
       this.diffuseAlphaNode,
     );
+    const adaptedIrradiance = irradiance
+      .mul(this.inputAdapter.indirectNormalization)
+      .mul(this.indirectStrength);
+    // Outdoor probes already contain colour. Multiplying a cool sunset probe
+    // by an orange horizon collapses both toward dark purple. Rocks instead
+    // retain the probe's directional luminance and receive chroma from the live
+    // visible sky, which is the scene state the player actually sees.
+    const multipliedIrradiance = adaptedIrradiance.mul(this.indirectTint);
+    const replacedIrradiance = vec3(
+      dot(adaptedIrradiance, vec3(0.2126, 0.7152, 0.0722)),
+    ).mul(this.indirectReplaceTint);
+    const tintedIrradiance = this.indirectTintMode === 'replace-chroma'
+      ? replacedIrradiance
+      : this.indirectTintMode === 'sky-adaptive'
+        ? mix(multipliedIrradiance, replacedIrradiance, this.indirectTintBlend)
+        : multipliedIrradiance;
     reflectedLight.indirectDiffuse.addAssign(
-      irradiance
-        .mul(this.inputAdapter.indirectNormalization)
-        .mul(this.indirectStrength)
-        .mul(this.indirectTint)
-        .mul(brdf.diffuse),
+      tintedIrradiance.mul(brdf.diffuse),
     );
   }
 
@@ -334,6 +396,9 @@ export function installToonLabSurfaceLighting(material, options = {}) {
   const workflow = options.workflow ?? prior?.workflow ?? 'metallic';
   const resolvedWorkflow = workflow === 'specular' ? 'specular' : 'metallic';
   const diffuseAlphaNode = options.diffuseAlphaNode ?? float(1);
+  const directStrength = Math.max(Number(
+    options.directStrength ?? prior?.directStrength ?? 1,
+  ) || 0, 0);
   const indirectStrength = Math.max(Number(
     options.indirectStrength ?? prior?.indirectStrength ?? 1,
   ) || 0, 0);
@@ -341,12 +406,37 @@ export function installToonLabSurfaceLighting(material, options = {}) {
     options.indirectTint ?? prior?.indirectTint ?? [1, 1, 1],
     'indirectTint',
   );
+  const indirectTintNode = options.indirectTintNode ?? null;
+  const indirectReplaceTintNode = options.indirectReplaceTintNode ?? null;
+  const indirectTintBlendNode = options.indirectTintBlendNode ?? null;
+  const requestedIndirectTintMode = options.indirectTintMode ?? prior?.indirectTintMode;
+  const indirectTintMode = ['replace-chroma', 'sky-adaptive'].includes(requestedIndirectTintMode)
+    ? requestedIndirectTintMode
+    : 'multiply';
+  const shadowFill = Math.min(Math.max(Number(
+    options.shadowFill ?? prior?.shadowFill ?? 0,
+  ) || 0, 0), 1);
+  const shadowFillTint = finiteColor(
+    options.shadowFillTint ?? prior?.shadowFillTint ?? [1, 1, 1],
+    'shadowFillTint',
+  );
+  const useSharedSunShadow = options.useSharedSunShadow
+    ?? prior?.useSharedSunShadow
+    ?? true;
   material.setupLightingModel = () => new ToonLabSurfaceLightingModel({
     diffuseAlphaNode,
+    directStrength,
     indirectStrength,
     indirectTint,
+    indirectTintNode,
+    indirectReplaceTintNode,
+    indirectTintBlendNode,
+    indirectTintMode,
     inputAdapter,
     perceptualRoughnessNode: material.roughnessNode ?? materialRoughness,
+    shadowFill,
+    shadowFillTint,
+    useSharedSunShadow,
     specularF0Node: material.specularColorNode ?? materialSpecularColor,
     workflow: resolvedWorkflow,
   });
@@ -354,9 +444,17 @@ export function installToonLabSurfaceLighting(material, options = {}) {
     ...TOONLAB_SURFACE_LIGHTING_CONTRACT,
     inputAdapter: inputAdapter.id,
     inputAdapterContract: { ...inputAdapter },
+    directStrength,
     indirectStrength,
     indirectTint: [...indirectTint],
+    indirectTintSource: indirectTintNode ? 'dynamic-node' : 'static',
+    indirectReplaceTintSource: indirectReplaceTintNode ? 'dynamic-node' : 'shared',
+    indirectTintBlendSource: indirectTintBlendNode ? 'dynamic-node' : 'static-zero',
+    indirectTintMode,
     preserveSpecularAlpha: options.diffuseAlphaNode != null,
+    shadowFill,
+    shadowFillTint: [...shadowFillTint],
+    useSharedSunShadow: useSharedSunShadow !== false,
     workflow: resolvedWorkflow,
   };
   material.needsUpdate = true;

package/src/environment/urbanPropMaterial.js

@@ -203,6 +203,27 @@ function surfaceProfile(base, overrides) {
 
 const SURFACE_PROFILES = Object.freeze({
   ...LEGACY_SURFACE_PROFILES,
+  // `bareMetal` is the weathered-scrap look: it discards the source albedo's
+  // hue AND value (both authority scales 0) and paints the surface from
+  // `bareMetalColor`, then piles on rust. That is right for an untextured or
+  // scanned prop, and wrong for an authored brushed-stainless map — the
+  // anisotropy an artist baked into the albedo simply never reached the frame,
+  // so `metal`/`brushed` rendered as one flat panel. `brushed` is its own
+  // finish in the contract and now gets its own profile: the metal response
+  // (role hue, fresnel, planar sheen, low light cap) is kept, the authored
+  // VALUE structure is honoured, and the scrapyard wear is dialled out.
+  // `raw`/`polished`/`anodized`/`mirror` still resolve to `bareMetal`.
+  brushedMetal: surfaceProfile(LEGACY_SURFACE_PROFILES.bareMetal, {
+    highlightScale: 0.16,
+    lightValueCap: 0.46,
+    normalScale: 0.9,
+    planarSheenScale: 0.5,
+    responseValueCap: 0.78,
+    sharpRustBoost: 0.5,
+    sourceHueAuthorityScale: 0,
+    sourceValueAuthorityScale: 1,
+    wearScale: 0.45,
+  }),
   coatedPanel: LEGACY_SURFACE_PROFILES.lid,
   genericDielectric: surfaceProfile(LEGACY_SURFACE_PROFILES.paintedMetal, {
     colorLiftScale: 0.42,
@@ -345,6 +366,33 @@ const SURFACE_PROFILES = Object.freeze({
     planarSheenScale: 0,
     viewReflectionScale: 0.01,
   }),
+  // A diffusing sheet — shoji paper, a paper lantern, a fabric shade — lit
+  // from the far side. `MANUFACTURED_RENDER_MODES` has carried `translucent`
+  // and `transmissive` since v1 and the manifest validates them, but nothing
+  // downstream did anything with them: a paper screen converted to the same
+  // opaque toon surface as a poster, and the single read that makes a teahouse
+  // look like a teahouse — warm interior light through paper, with the lattice
+  // dark against it — was not expressible. See D19-079.
+  //
+  // The response is deliberately NOT physical transmission. A diffuser is not
+  // a window: you do not see through it, you see it lit. So the term is a
+  // view-independent glow, tinted by `translucencyColor`, modulated by the
+  // paper's own albedo (a stain or a fibre inclusion must read darker when
+  // backlit, which is exactly what makes washi look like washi), softened
+  // toward grazing angles, and NOT gated by the sun shadow, because the light
+  // behind the screen is not the sun.
+  paperTranslucent: surfaceProfile(LEGACY_SURFACE_PROFILES.graphicPanel, {
+    fallbackMetalness: 0,
+    fresnelScale: 0.04,
+    highlightScale: 0.02,
+    lightValueCap: 1.16,
+    materialResponseScale: 0.08,
+    normalScale: 0.3,
+    planarSheenScale: 0,
+    translucencyScale: 1,
+    viewReflectionScale: 0.01,
+    wearScale: 0.04,
+  }),
   composite: surfaceProfile(LEGACY_SURFACE_PROFILES.technicalSurface, {
     fallbackMetalness: 0.08,
     fresnelScale: 0.58,
@@ -737,6 +785,11 @@ export function createUrbanPropShaderControls(palette = 'source') {
     sourceAuthorityEnabled: numberControl(1),
     sourceAuthorityStrength: numberControl(1),
     trimColor: colorControl(selected.trimColor),
+    // Diffusing-sheet response (shoji, paper lantern, fabric shade). Only
+    // profiles that declare `translucencyScale` read these.
+    translucencyColor: colorControl(0xffd7a0),
+    translucencyEnabled: numberControl(1),
+    translucencyStrength: numberControl(0.85),
     viewReflectionEnabled: numberControl(1),
     viewReflectionStrength: numberControl(0.62),
     wearEnabled: numberControl(1),
@@ -1042,7 +1095,10 @@ export function resolveUrbanMaterialProfile(classification) {
   }
   switch (classification?.baseMaterial) {
     case 'metal':
-      if (['raw', 'polished', 'brushed', 'anodized', 'mirror'].includes(
+      // Brushed is the one bare-metal finish that normally arrives with an
+      // authored anisotropic map; it keeps that map's value structure.
+      if (classification.finish === 'brushed') return 'brushedMetal';
+      if (['raw', 'polished', 'anodized', 'mirror'].includes(
         classification.finish,
       )) {
         return 'bareMetal';
@@ -1069,7 +1125,12 @@ export function resolveUrbanMaterialProfile(classification) {
     case 'leather':
       return 'leather';
     case 'paper':
-      return 'paper';
+      // A backlit diffusing sheet is a different surface from a poster, and
+      // renderMode is where the contract already says so.
+      return classification.renderMode === 'translucent'
+        || classification.renderMode === 'transmissive'
+        ? 'paperTranslucent'
+        : 'paper';
     case 'composite':
       return 'composite';
     case 'fluid':
@@ -2602,6 +2663,24 @@ export function createUrbanAnimePropMaterial(sourceMaterial, {
     emissive: 0x020508,
     gradientMap: createLockedGradientMap(),
   });
+  // WebGL counterpart of the WebGPU diffusing-sheet term. Without a node graph
+  // the view easing is not available, so this is the flat form: the sheet's own
+  // colour tinted by translucencyColor, added as emission.
+  const translucencyScale = Number(profile.translucencyScale ?? 0);
+  const applyTranslucency = () => {
+    if (!(translucencyScale > 0)) return;
+    const amount = THREE.MathUtils.clamp(
+      Number(shared.translucencyEnabled?.value ?? 0)
+        * Number(shared.translucencyStrength?.value ?? 0)
+        * translucencyScale,
+      0,
+      2,
+    );
+    material.emissive
+      .copy(shared.translucencyColor?.value ?? new THREE.Color(0xffd7a0))
+      .multiply(material.color)
+      .multiplyScalar(amount);
+  };
   material.name = `Locked urban · ${profileId} · ${source?.name ?? 'material'}`;
   material.map = source?.map ?? null;
   material.normalMap = source?.normalMap ?? null;
@@ -2637,6 +2716,7 @@ export function createUrbanAnimePropMaterial(sourceMaterial, {
     material.gradientMap = shared.celLightingEnabled.value > 0.5
       ? createLockedGradientMap()
       : createSmoothGradientMap();
+    applyTranslucency();
   };
   syncLookControls();
   material.onBeforeRender = syncLookControls;
@@ -2810,6 +2890,27 @@ export function createUrbanAnimePropNodeMaterial(sourceMaterial, {
     castShadowAmount.mul(0.72),
   );
 
+  // Diffusing-sheet response. A backlit paper screen is not a window: the read
+  // is the sheet GLOWING, not the room behind it, so this is a view-independent
+  // lift rather than a transmission sample. It is modulated by the sheet's own
+  // albedo so a fibre inclusion or a stain darkens when backlit — the thing
+  // that makes washi read as washi — and eased off toward grazing angles,
+  // where a real sheet presents more thickness and goes opaque. It is NOT
+  // multiplied by `sceneShadow`, because the light behind a shoji is the
+  // interior, not the sun, and a screen that stopped glowing when a cloud
+  // crossed would be exactly wrong.
+  const translucencyScale = Number(profile.translucencyScale ?? 0);
+  const translucency = translucencyScale > 0
+    ? colorControlNode(shared.translucencyColor, 0xffd7a0)
+      .mul(urbanColor)
+      .mul(
+        scalarControl(shared.translucencyEnabled)
+          .mul(scalarControl(shared.translucencyStrength))
+          .mul(translucencyScale)
+          .mul(mix(0.35, 1, facing)),
+      )
+    : null;
+
   const material = new MeshToonNodeMaterial();
   material.name = `Locked urban WebGPU · ${profileId} · ${
     source?.name ?? 'material'
@@ -2819,6 +2920,7 @@ export function createUrbanAnimePropNodeMaterial(sourceMaterial, {
   // Authored emission remains visible in shade; view-dependent manufactured
   // highlights are direct-light cues and must disappear with the sun.
   material.emissiveNode = sourceEmissionNode.add(stylizedResponse.mul(sceneShadow));
+  if (translucency) material.emissiveNode = material.emissiveNode.add(translucency);
   material.normalNode = sourceNormalNode;
   material.gradientMap = createLockedGradientMap();
   material.side = source?.side ?? THREE.FrontSide;

package/src/lighting/lightingSystem.js

@@ -224,6 +224,7 @@ export function createLightingSystem({
   let hour = clamp(finite(timeOfDay, 12), 0, 24);
   let frame = sampleLightingStyle(styleSettings, hour);
   let modulation = { ...DEFAULT_MODULATION };
+  let sunDirectionOverride = null;
   let clock = 0;
   let placementCounter = 0;
   let disposed = false;
@@ -382,6 +383,15 @@ export function createLightingSystem({
   const shadowFocusForward = new THREE.Vector3();
   const shadowFocusTarget = new THREE.Vector3();
 
+  function effectiveSunSourceRatios() {
+    if (!sunDirectionOverride) return frame.sunSourceRatios;
+    return {
+      x: sunDirectionOverride[0],
+      y: sunDirectionOverride[1],
+      z: sunDirectionOverride[2],
+    };
+  }
+
   function updateOwnSunShadowFocus(nextCamera) {
     const sun = attachment.ownSun;
     const contract = CALL_ME_SENSEI_LIGHTING_CONTRACT.sun.shadow;
@@ -395,11 +405,8 @@ export function createLightingSystem({
     // The style runtime cannot infer terrain height. Preserve the host/world
     // target plane while following the camera horizontally.
     shadowFocusTarget.y = sun.target.position.y;
-    shadowFocusDirection.set(
-      frame.sunSourceRatios.x,
-      frame.sunSourceRatios.y,
-      frame.sunSourceRatios.z,
-    ).normalize();
+    const sourceRatios = effectiveSunSourceRatios();
+    shadowFocusDirection.set(sourceRatios.x, sourceRatios.y, sourceRatios.z).normalize();
     sun.target.position.copy(shadowFocusTarget);
     sun.position.copy(shadowFocusTarget)
       .addScaledVector(shadowFocusDirection, attachment.sunDistance);
@@ -440,7 +447,8 @@ export function createLightingSystem({
     if (modulation.sunColorTint) {
       for (let i = 0; i < 3; i += 1) sunColor[i] = clamp(sunColor[i] * modulation.sunColorTint[i], 0, 4);
     }
-    const sunDirection = [frame.sunSourceRatios.x, frame.sunSourceRatios.y, frame.sunSourceRatios.z];
+    const sourceRatios = effectiveSunSourceRatios();
+    const sunDirection = [sourceRatios.x, sourceRatios.y, sourceRatios.z];
 
     if (attachment.sunRig?.setState) {
       attachment.sunRig.setState({
@@ -450,15 +458,15 @@ export function createLightingSystem({
         intensity: frame.sunIntensity * sunScale,
         shaftOpacity: 0.1 * frame.accentScale * sunScale,
         spillOpacity: 0.3 * frame.accentScale * sunScale,
-        ...(attachment.driveSunPosition ? { sourceRatios: frame.sunSourceRatios } : {}),
+        ...(attachment.driveSunPosition ? { sourceRatios } : {}),
       });
     } else if (attachment.ownSun) {
       attachment.ownSun.color.setRGB(sunColor[0], sunColor[1], sunColor[2]);
       attachment.ownSun.intensity = frame.sunIntensity * sunScale;
       attachment.ownSun.position.set(
-        frame.sunSourceRatios.x,
-        frame.sunSourceRatios.y,
-        frame.sunSourceRatios.z,
+        sourceRatios.x,
+        sourceRatios.y,
+        sourceRatios.z,
       ).multiplyScalar(attachment.sunDistance);
       attachment.ownSun.target.position.set(0, 0, 0);
       attachment.ownSun.target.updateMatrixWorld();
@@ -543,6 +551,26 @@ export function createLightingSystem({
       attachment.setSunDirection?.(sunDirection);
     }
 
+    // Rock material color remains geological; this transient input colors its
+    // small readability floor from the same visible sky that drives the rest
+    // of the world. Traverse only when the lighting frame changes, not per
+    // render frame, and deduplicate shared materials.
+    if (scene?.traverse) {
+      const rockMaterials = new Set();
+      scene.traverse((object) => {
+        if (!object?.isMesh || !object.material) return;
+        const materials = Array.isArray(object.material) ? object.material : [object.material];
+        for (const material of materials) {
+          if (material?.userData?.toonLabRockSceneState?.setSkyColor) {
+            rockMaterials.add(material);
+          }
+        }
+      });
+      for (const material of rockMaterials) {
+        material.userData.toonLabRockSceneState.setSkyColor(skyFillColor);
+      }
+    }
+
     if (attachment.water) {
       const waterFrame = {
         skyHorizonColor: renderedSky?.horizonColor ?? frame.skyHorizonColor,
@@ -717,6 +745,29 @@ export function createLightingSystem({
       return frame;
     },
 
+    /**
+     * Overrides the scene-space direction toward the sun without replacing
+     * the active time-of-day palette. Pass null to return direction ownership
+     * to the day curve.
+     */
+    setSunDirection(direction = null) {
+      if (direction == null) {
+        sunDirectionOverride = null;
+      } else {
+        const values = Array.isArray(direction)
+          ? direction.slice(0, 3).map(Number)
+          : [Number(direction.x), Number(direction.y), Number(direction.z)];
+        if (values.length < 3 || !values.every(Number.isFinite)) {
+          throw new TypeError('Sun direction must contain three finite components.');
+        }
+        const length = Math.hypot(...values);
+        if (length < 1e-6) throw new RangeError('Sun direction cannot be zero length.');
+        sunDirectionOverride = values.map((value) => value / length);
+      }
+      applyFrame();
+      return api.sunDirection;
+    },
+
     /** Advances the day cycle; use from update loops for live cycles. */
     advanceTime(hoursDelta) {
       return api.setTimeOfDay(hour + finite(hoursDelta, 0));
@@ -898,6 +949,10 @@ export function createLightingSystem({
     },
 
     get frame() { return frame; },
+    get sunDirection() {
+      const ratios = effectiveSunSourceRatios();
+      return [ratios.x, ratios.y, ratios.z];
+    },
     get manager() { return manager; },
     get quality() { return cloneJson(manager.quality); },
     get skyLightProbe() { return skyLightProbe; },

package/src/renderer/index.js

@@ -7,3 +7,10 @@ export {
   detectToonLabRendererBackend,
   stabilizeToonLabWebGPUResourceLifetime,
 } from './rendererConfiguration.js';
+export {
+  STYLE_COMPARISON_AXES,
+  STYLE_COMPARISON_GENERATED_NODE_FLAGS,
+  captureComparisonFrameState,
+  createStyleComparison,
+  verifyStyleComparisonIdentity,
+} from './styleComparison.js';