@flamingo-stack/openframe-frontend-core 0.0.472 → 0.0.473-snapshot.20260724114839

package/package.json

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

package/src/components/announcement-bar.tsx

@@ -12,6 +12,7 @@ import {
   isAnnouncementDismissed,
 } from '../utils/announcement-storage';
 import { getAppType } from '../utils/app-config';
+import { cn } from '../utils/cn';
 import { pickReadableTextColor } from '../utils/color-analysis';
 import { EntityIcon } from './icon-display';
 import { AnnouncementBarView } from './ui/announcement-bar-view';
@@ -42,7 +43,12 @@ import { Button } from './ui/button';
  * storage reads happen ONLY in effects (a render-time read would desync
  * hydration in SSR mode).
  */
-export function AnnouncementBar({ initialAnnouncement, previewMode = false, className }: AnnouncementBarProps = {}) {
+export function AnnouncementBar({
+  initialAnnouncement,
+  previewMode = false,
+  dismissible = true,
+  className,
+}: AnnouncementBarProps = {}) {
   // Namespace for the dismissal cookie/legacy keys. Next hosts inline
   // NEXT_PUBLIC_APP_TYPE (matching the server's currentPlatform(), which the
   // hub layout uses for the SSR cookie read); platform-agnostic embeds get
@@ -184,9 +190,11 @@ export function AnnouncementBar({ initialAnnouncement, previewMode = false, clas
     >
       {/*
         Markup is the shared pure view (AnnouncementBarView), which carries the
-        bar's anatomy: ONE line of text inside a 44px strip, ONE compact CTA on
-        the right (hidden below `md`, where the content row is the tap target),
-        and a ghost-icon dismiss. Surface + content treatment stay here.
+        bar's anatomy: one 56px row from `md` up with the compact CTA inline;
+        below `md` a stacked layout with the CTA VISIBLE full-width on its own
+        row and the dismiss up in the content row (Figma 2862-8391 — this
+        replaced the old whole-bar mobile tap target). Surface + content
+        treatment stay here.
       */}
       <div
         className={`min-h-0 overflow-hidden ${themeScope}`}
@@ -194,8 +202,6 @@ export function AnnouncementBar({ initialAnnouncement, previewMode = false, clas
       >
         <AnnouncementBarView
           className="text-[color:var(--color-text-primary)]"
-          contentClassName={hasCta ? 'cursor-pointer md:cursor-default' : undefined}
-          onContentClick={hasCta ? handleCtaClick : undefined}
           startAdornment={
             /* ONE unified icon path (shared with the chat): uploaded image URL
                wins, else a library glyph by name (+ props), via <EntityIcon>. */
@@ -206,20 +212,22 @@ export function AnnouncementBar({ initialAnnouncement, previewMode = false, clas
                 props: displayAnnouncement.icon_props,
               }}
               size={24}
-              // 20px below `md`, 24px from `md` up. `!` is required: logo
-              // glyphs (LogoOpenframeIcon / sizedLogo in icon-library) drive
-              // their size via an inline style, which a plain class loses to.
-              // Not `--icon-size-icon-size` — that token is 16/24 and would
-              // shrink the mobile glyph.
-              className="relative !size-5 shrink-0 md:!size-6"
+              // 16px below `md` (the mockup's mobile glyph — it must not
+              // exceed the 20px title row, Figma 9418-52387 / 2862-8391),
+              // 24px from `md` up. `!` is required: logo glyphs
+              // (LogoOpenframeIcon / sizedLogo in icon-library) drive their
+              // size via an inline style, which a plain class loses to.
+              className="relative !size-4 shrink-0 md:!size-6"
             />
           }
           title={
-            /* Single-line message: bold title + regular description inline,
-               truncating as one unit, at the strip's caption scale (`text-h6`
-               = 13/14px — the same treatment string titles get from the view).
-               Separator is a middot (house rule: no en/em dashes in copy). */
-            <p className="min-w-0 max-w-full text-h6 truncate mb-0">
+            /* Bold title + regular description inline at the mockup's body
+               scale (`text-h4` = DM Sans 500, 14/20 below `md`, 18/24 from
+               `md` up) — wrapping below `md`, truncating as one unit from
+               `md` up (the same responsive pair string titles get from the
+               view). Separator is a middot (house rule: no en/em dashes in
+               copy). */
+            <p className="min-w-0 max-w-full break-words text-h4 md:truncate mb-0">
               <span className="font-[number:var(--font-weight-semibold)]">{displayAnnouncement.title}</span>
               {displayAnnouncement.description && (
                 <span className="hidden sm:inline opacity-80"> · {displayAnnouncement.description}</span>
@@ -233,19 +241,20 @@ export function AnnouncementBar({ initialAnnouncement, previewMode = false, clas
                announcement colors are data, not token surfaces). Inline
                styles win over the variant's hover classes on every state,
                so hover feedback is opacity (the bar's original treatment);
-               nothing can render dark-on-dark. The view CSS-hides it below
-               `md`, where the whole content row is the tap target — this
-               Button stays the keyboard/AT path (known tradeoff).
+               nothing can render dark-on-dark. The view renders it inline
+               from `md` up and as a visible full-width row below `md`.
 
-               Geometry + type come from the design system's size="compact"
-               (24px caption-scale pill for slim strips — rationale documented
-               on the variant in button.tsx). */
+               Geometry + type follow the mockup's "button-full" (Figma
+               9418-52494 / 2862-8391): the design system's size="small"
+               (uppercase text-h5 label, 16px glyph) pinned to h-8 — the
+               mockup keeps the 32px height on EVERY breakpoint, while
+               "small" alone drops to 24px below `md`. */
             hasCta && displayAnnouncement.cta_text ? (
               <Button
                 onClick={handleCtaClick}
                 variant="outline"
-                size="compact"
-                className="transition-opacity hover:opacity-90"
+                size="small"
+                className="h-8 transition-opacity hover:opacity-90"
                 style={{
                   backgroundColor:
                     displayAnnouncement.cta_button_background_color || ANNOUNCEMENT_CTA_DEFAULTS.background,
@@ -257,8 +266,8 @@ export function AnnouncementBar({ initialAnnouncement, previewMode = false, clas
                   displayAnnouncement.cta_show_icon && displayAnnouncement.cta_icon_name ? (
                     <EntityIcon
                       icon={{ name: displayAnnouncement.cta_icon_name, props: displayAnnouncement.cta_icon_props }}
-                      size={14}
-                      className="w-3.5 h-3.5"
+                      size={16}
+                      className="w-4 h-4"
                     />
                   ) : undefined
                 }
@@ -268,21 +277,28 @@ export function AnnouncementBar({ initialAnnouncement, previewMode = false, clas
             ) : undefined
           }
           endAdornment={
-            /* Dismiss - the common Button in its ghost-icon treatment
-               (size="icon-sm": 32px target, >= the 24px WCAG 2.5.8 AA floor,
-               16px glyph) with the bar's quiet tint hover. Inert in
-               previewMode. */
-            <Button
-              onClick={handleDismiss}
-              variant="transparent"
-              size="icon-sm"
-              className={barButtonClasses}
-              aria-label="Dismiss announcement"
-              type="button"
-              tabIndex={expanded ? 0 : -1}
-            >
-              <X strokeWidth={2} />
-            </Button>
+            /* Dismiss - the common Button in its ghost-icon treatment with
+               the bar's quiet tint hover. Below `md` the mockup pins the
+               close to a 20px box with a 16px glyph so the top row stays
+               20px tall and the stacked bar lands on 76px total (Figma
+               2862-8391 — a deliberate exception to the 24px WCAG 2.5.8
+               target floor); from `md` up it grows back to the standard
+               icon-sm 32px target. Inert in previewMode; omitted entirely
+               when the host opts out via `dismissible={false}` (the bar
+               then only disappears by deactivating the announcement). */
+            dismissible ? (
+              <Button
+                onClick={handleDismiss}
+                variant="transparent"
+                size="icon-sm"
+                className={cn('h-5 w-5 p-0 md:h-8 md:w-8', barButtonClasses)}
+                aria-label="Dismiss announcement"
+                type="button"
+                tabIndex={expanded ? 0 : -1}
+              >
+                <X strokeWidth={2} />
+              </Button>
+            ) : undefined
           }
         />
       </div>

package/src/components/navigation/mobile-burger-menu.tsx

@@ -79,6 +79,7 @@ export const MobileBurgerMenu = React.memo(function MobileBurgerMenu({
         disabled={disabled}
         className={cn(
           "flex items-center gap-1 p-3 relative",
+          "focus:outline-none focus-visible:outline-none",
           "transition-colors duration-200",
           "bg-ods-card border border-ods-border rounded-md",
           !disabled && "hover:bg-ods-bg-hover",

package/src/components/ui/announcement-bar-view.tsx

@@ -3,44 +3,29 @@
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 import { cn } from '../../utils/cn';
 
-/**
- * Mirrors `screens.md` in tailwind.config.ts (800px), which is also where the
- * ODS responsive tokens step up (ods-responsive-tokens.css). ONE breakpoint
- * for the whole bar: the `md:` variants below and the `onContentClick` guard
- * must never disagree (they did before — the guard read a stale 768px while
- * the CSS switched at 800px).
- */
-const MD_QUERY = '(min-width: 800px)';
-
 export interface AnnouncementBarViewProps {
   /**
    * Leading slot — typically an icon, at content width before the title. Size
-   * it in the slot: the bar's icon runs 20px below `md` and 24px from `md` up,
-   * and no ODS icon token carries that pair (`--icon-size-icon-size` is 16/24).
+   * it in the slot: the bar's icon is 16px below `md` (must not exceed the
+   * 20px title row, Figma 9418-52387) and 24px from `md` up.
    */
   startAdornment?: ReactNode;
   /**
-   * Bar message, always ONE line. A plain string gets the strip's text
-   * treatment (`text-h6`, truncating); pass a ReactElement to own the markup
-   * (e.g. bold title + inline description truncating as one unit).
+   * Bar message. A plain string gets the mockup's text treatment (`text-h4` =
+   * DM Sans 500, 14/20 below `md` and 18/24 from `md` up), wrapping below `md`
+   * and truncating to one line from `md` up. Pass a ReactElement to own the
+   * markup (e.g. bold title + inline description) — mirror that responsive
+   * wrap/truncate pair in your element.
    */
   title?: string | ReactElement;
   /**
-   * Primary CTA, at content width after the title. Hidden below `md`, where
-   * the content row becomes the tap target instead (`onContentClick`) — the
-   * banner pattern's touch-first tradeoff.
+   * Primary CTA. From `md` up it sits inline at content width between the
+   * title and `endAdornment`; below `md` it moves to its own full-width row
+   * under the content (Figma 2862-8391) and the bar's height grows to fit.
    */
   actionBlock?: ReactElement;
-  /** Trailing slot (e.g. a dismiss button). Outside the tap target, every breakpoint. */
+  /** Trailing slot (e.g. a dismiss button) — stays in the top/content row on every breakpoint. */
   endAdornment?: ReactElement;
-  /**
-   * Below `md` only: fires when the content row is tapped, standing in for the
-   * `actionBlock` that is CSS-hidden at that width. No-op from `md` up, where
-   * the CTA is visible and owns the interaction.
-   */
-  onContentClick?: () => void;
-  /** Extra classes for the padded content row (e.g. a cursor affordance). */
-  contentClassName?: string;
   /** Surface styling (background, text color, theme scope) is the consumer's — pass it here. */
   className?: string;
   style?: CSSProperties;
@@ -50,62 +35,53 @@ export interface AnnouncementBarViewProps {
  * Pure presentational announcement/notification bar. No data fetching,
  * storage, or navigation — consumers own state and pass content through slots.
  *
- * Anatomy follows the announcement-bar industry standard: ONE line of text at
- * 13-14px inside a 44px-tall strip (guides converge on 40-60px with a single
- * sentence; two stacked 18px rows blow past that), ONE compact CTA on the
- * right, and a trailing dismiss slot. Spacing is the ODS responsive tokens,
- * which step at the same 800px as `md`: `l` = 16/24px edge padding, `s` =
- * 8/12px gap, `m` = CTA offset, `xs` = 4/8px.
+ * Layout (Figma 9418-52494 desktop/tablet, 2862-8391 mobile):
+ * - `md` (800px) and up: ONE row inside a strip with a RESERVED 56px minimum
+ *   height (`md:min-h-14`, the mockup's strip height) — held unconditionally,
+ *   so toggling or removing the action never resizes the bar on
+ *   desktop/tablet. Title truncates to one line.
+ * - Below `md`: the container stacks (`px` 16 / `py` 8 / gap 8). Top row =
+ *   `startAdornment` + wrapping title + `endAdornment`; when an `actionBlock`
+ *   is present it renders as a VISIBLE full-width button on its own second
+ *   row and the bar's height adapts to content (76px with a single-line
+ *   title and CTA per Figma 9418-52387: 8 + 20 + 8 + 32 + 8).
+ *
+ * The `actionBlock` element is mounted in both positions (inline `md`-up slot
+ * and the mobile full-width row); exactly one is `display:none` at any width,
+ * so keyboard/AT always reach exactly one control.
  */
 export function AnnouncementBarView({
   startAdornment,
   title,
   actionBlock,
   endAdornment,
-  onContentClick,
-  contentClassName,
   className,
   style,
 }: AnnouncementBarViewProps) {
-  const handleContentClick = onContentClick
-    ? () => {
-        if (!window.matchMedia(MD_QUERY).matches) onContentClick();
-      }
-    : undefined;
-
   return (
-    <div className={cn('flex w-full max-w-full min-h-11 items-center', className)} style={style}>
-      {/* Content row — the tap target below `md`, where the CTA is hidden.
-          Its vertical padding never drives the height; the 44px strip does. */}
-      <div
-        className={cn(
-          'flex min-w-0 flex-1 flex-row items-center gap-[var(--spacing-system-s)] py-[var(--spacing-system-xs)] pl-[var(--spacing-system-l)]',
-          contentClassName,
-        )}
-        onClick={handleContentClick}
-      >
+    <div
+      className={cn(
+        'flex w-full max-w-full flex-col gap-[var(--spacing-system-s)] px-[var(--spacing-system-l)] py-[var(--spacing-system-s)] md:min-h-14 md:flex-row md:items-center md:py-0',
+        className,
+      )}
+      style={style}
+    >
+      {/* Content row: leading icon + title (+ inline CTA from `md`) + trailing
+          slot. `items-start` below `md` keeps the adornments pinned to the
+          first text line when the title wraps; `md:items-center` re-centers
+          everything in the fixed strip. */}
+      <div className="flex w-full min-w-0 flex-1 items-start gap-[var(--spacing-system-s)] md:w-auto md:items-center">
         {startAdornment && <div className="flex shrink-0 items-center">{startAdornment}</div>}
         {typeof title === 'string' ? (
-          <p className="mb-0 min-w-0 max-w-full flex-1 truncate text-h6">{title}</p>
+          <p className="mb-0 min-w-0 max-w-full flex-1 break-words text-h4 md:truncate">{title}</p>
         ) : (
           title != null && <div className="min-w-0 max-w-full flex-1">{title}</div>
         )}
-        {/* Below `md` the CTA is visually replaced by the row-wide tap target,
-            but a `display:none` button is unreachable by keyboard and AT. So
-            it is only visually hidden there (`sr-only`) and reveals itself on
-            focus — the row stays the touch affordance while Tab still reaches
-            a real, labelled control. `md:` restores the normal inline CTA. */}
-        {actionBlock && (
-          <div className="ml-[var(--spacing-system-m)] sr-only shrink-0 focus-within:not-sr-only md:not-sr-only md:flex">
-            {actionBlock}
-          </div>
-        )}
+        {actionBlock && <div className="hidden shrink-0 md:flex">{actionBlock}</div>}
+        {endAdornment && <div className="flex shrink-0 items-center">{endAdornment}</div>}
       </div>
-      {/* Trailing slot. Its own 32px hit box optically re-centers the glyph
-          against the 16/24px left edge. */}
-      {endAdornment && (
-        <div className="ml-[var(--spacing-system-xs)] mr-[var(--spacing-system-m)] shrink-0">{endAdornment}</div>
-      )}
+      {/* Mobile-only action row — the CTA stretched to the bar's full width. */}
+      {actionBlock && <div className="flex w-full md:hidden [&>*]:w-full">{actionBlock}</div>}
     </div>
   );
 }

package/src/components/ui/entity-image.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import React from 'react'
+import { useAuthedImageSrc } from '../../hooks/use-authed-image-src'
 import { cn } from '../../utils/cn'
 import { getFirstLastInitials } from '../../utils/format'
 
@@ -13,13 +14,14 @@ export interface EntityImageProps {
 }
 
 export function EntityImage({ src, alt, fallbackText, className }: EntityImageProps) {
+  const resolvedSrc = useAuthedImageSrc(src)
   const [imageFailed, setImageFailed] = React.useState(false)
 
   React.useEffect(() => {
     setImageFailed(false)
-  }, [src])
+  }, [resolvedSrc])
 
-  const showFallback = imageFailed || !src
+  const showFallback = imageFailed || !resolvedSrc
   const initials = getFirstLastInitials(fallbackText ?? alt)
 
   if (showFallback) {
@@ -38,7 +40,7 @@ export function EntityImage({ src, alt, fallbackText, className }: EntityImagePr
 
   return (
     <img
-      src={src ?? undefined}
+      src={resolvedSrc}
       alt={alt ?? ''}
       onError={() => setImageFailed(true)}
       className={cn(

package/src/components/ui/image-uploader.tsx

@@ -5,6 +5,7 @@ import { Loader2 } from "lucide-react"
 import { ImagePlusIcon } from "../icons-v2-generated/audio-and-visual/image-plus-icon"
 import { Refresh02VrIcon } from "../icons-v2-generated/media-playback/refresh-02-vr-icon"
 import { TrashIcon } from "../icons-v2-generated/interface/trash-icon"
+import { useAuthedImageSrc } from "../../hooks/use-authed-image-src"
 import { cn } from "../../utils/cn"
 import { FieldWrapper } from "./field-wrapper"
 
@@ -98,6 +99,12 @@ export function ImageUploader({
   const [validationError, setValidationError] = React.useState<string | null>(null)
 
   const interactive = !disabled && !loading
+  // Bearer-mode shells: swap a gateway URL for an authed blob URL (native
+  // <img> loads can't carry Authorization); pass-through everywhere else,
+  // including local blob/data preview URLs. `hasImage` stays keyed on the
+  // caller's `value` so the preview chrome doesn't flash to the empty
+  // state while the blob fetch is in flight.
+  const resolvedValue = useAuthedImageSrc(value)
   const hasImage = Boolean(value)
   const displayError = error || validationError || undefined
   const resolvedHint = hint === undefined ? `Max. size: ${formatSize(maxSize)}` : hint
@@ -196,18 +203,20 @@ export function ImageUploader({
         {hasImage ? (
           <>
             <div className="relative min-h-0 w-full flex-1 overflow-hidden rounded-md">
-              <img
-                src={value}
-                alt={alt}
-                className={cn(
-                  "pointer-events-none absolute inset-0 size-full",
-                  objectFit === "cover" && "object-cover",
-                  objectFit === "contain" && "object-contain",
-                  objectFit === "fill" && "object-fill",
-                  objectFit === "none" && "object-none",
-                  objectFit === "scale-down" && "object-scale-down",
-                )}
-              />
+              {resolvedValue && (
+                <img
+                  src={resolvedValue}
+                  alt={alt}
+                  className={cn(
+                    "pointer-events-none absolute inset-0 size-full",
+                    objectFit === "cover" && "object-cover",
+                    objectFit === "contain" && "object-contain",
+                    objectFit === "fill" && "object-fill",
+                    objectFit === "none" && "object-none",
+                    objectFit === "scale-down" && "object-scale-down",
+                  )}
+                />
+              )}
             </div>
 
             <div className="absolute left-1/2 top-1/2 flex -translate-x-1/2 -translate-y-1/2 items-center gap-4">

package/src/components/ui/simple-markdown-renderer.tsx

@@ -9,6 +9,7 @@ import rehypeHighlight from 'rehype-highlight';
 import rehypeRaw from 'rehype-raw';
 import { visit } from 'unist-util-visit';
 import Image from '../../embed-shims/next-image';
+import { useAuthedImageSrc } from '../../hooks/use-authed-image-src';
 import { AlertCircleIcon } from '../icons-v2-generated';
 import { cn } from '../../utils/cn';
 import type { ResolveLinkResult } from '../../types/doc-source';
@@ -453,6 +454,58 @@ const MermaidDiagram: React.FC<{ chart: string }> = ({ chart }) => {
   );
 };
 
+// ---------------------------------------------------------------------------
+// MarkdownContentImage
+// ---------------------------------------------------------------------------
+// Inline content image renderer. Used by blog posts, docs, AND chat
+// messages (where users may attach screenshots / photos via the +
+// attachment button). A standalone component (rather than inline JSX in
+// the `img` renderer) because it needs `useAuthedImageSrc`: in
+// bearer-mode native shells a gateway-hosted image can't load via a
+// plain `<img>` (no Authorization header on native asset loads), so the
+// hook swaps in an authed blob URL; everywhere else it passes `src`
+// through untouched. While the blob fetch is in flight the component
+// renders nothing — same as the no-src case.
+//
+// Sizing rules (2025-2026 best practice — Claude.ai, ChatGPT,
+// iMessage, Slack, Discord inline image patterns):
+//
+//   - CAP max-width at 400px so inline images don't blow out the
+//     message column on wide panels. Click-to-expand opens a
+//     full-resolution modal for users who need detail.
+//   - CAP max-height at 400px so portrait-orientation images
+//     don't dominate vertical space (a 1000x3000 phone screenshot
+//     would otherwise push the next message off-screen).
+//   - Small images render at NATURAL pixel size — a 64x64
+//     thumbnail stays 64x64, not stretched to fill the column.
+//   - `object-contain` preserves aspect ratio when both dimensions
+//     are constrained (long landscape, tall portrait).
+//
+// Implementation: Next.js `<Image>` — the project's canonical
+// image primitive (WebP/AVIF conversion, responsive `srcset`, lazy
+// loading, async decode). `width={400} height={400}` are REQUIRED by
+// Next.js `<Image>` (non-`fill` mode throws without them) but they're
+// effectively a CEILING here, not the display size — the CSS overrides
+// (`w-auto h-auto max-w-full max-h-[400px]`) drive the actual rendered
+// size, and the inline `style={{ width: 'auto', height: 'auto' }}` is
+// belt-and-suspenders against the rendered `<img>`'s HTML width/height
+// attributes.
+const MarkdownContentImage: React.FC<{ src: string; alt?: string }> = ({ src, alt }) => {
+  const resolvedSrc = useAuthedImageSrc(src);
+  if (!resolvedSrc) return null;
+  return (
+    <Image
+      src={resolvedSrc}
+      alt={alt ?? 'No image available'}
+      width={400}
+      height={400}
+      sizes="(max-width: 400px) 100vw, 400px"
+      className="max-w-full max-h-[400px] w-auto h-auto rounded-lg object-contain"
+      style={{ width: 'auto', height: 'auto' }}
+    />
+  );
+};
+
 // ---------------------------------------------------------------------------
 // Utility: extract plain text from React children
 // ---------------------------------------------------------------------------
@@ -820,66 +873,12 @@ const SimpleMarkdownRendererImpl: React.FC<SimpleMarkdownRendererProps> = ({
     },
 
     // --- images ---
-    // Inline content image renderer. Used by blog posts, docs, AND chat
-    // messages (where users may attach screenshots / photos via the +
-    // attachment button).
-    //
-    // Sizing rules (2025-2026 best practice — Claude.ai, ChatGPT,
-    // iMessage, Slack, Discord inline image patterns):
-    //
-    //   - CAP max-width at 400px so inline images don't blow out the
-    //     message column on wide panels. Click-to-expand opens a
-    //     full-resolution modal for users who need detail.
-    //   - CAP max-height at 400px so portrait-orientation images
-    //     don't dominate vertical space (a 1000x3000 phone screenshot
-    //     would otherwise push the next message off-screen).
-    //   - Small images render at NATURAL pixel size — a 64x64
-    //     thumbnail stays 64x64, not stretched to fill the column.
-    //   - `object-contain` preserves aspect ratio when both dimensions
-    //     are constrained (long landscape, tall portrait).
-    //
-    // Implementation: Next.js `<Image>` — the project's canonical
-    // image primitive. Gives us:
-    //   - WebP/AVIF format conversion for modern browsers (smaller
-    //     bytes for the same visual quality).
-    //   - Responsive `srcset` via the `sizes` prop (browser picks the
-    //     right variant for the viewport).
-    //   - Automatic lazy-loading (`loading="lazy"` by default, mid-
-    //     page images skipped until they near the viewport).
-    //   - Automatic `decoding="async"` so image decode doesn't block
-    //     paint.
-    //
-    // `width={400} height={400}` props are REQUIRED by Next.js
-    // `<Image>` (non-`fill` mode throws without them) but they're
-    // effectively a CEILING here, not the display size — the CSS
-    // overrides (`w-auto h-auto max-w-full max-h-[400px]`) drive
-    // the actual rendered size. The inline `style={{ width: 'auto',
-    // height: 'auto' }}` is belt-and-suspenders: Next.js Image sets
-    // matching HTML `width`/`height` attributes on the rendered
-    // `<img>` and inline style wins over both HTML attributes AND
-    // utility classes regardless of CSS-specificity surprises.
-    //
-    // Layout reservation trade-off: until image bytes arrive, the
-    // browser may reserve a placeholder box up to 400x400 (the props'
-    // intrinsic-ratio hint). Once loaded, the box collapses to the
-    // natural size if smaller. This is the standard Next.js Image
-    // behavior across the codebase — accepted for the optimizer +
-    // responsive-srcset benefits. Chat attachments hosted in side
-    // panels see this only on first render of a fresh attachment
-    // (cached re-renders pop in without a perceptible shift).
+    // Delegates to MarkdownContentImage (module scope, above) — sizing
+    // rules, Next.js <Image> rationale, and the bearer-mode authed-src
+    // handling are documented there.
     img: ({ src, alt }: any) => {
       if (!src || typeof src !== 'string' || src.trim() === '') return null;
-      return (
-        <Image
-          src={src}
-          alt={alt ?? 'No image available'}
-          width={400}
-          height={400}
-          sizes="(max-width: 400px) 100vw, 400px"
-          className="max-w-full max-h-[400px] w-auto h-auto rounded-lg object-contain"
-          style={{ width: 'auto', height: 'auto' }}
-        />
-      );
+      return <MarkdownContentImage src={src} alt={alt} />;
     },
 
     // --- lists ---

package/src/components/ui/square-avatar.tsx

@@ -2,6 +2,7 @@
 
 import * as React from "react";
 import Image from "../../embed-shims/next-image";
+import { useAuthedImageSrc } from "../../hooks/use-authed-image-src";
 import { cn } from "../../utils/cn";
 import { getFirstLastInitials } from "../../utils/format";
 
@@ -22,6 +23,7 @@ interface SquareAvatarProps extends React.HTMLAttributes<HTMLDivElement> {
 
 const SquareAvatar = React.memo(React.forwardRef<HTMLDivElement, SquareAvatarProps>(
   ({ className, src, alt, size = 'md', sizePx, fallback, variant = 'square', initialsClassName, style, ...props }, ref) => {
+    const resolvedSrc = useAuthedImageSrc(src)
     const sizeClasses = {
       sm: 'h-8 w-8',
       md: 'h-10 w-10',
@@ -66,14 +68,14 @@ const SquareAvatar = React.memo(React.forwardRef<HTMLDivElement, SquareAvatarPro
           // keeps the later class).
           'flex items-center justify-center text-xs font-medium text-[color:var(--ods-avatar-initials,var(--color-text-primary))]',
           initialsClassName,
-          src && 'hidden'
+          resolvedSrc && 'hidden'
         )}>
           {getFirstLastInitials(fallback || alt) || '?'}
         </div>
-        {src && (
+        {resolvedSrc && (
           <Image
             className="absolute -inset-px h-[calc(100%+2px)] w-[calc(100%+2px)] max-w-none object-cover"
-            src={src}
+            src={resolvedSrc}
             alt={alt || ''}
             width={sizePx ?? sizePxBySize[size]}
             height={sizePx ?? sizePxBySize[size]}

package/src/hooks/index.ts

@@ -8,6 +8,7 @@ export * from './use-copy-to-clipboard'
 // Image authentication hooks
 export * from './use-batch-images'
 export * from './use-authenticated-image'
+export * from './use-authed-image-src'
 
 // URL State Management hooks
 export * from './state'