~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0

Old builds of an app draw what they can of newer views

Merged
Merged chadtmiller.com asked to merge into main from chadtmiller.com/hud:sdk/kit-version

Old iOS and Android builds keep the renderer they were built with while views change on the server. Kits now say their version as they call, HUD fits each tree to the kit that draws it, and release builds draw a component they don't know as its children, its fallback or nothing. Needs the owner's look at the shapes: the place.hud/kit capability, {"$kit": …} gates and fallback.

Claude Opus 5.5 · high

What changes

Kits say their version. HUDKit (Kit.version, bumped by knope), hudkit (BuildConfig.HUD_VERSION from hudVersion) and the web shell (its package.json) send io.modelcontextprotocol/clientInfo and the client capability extension place.hud/kit { platform, version } on every modern /mcp call; HUDKit's workspace client sends kit to place.hud.callTool (lexicon grows an optional kit). HUD reads the extension per request (MCP is stateless), logs it as kit on each mcp tool line, and fits the tree (hud_core::kit). No version said: the oldest kit, 0.2.0. The web shell, MCP Apps hosts (io.modelcontextprotocol/ui), legacy-era hosts, the workspace page and the playground: this HUD's version.

Views branch on it. A Stack's, Pane's or Bar's when/unless takes {"$kit": ">=0.3.0"} in place of a path, checked as semver by hud check. The resolver marks the node; kit::fit keeps or drops it per call, so caches stay kit-independent and no client sees the mark.

Unknown components degrade quietly. Any layout node may give fallback (validated, resolved over the same scope, in place.hud.ui). Each catalog component and prop carries since (all 0.2.0 now; new ones say theirs, shown in describe_collection). A component newer than the kit is sent as its children (as a Stack), else its fallback, else nothing. Release builds of HUDKit, hudkit and the web renderer do the same for a component they don't know; debug builds keep the NotYet box.

hud check warns about the oldest kit. An app file's "kits": {"oldest": "0.2.0"} makes hud check warn of each component or prop newer than it with no kit gate around it (or, a component, no fallback). Warning only.

Why

Grain's screens change for every client at once, but builds in people's hands drew a new component as "X isn't drawn on iOS yet" and the server couldn't tell who it was talking to. The kit is a client capability rather than clientInfo alone because MCP says servers shouldn't change behaviour on clientInfo. The $kit gate reuses when/unless as a first condition object, a step toward one condition form (No one way to say when a node draws: when, unless, mine, others, where) without taking it on here.

How it was checked

cargo fmt, clippy -D warnings, just cov (100% lines and functions), just lint, just lex, just json-schemas; web npm run check, npm run unit, npm run ssr (a dev server build added to hydrate the NotYet box), npm run package; just ios-test (166 passed); just android-test (153 passed). hud check with this build against next.grain.social's live apps: clean, with and without HUD_WORKSPACE=off, and with kits.oldest 0.2.0 added: no warnings. knope release --dry-run bumps everything, Kit.swift included, to 0.3.0.

Shortcomings

No component is newer than 0.2.0 yet, so the warning and server-side stand-in are exercised by unit tests with a fake catalog. The kit gate is on Stack, Pane and Bar alone, not on joins or a List. A kit claiming a version is trusted (it only chooses what is drawn). Builds already shipped (0.2.0) get the server-side stand-in but keep their own NotYet for anything else. docs/sdk.md said a minor bumps 0.x's minor; knope bumps the patch, so the change file says major for 0.3.0 and the doc now says so.

Review

Start at crates/hud-core/src/kit.rs, then ui/mod.rs (marked, menu) and the server's mcp.rs/xrpc.rs wiring.

Approved

This pull has kits send their version as a place.hud/kit client capability, or as kit to place.hud.callTool. HUD then fits each tree to the kit that draws it. A {"$kit": …} gate keeps or drops a node. A component newer than the kit becomes its children, else its fallback, else nothing. hud check warns about anything newer than kits.oldest.

I found nothing that needs changing. I read kit.rs in full, the /mcp and XRPC wiring, the resolver's marked and menu, and the iOS, Android and web clients' request changes.

  • Fallback to the oldest kit: an already-shipped 0.2.0 build sends a modern request with empty capabilities. It gets Kit::oldest(), which is the intended default.
  • Legacy-era requests: they get the current kit, and the doc comments say so.
  • Fitting: fit removes the $kit marks before anything is sent, so no client sees them. It recomputes hero when it changed the tree. It leaves caches kit-independent.
  • Menu rows: the Stack gate is carried onto each row, so the menu flattening keeps it.

Two small things, neither blocking:

  • passes uses VersionReq::matches, which never matches a pre-release kit version. A 0.3.0-rc.1 kit would fail >=0.3.0 gates. This is unlikely to matter.
  • A kit that claims platform: web is trusted as current. The pull's Shortcomings section already says kit claims are trusted.

I did not read these changed files:

  • the catalog, operator, schema and tools changes in hud-core;
  • the Swift, Kotlin and web renderer tree changes;
  • the test files;
  • the docs and schemas.

The pull says just check, just cov and the platform test suites pass. Per the pull's own note, the owner still needs to look at the place.hud/kit, $kit and fallback shapes.

Merged as 6365065