Opticross

Opticross is a developer tool that finds image optimization issues on your website and tells you exactly how to fix them.

It analyzes images across different screen sizes, detects oversized downloads, and generates ready-to-use sizes and srcset recommendations to reduce bandwidth and improve page performance.

Opticross ships as two consumers of one shared analysis engine:

• A Chrome extension — interactive inspect/section-select/full-page scanning in the live DOM.
• A Node CLI — headless, Puppeteer-driven scans for page / section / image targets, suitable for CI or scripting.

AI agents: read cli/SKILL.md first — it documents the CLI's modes, flags, and output shape specifically for agentic use (locator-mode selection, JSON field meanings, a typical audit-and-fix workflow). See also llms.txt.

---

Features

Accurate sizes Generation

Automatically derive production-ready sizes attributes from observed layout data.

Automated srcset Recommendations

Generate optimized image width candidates based on real rendering behavior across multiple breakpoints.

Responsive Image Analysis

Inspect individual images and determine whether delivered assets match their actual rendered dimensions.

Full-Page Auditing

Scan entire pages to identify oversized images, bandwidth waste, and responsive image optimization opportunities.

Multiple Scan Modes

• Single Image Analysis
• Selected Area Scanning
• Full Page Audit

High-DPI Detection

Identify images that may appear blurry on Retina and high-density displays.

---

Screenshots

Overview

Single Image Analysis

Selected Area Scanning

Full-Page Audit

Export Formats

---

Chrome Extension

Install from the Chrome Web Store: Opticross on Chrome Web Store.

Or load it unpacked for development: chrome://extensions → enable Developer mode → Load unpacked → select the repo root (manifest.json lives at the top level).

---

CLI

Install from npm: opticross on npm.

The CLI runs the same scanning and recommendation engine headlessly via Puppeteer — no browser extension required. Useful for CI checks, scripting, or auditing pages you don't have open.

Install

cd cli && npm install

Usage

node index.js page    <url> [flags]
node index.js section <url> --selector "#id" | --section "Label" [flags]
node index.js image   <url> --selector ".hero img" | --src "hero.webp" [flags]

• page — scans every image on the page.
• section — scans images within a CSS selector (--selector) or a named landmark/heading section (--section).
• image — scans a single image, targeted by CSS selector (--selector) or matching src/filename (--src).

Flags

Flag	Description
--format json|csv|md	Export format (default: md)
--output <file>	Write to a file instead of stdout
--ai-context	Enable full AI context (DOM path + semantic hints)
--strict-path	Enable strict CSS DOM path only
--semantic-context	Enable semantic hints only (nearest heading, alt text, component class)
--dpr-mode standard|custom	DPR mode (default: standard; passing --dpr alone implies custom)
--dpr <number>	Device pixel ratio, required for --dpr-mode custom
--fix-plan	Include ImageMagick quick-fix commands (Markdown output only)
--select all|needs-optimization	Which scanned images to export (default: all)
--include-implemented	With --select needs-optimization, also include images whose sizes already matches our recommendation
--debug	Launch a visible (non-headless) browser window

--select needs-optimization drops images that are already fine, and drops images whose sizes attribute already matches our recommendation (sizesAlreadyOptimized) — pass --include-implemented to keep the latter in the export anyway. Note: an image can still show nonzero wastePercent even when sizesAlreadyOptimized is true — that gap is expected (the fix only offers a handful of discrete srcset widths, not a perfectly continuous match), not a sign the fix wasn't applied correctly.

Example

node index.js page https://example.com --format md --ai-context --output report.md

# Image Optimization Report

URL: https://example.com/
Generated: 2026-07-04T12:05:34.328Z

---

## hero.png

**URL**: https://example.com/hero.png

**Dimensions**:
- Rendered: 304x192px
- Natural: 1920x1440px

**Analysis**:
- Waste: 98%
- Saved: 1759181 bytes

**Recommended sizes**:
sizes="(max-width: 768px) 87vw, (max-width: 1024px) 40vw, (max-width: 1440px) 30vw, (max-width: 1920px) 21vw, 16vw"

**Recommended srcset widths**:
320w

