imgtune 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,248 @@
+# Changelog
+
+## 0.1.0 (2026-11-03)
+
+- LCP first. Each scanned page reads the largest contentful paint before its first scroll, per viewport. A page's report
+  and the PR comment show one line above its numbers: `LCP image (<viewports>): <file:line>, <KB> served, <KB> fixable`,
+  or `LCP is not an image`. `hints` sorts the LCP image first and prefixes its line with `LCP image (<viewports>):`. The
+  scan JSON gains `lcp` and `lcpViewports` on images, `lcp` on each viewport, and the hints JSON gains `lcp` and `lcpViewports`.
+- `sizes="auto"` awareness. A lazy image whose only fix is its sizes gets an alternative line,
+  `sizes="auto, <proposed>"` (Chrome, Edge, Firefox 150 or later; Safari falls back to the proposed value). The explicit
+  value stays the fix. Eager and LCP images never get it.
+- CDN auto quality. A Cloudinary `q_auto` group whose estimated quality saving is below a tenth of its served bytes is
+  reported as `quality handled by <loader> (q_auto)`, and that saving is not counted. Above it, the hint names the explicit
+  `q_<N>`. A jpeg or png whose format the CDN negotiates (`f_auto`, imgix `auto=format`) gets no format change. The
+  fix record gains `cdnQuality` and `formatHandled`.
+- `images.qualities` cap. The next/image quality targets of a scan (across its pages) are clustered into at most
+  `--max-qualities N` values (default 2, 1 to 4). Each target is raised to the nearest chosen value, so the SSIMULACRA2 bar
+  still holds. The site-level line `next.config: images.qualities: [...]` is printed by `hints`, `scan` and the reports;
+  a usage's estimated quality saving is scaled to its capped value and marked approximate. `--qualities` turns the cap off.
+- The agent skill has a "Fix the images" section: the hints in batches, the LCP image first, the `images.qualities` line
+  once, then a scan again with before and after reported apart. Its description names "fix image sizes", "next/image
+  sizes" and "LCP image".
+- Third-party requests are allowed by default. `--block-third-party` turns the blocking on (scans, rechecks, locate-only,
+  sizes-only, `run` and `check`). Blocking can drop images that a page loads through its own API on another host: on a
+  local store build, 0 images were recorded with blocking and 50 without it. `--allow-host <h1,h2>` now needs
+  `--block-third-party`. `--allow-third-party` is accepted for one release as a no-op with a deprecation note. The
+  recorded setting is `allowed` by default, so a scan from before this change (recorded as `blocked`, or with no record)
+  does not match on `--resume` or `recheck` where the setting differs.
+- `check`: failed pages are counted. A deep page the browser could not load (status `failed`, for example a navigation
+  timeout) gets one retry: the next-heaviest measured page of its route type is scanned in its place, and the report names
+  both. `run.json` has a `failed` count per phase and a `deepRetries` list, `imgtune summary` prints the failed count in its
+  survey and deep lines, and the report's header and "broken, not measured" section count the failed pages.
+- Browser errors in the report and the terminal are one line: ANSI escape sequences are removed whole (`stripControls`), and
+  the Playwright "Call log:" block after the first line is dropped (`errorLine`). The full message stays in the page JSON.
+- Route types (`src/routes.ts`): a version segment after the first segment (`/docs/15/app/...`, `/docs/v2.3/...`) is a
+  dimension when the same section has unversioned pages, so the versions merge with them. Dated archives and numeric ids
+  are not read as versions (see the tests).
+- Route types (`src/routes.ts`): the URLs of a site group into the templates they are instances of. A leading locale or store
+  segment (`ae-en`, `sa_AR`) and a `desktop` or `mobile` variant are dimensions, not part of the type. Product slugs, ids
+  and listing families collapse to `*`, and query strings keep their parameter names (`/search?q=*`). Used by the survey
+  sampler (`--sample-per-pattern`), `run` and `check`. `--route-map <file>` names the URLs that match a pattern (`pattern =>
+  type`, or JSON). A store set of 299 URLs gave 289 patterns with the old grouping; the new grouping is not yet measured on it.
+- Deep selection (`src/deep.ts`): the heaviest page of each route type that has images, by image KB per view (exact KB as the
+  tie-break), with the types ordered by their total KB per view. `--deep <N>` defaults to 20 (was 5). The types the cap leaves
+  out, and the types with no images, are named in the output.
+- `imgtune check <origin | sitemap-url | page-url> | --urls-from <file|sitemap>`: the production check, in a browser only.
+  It surveys at most `--sample-per-pattern N` URLs per route type (default 3), full-scans the heaviest page of each type, and writes
+  `report.md` (header, summary numbers with sharpness as its own number, ranked fixes merged across the deep pages, heavy
+  pages with little to save, sharpness images, a route-type table, what was not measured, and how to read the numbers),
+  `run.json` (the manifest: `imgtune summary` reads it), `survey/`, `deep/` and `urls.txt`. It passes through `--gpu`,
+  `--gpu-device`, `--page-concurrency`, `--qualities`, `--block-third-party`, `--allow-host`, `--idle-timeout`, `--no-cache`,
+  `--ignore-robots` and `--storage-state`. `run` is kept: it also locates on a dev server (`--dev`) and writes the hints.
+- `imgtune audit --app <dir> --prod <origin> [--dev <origin>]`: the deep mode for your own Next.js app. It reads the route
+  files (`app/`, `src/app/`, `pages/`, `src/pages/`) into route patterns, and `images.qualities` from `next.config.{js,mjs,ts}`
+  (a static read; Next's `[75]` is assumed and reported when the list is missing). It surveys `--prod` and full-scans the
+  heaviest page of each route type, as `check` does. With `--dev` it locates those pages' images in the sources, and its
+  `report.md` has the file:line of every located fix and the route file of every route type. A preflight stops the audit
+  when the production home's stylesheets do not load (a CDN host the machine cannot reach: set the CDN variable empty for
+  both `next build` and `next start`). URLs come from `--urls-from`, else the `--prod` sitemap, else a same-origin crawl of
+  the home page two links deep (at most 500 pages, plain HTTP, no browser). See the audit discovery entry below.
+- `imgtune audit` discovery: the crawl starts from the home page and from the app's seeds (its static routes, and each route under a
+  dynamic first segment such as `/[store]/about-us` once per learned value). The values are where the home page redirects, then the
+  other first segments of its links and its `hreflang` alternates, capped by `--max-locales N` (default 3). The crawl takes the groups
+  of first segments in turn, so one locale cannot use up the page budget. A redirect or link is followed only on the exact origin of
+  `--prod` (a redirect to a sibling subdomain is refused). A sitemap or alternate that names another host is read on a local `--prod`
+  instead (path and query kept, the other host never fetched), and the audit says how many URLs it moved. `--urls-from` replaces the
+  discovery and adds no seeds.
+- `imgtune audit` route types are URL templates (`routes.ts`), not route files. The first segment of a URL that the app takes as a
+  dynamic segment, and a `desktop` or `mobile` variant after it, are dimensions. The route file of each type is an attribute and a
+  column of the report's route-type table. A route file that renders several templates gives several types.
+- Scan: the extra fetches (originals, srcset candidates, source maps, robots) are shared across the whole run as before, but a
+  failed fetch, or a body with `Cache-Control: no-store`, is no longer kept for later pages: a later page asks again. No
+  response of the 8-URL nextjs.org run changed.
+- Scan: a lossy image over 2 MP (MATCH_MAX_PIXELS) keeps its resize estimate. Its quality match runs at the fast AVIF effort
+  with at most 5 probes and no effort-4 confirmation, so the estimate is approximate: its record says `estimate: "approx"`
+  and the scan summary, the Markdown report and `imgtune summary` show it with ≈. On nextjs.org/conf the exact + est. share
+  is 94.6% ≈ (the 3840-px images, about 6.5 MB per view of est. saving).
+- Scan: each measured page is written to `<out>/.staged` as soon as it is measured, with its bodies as blobs, and is
+  complete only once its analysis is written. `--resume` after an interruption measures no staged page again and runs
+  only the analysis; the stage folder is removed when the run finishes.
+- `imgtune run <url...> | --urls-from <file|sitemap>` is the whole agent flow in one command: survey every URL, rank the pages
+  by image KB per view per route type, full-scan the heaviest page of each type (`--deep <N>`, default 20), locate
+  them on a dev server (`--dev <origin>`), and group the fix hints by call site (`--qualities`). It writes a run directory
+  (`survey/`, `deep/`, `located/`, `hints.json`, and `run.json`, a manifest that lists every file and every command it ran) and
+  prints a summary of at most 40 lines. The scan passthroughs are `--gpu`, `--gpu-device`, `--page-concurrency`,
+  `--idle-timeout` and `--no-cache`, plus `--root`, `--storage-state` and `--ignore-robots`.
+- `imgtune summary <run dir | scan.json ...>` prints the same one-screen summary again, from a run directory or from scan files.
+- Broken pages: a page whose document answered an HTTP error, whose linked stylesheet did not load, or that finds no images
+  where the survey found some is `broken`, with its reason and the likely fix. A broken page has no page numbers and counts in
+  no total. `scan --fail-on-broken` exits 4. `run` stops before the deep phase when more than half of the survey is broken.
+  A page now records `documentStatus` and `stylesheetHosts` when they apply.
+- Scan: `--survey` is a fast site-wide pass (viewports `iphone-15` and `desktop`, no quality estimate, four pages at once,
+  a 3 s network-idle cap). Its numbers are exact savings only and are labelled so in the scan's output, the Markdown and
+  the report. A survey is recorded in each page's options, so `--resume` and `compare` never mix it with a full scan.
+- Scan: `--page-concurrency <N>` (1 to 6, default 1) scans up to N pages at once on one browser. Results keep the input
+  order and each page's JSON is written as it finishes; `--max-pages` and `--max-images` stop new pages and keep those in
+  flight. The GPU scorer's CPU fallbacks are counted per page.
+- Scan: `--idle-timeout <ms>` (0 to 600000, default 10000) caps the wait for network idle after scroll; 0 skips it.
+- Faster AVIF quality search, same numbers: the search encodes AVIF at effort 2 (`cdn-fast`) and confirms the answer at
+  effort 4 from the qualities that decided it (two or three effort-4 probes). A confirmation that fails moves the fast bar by the
+  score difference seen at that quality and searches again (twice at most); when none confirms, the search runs at effort 4 as
+  before. The reported target and bytes are the effort-4 ones. On the Next.js guard scan the per-image targets and estimated
+  bytes are identical to the previous build, and the scan's CPU time fell from about 247 s to 155 s (shared machine).
+- Scans can block the requests to other sites that cannot change an image or the layout (scripts, fetch and xhr,
+  websockets, event streams, media, beacons and pings, manifests, iframes, other), with `--block-third-party`. Documents,
+  stylesheets, fonts and images are never blocked, from any host. Blocking makes pages reach `load` and network idle sooner.
+  `--allow-host <h1,h2>` keeps named hosts while blocking (for a third-party script that renders images). The page JSON
+  counts the aborted requests (`thirdPartyBlocked`) and records the setting, so `--resume` does not mix settings; a recheck
+  refuses a scan file recorded with the other setting.
+- Scan: `--shared-loads` (opt-in) loads each viewport class (mobile, desktop) once and resizes the open page for the other
+  viewports of the class. It saves CPU but costs wall time (survey: 98.7 s shared against 69.1 s fresh), so the default loads
+  each viewport fresh, as before. The mode is recorded in each page's options (`loads`): `--resume` rescans pages of the other
+  mode and `compare` warns about it.
+- Caller map: a call site whose component is rendered for several callers lists each caller at the first owner level above
+  the image that differs between usages (`callers:` in the grouped `hints`, `callers` in the JSON), with its file:line,
+  pages and its own sizes formula. The dev owner chain is read at `--locate-only` and kept on each located record
+  (`locator.ownerChain`, sanitised on read).
+- Docs: for Next.js, the asset-prefix env must be set the same for `next build` and `next start`; the skill says to check
+  the stylesheets load before a scan.
+- Fix: the GPU scorer no longer overwrites the user's `CUDA_VISIBLE_DEVICES` (a GPU the user excluded could run the scorer).
+  `--gpu-device` is an index within the user's visible list; imgtune never sets `CUDA_DEVICE_ORDER`. The scorer prints the
+  device it opened (name, index, order, visible list) and the scan JSON records `deviceOrder` and `visibleDevices`.
+- Fix: the sizes-only check judges undersize on the measured server's width, computes the chosen candidate from the dev
+  page's `sizes` (and checks it is the file the browser loaded), and reports a dev/measured layout difference as `LAYOUT`
+  (not a pass). It stops with no verdict when the dev page has a stylesheet that did not load.
+- Scans warn when a linked stylesheet did not load (`stylesheetsFailed` on the page): the widths measured on such a page
+  are not the app's. Earlier numbers measured on a page whose utility stylesheet was refused are void.
+- A sizes proposal undersized at any measured viewport is not a saving (the per-image records and the group report).
+  The candidate evaluation moves to `src/candidates.ts`, with a reader for the calc, min, max and clamp forms.
+- `hints --format json` is not cut to the text default of 10: JSON is unlimited unless `--limit` is passed, and carries
+  `truncated`.
+- `imgtune report` accepts `--compare` once per page; the byte totals are summed.
+- A PASS that adds bytes is labelled `PASS (sharpness fix)`; a batch that mixes them with savings prints a `mixed:` line.
+- Security: page-derived text in the sizes output is cleaned of bidi overrides and zero-width marks, and capped.
+
+- CSS background images are measured (`kind: "css-background"` records): every layer of a computed `background-image` that
+  names a file, with its box, `background-size`, the file the browser loaded, the device pixels it needs, undersized, and a
+  local resize estimate. Gradients, inline `data:` images and hidden or tiny elements are skipped with a reason. The headline
+  numbers stay `<img>`-only (the page's `backgrounds` line reports the layers apart). Page-controlled values are capped
+  (4096 characters, 8 layers) and parsed in one pass.
+- A harness route (`/__imgtune/<component>`, or any URL scanned with `--harness`) is measured-harness, not measured-page:
+  its records and report say the component was measured in isolation. The skill's harness step is fixed for App Router
+  (a `%5F_` folder: a plain `_` folder is private) and says to verify with recheck on the harness URL.
+- `scan --locate-only` works on a built page that ships source maps: the owner components' definitions, read through the
+  debugger and mapped by the chunk's source map, give `file:line` with `via: prod-sourcemap` (never verified: the definition
+  is not an image line). The same caps apply. Dev data stays the first choice.
+- Fix: a score the CPU made (a GPU scorer's fallback, or a pair too small for the GPU) is no longer stored under the GPU's
+  cache key. The cache version moves to 2, so entries written before are not read.
+- `imgtune compare <before.json> <after.json>`: the per-image before and after of two scans of one page, paired by URL
+  pattern and alt, and by rendered width where one key has several elements. Saved and added-for-sharpness bytes are two
+  numbers; unpaired images are listed, not counted. Drift is excluded and its totals printed: an image whose rendered
+  width changed (layout changed), the same file served with different bytes (server variance), and a view one scan did
+  not load. Two scans of one build compare to 0 KB saved.
+- Faster scans, same numbers: the quality samples of a scan are estimated two at a time (each encode already uses four
+  threads), and a served file under 2 KB is not swept (`quality.sweep: "skipped-small"` in the JSON). On the nextjs.org
+  guard the JSON is identical to the previous build. Cold CPU scan about 18% faster (median 57.5 s over four runs before,
+  46.9 s over five after).
+- `imgtune scan --recheck` with several pages starts one browser for all of them (it started one per page).
+- `imgtune hints --help` lists `--top`, `--flat` and `--qualities`, and accepts several scan files.
+- Shared and varied call sites get a fitted `sizes`: a linear `vw + px` per band of viewports where the measurements allow,
+  a ceiling constant elsewhere, never below a measured width at any measured viewport. When pages need different widths,
+  the call site says `shared component: pass sizes per caller` and each page gets its own formula. `hints` takes several
+  scan files, so call sites group across pages.
+- A sizes proposal whose predicted outcome adds bytes (or saves none) is not a saving: the scan leaves it out with a
+  `no saving` reason, and `hints` counts it. The prediction uses the candidate each proposed value would pick, per viewport.
+- `imgtune hints --top N`: the N call sites that save the most per view, one line each.
+- Recheck (full and `--sizes-only`) prints one line per image (`PASS`, `FAIL` or `GONE`, predicted and measured bytes) and a
+  batch line; the detail follows only for images that did not pass.
+- `imgtune report`: a Markdown run report from `.imgtune/ledger.jsonl` and the compare JSON. Ledger values are escaped as
+  code in pipe-free table cells.
+
+- Faster scans, same numbers. The AVIF and WebP calibration no longer encodes all 25 local qualities of each match: a
+  parallel search over the coarse grid and then the refine window encodes about half as many, and any probe that shows
+  bytes falling as quality rises falls back to the full scan. Targets and ratios are identical to the previous build on
+  the nextjs.org guard, on its five quality samples and on 25 generated images, with the CPU and with `--gpu`.
+- Result cache in `.imgtune/cache` (bounded to 500 MB, oldest removed first): the local encode sizes and each probe's
+  score, keyed by the original's content hash, width, scorer, encoder, quality, profile and tool version. Used by `scan`,
+  `scan --recheck` and `image`; a warm run reuses everything the cold run computed. `--no-cache` turns it off. Corrupt or
+  foreign entries are ignored.
+- Settle waits only for real document navigations. Same-document URL changes (`history.pushState`, `replaceState`, hash
+  changes) no longer repeat the settle and its 10 s network-idle wait; the wait itself is unchanged.
+- `--root <dir>` (`scan`, `--locate-only`): the folder project sources are read from. By default each file is read from the
+  nearest folder above the cwd that holds it, so a scan run from a sub-folder of a monorepo no longer marks every source
+  `unread`. Unread sources are named in the output with the folder they were looked up in.
+- `scan --recheck` takes several pages (repeat `--recheck`, at most three browser contexts in all) and `--viewports <names>`
+  to measure other viewports than the ones where the images rendered. Its default is unchanged.
+- Security: the `locate` block and the located records of a scan file are checked as a whole when read. A dev URL that is
+  not http or https, an unknown viewport, a count that is not a non-negative integer, or a short label that is not plain
+  text drops the block (the rest of the scan is kept, and the drop is reported). The sizes recheck refuses a non-http dev
+  URL from the file or the command line. `hints` prints the located line only from a checked block.
+
+- Split measure and locate. `scan <built-url>` measures the bytes on a built server or a preview (no source needed).
+  `scan <dev-url> --locate-only --from <scan.json>` reads the React source of the flagged images from a dev page, at one
+  viewport (default `iphone-15`), with no image bytes read and nothing scored. It writes `<scan>.located.json`: the measured
+  file with `file:line` and component joined in, and a `locate` summary (joined, not joined by reason). Elements join on
+  the whole srcset as URL patterns (origin, widths and qualities taken out) and alt, in document order, only when the counts
+  on both sides are equal; a count that differs joins nothing. Scans from before this version (no `domIndex`) cannot be
+  located: scan again.
+- `scan --recheck <file> --sizes-only [--ids ...] [--url <dev-url>]`: the per-batch check on dev, in seconds. Per image and
+  viewport: the `sizes` attribute, the rendered width, the DPR, the candidate chosen and its bytes (Content-Length), undersized,
+  the hint's target, and a verdict. Fails an undersized choice, a choice bigger than the hint's sizes need, and bytes that rose
+  without a sharpness fix. No bytes decoded, nothing scored. The full `--recheck` is unchanged.
+- `hints` on a located file prints where the sources came from, and says how many hinted images still have no `file:line`.
+- The agent skill, its reference and the AGENTS snippet use the four-step flow: measure (built), locate (dev), check each
+  batch (dev, sizes only), measure again (built, the real before and after).
+- `--gpu` and `--gpu-device <n>` (`scan`, `scan --recheck`, `image`): SSIMULACRA2 scoring on an NVIDIA GPU, opt-in. It runs
+  through `imgtune-ssimu2-gpu`, an external program built from `native/ssimulacra2-gpu/` against libvship (Vship). A missing
+  or failing program prints a warning and the run scores on the CPU. Encoding stays on the CPU. On nextjs.org scoring took
+  19 s on the CPU and 1 s on the GPU (a timed scan: 110 s to 89 s on a loaded machine). The quality targets and per-image
+  records of the nextjs.org scan were identical; scores differ by up to 1.2 points on its re-encode pairs.
+- Scan JSON records the scorer: `scorer` on each page and on the summary, and in `resume` options. `scan --recheck` warns when
+  its scorer differs from the scan's.
+- Locator check: a resolved `file:line` is read from the project (local pages only) and must render an image. A call
+  site that only uses the component which renders the image is `kind: owner`, `verified: false`, and hints say which
+  component to search. `kind` is `image`, `owner`, `unread` or `unchecked`. Scan from the project root.
+- Placeholder owner names (such as the app's fallback name) are never searched for or printed as a component; a hint with no clue says
+  `owner unknown`.
+- Recheck pairing: an image's id no longer includes its line, so an edit above it keeps the id. A changed id is paired
+  by source file and URL pattern, and `gone` lists what was looked for and asks for a pristine rescan first. The cause of
+  the earlier false `gone` results was the line in the id, not the `sizes` value.
+- `hints` groups by call site across pages (default; `--flat` for one entry per image). Shared components print each
+  caller's sizes and the rule to follow.
+- `hints --qualities <list>` snaps quality targets to the framework's allowed values and marks the quality saving void
+  after a snap.
+- Savings are split into `sizes` (exact) and `quality` (est.) in the scan records, hints and call sites. Recheck prints the
+  predicted saving beside the measured served bytes.
+- `basis: fit` is kept: it is emitted when the layout formula does not match the measured widths (for example with no
+  layout chain). It is rare, and documented as such.
+
+- `scan` measures the images of live pages in headless Chromium, per view and per viewport, at six viewports. It reports
+  exact and est. byte savings, sharpness growth apart from them, and a SSIMULACRA2 quality check.
+- Per-image fix hints. For each image: its locator (component, `file:line` in dev builds, `data-testid`, `alt`, loader
+  URL pattern), the `sizes` the browser resolved at each viewport, the quality and format targets, and two byte numbers,
+  bytes saved and bytes added for sharpness, which are never netted.
+- `hints <scan.json>` prints the fix hints in batches: `--limit`, `--offset`, filters, and `--format json`.
+- `scan --recheck <scan.json> [--ids a,b,c]` rescans the named images and prints before and after. It exits 1 when an
+  image became undersized, or when bytes rose without a sharpness fix.
+- `scan` at scale: `--urls-from` (a URL list or a sitemap), `--sample-per-pattern`, `--storage-state` for a logged-in
+  session, `--resume`, `--max-pages` and `--max-images`. `--ignore-robots` is for sites the user owns or is authorised to
+  test, and is recorded in the JSON.
+- `image <file|url|glob>` measures image files without a page: their bytes, the lowest quality per format that meets the
+  bar (SSIMULACRA2 90 by default, `--min-score` sets another), and at a `--width` the bytes at each needed width.
+  `--write` writes optimised copies into a folder and never overwrites a file.
+- The `skills/imgtune` agent skill (SKILL.md and reference.md), and `skills/imgtune/AGENTS.snippet.md` for AGENTS.md,
+  CLAUDE.md, Cursor, Codex or Copilot.
+- The composite GitHub Action in `action.yml` scans the pages it is given and comments on the pull request. The comment
+  keeps the summary tables and adds a collapsed "Fix hints for your AI agent" section.
+- Requires Node.js 20.9 or later and Chromium for Playwright.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 indicozy and imgtune contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,20 @@
+imgtune
+
+The SSIM quality measurement (src/ssim.ts) is adapted from Optiq:
+
+  Optiq
+  Copyright 2026 Optiq contributors
+  Licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
+
+The adapted code keeps the original attribution header. Modifications are made for imgtune.
+
+The SSIMULACRA2 WebAssembly module in vendor/ssimulacra2 is built from native/ssimulacra2-wasm, which uses:
+
+  ssimulacra2 0.5.0 (BSD-2-Clause), Copyright (c) 2022-2022, the rav1e contributors
+    The scoring loop (native/ssimulacra2-wasm/src/scorer.rs) and the blur (native/ssimulacra2-wasm/src/blur/) are
+    vendored from it and changed to use less memory. Their file headers carry the full license text. The upstream
+    crate is used only by the tests in native/ssimulacra2-wasm/tests/.
+  yuvxyb 0.4.0 (MIT)
+  wasm-bindgen 0.2.129 (MIT OR Apache-2.0)
+
+Full license texts for all of the above are in THIRD_PARTY_LICENSES.

package/README.md

@@ -1,3 +1,310 @@
-# Temporary Holding Version
+# ImgTune
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/imgtune.svg)](https://www.npmjs.com/package/imgtune)
+
+**ImgTune measures image waste on any live site.**
+
+Website: https://indicozy.github.io/imgtune/ · [Try the demo](https://indicozy.github.io/imgtune/demo) · [Docs](https://indicozy.github.io/imgtune/guide/getting-started)
+
+Lighthouse tells you your images are too big. ImgTune tells you the `sizes`, quality and format to set for each image,
+points at the line of code that renders it (when your dev server is running), and checks each quality target with
+SSIMULACRA2. Your coding agent applies the change, and a rescan checks it.
+
+**Works with your image CDN.** Cloudinary, imgix and `next/image` resize to whatever width `sizes` asks for, so a wrong
+`sizes` is waste that no CDN removes. ImgTune works on top of a CDN, not instead of one. Already on Cloudinary auto
+quality (`q_auto`)? ImgTune focuses on `sizes`, which no CDN can fix for you. A format the CDN picks per request
+(Cloudinary `f_auto`, imgix `auto=format`) is not proposed as a change.
+
+**Built for image-heavy sites:** e-commerce catalogs, media, marketplaces.
+
+## Two ways to measure
+
+- **`npx imgtune check https://your-site`** measures any live site, in a browser, with no source. It reads the site's
+  sitemap, groups the URLs into route types (templates such as product or listing pages), deep-scans the heaviest page of
+  each type at six viewports, and writes a Markdown report, `report.md`.
+- **`npx imgtune audit --app . --prod http://localhost:3000 --dev http://localhost:3001`** is the deep mode for your own
+  Next.js app. It reads the route files and `next.config`, measures the production build, and with `--dev` locates each
+  fix at its `file:line` in the source.
+
+Each page's report shows one line above its numbers for its LCP image (the largest contentful paint element, when it is an
+image). Where `next.config` lists several `images.qualities`, ImgTune clusters them into at most
+`--max-qualities` values (default 2), and each target is raised to the nearest value kept, so the SSIMULACRA2 bar still holds.
+
+## Install
+
+```sh
+npm i -D imgtune
+```
+
+Then run it with `npx imgtune`. Without installing, `npx imgtune` fetches it for one run. ImgTune needs Chromium for
+Playwright; see [Requirements](#requirements).
+
+## Quick start
+
+Measure a live site, with no access to its source:
+
+```sh
+npx imgtune scan https://your-site.example/
+```
+
+The scan writes one JSON file per page to `.imgtune/scan/`, for example `.imgtune/scan/your-site.example-index.json`, and
+prints a count of the images with fix hints. Read the hints in batches of ten:
+
+```sh
+npx imgtune hints .imgtune/scan/your-site.example-index.json
+```
+
+Each hint names the image, its component and `file:line` when they resolve, the `sizes` and quality to use, and the bytes
+the fix saves per view, with the bytes it adds for sharpness shown separately. Run `npx imgtune --help`, or
+`npx imgtune scan --help` for every option.
+
+For the whole site in one report, run `npx imgtune check https://your-site.example/` instead. It writes `report.md` to
+`.imgtune/check/`, and `imgtune summary` prints its one-screen summary.
+
+## Why one lever is not enough
+
+It looks at three levers for each image: **resolution** (the pixels the browser actually needs), **quality** (the
+encoder setting), and **format** (for example AVIF or WebP instead of JPEG). Measurements are per page view, per
+viewport, and quality is scored with SSIMULACRA2.
+
+- **Compressors** squeeze the file you hand them, but never learn how wide it is shown. A 6,000 px logo in a 150 px
+  slot stays 6,000 px, only better compressed.
+- **Image CDNs and `next/image`** resize on request, but only to the widths your `sizes` attribute asks for. A wrong or
+  missing `sizes` makes every phone fetch a file several times too wide.
+- **Lighthouse** flags oversized, poorly encoded and old-format images, at one viewport per run, with a fixed estimate.
+  It tells you something is wrong, not which `sizes` or quality to set.
+- **ImgTune** measures size, quality and format together, per image, on the live page at six viewports, accepts a
+  saving only when SSIMULACRA2 says nobody can see it.
+
+## Fix it with your agent
+
+ImgTune measures; it does not edit your project. The agent skill does the editing: it scans, matches each hint to the
+source, fixes it, verifies with a rescan, and reports from a ledger it keeps in the project.
+
+- **Claude Code**: copy the skill folder into your project. From the project root:
+
+  ```sh
+  mkdir -p .claude/skills && cp -r node_modules/imgtune/skills/imgtune .claude/skills/
+  ```
+
+  Then ask Claude Code to optimise the images of the site. The skill is `.claude/skills/imgtune/SKILL.md`, with a
+  `reference.md` beside it.
+- **Cursor, Codex, Copilot, and other agents**: paste `node_modules/imgtune/skills/imgtune/AGENTS.snippet.md` into your
+  `AGENTS.md` or `CLAUDE.md`. It is the short form of the same loop and rules, and points to `npx imgtune --help`.
+
+The skill works in batches of about ten hints, starting with the LCP image, and writes `.imgtune/ledger.jsonl` (one line
+per image usage). When its context fills, it writes `.imgtune/HANDOFF.md`, so a new session can resume. Use a built or
+preview server for the before and after numbers, and the dev server for the edit loop: source locations only resolve in
+dev builds, or in a built page that ships source maps.
+
+## What `scan` measures
+
+`scan` loads each page in headless Chromium at six viewports (four phones, a 1440 px desktop at 2x, and a 1280 px
+desktop at 1x), scrolls it to the end, and records every image.
+
+- **Exact** savings come from the site's own smaller `srcset` candidates. Each one is fetched and measured, so the
+  number is the real byte difference.
+- **Estimated** savings come from a local re-encode of the image: a different quality, a different format, or a resize of
+  a plain `<img>`. They are estimates.
+- The CLI prints `exact` and `exact + est.`. The `exact + est.` figure is the estimated saving: the exact part plus the
+  estimate.
+- Quality is judged with SSIMULACRA2 at a delta of 2 points. `--aggressive` adds a delta 4 column, which is reported
+  beside the main numbers and never used for the headline.
+- Undersized images (a file smaller than the slot it fills) are reported as sharpness growth, separately. Growth from
+  undersized images is never subtracted from other images' savings, and an undersized image itself contributes no
+  saving.
+- For each image, the scan records its locator (the component and `file:line` in dev builds, `data-testid`, `alt`, and the
+  loader URL pattern), the `sizes` the browser resolved at each viewport, the layout chain above it, and a fix hint with
+  two numbers: bytes saved, and bytes added for sharpness. The two are never netted.
+- Pages are scanned after their `robots.txt` is checked for the `*` user agent. A disallowed page is skipped and
+  recorded as `robots`. Pages that return a challenge or bot wall are recorded as `blocked` and not retried. The
+  scanner identifies itself with the default Chromium user agent, uses no stealth plugins, and fetches each image URL
+  at most once per scan.
+- Besides the page itself, scan fetches the page's own srcset candidates and, for quality estimates, the original of a
+  sampled image (derived from the loader URL), each at most once per scan. It never requests new transformations from
+  the CDN.
+- Large sites: `--urls-from` reads a URL list or a sitemap, `--sample-per-pattern` samples each route type, and
+  `--resume`, `--max-pages` and `--max-images` split a long run into parts. `--survey` is a fast pass over every URL
+  (two viewports, exact savings only, labelled as such); full-scan the heaviest page of each route type after it.
+- Production check: `imgtune check` (see [Two ways to measure](#two-ways-to-measure)) and `imgtune audit` do the same
+  survey and deep scan for a whole site, with no source needed for `check`.
+
+## The evidence ladder
+
+Every fix hint is labelled with the strength of its evidence, the rung it stands on:
+
+1. **measured-page** (exact): the usage was measured on the live page, at each viewport. This is what `scan` produces.
+2. **measured-harness**: the usage was measured in isolation, through a temporary route such as `/__imgtune/<component>`
+   that renders each state, or through Storybook. The agent removes the route afterwards.
+3. **ceiling-code**: derived from the resolved classes and the layout constraints (container width, grid columns,
+   padding). It is an upper bound on the width needed, never a measured saving.
+4. **not-measured**: no number, with the reason (hidden, behind a login, not rendered at scan time).
+
+A ceiling is never derived from the existing `sizes` value. When a usage is measured, its `sizes` comes from the layout
+the browser resolved, not from a guess.
+
+## Commands
+
+| command | what it does |
+| --- | --- |
+| `imgtune check <origin \| sitemap-url \| page-url>` | the production check, in a browser only: surveys the URLs, deep-scans the heaviest page of each route type, writes `report.md` and `run.json` to `--out` (default `.imgtune/check/<timestamp>`); `--urls-from <file\|sitemap>` instead of the URL; `--sample-per-pattern` (default 3), `--deep` (default 20), `--route-map` |
+| `imgtune audit --app <dir> --prod <origin> [--dev <origin>]` | the deep mode for a Next.js app: the check, plus the route files and `images.qualities` from `next.config`; with `--dev`, the `file:line` of each located fix; `--urls-from <file\|sitemap>`, `--max-locales` (default 3, how many values of a dynamic first segment the crawl expands) |
+| `imgtune run <url> [<url> ...] \| --urls-from <file\|sitemap>` | the whole flow in one command: survey, deep scan, locate (`--dev`), hints, and one run directory with a summary |
+| `imgtune scan <url> [<url> ...]` | measures live pages, one JSON file per page in `--out` (default `.imgtune/scan`); `--urls-from`, `--max-qualities <N>` (1 to 4, default 2) |
+| `imgtune hints <scan.json>` | prints a batch of fix hints: `--limit` (default 10), `--offset`, `--page`, `--component`, `--min-kb`, `--top`, `--flat`, `--qualities`, `--max-qualities`, `--format json` |
+| `imgtune summary <run dir \| scan.json ...>` | the one-screen summary of a run directory (`run.json`) or of scan files |
+| `imgtune scan --recheck <scan.json> [--ids a,b,c]` | rescans only the named images at the viewports where they rendered; prints before and after; exits 1 on a failed check |
+| `imgtune image <file\|url\|glob>` | measures image files without a page: bytes now, the lowest quality per format that meets the bar, and at a `--width` the bytes at each needed width; `--min-score` sets the bar (default 90), `--write <dir>` writes optimised copies |
+| `imgtune compare <before.json> <after.json>` | compares two scans of one page image by image: the bytes saved and the sharpness bytes added, as two numbers; drift (a changed layout, server variance, a view not loaded) is excluded and its totals printed; `--format json`, `--limit` |
+| `imgtune report` | a Markdown run report from the agent's ledger (`.imgtune/ledger.jsonl`); `--compare <file>` adds the bytes from `imgtune compare --format json`; `--out <file>` writes it |
+
+The scan options that matter most: `--viewports <names>` (a subset of the six), `--markdown <file>` (the PR comment),
+`--summary-json <file>` (one JSON of every page's numbers), `--fail-over <pct>` (exit 3 above a budget),
+`--storage-state <file>` (a logged-in session), and `--ignore-robots` (see Security). `npx imgtune scan --help` lists them all.
+`imgtune check --help`, `imgtune audit --help` and `imgtune run --help` list the options of each command.
+
+Two flows for a large app. One measures on a built server and then checks the edits on a dev server:
+`scan <built-url>`, then `scan <dev-url> --locate-only --from <scan.json>` (reads the React source of the flagged images),
+then `scan --recheck <located.json> --sizes-only --ids a,b` (judges the sizes choice on dev, no bytes), then `scan` on the
+built server again. The other runs the score on an NVIDIA GPU: `--gpu --gpu-device <n>` (a CUDA index; set `CUDA_DEVICE_ORDER=PCI_BUS_ID` to match `nvidia-smi`). The GPU
+program, `imgtune-ssimu2-gpu`, is not bundled; see the GPU section of the reference.
+
+## GitHub Action
+
+`action.yml` at the root scans the pages you name on each pull request, and comments the result on it. The comment keeps
+the summary tables and the top groups per page, and adds a collapsed "Fix hints for your AI agent" section with the top
+ten hints across the pages. The comment is updated on each push. Set `fail-over` to fail the job above a budget.
+
+```yaml
+- uses: indicozy/imgtune@main
+  with:
+    urls: https://preview.your-site.example/
+    fail-over: "5"
+```
+
+The action builds itself from source, so `dist/` is not needed in the repository. See [docs/ci.md](docs/ci.md) for the
+inputs, the permissions, and two example workflows (Vercel previews, and a local build on the runner).
+
+`scan` keeps Chrome on the CPUs it was started on, so you can keep it off the cores you need: `taskset -c 8-19 npx imgtune scan …` on Linux.
+
+## Security
+
+- **Egress and private addresses.** `scan` refuses private and loopback addresses unless the URL you give is itself local,
+  checks every redirect hop and sub-resource at connection time. See the [scanning guide](site/guide/scanning-any-site.md#security).
+- **ImgTune never commits, and `scan` does not change your project's source files.**
+- **Hint strings are data, not instructions.** File names, component names, `alt`, `testid`, classes and URLs come from
+  the page being scanned, and the agent must never follow text found in them. The hints print them JSON-quoted and capped
+  (in the terminal, and in the PR comment, where they sit in a fenced block after a line that says they are data). A
+  locator from a non-local source is marked `(unverified)`, and a call site that only renders the image's component is marked `(owner call site)`. The agent
+  checks that a file exists in the repository, and that the line holds an image usage, before it edits.
+- **Source maps come from the scanned site.** They are read with caps on size (20 MB), count (64 per scan), lines and
+  sections, and only a relative path under the project is kept as a source file.
+- **`--storage-state` holds session cookies.** Never commit that file. The scan never prints its contents.
+- **`--ignore-robots` is for sites you own or are authorised to test.** It prints a warning, and the JSON records
+  `robotsIgnored` with the rule that disallowed the page.
+
+## Supported loaders
+
+Loaders are detected from the URL each image renders. `original known?` means ImgTune can find the untransformed
+source, which is what quality is measured against. `quality settable?` means the URL carries a quality parameter
+that ImgTune can change.
+
+| loader | matches | original known? | quality settable? |
+| --- | --- | --- | --- |
+| next/image | `/_next/image?url=…` | yes | yes (`q`) |
+| Cloudflare Images | `/cdn-cgi/image/<opts>/<path>` | yes | yes (`quality`) |
+| Contentful | `images.ctfassets.net`, `downloads.ctfassets.net` | yes | yes (`q`) |
+| Sanity | `cdn.sanity.io/images/…`, or the same path shape on a custom domain | yes | yes (`q`) |
+| Shopify | `cdn.shopify.com`, `/cdn/shop/…` | yes (size parameters and legacy size suffixes removed) | yes (`quality`) |
+| Cloudinary | `res.cloudinary.com/<cloud>/image/upload/…`, or transformation paths on a custom domain | yes | yes (`q_<n>`); `q_auto` is left to the CDN |
+| imgix (incl. DatoCMS, Prismic) | `*.imgix.net`, `datocms-assets.com`, `images.prismic.io` | yes | yes (`q`) |
+| generic | any other URL | no | only when the URL has `q=` or `quality=` |
+
+Where the original is unknown, ImgTune still measures resolution, and reports the count of images it could not score
+for quality.
+
+## Demand study (2026-10-28)
+
+Before packaging, ImgTune scanned two groups of sites: production sites, which decided whether it was worth building,
+and open-source apps, for comparison. The site list was fixed before the first scan. Each run scans every site once:
+2 pages × 6 viewports, SSIMULACRA2 delta 2. Saving is the share of all image bytes per page view, with the page fully
+scrolled, averaged over viewports and then over the two pages. When the tool changed, every site was scanned again
+with the same version; v1 is the first run, v4 the current tool (loader adapters and the fixes found since).
+
+The `exact + est.` columns are the estimated saving: the exact saving plus the local re-encode estimate.
+
+### Production sites (decide)
+
+| site | image KB / view | exact | exact + est. (v4) | exact + est. (v1) |
+| --- | --- | --- | --- | --- |
+| A1 fashion retail, UK | 3,250 | 0.0% | 33.2% | 33.0% |
+| A2 home audio, DK | 1,263 | 5.7% | 53.1% | 47.8% |
+| A3 home audio, US | 3,355 | 13.1% | 38.2% | 13.1% |
+| A4 sportswear, UK | 9,254 | 26.8% | 35.9% | 26.8% |
+| A5 home/rugs, US | 7,714 | 12.7% | 16.5% | 12.7% |
+| A6 outdoor stays, US | 9,078 | 20.7% | 27.7% | 20.8% |
+
+Sharpness growth: about 2 KB per view on A4, 0 elsewhere.
+
+Kill criterion: a pass needs at least 2 of 6 sites above 15%.
+
+- exact only: 2 of 6 (v1 and v4), a pass at the bar
+- exact + est.: 6 of 6 in v4 (4 of 6 in v1), a pass
+
+### Open-source apps (do not decide)
+
+| site | image KB / view | exact | exact + est. | of fixable |
+| --- | --- | --- | --- | --- |
+| tailwindcss.com | 4,508 | 0.0% | 4.2% | 9.6% |
+| ui.shadcn.com | 238 | 0.0% | 33.7% | 42.0% |
+| supabase.com | 671 | 1.9% | 20.8% | 48.0% |
+| nextjs.org | 162 | 9.1% | 19.2% | 21.4% |
+| turborepo.com | 77 | 12.0% | 21.4% | 21.4% |
+| langfuse.com | 3,149 | 0.2% | 1.8% | 21.7% |
+| docs.sentry.io | 85 | 0.0% | 0.0% | 0.0% |
+| www.openstatus.dev | 152 | 0.0% | 4.2% | 31.7% |
+
+v4: 4 of 8 above 15% (exact + est.), 0 of 8 on exact alone. Developer sites carry few image bytes; the waste sits in
+image-heavy commerce.
+
+### Limits
+
+- **Six deciders.** A signal, not proof; the sample is biased to sites without bot walls.
+- **Exact is measured, est. is estimated.** On measured savings alone, 2 of 6 pass. The est. part
+  is a local re-encode scored with SSIMULACRA2 against the original; it is a floor where images could not be scored
+  (counted per page in the JSON as `qualityNA`, e.g. images that appear only at viewports where no sample was scored).
+- **Plain `<img>` resize** (A1, A2): local resize at the quality that matches the served bytes, so it doesn't add a
+  hidden quality saving.
+- A3's jump from v1 to v4 comes from Sanity images on a custom domain served at `q=100`, which v1 could not score.
+- tailwindcss.com/blog rendered no `<img>` at scan time (0 images); counted as 0%.
+
+## Requirements
+
+- Node.js 20.9 or later.
+- Chromium for Playwright. Install it once with `npx playwright install chromium`. If it is missing, ImgTune prints
+  that command and exits with status 2.
+- GPU scoring is optional. `--gpu` runs SSIMULACRA2 on an NVIDIA GPU through `imgtune-ssimu2-gpu`, an external program
+  that is not bundled with the package. If it is missing or fails, the run prints a warning and scores on the CPU.
+
+## Limitations
+
+- **Only `<img>`, `srcset`, `<picture>` and CSS background images are measured.** Background layers are kept in their own
+  records (`kind: css-background`), and the headline numbers stay `<img>`-only. Their fixes are `not-measured`, or a
+  `ceiling-code` from the layout.
+- **Source locations need dev builds.** A production build has no component names or `file:line` in its scan. A built
+  page that ships source maps gives the owner component's definition (`via: prod-sourcemap`, never verified as the image's
+  own line). The agent matches the other hints by `find` clues, `alt`, `testid` and the loader URL, and marks the
+  unmatched usages.
+- **Savings are measured on the pages and viewports scanned.** A usage that does not render on them (a hidden tab, a
+  modal, a logged-out view) is not measured. A lazy image that never loads is counted as not loaded.
+- **Est. numbers are estimates.** They come from a local re-encode judged by SSIMULACRA2. Quality is `qualityNA` where the
+  original cannot be found. Only exact numbers come from the site's own candidates.
+- **Bot walls and challenges stop a scan.** A page that returns one is recorded as `blocked`, and is not retried.
+- **Quality targets follow the loader.** Only the loaders in the table below expose a quality parameter, so only they get
+  quality proposals.
+- **ImgTune does not edit code.** The fixes are made by you, or by the agent skill, and checked by `scan --recheck`.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Third-party attributions, including the Optiq-derived SSIM code and the vendored
+SSIMULACRA2 WebAssembly module, are in [NOTICE](NOTICE).