@k2b/cloud 0.38.0 → 0.40.0

package/src/ssr/compact-shell.browser-harness.ts

@@ -0,0 +1,439 @@
+import { afterAll, beforeAll, setDefaultTimeout, spyOn } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { createConfig } from "@k2b/ssr";
+import tailwind from "bun-plugin-tailwind";
+import type { Browser, BrowserContext, Page } from "playwright";
+import { createComponent } from "solid-js";
+import type { launchBrowser } from "../../../ui/test/browser";
+
+// The shell's geometry at every width — which chrome exists, where the app
+// area ends, which edges draw lines — is decided by real layout, so a real
+// engine loads the server-rendered Layout with the global stylesheet and the
+// shared workspace controller, as Cloud serves them.
+const root = mkdtempSync(resolve(tmpdir(), "cloud-compact-shell-browser-"));
+const { plugin } = createConfig({ dev: true, rootDir: root });
+Bun.plugin(plugin());
+process.once("exit", () => rmSync(root, { recursive: true, force: true }));
+
+const { Hono } = await import("hono");
+const { AppWorkspace, Button, ScrollArea } = await import("@k2b/ui");
+const { defineApp } = await import("../_internal/define-app");
+const { person } = await import("../_internal/define-app.test-fixture");
+const railSnapshot = await import("../services/rail-snapshot");
+const settingsMiddleware = await import("../server/middleware/settings");
+const { defaultRailPreferences } = await import("../contracts/rail-preferences");
+const { default: WorkspaceNavigation } = await import("./WorkspaceNavigation.island");
+const { default: Layout } = await import("./Layout");
+
+const probe = defineApp({
+  id: "compact-shell-probe",
+  name: "Compact shell probe",
+  icon: "ti ti-layout",
+  description: "Shell geometry probe",
+  baseUrl: "http://compact-shell-probe:3000",
+  routes: ["/app/mail"],
+});
+const extraApps = ["Amber", "Birch", "Cedar", "Dune", "Elm"].map((name) => ({
+  id: name.toLowerCase(),
+  name,
+  icon: "ti ti-box",
+  description: `${name} demo`,
+  routes: [`/app/${name.toLowerCase()}`],
+  nav: { href: `/app/${name.toLowerCase()}`, section: "primary" },
+}));
+const apps = [
+  {
+    id: "mail",
+    name: "Mail",
+    icon: "ti ti-mail",
+    description: "Read and write mail",
+    routes: ["/app/mail"],
+    nav: { href: "/app/mail", section: "primary" },
+  },
+  {
+    id: "pwa",
+    name: "Phone app",
+    icon: "ti ti-device-mobile",
+    description: "Phone app",
+    routes: ["/pwa"],
+    nav: { href: "/pwa", section: "hidden" },
+  },
+];
+
+type LayoutContextArg = Parameters<typeof Layout>[0]["c"];
+
+/** A mail-like workspace: navigation, a list pane beside the reader, and a detail panel. Invented content. */
+const workspace = (selected: string) =>
+  createComponent(AppWorkspace, {
+    mobileSurface: "flush",
+    class: "min-h-0 flex-1",
+    get children() {
+      return [
+        createComponent(AppWorkspace.Sidebar, {
+          id: "mail-navigation",
+          label: "Mailboxes",
+          get children() {
+            return createComponent(AppWorkspace.SidebarDesktop, {
+              get children() {
+                return createComponent(AppWorkspace.SidebarBody, {
+                  get children() {
+                    return ["inbox", "archive", "sent"].map((id) =>
+                      createComponent(AppWorkspace.SidebarItem, {
+                        href: `#${id}`,
+                        icon: "ti ti-inbox",
+                        active: id === selected,
+                        children: id[0]!.toUpperCase() + id.slice(1),
+                      }),
+                    );
+                  },
+                });
+              },
+            });
+          },
+        }),
+        createComponent(AppWorkspace.Content, {
+          get children() {
+            return [
+              createComponent(AppWorkspace.Main, {
+                get children() {
+                  return [
+                    createComponent(AppWorkspace.MainPane, { id: "messages", label: "Messages", children: "Quarterly numbers" }),
+                    `Reader for ${selected}`,
+                  ];
+                },
+              }),
+              createComponent(AppWorkspace.Detail, { id: "message-detail", open: true, width: "sm", children: "Sender details" }),
+            ];
+          },
+        }),
+      ];
+    },
+  });
+
+/**
+ * A task-list page: a long list in Main and an open detail that the server renders with its own close
+ * control, as Contacts and Capabilities do. Invented content.
+ */
+const listWorkspace = (head = false) =>
+  createComponent(AppWorkspace, {
+    class: "min-h-0 flex-1",
+    get children() {
+      return [
+        head ? createComponent(AppWorkspace.Head, { primary: { label: "New task", icon: "ti ti-plus", href: "?new=task" } }) : null,
+        createComponent(AppWorkspace.Content, {
+          get children() {
+            return [
+              createComponent(AppWorkspace.Main, {
+                get children() {
+                  return Array.from({ length: 80 }, (_, index) =>
+                    createComponent(Button, {
+                      variant: head ? "ghost" : undefined,
+                      class: "list-row",
+                      align: "start",
+                      children: `Task ${index + 1}`,
+                    }),
+                  );
+                },
+              }),
+              createComponent(AppWorkspace.Detail, {
+                id: "task-detail",
+                open: true,
+                get children() {
+                  return createComponent(Button, { "data-workspace-detail-close": "", children: "Close task" });
+                },
+              }),
+            ];
+          },
+        }),
+      ];
+    },
+  });
+
+/** A sidebar-first overview that is the page itself, as Mail and Notebooks render. Invented content. */
+const overviewWorkspace = () =>
+  createComponent(AppWorkspace, {
+    mobileSurface: "flush",
+    flat: true,
+    resizable: false,
+    get children() {
+      return [
+        createComponent(AppWorkspace.Sidebar, {
+          id: "overview-navigation",
+          label: "Mailboxes",
+          get children() {
+            return createComponent(AppWorkspace.SidebarDesktop, {
+              get children() {
+                return createComponent(AppWorkspace.SidebarBody, {
+                  get children() {
+                    return ["Personal", "Projects", "Support"].map((name) =>
+                      createComponent(AppWorkspace.SidebarItem, { href: `#${name.toLowerCase()}`, children: name }),
+                    );
+                  },
+                });
+              },
+            });
+          },
+        }),
+        createComponent(AppWorkspace.Content, {
+          get children() {
+            return createComponent(AppWorkspace.Main, {
+              get children() {
+                return Array.from({ length: 80 }, (_, index) =>
+                  createComponent(Button, { class: "overview-row", align: "start", children: `Message ${index + 1}` }),
+                );
+              },
+            });
+          },
+        }),
+      ];
+    },
+  });
+
+const server = new Hono()
+  .get(
+    "/",
+    async (c, next) => {
+      c.set("runtime" as never, { apps } as never);
+      c.set("user" as never, person as never);
+      await next();
+    },
+    ...probe.ssr((c) => () => createComponent(Layout, { c: c as unknown as LayoutContextArg, title: "Start", children: "Start content" })),
+  )
+  .get(
+    "/app/mail/:folder",
+    async (c, next) => {
+      // `?name=` renames Mail, for a long app name in the phone header.
+      const name = c.req.query("name");
+      const catalog = c.req.query("catalog") ? [...extraApps, ...apps] : apps;
+      c.set("runtime" as never, { apps: name ? catalog.map((app) => (app.id === "mail" ? { ...app, name } : app)) : catalog } as never);
+      // A missing last name shows the profile notice above the app.
+      c.set("user" as never, (c.req.query("notice") ? { ...person, sn: "" } : person) as never);
+      await next();
+    },
+    ...probe.ssr((c) => {
+      const folder = c.req.param("folder") ?? "inbox";
+      const title = folder[0]!.toUpperCase() + folder.slice(1);
+      if (c.req.query("navigation"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            title: [{ title: "Home", href: "/" }, { title: "Mail" }],
+            get children() {
+              return [
+                createComponent(WorkspaceNavigation, { label: "Mail", items: [{ id: "inbox", label: "Inbox", href: "/app/mail/inbox" }] }),
+                overviewWorkspace(),
+              ];
+            },
+          });
+      // `?overview=` keeps regular Layout props, including its page scroller's gutter.
+      if (c.req.query("overview"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            title: [{ title: "Home", href: "/" }, { title: "Mail" }],
+            get children() {
+              return overviewWorkspace();
+            },
+          });
+      // `?plain=` renders a regular page without a workspace or scroll area: `main` is its page scroller.
+      if (c.req.query("plain"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            title: [{ title: "Home", href: "/" }, { title: "Settings" }],
+            get children() {
+              return Array.from({ length: 60 }, (_, index) =>
+                createComponent(Button, { class: "plain-row w-full", align: "start", children: `Setting ${index + 1}` }),
+              );
+            },
+          });
+      // `?cards=` renders a page without a workspace that scrolls its content in a ScrollArea, as
+      // Capabilities and Weather do.
+      if (c.req.query("cards"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            fullWidth: true,
+            title: [{ title: "Home", href: "/" }, { title: "Capabilities" }],
+            get children() {
+              return createComponent(ScrollArea, {
+                class: "min-h-0 min-w-0 flex-1",
+                get children() {
+                  return Array.from({ length: 60 }, (_, index) =>
+                    createComponent(Button, { class: "card-row w-full", align: "start", children: `App ${index + 1}` }),
+                  );
+                },
+              });
+            },
+          });
+      // `?list=` renders the task list: `scroll` in a page that grows with its content, `page` in a full page.
+      const list = c.req.query("list");
+      if (list)
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            fullWidth: true,
+            fullPage: list === "page",
+            title: [{ title: "Home", href: "/" }, { title: "Tasks" }],
+            get children() {
+              return listWorkspace(c.req.query("head") === "1");
+            },
+          });
+      return () =>
+        createComponent(Layout, {
+          c: c as unknown as LayoutContextArg,
+          fullWidth: true,
+          fullPage: true,
+          title: [{ title: "Home", href: "/" }, { title: "Mail", href: "/app/mail" }, { title }],
+          get children() {
+            return workspace(folder);
+          },
+        });
+    }),
+  )
+  .get(
+    "/public",
+    async (c, next) => {
+      c.set("runtime" as never, { apps } as never);
+      await next();
+    },
+    ...probe.ssr(
+      (c) => () =>
+        createComponent(Layout, {
+          c: c as unknown as LayoutContextArg,
+          title: [{ title: "Home", href: "/" }, { title: c.req.query("title") ?? "Public tools" }],
+          get children() {
+            if (c.req.query("cards"))
+              return createComponent(ScrollArea, {
+                get children() {
+                  return Array.from({ length: 60 }, (_, index) =>
+                    createComponent(Button, { class: "card-row", children: `App ${index + 1}` }),
+                  );
+                },
+              });
+            return c.req.query("overview") ? overviewWorkspace() : "Public content";
+          },
+        }),
+    ),
+  );
+
+let browser: Browser;
+let css: string;
+let controller: string;
+const spies: { mockRestore(): void }[] = [];
+// Register hooks in each importing test file; Bun caches this module across files.
+// Keeping hooks at module scope would leave the second file with a closed browser.
+/**
+ * Each suite passes `launchBrowser` from packages/ui/test/browser itself, so the test runner and the
+ * browser-launch check find it as a browser suite and the gate also runs it in WebKit.
+ */
+export function installCompactShellHarness(launch: typeof launchBrowser) {
+  // Several tests walk every device, each in a fresh browser context. Bun scopes the default timeout to
+  // the test file that sets it, and this module runs once per process, so each suite sets it here.
+  setDefaultTimeout(30_000);
+  beforeAll(async () => {
+    spies.push(
+      spyOn(railSnapshot, "readRailSnapshot").mockResolvedValue(defaultRailPreferences()),
+      spyOn(settingsMiddleware, "preloadLayoutAnnouncements").mockResolvedValue(undefined),
+    );
+    const build = await Bun.build({ entrypoints: [resolve(import.meta.dir, "../../../../styles.css")], plugins: [tailwind] });
+    if (!build.success) throw new AggregateError(build.logs, "Could not compile the global stylesheet.");
+    css = await build.outputs[0]!.text();
+    // Cloud installs the shared workspace controller once for the document; the
+    // test installs the same export from the shipped browser build.
+    const entry = resolve(import.meta.dir, "compact-shell.controller.ts");
+    const bundle = await Bun.build({
+      entrypoints: [entry],
+      files: {
+        [entry]: `import { installAppWorkspaceController } from ${JSON.stringify(resolve(import.meta.dir, "../../../ui/dist/browser/index.js"))};
+window.installController = () => installAppWorkspaceController();`,
+      },
+      target: "browser",
+      format: "iife",
+    });
+    if (!bundle.success) throw new AggregateError(bundle.logs, "Could not bundle the workspace controller.");
+    controller = await bundle.outputs[0]!.text();
+    browser = await launch();
+  }, 60_000);
+  afterAll(async () => {
+    for (const spy of spies.splice(0)) spy.mockRestore();
+    await browser?.close();
+  });
+}
+
+export type Device = { name: string; width: number; height: number; touch: boolean };
+export const phone: Device = { name: "phone", width: 390, height: 844, touch: true };
+export const ipadSplitView: Device = { name: "iPad Split View", width: 694, height: 834, touch: true };
+export const ipadPortrait: Device = { name: "iPad portrait", width: 834, height: 1194, touch: true };
+export const smallLaptop: Device = { name: "small laptop", width: 1024, height: 768, touch: false };
+export const ipadLandscape: Device = { name: "iPad landscape", width: 1194, height: 834, touch: true };
+export const laptop: Device = { name: "laptop", width: 1440, height: 900, touch: false };
+export const desktop: Device = { name: "desktop", width: 1920, height: 1080, touch: false };
+export const devices = [phone, ipadSplitView, ipadPortrait, smallLaptop, ipadLandscape, laptop, desktop];
+export const tabletBoundary: Device = { name: "tablet boundary", width: 1023, height: 768, touch: false };
+
+// The signed-in card's spacing and radius in whole pixels: 4 and 10 px at 1024 px, 8 and 14 px from 1440 px.
+export const cardInset = (width: number) => Math.round(Math.min(8, Math.max(4, 4 + (width - 1024) / 104)));
+export const cardRadius = (width: number) => Math.round(Math.min(14, Math.max(10, 10 + (width - 1024) / 104)));
+
+export type Options = {
+  language?: "en" | "de";
+  theme?: "light" | "dark";
+  notice?: boolean;
+  style?: string;
+  insets?: Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+};
+// Match the existing app-canvas safe-area fixture: engines cannot override env().
+export const withInsets = (stylesheet: string, insets: Options["insets"] = {}) => {
+  for (const [side, inset] of Object.entries(insets)) {
+    const pattern = new RegExp(`env\\(\\s*safe-area-inset-${side}\\s*(?:,\\s*0px\\s*)?\\)`, "g");
+    if (!pattern.test(stylesheet)) throw new Error(`Missing safe-area-inset-${side}`);
+    stylesheet = stylesheet.replace(pattern, `${inset}px`);
+  }
+  return stylesheet;
+};
+export const html = async (path: string, options: Options = {}) => {
+  const headers = {
+    "Accept-Language": options.language ?? "en",
+    Cookie: `theme=${options.theme ?? "light"}`,
+  };
+  const markup = await (await server.request(path, { headers })).text();
+  const clean = new HTMLRewriter()
+    .on('script[src], script[type="module"]', { element: (element) => void element.remove() })
+    .on('link[rel="stylesheet"], link[rel="preload"], link[rel="modulepreload"]', { element: (element) => void element.remove() })
+    .transform(markup);
+  return clean.replace(
+    "</head>",
+    `<style>${withInsets(css, options.insets)}</style><style>*,*::before,*::after{transition:none!important;animation:none!important}${options.style ?? ""}</style></head>`,
+  );
+};
+
+/** Attaches the controller as Cloud's island does after the first paint, and lets its first frame run. */
+export const attach = async (page: Page) => {
+  await page.addScriptTag({ content: controller });
+  await page.evaluate(async () => {
+    (window as unknown as { installController: () => void }).installController();
+    await new Promise((settle) => requestAnimationFrame(() => requestAnimationFrame(settle)));
+  });
+};
+
+export const open = async (
+  device: Device,
+  path: string,
+  options: Options & { attached?: boolean } = {},
+): Promise<{ context: BrowserContext; page: Page }> => {
+  // iPads and phones report a coarse pointer without hover, as Safari does. A page set from markup has
+  // no cookies in WebKit, so the theme script follows the system scheme; it matches the requested theme.
+  const context = await browser.newContext({
+    viewport: { width: device.width, height: device.height },
+    hasTouch: device.touch,
+    isMobile: device.touch,
+    colorScheme: options.theme ?? "light",
+  });
+  const page = await context.newPage();
+  await page.setContent(await html(path, options));
+  if (options.attached !== false) await attach(page);
+  return { context, page };
+};

