<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Zihang Dong 董子航</title>
    <description>The latest articles on DEV Community by Zihang Dong 董子航 (@dngzihng114379).</description>
    <link>https://dev.to/dngzihng114379</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3855987%2Fdd1ab560-0150-40f1-accb-88eadf95c919.png</url>
      <title>DEV Community: Zihang Dong 董子航</title>
      <link>https://dev.to/dngzihng114379</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/dngzihng114379"/>
    <language>en</language>
    <item>
      <title>Building PDF to Word with local OCR in the browser: what we chose not to promise</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Mon, 16 Nov 2026 02:08:11 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/building-pdf-to-word-with-local-ocr-in-the-browser-what-we-chose-not-to-promise-4j6h</link>
      <guid>https://dev.to/dngzihng114379/building-pdf-to-word-with-local-ocr-in-the-browser-what-we-chose-not-to-promise-4j6h</guid>
      <description>&lt;p&gt;Disclosure up front: I build ToolKnit, and this post is about how its &lt;a href="https://toolknit.com/tools/pdf-to-word.html" rel="noopener noreferrer"&gt;PDF to Word converter&lt;/a&gt; got local OCR for scanned pages. I'm writing it because the hard parts were more about honesty and UX than about algorithms.&lt;/p&gt;

&lt;h2&gt;
  
  
  Constraint: the document never leaves the device
&lt;/h2&gt;

&lt;p&gt;The goal was a DOCX from a text PDF &lt;em&gt;or&lt;/em&gt; a scanned one, with no upload, no account and no AI key. That rules out sending pages to a cloud OCR API. Everything has to run in the tab.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Native text first, OCR second
&lt;/h2&gt;

&lt;p&gt;If a PDF already has a text layer, OCR only adds errors. The engine reads text &lt;em&gt;and&lt;/em&gt; drawing instructions first, using positions and font information to rebuild reading order, columns and tables. OCR only runs on pages that are really just images.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. OCR components are installed once, on demand
&lt;/h2&gt;

&lt;p&gt;OCR models and the runtime are much larger than the page itself. Loading them on every visit would hurt everyone who only converts text PDFs. Instead:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Nothing heavy is loaded until you click &lt;strong&gt;Process&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;If components are missing, a first-run dialog asks to download them, &lt;strong&gt;verifies&lt;/strong&gt; the files, then continues the job automatically.&lt;/li&gt;
&lt;li&gt;Verified components stay in a separate browser cache, so normal site updates don't evict them. If the browser clears storage, you may need to reinstall.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The privacy line is precise on purpose: only public processing components are downloaded. Your PDF, its password, the page images and the DOCX stay on the device. Ordinary visit statistics may still be sent, and the page says so.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Don't pretend everything is editable
&lt;/h2&gt;

&lt;p&gt;This was the biggest product decision. Tools that claim "perfect conversion" leave users to find the broken tables later. We went the other way:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Recognized tables become real Word tables &lt;strong&gt;only when the layout passes the engine's checks&lt;/strong&gt;. Otherwise they stay as positioned text or an image.&lt;/li&gt;
&lt;li&gt;Complex figures and some formulas remain pictures.&lt;/li&gt;
&lt;li&gt;The default "keep original pages" mode prioritizes page geometry, which suits forms and reports. It is not the same as a freely reflowing Word document.&lt;/li&gt;
&lt;li&gt;After conversion, the counts describe what happened ("N tables rebuilt"), not a "correctness score".&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  4. Page selection before work starts
&lt;/h2&gt;

&lt;p&gt;Big PDFs (up to 100 MiB can be opened) shouldn't be processed blindly. After reading, a page chooser opens automatically: process all pages, or pick pages from thumbnails. Confirming starts the conversion directly.&lt;/p&gt;

&lt;h2&gt;
  
  
  Lessons
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Only show a progress bar if it is driven by real work, and let users cancel.&lt;/li&gt;
&lt;li&gt;Put limits on the page, not in a support doc.&lt;/li&gt;
&lt;li&gt;Give people an honest alternative. If you just need the page unchanged, PDF to Image is the better tool, and we link to it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you've shipped in-browser OCR, I'd like to hear how you handled model size and caching.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Drafted with AI assistance; technical claims checked against the live tool page.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>javascript</category>
      <category>pdf</category>
      <category>privacy</category>
    </item>
    <item>
      <title>parseFloat() will quietly change your 17-digit numbers — spelling out amounts with BigInt instead</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Sun, 15 Nov 2026 06:51:29 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/parsefloat-will-quietly-change-your-17-digit-numbers-spelling-out-amounts-with-bigint-instead-1852</link>
      <guid>https://dev.to/dngzihng114379/parsefloat-will-quietly-change-your-17-digit-numbers-spelling-out-amounts-with-bigint-instead-1852</guid>
      <description>&lt;p&gt;Try this in any browser console:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nb"&gt;parseFloat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"9007199254740993"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="c1"&gt;// 9007199254740992&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No error, no warning — the last digit just changes. JavaScript numbers are IEEE-754 doubles with a 53-bit significand, so integers above &lt;code&gt;Number.MAX_SAFE_INTEGER&lt;/code&gt; (9,007,199,254,740,991) can't all be represented.&lt;/p&gt;

&lt;p&gt;Usually that doesn't matter. It matters a lot when you convert a number into &lt;strong&gt;words&lt;/strong&gt;: check amounts, invoice lines, contract values, or Chinese RMB financial uppercase (人民币大写). If the number is wrong before you start, every word after it is wrong too.&lt;/p&gt;

&lt;h2&gt;
  
  
  Approach: treat the input as a string
&lt;/h2&gt;

&lt;p&gt;The fix is simple: never turn the input into a &lt;code&gt;Number&lt;/code&gt;.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Clean the input (&lt;code&gt;$1,234.56&lt;/code&gt; → &lt;code&gt;"1234.56"&lt;/code&gt;) and split on the decimal point.&lt;/li&gt;
&lt;li&gt;Keep the integer part as a digit string, or use &lt;code&gt;BigInt&lt;/code&gt; when you need arithmetic.&lt;/li&gt;
&lt;li&gt;Walk the digits in groups — &lt;strong&gt;3-digit groups&lt;/strong&gt; for English short scale (thousand, million, billion = 10⁹, trillion = 10¹² …) and &lt;strong&gt;4-digit groups&lt;/strong&gt; for Chinese (万, 亿).&lt;/li&gt;
&lt;li&gt;Format the fractional part as digits too, never as &lt;code&gt;0.56 * 100&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;A minimal grouping helper:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;groups&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;intStr&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;size&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;out&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;intStr&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="o"&gt;-=&lt;/span&gt; &lt;span class="n"&gt;size&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;out&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;unshift&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;intStr&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;size&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;out&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// "1234567" -&amp;gt; ["1", "234", "567"]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;ones&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"One"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Two"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Three"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Four"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Five"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Six"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Seven"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Eight"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Nine"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"Ten"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Eleven"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Twelve"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Thirteen"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Fourteen"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Fifteen"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Sixteen"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Seventeen"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"Eighteen"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Nineteen"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;tens&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Twenty"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Thirty"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Forty"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Fifty"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Sixty"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Seventy"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Eighty"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Ninety"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;threeDigits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// safe: always &amp;lt; 1000&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;h&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="o"&gt;%&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;h&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ones&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;h&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s2"&gt;" Hundred"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ones&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;tens&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="o"&gt;%&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s2"&gt;"-"&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;ones&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="o"&gt;%&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;" "&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Using &lt;code&gt;Number()&lt;/code&gt; &lt;em&gt;inside&lt;/em&gt; a three-digit chunk is fine, because each chunk is less than 1000. The precision bug only appears when the whole value goes through floating point.&lt;/p&gt;

&lt;h2&gt;
  
  
  Check-writing rules people miss
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;On US checks, the word "and" separates dollars from cents: &lt;code&gt;One Thousand Two Hundred Thirty-Four and 56/100&lt;/code&gt;. Avoid "One Hundred &lt;strong&gt;and&lt;/strong&gt; Twenty" on the amount line.&lt;/li&gt;
&lt;li&gt;Compound numbers from 21 to 99 take a hyphen: &lt;code&gt;Forty-Two&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;It's &lt;strong&gt;Forty&lt;/strong&gt;, not "Fourty". That's the most common spelling mistake on handwritten checks.&lt;/li&gt;
&lt;li&gt;In RMB uppercase, whole-yuan amounts end with &lt;code&gt;元整&lt;/code&gt;, while amounts that end in 分 drop the &lt;code&gt;整&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Test values worth keeping
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;1234.56                  -&amp;gt; One Thousand Two Hundred Thirty-Four and 56/100
100200.05                -&amp;gt; watch the zero handling in both English and Chinese
9007199254740993         -&amp;gt; fails with parseFloat; must survive unchanged
24-digit integers        -&amp;gt; forces BigInt/string path
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  If you just need the output
&lt;/h2&gt;

&lt;p&gt;Disclosure: I build ToolKnit, and this post grew out of writing its &lt;a href="https://toolknit.com/tools/number-to-words.html" rel="noopener noreferrer"&gt;Number to Words converter&lt;/a&gt;. It uses the string/BigInt approach above for up to 36 integer digits and 12 decimals, and outputs English words, an XX/100 check line (USD/EUR/GBP/CAD/AUD), ordinals and RMB uppercase. It runs in the browser. You should still check your bank's or contract's own formatting rules before issuing a real check.&lt;/p&gt;

&lt;p&gt;If you write your own, start with that &lt;code&gt;9007199254740993&lt;/code&gt; test case.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Drafted with AI assistance; code and facts reviewed before publishing.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>webdev</category>
      <category>beginners</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Your Aim Trainer Score Went Up. Did Your Aim Actually Improve?</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Fri, 06 Nov 2026 09:06:34 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/your-aim-trainer-score-went-up-did-your-aim-actually-improve-4imk</link>
      <guid>https://dev.to/dngzihng114379/your-aim-trainer-score-went-up-did-your-aim-actually-improve-4imk</guid>
      <description>&lt;p&gt;A faster time can mean better control. It can also mean bigger targets, a different mouse, or a run with fewer misses hidden in the average. Before treating one number as progress, make sure the next round is answering the same question as the last one.&lt;/p&gt;

&lt;p&gt;This is a practical way to design a small pointing experiment in the browser: choose a skill, hold the conditions steady, and read each result alongside its denominator. You can apply it to many trainers. I'll use the &lt;a href="https://toolknit.com/tools/aim-trainer.html" rel="noopener noreferrer"&gt;ToolKnit Aim Trainer&lt;/a&gt; as a concrete example; I develop ToolKnit, so this is my own tool.&lt;/p&gt;

&lt;h2&gt;
  
  
  First, decide what you are actually practising
&lt;/h2&gt;

&lt;p&gt;“Aim” is not one indivisible skill. A short exercise may isolate one part of the task while removing the rest:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Drill&lt;/th&gt;
&lt;th&gt;Your immediate task&lt;/th&gt;
&lt;th&gt;What it does not establish&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Stationary point and click&lt;/td&gt;
&lt;td&gt;Move onto a visible target, then click&lt;/td&gt;
&lt;td&gt;Game awareness or movement under pressure&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Headshot-only&lt;/td&gt;
&lt;td&gt;Place a shot on a smaller region&lt;/td&gt;
&lt;td&gt;Whether a body shot would have been strategically better&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Moving-target tracking&lt;/td&gt;
&lt;td&gt;Keep the crosshair on a moving region&lt;/td&gt;
&lt;td&gt;Accuracy while counter-strafing or reacting to opponents&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;In-game practice&lt;/td&gt;
&lt;td&gt;Coordinate aiming with the actual game's movement and rules&lt;/td&gt;
&lt;td&gt;A clean measurement of pointing alone&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;These exercises complement one another. A browser range with a fixed player position cannot recreate the full set of decisions, movement, latency and visual clutter in a match. A good score is useful feedback for the drill, not a promise of better rank.&lt;/p&gt;

&lt;p&gt;[Screenshot: basic practice settings — image pending upload]&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Actual interface: basic practice lets you choose a target count and size before starting. The 3D range has its own settings.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Build a baseline that you can repeat
&lt;/h2&gt;

&lt;p&gt;Start with a simple question: &lt;strong&gt;Can I point to stationary targets reliably without rushing?&lt;/strong&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Choose one device and input method. Keep the mouse, mouse pad, display scaling and browser zoom consistent.&lt;/li&gt;
&lt;li&gt;Select the basic drill, a target size and a target count. Write those choices down.&lt;/li&gt;
&lt;li&gt;Do a comfortable warm-up round, then complete three rounds with those same settings.&lt;/li&gt;
&lt;li&gt;Record the result for each round, including misses if shown. Keep all three rather than saving only the best one.&lt;/li&gt;
&lt;li&gt;Stop if your hand or wrist feels uncomfortable. Take breaks; longer is not automatically better.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Three rounds are a starting point, not a scientific sample size. Random target positions, warm-up, fatigue and ordinary variation can all change the outcome. Repeat the same setup over multiple sessions before drawing a strong conclusion.&lt;/p&gt;

&lt;h3&gt;
  
  
  A worked example, not a benchmark
&lt;/h3&gt;

&lt;p&gt;Suppose two rounds both finish 20 targets:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Round&lt;/th&gt;
&lt;th&gt;Elapsed time&lt;/th&gt;
&lt;th&gt;Misses&lt;/th&gt;
&lt;th&gt;What to notice&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;25 s&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;Slower, with few misses&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;B&lt;/td&gt;
&lt;td&gt;22 s&lt;/td&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;Faster completion, but many more missed clicks&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;These are &lt;strong&gt;illustrative numbers&lt;/strong&gt;, not measurements from a user or the screenshot. If your goal is reliable pointing, B is not automatically the better round. Decide in advance what matters: fewer misses, shorter time at a comparable miss rate, or a balance of both. Changing your criterion after seeing a high score makes the comparison less useful.&lt;/p&gt;

&lt;p&gt;If you calculate click accuracy, define it as successful hits divided by all attempts, including misses. For a drill where each target needs one successful click, 20 hits and 8 misses give 20 / 28, or about 71%. Do not treat time per target as pure reaction time: it also includes moving the pointer, deciding when to click and whatever the interface adds.&lt;/p&gt;

&lt;h2&gt;
  
  
  Change one variable, not five
&lt;/h2&gt;

&lt;p&gt;After a baseline, form a specific question. For example: &lt;strong&gt;What happens when the target becomes smaller?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Keep the device, round length, input method and mouse settings fixed. Run the same number of rounds at medium and small target sizes. Alternate the order across sessions (medium → small one day; small → medium another day) to reduce the chance that simple warm-up explains the entire difference.&lt;/p&gt;

&lt;p&gt;Compare the &lt;em&gt;pattern&lt;/em&gt;, not just the best score:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Did time rise while misses stayed about the same?&lt;/li&gt;
&lt;li&gt;Did misses increase while time barely changed?&lt;/li&gt;
&lt;li&gt;Did both change, suggesting a speed–accuracy trade-off?&lt;/li&gt;
&lt;li&gt;Are the results inconsistent enough that you need more sessions before interpreting them?&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The target layouts are still random, so alternating order does not make this a controlled laboratory study. It simply makes your own comparison less misleading.&lt;/p&gt;

&lt;h2&gt;
  
  
  Then add motion deliberately
&lt;/h2&gt;

&lt;p&gt;The ToolKnit 3D range keeps your position fixed while the mannequin moves. The setup separates movement speed from direction-change difficulty, so you can introduce them one at a time. Speed zero makes the target stationary.&lt;/p&gt;

&lt;p&gt;[Screenshot: 3D range — image pending upload]&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Actual 3D range using the drag-to-look fallback after mouse lock was declined in the browser. The timer in this image is not a performance result.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Try this progression:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Stationary, body and head:&lt;/strong&gt; learn the view controls and place deliberate shots.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Stationary, headshot-only:&lt;/strong&gt; keep speed at zero and focus on placing the shot on the head. In this mode, a body hit is still a shot but does not complete the target.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Moving target, simple direction pattern:&lt;/strong&gt; use a comfortable speed and keep the same distance and difficulty across rounds.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Head tracking:&lt;/strong&gt; follow the head without shooting. The useful measure is the share of active time the crosshair is on the head, not the number of clicks.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;In the trainer, hit accuracy is mannequin hits divided by valid shots; head-hit rate uses head hits divided by valid shots. Tracking coverage uses observed on-head time divided by active training time. These are different measurements, so do not compare a tracking percentage directly with shot accuracy.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make the interface work for you
&lt;/h2&gt;

&lt;p&gt;Use a crosshair that remains visible against both the background and target. The trainer offers crosshair adjustments and contrast choices; visibility matters more than copying someone else's colour. If a moving target feels too difficult to follow, reduce speed first instead of changing speed, distance and sensitivity together.&lt;/p&gt;

&lt;p&gt;On desktop, the 3D range can request mouse lock; full screen is optional. Browser support and permission behaviour vary. In my browser check, mouse lock was declined and the interface offered drag-to-look with a separate fire control. On touch devices, landscape orientation and drag controls are available where supported. If the 3D engine is unavailable, the basic drill is a useful fallback.&lt;/p&gt;

&lt;p&gt;One important caveat: the trainer's sensitivity slider is &lt;strong&gt;not&lt;/strong&gt; a verified conversion to Valorant, Counter-Strike or another game's settings. DPI, field of view, browser input and game settings can differ. Keep your setup consistent within the trainer; calibrate inside each game separately.&lt;/p&gt;

&lt;h2&gt;
  
  
  A short routine you can actually keep
&lt;/h2&gt;

&lt;p&gt;This is an example schedule, not a prescription or a guaranteed path to improvement:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Time&lt;/th&gt;
&lt;th&gt;Activity&lt;/th&gt;
&lt;th&gt;Focus&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2 minutes&lt;/td&gt;
&lt;td&gt;Easy stationary targets&lt;/td&gt;
&lt;td&gt;Comfortable movement and deliberate clicks&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3 minutes&lt;/td&gt;
&lt;td&gt;Headshot-only at low or zero speed&lt;/td&gt;
&lt;td&gt;Small corrections, not frantic clicking&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3 minutes&lt;/td&gt;
&lt;td&gt;Moving-target tracking&lt;/td&gt;
&lt;td&gt;Smooth following rather than shooting&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2 minutes&lt;/td&gt;
&lt;td&gt;Review matching rounds&lt;/td&gt;
&lt;td&gt;Note settings, misses and how the session felt&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Adjust the duration or stop early when needed. If your goal is a specific game, spend time in that game's own practice range too: target movement, recoil, positioning and decisions are part of the task. No browser drill alone can test all of those.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a result can and cannot tell you
&lt;/h2&gt;

&lt;p&gt;A useful comparison answers a narrow question: “Under similar conditions, did I complete this particular drill more consistently?” It cannot prove how you will perform in a match, diagnose a medical condition, or explain why a single run was unusually good or bad.&lt;/p&gt;

&lt;p&gt;The trainer stores its settings and history in the current browser rather than an account; clearing browser data can remove them. The site's ordinary visit analytics are separate from that history. If you compare results on another device or after changing a major setting, treat it as a new baseline.&lt;/p&gt;

&lt;p&gt;The practical takeaway is simple: &lt;strong&gt;make the exercise repeatable before making the score important&lt;/strong&gt;. A few carefully compared rounds can tell you more about your own control than one exciting personal best.&lt;/p&gt;

</description>
      <category>learning</category>
      <category>productivity</category>
      <category>tools</category>
    </item>
    <item>
      <title>Frame Rate Is Not a Stopwatch: Designing Honest Browser Aim Metrics</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Mon, 02 Nov 2026 07:58:43 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/frame-rate-is-not-a-stopwatch-designing-honest-browser-aim-metrics-3mid</link>
      <guid>https://dev.to/dngzihng114379/frame-rate-is-not-a-stopwatch-designing-honest-browser-aim-metrics-3mid</guid>
      <description>&lt;p&gt;A browser aim trainer is a useful small systems problem: the interface looks like a game, but its output looks like a measurement. That mismatch is where bugs become misleading claims.&lt;/p&gt;

&lt;p&gt;Rendering a target is straightforward. Deciding what counts as a shot, how much time a hidden tab earns, and whether two rounds are comparable requires a more explicit contract.&lt;/p&gt;

&lt;p&gt;This tutorial develops that contract with small, executable JavaScript examples. The implementation context is the &lt;a href="https://toolknit.com/zh/tools/aim-trainer.html" rel="noopener noreferrer"&gt;browser aim trainer I maintain at ToolKnit&lt;/a&gt;, which has separate click, body-hit, headshot, and head-tracking tasks. That is a case reference, not evidence of improved game performance. This article was prepared with AI assistance and checked against the implementation; examples below are simplified teaching code rather than a complete copy of the application.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with three different clocks
&lt;/h2&gt;

&lt;p&gt;An interactive task usually has at least three notions of time:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Wall time:&lt;/strong&gt; how long the person has had the page open.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Active task time:&lt;/strong&gt; how long a valid round has actually been running.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Observed tracking time:&lt;/strong&gt; the active intervals for which the application has observations supporting an on-target classification.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;They answer different questions. A countdown belongs to the interface, not necessarily the scored task. A pause belongs in the history of a round, but should not silently earn tracking credit. An unknown interval should not become a positive observation merely because the next frame looks good.&lt;/p&gt;

&lt;p&gt;Writing &lt;code&gt;elapsed += 1000 / 60&lt;/code&gt; in every animation callback confuses frame count with time. Switching to timestamps fixes that particular bug, but does not answer the semantic questions.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame" rel="noopener noreferrer"&gt;MDN documents&lt;/a&gt; that animation callbacks generally follow display refresh and are paused in most browsers in background tabs. Frame-driven measurements must account for both behaviors.&lt;/p&gt;

&lt;h2&gt;
  
  
  Define a clock that can reject an interval
&lt;/h2&gt;

&lt;p&gt;Here is a minimal active clock. The caller provides timestamps, making the arithmetic testable without a browser:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;ActiveClock&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;maxGapMs&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;250&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;maxGapMs&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;maxGapMs&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;elapsed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;last&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="nf"&gt;resume&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;now&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;last&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;now&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="nf"&gt;pause&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;last&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="nf"&gt;advance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;now&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;last&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;dt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;gap&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;dt&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;now&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;last&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;last&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;now&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;dt&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;maxGapMs&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;last&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;dt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;gap&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;elapsed&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;dt&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;dt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;gap&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;clock&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ActiveClock&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="nx"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resume&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;advance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1016&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nx"&gt;dt&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;advance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;5000&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nx"&gt;gap&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;elapsed&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;advance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;5016&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nx"&gt;dt&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The last assertion matters. Rejecting a long interval also disarms the clock. The next animation callback cannot resume it accidentally; a deliberate transition must call &lt;code&gt;resume()&lt;/code&gt; again.&lt;/p&gt;

&lt;p&gt;The 250 ms cutoff is an application policy used in this example, not a web standard, a measured latency guarantee, or a scientific boundary. A severe performance stall can trigger it even when the player never left the page. That is a tradeoff: prefer an interrupted round over pretending an unobserved interval was valid practice.&lt;/p&gt;

&lt;p&gt;Use timestamps from a consistent monotonic time basis. &lt;code&gt;performance.now()&lt;/code&gt; is appropriate for elapsed durations in a page; &lt;code&gt;Date.now()&lt;/code&gt; is useful for a human-readable record date. A more precise timestamp does not reveal the physical moment a pixel appeared on a display, nor remove input-device and operating-system latency.&lt;/p&gt;

&lt;h2&gt;
  
  
  A successful collision is not always a completed target
&lt;/h2&gt;

&lt;p&gt;Consider a headshot task. A shot that hits the torso is a valid shot and a collision, but it should not complete the target.&lt;/p&gt;

&lt;p&gt;Separate those facts before designing the result screen:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;newStats&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;shots&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;head&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;air&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;completed&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;recordShot&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;part&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;mode&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;shots&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;part&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;head&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;head&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;part&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;air&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;completes&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;mode&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;head&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;
    &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;part&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;head&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;
    &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Boolean&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;part&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;completes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;completed&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;completes&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;newStats&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;recordShot&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;body&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;head&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;recordShot&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;head&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;head&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;recordShot&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;head&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;shots&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;head&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;air&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;completed&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Geometry supplies &lt;code&gt;part&lt;/code&gt;; it does not decide whether the round was running or whether the input was accepted. The event layer checks those conditions first. Otherwise a click on the start overlay, a repeated key event, or a shot received after completion may mutate the score.&lt;/p&gt;

&lt;p&gt;For a 3D scene, classify the nearest relevant intersection before applying scoring rules. Do not award a headshot because the ray eventually intersects a head behind an occluding surface.&lt;/p&gt;

&lt;h2&gt;
  
  
  Name the denominator on the screen
&lt;/h2&gt;

&lt;p&gt;Suppose a constructed round contains ten shots: two head hits, six other hits, and two misses.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Metric&lt;/th&gt;
&lt;th&gt;Formula&lt;/th&gt;
&lt;th&gt;Result&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Hit accuracy&lt;/td&gt;
&lt;td&gt;All mannequin hits / accepted shots&lt;/td&gt;
&lt;td&gt;80%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Head-hit rate&lt;/td&gt;
&lt;td&gt;Head hits / accepted shots&lt;/td&gt;
&lt;td&gt;20%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Head share of hits&lt;/td&gt;
&lt;td&gt;Head hits / all mannequin hits&lt;/td&gt;
&lt;td&gt;25%&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Those percentages describe the same inputs. None is interchangeable with the others. A label such as “headshot rate” without a definition hides an important product decision.&lt;/p&gt;

&lt;p&gt;Keep missing observations distinct from zero:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ratio&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;numerator&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;denominator&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
  &lt;span class="nx"&gt;denominator&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;numerator&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;denominator&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;ratio&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;ratio&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Render the first case as “—” or “No shots,” not as an apparently measured 0%. Preserve the raw counts so the user can interpret a percentage from a small sample.&lt;/p&gt;

&lt;p&gt;Also avoid calling target acquisition “pure reaction time.” Finding a target, moving a pointer or camera, and clicking are part of that interval. Different target sizes and distances affect it. It is a task duration, not a clinical measurement of a person.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tracking needs time weighting and an uncertainty policy
&lt;/h2&gt;

&lt;p&gt;Counting on-target frames rewards a different unit on a 60 Hz display than on a 144 Hz display. Instead, accumulate observed time and divide by active time.&lt;/p&gt;

&lt;p&gt;One conservative sampling rule is to credit an interval only when both endpoints were on target:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;newTracking&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;previousOn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;credited&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;streak&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;longest&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;observe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;onTarget&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;dt&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;onTarget&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;previousOn&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;credited&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;dt&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;streak&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;dt&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;longest&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;longest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;streak&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;streak&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;previousOn&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;onTarget&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;tracking&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;newTracking&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="nf"&gt;observe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tracking&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;  &lt;span class="c1"&gt;// establish the first observation&lt;/span&gt;
&lt;span class="nf"&gt;observe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tracking&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;  &lt;span class="c1"&gt;// credit one supported interval&lt;/span&gt;
&lt;span class="nf"&gt;observe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tracking&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tracking&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;credited&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tracking&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;longest&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is still an approximation. Two on-target endpoints do not prove continuous on-target movement between them. The policy avoids assigning a whole unknown gap to a favorable final observation; it does not reconstruct a missing trajectory.&lt;/p&gt;

&lt;p&gt;When the active clock rejects a gap, do not call &lt;code&gt;observe()&lt;/code&gt; for that interval. On pause, clear the previous observation and current streak. Keep accumulated historical credit, but do not join the two sides of a pause into one continuous streak.&lt;/p&gt;

&lt;h2&gt;
  
  
  Treat interruptions as data, not embarrassment
&lt;/h2&gt;

&lt;p&gt;A compact lifecycle can look like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;idle -&amp;gt; loading -&amp;gt; ready -&amp;gt; countdown -&amp;gt; running -&amp;gt; completed
                                running -&amp;gt; paused -&amp;gt; countdown
                                paused  -&amp;gt; completed (aborted)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each transition owns cleanup. Leaving &lt;code&gt;running&lt;/code&gt; stops scheduled work and freezes the task clock. Completion freezes the result before any result animation. A visibility change, window blur, viewport change, pointer-lock loss, or rejected timing gap routes through the same pause operation.&lt;/p&gt;

&lt;p&gt;An interrupted round can remain useful history. It simply should not replace an uninterrupted personal best. “Save the record” and “eligible for best” are separate decisions:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;eligibleForBest&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
  &lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;completed&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
  &lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;interrupted&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
  &lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;elapsed&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Pointer Lock adds an asynchronous boundary. Requesting it does not mean it succeeded. Handle success, rejection, and a request that never reaches the expected locked state. A stale loading or lock result must not revive a scene the user has already left.&lt;/p&gt;

&lt;p&gt;Full-screen and raw mouse input are separate capabilities. A fallback can keep a task usable, but record the actual input path rather than pretending mouse, raw mouse, touch, and drag fallback are identical.&lt;/p&gt;

&lt;h2&gt;
  
  
  A personal best belongs to an experiment configuration
&lt;/h2&gt;

&lt;p&gt;Sorting every round by duration produces a misleading leaderboard. Ten large static targets are not fifty small moving targets.&lt;/p&gt;

&lt;p&gt;A comparison key should encode the task version, relevant settings, input category, and training-area dimensions. Decide explicitly whether cosmetic settings are relevant. Store an immutable round configuration rather than a reference to controls that can change later.&lt;/p&gt;

&lt;p&gt;This only controls variables the application knows. It cannot automatically identify physical mouse DPI, display latency, posture, or every browser setting. Random target layouts add variation even within a matching configuration. Matching profiles make comparisons more meaningful; they do not turn a browser game into a controlled laboratory experiment.&lt;/p&gt;

&lt;p&gt;Local history also needs ordinary defensive engineering: versioned records, bounded retention, finite numeric fields, count invariants, and visible storage-failure feedback. Do not let a malformed local record break the entire UI. Do not call browser-local persistence a backup or anti-cheat system.&lt;/p&gt;

&lt;h2&gt;
  
  
  Test the contract before polishing the score animation
&lt;/h2&gt;

&lt;p&gt;The examples above run with plain JavaScript. A useful test matrix adds these integration cases:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A torso hit in headshot mode increments the shot count without replacing the target.&lt;/li&gt;
&lt;li&gt;A hidden tab resumes as interrupted, without receiving unknown tracking credit.&lt;/li&gt;
&lt;li&gt;The final accepted hit freezes timing immediately.&lt;/li&gt;
&lt;li&gt;A failed lock request leaves the timer stopped.&lt;/li&gt;
&lt;li&gt;Leaving during asynchronous renderer loading prevents a late scene from mounting.&lt;/li&gt;
&lt;li&gt;Storage failure does not prevent practice, but the UI stops promising durable history.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Synthetic clicks validate the application contract; their completion times are not human performance results. A unit test verifies arithmetic, not monitor latency or successful transfer to a specific FPS game.&lt;/p&gt;

&lt;p&gt;The reusable lesson is simple: a convincing number needs a definition, an observation boundary, and a comparison rule. That applies to focus timers, typing tests, interaction benchmarks, and training tools just as much as it applies to aim practice.&lt;/p&gt;

&lt;h3&gt;
  
  
  References
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame" rel="noopener noreferrer"&gt;MDN: requestAnimationFrame&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API" rel="noopener noreferrer"&gt;MDN: Pointer Lock API&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Performance/now" rel="noopener noreferrer"&gt;MDN: performance.now&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;No game-performance, medical, or general-attention improvement is established by the examples in this article.&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>webdev</category>
    </item>
    <item>
      <title>The 200 KB Trap in Browser Image Compression</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Fri, 30 Oct 2026 05:03:31 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/the-200-kb-trap-in-browser-image-compression-411m</link>
      <guid>https://dev.to/dngzihng114379/the-200-kb-trap-in-browser-image-compression-411m</guid>
      <description>&lt;p&gt;Three images. Three green “within limit” results. Zero files that met the upload rules I had written down.&lt;/p&gt;

&lt;p&gt;The compressor was doing what it promised. My acceptance check was asking a different question.&lt;/p&gt;

&lt;p&gt;For this experiment, I defined a hypothetical destination that accepts &lt;strong&gt;JPEG, exactly 600 × 800 pixels, at most 200,000 bytes&lt;/strong&gt;. Then I ran three synthetic inputs through a browser compressor's “200 KB” preset and inspected the downloaded files with a separate image decoder.&lt;/p&gt;

&lt;p&gt;Here is the result before we get to any code:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Downloaded result&lt;/th&gt;
&lt;th&gt;Encoded bytes&lt;/th&gt;
&lt;th&gt;Actual format&lt;/th&gt;
&lt;th&gt;Actual dimensions&lt;/th&gt;
&lt;th&gt;Meets that destination's rules?&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Noisy PNG, compressed&lt;/td&gt;
&lt;td&gt;179,501&lt;/td&gt;
&lt;td&gt;PNG&lt;/td&gt;
&lt;td&gt;199 × 265&lt;/td&gt;
&lt;td&gt;No: wrong format and dimensions&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Noisy JPEG, compressed&lt;/td&gt;
&lt;td&gt;204,128&lt;/td&gt;
&lt;td&gt;JPEG&lt;/td&gt;
&lt;td&gt;600 × 800&lt;/td&gt;
&lt;td&gt;No: 4,128 bytes too large&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Small transparent PNG, unchanged&lt;/td&gt;
&lt;td&gt;12,736&lt;/td&gt;
&lt;td&gt;PNG&lt;/td&gt;
&lt;td&gt;600 × 800&lt;/td&gt;
&lt;td&gt;No: wrong format&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;This was a controlled acceptance test, not a story about a real application form rejecting a customer. The “200 KB” preset explicitly meant &lt;strong&gt;200 × 1,024 = 204,800 bytes&lt;/strong&gt;. It allowed proportional resizing, preserved PNG by default, and left an already-small input untouched. All three files satisfied that policy.&lt;/p&gt;

&lt;p&gt;I maintain &lt;a href="https://toolknit.com/tools/compress-image.html" rel="noopener noreferrer"&gt;ToolKnit's browser image compressor&lt;/a&gt;, which is the tool used for this case study. That affiliation matters: this is an engineering explanation of its limits, not an independent product review. The small implementation below is a separate teaching example, not a copy of the production algorithm.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ft1hskx5jd55sinbqwt7b.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ft1hskx5jd55sinbqwt7b.png" alt="Three actual compressor results: a resized PNG, a 600×800 JPEG, and an unchanged transparent PNG." width="750" height="510"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Actual tool output from synthetic fixtures. The table above uses independently parsed downloads rather than rounded UI values.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The useful lesson is that &lt;strong&gt;“make it smaller” and “make it acceptable” are different specifications&lt;/strong&gt;. A quality slider cannot decide the second one for you.&lt;/p&gt;

&lt;h2&gt;
  
  
  Write the destination's rules before choosing an encoder
&lt;/h2&gt;

&lt;p&gt;A file-size ceiling is one field in a larger contract:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;destination&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;maxBytes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="nx"&gt;_000&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;mime&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;image/jpeg&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;width&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;600&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;height&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;800&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;animation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;reject&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;transparency&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;flatten-on-white-with-consent&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Some fields are machine-checkable. Others are product decisions. Flattening a transparent asset onto white changes its appearance; it is not a harmless technical default. A portrait that must remain 600 × 800 cannot quietly become 199 × 265 just because a smaller canvas produces fewer bytes.&lt;/p&gt;

&lt;p&gt;Ask these questions before processing:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Does the receiver require an exact format or merely an allowed set?&lt;/li&gt;
&lt;li&gt;Are width and height exact, maximums, or unconstrained?&lt;/li&gt;
&lt;li&gt;Is the limit per file, per archive, or for the whole request?&lt;/li&gt;
&lt;li&gt;Must transparency, animation, metadata or a particular color profile survive?&lt;/li&gt;
&lt;li&gt;What is allowed to change when those requirements conflict?&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If the receiver says only “200 KB,” check its documentation or actual byte limit. &lt;strong&gt;200,000 bytes and 204,800 bytes differ by 4,800 bytes.&lt;/strong&gt; The second row in the table fits one and fails the other. Formatting a number as “199.3 KB” does not resolve that ambiguity.&lt;/p&gt;

&lt;p&gt;Use the encoded &lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob/size" rel="noopener noreferrer"&gt;&lt;code&gt;Blob.size&lt;/code&gt;&lt;/a&gt;, which is measured in bytes. Do not compare the length of a base64 data URL, a rounded display string, or the original file's size.&lt;/p&gt;

&lt;h2&gt;
  
  
  Quality is an encoder input, not a byte budget
&lt;/h2&gt;

&lt;p&gt;This looks plausible:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBlob&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;onResult&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;image/jpeg&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;0.85&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;But &lt;code&gt;0.85&lt;/code&gt; means neither “keep 85% of the original bytes” nor “produce an image of a predictable size.” It is also not a portable perceptual-quality score across codecs and browsers.&lt;/p&gt;

&lt;p&gt;I generated two 600 × 800 canvases: one with four flat rectangles, another with deterministic RGB noise. In the same browser, using the same JPEG quality parameter:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Synthetic input&lt;/th&gt;
&lt;th&gt;Dimensions&lt;/th&gt;
&lt;th&gt;JPEG quality argument&lt;/th&gt;
&lt;th&gt;Encoded bytes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Flat rectangles&lt;/td&gt;
&lt;td&gt;600 × 800&lt;/td&gt;
&lt;td&gt;0.85&lt;/td&gt;
&lt;td&gt;7,221&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RGB noise&lt;/td&gt;
&lt;td&gt;600 × 800&lt;/td&gt;
&lt;td&gt;0.85&lt;/td&gt;
&lt;td&gt;344,122&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The noise is deliberately difficult input, not a representative photo collection. This is evidence that the parameter does not enforce a budget; it is not a comparison of photo quality or a ranking of compressors.&lt;/p&gt;

&lt;p&gt;There are two more API details worth making explicit:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob" rel="noopener noreferrer"&gt;&lt;code&gt;toBlob()&lt;/code&gt;&lt;/a&gt; can return &lt;code&gt;null&lt;/code&gt; through its callback. A completed callback is not necessarily a usable image.&lt;/li&gt;
&lt;li&gt;An unsupported requested output format falls back to PNG. Naming the download &lt;code&gt;result.jpg&lt;/code&gt; does not make those bytes JPEG.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;My unsupported-type probe requested &lt;code&gt;image/x-budget-lab-test&lt;/code&gt;; the returned blob was &lt;code&gt;image/png&lt;/code&gt;. An encoder wrapper should reject that mismatch when the output type is a requirement.&lt;/p&gt;

&lt;p&gt;PNG has another trap: the canvas quality argument is intended for formats with lossy compression. In this run, encoding the transparent PNG fixture at &lt;code&gt;0.1&lt;/code&gt; and &lt;code&gt;0.9&lt;/code&gt; produced &lt;strong&gt;12,736 bytes each, with identical SHA-256 hashes&lt;/strong&gt;. Moving that slider did nothing to this PNG. That exact hash equality is an observation from this browser, not a promise about every implementation.&lt;/p&gt;

&lt;h2&gt;
  
  
  A small bounded encoder that is allowed to say no
&lt;/h2&gt;

&lt;p&gt;For a fixed-dimension JPEG destination, I prefer a small, explicit policy over silently shrinking the image until some file emerges.&lt;/p&gt;

&lt;p&gt;The following function:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;accepts an &lt;strong&gt;already-decoded canvas&lt;/strong&gt;;&lt;/li&gt;
&lt;li&gt;explicitly composites it onto white;&lt;/li&gt;
&lt;li&gt;preserves the canvas dimensions;&lt;/li&gt;
&lt;li&gt;tries six decreasing JPEG quality settings;&lt;/li&gt;
&lt;li&gt;returns a success only after checking the actual encoded bytes;&lt;/li&gt;
&lt;li&gt;returns a refusal when none of those candidates fits.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The white background must be an accepted product choice. This function is not appropriate when alpha or animation must be preserved. Its pixel ceiling is a scope limit for the example, not a guarantee that every device can safely process that input.&lt;/p&gt;

&lt;p&gt;It preserves the dimensions you give it; it does not crop an arbitrary source into a 600 × 800 portrait. Prepare the required canvas dimensions first, using a crop or padding policy the destination permits.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Teaching example: a fixed-dimension, explicitly white-matted JPEG policy.&lt;/span&gt;
&lt;span class="c1"&gt;// It is NOT ToolKnit's production implementation or an optimal codec search.&lt;/span&gt;
&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;quality&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;reject&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBlob&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;reject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Encoder returned no bytes&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="nx"&gt;type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;reject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`Requested &lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;type&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;; received &lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;type&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="nx"&gt;type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;quality&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;fitJpeg&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;maxBytes&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;qualities&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mf"&gt;0.92&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;0.82&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;0.72&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;0.62&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;0.52&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;0.42&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="nx"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{})&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nb"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isSafeInteger&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;maxBytes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;maxBytes&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;RangeError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;maxBytes must be a positive safe integer&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="c1"&gt;// Copy before awaiting: caller mutation must not change this run's policy.&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;candidates&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isArray&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;qualities&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="p"&gt;[...&lt;/span&gt;&lt;span class="nx"&gt;qualities&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;candidates&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;candidates&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;12&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
      &lt;span class="nx"&gt;candidates&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;some&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;q&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nb"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isFinite&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;q&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;q&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;q&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
      &lt;span class="nx"&gt;candidates&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;some&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;q&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;q&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="nx"&gt;candidates&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]))&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;RangeError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Use 1–12 strictly decreasing quality values in [0,1]&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="nx"&gt;_000_000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;RangeError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;This example permits 1–4,000,000 pixels&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="nx"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;throwIfAborted&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;opaque&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createElement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;canvas&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;opaque&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;width&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;opaque&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;attempts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;opaque&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getContext&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;2d&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Canvas 2D unavailable&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;fillStyle&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;#fff&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fillRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;width&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;drawImage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;quality&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nx"&gt;candidates&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;throwIfAborted&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;opaque&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;image/jpeg&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;quality&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
      &lt;span class="c1"&gt;// toBlob itself is not abortable; do not publish a stale result.&lt;/span&gt;
      &lt;span class="nx"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;throwIfAborted&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
      &lt;span class="nx"&gt;attempts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;&lt;span class="nx"&gt;quality&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;bytes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt;&lt;span class="p"&gt;});&lt;/span&gt;
      &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="nx"&gt;maxBytes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;width&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;quality&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;attempts&lt;/span&gt;&lt;span class="p"&gt;};&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;reason&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;No candidate in this policy fits&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;attempts&lt;/span&gt;&lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;finally&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;opaque&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;opaque&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For the hypothetical destination at the start, pass &lt;code&gt;destination.maxBytes&lt;/code&gt;, which is &lt;code&gt;200_000&lt;/code&gt;. Changing the displayed unit should never silently change that integer.&lt;/p&gt;

&lt;p&gt;The distinction in the failure message is intentional: &lt;strong&gt;“No candidate in this policy fits”&lt;/strong&gt;, not “This image cannot be compressed any further.” A lower quality value, different codec, different dimensions or different encoder might fit. Those are changes to the policy, and some may violate the destination's requirements.&lt;/p&gt;

&lt;p&gt;The function returns the first fitting value in the ordered ladder. It does not claim to find an optimal quality setting. Binary search can reduce the number of probes under suitable assumptions, but the canvas API does not define a portable byte-size function that guarantees your preferred search strategy finds the global best candidate. Whatever search you use, verify the blob you actually return.&lt;/p&gt;

&lt;h3&gt;
  
  
  What happened when I ran it
&lt;/h3&gt;

&lt;p&gt;Using the explicit budget &lt;code&gt;204_800&lt;/code&gt; and the six settings shown above:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Fixture&lt;/th&gt;
&lt;th&gt;Preserved dimensions&lt;/th&gt;
&lt;th&gt;Outcome&lt;/th&gt;
&lt;th&gt;Bytes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Flat rectangles&lt;/td&gt;
&lt;td&gt;600 × 800&lt;/td&gt;
&lt;td&gt;Fits at 0.92&lt;/td&gt;
&lt;td&gt;7,778&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Transparent rectangles, white matte&lt;/td&gt;
&lt;td&gt;600 × 800&lt;/td&gt;
&lt;td&gt;Fits at 0.92&lt;/td&gt;
&lt;td&gt;7,857&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RGB noise&lt;/td&gt;
&lt;td&gt;600 × 800&lt;/td&gt;
&lt;td&gt;Fits at 0.52&lt;/td&gt;
&lt;td&gt;190,797&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Larger RGB noise&lt;/td&gt;
&lt;td&gt;1200 × 1600&lt;/td&gt;
&lt;td&gt;Refused after all six candidates&lt;/td&gt;
&lt;td&gt;Smallest attempted: 648,881&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The large-noise refusal is a valid result. Returning a smaller canvas would produce a different kind of success, one the caller has not authorized here.&lt;/p&gt;

&lt;p&gt;These tables use different source representations and search policies: the production JPEG path started with an already-encoded JPEG, while the teaching function started with a canvas. Their byte counts do not establish which compressor is better.&lt;/p&gt;

&lt;p&gt;Likewise, &lt;code&gt;0.52&lt;/code&gt; passing a byte check does not prove the result is visually acceptable. Fine text, facial detail and gradients still need review in the actual destination. Keep the source so that a rejected result can be regenerated from the original rather than recompressed repeatedly.&lt;/p&gt;

&lt;h2&gt;
  
  
  Check the exported artifact, not just the function's return value
&lt;/h2&gt;

&lt;p&gt;For blobs produced by your own encoder, a useful second check is to decode the &lt;strong&gt;output&lt;/strong&gt; and inspect what it actually contains:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;checkGeneratedImage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;rule&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;problems&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="nx"&gt;rule&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;mime&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;problems&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;output MIME differs&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;rule&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;maxBytes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;problems&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;byte limit exceeded&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;bitmap&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;createImageBitmap&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;bitmap&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="nx"&gt;rule&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;bitmap&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="nx"&gt;rule&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;problems&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;pixel dimensions differ&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;finally&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;bitmap&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;close&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;problems&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is a convenience check for an application's generated output, &lt;strong&gt;not a security validator for arbitrary user uploads&lt;/strong&gt;. A client-supplied MIME label or extension is untrusted. A server must independently enforce its byte limits, recognize and safely decode allowed formats, validate dimensions and apply its own resource limits. Client-side checks improve the experience; they do not replace that boundary.&lt;/p&gt;

&lt;p&gt;For this article, I downloaded the generated files and opened them with Pillow, separately from the browser. The verification compared format, dimensions, byte count and SHA-256, then checked alpha and selected pixels. It caught a useful visual distinction: direct JPEG encoding of the transparent canvas produced a black corner in this browser, while the explicit white-matte path produced &lt;code&gt;(255, 255, 255)&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;I also downloaded the compressor's ZIP. Its three members were byte-identical to the individual downloads, but the archive was &lt;strong&gt;396,759 bytes&lt;/strong&gt;. Every member being below 204,800 bytes does not make the archive below 204,800 bytes. A per-file budget and an attachment budget need separate checks.&lt;/p&gt;

&lt;h2&gt;
  
  
  Four boundaries that deserve their own decisions
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Animation.&lt;/strong&gt; Drawing a decoded image onto one canvas gives you a bitmap, not a frame-preserving animation pipeline. Decide whether to reject animation, retain the original or use a suitable animated codec pipeline. Do not silently discard the other frames and call that a successful compression.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Orientation and metadata.&lt;/strong&gt; Define dimensions in the orientation the receiver uses. &lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/createImageBitmap" rel="noopener noreferrer"&gt;&lt;code&gt;createImageBitmap()&lt;/code&gt;&lt;/a&gt; defaults to using image orientation metadata when present. Re-encoding also should not be treated as a general guarantee that all metadata or color information was preserved—or removed. Test the fields your workflow actually depends on.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Memory.&lt;/strong&gt; A 6000 × 4000 RGBA bitmap contains 96,000,000 bytes of pixel data before additional buffers. Compressed file size is a poor proxy for that cost. Put limits on input bytes, dimensions, decoded work and retained outputs; process batches with bounded concurrency. This example starts after decoding, so it does not solve admission control for a malicious or enormous source file.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Stale work.&lt;/strong&gt; Someone can choose a new file while the previous encode is still running. The abort checks above prevent an aborted result from being returned, but do not cancel an in-progress &lt;code&gt;toBlob()&lt;/code&gt; operation. The caller must abort the old run and ensure only the current run can update the UI. “I clicked Cancel” and “the encoder stopped consuming resources immediately” are different claims.&lt;/p&gt;

&lt;p&gt;If the page processes files locally, describe that claim narrowly. Local file processing does not imply that the website makes no network requests; loading assets and ordinary analytics are separate concerns. It also does not make a page appropriate for every confidential workflow.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reproduce the interesting part
&lt;/h2&gt;

&lt;p&gt;These are synthetic fixtures, so the central experiment does not require anyone's private photos. Run the &lt;code&gt;encode&lt;/code&gt; and &lt;code&gt;fitJpeg&lt;/code&gt; definitions above in a browser module, then add this fixture generator and probe:&lt;/p&gt;

&lt;p&gt;&lt;/p&gt;
  Deterministic fixtures and reproduction code
  &lt;br&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Deterministic fixtures: deliberate test inputs, not customer photos.&lt;/span&gt;
&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;fixture&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createElement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;canvas&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;large-noise&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="mi"&gt;1200&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;600&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;large-noise&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="mi"&gt;1600&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;800&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getContext&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;2d&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Canvas 2D unavailable&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;noise&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;large-noise&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;pixels&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createImageData&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;seed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mh"&gt;0x12345678&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;pixels&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;c&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;c&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;c&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nx"&gt;seed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;imul&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;seed&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1664525&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1013904223&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="nx"&gt;pixels&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;c&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;seed&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="nx"&gt;pixels&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;255&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;putImageData&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;pixels&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;alpha&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;fillStyle&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rgba(22,120,200,0.5)&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fillRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;600&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;clearRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;flat&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;fillStyle&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;#fff&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fillRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;600&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;800&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;#182434&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;#4276ad&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;#d58456&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;#94b5a2&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nf"&gt;forEach&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;color&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;fillStyle&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;color&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fillRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;40&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;40&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;180&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;520&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;120&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Unknown fixture&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;measurements&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;
&lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;flat&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;alpha&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;noise&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;large-noise&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;fixture&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;baseline&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;image/jpeg&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;0.85&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;fitted&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fitJpeg&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;204&lt;/span&gt;&lt;span class="nx"&gt;_800&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;measurements&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;fixture&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;width&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;height&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;baselineBytes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;baseline&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;fits&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;fitted&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;quality&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;fitted&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;ok&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;fitted&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;quality&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;resultBytes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;fitted&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;ok&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;fitted&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;fitted&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;attempts&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;table&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;measurements&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;




&lt;p&gt;&lt;/p&gt;

&lt;p&gt;The measurements here were collected on &lt;strong&gt;October 30, 2026, in a Windows Chromium-based browser reporting Chrome 156&lt;/strong&gt;. Another browser or encoder version can produce different bytes. Reproduce the invariants—dimensions retained, returned type checked, successful blobs within the byte cap, explicit failure—not a claim that everyone should get the same JPEG hash.&lt;/p&gt;

&lt;p&gt;The local harness also exercised invalid budgets, invalid quality ladders, a pre-aborted run, a one-byte refusal and unsupported-format fallback. Those checks supplement the downloaded-file verification; a green test count by itself would not establish visual quality, cross-browser compatibility or safe handling of arbitrary inputs.&lt;/p&gt;

&lt;h2&gt;
  
  
  The UI should report what it actually proved
&lt;/h2&gt;

&lt;p&gt;Instead of showing one ambiguous “Success” badge, report the constraints independently:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Bytes:       179,501 / 200,000       PASS
Format:      PNG / JPEG required    FAIL
Dimensions:  199×265 / 600×800       FAIL
Decision:    Do not submit this file
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then offer choices that match the failed rule: select a permitted format, obtain a suitable original, accept a resize only if allowed, or explain that the current policy has no fitting candidate. Do not keep lowering quality when the failing field is the format.&lt;/p&gt;

&lt;p&gt;The most useful compression result is not always the smallest file. It is a file whose properties match the destination—and a clear refusal when they do not.&lt;/p&gt;

&lt;p&gt;Which constraint has caused the most surprises in your upload flow: bytes, dimensions, alpha, or the receiver's definition of “KB”?&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Disclosure: I maintain ToolKnit. AI tools produced the draft, example code and cover illustration. The numerical results came from actual browser runs and separately parsed downloads; the cover is not experimental evidence.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>webdev</category>
      <category>tutorial</category>
      <category>testing</category>
    </item>
    <item>
      <title>Abort Is Not Enough: Lifecycles and Output Contracts in a Tauri Toolbox</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Tue, 27 Oct 2026 02:53:44 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/abort-is-not-enough-lifecycles-and-output-contracts-in-a-tauri-toolbox-17mf</link>
      <guid>https://dev.to/dngzihng114379/abort-is-not-enough-lifecycles-and-output-contracts-in-a-tauri-toolbox-17mf</guid>
      <description>&lt;p&gt;A user starts a conversion, switches tools, and starts another operation. The first promise resolves last. Which screen is allowed to display its result?&lt;/p&gt;

&lt;p&gt;That question looks like a small UI bug. In a desktop toolbox, it connects several architectural decisions: who owns asynchronous work, whether an imported module is still wanted, and when a file operation is actually complete.&lt;/p&gt;

&lt;p&gt;This is a source-based walkthrough of those boundaries in ToolKnit Desktop, a project I maintain. The examples below are simplified teaching examples, not copied production implementations. The references point to one fixed revision so the discussion remains reproducible as the code changes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Scope and disclosure:&lt;/strong&gt; AI generated this draft from a review of the linked source and documentation. This is not a benchmark or an independent security audit. The repository is source-available: its current licensing includes PolyForm Noncommercial and a separate restriction for the PDF-to-Word engine. Public source access should not be confused with unrestricted open-source licensing.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Three different lifetimes hide behind one tool button
&lt;/h2&gt;

&lt;p&gt;A toolbox can have at least three useful lifetimes:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Lifetime&lt;/th&gt;
&lt;th&gt;What belongs to it&lt;/th&gt;
&lt;th&gt;When it ends&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Application&lt;/td&gt;
&lt;td&gt;Navigation, global keyboard handling, registry&lt;/td&gt;
&lt;td&gt;App or registry disposal&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Tool instance&lt;/td&gt;
&lt;td&gt;Imported module and reusable tool state&lt;/td&gt;
&lt;td&gt;Instance disposal&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Active operation or session&lt;/td&gt;
&lt;td&gt;Fetch, progress updates, preview URLs, temporary listeners&lt;/td&gt;
&lt;td&gt;Cancellation, replacement, or session cleanup&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;These lifetimes do not necessarily end together. Hiding a tool does not unload an ES module. A registry can cache an initialized tool for reuse while the tool cancels its current operation.&lt;/p&gt;

&lt;p&gt;This distinction matters because two opposite mistakes are easy to make:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Keep every resource alive because the tool instance is cached.&lt;/li&gt;
&lt;li&gt;Destroy all reusable state whenever a tool becomes invisible.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The useful question for each resource is: &lt;strong&gt;which lifetime owns it?&lt;/strong&gt; A global Escape listener and a conversion-specific progress callback should not have identical ownership.&lt;/p&gt;

&lt;p&gt;The project's &lt;a href="https://github.com/ZihangDong/toolknit-desktop/blob/0f088b0ee25ac3a1d362c740fed7267ab4b36b36/toolknit-desktop/src/app/tool-lifecycle.js" rel="noopener noreferrer"&gt;lifecycle utilities&lt;/a&gt; group cleanup callbacks into a scope. The scope provides event and timer helpers, an abort controller, revision tokens, and idempotent disposal. Disposal invalidates outstanding tokens and runs cleanup callbacks in reverse registration order. One cleanup error does not prevent the other cleanups from running.&lt;/p&gt;

&lt;p&gt;That is a mechanism for managing resources, not proof that every feature uses it correctly. Feature implementations still have to register what they allocate.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Cancellation and permission to update the UI are different things
&lt;/h2&gt;

&lt;p&gt;An &lt;code&gt;AbortController&lt;/code&gt; asks cooperative work to stop. It does not automatically make every result from that work irrelevant.&lt;/p&gt;

&lt;p&gt;Consider this sequence:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;1. Operation A starts.
2. The user starts operation B.
3. A is asked to abort.
4. A's already-completed result reaches a continuation.
5. A overwrites B's progress or result.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Not every dependency accepts an abort signal. Even when it does, a completion may already be queued. A result needs an identity check as well as a cancellation mechanism.&lt;/p&gt;

&lt;p&gt;Here is an intentionally small, original example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;generation&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;activeController&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;closed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;run&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;closed&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;mine&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="nx"&gt;generation&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;activeController&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;abort&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;controller&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;AbortController&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="nx"&gt;activeController&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;controller&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;isCurrent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;closed&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;mine&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="nx"&gt;generation&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="nf"&gt;setBusy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;convert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;controller&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nf"&gt;isCurrent&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nf"&gt;render&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;result&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;isCurrent&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;AbortError&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;showError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;finally&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;isCurrent&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt; &lt;span class="nf"&gt;setBusy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;dispose&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;closed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;generation&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;activeController&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;abort&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notice the guard in &lt;code&gt;finally&lt;/code&gt;. Guarding only &lt;code&gt;render()&lt;/code&gt; still lets an older request clear the busy indicator for a newer one. Error notifications need the same treatment.&lt;/p&gt;

&lt;p&gt;The example also has a limit: if &lt;code&gt;convert()&lt;/code&gt; allocates a resource and returns it after becoming stale, returning early is not sufficient cleanup. A real implementation must release that result, or give the operation scope ownership of it. Ignoring a stale object URL does not revoke it.&lt;/p&gt;

&lt;p&gt;In the actual lifecycle utility, &lt;code&gt;invalidate()&lt;/code&gt;, &lt;code&gt;token()&lt;/code&gt;, and &lt;code&gt;isCurrent()&lt;/code&gt; provide the revision mechanism, while disposal makes all earlier tokens invalid. Cancellation manages work; a revision check manages authority to affect the current interface.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Lazy loading introduces a second race
&lt;/h2&gt;

&lt;p&gt;Lazy loading is often presented as a bundle-size technique. It also changes navigation semantics.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;User requests tool A → A's module starts loading
User requests tool B → B's module starts loading
B finishes → display B
A finishes → should A replace B?
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The answer should normally follow the latest user request, not the slowest import.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/ZihangDong/toolknit-desktop/blob/0f088b0ee25ac3a1d362c740fed7267ab4b36b36/toolknit-desktop/src/app/lazy-tool-registry.js" rel="noopener noreferrer"&gt;lazy registry&lt;/a&gt; handles two separate concerns:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;It caches pending loads by instance key, so concurrent requests for one tool share initialization work.&lt;/li&gt;
&lt;li&gt;It maintains a request revision and checks it across asynchronous navigation steps, so an older request cannot simply reclaim the active view after loading.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;De-duplicating a promise does not solve stale navigation. Conversely, preventing stale activation does not prevent duplicate initialization. Both are needed.&lt;/p&gt;

&lt;p&gt;There is another nuance: the currently active tool can reject a close by returning &lt;code&gt;false&lt;/code&gt;. A navigation system must respect that decision rather than treating a successful import as permission to discard the current workflow.&lt;/p&gt;

&lt;p&gt;A cached module may remain available after its original navigation request becomes stale. The important distinction is between &lt;strong&gt;having loaded a tool&lt;/strong&gt; and &lt;strong&gt;being authorized to activate it now&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Platform boundaries should be explicit, not magically universal
&lt;/h2&gt;

&lt;p&gt;The frontend uses vanilla JavaScript modules with Vite, while Tauri supplies the desktop boundary. The &lt;a href="https://github.com/ZihangDong/toolknit-desktop/blob/0f088b0ee25ac3a1d362c740fed7267ab4b36b36/toolknit-desktop/src/platform/tauri-runtime.js" rel="noopener noreferrer"&gt;platform adapter&lt;/a&gt; centralizes core Tauri imports and exposes dynamic imports for selected APIs, including dialogs and webviews.&lt;/p&gt;

&lt;p&gt;That is a specific boundary, not a claim that every native API is loaded lazily or that desktop code can be dropped unchanged into a browser.&lt;/p&gt;

&lt;p&gt;For a reusable feature, the design question is which capability it needs: file selection, native processing, opening a window, or a browser API. Making those dependencies visible is more useful than giving every feature unrestricted access to every environment.&lt;/p&gt;

&lt;p&gt;This also helps explain why a graphical app and a command-line interface should not be coupled through simulated clicks. A CLI should invoke a processing contract, not depend on which overlay happens to be open.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. A successful command does not necessarily mean a new file exists
&lt;/h2&gt;

&lt;p&gt;The project's &lt;a href="https://github.com/ZihangDong/toolknit-desktop/blob/0f088b0ee25ac3a1d362c740fed7267ab4b36b36/toolknit-desktop/docs/cli-agent.md" rel="noopener noreferrer"&gt;CLI documentation&lt;/a&gt; describes direct file operations rather than GUI automation. Its documented output rules include explicit destinations, rejecting symbolic links, refusing to overwrite inputs, and requiring an explicit overwrite option for existing outputs. Writing operations stage temporary output in the destination directory before publishing it on success.&lt;/p&gt;

&lt;p&gt;These rules give callers something more useful than a button label: a file-system contract.&lt;/p&gt;

&lt;p&gt;They do not eliminate every operational failure. Disk exhaustion, process interruption, unsupported formats, and missing engines still need handling. Staging an output also should not be described as a universal power-loss durability guarantee.&lt;/p&gt;

&lt;p&gt;Compression provides an especially useful lesson. A request can be handled without publishing a new output: the input might already satisfy the target, the requested target might not be reached, or the operation might achieve no reduction. The documented statuses distinguish these cases from a newly published compressed file.&lt;/p&gt;

&lt;p&gt;An automation client that only checks “exit code equals zero” can therefore make the wrong next move. It should inspect the operation's structured status and documented output fields before trying to attach or upload a result.&lt;/p&gt;

&lt;p&gt;This is a general API design principle: &lt;strong&gt;report what happened to the artifact, not just what happened to the process.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  6. MCP needs the same contracts, plus protocol discipline
&lt;/h2&gt;

&lt;p&gt;Exposing tools to an agent does not make their file operations less consequential. It makes explicit inputs, outputs, and cancellation more important.&lt;/p&gt;

&lt;p&gt;The documented MCP interface uses newline-delimited JSON-RPC over standard input and output. Standard output must remain protocol-only: a friendly startup banner in that stream can break a client. Human-readable diagnostics need a separate channel.&lt;/p&gt;

&lt;p&gt;The documentation also specifies bounded input and concurrency rather than unlimited parallel execution. Those are useful resource controls, but they should not be mistaken for a sandbox or authorization policy.&lt;/p&gt;

&lt;p&gt;An agent caller still needs to inspect a tool's schema, identify the intended input files, choose a destination, and interpret the returned status. Permission to inspect one document is not automatically permission to replace a folder of documents.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Test the transitions, not only the happy path
&lt;/h2&gt;

&lt;p&gt;The following is a proposed test matrix for this architecture, not a claim that these scenarios were executed for this article:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Scenario&lt;/th&gt;
&lt;th&gt;Observable invariant&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Start A, then B; resolve A last&lt;/td&gt;
&lt;td&gt;A changes neither B's result nor its busy state&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Dispose while work is pending&lt;/td&gt;
&lt;td&gt;Late completion does not update the disposed view&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Request the same unloaded tool twice&lt;/td&gt;
&lt;td&gt;Initialization is shared&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Request A, then B; finish loading A last&lt;/td&gt;
&lt;td&gt;Latest permitted navigation stays active&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Active tool refuses close&lt;/td&gt;
&lt;td&gt;New navigation preserves the current workflow&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;One cleanup callback throws&lt;/td&gt;
&lt;td&gt;Remaining cleanups still run&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Conversion fails after staging begins&lt;/td&gt;
&lt;td&gt;Incomplete output is not presented as a completed artifact&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compression returns a no-output status&lt;/td&gt;
&lt;td&gt;Caller does not assume a new file was created&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MCP runs with diagnostics enabled&lt;/td&gt;
&lt;td&gt;Standard output remains valid protocol traffic&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Deferred promises make the frontend races deterministic: resolve them in the wrong order deliberately instead of hoping a slow machine reproduces the bug. File-writing tests should use temporary fixtures and inspect both content and directory state after failure.&lt;/p&gt;

&lt;p&gt;The common thread is ownership. A result needs an owner that is still current. A resource needs an owner that will release it. An output file needs a contract that tells the next caller whether it exists and whether it is complete.&lt;/p&gt;

&lt;p&gt;Those boundaries are worth defining before a toolbox becomes large. They remain useful whether the application has five tools or fifty.&lt;/p&gt;

&lt;h3&gt;
  
  
  Source references
&lt;/h3&gt;

&lt;p&gt;The source review used revision &lt;code&gt;0f088b0ee25ac3a1d362c740fed7267ab4b36b36&lt;/code&gt;. Code examples above are explanatory; the linked implementation is the authority for its exact behavior.&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>architecture</category>
    </item>
    <item>
      <title>463 GitHub Stars Didn't Validate My Windows App. Other People's PCs Did.</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Mon, 17 Aug 2026 13:28:43 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/463-github-stars-didnt-validate-my-windows-app-other-peoples-pcs-did-23g4</link>
      <guid>https://dev.to/dngzihng114379/463-github-stars-didnt-validate-my-windows-app-other-peoples-pcs-did-23g4</guid>
      <description>&lt;p&gt;Eighteen days after I open-sourced &lt;a href="https://github.com/ZihangDong/toolknit-desktop" rel="noopener noreferrer"&gt;ToolKnit Desktop&lt;/a&gt;, the repository had reached 463 GitHub stars and 56 forks. GitHub's release asset counter had also passed 3,000 installer downloads across four public releases.&lt;/p&gt;

&lt;p&gt;Those figures are a snapshot from August 17, 2026, and asset downloads are not the same as unique users. Still, they told me that people were curious.&lt;/p&gt;

&lt;p&gt;They did not tell me that the app was reliable.&lt;/p&gt;

&lt;p&gt;The useful feedback arrived when ToolKnit left my machine.&lt;/p&gt;

&lt;p&gt;A hardware inspector that worked on my Windows 10 machine returned nothing on another user's Windows 11 system. A window that maximized perfectly most of the time occasionally left a thin gap along the top and left edges. PPT conversion worked, but on some machines it was slow enough to feel broken and could trigger a Windows printer dialog. An audio tool kept resources from the previously loaded file. A PDF text-editing experiment produced ghosted text because the original page content and the replacement layer were both visible.&lt;/p&gt;

&lt;p&gt;None of those problems appeared in the clean version of the product that existed on my own computer.&lt;/p&gt;

&lt;p&gt;The first 463 stars did not validate my code. They expanded the number of environments in which it could be wrong.&lt;/p&gt;

&lt;p&gt;That has been the most valuable part of releasing it.&lt;/p&gt;

&lt;h2&gt;
  
  
  It started with one file problem
&lt;/h2&gt;

&lt;p&gt;ToolKnit began with an ordinary PDF task.&lt;/p&gt;

&lt;p&gt;I did not want another subscription, another oversized application, or another website asking me to upload a private document. I needed a small operation to be simple, predictable, and close to the file itself.&lt;/p&gt;

&lt;p&gt;One PDF tool became several. The same pattern appeared with images, audio, video, text, and presentations. Many everyday file operations were individually small, but the available solutions were often fragmented across unrelated applications and websites.&lt;/p&gt;

&lt;p&gt;Eventually I decided that some of these workflows needed a real desktop environment.&lt;/p&gt;

&lt;p&gt;Browsers are excellent for quick access, but local files introduce requirements that are easier to handle in a desktop application:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;larger files and longer-running jobs&lt;/li&gt;
&lt;li&gt;repeatable output directories&lt;/li&gt;
&lt;li&gt;native drag and drop&lt;/li&gt;
&lt;li&gt;local command-line automation&lt;/li&gt;
&lt;li&gt;hardware and system inspection&lt;/li&gt;
&lt;li&gt;optional processing runtimes&lt;/li&gt;
&lt;li&gt;explicit control over when data leaves the machine&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That became ToolKnit Desktop.&lt;/p&gt;

&lt;p&gt;I build and primarily maintain it alone, usually after my day job. That makes scope discipline and reusable patterns less of an aesthetic preference and more of a survival constraint.&lt;/p&gt;

&lt;p&gt;Version 2.0, released on August 16, contains 49 desktop tools across 11 categories, with 46 selected capabilities exposed through MCP. They cover PDF, PPT, image, audio, video, text, calculators, hardware inspection, cleanup, creative utilities, and AI-assisted workflows.&lt;/p&gt;

&lt;p&gt;The application is Windows-first and built with Tauri 2, Rust, and JavaScript. It also uses focused engines where appropriate, including PDF.js, pdf-lib, qpdf, FFmpeg, Whisper, and LibreOffice.&lt;/p&gt;

&lt;p&gt;The technology list is less important than the boundary around each component: one engine should solve one clear class of problems, and the application should make its inputs, outputs, dependencies, and failure modes visible.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F9kj8aty0lr01pntu26j0.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F9kj8aty0lr01pntu26j0.png" alt="ToolKnit Desktop 2.0 home screen" width="800" height="514"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Local-first requires more than avoiding an upload button
&lt;/h2&gt;

&lt;p&gt;ToolKnit is local-first by default.&lt;/p&gt;

&lt;p&gt;Its ordinary PDF, PPT, image, audio, video, text, hardware, and cleanup operations run on the user's computer. ToolKnit does not upload those source files to its own server.&lt;/p&gt;

&lt;p&gt;That statement needs qualification because the application also includes AI features.&lt;/p&gt;

&lt;p&gt;When a user explicitly invokes AI polishing, translation, document generation, table generation, or another model-backed workflow, the relevant content is sent to the model service that user configured. The interface must make that transition clear.&lt;/p&gt;

&lt;p&gt;This distinction matters. "Local-first" should describe an observable data boundary, not act as a vague privacy label.&lt;/p&gt;

&lt;p&gt;I started treating every feature as a processing contract:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;preflight
  -&amp;gt; validate input
  -&amp;gt; declare required dependency
  -&amp;gt; execute locally or request explicit remote authorization
  -&amp;gt; report progress
  -&amp;gt; return a structured result
  -&amp;gt; reveal the exact output location
  -&amp;gt; support retry, cancellation, or recovery
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That model improved more than privacy messaging. It also made the application easier to test and helped connect the desktop interface to the CLI and MCP layers.&lt;/p&gt;

&lt;h2&gt;
  
  
  One capability, three different surfaces
&lt;/h2&gt;

&lt;p&gt;ToolKnit 2.0 supports three ways of working with suitable capabilities:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;The desktop application provides visual preview, drag and drop, editing, and interactive configuration.&lt;/li&gt;
&lt;li&gt;The CLI supports deterministic batch operations and scripts.&lt;/li&gt;
&lt;li&gt;MCP exposes selected local capabilities to compatible IDE agents through explicit tool contracts.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;These surfaces should share behavior, but they should not blindly expose every feature.&lt;/p&gt;

&lt;p&gt;A PDF merge operation has clear files, ordering, output, and error conditions. It fits a CLI or agent tool well.&lt;/p&gt;

&lt;p&gt;Dragging a visual component inside a PDF editor is different. Its core export logic may be reusable, but the interaction itself belongs in the desktop application.&lt;/p&gt;

&lt;p&gt;This led to a useful rule:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;A feature should enter the CLI or MCP layer only when its inputs, side effects, progress, output, and failures can be explained without relying on hidden UI state.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Adding a command is easy. Maintaining a trustworthy automation contract is the real work.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 1: maximizing a custom window was probabilistic
&lt;/h2&gt;

&lt;p&gt;ToolKnit uses custom window chrome and optional rounded corners.&lt;/p&gt;

&lt;p&gt;At normal size, the window could look correct. When maximized, the rounded corners needed to disappear so the content reached the screen edges. The first implementation appeared to work, but repeated testing exposed a small probability that the top or left side would not fully cover the available area.&lt;/p&gt;

&lt;p&gt;This was not a simple CSS &lt;code&gt;border-radius&lt;/code&gt; bug.&lt;/p&gt;

&lt;p&gt;Several states were involved:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the native Windows window state&lt;/li&gt;
&lt;li&gt;the Tauri maximize event&lt;/li&gt;
&lt;li&gt;the transparent window surface&lt;/li&gt;
&lt;li&gt;the custom frame and shadow&lt;/li&gt;
&lt;li&gt;the frontend's maximized class&lt;/li&gt;
&lt;li&gt;the timing of the final bounds update&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If those states changed in the wrong order, the visual result could be one frame behind the native window.&lt;/p&gt;

&lt;p&gt;The larger lesson was that system state needs a single synchronization path. Every page should not implement its own maximize logic, and frontend layout should not guess whether the native window is maximized.&lt;/p&gt;

&lt;p&gt;The fix required treating maximize and restore as transitions, not isolated button clicks. The application needed one shared window-state controller, consistent state reconciliation, and repeated testing across maximize, restore, double-click, taskbar restoration, and keyboard-driven window changes.&lt;/p&gt;

&lt;p&gt;A bug that happened only occasionally was still a release bug. Probability is not the same as harmlessness.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 2: Windows 10 success said nothing about Windows 11
&lt;/h2&gt;

&lt;p&gt;The hardware tools originally worked on the machine where I built them.&lt;/p&gt;

&lt;p&gt;Then a Windows 11 Professional user opened every hardware page and received incomplete data. Running the app as administrator did not help. The useful clue appeared only after the application began preserving and displaying the underlying error:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;CannotCreateTypeConstrainedLanguage
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A PowerShell execution environment was preventing an operation that my development machine allowed.&lt;/p&gt;

&lt;p&gt;This changed how I thought about Windows compatibility. "Works on Windows" is not one test case. Different editions, policies, language modes, permissions, firmware implementations, drivers, and vendor-specific data can all change the result.&lt;/p&gt;

&lt;p&gt;Hardware inspection now has to be approached as a layered query problem:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;prefer stable system interfaces&lt;/li&gt;
&lt;li&gt;avoid unnecessary dynamic type creation&lt;/li&gt;
&lt;li&gt;preserve stderr instead of reducing every failure to "inspection failed"&lt;/li&gt;
&lt;li&gt;provide fallback sources when one query path is unavailable&lt;/li&gt;
&lt;li&gt;allow partial results rather than discarding the entire inspection&lt;/li&gt;
&lt;li&gt;distinguish permissions from unsupported or missing data&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The most important improvement was not another query. It was exposing the actual failure.&lt;/p&gt;

&lt;p&gt;A specific error can be fixed. A generic toast cannot.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 3: PPT conversion was really dependency management
&lt;/h2&gt;

&lt;p&gt;Converting PPT files accurately is not just a matter of reading XML from a ZIP archive. Fonts, shapes, layout rules, transitions, and Office rendering behavior make fidelity difficult.&lt;/p&gt;

&lt;p&gt;ToolKnit uses an optional LibreOffice runtime for PPT rendering. Bundling that runtime into the base installer would substantially increase the download for every user, including people who never open a presentation tool.&lt;/p&gt;

&lt;p&gt;So the runtime is installed on demand.&lt;/p&gt;

&lt;p&gt;That decision created a complete secondary product flow:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;detect whether the dependency is available&lt;/li&gt;
&lt;li&gt;prevent entry into a tool that cannot work yet&lt;/li&gt;
&lt;li&gt;offer official and regional download sources&lt;/li&gt;
&lt;li&gt;display download and installation stages separately&lt;/li&gt;
&lt;li&gt;verify the extracted runtime&lt;/li&gt;
&lt;li&gt;store it in the application's managed data location&lt;/li&gt;
&lt;li&gt;reuse it without rescanning on every page render&lt;/li&gt;
&lt;li&gt;run conversions headlessly with an isolated profile&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The first progress indicator reached 100% while extraction and verification were still running. From the user's perspective, the installation froze for another minute. Technically, the download was complete. Product-wise, the progress report was misleading.&lt;/p&gt;

&lt;p&gt;PPT conversion also exposed a printer-related Windows dialog and took too long on small presentations. Resolving the runtime path repeatedly and starting conversion with the wrong process assumptions made the workflow slower and noisier than necessary.&lt;/p&gt;

&lt;p&gt;The general lesson is that optional dependencies are not a packaging footnote. Detection, installation, verification, startup cost, caching, and failure recovery are part of the feature.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 4: the second audio file was more revealing than the first
&lt;/h2&gt;

&lt;p&gt;The BPM detector became much more accurate after improving the analysis pipeline, but another problem remained.&lt;/p&gt;

&lt;p&gt;When a user uploaded a different audio file, the previous playback and processing state was not completely destroyed. The new file entered a page that still contained resources associated with the old one.&lt;/p&gt;

&lt;p&gt;This class of bug appears across media tools:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;old object URLs remain alive&lt;/li&gt;
&lt;li&gt;animation frames continue running&lt;/li&gt;
&lt;li&gt;audio contexts or nodes survive&lt;/li&gt;
&lt;li&gt;stale asynchronous results update the new session&lt;/li&gt;
&lt;li&gt;waveform data is reused unintentionally&lt;/li&gt;
&lt;li&gt;previous playback position leaks into the next file&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The first upload is a happy-path test. The second upload is a lifecycle test.&lt;/p&gt;

&lt;p&gt;I now consider replacement, cancellation, and page exit part of the core media workflow. Every resource should have a clear owner and a clear destruction point.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 5: PDF text is not a word processor document
&lt;/h2&gt;

&lt;p&gt;A user opened a normal, non-scanned PDF and expected to change a word directly.&lt;/p&gt;

&lt;p&gt;That expectation is reasonable. The internal structure of a PDF makes it difficult.&lt;/p&gt;

&lt;p&gt;Visible text may be stored as separate glyph runs with embedded fonts, transformation matrices, positioning commands, and no semantic concept of a paragraph. Replacing one word can change its width without providing any layout engine to reflow the surrounding content.&lt;/p&gt;

&lt;p&gt;My lightweight editor used selectable hit regions and replacement layers. When the original content was not masked precisely, the replacement appeared on top of the old text and created a visible ghost.&lt;/p&gt;

&lt;p&gt;That failure clarified the product boundary.&lt;/p&gt;

&lt;p&gt;ToolKnit can support useful lightweight PDF edits, insertion, movement, resizing, rotation, masking, and export. It should not claim to provide the same native document model as a full professional PDF editor.&lt;/p&gt;

&lt;p&gt;The engineering work is still valuable, but the interface and documentation must describe what the tool actually guarantees.&lt;/p&gt;

&lt;h2&gt;
  
  
  Responsive UI bugs usually appeared after real data arrived
&lt;/h2&gt;

&lt;p&gt;Many pages looked correct in their initial empty state.&lt;/p&gt;

&lt;p&gt;Then a result arrived.&lt;/p&gt;

&lt;p&gt;Long filenames exceeded a dialog. Statistics overlapped controls. A right-side preview grew while the middle column stayed empty. A menu opened beneath a scrolling list because its stacking context was wrong. Controls that fit in a maximized window were clipped at the default 1400 x 900 size.&lt;/p&gt;

&lt;p&gt;These bugs encouraged a better layout test matrix:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Dimension&lt;/th&gt;
&lt;th&gt;Cases&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Window&lt;/td&gt;
&lt;td&gt;default, maximized, restored&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Data&lt;/td&gt;
&lt;td&gt;empty, short, long, many items&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Task&lt;/td&gt;
&lt;td&gt;idle, running, completed, failed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Lifecycle&lt;/td&gt;
&lt;td&gt;first file, replacement file, repeated run&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Environment&lt;/td&gt;
&lt;td&gt;dependency present, absent, damaged&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;System&lt;/td&gt;
&lt;td&gt;Windows versions, scaling, permission levels&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A screenshot of an empty page is not evidence of responsive behavior. A page needs to survive its largest meaningful state.&lt;/p&gt;

&lt;h2&gt;
  
  
  Open source widened the test surface
&lt;/h2&gt;

&lt;p&gt;Before release, I had tested almost every feature myself. That was useful, but all of those tests still shared many assumptions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the same hardware&lt;/li&gt;
&lt;li&gt;the same Windows configuration&lt;/li&gt;
&lt;li&gt;the same display&lt;/li&gt;
&lt;li&gt;the same network&lt;/li&gt;
&lt;li&gt;the same filesystem habits&lt;/li&gt;
&lt;li&gt;the same understanding of how the interface was intended to work&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;External users removed those shared assumptions.&lt;/p&gt;

&lt;p&gt;Their reports showed that a reproducible bug description can be more valuable than another feature request. The project also received its first outside pull requests, which forced me to think more clearly about contribution scope, regression risk, and how to review changes without losing product consistency.&lt;/p&gt;

&lt;p&gt;Stars helped people discover the repository. Issues, screenshots, sample files, and environment details helped improve it.&lt;/p&gt;

&lt;p&gt;Those are different forms of contribution, and both matter.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I would recommend to another solo developer
&lt;/h2&gt;

&lt;p&gt;The lessons I am carrying forward are simple, but not easy.&lt;/p&gt;

&lt;h3&gt;
  
  
  Define completion around repeated use
&lt;/h3&gt;

&lt;p&gt;Test the second upload, second run, cancel path, restored window, and missing dependency.&lt;/p&gt;

&lt;h3&gt;
  
  
  Preserve real errors
&lt;/h3&gt;

&lt;p&gt;Do not replace actionable stderr with a generic notification. Sanitize it, bound its length, and give the user enough context to report it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Centralize operating-system behavior
&lt;/h3&gt;

&lt;p&gt;Window controls, storage paths, permissions, dependency resolution, and external process execution should not be reimplemented independently by every page.&lt;/p&gt;

&lt;h3&gt;
  
  
  Make privacy boundaries concrete
&lt;/h3&gt;

&lt;p&gt;State which operations are local, which invoke a configured external provider, and what data is sent.&lt;/p&gt;

&lt;h3&gt;
  
  
  Use on-demand dependencies deliberately
&lt;/h3&gt;

&lt;p&gt;A smaller installer is useful only if dependency installation is understandable and recoverable.&lt;/p&gt;

&lt;h3&gt;
  
  
  Let automation earn its interface
&lt;/h3&gt;

&lt;p&gt;Expose a capability to CLI or MCP when it has a deterministic, inspectable contract, not merely because automation sounds impressive.&lt;/p&gt;

&lt;h3&gt;
  
  
  Publish before your environment becomes your only reality
&lt;/h3&gt;

&lt;p&gt;Private testing can verify logic. It cannot reproduce the diversity of real Windows machines.&lt;/p&gt;

&lt;h2&gt;
  
  
  What ToolKnit 2.0 is, and is not
&lt;/h2&gt;

&lt;p&gt;ToolKnit Desktop 2.0 is a Windows-first local file workbench with 49 tools across 11 categories.&lt;/p&gt;

&lt;p&gt;It is not a replacement for every professional creative or document application. Some advanced capabilities require optional runtimes. AI operations are not offline unless the configured provider itself is local. Lightweight PDF editing has format-level limitations.&lt;/p&gt;

&lt;p&gt;I think stating those limits makes the project stronger.&lt;/p&gt;

&lt;p&gt;The purpose of ToolKnit is not to promise that one application solves every possible file problem. It is to make a useful set of frequent operations clearer, more local, and easier to repeat.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it, inspect it, or break an assumption
&lt;/h2&gt;

&lt;p&gt;ToolKnit Desktop is open source under the Apache License 2.0.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;GitHub:&lt;/strong&gt; &lt;a href="https://github.com/ZihangDong/toolknit-desktop" rel="noopener noreferrer"&gt;github.com/ZihangDong/toolknit-desktop&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Windows release:&lt;/strong&gt; &lt;a href="https://github.com/ZihangDong/toolknit-desktop/releases/tag/v2.0.0" rel="noopener noreferrer"&gt;ToolKnit Desktop 2.0.0&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Web version:&lt;/strong&gt; &lt;a href="https://toolknit.com" rel="noopener noreferrer"&gt;toolknit.com&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Issues:&lt;/strong&gt; &lt;a href="https://github.com/ZihangDong/toolknit-desktop/issues" rel="noopener noreferrer"&gt;github.com/ZihangDong/toolknit-desktop/issues&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you test it, a reproducible issue with the Windows version, operation, file type, and visible error is especially helpful.&lt;/p&gt;

&lt;p&gt;For other solo developers, I am curious:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Which bug in your product appeared only after it left your own machine?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That is the part of open-source growth I now value most.&lt;/p&gt;

</description>
      <category>opensource</category>
      <category>tauri</category>
      <category>testing</category>
      <category>rust</category>
    </item>
    <item>
      <title>We Didn't Build a 'Compress PDF' Button. We Built a Constraint Solver.</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Thu, 06 Aug 2026 09:11:40 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/we-didnt-build-a-compress-pdf-button-we-built-a-constraint-solver-hob</link>
      <guid>https://dev.to/dngzihng114379/we-didnt-build-a-compress-pdf-button-we-built-a-constraint-solver-hob</guid>
      <description>&lt;p&gt;"Make this PDF under 5 MB" sounds like a setting.&lt;/p&gt;

&lt;p&gt;It is not.&lt;/p&gt;

&lt;p&gt;For a browser-based PDF tool, that request is a constrained search problem with a user-facing promise attached to it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;output.size &amp;lt;= chosen limit
while preserving as much readable page appearance as possible
without making the interface feel stuck
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The easy implementation is a quality slider. The hard part is delivering a result that is actually below the chosen limit, explaining the trade-off honestly, and not turning every adjustment into another full PDF render.&lt;/p&gt;

&lt;p&gt;This is how I approached target-size PDF compression in a browser-only tool.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmi5ij2ei62z7kciv1rey.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmi5ij2ei62z7kciv1rey.png" alt="Target-size controls with presets, a slider, and an exact maximum field" width="800" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The request is deceptively simple
&lt;/h2&gt;

&lt;p&gt;Users do not normally ask for "JPEG quality 0.64" or "render at 1.13x." They ask for something concrete:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;"This portal only accepts PDFs below 500 KB."&lt;/li&gt;
&lt;li&gt;"My email attachment has to stay below 5 MB."&lt;/li&gt;
&lt;li&gt;"I need to upload this form, but the file limit is 1 MB."&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That means the product contract is different from ordinary compression. A result that looks good but is 501 KB for a 500 KB upload limit is still a failure.&lt;/p&gt;

&lt;p&gt;At the same time, a result that is technically 100 KB but destroys legibility is not a useful success. The goal is not to create the smallest PDF. The goal is to find the largest acceptable output that still obeys the user's limit.&lt;/p&gt;

&lt;h2&gt;
  
  
  The first bad idea: re-render the PDF on every attempt
&lt;/h2&gt;

&lt;p&gt;The naive loop looks like this:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Render every PDF page.&lt;/li&gt;
&lt;li&gt;Encode each page as JPEG at one quality level.&lt;/li&gt;
&lt;li&gt;Build a new PDF.&lt;/li&gt;
&lt;li&gt;Check its byte size.&lt;/li&gt;
&lt;li&gt;Repeat from step 1 if it is too large.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;It works, but it repeats the most expensive part of the job. A multi-page PDF can require several full page renders before the search settles near the target. That wastes CPU time, reallocates large canvases, and makes the UI feel increasingly slow as documents get longer.&lt;/p&gt;

&lt;p&gt;The more useful question is not "Which quality preset should I use?" It is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;How can I reuse the expensive work while searching two variables: render scale and JPEG quality?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Turn repeated rendering into a bounded search
&lt;/h2&gt;

&lt;p&gt;The workflow starts by preparing each page once at a bounded source resolution. The browser renders the PDF page to a canvas, encodes a reusable source JPEG, records the original page dimensions, and releases the canvas. There is also a memory budget, because a browser tool should not try to hold an unlimited number of huge page images in memory just to chase a smaller result.&lt;/p&gt;

&lt;p&gt;After that preparation stage, each candidate is described by two values:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;quality&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;scale&lt;/code&gt; changes the number of pixels available to the page. &lt;code&gt;quality&lt;/code&gt; changes JPEG encoding fidelity. Both affect the final byte size, but neither maps perfectly to it. A mostly-text page, a scanned page, and a photo-heavy brochure respond very differently.&lt;/p&gt;

&lt;p&gt;The search begins at the highest safe settings. For every candidate, the compressor records one of two things:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the closest candidate that is still too large; or&lt;/li&gt;
&lt;li&gt;the largest candidate already at or below the requested limit.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Once there is one candidate on each side of the limit, the next attempt can refine between them instead of blindly dropping quality. The implementation uses logarithmic interpolation for that refinement because file sizes do not behave like a neat linear slider.&lt;/p&gt;

&lt;p&gt;Here is the essential shape of the search:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;bestFit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;tooLarge&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;highestSafeSettings&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;maxAttempts&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;attempt&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;buildCandidate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="nx"&gt;targetBytes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;bestFit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;keepTheLargerOf&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;bestFit&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;refineBetween&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tooLarge&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;bestFit&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;targetBytes&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;tooLarge&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;keepTheSmallerOf&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tooLarge&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="nx"&gt;settings&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;lowerScaleAndQuality&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;targetBytes&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;bestFit&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;There are two important details here:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;The output is measured after the PDF has actually been encoded. Estimating size from dimensions or JPEG quality is not enough.&lt;/li&gt;
&lt;li&gt;The search has strict lower bounds and a fixed attempt limit. If the minimum readable settings cannot meet the request, the tool has to say so.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  A Worker helps, but it is not magic
&lt;/h2&gt;

&lt;p&gt;Preparing source pages still requires browser PDF rendering. The repeated candidate assembly is where the work becomes especially wasteful, so that stage runs in a Web Worker when the browser supports it.&lt;/p&gt;

&lt;p&gt;The Worker receives the prepared page images and builds candidate PDFs away from the interaction path. The main page can keep showing progress while candidates are encoded and measured. If the Worker cannot start, or if the prepared sources would exceed the safe memory budget, the tool falls back to a compatible in-page path instead of failing the conversion entirely.&lt;/p&gt;

&lt;p&gt;That distinction matters. A Worker is not a claim that every byte of PDF work suddenly becomes free or GPU-accelerated. It is a way to avoid repeatedly tying up the interface during the part of the search that can safely happen elsewhere.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7kedl10ck91mng02btes.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7kedl10ck91mng02btes.png" alt="Browser progress while source pages are prepared for target-size PDF compression" width="800" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The honesty requirement: visual preservation is not semantic preservation
&lt;/h2&gt;

&lt;p&gt;There is a product trade-off that must be visible before the user clicks the button.&lt;/p&gt;

&lt;p&gt;For strict target-size compression, the tool rebuilds pages as optimized JPEG images inside a new PDF. That preserves the visible page appearance, but it does &lt;strong&gt;not&lt;/strong&gt; preserve:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;selectable and searchable text;&lt;/li&gt;
&lt;li&gt;links;&lt;/li&gt;
&lt;li&gt;form fields;&lt;/li&gt;
&lt;li&gt;bookmarks; or&lt;/li&gt;
&lt;li&gt;accessibility tags.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It would be easy to hide that limitation under a generic "high compression" label. That would also be misleading. A user sending a scanned receipt may be perfectly happy with an image-based result. A user submitting an accessible form or a searchable contract probably should keep the original.&lt;/p&gt;

&lt;p&gt;So the interface states the trade-off in the target-size mode itself, rather than discovering it only after download.&lt;/p&gt;

&lt;h2&gt;
  
  
  Verification is the feature, not the progress bar
&lt;/h2&gt;

&lt;p&gt;The result screen is deliberately simple: show the original size, the final size, the percentage reduction, and whether the result meets the exact cap.&lt;/p&gt;

&lt;p&gt;In one local test with a three-page image-heavy PDF, the input was &lt;strong&gt;1.09 MB&lt;/strong&gt;. The chosen maximum was &lt;strong&gt;500 KB&lt;/strong&gt;. The completed output was &lt;strong&gt;473.0 KB&lt;/strong&gt;, or &lt;strong&gt;58% smaller&lt;/strong&gt;. The download became available only after the final bytes were verified against the limit.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F87bnhwea44dbdl2opqvz.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F87bnhwea44dbdl2opqvz.png" alt="Verified result showing 1.09 MB reduced to 473 KB under a 500 KB limit" width="800" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The opposite outcome is equally important. If the compressor reaches its declared minimum settings and still cannot satisfy the limit, it should not show a green success state or hand the user a file that will fail their upload. "Cannot meet this limit safely" is a valid product result.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I learned
&lt;/h2&gt;

&lt;p&gt;The interesting part of a target-size compressor is not the slider. It is the decision to treat the chosen size as a contract:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;prepare expensive source data once;&lt;/li&gt;
&lt;li&gt;search bounded combinations of scale and quality;&lt;/li&gt;
&lt;li&gt;keep the best valid result rather than the first valid result;&lt;/li&gt;
&lt;li&gt;isolate repeated assembly work when the browser can support it;&lt;/li&gt;
&lt;li&gt;clearly disclose what a rasterized result loses; and&lt;/li&gt;
&lt;li&gt;refuse to label an over-limit file as successful.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That pattern applies beyond PDFs. Any browser feature that promises an exact output size, duration, or quota is usually not one knob. It is a constrained optimization problem with product decisions around honesty, fallbacks, and failure states.&lt;/p&gt;

&lt;p&gt;You can try the browser-only implementation here: &lt;a href="https://toolknit.com/tools/compress-pdf.html" rel="noopener noreferrer"&gt;Compress PDF to a Target Size&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>webdev</category>
      <category>performance</category>
      <category>pdf</category>
    </item>
    <item>
      <title>Building a Dice Roller That Teaches Probability: Batches, Histograms, and CSV</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Mon, 27 Jul 2026 01:32:36 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/building-a-dice-roller-that-teaches-probability-batches-histograms-and-csv-4jpa</link>
      <guid>https://dev.to/dngzihng114379/building-a-dice-roller-that-teaches-probability-batches-histograms-and-csv-4jpa</guid>
      <description>&lt;p&gt;A dice roller looks like a one-line project:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;random&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That line is enough to draw a number from 1 through 6. It is not enough to make a useful probability tool.&lt;/p&gt;

&lt;p&gt;The interesting engineering begins when a user asks the next questions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Can I roll several dice at once?&lt;/li&gt;
&lt;li&gt;Can I run 10, 50, or 100 trials without freezing the page?&lt;/li&gt;
&lt;li&gt;Is the result distribution behaving as expected?&lt;/li&gt;
&lt;li&gt;What exactly does the displayed average measure?&lt;/li&gt;
&lt;li&gt;Can I export the observations and inspect them elsewhere?&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This article builds the mental model and the implementation behind those features. The goal is not a flashy animation. It is a small, honest experiment whose state, statistics, and limitations are easy to understand.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Define the experiment before writing the UI
&lt;/h2&gt;

&lt;p&gt;Suppose a user selects &lt;code&gt;k&lt;/code&gt; six-sided dice and presses Roll once. That action is one &lt;strong&gt;trial&lt;/strong&gt;, but it produces &lt;code&gt;k&lt;/code&gt; individual &lt;strong&gt;face observations&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The distinction matters. After 100 trials with 6 dice:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the trial count is 100;&lt;/li&gt;
&lt;li&gt;the number of observed faces is 600;&lt;/li&gt;
&lt;li&gt;the expected mean of a single face is 3.5;&lt;/li&gt;
&lt;li&gt;the expected mean of each trial total is &lt;code&gt;3.5 * 6 = 21&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;each face should account for roughly one sixth of the 600 face observations.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If a histogram divides a face count by 100 instead of 600, it is not showing a probability. It is mixing two different units.&lt;/p&gt;

&lt;p&gt;A compact state model makes those units explicit:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;diceCount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;trialCount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;grandTotal&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;faceCounts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="na"&gt;history&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;I use &lt;code&gt;trialCount&lt;/code&gt; for completed rolls and derive the number of face observations with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sampleCount&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;faceCounts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reduce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;sum&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;sum&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="mi"&gt;0&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Deriving this value is useful: the histogram remains correct even if a future feature allows the number of dice to change between trials.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Keep generation separate from recording
&lt;/h2&gt;

&lt;p&gt;The generator should have one job:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;rollD6&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;random&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;rollDice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;length&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;count&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="nx"&gt;rollD6&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The state update should be a separate operation:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;recordTrial&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reduce&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;sum&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;sum&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;trialCount&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;grandTotal&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;total&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;value&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;faceCounts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;history&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;trial&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;trialCount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;results&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[...&lt;/span&gt;&lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
    &lt;span class="nx"&gt;total&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;total&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This separation pays off immediately:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;animation can display a result without owning the statistics;&lt;/li&gt;
&lt;li&gt;batch mode can reuse the same recording logic;&lt;/li&gt;
&lt;li&gt;tests can pass fixed arrays to &lt;code&gt;recordTrial&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;CSV export can consume history without reading the DOM.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The DOM should be a view of the state, not the database for the experiment.&lt;/p&gt;

&lt;h3&gt;
  
  
  A necessary honesty note about &lt;code&gt;Math.random()&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;Math.random()&lt;/code&gt; is a pseudorandom generator supplied by the JavaScript engine. It is suitable for a casual dice toy, classroom demonstration, or UI simulation. It is &lt;strong&gt;not cryptographically secure&lt;/strong&gt;, and it should not be used for gambling, lotteries, authentication tokens, or any situation where an attacker benefits from predicting results.&lt;/p&gt;

&lt;p&gt;For security-sensitive randomness, use &lt;code&gt;crypto.getRandomValues()&lt;/code&gt; and design the integer mapping carefully so it does not introduce modulo bias. That is a different threat model from the educational simulator built here.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Measure the right averages
&lt;/h2&gt;

&lt;p&gt;An interface labeled simply "Average" is ambiguous. There are at least two legitimate averages:&lt;/p&gt;

&lt;h3&gt;
  
  
  Average trial total
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;averageTrialTotal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;trialCount&lt;/span&gt;
  &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;grandTotal&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;trialCount&lt;/span&gt;
  &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For a fixed &lt;code&gt;k&lt;/code&gt; fair d6 dice, this should move toward &lt;code&gt;3.5 * k&lt;/code&gt; as the number of trials grows.&lt;/p&gt;

&lt;p&gt;If the user changes the dice count without resetting, this average mixes different experiments. Either group the statistic by dice count, reset when &lt;code&gt;k&lt;/code&gt; changes, or label it clearly as an average across a mixed session. Comparing that mixed value with &lt;code&gt;3.5 * currentDiceCount&lt;/code&gt; would be misleading.&lt;/p&gt;

&lt;h3&gt;
  
  
  Average individual face
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sampleCount&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;faceCounts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reduce&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;averageFace&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;sampleCount&lt;/span&gt;
  &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;grandTotal&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;sampleCount&lt;/span&gt;
  &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This should move toward 3.5 regardless of how many dice are rolled per trial.&lt;/p&gt;

&lt;p&gt;Either metric is valid. The important part is to label it. If the UI shows &lt;code&gt;grandTotal / trialCount&lt;/code&gt;, call it "average total per roll," not "average die value."&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Build a histogram from observations, not impressions
&lt;/h2&gt;

&lt;p&gt;For each face, calculate an observed proportion:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;distribution&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;n&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;faceCounts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reduce&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;faceCounts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;index&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;face&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;index&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;proportion&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;n&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;count&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;n&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;expected&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;
  &lt;span class="p"&gt;}));&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The theoretical reference line is &lt;code&gt;1 / 6&lt;/code&gt;, or about 16.67%. It is a target for the long-run proportion, not a promise that every short run will be balanced.&lt;/p&gt;

&lt;p&gt;In fact, perfectly equal bars after a small number of rolls would be suspicious.&lt;/p&gt;

&lt;p&gt;For one face, the standard deviation of its observed proportion is approximately:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;sqrt(p * (1 - p) / N)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;where &lt;code&gt;p = 1/6&lt;/code&gt; and &lt;code&gt;N&lt;/code&gt; is the number of individual dice observations. An approximate 95% margin is 1.96 times that value.&lt;/p&gt;

&lt;p&gt;At 600 observations, the margin is about 3.0 percentage points. A face appearing 14% or 19% of the time is therefore not surprising. At 6,000 observations, the margin falls to about 0.94 percentage points.&lt;/p&gt;

&lt;p&gt;That shrinking range is a better demonstration of the law of large numbers than a vague statement that results "become random."&lt;/p&gt;

&lt;p&gt;You can add the range to the chart:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;approximate95Band&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;sampleCount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;sampleCount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;margin&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mf"&gt;1.96&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sqrt&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;p&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;sampleCount&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;lower&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;margin&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="na"&gt;upper&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;margin&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is an approximation, not a pass/fail fairness test. A formal goodness-of-fit test such as chi-square needs its own assumptions and interpretation. Adding a red "unfair" badge to a small random sample would teach the wrong lesson.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Batch work without blocking interaction
&lt;/h2&gt;

&lt;p&gt;Running 100 trials is computationally cheap. Rendering 100 animations, updating every bar 100 times, and rebuilding history after each result is where a small tool can become unpleasant.&lt;/p&gt;

&lt;p&gt;The first optimization is conceptual: &lt;strong&gt;compute every trial, but do not render every trial&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The second is scheduling. Process a small chunk, update the visible summary, then yield to the browser:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;runBatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;totalTrials&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;onProgress&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;onComplete&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;completed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;step&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;chunkSize&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;totalTrials&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;completed&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;chunkSize&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;recordTrial&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;rollDice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;diceCount&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nx"&gt;completed&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;chunkSize&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nf"&gt;onProgress&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;completed&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;totalTrials&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nf"&gt;renderSummary&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;completed&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;totalTrials&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;requestAnimationFrame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;step&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;onComplete&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nf"&gt;requestAnimationFrame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;step&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;requestAnimationFrame()&lt;/code&gt; does not make the calculation faster and it is not a worker. It schedules the next chunk before a future repaint, giving the main thread opportunities to render progress and respond between chunks.&lt;/p&gt;

&lt;p&gt;For 100 trials, this is sufficient. For hundreds of thousands or millions of trials, move simulation to a Web Worker and send aggregated counts back to the UI. Otherwise, the calculation still occupies the main thread even if it is divided into frames.&lt;/p&gt;

&lt;p&gt;Also guard against concurrent actions:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;isRunning&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;startBatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;size&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;isRunning&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;isRunning&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;setControlsDisabled&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="nf"&gt;runBatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nx"&gt;size&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;renderProgress&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;renderFinalDice&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
      &lt;span class="nf"&gt;setControlsDisabled&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
      &lt;span class="nx"&gt;isRunning&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Without a lock, two clicks can interleave batches, corrupt progress, and produce a history order that no longer matches the labels.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. Treat history as data, not decoration
&lt;/h2&gt;

&lt;p&gt;A common UI compromise is to show only the most recent 20 or 30 rows. That is fine for rendering performance, but it should not silently truncate the data exported by the user.&lt;/p&gt;

&lt;p&gt;Keep full history in memory and slice only for the visible list:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;visibleHistory&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;limit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;history&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nx"&gt;limit&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;reverse&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then export from &lt;code&gt;state.history&lt;/code&gt;, not from table rows.&lt;/p&gt;

&lt;p&gt;For a long-running simulator, full in-memory history eventually becomes expensive. At that point, decide explicitly between:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;a documented maximum history size;&lt;/li&gt;
&lt;li&gt;streaming rows to a file where supported;&lt;/li&gt;
&lt;li&gt;storing aggregate counts only;&lt;/li&gt;
&lt;li&gt;moving a bounded session to IndexedDB.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Do not allow an accidental memory limit to become an undocumented data-retention policy.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Export CSV that spreadsheet software can read
&lt;/h2&gt;

&lt;p&gt;CSV is deceptively simple. Values containing commas, quotes, or newlines must be escaped. A UTF-8 byte order mark is also helpful for some spreadsheet applications when headers contain non-ASCII text.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;csvCell&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;",&lt;/span&gt;&lt;span class="se"&gt;\n\r]&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="s2"&gt;`"&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;replaceAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;"&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;""&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="s2"&gt;"`&lt;/span&gt;
    &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;buildCsv&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;history&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;rows&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Trial&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Dice results&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Total&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
    &lt;span class="p"&gt;...&lt;/span&gt;&lt;span class="nx"&gt;history&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;entry&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="nx"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;trial&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;,&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
      &lt;span class="nx"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt;
    &lt;span class="p"&gt;])&lt;/span&gt;
  &lt;span class="p"&gt;];&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;rows&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;row&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;csvCell&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;,&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="se"&gt;\r\n&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;downloadCsv&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;history&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;csv&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;buildCsv&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;history&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Blob&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="se"&gt;\&lt;/span&gt;&lt;span class="s2"&gt;uFEFF&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;csv&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;text/csv;charset=utf-8&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;url&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createObjectURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;link&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createElement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;a&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;link&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;href&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;link&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;download&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;dice-rolls.csv&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;link&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;click&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="nx"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;revokeObjectURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The object URL is a temporary browser-local reference to the &lt;code&gt;Blob&lt;/code&gt;. Revoking it after the click releases that reference. No upload is required.&lt;/p&gt;

&lt;p&gt;If cells can contain user-controlled text and the file will be opened in a spreadsheet, also consider CSV formula injection. Values beginning with &lt;code&gt;=&lt;/code&gt;, &lt;code&gt;+&lt;/code&gt;, &lt;code&gt;-&lt;/code&gt;, or &lt;code&gt;@&lt;/code&gt; can be interpreted as formulas by some applications. Dice values are numeric and safe, but a reusable exporter should account for that threat.&lt;/p&gt;

&lt;h2&gt;
  
  
  8. Small UX decisions make the experiment legible
&lt;/h2&gt;

&lt;p&gt;Probability tools benefit from restraint. The useful feedback is:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the latest dice faces and total;&lt;/li&gt;
&lt;li&gt;completed trial count;&lt;/li&gt;
&lt;li&gt;total number of face observations;&lt;/li&gt;
&lt;li&gt;a clearly named average;&lt;/li&gt;
&lt;li&gt;observed counts and percentages beside a 16.67% reference;&lt;/li&gt;
&lt;li&gt;a Reset action that clears all experiment state;&lt;/li&gt;
&lt;li&gt;an Export action that is disabled when no data exists.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Animation should confirm an action, not delay analysis. One short animation for a manual roll is pleasant. Replaying it 100 times during batch mode turns a one-second calculation into a queue.&lt;/p&gt;

