@k2b/cloud 0.38.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -38,10 +38,12 @@
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
     "./browser/commands": "./src/browser/commands.ts",
+    "./browser/panel": "./src/browser/panel.ts",
     "./browser/search": "./src/browser/search.ts",
     "./browser/widgets": "./src/browser/widgets.ts",
     "./browser/testing": "./src/browser/testing.ts",
     "./browser/resource-picker": "./src/browser/resource-picker.tsx",
+    "./browser/composer-insert": "./src/browser/composer-insert.ts",
     "./browser/files": "./src/browser/files.tsx",
     "./capabilities": "./src/capabilities/client.ts",
     "./capabilities/server": "./src/capabilities/server.ts",
@@ -103,12 +105,13 @@
     "@firecrawl/anydoc": "0.2.4",
     "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
+    "sharp": "0.35.4",
     "@simplewebauthn/server": "14.0.3",
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
     "@k2b/ssr": "0.17.0",
-    "@k2b/ui": "0.28.0",
+    "@k2b/ui": "0.29.0",
     "@k2b/stdlib": "0.29.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
@@ -141,7 +144,7 @@
     "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.15",
     "hono": "4.13.9",
-    "playwright": "1.63.0",
+    "playwright": "1.64.1",
     "solid-js": "1.9.15",
     "typescript": "7.0.2",
     "zod": "4.6.5"

package/scripts/build-canvas-workers.ts

@@ -1,58 +1,138 @@
-import { cp, mkdir } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { cp, mkdir, realpath } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { readImageRecords } from "../src/services/pdf/image-protocol";
 
-/** 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",
+    define: "__CLOUD_PDF_RENDER_WORKER__",
+    entry: "src/ai/pdf-render-worker.ts",
+    output: "pdf-worker.js",
+    packages: ["@napi-rs/canvas", "pdfjs-dist"],
+  },
+  {
+    define: "__CLOUD_ICON_RENDER_WORKER__",
     entry: "src/services/branding/icon-render-worker.ts",
     output: "icon-worker.js",
-    packages: [],
+    packages: ["@napi-rs/canvas"],
   },
+  { define: "__CLOUD_PDF_IMAGE_WORKER__", entry: "src/services/pdf/image-worker.ts", output: "image-worker.js", packages: ["sharp"] },
 ] as const;
 
+/** Server bundle defines: each caller starts its worker from `canvas/` next to `server.js`. */
+export const CANVAS_WORKER_DEFINES = Object.fromEntries(
+  CANVAS_WORKERS.map((worker) => [worker.define, JSON.stringify(`./canvas/${worker.output}`)]),
+);
+
+const Manifest = z.object({
+  version: z.string(),
+  dependencies: z.record(z.string(), z.string()).default({}),
+  optionalDependencies: z.record(z.string(), z.string()).default({}),
+  os: z.array(z.string()).optional(),
+  cpu: z.array(z.string()).optional(),
+  libc: z.array(z.string()).optional(),
+});
+const matches = (values: string[] | undefined, target: string) =>
+  !values || (!values.includes(`!${target}`) && (values.every((value) => value.startsWith("!")) || values.includes(target)));
+
 /**
- * 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`.
+ * Bundle each reached native worker with only its runtime packages external. Copy their real dependency closures flat,
+ * dereferenced and filtered by OS, CPU and libc; reject version collisions and missing native binaries. Smoke-test sharp
+ * in the packaged subprocess so the build proves that its native closure loads on this architecture.
  */
-export async function buildCanvasWorkers(dist: string, bundledInputs: readonly string[]) {
-  const workers = CANVAS_WORKERS.filter((worker) => bundledInputs.some((path) => path.endsWith(worker.reachedBy)));
+export async function buildCanvasWorkers(dist: string, serverCode: string) {
+  // A worker ships only when the server code still contains its path, which only the code that starts it carries.
+  // Metafile inputs also list tree-shaken modules, and a retained module binding contributes bytes without its caller.
+  const workers = CANVAS_WORKERS.filter((worker) => serverCode.includes(`./canvas/${worker.output}`));
   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,
+      external: [...worker.packages],
     });
