@k2b/cloud 0.41.0 → 0.42.0

package/src/shared-text/snapshots.ts

@@ -0,0 +1,340 @@
+import { type Job, type JobConfig, RetentionGapError, type Topic, type Worker } from "@k2b/sync";
+import * as Y from "yjs";
+import { logger } from "../services/logging";
+import { compareStreamCursor } from "./cursor";
+import { createDoc } from "./documents";
+import { applySharedTextEvent, MalformedSharedTextEventError, SHARED_TEXT_NAME, sharedTextNodeId } from "./events";
+import type { SharedTextContributor, SharedTextSaveInput, SharedTextStoredState, SharedTextSyncEvent } from "./types";
+
+const ACK_WAIT_MS = 120_000;
+const RECONCILE_LIMIT = 5_000;
+// Each lookup is a short-lived tenant replay stopped after its first event; 16 is far below 5,000 latestCursor lookups per scan page.
+// In steady state, only documents edited within the last snapshot delay or stalled documents remain behind.
+const BACKLOG_LOOKUPS = 16;
+
+export const sharedTextSnapshotJobConfig = (
+  config: Pick<JobConfig, "id" | "deadLetterRetention" | "terminalRetentionMs" | "dedupeWindowMs"> & {
+    retention: NonNullable<JobConfig["retention"]>;
+  },
+) =>
+  ({
+    id: config.id,
+    delivery: { ackWaitMs: ACK_WAIT_MS, maxAttempts: 20, backoffMs: [5_000] },
+    // Ordered by document across 8 partitions. Each process reconstructs one
+    // document at a time, keeping its memory budget fixed while a fleet can
+    // save up to 8 documents concurrently. Changing the count is a resource change.
+    ordering: { mode: "partitioned" as const, partitions: 8 },
+    retention: config.retention,
+    terminalRetentionMs: config.terminalRetentionMs ?? 30 * 24 * 60 * 60 * 1000,
+    // 256 dead letters at Sync's 128 KiB payload limit plus its 4 KiB of
+    // dead-letter headroom, the depth Sync gives a job by default. A snapshot is
+    // dead-lettered only for incomplete or malformed history or after 20 failed
+    // attempts; each one carries a document ID and a cursor of a few hundred bytes.
+    deadLetterRetention: config.deadLetterRetention ?? { maxBytes: 256 * (128 * 1024 + 4096) },
+    ...(config.dedupeWindowMs === undefined ? {} : { dedupeWindowMs: config.dedupeWindowMs }),
+  }) satisfies JobConfig;
+
+export type SharedTextSnapshotRequest = { docId: string; targetCursor: string; reason: string };
+export type SharedTextSnapshotStore = {
+  /** Stable keyset order by docId; include only documents that take snapshots. */
+  list(options: { limit: number; after?: string; signal?: AbortSignal }): Promise<Array<{ docId: string; cursor: string | null }>>;
+  /** Anchor legacy cursors to this log before returning. */
+  load(docId: string, options: { signal?: AbortSignal }): Promise<SharedTextStoredState | null>;
+  /**
+   * Atomically fence restoreRevision and non-newer cursors. Apply projections
+   * only when the write was accepted, never when overtaken. Return normally
+   * when covered, gone or locked; throw after a restore if not already covered
+   * so the job retries from the current snapshot.
+   */
+  save(docId: string, input: SharedTextSaveInput): Promise<void>;
+  /** Preserve every valid retained update, including pending structs/deletes;
+   * save at a captured head with history incomplete. Lost bytes remain lost. */
+  recover(docId: string, cause: RetentionGapError | MalformedSharedTextEventError, options: { signal?: AbortSignal }): Promise<unknown>;
+  /** Move an idle cursor only while from is still stored and no newer event exists. */
+  advance(docId: string, input: { from: string; to: string; latest: string | null }): Promise<boolean>;
+};
+export type SharedTextSnapshotBacklog = {
+  log: string;
+  measuredAt: Date;
+  documents: number;
+  oldest: null | {
+    docId: string;
+    sequence: number;
+    ageMs: number | null;
+    sequenceDistance: number;
+    historyGap?: boolean;
+    /** The lookup budget left documents that may contain an older update. */
+    partial?: true;
+  };
+};
+type SnapshotLog = {
+  id: string;
+  topic(): Pick<Topic<SharedTextSyncEvent>, "head" | "latestCursor" | "cursorSequence" | "cursorAt" | "replay">;
+  firstSequence(): Promise<number>;
+};
+type SnapshotOptions = { log: SnapshotLog; store: SharedTextSnapshotStore; logger?: ReturnType<typeof logger> };
+type InputCodec<Input> = { encode(request: SharedTextSnapshotRequest): Input; decode(input: Input): SharedTextSnapshotRequest };
+type SnapshotJob<Input> = () => Pick<Job<Input>, "submit" | "process">;
+
+export function snapshots(
+  options: SnapshotOptions & { job: SnapshotJob<SharedTextSnapshotRequest>; input?: undefined },
+): ReturnType<typeof createSnapshots>;
+export function snapshots<Input>(
+  options: SnapshotOptions & { job: SnapshotJob<Input>; input: InputCodec<Input> },
+): ReturnType<typeof createSnapshots>;
+export function snapshots<Input>(
+  options: SnapshotOptions &
+    ({ job: SnapshotJob<SharedTextSnapshotRequest>; input?: undefined } | { job: SnapshotJob<Input>; input: InputCodec<Input> }),
+) {
+  if (options.input) return createSnapshots(options, options.job, options.input);
+  return createSnapshots(options, options.job, { encode: (request) => request, decode: (input) => input });
+}
+
+const createSnapshots = <Input>(
+  { log, store, logger: suppliedLogger }: SnapshotOptions,
+  job: SnapshotJob<Input>,
+  input: InputCodec<Input>,
+) => {
+  const output = suppliedLogger ?? logger("shared-text-snapshots");
+  let worker: Promise<Worker> | null = null;
+  let lastBacklog: SharedTextSnapshotBacklog | null = null;
+  const queue = async (request: SharedTextSnapshotRequest): Promise<void> => {
+    const sequence = log.topic().cursorSequence(request.targetCursor);
+    // A final unload at a newer cursor must not coalesce with an already settling snapshot.
+    await job().submit({ key: `${request.docId}:${sequence}`, coalesce: true, orderingKey: request.docId, input: input.encode(request) });
+  };
+  const start = async (): Promise<void> => {
+    if (worker) {
+      await worker;
+      return;
+    }
+    worker = job().process(
+      {
+        concurrency: 1,
+        onError: async ({ error, context }) => {
+          output.error("Snapshot job failed; missing or malformed history requires attention", {
+            docId: input.decode(context.input).docId,
+            error: error instanceof Error ? error.message : String(error),
+            attempt: context.attempt,
+          });
+          if (error instanceof RetentionGapError)
+            return {
+              action: "dead_letter",
+              reason: "Document history is incomplete; retained updates and pending dependencies were recovered",
+            };
+          if (error instanceof MalformedSharedTextEventError)
+            return {
+              action: "dead_letter",
+              reason: `Retained event cannot be applied; valid updates and pending dependencies were recovered: ${error.message}`,
+            };
+          return { action: "retry" };
+        },
+      },
+      async (context) => {
+        const request = input.decode(context.input);
+        const { docId } = request;
+        let heartbeatError: unknown;
+        const timer = setInterval(() => {
+          void context.heartbeat().catch((error) => {
+            heartbeatError = error;
+          });
+        }, 15_000);
+        try {
+          const topic = log.topic();
+          const initial = await store.load(docId, { signal: context.signal });
+          // Head BEFORE the document's latest event: once it is applied up to
+          // that event, the head is a valid (fresher) cursor for the snapshot.
+          const head = await topic.head();
+          // Cover queued older cursors in one replay; later jobs skip already saved state.
+          const target = await topic.latestCursor({ tenantId: docId });
+          if (!target) {
+            output.warn("Snapshot skipped: no retained events for the note", { docId, requestedCursor: request.targetCursor });
+            return;
+          }
+          const requestedAt = Date.now();
+          if (!initial || (initial.cursor && compareStreamCursor(initial.cursor, target) >= 0)) return;
+          const doc = createDoc(initial);
+          const contributors = new Map<string, SharedTextContributor>();
+          try {
+            let reachedTarget = false;
+            try {
+              for await (const event of topic.replay({
+                tenantId: docId,
+                after: initial.cursor ?? topic.cursorAt(0),
+                until: target,
+                signal: context.signal,
+              })) {
+                applySharedTextEvent(doc, event, docId);
+                if (event.data.actor)
+                  contributors.set(`${event.data.actor.kind}:${event.data.actor.id}`, {
+                    ...event.data.actor,
+                    lastContributedAt: event.publishedAt,
+                  });
+                reachedTarget = event.cursor === target;
+              }
+            } catch (error) {
+              // Preserve all valid retained updates and unresolved dependencies;
+              // record the missing/invalid history once in the DLQ after recovery.
+              if (error instanceof RetentionGapError || error instanceof MalformedSharedTextEventError)
+                await store.recover(docId, error, { signal: context.signal });
+              throw error;
+            }
+            context.signal.throwIfAborted();
+            if (heartbeatError) throw heartbeatError;
+            if (!reachedTarget) throw new Error("Snapshot replay did not reach its target");
+            await context.heartbeat();
+            context.signal.throwIfAborted();
+            await store.save(docId, {
+              state: Y.encodeStateAsUpdate(doc),
+              text: doc.getText(SHARED_TEXT_NAME).toString(),
+              cursor: compareStreamCursor(head, target) > 0 ? head : target,
+              restoreRevision: initial.restoreRevision,
+              requestedAt,
+              actor: null,
+              contributors: [...contributors.values()],
+            });
+          } finally {
+            doc.destroy();
+          }
+        } finally {
+          clearInterval(timer);
+        }
+      },
+    );
+    try {
+      await worker;
+      output.debug("Snapshot worker started", { nodeId: sharedTextNodeId });
+    } catch (error) {
+      worker = null;
+      throw error;
+    }
+  };
+  const stop = async (): Promise<void> => {
+    const active = await worker;
+    worker = null;
+    active?.stop();
+    await active?.drain({ timeoutMs: ACK_WAIT_MS });
+  };
+  const reconcile = async (config: { signal?: AbortSignal; heartbeat?: () => Promise<void> } = {}) => {
+    const topic = log.topic();
+    let after: string | undefined;
+    let checked = 0;
+    let queued = 0;
+    let advanced = 0;
+    let lastHeadSeq = 0;
+    const backlogCandidates: Array<{ docId: string; stored: string; storedSeq: number; latest: string }> = [];
+    let unretainedMinSeq: number | null = null;
+    while (true) {
+      config.signal?.throwIfAborted();
+      const candidates = await store.list({ limit: RECONCILE_LIMIT, after, signal: config.signal });
+      // Head BEFORE each document's latest event: an idle document is covered up to it.
+      const head = await topic.head();
+      const headSeq = topic.cursorSequence(head);
+      lastHeadSeq = headSeq;
+      const firstSeq = await log.firstSequence();
+      const refreshBelow = firstSeq + Math.floor((headSeq - firstSeq) / 2);
+      for (const candidate of candidates) {
+        config.signal?.throwIfAborted();
+        if (checked % 200 === 0) await config.heartbeat?.();
+        checked++;
+        let stored = candidate.cursor;
+        let shared = false;
+        if (stored) {
+          try {
+            topic.cursorSequence(stored);
+            shared = true;
+          } catch {
+            /* Legacy cursor: load anchors it. */
+          }
+        }
+        if (!shared) {
+          const loaded = await store.load(candidate.docId, { signal: config.signal });
+          if (!loaded) continue;
+          stored = loaded.cursor;
+        }
+        const latest = await topic.latestCursor({ tenantId: candidate.docId });
+        // A document without a stored cursor replays from the log's start, like the job does.
+        if (latest && (!stored || compareStreamCursor(latest, stored) > 0)) {
+          await queue({ docId: candidate.docId, targetCursor: latest, reason: "reconcile" });
+          queued++;
+          const from = stored ?? topic.cursorAt(0);
+          const storedSeq = topic.cursorSequence(from);
+          const index = backlogCandidates.findIndex((entry) => entry.storedSeq > storedSeq);
+          if (backlogCandidates.length === BACKLOG_LOOKUPS && index === -1) {
+            unretainedMinSeq = Math.min(unretainedMinSeq ?? storedSeq, storedSeq);
+          } else {
+            if (backlogCandidates.length === BACKLOG_LOOKUPS) {
+              const evicted = backlogCandidates.pop()!;
+              unretainedMinSeq = Math.min(unretainedMinSeq ?? evicted.storedSeq, evicted.storedSeq);
+            }
+            backlogCandidates.splice(index === -1 ? backlogCandidates.length : index, 0, {
+              docId: candidate.docId,
+              stored: from,
+              storedSeq,
+              latest,
+            });
+          }
+          continue;
+        }
+        if (!stored) continue;
+        if (topic.cursorSequence(stored) < refreshBelow && (await store.advance(candidate.docId, { from: stored, to: head, latest })))
+          advanced++;
+      }
+      if (candidates.length < RECONCILE_LIMIT) break;
+      after = candidates.at(-1)!.docId;
+    }
+    const report: SharedTextSnapshotBacklog = { log: log.id, measuredAt: new Date(), documents: queued, oldest: null };
+    for (const [index, candidate] of backlogCandidates.entries()) {
+      if (report.oldest && candidate.storedSeq + 1 >= report.oldest.sequence) break;
+      // The first lookup runs in the scan's last heartbeat interval, each later one
+      // renews it. A lost lease ends the run; only the lookup itself fails softly.
+      if (index > 0) await config.heartbeat?.();
+      const lookup = new AbortController();
+      const signal = config.signal ? AbortSignal.any([lookup.signal, config.signal]) : lookup.signal;
+      try {
+        let found = false;
+        for await (const event of topic.replay({ tenantId: candidate.docId, after: candidate.stored, until: candidate.latest, signal })) {
+          found = true;
+          if (!report.oldest || event.sequence < report.oldest.sequence)
+            report.oldest = {
+              docId: candidate.docId,
+              sequence: event.sequence,
+              ageMs: report.measuredAt.getTime() - event.publishedAt.getTime(),
+              sequenceDistance: lastHeadSeq - event.sequence,
+            };
+          break;
+        }
+        if (!found) throw new Error("Snapshot backlog replay returned no retained event");
+      } catch (error) {
+        config.signal?.throwIfAborted();
+        output.warn("Could not read shared text snapshot backlog history", {
+          docId: candidate.docId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        report.oldest = {
+          docId: candidate.docId,
+          sequence: candidate.storedSeq + 1,
+          ageMs: null,
+          sequenceDistance: lastHeadSeq - candidate.storedSeq,
+          historyGap: error instanceof RetentionGapError,
+        };
+        break;
+      } finally {
+        lookup.abort();
+      }
+      if (
+        candidate === backlogCandidates.at(-1) &&
+        report.oldest &&
+        unretainedMinSeq !== null &&
+        unretainedMinSeq + 1 < report.oldest.sequence
+      )
+        report.oldest.partial = true;
+    }
+    config.signal?.throwIfAborted();
+    output.info("Snapshot reconcile finished", { checked, queued, advanced });
+    output.info("Shared text snapshot backlog", report);
+    lastBacklog = report;
+    return { checked, queued, advanced };
+  };
+  return { queue, start, stop, reconcile, backlog: () => lastBacklog };
+};

package/src/ssr/AdminLayout.tsx

@@ -3,14 +3,16 @@ import type { JSX } from "solid-js/jsx-runtime";
 import type { PanelConsentSnapshot } from "../contracts/panel-context";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import { getLocale } from "../server/locale";
+import type { AuthContext } from "../server/middleware/auth";
 import type { LayoutAnnouncementsState } from "../server/middleware/settings";
 import AdminSidebar from "./AdminSidebar";
 import Layout from "./Layout";
 import { platformMessages } from "./platform-messages";
-import { getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
+import { getDisplayRuntimeContext, type RuntimeContext } from "./runtime";
 
 type Breadcrumb = { title: string; href?: string };
 type AdminLayoutContext = {
+  get(key: "actor"): AuthContext["Variables"]["actor"] | undefined;
   get(key: "panelConsent"): PanelConsentSnapshot | undefined;
   get(key: "railPreferences"): RailSnapshot | undefined;
   get(key: "user"): any;
@@ -34,7 +36,7 @@ export default function AdminLayout(props: Props) {
   const t = platformMessages.resolve([locale]).t;
   const url = new URL(c.req.raw.url);
   const currentPath = `${url.pathname}${url.search}`;
-  const runtime = getLocalizedRuntimeContext(c);
+  const runtime = getDisplayRuntimeContext(c);
   // Admin is the area's root, as an app's root is: the rail and the admin sidebar lead there. So it is no level
   // above an admin page, and every admin page shows its title alone, whichever app owns it.
   const overview = title === "Overview" || title === t.overview;

package/src/ssr/CloudShell.island.tsx

@@ -57,6 +57,9 @@ function BarNavigation(props: { currentPath: string }) {
     syncLocation();
     window.addEventListener(RAIL_PREFERENCES_EVENT, sync);
     window.addEventListener("popstate", syncLocation);
+    window.addEventListener("ssr:nav-popstate", syncLocation);
+    window.addEventListener("ssr:nav-swapped", sync);
+    window.addEventListener("ssr:nav-swapped", syncLocation);
     window.addEventListener("hashchange", syncLocation);
     // In-page navigation (`@k2b/ssr/nav`) commits with pushState or replaceState, which only the Navigation API
     // reports; where a browser lacks it, the bar follows at the next page load.
@@ -64,6 +67,9 @@ function BarNavigation(props: { currentPath: string }) {
     onCleanup(() => {
       window.removeEventListener(RAIL_PREFERENCES_EVENT, sync);
       window.removeEventListener("popstate", syncLocation);
+      window.removeEventListener("ssr:nav-popstate", syncLocation);
+      window.removeEventListener("ssr:nav-swapped", sync);
+      window.removeEventListener("ssr:nav-swapped", syncLocation);
       window.removeEventListener("hashchange", syncLocation);
       window.navigation?.removeEventListener("currententrychange", syncLocation);
     });

package/src/ssr/Layout.tsx

@@ -10,6 +10,7 @@ import { PANEL_HELP_ID_MAX_LENGTH, PanelPageContextSchema } from "../contracts/p
 import { isPwaShellAvailable } from "../contracts/pwa";
 import { defaultRailPreferences } from "../contracts/rail-preferences";
 import { hasRole, type User } from "../contracts/shared";
+import { isAppSessionActor } from "../server/actor";
 import { getLocale } from "../server/locale";
 import { getDateConfig } from "../server/time";
 import { dates, resolveHomePath } from "../shared";
@@ -27,14 +28,15 @@ import { HELP_VIEW_LIMIT } from "./layout-help-start";
 import type { LayoutBreadcrumb } from "./layout-runtime";
 import PageTrailRow from "./PageTrailRow";
 import PanelSlot from "./PanelSlot";
+import { getPageSwapBuild, pageSwapSignature } from "./page-swap";
 import { derivePageTrail } from "./page-trail";
 import { platformMessages } from "./platform-messages";
 import { sortRailApps } from "./rail-navigation";
 import { requestPath } from "./request-path";
-import { getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
+import { getDisplayRuntimeContext, getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
 import ShellFocusToggle from "./ShellFocusToggle";
 import ShellRuntime from "./ShellRuntime.island";
-import { type ShellData, ShellDataProvider } from "./shell-data";
+import { type ShellData, ShellDataProvider, ShellDataScript } from "./shell-data";
 
 // Types
 type Breadcrumb = LayoutBreadcrumb;
@@ -164,7 +166,9 @@ export default function Layout(props: LayoutProps) {
   const lang = getLocale(c);
   const t = platformMessages.resolve([lang]).t;
   const user = c.get("user");
-  const providers = user && props.panel !== false ? visiblePanelProviders(runtime.apps, user, lang) : [];
+  const displayIds = new Set(getDisplayRuntimeContext(c).apps.map((app) => app.id));
+  const displayApps = runtime.apps.filter((app) => displayIds.has(app.id));
+  const providers = user && props.panel !== false ? visiblePanelProviders(displayApps, user, lang) : [];
   const panelState = readPanelCookie(
     providers.length ? cookie : undefined,
     providers.map((provider) => provider.id),
@@ -178,12 +182,14 @@ export default function Layout(props: LayoutProps) {
     readAppWorkspaceLayoutCookie(cookie, currentApp?.id),
     workspaceSidebarCollapsible,
   );
-  const { primary: primaryApps, more: moreApps } = buildNavLinks(runtime.apps, user, lang);
+  const { primary: primaryApps, more: moreApps } = buildNavLinks(displayApps, user, lang);
   const allApps = sortRailApps([...primaryApps, ...moreApps], lang);
   const visibleAppIds = new Set(allApps.map((app) => app.id));
   const searchLinks = Object.fromEntries(
-    runtime.apps.flatMap((app) => (visibleAppIds.has(app.id) && app.searchLinks?.length ? [[app.id, app.searchLinks] as const] : [])),
+    displayApps.flatMap((app) => (visibleAppIds.has(app.id) && app.searchLinks?.length ? [[app.id, app.searchLinks] as const] : [])),
   );
+  const swapBuild = getPageSwapBuild(c);
+  const swap = swapBuild !== undefined && !focusMode && !!currentRoute?.prefix;
   const settings = c.get("settings");
   const announcements = c.get("announcements");
   const appName = settings?.app?.name || "Cloud";
@@ -212,7 +218,7 @@ export default function Layout(props: LayoutProps) {
   // The app bar and the app's navigation hidden with Cmd/Ctrl+\ or the sidebar buttons; phones ignore it in CSS.
   const shellFocus = showRail && readShellFocusCookie(cookie);
   // The profile menu offers the mobile app only while the installation runs it.
-  const appHref = user && isPwaShellAvailable(runtime.apps) ? "/me/app" : undefined;
+  const appHref = user && isPwaShellAvailable(displayApps) ? "/me/app" : undefined;
   const profileName = user?.displayName || user?.uid || "?";
   const profileAvatarSrc =
     user?.avatarHash && user.id
@@ -271,6 +277,30 @@ export default function Layout(props: LayoutProps) {
     searchLinks,
     appId: currentApp?.id,
   };
+  // What the kept shell shows outside the column: when any of it differs, the next page loads as a document.
+  const signature = swap
+    ? pageSwapSignature({
+        app: currentApp?.id,
+        kind: user ? "app" : "anonymous",
+        user: user?.id ?? null,
+        appSession: isAppSessionActor(c.get("actor")),
+        locale: lang,
+        theme: c.get("page").theme,
+        build: swapBuild,
+        shell: {
+          // The document's <html> theme and the profile menu keep this preference.
+          themePreference: theme,
+          providers,
+          apps: allApps,
+          legalLinks,
+          searchLinks,
+          home: shellData.home,
+          profile: shellData.profile,
+          announcements: user ? (announcements?.latestAnnouncementVersion ?? null) : null,
+          help: registeredHelp?.manifestHash ?? (layoutHelpFailed(c) ? "failed" : null),
+        },
+      })
+    : undefined;
   if (focusMode) {
     return (
       <LocaleProvider locale={lang}>
@@ -310,8 +340,11 @@ export default function Layout(props: LayoutProps) {
   return (
     <LocaleProvider locale={lang}>
       <div
-        class={`cloud-app-canvas relative flex w-full ${fullPage ? "h-dvh overflow-hidden" : "min-h-dvh md:h-dvh md:overflow-hidden"}`}
+        class={`cloud-app-canvas relative flex w-full ${fullPage && !swap ? "h-dvh overflow-hidden" : "min-h-dvh md:h-dvh md:overflow-hidden"}`}
         style={canvasStyle}
+        data-nav-shell={signature}
+        data-nav-scope={swap ? currentRoute?.prefix : undefined}
+        data-nav-attributes={swap ? "data-layout-full-page data-workspace-sidebar-collapsed" : undefined}
         data-panel={panelState.open ? "open" : undefined}
         data-app-id={currentApp?.id}
         data-app-base={currentRoute?.prefix}
@@ -334,13 +367,18 @@ export default function Layout(props: LayoutProps) {
               ? { entries: announcements.announcements, latestVersion: announcements.latestAnnouncementVersion }
               : undefined
           }
-          banners={user && announcements?.banners.length ? true : undefined}
+          banners={user && (swap || announcements?.banners.length) ? true : undefined}
         />
-        <ShellDataProvider data={shellData}>
+        <ShellDataProvider data={shellData} skipScript={swap}>
           {showRail && <LayoutRail currentPath={requestPath(c)} panelOpen={panel ? panelState.open : undefined} />}
           {showRail && <ShellFocusToggle variant="float" />}
           {showRail && <div class="cloud-shell-reveal" data-cloud-shell-reveal="" aria-hidden="true" />}
-          <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col" data-cloud-app-area="">
+          <div
+            class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col"
+            data-cloud-app-area=""
+            data-nav-root={swap ? "" : undefined}
+          >
+            {swap && <ShellDataScript data={shellData} />}
             <LayoutHeader
               panelOpen={panel ? panelState.open : undefined}
               authenticated={showRail}
@@ -353,19 +391,31 @@ export default function Layout(props: LayoutProps) {
             {user && <ExpiryWarnings user={user} dateConfig={dateConfig} locale={lang} />}
             <PageTrailProvider trail={pageTrail}>
               <PageTrailRow trail={pageTrail} />
-              <main class={`layout-content-main min-h-0 min-w-0 flex-1 ${mainLayoutClass}`}>
+              <main
+                class={`layout-content-main min-h-0 min-w-0 flex-1 ${mainLayoutClass}`}
+                data-scroll-preserve={swap ? "cloud-main" : undefined}
+                data-scroll-page={swap ? "" : undefined}
+              >
                 <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
               </main>
             </PageTrailProvider>
             {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
+            {swap && (
+              <div data-print-fallback="">
+                <p>{t.printFallbackTitle}</p>
+                <p>{props.printHint ?? t.printFallbackHint}</p>
+              </div>
+            )}
           </div>
           {panel && <PanelSlot panel={panel} state={panelState} platform={shellData.platform} />}
           {showRail && <LayoutTabBar currentPath={requestPath(c)} />}
         </ShellDataProvider>
-        <div data-print-fallback="">
-          <p>{t.printFallbackTitle}</p>
-          <p>{props.printHint ?? t.printFallbackHint}</p>
-        </div>
+        {!swap && (
+          <div data-print-fallback="">
+            <p>{t.printFallbackTitle}</p>
+            <p>{props.printHint ?? t.printFallbackHint}</p>
+          </div>
+        )}
       </div>
     </LocaleProvider>
   );

package/src/ssr/LayoutHelp.browser-harness.tsx

@@ -100,7 +100,7 @@ if (!main) throw new Error("Missing Layout main");
 const embedded = params.has("embedded");
 const referenceHost = params.get("host");
 if (referenceHost === "grids" || referenceHost === "pulse") {
-  // The Grids and Pulse query reference windows: one article beside the reference sidebar, without the Cloud shell.
+  // The Grids query reference windows: one article beside the reference sidebar, without the Cloud shell.
   const host = document.createElement("div");
   host.className = "h-dvh";
   document.body.replaceChildren(host);

package/src/ssr/LayoutHelp.tsx

@@ -1,4 +1,5 @@
 import type { HelpArticleLink, HelpDocumentManifest, HelpDocumentPayload } from "@k2b/cloud/shared";
+import { listenPopState } from "@k2b/ssr/nav";
 import { clipboard } from "@k2b/stdlib/solid";
 import {
   BottomSheet,
@@ -383,12 +384,12 @@ const HelpShell = (props: {
       // The hub keeps its search, as the reader's own Back button does. An unknown topic shows the hub, as the server does.
       else setView("hub");
     };
-    if (props.syncPageUrl) window.addEventListener("popstate", onPopState);
+    const stopPopState = props.syncPageUrl ? listenPopState(onPopState) : undefined;
     onCleanup(() => {
       scrollArea?.removeEventListener("scroll", onScroll);
       window.removeEventListener("resize", onResize);
       if (resizeFrame !== undefined) cancelAnimationFrame(resizeFrame);
-      window.removeEventListener("popstate", onPopState);
+      stopPopState?.();
     });
   });
   onCleanup(() => copyAllController?.abort());

package/src/ssr/PanelRuntime.island.tsx

@@ -1,6 +1,7 @@
 import { installAppWorkspaceController, installInputModeController, keyboardPlatform } from "@k2b/ui";
 import { onCleanup, onMount } from "solid-js";
 import { installPanelContextReceiver } from "../browser/panel-context-receiver";
+import { hasPanelLeaveGuard, panelLinkDestination } from "../browser/panel-leave";
 import { syncTimezoneCookie } from "./timezone-cookie";
 
 export default function PanelRuntime(props: { provider?: string; scope?: string }) {
@@ -24,15 +25,18 @@ export default function PanelRuntime(props: { provider?: string; scope?: string
     };
     const close = () => window.parent.postMessage({ type: "cloud.panel.close" }, location.origin);
     const click = (event: MouseEvent) => {
-      if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
-      const anchor = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>("a[href]") : null;
-      if (!anchor || (anchor.target && anchor.target !== "_self") || anchor.hasAttribute("download")) return;
-      const url = new URL(anchor.getAttribute("href")!, document.baseURI);
-      if (url.origin !== location.origin) return;
+      const url = panelLinkDestination(event);
+      if (!url) return;
       const scope = props.scope?.replace(/\/$/, "");
-      if (scope !== undefined && (url.pathname === scope || url.pathname.startsWith(`${scope}/`))) return;
+      const internal = scope !== undefined && (url.pathname === scope || url.pathname.startsWith(`${scope}/`));
+      if (!hasPanelLeaveGuard()) {
+        if (internal) return;
+        event.preventDefault();
+        window.parent.location.assign(url.href);
+        return;
+      }
       event.preventDefault();
-      window.parent.location.assign(url.href);
+      window.parent.postMessage({ type: "cloud.panel.navigate", v: 1, href: url.href }, location.origin);
     };
     const key = (event: KeyboardEvent) => {
       if (event.isComposing || event.defaultPrevented || event.altKey || event.shiftKey) return;

package/src/ssr/PwaLayout.tsx

@@ -6,7 +6,7 @@ import { visiblePwaParts } from "./app-navigation";
 import type { LayoutContext } from "./layout-context";
 import PwaRuntime from "./PwaRuntime.island";
 import { pwaMessages } from "./pwa-messages";
-import { getRuntimeContext } from "./runtime";
+import { getDisplayRuntimeContext } from "./runtime";
 import TimezoneCookie from "./TimezoneCookie.island";
 
 /** Parts with their own tab; Start lists every part and doubles as "More". */
@@ -42,7 +42,7 @@ export default function PwaLayout(props: PwaLayoutProps) {
   c.header("Referrer-Policy", "no-referrer");
   c.header("Content-Security-Policy", "frame-ancestors 'none'");
 
-  const parts = visiblePwaParts(getRuntimeContext(c).apps, user, locale);
+  const parts = visiblePwaParts(getDisplayRuntimeContext(c).apps, user, locale);
   const path = new URL(c.req.raw.url).pathname;
   const tabs = parts.slice(0, TAB_PARTS);
   const currentTab = tabs.find((part) => path === part.pwa.href || path.startsWith(`${part.pwa.href}/`));

package/src/ssr/RailApps.tsx

@@ -44,11 +44,17 @@ export default function RailApps(props: { apps: RailApp[]; settings: RailSnapsho
     const stopBadges = watchAppBadges(props.apps.flatMap((app) => (app.badge ? [app.badge] : [])));
     window.addEventListener(RAIL_PREFERENCES_EVENT, sync);
     window.addEventListener("popstate", syncLocation);
+    window.addEventListener("ssr:nav-popstate", syncLocation);
+    window.addEventListener("ssr:nav-swapped", sync);
+    window.addEventListener("ssr:nav-swapped", syncLocation);
     window.addEventListener("hashchange", syncLocation);
     onCleanup(() => {
       stopBadges();
       window.removeEventListener(RAIL_PREFERENCES_EVENT, sync);
       window.removeEventListener("popstate", syncLocation);
+      window.removeEventListener("ssr:nav-popstate", syncLocation);
+      window.removeEventListener("ssr:nav-swapped", sync);
+      window.removeEventListener("ssr:nav-swapped", syncLocation);
       window.removeEventListener("hashchange", syncLocation);
     });
   });