@k2b/cloud 0.27.0 → 0.29.0

package/src/shared/markdown/index.ts

@@ -23,7 +23,7 @@ import { taskListExtension } from "./extensions/task-list";
 type MarkdownProfile = "content" | "help";
 type LinkStyle = "widget" | "plain";
 
-const createMarked = (profile: MarkdownProfile, links: LinkStyle, infoBlocks: MarkedExtension) => {
+const createMarked = (profile: MarkdownProfile, links: LinkStyle, infoBlocks: MarkedExtension, locale?: string) => {
   const marked = new Marked();
 
   marked.use({
@@ -37,7 +37,8 @@ const createMarked = (profile: MarkdownProfile, links: LinkStyle, infoBlocks: Ma
   marked.use(taskListExtension());
   marked.use(tablesExtension());
   // Plain links keep marked's own renderer: an anchor around the link text.
-  if (links === "widget") marked.use(linksExtension({ internalTarget: profile === "help" ? "_self" : "_blank" }));
+  // Cloud links are calm reference pills and quiet web links from `@k2b/ui`.
+  if (links === "widget") marked.use(linksExtension({ internalTarget: profile === "help" ? "_self" : "_blank", locale }));
   marked.use(imagesExtension());
   marked.use(katexExtension());
   marked.use(codeExtension());
@@ -58,7 +59,7 @@ const markedFor = (profile: MarkdownProfile, links: LinkStyle = "widget", locale
   const byStyle = instances.get(infoBlocks) ?? new Map<string, Marked>();
   instances.set(infoBlocks, byStyle);
   const key = `${profile}:${links}`;
-  const instance = byStyle.get(key) ?? createMarked(profile, links, infoBlocks);
+  const instance = byStyle.get(key) ?? createMarked(profile, links, infoBlocks, locale);
   byStyle.set(key, instance);
   return instance;
 };
@@ -66,7 +67,7 @@ const markedFor = (profile: MarkdownProfile, links: LinkStyle = "widget", locale
 const marked = markedFor("content");
 
 export type MarkdownRenderOptions = {
-  /** `"plain"` renders each link as an ordinary anchor around its text, for HTML read outside Cloud such as email. */
+  /** `"plain"` renders each link as an ordinary anchor around its text, for HTML read outside Cloud such as email. The default renders references to Cloud content as calm pills and web links as quiet text links. */
   links?: LinkStyle;
   /** Request locale for the screen-reader names of untitled info blocks. Defaults to English on the server and the page language in the browser. */
   locale?: string;
@@ -111,7 +112,15 @@ const sanitizeRenderedHtml = (html: string): string =>
     ],
     allowedAttributes: {
       "*": ["aria-hidden", "aria-label", "class", "data-help-icon", "data-tone", "id", "title"],
-      a: ["href", "name", "rel", "target", "title"],
+      a: [
+        "href",
+        "name",
+        "rel",
+        "target",
+        "title",
+        { name: "data-link", multiple: false, values: ["web", "mail"] },
+        { name: "data-reference", multiple: false, values: ["pdf", "image", "design", "file", "note", "heading", "task", "page"] },
+      ],
       annotation: ["encoding"],
       aside: [{ name: "role", multiple: false, values: ["note"] }],
       code: ["class"],

package/src/shared/markdown/shared.ts

@@ -27,10 +27,3 @@ export const IMAGE_STYLES = {
   img: "block max-h-[400px] rounded border border-gray-200 dark:border-gray-700",
   caption: "text-sm text-gray-500 dark:text-gray-400 mt-2 italic",
 } as const;
-
-/** Link widget styles */
-export const LINK_STYLES = {
-  link: "md-link-widget",
-  label: "md-link-label",
-  icon: "md-link-icon",
-} as const;

package/src/shared/redirect.ts

@@ -9,7 +9,8 @@ export const normalizeRedirectTo = (value: string | null | undefined): string |
 
   try {
     const url = new URL(trimmed, REDIRECT_BASE);
-    if (url.origin !== REDIRECT_BASE) return undefined;
+    // Dot segments can resolve to `//host`, which a browser reads as another host.
+    if (url.origin !== REDIRECT_BASE || url.pathname.startsWith("//")) return undefined;
     return `${url.pathname}${url.search}${url.hash}`;
   } catch {
     return undefined;

package/src/shared/template-rendering.ts

@@ -1,10 +1,24 @@
-import { Liquid } from "liquidjs";
+import {
+  AssertionError,
+  Context,
+  defaultOperators,
+  type Emitter,
+  type FilterImplOptions,
+  Liquid,
+  LiquidError,
+  type Operators,
+  toValue,
+  toValueSync,
+} from "liquidjs";
 
 const TEMPLATE_MAX_BYTES = 200_000;
 const RENDER_MAX_BYTES = 300_000;
+// Synchronous rendering blocks every request in the app process. Legitimate templates
+// take milliseconds; keep this well below normal request latency budgets.
+const RENDER_TIMEOUT_MS = 1_000;
 
 type LiquidEngine = Liquid;
-export type LiquidTemplateErrorReason = "render_too_large";
+export type LiquidTemplateErrorReason = "render_too_large" | "render_timeout" | "render_memory_limit";
 
 export class LiquidTemplateError extends Error {
   constructor(
@@ -22,6 +36,7 @@ export type LiquidTemplateOptions = {
   escapeOutput?: boolean | ((value: unknown) => string);
   templateMaxBytes?: number;
   renderMaxBytes?: number;
+  renderTimeoutMs?: number;
   memoryLimit?: number;
 };
 
@@ -52,6 +67,35 @@ const TEMPLATE_TAG_RE = /{%-?\s*([A-Za-z_][A-Za-z0-9_]*)\b/g;
 
 const byteLength = (value: string): number => new TextEncoder().encode(value).byteLength;
 
+class BoundedEmitter implements Emitter {
+  buffer = "";
+  private bytes = 0;
+  private lastCodeUnit = 0;
+
+  constructor(private readonly maxBytes: number) {}
+
+  write(input: unknown): void {
+    const value: unknown = toValue(input);
+    // Match LiquidJS's emitter: nil is empty, arrays concatenate their elements.
+    if (value === null || value === undefined) return;
+    if (Array.isArray(value)) {
+      for (const item of value) this.write(item);
+      return;
+    }
+    const chunk = String(value);
+    if (!chunk) return;
+    const last = this.lastCodeUnit;
+    const first = chunk.charCodeAt(0);
+    // A surrogate pair split across writes encodes as four bytes, rather than six.
+    const paired = last >= 0xd800 && last <= 0xdbff && first >= 0xdc00 && first <= 0xdfff;
+    const bytes = this.bytes + byteLength(chunk) - (paired ? 2 : 0);
+    if (bytes > this.maxBytes) throw new LiquidTemplateError("render_too_large", "Rendered template is too large");
+    this.bytes = bytes;
+    this.lastCodeUnit = chunk.charCodeAt(chunk.length - 1);
+    this.buffer += chunk;
+  }
+}
+
 export const escapeTemplateOutput = (value: unknown): string =>
   String(value).replace(/[&<>"'`=/]/g, (char) => {
     switch (char) {
@@ -76,16 +120,34 @@ export const escapeTemplateOutput = (value: unknown): string =>
     }
   });
 
+const expandedTextLength = (input: unknown): number => {
+  const value: unknown = toValue(input);
+  if (typeof value === "string") return value.length;
+  if (Array.isArray(value)) return value.reduce((length: number, item: unknown) => length + expandedTextLength(item), 0);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value).length;
+  return 0;
+};
+
 const createEngine = (options: LiquidTemplateOptions = {}) => {
   const outputEscape =
     typeof options.escapeOutput === "function" ? options.escapeOutput : options.escapeOutput === false ? undefined : escapeTemplateOutput;
+  const operators: Operators = {};
+  for (const [name, handler] of Object.entries(defaultOperators)) {
+    operators[name] = (...args: [unknown, Context] | [unknown, unknown, Context]): boolean => {
+      const result: boolean = Reflect.apply(handler, undefined, args);
+      const context = args[args.length - 1];
+      if (context instanceof Context) context.renderLimit.check(performance.now());
+      return result;
+    };
+  }
   const engine = new Liquid({
+    operators,
     strictVariables: true,
     strictFilters: true,
     ownPropertyOnly: true,
     ...(outputEscape ? { outputEscape } : {}),
     parseLimit: options.templateMaxBytes ?? TEMPLATE_MAX_BYTES,
-    renderLimit: options.renderMaxBytes ?? RENDER_MAX_BYTES,
+    renderLimit: options.renderTimeoutMs ?? RENDER_TIMEOUT_MS,
     memoryLimit: options.memoryLimit ?? 2_000_000,
     cache: false,
     dynamicPartials: false,
@@ -94,7 +156,42 @@ const createEngine = (options: LiquidTemplateOptions = {}) => {
     partials: [],
   });
 
+  const renderTemplates = engine.renderer.renderTemplates.bind(engine.renderer);
+  engine.renderer.renderTemplates = function* (templates, context, emitter) {
+    // Capture renders without an emitter; bound its intermediate buffer as well.
+    const result = yield* renderTemplates(
+      templates,
+      context,
+      emitter ?? new BoundedEmitter(Math.max(options.renderMaxBytes ?? RENDER_MAX_BYTES, RENDER_MAX_BYTES)),
+    );
+    // LiquidJS checks before templates and every loop body (even an empty one).
+    // Check after them too, so a slow final filter cannot return over budget.
+    context.renderLimit.check(performance.now());
+    return result;
+  };
+
+  for (const name of ["push", "concat", "unshift", "map"]) {
+    const filter = engine.filters[name];
+    if (!filter) continue;
+    const handler = typeof filter === "function" ? filter : filter.handler;
+    const bounded: FilterImplOptions = function* (...args: [unknown, ...unknown[]]): Generator<unknown, unknown, unknown> {
+      const result: unknown = yield handler.apply(this, args);
+      // Charge added text only; charging the left array again would compound.
+      this.context.memoryLimit.use(expandedTextLength(name === "map" ? result : args[1]));
+      return result;
+    };
+    engine.registerFilter(name, typeof filter === "function" ? bounded : { ...filter, handler: bounded });
+  }
   for (const [name, filter] of Object.entries(options.filters ?? {})) engine.registerFilter(name, filter);
+  for (const [name, filter] of Object.entries(engine.filters)) {
+    const handler = typeof filter === "function" ? filter : filter.handler;
+    const timed: FilterImplOptions = function* (...args: [unknown, ...unknown[]]): Generator<unknown, unknown, unknown> {
+      const result: unknown = yield handler.apply(this, args);
+      this.context.renderLimit.check(performance.now());
+      return result;
+    };
+    engine.registerFilter(name, typeof filter === "function" ? timed : { ...filter, handler: timed });
+  }
   return engine;
 };
 
@@ -126,11 +223,27 @@ export const validateLiquidTemplate = (
 export const renderLiquidTemplate = (template: string, data: Record<string, unknown>, options: LiquidTemplateOptions = {}): string => {
   const valid = validateLiquidTemplate(template, options);
   if (!valid.ok) throw new Error(valid.error);
-  const rendered = engineFor(options).parseAndRenderSync(template, data);
-  if (byteLength(rendered) > (options.renderMaxBytes ?? RENDER_MAX_BYTES)) {
-    throw new LiquidTemplateError("render_too_large", "Rendered template is too large");
+  const engine = engineFor(options);
+  const context = new Context(data, engine.options, { sync: true }, { liquid: engine });
+  const emitter = new BoundedEmitter(options.renderMaxBytes ?? RENDER_MAX_BYTES);
+  try {
+    toValueSync(engine.renderer.renderTemplates(engine.parse(template), context, emitter));
+    return emitter.buffer;
+  } catch (error) {
+    // LiquidJS wraps emitter and limiter failures in RenderError.originalError.
+    let original = error;
+    while (original instanceof LiquidError && original.originalError) original = original.originalError;
+    if (original instanceof LiquidTemplateError) throw original;
+    if (original instanceof AssertionError) {
+      if (original.message === "template render limit exceeded") {
+        throw new LiquidTemplateError("render_timeout", "Template rendering exceeded its time budget");
+      }
+      if (original.message === "memory alloc limit exceeded") {
+        throw new LiquidTemplateError("render_memory_limit", "Template rendering exceeded its memory limit");
+      }
+    }
+    throw error;
   }
-  return rendered;
 };
 
 export const liquidTemplateVariables = (template: string, options: LiquidTemplateOptions = {}): string[] => {

package/src/ssr/AppBadge.tsx

@@ -0,0 +1,30 @@
+import { useLocale } from "@k2b/ui";
+import { Show } from "solid-js";
+import { appBadgeCount } from "./app-badges";
+import { railMessages } from "./rail-messages";
+
+/** What a screen reader hears after the app name; empty without a count. Says no more than the "99+" shown. */
+export const useAppBadgeDescription = (endpoint: () => string | undefined) => {
+  const locale = useLocale();
+  return () => {
+    const count = appBadgeCount(endpoint());
+    const t = railMessages.resolve([locale()]).t;
+    return count > 99 ? t.badgeMany : count > 0 ? t.badge({ count }) : "";
+  };
+};
+
+/**
+ * Count on the corner of an app icon. It is positioned over the icon and never
+ * takes layout space, so appearing, growing to "99+", or clearing moves
+ * nothing. Decorative: the link carries the description.
+ */
+export function AppBadge(props: { endpoint?: string }) {
+  const count = () => appBadgeCount(props.endpoint);
+  return (
+    <Show when={count() > 0}>
+      <span class="cloud-app-badge" aria-hidden="true">
+        {count() > 99 ? "99+" : count()}
+      </span>
+    </Show>
+  );
+}

package/src/ssr/AppLaunchpadPanel.tsx

@@ -3,6 +3,7 @@ import { IconButton, ScrollArea, TextInput, useLocale } from "@k2b/ui";
 import { createSignal, For, type JSX, Show } from "solid-js";
 import { Dynamic } from "solid-js/web";
 import type { CloudTheme } from "../shared/theme";
+import { AppBadge, useAppBadgeDescription } from "./AppBadge";
 import { MobileProfileActions } from "./MobileProfileActions";
 import { platformMessages } from "./platform-messages";
 import { openRailEditor } from "./RailEditor";
@@ -17,6 +18,8 @@ export type AppLaunchpadApp = {
   href: string;
   description?: string;
   accent?: string;
+  /** The app's `nav.badge` endpoint. */
+  badge?: string;
 };
 
 export type AppLaunchpadLegalLink = {
@@ -119,39 +122,57 @@ export const AppLaunchpadPanel = (
         <section class="mb-5" aria-label={t().shortcuts}>
           <div class="flex flex-wrap justify-center gap-3">
             <For each={shortcuts()}>
-              {(shortcut) => (
-                <a
-                  onClick={follow}
-                  href={shortcut.href}
-                  class="group flex w-16 min-w-0 flex-col items-center gap-1 rounded-lg p-1 text-center focus-ui"
-                >
-                  <span class="grid h-9 w-9 place-items-center rounded-xl bg-[var(--ui-hover)] text-lg transition-colors group-hover:bg-[var(--ui-active)]">
-                    <i class={shortcut.iconClass} aria-hidden="true" />
-                  </span>
-                  <span class="max-w-full truncate text-[11px] font-medium text-primary dark:text-white">{shortcut.label}</span>
-                </a>
-              )}
+              {(shortcut) => {
+                const badge = useAppBadgeDescription(() => shortcut.badge);
+                return (
+                  <a
+                    onClick={follow}
+                    href={shortcut.href}
+                    class="group flex w-16 min-w-0 flex-col items-center gap-1 rounded-lg p-1 text-center focus-ui"
+                  >
+                    <span class="relative grid h-9 w-9 place-items-center rounded-xl bg-[var(--ui-hover)] text-lg transition-colors group-hover:bg-[var(--ui-active)]">
+                      <i class={shortcut.iconClass} aria-hidden="true" />
+                      <AppBadge endpoint={shortcut.badge} />
+                    </span>
+                    <span class="max-w-full truncate text-[11px] font-medium text-primary dark:text-white">
+                      {shortcut.label}
+                      <Show when={badge()}>
+                        <span class="sr-only">, {badge()}</span>
+                      </Show>
+                    </span>
+                  </a>
+                );
+              }}
             </For>
           </div>
         </section>
       </Show>
       <div class="launchpad-apps-grid flex flex-wrap justify-center gap-x-4 gap-y-4 sm:gap-x-7 sm:gap-y-6">
         <For each={apps()}>
-          {(app) => (
-            <a
-              onClick={follow}
-              href={app.href}
-              class="launchpad-app group flex w-[4.75rem] min-w-0 flex-col items-center gap-1.5 rounded-2xl p-1 text-center focus-ui sm:w-[6.25rem] sm:gap-2 sm:p-2"
-            >
-              <span
-                class="app-icon grid h-12 w-12 place-items-center rounded-[0.95rem] text-[1.25rem] sm:h-16 sm:w-16 sm:rounded-[1.25rem] sm:text-[1.7rem]"
-                style={appIconStyle(app)}
+          {(app) => {
+            const badge = useAppBadgeDescription(() => app.badge);
+            return (
+              <a
+                onClick={follow}
+                href={app.href}
+                class="launchpad-app group flex w-[4.75rem] min-w-0 flex-col items-center gap-1.5 rounded-2xl p-1 text-center focus-ui sm:w-[6.25rem] sm:gap-2 sm:p-2"
               >
-                <i class={app.iconClass} />
-              </span>
-              <span class="max-w-full truncate text-[11px] font-medium text-primary sm:text-xs dark:text-white">{app.label}</span>
-            </a>
-          )}
+                <span
+                  class="app-icon relative grid h-12 w-12 place-items-center rounded-[0.95rem] text-[1.25rem] sm:h-16 sm:w-16 sm:rounded-[1.25rem] sm:text-[1.7rem]"
+                  style={appIconStyle(app)}
+                >
+                  <i class={app.iconClass} />
+                  <AppBadge endpoint={app.badge} />
+                </span>
+                <span class="max-w-full truncate text-[11px] font-medium text-primary sm:text-xs dark:text-white">
+                  {app.label}
+                  <Show when={badge()}>
+                    <span class="sr-only">, {badge()}</span>
+                  </Show>
+                </span>
+              </a>
+            );
+          }}
         </For>
       </div>
       <Show when={!apps().length && !shortcuts().length}>

package/src/ssr/GlobalAnnouncements.island.tsx

@@ -102,7 +102,7 @@ export default function GlobalAnnouncements(props: Props) {
                 <MarkdownView
                   trustedHtml={banner.bodyHtml}
                   headingScale="compact"
-                  class="max-h-36 overflow-y-auto overscroll-contain pr-1 [&_p]:my-0"
+                  class="-mx-2 max-h-36 overflow-y-auto overscroll-contain pl-2 pr-3 [&_p]:my-0"
                 />
               </NoticeCard>
               <IconButton size="sm" label={t().dismissBanner} onClick={() => dismissBanner(banner.version)}>

package/src/ssr/IslandError.tsx

@@ -0,0 +1,33 @@
+import type { IslandErrorProps } from "@k2b/ssr";
+import { i18n } from "@k2b/stdlib";
+import { Button, Placeholder, useLocale } from "@k2b/ui";
+
+const messages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: { title: "This section could not be displayed.", retry: "Try again" },
+    de: { title: "Dieser Bereich konnte nicht angezeigt werden.", retry: "Erneut versuchen" },
+  },
+});
+
+/**
+ * Takes the place of an island or client component whose rendering failed.
+ * `defineApp` hands it to @k2b/ssr as `errorFallback`, so every island of every
+ * app gets it; the locale comes from `<html lang>`. "Try again" remounts the
+ * island with its original props.
+ */
+export default function IslandError(props: IslandErrorProps) {
+  const locale = useLocale();
+  const t = () => messages.resolve([locale()]).t;
+  return (
+    <Placeholder
+      state="error"
+      title={t().title}
+      action={
+        <Button variant="secondary" onClick={() => props.reset()}>
+          {t().retry}
+        </Button>
+      }
+    />
+  );
+}

package/src/ssr/Layout.tsx

@@ -61,6 +61,7 @@ function buildNavLinks(
       match: resolveNavMatch(app) ?? app.nav.href.split("?")[0] ?? app.nav.href,
       description: app.description,
       accent: app.appearance?.accent,
+      badge: app.nav.badge,
     } satisfies LayoutAppLink,
   }));
   const primary = links.filter((entry) => entry.section === "primary").map((entry) => entry.link);
@@ -75,6 +76,7 @@ function buildNavLinks(
       match: "/admin",
       description: t.platformAdministration,
       accent: undefined,
+      badge: undefined,
     });
   }
   return { primary, more };
@@ -166,6 +168,7 @@ export default function Layout(props: LayoutProps) {
     href: app.href,
     description: app.description,
     accent: app.accent,
+    badge: app.badge,
   }));
   const searchLinks = navigationSearchItems(
     runtime.apps,

package/src/ssr/LayoutHelp.tsx

@@ -95,11 +95,13 @@ const registerTopic = (topic: HelpTopic) => {
 /** Register an app's server-prepared Markdown manifest with the shared help UI. */
 export function LayoutHelpDocuments(props: LayoutHelpDocumentsProps) {
   onMount(() => {
-    window.__cloudLayoutHelpPageBase = props.pageBase;
+    // Cleanup runs while this unmounts, when a parent `<Show>` may already have dropped the props' source.
+    const pageBase = props.pageBase;
+    window.__cloudLayoutHelpPageBase = pageBase;
     const disposers = props.documents.map((document) => registerTopic({ ...document, kind: "document" }));
     onCleanup(() => {
       disposers.forEach((dispose) => dispose());
-      if (window.__cloudLayoutHelpPageBase === props.pageBase) delete window.__cloudLayoutHelpPageBase;
+      if (window.__cloudLayoutHelpPageBase === pageBase) delete window.__cloudLayoutHelpPageBase;
     });
   });
   return null;

package/src/ssr/RailApps.island.tsx

@@ -1,25 +1,29 @@
 import { ScrollArea, Tooltip, useLocale } from "@k2b/ui";
 import { createMemo, createSignal, For, onCleanup, onMount, Show } from "solid-js";
 import type { RailSnapshot } from "../contracts/rail-preferences";
+import { AppBadge, useAppBadgeDescription } from "./AppBadge";
 import { appAccentStyle } from "./app-appearance";
+import { watchAppBadges } from "./app-badges";
 import { RAIL_PREFERENCES_EVENT, readRailContext } from "./rail-context";
 import { projectRailNavigation, type RailApp, type RailLink, railLinkActive } from "./rail-navigation";
 
 function RailIcon(props: { link: RailLink; currentPath: string }) {
   let target: HTMLAnchorElement | undefined;
   const active = () => railLinkActive(props.link, props.currentPath);
+  const badge = useAppBadgeDescription(() => props.link.badge);
   return (
     <>
       <a
         ref={target}
         href={props.link.href}
-        class={`rail-item shrink-0 ${active() ? "rail-item-active" : ""}`}
-        aria-label={props.link.label}
+        class={`rail-item relative shrink-0 ${active() ? "rail-item-active" : ""}`}
+        aria-label={badge() ? `${props.link.label}, ${badge()}` : props.link.label}
         aria-current={active() ? "page" : undefined}
         style={appAccentStyle(props.link.accent)}
       >
         <i class={`${props.link.iconClass} text-base`} aria-hidden="true" />
         <span class="sr-only">{props.link.label}</span>
+        <AppBadge endpoint={props.link.badge} />
       </a>
       <Tooltip target={() => target} content={props.link.label} placement="right" delay={0} />
     </>
@@ -36,10 +40,13 @@ export default function RailApps(props: { apps: RailApp[]; settings: RailSnapsho
     const syncLocation = () => setCurrentPath(`${window.location.pathname}${window.location.search}${window.location.hash}`);
     sync();
     syncLocation();
+    // Every visible app, not only the rail's: the app grid shows the same counts.
+    const stopBadges = watchAppBadges(props.apps.flatMap((app) => (app.badge ? [app.badge] : [])));
     window.addEventListener(RAIL_PREFERENCES_EVENT, sync);
     window.addEventListener("popstate", syncLocation);
     window.addEventListener("hashchange", syncLocation);
     onCleanup(() => {
+      stopBadges();
       window.removeEventListener(RAIL_PREFERENCES_EVENT, sync);
       window.removeEventListener("popstate", syncLocation);
       window.removeEventListener("hashchange", syncLocation);

package/src/ssr/app-badges.ts

@@ -0,0 +1,93 @@
+import { createSignal } from "solid-js";
+import { APP_BADGES_REFRESH_EVENT } from "../browser/app-badges";
+
+/**
+ * Shortest time between two scheduled reads in one tab, and the longest one
+ * read may take. Badges are a hint to open an app, not a live view, so one
+ * read per minute keeps them current while someone works elsewhere without a
+ * steady stream of requests per tab.
+ */
+export const APP_BADGE_INTERVAL_MS = 60_000;
+
+// Keyed by endpoint, so a pinned app shortcut and the app's own entry share one
+// count. Only the browser ever writes it; server renders always see no badge.
+const [counts, setCounts] = createSignal<ReadonlyMap<string, number>>(new Map());
+
+/** The count for a declared `nav.badge` endpoint; 0 until the browser has read it. */
+export const appBadgeCount = (endpoint: string | undefined): number => (endpoint ? (counts().get(endpoint) ?? 0) : 0);
+
+/** A positive safe integer from an `AppNavBadge` body, else 0. */
+export const parseAppBadge = (body: unknown): number => {
+  if (typeof body !== "object" || body === null || !("count" in body)) return 0;
+  const count = body.count;
+  return typeof count === "number" && Number.isSafeInteger(count) && count > 0 ? count : 0;
+};
+
+const readBadge = async (endpoint: string, signal: AbortSignal): Promise<number> => {
+  try {
+    const response = await fetch(endpoint, { credentials: "same-origin", headers: { accept: "application/json" }, signal });
+    return response.status === 200 ? parseAppBadge(await response.json()) : 0;
+  } catch {
+    // An unreachable or failing app shows no badge rather than a stale one.
+    return 0;
+  }
+};
+
+let watching = false;
+
+/**
+ * Reads the badge endpoints after hydration, every interval while the tab is
+ * visible, when a hidden tab becomes visible again after the interval, and on
+ * `refreshAppBadges()`. A hidden tab sends nothing and keeps its schedule.
+ * Each endpoint has at most one read in flight, and its count shows as soon as
+ * that read settles, so a slow app delays only its own badge. A refresh while
+ * a read runs queues one more read after it instead of another request, and a
+ * read still running after the interval gives up. Returns a disposer.
+ */
+export const watchAppBadges = (endpoints: readonly string[]): (() => void) => {
+  const unique = [...new Set(endpoints)];
+  if (typeof window === "undefined" || unique.length === 0 || watching) return () => {};
+  watching = true;
+  const stopped = new AbortController();
+  // Endpoints with a read in flight, mapped to whether one more read waits for it.
+  const running = new Map<string, boolean>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let last = Number.NEGATIVE_INFINITY;
+
+  const read = (endpoint: string) => {
+    if (running.has(endpoint)) {
+      running.set(endpoint, true);
+      return;
+    }
+    running.set(endpoint, false);
+    void readBadge(endpoint, AbortSignal.any([stopped.signal, AbortSignal.timeout(APP_BADGE_INTERVAL_MS)])).then((count) => {
+      if (stopped.signal.aborted) return;
+      setCounts((previous) => new Map(previous).set(endpoint, count));
+      const queued = running.get(endpoint);
+      running.delete(endpoint);
+      if (queued && document.visibilityState !== "hidden") read(endpoint);
+    });
+  };
+  const refresh = () => {
+    // Leave the pending read in place, so the tab still reads on time once it is visible again.
+    if (document.visibilityState === "hidden") return;
+    clearTimeout(timer);
+    last = Date.now();
+    timer = setTimeout(refresh, APP_BADGE_INTERVAL_MS);
+    for (const endpoint of unique) read(endpoint);
+  };
+  const resume = () => {
+    if (document.visibilityState !== "hidden" && Date.now() - last >= APP_BADGE_INTERVAL_MS) refresh();
+  };
+
+  document.addEventListener("visibilitychange", resume);
+  window.addEventListener(APP_BADGES_REFRESH_EVENT, refresh);
+  refresh();
+  return () => {
+    watching = false;
+    clearTimeout(timer);
+    stopped.abort();
+    document.removeEventListener("visibilitychange", resume);
+    window.removeEventListener(APP_BADGES_REFRESH_EVENT, refresh);
+  };
+};

package/src/ssr/platform-messages.ts

@@ -98,7 +98,7 @@ export const platformMessages = i18n.define({
       skills: "Skills",
       projects: "Projekte",
       aiUsage: "Nutzung",
-      aiQuotas: "Assistant-Limits",
+      aiQuotas: "Assistenten-Limits",
       backgroundJobs: "Hintergrundaufgaben",
       apps: "Apps",
       appMenu: "Menü",

package/src/ssr/rail-messages.ts

@@ -32,6 +32,8 @@ export const railMessages = i18n.define({
       saveFailed: "Could not save app bar settings. Your edits are still here.",
       conflict: "The app bar changed in another editor. Cancel and reopen this editor to load the latest settings.",
       invalid: "Check shortcut titles, links and icons. Each app can be pinned once; settings must fit within 16 KiB.",
+      badge: ({ count }: { count: number }) => `${count} new`,
+      badgeMany: "more than 99 new",
     },
     de: {
       managed: "Von der Administration bereitgestellt",
@@ -63,6 +65,8 @@ export const railMessages = i18n.define({
       conflict:
         "Die App-Leiste wurde in einem anderen Editor geändert. Brich ab und öffne den Editor erneut, um den aktuellen Stand zu laden.",
       invalid: "Prüfe Titel, Links und Icons. Jede App kann einmal angeheftet werden; die Einstellungen dürfen höchstens 16 KiB belegen.",
+      badge: ({ count }) => `${count} neu`,
+      badgeMany: "mehr als 99 neu",
     },
   },
 });

package/src/ssr/rail-navigation.ts

@@ -9,6 +9,8 @@ export type RailApp = {
   defaultVisible: boolean;
   description?: string;
   accent?: string;
+  /** The app's `nav.badge` endpoint. */
+  badge?: string;
 };
 export type RailLink = Omit<RailApp, "defaultVisible"> & { exact?: boolean };