@k2b/cloud 0.11.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -31,6 +31,8 @@
     "./browser": "./src/server/api-client.ts",
     "./browser/app-approval": "./src/browser/app-approval.ts",
     "./browser/live": "./src/browser/live-websocket.ts",
+    "./browser/mermaid": "./src/browser/mermaid.ts",
+    "./browser/reload": "./src/browser/reload.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
     "./browser/commands": "./src/browser/commands.ts",
@@ -84,8 +86,7 @@
     "./styles/global.css": "./src/styles/global.css"
   },
   "scripts": {
-    "test": "bun test --isolate --path-ignore-patterns '**/*.behavior.test.tsx' --path-ignore-patterns '**/*.dom.test.tsx' && bun run test:dom",
-    "test:dom": "bun test --isolate --conditions=browser --preload ../ui/test/solid-dom-preload.ts behavior.test.tsx dom.test.tsx",
+    "test": "bun test --isolate --path-ignore-patterns '**/*.behavior.test.*'",
     "typecheck": "tsc -p tsconfig.json --noEmit --pretty false"
   },
   "dependencies": {
@@ -98,8 +99,8 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.5.1",
-    "@k2b/stdlib": "0.25.0",
+    "@k2b/ui": "0.6.0",
+    "@k2b/stdlib": "0.26.0",
     "@k2b/sync": "6.5.0",
     "@nats-io/transport-node": "3.4.0",
     "@modelcontextprotocol/sdk": "1.30.0",
@@ -109,7 +110,7 @@
     "katex": "0.18.7",
     "liquidjs": "10.29.0",
     "marked": "17.0.6",
-    "mermaid": "11.16.0",
+    "mermaid": "12.0.0",
     "nodemailer": "10.0.10",
     "postcss": "8.5.28",
     "reflect-metadata": "0.2.2",

package/src/access/PermissionEditor.tsx

@@ -3,6 +3,7 @@ import { IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from
 import { createSignal, For, Show } from "solid-js";
 import { CloudAvatar } from "../account/Avatar";
 import type { AccessEntry, PermissionLevel, Principal } from "../contracts/shared";
+import { groupDisplayName } from "../shared/account-display";
 import { accessMessages } from "./messages";
 import PrincipalPicker from "./PrincipalPicker";
 
@@ -112,8 +113,8 @@ const resolveEntryDisplay = (
   return defaults[permission] ?? defaults.none;
 };
 
-const getEntryDisplayName = (entry: AccessEntry, t: ReturnType<typeof accessMessages.resolve>["t"]): string => {
-  if (entry.displayName) return entry.displayName;
+const getEntryDisplayName = (entry: AccessEntry, t: ReturnType<typeof accessMessages.resolve>["t"], locale: string): string => {
+  if (entry.displayName) return entry.principal.type === "group" ? groupDisplayName(entry.displayName, locale) : entry.displayName;
   if (entry.principal.type === "authenticated") return t.allUsers;
   if (entry.principal.type === "public") return t.public;
   if (entry.principal.type === "user") return entry.principal.userId;
@@ -184,7 +185,7 @@ export default function PermissionEditor(props: PermissionEditorProps) {
 
   const revokeMut = mutation.create<string | null, AccessEntry>({
     mutation: async (entry) => {
-      const displayName = getEntryDisplayName(entry, t());
+      const displayName = getEntryDisplayName(entry, t(), locale());
       const confirmed = await prompts.confirm(t().removeAccessConfirm({ name: displayName }), {
         title: t().removeAccess,
         variant: "danger",
@@ -263,7 +264,7 @@ function AccessEntryRow(props: {
 }) {
   const locale = useLocale();
   const t = () => accessMessages.resolve([locale()]).t;
-  const displayName = () => getEntryDisplayName(props.entry, t());
+  const displayName = () => getEntryDisplayName(props.entry, t(), locale());
   const display = () => resolveEntryDisplay(props.entry.permission, props.allowed, t());
   const isInteractive = () =>
     props.canEdit && !props.disabled && !props.singlePicker && props.allowed.some((option) => option.level === props.entry.permission);

package/src/access/PrincipalPicker.tsx

@@ -1,5 +1,6 @@
 import { Combobox, type ComboboxOption, useLocale } from "@k2b/ui";
 import type { Principal } from "../contracts/shared";
+import { groupDisplayName } from "../shared/account-display";
 import { accessMessages } from "./messages";
 
 export const principalKey = (p: Principal) =>
@@ -66,7 +67,7 @@ export default function PrincipalPicker(props: {
         else if (e.kind === "group")
           entries.push({
             principal: { type: "group", groupId: e.group.id },
-            label: e.group.name,
+            label: groupDisplayName(e.group.name, locale()),
             icon: "ti ti-users-group",
             description: e.group.description ?? undefined,
           });

package/src/account/EntitySearch.tsx

@@ -1,7 +1,8 @@
 import { timed } from "@k2b/stdlib/solid";
-import { Button, ScrollArea, TextInput } from "@k2b/ui";
+import { Button, ScrollArea, TextInput, useLocale } from "@k2b/ui";
 import type { JSX } from "solid-js";
 import { createSignal, For, Show } from "solid-js";
+import { groupDisplayName } from "../shared/account-display";
 import { CloudAvatar } from "./Avatar";
 
 /**
@@ -108,6 +109,7 @@ type ApiServiceAccount = {
 };
 
 const EntitySearch = (props: EntitySearchProps) => {
+  const locale = useLocale();
   const [search, setSearch] = createSignal("");
   const [users, setUsers] = createSignal<ApiUser[]>([]);
   const [groups, setGroups] = createSignal<ApiGroup[]>([]);
@@ -270,7 +272,7 @@ const EntitySearch = (props: EntitySearchProps) => {
               {(group) => (
                 <ResultRow
                   icon="ti-users-group"
-                  title={group.name}
+                  title={groupDisplayName(group.name, locale())}
                   subtitle={group.description ?? undefined}
                   disabled={props.disabled}
                   onSelect={() =>
@@ -339,7 +341,7 @@ const ResultRow = (props: {
   disabled?: boolean;
   onSelect: () => void;
 }) => (
-  <Button onClick={props.onSelect} disabled={props.disabled} variant="ghost" class="w-full justify-start gap-3 text-left">
+  <Button onClick={props.onSelect} disabled={props.disabled} variant="ghost" align="start" class="w-full">
     <Show
       when={props.avatar}
       fallback={

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": 51,
+  "version": 52,
   "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, 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\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,\ncategory S VAT, units C62/HUR/DAY/KGM. It does not support UBL, XRechnung,\ndiscounts, prepayments or exemptions. 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; vatId: string;\n  address: {line1: string; city: string; postalCode: string; countryCode: string};\n};\ntype InvoiceLine = {\n  id: string; name: string; description?: string;\n  quantity: string; unitPrice: string; unitCode: \"C62\" | \"HUR\" | \"DAY\" | \"KGM\";\n  taxRate: string; netAmount?: string;\n};\ntype InvoiceTotals = {\n  netAmount: string; taxAmount: string; grossAmount: string; dueAmount: string;\n  taxGroups: {taxRate: string; 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; buyer: Party; 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 greater than 0 and 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- `calculate` rounds each line half up to cents, then VAT per 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, account or business reference merely to\nsatisfy input validation.\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 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"
     },
     {
       "path": "references/examples.md",

package/src/ai/store.ts

@@ -1095,10 +1095,10 @@ export const aiConversations: AiConversationService = {
     const refs = input.refs ?? [];
     const rows = await withConversationSearchBackend(query, async (backend) => {
       const order = query
-        ? sql`${conversationSearchRank(backend, query)} DESC, conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC`
+        ? sql`${conversationSearchRank(backend, query)} DESC, conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC, conversation.id DESC`
         : input.done === true
           ? sql`conversation.last_used_at DESC, conversation.id DESC`
-          : sql`conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC`;
+          : sql`conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC, conversation.id DESC`;
       return sql<ConversationRow[]>`
       SELECT
         conversation.*,
@@ -1198,10 +1198,10 @@ export const aiConversations: AiConversationService = {
     const { page, perPage, offset } = sanitizePagination(input);
     const rows = await withConversationSearchBackend(query, async (backend) => {
       const order = query
-        ? sql`${conversationSearchRank(backend, query)} DESC, conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC`
+        ? sql`${conversationSearchRank(backend, query)} DESC, conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC, conversation.id DESC`
         : input.done === true
           ? sql`conversation.last_used_at DESC, conversation.id DESC`
-          : sql`conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC`;
+          : sql`conversation.pinned_at DESC NULLS LAST, conversation.updated_at DESC, conversation.created_at DESC, conversation.id DESC`;
       return sql<ConversationRow[]>`
       SELECT
         conversation.*,

package/src/api/accounts-entities.ts

@@ -41,6 +41,7 @@ const QuerySchema = z
     parent_group_id: z.uuid().optional(),
     managed_by_user_id: z.uuid().optional(),
     recursive: z.enum(["true", "false"]).optional(),
+    include_personal: z.enum(["true", "false"]).optional(),
   })
   .refine(
     (value) => {
@@ -98,7 +99,7 @@ export const createAccountsEntitiesRoutes = (dependencies: AccountsEntitiesRoute
       tags: ["Accounts"],
       summary: "List mixed users and groups",
       description:
-        "List visible users and groups with SQL-backed filtering and pagination. Guest accounts see only themselves and their effective groups; relation filters require a full user account.",
+        "List visible users and groups with SQL-backed filtering and pagination. Guest accounts see only themselves and their effective groups; relation filters require a full user account. Personal Linux groups (a user's private primary group, flagged with `personalOwner`) are left out unless `include_personal=true`; exact `group_ids` lookups and relation filters always return them.",
       ...requiresAuth,
       responses: {
         200: jsonResponse(EntitiesListResponseSchema, "Paginated mixed entity list"),
@@ -159,6 +160,7 @@ export const createAccountsEntitiesRoutes = (dependencies: AccountsEntitiesRoute
         parentGroupId: query.parent_group_id,
         managedByUserId: query.managed_by_user_id,
         recursive: query.recursive === "true",
+        includePersonal: query.include_personal === "true",
       });
 
       return respond(c, {

package/src/api/app-approval.ts

@@ -113,7 +113,10 @@ export const createAppApprovalRoutes = (service: Service = appApproval) => {
     )
     .post("/login/status", v("json", AppLoginReferenceSchema), async (c) => {
       const input = c.req.valid("json");
-      return c.json(await service.browserStatus(input.requestId, input.browserSecret));
+      // Hold a pending request for one poll interval: the browser learns a decision at once,
+      // keeps its request cadence, and stays below Bun's 10-second idle timeout.
+      const hold = { ms: APP_APPROVAL_LIMITS.pollSeconds * 1000, signal: c.req.raw.signal };
+      return c.json(await service.browserStatus(input.requestId, input.browserSecret, hold));
     })
     .post(
       "/login/complete",

package/src/browser/live-websocket.ts

@@ -52,6 +52,16 @@ const DEFAULT_RECONNECT = {
   jitterMs: 250,
 } as const;
 
+/**
+ * Deadline for one opening handshake. The handshake is a single HTTP upgrade
+ * round trip (the gateway accepts it before reaching the application), so a
+ * healthy attempt finishes far sooner. Browsers can otherwise leave a socket in
+ * `CONNECTING` indefinitely after sleep or a network change. Matching the
+ * longest default reconnect delay means a stalled attempt never blocks recovery
+ * for longer than an ordinary retry.
+ */
+const CONNECT_TIMEOUT_MS = DEFAULT_RECONNECT.maxDelayMs;
+
 const defaultCloseError = ({ code, reason }: LiveWebSocketClose): LiveWebSocketError | null => {
   if (code === 1008) return { code: reason || "access_denied", message: "Live access changed or expired." };
   if (code === 1011) return { code: reason || "internal_error", message: "Live updates failed." };
@@ -72,7 +82,8 @@ const socketUrl = (raw: string): string => {
  *
  * The app owns its wire protocol, validation, permissions, and domain updates.
  * This helper owns only browser transport lifecycle: one socket, visibility,
- * reconnect backoff, applied-cursor resume, terminal closes, and disposal.
+ * reconnect backoff, connection deadlines, recovery when the tab or network
+ * returns, applied-cursor resume, terminal closes, and disposal.
  */
 export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMessage>): LiveWebSocket => {
   const activity = options.activity ?? "visible";
@@ -81,6 +92,8 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
 
   let socket: WebSocket | null = null;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let connectTimer: ReturnType<typeof setTimeout> | null = null;
+  let connectStartedAt = 0;
   let reconnectAttempt = 0;
   let lastAppliedCursor = options.initialCursor ?? null;
   let started = false;
@@ -120,9 +133,15 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
     }
   };
 
+  const clearConnectDeadline = () => {
+    if (connectTimer !== null) clearTimeout(connectTimer);
+    connectTimer = null;
+  };
+
   const closeSocket = (code = 1000, reason = "") => {
     const current = socket;
     socket = null;
+    clearConnectDeadline();
     if (!current || current.readyState > WebSocket.OPEN) return;
     try {
       current.close(code, reason);
@@ -135,6 +154,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
     if (terminated) return;
     terminated = true;
     clearReconnect();
+    detachRecovery();
     closeSocket(close.code, close.reason);
     setStatus("closed");
     if (!fatalSent) {
@@ -165,6 +185,13 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
     }, delay);
   };
 
+  /** Gives up on an attempt that is still connecting and schedules a retry. */
+  const abandonAttempt = (attempt: WebSocket) => {
+    if (socket !== attempt) return;
+    closeSocket();
+    scheduleReconnect();
+  };
+
   const openSocket = () => {
     if (disposed || terminated || !started || socket) return;
     if (!browserAvailable()) {
@@ -174,7 +201,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
     if (!isActive()) return;
 
     let next: WebSocket;
-    setStatus(reconnectAttempt > 0 ? "reconnecting" : "connecting");
+    setStatus(reconnectAttempt > 0 || status === "reconnecting" ? "reconnecting" : "connecting");
     try {
       next = new WebSocket(socketUrl(typeof options.url === "function" ? options.url() : options.url));
     } catch (error) {
@@ -182,9 +209,15 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       return;
     }
     socket = next;
+    connectStartedAt = Date.now();
+    connectTimer = setTimeout(() => {
+      connectTimer = null;
+      if (next.readyState === WebSocket.CONNECTING) abandonAttempt(next);
+    }, CONNECT_TIMEOUT_MS);
 
     next.onopen = () => {
       if (socket !== next || disposed || terminated) return;
+      clearConnectDeadline();
       try {
         if (!send(options.subscribe(lastAppliedCursor))) throw new Error("Live WebSocket subscription could not be sent");
         setStatus("open");
@@ -213,6 +246,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
     next.onclose = (event) => {
       if (socket !== next) return;
       socket = null;
+      clearConnectDeadline();
       if (disposed || terminated) return;
       const closeError = classifyClose({ code: event.code, reason: event.reason.trim() });
       if (closeError) fatal(closeError, { code: event.code, reason: event.reason });
@@ -224,22 +258,55 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
         next.close();
       } catch {
         if (socket === next) {
-          socket = null;
+          closeSocket();
           scheduleReconnect();
         }
       }
     };
   };
 
-  const syncVisibility = () => {
-    if (isActive()) openSocket();
-    else {
+  /**
+   * Reconnects now when the tab or network returns. Open and closing sockets
+   * are left alone; a closing socket's close event still decides between retry
+   * and a terminal error. A handshake within its deadline is kept unless the
+   * network just returned, because it began on the network that was gone. A
+   * stalled handshake or a pending backoff is replaced by an immediate attempt
+   * whose backoff starts over.
+   */
+  const recover = (event: Event) => {
+    if (disposed || terminated || !started || !isActive()) return;
+    if (socket) {
+      if (socket.readyState !== WebSocket.CONNECTING) return;
+      if (event.type !== "online" && Date.now() - connectStartedAt < CONNECT_TIMEOUT_MS) return;
+      closeSocket();
+    }
+    clearReconnect();
+    reconnectAttempt = 0;
+    openSocket();
+  };
+
+  const syncVisibility = (event: Event) => {
+    if (isActive()) recover(event);
+    else if (activity === "visible") {
       clearReconnect();
       closeSocket(1000, "inactive");
       setStatus("paused");
     }
   };
 
+  const attachRecovery = () => {
+    document.addEventListener("visibilitychange", syncVisibility);
+    window.addEventListener("online", recover);
+    window.addEventListener("focus", recover);
+  };
+
+  const detachRecovery = () => {
+    if (!started || !browserAvailable()) return;
+    document.removeEventListener("visibilitychange", syncVisibility);
+    window.removeEventListener("online", recover);
+    window.removeEventListener("focus", recover);
+  };
+
   return {
     connect: () => {
       if (started || disposed || terminated) return;
@@ -248,7 +315,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
         fatal({ code: "unsupported", message: "Live WebSockets are not available in this browser" });
         return;
       }
-      if (activity === "visible") document.addEventListener("visibilitychange", syncVisibility);
+      attachRecovery();
       openSocket();
     },
     markApplied,
@@ -258,9 +325,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       if (disposed) return;
       disposed = true;
       clearReconnect();
-      if (activity === "visible" && typeof document !== "undefined") {
-        document.removeEventListener("visibilitychange", syncVisibility);
-      }
+      detachRecovery();
       closeSocket();
       setStatus("closed");
     },

package/src/browser/mermaid.ts

@@ -0,0 +1,202 @@
+import type { MermaidConfig } from "mermaid";
+
+/** Series colors shared by pie slices and mindmap branches. */
+const lightSeries = [
+  "#dbeafe",
+  "#d1fae5",
+  "#fef3c7",
+  "#ede9fe",
+  "#ffe4e6",
+  "#cffafe",
+  "#ecfccb",
+  "#ffedd4",
+  "#e0f2fe",
+  "#ccfbf1",
+  "#fae8ff",
+  "#fef9c3",
+];
+const darkSeries = [
+  "#1e3a8a",
+  "#065f46",
+  "#78350f",
+  "#4c1d95",
+  "#881337",
+  "#155e75",
+  "#3f6212",
+  "#7c2d12",
+  "#075985",
+  "#115e59",
+  "#86198f",
+  "#713f12",
+];
+
+// Mermaid derives colors from hex values, so these mirror the Cloud tokens
+// (zinc ink, --ui-surface*, --ui-border*) instead of reading CSS variables.
+const light = {
+  darkMode: false,
+  background: "#ffffff",
+  textColor: "#27272a",
+  titleColor: "#18181b",
+  lineColor: "#71717a",
+  primaryColor: "#f4f4f5",
+  primaryTextColor: "#18181b",
+  primaryBorderColor: "#a1a1aa",
+  secondaryColor: "#eff6ff",
+  secondaryTextColor: "#18181b",
+  secondaryBorderColor: "#93c5fd",
+  tertiaryColor: "#fafafa",
+  tertiaryTextColor: "#18181b",
+  tertiaryBorderColor: "#d4d4d8",
+  mainBkg: "#f4f4f5",
+  nodeBorder: "#a1a1aa",
+  clusterBkg: "#fafafa",
+  clusterBorder: "#d4d4d8",
+  edgeLabelBackground: "#ffffff",
+  noteBkgColor: "#fefce8",
+  noteBorderColor: "#eab308",
+  noteTextColor: "#27272a",
+  actorBkg: "#f4f4f5",
+  actorBorder: "#a1a1aa",
+  actorTextColor: "#18181b",
+  signalColor: "#52525b",
+  signalTextColor: "#27272a",
+  labelBoxBkgColor: "#f4f4f5",
+  labelBoxBorderColor: "#a1a1aa",
+  activationBkgColor: "#e4e4e7",
+  activationBorderColor: "#a1a1aa",
+  attributeBackgroundColorOdd: "#ffffff",
+  attributeBackgroundColorEven: "#fafafa",
+  sectionBkgColor: "#f4f4f5",
+  altSectionBkgColor: "#ffffff",
+  sectionBkgColor2: "#fafafa",
+  gridColor: "#e4e4e7",
+  taskBkgColor: "#dbeafe",
+  taskBorderColor: "#3b82f6",
+  taskTextColor: "#18181b",
+  taskTextLightColor: "#18181b",
+  taskTextDarkColor: "#18181b",
+  taskTextOutsideColor: "#27272a",
+  activeTaskBkgColor: "#bfdbfe",
+  activeTaskBorderColor: "#2563eb",
+  doneTaskBkgColor: "#e4e4e7",
+  doneTaskBorderColor: "#a1a1aa",
+  critBkgColor: "#ffe4e6",
+  critBorderColor: "#e11d48",
+  todayLineColor: "#e11d48",
+  pieStrokeColor: "#ffffff",
+  pieOuterStrokeColor: "#d4d4d8",
+  pieSectionTextColor: "#18181b",
+  pieTitleTextColor: "#18181b",
+  pieLegendTextColor: "#27272a",
+  series: lightSeries,
+  seriesText: "#18181b",
+};
+
+const dark: typeof light = {
+  darkMode: true,
+  background: "#11151b",
+  textColor: "#e4e4e7",
+  titleColor: "#f4f4f5",
+  lineColor: "#a1a1aa",
+  primaryColor: "#20242a",
+  primaryTextColor: "#f4f4f5",
+  primaryBorderColor: "#5b6573",
+  secondaryColor: "#172554",
+  secondaryTextColor: "#f4f4f5",
+  secondaryBorderColor: "#3b82f6",
+  tertiaryColor: "#181d24",
+  tertiaryTextColor: "#f4f4f5",
+  tertiaryBorderColor: "#3a4552",
+  mainBkg: "#20242a",
+  nodeBorder: "#5b6573",
+  clusterBkg: "#181d24",
+  clusterBorder: "#3a4552",
+  edgeLabelBackground: "#11151b",
+  noteBkgColor: "#422006",
+  noteBorderColor: "#a16207",
+  noteTextColor: "#fef9c3",
+  actorBkg: "#20242a",
+  actorBorder: "#5b6573",
+  actorTextColor: "#f4f4f5",
+  signalColor: "#a1a1aa",
+  signalTextColor: "#e4e4e7",
+  labelBoxBkgColor: "#20242a",
+  labelBoxBorderColor: "#5b6573",
+  activationBkgColor: "#29313a",
+  activationBorderColor: "#5b6573",
+  attributeBackgroundColorOdd: "#181d24",
+  attributeBackgroundColorEven: "#20242a",
+  sectionBkgColor: "#181d24",
+  altSectionBkgColor: "#11151b",
+  sectionBkgColor2: "#1c2129",
+  gridColor: "#29313a",
+  taskBkgColor: "#1e3a8a",
+  taskBorderColor: "#60a5fa",
+  taskTextColor: "#f4f4f5",
+  taskTextLightColor: "#f4f4f5",
+  taskTextDarkColor: "#f4f4f5",
+  taskTextOutsideColor: "#e4e4e7",
+  activeTaskBkgColor: "#1e40af",
+  activeTaskBorderColor: "#93c5fd",
+  doneTaskBkgColor: "#3f3f46",
+  doneTaskBorderColor: "#71717a",
+  critBkgColor: "#881337",
+  critBorderColor: "#fb7185",
+  todayLineColor: "#fb7185",
+  pieStrokeColor: "#11151b",
+  pieOuterStrokeColor: "#3a4552",
+  pieSectionTextColor: "#f4f4f5",
+  pieTitleTextColor: "#f4f4f5",
+  pieLegendTextColor: "#e4e4e7",
+  series: darkSeries,
+  seriesText: "#f4f4f5",
+};
+
+/**
+ * Mermaid configuration that follows Cloud's light or dark tokens.
+ *
+ * Diagrams keep Mermaid 11's flat look and layouts; an author may still
+ * choose `layout: elk` in front matter, which loads ELK on demand. Author
+ * directives cannot change security, theme, or CSS.
+ */
+export function mermaidConfig(options: { dark: boolean }): MermaidConfig {
+  const { series, seriesText, ...palette } = options.dark ? dark : light;
+  const themeVariables: Record<string, string | boolean> = {
+    ...palette,
+    fontFamily: '"IBM Plex Sans", ui-sans-serif, system-ui, sans-serif',
+  };
+  series.forEach((color, index) => {
+    themeVariables[`pie${index + 1}`] = color;
+    themeVariables[`cScale${index}`] = color;
+    themeVariables[`cScaleLabel${index}`] = seriesText;
+  });
+  return {
+    startOnLoad: false,
+    securityLevel: "strict",
+    suppressErrorRendering: true,
+    theme: "base",
+    look: "classic",
+    // Mermaid 12 lays these types out with ELK by default. Keep dagre so ELK
+    // loads only for diagrams whose front matter asks for `layout: elk`.
+    flowchart: { layout: "dagre" },
+    class: { layout: "dagre" },
+    state: { layout: "dagre" },
+    er: { layout: "dagre" },
+    requirement: { layout: "dagre" },
+    themeVariables,
+    secure: [
+      "secure",
+      "securityLevel",
+      "startOnLoad",
+      "maxTextSize",
+      "maxEdges",
+      "suppressErrorRendering",
+      "htmlLabels",
+      "themeCSS",
+      "themeVariables",
+      "theme",
+      "fontFamily",
+      "altFontFamily",
+    ],
+  };
+}