@k2b/cloud 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -30,7 +30,7 @@
     "./server/*": "./src/server/*",
     "./browser": "./src/server/api-client.ts",
     "./browser/app-approval": "./src/browser/app-approval.ts",
-    "./browser/live": "./src/browser/live-websocket.ts",
+    "./browser/live": "./src/browser/live.ts",
     "./browser/mermaid": "./src/browser/mermaid.ts",
     "./browser/reload": "./src/browser/reload.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
@@ -74,6 +74,7 @@
     "./contracts": "./src/contracts/index.ts",
     "./contracts/notifications": "./src/contracts/notification-types.ts",
     "./contracts/*": "./src/contracts/*",
+    "./events": "./src/events/index.ts",
     "./workflows": "./src/workflows/index.ts",
     "./workflows/ai": "./src/workflows/ai/index.ts",
     "./workflows/editor": "./src/workflows/editor.ts",
@@ -98,7 +99,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.12.0",
+    "@k2b/ui": "0.13.0",
     "@k2b/stdlib": "0.27.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/scripts/README.md

@@ -2,7 +2,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-pdf-renderer.ts` — packages the PDF decoder and native assets for bundles that import PDF vision.
+- `build-canvas-workers.ts` — packages the isolated canvas workers (PDF pages, mobile app icons) and the native canvas for bundles that start them.
 - `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/build-canvas-workers.ts

