@k2b/cloud 0.37.0 → 0.38.0

package/src/shared/markdown/extensions/guided-help.ts

@@ -1,11 +1,7 @@
-import type { MarkedExtension, Tokens } from "marked";
+import { Lexer, type MarkedExtension, type Token, type Tokens } from "marked";
 
-type GuidedBlock = "compare" | "reference" | "steps";
-
-const guidedBlocks = new Set<GuidedBlock>(["compare", "reference", "steps"]);
-const headingMetaPattern = /\s+\{icon="([a-z0-9-]+)"\}\s*$/i;
-
-const slug = (value: string): string =>
+export const headingMetaPattern = /\s+\{icon="([a-z0-9-]+)"\}\s*$/i;
+export const helpHeadingSlug = (value: string): string =>
   value
     .toLocaleLowerCase()
     .normalize("NFKD")
@@ -13,63 +9,218 @@ const slug = (value: string): string =>
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "") || "section";
 
-const headingTitleTokens = (token: Tokens.Heading, hasMetadata: boolean): Tokens.Heading["tokens"] => {
-  if (!hasMetadata) return token.tokens;
-
+const headingTitleTokens = (token: Tokens.Heading): Token[] => {
   const tokens = [...token.tokens];
-  const trailingToken = tokens.at(-1);
-  if (trailingToken?.type !== "text") return tokens;
+  const trailing = tokens.at(-1);
+  if (trailing?.type === "text")
+    tokens[tokens.length - 1] = {
+      ...trailing,
+      raw: trailing.raw.replace(headingMetaPattern, ""),
+      text: trailing.text.replace(headingMetaPattern, ""),
+    };
+  return tokens;
+};
 
-  const raw = trailingToken.raw.replace(headingMetaPattern, "");
-  const text = trailingToken.text.replace(headingMetaPattern, "");
-  if (!raw && !text) {
-    tokens.pop();
-  } else {
-    tokens[tokens.length - 1] = { ...trailingToken, raw, text };
-  }
+const FENCE = /^([ \t]*(?:>[ \t]*|(?:[-+*]|\d+[.)])[ \t]+)*)(`{3,}|~{3,})(.*)$/;
+// A directive name ends at a space or the line end, as in the openers themselves: `:::reference-data` is text.
+const DIRECTIVE_OPENER = /^ {0,3}:::(?:steps|reference|compare|details|note|info|success|warning|danger)(?=[ \t]|$)/i;
+const DIRECTIVE_CLOSER = /^ {0,3}:::[ \t]*$/;
+const CALLOUT_OPENER = /^ {0,3}:::(?:note|info|success|warning|danger)(?=[ \t]|$)/i;
+const DETAILS_OPENER = /^ {0,3}:::details(?=[ \t]|$)/i;
 
-  return tokens;
+const detailsLexers = new WeakSet<Lexer>();
+
+/** The indentation column of a line prefix; a tab advances to the next multiple of four, as in Markdown. */
+const columns = (prefix: string): number => {
+  let column = 0;
+  for (const char of prefix) column = char === "\t" ? column + 4 - (column % 4) : column + 1;
+  return column;
 };
+/** The indentation after a prefix's last quote marker. */
+const indentAfterQuotes = (prefix: string): number => columns(prefix.slice(prefix.lastIndexOf(">") + 1));
 
 /**
- * Help-only Markdown affordances. The source stays useful as plain Markdown:
- * the directives merely add reading semantics to otherwise ordinary lists.
+ * A `:::details Title` block up to its own closing `:::`. One directive inside it (steps, reference, compare, a
+ * callout, which stays text there) keeps its own closer; directives do not nest further, and fenced code hides
+ * its lines. Details never nest; another details opener or a missing closer leaves the first opener as text.
  */
-export function guidedHelpExtension(): MarkedExtension {
-  const headingIds = new Map<string, number>();
+const detailsBlock = (
+  source: string,
+  start = 0,
+): { block?: { raw: string; title: string; body: string; callout: boolean }; stoppedAt: number } => {
+  const openerEnd = source.indexOf("\n", start);
+  const opener = /^:::details[ \t]+(\S[^\n]*)\n/.exec(source.slice(start, openerEnd + 1));
+  if (!opener) return { stoppedAt: source.length };
+  let offset = start + opener[0].length;
+  let inner = false;
+  let callout = false;
+  let listContentColumn: number | undefined;
+  let fence: { marker: string; prefix: string; quotes: number; list: boolean } | undefined;
+  while (offset < source.length) {
+    const newline = source.indexOf("\n", offset);
+    const end = newline < 0 ? source.length : newline + 1;
+    const line = source.slice(offset, end);
+    const text = line.replace(/\r?\n$/, "");
+    const marker = FENCE.exec(text);
+    const prefix = /^[ \t]*(?:>[ \t]*|(?:[-+*]|\d+[.)])[ \t]+)*/.exec(text)![0];
+    const quotes = prefix.split(">").length - 1;
+    const list = /[-+*]|\d+[.)]/.test(prefix);
+    const indentation = indentAfterQuotes(prefix);
+    if (fence && (quotes < fence.quotes || (fence.list && text.trim() && columns(/^[ \t>]*/.exec(text)![0]) < columns(fence.prefix))))
+      fence = undefined;
+    if (!fence) {
+      if (list) listContentColumn = indentation;
+      else if (text.trim() && listContentColumn !== undefined && indentation < listContentColumn) listContentColumn = undefined;
+    }
+    if (fence) {
+      if (
+        marker &&
+        marker[2]![0] === fence.marker[0] &&
+        marker[2]!.length >= fence.marker.length &&
+        /^[ \t]*$/.test(marker[3]!) &&
+        quotes === fence.quotes &&
+        indentAfterQuotes(marker[1]!) <= indentAfterQuotes(fence.prefix) + 3
+      )
+        fence = undefined;
+    } else if (marker && indentation - (listContentColumn ?? 0) <= 3 && !(marker[2]![0] === "`" && marker[3]!.includes("`")))
+      fence = { marker: marker[2]!, prefix: marker[1]!, quotes, list };
+    else if (DETAILS_OPENER.test(text)) return { stoppedAt: offset };
+    else if (DIRECTIVE_CLOSER.test(text)) {
+      if (!inner)
+        return {
+          block: {
+            raw: source.slice(start, end),
+            title: opener[1]!.trim(),
+            body: source.slice(start + opener[0].length, offset),
+            callout,
+          },
+          stoppedAt: end,
+        };
+      inner = false;
+    } else if (DIRECTIVE_OPENER.test(text)) {
+      inner = true;
+      callout ||= CALLOUT_OPENER.test(text);
+    }
+    offset = end;
+  }
+  return { stoppedAt: source.length };
+};
 
+const menuSegments = (tokens: Token[]): Token[][] => {
+  const segments: Token[][] = [[]];
+  for (const token of tokens) {
+    if (token.type !== "text" || !token.text.includes(" → ")) {
+      segments.at(-1)!.push(token);
+      continue;
+    }
+    const parts = token.text.split(" → ");
+    for (const [index, text] of parts.entries()) {
+      if (index > 0) segments.push([]);
+      segments.at(-1)!.push({ type: "text", raw: text, text });
+    }
+  }
+  return segments;
+};
+
+/** Help-only syntax; per-reader keys, links and heading ids are assigned after lexing. */
+export function guidedHelpExtension(): MarkedExtension {
   return {
-    hooks: {
-      preprocess(source) {
-        headingIds.clear();
-        return source;
-      },
-    },
     renderer: {
-      paragraph(token: Tokens.Paragraph) {
-        if (token.tokens.length !== 1 || token.tokens[0]?.type !== "strong") return false;
-        return `<p class="help-eyebrow">${this.parser.parseInline(token.tokens)}</p>`;
+      paragraph(token) {
+        if (token.tokens.length !== 1 || token.tokens[0]?.type !== "strong" || token.tokens[0].text.includes(" → ")) return false;
+        return `<p class="help-eyebrow">${this.parser.parseInline(token.tokens ?? [])}</p>`;
       },
-      heading(token: Tokens.Heading) {
-        const metadata = token.text.match(headingMetaPattern);
-        const title = metadata ? token.text.slice(0, metadata.index).trim() : token.text;
-        const baseId = slug(title);
-        const occurrence = headingIds.get(baseId) ?? 0;
-        headingIds.set(baseId, occurrence + 1);
-        const id = occurrence === 0 ? baseId : `${baseId}-${occurrence + 1}`;
-
-        if (token.depth === 2) {
-          const icon = metadata?.[1] ? `ti ti-${metadata[1]}` : "ti ti-point";
-          return `<h2 id="${id}" class="help-section-title" data-help-icon="${icon}">
-  <span class="help-section-icon" aria-hidden="true"><i class="${icon}"></i></span>
-  <span>${this.parser.parseInline(headingTitleTokens(token, Boolean(metadata)))}</span>
-</h2>`;
-        }
-
-        return `<h${token.depth} id="${id}">${this.parser.parseInline(token.tokens)}</h${token.depth}>`;
+      heading(token) {
+        const id: unknown = Reflect.get(token, "helpId");
+        const title = this.parser.parseInline(token.depth === 2 ? headingTitleTokens(token) : token.tokens);
+        return `<h${token.depth} id="${typeof id === "string" ? id : "section"}"${token.depth === 2 ? ' class="help-section-title"' : ""}>${title}</h${token.depth}>`;
+      },
+      strong(token) {
+        if (!token.text.includes(" → ")) return false;
+        const chips = menuSegments(token.tokens ?? []).map(
+          (segment) => `<span class="k2b-label-chip">${this.parser.parseInline(segment)}</span>`,
+        );
+        return `<span class="help-menu-path">${chips.join('<span class="help-menu-path-separator" aria-hidden="true">›</span><span class="k2b-sr-only"> → </span>')}</span>`;
       },
     },
     extensions: [
+      {
+        name: "helpKbd",
+        level: "inline",
+        start: (source) => source.indexOf(":kbd["),
+        tokenizer(source) {
+          const match = /^:kbd\[([^\]\n]*)\]/.exec(source);
+          return match ? { type: "helpKbd", raw: match[0], keys: match[1] } : undefined;
+        },
+        renderer: (token) => String(token.html ?? ""),
+      },
+      {
+        name: "helpLabel",
+        level: "inline",
+        start: (source) => source.indexOf("**"),
+        tokenizer(source) {
+          const match = /^(\*\*(?:[^*]|\*(?!\*))+?\*\*)\{icon="([a-z0-9-]+)"\}/.exec(source);
+          if (!match) return undefined;
+          const [strong] = Lexer.lexInline(match[1]!);
+          if (strong?.type !== "strong") return undefined;
+          const icon = /^\{icon="([a-z0-9-]+)"\}/.exec(source.slice(strong.raw.length));
+          if (!icon) return undefined;
+          return {
+            ...strong,
+            type: "helpLabel",
+            raw: strong.raw + icon[0],
+            icon: icon[1],
+            tokens: this.lexer.inlineTokens(strong.text),
+          };
+        },
+        renderer(token) {
+          const icon = `<i class="ti ti-${token.icon}" aria-hidden="true"></i>`;
+          const segments = menuSegments(token.tokens ?? []);
+          const chips = segments.map(
+            (segment, index) => `<span class="k2b-label-chip">${index === 0 ? icon : ""}${this.parser.parseInline(segment)}</span>`,
+          );
+          return segments.length === 1
+            ? chips[0]!
+            : `<span class="help-menu-path">${chips.join('<span class="help-menu-path-separator" aria-hidden="true">›</span><span class="k2b-sr-only"> → </span>')}</span>`;
+        },
+        childTokens: ["tokens"],
+      },
+      {
+        name: "helpUnresolvedLink",
+        level: "inline",
+        renderer(token) {
+          return this.parser.parseInline(token.tokens ?? []);
+        },
+        childTokens: ["tokens"],
+      },
+      {
+        name: "helpDetails",
+        level: "block",
+        tokenizer(source) {
+          if (detailsLexers.has(this.lexer)) return undefined;
+          const { block } = detailsBlock(source);
+          if (!block) return undefined;
+          detailsLexers.add(this.lexer);
+          try {
+            return {
+              type: "helpDetails",
+              raw: block.raw,
+              title: block.title,
+              // Queued like paragraph text, so a link definition below the block applies to the title too.
+              titleTokens: this.lexer.inline(block.title),
+              callout: block.callout,
+              // The body joins this document: its links, steps, and reference blocks work as anywhere else.
+              tokens: this.lexer.blockTokens(block.body, []),
+            };
+          } finally {
+            detailsLexers.delete(this.lexer);
+          }
+        },
+        renderer(token) {
+          return `<details class="k2b-disclosure help-details" data-surface="plain"><summary><span>${this.parser.parseInline(token.titleTokens ?? [])}</span><i class="ti ti-chevron-down k2b-disclosure__chevron" aria-hidden="true"></i></summary><div class="k2b-disclosure__content">${this.parser.parse(token.tokens ?? [])}</div></details>`;
+        },
+        childTokens: ["titleTokens", "tokens"],
+      },
       {
         name: "guidedHelpBlock",
         level: "block",
@@ -77,21 +228,14 @@ export function guidedHelpExtension(): MarkedExtension {
           return source.match(/^:::(?:compare|reference|steps)\b/)?.index;
         },
         tokenizer(source) {
-          const match = source.match(/^:::(compare|reference|steps)[ \t]*\n([\s\S]*?)\n:::(?:\n|$)/);
-          if (!match) return undefined;
-          const kind = match[1] as GuidedBlock;
-          if (!guidedBlocks.has(kind)) return undefined;
-          const content = match[2]?.trim() ?? "";
-          return {
-            type: "guidedHelpBlock",
-            raw: match[0],
-            kind,
-            tokens: this.lexer.blockTokens(content),
-          };
+          const match = /^:::(compare|reference|steps)[ \t]*\n([\s\S]*?)\n:::(?:\n|$)/.exec(source);
+          return match
+            ? { type: "guidedHelpBlock", raw: match[0], kind: match[1], tokens: this.lexer.blockTokens(match[2]?.trim() ?? "") }
+            : undefined;
         },
-        renderer(token: Tokens.Generic) {
-          const kind = token.kind as GuidedBlock;
-          return `<div class="help-${kind}">${this.parser.parse(token.tokens as Tokens.Generic[])}</div>`;
+        renderer(token) {
+          const body = this.parser.parse(token.tokens ?? []);
+          return `<div class="help-${token.kind}">${token.kind === "steps" ? body.replace(/<ol([^>]*) class="[^"]*"/, '<ol$1 class="k2b-steps"') : body}</div>`;
         },
         childTokens: ["tokens"],
       },

