83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# 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
|
|
|
|
1. **Explicit export surface** — no wildcard `export *`; each symbol explicitly listed.
|
|
2. **`MediaError`** — codes: `MEDIA_LOAD_FAILED`, `MEDIA_FORMAT_UNSUPPORTED`, `MEDIA_SOURCE_NOT_FOUND`.
|
|
3. **No `vi.stubGlobal`** — `fetch` injected via `MediaProvider` `fetchFn` prop.
|
|
4. **Storybook** — every renderer with default, loading, error, playground stories.
|
|
5. **Playwright E2E** — `ImageRenderer` lazy-loads; `VideoRenderer` plays/pauses; `Model3DRenderer` renders canvas.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
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
|
|
```
|