package/src/ssr/dialog-app-colors.browser-harness.tsx

@@ -0,0 +1,43 @@
+import { DataTable, prompts, SettingsModal } from "@k2b/ui";
+import { render } from "solid-js/web";
+
+const host = document.createElement("div");
+document.querySelector(".cloud-app-canvas")!.append(host);
+
+const SelectedTable = () => (
+  <DataTable
+    rows={[{ id: "selected", name: "Selected file" }]}
+    columns={[{ id: "name", header: "Name", value: "name" }]}
+    getRowId={(row) => row.id}
+    selectedRowId="selected"
+    surface="plain"
+  />
+);
+
+render(
+  () => (
+    <button
+      type="button"
+      onClick={() =>
+        void prompts.dialog<void>(
+          (close) => (
+            <div class="dialog-fixed-frame flex min-h-0 flex-col overflow-hidden">
+              <SettingsModal title="App settings" onClose={() => close()}>
+                <SettingsModal.Tab id="general" title="General">
+                  <SelectedTable />
+                </SettingsModal.Tab>
+                <SettingsModal.Tab id="files" title="Files">
+                  <SelectedTable />
+                </SettingsModal.Tab>
+              </SettingsModal>
+            </div>
+          ),
+          { surface: "bare", header: false, size: "large" },
+        )
+      }
+    >
+      Open app settings
+    </button>
+  ),
+  host,
+);

