@k2b/cloud 0.6.0 → 0.8.0

package/README.md

@@ -78,9 +78,9 @@ A standard app declares four prefixes (`/api/<id>`, `/app/<id>`, `/admin/<id>`,
 
 ## Documentation
 
-Full walkthroughs, the per-app anatomy, deployment templates, and a reference app:
+Application setup, public contracts, and deployment guidance:
 
-- **[github.com/ValentinKolb/cloud-template](https://github.com/ValentinKolb/cloud-template)** — starter repo with a working reference app + the complete app-authoring guide
+- **[Create the first application](https://github.com/k2b-dev/cloud/blob/main/docs-site/docs/en/build/getting-started.md)** — standalone project setup and a verified API endpoint
 - **[github.com/k2b-dev/cloud](https://github.com/k2b-dev/cloud)** — the platform monorepo (gateway, core, all platform apps)
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.6.0",
-  "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
+  "version": "0.8.0",
+  "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
     "type": "git",
@@ -18,7 +18,9 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.integration.test.ts",
-    "!scripts/**/*.test.ts"
+    "!src/**/*.test-fixture.ts",
+    "!scripts/**/*.test.ts",
+    "!scripts/runtime-recovery-*.ts"
   ],
   "exports": {
     ".": "./src/index.ts",
@@ -31,9 +33,13 @@
     "./browser/live": "./src/browser/live-websocket.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
+    "./browser/commands": "./src/browser/commands.ts",
+    "./browser/search": "./src/browser/search.ts",
+    "./browser/testing": "./src/browser/testing.ts",
     "./browser/resource-picker": "./src/browser/resource-picker.tsx",
     "./capabilities": "./src/capabilities/client.ts",
     "./capabilities/server": "./src/capabilities/server.ts",
+    "./capabilities/store": "./src/capabilities/executions.ts",
     "./capabilities/testing": "./src/capabilities/testing.ts",
     "./cli": "./src/cli/index.ts",
     "./cli/access": "./src/cli/access.ts",
@@ -59,6 +65,7 @@
     "./access/ui": "./src/access/ui.ts",
     "./ssr": "./src/ssr/index.ts",
     "./ssr/islands": "./src/ssr/islands/index.ts",
+    "./ssr/WorkspaceNavigation.island": "./src/ssr/WorkspaceNavigation.island.tsx",
     "./ssr/*": "./src/ssr/*",
     "./config": "./src/config/index.ts",
     "./config/*": "./src/config/*",
@@ -77,19 +84,22 @@
     "./styles/global.css": "./src/styles/global.css"
   },
   "scripts": {
-    "test": "bun test",
-    "typecheck": "tsc -p tsconfig.json --noEmit --pretty false 2>&1 | grep -v node_modules | (! grep -q 'error TS')"
+    "test": "bun test --isolate --path-ignore-patterns '**/*.behavior.test.tsx' --path-ignore-patterns '**/*.dom.test.tsx' && bun run test:dom",
+    "test:dom": "bun test --isolate --conditions=browser --preload ../ui/test/solid-dom-preload.ts behavior.test.tsx dom.test.tsx",
+    "typecheck": "tsc -p tsconfig.json --noEmit --pretty false"
   },
   "dependencies": {
     "@firecrawl/anydoc": "0.1.9",
+    "@napi-rs/canvas": "1.0.8",
+    "pdfjs-dist": "6.3.289",
     "@hono/standard-validator": "0.2.2",
     "@simplewebauthn/server": "13.3.2",
     "@tabler/icons": "3.46.0",
     "@tailwindcss/typography": "0.5.20",
-    "@k2b/nessi": "0.11.0",
-    "@k2b/ssr": "0.12.0",
-    "@k2b/ui": "0.2.0",
-    "@k2b/stdlib": "0.22.0",
+    "@k2b/nessi": "0.12.0",
+    "@k2b/ssr": "0.14.0",
+    "@k2b/ui": "0.4.0",
+    "@k2b/stdlib": "0.25.0",
     "@k2b/sync": "6.4.0",
     "@nats-io/transport-node": "3.4.0",
     "@modelcontextprotocol/sdk": "1.30.0",
@@ -107,6 +117,7 @@
     "seroval": "1.6.0",
     "tailwindcss": "4.3.3",
     "web-push": "3.6.7",
+    "web-vitals": "6.2.1",
     "yaml": "2.9.0",
     "hash-wasm": "4.12.0",
     "@types/nodemailer": "7.0.12",
@@ -116,12 +127,12 @@
   "devDependencies": {
     "@babel/core": "7.29.7",
     "@babel/preset-typescript": "7.29.7",
-    "@types/bun": "1.3.14",
+    "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.12",
     "hono": "4.12.32",
     "solid-js": "1.9.14",
     "typescript": "5.9.3",
-    "zod": "4.4.3"
+    "zod": "4.6.2"
   },
   "peerDependencies": {
     "hono": "^4.12.25",

package/scripts/README.md

@@ -0,0 +1,10 @@
+# Cloud platform scripts
+
+- `build.ts` — production build for one Cloud app (`APP_ID`); used by the Dockerfiles and `bun run build` targets.
+- `preload.ts` — dev-mode preload that registers the SSR plugin and builds CSS before app code loads.
+- `build-pdf-renderer.ts` — packages the PDF decoder and native assets for bundles that import PDF vision.
+- `app-favicon.ts` — generates app favicons from Tabler icons; imported by `build.ts` and `preload.ts`.
+- `browser-performance.ts` — bundles the web-vitals browser asset for core; imported by `build.ts` and `preload.ts`.
+- `runtime-recovery-acceptance.ts` — shared-runtime recovery acceptance on disposable Docker containers: `bun packages/cloud/scripts/runtime-recovery-acceptance.ts` (also `bun run test:runtime-recovery`).
+- `runtime-recovery-worker.ts` — the containerized fixture started by `runtime-recovery-acceptance.ts`; not run directly.
+- `sync-recovery-smoke.ts` — two-phase NATS recovery smoke: `bun packages/cloud/scripts/sync-recovery-smoke.ts prepare --namespace cloud-recovery-smoke-<unique>`, restart the fleet, then `... recover --namespace <same>`.

package/scripts/browser-performance.ts

@@ -0,0 +1,14 @@
+import { resolve } from "node:path";
+import { WEB_VITALS_ASSET_NAME } from "../src/_internal/web-vitals-asset";
+
+export async function buildBrowserPerformance(publicDir: string, appId: string): Promise<void> {
+  if (appId !== "core") return;
+  const result = await Bun.build({
+    entrypoints: [resolve(import.meta.dir, "../src/browser/web-vitals.ts")],
+    outdir: publicDir,
+    naming: WEB_VITALS_ASSET_NAME,
+    target: "browser",
+    minify: true,
+  });
+  if (!result.success) throw new AggregateError(result.logs, "Browser performance build failed");
+}

package/scripts/build-pdf-renderer.ts

@@ -0,0 +1,39 @@
+import { cp, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+/** Package the decoder and native assets only for bundles importing PDF vision. */
+export async function buildPdfRenderer(dist: string) {
+  const framework = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const out = resolve(dist, "pdf-render");
+  await mkdir(out, { recursive: true });
+  const worker = await Bun.build({
+    entrypoints: [resolve(framework, "src/ai/pdf-render-worker.ts")],
+    target: "bun",
+    outdir: out,
+    naming: "worker.js",
+    external: ["pdfjs-dist", "@napi-rs/canvas"],
+  });
+  if (!worker.success) throw new Error(`PDF decoder build failed: ${worker.logs.join("\n")}`);
+  for (const name of ["pdfjs-dist", "@napi-rs/canvas"]) {
+    const source = dirname(Bun.resolveSync(`${name}/package.json`, framework));
+    await cp(source, resolve(out, "node_modules", name), { recursive: true, dereference: true });
+    if (name !== "@napi-rs/canvas") continue;
+    const manifest = z
+      .object({ optionalDependencies: z.record(z.string(), z.string()) })
+      .parse(await Bun.file(resolve(source, "package.json")).json());
+    let nativePackages = 0;
+    for (const dependency of Object.keys(manifest.optionalDependencies)) {
+      let location: string;
+      try {
+        location = dirname(Bun.resolveSync(`${dependency}/package.json`, source));
+      } catch {
+        continue;
+      } // Only the installed target-platform binary is needed.
+      await cp(location, resolve(out, "node_modules", dependency), { recursive: true, dereference: true });
+      nativePackages++;
+    }
+    if (!nativePackages) throw new Error("PDF decoder needs an installed native canvas binary for the build platform.");
+  }
+}

package/scripts/build.ts

@@ -4,11 +4,11 @@
  * Two consumer shapes:
  *
  *   Monorepo (this repo):
- *     APP_ID=<id> bun run packages/cloud/scripts/build.ts
+ *     NODE_ENV=production APP_ID=<id> bun run packages/cloud/scripts/build.ts
  *     # appDir defaults to packages/<APP_ID>, run from workspace root.
  *
  *   Standalone (npm consumer, see cloud-template):
- *     APP_ID=<id> APP_DIR=. bun run node_modules/@k2b/cloud/scripts/build.ts
+ *     NODE_ENV=production APP_ID=<id> APP_DIR=. bun run node_modules/@k2b/cloud/scripts/build.ts
  *     # appDir = APP_DIR (resolved against cwd) and must be the directory
  *     # that CONTAINS src/, since entrypoints resolve to <appDir>/src/*.
  *
@@ -22,20 +22,21 @@
  * it ships a `scripts/build-extras.ts` that this script runs at the end.
  */
 import { existsSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { brotliCompress, gzip, constants as zlibConstants } from "node:zlib";
-import { CryptoHasher, Glob } from "bun";
+import { Glob } from "bun";
 import tailwind from "bun-plugin-tailwind";
 import { writeAppFavicon } from "./app-favicon";
+import { buildBrowserPerformance } from "./browser-performance";
+import { buildPdfRenderer } from "./build-pdf-renderer";
 
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
 
-// `root` = wherever the user is building from. SSR plugin's rootDir is
-// process.cwd() (set in defineApp), so we use the same here for hash parity.
+// Build output is relative to the consuming project, including npm consumers.
 const root = process.cwd();
 
 // Framework dir — works whether this script is in packages/cloud/scripts/
@@ -46,6 +47,10 @@ const release = process.env.CLOUD_RELEASE?.trim() || "local";
 if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(release)) {
   throw new Error(`Invalid CLOUD_RELEASE: ${JSON.stringify(release)}`);
 }
+const version = process.env.CLOUD_VERSION?.trim() || "0.0.0-local";
+if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+  throw new Error(`Invalid CLOUD_VERSION: ${JSON.stringify(version)}`);
+}
 const syncPackagePath = Bun.resolveSync("@k2b/sync/package.json", frameworkDir);
 const syncPackage = JSON.parse(await readFile(syncPackagePath, "utf8")) as {
   version?: unknown;
@@ -59,6 +64,8 @@ const syncVersion = syncPackage.version;
 // convention. Resolved against cwd if relative.
 const appDir = process.env.APP_DIR ? resolve(root, process.env.APP_DIR) : resolve(root, "packages", appId);
 if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DIR or check APP_ID)`);
+// Share the resolved source directory with defineApp before importing config.
+process.env.APP_DIR = appDir;
 
 const dist = resolve(root, "dist");
 const distPublic = resolve(dist, "public");
@@ -68,14 +75,6 @@ const compressGzip = promisify(gzip);
 await rm(dist, { recursive: true, force: true });
 await mkdir(distPublic, { recursive: true });
 
-// Mirrors @k2b/ssr's island-id (md5 of POSIX path relative to the
-// SSR plugin's rootDir, truncated to 12 chars). Both this script and the
-// plugin use process.cwd() as the rootDir, so hashes match.
-const islandId = (file: string): string => {
-  const rel = file.slice(root.length + 1).replace(/\\/g, "/");
-  return new CryptoHasher("md5").update(rel).digest("hex").slice(0, 12);
-};
-
 const compressibleExtensions = new Set([".css", ".html", ".js", ".json", ".map", ".svg", ".txt", ".xml"]);
 
 async function precompressDistAssets(dir: string): Promise<void> {
@@ -124,11 +123,14 @@ try {
     naming: "server.js",
     target: "bun",
     minify: true,
+    metafile: true,
     define: {
+      __CLOUD_VERSION__: JSON.stringify(version),
       __CLOUD_RELEASE__: JSON.stringify(release),
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
+      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./pdf-render/worker.js"),
     },
-    plugins: [plugin()],
+    plugins: [(app?.plugin ?? plugin)()],
   });
 } finally {
   await rm(serverEntry, { force: true });
@@ -137,26 +139,8 @@ if (!server.success) {
   for (const m of server.logs) console.error(m);
   throw new Error("Server bundle failed");
 }
-
-// 1b. The SSR plugin scans the project root and emits one chunk per island
-//     across every reachable package (including any island-shaped files in
-//     other workspace packages or in node_modules). Keep only this app's own
-//     islands plus the framework's; drop the rest. chunk-* files are shared
-//     splits and always kept.
-const ssrDir = resolve(dist, "_ssr");
-if (existsSync(ssrDir)) {
-  const allowedDirs = [frameworkDir, appDir];
-  const allowedIds = new Set<string>();
-  for (const dir of allowedDirs) {
-    for await (const file of new Glob("**/*.{island,client}.tsx").scan({ cwd: dir, absolute: true })) {
-      allowedIds.add(islandId(file));
-    }
-  }
-  for (const entry of await readdir(ssrDir)) {
-    if (entry.startsWith("chunk-") || !entry.endsWith(".js")) continue;
-    const id = entry.slice(0, -3);
-    if (!allowedIds.has(id)) await rm(resolve(ssrDir, entry));
-  }
+if (Object.keys(server.metafile?.inputs ?? {}).some((path) => path.endsWith("/ai/pdf-render.ts"))) {
+  await buildPdfRenderer(dist);
 }
 
 // 2. Per-app Tailwind stylesheet.
@@ -199,6 +183,7 @@ if (existsSync(extras)) {
   await import(extras);
 }
 
+await buildBrowserPerformance(distPublic, appId);
 await precompressDistAssets(resolve(dist, "public"));
 await precompressDistAssets(resolve(dist, "_ssr"));
 

package/scripts/preload.ts

@@ -23,6 +23,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import tailwind from "bun-plugin-tailwind";
 import { writeAppFavicon } from "./app-favicon";
+import { buildBrowserPerformance } from "./browser-performance";
 
 const appId = process.env.APP_ID ?? "core";
 
@@ -38,9 +39,11 @@ const frameworkDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // convention. Resolved against cwd if relative.
 const appDir = process.env.APP_DIR ? resolve(root, process.env.APP_DIR) : resolve(root, "packages", appId);
 if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DIR or check APP_ID)`);
+// Share the resolved source directory with defineApp before importing config.
+process.env.APP_DIR = appDir;
 
 const { app, plugin } = await import(resolve(appDir, "src/config"));
-Bun.plugin(plugin());
+Bun.plugin((app?.plugin ?? plugin)());
 
 // ── Build CSS ───────────────────────────────────────────────────────────────
 const publicDir = resolve(root, "public");
@@ -125,19 +128,17 @@ if (appId === "core" && existsSync(globalCssEntry)) {
   await cp(resolve(frameworkDir, "public/logo.svg"), resolve(publicDir, "logo.svg"));
 }
 
-// katex.css is only needed by notebooks (served by core via Traefik /public/katex.css)
-if (appId === "notebooks") {
-  try {
-    await cp(resolve(root, "node_modules/katex/dist/katex.min.css"), resolve(publicDir, "katex.css"));
-  } catch {
-    console.warn("[preload] katex.css not found, skipping");
-  }
-}
-
 // Each app builds its own app.css
 const appPublicDir = resolve(publicDir, appId);
 await mkdir(appPublicDir, { recursive: true });
 
+// Static assets from <appDir>/public, same as step 3 of the production build.
+const appPublicSource = resolve(appDir, "public");
+// A standalone application's public directory can be the serving root itself; never copy a tree into itself.
+if (existsSync(appPublicSource) && appPublicSource !== publicDir && !appPublicDir.startsWith(`${appPublicSource}/`)) {
+  await cp(appPublicSource, appPublicDir, { recursive: true });
+}
+
 if (appId !== "core" && app) {
   await writeAppFavicon({
     publicDir,
@@ -146,9 +147,12 @@ if (appId !== "core" && app) {
   });
 }
 
-await buildAppCss();
+if (existsSync(appCssPath)) {
+  await buildAppCss();
+  watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
+}
+await buildBrowserPerformance(publicDir, appId);
 
-watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
 if (appId === "core" && existsSync(globalCssEntry)) {
   watchDevCss("global.css", [globalCssEntry, resolve(frameworkDir, "src/styles")], buildGlobalCss);
 }

package/scripts/sync-recovery-smoke.ts

@@ -1,14 +1,17 @@
 /**
  * Isolated two-process recovery acceptance for the local NATS cluster.
  *
- * SYNC_RECOVERY_NAMESPACE=cloud-recovery-smoke-<unique> bun packages/cloud/scripts/sync-recovery-smoke.ts prepare
+ * bun packages/cloud/scripts/sync-recovery-smoke.ts prepare --namespace cloud-recovery-smoke-<unique>
  * Stop the application fleet across the printed nextTick boundary, keeping NATS up.
  * Restart the fleet, then run the same command with `recover`.
  * No provider or application-domain effects; successful recovery deletes only
  * the exact test streams after checking their broker identity metadata.
  */
+
+import { parseArgs } from "node:util";
 import { createSync, type SyncResourceSummary, type Worker } from "@k2b/sync";
 import { connect, type NatsConnection } from "@nats-io/transport-node";
+import { env } from "../src/config/env";
 
 const APPLICATION = "cloud-recovery-smoke";
 const JOB_ID = "restart-job";
@@ -48,16 +51,29 @@ const removeTestStreams = async (connection: NatsConnection, namespace: string,
 };
 
 export const main = async (): Promise<void> => {
-  const phase = Bun.argv[2];
+  const { values: options, positionals } = parseArgs({
+    args: Bun.argv.slice(2),
+    allowPositionals: true,
+    options: { namespace: { type: "string" }, help: { type: "boolean", default: false } },
+  });
+  if (options.help) {
+    console.log(`Usage: bun packages/cloud/scripts/sync-recovery-smoke.ts <prepare|recover> --namespace cloud-recovery-smoke-<unique>
+
+Two-phase recovery acceptance against the application's NATS servers (NATS_SERVERS, default nats://127.0.0.1:4222).
+Run "prepare", restart the application fleet while NATS stays up, then run "recover" with the same namespace.
+`);
+    return;
+  }
+  const phase = positionals[0];
   check(phase === "prepare" || phase === "recover", "Pass prepare or recover");
-  const namespace = process.env.SYNC_RECOVERY_NAMESPACE?.trim() ?? "";
-  check(/^cloud-recovery-smoke-[A-Za-z0-9_-]{6,60}$/.test(namespace), "Set a unique SYNC_RECOVERY_NAMESPACE=cloud-recovery-smoke-<suffix>");
-  const servers = (process.env.NATS_SERVERS ?? "nats://127.0.0.1:4222")
+  const namespace = options.namespace?.trim() ?? "";
+  check(/^cloud-recovery-smoke-[A-Za-z0-9_-]{6,60}$/.test(namespace), "Pass a unique --namespace cloud-recovery-smoke-<suffix>");
+  const servers = (env.NATS_SERVERS ?? "nats://127.0.0.1:4222")
     .split(",")
     .map((value) => value.trim())
     .filter(Boolean);
   const connection = await connect({ servers, name: `${APPLICATION}-${phase}`, ignoreClusterUpdates: true });
-  const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: 3 } });
+  const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: env.SYNC_REPLICAS } });
   const job = sync.job<{ preparedAt: string }>({
     id: JOB_ID,
     delivery: { ackWaitMs: 30_000, maxAttempts: 3, backoffMs: [1_000, 2_000] },

package/src/_internal/app-presentation.ts

@@ -11,12 +11,12 @@ const text = (value: string, label: string, max = MAX_SHORT_TEXT): string => {
   return normalized;
 };
 
-const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string) => {
+const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string, max = MAX_SHORT_TEXT) => {
   if (!values) return undefined;
   const normalized: Record<string, string> = {};
   for (const [key, value] of Object.entries(values)) {
     if (!allowed.has(key)) throw new Error(`${label} contains unknown key ${JSON.stringify(key)}`);
-    normalized[key] = text(value, `${label}.${key}`);
+    normalized[key] = text(value, `${label}.${key}`, max);
   }
   return normalized;
 };
@@ -34,6 +34,7 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
     groupIds.add(group.id);
   }
   const adminHrefs = new Set((app.adminNav ?? []).flatMap((group) => group.links.map((link) => link.href)));
