DEV Community: Zihang Dong 董子航

How I Built a Dice Roller That Google Can't Beat — A Technical Deep Dive

Zihang Dong 董子航 — Wed, 08 Jul 2026 08:48:15 +0000

Google's built-in dice roller was stealing my search traffic. Instead of competing, I built something it can't replicate: batch rolling, game presets, probability visualization, CSV export, and 3D CSS dice faces. Here's the full technical breakdown.

How I Built a Dice Roller That Google Can't Beat

Google was stealing my clicks. Every time someone searched "dice roller," Google's own interactive dice widget sat at the top of the results — a fully functional, zero-click tool that let users roll dice without ever visiting a website.

This is the story of how I analyzed the competitive landscape, identified what Google's built-in tool couldn't do, and built a dice roller that serves real users instead of competing with a search giant head-on.

Part 1: The Discovery

I run ToolKnit, a collection of 90 free browser-based tools. Our dice roller had been live for months — it supported D4 through D100, custom sides, multi-dice rolls, and had a clean dark UI. But the click-through rate from Google Search was abysmal.

When I looked at the SERP for "dice roller," the answer was obvious:

Google displays an interactive dice widget directly in the search results. Users can click it, roll dice, and get results — all without leaving Google. This is a SERP Feature specifically designed for dice-related queries, and it cannibalizes organic traffic almost completely.

The conventional SEO playbook says: "Optimize your meta tags, build more backlinks, write better content." But none of that matters when Google puts a working tool above your link. Users don't scroll down because they don't need to.

The insight: Stop trying to outrank Google. Instead, build something Google's widget can't do.

Part 2: What Google's Dice Can't Do

Google's built-in dice roller is minimal by design. It supports:

D4, D6, D8, D10, D12, D20, D100
Multiple dice (e.g., 3d6)
Adding modifiers (+3, +5)
An animation that shows results

What it doesn't support:

❌ Game-specific presets (Monopoly, Yahtzee, Catan, Craps)
❌ Batch rolling (10×, 50×, 100×)
❌ Roll history with CSV export
❌ Probability distribution visualization
❌ Dice face customization (skins)
❌ Keyboard shortcuts
❌ Sound effects
❌ Session statistics (total rolls, average, grand sum)

Every feature on this list is something a real user would want — whether they're a D&D player tracking combat rounds, a teacher running a probability lesson, or a board game enthusiast who lost their physical dice.

I decided to build all of them.

Part 3: The Technical Build

Here's the architecture: zero dependencies, pure vanilla JavaScript, CSS animations, and HTML5 Canvas. No npm, no build step, no framework. The tool is a single HTML file with inline JS that loads in under 300ms.

3.1 3D Dice Faces with Pure CSS

The dice aren't images or SVGs — they're styled <div> elements with CSS grid layouts. Each face shows the correct dot pattern:

.dice-face {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  grid-template-rows: repeat(3, 1fr);
  width: 64px;
  height: 64px;
  background: #1a1a2e;
  border: 2px solid rgba(255,255,255,0.12);
  border-radius: 14px;
  padding: 8px;
}

.dot {
  width: 12px;
  height: 12px;
  background: #fff;
  border-radius: 50%;
  place-self: center;
}

The roll animation applies a CSS transform sequence — rotation in 3D space with a scale bounce:

@keyframes diceRoll {
  0%   { transform: rotateX(0deg) rotateY(0deg) rotateZ(0deg) scale(1); }
  25%  { transform: rotateX(180deg) rotateY(90deg) rotateZ(45deg) scale(1.1); }
  50%  { transform: rotateX(360deg) rotateY(180deg) rotateZ(90deg) scale(0.95); }
  75%  { transform: rotateX(540deg) rotateY(270deg) rotateZ(135deg) scale(1.05); }
  100% { transform: rotateX(720deg) rotateY(360deg) rotateZ(180deg) scale(1); }
}

Each die gets a different animation delay so they tumble sequentially, not simultaneously — this creates a much more satisfying visual cascade.

3.2 requestAnimationFrame for Batch Rolling

The batch roll feature was the hardest technical challenge. Rolling 100 dice at once with the full animation loop would freeze the browser. The solution: chunked processing with requestAnimationFrame.

function batchRoll(count) {
  if (isRolling) return;
  isRolling = true;

  var batchResults = [];
  var i = 0;

  function step() {
    // Process 10 rolls per frame to avoid UI freeze
    var chunk = Math.min(10, count - i);

    for (var j = 0; j < chunk; j++) {
      var results = [];
      for (var d = 0; d < diceCount; d++) {
        results.push(Math.floor(Math.random() * 6) + 1);
      }
      batchResults.push(results);

      var total = results.reduce(function(a, b) { return a + b; }, 0);
      rolls++;
      grandTotal += total;
      results.forEach(function(v) { distribution[v]++; });
    }

    i += chunk;

    // Update UI every frame
    updateDistribution();
    updateHistory();
    progressBar.style.width = Math.round((i / count) * 100) + '%';

    if (i < count) {
      requestAnimationFrame(step);
    } else {
      // Final animation for the last result
      renderDice(batchResults[batchResults.length - 1]);
      isRolling = false;
    }
  }

  requestAnimationFrame(step);
}

Key decisions:

10 rolls per frame keeps the UI responsive while maintaining visual feedback
The progress bar updates every frame, giving users a satisfying sense of progress
The last roll gets the full dice animation treatment so it "feels" like a real roll
isRolling gate prevents double-clicks from stacking batch operations

3.3 Game Presets

Instead of asking users to configure dice manually, I added one-click presets for popular games:

Preset	Dice	Why
Monopoly	2d6	Classic property-buying rolls
Yahtzee	5d6	Five dice, three rolls per turn (manual)
Catan	2d6	Settlers resource distribution
Craps	2d6	Casino-style come-out roll
D&D Skill	1d20	Ability checks and saving throws

Each preset adjusts the dice count and type automatically. This small UX decision matters enormously for casual users who just want to play their game without reading documentation.

3.4 Probability Distribution with Theoretical Comparison

The distribution chart uses HTML5 Canvas to draw a bar chart showing the frequency of each die face (1-6). But the real insight was adding a theoretical overlay:

// Theoretical: exactly 1/6 = 16.67% per face
var theoretical = 1 / 6;
var theoreticalHeight = maxBarHeight * theoretical;
ctx.fillStyle = 'rgba(59, 130, 246, 0.25)';
ctx.fillRect(barX, chartH - theoreticalHeight, barW, theoreticalHeight);

Each bar shows:

Actual frequency (solid white/gray bar)
Theoretical 16.67% (semi-transparent blue overlay)

As users roll more, the bars converge toward the theoretical line — visually demonstrating the Law of Large Numbers. This is useful for teachers and anyone curious about probability.

3.5 CSV Export

Roll history is more useful when you can take it elsewhere. The CSV export button generates a downloadable file with headers:

function exportCSV() {
  var csv = 'Roll#,Die1,Die2,Die3,Die4,Die5,Die6,Total\n';
  for (var i = historyData.length - 1; i >= 0; i--) {
    var row = historyData[i];
    csv += (row.roll) + ',' + row.results.join(',') + ',' + row.total + '\n';
  }
  var blob = new Blob([csv], { type: 'text/csv' });
  var url = URL.createObjectURL(blob);
  var a = document.createElement('a');
  a.href = url;
  a.download = 'dice-rolls.csv';
  a.click();
}

This lets users analyze their rolls in Excel, Google Sheets, or any statistics tool. Combined with the batch roll feature, you can generate thousands of data points for a probability experiment in seconds.

3.6 Dice Skins

Three color themes (slate, indigo, emerald) that apply via CSS class switching. Under the hood, it's just swapping data-skin attributes and re-rendering. The DOM stays unchanged — only the visual presentation changes.

3.7 Keyboard Shortcuts

document.addEventListener('keydown', function(e) {
  if (e.key === ' ' || e.key === 'Enter') { roll(); }
  if (e.key === 'r' || e.key === 'R') { reset(); }
  if (e.key === 'ArrowUp') { changeDice(1); }
  if (e.key === 'ArrowDown') { changeDice(-1); }
  if (e.key === '1') { batchRoll(10); }
  if (e.key === '5') { batchRoll(50); }
  if (e.key === '0') { batchRoll(100); }
});

Space/Enter to roll, R to reset, arrows to adjust dice count, number keys for batch operations. Power users love this.

Part 4: The Results

After the update, the dice roller went from a generic tool to a feature-rich dice toolbox. Key metrics:

Metric	Before	After
Weekly Google impressions	~200	2,230+
Weekly Bing impressions	~50	1,300+
Total weekly exposure	~250	3,500+

That's a 14× increase in three months.

The lesson: Google's SERP Features aren't an impenetrable wall. They're a constraint that forces you to build something genuinely better. If Google's widget does A, B, and C — build A through Z. Users will find you when they need more than what the search result page provides.

Part 5: What I'd Do Differently

Web Workers for batch rolling. Currently, requestAnimationFrame is good enough for 100 rolls, but 1,000+ rolls should be offloaded to a Worker thread.
IndexedDB for persistent roll history. Right now, history resets on page reload. Storing it locally would make the tool feel like a real app.
Physics-based 3D dice. The CSS animations look good, but a Three.js or Canvas-based physics simulation would be the ultimate differentiator.
Multiplayer sync. Imagine a shared dice room where multiple players see the same roll in real-time via WebSockets.

The Bigger Picture

This approach applies to any tool that faces Google SERP Feature competition: calculators, unit converters, timers, coin flippers, color pickers. The strategy is always the same:

Analyze what the SERP Feature does.
List everything it doesn't do that real users need.
Build those things.

Don't try to outrank Google. Out-build them.

This article was written by the creator of ToolKnit — 90 free browser-based tools that run entirely in your browser with no sign-up and no uploads. Try the Dice Roller and let me know what else you'd want to see.

I Built a Free Breathing Relaxation Tool with 6 Science-Backed Techniques — Here's How It Works and Why You Should Try It

Zihang Dong 董子航 — Mon, 06 Jul 2026 07:09:54 +0000

Stress is a silent killer. The WHO estimates that stress-related disorders affect over 300 million people worldwide. We've all been there — deadlines piling up, notifications buzzing, your chest tightening, and no clear way to reset.

As a developer who also struggles with stress and anxiety, I wanted to build something genuinely useful — not another productivity app or to-do list. Something that could help in the moment. So I built Breathing Relaxation, a free, privacy-first browser tool with 6 guided breathing techniques, now live at toolknit.com/tools/breathing-relaxation.html.

In this post, I'll cover:

Why breathing exercises work (the science)
The 6 techniques and when to use each one
How I built it (Canvas animation, Web Audio API, haptic feedback)
Key UI/UX decisions that made the experience work

Why Breathing Works: A Quick Science Primer

When you're stressed, your sympathetic nervous system kicks in — heart rate rises, breathing becomes shallow, cortisol floods your bloodstream. This is the "fight or flight" response, hardwired into our biology.

Slow, controlled breathing activates the parasympathetic nervous system — your body's built-in "rest and digest" mode. The vagus nerve, which runs from your brainstem to your abdomen, detects slow exhalations and signals your heart to slow down. This is called respiratory sinus arrhythmia — and it's the physiological mechanism behind why deep breathing actually works.

A 2017 meta-analysis published in Frontiers in Psychology reviewed 15 randomized controlled trials and found that slow-paced breathing (around 6 breaths per minute) significantly reduced self-reported stress, anxiety, and depression scores. Another study in Cell Reports Medicine (2023) demonstrated that deliberate breathwork practices produced measurable changes in brain connectivity patterns associated with emotion regulation.

The key: exhale longer than you inhale. That's the signal your vagus nerve needs to trigger relaxation.

The 6 Techniques — When to Use Each

1. 4-7-8 Breathing (Dr. Andrew Weil)

Pattern: Inhale 4s → Hold 7s → Exhale 8s

This is the "nuclear option" for anxiety. The extended exhale (8 seconds) forces maximum vagal activation. Dr. Weil calls it a "natural tranquilizer for the nervous system." It's particularly effective for falling asleep — many users report drifting off within 2-3 cycles.

Best for: Insomnia, acute anxiety, panic moments.

2. Box Breathing (Navy SEAL Technique)

Pattern: Inhale 4s → Hold 4s → Exhale 4s → Hold 4s

