@k2b/cloud 0.42.0 → 0.44.0

package/src/_internal/define-app.ts

@@ -1,10 +1,18 @@
 import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, validateAppSkillCatalog } from "../ai/app-skills";
+import { createOwnedAppAccessRoutes } from "../api/app-access";
+import { createAppEventDeliveryRoutes } from "../api/app-event-delivery";
+import { createResourceAppAccessRoutes } from "../api/app-resource-access";
 import { type AppAccessDeclaration, compileAppAccess } from "../contracts/app-access";
+import { startAppEventDelivery } from "../events/app-event-delivery";
+import { bindAppEvents } from "../events/app-events";
 import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
 import { registerPageSwap } from "../ssr/page-swap";
 import { preloadPanelConsent } from "../ssr/panel-consent";
+import { appAccessManagementPath } from "./app-access-path";
+import { bindResourceAppAccess, RESOURCE_ACCESS_PATH } from "./app-access-resources";
+import { registerApplicationPackage, resolveApplicationPackage } from "./application-package";
 import { invokeCapabilityStream } from "./capability-streams";
 import { withCapabilityRequestTimeout } from "./capability-timeout";
 import { bindProcessApplicationId, clearProcessApplicationId } from "./process-identity";
@@ -17,7 +25,7 @@ import { bindProcessApplicationId, clearProcessApplicationId } from "./process-i
 
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { SsrConfig } from "@k2b/ssr";
+import type { HtmlFn, SsrConfig } from "@k2b/ssr";
 import { createConfig as createSsrConfig } from "@k2b/ssr";
 import { routes } from "@k2b/ssr/hono";
 import type { Sync } from "@k2b/sync";
