@k2b/cloud 0.38.0 → 0.40.0

package/src/_internal/capability-reviews.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { capabilityPreviewIssues, capabilityReviewFormIssues } from "../capabilities/reviews";
+import {
+  CAPABILITY_REACHES,
+  CapabilityActionCheckSchema,
+  type CapabilityActionPolicy,
+  CapabilityActionReceiptSchema,
+  CapabilityActionReviewDataSchema,
+  type CapabilityQueryManifest,
+  CapabilitySemanticLinkSchema,
+} from "../contracts/capabilities";
+import { localeFallbackChain } from "../shared/locale";
+import { capabilityHash, projectSchema } from "./capability-schemas";
+
+export {
+  actionReview,
+  type CapabilityReviewForms,
+  capabilityReviewFormIssues,
+  capabilityReviewRememberScope,
+  capabilityReviewView,
+  type SlotNames,
+} from "../capabilities/reviews";
+
+export { CAPABILITY_MAX_REVIEW_BYTES } from "../contracts/capabilities";
+export type CapabilityReviewContext = {
+  policy?: CapabilityActionPolicy;
+  approval?: "rememberable" | "none";
+  queries: readonly CapabilityQueryManifest[];
+  validateQueryInput: (query: CapabilityQueryManifest, input: Record<string, unknown>) => boolean;
+  locales?: readonly string[];
+};
+const schemaIssues = (error: z.ZodError): string[] => error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+let actionCheckDataHash: string | undefined;
+/** Whether a Query answers an Action's `check`: its data schema is exactly the projected `CapabilityActionCheckSchema`. */
+export const capabilityQueryChecksActionOutcome = (query: CapabilityQueryManifest): boolean => {
+  actionCheckDataHash ??= capabilityHash(projectSchema(CapabilityActionCheckSchema, "Action check", "output"));
+  return capabilityHash(query.dataSchema) === actionCheckDataHash;
+};
+
+export const capabilityActionReviewIssues = (review: unknown, context: CapabilityReviewContext): string[] => {
+  const parsed = CapabilityActionReviewDataSchema.safeParse(review);
+  if (!parsed.success) return schemaIssues(parsed.error);
+  const data = parsed.data;
+  if (!("sentence" in data))
+    return context.policy
+      ? ["A policy Action must return a new review"]
+      : data.approvalScope !== undefined && context.approval !== "rememberable"
+        ? ["approvalScope requires rememberable approval"]
+        : [];
+  if (!context.policy) return ["An Action without policy must return a legacy review"];
+  const issues = capabilityReviewFormIssues(data);
+  if (
+    data.reach !== undefined &&
+    (!("silent" in context.policy) || CAPABILITY_REACHES.indexOf(data.reach) > CAPABILITY_REACHES.indexOf(context.policy.silent))
+  )
+    issues.push("reach exceeds the declared silent reach");
+  if (context.locales && !localeFallbackChain(data.locale, data.locale).some((locale) => context.locales?.includes(locale)))
+    issues.push("locale is not supported by the app");
+  if (data.check) {
+    const query = context.queries.find((query) => query.localId === data.check?.query);
+    if (!query || !capabilityQueryChecksActionOutcome(query)) issues.push("check.query must return CapabilityActionCheckSchema");
+    else if (!context.validateQueryInput(query, data.check.input)) issues.push("check.input does not match the Query");
+  }
+  issues.push(
+    ...capabilityPreviewIssues(
+      data.preview,
+      data.links,
+      // A per-call reason never lifts the declared `sends` completeness rule.
+      data.ask === "sends" || ("ask" in context.policy && context.policy.ask === "sends"),
+    ),
+  );
+  return [...new Set(issues)];
+};
+/** A receipt's own rules; completeness links are the result envelope's top-level `links`. */
+export const capabilityActionReceiptIssues = (receipt: unknown, links: unknown): string[] => {
+  const parsed = CapabilityActionReceiptSchema.safeParse(receipt);
+  const resultLinks = z.array(CapabilitySemanticLinkSchema).safeParse(links);
+  return parsed.success
+    ? capabilityPreviewIssues(parsed.data.preview, resultLinks.success ? resultLinks.data : undefined)
+    : schemaIssues(parsed.error);
+};