Used by Navy SEALs before high-pressure missions, this technique creates a rhythmic, predictable pattern that forces your mind into a focused state. The equal-phase structure makes it easy to visualize as a square — each side equal in length.

Best for: Pre-meeting jitters, public speaking, performance anxiety, regaining focus.

3. Coherent Breathing (5-5)

Pattern: Inhale 5s → Exhale 5s

At exactly 5 breaths per minute, this rhythm synchronizes heart rate, blood pressure, and respiration into a phenomenon called cardiorespiratory coherence. Research from the HeartMath Institute shows that this state measurably improves cognitive performance and emotional stability.

Best for: Daily maintenance, meditation, sustained focus work.

4. 4-2-4 Relaxation

Pattern: Inhale 4s → Hold 2s → Exhale 4s

A gentler introduction to breath holds. The 2-second hold teaches your body to tolerate slight CO2 buildup without triggering panic — a skill that transfers to real-world stressful situations.

Best for: Beginners, quick resets between meetings, afternoon slumps.

5. Energizing Breath

Pattern: Inhale 6s → Hold 2s → Exhale 4s

This is the reverse of most relaxation patterns — inhale longer than exhale. It increases oxygen saturation and creates a mild stimulatory effect. Think of it as a natural espresso shot without the crash.

Best for: Morning energy, pre-workout, beating the 3pm slump.

6. Alternate Nostril Breathing (Nadi Shodhana)

Pattern: Inhale left 4s → Hold 4s → Exhale right 4s → Inhale right 4s → Hold 4s → Exhale left 4s

Rooted in yogic tradition and validated by modern research, this technique balances the left and right hemispheres of the brain. A 2018 study in the International Journal of Yoga found that regular alternate nostril breathing significantly reduced stress and improved attention in healthy adults.

Best for: Mental clarity, balancing energy, pre-meditation.

The Tech Stack: How I Built It

Canvas Animation Engine

The breathing animation is powered by pure Canvas API — no libraries, no dependencies. Here's the core approach:

// Simplified animation loop
function animate(timestamp) {
    const progress = (timestamp - startTime) / (phaseDuration * 1000);
    const scale = 1 + Math.sin(progress * Math.PI) * 0.35; // Smooth expand/contract

    ctx.clearRect(0, 0, canvas.width, canvas.height);
    ctx.save();
    ctx.translate(canvas.width / 2, canvas.height / 2);
    ctx.scale(scale, scale);
    // Draw the breathing circle
    ctx.beginPath();
    ctx.arc(0, 0, radius, 0, Math.PI * 2);
    ctx.fill();
    ctx.restore();

    requestAnimationFrame(animate);
}

The key design challenge was creating smooth, natural-feeling animations. Linear scaling feels mechanical and jarring. I used Math.sin() with a half-cycle for each phase — inhale maps to 0 → π (expanding), exhale to π → 0 (contracting). The result is a fluid, organic breathing motion that feels intuitive to follow.

Each technique has its own phase configuration:

const techniques = {
    '4-7-8': [
        { label: 'Inhale', duration: 4, action: 'expand' },
        { label: 'Hold',  duration: 7, action: 'hold' },
        { label: 'Exhale', duration: 8, action: 'contract' }
    ],
    'box': [
        { label: 'Inhale', duration: 4, action: 'expand' },
        { label: 'Hold',  duration: 4, action: 'hold' },
        { label: 'Exhale', duration: 4, action: 'contract' },
        { label: 'Hold',  duration: 4, action: 'hold' }
    ]
    // ... etc
};

Phase Timer & Visual Rhythm

Below the animation circle, I built a compact timeline that shows the current phase, remaining time, and overall cycle progress. This was actually the trickiest part — on smaller screens, the labels for a 6-phase technique like Alternate Nostril Breathing would wrap and break the layout.

The solution: a flexbox row with flex: 0 0 X% on each phase label (where X = 100 / numberOfPhases), white-space: nowrap, and text-align: center. No wrapping, no misalignment — even on mobile.

Web Audio API for Sound Cues

When enabled, the tool plays subtle audio cues at phase transitions. I used the Web Audio API's OscillatorNode to generate a soft, bell-like tone:

function playPhaseBeep() {
    const ctx = new AudioContext();
    const osc = ctx.createOscillator();
    const gain = ctx.createGain();

    osc.type = 'sine';
    osc.frequency.value = 880; // A5 — soft and pleasant
    gain.gain.setValueAtTime(0.1, ctx.currentTime);
    gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.3);

    osc.connect(gain);
    gain.connect(ctx.destination);
    osc.start();
    osc.stop(ctx.currentTime + 0.3);
}

I deliberately chose a high-frequency sine wave (A5, 880Hz) at very low volume — it's audible but never startling. The exponentialRampToValueAtTime creates a natural decay that feels like a soft chime rather than an alert.

Haptic Feedback (iOS)

On supported devices, the tool uses the Vibration API to provide tactile cues:

if (navigator.vibrate) {
    navigator.vibrate([50, 30, 50]); // short-long-short pattern
}

This is especially useful when using the tool with eyes closed — the vibration confirms phase transitions without breaking the meditative state.

Cycle Locking Safety Mechanism

One insight from early testing: if you change the number of cycles mid-session, it corrupts the session state. The fix was straightforward — once breathing starts, the +/- buttons are disabled with pointer-events: none and reduced opacity:

function lockCycles(enabled) {
    const btns = document.querySelectorAll('.cycle-btn');
    btns.forEach(btn => {
        btn.style.pointerEvents = enabled ? 'none' : 'auto';
        btn.style.opacity = enabled ? '0.35' : '1';
    });
}

Session Completion UX

When a session ends, instead of an abrupt stop or a modal, I chose a gentle completion message that replaces the phase timer text with a congratulatory note. The font scales responsively (clamp(.85rem, 2vw, 1.1rem)) and appears at 50% opacity — present but not demanding attention. The user can simply close their eyes, breathe naturally, and let the moment settle.

Design Philosophy

A few principles that guided the design:

1. Distraction-free by default. The UI is minimal — one circle, one progress bar, one text label. You don't need to look at the screen to use it. Sound and vibration are opt-in, not opt-out.

