@opensite/img

High‑performance, native‑like dynamic img rendering engine for the OpenSite ecosystem. It accepts a numeric mediaId, fetches the optimal variants from the DashTrack CDN, and renders the best source for the viewer’s device and browser. It wraps the srcset variants list inside a tag and can be treated like a standard html tag.

Key points
- Renders a plain element (no wrapper, no default styles).
- Accepts all native props and ref; drop‑in replacement.
- Chooses the best source: Webp → jpg → png.

---

Installation

Core (required):

``
pnpm install @opensite/img
`

---

Quick Start

Minimal (progressive playback, tiny bundle):

`tsx
import { Image } from '@opensite/img';

export function Hero({ mediaId }: { mediaId: number }) {
return (
mediaId={mediaId}
className="hero-video"
/>
);
}
`

TODO: CONTINUE WRITING OUT DOCS FROM HERE - @opensite/video's README.md below for an example

Upgrade to adaptive streaming only on user interaction (e.g., first play):

`tsx
`

Force adaptive streaming immediately (if available):

`tsx
`

Prefer a progressive codec/size (optional):

`tsx
`

Poster behavior:
- poster={"https://…"} → use provided URL.
- poster={false} → disable poster entirely.
- Poster omitted → auto‑use cover.url from CDN payload if provided.

---

Props

Required
- mediaId: number — DashTrack media record ID used to fetch the media snapshot.

Optional
- cdnHost?: string — Override CDN origin. Default: https://cdn.ing.
- adaptiveStreaming?: boolean — Immediately attach HLS/DASH adapter when applicable.
- streamingOnInteraction?: boolean — Progressive first, upgrade on first play.
- streamingUpgrade?: boolean — Allow upgrades at all (default: true). Set false to force progressive.
- preferCodec?: 'HLS' | 'DASH' | 'WEBM' | 'MP4' — Preferred codec when multiple are present.
- preferSize?: 'tiny' | 'small' | 'medium' | 'large' | 'xlarge' — Preferred progressive size variant.
- poster?: string | false — Poster override or disable; omitted defaults to CDN cover.url.
- onImageData?: (data: ImageData) => void — Callback when CDN payload is loaded.
- All native

Direct src fallback
- You can omit mediaId and provide src to play a direct progressive asset (MP4/WebM). In this mode, no CDN request is performed and streaming adapters are not attached.

Ref
- The component forwards a ref to the underlying

---

CDN Integration

- Default fetch URL: https://cdn.ing/assets/videos/.
- Override origin via cdnHost prop; path shape is fixed by the module.
- The response is cached at the module level to avoid redundant network calls.

Expected payload (subset)
`ts
type ImageData = {
id: number;
cover?: { url: string; width?: number; height?: number };
variants_data: {
variants: {
HLS?: { cdn_master_playlist_url: string; rungs?: { bandwidth?: number; resolution?: string; codecs?: string }[] };
DASH?: { cdn_manifest_url: string; rungs?: { bandwidth?: number; resolution?: string; codecs?: string }[] };
PROGRESSIVE_MP4?: Partial>;
WEBM?: Partial>;
};
};
};
`

---

Source Selection Logic

Order of preference (auto mode)
1. Native HLS (Safari/iOS) via application/vnd.apple.mpegurl.
2. Progressive WebM (modern browsers) by preferred/available size.
3. Progressive MP4 (universal fallback) by preferred/available size.
4. If only streaming manifests exist and not natively supported, attach hls.js or dashjs when allowed.

You can override with preferCodec and preferSize as hints; the component will still ensure the final result is playable on the current browser.

---

Streaming Options

- adaptiveStreaming — Attach streaming adapter immediately if an HLS or DASH manifest exists and the browser needs an adapter.
- streamingOnInteraction — Keep progressive first, then upgrade on first play event (recommended to minimize initial JS).
- streamingUpgrade={false} — Disable all upgrades and stick to progressive assets.

Adapters (dynamic imports)
- HLS (non‑Safari): hls.js via src/streaming/hls-adapter.
- DASH: dashjs via src/streaming/dash-adapter.

These imports happen only when required by the chosen streaming path.

---

Styling & Layout

- The component renders a plain