Forem: Teimur Gasanov

Building SSR-Friendly Avatars with In-Browser AI: How I Trained Python Models and Ported Them to TensorFlow.js

Teimur Gasanov — Tue, 09 Dec 2025 12:02:32 +0000

We just shipped the initial release of Avatune, an open-source avatar system that combines native SVG rendering with experimental in-browser ML models. Here's what makes it different and why you might care.

The Problem

Avatar libraries typically fall into two camps:

Canvas-based - Fast, but breaks SSR and accessibility
SVG-as-image - SSR-friendly, but no dynamic theming or component composition

I wanted both: true SSR compatibility AND intelligent avatar generation from user photos.

Native SVG = First-Class SSR

Every avatar in Avatune renders as a real SVG element, not a canvas or base64 image. This means:

Zero hydration mismatch - Server renders identical markup to client
Accessibility built-in - Screen readers can access SVG semantics
CSS styling works - Target elements with selectors, use CSS variables
Inspectable in DevTools - Debug like any DOM element

import { Avatar } from '@avatune/react'
import theme from '@avatune/pacovqzz-theme/react'

// This SSR renders as clean SVG markup
function UserCard({ seed }: { seed: string }) {
  return <Avatar theme={theme} seed={seed} size={200} />
}

Experimental In-Browser ML Predictors

Here's where it gets interesting. I trained several CNN models in Python using TensorFlow/Keras on the CelebA and FairFace datasets, then converted them to TensorFlow.js for browser inference:

Hair Color Predictor - black, brown, blond, gray
Hair Length Predictor - short, medium, long
Skin Tone Predictor - light, medium, dark
Facial Hair Predictor - clean-shaven vs facial hair

The training pipeline uses Marimo notebooks (think Jupyter, but reactive). Models are quantized to uint8 and served via CDN. Total bundle for a predictor: up-to 2MB.

Type-Safe Themes

Each theme exports strongly-typed color enums and layer configurations:

import type { ReactAvatarItem } from '@avatune/types'
import { createTheme, fromHead } from '@avatune/theme-builder'

const theme = createTheme()
  .withStyle({ size: 500, borderRadius: '100%' })
  .addColors('hair', [HairColors.Black, HairColors.Brown, HairColors.Blond])
  .addColors('skin', [SkinTones.Light, SkinTones.Medium, SkinTones.Dark])
  .connectColors('head', ['ears', 'nose'])  // ears + nose inherit head's skin color
  .setOptional('glasses')
  .mapPrediction('hairColor', 'brown', [HairColors.Brown, HairColors.Auburn])
  .toFramework<ReactAvatarItem>()
  .build()

TypeScript knows exactly which colors and items are valid for each theme. No more runtime surprises.

Custom Rsbuild Plugins for SVG → Component

When you have 500+ SVG files across multiple frameworks, you hit a problem: SVG id and mask collisions. Put two avatars on a page, and their internal gradients and masks conflict.

I built two Rsbuild plugins to solve this:

@avatune/rsbuild-plugin-svg-to-svelte and @avatune/rsbuild-plugin-svg-to-vue

They transform SVG files into proper framework components with:

Auto-prefixed IDs via SVGO (no collisions)
Preserved viewBox for responsive scaling
Query-based imports for flexibility

<script>
  import Icon from './icon.svg?svelte'
</script>

<Icon />

<script setup>
import Icon from './icon.svg?vue'
</script>

<template>
  <Icon />
</template>

The Stack

Turborepo - Monorepo orchestration with caching
Bun - Package manager (2x faster installs)
Rspack/Rslib - Build tooling (10x faster than webpack)
Biome - Linting + formatting (replaces ESLint + Prettier)
uv - Python package manager (10-100x faster than pip)

10 themes, 5 framework renderers (React, Vue, Svelte, Vanilla, React Native), 5 ML predictors. All from one monorepo.

Try It

Website + Docs: avatune.dev
GitHub: github.com/avatune/avatune
Playground: avatune.dev/docs/playground

npm install @avatune/react @avatune/pacovqzz-theme

The ML models are experimental - I'd love feedback on accuracy and performance. If you're into training better attribute predictors, PRs welcome.

Building BlazeDiff: How I Made The Fastest Image Diff up-to 60% Faster with Block-Level Optimization

Teimur Gasanov — Mon, 01 Sep 2025 12:17:46 +0000

From analyzing pixelmatch's bottlenecks to creating a faster algorithm with zero allocations and dynamic block sizing.

The Spark: Visual Testing Performance Pain

It started during a usual day of visual regression testing. I was watching a CI pipeline going through hundreds of screenshot comparisons, each one taking precious seconds.

I was using pixelmatch: the gold standard for pixel-level image comparison in JavaScript. It's an excellent library that's served the community well for years. But as my test suite grew and image resolutions increased, those milliseconds started adding up to minutes. I thought: "There has to be a better way."

Diving Deep: Analyzing pixelmatch's Architecture

Before jumping into optimization, I needed to understand what pixelmatch was actually doing. I dove into the source code and found a beautifully simple algorithm:

