feat: irradiation compensation for dark backgrounds (#24)

* feat: irradiation compensation for dark backgrounds

Light content on dark backgrounds appears larger due to the optical
irradiation illusion. Apply a small scale-down (up to 5%) proportional
to how dark the detected background is.

Exposes backgroundLuminance (Rec.601) on MeasurementResult for opaque
images. Transparent images are unaffected.

* feat: pass backgroundColor in Comparison story to activate irradiation compensation

* refactor: density-aware irradiation compensation

Scale compensation by darkness × density × 0.08 instead of flat 5%.
Denser logos get more compensation (more surface area blooms).
Thin wordmarks get less. Based on Helmholtz irradiation research.

* refactor: use CSS color strings in Comparison story

Author: RostiMelk

src/types.ts

@@ -52,6 +52,7 @@ export interface MeasurementResult {
   contentBox?: BoundingBox;
   pixelDensity?: number;
   visualCenter?: VisualCenter;
+  backgroundLuminance?: number;
 }
 
 export type ImageRenderProps = ImgHTMLAttributes<HTMLImageElement> & {

src/utils/measure.ts

@@ -373,6 +373,10 @@ export function measureWithContentDetection(
     visualCenter,
   };
 
+  if (!alphaOnly) {
+    result.backgroundLuminance = (bgR * 299 + bgG * 587 + bgB * 114) / 255000;
+  }
+
   if (includeDensity) {
     const scanArea = (maxX - minX + 1) * (maxY - minY + 1);
     if (scanArea === 0) {

src/utils/normalize.ts

@@ -50,6 +50,25 @@ export function calculateNormalizedDimensions(
   let normalizedWidth = aspectRatio ** scaleFactor * baseSize;
   let normalizedHeight = normalizedWidth / aspectRatio;
 
+  // Irradiation compensation: light content on dark backgrounds appears
+  // larger/bolder due to the optical irradiation illusion. The effect is
+  // more pronounced on dense/bold logos (more surface area "blooms") and
+  // at higher contrast (darker backgrounds). Scale down proportionally
+  // to darkness × density. Only applies to opaque images where
+  // backgroundLuminance is available (transparent images are unaffected).
+  //
+  // References:
+  // - Helmholtz irradiation illusion (1860s)
+  // - https://gist.github.com/janogarcia/e9f57cd18ca85756743f81d9692764b7
+  // - https://nerdy.dev/adjust-perceived-typepace-weight-for-dark-mode-without-layout-shift
+  if (measurement.backgroundLuminance !== undefined) {
+    const darkness = 1 - measurement.backgroundLuminance;
+    const density = measurement.pixelDensity ?? 0.5;
+    const irradiationScale = 1 - darkness * density * 0.08;
+    normalizedWidth *= irradiationScale;
+    normalizedHeight *= irradiationScale;
+  }
+
   // Apply density compensation if available
   // Dense logos (high pixel density) get scaled down
   // Light/thin logos (low pixel density) get scaled up

stories/LogoSoup.DarkMode.stories.tsx

@@ -18,7 +18,7 @@ function InvertedSVGs({ count, shuffleSeed, ...rest }: StoryArgs) {
   }, [count, shuffleSeed]);
 
   return (
-    <div style={{ background: "#1a1a1a", padding: 16, borderRadius: 8 }}>
+    <div style={{ background: "#0a0a0a", padding: 16, borderRadius: 8 }}>
       <StoryLogoSoup logos={logos} {...rest} />
     </div>
   );
@@ -44,10 +44,10 @@ function SideBySide({ count, shuffleSeed, ...rest }: StoryArgs) {
   return (
     <>
       <div style={{ background: "#ffffff", padding: 16, borderRadius: 8 }}>
-        <StoryLogoSoup logos={originals} {...rest} />
+        <StoryLogoSoup logos={originals} backgroundColor="#ffffff" {...rest} />
       </div>
-      <div style={{ background: "#1a1a1a", padding: 16, borderRadius: 8 }}>
-        <StoryLogoSoup logos={inverted} {...rest} />
+      <div style={{ background: "#0a0a0a", padding: 16, borderRadius: 8 }}>
+        <StoryLogoSoup logos={inverted} backgroundColor="#0a0a0a" {...rest} />
       </div>
     </>
   );