FE-43: Add SpecularRim effect and move effects to components/effects/

Create composable effects folder with:
- refraction.tsx (moved from components/)
- specular-rim.tsx (new) — 2px directional edge highlight computed
  entirely in SVG filter primitives from the polar map

The rim is always ~2px wide regardless of radius, using an exponential
falloff table scaled by 2/radius. A directional cosine lobe controls
the light angle.

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

Author: kube

…refractive/src/components/refraction.tsx …ve/src/components/effects/refraction.tsxlibs/@hashintel/refractive/src/components/refraction.tsx renamed to libs/@hashintel/refractive/src/components/effects/refraction.tsx libs/@hashintel/refractive/src/components/refraction.tsx renamed to libs/@hashintel/refractive/src/components/effects/refraction.tsx

@@ -1,4 +1,4 @@
-import { generateTableValues } from "../helpers/generate-table-values";
+import { generateTableValues } from "../../helpers/generate-table-values";
 
 // Trig tables are constant — computed once at module level.
 const cosTable = generateTableValues(256, (i) => {

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

@@ -0,0 +1,130 @@
+import { generateTableValues } from "../../helpers/generate-table-values";
+
+/**
+ * Generates a rim falloff lookup table.
+ *
+ * Maps distance-to-border ratio [0,1] to rim intensity [0,1].
+ * The rim is always ~2px wide: `ratio = 2/radius` corresponds to 2px.
+ * A subtle exponential tail extends a few pixels beyond.
+ */
+function generateRimTable(radius: number): string {
+  // 2px expressed as a ratio of the total edge
+  const onePixelRatio = radius > 0 ? 2 / radius : 1;
+
+  return generateTableValues(256, (i) => {
+    const ratio = i / 255;
+    // Sharp peak at the border (first pixel), exponential decay after
+    return Math.exp((-ratio / onePixelRatio) * 2);
+  });
+}
+
+/**
+ * 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.
+ */
+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);
+  });
+}
+
+type SpecularRimProps = {
+  /** Input result name containing the polar map (R=distance ratio, G=angle). */
+  in: string;
+  /** Input source image to overlay the specular rim onto. */
+  source: string;
+  /** Corner radius in pixels — used to scale the rim to always be ~1px wide. */
+  radius: number;
+  /** Light angle in radians (0 = right, π/2 = down, π = left, 3π/2 = up). */
+  lightAngle?: number;
+  /** Controls the tightness of the directional highlight (1 = broad, higher = tighter). */
+  spread?: number;
+  /** Brightness multiplier for the specular highlight [0,1]. */
+  intensity?: number;
+  /** Output result name. */
+  result: string;
+};
+
+/**
+ * @private
+ * Specular rim effect: produces a directional edge highlight from the polar map
+ * and composites it over a source image.
+ *
+ * Pipeline:
+ * 1. Apply rim falloff table to R channel (distance-to-border → rim intensity)
+ * 2. Copy G channel (angle) to R, apply directional cosine table
+ * 3. Multiply rim × directional → combined specular intensity
+ * 4. Convert to white highlight with alpha = intensity
+ * 5. Composite over source
+ */
+export const SpecularRim: React.FC<SpecularRimProps> = ({
+  in: inResult,
+  source,
+  radius,
+  lightAngle = Math.PI / 4,
+  spread = 2,
+  intensity = 0.6,
+  result,
+}) => {
+  const rimTable = generateRimTable(radius);
+  const directionalTable = generateDirectionalTable(lightAngle, spread);
+
+  return (
+    <>
+      {/* 1. Distance-based rim falloff: R channel → rim intensity */}
+      <feComponentTransfer in={inResult} result={`${result}_rim`}>
+        <feFuncR type="table" tableValues={rimTable} />
+        <feFuncG type="discrete" tableValues="0" />
+        <feFuncB type="discrete" tableValues="0" />
+      </feComponentTransfer>
+
+      {/* 2. Copy angle (G) into R for directional lookup */}
+      <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}_angle`}
+      />
+
+      {/* 3. Apply directional cosine table to R channel */}
+      <feComponentTransfer in={`${result}_angle`} result={`${result}_dir`}>
+        <feFuncR type="table" tableValues={directionalTable} />
+      </feComponentTransfer>
+
+      {/* 4. Multiply rim × directional (both in R channel) */}
+      <feComposite
+        in={`${result}_rim`}
+        in2={`${result}_dir`}
+        operator="arithmetic"
+        k1={1}
+        k2={0}
+        k3={0}
+        k4={0}
+        result={`${result}_combined`}
+      />
+
+      {/* 5. Convert to white highlight: RGB=1, A=R×intensity */}
+      <feColorMatrix
+        in={`${result}_combined`}
+        type="matrix"
+        values={`0 0 0 0 1  0 0 0 0 1  0 0 0 0 1  ${intensity} 0 0 0 0`}
+        result={`${result}_highlight`}
+      />
+
+      {/* 6. Composite highlight over source */}
+      <feComposite
+        in={`${result}_highlight`}
+        in2={source}
+        operator="over"
+        result={result}
+      />
+    </>
+  );
+};

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

@@ -1,7 +1,8 @@
 import type { Parts } from "../helpers/split-imagedata-to-parts";
 import { buildCompositeSvgUrl } from "./composite/image";
 import { CompositeParts } from "./composite/parts";
-import { Refraction } from "./refraction";
+import { Refraction } from "./effects/refraction";
+import { SpecularRim } from "./effects/specular-rim";
 
 export type CompositeMode = "image" | "parts";
 
@@ -22,6 +23,8 @@ 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;
   hideTop?: boolean;
   hideBottom?: boolean;
   hideLeft?: boolean;
@@ -30,11 +33,11 @@ type FilterShellProps = {
 
 /**
  * @private
- * Full SVG filter pipeline: blur → polar map compositing → refraction effect.
+ * 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 the
- * Refraction effect (and in the future, other effects like specular).
+ * inside the SVG filter graph. The polar map is then consumed by composable
+ * effects (refraction, specular rim, etc.).
  */
 export const FilterShell: React.FC<FilterShellProps> = ({
   id,
@@ -45,6 +48,7 @@ export const FilterShell: React.FC<FilterShellProps> = ({
   cornerWidth,
   compositing = "image",
   elementRef,
+  specularRimAngle,
   hideTop,
   hideBottom,
   hideLeft,
@@ -98,6 +102,16 @@ export const FilterShell: React.FC<FilterShellProps> = ({
             source="blurred_source"
             result="refracted"
           />
+
+          {specularRimAngle !== undefined && (
+            <SpecularRim
+              in="polar_map"
+              source="refracted"
+              radius={cornerWidth}
+              lightAngle={specularRimAngle}
+              result="with_specular"
+            />
+          )}
         </filter>
       </defs>
     </svg>

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

@@ -49,6 +49,8 @@ type RefractionProps = {
      * - `"parts"`: 9-patch feImage primitives, requires explicit sizing.
      */
     compositing?: CompositeMode;
+    /** Specular rim light angle in radians. Undefined disables the effect. */
+    specularRimAngle?: number;
   };
 };
 
@@ -106,6 +108,7 @@ function createRefractiveComponent<
           cornerWidth={radius}
           compositing={refraction.compositing}
           elementRef={elementRef}
+          specularRimAngle={refraction.specularRimAngle}
         />
 
         {/* @ts-expect-error Need to fix types in this file */}

libs/@hashintel/refractive/stories/playground.stories.tsx

@@ -6,10 +6,12 @@ import { refractive } from "../src/hoc/refractive";
 import { ExampleArticle } from "./example-article";
 
 type Props = {
+  radius: number;
   compositing: CompositeMode;
+  specularRimAngle: number | undefined;
 };
 
-const GlassOverArticle = ({ compositing }: Props) => (
+const GlassOverArticle = ({ radius, compositing, specularRimAngle }: Props) => (
   <div style={{ position: "relative" }}>
     <refractive.div
       style={{
@@ -28,12 +30,13 @@ const GlassOverArticle = ({ compositing }: Props) => (
       }}
       refraction={{
         blur: 2,
-        radius: 20,
+        radius,
         edgeSize: 30,
         thickness: 70,
         refractiveIndex: 1.5,
         edgeProfile: convex,
         compositing,
+        specularRimAngle,
       }}
     >
       Refractive Glass
@@ -47,13 +50,21 @@ const meta = {
   title: "Playground",
   component: GlassOverArticle,
   argTypes: {
+    radius: {
+      control: { type: "range", min: 0, max: 100, step: 1 },
+    },
     compositing: {
       control: { type: "inline-radio" as const },
       options: ["image", "parts"],
     },
+    specularRimAngle: {
+      control: { type: "range", min: 0, max: 6.28, step: 0.01 },
+    },
   },
   args: {
+    radius: 20,
     compositing: "image",
+    specularRimAngle: Math.PI / 4,
   },
 } satisfies Meta<typeof GlassOverArticle>;
 
@@ -62,3 +73,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
+
+export const NoSpecular: Story = {
+  args: { specularRimAngle: undefined },
+};