-    if (!build.success) throw new Error(`Canvas worker ${worker.output} build failed: ${build.logs.join("\n")}`);
+    if (!build.success) throw new Error(`Native 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());
+  const libc = z.object({ header: z.object({ glibcVersionRuntime: z.string().optional() }) }).parse(process.report.getReport()).header
+    .glibcVersionRuntime
+    ? "glibc"
+    : "musl";
+  const copied = new Map<string, string>();
+  const copyPackage = async (name: string, dependent: string, optional = false): Promise<boolean> => {
+    let source: string;
+    try {
+      source = await realpath(dirname(Bun.resolveSync(`${name}/package.json`, dependent)));
+    } catch (error) {
+      if (optional) return false;
+      throw error;
+    }
+    const manifest = Manifest.parse(await Bun.file(resolve(source, "package.json")).json());
+    if (!matches(manifest.os, process.platform) || !matches(manifest.cpu, process.arch) || !matches(manifest.libc, libc)) {
+      if (optional) return false;
+      throw new Error(`Native worker dependency ${name} does not support the build platform.`);
+    }
+    const existing = copied.get(name);
+    if (existing) {
+      if (existing !== manifest.version)
+        throw new Error(`Native worker dependency collision: ${name} ${existing} and ${manifest.version}.`);
+      return true;
+    }
+    copied.set(name, manifest.version);
+    await cp(source, resolve(out, "node_modules", name), {
+      recursive: true,
+      dereference: true,
+      filter: (path) => basename(path) !== "node_modules",
+    });
+    for (const dependency of Object.keys(manifest.dependencies)) {
+      if (dependency in manifest.optionalDependencies) continue;
+      await copyPackage(dependency, source);
+    }
     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 (await copyPackage(dependency, source, true)) {
+        if (
+          (name === "sharp" && dependency.startsWith("@img/sharp-") && !dependency.startsWith("@img/sharp-libvips-")) ||
+          (name === "@napi-rs/canvas" && dependency.startsWith("@napi-rs/canvas-"))
+        )
+          nativePackages++;
+      }
+    }
+    if ((name === "sharp" || name === "@napi-rs/canvas") && !nativePackages) {
+      throw new Error(`Native workers need an installed ${name} binary for the build platform.`);
+    }
+    return true;
+  };
+  for (const name of new Set(workers.flatMap((worker) => [...worker.packages]))) await copyPackage(name, framework);
+  if (workers.some((worker) => worker.output === "image-worker.js")) await smokeImageWorker(resolve(out, "image-worker.js"));
+}
+
+async function smokeImageWorker(entry: string) {
+  // A fixed 2x2 RGBA PNG; the build process never loads sharp.
+  const png = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEUlEQVR4nGP4z8DQAMIMMAYAOOgF/REzMMkAAAAASUVORK5CYII=", "base64");
+  const child = Bun.spawn([process.execPath, "--no-env-file", entry], {
+    stdin: new Blob([
+      `${JSON.stringify({ bytes: png.byteLength, boxes: [{ width: 2, height: 2 }], maxBytes: 4096, timeoutMs: 10_000 })}\n`,
+      png,
+    ]),
+    stdout: "pipe",
+    stderr: "ignore",
+    env: { PATH: process.env.PATH },
+  });
+  const timer = setTimeout(() => child.kill("SIGKILL"), 15_000);
+  try {
+    const result = await readImageRecords(child.stdout, { boxes: [{ width: 2, height: 2 }], maxBytes: 4096 });
+    if ((await child.exited) !== 0 || !result.ok || result.variants.length !== 1 || !result.variants[0]) {
+      throw new Error("Packaged image worker could not convert its PNG: sharp's native dependency closure is incomplete or unusable.");
     }
-    if (!nativePackages) throw new Error("Canvas workers need an installed native canvas binary for the build platform.");
+  } finally {
+    clearTimeout(timer);
+    child.kill("SIGKILL");
+    await child.exited;
   }
 }

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 { buildCanvasWorkers } from "./build-canvas-workers";
+import { buildCanvasWorkers, CANVAS_WORKER_DEFINES } from "./build-canvas-workers";
 
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
@@ -127,13 +127,11 @@ try {
     naming: "server.js",
     target: "bun",
     minify: true,
-    metafile: true,
     define: {
       __CLOUD_VERSION__: JSON.stringify(version),
       __CLOUD_RELEASE__: JSON.stringify(release),
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
-      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./canvas/pdf-worker.js"),
-      __CLOUD_ICON_RENDER_WORKER__: JSON.stringify("./canvas/icon-worker.js"),
+      ...CANVAS_WORKER_DEFINES,
       __CLOUD_APP_ASSETS__: JSON.stringify("./assets/"),
       __CLOUD_CLI_PLUGINS__: JSON.stringify("./cli/"),
     },
@@ -146,7 +144,7 @@ if (!server.success) {
   for (const m of server.logs) console.error(m);
   throw new Error("Server bundle failed");
 }
-await buildCanvasWorkers(dist, Object.keys(server.metafile?.inputs ?? {}));
+await buildCanvasWorkers(dist, await Bun.file(resolve(dist, "server.js")).text());
 
 // 2. Per-app Tailwind stylesheet.
 const appCss = resolve(appDir, "src/styles/app.css");

package/src/_internal/app-path.ts

@@ -0,0 +1,25 @@
+/** An absolute path on the current origin: one leading slash, no backslash or whitespace. */
+export const SAME_ORIGIN_PATH = /^\/(?![\/\\])[^\\\s]*$/;
+
+/** A route as the gateway reads it: trimmed and without empty segments, so `//pwa/x/` is `/pwa/x`. */
+export const canonicalRoute = (route: string): string => {
+  const trimmed = route.trim();
+  return trimmed.startsWith("/") ? `/${trimmed.split("/").filter(Boolean).join("/")}` : trimmed;
+};
+
+/**
+ * Whether an application path stays below one of the app's own `routes`. It is
+ * checked on the path the browser actually requests, after dot segments, and
+ * never starts with `//`, which a URL resolver reads as another host.
+ */
+export const isOwnAppPath = (href: string, routes: readonly string[]): boolean => {
+  if (!SAME_ORIGIN_PATH.test(href)) return false;
+  const path = new URL(href, "https://cloud.invalid").pathname;
+  return (
+    !path.startsWith("//") &&
+    routes.some((route) => {
+      const prefix = canonicalRoute(route);
+      return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
+    })
+  );
+};

package/src/_internal/app-presentation.ts

@@ -92,7 +92,11 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
     if (!canonical) throw new Error(`App presentation locale ${JSON.stringify(locale)} is not a valid BCP 47 locale`);
     if (canonical === baseLocale) throw new Error(`App presentation translations must not repeat base locale ${baseLocale}`);
     if (translations[canonical]) throw new Error(`App presentation locale ${canonical} is duplicated after canonicalization`);
+    if (translation.panelLabel !== undefined && !app.panel) {
+      throw new Error(`${canonical}.panelLabel contains unknown key "panel"`);
+    }
     translations[canonical] = {
+      ...(translation.panelLabel !== undefined ? { panelLabel: text(translation.panelLabel, `${canonical}.panelLabel`) } : {}),
       ...(translation.name !== undefined ? { name: text(translation.name, `${canonical}.name`) } : {}),
       ...(translation.description !== undefined
         ? { description: text(translation.description, `${canonical}.description`, MAX_DESCRIPTION) }

package/src/_internal/canvas-worker.ts

@@ -1,24 +1,26 @@
 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
+ * Starts a native worker (PDF pages, app icons, print images) 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) =>
+export const spawnCanvasWorker = (worker: URL, name: string, input: string | Blob) =>
   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
+    // runtime settings: 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.
+    // Bun's allocator otherwise commits whole arenas up front, which RLIMIT_DATA counts as used.
     env: {
       PATH: process.env.PATH,
       LANG: "C.UTF-8",
       UV_THREADPOOL_SIZE: "2",
       TOKIO_WORKER_THREADS: "2",
       BUN_JSC_numberOfGCMarkers: "2",
+      MIMALLOC_ARENA_EAGER_COMMIT: "0",
     },
   });

