@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/_internal/help-catalog.ts

@@ -1,49 +1,7 @@
-import type { AppRegistryEntry, HelpRegistryDocument, HelpRegistryEntry } from "../contracts/registry";
-import { helpLocaleChain } from "../shared/help";
+import type { HelpArticle } from "../services/help/types";
 import { markdownToPlainText } from "../shared/markdown";
-import { getApp, getHelp, listApps, listHelp } from "./registry";
-
 export const HELP_SEARCH_MAX_LIMIT = 25;
 export const HELP_READ_MAX_CHARS = 7_000;
-
-export type HelpCatalogDocument = {
-  appId: string;
-  appName: string;
-  appIcon?: string;
-  manifestHash: string;
-  locale: string;
-  documentId: string;
-  title: string;
-  description?: string;
-  order: number;
-  markdown: string;
-  searchText: string;
-};
-
-export type HelpCatalogItem = Omit<HelpCatalogDocument, "appIcon" | "manifestHash" | "order" | "markdown" | "searchText"> & {
-  kind: "help";
-};
-
-export type HelpCatalogRead = HelpCatalogItem & {
-  markdown: string;
-  truncated: boolean;
-};
-
-export type HelpCatalogDependencies = {
-  listApps?: () => Promise<AppRegistryEntry[]>;
-  listHelp?: () => Promise<HelpRegistryEntry[]>;
-};
-
-export type AppHelpDependencies = {
-  getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
-  getHelp?: (appId: string) => Promise<HelpRegistryEntry | null>;
-};
-
-export type ResolvedAppHelp =
-  | { status: "available"; app: AppRegistryEntry; help: HelpRegistryEntry }
-  | { status: "missing" }
-  | { status: "stale" };
-
 const normalizeSearchText = (value: string): string =>
   value
     .normalize("NFKD")
@@ -51,125 +9,7 @@ const normalizeSearchText = (value: string): string =>
     .toLocaleLowerCase()
     .replace(/[^\p{L}\p{N}]+/gu, " ")
     .trim();