&lt;p&gt;Accessibility matters here too. Do not encode each face only as dot positions. Give the die an accessible label such as &lt;code&gt;Die 2: 5&lt;/code&gt;, expose batch progress with appropriate status text, and respect &lt;code&gt;prefers-reduced-motion&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  9. What to test
&lt;/h2&gt;

&lt;p&gt;The random output itself makes naive tests flaky. Test invariants and inject deterministic generators.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;createD6&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;random&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;random&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return &lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;random&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now boundary behavior is testable:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;alwaysOne&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createD6&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;almostOne&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createD6&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="mf"&gt;0.999999999999&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;alwaysOne&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;almostOne&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Also verify:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;every generated face is an integer from 1 through 6;&lt;/li&gt;
&lt;li&gt;the sum of face counts equals the number of dice observations;&lt;/li&gt;
&lt;li&gt;history length equals trial count unless a documented cap applies;&lt;/li&gt;
&lt;li&gt;resetting returns every counter and chart to zero;&lt;/li&gt;
&lt;li&gt;CSV row count equals history length plus the header;&lt;/li&gt;
&lt;li&gt;controls cannot start overlapping batches;&lt;/li&gt;
&lt;li&gt;changing dice count affects future trials without rewriting past history.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A statistical test that demands exactly one sixth of results in a small sample will fail valid randomness. Deterministic unit tests check logic; larger statistical checks are better treated as diagnostics with tolerances.&lt;/p&gt;

