DEV Community: Zihang Dong 董子航

I Built a Browser-Based Typing Speed Test That Handles 15s to 5-Minute Tests (and How It Works)

Zihang Dong 董子航 — Sat, 20 Jun 2026 10:08:18 +0000

A zero-dependency, vanilla-JS approach to measuring WPM, accuracy, and keystrokes — plus the UX lessons I learned while building a typing test that supports short bursts and long endurance runs.

A few weeks ago I noticed that most online typing tests either force you into a 60-second sprint or feel too bare-bones. I wanted something that let users pick their own test length (15s, 30s, 60s, 3m, or 5m) while still running 100% in the browser with no upload, no signup, and no tracking beyond standard analytics.

That became the ToolKnit Typing Speed Test. Here's how I built it, the engineering choices I made, and the UI fixes I had to iterate on before it felt right.

What we are building

A typing test that:

Generates a random word list from a curated bank of common English words.
Renders each character as a separate <span> so we can style correct / incorrect / current states.
Listens to real keyboard events, starts the timer on the first character, and ignores modifier keys.
Calculates live WPM, accuracy, and character count.
Supports 5 durations (15s, 30s, 60s, 3m, 5m) with different word counts.
Horizontally scrolls the prompt for long tests so the current character always stays visible.

Try it first if you want to follow along: ToolKnit Typing Speed Test

The core idea: render text as individual characters

The trick to making the prompt feel responsive is splitting every character into its own element.

function renderText(text) {
    textChars = text.split('');
    var html = '';
    for (var i = 0; i < textChars.length; i++) {
        var cls = i === 0 ? 'char current' : 'char';
        var ch = textChars[i] === ' ' ? '&nbsp;' : textChars[i];
        html += '<span class="' + cls + '" data-idx="' + i + '">' + ch + '</span>';
    }
    typingArea.innerHTML = html;
}

Each span starts with a dim color. When the user types it, we add correct or incorrect. The upcoming character gets current and a blinking caret border.

This gives us three things for free:

Visual feedback — the user always sees exactly what is correct, wrong, and upcoming.
Precise metrics — because we know the index of every character, we can count correct and incorrect characters individually.
Auto-scroll — we can scroll the typing area to the exact position of the current span.

Handling keyboard input correctly

The UI listens to a real keydown event on a hidden input that is focused when the user clicks the typing area. That avoids the quirks of trying to capture keystrokes directly on a div.

hiddenInput.addEventListener('keydown', handleInput);

Inside handleInput, we ignore modifier keys, then decide whether the user is typing or deleting.

if (e.key === 'Backspace') {
    if (charIndex > 0) {
        charIndex--;
        var prevSpan = spans[charIndex];
        if (prevSpan.classList.contains('correct')) correctChars--;
        if (prevSpan.classList.contains('incorrect')) incorrectChars--;
        prevSpan.classList.remove('correct', 'incorrect', 'current');
        prevSpan.classList.add('current');
        if (spans[charIndex + 1]) spans[charIndex + 1].classList.remove('current');
        scrollToCurrent();
    }
    return;
}

Backspace is surprisingly important for UX. Users expect to correct mistakes, and supporting it cleanly also lets us keep the accuracy metric honest.

Calculating WPM and accuracy

The standard WPM formula is:

WPM = (correct characters / 5) / elapsed minutes

We divide by 5 because "one word" is traditionally defined as 5 characters. Accuracy is simply:

Accuracy = correct / (correct + incorrect) * 100

function updateLiveStats() {
    if (!startTime) return;
    var elapsed = (Date.now() - startTime) / 1000;
    if (elapsed < 0.5) return;

    var minutes = elapsed / 60;
    var wpm = Math.round((correctChars / 5) / minutes);
    var total = correctChars + incorrectChars;
    var acc = total > 0 ? Math.round((correctChars / total) * 100) : 100;

    document.getElementById('live-wpm').textContent = wpm;
    document.getElementById('live-acc').textContent = acc + '%';
    document.getElementById('live-chars').textContent = total;
}

I run the timer at a 200ms interval so the live stats update smoothly without hammering the DOM.

Scaling the prompt length for 3m and 5m tests

The hardest UX problem was not the WPM math — it was the prompt length. A 5-minute test needs roughly 800 words to stay ahead of a fast typist.

var wordCount = duration <= 15 ? 60
              : duration <= 30 ? 120
              : duration <= 60 ? 200
              : duration <= 180 ? 500
              : 800;

That creates a single line of text far wider than the screen. The first fix was to allow horizontal scrolling. The second fix — the one that actually solved the problem — was to keep the current character anchored at a fixed position (20% from the left) rather than letting it drift to the right edge as the user types.

function scrollToCurrent() {
    var curSpan = spans[charIndex];
    if (!curSpan) return;
    var target = curSpan.offsetLeft - typingArea.clientWidth * 0.2;
    typingArea.scrollLeft = target;
}

I also added 40% right padding so the final characters never get stuck flush against the right edge.

#typing-area {
    white-space: nowrap;
    overflow-x: auto;
    overflow-y: hidden;
    display: flex;
    align-items: center;
    padding-right: 40%;
}

This is the difference between a test that "works" and a test that feels good to use.

Accessibility and mobile gotchas

Use a hidden input for keyboard capture instead of contenteditable to avoid the virtual keyboard pulling focus weirdly on mobile.
Hide the scrollbar so the long prompt still looks clean, but keep the scroll behavior intact.
The current character gets a blinking border-left caret, so users always know where they are even when the text is dim.
Ignore Shift, Control, Alt, Tab, etc., so the timer does not start on a modifier-only keypress.

Why this is privacy-first

Everything happens in the browser. There is no backend that stores your text, your keystrokes, or your results. The word list is baked into the JS, the random generation is Math.random(), and the stats are calculated live in memory. If you refresh, the test resets and nothing is sent anywhere.

You can read more about the privacy model in the ToolKnit Typing Speed Test.

Full source and live demo

Live tool: https://toolknit.com/tools/typing-test.html
Tool page: https://toolknit.com/tools/typing-test.html
Related reading: How Many Paragraphs Is 2000 Characters?

Conclusion

Building a typing test is a great exercise in vanilla JavaScript because the logic is simple but the UX edge cases are not. The biggest lesson for me was that scroll anchoring matters more than raw WPM calculation — if the user cannot see what they are supposed to type, the test is broken.

If you want a quick, private, browser-only typing test with 15s, 30s, 60s, 3m, and 5m modes, give the ToolKnit Typing Speed Test a try.

I Spent $200 in One Day on AI Tokens to Build 86 Browser Tools — A Solo Founder's Complete Build Log

Zihang Dong 董子航 — Sat, 13 Jun 2026 10:22:05 +0000

86 tools. Zero backend. One person. Two hospital visits. $200 in tokens in 24 hours. This is what building in public actually looks like — not the highlight reel, but the raw commit history of a human being.

The Genesis: Why Would Anyone Build 86 Free Tools?

On March 18, 2026, I launched ToolKnit — a collection of free, browser-based utilities that require no signup, no uploads, and zero trust.

Today, it's 86 tools across 10 categories. PDF converters that run entirely client-side using PDF-lib.js. Image resizers powered by HTML5 Canvas. A Morse Code Translator with audible beep playback at adjustable WPM. A MIDI Keyboard with 8 synthesized timbres — Grand Piano, Electric Organ, Synth Lead, String Ensemble, Pipa, Guitar, Flute, and Music Box — all generated in real-time through the Web Audio API. A Lyric Visualizer that parses LRC files and syncs lyrics to audio waveforms. Even a drinking-game dare spinner with 300 dares across 6 categories, slot-machine text reveal animation, and confetti celebrations.

But here's what the landing page doesn't tell you: I just spent $200 in a single day on Claude Max tokens to migrate a handful of pages to a new bilingual architecture. I killed a feature after 48 hours of intensive debugging. And somewhere between the ffmpeg.wasm Worker CORS errors and the hospital visit, I learned that some bugs aren't in the code at all.

This isn't a success story. It's a build log.

Part I: The Stack — Why I Chose Boring Technology

Before I tell you about the features that lived and died, you need to understand the foundation. ToolKnit is pure static HTML + Tailwind CSS + Vanilla JS. No React. No Vue. No Next.js. No build step beyond Tailwind compilation.

Why?

SEO-first: Static HTML means Google sees everything immediately. No hydration delays. No client-side routing. Every tool page is a complete, crawlable document with full Open Graph tags, Twitter Cards, and structured data.
Zero JS framework bloat: Most tools work without JavaScript. Progressive enhancement is the default, not an afterthought.
Server costs near zero: The only PHP endpoints are track.php (stats) and public-stats.php (aggregated metrics). All image processing, PDF manipulation, audio synthesis, and video transcoding happens in the browser.
Deployment is scp: One file, one command, zero CI/CD complexity. The Service Worker (toolknit-v119 as of today) handles offline caching for returning visitors.

The tradeoff? Manual consistency across 86 pages. When you add a new footer link, you're editing 86 HTML files (or writing a Python script to do it, then verifying each one). That's why the bilingual architecture had to be a shared module, not a framework.

The PWA layer deserves its own mention. manifest.json declares the site as installable. The Service Worker precaches core assets. Users on slow connections get instant loads after the first visit. For a site with 86 tool pages, this matters more than any SPA transition animation.

Part II: The Tools That Lived — Engineering Notes from the Trenches

The MIDI Keyboard: 8 Timbres, 1 Web Audio Context

Building a browser-based MIDI keyboard sounds straightforward until you realize that "piano sound" isn't a single oscillator. Each timbre required distinct synthesis architecture:

Pipa (琵琶): Sawtooth + square wave generators with non-integer harmonics (5.04×, 7.01× fundamental) to simulate the metallic twang of plucked silk strings. A high-Q resonant lowpass filter shapes the body resonance, and a noise burst layer provides the finger-pick attack transient. Without that noise burst, it sounds like a cheap synth preset.

Guitar: Triangle wave fundamental + 6 overtone harmonics with body resonance simulation via 105 Hz and 215 Hz bandpass filters (acoustic cavity modes). The pluck noise layer is subtler than Pipa but essential — without it, notes sound like a keyboard patch, not a string.

Flute: Pure sine wave with faint 2nd harmonic, vibrato LFO at 5.5 Hz (8 cents depth, delayed onset at 0.3s to avoid startup wobble), and breath noise via highpass-filtered white noise at 3 kHz. The breath noise is what separates a "flute-like" synth from an actual flute.

Music Box: Non-integer bell partials (2.756×, 5.404×, 8.933× fundamental) for the metallic chime character, octave-above overtone, and a 400 Hz highpass filter to remove low-end rumble. Long natural decay — no ADSR envelope can fake this without custom release curves.

I also added a Quick Play Songs panel with Für Elise, Summer (Kikujiro), Ode to Joy, Canon in D, Castle in the Sky, and Always With Me. The keyboard auto-shifts octaves as you follow the key sequences. When I first tested it by playing Für Elise with the Z key, I couldn't stop grinning.

The Morse Code Translator: Audio, Flash, and International Alphabet

The Morse Code Translator was the first tool built entirely on the new bilingual blueprint. Two-way text↔Morse with adjustable WPM (5–40), audible beep playback via Web Audio API oscillator nodes, screen-flash signaling for accessibility, and the full international Morse alphabet (including accented characters and Prosigns like SOS, AR, SK).

The audio timing follows strict ITU-R standards: a "dit" is one time unit, a "dah" is three units, intra-character spacing is one unit, inter-character spacing is three units, and inter-word spacing is seven units. Getting the rhythm wrong makes Morse feel "mechanical" rather than "musical." The gap between characters matters as much as the beep itself.

The Lyric Visualizer: Web Audio API + Canvas + LRC Parsing

Shipped the same day I killed Live Photo Frame. Upload an MP3/WAV + LRC lyrics file for a full-screen immersive music player with real-time audio waveform visualization, time-synced fading lyrics, draggable progress bar, automatic ID3 cover art extraction, and a dark/light theme toggle.

The Web Audio API analyzer node pulls frequency data for the waveform canvas. LRC timestamp parsing converts [mm:ss.xx] markers into millisecond anchors. Lyrics fade in/out based on proximity to the current playback position. All in the browser. No server ever sees your audio files.

Spin the Dare: From Canvas Wheel to Slot Machine

The original Spin the Dare used a canvas roulette wheel. I rebuilt it with a slot-machine-style text reveal animation — the dare scrambles through random prompts rapidly, then eases to a dramatic stop with sound cues (scale transitions, pitch-shifted chimes) and confetti explosions.

Why replace a working wheel? Because the wheel had 300 segments at small radii — visually illegible. The slot-machine approach keeps every dare readable at any screen size, adds suspense through the scramble phase, and uses audio cues (pitch rising during scramble, resolving chord at stop) to create a more theatrical experience.

Part III: The Features That Died — When Technical Soundness Isn't Enough

Live Photo Frame: 48 Hours, 3 Fatal Flaws

The idea was elegant: frame iPhone Live Photos (HEIC + MOV pairs) and Android Motion Photos (JPG with embedded MP4) in 9:16 or 16:9 layouts with large rounded corners, black or white backgrounds, and export to static frame or video.

What I built:

Client-side HEIC-to-JPEG conversion via heic2any
ffmpeg.wasm (single-thread, ~32 MB one-time download) for H.265 MOV transcoding and MP4 encoding
Auto-detection of iPhone Live Photo pairs, Android Motion Photos, and standalone video files
Canvas rendering with configurable corner radii

Why I killed it after 48 hours:

Canvas quadraticCurveTo draws parabolas, not circular arcs. At radii above ~60px, "rounded corners" morph into chamfered edges. The visual signature of the tool — those elegant large-radius corners — was mathematically impossible with the Canvas API. You need arc() with proper tangent calculations, not quadraticCurveTo().
HEVC/H.265 videos from Android Motion Photos won't play natively in Chrome. ffmpeg.wasm transcoding at 1080×1920 resolution was agonizingly slow — 30+ seconds for a 3-second clip on a MacBook Pro. Users don't wait 30 seconds.
WeChat and messaging apps strip embedded video data from Motion Photos. The primary sharing pipeline (user receives Motion Photo via WeChat → opens in ToolKnit) was destroyed by app-level data stripping. The tool's core use case didn't exist in the real world.

