@valentinkolb/cloud 0.1.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@valentinkolb/cloud",
+  "version": "0.1.0",
+  "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ValentinKolb/cloud.git",
+    "directory": "packages/cloud"
+  },
+  "homepage": "https://github.com/ValentinKolb/cloud",
+  "bugs": "https://github.com/ValentinKolb/cloud/issues",
+  "type": "module",
+  "files": [
+    "src",
+    "scripts",
+    "public"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./server": "./src/server/index.ts",
+    "./browser": "./src/server/api-client.ts",
+    "./shared": "./src/shared/index.ts",
+    "./services": "./src/services/index.ts",
+    "./services/*": "./src/services/*",
+    "./ssr": "./src/ssr/index.ts",
+    "./ssr/islands": "./src/ssr/islands/index.ts",
+    "./config": "./src/config/index.ts",
+    "./config/*": "./src/config/*",
+    "./contracts": "./src/contracts/index.ts",
+    "./styles/global.css": "./src/styles/global.css"
+  },
+  "scripts": {
+    "typecheck": "node ../../node_modules/typescript/bin/tsc -p tsconfig.typecheck.json --noEmit --pretty false 2>&1 | grep -v node_modules | (! grep -q 'error TS')"
+  },
+  "dependencies": {
+    "@fontsource-variable/jetbrains-mono": "^5.2.8",
+    "@scalar/hono-api-reference": "^0.10.9",
+    "@scalar/openapi-to-markdown": "^0.5.6",
+    "@tabler/icons-webfont": "^3.36.1",
+    "@valentinkolb/ssr": "0.9.0",
+    "@valentinkolb/stdlib": "0.3.0",
+    "@valentinkolb/sync": "^5.0.0",
+    "hono": "^4.11.1",
+    "hono-openapi": "^1.1.2",
+    "katex": "^0.16.28",
+    "marked": "^17.0.1",
+    "mermaid": "^11.12.2",
+    "mustache": "^4.2.0",
+    "nodemailer": "^7.0.12",
+    "sanitize-html": "^2.17.0",
+    "solid-js": "^1.9.10",
+    "zod": "^4.3.4"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/preset-typescript": "^7.28.5",
+    "@tailwindcss/typography": "^0.5.19",
+    "@types/bun": "1.3.9",
+    "@types/mustache": "^4.2.6",
+    "@types/nodemailer": "^7.0.5",
+    "@types/sanitize-html": "^2.16.0",
+    "babel-preset-solid": "^1.9.10",
+    "bun-plugin-tailwind": "^0.1.2",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3"
+  }
+}

