@workbench-kit/react 0.0.2-prototype.0.2.2 → 0.0.2-prototype.0.2.21

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/index.ts

@@ -1 +1,6 @@
 export * from './LibraryDetailLayout';
+export {
+  resolveLibraryDetailHeroCoverMedia,
+  type ResolveLibraryDetailHeroCoverMediaInput,
+  type ResolvedLibraryDetailHeroCoverMedia,
+} from './resolve-hero-cover-media.js';

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,
+  };
+}

package/src/primitives/library-facet-filter-panel/LibraryFacetFilterPanel.tsx

@@ -38,7 +38,7 @@ export interface LibraryFacetSection {
    * Uncontrolled initial collapsed state when `collapsibleSections` is true.
    * When omitted, sections start expanded.
    */
-  readonly defaultCollapsed?: boolean | undefined;
+  readonly defaultCollapsed?: boolean;
   readonly fields: ReadonlyArray<LibraryFacetField>;
   readonly id: string;
 }
@@ -46,33 +46,33 @@ export interface LibraryFacetSection {
 export interface LibraryFacetFilterPanelLabels {
   readonly clearAll: string;
   readonly clearChipAria: (chipLabel: string) => string;
-  readonly empty?: string | undefined;
+  readonly empty?: string;
   /** Aria/placeholder for searchable facet input. Default: "Search options". */
-  readonly filterOptions?: string | undefined;
+  readonly filterOptions?: string;
   /** Shown when option filter matches nothing. Default: "No matching options". */
-  readonly noMatchingOptions?: string | undefined;
+  readonly noMatchingOptions?: string;
 }
 
 export interface LibraryFacetFilterPanelProps {
-  readonly activeChips?: ReadonlyArray<LibraryFacetActiveChip> | undefined;
-  readonly className?: string | undefined;
+  readonly activeChips?: ReadonlyArray<LibraryFacetActiveChip>;
+  readonly className?: string;
   /**
    * When true, section headers toggle collapse.
    * Default false — keeps all sections expanded.
    */
-  readonly collapsibleSections?: boolean | undefined;
-  readonly description?: string | undefined;
+  readonly collapsibleSections?: boolean;
+  readonly description?: string;
   readonly labels: LibraryFacetFilterPanelLabels;
   /** Required when `showActiveChips` is true (chip strip Clear). Host may own Clear otherwise. */
-  readonly onClearAll?: (() => void) | undefined;
-  readonly onRemoveChip?: ((chipId: string) => void) | undefined;
+  readonly onClearAll?: () => void;
+  readonly onRemoveChip?: (chipId: string) => void;
   readonly onToggleFacetValue: (
     fieldId: string,
     value: string,
     kind: LibraryFacetFieldKind,
   ) => void;
   readonly resolveFieldLabel: (fieldId: string) => string;
-  readonly resolveSectionLabel?: ((sectionId: string) => string) | undefined;
+  readonly resolveSectionLabel?: (sectionId: string) => string;
   readonly sections: ReadonlyArray<LibraryFacetSection>;
   readonly selectedValues: Readonly<Record<string, readonly string[]>>;
   /**
@@ -80,7 +80,7 @@ export interface LibraryFacetFilterPanelProps {
    * selection). Hosts should place Clear in their own header chrome.
    * Default true for backward compatibility.
    */
-  readonly showActiveChips?: boolean | undefined;
+  readonly showActiveChips?: boolean;
 }
 
 function sectionHasSelection(

package/src/primitives/library-facet-filter-strip/LibraryFacetFilterStrip.tsx

@@ -26,7 +26,7 @@ export type LibraryFacetFieldKind = 'single-select' | 'multi-select';
 export type LibraryFacetFieldPresentation = 'checklist' | 'searchable-multi';
 
 export interface LibraryFacetFieldOption {
-  readonly count?: number | undefined;
+  readonly count?: number;
   readonly label: string;
   readonly value: string;
 }
@@ -43,7 +43,7 @@ export interface LibraryFacetField {
    * Panel presentation hint. When omitted, long multi-select lists use
    * `searchable-multi` and short lists use `checklist`.
    */
-  readonly presentation?: LibraryFacetFieldPresentation | undefined;
+  readonly presentation?: LibraryFacetFieldPresentation;
 }
 
 export interface LibraryFacetActiveChip {
@@ -61,9 +61,9 @@ export interface LibraryFacetFilterStripProps {
    * When set with `onOpenMoreFilters`, replaces cascade show-more/less with a
    * menu item that opens the fuller facet panel/dialog.
    */
-  readonly moreFiltersLabel?: string | undefined;
+  readonly moreFiltersLabel?: string;
   readonly onClearAll: () => void;
-  readonly onOpenMoreFilters?: (() => void) | undefined;
+  readonly onOpenMoreFilters?: () => void;
   readonly onShowLess: () => void;
   readonly onShowMore: () => void;
   readonly onToggleFacetValue: (

package/src/primitives/number-input/NumberInput.tsx

@@ -17,16 +17,16 @@ export interface NumberInputProps extends Omit<
   TextInputProps,
   'defaultValue' | 'onValueChange' | 'type' | 'value'
 > {
-  defaultValue?: number | undefined;
+  defaultValue?: number;
   /**
    * When true, `undefined` renders as an empty field. Clearing the input calls
    * `onEmptyValue` (preferred) instead of `onValueChange`.
    */
-  nullable?: boolean | undefined;
+  nullable?: boolean;
   /** Fired when a nullable field is cleared. */
-  onEmptyValue?: (() => void) | undefined;
-  onValueChange?: ((value: number, event: ChangeEvent<HTMLInputElement>) => void) | undefined;
-  value?: number | undefined;
+  onEmptyValue?: () => void;
+  onValueChange?: (value: number, event: ChangeEvent<HTMLInputElement>) => void;
+  value?: number;
 }
 
 function resolveStep(step: TextInputProps['step']): number {

package/src/primitives/record-media-hero/RecordMediaHero.tsx

@@ -9,12 +9,14 @@ import { WorkbenchMediaSlot } from '../workbench-media-slot';
 export type RecordMediaHeroLayout = 'banner' | 'compact' | 'background';
 
 export interface RecordMediaHeroProps extends ComponentPropsWithRef<'div'> {
-  alt?: string | undefined;
-  fallbackIcon?: string | undefined;
-  imageUrl?: string | null | undefined;
-  layout?: RecordMediaHeroLayout | undefined;
-  logoUrl?: string | null | undefined;
-  maxWidth?: number | string | undefined;
+  alt?: string;
+  fallbackIcon?: string;
+  imageUrl?: string | null;
+  layout?: RecordMediaHeroLayout;
+  logoUrl?: string | null;
+  maxWidth?: number | string;
+  /** Forwarded when the primary hero/cover image fails to load. */
+  onImageError?: () => void;
 }
 
 function resolveMaxWidth(maxWidth: number | string | undefined): CSSProperties['maxWidth'] {
@@ -33,6 +35,7 @@ export function RecordMediaHero({
   layout = 'banner',
   logoUrl = null,
   maxWidth,
+  onImageError,
   style,
   ...props
 }: RecordMediaHeroProps) {
@@ -66,6 +69,7 @@ export function RecordMediaHero({
         imageClassName="ui-record-media-hero__image"
         imageUrl={imageUrl}
         loading="eager"
+        onImageError={onImageError}
       />
       {logoMedia.shouldShowImage ? (
         <img

package/src/primitives/scroll-area/ScrollArea.tsx

@@ -19,11 +19,11 @@ export type ScrollAreaOrientation = 'both' | 'horizontal' | 'vertical';
 export type ScrollAreaScrollbarVisibility = 'auto' | 'hidden' | 'overlay';
 
 export interface ScrollAreaProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
-  as?: ElementType | undefined;
-  children?: ReactNode | undefined;
-  gutter?: ScrollAreaGutter | undefined;
-  orientation?: ScrollAreaOrientation | undefined;
-  scrollbars?: ScrollAreaScrollbarVisibility | undefined;
+  as?: ElementType;
+  children?: ReactNode;
+  gutter?: ScrollAreaGutter;
+  orientation?: ScrollAreaOrientation;
+  scrollbars?: ScrollAreaScrollbarVisibility;
 }
 
 type OverlayThumb = {

package/src/primitives/scroll-area-infinite-load/useScrollAreaInfiniteLoad.ts

@@ -3,13 +3,13 @@ import { useEffect, useRef, type RefObject } from 'react';
 const DEFAULT_ROOT_MARGIN = '0px 0px 120px 0px';
 
 export interface UseScrollAreaInfiniteLoadOptions {
-  enabled?: boolean | undefined;
+  enabled?: boolean;
   hasMore: boolean;
-  isLoading?: boolean | undefined;
-  isLoadingMore?: boolean | undefined;
+  isLoading?: boolean;
+  isLoadingMore?: boolean;
   onLoadMore: () => void | Promise<void>;
-  rootMargin?: string | undefined;
-  scrollAreaRef?: RefObject<HTMLElement | null> | undefined;
+  rootMargin?: string;
+  scrollAreaRef?: RefObject<HTMLElement | null>;
 }
 
 export interface UseScrollAreaInfiniteLoadResult {

package/src/primitives/searchable-multi-select/SearchableMultiSelect.tsx

@@ -25,24 +25,24 @@ import {
 } from './overlay';
 
 export interface SearchableMultiSelectOption {
-  readonly count?: number | undefined;
-  readonly disabled?: boolean | undefined;
+  readonly count?: number;
+  readonly disabled?: boolean;
   readonly label: string;
   readonly value: string;
 }
 
 export interface SearchableMultiSelectProps {
   readonly 'aria-label'?: string | undefined;
-  readonly className?: string | undefined;
-  readonly disabled?: boolean | undefined;
+  readonly className?: string;
+  readonly disabled?: boolean;
   /** Shown when the query matches no options. Default: "No matching options". */
-  readonly emptyMessage?: string | undefined;
+  readonly emptyMessage?: string;
   /** Aria label for dismissible selected chips. Default: "Remove {label}". */
-  readonly getRemoveChipAriaLabel?: ((optionLabel: string) => string) | undefined;
+  readonly getRemoveChipAriaLabel?: (optionLabel: string) => string;
   readonly onValueToggle: (value: string) => void;
   readonly options: ReadonlyArray<SearchableMultiSelectOption>;
   /** Search input placeholder. Default: "Search". */
-  readonly searchPlaceholder?: string | undefined;
+  readonly searchPlaceholder?: string;
   readonly selectedValues: readonly string[];
 }
 

package/src/primitives/select/Select.tsx

@@ -16,6 +16,7 @@ import type { ControlWidth } from '../text-input/TextInput';
 import { cxCodicon } from '../../utils/codicon';
 import { cx } from '../../utils/cx';
 import { getEnabledOptionIndex, parseOptions } from './options';
+import { resolvePortalContainer } from '../searchable-multi-select/overlay';
 import { isTriggerVisible, measureOverlayPosition, overlayListboxStyle } from './overlay';
 import type { OverlayPosition, ParsedOption } from './types';
 
@@ -24,19 +25,6 @@ export interface SelectProps extends ComponentPropsWithRef<'select'> {
   onValueChange?: (value: string, event: ChangeEvent<HTMLSelectElement>) => void;
 }
 
-/**
- * Portaling straight to `document.body` escapes the workbench root (`[data-theme-preset]`),
- * which re-declares theme tokens locally and shadows whatever a contributed theme overrides
- * on `document.documentElement`. Prefer themed hosts / overlay roots when present.
- */
-function resolvePortalContainer(trigger: HTMLElement | null): HTMLElement {
-  return (
-    trigger?.closest<HTMLElement>(
-      '[data-theme-preset], [data-theme], .ui-workbench-host-root, .ide-workbench-overlays',
-    ) ?? document.body
-  );
-}
-
 export function Select({
   className,
   controlWidth = 'default',

package/src/primitives/text-area/TextArea.tsx

@@ -7,7 +7,7 @@ type ControlWidth = 'default' | 'wide' | 'full';
 export interface TextAreaProps extends ComponentPropsWithRef<'textarea'> {
   controlWidth?: ControlWidth;
   monospace?: boolean;
-  resize?: CSSProperties['resize'] | undefined;
+  resize?: CSSProperties['resize'];
 }
 
 export function TextArea({

package/src/primitives/text-input/TextInput.tsx

@@ -7,7 +7,7 @@ export type ControlWidth = 'default' | 'wide' | 'full';
 export interface TextInputProps extends ComponentPropsWithRef<'input'> {
   controlWidth?: ControlWidth;
   monospace?: boolean;
-  onValueChange?: ((value: string, event: ChangeEvent<HTMLInputElement>) => void) | undefined;
+  onValueChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
 }
 
 export function TextInput({

package/src/primitives/workbench-media-slot/WorkbenchMediaPlaceholder.tsx

@@ -4,8 +4,8 @@ import { cxCodicon } from '../../utils/codicon';
 import { cx } from '../../utils/cx';
 
 export interface WorkbenchMediaPlaceholderProps extends ComponentPropsWithRef<'span'> {
-  icon?: string | undefined;
-  iconClassName?: string | undefined;
+  icon?: string;
+  iconClassName?: string;
 }
 
 /**

package/src/primitives/workbench-media-slot/WorkbenchMediaSlot.tsx

@@ -6,20 +6,22 @@ import { useWorkbenchMediaImage } from '../../utils/useWorkbenchMediaImage';
 import { WorkbenchMediaPlaceholder } from './WorkbenchMediaPlaceholder';
 
 export interface WorkbenchMediaSlotProps extends Omit<ComponentPropsWithRef<'span'>, 'children'> {
-  alt?: string | undefined;
-  as?: 'div' | 'span' | undefined;
-  fallback?: ReactNode | undefined;
-  fallbackClassName?: string | undefined;
-  fallbackIcon?: string | undefined;
+  alt?: string;
+  as?: 'div' | 'span';
+  fallback?: ReactNode;
+  fallbackClassName?: string;
+  fallbackIcon?: string;
   /** Stretch to fill the parent box (hero/cover surfaces). */
-  fill?: boolean | undefined;
-  imageClassName?: string | undefined;
-  imageUrl?: string | null | undefined;
+  fill?: boolean;
+  imageClassName?: string;
+  imageUrl?: string | null;
   /**
    * Native image loading hint. Defaults to `lazy` for list/thumbnail surfaces.
    * Pass `eager` for above-the-fold heroes and detail identity art.
    */
-  loading?: 'eager' | 'lazy' | undefined;
+  loading?: 'eager' | 'lazy';
+  /** Optional host callback after the slot marks the current URL as failed. */
+  onImageError?: () => void;
 }
 
 export function WorkbenchMediaSlot({
@@ -33,6 +35,7 @@ export function WorkbenchMediaSlot({
   imageClassName,
   imageUrl = null,
   loading = 'lazy',
+  onImageError,
   ...props
 }: WorkbenchMediaSlotProps) {
   const media = useWorkbenchMediaImage(imageUrl);
@@ -47,7 +50,10 @@ export function WorkbenchMediaSlot({
           alt={alt ?? ''}
           className={cx('ui-workbench-media-slot__image', imageClassName)}
           loading={loading}
-          onError={media.onImageError}
+          onError={() => {
+            media.onImageError();
+            onImageError?.();
+          }}
           src={media.imageSrc}
         />
       ) : (