@solidrt/cli 0.0.32 → 0.0.34

package/src/commands/pack.ts

@@ -1,6 +1,11 @@
 import { values, source } from "../args"
-import { bundleFlux, bundleSolid } from "../bundler"
-import { packRunner } from "../packer"
+import { bundleFlux, bundleSolid, compileToBytecode } from "../bundler"
+import { resolvePackFonts } from "../fonts"
+import { loadAppIdentity } from "../project"
+import { packFlux, packSolid } from "../packer"
+import { buildPackFolder, writePackFolder } from "../pack-folder"
+import { requireBinary } from "../util"
+import { resolve } from "node:path"
 
 // Write the packed executable, mark it runnable, and report its size.
 async function writeExecutable(packed: Buffer, outfile: string) {
@@ -12,14 +17,45 @@ async function writeExecutable(packed: Buffer, outfile: string) {
 }
 
 export async function runPackCommand() {
+  if (values.flux) {
+    if (values.folder) {
+      console.error("--folder is for app packs; flux scripts have no folder output")
+      process.exit(1)
+    }
+    let outfile = values.output ?? source!.replace(/\.[jt]sx?$/, "")
+    if (process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe")) {
+      outfile += ".exe"
+    }
+    await writeExecutable(await packFlux(await bundleFlux(source!)), outfile)
+    process.exit()
+  }
+
+  // Both solidrt outputs are the same canonical pack: manifest + bundle.bin +
+  // assets (fonts included). --folder writes it as a flat folder next to a
+  // bare runner; the default single-file exe carries it as trailer sections.
+  let identity = loadAppIdentity(source!)
+  console.log(`>> app: ${identity.appId} (${identity.org} / ${identity.displayName})`)
+  if (identity.defaulted) {
+    console.warn('>> warning: no "solidrt.appId" in package.json; set a stable reverse-DNS id before distributing')
+  }
+  let fonts = resolvePackFonts(source!)
+  console.log(`>> fonts: ${fonts.length ? fonts.map((f) => f.alias).join(", ") : "none"}`)
+
+  let bytecode = await compileToBytecode(await bundleSolid())
+  let folder = buildPackFolder(source!, bytecode)
+
+  if (values.folder) {
+    let outDir = values.output ?? "dist"
+    writePackFolder(outDir, requireBinary("solidrt"), bytecode, folder)
+    console.log(`>> wrote pack folder to ${resolve(outDir)}`)
+    process.exit()
+  }
+
   let outfile = values.output ?? source!.replace(/\.[jt]sx?$/, "")
   // On Windows the packed image is a PE executable; it needs a .exe name to run.
   if (process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe")) {
     outfile += ".exe"
   }
-  let packed = values.flux
-    ? await packRunner("fluxrt", await bundleFlux(source!))
-    : await packRunner("solidrt", await bundleSolid())
-  await writeExecutable(packed, outfile)
+  await writeExecutable(packSolid(folder, bytecode), outfile)
   process.exit()
-}
+}

package/src/commands/server.ts

@@ -2,6 +2,7 @@ import pkg from "../../package.json"
 import { source, isSource, isPrebuilt, values } from "../args"
 import { state, shutdown } from "../util"
 import { bundle } from "../bundler"
+import { buildManifest, projectDirFor } from "../project"
 import { startServer, buildReload, sendReload, showBuildFailure } from "../dev-server"
 import { startRepl } from "../repl"
 import { startWatcher } from "../watcher"