package/public/logo.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;"><rect id="ArtBoard1" x="0" y="0" width="24" height="24" style="fill:none;"/><g id="ArtBoard11" serif:id="ArtBoard1"><path d="M9.974,4.062c2.269,-0.689 4.771,-0.231 6.574,1.216c1.433,1.145 2.262,2.777 2.328,4.486l0.003,0.219l0.094,0.004c2.378,0.11 4.283,2.027 4.394,4.414l0.004,0.218c-0,2.488 -1.949,4.519 -4.399,4.633l-0.217,0.005l-12.278,-0l-0.23,-0.008c-3.039,-0.114 -5.496,-2.48 -5.613,-5.441l-0.005,-0.223c0,-2.84 2.15,-5.179 4.945,-5.6l0.118,-0.016l0.073,-0.187c0.685,-1.675 2.125,-3.004 3.958,-3.637l0.252,-0.083l-0.001,0Z" style="fill:url(#_Linear1);fill-rule:nonzero;"/><path d="M0.156,13.767l-0.001,-0.019l-0.005,-0.205l-0,-0.026c-0,-3.044 2.204,-5.581 5.143,-6.192c0.789,-1.718 2.309,-3.082 4.227,-3.743c-0.121,0.041 0.018,-0.007 0.018,-0.007l0.231,-0.076l0.024,-0.007c2.464,-0.749 5.179,-0.246 7.138,1.326c1.439,1.15 2.321,2.745 2.528,4.443c2.416,0.425 4.269,2.487 4.386,5.006l0.001,0.029l0.004,0.2l-0.034,0.035l-0.009,0.029l0.043,-0.043c0,2.864 -2.245,5.2 -5.066,5.331l-0.039,0.001l-0.21,0.005l-11.878,0c0.097,0 0.097,-0.015 0,0l-0.222,-0.008l-0.032,-0.001c-3.389,-0.126 -6.117,-2.777 -6.247,-6.078Zm9.088,-9.164c-0.161,0.076 -0.094,0.044 -0.232,0.109c-1.411,0.656 -2.482,1.819 -3.044,3.191l-0.07,0.181c0,0 -0.57,0.103 -0.943,0.204c-2.31,0.624 -3.955,2.77 -3.955,5.229l0.005,0.216c0.01,0.259 0.039,0.514 0.085,0.762c0,0 0.008,0.083 0.016,0.082c0.495,2.458 2.684,4.32 5.329,4.419l0.016,0.001l0.002,0l0.204,0.007l0.013,-0c0.324,0.047 11.865,-0 11.865,-0l0.21,-0.005c2.37,-0.11 4.255,-2.075 4.255,-4.482l-0.004,-0.211c-0.107,-2.309 -1.95,-4.163 -4.25,-4.27l-0.091,-0.003l-0.003,-0.212c-0.064,-1.654 -0.866,-3.232 -2.252,-4.34c-1.745,-1.4 -4.164,-1.843 -6.359,-1.176l-0.244,0.08c-0.189,0.065 -0.375,0.134 -0.553,0.218Z" style="fill:url(#_Linear2);"/></g><defs><linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(0.28477,14.9308,-14.9308,0.28477,12.4271,4.32609)"><stop offset="0" style="stop-color:#f0f6ff;stop-opacity:1"/><stop offset="1" style="stop-color:#5a9cff;stop-opacity:1"/></linearGradient><linearGradient id="_Linear2" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(1.11193e-15,18.1593,-18.1593,1.11193e-15,12,1.69474)"><stop offset="0" style="stop-color:#a6d1ff;stop-opacity:1"/><stop offset="1" style="stop-color:#1f8bff;stop-opacity:1"/></linearGradient></defs></svg>

package/scripts/build.ts

@@ -0,0 +1,113 @@
+/**
+ * Production build for a single app.
+ *
+ *   APP_ID=<id> bun run packages/cloud/scripts/build.ts
+ *
+ * Output goes to /<workspace-root>/dist:
+ *   server.js            bundled Bun entry
+ *   _ssr/<island>.js     hydration bundles (auto-emitted by the SSR plugin)
+ *   public/<id>/app.css  Tailwind, if the app has src/styles/app.css
+ *   public/<id>/...      anything from packages/<id>/public/
+ *
+ * If the app needs additional artefacts (core's global.css, logo, katex),
+ * it ships a `scripts/build-extras.ts` that this script runs at the end.
+ */
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import tailwind from "bun-plugin-tailwind";
+import { Glob, CryptoHasher } from "bun";
+
+// Mirrors @valentinkolb/ssr's island-id (md5 of POSIX path relative to the
+// SSR plugin's rootDir, truncated to 12 chars). define-app sets rootDir to
+// the `packages` directory.
+const ssrRootDir = "packages";
+const islandId = (file: string): string => {
+  const rel = file.slice(root.length + 1 + ssrRootDir.length + 1).replace(/\\/g, "/");
+  return new CryptoHasher("md5").update(rel).digest("hex").slice(0, 12);
+};
+
+const appId = process.env.APP_ID;
+if (!appId) throw new Error("APP_ID env var required");
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const appDir = resolve(root, "packages", appId);
+if (!existsSync(appDir)) throw new Error(`Unknown app: ${appId} (no packages/${appId})`);
+
+const dist = resolve(root, "dist");
+const distPublic = resolve(dist, "public");
+
+await rm(dist, { recursive: true, force: true });
+await mkdir(distPublic, { recursive: true });
+
+// Register the app's SSR plugin (Solid JSX transform + island bundler).
+const { plugin } = await import(`../../${appId}/src/config`);
+
+// 1. Server entry — also emits dist/_ssr/<island>.js via the SSR plugin.
+const server = await Bun.build({
+  entrypoints: [resolve(appDir, "src/index.ts")],
+  outdir: dist,
+  naming: "server.js",
+  target: "bun",
+  minify: true,
+  plugins: [plugin()],
+});
+if (!server.success) {
+  for (const m of server.logs) console.error(m);
+  throw new Error("Server bundle failed");
+}
+
+// 1b. The SSR plugin scans the workspace root and emits one chunk per
+//     island/client file across every package. Drop the ones from other apps
+//     so this image only carries its own + the framework's. Chunk files
+//     (chunk-<hash>.js) are shared splits and always kept.
+const ssrDir = resolve(dist, "_ssr");
+if (existsSync(ssrDir)) {
+  const allowedDirs = [resolve(root, "packages/cloud"), 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));
+  }
+}
+
+// 2. Per-app Tailwind stylesheet.
+const appCss = resolve(appDir, "src/styles/app.css");
+if (existsSync(appCss)) {
+  const out = resolve(distPublic, appId);
+  await mkdir(out, { recursive: true });
+  const css = await Bun.build({
+    entrypoints: [appCss],
+    outdir: out,
+    naming: "app.css",
+    root,
+    plugins: [tailwind],
+  });
+  if (!css.success) {
+    for (const m of css.logs) console.error(m);
+    throw new Error("App CSS build failed");
+  }
+}
+
+// 3. Per-app static assets.
+const appPublic = resolve(appDir, "public");
+if (existsSync(appPublic)) {
+  await cp(appPublic, resolve(distPublic, appId), { recursive: true });
+}
+
+// 4. Optional app-specific extras (e.g. core's global.css + logo + katex).
+const extras = resolve(appDir, "scripts/build-extras.ts");
+if (existsSync(extras)) {
+  process.env.WORKSPACE_ROOT = root;
+  process.env.DIST_DIR = dist;
+  await import(extras);
+}
+
+console.log(`Built ${appId} → ${dist}`);

