Initial Commit

openspec/changes/enterprise-react-media/proposal.md

@@ -0,0 +1,82 @@
+# 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
+```

openspec/changes/enterprise-react-media/tasks.md

@@ -0,0 +1,85 @@
+# Tasks: enterprise-react-media
+
+**Change ID**: enterprise-react-media
+**Package**: `@suaveplan/react-media`
+**Target path**: `react/media/react-media`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/react-translate`, `@suaveplan/timing`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold
+
+- [ ] Create directory tree per proposal layout.
+- [ ] Write `package.json` at `0.1.0` with `"sideEffects": false`, explicit exports map.
+- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/react-translate workspace:^`, `@suaveplan/timing workspace:^`, `@react-three/drei catalog:3d`, `@react-three/fiber catalog:3d`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
+- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
+
+---
+
+## 2. Error codes and types
+
+- [ ] Define `MediaError` extending `SuaveplanError`; codes: `MEDIA_LOAD_FAILED`, `MEDIA_FORMAT_UNSUPPORTED`, `MEDIA_SOURCE_NOT_FOUND`.
+- [ ] Define `MediaConfig`, `MediaVariant`, `MediaSource`, `AdaptiveQualityOptions`, `ServiceWorkerConfig`.
+- [ ] Write Zod `MediaConfigSchema`.
+
+---
+
+## 3. MediaProvider + context
+
+- [ ] `MediaProvider` — accepts `config: MediaConfig`, `fetchFn?: typeof fetch` (default `globalThis.fetch`). Provides all `use*` hooks.
+- [ ] `useMediaConfig`, `useMediaError`, `useMediaPath`, `useMediaSource`, `useMediaVariant` — consume context.
+- [ ] Write tests (no `vi.stubGlobal` — inject mock `fetchFn`) + md.
+
+---
+
+## 4. Hooks
+
+- [ ] `useLazyLoad(ref)` — `IntersectionObserver`-based; returns `isVisible`.
+- [ ] `useAdaptiveQuality(src)` — selects quality tier based on connection type from `connection-quality` util.
+- [ ] `useProgressiveImage(src, placeholder)` — loads full image after placeholder; returns `currentSrc`, `isLoading`.
+- [ ] `useServiceWorker(options)` — registers/unregisters service worker for media caching.
+- [ ] Write tests + md for each. All use real DI, no mocks. `{ timeout: 10000 }`.
+
+---
+
+## 5. Components
+
+For each (`Media`, `ImageRenderer`, `VideoRenderer`, `AudioRenderer`, `Model3DRenderer`, `DocumentRenderer`, `PictureRenderer`, `ProgressiveImage`, `MediaErrorBoundary`, `PerformanceDashboard`, `PerformanceBadge`):
+
+- [ ] Implement with OTel `media.load` span on successful load.
+- [ ] `MediaErrorBoundary` — extends `@suaveplan/react-error-boundary` with media-specific fallback.
+- [ ] Write test + stories (default, loading, error, playground) + md.
+
+---
+
+## 6. Utils
+
+- [ ] `connection-quality/` — `getConnectionQuality(): 'low' | 'medium' | 'high'` using `navigator.connection`. Write test + md.
+- [ ] `image-optimization/` — `generateSrcSet(url, widths[])`, `getOptimalFormat(accept)`. Write test + md.
+- [ ] `media-cache/` — LRU cache for media blobs. Write test + md.
+- [ ] `responsive-images/` — `buildPictureSourceSet(image)`. Write test + md.
+- [ ] `style-helpers/` — aspect-ratio, object-fit helpers. Write test + md.
+
+---
+
+## 7. E2E
+
+- [ ] `e2e/media.spec.ts` — Playwright:
+  - `ImageRenderer` with lazy-load: scroll into view → image loads.
+  - `VideoRenderer`: play button → video plays.
+  - `ProgressiveImage`: placeholder shown immediately, full image loads after.
+
+---
+
+## 8. Verify and publish
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-media` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-media` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/react-media`.
+- [ ] Archive change folder.