@@ -14,6 +15,7 @@ export async function runServerCommand() {
   // Initialize state from args
   state.source = source
   state.sourceDir = source ? dirname(resolve(source)) : process.cwd()
+  state.projectDir = source ? projectDirFor(resolve(source)) : process.cwd()
   state.stats = values.stats
   state.capture = values.capture ? resolve(values.capture) : undefined
 
@@ -29,13 +31,19 @@ export async function runServerCommand() {
     if (initialResult) {
       state.currentCode = initialResult.code
       state.currentMap = initialResult.map
-      await sendReload(buildReload({ code: state.currentCode }), { latch: true, map: state.currentMap })
+      state.currentManifest = initialResult.manifest
+      await sendReload(buildReload({ code: state.currentCode, manifest: state.currentManifest }), {
+        latch: true,
+        map: state.currentMap,
+      })
     } else {
       await showBuildFailure()
     }
   } else if (source && isPrebuilt && source.endsWith(".srt.js")) {
-    state.currentCode = await Bun.file(resolve(source)).text()
-    await sendReload(buildReload({ code: state.currentCode }), { latch: true })
+    let path = resolve(source)
+    state.currentCode = await Bun.file(path).text()
+    state.currentManifest = buildManifest(state.currentCode, path)
+    await sendReload(buildReload({ code: state.currentCode, manifest: state.currentManifest }), { latch: true })
   }
 
   process.on("SIGINT", shutdown)

package/src/dev-client.ts

@@ -1,12 +1,12 @@
 import { state, print, requireBinary, pipeAbovePrompt, shutdown } from "./util"
 import { DEV_HOST, DEV_PORT, getClients, shutdownWhenEmpty } from "./dev-server"
-import { values } from "./args"
+import { values, clientStorageArgs } from "./args"
 
 export function spawnClient() {
   let runner = requireBinary("solidrt-go")
   // The local client and dev server share this machine, so connect straight to
   // the loopback server: no mDNS discovery or recents lookup is needed for `run`.
-  let args: string[] = ["--dev-server", `${DEV_HOST}:${DEV_PORT}`]
+  let args: string[] = ["--dev-server", `${DEV_HOST}:${DEV_PORT}`, ...clientStorageArgs()]
   if (values.size) args.push("--size", values.size)
   state.child = Bun.spawn([runner, ...args], {
     stdio: ["ignore", "pipe", "pipe"],

package/src/dev-server.ts

@@ -16,9 +16,18 @@ const INTERNAL_BASE = `http://${DEV_HOST}:${DEV_PORT}/__internal__`
 
 // Build the reload message for the client protocol. The server latches a
 // broadcast reload verbatim for late-joining clients, so srt owns the message
-// shape (including the proxy flags) end to end.
-export function buildReload(payload: { code?: string | null; bytecode?: string }) {
-  return { type: "reload", proxyFiles: values["proxy-files"], proxyHttp: values["proxy-http"], ...payload }
+// shape (including the proxy flags) end to end. `manifest` is the bundle's
+// version manifest JSON string; when present, clients install the push into
+// their version store before applying it (absent for bytecode one-shots and
+// the BSOD trigger, which must not be installed).
+export function buildReload(payload: { code?: string | null; bytecode?: string; manifest?: string | null }) {
+  let { manifest, ...rest } = payload
+  return {
+    type: "reload",
+    proxyHttp: values["proxy-http"],
+    ...(manifest ? { manifest } : {}),
+    ...rest,
+  }
 }
 
 async function post(path: string, body: object) {
@@ -30,13 +39,21 @@ async function post(path: string, body: object) {
  * Send a client-protocol message through the server: to the given client ids,
  * or to every client when omitted. `latch` keeps the message for late-joining
  * clients (code reloads latch, one-shot bytecode loads do not); `sourceDir`
- * moves the server's file-serving root (repl `load`); `map` is the bundle's
- * sourcemap, kept server-side for stack-trace remapping (omitting it clears
- * the server's map, so a mapless reload never remaps against a stale one).
+ * moves the server's file-serving root and `projectDir` its /assets/ root
+ * (repl `load`); `map` is the bundle's sourcemap, kept server-side for
+ * stack-trace remapping (omitting it clears the server's map, so a mapless
+ * reload never remaps against a stale one).
  */
 export async function sendReload(
   message: object,
-  opts: { clients?: number[]; latch?: boolean; sourceDir?: string; entry?: string; map?: string | null } = {},
+  opts: {
+    clients?: number[]
+    latch?: boolean
+    sourceDir?: string
+    projectDir?: string
+    entry?: string
+    map?: string | null
+  } = {},
 ) {
   await post("/reload", { message, ...opts })
 }
@@ -97,6 +114,8 @@ const BSOD_TRIGGER = `throw new Error("SolidRT: build failed")`
 // pushes it to every connected client.
 export async function showBuildFailure() {
   state.currentCode = BSOD_TRIGGER
+  // No manifest: the BSOD trigger is not a version and must never be installed.
+  state.currentManifest = null
   await sendReload(buildReload({ code: BSOD_TRIGGER }), { latch: true })
 }
 
@@ -158,14 +177,15 @@ export async function startServer() {
   let config = {
     port: DEV_PORT,
     sourceDir: state.sourceDir,
+    projectDir: state.projectDir,
     address,
-    proxyFiles: values["proxy-files"],
     proxyHttp: values["proxy-http"],
     entry: state.source,
     minify: values.minify,
     bundlerCmd: [process.execPath, bundleCli],
     cache: values["proxy-http"],
-    cacheDir: process.cwd(),
+    cacheDir: resolve(".srt-data"),
+    keyDir: process.cwd(),
     capture: state.capture,
     stats: state.stats,
     tunnel: values.tunnel,

package/src/fonts.ts

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { findProjectPackage } from "./project"
+
+// The fonts `srt pack` appends to a solidrt binary (see
+// okf/plans/packaged-fonts.md). By default the three Noto role defaults;
+// the project's package.json can override them via the `solidrt.fonts` map
+// (alias -> font file path, or false to drop a default):
+//
+//   "solidrt": {
+//     "fonts": {
+//       "sans": "./fonts/Inter.ttf",   // replaces the sans default
+//       "mono": false,                 // drops the mono default
+//       "display": "./fonts/F.ttf"     // adds a font under a custom alias
+//     }
+//   }
+
+/** A resolved font source: the file behind an alias. */
+export type ResolvedFont = { alias: string; path: string; isDefault: boolean }
+
+let DEFAULT_FONTS: Record<string, string> = {
+  sans: "NotoSans.ttf",
+  serif: "NotoSerif.ttf",
+  mono: "NotoSansMono.ttf",
+}
+
+// Where the default Noto files live: a contributor checkout via SRT_HOME, the
+// fonts/ copy shipped inside the published CLI package (staged at release
+// time), or the monorepo relative to this source file.
+function defaultFontsDir(): string | null {
+  let candidates: string[] = []
+  if (process.env.SRT_HOME) candidates.push(resolve(process.env.SRT_HOME, "alloy/assets/fonts"))
+  candidates.push(resolve(import.meta.dir, "../fonts"))
+  candidates.push(resolve(import.meta.dir, "../../../alloy/assets/fonts"))
+  for (let dir of candidates) {
+    if (existsSync(resolve(dir, "NotoSans.ttf"))) return dir
+  }
+  return null
+}
+
+function findProjectConfig(sourcePath: string): { dir: string; fonts: unknown } | null {
+  let project = findProjectPackage(sourcePath)
+  return project && { dir: project.dir, fonts: project.pkg.solidrt?.fonts }
+}
+
+function fail(message: string): never {
+  console.error(message)
+  process.exit(1)
+}
+
+// Resolve the font set for a pack as file paths: role defaults merged with the
+// project's `solidrt.fonts` map. Order is roles first (sans, serif, mono),
+// then added aliases in config order.
+export function resolvePackFonts(sourcePath: string): ResolvedFont[] {
+  let config = findProjectConfig(sourcePath)
+  let overrides = config?.fonts ?? {}
+  if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
+    fail('The "solidrt.fonts" key in package.json must be a map of alias to font file path (or false)')
+  }
+
+  // alias -> path relative to the config dir, or null for a role default.
+  let selected = new Map<string, string | null>()
+  for (let role of Object.keys(DEFAULT_FONTS)) selected.set(role, null)
+  for (let [alias, value] of Object.entries(overrides)) {
+    if (value === false) {
+      if (!(alias in DEFAULT_FONTS)) fail(`"solidrt.fonts": "${alias}": false drops a default, but "${alias}" is not one of ${Object.keys(DEFAULT_FONTS).join("/")}`)
+      selected.delete(alias)
+    } else if (typeof value === "string") {
+      if (Buffer.byteLength(alias, "utf8") > 255) fail(`"solidrt.fonts": alias "${alias}" is too long (max 255 bytes)`)
+      selected.set(alias, resolve(config!.dir, value))
+    } else {
+      fail(`"solidrt.fonts": "${alias}" must be a font file path or false, got ${JSON.stringify(value)}`)
+    }
+  }
+
+  let defaultsDir: string | null = null
+  let fonts: ResolvedFont[] = []
+  for (let [alias, path] of selected) {
+    let isDefault = path === null
+    if (path === null) {
+      defaultsDir ??= defaultFontsDir() ?? fail(
+        "Could not find the default fonts (NotoSans.ttf and friends).\n" +
+          "Point SRT_HOME at your SolidRT checkout (and run `make download-fonts` there if needed).",
+      )
+      path = resolve(defaultsDir, DEFAULT_FONTS[alias]!)
+    }
+    if (!existsSync(path)) fail(`"solidrt.fonts": "${alias}": no such file: ${path}`)
+    fonts.push({ alias, path, isDefault })
+  }
+  return fonts
+}

package/src/pack-folder.ts

@@ -0,0 +1,112 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import {
+  assetPathFor,
+  collectAssets,
+  loadAppIdentity,
+  projectDirFor,
+  RUNTIME_VERSION,
+  type ManifestFont,
+} from "./project"
+import { resolvePackFonts } from "./fonts"
+
+// The canonical flat pack folder (okf/plans/client-storage-updates.md, Pack
+// output): runner + manifest.json + bundle.bin + assets/. The manifest
+// enumerates exactly the files belonging to the version - the runner is
+// deliberately unlisted - and, unlike dev manifests, carries the full app
+// identity (org, displayName) and the complete font set with the default
+// fonts materialized under assets/fonts/.
+
+function fail(message: string): never {
+  console.error(message)
+  process.exit(1)
+}
+
+function hashHex(bytes: Uint8Array): string {
+  return new Bun.CryptoHasher("sha256").update(bytes).digest("hex")
+}
+
+export type PackFolder = {
+  /** The canonical manifest JSON string (serialized once, written verbatim). */
+  manifest: string
+  /** Files to place in the folder: absolute source -> folder-relative path. */
+  copies: Array<{ from: string; to: string }>
+}
+
+export function buildPackFolder(entry: string, bytecode: Buffer): PackFolder {
+  let identity = loadAppIdentity(entry)
+  let projectDir = projectDirFor(resolve(entry))
+  let { assets } = collectAssets(entry)
+  let copies = assets.map((a) => ({ from: join(projectDir, a.path), to: a.path }))
+
+  // The full resolved font set: custom fonts are already collected assets;
+  // defaults materialize under assets/fonts/ (a user file already at that
+  // path must be the same bytes, otherwise the layout is ambiguous).
+  let fonts: ManifestFont[] = []
+  for (let font of resolvePackFonts(entry)) {
+    if (font.isDefault) {
+      let path = "assets/fonts/" + basename(font.path)
+      let bytes = readFileSync(font.path)
+      let existing = assets.find((a) => a.path === path)
+      if (existing) {
+        if (existing.sha256 !== hashHex(bytes)) {
+          fail(`${path} collides with the packed default font; rename it or bind it via "solidrt.fonts"`)
+        }
+      } else {
+        assets.push({ path, sha256: hashHex(bytes), size: bytes.length })
+        copies.push({ from: font.path, to: path })
+      }
+      fonts.push({ path, alias: font.alias })
+    } else {
+      let path = assetPathFor(projectDir, font.path)
+      if (!path) fail(`"solidrt.fonts": "${font.alias}": ${font.path} must live under assets/`)
+      fonts.push({ path, alias: font.alias })
+    }
+  }
+  assets.sort((a, b) => (a.path < b.path ? -1 : 1))
+
+  let manifest = JSON.stringify({
+    appId: identity.appId,
+    org: identity.org,
+    displayName: identity.displayName,
+    runtimeVersion: RUNTIME_VERSION,
+    bundle: { path: "bundle.bin", sha256: hashHex(bytecode), size: bytecode.length },
+    ...(assets.length ? { assets } : {}),
+    ...(fonts.length ? { fonts } : {}),
+  })
+  return { manifest, copies }
+}
+
+/**
+ * Write the folder. An existing output dir is only reused when it is empty or
+ * already a pack folder (has a manifest.json) - then the files this pack owns
+ * (runner, manifest, bundle, assets/) are replaced; anything else in it is
+ * left alone but never a reason to touch an unrelated directory.
+ */
+export function writePackFolder(outDir: string, runnerPath: string, bytecode: Buffer, folder: PackFolder) {
+  let existing = existsSync(outDir) ? readdirSync(outDir) : null
+  if (existing && existing.length > 0 && !existing.includes("manifest.json")) {
+    fail(`${resolve(outDir)} exists and is not a pack folder; choose another --output`)
+  }
+
+  let runnerName = "solidrt" + (process.platform === "win32" ? ".exe" : "")
+  mkdirSync(outDir, { recursive: true })
+  rmSync(join(outDir, "assets"), { recursive: true, force: true })
+  for (let name of ["manifest.json", "bundle.bin", runnerName]) {
+    rmSync(join(outDir, name), { force: true })
+  }
+
+  // Dereference: the runner path may itself be a symlink (contributor dist
+  // layouts); the folder must carry the real binary.
+  cpSync(runnerPath, join(outDir, runnerName), { dereference: true })
+  if (process.platform !== "win32") {
+    Bun.spawnSync(["chmod", "+x", join(outDir, runnerName)])
+  }
+  writeFileSync(join(outDir, "bundle.bin"), bytecode)
+  writeFileSync(join(outDir, "manifest.json"), folder.manifest)
+  for (let { from, to } of folder.copies) {
+    let dest = join(outDir, to)
+    mkdirSync(dirname(dest), { recursive: true })
+    cpSync(from, dest)
+  }
+}

package/src/packer.ts

@@ -1,27 +1,70 @@
+import { readFileSync } from "node:fs"
 import { requireBinary } from "./util"
 import { compileToBytecode } from "./bundler"
+import type { PackFolder } from "./pack-folder"
 
 // Trailer magic identifying the runner an embedded payload belongs to. Must match
 // the runner-side checks: fluxrt -> flux/src/bin/fluxrt.rs, solidrt ->
-// lattice/src/main.rs (load_embedded_bytecode).
+// lattice/src/main.rs (load_embedded_payload).
 const MAGIC = {
   fluxrt: Buffer.from([0x46, 0x4c, 0x55, 0x58, 0x52, 0x54, 0x88, 0x44]), // "FLUXRT\x88\x44"
   solidrt: Buffer.from([0x53, 0x4f, 0x4c, 0x49, 0x44, 0x52, 0x54, 0x88, 0x44]), // "SOLIDRT\x88\x44"
 }
 
-export type Runner = keyof typeof MAGIC
+// Section kinds in the solidrt trailer. Must match lattice/src/main.rs.
+const SECTION_MANIFEST = 1
+const SECTION_FILE = 2
 
-// Compile JS to bytecode and append it to the runner binary, followed by a
-// trailer of [u64 offset LE][8-byte magic]. The runner reads its own image at
-// startup, validates the magic, and slices the bytecode back out.
-export async function packRunner(runner: Runner, jsCode: string): Promise<Buffer> {
-  let bytecode = await compileToBytecode(jsCode)
+type Section = { kind: number; bytes: Buffer; name?: string }
+
+// Append sections to the runner image: each section's bytes, then a table of
+// section entries, then [table offset u64 LE][entry count u32 LE][magic].
+// Table entry: [kind u32 LE][offset u64 LE][len u64 LE][name len u16 LE][name].
+// Offsets are absolute file offsets. The runner reads its own image at
+// startup, validates the magic, and slices the sections back out.
+function packSections(runnerBytes: Buffer, sections: Section[], magic: Buffer): Buffer {
+  let parts: Buffer[] = [runnerBytes]
+  let entries: Buffer[] = []
+  let offset = runnerBytes.length
+  for (let section of sections) {
+    parts.push(section.bytes)
+    let name = Buffer.from(section.name ?? "", "utf8")
+    let entry = Buffer.allocUnsafe(22 + name.length)
+    entry.writeUInt32LE(section.kind, 0)
+    entry.writeBigUInt64LE(BigInt(offset), 4)
+    entry.writeBigUInt64LE(BigInt(section.bytes.length), 12)
+    entry.writeUInt16LE(name.length, 20)
+    name.copy(entry, 22)
+    entries.push(entry)
+    offset += section.bytes.length
+  }
+  let tail = Buffer.allocUnsafe(12)
+  tail.writeBigUInt64LE(BigInt(offset), 0) // the table starts where the sections end
+  tail.writeUInt32LE(sections.length, 8)
+  return Buffer.concat([...parts, ...entries, tail, magic])
+}
 
-  let runnerPath = requireBinary(runner)
-  let runnerBytes = Buffer.from(await Bun.file(runnerPath).arrayBuffer())
+// The single-file solidrt executable: the runner image plus the pack folder in
+// section form - the canonical manifest verbatim, then every manifest-listed
+// file named by its manifest path. Bundle, fonts, and identity all come from
+// the manifest; assets are read in place via ranged reads at their section
+// offsets, so nothing is unpacked at runtime.
+export function packSolid(folder: PackFolder, bytecode: Buffer): Buffer {
+  let runnerBytes = readFileSync(requireBinary("solidrt"))
+  let sections: Section[] = [
+    { kind: SECTION_MANIFEST, bytes: Buffer.from(folder.manifest, "utf8") },
+    { kind: SECTION_FILE, bytes: bytecode, name: "bundle.bin" },
+    ...folder.copies.map((c) => ({ kind: SECTION_FILE, bytes: readFileSync(c.from), name: c.to })),
+  ]
+  return packSections(runnerBytes, sections, MAGIC.solidrt)
+}
 
+// Compile JS to bytecode and append it to the fluxrt runner as its
+// single-payload trailer: [bytecode][u64 offset LE][8-byte magic].
+export async function packFlux(jsCode: string): Promise<Buffer> {
+  let bytecode = await compileToBytecode(jsCode)
+  let runnerBytes = readFileSync(requireBinary("fluxrt"))
   let offsetBuf = Buffer.allocUnsafe(8)
   offsetBuf.writeBigUInt64LE(BigInt(runnerBytes.length))
-
-  return Buffer.concat([runnerBytes, bytecode, offsetBuf, MAGIC[runner]])
-}
+  return Buffer.concat([runnerBytes, bytecode, offsetBuf, MAGIC.fluxrt])
+}

package/src/project.ts

@@ -0,0 +1,171 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+
+// Project configuration lives in the `solidrt` key of the nearest package.json
+// above the entry file (okf/plans/client-storage-updates.md):
+//
+//   "solidrt": {
+//     "appId": "com.example.app",   // stable identity: storage dir, Android package id
+//     "org": "Example",             // optional display metadata (publisher)
+//     "displayName": "Example App", // optional display metadata (launcher/window)
+//     "fonts": { ... }              // see fonts.ts
+//   }
+//
+// Everything defaults from the package name (or the entry filename when there
+// is no package.json) so a dev project needs zero config; `srt pack` warns
+// when appId is defaulted, since a distributed app should pin its identity.
+
+export function findProjectPackage(sourcePath: string): { dir: string; pkg: any } | null {
+  let dir = resolve(dirname(sourcePath))
+  while (true) {
+    let pkgPath = resolve(dir, "package.json")
+    if (existsSync(pkgPath)) {
+      return { dir, pkg: JSON.parse(readFileSync(pkgPath, "utf8")) }
+    }
+    let parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+export type AppIdentity = { appId: string; org: string; displayName: string; defaulted: boolean }
+
+function fail(message: string): never {
+  console.error(message)
+  process.exit(1)
+}
+
+// Storage directory component (matches the runtime's safe_component check).
+let APP_ID_PATTERN = /^[A-Za-z0-9._-]+$/
+
+// Derived values are sanitized into a valid appId; explicit config must
+// already be valid (throw-in-dev policy: a bad value fails the command).
+function sanitizeAppId(name: string): string {
+  let id = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "")
+  return id === "" || id === "." || id === ".." ? "app" : id
+}
+
+function checkField(value: string, what: string) {
+  if (Buffer.byteLength(value, "utf8") > 255) fail(`"solidrt": ${what} is too long (max 255 bytes)`)
+  if (/[/\\]/.test(value)) fail(`"solidrt": ${what} must not contain path separators`)
+  if (value === "") fail(`"solidrt": ${what} must not be empty`)
+}
+
+// The version manifest for a bundle (okf/plans/client-storage-updates.md,
+// stages 2 + 3): appId + runtimeVersion + the bundle entry + the collected
+// assets/ tree + font annotations. The returned JSON string is canonical - it
+// travels verbatim to clients and its sha256 is the version id, so it must
+// never be re-serialized along the way. runtimeVersion is the constant 1
+// until the derivation question is settled (see plan).
+// The manifest's runtimeVersion: a manually bumped constant until the
+// derivation question is settled (see plan).
+export const RUNTIME_VERSION = 1
+
+export function buildManifest(code: string, entry: string): string {
+  let identity = loadAppIdentity(entry)
+  let sha256 = new Bun.CryptoHasher("sha256").update(code).digest("hex")
+  let { assets, fonts } = collectAssets(entry)
+  return JSON.stringify({
+    appId: identity.appId,
+    runtimeVersion: RUNTIME_VERSION,
+    bundle: { path: "bundle.js", sha256, size: Buffer.byteLength(code, "utf8") },
+    ...(assets.length ? { assets } : {}),
+    ...(fonts.length ? { fonts } : {}),
+  })
+}
+
+export type ManifestAsset = { path: string; sha256: string; size: number }
+export type ManifestFont = { path: string; alias: string }
+
+// The project root the assets/ convention hangs off: the nearest package.json
+// dir, or the entry's own dir when there is none.
+export function projectDirFor(sourcePath: string): string {
+  return findProjectPackage(sourcePath)?.dir ?? resolve(dirname(sourcePath))
+}
+
+// The manifest asset path for an absolute file inside the project's assets/
+// dir, or null when it lies outside it.
+export function assetPathFor(projectDir: string, abs: string): string | null {
+  let rel = relative(resolve(projectDir, "assets"), abs)
+  if (rel.startsWith("..") || isAbsolute(rel)) return null
+  return "assets/" + rel.split(sep).join("/")
+}
+
+function walkAssets(assetsDir: string, dir: string, out: ManifestAsset[]) {
+  for (let entry of readdirSync(dir, { withFileTypes: true })) {
+    // Dotfiles (.DS_Store and friends) are tooling noise, not app assets.
+    if (entry.name.startsWith(".")) continue
+    let abs = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walkAssets(assetsDir, abs, out)
+    } else if (entry.isFile()) {
+      let bytes = readFileSync(abs)
+      let path = "assets/" + relative(assetsDir, abs).split(sep).join("/")
+      out.push({ path, sha256: new Bun.CryptoHasher("sha256").update(bytes).digest("hex"), size: bytes.length })
+    }
+  }
+}
+
+// The convention-first asset set: everything under the project's assets/
+// folder (next to package.json), collected wholesale in sorted order so the
+// manifest bytes are deterministic. Fonts are annotations pointing into that
+// set: `solidrt.fonts` path entries must live under assets/ so they reach dev
+// clients and the version store (`false` entries only drop pack defaults and
+// have no manifest presence).
+export function collectAssets(entry: string): { assets: ManifestAsset[]; fonts: ManifestFont[] } {
+  let project = findProjectPackage(entry)
+  let projectDir = projectDirFor(entry)
+  let assetsDir = resolve(projectDir, "assets")
+
+  let assets: ManifestAsset[] = []
+  if (existsSync(assetsDir) && statSync(assetsDir).isDirectory()) {
+    walkAssets(assetsDir, assetsDir, assets)
+    assets.sort((a, b) => (a.path < b.path ? -1 : 1))
+  }
+
+  let fonts: ManifestFont[] = []
+  let map = project?.pkg.solidrt?.fonts
+  if (map && typeof map === "object" && !Array.isArray(map)) {
+    for (let [alias, value] of Object.entries(map)) {
+      if (typeof value !== "string") continue
+      let path = assetPathFor(projectDir, resolve(projectDir, value))
+      if (!path) {
+        fail(`"solidrt.fonts": "${alias}": ${value} must live under assets/ (fonts ship as version assets)`)
+      }
+      if (!assets.some((a) => a.path === path)) {
+        fail(`"solidrt.fonts": "${alias}": no such file: ${resolve(projectDir, value)}`)
+      }
+      fonts.push({ path, alias })
+    }
+  }
+  return { assets, fonts }
+}
+
+// Resolve the app identity for a pack. All three fields are guaranteed
+// non-empty and 255 bytes max (the trailer encoding's length prefix).
+export function loadAppIdentity(sourcePath: string): AppIdentity {
+  let project = findProjectPackage(sourcePath)
+  let config = project?.pkg.solidrt ?? {}
+  let fallbackName = project?.pkg.name ?? basename(sourcePath).replace(/\.[jt]sx?$/, "")
+
+  for (let key of ["appId", "org", "displayName"]) {
+    if (key in config && typeof config[key] !== "string") fail(`"solidrt": "${key}" must be a string`)
+  }
+
+  let appId: string
+  let defaulted = typeof config.appId !== "string"
+  if (defaulted) {
+    appId = sanitizeAppId(fallbackName)
+  } else {
+    appId = config.appId
+    if (!APP_ID_PATTERN.test(appId) || appId === "." || appId === "..") {
+      fail(`"solidrt": "appId" must match ${APP_ID_PATTERN} (reverse-DNS recommended, e.g. "com.example.app")`)
+    }
+  }
+  let displayName = config.displayName ?? (project?.pkg.name || fallbackName)
+  let org = config.org ?? displayName
+  checkField(appId, '"appId"')
+  checkField(displayName, '"displayName"')
+  checkField(org, '"org"')
+  return { appId, org, displayName, defaulted }
+}