@k2b/cloud 0.42.0 → 0.44.0

package/src/ssr/admin-navigation.ts

@@ -2,7 +2,8 @@ import { normalizeRedirectTo } from "../shared";
 import { platformMessages } from "./platform-messages";
 import type { RuntimeContext } from "./runtime";
 
-export type AdminLink = { href: string; icon: string; label: string };
+/** `match` lists further paths the link stands for, such as the pages of an area. */
+export type AdminLink = { href: string; icon: string; label: string; match?: string[] };
 export type AdminGroup = { label: string; links: AdminLink[] };
 
 const normalizeAdminHref = (href: string | undefined): string | undefined => {
@@ -13,23 +14,12 @@ const normalizeAdminHref = (href: string | undefined): string | undefined => {
 export const buildAdminGroups = (apps: readonly RuntimeContext["apps"][number][], locale = "en"): AdminGroup[] => {
   const t = platformMessages.resolve([locale]).t;
   const settingsLinks: AdminLink[] = [
-    { href: "/admin/settings?tab=general", icon: "ti-app-window", label: t.general },
+    { href: "/admin/settings?tab=storage", icon: "ti-database", label: t.storage },
     { href: "/admin/outgoing-mail", icon: "ti-mail", label: t.outgoingMail },
-    { href: "/admin/settings?tab=pdf-rendering", icon: "ti-file-type-pdf", label: t.pdfRendering },
-    { href: "/admin/places-and-maps", icon: "ti-map-2", label: t.placesAndMaps },
     { href: "/admin/settings?tab=email-templates", icon: "ti-template", label: t.emailTemplates },
     { href: "/admin/settings?tab=security", icon: "ti-shield-lock", label: t.security },
-    { href: "/admin/settings?tab=legal", icon: "ti-file-text", label: t.legal },
-  ];
-  const aiLinks: AdminLink[] = [
-    { href: "/admin/settings?tab=ai-general", icon: "ti-adjustments", label: t.general },
-    { href: "/admin/settings?tab=ai-providers", icon: "ti-sparkles", label: t.providers },
-    { href: "/admin/settings?tab=ai-quotas", icon: "ti-gauge", label: t.aiQuotas },
-    { href: "/admin/settings?tab=ai-usage", icon: "ti-chart-histogram", label: t.aiUsage },
-    { href: "/admin/settings?tab=ai-skills", icon: "ti-wand", label: t.skills },
-    { href: "/admin/settings?tab=ai-projects", icon: "ti-folders", label: t.projects },
-    { href: "/admin/settings?tab=ai-jobs", icon: "ti-activity", label: t.backgroundJobs },
   ];
+  // Areas show as one entry each. The AI area belongs to Core; Observability exists when an app contributes it.
   const contributedApps = apps
     .map((app) => ({
       app,
@@ -46,10 +36,6 @@ export const buildAdminGroups = (apps: readonly RuntimeContext["apps"][number][]
     }))
     .sort((a, b) => a.app.name.localeCompare(b.app.name));
 
-  aiLinks.push(
-    ...contributedApps.flatMap(({ groups }) => groups.filter((group) => group.section === "ai").flatMap((group) => group.links)),
-  );
-
   const appsWithGroups = new Set(contributedApps.filter(({ groups }) => groups.length > 0).map(({ app }) => app.id));
   const appLinks = apps
     .filter((app) => !appsWithGroups.has(app.id))
@@ -59,18 +45,39 @@ export const buildAdminGroups = (apps: readonly RuntimeContext["apps"][number][]
     })
     .sort((a, b) => a.label.localeCompare(b.label));
 
+  const observabilityPaths = contributedApps.flatMap(({ groups }) =>
+    groups.filter((group) => group.section === "observability").flatMap((group) => group.links.map((link) => link.href)),
+  );
+  const areaLinks: AdminLink[] = [
+    { href: "/admin/base", icon: "ti-adjustments", label: t.baseSettings },
+    { href: "/admin/ai", icon: "ti-sparkles", label: t.ai },
+    ...(observabilityPaths.length > 0
+      ? [
+          {
+            // Gateway Ops owns the area's start; without it, the entry opens the first contributed page.
+            href: observabilityPaths.includes("/admin/observability") ? "/admin/observability" : observabilityPaths[0]!,
+            icon: "ti-heart-rate-monitor",
+            label: t.observability,
+            match: observabilityPaths,
+          },
+        ]
+      : []),
+  ];
+
   return [
     {
       label: t.general,
       links: [
         { href: "/admin", icon: "ti-dashboard", label: t.overview },
+        { href: "/admin/apps", icon: "ti-apps", label: t.apps },
         { href: "/admin/app-credentials", icon: "ti-key", label: t.appCredentials },
         { href: "/admin/rail", icon: "ti-layout-sidebar", label: t.rail },
         { href: "/admin/announcements", icon: "ti-speakerphone", label: t.announcements },
       ],
     },
+    { label: t.cloudAreas, links: areaLinks },
     ...contributedApps.flatMap(({ groups }) =>
-      groups.filter((group) => group.section !== "ai").map(({ label, links }) => ({ label, links })),
+      groups.filter((group) => group.section === undefined).map(({ label, links }) => ({ label, links })),
     ),
     {
       label: t.userManagement,
@@ -82,7 +89,6 @@ export const buildAdminGroups = (apps: readonly RuntimeContext["apps"][number][]
         { href: "/admin/settings?tab=freeipa", icon: "ti-building-fortress", label: "FreeIPA" },
       ],
     },
-    { label: t.ai, links: aiLinks },
     { label: t.settings, links: settingsLinks },
     ...(appLinks.length > 0 ? [{ label: t.appAdmin, links: appLinks }] : []),
   ];

package/src/ssr/app-badges.ts

@@ -14,6 +14,11 @@ export const APP_BADGE_INTERVAL_MS = 60_000;
 // Keyed by endpoint, so a pinned app shortcut and the app's own entry share one
 // count. Only the browser ever writes it; server renders always see no badge.
 const [counts, setCounts] = createSignal<ReadonlyMap<string, number>>(new Map());
+// The line a Cloud app part's summary route returns beside its count, keyed like the counts.
+const [texts, setTexts] = createSignal<ReadonlyMap<string, string>>(new Map());
+
+/** The text of a `PwaPartSummary` route once the browser has read it; undefined before or when the read failed. */
+export const appPartSummaryText = (endpoint: string): string | undefined => texts().get(endpoint);
 
 const [approvalCounts, setApprovalCounts] = createSignal<ApprovalCounts | null>(null);
 
@@ -37,16 +42,28 @@ export const parseAppBadge = (body: unknown): number => {
   return typeof count === "number" && Number.isSafeInteger(count) && count > 0 ? count : 0;
 };
 
-const readBadge = async (endpoint: string, signal: AbortSignal): Promise<number> => {
+/** A one-line text of at most 200 characters from a `PwaPartSummary` body, else undefined. */
+export const parsePartSummaryText = (body: unknown): string | undefined => {
+  if (typeof body !== "object" || body === null || !("text" in body)) return undefined;
+  const text = body.text;
+  return typeof text === "string" && text.trim() !== "" && text.length <= 200 && !/[\r\n]/.test(text) ? text.trim() : undefined;
+};
+
+type BadgeRead = { count: number; text?: string };
+
+const readBadge = async (endpoint: string, signal: AbortSignal): Promise<BadgeRead> => {
   try {
     const response = await fetch(endpoint, { credentials: "same-origin", headers: { accept: "application/json" }, signal });
-    if (response.status === 200) return parseAppBadge(await response.json());
+    if (response.status === 200) {
+      const body: unknown = await response.json();
+      return { count: parseAppBadge(body), text: parsePartSummaryText(body) };
+    }
     // Release the response without buffering an unused, potentially unbounded error body.
     await response.body?.cancel();
-    return 0;
+    return { count: 0 };
   } catch {
     // An unreachable or failing app shows no badge rather than a stale one.
-    return 0;
+    return { count: 0 };
   }
 };
 
@@ -108,10 +125,17 @@ export const watchAppBadges = (endpoints: readonly string[]): (() => void) => {
     running.set(endpoint, false);
     const signal = AbortSignal.any([stopped.signal, AbortSignal.timeout(APP_BADGE_INTERVAL_MS)]);
     const result = endpoint === APPROVAL_COUNTS_PATH ? readApprovalCounts(signal) : readBadge(endpoint, signal);
-    void result.then((count) => {
+    void result.then((answer) => {
       if (stopped.signal.aborted) return;
-      if (typeof count === "number") setCounts((previous) => new Map(previous).set(endpoint, count));
-      else setApprovalCounts(count);
+      if ("count" in answer) {
+        setCounts((previous) => new Map(previous).set(endpoint, answer.count));
+        setTexts((previous) => {
+          const next = new Map(previous);
+          if (answer.text === undefined) next.delete(endpoint);
+          else next.set(endpoint, answer.text);
+          return next;
+        });
+      } else setApprovalCounts(answer);
       const queued = running.get(endpoint);
       running.delete(endpoint);
       if (queued && document.visibilityState !== "hidden") read(endpoint);

package/src/ssr/app-pwa-document.tsx

@@ -0,0 +1,16 @@
+import type { RenderFn } from "@k2b/ssr";
+import { LocaleProvider } from "@k2b/ui";
+import type { AppInstallable } from "../contracts/installable";
+import AppPwaRuntime from "./AppPwaRuntime.island";
+
+/** Called by the framework, even when the application renders its own layout. */
+export const appPwaDocument =
+  (render: RenderFn, app: AppInstallable, locale: string): RenderFn =>
+  () => (
+    <>
+      {render()}
+      <LocaleProvider locale={locale}>
+        <AppPwaRuntime app={app} />
+      </LocaleProvider>
+    </>
+  );

package/src/ssr/app-pwa-messages.ts

@@ -0,0 +1,17 @@
+import { i18n } from "@k2b/stdlib";
+
+export const appPwaMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      title: ({ name }: { name: string }) => `Install ${name}`,
+      workerFailed: "Offline support is unavailable. You can continue online or try again.",
+      retry: "Try again",
+    },
+    de: {
+      title: ({ name }: { name: string }) => `${name} installieren`,
+      workerFailed: "Die Offline-Unterstützung ist nicht verfügbar. Du kannst online fortfahren oder es erneut versuchen.",
+      retry: "Erneut versuchen",
+    },
+  },
+});

package/src/ssr/index.ts

@@ -1,6 +1,14 @@
 // Server-only exports (these transitively import bun:sql via services)
 // Do NOT import from this barrel in .island.tsx or .client.tsx files!
 
+export {
+  AdminArea,
+  type AdminAreaGroup,
+  type AdminAreaItem,
+  AdminAreaPane,
+  AdminAreaSaveStatusFoot,
+  AdminAreaSaveStatusHead,
+} from "./AdminArea";
 export { default as AdminLayout } from "./AdminLayout";
 export {
   hasDedicatedRuntimeRoute,

package/src/ssr/layout-context.ts

@@ -10,7 +10,7 @@ export type LayoutContext = {
   get(key: "user"): User | undefined;
   get(key: "panelConsent"): PanelConsentSnapshot | undefined;
   get(key: "railPreferences"): RailSnapshot | undefined;
-  get(key: "page"): { theme?: "light" | "dark"; title?: string; pwa?: { name: string } };
+  get(key: "page"): { theme?: "light" | "dark"; title?: string; pwa?: { name: string }; pwaAddress?: string; pwaOwner?: string };
   get(key: "runtime"): RuntimeContext;
   get(key: "announcements"): LayoutAnnouncementsState | undefined;
   /** Every application settings snapshot includes Core's app metadata. */

package/src/ssr/page-trail-runtime.ts

@@ -304,7 +304,9 @@ export const installPageTrailRuntime = (labels: PageUpLabels): (() => void) => {
   window.addEventListener("ssr:nav-swapped", restoreArrivingPage);
   const onCapture = () => rememberPage();
   const onNavigate = (event: NavigateEvent) => {
-    if (event.navigationType === "traverse") rememberPage();
+    // Same-address history (for example a closing sheet) stays on this page.
+    // Only a departure needs a new scroll snapshot; reading it can force layout.
+    if (event.navigationType === "traverse" && event.destination.url !== location.href) rememberPage();
   };
   const onKey = (event: KeyboardEvent) => {
     if (event.key === "Enter") rememberPage();

package/src/ssr/platform-messages.ts

@@ -42,6 +42,9 @@ export const platformMessages = i18n.define({
       announcements: "Announcements",
       appCredentials: "App credentials",
       ai: "AI",
+      observability: "Observability",
+      baseSettings: "Base settings",
+      cloudAreas: "Cloud",
       settings: "Settings",
       appAdmin: "App administration",
       userManagement: "Accounts & sign-in",
@@ -49,6 +52,7 @@ export const platformMessages = i18n.define({
       accountRegistration: "Registration & requests",
       accountOperations: "Operations",
       linuxAccess: "Linux identities",
+      storage: "Storage",
       pdfRendering: "PDF rendering",
       placesAndMaps: "Places and maps",
       emailTemplates: "Email templates",
@@ -142,8 +146,11 @@ export const platformMessages = i18n.define({
       general: "Allgemein",
       rail: "App-Leiste",
       announcements: "Ankündigungen",
-      appCredentials: "App-Zugänge",
+      appCredentials: "App-Schlüssel",
       ai: "KI",
+      observability: "Observability",
+      baseSettings: "Grundeinstellungen",
+      cloudAreas: "Cloud",
       settings: "Einstellungen",
       appAdmin: "App-Administration",
       userManagement: "Accounts & Anmeldung",
@@ -151,6 +158,7 @@ export const platformMessages = i18n.define({
       accountRegistration: "Registrierung & Anfragen",
       accountOperations: "Betrieb",
       linuxAccess: "Linux-Identitäten",
+      storage: "Speicher",
       pdfRendering: "PDF-Erstellung",
       placesAndMaps: "Orte und Karten",
       emailTemplates: "E-Mail-Vorlagen",

package/src/ssr/pwa-messages.ts

@@ -7,17 +7,25 @@ export const pwaMessages = i18n.define({
     en: {
       tabs: "App",
       start: "Start",
+      apps: "Apps",
+      settings: "Settings",
       offline: "You're offline",
+      newVersion: ({ cloud }: { cloud: string }) => `New version of ${cloud}`,
+      reload: "Reload",
       otherAccount: ({ cloud, name }: { cloud: string; name: string }) =>
-        `Chrome on this phone is signed in to ${cloud} as ${name}. Changes in the app may be saved to that account. Sign out of ${cloud} in Chrome.`,
+        `Chrome on this device is signed in to ${cloud} as ${name}. Changes in the app may be saved to that account. Sign out of ${cloud} in Chrome.`,
       errorAction: "Back to Start",
     },
     de: {
       tabs: "App",
       start: "Start",
+      apps: "Apps",
+      settings: "Einstellungen",
       offline: "Du bist offline",
+      newVersion: ({ cloud }: { cloud: string }) => `Neue Version von ${cloud}`,
+      reload: "Neu laden",
       otherAccount: ({ cloud, name }: { cloud: string; name: string }) =>
-        `Chrome auf diesem Telefon ist bei ${cloud} als ${name} angemeldet. Änderungen in der App werden womöglich in diesem Konto gespeichert. Melde dich in Chrome von ${cloud} ab.`,
+        `Chrome auf diesem Gerät ist bei ${cloud} als ${name} angemeldet. Änderungen in der App werden womöglich in diesem Konto gespeichert. Melde dich in Chrome von ${cloud} ab.`,
       errorAction: "Zurück zum Start",
     },
   },

package/src/ssr/rail-navigation.ts

@@ -79,6 +79,9 @@ export const phoneBarLinks = (navigation: { shortcuts: RailLink[]; apps: RailLin
   return [...links.slice(0, limit - 1), links[current]!];
 };
 
+/** A phone bar item, and where its app's count comes from, like the rail icon's. */
+export type PhoneBarItem = TabBarItem & { counted?: { endpoint?: string; appId?: string } };
+
 /** Start and four apps fill the phone bar's five places. */
 const PHONE_BAR_APPS = 4;
 
@@ -93,7 +96,7 @@ export const phoneBarItems = (
   navigation: { shortcuts: RailLink[]; apps: RailLink[] },
   currentPath: string,
   home: { label: string; path: string },
-): TabBarItem[] => {
+): PhoneBarItem[] => {
   const links = phoneBarLinks(navigation, currentPath, PHONE_BAR_APPS);
   const items = links.map((link) => ({
     id: link.id,
@@ -101,6 +104,7 @@ export const phoneBarItems = (
     icon: link.iconClass,
     href: link.href,
     current: railLinkActive(link, currentPath),
+    ...(link.badge || link.appId ? { counted: { endpoint: link.badge, appId: link.appId } } : {}),
   }));
   const pathname = new URL(currentPath, "https://cloud.invalid").pathname;
   const start = new URL(home.path, "https://cloud.invalid").pathname;

package/src/ssr/settings-draft.ts

@@ -0,0 +1,153 @@
+import type { SaveStatusState } from "@k2b/ui";
+import { createEffect, createMemo, createSignal, onCleanup } from "solid-js";
+
+/**
+ * A settings form saves with the button in its level head, outside the form island. Both islands read this store: the
+ * form registers its state and actions, `SettingsSaveStatus` renders them. One form per page registers at a time.
+ */
+export type SettingsSaveControls = {
+  state: SaveStatusState;
+  savedAt?: string;
+  invalidCount?: number;
+  save: () => void;
+  discard: () => void;
+};
+
+const [controls, setControls] = createSignal<SettingsSaveControls | null>(null);
+export const settingsSaveControls = controls;
+
+/** A save that did not succeed: refused with a reason, or with an unclear outcome. */
+export type SettingsDraftOutcome = { kind: "failed" | "unknown"; message: string };
+
+/** Thrown by `save` when the server refused the write; anything else counts as an unclear outcome. */
+export class SaveRejected extends Error {}
+
+/**
+ * The error for a non-OK save response. A 4xx refused the write. A 5xx can come after the value was stored (for
+ * example when a follow-up step failed), so its outcome stays unclear and the person checks the current state.
+ */
+export const saveFailure = (status: number, message: string): Error =>
+  status >= 400 && status < 500 ? new SaveRejected(message) : new Error(message);
+
+/**
+ * For endpoints that write in one step and answer afterwards: an error body with a message comes from the handler,
+ * which did not store the value, so the save is refused and can be tried again. A response without one (a proxy
+ * page, a crash) leaves the outcome unclear.
+ */
+export const oneStepFailure = (status: number, body: { message?: string } | null, fallback: string): Error =>
+  body?.message ? new SaveRejected(body.message) : saveFailure(status, fallback);
+
+type Options<T> = {
+  initial: T;
+  /** Field errors of a draft; Save stays disabled while there are any. */
+  validate?: (value: T) => Record<string, string>;
+  /** True when saving is needed although the values did not change, such as a confirmed replacement. */
+  pending?: () => boolean;
+  /**
+   * Writes the draft and returns what is stored now. A save that writes several values one after another reports
+   * each stored step with `commit`, so a later failure keeps what already reached the server as the saved state.
+   */
+  save: (value: T, commit: (stored: T) => void) => Promise<T>;
+  locale: () => string;
+  /** Runs with Discard, for state the form keeps beside the draft, such as staged resets. */
+  onDiscard?: () => void;
+};
+
+/**
+ * A settings form that saves with a button: the draft, its field errors and the outcome of the last save. It registers
+ * with the level head, which shows the status with Discard and Save. A failed save keeps the draft; when the
+ * connection breaks, the outcome stays unclear and the person checks the current state instead of saving twice.
+ */
+export const createSettingsDraft = <T>(options: Options<T>) => {
+  const [stored, setStored] = createSignal<T>(options.initial);
+  const [draft, setDraft] = createSignal<T>(options.initial);
+  const [saving, setSaving] = createSignal(false);
+  const [outcome, setOutcome] = createSignal<SettingsDraftOutcome | null>(null);
+  const [savedAt, setSavedAt] = createSignal<string | undefined>(undefined);
+  const errors = createMemo(() => options.validate?.(draft()) ?? {});
+  const dirty = createMemo(() => JSON.stringify(draft()) !== JSON.stringify(stored()) || options.pending?.() === true);
+  const state = createMemo<SaveStatusState>(() => {
+    if (saving()) return "saving";
+    if (outcome()?.kind === "unknown") return "unknown";
+    if (Object.keys(errors()).length > 0) return "invalid";
+    if (outcome()?.kind === "failed") return "failed";
+    return dirty() ? "draft" : "saved";
+  });
+
+  const save = async () => {
+    if (saving() || !dirty() || Object.keys(errors()).length > 0 || outcome()?.kind === "unknown") return;
+    setSaving(true);
+    setOutcome(null);
+    const submitted = draft();
+    // Edits made while the request runs stay; only an untouched draft takes the stored values.
+    const settle = (next: T) => {
+      setStored(() => next);
+      if (draft() === submitted) setDraft(() => next);
+    };
+    try {
+      // A step only moves the saved state; the draft keeps the values still on their way.
+      settle(await options.save(submitted, (step) => setStored(() => step)));
+      setSavedAt(new Intl.DateTimeFormat(options.locale(), { hour: "2-digit", minute: "2-digit" }).format(new Date()));
+    } catch (error) {
+      setOutcome({
+        kind: error instanceof SaveRejected ? "failed" : "unknown",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      setSaving(false);
+    }
+  };
+  const discard = () => {
+    setDraft(() => stored());
+    setOutcome((current) => (current?.kind === "unknown" ? current : null));
+    options.onDiscard?.();
+  };
+  /**
+   * Takes newer stored values without losing edits: a field still at its old saved value moves to the new one, an
+   * edited field keeps the person's value. `adopt` names fields that take the new value regardless.
+   */
+  const rebase = (next: T, adopt: readonly string[] = []) => {
+    const previous = stored() as Record<string, unknown>;
+    const current = draft() as Record<string, unknown>;
+    const merged: Record<string, unknown> = { ...current };
+    for (const [key, value] of Object.entries(next as Record<string, unknown>)) {
+      if (adopt.includes(key) || JSON.stringify(current[key]) === JSON.stringify(previous[key])) merged[key] = value;
+    }
+    setStored(() => next);
+    setDraft(() => merged as T);
+  };
+
+  // Leaving the page with unsaved changes asks first, as the settings pages did before.
+  if (typeof window !== "undefined") {
+    const guard = (event: BeforeUnloadEvent) => {
+      if (state() === "saved") return;
+      event.preventDefault();
+    };
+    window.addEventListener("beforeunload", guard);
+    onCleanup(() => window.removeEventListener("beforeunload", guard));
+  }
+
+  createEffect(() =>
+    setControls({
+      state: state(),
+      savedAt: savedAt(),
+      invalidCount: Object.keys(errors()).length,
+      save: () => void save(),
+      discard,
+    }),
+  );
+  onCleanup(() => setControls(null));
+
+  return {
+    draft,
+    update: (change: Partial<T>) => setDraft((current) => ({ ...current, ...change })),
+    errors,
+    outcome,
+    saving,
+    save,
+    discard,
+    rebase,
+    /** The values last read from the server. */
+    stored,
+  };
+};

package/src/ssr/shell-data.tsx

@@ -9,6 +9,8 @@ import type { PanelProvider } from "./app-navigation";
 import type { RailApp } from "./rail-navigation";
 
 export type ShellData = {
+  /** Canonical public Cloud origin; omitted until app.url is configured. */
+  cloudOrigin?: string;
   panel?: { providers: PanelProvider[]; provider?: string; context: PanelPageContext | null; consent?: PanelConsentSnapshot };
   /** The authorized navigation catalog, sorted for the request locale: the rail, the app grid and the phone menu show it. */
   apps: RailApp[];

package/src/styles/global.css

@@ -32,6 +32,7 @@
 @import "./input.css";
 @import "./resource-search.css";
 @import "./file-chooser.css";
+@import "./profile-picture.css";
 @import "./panel.css";
 
 @theme {