@k2b/cloud 0.39.0 → 0.40.0

package/src/_internal/capability-sentences.ts

@@ -1,5 +1,14 @@
 import { dates, i18n } from "@k2b/stdlib";
-import type { CapabilityActionSentences, CapabilityPresentationCatalog } from "../contracts/capabilities";
+import type {
+  CapabilityActionCallReview,
+  CapabilityActionOutcome,
+  CapabilityActionReceipt,
+  CapabilityActionSentences,
+  CapabilityAskReason,
+  CapabilityPerson,
+  CapabilityPresentationCatalog,
+  CapabilitySlot,
+} from "../contracts/capabilities";
 import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../shared/locale";
 import { normalizeTimeZone } from "../shared/time";
 
@@ -78,12 +87,38 @@ const words = i18n.define({
   baseLocale: "en",
   messages: {
     en: {
+      question: ({ sentence }: { sentence: string }) => `${sentence}?`,
+      rejected: ({ action }: { action: string }) => `Not done: ${action}`,
+      unknown: ({ action }: { action: string }) => `Not known yet whether this happened: ${action}`,
+      unknownStill: ({ action }: { action: string }) => `Still not known whether this happened: ${action}`,
+      people: ({ count }: { count: number }) => `${count} ${new Intl.PluralRules("en").select(count) === "one" ? "person" : "people"}`,
+      sends: "I'm asking because this leaves Cloud.",
+      deletes: "I'm asking because you can't bring it back afterwards.",
+      cannot_undo: "I'm asking because you can't set this back.",
+      involves_people: "I'm asking because this involves or notifies other people.",
+      changes_access: "I'm asking because this changes who can see it.",
+      keeps_working: "I'm asking because this keeps acting without you.",
+      sensitive: "I'm asking because this concerns payments, invoices, addresses, or sign-in data.",
+      app_asks: ({ app }: { app: string }) => `I'm asking because ${app} always asks for this.`,
       yes: "yes",
       no: "no",
       more: ({ count }: { count: number }) => `${count} more`,
       why: "Why",
     },
     de: {
+      question: ({ sentence }) => `${sentence}?`,
+      rejected: ({ action }) => `Nicht ausgeführt: ${action}`,
+      unknown: ({ action }) => `Ob ${action} passiert ist, weiß ich noch nicht.`,
+      unknownStill: ({ action }) => `Ob ${action} passiert ist, weiß ich weiterhin nicht.`,
+      people: ({ count }) => `${count} ${new Intl.PluralRules("de").select(count) === "one" ? "Person" : "Personen"}`,
+      sends: "Ich frage, weil das Cloud verlässt.",
+      deletes: "Ich frage, weil du das danach nicht zurückholen kannst.",
+      cannot_undo: "Ich frage, weil du das nicht zurückstellen kannst.",
+      involves_people: "Ich frage, weil das andere Personen einbindet oder benachrichtigt.",
+      changes_access: "Ich frage, weil sich ändert, wer das sehen kann.",
+      keeps_working: "Ich frage, weil das ohne dich weiterwirkt.",
+      sensitive: "Ich frage, weil das Zahlungen, Rechnungen, Adressen oder Zugangsdaten betrifft.",
+      app_asks: ({ app }) => `Ich frage, weil ${app} hier jedes Mal fragt.`,
       yes: "ja",
       no: "nein",
       more: ({ count }) => `${count} weitere`,
@@ -411,3 +446,183 @@ export const capabilitySentenceFields = (input: {
   }
   return [...fields.values()];
 };
+
+export type CapabilitySlotSentenceContext = { locale: string; timeZone: string };
+export type CapabilitySentencePart =
+  | { kind: "text"; text: string }
+  | { kind: "chip"; name: string; slot: CapabilitySlot; label: string; full: string };
+export const capabilityPersonText = (person: CapabilityPerson): string =>
+  person.name && person.address ? `${person.name} <${person.address}>` : (person.name ?? person.address ?? "");
+
+const slotText = (slot: CapabilitySlot, context: CapabilitySlotSentenceContext, mode: "chip" | "plain" | "button" | "full"): string => {
+  const t = words.resolve([context.locale]).t;
+  switch (slot.kind) {
+    case "text":
+      return slot.value;
+    case "count": {
+      const plural = new Intl.PluralRules(context.locale).select(slot.value);
+      return `${new Intl.NumberFormat(context.locale).format(slot.value)} ${slot.noun[plural] ?? slot.noun.other}`;
+    }
+    case "person": {
+      const total = slot.total ?? slot.people.length;
+      if (mode === "button") return total === 1 ? (slot.people[0]!.name ?? slot.people[0]!.address ?? "") : t.people({ count: total });
+      const shown = mode === "full" ? slot.people : slot.people.slice(0, 3);
+      const list = shown.map((person) =>
+        mode === "chip" ? plain(person.name ?? person.address ?? "", 40, "middle") : capabilityPersonText(person),
+      );
+      const rest = total - shown.length;
+      if (rest > 0) list.push(t.more({ count: rest }));
+      return new Intl.ListFormat(context.locale, { type: "conjunction" }).format(list);
+    }
+    case "object":
+    case "place": {
+      if (mode === "button") return plain(slot.title, 24, "middle");
+      if (mode === "chip" || mode === "full") return slot.title;
+      return context.locale.toLowerCase().startsWith("de") ? `„${slot.title}“` : `“${slot.title}”`;
+    }
+    case "time": {
+      const date = (value: string) => {
+        const options = { locale: context.locale, timeZone: slot.format === "date" ? "UTC" : normalizeTimeZone(context.timeZone) };
+        return slot.format === "date" ? dates.formatDate(`${value}T12:00:00.000Z`, options) : dates.formatDateTime(value, options);
+      };
+      return slot.end ? `${date(slot.start)} – ${date(slot.end)}` : date(slot.start);
+    }
+  }
+};
+
+/** Typed slots are data, never expressions. All formatting is explicit and independent of the process zone. */
+export const capabilitySentenceParts = (
+  text: string,
+  slots: Readonly<Record<string, CapabilitySlot>>,
+  context: CapabilitySlotSentenceContext,
+): CapabilitySentencePart[] => {
+  const parts: CapabilitySentencePart[] = [];
+  let index = 0;
+  for (const match of text.matchAll(/\{([a-z][A-Za-z0-9]{0,31})\}/g)) {
+    if (match.index > index) parts.push({ kind: "text", text: text.slice(index, match.index) });
+    const name = match[1]!;
+    const slot = Object.hasOwn(slots, name) ? slots[name] : undefined;
+    if (!slot) throw new Error(`Unknown sentence slot ${name}`);
+    const label = slotText(slot, context, "chip");
+    const full = slotText(slot, context, "full");
+    parts.push(
+      slot.kind === "text" || slot.kind === "count"
+        ? { kind: "text", text: label }
+        : { kind: "chip", name, slot, label: slot.kind === "person" ? label : plain(label, 40, "middle"), full },
+    );
+    index = match.index + match[0].length;
+  }
+  if (index < text.length) parts.push({ kind: "text", text: text.slice(index) });
+  return parts;
+};
+const sentenceText = (
+  text: string,
+  slots: Readonly<Record<string, CapabilitySlot>>,
+  context: CapabilitySlotSentenceContext,
+  mode: "plain" | "button",
+  max = 400,
+): string => {
+  const render = (slotMax: number) =>
+    text.replace(/\{([a-z][A-Za-z0-9]{0,31})\}/g, (_, name: string) => {
+      const slot = Object.hasOwn(slots, name) ? slots[name] : undefined;
+      if (!slot) throw new Error(`Unknown sentence slot ${name}`);
+      return plain(slotText(slot, context, mode), slotMax, "middle");
+    });
+  let result = render(Number.MAX_SAFE_INTEGER);
+  if (Array.from(result).length > max) result = render(40);
+  return plain(result, max);
+};
+export const capabilitySentenceText = (
+  text: string,
+  slots: Readonly<Record<string, CapabilitySlot>>,
+  context: CapabilitySlotSentenceContext,
+): string => sentenceText(text, slots, context, "plain");
+export type CapabilityReviewSentenceForm =
+  | "question"
+  | "unknownStill"
+  | "running"
+  | "done"
+  | "rejected"
+  | "notRun"
+  | "unknown"
+  | "short"
+  | "confirm"
+  | "decline";
+export const capabilityReviewSentence = (
+  review: CapabilityActionCallReview,
+  form: CapabilityReviewSentenceForm,
+  context: { timeZone: string },
+): string => {
+  const rendering = { locale: review.locale, timeZone: context.timeZone };
+  const t = words.resolve([review.locale]).t;
+  const action = () => capabilitySentenceText(review.sentence.action, review.slots, rendering);
+  if (form === "question") return plain(t.question({ sentence: action() }), 400);
+  if (form === "unknown") return plain(t.unknown({ action: action() }), 400);
+  if (form === "unknownStill") return plain(t.unknownStill({ action: action() }), 400);
+  if (form === "confirm" || form === "decline")
+    return sentenceText(review.sentence[form], review.slots, rendering, "button", Number.MAX_SAFE_INTEGER);
+  const template = form === "notRun" ? (review.sentence.notRun ?? review.sentence.rejected) : review.sentence[form];
+  if (template) return capabilitySentenceText(template, review.slots, rendering);
+  if (form === "short") return action();
+  return plain(t.rejected({ action: action() }), 400);
+};
+export const capabilityOutcomeSentence = (
+  review: CapabilityActionCallReview,
+  outcome: CapabilityActionOutcome,
+  receipt: CapabilityActionReceipt | undefined,
+  context: { timeZone: string },
+): string =>
+  outcome === "done" && receipt
+    ? capabilitySentenceText(receipt.text, receipt.slots ?? {}, { locale: review.locale, timeZone: context.timeZone })
+    : capabilityReviewSentence(review, outcome === "not_run" ? "notRun" : outcome, context);
+export const capabilityAskReasonText = (reason: CapabilityAskReason, context: { locale: string; appName: string }): string => {
+  const t = words.resolve([context.locale]).t;
+  return reason === "app_asks" ? t.app_asks({ app: context.appName }) : t[reason];
+};
+
+/** Splits a Cloud frame such as "Ob {action} passiert ist, weiß ich noch nicht." around the inserted sentence. */
+const framed = (frame: (input: { action: string }) => string, inner: CapabilitySentencePart[]): CapabilitySentencePart[] => {
+  const marker = "\u0000";
+  const [before = "", after = ""] = frame({ action: marker }).split(marker);
+  return [
+    ...(before ? [{ kind: "text" as const, text: before }] : []),
+    ...inner,
+    ...(after ? [{ kind: "text" as const, text: after }] : []),
+  ];
+};
+
+/**
+ * One form of a review as parts for chips: the same words as `capabilityReviewSentence`, with Cloud's frames (the
+ * question mark, "not known yet", the default rejection) around the app's sentence. Buttons and `short` stay text.
+ */
+export const capabilityReviewSentenceParts = (
+  review: CapabilityActionCallReview,
+  form: Exclude<CapabilityReviewSentenceForm, "short" | "confirm" | "decline">,
+  context: { timeZone: string },
+): CapabilitySentencePart[] => {
+  const rendering = { locale: review.locale, timeZone: context.timeZone };
+  const t = words.resolve([review.locale]).t;
+  const action = () => capabilitySentenceParts(review.sentence.action, review.slots, rendering);
+  if (form === "question") return framed(({ action: sentence }) => t.question({ sentence }), action());
+  if (form === "unknown") return framed(t.unknown, action());
+  if (form === "unknownStill") return framed(t.unknownStill, action());
+  const template = form === "notRun" ? (review.sentence.notRun ?? review.sentence.rejected) : review.sentence[form];
+  if (template) return capabilitySentenceParts(template, review.slots, rendering);
+  return framed(t.rejected, action());
+};
+
+/** The parts of a receipt the app returned, in the review's language. */
+export const capabilityReceiptParts = (
+  receipt: CapabilityActionReceipt,
+  context: { locale: string; timeZone: string },
+): CapabilitySentencePart[] => capabilitySentenceParts(receipt.text, receipt.slots ?? {}, context);
+
+/** Cloud's frame for an outcome it could not see, around any plain sentence. */
+export const capabilityUnknownText = (action: string, locale: string, still = false): string => {
+  const t = words.resolve([locale]).t;
+  return plain(still ? t.unknownStill({ action }) : t.unknown({ action }), 400);
+};
+
+/** Cloud's question frame around a plain sentence, such as Cloud's own sentence for a call without a review. */
+export const capabilityQuestionText = (sentence: string, locale: string): string =>
+  plain(words.resolve([locale]).t.question({ sentence }), 400);

package/src/_internal/capability-streams.ts

@@ -8,6 +8,7 @@ import {
   capabilityResultSchema,
 } from "../contracts/capabilities";
 import type { CompiledCapabilities } from "./capabilities";
+import { capabilityActionReceiptIssues } from "./capability-reviews";
 
 const failure = (status: number, code: string, message: string) => Response.json({ code, message }, { status });
 export async function invokeCapabilityStream(params: {
@@ -26,6 +27,12 @@ export async function invokeCapabilityStream(params: {
   const receipt = (value: unknown) => {
     const parsed = capabilityResultSchema(operation.definition.data).parse(value);
     if (parsed.stream) throw new Error("Stream receipts cannot issue another stream");
+    // The same receipt rules as an ordinary result, so a stream completion cannot skip them.
+    if (parsed.receipt !== undefined) {
+      const issues =
+        params.kind === "queries" ? ["Queries cannot return a receipt"] : capabilityActionReceiptIssues(parsed.receipt, parsed.links);
+      if (issues.length > 0) throw new Error(`Stream result receipt is invalid: ${issues.join("; ")}`);
+    }
     return parsed;
   };
   try {

package/src/_internal/define-app.ts

@@ -2,6 +2,7 @@ import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, valid
 import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
+import { preloadPanelConsent } from "../ssr/panel-consent";
 import { invokeCapabilityStream } from "./capability-streams";
 import { bindProcessApplicationId, clearProcessApplicationId } from "./process-identity";
 /**
@@ -75,10 +76,11 @@ import { capabilityMessages } from "../shared/capability-messages";
 import { normalizeLocale } from "../shared/locale";
 import { escapeHtml } from "../shared/markdown/shared";
 import { type CloudThemePreference, readThemePreferenceFromCookieHeader, themeBootstrapScript } from "../shared/theme";
+import { appAccentStyle } from "../ssr/app-appearance";
 import { appFaviconHref } from "./app-favicon";
 import { compileAppPresentation } from "./app-presentation";
 import { readBoundedJson } from "./bounded-json";
-import { appRuntimeMetadata } from "./build-metadata";
+import { appRuntimeMetadata, buildMetadata } from "./build-metadata";
 import { compileCapabilities, invokeCompiledCapability, reviewCompiledCapability, serializeCapabilityProviderResult } from "./capabilities";
 import { cliPluginRoutePrefixes, createCliPluginRoutes, validateAppCliModules } from "./cli-plugins";
 import { FONT_PRELOAD_LINKS } from "./font-preloads";
@@ -90,14 +92,14 @@ import { getProcessSync, startProcessSync } from "./process-sync";
 import { APP_READINESS_PATH, appReadinessResponse } from "./readiness";
 import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
 import { canonicalRoute, isOwnAppPath } from "./registry-validation";
-import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
-import { servePublicAsset } from "./static-assets";
+import { ensureRuntimeWatcher, getCurrentRuntime, registeredCoreRelease, stopRuntimeWatcher } from "./runtime-watcher";
+import { publicFileVersion, servePublicAsset, sharedStylesheetVersion, versionedPublicHref } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
 import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
 import { compileWidgetDeclarations } from "./widget-declarations";
 
-/** Cache-busting version stamp — changes on every server start / rebuild. */
-const v = Date.now();
+/** Only development links use this start stamp to pick up rebuilds. */
+const developmentStamp = Date.now();
 
 export type PageOptions = {
   title?: string;
@@ -110,7 +112,7 @@ export type PageOptions = {
   pwa?: { name: string };
 };
 
-type ResolvedPageOptions = PageOptions & { performanceRoute?: string; themePreference?: CloudThemePreference };
+type ResolvedPageOptions = PageOptions & { performanceRoute?: string; themePreference?: CloudThemePreference; appAccent?: string };
 
 // ── Public types ────────────────────────────────────────────────────────────
 
@@ -377,13 +379,20 @@ const validateAppNavBadge = (opts: Pick<AppOptions, "id" | "routes" | "nav">): v
   }
 };
 
-const validateAppPanel = (opts: Pick<AppOptions, "id" | "routes" | "panel">): AppMeta["panel"] => {
+const validateAppPanel = (opts: Pick<AppOptions, "id" | "routes" | "basePath" | "panel">): AppMeta["panel"] => {
   const panel = opts.panel;
   if (panel === undefined) return undefined;
   if (!panel || typeof panel !== "object" || Array.isArray(panel)) throw new Error(`App "${opts.id}" declares panel; it must be an object`);
   if (typeof panel.href !== "string" || !isOwnAppPath(panel.href, opts.routes)) {
     throw new Error(`App "${opts.id}" declares panel.href "${panel.href}"; it must be a same-origin path below one of its routes`);
   }
+  const pageBase = `${opts.basePath?.replace(/\/$/, "") ?? ""}/help`;
+  const path = new URL(panel.href, "https://cloud.invalid").pathname;
+  if (path === pageBase || path.startsWith(`${pageBase}/`)) {
+    throw new Error(
+      `App "${opts.id}" declares panel.href "${panel.href}"; it must not be at or below its Help path "${pageBase}", which the framework uses for Help`,
+    );
+  }
   for (const field of ["label", "icon"] as const) {
     if (typeof panel[field] !== "string" || !panel[field].trim())
       throw new Error(`App "${opts.id}" declares panel.${field}; it must be a non-empty string`);
@@ -434,7 +443,18 @@ export const defineApp = <
     // Every island instance already mounts inside its own error boundary; this
     // only gives the fallback Cloud's look and the reader's language.
     errorFallback: fileURLToPath(new URL("../ssr/IslandError.tsx", import.meta.url)),
-    template: ({ body, scripts, title, description, theme, themePreference, lang, performanceRoute, pwa }) => {
+    template: ({ body, scripts, title, description, theme, themePreference, lang, performanceRoute, pwa, appAccent }) => {
+      // A URL changes only when what it names changes: the app's own files by their content, Core's shared sheets by
+      // the release of the Core build in the registry, so every app links them under one URL per Core build.
+      const sharedVersion = isDevelopment ? String(developmentStamp) : sharedStylesheetVersion(registeredCoreRelease());
+      const appStylesheet = `/public/${opts.id}/app.css`;
+      const appVersion = isDevelopment ? String(developmentStamp) : publicFileVersion(appStylesheet);
+      const faviconVersion = isDevelopment
+        ? developmentStamp
+        : opts.id === "core"
+          ? undefined
+          : publicFileVersion(`/public/${opts.id}/favicon.svg`);
+      const accentStyle = appAccentStyle(appAccent);
       const fixed = theme !== undefined;
       const resolved = theme ?? (themePreference === "light" || themePreference === "dark" ? themePreference : undefined);
       // App pages paint the canvas before any stylesheet and give it to the
@@ -478,17 +498,17 @@ export const defineApp = <
     <title>${escapeHtml(title ?? "Cloud")}</title>
     <meta name="description" content="${escapeHtml(description ?? "Cloud workspace")}">
     ${head.app}
-    <link rel="icon" href="${appFaviconHref(opts.id, v)}">
+    <link rel="icon" href="${appFaviconHref(opts.id, faviconVersion)}">
     <style data-cloud-css-layers>@layer properties, theme, base, components, utilities;</style>
     <link rel="preload" href="/public/tabler-icons.woff2" as="font" type="font/woff2" crossorigin>
     ${FONT_PRELOAD_LINKS}
-    <link rel="stylesheet" href="/public/fonts.css?v=${v}">
-    <link rel="stylesheet" href="/public/tabler-icons.css?v=${v}">
-    <link rel="stylesheet" href="/public/${opts.id}/app.css?v=${v}">
-    <link rel="stylesheet" href="/public/global.css?v=${v}">${head.styles}
+    <link rel="stylesheet" href="${versionedPublicHref("/public/fonts.css", sharedVersion)}">
+    <link rel="stylesheet" href="${versionedPublicHref("/public/tabler-icons.css", sharedVersion)}">
+    <link rel="stylesheet" href="${versionedPublicHref(appStylesheet, appVersion)}">
+    <link rel="stylesheet" href="${versionedPublicHref("/public/global.css", sharedVersion)}">${head.styles}
     <script>${themeBootstrapScript}</script>
   </head>
-  <body class="k2b-ui" data-k2b-app-workspace-controller="global">
+  <body class="k2b-ui${accentStyle ? " app-accent-scope" : ""}"${accentStyle ? ` style="${escapeHtml(accentStyle)}"` : ""} data-k2b-app-workspace-controller="global">
     ${body}
   </body>
   ${scripts}
@@ -520,6 +540,7 @@ export const defineApp = <
       await Promise.all([
         preloadLayoutAnnouncements(c),
         preloadLayoutHelp(c),
+        user ? preloadPanelConsent(c) : undefined,
         user ? readRailSnapshot(user).then((snapshot) => c.set("railPreferences", snapshot)) : undefined,
       ]);
     }),
@@ -741,7 +762,7 @@ export const defineApp = <
         .get(APP_READINESS_PATH, () => appReadinessResponse(meta.id))
         .route(ssrMountPath, routes(config))
         .all(`${ssrMountPath}/*`, (c) => c.notFound())
-        .all("/public/*", servePublicAsset(isDevelopment))
+        .all("/public/*", servePublicAsset(isDevelopment, sharedStylesheetVersion(buildMetadata.release)))
         .use(
           "/_internal/sync/*",
           requireInvocation((c) => ({

package/src/_internal/font-preloads.ts

@@ -3,7 +3,8 @@ import plexPreset from "@k2b/ui/fonts/plex.css" with { type: "text" };
 
 /**
  * Preload tags for the IBM Plex Sans faces that every page sets in its first
- * frame: Latin text at 400, 500 (buttons, labels) and 600 (headings).
+ * frame: Latin text at 400, 500 (list titles, medium text) and 600 (headings,
+ * buttons, labels).
  *
  * The preset declares its faces with `font-display: swap`. Without a preload
  * the browser requests a face only when layout needs it, paints the fallback

package/src/_internal/runtime-watcher.ts

@@ -19,6 +19,7 @@ import { buildRuntimeFromRegistry } from "./runtime-context";
 const log = logger("runtime-watcher");
 
 let current: CloudRuntime | undefined;
+let coreRelease: string | undefined;
 let initPromise: Promise<void> | undefined;
 let watcherTask: Promise<void> | undefined;
 let abort: AbortController | undefined;
@@ -27,8 +28,12 @@ const refresh = async () => {
   const apps = await listApps();
   const capabilities = await listCapabilities(apps);
   current = buildRuntimeFromRegistry(apps, capabilities);
+  coreRelease = apps.find((app) => app.id === "core")?.runtime?.release;
 };
 
+/** Core's release from the live registry, absent before initialization and after shutdown. */
+export const registeredCoreRelease = (): string | undefined => coreRelease;
+
 export const ensureRuntimeWatcher = (): Promise<void> => {
   // Concurrent callers (start() + first request) wait on the same init —
   // returning before `current` is populated would race getCurrentRuntime().
@@ -68,6 +73,7 @@ export const stopRuntimeWatcher = async (): Promise<void> => {
   watcherTask = undefined;
   initPromise = undefined;
   current = undefined;
+  coreRelease = undefined;
 };
 
 export const getCurrentRuntime = (): CloudRuntime => {

package/src/_internal/static-assets.ts

@@ -1,7 +1,43 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
 import { resolve, sep } from "node:path";
 import type { Context } from "hono";
 
 const publicRoot = resolve(process.cwd(), "public");
+const versions = new Map<string, { size: number; mtimeMs: number; version: string }>();
+
+/**
+ * Version of Core's shared stylesheets: the release, which names one build. `local` and `development` are the
+ * defaults of unnamed builds and name many, so those sheets get no version and are revalidated instead.
+ */
+export function sharedStylesheetVersion(release: string | undefined): string | undefined {
+  return !release || release === "local" || release === "development" ? undefined : release;
+}
+
+/**
+ * Content version of a file below `public/`: hashed on first use and re-hashed only when the file's size or
+ * modification time changes; a missing or unreadable file has no version.
+ */
+export function publicFileVersion(pathname: string): string | undefined {
+  const path = resolvePublicAsset(pathname);
+  if (!path) return undefined;
+  try {
+    const stat = statSync(path, { throwIfNoEntry: false });
+    if (!stat?.isFile()) return undefined;
+    const cached = versions.get(path);
+    if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return cached.version;
+    const version = createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 16);
+    versions.set(path, { size: stat.size, mtimeMs: stat.mtimeMs, version });
+    return version;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Append a URL-encoded version only when the asset has one. */
+export function versionedPublicHref(pathname: string, version: string | undefined): string {
+  return version === undefined ? pathname : `${pathname}?v=${encodeURIComponent(version)}`;
+}
 
 function decodePathname(pathname: string): string | null {
   try {
@@ -48,14 +84,15 @@ async function encodedFile(path: string, encoding: "br" | "gzip"): Promise<Bun.B
   return (await file.exists()) ? file : null;
 }
 
-export function servePublicAsset(isDevelopment: boolean) {
+export function servePublicAsset(isDevelopment: boolean, sharedVersion?: string) {
   return async (c: Context) => {
     if (c.req.method !== "GET" && c.req.method !== "HEAD") {
       c.header("Allow", "GET, HEAD");
       return c.text("Method Not Allowed", 405);
     }
 
-    const path = resolvePublicAsset(new URL(c.req.url).pathname);
+    const url = new URL(c.req.url);
+    const path = resolvePublicAsset(url.pathname);
     if (!path) return c.notFound();
 
     const sourceFile = Bun.file(path);
@@ -84,8 +121,20 @@ export function servePublicAsset(isDevelopment: boolean) {
     // Development rebuilds files in place under the same address, so the browser asks again on every use; an
     // unchanged file then costs one round trip instead of its whole size on every page.
     const etag = `"${selectedEncoding ?? "identity"}-${selected.size.toString(36)}-${selected.lastModified.toString(36)}"`;
+    // The page head links these files with the version this process names for them. Any other version may name
+    // other content (a rolling deploy, an app started before a Core redeploy), so it is revalidated, never kept.
+    let cacheControl = isDevelopment ? "no-cache" : "public, max-age=31536000, immutable";
+    if (!isDevelopment) {
+      const pathname = decodePathname(url.pathname)!;
+      const shared = /^\/public\/(fonts|tabler-icons|global)\.css$/.test(pathname);
+      const own = /^\/public\/[^/]+\/(app\.css|favicon\.svg)$/.test(pathname);
+      if (shared || own) {
+        const expected = shared ? sharedVersion : publicFileVersion(url.pathname);
+        if (expected === undefined || url.searchParams.get("v") !== expected) cacheControl = "no-cache";
+      }
+    }
     const headers = new Headers({
-      "Cache-Control": isDevelopment ? "no-cache" : "public, max-age=31536000, immutable",
+      "Cache-Control": cacheControl,
       ETag: etag,
       Vary: "Accept-Encoding",
     });

package/src/_internal/status-preserving-ssr.ts

@@ -2,6 +2,7 @@ import type { HtmlFn, RenderFn } from "@k2b/ssr";
 import { createSSRHandler } from "@k2b/ssr/hono";
 import type { Context, Env, MiddlewareHandler, TypedResponse } from "hono";
 import type { StatusCode } from "hono/utils/http-status";
+import type { PanelConsentSnapshot } from "../contracts/panel-context";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { SettingsFlat, Unflatten } from "../contracts/settings-types";
 import type { User } from "../contracts/shared";
@@ -13,6 +14,7 @@ type PageEnv<T extends object> = {
     page: Partial<T>;
     user?: User;
     railPreferences?: RailSnapshot;
+    panelConsent?: PanelConsentSnapshot;
     settings?: Unflatten<SettingsFlat<typeof CORE_SETTINGS>>;
   };
 };

package/src/access/PermissionEditor.tsx

@@ -425,7 +425,7 @@ function AccessEntryRow(props: {
         <Show
           when={props.entry.principal.type === "user"}
           fallback={
-            <div class="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-zinc-600 dark:bg-zinc-700 dark:text-zinc-300">
+            <div class="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-secondary dark:bg-zinc-700">
               <i class={`ti ${getPrincipalIcon(props.entry, t())} text-sm`} />
             </div>
           }
@@ -509,7 +509,7 @@ function AccessEntryRow(props: {
               aria-label={t().remove({ name: displayName() })}
               // A disabled button takes no focus and touch has no hover, so the reason also reaches assistive technology.
               aria-description={props.lastManager ? removeLabel() : undefined}
-              class="focus-ui flex h-7 w-7 items-center justify-center rounded text-zinc-400 transition-colors focus:opacity-100 enabled:hover:bg-red-500/[0.08] enabled:hover:text-red-600 dark:enabled:hover:text-red-400"
+              class="focus-ui flex h-7 w-7 items-center justify-center rounded text-dimmed transition-colors focus:opacity-100 enabled:hover:bg-red-500/[0.08] enabled:hover:text-red-600 dark:enabled:hover:text-red-400"
             >
               <i class="ti ti-x text-sm" />
             </IconButton>

package/src/account/EntitySearch.tsx

@@ -350,7 +350,7 @@ const ResultRow = (props: {
     <Show
       when={props.avatar}
       fallback={
-        <div class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-xs text-zinc-600 dark:bg-zinc-700 dark:text-zinc-300">
+        <div class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-xs text-secondary dark:bg-zinc-700">
           <i class={`ti ${props.icon} text-sm`} />
         </div>
       }