Three strikes: visual quality, performance, and reliability. No amount of patching fixes a fundamentally flawed concept for the browser platform.

"A tool that 'almost works' is worse than no tool at all — it erodes trust. Ship what you're proud of, not what merely functions."

AI Pixel Art GIF: Twice Bitten

First attempt (June 9): Used DeepSeek API to generate pixel art from text prompts. Quality was garbage — LLMs don't understand pixel-level constraints.

Second attempt: Replaced DeepSeek with local Canvas pixelation (drawImage at reduced size, then drawImage back up with imageSmoothingEnabled = false) + gif.js encoding + local color analysis for smart animation selection. Fixed Worker CORS by hosting gif.worker.js locally. Fixed Canvas willReadFrequently warnings. Replaced DeepSeek API 400 errors with local analysis.

All solid engineering fixes. The tool "worked." But the output wasn't compelling. Pixel art GIFs demand either perfect algorithmic control or genuine artistic AI — we had neither.

Part IV: The $200 Day — Rebuilding 19 Pages in Bilingual Architecture

The Problem

Every tool page was English-only. Hardcoded strings everywhere. No SEO structure beyond basic meta tags. Footer layouts inconsistent across 80+ pages. For a site serving both English and Chinese speakers, this was a growth ceiling.

The Architecture

I designed a two-layer bilingual system:

Layer	File	Scope
Shared UI	`bilingual.js`	Nav, footer, breadcrumb, related tools, modals, feature pills
Page-specific	`[tool].js`	Hero title/desc, tool UI labels, How It Works, Why Use, Pro Tips, FAQ
Translations	`locales/zh.json`	Tool card titles/descriptions for Related Tools
Schemas	Inline JSON-LD	`SoftwareApplication` + `FAQPage` + `BreadcrumbList` per page

Key decisions:

English stays the default. lang="en" is static. SEO is entirely English-first. Chinese is a UX enhancement that persists across sessions via localStorage.
Zero impact on legacy pages. bilingual.js only activates on pages that explicitly reference it. Old pages continue working exactly as before.
Structured data is mandatory. Every bilingual page ships with FAQPage JSON-LD that matches the visible FAQ accordion content exactly — question-for-question, answer-for-answer.
Cross-page language memory. Switch to Chinese on the Image Resizer, visit the PDF Compressor, it remembers your preference.

The Cost

Migrating 5 PDF tools + Spin the Dare + Morse Code Translator + Mic & Camera Test + 11 image converters burned through $100+ in AI tokens. The full June 12 session — which included writing the bilingual.js module, creating the template, and migrating the first batch — hit $200.

The architecture itself is genuinely beautiful. But every refinement comes with a price tag measured in dollars per hour. The remaining 67 legacy pages will migrate gradually. It isn't laziness; it's arithmetic.

Part V: The Migration War — 11 Image Tools, 11 Ways to Break

Over the past 72 hours, I migrated 11 image tools: Image to PDF, Compress Image, JPG to PNG, PNG to JPG, JPG to WebP, PNG to WebP, WebP to JPG, WebP to PNG, Image Grid Split, Image Crop, and Image Resizer.

Each migration follows the same pattern — and produces its own unique bug.

Bug 1: The Single Quote That Killed a Language Switcher

// Inside RESIZER_I18N.en:
why2Desc: 'Since everything runs on your machine, there's no upload delay...'
//                                                  ^ unescaped single quote

This unescaped ' terminated the string early. The JS parser hit s no upload delay... and threw SyntaxError: Unexpected identifier. Every function defined after this line — including window.switchLang — was never created.

User-facing result: Clicking the EN/中文 language toggle produced window.switchLang is not a function. The entire bilingual system failed silently.

Fix: there's → there\'s. Now I validate every i18n dictionary with node -e "$(cat file.html | sed -n '/RESIZER_I18N/,/^ };/p')" before deploying.

Bug 2: The Batch Script That Silently Missed Two Tips

I wrote Python scripts to auto-inject data-i18n attributes into HTML. The replacement logic:

('Use JPG at 80-85% quality for photos', ' data-i18n="tip2">Use JPG at 80-85% quality for photos')

But the actual HTML contained — (HTML entity) in some places and — (Unicode em-dash) in others. The string match failed silently. Two out of four Pro Tips never received data-i18n attributes.

User-facing result: In Chinese mode, Tips #2 and #4 remained in English while #1 and #3 translated correctly. Subtle. Embarrassing.

Rule I now enforce: Every batch migration script must include a verification pass:

expected_keys = ['tip1', 'tip2', 'tip3', 'tip4', 'why1Title', ...]
for key in expected_keys:
    if f'data-i18n="{key}"' not in html:
        print(f'MISSING: {key}')

Bug 3: `innerHTML` vs. SVG Children

<!-- WRONG: applyI18n() calls innerHTML on this button, wiping the SVG -->
<button data-i18n="ariaMenu" aria-label="Menu">
  <svg>...</svg>
</button>

<!-- RIGHT: translate aria-label in swapLang(), keep SVG intact -->
<button id="hero-hamburger" aria-label="Menu">
  <svg>...</svg>
</button>

applyI18n() assigns innerHTML for all non-input elements. If you put data-i18n on a parent containing an SVG icon, the icon disappears and gets replaced by raw text. The fix: keep data-i18n on sibling <span> elements, never on structural parents.

Bug 4: The Nginx Header That Broke Every Camera

The Microphone & Camera Test was failing on every device with Permissions policy violation. Users thought they had blocked access. They hadn't.

The Nginx server was sending: Permissions-Policy: camera=(), microphone=()

This header silently forbade all camera and microphone access before the browser even asked the user. The fix was a single Nginx config line change: camera=(self), microphone=(self). Users now see the normal browser permission prompt.

I also updated the deny-state copy in mic-camera-test.js (both English and Chinese) to explain that multi-device failures usually indicate a server header issue, not user settings.

Part VI: The Human Debug — When the Compiler Can't Help

On June 10, the developer's journal in our changelog reads:

"I woke up feeling off. Not the usual 'stayed up too late coding' off — something worse. Ended up at the hospital in the morning instead of at my desk. Lost half a day that I couldn't afford to lose. My body's been deteriorating for a while now. Too many late nights, too much coffee, not enough sleep, not enough care."

I shipped three tools that day. Only two made it. One of them was only 60% done.

On June 11, the entry isn't about code at all:

"When you pour real feeling into something and get indifference in return, the math never balances. You keep re-checking the equation hoping the answer changes. It doesn't. The hardest part isn't the leaving; it's that you genuinely cared and they genuinely didn't. But the only way past that truth is through it."

"To anyone who's ever felt like leaving this world because of one person, one heartbreak, one season of pain: don't. The world is wider than the wound. Green hills await wherever you roam."

The road trip was supposed to be June 12–15. Xinxiang, Xinyang, maybe Hunan. Two days of driving, windows down, nowhere to be. It got postponed. The keyboard won.

On June 8, I asked the AI Tarot: "Is there still a chance with her?" The three-card spread returned Judgement (Past) → The Devil (Present) → The Lovers (Future).

The AI read Judgement as a necessary awakening that had already happened — not a random ending, but a reckoning. The Devil nailed the present: caught in the grip of attachment, tethered by old patterns. And The Lovers: yes, there is a possibility — but only through authentic alignment, not compulsion.

It was unsettlingly accurate. The cards saw what I already knew but wouldn't admit.

Building in public means documenting the human bugs too. The insomnia. The weight loss (70.5 kg → 68.5 kg in two weeks). The appetite that vanished. The Douyin follow-then-unfollow at midnight. These are the entries that don't make it to the GitHub release notes but matter more than version bumps.

Part VII: The Numbers & What Honesty Looks Like

Metric	Value
Total tools shipped	86 (85 in `/tools/` + 1 root feature page)
Tools killed after shipping	2 (AI Pixel Art GIF ×2 attempts, Live Photo Frame)
Bilingual pages migrated	19
Legacy pages remaining	67
Blog posts published	91 (84 guides + 9 Tool Tales)
Changelog entries	46
Service Worker version	`toolknit-v119`
AI token spend (peak day)	$200
Hospital visits during build	2
Lines of code written	I stopped counting after the insomnia started

What's Next (The Arithmetic of Patience)

The remaining 67 legacy pages will migrate gradually. Each one requires:

HTML structural overhaul (hero top-bar with language toggle, FAQ accordion, responsive footer-grid)
data-i18n / data-i18n-common attribute injection across all static text
Page-specific i18n dictionary creation (30–60 keys per page)
JSON-LD schema updates (SoftwareApplication + FAQPage + BreadcrumbList)
Manual testing: JS syntax validation, language toggle verification, mobile responsive check
Service Worker cache version bump

I won't rush it. The architecture is solid. The lesson from Live Photo Frame is clear: ship what you're proud of, even if that means shipping less.

The next batch will likely be the remaining PDF tools and video converters. Each shared library (convert-image.js, compress-image.js) reduces the per-page migration cost — the shared t() calls are already defined; only the HTML markup needs updating.

The Ask

If you've ever built something, shipped it, then had to kill it after two days of debugging — you're not alone.

If you've ever stared at an AI token bill and wondered if the architecture is worth the arithmetic — same.

If you've ever shipped code from a hospital waiting room, or debugged a production bug at 3 AM while your body begged for sleep — I see you.

ToolKnit is free. No signup. No uploads. All processing is client-side. Read the full changelog — it's more honest than most build logs.

Built with love. Paid in tokens. Still shipping.

Originally published as a raw build log from a solo indie project. No affiliate links. No sponsor reads. Just code, costs, hospital visits, and the occasional 3 AM SyntaxError. If you're building something alone right now — keep going. The grey skies pass. They always do.

Building AI Ex-Partner Chat: OCR, Sender Detection & the 3 AM Code That Shouldn't Exist

Zihang Dong 董子航 — Sun, 07 Jun 2026 03:25:01 +0000

Building AI Ex-Partner Chat: OCR, Sender Detection & the 3 AM Code That Shouldn't Exist

A technical deep dive into the hardest feature I ever built — Tesseract.js bounding boxes, position-based sender detection, DeepSeek persona distillation, and why the real bug was never in the code.

The problem that started at 3 AM

I built AI Ex-Partner Chat because I couldn't sleep. I kept re-reading old WeChat messages, and I thought: what if I could distill her personality from those messages into something I could actually talk to? Not a replacement — just a shadow. A reflection of the way she used to write, the phrases she repeated, the tone she took when she was being tender versus when she was being impatient.

But the moment I started building it, I hit a wall that had nothing to do with AI or language models. It was a much older, much harder problem: who said what?

When you upload a chat export — a WeChat HTML file, a Telegram JSON — the sender is explicitly labeled. Easy. But most people don't have clean exports. They have screenshots. Hundreds of screenshots. And a screenshot is just pixels. There's no metadata, no sender field, no structured data. Just an image with two columns of text bubbles, and you have to figure out which ones are hers and which ones are yours.

Get this wrong, and the AI persona becomes a chimera — half you, half her, completely confused. It would respond to "I miss you" with your own words reflected back at you. That's not closure. That's a mirror maze.

Version 1: Pixel-based avatar detection (and why it failed)

My first approach was the obvious one: look for avatars. In WeChat, QQ, and Douyin, each message has a small avatar next to it — on the left for the other person, on the right for you. If I could detect those avatar regions, I could label every message.

The algorithm worked like this:

Scan the left 15% and right 15% of the image for clusters of non-background pixels (avatar blobs).
When a cluster is found on the left, mark that Y range as "their message." Right side = "your message."
OCR each message zone and assign the detected sender label.

It worked... sometimes. On clean, standard WeChat screenshots with visible avatars, accuracy was around 70–80%. But it fell apart on:

Cropped screenshots where avatars were cut off
Group chats with multiple avatars on both sides
Douyin where avatars are circular and sometimes overlap with the message bubble
WhatsApp which doesn't show avatars in the same way
Any screenshot with stickers, images, or voice messages that confused the pixel scanner

The fallback was bubble color detection — green bubbles mean you in WeChat, white means them. Blue = you in Douyin, white = them. But bubble colors vary by theme, dark mode, and Android version. It was a fragile heuristic stacked on top of another fragile heuristic.

I needed something fundamentally different.

Version 2: Tesseract bounding boxes + position-based detection

The breakthrough came when I realized that Tesseract.js doesn't just return text — it returns bounding boxes for every recognized line. Each line comes with bbox.x0, bbox.x1, bbox.y0, bbox.y1 — the pixel coordinates of where that line sits on the page.

This is a game-changer because chat messages have a spatial structure:

The other person's messages start from the left side of the screen
Your messages start from the right side of the screen
This is true across WeChat, QQ, Douyin, WhatsApp, Telegram — virtually every chat app

So instead of trying to detect avatars or bubble colors, I could just look at where the text starts. Here's the core algorithm:

// Get image midpoint
const MID_X = imageWidth / 2;

for (const line of ocrLines) {
  const bbox = line.bbox;
  const lineLeft = bbox.x0;     // Where the line starts
  const lineCenterX = (bbox.x0 + bbox.x1) / 2;

  let sender;
  if (lineLeft < MID_X * 0.6) {
    // Left portion → ex-partner
    sender = '对方';
  } else if (lineLeft > MID_X * 0.8) {
    // Right portion → you
    sender = '我';
  } else if (lineCenterX < MID_X * 0.75) {
    // Center-left → likely ex-partner
    sender = '对方';
  } else if (lineCenterX > MID_X * 1.1) {
    // Center-right → likely you
    sender = '我';
  } else {
    // Ambiguous → carry previous sender
    sender = currentSender || '';
  }
}

