Forem: orangishcat

Page Proxy v0.2.x: the boring 'polishing' work and why I think it matters

orangishcat — Fri, 10 Apr 2026 22:48:12 +0000

This is the second devlog for my Chrome/Firefox userscript manager extension, Page Proxy! Here I'm gonna cover v0.2.x, where I'm still trying to figure out what direction I'm planning to take the extension in.

Refining and QOL work

This is what I would normally call "polishing" work. It gives the extension much-needed features and fixes long-standing bugs. This stage, I would say, comes after the "minimum viable product" stage, where you just need to get something working as idea validation.

After you get your initial users who are interested in your idea, keeping them becomes very important. This is where usability comes in, and to make a product with good usability, it must have adequate features and minimal bugs.

Extension early stage

At this point, I had a solid main idea of what I wanted the extension to do: turn page interactions into reusable userscripts.
But the extension was lacking a lot of features, so I had to find the order which I wanted to implement them in.

Roadmap

Website homepage
Create tool:
- Create a settings UI for your script (or any UI) easily
- Create components
Settings page for the extension
Multi-file scripts
Local scripts
Export to Tampermonkey userscript, CSS stylesheet, WXT extension
Import/export with Figma
Sync to cloud storage (Appwrite backend)
Userscript discovery, sharing, and collaboration

Now I had a good idea for what I wanted the extension to do.

But for v0.2.x, I started with the missing features.

The inconvenience I wanted to solve

While pq.selector could do a lot, sometimes it is simpler to just write CSS instead.

Using JS would be a waste for doing things that CSS can do already. Worst of all would be using a JS pq.selector just to inject styles on every matching element.

So I made a CSS inspector!

CSS Inspector

The CSS Inspector (above) works similarly to the selector popup added in the previous version, but it directly allows you to apply CSS rules to a pregenerated selector for the element.

And there's a nice dropdown that allows you to switch between this and the selector popup.

On the right side of the CSS inspector is a properties list, similar to the one from the other selector. Placing the mouse caret over any part of the main CSS selector will provide documentation for what that CSS keyword does, which essentially acts like built-in documentation.

As the tooltip says, you can also hold z to highlight matching elements in lime or x to preview styles applied in the editor.

I also added a button that can bring you to the CSS inspector page directly from the Select Tool.

There's also some other features. Like, you can view the computed styles for the selected element! It's very similar to the computed styles in DevTools. If there are :nth-of-type selectors in the selector, a link appears to remove them easily. The CSS selector syncs with the baseSelector field in the selector popup as well! Anything to avoid repetitive copying.

Upon hitting Save, it adds a ps.injectCSS snippet into the editor, which will directly inject a style tag into the document head upon script run.

Other QOL features

run-on-page-load grant

Before the update, the script wouldn't even be able to run on page load, and you'd have to click the run button manually every time. Fortunately, I added a @grant field to the metadata. It only accepts one value as of now, run-on-page-load, but it allows the script to execute automatically. A much needed feature.

// @grant run-on-page-load

Upon reload, it will create a dialog asking the user to grant permissions, like this:

Then it will ask the user to reload to apply updated permissions.

Help tool

Previously it was hardcoded into the extension. Now it fetches from the Github repository's HELP.md file, and rendered nicely in markdown.

DevTools integration

Added a wrench button in the select tool panel that appears when DevTools is open on the active tab. When clicking it, the selected element will match the selected element in DevTools. Highly useful for when the select tool can't select the element you want, like for example if its bounding box is covered by the bounding box of another element.

New APIs

pa.moveNode to move a node elsewhere, such as to a parent node, or before or after another node.
pv.pressKey to press keys programmatically using JS.

Editor persistence

Previously if a script was unsaved, switching to another tab without saving would cause you to lose your changes. Not anymore. Now a warning message appears and forces you to manually save before continuing.

It does not handle the extension sidepanel being closed, though, as there is no way to prevent it. The only solution in that case would be to autosave, which is risky as if there are bugs in the implementation someone's userscript can get overriden with the default script, causing them to lose it entirely.

Selectors tool