-
-const searchTerms = (value: string): string[] =>
-  Array.from(
-    new Set(
-      normalizeSearchText(value)
-        .split(" ")
-        .filter((term) => term.length > 0),
-    ),
-  );
-
-export const resolveAppHelp = async (appId: string, dependencies: AppHelpDependencies = {}): Promise<ResolvedAppHelp> => {
-  const [app, help] = await Promise.all([(dependencies.getApp ?? getApp)(appId), (dependencies.getHelp ?? getHelp)(appId)]);
-  if (!app?.help || !help) return { status: "missing" };
-  if (app.help.manifestHash !== help.manifestHash) return { status: "stale" };
-  return { status: "available", app, help };
-};
-
-export const loadCurrentHelp = async (dependencies: HelpCatalogDependencies = {}): Promise<HelpRegistryEntry[]> => {
-  const [apps, entries] = await Promise.all([(dependencies.listApps ?? listApps)(), (dependencies.listHelp ?? listHelp)()]);
-  const manifestHashes = new Map(apps.flatMap((app) => (app.help ? [[app.id, app.help.manifestHash] as const] : [])));
-  return entries.filter((entry) => manifestHashes.get(entry.appId) === entry.manifestHash);
-};
-
-const resolveRegistryDocuments = (
-  entry: HelpRegistryEntry,
-  requestedLocale: string,
-): { locale: string; documents: HelpRegistryDocument[] } => {
-  const baseLocale = entry.baseLocale ?? "en";
-  const variants = entry.documentsByLocale ?? {};
-  const chain = helpLocaleChain(requestedLocale, baseLocale);
-  const locale = chain.find((candidate) => candidate === baseLocale || variants[candidate] !== undefined) ?? baseLocale;
-  const byId = new Map(entry.documents.map((document) => [document.id, document]));
-  for (const candidate of [...chain.slice(0, chain.indexOf(baseLocale)), baseLocale].reverse()) {
-    if (candidate === baseLocale) continue;
-    for (const document of variants[candidate] ?? []) byId.set(document.id, { ...byId.get(document.id), ...document });
-  }
-  return { locale, documents: entry.documents.map((document) => byId.get(document.id) ?? document) };
-};
-
-export const createHelpCatalog = (entries: readonly HelpRegistryEntry[], requestedLocale = "en"): HelpCatalogDocument[] =>
-  entries
-    .flatMap((entry) => {
-      const resolved = resolveRegistryDocuments(entry, requestedLocale);
-      return resolved.documents.map((document) => ({
-        appId: entry.appId,
-        appName: entry.appName,
-        appIcon: entry.appIcon,
-        manifestHash: entry.manifestHash,
-        locale: resolved.locale,
-        documentId: document.id,
-        title: document.title,
-        description: document.description,
-        order: document.order,
-        markdown: document.markdown,
-        searchText: document.searchText ?? markdownToPlainText(document.markdown),
-      }));
-    })
-    .sort(
-      (left, right) => left.appId.localeCompare(right.appId) || left.order - right.order || left.documentId.localeCompare(right.documentId),
-    );
-
-export const loadHelpCatalog = async (dependencies: HelpCatalogDependencies = {}, requestedLocale = "en"): Promise<HelpCatalogDocument[]> =>
-  createHelpCatalog(await loadCurrentHelp(dependencies), requestedLocale);
-
-const catalogItem = (document: HelpCatalogDocument): HelpCatalogItem => ({
-  appId: document.appId,
-  appName: document.appName,
-  kind: "help",
-  locale: document.locale,
-  documentId: document.documentId,
-  title: document.title,
-  description: document.description,
-});
-
-const searchScore = (document: HelpCatalogDocument, query: string): number => {
-  const phrase = normalizeSearchText(query);
-  const terms = searchTerms(query);
-  if (!phrase || terms.length === 0) return 0;
-
-  const app = normalizeSearchText(`${document.appId} ${document.appName}`);
-  const identity = normalizeSearchText(`${document.documentId} ${document.title}`);
-  const description = normalizeSearchText(document.description ?? "");
-  const body = normalizeSearchText(document.searchText);
-  let score = 0;
-  if (identity === phrase) score += 80;
-  else if (identity.includes(phrase)) score += 40;
-  if (app.includes(phrase)) score += 30;
-  if (description.includes(phrase)) score += 20;
-  if (body.includes(phrase)) score += 10;
-  for (const term of terms) {
-    if (identity.includes(term)) score += 8;
-    if (app.includes(term)) score += 6;
-    if (description.includes(term)) score += 4;
-    if (body.includes(term)) score += 1;
-  }
-  return score;
-};
-
-export const searchHelpCatalog = (
-  catalog: readonly HelpCatalogDocument[],
-  input: { query: string; appId?: string; limit?: number },
-): HelpCatalogItem[] => {
-  const limit = Math.max(1, Math.min(Math.floor(input.limit ?? 10), HELP_SEARCH_MAX_LIMIT));
-  return catalog
-    .filter((document) => !input.appId || document.appId === input.appId)
-    .map((document) => ({ document, score: searchScore(document, input.query) }))
-    .filter(({ score }) => score > 0)
-    .sort(
-      (left, right) =>
-        right.score - left.score ||
-        left.document.appId.localeCompare(right.document.appId) ||
-        left.document.documentId.localeCompare(right.document.documentId),
-    )
-    .slice(0, limit)
-    .map(({ document }) => catalogItem(document));
-};
-
-export const findHelpDocument = (catalog: readonly HelpCatalogDocument[], appId: string, documentId: string): HelpCatalogDocument | null =>
-  catalog.find((document) => document.appId === appId && document.documentId === documentId) ?? null;
+const searchTerms = (value: string): string[] => [...new Set(normalizeSearchText(value).split(" ").filter(Boolean))];
 
 const splitSections = (markdown: string): string[] => {
   const starts = [
@@ -193,7 +33,21 @@ const boundedExcerpt = (markdown: string, terms: readonly string[]): string => {
   return `${start > 0 ? `${marker}\n\n` : ""}${body}${start + budget < markdown.length ? `\n\n${marker}` : ""}`;
 };
 
-const selectMarkdown = (markdown: string, query?: string): { markdown: string; truncated: boolean } => {
+export const selectHelpMarkdown = (markdown: string, query?: string): { markdown: string; truncated: boolean } => {
+  // An exact heading identifies one complete reference section, even in short articles.
+  const headingQuery = query?.trim().toLocaleLowerCase();
+  const exact =
+    headingQuery &&
+    splitSections(markdown).find((section) => {
+      const heading = section
+        .match(/^##\s+([^\n]+)/)?.[1]
+        ?.replace(/\s*\{icon="[^"]*"\}\s*$/, "")
+        .replaceAll("`", "")
+        .trim()
+        .toLocaleLowerCase();
+      return heading === headingQuery;
+    });
+  if (exact) return { markdown: boundedExcerpt(exact, [headingQuery]), truncated: exact !== markdown };
   if (markdown.length <= HELP_READ_MAX_CHARS) return { markdown, truncated: false };
   const terms = searchTerms(query ?? "");
   const phrase = normalizeSearchText(query ?? "");
@@ -217,15 +71,16 @@ const selectMarkdown = (markdown: string, query?: string): { markdown: string; t
   return { markdown: excerpt || boundedExcerpt(markdown, terms), truncated: true };
 };
 
-export const readHelpCatalog = (
-  catalog: readonly HelpCatalogDocument[],
-  input: { appId: string; documentId: string; query?: string },
-): HelpCatalogRead | null => {
-  const document = findHelpDocument(catalog, input.appId, input.documentId);
-  if (!document) return null;
-  const selected = selectMarkdown(document.markdown, input.query);
-  return { ...catalogItem(document), ...selected };
-};
+export const readHelpArticle = (document: HelpArticle, query?: string) => ({
+  kind: "help" as const,
+  appId: document.appId,
+  appName: document.appName,
+  locale: document.locale,
+  documentId: document.documentId,
+  title: document.title,
+  description: document.description,
+  ...selectHelpMarkdown(document.markdown, query),
+});
 
 export const helpResourceUri = (appId: string, documentId: string): string =>
   `cloud://help/${encodeURIComponent(appId)}/${encodeURIComponent(documentId)}`;

package/src/_internal/help.ts

@@ -1,42 +1,15 @@
 import { createHash } from "node:crypto";
-import type { AppRegistryHelpSummary, HelpRegistryEntry } from "../contracts/registry";
+import type { AppRegistryHelpSummary } from "../contracts/registry";
 import type { HelpDefinition } from "../server/help";
-import type { HelpDocumentManifest } from "../shared/help";
+import type { HelpCorpus, HelpDocument } from "../services/help/types";
 
-export const HELP_REGISTRY_MAX_BYTES = 512 * 1024;
 export const HELP_DOCUMENT_MAX_BYTES = 128 * 1024;
+export type CompiledHelp = { summary: AppRegistryHelpSummary; corpus: HelpCorpus };
 
-export type CompiledHelp = {
-  summary: AppRegistryHelpSummary;
-  registryEntry: HelpRegistryEntry;
-};
-
-const serializedBytes = (value: unknown): number => new TextEncoder().encode(JSON.stringify(value)).byteLength;
-
-const helpHash = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-
-const omitSearchText = (documents: readonly HelpRegistryEntry["documents"][number][]) =>
-  documents.map(({ searchText: _searchText, ...document }) => document);
-
-const normalizedBasePath = (basePath: string | undefined): string => {
-  const value = basePath?.replace(/\/$/, "") ?? "";
-  return value || "";
-};
-
-export const compileHelp = (input: {
-  appId: string;
-  appName: string;
-  appIcon: string;
-  basePath?: string;
-  definition: HelpDefinition;
-}): CompiledHelp => {
-  const appId = encodeURIComponent(input.appId);
-  const pageBase = `${normalizedBasePath(input.basePath)}/help`;
-  const searchUrl = `/api/help/v1/${appId}/search`;
-  const compileDocuments = (source: readonly (typeof input.definition.documents)[number][]) =>
+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 markdownBytes = new TextEncoder().encode(markdown).byteLength;
-      if (markdownBytes > HELP_DOCUMENT_MAX_BYTES) {
+      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 };
@@ -46,50 +19,14 @@ export const compileHelp = (input: {
   const documentsByLocale = Object.fromEntries(
     Object.entries(input.definition.documentsByLocale ?? {})
       .filter(([locale]) => locale !== baseLocale)
-      .map(([locale, localized]) => [locale, compileDocuments(localized)]),
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([locale, docs]) => [locale, compileDocuments(docs)]),
   );
-  const manifestHash = helpHash({ appId: input.appId, baseLocale, documents, documentsByLocale });
-  const toManifest = (source: readonly (typeof documents)[number][]) =>
-    source.map<HelpDocumentManifest>(({ id, title, icon, description, order }) => ({
-      id,
-      title,
-      icon,
-      description,
-      order,
-      searchUrl,
-      url: `/api/help/v1/${appId}/documents/${encodeURIComponent(id)}`,
-    }));
-  const manifest = toManifest(documents);
-  const manifestByLocale = Object.fromEntries(
-    Object.entries(documentsByLocale).map(([locale, localized]) => [locale, toManifest(localized)]),
-  );
-  let registryEntry: HelpRegistryEntry = {
-    appId: input.appId,
-    appName: input.appName,
-    appIcon: input.appIcon,
-    manifestHash,
-    baseLocale,
-    documentsByLocale,
-    documents,
-  };
-  let bytes = serializedBytes(registryEntry);
-  if (bytes > HELP_REGISTRY_MAX_BYTES) {
-    registryEntry = {
-      ...registryEntry,
-      documents: omitSearchText(registryEntry.documents),
-      documentsByLocale: registryEntry.documentsByLocale
-        ? Object.fromEntries(
-            Object.entries(registryEntry.documentsByLocale).map(([locale, localized]) => [locale, omitSearchText(localized)]),
-          )
-        : undefined,
-    };
-    bytes = serializedBytes(registryEntry);
-  }
-  if (bytes > HELP_REGISTRY_MAX_BYTES) {
-    throw new Error(`Help corpus exceeds the ${HELP_REGISTRY_MAX_BYTES}-byte registry limit`);
-  }
+  const manifestHash = createHash("sha256")
+    .update(JSON.stringify({ revision: 1, appId: input.appId, baseLocale, documents, documentsByLocale }))
+    .digest("hex");
   return {
-    summary: { manifestHash, pageBase, baseLocale, documentsByLocale: manifestByLocale, documents: manifest },
-    registryEntry,
+    summary: { manifestHash, pageBase: `${input.basePath?.replace(/\/$/, "") ?? ""}/help`, baseLocale },
+    corpus: { appId: input.appId, manifestHash, baseLocale, documents, documentsByLocale },
   };
 };

package/src/_internal/page-responses.ts

@@ -1,6 +1,7 @@
 import type { HtmlFn } from "@k2b/ssr";
 import type { Context } from "hono";
 import type { ClientErrorStatusCode, ServerErrorStatusCode } from "hono/utils/http-status";
+import { preloadLayoutAnnouncements } from "../server/middleware/settings";
 import { getLocale } from "../server/locale";
 import { createLoginRedirectUrl } from "../shared/redirect";
 import type { PageOptions } from "./define-app";
@@ -21,6 +22,7 @@ export const createPageResponses = (html: HtmlFn<PageOptions>) => {
     // Auth middleware may reject before ssr() initializes page metadata.
     c.set("page", { lang: getLocale(c) });
     c.header("Cache-Control", "private, no-store");
+    await preloadLayoutAnnouncements(c);
     // Load JSX only after the application's SSR plugin has been installed.
     const { renderPageError } = await import("../ssr/PageError");
     const response = await html(renderPageError(c, status, options), c.get("page"));

package/src/_internal/postgres-application-name.ts

@@ -0,0 +1,30 @@
+/** Name Bun's default pool before its first use without changing connection ownership. */
+export const configurePostgresApplicationName = (
+  applicationId: string,
+  environment: Record<string, string | undefined> = process.env,
+): void => {
+  // Match Bun's precedence and preserve TLS_* variables, which imply required TLS.
+  const variable = ["DATABASE_URL", "DATABASEURL", "TLS_DATABASE_URL", "POSTGRES_URL", "PGURL", "PG_URL", "TLS_POSTGRES_DATABASE_URL"].find(
+    (key) => environment[key],
+  );
+  if (!variable) return;
+
+  let url: URL;
+  try {
+    url = new URL(environment[variable]!);
+  } catch {
+    // Diagnostics must not change how Bun handles an existing connection configuration.
+    return;
+  }
+  if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") return;
+
+  let operatorConfigured = false;
+  url.searchParams.forEach((_value, key) => {
+    // options can contain an operator-owned `-c application_name=...` setting.
+    if (key.toLowerCase() === "application_name" || key.toLowerCase() === "options") operatorConfigured = true;
+  });
+  if (operatorConfigured) return;
+
+  url.searchParams.set("application_name", `cloud:${applicationId}`);
+  environment[variable] = url.toString();
+};

package/src/_internal/process-identity.ts

@@ -0,0 +1,15 @@
+/** Identity of the application started in this process, derived from its declaration. */
+let applicationId: string | undefined;
+
+export const getProcessApplicationId = (): string | undefined => applicationId;
+
+export const bindProcessApplicationId = (id: string): void => {
+  if (applicationId !== undefined && applicationId !== id) {
+    throw new Error(`This process already hosts application "${applicationId}"`);
+  }
+  applicationId = id;
+};
+
+export const clearProcessApplicationId = (): void => {
+  applicationId = undefined;
+};

package/src/_internal/process-sync.ts

@@ -82,7 +82,7 @@ export const startProcessSync = async ({ application }: { application: string })
         connection,
         namespace: env.SYNC_NAMESPACE,
         application,
-        defaults: { replicas: 3 },
+        defaults: { replicas: env.SYNC_REPLICAS },
         observe: (event) => observeSyncEvent(event, application),
       });
       bindProcessSync(sync);

package/src/_internal/registry-validation.ts

@@ -39,11 +39,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     }
     for (const [locale, translation] of Object.entries(value.presentation.translations)) {
       if (!isRecord(translation)) return invalid(`presentation.translations.${locale}`, "an object");
-      if (translation.name !== undefined && !isString(translation.name)) return invalid(`presentation.translations.${locale}.name`, "a string");
+      if (translation.name !== undefined && !isString(translation.name))
+        return invalid(`presentation.translations.${locale}.name`, "a string");
       if (translation.description !== undefined && !isString(translation.description)) {
         return invalid(`presentation.translations.${locale}.description`, "a string");
       }
-      for (const field of ["adminGroups", "adminLinks", "legalLinks"] as const) {
+      for (const field of ["adminGroups", "adminLinks", "legalLinks", "searchLinks", "searchLinkDescriptions"] as const) {
         if (translation[field] !== undefined && !isStringRecord(translation[field])) {
           return invalid(`presentation.translations.${locale}.${field}`, "a string map");
         }
@@ -66,6 +67,7 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
         (group) =>
           !isRecord(group) ||
           (group.id !== undefined && !isString(group.id)) ||
+          (group.section !== undefined && group.section !== "ai") ||
           !isString(group.label) ||
           !Array.isArray(group.links) ||
           group.links.some((link) => !isRecord(link) || !isString(link.label) || !isString(link.href) || !isString(link.icon)),
@@ -84,6 +86,23 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("legalLinks", "an array of valid links");
     }
   }
+  if (value.searchLinks !== undefined) {
+    if (
+      !Array.isArray(value.searchLinks) ||
+      value.searchLinks.some(
+        (link) =>
+          !isRecord(link) ||
+          !isString(link.label) ||
+          !link.label.trim() ||
+          (link.description !== undefined && !isString(link.description)) ||
+          !isString(link.href) ||
+          !/^\/(?![\/\\])[^\\\s]*$/.test(link.href) ||
+          (link.icon !== undefined && !isString(link.icon)) ||
+          (link.keywords !== undefined && !isStringArray(link.keywords)),
+      )
+    )
+      return invalid("searchLinks", "an array of same-origin navigation links");
+  }
   if (value.widgets !== undefined) {
     if (
       !Array.isArray(value.widgets) ||
@@ -102,32 +121,17 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("capabilities", "a valid capability summary");
     }
   }
-  if (value.help !== undefined) {
-    if (
-      !isRecord(value.help) ||
+  if (
+    value.help !== undefined &&
+    (!isRecord(value.help) ||
       !isString(value.help.manifestHash) ||
+      !isString(value.help.baseLocale) ||
       !isString(value.help.pageBase) ||
-      !Array.isArray(value.help.documents)
-    ) {
-      return invalid("help", "a valid Help summary");
-    }
-    if (
-      !value.help.pageBase.startsWith("/") ||
-      value.help.documents.some(
-        (document) =>
-          !isRecord(document) ||
-          !isString(document.id) ||
-          !isString(document.title) ||
-          typeof document.order !== "number" ||
-          !isString(document.searchUrl) ||
-          !document.searchUrl.startsWith("/") ||
-          !isString(document.url) ||
-          !document.url.startsWith("/"),
-      )
-    ) {
-      return invalid("help", "a valid Help summary");
-    }
+      !value.help.pageBase.startsWith("/"))
+  ) {
+    return invalid("help", "a valid Help reference");
   }
+
   if (value.openapi !== undefined && !isString(value.openapi)) return invalid("openapi", "a string");
   return null;
 };

package/src/_internal/registry.ts

@@ -1,7 +1,7 @@
 import type { EphemeralConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
-import type { AppRegistryEntry, CapabilityRegistryEntry, HelpRegistryEntry } from "../contracts/registry";
+import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import type { DashboardWidgetPresentation } from "../contracts/widgets";
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
@@ -10,7 +10,7 @@ import { validateAppRegistryEntry } from "./registry-validation";
 import { watchRegistryChanges } from "./registry-watch";
 
 /**
- * Shared app registry: three @k2b/sync ephemerals on the process Sync
+ * Shared app registry: two @k2b/sync ephemerals on the process Sync
  * instance. Apps, the gateway, and gateway-ops all declare them through the
  * functions below, so id, owner, TTL, and value bound stay identical across
  * the fleet (a differing declaration fails with ResourceDriftError).
@@ -34,20 +34,12 @@ export const CAPABILITY_REGISTRY_CONFIG = {
   maxValueBytes: 512 * 1024,
 } as const satisfies EphemeralConfig;
 
-export const HELP_REGISTRY_CONFIG = {
-  id: "cloud-help",
-  owner: REGISTRY_OWNER,
-  ttlMs: APP_REGISTRY_TTL_MS,
-  maxValueBytes: 512 * 1024,
-} as const satisfies EphemeralConfig;
-
 export const APP_REGISTRY_PREFIX = "apps/";
 
 export type CapabilityRegistryRecord = { appId: string; manifest: CapabilityManifest; presentation?: CapabilityPresentationCatalog };
 
 export const appRegistry = lazySync((sync) => sync.ephemeral<AppRegistryEntry>(APP_REGISTRY_CONFIG));
 export const capabilityRegistry = lazySync((sync) => sync.ephemeral<CapabilityRegistryRecord>(CAPABILITY_REGISTRY_CONFIG));
-export const helpRegistry = lazySync((sync) => sync.ephemeral<HelpRegistryEntry>(HELP_REGISTRY_CONFIG));
 
 /**
  * Follow the app registry until `signal` aborts. The watch first replays the
@@ -232,49 +224,6 @@ export const getCapability = async (appId: string): Promise<CapabilityRegistryEn
   return entry ? resolveLiveCapabilityRegistryEntry(entry.key, entry.value, app ?? undefined) : null;
 };
 
-const isHelpRegistryEntry = (value: unknown): value is HelpRegistryEntry => {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const entry = value as Partial<HelpRegistryEntry>;
-  const validDocument = (document: unknown) =>
-    !!document &&
-    typeof document === "object" &&
-    typeof (document as { id?: unknown }).id === "string" &&
-    typeof (document as { title?: unknown }).title === "string" &&
-    typeof (document as { order?: unknown }).order === "number" &&
-    typeof (document as { markdown?: unknown }).markdown === "string" &&
-    ((document as { searchText?: unknown }).searchText === undefined ||
-      typeof (document as { searchText?: unknown }).searchText === "string") &&
-    ((document as { icon?: unknown }).icon === undefined || typeof (document as { icon?: unknown }).icon === "string") &&
-    ((document as { description?: unknown }).description === undefined ||
-      typeof (document as { description?: unknown }).description === "string");
-  return (
-    typeof entry.appId === "string" &&
-    typeof entry.appName === "string" &&
-    typeof entry.appIcon === "string" &&
-    typeof entry.manifestHash === "string" &&
-    (entry.baseLocale === undefined || typeof entry.baseLocale === "string") &&
-    Array.isArray(entry.documents) &&
-    entry.documents.every(validDocument) &&
-    (entry.documentsByLocale === undefined ||
-      (!!entry.documentsByLocale &&
-        typeof entry.documentsByLocale === "object" &&
-        !Array.isArray(entry.documentsByLocale) &&
-        Object.values(entry.documentsByLocale).every((documents) => Array.isArray(documents) && documents.every(validDocument))))
-  );
-};
-
-export const listHelp = async (): Promise<HelpRegistryEntry[]> => {
-  const snap = await helpRegistry().snapshot({ prefix: "help/" });
-  return snap.entries.map((entry) => entry.value).filter(isHelpRegistryEntry);
-};
-
-export const getHelp = async (appId: string): Promise<HelpRegistryEntry | null> => {
-  const key = `help/${appId}`;
-  const snap = await helpRegistry().snapshot({ prefix: key });
-  const value = snap.entries.find((entry) => entry.key === key)?.value;
-  return isHelpRegistryEntry(value) ? value : null;
-};
-
 /**
  * Same as `listApps` but returns registry metadata for admin observability.
  */

package/src/_internal/runtime-context.ts

@@ -29,6 +29,8 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
                   adminGroups: translation.adminGroups ? { ...translation.adminGroups } : undefined,
                   adminLinks: translation.adminLinks ? { ...translation.adminLinks } : undefined,
                   legalLinks: translation.legalLinks ? { ...translation.legalLinks } : undefined,
+                  searchLinks: translation.searchLinks ? { ...translation.searchLinks } : undefined,
+                  searchLinkDescriptions: translation.searchLinkDescriptions ? { ...translation.searchLinkDescriptions } : undefined,
                 },
               ]),
             ),
@@ -37,6 +39,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
       appearance: e.appearance,
       adminHref: e.nav?.adminHref,
       adminNav: e.adminNav?.map((group) => ({
+        ...(group.section ? {section:group.section} : {}),
         id: group.id,
         label: group.label,
         links: group.links.map((link) => ({ ...link })),
@@ -53,22 +56,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
             requiresRoles: e.nav.requiresRoles as Role[] | undefined,
           }
         : undefined,
-      help: e.help
-        ? {
-            manifestHash: e.help.manifestHash,
-            pageBase: e.help.pageBase,
-            baseLocale: e.help.baseLocale,
-            documentsByLocale: e.help.documentsByLocale
-              ? Object.fromEntries(
-                  Object.entries(e.help.documentsByLocale).map(([locale, documents]) => [
-                    locale,
-                    documents.map((document) => ({ ...document })),
-                  ]),
-                )
-              : undefined,
-            documents: e.help.documents.map((document) => ({ ...document })),
-          }
-        : undefined,
+      help: e.help ? { ...e.help } : undefined,
       searchTags,
       searchHelp: searchQueries?.map((query) => query.description).join(" "),
       searchTagHelp: searchQueries?.flatMap((query) =>
@@ -78,6 +66,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
         ]),
       ),
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
+      searchLinks: e.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
       openapi: e.openapi,
     };
   }),

package/src/_internal/server-timing.ts

@@ -0,0 +1,13 @@
+import type { Context } from "hono";
+
+type Phase = "auth" | "settings" | "runtime" | "ssr_data" | "ssr_finalize" | "ssr_render";
+
+/** Measure the owning operation, not downstream middleware or another request. */
+export async function measureServerPhase<T>(c: Context, phase: Phase, operation: () => T | Promise<T>): Promise<T> {
+  const start = performance.now();
+  try {
+    return await operation();
+  } finally {
+    c.header("Server-Timing", `${phase};dur=${(performance.now() - start).toFixed(2)}`, { append: true });
+  }
+}