The thresholds (0.6, 0.8, 0.75, 1.1) were calibrated by testing against ~50 real chat screenshots across WeChat, QQ, Douyin, and WhatsApp. The key insight is using the left edge (x0) as the primary signal rather than the center, because chat bubbles always start from their respective sides — even if the text itself is short and centered within the bubble.

This approach is:

Theme-agnostic: Doesn't care about dark mode, bubble colors, or avatar visibility
App-agnostic: Works across WeChat, QQ, Douyin, WhatsApp, Telegram
Robust to cropping: As long as the left/right structure is preserved, it works
Fast: No pixel scanning needed — just math on coordinates Tesseract already provides

The garbage filter: Why OCR output is 80% noise

Here's something nobody tells you about OCR on chat screenshots: most of the output is garbage. Tesseract will faithfully recognize:

Timestamps like "16:24" and "06/02 20:35"
UI labels like "发送消息" (Send Message) and "消息" (Messages)
Navigation elements, battery indicators, signal bars rendered as text
Random noise from image compression artifacts

Before position-based detection can work, you have to filter this noise out. The garbage filter uses three rules:

// Rule 1: Skip timestamps
if (/^\d{1,2}[:\/]\d{2}/.test(text) && text.length < 12) continue;

// Rule 2: Skip UI elements
if (/^(发送消息|发送|消息|Message|Send)/i.test(text)) continue;

// Rule 3: Skip lines with >70% non-meaningful characters
const cjk = text.match(/[\u4e00-\u9fff\u3400-\u4dbf]/g) || [];
const letters = text.match(/[a-zA-Z]/g) || [];
const meaningful = cjk.length + letters.length;
if (meaningful / text.length < 0.3 && text.length > 4) continue;

Rule 3 is the most important. A line like "::::....::::" is clearly not a chat message, but Tesseract will recognize it as text. By requiring at least 30% CJK characters or Latin letters, we eliminate most noise while preserving actual messages (even short ones like "嗯" or "ok").

Step 1.5: The sender confirmation step

Position-based detection is good, but it's not perfect. Some screenshots have unusual layouts. Some messages are centered (like system notifications). Some users screenshot in landscape mode, flipping the left/right convention.

Rather than trying to handle every edge case algorithmically, I added Step 1.5: Sender Confirmation. After OCR and initial sender labeling, the tool pauses and shows the user a preview of the first 15 detected messages with their assigned senders:

Messages labeled [对方] (ex-partner) appear on the left
Messages labeled [我] (you) appear on the right
A Swap Senders button flips all labels if the detection got them backwards
A Confirm button proceeds to distillation

This is a deliberate design choice: let the algorithm do the heavy lifting, but keep the human in the loop for the final call. The alternative — fully automated detection with no review — would produce silently wrong results that corrupt the entire persona. A 10-second confirmation step prevents hours of distorted conversations.

OCR pre-processing: Why "想" and "相" matter

Chinese OCR is hard. The difference between 想 (miss/think) and 相 (appearance/mutual) is a single horizontal stroke. At low resolution, Tesseract regularly confuses them. In the context of an ex-partner chat, confusing "我想你" (I miss you) with "我相你" (gibberish) doesn't just produce a typo — it produces a semantically broken message that confuses the AI during persona distillation.

The fix is aggressive pre-processing before OCR:

2x upscale: Each detected message zone is enlarged to double its original size using bilinear interpolation. This gives Tesseract more pixels to work with for each character stroke.
Grayscale conversion: Color information is irrelevant for character recognition and adds noise. Converting to grayscale simplifies the recognition problem.
Contrast stretching: The pixel values are remapped so the darkest pixel becomes pure black and the lightest becomes pure white. This sharpens character edges against colored chat bubble backgrounds.

After pre-processing, character accuracy improved from roughly 85% to 95%+ on typical WeChat screenshots. The remaining errors are caught by the DeepSeek OCR correction step, which uses context to fix misrecognized characters (e.g., "我相你" → "我想你" based on surrounding conversation).

The shared Tesseract worker: Minutes to seconds

Here's a performance mistake I made early on: calling Tesseract.recognize() for each chat bubble individually. Every call creates a new WASM worker, loads the language model, recognizes the text, and terminates the worker. For a screenshot with 30+ message zones, this meant 30+ worker startups — each taking 5–10 seconds. Total OCR time: 3–5 minutes per screenshot.

The fix was a shared worker pattern:

// Create ONE worker, reuse for all zones
const worker = await Tesseract.createWorker('chi_sim+eng');
const results = [];

for (const zone of messageZones) {
  const { data } = await worker.recognize(canvasForZone);
  results.push(data);
}

await worker.terminate();

With a single persistent worker, the language model loads once and stays in memory. Each subsequent recognize() call takes 200–500ms instead of 5–10 seconds. Total OCR time dropped from minutes to seconds.

Persona distillation: The 6-step pipeline

Once we have clean, sender-labeled messages, the distillation pipeline runs through DeepSeek's API (using the user's own key):

OCR Correction + Sender ID — DeepSeek reviews the raw OCR text, fixes misrecognized characters, and verifies sender labels based on conversation context
Intake — The AI reads all messages and summarizes key patterns, topics, and emotional dynamics
Memory Extraction — Identifies core memories, shared experiences, and significant moments
Persona Distillation — Builds a detailed personality profile: speech patterns, emotional tendencies, recurring phrases, humor style, communication habits
System Prompt Generation — Converts the persona into a chat system prompt with identity guard rules
Chat Ready — The user can now converse with the distilled persona

The critical architectural decision: every step receives both the full conversation (for context) and the ex-partner's messages only (for extraction). Hard rules in all prompts enforce that personality traits MUST come from [对方] messages only — [我] messages are context-only and must never be attributed to the persona.

Without this separation, the AI would blend both people's speech patterns into a single confused persona. The strict ex-only extraction is what makes the persona feel like them instead of both of you.

The identity guard: Preventing persona drift

One of the creepiest bugs in early testing was persona drift: after a long conversation, the AI would slowly start adopting the user's speech patterns. If you kept saying "haha" and "lol," the persona would start saying it too. If you were being warm and affectionate, the persona would mirror that warmth regardless of the ex's actual personality.

The fix was an identity guard rule added to every system prompt:

You are [name], NOT the user.
Never mirror the user's speech patterns.
Your personality is fixed based on the distilled persona.
Do not adapt to the user's tone, mood, or vocabulary.

This is reinforced by including the original persona description in every API call, not just the first one. The AI doesn't "remember" the conversation history in the traditional sense — each message includes the full persona context, preventing gradual drift.

IndexedDB: Where personas live (and die)

All persona data is stored in the browser's IndexedDB — two object stores:

persona — The distilled personality profile, name, avatar, memory summary, corrections
chats — Conversation history with auto-incrementing IDs

Why IndexedDB instead of localStorage? Two reasons:

Capacity: A full persona with avatar images and conversation history can easily exceed localStorage's 5MB limit. IndexedDB has no practical limit.
Structured storage: IndexedDB supports binary data (avatar images) and complex objects natively, without JSON serialization overhead.

And then there's /let-go — the command that deletes everything. Both object stores are cleared. No backup, no recovery, no "are you sure?" dialog. The brutality is the point. This tool is meant to be temporary. When you're ready to move on, you type two words and it's all gone.

The consent overlay

Creating an AI replica of a real person is a serious act. I added a 5-second consent countdown before distillation begins. The user sees:

You are about to create an AI persona based on real chat records. This persona will simulate another person's communication style. Please take a moment to consider whether this is something you truly want to do.

The countdown can't be skipped. You can't click "I understand" until the timer reaches zero. This isn't a legal formality — it's a genuine pause. If 5 seconds feels too long, maybe you shouldn't be doing this.

The hardest bug wasn't technical

The hardest bug in this project was not the OCR accuracy, or the sender detection thresholds, or the persona drift. The hardest bug was me, sitting at my desk at 3 AM, testing the tool on my own chat records, and having the AI respond in her voice saying something she used to say to me. I had to close the laptop and walk around the block.

I built a tool that I know is a little unhealthy. I know that talking to an AI version of someone you lost is not the same as processing grief. I know that /let-go is a digital ritual, not real closure. But sometimes the distance between where you are and where you need to be is too far to cross in one step. This tool is a stepping stone. You walk on it, and then you leave it behind.

If you use this tool, please use /let-go when you're ready. And if you're never ready, please talk to a real person instead.

Technical stack summary