I gave it functionality by displaying highlighted elements upon hover.

Error handling

Errors are less likely to be silently swallowed now, and surface more clearly. It still needs a bit of work though.

Moving on to v0.3.x

v0.2.x added some much needed polish and a crucial CSS Inspector. It wasn't much, and ended up only being three versions, v0.2.0 to v0.2.2. That just means there were less features.

Oh and I also changed the storage format, which ended up causing some scripts to be lost. It was okay as I still don't have that many users, but I definitely need to be more careful with that next time.

Final thoughts

I think it's okay to be still figuring things out, and not just for your project either, this probably could work as life advice too. Changing directions in software development or in general is perfectly okay, and it allows one to refine and test their designs, and also throw out ideas that just don't quite work.

Of course, I definitely could have planned my features more thoroughly. The CSS Inspector as the main feature in v0.2.x is probably fine, but the rest of the polish would probably make more sense to be done in v0.1.x. Like having a method to inject CSS (ps.injectCSS) should have been like one of the main features of the custom pp-api. And making a breaking change to the storage format was definitely not a good idea. Could have used some planning beforehand.

Also, I started to use AI for coding a lot for this project. My AI setup is just Codex and some basic skills like superpowers, but it works pretty well. AI-generated code certainly isn't as clean as handwritten code, but it handles edge cases pretty well. Previously I found myself spending a lot more time passing states between components and fixing type objects, than spending time implementing actual functionality. So it's nice that AI allows me to go back to focusing on features, rather than type errors.

But the great thing about agentic engineering is that the product is still the output of my creative work. All the designs, the raw flow chart, and all my ideas are all me, and I've documented them in the Figma file and my devlogs. AI is just speeding up the implementation of those ideas, in a controlled manner.

The landing page is still looking pretty barren... definitely need to do that earlier next time.

I think that's it for this devlog. If you want to stick around, maybe I'll see you for v0.3.x?

Try out Page Proxy, and maybe give me some feedback? I'd also be interested to hear about your thoughts on AI and whatnot.

I built a GUI-powered Userscript manager to turn page interactions into userscripts!

orangishcat — Sat, 04 Apr 2026 04:04:56 +0000

I made Page Proxy, a Chrome and Firefox extension that converts page interactions into reusable code via Userscripts.

This is my first project I've ever released. Please try it out and give feedback! Would be really appreciated.

Why?

I've always found messing around with userscript managers like Tampermonkey quite fun; I could fix websites and change their behavior to my liking. But it took me roughly 15 minutes to go from idea to code, then 30 minutes to an hour just to debug and polish the script.

The first issue: juggling with DevTools windows, copy-pasting CSS selectors, and debugging my scripts was incredibly tedious.
I'd mostly have to rely on print debugging, then I would have to reload the page every time and search through the console for errors.

So I wanted a way to quickly generate CSS selectors and code. I wanted something similar to DevTools, but has integration with code and selector generation to speed up userscript development.

Second of all, there were many reoccurring patterns in all of my scripts. For example:

Do something on key press:

document.addEventListener("keydown" ev => {
    if (!ev.altKey) return;
    if (ev.code === "KeyV") {
        runFunction();
    }
});

Press a key using JS (e.g. Escape):

const escEvent = new KeyboardEvent("keydown", {
    key: "Escape",
    keyCode: 27,
    which: 27,
    bubbles: true,
    cancelable: true,
});

document.dispatchEvent(escEvent);

So I wanted to make an API that included all of these common usage patterns out of the box.

My philosophy

The product should solve:

GUI tools for userscript creation to make it less tedious
API covering common use cases and code patterns

The product must remain:

Accessibility: The extension can be complicated, but it should be easy to use. Add help docs (or links to them) everywhere.
Break-resistant: If a website's CSS classes change, the script should still work or at least be easy to migrate.
Integration: The extension should not replace any other tools. Keep Tampermonkey compatibility, integrate with DevTools.

Planning and design

Note: this was the first ever design sketch of the project. The extension has probably strayed quite far from it now.

I learned how to use Figma and some common design patterns. Designing my own UI has always been a goal of mine as a programmer, so I'm glad I was able to do that for this project.

