responsive-image-delivery

name	responsive-image-delivery
description	Audit and optimize adopted web image assets without changing art direction. Use after mockup-to-code or another visual implementation has selected final imagery, especially when pages risk multi-megabyte images, missing intrinsic dimensions, weak LCP delivery, invalid or misleading srcset/sizes, upscaled variants, or absent HTML integration evidence.

Responsive Image Delivery

Turn approved raster assets into measured responsive delivery. Preserve composition, crop, aspect ratio, color profile, and source files.

Workflow

1. Identify the actual page image set and explicitly name every likely LCP asset. Do not guess LCP from filename alone.

2. Record codec support before choosing formats:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/responsive-image-delivery/scripts/media_delivery.py" capabilities
   

3. Generate derivatives only with an explicit output directory. Keep originals outside that directory and never overwrite them:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/responsive-image-delivery/scripts/media_delivery.py" optimize \
     --input public/images/hero.jpg \
     --output-dir public/images/generated \
     --widths 480,768,1024,1440,1920 \
     --formats auto \
     --report work/media-delivery-optimize.json
   

4. Integrate generated files into <picture>/<img>. Derive sizes from the implemented layout at each breakpoint; never use 100vw as an unverified placeholder. Keep width and height attributes at the correct aspect ratio. For LCP images, use fetchpriority="high" and do not use loading="lazy".

5. Audit the real HTML and delivery directory. A pass requires resolved srcset width candidates, a non-empty sizes, intrinsic-ratio evidence, declared LCP behavior, budget compliance, and no upscaling:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/responsive-image-delivery/scripts/media_delivery.py" audit \
     --input public/images/hero.jpg \
     --variant-dir public/images/generated \
     --html out/index.html \
     --lcp public/images/hero.jpg \
     --report work/media-delivery-report.json
   

6. Validate the report against media-delivery-report-v1.schema.json. If inspection or generation cannot run, copy media-delivery-report.blocked.json, fill its blocker, and do not claim pass.

7. After a pass, emit the parent manifest receipt from the mockup work root and store it at specialistReports.mediaDelivery:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/responsive-image-delivery/scripts/media_delivery.py" receipt \
     --report work/media-delivery-report.json --root .
   

   Non-passing reports cannot emit {contract,path,sha256}.

Hard rules

• Preserve every original byte-for-byte. The optimizer hashes each source before and after generation.
• Write derivatives only beneath the explicit --output-dir; refuse conflicting existing files unless --overwrite is passed.
• Resize proportionally with no crop and never emit or declare a candidate wider or taller than its source.
• Treat AVIF/WebP as capability-dependent. Report read/write support and fall back to JPEG for opaque images or PNG for alpha; never relabel bytes with a different extension.
• Apply file-size and dimension budgets to files actually delivered by HTML. Apply the stricter LCP byte budget to every declared LCP candidate.
• Require width descriptors (320w), resolvable candidate files, and truthful descriptor-to-intrinsic-width equality. Do not accept density descriptors as responsive-width evidence.
• Do not change focal point, crop, overlays, lettering, or other art direction. Escalate those changes back to visual design.

Tool contract

scripts/media_delivery.py uses Pillow plus the standard library. Run --help for budget, quality, format, and input options. It emits deterministic, sorted JSON with top-level schemaVersion: media-delivery-report/v1; reports omit timestamps. auto always includes a source-compatible fallback and adds writable AVIF/WebP encoders. Unsupported explicitly requested codecs become blockers while supported outputs remain inspectable.

Run focused tests with:

SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
"$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" -m unittest discover \
  -s "$SKILL_ROOT/responsive-image-delivery/tests" -p 'test_*.py'