feat: adaptive background detection for dark mode support (#23)

* feat: adaptive background detection for dark mode support

Replace hardcoded white (255,255,255) background assumption in content
detection with auto-detection from image perimeter pixels.

Two strategies, chosen automatically:
- Alpha-only: transparent PNGs skip color-distance filtering entirely
- Perimeter sampling: opaque images infer background via quantized
  color bucketing of edge pixels

Adds backgroundColor prop as explicit override fallback.

* fix: revert corner-first optimization, restore full perimeter scan

The corner-first fast path misidentified logo content as background
when logos extended to the corners, causing sizing regressions.

Restores the first commit's logic (full perimeter scan, alphaOnly for
transparent images) with typed arrays instead of Map for bucketing.

* feat: add dark mode stories, test logos, shared story controls

- Inverted SVGs (transparent, light content) and JPG test logos
- Dark Mode, JPG, and Comparison stories under LogoSoup group
- Shared StoryLogoSoup wrapper with debug controls
- Consolidated argTypes, defaults, and types in shared.tsx
- alphaOnly path for transparent images, color distance for opaque
- min(a, sqrt(distSq)) opacity for opaque density normalization

* fix: story sidebar ordering by renaming DarkMode story file

* feat: accept CSS color strings for backgroundColor prop

BackgroundColor type accepts hex, rgb(), hsl(), named colors, or
[r, g, b] tuples. CSS strings are resolved via a 1×1 canvas.

Author: RostiMelk

.storybook/preview.ts

@@ -9,6 +9,15 @@ const preview: Preview = {
       },
     },
     layout: "centered",
+    options: {
+      storySort: {
+        order: [
+          "LogoSoup",
+          ["Default", "Dark Mode", "JPG", "Comparison"],
+          "No Optimization (Worst Case)",
+        ],
+      },
+    },
   },
 };
 

package.json

@@ -20,6 +20,7 @@
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target browser --format esm --sourcemap=external --external react --external react-dom && bun build src/index.ts --outfile dist/index.cjs --target browser --format cjs --sourcemap=inline --external react --external react-dom && bun run build:types",
     "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist",
+    "generate:logos": "bun scripts/generate-test-logos.ts",
     "prepublishOnly": "bun run build",
     "test": "bun test",
     "bench": "bun tests/bench/run.ts",

scripts/generate-test-logos.ts

@@ -0,0 +1,48 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createCanvas, loadImage } from "@napi-rs/canvas";
+
+const LOGOS_DIR = join(import.meta.dir, "../static/logos");
+const INVERTED_DIR = join(import.meta.dir, "../static/logos-inverted");
+const JPG_DIR = join(import.meta.dir, "../static/logos-jpg");
+
+mkdirSync(INVERTED_DIR, { recursive: true });
+mkdirSync(JPG_DIR, { recursive: true });
+
+const svgFiles = readdirSync(LOGOS_DIR).filter((f) => f.endsWith(".svg"));
+
+console.log(`Processing ${svgFiles.length} SVGs…\n`);
+
+let invertedCount = 0;
+let jpgCount = 0;
+
+for (const file of svgFiles) {
+  const src = readFileSync(join(LOGOS_DIR, file), "utf-8");
+
+  // --- Inverted SVG: light content, still transparent ---
+  const inverted = src.replaceAll('fill="#0B0B0B"', 'fill="#F4F4F4"');
+  writeFileSync(join(INVERTED_DIR, file), inverted);
+  invertedCount++;
+
+  // --- JPG: rasterize SVG onto opaque white background ---
+  const svgBuf = Buffer.from(src);
+  try {
+    const img = await loadImage(svgBuf);
+    const scale = Math.min(1, 400 / img.width);
+    const w = Math.round(img.width * scale);
+    const h = Math.round(img.height * scale);
+    const canvas = createCanvas(w, h);
+    const ctx = canvas.getContext("2d");
+    ctx.fillStyle = "#ffffff";
+    ctx.fillRect(0, 0, w, h);
+    ctx.drawImage(img, 0, 0, w, h);
+    const jpgBuf = canvas.toBuffer("image/jpeg");
+    writeFileSync(join(JPG_DIR, file.replace(/\.svg$/, ".jpg")), jpgBuf);
+    jpgCount++;
+  } catch (e) {
+    console.warn(`  ⚠ Failed to rasterize ${file}: ${e}`);
+  }
+}
+
+console.log(`✓ ${invertedCount} inverted SVGs → static/logos-inverted/`);
+console.log(`✓ ${jpgCount} JPGs → static/logos-jpg/`);

src/components/LogoSoup.tsx