Plus, I really disliked the overused blue-and-purple palette signature of AI website design. So using Realtime Colors, I chose a simple orange and lime color palette.

If you're interested, here's a raw, unedited flow chart of the features I wanted in Page Proxy that I threw up in an hour or so.

Initial design

I originally wanted to make Page Proxy a web app, mainly so it would "be unique". I quickly realized that unique does not always mean that it's good.

From a technical standpoint, the web app quickly became a terrible idea. Websites won't function due to CSP, and they certainly won't keep cookies, rendering pretty much all content behind a login screen completely inaccessible.

Besides, it just didn't make sense at all. It would be much more convenient to create an extension side panel, allowing it to be easily accessed, like DevTools.

Old design:

New extension design

After some designing, I came up with this:

I finally loved the design. It was significantly cleaner, and I also was incredibly proud of myself that I could make my color palette work so well.

It's similar to DevTools, but I kept the top toolbar as buttons. This fits the design very well, keeping the UI large-scale and with self-explanatory icons.

I liked this design for its simplicity. While DevTools, for example, was feature rich, it also had quite a steep learning curve, and a very dense, packed UI. I wanted to do the opposite; with the features I am planning, I wanted to prioritize ease of use, and I had no need for such densely packed features.

So the natural next question was: what tools do I want to add?

Tools

Select tool: Similar to DevTools' inspect element, but provides additional information like selectors, attributes, and more.
Create tool: Create components (like in web frameworks like React and Svelte) in scripts
Selectors tool: List CSS selectors and their properties
Help tool: Help links and stuff
Export tool: Export the script in a variety of different formats.

Now for the bottom half of the sidepanel.

Code editor

JS code editor
Has highlighting and autocomplete
Inspiration: Tampermonkey editor

Total time spent in design phase: 10 days. Probably only a few hours overall, but designing kinda felt like a chore since I was so new to it, which is why I didn't have the motivation to spend much time on it per day.

Implementation

Setup

I split the monorepo into web and extension directories.

Some library choices:

Package manager: bun
Web framework: Svelte
Extension framework: WXT
Components: bits-ui
CSS: tailwindcss
Icons: lucide-svelte
Network: axios (no I was not affected by the breach, because I update my packages like once a month)
Test: vitest
Code editor: CodeMirror

Actual coding

And implementation began. It was a bit rough at the start; the first implementation did not look good.

Along with the selector panel, I added a popup centered on the main page that provides element information and a selector builder. This helped identifying elements much easier, as unlike DevTools, all the selector information was all laid out already for me to convert into code.

The API

Original API layout (changed now):

pq: stands for pp-query, contains methods related to querying and traversing through DOM elements.
ps: pp-style: A module for style helpers
pv: pp-event: A module for callback-based event selectors For the methods that were added, view the old documentation, there's too many for me to list here.

The three files was placed in the extension directory, serving as a library containing the modules.

Also at the top of each userscript, there must be metadata. Similar to Tampermonkey, it had @title, @website, and @description to describe the script, and it is autogenerated upon new script creation but is very much editable.

// ==Page Proxy==
// @title Page Proxy
// @website
// @description
// ==/Page Proxy==

The editor

Looking at the above screenshot, the editor looked, well, not great. Code syntax highlighting broke often, and required a lot of maintenance. There were no line numbers. The entire container was offset for some reason. It was overall a huge pain to fix.

So I switched to Monaco editor, the same editor that powers VSCode. The extension instantly became a few MB heavier, but it was definitely worth it. Monaco editor was extremely powerful, with all the standard editor features such as renaming variables, syntax highlighting, and more just out of the box. I'm so glad I didn't have to implement any of that myself, yet it's available for everyone to use.

For autocomplete, I eventually hacked together a solution that generated type stubs from the API and passed it into Monaco editor. That temporary solution is still being used today. If it ain't broke, I ain't fixing it. It's probably staying in the codebase for good.

Nearly two months of coding later

