@workbench-kit/react 0.0.2-prototype.0.2.4 → 0.0.2-prototype.0.2.41

package/src/primitives/app-icon/app-icon.css

@@ -0,0 +1,28 @@
+.ui-app-icon {
+  --ui-app-icon-size: 20px;
+  box-sizing: border-box;
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  width: var(--ui-app-icon-size);
+  height: var(--ui-app-icon-size);
+  overflow: hidden;
+  border-radius: var(--shell-radius-xs, var(--radius-sm, 2px));
+}
+
+.ui-app-icon[data-size='sm'] {
+  --ui-app-icon-size: 16px;
+}
+
+.ui-app-icon[data-size='lg'] {
+  --ui-app-icon-size: 32px;
+}
+
+.ui-app-icon__image,
+.ui-app-icon > svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}

package/src/primitives/button/Button.tsx

@@ -6,10 +6,10 @@ import { cx } from '../../utils/cx';
 type ButtonVariant = 'default' | 'primary' | 'danger';
 
 export interface ButtonProps extends ComponentPropsWithRef<'button'> {
-  block?: boolean | undefined;
-  compact?: boolean | undefined;
-  icon?: string | undefined;
-  secondary?: boolean | undefined;
+  block?: boolean;
+  compact?: boolean;
+  icon?: string;
+  secondary?: boolean;
   variant?: ButtonVariant;
 }
 

package/src/primitives/catalog-browse-card/CatalogBrowseCard.tsx