The CLI is designed around a single orchestration entry point (cli/runner.js#run(opts)), separated from argument parsing so it can be called programmatically — e.g. from a future MCP server — without going through the CLI at all.

---

The Problem

Responsive images depend on correctly configured sizes attributes so browsers can request appropriately sized assets.

Determining those values manually is difficult because image dimensions change across breakpoints, layouts evolve over time, and responsive behavior often depends on complex CSS rules.

As a result, many websites deliver images that are significantly larger than necessary, causing:

• Increased bandwidth usage
• Slower page loads
• Higher CDN costs
• Poor Core Web Vitals
• Reduced mobile performance

Opticross bridges this gap by analyzing actual rendering behavior and generating implementation-ready recommendations instead of simply reporting issues.

---

How It Works

The sections below describe the browser extension's scanning approach, which must simulate viewports without disturbing the live page the user is looking at. The CLI doesn't have that constraint — it drives a real headless Puppeteer viewport and resizes it directly per breakpoint, so it skips the iframe sandbox and asset-matching steps entirely. Both adapters feed the same RawMeasurement shape into the shared recommendation engine, so results are consistent either way.

The extension uses an out-of-band rendering architecture to simulate responsive layouts without disrupting the user's browsing experience.

[DOM Stabilization]
          │
          ▼
[Deterministic Matching]
          │
          ▼
[Throttled Processing]
          │
          ▼
[Responsive Calculations]
          │
          ▼
[Optimization Recommendations]

Hidden Rendering Sandbox

A detached invisible iframe mirrors the current page and performs viewport simulations independently from the active browsing session.

This allows image measurements across multiple screen sizes without causing visual flashes or layout shifts.

Deterministic Asset Matching

Images discovered inside the sandbox must be accurately mapped back to their live counterparts.

A multi-stage matching system is used:

CSS Selector
    ↓
Absolute URL
    ↓
currentSrc
    ↓
Relative Path
    ↓
CDN Parameter Decoding
    ↓
Filename Matching
    ↓
Alt Text Tokens

This ensures assets remain identifiable even when pages contain dynamic content, lazy loading, or client-side rendering.

Page Stabilization

Many websites defer image loading until elements enter the viewport.

Before auditing begins, the tool performs an automated scroll and hydration sequence to ensure deferred assets are fully loaded and measurable.

Fault-Isolated Scanning

Every image audit executes independently.

Failures such as:

• CORS restrictions
• Broken URLs
• Rendering exceptions
• Network failures

are isolated and converted into local metrics without affecting the overall scan.

Concurrency Control

A throttled execution pool limits concurrent image processing operations.

This prevents:

• CPU spikes
• Excessive memory pressure
• Main-thread blocking
• Garbage collection thrashing

while maintaining efficient throughput.

Deferred Calculation Pipeline

Scanning and analysis are intentionally separated.

Collection Phase
        ↓
Raw Metrics Storage
        ↓
Post-Processing
        ↓
Responsive Recommendation Engine

This architecture minimizes layout thrashing and keeps the user interface responsive during large audits.

---

Generated Recommendations

For every analyzed image, the tool can generate:

• Recommended image widths
• Breakpoint-specific rendering data
• srcset candidates
• Accurate sizes attributes
• Potential bandwidth savings
• High-DPI optimization suggestions

---

Benefits

For Developers

• Eliminates manual sizes calculations
• Generates responsive image recommendations automatically
• Detects hidden bandwidth waste
• Identifies oversized image payloads
• Simplifies responsive image implementation

For Users

• Faster page loads
• Reduced data consumption
• Improved mobile experience
• Better image quality on Retina displays

For Businesses

• Lower CDN costs
• Reduced bandwidth consumption
• Improved Core Web Vitals
• Better SEO performance
• Increased conversion potential through faster loading experiences

---

Ideal Use Cases

Opticross is particularly valuable for:

• E-commerce platforms
• Travel booking websites
• Real estate marketplaces
• Media and publishing platforms
• Portfolio websites
• Photography platforms
• Content-heavy applications

---

Technical Highlights

• Out-of-band iframe rendering engine
• Multi-viewport layout simulation
• Deterministic DOM matching system
• Automated lazy-load hydration
• Fault-isolated image auditing
• Throttled concurrency execution pool
• Deferred calculation architecture
• Responsive image recommendation engine

---

Goal

The goal of Opticross is simple:

Help developers ship images that are only as large as they need to be—nothing more, nothing less.