@underpostnet/cyberia 3.3.76 → 3.3.77

package/src/cli/cluster.js

@@ -36,6 +36,13 @@ import os from 'os';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
 
+/**
+ * @constant CERT_MANAGER_VERSION
+ * @description Pinned cert-manager chart version.
+ * @memberof UnderpostCluster
+ */
+const CERT_MANAGER_VERSION = 'v1.17.0';
+
 const logger = loggerFactory(import.meta);
 
 const GATEWAY_API_RELEASE = 'v1.5.1';
@@ -670,22 +677,12 @@ EOF
         }
       }
 
-      if (options.certManager) {
-        if (!Underpost.kubectl.get('cert-manager').find((p) => p.STATUS === 'Running')) {
-          shellExec(`helm repo add jetstack https://charts.jetstack.io --force-update`);
-          shellExec(
-            `helm install cert-manager jetstack/cert-manager \
---namespace cert-manager \
---create-namespace \
---version v1.17.0 \
---set crds.enabled=true`,
-          );
-        }
-
-        const letsEncName = 'letsencrypt-prod';
-        shellExec(`sudo kubectl delete ClusterIssuer ${letsEncName} --ignore-not-found`);
-        shellExec(`sudo kubectl apply -f ${underpostRoot}/manifests/${letsEncName}.yaml -n ${options.namespace}`);
-      }
+      if (options.certManager)
+        Underpost.cluster.installCertManager({
+          namespace: options.namespace,
+          env: options.dev ? 'development' : 'production',
+          solver: Underpost.cluster.acmeSolverFactory({ options, presence: Underpost.cluster.ingressStackPresence() }),
+        });
     },
 
     /**
@@ -1100,6 +1097,57 @@ EOF
       return true;
     },
 
+    /**
+     * @method acmeSolverFactory
+     * @description Which ingress stack answers the HTTP-01 challenge.
+     *
+     * Read from the cluster, like {@link UnderpostCluster.ingressStackPresence}: the
+     * `cluster` runner installs the issuer in a separate invocation that carries no stack
+     * flag, so the flags alone would always name the Contour solver. `--contour` is the
+     * only explicit override; a cluster with the Gateway API data plane installed routes
+     * every hostname through it, so an Ingress solver there is unreachable.
+     * @param {object} params
+     * @param {object} [params.options] - Cluster init options.
+     * @param {{contour: boolean, gateway: boolean}} params.presence - Installed stacks.
+     * @returns {'gateway'|'ingress'} Solver kind.
+     * @memberof UnderpostCluster
+     */
+    acmeSolverFactory({ options = {}, presence }) {
+      if (options.contour === true && options.gatewayApi !== true) return 'ingress';
+      return options.gatewayApi === true || presence.gateway ? 'gateway' : 'ingress';
+    },
+
+    /**
+     * @method installCertManager
+     * @description Installs or upgrades cert-manager and applies the Let's Encrypt
+     * ClusterIssuer for the stack in use.
+     *
+     * `upgrade --install` rather than a one-time install: the Gateway API solver is
+     * ignored by a controller that was not started with `enableGatewayAPI`, so a cluster
+     * whose cert-manager predates the Gateway API migration must be re-configured, not
+     * skipped because a pod is Running. The version is pinned, so on a cluster already at
+     * it the upgrade is a no-op.
+     * @param {object} params
+     * @param {string} [params.namespace] - Namespace the deploys' Gateways live in.
+     * @param {string} [params.env] - Environment the routed deploys publish under.
+     * @param {'gateway'|'ingress'} params.solver - Which stack answers the challenge.
+     * @returns {{solver: string, parentRefs: Array<{name: string, namespace: string}>}} What was applied.
+     * @memberof UnderpostCluster
+     */
+    installCertManager({ namespace = 'default', env = 'production', solver }) {
+      const gatewayValues =
+        solver === 'gateway'
+          ? ' --set config.apiVersion=controller.config.cert-manager.io/v1alpha1' +
+            ' --set config.kind=ControllerConfiguration --set config.enableGatewayAPI=true'
+          : '';
+      shellExec(`helm repo add jetstack https://charts.jetstack.io --force-update`);
+      shellExec(
+        `helm upgrade --install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace` +
+          ` --version ${CERT_MANAGER_VERSION} --set crds.enabled=true${gatewayValues} --wait --timeout 5m`,
+      );
+      return Underpost.deploy.applyLetsEncryptIssuer({ solver, namespace, env });
+    },
+
     /**
      * @method ingressStackPresence
      * @description Which ingress data planes are installed right now.
@@ -1358,14 +1406,21 @@ EOF
       }
 
       try {
-        shellExec(`kubectl apply -f - -n ${namespace} <<'EOF'
+        // The manifest carries the whole nginx.conf: echoing it as the command line
+        // buries the lines that follow it — the fallback probes above all — under
+        // a page of routing tables on every sync.
+        logger.info('Applying the underpost ingress manifests', { namespace, node: ingressNode });
+        shellExec(
+          `kubectl apply -f - -n ${namespace} <<'EOF'
 ${underpostIngressManifestsFactory({
   namespace,
   conf,
   nodeName: ingressNode,
 })}
 EOF
-`);
+`,
+          { disableLog: true },
+        );
       } catch (error) {
         if (shouldHotReload)
           execIngress(`sh -c 'cp /tmp/nginx.previous.conf /tmp/nginx.conf && nginx -s reload -c /tmp/nginx.conf'`, {

package/src/cli/deploy.js

@@ -50,6 +50,8 @@ import nodePath from 'node:path';
 import dotenv from 'dotenv';
 import os from 'node:os';
 import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
 import { appSecretName } from './app.js';
 import { domainContextFactory } from './domains.js';
 import Underpost from '../index.js';
@@ -93,6 +95,23 @@ const UPSTREAM_FAILURE_STATUSES = [502, 503, 504];
 
 const CONTAINER_ENGINE_ROOT = '/home/dd/engine';
 
+/**
+ * @constant LETSENCRYPT_ISSUER_NAME
+ * @description The ClusterIssuer every generated Certificate references.
+ * @memberof UnderpostDeploy
+ */
+const LETSENCRYPT_ISSUER_NAME = 'letsencrypt-prod';
+
+/**
+ * @constant LETSENCRYPT_ISSUER_MANIFEST
+ * @description Base ClusterIssuer manifest: account, ACME server and key Secret. Resolved
+ * from this module so an installed CLI and a checkout read the same file.
+ * @memberof UnderpostDeploy
+ */
+const LETSENCRYPT_ISSUER_MANIFEST = fileURLToPath(
+  new URL(`../../manifests/${LETSENCRYPT_ISSUER_NAME}.yaml`, import.meta.url),
+);
+
 // The manifest set `deploy --build-manifest` produces for one environment.
 const DEFAULT_MANIFEST_FILES = [
   'deployment.yaml',
@@ -255,12 +274,68 @@ ${buildKindPorts(fromPort, toPort)}`;
           : Underpost.deploy.trafficServiceYamlFactory({ deployId, env, traffic, namespace, fromPort, toPort });
       const escaped = `${deployId}-${env}`.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
       manifest = manifest.replace(new RegExp(`app: ${escaped}-(?:blue|green)`), `app: ${deployId}-${env}-${traffic}`);
-      shellExec(`kubectl apply -f - -n ${namespace} <<'EOF'
+      logger.info('Applying the traffic Service', { deployId, env, traffic, namespace });
+      shellExec(
+        `kubectl apply -f - -n ${namespace} <<'EOF'
 ${manifest}
 EOF
-`);
+`,
+        { disableLog: true },
+      );
       return Underpost.deploy.trafficServiceNameFactory({ deployId, env });
     },
+    /**
+     * Removes the Gateway API objects an earlier model of this deploy left behind, so
+     * they stop competing with the consolidated `<deployId>-<env>` Gateway.
+     *
+     * The per-host model emitted one Gateway and one `<host>-http3` ClientTrafficPolicy
+     * per hostname. Left in place they duplicate that hostname's listeners in the same
+     * merged set, and the oldest resource retains traffic. `undefined` / `undefined-http3`
+     * is the same problem under a different name: the consolidated objects were briefly
+     * emitted with an unresolved host in their metadata, and merged listeners are
+     * configured by the oldest policy that targets them.
+     *
+     * The namespace is listed once and only objects that exist are deleted: a sweep that
+     * issued a blind delete per host per kind spent two dozen `kubectl` round-trips per
+     * sync on names that were gone after the first migration, and buried the one line
+     * that mattered when something was actually removed.
+     * @param {object} params
+     * @param {string[]} params.hosts - Hostnames the deploy's `conf.server.json` declares.
+     * @param {string} params.namespace - Namespace the deploy's Gateway objects live in.
+     * @returns {{gateways: string[], policies: string[]}} Names removed, per kind.
+     * @memberof UnderpostDeploy
+     */
+    sweepLegacyGatewayObjects({ hosts = [], namespace = 'default' }) {
+      const existing = (kind) =>
+        new Set(
+          `${
+            shellExec(`kubectl get ${kind} -n ${namespace} -o name --ignore-not-found`, {
+              stdout: true,
+              silent: true,
+              silentOnError: true,
+              disableLog: true,
+            }) ?? ''
+          }`
+            .split('\n')
+            .map((line) => line.trim().split('/').pop())
+            .filter(Boolean),
+        );
+      const legacy = [...new Set(hosts.filter(Boolean)), 'undefined'];
+      const gateways = existing('Gateway');
+      const policies = existing('ClientTrafficPolicy');
+      const removed = {
+        gateways: legacy.filter((name) => gateways.has(name)),
+        policies: legacy.map((name) => `${name}-http3`).filter((name) => policies.has(name)),
+      };
+      for (const name of removed.gateways)
+        shellExec(`sudo kubectl delete Gateway ${name} -n ${namespace} --ignore-not-found`);
+      for (const name of removed.policies)
+        shellExec(`sudo kubectl delete ClientTrafficPolicy ${name} -n ${namespace} --ignore-not-found`);
+      if (removed.gateways.length > 0 || removed.policies.length > 0)
+        logger.warn('Legacy per-host Gateway API objects removed', { namespace, ...removed });
+      return removed;
+    },
+
     /**
      * Removes the route kind owned by the inactive ingress stack. The active
      * route is already published before this runs, so migration never creates a
@@ -1112,6 +1187,125 @@ spec:
     kind: ClusterIssuer
   secretName: ${host}`;
     },
