@k2b/cloud 0.40.0 → 0.42.0

package/src/ssr/LayoutHelp.tsx

@@ -1,4 +1,5 @@
-import type { HelpAccessLevel, HelpArticleLink, HelpDocumentManifest, HelpDocumentPayload } from "@k2b/cloud/shared";
+import type { HelpArticleLink, HelpDocumentManifest, HelpDocumentPayload } from "@k2b/cloud/shared";
+import { listenPopState } from "@k2b/ssr/nav";
 import { clipboard } from "@k2b/stdlib/solid";
 import {
   BottomSheet,
@@ -7,8 +8,6 @@ import {
   Dropdown,
   dialogCore,
   IconButton,
-  Kbd,
-  type KeyboardPlatform,
   MarkdownView,
   NoticeCard,
   Placeholder,
@@ -16,14 +15,12 @@ import {
   prompts,
   ScrollArea,
   TableOfContents,
-  TextInput,
   toast,
   useLocale,
 } from "@k2b/ui";
-import { createEffect, createMemo, createSignal, For, type JSX, onCleanup, onMount, Show, untrack } from "solid-js";
+import { createEffect, createMemo, createSignal, type JSX, onCleanup, onMount, Show, untrack } from "solid-js";
 import { COMMANDS_CHANGED, contextCommandsWithShortcuts } from "../browser/command-shortcuts";
-import { getContext, onContextChange, openPanel } from "../browser/panel";
-import { onPanelShortcutsChange, panelShortcutsReceived, readPanelShortcuts } from "../browser/panel-shortcuts";
+import { openPanel } from "../browser/panel";
 import { HELP_ACCESS_LEVELS, HELP_KINDS } from "../shared/help";
 import { appAccentStyle } from "./app-appearance";
 import type { LayoutHelpArticle } from "./help";
@@ -33,14 +30,9 @@ import { formatHelpBundleMarkdown, formatHelpDocumentMarkdown } from "./layout-h
 import { focusHelpArticleHeading, resetHelpArticleScroll } from "./layout-help-navigation";
 import { HELP_TOPICS_EVENT, type HelpTopic, registry } from "./layout-help-registry";
 import { searchHelpTopics } from "./layout-help-search";
-import {
-  type HelpShortcutCommand,
-  type HelpShortcutScope,
-  type HelpStartGroupKind,
-  helpShortcutGroups,
-  helpStart,
-} from "./layout-help-start";
+import { type HelpShortcutCommand, helpShortcutGroups, helpStart } from "./layout-help-start";
 import { helpLinkTarget, layoutHelpTopicHref } from "./layout-help-url";
+import { HelpArticleView, HelpHead, HelpResultsView, HelpShortcutsView, HelpStartView, type HelpSurface } from "./layout-help-views";
 import { platformMessages } from "./platform-messages";
 import { readShellData, useShellData } from "./shell-data";
 import { shellShortcuts } from "./shell-shortcuts";
@@ -58,22 +50,6 @@ export type LayoutHelpPageProps = {
   pageBase?: string;
 };
 
-export type LayoutHelpPanelProps = {
-  documents: readonly HelpDocumentManifest[];
-  /** Absent when the context selected Help the reader may not see. */
-  app?: { id: string; name: string; icon?: string };
-  /** appAppearanceStyle() of the app, from the server. */
-  appearance?: string;
-  /** Server-filtered For this view ids. */
-  view?: readonly string[];
-  initialTopic?: string;
-  /** Authorized article and server-parsed parts for an identical first frame. */
-  initialArticle?: LayoutHelpArticle;
-  pageBase?: string;
-  platform: KeyboardPlatform;
-  state?: "failed" | "unavailable";
-};
-
 type HelpView = "hub" | "article";
 type HelpSession = {
   view: HelpView;
@@ -101,8 +77,6 @@ const articleLink = (value: unknown): HelpArticleLink | undefined => {
   return { appId, appName, accent, documentId, title, description, icon, url };
 };
 
-/** An article without its own icon gets a neutral page tile. */
-const iconClass = (icon?: string) => (icon?.startsWith("ti ") ? icon : `ti ${icon ?? "ti-file-text"}`);
 const byOrder = (a: HelpTopic, b: HelpTopic) => (a.order ?? 100) - (b.order ?? 100) || a.title.localeCompare(b.title);
 const sortedTopics = () => [...(registry()?.values() ?? [])].sort(byOrder);
 const mergeTopics = (registered: readonly HelpTopic[], documents: readonly HelpDocumentManifest[] = []): HelpTopic[] => {
@@ -110,11 +84,6 @@ const mergeTopics = (registered: readonly HelpTopic[], documents: readonly HelpD
   for (const topic of documents) topics.set(topic.id, topic);
   return [...topics.values()].sort(byOrder);
 };
-const GROUP_ICONS: Record<HelpStartGroupKind, string> = {
-  start: "ti ti-rocket",
-  reference: "ti ti-book-2",
-  troubleshoot: "ti ti-lifebuoy",
-};
 
 /**
  * Keyboard shortcuts come last in the start. The browser knows the page's commands. On a Layout page (it has shell
@@ -122,68 +91,22 @@ const GROUP_ICONS: Record<HelpStartGroupKind, string> = {
  * first client render on, also before the shell has registered them. The groups reserve their height and place in CSS,
  * so the ones the browser adds fill space that is already there.
  */
-const StartShortcuts = (props: { appName?: string; panel?: boolean; platform?: KeyboardPlatform }) => {
+const StartShortcuts = (props: { appName?: string }) => {
   const locale = useLocale();
-  const t = () => helpMessages.resolve([locale()]).t;
-  const shell = props.panel ? undefined : useShellData();
-  const seed: HelpShortcutCommand[] =
-    props.panel || shell ? shellShortcuts(platformMessages.resolve([locale()]).t, { panel: props.panel || !!shell?.panel }) : [];
+  const shell = useShellData();
+  const seed: HelpShortcutCommand[] = shell ? shellShortcuts(platformMessages.resolve([locale()]).t, { panel: !!shell.panel }) : [];
   const read = (): HelpShortcutCommand[] => {
-    // Once received, the host list is authoritative: omitted shortcuts must stay omitted.
-    if (props.panel) return panelShortcutsReceived() && getContext() !== null ? readPanelShortcuts() : seed;
     const commands = contextCommandsWithShortcuts();
     return [...seed.filter((command) => !commands.some((other) => other.id === command.id)), ...commands];
   };
-  const [commands, setCommands] = createSignal<HelpShortcutCommand[]>(props.panel ? seed : read());
+  const [commands, setCommands] = createSignal<HelpShortcutCommand[]>(read());
   onMount(() => {
     const update = () => setCommands(read());
-    if (props.panel) {
-      onCleanup(onPanelShortcutsChange(update));
-      onCleanup(onContextChange(update));
-    }
     update();
-    if (!props.panel) {
-      window.addEventListener(COMMANDS_CHANGED, update);
-      onCleanup(() => window.removeEventListener(COMMANDS_CHANGED, update));
-    }
+    window.addEventListener(COMMANDS_CHANGED, update);
+    onCleanup(() => window.removeEventListener(COMMANDS_CHANGED, update));
   });
-  const label = (scope: HelpShortcutScope) =>
-    scope === "everywhere"
-      ? t().shortcutsEverywhere
-      : scope === "selection"
-        ? t().shortcutsWithSelection
-        : props.appName
-          ? t().shortcutsInApp({ app: props.appName })
-          : t().shortcutsInThisApp;
-  return (
-    <section class="help-start-section help-start-shortcuts" data-help-shortcuts="" aria-labelledby="help-start-shortcuts-title">
-      <h3 id="help-start-shortcuts-title" class="help-start-heading">
-        <i class="ti ti-keyboard" aria-hidden="true" />
-        {t().keyboardShortcuts}
-      </h3>
-      <div class="help-shortcut-groups">
-        <For each={helpShortcutGroups(commands())}>
-          {(group) => (
-            <section class="help-shortcut-group" data-help-shortcut-group={group.scope} aria-label={label(group.scope)}>
-              <h4 class="help-shortcut-group-title" aria-hidden="true">
-                {label(group.scope)}
-              </h4>
-              <ul>
-                <For each={group.shortcuts}>
-                  {(command) => (
-                    <li class="help-shortcut" title={command.description}>
-                      <span class="help-shortcut-title">{command.title}</span>
-                      <Kbd keys={command.shortcut} platform={props.platform ?? shell?.platform} />
-                    </li>
-                  )}
-                </For>
-              </ul>
-            </section>
-          )}
-        </For>
-      </div>
-    </section>
-  );
+  return <HelpShortcutsView groups={helpShortcutGroups(commands())} appName={props.appName} platform={shell?.platform} />;
 };
 
 const HelpShell = (props: {
@@ -196,29 +119,29 @@ const HelpShell = (props: {
   accent?: string;
   /** The app's canvas colours for a reader outside the app canvas. */
   appearance?: string;
-  surface?: "modal" | "page" | "embedded" | "panel";
-  panel?: LayoutHelpPanelProps;
+  surface: HelpSurface;
   syncPageUrl?: boolean;
 }) => {
   const locale = useLocale();
   const t = () => helpMessages.resolve([locale()]).t;
   // Links to this app's Help, by its own route or Core's `/help/apps/<id>`, open in place.
-  const shell = props.surface === "panel" ? undefined : useShellData();
-  const appId = props.panel?.app?.id ?? shell?.appId;
+  const shell = useShellData();
+  const appId = shell?.appId;
   const app = shell?.apps.find((candidate) => candidate.id === appId);
-  const appName = props.panel?.app?.name ?? app?.label;
-  const [viewIds, setViewIds] = createSignal(props.panel?.view ?? []);
-  const registeredTopics = () => (props.surface === "panel" ? [] : sortedTopics());
-  const accessLabel = (level: HelpAccessLevel) => ({ view: t().accessView, edit: t().accessEdit, manage: t().accessManage })[level];
+  const appName = app?.label;
+  const registeredTopics = () => sortedTopics();
   const [externalTopics, setExternalTopics] = createSignal(mergeTopics(registeredTopics(), props.documents));
   const [view, setView] = createSignal<HelpView>(props.session.view);
   const [query, setQuery] = createSignal(props.session.query);
   const [activeId, setActiveId] = createSignal<string | null>(props.session.activeId);
   const initialTopic = props.documents?.find((topic) => topic.id === props.session.activeId);
   const initialArticle = initialTopic && props.initialArticle?.payload.id === initialTopic.id ? props.initialArticle : undefined;
-  if (initialArticle && initialTopic)
-    props.session.articleCache.set(`${initialTopic.locale ?? "en"}:${initialTopic.url}`, initialArticle.payload);
-  const [payload, setPayload] = createSignal<HelpDocumentPayload | null>(initialArticle?.payload ?? null);
+  // HTML travels once as parts; rebuild it for the cache and the article settle effect.
+  const seeded = initialArticle
+    ? { ...initialArticle.payload, html: (initialArticle.parts.lead ?? "") + initialArticle.parts.body }
+    : undefined;
+  if (seeded && initialTopic) props.session.articleCache.set(`${initialTopic.locale ?? "en"}:${initialTopic.url}`, seeded);
+  const [payload, setPayload] = createSignal<HelpDocumentPayload | null>(seeded ?? null);
   const [loading, setLoading] = createSignal(props.session.view === "article" && !initialArticle);
   const [loadError, setLoadError] = createSignal<string | null>(null);
   const [loadAttempt, setLoadAttempt] = createSignal(0);
@@ -266,7 +189,7 @@ const HelpShell = (props: {
   };
 
   const restoreArticleScroll = () => {
-    if ((props.surface !== "modal" && props.surface !== "panel") || pendingNavigation || pendingHash) return;
+    if (props.surface !== "modal" || pendingNavigation || pendingHash) return;
     requestAnimationFrame(() => {
       if (scrollArea && view() === "article") scrollArea.scrollTop = props.session.articleScrollTop;
     });
@@ -311,14 +234,12 @@ const HelpShell = (props: {
   };
 
   const topics = externalTopics;
-  const start = createMemo(() =>
-    helpStart(topics(), props.surface === "panel" ? viewIds() : props.surface === "modal" ? shell?.help : undefined),
-  );
+  const start = createMemo(() => helpStart(topics(), props.surface === "modal" ? shell?.help : undefined));
   const activeTopic = createMemo(() => topics().find((topic) => topic.id === activeId()) ?? null);
   // Reuse the serialized parts for the initial object on both sides of the island boundary.
   const articleParts = createMemo(() => {
     const article = payload();
-    if (initialArticle && article === initialArticle.payload) return initialArticle.parts;
+    if (initialArticle && article === seeded) return initialArticle.parts;
     return article?.html ? helpArticleParts(article.html) : null;
   });
   const articleSections = (): HelpSection[] => (view() === "article" ? articleParts()?.sections : undefined) ?? [];
@@ -409,10 +330,7 @@ const HelpShell = (props: {
   createEffect(syncSession);
 
   onMount(() => {
-    if (props.surface === "panel") {
-      onCleanup(onContextChange((context) => setViewIds(context && context.app === appId ? (context.help ?? []) : [])));
-    }
-    if (props.surface === "panel" || props.surface === "modal") {
+    if (props.surface === "modal") {
       const key = (event: KeyboardEvent) => {
         if (event.defaultPrevented || event.isComposing) return;
         const target = event.target;
@@ -445,7 +363,7 @@ const HelpShell = (props: {
     const onScroll = () => {
       if (view() === "article" && scrollArea) props.session.articleScrollTop = scrollArea.scrollTop;
     };
-    if (props.surface === "modal" || props.surface === "panel") scrollArea?.addEventListener("scroll", onScroll, { passive: true });
+    if (props.surface === "modal") scrollArea?.addEventListener("scroll", onScroll, { passive: true });
     // Layout's breakpoints move page scrolling between its main column and the window; the contents follow.
     let resizeFrame: number | undefined;
     const onResize = () => {
@@ -466,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());
@@ -704,99 +622,6 @@ const HelpShell = (props: {
     }
   };
 
-  /** Rows: icon tile, title, and description; the start's groups, its further tasks, and search results use them. */
-  const TopicList = (listProps: { items: HelpTopic[]; marker?: string }) => (
-    <ul class="help-start-rows" {...(listProps.marker ? { [listProps.marker]: "" } : {})}>
-      <For each={listProps.items}>
-        {(topic) => (
-          <li>
-            <button type="button" class="help-start-row focus-ui" data-help-topic={topic.id} onClick={() => openTopic(topic.id)}>
-              <span class="help-topic-icon k2b-icon-tile help-start-row-icon app-accent-text" aria-hidden="true">
-                <i class={iconClass(topic.icon)} />
-              </span>
-              <span class="help-article-link-copy">
-                <span class="help-article-link-title">{topic.title}</span>
-                <Show when={topic.description}>{(description) => <span class="help-article-link-description">{description()}</span>}</Show>
-              </span>
-              <i class="ti ti-chevron-right help-start-row-arrow" aria-hidden="true" />
-            </button>
-          </li>
-        )}
-      </For>
-    </ul>
-  );
-
-  /** At most eight tasks as tiles; the app colour shows only in the icon. */
-  const TaskTiles = (tilesProps: { items: HelpTopic[] }) => (
-    <ul class="help-start-tiles" data-help-tiles="">
-      <For each={tilesProps.items}>
-        {(topic) => (
-          <li>
-            <button type="button" class="help-start-tile focus-ui" data-help-topic={topic.id} onClick={() => openTopic(topic.id)}>
-              <span class="help-topic-icon k2b-icon-tile help-start-tile-icon app-accent-text" aria-hidden="true">
-                <i class={iconClass(topic.icon)} />
-              </span>
-              <span class="help-start-tile-title">{topic.title}</span>
-              <Show when={topic.description}>{(description) => <span class="help-start-tile-description">{description()}</span>}</Show>
-            </button>
-          </li>
-        )}
-      </For>
-    </ul>
-  );
-
-  const groupTitle = (kind: HelpStartGroupKind) =>
-    ({ start: t().groupStart, reference: t().groupReference, troubleshoot: t().groupTroubleshoot })[kind];
-
-  const ArticleLinkTitle = (link: { link: HelpArticleLink }) => (
-    <span class="help-article-link-copy">
-      <span class="help-article-link-title">{link.link.title}</span>
-      <Show when={link.link.description}>{(description) => <span class="help-article-link-description">{description()}</span>}</Show>
-    </span>
-  );
-
-  /** "Next" leads on; related articles keep their own app's colour, and another app says whose article it is. */
-  const ArticleEnd = (end: { document: HelpDocumentPayload }) => (
-    <Show when={end.document.next || end.document.related.length > 0}>
-      <footer class="help-article-end">
-        <Show when={end.document.next}>
-          {(next) => (
-            <a class="help-article-next app-accent-scope focus-ui" href={next().url} style={appAccentStyle(next().accent)}>
-              <span class="help-article-next-label">{t().next}</span>
-              <span class="help-article-next-row">
-                <i class={`${iconClass(next().icon)} help-article-next-icon`} aria-hidden="true" />
-                <ArticleLinkTitle link={next()} />
-                <i class="ti ti-arrow-right help-article-next-arrow" aria-hidden="true" />
-              </span>
-            </a>
-          )}
-        </Show>
-        <Show when={end.document.related.length > 0}>
-          <section class="help-article-related" aria-labelledby="help-article-related-title">
-            <h4 id="help-article-related-title">{t().related}</h4>
-            <ul>
-              <For each={end.document.related}>
-                {(link) => (
-                  <li>
-                    <a class="help-article-related-link app-accent-scope focus-ui" href={link.url} style={appAccentStyle(link.accent)}>
-                      <span class="help-topic-icon k2b-icon-tile help-article-related-icon app-accent-text" aria-hidden="true">
-                        <i class={iconClass(link.icon)} />
-                      </span>
-                      <ArticleLinkTitle link={link} />
-                      <Show when={link.appId !== appId}>
-                        <span class="help-article-related-app app-accent-text">{link.appName}</span>
-                      </Show>
-                    </a>
-                  </li>
-                )}
-              </For>
-            </ul>
-          </section>
-        </Show>
-      </footer>
-    </Show>
-  );
-
   const ReaderContent = (content: { children: JSX.Element }) =>
     props.surface === "page" ? (
       <div class="p-4 sm:p-5">{content.children}</div>
@@ -806,8 +631,8 @@ const HelpShell = (props: {
       </ScrollArea>
     );
 
-  // The dialog and the panel copy from their ⋯ menu; only the page repeats the copy action beside the article.
-  const copyInMenu = props.surface === "modal" || props.surface === "panel";
+  // The dialog copies from its ⋯ menu; only the page repeats the copy action beside the article.
+  const copyInMenu = props.surface === "modal";
   const pageHref = () => (props.pageBase ? layoutHelpTopicHref(props.pageBase, view() === "article" ? activeId() : null) : undefined);
   const menuItems = () => [
     {
@@ -823,335 +648,169 @@ const HelpShell = (props: {
   return (
     <div
       ref={root}
-      class={
-        props.surface === "panel"
-          ? "help-shell app-accent-scope flex h-full min-h-0 flex-col"
-          : `help-shell app-accent-scope flex min-h-0 flex-col ${props.surface === "page" ? "" : "bg-[var(--ui-surface-raised)]"} ${
-              props.surface === "modal"
-                ? "h-[min(48rem,var(--ui-dialog-available-height))] overflow-hidden panel-dialog-shell [box-shadow:var(--ui-shadow-float)]"
-                : props.surface === "page"
-                  ? ""
-                  : "h-full"
-            }`
-      }
+      class={`help-shell app-accent-scope flex min-h-0 flex-col ${props.surface === "page" ? "" : "bg-[var(--ui-surface-raised)]"} ${
+        props.surface === "modal"
+          ? "h-[min(48rem,var(--ui-dialog-available-height))] overflow-hidden panel-dialog-shell [box-shadow:var(--ui-shadow-float)]"
+          : props.surface === "page"
+            ? ""
+            : "h-full"
+      }`}
       data-surface={props.surface}
-      style={
-        props.surface === "panel"
-          ? props.panel?.appearance
-          : [appAccentStyle(props.accent), props.appearance].filter(Boolean).join(";") || undefined
-      }
+      style={[appAccentStyle(props.accent), props.appearance].filter(Boolean).join(";") || undefined}
     >
-      {/* One head in every view: the search never moves between the start, an article, and results. An app's embedded
-          reader sits in the app's own chrome, which names it and picks its article, so it keeps only the search of its start. */}
-      {/* Help the reader may not see gets no head either: the slot already names the panel, and there is nothing to search. */}
-      <Show when={(props.surface !== "embedded" || view() === "hub") && props.panel?.state !== "unavailable"}>
-        <header class="help-head" data-help-head="">
-          <div class="help-head-inner help-measure">
-            <Show when={props.surface !== "embedded"}>
-              <div class="help-head-row">
-                {/* The back button takes the app tile's place in an article, so nothing beside it moves. */}
-                <Show
-                  when={view() === "article"}
-                  fallback={
-                    <span class="help-head-tile" aria-hidden="true">
-                      <i class={props.panel?.app?.icon ?? app?.iconClass ?? "ti ti-help-circle"} />
-                    </span>
-                  }
-                >
-                  <IconButton class="help-head-back" label={t().backToTopics} title={t().back} onClick={goBack}>
-                    <i class="ti ti-arrow-left" />
-                  </IconButton>
-                </Show>
-                <h2 id="layout-help-title" class="help-head-title">
-                  {appName ? (props.surface === "panel" ? appName : t().helpFor({ app: appName })) : t().help}
-                </h2>
-                <div class="help-head-actions" role="group" aria-label={t().actions}>
-                  <Dropdown.Root label={t().moreActions} position="bottom-left" items={menuItems()}>
-                    <Dropdown.Trigger iconOnly label={t().moreActions} variant="ghost" data-help-menu="">
-                      <i class="ti ti-dots" aria-hidden="true" />
-                    </Dropdown.Trigger>
-                  </Dropdown.Root>
-                  <Show when={props.surface === "modal"}>
-                    <IconButton label={t().closeHelp} title={t().close} onClick={props.close}>
-                      <i class="ti ti-x" />
-                    </IconButton>
-                  </Show>
-                </div>
-              </div>
-            </Show>
-            <TextInput
-              ref={searchInput}
-              type="search"
-              class="help-head-search"
-              icon="ti ti-search"
-              aria-label={t().searchHelp}
-              data-help-search=""
-              value={query()}
-              placeholder={t().searchPlaceholder}
-              onValueChange={changeQuery}
-            />
-          </div>
-        </header>
+      <Show when={props.surface !== "embedded" || view() === "hub"}>
+        <HelpHead
+          row={props.surface !== "embedded"}
+          back={view() === "article"}
+          tile={app?.iconClass ?? "ti ti-help-circle"}
+          title={appName ? t().helpFor({ app: appName }) : t().help}
+          menu={
+            <Dropdown.Root label={t().moreActions} position="bottom-left" items={menuItems()}>
+              <Dropdown.Trigger iconOnly label={t().moreActions} variant="ghost" data-help-menu="">
+                <i class="ti ti-dots" aria-hidden="true" />
+              </Dropdown.Trigger>
+            </Dropdown.Root>
+          }
+          closable={props.surface === "modal"}
+          onBack={goBack}
+          onClose={props.close}
+          query={query()}
+          onQuery={changeQuery}
+          searchRef={(element) => {
+            searchInput = element;
+          }}
+        />
       </Show>
 
       <ReaderContent>
-        <Show
-          when={props.panel?.state !== "unavailable"}
-          fallback={<Placeholder icon="ti ti-book-off" title={t().helpNotAvailable} description={t().helpNotAvailableDetail} />}
-        >
-          <Show when={view() === "hub"}>
-            <div ref={resultsRegion} data-help-results="" class="help-start help-measure" style={{ "min-height": resultsMinHeight() }}>
-              <Show
-                when={normalizedQuery()}
-                fallback={
-                  <>
-                    <Show when={start().view.length > 0}>
-                      <section class="help-start-section" data-help-view="" aria-labelledby="help-start-view-title">
-                        <h3 id="help-start-view-title" class="help-start-heading">
-                          <i class="ti ti-focus-2" aria-hidden="true" />
-                          {t().forThisView}
-                        </h3>
-                        <TopicList items={start().view} />
-                      </section>
-                    </Show>
-                    <Show when={start().tiles.length > 0}>
-                      <section class="help-start-section" data-help-tasks="" aria-labelledby="help-start-tasks-title">
-                        <h3 id="help-start-tasks-title" class="help-start-heading">
-                          <i class="ti ti-checklist" aria-hidden="true" />
-                          {t().whatToDo}
-                        </h3>
-                        <TaskTiles items={start().tiles} />
-                        <Show when={start().moreTasks.length > 0}>
-                          <TopicList items={start().moreTasks} marker="data-help-more-tasks" />
-                        </Show>
-                      </section>
-                    </Show>
-                    <Show when={start().groups.length > 0}>
-                      <div class="help-start-groups">
-                        <For each={start().groups}>
-                          {(group) => (
-                            <section
-                              class="help-start-section"
-                              data-help-group={group.kind}
-                              aria-labelledby={`help-start-${group.kind}-title`}
-                            >
-                              <h3 id={`help-start-${group.kind}-title`} class="help-start-heading">
-                                <i class={GROUP_ICONS[group.kind]} aria-hidden="true" />
-                                {groupTitle(group.kind)}
-                              </h3>
-                              <TopicList items={group.topics} />
-                            </section>
-                          )}
-                        </For>
-                      </div>
-                    </Show>
-                    {/* An app without Help says so plainly; only a failed read of its Help offers a way to try again. */}
-                    <Show when={topics().length === 0}>
-                      <Show
-                        when={props.panel?.state === "failed" || shell?.helpFailed}
-                        fallback={<Placeholder icon="ti ti-book-off" title={t().noArticles} description={t().noArticlesDetail} />}
-                      >
-                        <NoticeCard tone="danger" title={t().helpUnavailable} detail={t().helpUnavailableDetail} data-help-unavailable="">
-                          <Button size="sm" variant="secondary" onClick={() => location.reload()}>
-                            {t().reload}
-                          </Button>
-                        </NoticeCard>
-                      </Show>
-                    </Show>
+        <Show when={view() === "hub"}>
+          <div ref={resultsRegion} data-help-results="" class="help-start help-measure" style={{ "min-height": resultsMinHeight() }}>
+            <Show
+              when={normalizedQuery()}
+              fallback={
+                <HelpStartView
+                  start={start()}
+                  empty={topics().length === 0}
+                  failed={!!shell?.helpFailed}
+                  onOpen={openTopic}
+                  onReload={() => location.reload()}
+                  shortcuts={
                     <Show when={props.includeShortcuts !== false}>
-                      <StartShortcuts appName={appName} panel={props.surface === "panel"} platform={props.panel?.platform} />
+                      <StartShortcuts appName={appName} />
                     </Show>
-                  </>
+                  }
+                />
+              }
+            >
+              <HelpResultsView
+                results={results()}
+                searching={searching()}
+                failed={searchFailed()}
+                onRetry={() => setSearchAttempt((value) => value + 1)}
+                onOpen={openTopic}
+              />
+            </Show>
+          </div>
+        </Show>
+
+        <Show when={view() === "article" && activeTopic()}>
+          {(topic) => (
+            <article
+              class="help-article"
+              data-surface={props.surface}
+              ref={(element) => {
+                // Delegated from the article: its body, table of contents, and end hold the links.
+                element.addEventListener("click", followHelpLink);
+                onCleanup(() => element.removeEventListener("click", followHelpLink));
+              }}
+            >
+              <HelpArticleView
+                surface={props.surface}
+                topic={topic()}
+                appName={appName}
+                appId={appId}
+                parts={articleParts()}
+                document={payload()}
+                Markdown={MarkdownView}
+                showTools={articleSections().length > 0 || !copyInMenu}
+                sectionMenu={
+                  <Show when={articleSections().length > 0}>
+                    <Dropdown.Root
+                      label={t().onThisPage}
+                      position="bottom-left"
+                      items={articleSections().map((section) => ({
+                        label: section.label,
+                        choice: "radio" as const,
+                        checked: () => activeSectionId() === section.id,
+                        action: () => openArticleSection(section),
+                      }))}
+                    >
+                      <Dropdown.Trigger label={t().onThisPage} size="sm" tooltip={false} variant="secondary">
+                        <i class="ti ti-list" aria-hidden="true" />
+                        <span>{t().onThisPage}</span>
+                        <i class="ti ti-chevron-down" aria-hidden="true" />
+                      </Dropdown.Trigger>
+                    </Dropdown.Root>
+                  </Show>
                 }
-              >
-                {/* The count takes the place of the first heading, so the first row stays where it was. */}
-                <section class="help-start-section" data-help-search-results="">
-                  {/* A failed full-text search says so in the same line, with a way to try again; the results do not move. */}
-                  <div class="help-start-status">
-                    <span aria-live="polite">{t().results({ count: results().length })}</span>
-                    <Show when={searching()}>
-                      <i class="ti ti-loader-2 animate-spin" aria-hidden="true" />
-                    </Show>
-                    <Show when={searchFailed()}>
-                      <span class="help-start-status-warning" data-help-search-failed="" title={t().searchTitlesOnly} role="status">
-                        <i class="ti ti-alert-triangle" aria-hidden="true" />
-                        <span aria-hidden="true">{t().titlesOnly}</span>
-                        <span class="sr-only">{t().searchTitlesOnly}</span>
-                      </span>
-                      <Button
-                        size="xs"
-                        variant="ghost"
-                        class="help-start-status-retry"
-                        onClick={() => setSearchAttempt((value) => value + 1)}
-                      >
-                        {t().tryAgain}
-                      </Button>
-                    </Show>
-                  </div>
-                  <Show
-                    when={results().length > 0}
-                    fallback={
-                      <Show when={!searching()}>
-                        <Placeholder icon="ti ti-search-off" title={t().noResults} />
-                      </Show>
-                    }
-                  >
-                    <TopicList items={results()} />
+                copyButton={
+                  <Show when={!copyInMenu}>
+                    <IconButton
+                      class="help-article-tools-copy"
+                      disabled={!payload()}
+                      label={articleClipboard.wasCopied() ? t().articleCopied : t().copyArticle}
+                      title={articleClipboard.wasCopied() ? t().copied : t().copyArticle}
+                      onClick={() => void copyArticle(topic(), payload())}
+                    >
+                      <i class={articleClipboard.wasCopied() ? "ti ti-check" : "ti ti-markdown"} />
+                    </IconButton>
                   </Show>
-                </section>
-              </Show>
-            </div>
-          </Show>
-
-          <Show when={view() === "article" && activeTopic()}>
-            {(topic) => (
-              <article
-                class="help-article"
-                data-surface={props.surface}
-                ref={(element) => {
-                  // Delegated from the article: its body, table of contents, and end hold the links.
-                  element.addEventListener("click", followHelpLink);
-                  onCleanup(() => element.removeEventListener("click", followHelpLink));
-                }}
-              >
-                <div class="help-article-layout">
-                  <div class="help-article-main">
-                    <header class="help-article-head" data-help-article-head="">
-                      <div class="help-article-head-copy">
-                        {/* In the panel, its head already names the app and leads back to the start. */}
-                        <Show when={props.surface !== "panel"}>
-                          <p class="help-article-path">
-                            <Show when={appName}>
-                              {(name) => (
-                                <>
-                                  <span class="app-accent-text">{name()}</span>
-                                  <i class="ti ti-chevron-right" aria-hidden="true" />
-                                </>
-                              )}
-                            </Show>
-                            <button type="button" class="help-article-path-link focus-ui" onClick={goBack}>
-                              {t().help}
-                            </button>
-                          </p>
-                        </Show>
-                        <h3 ref={articleHeading} tabindex="-1" class="help-article-title focus-ui">
-                          {topic().title}
-                        </h3>
-                        <Show
-                          when={articleParts()?.lead}
-                          fallback={
-                            // An article without a leading paragraph, or a built-in topic, shows its description; a loading article shows neither yet.
-                            <Show when={articleParts() && topic().description}>
-                              {(description) => <p class="help-article-lead">{description()}</p>}
-                            </Show>
-                          }
-                        >
-                          {(lead) => <MarkdownView trustedHtml={lead()} class="help-document help-article-lead" />}
-                        </Show>
-                        <Show when={payload()?.needs || articleParts()?.steps}>
-                          {/* One row of facts; the access level appears here and nowhere else in the reader's chrome. */}
-                          <ul class="help-article-facts" aria-label={t().articleFacts}>
-                            <Show when={payload()?.needs}>
-                              {(level) => (
-                                <li class="help-article-fact" data-fact="needs">
-                                  <i class="ti ti-key" aria-hidden="true" />
-                                  <span>
-                                    {t().youNeed} <strong>{accessLabel(level())}</strong>
-                                  </span>
-                                </li>
-                              )}
-                            </Show>
-                            <Show when={articleParts()?.steps}>
-                              {(count) => (
-                                <li class="help-article-fact" data-fact="steps">
-                                  <i class="ti ti-list-numbers" aria-hidden="true" />
-                                  <span>{t().steps({ count: count() })}</span>
-                                </li>
-                              )}
-                            </Show>
-                          </ul>
-                        </Show>
-                        <Show when={articleSections().length > 0 || !copyInMenu}>
-                          <div class="help-article-tools">
-                            <Show when={articleSections().length > 0}>
-                              <Dropdown.Root
-                                label={t().onThisPage}
-                                position="bottom-left"
-                                items={articleSections().map((section) => ({
-                                  label: section.label,
-                                  choice: "radio" as const,
-                                  checked: () => activeSectionId() === section.id,
-                                  action: () => openArticleSection(section),
-                                }))}
-                              >
-                                <Dropdown.Trigger label={t().onThisPage} size="sm" tooltip={false} variant="secondary">
-                                  <i class="ti ti-list" aria-hidden="true" />
-                                  <span>{t().onThisPage}</span>
-                                  <i class="ti ti-chevron-down" aria-hidden="true" />
-                                </Dropdown.Trigger>
-                              </Dropdown.Root>
-                            </Show>
-                            <Show when={!copyInMenu}>
-                              <IconButton
-                                class="help-article-tools-copy"
-                                disabled={!payload()}
-                                label={articleClipboard.wasCopied() ? t().articleCopied : t().copyArticle}
-                                title={articleClipboard.wasCopied() ? t().copied : t().copyArticle}
-                                onClick={() => void copyArticle(topic(), payload())}
-                              >
-                                <i class={articleClipboard.wasCopied() ? "ti ti-check" : "ti ti-markdown"} />
-                              </IconButton>
-                            </Show>
-                          </div>
-                        </Show>
-                      </div>
-                      {/* The embedded readers sit in the app's own chrome and keep the flat head. */}
-                      <Show when={props.surface !== "embedded"}>
-                        <span class="help-article-icon k2b-icon-tile app-accent-text" aria-hidden="true">
-                          <i class={iconClass(topic().icon)} />
-                        </span>
-                      </Show>
-                    </header>
-                    <Show when={loading()}>
-                      <div class="min-h-[24rem]">
-                        <Placeholder state="loading" variant="panel" title={t().loading} />
-                      </div>
-                    </Show>
-                    <Show when={loadError()}>
-                      {(message) => (
-                        <NoticeCard tone="danger" title={t().loadFailed} detail={message()}>
-                          <Button size="sm" variant="secondary" onClick={() => setLoadAttempt((value) => value + 1)}>
-                            {t().tryAgain}
-                          </Button>
-                        </NoticeCard>
-                      )}
-                    </Show>
-                    <div ref={articleContent}>
-                      <Show when={articleParts()}>{(parts) => <MarkdownView trustedHtml={parts().body} class="help-document" />}</Show>
+                }
+                loading={
+                  <Show when={loading()}>
+                    <div class="min-h-[24rem]">
+                      <Placeholder state="loading" variant="panel" title={t().loading} />
                     </div>
-                    <Show when={payload()}>{(document) => <ArticleEnd document={document()} />}</Show>
-                  </div>
-                  <aside class="help-article-aside">
-                    <div class="help-article-aside-sticky">
-                      <TableOfContents
-                        items={articleSections()}
-                        title={t().onThisPage}
-                        scrollRoot={tocScrollRoot}
-                        contentRoot={() => articleContent}
-                        onActiveChange={(id) => setActiveSectionId(id ?? null)}
-                      />
-                      <Show when={!copyInMenu}>
-                        <Button size="sm" variant="ghost" disabled={!payload()} onClick={() => void copyArticle(topic(), payload())}>
-                          <i class={articleClipboard.wasCopied() ? "ti ti-check" : "ti ti-markdown"} />
-                          {articleClipboard.wasCopied() ? t().copied : t().copyMarkdown}
+                  </Show>
+                }
+                failure={
+                  <Show when={loadError()}>
+                    {(message) => (
+                      <NoticeCard tone="danger" title={t().loadFailed} detail={message()}>
+                        <Button size="sm" variant="secondary" onClick={() => setLoadAttempt((value) => value + 1)}>
+                          {t().tryAgain}
                         </Button>
-                      </Show>
-                    </div>
-                  </aside>
-                </div>
-              </article>
-            )}
-          </Show>
+                      </NoticeCard>
+                    )}
+                  </Show>
+                }
+                toc={
+                  <TableOfContents
+                    items={articleSections()}
+                    title={t().onThisPage}
+                    scrollRoot={tocScrollRoot}
+                    contentRoot={() => articleContent}
+                    onActiveChange={(id) => setActiveSectionId(id ?? null)}
+                  />
+                }
+                copyAction={
+                  <Show when={!copyInMenu}>
+                    <Button size="sm" variant="ghost" disabled={!payload()} onClick={() => void copyArticle(topic(), payload())}>
+                      <i class={articleClipboard.wasCopied() ? "ti ti-check" : "ti ti-markdown"} />
+                      {articleClipboard.wasCopied() ? t().copied : t().copyMarkdown}
+                    </Button>
+                  </Show>
+                }
+                headingRef={(element) => {
+                  articleHeading = element;
+                }}
+                contentRef={(element) => {
+                  articleContent = element;
+                }}
+                onBack={goBack}
+              />
+            </article>
+          )}
         </Show>
         <span class="sr-only" aria-live="polite">
           {articleClipboard.wasCopied() ? t().articleCopiedAnnouncement : ""}
@@ -1201,22 +860,6 @@ export function LayoutHelpPage(props: LayoutHelpPageProps) {
   );
 }
 
-/** Help inside a provider document; the server snapshot also owns the first browser render. */
-export function LayoutHelpPanel(props: LayoutHelpPanelProps) {
-  const session = createSession(props.initialTopic);
-  return (
-    <HelpShell
-      session={session}
-      initialArticle={props.initialTopic ? props.initialArticle : undefined}
-      close={() => {}}
-      documents={props.documents}
-      pageBase={props.pageBase}
-      surface="panel"
-      panel={props}
-    />
-  );
-}
-
 /** The dialog renders outside the app canvas; it takes the app's canvas colours along for the article head. */
 const canvasAppearance = () => {
   const canvas = document.querySelector(".cloud-app-canvas");