&lt;h2&gt;
  
  
  A working reference
&lt;/h2&gt;

&lt;p&gt;If you want to compare the behavior against a finished browser implementation, I use this &lt;a href="https://toolknit.com/tools/dice-roller.html?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=probability_tools&amp;amp;utm_content=dice_probability_inline" rel="noopener noreferrer"&gt;dice roller with batch runs, a live face distribution, history, and CSV export&lt;/a&gt;. It supports 1 to 6 d6 dice and 10, 50, or 100-trial batches. The calculation stays in the page.&lt;/p&gt;

&lt;p&gt;The source of value is not the random-number line. It is making the experiment's units visible, keeping the interface responsive, and giving the user their observations in a form they can inspect.&lt;/p&gt;

&lt;p&gt;That is the difference between a dice animation and a probability tool.&lt;/p&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random" rel="noopener noreferrer"&gt;MDN: &lt;code&gt;Math.random()&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame" rel="noopener noreferrer"&gt;MDN: &lt;code&gt;requestAnimationFrame()&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob" rel="noopener noreferrer"&gt;MDN: &lt;code&gt;Blob&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static" rel="noopener noreferrer"&gt;MDN: &lt;code&gt;URL.createObjectURL()&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.itl.nist.gov/div898/handbook/eda/section3/eda366i.htm" rel="noopener noreferrer"&gt;NIST/SEMATECH: Binomial distribution&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>javascript</category>
      <category>webdev</category>
      <category>tutorial</category>
      <category>data</category>
    </item>
    <item>
      <title>How I Built a Dice Roller That Google Can't Beat — A Technical Deep Dive</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Wed, 08 Jul 2026 08:48:15 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/how-i-built-a-dice-roller-that-google-cant-beat-a-technical-deep-dive-3i44</link>
      <guid>https://dev.to/dngzihng114379/how-i-built-a-dice-roller-that-google-cant-beat-a-technical-deep-dive-3i44</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fm1j1cdbxsyx99b7jkn5a.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fm1j1cdbxsyx99b7jkn5a.png" alt=" " width="800" height="966"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h1&gt;
  
  
  How I Built a Dice Roller That Google Can't Beat
&lt;/h1&gt;

&lt;p&gt;&lt;strong&gt;Google was stealing my clicks.&lt;/strong&gt; 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.&lt;/p&gt;

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




&lt;h2&gt;
  
  
  Part 1: The Discovery
&lt;/h2&gt;

&lt;p&gt;I run &lt;a href="https://toolknit.com" rel="noopener noreferrer"&gt;ToolKnit&lt;/a&gt;, 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.&lt;/p&gt;

&lt;p&gt;When I looked at the SERP for "dice roller," the answer was obvious:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Ftoolknit.com%2Fassets%2Fimg%2Fog-image.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Ftoolknit.com%2Fassets%2Fimg%2Fog-image.png" alt="Google SERP for dice roller" width="800" height="400"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Google displays an &lt;strong&gt;interactive dice widget&lt;/strong&gt; 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.&lt;/p&gt;

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

&lt;p&gt;&lt;strong&gt;The insight:&lt;/strong&gt; Stop trying to outrank Google. Instead, build something Google's widget &lt;em&gt;can't&lt;/em&gt; do.&lt;/p&gt;




&lt;h2&gt;
  
  
  Part 2: What Google's Dice Can't Do
&lt;/h2&gt;

&lt;p&gt;Google's built-in dice roller is minimal by design. It supports:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;D4, D6, D8, D10, D12, D20, D100&lt;/li&gt;
&lt;li&gt;Multiple dice (e.g., 3d6)&lt;/li&gt;
&lt;li&gt;Adding modifiers (+3, +5)&lt;/li&gt;
&lt;li&gt;An animation that shows results&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;What it &lt;strong&gt;doesn't&lt;/strong&gt; support:&lt;/p&gt;

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

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

&lt;p&gt;I decided to build all of them.&lt;/p&gt;




&lt;h2&gt;
  
  
  Part 3: The Technical Build
&lt;/h2&gt;

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

&lt;h3&gt;
  
  
  3.1 3D Dice Faces with Pure CSS
&lt;/h3&gt;

&lt;p&gt;The dice aren't images or SVGs — they're styled &lt;code&gt;&amp;lt;div&amp;gt;&lt;/code&gt; elements with CSS grid layouts. Each face shows the correct dot pattern:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="nc"&gt;.dice-face&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;display&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;grid&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="py"&gt;grid-template-columns&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;repeat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;3&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="n"&gt;fr&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="py"&gt;grid-template-rows&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;repeat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;3&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="n"&gt;fr&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nl"&gt;width&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;64px&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;height&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;64px&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;background&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;#1a1a2e&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;border&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;2px&lt;/span&gt; &lt;span class="nb"&gt;solid&lt;/span&gt; &lt;span class="n"&gt;rgba&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;255&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="m"&gt;255&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="m"&gt;255&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="m"&gt;0.12&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nl"&gt;border-radius&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;14px&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;padding&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;8px&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nc"&gt;.dot&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;width&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;12px&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;height&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;12px&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;background&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;#fff&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;border-radius&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;50%&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="py"&gt;place-self&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;center&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The roll animation applies a CSS transform sequence — rotation in 3D space with a scale bounce:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="k"&gt;@keyframes&lt;/span&gt; &lt;span class="n"&gt;diceRoll&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="err"&gt;0&lt;/span&gt;&lt;span class="o"&gt;%&lt;/span&gt;   &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;transform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;rotateX&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;0deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateY&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;0deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateZ&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;0deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="err"&gt;25&lt;/span&gt;&lt;span class="o"&gt;%&lt;/span&gt;  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;transform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;rotateX&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;180deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateY&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;90deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateZ&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;45deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;1.1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="err"&gt;50&lt;/span&gt;&lt;span class="o"&gt;%&lt;/span&gt;  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;transform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;rotateX&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;360deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateY&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;180deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateZ&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;90deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;0.95&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="err"&gt;75&lt;/span&gt;&lt;span class="o"&gt;%&lt;/span&gt;  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;transform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;rotateX&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;540deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateY&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;270deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateZ&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;135deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;1.05&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="err"&gt;100&lt;/span&gt;&lt;span class="o"&gt;%&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;transform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;rotateX&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;720deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateY&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;360deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;rotateZ&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;180deg&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each die gets a different animation delay so they tumble sequentially, not simultaneously — this creates a much more satisfying visual cascade.&lt;/p&gt;

&lt;h3&gt;
  
  
  3.2 requestAnimationFrame for Batch Rolling
&lt;/h3&gt;

&lt;p&gt;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: &lt;strong&gt;chunked processing with &lt;code&gt;requestAnimationFrame&lt;/code&gt;.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;batchRoll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;isRolling&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;isRolling&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;batchResults&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;
  &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;step&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Process 10 rolls per frame to avoid UI freeze&lt;/span&gt;
    &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;chunk&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;count&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;j&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;j&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;chunk&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;j&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;results&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;
      &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;diceCount&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;random&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="nx"&gt;batchResults&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

      &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reduce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;function&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
      &lt;span class="nx"&gt;rolls&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nx"&gt;grandTotal&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;total&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;forEach&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;function&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;v&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;distribution&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;v&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;chunk&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="c1"&gt;// Update UI every frame&lt;/span&gt;
    &lt;span class="nf"&gt;updateDistribution&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="nf"&gt;updateHistory&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="nx"&gt;progressBar&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;style&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;round&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;%&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;count&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nf"&gt;requestAnimationFrame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;step&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="c1"&gt;// Final animation for the last result&lt;/span&gt;
      &lt;span class="nf"&gt;renderDice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;batchResults&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;batchResults&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
      &lt;span class="nx"&gt;isRolling&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nf"&gt;requestAnimationFrame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;step&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Key decisions:&lt;/p&gt;

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

&lt;h3&gt;
  
  
  3.3 Game Presets
&lt;/h3&gt;

&lt;p&gt;Instead of asking users to configure dice manually, I added one-click presets for popular games:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Preset&lt;/th&gt;
&lt;th&gt;Dice&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Monopoly&lt;/td&gt;
&lt;td&gt;2d6&lt;/td&gt;
&lt;td&gt;Classic property-buying rolls&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Yahtzee&lt;/td&gt;
&lt;td&gt;5d6&lt;/td&gt;
&lt;td&gt;Five dice, three rolls per turn (manual)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Catan&lt;/td&gt;
&lt;td&gt;2d6&lt;/td&gt;
&lt;td&gt;Settlers resource distribution&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Craps&lt;/td&gt;
&lt;td&gt;2d6&lt;/td&gt;
&lt;td&gt;Casino-style come-out roll&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;D&amp;amp;D Skill&lt;/td&gt;
&lt;td&gt;1d20&lt;/td&gt;
&lt;td&gt;Ability checks and saving throws&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;
  
  
  3.4 Probability Distribution with Theoretical Comparison
&lt;/h3&gt;

&lt;p&gt;The distribution chart uses &lt;strong&gt;HTML5 Canvas&lt;/strong&gt; to draw a bar chart showing the frequency of each die face (1-6). But the real insight was adding a &lt;strong&gt;theoretical overlay:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Theoretical: exactly 1/6 = 16.67% per face&lt;/span&gt;
&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;theoretical&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;theoreticalHeight&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;maxBarHeight&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="nx"&gt;theoretical&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;fillStyle&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rgba(59, 130, 246, 0.25)&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fillRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;barX&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;chartH&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;theoreticalHeight&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;barW&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;theoreticalHeight&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each bar shows:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Actual frequency&lt;/strong&gt; (solid white/gray bar)&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Theoretical 16.67%&lt;/strong&gt; (semi-transparent blue overlay)&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;
  
  
  3.5 CSV Export
&lt;/h3&gt;

&lt;p&gt;Roll history is more useful when you can take it elsewhere. The CSV export button generates a downloadable file with headers:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;exportCSV&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;csv&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Roll#,Die1,Die2,Die3,Die4,Die5,Die6,Total&lt;/span&gt;&lt;span class="se"&gt;\n&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;historyData&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt;&lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;row&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;historyData&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;
    &lt;span class="nx"&gt;csv&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;roll&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;,&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;,&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;,&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="se"&gt;\n&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Blob&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="nx"&gt;csv&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;text/csv&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;url&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createObjectURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createElement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;a&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;href&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;download&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;dice-rolls.csv&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;click&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;
  
  
  3.6 Dice Skins
&lt;/h3&gt;

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

&lt;h3&gt;
  
  
  3.7 Keyboard Shortcuts
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addEventListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;keydown&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt; &lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Enter&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nf"&gt;roll&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;r&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;R&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nf"&gt;reset&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ArrowUp&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nf"&gt;changeDice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ArrowDown&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nf"&gt;changeDice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;1&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nf"&gt;batchRoll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;5&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nf"&gt;batchRoll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;50&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;0&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nf"&gt;batchRoll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



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