package/scripts/preload.ts

@@ -0,0 +1,73 @@
+/**
+ * Preload script for dev mode.
+ * Registers the SSR plugin (Solid.js JSX transform + island bundling)
+ * and builds CSS before any app code is imported.
+ *
+ * Uses bun-plugin-tailwind with root=workspaceRoot so the oxide scanner
+ * uses /app as projectRoot → auto-detect scans all packages → all classes generated.
+ * No @source directives needed in CSS files.
+ */
+import tailwind from "bun-plugin-tailwind";
+import { cp, mkdir } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const appId = process.env.APP_ID ?? "core";
+const { plugin } = await import(`../../${appId}/src/config`);
+Bun.plugin(plugin());
+
+// ── Build CSS ───────────────────────────────────────────────────────────────
+const workspaceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const publicDir = resolve(workspaceRoot, "public");
+await mkdir(publicDir, { recursive: true });
+
+// global.css + branding are only served by core (Traefik routes them there)
+if (appId === "core") {
+  // Use styles.css at workspace root as entrypoint so the oxide scanner
+  // walks up to /app/package.json and scans ALL packages for utility classes.
+  // (If the CSS file is inside packages/lib/, it only scans packages/lib/.)
+  await Bun.build({
+    entrypoints: [resolve(workspaceRoot, "styles.css")],
+    outdir: publicDir,
+    naming: "global.css",
+    plugins: [tailwind],
+  });
+
+  // Default branding asset: copy the tracked logo.svg into the runtime
+  // public dir so serveBranding can fall back to it when no admin-uploaded
+  // logo (data URI) is configured. User uploads are stored as base64 data
+  // URIs in settings — no image processing (sharp etc.) needed.
+  await cp(
+    resolve(workspaceRoot, "packages/cloud/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(workspaceRoot, "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 appCssPath = resolve(workspaceRoot, `packages/${appId}/src/styles/app.css`);
+const appPublicDir = resolve(publicDir, appId);
+await mkdir(appPublicDir, { recursive: true });
+
+// `naming: "app.css"` is essential — without it, Bun.build with `root: workspaceRoot`
+// preserves the directory structure (packages/<id>/src/styles/app.css) inside outdir,
+// so Layout's `<link href="/public/<id>/app.css">` 404s and only global.css's classes
+// reach the browser. That's why responsive grid utilities went missing on dashboard.
+await Bun.build({
+  entrypoints: [appCssPath],
+  outdir: appPublicDir,
+  naming: "app.css",
+  root: workspaceRoot, // same: auto-detect from /app
+  plugins: [tailwind],
+});

package/src/_internal/define-app.ts

@@ -0,0 +1,399 @@
+/**
+ * defineApp() — The single entry point for every cloud app.
+ *
+ * Merges SSR config, app meta, and server bootstrap into one call.
+ * Returns `{ ssr, plugin, config, meta, start }`.
+ */
+import { createConfig as createSsrConfig } from "@valentinkolb/ssr";
+import { createSSRHandler, routes } from "@valentinkolb/ssr/hono";
+import { Hono } from "hono";
+import { serveStatic } from "hono/bun";
+import type { SsrConfig } from "@valentinkolb/ssr";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AppMeta,
+  AppLifecycle,
+  AppCapabilities,
+  AppSearchContext,
+  CloudContext,
+} from "../contracts/app";
+import type { AppRegistryEntry } from "../contracts/registry";
+import type { Role } from "../contracts/shared";
+import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
+import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
+import { loadSnapshot } from "../services/settings/snapshot";
+import { registerSettings, type SettingDef } from "../services/settings/defaults";
+import { auth } from "../server/middleware/auth";
+import { logger } from "../services/logging";
+import { get, set, loadCache as loadSettingsCache } from "../services/settings";
+import { appRegistry, listApps } from "./registry";
+import { createHeartbeat } from "./heartbeat";
+import { buildRuntimeFromRegistry } from "./runtime-context";
+
+/** Cache-busting version stamp — changes on every server start / rebuild. */
+const v = Date.now();
+
+type PageOptions = {
+  title?: string;
+  description?: string;
+  theme?: "light" | "dark";
+};
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+/**
+ * App definition options.
+ *
+ * `S` is the inferred per-app settings map (see `AppSettingsMap`). Apps that
+ * declare `settings: { ... } as const` get S inferred to the literal shape;
+ * `AppContext<typeof app>` then exposes the typed snapshot on `c.get("settings")`.
+ *
+ * Apps that omit `settings` get S = {} (no own settings — only core's are
+ * available in their snapshot, populated by core's own defineApp.settings).
+ */
+export type AppOptions<S extends AppSettingsMap = {}> = {
+  id: string;
+  name: string;
+  icon: string;
+  description: string;
+  /** URL prefix for SSR asset isolation. Omit for the global `/_ssr/` path (core). */
+  basePath?: string;
+  /** Base URL as seen by other containers (e.g. "http://app-notebooks:3000"). */
+  baseUrl: string;
+  adminHref?: string;
+  nav?: {
+    href: string;
+    match?: string;
+    section: "primary" | "more" | "hidden";
+    requiresAuth?: boolean;
+    requiresRoles?: Role[];
+  };
+  /**
+   * Settings owned by this app, declared as a map of dotted-key → definition.
+   *
+   * Example: `{ "files.filegate_url": { kind: "url", default: "" } }`.
+   *
+   * These keys are exposed as a typed nested snapshot on `c.get("settings")`
+   * for any Hono route using `Hono<AppContext<typeof app>>`. Writes go through
+   * `app.settings.set(key, value)` (also typed). The runtime registry
+   * (`SETTINGS_MAP` in `services/settings/defaults.ts`) is populated from
+   * this map automatically on `defineApp()` call.
+   */
+  settings?: S;
+  /**
+   * Legal/info links contributed by this app — aggregated app-wide via
+   * `listLegalLinks()` and rendered in login footer, app Footer, rail more
+   * dropdown. Each app contributes its own (e.g. settings owns
+   * Imprint/Privacy/Terms; faq owns FAQ). KISS: no `external` flag, links
+   * always open in a new tab from the login footer.
+   */
+  legalLinks?: ReadonlyArray<{ label: string; href: string; icon?: string }>;
+  /**
+   * Dashboard widget endpoints this app exposes. Each entry references an
+   * HTTP path on this app that returns a `WidgetResponse`. The dashboard
+   * fetches them with the user's cookie forwarded; the endpoint is
+   * responsible for permission gating (200 = render, 204 = skip silently).
+   */
+  widgets?: ReadonlyArray<{ id: string; path: string }>;
+  /**
+   * Top-level URL prefixes the gateway should route to this app.
+   *
+   * Standard apps follow a four-prefix convention:
+   *   `/api/<id>`     — widget, admin, ws, crud — everything HTTP API
+   *   `/app/<id>`     — user-facing SSR pages
+   *   `/admin/<id>`   — admin SSR pages
+   *   `/public/<id>`  — built CSS and other static assets
+   *
+   * Apps with non-standard URLs (core's `/auth`, `/me`; oauth's `/oauth`,
+   * `/.well-known/...`; settings' `/legal/*`, `/impressum`) list whatever
+   * top-level paths they own. The gateway is dumb — it just builds a
+   * prefix-trie from these strings.
+   */
+  routes: readonly string[];
+};
+
+export type StartOptions = {
+  routes: {
+    api?: Hono<any>;
+    pages?: Hono<any>;
+  };
+  lifecycle?: AppLifecycle;
+  capabilities?: AppCapabilities;
+  port?: number;
+  skipSetup?: boolean;
+};
+
+export type StartResult = {
+  port: number;
+  fetch: Hono["fetch"];
+};
+
+export type AppDefinition<S extends AppSettingsMap = {}> = {
+  // Bind the generic explicitly — without it, ssr collapses to the constraint
+  // `object` and apps lose the typed `c.get("page")` (title/description/theme).
+  ssr: ReturnType<typeof createSSRHandler<PageOptions>>;
+  plugin: () => import("bun").BunPlugin;
+  config: SsrConfig;
+  meta: AppMeta;
+  baseUrl: string;
+  start: (opts: StartOptions) => Promise<StartResult>;
+  /**
+   * Phantom field — type-only carrier for the per-app settings shape. Always
+   * `undefined` at runtime; do not read or assign. Used by `AppContext<App>`
+   * to extract the inferred settings map via `App["_settings"]`.
+   */
+  readonly _settings: S;
+  /**
+   * Typed async settings API for this app. Keys constrained to those declared
+   * in `defineApp({ settings: ... })`. Backed by Redis cache-aside (see store.ts).
+   *
+   * Use for read/write outside of request-scoped sync access. Inside HTTP
+   * handlers, prefer `c.get("settings").x.y` (the per-request snapshot, sync,
+   * frozen for the duration of the request).
+   */
+  readonly settings: SettingsAPI<{ [K in keyof S]: KindToType<S[K]["kind"]> }>;
+};
+
+// ── Implementation ──────────────────────────────────────────────────────────
+
+export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<S>): AppDefinition<S> => {
+  // ── 0. Register declared settings into the runtime registry ──────────
+  // SETTINGS_MAP is the single source of truth for validation in store.ts
+  // (writeKey checks SETTINGS_MAP.get(key)) and for snapshot.ts (allKnownKeys
+  // returns SETTINGS.map(d => d.key)). Without this registration, app-declared
+  // settings would be type-known but runtime-unknown.
+  if (opts.settings) {
+    const legacyDefs: SettingDef[] = Object.entries(opts.settings).map(([key, def]) => {
+      const d = def as Record<string, unknown>;
+      return {
+        key,
+        // Group derived from the dotted prefix (admin UIs use this for tab
+        // grouping; the new bespoke admin UIs ignore it but legacy paths use it).
+        group: key.split(".")[0] ?? "app",
+        kind: d.kind as SettingDef["kind"],
+        // The cast loses the per-kind discriminated default type but the data
+        // is correct; legacy validateSettingValue re-validates against kind anyway.
+        default: d.default as never,
+        label: d.label as string | undefined,
+        description: (d.description as string | undefined) ?? "",
+        placeholder: d.placeholder as string | undefined,
+        envFallback: d.envFallback as (() => unknown) | undefined,
+        envBootstrap: d.envBootstrap as (() => unknown) | undefined,
+        templateVars: d.templateVars as readonly string[] | undefined,
+        options: d.options as ReadonlyArray<{ value: string; label: string }> | undefined,
+        min: d.min as number | undefined,
+        max: d.max as number | undefined,
+      } as SettingDef;
+    });
+    registerSettings(legacyDefs);
+  }
+
+  // ── 1. SSR config ─────────────────────────────────────────────────────
+  const { config, plugin, html } = createSsrConfig<PageOptions>({
+    dev: process.env.NODE_ENV !== "production",
+    verbose: true,
+    rootDir: resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."),
+    basePath: opts.basePath,
+    template: ({ body, scripts, title, description, theme }) => {
+      const themeFixed = theme !== undefined;
+      return `<!DOCTYPE html>
+<html lang="de" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}>
+  <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="view-transition" content="same-origin">
+    <title>${title ?? "Cloud"}</title>
+    <meta name="description" content="${description ?? "Cloud workspace"}">
+    <meta name="theme-color" content="#09090b">
+    <meta name="mobile-web-app-capable" content="yes">
+    <link rel="icon" href="/branding/favicon">
+    <link rel="stylesheet" href="/public/global.css?v=${v}">
+    <link rel="stylesheet" href="/public/${opts.id}/app.css?v=${v}">
+    <script>
+      (function() {
+        var el = document.documentElement;
+        if (!el.hasAttribute('data-theme-fixed')) {
+          var theme = document.cookie.match(/theme=([^;]+)/)?.[1] || 'light';
+          el.classList.add(theme);
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    ${body}
+  </body>
+  ${scripts}
+</html>`;
+    },
+  });
+
+  // Pass PageOptions explicitly so c.get("page") in apps' SSR handlers is
+  // typed as Partial<PageOptions> (with title/description/theme), not the
+  // bare `object` fallback the constraint would otherwise produce.
+  const ssr = createSSRHandler<PageOptions>(html);
+
+  // ── 2. Meta ───────────────────────────────────────────────────────────
+  const meta: AppMeta = {
+    id: opts.id,
+    name: opts.name,
+    icon: opts.icon,
+    description: opts.description,
+    adminHref: opts.adminHref,
+    routes: [...opts.routes],
+    nav: opts.nav,
+    legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
+    widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
+  };
+
+  // ── 3. start() — builds and boots the Hono server ────────────────────
+  const start = async (startOpts: StartOptions): Promise<StartResult> => {
+    const port = startOpts.port ?? 3000;
+    const baseUrl = opts.baseUrl;
+    const log = logger("app");
+
+    // Registry entry
+    const entry: AppRegistryEntry = {
+      id: meta.id,
+      name: meta.name,
+      icon: meta.icon,
+      description: meta.description,
+      baseUrl,
+      routes: [...meta.routes],
+      nav: (meta.nav || meta.adminHref)
+        ? {
+            href: meta.nav?.href ?? "",
+            match: meta.nav?.match,
+            section: meta.nav?.section ?? "hidden",
+            requiresAuth: meta.nav?.requiresAuth,
+            requiresRoles: meta.nav?.requiresRoles,
+            adminHref: meta.adminHref,
+          }
+        : undefined,
+      search: startOpts.capabilities?.search
+        ? {
+            tags: [...(startOpts.capabilities.search.tags ?? [])],
+            help: startOpts.capabilities.search.help ?? "",
+            tagHelp: [...(startOpts.capabilities.search.tagHelp ?? [])],
+            endpoint: `${baseUrl}/api/_internal/search`,
+          }
+        : undefined,
+      legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
+      widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
+    };
+
+    // Heartbeat
+    const heartbeat = createHeartbeat(meta.id, entry);
+    await heartbeat.start();
+    log.info(`Registered "${meta.id}"`, { baseUrl });
+
+    // Runtime context (navigation, app discovery)
+    const ac = new AbortController();
+    let currentRuntime = buildRuntimeFromRegistry(await listApps());
+
+    const refreshRuntime = async () => {
+      currentRuntime = buildRuntimeFromRegistry(await listApps());
+    };
+
+    (async () => {
+      try {
+        const snap = await appRegistry.snapshot({ prefix: "apps/" });
+        for await (const ev of appRegistry.reader({ prefix: "apps/", after: snap.cursor }).stream({ signal: ac.signal })) {
+          if (ev.type === "overflow") {
+            await refreshRuntime();
+            continue;
+          }
+          await refreshRuntime();
+        }
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") return;
+        log.error("Registry watcher failed", { error: err instanceof Error ? err.message : String(err) });
+      }
+    })();
+
+    // Build Hono server
+    const ssrMountPath = config.basePath ? `${config.basePath}/_ssr` : "/_ssr";
+
+    // Per-request settings snapshot: skip static-asset paths so each /public,
+    // /branding, /favicon, /_ssr request isn't paying the snapshot cost.
+    const SNAPSHOT_SKIP_PREFIXES = ["/public/", "/_ssr/", "/branding/", "/favicon"];
+
+    const server = new Hono()
+      .use("*", async (c, next) => {
+        (c as any).set("runtime", currentRuntime);
+        const path = c.req.path;
+        const skip = SNAPSHOT_SKIP_PREFIXES.some((p) => path.startsWith(p));
+        if (!skip) {
+          (c as any).set("settings", await loadSnapshot());
+        }
+        await next();
+      })
+      .route(ssrMountPath, routes(config))
+      .use("/public/*", serveStatic({
+        root: "./",
+        onFound: (_path, c) => {
+          c.header("Cache-Control", "public, max-age=31536000, immutable");
+        },
+      }));
+
+    // Mount app routes
+    if (startOpts.routes.api) server.route("/api", startOpts.routes.api);
+    if (startOpts.routes.pages) server.route("/", startOpts.routes.pages);
+
+    // Internal search endpoint
+    if (startOpts.capabilities?.search) {
+      const searchRun = startOpts.capabilities.search.run;
+      server.post("/api/_internal/search", auth.requireRole("authenticated"), async (c) => {
+        const body = await c.req.json<{ query: string; tags: string[]; limit: number }>();
+        const ctx: AppSearchContext = { get: (key) => c.get(key) as never };
+        const results = await searchRun({ query: body.query, tags: body.tags, limit: body.limit, ctx });
+        return c.json(results);
+      });
+    }
+
+    // Lifecycle
+    const cloudCtx: CloudContext = {
+      logger,
+      settings: { get, set },
+      runtime: currentRuntime,
+    };
+
+    if (!startOpts.skipSetup && startOpts.lifecycle?.setup) {
+      log.info(`Setup: ${meta.id}`);
+      await startOpts.lifecycle.setup(cloudCtx);
+    }
+
+    await loadSettingsCache();
+
+    if (startOpts.lifecycle?.start) {
+      log.info(`Start: ${meta.id}`);
+      await startOpts.lifecycle.start(cloudCtx);
+    }
+
+    // Graceful shutdown
+    let stopping = false;
+    const shutdown = async () => {
+      if (stopping) return;
+      stopping = true;
+      log.info(`Stopping: ${meta.id}`);
+      try { if (startOpts.lifecycle?.stop) await startOpts.lifecycle.stop(cloudCtx); } catch {}
+      ac.abort();
+      await heartbeat.stop();
+    };
+
+    process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
+    process.on("SIGINT", () => void shutdown().then(() => process.exit(0)));
+
+    return { port, fetch: server.fetch };
+  };
+
+  return {
+    ssr,
+    plugin,
+    config,
+    meta,
+    baseUrl: opts.baseUrl,
+    start,
+    // Phantom — see AppDefinition._settings doc. Do not read at runtime.
+    _settings: undefined as unknown as S,
+    settings: createSettingsAPI<S>(),
+  };
+};