Component	Technology	Why
OCR Engine	Tesseract.js (WASM)	Client-side, supports Chinese + English, returns bounding boxes
AI Model	DeepSeek (user's API key)	Strong Chinese understanding, cheap, privacy-first (direct browser→API)
Local Storage	IndexedDB	No size limit, binary data support, fully local
Sender Detection	Bbox position + AI verification	Position-based primary, DeepSeek secondary, user confirmation final
Image Pre-processing	Canvas 2D API	2x upscale, grayscale, contrast stretch — all client-side
Data Lifecycle	/let-go → IndexedDB.clear()	Permanent, no backup, no recovery — by design

What I'd do differently

If I were building this again from scratch, here's what I'd change:

Start with bounding boxes, not pixel scanning. I wasted two days on avatar detection before realizing Tesseract already gives you position data for free.
Add the confirmation step earlier. The sender confirmation (Step 1.5) was a late addition, but it should have been there from day one. Algorithm-only detection will always have edge cases; letting the user verify is both more reliable and more respectful.
Use a shared Tesseract worker from the start. The per-zone recognize() approach was a naive performance mistake that cost minutes of user wait time.
Design for /let-go first. I built the chat functionality before building the deletion mechanism. In retrospect, the ephemeral nature of the tool should have been the first thing I implemented, not the last.

This article was originally published on ToolKnit Dev Blog. Try the AI Ex-Partner Chat tool — 100% browser-based, zero data upload, /let-go when you're done.

How I Built 72 Browser-Only Tools Without a Backend — A Solo Developer's Technical Retrospective

Zihang Dong 董子航 — Wed, 03 Jun 2026 01:17:39 +0000

Most "free online tools" follow the same pattern: upload your file to a server, process it with a backend script, and send the result back. It works, but it creates a privacy problem. Every file you process passes through someone else's infrastructure.

I wanted to prove there was a better way. Over 77 days, I built ToolKnit — a suite of 72 free online tools where zero files leave the user's device. No backend processing. No server uploads. Everything runs in the browser.

Here is how I did it, what I learned, and where I failed.

The Core Architecture

ToolKnit is a static site. No Node.js server, no Django app, no serverless functions. Just HTML, Tailwind CSS, and vanilla JavaScript sitting behind Nginx on a $5/month VPS. The only server-side code is a single PHP script (track.php) that records anonymous page-load counts — no file processing, no user data.

Every tool is a self-contained HTML page with its own JavaScript file. When you visit compress-pdf.html, the entire PDF compression pipeline runs in your browser using:

PDF-lib.js for PDF manipulation (compression, merging, splitting)
Canvas API for image processing (crop, resize, convert)
FFmpeg.wasm for video and audio conversion (compiled from C to WebAssembly)
Web Audio API for audio analysis (BPM detection, waveform visualization)
File System Access API for reading and writing local files

The user picks a file, the browser processes it locally, and the result is downloaded directly from memory. The file never touches a server.

WebAssembly: The Enabler

The biggest technical enabler was WebAssembly. Tools like video-to-audio conversion, audio trimming, and video-to-GIF would be impossible in a browser without it. I use FFmpeg.wasm (the WebAssembly port of FFmpeg) for all media conversion tasks.

The trade-off is size. FFmpeg.wasm adds roughly 25MB to the initial load. To mitigate this, I load it lazily — only when the user actually selects a media file. The core tool page loads instantly with a lightweight UI, and the WebAssembly module downloads in the background while the user is choosing their file.

SharedArrayBuffer is required for multi-threaded FFmpeg.wasm, which means every media tool page needs Cross-Origin Isolation headers (COOP and COEP). I handle this with a service worker (coi-serviceworker.js) that injects the required headers on the fly, so I do not need to configure Nginx for each tool individually.

The Service Worker Strategy

ToolKnit is a Progressive Web App with an aggressive caching strategy. The service worker (service-worker.js) precaches all tool pages, JavaScript files, and blog articles on install. This means:

Offline access — All tools work without an internet connection after the first visit
Instant loading — Subsequent visits load from cache, with background updates
Version management — Every deploy increments the cache version (currently toolknit-v67)

The challenge is cache invalidation. Every time I add a tool or fix a bug, I need to bump the cache version and update the PRECACHE_URLS array. Early on, I forgot to bump the version after a deploy and users were stuck with a stale version for days. Now it is part of my deployment checklist — no exceptions.

The Deployment Disaster That Changed Everything

On May 27, I made a deployment mistake that nearly destroyed the site.

I was using SCP to upload multiple files at once. Two files had the same basename but different paths: blog/index.html and the root index.html. When I ran:

scp blog/index.html tools/video-screenshot.html root@server:/www/wwwroot/toolknit.com/

The blog index.html overwrote the homepage. The blog video-screenshot.html overwrote the tool page. The entire homepage was replaced with a blog article list. The video screenshot tool was replaced with an SEO blog post.

I restored from backup within minutes, but the lesson was seared into my brain. From that day forward, my deployment rule is absolute:

One file per SCP command. Always specify the full target path. Never upload multiple files to the same directory in one command.

It is slower. It is tedious. It has prevented every deployment accident since.

The Architecture Refactor That Saved My Sanity

By June 1, I had 70 tool pages, each with an inline JavaScript array listing related tools:

var tools = [
  {n:"Compress PDF",u:"compress-pdf.html"},
  {n:"Merge PDF",u:"merge-pdf.html"},
  // ... 70 entries
];

Every time I added a new tool, I had to update this array in all 70 HTML files. That is 70 file edits per tool launch. I was spending more time updating related-tool lists than building actual tools.

So I stopped shipping features for a day and rebuilt the entire system:

Created assets/data/tools.json — a single source of truth for all tools
Created assets/js/related-tools.js — fetches the JSON and renders related tools dynamically
Removed all inline var tools=[...] arrays from 70 HTML files

Now, adding a new tool means adding one entry to tools.json. Every tool page automatically shows the updated related tools list. It was the most boring deploy I have ever made — and the most impactful.

Privacy Hardening: The Day I Scrubbed My Own Analytics

On May 26, I realized my anonymous analytics system had a flaw. The track.php script was storing raw IP addresses in daily JSON files on the server. The data was never shared, never sold, and never connected to any user identity. But it felt wrong. If I am going to claim that ToolKnit respects privacy, the analytics system should reflect that.

I spent the entire day on three changes:

Rewrote track.php to hash all IPs and visitor IDs with day-scoped SHA-256 before storage. The hash changes every day, so you cannot track a single IP across days.
Scrubbed historical data — batch-migrated all existing daily JSON files, converting 650 raw IPv4 addresses, 181 IPv6 addresses, and 763 raw UIDs into hashed values.
Saved a backup first — analytics-backup-20260526-status-scrub.tgz on the server, just in case.

No user will ever notice this change. The analytics dashboard looks identical. But I sleep better knowing there are no raw IPs sitting on my server.

Internationalization: Chinese Without a Framework

ToolKnit supports English and Chinese. I did not use i18next or any localization framework — just a simple JSON file (locales/zh.json) with translations for all tool titles and descriptions, and a lightweight i18n.js that swaps text content based on the user's language preference.

The tricky part is cache busting. When I add a new tool and its Chinese translation, I need to bump the zh.json cache version in i18n.js so the browser fetches the updated translations. Forget to bump, and Chinese users see the old tool list. I have forgotten exactly twice. Both times, I received confused emails within hours.

FIGlet Fonts and CORS: A Cautionary Tale

The most recent technical challenge was the ASCII Text Banner tool. I initially used the figlet.js library with fonts loaded from a CDN (unpkg.com). It worked perfectly in development. Then I deployed it, and every font request was blocked by CORS policy.

The fix was to download all 20 FIGlet font files (.flf) and host them locally under /assets/fonts/. Simple in hindsight, but it took me an hour of debugging to realize that unpkg.com does not set Access-Control-Allow-Origin headers for .flf files.

Lesson: always test CDN resources against CORS before deploying. Browser development servers often skip CORS checks, so everything works locally and breaks in production.

The Tech Stack Summary

Layer	Technology	Why
Frontend	Vanilla JS + Tailwind CSS	No build step, no framework overhead, fast loading
PDF	PDF-lib.js	Pure JS PDF manipulation, no server needed
Image	Canvas API	Native browser API, zero dependencies
Video/Audio	FFmpeg.wasm	WebAssembly port of FFmpeg, handles all media formats
Audio Analysis	Web Audio API + BeatDetect.js	BPM detection, waveform visualization
ASCII Art	Canvas pixel sampling	Read pixels, map brightness to characters
ASCII Banners	figlet.js + local .flf fonts	20 FIGlet fonts, CORS-safe local hosting
Caching	Service Worker (v67)	Precache all pages, offline support
i18n	JSON + custom JS	Lightweight, no framework dependency
Analytics	tracker.js + track.php (hashed IPs)	Anonymous, privacy-first
Hosting	Nginx + PHP 8.2 on BT Panel	Static files + one PHP endpoint
CDN	Cloudflare Free	DDoS protection, edge caching
PWA	manifest.json + service-worker.js	Installable, offline-capable

What I Would Do Differently

Start with a build system. I went full vanilla JS because it was fast to start. Now, with 72 tool pages and 70+ JavaScript files, I miss tree-shaking, bundling, and TypeScript type checking. A lightweight Vite setup would have saved me from several runtime bugs.
Automate deployments earlier. I deploy by running SCP commands one at a time. A CI/CD pipeline (even a simple GitHub Actions workflow) would eliminate the risk of manual deployment errors.
Test CORS from day one. The figlet.js CORS issue was entirely preventable. I should have tested all external resource loads against production CORS headers before deploying.
Hash analytics from day one. Storing raw IPs was unnecessary and created a privacy debt that took a full day to clean up. The hashed version works identically and is strictly better.

Alternatives and Related Projects

If you are interested in browser-based tool suites, here are some projects worth exploring:

Smallpdf

Polished PDF tool suite with a clean API. Great if you need server-side PDF processing or want to integrate PDF features into your own app. Their free tier is limited to 2 tasks/day.

Squoosh

Google's browser-only image compression tool. It uses WebAssembly codecs (MozJPEG, WebP, AVIF) and proves that client-side image processing can match server-side quality. A great technical reference if you are building your own image tools.

TinyWow

A broad free tool suite similar to ToolKnit in philosophy. Good for comparing approaches to the same problem — they use server-side processing while ToolKnit uses browser-only processing.

Building ToolKnit has been the most intense learning experience of my development career. Not because the technology is cutting-edge — it is not. But because the constraint of "everything must run in the browser with zero server processing" forces creative solutions that you would never discover otherwise.

If you are building something similar, or if you just want to compress a PDF without uploading it to a stranger's server, visit toolknit.com. No signup. No upload. No catch.

Written by Zihang Dong, solo developer of ToolKnit. 72 tools, 77 days, zero backend processing. Content published under CC BY-SA 4.0.

My static site's visitor counter reset to 1. Here is the deploy checklist I wish I had

Zihang Dong 董子航 — Thu, 28 May 2026 07:00:07 +0000

A few hours after a successful deploy, I opened my own site and saw the kind of number that makes you immediately stop doing everything else:

Total visits: 1

That was not a new project. It was not a fresh database. It was not supposed to say 1.

For context, I have been building 24Picture, a small browser-local image toolkit. It is mostly static HTML, CSS, JavaScript, Canvas, and a tiny PHP endpoint for visit stats. The image tools themselves do not upload files anywhere. The site is intentionally boring: static pages, shared scripts, cache-busted assets, and a full-package deploy script.

The deploy worked. The pages loaded. The new homepage shipped.

And the visitor counter reset itself.

This is the checklist I wish I had before that happened.

The setup: static site, one tiny runtime file

Most of the site is just files on disk:

public/
  index.html
  tools/*.html
  assets/js/*.js
  assets/css/*.css
  service-worker.js

There is one small exception:

public/data/visits.json

A PHP endpoint reads and writes that file:

$dataFile = __DIR__ . '/../data/visits.json';

if (!file_exists($dataFile)) {
    file_put_contents($dataFile, json_encode([
        'total' => 0,
        'today' => 0,
        'date' => date('Y-m-d'),
        'start_date' => '2026-05-01'
    ]));
}

$data = json_decode(file_get_contents($dataFile), true);

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $data['total']++;
    $data['today']++;
    file_put_contents($dataFile, json_encode($data));
}

That is fine for a tiny site. It is not pretending to be a serious analytics platform. It just gives me a basic heartbeat without shipping a large third-party analytics script.

But it also means visits.json is not source code.

It is runtime data.

And my deploy script forgot that distinction.

The bug: full replacement treated runtime data like build output

The original deploy process was simple:

Build a package locally.
Upload it to the server.
Back up the live site.
Remove the old public directory.
Extract the new package.
Fix ownership and permissions.

The dangerous part looked conceptually like this:

cp -a "$SITE_DIR" "$BACKUP_DIR"
rm -rf "$SITE_DIR/public" "$SITE_DIR/config" "$SITE_DIR/deploy"
tar -xzf "$PACKAGE_PATH" -C "$SITE_DIR"
chown -R www:www "$SITE_DIR" || true

That is a common pattern for small static sites. It keeps production from accumulating stale files. It makes deploys predictable. It avoids weird cases where a deleted local file keeps surviving online forever.

But it also deleted this:

$SITE_DIR/public/data/visits.json

On the next request, the PHP endpoint did exactly what it was written to do: it saw a missing file, recreated it from zero, and then incremented it.

So production proudly reported:

{"total":1,"today":1}

The code was not broken. The deploy model was incomplete.

Fix #1: restore from the highest trustworthy backup

The first step was not changing code. It was recovering the most trustworthy data.

Because the deploy script created full backups before replacing the site, I could inspect older backup directories and compare their public/data/visits.json files.

The highest trustworthy pre-reset value was:

{
  "total": 175,
  "today": 7,
  "date": "2026-05-28",
  "start_date": "2026-05-01"
}

I restored that exact JSON to production, fixed ownership, and verified the API returned the expected value.

The important detail: do not restore from the newest backup blindly.

After a reset happens, later backups may contain the already-corrupted value. In my case, some newer backups contained reset-derived counts. The right source was the newest backup from before the reset, not simply the latest backup on disk.

Fix #2: preserve runtime data during full deploys

The actual deploy fix was small.

After creating the backup, I record the old runtime data path:

cp -a "$SITE_DIR" "$BACKUP_DIR"
printf '%s' "$BACKUP_DIR" > "$LAST_BACKUP_FILE"
RUNTIME_DATA_BACKUP="${BACKUP_DIR}/public/data"

Then I still do the full replacement:

rm -rf "$SITE_DIR/public" "$SITE_DIR/config" "$SITE_DIR/README.md" "$SITE_DIR/.gitignore" "$SITE_DIR/deploy"
tar -xzf "$PACKAGE_PATH" -C "$SITE_DIR"

But immediately after extraction, I copy the runtime data back:

if [ -d "$RUNTIME_DATA_BACKUP" ]; then
  mkdir -p "$SITE_DIR/public/data"
  cp -a "$RUNTIME_DATA_BACKUP/." "$SITE_DIR/public/data/"
fi

chown -R www:www "$SITE_DIR" || true

Now full deploys still remove stale build output, but they no longer erase production-owned state.

That is the rule I should have written down earlier:

Full deploys may replace build artifacts. They must not replace runtime data unless that is an explicit migration.

Fix #3: make the deploy script prove it is safe

A deploy script is production code. It deserves at least a syntax check.

Before trusting the new version, I ran:

bash -n /root/server-deploy.sh

Then after the next deploy, I checked the file directly:

cat /www/wwwroot/24picture.com/public/data/visits.json

And checked the public endpoint:

https://example.com/api/visit.php

The post-deploy rule is now simple:

If total or today unexpectedly returns to 0 or 1, stop.
Do not keep deploying.
Check runtime data before touching anything else.

That sounds obvious after the incident. It was not in my checklist before the incident.

The cache lesson from the same release

The same release also touched the homepage and language switching. That created a different kind of deployment risk: cache visibility.

A user clicking ?lang=zh but still seeing English is not a small i18n bug from their point of view. It looks like the site is ignoring them.

On a static site with a Service Worker, cache-busting needs to be specific. I ended up treating assets differently based on where they live:

Shell-level assets need a Service Worker cache version bump.
Shared JavaScript files need changed query strings in the HTML that references them.
CSS-only hotfixes can often be isolated to the affected page or stylesheet reference.
Shared data files need every consuming page to reference the new version if you want the update visible immediately.

For example:

<script src="/assets/js/i18n.js?v=1.8.14"></script>
<link rel="stylesheet" href="/assets/css/main-new.css?v=1.8.15">
<script src="/assets/js/changelog-data.js?v=1.8.15"></script>

I wrote a short public changelog entry for the release because this kind of tiny infrastructure work is easy to forget. The code change may be one line, but the operational lesson is much bigger.

My new tiny-site deploy checklist

Here is the checklist I am using now.

1. Classify every path before deleting anything

Before a full replacement deploy, split files into categories:

build artifacts:
  public/*.html
  public/assets/**
  public/tools/**

runtime data:
  public/data/visits.json
  uploads/
  cache/
  queues/
  generated reports
  anything written by production code

secrets/config:
  .env
  config/*.php
  server-only keys

If a production process writes it, the deploy script should not casually delete it.

2. Preserve runtime data explicitly

Do not rely on “it is probably in the package” or “the backup exists somewhere.”

Make the restore step part of the deploy script:

RUNTIME_DATA_BACKUP="${BACKUP_DIR}/public/data"

# after extracting the new package
if [ -d "$RUNTIME_DATA_BACKUP" ]; then
  mkdir -p "$SITE_DIR/public/data"
  cp -a "$RUNTIME_DATA_BACKUP/." "$SITE_DIR/public/data/"
fi

Explicit beats remembered.

3. Verify the values users can see

Do not only check whether the deploy command exited successfully.

Check the thing the user will notice:

Homepage loads
Language switch renders the expected language
Changelog shows the newest version
Visitor stats did not reset
Critical assets use the new cache-busted URL

A deploy that returns DEPLOY_OK can still ship a bad state.

4. Keep one small audit script per scary class of bug

I now prefer small, boring verification scripts over trying to remember every edge case manually.

Examples:

verify homepage i18n keys
scan changelog asset versions
check broken internal links
check missing hreflang tags
scan for mojibake signatures
verify visit stats after deploy

The best audit scripts are not clever. They are just executable memory.

5. Write the postmortem while it is still embarrassing

This is the part I recommend most.

When the bug still feels annoying, write down:

what happened
why it happened
what file caused it
what exact check would have caught it
what rule changes now

A week later, you will remember “the stats bug.” You may not remember the exact path, command, backup, and prevention rule.

Future-you needs the boring details.

A small ask

One practical problem with small independent tools is discovery. Search engines trust links, and new projects do not have many.

If you maintain a list of privacy-friendly tools, browser-based utilities, frontend resources, or “no upload” image tools, and you think this project belongs there, a mention or backlink to 24Picture's zero-upload image tools would genuinely help.

No pressure, and please do not link it if it is not useful for your audience. But if it fits, that kind of independent web curation is still one of the best ways small tools get found.

I am also happy to look at useful directories, resource lists, or indie tool pages in return. Good lists deserve links too.

Wrap

The bug was small. One JSON file disappeared.

But the lesson was bigger: static deploys are only simple if everything is actually static.

The moment a production process writes a file, even a tiny one, your deploy script has to treat it as state. If it does not, the script is not just deploying your site. It is editing your production data model.

And sometimes the first sign is a very loud number:

I shipped 29 browser-only image tools. These 5 boring patterns kept the codebase sane

Zihang Dong 董子航 — Wed, 27 May 2026 03:10:07 +0000

I thought building browser-only image tools would mostly be about Canvas APIs and file formats.

It wasn’t.

The hard part started after tool #3, then tool #12, then tool #29: shared logic that wanted to fork, decoder libraries that were too expensive to load everywhere, export bugs that only showed up on transparent images, hash links that broke on real version IDs, and “fixed” assets that users still couldn’t see because cache visibility was treated as an afterthought.

For the past few weekends I’ve been shipping 24Picture, a free browser-local image toolkit. The stack is intentionally boring: static HTML, ES2020 JavaScript, Canvas, and a few route-specific decoders. No backend image processing. No uploads. Just a growing set of small tools that all need to feel consistent, stay fast, and survive hotfixes without turning into a pile of one-off exceptions.

Here are five patterns that actually held up.

1. One shared dispatcher beats cloned tool logic

The first few tools tempted me into the usual trap: one page, one script, one slightly different copy of the same workflow. That feels harmless at tool #2. By tool #10, it becomes a maintenance tax. By tool #29, it means every upload rule, MIME check, preview behavior, download naming fix, and UX improvement has to be rediscovered in multiple places.

The pattern that held up was much less exciting: one shared dispatcher and one route-to-format matrix.

const ROUTE_MATRIX = {
  'webp-to-png':  { input: ['image/webp'], outputMime: 'image/png',  ext: 'png'  },
  'webp-to-jpg':  { input: ['image/webp'], outputMime: 'image/jpeg', ext: 'jpg'  },
  'png-to-jpg':   { input: ['image/png'],  outputMime: 'image/jpeg', ext: 'jpg'  },
  'tiff-to-jpg':  { input: ['image/tiff'], outputMime: 'image/jpeg', ext: 'jpg', decoder: decodeTiff },
  'tiff-to-png':  { input: ['image/tiff'], outputMime: 'image/png',  ext: 'png', decoder: decodeTiff },
  'ico-to-png':   {
    input: ['image/x-icon', 'image/vnd.microsoft.icon'],
    outputMime: 'image/png',
    ext: 'png',
    decoder: decodeIco
  },
  // …29 routes
};

Each tool page sets a route hint like <body data-route="tiff-to-jpg">, and the shared script looks up its row at boot. Adding a new converter becomes “one HTML page + one matrix row” instead of “copy three files and hope nothing drifted.”

The real win isn’t lines saved. It’s that drag-drop, preview, validation, download naming, empty-state copy, and error handling all live in one place. When a UX bug shows up, I fix it once and 29 tools inherit it.

If the user experience is the same, the code path should probably be shared too.

2. Lazy-load the expensive decoders, not the whole site

Not every browser image format is created equal. Some tools only need Canvas. Others need heavier decoders for formats like HEIC, TIFF, or ICO. The mistake would have been treating those libraries as “site-wide JavaScript” and making every visitor pay for them on first load.

Some of the specialized libraries are big enough to matter:

Library	Size	When you actually need it
`heic2any`	~1.3 MB	only on HEIC tools
`UTIF.js` + `pako_inflate`	~79 KB	only on TIFF tools
`icojs`	~11 KB	only on the ICO tool

The better rule was simple: if only a small slice of pages needs a decoder, only those pages should load it.

<!-- tools/tiff-to-jpg.html -->
<script src="/assets/vendor/pako/pako_inflate.min.js"></script>
<script src="/assets/vendor/utif/UTIF.js"></script>
<script src="/assets/js/tool-page.js?v=1.8.0"></script>

The shared dispatcher only invokes a decoder when its route declares one. The homepage stays lighter, the general tools stay decoder-free, and specialized features stop dragging the entire site down with them.

Don’t let your homepage pay the bundle tax for edge-case formats.

3. JPG export needs a deliberate transparency policy

One of the most boring bugs turned out to be one of the most user-visible: exporting transparent images to JPG. If you don’t make the background policy explicit, the result is whatever the browser gives you — and that often means black where users expected white.

The fix is tiny, but the rule matters more than the code.

function exportJpg(srcCanvas) {
  const c = document.createElement('canvas');
  c.width = srcCanvas.width;
  c.height = srcCanvas.height;
  const ctx = c.getContext('2d');

  ctx.fillStyle = '#ffffff';
  ctx.fillRect(0, 0, c.width, c.height);
  ctx.drawImage(srcCanvas, 0, 0);

  return new Promise(resolve => c.toBlob(resolve, 'image/jpeg', 0.92));
}

The lesson wasn’t just “remember to fill white first.” The real lesson was that format-specific assumptions should never be scattered across multiple tools. If JPG export has a quirk, centralize that logic once and make every *-to-jpg page inherit it.

Format quirks become production bugs when they’re duplicated instead of standardized.

4. A harmless-looking `querySelector()` can break production navigation

Some bugs don’t look like bugs until real data hits them. One production example came from a public changelog with version IDs like v1.7.2. The smooth-scroll handler fed the raw href straight into querySelector().

// 🔥 will throw on hashes like #v1.7.2
document.querySelectorAll('a[href^="#"]').forEach(a => {
  a.addEventListener('click', e => {
    e.preventDefault();
    const t = document.querySelector(a.getAttribute('href'));
    if (t) t.scrollIntoView({ behavior: 'smooth' });
  });
});

That looked fine until the real IDs contained dots. Then the page started throwing:

Uncaught SyntaxError: Failed to execute 'querySelector' on 'Document':
'#v1.7.2' is not a valid selector.

In CSS, . is a class delimiter, so #v1.7.2 isn’t interpreted as a literal ID. It’s interpreted as something structurally different — and invalid for this case.

The safer fix was to stop being clever:

const t = document.getElementById(href.slice(1));

If I really needed selector semantics, CSS.escape() would also work. But this bug was a good reminder that production identifiers are rarely as clean as demo values. The more direct DOM API is often the more robust one.

Real production IDs don’t care whether your selector assumptions are elegant.

5. Shared asset hotfixes need a visibility strategy, not just cache busting

One of the most frustrating classes of bugs is the kind you already fixed, deployed, and still can’t reliably show to users. On a static site with shared JavaScript, “the file changed” is not the same thing as “the update is visible.”

The reason is that not every shared asset lives in the same caching layer. Some resources are effectively part of your shell and Service Worker lifecycle. Others are just shared runtime files referenced by many HTML pages. Treating both cases as the same problem leads to half-fixes.

For shell-level changes, a Service Worker version bump is still the right lever:

// public/service-worker.js
const VERSION = 'v1.8.11';
const SHELL_CACHE = `app-shell-${VERSION}`;
const RUNTIME_CACHE = `app-runtime-${VERSION}`;

But for non-precached shared assets, visibility often comes from changing the referenced URL and deploying the HTML that points to it:

<script src="/assets/js/changelog-data.js?v=1.8.12"></script>

That distinction mattered a lot on a multi-language static site. A shared data file can be perfectly updated on origin and still appear “stuck” if many pages continue referencing the old path, or if intermediate caches never see a URL change. The question that finally improved hotfix reliability wasn’t “did I bust cache?” It was: which layer is caching this file, which pages reference it, and what exactly has to change before a user can observe the fix?

A hotfix is only real when users can actually see it.

Wrap

None of these patterns are especially novel. That’s exactly why they were worth keeping.

When you ship a lot of small browser tools, the flashy part usually isn’t the hard part. The hard part is making sure the same rules still hold when the codebase grows, when shared assets change, and when one tiny bug suddenly affects twenty pages instead of two.

That’s what made the boring patterns valuable: they kept the project moving without demanding a rewrite every time a new tool or edge case showed up.

Shipping 28 browser-only image tools: 5 patterns from a quiet weekend project

Zihang Dong 董子航 — Sat, 23 May 2026 10:02:52 +0000

Five concrete patterns from building a no-upload, browser-local image toolkit — a single dispatcher for many converters, lazy-loaded decoders, transparency-safe JPG export, a subtle querySelector trap, and the cache-busting recipe that finally made hotfixes feel atomic.

For the past few weekends I've been quietly shipping a free, browser-local image toolkit called 24Picture. No uploads, no accounts, no servers — every conversion, resize, crop, watermark, and GIF builder runs on the user's own device.

The codebase is intentionally boring: plain HTML, ES2020 JavaScript, and Canvas. Nothing fancy. But after shipping 28 tools and ~30 supporting blog posts in five languages, a few patterns have proved themselves over and over — and a few traps have bitten me in ways that produced surprisingly weird bugs.

Here are five of those patterns. They're worth stealing if you're building anything that ships a lot of small browser tools, processes user files locally, or just wants to keep a healthy Lighthouse score without becoming a build-tooling project.

1. One shared dispatcher beats N copies of similar tool code

I originally hand-wrote a converter file per pair of formats. After the third one I gave up.

Now there's a single tool-page.js that holds a tiny route → format-matrix table:

const ROUTE_MATRIX = {
  'webp-to-png':  { input: ['image/webp'], outputMime: 'image/png',  ext: 'png'  },
  'webp-to-jpg':  { input: ['image/webp'], outputMime: 'image/jpeg', ext: 'jpg'  },
  'png-to-jpg':   { input: ['image/png'],  outputMime: 'image/jpeg', ext: 'jpg'  },
  'tiff-to-jpg':  { input: ['image/tiff'], outputMime: 'image/jpeg', ext: 'jpg', decoder: decodeTiff },
  'tiff-to-png':  { input: ['image/tiff'], outputMime: 'image/png',  ext: 'png', decoder: decodeTiff },
  'ico-to-png':   { input: ['image/x-icon', 'image/vnd.microsoft.icon'],
                    outputMime: 'image/png', ext: 'png', decoder: decodeIco },
  // …28 entries
};

Each tool page sets <body data-route="tiff-to-jpg"> and the dispatcher looks up its row at boot. Adding a new tool is one line + one tool HTML page.

The real win isn't lines saved — it's that the upload zone, preview, MIME validation, batch download UX, drag-drop hints, and download naming convention all live in one place. No duplicated bug fixes. When you find a UX flaw, you fix it 28 times by editing one file.

2. Lazy-load heavy decoders only on the pages that need them

Some browser image libraries are huge:

Library	Size	When you actually need it
`heic2any`	~1.3 MB	only on HEIC tools
`UTIF.js` + `pako_inflate`	~79 KB	only on TIFF tools
`icojs`	~11 KB	only on the ICO tool

If I had loaded all of these globally on every page, the homepage would have paid a 1.5 MB tax for a feature 95% of users will never touch.

Instead, each tool HTML pulls only its own decoder:

<!-- tools/tiff-to-jpg.html -->
<script src="/assets/vendor/pako/pako_inflate.min.js"></script>
<script src="/assets/vendor/utif/UTIF.js"></script>
<script src="/assets/js/tool-page.js?v=1.8.0"></script>

The shared dispatcher only invokes a decoder when its row declares one. The rest of the site stays decoder-free.

If you go this route, host the libraries yourself (/assets/vendor/<lib>/…) rather than relying on a third-party CDN. The whole point of a "no upload, runs locally" tool is undermined the moment you start fanning out to ten random origins on first paint.

3. Always flatten transparency before exporting JPG

This one is mundane but I caught myself making the mistake twice. JPG has no alpha channel, so if you draw a PNG with transparent areas straight to a canvas and call toBlob('image/jpeg'), you get black, not white, in most browsers.

The fix is one extra rectangle:

function exportJpg(srcCanvas) {
  const c = document.createElement('canvas');
  c.width  = srcCanvas.width;
  c.height = srcCanvas.height;
  const ctx = c.getContext('2d');

  // Paint white first — transparent source pixels otherwise become black in JPG.
  ctx.fillStyle = '#ffffff';
  ctx.fillRect(0, 0, c.width, c.height);
  ctx.drawImage(srcCanvas, 0, 0);

  return new Promise(res => c.toBlob(res, 'image/jpeg', 0.92));
}

Wrap it in a single helper and call it from every *-to-jpg tool. Pick a quality (0.85–0.92 is a safe sweet spot for photos), and stop worrying about it.

4. Don't pass `href` straight into `querySelector` for hash anchors

This bug shipped to production for several days before I noticed it. The site has a /changelog/ page with version IDs like v1.7.2. The smooth-scroll handler was:

// 🔥 will throw on click for ANY hash containing a dot
document.querySelectorAll('a[href^="#"]').forEach(a => {
  a.addEventListener('click', e => {
    e.preventDefault();
    const t = document.querySelector(a.getAttribute('href'));
    if (t) t.scrollIntoView({ behavior: 'smooth' });
  });
});

Clicking the sidebar #v1.7.2 link blew up the page with:

Uncaught SyntaxError: Failed to execute 'querySelector' on 'Document':
'#v1.7.2' is not a valid selector.

In CSS, . is a class delimiter, so #v1.7.2 is parsed as "element with ID v1 that also has classes 7 and 2" — structurally invalid.

Two fixes that always work:

// Preferred: skip CSS entirely for hash anchors
const t = document.getElementById(href.slice(1));

// Or, if you really need a selector, escape it
const t = document.querySelector('#' + CSS.escape(href.slice(1)));

I now grep the whole codebase for querySelector(.*getAttribute\(.href before every release, and the rule is written into our skill docs so it never sneaks back in.

5. When you change a shared asset, bump the Service Worker AND add `?v=`

The site's Service Worker uses stale-while-revalidate for static assets — fast for users, but it means an old cached i18n.js can hang around for a long visit. Worse, edge / origin caches can hold on to the path-without-query independently.

The cheapest belt-and-suspenders recipe:

// public/service-worker.js
const VERSION = 'v1.8.3'; // bump this on shared asset changes
const SHELL_CACHE   = `app-shell-${VERSION}`;
const RUNTIME_CACHE = `app-runtime-${VERSION}`;

<!-- referencing HTML -->
<script src="/assets/js/i18n.js?v=1.8.3"></script>

The pattern, every time:

Edit the shared JS/CSS.
Bump VERSION in the service worker.
Update the ?v= query string on every page that references the file.

The SW bump invalidates RUNTIME_CACHE on next activate. The ?v= busts any intermediate cache by changing the URL. Either one alone leaves a long tail of stale clients; the two together are what finally made hotfixes feel atomic on a multi-language static site.

Bonus tip: also wire the SW registration itself to a versioned URL so a stale /service-worker.js response can't keep an old SW alive:

// pwa-install.js
const SW_VERSION = '1.8.1';
navigator.serviceWorker.register(`/service-worker.js?v=${SW_VERSION}`);

Wrap

None of these patterns are clever. They're just the boring tools that have actually kept the project moving on weekend after weekend, while shipping 28 tools across 5 languages without a backend.

If you want to see them in production, the whole toolkit is browser-local and free, and the changelog literally documents the version where each of these patterns was learned the hard way (including v1.8.2, the "querySelector hash" release).

Happy shipping — and may all your weekend projects compile in the browser. 🛠️

Canvas 2D API is Underrated — 5 Real Tools I Built With It

Zihang Dong 董子航 — Fri, 22 May 2026 16:31:33 +0000

Most web developers reach for heavy libraries the moment they need to do anything visual. Need a chart? Chart.js. Image editing? Fabric.js. PDF export? html2canvas.

I've been building ToolKnit — a suite of 62 free browser-based tools — and I kept running into the same realization: the native Canvas 2D API can do way more than people think. No npm install, no bundle size, no compatibility issues. Just getContext('2d') and go.

Here are five real, production tools I built using nothing but vanilla Canvas 2D.

1. Signature Pad — Draw, Trim, Export Transparent PNG

Tool: Signature Maker

The most recent one. Users draw their signature with mouse/touch/stylus, and download it as a transparent PNG — ready to paste into documents.

The core drawing loop

canvas.addEventListener('mousedown', (e) => {
  drawing = true;
  saveState(); // push to undo stack
  const pos = getPos(e);
  lastX = pos.x;
  lastY = pos.y;
});

canvas.addEventListener('mousemove', (e) => {
  if (!drawing) return;
  const pos = getPos(e);
  ctx.strokeStyle = penColor;
  ctx.lineWidth = penSize;
  ctx.lineCap = 'round';
  ctx.lineJoin = 'round';
  ctx.beginPath();
  ctx.moveTo(lastX, lastY);
  ctx.lineTo(pos.x, pos.y);
  ctx.stroke();
  lastX = pos.x;
  lastY = pos.y;
});

Nothing revolutionary — but the magic is in what happens after drawing.

Auto-trimming transparent pixels

When the user downloads, I scan every pixel to find the bounding box of the actual signature, then crop:

function trimCanvas(source) {
  const { width: w, height: h } = source;
  const data = source.getContext('2d')
    .getImageData(0, 0, w, h).data;

  let top = h, left = w, right = 0, bottom = 0;

  for (let y = 0; y < h; y++) {
    for (let x = 0; x < w; x++) {
      if (data[(y * w + x) * 4 + 3] > 0) { // alpha > 0
        if (y < top) top = y;
        if (y > bottom) bottom = y;
        if (x < left) left = x;
        if (x > right) right = x;
      }
    }
  }

  const out = document.createElement('canvas');
  out.width = right - left + 20;  // 10px padding each side
  out.height = bottom - top + 20;
  out.getContext('2d').drawImage(
    source, left - 10, top - 10, out.width, out.height,
    0, 0, out.width, out.height
  );
  return out;
}

The output is a tight, transparent PNG — no white box, no wasted space. Works perfectly when overlaid on PDFs or documents.

HiDPI support

One gotcha: on Retina/HiDPI screens, the canvas looks blurry if you don't account for devicePixelRatio:

const dpr = window.devicePixelRatio || 1;
const rect = canvas.getBoundingClientRect();
canvas.width = rect.width * dpr;
canvas.height = rect.height * dpr;
ctx.scale(dpr, dpr);
canvas.style.width = rect.width + 'px';
canvas.style.height = rect.height + 'px';

This makes the internal resolution match the physical pixels. Lines look crisp on every screen.

2. AI Background Remover — Mask Painting with Canvas

Tool: Background Remover (open-sourced)

An ONNX neural network removes the background automatically (via WebAssembly). But the AI isn't perfect — especially around hair, transparent objects, or complex edges.

So I added a manual refinement mode: paint on a mask canvas with a brush (restore) or eraser (remove).

Dual-canvas compositing

Layer 1: Original image (never modified)
Layer 2: Mask canvas (white = keep, black = remove)
Layer 3: Preview canvas (composited result)

The brush paints directly on the mask:

function paintOnMask(x, y) {
  maskCtx.globalCompositeOperation =
    currentTool === 'brush' ? 'source-over' : 'destination-out';
  maskCtx.strokeStyle = '#fff';
  maskCtx.lineWidth = brushSize;
  maskCtx.lineCap = 'round';
  maskCtx.beginPath();
  maskCtx.moveTo(lastX, lastY);
  maskCtx.lineTo(x, y);
  maskCtx.stroke();
}

Then the preview composites original × mask in real-time:

function renderPreview() {
  previewCtx.clearRect(0, 0, w, h);
  // Draw checkered background (transparency indicator)
  drawCheckerboard(previewCtx, w, h);
  // Apply mask: only show original where mask is white
  previewCtx.globalCompositeOperation = 'source-over';
  previewCtx.drawImage(originalCanvas, 0, 0);
  previewCtx.globalCompositeOperation = 'destination-in';
  previewCtx.drawImage(maskCanvas, 0, 0);
}

destination-in is the key — it keeps original pixels only where the mask has alpha. Pure Canvas compositing, zero libraries.

3. Pixel Art Converter — Quantization & Palette Mapping

Tool: Pixel Art Converter

Upload a photo, get retro pixel art. The algorithm:

Downscale to target pixel size (e.g., 64×64)
Color quantize to a limited palette (8, 16, 32 colors)
Upscale with nearest-neighbor (no anti-aliasing)

Nearest-neighbor upscaling

Browsers default to bilinear interpolation when scaling canvas images. For pixel art, you need hard edges:

ctx.imageSmoothingEnabled = false;
ctx.drawImage(smallCanvas, 0, 0, 64, 64, 0, 0, 512, 512);

One line — imageSmoothingEnabled = false — turns a blurry mess into crisp pixel art. This single property makes the Canvas API viable for an entire category of retro image tools.

Color palette mapping

For each pixel, I find the closest color in the target palette using Euclidean distance in RGB space:

function nearestColor(r, g, b, palette) {
  let minDist = Infinity, best = palette[0];
  for (const c of palette) {
    const dr = r - c[0], dg = g - c[1], db = b - c[2];
    const dist = dr * dr + dg * dg + db * db;
    if (dist < minDist) { minDist = dist; best = c; }
  }
  return best;
}

Process every pixel with getImageData / putImageData, and the entire conversion runs in a single frame on most devices.

4. Daily Planner — PDF/PNG Export via Pure Canvas Drawing

Tool: Daily Planner

Users fill out a daily schedule in the browser. They can export it as a pixel-perfect PNG or PDF. My first attempt used html2canvas to screenshot the DOM.

Why html2canvas failed

html2canvas re-implements CSS rendering in JavaScript. It doesn't use the browser's actual layout engine. The result:

flexbox alignment was off by 2-3px
margin: auto centering didn't work
Font rendering differed subtly
Every CSS fix I made for html2canvas broke the live preview

After hours of fighting, I threw it away and drew everything manually with Canvas 2D.

Direct Canvas rendering

async function renderToCanvas(data) {
  const canvas = document.createElement('canvas');
  canvas.width = 1200;
  canvas.height = 1600;
  const ctx = canvas.getContext('2d');

  // Wait for fonts
  await document.fonts.ready;

  // Background
  ctx.fillStyle = '#0a0a0a';
  ctx.fillRect(0, 0, 1200, 1600);

  // Title — perfectly centered
  ctx.font = '700 36px "Space Grotesk"';
  ctx.fillStyle = '#ffffff';
  ctx.textAlign = 'center';
  ctx.fillText(data.title, 600, 80);

  // Time slots — precise positioning
  let y = 140;
  for (const slot of data.slots) {
    ctx.font = '600 16px "Space Grotesk"';
    ctx.fillStyle = 'rgba(255,255,255,0.5)';
    ctx.textAlign = 'left';
    ctx.fillText(slot.time, 60, y);

    ctx.fillStyle = '#fff';
    ctx.fillText(slot.task, 180, y);
    y += 44;
  }

  return canvas;
}

Zero rendering discrepancies. The PNG/PDF output matches exactly what the user sees — because I control every pixel. The lesson: if you need pixel-perfect export, skip DOM-to-canvas libraries and draw directly.

5. AI to PNG — Rendering Vector Files via Canvas

Tool: AI to PNG (open-sourced)

Adobe Illustrator .ai files saved with PDF compatibility can be parsed by pdf.js. Each page/artboard gets rendered to a Canvas:

const page = await pdfDoc.getPage(pageNum);
const viewport = page.getViewport({ scale: 2.0 });

const canvas = document.createElement('canvas');
canvas.width = viewport.width;
canvas.height = viewport.height;

await page.render({
  canvasContext: canvas.getContext('2d'),
  viewport: viewport
}).promise;

// Now canvas contains the rendered artboard
canvas.toBlob(blob => {
  // Download as PNG or add to ZIP
}, 'image/png');

The Canvas is the final rendering target — pdf.js draws vector paths, text, and embedded images onto it. The user gets a high-resolution PNG without ever installing Adobe software.

For batch exports (multiple artboards), each canvas gets converted to a blob and packed into a ZIP using JSZip — all in the browser.

Why Canvas 2D Over Libraries?

Concern	Library	Canvas 2D
Bundle size	50-500 KB	0 KB (native)
Browser support	Varies	Universal (IE9+)
Rendering accuracy	Approximation	Exact
Learning curve	API-specific	One API for everything
Touch/mobile	Often buggy	Native support

I'm not saying never use libraries. But before you npm install, ask: can Canvas 2D do this natively? You'll be surprised how often the answer is yes.

The Pattern

Every tool above follows the same architecture:

User Input → Canvas Processing → Blob Export → Download/Clipboard

No server. No upload. No framework. Just the browser doing what it was built for.

All 62 tools are free at toolknit.com. Background Remover and AI to PNG are open-sourced on GitHub.

If you've built something cool with Canvas 2D, I'd love to hear about it in the comments.

I Open-Sourced a Browser-Based AI Background Remover — Here's the Full Architecture

Zihang Dong 董子航 — Wed, 20 May 2026 03:30:59 +0000

Most background removal tools work like this: upload your photo to a server, wait for an AI model to process it, download the result. Your image sits on someone else's infrastructure. You hope they delete it.

I built one that works differently. The AI model runs in your browser tab. Your image never leaves your device. And I just open-sourced the core logic — two files, zero dependencies beyond a CDN import.

Here's how it works under the hood.

The Pipeline

The full flow from "user drops an image" to "transparent PNG download" goes through five stages:

Upload → ONNX Model Load → WebAssembly Inference → Mask Generation → Canvas Compositing

Each stage runs entirely client-side. Let me walk through them.

Stage 1: Loading the AI Model in the Browser

The backbone is @imgly/background-removal, an open-source library that bundles an ONNX segmentation model with ONNX Runtime Web (WebAssembly backend).

const LIB_CDN = 'https://cdn.jsdelivr.net/npm/@imgly/background-removal@1.5.5';

async function loadLibrary() {
  const module = await import(LIB_CDN + '/+esm');
  removeBackgroundFn = module.removeBackground;
}

The first call downloads ~40MB of model weights. That sounds heavy, but:

The browser caches it automatically
Subsequent uses load instantly from cache
No server round-trip on any future use

This is the same trade-off FFmpeg.wasm makes — big initial download, but then your browser becomes a local processing powerhouse.

Stage 2: Running AI Inference Locally

Once the model is loaded, inference is straightforward:

const imageBlob = await new Promise(r => canvas.toBlob(r, 'image/png'));

const resultBlob = await removeBackgroundFn(imageBlob, {
  model: 'medium',
  output: { format: 'image/png' },
  progress: (key, current, total) => {
    // Update loading UI
  }
});

What's happening behind the scenes:

The library resizes your image to the model's input dimensions
Pixel data is converted to a tensor
ONNX Runtime Web runs the segmentation model via WebAssembly
The output tensor (a per-pixel foreground probability map) is converted back to an image with transparent background

The medium model balances quality and speed. On a decent laptop, inference takes 2-5 seconds for a typical photo. On a phone, maybe 8-15 seconds. Acceptable for a free, private tool.

Stage 3: Building the Editable Mask

Here's where it gets interesting. The AI output isn't final — it's a starting point. I extract the alpha channel from the AI result and build an editable grayscale mask:

async function buildMaskFromResult() {
  const w = originalImage.naturalWidth;
  const h = originalImage.naturalHeight;

  // Draw AI result to a temporary canvas
  const resultCanvas = document.createElement('canvas');
  resultCanvas.width = w;
  resultCanvas.height = h;
  const rCtx = resultCanvas.getContext('2d');
  rCtx.drawImage(resultImg, 0, 0);
  const resultData = rCtx.getImageData(0, 0, w, h);

  // Extract alpha channel → grayscale mask
  // White = foreground (keep), Black = background (remove)
  maskCanvas = document.createElement('canvas');
  maskCanvas.width = w;
  maskCanvas.height = h;
  maskCtx = maskCanvas.getContext('2d');
  const maskData = maskCtx.createImageData(w, h);

  for (let i = 0; i < resultData.data.length; i += 4) {
    const alpha = resultData.data[i + 3];
    maskData.data[i] = alpha;     // R
    maskData.data[i + 1] = alpha; // G
    maskData.data[i + 2] = alpha; // B
    maskData.data[i + 3] = 255;   // A (mask itself is always opaque)
  }
  maskCtx.putImageData(maskData, 0, 0);
}

Why a separate mask canvas?

Because users need to fix the AI's mistakes. Hair edges, transparent objects, similar-colored backgrounds — no AI gets these perfect 100% of the time. The mask canvas becomes a paintable surface.

Stage 4: Manual Refinement with Brush & Eraser

This is the feature that separates a toy demo from a usable tool. Users can:

Brush (paint white on mask) → restore foreground areas the AI removed
Eraser (paint black on mask) → remove background areas the AI missed

function paintOnMask(e) {
  const rect = editCanvas.getBoundingClientRect();
  const x = (e.clientX - rect.left) / rect.width * maskCanvas.width;
  const y = (e.clientY - rect.top) / rect.height * maskCanvas.height;

  const brushSize = parseInt(brushSizeEl.value);
  const softness = parseInt(brushSoftEl.value) / 100;

  maskCtx.lineCap = 'round';
  maskCtx.lineWidth = brushSize;

  // Softness = CSS filter blur on the mask canvas context
  if (softness > 0) {
    maskCtx.filter = `blur(${Math.round(brushSize * softness * 0.3)}px)`;
  }

  if (currentTool === 'brush') {
    maskCtx.globalCompositeOperation = 'lighter';
    maskCtx.strokeStyle = '#ffffff';
  } else {
    maskCtx.globalCompositeOperation = 'source-over';
    maskCtx.strokeStyle = '#000000';
  }

  maskCtx.beginPath();
  maskCtx.moveTo(lastX, lastY);
  maskCtx.lineTo(x, y);
  maskCtx.stroke();
}

Key details:

Coordinate mapping: The edit canvas is CSS-scaled to fit the viewport, but the mask operates at full image resolution. Every mouse position gets mapped from display coordinates to mask coordinates.
Edge softness: Uses Canvas 2D filter: blur() on the stroke — this creates feathered edges instead of hard cuts.
Undo stack: Each mousedown saves a full ImageData snapshot of the mask. Up to 20 undo levels.

The brush cursor is a position: fixed div that follows the mouse, sized to match the display-scaled brush diameter. The actual canvas cursor is set to none.

Stage 5: Compositing the Final Output

To generate the downloadable PNG, the mask is applied to the original image:

function applyMaskToOriginal() {
  const origData = origCtx.getImageData(0, 0, w, h);
  const mData = maskCtx.getImageData(0, 0, w, h);
  const outData = oCtx.createImageData(w, h);

  for (let i = 0; i < origData.data.length; i += 4) {
    outData.data[i] = origData.data[i];       // R — original
    outData.data[i + 1] = origData.data[i + 1]; // G — original
    outData.data[i + 2] = origData.data[i + 2]; // B — original
    outData.data[i + 3] = mData.data[i];       // A — from mask R channel
  }

  oCtx.putImageData(outData, 0, 0);
  return outCanvas;
}

The mask's R channel (which equals G and B since it's grayscale) becomes the alpha channel of the output. White mask pixels → fully opaque. Black → fully transparent. Gray → semi-transparent (useful for hair and soft edges).

The Refine Mode Overlay

In refine mode, users see the original image with a semi-transparent red overlay on removed areas:

function renderMaskOverlay() {
  editCtx.drawImage(maskCanvas, 0, 0, dw, dh);
  const overlayData = editCtx.getImageData(0, 0, dw, dh);

  for (let i = 0; i < overlayData.data.length; i += 4) {
    const maskVal = overlayData.data[i];
    if (maskVal < 128) {
      // Removed area → semi-transparent red
      overlayData.data[i] = 220;     // R
      overlayData.data[i + 1] = 50;  // G
      overlayData.data[i + 2] = 50;  // B
      overlayData.data[i + 3] = 120; // A
    } else {
      // Kept area → fully transparent (show original underneath)
      overlayData.data[i + 3] = 0;
    }
  }
  editCtx.putImageData(overlayData, 0, 0);
}

This gives immediate visual feedback — you can see exactly what the AI removed and paint corrections in real time.

Performance Considerations

Memory: Three full-resolution canvases live in memory (original, mask, output). For a 4000×3000 photo, that's ~144MB of pixel data. Mobile devices with <4GB RAM may struggle.
Real-time rendering: Every brush stroke triggers renderPreview() via requestAnimationFrame. This redraws the preview canvas + overlay from the mask. On large images, there's a noticeable lag.
Touch support: Full touch event handling with passive: false to prevent scroll interference.

What I Stripped for the Open-Source Version

The production version on ToolKnit includes:

Daily usage limits (fair-use throttling)
Analytics tracking
Self-hosted model weights (faster loading from our CDN)
Sound effects on completion
Site navigation and SEO shell

The open-source version strips all of that down to two files:

index.html — standalone UI (~250 lines)
app.js — core logic (~380 lines)

You can clone it, run npx serve ., and have a working background remover in 30 seconds.

What's Next

Some ideas for anyone who wants to fork and extend:

Background replacement — solid color or custom image behind the subject
Batch processing — drop multiple images, process all sequentially
WebGPU acceleration — ONNX Runtime Web supports WebGPU; inference could be 3-5x faster
Edge feathering controls — post-process the mask with adjustable blur radius
Before/after slider — drag to compare original and result

Try It

Live tool: toolknit.com/tools/background-remover.html
Open source: github.com/2645149786-dotcom/toolknit
All 61 tools: toolknit.com

If you've ever needed to remove a background without uploading your photo to a random website — this is it. Clone it, use it, break it, improve it.

Built by Zihang Dong. Building browser-first tools at ToolKnit.

I Built a Free Browser-Based Image Tools Platform

Zihang Dong 董子航 — Tue, 19 May 2026 07:12:30 +0000

I Built a Privacy-First Online Image Tools Platform That Runs 100% in the Browser

Most online image tools solve one problem and create three new ones.

You want to compress an image, resize a file, convert PNG to WebP, or add a watermark — and suddenly you're dealing with uploads, account walls, aggressive ads, or “free” tools that stop being useful after one click.

I wanted something simpler.

So I built 24Picture: a privacy-first online image tools platform focused on speed, simplicity, and browser-based processing.

Why I built it

A lot of people don’t need Photoshop.

They just need to:

convert image formats
compress large files
resize assets for social media
crop screenshots
add watermarks
create memes or GIFs
edit images quickly without installing software

That sounds simple, but the existing experience is often frustrating.

So I decided to build a toolset that feels lightweight and practical.

What makes it different

The core idea is simple:

Do as much as possible directly in the browser.

That means users can process images without sending files to a remote server for every basic task.

This has a few clear advantages:

better privacy
less friction
faster iteration
no account requirement
no software installation

Current features

24Picture currently includes tools for:

JPG to PNG
PNG to WebP
HEIC to JPG
image compression
image resizing
image cropping
adding watermarks
Base64 conversion
batch conversion
SVG optimization
gradient generation
meme creation
GIF creation
GIF to MP4 conversion
browser-based image editing

You can explore the full platform here:

https://24picture.com/

Built for normal users, not just designers

One thing I’ve learned while building this is that many users are not looking for a “creative suite.”

They’re looking for relief.

They want to finish a task and move on.

A seller needs product images resized.
A creator needs a thumbnail compressed.
A student needs a PNG with transparency.
A marketer needs a quick watermark.
A developer needs an image converted to Base64.

The goal is not to impress them with complexity.
The goal is to help them solve the problem in 30 seconds.

Technical direction

The project is intentionally lightweight:

static HTML/CSS/JS
browser-side processing where possible
multilingual support
PWA support
SEO-focused content structure
no unnecessary build complexity for the public-facing experience

I’ve also been investing in better crawlability, structured metadata, multilingual coverage, sitemap automation, and AI-readable site documentation so the platform becomes easier to discover and understand over time.

Privacy matters

This was non-negotiable for me.

A lot of users handle private screenshots, personal photos, client files, or business assets. They should not have to wonder where those files go.

That’s why privacy-first processing is one of the key principles behind the platform.

If you want to try it

If you work with images regularly and want something fast, simple, and browser-friendly, take a look:

24Picture — Free Online Image Tools

I’m still improving it continuously, adding features, refining UX, fixing edge cases, and expanding content for different languages and use cases.

If you’ve built something similar — or if you have strong opinions about browser-based media tools — I’d love to hear how you think about the tradeoff between simplicity, privacy, and power.

Building a 3D Coin Flip with Pure CSS Animations & Vanilla JS (Open Source)

Zihang Dong 董子航 — Mon, 18 May 2026 16:27:02 +0000

How I built a realistic coin flip tool with 3D CSS transforms, parabolic arc physics, and streak tracking — zero dependencies, 150 lines of JS.

The Problem

I needed a coin flip tool for ToolKnit that felt physical — not just a random number with a boring text swap. The goal: a 3D coin that launches into the air, spins realistically, lands with a bounce, and tracks your statistics. All running 100% in the browser with zero dependencies.

Here's how I built it.

Architecture: 3 Layers of Animation

The trick to realistic coin physics is separating concerns into three independent CSS animations that play simultaneously:

┌─────────────────────────────────┐
│  .coin-wrapper  → Y trajectory  │  (parabolic arc up/down)
│    └── .coin    → 3D spin       │  (rotateY for flip)
│  .coin-shadow   → ground shadow │  (scale pulse)
└─────────────────────────────────┘

Each layer handles one axis of movement. Combined, they create convincing physics without any JavaScript animation libraries.

Layer 1: The Parabolic Arc (Y-axis)

The wrapper handles the vertical trajectory — launch up, hang at apex, fall back down with a small bounce:

@keyframes coinToss {
    0%   { transform: translateY(0); }
    8%   { transform: translateY(10px); }      /* crouch before launch */
    35%  { transform: translateY(-200px); }    /* rising */
    50%  { transform: translateY(-220px); }    /* apex — slight hang */
    65%  { transform: translateY(-180px); }    /* falling */
    88%  { transform: translateY(-10px); }     /* impact */
    93%  { transform: translateY(5px); }       /* bounce 1 */
    96%  { transform: translateY(-3px); }      /* bounce 2 */
    100% { transform: translateY(0); }         /* settle */
}