package/src/ssr/help-messages.ts

@@ -20,6 +20,8 @@ export const helpMessages = i18n.define({
       shortcutsInApp: ({ app }: { app: string }) => `In ${app}`,
       shortcutsInThisApp: "In this app",
       shortcutsWithSelection: "With a selection",
+      helpNotAvailable: "This Help is not available",
+      helpNotAvailableDetail: "You may not have access to it, or it no longer exists.",
       noArticles: "No Help articles here yet",
       reload: "Reload",
       noArticlesDetail: "This app has not published Help yet.",
@@ -79,6 +81,8 @@ export const helpMessages = i18n.define({
       shortcutsInApp: ({ app }) => `In ${app}`,
       shortcutsInThisApp: "In dieser App",
       shortcutsWithSelection: "Mit Auswahl",
+      helpNotAvailable: "Diese Hilfe ist nicht verfügbar",
+      helpNotAvailableDetail: "Vielleicht hast du keinen Zugriff, oder es gibt sie nicht mehr.",
       noArticles: "Hier gibt es noch keine Hilfeartikel",
       reload: "Neu laden",
       noArticlesDetail: "Diese App hat noch keine Hilfe veröffentlicht.",

package/src/ssr/help.ts

@@ -1,9 +1,13 @@
 import type { Context } from "hono";
+import { buildHelpDocumentPayload } from "../server/help-payload";
 import { getLocale } from "../server/locale";
 import { createHelpReader } from "../services/help";
 import type { HelpManifestResult } from "../services/help/types";
 import { logger } from "../services/logging";
+import type { HelpDocumentPayload } from "../shared/help";
 import { resolveCurrentApp } from "./app-appearance";
+import type { HelpArticleParts } from "./layout-help-article";
+import { helpArticlePartsServer } from "./layout-help-article.server";
 import { getRuntimeContext } from "./runtime";
 
 const manifests = new WeakMap<object, HelpManifestResult | null>();
@@ -30,3 +34,19 @@ export const preloadLayoutHelp = async (c: Context, appId?: string): Promise<Hel
     return null;
   }
 };
+
+export type LayoutHelpArticle = { payload: HelpDocumentPayload; parts: HelpArticleParts };
+
+/** An authorized initial article; failures leave the browser's on-demand reader available. */
+export const preloadLayoutHelpArticle = async (c: Context, appId: string, documentId: string): Promise<LayoutHelpArticle | null> => {
+  if (!c.get("user")) return null;
+  try {
+    const article = await createHelpReader(getLocale(c), c.get("actor")).read({ appId, documentId });
+    if (!article) return null;
+    const payload = buildHelpDocumentPayload(article, c.req.header("User-Agent") ?? "");
+    return { payload, parts: helpArticlePartsServer(payload.html) };
+  } catch (error) {
+    log.warn("Help article unavailable", { appId, documentId, error: error instanceof Error ? error.message : String(error) });
+    return null;
+  }
+};

package/src/ssr/hints.ts

@@ -0,0 +1,25 @@
+import type { Context } from "hono";
+import { isHintId, mergeSeenHints, parseSeenHintsCookieHeader, seenHintsSetCookie } from "../contracts/seen-hints";
+import { userFromActor } from "../server/actor";
+
+/** Ids marked seen earlier in the same request, so a second mark or a later check sees them too. */
+const marked = new WeakMap<Context, string[]>();
+
+const seenIds = (c: Context): string[] => marked.get(c) ?? parseSeenHintsCookieHeader(c.req.header("Cookie"));
+
+/** The caller checks access to the new path; anonymous visitors never see a hint. */
+export const hintOpen = (c: Context, id: string, options: { allowed: boolean }): boolean => {
+  if (!isHintId(id)) throw new Error(`Invalid hint id: ${id}`);
+  return options.allowed && !!userFromActor(c.get("actor")) && !seenIds(c).includes(id);
+};
+
+/**
+ * Call on the new path too: using it counts as having seen the hint. Each call writes the whole list seen so far in
+ * this request, so with several calls the browser keeps the last cookie and with it every id.
+ */
+export const markHintSeen = (c: Context, id: string): void => {
+  const ids = mergeSeenHints(seenIds(c), id);
+  marked.set(c, ids);
+  const secure = new URL(c.req.url).protocol === "https:" || c.req.header("x-forwarded-proto")?.split(",")[0]?.trim() === "https";
+  c.header("Set-Cookie", seenHintsSetCookie(ids, secure), { append: true });
+};

package/src/ssr/index.ts

@@ -4,18 +4,23 @@
 export { default as AdminLayout } from "./AdminLayout";
 export {
   hasDedicatedRuntimeRoute,
+  type PanelProvider,
   resolveRuntimeRoute,
   type VisiblePwaPart,
   visibleNavigationApps,
+  visiblePanelProviders,
   visiblePwaParts,
 } from "./app-navigation";
+export { hintOpen, markHintSeen } from "./hints";
 export { default as Layout } from "./Layout";
 export {
   default as MinimalLayout,
   type MinimalLayoutPreferencePosition,
   type MinimalLayoutProps,
 } from "./MinimalLayout";
+export { default as PanelLayout, type PanelLayoutProps } from "./PanelLayout";
 export { default as PwaLayout, type PwaLayoutProps } from "./PwaLayout";
+export { readPanelContext } from "./panel-context";
 export { requestPath } from "./request-path";
 export { getLocalizedRuntimeContext, getRuntimeContext, type RuntimeContext } from "./runtime";
 export type { UrlFilterField } from "./url-filter";

package/src/ssr/islands/index.ts

@@ -4,19 +4,20 @@ export { provideWorkspaceNavigation } from "../workspace-navigation";
 export { default as SearchBar } from "./SearchBar";
 
 import { AppLaunchpadButton, AppLaunchpadProvider } from "../app-launchpad";
-import { LayoutHelpPage } from "../LayoutHelp";
+import { LayoutHelpPage, LayoutHelpPanel } from "../LayoutHelp";
 import { LayoutHelpDocuments } from "../layout-help-registry";
 
 export type { AppLaunchpadApp, AppLaunchpadLegalLink } from "../app-launchpad";
 export { AppLaunchpadButton, AppLaunchpadProvider, openAppLaunchpad, setAppLaunchpadContext } from "../app-launchpad";
-export type { LayoutHelpPageProps } from "../LayoutHelp";
-export { LayoutHelpPage, openLayoutHelpDialog } from "../LayoutHelp";
+export type { LayoutHelpPageProps, LayoutHelpPanelProps } from "../LayoutHelp";
+export { LayoutHelpPage, LayoutHelpPanel, openLayoutHelpDialog } from "../LayoutHelp";
 export type { LayoutHelpDocumentsProps } from "../layout-help-registry";
 export { LayoutHelpDocuments } from "../layout-help-registry";
 
 export const Layout = {
   HelpDocuments: LayoutHelpDocuments,
   HelpPage: LayoutHelpPage,
+  HelpPanel: LayoutHelpPanel,
   AppLaunchpadButton,
   AppLaunchpadProvider,
 };

package/src/ssr/layout-context.ts

@@ -1,3 +1,4 @@
+import type { PanelConsentSnapshot } from "../contracts/panel-context";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { User } from "../contracts/shared";
 import type { LayoutAnnouncementsState } from "../server/middleware/settings";
@@ -5,6 +6,7 @@ import type { RuntimeContext } from "./runtime";
 
 export type LayoutContext = {
   get(key: "user"): User | undefined;
+  get(key: "panelConsent"): PanelConsentSnapshot | undefined;
   get(key: "railPreferences"): RailSnapshot | undefined;
   get(key: "page"): { theme?: "light" | "dark"; title?: string; pwa?: { name: string } };
   get(key: "runtime"): RuntimeContext;

package/src/ssr/layout-help-article.server.ts

@@ -0,0 +1,50 @@
+import type * as Htmlparser2 from "htmlparser2";
+import type { HelpArticleParts } from "./layout-help-article";
+
+// Keep the same synchronous import path as sanitize-html (see ai/readable-html.ts).
+const { parseDocument, DomUtils, ElementType }: typeof Htmlparser2 = require("htmlparser2");
+type HtmlNode = ReturnType<typeof parseDocument>["children"][number];
+
+const insideDetails = (node: HtmlNode): boolean => {
+  for (let parent = node.parent; parent; parent = parent.parent) if ("name" in parent && parent.name === "details") return true;
+  return false;
+};
+const spokenText = (node: HtmlNode): string => {
+  if (node.type === ElementType.Text) return node.data;
+  if (!("children" in node)) return "";
+  return node.children
+    .filter((child) => !("attribs" in child) || child.attribs["aria-hidden"] !== "true")
+    .map(spokenText)
+    .join("");
+};
+
+/** Server-only equivalent of the browser's inert-template splitter. Never import into an island. */
+export const helpArticlePartsServer = (html: string): HelpArticleParts => {
+  const body = parseDocument(html);
+  const first = body.children.find((node) => "attribs" in node);
+  const lead = first?.name === "p" && !first.attribs.class ? DomUtils.getOuterHTML(first) : undefined;
+  if (lead && first) DomUtils.removeElement(first);
+  const elements = DomUtils.findAll(() => true, body.children);
+  return {
+    lead,
+    body: DomUtils.getInnerHTML(body),
+    sections: elements
+      .filter((element) => element.name === "h2" && "id" in element.attribs && !insideDetails(element))
+      .map((element) => ({ id: element.attribs.id ?? "", label: spokenText(element).replace(/\s+/g, " ").trim() }))
+      .filter((section) => section.label),
+    steps: elements.filter((element) => {
+      const list = element.parent;
+      const wrapper = list?.parent;
+      return (
+        element.name === "li" &&
+        list &&
+        "name" in list &&
+        list.name === "ol" &&
+        wrapper &&
+        "attribs" in wrapper &&
+        (wrapper.attribs.class ?? "").split(/\s+/).includes("help-steps") &&
+        !insideDetails(element)
+      );
+    }).length,
+  };
+};