package/src/_internal/define-app.ts

@@ -89,7 +89,7 @@ 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 { canonicalRoute, isOwnAppPath } from "./registry-validation";
 import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 import { servePublicAsset } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
@@ -144,6 +144,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 +372,31 @@ 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" | "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`);
+  }
+  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 +412,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
@@ -528,6 +550,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 +650,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) } : {}),

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" : ""}`;
+}

package/src/_internal/registry-validation.ts

@@ -1,37 +1,14 @@
 import { CLOUD_CLI_MODULE_NAME } from "../cli/plugin";
 import { PlatformPermissionSchema } from "../contracts/outgoing-mail";
 import type { AppRegistryEntry } from "../contracts/registry";
+import { isOwnAppPath, SAME_ORIGIN_PATH } from "./app-path";
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 const isString = (value: unknown): value is string => typeof value === "string";
 const isStringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every(isString);
 const isStringRecord = (value: unknown): value is Record<string, string> => isRecord(value) && Object.values(value).every(isString);
 
-/** An absolute path on the current origin: one leading slash, no backslash or whitespace. */
-const SAME_ORIGIN_PATH = /^\/(?![\/\\])[^\\\s]*$/;
-
-/** A route as the gateway reads it: trimmed and without empty segments, so `//pwa/x/` is `/pwa/x`. */
-export const canonicalRoute = (route: string): string => {
-  const trimmed = route.trim();
-  return trimmed.startsWith("/") ? `/${trimmed.split("/").filter(Boolean).join("/")}` : trimmed;
-};
-
-/**
- * Whether a `nav.badge` path stays below one of the app's own `routes`. It is
- * checked on the path the browser actually requests, after dot segments, and
- * never starts with `//`, which a URL resolver reads as another host.
- */
-export const isOwnNavBadge = (badge: string, routes: readonly string[]): boolean => {
-  if (!SAME_ORIGIN_PATH.test(badge)) return false;
-  const path = new URL(badge, "https://cloud.invalid").pathname;
-  return (
-    !path.startsWith("//") &&
-    routes.some((route) => {
-      const prefix = canonicalRoute(route);
-      return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
-    })
-  );
-};
+export { canonicalRoute, isOwnAppPath } from "./app-path";
 
 const invalid = (path: string, expected: string): string => `${path} must be ${expected}`;
 
