@k2b/cloud 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -99,7 +99,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.8.0",
+    "@k2b/ui": "0.9.0",
     "@k2b/stdlib": "0.26.0",
     "@k2b/sync": "6.5.0",
     "@nats-io/transport-node": "3.4.0",

package/src/_internal/define-app.ts

@@ -341,6 +341,9 @@ export const defineApp = <
     basePath: opts.basePath,
     template: ({ body, scripts, title, description, theme, lang, performanceRoute }) => {
       const themeFixed = theme !== undefined;
+      // The inline layer statement fixes the cascade order before any
+      // stylesheet declares a layer. Tailwind's `properties` layer resets
+      // `--tw-*` in browsers without `@property` and must stay lowest.
       return `<!DOCTYPE html>
 <html lang="${normalizeLocale(lang)}" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}>
   <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -350,7 +353,7 @@ export const defineApp = <
     <meta name="theme-color" content="#09090b">
     <meta name="mobile-web-app-capable" content="yes">
     <link rel="icon" href="${appFaviconHref(opts.id, v)}">
-    <style data-cloud-css-layers>@layer theme, base, components, utilities;</style>
+    <style data-cloud-css-layers>@layer properties, theme, base, components, utilities;</style>
     <link rel="preload" href="/public/tabler-icons.woff2" as="font" type="font/woff2" crossorigin>
     <link rel="stylesheet" href="/public/fonts.css?v=${v}">
     <link rel="stylesheet" href="/public/tabler-icons.css?v=${v}">

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": 54,
+  "version": 55,
   "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.",
@@ -88,7 +88,7 @@ export const ASSISTANT_CODE_MODE_SKILL = {
     },
     {
       "path": "references/pdf.md",
-      "content": "# Generate PDFs\n\n`pdf.render`, `pdf.attach` and `pdf.facturX` are asynchronous and return a PDF\n`Blob`. They use the instance's configured PDF service. `pdf.open` is\nthe local text reader described in [Documents](documents.md).\n\n## Choose the path\n\nA document written in the chat needs no code. Use the chat tool\n`markdown_to_pdf` for text-first documents; it applies A4 presets and custom CSS\nand turns images into links. Use `html_to_pdf` for a chat `.html` file whose\nlayout needs HTML and CSS, images, or fonts. It takes optional CSS (file or\ninline), header and footer files, chat files as named assets, and the `page`\noptions below, then writes a sibling `.pdf` for `present`. Use `pdf.render` when\ncode builds the document from data, for Factur-X or attachments, and in Studio\nApps.\n\n## HTML and CSS\n\n```js\nconst document = await pdf.render({\n  html: `<!doctype html><html><head><style>\n    body { font-family: sans-serif; }\n    h1 { color: #087f70; }\n    tr { break-inside: avoid; }\n  </style></head><body><h1>Stock report</h1><img src=\"logo.png\"></body></html>`,\n  assets: [{ name: \"logo.png\", data: logoFile }],\n  page: { format: \"A4\", landscape: false, margin: { top: 15, right: 15, bottom: 15, left: 15 } },\n  tagged: true,\n});\nawait files.save(document, \"stock-report.pdf\");\n```\n\n`html` is required. `assets` defaults to an empty array and accepts named `Blob`\nvalues for local images, fonts and CSS. Use plain filenames, no directories;\nreference the exact filename from HTML or CSS. Duplicate names and the reserved\nnames `index.html`, `header.html`, `footer.html`, `factur-x.xml` fail.\n`headerHtml` and `footerHtml` are optional independent HTML strings with their own\nCSS. They load no assets; use `data:` URLs for images there. Page markers such as\n`<span class=\"pageNumber\"></span>` work in those templates, and the page margin\nmust leave room for them. Background colors are printed.\n\n`page.format` defaults to `A4`; alternatives are `A3`, `A5`, `Letter`, and `Legal`.\n`landscape` defaults to false. Each margin is a nonnegative millimeter number,\ndefaulting to 15. Use `page` for paper dimensions and margins; avoid conflicting\nCSS `@page` rules. `tagged` defaults to true, which requests a tagged PDF but does\nnot certify accessibility.\n\nStudio styles are not inherited. Scripts, redirects, frames and outbound\nresources are blocked. MathML (`math`) and the SVG elements `foreignObject` and\n`desc` are removed; write formulas and labels as HTML and CSS or as SVG text.\nSupply local assets or data URLs; this is not a URL-to-PDF browser or a\nJavaScript rendering environment.\n\n## Attach files\n\n```js\nconst result = await pdf.attach({\n  document,\n  attachments: [{\n    name: \"details.xml\",\n    data: new Blob([xml], { type: \"application/xml\" }),\n    relationship: \"Data\",\n  }],\n});\nawait files.shared.write(\"reports/with-details.pdf\", result);\n```\n\nThe source PDF and attachments are ordinary `Blob`s. Their origin does not\nmatter: explicit picker selections, authorized chat inputs, or app storage use\nthe same API. `relationship` defaults to `Unspecified`; alternatives are\n`Source`, `Data`, `Alternative`, and `Supplement`. MIME type comes from the Blob\nand defaults to `application/octet-stream` if empty. Provide at least one attachment. Names within the request\nmust be unique. All asset/attachment names are 1–180 characters, with no slash,\nbackslash or control characters, and cannot be `.` or `..`. Embedding an XML file alone does not create a compliant invoice.\n\n## Factur-X / ZUGFeRD\n\n```js\nconst checked = einvoice.validate(invoice);\nif (!checked.ok) throw new Error(JSON.stringify(checked.error));\nconst xml = einvoice.serialize(checked.data, { format: \"zugferd-2.5-en16931\" });\nif (!xml.ok) throw new Error(JSON.stringify(xml.error));\nconst document = await pdf.facturX({\n  html: invoiceHtml,\n  xml: xml.data.xml,\n  profile: \"EN 16931\",\n});\nawait files.save(document, \"invoice.pdf\");\n```\n\n`facturX` accepts the same render options plus required `xml` and `profile`.\nProfiles: `MINIMUM`, `BASIC WL`, `BASIC`, `EN 16931`, `EXTENDED`. Use `EN 16931`\nwith the bundled `einvoice.serialize` output; that serializer does not support\nthe other profiles. The service embeds `factur-x.xml`, sets Factur-X 1.0 invoice\nmetadata and requests PDF/A-3b. The app must supply matching HTML and XML.\nNeither rendering nor parsing certifies XSD, Schematron, tax or invoice validity.\n\n## Save a PDF in Files\n\nA chat PDF stays in the chat until code writes it elsewhere. To save it in the\nuser's Files, pass its chat path in `code_run.inputPaths` and write it through\nthe discovered `filesv2.content.create` action:\n\n```js\nexport default async () => {\n  const document = await files.read(\"/offer.pdf\");\n  const target = await capabilities.run(\"filesv2.content.create\", {\n    baseId: \"<exact ID from filesv2.bases.list>\",\n    path: \"Offers/offer.pdf\",\n    size: document.size,\n    mediaType: \"application/pdf\",\n  });\n  return capabilities.streams.write(target.stream, document);\n};\n```\n\nAsk for the storage base and folder when the request does not name them. The user\nreviews the write. It creates a new file and fails when the path exists;\nreplacing requires the current `expectedRevision`. A `pdf.render` result can be\nwritten the same way without saving it to the chat first. See\n[Capability calls](capabilities.md) for stream limits and interrupted writes.\n\n## Cancellation, access and limits\n\nAll three methods accept a second `{ signal }` argument, for example the signal\nfrom a `work.run` job. Abort rejects with `AbortError`. Stopping the execution\nhost also cancels pending PDF requests. Rendering creates no stored file until\ncode explicitly saves it; do not automatically retry failed calls.\n\nSaved resources need Use access, not Manage. One-off scripts need an accessible,\nunrestricted current chat. The server checks access before reading the body.\nNo service URL, credentials, shell flags or arbitrary conversion route are\nexposed to app code. This is an internal conversion, not `http.fetch`; there is\nno external API approval prompt.\n\nConfigured service input, output and timeout limits apply. HTML, its headers,\nfooters, assets and invoice XML share the HTML input budget. PDF attachments\nand the source PDF share the PDF input budget. All transfers also have a 64 MiB\nceiling; multipart framing has a separate bounded overhead. Shared storage and\nchat export budgets remain independent. Errors include `PDF_NOT_CONFIGURED`,\n`PDF_LIMIT`, `PDF_TIMEOUT`, `PDF_FAILED`, `INVALID_INPUT`, and `ACCESS_DENIED`.\n"
+      "content": "# Generate PDFs\n\n`pdf.render`, `pdf.attach` and `pdf.facturX` are asynchronous and return a PDF\n`Blob`. They use the instance's configured PDF service. `pdf.open` is\nthe local text reader described in [Documents](documents.md).\n\n## Choose the path\n\nA document written in the chat needs no code. Use the chat tool\n`markdown_to_pdf` for text-first documents; it applies A4 presets and custom CSS\nand turns images into links. Use `html_to_pdf` for a chat `.html` file whose\nlayout needs HTML and CSS, images, or fonts. It takes optional CSS (file or\ninline), header and footer files, chat files as named assets, and the `page`\noptions below, then writes a sibling `.pdf` for `present`. Use `pdf.render` when\ncode builds the document from data, for Factur-X or attachments, and in Studio\nApps.\n\n## HTML and CSS\n\n```js\nconst document = await pdf.render({\n  html: `<!doctype html><html><head><title>Stock report</title><style>\n    body { font-family: sans-serif; }\n    h1 { color: #087f70; }\n    tr { break-inside: avoid; }\n  </style></head><body><h1>Stock report</h1><img src=\"logo.png\"></body></html>`,\n  assets: [{ name: \"logo.png\", data: logoFile }],\n  page: { format: \"A4\", landscape: false, margin: { top: 15, right: 15, bottom: 15, left: 15 } },\n  tagged: true,\n});\nawait files.save(document, \"stock-report.pdf\");\n```\n\n`html` is required. Give it a `<title>`: PDF viewers show it as the document\nname, and without one they show a random file name. `assets` defaults to an empty array and accepts named `Blob`\nvalues for local images, fonts and CSS. Use plain filenames, no directories;\nreference the exact filename from HTML or CSS. Duplicate names and the reserved\nnames `index.html`, `header.html`, `footer.html`, `factur-x.xml` fail.\n`headerHtml` and `footerHtml` are optional independent HTML strings with their own\nCSS. They load no assets; use `data:` URLs for images there. Page markers such as\n`<span class=\"pageNumber\"></span>` work in those templates, and the page margin\nmust leave room for them. Background colors are printed.\n\n`page.format` defaults to `A4`; alternatives are `A3`, `A5`, `Letter`, and `Legal`.\n`landscape` defaults to false. Each margin is a nonnegative millimeter number,\ndefaulting to 15. Use `page` for paper dimensions and margins; avoid conflicting\nCSS `@page` rules. `tagged` defaults to true, which requests a tagged PDF but does\nnot certify accessibility.\n\nStudio styles are not inherited. Scripts, redirects, frames and outbound\nresources are blocked. MathML (`math`) and the SVG elements `foreignObject` and\n`desc` are removed; write formulas and labels as HTML and CSS or as SVG text.\nSupply local assets or data URLs; this is not a URL-to-PDF browser or a\nJavaScript rendering environment.\n\n## Attach files\n\n```js\nconst result = await pdf.attach({\n  document,\n  attachments: [{\n    name: \"details.xml\",\n    data: new Blob([xml], { type: \"application/xml\" }),\n    relationship: \"Data\",\n  }],\n});\nawait files.shared.write(\"reports/with-details.pdf\", result);\n```\n\nThe source PDF and attachments are ordinary `Blob`s. Their origin does not\nmatter: explicit picker selections, authorized chat inputs, or app storage use\nthe same API. `relationship` defaults to `Unspecified`; alternatives are\n`Source`, `Data`, `Alternative`, and `Supplement`. MIME type comes from the Blob\nand defaults to `application/octet-stream` if empty. Provide at least one attachment. Names within the request\nmust be unique. All asset/attachment names are 1–180 characters, with no slash,\nbackslash or control characters, and cannot be `.` or `..`. Embedding an XML file alone does not create a compliant invoice.\n\n## Factur-X / ZUGFeRD\n\n```js\nconst checked = einvoice.validate(invoice);\nif (!checked.ok) throw new Error(JSON.stringify(checked.error));\nconst xml = einvoice.serialize(checked.data, { format: \"zugferd-2.5-en16931\" });\nif (!xml.ok) throw new Error(JSON.stringify(xml.error));\nconst document = await pdf.facturX({\n  html: invoiceHtml,\n  xml: xml.data.xml,\n  profile: \"EN 16931\",\n});\nawait files.save(document, \"invoice.pdf\");\n```\n\n`facturX` accepts the same render options plus required `xml` and `profile`.\nProfiles: `MINIMUM`, `BASIC WL`, `BASIC`, `EN 16931`, `EXTENDED`. Use `EN 16931`\nwith the bundled `einvoice.serialize` output; that serializer does not support\nthe other profiles. The service embeds `factur-x.xml`, sets Factur-X 1.0 invoice\nmetadata and requests PDF/A-3b. The app must supply matching HTML and XML.\nNeither rendering nor parsing certifies XSD, Schematron, tax or invoice validity.\n\n## Save a PDF in Files\n\nA chat PDF stays in the chat until code writes it elsewhere. To save it in the\nuser's Files, pass its chat path in `code_run.inputPaths` and write it through\nthe discovered `filesv2.content.create` action:\n\n```js\nexport default async () => {\n  const document = await files.read(\"/offer.pdf\");\n  const target = await capabilities.run(\"filesv2.content.create\", {\n    baseId: \"<exact ID from filesv2.bases.list>\",\n    path: \"Offers/offer.pdf\",\n    size: document.size,\n    mediaType: \"application/pdf\",\n  });\n  return capabilities.streams.write(target.stream, document);\n};\n```\n\nAsk for the storage base and folder when the request does not name them. The user\nreviews the write. It creates a new file and fails when the path exists;\nreplacing requires the current `expectedRevision`. A `pdf.render` result can be\nwritten the same way without saving it to the chat first. See\n[Capability calls](capabilities.md) for stream limits and interrupted writes.\n\n## Cancellation, access and limits\n\nAll three methods accept a second `{ signal }` argument, for example the signal\nfrom a `work.run` job. Abort rejects with `AbortError`. Stopping the execution\nhost also cancels pending PDF requests. Rendering creates no stored file until\ncode explicitly saves it; do not automatically retry failed calls.\n\nSaved resources need Use access, not Manage. One-off scripts need an accessible,\nunrestricted current chat. The server checks access before reading the body.\nNo service URL, credentials, shell flags or arbitrary conversion route are\nexposed to app code. This is an internal conversion, not `http.fetch`; there is\nno external API approval prompt.\n\nConfigured service input, output and timeout limits apply. HTML, its headers,\nfooters, assets and invoice XML share the HTML input budget. PDF attachments\nand the source PDF share the PDF input budget. All transfers also have a 64 MiB\nceiling; multipart framing has a separate bounded overhead. Shared storage and\nchat export budgets remain independent. Errors include `PDF_NOT_CONFIGURED`,\n`PDF_LIMIT`, `PDF_TIMEOUT`, `PDF_FAILED`, `INVALID_INPUT`, and `ACCESS_DENIED`.\n"
     },
     {
       "path": "references/publishing.md",

package/src/ai/html-pdf-tool.ts

@@ -100,7 +100,7 @@ export const createCloudAiHtmlToPdfTool = (dependencies: HtmlPdfToolDependencies
   return defineAiTool({
     name: "html_to_pdf",
     description:
-      'Convert one assistant-created conversation HTML file to a sibling PDF; the output path replaces .html with .pdf. Use it when the layout needs HTML and CSS, such as columns, exact tables, letterheads, invoices, certificates, images, or custom fonts; use markdown_to_pdf for text-first documents. Write the .html source with write_file first, appending long files in parts; CSS, header, footer, and asset files can be any conversation files, including uploads. Rendering is offline without JavaScript: scripts, frames, and remote URLs are removed or blocked, and MathML and the SVG foreignObject and desc elements are removed, so write formulas and labels as HTML and CSS or as SVG text. Embed images and fonts as data: URLs, or list conversation files in assets and reference each by its file name only, for example <img src="logo.png"> or url("brand.woff2"); percent-encode #, ?, %, and : in a name, such as logo%232.png for logo#2.png. cssPath and customCss apply after the document\'s own styles. page sets paper size (default A4), orientation, and millimeter margins (default 15); CSS @page sizes are ignored. Header and footer files are small separate HTML documents with their own inline styles; they load no assets, so use data: URLs for images there. <span class="pageNumber"></span> and <span class="totalPages"></span> print page numbers, and the top or bottom margin must leave room for them. All input files share the configured PDF input budget. Call present with the returned path. To also save the PDF in Files, follow the PDF reference of the assistant-code-mode skill.',
+      'Convert one assistant-created conversation HTML file to a sibling PDF; the output path replaces .html with .pdf. Use it when the layout needs HTML and CSS, such as columns, exact tables, letterheads, invoices, certificates, images, or custom fonts; use markdown_to_pdf for text-first documents. Write the .html source with write_file first, appending long files in parts; CSS, header, footer, and asset files can be any conversation files, including uploads. Rendering is offline without JavaScript: scripts, frames, and remote URLs are removed or blocked, and MathML and the SVG foreignObject and desc elements are removed, so write formulas and labels as HTML and CSS or as SVG text. Embed images and fonts as data: URLs, or list conversation files in assets and reference each by its file name only, for example <img src="logo.png"> or url("brand.woff2"); percent-encode #, ?, %, and : in a name, such as logo%232.png for logo#2.png. cssPath and customCss apply after the document\'s own styles. page sets paper size (default A4), orientation, and millimeter margins (default 15); CSS @page sizes are ignored. Header and footer files are small separate HTML documents with their own inline styles; they load no assets, so use data: URLs for images there. <span class="pageNumber"></span> and <span class="totalPages"></span> print page numbers, and the top or bottom margin must leave room for them. The HTML <title> names the PDF in viewers; without one, the file name does. All input files share the configured PDF input budget. Call present with the returned path. To also save the PDF in Files, follow the PDF reference of the assistant-code-mode skill.',
     inputSchema: CloudAiHtmlToPdfInputSchema,
     outputSchema: CloudAiHtmlToPdfOutputSchema,
     approval: "never",
@@ -158,6 +158,7 @@ export const createCloudAiHtmlToPdfTool = (dependencies: HtmlPdfToolDependencies
             // Like Code Mode, the document renders in standards mode. Separate CSS
             // follows the document, so it wins over the document's own styles.
             html: `<!doctype html>${source}${css ? `\n<style>\n${css}\n</style>\n` : ""}`,
+            title: basename(sourcePath).replace(HTML_EXTENSION, ""),
             headerHtml,
             footerHtml,
             assets,

package/src/ai/markdown-pdf-tool.ts

@@ -84,7 +84,15 @@ export const createCloudAiMarkdownToPdfTool = (dependencies: MarkdownPdfToolDepe
     let rendered: { pdf: Uint8Array; contentType: string };
     try {
       rendered = await withAiPdfConversionSlot(() =>
-        render({ markdown, templateId: input.template, customCss: input.customCss }, { signal: ctx.signal }),
+        render(
+          {
+            markdown,
+            title: sourcePath.slice(sourcePath.lastIndexOf("/") + 1, -".md".length),
+            templateId: input.template,
+            customCss: input.customCss,
+          },
+          { signal: ctx.signal },
+        ),
       );
     } catch (error) {
       throw ctx.signal.aborted ? cancelled() : error;

package/src/services/pdf/gotenberg.ts

@@ -32,6 +32,12 @@ export type GotenbergConfig = {
 
 export type RenderHtmlToPdfInput = {
   html: string;
+  /**
+   * Document title that PDF viewers show, such as the document's name. The
+   * HTML's own non-blank `<title>` wins; without either, viewers show a
+   * random file name.
+   */
+  title?: string;
   headerHtml?: string | null;
   footerHtml?: string | null;
   filename?: string;
@@ -49,7 +55,8 @@ export type AttachPdfFilesInput = {
   attachments: Array<{ name: string; data: Blob; relationship?: "Source" | "Data" | "Alternative" | "Supplement" | "Unspecified" }>;
 };
 
-export type RenderFacturXHtmlToPdfInput = RenderHtmlToPdfInput & {
+/** PDF/A conversion drops the document title, so viewers show the file name of a Factur-X invoice. */
+export type RenderFacturXHtmlToPdfInput = Omit<RenderHtmlToPdfInput, "title"> & {
   xml: string;
   conformanceLevel?: "MINIMUM" | "BASIC WL" | "BASIC" | "EN 16931" | "EXTENDED";
   documentType?: "INVOICE" | "ORDER" | "ORDER RESPONSE";
@@ -132,7 +139,7 @@ function htmlForm(input: RenderHtmlToPdfInput, config: GotenbergConfig): FormDat
     (input.assets ?? []).reduce((sum, asset) => sum + asset.data.size, 0);
   if (total > config.maxHtmlBytes) throw new GotenbergRenderError("html_too_large", "HTML and assets exceed the configured input budget.");
   const form = new FormData();
-  form.append("files", new Blob([offlineHtml(input.html)], { type: "text/html" }), "index.html");
+  form.append("files", new Blob([offlineHtml(input.html, input.title)], { type: "text/html" }), "index.html");
   if (input.headerHtml?.trim()) form.append("files", new Blob([offlineHtml(input.headerHtml)], { type: "text/html" }), "header.html");
   if (input.footerHtml?.trim()) form.append("files", new Blob([offlineHtml(input.footerHtml)], { type: "text/html" }), "footer.html");
   const names = new Set(["index.html", "header.html", "footer.html", "factur-x.xml"]);

package/src/services/pdf/markdown.ts

@@ -30,6 +30,8 @@ export class MarkdownPdfError extends Error {
 
 export type RenderMarkdownToPdfInput = {
   markdown: string;
+  /** Document title that PDF viewers show, such as the note or file name. */
+  title?: string;
   templateId?: MarkdownPdfTemplateId;
   customCss?: string;
 };
@@ -201,7 +203,7 @@ export const renderMarkdownToPdfWithConfig = (
   input: RenderMarkdownToPdfInput,
   config: GotenbergConfig,
   options: RenderMarkdownToPdfOptions = {},
-): Promise<RenderHtmlToPdfResult> => renderHtmlToPdfWithConfig({ html: buildMarkdownPdfHtml(input) }, config, options);
+): Promise<RenderHtmlToPdfResult> => renderHtmlToPdfWithConfig({ html: buildMarkdownPdfHtml(input), title: input.title }, config, options);
 
 export const renderMarkdownToPdf = async (
   input: RenderMarkdownToPdfInput,

package/src/services/pdf/offline-html.ts

@@ -13,6 +13,16 @@
  * MathML (`math`) and the SVG elements that hold HTML (`foreignObject`,
  * `desc`) go as well; they have no print use in Cloud documents. SVG shapes,
  * images, `title`, and links stay, so graphics still render.
+ *
+ * Chromium takes the PDF title from the document's first `<title>`. Without
+ * one it falls back to the random name Gotenberg gives the uploaded file,
+ * which PDF viewers then show. A caller title fills that gap: it goes ahead
+ * of the document, so it becomes the first title, unless the document names
+ * itself with a non-blank HTML `<title>`. SVG titles label graphics, template
+ * content stays inert, and removed elements take their titles with them, so
+ * none of them count. A title of only whitespace character references, such
+ * as `&#32;`, still counts and leaves the random name; generated HTML does not
+ * write whitespace that way.
  */
 const POLICY =
   "default-src 'none'; style-src 'unsafe-inline' file: data:; img-src file: data:; font-src file: data:; base-uri 'none'; form-action 'none'";
@@ -53,13 +63,48 @@ const leadingDoctype = (html: string): string => {
 /** An empty comment stands in for a removed element, so the text on either side stays separate. */
 const REMOVED = "<!---->";
 
-export const offlineHtml = (html: string): string =>
-  leadingDoctype(html) +
-  OFFLINE_META +
-  new HTMLRewriter()
-    // Chromium parses noscript content as markup when JavaScript is disabled.
-    // math, foreignObject, and desc: see the module comment.
-    .on("script, noscript, meta, base, iframe, frame, frameset, object, embed, math, foreignObject, desc", {
+// Chromium parses noscript content as markup when JavaScript is disabled.
+// math, foreignObject, and desc: see the module comment.
+const REMOVED_ELEMENTS = [
+  "script",
+  "noscript",
+  "meta",
+  "base",
+  "iframe",
+  "frame",
+  "frameset",
+  "object",
+  "embed",
+  "math",
+  "foreignObject",
+  "desc",
+];
+const INERT_TITLES = ["svg", "template", ...REMOVED_ELEMENTS].map((element) => `${element} title`).join(", ");
+
+const escapeTitle = (title: string): string => title.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+
+export const offlineHtml = (html: string, title?: string): string => {
+  // Only the text of the first HTML title element names the document.
+  let current: { inert: boolean } | undefined;
+  let firstSeen = false;
+  let named = false;
+  const offline = new HTMLRewriter()
+    .on("title", {
+      element() {
+        if (current && !current.inert) firstSeen = true;
+        current = { inert: false };
+      },
+      text(chunk) {
+        if (!firstSeen && !current?.inert && chunk.text.trim()) named = true;
+      },
+    })
+    // Runs after the title handler for the same element, in registration order.
+    .on(INERT_TITLES, {
+      element() {
+        if (current) current.inert = true;
+      },
+    })
+    .on(REMOVED_ELEMENTS.join(", "), {
       element(element) {
         element.replace(REMOVED, { html: true });
       },
@@ -72,3 +117,6 @@ export const offlineHtml = (html: string): string =>
       },
     })
     .transform(html);
+  const fallbackTitle = title?.trim() && !named ? `<title>${escapeTitle(title.trim())}</title>` : "";
+  return leadingDoctype(html) + OFFLINE_META + fallbackTitle + offline;
+};

package/src/services/pdf/template-preview.ts

@@ -39,6 +39,8 @@ export type RenderTemplatePdfPreviewInput = {
   data: Record<string, unknown>;
   filters?: LiquidTemplateOptions["filters"];
   filename?: string;
+  /** PDF document title when the rendered HTML has no `<title>`; see `RenderHtmlToPdfInput.title`. */
+  title?: string;
 };
 
 export type RenderTemplatePdfPreviewOptions = RenderHtmlToPdfOptions & {
@@ -89,7 +91,7 @@ export const renderTemplatePdfPreview = async (
   }
 
   try {
-    const pdfInput = { html, headerHtml, footerHtml, filename: input.filename };
+    const pdfInput = { html, title: input.title, headerHtml, footerHtml, filename: input.filename };
     return {
       ok: true,
       html,

package/src/shared/markdown/index.ts

@@ -21,8 +21,9 @@ import { taskListExtension } from "./extensions/task-list";
 
 // Create a configured marked instance
 type MarkdownProfile = "content" | "help";
+type LinkStyle = "widget" | "plain";
 
-const createMarked = (profile: MarkdownProfile = "content", notices: NoticeStyle = "card") => {
+const createMarked = (profile: MarkdownProfile = "content", notices: NoticeStyle = "card", links: LinkStyle = "widget") => {
   const marked = new Marked();
 
   marked.use({
@@ -35,7 +36,8 @@ const createMarked = (profile: MarkdownProfile = "content", notices: NoticeStyle
   marked.use(infoBlocksExtension(notices));
   marked.use(taskListExtension());
   marked.use(tablesExtension());
-  marked.use(linksExtension({ internalTarget: profile === "help" ? "_self" : "_blank" }));
+  // Plain links keep marked's own renderer: an anchor around the link text.
+  if (links === "widget") marked.use(linksExtension({ internalTarget: profile === "help" ? "_self" : "_blank" }));
   marked.use(imagesExtension());
   marked.use(katexExtension());
   marked.use(codeExtension());
@@ -48,15 +50,24 @@ const createMarked = (profile: MarkdownProfile = "content", notices: NoticeStyle
 };
 
 const marked = createMarked();
-const minimalNoticeMarked = createMarked("content", "minimal");
 const helpMarked = createMarked("help");
+const contentMarked = new Map<`${NoticeStyle}:${LinkStyle}`, Marked>([["card:widget", marked]]);
 
 export type MarkdownRenderOptions = {
   /** `"minimal"` shows notices as tone colour only; the type name stays for screen readers. */
   notices?: NoticeStyle;
+  /** `"plain"` renders each link as an ordinary anchor around its text, for HTML read outside Cloud such as email. */
+  links?: LinkStyle;
 };
 
-const markedFor = (options: MarkdownRenderOptions): Marked => (options.notices === "minimal" ? minimalNoticeMarked : marked);
+const markedFor = ({ notices = "card", links = "widget" }: MarkdownRenderOptions): Marked => {
+  const key = `${notices}:${links}` as const;
+  const cached = contentMarked.get(key);
+  if (cached) return cached;
+  const created = createMarked("content", notices, links);
+  contentMarked.set(key, created);
+  return created;
+};
 
 const sanitizeRenderedHtml = (html: string): string =>
   sanitizeHtml(html, {

package/src/ssr/LayoutHeader.tsx

@@ -1,4 +1,4 @@
-import { ButtonLink } from "@k2b/ui";
+import { ButtonLink, IconButtonLink } from "@k2b/ui";
 import type { NavigationSearchItem } from "../browser/navigation-search";
 import type { CloudTheme } from "../shared/theme";
 import AppLaunchpad, { type AppLaunchpadApp } from "./AppLaunchpad.island";
@@ -34,17 +34,13 @@ export default function LayoutHeader(props: LayoutHeaderProps) {
       style="box-shadow: var(--ui-shadow-surface)"
     >
       <div class="flex min-w-0 items-center gap-2">
-        <a
-          href="/"
-          class={
-            props.authenticated
-              ? "inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-lg text-dimmed transition-colors hover:bg-zinc-100 hover:text-secondary lg:hidden dark:hover:bg-zinc-800"
-              : "flex shrink-0 items-center"
-          }
-          aria-label={props.homeLabel}
-        >
-          <img src="/branding/logo" alt="" class={props.authenticated ? "h-4 w-4" : "h-6 w-6"} />
-        </a>
+        {/* Signed-in desktops reach Home through the rail. `lg:hidden` sits on a wrapper because the button's
+            own display would win over the utility on the link. */}
+        <div class={props.authenticated ? "flex shrink-0 lg:hidden" : "flex shrink-0"}>
+          <IconButtonLink href="/" label={props.homeLabel}>
+            <img src="/branding/logo" alt="" class={props.authenticated ? "h-4 w-4" : "h-6 w-6"} />
+          </IconButtonLink>
+        </div>
         <div class="hidden min-w-0 items-center lg:flex">
           <LayoutBreadcrumbs breadcrumbs={props.breadcrumbs} />
         </div>
@@ -66,40 +62,22 @@ export default function LayoutHeader(props: LayoutHeaderProps) {
             searchLinks={props.searchLinks}
             searchResources={props.authenticated}
           />
+          {(props.authenticated || props.appLabel) && (
+            <AppLaunchpad
+              profile={props.authenticated ? { name: props.profileName, theme: props.theme } : undefined}
+              apps={props.launchpadApps}
+              legalLinks={props.legalLinks}
+              variant="header"
+              label={props.openAppsLabel}
+            />
+          )}
         </div>
         {props.authenticated ? (
-          <>
-            <div class="lg:hidden">
-              <AppLaunchpad
-                profile={props.authenticated ? { name: props.profileName, theme: props.theme } : undefined}
-                apps={props.launchpadApps}
-                legalLinks={props.legalLinks}
-                variant="header"
-                label={props.openAppsLabel}
-              />
-            </div>
-            <div class="hidden lg:block">
-              <ProfilePreferences
-                avatarSrc={props.profileAvatarSrc}
-                initialTheme={props.theme}
-                name={props.profileName}
-                placement="header"
-              />
-            </div>
-          </>
+          <div class="hidden lg:block">
+            <ProfilePreferences avatarSrc={props.profileAvatarSrc} initialTheme={props.theme} name={props.profileName} placement="header" />
+          </div>
         ) : (
           <>
-            {props.appLabel && (
-              <div class="lg:hidden">
-                <AppLaunchpad
-                  profile={props.authenticated ? { name: props.profileName, theme: props.theme } : undefined}
-                  apps={props.launchpadApps}
-                  legalLinks={props.legalLinks}
-                  variant="header"
-                  label={props.openAppsLabel}
-                />
-              </div>
-            )}
             <LayoutPreferences initialTheme={props.theme} position="bottom-left" />
             <ButtonLink href="/auth/login" size="sm" variant="primary">
               <i class="ti ti-login" aria-hidden="true" />

package/src/ssr/workspace-navigation.ts

@@ -49,12 +49,14 @@ export function readWorkspaceNavigation(): WorkspaceNavigationState | undefined
   try {
     const value: unknown = JSON.parse(owner.textContent ?? "");
     if (!value || typeof value !== "object" || !("items" in value) || !validItems(value.items)) return;
-    // SSR links work before the app island loads; action handlers are not yet available.
+    // SSR links work before the app island loads; action and disclosure handlers are not yet available,
+    // so the owner's folds only set where the local disclosure starts.
     const links = (items: readonly NavigationItem[]): NavigationItem[] =>
       items.map((item) => ({
         ...item,
         disabled: item.disabled || Boolean(item.action && !item.href),
         ...(item.href ? { action: undefined } : {}),
+        ...(item.expanded !== undefined ? { expanded: undefined, defaultExpanded: item.expanded } : {}),
         ...(item.children ? { children: links(item.children) } : {}),
         ...(item.actions ? { actions: links(item.actions) } : {}),
       }));