@k2b/cloud 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -93,23 +93,23 @@
     "@firecrawl/anydoc": "0.2.4",
     "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
-    "@hono/standard-validator": "0.2.2",
-    "@simplewebauthn/server": "14.0.2",
-    "@tabler/icons": "3.47.0",
+    "@simplewebauthn/server": "14.0.3",
+    "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.9.0",
-    "@k2b/stdlib": "0.26.0",
-    "@k2b/sync": "6.5.0",
+    "@k2b/ui": "0.9.1",
+    "@k2b/stdlib": "0.27.0",
+    "@k2b/sync": "7.0.0",
+    "@nats-io/jetstream": "3.4.0",
     "@nats-io/transport-node": "3.4.0",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/sdk": "1.30.1",
     "bun-plugin-tailwind": "0.1.2",
-    "hono-openapi": "1.3.1",
+    "hono-openapi": "1.3.3",
     "jose": "6.2.12",
-    "katex": "0.18.7",
+    "katex": "0.18.9",
     "liquidjs": "10.29.0",
-    "marked": "17.0.6",
+    "marked": "18.0.14",
     "mermaid": "12.0.0",
     "nodemailer": "10.0.10",
     "postcss": "8.5.28",
@@ -129,8 +129,8 @@
     "@babel/preset-typescript": "8.0.1",
     "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.15",
-    "hono": "4.13.8",
-    "playwright": "1.62.0",
+    "hono": "4.13.9",
+    "playwright": "1.63.0",
     "solid-js": "1.9.15",
     "typescript": "5.9.3",
     "zod": "4.6.5"

package/scripts/build.ts

@@ -32,6 +32,7 @@ import { promisify } from "node:util";
 import { brotliCompress, gzip, constants as zlibConstants } from "node:zlib";
 import { Glob } from "bun";
 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";