The extension looks much more polished now. It was also functional enough that I was able to actually make and run userscripts on it.
I had spent way longer than expected on the project, and decided to cut some features for the initial release.
The select tool was finished fully, but the create tool was marked "Coming soon", and I settled on a simple display for the selectors tool.
At this point, I just needed to publish it and get some initial validation.

Demo website

It was quite plain, and didn't even have a feature list. I struggled a lot to explain the premise of the system in just 1-2 sentences. Even after publishing, the landing page remained incomplete for another two months.

Final polishes

Oh... no one could figure out how to use the extension. I've already tried to make the extension pretty self-explanatory, but I guess I still need to write some documentation.

Documentation

I used Docusaurus to host my documentation website. Although it used mdx (based on React) while the rest of my website was using Svelte, there just wasn't a solution that worked nearly as well out of the box. There I made some basic tutorials and wrote documentation for the API.

It was very primitive, but it got the job done, and eventually it was good enough for publish.

Bugs

I initially used script injection to run user JS in the page content, but that would be blocked by CSP on certain websites, rendering them completely inaccessible for userscripts. This was fixed easily by migrating to the UserScript API, but now users will have to enable permissions to run scripts on the main page.

Also, there were annoying Firefox-specific bugs that I had to fix, but they overall weren't too important.

The end of v0.1.x

For the rest of v0.1.x I just did some chores, bug fixes, and small features. I had made a basic sandbox for the userscript using @endojs/lockdown, but it didn't really work as it was extremely easy to bypass. I wanted to add functions, network access controls, etc., but it couldn't be done reliably without OS-native controls so I removed it in the last version of v0.1.x.

Initial validation

I published to Hack Club, and everyone who viewed my project thought it was pretty cool :D

Final thoughts

Whew! This is probably the longest piece of media I have written in my entire life. Evidently I have a lot to learn.

I'm ending the devlog at v0.1.x because as my first post ever, this took me like 3-4 hours to write. I've already added way more features in v0.2.x and v0.3.x, but I will get around to writing about them another time.

I learned a lot over this journey. This was my first introduction to multiple new webdev (and also non-webdev) concepts I had never interacted with before.

Figma: Probably my biggest reward from seeing the project through. I used to never plan out my projects, working things out as I go. Terrible idea. I eventually lost track of where I was going, leading me to lose motivation, and it's much easier to change a wireframe or Figma design than website code. Without UI planning, the UI doesn't look good and is quite clunky. I definitely also wanted to avoid the AI-generated UI look, so rolling my own would be a great learning process and would also look decent.
Svelte: I used React for a project once, but I hated it. I eventually became trapped in useEffect hell and gave up. Svelte gave me way less trouble; it handled all the dependencies and states easily without me ever needing to use a $effect.
WXT: Last time I tried making a Chrome extension, I gave up because Chrome refused to recognize my manifest no matter what I tried. WXT allows me to build extensions that are not only cross-browser using a unified API, but simplify the configuration as well. WXT gets a glowing recommendation from me.
Docusaurus: Not much else to say, other than it is insanely cool and works very well for hosting documentation.
GitHub actions: I learned to set up Actions workflows for basically whatever I wanted. I wrote build, check, deploy to GitHub Pages workflows using myself and some AI.
Dependency management: I configured Renovate to check for package updates. After all the package breaches that have been happening lately, I probably won't be updating any packages until they're each at least three days old.
Search Engine Optimization: I learned to add some basic metadata to the website for SEO.
Coding with AI: I learned to code alongside AI (no, letting the AI do everything didn't work) and speed up development, while I reviewed the code and kept the code quality as best as I could.

And as of v0.1.x, am I following my original goals for the project?

GUI tools: yes
API for common use cases: yes
Accessibility: yes
Break-resistant: no, not really; there were matchers based on other attributes like inner text, but CSS selectors were still much better
Integration: no, there's not much integration

But this is just the beginning, so I'd say this is a great starting point. I still have a lot of blogging to do for v0.2.x and v0.3.x.

If you think my extension is interesting, you can give it a try and maybe stick around as I devlog more of my journey!

This being my first project, I've probably never even written a blog post before, so I'm still figuring things out. Any feedback you have would be greatly appreciated!