FRD: Media-Processing Wrapper

Document Summary

Field	Details
Feature Name	Media-Processing Wrapper
Status	Draft
Owner	David Holmes
Contributors	Engineering
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #76, ADR-027 (Default Tech Stack)
Last Updated	2026-05-26
Open Source Libraries	`sharp`, `fluent-ffmpeg`

Introduction

Overview

The Media-Processing Wrapper library provides a vendor-neutral contract for image and video operations: transform URLs, generate thumbnails, retrieve optimization metadata, and handle fallback behavior. The design system already ships media UI components (media.tsx, media-card.tsx), but there is no shared abstraction for the underlying media-processing service. This library bridges that gap so application code can request transforms, thumbnails, and metadata without coupling to Cloudinary, Imgix, or any specific provider.

Goals

Define a common MediaProvider interface for URL-based transforms (resize, crop, format conversion).
Provide a typed thumbnail-generation API with preset sizes and custom dimensions.
Expose optimization metadata (format, dimensions, file size, content type) through a typed schema.
Define fallback behavior when a provider is unavailable or a transform fails.
Ship a mock adapter for testing and a passthrough adapter for development.

Non-Goals

Implementing production Cloudinary, Imgix, or S3 adapters (shipped separately).
Client-side image editing or cropping UI.
Video transcoding or streaming.
CDN configuration or cache invalidation.
File upload (covered by the file-upload recipe).

Scope

In Scope

Area	Description
Media contract	`MediaProvider` interface for `transformUrl`, `thumbnailUrl`, `getMetadata`
Transform options	Typed options for width, height, crop mode, format, quality
Thumbnail presets	Named presets (`sm`, `md`, `lg`, `xl`) with configurable dimensions
Optimization metadata	`MediaMetadata` type: format, width, height, fileSize, contentType
Fallback behavior	Strategy pattern for unavailable providers: return original URL, placeholder, or throw
Mock adapter	In-memory adapter returning predictable URLs for testing
Passthrough adapter	Returns original URLs unchanged for local development
Unit tests	Full coverage of transforms, thumbnails, metadata, and fallback
Documentation	Storybook MDX docs with usage examples

Out of Scope

