Last time, AI talked to HTML files. This time: a reactive library for malleable documents.

Hi web explorers,

I'm building a lot of malleable documents, and many of them need state that reacts to other state. Calculators, complex forms, spreadsheets, a note-taking app, a kanban board.

So I built sap.js, the first DOM-first reactive library, where all of your state lives in the document.

The first app built on it is the new Freelance Rate Calculator. It's probably my most-used tool online. It got almost 2,000 likes on Twitter, and it shows up on the first page of Google.

I'd estimate it's been downloaded around 100,000 times, and real freelancers love it. One freelance illustrator wrote: "I never would have guessed it could be so easy!"

In 2019 I gave my friend Zach Collins a project: build the most useful tool for freelancers. He designed a beautiful freelance rate calculator to help himself determine his rate.

The break-even ledger animation from freelanceratecalculator.com

Why normal reactive libraries break with documents that save themselves

When you build an app inside a malleable document, you hit a wall fast: data on the page has to respond to other data and to user inputs right away, or the app feels broken.

In a normal web app, React, Vue, and Alpine.js keep your state in a JavaScript object in memory and paint the result into the DOM. That breaks the moment the document saves itself. Saving serializes the live DOM to disk, so anything living only in JavaScript memory vanishes on reload.

My first try was a fork of Alpine.js that copied its state into HTML attributes. It was the easiest design to start with, but it had two problems:

  1. Every changed field was saved twice. The saved file kept the old default in x-data and the live value in a second attribute beside it.
  2. List rows were saved as escaped JSON. If you fixed a typo in the visible text, the JSON overwrote your fix on reload.

The cause of both is the same: Alpine treats a JavaScript object as the truth, and the page as a copy of it. Fixing that inside Alpine meant maintaining a 3,525-line fork forever, so I dropped it. I looked at HTMX, Stimulus, Datastar, Vue, petite-vue, Svelte, Solid, and Knockout. None of them fit. So I built a library where the page is the only copy of the data.

The same saved todo list in the Alpine fork and in sap.js

The DOM is the source of truth

A sap.js example: two number inputs bound to qty and price, and an output that shows their product as dollars

Type in either box and the total updates. Save the file and the value attributes hold what you typed. Reopen it later and everything is still there.

Most reactive libraries don't work with a DOM-first approach for three reasons:

  1. They keep state in memory. The saved page is a picture of the state, not the state itself, so it goes stale.
  2. They update only what they think changed. Fine-grained signals are fast, but when live collaboration changes the page behind their back, they leave stale values on screen.
  3. They remove what isn't showing. A normal router takes inactive pages out of the DOM, and in a document that saves itself, removed content is deleted from the file.

sap.js does the opposite. There is no state object: on every change it reads the page, recomputes everything, and writes the results back as real attributes. It never removes content, it only hides it, including when you use its router for multiple pages.

Recomputing everything sounds slow, and on big pages it was at first. With 10,000 rows, the test environment took 54 seconds per change. Profiling showed 92% of that time was spent looking up each element's children. Switching to walking siblings, and caching what we parsed from each element's attributes (never the values), brought it to 147 milliseconds.

Here are the stats in Chrome for a document with 10,000 rows:

sap.js in Chrome at 10,000 rows: todo toggle 44 ms to 8 ms, journal edit 103 ms to 34 ms, Cmd+S save 628 ms to 392 ms

I like software, but I don't like signing up for it

When I sat down to rebuild the Freelance Rate Calculator as a web app, the obvious move was a SaaS with user accounts. But I don't like that type of software. It means a monthly fee, a login to run your own numbers, and not knowing how your data is used.

I want tools that are:

How do I compete with the Google Sheets brand? I can't.

The hardest part of replacing the old page was the trust people have in Google Sheets. Everyone knows Google, everyone is already logged in, and making a copy of a sheet feels safe.

But here's what I can do:

I want to help people out of silos like Google and Canva, and onto the open web, working with their own documents on their own computers.

New features in the Freelance Rate Calculator, added in the latest version

My favorite feature: from browser tab to file on disk

Here's how your numbers get from the web page into your own file:

  1. Your browser has them. As you type, the calculator saves your numbers as JSON in your browser's local storage.
  2. The download sends them along. When you click download, the page sends that JSON to Hyperclay, through the same engine as its JSON API.
  3. Hyperclay writes your file. It puts your numbers into a fresh copy of the calculator and sends that back to you as a download.

Hyperclay never stores your numbers. They only live in your browser, and then in the file on your computer.

From browser tab to disk: your browser's JSON goes to Hyperclay's JSON API, which writes your .htmlclay file

Independent velociraptors will take down gargantuan T-Rexes

I built this Freelance Rate Calculator because I want more people to go independent. The first question anyone asks before they jump is: can I afford it? The calculator makes that first step easier to think about.

If Hyperclay succeeds as a business, I want it to spawn many small businesses that my employees leave to run, not grow into one gargantuan company. More autonomy leads to better work, a higher-trust society, and more human flourishing.

I know leaving your employer is a huge risk, and nobody should take it lightly. But if you can make the numbers work, you get to serve people directly.

That's really why I'm building malleable software. I think the world should be malleable. Everyone should have the authority to shape not only their homes and their own bodies, but their neighborhoods, communities, towns and cities, and to make reality into a fun, cooperative game. My hope is that malleable software is the first step toward a more malleable physical world.

Three velociraptors facing down a T-Rex

Let's hack software and make it easier to build for everyone,

David
@panphora

P.S. If you've been using HTML Clay to run your own apps on your computer, reply and tell me how it's going.

P.P.S. Hyperclay has a new homepage.