@weft-js/plugin-media 0.1.1 → 0.1.4

package/src/build.mjs

@@ -1,10 +1,9 @@
-// media.build@1 (research 15 §2–4, research 26 §2.4): one source file in, a MediaAsset and its files out.
 //   probe (sharp, EXIF orientation) → width ladder → per-format quality search at the largest width (SSIMULACRA2,
 //   the libjxl tool) → encode every width → dominant colour + 16 px WebP placeholder. SVG: refuse unsafe files
 //   (M012), then SVGO. With a media.encode@1 provider (@weft-js/plugin-media-ffmpeg), src/video.mjs takes video, audio
 //   and animated GIFs; without one, a GIF stays as it is and video is P101.
 // Cached by content hash under `cacheDir`, so dev restarts and rebuilds don't re-encode. With `encoder: 'server'` the
-// build only stores the original: the variants are media.server@1's to encode (research 29 §6).
+// build only stores the original: the variants are media.server@1's to encode.
 import { execFile, spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
@@ -15,7 +14,7 @@ import sharp from 'sharp'
 import { optimize } from 'svgo'
 import { probe } from '@weft-js/core/media-probe'
 import { createMediaServer } from './server.mjs'
-import { DEFAULTS, FIXED, encoders, hex, isPhoto, MIME } from './shared.mjs'
+import { DEFAULTS, FIXED, encoders, hex, isPhoto, MIME, withPlaceholder } from './shared.mjs'
 import { unsafeSvg } from './svg.mjs'
 import { AUDIO, audioFile, gif, VIDEO, video } from './video.mjs'
 
@@ -40,10 +39,10 @@ export function findScorer(name) {
 }
 
 /** Lowest quality whose SSIMULACRA2 score is ≥ target, within 5 encodes (scores rise with quality). */
-async function search(format, base, width, scorer, target, dir) {
+async function search({ format, base, width, scorer, target, dir }) {
   const ref = join(dir, 'ref.png')
   if (!existsSync(ref)) writeFileSync(ref, await base().resize({ width }).png().toBuffer())
-  const score = async q => {
+  const score = async (q) => {
     const encoded = await encoders[format](base().resize({ width }), q).toBuffer()
     const out = join(dir, `${format}-${q}.png`)
     writeFileSync(out, await sharp(encoded).png().toBuffer())
@@ -59,11 +58,16 @@ async function search(format, base, width, scorer, target, dir) {
   return hi
 }
 
-const short = bytes => createHash('sha256').update(bytes).digest('hex').slice(0, 8)
+const short = (bytes) => createHash('sha256').update(bytes).digest('hex').slice(0, 8)
 
 /** The media.build@1 provider: `build` takes one source file and gives back its asset and encoded files, cached by content. */
 export function createMediaBuild(input = {}) {
-  const o = { ...DEFAULTS, ...input, quality: { ...DEFAULTS.quality, ...input.quality }, video: { ...DEFAULTS.video, ...input.video } }
+  const o = {
+    ...DEFAULTS,
+    ...input,
+    quality: { ...DEFAULTS.quality, ...input.quality },
+    video: { ...DEFAULTS.video, ...input.video },
+  }
   return {
     /**
      * @param {{ file: string, bytes: Uint8Array }} source
@@ -74,27 +78,53 @@ export function createMediaBuild(input = {}) {
       const timed = VIDEO.test(file) || AUDIO.test(file)
       if (o.encoder === 'server' && !timed) {
         try {
-          return { asset: await createMediaServer(o).at(root, encode).ingest(bytes, { name }), files: [] }
+          return {
+            asset: await createMediaServer(o).at(root, encode).ingest(bytes, { name }),
+            files: [],
+          }
         } catch (e) {
           if (!e.code) throw e
-          return { asset: null, files: [], diagnostics: [{ code: e.code, severity: 'error', message: e.message }] }
+          return {
+            asset: null,
+            files: [],
+            diagnostics: [{ code: e.code, severity: 'error', message: e.message }],
+          }
         }
       }
       const stem = basename(file, extname(file)).replace(/[^\w-]+/g, '-')
-      const key = createHash('sha256').update(bytes).update(JSON.stringify(o)).update(String(VERSION)).update(audio ? readFileSync(audio) : '').update(JSON.stringify(await versions(encode))).digest('hex').slice(0, 20)
+      const key = createHash('sha256')
+        .update(bytes)
+        .update(JSON.stringify(o))
+        .update(String(VERSION))
+        .update(audio ? readFileSync(audio) : '')
+        .update(JSON.stringify(await versions(encode)))
+        .digest('hex')
+        .slice(0, 20)
       const cached = join(cacheDir, `${key}.json`)
       if (existsSync(cached)) {
         const hit = JSON.parse(readFileSync(cached, 'utf8'))
-        return { ...hit, files: hit.files.map(n => ({ name: n, bytes: new Uint8Array(readFileSync(join(cacheDir, key, n))) })) }
+        return {
+          ...hit,
+          files: hit.files.map((n) => ({
+            name: n,
+            bytes: new Uint8Array(readFileSync(join(cacheDir, key, n))),
+          })),
+        }
       }
 
       const source = { bytes, name, stem, audio }
       const scorer = findScorer(o.quality.scorer)
-      const out = await (/\.svg$/i.test(file) ? vector(name, stem, bytes) : VIDEO.test(file) ? video(source, o, encode, scorer) : AUDIO.test(file) ? audioFile(source, o, encode) : raster(source, o, encode))
-      if (out.diagnostics?.some(d => d.severity === 'error')) return out
+      const out = await (/\.svg$/i.test(file)
+        ? vector(name, stem, bytes)
+        : VIDEO.test(file)
+          ? video(source, o, encode, scorer)
+          : AUDIO.test(file)
+            ? audioFile(source, o, encode)
+            : raster(source, o, encode))
+      if (out.diagnostics?.some((d) => d.severity === 'error')) return out
       mkdirSync(join(cacheDir, key), { recursive: true })
       for (const f of out.files) writeFileSync(join(cacheDir, key, f.name), f.bytes)
-      writeFileSync(cached, JSON.stringify({ ...out, files: out.files.map(f => f.name) }))
+      writeFileSync(cached, JSON.stringify({ ...out, files: out.files.map((f) => f.name) }))
       return out
     },
   }
@@ -103,7 +133,8 @@ export function createMediaBuild(input = {}) {
 /** What the encoders are: a new ffmpeg means new bytes. */
 async function versions(encode) {
   const found = {}
-  for (const [key, enc] of Object.entries(encode)) found[key] = await enc.versions().catch(() => null)
+  for (const [key, enc] of Object.entries(encode))
+    found[key] = await enc.versions().catch(() => null)
   return found
 }
 
@@ -111,12 +142,82 @@ async function versions(encode) {
 function vector(name, stem, bytes) {
   const text = new TextDecoder().decode(bytes)
   const unsafe = unsafeSvg(text)
-  if (unsafe.length) return { asset: null, files: [], diagnostics: [{ code: 'M012', severity: 'error', message: `${name} has ${unsafe.join(', ')}: an image with active content or external references is not optimised or served. Sanitise the file.` }] }
+  if (unsafe.length)
+    return {
+      asset: null,
+      files: [],
+      diagnostics: [
+        {
+          code: 'M012',
+          severity: 'error',
+          message: `${name} has ${unsafe.join(', ')}: an image with active content or external references is not optimised or served. Sanitise the file.`,
+        },
+      ],
+    }
   const size = probe(bytes, name)
-  if (!size) return { asset: null, files: [], diagnostics: [{ code: 'M001', severity: 'error', message: `${name} has no width/height or viewBox, so its size is unknown.` }] }
+  if (!size)
+    return {
+      asset: null,
+      files: [],
+      diagnostics: [
+        {
+          code: 'M001',
+          severity: 'error',
+          message: `${name} has no width/height or viewBox, so its size is unknown.`,
+        },
+      ],
+    }
   const svg = new TextEncoder().encode(optimize(text, { multipass: true }).data)
   const fileName = `${stem}-${short(svg)}.svg`
-  return { asset: { kind: 'vector', src: fileName, width: size.width, height: size.height, type: MIME.svg, sources: [], name, quality: 'original' }, files: [{ name: fileName, bytes: svg }] }
+  return {
+    asset: {
+      kind: 'vector',
+      src: fileName,
+      width: size.width,
+      height: size.height,
+      type: MIME.svg,
+      sources: [],
+      name,
+      quality: 'original',
+    },
+    files: [{ name: fileName, bytes: svg }],
+  }
+}
+
+async function animatedGif(
+  { bytes, name, stem, audio, meta, width, height },
+  o,
+  encode,
+  diagnostics,
+) {
+  const converted = await gif(
+    { bytes, name, stem, audio, meta, width, height },
+    o,
+    encode,
+    findScorer(o.quality.scorer),
+  )
+  if (converted) return converted
+  if (bytes.length > o.gifLimit)
+    diagnostics.push({
+      code: 'M004',
+      severity: 'warning',
+      message: `${name} is a ${Math.round(bytes.length / 1024)} KB animated GIF, and it ships as is${encode['video/h264'] ? ': nothing beat it by 15%' : '. Add `mediaFfmpeg()` from @weft-js/plugin-media-ffmpeg to turn it into video'}.`,
+    })
+  const fileName = `${stem}-${short(bytes)}.gif`
+  return {
+    asset: {
+      kind: 'graphic',
+      src: fileName,
+      width,
+      height,
+      type: MIME.gif,
+      sources: [],
+      name,
+      quality: 'original',
+    },
+    files: [{ name: fileName, bytes }],
+    diagnostics,
+  }
 }
 
 async function raster({ bytes, name, stem, audio }, o, encode) {
@@ -126,19 +227,14 @@ async function raster({ bytes, name, stem, audio }, o, encode) {
   const height = turned ? (meta.pageHeight ?? meta.width) : (meta.pageHeight ?? meta.height)
   const diagnostics = []
 
-  if (meta.format === 'gif' && (meta.pages ?? 1) > 1) {
-    const converted = await gif({ bytes, name, stem, audio, meta, width, height }, o, encode, findScorer(o.quality.scorer))
-    if (converted) return converted
-    if (bytes.length > o.gifLimit) diagnostics.push({ code: 'M004', severity: 'warning', message: `${name} is a ${Math.round(bytes.length / 1024)} KB animated GIF, and it ships as is${encode['video/h264'] ? ': nothing beat it by 15%' : '. Add `mediaFfmpeg()` from @weft-js/plugin-media-ffmpeg to turn it into video'}.` })
-    const fileName = `${stem}-${short(bytes)}.gif`
-    return { asset: { kind: 'graphic', src: fileName, width, height, type: MIME.gif, sources: [], name, quality: 'original' }, files: [{ name: fileName, bytes }], diagnostics }
-  }
+  if (meta.format === 'gif' && (meta.pages ?? 1) > 1)
+    return animatedGif({ bytes, name, stem, audio, meta, width, height }, o, encode, diagnostics)
 
   const photo = isPhoto(meta)
   const fallback = photo ? 'jpeg' : 'png'
-  const formats = [...new Set(o.formats.filter(f => f !== fallback)), fallback]
+  const formats = [...new Set(o.formats.filter((f) => f !== fallback)), fallback]
   const largest = Math.min(width, o.widths.at(-1))
-  const ladder = [...new Set([...o.widths.filter(w => w < largest), largest])]
+  const ladder = [...new Set([...o.widths.filter((w) => w < largest), largest])]
   const base = () => sharp(bytes).rotate()
 
   const scorer = findScorer(o.quality.scorer)
@@ -147,7 +243,9 @@ async function raster({ bytes, name, stem, audio }, o, encode) {
   try {
     for (const f of formats) {
       if (f === 'png') continue
-      qualities[f] = scorer ? await search(f, base, largest, scorer, o.quality.target, dir) : FIXED[f]
+      qualities[f] = scorer
+        ? await search({ format: f, base, width: largest, scorer, target: o.quality.target, dir })
+        : FIXED[f]
     }
   } finally {
     if (dir) rmSync(dir, { recursive: true, force: true })
@@ -167,16 +265,30 @@ async function raster({ bytes, name, stem, audio }, o, encode) {
   }
   const src = sources.at(-1).srcset.split(', ').at(-1).split(' ')[0]
 
-  const asset = { kind: photo ? 'photo' : 'graphic', src, width, height, type: MIME[fallback], sources, name, quality: scorer ? 'ssimulacra2' : 'fixed', qualities }
-  if (o.encoder === 'compatible') { // The fallback ladder is already built: a swap costs no extra files.
+  const asset = {
+    kind: photo ? 'photo' : 'graphic',
+    src,
+    width,
+    height,
+    type: MIME[fallback],
+    sources,
+    name,
+    quality: scorer ? 'ssimulacra2' : 'fixed',
+    qualities,
+  }
+  if (o.encoder === 'compatible') {
+    // The fallback ladder is already built: a swap costs no extra files.
     asset.copy = { src, type: MIME[fallback] }
     asset.swap = o.swap ?? 'intent'
-    diagnostics.push({ code: 'M014', severity: 'info', message: `${name}: \`encoder: 'compatible'\` adds 0 KB: the compatible copy is the fallback ladder.` })
+    diagnostics.push({
+      code: 'M014',
+      severity: 'info',
+      message: `${name}: \`encoder: 'compatible'\` adds 0 KB: the compatible copy is the fallback ladder.`,
+    })
   }
   if (o.placeholder) {
     asset.dominant = hex((await base().stats()).dominant)
-    const tiny = await base().resize(16, 16, { fit: 'inside' }).webp({ quality: 40 }).toBuffer()
-    asset.placeholder = `data:image/webp;base64,${tiny.toString('base64')}`
+    await withPlaceholder(asset, files, base(), stem, o)
   }
   return { asset, files, diagnostics }
 }

package/src/check.mjs

@@ -1,4 +1,4 @@
-// M001–M013 in `weft check` (research 15 §7.5; the static rules of research 26 §2.5). Runs as this plugin's `check`
+// M001–M013 in `weft check`. Runs as this plugin's `check`
 // hook over the project's .tsx/.jsx files, with the JSX view `weft check` passes in `ctx`.
 import { basename, dirname, extname, join, normalize } from 'node:path'
 import { probe } from '@weft-js/core/media-probe'
@@ -8,7 +8,211 @@ const IMAGE = /\.(png|jpe?g|gif|webp|avif|svg)$/i
 const MEDIA = new Set(['img', 'video', 'Media'])
 const ROUTE = /(^|\/)src\/routes\//
 
-const rel = (from, spec) => normalize(join(dirname(from), spec)).split('\\').join('/')
+const rel = (from, spec) =>
+  normalize(join(dirname(from), spec))
+    .split('\\')
+    .join('/')
+
+function checkSource({ el, src, size, sized, raw, report }) {
+  // M016: a string has no dimensions until it loads
+  if (!raw && (src?.kind === 'string' || /^[`'"]/.test(src?.expr ?? '')))
+    report(
+      'M016',
+      el,
+      '`<Media src>` is a string, so nothing knows its size before it loads and the page shifts.',
+      {
+        description:
+          'Import it with `?media`, or store the record `ctx.media.ingest` returns and type the field `z.media()`',
+        safe: false,
+      },
+    )
+
+  // M001: raw media with no box (X030 covers it inside a Boundary)
+  if (raw && !sized && !el.ancestors.includes('Boundary')) {
+    report(
+      'M001',
+      el,
+      `<${el.name}> has no \`width\`/\`height\` or \`aspect-ratio\`: it renders 0 px tall and pushes the page down when it loads.`,
+      size
+        ? {
+            description: `Insert the file's size (${size.width}×${size.height})`,
+            safe: true,
+            edits: [
+              {
+                start: el.tagEnd,
+                end: el.tagEnd,
+                text: ` width={${size.width}} height={${size.height}}`,
+              },
+            ],
+          }
+        : undefined,
+    )
+  }
+}
+
+function checkImport({ el, a, src, imp, spec, query, target, size, ctx, file, report }) {
+  // M002: through Vite's URL import or a string path to a project file
+  if (el.name === 'img' && imp && IMAGE.test(spec) && query !== 'media') {
+    report(
+      'M002',
+      el,
+      `\`${imp.source}\` is the untouched file: no resizing, no AVIF, no placeholder.`,
+      {
+        description: 'Use ?media and <Media>',
+        safe: false,
+        edits: [
+          { start: imp.start, end: imp.end, text: `import ${imp.local} from '${spec}?media'` },
+        ],
+      },
+    )
+  } else if (
+    el.name === 'img' &&
+    src?.kind === 'string' &&
+    !/^(https?:|data:|\/\/)/.test(src.value) &&
+    !src.value.startsWith('/') &&
+    IMAGE.test(src.value) &&
+    ctx.exists(rel(file, src.value))
+  ) {
+    report(
+      'M002',
+      el,
+      `\`${src.value}\` is a project file referenced by string: no resizing, no AVIF, no dimensions.`,
+    )
+  }
+  // M003: oversize for its rendered width
+  const w = Number(a('width')?.value ?? a('width')?.expr)
+  if (el.name === 'img' && size && w > 0 && size.width > w * 2 * 1.25) {
+    report(
+      'M003',
+      el,
+      `${basename(target)} is ${size.width} px wide for a ${w} px slot: ${Math.round((size.width / (w * 2)) * 100) / 100}× what a 2× screen needs.`,
+    )
+  }
+}
+
+function checkMotion({ el, a, src, target, bytes, gifLimit, report }) {
+  // M004 and M011: GIFs in raw <img>
+  const gif =
+    (target && /\.gif$/i.test(target)) || (src?.kind === 'string' && /\.gif$/i.test(src.value))
+  if (el.name === 'img' && gif && bytes && bytes.length > gifLimit)
+    report('M004', el, `${basename(target)} is ${Math.round(bytes.length / 1024)} KB of GIF.`)
+  if (el.name === 'img' && gif)
+    report(
+      'M011',
+      el,
+      'An animated GIF in a raw <img> loops forever with no pause control (WCAG 2.2.2).',
+    )
+  // M005, M006, M011: video
+  if (el.name === 'video') {
+    if (a('autoplay') && !a('muted'))
+      report(
+        'M005',
+        el,
+        '<video autoplay> without `muted`: browsers block it, and sound before a gesture is hostile.',
+        {
+          description: 'Add muted',
+          safe: true,
+          edits: [{ start: el.tagEnd, end: el.tagEnd, text: ' muted' }],
+        },
+      )
+    if (!a('poster'))
+      report('M006', el, '<video> without `poster` is a blank box until its first frame decodes.')
+    if (a('autoplay') && a('loop') && !a('controls'))
+      report(
+        'M011',
+        el,
+        '<video autoplay loop> without `controls` moves forever with no way to pause it (WCAG 2.2.2).',
+      )
+  }
+}
+
+function checkAlt({ el, a, src, imp, target, report }) {
+  // M007: alt
+  if (el.name !== 'video') {
+    const alt = a('alt')
+    const stems = [
+      imp?.local,
+      target && basename(target),
+      target && basename(target, extname(target)),
+      src?.kind === 'string' && basename(src.value),
+    ]
+      .filter(Boolean)
+      .map((s) => s.toLowerCase())
+    if (!alt) report('M007', el, `<${el.name}> has no \`alt\`.`)
+    else if (el.name === 'Media' && alt.kind === 'string' && alt.value === '' && !a('decorative'))
+      report(
+        'M007',
+        el,
+        '`alt=""` hides the image from screen readers: say so with `decorative`, or describe it.',
+      )
+    else if (alt.kind === 'string' && alt.value && stems.includes(alt.value.toLowerCase()))
+      report(
+        'M007',
+        el,
+        `\`alt="${alt.value}"\` is the file name, which tells nobody what the image shows.`,
+      )
+  }
+}
+
+function checkPriority({ el, a, route, i, priorities, report }) {
+  // M008, M009, M010: priority (route files: the likely LCP image)
+  const lazy = a('loading')?.value === 'lazy'
+  const priority = !!a('priority') || a('fetchpriority')?.value === 'high'
+  if (priority && lazy)
+    report('M008', el, '`priority` media with `loading="lazy"` loads late anyway.', {
+      description: 'Remove loading="lazy"',
+      safe: true,
+      edits: [{ start: a('loading').start - 1, end: a('loading').end, text: '' }],
+    })
+  else if (route && i === 0 && lazy)
+    report(
+      'M008',
+      el,
+      `The route's first media is \`loading="lazy"\`: it is the likely LCP image, and lazy delays it.`,
+    )
+  if (route && priority && ++priorities > 2) {
+    const p = a('priority') ?? a('fetchpriority')
+    report(
+      'M009',
+      el,
+      `More than 2 \`priority\` media in this route: they compete for the first bytes.`,
+      {
+        description: 'Remove priority',
+        safe: true,
+        edits: [{ start: p.start - 1, end: p.end, text: '' }],
+      },
+    )
+  }
+  if (el.name === 'Media' && a('priority') && !a('width') && !a('sizes'))
+    report(
+      'M010',
+      el,
+      '`priority` makes this image eager, and eager images can\'t use `sizes="auto"`: the browser assumes 100vw and fetches the largest file.',
+    )
+  return priorities
+}
+
+function checkSecurity({ el, src, target, bytes, svgs, ctx, report }) {
+  // M012: unsafe SVG used as an image
+  if (target && /\.svg$/i.test(target) && bytes) {
+    if (!svgs.has(target)) svgs.set(target, unsafeSvg(new TextDecoder().decode(bytes)))
+    if (svgs.get(target).length)
+      report('M012', el, `${basename(target)} has ${svgs.get(target).join(', ')}.`)
+  }
+  // M013: public/ by string
+  if (
+    src?.kind === 'string' &&
+    src.value.startsWith('/') &&
+    !src.value.startsWith('//') &&
+    ctx.exists(`public${src.value.split('?')[0]}`)
+  ) {
+    report(
+      'M013',
+      el,
+      `\`${src.value}\` is served from public/: untracked, unoptimised, with no dimensions.`,
+    )
+  }
+}
 
 /** @param {{ files: string[], read: (f: string) => string, jsx: Function, importOf: Function, exists: (f: string) => boolean, bytes: (f: string) => Uint8Array | undefined }} ctx */
 export function checkMedia(ctx, { gifLimit = 256 * 1024 } = {}) {
@@ -17,13 +221,14 @@ export function checkMedia(ctx, { gifLimit = 256 * 1024 } = {}) {
   for (const file of ctx.files) {
     if (!/\.[jt]sx$/.test(file)) continue
     const scan = ctx.jsx(file)
-    const report = (code, el, why, fix) => out.push({ code, file, start: el.start, end: el.tagEnd, why, ...(fix && { fix }) })
-    const media = scan.elements.filter(e => MEDIA.has(e.name))
+    const report = (code, el, why, fix) =>
+      out.push({ code, file, start: el.start, end: el.tagEnd, why, ...(fix && { fix }) })
+    const media = scan.elements.filter((e) => MEDIA.has(e.name))
     const route = ROUTE.test(file)
     let priorities = 0
 
     for (const [i, el] of media.entries()) {
-      const a = n => el.attr(n)
+      const a = (n) => el.attr(n)
       const src = a('src')
       const imp = src?.kind === 'expr' ? ctx.importOf(scan, src.expr) : undefined
       const [spec, query = ''] = imp ? imp.source.split('?') : []
@@ -34,63 +239,12 @@ export function checkMedia(ctx, { gifLimit = 256 * 1024 } = {}) {
       const sized = (a('width') && a('height')) || /aspect-?ratio/i.test(style)
       const raw = el.name !== 'Media'
 
-      // M016: a string has no dimensions until it loads
-      if (!raw && (src?.kind === 'string' || /^[`'"]/.test(src?.expr ?? '')))
-        report('M016', el, '`<Media src>` is a string, so nothing knows its size before it loads and the page shifts.', { description: 'Import it with `?media`, or store the record `ctx.media.ingest` returns and type the field `z.media()`', safe: false })
-
-      // M001: raw media with no box (X030 covers it inside a Boundary)
-      if (raw && !sized && !el.ancestors.includes('Boundary')) {
-        report('M001', el, `<${el.name}> has no \`width\`/\`height\` or \`aspect-ratio\`: it renders 0 px tall and pushes the page down when it loads.`,
-          size ? { description: `Insert the file's size (${size.width}×${size.height})`, safe: true, edits: [{ start: el.tagEnd, end: el.tagEnd, text: ` width={${size.width}} height={${size.height}}` }] } : undefined)
-      }
-      // M002: through Vite's URL import or a string path to a project file
-      if (el.name === 'img' && imp && IMAGE.test(spec) && query !== 'media') {
-        report('M002', el, `\`${imp.source}\` is the untouched file: no resizing, no AVIF, no placeholder.`, { description: 'Use ?media and <Media>', safe: false, edits: [{ start: imp.start, end: imp.end, text: `import ${imp.local} from '${spec}?media'` }] })
-      } else if (el.name === 'img' && src?.kind === 'string' && !/^(https?:|data:|\/\/)/.test(src.value) && !src.value.startsWith('/') && IMAGE.test(src.value) && ctx.exists(rel(file, src.value))) {
-        report('M002', el, `\`${src.value}\` is a project file referenced by string: no resizing, no AVIF, no dimensions.`)
-      }
-      // M003: oversize for its rendered width
-      const w = Number(a('width')?.value ?? a('width')?.expr)
-      if (el.name === 'img' && size && w > 0 && size.width > w * 2 * 1.25) {
-        report('M003', el, `${basename(target)} is ${size.width} px wide for a ${w} px slot: ${Math.round(size.width / (w * 2) * 100) / 100}× what a 2× screen needs.`)
-      }
-      // M004 and M011: GIFs in raw <img>
-      const gif = (target && /\.gif$/i.test(target)) || (src?.kind === 'string' && /\.gif$/i.test(src.value))
-      if (el.name === 'img' && gif && bytes && bytes.length > gifLimit) report('M004', el, `${basename(target)} is ${Math.round(bytes.length / 1024)} KB of GIF.`)
-      if (el.name === 'img' && gif) report('M011', el, 'An animated GIF in a raw <img> loops forever with no pause control (WCAG 2.2.2).')
-      // M005, M006, M011: video
-      if (el.name === 'video') {
-        if (a('autoplay') && !a('muted')) report('M005', el, '<video autoplay> without `muted`: browsers block it, and sound before a gesture is hostile.', { description: 'Add muted', safe: true, edits: [{ start: el.tagEnd, end: el.tagEnd, text: ' muted' }] })
-        if (!a('poster')) report('M006', el, '<video> without `poster` is a blank box until its first frame decodes.')
-        if (a('autoplay') && a('loop') && !a('controls')) report('M011', el, '<video autoplay loop> without `controls` moves forever with no way to pause it (WCAG 2.2.2).')
-      }
-      // M007: alt
-      if (el.name !== 'video') {
-        const alt = a('alt')
-        const stems = [imp?.local, target && basename(target), target && basename(target, extname(target)), src?.kind === 'string' && basename(src.value)].filter(Boolean).map(s => s.toLowerCase())
-        if (!alt) report('M007', el, `<${el.name}> has no \`alt\`.`)
-        else if (el.name === 'Media' && alt.kind === 'string' && alt.value === '' && !a('decorative')) report('M007', el, '`alt=""` hides the image from screen readers: say so with `decorative`, or describe it.')
-        else if (alt.kind === 'string' && alt.value && stems.includes(alt.value.toLowerCase())) report('M007', el, `\`alt="${alt.value}"\` is the file name, which tells nobody what the image shows.`)
-      }
-      // M008, M009, M010: priority (route files: the likely LCP image)
-      const lazy = a('loading')?.value === 'lazy'
-      const priority = !!a('priority') || a('fetchpriority')?.value === 'high'
-      if (priority && lazy) report('M008', el, '`priority` media with `loading="lazy"` loads late anyway.', { description: 'Remove loading="lazy"', safe: true, edits: [{ start: a('loading').start - 1, end: a('loading').end, text: '' }] })
-      else if (route && i === 0 && lazy) report('M008', el, `The route's first media is \`loading="lazy"\`: it is the likely LCP image, and lazy delays it.`)
-      if (route && priority && ++priorities > 2) {
-        const p = a('priority') ?? a('fetchpriority')
-        report('M009', el, `More than 2 \`priority\` media in this route: they compete for the first bytes.`, { description: 'Remove priority', safe: true, edits: [{ start: p.start - 1, end: p.end, text: '' }] })
-      }
-      if (el.name === 'Media' && a('priority') && !a('width') && !a('sizes')) report('M010', el, '`priority` makes this image eager, and eager images can\'t use `sizes="auto"`: the browser assumes 100vw and fetches the largest file.')
-      // M012: unsafe SVG used as an image
-      if (target && /\.svg$/i.test(target) && bytes) {
-        if (!svgs.has(target)) svgs.set(target, unsafeSvg(new TextDecoder().decode(bytes)))
-        if (svgs.get(target).length) report('M012', el, `${basename(target)} has ${svgs.get(target).join(', ')}.`)
-      }
-      // M013: public/ by string
-      if (src?.kind === 'string' && src.value.startsWith('/') && !src.value.startsWith('//') && ctx.exists(`public${src.value.split('?')[0]}`)) {
-        report('M013', el, `\`${src.value}\` is served from public/: untracked, unoptimised, with no dimensions.`)
-      }
+      checkSource({ el, src, size, sized, raw, report })
+      checkImport({ el, a, src, imp, spec, query, target, size, ctx, file, report })
+      checkMotion({ el, a, src, target, bytes, gifLimit, report })
+      checkAlt({ el, a, src, imp, target, report })
+      priorities = checkPriority({ el, a, route, i, priorities, report })
+      checkSecurity({ el, src, target, bytes, svgs, ctx, report })
     }
   }
   return out

package/src/index.d.ts

@@ -8,8 +8,11 @@ export interface MediaOptions {
   widths?: number[]
   /** `target`: the SSIMULACRA2 score each format is searched to (default 80). `scorer`: the command, or 'none'. */
   quality?: { target?: number; scorer?: string }
-  /** Dominant colour and a 16 px WebP placeholder. Default true. */
-  placeholder?: boolean
+  /**
+   * Dominant colour and a 16 px WebP placeholder. `true` or 'inline' (the default) inlines it as a `data:` URL; 'file'
+   * writes it as its own file, for a CSP whose `img-src` has no `data:`; `false` leaves both out.
+   */
+  placeholder?: boolean | 'inline' | 'file'
   /** Bytes over which a GIF is M004. Default 256 KB. */
   gifLimit?: number
   /** 'server': `?media` imports are encoded on first request by the media route, not at build. 'compatible': the page shows the efficient file, and a compatible copy swaps in so saving gives a file that opens anywhere. Default 'off'. */