Area	Reason
Vendor-specific adapters	Shipped separately per provider
File upload	Covered by the file-upload recipe (item #78)
Video transcoding	Different concern requiring specialized infrastructure
CDN/cache configuration	Infrastructure concern
Client-side image editing	UI component concern

Users and Pain Points

User Groups

User	Description	Needs
Frontend developers	Engineers rendering images with transforms in UI components	A consistent API for generating transform URLs regardless of provider
Backend developers	Engineers generating thumbnail URLs in API responses	A typed thumbnail API with presets
Design system maintainers	Engineers maintaining `media.tsx` and `media-card.tsx`	A clean integration point for media processing in existing components

Pain Points

User	Pain Point	Impact
Frontend developers	Transform URL construction is scattered across components with provider-specific string manipulation	Provider lock-in; inconsistent URL patterns; hard to change providers
Backend developers	No shared thumbnail preset definitions; each service defines its own sizes	Inconsistent thumbnail dimensions across products
Design system maintainers	`media.tsx` has no standard way to request optimized images	Components render unoptimized images or duplicate optimization logic

Definitions

Term	Definition
Media provider	An object implementing `MediaProvider` that generates transform URLs for a specific service
Transform URL	A URL that instructs a media service to apply operations (resize, crop, format) to an image
Thumbnail preset	A named size configuration (e.g., `sm: 150x150`, `md: 300x300`)
Optimization metadata	Information about an image: format, dimensions, file size, content type
Fallback strategy	The behavior when a provider cannot process a request: return original URL, use placeholder, or throw
Passthrough adapter	A provider that returns URLs unchanged; useful for local development

Current State

Existing Behavior

The design system ships media.tsx and media-card.tsx components that accept image URLs directly. There is no abstraction for generating transform URLs, requesting thumbnails, or retrieving metadata.

Current Limitations

No shared interface for media transforms; each app constructs provider-specific URLs inline.
No thumbnail preset system; thumbnail sizes are hardcoded per feature.
No fallback behavior when a media provider is unavailable.
No mock adapter for testing image-dependent components.

Existing Workarounds

Developers construct Cloudinary or Imgix URLs manually with string concatenation.
Tests use static image URLs without testing transform logic.
Components accept full URLs, pushing transform responsibility to the consumer.

Proposed Solution

Summary

Ship a TypeScript library (@dmwd/media) exporting a MediaProvider interface, transform and thumbnail types, a metadata schema, fallback strategies, and mock/passthrough adapters.

Key Capabilities

MediaProvider interface with transformUrl, thumbnailUrl, and getMetadata methods.
TransformOptions type: { width?, height?, crop?, format?, quality? }.
ThumbnailPreset type with named sizes and a custom(width, height) builder.
MediaMetadata type: { format, width, height, fileSize, contentType, blurhash? }.
FallbackStrategy type: 'original' | 'placeholder' | 'throw'.
MockMediaProvider returning predictable, assertion-friendly URLs.
PassthroughMediaProvider returning original URLs unchanged.

User Experience

Not directly applicable. Indirectly, users see faster-loading, correctly-sized images because the library enables consistent optimization.

Developer Experience

Developers inject a MediaProvider and call provider.transformUrl(src, { width: 800, format: 'webp' }) to get an optimized URL. Components like media.tsx can accept a provider prop or use a context. In tests, MockMediaProvider returns deterministic URLs. In local dev, PassthroughMediaProvider skips transforms.

Requirements

ID	Requirement	Priority	Notes
FR-001	The library must export a `MediaProvider` interface	Must	Core contract
FR-002	The library must export `TransformOptions` and `ThumbnailPreset` types	Must	Typed transforms
FR-003	The library must export a `MediaMetadata` type	Must	Optimization info
FR-004	The library must ship `MockMediaProvider` and `PassthroughMediaProvider`	Must	Testing and dev
FR-005	The library must support configurable fallback strategies	Must	Resilience
FR-006	The library should export a `MediaContext` React provider for component integration	Should	DX convenience

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	`transformUrl(src, options)` returns a new URL with the requested transforms applied	Consistent transform API	Must
FUNC-002	`thumbnailUrl(src, preset)` returns a URL for the specified thumbnail preset	Easy thumbnail generation	Must
FUNC-003	`getMetadata(src)` returns `MediaMetadata` for the given source	Components can render placeholders with correct aspect ratios	Should
FUNC-004	Thumbnail presets include `sm` (150x150), `md` (300x300), `lg` (600x600), `xl` (1200x1200)	Consistent sizing across products	Must
FUNC-005	`TransformOptions` supports `width`, `height`, `crop` (`fill`, `fit`, `cover`), `format` (`webp`, `avif`, `jpeg`, `png`), and `quality` (1-100)	Full transform control	Must
FUNC-006	When fallback is `'original'`, return the unmodified source URL on provider failure	Graceful degradation	Must
FUNC-007	When fallback is `'placeholder'`, return a configurable placeholder URL on provider failure	Visual feedback that something went wrong	Must
FUNC-008	When fallback is `'throw'`, throw a typed `MediaTransformError` on provider failure	Callers can handle errors explicitly	Must
FUNC-009	`MockMediaProvider.transformUrl` returns a URL containing the transform parameters as query strings	Tests can assert on requested transforms	Must

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Zero runtime dependencies (core library)	Maintainability	Must
NFR-002	React context provider is a separate entry point (`@dmwd/media/react`) to keep the core framework-agnostic	Compatibility	Must
NFR-003	All public types exported from package entry point	Maintainability	Must
NFR-004	`transformUrl` and `thumbnailUrl` must be synchronous (URL construction only)	Performance	Must
NFR-005	Bundle size under 3 KB minified + gzipped (core, excluding React provider)	Performance	Should

API / Interface Requirements

Public API

Name	Type	Description	Required
`MediaProvider`	`interface`	`transformUrl`, `thumbnailUrl`, `getMetadata`	Yes
`TransformOptions`	`type`	`{ width?, height?, crop?, format?, quality? }`	Yes
`ThumbnailPreset`	`type`	`'sm' \| 'md' \| 'lg' \| 'xl' \| { width: number; height: number }`	Yes
`MediaMetadata`	`type`	`{ format, width, height, fileSize, contentType, blurhash? }`	Yes
`FallbackStrategy`	`type`	`'original' \| 'placeholder' \| 'throw'`	Yes
`MediaTransformError`	`class`	Error with `src`, `options`, and `cause`	Yes
`MockMediaProvider`	`class`	Predictable URLs for testing	Yes
`PassthroughMediaProvider`	`class`	Returns original URLs	Yes
`THUMBNAIL_PRESETS`	`const`	Map of preset names to dimensions	Yes

Example Usage

import { type MediaProvider, PassthroughMediaProvider, THUMBNAIL_PRESETS } from "@dmwd/media";

const provider: MediaProvider = new PassthroughMediaProvider();

// Transform
const optimized = provider.transformUrl("/images/hero.jpg", {
  width: 800,
  format: "webp",
  quality: 80,
});

// Thumbnail
const thumb = provider.thumbnailUrl("/images/hero.jpg", "md");
// Returns URL for 300x300 thumbnail

// Custom thumbnail
const custom = provider.thumbnailUrl("/images/hero.jpg", { width: 400, height: 250 });

API Notes

transformUrl and thumbnailUrl are synchronous; they construct URLs, not fetch images.
getMetadata is async because it may require a network call to the provider.
The React context provider (MediaContext) is in a separate entry point to keep the core usable in non-React environments.
MockMediaProvider encodes transform parameters in the returned URL for test assertions.

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Library must not interfere with `alt` text on images	Transform URLs must not strip or alter alt text handling
A11Y-002	Placeholder fallback images should have appropriate alt text guidance in docs	Document that consumers must provide alt text for placeholders

Checklist

Keyboard support is defined. (N/A — no interactive UI)
Focus behavior is defined. (N/A — no interactive UI)
Screen reader behavior is defined. (N/A — no interactive UI)
Color contrast requirements are met. (N/A — no UI)
Reduced motion behavior is considered. (N/A — no animation)
Semantic HTML expectations are documented. (Consumers handle <img> semantics)
ARIA usage is defined only where needed. (N/A — no UI)

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	API reference with all exported types, classes, and constants	Storybook MDX	Must
DOC-002	Quick start guide with transform and thumbnail examples	Storybook MDX	Must
DOC-003	Integration guide for existing `media.tsx` and `media-card.tsx`	Storybook MDX	Must
DOC-004	Fallback strategy guide	Storybook MDX	Must
DOC-005	Guide for building a vendor adapter (Cloudinary, Imgix)	Storybook MDX	Should
DOC-006	Testing guide with MockMediaProvider	Storybook MDX	Must

Documentation Should Include

Overview and provider pattern explanation
Installation and import
Transform URL construction
Thumbnail presets and custom sizes
Fallback strategies
React context integration
Testing with MockMediaProvider
Building a vendor adapter
Integration with existing media components

Dependencies

Dependency	Type	Owner	Status	Notes
TypeScript 5.x	Engineering	David Holmes	Ready	Build toolchain
Vitest	Engineering	David Holmes	Ready	Test runner
React 18+	Engineering	David Holmes	Ready	Peer dependency for `@dmwd/media/react` only
`media.tsx`, `media-card.tsx`	Design System	David Holmes	Ready	Existing components to integrate with

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Generic interface may not expose all vendor-specific features	Some transforms (face detection, AI cropping) may not fit	Use `metadata` or `extra` fields for vendor extensions
Synchronous `transformUrl` assumes URL-based transforms	Some providers require API calls for transforms	Document that providers needing async transforms should use `getMetadata` or a separate async method
Thumbnail presets may not fit all use cases	Different products may need different default sizes	Presets are exported as constants; consumers can define their own
PassthroughMediaProvider may mask issues in development	Transforms work in prod but are untested in dev	Document that MockMediaProvider is better for catching transform issues in tests

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should `transformUrl` accept a `srcSet` option for responsive images?	David Holmes	Open	—
Q-002	Should `MediaMetadata` include a `blurhash` field for placeholder rendering?	David Holmes	Open	—
Q-003	Should the React provider support SSR with server-side metadata fetching?	David Holmes	Open	—
Q-004	Should we define a `MediaAsset` type that bundles URL + metadata for richer component integration?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	`MediaProvider` interface is exported with `transformUrl`, `thumbnailUrl`, `getMetadata`	FR-001
AC-002	`transformUrl(src, { width: 800, format: 'webp' })` returns a URL reflecting those transforms	FUNC-001
AC-003	`thumbnailUrl(src, 'md')` returns a URL for a 300x300 image	FUNC-002
AC-004	Custom thumbnail `thumbnailUrl(src, { width: 400, height: 250 })` works	FUNC-002
AC-005	Fallback `'original'` returns the source URL when provider fails	FUNC-006
AC-006	Fallback `'throw'` throws `MediaTransformError` when provider fails	FUNC-008
AC-007	`MockMediaProvider` encodes transforms in the returned URL	FUNC-009
AC-008	All public types re-exported from package index	NFR-003
AC-009	Unit tests pass covering transforms, thumbnails, metadata, and all fallback strategies	FR-001 through FR-005
AC-010	Storybook MDX docs render without errors	DOC-001

LLM Handoff Instructions

Expected LLM Behavior

Follow the requirements and acceptance criteria in this document.
Do not expand scope beyond the In Scope section.
Respect the Out of Scope section.
transformUrl and thumbnailUrl must be synchronous (pure URL construction).
getMetadata must be async.
Keep the React provider in a separate entry point (@dmwd/media/react).
The mock adapter must encode parameters in the URL for test assertions (e.g., mock://image?w=800&fmt=webp).
Integrate with existing media.tsx and media-card.tsx where natural, but do not refactor those components.

LLM Should Not

Invent undocumented product behavior.
Implement vendor-specific adapters (Cloudinary, Imgix).
Add image processing dependencies (sharp, jimp).
Change unrelated components.
Fetch actual images in tests.
Make transformUrl async.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Synchronous `transformUrl` and `thumbnailUrl`	URL construction should not require async; keeps components simple	David Holmes
2026-05-26	Separate React provider entry point	Core library stays framework-agnostic	David Holmes
2026-05-26	Three fallback strategies (original, placeholder, throw)	Covers graceful degradation, visual feedback, and explicit error handling	David Holmes
2026-05-26	Four named thumbnail presets	Standardizes common sizes; custom sizes are still supported	David Holmes

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft