FE-43: Add DiffuseReflection effect, shared lightAngle, and Playground controls

- DiffuseReflection: Lambertian shading using surface tilt (from edge profile
  derivative) × cos(borderAngle - lightAngle). Uses alpha-based white/black
  overlays instead of blend modes to avoid gray wash on dark backgrounds.
- Rename specularRimAngle → lightAngle (shared by diffuse and specular)
- SpecularRim: treat lightAngle as axis (|cos| for both sides), revert to 2px
- Add generateSurfaceTiltTable helper
- Playground: add radius, specular toggle, diffuseIntensity, shadowOpacity controls

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kube

libs/@hashintel/refractive/src/components/effects/diffuse-reflection.tsx

@@ -0,0 +1,125 @@
+import { generateTableValues } from "../../helpers/generate-table-values";
+
+/**
+ * Generates a directional cosine table centered at 0.5 (signed encoding).
+ *
+ * Maps the polar map angle channel [0,255] → [0,2π] to
+ * `(cos(angle - lightAngle) + 1) / 2`, where 0.5 = perpendicular,
+ * 1 = facing light, 0 = facing away.
+ */
+function generateCosAngleTable(lightAngle: number): string {
+  return generateTableValues(256, (i) => {
+    const angle = (i / 255) * 2 * Math.PI;
+    return (Math.cos(angle - lightAngle) + 1) / 2;
+  });
+}
+
+type DiffuseReflectionProps = {
+  /** Input result name containing the polar map (R=distance ratio, G=angle). */
+  in: string;
+  /** Input source image to apply diffuse shading to. */
+  source: string;
+  /** Light angle in radians (0 = right, π/2 = down, π = left, 3π/2 = up). */
+  lightAngle: number;
+  /**
+   * Pre-computed surface tilt lookup table (from generateSurfaceTiltTable).
+   * Maps distance ratio → normalized tilt [0,1].
+   */
+  surfaceTiltTable: string;
+  /** Strength of the diffuse shading [0,1]. */
+  intensity?: number;
+  /** Output result name. */
+  result: string;
+};
+
+/**
+ * @private
+ * Diffuse reflection effect: applies Lambertian-style shading based on the
+ * surface normal (derived from the edge profile) and light direction.
+ *
+ * Surfaces facing the light are brightened (white overlay), surfaces facing
+ * away are darkened (black overlay). Neutral areas have alpha=0 and don't
+ * affect the source at all — no gray wash on dark backgrounds.
+ *
+ * Pipeline:
+ * 1. Extract angle (G) → cosine of angle relative to light direction (signed, centered at 0.5)
+ * 2. Extract distance ratio (R) → surface tilt from edge profile (unsigned [0,1])
+ * 3. Signed × unsigned multiply → diffuse value centered at 0.5
+ * 4. Light pass: white with alpha = max(0, diffuse - 0.5) × 2 × intensity
+ * 5. Dark pass: black with alpha = max(0, 0.5 - diffuse) × 2 × intensity
+ */
+export const DiffuseReflection: React.FC<DiffuseReflectionProps> = ({
+  in: inResult,
+  source,
+  lightAngle,
+  surfaceTiltTable,
+  intensity = 0.3,
+  result,
+}) => {
+  const cosAngleTable = generateCosAngleTable(lightAngle);
+  const lightAlphaScale = 2 * intensity;
+
+  return (
+    <>
+      {/* 1. Copy angle (G) into R, apply signed cosine table */}
+      <feColorMatrix
+        in={inResult}
+        type="matrix"
+        values="0 1 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0"
+        result={`${result}_cos_in`}
+      />
+      <feComponentTransfer in={`${result}_cos_in`} result={`${result}_cos`}>
+        <feFuncR type="table" tableValues={cosAngleTable} />
+      </feComponentTransfer>
+
+      {/* 2. Apply surface tilt table to R channel (distance ratio → tilt) */}
+      <feComponentTransfer in={inResult} result={`${result}_tilt`}>
+        <feFuncR type="table" tableValues={surfaceTiltTable} />
+      </feComponentTransfer>
+
+      {/* 3. Signed × unsigned multiply: cos(centered 0.5) × tilt(unsigned)
+           result = A·B - 0.5·B + 0.5
+           Maps to [0,1] centered at 0.5: >0.5 = lit, <0.5 = shadow */}
+      <feComposite
+        in={`${result}_cos`}
+        in2={`${result}_tilt`}
+        operator="arithmetic"
+        k1={1}
+        k2={0}
+        k3={-0.5}
+        k4={0.5}
+        result={`${result}_diffuse`}
+      />
+
+      {/* 4. Light pass: white overlay where diffuse > 0.5
+           A = intensity × 2 × (R - 0.5), clamped to 0 when R < 0.5 */}
+      <feColorMatrix
+        in={`${result}_diffuse`}
+        type="matrix"
+        values={`0 0 0 0 1  0 0 0 0 1  0 0 0 0 1  ${lightAlphaScale} 0 0 0 ${-intensity}`}
+        result={`${result}_light`}
+      />
+      <feComposite
+        in={`${result}_light`}
+        in2={source}
+        operator="over"
+        result={`${result}_lit`}
+      />
+
+      {/* 5. Dark pass: black overlay where diffuse < 0.5
+           A = intensity × 2 × (0.5 - R), clamped to 0 when R > 0.5 */}
+      <feColorMatrix
+        in={`${result}_diffuse`}
+        type="matrix"
+        values={`0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  ${-lightAlphaScale} 0 0 0 ${intensity}`}
+        result={`${result}_dark`}
+      />
+      <feComposite
+        in={`${result}_dark`}
+        in2={`${result}_lit`}
+        operator="over"
+        result={result}
+      />
+    </>
+  );
+};

