Patrick McCarthy dev blog

WikiMapper 3.0

WikiMapper is back, and now also for Firefox!

WikiMapper is now a fully Manifest v3 compliant extension for both Chrome and Firefox!

Get it in the Chrome Store and Firefox Add-Ons

WikiMapper is a lightweight, passive browser extension that visualizes your Wikipedia stumblings so that you can see precisely how you got from Point A to Point B, and C, and D, etc.

This phenomenon was beautifully summed up by xkcd:

XKCD 214

Manifest v3

I’ve long-known about the need for all Chrome extensions to take on the breaking changes to migrate to Extension Manifest v3. But with life being busy and this twelve year old project (wow!) being pretty much an antique, I had mostly written off the effort and accepted WikiMapper’s fate as end-of-life when manifest v2 support ended.

Looking at the necessary migrations, updating the core functionality actually didn’t look so bad. Really just two notable items: moving the background script into a service worker (for Chrome), and refactoring direct synchronous interactions with localStorage to the newer, asynchronous storage API.

npm install trouble

Unfortunately, the last time I had significantly updated this extension was in 2016. And the last time I had even built the source was in 2021. And as most developers are aware, untouched and unused code tends to rot while the world moves on. Especially Javascript, and extra especially Javascript dev tooling.

Even with a checked-in package-lock.json and running the appropriate ancient version 4 of node.js, the first go at running npm install was a full on vomit of errors. Missing and unfulfilled dependencies, errors about version mismatches, deprecation notices, critical security flaws, and failures to build old binaries such as the long-defunct PhantomJS headless browser.

Disheartened, I was initially ready to throw in the towel and count WikiMapper a casualty of the new manifest v3 regime. But then I had an idea…

AI with the Assist

I don’t buy into the hype cycle that AI is coming to replace human developers, but I do utilize some AI assistant tools in my developer workflow. I don’t typically rely on AI tools to write significant code for me, but I have found value in using LLM chatbots as a better, more interactive, more tailored StackOverflow for learning new frameworks, libraries, APIs, and language features.

But for this WikiMapper upgrade, I thought it’d be a great test case for diving all the way in with Cursor and its agentic code assistant running to help me churn through the many tedious fixes, upgrades, and refactors. The codebase is only a couple thousand lines, entirely open source, and written in (for better or worse) the world’s most popular language: Javascript.

What I found using Cursor was pleasantly surprising, but also reaffirming that there is no scary magic miracle AI here yet.

An Overzealous Start

At first I set out with Cursor to modernize everything all at once, and it happily obliged. The Cursor agent suggested that I replace the old Grunt and Webpack build with Vite, the Karma and Jasmine test frameworks with Vitest, the Backbone app and Handlebars views with React, and so forth. And it offered to do all of this for me if I said yet. Ambitious!

I said let’s do it, and away we went churning through all the dependency changes and refactors. Every step of the way the AI agent was reporting on how great the progress was with such great confidence, assuring me that everything was going great. But after a couple hours of iterating we had created a monster. A haphazard, unintelligble, spaghetti monster.

I had ended up with an 80%ish functional app, but littered with issues that sent both me and the AI agent in circles. And since I hadn’t written any of the code myself I was both unable and uninspired to fix it. We had vibe coded ourselves into a hole.

A More Tactical, Guided Approach

So back to the drawing board, I git reset --hard origin/master and tried again, this time with much more oversight and narrowly scoped tasks for the AI agent to tackle. Instead of a sweeping modernization effort, I set out to do the minimal amount of work just to get the app working again.

First fix the build with the minimal necessary dependency changes. Then fix tests. Then make sure it would bundle and load as a dev extension (still v2 at this point). With each successful step, git commit along the way.

Once I had a working manifest v2 version up and running again, then I could undertake the specific changes to migrate to manifest v3. The AI agent made some missteps along the way, but ultimately helped me make all the necessary changes and iron most of the kinks to make the migration a success.

I did end up having to use my own human brain to debug an async race condition that the AI just kept going in circles trying to solve, which made it seems like a much harder bug than it was. I should have taken the reins on that one earlier.

The end result is that the app is still a Backbone-based app using an outdated version of D3.js and built with Grunt, all anachronisms in the year 2025, but I did make several major upgrades:

  • Updated all dependencies to latest supported versions
  • Replaced Browserify with Webpack
  • Migrated everything from CommonJS to ES Modules
  • Replaced PhantomJS with headless Chrome
  • Leverage webextension-polyfill to abstract the Chrome API to also support Firefox
  • Refactored the manifest v2 background script to manifest v3 background service worker
  • Refactored direct, synchronous localStorage usage with async browser.storage.local API
  • Refactored in-memory session state to persisted browser.storage.session API
  • Replace an obsolete svg-to-png library with a native canvas-based solution
  • Various other minor upgrades/replacements

Ultimately I’d call this a success story for using Cursor, and in retrospect I could have accomplished all of this without it, but it would have been tedious. Test-driving the AI agent approach was the motivation to do what I may otherwise have never gotten around to slogging through. Worth the $20 for a month of the Pro subscription for keeping this little hobby project.

Who knows, now that it’s back up and running maybe I’ll get inspired to do make some real functional improvements and modernizations in the future. No promises but stay tuned.

GitHub

As always, WikiMapper is a free and open-source software (MIT) project and is hosted on GitHub. WikiMapper does not collect any personal information, does not serve any ads, and does not transmit any data of any kind to anyone.