package/src/_internal/capability-schemas.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+type JsonSchema = Record<string, unknown>;
+export const stableJsonValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(stableJsonValue);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, stableJsonValue(entry)]),
+  );
+};
+
+export const capabilityHash = (value: unknown): string =>
+  createHash("sha256")
+    .update(JSON.stringify(stableJsonValue(value)))
+    .digest("hex");
+
+export const projectSchema = (schema: z.ZodType, label: string, io: "input" | "output"): JsonSchema => {
+  try {
+    const projected = z.toJSONSchema(schema, { io });
+    z.fromJSONSchema(projected);
+    return projected;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${label} is not JSON-Schema-round-trippable: ${message}`);
+  }
+};

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";
@@ -89,15 +91,15 @@ import { configurePostgresApplicationName } from "./postgres-application-name";
 import { getProcessSync, startProcessSync } from "./process-sync";
 import { APP_READINESS_PATH, appReadinessResponse } from "./readiness";
 import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
-import { canonicalRoute, isOwnNavBadge } from "./registry-validation";
-import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
-import { servePublicAsset } from "./static-assets";
+import { canonicalRoute, isOwnAppPath } from "./registry-validation";
+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 ────────────────────────────────────────────────────────────
 
@@ -144,6 +146,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
     label: string;
     links: ReadonlyArray<{ label: string; href: string; icon: string }>;
   }>;
+  panel?: AppMeta["panel"];
   nav?: {
     href: string;
     match?: string;
@@ -371,11 +374,38 @@ const validateAppPwaPart = (opts: Pick<AppOptions, "id" | "routes" | "pwa">): Ap
 /** The badge route is read by the browser through the gateway, so it must be one of this app's own paths. */
 const validateAppNavBadge = (opts: Pick<AppOptions, "id" | "routes" | "nav">): void => {
   const badge = opts.nav?.badge;
-  if (badge !== undefined && !isOwnNavBadge(badge, opts.routes)) {
+  if (badge !== undefined && !isOwnAppPath(badge, opts.routes)) {
     throw new Error(`App "${opts.id}" declares nav.badge "${badge}"; it must be a same-origin path below one of its routes`);
   }
 };
 
+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`);
+  }
+  if (
+    panel.requiresRoles !== undefined &&
+    (!Array.isArray(panel.requiresRoles) || !panel.requiresRoles.every((role) => typeof role === "string"))
+  ) {
+    throw new Error(`App "${opts.id}" declares panel.requiresRoles; it must be an array of strings`);
+  }
+  return { ...panel, requiresRoles: panel.requiresRoles ? [...panel.requiresRoles] : undefined };
+};
+
 export const defineApp = <
   const S extends AppSettingsMap = {},
   const N extends NotificationDefinitionMap = {},
@@ -391,6 +421,7 @@ export const defineApp = <
   const cliModules = validateAppCliModules(opts.id, opts.cli);
   const pwaPart = validateAppPwaPart(opts);
   validateAppNavBadge(opts);
+  const panel = validateAppPanel(opts);
 
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
@@ -412,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
@@ -456,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}
@@ -498,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,
       ]);
     }),
@@ -528,6 +571,7 @@ export const defineApp = <
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     pwa: pwaPart,
+    panel,
     widgets: compileWidgetDeclarations(opts.id, opts.widgets),
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
@@ -627,6 +671,9 @@ export const defineApp = <
         pwa: meta.pwa
           ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
           : undefined,
+        panel: meta.panel
+          ? { ...meta.panel, requiresRoles: meta.panel.requiresRoles ? [...meta.panel.requiresRoles] : undefined }
+          : undefined,
         widgets: meta.widgets?.map((widget) => ({
           ...widget,
           ...(widget.settings ? { settings: structuredClone(widget.settings) } : {}),
@@ -715,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/panel-cookie.ts

@@ -0,0 +1,39 @@
+export const PANEL_COOKIE = "cloud_panel";
+export const PANEL_MIN_WIDTH_REM = 20;
+export const PANEL_MAX_WIDTH_REM = 36;
+
+export type PanelCookieState = { open: boolean; provider?: string; widthRem?: number };
+const clampWidth = (value: number) => Math.min(PANEL_MAX_WIDTH_REM, Math.max(PANEL_MIN_WIDTH_REM, value));
+
+export function readPanelCookie(cookieHeader: string | null | undefined, providers: readonly string[]): PanelCookieState {
+  const value = cookieHeader
+    ?.split(";")
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${PANEL_COOKIE}=`))
+    ?.slice(PANEL_COOKIE.length + 1);
+  if (value === undefined) return { open: false };
+  const parts = value.split(":");
+  const [open, encodedProvider, width] = parts;
+  if (
+    parts.length !== 3 ||
+    (open !== "0" && open !== "1") ||
+    encodedProvider === undefined ||
+    width === undefined ||
+    (width !== "" && !/^\d{1,2}(\.\d{1,2})?$/.test(width))
+  )
+    return { open: false };
+  let provider: string;
+  try {
+    provider = decodeURIComponent(encodedProvider);
+    if (encodeURIComponent(provider) !== encodedProvider) return { open: false };
+  } catch {
+    return { open: false };
+  }
+  if ((provider && !providers.includes(provider)) || (open === "1" && !provider)) return { open: false };
+  return { open: open === "1", ...(provider ? { provider } : {}), ...(width ? { widthRem: clampWidth(Number(width)) } : {}) };
+}
+
+export function serializePanelCookie(state: PanelCookieState, secure: boolean): string {
+  const width = state.widthRem !== undefined && Number.isFinite(state.widthRem) ? Math.round(clampWidth(state.widthRem) * 100) / 100 : "";
+  return `${PANEL_COOKIE}=${state.open && state.provider ? "1" : "0"}:${encodeURIComponent(state.provider ?? "")}:${width}; Path=/; Max-Age=31536000; SameSite=Lax${secure ? "; Secure" : ""}`;
+}