@flamingo-stack/openframe-frontend-core 0.0.847 → 0.0.849

package/dist/utils/source-grouping.d.ts

@@ -24,13 +24,13 @@
 import type { ChatSource } from '../components/chat/types/message.types';
 /**
  * Doc-table documentTypes: whole documents with their own viewer (markdown =
- * product docs, data_room_doc = data room). They carry an in-app `path` (handed
+ * product docs, data_room_doc = data room, policy_doc = company policies). They carry an in-app `path` (handed
  * to the host's composer as the slug), and a server never folds them
  * into one citation (`groupsByTable`); the strip still draws them as one chip
  * per table. The hub's per-source contract test pins this list to its
  * doc-table configs.
  */
-export declare const DOC_TABLE_TYPES: readonly ["markdown", "data_room_doc"];
+export declare const DOC_TABLE_TYPES: readonly ["markdown", "data_room_doc", "policy_doc"];
 /**
  * Which tables a SERVER folds into one citation: rows of a knowledge table
  * share one number (and reach the model as one table) unless they are whole

package/dist/utils/source-grouping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-grouping.d.ts","sourceRoot":"","sources":["../../src/utils/source-grouping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAGzE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,wCAAyC,CAAC;AAEtE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,KAAK,WAAW,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;2EAC2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GAAG,UAAU,CAcb;AA0DD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAqCvE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAU/D"}
+{"version":3,"file":"source-grouping.d.ts","sourceRoot":"","sources":["../../src/utils/source-grouping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAGzE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,sDAAuD,CAAC;AAEpF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,KAAK,WAAW,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;2EAC2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GAAG,UAAU,CAcb;AA0DD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAqCvE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAU/D"}

package/dist/utils/source-grouping.js

@@ -1,5 +1,5 @@
 import { defaultDocumentTypeForTableId, getSourceLabel } from "./source-icons.js";
-const DOC_TABLE_TYPES = ["markdown", "data_room_doc"];
+const DOC_TABLE_TYPES = ["markdown", "data_room_doc", "policy_doc"];
 function groupsByTable(documentType) {
   return !DOC_TABLE_TYPES.includes(documentType ?? "");
 }

package/dist/utils/source-icons.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-icons.d.ts","sourceRoot":"","sources":["../../src/utils/source-icons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqFpD,CAAC;AAEF;;6DAE6D;AAC7D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4EzD,CAAC;AAEF;;kEAEkE;AAClE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsEpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5E"}
+{"version":3,"file":"source-icons.d.ts","sourceRoot":"","sources":["../../src/utils/source-icons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsFpD,CAAC;AAEF;;6DAE6D;AAC7D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA6EzD,CAAC;AAEF;;kEAEkE;AAClE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuEpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5E"}

package/dist/utils/source-icons.js

@@ -2,6 +2,7 @@ const SOURCE_ICON_NAMES = {
   // Doc tables
   "openframe-docs": "openframe",
   "data-room-docs": "shield",
+  "company-policies": "book-open",
   // CMS / programs
   "blog-posts": "newspaper",
   "product-releases": "rocket",
@@ -81,6 +82,7 @@ const SOURCE_LABELS_BY_TABLE = {
   // Doc tables
   "openframe-docs": "OpenFrame Docs",
   "data-room-docs": "Data Room",
+  "company-policies": "Company Policies",
   // CMS / programs
   "blog-posts": "Blog Posts",
   "product-releases": "Product Releases",
@@ -151,6 +153,7 @@ const DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID = {
   // Doc tables
   markdown: "openframe-docs",
   data_room_doc: "data-room-docs",
+  policy_doc: "company-policies",
   // CMS / programs
   blog_post: "blog-posts",
   product_release: "product-releases",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.847",
+  "version": "0.0.849",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "sideEffects": [

package/src/components/chat/chat-composer.tsx

@@ -14,6 +14,13 @@ import { ModelDisplay } from './model-display';
 import type { ChatInputRef, ModelDisplayProps } from './types/component.types';
 import type { ChatContextItem, ChatContextPickerConfig } from './types/context-item.types';
 
+/**
+ * The top strip's corners: the card's radius (`rounded-md`, `--radius` - 2px) less the card's 1px border, so the strip
+ * meets the border's inner curve. At the card's own radius it sits 1px inside that curve and leaves a sliver of the
+ * card's fill at each corner. The card cannot clip it instead: the picker and the memory popover float out of it.
+ */
+const TOP_STRIP_ROUNDING_CLASS = 'rounded-t-[calc(var(--radius)_-_3px)]';
+
 /** Why the composer takes no input, in the user's words — shown where the prompt would be. */
 export interface ChatComposerLock {
   placeholder: string;
@@ -248,7 +255,7 @@ export function ChatComposer({
     // `border-b`) stack flush above the input; the card owns the border
     // / radius / focus ring. No `overflow-hidden` so the picker and the
     // memory popover can float above the input (whichever strip comes
-    // first gets `rounded-t`).
+    // first gets `TOP_STRIP_ROUNDING_CLASS`).
     // `has-[[data-editor]:focus]` (not `focus-within`) so the accent
     // border reacts ONLY to the composer editor — not the picker's search
     // input or item buttons, which also live inside this card. The editor
@@ -264,7 +271,7 @@ export function ChatComposer({
         resolveIcon={resolveContextIcon}
         disabled={sending || locked}
         leading={contextLeading}
-        className="rounded-t-md"
+        className={TOP_STRIP_ROUNDING_CLASS}
       />
       {selected.length > 0 && (
         <ChatContextChipStrip
@@ -275,7 +282,7 @@ export function ChatComposer({
           className={cn(
             'border-b border-ods-border bg-ods-bg p-2',
             // Only the TOP strip rounds into the card corner.
-            memory.length === 0 && !contextLeading && 'rounded-t-md',
+            memory.length === 0 && !contextLeading && TOP_STRIP_ROUNDING_CLASS,
           )}
         />
       )}

package/src/components/chat/chat-container.tsx

@@ -111,7 +111,9 @@ const ChatHeader = forwardRef<HTMLDivElement, ChatHeaderProps>(
             className={cn(cardClasses, 'absolute right-full top-0 mr-[var(--spacing-system-s)] hover:bg-ods-bg-hover')}
           />
         )}
-        <div className={cardClasses}>
+        {/* The card clips its content at the border's inner curve, so a filled section at its edge (the MSP card)
+            meets the border; nothing in it floats out. */}
+        <div className={cn(cardClasses, !bare && 'overflow-hidden')}>
           <div className="flex items-center justify-between gap-4 px-4 py-3">
             <div className="flex items-center gap-3">
               {userIcon && !isLoading ? (
@@ -176,8 +178,8 @@ const ChatHeader = forwardRef<HTMLDivElement, ChatHeaderProps>(
           </div>
           {/* MSP branding slot — home-screen only; `ticketInfo` (open chat)
               claims this space, so it wins when both are provided. The card
-              already draws the chrome: strip the section's own ring and keep
-              only the bottom rounding so its bg fits the card corners. */}
+              already draws the chrome and clips its corners: strip the
+              section's own ring and rounding. */}
           {!ticketInfo && (mspLoading || mspOrganization) && (
             <>
               <div className="h-px bg-ods-border" />
@@ -185,7 +187,7 @@ const ChatHeader = forwardRef<HTMLDivElement, ChatHeaderProps>(
                 name=""
                 {...mspOrganization}
                 loading={mspLoading || !mspOrganization}
-                className={cn('rounded-none ring-0', !bare && 'rounded-b-md', mspOrganization?.className)}
+                className={cn('rounded-none ring-0', mspOrganization?.className)}
               />
             </>
           )}

package/src/components/chat/entity-cards/design-doc-card.tsx

@@ -3,7 +3,7 @@
 /**
  * DesignDocCard (pure presentation) — a design doc as the entity card every surface shows it with: the full card
  * (`default`, the `RoadmapCard` layout without its image slot, since a doc has no image of its own and a constant glyph
- * says nothing: title, DRI and date, readiness (the hub's own wording, `design-doc-readiness`), summary, sign-off caption and the people) for admin surfaces, and the chat's compact card (`DesignDocChatCard` in `dispatch.tsx`, which reads
+ * says nothing: title, DRI and date, its status (the status a person set, else its readiness: the hub's own wording, `design-doc-readiness`), summary, sign-off caption and the people) for admin surfaces, and the chat's compact card (`DesignDocChatCard` in `dispatch.tsx`, which reads
  * the same readiness and meta). The card writes no click logic beyond its `href` anchor.
  */
 
@@ -12,14 +12,11 @@ import { TEXT_LINES_MIN } from '../../../styles/component-sizes';
 import type { DesignDoc } from '../../../types/design-doc';
 import { cn } from '../../../utils/cn';
 import { formatDateShort } from '../../../utils/date-formatters';
-import {
-  DESIGN_DOC_READINESS_DISPLAY,
-  designDocReadiness,
-  formatCompletionLabelWithBlockers,
-} from '../../../utils/design-doc-readiness';
+import { designDocStatusDisplay, formatCompletionLabelWithBlockers } from '../../../utils/design-doc-readiness';
 import { TextLineSkeleton } from '../../loading/unified-skeleton';
 import { AvatarStack, type AvatarStackPerson } from '../../ui/avatar-stack';
 import { useLoadingScope } from '../../ui/loading-scope';
+import { PaletteBadge } from '../../ui/palette-badge';
 import { StatusBadge } from '../../ui/status-badge';
 import { safeHref } from '../utils/compact-card-classes';
 import { CONTENT_CARD_FRAME_CLASS, CONTENT_CARD_SKELETON_FRAME_CLASS } from './content-card-frame';
@@ -102,7 +99,7 @@ function DesignDocCardSkeleton({ className }: { className?: string } = {}) {
 }
 
 export function DesignDocCard({ doc, href, target, rel, className }: DesignDocCardProps) {
-  const readiness = DESIGN_DOC_READINESS_DISPLAY[designDocReadiness(doc.completion)];
+  const status = designDocStatusDisplay(doc);
   const people = designDocPeople(doc);
   const link = safeHref(href ?? null);
   if (useLoadingScope()) return <DesignDocCardSkeleton className={className} />;
@@ -117,17 +114,15 @@ export function DesignDocCard({ doc, href, target, rel, className }: DesignDocCa
             <p className="truncate text-ods-text-secondary text-h5">{designDocMetaLine(doc)}</p>
           </div>
         </div>
-        <StatusBadge
-          text={readiness.label}
-          colorScheme={readiness.scheme}
-          variant="button"
-          singleLine
-          className="hidden md:inline-flex"
-        />
-      </div>
-      <div className="md:hidden">
-        <StatusBadge text={readiness.label} colorScheme={readiness.scheme} variant="button" singleLine />
+        {status ? (
+          <PaletteBadge text={status.label} color={status.color_scheme} className="hidden md:inline-flex" />
+        ) : null}
       </div>
+      {status ? (
+        <div className="md:hidden">
+          <PaletteBadge text={status.label} color={status.color_scheme} />
+        </div>
+      ) : null}
       <div className={DESIGN_DOC_CARD_SUMMARY_ROW}>
         <p className="line-clamp-3 text-ods-text-secondary text-h4">{doc.summary || ''}</p>
       </div>

package/src/components/chat/entity-cards/dispatch.tsx

@@ -48,11 +48,7 @@ import {
 } from '../../../types/trust-center';
 import { isAppOriginUrl } from '../../../utils/app-origins';
 import { formatDateShort } from '../../../utils/date-formatters';
-import {
-  DESIGN_DOC_READINESS_DISPLAY,
-  designDocReadiness,
-  formatCompletionLabel,
-} from '../../../utils/design-doc-readiness';
+import { designDocStatusDisplay, formatCompletionLabel } from '../../../utils/design-doc-readiness';
 import { faqItemAnchor } from '../../../utils/faq-anchor';
 import { formatDateUTC as formatDate } from '../../../utils/format';
 import { programMetaFormatters, programMetaLine } from '../../../utils/program-instant';
@@ -88,6 +84,7 @@ import type { LoadedProductReleaseCardProps } from '../../shared/product-release
 import { ProductReleaseCard } from '../../shared/product-release/product-release-card';
 import type { ActionsMenuGroup } from '../../ui/actions-menu';
 import { ExternalMediaNotice } from '../../ui/markdown/external-media-notice';
+import { tagVariantForBadgeColor } from '../../ui/tag';
 import { VendorIcon } from '../../vendor-icon';
 import { useChatPanel } from '../chat-panel-context';
 import type { ChatRef } from '../chat-ref.types';
@@ -1046,8 +1043,8 @@ function CustomerInterviewChatCard({
 }
 
 /**
- * Design doc → the doc glyph, its readiness as the pill (the hub's own wording: "Ready to build" / "Not ready",
- * `design-doc-readiness`) and "DRI · updated · n/m reviews signed off" under the title. The hub's card route attaches the doc's list row as
+ * Design doc → the doc glyph, its status as the pill (the status a person set, else its readiness, both vocabulary rows the hub resolves onto the
+ * doc: `designDocStatusDisplay`) and "DRI · updated · n/m signed off" under the title. The hub's card route attaches the doc's list row as
  * `item.doc`; a row without it (an older hub) renders the ref's own title and preview.
  */
 function DesignDocChatCard({
@@ -1063,7 +1060,7 @@ function DesignDocChatCard({
 }) {
   const displayRef = fetchedItemDisplayRef(item, chatRef);
   const doc = item?.doc;
-  const readiness = doc ? DESIGN_DOC_READINESS_DISPLAY[designDocReadiness(doc.completion)] : null;
+  const status = doc ? designDocStatusDisplay(doc) : null;
   return (
     <MingoInfoCard
       title={doc?.title ?? displayRef.title}
@@ -1074,8 +1071,8 @@ function DesignDocChatCard({
       }
       icon={<FileContentIcon size={24} />}
       status={
-        readiness
-          ? { label: readiness.label, variant: readiness.scheme === 'success' ? 'success' : 'grey' }
+        status
+          ? { label: status.label, variant: tagVariantForBadgeColor(status.color_scheme) }
           : { label: 'Design doc', variant: 'grey' }
       }
       anchorProps={buildAnchorProps(displayRef.url, isNewTab, displayRef.targetPlatform)}
@@ -1738,6 +1735,9 @@ export const CHAT_CARD_REGISTRY: Record<string, ChatCardRegistryEntry> = {
   data_room_doc: refHydratedEntry('data_room_doc', 'Data-room doc', (displayRef, opts) => (
     <DataRoomDocChatCard chatRef={displayRef} isNewTab={opts.isNewTab} discuss={opts.discuss} />
   )),
+  policy_doc: refHydratedEntry('policy_doc', 'Company policy', (displayRef, opts) => (
+    <DataRoomDocChatCard chatRef={displayRef} isNewTab={opts.isNewTab} discuss={opts.discuss} />
+  )),
   markdown: refHydratedEntry('markdown', 'Doc page (markdown)', (displayRef, opts) => (
     <DataRoomDocChatCard chatRef={displayRef} isNewTab={opts.isNewTab} discuss={opts.discuss} />
   )),

package/src/components/docs/doc-viewer.tsx

@@ -4,15 +4,15 @@ import type React from 'react';
 import { useMemo } from 'react';
 import { useRouter } from '../../embed-shims/next-navigation';
 import type { DocContent, DocNode, DocRenderHandlers, DocSourceId } from '../../types/doc-source';
-import { findDocNodeByPath } from '../../utils/doc-tree-nav';
+import { findDocNodeByPath, rootDocumentPath } from '../../utils/doc-tree-nav';
 import { PageShell } from '../layout/article-detail-layout';
 import { PageLayout } from '../layout/page-layout';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { MultiLevelNavigation, MobileNavigationDropdown } from '../navigation/multi-level-navigation';
 import { StickySectionNav } from '../navigation/sticky-section-nav';
 import { PersistentSidebar, PersistentMobileDropdown } from '../persistent-filter-controls';
 import { DocSearchBar, useDocSearch } from '../shared/doc-search';
 import { DataSyncLine } from '../ui/data-attribution';
+import { LoadingScope } from '../ui/loading-scope';
 import { useDocNavigation } from './doc-navigation-context';
 import { useDocsResolveLink } from './use-docs-resolve-link';
 import { useDocumentTree } from './use-document-tree';
@@ -46,13 +46,6 @@ export interface DocViewerProps {
    */
   renderContent: (content: DocContent, handlers: DocRenderHandlers) => React.ReactNode;
 
-  /**
-   * Render the loading skeleton. Receives the selected node's `documentType`
-   * (undefined while structure is still loading) so the caller can return a
-   * markdown-shaped skeleton vs an embed-shaped skeleton.
-   */
-  renderSkeleton: (documentType: DocNode['documentType']) => React.ReactNode;
-
   /**
    * Chat-source identifier — passed in by the page shell from server-side
    * `currentPlatform()`. Lib has no platform context; the page shell is the
@@ -88,6 +81,13 @@ export interface DocViewerProps {
   /** Initial doc path (URL `[...path]`). */
   docPath?: string;
 
+  /**
+   * The type of the document at `docPath`, when the page knows it before the tree is read (the host read it on the
+   * server). The content's loading state takes its shape from it on a page's first load (a Figma deck draws the embed
+   * skeleton, not a text page); once the tree is read, the selected node's own type decides.
+   */
+  initialDocumentType?: DocNode['documentType'];
+
   /** Sidebar header copy (`'DOCUMENTATION'`, `'DATA ROOM'`). */
   sidebarLabel?: string;
 
@@ -113,7 +113,7 @@ export interface DocViewerProps {
   /** Base route path for URL navigation. */
   baseRoute: string;
 
-  /** Empty state copy when no doc is selected. */
+  /** What the viewer says when the source holds no documents yet (default "No documents yet."). */
   emptyStateText?: string;
 
   /** Whether to render the doc-search bar (bound to chat). */
@@ -141,12 +141,13 @@ export function DocViewer(props: DocViewerProps) {
 
 /** The "On this page" column's heading: static copy, drawn for real loaded and loading. */
 const ON_THIS_PAGE_LABEL = 'ON THIS PAGE';
+/** The loading section list's click handler: it has no sections to click. */
+const NO_SECTION_CLICK = () => {};
 const ON_THIS_PAGE_HEADING_CLASS = 'mb-4 font-semibold text-ods-text-secondary text-h5';
 
 function DocViewerContent({
   sourceId,
   renderContent,
-  renderSkeleton,
   chatSource,
   title,
   subtitle,
@@ -154,6 +155,7 @@ function DocViewerContent({
   className = '',
   shell = true,
   docPath,
+  initialDocumentType,
   sidebarLabel = 'DOCUMENTATION',
   structureEndpoint,
   contentEndpoint,
@@ -246,11 +248,31 @@ function DocViewerContent({
   //   - the article max-width + sticky-nav visibility (markdown only)
   // `undefined` documentType is treated as `'markdown'` (per the DocNode
   // discriminator's documented default).
+  // Before the tree is read, the host's `initialDocumentType` (the page's own document) stands in. Once it is read, the
+  // root takes the type of the document it shows (`rootDocumentPath`), so a root Figma or PDF never flips to the text
+  // layout between the tree arriving and the document arriving.
+  const selectedNodePath =
+    structure.length > 0 && !selectedPath ? rootDocumentPath(structure, folderIndexFile) : selectedPath;
   const selectedNodeDocType =
-    selectedPath && structure.length > 0 ? findDocNodeByPath(selectedPath, structure)?.documentType : undefined;
-  // During loading, the in-flight content's type isn't known yet — fall back
-  // to the selected node's type (or markdown if neither is set).
-  const activeDocType = content?.documentType ?? selectedNodeDocType;
+    structure.length > 0
+      ? selectedNodePath
+        ? findDocNodeByPath(selectedNodePath, structure)?.documentType
+        : undefined
+      : initialDocumentType;
+  // While a document loads, `content` is still the PREVIOUS document's: the layout (the "On this page" column, the
+  // article width) follows the document being opened, never the one being left, or opening a Figma deck from a text
+  // page draws the text page's column beside the deck's skeleton. Loaded, the content's own type decides.
+  const isLoadingDocument = isLoadingContent || isLoadingStructure;
+  // While a document loads: its renderer with an EMPTY document of its type (the selected node's, or the host's
+  // `initialDocumentType` before the tree is read), drawn in a loading scope, so every renderer shows its own loading
+  // form.
+  const loadingContent = isLoadingDocument
+    ? renderContent(
+        { content: '', sections: [], path: selectedPath ?? '', documentType: selectedNodeDocType },
+        { onInternalLinkClick: navigateToDoc, currentPath: selectedPath ?? '', sourceId },
+      )
+    : null;
+  const activeDocType = isLoadingDocument ? selectedNodeDocType : (content?.documentType ?? selectedNodeDocType);
   const isMarkdownContent = !activeDocType || activeDocType === 'markdown';
   const showStickyNav = isMarkdownContent;
 
@@ -266,11 +288,10 @@ function DocViewerContent({
   const containerBgStyle =
     colorPalette.containerBackground !== 'transparent' ? { backgroundColor: colorPalette.containerBackground } : {};
 
-  const defaultEmptyText =
-    structure.length > 0
-      ? 'Select a document from the sidebar to view'
-      : 'No documents yet. Add content from the admin panel.';
-  const resolvedEmptyText = emptyStateText || defaultEmptyText;
+  // A source with documents and none open asks for one; an empty source says so in the host's words (a reader may
+  // not be the one who adds documents, so the default names no admin screen).
+  const resolvedEmptyText =
+    structure.length > 0 ? 'Select a document from the sidebar to view' : emptyStateText || 'No documents yet.';
 
   // Unified header: title/subtitle route through the canonical (frozen)
   // `PageLayout` `TitleBlock` (text-h2) — same as every other help-center page —
@@ -365,8 +386,10 @@ function DocViewerContent({
                       (app-globals.css) so content wraps instead of overflowing. */}
                   <div className={`w-full min-w-0 ${isMarkdownContent ? 'mx-auto max-w-4xl' : ''}`}>
                     <article className="space-y-2">
-                      {isLoadingContent || isLoadingStructure ? (
-                        renderSkeleton(selectedNodeDocType)
+                      {isLoadingDocument ? (
+                        // The document being opened draws its own loading form: its renderer, in a loading scope,
+                        // with an empty document of its type (no words, no address), never a skeleton picked here.
+                        <LoadingScope>{loadingContent}</LoadingScope>
                       ) : !content ? (
                         <div className="py-16 text-center">
                           <p className="text-ods-text-secondary text-h4">{resolvedEmptyText}</p>
@@ -377,22 +400,20 @@ function DocViewerContent({
                     </article>
                   </div>
 
-                  {isMarkdownContent && (isLoadingContent || isLoadingStructure) && (
+                  {isMarkdownContent && isLoadingDocument && (
                     <div className="hidden content-lg:block">
                       <div className="sticky top-24">
                         <h3 className={ON_THIS_PAGE_HEADING_CLASS}>{ON_THIS_PAGE_LABEL}</h3>
-                        <div className="space-y-0">
-                          {[130, 170, 190, 220, 110, 200, 80, 100, 120, 140, 90].map((w, i) => (
-                            <div
-                              key={i}
-                              className={`border-l-2 py-[13px] pl-3 ${
-                                i === 0 ? 'border-ods-accent' : 'border-transparent'
-                              }`}
-                            >
-                              <UnifiedSkeleton className="h-[13px] rounded" width={w} />
-                            </div>
-                          ))}
-                        </div>
+                        {/* The section list's own loading form (`StickySectionNav` with no sections, in a scope). */}
+                        <LoadingScope>
+                          <StickySectionNav
+                            sections={[]}
+                            activeSection=""
+                            onSectionClick={NO_SECTION_CLICK}
+                            ribbonPosition="left"
+                            ribbonColor="var(--ods-accent)"
+                          />
+                        </LoadingScope>
                       </div>
                     </div>
                   )}

package/src/components/docs/docs-hub-page.tsx

@@ -5,7 +5,6 @@ import { FileDownloadCard } from '../embeds/file-download-card';
 import { GoogleSheetsViewer } from '../embeds/google-sheets-viewer';
 import { PdfViewer } from '../embeds/pdf-viewer';
 import { DocViewer, type DocViewerProps } from './doc-viewer';
-import { MarkdownSkeleton, EmbedSkeleton } from './skeletons';
 
 type DocRenderer = (content: DocContent, handlers: DocRenderHandlers) => React.ReactNode;
 
@@ -20,7 +19,7 @@ type DocRenderer = (content: DocContent, handlers: DocRenderHandlers) => React.R
  */
 export type DocumentTypeRenderers = { markdown: DocRenderer } & Partial<Record<DocumentType, DocRenderer>>;
 
-export interface DocsHubPageProps extends Omit<DocViewerProps, 'renderContent' | 'renderSkeleton' | 'showAIChat'> {
+export interface DocsHubPageProps extends Omit<DocViewerProps, 'renderContent' | 'showAIChat'> {
   /** Per-document-type renderer map. `markdown` is REQUIRED. */
   documentTypeRenderers: DocumentTypeRenderers;
 
@@ -42,32 +41,20 @@ const defaultFallbackRenderer: DocRenderer = () => (
   </div>
 );
 
-// When the DAL hasn't populated the URL field for a rich-content type, the
-// embed-viewer components render a broken iframe (empty src). Fall back to
-// the same lib-styled "Unsupported document type" panel the explicit
-// fallback uses — the surface is honest about the missing data instead of
-// pretending to load. `FileDownloadCard` handles its own missing-URL state
-// (hides the Download button), so it doesn't need this guard.
-const defaultPdfRenderer: DocRenderer = (content, handlers) =>
-  content.fileUrl ? (
-    <PdfViewer src={content.fileUrl} fileName={content.fileName} />
-  ) : (
-    defaultFallbackRenderer(content, handlers)
-  );
+// Each viewer owns both its states without a document: in a loading scope (the document is being read) it draws its
+// own loading form, otherwise its "not available" state when the DAL left the URL empty. So the renderers always
+// render the viewer, and the viewer never mounts a frame without a source.
+const defaultPdfRenderer: DocRenderer = content => (
+  <PdfViewer src={content.fileUrl ?? ''} fileName={content.fileName} />
+);
 
-const defaultGoogleSheetRenderer: DocRenderer = (content, handlers) =>
-  content.externalUrl ? (
-    <GoogleSheetsViewer externalUrl={content.externalUrl} fileName={content.fileName} />
-  ) : (
-    defaultFallbackRenderer(content, handlers)
-  );
+const defaultGoogleSheetRenderer: DocRenderer = content => (
+  <GoogleSheetsViewer externalUrl={content.externalUrl ?? ''} fileName={content.fileName} />
+);
 
-const defaultFigmaRenderer: DocRenderer = (content, handlers) =>
-  content.externalUrl ? (
-    <FigmaEmbed url={content.externalUrl} title={content.fileName} loading="eager" />
-  ) : (
-    defaultFallbackRenderer(content, handlers)
-  );
+const defaultFigmaRenderer: DocRenderer = content => (
+  <FigmaEmbed url={content.externalUrl ?? ''} title={content.fileName} iframeLoading="eager" />
+);
 
 const defaultFileRenderer: DocRenderer = content => (
   <FileDownloadCard
@@ -78,16 +65,6 @@ const defaultFileRenderer: DocRenderer = content => (
   />
 );
 
-/** The page's own loading form per document type: the markdown article's, else the embed viewer's. */
-const documentLoadingForm = (documentType: DocumentType | undefined) =>
-  !documentType || documentType === 'markdown' ? (
-    <MarkdownSkeleton />
-  ) : (
-    // Forward the documentType so the embed skeleton renders the right
-    // shape (PDF=2 buttons, sheets/figma=1 button, file=centered card).
-    <EmbedSkeleton documentType={documentType} />
-  );
-
 /**
  * Embeddable docs-hub page. Bundles `<DocViewer>` with safe defaults so the
  * minimum embed is a one-line mount (consumer only has to supply
@@ -132,7 +109,6 @@ export function DocsHubPage({
       className={className}
       sidebarLabel={sidebarLabel}
       renderContent={renderContent}
-      renderSkeleton={documentLoadingForm}
     />
   );
 }

package/src/components/docs/use-document-tree.ts

@@ -9,6 +9,8 @@ import {
   findDocNodeByPath,
   getDocAncestorNodeIds,
   DEFAULT_FOLDER_INDEX_FILE,
+  findFirstDocPath,
+  rootDocumentPath,
 } from '../../utils/doc-tree-nav';
 import { contentFetch } from '../../utils/embed-content-fetch';
 import { navigateSamePageHash, HUB_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
@@ -34,21 +36,6 @@ function scrollToContent() {
  * its README) instead of a blank panel or a redundant in-page listing — the
  * sidebar tree is the directory browser. Returns null for a folder with no docs.
  */
-function findFirstDocPath(folder: DocNode): string | null {
-  const children = folder.children ?? [];
-  for (const child of children) {
-    if (child.type === 'file' && !child.path.toLowerCase().endsWith('.mmd')) {
-      return child.path;
-    }
-  }
-  for (const child of children) {
-    if (child.type === 'folder') {
-      const nested = findFirstDocPath(child);
-      if (nested) return nested;
-    }
-  }
-  return null;
-}
 
 // ---------------------------------------------------------------------------
 // Wire decoding for the two doc-source endpoints
@@ -220,6 +207,11 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
   const cleanInitialPath = stripFolderIndexFromPath(initialPath?.replace(/\/$/, '') || '', folderIndexFile);
 
   const [structure, setStructure] = useState<DocNode[]>([]);
+  // The latest committed tree, for a request that settles after the tree arrived (its closure holds the old one).
+  const structureRef = useRef(structure);
+  useEffect(() => {
+    structureRef.current = structure;
+  }, [structure]);
   const [selectedPath, setSelectedPath] = useState<string>(cleanInitialPath);
   const [content, setContent] = useState<DocContent | null>(null);
   const [isLoadingStructure, setIsLoadingStructure] = useState(true);
@@ -409,12 +401,16 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
           // No-README FOLDER → stay silent: the content effect resolves it to
           // the folder's first child, so the folder-path 404 from the direct-
           // load speculative fetch is expected, not an error to flash.
-          const probe = findDocNodeByPath(stripFolderIndexFromPath(path, folderIndexFile), structure);
+          // Classified against the LATEST tree (`structureRef`), never the one captured when this request went out: the tree
+          // often arrives while the request is in flight, and judged against the empty tree of the call a missing
+          // document read as "not classified yet, wait", so nothing settled it and the page stayed a skeleton.
+          const latestStructure = structureRef.current;
+          const probe = findDocNodeByPath(stripFolderIndexFromPath(path, folderIndexFile), latestStructure);
           const probeIsNoReadmeFolder = !!probe && probe.type === 'folder' && !probe.hasReadme;
           // Before the structure has loaded to classify the path (`structure`
           // is [] in the speculative call's closure), only silence FOLDER-LIKE
           // paths (no `.md`) — a genuinely missing `*.md` leaf must still error.
-          const preStructureFolderLike = structure.length === 0 && !path.endsWith('.md');
+          const preStructureFolderLike = latestStructure.length === 0 && !path.endsWith('.md');
           if (probeIsNoReadmeFolder || preStructureFolderLike) {
             // Superseded by the targeted fetch (first-child / reclassified path)
             // the structure effect fires. Null the request id so the `finally`
@@ -507,7 +503,15 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
     let pathToFetch: string | null = null;
 
     if (selectedPath === '') {
-      pathToFetch = folderIndexFile;
+      // The root shows its landing document (the folder index); a source with none shows its FIRST document, the
+      // rule a no-README folder follows. Asking for the missing index again would 404 for ever.
+      const rootPath = rootDocumentPath(structure, folderIndexFile);
+      if (!rootPath) {
+        // A tree with folders and no document at all: nothing to fetch; the empty state is derived below.
+        lastFetchedPath.current = null;
+        return;
+      }
+      pathToFetch = rootPath;
     } else {
       const node = findDocNodeByPath(selectedPath, structure);
 
@@ -731,19 +735,25 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
   // the content effect, which reached the same conclusion one commit later and
   // meanwhile left the PREVIOUS document's body on screen.
   const isEmptyFolder = useMemo(() => {
-    if (!selectedPath || structure.length === 0) return false;
+    if (structure.length === 0) return false;
+    // The root of a source whose tree holds no document at all is an empty folder too.
+    if (!selectedPath) return !rootDocumentPath(structure, folderIndexFile);
     const node = findDocNodeByPath(selectedPath, structure);
     return !!node && node.type === 'folder' && !node.hasReadme && !findFirstDocPath(node);
-  }, [selectedPath, structure]);
+  }, [selectedPath, structure, folderIndexFile]);
+  // A source with no documents at all (its tree is read and empty): there is nothing to load, so the viewer shows the
+  // source's empty state instead of waiting for a landing document that does not exist.
+  const isEmptySource = !isLoadingStructure && structure.length === 0;
+  const settled = isEmptyFolder || isEmptySource;
 
   return {
     structure,
     selectedPath,
     setSelectedPath,
-    content: isEmptyFolder ? null : content,
+    content: settled ? null : content,
     isLoadingStructure,
-    isLoadingContent: isEmptyFolder ? false : isLoadingContent,
-    error: isEmptyFolder ? null : error,
+    isLoadingContent: settled ? false : isLoadingContent,
+    error: settled ? null : error,
     expandedNodes,
     toggleNode,
     selectNode,