@k2b/cloud 0.36.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -19,6 +19,7 @@
     "!src/**/*.test.tsx",
     "!src/**/*.integration.test.ts",
     "!src/**/*.test-fixture.ts",
+    "!src/**/*.test-fixture.tsx",
     "!scripts/**/*.test.ts",
     "!scripts/runtime-recovery-*.ts"
   ],
@@ -106,8 +107,8 @@
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.16.0",
-    "@k2b/ui": "0.26.0",
+    "@k2b/ssr": "0.17.0",
+    "@k2b/ui": "0.28.0",
     "@k2b/stdlib": "0.29.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
@@ -115,6 +116,7 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.3",
+    "htmlparser2": "12.0.0",
     "jose": "6.2.12",
     "katex": "0.18.9",
     "liquidjs": "10.29.0",

package/scripts/README.md

@@ -3,6 +3,7 @@
 - `build.ts` — production build for one Cloud app (`APP_ID`); used by the Dockerfiles and `bun run build` targets.
 - `preload.ts` — dev-mode preload that registers the SSR plugin and builds CSS before app code loads.
 - `build-canvas-workers.ts` — packages the isolated canvas workers (PDF pages, mobile app icons) and the native canvas for bundles that start them.
+- `cli-pack.ts` — packs a standalone `cld` module with its verified manifest and skill references: `bun run packages/cloud/scripts/cli-pack.ts <module.ts> --references <dir> --out <dir>`. Reads the package name and version from the current directory; publish the output with `npm publish <dir>` or archive it with `npm pack <dir>`.
 - `app-favicon.ts` — generates app favicons from Tabler icons; imported by `build.ts` and `preload.ts`.
 - `browser-performance.ts` — bundles the web-vitals browser asset for core; imported by `build.ts` and `preload.ts`.
 - `runtime-recovery-acceptance.ts` — shared-runtime recovery acceptance on disposable Docker containers: `bun packages/cloud/scripts/runtime-recovery-acceptance.ts` (also `bun run test:runtime-recovery`).