@@ -11,9 +11,9 @@ export interface CatalogBrowseCardProps extends Omit<
   'children' | 'title'
 > {
   description?: ReactNode;
-  icon?: string | undefined;
-  imageAlt?: string | undefined;
-  imageUrl?: string | null | undefined;
+  icon?: string;
+  imageAlt?: string;
+  imageUrl?: string | null;
   label: ReactNode;
   /**
    * Custom media content for the icon/cover region. When set, replaces the
@@ -23,15 +23,15 @@ export interface CatalogBrowseCardProps extends Omit<
   /** Overlay content inside the media region (badges, status chips, etc.). */
   mediaOverlay?: ReactNode;
   meta?: ReactNode;
-  selected?: boolean | undefined;
+  selected?: boolean;
   /**
    * Secondary actions outside the primary hit target (for example Assign).
    * When set, the root becomes a non-button container and click/drag handlers
    * apply to the main control only.
    */
   trailing?: ReactNode;
-  tooltip?: string | undefined;
-  variant?: CatalogBrowseCardVariant | undefined;
+  tooltip?: string;
+  variant?: CatalogBrowseCardVariant;
 }
 
 export function CatalogBrowseCard({

package/src/primitives/catalog-browse-pane/CatalogBrowsePane.tsx

@@ -33,12 +33,12 @@ export type CatalogBrowseViewMode = 'grid' | 'list';
  * Hosts with richer cards should pass `renderGridItem` / `renderListItem`.
  */
 export interface CatalogBrowseItem {
-  readonly description?: string | null | undefined;
+  readonly description?: string | null;
   readonly id: string;
-  readonly imageAlt?: string | undefined;
-  readonly imageUrl?: string | null | undefined;
+  readonly imageAlt?: string;
+  readonly imageUrl?: string | null;
   readonly label: string;
-  readonly meta?: string | null | undefined;
+  readonly meta?: string | null;
 }
 
 export interface CatalogBrowseItemRenderState {
@@ -48,17 +48,17 @@ export interface CatalogBrowseItemRenderState {
 export interface CatalogBrowsePaneProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
   readonly clearSearchLabel: string;
   readonly emptyMessage: string;
-  readonly errorMessage?: string | null | undefined;
+  readonly errorMessage?: string | null;
   /** Slot between search and sort/view controls (facet trigger, chips, etc.). */
   readonly facetStrip?: ReactNode;
-  readonly gridAriaLabel?: string | undefined;
+  readonly gridAriaLabel?: string;
   /** Visual label for the grid view-mode segment (string or icon node). */
   readonly gridLabel?: ReactNode;
   readonly hasMore: boolean;
   readonly isLoading: boolean;
   readonly isLoadingMore: boolean;
   readonly items: ReadonlyArray<CatalogBrowseItem>;
-  readonly listAriaLabel?: string | undefined;
+  readonly listAriaLabel?: string;
   /** Visual label for the list view-mode segment (string or icon node). */
   readonly listLabel?: ReactNode;
   readonly loadingMessage: string;
@@ -66,11 +66,11 @@ export interface CatalogBrowsePaneProps extends Omit<ComponentPropsWithRef<'div'
     ((itemId: string, itemLabel: string, event: ReactMouseEvent<HTMLElement>) => void) | undefined;
   readonly onLoadMore: () => void;
   readonly onOpenItem: (itemId: string) => void;
-  readonly onRefresh?: (() => void) | null | undefined;
+  readonly onRefresh?: (() => void) | null;
   readonly onSearchQueryChange: (query: string) => void;
-  readonly onSortChange?: ((sort: string) => void) | undefined;
+  readonly onSortChange?: (sort: string) => void;
   readonly onViewModeChange: (viewMode: CatalogBrowseViewMode) => void;
-  readonly refreshLabel?: string | null | undefined;
+  readonly refreshLabel?: string | null;
   readonly renderGridItem?:
     ((item: CatalogBrowseItem, state: CatalogBrowseItemRenderState) => ReactNode) | undefined;
   readonly renderListItem?:
@@ -78,14 +78,14 @@ export interface CatalogBrowsePaneProps extends Omit<ComponentPropsWithRef<'div'
   readonly searchAriaLabel: string;
   readonly searchPlaceholder: string;
   readonly searchQuery: string;
-  readonly selectedItemId?: string | null | undefined;
-  readonly sort?: string | undefined;
-  readonly sortAriaLabel?: string | undefined;
-  readonly sortOptions?: ReadonlyArray<{ label: string; value: string }> | undefined;
+  readonly selectedItemId?: string | null;
+  readonly sort?: string;
+  readonly sortAriaLabel?: string;
+  readonly sortOptions?: ReadonlyArray<{ label: string; value: string }>;
   /** Extra trailing controls after built-in sort / view mode (before refresh). */
   readonly toolbarTrailing?: ReactNode;
   readonly viewMode: CatalogBrowseViewMode;
-  readonly viewModeAriaLabel?: string | undefined;
+  readonly viewModeAriaLabel?: string;
 }
 
 export function CatalogBrowsePane({
@@ -240,25 +240,32 @@ export function CatalogBrowsePane({
         >
           {items.map((item) => {
             const selected = selectedItemId === item.id;
-            if (renderGridItem) {
-              return <Fragment key={item.id}>{renderGridItem(item, { selected })}</Fragment>;
-            }
             return (
-              <CatalogBrowseCard
-                data-ui-catalog-browse-item={item.id}
-                imageAlt={item.imageAlt ?? item.label}
-                imageUrl={item.imageUrl ?? null}
+              <div
+                className="ui-catalog-browse__item"
+                data-ui-catalog-browse-item-container={item.id}
                 key={item.id}
-                label={item.label}
-                meta={item.meta ?? undefined}
-                onClick={() => onOpenItem(item.id)}
-                onContextMenu={(event) => {
-                  onItemContextMenu?.(item.id, item.label, event);
-                }}
-                selected={selected}
-                tooltip={item.label}
-                variant="cover"
-              />
+                role="listitem"
+              >
+                {renderGridItem ? (
+                  renderGridItem(item, { selected })
+                ) : (
+                  <CatalogBrowseCard
+                    data-ui-catalog-browse-item={item.id}
+                    imageAlt={item.imageAlt ?? item.label}
+                    imageUrl={item.imageUrl ?? null}
+                    label={item.label}
+                    meta={item.meta ?? undefined}
+                    onClick={() => onOpenItem(item.id)}
+                    onContextMenu={(event) => {
+                      onItemContextMenu?.(item.id, item.label, event);
+                    }}
+                    selected={selected}
+                    tooltip={item.label}
+                    variant="cover"
+                  />
+                )}
+              </div>
             );
           })}
           <BrowseScrollFooter

package/src/primitives/catalog-browse-pane/catalog-browse-pane.css

@@ -50,6 +50,10 @@
   min-height: 0;
 }
 
+.ui-catalog-browse__item {
+  min-width: 0;
+}
+
 .ui-catalog-browse__grid {
   align-content: start;
   display: grid;

package/src/primitives/catalog-filter-overlay/CatalogFilterOverlay.tsx

@@ -13,10 +13,10 @@ export interface CatalogFilterOverlayProps extends Omit<
    * When true, Clear stays mounted and sized but is not actionable.
    * Keeps the title row height stable across selection changes.
    */
-  readonly clearDisabled?: boolean | undefined;
+  readonly clearDisabled?: boolean;
   readonly clearLabel: string;
   readonly onClear: () => void;
-  readonly ref?: Ref<HTMLDivElement> | undefined;
+  readonly ref?: Ref<HTMLDivElement>;
   readonly title: ReactNode;
   readonly titleId: string;
 }

package/src/primitives/checkbox/Checkbox.tsx

@@ -3,7 +3,7 @@ import type { ChangeEvent, ComponentPropsWithRef, ReactNode } from 'react';
 import { cx } from '../../utils/cx';
 
 export interface CheckboxProps extends Omit<ComponentPropsWithRef<'input'>, 'type'> {
-  label?: ReactNode | undefined;
+  label?: ReactNode;
   onCheckedChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
 }
 

package/src/primitives/chip/Chip.tsx

@@ -4,15 +4,12 @@ import { Button } from '../button';
 import { cx } from '../../utils/cx';
 
 export interface ChipProps extends Omit<ComponentPropsWithRef<'button'>, 'children'> {
-  count?: number | undefined;
+  count?: number;
   label: ReactNode;
-  onDismiss?: (() => void) | undefined;
+  onDismiss?: () => void;
 }
 
-/**
- * Compact labeled control, optionally dismissible (close affordance).
- * Preferred over layout-scoped `FilterChip`.
- */
+/** Compact labeled control, optionally dismissible (close affordance). */
 export function Chip({ className, count, label, onDismiss, type = 'button', ...props }: ChipProps) {
   return (
     <Button className={cx('ui-chip', 'ui-filter-chip', className)} type={type} {...props}>
@@ -35,9 +32,3 @@ export function Chip({ className, count, label, onDismiss, type = 'button', ...p
     </Button>
   );
 }
-
-/** @deprecated Use {@link Chip} / {@link ChipProps}. */
-export const FilterChip = Chip;
-
-/** @deprecated Use {@link ChipProps}. */
-export type FilterChipProps = ChipProps;

package/src/primitives/chip/index.ts

@@ -1,2 +1,2 @@
-export { Chip, FilterChip } from './Chip';
-export type { ChipProps, FilterChipProps } from './Chip';
+export { Chip } from './Chip';
+export type { ChipProps } from './Chip';

package/src/primitives/codicon/Codicon.tsx

@@ -4,7 +4,7 @@ import { cxCodicon } from '../../utils/codicon';
 export interface CodiconProps extends Omit<ComponentPropsWithRef<'i'>, 'children'> {
   icon: string;
   /** When set, exposes the icon to assistive tech instead of aria-hidden. */
-  label?: string | undefined;
+  label?: string;
 }
 
 /** VS Code codicon glyph (`codicon` font). Requires `@vscode/codicons` CSS in the app entry. Prefer `WorkbenchIcon` for new code. */

package/src/primitives/file-icon/FileIcon.tsx

@@ -6,7 +6,7 @@ export const UI_FILE_ICON_CLASS = 'ui-file-icon';
 
 export interface FileIconProps extends Omit<ComponentPropsWithRef<'i'>, 'children'> {
   icon: string;
-  kind?: FileIconKind | undefined;
+  kind?: FileIconKind;
 }
 
 export function FileIcon({ className, icon, kind, ...props }: FileIconProps) {

package/src/primitives/icon-button/IconButton.tsx

@@ -7,7 +7,7 @@ import { cx } from '../../utils/cx';
 type IconButtonVariant = 'default' | 'danger';
 
 export interface IconButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'children'> {
-  compact?: boolean | undefined;
+  compact?: boolean;
   icon: WorkbenchIconInput;
   label: string;
   variant?: IconButtonVariant;

package/src/primitives/index.ts

@@ -1,5 +1,7 @@
 export { AbsoluteBox } from './absolute-box/AbsoluteBox';
 export type { AbsoluteBoxProps, WorkbenchRect } from './absolute-box/AbsoluteBox';
+export { AppIcon } from './app-icon/AppIcon';
+export type { AppIconProps, AppIconSize } from './app-icon/AppIcon';
 export { Badge } from './badge/Badge';
 export type { BadgeProps } from './badge/Badge';
 export { Button } from './button/Button';
@@ -110,6 +112,11 @@ export type {
   LibraryDetailLayoutMode,
   LibraryDetailLayoutProps,
 } from './library-detail-layout/LibraryDetailLayout';
+export { resolveLibraryDetailHeroCoverMedia } from './library-detail-layout/resolve-hero-cover-media.js';
+export type {
+  ResolveLibraryDetailHeroCoverMediaInput,
+  ResolvedLibraryDetailHeroCoverMedia,
+} from './library-detail-layout/resolve-hero-cover-media.js';
 export { ScrollAreaInfiniteSentinel } from './scroll-area-infinite-load/ScrollAreaInfiniteSentinel';
 export type { ScrollAreaInfiniteSentinelProps } from './scroll-area-infinite-load/ScrollAreaInfiniteSentinel';
 export { useScrollAreaInfiniteLoad } from './scroll-area-infinite-load/useScrollAreaInfiniteLoad';
@@ -145,7 +152,6 @@ export {
   FilterBar,
   FilterBarActiveChips,
   FilterBarRow,
-  FilterChip,
   HelpText,
   Panel,
   PanelBody,
@@ -164,7 +170,6 @@ export type {
   FilterBarActiveChipsProps,
   FilterBarProps,
   FilterBarRowProps,
-  FilterChipProps,
   HelpTextProps,
   PanelBodyProps,
   PanelFooterProps,

package/src/primitives/library-detail-layout/LibraryDetailLayout.tsx

@@ -1,25 +1,33 @@
 import './library-detail-layout.css';
-import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { useEffect, useState, type ComponentPropsWithRef, type ReactNode } from 'react';
 
 import { cx } from '../../utils/cx';
 import { WorkbenchMediaSlot } from '../workbench-media-slot';
 import { RecordMediaHero } from '../record-media-hero';
 import { ScrollArea } from '../scroll-area';
+import { resolveLibraryDetailHeroCoverMedia } from './resolve-hero-cover-media.js';
 
-export type LibraryDetailLayoutMode = 'background' | 'banner' | 'compact';
+export type LibraryDetailLayoutMode = 'background' | 'banner' | 'compact' | 'hero-cover';
 
 export interface LibraryDetailLayoutProps extends Omit<
   ComponentPropsWithRef<'div'>,
   'children' | 'title'
 > {
   readonly actions?: ReactNode;
-  readonly backgroundImageUrl?: string | null | undefined;
+  /** Optional attribution / footer below the identity row (`hero-cover` mode). */
+  readonly attribution?: ReactNode;
+  readonly backgroundImageUrl?: string | null;
   readonly children?: ReactNode;
-  readonly coverAlt?: string | undefined;
-  readonly coverImageUrl?: string | null | undefined;
+  readonly coverAlt?: string;
+  readonly coverImageUrl?: string | null;
   readonly description?: ReactNode;
-  readonly logoImageUrl?: string | null | undefined;
-  readonly mode?: LibraryDetailLayoutMode | undefined;
+  /**
+   * Wide hero band URL for `hero-cover` mode. When omitted or identical to
+   * `coverImageUrl`, the cover is used as soft atmosphere behind the portrait.
+   */
+  readonly heroImageUrl?: string | null;
+  readonly logoImageUrl?: string | null;
+  readonly mode?: LibraryDetailLayoutMode;
   readonly summary?: ReactNode;
   readonly title: ReactNode;
   readonly toolbar?: ReactNode;
@@ -27,12 +35,14 @@ export interface LibraryDetailLayoutProps extends Omit<
 
 export function LibraryDetailLayout({
   actions,
+  attribution,
   backgroundImageUrl = null,
   children,
   className,
   coverAlt,
   coverImageUrl = null,
   description,
+  heroImageUrl = null,
   logoImageUrl = null,
   mode = 'banner',
   summary,
@@ -41,7 +51,13 @@ export function LibraryDetailLayout({
   ...props
 }: LibraryDetailLayoutProps): ReactNode {
   const resolvedMode =
-    mode === 'background' ? 'background' : mode === 'compact' ? 'compact' : 'banner';
+    mode === 'background'
+      ? 'background'
+      : mode === 'compact'
+        ? 'compact'
+        : mode === 'hero-cover'
+          ? 'hero-cover'
+          : 'banner';
 
   return (
     <div
@@ -54,7 +70,18 @@ export function LibraryDetailLayout({
       {...props}
     >
       {toolbar}
-      {resolvedMode === 'background' ? (
+      {resolvedMode === 'hero-cover' ? (
+        <LibraryDetailHeroCover
+          actions={actions}
+          attribution={attribution}
+          coverAlt={coverAlt}
+          coverImageUrl={coverImageUrl}
+          description={description}
+          heroImageUrl={heroImageUrl ?? backgroundImageUrl}
+          summary={summary}
+          title={title}
+        />
+      ) : resolvedMode === 'background' ? (
         <div className="ui-library-detail-layout__band" data-ui-library-detail-band="true">
           <RecordMediaHero
             alt={coverAlt}
@@ -105,6 +132,93 @@ export function LibraryDetailLayout({
   );
 }
 
+function LibraryDetailHeroCover({
+  actions,
+  attribution,
+  coverAlt,
+  coverImageUrl,
+  description,
+  heroImageUrl,
+  summary,
+  title,
+}: {
+  actions?: ReactNode;
+  attribution?: ReactNode;
+  coverAlt?: string;
+  coverImageUrl: string | null;
+  description?: ReactNode;
+  heroImageUrl: string | null;
+  summary?: ReactNode;
+  title: ReactNode;
+}): ReactNode {
+  const [heroFailed, setHeroFailed] = useState(false);
+  const [coverFailed, setCoverFailed] = useState(false);
+
+  useEffect(() => {
+    setHeroFailed(false);
+  }, [heroImageUrl]);
+
+  useEffect(() => {
+    setCoverFailed(false);
+  }, [coverImageUrl]);
+
+  const media = resolveLibraryDetailHeroCoverMedia({
+    heroImageUrl,
+    coverImageUrl,
+    heroFailed,
+    coverFailed,
+  });
+
+  return (
+    <div className="ui-library-detail-layout__hero-cover" data-ui-library-detail-hero-cover="true">
+      <div className="ui-library-detail-layout__band" data-ui-library-detail-band="true">
+        <RecordMediaHero
+          alt={coverAlt}
+          className={cx(
+            'ui-library-detail-layout__band-media',
+            media.bandKind === 'atmosphere' && 'ui-library-detail-layout__band-media--atmosphere',
+          )}
+          data-atmosphere={media.bandKind === 'atmosphere' ? 'true' : undefined}
+          fallbackIcon="library"
+          imageUrl={media.bandImageUrl}
+          layout="background"
+          onImageError={() => {
+            if (media.bandKind === 'hero') {
+              setHeroFailed(true);
+            } else if (media.bandKind === 'atmosphere') {
+              setCoverFailed(true);
+            }
+          }}
+        />
+        <div aria-hidden className="ui-library-detail-layout__band-overlay" />
+      </div>
+      <div className="ui-library-detail-layout__hero-cover-body">
+        {media.showPortraitCover ? (
+          <RecordMediaHero
+            alt={coverAlt}
+            className="ui-library-detail-layout__portrait-cover"
+            fallbackIcon="library"
+            imageUrl={media.resolvedCover}
+            layout="compact"
+            onImageError={() => setCoverFailed(true)}
+          />
+        ) : null}
+        <div className="ui-library-detail-layout__hero-content">
+          <div className="ui-library-detail-layout__title">{title}</div>
+          {summary ? <div className="ui-library-detail-layout__summary">{summary}</div> : null}
+          {actions ? <div className="ui-library-detail-layout__actions">{actions}</div> : null}
+          {description ? (
+            <div className="ui-library-detail-layout__description">{description}</div>
+          ) : null}
+          {attribution ? (
+            <div className="ui-library-detail-layout__attribution">{attribution}</div>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
 function LibraryDetailIdentity({
   logoImageUrl,
   summary,

package/src/primitives/library-detail-layout/library-detail-layout.css

@@ -4,6 +4,11 @@
   --shell-library-capsule-list-height: 43px;
   --shell-detail-hero-cover-width: 231px;
   --shell-detail-hero-cover-height: calc(var(--shell-detail-hero-cover-width, 231px) * 43 / 116);
+  --shell-detail-portrait-cover-width: 120px;
+  --shell-detail-portrait-cover-height: 160px;
+  --shell-detail-atmosphere-blur: 18px;
+  --shell-detail-atmosphere-scale: 1.12;
+  --shell-detail-atmosphere-opacity: 0.55;
   --shell-library-detail-logo-size: 56px;
   --shell-library-detail-thumb-width: var(--shell-library-capsule-list-width, 116px);
   --shell-library-detail-thumb-height: var(--shell-library-capsule-list-height, 43px);
@@ -167,3 +172,55 @@
   aspect-ratio: var(--shell-library-capsule-aspect, 116 / 43);
   flex: 0 0 auto;
 }
+
+.ui-library-detail-layout__hero-cover {
+  display: grid;
+  gap: 0;
+  min-width: 0;
+}
+
+.ui-library-detail-layout__hero-cover .ui-library-detail-layout__band {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.ui-library-detail-layout__band-media--atmosphere .ui-record-media-hero__image,
+.ui-library-detail-layout__band-media[data-atmosphere='true'] .ui-record-media-hero__image {
+  opacity: var(--shell-detail-atmosphere-opacity, 0.55);
+  filter: blur(var(--shell-detail-atmosphere-blur, 18px));
+  transform: scale(var(--shell-detail-atmosphere-scale, 1.12));
+  object-fit: cover;
+}
+
+.ui-library-detail-layout__hero-cover-body {
+  display: flex;
+  gap: 16px;
+  align-items: flex-end;
+  margin-top: -48px;
+  padding: 0 16px 8px;
+  position: relative;
+  z-index: 2;
+}
+
+.ui-library-detail-layout__portrait-cover.ui-record-media-hero--compact {
+  box-sizing: border-box;
+  width: var(--shell-detail-portrait-cover-width, 120px);
+  min-width: var(--shell-detail-portrait-cover-width, 120px);
+  max-width: var(--shell-detail-portrait-cover-width, 120px);
+  height: var(--shell-detail-portrait-cover-height, 160px);
+  min-height: var(--shell-detail-portrait-cover-height, 160px);
+  max-height: var(--shell-detail-portrait-cover-height, 160px);
+  aspect-ratio: auto;
+  flex: 0 0 auto;
+  border: 1px solid
+    var(--shell-color-border-subtle, var(--color-border-subtle, rgba(255, 255, 255, 0.12)));
+  border-radius: var(--shell-radius-sm, 4px);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.28);
+  overflow: hidden;
+}
+
+.ui-library-detail-layout__attribution {
+  color: var(--shell-color-text-subtle, var(--color-text-subtle, var(--color-text-muted)));
+  font-size: var(--shell-font-size-caption, 0.75rem);
+  line-height: 1.4;
+}

package/src/primitives/library-detail-layout/resolve-hero-cover-media.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure media resolution for LibraryDetailLayout `hero-cover` mode.
+ * Implements atmosphere-from-cover when no distinct wide hero URL succeeds.
+ */
+
+export interface ResolveLibraryDetailHeroCoverMediaInput {
+  readonly heroImageUrl?: string | null;
+  readonly coverImageUrl?: string | null;
+  readonly heroFailed?: boolean;
+  readonly coverFailed?: boolean;
+}
+
+export interface ResolvedLibraryDetailHeroCoverMedia {
+  /** Trimmed cover URL when load has not failed. */
+  readonly resolvedCover: string | null;
+  /** Distinct wide hero URL (differs from cover) when load has not failed. */
+  readonly resolvedHero: string | null;
+  /**
+   * Soft backdrop URL when there is no successful distinct hero but cover is
+   * available. Must not be stretched as the sole full-bleed identity cover.
+   */
+  readonly atmosphereUrl: string | null;
+  /** Band media to render: distinct hero, else atmosphere, else null (fallback). */
+  readonly bandImageUrl: string | null;
+  readonly bandKind: 'hero' | 'atmosphere' | 'fallback';
+  readonly showPortraitCover: boolean;
+}
+
+function trimUrl(value: string | null | undefined): string | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed === '' ? null : trimmed;
+}
+
+export function resolveLibraryDetailHeroCoverMedia(
+  input: ResolveLibraryDetailHeroCoverMediaInput,
+): ResolvedLibraryDetailHeroCoverMedia {
+  const coverSource = trimUrl(input.coverImageUrl);
+  const heroSource = trimUrl(input.heroImageUrl);
+  const heroFailed = input.heroFailed ?? false;
+  const coverFailed = input.coverFailed ?? false;
+
+  const resolvedCover = coverSource && !coverFailed ? coverSource : null;
+  const distinctHero = heroSource && coverSource && heroSource === coverSource ? null : heroSource;
+  const resolvedHero = distinctHero && !heroFailed ? distinctHero : null;
+  const atmosphereUrl = !resolvedHero && resolvedCover ? resolvedCover : null;
+
+  if (resolvedHero) {
+    return {
+      resolvedCover,
+      resolvedHero,
+      atmosphereUrl: null,
+      bandImageUrl: resolvedHero,
+      bandKind: 'hero',
+      showPortraitCover: resolvedCover !== null,
+    };
+  }
+
+  if (atmosphereUrl) {
+    return {
+      resolvedCover,
+      resolvedHero: null,
+      atmosphereUrl,
+      bandImageUrl: atmosphereUrl,
+      bandKind: 'atmosphere',
+      showPortraitCover: true,
+    };
+  }
+
+  return {
+    resolvedCover,
+    resolvedHero: null,
+    atmosphereUrl: null,
+    bandImageUrl: null,
+    bandKind: 'fallback',
+    showPortraitCover: false,
+  };
+}