@@ -27,6 +27,7 @@ export function LogoSoup({
   densityAware,
   densityFactor,
   cropToContent,
+  backgroundColor,
   alignBy = DEFAULT_ALIGN_BY,
   gap = DEFAULT_GAP,
   renderImage,
@@ -42,6 +43,7 @@ export function LogoSoup({
     densityAware,
     densityFactor,
     cropToContent,
+    backgroundColor,
   });
 
   const ImageComponent = renderImage || DefaultImage;

src/hooks/useLogoSoup.ts

@@ -1,4 +1,4 @@
-import { useEffect, useReducer, useRef } from "react";
+import { useEffect, useMemo, useReducer, useRef } from "react";
 import {
   DEFAULT_BASE_SIZE,
   DEFAULT_CONTRAST_THRESHOLD,
@@ -18,6 +18,7 @@ import {
   cropToBlobUrl,
   loadImage,
   measureWithContentDetection,
+  resolveBackgroundColor,
 } from "../utils/measure";
 import {
   createNormalizedLogo,
@@ -91,8 +92,17 @@ export function useLogoSoup(options: UseLogoSoupOptions): UseLogoSoupResult {
     densityAware = DEFAULT_DENSITY_AWARE,
     densityFactor = DEFAULT_DENSITY_FACTOR,
     cropToContent = DEFAULT_CROP_TO_CONTENT,
+    backgroundColor: backgroundColorProp,
   } = options;
 
+  const resolvedBg = useMemo(
+    () =>
+      backgroundColorProp
+        ? resolveBackgroundColor(backgroundColorProp)
+        : undefined,
+    [backgroundColorProp],
+  );
+
   const [state, dispatch] = useReducer(reducer, INITIAL_STATE);
 
   const logosRef = useRef(logos);
@@ -105,6 +115,7 @@ export function useLogoSoup(options: UseLogoSoupOptions): UseLogoSoupResult {
   const cacheKeyRef = useRef({
     contrastThreshold: NaN,
     densityAware: false,
+    resolvedBg: undefined as [number, number, number] | undefined,
   });
 
   useEffect(() => {
@@ -120,12 +131,22 @@ export function useLogoSoup(options: UseLogoSoupOptions): UseLogoSoupResult {
     const cache = cacheRef.current;
     const prevKey = cacheKeyRef.current;
 
+    const bgChanged =
+      prevKey.resolvedBg?.[0] !== resolvedBg?.[0] ||
+      prevKey.resolvedBg?.[1] !== resolvedBg?.[1] ||
+      prevKey.resolvedBg?.[2] !== resolvedBg?.[2];
+
     if (
       prevKey.contrastThreshold !== contrastThreshold ||
-      prevKey.densityAware !== densityAware
+      prevKey.densityAware !== densityAware ||
+      bgChanged
     ) {
       clearCache(cache);
-      cacheKeyRef.current = { contrastThreshold, densityAware };
+      cacheKeyRef.current = {
+        contrastThreshold,
+        densityAware,
+        resolvedBg,
+      };
     }
 
     const sources: LogoSource[] = stableLogos.map(normalizeSource);
@@ -178,6 +199,7 @@ export function useLogoSoup(options: UseLogoSoupOptions): UseLogoSoupResult {
             img,
             contrastThreshold,
             densityAware,
+            resolvedBg,
           );
           entry = { img, measurement };
           cache.set(source.src, entry);
@@ -244,6 +266,7 @@ export function useLogoSoup(options: UseLogoSoupOptions): UseLogoSoupResult {
     densityAware,
     densityFactor,
     cropToContent,
+    resolvedBg,
   ]);
 
   return {

src/index.ts

@@ -3,6 +3,7 @@ export { DEFAULT_ALIGN_BY } from "./constants";
 export { useLogoSoup } from "./hooks/useLogoSoup";
 export type {
   AlignmentMode,
+  BackgroundColor,
   BoundingBox,
   ImageRenderProps,
   LogoSoupProps,

src/types.ts

@@ -1,5 +1,12 @@
 import type { CSSProperties, ImgHTMLAttributes, ReactNode } from "react";
 
+type HexColor = `#${string}`;
+type RGBFunction = `rgb(${string})` | `rgba(${string})`;
+type HSLFunction = `hsl(${string})` | `hsla(${string})`;
+type CSSColor = HexColor | RGBFunction | HSLFunction | (string & {});
+
+export type BackgroundColor = CSSColor | [number, number, number];
+
 export type AlignmentMode =
   | "bounds"
   | "visual-center"
@@ -65,6 +72,7 @@ export interface UseLogoSoupOptions {
   densityAware?: boolean;
   densityFactor?: number;
   cropToContent?: boolean;
+  backgroundColor?: BackgroundColor;
 }
 
 export interface UseLogoSoupResult {
@@ -82,6 +90,7 @@ export interface LogoSoupProps {
   densityAware?: boolean;
   densityFactor?: number;
   cropToContent?: boolean;
+  backgroundColor?: BackgroundColor;
   alignBy?: AlignmentMode;
   gap?: number | string;
   renderImage?: RenderImageFn;