@flamingo-stack/openframe-frontend-core 0.0.489 → 0.0.490-snapshot.20260728181420

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.489",
+  "version": "0.0.490-snapshot.20260728181420",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/chat-message-enhanced.tsx

@@ -11,6 +11,7 @@ import { ApprovalBatchMessage } from "./approval-batch-message"
 import { ErrorMessageDisplay } from "./error-message-display"
 import { ContextCompactionDisplay } from "./context-compaction-display"
 import { ThinkingDisplay } from "./thinking-display"
+import { GuideDisplay } from "./guide-display"
 import { SimpleMarkdownRenderer } from "../ui/simple-markdown-renderer"
 import type { ChatRef } from "./chat-ref.types"
 import { remarkCardLinks } from "./remark-card-links"
@@ -172,7 +173,12 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
       // duplicates so two siblings never collide on the same React key.
       const emittedBlockKeys = new Set<string>()
       segments.forEach((segment, segIdx) => {
-        if (segment.type !== 'text') return
+        // Both markdown-bearing segment types take part: a `guide` body is
+        // authored by the same LLM and carries the same `[card://]` markers,
+        // so skipping it here left its markers with no `inlineByKey` entry and
+        // no hoisted card — the `<a card://>` override silently degraded them
+        // to a bare title / id.
+        if (segment.type !== 'text' && segment.type !== 'guide') return
         const text = segment.text
         const parts: SegmentPart[] = []
         let cursor = 0
@@ -384,6 +390,52 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
       }
     }, [hasMarkerSupport, hasMentionSupport, renderMention, chatRefs, renderingPlan, NavLinkAnchor])
 