+
+    /**
+     * The Gateways an ACME HTTP-01 challenge route must attach to: every Gateway the
+     * namespace holds now, plus the one each routed deploy publishes under, whether or
+     * not it exists yet. A challenge HTTPRoute lists them all as parents; the data plane
+     * attaches it to whichever one carries a listener for the challenged hostname, and
+     * reports the rest as unmatched, which is harmless.
+     *
+     * The union rather than either side alone: the live list covers Gateways a deploy
+     * outside `dd.routes` created, the route table covers a deploy that has not been
+     * applied yet — an issuer that only knew the live list would have to be re-applied
+     * after every first deploy before that deploy's certificate could issue.
+     * @param {object} params
+     * @param {string} [params.namespace] - Namespace the Gateways live in.
+     * @param {string} [params.env] - Environment the routed deploys publish under.
+     * @returns {Array<{name: string, namespace: string}>} Parent references, sorted by name.
+     * @memberof UnderpostDeploy
+     */
+    acmeGatewayParentRefsFactory({ namespace = 'default', env = 'production' } = {}) {
+      const live = `${
+        shellExec(`kubectl get gateway -n ${namespace} -o name --ignore-not-found`, {
+          stdout: true,
+          silent: true,
+          silentOnError: true,
+          disableLog: true,
+        }) ?? ''
+      }`
+        .split('\n')
+        .map((line) => line.trim().split('/').pop())
+        .filter(Boolean);
+      const routed = readDeployRoutes().map((deployId) => Underpost.deploy.gatewayNameFactory({ deployId, env }));
+      return [...new Set([...live, ...routed])].sort().map((name) => ({ name, namespace }));
+    },
+
+    /**
+     * Renders the Let's Encrypt ClusterIssuer for the ingress stack that actually
+     * carries the HTTP-01 challenge.
+     *
+     * The base manifest fixes the account (email, ACME server, key Secret); only the
+     * solver is decided here. With the Gateway API stack, the challenge must be answered
+     * through an HTTPRoute on the deploy's Gateway: an `ingress`-class solver creates an
+     * Ingress nothing on the request path reads, so `/.well-known/acme-challenge/*` is
+     * routed by the application's own HTTPRoute to the workload — a 404 — or, with no
+     * workload behind it, to the maintenance fallback. Every renewal fails that way while
+     * the solver pods sit there ready, and the failure only surfaces when the certificate
+     * expires.
+     * @param {object} params
+     * @param {'gateway'|'ingress'} params.solver - Which stack answers the challenge.
+     * @param {Array<{name: string, namespace: string}>} [params.parentRefs] - Gateways for the `gateway` solver.
+     * @param {string} [params.basePath] - Base ClusterIssuer manifest.
+     * @returns {string} ClusterIssuer YAML.
+     * @throws {Error} When the Gateway solver is requested with no Gateway to attach to.
+     * @memberof UnderpostDeploy
+     */
+    letsEncryptIssuerYamlFactory({ solver, parentRefs = [], basePath = LETSENCRYPT_ISSUER_MANIFEST }) {
+      const issuer = yamlLoad(fs.readFileSync(basePath, 'utf8'));
+      if (solver === 'gateway') {
+        if (parentRefs.length === 0)
+          throw new Error('[cert-manager] the Gateway API HTTP-01 solver needs at least one Gateway parentRef');
+        issuer.spec.acme.solvers = [
+          {
+            http01: {
+              gatewayHTTPRoute: {
+                parentRefs: parentRefs.map(({ name, namespace }) => ({ name, namespace, kind: 'Gateway' })),
+              },
+            },
+          },
+        ];
+      } else issuer.spec.acme.solvers = [{ http01: { ingress: { class: 'contour' } } }];
+      return yamlDump(issuer, { lineWidth: -1, noRefs: true });
+    },
+
+    /**
+     * Whether the Let's Encrypt ClusterIssuer is installed. False both when it was never
+     * applied and when cert-manager's CRDs are absent, which is the same answer here.
+     * @returns {boolean}
+     * @memberof UnderpostDeploy
+     */
+    letsEncryptIssuerExists() {
+      return (
+        `${
+          shellExec(`kubectl get clusterissuer ${LETSENCRYPT_ISSUER_NAME} -o name --ignore-not-found`, {
+            stdout: true,
+            silent: true,
+            silentOnError: true,
+            disableLog: true,
+          }) ?? ''
+        }`.trim().length > 0
+      );
+    },
+
+    /**
+     * Applies the Let's Encrypt ClusterIssuer for the stack in use, so certificates keep
+     * renewing through whichever data plane the deploy's hostnames are served by.
+     * @param {object} params
+     * @param {'gateway'|'ingress'} params.solver - Which stack answers the challenge.
+     * @param {string} [params.namespace] - Namespace the Gateways live in.
+     * @param {string} [params.env] - Environment the routed deploys publish under.
+     * @param {string} [params.basePath] - Base ClusterIssuer manifest.
+     * @returns {{solver: string, parentRefs: Array<{name: string, namespace: string}>}} What was applied.
+     * @memberof UnderpostDeploy
+     */
+    applyLetsEncryptIssuer({ solver, namespace = 'default', env = 'production', basePath } = {}) {
+      const parentRefs = solver === 'gateway' ? Underpost.deploy.acmeGatewayParentRefsFactory({ namespace, env }) : [];
+      const manifest = Underpost.deploy.letsEncryptIssuerYamlFactory({ solver, parentRefs, basePath });
+      const stagePath = `/dev/shm/underpost-${LETSENCRYPT_ISSUER_NAME}.yaml`;
+      fs.writeFileSync(stagePath, manifest, 'utf8');
+      try {
+        shellExec(`sudo kubectl apply -f ${stagePath}`);
+      } finally {
+        fs.removeSync(stagePath);
+      }
+      logger.info("Let's Encrypt ClusterIssuer applied", {
+        issuer: LETSENCRYPT_ISSUER_NAME,
+        solver,
+        gateways: parentRefs.map(({ name }) => name),
+      });
+      return { solver, parentRefs };
+    },
     /**
      * Mirrors each deploy's built development manifests into the project tree, and refreshes the
      * public default configuration they belong to.
@@ -2341,34 +2535,15 @@ EOF`);
                 });
           }
 
-        for (const host of Object.keys(confServer)) {
-          if (!options.disableUpdateProxy) {
-            // The host's route object is left in place and replaced by the `apply`
-            // below. Deleting it first unpublished the hostname for the whole
-            // reconciliation window, so every promote dropped live requests before
-            // the new colour was ever the question.
-            //
-            // A deploy that previously ran the per-host model left a Gateway
-            // named after each host. Those are superseded by the consolidated
-            // one, and leaving them behind duplicates that hostname's listeners
-            // in the same merged set. The oldest resource would retain traffic.
-            //
-            // `undefined-http3` is the same problem under a different name: the
-            // consolidated policy was briefly emitted with an unresolved host in
-            // its metadata. Merged listeners are configured by the oldest policy
-            // that targets them, so that object outranks the correctly named one
-            // for as long as it exists.
-            if (options.gatewayApi)
-              for (const name of [host, 'undefined']) {
-                shellExec(`sudo kubectl delete Gateway ${name} -n ${namespace} --ignore-not-found`, { silent: true });
-                shellExec(`sudo kubectl delete ClientTrafficPolicy ${name}-http3 -n ${namespace} --ignore-not-found`, {
-                  silent: true,
-                });
-              }
-            if (Underpost.deploy.isCertManagerContext({ host, env, options }))
-              shellExec(`sudo kubectl delete Certificate ${host} -n ${namespace} --ignore-not-found`);
-          }
-        }
+        // The host's route object is left in place and replaced by the `apply`
+        // below. Deleting it first unpublished the hostname for the whole
+        // reconciliation window, so every promote dropped live requests before
+        // the new colour was ever the question.
+        if (!options.disableUpdateProxy && options.gatewayApi)
+          Underpost.deploy.sweepLegacyGatewayObjects({ hosts: Object.keys(confServer), namespace });
+        for (const host of Object.keys(confServer))
+          if (!options.disableUpdateProxy && Underpost.deploy.isCertManagerContext({ host, env, options }))
+            shellExec(`sudo kubectl delete Certificate ${host} -n ${namespace} --ignore-not-found`);
 
         const manifestsPath =
           env === 'production'
@@ -2480,6 +2655,11 @@ EOF`);
           }
 
           if (Underpost.deploy.isCertManagerContext({ host: Object.keys(confServer)[0], env, options })) {
+            // The issuer's challenge route must list this deploy's Gateway as a parent, or
+            // the certificates applied below can never issue. Re-rendered from the live
+            // Gateway list, so a deploy created after `cluster --cert-manager` is covered.
+            if (options.gatewayApi && Underpost.deploy.letsEncryptIssuerExists())
+              Underpost.deploy.applyLetsEncryptIssuer({ solver: 'gateway', namespace, env });
             const secretPath = `./${manifestsPath}/secret.yaml`;
             if (fs.existsSync(secretPath) && fs.readFileSync(secretPath, 'utf8').trim()) {
               shellExec(`sudo kubectl apply -f ${secretPath} -n ${namespace}`);
@@ -3143,3 +3323,4 @@ spec:
 }
 
 export default UnderpostDeploy;
+export { LETSENCRYPT_ISSUER_MANIFEST, LETSENCRYPT_ISSUER_NAME };

package/src/cli/docker-compose.js

@@ -192,7 +192,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.3.76
+APP_TAG=v3.3.77
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest

package/src/cli/release.js

@@ -547,7 +547,9 @@ class UnderpostRelease {
       logger.info(`CI push commit message: ${commitMsg}`);
       shellExec(`node engine/bin clone --bare ${githubOrg}/${repoName}`);
       shellCd('/home/dd/engine');
-      shellExec(`node bin/build ${buildTarget}`);
+      // `--coverage` runs the suites the deploy's `docs.coverage` names so the published
+      // source carries the reports; without it the pod serves the unavailable page.
+      shellExec(`node bin/build ${buildTarget} --coverage`);
       shellCd('/home/dd/pwa-microservices-template');
       shellExec(`rm -rf ./.git`);
       shellExec(`mv ../${repoName}.git ./.git`);

package/src/cli/repository.js

@@ -2160,13 +2160,13 @@ Prevent build private config repo.`,
 
     /**
      * Ensures a deploy's public source repo (e.g. `engine-prototype`) is present
-     * next to the engine and reset to a pristine HEAD, so catalog `sourceMoves`
-     * can (re)pull custom sources even after a previous build moved them out of
-     * the source tree.
+     * next to the engine, so catalog `sourceMoves` the engine tree lacks can be
+     * copied in.
      *
-     * Clones `../<repoName>` when missing; otherwise restores a clean checkout
-     * (`git checkout .` brings back any moved-out tracked files) and pulls latest.
-     * Mirrors the sibling-repo handling used by `syncPrivateConf`.
+     * Clones `../<repoName>` when missing; otherwise fast-forwards it. The working
+     * tree is never reset: it is the git view of edits made in the engine tree,
+     * which ignores those paths, so a pending change there is review material, not
+     * something to discard.
      *
      * @param {string} repoName - Public source repo name (e.g. `engine-prototype`).
      * @returns {boolean} `true` when the repo is available on disk.
@@ -2182,9 +2182,7 @@ Prevent build private config repo.`,
       } else {
         const repoAbsPath = path.resolve(repoPath);
         shellExec(`git config --global --add safe.directory '${repoAbsPath}'`);
-        shellExec(`cd ${repoPath} && git checkout . && git clean -f -d && underpost pull . ${gitUri}`, {
-          silent: true,
-        });
+        shellExec(`cd ${repoPath} && underpost pull . ${gitUri}`, { silent: true });
       }
       return fs.existsSync(repoPath);
     },

package/src/cli/run.js

@@ -3079,7 +3079,7 @@ EOF`);
         const hostListenResult = etcHostFactory(hosts);
         logger.info(hostListenResult.renderHosts);
       }
-      const version = 'v3.3.76';
+      const version = 'v3.3.77';
       const instanceOptionsFactory = (deployId, instanceId) => ({
         ...options,
         ...clusterContextFactory(clusterType),
@@ -3518,10 +3518,17 @@ EOF`);
           logger.info('[gateway-status] Backend probe (same Host and path, bypassing Envoy)', { backendProbes });
           // Only the rule the browser actually hit is comparable, so judge on
           // the root rule rather than on every rule of the route.
+          // The gateway answer carries the `server` header (`502 (nginx)`), the
+          // direct one is the bare code: compared as strings, every relayed status
+          // read as a routing fault, and the data plane log was dumped on a healthy
+          // edge whose only problem was an absent workload.
+          const statusCode = (answer) => /^([0-9]{3})/.exec(`${answer ?? ''}`)?.[1];
           const rootProbes = backendProbes.filter((entry) => entry.request.endsWith('/'));
-          const appFault = rootProbes.filter((entry) => `${entry.direct}` === `${entry.gateway}`);
+          const appFault = rootProbes.filter(
+            (entry) => statusCode(entry.direct) && statusCode(entry.direct) === statusCode(entry.gateway),
+          );
           const gatewayFault = rootProbes.filter(
-            (entry) => /^[0-9]{3}$/.test(entry.direct) && `${entry.direct}` !== `${entry.gateway}`,
+            (entry) => statusCode(entry.direct) && statusCode(entry.direct) !== statusCode(entry.gateway),
           );
           if (gatewayFault.length > 0) {
             logger.warn(

package/src/client/components/core/Badge.js

@@ -7,7 +7,6 @@ class Badge {
   static async instance(options = { id: '', type: 'circle-red', classList: '', text: '', style: '' }) {
     if (!options.id) options.id = getId(Badge.Tokens, 'badge-');
     else options.id = 'badge-' + options.id;
-    if (options && options.style && !options.style.color) options.style.color = 'white';
     if (!options.classList) options.classList = '';
     const { id, type } = options;
     Badge.Tokens[id] = { ...options };

package/src/client/components/core/CssCore.js

@@ -53,23 +53,30 @@ const CssCommonCore = async () => {
       .btn-label-content {
         top: 15px;
       }
+      /* Badge: one dark chip in every theme, so its lettering is always white — a caller
+         only sets a color when it also sets the background (see Badge.instance style). */
       .badge {
         min-width: 20px;
         height: 20px;
         border-radius: 3px;
         background: #3b434b;
+        color: white;
         position: relative;
         font-size: 12px;
         font-family: arial;
       }
       .badge-text {
-        /* color: white; */
         padding: 3px 6px 0px 6px;
       }
       .badge-notification-circle-red {
         background: #bd0c0c;
         border-radius: 50%;
       }