package/scripts/cli-pack.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env bun
+/**
+ * Pack a `cld` module as a package plugin, for authors without a Cloud
+ * application:
+ *
+ *   bun run node_modules/@k2b/cloud/scripts/cli-pack.ts src/cli.ts --references src/cli-references --out dist/cld-plugin
+ *
+ * Writes the same verified bundle the application build writes to
+ * `dist/cli/<name>/` (`cli.js`, `references/`, `manifest.json`), plus a
+ * `package.json` whose `cld.manifest` points at the manifest. Name and version
+ * come from `package.json` in the current directory.
+ */
+import { lstat, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildCliPlugin, writeCliPlugin } from "../src/_internal/cli-plugins";
+import { validateCloudCliModule } from "../src/cli/plugin";
+
+const USAGE = "Usage: bun run node_modules/@k2b/cloud/scripts/cli-pack.ts <module.ts> --references <dir> --out <dir>";
+
+const HELP = `${USAGE}
+
+Packs a cld module as a package plugin: the bundled module cli.js, the skill
+references (index.md plus further Markdown files), manifest.json with the
+SHA-512 of every file, and a package.json with "cld": { "manifest": "manifest.json" }.
+Name and version come from package.json in the current directory.
+
+--out must be missing, empty, or an earlier pack output, which is replaced.
+Ship the result with \`npm publish <out>\` or \`npm pack <out>\`.`;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const readJson = (path: string): Promise<unknown> =>
+  readFile(path, "utf8")
+    .then(JSON.parse)
+    .catch(() => null);
+
+const parseArgs = (args: string[]) => {
+  const [module, ...rest] = args;
+  const flags = new Map<string, string>();
+  for (let index = 0; index < rest.length; index += 2) {
+    const [flag, value] = [rest[index]!, rest[index + 1]];
+    if (!["--references", "--out"].includes(flag) || !value || value.startsWith("-") || flags.has(flag)) throw new Error(USAGE);
+    flags.set(flag, value);
+  }
+  const references = flags.get("--references");
+  const out = flags.get("--out");
+  if (!module || module.startsWith("-") || !references || !out) throw new Error(USAGE);
+  return { module: resolve(module), references: resolve(references), out: resolve(out) };
+};
+
+const containsPath = (directory: string, path: string): boolean => {
+  const inside = relative(directory, path);
+  return inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside);
+};
+
+/** Empty `out` for a fresh pack; anything but an earlier pack output stays untouched. */
+const prepareOut = async (out: string, inputs: string[]): Promise<void> => {
+  const refusal = `Refusing --out ${out}: it must be missing, empty, or an earlier pack output.`;
+  const output = await realpath(out).catch(() => out);
+  for (const input of inputs) {
+    const path = await realpath(input).catch(() => input);
+    if (containsPath(out, input) || containsPath(output, path)) throw new Error(refusal);
+  }
+  const info = await lstat(out).catch(() => null);
+  if (!info) return;
+  if (!info.isDirectory()) throw new Error(refusal);
+  const entries = await readdir(out);
+  if (entries.length === 0) return;
+  const previous = await readJson(join(out, "package.json"));
+  if (
+    entries.some((entry) => !["package.json", "manifest.json", "cli.js", "references"].includes(entry)) ||
+    !isRecord(previous) ||
+    !isRecord(previous.cld) ||
+    previous.cld.manifest !== "manifest.json"
+  )
+    throw new Error(refusal);
+  await rm(out, { recursive: true });
+};
+
+const pack = async (args: string[]): Promise<void> => {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(HELP);
+    return;
+  }
+  const options = parseArgs(args);
+  const cwd = process.cwd();
+  const manifest = await readJson(join(cwd, "package.json"));
+  if (
+    !isRecord(manifest) ||
+    typeof manifest.name !== "string" ||
+    !manifest.name ||
+    typeof manifest.version !== "string" ||
+    !manifest.version
+  ) {
+    throw new Error(`${join(cwd, "package.json")} needs a string name and version.`);
+  }
+  const { name: packageName, version } = manifest;
+  await prepareOut(options.out, [cwd, options.module, options.references]);
+  const loaded: unknown = await import(pathToFileURL(options.module).href);
+  const module = validateCloudCliModule(isRecord(loaded) ? loaded.default : undefined);
+  const plugin = await buildCliPlugin({
+    appDir: cwd,
+    appId: packageName,
+    name: module.name,
+    declaration: { module: options.module, references: options.references },
+    version,
+  });
+  await writeCliPlugin(options.out, plugin);
+  await writeFile(
+    join(options.out, "package.json"),
+    `${JSON.stringify({ name: packageName, version, type: "module", cld: { manifest: "manifest.json" } }, null, 2)}\n`,
+  );
+  const references = plugin.manifest.files.filter((file) => file.path.startsWith("references/")).length;
+  console.log(
+    `Packed ${packageName}@${version} (module "${module.name}", ${references} reference files) to ${options.out}. Ship it with \`npm publish ${options.out}\` or \`npm pack ${options.out}\`.`,
+  );
+};
+
+pack(Bun.argv.slice(2)).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message.replace(/\s*\n\s*/g, " ") : String(error));
+  process.exitCode = 1;
+});

package/src/_internal/help-catalog.ts

@@ -1,5 +1,124 @@
+import { i18n } from "@k2b/stdlib";
+import { formatShortcut } from "@k2b/ui";
+import type { Token } from "marked";
 import type { HelpArticle } from "../services/help/types";