Key insight: The 8% crouch before launch sells the "weight" of the coin. The micro-bounces at 88–100% prevent it from feeling like it stops dead.

Layer 2: The 3D Spin

This is where the magic happens. CSS rotateY with transform-style: preserve-3d gives us true 3D flipping:

/* Heads: lands face-up (even half-turns = 3240° = 9 full rotations) */
@keyframes spinHeads {
    0%   { transform: rotateY(0deg) rotateX(0deg); }
    35%  { transform: rotateY(1080deg) rotateX(15deg); }
    65%  { transform: rotateY(2160deg) rotateX(-10deg); }
    88%  { transform: rotateY(2800deg) rotateX(5deg); }
    100% { transform: rotateY(3240deg) rotateX(0deg); }  /* 3240 / 360 = 9 */
}

/* Tails: lands face-down (odd half-turns = 3060° = 8.5 rotations) */
@keyframes spinTails {
    0%   { transform: rotateY(0deg) rotateX(0deg); }
    35%  { transform: rotateY(1080deg) rotateX(15deg); }
    65%  { transform: rotateY(2160deg) rotateX(-10deg); }
    88%  { transform: rotateY(2800deg) rotateX(5deg); }
    100% { transform: rotateY(3060deg) rotateX(0deg); }  /* 3060 / 360 = 8.5 */
}