2. Privacy-first. Zero data leaves your browser. No accounts, no tracking, no analytics on the tool page. Your breathing patterns are yours alone.

3. Accessibility matters. All color choices passed WCAG AA contrast ratios. The Phosphor icon set replaced emojis to ensure consistent rendering across platforms.

Try It Yourself

The tool is free and lives at toolknit.com/tools/breathing-relaxation.html. No sign-up, no download — just open it in any browser.

I built this for myself. I use it before stressful meetings, when I can't fall asleep, and during those moments when the world feels a little too heavy. If it helps even one other person breathe a little easier, the late nights were worth it.

Built with vanilla JavaScript, Canvas API, Web Audio API, and a lot of deep breaths. Questions? Feedback? Reach me at 2645149786@qq.com or @dngzihng114379.

References

Zaccaro, A., et al. (2018). "How Breath-Control Can Change Your Life: A Systematic Review on Psycho-Physiological Correlates of Slow Breathing." Frontiers in Human Neuroscience, 12, 353.
Balban, M. Y., et al. (2023). "Brief structured respiration practices enhance mood and reduce physiological arousal." Cell Reports Medicine, 4(1), 100895.
Telles, S., et al. (2018). "Alternate Nostril Breathing at Different Rates and its Influence on Heart Rate Variability in Non-Practitioners of Yoga." International Journal of Yoga, 11(1), 46–52.
McCraty, R., & Zayas, M. A. (2014). "Cardiac coherence, self-regulation, autonomic stability, and psychosocial well-being." Frontiers in Psychology, 5, 1090.
Weil, A. (2015). Breathing: The Master Key to Self Healing. Sounds True.

I Built 89 Tools in 100 Days. AI Wrote 90% of the Code. I Don't Regret It.

Zihang Dong 董子航 — Sun, 05 Jul 2026 09:39:17 +0000

The 'hand-written code backlash' misses the point. Here's what actually happens when one developer ships a full SaaS with AI — and what the critics get wrong.

I Built 89 Tools in 100 Days. AI Wrote 90% of the Code. I Don't Regret It.

The current dev.to narrative is clear: AI coding is creating a generation of "prompt engineers" who can't debug their own code. The hand-written code backlash is real — a recent HN post arguing for ditching AI coding assistants hit 737 points. "Vibe coding" is a punchline. Senior engineers are writing manifestos about comprehension gaps and skill atrophy.

I want to offer a counterpoint — not from theory, but from production.

On March 18, 2026, I launched ToolKnit.com — a privacy-first online toolbox. 109 days later, the site has 89 browser-based tools, 87 blog posts, a DR 41 domain rating, and thousands of monthly visitors from Google and Bing. Every tool runs 100% client-side. No backend. No database. No signup.

AI wrote roughly 90% of the code.

Here's the part the critics don't tell you: it worked. And I think the backlash, while understandable, is fighting the wrong battle.

What "90% AI-Generated" Actually Means

Let me be precise, because the numbers matter.

ToolKnit has 89 tools. Each tool has:

An HTML page (~350-600 lines of semantic markup)
A JavaScript engine (~200-800 lines of logic)
i18n translations in English and Chinese
SEO metadata, JSON-LD structured data, Open Graph tags
A service worker entry
A sitemap entry

That's roughly 55,000 lines of code across the project.

I hand-wrote exactly zero of those lines from scratch. Every file started with an AI prompt. Some took 3 iterations. Some took 15. But the initial scaffolding, the repetitive patterns (tool cards, footer components, meta tags), the JavaScript logic — AI generated all of it.

But here's the catch: I read and understood every line.

The Workflow That Makes AI Actually Work

The anti-AI crowd describes a world where developers paste AI output into production without reading it. I don't know anyone who actually works that way. Here's my real workflow:

Phase 1: Architecture (Human)

AI cannot design a system. It can't decide that 89 tools should share a common bilingual.js engine rather than each implementing their own language toggle. It can't plan a service worker caching strategy or decide which CDN to use.

I made all architectural decisions. I designed the component patterns, the file structure, the CSS custom property system, the build pipeline. This is the work that determines whether a project survives six months or collapses under its own weight.

Phase 2: Scaffolding (AI)

Once the patterns were established, AI became a multiplier. "Create a new tool page following this template, with these features, using this CSS framework." 90 seconds later, I had a complete HTML file with working JavaScript.

The AI understood the patterns because I'd already established them. It knew the bilingual setup because bilingual.js was part of the project context. It knew the footer pattern, the tool card pattern, the SEO pattern.

Phase 3: Review & Fix (Human)

This is where the 70% rejection rate from the studies comes in. AI gets things wrong. It hallucinates API names. It generates CSS that looks right but breaks at certain viewports. It writes JavaScript that handles the happy path but ignores edge cases.

But here's the thing: reviewing AI-generated code is faster than writing it from scratch. The cognitive load of "is this correct?" is lower than "what should I write and is it correct?".

For ToolKnit, the review phase typically took 5-10 minutes per file. I'd scan for:

Logical errors (timer countdowns that don't handle pause correctly)
Edge cases (what happens when localStorage is full?)
Security issues (never trust user input, even in client-side tools)
i18n completeness (did the Chinese translations actually get generated?)

Phase 4: Iterate (Human + AI)

The back-and-forth is where the real work happens. "The progress ring doesn't update when switching tabs." "The mobile layout breaks at 320px." "The Chinese translation for 'health recovery timeline' is awkward."

Each fix is another AI prompt. Each prompt takes 30 seconds. Each fix takes 2 minutes to verify.

What the Critics Get Right

I want to be fair to the backlash. They're not entirely wrong.

AI code converges on the median. If you let AI design your architecture, you'll get a generic React app with useState and useEffect everywhere. It won't be wrong, but it won't be good. The median is fine for CRUD. It's death for anything novel.

The comprehension gap is real. When I wrote code by hand ten years ago, I built a mental model of every subsystem. With AI, I have to actively build that model by reading the generated output. It's a different kind of understanding — more like code review than authorship — but understanding still happens if you're disciplined about it.

Debugging AI-generated code is harder. When you wrote it yourself, you know where the bodies are buried. When AI wrote it, you have to discover them. This is the single biggest productivity drag in my workflow. I've spent 45 minutes debugging a 200-line JavaScript file that AI wrote in 90 seconds. That ratio is real and it's painful.

What the Critics Get Wrong

They assume AI replaces thinking. It doesn't. It replaces typing. The thinking — architecture, design decisions, user experience, SEO strategy — all of that still comes from a human. AI is a force multiplier for execution, not a substitute for judgment.

They compare AI output to ideal human output. The fair comparison is AI output vs. what one developer can actually ship in a given timeframe. I could have built ToolKnit without AI. It would have taken 500 days instead of 100. And in those 400 extra days, I probably would have made just as many mistakes — just slower.

They ignore the solo developer economics. I'm one person. I don't have a team. I don't have a QA department. AI is my rubber duck, my code reviewer, my junior developer, and my documentation writer. For a solo founder, the alternative to "AI with careful review" isn't "pristine hand-written code." It's "shipping 15 tools instead of 89."

The Tools That Prove the Point

Some examples from ToolKnit where AI genuinely accelerated shipping:

Quit Smoking Tracker — A behavioral reinforcement tool with localStorage persistence, a 10-stage health recovery timeline (based on CDC/WHO research), achievement badges, and bilingual support. The core logic — calculating cigarettes avoided, money saved, life minutes regained — took about 4 prompts to implement. The health timeline component took another 3. Total dev time: ~2 hours.

Pomodoro Timer — Circular progress ring with SVG animation, three work/break modes, configurable durations, audio alerts, and tab title countdown. The SVG arc animation logic alone would have taken me an hour to write from scratch. AI generated it in one prompt. I spent 15 minutes fixing edge cases (what happens when the user switches tabs?).

PDF to Image — Converts PDF pages to PNG/JPG/WebP using pdf.js and canvas. This would have been a multi-day deep dive into the pdf.js API. AI knew the API surface area, generated the rendering pipeline, and handled the format conversion options. I verified correctness and fixed browser-specific rendering bugs.

The pattern repeats across all 89 tools. AI handles the API integration, the boilerplate, the repetitive patterns. I handle the architecture, the UX decisions, the edge cases, and the quality gate.

So Should You Use AI to Write Code?

In 2026, asking "should I use AI to code?" is like asking "should I use a framework?" in 2016. The answer depends on what you're building and who you are.

Use AI aggressively if:

You're a solo developer shipping a product
Your project has clear, repeatable patterns
You understand the code well enough to review it
Speed-to-market matters more than architectural elegance

Be skeptical of AI if:

You're building novel, performance-critical systems
You're a junior developer who can't evaluate AI output yet
Your project has complex state management or race conditions
You're working on security-sensitive infrastructure

The critical variable isn't the tool. It's whether you're capable of reviewing what the tool produces. If you can spot the bugs, AI is a multiplier. If you can't, AI is a liability.

This is why the most dangerous advice in tech right now is "just use AI, you don't need to learn to code." You absolutely need to learn to code. You just might not need to type as much.

The Bottom Line

109 days. 89 tools. 87 blog posts. DR 41. Real traffic from Google and Bing. All built by one person with AI assistance.

The hand-written code crowd isn't wrong about the risks. They're wrong about the conclusion. The goal shouldn't be hand-written code. The goal should be understood code — code where the developer, AI-assisted or not, knows what every line does and why it's there.

AI didn't build ToolKnit. I built ToolKnit. AI typed faster than I can. That's it. That's the entire magic trick.

And I don't regret a single prompt.

ToolKnit.com is a free, privacy-first online toolbox with 89 browser-based utilities. No uploads, no signup, no ads. All tools run entirely in your browser.

What's your experience with AI coding? Has it been a multiplier or a liability for your projects? I'm genuinely curious — especially if you're in the "going back to hand-written code" camp. Drop a comment.

From Web App to Native Desktop: Building ToolKnit with Tauri and a Dual-Source Installer

Zihang Dong 董子航 — Thu, 02 Jul 2026 11:08:05 +0000

The Problem We Wanted to Solve

Every day, developers, designers, and content creators juggle dozens of small tasks — merge a PDF, convert an audio file, compress an image, generate a QR code, polish some text with AI. The typical workflow? Open a browser, search for an online tool, upload your file, wait, download the result. Repeat for the next task. Repeat for the next tool.

The problems with this approach are obvious:

Privacy: You're uploading sensitive documents to random websites
Speed: Browser-based tools are slower than native processing
Fragmentation: Each tool lives on a different site with different UI
Offline: No internet, no tools

We wanted to build one desktop application that bundles all these utilities together — running locally, respecting privacy, and feeling like a native app.

This is the story of how ToolKnit went from a web prototype to a polished Windows .exe with a custom installer and dual-source CDN deployment.

Phase 1: The Web Prototype

Before committing to a desktop framework, we built a web-based prototype to validate the concept. The idea was simple: a single-page app with a sidebar navigation, dark theme, and tool cards for each category.

The prototype covered 9 tool categories:

Home — Dashboard with usage stats and navigation
PDF Tools — Merge, split, compress, encrypt/decrypt, rotate, watermark
Image Tools — Format conversion, batch compress, crop, collage, watermark removal
Audio Tools — Format conversion, clipping, BPM detection, channel processing
Video Tools — Format conversion, compression, screenshot extraction
Text Tools — Full/half-width conversion, case conversion, JSON formatting
Calculator Tools — Scientific computation, unit conversion, base conversion
Creative Tools — QR code generation, color picker, password generator
AI Tools — Translation, polishing, document generation, role play

The web prototype proved the concept, but it had limitations:

File processing required server-side APIs (or WASM, which was complex for video/audio)
Users had to be online
No drag-and-drop file system access
Browser security sandbox limited what we could do with local files

We needed to go native.

Phase 2: DR41 — The Tauri Migration

We evaluated several options for the desktop migration:

Framework	Bundle Size	Native Feel	Rust Ecosystem	Complexity
Electron	~150MB	Good	No	Low
Tauri	~12MB	Excellent	Yes	Medium
Flutter Desktop	~20MB	Good	No	Medium

We chose Tauri 2.x for three reasons:

Tiny bundle size — The final .exe is ~46MB (including FFmpeg), compared to Electron's typical 150MB+
Rust backend — Native performance for file processing, PDF manipulation, and media conversion
Web frontend — We could reuse our existing HTML/CSS/JS frontend almost entirely

Architecture

┌─────────────────────────────────────────┐
│           ToolKnit Desktop              │
├─────────────────────────────────────────┤
│  Frontend (HTML/CSS/JS)                 │
│  ├── Dark theme + WebGL background      │
│  ├── 9 tool category pages              │
│  ├── i18n (zh/en) with nested keys      │
│  └── Spider mascot loading animations   │
├─────────────────────────────────────────┤
│  Tauri Bridge (IPC)                     │
│  ├── invoke() commands                  │
│  ├── Event listeners                    │
│  └── Drag & drop file handling          │
├─────────────────────────────────────────┤
│  Rust Backend                            │
│  ├── PDF: pdf-lib-plus-encrypt          │
│  ├── Audio/Video: FFmpeg (bundled)      │
│  ├── Image: image crate                 │
│  ├── AI: DeepSeek/OpenAI/Qwen APIs      │
│  └── File system access                 │
├─────────────────────────────────────────┤
│  Native Window                          │
│  ├── Custom titlebar (no decorations)   │
│  ├── System tray with i18n menu         │
│  └── 1100x800 fixed size                │
└─────────────────────────────────────────┘

Key Technical Decisions

Custom window decorations: We disabled native window decorations (decorations: false) and built a custom titlebar with minimize/maximize/close buttons, plus a "always on top" toggle. This gave us full control over the visual design.

WebGL dynamic background: The home page features a custom WebGL shader that renders a flowing dark fluid animation. We optimized it by disabling anti-aliasing and alpha channels for performance:

const gl = canvas.getContext('webgl', {
  antialias: false,
  alpha: false,
  premultipliedAlpha: false
});

Bundled FFmpeg: Audio and video tools require FFmpeg. Instead of asking users to install it separately, we bundle a minimal FFmpeg binary and download it on first launch if needed. The download source is selected based on the user's language (more on this below).

i18n with nested keys: We use a nested JSON structure for translations, supporting both Chinese and English:

{
  "home": {
    "pdfDecrypt": {
      "title": "PDF Decrypt",
      "dropHere": "Drop your PDF here..."
    }
  }
}

The language is determined at startup by reading an install_lang.txt file that the installer writes during setup. This file contains the NSIS language ID (1033 for English, 2052 for Simplified Chinese).

Phase 3: The Installer

Distributing a Tauri app is straightforward — npm run tauri build produces an .exe. But we wanted more control over the installation experience.

Custom NSIS Installer

We built a separate Tauri-based installer (toolknit-installer) that:

Presents a visual wizard with language selection (Chinese/English)
Downloads the main program zip from CDN
Extracts it to the user's chosen path
Creates desktop shortcuts and start menu entries
Writes install_config.json and install_lang.txt for the main app to read

The installer itself is a Tauri app too — same tech stack, different purpose. It's only ~11.6MB.

Dual-Source CDN Deployment

Here's where it gets interesting. We serve users in both China and internationally. Network latency between China and overseas CDNs can be significant.

We deployed two object storage sources:

Source	Provider	Region	Use Case
R2	Cloudflare R2	Global (CDN)	International/English users
RainS3	RainS3	China (cn-nb1)	Chinese users

The download URL is selected based on the user's language preference:

let base_url = if language == "zh" {
    "https://toolknit.cn-nb1.rains3.com/toolknit-desktop.zip"
} else {
    "https://cdn.24picture.com/toolknit-desktop.zip"
};

Both sources are kept in sync using a Node.js upload script that pushes to both simultaneously:

// Upload zip (main program)
await uploadToClient(r2Client, r2Bucket, 'toolknit-desktop.zip', zipPath, 'application/zip', 'R2');
await uploadToClient(rainClient, rainBucket, 'toolknit-desktop.zip', zipPath, 'application/zip', 'RainS3');

// Upload installer exe
await uploadToClient(r2Client, r2Bucket, 'toolknit-installer.exe', installerPath, 'application/octet-stream', 'R2');
await uploadToClient(rainClient, rainBucket, 'toolknit-installer.exe', installerPath, 'application/octet-stream', 'RainS3');

The installer also has a fallback mechanism — if the primary source fails, it automatically tries the other source:

let urls = [
    format!("{}?_t={}", base_url, ts),
    format!("{}?_t={}", fallback_url, ts),
];

We append a timestamp parameter to bust CDN cache, ensuring users always get the latest version.

Phase 4: The Download Page

The final piece was a beautiful download page at toolknit.com. We wanted it to showcase the app's features with smooth parallax scrolling and full bilingual support.

Parallax Scrolling with Layered Effects

Each of the 9 tool categories gets its own scrolling module with alternating image/text layouts. We implemented 4 layers of parallax:

Hero section — Title, subtitle, and description each move at different speeds
Module images — Images translate at a different rate than the scroll
Module content — Text content moves at its own pace, with sub-elements (tag, title, description, features, stats) each having individual data-speed values
Image scaling — Images subtly scale based on scroll position for depth

// Each element has a data-speed attribute
const offset = (elementCenter - viewportCenter) * speed;
el.style.transform = `translateY(${offset}px)`;

Language-Aware Screenshots

The download page supports both English and Chinese. When the user switches languages, not only does the text change, but the screenshots change too — English screenshots show the English UI, Chinese screenshots show the Chinese UI:

const prefix = lang === 'en' ? '1-' : '';
document.querySelectorAll('.module-image img').forEach((img, i) => {
    img.src = `https://24picture.com/${prefix}${i + 1}.webp`;
});

The language preference is saved to localStorage, so returning users see their preferred language automatically.

Download Logic

The download buttons on the page follow the same dual-source logic as the installer:

const DOWNLOAD_URLS = {
    en: 'https://cdn.24picture.com/toolknit-installer.exe',
    zh: 'https://toolknit.cn-nb1.rains3.com/toolknit-installer.exe'
};

function handleDownload(e) {
    e.preventDefault();
    const lang = localStorage.getItem('toolknit-lang') || 'en';
    window.open(DOWNLOAD_URLS[lang], '_blank');
}

Lessons Learned

1. Tauri's CSP is strict but worth it

Tauri enforces a strict Content Security Policy. Every external domain your app connects to must be whitelisted in tauri.conf.json. This forced us to be explicit about our API endpoints and CDN URLs — which is actually a good security practice.

2. File locks on Windows are painful

During development, the Rust compiler would sometimes fail with os error 32 (file in use) because the previous build's .exe was still running. Our solution: a kill script that runs before every build:

taskkill /F /IM toolknit-desktop.exe 2>$null
taskkill /F /IM cargo.exe 2>$null

For first-time full builds, we also set CARGO_BUILD_JOBS=1 to avoid concurrent file access.

3. Dual-source deployment is simpler than it sounds

Using S3-compatible APIs for both Cloudflare R2 and RainS3 means we can use the same AWS SDK code for both. The only difference is the endpoint and credentials. One script, two uploads, done.

4. The installer is part of the product

A great app with a terrible install experience still feels bad. Building a custom Tauri-based installer let us control the entire user journey — from download to first launch — with proper language detection and a clean wizard UI.

Tech Stack Summary

Layer	Technology
Desktop Framework	Tauri 2.x
Frontend	Vanilla HTML/CSS/JS
Backend	Rust
PDF Processing	pdf-lib-plus-encrypt
Audio/Video	FFmpeg (bundled)
Image Processing	image crate
AI Integration	DeepSeek, OpenAI, Qwen APIs
Icons	Lucide Icons
Object Storage	Cloudflare R2 + RainS3
Upload Script	Node.js + AWS SDK v3
Smooth Scroll	Lenis
Background	Custom WebGL shader

What's Next

ToolKnit is currently in v1.0 Beta for Windows. We're planning:

macOS and Linux support
Plugin system for community-contributed tools
More AI-powered features
Auto-update mechanism

Try It Out

ToolKnit is free and open for everyone. Download the installer for your platform:

International users: Download from CDN
China users: Download from RainS3

Visit toolknit.com to see the full feature showcase, or check out our blog for more development stories.

If you found this article helpful, consider giving it a reaction or following for more posts about desktop development with Tauri, Rust, and modern web technologies.

100 Days, 87 Tools, Zero Servers: What I Learned Building a Fully Client-Side Utility Suite

Zihang Dong 董子航 — Fri, 26 Jun 2026 10:22:35 +0000

On March 18, 2026, I launched a side project called ToolKnit — a collection of free browser-based tools that process everything locally. No uploads, no signup, no backend beyond a tiny PHP stats endpoint. Yesterday was day 100. This is what I learned about architecture, performance, and the limits of "just use the browser."

The Premise

Most online tool sites follow the same pattern: upload your file → server processes it → download the result. This means your sensitive documents (PDFs, photos, audio recordings) sit on someone else's server, even if only briefly.

ToolKnit's premise was simple: what if every tool ran entirely in the browser?

Not "mostly client-side with a fallback API." Not "client-side for small files, server for large ones." Entirely. Every PDF merge, every image resize, every audio conversion, every QR code generation — all happening in the user's browser via Web APIs, with zero bytes leaving their device.

100 days in, the site has 87 tools across 10 categories. Here's what worked, what didn't, and what I'd do differently.

The Stack: Boring on Purpose

HTML + Tailwind CSS + Vanilla JS
PHP (stats endpoint only)
scp for deployment

No React. No Vue. No build step beyond Tailwind compilation. No CI/CD pipeline. No Docker containers. No Kubernetes.

Why static HTML for 87 tool pages?

SEO is non-negotiable for a tool site. Static HTML means Google crawls everything immediately — no hydration delays, no client-side routing, no JavaScript-required indexing. Every page is a complete document with full Open Graph tags, Twitter Cards, and JSON-LD structured data.
Performance budget is tight. Users landing on a "compress PDF" page from Google Search expect the tool to work now, not after a 2 MB JS bundle downloads and hydrates. Most ToolKnit tools work without any framework — progressive enhancement is the default.
Server costs are near zero. The only PHP endpoints are track.php (receives usage beacons) and public-stats.php (serves aggregated metrics). Everything else — PDF manipulation via pdf-lib.js, image processing via Canvas API, audio encoding via Web Audio API, video transcoding via ffmpeg.wasm — runs in the browser.

The tradeoff: Manual consistency across 87 HTML files. When you add a new footer link, you're editing 87 files (or writing a Python script to do it, then verifying each one). There's no component system to save you.

What Actually Works in the Browser

PDF Processing — Better Than Expected

pdf-lib.js handles PDF merge, split, compress, and page-to-image conversion entirely client-side. The only server-side fallback is pdf-to-word.php for extreme edge cases where client-side extraction fails — and even that strips identifying metadata before processing.

Surprise: PDF compression was the hardest. "Compress" sounds simple until you realize it means recompressing embedded images at lower JPEG quality, removing duplicate font subsets, and stripping unused objects — all without corrupting the file structure. The browser does this well, but the implementation is 400+ lines of careful stream manipulation.

Image Tools — Canvas API Is Underrated

17 image tools run on plain Canvas API:

Resize, crop, grid split, format conversion (JPG/PNG/WebP), circle crop, silk-screen halftone effect, background removal (via color thresholding), HEIC conversion (via heic2any)
The imageSmoothingEnabled = false flag is your best friend for pixel-perfect operations
willReadRecently: true on getContext('2d') eliminates console warnings when you call getImageData frequently

Audio — Web Audio API Is Powerful but Quirky

A MIDI keyboard with 8 synthesized timbres (Grand Piano, Pipa, Guitar, Flute, Music Box, and more) — all generated in real-time through oscillator nodes, custom harmonics, and resonant filters.

Key learning: "Piano sound" isn't one oscillator. Each timbre required distinct synthesis architecture. The Pipa (琵琶) timbre needed sawtooth + square waves with non-integer harmonics (5.04×, 7.01× fundamental) to simulate the metallic twang of plucked silk strings, plus a noise burst layer for the finger-pick attack transient. Without that noise burst, it sounds like a cheap synth preset.

Video — ffmpeg.wasm Works, But...

ffmpeg.wasm enables browser-side video compression and format conversion. It works. But the ~32 MB one-time Worker download is a real cost on slow connections. I'm still evaluating whether this belongs in a "zero upload" toolkit or whether the download size undermines the value proposition.

What Doesn't Work in the Browser

Live Photo Frame — Killed After 48 Hours

The idea: frame iPhone Live Photos (HEIC + MOV pairs) and Android Motion Photos in elegant layouts, export to video.

Three fatal flaws:

Canvas quadraticCurveTo draws parabolas, not circular arcs. At corner radii above ~60px, "rounded corners" morph into chamfered edges. The visual signature of the tool was mathematically impossible with the Canvas API I was using. (The fix is arc() with tangent calculations, but by then I'd lost confidence in the concept.)
HEVC/H.265 videos from Android Motion Photos don't play natively in Chrome. ffmpeg.wasm transcoding at 1080×1920 was 30+ seconds for a 3-second clip. Users don't wait 30 seconds.
WeChat strips 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 core use case didn't exist in the real world.

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-Generated Pixel Art — Twice Bitten

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

Second attempt: Local Canvas pixelation + gif.js encoding + color analysis. Solid engineering. The output just wasn't compelling. Pixel art demands either perfect algorithmic control or genuine artistic AI — we had neither.

Lesson: "It works" ≠ "it's worth shipping." I killed both versions.

The Bilingual Architecture — A Two-Layer Approach

After 60+ tools, I needed bilingual support (English + Chinese). The challenge: no framework, no build step, 87 static HTML files.

Solution: two-layer i18n without a framework.

Layer	File	Scope
Shared UI	`bilingual.js`	Nav, footer, breadcrumb, related tools, modals
Page-specific	`[tool].js`	Hero, How It Works, Why Use, Pro Tips, FAQ
Homepage	`i18n.js` + `zh.json`	Tool card titles, stats, search

How it works:

// HTML: <span data-i18n="heroTitle">Compress PDF Files</span>
// JS:   heroTitle: { en: 'Compress PDF Files', zh: '压缩 PDF 文件' }

function applyI18n(lang) {
    document.querySelectorAll('[data-i18n]').forEach(function(el) {
        var key = el.getAttribute('data-i18n');
        var dict = I18N[lang];
        if (dict && dict[key]) {
            if (el.tagName === 'INPUT') el.placeholder = dict[key];
            else if (el.tagName === 'OPTION') el.textContent = dict[key];
            else el.innerHTML = dict[key];
        }
    });
}

window.switchLang(lang) triggers both layers simultaneously. Language preference persists via localStorage and syncs across pages.

Gotchas I hit:

data-i18n on a parent with SVG children = disaster. innerHTML assignment wipes the SVG. Always put data-i18n on a sibling <span>, never on a structural parent.
Unescaped single quotes in i18n dictionaries silently break window.switchLang. One there's without a backslash killed the entire language system.
Batch data-i18n injection scripts silently fail when HTML entities (—) don't match Unicode characters (—). Always verify with a key checklist after migration.

The 100-Day Celebration — A Small Experiment

For day 100, I wanted to do something fun. I built a full-screen fireworks animation using Canvas API that would automatically appear on the homepage for 24 hours.

function launchFirework(x, y) {
    var colors = ['#6366f1','#a855f7','#f59e0b','#ef4444','#22c55e','#3b82f6','#ec4899','#fff'];
    var color = colors[Math.floor(Math.random() * colors.length)];
    var count = 60 + Math.floor(Math.random() * 40);
    for (var i = 0; i < count; i++) {
        var angle = (Math.PI * 2 * i) / count + (Math.random() - 0.5) * 0.3;
        var speed = 2 + Math.random() * 4;
        particles.push({
            x: x, y: y,
            vx: Math.cos(angle) * speed,
            vy: Math.sin(angle) * speed,
            life: 1,
            decay: 0.008 + Math.random() * 0.012,
            color: color,
            size: 1.5 + Math.random() * 2
        });
    }
}

The fireworks canvas uses clearRect (not a semi-transparent fill) so particles render crisply against the overlay. An IntersectionObserver starts/stops the animation when the changelog entry scrolls into view — no wasted CPU when off-screen.

Performance note: The entire celebration code — CSS, HTML, JS, fireworks — is inlined in index.html. After day 101, the IIFE returns immediately on the first line. Zero overhead for the remaining lifespan of the site.

I don't know how many people saw it. That's part of the fun.

The Desktop Client — Same Tools, Offline

Now I'm building a Windows desktop app using Tauri 2 + Rust. Same principle: all processing happens locally. The Rust backend handles PDF operations via lopdf (split/merge) and pdfium (render to images), while the UI reuses the Vanilla JS frontend.

The web version isn't going anywhere. The desktop client is for users who want a native app experience — drag-and-drop without a browser tab, offline-first, system-level file access.

Numbers After 100 Days

Metric	Value
Tools shipped	87
Tools killed after shipping	3
Bilingual pages migrated	19 of 87
Blog guides published	86
Service Worker cache version	v144
Total uses	3,000+
Server-side code	2 PHP files (stats only)
Framework dependencies	0

What I'd Tell Someone Starting a Similar Project

Static HTML scales further than you think. 87 pages with no framework is manageable if you're disciplined about shared CSS/JS and write verification scripts for batch changes.
The browser can do more than you expect. PDF manipulation, audio synthesis, video transcoding, image processing — all viable client-side. The main limitation isn't capability; it's download size for WASM libraries.
Kill features that "almost work." Live Photo Frame taught me that three near-fatal flaws compound, they don't cancel out. A tool that's 90% right erodes more trust than a missing tool page.
Inline celebration code and clean up after yourself. The fireworks animation was fun to build, but the real engineering was making sure it costs zero bytes of overhead after day 101.
data-i18n on SVG parents will haunt you. Test language toggles on every page, every time.

What's Next

The remaining 68 legacy pages will migrate to the bilingual architecture gradually. The desktop client is in active development. New tools are still shipping — the 87th tool (Text Animation Maker with real MP4 export via WebCodecs) went live on June 23.

If you're curious about the full build history, the changelog is more honest than most — it includes the features that died, the bugs that took hours to find, and the occasional developer's journal entry that has nothing to do with code.

No signup. No uploads. No tracking beyond a usage counter. Just tools that work in your browser because that's where your files already are.

If you're building something client-side, I'd love to hear about your architecture decisions. What did you try that didn't work? What surprised you about the browser's capabilities? Drop a comment — I read all of them.

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. 🛠️