@k2b/cloud 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -19,6 +19,7 @@
     "!src/**/*.test.tsx",
     "!src/**/*.integration.test.ts",
     "!src/**/*.test-fixture.ts",
+    "!src/**/*.test-fixture.tsx",
     "!scripts/**/*.test.ts",
     "!scripts/runtime-recovery-*.ts"
   ],
@@ -37,10 +38,12 @@
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
     "./browser/commands": "./src/browser/commands.ts",
+    "./browser/panel": "./src/browser/panel.ts",
     "./browser/search": "./src/browser/search.ts",
     "./browser/widgets": "./src/browser/widgets.ts",
     "./browser/testing": "./src/browser/testing.ts",
     "./browser/resource-picker": "./src/browser/resource-picker.tsx",
+    "./browser/composer-insert": "./src/browser/composer-insert.ts",
     "./browser/files": "./src/browser/files.tsx",
     "./capabilities": "./src/capabilities/client.ts",
     "./capabilities/server": "./src/capabilities/server.ts",
@@ -102,12 +105,13 @@
     "@firecrawl/anydoc": "0.2.4",
     "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
+    "sharp": "0.35.4",
     "@simplewebauthn/server": "14.0.3",
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
     "@k2b/ssr": "0.17.0",
-    "@k2b/ui": "0.27.0",
+    "@k2b/ui": "0.29.0",
     "@k2b/stdlib": "0.29.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
@@ -115,6 +119,7 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.3",
+    "htmlparser2": "12.0.0",
     "jose": "6.2.12",
     "katex": "0.18.9",
     "liquidjs": "10.29.0",
@@ -139,7 +144,7 @@
     "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.15",
     "hono": "4.13.9",
-    "playwright": "1.63.0",
+    "playwright": "1.64.1",
     "solid-js": "1.9.15",
     "typescript": "7.0.2",
     "zod": "4.6.5"

package/scripts/build-canvas-workers.ts

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

package/scripts/build.ts

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

package/src/_internal/app-path.ts

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

package/src/_internal/app-presentation.ts

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

package/src/_internal/canvas-worker.ts

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

package/src/_internal/define-app.ts

@@ -89,7 +89,7 @@ import { configurePostgresApplicationName } from "./postgres-application-name";
 import { getProcessSync, startProcessSync } from "./process-sync";
 import { APP_READINESS_PATH, appReadinessResponse } from "./readiness";
 import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
-import { canonicalRoute, isOwnNavBadge } from "./registry-validation";
+import { canonicalRoute, isOwnAppPath } from "./registry-validation";
 import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 import { servePublicAsset } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
@@ -144,6 +144,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
     label: string;
     links: ReadonlyArray<{ label: string; href: string; icon: string }>;
   }>;
