@k2b/cloud 0.6.0 → 0.8.0

package/src/_internal/define-app.ts

@@ -1,3 +1,7 @@
+import { registerHelp } from "../services/help";
+import { preloadLayoutHelp } from "../ssr/help";
+import { invokeCapabilityStream } from "./capability-streams";
+import { bindProcessApplicationId, clearProcessApplicationId } from "./process-identity";
 /**
  * defineApp() — The single entry point for every cloud app.
  *
@@ -5,6 +9,8 @@
  * Returns `{ ssr, plugin, config, meta, start }`.
  */
 
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { SsrConfig } from "@k2b/ssr";
 import { createConfig as createSsrConfig } from "@k2b/ssr";
 import { routes } from "@k2b/ssr/hono";
@@ -18,10 +24,17 @@ import type {
   AppLifecycle,
   AppMeta,
   AppPresentationCatalog,
+  AppSearchLink,
   CloudLifecycleContext,
   WidgetEndpoint,
 } from "../contracts/app";
-import { CAPABILITY_FRAMEWORK_ERROR_CODES, CAPABILITY_MAX_REQUEST_BYTES, type CapabilityDefinitions } from "../contracts/capabilities";
+import {
+  CAPABILITY_FRAMEWORK_ERROR_CODES,
+  CAPABILITY_MAX_REQUEST_BYTES,
+  CAPABILITY_ORIGIN_HEADER,
+  type CapabilityDefinitions,
+  CapabilityOriginSchema,
+} from "../contracts/capabilities";
 import { type BoundNotificationMap, bindNotificationDefinitions, type NotificationDefinitionMap } from "../contracts/notification-types";
 import type { AppRegistryEntry } from "../contracts/registry";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
@@ -30,18 +43,19 @@ import type { HelpDefinition } from "../server/help";
 import { getLocale, resolveLocale } from "../server/locale";
 import { type AuthContext, auth } from "../server/middleware/auth";
 import { requireInvocation } from "../server/middleware/invocation";
-import { routeTemplate } from "../server/middleware/route-template";
+import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-template";
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
-import { settings as settingsMiddleware } from "../server/middleware/settings";
+import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
 import {
   capabilityInvocationOperation,
   searchInvocationOperation,
   syncInvocationOperation,
   widgetInvocationOperation,
 } from "../services/identity/invocation-operations";
+import { normalizeInvocationRequestId } from "../services/identity/invocation-token";
 import { logger } from "../services/logging";
 import { startNotificationDefinitionRegistration } from "../services/notifications/catalog";
-import { railPreferences } from "../services/rail-preferences";
+import { readRailSnapshot } from "../services/rail-snapshot";
 import { get, loadCache as loadSettingsCache, set } from "../services/settings";
 import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
 import { registerSettings, toLegacySettingDefs } from "../services/settings/defaults";
@@ -58,12 +72,14 @@ import { compileCapabilities, invokeCompiledCapability, reviewCompiledCapability
 import { createHeartbeat } from "./heartbeat";
 import { compileHelp } from "./help";
 import { createPageResponses } from "./page-responses";
+import { configurePostgresApplicationName } from "./postgres-application-name";
 import { getProcessSync, startProcessSync } from "./process-sync";
 import { APP_READINESS_PATH, appReadinessResponse } from "./readiness";
-import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry, helpRegistry } from "./registry";
+import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
 import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 import { servePublicAsset } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
+import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
 
 /** Cache-busting version stamp — changes on every server start / rebuild. */
 const v = Date.now();
@@ -76,6 +92,8 @@ export type PageOptions = {
   lang?: string;
 };
 
+type ResolvedPageOptions = PageOptions & { performanceRoute?: string };
+
 // ── Public types ────────────────────────────────────────────────────────────
 
 /**
@@ -103,6 +121,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   adminHref?: string;
   /** Multi-link admin navigation contributed by this app. */
   adminNav?: ReadonlyArray<{
+    section?: "ai";
     id?: string;
     label: string;
     links: ReadonlyArray<{ label: string; href: string; icon: string }>;
@@ -136,6 +155,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
    * always open in a new tab from the login footer.
    */
   legalLinks?: ReadonlyArray<{ label: string; href: string; icon?: string }>;
+  /** Static destinations for the global search UI; no capabilities are created. */
+  searchLinks?: readonly AppSearchLink[];
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP path on this app that returns a `WidgetResponse`. The dashboard
@@ -177,9 +198,10 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
    */
   openapi?: string;
   /**
-   * Project root used by the SSR plugin to discover island/client files.
+   * Project root used for SSR component IDs and development assets.
    * Defaults to `process.cwd()`. Override only if you run the entrypoint
-   * from a directory other than the project root.
+   * from a directory other than the project root. Discovery uses APP_DIR/src
+   * (or appRoot/src) plus the installed Cloud framework source.
    */
   appRoot?: string;
 };
