<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Mahshid Hajyani on Medium]]></title>
        <description><![CDATA[Stories by Mahshid Hajyani on Medium]]></description>
        <link>https://medium.com/@mahshid-hajyani?source=rss-8c3cc9a2b07c------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*KvkP1aHDeZwDa6m-mypbkg.jpeg</url>
            <title>Stories by Mahshid Hajyani on Medium</title>
            <link>https://medium.com/@mahshid-hajyani?source=rss-8c3cc9a2b07c------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 21:01:11 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@mahshid-hajyani/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[A Practical Journey into MCP and AI Skills]]></title>
            <link>https://mahshid-hajyani.medium.com/a-practical-journey-into-mcp-and-ai-skills-797e0fdbb55b?source=rss-8c3cc9a2b07c------2</link>
            <guid isPermaLink="false">https://medium.com/p/797e0fdbb55b</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[developer-tools]]></category>
            <category><![CDATA[mcp-server]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Mahshid Hajyani]]></dc:creator>
            <pubDate>Sun, 08 Nov 2026 15:42:04 GMT</pubDate>
            <atom:updated>2026-11-08T15:42:04.071Z</atom:updated>
            <content:encoded><![CDATA[<p><em>What I learned from turning a small TypeScript project into a tool for Codex and Claude Code.</em></p><p>I started this project because I wanted to understand how the Model Context Protocol (MCP) and skills actually work together.</p><figure><img alt="Git changes connected through modular tools to three validated commit-message suggestions" src="https://cdn-images-1.medium.com/max/1024/1*7UDNABl8D3Lk9BDbM9Zu6w.png" /></figure><p>I had some basic questions: how does an AI coding assistant, such as Codex or Claude Code, call my code? What belongs in a skill? And if the assistant can already run commands, what does an MCP server add?</p><p>To explore those questions, I built <a href="https://github.com/mahshid/ai-commit-helper">AI Commit Helper</a>. I chose commit messages because they were familiar, and I could compare the suggestions with my actual changes. The tool reads staged Git changes and helps Codex or Claude Code suggest three commit messages that follow the repository’s rules. You choose the message and make the commit yourself.</p><p>The idea sounds straightforward. Working out how the pieces should fit together was the interesting part.</p><h3>Starting with a function I could understand</h3><p>My first step was a TypeScript function that runs:</p><pre>git diff --staged</pre><p>I used Node’s execFile, wrapped with promisify so I could use await. The important part looked like this:</p><pre>const { stdout } = await execFileAsync(<br>  &quot;git&quot;,<br>  [&quot;diff&quot;, &quot;--staged&quot;],<br>  { cwd: repositoryPath, encoding: &quot;utf8&quot; }<br>);</pre><p>The cwd option tells Git which repository to inspect. That matters because the helper can be installed in one directory and used on a project somewhere else.</p><p>This gave me something I could test before involving the assistant. If the function returned the wrong diff, I knew where to look.</p><p>I would use that approach again: make the underlying operation work as ordinary code first. Adding the MCP interface becomes easier when you already understand what the function does.</p><h3>Understanding what the skill and server each do</h3><p>At first, I wasn’t sure where to put the instructions. Should the server tell the assistant how to write a message? Was that the skill’s job? Why have both?</p><p>In this project, the MCP server makes specific operations available as tools. The skill describes how the assistant should use them to complete the task.</p><p>For example, a tool returns the staged changes and commit rules. The skill tells the assistant to read that context, generate three candidates, validate them, and present the results.</p><p>Codex or Claude Code generates the wording. My server doesn’t call a separate AI API, so there is no additional API key to configure for it.</p><p>That division helped me make decisions. Reading a file belongs in the tool’s implementation. Asking for a missing ticket number belongs in the workflow instructions.</p><p>I also realised that this project didn’t need MCP just to run Git. An assistant could already do that. The more useful part came when I added repository-specific rules and validation.</p><h3>Making the helper useful beyond my own preferences</h3><p>A generic commit suggestion might look fine but still be wrong for a team’s workflow.</p><p>One repository might use feat(auth): add password reset. Another might require #234 Add password reset. I wanted the helper to work with either, so I added a .commit-helper.json file:</p><pre>{<br>  &quot;format&quot;: &quot;ticket&quot;,<br>  &quot;maxSubjectLength&quot;: 100<br>}</pre><p>The server now provides three tools:</p><ul><li><strong>get_commit_context</strong>‌: Read the staged diff and effective rules</li><li><strong>validate_commit_message</strong>: Check a candidate’s format and length</li><li><strong>create_commit_rules</strong>: Save configuration without overwriting an existing file</li></ul><p>This gave the server a clearer role. It could provide consistent checks that the assistant could reuse.</p><p>The skill instructs the assistant to validate each candidate before showing it. If validation fails, the returned errors guide a revision, with a limit on correction attempts.</p><p><strong>Generating a suggestion and checking it became separate steps.</strong> I would reuse that pattern anywhere an AI-generated answer has requirements that code can verify.</p><p>Of course, a valid format doesn’t guarantee an accurate summary. The developer still needs to compare the message with the changes.</p><h3>The small mistakes taught me the most</h3><p>During early testing, the helper returned three suggestions even though nothing was staged.</p><p>It had followed the “three messages” part of the task, but there was no change to describe. I made that state explicit: the context tool returns a no_changes status, and the skill instructs the assistant to stop.</p><p>That pushed me to think about the other unsuccessful cases too. What happens when Git fails? When a ticket number is missing? When the configuration contains invalid JSON?</p><p>Configuration also gave me a practical reason to use <strong>Zod</strong>. A TypeScript type describes the values my code expects, but it can’t guarantee what someone puts in a JSON file. I needed to validate those values at runtime.</p><p>I kept missing configuration and invalid configuration separate. A missing file can lead to defaults; a broken file should produce an error so the user can fix it.</p><p>For testing, I focused on predictable behaviour: valid prefixes, messages at the length limit, oversized messages, and unwanted line breaks. These checks were easier to test precisely than the wording of an AI-generated sentence.</p><h3><strong>Putting the Pieces Together</strong></h3><p>Packaging the project helped me understand how the pieces connect. The TypeScript code lives in src/, while the skills live inside plugins/ai-commit-helper/skills/. The plugin configuration connects the host to the MCP server, and the marketplace catalog tells it where to find the plugin for installation. Codex and Claude Code use separate catalogs, but share the same server and skills.</p><p>One detail that caught my attention was that installing the plugin doesn’t automatically build the TypeScript server. That made me realise the setup instructions were part of the project too. I’ve kept the installation steps in the README.</p><h3>What I’d do again</h3><p>If you’re building something similar, my advice is to choose one task you already understand. Start with its core function, expose it as a tool, then write the workflow around it. Include empty inputs and failures from the beginning.</p><p>I wanted to understand MCP and skills by following one complete request: from a command in the assistant, through my TypeScript code, and back to a useful result. This project gave me that experience without becoming too large to follow.</p><p>You can find the <a href="https://github.com/mahshid/ai-commit-helper">code and setup instructions on GitHub</a>. If you build something similar, I’d be interested to hear which task you choose and what turns out to be less obvious than you expected.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=797e0fdbb55b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building TabSift: The Small Browser Extension That Taught Me a Lot]]></title>
            <link>https://mahshid-hajyani.medium.com/building-tabsift-the-small-browser-extension-that-taught-me-a-lot-37af7d19ada5?source=rss-8c3cc9a2b07c------2</link>
            <guid isPermaLink="false">https://medium.com/p/37af7d19ada5</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[wxt]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[browser-extension]]></category>
            <category><![CDATA[typescript]]></category>
            <dc:creator><![CDATA[Mahshid Hajyani]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 18:21:38 GMT</pubDate>
            <atom:updated>2026-10-30T16:58:35.326Z</atom:updated>
            <content:encoded><![CDATA[<p>I wanted a TypeScript project that was small enough to finish, but real enough to teach me something beyond another tutorial app.</p><p>A browser extension felt like a good fit.</p><p>That’s how <a href="https://chromewebstore.google.com/detail/tabsift/jkhicjbejfpnpohgjfkeepcoadjkoelc"><strong>TabSift</strong></a> started: a small extension that finds tabs you haven’t used in a while and lets you decide which ones to close.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jJ4J4FMz_DBaUVqPiXMLOg.png" /></figure><p>The idea itself is simple. The interesting part was everything I had to think about while building it.</p><h3>Why WXT?</h3><p>My first question was how to structure the project.</p><p>I could have started with Vite and configured the extension setup myself, but browser extensions come with a few extra concerns: manifests, background scripts, permissions, different browser targets, and packaging.</p><p>I ended up choosing <a href="https://wxt.dev/"><strong>WXT</strong></a>.</p><p>What I liked about it was that it handled the extension-specific setup without hiding everything from me. It still uses Vite underneath, but gave me a structure that made sense for a browser extension from the start.</p><p>That meant I could spend more time thinking about the actual extension instead of build configuration.</p><p>For this project, that trade-off was worth it.</p><h3>I Kept the UI Simple on Purpose</h3><p>I also decided not to use React.</p><p>TabSift has a small popup, a settings panel, and a few interactive states. Adding a UI framework would have worked, but I didn’t really need one.</p><p>Using vanilla TypeScript made me work directly with DOM events, state updates, and browser APIs.</p><p>It also pushed me to separate the UI from the actual tab-management logic.</p><p>That turned out to be useful later when I started writing tests.</p><h3>The Hard Part Wasn’t Finding Old Tabs</h3><p>The browser already gives you useful tab information, including when a tab was last accessed.</p><p>So technically, finding an old tab is just comparing timestamps.</p><p>But an old tab isn’t automatically a useless tab.</p><p>A pinned tab might be important. A tab playing audio probably shouldn’t suddenly appear in a cleanup list. And the currently active tab definitely shouldn’t.</p><p>So I ended up defining a “forgotten” tab more carefully.</p><p>TabSift ignores tabs that are:</p><ul><li>active</li><li>pinned</li><li>playing audio</li></ul><p>Users can also choose how long a tab should be inactive before it appears in the list.</p><p>That small decision changed the extension from “close old tabs” into “show me tabs I might want to clean up.”</p><h3>Why TabSift Doesn’t Close Tabs Automatically</h3><p>I considered automatic cleanup.</p><p>It sounds convenient: if a tab hasn’t been used for a while, just close it.</p><p>But I didn’t like the idea.</p><p>Inactivity doesn’t necessarily mean a tab is unimportant. Maybe it’s documentation you want to come back to. Maybe it’s something you’re keeping open for tomorrow.</p><p>So TabSift only suggests tabs.</p><p>You select what you want to close, review the selection, and confirm it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*avvuffVCYyMOTqcsRCJfvQ.png" /></figure><p>I also added one more safety step: before closing anything, the extension checks those tabs again.</p><p>Why?</p><p>Because browser state can change while you’re using the popup.</p><p>A tab that looked inactive a few seconds ago might now be active.</p><p>That was one of the first moments in the project where a simple feature made me think more seriously about asynchronous state.</p><h3>The Badge Was More Interesting Than I Expected</h3><p>I wanted the extension icon to show how many forgotten tabs were currently open.</p><p>At first, I thought I’d just update the badge whenever a tab changed.</p><p>Then I noticed a problem.</p><p>A tab can become forgotten without any browser event happening.</p><p>Time passes.</p><p>That’s it.</p><p>So tab events weren’t enough.</p><p>I ended up combining browser events with a periodic alarm so the badge could refresh even when nothing else changed.</p><p>Then another issue appeared: several events could trigger badge updates very close together.</p><p>Instead of letting multiple async updates run at the same time, I added a small refresh queue so badge updates happen in a controlled order.</p><p>For such a small feature, it turned into a surprisingly useful exercise in async programming.</p><h3>Chrome Worked. Firefox Had Other Ideas.</h3><p>Once the Chrome version was working, I tried Firefox.</p><p>This is where I was reminded that “cross-browser” doesn’t mean “identical everywhere.”</p><p>My badge code used:</p><p>browser.action</p><p>In my first Firefox build, that was undefined.</p><p>The reason was the manifest version.</p><p>WXT was building Firefox with Manifest V2 by default, where the equivalent API is browser.browserAction.</p><p>Instead of maintaining separate badge code, I chose to build the Firefox version with Manifest V3 as well.</p><p>That kept the extension architecture more consistent across both browsers.</p><p>There were still Firefox-specific details to handle, especially around the manifest and add-on submission, but using WXT made the overall process much easier.</p><h3>I Also Removed a Feature I Had Already Built</h3><p>An earlier version of the project had a floating character on web pages.</p><p>It reacted to the number of open tabs.</p><p>It was fun.</p><p>It also became completely unnecessary.</p><p>As TabSift moved toward being a practical tab manager, the floating character started feeling more like decoration than functionality.</p><p>So I removed it.</p><p>That was probably one of the more useful lessons from the project.</p><p>Just because something was interesting to build doesn’t mean it deserves to stay.</p><h3>What I Learned</h3><p>TabSift started as TypeScript practice, but it ended up touching a lot of areas I wanted to understand better:</p><ul><li>Browser extension architecture</li><li>Browser APIs</li><li>Async state and race conditions</li><li>Cross-browser differences</li><li>Testing logic separately from the UI</li><li>Permissions and extension-store requirements</li><li>Knowing when to remove a feature</li></ul><p>The biggest thing I took away from it was that even small projects have real design decisions.</p><p>Choosing a framework, deciding what not to automate, handling changing browser state, or removing a feature can matter more than adding another library.</p><p>TabSift is now available on both the Chrome Web Store and Firefox Add-ons!</p><p>If you want to give it a try or explore the code:</p><ul><li><strong>Chrome Web Store:</strong> <a href="https://chromewebstore.google.com/detail/tabsift/jkhicjbejfpnpohgjfkeepcoadjkoelc">Install TabSift</a></li><li><strong>Firefox Add-ons:</strong> <a href="https://addons.mozilla.org/en-GB/firefox/addon/tabsift/">Install TabSift</a></li><li><strong>GitHub:</strong> <a href="https://github.com/mahshid/tabsift">View the source code</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=37af7d19ada5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building Mood Pixels: What I Learned from Trying JEV AI]]></title>
            <link>https://mahshid-hajyani.medium.com/building-mood-pixels-what-i-learned-from-trying-jev-ai-a3e55ee40653?source=rss-8c3cc9a2b07c------2</link>
            <guid isPermaLink="false">https://medium.com/p/a3e55ee40653</guid>
            <category><![CDATA[typesafe-ai]]></category>
            <category><![CDATA[mood-tracker-app]]></category>
            <category><![CDATA[nextjs]]></category>
            <category><![CDATA[tailwind-css]]></category>
            <category><![CDATA[jevai]]></category>
            <dc:creator><![CDATA[Mahshid Hajyani]]></dc:creator>
            <pubDate>Mon, 05 Oct 2026 13:18:43 GMT</pubDate>
            <atom:updated>2026-11-17T16:02:16.292Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong>Update - November 2026:</strong> This article covers the first version of Mood Pixels. Since then, I’ve released v0.2.0 with Google sign-in, PostgreSQL storage, and an updated interface. <a href="https://github.com/mahshid/mood-pixels/releases/tag/v0.2.0">See what’s new →</a></blockquote><p>I’d been curious about JEV AI for a while, and I was also spending more time learning Next.js and TypeScript. Eventually, I needed to give myself something to build.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MxaQJ91Bw5yfZc4F3W3Rag.png" /></figure><p>So I combined the two in <strong>Mood Pixels</strong>: a small app that turns a daily journal entry into a coloured square in a yearly calendar.</p><p>The plan sounded straightforward. Write about your day, let AI suggest a mood and energy level, and watch the calendar fill up. Getting it working was satisfying. Testing the results was where things got interesting.</p><h3>The idea: your year, one pixel at a time</h3><p>Mood Pixels is inspired by “Year in Pixels” journals, where each day gets a colour representing how you felt.</p><p>You write a short entry, and JEV AI suggests one of five moods: 🟢 <strong>Sparkly</strong>, <strong>🟡 Cozy</strong>, <strong>🔵 Tired</strong>, <strong>🟣 Sad</strong>, or <strong>🔴 Frustrated</strong>. It also provides an energy level.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/621/1*97Tgevn9jzVSLn-VXaDqEQ.png" /></figure><p>Each check-in adds another colour to the calendar. Simple, but surprisingly satisfying to watch.</p><h3>Getting connected was the easy part</h3><p>I expected integrating AI to take more setup than it did. Using JEV through the TypeSafe SDK was fairly smooth, and I could start connecting the results to the interface.</p><pre>import { choice, noul, TypeSafeClient } from &quot;@typesafe-ai/sdk&quot;;<br><br>if (! process.env.TYPESAFE_API_KEY) {<br>    throw new Error(<br>        &quot;TYPESAFE_API_KEY is not defined in the environment variables.&quot;,<br>    );<br>}<br><br>const client = new TypeSafeClient();</pre><p>That first complete flow felt good: submit an entry, get a result, save it, and see the calendar update.</p><p>It also gave my Next.js and TypeScript practice a purpose. I had to make the input, server-side logic, saved data, and calendar work together.</p><p>Then I started looking more closely at what the AI was returning.</p><h3>Sparkly mood. Almost no energy.</h3><p>Initially, I used choice for the mood and score for an energy rating from 1 to 5.</p><p>During testing, I sometimes got a “Sparkly” mood alongside a very low energy score. Apparently, my app thought I was having a wonderful day and needed an immediate nap.</p><p>That combination is possible! But some results didn’t fit the entry I was testing.</p><p>Mood and energy came from two separate AI calls, each interpreting the text independently. Placing their answers next to each other made those differences much easier to notice.</p><p><strong>The change:</strong> I kept the energy feature and used the result of the same choice call to determine the energy level as well.</p><p><strong>The lesson:</strong> test related AI outputs together. Two successful calls don’t automatically add up to a useful result. You still need to look at what the person using the app actually sees.</p><h3>The Next Steps for Mood Pixels</h3><p>This is <strong>version 1</strong>, so the scope is still small. The calendar is fixed to 2026 and shows each logged day’s colour, but there’s no history or editing screen yet.</p><p>Results are stored in the browser. Clearing the site’s browser storage removes them. So an important limitation for something intended to hold daily check-ins.</p><p>Next, I plan to support more years and move storage to a database. That gives me another practical area to explore as the project develops.</p><h3>What I learned</h3><p>Mood Pixels helped me explore JEV AI while practising Next.js and TypeScript. The biggest lessons came from testing real entries and figuring out why the results didn’t always match my expectations.</p><p>A small app, but plenty to learn from.</p><p>You can find the source code and a link to try Mood Pixels on <a href="https://github.com/mahshid/mood-pixels">GitHub</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a3e55ee40653" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Beyond the Tutorials: 4 Hidden Traps of Deploying AMP Emails]]></title>
            <link>https://mahshid-hajyani.medium.com/beyond-the-tutorials-4-hidden-traps-of-deploying-amp-emails-1f344bf0b372?source=rss-8c3cc9a2b07c------2</link>
            <guid isPermaLink="false">https://medium.com/p/1f344bf0b372</guid>
            <category><![CDATA[amp-for-email]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[email-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[amp]]></category>
            <dc:creator><![CDATA[Mahshid Hajyani]]></dc:creator>
            <pubDate>Mon, 11 May 2026 16:51:45 GMT</pubDate>
            <atom:updated>2026-05-13T10:21:17.204Z</atom:updated>
            <content:encoded><![CDATA[<p>Let’s be honest: we all want user feedback on our newsletters, product recommendations, or invites. But users are busy. If you ask them to click a link, wait for a browser tab to load, and fill out a form just to say, “I don’t like this item,” you’ve already lost 90% of them.</p><p>I wanted to remove that friction completely, so I turned to <a href="https://amp.dev/about/email"><strong>AMP for Email</strong></a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WKK_UfHS-MPjYbgEXTYi3w.jpeg" /></figure><p>AMP lets you put fully interactive forms <strong>directly</strong> inside the email. A user clicks a button, the email fires a background request to my API, and the user instantly sees a “Success!” message without ever leaving their inbox.</p><p>There are plenty of tutorials out there showing you how to write a basic tag, so I’m not going to bore you with boilerplate code here. Instead, I want to talk about what happens after you follow those tutorials.</p><p>Because while the basic HTML is straightforward, getting it to actually work in production came with a few wild surprises. Here are the hidden traps those tutorials don’t mention, and how I solved them so you don’t have to waste hours debugging like I did!</p><h3>Trap #1: The Strict AMP Diet</h3><p>When you first discover AMP, you want to use every feature: carousels, dynamic lists, accordions, and so on. But there’s a catch: <strong>email clients are super strict about file sizes.</strong> Gmail will clip standard emails over 102KB, and AMP has its own strict validation limits.</p><p>Because you have to include mandatory AMP &lt;script&gt; tags in the &lt;head&gt;, a good chunk of your size limit is gone before you even write your actual content.</p><p>Here are the three best ways I found to put my AMP code on a diet:</p><ul><li><strong>Drop the Tables for Divs:</strong> If you’ve ever coded a standard HTML email, you know the absolute nightmare of nesting &lt;table&gt; tags inside other &lt;table&gt; tags just to make a layout work for ancient versions of Outlook. All that extra HTML adds a massive amount of weight. The good news? Any email client modern enough to support AMP (like Gmail and Yahoo) is also modern enough to perfectly render &lt;div&gt; tags and standard CSS. By stripping out the ancient table-based layouts and using clean &lt;div&gt;s for your AMP version, you&#39;ll slash your file size in half.</li><li><strong>Swap Images for Emojis:</strong> I skipped bulky &lt;amp-img&gt; tags and heavy SVGs, and just used standard Unicode emojis (like 📍 and 💰). They cost literally zero bytes, load instantly, and you never get that ugly &quot;broken image&quot; icon.</li><li><strong>Offload Heavy Data with </strong><strong>&lt;amp-list&gt;:</strong> Instead of hardcoding long product lists, I used &lt;amp-list&gt; to fetch my JSON dynamically when the email opens. It&#39;s a huge space saver! <strong>But here is the catch:</strong> AMP forces you to define the container height upfront. I had to write backend logic to dynamically calculate the exact pixel height for each user based on how many items they received. If you guess wrong, your list just awkwardly chops off halfway through.</li></ul><h3>Trap #2: The Playground Illusion</h3><p>AMP is a perfectionist. If you have a single rogue space or an unsupported CSS rule, the entire email breaks silently in the inbox, and Gmail just shows your boring fallback HTML instead.</p><p>To avoid this, I used the official <strong>AMP Email Playground</strong> to validate my code. It gave me a green light, everything looked perfect, but when I sent the test email to myself… it completely failed.</p><p>Why? Because of <strong>character encoding</strong>. During the actual email transmission, my backend mailer accidentally converted one of my beautiful emojis into a corrupted string (like ð¼). The AMP Playground couldn&#39;t warn me about this because it only tests your code in a browser, not the actual email delivery process.</p><p>Another example is popup which you can find more details in trap #4 section.</p><p><strong>The lesson:</strong> The Playground is great for checking your UI, but to test real-world delivery, you have to send real test emails!</p><h3>Trap #3: The Local Testing Maze</h3><p>Okay, so the Playground is an illusion. You need to test your full API flow locally. But wait, how does the Gmail app on your phone talk to your localhost API? Spoiler: it can&#39;t.</p><p>Here is the ultimate setup that saved my sanity:</p><ul><li><strong>Step 1: Send the email easily.</strong> Don’t bother setting up a local SMTP server. Just use your personal Gmail! Generate an <strong>App Password</strong> in your Google account settings, drop it into your local .env file, and let your app fire emails straight to your inbox.</li><li><strong>Step 2: Ditch Ngrok, use Cloudflare Tunnels.</strong> You need a public URL to catch the background request from Gmail. Most of us reach for the free version of Ngrok, but <strong>don’t do it.</strong> Ngrok injects a “Browser Warning” HTML page on the first request, which completely breaks AMP’s strict JSON requirements.</li><li><strong>The Fix:</strong> I switched to <strong>Cloudflare Tunnels</strong>. It gives you a clean, secure HTTPS URL (https://my-tunnel.trycloudflare.com) with zero injected junk. I pasted that URL into my AMP form, and boom! I could tap a button in my Gmail app and watch the data hit my local backend instantly.</li></ul><h3>Trap #4: The Popup Disaster</h3><p>I wanted to get fancy and add a modal for custom feedback. As I hinted at in Trap #2, the AMP Playground completely betrayed me here: it rendered my CSS position: fixed perfectly, popping the modal dead-center.</p><p>But in the real world, email clients routinely strip out fixed or absolute positioning. When I clicked the button at the bottom of my live test email, nothing seemed to happen. It turned out the popup was rendering, but because the CSS was stripped, it was awkwardly shoved at the very top of the email, completely out of view!</p><p>I thought about using the built-in &lt;amp-lightbox&gt; component to fix it, but I quickly realized two things: first, that component is facing deprecation soon, and second, it still suffered from weird positioning quirks inside certain email clients.</p><p><strong>The Fix:</strong> I stopped fighting the email clients and completely killed the popup idea.</p><p>In email design, simple is always better. Instead of a modal, I just used AMP’s state variables (amp-bind) to instantly reveal a hidden form right below the button they just clicked.</p><pre>&lt;button on=&quot;tap:AMP.setState({ showFeedbackForm: true })&quot;&gt;Tell us more&lt;/button&gt;</pre><pre>&lt;div hidden data-amp-bind-hidden=&quot;!showFeedbackForm&quot;&gt;<br>  &lt;textarea placeholder=&quot;Type your feedback...&quot;&gt;&lt;/textarea&gt;<br>  &lt;button type=&quot;submit&quot;&gt;Send&lt;/button&gt;<br>&lt;/div&gt;</pre><p>No scrolling, no overlay math, no deprecated components. Just a buttery smooth, inline UI that works perfectly every single time.</p><h3>Final Thoughts</h3><p>Building interactive emails is totally worth the learning curve. Seeing a user interact with your backend right from their inbox feels like magic, and the engagement rates are incredible once you get it right.</p><p>If you’re going to build this yourself: ditch the tables and use divs, use emojis to save weight, dynamically calculate your &lt;amp-list&gt; heights, skip Ngrok and use Cloudflare Tunnels for local testing, ditch the popups for inline forms, and always test with real emails to catch weird encoding bugs.</p><p><em>(Oh, and one last thing: Before you go live, remember that you have to submit a production-ready example of your email to Google, Yahoo, and Mail.ru to get your sending domain officially whitelisted. Happy coding!)</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1f344bf0b372" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>