URL state
The URL is the one source of truth for page state, shared by the UI and the assistant.
The problem
The usual way is to keep a filter in component state and maybe mirror it to the URL. Now there are two copies, and they drift. The link you paste to someone opens a different page than the one you were looking at, and Back does something nobody can predict.
Add an assistant and it gets worse. It needs its own list of “things I can do to this page”, written by hand, and that list falls behind the moment someone adds a filter.
What I concluded
There’s only one copy. Anything you’d want to share, bookmark or undo lives in the route’s search params, and each route says what it reads with a schema. The page reads the parsed params and writes by navigating. There’s no local state or global store for any of it.
const search = z.object({
status: z.enum(["all", "late", "shipped"]).default("all"),
sort: z.enum(["newest", "oldest"]).default("newest"),
order: z.string().optional(), // the open detail panel
});
createFileRoute("/orders/")({ validateSearch: search });
The same schema goes to the assistant
The assistant needs to know what it can do to a page, and that’s already written down: it’s the schema. For each page I merge the layouts’ schemas with the page’s own and hand the result over as JSON Schema.
schema ──▶ the page parses the address bar, fills defaults
└──▶ the assistant "open /orders with { status, sort }"
│
a write that fails the schema never reaches the page;
the reason goes back to the model instead
“Show me late orders, oldest first” becomes a navigation to /orders?status=late&sort=oldest. It’s checked against the same schema the address bar is, it lands in history like any other navigation, and Back undoes it.
The demo shows all three writers (the controls, the address bar and the assistant) changing one URL. A bad value typed by hand falls back to the default, a bad value from the assistant is rejected with the reason, and Back undoes any of them.
Rules
- If you’d share it, it’s in the URL. Filters, tabs, sort, pagination, which panel is open. Local state is for hover, focus and half-typed text.
- Debounce search inputs. Keep the keystrokes local and write the URL after a pause. Navigating on every keystroke makes the cursor jump.
- A schema the assistant can’t read is a bug. A custom validator that JSON Schema can’t express leaves that page invisible, so a test keeps that list empty.
- A modal publishes nothing of its own. It’s a child route, closing it is a Back, and its parent’s filters aren’t its filters.
What you get
You were going to validate the URL anyway. Publishing that validation costs one function and removes a whole class of drift: add a filter and the assistant can use it the same day.
Related: Navigation, UI as rendering engine, Back button.