package/src/shared/markdown/formula.ts

@@ -571,7 +571,7 @@ const isCurrentFormulaCell = (row: number, col: number, ctx: EvalContext): boole
  * a column that's itself filled with `=hours * rate` formulas computes
  * the chain correctly instead of seeing the literal formula strings.
  */
-const evaluateCell = (row: number, col: number, ctx: EvalContext): EvalResult => {
+export const evaluateTableCell = (row: number, col: number, ctx: EvalContext): EvalResult => {
   const cell = cellAt(row, col, ctx);
   if (!cell.startsWith("=")) {
     const text = cell.trim();
@@ -623,7 +623,7 @@ const collectColumnValues = (arg: AST, state: EvalState): { values: string[] } |
   const values: string[] = [];
   for (let r = 0; r < state.ctx.rows.length; r++) {
     if (isCurrentFormulaCell(r, lookup.index, state.ctx)) continue;
-    const result = evaluateCell(r, lookup.index, state.ctx);
+    const result = evaluateTableCell(r, lookup.index, state.ctx);
     if (result.kind === "ok") values.push(toString(result.value));
     // errored cells silently skipped — same handling as non-numeric cells
   }
@@ -790,10 +790,10 @@ const FUNCTIONS: Record<string, FuncImpl> = {
     let total = 0;
     for (let r = 0; r < state.ctx.rows.length; r++) {
       if (isCurrentFormulaCell(r, condLookup.index, state.ctx) || isCurrentFormulaCell(r, sumLookup.index, state.ctx)) continue;
-      const condResult = evaluateCell(r, condLookup.index, state.ctx);
+      const condResult = evaluateTableCell(r, condLookup.index, state.ctx);
       if (condResult.kind !== "ok") continue;
       if (!isEqual(condResult.value, condValueArg.value)) continue;
-      const sumResult = evaluateCell(r, sumLookup.index, state.ctx);
+      const sumResult = evaluateTableCell(r, sumLookup.index, state.ctx);
       if (sumResult.kind !== "ok") continue;
       const n = toNumber(sumResult.value);
       if (n !== null) total += n;
@@ -841,7 +841,7 @@ const FUNCTIONS: Record<string, FuncImpl> = {
     let sum = 0;
     for (let i = 0; i < row.length; i++) {
       if (i === state.ctx.currentCol) continue;
-      const result = evaluateCell(state.ctx.currentRow, i, state.ctx);
+      const result = evaluateTableCell(state.ctx.currentRow, i, state.ctx);
       if (result.kind !== "ok") continue;
       const n = toNumber(result.value);
       if (n !== null) sum += n;
@@ -855,7 +855,7 @@ const FUNCTIONS: Record<string, FuncImpl> = {
     let count = 0;
     for (let i = 0; i < row.length; i++) {
       if (i === state.ctx.currentCol) continue;
-      const result = evaluateCell(state.ctx.currentRow, i, state.ctx);
+      const result = evaluateTableCell(state.ctx.currentRow, i, state.ctx);
       if (result.kind !== "ok") continue;
       const n = toNumber(result.value);
       if (n !== null) {
@@ -890,7 +890,7 @@ const FUNCTIONS: Record<string, FuncImpl> = {
       }
       const rawCell = cellAt(state.ctx.currentRow, lookup.index, state.ctx);
       if (rawCell.trim().length === 0) return state.evaluate(args[1]!);
-      return evaluateCell(state.ctx.currentRow, lookup.index, state.ctx);
+      return evaluateTableCell(state.ctx.currentRow, lookup.index, state.ctx);
     }
     const v = state.evaluate(args[0]!);
     if (v.kind === "error") return v;
@@ -1182,7 +1182,7 @@ const evaluateAst = (ast: AST, ctx: EvalContext): EvalResult => {
           lookup.suggestion,
         );
       }
-      return evaluateCell(ctx.currentRow, lookup.index, ctx);
+      return evaluateTableCell(ctx.currentRow, lookup.index, ctx);
     }
     case "neg": {
       const v = evaluateAst(ast.operand, ctx);

package/src/shared/markdown/index.ts

@@ -5,13 +5,14 @@
  * the visual appearance of the CodeMirror editor extensions.
  */
 
-import { markdownInfoBlocks } from "@k2b/ui";
-import { Marked, type MarkedExtension } from "marked";
+import { formatShortcut, type KeyboardPlatform, markdownInfoBlocks } from "@k2b/ui";
+import { Marked, type MarkedExtension, type Token } from "marked";
 import sanitizeHtml from "sanitize-html";
+import { type HelpLinkResolver, parseHelpReference } from "../help";
 import { markdownCalloutSanitizeOptions } from "./callout-sanitizer";
 import { markdownClient } from "./client";
 import { codeExtension, plainCodeExtension } from "./extensions/code";
-import { guidedHelpExtension } from "./extensions/guided-help";
+import { guidedHelpExtension, headingMetaPattern, helpHeadingSlug } from "./extensions/guided-help";
 import { imagesExtension } from "./extensions/images";
 import { katexExtension } from "./extensions/katex";
 import { linksExtension } from "./extensions/links";
@@ -19,6 +20,7 @@ import { markExtension } from "./extensions/mark";
 import { subSupExtension } from "./extensions/sub-sup";
 import { tablesExtension } from "./extensions/tables";
 import { taskListExtension } from "./extensions/task-list";
+import { escapeHtml } from "./shared";
 
 // Create a configured marked instance
 type MarkdownProfile = "content" | "help";
@@ -74,7 +76,7 @@ export type MarkdownRenderOptions = {
   locale?: string;
 };
 
-const sanitizeRenderedHtml = (html: string): string => {
+const sanitizeRenderedHtml = (html: string, profile: MarkdownProfile = "content"): string => {
   const callouts = markdownCalloutSanitizeOptions();
   return sanitizeHtml(html, {
     ...callouts,
@@ -84,6 +86,7 @@ const sanitizeRenderedHtml = (html: string): string => {
       "aside",
       "br",
       "div",
+      ...(profile === "help" ? ["details", "summary", "kbd"] : []),
       "figcaption",
       "figure",
       "i",
@@ -115,7 +118,7 @@ const sanitizeRenderedHtml = (html: string): string => {
       "tr",
     ],
     allowedAttributes: {
-      "*": ["aria-hidden", "aria-label", "class", "data-help-icon", "data-tone", "id", "title"],
+      "*": ["aria-hidden", "aria-label", "class", "data-tone", "id", "title"],
       a: [
         "href",
         "name",
@@ -128,6 +131,7 @@ const sanitizeRenderedHtml = (html: string): string => {
       annotation: ["encoding"],
       aside: [{ name: "role", multiple: false, values: ["note"] }],
       code: ["class"],
+      ...(profile === "help" ? { details: [{ name: "data-surface", multiple: false, values: ["plain"] }] } : {}),
       div: ["class", "data-block-name", "style"],
       img: ["alt", "class", "height", "loading", "src", "title", "width", "style"],
       input: ["checked", "class", "disabled", "type"],
@@ -210,16 +214,73 @@ export function renderMarkdownSync(content: string, options: MarkdownRenderOptio
  * Render trusted documentation Markdown with guided sections and internal
  * navigation. All fenced code remains visible source, as in ordinary Markdown.
  */
-export function renderHelpMarkdown(content: string, locale?: string): string {
+export type HelpMarkdownRenderOptions = { locale?: string; platform?: KeyboardPlatform; links?: HelpLinkResolver };
+export type { HelpLinkResolver } from "../help";
+
+/** Lexer shared by rendering, startup validation and agent source conversion. */
+export const lexHelpMarkdown = (content: string, locale?: string) => markedFor("help", "widget", locale).lexer(content);
+/**
+ * Visit tokens in the order of marked's walkTokens. Marked concatenates every visitor result into a new array per
+ * token, which grows quadratically with the number of sibling tokens in one paragraph.
+ */
+export const walkHelpTokens = (tokens: Token[], visitor: (token: Token) => void) => {
+  const childTokens = markedFor("help").defaults.extensions?.childTokens ?? {};
+  const walk = (list: readonly Token[]) => {
+    for (const token of list) {
+      visitor(token);
+      if (token.type === "table") {
+        for (const cell of token.header) walk(cell.tokens);
+        for (const row of token.rows) for (const cell of row) walk(cell.tokens);
+      } else if (token.type === "list") walk(token.items);
+      else if (childTokens[token.type])
+        for (const key of childTokens[token.type]!) walk((Reflect.get(token, key) as Token[] | Token[][]).flat(Infinity) as Token[]);
+      else if ("tokens" in token && token.tokens) walk(token.tokens);
+    }
+  };
+  walk(tokens);
+};
+
+export function renderHelpMarkdown(content: string, options: HelpMarkdownRenderOptions = {}): string {
   if (!content || typeof content !== "string") return "";
-  const html = markedFor("help", "widget", locale).parse(content);
-  return typeof html === "string" ? sanitizeRenderedHtml(html) : "";
+  const instance = markedFor("help", "widget", options.locale);
+  const tokens = instance.lexer(content);
+  const headingIds = new Map<string, number>();
+  walkHelpTokens(tokens, (token) => {
+    if (token.type === "heading") {
+      const base = helpHeadingSlug(token.text.replace(headingMetaPattern, "").trim());
+      const occurrence = headingIds.get(base) ?? 0;
+      headingIds.set(base, occurrence + 1);
+      Reflect.set(token, "helpId", occurrence === 0 ? base : `${base}-${occurrence + 1}`);
+    } else if (token.type === "helpKbd") {
+      const shortcut = formatShortcut(String(token.keys), { platform: options.platform ?? "other", locale: options.locale });
+      token.html = `<kbd class="k2b-kbd"><span class="k2b-sr-only">${escapeHtml(shortcut.name)}</span><span class="k2b-kbd__keys" aria-hidden="true">${shortcut.keys.map((key) => `<kbd class="k2b-kbd__key">${escapeHtml(key.label)}</kbd>`).join("")}</span></kbd>`;
+    } else if (token.type === "link" && token.href.startsWith("help:")) {
+      const ref = parseHelpReference(token.href.slice(5));
+      const target = ref && options.links?.(ref);
+      if (target) token.href = target.url + ref.fragment;
+      else token.type = "helpUnresolvedLink";
+    }
+  });
+  return sanitizeRenderedHtml(instance.parser(tokens), "help");
+}
+
+/** Derive Help search text from already-rendered HTML. */
+export function helpHtmlToPlainText(html: string): string {
+  // The text a screen reader reads: key names instead of key caps, no decorative separators, and words of
+  // adjacent blocks (a callout's title and body, a summary and its details) kept apart.
+  const spaced = html.replace(/<\/(?:p|div|summary|li|h[1-6]|td|th)>/g, "$& ");
+  // Hidden parts are spans and icons; the filter only sees tags that the first pass keeps.
+  const spoken = sanitizeHtml(spaced, {
+    allowedTags: ["span", "i"],
+    allowedAttributes: { "*": ["aria-hidden"] },
+    exclusiveFilter: (frame) => frame.attribs["aria-hidden"] === "true",
+  });
+  return sanitizeHtml(spoken, { allowedTags: [], allowedAttributes: {} }).replace(/\s+/g, " ").trim();
 }
 
 /** Plain text used by lightweight client-side help search indexes. */
-export function markdownToPlainText(content: string): string {
-  const html = renderHelpMarkdown(content);
-  return sanitizeHtml(html, { allowedTags: [], allowedAttributes: {} }).replace(/\s+/g, " ").trim();
+export function markdownToPlainText(content: string, locale?: string): string {
+  return helpHtmlToPlainText(renderHelpMarkdown(content, { locale }));
 }
 
 export { marked };

package/src/ssr/Layout.tsx

@@ -1,5 +1,5 @@
 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 { readShellFocusCookie } from "../_internal/shell-focus";
@@ -14,11 +14,12 @@ 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 { getLayoutHelp, layoutHelpFailed } from "./help";
 import LayoutFooter from "./LayoutFooter";
 import LayoutHeader from "./LayoutHeader";
 import LayoutRail, { type LayoutAppLink } from "./LayoutRail";
 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 { derivePageTrail } from "./page-trail";
@@ -36,10 +37,14 @@ 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. */;
   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
@@ -206,7 +211,12 @@ export default function Layout(props: LayoutProps) {
       .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 = {
+    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 } }
@@ -235,6 +245,10 @@ export default function Layout(props: LayoutProps) {
               <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
             </main>
           </PageTrailProvider>
+          <div data-print-fallback="">
+            <p>{t.printFallbackTitle}</p>
+            <p>{props.printHint ?? t.printFallbackHint}</p>
+          </div>
         </div>
       </LocaleProvider>
     );
@@ -292,6 +306,10 @@ export default function Layout(props: LayoutProps) {
             {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
           </div>
         </ShellDataProvider>
+        <div data-print-fallback="">
+          <p>{t.printFallbackTitle}</p>
+          <p>{props.printHint ?? t.printFallbackHint}</p>
+        </div>
       </div>
     </LocaleProvider>
   );