Media Pixel Sampler

Install

Add the @te registry to your components.json once:

{
  "registries": {
    "@te": "https://templateempire.io/r/{name}.json"
  }
}

Then install the component:

npx shadcn@latest add @te/media-pixel-sampler

Usage

"use client";

import { useEffect, useState } from "react";
import { MediaPixelSampler, type MediaPixelSamplerValue } from "@/components/media-pixel-sampler";

// Copy your own admitted PNG to public/media-pixel-sampler/proof.png first.
const path = "/media-pixel-sampler/proof.png";

export function PixelReview() {
  const [blob, setBlob] = useState<Blob | null>(null); // SSR and initial render
  const [value, setValue] = useState<MediaPixelSamplerValue | null>(null);
  useEffect(() => {
    const controller = new AbortController();
    async function load() {
      try {
        const response = await fetch(path, { signal: controller.signal });
        if (!response.ok || !response.body) return;
        const reader = response.body.getReader();
        const parts: Uint8Array<ArrayBuffer>[] = [];
        let size = 0;
        try {
          for (;;) {
            const part = await reader.read();
            if (part.done) break;
            size += part.value.byteLength;
            if (size > 4194304) { await reader.cancel(); return; }
            parts.push(new Uint8Array(part.value));
          }
        } finally { reader.releaseLock(); }
        if (!controller.signal.aborted && size > 0)
          setBlob(new Blob(parts, { type: "image/png" }));
      } catch { /* The original remains available. */ }
    }
    void load();
    return () => controller.abort();
  }, []);
  return <MediaPixelSampler
    source={{ key: "proof-v1", blob, fallbackSrc: path, originalHref: path,
      alt: "Original interface proof with a blue primary action" }}
    value={value} onValueChange={setValue} label="Action colour review"
  />;
}

Props

Customisation

Provide one static noninterlaced PNG with 8-bit RGBA and an explicit sRGB tag; untagged PNGs are unavailable. Before browser decode, the native Blob size and single byte-read length must agree within 1 to 4,194,304 encoded bytes. The bounded admission check requires the PNG signature, exact chunk bounds and CRCs, no more than 1,024 chunks, and no trailing bytes. IHDR must be first, unique and 13 bytes: width and height 1 to 4,096, area at most 4,194,304 pixels, bit depth 8, colour type 6, and compression, filter and interlace values 0. Exactly one one-byte sRGB chunk with rendering intent 0, 1, 2 or 3 must precede IDAT. One or more consecutive IDAT chunks need a positive combined payload; IEND must be unique, last and zero-length. Only IHDR, sRGB, IDAT and IEND are permitted; other metadata or animation chunks are unavailable. This check does not inflate or decode IDAT: the browser must still decode the PNG and return verifiable sRGB RGBA8 readback. The output is canvas readback, not encoded hidden RGB, screen appearance, print colour or a contrast certificate. Alpha zero is a successful transparent sample. Unsupported formats, readback failure and unready bytes show unavailable text. The leaf never downloads an image: supply a Blob in a client effect and keep blob null on SSR. Registry installation delivers source files and utils only. For the two demo examples, separately copy interface-colour-proof.png and transit-marker-alpha-proof.png into your host's public/media-pixel-sampler directory, or use your own admitted PNGs and Blob source. Preserve native Column, Row, Apply, Revert and the original source link. The original link is a native keyboard and no-JavaScript alternative. Four inherited aliases allow a scoped theme without changing data pixels.

.pixel-review {
  --pixel-surface: var(--background);
  --pixel-ink: var(--foreground);
  --pixel-border: color-mix(in oklch, var(--foreground) 55%, var(--background));
  --pixel-focus: var(--ring);
}

/* Add className="pixel-review" or define these on an ancestor. */

Frequently asked questions

Is Media Pixel Sampler free for commercial use?

Yes, for personal and commercial projects under the repository's MIT licence with the Commons Clause condition. Keep the copyright, licence and Commons Clause notices in source. Distributing these components as a component library requires a separate agreement. See LICENCE.md for the full terms.

What do the RGBA numbers and transparent samples mean?

They are decimal browser canvas-sRGB readback bytes for the current accepted source pixel. Partial-alpha rounding and RGB at alpha zero do not recover encoded hidden channels. The sample does not certify display, print or contrast colour. Native fields and the original source link remain available when readback is unavailable.

Are the PNG examples installed automatically?

No. The registry installs the leaf, its private model, the portable demo and utils. Separately copy the two original PNGs into public/media-pixel-sampler, or supply your own eligible assets and Blob in a client component. The demo fetches only its documented root-relative caller paths in the browser; it starts with blob null on SSR.

Related components

• Before After Slider
• Video Chapter Player
• Audio Region Loop