@@ -280,7 +302,8 @@ export const defineApp = <
 >(
   opts: AppOptions<S, N, AppId>,
 ): AppDefinition<S, N, AppId> => {
-  const isDevelopment = process.env.NODE_ENV === "development";
+  configurePostgresApplicationName(opts.id);
+  const isDevelopment = env.IS_DEVELOPMENT;
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
 
   // ── 0. Register declared settings into the runtime registry ──────────
@@ -293,12 +316,14 @@ export const defineApp = <
   }
 
   // ── 1. SSR config ─────────────────────────────────────────────────────
-  const { config, plugin, html } = createSsrConfig<PageOptions>({
+  const rootDir = opts.appRoot ?? process.cwd();
+  const { config, plugin, html } = createSsrConfig<ResolvedPageOptions>({
     dev: isDevelopment,
     verbose: true,
-    rootDir: opts.appRoot ?? process.cwd(),
+    rootDir,
+    componentRoots: [resolve(env.APP_DIR ?? rootDir, "src"), fileURLToPath(new URL("../", import.meta.url))],
     basePath: opts.basePath,
-    template: ({ body, scripts, title, description, theme, lang }) => {
+    template: ({ body, scripts, title, description, theme, lang, performanceRoute }) => {
       const themeFixed = theme !== undefined;
       return `<!DOCTYPE html>
 <html lang="${normalizeLocale(lang)}" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}>
@@ -321,6 +346,7 @@ export const defineApp = <
     ${body}
   </body>
   ${scripts}
+  ${performanceRoute ? `<script type="module" src="${WEB_VITALS_ASSET_HREF}" data-cloud-web-vitals data-app-id="${escapeHtml(opts.id)}" data-route-template="${escapeHtml(performanceRoute)}"></script>` : ""}
 </html>`;
     },
   });
@@ -336,10 +362,16 @@ export const defineApp = <
   // `getDateConfig` share one canonical `getLocale(c)` that page handlers
   // cannot override.
   const ssr = Object.assign(
-    createStatusPreservingSsrHandler<PageOptions>(html, async (c) => {
+    createStatusPreservingSsrHandler<ResolvedPageOptions>(html, async (c) => {
       c.get("page").lang = getLocale(c);
       const user = c.get("user");
-      if (user) c.set("railPreferences", await railPreferences.get(user.id));
+      c.get("page").performanceRoute =
+        user && c.get("settings")?.observability?.web_vitals?.enabled === true ? (matchedRouteTemplate(c) ?? undefined) : undefined;
+      await Promise.all([
+        preloadLayoutAnnouncements(c),
+        preloadLayoutHelp(c),
+        user ? readRailSnapshot(user).then((snapshot) => c.set("railPreferences", snapshot)) : undefined,
+      ]);
     }),
     createPageResponses(html),
   );
@@ -354,6 +386,7 @@ export const defineApp = <
     adminHref: opts.adminHref,
     adminNav: opts.adminNav?.map(
       (group): AppAdminNavigationGroup => ({
+        ...(group.section ? { section: group.section } : {}),
         id: group.id,
         label: group.label,
         links: group.links.map((link) => ({ ...link })),
@@ -362,6 +395,7 @@ export const defineApp = <
     routes: [...opts.routes],
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
+    searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
@@ -400,6 +434,8 @@ export const defineApp = <
         }
       })());
     try {
+      bindProcessApplicationId(meta.id);
+      cleanup.unshift(clearProcessApplicationId);
       const startedAt = Date.now();
 
       // OpenAPI advertised in the registry only when there's a router to
@@ -410,8 +446,6 @@ export const defineApp = <
       const compiledHelp = startOpts.help
         ? compileHelp({
             appId: meta.id,
-            appName: meta.name,
-            appIcon: meta.icon,
             basePath: opts.basePath,
             definition: startOpts.help,
           })
@@ -441,6 +475,7 @@ export const defineApp = <
               }
             : undefined,
         adminNav: meta.adminNav?.map((group) => ({
+          ...(group.section ? { section: group.section } : {}),
           id: group.id,
           label: group.label,
           links: group.links.map((link) => ({ ...link })),
@@ -453,6 +488,7 @@ export const defineApp = <
           : undefined,
         help: compiledHelp?.summary,
         legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
+        searchLinks: meta.searchLinks,
         widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
@@ -461,6 +497,7 @@ export const defineApp = <
       // Heartbeat
       const heartbeat = createHeartbeat(meta.id, entry, {
         registry: appRegistry(),
+        beforeWrite: compiledHelp ? () => registerHelp(compiledHelp.corpus) : undefined,
         onError: (error) =>
           log.error("Registry heartbeat failed", {
             appId: meta.id,
@@ -499,27 +536,6 @@ export const defineApp = <
             },
           })
         : undefined;
-      const helpHeartbeat = compiledHelp
-        ? createHeartbeat(meta.id, compiledHelp.registryEntry, {
-            key: `help/${meta.id}`,
-            registry: helpRegistry(),
-            onError: (error) =>
-              log.error("Help registry heartbeat failed", {
-                appId: meta.id,
-                error: error instanceof Error ? error.message : String(error),
-              }),
-            onStale: (error) => {
-              log.error("Help registry lease expired; restarting", {
-                appId: meta.id,
-                error: error instanceof Error ? error.message : String(error),
-              });
-              process.exit(1);
-            },
-          })
-        : undefined;
-      cleanup.push(async () => {
-        await helpHeartbeat?.stop();
-      });
       cleanup.push(async () => {
         await capabilityHeartbeat?.stop();
       });
@@ -614,6 +630,8 @@ export const defineApp = <
               user,
               idempotencyKey,
               locale: requestLocale,
+              requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(),
+              origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)),
               signal: c.req.raw.signal,
             },
             onUnexpectedError: (error: unknown) =>
@@ -654,6 +672,32 @@ export const defineApp = <
               schemaHash: operation.manifest.schemaHash,
             };
           });
+        for (const kind of ["queries", "actions"] as const) {
+          server.post(
+            `/api/_internal/capabilities/v1/streams/${kind}/:capabilityId/:verb`,
+            capabilityAuth(kind),
+            auth.requireOAuthScope(kind === "queries" ? "read" : "write", "admin"),
+            async (c) => {
+              const actor = c.get("actor");
+              return invokeCapabilityStream({
+                compiled: compiledCapabilities,
+                kind,
+                localId: c.req.param("capabilityId") ?? "",
+                verb: c.req.param("verb") ?? "",
+                request: c.req.raw,
+                context: {
+                  actor,
+                  accessSubject: c.get("accessSubject"),
+                  user: actor.kind === "user" ? actor.user : actor.delegatedUser,
+                  locale: resolveLocale(c.req.raw.headers, await get<string>("app.locale")),
+                  requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(),
+                  origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)),
+                  signal: c.req.raw.signal,
+                },
+              });
+            },
+          );
+        }
         const capabilityReadScope = auth.requireOAuthScope("read", "admin");
         const capabilityWriteScope = auth.requireOAuthScope("write", "admin");
         server.post("/api/_internal/capabilities/v1/queries/:capabilityId", capabilityAuth("queries"), capabilityReadScope, (c) =>
@@ -759,7 +803,6 @@ export const defineApp = <
 
       // Only advertise after setup, workers, and their declared resources are ready.
       // Publish supporting entries first; the app entry makes them discoverable.
-      await helpHeartbeat?.start();
       await capabilityHeartbeat?.start();
       await heartbeat.start();
       log.info(`Registered "${meta.id}"`, { baseUrl });

package/src/_internal/heartbeat.ts

@@ -18,6 +18,8 @@ type HeartbeatRegistry<T> = {
 type HeartbeatOptions<T> = {
   registry: HeartbeatRegistry<T>;
   key?: string;
+  /** Publish dependent data before advertising or renewing the app. */
+  beforeWrite?: () => Promise<void>;
   intervalMs?: number;
   retryMs?: number;
   staleAfterMs?: number;
@@ -53,6 +55,7 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
   };
 
   const register = async (): Promise<void> => {
+    await options.beforeWrite?.();
     await registry.upsert({ key, value: entry });
     noteSuccess();
   };
@@ -61,6 +64,7 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
     // Touch renews the existing entry (and emits a registry invalidation).
     // Avoid rebuilding the manifest here. A missing entry is repaired
     // immediately, preserving restart-free registry recovery.
+    await options.beforeWrite?.();
     const touched = await registry.touch({ key });
     if (!touched) await registry.upsert({ key, value: entry });
     noteSuccess();

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

@@ -2,6 +2,7 @@ import type { HtmlFn } from "@k2b/ssr";
 import type { Context } from "hono";
 import type { ClientErrorStatusCode, ServerErrorStatusCode } from "hono/utils/http-status";
 import { getLocale } from "../server/locale";
+import { preloadLayoutAnnouncements } from "../server/middleware/settings";
 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"));