@@ -26,6 +34,7 @@ import { generateSpecs } from "hono-openapi";
 import { CLOUD_CLI_PLUGIN_ROUTE } from "../cli/plugin";
 import { env } from "../config/env";
 import type {
+  AppAdminArea,
   AppAdminNavigationGroup,
   AppAppearance,
   AppCliModules,
@@ -44,9 +53,11 @@ import {
   type CapabilityDefinitions,
   CapabilityOriginSchema,
 } from "../contracts/capabilities";
+import { type AppInstallable, installableContains, validateInstallable } from "../contracts/installable";
 import { type BoundNotificationMap, bindNotificationDefinitions, type NotificationDefinitionMap } from "../contracts/notification-types";
 import { type PlatformPermission, PlatformPermissionSchema } from "../contracts/outgoing-mail";
 import { isPwaPartId, PWA_AUTH_PATH, PWA_CANVAS_COLORS, PWA_MANIFEST_PATH, PWA_SHELL_APP_ID } from "../contracts/pwa";
+import { rememberedPwaAddress } from "../contracts/pwa-location";
 import type { AppRegistryEntry } from "../contracts/registry";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
 import type { Role } from "../contracts/shared";
@@ -56,6 +67,7 @@ import { requireAppAccess, stopAppAccessConnections } from "../server/middleware
 import { type AuthContext, auth } from "../server/middleware/auth";
 import { requireInvocation } from "../server/middleware/invocation";
 import "../events/app-access";
+import { createNestedCapabilityQuery } from "../capabilities/nested";
 import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-template";
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
 import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
@@ -92,6 +104,8 @@ import { FONT_PRELOAD_LINKS } from "./font-preloads";
 import { createHeartbeat, createRegistryMembership } from "./heartbeat";
 import { compileHelp } from "./help";
 import { createHttpDrain } from "./http-drain";
+import { createInstallableRoutes } from "./installable-assets";
+import { installableHead, installableThemeScript } from "./installable-head";
 import { createPageResponses } from "./page-responses";
 import { configurePostgresApplicationName } from "./postgres-application-name";
 import { getProcessSync, startProcessSync } from "./process-sync";
@@ -117,9 +131,18 @@ export type PageOptions = {
   lang?: string;
   /** Renders the document as a page of the installable mobile app; set by `PwaLayout`. */
   pwa?: { name: string };
+  /** A successful app document may keep its same-document address changes. */
+  pwaAddress?: string;
+  /** The actual rendering application, including on error pages. */
+  pwaOwner?: string;
 };
 
-type ResolvedPageOptions = PageOptions & { performanceRoute?: string; themePreference?: CloudThemePreference; appAccent?: string };
+type ResolvedPageOptions = PageOptions & {
+  installable?: AppInstallable;
+  performanceRoute?: string;
+  themePreference?: CloudThemePreference;
+  appAccent?: string;
+};
 
 // ── Public types ────────────────────────────────────────────────────────────
 
@@ -135,6 +158,8 @@ type ResolvedPageOptions = PageOptions & { performanceRoute?: string; themePrefe
  */
 export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefinitionMap = {}, AppId extends string = string> = {
   id: AppId;
+  /** Shared object-store package. Defaults to the app ID. */
+  package?: string;
   access?: AppAccessDeclaration;
   name: string;
   icon: string;
@@ -151,7 +176,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   adminHref?: string;
   /** Multi-link admin navigation contributed by this app. */
   adminNav?: ReadonlyArray<{
-    section?: "ai";
+    section?: AppAdminArea;
     id?: string;
     label: string;
     links: ReadonlyArray<{ label: string; href: string; icon: string }>;
@@ -167,7 +192,7 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
      * Same-origin path of a `GET` route this app serves below one of its
      * `routes`. After the page loads, the shell reads it with the person's
      * session and shows the returned `AppNavBadge` count on the app's icon in
-     * the rail and the app grid. Protect it like any other route.
+     * the rail, the phone bar, and the app grid. Protect it like any other route.
      */
     badge?: string;
   };
@@ -197,6 +222,8 @@ 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[];
+  /** One standalone App-PWA at a canonical, declared own /app/<id>/<surface>/ path. */
+  installable?: AppInstallable;
   /**
    * 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,
@@ -206,6 +233,17 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   pwa?: {
     /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
     requiresRoles?: Role[];
+    /**
+     * Same-origin path of a `GET` route this app serves that returns an `AppNavBadge`: the count beside the part in
+     * the app's sidebar, such as unread messages. Like `nav.badge`, it must be one of the app's own paths.
+     */
+    badge?: string;
+    /**
+     * Same-origin path of a `GET` route this app serves that returns a `PwaPartSummary`: one line under the part on
+     * Start, such as "5 tasks for you", in the reader's locale, and its count beside the part in the sidebar when the
+     * part has no `badge`. It may be the badge's route. It must be one of the app's own paths.
+     */
+    summary?: string;
   };
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
@@ -226,8 +264,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
    *
    * Apps with non-standard URLs (core's `/auth`, `/me`, `/legal/*`, `/impressum`;
    * oauth's `/oauth`, `/.well-known/...`) list whatever
-   * top-level paths they own. The gateway is dumb — it just builds a
-   * prefix-trie from these strings.
+   * top-level paths they own. The gateway builds a prefix trie and enforces
+   * /app/<id> ownership and the reserved /pwa paths.
    */
   routes: readonly string[];
   /** Platform services requested by this application, visible to administrators. */
@@ -378,7 +416,21 @@ const validateAppPwaPart = (opts: Pick<AppOptions, "id" | "routes" | "pwa">): Ap
   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 };
+  const { badge, summary } = opts.pwa;
+  for (const [field, path] of [
+    ["badge", badge],
+    ["summary", summary],
+  ] as const) {
+    if (path !== undefined && !isOwnAppPath(path, [...opts.routes, `/pwa/${opts.id}`])) {
+      throw new Error(`App "${opts.id}" declares pwa.${field} "${path}"; it must be a same-origin path below one of its routes`);
+    }
+  }
+  return {
+    href: `/pwa/${opts.id}`,
+    requiresRoles: opts.pwa.requiresRoles ? [...opts.pwa.requiresRoles] : undefined,
+    ...(badge ? { badge } : {}),
+    ...(summary ? { summary } : {}),
+  };
 };
 
 /** The badge route is read by the browser through the gateway, so it must be one of this app's own paths. */
@@ -430,6 +482,11 @@ export const defineApp = <
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
   const cliModules = validateAppCliModules(opts.id, opts.cli);
   const pwaPart = validateAppPwaPart(opts);
+  const packageName = resolveApplicationPackage(opts.id, opts.package);
+  const installable = opts.installable === undefined ? undefined : validateInstallable(opts.id, opts.routes, opts.installable);
+  if (installable === null)
+    throw new Error(`App "${opts.id}" declares invalid installable; use a canonical own /app/<id>/<surface>/ path covered by routes`);
+  const requestInstallable = (path: string) => (installable && installableContains(installable.path, path) ? installable : undefined);
   validateAppNavBadge(opts);
   const panel = validateAppPanel(opts);
 
@@ -444,7 +501,11 @@ export const defineApp = <
 
   // ── 1. SSR config ─────────────────────────────────────────────────────
   const rootDir = opts.appRoot ?? process.cwd();
-  const { config, plugin, html } = createSsrConfig<ResolvedPageOptions>({
+  const {
+    config,
+    plugin,
+    html: renderHtml,
+  } = createSsrConfig<ResolvedPageOptions>({
     dev: isDevelopment,
     verbose: true,
     rootDir,
@@ -453,7 +514,19 @@ export const defineApp = <
     // Every island instance already mounts inside its own error boundary; this
     // only gives the fallback Cloud's look and the reader's language.
     errorFallback: fileURLToPath(new URL("../ssr/IslandError.tsx", import.meta.url)),
-    template: ({ body, scripts, title, description, theme, themePreference, lang, performanceRoute, pwa, appAccent }) => {
+    template: ({
+      body,
+      scripts,
+      title,
+      description,
+      theme,
+      themePreference,
+      lang,
+      performanceRoute,
+      pwa,
+      appAccent,
+      installable: pageInstallable,
+    }) => {
       // A URL changes only when what it names changes: the app's own files by their content, Core's shared sheets by
       // the release of the Core build in the registry, so every app links them under one URL per Core build.
       const sharedVersion = isDevelopment ? String(developmentStamp) : sharedStylesheetVersion(registeredCoreRelease());
@@ -471,33 +544,35 @@ export const defineApp = <
       // status bar. No status-bar style: `black-translucent` lays a blur band
       // over the top edge on iOS 26.
       const canvas = resolved ? PWA_CANVAS_COLORS[resolved] : undefined;
-      const head = pwa
-        ? {
-            html: canvas ? ` style="background-color:${canvas}"` : "",
-            viewport: "width=device-width, initial-scale=1, viewport-fit=cover",
-            app: `${
-              canvas
-                ? `<meta name="theme-color" content="${canvas}">`
-                : `<meta name="theme-color" media="(prefers-color-scheme: light)" content="${PWA_CANVAS_COLORS.light}">
+      const head = pageInstallable
+        ? installableHead(pageInstallable, resolved)
+        : pwa
+          ? {
+              html: canvas ? ` style="background-color:${canvas}"` : "",
+              viewport: "width=device-width, initial-scale=1, viewport-fit=cover",
+              app: `${
+                canvas
+                  ? `<meta name="theme-color" content="${canvas}">`
+                  : `<meta name="theme-color" media="(prefers-color-scheme: light)" content="${PWA_CANVAS_COLORS.light}">
     <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${PWA_CANVAS_COLORS.dark}">
     <style data-cloud-canvas>html{background-color:${PWA_CANVAS_COLORS.light}}@media (prefers-color-scheme: dark){html{background-color:${PWA_CANVAS_COLORS.dark}}}</style>`
-            }
+              }
     <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: `
+              // 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">
+            }
+          : {
+              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: "",
-          };
+              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.
@@ -516,7 +591,7 @@ export const defineApp = <
     <link rel="stylesheet" href="${versionedPublicHref("/public/tabler-icons.css", sharedVersion)}">
     <link rel="stylesheet" href="${versionedPublicHref(appStylesheet, appVersion)}">
     <link rel="stylesheet" href="${versionedPublicHref("/public/global.css", sharedVersion)}">${head.styles}
-    <script>${themeBootstrapScript}</script>
+    <script>${themeBootstrapScript}</script>${pageInstallable ? `<script>${installableThemeScript(pageInstallable)}</script>` : ""}
   </head>
   <body class="k2b-ui${accentStyle ? " app-accent-scope" : ""}"${accentStyle ? ` style="${escapeHtml(accentStyle)}"` : ""} data-k2b-app-workspace-controller="global">
     ${body}
@@ -527,6 +602,13 @@ export const defineApp = <
     },
   });
 
+  const html: HtmlFn<ResolvedPageOptions> = async (render, page) => {
+    if (!page?.installable) return renderHtml(render, page);
+    // Load JSX only after the standard preload/build has installed the SSR plugin.
+    const { appPwaDocument } = await import("../ssr/app-pwa-document");
+    return renderHtml(appPwaDocument(render, page.installable, normalizeLocale(page.lang)), page);
+  };
+
   // Pass PageOptions explicitly so c.get("page") in apps' SSR handlers is
   // typed as Partial<PageOptions> (with title/description/theme), not the
   // bare `object` fallback the constraint would otherwise produce.
@@ -539,7 +621,8 @@ export const defineApp = <
   // cannot override.
   const ssr = Object.assign(
     createStatusPreservingSsrHandler<ResolvedPageOptions>(html, async (c) => {
-      if (opts.pageSwap)
+      c.get("page").installable = requestInstallable(c.req.path);
+      if (opts.pageSwap && !c.get("page").installable)
         registerPageSwap(c, isDevelopment ? String(developmentStamp) : `${buildMetadata.version}:${buildMetadata.release}`);
       c.get("page").lang = getLocale(c);
       c.get("page").themePreference = readThemePreferenceFromCookieHeader(c.req.header("Cookie"));
@@ -548,7 +631,14 @@ export const defineApp = <
         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;
+      if (isAppPagePath(c.req.path)) {
+        c.get("page").pwaOwner = opts.id;
+        const url = new URL(c.req.url);
+        const address = rememberedPwaAddress(url.pathname + url.search);
+        if (user && address && c.newResponse(null).status < 400) c.get("page").pwaAddress = address;
+        return;
+      }
+      if (c.get("page").installable) return;
       await Promise.all([
         preloadLayoutAnnouncements(c),
         preloadLayoutHelp(c),
@@ -556,11 +646,12 @@ export const defineApp = <
         user ? readRailSnapshot(user).then((snapshot) => c.set("railPreferences", snapshot)) : undefined,
       ]);
     }),
-    createPageResponses(html),
+    createPageResponses(html, opts.id, (c) => ({ installable: requestInstallable(c.req.path) })),
   );
 
   // ── 2. Meta ───────────────────────────────────────────────────────────
   const baseMeta: AppMeta = {
+    package: packageName,
     id: opts.id,
     platformPermissions: opts.platformPermissions
       ? opts.platformPermissions.map((permission) => PlatformPermissionSchema.parse(permission))
@@ -583,6 +674,7 @@ export const defineApp = <
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     pwa: pwaPart,
+    installable: installable ?? undefined,
     panel,
     widgets: compileWidgetDeclarations(opts.id, opts.widgets),
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
@@ -629,7 +721,8 @@ export const defineApp = <
         }
       })());
     try {
-      bindProcessApplicationId(meta.id, meta.platformPermissions);
+      await registerApplicationPackage(meta.id, packageName);
+      bindProcessApplicationId(meta.id, meta.platformPermissions, packageName);
       cleanup.unshift(clearProcessApplicationId);
       const startedAt = Date.now();
 
@@ -637,7 +730,8 @@ export const defineApp = <
       // derive the spec from. The mount block lower down uses the same
       // flag so the registry never points at a URL that 404s.
       const advertiseOpenapi = !!(opts.openapi && startOpts.openapi);
-      const compiledCapabilities = startOpts.capabilities ? compileCapabilities(meta.id, startOpts.capabilities) : undefined;
+      const compiledCapabilities = startOpts.capabilities ? compileCapabilities(meta.id, startOpts.capabilities, meta.routes) : undefined;
+      if (startOpts.capabilities) bindAppEvents(meta.id, startOpts.capabilities, compiledCapabilities);
       const compiledHelp = startOpts.help
         ? compileHelp({
             appId: meta.id,
@@ -648,6 +742,7 @@ export const defineApp = <
 
       // Registry entry
       const entry: AppRegistryEntry = {
+        package: packageName,
         id: meta.id,
         access: meta.access,
         name: meta.name,
@@ -688,8 +783,14 @@ export const defineApp = <
         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 }
+          ? {
+              href: meta.pwa.href,
+              requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined,
+              ...(meta.pwa.badge ? { badge: meta.pwa.badge } : {}),
+              ...(meta.pwa.summary ? { summary: meta.pwa.summary } : {}),
+            }
           : undefined,
+        installable: meta.installable,
         panel: meta.panel
           ? { ...meta.panel, requiresRoles: meta.panel.requiresRoles ? [...meta.panel.requiresRoles] : undefined }
           : undefined,
@@ -809,6 +910,11 @@ export const defineApp = <
         })
         .route("/_internal/sync", createSyncOpsRoutes(getProcessSync));
 
+      if (installable) server.route("/", createInstallableRoutes(meta.id, installable));
+
+      if (compiledCapabilities?.subscribes.size)
+        server.route("/api/_internal/events/v1", createAppEventDeliveryRoutes(compiledCapabilities));
+
       if (compiledCapabilities) {
         const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") =>
           withCapabilityRequestTimeout(c, kind, async () => {
@@ -846,6 +952,7 @@ export const defineApp = <
               input: body.input,
               expectedSchemaHash: c.req.header("x-cloud-capability-schema-hash") ?? null,
               context: {
+                query: createNestedCapabilityQuery(c.req.raw),
                 authority: auth.getAuthority(c),
                 actor,
                 accessSubject: c.get("accessSubject"),
@@ -898,6 +1005,7 @@ export const defineApp = <
         for (const kind of ["queries", "actions"] as const) {
           server.post(
             `/api/_internal/capabilities/v1/streams/${kind}/:capabilityId/:verb`,
+            kind === "queries" ? auth.readOnly : auth.requireOAuthScope("write", "admin"),
             capabilityAuth(kind),
             auth.requireOAuthScope(kind === "queries" ? "read" : "write", "admin"),
             async (c) => {
@@ -924,14 +1032,19 @@ export const defineApp = <
         }
         const capabilityReadScope = auth.requireOAuthScope("read", "admin");
         const capabilityWriteScope = auth.requireOAuthScope("write", "admin");
-        server.post("/api/_internal/capabilities/v1/queries/:capabilityId", capabilityAuth("queries"), capabilityReadScope, (c) =>
-          invoke(c, "query"),
+        server.post(
+          "/api/_internal/capabilities/v1/queries/:capabilityId",
+          auth.readOnly,
+          capabilityAuth("queries"),
+          capabilityReadScope,
+          (c) => invoke(c, "query"),
         );
         server.post("/api/_internal/capabilities/v1/actions/:capabilityId", capabilityAuth("actions"), capabilityWriteScope, (c) =>
           invoke(c, "action"),
         );
         server.post(
           "/api/_internal/capabilities/v1/actions/:capabilityId/review",
+          auth.readOnly,
           capabilityAuth("actions", true),
           capabilityReadScope,
           (c) => invoke(c, "review"),
@@ -964,16 +1077,15 @@ export const defineApp = <
         );
       }
 
+      cleanup.push(bindResourceAppAccess(meta.id, opts.access));
+      server.route(RESOURCE_ACCESS_PATH, createResourceAppAccessRoutes(meta));
       cleanup.push(() => stopAppAccessConnections());
+      if (meta.access?.kind === "grants") {
+        server.route(appAccessManagementPath(meta), createOwnedAppAccessRoutes(meta, opts.access?.canManage));
+      }
       server.use(
         "*",
-        requireAppAccess(meta, (c, message) =>
-          ssr.error(c, 403, {
-            title: "No access",
-            description: message,
-            layout: "minimal",
-          }),
-        ),
+        requireAppAccess(meta, (c) => ssr.appAccessDenied(c, meta)),
       );
 
       if (opts.cli && cliModules.length > 0) server.route(CLOUD_CLI_PLUGIN_ROUTE, createCliPluginRoutes(meta.id, opts.cli));
@@ -1037,6 +1149,8 @@ export const defineApp = <
       const startOutbox = async () => {
         const stopLiveOutbox = await startLiveOutbox(meta.id);
         if (stopLiveOutbox) cleanup.push(stopLiveOutbox);
+        const stopAppEvents = await startAppEventDelivery(meta.id);
+        if (stopAppEvents) cleanup.push(stopAppEvents);
       };
       // 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.

package/src/_internal/installable-assets.ts

@@ -0,0 +1,90 @@
+import { resolve } from "node:path";
+import { Hono } from "hono";
+import type { AppInstallable } from "../contracts/installable";
+import { escapeHtml } from "../shared/markdown/shared";
+
+export const INSTALLABLE_ICON_VARIANTS = {
+  "icon-192": { size: 192, box: 0.84 },
+  "icon-512": { size: 512, box: 0.84 },
+  // The square fits inside the maskable safe circle of radius 40%.
+  "icon-maskable-512": { size: 512, box: 0.56 },
+  "apple-touch-icon": { size: 180, box: 0.7 },
+} as const;
+
+export const installableManifest = (app: AppInstallable, theme: "light" | "dark") => ({
+  id: app.path,
+  start_url: app.path,
+  scope: app.path,
+  name: app.name,
+  short_name: app.shortName,
+  display: app.display,
+  theme_color: app.themeColor[theme],
+  background_color: app.themeColor[theme],
+  icons: [
+    { src: `${app.path}icon-192-${theme}.png`, sizes: "192x192", type: "image/png", purpose: "any" },
+    { src: `${app.path}icon-512-${theme}.png`, sizes: "512x512", type: "image/png", purpose: "any" },
+    { src: `${app.path}icon-maskable-512-${theme}.png`, sizes: "512x512", type: "image/png", purpose: "maskable" },
+  ],
+});
+
+/** One public bilingual document. It never includes a request, account, or application payload. */
+export const installableOfflineHtml = (app: AppInstallable): string => `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>${escapeHtml(app.name)} · Offline</title><meta name="referrer" content="no-referrer">
+<style>:root{color-scheme:light dark;font-family:system-ui;background:#fafafa;color:#111}body{margin:0;padding: max(24px,env(safe-area-inset-top)) max(24px,env(safe-area-inset-right)) max(24px,env(safe-area-inset-bottom)) max(24px,env(safe-area-inset-left))}main{max-width:36rem;margin:10vh auto}button{font:inherit;min-height:44px;padding:8px 20px;cursor:pointer}@media(prefers-color-scheme:dark){:root{background:#090d12;color:#fff}}</style>
+</head><body><main><h1>${escapeHtml(app.name)}</h1><p>You're offline. Connect to the internet and try again.</p><p lang="de">Du bist offline. Verbinde dich mit dem Internet und versuche es erneut.</p><button type="button">Try again / Erneut versuchen</button></main><script>document.querySelector('button').addEventListener('click',()=>location.reload())</script></body></html>`;
+
+/** No cache storage, install/activate shortcuts, client messages, or private response retention. */
+export const installableWorker = (app: AppInstallable): string => `"use strict";
+const scope = ${JSON.stringify(app.path)};
+const offline = ${JSON.stringify(installableOfflineHtml(app))};
+self.addEventListener("fetch", event => {
+  const request = event.request;
+  const url = new URL(request.url);
+  if (request.method !== "GET" || request.mode !== "navigate" || url.origin !== self.location.origin || !url.pathname.startsWith(scope)) return;
+  event.respondWith(fetch(request).catch(() => new Response(offline, {
+    status: 503,
+    headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" }
+  })));
+});
+`;
+
+/** Framework mounts before app access/auth and never delegates a missing generated file to app code. */
+export const createInstallableRoutes = (appId: string, app: AppInstallable, publicDir = resolve(process.cwd(), "public")) => {
+  const router = new Hono();
+  const headers = { "Cache-Control": "no-cache", "X-Content-Type-Options": "nosniff" };
+  router.get(app.path.slice(0, -1), (c) => {
+    const url = new URL(c.req.url);
+    return c.redirect(`${app.path}${url.search}`, 308);
+  });
+  router.all(`${app.path}manifest.webmanifest`, (c) => {
+    if (c.req.method !== "GET" && c.req.method !== "HEAD") return c.text("Method Not Allowed", 405, { Allow: "GET, HEAD" });
+    return new Response(
+      c.req.method === "HEAD" ? null : JSON.stringify(installableManifest(app, c.req.query("theme") === "dark" ? "dark" : "light")),
+      {
+        headers: { ...headers, "Content-Type": "application/manifest+json" },
+      },
+    );
+  });
+  for (const [name, content, type] of [
+    ["sw.js", installableWorker(app), "text/javascript; charset=utf-8"],
+    ["offline.html", installableOfflineHtml(app), "text/html; charset=utf-8"],
+  ] as const) {
+    router.all(`${app.path}${name}`, (c) => {
+      if (c.req.method !== "GET" && c.req.method !== "HEAD") return c.text("Method Not Allowed", 405, { Allow: "GET, HEAD" });
+      return new Response(c.req.method === "HEAD" ? null : content, { headers: { ...headers, "Content-Type": type } });
+    });
+  }
+  for (const theme of ["light", "dark"] as const) {
+    for (const name of Object.keys(INSTALLABLE_ICON_VARIANTS)) {
+      const filename = `${name}-${theme}.png`;
+      router.all(`${app.path}${filename}`, async (c) => {
+        if (c.req.method !== "GET" && c.req.method !== "HEAD") return c.text("Method Not Allowed", 405, { Allow: "GET, HEAD" });
+        const file = Bun.file(resolve(publicDir, appId, "installable", filename));
+        if (!(await file.exists())) return c.notFound();
+        return new Response(c.req.method === "HEAD" ? null : file, { headers: { ...headers, "Content-Type": "image/png" } });
+      });
+    }
+  }
+  return router;
+};

package/src/_internal/installable-head.ts

@@ -0,0 +1,22 @@
+import type { AppInstallable } from "../contracts/installable";
+import { escapeHtml } from "../shared/markdown/shared";
+
+export const installableHead = (app: AppInstallable, resolved: "light" | "dark" | undefined) => {
+  const theme = resolved ?? "light";
+  return {
+    html: "",
+    viewport: "width=device-width, initial-scale=1, viewport-fit=cover",
+    app: `<meta name="theme-color" data-app-pwa-theme content="${app.themeColor[theme]}">
+    <link rel="manifest" data-app-pwa-manifest href="${app.path}manifest.webmanifest?theme=${theme}">
+    <link rel="apple-touch-icon" data-app-pwa-apple href="${app.path}apple-touch-icon-${theme}.png">
+    <meta name="apple-mobile-web-app-title" content="${escapeHtml(app.shortName)}">
+    <meta name="mobile-web-app-capable" content="yes">
+    <meta name="apple-mobile-web-app-capable" content="yes">
+    <style data-app-pwa-canvas>html{background:${app.themeColor.light}}html.dark{background:${app.themeColor.dark}}body{box-sizing:border-box;min-height:100dvh;padding:env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left)}[data-app-pwa-runtime]:not(:empty){max-width:40rem;margin:1rem auto}</style>`,
+    styles: "<style data-app-pwa-navigation>@view-transition{navigation:none}</style>",
+  };
+};
+
+/** Runs after the shared theme bootstrap, before first paint or island downloads. All interpolations are validated paths/hex colors. */
+export const installableThemeScript = (app: AppInstallable): string =>
+  `!function(){var t=document.documentElement.classList.contains('dark')?'dark':'light';document.querySelector('meta[data-app-pwa-theme]').content=${JSON.stringify(app.themeColor)}[t];document.querySelector('link[data-app-pwa-manifest]').href=${JSON.stringify(`${app.path}manifest.webmanifest?theme=`)}+t;document.querySelector('link[data-app-pwa-apple]').href=${JSON.stringify(`${app.path}apple-touch-icon-`)}+t+'.png'}();`;

package/src/_internal/object-store-area.ts

@@ -0,0 +1,9 @@
+import { getProcessApplicationPackage } from "./process-identity";
+
+/** The single application-to-area mapping. No caller-supplied application or area ID. */
+export const objectStoreArea = (visibility: "private" | "public" = "private"): string => {
+  const packageName = getProcessApplicationPackage();
+  if (!packageName) throw new Error("Start the application before using the object store.");
+  if (!/^[a-z][a-z0-9-]{0,79}$/.test(packageName)) throw new Error("Invalid object-store application package.");
+  return `${visibility}/${packageName}/`;
+};