&lt;h2&gt;
  
  
  Part 4: The Results
&lt;/h2&gt;

&lt;p&gt;After the update, the dice roller went from a generic tool to a feature-rich dice toolbox. Key metrics:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Metric&lt;/th&gt;
&lt;th&gt;Before&lt;/th&gt;
&lt;th&gt;After&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Weekly Google impressions&lt;/td&gt;
&lt;td&gt;~200&lt;/td&gt;
&lt;td&gt;2,230+&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Weekly Bing impressions&lt;/td&gt;
&lt;td&gt;~50&lt;/td&gt;
&lt;td&gt;1,300+&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Total weekly exposure&lt;/td&gt;
&lt;td&gt;~250&lt;/td&gt;
&lt;td&gt;3,500+&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;That's a &lt;strong&gt;14× increase&lt;/strong&gt; in three months.&lt;/p&gt;

&lt;p&gt;The lesson: &lt;strong&gt;Google's SERP Features aren't an impenetrable wall.&lt;/strong&gt; 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.&lt;/p&gt;




&lt;h2&gt;
  
  
  Part 5: What I'd Do Differently
&lt;/h2&gt;

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




&lt;h2&gt;
  
  
  The Bigger Picture
&lt;/h2&gt;

&lt;p&gt;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:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Analyze what the SERP Feature does.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;List everything it &lt;em&gt;doesn't&lt;/em&gt; do that real users need.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Build those things.&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Don't try to outrank Google. Out-build them.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;This article was written by the creator of &lt;a href="https://toolknit.com" rel="noopener noreferrer"&gt;ToolKnit&lt;/a&gt; — 90 free browser-based tools that run entirely in your browser with no sign-up and no uploads. Try the &lt;a href="https://toolknit.com/tools/dice-roller.html" rel="noopener noreferrer"&gt;Dice Roller&lt;/a&gt; and let me know what else you'd want to see.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ffxs224exkjokogtc65ip.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ffxs224exkjokogtc65ip.png" alt=" " width="799" height="693"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fc3oz5bdvf6ryjb5y7m60.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fc3oz5bdvf6ryjb5y7m60.png" alt=" " width="800" height="1067"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fxlxtf72krf7044ogt6qe.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fxlxtf72krf7044ogt6qe.png" alt=" " width="800" height="1016"&gt;&lt;/a&gt;&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>webdev</category>
      <category>css</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>I Built a Free Breathing Relaxation Tool with 6 Science-Backed Techniques — Here's How It Works and Why You Should Try It</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Mon, 06 Jul 2026 07:09:54 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/i-built-a-free-breathing-relaxation-tool-with-6-science-backed-techniques-heres-how-it-works-and-4c14</link>
      <guid>https://dev.to/dngzihng114379/i-built-a-free-breathing-relaxation-tool-with-6-science-backed-techniques-heres-how-it-works-and-4c14</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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 &lt;strong&gt;Breathing Relaxation&lt;/strong&gt;, a free, privacy-first browser tool with 6 guided breathing techniques, now live at &lt;a href="https://toolknit.com/tools/breathing-relaxation.html" rel="noopener noreferrer"&gt;toolknit.com/tools/breathing-relaxation.html&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;In this post, I'll cover:&lt;/p&gt;

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




&lt;h2&gt;
  
  
  Why Breathing Works: A Quick Science Primer
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Slow, controlled breathing activates the parasympathetic nervous system&lt;/strong&gt; — 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 &lt;strong&gt;respiratory sinus arrhythmia&lt;/strong&gt; — and it's the physiological mechanism behind why deep breathing actually works.&lt;/p&gt;

&lt;p&gt;A 2017 meta-analysis published in &lt;em&gt;Frontiers in Psychology&lt;/em&gt; 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 &lt;em&gt;Cell Reports Medicine&lt;/em&gt; (2023) demonstrated that deliberate breathwork practices produced measurable changes in brain connectivity patterns associated with emotion regulation.&lt;/p&gt;

&lt;p&gt;The key: &lt;strong&gt;exhale longer than you inhale&lt;/strong&gt;. That's the signal your vagus nerve needs to trigger relaxation.&lt;/p&gt;




&lt;h2&gt;
  
  
  The 6 Techniques — When to Use Each
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. 4-7-8 Breathing (Dr. Andrew Weil)
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Pattern:&lt;/strong&gt; Inhale 4s → Hold 7s → Exhale 8s&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Best for:&lt;/strong&gt; Insomnia, acute anxiety, panic moments.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Box Breathing (Navy SEAL Technique)
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Pattern:&lt;/strong&gt; Inhale 4s → Hold 4s → Exhale 4s → Hold 4s&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Best for:&lt;/strong&gt; Pre-meeting jitters, public speaking, performance anxiety, regaining focus.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Coherent Breathing (5-5)
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Pattern:&lt;/strong&gt; Inhale 5s → Exhale 5s&lt;/p&gt;

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

&lt;p&gt;&lt;strong&gt;Best for:&lt;/strong&gt; Daily maintenance, meditation, sustained focus work.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. 4-2-4 Relaxation
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Pattern:&lt;/strong&gt; Inhale 4s → Hold 2s → Exhale 4s&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Best for:&lt;/strong&gt; Beginners, quick resets between meetings, afternoon slumps.&lt;/p&gt;

&lt;h3&gt;
  
  
  5. Energizing Breath
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Pattern:&lt;/strong&gt; Inhale 6s → Hold 2s → Exhale 4s&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Best for:&lt;/strong&gt; Morning energy, pre-workout, beating the 3pm slump.&lt;/p&gt;

&lt;h3&gt;
  
  
  6. Alternate Nostril Breathing (Nadi Shodhana)
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Pattern:&lt;/strong&gt; Inhale left 4s → Hold 4s → Exhale right 4s → Inhale right 4s → Hold 4s → Exhale left 4s&lt;/p&gt;

&lt;p&gt;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 &lt;em&gt;International Journal of Yoga&lt;/em&gt; found that regular alternate nostril breathing significantly reduced stress and improved attention in healthy adults.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Best for:&lt;/strong&gt; Mental clarity, balancing energy, pre-meditation.&lt;/p&gt;




&lt;h2&gt;
  
  
  The Tech Stack: How I Built It
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Canvas Animation Engine
&lt;/h3&gt;

&lt;p&gt;The breathing animation is powered by pure Canvas API — no libraries, no dependencies. Here's the core approach:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Simplified animation loop&lt;/span&gt;
&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;animate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;timestamp&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;progress&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;timestamp&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;startTime&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;phaseDuration&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;scale&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sin&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;progress&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;PI&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mf"&gt;0.35&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// Smooth expand/contract&lt;/span&gt;

    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;clearRect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;translate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;width&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;canvas&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;height&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="c1"&gt;// Draw the breathing circle&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;beginPath&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;arc&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;radius&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;PI&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fill&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;restore&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

    &lt;span class="nf"&gt;requestAnimationFrame&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;animate&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



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

&lt;p&gt;Each technique has its own phase configuration:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;techniques&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;4-7-8&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Inhale&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;expand&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Hold&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;  &lt;span class="na"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;7&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;hold&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Exhale&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;contract&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;],&lt;/span&gt;
    &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;box&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Inhale&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;expand&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Hold&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;  &lt;span class="na"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;hold&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Exhale&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;contract&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Hold&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;  &lt;span class="na"&gt;duration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;hold&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="c1"&gt;// ... etc&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Phase Timer &amp;amp; Visual Rhythm
&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

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

&lt;h3&gt;
  
  
  Web Audio API for Sound Cues
&lt;/h3&gt;

&lt;p&gt;When enabled, the tool plays subtle audio cues at phase transitions. I used the Web Audio API's &lt;code&gt;OscillatorNode&lt;/code&gt; to generate a soft, bell-like tone:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;playPhaseBeep&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;AudioContext&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;osc&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createOscillator&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;gain&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createGain&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

    &lt;span class="nx"&gt;osc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;sine&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nx"&gt;osc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;frequency&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;880&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// A5 — soft and pleasant&lt;/span&gt;
    &lt;span class="nx"&gt;gain&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;gain&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setValueAtTime&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;0.1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;currentTime&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;gain&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;gain&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;exponentialRampToValueAtTime&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;0.001&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;currentTime&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mf"&gt;0.3&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="nx"&gt;osc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;gain&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;gain&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;destination&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;osc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;start&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="nx"&gt;osc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stop&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;currentTime&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mf"&gt;0.3&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



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

&lt;h3&gt;
  
  
  Haptic Feedback (iOS)
&lt;/h3&gt;

&lt;p&gt;On supported devices, the tool uses the Vibration API to provide tactile cues:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;navigator&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;vibrate&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nb"&gt;navigator&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;vibrate&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="mi"&gt;50&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;50&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt; &lt;span class="c1"&gt;// short-long-short pattern&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is especially useful when using the tool with eyes closed — the vibration confirms phase transitions without breaking the meditative state.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cycle Locking Safety Mechanism
&lt;/h3&gt;

&lt;p&gt;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 &lt;code&gt;pointer-events: none&lt;/code&gt; and reduced opacity:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;lockCycles&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;enabled&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;btns&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;querySelectorAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;.cycle-btn&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;btns&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;forEach&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;btn&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nx"&gt;btn&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;style&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;pointerEvents&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;enabled&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;none&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;auto&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="nx"&gt;btn&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;style&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;opacity&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;enabled&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;0.35&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;1&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Session Completion UX
&lt;/h3&gt;

&lt;p&gt;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 (&lt;code&gt;clamp(.85rem, 2vw, 1.1rem)&lt;/code&gt;) and appears at 50% opacity — present but not demanding attention. The user can simply close their eyes, breathe naturally, and let the moment settle.&lt;/p&gt;




&lt;h2&gt;
  
  
  Design Philosophy
&lt;/h2&gt;

&lt;p&gt;A few principles that guided the design:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Distraction-free by default.&lt;/strong&gt; 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Privacy-first.&lt;/strong&gt; Zero data leaves your browser. No accounts, no tracking, no analytics on the tool page. Your breathing patterns are yours alone.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. Accessibility matters.&lt;/strong&gt; All color choices passed WCAG AA contrast ratios. The Phosphor icon set replaced emojis to ensure consistent rendering across platforms.&lt;/p&gt;




&lt;h2&gt;
  
  
  Try It Yourself
&lt;/h2&gt;

&lt;p&gt;The tool is free and lives at &lt;strong&gt;&lt;a href="https://toolknit.com/tools/breathing-relaxation.html" rel="noopener noreferrer"&gt;toolknit.com/tools/breathing-relaxation.html&lt;/a&gt;&lt;/strong&gt;. No sign-up, no download — just open it in any browser.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Built with vanilla JavaScript, Canvas API, Web Audio API, and a lot of deep breaths. Questions? Feedback? Reach me at &lt;a href="mailto:2645149786@qq.com"&gt;2645149786@qq.com&lt;/a&gt; or &lt;a href="https://x.com/dngzihng114379" rel="noopener noreferrer"&gt;@dngzihng114379&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

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

</description>
      <category>javascript</category>
      <category>webdev</category>
      <category>tutorial</category>
      <category>mentalhealth</category>
    </item>
    <item>
      <title>I Built 89 Tools in 100 Days. AI Wrote 90% of the Code. I Don't Regret It.</title>
      <dc:creator>Zihang Dong 董子航</dc:creator>
      <pubDate>Sun, 05 Jul 2026 09:39:17 +0000</pubDate>
      <link>https://dev.to/dngzihng114379/i-built-89-tools-in-100-days-ai-wrote-90-of-the-code-i-dont-regret-it-563j</link>
      <guid>https://dev.to/dngzihng114379/i-built-89-tools-in-100-days-ai-wrote-90-of-the-code-i-dont-regret-it-563j</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

&lt;h1&gt;
  
  
  I Built 89 Tools in 100 Days. AI Wrote 90% of the Code. I Don't Regret It.
&lt;/h1&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;I want to offer a counterpoint — not from theory, but from production.&lt;/p&gt;

&lt;p&gt;On March 18, 2026, I launched &lt;a href="https://toolknit.com" rel="noopener noreferrer"&gt;ToolKnit.com&lt;/a&gt; — a privacy-first online toolbox. 109 days later, the site has &lt;strong&gt;89 browser-based tools&lt;/strong&gt;, &lt;strong&gt;87 blog posts&lt;/strong&gt;, a &lt;strong&gt;DR 41 domain rating&lt;/strong&gt;, and thousands of monthly visitors from Google and Bing. Every tool runs 100% client-side. No backend. No database. No signup.&lt;/p&gt;

&lt;p&gt;AI wrote roughly 90% of the code.&lt;/p&gt;

&lt;p&gt;Here's the part the critics don't tell you: &lt;strong&gt;it worked&lt;/strong&gt;. And I think the backlash, while understandable, is fighting the wrong battle.&lt;/p&gt;

&lt;h2&gt;
  
  
  What "90% AI-Generated" Actually Means
&lt;/h2&gt;

&lt;p&gt;Let me be precise, because the numbers matter.&lt;/p&gt;

&lt;p&gt;ToolKnit has 89 tools. Each tool has:&lt;/p&gt;

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

&lt;p&gt;That's roughly &lt;strong&gt;55,000 lines of code&lt;/strong&gt; across the project.&lt;/p&gt;

&lt;p&gt;I hand-wrote exactly &lt;strong&gt;zero&lt;/strong&gt; 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.&lt;/p&gt;

&lt;p&gt;But here's the catch: &lt;strong&gt;I read and understood every line.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The Workflow That Makes AI Actually Work
&lt;/h2&gt;

&lt;p&gt;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:&lt;/p&gt;

&lt;h3&gt;
  
  
  Phase 1: Architecture (Human)
&lt;/h3&gt;

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

&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;
  
  
  Phase 2: Scaffolding (AI)
&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;The AI understood the patterns because I'd already established them. It knew the bilingual setup because &lt;a href="https://toolknit.com/assets/js/bilingual.js" rel="noopener noreferrer"&gt;bilingual.js&lt;/a&gt; was part of the project context. It knew the footer pattern, the tool card pattern, the SEO pattern.&lt;/p&gt;

&lt;h3&gt;
  
  
  Phase 3: Review &amp;amp; Fix (Human)
&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

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

&lt;p&gt;For ToolKnit, the review phase typically took 5-10 minutes per file. I'd scan for:&lt;/p&gt;

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

&lt;h3&gt;
  
  
  Phase 4: Iterate (Human + AI)
&lt;/h3&gt;

&lt;p&gt;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."&lt;/p&gt;

&lt;p&gt;Each fix is another AI prompt. Each prompt takes 30 seconds. Each fix takes 2 minutes to verify.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the Critics Get Right
&lt;/h2&gt;

&lt;p&gt;I want to be fair to the backlash. They're not entirely wrong.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AI code converges on the median.&lt;/strong&gt; 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The comprehension gap is real.&lt;/strong&gt; When I wrote code by hand ten years ago, I built a mental model of every subsystem. With AI, I have to &lt;em&gt;actively&lt;/em&gt; 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Debugging AI-generated code is harder.&lt;/strong&gt; 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the Critics Get Wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;They assume AI replaces thinking.&lt;/strong&gt; 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;They compare AI output to ideal human output.&lt;/strong&gt; 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;They ignore the solo developer economics.&lt;/strong&gt; 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."&lt;/p&gt;

&lt;h2&gt;
  
  
  The Tools That Prove the Point
&lt;/h2&gt;

&lt;p&gt;Some examples from ToolKnit where AI genuinely accelerated shipping:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://toolknit.com/tools/quit-smoking-tracker.html" rel="noopener noreferrer"&gt;Quit Smoking Tracker&lt;/a&gt;&lt;/strong&gt; — 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://toolknit.com/tools/pomodoro-timer.html" rel="noopener noreferrer"&gt;Pomodoro Timer&lt;/a&gt;&lt;/strong&gt; — 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?).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://toolknit.com/tools/pdf-to-image.html" rel="noopener noreferrer"&gt;PDF to Image&lt;/a&gt;&lt;/strong&gt; — 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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  So Should You Use AI to Write Code?
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Use AI aggressively if:&lt;/strong&gt;&lt;/p&gt;

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

&lt;p&gt;&lt;strong&gt;Be skeptical of AI if:&lt;/strong&gt;&lt;/p&gt;

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

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

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Bottom Line
&lt;/h2&gt;

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

&lt;p&gt;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 &lt;strong&gt;understood code&lt;/strong&gt; — code where the developer, AI-assisted or not, knows what every line does and why it's there.&lt;/p&gt;

&lt;p&gt;AI didn't build ToolKnit. I built ToolKnit. AI typed faster than I can. That's it. That's the entire magic trick.&lt;/p&gt;

&lt;p&gt;And I don't regret a single prompt.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;&lt;a href="https://toolknit.com" rel="noopener noreferrer"&gt;ToolKnit.com&lt;/a&gt; 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.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;&lt;strong&gt;What's your experience with AI coding?&lt;/strong&gt; 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.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>webdev</category>
      <category>productivity</category>
      <category>startup</category>
    </item>
  </channel>
</rss>