libs/@hashintel/refractive/src/components/effects/specular-rim.tsx

@@ -22,16 +22,17 @@ function generateRimTable(radius: number): string {
  * Generates a directional highlight lookup table.
  *
  * Maps the polar map angle channel [0,255] → [0,2π] to a cosine
- * lobe centered on `lightAngle`. The lobe width is controlled by
- * `spread`: 1 = normal cosine, higher = tighter highlight.
+ * lobe along the `lightAngle` axis. The light direction is treated
+ * as an axis — both the light-facing and opposite sides receive
+ * the highlight. The lobe width is controlled by `spread`.
  */
 function generateDirectionalTable(lightAngle: number, spread: number): string {
   return generateTableValues(256, (i) => {
     // The polar map G channel encodes the displacement angle (toward center).
     const angle = (i / 255) * 2 * Math.PI;
     const dot = Math.cos(angle - lightAngle);
-    // Raise to power for tighter highlights, clamp negative
-    return Math.pow(Math.max(0, dot), spread);
+    // Use |cos| so both sides of the axis get the highlight
+    return Math.pow(Math.abs(dot), spread);
   });
 }
 

libs/@hashintel/refractive/src/components/filter-shell.tsx

@@ -1,6 +1,7 @@
 import type { Parts } from "../helpers/split-imagedata-to-parts";
 import { buildCompositeSvgUrl } from "./composite/image";
 import { CompositeParts } from "./composite/parts";
+import { DiffuseReflection } from "./effects/diffuse-reflection";
 import { Refraction } from "./effects/refraction";
 import { SpecularRim } from "./effects/specular-rim";
 
@@ -11,6 +12,7 @@ type FilterShellProps = {
   blur: number;
   scale: number;
   magnitudeTable: string;
+  surfaceTiltTable: string;
   parts: Parts;
   cornerWidth: number;
   /**
@@ -23,8 +25,12 @@ type FilterShellProps = {
   compositing?: CompositeMode;
   /** Ref to the element whose dimensions drive the "parts" layout. Required when compositing is "parts". */
   elementRef?: React.RefObject<HTMLElement | null>;
-  /** Specular rim light angle in radians. Undefined disables the effect. */
-  specularRimAngle?: number;
+  /** Light direction in radians. Enables diffuse and specular effects. */
+  lightAngle?: number;
+  /** Strength of diffuse reflection shading [0,1]. 0 or undefined disables. */
+  diffuseIntensity?: number;
+  /** Whether to enable the specular rim highlight. Requires lightAngle. */
+  specular?: boolean;
   hideTop?: boolean;
   hideBottom?: boolean;
   hideLeft?: boolean;
@@ -35,26 +41,42 @@ type FilterShellProps = {
  * @private
  * Full SVG filter pipeline: blur → polar map compositing → effects.
  *
- * The `compositing` prop controls how the 9-patch polar map is assembled
- * inside the SVG filter graph. The polar map is then consumed by composable
- * effects (refraction, specular rim, etc.).
+ * Effect chain: refraction → diffuse reflection → specular rim.
+ * Each effect consumes the shared polar map independently.
  */
 export const FilterShell: React.FC<FilterShellProps> = ({
   id,
   blur,
   scale,
   magnitudeTable,
+  surfaceTiltTable,
   parts,
   cornerWidth,
   compositing = "image",
   elementRef,
-  specularRimAngle,
+  lightAngle,
+  diffuseIntensity,
+  specular,
   hideTop,
   hideBottom,
   hideLeft,
   hideRight,
 }) => {
   const isImage = compositing === "image";
+  const hasDiffuse =
+    lightAngle !== undefined &&
+    diffuseIntensity !== undefined &&
+    diffuseIntensity > 0;
+  const hasSpecular = specular !== false && lightAngle !== undefined;
+
+  // Build the effect chain: refraction → diffuse → specular
+  // Each effect reads "polar_map" and takes the previous result as source.
+  const refractionResult = "refracted";
+  const diffuseResult = hasDiffuse ? "with_diffuse" : refractionResult;
+  const specularResult = hasSpecular ? "with_specular" : diffuseResult;
+  // The last enabled effect's result is used as the filter output.
+  // SVG uses the last result in the filter chain automatically.
+  void specularResult; // referenced implicitly by the filter
 
   return (
     <svg colorInterpolationFilters="sRGB" style={{ display: "none" }}>
@@ -100,16 +122,27 @@ export const FilterShell: React.FC<FilterShellProps> = ({
             scale={scale}
             in="polar_map"
             source="blurred_source"
-            result="refracted"
+            result={refractionResult}
           />
 
-          {specularRimAngle !== undefined && (
+          {hasDiffuse && (
+            <DiffuseReflection
+              in="polar_map"
+              source={refractionResult}
+              lightAngle={lightAngle}
+              surfaceTiltTable={surfaceTiltTable}
+              intensity={diffuseIntensity}
+              result={diffuseResult}
+            />
+          )}
+
+          {hasSpecular && (
             <SpecularRim
               in="polar_map"
-              source="refracted"
+              source={diffuseResult}
               radius={cornerWidth}
-              lightAngle={specularRimAngle}
-              result="with_specular"
+              lightAngle={lightAngle}
+              result={specularResult}
             />
           )}
         </filter>

libs/@hashintel/refractive/src/helpers/generate-table-values.ts

@@ -39,3 +39,31 @@ export function generateMagnitudeTable(
     );
   });
 }
+
+/**
+ * Generate a surface tilt lookup table from an edge profile function.
+ *
+ * Maps border distance ratio [0,1] to normalized surface tilt [0,1],
+ * where 0 = flat surface (no diffuse contribution) and 1 = maximum tilt.
+ *
+ * The tilt is `sin(atan(derivative))` = `|d| / sqrt(1 + d²)` where d is
+ * the edge profile's derivative at the given ratio.
+ *
+ * @param edgeProfile - Surface equation function (e.g. convex, concave).
+ * @param ratioScale - Multiplier to remap the input ratio (e.g. radius/edgeSize).
+ */
+export function generateSurfaceTiltTable(
+  edgeProfile: (x: number) => number,
+  ratioScale: number = 1,
+): string {
+  return generateTableValues(256, (i) => {
+    if (i === 0) return 0; // border/outside → no effect
+    const ratio = Math.min(1, (i / 255) * ratioScale);
+    if (ratio >= 1) return 0; // past the edge → flat
+    const dx = 0.0001;
+    const derivative =
+      (edgeProfile(Math.min(1, ratio + dx)) - edgeProfile(ratio)) / dx;
+    // sin(atan(d)) = |d| / sqrt(1 + d²)
+    return Math.abs(derivative) / Math.sqrt(1 + derivative * derivative);
+  });
+}

libs/@hashintel/refractive/src/hoc/refractive.tsx

@@ -4,7 +4,10 @@ import type { JSX } from "react/jsx-runtime";
 
 import type { CompositeMode } from "../components/filter-shell";
 import { FilterShell } from "../components/filter-shell";
-import { generateMagnitudeTable } from "../helpers/generate-table-values";
+import {
+  generateMagnitudeTable,
+  generateSurfaceTiltTable,
+} from "../helpers/generate-table-values";
 import { splitImageDataToParts } from "../helpers/split-imagedata-to-parts";
 import { convex } from "../helpers/surface-equations";
 import { calculateDisplacementMapRadius } from "../maps/displacement-radius";
@@ -49,8 +52,12 @@ type RefractionProps = {
      * - `"parts"`: 9-patch feImage primitives, requires explicit sizing.
      */
     compositing?: CompositeMode;
-    /** Specular rim light angle in radians. Undefined disables the effect. */
-    specularRimAngle?: number;
+    /** Light direction in radians (0 = right, π/2 = down). Used by diffuse and specular effects. */
+    lightAngle?: number;
+    /** Strength of diffuse reflection shading [0,1]. 0 disables. */
+    diffuseIntensity?: number;
+    /** Whether to enable the specular rim highlight. Default true when lightAngle is set. */
+    specular?: boolean;
   };
 };
 
@@ -97,18 +104,24 @@ function createRefractiveComponent<
       ratioScale,
     );
 
+    const edgeProfile = refraction.edgeProfile ?? convex;
+    const surfaceTiltTable = generateSurfaceTiltTable(edgeProfile, ratioScale);
+
     return (
       <>
         <FilterShell
           id={filterId}
           blur={refraction.blur ?? 0}
           scale={2 * maximumDisplacement}
           magnitudeTable={magnitudeTable}
+          surfaceTiltTable={surfaceTiltTable}
           parts={hiResParts}
           cornerWidth={radius}
           compositing={refraction.compositing}
           elementRef={elementRef}
-          specularRimAngle={refraction.specularRimAngle}
+          lightAngle={refraction.lightAngle}
+          diffuseIntensity={refraction.diffuseIntensity}
+          specular={refraction.specular}
         />
 
         {/* @ts-expect-error Need to fix types in this file */}