@k2b/cloud 0.37.0 → 0.39.0

package/src/ssr/CloudShell.island.tsx

@@ -1,30 +1,85 @@
-import { useLocale } from "@k2b/ui";
-import { createEffect } from "solid-js";
+import { TabBar, useLocale } from "@k2b/ui";
+import { createEffect, createMemo, createSignal, onCleanup, onMount, Show } from "solid-js";
+import { isServer, Portal } from "solid-js/web";
 import { AppLaunchpadButton, setAppLaunchpadContext } from "./app-launchpad";
 import GlobalSearchTrigger from "./GlobalSearchTrigger";
 import LayoutBreadcrumbs from "./LayoutBreadcrumbs";
 import LayoutHelpTrigger from "./LayoutHelpTrigger";
 import LayoutPreferences from "./LayoutPreferences";
 import type { LayoutBreadcrumb } from "./layout-runtime";
+import PanelTrigger from "./PanelTrigger";
 import ProfilePreferences from "./ProfilePreferences";
 import { platformMessages } from "./platform-messages";
 import RailApps from "./RailApps";
+import { RAIL_PREFERENCES_EVENT, readRailContext } from "./rail-context";
+import { phoneBarItems, projectRailNavigation } from "./rail-navigation";
 import ShellFocusToggle from "./ShellFocusToggle";
 import { useShellData } from "./shell-data";
 
 type CloudShellProps =