Why this works:

Heads lands on an even number of half-turns (front face visible)
Tails lands on an odd number of half-turns (back face visible, thanks to backface-visibility: hidden)
The subtle rotateX wobble at 35%/65% simulates the coin not spinning on a perfectly flat axis — just like real physics

Layer 3: Ground Shadow

A radial-gradient ellipse that shrinks when the coin is airborne and expands on landing:

@keyframes shadowPulse {
    0%   { width: 120px; opacity: 1; }
    10%  { width: 80px; opacity: 0.5; }
    30%  { width: 50px; opacity: 0.2; }     /* coin at height */
    50%  { width: 40px; opacity: 0.15; }    /* apex */
    70%  { width: 60px; opacity: 0.3; }     /* falling */
    85%  { width: 100px; opacity: 0.7; }
    92%  { width: 130px; opacity: 1; }      /* impact overshoot */
    96%  { width: 110px; opacity: 0.9; }
    100% { width: 120px; opacity: 1; }      /* settle */
}

This shadow grounds the coin in 3D space. Without it, the coin feels like it's floating.

The JavaScript: 150 Lines, Zero Dependencies

The entire logic is a self-contained IIFE:

(function () {
    'use strict';

    const ANIM_DURATION = 1450; // matches CSS 1.4s + buffer
    let heads = 0, tails = 0, streak = 0, best = 0;
    let lastResult = null, isFlipping = false, history = [];

    function flipCoin() {
        if (isFlipping) return;
        isFlipping = true;

        // Fair 50/50 random
        const result = Math.random() < 0.5 ? 'heads' : 'tails';

        // Reset animations (remove class → force reflow → add class)
        coin.classList.remove('spin-heads', 'spin-tails');
        coinWrapper.classList.remove('tossing');
        void coin.offsetWidth; // force reflow — critical!

        // Trigger all 3 animation layers simultaneously
        coinWrapper.classList.add('tossing');
        coinShadow.classList.add('airborne');
        coin.classList.add(result === 'heads' ? 'spin-heads' : 'spin-tails');

        // Update state after animation completes
        setTimeout(() => {
            result === 'heads' ? heads++ : tails++;

            // Streak tracking
            streak = (result === lastResult) ? streak + 1 : 1;
            lastResult = result;
            if (streak > best) best = streak;

            history.push(result);
            updateStats();
            isFlipping = false;
        }, ANIM_DURATION);
    }

    // Keyboard shortcut: Space to flip
    document.addEventListener('keydown', (e) => {
        if (e.code === 'Space' && !e.repeat) {
            e.preventDefault();
            flipCoin();
        }
    });
})();