+  const searchHrefs = new Set((app.searchLinks ?? []).map((link) => link.href));
   const legalHrefs = new Set((app.legalLinks ?? []).map((link) => link.href));
   const translations: Record<string, AppPresentationTranslation> = {};
 
@@ -49,6 +50,17 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
         : {}),
       ...(translation.adminGroups ? { adminGroups: labels(translation.adminGroups, groupIds, `${canonical}.adminGroups`) } : {}),
       ...(translation.adminLinks ? { adminLinks: labels(translation.adminLinks, adminHrefs, `${canonical}.adminLinks`) } : {}),
+      ...(translation.searchLinks ? { searchLinks: labels(translation.searchLinks, searchHrefs, `${canonical}.searchLinks`) } : {}),
+      ...(translation.searchLinkDescriptions
+        ? {
+            searchLinkDescriptions: labels(
+              translation.searchLinkDescriptions,
+              searchHrefs,
+              `${canonical}.searchLinkDescriptions`,
+              MAX_DESCRIPTION,
+            ),
+          }
+        : {}),
       ...(translation.legalLinks ? { legalLinks: labels(translation.legalLinks, legalHrefs, `${canonical}.legalLinks`) } : {}),
     };
   }

package/src/_internal/build-metadata.ts

@@ -1,9 +1,16 @@
 import type { AppRuntimeMetadata } from "../contracts/registry";
 
+declare const __CLOUD_VERSION__: string;
 declare const __CLOUD_RELEASE__: string;
 declare const __CLOUD_SYNC_VERSION__: string;
 
-export const appRuntimeMetadata: AppRuntimeMetadata = {
+/** Cloud version and release label baked into the bundle by `scripts/build.ts`. */
+export const buildMetadata = {
+  version: typeof __CLOUD_VERSION__ === "string" ? __CLOUD_VERSION__ : "0.0.0-local",
   release: typeof __CLOUD_RELEASE__ === "string" ? __CLOUD_RELEASE__ : "development",
+} as const;
+
+export const appRuntimeMetadata: AppRuntimeMetadata = {
+  ...buildMetadata,
   syncVersion: typeof __CLOUD_SYNC_VERSION__ === "string" ? __CLOUD_SYNC_VERSION__ : "unknown",
 };