+    /**
+     * Body of a markdown-bearing segment (`text` / `guide`).
+     *
+     * No block markers in this segment → a single SimpleMarkdownRenderer call
+     * (the vast majority of messages). Otherwise the text is split at each
+     * marker and block payloads are interleaved: each text chunk includes its
+     * trailing marker so the inline pill renders at the right position via the
+     * `<a>` override, and block payloads land AS SIBLINGS between text chunks —
+     * HTML-valid (block DOM never nests inside `<p>`) AND positionally correct
+     * (the block appears where the marker is in the flow, not at the segment's
+     * end). Stable React keys come from the card key (block) and chunk position
+     * (text); streaming token-by-token reuses the same React instances so
+     * `<Video>` doesn't remount mid-play.
+     */
+    const renderSegmentBody = (segIndex: number, text: string) => {
+      const parts = renderingPlan?.partsBySegment.get(segIndex)
+      if (!parts || parts.length === 0) {
+        return (
+          <SimpleMarkdownRenderer
+            content={text}
+            textSize="compact"
+            additionalRemarkPlugins={cardRemarkPlugins}
+            componentOverrides={cardComponentOverrides}
+          />
+        )
+      }
+      return parts.map((part, pIdx) => {
+        if (part.kind === 'text') {
+          return (
+            <SimpleMarkdownRenderer
+              key={`t-${pIdx}`}
+              content={part.text}
+              textSize="compact"
+              additionalRemarkPlugins={cardRemarkPlugins}
+              componentOverrides={cardComponentOverrides}
+            />
+          )
+        }
+        return (
+          <div key={`b-${part.key}`} className="my-3">
+            {part.node}
+          </div>
+        )
+      })
+    }
+
     const getAvatarProps = () => {
       const displayName = name || (isUser ? "User" : assistantType === 'mingo' ? "Mingo" : "Fae")
       const isMingo = assistantType === 'mingo'
@@ -488,60 +540,19 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           {(!isSystem || segments.length > 0) && <div className="flex flex-col gap-2">
             {segments.map((segment, index) => {
                 if (segment.type === 'text') {
-                  const parts = renderingPlan?.partsBySegment.get(index)
-                  const wrapperClass = cn(
-                    "min-w-0 w-full break-words text-h4",
-                    isError ? "text-ods-error" : "text-ods-text-primary",
-                  )
-                  // No block markers in this segment → single
-                  // SimpleMarkdownRenderer call (existing behaviour
-                  // preserved for the vast majority of messages).
-                  if (!parts || parts.length === 0) {
-                    return (
-                      <div key={index} className={wrapperClass}>
-                        <SimpleMarkdownRenderer
-                          content={segment.text}
-                          textSize="compact"
-                          additionalRemarkPlugins={cardRemarkPlugins}
-                          componentOverrides={cardComponentOverrides}
-                        />
-                      </div>
-                    )
-                  }
-                  // Block markers present → split text at each marker
-                  // and interleave block payloads. Each text chunk
-                  // includes its trailing marker so the inline pill
-                  // renders at the right position via the `<a>`
-                  // override. Block payloads land AS SIBLINGS between
-                  // text chunks — HTML-valid (block DOM never nests
-                  // inside `<p>`) AND positionally correct (block
-                  // appears where the marker is in the flow, not at
-                  // the segment's end). Stable React keys come from
-                  // the card key (block) and chunk position (text);
-                  // streaming token-by-token reuses the same React
-                  // instances so `<Video>` doesn't remount mid-play.
                   return (
-                    <div key={index} className={wrapperClass}>
-                      {parts.map((part, pIdx) => {
-                        if (part.kind === 'text') {
-                          return (
-                            <SimpleMarkdownRenderer
-                              key={`t-${pIdx}`}
-                              content={part.text}
-                              textSize="compact"
-                              additionalRemarkPlugins={cardRemarkPlugins}
-                              componentOverrides={cardComponentOverrides}
-                            />
-                          )
-                        }
-                        return (
-                          <div key={`b-${part.key}`} className="my-3">
-                            {part.node}
-                          </div>
-                        )
-                      })}
+                    <div
+                      key={index}
+                      className={cn(
+                        "min-w-0 w-full break-words text-h4",
+                        isError ? "text-ods-error" : "text-ods-text-primary",
+                      )}
+                    >
+                      {renderSegmentBody(index, segment.text)}
                     </div>
                   )
+                } else if (segment.type === 'guide') {
+                  return <GuideDisplay key={index}>{renderSegmentBody(index, segment.text)}</GuideDisplay>
                 } else if (segment.type === 'tool_execution') {
                   return (
                     <ToolExecutionDisplay

package/src/components/chat/guide-display.tsx

@@ -0,0 +1,44 @@
+"use client"
+
+import { forwardRef } from "react"
+
+import { cn } from "../../utils/cn"
+import { CompassIcon } from "../icons-v2-generated"
+import type { GuideDisplayProps } from "./types"
+
+const GUIDE_LABEL = "OpenFrame Guide"
+
+/**
+ * `GUIDE` segment — the assistant's how-to/documentation answer, framed as a
+ * titled card instead of a bare paragraph.
+ *
+ * Chrome only: the caller renders the markdown body and passes it as children,
+ * so a guide goes through the SAME body pipeline as a text segment
+ * (`[card://]` splitting + hoisted entity cards + mention chips). Rendering the
+ * raw markdown here instead would bypass that plan and degrade every card
+ * marker inside a guide to a bare title.
+ */
+const GuideDisplay = forwardRef<HTMLDivElement, GuideDisplayProps>(
+  ({ className, children, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "flex flex-col gap-[var(--spacing-system-m)] rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-m)]",
+          className
+        )}
+        {...props}
+      >
+        <div className="flex items-center gap-[var(--spacing-system-xs)]">
+          <CompassIcon size={16} className="shrink-0 text-ods-open-yellow" />
+          <span className="text-h5 text-ods-open-yellow">{GUIDE_LABEL}</span>
+        </div>
+        <div className="min-w-0 w-full break-words text-h4 text-ods-text-primary">{children}</div>
+      </div>
+    )
+  }
+)
+
+GuideDisplay.displayName = "GuideDisplay"
+
+export { GuideDisplay }

package/src/components/chat/hooks/use-nats-chat-adapter.ts

@@ -442,6 +442,8 @@ export function appendToTrailingAssistant(
       merged[merged.length - 1] = { type: 'text', text: tail.text + seg.text }
     } else if (seg.type === 'thinking' && tail?.type === 'thinking') {
       merged[merged.length - 1] = { type: 'thinking', text: tail.text + seg.text }
+    } else if (seg.type === 'guide' && tail?.type === 'guide') {
+      merged[merged.length - 1] = { type: 'guide', text: tail.text + seg.text }
     } else if (seg.type === 'approval_batch') {
       // Approval deltas must be IDEMPOTENT: the escalated-result emit can be
       // seen twice (live + catch-up replay over hydrated history), so upsert

package/src/components/chat/hooks/use-realtime-chunk-processor.ts

@@ -173,6 +173,16 @@ export function useRealtimeChunkProcessor(
           break
         }
 
+        case 'guide': {
+          const segments = accumulator.appendGuide(action.text)
+          if (isInStreamRef.current || !hasEverStreamedRef.current) {
+            emitSegments(segments)
+          } else {
+            emitSegments([{ type: 'guide', text: action.text }], { append: true })
+          }
+          break
+        }
+
         case 'tool_execution': {
           // A starting tool run means the agent's turn is in progress even
           // when this lands after MESSAGE_END (approved commands execute

package/src/components/chat/index.ts

@@ -6,6 +6,7 @@ export * from './approval-batch-message'
 export * from './context-compaction-display'
 export * from './expand-chevron'
 export * from './thinking-display'
+export * from './guide-display'
 export * from './error-message-display'
 export * from './chat-container'
 export * from './chat-input'

package/src/components/chat/types/component.types.ts

@@ -556,6 +556,15 @@ export interface ThinkingDisplayProps extends HTMLAttributes<HTMLDivElement> {
   isStreaming?: boolean
 }
 
+// ========== Guide Display Props ==========
+
+export interface GuideDisplayProps extends HTMLAttributes<HTMLDivElement> {
+  /** Rendered guide body. `ChatMessageEnhanced` passes the SAME markdown
+   *  output a text segment gets, so `[card://]` cards and mention chips
+   *  behave identically inside a guide. */
+  children?: ReactNode
+}
+
 // ========== Model Display Props ==========
 
 export interface ModelDisplayProps extends HTMLAttributes<HTMLDivElement> {

package/src/components/chat/types/message.types.ts

@@ -10,6 +10,7 @@ import type { AssistantType, AuthorType, ChatApprovalStatus, MessageOwner } from
 export const MESSAGE_TYPE = {
   TEXT: 'TEXT',
   THINKING: 'THINKING',
+  GUIDE: 'GUIDE',
   EXECUTING_TOOL: 'EXECUTING_TOOL',
   EXECUTED_TOOL: 'EXECUTED_TOOL',
   APPROVAL_REQUEST: 'APPROVAL_REQUEST',
@@ -170,6 +171,15 @@ export type ThinkingSegment = {
   text: string
 }
 
+/** Guide answer body — the assistant's how-to/documentation reply, rendered as
+ *  a titled "OpenFrame Guide" card instead of a bare paragraph. `text` is
+ *  markdown, streamed in fragments like a `text` segment and coalesced by the
+ *  accumulator. */
+export type GuideSegment = {
+  type: 'guide'
+  text: string
+}
+
 export type ToolExecutionSegment = {
   type: 'tool_execution'
   data: ToolExecutionData
@@ -208,7 +218,7 @@ export type ContextCompactionSegment = {
   summary?: string
 }
 
-export type MessageSegment = TextSegment | ThinkingSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
+export type MessageSegment = TextSegment | ThinkingSegment | GuideSegment | ToolExecutionSegment | ApprovalRequestSegment | ApprovalBatchSegment | ErrorSegment | ContextCompactionSegment
 
 export type MessageContent = string | MessageSegment[]
 
@@ -228,6 +238,11 @@ export interface ThinkingMessageData extends MessageDataBase {
   text?: string
 }
 
+export interface GuideMessageData extends MessageDataBase {
+  type: 'GUIDE'
+  text?: string
+}
+
 export interface ExecutingToolMessageData extends MessageDataBase {
   type: 'EXECUTING_TOOL'
   integratedToolType?: string
@@ -309,6 +324,7 @@ export interface ContextCompactionEndMessageData extends MessageDataBase {
 export type MessageData =
   | TextMessageData
   | ThinkingMessageData
+  | GuideMessageData
   | ExecutingToolMessageData
   | ExecutedToolMessageData
   | ApprovalRequestMessageData

package/src/components/chat/types/processing.types.ts

@@ -16,6 +16,7 @@ export type ParsedChunkAction =
   | { action: 'metadata'; modelDisplayName: string; modelName: string; providerName: string; contextWindow: number }
   | { action: 'text'; text: string }
   | { action: 'thinking'; text: string }
+  | { action: 'guide'; text: string }
   | { action: 'tool_execution'; segment: ToolExecutionSegment }
   | { action: 'approval_request'; requestId: string; command: string; explanation?: string; approvalType: string }
   | { action: 'approval_batch'; requestId: string; approvalType: string; toolCalls: PendingToolCallData[] }

package/src/components/chat/utils/chunk-parser.ts

@@ -65,6 +65,12 @@ export function parseChunkToAction(chunk: unknown): ParsedChunkAction | null {
       }
       return null
 
+    case MESSAGE_TYPE.GUIDE:
+      if (typeof data.text === 'string') {
+        return { action: 'guide', text: data.text }
+      }
+      return null
+
     case MESSAGE_TYPE.EXECUTING_TOOL:
       return {
         action: 'tool_execution',

package/src/components/chat/utils/message-segment-accumulator.ts

@@ -139,6 +139,22 @@ export class MessageSegmentAccumulator {
     return this.getSegments()
   }
 
+  /**
+   * Append guide text to the current message.
+   * If the last segment is guide, append to it; otherwise start a new guide segment.
+   */
+  appendGuide(text: string): MessageSegment[] {
+    const lastSegment = this.segments[this.segments.length - 1]
+
+    if (lastSegment && lastSegment.type === 'guide') {
+      this.segments[this.segments.length - 1] = { type: 'guide', text: lastSegment.text + text }
+    } else {
+      this.segments.push({ type: 'guide', text })
+    }
+
+    return this.getSegments()
+  }
+
   /**
    * Add a tool execution segment.
    *
@@ -516,6 +532,9 @@ export class MessageSegmentAccumulator {
         case 'thinking':
           if (segment.text) this.appendThinking(segment.text)
           break
+        case 'guide':
+          if (segment.text) this.appendGuide(segment.text)
+          break
         case 'tool_execution':
           this.addToolExecution(segment)
           break

package/src/components/chat/utils/process-historical-messages.ts

@@ -275,6 +275,12 @@ function processMessageData(
       }
       break
 
+    case MESSAGE_TYPE.GUIDE:
+      if ('text' in data && data.text) {
+        accumulator.appendGuide(data.text)
+      }
+      break
+
     case MESSAGE_TYPE.EXECUTING_TOOL:
       if ('integratedToolType' in data) {
         accumulator.addToolExecution({

package/src/components/features/select-button.tsx

@@ -36,9 +36,12 @@ export const SelectButton = React.forwardRef<HTMLButtonElement, SelectButtonProp
           "font-body text-left w-full",
           "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-focus",
           "disabled:pointer-events-none disabled:opacity-50",
+          // Hover / active move the BACKGROUND only, like Input — the accent
+          // border is reserved for the selected state, so an unselected button
+          // no longer flashes "selected" under the cursor.
           selected
             ? "bg-ods-open-yellow-light border-ods-accent hover:bg-ods-open-yellow-light-hover active:bg-ods-open-yellow-light-action"
-            : "bg-ods-card border-ods-border hover:bg-ods-bg-hover hover:border-ods-accent active:bg-ods-bg-active active:border-ods-accent",
+            : "bg-ods-card border-ods-border hover:bg-ods-bg-hover active:bg-ods-bg-active",
           className,
         )}
       >

package/src/components/layout/page-layout.tsx

@@ -36,6 +36,12 @@
  * `titleWrap` prop, forwarded to `TitleBlock`. Defaults to `false` (frozen
  * single-line truncate). Content detail pages with CMS titles pass it to let
  * long titles wrap instead of ellipsis-clip. Additive + default-preserving.
+ *
+ * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): the OPTIONAL
+ * `subtitleRow` prop, forwarded to `TitleBlock`. Defaults to `'when-set'` (the
+ * subtitle row renders only when there is text for it). Pages whose subtitle is
+ * optional record data use it to choose how the row behaves while loading.
+ * Additive + default-preserving.
  * ========================================================================== */
 
 import React from 'react'
@@ -68,6 +74,12 @@ export interface PageLayoutProps {
   /** When true, the title/subtitle render as line-box-accurate skeleton bars (forwarded to
    *  `TitleBlock`). Header height stays identical to the loaded state — for page skeletons. */
   loading?: boolean
+  /** Render the header ACTIONS as placeholders (their set depends on data still loading). */
+  loadingActions?: boolean
+  /** When the subtitle row occupies the layout (forwarded to `TitleBlock`):
+   *  `'when-set'` (default), `'while-loading'` (skeleton bar while loading, collapses
+   *  if the record has no subtitle), or `'always'` (never collapses). */
+  subtitleRow?: 'when-set' | 'while-loading' | 'always'
   /** When true, a long title wraps onto multiple lines instead of the frozen single-line
    *  ellipsis clamp (forwarded to `TitleBlock`). For content detail pages whose h1 is CMS
    *  data of arbitrary length. Additive + default-preserving. */
@@ -96,6 +108,8 @@ export function PageLayout({
   titleSize,
   titleAdornment,
   loading,
+  loadingActions,
+  subtitleRow,
   titleWrap,
 }: PageLayoutProps) {
   const hasActions = actions && actions.length > 0
@@ -118,6 +132,8 @@ export function PageLayout({
           titleSize={titleSize}
           titleAdornment={titleAdornment}
           loading={loading}
+          loadingActions={loadingActions}
+          subtitleRow={subtitleRow}
           titleWrap={titleWrap}
         />
       )}

package/src/components/layout/title-block.tsx

@@ -40,6 +40,14 @@
  * byte-identical. Do NOT change defaults or touch anything else here.
  *
  * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): the OPTIONAL
+ * `subtitleRow` prop. Defaults to `'when-set'` — the subtitle row keeps
+ * rendering only when `subtitle` is truthy, so every existing caller is
+ * byte-identical. The other two values decide how a page trades a header that
+ * never moves against a header that never shows an empty line; see the prop's
+ * own doc for which to pick. Additive + default-preserving; do NOT change the
+ * default.
+ *
+ * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): the OPTIONAL
  * `titleWrap` prop. Defaults to `false` — the frozen single-line `truncate`
  * baseline is unchanged for every existing caller. Content DETAIL pages (whose
  * h1 is CMS data of arbitrary length — releases, legal docs, FAQ docs, dev
@@ -58,12 +66,27 @@
  * so its natural width drives the wrap while `truncate` still clamps a title
  * that alone exceeds the container. The mobile (base) layout is untouched.
  * This is the new frozen baseline; do NOT re-introduce breakpoint stacking.
+ *
+ * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): overflow tooltips on
+ * the title and subtitle. This one CHANGES the baseline for every caller: the
+ * native `title=""` attribute on both is replaced by the ODS `FloatingTooltip`,
+ * armed only when the text is genuinely clipped (`useIsTruncated`). Both stay
+ * single-line — that is the design, and the tooltip is what makes a clipped
+ * title readable instead of merely pretty. Nothing is lost for assistive tech:
+ * `text-overflow: ellipsis` never hid the text from the accessibility tree, so
+ * the full string was always exposed; the attribute only ever served a mouse.
+ * The wrapper `div` the tooltip needs goes OUTSIDE the `h1`/`p` — never inside:
+ * a `div` inside a `p` is auto-closed by the HTML parser, which would split the
+ * subtitle paragraph and desync hydration. The `titleWrap` branch is untouched
+ * (wrapped text never clips, so it never needs a tooltip).
  * ========================================================================== */
 
 import React from 'react'
+import { useIsTruncated } from '../../hooks/ui/use-is-truncated'
 import { cn } from '../../utils/cn'
 import type { ActionsMenuGroup } from '../ui/actions-menu'
 import { EntityImage } from '../ui/entity-image'
+import { FloatingTooltip } from '../ui/floating-tooltip'
 import { PageActions, type PageActionButton } from '../ui/page-actions'
 import { BackButton } from './back-button'
 
@@ -106,6 +129,28 @@ export interface TitleBlockProps {
    *  (typography + surrounding markup unchanged, so header height is identical to loaded).
    *  Additive + default-preserving: omit it and every existing caller is byte-identical. */
   loading?: boolean
+  /**
+   * Render the ACTIONS as placeholders too. Separate from `loading` on purpose:
+   * a page whose action set is already final (it depends on the route, not on
+   * the record) keeps showing its real buttons while the title loads.
+   */
+  loadingActions?: boolean
+  /**
+   * When the subtitle row occupies the layout. The subtitle is often optional
+   * RECORD data — unknown while loading, sometimes absent afterwards — and there
+   * is no setting that both fills the loading header and never leaves a blank
+   * line, so the caller picks which one matters.
+   *
+   * - `'when-set'` (default) — only when `subtitle` has text.
+   * - `'while-loading'` — also during `loading`, as a skeleton bar. The header
+   *   looks complete while it loads, and the row collapses if the record turns
+   *   out to have no subtitle (so that case settles one line shorter).
+   * - `'always'` — the row never collapses; an empty subtitle holds its line
+   *   with an invisible spacer. The header cannot change height. Use it when the
+   *   loaded page ALWAYS has a subtitle — typically a standalone skeleton
+   *   component matching a page whose subtitle is guaranteed.
+   */
+  subtitleRow?: 'when-set' | 'while-loading' | 'always'
   /** When true, a long title WRAPS onto multiple lines instead of the frozen single-line
    *  ellipsis clamp. For content detail pages whose h1 is CMS data of arbitrary length.
    *  Additive + default-preserving: omit it and every existing caller is byte-identical. */
@@ -129,6 +174,22 @@ function TitleTextSkeleton({ widthClass, heightClass }: { widthClass: string; he
   )
 }
 
+/**
+ * Bar geometry per title size, following the ODS type scale across breakpoints
+ * (`md` = 800px, `lg` = 1280px here — the SAME widths the typography tokens
+ * switch at, so bar and text step together).
+ *
+ * `h2` needs no `lg` step because `text-h2` has none: it is 24/32 on mobile and
+ * 32/40 from tablet up. `text-h1` scales at both breakpoints (40 → 48 → 56), so
+ * its bar does too — reusing the h2 bar there would leave a stamp-sized smudge
+ * inside a 64px line. Heights stay well under the line box's ascent on purpose;
+ * see `TitleTextSkeleton` for why that is what keeps the header height honest.
+ */
+const TITLE_SKELETON_SIZE = {
+  h1: { width: 'w-56 md:w-80 lg:w-96', height: 'h-7 md:h-8 lg:h-9' },
+  h2: { width: 'w-48 md:w-72', height: 'h-4 md:h-6' },
+} as const
+
 export function TitleBlock({
   title,
   subtitle,
@@ -143,14 +204,28 @@ export function TitleBlock({
   titleSize = 'h2',
   titleAdornment,
   loading,
+  loadingActions,
+  subtitleRow = 'when-set',
   titleWrap = false,
 }: TitleBlockProps) {
+  const hasSubtitleRow =
+    !!subtitle || subtitleRow === 'always' || (subtitleRow === 'while-loading' && !!loading)
   const hasActions = actions && actions.length > 0
   const hasMenuActions = !!menuActions && menuActions.some(g => g.items.length > 0)
   const titleClass = titleSize === 'h1' ? 'text-h1' : 'text-h2'
   // Frozen baseline is the single-line `truncate`; `titleWrap` swaps it for
   // multi-line wrapping (break-words guards pathological unbroken tokens).
   const titleOverflowClass = titleWrap ? 'break-words' : 'truncate'
+  const skeletonSize = TITLE_SKELETON_SIZE[titleSize]
+
+  // Exactly one title element renders per pass, so one ref covers every branch.
+  // The tooltip arms itself only on real clipping — repeating a fully visible
+  // title back to the user is noise, and `titleWrap`/loading never clip at all.
+  const { ref: titleRef, isTruncated: titleTruncated } = useIsTruncated<HTMLHeadingElement>(loading ? null : title)
+  const { ref: subtitleRef, isTruncated: subtitleTruncated } = useIsTruncated<HTMLParagraphElement>(
+    loading ? null : subtitle,
+  )
+  const titleNode = loading ? <TitleTextSkeleton widthClass={skeletonSize.width} heightClass={skeletonSize.height} /> : title
 
   return (
     <div
@@ -183,7 +258,7 @@ export function TitleBlock({
             className="hidden md:inline-flex"
           />
         )}
-        {(image || subtitle || loading) ? (
+        {(image || hasSubtitleRow || loading) ? (
           <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
             {image && (
               <EntityImage
@@ -196,15 +271,32 @@ export function TitleBlock({
               {(loading || title) && (
                 titleAdornment ? (
                   <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
-                    <h1 className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)} title={title}>{loading ? <TitleTextSkeleton widthClass="w-48 md:w-72" heightClass="h-4 md:h-6" /> : title}</h1>
+                    {/* `min-w-0` moves onto the tooltip's wrapper: the wrapper is
+                        now the flex item, and without it the row refuses to
+                        shrink and pushes the adornment out. */}
+                    <FloatingTooltip content={title} side="bottom" disabled={!titleTruncated} triggerClassName="min-w-0">
+                      <h1 ref={titleRef} className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)}>{titleNode}</h1>
+                    </FloatingTooltip>
                     <span className="shrink-0">{titleAdornment}</span>
                   </div>
                 ) : (
-                  <h1 className={cn(titleClass, 'text-ods-text-primary', titleOverflowClass)} title={title}>{loading ? <TitleTextSkeleton widthClass="w-48 md:w-72" heightClass="h-4 md:h-6" /> : title}</h1>
+                  <FloatingTooltip content={title} side="bottom" disabled={!titleTruncated}>
+                    <h1 ref={titleRef} className={cn(titleClass, 'text-ods-text-primary', titleOverflowClass)}>{titleNode}</h1>
+                  </FloatingTooltip>
                 )
               )}
-              {subtitle && (
-                <p className="text-h6 text-ods-text-secondary truncate" title={subtitle}>{loading ? <TitleTextSkeleton widthClass="w-28 md:w-36" heightClass="h-2.5 md:h-3" /> : subtitle}</p>
+              {hasSubtitleRow && (
+                /* The NBSP is a pure spacer, reached only in `'always'` mode: an
+                   empty `p` collapses to zero height (its only content would be
+                   collapsible whitespace), which is exactly the shift that mode
+                   exists to prevent. Hidden from AT — it carries no meaning. */
+                <FloatingTooltip content={subtitle} side="bottom" disabled={!subtitleTruncated}>
+                  <p
+                    ref={subtitleRef}
+                    className="text-h6 text-ods-text-secondary truncate"
+                    aria-hidden={!loading && !subtitle ? true : undefined}
+                  >{loading ? <TitleTextSkeleton widthClass="w-28 md:w-36" heightClass="h-2.5 md:h-3" /> : (subtitle || '\u00A0')}</p>
+                </FloatingTooltip>
               )}
             </div>
           </div>
@@ -212,7 +304,9 @@ export function TitleBlock({
           title && (
             titleAdornment ? (
               <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
-                <h1 className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)} title={title}>{title}</h1>
+                <FloatingTooltip content={title} side="bottom" disabled={!titleTruncated} triggerClassName="min-w-0">
+                  <h1 ref={titleRef} className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)}>{title}</h1>
+                </FloatingTooltip>
                 <span className="shrink-0">{titleAdornment}</span>
               </div>
             ) : (
@@ -226,13 +320,18 @@ export function TitleBlock({
         )}
       </div>
 
-      {(hasActions || hasMenuActions || selector) && (
+      {/* `loadingActions` opens this gate on its own: the case the flag exists for
+          is a page that does not YET know its action set, which is exactly the
+          page that passes `actions={[]}` — gating on `hasActions` alone would
+          render nothing and then pop the real buttons in. */}
+      {(hasActions || hasMenuActions || selector || loadingActions) && (
         <div className="flex gap-2 items-center shrink-0">
           <PageActions
             variant={actionsVariant}
             actions={actions ?? []}
             menuActions={menuActions}
             selector={selector}
+            loading={loadingActions}
           />
         </div>
       )}