@@ -181,7 +182,8 @@ if (existsSync(appAssets)) {
 // `cld` plugins: one self-contained module bundle plus references per module.
 // Imported after the app config so the framework sees the APP_DIR set above.
 const { buildCliPlugin, writeCliPlugin } = await import("../src/_internal/cli-plugins");
-for (const [name, declaration] of Object.entries(app?.meta.cli ?? {})) {
+const cliModules: AppCliModules = app?.meta.cli ?? {};
+for (const [name, declaration] of Object.entries(cliModules)) {
   const plugin = await buildCliPlugin({ appDir, appId, name, declaration, version });
   await writeCliPlugin(resolve(dist, "cli", name), plugin);
 }

package/scripts/sync-recovery-smoke.ts

@@ -68,10 +68,7 @@ Run "prepare", restart the application fleet while NATS stays up, then run "reco
   check(phase === "prepare" || phase === "recover", "Pass prepare or recover");
   const namespace = options.namespace?.trim() ?? "";
   check(/^cloud-recovery-smoke-[A-Za-z0-9_-]{6,60}$/.test(namespace), "Pass a unique --namespace cloud-recovery-smoke-<suffix>");
-  const servers = (env.NATS_SERVERS ?? "nats://127.0.0.1:4222")
-    .split(",")
-    .map((value) => value.trim())
-    .filter(Boolean);
+  const servers = env.NATS_SERVERS.length ? env.NATS_SERVERS : ["nats://127.0.0.1:4222"];
   const connection = await connect({ servers, name: `${APPLICATION}-${phase}`, ignoreClusterUpdates: true });
   const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: env.SYNC_REPLICAS } });
   const job = sync.job<{ preparedAt: string }>({

package/src/_internal/define-app.ts

@@ -48,6 +48,7 @@ import { requireInvocation } from "../server/middleware/invocation";
 import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-template";
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
 import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
+import { validationErrorResponse } from "../server/middleware/validator";
 import {
   capabilityInvocationOperation,
   searchInvocationOperation,
@@ -774,6 +775,7 @@ export const defineApp = <
       if (advertiseOpenapi) {
         const apiPrefix = opts.openapi!.replace(/\/openapi\.json$/, "") || "/";
         const spec = await generateSpecs(startOpts.openapi!, {
+          defaultValidationErrorResponse: validationErrorResponse,
           documentation: {
             info: {
               title: meta.name,

package/src/_internal/process-sync.ts

@@ -12,6 +12,7 @@ import { createSync, type Sync } from "@k2b/sync";
 import { env } from "../config/env";
 import { flushSyncTraceEvents, observeSyncEvent } from "../services/logging/trace";
 import { connectNats } from "./nats-connection";
+import { withSyncBudgets } from "./sync-budget";
 
 let current: Sync | undefined;
 let starting = false;
@@ -64,7 +65,11 @@ export type ProcessSync = {
   stop: () => Promise<void>;
 };
 
-/** Connect NATS, create and bind the process Sync instance, and wait until it is ready. */
+/**
+ * Connect NATS, create and bind the process Sync instance, and wait until it is
+ * ready. Existing streams of its jobs, queues, and topics take the byte
+ * limits they declare before first use (see `sync-budget.ts`).
+ */
 export const startProcessSync = async ({ application }: { application: string }): Promise<ProcessSync> => {
   if (!env.SYNC_NAMESPACE.trim()) {
     throw new Error(
@@ -78,13 +83,16 @@ export const startProcessSync = async ({ application }: { application: string })
     const connection = await connectNats({ name: `${application}@${hostname()}` });
     let sync: Sync | undefined;
     try {
-      sync = createSync({
-        connection,
-        namespace: env.SYNC_NAMESPACE,
-        application,
-        defaults: { replicas: env.SYNC_REPLICAS },
-        observe: (event) => observeSyncEvent(event, application),
-      });
+      sync = withSyncBudgets(
+        createSync({
+          connection,
+          namespace: env.SYNC_NAMESPACE,
+          application,
+          defaults: { replicas: env.SYNC_REPLICAS },
+          observe: (event) => observeSyncEvent(event, application),
+        }),
+        { connection, namespace: env.SYNC_NAMESPACE },
+      );
       bindProcessSync(sync);
       await sync.ready();
     } catch (error) {

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

@@ -28,6 +28,9 @@ type SsrHandler<E extends Env, T extends object> = (context: Context<E & PageEnv
  * (such as the request locale for `<html lang>`) are present on every SSR
  * page without per-route plumbing. Redirects and other passthrough Responses
  * skip it.
+ *
+ * Rendered documents default to `Cache-Control: private, no-store` unless the
+ * handler or a middleware already chose a policy.
  */
 export const createStatusPreservingSsrHandler = <T extends object>(
   html: HtmlFn<T>,
@@ -55,7 +58,12 @@ export const createStatusPreservingSsrHandler = <T extends object>(
       response.headers.forEach((value, key) => {
         headers[key] = value;
       });
-      return context.newResponse(response.body, status as StatusCode, headers);
+      const document = context.newResponse(response.body, status as StatusCode, headers);
+      // A rendered document carries the signed-in user's state. Without an
+      // explicit policy, a browser may show it again on Back from its HTTP
+      // cache, even after sign-out. Handlers that set their own policy keep it.
+      if (!document.headers.has("Cache-Control")) document.headers.set("Cache-Control", "private, no-store");
+      return document;
     });
   };
 };

package/src/_internal/sync-budget.ts

@@ -0,0 +1,306 @@
+/**
+ * Brings existing JetStream streams to the byte limits that the Sync jobs,
+ * queues, and topics of one Cloud process declare.
+ *
+ * JetStream reserves a stream's whole `max_bytes` on every replica as soon as
+ * the stream exists. @k2b/sync 7 declares small limits: a job or queue without
+ * `retention` holds 256 messages at its payload limit, and `deadLetterRetention`
+ * sizes dead letters apart from the work or event stream. Sync never
+ * reconfigures an existing stream, though. A stream created with other limits,
+ * such as the 1 GiB that Sync 6 gave every job and queue without `retention`,
+ * fails the declaration with `ResourceDriftError` on `max_bytes`.
+ *
+ * Before a job, queue, or topic is first used, this module therefore changes
+ * the byte limit of such a stream in place: both streams of a job or queue,
+ * and the dead-letter stream of a topic. A stream that holds more than its new
+ * limit would lose its oldest messages; it keeps its limit instead:
+ *
+ * - a job or queue is declared with the stream's current limit, so its work
+ *   stays usable, and a later start applies the new limit;
+ * - a topic is declared synchronously, before its streams can be inspected,
+ *   so its declaration keeps reporting the drift until the stream holds less.
+ */
+import {
+  type DeadLetterStore,
+  type Job,
+  type JobConfig,
+  type Queue,
+  type QueueConfig,
+  ResourceDriftError,
+  type Sync,
+  type Topic,
+  type TopicConfig,
+} from "@k2b/sync";
+import { jetstreamManager, RetentionPolicy, type StreamInfo } from "@nats-io/jetstream";
+import type { NatsConnection } from "@nats-io/transport-node";
+import { logger } from "../services/logging";
+
+/** Sync 7's limits for a job or queue declared without `retention`, which @k2b/sync does not export. */
+const SYNC_PAYLOAD_BYTES = 128 * 1024;
+const SYNC_DEAD_LETTER_HEADROOM_BYTES = 4096;
+const SYNC_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Byte limit Sync 7 gives a job or queue without `retention`: 256 messages at its payload limit, at most 1 GiB. */
+export const syncDefaultMaxBytes = (maxPayloadBytes = SYNC_PAYLOAD_BYTES): number =>
+  Math.min(1024 ** 3, 256 * (maxPayloadBytes + SYNC_DEAD_LETTER_HEADROOM_BYTES));
+
+const log = logger("sync:budget");
+
+type Kind = "job" | "queue" | "topic";
+type Limits = { work: number; deadLetters: number };
+
+/** Memoizes a promise, forgetting a rejection so the next call retries. */
+const once = <T>(create: () => Promise<T>): (() => Promise<T>) => {
+  let pending: Promise<T> | undefined;
+  return () =>
+    (pending ??= create().catch((error: unknown) => {
+      pending = undefined;
+      throw error;
+    }));
+};
+
+/** The stream and declared byte limit when Sync refused a declaration only for an existing stream's byte limit. */
+const byteLimitDrift = (error: unknown): { stream: string; maxBytes: number } | undefined => {
+  if (!(error instanceof ResourceDriftError) || error.differences.length !== 1) return undefined;
+  const [difference] = error.differences;
+  if (difference?.field !== "max_bytes" || typeof difference.declared !== "number") return undefined;
+  return { stream: error.resource, maxBytes: difference.declared };
+};
+
+/** Byte limits a job or queue declares for its work and dead-letter streams. */
+const declaredLimits = (config: QueueConfig | JobConfig): Limits => {
+  const work = config.retention?.maxBytes ?? syncDefaultMaxBytes(config.maxPayloadBytes);
+  return { work, deadLetters: config.deadLetterRetention?.maxBytes ?? work };
+};
+
+/** The declaration with the given limits, or unchanged when they are its own. */
+const withLimits = <Config extends QueueConfig | JobConfig>(config: Config, target: Limits, limits: Limits): Config =>
+  limits.work === target.work && limits.deadLetters === target.deadLetters
+    ? config
+    : {
+        ...config,
+        retention: { maxAgeMs: SYNC_MAX_AGE_MS, ...config.retention, maxBytes: limits.work },
+        deadLetterRetention: { ...config.deadLetterRetention, maxBytes: limits.deadLetters },
+      };
+
+const createStreamLimits = (connection: NatsConnection, namespace: string) => {
+  const manager = once(() => jetstreamManager(connection));
+
+  /**
+   * Work and dead-letter streams per job and queue of this namespace as they
+   * are now. Concurrent callers share one listing; a later call lists again,
+   * so streams that another process created or changed since are seen.
+   */
+  let listing: Promise<Map<string, StreamInfo[]>> | undefined;
+  const list = () =>
+    (listing ??= (async () => {
+      const jsm = await manager();
+      const streams = new Map<string, StreamInfo[]>();
+      for await (const info of jsm.streams.list()) {
+        const metadata = info.config.metadata;
+        const kind = metadata?.["sync.kind"];
+        if (metadata?.["sync.namespace"] !== namespace || metadata["sync.managed"] !== "true") continue;
+        // A job's coalescing claims live in a KV bucket without a byte limit.
+        if ((kind !== "job" && kind !== "queue") || info.config.name.startsWith("KV_")) continue;
+        const key = `${kind}:${metadata["sync.id"]}`;
+        streams.set(key, [...(streams.get(key) ?? []), info]);
+      }
+      return streams;
+    })().finally(() => {
+      listing = undefined;
+    }));
+
+  /**
+   * Limits a job or queue declares: its own, except for an existing stream
+   * that holds more than its new limit, which keeps its current limit.
+   */
+  const keep = async (kind: Kind, id: string, target: Limits): Promise<Limits> => {
+    const streams = (await list()).get(`${kind}:${id}`) ?? [];
+    const kept = (info: StreamInfo | undefined, maxBytes: number): number => {
+      if (!info || info.config.max_bytes === maxBytes || info.state.bytes <= maxBytes) return maxBytes;
+      log.warn("Kept the byte limit of a Sync stream that holds more than its new limit", {
+        kind,
+        id,
+        stream: info.config.name,
+        limit: info.config.max_bytes,
+        target: maxBytes,
+        held: info.state.bytes,
+      });
+      return info.config.max_bytes;
+    };
+    return {
+      work: kept(
+        streams.find((info) => info.config.retention === RetentionPolicy.Workqueue),
+        target.work,
+      ),
+      deadLetters: kept(
+        streams.find((info) => info.config.retention !== RetentionPolicy.Workqueue),
+        target.deadLetters,
+      ),
+    };
+  };
+
+  /** Streams reported as too full to lower; a topic retries on every use, but logs once. */
+  const reported = new Set<string>();
+
+  /**
+   * Provisions a declaration. Each existing stream whose byte limit differs
+   * from the declared one gets the declared limit if it holds no more; then
+   * the declaration is tried again. Each stream is changed at most once. Of a
+   * topic, only the dead-letter stream, whose subjects end in `.dlq.>`, is
+   * changed: its event stream keeps Sync's drift check, so applications that
+   * declare one topic differently still fail instead of overwriting each
+   * other's limit.
+   */
+  const adopt = async (kind: Kind, id: string, ready: () => Promise<void>): Promise<void> => {
+    const changed = new Set<string>();
+    for (;;) {
+      try {
+        return await ready();
+      } catch (error) {
+        const drift = byteLimitDrift(error);
+        if (!drift || changed.has(drift.stream)) throw error;
+        changed.add(drift.stream);
+        const jsm = await manager();
+        const info = await jsm.streams.info(drift.stream);
+        if (kind === "topic" && !info.config.subjects.some((subject) => subject.endsWith(".dlq.>"))) throw error;
+        if (info.state.bytes > drift.maxBytes) {
+          if (reported.has(drift.stream)) throw error;
+          reported.add(drift.stream);
+          log.warn("Kept the byte limit of a Sync stream that holds more than its new limit", {
+            kind,
+            id,
+            stream: drift.stream,
+            limit: info.config.max_bytes,
+            target: drift.maxBytes,
+            held: info.state.bytes,
+          });
+          throw error;
+        }
+        await jsm.streams.update(drift.stream, { max_bytes: drift.maxBytes });
+        log.info("Changed the byte limit of a Sync stream", {
+          kind,
+          id,
+          stream: drift.stream,
+          from: info.config.max_bytes,
+          to: drift.maxBytes,
+        });
+      }
+    }
+  };
+
+  return { keep, adopt };
+};
+
+const deferDeadLetters = <T>(resolve: () => Promise<{ deadLetters: DeadLetterStore<T> }>): DeadLetterStore<T> => ({
+  page: async (options) => (await resolve()).deadLetters.page(options),
+  get: async (input) => (await resolve()).deadLetters.get(input),
+  list: async (options) => (await resolve()).deadLetters.list(options),
+  requeue: async (input) => (await resolve()).deadLetters.requeue(input),
+  delete: async (input) => (await resolve()).deadLetters.delete(input),
+});
+
+const deferJob = <Input>(resolve: () => Promise<Job<Input>>): Job<Input> => ({
+  ready: async () => (await resolve()).ready(),
+  submit: async (job) => (await resolve()).submit(job),
+  submitMany: async (jobs, options) => (await resolve()).submitMany(jobs, options),
+  submitBatch: async (jobs) => (await resolve()).submitBatch(jobs),
+  pause: async (options) => (await resolve()).pause(options),
+  resume: async () => (await resolve()).resume(),
+  process: async (options, handler) => (await resolve()).process(options, handler),
+  deadLetters: deferDeadLetters(resolve),
+});
+
+const deferQueue = <T>(resolve: () => Promise<Queue<T>>): Queue<T> => ({
+  ready: async () => (await resolve()).ready(),
+  send: async (message) => (await resolve()).send(message),
+  sendBatch: async (messages) => (await resolve()).sendBatch(messages),
+  pause: async (options) => (await resolve()).pause(options),
+  resume: async () => (await resolve()).resume(),
+  process: async (options, handler) => (await resolve()).process(options, handler),
+  reader: async (options) => (await resolve()).reader(options),
+  deadLetters: deferDeadLetters(resolve),
+});
+
+/** A declared topic whose every provisioning use waits until `ready` has adopted its streams. */
+const deferTopic = <T>(topic: Topic<T>, ready: () => Promise<void>): Topic<T> => {
+  const whenReady = <Result>(use: () => Promise<Result>): Promise<Result> => ready().then(use);
+  const iterateWhenReady = async function* <Event>(open: () => AsyncIterable<Event>): AsyncIterable<Event> {
+    await ready();
+    yield* open();
+  };
+  return {
+    ready,
+    publish: (input) => whenReady(() => topic.publish(input)),
+    publishBatch: (input) => whenReady(() => topic.publishBatch(input)),
+    hub: (options) => {
+      const hub = topic.hub(options);
+      return { subscribe: (subscription) => iterateWhenReady(() => hub.subscribe(subscription)), close: () => hub.close() };
+    },
+    cursorSequence: (cursor) => topic.cursorSequence(cursor),
+    cursorAt: (sequence) => topic.cursorAt(sequence),
+    pauseConsumer: (input) => whenReady(() => topic.pauseConsumer(input)),
+    resumeConsumer: (input) => whenReady(() => topic.resumeConsumer(input)),
+    latestCursor: (options) => whenReady(() => topic.latestCursor(options)),
+    head: () => whenReady(() => topic.head()),
+    live: (options) => iterateWhenReady(() => topic.live(options)),
+    replay: (options) => iterateWhenReady(() => topic.replay(options)),
+    follow: (options) => iterateWhenReady(() => topic.follow(options)),
+    destroy: () => topic.destroy(),
+    process: (options, handler) => whenReady(() => topic.process(options, handler)),
+    deadLetters: {
+      list: (options) => whenReady(() => topic.deadLetters.list(options)),
+      get: (input) => whenReady(() => topic.deadLetters.get(input)),
+      delete: (input) => whenReady(() => topic.deadLetters.delete(input)),
+      replay: (input) => whenReady(() => topic.deadLetters.replay(input)),
+    },
+  };
+};
+
+/**
+ * The process Sync whose jobs, queues, and topics adopt the byte limits of
+ * their existing streams before first use. A job or queue is declared to Sync
+ * on its first use or on `ready()`; a topic is declared at once. Every other
+ * primitive is Sync's own.
+ */
+export const withSyncBudgets = (sync: Sync, { connection, namespace }: { connection: NatsConnection; namespace: string }): Sync => {
+  const { keep, adopt } = createStreamLimits(connection, namespace);
+  /** Every job, queue, and topic declared so far, so `ready()` provisions them like Sync does. */
+  const declared = new Map<string, () => Promise<unknown>>();
+
+  const declareWork = <Config extends QueueConfig | JobConfig, Handle extends { ready(): Promise<void> }>(
+    kind: "job" | "queue",
+    config: Config,
+    create: (config: Config) => Handle,
+  ): (() => Promise<Handle>) => {
+    // Declared once: Sync refuses a second declaration with other limits, so a
+    // failed first use retries provisioning with the limits chosen first.
+    const declaration = once(async () => {
+      const target = declaredLimits(config);
+      return create(withLimits(config, target, await keep(kind, config.id, target)));
+    });
+    const resolve = once(async () => {
+      const handle = await declaration();
+      await adopt(kind, config.id, () => handle.ready());
+      return handle;
+    });
+    declared.set(`${kind}:${config.id}`, resolve);
+    return resolve;
+  };
+
+  return {
+    ...sync,
+    ready: async () => {
+      await Promise.all([...declared.values()].map((resolve) => resolve()));
+      await sync.ready();
+    },
+    job: <Input>(config: JobConfig) => deferJob(declareWork("job", config, (declaration) => sync.job<Input>(declaration))),
+    queue: <T>(config: QueueConfig) => deferQueue(declareWork("queue", config, (declaration) => sync.queue<T>(declaration))),
+    topic: <T>(config: TopicConfig) => {
+      const topic = sync.topic<T>(config);
+      const ready = once(() => adopt("topic", config.id, () => topic.ready()));
+      declared.set(`topic:${config.id}`, ready);
+      return deferTopic(topic, ready);
+    },
+  };
+};

package/src/ai/code-mode-skill.ts

@@ -4,7 +4,7 @@ import type { AiSkillTemplate } from "./skills";
 
 export const ASSISTANT_CODE_MODE_SKILL = {
   "key": "assistant:code-mode",
-  "version": 55,
+  "version": 56,
   "name": "assistant-code-mode",
   "description": "Inspect and transform unfamiliar data, analyze files, compare results across Cloud apps, or build and improve interactive and agent-only Apps in Assistant Studio. Use for quick code experiments, data analysis, file generation, resource SQL queries and combining discovered Cloud capabilities. For plain arithmetic or date offsets, answer directly or use calculate.",
   "instructions": "# Assistant code mode\n\nChoose the smallest useful result: one-off answer, exported file, or reusable\nStudio App. Apps may expose agent actions, a display-only dashboard, or both.\nPersistence is optional. One-off scripts stay in their chat and cannot be shared. Reuse an\nexisting Cloud feature when it fits. For a\nquick reading of an uploaded PDF or Office document, `read_file` can return\nMarkdown; use code for exact cells, calculations, original PDF text or positions.\n\n## Start from the contract\n\nLoad the needed `code_*` tools individually through `load_tools` and read their\ninput schemas. They are Assistant tools, not capabilities or functions inside\ncode. Discover other Cloud operations before using `capabilities.run`.\n\nRuntime namespaces are globals: no imports or package installation are needed.\nOnly relative imports of the resource's own source files are supported. There is\nno DOM or native network access. Before using a namespace, read its reference\nbelow for signatures, options and return values. Do not invent methods or infer\nan API from a familiar library. For discovered Cloud capabilities and external\nAPIs, obtain their actual contracts separately.\n\nInspect supplied data before joining, filtering or calculating: column names,\ntypes, units, date ranges and missing values. Ask only for decisions or inputs\nthat cannot be established from available evidence. For several real steps,\nkeep a short `todo_write` plan and update it as work changes; skip ceremony for a\nsmall experiment. A failed experiment should change the next hypothesis.\n\n## First file script\n\nPass exact current-chat manifest paths as `code_run.inputPaths`, and this entry\nas `code_run.code` for a small CSV:\n\n```js\nexport default async () => {\n  const [input] = await files.list();\n  if (!input) throw new Error(\"Select a CSV input.\");\n  const rows = await sheet.fromCsv(await files.read(input.name));\n  return { rows: rows.length, columns: Object.keys(rows[0] ?? {}), sample: rows.slice(0, 3) };\n};\n```\n\n`input.name` is the full path, such as `/sales.csv`; pass it unchanged to\n`files.read`, which returns a `File`. CSV rows are objects keyed by headers:\n`rows[0]` is already data. Do not drop it. For older Excel CSVs, use\n`sheet.fromCsv(file, {encoding:\"windows-1252\"})`. Inspect actual headings first.\nFor a tiny experiment without files, `export default () => ({answer:42})` suffices.\nEach run has fresh variables. No saved resource or UI is required.\n\n## Reference routing\n\nRead only the rows relevant to the task. Each link describes its own complete\nsupported surface; links within references add related workflows when needed.\n\n| Task / API | Read |\n| --- | --- |\n| Source entry, input/output files, pickers, CSV, IDs | [Runtime and files](/skills/assistant-code-mode/references/runtime.md) |\n| Inspect PDF pages, read PDF text/positions or XLSX/ODS cells, write ODS | [Documents](/skills/assistant-code-mode/references/documents.md) |\n| Generate a PDF, save one in Files, embed attachments, combine invoice HTML and XML | [PDF generation](/skills/assistant-code-mode/references/pdf.md) |\n| Exact amounts, taxes, allocation, localized money | [Money](/skills/assistant-code-mode/references/money.md) |\n| Export DATEV bookings or SEPA transfers | [DATEV and SEPA](/skills/assistant-code-mode/references/finance.md) |\n| Parse a CAMT bank report | [Bank reports](/skills/assistant-code-mode/references/camt.md) |\n| Calculate, create or read electronic invoices/XML/PDF attachments | [Electronic invoices](/skills/assistant-code-mode/references/einvoice.md) |\n| Controls, layouts and dialogs | [UI and dialogs](/skills/assistant-code-mode/references/ui.md), [Analytics UI](/skills/assistant-code-mode/references/analytics.md) |\n| Chart types, series and axes | [Charts](/skills/assistant-code-mode/references/charts.md) |\n| Long processing, progress, cancellation | [Background work](/skills/assistant-code-mode/references/work.md) |\n| Persist JSON or files locally/shared | [Storage](/skills/assistant-code-mode/references/storage.md) |\n| Copy files between stores; list and download Filesv2 beside Grids documents | [File transfers](/skills/assistant-code-mode/references/files.md) |\n| Resource SQL, schema, row CRUD, imports | [Database](/skills/assistant-code-mode/references/database.md) |\n| Generate text, classify data or extract structured fields | [AI calculations](/skills/assistant-code-mode/references/ai.md) |\n| Discovered Cloud queries/actions | [Capability calls](/skills/assistant-code-mode/references/capabilities.md) |\n| External HTTPS and personal secrets | [HTTP and secrets](/skills/assistant-code-mode/references/http.md) |\n| Call a published App action; declare handlers | [App actions](/skills/assistant-code-mode/references/app-actions.md) |\n| Reuse work across chats, create or edit an App | [Source workflow](/skills/assistant-code-mode/references/source-workflow.md) |\n| Publish, restore, copy | [Publishing](/skills/assistant-code-mode/references/publishing.md) |\n| Find recipients or change App/Skill sharing | [Access](/skills/assistant-code-mode/references/access.md) |\n| Inspect, export, clear server data, or delete an App | [Management](/skills/assistant-code-mode/references/management.md) |\n| Execute, inspect, interact, export, stop, diagnose errors | [Run and debug](/skills/assistant-code-mode/references/debugging.md) |\n| Unfamiliar inputs or cross-app investigation | [Investigation](/skills/assistant-code-mode/references/investigation.md) |\n| Complete app starters | [Examples](/skills/assistant-code-mode/references/examples.md) |\n\nFor a new app, read Source workflow and the closest complete example before\nwriting source, plus only the API references it uses. For analytical reports or\ndashboards, also load `assistant-data-analysis` for metrics and source validation.\n\n## Choose the delivery\n\nFor a one-off chart, calculator, or interactive analysis in this conversation,\nuse `code_run({code,inputPaths})`, test the controls, then\n`code_present({runId,title})`. Read [Chat visualizations](/skills/assistant-code-mode/references/chat.md).\nA successful run is visible to the agent only; present it before saying the\nuser can see it. No saved App or chat file is necessary.\n\nUse a Studio App when the user needs an independently accessible, reusable\napplication. Use `files.save`, `code_export`, and `present` when the requested\nresult is a file. These are separate delivery choices.\n\n## Verify and deliver\n\nRun the actual source (the saved revision for Apps) and test relevant controls with IDs returned by\n`code_run`/`code_interact`, including invalid inputs and picker fixtures. Creating,\ncompiling or saving source does not verify behavior. If `work.status` is\n`running`, wait with `code_inspect({runId,waitMs:30000})`; do not restart the job.\nInspect only when the returned snapshot needs more detail. Errors and\n`outputTruncated` are not successful complete results.\n\nFor a CSV, call `await files.save(sheet.toCsv(rows), \"result.csv\")` inside code;\nfor a spreadsheet, `await files.save(await sheet.toOds(sheets), \"result.ods\")`.\nThen call the **tool** `code_export` with the returned `runId` and captured file\nname, and `present` its returned chat path. `files.save` returns no path.\nReuse exported data via its path/version rather than retyping truncated output.\nReconcile row counts, exclusions and totals before reporting findings.\n\nOpen GUI apps with `code_open`. Saving or testing does\nnot replace a user's already-running app. Stop runs no longer needed that retain\nUI, jobs or output files. Never claim an unexecuted result is verified.\n\nAgent execution runs independently of the user's tab. Agent local storage is\ntemporary; shared storage, database writes and external actions are real, even\nin tests. Cancellation and source restore do not undo them. Apps select local\nfiles explicitly; they never gain implicit access to chat attachments. Use\n`code_secret` for credentials, never chat or app controls. Honor normal access\nand approval decisions; availability is not authorization for unrelated actions.",
@@ -56,7 +56,7 @@ export const ASSISTANT_CODE_MODE_SKILL = {
     },
     {
       "path": "references/einvoice.md",
-      "content": "# Electronic invoices\n\n`einvoice` is a global. These methods return Results: inspect `ok`, then use\n`data` or `error: {code,status,message,issues}`. Issue entries contain\n`{code,path,message,line?,column?}`; paths have zero-based row indices.\n\n| Call | Successful `data` |\n| --- | --- |\n| `einvoice.validate(input)` | `Invoice` |\n| `einvoice.calculate(lines)` | `InvoiceCalculation` |\n| `einvoice.serialize(invoice, {format: \"zugferd-2.5-en16931\"})` | `{format, xml: string, bytes: Uint8Array}` |\n| `einvoice.parseXml(xml, options?)` | `ParsedInvoice` |\n| `await einvoice.parsePdf(bytes, options?)` | `ParsedInvoice` |\n| `einvoice.parseXml(xml, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n| `await einvoice.parsePdf(bytes, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n\nAll calls except `parsePdf` are synchronous. `parsePdf` takes a `Uint8Array`,\nfor example `new Uint8Array(await file.arrayBuffer())`. It reads embedded XML,\nnot scanned pages or arbitrary visual invoice layouts. For those, use the\n[local PDF text reader](documents.md) or the agent's document/vision tools.\n\nThe supported slice covers EUR CII EN16931 invoices, credit notes and self-billing,\nVAT categories S/Z/E/AE/K/G/O, units C62/HUR/DAY/KGM. Generation does not\nsupport UBL, XRechnung, discounts or prepayments. Readers preserve declared totals;\nparsing is not arithmetic verification. Validation is not XSD or Schematron\ncertification. No XSD validator is exposed.\n\n## Complete input and result shapes\n\nType descriptions only; no imports are needed. All fields are required unless\nmarked `?`; unknown fields are rejected.\n\n```ts\ntype Party = {\n  name: string; id?: string; vatId: string; // \"\" when the party has no VAT ID\n  address: {line1: string; city: string; postalCode: string; countryCode: string};\n};\ntype Tax = {\n  taxCategory?: \"S\" | \"Z\" | \"E\" | \"AE\" | \"K\" | \"G\" | \"O\"; // default \"S\"\n  taxRate: string; taxExemptionReason?: string; taxExemptionReasonCode?: string;\n};\ntype InvoiceLine = Tax & {\n  id: string; name: string; description?: string;\n  quantity: string; unitPrice: string; unitCode: \"C62\" | \"HUR\" | \"DAY\" | \"KGM\";\n  netAmount?: string;\n};\ntype InvoiceTotals = {\n  netAmount: string; taxAmount: string; grossAmount: string; dueAmount: string;\n  taxGroups: (Tax & {netAmount: string; taxAmount: string})[];\n};\ntype Invoice = {\n  kind: \"invoice\" | \"creditNote\" | \"selfBilling\";\n  number: string; invoiceDate: string; serviceDate: string; dueDate: string;\n  currency: \"EUR\"; seller: Party & {taxRegistrationId?: string}; buyer: Party;\n  deliverToCountryCode?: string; buyerReference: string;\n  notes?: string[];\n  precedingInvoice?: {number: string; invoiceDate: string};\n  payment: {iban: string; accountName: string};\n  lines: InvoiceLine[]; totals?: InvoiceTotals;\n};\ntype InvoiceCalculation = InvoiceTotals & {\n  lines: (InvoiceLine & {netAmount: string})[];\n};\ntype ParsedInvoice = {\n  format: \"zugferd-2.5-en16931\"; profile: string; xml: string;\n  invoice: Invoice; filename?: string;\n};\ntype ParseOptions = {maxCharacters?: number; maxElements?: number; maxDepth?: number};\ntype PdfOptions = ParseOptions & {maxPdfBytes?: number};\n```\n\nXML options default to 10 Mi UTF-16 code units, 100,000 elements, depth 64.\nPDF input defaults to 25 MiB. Overrides must be positive safe integers.\nA parser result's business fields are under **`data.invoice`**. Calculated\namounts are directly under **`data.netAmount`**, etc., with no `data.totals` wrapper.\n\n- Dates are real `YYYY-MM-DD` dates; `dueDate` cannot precede `invoiceDate`.\n  Credit notes require `precedingInvoice`, whose date cannot be later than the\n  credit note; other kinds cannot supply it. Credit-note amounts stay unsigned.\n- Lines: 1–1000, unique IDs. Quantities are positive, prices nonnegative,\n  VAT rates at most 100. Decimal strings allow up to four\n  fractional digits and no leading zeros. Totals/net amounts require exactly\n  two fractional digits; do not convert through JavaScript Number.\n- Country codes: two uppercase letters. `payment.iban` must be valid.\n  Required text is nonblank valid XML text. Limits: number/reference/line ID/VAT ID\n  100; names/address line/accountName 200; city 100; postalCode 20;\n  line description and each note 4000; at most 100 notes.\n- Category S needs a positive rate; every other category uses `taxRate: \"0\"`\n  and zero tax. E/AE/K/G/O need `taxExemptionReason` or a VATEX\n  `taxExemptionReasonCode`; S/Z forbid both. O cannot be mixed with other\n  categories and requires `vatId: \"\"` for both parties. A seller without a VAT\n  ID needs `seller.id` and, outside O, `seller.taxRegistrationId`. AE/K need a\n  buyer VAT ID, K/G a seller VAT ID, and K `deliverToCountryCode`.\n- `calculate` rounds each line half up to cents, then VAT per category and rate. It recalculates\n  line `netAmount`; `serialize` also rejects supplied line/totals values that\n  disagree. Render these calculated amounts in HTML instead of another arithmetic path.\n\n## Minimal supported invoice\n\nUse real business data and an app-owned invoice number. This illustrative\nfixture demonstrates the required fields; it is not a document to issue.\n\n```js\nconst invoice = {\n  kind: \"invoice\",\n  number: \"EXAMPLE-42\",\n  invoiceDate: \"2026-09-15\",\n  serviceDate: \"2026-09-15\",\n  dueDate: \"2026-09-30\",\n  currency: \"EUR\",\n  seller: {\n    name: \"Example Seller\", vatId: \"DE123456789\",\n    address: { line1: \"Street 1\", city: \"Ulm\", postalCode: \"89073\", countryCode: \"DE\" },\n  },\n  buyer: {\n    name: \"Example Buyer\", vatId: \"DE987654321\",\n    address: { line1: \"Street 2\", city: \"Berlin\", postalCode: \"10115\", countryCode: \"DE\" },\n  },\n  buyerReference: \"ORDER-42\",\n  payment: { iban: \"DE89370400440532013000\", accountName: \"Example Seller\" },\n  lines: [{ id: \"1\", name: \"Service\", quantity: \"2.0000\", unitPrice: \"50.0000\", unitCode: \"HUR\", taxRate: \"19.00\" }],\n};\nconst result = einvoice.serialize(invoice, { format: \"zugferd-2.5-en16931\" });\nif (!result.ok) throw new Error(JSON.stringify(result.error));\nawait files.save(new Blob([result.data.bytes], { type: \"application/xml\" }), \"invoice.xml\");\n```\n\nNever infer a missing VAT identifier, tax category, exemption reason, account\nor business reference merely to satisfy input validation.\n\n## Reading received invoices\n\n`{mode: \"incoming\"}` (plus the same limits) reads a broader separate model:\nalso XRechnung 3.0/2.3 CII, other currencies, discounts, prepayments, all\npayment means and optional references. `data` is\n`{format: \"cii-en16931\", profile, xml, invoice, unmapped, filename?}`.\nAmounts are declared strings, never recalculated; O lines have no `taxRate`.\n`unmapped` lists supplementary XML elements and attributes with their paths; review it before\naccounting. Do not pass this `invoice` to `validate` or `serialize`.\n\nFor an invoice PDF, pass `serialized.data.xml` to\n[`pdf.facturX`](pdf.md) with profile `\"EN 16931\"` and matching HTML.\nNumbering, business mapping, issuance and persistence belong to the app.\n"
+      "content": "# Electronic invoices\n\n`einvoice` is a global. These methods return Results: inspect `ok`, then use\n`data` or `error: {code,status,message,issues}`. Issue entries contain\n`{code,path,message,line?,column?}`; paths have zero-based row indices.\n\n| Call | Successful `data` |\n| --- | --- |\n| `einvoice.validate(input)` | `Invoice` |\n| `einvoice.calculate(lines)` | `InvoiceCalculation` |\n| `einvoice.serialize(invoice, {format: \"zugferd-2.5-en16931\"})` | `{format, xml: string, bytes: Uint8Array}` |\n| `einvoice.parseXml(xml, options?)` | `ParsedInvoice` |\n| `await einvoice.parsePdf(bytes, options?)` | `ParsedInvoice` |\n| `einvoice.parseXml(xml, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n| `await einvoice.parsePdf(bytes, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n\nAll calls except `parsePdf` are synchronous. `parsePdf` takes a `Uint8Array`,\nfor example `new Uint8Array(await file.arrayBuffer())`. It reads embedded XML,\nnot scanned pages or arbitrary visual invoice layouts. For those, use the\n[local PDF text reader](documents.md) or the agent's document/vision tools.\n\nThe supported slice covers EUR CII EN16931 invoices, credit notes, self-billing\nand self-billed credit notes, VAT categories S/Z/E/AE/K/G/O, units\nC62/HUR/DAY/KGM, and payment by credit transfer, cash, online service or\nclearing, or no payment means. Generation does not support UBL, XRechnung,\ndiscounts or prepayments. Readers preserve declared totals; parsing is not\narithmetic verification. Validation is not XSD or Schematron certification.\nNo XSD validator is exposed.\n\n## Complete input and result shapes\n\nType descriptions only; no imports are needed. All fields are required unless\nmarked `?`; unknown fields are rejected.\n\n```ts\ntype Party = {\n  name: string; id?: string; vatId: string; // \"\" when the party has no VAT ID\n  address: {line1: string; city: string; postalCode: string; countryCode: string};\n};\ntype Tax = {\n  taxCategory?: \"S\" | \"Z\" | \"E\" | \"AE\" | \"K\" | \"G\" | \"O\"; // default \"S\"\n  taxRate: string; taxExemptionReason?: string; taxExemptionReasonCode?: string;\n};\ntype InvoiceLine = Tax & {\n  id: string; name: string; description?: string;\n  quantity: string; unitPrice: string; unitCode: \"C62\" | \"HUR\" | \"DAY\" | \"KGM\";\n  netAmount?: string;\n};\ntype InvoiceTotals = {\n  netAmount: string; taxAmount: string; grossAmount: string; dueAmount: string;\n  taxGroups: (Tax & {netAmount: string; taxAmount: string})[];\n};\ntype Invoice = {\n  kind: \"invoice\" | \"creditNote\" | \"selfBilling\" | \"selfBillingCreditNote\";\n  number: string; invoiceDate: string; dueDate: string;\n  serviceDate?: string; period?: {startDate?: string; endDate?: string};\n  currency: \"EUR\"; seller: Party & {taxRegistrationId?: string}; buyer: Party;\n  deliverToCountryCode?: string; buyerReference: string;\n  notes?: string[];\n  precedingInvoice?: {number: string; invoiceDate: string};\n  payment?: {\n    typeCode?: \"10\" | \"30\" | \"58\" | \"68\" | \"97\"; // default \"58\"\n    information?: string; iban?: string; accountName?: string;\n  };\n  lines: InvoiceLine[]; totals?: InvoiceTotals;\n};\ntype InvoiceCalculation = InvoiceTotals & {\n  lines: (InvoiceLine & {netAmount: string})[];\n};\ntype ParsedInvoice = {\n  format: \"zugferd-2.5-en16931\"; profile: string; xml: string;\n  invoice: Invoice; filename?: string;\n};\ntype ParseOptions = {maxCharacters?: number; maxElements?: number; maxDepth?: number};\ntype PdfOptions = ParseOptions & {maxPdfBytes?: number};\n```\n\nXML options default to 10 Mi UTF-16 code units, 100,000 elements, depth 64.\nPDF input defaults to 25 MiB. Overrides must be positive safe integers.\nA parser result's business fields are under **`data.invoice`**. Calculated\namounts are directly under **`data.netAmount`**, etc., with no `data.totals` wrapper.\nA parsed invoice carries `serviceDate`, `period`, `payment` and the account\nfields only when the XML does: check each before reading it, for example\n`invoice.payment?.iban`. A parsed `payment` always has its `typeCode`.\n\n- Dates are real `YYYY-MM-DD` dates; `dueDate` cannot precede `invoiceDate`.\n  `serviceDate` (delivery date) and `period` (invoicing period) are optional\n  and can be combined. A `period` needs a start or an end, and its end cannot\n  precede its start.\n- `creditNote` and `selfBillingCreditNote` require `precedingInvoice`; every\n  kind may supply it, and its date cannot be later than `invoiceDate`.\n  Credit-note amounts stay unsigned.\n- `payment.typeCode`: `\"58\"` SEPA credit transfer, `\"30\"` credit transfer,\n  `\"10\"` cash, `\"68\"` online payment service, `\"97\"` clearing between\n  partners. 30 and 58 require `iban`; `accountName` is optional. The other\n  codes forbid both. `information` is free text for any code. Omit `payment`\n  when no payment means applies. Any other code fails both writing and the\n  default reader; read such invoices with `{mode: \"incoming\"}`.\n- Lines: 1–1000, unique IDs. Quantities are positive, prices nonnegative,\n  VAT rates at most 100. Decimal strings allow up to four\n  fractional digits and no leading zeros. Totals/net amounts require exactly\n  two fractional digits; do not convert through JavaScript Number.\n- Country codes: two uppercase letters. A supplied `payment.iban` must be valid.\n  Required text is nonblank valid XML text. Limits: number/reference/line ID/VAT ID\n  100; names/address line/accountName 200; city 100; postalCode 20;\n  line description, `payment.information` and each note 4000; at most 100 notes.\n- Category S needs a positive rate; every other category uses `taxRate: \"0\"`\n  and zero tax. E/AE/K/G/O need `taxExemptionReason` or a VATEX\n  `taxExemptionReasonCode`; S/Z forbid both. O cannot be mixed with other\n  categories and requires `vatId: \"\"` for both parties. A seller without a VAT\n  ID needs `seller.id` and, outside O, `seller.taxRegistrationId`. AE/K need a\n  buyer VAT ID, K/G a seller VAT ID, and K `deliverToCountryCode` plus a\n  `serviceDate` or `period`.\n- `calculate` rounds each line half up to cents, then VAT per category and rate. It recalculates\n  line `netAmount`; `serialize` also rejects supplied line/totals values that\n  disagree. Render these calculated amounts in HTML instead of another arithmetic path.\n\n## Example invoice\n\nUse real business data and an app-owned invoice number. This illustrative\nfixture is a credit-transfer invoice with a delivery date; it is not a\ndocument to issue.\n\n```js\nconst invoice = {\n  kind: \"invoice\",\n  number: \"EXAMPLE-42\",\n  invoiceDate: \"2026-09-15\",\n  serviceDate: \"2026-09-15\",\n  dueDate: \"2026-09-30\",\n  currency: \"EUR\",\n  seller: {\n    name: \"Example Seller\", vatId: \"DE123456789\",\n    address: { line1: \"Street 1\", city: \"Ulm\", postalCode: \"89073\", countryCode: \"DE\" },\n  },\n  buyer: {\n    name: \"Example Buyer\", vatId: \"DE987654321\",\n    address: { line1: \"Street 2\", city: \"Berlin\", postalCode: \"10115\", countryCode: \"DE\" },\n  },\n  buyerReference: \"ORDER-42\",\n  payment: { iban: \"DE89370400440532013000\", accountName: \"Example Seller\" },\n  lines: [{ id: \"1\", name: \"Service\", quantity: \"2.0000\", unitPrice: \"50.0000\", unitCode: \"HUR\", taxRate: \"19.00\" }],\n};\nconst result = einvoice.serialize(invoice, { format: \"zugferd-2.5-en16931\" });\nif (!result.ok) throw new Error(JSON.stringify(result.error));\nawait files.save(new Blob([result.data.bytes], { type: \"application/xml\" }), \"invoice.xml\");\n```\n\nNever infer a missing VAT identifier, tax category, exemption reason, delivery\ndate, account or business reference merely to satisfy input validation.\n\n## Reading received invoices\n\n`{mode: \"incoming\"}` (plus the same limits) reads a broader separate model:\nalso XRechnung 3.0/2.3 CII, other currencies, discounts, prepayments, all\npayment means and optional references. `data` is\n`{format: \"cii-en16931\", profile, xml, invoice, unmapped, filename?}`.\nAmounts are declared strings, never recalculated; O lines have no `taxRate`.\n`unmapped` lists supplementary XML elements and attributes with their paths; review it before\naccounting. Do not pass this `invoice` to `validate` or `serialize`.\n\nFor an invoice PDF, pass `serialized.data.xml` to\n[`pdf.facturX`](pdf.md) with profile `\"EN 16931\"` and matching HTML.\nNumbering, business mapping, issuance and persistence belong to the app.\n"
     },
     {
       "path": "references/examples.md",

package/src/config/env.ts

@@ -72,6 +72,11 @@ const registry = defineEnv({
     example: "localhost:3000",
     doc: "Public Cloud URL used to bootstrap the `app.url` setting; the stored setting wins once written.",
   },
+  GOTENBERG_URL: {
+    schema: z.string(),
+    example: "http://localhost:3001",
+    doc: "Internal Gotenberg base URL used to bootstrap the `gotenberg.url` PDF rendering setting; the stored setting wins once written.",
+  },
   APP_SECRET: {
     schema: z.string(),
     default: "",

package/src/server/locale.ts

@@ -9,20 +9,33 @@ type LocaleContext = {
   req: { raw: { headers: Headers } };
 };
 
+/**
+ * Languages Cloud ships platform catalogs for and offers in its language
+ * picker. `Accept-Language` negotiation prefers a tag in one of these.
+ */
+const CATALOG_LANGUAGES = new Set(["en", "de"]);
+
 /**
  * The caller's explicit locale preference, or `undefined` when the request
  * carries none. Precedence: `x-cloud-locale` transport metadata, then the
- * `cloud.locale` cookie, then `Accept-Language` in quality order. Every
- * candidate is canonicalized; invalid tags fall through to the next source.
+ * `cloud.locale` cookie, then `Accept-Language`. Every candidate is
+ * canonicalized; invalid tags fall through to the next source.
+ *
+ * `Accept-Language` picks the first tag in quality order whose language has a
+ * catalog, keeping its region (`de-CH`, `en-GB`) for formatting. Without such a
+ * tag, the first valid tag still wins so formatting follows the browser.
  */
 export const preferredLocale = (headers: Headers): string | undefined => {
   const explicit = canonicalLocale(headers.get(LOCALE_HEADER)) ?? canonicalLocale(readCookie(headers, LOCALE_COOKIE));
   if (explicit) return explicit;
+  let firstValid: string | undefined;
   for (const tag of i18n.parseAcceptLanguage(headers.get("Accept-Language"))) {
     const candidate = canonicalLocale(tag);
-    if (candidate) return candidate;
+    if (!candidate) continue;
+    if (CATALOG_LANGUAGES.has(new Intl.Locale(candidate).language)) return candidate;
+    firstValid ??= candidate;
   }
-  return undefined;
+  return firstValid;
 };
 
 /**

package/src/server/middleware/validator.ts

@@ -1,5 +1,5 @@
 import type { Context, ValidationTargets } from "hono";
-import { validator as honoValidator } from "hono-openapi";
+import { type GenerateSpecOptions, validator as honoValidator } from "hono-openapi";
 import type { ZodType } from "zod";
 
 export type ValidatorError = Readonly<{
@@ -9,6 +9,28 @@ export type ValidatorError = Readonly<{
 
 export type ValidatorErrorResolver = (context: Context) => ValidatorError;
 
+/**
+ * OpenAPI description of the 400 body `validator()` sends: `{ message }`, or
+ * `{ code, message }` from a route's error resolver. The generated spec of
+ * every application uses it for validated routes that do not describe their
+ * own 400, in place of hono-openapi's default body, which Cloud never sends.
+ */
+export const validationErrorResponse: Exclude<GenerateSpecOptions["defaultValidationErrorResponse"], boolean> = {
+  description: "Validation failed",
+  content: {
+    "application/json": {
+      schema: {
+        type: "object",
+        properties: {
+          message: { type: "string" },
+          code: { type: "string" },
+        },
+        required: ["message"],
+      },
+    },
+  },
+};
+
 /**
  * Zod validator middleware with pretty error messages and OpenAPI support.
  * Uses hono-openapi validator for automatic OpenAPI schema generation.

package/src/services/gateway.ts

@@ -132,6 +132,11 @@ export const latestGatewayRouteSnapshot = async (): Promise<GatewayRouteSnapshot
   return all.sort((a, b) => b.updatedAt - a.updatedAt)[0] ?? null;
 };
 
+/**
+ * Dead letters keep the event stream's limit. Gateway Ops leaves dead letters
+ * when rollup writes fail; if they exceeded a lowered limit, this topic, and
+ * with it Gateway Ops' start, would fail until they expired.
+ */
 export const gatewayTelemetryTopic = lazySync((sync) =>
   sync.topic<GatewayTelemetryEvent>({
     id: TOPIC_ID,

package/src/services/index.ts

@@ -148,6 +148,7 @@ export {
   MARKDOWN_PDF_TEMPLATE_IDS,
   MarkdownPdfError,
   buildMarkdownPdfHtml,
+  buildPresetPdfHtml,
   getGotenbergConfig,
   attachPdfFiles,
   attachPdfFilesWithConfig,
@@ -163,6 +164,7 @@ export {
   testGotenberg,
 } from "./pdf";
 export type {
+  BuildPresetPdfHtmlInput,
   GotenbergConfig,
   AttachPdfFilesInput,
   RenderFacturXHtmlToPdfInput,

package/src/services/pdf/index.ts

@@ -22,6 +22,7 @@ export {
   testGotenberg,
 } from "./gotenberg";
 export type {
+  BuildPresetPdfHtmlInput,
   MarkdownPdfErrorCode,
   MarkdownPdfTemplateId,
   RenderMarkdownToPdfInput,
@@ -29,6 +30,7 @@ export type {
 } from "./markdown";
 export {
   buildMarkdownPdfHtml,
+  buildPresetPdfHtml,
   MARKDOWN_PDF_MAX_CUSTOM_CSS_BYTES,
   MARKDOWN_PDF_MAX_MARKDOWN_BYTES,
   MARKDOWN_PDF_TEMPLATE_IDS,

package/src/services/pdf/markdown.ts

@@ -38,6 +38,27 @@ export type RenderMarkdownToPdfInput = {
 
 export type RenderMarkdownToPdfOptions = RenderHtmlToPdfOptions;
 
+export type BuildPresetPdfHtmlInput = {
+  /** Body HTML the application rendered from its own document format. */
+  html: string;
+  templateId?: MarkdownPdfTemplateId;
+  customCss?: string;
+  /** Application CSS for its own elements, applied after the preset and before `customCss`. */
+  css?: string;
+};
+
+// Noto Serif, which Gotenberg ships, forms f-ligatures for the report body. It
+// has no "≠" but has "=" and the combining overlay U+0338, so Chromium would
+// build "≠" from both and draw "=/". Without U+0338 in the range, such
+// characters fall back whole to the next font. local() takes the PostScript
+// name and fetches nothing.
+const REPORT_SERIF_RANGE = "U+0-337, U+339-10FFFF";
+const REPORT_SERIF_FACES = `
+@font-face { font-family: "Report Noto Serif"; src: local("NotoSerif-Regular"); unicode-range: ${REPORT_SERIF_RANGE}; }
+@font-face { font-family: "Report Noto Serif"; src: local("NotoSerif-Bold"); font-weight: bold; unicode-range: ${REPORT_SERIF_RANGE}; }
+@font-face { font-family: "Report Noto Serif"; src: local("NotoSerif-Italic"); font-style: italic; unicode-range: ${REPORT_SERIF_RANGE}; }
+@font-face { font-family: "Report Noto Serif"; src: local("NotoSerif-BoldItalic"); font-weight: bold; font-style: italic; unicode-range: ${REPORT_SERIF_RANGE}; }`;
+
 const TEMPLATE_CSS: Record<MarkdownPdfTemplateId, string> = {
   document: `
 @page { size: A4; margin: 22mm 20mm 24mm; }
@@ -58,9 +79,9 @@ th { background: #f1f5f9; font-weight: 650; }
 thead { display: table-header-group; } tr { break-inside: avoid; }
 hr { border: 0; border-top: 1px solid #cbd5e1; margin: 1.5em 0; }
 `,
-  report: `
+  report: `${REPORT_SERIF_FACES}
 @page { size: A4; margin: 24mm 22mm 26mm; }
-:root { color: #263244; font: 10.75pt/1.58 Georgia, "Times New Roman", serif; }
+:root { color: #263244; font: 10.75pt/1.58 Georgia, "Report Noto Serif", "Times New Roman", serif; }
 body { margin: 0; background: #fff; }
 .markdown-document { max-width: 100%; overflow-wrap: anywhere; }
 h1, h2, h3, h4, h5, h6 { color: #13233a; font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; line-height: 1.18; break-after: avoid-page; }
@@ -114,6 +135,12 @@ const safeLink = (value: string): string | null => {
 const renderMarkdown = (source: string): string => {
   const renderer = new Renderer();
   renderer.html = ({ text }: Tokens.HTML | Tokens.Tag) => escapeHtml(text);
+  // marked flags text that follows an inline <pre>, <code>, <kbd> or <script>
+  // tag as already escaped, because it expects that tag to reach the output as
+  // HTML. The tag is escaped here, so the text after it is escaped as well.
+  renderer.text = function (token: Tokens.Text | Tokens.Escape) {
+    return Renderer.prototype.text.call(this, token.type === "text" && token.escaped ? { ...token, escaped: false } : token);
+  };
   renderer.image = ({ href, title, text }: Tokens.Image) => {
     const label = escapeHtml(text.trim() ? `Image: ${text}` : "Image");
     const safeHref = safeLink(href);
@@ -144,6 +171,10 @@ const renderMarkdown = (source: string): string => {
   }
 };
 
+// Keep CSS inside its style element even when it contains an HTML end tag.
+// The backslash is valid CSS escaping but no longer an HTML token.
+const styleText = (css: string): string => css.replace(/<\/style/giu, "<\\/style");
+
 const validateCustomCss = (customCss: string): string => {
   if (byteLength(customCss) > MARKDOWN_PDF_MAX_CUSTOM_CSS_BYTES) {
     throw new MarkdownPdfError("invalid_css", "Custom CSS exceeds the 32 KiB limit.", "css_too_large");
@@ -168,15 +199,15 @@ const validateCustomCss = (customCss: string): string => {
     }
   });
 
-  // Keep the CSS inside its style element even when input contains an HTML
-  // end tag. The backslash is valid CSS escaping but no longer an HTML token.
-  return root.toString().replace(/<\/style/giu, "<\\/style");
+  return styleText(root.toString());
 };
 
-export const buildMarkdownPdfHtml = (input: RenderMarkdownToPdfInput): string => {
-  if (typeof input.markdown !== "string" || !input.markdown.trim()) {
-    throw new MarkdownPdfError("bad_input", "Markdown must not be empty.", "markdown_empty");
-  }
+/**
+ * Wrap application-rendered HTML in the same print presets and validated
+ * custom CSS as Markdown PDFs, for documents whose Markdown dialect the
+ * application renders itself.
+ */
+export const buildPresetPdfHtml = (input: BuildPresetPdfHtmlInput): string => {
   const templateId = input.templateId;
   if (templateId !== undefined && !MARKDOWN_PDF_TEMPLATE_IDS.includes(templateId)) {
     throw new MarkdownPdfError("bad_input", "Unknown Markdown PDF template.", "unknown_template");
@@ -185,8 +216,8 @@ export const buildMarkdownPdfHtml = (input: RenderMarkdownToPdfInput): string =>
   const suppliedCustomCss = input.customCss?.trim() ?? "";
   const customCss = suppliedCustomCss ? validateCustomCss(input.customCss ?? "") : "";
   const presetCss = templateId ? TEMPLATE_CSS[templateId] : customCss ? "" : TEMPLATE_CSS.document;
-  const stylesheet = `${presetCss}${presetCss && customCss ? `\n/* Custom CSS overrides */\n` : ""}${customCss}`;
-  const content = renderMarkdown(input.markdown);
+  const baseCss = [presetCss, input.css ? styleText(input.css) : ""].filter(Boolean).join("\n");
+  const stylesheet = `${baseCss}${baseCss && customCss ? `\n/* Custom CSS overrides */\n` : ""}${customCss}`;
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -195,10 +226,17 @@ export const buildMarkdownPdfHtml = (input: RenderMarkdownToPdfInput): string =>
 <meta http-equiv="Content-Security-Policy" content="default-src 'none'; base-uri 'none'; connect-src 'none'; font-src 'none'; form-action 'none'; frame-src 'none'; img-src 'none'; media-src 'none'; object-src 'none'; script-src 'none'; style-src 'unsafe-inline'">
 <style>${stylesheet}</style>
 </head>
-<body><main class="markdown-document">${content}</main></body>
+<body><main class="markdown-document">${input.html}</main></body>
 </html>`;
 };
 
+export const buildMarkdownPdfHtml = (input: RenderMarkdownToPdfInput): string => {
+  if (typeof input.markdown !== "string" || !input.markdown.trim()) {
+    throw new MarkdownPdfError("bad_input", "Markdown must not be empty.", "markdown_empty");
+  }
+  return buildPresetPdfHtml({ html: renderMarkdown(input.markdown), templateId: input.templateId, customCss: input.customCss });
+};
+
 export const renderMarkdownToPdfWithConfig = (
   input: RenderMarkdownToPdfInput,
   config: GotenbergConfig,

package/src/services/settings/core-settings.ts

@@ -317,6 +317,8 @@ export const CORE_SETTINGS = {
     default: "",
     description: "Internal base URL of the Gotenberg service used for HTML-to-PDF rendering.",
     placeholder: "e.g. http://gotenberg:3000",
+    envFallback: () => env.GOTENBERG_URL,
+    envBootstrap: () => env.GOTENBERG_URL,
   },
   "gotenberg.username": {
     kind: "string",

package/src/ssr/LayoutPreferences.island.tsx

@@ -3,10 +3,8 @@ import type { CloudTheme } from "../shared/theme";
 import { createPreferenceController } from "./preference-controller";
 
 type LayoutPreferencesProps = {
-  class?: string;
   initialTheme: CloudTheme;
   position: DropdownPosition;
-  triggerClass?: string;
 };
 
 export default function LayoutPreferences(props: LayoutPreferencesProps) {
@@ -14,21 +12,8 @@ export default function LayoutPreferences(props: LayoutPreferencesProps) {
   const preferences = createPreferenceController(props.initialTheme, locale);
 
   return (
-    <Dropdown.Root
-      class={props.class}
-      items={preferences.items()}
-      label={preferences.messages().preferencesMenuLabel}
-      position={props.position}
-      width="14rem"
-    >
-      <Dropdown.Trigger
-        class={props.triggerClass}
-        iconOnly
-        label={preferences.messages().preferencesMenuLabel}
-        size="sm"
-        tooltip={false}
-        variant="secondary"
-      >
+    <Dropdown.Root items={preferences.items()} label={preferences.messages().preferencesMenuLabel} position={props.position} width="14rem">
+      <Dropdown.Trigger iconOnly label={preferences.messages().preferencesMenuLabel} size="sm" tooltip={false} variant="secondary">
         <i class="ti ti-adjustments-horizontal" aria-hidden="true" />
       </Dropdown.Trigger>
     </Dropdown.Root>

package/src/ssr/MinimalLayout.tsx

@@ -1,46 +1,70 @@
 import { LocaleProvider } from "@k2b/ui";
 import type { JSX } from "solid-js/jsx-runtime";
 import { getLocale } from "../server/locale";
+import { resolveAppPresentations } from "../shared/app-presentation";
 import { readThemeFromCookieHeader } from "../shared/theme";
-import LayoutPreferences from "./LayoutPreferences.island";
 import type { MinimalLayoutContext } from "./layout-context";
+import MinimalLayoutPreferences from "./MinimalLayoutPreferences.island";
+import { profilePreferencesMessages } from "./profile-preferences-messages";
 import TimezoneCookie from "./TimezoneCookie.island";
 
+/**
+ * @deprecated The language and theme settings always sit in the footer; a
+ * position is treated like `true`.
+ */
 export type MinimalLayoutPreferencePosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
 
 export type MinimalLayoutProps = {
   children: JSX.Element;
   c: MinimalLayoutContext;
-  /** Position the shared language/theme control, or disable it entirely. */
-  preferences?: MinimalLayoutPreferencePosition | false;
-};
-
-const menuPosition = (position: MinimalLayoutPreferencePosition) => {
-  if (position === "top-left") return "bottom-right" as const;
-  if (position === "top-right") return "bottom-left" as const;
-  if (position === "bottom-left") return "top-right" as const;
-  return "top-left" as const;
+  /**
+   * Render the footer with legal links and the language and theme settings
+   * (default), or `false` for embeds and fixed presentation surfaces.
+   */
+  preferences?: boolean | MinimalLayoutPreferencePosition;
 };
 
 export default function MinimalLayout(props: MinimalLayoutProps) {
   const cookie = props.c.req.raw.headers.get("Cookie") ?? "";
   const theme = readThemeFromCookieHeader(cookie);
   const locale = getLocale(props.c);
-  const preferences = props.preferences === undefined ? "bottom-right" : props.preferences;
   props.c.get("page").theme = theme;
 
+  if (props.preferences === false) {
+    return (
+      <LocaleProvider locale={locale}>
+        <TimezoneCookie />
+        {props.children}
+      </LocaleProvider>
+    );
+  }
+
+  const t = profilePreferencesMessages.resolve([locale]).t;
+  // Aggregate every running app's legal links like Layout (last wins on
+  // duplicate href). Unlike Layout, MinimalLayout does not require
+  // middleware.runtime(); without it the footer has no legal links.
+  const apps = resolveAppPresentations(props.c.get("runtime")?.apps ?? [], locale);
+  const legalLinks = [...new Map(apps.flatMap((app) => (app.legalLinks ?? []).map((link) => [link.href, link] as const))).values()];
+
   return (
     <LocaleProvider locale={locale}>
       <TimezoneCookie />
-      {props.children}
-      {preferences !== false && (
-        <LayoutPreferences
-          class={`minimal-layout-preferences minimal-layout-preferences--${preferences}`}
-          initialTheme={theme}
-          position={menuPosition(preferences)}
-          triggerClass="minimal-layout-preferences__trigger"
-        />
-      )}
+      <div class="minimal-layout">
+        {props.children}
+        <footer class="minimal-layout-footer">
+          {legalLinks.length > 0 && (
+            <nav class="minimal-layout-footer__links" aria-label={t.legalLinks}>
+              {legalLinks.map((link) => (
+                // A new tab keeps a started upload or a filled-in form on this page.
+                <a href={link.href} target="_blank" rel="noopener">
+                  {link.label}
+                </a>
+              ))}
+            </nav>
+          )}
+          <MinimalLayoutPreferences initialTheme={theme} />
+        </footer>
+      </div>
     </LocaleProvider>
   );
 }

package/src/ssr/MinimalLayoutPreferences.island.tsx

@@ -0,0 +1,48 @@
+import { Button, Dropdown, useLocale } from "@k2b/ui";
+import { type ProfilePreferenceLocale, profilePreferenceLocale, setLocalePreference } from "../browser/locale-preference";
+import { canonicalLocale } from "../shared/locale";
+import type { CloudTheme } from "../shared/theme";
+import { createPreferenceController } from "./preference-controller";
+
+/**
+ * Labeled language and theme controls for the MinimalLayout footer. The
+ * language trigger names the current language; the theme button names the
+ * mode it switches to, like every other Cloud preference menu.
+ */
+export default function MinimalLayoutPreferences(props: { initialTheme: CloudTheme }) {
+  const locale = useLocale();
+  const preferences = createPreferenceController(props.initialTheme, locale);
+  const t = preferences.messages;
+  const language = () => profilePreferenceLocale(locale());
+  const languageName = () => (language() === "de" ? t().switchToGerman : t().switchToEnglish);
+  // Keep a regional locale such as en-GB when its language is chosen again,
+  // but let a visitor on an unsupported locale such as fr-FR, who reads the
+  // English fallback, still choose English explicitly.
+  const choose = (next: ProfilePreferenceLocale) => {
+    if (canonicalLocale(locale())?.split("-")[0] !== next) setLocalePreference(next);
+  };
+
+  return (
+    <div class="minimal-layout-footer__preferences">
+      <Dropdown.Root
+        label={t().language}
+        position="top-right"
+        width="10rem"
+        items={[
+          { label: t().switchToGerman, choice: "radio", checked: () => language() === "de", action: () => choose("de") },
+          { label: t().switchToEnglish, choice: "radio", checked: () => language() === "en", action: () => choose("en") },
+        ]}
+      >
+        <Dropdown.Trigger label={`${t().language}: ${languageName()}`} size="sm" tooltip={false} variant="ghost">
+          <i class="ti ti-language" aria-hidden="true" />
+          {languageName()}
+          <i class="ti ti-chevron-down" aria-hidden="true" />
+        </Dropdown.Trigger>
+      </Dropdown.Root>
+      <Button onClick={preferences.toggleTheme} size="sm" variant="ghost">
+        <i class={preferences.theme() === "light" ? "ti ti-moon" : "ti ti-sun-high"} aria-hidden="true" />
+        {preferences.themeLabel()}
+      </Button>
+    </div>
+  );
+}

package/src/ssr/PageError.tsx

@@ -17,7 +17,7 @@ export const renderPageError = (c: Context, status: PageErrorStatus, options: Pa
   return () =>
     options.layout === "minimal" ? (
       <MinimalLayout c={c}>
-        <main class="min-h-screen bg-[var(--ui-canvas)] p-[var(--ui-space-shell)]">
+        <main class="flex-1 bg-[var(--ui-canvas)] p-[var(--ui-space-shell)]">
           <NotFoundState code={String(status)} title={title} description={description} action={action} />
         </main>
       </MinimalLayout>

package/src/ssr/profile-preferences-messages.ts

@@ -6,6 +6,8 @@ export const profilePreferencesMessages = i18n.define({
     en: {
       menuLabel: "Profile and preferences",
       preferencesMenuLabel: "Appearance and language",
+      language: "Language",
+      legalLinks: "Legal",
       profileSettings: "Profile settings",
       signOut: "Sign out",
       signOutFailed: "Sign out failed. Please try again.",
@@ -17,6 +19,8 @@ export const profilePreferencesMessages = i18n.define({
     de: {
       menuLabel: "Profil und Einstellungen",
       preferencesMenuLabel: "Darstellung und Sprache",
+      language: "Sprache",
+      legalLinks: "Rechtliches",
       profileSettings: "Profileinstellungen",
       signOut: "Abmelden",
       signOutFailed: "Abmelden fehlgeschlagen. Bitte versuche es erneut.",

package/src/styles/utilities-navigation.css

@@ -903,36 +903,85 @@
   }
 }
 
-/* MinimalLayout owns no page geometry. Its optional preference trigger is the
-   only positioned element and respects device safe areas in every corner. */
-.minimal-layout-preferences {
-  position: fixed;
-  z-index: 50;
+/* MinimalLayout stacks the page content and its footer in a column at least
+   one viewport tall, so the footer ends a short page and follows a long one.
+   Content that should fill the remaining height grows with flex-1. */
+.minimal-layout {
+  display: flex;
+  min-height: 100vh;
+  min-height: 100dvh;
+  flex-direction: column;
+}
+
+.minimal-layout-footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 0.25rem 1rem;
+  margin-top: auto;
+  padding: 0.75rem max(1rem, env(safe-area-inset-right)) max(0.75rem, env(safe-area-inset-bottom))
+    max(1rem, env(safe-area-inset-left));
+  color: var(--k2b-text-muted);
+  font-size: 0.75rem;
+  line-height: 1rem;
+}
+
+.minimal-layout-footer__links,
+.minimal-layout-footer__preferences {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+}
+
+.minimal-layout-footer__links {
+  column-gap: 1rem;
 }
 
-.minimal-layout-preferences--top-left {
-  top: max(0.75rem, env(safe-area-inset-top));
-  left: max(0.75rem, env(safe-area-inset-left));
+.minimal-layout-footer__preferences {
+  gap: 0.25rem;
 }
 
-.minimal-layout-preferences--top-right {
-  top: max(0.75rem, env(safe-area-inset-top));
-  right: max(0.75rem, env(safe-area-inset-right));
+.minimal-layout-footer__links a {
+  display: inline-flex;
+  min-height: 1.75rem;
+  align-items: center;
+  border-radius: var(--k2b-radius-control);
+  color: inherit;
+  transition: color 150ms ease-out;
+}
+
+.minimal-layout-footer__links a:hover {
+  color: var(--k2b-text);
+}
+
+.minimal-layout-footer__links a:focus-visible {
+  outline: 2px solid var(--k2b-focus-ring);
+  outline-offset: 2px;
 }
 
-.minimal-layout-preferences--bottom-left {
-  bottom: max(0.75rem, env(safe-area-inset-bottom));
-  left: max(0.75rem, env(safe-area-inset-left));
+.k2b-ui .minimal-layout-footer .k2b-button[data-size] {
+  color: inherit;
+  font-size: inherit;
+}
+
+.k2b-ui .minimal-layout-footer .k2b-button[data-size]:hover {
+  color: var(--k2b-text);
 }
 
-.minimal-layout-preferences--bottom-right {
-  right: max(0.75rem, env(safe-area-inset-right));
-  bottom: max(0.75rem, env(safe-area-inset-bottom));
+/* Finger-sized footer targets on touch screens. */
+@media (any-pointer: coarse) {
+  .minimal-layout-footer__links a,
+  .k2b-ui .minimal-layout-footer .k2b-button[data-size] {
+    min-height: 2.75rem;
+  }
 }
 
-.minimal-layout-preferences__trigger {
-  box-shadow: var(--ui-shadow-float);
-  backdrop-filter: blur(0.5rem);
+@media (prefers-reduced-motion: reduce) {
+  .minimal-layout-footer__links a {
+    transition: none;
+  }
 }
 
 /* Workspace navigation chrome and resource identity. */