+      /* Unread dot over a menu button icon; the label reads left-to-right in both menu modes. */
+      .badge-notification-menu {
+        top: -33px;
+        left: 24px;
+      }
       .top-box-profile-container {
         top: 0px;
         right: 0px;

package/src/client/components/core/Modal.js

@@ -415,16 +415,18 @@ class Modal {
               },
               { key: `slide-menu-${idModal}` },
             );
-            // The fixed hamburger only opens the menu: it shows while the top bar is collapsed
-            // and the menu is closed. An open menu (50px or full) carries its own controls and
-            // already pushes the views aside, so neither the button nor the title padding apply.
+            // The fixed hamburger stands in for the top bar's while it is collapsed, opening and
+            // closing the menu alike. Its 50px corner is kept clear two ways: the menu content is
+            // padded down while it shows, and a view title is padded right only while the menu
+            // is closed — an open menu (50px or full) already pushes the views aside.
             const syncFixedMenuButton = () => {
               const fixed = s(`.main-btn-menu-top-fixed-container`);
               if (!fixed) return;
               const collapsed = s(`.main-body-btn-ui-close`) && s(`.main-body-btn-ui-close`).classList.contains('hide');
-              const active = collapsed && Modal.Data[idModal][options.mode].width === 0;
-              fixed.classList[active ? 'remove' : 'add']('hide');
-              s('body').classList[active ? 'add' : 'remove']('main-btn-menu-top-fixed-active');
+              const menuClosed = Modal.Data[idModal][options.mode].width === 0;
+              fixed.classList[collapsed ? 'remove' : 'add']('hide');
+              s('body').classList[collapsed ? 'add' : 'remove']('main-btn-menu-top-fixed-active');
+              s('body').classList[collapsed && menuClosed ? 'add' : 'remove']('main-btn-menu-top-fixed-title-offset');
             };
             barConfig.buttons.menu.onClick = () => {
               Modal.Data[idModal][options.mode].width = slideMenuWidth;
@@ -548,17 +550,24 @@ class Modal {
                       ${await BtnIcon.instance({
                         style: `height: 100%`,
                         class: `in fll main-btn-menu-top action-bar-box action-btn-center-top-fixed`,
-                        label: html`<div class="abs center">${barConfig.buttons.menu.label}</div>`,
+                        label: html`<div class="abs center">
+                          <span class="btn-bar-center-icon-close hide">${barConfig.buttons.close.label}</span>
+                          <span class="btn-bar-center-icon-menu">${barConfig.buttons.menu.label}</span>
+                        </div>`,
                       })}
                     </div>
                     <style>
+                      /* The menu content starts below the fixed hamburger while it shows. */
+                      body.main-btn-menu-top-fixed-active .html-${idModal} {
+                        padding-top: ${originHeightTopBar}px;
+                      }
                       /* View modals sit at top: 0 while the top bar is collapsed; keep their
                          title clear of the fixed hamburger. The padding eases at the same pace
                          the views slide so the title moves once, not a jump and a slide back. */
                       .title-main-modal {
                         transition: padding-left 0.3s;
                       }
-                      body.main-btn-menu-top-fixed-active .title-main-modal {
+                      body.main-btn-menu-top-fixed-title-offset .title-main-modal {
                         padding-left: ${originHeightTopBar}px;
                       }
                     </style>
@@ -2884,28 +2893,18 @@ const renderViewTitle = (
     </div>`;
 };
 
-const buildBadgeToolTipMenuOption = (id, sideKey = 'left') => {
-  const option = {
-    id: `tooltip-content-main-btn-${id}`,
-    text: `${Translate.instance(`${id}`)}`,
-    classList: 'tooltip-menu',
-    style: { top: `-40px` },
-  };
-  switch (sideKey) {
-    case 'left':
-      option.style.left = '60px';
-
-      break;
-
-    case 'right':
-      option.style.right = '60px';
-      break;
-
-    default:
-      break;
-  }
-  return option;
-};
+/**
+ * Tooltip badge for a collapsed menu button. ToolTip places it beside the button on the side
+ * the menu leaves free, read from the menu mode when it shows — so a shell never pins an
+ * offset that only holds for one of 'slide-menu' or 'slide-menu-right'.
+ * @param {string} id - Translation key and tooltip id suffix.
+ * @param {'left'|'right'} [sideKey] - Forces the side the menu sits on; omit to follow the mode.
+ */
+const buildBadgeToolTipMenuOption = (id, sideKey) => ({
+  id: `tooltip-content-main-btn-${id}`,
+  text: `${Translate.instance(`${id}`)}`,
+  classList: `tooltip-menu${sideKey ? ` tooltip-menu-side-${sideKey}` : ''}`,
+});
 
 const isSubMenuOpen = (subMenuId) => {
   return s(`.down-arrow-submenu-${subMenuId}`) && s(`.down-arrow-submenu-${subMenuId}`).style.rotate === '180deg';

package/src/client/components/core/ToolTip.js

@@ -58,6 +58,21 @@ class ToolTip {
       const tooltipRect = tooltipEl.getBoundingClientRect();
       let top = containerRect.bottom + window.scrollY + 5;
       let left = containerRect.left + window.scrollX + containerRect.width / 2 - tooltipRect.width / 2;
+      if (options.useMenuBtn) {
+        // Beside the collapsed menu button, on the side the menu leaves free: a right-hand menu
+        // sits on the window edge, so its tooltips open leftwards. A shell may pin the side.
+        const pinned = tooltipEl.querySelector('.tooltip-menu-side-right')
+          ? 'right'
+          : tooltipEl.querySelector('.tooltip-menu-side-left')
+            ? 'left'
+            : null;
+        const menuSide = pinned || (Modal.Data['modal-menu'].options.mode === 'slide-menu-right' ? 'right' : 'left');
+        top = containerRect.top + window.scrollY + (containerRect.height - tooltipRect.height) / 2;
+        left =
+          menuSide === 'right'
+            ? containerRect.left + window.scrollX - tooltipRect.width - 10
+            : containerRect.right + window.scrollX + 10;
+      }
       // Adjust if it goes off-screen
       if (left < 0) left = 5;
       if (left + tooltipRect.width > window.innerWidth) {