Key decisions:

void coin.offsetWidth — Forces a browser reflow between removing and re-adding animation classes. Without this, the browser optimizes away the class change and the animation won't replay.
isFlipping guard — Prevents spamming the button during animation. CSS animations can stack weirdly if retriggered mid-flight.
Math.random() < 0.5 — Simple and fair. The browser's PRNG is seeded from OS entropy, making it perfectly adequate for a coin flip (this isn't cryptography).
Streak tracking — A single variable that resets on result change. Elegant and zero-allocation.

The Coin Face Structure (HTML)

<div class="coin-container">
    <div class="coin-shadow" id="coin-shadow"></div>
    <div class="coin-wrapper" id="coin-wrapper">
        <div class="coin" id="coin">
            <div class="coin-face coin-heads">
                <div class="coin-shine"></div>
                H
            </div>
            <div class="coin-face coin-tails">
                <div class="coin-shine"></div>
                T
            </div>
        </div>
    </div>
</div>

The .coin-tails face has transform: rotateY(180deg) so it's initially hidden by backface-visibility: hidden. The shine overlay is a CSS gradient that gives the coin a metallic reflection.

Stats & Probability Bar

A dead-simple probability visualization:

function updateStats() {
    const total = heads + tails;
    const hp = total > 0 ? Math.round((heads / total) * 100) : 50;
    headsBar.style.width = hp + '%';
    tailsBar.style.width = (100 - hp) + '%';
}