-import { markdownToPlainText } from "../shared/markdown";
+import { parseHelpReference } from "../shared/help";
+import { lexHelpMarkdown, markdownToPlainText } from "../shared/markdown";
+
+const helpAgentMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: { apple: ({ shortcut }: { shortcut: string }) => `${shortcut} on Mac` },
+    de: { apple: ({ shortcut }) => `${shortcut} auf dem Mac` },
+  },
+});
+
+const helpLinkLabel = (source: string, fallback: string): string => {
+  // Index backtick runs once so unmatched runs cannot repeatedly scan the remaining source.
+  const backticks = new Map<number, { positions: number[]; next: number }>();
+  for (const run of source.matchAll(/`+/g)) {
+    const length = run[0].length;
+    if (!backticks.has(length)) backticks.set(length, { positions: [], next: 0 });
+    backticks.get(length)!.positions.push(run.index);
+  }
+  let depth = 0;
+  for (let index = 1; index < source.length; index++) {
+    const char = source[index];
+    if (char === "\\") index++;
+    else if (char === "`") {
+      let end = index + 1;
+      while (source[end] === "`") end++;
+      const length = end - index;
+      const runs = backticks.get(length);
+      if (runs) {
+        while (runs.next < runs.positions.length && runs.positions[runs.next]! <= index) runs.next++;
+      }
+      const closing = runs?.positions[runs.next];
+      index = closing === undefined ? end - 1 : closing + length - 1;
+    } else if (char === "[") depth++;
+    else if (char === "]") {
+      if (depth === 0) return source.slice(1, index);
+      depth--;
+    }
+  }
+  return fallback;
+};
+
+/** Portable source for agents and Copy as Markdown; code is kept verbatim. */
+export const helpAgentMarkdown = (
+  article: Pick<HelpArticle, "markdown" | "locale" | "appId" | "links">,
+  tokens: readonly Token[] = lexHelpMarkdown(article.markdown, article.locale),
+): string => {
+  const { t } = helpAgentMessages.resolve([article.locale]);
+  const rewriteChildren = (raw: string, children: readonly Token[]): string => {
+    let offset = 0;
+    let result = "";
+    for (const child of children) {
+      let start = raw.indexOf(child.raw, offset);
+      let source = child.raw;
+      if (start < 0 && child.raw.includes("|")) {
+        source = child.raw.replaceAll("|", "\\|");
+        start = raw.indexOf(source, offset);
+      }
+      // Marked removes quote markers and list indentation from child block sources.
+      if (start < 0 && child.raw.includes("\n")) {
+        const pattern = child.raw
+          .split("\n")
+          .map((line, index) => (index > 0 ? line.replace(/^[ \t]+/, "") : line).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+          .join("\\r?\\n[ \\t>]*");
+        const match = new RegExp(pattern).exec(raw.slice(offset));
+        if (match) {
+          start = offset + match.index;
+          source = match[0];
+        }
+      }
+      if (start < 0) break;
+      result += raw.slice(offset, start) + rewrite(child, source);
+      offset = start + source.length;
+    }
+    return result + raw.slice(offset);
+  };
+  const rewrite = (token: Token, source: string): string => {
+    if (token.type === "code" || token.type === "codespan") return source;
+    if (token.type === "helpKbd") {
+      const keys = String(token.keys);
+      const other = formatShortcut(keys, { platform: "other", locale: article.locale });
+      const apple = formatShortcut(keys, { platform: "apple", locale: article.locale }).label;
+      // Key labels such as | or ` stay text in a table cell or a sentence.
+      const escape = (text: string) => text.replace(/[\\`*_[\]|<>~]/g, "\\$&");
+      // A key without a platform modifier reads by its name: "Enter", not "↵".
+      return other.label === apple ? escape(other.name) : `${escape(other.label)} (${t.apple({ shortcut: escape(apple) })})`;
+    }
+    if (token.type === "helpDetails") {
+      const newline = source.includes("\r\n") ? "\r\n" : "\n";
+      const bodyStart = source.indexOf("\n") + 1;
+      const closing = [...source.matchAll(/^[ \t>]*:::[ \t]*(?:\r?\n|$)/gm)].at(-1)!;
+      const body = source.slice(bodyStart, closing.index);
+      const prefix = body.match(/^[ \t>]+/)?.[0] ?? "";
+      const trailing = source.slice(closing.index + closing[0].length);
+      return `**${rewriteChildren(String(token.title), token.titleTokens ?? [])}**${newline}${prefix}${newline}${rewriteChildren(body, token.tokens ?? [])}${trailing}`;
+    }
+    if (token.type === "helpLabel") return rewriteChildren(source.replace(/\{icon="[a-z0-9-]+"\}$/, ""), token.tokens ?? []);
+    if (token.type === "link" && token.href.startsWith("help:")) {
+      const ref = parseHelpReference(token.href.slice(5));
+      const target = ref && article.links[`${ref.appId ?? article.appId}/${ref.documentId}`];
+      const label = rewriteChildren(helpLinkLabel(source, token.text), token.tokens ?? []);
+      return target ? `[${label}](${target.url}${ref.fragment})` : label;
+    }
+    const children =
+      token.type === "list"
+        ? token.items
+        : token.type === "table"
+          ? [...token.header, ...token.rows.flat()].flatMap((cell) => cell.tokens)
+          : "tokens" in token
+            ? (token.tokens ?? [])
+            : [];
+    const raw = rewriteChildren(source, children);
+    return token.type === "heading" ? raw.replace(/[ \t]+\{icon="[a-z0-9-]+"\}(?=[ \t]*\r?\n?$)/i, "") : raw;
+  };
+  return rewriteChildren(article.markdown, tokens);
+};
+
 export const HELP_SEARCH_MAX_LIMIT = 25;
 export const HELP_READ_MAX_CHARS = 7_000;
 const normalizeSearchText = (value: string): string =>
@@ -33,7 +152,7 @@ const boundedExcerpt = (markdown: string, terms: readonly string[]): string => {
   return `${start > 0 ? `${marker}\n\n` : ""}${body}${start + budget < markdown.length ? `\n\n${marker}` : ""}`;
 };
 
-export const selectHelpMarkdown = (markdown: string, query?: string): { markdown: string; truncated: boolean } => {
+export const selectHelpMarkdown = (markdown: string, query?: string, locale?: string): { markdown: string; truncated: boolean } => {
   // An exact heading identifies one complete reference section, even in short articles.
   const headingQuery = query?.trim().toLocaleLowerCase();
   const exact =
@@ -53,7 +172,7 @@ export const selectHelpMarkdown = (markdown: string, query?: string): { markdown
   const phrase = normalizeSearchText(query ?? "");
   const ranked = splitSections(markdown)
     .map((section, index) => {
-      const text = normalizeSearchText(markdownToPlainText(section));
+      const text = normalizeSearchText(markdownToPlainText(section, locale));
       const score = (phrase && text.includes(phrase) ? 10 : 0) + terms.filter((term) => text.includes(term)).length;
       return { section, index, score };
     })
@@ -79,7 +198,7 @@ export const readHelpArticle = (document: HelpArticle, query?: string) => ({
   documentId: document.documentId,
   title: document.title,
   description: document.description,
-  ...selectHelpMarkdown(document.markdown, query),
+  ...selectHelpMarkdown(helpAgentMarkdown(document), query, document.locale),
 });
 
 export const helpResourceUri = (appId: string, documentId: string): string =>

package/src/_internal/help.ts

@@ -2,28 +2,49 @@ import { createHash } from "node:crypto";
 import type { AppRegistryHelpSummary } from "../contracts/registry";
 import type { HelpDefinition } from "../server/help";
 import type { HelpCorpus, HelpDocument } from "../services/help/types";
+import { parseHelpReference } from "../shared/help";
+import { lexHelpMarkdown, walkHelpTokens } from "../shared/markdown";
 
 export const HELP_DOCUMENT_MAX_BYTES = 128 * 1024;
+// defineHelp documents are frozen; retain only their validated targets, not the token trees.
+export const helpLinkTargets = new WeakMap<object, readonly string[]>();
 export type CompiledHelp = { summary: AppRegistryHelpSummary; corpus: HelpCorpus };
 
 export const compileHelp = (input: { appId: string; basePath?: string; definition: HelpDefinition }): CompiledHelp => {
-  const compileDocuments = (source: HelpDefinition["documents"]): HelpDocument[] =>
-    source.map(({ id, title, icon, description, order, markdown, searchText }) => {
+  const baseIds = new Set(input.definition.documents.map((document) => document.id));
+  const compileDocuments = (source: HelpDefinition["documents"], locale: string): HelpDocument[] =>
+    source.map((document) => {
+      const { id, title, icon, description, order, kind, needs, next, related, markdown, searchText } = document;
       if (Buffer.byteLength(markdown) > HELP_DOCUMENT_MAX_BYTES) {
         throw new Error(`Help document "${id}" exceeds the ${HELP_DOCUMENT_MAX_BYTES}-byte limit`);
       }
-      return { id, title, icon, description, order, markdown, searchText };
+      const validate = (reference: string) => {
+        const ref = parseHelpReference(reference);
+        if (ref?.appId === input.appId && !baseIds.has(ref.documentId))
+          throw new Error(`Help locale "${locale}" document "${id}" has unknown reference "${reference}"`);
+      };
+      for (const reference of related) validate(reference);
+      const targets = helpLinkTargets.get(document);
+      if (targets) {
+        for (const target of targets) validate(target);
+      } else {
+        walkHelpTokens(lexHelpMarkdown(markdown, locale), (token) => {
+          if (token.type === "link" && token.href.startsWith("help:")) validate(token.href.slice(5));
+        });
+      }
+      return { id, title, icon, description, order, kind, needs, next, related, markdown, searchText };
     });
   const baseLocale = input.definition.baseLocale ?? "en";
-  const documents = compileDocuments(input.definition.documents);
+  const documents = compileDocuments(input.definition.documents, baseLocale);
   const documentsByLocale = Object.fromEntries(
     Object.entries(input.definition.documentsByLocale ?? {})
       .filter(([locale]) => locale !== baseLocale)
       .sort(([a], [b]) => a.localeCompare(b))
-      .map(([locale, docs]) => [locale, compileDocuments(docs)]),
+      .map(([locale, docs]) => [locale, compileDocuments(docs, locale)]),
   );
+  // A revision bump republishes every corpus, here to fill the new metadata columns.
   const manifestHash = createHash("sha256")
-    .update(JSON.stringify({ revision: 1, appId: input.appId, baseLocale, documents, documentsByLocale }))
+    .update(JSON.stringify({ revision: 2, appId: input.appId, baseLocale, documents, documentsByLocale }))
     .digest("hex");
   return {
     summary: { manifestHash, pageBase: `${input.basePath?.replace(/\/$/, "") ?? ""}/help`, baseLocale },

package/src/_internal/shell-focus.ts

@@ -0,0 +1,11 @@
+export const SHELL_FOCUS_COOKIE = "cloud_shell_focus";
+
+export const readShellFocusCookie = (cookieHeader: string | null | undefined): boolean =>
+  cookieHeader
+    ?.split(";")
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${SHELL_FOCUS_COOKIE}=`))
+    ?.slice(SHELL_FOCUS_COOKIE.length + 1) === "1";
+
+export const shellFocusCookie = (hidden: boolean, secure: boolean): string =>
+  `${SHELL_FOCUS_COOKIE}=${hidden ? "1" : ""}; Path=/; Max-Age=${hidden ? 31536000 : 0}; SameSite=Lax${secure ? "; Secure" : ""}`;

package/src/access/PermissionEditor.browser-harness.tsx

@@ -0,0 +1,46 @@
+import { LocaleProvider } from "@k2b/ui";
+import { render } from "solid-js/web";
+import PermissionEditor from "./PermissionEditor";
+
+const host = document.getElementById("root");
+if (!host) throw new Error("Missing harness root");
+render(
+  () => (
+    <LocaleProvider locale="en">
+      <PermissionEditor
+        initialEntries={["Mara Lind", "Lea Sommer", "Jonas Weber"].map((displayName, index) => ({
+          id: `access-${index}`,
+          principal: { type: "user", userId: `user-${index}` },
+          displayName,
+          permission: "read",
+          createdAt: "2026-10-15T07:00:00.000Z",
+        }))}
+        // Equal-width labels isolate pending-state layout from a normal change in label width.
+        allowedLevels={[
+          { level: "read", label: "Level 1" },
+          { level: "write", label: "Level 2" },
+        ]}
+        allowAuthenticated={false}
+        grantAccess={async () => {
+          throw new Error("Not used");
+        }}
+        updateAccess={() =>
+          new Promise<void>((resolve) => {
+            // The test waits for this mark, so it does not depend on how the editor shows a pending change.
+            document.documentElement.dataset.saving = "true";
+            document.addEventListener(
+              "settle-access",
+              () => {
+                delete document.documentElement.dataset.saving;
+                resolve();
+              },
+              { once: true },
+            );
+          })
+        }
+        revokeAccess={async () => {}}
+      />
+    </LocaleProvider>
+  ),
+  host,
+);

package/src/access/PermissionEditor.tsx

@@ -236,8 +236,16 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   };
 
   type LevelChange = { accessId: string; permission: GrantableLevel; scope: string | undefined };
+  // The row whose change is saving: it shows the chosen level with a spinner, the other rows wait.
+  const [updating, setUpdating] = createSignal<LevelChange | null>(null);
+  const [revoking, setRevoking] = createSignal<string | null>(null);
+  const updatingRow = (accessId: string) => {
+    const change = updating();
+    return change?.accessId === accessId ? change : undefined;
+  };
   const updateMut = mutation.create<LevelChange, LevelChange>({
     mutation: async (data) => {
+      setUpdating(data);
       await props.updateAccess(data.accessId, data.permission, data.scope);
       return data;
     },
@@ -247,6 +255,9 @@ export default function PermissionEditor(props: PermissionEditorProps) {
       }
     },
     onError: (err) => prompts.error(err.message),
+    onFinally: () => {
+      if (!disposed) setUpdating(null);
+    },
   });
 
   const revokeMut = mutation.create<string | null, AccessEntry>({
@@ -257,6 +268,7 @@ export default function PermissionEditor(props: PermissionEditorProps) {
         variant: "danger",
       });
       if (!confirmed) return null;
+      setRevoking(entry.id);
       await props.revokeAccess(entry.id);
       return entry.id;
     },
@@ -264,6 +276,9 @@ export default function PermissionEditor(props: PermissionEditorProps) {
       if (accessId) setEntries((current) => current.filter((entry) => entry.id !== accessId));
     },
     onError: (err) => prompts.error(err.message),
+    onFinally: () => {
+      if (!disposed) setRevoking(null);
+    },
   });
   const busy = () => grantPending() || updateMut.loading() || revokeMut.loading();
   // The service refuses to remove the last manager; the row says so up front.
