<?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: Gavin Liu</title>
    <description>The latest articles on DEV Community by Gavin Liu (@gavin_liu_7aea7ba68cbceb2).</description>
    <link>https://dev.to/gavin_liu_7aea7ba68cbceb2</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%2F3673029%2F6175c72b-9276-4b82-9952-5c726b42770e.png</url>
      <title>DEV Community: Gavin Liu</title>
      <link>https://dev.to/gavin_liu_7aea7ba68cbceb2</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/gavin_liu_7aea7ba68cbceb2"/>
    <language>en</language>
    <item>
      <title>What we learned building a remote MCP server for slow, paid AI jobs</title>
      <dc:creator>Gavin Liu</dc:creator>
      <pubDate>Sat, 14 Nov 2026 20:11:53 +0000</pubDate>
      <link>https://dev.to/gavin_liu_7aea7ba68cbceb2/what-we-learned-building-a-remote-mcp-server-for-slow-paid-ai-jobs-1pm7</link>
      <guid>https://dev.to/gavin_liu_7aea7ba68cbceb2/what-we-learned-building-a-remote-mcp-server-for-slow-paid-ai-jobs-1pm7</guid>
      <description>&lt;p&gt;Most MCP servers answer in milliseconds and cost nothing to call. Ours does neither. The BudgetPixel MCP server lets agents like Claude, ChatGPT, Cursor and Codex make images, video, music and sound effects with a user's own account. A video takes minutes, and generate calls spend the user's credits (failed jobs are free).&lt;/p&gt;

&lt;p&gt;It's a remote server on streamable HTTP with 31 tools behind one OAuth sign-in, written in TypeScript as a thin layer over our existing API. Here's what slow, paid jobs taught us about building one, including a bug we'd rather you didn't repeat.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Disclosure: BudgetPixel is our product. This post was written with help from AI, and we checked every detail against our server's code.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Return a job id, then teach the agent to poll
&lt;/h2&gt;

&lt;p&gt;A generate call can't hold a connection open for three minutes, so every &lt;code&gt;generate_*&lt;/code&gt; tool starts a job and returns its id straight away. A separate &lt;code&gt;check_generation_status&lt;/code&gt; tool collects the result.&lt;/p&gt;

&lt;p&gt;The tool description tells the agent how often to ask: every few seconds for images and sound effects, every 15–30 seconds for video, music and 3D models.&lt;/p&gt;

&lt;p&gt;One sentence in our server instructions saves users more money than anything else:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Each generate or upscale call starts a new paid job: don't repeat a call that already returned a job_id — poll it instead.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Without it, an agent that thinks a call stalled "retries" it, and the user pays twice.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Put the price list where the agent reads it
&lt;/h2&gt;

&lt;p&gt;MCP servers can send &lt;code&gt;instructions&lt;/code&gt; when a session starts, and many clients pass them to the model. Ours hold the costs and the rules for spending:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Default video model seedance-2.5, priced per second by resolution
(480p=150, 720p=330, 1080p=750 credits/s) ... Prefer 480p, and confirm
the cost with the user before 1080p, long clips or more than 5 s.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Prices change, so a &lt;code&gt;list_models&lt;/code&gt; tool returns the live catalog with each model's price and input limits. The instructions say not to assume a fixed list.&lt;/p&gt;

&lt;p&gt;Video also has a draft step. The agent makes a 480p draft at the 480p price, and only if the user likes it does &lt;code&gt;finalize_video_draft&lt;/code&gt; render the same video at 1080p. An idea that doesn't work fails at the cheap stage.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Design results for a chat window
&lt;/h2&gt;

&lt;p&gt;Chat apps differ in what they show, so results carry more than one form:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Finished images come back inline as image content and as a full-resolution link, because some chat apps don't show inline images.&lt;/li&gt;
&lt;li&gt;Video, music and sound effects come back as links, since chat can't embed a player.&lt;/li&gt;
&lt;li&gt;Some outputs are H.265 (HEVC) 10-bit, which some browsers play as a black frame with sound. The file is fine, so the tool result says when a video is H.265 and the agent can tell the user.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Results don't last forever either. Links last about an hour and files about a day, and a &lt;code&gt;save_to_assets&lt;/code&gt; tool keeps a copy in the user's library. The instructions spell that out, so the agent can tell the user to save what they want to keep.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Tool output is a transcript: never put a token in a link
&lt;/h2&gt;

&lt;p&gt;Videos made on our website play through a private path that uses the account's login token. The easy way to show one in chat would be a link with the token in it.&lt;/p&gt;

&lt;p&gt;That link would land in a chat transcript the user doesn't control, and the token opens the whole account for 7 days. So the tool links to the page where the video lives instead. Treat anything you put in a tool result as public.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Make failures something the host can act on
&lt;/h2&gt;

&lt;p&gt;Every tool result goes through one final pass before it leaves the server:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A failed call gets &lt;code&gt;isError: true&lt;/code&gt;. A job that ran and failed is a normal result, though, and is left alone.&lt;/li&gt;
&lt;li&gt;Raw backend errors (&lt;code&gt;API error 403: {...}&lt;/code&gt;) become plain sentences.&lt;/li&gt;
&lt;li&gt;When our API rejects the token, the result carries an OAuth challenge, so the chat app offers to reconnect instead of showing an error the user can't act on:
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;content&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;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Your BudgetPixel sign-in has expired or isn't valid. Reconnect your BudgetPixel account in this app, then try again."&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="n"&gt;structuredContent&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"not_authenticated"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;isError&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="n"&gt;_meta&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="s2"&gt;"mcp/www_authenticate"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="sb"&gt;`Bearer resource_metadata="${publicUrl}/.well-known/oauth-protected-resource", error="invalid_token"`&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="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;When a plan or balance falls short, the result says exactly what's missing and links an informational pricing page, never a checkout page. ChatGPT's app review guidelines ask for this, and it's the right call anyway: an agent shouldn't be a sales funnel.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. The bug: a token captured too early
&lt;/h2&gt;

&lt;p&gt;Our first version read the user's token once, when the MCP session was created, and handed it to the code that calls our API.&lt;/p&gt;

&lt;p&gt;That broke in Claude Code. Claude Code starts the session before the user signs in, and only sends the &lt;code&gt;Authorization&lt;/code&gt; header on later requests. We had frozen an empty token for the whole session, so every API call came back 401.&lt;/p&gt;

&lt;p&gt;The fix is to pass a getter, not a string:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Before: the token as it was when the session started (empty in Claude Code).&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createBudgetPixelServer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// After: read the session's current token on every call.&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createBudgetPixelServer&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="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;token&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;If your server keeps per-session state, check which values can change after the session starts.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. With open client registration, the redirect URI is the safety check
&lt;/h2&gt;

&lt;p&gt;MCP clients register themselves with OAuth dynamic client registration (RFC 7591). Claude, ChatGPT, Cursor and VS Code each show up as a new client. An allowlist or an initial access token would lock them all out, so registration stays open.&lt;/p&gt;

&lt;p&gt;That leaves the redirect URI as the one thing a phisher controls that the user can check. Our connect page names where the sign-in will land. It recognizes known hosts (claude.ai, chatgpt.com, vscode.dev) and app schemes (cursor, vscode, windsurf), and warns when it can't vouch for one.&lt;/p&gt;

&lt;p&gt;We reject very little: only URI shapes no real client uses, such as browser-launcher schemes that would hand the code to a web browser. A stricter rule would leave some real client unable to connect at all. The unauthenticated OAuth endpoints are rate-limited, and the sign-in pages are static markup under a strict content security policy.&lt;/p&gt;

&lt;h2&gt;
  
  
  8. URLs in tool arguments are an SSRF hole
&lt;/h2&gt;

&lt;p&gt;Many tools take image or video URLs as inputs. Our server runs inside a cluster, so a plain &lt;code&gt;fetch()&lt;/code&gt; of a user's URL could reach internal services or the cloud metadata endpoint at 169.254.169.254, and hand back whatever it found.&lt;/p&gt;

&lt;p&gt;Checking the hostname before fetching isn't enough, because DNS can answer differently a moment later (DNS rebinding). So the check runs inside the socket's own DNS lookup, and the address that's checked is the address that's connected to:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;guardedLookup&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;hostname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;callback&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;dns&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;lookup&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;hostname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;all&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="n"&gt;family&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="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;addresses&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="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;callback&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="c1"&gt;// Refuse if ANY address is private or reserved: a mixed record set is how rebinding hides.&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;addresses&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="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;isBlockedAddress&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;address&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="nf"&gt;callback&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;SafeFetchError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"blocked_address"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"that host resolves to a private or reserved address"&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;options&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;all&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="nf"&gt;callback&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="n"&gt;addresses&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;callback&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="n"&gt;addresses&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="n"&gt;address&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;addresses&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="n"&gt;family&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="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;request&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;agent&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="n"&gt;lookup&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;guardedLookup&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;onResponse&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;agent: false&lt;/code&gt; matters: a pooled keep-alive socket would skip the lookup, and with it the check. Each redirect hop goes through the same check, and the body streams against a byte cap under one deadline, so a huge or endless response can't pin the server's memory.&lt;/p&gt;

&lt;h2&gt;
  
  
  Annotate every tool
&lt;/h2&gt;

&lt;p&gt;All 31 tools carry a &lt;code&gt;title&lt;/code&gt; and the &lt;code&gt;readOnlyHint&lt;/code&gt;, &lt;code&gt;destructiveHint&lt;/code&gt; and &lt;code&gt;openWorldHint&lt;/code&gt; annotations, so hosts know which calls only read and which change something. &lt;code&gt;check_generation_status&lt;/code&gt; is read-only. &lt;code&gt;create_social_post&lt;/code&gt; publishes to the user's public feed, so the instructions allow it only when the user explicitly asks, with an hourly cap and a "via MCP" label on every post.&lt;/p&gt;

&lt;h2&gt;
  
  
  The short version
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Return job ids fast, teach polling, and never let a paid call run twice.&lt;/li&gt;
&lt;li&gt;Put prices and confirmation rules in the server instructions.&lt;/li&gt;
&lt;li&gt;Send images inline and as links, and say when a file might not play.&lt;/li&gt;
&lt;li&gt;Treat tool output as public: no tokens in links.&lt;/li&gt;
&lt;li&gt;Shape errors so the host can act on them.&lt;/li&gt;
&lt;li&gt;Read auth on every call, not once per session.&lt;/li&gt;
&lt;li&gt;With open client registration, make the redirect URI visible and checkable.&lt;/li&gt;
&lt;li&gt;Guard every URL fetch at the socket's DNS lookup.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If you want to see how it behaves from the agent's side, setup for each client is at &lt;a href="https://budgetpixel.com/mcp" rel="noopener noreferrer"&gt;budgetpixel.com/mcp&lt;/a&gt;. We'd like to hear how others handle long-running, paid tools in MCP.&lt;/p&gt;

</description>
      <category>mcp</category>
      <category>ai</category>
      <category>typescript</category>
      <category>security</category>
    </item>
    <item>
      <title>Making a typing game fair from 20 to 150 WPM</title>
      <dc:creator>Gavin Liu</dc:creator>
      <pubDate>Sat, 14 Nov 2026 19:41:52 +0000</pubDate>
      <link>https://dev.to/gavin_liu_7aea7ba68cbceb2/making-a-typing-game-fair-from-20-to-150-wpm-57f1</link>
      <guid>https://dev.to/gavin_liu_7aea7ba68cbceb2/making-a-typing-game-fair-from-20-to-150-wpm-57f1</guid>
      <description>&lt;p&gt;Many typing games set the speed for you. Words fall at a fixed rate, so someone learning at 20 WPM gets buried and someone at 150 WPM gets bored. We wanted one arcade game that's the same challenge for both, where the only way to do better is to type better.&lt;/p&gt;

&lt;p&gt;Getting there took four things: a pace taken from the player's own history, measuring everything in characters, a test that plays the game at different speeds, and a renderer light enough for an old laptop. Here's each one, including the bug that taught us the second.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Disclosure: the game is Outpace, on TypingPractice.ai, which is our site. This post was written with help from AI, and we checked every number against our code and test output.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The game in one paragraph
&lt;/h2&gt;

&lt;p&gt;You type a line of text, and every right key moves a comet one character on. Night follows through the same text at a set pace. A wrong key doesn't move you: the caret waits for the right one. If the night reaches you, you lose one of three lights and it falls back a little. A run is ten "skies", each a bit faster than the last, and it ends when your lights are gone or you clear sky 10.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. The pace comes from your own history
&lt;/h2&gt;

&lt;p&gt;The night's speed is a share of your usual speed: the median WPM of your last 10 rounds. Lessons and key drills are left out, because a few letters typed over and over aren't a fair measure of speed. The median means one distracted round doesn't swing it.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Sky 1 is 80% of your usual speed; each sky after adds 6%.&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;nightPace&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sky&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&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.8&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mf"&gt;0.06&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sky&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="c1"&gt;// sky 1: 0.80, sky 5: 1.04, sky 10: 1.34&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;So the first skies are a little slower than you usually type, sky 5 is about level with it, and sky 10 needs 34% more. A new player with no rounds yet types a 45-character warm-up first, which sets a starting number.&lt;/p&gt;

&lt;p&gt;It also means the game gets harder as you get faster. You can't grind it: the only way further is to type better than you usually do.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Measure the world in characters
&lt;/h2&gt;

&lt;p&gt;Positions in Outpace are characters of the text, spaces included, the same unit WPM is built on (a "word" is five keystrokes). The comet is how far you've typed correctly, and the night is how far it has reached.&lt;/p&gt;

&lt;p&gt;The screen shows the gap between them in seconds at the night's pace. So the picture looks the same at every speed: the comet sits in a fixed spot, and the night is your lead in seconds behind it.&lt;/p&gt;

&lt;p&gt;Each sky is 18 seconds of text at its night's pace. For a 20 WPM typist, sky 1 is 24 characters; at 150 WPM it's 180. A run lasts about three minutes at most, at any speed.&lt;/p&gt;

&lt;p&gt;The lead has limits too. You start 4 seconds ahead, each sky's gate pushes the night back half a second, and the lead is capped at 5 seconds. You can't bank time in an easy sky and coast through a hard one.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. The bug: penalties in seconds
&lt;/h2&gt;

&lt;p&gt;Our first version charged a slip in seconds of lead. That sounds neutral, but it isn't. At the same accuracy, a fast typist makes more slips per second, because they press more keys per second. At 96% accuracy, a 120 WPM typist makes about 0.4 slips a second and a 40 WPM typist about 0.13. Same accuracy, three times the penalty.&lt;/p&gt;

&lt;p&gt;The fix was to charge in characters:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Before: a cost in seconds of lead, the same for everyone.&lt;/span&gt;
&lt;span class="n"&gt;night&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="no"&gt;SLIP_COST_SECONDS&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="n"&gt;nightCharsPerSecond&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// After: a slip lets the night move 2 characters closer...&lt;/span&gt;
&lt;span class="n"&gt;night&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="c1"&gt;// ...and a clean word with this sky's focus key or letter pair pushes it back 1.&lt;/span&gt;
&lt;span class="n"&gt;night&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;Now a slip costs the same share of your pace at any speed. We simulated the current rules with the slip cost swapped back to half a second. The simulated typist types at exactly their usual speed and slips every 50th key (98% accuracy) or every 25th (96%). Skies cleared, out of 10:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Accuracy&lt;/th&gt;
&lt;th&gt;Slip costs&lt;/th&gt;
&lt;th&gt;20 WPM&lt;/th&gt;
&lt;th&gt;40&lt;/th&gt;
&lt;th&gt;60&lt;/th&gt;
&lt;th&gt;120&lt;/th&gt;
&lt;th&gt;150&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;98%&lt;/td&gt;
&lt;td&gt;0.5 seconds&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;98%&lt;/td&gt;
&lt;td&gt;2 characters&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;96%&lt;/td&gt;
&lt;td&gt;0.5 seconds&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;96%&lt;/td&gt;
&lt;td&gt;2 characters&lt;/td&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;With a cost in time, the fastest typist got half as far as the slowest for the same accuracy. In characters, everyone ends within a sky of each other.&lt;/p&gt;

&lt;p&gt;The reward follows the same rule. The clean-word bonus is in characters too, and the focus comes from the player's profile: one of their weak keys or slow letter pairs, taking turns from sky to sky. Words that contain it glow, so the bonus lands where practice helps most.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Make fairness a test
&lt;/h2&gt;

&lt;p&gt;That table comes from a small harness in our unit tests. The game's rules are plain functions with no DOM: &lt;code&gt;right()&lt;/code&gt;, &lt;code&gt;slip()&lt;/code&gt;, &lt;code&gt;wordDone()&lt;/code&gt; and &lt;code&gt;tick()&lt;/code&gt;. A scripted typist calls them with a fake clock: keys at an even rhythm, a slip every Nth key, a frame every 16 ms. A whole run takes milliseconds, so we can play hundreds.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nf"&gt;it&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'is the same run at 20 and at 150 wpm, for the same pace and accuracy'&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="o"&gt;=&amp;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="n"&gt;pace&lt;/span&gt; &lt;span class="k"&gt;of&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="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mf"&gt;1.15&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;const&lt;/span&gt; &lt;span class="n"&gt;slipEvery&lt;/span&gt; &lt;span class="k"&gt;of&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;50&lt;/span&gt;&lt;span class="p"&gt;,&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="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;slow&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;play&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;pace&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;slipEvery&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;fast&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;play&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;150&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;pace&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;slipEvery&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nf"&gt;expect&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;abs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;slow&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cleared&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;fast&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cleared&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;toBeLessThanOrEqual&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="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="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Next to it are tests that typing 12% faster than usual clears more skies, a slip every 15 keys clears fewer, typing 40% faster clears all ten, and a run lasts about three minutes at most. If someone tunes a number later and breaks fairness, a test fails.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Don't let the clock cheat
&lt;/h2&gt;

&lt;p&gt;A timing game has more clocks than you'd think, and each one can be unfair:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Long frames.&lt;/strong&gt; A frame longer than 250 ms (a stall, a background tab) moves the night at most 250 ms.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Leaving.&lt;/strong&gt; The night pauses when the tab is hidden or the window loses focus, and on Esc.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pauses.&lt;/strong&gt; Paused time is taken off the round's clock, so it doesn't lower your WPM.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Getting caught.&lt;/strong&gt; If the night catches you while you've stopped typing, the round ends at your last key. The seconds you sat there aren't typing, so they don't count.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  6. Light enough for an old laptop
&lt;/h2&gt;

&lt;p&gt;We wanted Outpace to run on school Chromebooks and old laptops, so it uses no game engine. The sky is a plain 2D canvas:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Glows (the comet, its trail, sparks, stars) are small sprites drawn once at start and stamped with &lt;code&gt;drawImage&lt;/code&gt;. There's no &lt;code&gt;shadowBlur&lt;/code&gt; and no filters, which are what usually make a canvas slow.&lt;/li&gt;
&lt;li&gt;The sky gradient is cached until the sky changes. Each frame is a few fills: three hill outlines, the night, a gate ring and a fixed pool of particles.&lt;/li&gt;
&lt;li&gt;The canvas is opaque (&lt;code&gt;{ alpha: false }&lt;/code&gt;), its pixel ratio is capped at 2, and on big screens it's capped lower (about 2.4 million pixels in all).&lt;/li&gt;
&lt;li&gt;If frames run slow during a run, quality steps down: fewer particles first, then no aurora and 30 frames a second. It never steps back up mid-run.&lt;/li&gt;
&lt;li&gt;When nothing moves (before a run, paused, after it), it paints 15 frames a second. When the tab is hidden or the game is scrolled off-screen, the loop stops.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Typing runs outside React. The line is a row of spans in a monospace font, and each word's left edge is measured once, when it's added. A letter's position is that edge plus its index times the letter width, so nothing reads layout while you type. The caret and the line move with CSS transforms.&lt;/p&gt;

&lt;p&gt;In headless Chrome on a Mac, a run used about 5% of one CPU core on the main thread, at 60 frames a second. With Chrome's CPU throttled 4x, it used about 18% and still held 60, without stepping quality down. (That's main-thread time; GPU work isn't in it.)&lt;/p&gt;

&lt;p&gt;One bug is worth passing on. We measured the line while it was hidden with &lt;code&gt;display: none&lt;/code&gt;. Every width came back 0, and after a restart the words sat off-screen. Now a &lt;code&gt;ResizeObserver&lt;/code&gt; measures again when the line is shown, and measuring is skipped while it has no width.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Don't move words people are about to read
&lt;/h2&gt;

&lt;p&gt;Our second game, Word garden, turns the words you miss or slow down on into plants. A clean word, typed no more than 10% slower than your usual pace, grows a stage. A plant grows at most two stages a day and blooms at four, so every word takes at least two days. That spacing is on purpose: short sessions, no grind. The plants are SVG, picked from a hash of the word so "which" always grows the same flower. All motion is CSS keyframes, so there's no animation loop at all.&lt;/p&gt;

&lt;p&gt;Its first version showed the current word large in the middle and the next two small beside it. Every new word changed size and place as it came up. In testing, that was distracting and hard to read ahead, and the timings agreed: one clean word took 329 ms a key, against a usual 161.&lt;/p&gt;

&lt;p&gt;Typists read a word or two ahead, and moving words breaks that. Word garden now types on the same steady line as Outpace, with every word the same size. A word that needs another try joins the end of the line, so the words ahead never change. Our browser test now checks both: the line ahead never changes, and every word on it is the same size.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we'd tell anyone building a typing game
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Set the pace from the player's own history (a median), not a fixed speed.&lt;/li&gt;
&lt;li&gt;Count costs and rewards in characters, not seconds.&lt;/li&gt;
&lt;li&gt;Put fairness in a test: play your real rules at 20 and at 150 WPM.&lt;/li&gt;
&lt;li&gt;Never move or resize words someone is about to read.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;You can try Outpace and Word garden at &lt;a href="https://typingpractice.ai/typing-games" rel="noopener noreferrer"&gt;typingpractice.ai/typing-games&lt;/a&gt;. They're free and don't need an account. If you've built typing tools, we'd like to hear how you handle pace.&lt;/p&gt;

</description>
      <category>gamedev</category>
      <category>javascript</category>
      <category>webdev</category>
      <category>performance</category>
    </item>
  </channel>
</rss>