Two <div>s inside a flex container with transition: width 0.5s — the bar animates smoothly as the probability shifts with each flip. Over 100+ flips, you watch it converge to 50/50 (law of large numbers in real time).

Try It Live

👉 ToolKnit Coin Flip — free, no signup, runs entirely in your browser.

The full source is visible in-browser (View Source) since it's all client-side HTML/CSS/JS. Feel free to learn from it, fork the approach, or adapt it for your own projects.

What I'd Do Differently

Web Animations API instead of CSS keyframes — more control over playback speed, easing, and cancellation
Canvas/WebGL for truly custom coin textures (country flags, custom images)
Haptic feedback on mobile via navigator.vibrate()

But for a zero-dependency, 150-line solution that works on every browser? Pure CSS animations are hard to beat.

Built as part of ToolKnit — a free, open-source collection of 60+ browser-based tools. No uploads, no accounts, works offline.

Building a 3D Coin Flip with Pure CSS Animations & Vanilla JS (Open Source)

Zihang Dong 董子航 — Mon, 18 May 2026 16:27:02 +0000

How I built a realistic coin flip tool with 3D CSS transforms, parabolic arc physics, and streak tracking — zero dependencies, 150 lines of JS.

The Problem

Here's how I built it.

Architecture: 3 Layers of Animation

The trick to realistic coin physics is separating concerns into three independent CSS animations that play simultaneously:

┌─────────────────────────────────┐
│  .coin-wrapper  → Y trajectory  │  (parabolic arc up/down)
│    └── .coin    → 3D spin       │  (rotateY for flip)
│  .coin-shadow   → ground shadow │  (scale pulse)
└─────────────────────────────────┘

Each layer handles one axis of movement. Combined, they create convincing physics without any JavaScript animation libraries.

Layer 1: The Parabolic Arc (Y-axis)

The wrapper handles the vertical trajectory — launch up, hang at apex, fall back down with a small bounce:

@keyframes coinToss {
    0%   { transform: translateY(0); }
    8%   { transform: translateY(10px); }      /* crouch before launch */
    35%  { transform: translateY(-200px); }    /* rising */
    50%  { transform: translateY(-220px); }    /* apex — slight hang */
    65%  { transform: translateY(-180px); }    /* falling */
    88%  { transform: translateY(-10px); }     /* impact */
    93%  { transform: translateY(5px); }       /* bounce 1 */
    96%  { transform: translateY(-3px); }      /* bounce 2 */
    100% { transform: translateY(0); }         /* settle */
}

Key insight: The 8% crouch before launch sells the "weight" of the coin. The micro-bounces at 88–100% prevent it from feeling like it stops dead.

Layer 2: The 3D Spin

This is where the magic happens. CSS rotateY with transform-style: preserve-3d gives us true 3D flipping:

/* Heads: lands face-up (even half-turns = 3240° = 9 full rotations) */
@keyframes spinHeads {
    0%   { transform: rotateY(0deg) rotateX(0deg); }
    35%  { transform: rotateY(1080deg) rotateX(15deg); }
    65%  { transform: rotateY(2160deg) rotateX(-10deg); }
    88%  { transform: rotateY(2800deg) rotateX(5deg); }
    100% { transform: rotateY(3240deg) rotateX(0deg); }  /* 3240 / 360 = 9 */
}

/* Tails: lands face-down (odd half-turns = 3060° = 8.5 rotations) */
@keyframes spinTails {
    0%   { transform: rotateY(0deg) rotateX(0deg); }
    35%  { transform: rotateY(1080deg) rotateX(15deg); }
    65%  { transform: rotateY(2160deg) rotateX(-10deg); }
    88%  { transform: rotateY(2800deg) rotateX(5deg); }
    100% { transform: rotateY(3060deg) rotateX(0deg); }  /* 3060 / 360 = 8.5 */
}

Why this works:

Heads lands on an even number of half-turns (front face visible)
Tails lands on an odd number of half-turns (back face visible, thanks to backface-visibility: hidden)
The subtle rotateX wobble at 35%/65% simulates the coin not spinning on a perfectly flat axis — just like real physics

Layer 3: Ground Shadow

A radial-gradient ellipse that shrinks when the coin is airborne and expands on landing:

@keyframes shadowPulse {
    0%   { width: 120px; opacity: 1; }
    10%  { width: 80px; opacity: 0.5; }
    30%  { width: 50px; opacity: 0.2; }     /* coin at height */
    50%  { width: 40px; opacity: 0.15; }    /* apex */
    70%  { width: 60px; opacity: 0.3; }     /* falling */
    85%  { width: 100px; opacity: 0.7; }
    92%  { width: 130px; opacity: 1; }      /* impact overshoot */
    96%  { width: 110px; opacity: 0.9; }
    100% { width: 120px; opacity: 1; }      /* settle */
}

This shadow grounds the coin in 3D space. Without it, the coin feels like it's floating.

The JavaScript: 150 Lines, Zero Dependencies

The entire logic is a self-contained IIFE:

(function () {
    'use strict';

    const ANIM_DURATION = 1450; // matches CSS 1.4s + buffer
    let heads = 0, tails = 0, streak = 0, best = 0;
    let lastResult = null, isFlipping = false, history = [];

    function flipCoin() {
        if (isFlipping) return;
        isFlipping = true;

        // Fair 50/50 random
        const result = Math.random() < 0.5 ? 'heads' : 'tails';

        // Reset animations (remove class → force reflow → add class)
        coin.classList.remove('spin-heads', 'spin-tails');
        coinWrapper.classList.remove('tossing');
        void coin.offsetWidth; // force reflow — critical!

        // Trigger all 3 animation layers simultaneously
        coinWrapper.classList.add('tossing');
        coinShadow.classList.add('airborne');
        coin.classList.add(result === 'heads' ? 'spin-heads' : 'spin-tails');

        // Update state after animation completes
        setTimeout(() => {
            result === 'heads' ? heads++ : tails++;

            // Streak tracking
            streak = (result === lastResult) ? streak + 1 : 1;
            lastResult = result;
            if (streak > best) best = streak;

            history.push(result);
            updateStats();
            isFlipping = false;
        }, ANIM_DURATION);
    }

    // Keyboard shortcut: Space to flip
    document.addEventListener('keydown', (e) => {
        if (e.code === 'Space' && !e.repeat) {
            e.preventDefault();
            flipCoin();
        }
    });
})();

Key decisions:

void coin.offsetWidth — Forces a browser reflow between removing and re-adding animation classes. Without this, the browser optimizes away the class change and the animation won't replay.
isFlipping guard — Prevents spamming the button during animation. CSS animations can stack weirdly if retriggered mid-flight.
Math.random() < 0.5 — Simple and fair. The browser's PRNG is seeded from OS entropy, making it perfectly adequate for a coin flip (this isn't cryptography).
Streak tracking — A single variable that resets on result change. Elegant and zero-allocation.

The Coin Face Structure (HTML)

<div class="coin-container">
    <div class="coin-shadow" id="coin-shadow"></div>
    <div class="coin-wrapper" id="coin-wrapper">
        <div class="coin" id="coin">
            <div class="coin-face coin-heads">
                <div class="coin-shine"></div>
                H
            </div>
            <div class="coin-face coin-tails">
                <div class="coin-shine"></div>
                T
            </div>
        </div>
    </div>
</div>

The .coin-tails face has transform: rotateY(180deg) so it's initially hidden by backface-visibility: hidden. The shine overlay is a CSS gradient that gives the coin a metallic reflection.

Stats & Probability Bar

A dead-simple probability visualization:

function updateStats() {
    const total = heads + tails;
    const hp = total > 0 ? Math.round((heads / total) * 100) : 50;
    headsBar.style.width = hp + '%';
    tailsBar.style.width = (100 - hp) + '%';
}

Try It Live

👉 ToolKnit Coin Flip — free, no signup, runs entirely in your browser.

The full source is visible in-browser (View Source) since it's all client-side HTML/CSS/JS. Feel free to learn from it, fork the approach, or adapt it for your own projects.

What I'd Do Differently

Web Animations API instead of CSS keyframes — more control over playback speed, easing, and cancellation
Canvas/WebGL for truly custom coin textures (country flags, custom images)
Haptic feedback on mobile via navigator.vibrate()

But for a zero-dependency, 150-line solution that works on every browser? Pure CSS animations are hard to beat.

Built as part of ToolKnit — a free, open-source collection of 60+ browser-based tools. No uploads, no accounts, works offline.

DEV Community: Zihang Dong 董子航

I Built a Browser-Based Typing Speed Test That Handles 15s to 5-Minute Tests (and How It Works)

What we are building

The core idea: render text as individual characters

Handling keyboard input correctly

Calculating WPM and accuracy

Scaling the prompt length for 3m and 5m tests

Accessibility and mobile gotchas

Why this is privacy-first

Full source and live demo

Conclusion

I Spent $200 in One Day on AI Tokens to Build 86 Browser Tools — A Solo Founder's Complete Build Log

The Genesis: Why Would Anyone Build 86 Free Tools?

Part I: The Stack — Why I Chose Boring Technology

Part II: The Tools That Lived — Engineering Notes from the Trenches

The MIDI Keyboard: 8 Timbres, 1 Web Audio Context

The Morse Code Translator: Audio, Flash, and International Alphabet

The Lyric Visualizer: Web Audio API + Canvas + LRC Parsing

Spin the Dare: From Canvas Wheel to Slot Machine

Part III: The Features That Died — When Technical Soundness Isn't Enough

Live Photo Frame: 48 Hours, 3 Fatal Flaws

AI Pixel Art GIF: Twice Bitten

Part IV: The $200 Day — Rebuilding 19 Pages in Bilingual Architecture

The Problem

The Architecture

The Cost

Part V: The Migration War — 11 Image Tools, 11 Ways to Break

Bug 1: The Single Quote That Killed a Language Switcher

Bug 2: The Batch Script That Silently Missed Two Tips

Bug 3: innerHTML vs. SVG Children

Bug 4: The Nginx Header That Broke Every Camera

Part VI: The Human Debug — When the Compiler Can't Help

Part VII: The Numbers & What Honesty Looks Like

What's Next (The Arithmetic of Patience)

The Ask

Building AI Ex-Partner Chat: OCR, Sender Detection & the 3 AM Code That Shouldn't Exist

Building AI Ex-Partner Chat: OCR, Sender Detection & the 3 AM Code That Shouldn't Exist

The problem that started at 3 AM

Version 1: Pixel-based avatar detection (and why it failed)

Version 2: Tesseract bounding boxes + position-based detection

The garbage filter: Why OCR output is 80% noise

Step 1.5: The sender confirmation step

OCR pre-processing: Why "想" and "相" matter

The shared Tesseract worker: Minutes to seconds

Persona distillation: The 6-step pipeline

The identity guard: Preventing persona drift

IndexedDB: Where personas live (and die)

The consent overlay

The hardest bug wasn't technical

Technical stack summary

What I'd do differently

How I Built 72 Browser-Only Tools Without a Backend — A Solo Developer's Technical Retrospective

The Core Architecture

WebAssembly: The Enabler

The Service Worker Strategy

The Deployment Disaster That Changed Everything

The Architecture Refactor That Saved My Sanity

Privacy Hardening: The Day I Scrubbed My Own Analytics

Internationalization: Chinese Without a Framework

FIGlet Fonts and CORS: A Cautionary Tale

The Tech Stack Summary

What I Would Do Differently

Alternatives and Related Projects

Smallpdf

Squoosh

TinyWow

My static site's visitor counter reset to 1. Here is the deploy checklist I wish I had

The setup: static site, one tiny runtime file

The bug: full replacement treated runtime data like build output

Fix #1: restore from the highest trustworthy backup

Fix #2: preserve runtime data during full deploys

Fix #3: make the deploy script prove it is safe

The cache lesson from the same release

My new tiny-site deploy checklist

1. Classify every path before deleting anything

2. Preserve runtime data explicitly

3. Verify the values users can see

4. Keep one small audit script per scary class of bug

5. Write the postmortem while it is still embarrassing

A small ask

Bug 3: `innerHTML` vs. SVG Children

4. A harmless-looking `querySelector()` can break production navigation

4. Don't pass `href` straight into `querySelector` for hash anchors

5. When you change a shared asset, bump the Service Worker AND add `?v=`