@@ -288,6 +303,8 @@ export default function PermissionEditor(props: PermissionEditorProps) {
                 coverage={coverage}
                 canEdit={canEdit()}
                 pending={entry.id === pending()}
+                updating={updatingRow(entry.id)}
+                revoking={entry.id === revoking()}
                 disabled={busy()}
                 lastManager={entry.id === lastManagerId()}
                 allowed={allowed(entry.principal)}
@@ -332,8 +349,14 @@ export default function PermissionEditor(props: PermissionEditorProps) {
 function AccessEntryRow(props: {
   entry: AccessEntry;
   canEdit: boolean;
+  /** Another change is saving: the row keeps its controls, disabled. */
   disabled: boolean;
+  /** This row's grant is saving. */
   pending?: boolean;
+  /** This row's level change is saving. */
+  updating?: { permission: GrantableLevel; scope: string | undefined };
+  /** This row's removal is saving. */
+  revoking?: boolean;
   /** The only entry that manages the resource: it keeps its level and cannot be removed. */
   lastManager: boolean;
   allowed: ResolvedLevel[];
@@ -352,8 +375,14 @@ function AccessEntryRow(props: {
   const display = () => resolveEntryDisplay(props.entry.permission, props.entry.scope, props.allowed, t());
   const manageLabel = () => resolveEntryDisplay("admin", undefined, props.allowed, t()).label;
   const removeLabel = () => (props.lastManager ? t().lastManager({ level: manageLabel() }) : t().remove({ name: displayName() }));
-  const isInteractive = () =>
-    props.canEdit && !props.disabled && !props.pending && !props.singlePicker && props.allowed.some((option) => option.key === entryKey());
+  // Whether the row offers a picker depends only on what the viewer may do, never on a change in flight, so a
+  // saving change never swaps the picker for the badge and the rows keep their size.
+  const hasPicker = () => props.canEdit && !props.singlePicker && props.allowed.some((option) => option.key === entryKey());
+  const saving = () => props.pending || props.updating !== undefined || props.revoking === true;
+  // While a level change saves, the picker already shows the chosen level.
+  const shownKey = () => (props.updating ? levelKey(props.updating.permission, props.updating.scope) : entryKey());
+  const shownDisplay = () =>
+    props.updating ? resolveEntryDisplay(props.updating.permission, props.updating.scope, props.allowed, t()) : display();
 
   const badgeClass =
     "flex min-h-7 items-center gap-1 rounded-full border border-transparent bg-[var(--ui-surface-muted)] px-2.5 py-1 text-xs text-secondary";
@@ -362,15 +391,12 @@ function AccessEntryRow(props: {
     <>
       <i class={props.pending ? "ti ti-loader-2 animate-spin" : `ti ${display().icon}`} />
       <span>{display().label}</span>
-      <Show when={isInteractive()}>
-        <i class="ti ti-chevron-down text-[10px]" />
-      </Show>
     </>
   );
 
   return (
     <div>
-      <div class="group/access-row flex items-center gap-2 py-1.5" aria-busy={props.pending ? "true" : undefined}>
+      <div class="group/access-row flex items-center gap-2 py-1.5" aria-busy={saving() ? "true" : undefined}>
         <Show
           when={props.entry.principal.type === "user"}
           fallback={
@@ -415,10 +441,12 @@ function AccessEntryRow(props: {
 
         {/* Permission badge — interactive single-value picker when editable,
           plain span otherwise. */}
-        <Show when={isInteractive()} fallback={<span class={`${badgeClass} cursor-default`}>{badgeContent}</span>}>
+        <Show when={hasPicker()} fallback={<span class={`${badgeClass} cursor-default`}>{badgeContent}</span>}>
           <SelectChip
             aria-label={t().permissionFor({ name: displayName() })}
-            value={entryKey}
+            value={shownKey}
+            disabled={props.disabled}
+            loading={props.pending || props.updating !== undefined}
             options={props.allowed.map((option) => {
               const locked = props.lastManager && (option.level !== "admin" || option.scope !== undefined);
               return {
@@ -429,7 +457,7 @@ function AccessEntryRow(props: {
                 description: locked ? t().lastManagerOption({ level: manageLabel() }) : option.description,
               };
             })}
-            icon={`ti ${display().icon}`}
+            icon={`ti ${shownDisplay().icon}`}
             position="bottom-left"
             onValueChange={(key) => {
               const option = props.allowed.find((candidate) => candidate.key === key);
@@ -452,6 +480,7 @@ function AccessEntryRow(props: {
               size="xs"
               onClick={props.onRevoke}
               disabled={props.disabled || props.pending || props.lastManager}
+              loading={props.revoking}
               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}

package/src/access/ui.ts

@@ -6,6 +6,7 @@
  * from depending on Cloud's broad legacy UI entrypoint.
  */
 
+export { isManagerEntry, type ManagerCandidate } from "./managers";
 export type { AllowedLevel, GrantableLevel } from "./PermissionEditor";
 export { default as PermissionEditor } from "./PermissionEditor";
 export { default as PrincipalPicker, principalKey } from "./PrincipalPicker";

package/src/account/Avatar.tsx

@@ -1,10 +1,14 @@
 import { Avatar, type AvatarProps } from "@k2b/ui";
 import type { JSX } from "solid-js";
 
-export type CloudAvatarProps = Omit<AvatarProps, "name" | "src"> & {
+/** Who an avatar stands for; agents and service accounts are square, people round. */
+export type CloudAvatarKind = "user" | "service_account" | "system";
+
+export type CloudAvatarProps = Omit<AvatarProps, "name" | "src" | "shape" | "icon"> & {
   username: string;
   userId?: string | null;
   avatarHash?: string | null;
+  kind?: CloudAvatarKind;
 };
 
 const avatarSource = (userId?: string | null, avatarHash?: string | null): string | undefined => {
@@ -12,14 +16,28 @@ const avatarSource = (userId?: string | null, avatarHash?: string | null): strin
   return `/api/accounts/users/${encodeURIComponent(userId)}/avatar?rev=${encodeURIComponent(avatarHash)}`;
 };
 
+/** The URL of a person's uploaded picture, or undefined when there is none. */
+export const cloudAvatarSource = avatarSource;
+
+const KIND_ICON: Record<CloudAvatarKind, string | undefined> = {
+  user: undefined,
+  service_account: "ti ti-robot",
+  system: "ti ti-settings-automation",
+};
+
+/** One avatar for every Cloud surface: the uploaded picture when there is one, otherwise initials. */
 export function CloudAvatar(props: CloudAvatarProps): JSX.Element {
+  const kind = () => props.kind ?? "user";
   return (
     <Avatar
       name={props.username}
-      src={avatarSource(props.userId, props.avatarHash)}
+      src={kind() === "user" ? avatarSource(props.userId, props.avatarHash) : undefined}
+      icon={KIND_ICON[kind()]}
+      shape={kind() === "user" ? "circle" : "square"}
       alt={props.alt}
       fallback={props.fallback}
       size={props.size}
+      ring={props.ring}
       loading={props.loading}
       class={props.class}
       style={props.style}

package/src/account/ui.ts

@@ -1,3 +1,3 @@
-export { CloudAvatar, type CloudAvatarProps } from "./Avatar";
+export { CloudAvatar, type CloudAvatarKind, type CloudAvatarProps, cloudAvatarSource } from "./Avatar";
 export { type AvatarUploadDialogOptions, openAvatarUploadDialog } from "./avatar-upload-dialog";
 export { default as EntitySearch, type EntitySearchPrincipal } from "./EntitySearch";

package/src/ai/browser.ts

@@ -25,6 +25,7 @@ export {
   cloudAiChartRenderOptions,
   cloudAiChartRows,
   cloudAiChartTable,
+  cloudAiChartTooltip,
   cloudAiChartXValueFormat,
   cloudAiNumberFormatters,
 } from "./chart-block";