@@ -0,0 +1,58 @@
+import { cp, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+/** Isolated native canvas workers, each packaged only when the server bundle reaches the module that starts it. */
+const CANVAS_WORKERS = [
+  { reachedBy: "/ai/pdf-render.ts", entry: "src/ai/pdf-render-worker.ts", output: "pdf-worker.js", packages: ["pdfjs-dist"] },
+  {
+    reachedBy: "/services/branding/app-icons.ts",
+    entry: "src/services/branding/icon-render-worker.ts",
+    output: "icon-worker.js",
+    packages: [],
+  },
+] as const;
+
+/**
+ * Writes `dist/canvas/<worker>.js` for every canvas worker the bundle needs, with one copy of `@napi-rs/canvas`, its
+ * installed platform binary and the workers' other packages in `dist/canvas/node_modules`.
+ */
+export async function buildCanvasWorkers(dist: string, bundledInputs: readonly string[]) {
+  const workers = CANVAS_WORKERS.filter((worker) => bundledInputs.some((path) => path.endsWith(worker.reachedBy)));
+  if (workers.length === 0) return;
+  const framework = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const out = resolve(dist, "canvas");
+  await mkdir(out, { recursive: true });
+  const external = ["@napi-rs/canvas", ...workers.flatMap((worker) => worker.packages)];
+  for (const worker of workers) {
+    const build = await Bun.build({
+      entrypoints: [resolve(framework, worker.entry)],
+      target: "bun",
+      outdir: out,
+      naming: worker.output,
+      external,
+    });
+    if (!build.success) throw new Error(`Canvas worker ${worker.output} build failed: ${build.logs.join("\n")}`);
+  }
+  for (const name of external) {
+    const source = dirname(Bun.resolveSync(`${name}/package.json`, framework));
+    await cp(source, resolve(out, "node_modules", name), { recursive: true, dereference: true });
+    if (name !== "@napi-rs/canvas") continue;
+    const manifest = z
+      .object({ optionalDependencies: z.record(z.string(), z.string()) })
+      .parse(await Bun.file(resolve(source, "package.json")).json());
+    let nativePackages = 0;
+    for (const dependency of Object.keys(manifest.optionalDependencies)) {
+      let location: string;
+      try {
+        location = dirname(Bun.resolveSync(`${dependency}/package.json`, source));
+      } catch {
+        continue;
+      } // Only the installed target-platform binary is needed.
+      await cp(location, resolve(out, "node_modules", dependency), { recursive: true, dereference: true });
+      nativePackages++;
+    }
+    if (!nativePackages) throw new Error("Canvas workers need an installed native canvas binary for the build platform.");
+  }
+}

package/scripts/build.ts

@@ -35,7 +35,7 @@ import tailwind from "bun-plugin-tailwind";
 import type { AppCliModules } from "../src/contracts/app";
 import { writeAppFavicon } from "./app-favicon";
 import { buildBrowserPerformance } from "./browser-performance";
-import { buildPdfRenderer } from "./build-pdf-renderer";
+import { buildCanvasWorkers } from "./build-canvas-workers";
 
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
@@ -132,7 +132,8 @@ try {
       __CLOUD_VERSION__: JSON.stringify(version),
       __CLOUD_RELEASE__: JSON.stringify(release),
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
-      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./pdf-render/worker.js"),
+      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./canvas/pdf-worker.js"),
+      __CLOUD_ICON_RENDER_WORKER__: JSON.stringify("./canvas/icon-worker.js"),
       __CLOUD_APP_ASSETS__: JSON.stringify("./assets/"),
       __CLOUD_CLI_PLUGINS__: JSON.stringify("./cli/"),
     },
@@ -145,9 +146,7 @@ if (!server.success) {
   for (const m of server.logs) console.error(m);
   throw new Error("Server bundle failed");
 }
-if (Object.keys(server.metafile?.inputs ?? {}).some((path) => path.endsWith("/ai/pdf-render.ts"))) {
-  await buildPdfRenderer(dist);
-}
+await buildCanvasWorkers(dist, Object.keys(server.metafile?.inputs ?? {}));
 
 // 2. Per-app Tailwind stylesheet.
 const appCss = resolve(appDir, "src/styles/app.css");

package/src/_internal/canvas-worker.ts

@@ -0,0 +1,24 @@
+import { fileURLToPath } from "node:url";
+
+/**
+ * Starts a native canvas worker (PDF pages, app icons) in a process of its own. RLIMIT_DATA bounds the decoder heap
+ * and native writable mappings on Linux. Positional arguments keep paths out of shell code; no elevated privileges.
+ * The caller owns the deadline and kills the process on abort.
+ */
+export const spawnCanvasWorker = (worker: URL, name: string, input: string) =>
+  Bun.spawn(["/bin/sh", "-c", 'ulimit -d 524288 || exit 70; exec "$@"', name, process.execPath, "--no-env-file", fileURLToPath(worker)], {
+    stdin: new Blob([input]),
+    stdout: "pipe",
+    stderr: "ignore",
+    // No application credentials or configuration reach the decoder, only fixed
+    // thread pool sizes: the Bun work pool, canvas tokio runtime, and JSC GC
+    // markers otherwise grow with the host's cores, and RLIMIT_DATA also counts
+    // each thread's stack and allocator memory.
+    env: {
+      PATH: process.env.PATH,
+      LANG: "C.UTF-8",
+      UV_THREADPOOL_SIZE: "2",
+      TOKIO_WORKER_THREADS: "2",
+      BUN_JSC_numberOfGCMarkers: "2",
+    },
+  });

package/src/_internal/define-app.ts

@@ -1,3 +1,4 @@
+import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
 import { invokeCapabilityStream } from "./capability-streams";
@@ -26,6 +27,7 @@ import type {
   AppLifecycle,
   AppMeta,
   AppPresentationCatalog,
+  AppPwaPart,
   AppSearchLink,
   CloudLifecycleContext,
   WidgetEndpoint,
@@ -38,6 +40,7 @@ import {
   CapabilityOriginSchema,
 } from "../contracts/capabilities";
 import { type BoundNotificationMap, bindNotificationDefinitions, type NotificationDefinitionMap } from "../contracts/notification-types";
+import { isPwaPartId, PWA_AUTH_PATH, PWA_CANVAS_COLORS, PWA_MANIFEST_PATH, PWA_SHELL_APP_ID } from "../contracts/pwa";
 import type { AppRegistryEntry } from "../contracts/registry";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
 import type { Role } from "../contracts/shared";
@@ -95,6 +98,8 @@ export type PageOptions = {
   theme?: "light" | "dark";
   /** Framework-resolved BCP 47 document language — always the canonical request locale, never a page override. */
   lang?: string;
+  /** Renders the document as a page of the installable mobile app; set by `PwaLayout`. */
+  pwa?: { name: string };
 };
 
 type ResolvedPageOptions = PageOptions & { performanceRoute?: string };
@@ -162,6 +167,16 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   legalLinks?: ReadonlyArray<{ label: string; href: string; icon?: string }>;
   /** Static destinations for the global search UI; no capabilities are created. */
   searchLinks?: readonly AppSearchLink[];
+  /**
+   * Preview: pages of this app in the installable mobile app. Declaring it adds
+   * `/pwa/<id>` to the gateway routes and lists the app in the mobile app,
+   * with its name, icon and description. Serve the pages below `/pwa/<id>`
+   * with `PwaLayout` and `ssr.pwaAccess`. `routes` never lists `/pwa` paths.
+   */
+  pwa?: {
+    /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
+    requiresRoles?: Role[];
+  };
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP path on this app that returns a `WidgetResponse`. The dashboard
@@ -312,6 +327,32 @@ export type AppDefinition<S extends AppSettingsMap = {}, N extends NotificationD
 
 // ── Implementation ──────────────────────────────────────────────────────────
 
+const isPwaPath = (route: string): boolean => route === "/pwa" || route.startsWith("/pwa/");
+/** A route as the gateway reads it: trimmed and without empty segments, so `//pwa/x/` is `/pwa/x`. */
+const canonicalRoute = (route: string): string => {
+  const trimmed = route.trim();
+  return trimmed.startsWith("/") ? `/${trimmed.split("/").filter(Boolean).join("/")}` : trimmed;
+};
+
+/**
+ * `/pwa` belongs to the mobile app shell, `/pwa/_auth` to Core, and `/pwa/<id>`
+ * to the app that declares `pwa`. A part never claims a path by hand, so no app
+ * can take the shell's pages or another app's part.
+ */
+const validateAppPwaPart = (opts: Pick<AppOptions, "id" | "routes" | "pwa">): AppPwaPart | undefined => {
+  for (const route of opts.routes) {
+    const path = canonicalRoute(route);
+    if (!isPwaPath(path)) continue;
+    if ((path === "/pwa" && opts.id === PWA_SHELL_APP_ID) || (path === PWA_AUTH_PATH && opts.id === "core")) continue;
+    throw new Error(`App "${opts.id}" lists route "${route}"; /pwa is reserved for the mobile app, declare pwa: {} to get /pwa/${opts.id}`);
+  }
+  if (!opts.pwa) return undefined;
+  if (!isPwaPartId(opts.id)) {
+    throw new Error(`App "${opts.id}" cannot declare pwa; a part needs a plain id other than pwa, settings and offline`);
+  }
+  return { href: `/pwa/${opts.id}`, requiresRoles: opts.pwa.requiresRoles ? [...opts.pwa.requiresRoles] : undefined };
+};
+
 export const defineApp = <
   const S extends AppSettingsMap = {},
   const N extends NotificationDefinitionMap = {},
@@ -323,6 +364,7 @@ export const defineApp = <
   const isDevelopment = env.IS_DEVELOPMENT;
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
   const cliModules = validateAppCliModules(opts.id, opts.cli);
+  const pwaPart = validateAppPwaPart(opts);
 
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
@@ -341,19 +383,43 @@ export const defineApp = <
     rootDir,
     componentRoots: [resolve(env.APP_DIR ?? rootDir, "src"), fileURLToPath(new URL("../", import.meta.url))],
     basePath: opts.basePath,
-    template: ({ body, scripts, title, description, theme, lang, performanceRoute }) => {
+    template: ({ body, scripts, title, description, theme, lang, performanceRoute, pwa }) => {
       const themeFixed = theme !== undefined;
+      // App pages paint the canvas before any stylesheet and give it to the
+      // status bar. No status-bar style: `black-translucent` lays a blur band
+      // over the top edge on iOS 26.
+      const canvas = PWA_CANVAS_COLORS[theme ?? "light"];
+      const head = pwa
+        ? {
+            html: ` style="background-color:${canvas}"`,
+            viewport: "width=device-width, initial-scale=1, viewport-fit=cover",
+            app: `<meta name="theme-color" content="${canvas}">
+    <link rel="manifest" href="${PWA_MANIFEST_PATH}">
+    <link rel="apple-touch-icon" href="/branding/apple-touch-icon.png">
+    <meta name="apple-mobile-web-app-title" content="${escapeHtml(pwa.name)}">`,
+            // The web cross-fades between pages; an app page swaps at once. The browser ignores taps while a
+            // cross-document transition runs, so a tab tap right after the last one would be lost. After
+            // global.css, whose `navigation: auto` it overrides.
+            styles: `
+    <style data-cloud-app-navigation>@view-transition{navigation:none}</style>`,
+          }
+        : {
+            html: "",
+            viewport: "width=device-width, initial-scale=1.0",
+            app: `<meta name="theme-color" content="#09090b">
+    <meta name="mobile-web-app-capable" content="yes">`,
+            styles: "",
+          };
       // The inline layer statement fixes the cascade order before any
       // stylesheet declares a layer. Tailwind's `properties` layer resets
       // `--tw-*` in browsers without `@property` and must stay lowest.
       return `<!DOCTYPE html>
-<html lang="${normalizeLocale(lang)}" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}>
-  <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
+<html lang="${normalizeLocale(lang)}" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}${head.html}>
+  <head><meta charset="UTF-8"><meta name="viewport" content="${head.viewport}">
     <meta name="view-transition" content="same-origin">
     <title>${escapeHtml(title ?? "Cloud")}</title>
     <meta name="description" content="${escapeHtml(description ?? "Cloud workspace")}">
-    <meta name="theme-color" content="#09090b">
-    <meta name="mobile-web-app-capable" content="yes">
+    ${head.app}
     <link rel="icon" href="${appFaviconHref(opts.id, v)}">
     <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>
@@ -361,7 +427,7 @@ export const defineApp = <
     <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}">
+    <link rel="stylesheet" href="/public/global.css?v=${v}">${head.styles}
     <script>${themeBootstrapScript}</script>
   </head>
   <body class="k2b-ui" data-k2b-app-workspace-controller="global">
@@ -414,10 +480,11 @@ export const defineApp = <
         links: group.links.map((link) => ({ ...link })),
       }),
     ),
-    routes: [...opts.routes, ...cliPluginRoutePrefixes(cliModules)],
+    routes: [...opts.routes, ...cliPluginRoutePrefixes(cliModules), ...(pwaPart ? [pwaPart.href] : [])],
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
+    pwa: pwaPart,
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
@@ -512,6 +579,9 @@ export const defineApp = <
         help: compiledHelp?.summary,
         legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
         searchLinks: meta.searchLinks,
+        pwa: meta.pwa
+          ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
+          : undefined,
         widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
@@ -812,6 +882,10 @@ export const defineApp = <
       const stopLifecycle = startOpts.lifecycle?.stop;
       if (stopLifecycle) cleanup.push(() => stopLifecycle(cloudCtx));
 
+      // Fails before any setup when Core has not created the platform outbox yet.
+      const stopLiveOutbox = await startLiveOutbox(meta.id);
+      if (stopLiveOutbox) cleanup.push(stopLiveOutbox);
+
       if (!startOpts.skipSetup && startOpts.lifecycle?.setup) {
         log.info(`Setup: ${meta.id}`);
         await startOpts.lifecycle.setup(cloudCtx);

package/src/_internal/page-responses.ts

@@ -1,6 +1,7 @@
 import type { HtmlFn } from "@k2b/ssr";
 import type { Context } from "hono";
 import type { ClientErrorStatusCode, ServerErrorStatusCode } from "hono/utils/http-status";
+import { PWA_AUTH_PATH, PWA_SCOPE } from "../contracts/pwa";
 import { getLocale } from "../server/locale";
 import { preloadLayoutAnnouncements } from "../server/middleware/settings";
 import { createLoginRedirectUrl } from "../shared/redirect";
@@ -10,8 +11,8 @@ export type PageErrorOptions = {
   title?: string;
   description?: string;
   action?: { label: string; href: string; icon?: string };
-  /** Keep standalone/public pages outside the Cloud navigation shell. */
-  layout?: "cloud" | "minimal";
+  /** Keep standalone/public pages outside the Cloud navigation shell; `pwa` renders a page of the mobile app. */
+  layout?: "cloud" | "minimal" | "pwa";
 };
 
 export type PageErrorStatus = ClientErrorStatusCode | ServerErrorStatusCode;
@@ -38,5 +39,20 @@ export const createPageResponses = (html: HtmlFn<PageOptions>) => {
     },
   };
 
-  return { access, error };
+  /**
+   * Route policy for pages of the mobile app (preview), below `/pwa/`. Only an app session reaches them. Without
+   * one, Core renews the app session with the phone's device key and returns to the same page; `pwa_launch` marks
+   * that return, so a second miss stops at the shell's "unavailable" state instead of bouncing again.
+   */
+  const pwaAccess = {
+    onReject: (c: Context, reason: "unauthenticated" | "forbidden") => {
+      c.header("Cache-Control", "private, no-store");
+      if (reason === "forbidden" || c.get("actor")) return error(c, 403, { layout: "pwa" });
+      const url = new URL(c.req.url);
+      if (url.searchParams.has("pwa_launch")) return `${PWA_SCOPE}?pwa=unavailable`;
+      return `${PWA_AUTH_PATH}/session/launch?to=${encodeURIComponent(url.pathname + url.search)}`;
+    },
+  };
+
+  return { access, pwaAccess, error };
 };

package/src/_internal/registry-validation.ts

@@ -104,6 +104,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     )
       return invalid("searchLinks", "an array of same-origin navigation links");
   }
+  if (value.pwa !== undefined) {
+    if (!isRecord(value.pwa) || value.pwa.href !== `/pwa/${value.id as string}`) return invalid("pwa", "a mobile app part at /pwa/<id>");
+    if (value.pwa.requiresRoles !== undefined && !isStringArray(value.pwa.requiresRoles)) {
+      return invalid("pwa.requiresRoles", "an array of strings");
+    }
+  }
   if (value.widgets !== undefined) {
     if (
       !Array.isArray(value.widgets) ||

package/src/_internal/runtime-context.ts

@@ -67,6 +67,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
       ),
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
       searchLinks: e.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
+      pwa: e.pwa ? { href: e.pwa.href, requiresRoles: e.pwa.requiresRoles ? ([...e.pwa.requiresRoles] as Role[]) : undefined } : undefined,
       openapi: e.openapi,
     };
   }),

package/src/_internal/static-assets.ts

@@ -33,6 +33,15 @@ function acceptsEncoding(header: string | null, encoding: "br" | "gzip"): boolea
   });
 }
 
+/** `If-None-Match` names the current file: a list of tags, possibly weak, or `*`. */
+function matchesEtag(header: string | null, etag: string): boolean {
+  if (!header) return false;
+  return header.split(",").some((part) => {
+    const tag = part.trim();
+    return tag === "*" || tag === etag || tag === `W/${etag}`;
+  });
+}
+
 async function encodedFile(path: string, encoding: "br" | "gzip"): Promise<Bun.BunFile | null> {
   const suffix = encoding === "br" ? ".br" : ".gz";
   const file = Bun.file(`${path}${suffix}`);
@@ -72,13 +81,19 @@ 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)}"`;
     const headers = new Headers({
-      "Cache-Control": isDevelopment ? "no-store" : "public, max-age=31536000, immutable",
-      "Content-Length": String(selected.size),
-      "Content-Type": sourceFile.type || "application/octet-stream",
+      "Cache-Control": isDevelopment ? "no-cache" : "public, max-age=31536000, immutable",
+      ETag: etag,
       Vary: "Accept-Encoding",
     });
 
+    if (matchesEtag(c.req.header("If-None-Match") ?? null, etag)) return new Response(null, { status: 304, headers });
+
+    headers.set("Content-Length", String(selected.size));
+    headers.set("Content-Type", sourceFile.type || "application/octet-stream");
     if (selectedEncoding) headers.set("Content-Encoding", selectedEncoding);
 
     return new Response(c.req.method === "HEAD" ? null : selected, { headers });

package/src/access/ResourceApiKeys.tsx

@@ -1,6 +1,18 @@
 import { dates } from "@k2b/stdlib";
 import { mutation as mutations } from "@k2b/stdlib/solid";
-import { Button, CopyButton, DateTimePicker, NoticeCard, Placeholder, prompts, Select, Tag, TextInput, useLocale } from "@k2b/ui";
+import {
+  Button,
+  CopyButton,
+  DateTimePicker,
+  DetailPanel,
+  NoticeCard,
+  Placeholder,
+  prompts,
+  Select,
+  Tag,
+  TextInput,
+  useLocale,
+} from "@k2b/ui";
 import { createEffect, createSignal, For, Show } from "solid-js";
 import type { PermissionLevel, ServiceAccountCredential } from "../contracts/shared";
 import { accessMessages } from "./messages";
@@ -56,9 +68,7 @@ function TokenDialog(props: { token: string }) {
   const t = () => accessMessages.resolve([locale()]).t;
   return (
     <div class="flex flex-col gap-4">
-      <NoticeCard tone="warning" icon={false}>
-        {t().copyOnce}
-      </NoticeCard>
+      <NoticeCard tone="warning">{t().copyOnce}</NoticeCard>
       <div class="rounded-lg border border-zinc-200 bg-zinc-50 p-3 dark:border-zinc-800 dark:bg-zinc-900">
         <code class="block break-all font-mono text-xs text-primary">{props.token}</code>
       </div>
@@ -203,39 +213,29 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
     if (confirmed) await revokeMutation.mutate({ id: key.id, name: key.name });
   };
 
+  // The heading is a detail panel section heading: in a detail panel the keys line up with the sections around them,
+  // and below a settings group title they read as one level down.
   return (
-    <section class="flex flex-col gap-4">
-      <div class="flex items-start justify-between gap-3">
-        <div>
-          <h3 class="flex items-center gap-1.5 text-sm font-semibold text-primary">
-            <i class="ti ti-key text-sm" />
-            {props.title ?? t().apiKeys}
-          </h3>
-          <p class="mt-1 text-xs text-dimmed">{props.description ?? t().apiKeysDescription}</p>
-        </div>
-        <Button type="button" variant="secondary" size="sm" class="shrink-0" onClick={openCreate} disabled={createMutation.loading()}>
-          <i class="ti ti-plus" />
+    <DetailPanel.Section
+      title={props.title ?? t().apiKeys}
+      icon="ti ti-key"
+      description={props.description ?? t().apiKeysDescription}
+      actions={
+        <Button type="button" variant="secondary" size="sm" onClick={openCreate} disabled={createMutation.loading()}>
+          <i class="ti ti-plus" aria-hidden="true" />
           {t().add}
         </Button>
-      </div>
-
-      <Show
-        when={keys().length > 0}
-        fallback={
-          <Placeholder
-            icon="ti ti-key"
-            class="rounded-lg border border-dashed border-zinc-200 dark:border-zinc-800"
-            description={t().noApiKeys}
-          />
-        }
-      >
+      }
+    >
+      <Show when={keys().length > 0} fallback={<Placeholder icon="ti ti-key" align="left" description={t().noApiKeys} />}>
         <div class="flex flex-col gap-2">
           <For each={keys()}>
             {(key) => (
               <div class="group/api-key flex items-center gap-3 rounded-lg bg-zinc-50/70 p-3 dark:bg-zinc-900/35">
                 <div class="min-w-0 flex-1">
-                  <div class="flex min-w-0 items-center gap-2">
-                    <span class="truncate text-sm font-medium text-primary">{key.name}</span>
+                  {/* The name and its tags wrap instead of squeezing the name to a few letters in a narrow section. */}
+                  <div class="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+                    <span class="max-w-full truncate text-sm font-medium text-primary">{key.name}</span>
                     <Tag color={key.permission === "none" ? "#dc2626" : "#2563eb"}>
                       {permissionLabel(key.permission, options(), t().noAccess)}
                     </Tag>
@@ -266,6 +266,6 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
           </For>
         </div>
       </Show>
-    </section>
+    </DetailPanel.Section>
   );
 }

package/src/ai/capability-execution.ts

@@ -8,6 +8,7 @@ import type { AccessSubject } from "../server/services/access";
 import { isAccountCategoryAllowed } from "../services/account-category-policy";
 import { isAccountExpired } from "../services/account-model";
 import { accounts } from "../services/accounts";
+import { withoutAdminRole } from "../services/session/user";
 import { LOCALE_HEADER } from "../shared/locale";
 import type { AiCapabilityCatalogEntry } from "./capabilities";
 import { aiToolAudit } from "./tool-audit";
@@ -30,6 +31,10 @@ export const resolveAiCapabilityActor = async (input: {
   const user = await (input.getUser ?? accounts.users.get)({ id: conversation.createdByUserId });
   if (!user || isAccountExpired(user.accountExpires)) throw new Error("Cloud capability actor is no longer active.");
   if (!(await isAccountCategoryAllowed(user))) throw new Error("Cloud capability actor category is disabled.");
+  // A turn started in the mobile app keeps its limits: no administrator role, and invocations say so.
+  if (input.persistedActor.sessionKind === "app") {
+    return { actor: { kind: "user", user: withoutAdminRole(user), sessionKind: "app" }, accessSubject: { type: "user", userId: user.id } };
+  }
   return { actor: { kind: "user", user }, accessSubject: { type: "user", userId: user.id } };
 };
 

package/src/ai/client/controller.ts

@@ -178,6 +178,8 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
   const abortRequests = new Map<string, Promise<boolean>>();
   let stream: AiStreamHandle | null = null;
   let streamSession: AiStreamSession | null = null;
+  /** The chat error left by a stream that ended for good, until a stream opens again. */
+  let streamError: string | null = null;
   let streamGeneration = 0;
   let conversationOpenGeneration = 0;
   let historyTargetSeq: number | null = null;
@@ -217,9 +219,12 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     if (activeConversationId()) setGlobalError(message);
     else setGlobalError(message);
   };
+  /** Starts the person's next action in the active chat clean, including a stream that ended with an error. */
   const clearErrors = () => {
     setGlobalError(null);
     setRunError(null);
+    const conversationId = activeConversationId();
+    if (conversationId) openStream(conversationId);
   };
   const error = () => globalError() ?? runError();
 
@@ -314,12 +319,19 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
       conversationId,
       url: url(`/conversations/${conversationId}/stream`),
       onStatus: (status) => {
-        if (isCurrentStreamSession(streamSession, session)) setStreamStatus(status);
+        if (!isCurrentStreamSession(streamSession, session)) return;
+        setStreamStatus(status);
+        if (status !== "open" || streamError === null) return;
+        if (globalError() === streamError) setGlobalError(null);
+        streamError = null;
       },
       onEvent: (event) => applyEvent(session, event),
+      // The transport has stopped. Drop its handle so the next visit, refresh,
+      // or action in this chat can subscribe again.
       onError: (error) => {
         if (!isCurrentStreamSession(streamSession, session)) return;
-        setStreamStatus("idle");
+        closeStream();
+        streamError = error.message;
         setConversationError(conversationId, error.message);
       },
     });
@@ -422,6 +434,7 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
 
   const openConversation = async (conversationId: string) => {
     if (activeConversationId() === conversationId && state.conversation?.id === conversationId) {
+      openStream(conversationId);
       void markConversationViewed(conversationId);
       return "current" as const;
     }
@@ -485,6 +498,7 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     if (preservedOlder.length === 0) setHasMore(conversationId, detail.hasMoreMessages ?? false);
     if (detail.timeline) setTimeline(conversationId, detail.timeline);
     setRunError(conversationRunError(detail.conversation));
+    openStream(conversationId);
   };
 
   const requestMessagesPage = async (conversationId: string, before: number, limit: number): Promise<AiMessagesPage> => {
@@ -573,8 +587,8 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     if (conversationId) void openConversation(conversationId);
     else {
       conversationOpenGeneration += 1;
-      clearErrors();
       setActiveConversationIdSignal(null);
+      clearErrors();
       historyTargetSeq = null;
       setLoadingConversationId(null);
       closeStream();