Client: Add state to set a page's state and write what it can

[marcoroth]

This pull request adds state to the runtime, so a page can say what changed and let the client write the parts it can answer for itself.

apply says what to do with values once a page has them. Getting them was left to the page, which is to collect the state, put it in the query string, fetch, apply, then put the address bar back. That loop is the other half of the protocol, so it belongs next to apply.

const { state } = HerbRuntime.start()

await state.set({ query: "ruby", page: 1 })
state.set("query", "")
state.get("query")

The query string is the state, so the address bar keeps matching the page and back, forward and bookmarking keep working with nothing held on the server. set takes an object because one interaction usually changes several things at once, and everything set together travels as one request. It resolves to the report, because a page that shows what an update did needs it.

Writing before the server answers

Given the map the compiler builds, a page can write some slots itself. A slot whose expression is the state is written by copying, escaped the way the template would have escaped it, so a search box updates as fast as it is typed in while the count above it waits for the answer.

const report = await state.set("query", "ruby")
// { applied, deferred, written, restored, stale, failed }

written counts the optimistic writes and applied counts what the reply changed on top of them, so a reply that agrees reports 0. Confirming a write costs nothing, because a value equal to the one on the page is not written, and only a correction touches the DOM.

Escaping is not cosmetic here. An unescaped write would put live markup on the page for the length of a round trip and then be corrected, so matching what the server will send is what makes the confirmation free.

Three ways it goes wrong

A request that fails puts back every value it wrote, and the state it wrote them for, so a page does not keep claiming something the server never accepted.

A reply that arrives after a newer write has gone out is dropped, since applying it would undo something newer than itself. Sequencing is per key, so an unrelated key in flight does not discard an answer.

A slot the client cannot compute is left alone and comes back in the reply like any other.

Transport

The transport is a function, so the package assumes nothing about the protocol and its tests need no network. The default asks the same URL for the slots format, which is what ReActionView serves.

HerbRuntime.start({
  state: {
    transport: async (request, signal) => fetch(build(request), { signal }).then(response => response.json()),
    debounce: 150,
    history: false,
  },
})

Writing the value attribute does not move the property the browser reads, so an input keeps showing what was typed until the property follows. Every demo copied it back by hand. Doing it where the write is announced covers the server's writes too.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a5e3fa8

Command	Status	Duration	Result
nx run-many -t test --all --parallel --exclude=...	✅ Succeeded	3m 50s	View ↗
nx run-many -t build --all --exclude=herb-langu...	✅ Succeeded	46s	View ↗
nx build @herb-tools/tailwind-class-sorter	✅ Succeeded	1s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-08-18 16:30:04 UTC

[github-actions]

🌿 Interactive Playground and Documentation Preview

A preview deployment has been built for this pull request. Try out the changes live in the interactive playground:

• Playground Preview
• Documentation Preview
• Website Preview

---

_{🌱 Grown from commit 26c8927}

---

✅ Preview deployment has been cleaned up.

[pkg-pr-new]

npx https://pkg.pr.new/@herb-tools/formatter@2282

npx https://pkg.pr.new/@herb-tools/language-server@2282

npx https://pkg.pr.new/@herb-tools/linter@2282

commit: 26c8927