~ 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
149 lines · 6.7 KB Raw History

title: Building an app on HUD section: HUD order: 9 summary: "HUD's packages for the web, iOS and Android, the registries they come from, and how they're versioned and released."

An app built on HUD draws what HUD's server resolves with HUD's own renderers, and calls HUD's tools for its data. Grain is one. The renderers and what goes around them come as packages, published from HUD's main to HUD's registries on knotless, so an app takes a version of them as it takes any other dependency.

PlatformPackageFrom
Web@hud/renderer, @hud/shell, @hud/sharednpm, https://knotless.dev/npm/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/
iOShud.HUDKitSwift package registry, https://knotless.dev/swift/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/
Androidplace.hud:hudkitMaven, https://knotless.dev/maven/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/

Each registry belongs to HUD's repository on knotless, named by its owner's DID and the repository's key (3n2kdckpvmnlo), which don't change. Reading them needs no login.

Versions

HUD has one version. The server, its crates and every package above share it, so @hud/shell 0.2.0, HUDKit 0.2.0 and hudkit 0.2.0 were made from the same commit, and they draw what a 0.2.0 server resolves. CHANGELOG.md says what changed in each version for an app built on HUD. An app file names the server versions it runs on in its hud (HUD versions), and hud check loads the app as that server would (checking apps).

Each kit says its version as it calls HUD: HUDKit's Kit.version, hudkit's BuildConfig.HUD_VERSION (its hudVersion) and the web shell's package version, each bumped by knope with the rest. So a build in someone's hands gets trees it can draw, and an app file names the oldest kit its builds still use (old builds and new views).

A pull that changes what such an app sees (a component, a prop, what a tree draws) adds a change file under .changeset/, as knope document-change writes one (https://knope.tech). It names the bump (patch, minor or major) in its front matter, then a heading and a line for the app's authors. In 0.x a major bumps the minor, and a minor or patch the patch. A component or prop it adds says the version it arrives in, its since in the catalog (p!("tone", TONE, since "0.3.0")).

On the web

@hud/renderer draws a resolved tree (Tree) and the pieces around it, @hud/shell draws an app from its app file (its frame, tabs and screens, on a server and hydrated), and @hud/shared reads a tool result (@hud/shared/result, @hud/shared/interactions). Each is Svelte 5 components and modules with their types, built by svelte-package, with Svelte as a peer dependency. Point the @hud scope at HUD's registry, then install them:

# .npmrc
@hud:registry=https://knotless.dev/npm/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/
npm install @hud/renderer @hud/shell @hud/shared

In a SvelteKit app, import the stylesheets once, in the root layout, the renderer's first:

<script lang="ts">
	import '@hud/renderer/theme.css';
	import '@hud/shell/shell.css';
</script>

Then draw with Shell from @hud/shell, and read the page's screen on the server with @hud/shell/server (screenAt, frameData, lookHead, Sessions). The packages leave relative imports without extensions, as a bundler resolves them, and SvelteKit's Vite bundles any package that exports Svelte, so they need no config of their own.

Inside HUD's own web/, the packages resolve to their source. Their exports name it under the @hud/source condition, which web/vite.config.ts, web/tsconfig.json and the server tests' builds ask for, so a change shows without a build. cd web && npm run package builds each package's dist, which is what a release publishes.

On iOS

HUDKit is a Swift package with Package.swift in ios/HUDKit. The registry has it as hud.HUDKit, published as an archive of that directory. Name HUD's registry for the hud scope, for your user (Xcode reads that) or for one package:

swift package-registry set --global --scope hud https://knotless.dev/swift/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/

Then depend on it in a Package.swift:

dependencies: [.package(id: "hud.HUDKit", from: "0.2.0")],
targets: [.target(name: "App", dependencies: [.product(name: "HUDKit", package: "hud.HUDKit")])]

Xcode resolves it as SwiftPM does, once the registry is set for your user. HUDKit needs iOS 17. The archives aren't signed, so SwiftPM warns that hud.HUDKit isn't signed as it fetches it.

On Android

hudkit is the Gradle module android/hudkit, published as place.hud:hudkit: its release AAR, its sources, a POM and Gradle's module metadata, naming what it depends on (Compose's BOM, OkHttp, kotlinx.serialization and the rest). It brings MapLibre Native's OpenGL ES build in place of the Vulkan one, so an app needs no substitution for it. Add HUD's repository for place.hud alone:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://knotless.dev/maven/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/") {
            content { includeGroup("place.hud") }
        }
    }
}
// app/build.gradle.kts
dependencies {
    implementation("place.hud:hudkit:0.2.0")
}

hudkit needs minSdk 28 and Compose. cd android && ./gradlew :hudkit:publishToMavenLocal puts the version in the tree into ~/.m2, to try it in an app with mavenLocal().

Releasing

A release starts from the change files on main. Ask for release-pull at main and it opens (or brings up to date) a pull titled Release <version>, which knope release made: every version in knope.toml bumped, the version's CHANGELOG.md section, the change files gone.

knotless run rerun knotless://chadtmiller.com/hud --ref refs/heads/main --workflow release-pull

Once it lands, ask for release at main. It builds the web packages, HUDKit's archive and hudkit's AAR, publishes each to its registry as the owner, and tags the commit v<version>.

knotless run rerun knotless://chadtmiller.com/hud --ref refs/heads/main --workflow release

It skips a package whose version is out already, so a run that failed partway is asked for again to finish. Until knotless.dev serves the Swift and Maven registries, it builds HUDKit and hudkit and says it skipped publishing them. Asked for at another branch, it builds everything and publishes nothing. Both run on ci.knotless.dev with RELEASE_PASSWORD, an app password of the owner's, sealed to that runner for main alone (knotless secret set).