@@ -69,6 +46,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       if (!isRecord(translation)) return invalid(`presentation.translations.${locale}`, "an object");
       if (translation.name !== undefined && !isString(translation.name))
         return invalid(`presentation.translations.${locale}.name`, "a string");
+      if (
+        translation.panelLabel !== undefined &&
+        (!isString(translation.panelLabel) || !translation.panelLabel.trim() || value.panel === undefined)
+      ) {
+        return invalid(`presentation.translations.${locale}.panelLabel`, "a non-empty string for a declared panel");
+      }
       if (translation.description !== undefined && !isString(translation.description)) {
         return invalid(`presentation.translations.${locale}.description`, "a string");
       }
@@ -87,10 +70,22 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     if (value.nav.requiresRoles !== undefined && !isStringArray(value.nav.requiresRoles)) {
       return invalid("nav.requiresRoles", "an array of strings");
     }
-    if (value.nav.badge !== undefined && (!isString(value.nav.badge) || !isOwnNavBadge(value.nav.badge, value.routes))) {
+    if (value.nav.badge !== undefined && (!isString(value.nav.badge) || !isOwnAppPath(value.nav.badge, value.routes))) {
       return invalid("nav.badge", "a same-origin path below one of the entry's routes");
     }
   }
+  if (value.panel !== undefined) {
+    if (!isRecord(value.panel)) return invalid("panel", "an object");
+    if (!isString(value.panel.href) || !isOwnAppPath(value.panel.href, value.routes)) {
+      return invalid("panel.href", "a same-origin path below one of the entry's routes");
+    }
+    for (const field of ["label", "icon"] as const) {
+      if (!isString(value.panel[field]) || !value.panel[field].trim()) return invalid(`panel.${field}`, "a non-empty string");
+    }
+    if (value.panel.requiresRoles !== undefined && !isStringArray(value.panel.requiresRoles)) {
+      return invalid("panel.requiresRoles", "an array of strings");
+    }
+  }
   if (value.adminNav !== undefined) {
     if (
       !Array.isArray(value.adminNav) ||

package/src/_internal/runtime-context.ts

@@ -58,6 +58,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
             badge: e.nav.badge,
           }
         : undefined,
+      panel: e.panel ? { ...e.panel, requiresRoles: e.panel.requiresRoles ? [...e.panel.requiresRoles] : undefined } : undefined,
       help: e.help ? { ...e.help } : undefined,
       searchTags,
       searchHelp: searchQueries?.map((query) => query.description).join(" "),

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

@@ -1,46 +1,65 @@
 import { LocaleProvider } from "@k2b/ui";
+import { createSignal, onCleanup, Show } from "solid-js";
 import { render } from "solid-js/web";
+import type { AccessEntry } from "../contracts/shared";
 import PermissionEditor from "./PermissionEditor";
 
 const host = document.getElementById("root");
 if (!host) throw new Error("Missing harness root");
-render(
-  () => (
+render(() => {
+  let saved: AccessEntry[] = ["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",
+  }));
+  const [data, setData] = createSignal(saved);
+  const refetch = () => {
+    // Like a consumer's query: fresh objects contain the saved level and another person's change.
+    saved = saved.map((entry, index) => ({
+      ...entry,
+      principal: { ...entry.principal },
+      ...(index === 2 ? { permission: "write" as const } : {}),
+    }));
+    setData(saved);
+  };
+  document.addEventListener("refetch-access", refetch);
+  onCleanup(() => document.removeEventListener("refetch-access", refetch));
+  return (
     <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 () => {}}
-      />
+      <Show when={data()}>
+        {(entries) => (
+          <PermissionEditor
+            initialEntries={entries()}
+            // 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={(id, permission) =>
+              new Promise<void>((resolve) => {
+                // Existing tests use this mark and event to control the save.
+                document.documentElement.dataset.saving = "true";
+                document.addEventListener(
+                  "settle-access",
+                  () => {
+                    saved = saved.map((entry) => (entry.id === id ? { ...entry, permission } : entry));
+                    delete document.documentElement.dataset.saving;
+                    resolve();
+                  },
+                  { once: true },
+                );
+              })
+            }
+            revokeAccess={async () => {}}
+          />
+        )}
+      </Show>
     </LocaleProvider>
-  ),
-  host,
-);
+  );
+}, host);