// Simplified pixelmatch flow
function pixelmatch(img1, img2, output, width, height, options) {
  // 1. Check if images are completely identical (fast path)
  const len = width * height;
  const a32 = new Uint32Array(img1.buffer, img1.byteOffset, len);
  const b32 = new Uint32Array(img2.buffer, img2.byteOffset, len);

  let identical = true;
  for (let i = 0; i < len; i++) {
    if (a32[i] !== b32[i]) { 
      identical = false; 
      break; 
    }
  }

  if (identical) return 0; // Early exit

  // 2. Pixel-by-pixel comparison using YIQ color space
  for (let y = 0; y < height; y++) {
    for (let x = 0; x < width; x++) {
      // Complex color difference calculation...
    }
  }
}

Pixelmatch had a clever optimization for completely identical images. It would quickly scan through 32-bit chunks and exit early. But what about partially identical images?

In real-world visual testing scenarios:

Screenshots often have large unchanged regions (headers, sidebars, backgrounds)
Only small portions typically change (content areas, buttons, text)
We were still processing every single pixel even when 80% of the image was identical

The "Aha!" Moment: Coarse-to-Fine Processing

The breakthrough came when I realized we could apply the "identical check" concept at a block level, rather than just the entire image.

What if we could:

Divide the image into blocks (16x16, 32x32, etc.)
Quickly identify which blocks are identical using the same 32-bit comparison trick
Skip pixel-level processing entirely for identical blocks
Only do the expensive YIQ color analysis on blocks that actually changed

This is a classic coarse-to-fine approach used in computer vision, but I hadn't seen it applied to web-based image diffing libraries.

From Idea to Implementation

Challenge #1: Dynamic Block Sizing

Fixed block sizes would be suboptimal – small images need fine granularity, large images can use bigger blocks for better cache performance.

function calculateOptimalBlockSize(width: number, height: number): number {
  const area = width * height;

  // Block size grows roughly with the square root of the image area
  // Scale factor chosen to match your thresholds
  const base = 16;
  const scale = Math.sqrt(area) / 100; // 100 is a tuning constant

  // Round to nearest power-of-two block size
  const rawSize = base * Math.pow(scale, 0.5);
  return Math.pow(2, Math.round(Math.log2(rawSize)));
}

Challenge #2: Efficient Memory Management

Initial prototypes were actually slower than pixelmatch because I was creating dynamic arrays and objects to store block information. The allocation overhead was killing performance.

The solution? Store changed coordinates only and preprocess blocks:

// Instead of storing full changed blocks in arrays...
const changedBlocks = [];
const identicalBlocks = [];

// Allocate memory for a fast Int32Array...
const maxBlocks = Math.ceil(width / 8) * Math.ceil(height / 8); // worst case
  const changedBlockCoords = new Int32Array(maxBlocks * 4); // x,y,endX,endY
let changedCount = 0;

// Preprocess blocks...
for (let by = 0; by < blocksY; by++) {
  for (let bx = 0; bx < blocksX; bx++) {
    if (blockIsIdentical(startX, startY, endX, endY)) {
      processIdenticalBlock(); // Draw gray pixels immediately
    } else {
      processChangedBlock();   // Add to changedBlockCoords
    }
  }
}

// Process only changed blocks...
for (let blockIdx = 0; blockIdx < changedCount; blockIdx++) {

}

Challenge #3: Maintaining Pixel-Perfect Accuracy

The block optimization couldn't change the final result – it had to produce identical output to pixelmatch. This meant:

Same YIQ color space calculations
Same anti-aliasing detection
Same output pixel colors
Only the processing order could change

Going Live

After solving the core algorithmic challenges, I released BlazeDiff as MIT licensed with a minimal ecosystem:

@blazediff/core - The core algorithm
@blazediff/pngjs-transformer - PNG support using pngjs
@blazediff/sharp-transformer - High-performance image processing with Sharp
@blazediff/bin - Transformers + core algorithm via CLI or programmatically

This modular approach means you only install what you need, keeping bundle sizes minimal.

Built for Today's Ecosystem

While analyzing pixelmatch, I noticed it was built with the tooling standards of its era. Don't get me wrong – it works perfectly. But I saw an opportunity to leverage modern development practices that could improve both developer experience and performance.

pixelmatch approach:

JavaScript with JSDoc comments
npm for package management
Basic build setup
Single package architecture

BlazeDiff approach:

TypeScript for type safety and better DX
pnpm for efficient dependency management
tsup for lightning-fast builds
Monorepo architecture with multiple focused packages

Why does it matter?

Crystal clear APIs and complete IntelliSense with TypeScript
TypeScript's compile-time safety prevents common mistakes
Bundle size wins with composable monorepo packages
- @blazediff/core is only 8.59 kB compared to pixelmatch's 19.4 kB

The Results: 20-60% Performance Improvement

After weeks of optimization and benchmarking:

Around 20-25% boost when using @blazediff/core package
Around 60-99% boost when using @blazediff/bin with @blazediff/sharp-transformer.

You can find benchmark results in the GitHub Action of the BlazeDiff repository.