OpenSpec Change: enterprise-react-media

Change ID: enterprise-react-media
Package: @suaveplan/react-media
Category: react
Target path: react/media/react-media
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/react-media.md

Summary

Deliver @suaveplan/react-media on genesis from scratch at enterprise quality. Omnibus React media-rendering library: Media (unified entry point), ImageRenderer, VideoRenderer, AudioRenderer, Model3DRenderer, DocumentRenderer, PictureRenderer, ProgressiveImage, MediaProvider, MediaErrorBoundary, PerformanceDashboard. Hooks for config, error, path, source, variant, lazy-load, adaptive quality, progressive image, service worker. Genesis adds Storybook stories (zero currently exist), replaces vi.stubGlobal('fetch', …) with real DI adapters, and fixes wild-card export surface.

Current-state audit (genesis)

Package does not exist on genesis — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`MediaError`
`@suaveplan/types` (`workspace:^`)	`LoggerLike`
`@suaveplan/react-translate` (`workspace:^`)	i18n
`@suaveplan/timing` (`workspace:^`)	Throttle/debounce
`zod` (`catalog:forms`)	Media config schemas
`@opentelemetry/api` (`catalog:observability`)	`media.load` span

External: @react-three/drei catalog:3d, @react-three/fiber catalog:3d, tslib catalog:build. React 18 peer.

Preserved public API surface

Components: Media, ImageRenderer, VideoRenderer, AudioRenderer, Model3DRenderer, DocumentRenderer, PictureRenderer, ProgressiveImage, MediaProvider, MediaErrorBoundary, PerformanceDashboard, PerformanceBadge.

Hooks: useMediaConfig, useMediaError, useMediaPath, useMediaSource, useMediaVariant, useLazyLoad, useAdaptiveQuality, useProgressiveImage, useServiceWorker.

New additions for genesis

Explicit export surface — no wildcard export *; each symbol explicitly listed.
MediaError — codes: MEDIA_LOAD_FAILED, MEDIA_FORMAT_UNSUPPORTED, MEDIA_SOURCE_NOT_FOUND.
No vi.stubGlobal — fetch injected via MediaProvider fetchFn prop.
Storybook — every renderer with default, loading, error, playground stories.
Playwright E2E — ImageRenderer lazy-loads; VideoRenderer plays/pauses; Model3DRenderer renders canvas.

File layout

react/media/react-media/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    provider/ context/ config/
    components/
      media/ image-renderer/ video-renderer/ audio-renderer/
      model-3d-renderer/ document-renderer/ picture-renderer/
      progressive-image/ error-boundary/ performance-dashboard/
    hooks/
      use-media-config/ use-media-error/ use-media-path/
      use-media-source/ use-media-variant/ use-lazy-load/
      use-adaptive-quality/ use-progressive-image/ use-service-worker/
    utils/
      connection-quality/ image-optimization/ media-cache/
      responsive-images/ style-helpers/
    types/
  e2e/
    media.spec.ts

3.2 KiB Raw Blame History