fix(images): drop Unpic, return the scaffold to Astro's sharp service

[dmurko]

Propagates the findings from site-paretosecurity#33 back into the scaffold and skills.

The scaffold shipped @unpic/astro as Astro's image service, and both CLAUDE.md and the code-review skill had been written around its quirks — to the point that its bugs were codified as doctrine:

.img-uncap … This is the sanctioned escape hatch, not a hack
width is what controls the emitted file. widths does NOT.

Removing unpic inverts all of that.

What unpic was actually doing

Verified against a production build before removal:

#	Defect	Impact
1	Ignored the widths prop	Generated its own 12-step ladder (640…3840w) regardless of what the markup declared.
2	Turned width/height into inline max-width/max-height/width:100%	Inline style outranks every Tailwind class — this is the only reason .img-uncap existed.
3	Emitted style="[object Object]" + stray url=/format=	41 images across 15 pages, 4 of which rendered at 2×2px (invisible). unpic returns style as an object; Astro's content layer stringifies it with String(value).

Removing it cut that site's built asset footprint from 173MB → 47MB.

⚠️ imageService: "compile" was wrong everywhere — now flagged

website-builder, code-review and scaffold CLAUDE.md all recommended "compile". It does not keep sharp:

// adapter v13 — unconditional
case "compile": return { ...config, service: WORKERD_IMAGE_SERVICE, ... };

// adapter v14 — and hasUserImageService() explicitly excludes the sharp entrypoint
case "compile": return { ...config, service: hasUserImageService(config) ? config.service : WORKERD_IMAGE_SERVICE, ... };

Either version replaces sharp. case "custom": return { ...config } is the only branch that passes the config through untouched. The scaffold already used "custom" — the docs were wrong, not the config. "compile" moves from Pass to Critical in code-review.

Worth noting: no adapter upgrade is needed for this. v13 is the more absolute of the two, and @astrojs/cloudflare@14 has peer astro: ^7.0.0 while the scaffold is on Astro 6.4.8 — so upgrading would force an Astro major bump, which is separate work.

Scaffold

• Drop @unpic/astro and the image.service key (Astro's schema default is already sharp).
• Delete the .img-uncap utility from src/index.css.
• Comment imageService: "custom" as load-bearing, in the config itself, so nobody "fixes" it back.
• Replace the unpic right-sizing rules with sharp's real semantics:
  • sizes without widths/densities → getSrcSet returns [], so no srcset is emitted and sizes is inert.
  • widths above the source's intrinsic width are clamped, never upscaled — a 2× candidate needs a big enough source.
  • width + height disagreeing with the source ratio → sharp resizes with fit: cover, a silent crop.
  • width sizes the file; w-full sizes the element.
  • Markdown rehype plugins need a widths ladder too — user rehype plugins run before rehypeImages, which folds node.properties into the __ASTRO_IMAGE_ payload, so those props are real getImage() options.

Skills

• code-review — right-sizing section rewritten against sharp's getSrcSet/getTargetDimensions. New Critical for sizes without widths; new warnings for width+height on a CSS-controlled box and for max-width: none !important image utilities. Removes the "do NOT flag .img-uncap" pass rule.
• seo-audit — new build-output check that measures real pixel dimensions against the slot sizes declares, instead of using file size in MB as a proxy. Catches the "5000px file in a 200px slot" case, inert sizes, aspect-ratio drift, and malformed image markup. Skips SVG (vector — measuring it produces false positives on every logo).
• website-builder — corrected adapter guidance plus a right-sizing rule in the always-on constraints.
• scaffold-sync — 0.1.2 Unpic entry marked superseded; new 0.3.1 migration entry with the manual steps for existing sites (including the two failure modes to watch for: images that shrink without w-full, and tags that silently lose their srcset without widths).

Plugin version bumped to 0.3.1 to match the migration entry.

Verification

• Scaffold bun install + bun run build succeed.
• bun run check is unchanged from main — 6 pre-existing errors (schema-dts typing on 404.astro, missing @types/bun), confirmed by stashing and re-running on main rather than assumed.
• Built markup carries zero unpic artifacts (style="[object Object]", url=, format=) and emits a correct 2-candidate srcset.

🤖 Generated with Claude Code