@k2b/cloud 0.22.0 → 0.24.0

package/src/_internal/define-app.ts

@@ -1,3 +1,4 @@
+import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
 import { invokeCapabilityStream } from "./capability-streams";
@@ -26,6 +27,7 @@ import type {
   AppLifecycle,
   AppMeta,
   AppPresentationCatalog,
+  AppPwaPart,
   AppSearchLink,
   CloudLifecycleContext,
   WidgetEndpoint,
@@ -38,6 +40,7 @@ import {
   CapabilityOriginSchema,
 } from "../contracts/capabilities";
 import { type BoundNotificationMap, bindNotificationDefinitions, type NotificationDefinitionMap } from "../contracts/notification-types";
+import { isPwaPartId, PWA_AUTH_PATH, PWA_CANVAS_COLORS, PWA_MANIFEST_PATH, PWA_SHELL_APP_ID } from "../contracts/pwa";
 import type { AppRegistryEntry } from "../contracts/registry";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
 import type { Role } from "../contracts/shared";
@@ -59,6 +62,7 @@ import { normalizeInvocationRequestId } from "../services/identity/invocation-to
 import { logger } from "../services/logging";
 import { startNotificationDefinitionRegistration } from "../services/notifications/catalog";
 import { readRailSnapshot } from "../services/rail-snapshot";
+import { isAppPagePath } from "../services/session";
 import { get, loadCache as loadSettingsCache, set } from "../services/settings";
 import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
 import { registerSettings, toLegacySettingDefs } from "../services/settings/defaults";
@@ -95,6 +99,8 @@ export type PageOptions = {
   theme?: "light" | "dark";
   /** Framework-resolved BCP 47 document language — always the canonical request locale, never a page override. */
   lang?: string;
+  /** Renders the document as a page of the installable mobile app; set by `PwaLayout`. */
+  pwa?: { name: string };
 };
 
 type ResolvedPageOptions = PageOptions & { performanceRoute?: string };
@@ -162,6 +168,16 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   legalLinks?: ReadonlyArray<{ label: string; href: string; icon?: string }>;
   /** Static destinations for the global search UI; no capabilities are created. */
   searchLinks?: readonly AppSearchLink[];
+  /**
+   * Preview: pages of this app in the installable mobile app. Declaring it adds
+   * `/pwa/<id>` to the gateway routes and lists the app in the mobile app,
+   * with its name, icon and description. Serve the pages below `/pwa/<id>`
+   * with `PwaLayout` and `ssr.pwaAccess`. `routes` never lists `/pwa` paths.
+   */
+  pwa?: {
+    /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
+    requiresRoles?: Role[];
+  };
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP path on this app that returns a `WidgetResponse`. The dashboard
@@ -312,6 +328,32 @@ export type AppDefinition<S extends AppSettingsMap = {}, N extends NotificationD
 
 // ── Implementation ──────────────────────────────────────────────────────────
 
+const isPwaPath = (route: string): boolean => route === "/pwa" || route.startsWith("/pwa/");
+/** A route as the gateway reads it: trimmed and without empty segments, so `//pwa/x/` is `/pwa/x`. */
+const canonicalRoute = (route: string): string => {
+  const trimmed = route.trim();
+  return trimmed.startsWith("/") ? `/${trimmed.split("/").filter(Boolean).join("/")}` : trimmed;
+};
+
+/**
+ * `/pwa` belongs to the mobile app shell, `/pwa/_auth` to Core, and `/pwa/<id>`
+ * to the app that declares `pwa`. A part never claims a path by hand, so no app
+ * can take the shell's pages or another app's part.
+ */
+const validateAppPwaPart = (opts: Pick<AppOptions, "id" | "routes" | "pwa">): AppPwaPart | undefined => {
+  for (const route of opts.routes) {
+    const path = canonicalRoute(route);
+    if (!isPwaPath(path)) continue;
+    if ((path === "/pwa" && opts.id === PWA_SHELL_APP_ID) || (path === PWA_AUTH_PATH && opts.id === "core")) continue;
+    throw new Error(`App "${opts.id}" lists route "${route}"; /pwa is reserved for the mobile app, declare pwa: {} to get /pwa/${opts.id}`);
+  }
+  if (!opts.pwa) return undefined;
+  if (!isPwaPartId(opts.id)) {
+    throw new Error(`App "${opts.id}" cannot declare pwa; a part needs a plain id other than pwa, settings and offline`);
+  }
+  return { href: `/pwa/${opts.id}`, requiresRoles: opts.pwa.requiresRoles ? [...opts.pwa.requiresRoles] : undefined };
+};
+
 export const defineApp = <
   const S extends AppSettingsMap = {},
   const N extends NotificationDefinitionMap = {},
@@ -323,6 +365,7 @@ export const defineApp = <
   const isDevelopment = env.IS_DEVELOPMENT;
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
   const cliModules = validateAppCliModules(opts.id, opts.cli);
+  const pwaPart = validateAppPwaPart(opts);
 
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
@@ -341,19 +384,43 @@ export const defineApp = <
     rootDir,
     componentRoots: [resolve(env.APP_DIR ?? rootDir, "src"), fileURLToPath(new URL("../", import.meta.url))],
     basePath: opts.basePath,
-    template: ({ body, scripts, title, description, theme, lang, performanceRoute }) => {
+    template: ({ body, scripts, title, description, theme, lang, performanceRoute, pwa }) => {
       const themeFixed = theme !== undefined;
+      // App pages paint the canvas before any stylesheet and give it to the
+      // status bar. No status-bar style: `black-translucent` lays a blur band
+      // over the top edge on iOS 26.
+      const canvas = PWA_CANVAS_COLORS[theme ?? "light"];
+      const head = pwa
+        ? {
+            html: ` style="background-color:${canvas}"`,
+            viewport: "width=device-width, initial-scale=1, viewport-fit=cover",
+            app: `<meta name="theme-color" content="${canvas}">
+    <link rel="manifest" href="${PWA_MANIFEST_PATH}">
+    <link rel="apple-touch-icon" href="/branding/apple-touch-icon.png">
+    <meta name="apple-mobile-web-app-title" content="${escapeHtml(pwa.name)}">`,
+            // The web cross-fades between pages; an app page swaps at once. The browser ignores taps while a
+            // cross-document transition runs, so a tab tap right after the last one would be lost. After
+            // global.css, whose `navigation: auto` it overrides.
+            styles: `
+    <style data-cloud-app-navigation>@view-transition{navigation:none}</style>`,
+          }
+        : {
+            html: "",
+            viewport: "width=device-width, initial-scale=1.0",
+            app: `<meta name="theme-color" content="#09090b">
+    <meta name="mobile-web-app-capable" content="yes">`,
+            styles: "",
+          };
       // 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">
+<html lang="${normalizeLocale(lang)}" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}${head.html}>
+  <head><meta charset="UTF-8"><meta name="viewport" content="${head.viewport}">
     <meta name="view-transition" content="same-origin">
     <title>${escapeHtml(title ?? "Cloud")}</title>
     <meta name="description" content="${escapeHtml(description ?? "Cloud workspace")}">
-    <meta name="theme-color" content="#09090b">
-    <meta name="mobile-web-app-capable" content="yes">
+    ${head.app}
     <link rel="icon" href="${appFaviconHref(opts.id, v)}">
     <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>
@@ -361,7 +428,7 @@ export const defineApp = <
     <link rel="stylesheet" href="/public/fonts.css?v=${v}">
     <link rel="stylesheet" href="/public/tabler-icons.css?v=${v}">
     <link rel="stylesheet" href="/public/${opts.id}/app.css?v=${v}">
-    <link rel="stylesheet" href="/public/global.css?v=${v}">
+    <link rel="stylesheet" href="/public/global.css?v=${v}">${head.styles}
     <script>${themeBootstrapScript}</script>
   </head>
   <body class="k2b-ui" data-k2b-app-workspace-controller="global">
@@ -389,6 +456,9 @@ export const defineApp = <
       const user = c.get("user");
       c.get("page").performanceRoute =
         user && c.get("settings")?.observability?.web_vitals?.enabled === true ? (matchedRouteTemplate(c) ?? undefined) : undefined;
+      // Pages of the mobile app render in PwaLayout, which shows no announcements, Help, or rail; reading them would
+      // only delay every tab switch. Core's pages below /pwa/_auth, such as its not-found page, keep the web layout.
+      if (isAppPagePath(c.req.path)) return;
       await Promise.all([
         preloadLayoutAnnouncements(c),
         preloadLayoutHelp(c),
@@ -414,10 +484,11 @@ export const defineApp = <
         links: group.links.map((link) => ({ ...link })),
       }),
     ),
-    routes: [...opts.routes, ...cliPluginRoutePrefixes(cliModules)],
+    routes: [...opts.routes, ...cliPluginRoutePrefixes(cliModules), ...(pwaPart ? [pwaPart.href] : [])],
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
+    pwa: pwaPart,
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
@@ -512,6 +583,9 @@ export const defineApp = <
         help: compiledHelp?.summary,
         legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
         searchLinks: meta.searchLinks,
+        pwa: meta.pwa
+          ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
+          : undefined,
         widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
@@ -812,10 +886,19 @@ export const defineApp = <
       const stopLifecycle = startOpts.lifecycle?.stop;
       if (stopLifecycle) cleanup.push(() => stopLifecycle(cloudCtx));
 
+      const startOutbox = async () => {
+        const stopLiveOutbox = await startLiveOutbox(meta.id);
+        if (stopLiveOutbox) cleanup.push(stopLiveOutbox);
+      };
+      // An application fails before any setup when Core has not created the platform outbox yet.
+      // Core creates it in its own setup, so it starts publishing after that.
+      if (meta.id !== "core") await startOutbox();
+
       if (!startOpts.skipSetup && startOpts.lifecycle?.setup) {
         log.info(`Setup: ${meta.id}`);
         await startOpts.lifecycle.setup(cloudCtx);
       }
+      if (meta.id === "core") await startOutbox();
 
       stopNotificationRegistration = await startNotificationDefinitionRegistration(meta.id, notifications);