-  | { slot: "rail"; currentPath: string }
-  | { slot: "header"; authenticated: boolean; title?: string; launchpad: boolean; breadcrumbs?: LayoutBreadcrumb[] };
+  | { slot: "rail"; currentPath: string; panelOpen?: boolean }
+  | { slot: "header"; authenticated: boolean; title?: string; launchpad: boolean; breadcrumbs?: LayoutBreadcrumb[]; panelOpen?: boolean };
 
 /**
  * The interactive part of the shell chrome. `LayoutRail` and `LayoutHeader`
  * own the frame and the plain links around it as server markup.
  */
 export default function CloudShell(props: CloudShellProps) {
-  return props.slot === "rail" ? <RailNavigation currentPath={props.currentPath} /> : <HeaderControls {...props} />;
+  return props.slot === "rail" ? (
+    <RailNavigation currentPath={props.currentPath} panelOpen={props.panelOpen} />
+  ) : (
+    <HeaderControls {...props} />
+  );
+}
+
+/**
+ * The phone bar's live copy, mounted with the rail's island so the shell adds no island instance. It renders nothing
+ * while the server's bar is current, so mounting moves and refocuses nothing. When the saved rail preferences or the
+ * URL (a fragment, Back and Forward, an in-page navigation) change what the bar shows, it renders the new bar into the
+ * bar's row, and CSS hides the server's.
+ */
+function BarNavigation(props: { currentPath: string }) {
+  if (isServer) return null;
+  const data = useShellData();
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const initial = data?.rail;
+  if (!data || !initial) return null;
+  const [settings, setSettings] = createSignal(initial);
+  const [currentPath, setCurrentPath] = createSignal(props.currentPath);
+  const itemsFor = (rail: typeof initial, path: string) =>
+    phoneBarItems(projectRailNavigation(data.apps, rail, locale()), path, { label: t().home, path: data.home ?? "/" });
+  const served = JSON.stringify(itemsFor(initial, props.currentPath));
+  const items = createMemo(() => itemsFor(settings(), currentPath()));
+  onMount(() => {
+    const sync = () => setSettings(readRailContext()?.settings ?? initial);
+    const syncLocation = () => setCurrentPath(`${window.location.pathname}${window.location.search}${window.location.hash}`);
+    syncLocation();
+    window.addEventListener(RAIL_PREFERENCES_EVENT, sync);
+    window.addEventListener("popstate", 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.
+    window.navigation?.addEventListener("currententrychange", syncLocation);
+    onCleanup(() => {
+      window.removeEventListener(RAIL_PREFERENCES_EVENT, sync);
+      window.removeEventListener("popstate", syncLocation);
+      window.removeEventListener("hashchange", syncLocation);
+      window.navigation?.removeEventListener("currententrychange", syncLocation);
+    });
+  });
+  const row = document.querySelector<HTMLElement>(".cloud-tab-bar__row");
+  if (!row) return null;
+  return (
+    <Show when={JSON.stringify(items()) !== served}>
+      <Portal mount={row}>
+        <TabBar variant="floating" class="cloud-tab-bar__live" label={t().apps} items={items()} />
+      </Portal>
+    </Show>
+  );
 }
 
-function RailNavigation(props: { currentPath: string }) {
+function RailNavigation(props: { currentPath: string; panelOpen?: boolean }) {
   const data = useShellData();
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
@@ -36,7 +91,9 @@ function RailNavigation(props: { currentPath: string }) {
       <ShellFocusToggle variant="rail" />
       <RailApps apps={data.apps} settings={data.rail} currentPath={props.currentPath} />
       <AppLaunchpadButton profile={profile} apps={data.apps} legalLinks={data.legalLinks} variant="rail" label={t().openApps} />
+      <BarNavigation currentPath={props.currentPath} />
       <div class="mt-auto shrink-0 flex flex-col items-center gap-1">
+        {(data.panel?.providers.length ?? 0) > 1 && <PanelTrigger variant="rail" open={props.panelOpen} />}
         <GlobalSearchTrigger variant="rail" />
         <LayoutHelpTrigger variant="rail" />
         <ProfilePreferences
@@ -51,7 +108,13 @@ function RailNavigation(props: { currentPath: string }) {
 }
 
 /** The header's title and controls, between the server-rendered Home and Sign in. */
-function HeaderControls(props: { authenticated: boolean; title?: string; launchpad: boolean; breadcrumbs?: LayoutBreadcrumb[] }) {
+function HeaderControls(props: {
+  authenticated: boolean;
+  title?: string;
+  launchpad: boolean;
+  breadcrumbs?: LayoutBreadcrumb[];
+  panelOpen?: boolean;
+}) {
   const data = useShellData();
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
@@ -65,13 +128,27 @@ function HeaderControls(props: { authenticated: boolean; title?: string; launchp
           </div>
         )}
         <div class="flex min-w-0 items-center lg:hidden">
-          <span class="truncate font-semibold">{props.title}</span>
+          <span class="layout-header-title truncate font-semibold">{props.title}</span>
+          {props.launchpad && (
+            <AppLaunchpadButton
+              profile={
+                data.profile
+                  ? { name: data.profile.name, theme: data.theme, ...(data.profile.appHref ? { appHref: data.profile.appHref } : {}) }
+                  : undefined
+              }
+              apps={data.apps}
+              legalLinks={data.legalLinks}
+              variant="title"
+              label={props.title}
+            />
+          )}
         </div>
       </div>
       <div class="flex shrink-0 items-center gap-1">
         <div class="flex items-center gap-1 lg:hidden">
-          <LayoutHelpTrigger variant="header" />
+          {(data.panel?.providers.length ?? 0) > 1 && <PanelTrigger variant="header" open={props.panelOpen} />}
           {props.authenticated && <GlobalSearchTrigger variant="header" />}
+          <LayoutHelpTrigger variant="header" />
           {props.launchpad && (
             <AppLaunchpadButton
               profile={

package/src/ssr/Layout.tsx

@@ -1,7 +1,8 @@
 import type { DateContext } from "@k2b/stdlib";
-import { AppWorkspace, appWorkspaceLayoutStyle, LocaleProvider, NoticeCard, PageTrailProvider } from "@k2b/ui";
+import { AppWorkspace, appWorkspaceLayoutStyle, keyboardPlatform, LocaleProvider, NoticeCard, PageTrailProvider } from "@k2b/ui";
 import type { JSX } from "solid-js/jsx-runtime";
 import { readAppWorkspaceLayoutCookie, resolveAppWorkspaceLayoutForSidebar } from "../_internal/app-workspace-state";
+import { readPanelCookie } from "../_internal/panel-cookie";
 import { readShellFocusCookie } from "../_internal/shell-focus";
 import { resolveNavMatch } from "../contracts/app"; // ==========================
 import { isPwaShellAvailable } from "../contracts/pwa";
@@ -9,18 +10,21 @@ import { defaultRailPreferences } from "../contracts/rail-preferences";
 import { hasRole, type User } from "../contracts/shared";
 import { getLocale } from "../server/locale";
 import { getDateConfig } from "../server/time";
-import { dates } from "../shared";
+import { dates, resolveHomePath } from "../shared";
 import { readThemePreferenceFromCookieHeader } from "../shared/theme";
 import AnnouncementBanners from "./AnnouncementBanners";
 import { appAppearanceStyle, resolveCurrentApp } from "./app-appearance";
-import { resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
-import { getLayoutHelp } from "./help";
+import { resolveRuntimeRoute, visibleNavigationApps, visiblePanelProviders } from "./app-navigation";
+import { getLayoutHelp, layoutHelpFailed } from "./help";
 import LayoutFooter from "./LayoutFooter";
 import LayoutHeader from "./LayoutHeader";
 import LayoutRail, { type LayoutAppLink } from "./LayoutRail";
+import LayoutTabBar from "./LayoutTabBar";
 import type { LayoutContext } from "./layout-context";
+import { HELP_VIEW_LIMIT } from "./layout-help-start";
 import type { LayoutBreadcrumb } from "./layout-runtime";
 import PageTrailRow from "./PageTrailRow";
+import PanelSlot from "./PanelSlot";
 import { derivePageTrail } from "./page-trail";
 import { platformMessages } from "./platform-messages";
 import { sortRailApps } from "./rail-navigation";
@@ -36,10 +40,16 @@ type LayoutProps = {
   children: JSX.Element;
   c: LayoutContext;
   title?: string | Breadcrumb[];
+  /** Up to three ids of the current app's Help articles that fit this page; Help lists them first under "For this view". Unknown ids and articles the reader may not see are ignored. */
+  help?: readonly string[];
   fullPage?: boolean /** Keep the shell viewport-bound and suppress its footer. */;
   fullWidth?: boolean /** Delegate scrolling and clipping to the page's work surface. */;
+  /** Hide the panel slot on this page (sign-in, print, presentation, public pages). */
+  panel?: false;
   focusMode?: boolean /** Render only the app canvas and content for dedicated editors or pop-out windows. */;
   flushCanvas?: boolean /** Remove app-canvas spacing for edge-to-edge focus surfaces such as pop-out windows. */;
+  /** Final localized app-specific export or printing guidance, shown when no data-print-region exists. */
+  printHint?: string;
   workspaceSidebarCollapsible?: boolean /** Resolve persisted sidebar geometry for the page's sidebar policy during SSR. */;
 }; // ==========================
 // Helpers
@@ -150,6 +160,12 @@ 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 panelState = readPanelCookie(
+    providers.length ? cookie : undefined,
+    providers.map((provider) => provider.id),
+  );
+  const panel = providers.length ? { providers, provider: panelState.provider ?? providers[0]?.id } : undefined;
   const pathname = new URL(c.req.raw.url).pathname;
   const currentRoute = resolveRuntimeRoute(runtime.apps, pathname);
   const currentApp = resolveCurrentApp(runtime.apps, pathname);
@@ -202,14 +218,29 @@ export default function Layout(props: LayoutProps) {
   // keeps short and long pages at the same width where scrollbars take space.
   const mainLayoutClass = fullPage || fullWidth ? "flex flex-col" : "md:overflow-auto md:[scrollbar-gutter:stable]";
   const canvasStyle =
-    [appAppearanceStyle(currentApp?.appearance), appWorkspaceLayoutStyle(workspaceLayout), focusMode && flushCanvas ? "padding:0" : ""]
+    [
+      appAppearanceStyle(currentApp?.appearance),
+      appWorkspaceLayoutStyle(workspaceLayout),
+      panelState.widthRem !== undefined ? `--cloud-panel-width-set:${panelState.widthRem}rem` : "",
+      focusMode && flushCanvas ? "padding:0" : "",
+    ]
       .filter(Boolean)
       .join(";") || undefined;
   const appLabel = currentApp?.name ?? (pathname.startsWith("/admin") ? t.admin : undefined);
+  const helpIds = new Set(registeredHelp?.documents.map((topic) => topic.id));
+  const viewHelp = [...new Set(props.help)].filter((id) => helpIds.has(id)).slice(0, HELP_VIEW_LIMIT);
   const shellData: ShellData = {
+    ...(panel ? { panel } : {}),
+    platform: keyboardPlatform(c.req.raw.headers.get("User-Agent") ?? ""),
+    ...(viewHelp.length ? { help: viewHelp } : {}),
+    ...(layoutHelpFailed(c) ? { helpFailed: true as const } : {}),
     apps: allApps,
     ...(user
-      ? { rail: c.get("railPreferences") ?? defaultRailPreferences(), profile: { name: profileName, avatarSrc: profileAvatarSrc, appHref } }
+      ? {
+          rail: c.get("railPreferences") ?? defaultRailPreferences(),
+          home: resolveHomePath(settings?.app?.home_path),
+          profile: { name: profileName, avatarSrc: profileAvatarSrc, appHref },
+        }
       : {}),
     legalLinks,
     theme,
@@ -221,20 +252,31 @@ export default function Layout(props: LayoutProps) {
     return (
       <LocaleProvider locale={lang}>
         <div
-          class="cloud-app-canvas flex h-dvh w-full overflow-hidden"
+          class="cloud-app-canvas relative flex h-dvh w-full overflow-hidden"
           style={canvasStyle}
+          data-panel-transient=""
           data-app-id={currentApp?.id}
           data-app-base={currentRoute?.prefix}
           data-page-trail-title-only=""
           data-layout-full-page="true"
           data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
         >
-          <ShellRuntime pageTrail help={runtimeHelp} />
+          <ShellRuntime pageTrail help={runtimeHelp} panel={panel ? true : undefined} />
           <PageTrailProvider trail={pageTrail}>
-            <main class="min-h-0 min-w-0 flex-1">
+            <main class="min-h-0 min-w-0 flex-1" data-cloud-app-area="">
               <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
             </main>
           </PageTrailProvider>
+          {/* Focus pages carry shell data only for their panel providers. */}
+          {panel && (
+            <ShellDataProvider data={{ panel, platform: shellData.platform, theme, apps: [], legalLinks: [], searchLinks: {} }}>
+              <PanelSlot panel={panel} state={{ ...panelState, open: false }} platform={shellData.platform} />
+            </ShellDataProvider>
+          )}
+          <div data-print-fallback="">
+            <p>{t.printFallbackTitle}</p>
+            <p>{props.printHint ?? t.printFallbackHint}</p>
+          </div>
         </div>
       </LocaleProvider>
     );
@@ -247,6 +289,7 @@ export default function Layout(props: LayoutProps) {
       <div
         class={`cloud-app-canvas relative flex w-full ${fullPage ? "h-dvh overflow-hidden" : "min-h-dvh md:h-dvh md:overflow-hidden"}`}
         style={canvasStyle}
+        data-panel={panelState.open ? "open" : undefined}
         data-app-id={currentApp?.id}
         data-app-base={currentRoute?.prefix}
         data-page-trail-title-only={titleOnly ? "" : undefined}
@@ -256,6 +299,7 @@ export default function Layout(props: LayoutProps) {
         data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
       >
         <ShellRuntime
+          panel={panel ? true : undefined}
           workspace={{ appId: currentApp?.id }}
           pageTrail
           focus={showRail}
@@ -270,11 +314,12 @@ export default function Layout(props: LayoutProps) {
           banners={user && announcements?.banners.length ? true : undefined}
         />
         <ShellDataProvider data={shellData}>
-          {showRail && <LayoutRail currentPath={requestPath(c)} />}
+          {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">
+          <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col" data-cloud-app-area="">
             <LayoutHeader
+              panelOpen={panel ? panelState.open : undefined}
               authenticated={showRail}
               title={appLabel ?? breadcrumbs.at(-1)?.title}
               launchpad={!!(user || appLabel)}
@@ -291,7 +336,13 @@ export default function Layout(props: LayoutProps) {
             </PageTrailProvider>
             {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
           </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>
       </div>
     </LocaleProvider>
   );

package/src/ssr/LayoutHeader.tsx

@@ -5,6 +5,7 @@ import { platformMessages } from "./platform-messages";
 
 type LayoutHeaderProps = {
   authenticated: boolean;
+  panelOpen?: boolean;
   title?: string;
   launchpad: boolean;
   breadcrumbs?: LayoutBreadcrumb[];
@@ -14,10 +15,12 @@ type LayoutHeaderProps = {
  * Phones (below `md`) always get this header. From `md` it remains only on
  * anonymous pages; signed-in people reach Home, search, help, the app grid,
  * and their profile through the rail, so the app area starts at the top edge.
- * Anonymous pages have no rail: up to `lg` their header keeps the app name,
- * help, search, and the app grid, and from `lg` it shows the breadcrumbs.
- * Home and Sign in stay server markup, so focus on them survives the shell's
- * mount; the shell renders the title and the controls between them.
+ * On a signed-in phone it is the title row on the app gradient: Home moves to
+ * the bottom bar's Start, so the row holds the title, search, help, and the
+ * app menu. Anonymous pages have no rail: up to `lg` their header keeps Home,
+ * the app name, help, search, and the app grid, and from `lg` it shows the
+ * breadcrumbs. Home and Sign in stay server markup, so focus on them survives
+ * the shell's mount; the shell renders the title and the controls between them.
  */
 export default function LayoutHeader(props: LayoutHeaderProps) {
   const locale = useLocale();
@@ -29,13 +32,16 @@ export default function LayoutHeader(props: LayoutHeaderProps) {
     >
       {/* A long title must not squeeze the button; `shrink-0` sits on a wrapper because the button's own
           styles would win over a utility on the link. */}
-      <div class="flex shrink-0">
-        <IconButtonLink href="/" label={t().home}>
-          <img src="/branding/logo" alt="" class={props.authenticated ? "h-4 w-4" : "h-6 w-6"} />
-        </IconButtonLink>
-      </div>
+      {!props.authenticated && (
+        <div class="flex shrink-0">
+          <IconButtonLink href="/" label={t().home}>
+            <img src="/branding/logo" alt="" class="h-6 w-6" />
+          </IconButtonLink>
+        </div>
+      )}
       <CloudShell
         slot="header"
+        panelOpen={props.panelOpen}
         authenticated={props.authenticated}
         title={props.title}
         launchpad={props.launchpad}

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

@@ -1,43 +1,146 @@
-import { LocaleProvider } from "@k2b/ui";
+import { AppWorkspace, LocaleProvider } from "@k2b/ui";
 import { render } from "solid-js/web";
+import { registerContextAwareCommand } from "../browser/command-bridge";
 import type { HelpDocumentManifest, HelpDocumentPayload } from "../shared/help";
-import { LayoutHelpPage } from "./LayoutHelp";
+import { LayoutHelpPage, openLayoutHelpDialog } from "./LayoutHelp";
+import { registry } from "./layout-help-registry";
 
-const documents: HelpDocumentManifest[] = Array.from({ length: 8 }, (_, index) => ({
-  id: `topic-${index}`,
-  title: `Topic ${index}`,
+const params = new URL(location.href).searchParams;
+const fixture = (id: string, title: string, order: number, kind?: HelpDocumentManifest["kind"], icon?: string): HelpDocumentManifest => ({
+  id,
+  title,
   description: "Help browser fixture",
-  order: index,
-  url: `/api/help/topic-${index}`,
+  order,
+  ...(kind ? { kind } : {}),
+  ...(icon ? { icon } : {}),
+  url: `/api/help/${id}`,
   searchUrl: "/api/help/search",
-}));
-const html = Array.from(
-  { length: 8 },
-  (_, index) =>
-    `<h2 id="section-${index}" class="help-section-title" data-help-icon="ti ti-point">Section ${index}</h2>${Array.from({ length: 18 }, () => "<p>Read this guidance to finish the task and understand how the app works.</p>").join("")}`,
-).join("");
+});
+// `?start`: an app with every kind and more tasks than the start shows as tiles.
+const startDocuments: HelpDocumentManifest[] = [
+  fixture("share-space", "Share a Space", 10, "task", "ti ti-share"),
+  fixture("claim-task", "Claim a task", 20, "task", "ti ti-hand-grab"),
+  fixture("statuses", "Create and order statuses", 30, "task", "ti ti-arrows-sort"),
+  fixture("calendar-feed", "See dates in your own calendar", 40, "task", "ti ti-calendar-share"),
+  fixture("templates", "Start from a template", 50, undefined, "ti ti-template"),
+  fixture("filters", "Filter and find items", 60, "task", "ti ti-filter"),
+  fixture("handoffs", "Hand work over", 70, "task", "ti ti-arrows-exchange"),
+  fixture("archive", "Archive a Space", 80, "task", "ti ti-archive"),
+  fixture("import", "Import tasks from a spreadsheet with a very long title that wraps", 90, "task", "ti ti-table-import"),
+  fixture("recurring", "Repeat a task", 100, "task", "ti ti-repeat"),
+  fixture("start", "Start with Spaces", 5, "start", "ti ti-rocket"),
+  fixture("access-levels", "Access levels", 110, "reference", "ti ti-key"),
+  fixture("troubleshoot", "Fix problems in Spaces", 120, "troubleshoot", "ti ti-lifebuoy"),
+];
+const documents: HelpDocumentManifest[] = params.has("start")
+  ? startDocuments
+  : Array.from({ length: 8 }, (_, index) => fixture(`topic-${index}`, `Topic ${index}`, index));
+// `?commands`: what the shell and an app register on a real page.
+if (params.has("commands")) {
+  for (const command of [
+    { id: "cloud.shell.focus", title: "Hide sidebar", description: "", shortcut: "mod+\\" },
+    { id: "cloud.search", title: "Open global search", description: "", shortcut: "mod+k" },
+    { id: "cloud.help", title: "Open shortcut help", description: "", shortcut: "shift+/" },
+    { id: "spaces.new", title: "New task", description: "", shortcut: "n" },
+    { id: "spaces.filter", title: "Filter tasks", description: "", shortcut: "f" },
+    { id: "spaces.complete", title: "Complete selected", description: "", shortcut: "x", scope: "selection" as const },
+  ])
+    registerContextAwareCommand({ ...command, action: () => {} });
+}
+const lead = "<p>Share a Space so that other people can see and change its tasks.</p>";
+const longHtml =
+  lead +
+  Array.from(
+    { length: 8 },
+    (_, index) =>
+      `<h2 id="section-${index}" class="help-section-title">Section ${index}</h2>${Array.from({ length: 18 }, () => "<p>Read this guidance to finish the task and understand how the app works.</p>").join("")}`,
+  ).join("");
+// A short task article: the short answer, one section, four steps.
+const taskHtml = `${lead}<h2 id="invite-people" class="help-section-title">Invite people</h2><div class="help-steps"><ol class="k2b-steps"><li>Open <span class="k2b-label-chip">Space settings</span>.</li><li>Choose <span class="k2b-label-chip">Add person</span>.</li><li>Enter a name or a group.</li><li>Choose the access level.</li></ol></div><p>Spaces saves the change at once.</p><div class="help-compare"><ul><li><strong>Add a person</strong> Gives one named person access to every task in this Space.</li><li><strong>Add a group</strong> Gives everyone in the group access, including people who join later.</li></ul></div>`;
+const link = (id: string, title: string, appId = "spaces", appName = "Spaces") => ({
+  appId,
+  appName,
+  accent: appId === "spaces" ? "#16a34a" : "#2563eb",
+  documentId: id,
+  title,
+  description: "Help browser fixture",
+  url: `/help/apps/${appId}/${id}`,
+});
 window.fetch = Object.assign(
   async (input: URL | RequestInfo) => {
     await new Promise((resolve) => setTimeout(resolve, 80));
     const path = String(input);
-    if (path.includes("/search")) return Response.json({ locale: "en", ids: ["topic-0", "topic-1"] });
+    if (path.includes("/search")) {
+      const query = new URL(path, location.href).searchParams.get("q") ?? "";
+      const ids = params.has("start")
+        ? documents.filter((document) => document.title.toLocaleLowerCase().includes(query)).map((document) => document.id)
+        : ["topic-0", "topic-1"];
+      return Response.json({ locale: "en", ids });
+    }
     const id = path.split("/").at(-1) ?? "topic-0";
-    const payload: HelpDocumentPayload = { id, locale: "en", title: id, markdown: "Help", html };
+    const payload: HelpDocumentPayload = {
+      id,
+      locale: "en",
+      title: id,
+      markdown: "Help",
+      html: id === "topic-1" ? taskHtml : longHtml,
+      kind: "task",
+      needs: "manage",
+      next: link("topic-2", "Topic 2"),
+      related: [link("topic-3", "Topic 3"), link("mail-share", "Share a mailbox", "mail", "Mail")],
+    };
     return Response.json(payload);
   },
   { preconnect: () => {} },
 );
 const main = document.querySelector<HTMLElement>(".layout-content-main");
 if (!main) throw new Error("Missing Layout main");
-const embedded = new URL(location.href).searchParams.has("embedded");
-const host = document.createElement("div");
-if (embedded) host.style.cssText = "width:360px;height:700px";
-main.append(host);
-render(
-  () => (
-    <LocaleProvider locale="en">
-      <LayoutHelpPage documents={documents} embedded={embedded} pageBase="/app/spaces/help" />
-    </LocaleProvider>
-  ),
-  host,
-);
+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.
+  const host = document.createElement("div");
+  host.className = "h-dvh";
+  document.body.replaceChildren(host);
+  const reader = () => <LayoutHelpPage documents={documents.slice(0, 1)} initialTopic="topic-0" includeShortcuts={false} embedded />;
+  render(
+    () => (
+      <LocaleProvider locale="en">
+        <AppWorkspace>
+          <AppWorkspace.Sidebar>
+            <AppWorkspace.SidebarDesktop>
+              <AppWorkspace.SidebarBody>Reference</AppWorkspace.SidebarBody>
+            </AppWorkspace.SidebarDesktop>
+          </AppWorkspace.Sidebar>
+          <AppWorkspace.Content>
+            {referenceHost === "grids" ? (
+              <AppWorkspace.Main class="p-[var(--ui-space-shell)]" scroll={false}>
+                <div class="flex min-h-0 flex-1 flex-col overflow-auto">{reader()}</div>
+              </AppWorkspace.Main>
+            ) : (
+              <AppWorkspace.Main class="overflow-y-auto">{reader()}</AppWorkspace.Main>
+            )}
+          </AppWorkspace.Content>
+        </AppWorkspace>
+      </LocaleProvider>
+    ),
+    host,
+  );
+} else if (params.has("modal")) {
+  // The dialog reads the topics the page registered, as Layout.HelpDocuments does.
+  for (const manifest of documents) registry()?.set(manifest.id, manifest);
+  window.__cloudLayoutHelpPageBase = "/app/spaces/help";
+  openLayoutHelpDialog();
+} else {
+  const host = document.createElement("div");
+  if (embedded) host.style.cssText = "width:360px;height:700px";
+  main.append(host);
+  render(
+    () => (
+      <LocaleProvider locale="en">
+        <LayoutHelpPage documents={documents} embedded={embedded} pageBase="/app/spaces/help" />
+      </LocaleProvider>
+    ),
+    host,
+  );
+}