+  panel?: AppMeta["panel"];
   nav?: {
     href: string;
     match?: string;
@@ -371,11 +372,31 @@ const validateAppPwaPart = (opts: Pick<AppOptions, "id" | "routes" | "pwa">): Ap
 /** The badge route is read by the browser through the gateway, so it must be one of this app's own paths. */
 const validateAppNavBadge = (opts: Pick<AppOptions, "id" | "routes" | "nav">): void => {
   const badge = opts.nav?.badge;
-  if (badge !== undefined && !isOwnNavBadge(badge, opts.routes)) {
+  if (badge !== undefined && !isOwnAppPath(badge, opts.routes)) {
     throw new Error(`App "${opts.id}" declares nav.badge "${badge}"; it must be a same-origin path below one of its routes`);
   }
 };
 
+const validateAppPanel = (opts: Pick<AppOptions, "id" | "routes" | "panel">): AppMeta["panel"] => {
+  const panel = opts.panel;
+  if (panel === undefined) return undefined;
+  if (!panel || typeof panel !== "object" || Array.isArray(panel)) throw new Error(`App "${opts.id}" declares panel; it must be an object`);
+  if (typeof panel.href !== "string" || !isOwnAppPath(panel.href, opts.routes)) {
+    throw new Error(`App "${opts.id}" declares panel.href "${panel.href}"; it must be a same-origin path below one of its routes`);
+  }
+  for (const field of ["label", "icon"] as const) {
+    if (typeof panel[field] !== "string" || !panel[field].trim())
+      throw new Error(`App "${opts.id}" declares panel.${field}; it must be a non-empty string`);
+  }
+  if (
+    panel.requiresRoles !== undefined &&
+    (!Array.isArray(panel.requiresRoles) || !panel.requiresRoles.every((role) => typeof role === "string"))
+  ) {
+    throw new Error(`App "${opts.id}" declares panel.requiresRoles; it must be an array of strings`);
+  }
+  return { ...panel, requiresRoles: panel.requiresRoles ? [...panel.requiresRoles] : undefined };
+};
+
 export const defineApp = <
   const S extends AppSettingsMap = {},
   const N extends NotificationDefinitionMap = {},
@@ -391,6 +412,7 @@ export const defineApp = <
   const cliModules = validateAppCliModules(opts.id, opts.cli);
   const pwaPart = validateAppPwaPart(opts);
   validateAppNavBadge(opts);
+  const panel = validateAppPanel(opts);
 
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
@@ -528,6 +550,7 @@ export const defineApp = <
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     pwa: pwaPart,
+    panel,
     widgets: compileWidgetDeclarations(opts.id, opts.widgets),
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
@@ -627,6 +650,9 @@ export const defineApp = <
         pwa: meta.pwa
           ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
           : undefined,
+        panel: meta.panel
+          ? { ...meta.panel, requiresRoles: meta.panel.requiresRoles ? [...meta.panel.requiresRoles] : undefined }
+          : undefined,
         widgets: meta.widgets?.map((widget) => ({
           ...widget,
           ...(widget.settings ? { settings: structuredClone(widget.settings) } : {}),

package/src/_internal/help-catalog.ts

@@ -1,5 +1,124 @@
+import { i18n } from "@k2b/stdlib";
+import { formatShortcut } from "@k2b/ui";
+import type { Token } from "marked";
 import type { HelpArticle } from "../services/help/types";
-import { markdownToPlainText } from "../shared/markdown";
+import { parseHelpReference } from "../shared/help";
+import { lexHelpMarkdown, markdownToPlainText } from "../shared/markdown";
+
+const helpAgentMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: { apple: ({ shortcut }: { shortcut: string }) => `${shortcut} on Mac` },
+    de: { apple: ({ shortcut }) => `${shortcut} auf dem Mac` },
+  },
+});
+
+const helpLinkLabel = (source: string, fallback: string): string => {
+  // Index backtick runs once so unmatched runs cannot repeatedly scan the remaining source.
+  const backticks = new Map<number, { positions: number[]; next: number }>();
+  for (const run of source.matchAll(/`+/g)) {
+    const length = run[0].length;
+    if (!backticks.has(length)) backticks.set(length, { positions: [], next: 0 });
+    backticks.get(length)!.positions.push(run.index);
+  }
+  let depth = 0;
+  for (let index = 1; index < source.length; index++) {
+    const char = source[index];
+    if (char === "\\") index++;
+    else if (char === "`") {
+      let end = index + 1;
+      while (source[end] === "`") end++;
+      const length = end - index;
+      const runs = backticks.get(length);
+      if (runs) {
+        while (runs.next < runs.positions.length && runs.positions[runs.next]! <= index) runs.next++;
+      }
+      const closing = runs?.positions[runs.next];
+      index = closing === undefined ? end - 1 : closing + length - 1;
+    } else if (char === "[") depth++;
+    else if (char === "]") {
+      if (depth === 0) return source.slice(1, index);
+      depth--;
+    }
+  }
+  return fallback;
+};
+
+/** Portable source for agents and Copy as Markdown; code is kept verbatim. */
+export const helpAgentMarkdown = (
+  article: Pick<HelpArticle, "markdown" | "locale" | "appId" | "links">,
+  tokens: readonly Token[] = lexHelpMarkdown(article.markdown, article.locale),
+): string => {
+  const { t } = helpAgentMessages.resolve([article.locale]);
+  const rewriteChildren = (raw: string, children: readonly Token[]): string => {
+    let offset = 0;
+    let result = "";
+    for (const child of children) {
+      let start = raw.indexOf(child.raw, offset);
+      let source = child.raw;
+      if (start < 0 && child.raw.includes("|")) {
+        source = child.raw.replaceAll("|", "\\|");
+        start = raw.indexOf(source, offset);
+      }
+      // Marked removes quote markers and list indentation from child block sources.
+      if (start < 0 && child.raw.includes("\n")) {
+        const pattern = child.raw
+          .split("\n")
+          .map((line, index) => (index > 0 ? line.replace(/^[ \t]+/, "") : line).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+          .join("\\r?\\n[ \\t>]*");
+        const match = new RegExp(pattern).exec(raw.slice(offset));
+        if (match) {
+          start = offset + match.index;
+          source = match[0];
+        }
+      }
+      if (start < 0) break;
+      result += raw.slice(offset, start) + rewrite(child, source);
+      offset = start + source.length;
+    }
+    return result + raw.slice(offset);
+  };
+  const rewrite = (token: Token, source: string): string => {
+    if (token.type === "code" || token.type === "codespan") return source;
+    if (token.type === "helpKbd") {
+      const keys = String(token.keys);
+      const other = formatShortcut(keys, { platform: "other", locale: article.locale });
+      const apple = formatShortcut(keys, { platform: "apple", locale: article.locale }).label;
+      // Key labels such as | or ` stay text in a table cell or a sentence.
+      const escape = (text: string) => text.replace(/[\\`*_[\]|<>~]/g, "\\$&");
+      // A key without a platform modifier reads by its name: "Enter", not "↵".
+      return other.label === apple ? escape(other.name) : `${escape(other.label)} (${t.apple({ shortcut: escape(apple) })})`;
+    }
+    if (token.type === "helpDetails") {
+      const newline = source.includes("\r\n") ? "\r\n" : "\n";
+      const bodyStart = source.indexOf("\n") + 1;
+      const closing = [...source.matchAll(/^[ \t>]*:::[ \t]*(?:\r?\n|$)/gm)].at(-1)!;
+      const body = source.slice(bodyStart, closing.index);
+      const prefix = body.match(/^[ \t>]+/)?.[0] ?? "";
+      const trailing = source.slice(closing.index + closing[0].length);
+      return `**${rewriteChildren(String(token.title), token.titleTokens ?? [])}**${newline}${prefix}${newline}${rewriteChildren(body, token.tokens ?? [])}${trailing}`;
+    }
+    if (token.type === "helpLabel") return rewriteChildren(source.replace(/\{icon="[a-z0-9-]+"\}$/, ""), token.tokens ?? []);
+    if (token.type === "link" && token.href.startsWith("help:")) {
+      const ref = parseHelpReference(token.href.slice(5));
+      const target = ref && article.links[`${ref.appId ?? article.appId}/${ref.documentId}`];
+      const label = rewriteChildren(helpLinkLabel(source, token.text), token.tokens ?? []);
+      return target ? `[${label}](${target.url}${ref.fragment})` : label;
+    }
+    const children =
+      token.type === "list"
+        ? token.items
+        : token.type === "table"
+          ? [...token.header, ...token.rows.flat()].flatMap((cell) => cell.tokens)
+          : "tokens" in token
+            ? (token.tokens ?? [])
+            : [];
+    const raw = rewriteChildren(source, children);
+    return token.type === "heading" ? raw.replace(/[ \t]+\{icon="[a-z0-9-]+"\}(?=[ \t]*\r?\n?$)/i, "") : raw;
+  };
+  return rewriteChildren(article.markdown, tokens);
+};
+
 export const HELP_SEARCH_MAX_LIMIT = 25;
 export const HELP_READ_MAX_CHARS = 7_000;
 const normalizeSearchText = (value: string): string =>
@@ -33,7 +152,7 @@ const boundedExcerpt = (markdown: string, terms: readonly string[]): string => {
   return `${start > 0 ? `${marker}\n\n` : ""}${body}${start + budget < markdown.length ? `\n\n${marker}` : ""}`;
 };
 
-export const selectHelpMarkdown = (markdown: string, query?: string): { markdown: string; truncated: boolean } => {
+export const selectHelpMarkdown = (markdown: string, query?: string, locale?: string): { markdown: string; truncated: boolean } => {
   // An exact heading identifies one complete reference section, even in short articles.
   const headingQuery = query?.trim().toLocaleLowerCase();
   const exact =
@@ -53,7 +172,7 @@ export const selectHelpMarkdown = (markdown: string, query?: string): { markdown
   const phrase = normalizeSearchText(query ?? "");
   const ranked = splitSections(markdown)
     .map((section, index) => {
-      const text = normalizeSearchText(markdownToPlainText(section));
+      const text = normalizeSearchText(markdownToPlainText(section, locale));
       const score = (phrase && text.includes(phrase) ? 10 : 0) + terms.filter((term) => text.includes(term)).length;
       return { section, index, score };
     })
@@ -79,7 +198,7 @@ export const readHelpArticle = (document: HelpArticle, query?: string) => ({
   documentId: document.documentId,
   title: document.title,
   description: document.description,
-  ...selectHelpMarkdown(document.markdown, query),
+  ...selectHelpMarkdown(helpAgentMarkdown(document), query, document.locale),
 });
 
 export const helpResourceUri = (appId: string, documentId: string): string =>

package/src/_internal/help.ts

@@ -2,28 +2,49 @@ import { createHash } from "node:crypto";
 import type { AppRegistryHelpSummary } from "../contracts/registry";
 import type { HelpDefinition } from "../server/help";
 import type { HelpCorpus, HelpDocument } from "../services/help/types";
+import { parseHelpReference } from "../shared/help";
+import { lexHelpMarkdown, walkHelpTokens } from "../shared/markdown";
 
 export const HELP_DOCUMENT_MAX_BYTES = 128 * 1024;
+// defineHelp documents are frozen; retain only their validated targets, not the token trees.
+export const helpLinkTargets = new WeakMap<object, readonly string[]>();
 export type CompiledHelp = { summary: AppRegistryHelpSummary; corpus: HelpCorpus };
 
 export const compileHelp = (input: { appId: string; basePath?: string; definition: HelpDefinition }): CompiledHelp => {
-  const compileDocuments = (source: HelpDefinition["documents"]): HelpDocument[] =>
-    source.map(({ id, title, icon, description, order, markdown, searchText }) => {
+  const baseIds = new Set(input.definition.documents.map((document) => document.id));
+  const compileDocuments = (source: HelpDefinition["documents"], locale: string): HelpDocument[] =>
+    source.map((document) => {
+      const { id, title, icon, description, order, kind, needs, next, related, markdown, searchText } = document;
       if (Buffer.byteLength(markdown) > HELP_DOCUMENT_MAX_BYTES) {
         throw new Error(`Help document "${id}" exceeds the ${HELP_DOCUMENT_MAX_BYTES}-byte limit`);
       }
-      return { id, title, icon, description, order, markdown, searchText };
+      const validate = (reference: string) => {
+        const ref = parseHelpReference(reference);
+        if (ref?.appId === input.appId && !baseIds.has(ref.documentId))
+          throw new Error(`Help locale "${locale}" document "${id}" has unknown reference "${reference}"`);
+      };
+      for (const reference of related) validate(reference);
+      const targets = helpLinkTargets.get(document);
+      if (targets) {
+        for (const target of targets) validate(target);
+      } else {
+        walkHelpTokens(lexHelpMarkdown(markdown, locale), (token) => {
+          if (token.type === "link" && token.href.startsWith("help:")) validate(token.href.slice(5));
+        });
+      }
+      return { id, title, icon, description, order, kind, needs, next, related, markdown, searchText };
     });
   const baseLocale = input.definition.baseLocale ?? "en";
-  const documents = compileDocuments(input.definition.documents);
+  const documents = compileDocuments(input.definition.documents, baseLocale);
   const documentsByLocale = Object.fromEntries(
     Object.entries(input.definition.documentsByLocale ?? {})
       .filter(([locale]) => locale !== baseLocale)
       .sort(([a], [b]) => a.localeCompare(b))
-      .map(([locale, docs]) => [locale, compileDocuments(docs)]),
+      .map(([locale, docs]) => [locale, compileDocuments(docs, locale)]),
   );
+  // A revision bump republishes every corpus, here to fill the new metadata columns.
   const manifestHash = createHash("sha256")
-    .update(JSON.stringify({ revision: 1, appId: input.appId, baseLocale, documents, documentsByLocale }))
+    .update(JSON.stringify({ revision: 2, appId: input.appId, baseLocale, documents, documentsByLocale }))
     .digest("hex");
   return {
     summary: { manifestHash, pageBase: `${input.basePath?.replace(/\/$/, "") ?? ""}/help`, baseLocale },