@weft-js/plugin-media 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+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/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @weft-js/plugin-media
 
-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.
+> **Early release (0.1.1).** APIs will change between minor versions.
+
+The media.build@1 provider (sharp + SVGO: AVIF plus a compatible fallback, an SSIMULACRA2 quality search, width ladders, placeholders), the media.server@1 route provider, and M001–M018.
+
+```bash
+npm install @weft-js/plugin-media
+```

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@weft-js/plugin-media",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "@weft-js/plugin-media: the media.build@1 provider (sharp + SVGO: AVIF plus a compatible fallback, an SSIMULACRA2 quality search, width ladders, placeholders), the media.server@1 route provider, and M001–M018",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./build": "./src/build.mjs",
+    "./server": "./src/server.mjs"
+  },
+  "dependencies": {
+    "sharp": "0.35.5",
+    "svgo": "4.1.0"
+  },
+  "peerDependencies": {
+    "@weft-js/core": "^0.1.1"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "plugin.mjs",
+    "plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/build.mjs

@@ -0,0 +1,182 @@
+// 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).
+import { execFile, spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, extname, join } from 'node:path'
+import { promisify } from 'node:util'
+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 { unsafeSvg } from './svg.mjs'
+import { AUDIO, audioFile, gif, VIDEO, video } from './video.mjs'
+
+const run = promisify(execFile)
+const VERSION = 2 // bump when the output for the same input and options changes
+
+export { DEFAULTS, FIXED, MIME, encoders, hex, isPhoto } from './shared.mjs'
+
+/** The range the quality search walks. */
+const RANGE = { avif: [20, 90], webp: [40, 95], jpeg: [40, 95] }
+const EXT = { avif: 'avif', webp: 'webp', jpeg: 'jpg', png: 'png', gif: 'gif', svg: 'svg' }
+
+const scorers = new Map()
+/** The SSIMULACRA2 command if it runs, else null (the search then uses FIXED and says `quality: 'fixed'`). */
+export function findScorer(name) {
+  if (!name || name === 'none') return null
+  if (!scorers.has(name)) {
+    const r = spawnSync(name, [], { encoding: 'utf8' })
+    scorers.set(name, r.error ? null : name)
+  }
+  return scorers.get(name)
+}
+
+/** Lowest quality whose SSIMULACRA2 score is ≥ target, within 5 encodes (scores rise with quality). */
+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 encoded = await encoders[format](base().resize({ width }), q).toBuffer()
+    const out = join(dir, `${format}-${q}.png`)
+    writeFileSync(out, await sharp(encoded).png().toBuffer())
+    const { stdout } = await run(scorer, [ref, out])
+    return parseFloat(stdout)
+  }
+  let [lo, hi] = RANGE[format]
+  for (let i = 0; i < 5 && lo < hi; i++) {
+    const mid = Math.floor((lo + hi) / 2)
+    if ((await score(mid)) >= target) hi = mid
+    else lo = mid + 1
+  }
+  return hi
+}
+
+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 } }
+  return {
+    /**
+     * @param {{ file: string, bytes: Uint8Array }} source
+     * @param {{ cacheDir: string, dev?: boolean, encode?: Record<string, object> }} ctx
+     */
+    async build({ file, bytes, audio }, { cacheDir, root, encode = {} }) {
+      const name = basename(file)
+      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: [] }
+        } catch (e) {
+          if (!e.code) throw e
+          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 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))) })) }
+      }
+
+      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
+      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) }))
+      return out
+    },
+  }
+}
+
+/** 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)
+  return found
+}
+
+/** SVG: refuse what can run or fetch (M012), else SVGO's default preset (it keeps the viewBox). */
+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.` }] }
+  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.` }] }
+  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 }] }
+}
+
+async function raster({ bytes, name, stem, audio }, o, encode) {
+  const meta = await sharp(bytes, { animated: true }).metadata()
+  const turned = (meta.orientation ?? 1) >= 5
+  const width = turned ? meta.height : meta.width
+  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 }
+  }
+
+  const photo = isPhoto(meta)
+  const fallback = photo ? 'jpeg' : 'png'
+  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 base = () => sharp(bytes).rotate()
+
+  const scorer = findScorer(o.quality.scorer)
+  const dir = scorer ? mkdtempSync(join(tmpdir(), 'weft-media-')) : null
+  const qualities = {}
+  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]
+    }
+  } finally {
+    if (dir) rmSync(dir, { recursive: true, force: true })
+  }
+
+  const files = []
+  const sources = []
+  for (const f of formats) {
+    const entries = []
+    for (const w of ladder) {
+      const encoded = await encoders[f](base().resize({ width: w }), qualities[f]).toBuffer()
+      const fileName = `${stem}-${w}-${short(encoded)}.${EXT[f]}`
+      files.push({ name: fileName, bytes: new Uint8Array(encoded) })
+      entries.push([fileName, w])
+    }
+    sources.push({ type: MIME[f], srcset: entries.map(([n, w]) => `${n} ${w}w`).join(', ') })
+  }
+  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.
+    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.` })
+  }
+  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')}`
+  }
+  return { asset, files, diagnostics }
+}

package/src/check.mjs

@@ -0,0 +1,97 @@
+// M001–M013 in `weft check` (research 15 §7.5; the static rules of research 26 §2.5). 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'
+import { unsafeSvg } from './svg.mjs'
+
+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('/')
+
+/** @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 } = {}) {
+  const out = []
+  const svgs = new Map()
+  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 route = ROUTE.test(file)
+    let priorities = 0
+
+    for (const [i, el] of media.entries()) {
+      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('?') : []
+      const target = imp && spec.startsWith('.') ? rel(file, spec) : undefined
+      const bytes = target && IMAGE.test(target) ? ctx.bytes(target) : undefined
+      const size = bytes && probe(bytes, target)
+      const style = a('style')?.value ?? a('style')?.expr ?? ''
+      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.`)
+      }
+    }
+  }
+  return out
+}

package/src/index.d.ts

@@ -0,0 +1,28 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Options of `media()`: what to encode, how far to search, and when the encoding happens. */
+export interface MediaOptions {
+  /** Efficient formats in front of the source-format fallback. Default `['avif']`. */
+  formats?: ('avif' | 'webp')[]
+  /** The width ladder; the largest also caps the output. Default 320, 640, 960, 1280, 1920, 2560. */
+  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
+  /** 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'. */
+  encoder?: 'off' | 'compatible' | 'server'
+  /** When a compatible copy swaps in, with `encoder: 'compatible'`. Default 'intent': on right-click, long-press or drag. */
+  swap?: 'intent' | 'idle' | 'never'
+  /** Efficient codecs next to H.264 (default `['av1']`), and the ladder (default 640, 960, 1280, 1920). */
+  video?: { codecs?: ('av1' | 'vp9' | 'hevc')[]; widths?: number[] }
+  /** `toVideo: 'never'` keeps GIFs. `keepUnder`: bytes under which a GIF stays one. Default 8 KB. */
+  gif?: { toVideo?: 'auto' | 'never'; keepUnder?: number }
+  /** The media route's store (uploads, and `encoder: 'server'`). `dir` default `.weft/media`, `maxBytes` default 20 MB. */
+  server?: { dir?: string; maxBytes?: number }
+}
+
+/** The plugin for `weft.config.ts`: `?media` imports become optimised, responsive assets. */
+export declare function media(options?: MediaOptions): PluginInstance<MediaOptions>

package/src/index.mjs

@@ -0,0 +1,115 @@
+// media() for weft.config.ts (research 15 §7.4, research 26 §2, research 29 §6): provides media.build@1 (src/build.mjs,
+// run by @weft-js/core/vite for `?media` imports) and media.server@1 (src/server.mjs, the route for uploads and `encoder:
+// 'server'`), and reports M001–M013 and M016 through its `check` hook (src/check.mjs).
+import { fileURLToPath } from 'node:url'
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+import { checkMedia } from './check.mjs'
+
+const mediaBuild = defineSlot({ id: 'media.build', version: 1, cardinality: 'one', sides: ['build'] })
+const mediaServer = defineSlot({ id: 'media.server', version: 1, cardinality: 'one', sides: ['server'] })
+const FORMATS = ['avif', 'webp']
+const CODECS = ['av1', 'vp9', 'hevc']
+
+const fail = (path, message) => {
+  throw Object.assign(new Error(message), { path })
+}
+
+function options(input) {
+  for (const key of Object.keys(input)) if (!['formats', 'widths', 'quality', 'placeholder', 'gifLimit', 'encoder', 'swap', 'video', 'gif', 'server'].includes(key)) fail(key, 'unknown option')
+  const out = {}
+  if (input.encoder !== undefined) {
+    if (!['off', 'compatible', 'server'].includes(input.encoder)) fail('encoder', `\`${input.encoder}\`: 'off', 'compatible' or 'server'`)
+    out.encoder = input.encoder
+  }
+  if (input.swap !== undefined) {
+    if (!['intent', 'idle', 'never'].includes(input.swap)) fail('swap', `\`${input.swap}\`: 'intent', 'idle' or 'never'`)
+    if (input.encoder !== 'compatible') fail('swap', "only means something with `encoder: 'compatible'`")
+    out.swap = input.swap
+  }
+  if (input.video !== undefined) {
+    const { codecs, widths } = input.video
+    if (codecs !== undefined) {
+      if (!Array.isArray(codecs)) fail('video.codecs', 'expected an array')
+      for (const [i, c] of codecs.entries()) if (!CODECS.includes(c)) fail(`video.codecs.${i}`, `\`${c}\`: ${CODECS.join(', ')} (H.264 is always there)`)
+    }
+    if (widths !== undefined && !(Array.isArray(widths) && widths.length && widths.every(w => Number.isInteger(w) && w > 0))) fail('video.widths', 'expected positive integers')
+    out.video = { ...input.video, ...(widths && { widths: [...widths].sort((a, b) => a - b) }) }
+  }
+  if (input.gif !== undefined) {
+    const { toVideo, keepUnder } = input.gif
+    if (toVideo !== undefined && !['auto', 'never'].includes(toVideo)) fail('gif.toVideo', "'auto' or 'never'")
+    if (keepUnder !== undefined && !(Number.isInteger(keepUnder) && keepUnder >= 0)) fail('gif.keepUnder', 'a number of bytes')
+    out.gif = input.gif
+  }
+  if (input.server !== undefined) {
+    const { dir, maxBytes } = input.server
+    if (dir !== undefined && typeof dir !== 'string') fail('server.dir', 'a directory, relative to the app')
+    if (maxBytes !== undefined && !(Number.isInteger(maxBytes) && maxBytes > 0)) fail('server.maxBytes', 'a positive number of bytes')
+    out.server = input.server
+  }
+  if (input.formats !== undefined) {
+    if (!Array.isArray(input.formats)) fail('formats', 'expected an array')
+    for (const [i, f] of input.formats.entries()) if (!FORMATS.includes(f)) fail(`formats.${i}`, `\`${f}\`: the efficient formats are ${FORMATS.join(', ')} (the fallback follows the source)`)
+    out.formats = input.formats
+  }
+  if (input.widths !== undefined) {
+    if (!Array.isArray(input.widths) || !input.widths.length || !input.widths.every(w => Number.isInteger(w) && w > 0)) fail('widths', 'expected positive integers')
+    out.widths = [...input.widths].sort((a, b) => a - b)
+  }
+  if (input.quality !== undefined) {
+    const { target = 80, scorer = 'ssimulacra2' } = input.quality
+    if (!(target > 0 && target <= 100)) fail('quality.target', 'an SSIMULACRA2 score, 1–100 (80 ≈ visually lossless at normal viewing)')
+    if (typeof scorer !== 'string') fail('quality.scorer', "the SSIMULACRA2 command, or 'none' for fixed qualities")
+    out.quality = { target, scorer }
+  }
+  if (input.placeholder !== undefined) out.placeholder = !!input.placeholder
+  if (input.gifLimit !== undefined) out.gifLimit = input.gifLimit
+  return out
+}
+
+const CODES = [
+  ['M001', 'Raw <img>/<video> without width/height or aspect-ratio'],
+  ['M002', 'Image through ?url or a string path'],
+  ['M003', 'Raw <img> file far wider than its slot'],
+  ['M004', 'GIF over 256 KB rendered raw'],
+  ['M005', '<video autoplay> without muted'],
+  ['M006', '<video> without poster'],
+  ['M007', 'Missing or meaningless alt'],
+  ['M008', 'Likely LCP image loaded lazily'],
+  ['M009', 'More than 2 priority media in a route'],
+  ['M010', 'priority <Media> with no width or sizes'],
+  ['M011', 'Endless motion with no pause control'],
+  ['M012', 'Unsafe SVG used as an image'],
+  ['M013', 'public/ file referenced by string'],
+  ['M014', "What `encoder: 'compatible'` adds to the build"],
+  ['M015', 'An HDR or over-8-bit source that comes out 8-bit SDR'],
+  ['M016', '<Media src> given a string: no dimensions before render'],
+  ['M017', 'Media requested with no media.server provider'],
+  ['M018', 'An upload refused: not an image, or over the size limit'],
+  ['M019', 'ffmpeg missing, not the pinned binary, or without an encoder'],
+]
+
+export const media = definePlugin({
+  name: '@weft-js/plugin-media',
+  version: '0.1.0',
+  weft: '*',
+  namespace: 'M',
+  options,
+  permissions: { fs: { read: ['**/*.{png,jpg,jpeg,gif,webp,avif,svg,mp4,m4v,mov,webm,mkv,ogv,mp3,wav,flac,ogg,oga,opus,m4a,aac}'] }, env: ['WEFT_MEDIA_DIR'], spawn: ['ssimulacra2'], native: true },
+  contribute: o => ({
+    provides: [provide(mediaBuild, { sides: { build: { module: fileURLToPath(new URL('./build.mjs', import.meta.url)), export: 'createMediaBuild', options: o } } }), provide(mediaServer, { sides: { server: { module: '@weft-js/plugin-media/server', export: 'createMediaServer', options: o } } })],
+    check: { include: ['**/*.{tsx,jsx}'], run: ctx => checkMedia(ctx, { gifLimit: o.gifLimit }) },
+    diagnostics: CODES.map(([code, catches]) => ({ code, catches, fix: `weft docs ${code}` })),
+    agents: {
+      title: 'Media (@weft-js/plugin-media)',
+      text: [
+        "- Import images with `?media` and render `<Media src={x} alt=\"…\" />` from `@weft-js/core/media`. Never hand-write srcset, sizes, width/height or blur placeholders.",
+        '- Mark the one hero image `priority` and give it `width` (`"1/2"`, `"480px"`) so its `sizes` is right (M010). Nothing else gets `priority` (M009).',
+        '- `alt` is required; use `alt="" decorative` for purely visual media (M007).',
+        '- Never reference files in public/ by string (M013) or render `?url` imports in `<img>` (M002).',
+        "- Uploads: `await ctx.media.ingest(file)` in a mutation returns a record. Store it, type the field `z.media()` (from `@weft-js/start/media`), and pass it to `<Media src>` (M016).",
+      ].join('\n'),
+    },
+    catalog: [{ name: 'Media', import: '@weft-js/core/media', summary: '<Media src={x} alt>: dimensions, AVIF + fallback, srcset/sizes, placeholder' }],
+  }),
+})

package/src/server.mjs

@@ -0,0 +1,143 @@
+// media.server@1 (research 15 §5.4, research 29 §6): uploads, CMS images and `encoder: 'server'`. `ingest` stores an
+// original under its hash and returns the record `z.media()` validates; `serve` answers `/_weft/m/<hash>/<w>.<fmt>`,
+// encoding each variant once and keeping it next to the original. `auto` negotiates on `Accept`. Only widths on the
+// ladder and formats in the config are served, so a URL can't ask for unbounded work. Video, audio and animated GIFs go
+// through src/upload.mjs when media.encode@1 is bound.
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import sharp from 'sharp'
+import { optimize } from 'svgo'
+import { probe } from '@weft-js/core/media-probe'
+import { DEFAULTS, FIXED, encoders, hex, isPhoto, MIME } from './shared.mjs'
+import { unsafeSvg } from './svg.mjs'
+import { sniff, uploads } from './upload.mjs'
+
+const ROUTE = '/_weft/m'
+const FORMATS_TIMED = new Set(['mp4', 'webm', 'm4a', 'gif', 'webp'])
+const MAX_BYTES = 20 * 1024 * 1024
+const EXT = { avif: 'avif', webp: 'webp', jpeg: 'jpg', png: 'png' }
+const FORMAT = { avif: 'avif', webp: 'webp', jpg: 'jpeg', png: 'png' }
+
+const refuse = (code, message) => {
+  throw Object.assign(new Error(message), { code })
+}
+
+/** The first of `formats` the client names with a q above 0, else `fallback`. `*` promises nothing: only names count. */
+export function negotiate(accept, formats, fallback) {
+  const q = new Map()
+  for (const part of accept.split(',')) {
+    const [type, ...params] = part.trim().toLowerCase().split(';')
+    const v = params.map(p => /^\s*q=([\d.]+)/.exec(p)?.[1]).find(Boolean)
+    q.set(type.trim(), v === undefined ? 1 : Number(v))
+  }
+  return formats.find(f => q.get(MIME[f]) > 0) ?? fallback
+}
+
+/** The media.server@1 provider: `at(root, encode)` is the store for one app, its `ingest` and its `serve`. */
+export function createMediaServer(input = {}) {
+  const o = { ...DEFAULTS, ...input, video: { ...DEFAULTS.video, ...input.video } }
+  return { at: (root, encode = {}) => storage(o, root, encode) }
+}
+
+function storage(o, root, encode) {
+  const dir = process.env.WEFT_MEDIA_DIR ? resolve(process.env.WEFT_MEDIA_DIR) : resolve(root ?? process.cwd(), o.server?.dir ?? '.weft/media')
+  const limit = o.server?.maxBytes ?? MAX_BYTES
+  const flight = new Map()
+  const url = (hash, width, format = 'auto') => `${ROUTE}/${hash}/${width}.${format}`
+  const metaOf = hash => {
+    const file = join(dir, hash, 'meta.json')
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null
+  }
+
+  /** The record and what `serve` needs; written last, so a meta.json means the original is whole. */
+  function store(hash, bytes, asset, meta) {
+    mkdirSync(join(dir, hash), { recursive: true })
+    writeFileSync(join(dir, hash, 'source'), bytes)
+    const tmp = join(dir, hash, `meta.${process.pid}.tmp`)
+    writeFileSync(tmp, JSON.stringify({ ...meta, asset }))
+    renameSync(tmp, join(dir, hash, 'meta.json'))
+    return asset
+  }
+
+  const timed = uploads({ o, dir, encode, url, store, refuse })
+
+  async function ingest(bytes, { name = 'upload' } = {}) {
+    if (bytes.length > limit) refuse('M018', `${name} is ${Math.round(bytes.length / 1048576)} MB, over the ${Math.round(limit / 1048576)} MB limit.`)
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 32)
+    const known = metaOf(hash)
+    if (known) return { ...known.asset, name }
+    const kind = sniff(bytes)
+    if (kind) {
+      if (!encode['video/h264']) refuse('M018', `${name} is ${kind}, and nothing here encodes it: add \`mediaFfmpeg()\` from @weft-js/plugin-media-ffmpeg to \`plugins\`, with ffmpeg on the server.`)
+      mkdirSync(join(dir, hash), { recursive: true })
+      return timed.ingest(hash, bytes, name, kind)
+    }
+    const size = probe(bytes, name)
+    if (size?.type === 'image/svg+xml') {
+      const text = new TextDecoder().decode(bytes)
+      const unsafe = unsafeSvg(text)
+      if (unsafe.length) refuse('M012', `${name} has ${unsafe.join(', ')}: an image with active content or external references is not stored.`)
+      const svg = new TextEncoder().encode(optimize(text, { multipass: true }).data)
+      return store(hash, svg, { kind: 'vector', src: url(hash, size.width), width: size.width, height: size.height, type: MIME.svg, sources: [], name, quality: 'original' }, { ladder: [size.width], type: MIME.svg })
+    }
+    let meta
+    try { meta = await sharp(bytes, { animated: true }).metadata() } catch { refuse('M018', `${name} isn't an image weft can read (PNG, JPEG, GIF, WebP, AVIF, SVG).`) }
+    const turned = (meta.orientation ?? 1) >= 5
+    const tall = meta.pageHeight ?? meta.height
+    const width = turned ? tall : meta.width
+    const height = turned ? meta.width : tall
+    if (meta.format === 'gif' && (meta.pages ?? 1) > 1) { // Animated: video when that's a saving, else as it is.
+      mkdirSync(join(dir, hash), { recursive: true })
+      const video = await timed.gif(hash, bytes, name, meta)
+      if (video) return video
+      return store(hash, bytes, { kind: 'graphic', src: url(hash, width), width, height, type: MIME.gif, sources: [], name, quality: 'original' }, { ladder: [width], type: MIME.gif })
+    }
+    const photo = isPhoto(meta)
+    const fallback = photo ? 'jpeg' : 'png'
+    const largest = Math.min(width, o.widths.at(-1))
+    const ladder = [...new Set([...o.widths.filter(w => w < largest), largest])]
+    const asset = {
+      kind: photo ? 'photo' : 'graphic', src: url(hash, largest), width, height, type: MIME[fallback],
+      sources: [{ type: MIME[fallback], srcset: ladder.map(w => `${url(hash, w)} ${w}w`).join(', ') }], name, quality: 'fixed',
+    }
+    if (o.placeholder) {
+      const base = () => sharp(bytes).rotate()
+      asset.dominant = hex((await base().stats()).dominant)
+      asset.placeholder = `data:image/webp;base64,${(await base().resize(16, 16, { fit: 'inside' }).webp({ quality: 40 }).toBuffer()).toString('base64')}`
+    }
+    return store(hash, bytes, asset, { ladder, fallback })
+  }
+
+  /** One variant, encoded once: concurrent requests share the encode, and the file lands whole or not at all. */
+  function variant(hash, width, format) {
+    const file = join(dir, hash, `${width}.${EXT[format]}`)
+    if (existsSync(file)) return readFileSync(file)
+    const key = `${hash}/${width}.${format}`
+    if (!flight.has(key)) {
+      const work = (async () => {
+        const img = sharp(readFileSync(join(dir, hash, 'source'))).rotate().resize({ width })
+        const bytes = await encoders[format](img, FIXED[format]).toBuffer()
+        const tmp = `${file}.${process.pid}.tmp`
+        writeFileSync(tmp, bytes)
+        renameSync(tmp, file)
+        return bytes
+      })().finally(() => flight.delete(key))
+      flight.set(key, work)
+    }
+    return flight.get(key)
+  }
+
+  async function serve({ hash, width, format, accept }) {
+    const meta = /^[0-9a-f]{32}$/.test(hash) ? metaOf(hash) : null
+    if (meta?.timed) return FORMATS_TIMED.has(format) ? timed.serve(hash, meta, width, format) : null
+    if (!meta?.ladder.includes(width)) return null
+    const negotiated = format === 'auto'
+    if (meta.type) return negotiated ? { bytes: readFileSync(join(dir, hash, 'source')), type: meta.type, width, format: 'source', negotiated: false } : null
+    const fmt = negotiated ? negotiate(accept, o.formats, meta.fallback) : FORMAT[format]
+    if (!fmt || !(fmt === meta.fallback || o.formats.includes(fmt))) return null
+    return { bytes: new Uint8Array(await variant(hash, width, fmt)), type: MIME[fmt], width, format: fmt, negotiated }
+  }
+
+  return { ingest, serve, settled: timed.settled }
+}

package/src/shared.mjs

@@ -0,0 +1,29 @@
+// What build.mjs and server.mjs both need: the defaults, the encoder calls and the MIME table. It lives apart so the build
+// can call the server for `encoder: 'server'` without the two importing each other.
+
+/** Every option's default: the width ladder, the quality search, the placeholder, the GIF limit, the video ladder. */
+export const DEFAULTS = {
+  formats: ['avif'],
+  widths: [320, 640, 960, 1280, 1920, 2560],
+  quality: { target: 80, scorer: 'ssimulacra2' },
+  placeholder: true,
+  gifLimit: 256 * 1024,
+  video: { codecs: ['av1'], widths: [640, 960, 1280, 1920] },
+}
+/** Encoder settings without a scorer (research 26 §2.4). */
+export const FIXED = { avif: 50, webp: 75, jpeg: 78 }
+/** Content types of the formats this package writes. */
+export const MIME = { avif: 'image/avif', webp: 'image/webp', jpeg: 'image/jpeg', png: 'image/png', gif: 'image/gif', svg: 'image/svg+xml' }
+
+/** One sharp call per format: quality in, a configured pipeline out. PNG takes no quality. */
+export const encoders = {
+  avif: (img, q) => img.avif({ quality: q, effort: 4, chromaSubsampling: '4:2:0' }),
+  webp: (img, q) => img.webp({ quality: q, effort: 5 }),
+  jpeg: (img, q) => img.jpeg({ quality: q, mozjpeg: true }),
+  png: img => img.png({ compressionLevel: 9, effort: 8 }),
+}
+
+/** A sharp `dominant` colour as `#rrggbb`. */
+export const hex = ({ r, g, b }) => `#${[r, g, b].map(v => v.toString(16).padStart(2, '0')).join('')}`
+/** Lossy sources get a lossy fallback; a WebP with alpha is a graphic. */
+export const isPhoto = meta => ['jpeg', 'jpg', 'avif', 'heif', 'tiff', 'webp'].includes(meta.format) && !(meta.format === 'webp' && meta.hasAlpha)

package/src/svg.mjs

@@ -0,0 +1,15 @@
+// M012 (research 15 §7.5): SVG content that can run code or fetch something, which an image must not carry.
+
+const RULES = [
+  [/<script[\s>/]/i, '<script>'],
+  [/<foreignObject[\s>/]/i, '<foreignObject>'],
+  [/\son[a-z]+\s*=/i, 'an on* event handler'],
+  [/\s(?:xlink:)?href\s*=\s*["'](?!#|data:)[^"']/i, 'an external href'],
+  [/url\(\s*['"]?(?!#|data:)[a-z]+:/i, 'an external url()'],
+  [/@import\b/i, 'a CSS @import'],
+]
+
+/** What makes this SVG unsafe as an image, or [] when nothing does. */
+export function unsafeSvg(text) {
+  return RULES.filter(([re]) => re.test(text)).map(([, what]) => what)
+}

package/src/upload.mjs

@@ -0,0 +1,133 @@
+// Video, audio and animated GIFs through media.server@1, for uploads a build never saw (research 15 §5.4). `ingest`
+// answers with the record at once and a queue encodes the rungs one at a time, so a server isn't swamped by a burst.
+// Until a rung exists its URL gives the original if browsers can play that, marked temporary so nothing caches it, and
+// otherwise waits for that encode. A queue lost to a restart costs nothing: the first request for a rung encodes it.
+// No quality search here: fixed CRFs, and H.264 already at its width is kept (re-encoding can't win, research 15 §3.4).
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import sharp from 'sharp'
+import { ladderOf, poster } from './video.mjs'
+
+const TYPES = { mp4: 'video/mp4', webm: 'video/webm', m4a: 'audio/mp4', gif: 'image/gif', webp: 'image/webp' }
+const COMPATIBLE = 'video/h264'
+const SMALLER = 0.85
+
+/** Video or audio, from the first bytes: what ffprobe should be asked about, not what the file's name claims. */
+export function sniff(bytes) {
+  const head = new TextDecoder('latin1').decode(bytes.subarray(0, 12))
+  if (head.slice(4, 8) === 'ftyp') return /^M4A|^M4B/.test(head.slice(8, 12)) ? 'audio' : 'video'
+  if (bytes[0] === 0x1a && bytes[1] === 0x45) return 'video'
+  if (head.startsWith('RIFF') && head.slice(8, 12) === 'WAVE') return 'audio'
+  if (head.startsWith('OggS') || head.startsWith('fLaC') || head.startsWith('ID3') || (bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0)) return 'audio'
+  return null
+}
+
+const webKept = info => info.video?.codec === 'h264' && info.video.pix === 'yuv420p' && (!info.audio || info.audio.codec === 'aac')
+const playable = info => webKept(info) || (/webm/.test(info.format) && ['vp9', 'av1'].includes(info.video?.codec))
+
+export function uploads({ o, dir, encode, url, store, refuse }) {
+  const flight = new Map()
+  let line = Promise.resolve()
+  const efficient = () => (o.video.codecs ?? []).map(c => `video/${c}`).find(k => encode[k])
+  const sourceOf = hash => join(dir, hash, 'source')
+
+  /** One rung, encoded once: the queue and a waiting request share the work, and the file lands whole or not at all. */
+  function rung(hash, meta, width, format) {
+    const file = join(dir, hash, `${width}.${format}`)
+    if (existsSync(file)) return readFileSync(file)
+    const key = `${hash}/${width}.${format}`
+    if (!flight.has(key)) {
+      const work = (async () => {
+        const audio = meta.kind === 'audio'
+        const enc = encode[audio ? (format === 'webm' ? 'audio/opus' : 'audio/aac') : format === 'webm' ? meta.webm : COMPATIBLE]
+        const copy = meta.keepTop === width && format === 'mp4'
+        const bytes = await enc.encode(sourceOf(hash), audio ? {} : copy ? { copy } : { width, knob: enc.knob.fixed })
+        const tmp = `${file}.${process.pid}.tmp`
+        writeFileSync(tmp, bytes)
+        renameSync(tmp, file)
+        return bytes
+      })().finally(() => flight.delete(key))
+      flight.set(key, work)
+    }
+    return flight.get(key)
+  }
+
+  const enqueue = (hash, meta) => {
+    for (const [width, format] of meta.rungs) line = line.then(() => rung(hash, meta, width, format)).catch(e => console.error(`media: ${hash}: ${e.message}`))
+  }
+
+  const record = (hash, rungs, types) => [...new Set(rungs.map(r => r[1]))].map(format => ({ type: types[format], srcset: rungs.filter(r => r[1] === format).map(([w]) => `${url(hash, w, format)} ${w || 1}w`).join(', ') }))
+
+  /** Rungs for a video: AV1 or VP9 first when there's something to gain, H.264 always. */
+  function videoRungs(info, width) {
+    const widths = ladderOf(o, width)
+    const keepTop = webKept(info) && widths.at(-1) === width ? width : undefined
+    const webm = keepTop === undefined ? efficient() : undefined
+    return { keepTop, webm, rungs: [...(webm ? widths.map(w => [w, 'webm']) : []), ...widths.map(w => [w, 'mp4'])] }
+  }
+
+  const hasCopy = () => o.encoder === 'compatible'
+  const compatible = asset => (hasCopy() ? { ...asset, swap: o.swap ?? 'intent' } : asset)
+
+  async function video(hash, bytes, name, info, extra = {}) {
+    const { width, height } = info.video
+    const plan = videoRungs(info, width)
+    const types = { webm: `video/webm; codecs="${plan.webm === 'video/vp9' ? 'vp9' : 'av01.0.08M.08'}${info.audio ? ', opus' : ''}"`, mp4: 'video/mp4' }
+    const cover = await poster(encode[COMPATIBLE], sourceOf(hash), 'poster', width, info.duration, o)
+    writeFileSync(join(dir, hash, 'poster.webp'), cover.file.bytes)
+    const top = url(hash, plan.rungs.at(-1)[0], 'mp4')
+    const asset = compatible({ kind: 'video', src: top, width, height, type: 'video/mp4', sources: record(hash, plan.rungs, types), name, quality: 'fixed', duration: info.duration, audio: !!info.audio, ...cover.asset, poster: url(hash, 0, 'webp'), ...(plan.webm && hasCopy() && { copy: { src: top, type: 'video/mp4' } }), ...extra.asset })
+    const meta = { kind: 'video', timed: true, ...plan, playable: playable(info) }
+    return { asset, meta }
+  }
+
+  async function ingest(hash, bytes, name, kind) {
+    const enc = encode[COMPATIBLE]
+    writeFileSync(sourceOf(hash), bytes)
+    const info = await enc.info(sourceOf(hash)).catch(() => null)
+    if (kind === 'audio') {
+      if (!info?.audio) refuse('M018', `${name} has no audio track weft can read.`)
+      const rungs = [...(encode['audio/opus'] ? [[0, 'webm']] : []), [0, 'm4a']]
+      const asset = { kind: 'audio', src: url(hash, 0, 'm4a'), width: 0, height: 0, type: 'audio/mp4', sources: record(hash, rungs, { webm: 'audio/webm; codecs="opus"', m4a: 'audio/mp4; codecs="mp4a.40.2"' }), name, quality: 'fixed', duration: info.duration, audio: true }
+      const meta = { kind, timed: true, rungs }
+      enqueue(hash, meta)
+      return store(hash, bytes, asset, meta)
+    }
+    if (!info?.video) refuse('M018', `${name} has no video track weft can read.`)
+    const { asset, meta } = await video(hash, bytes, name, info)
+    enqueue(hash, meta)
+    return store(hash, bytes, asset, meta)
+  }
+
+  /** An animated GIF: null when it should stay one (the rules in src/video.mjs, on the top H.264 rung). */
+  async function gif(hash, bytes, name, meta) {
+    if (!encode[COMPATIBLE] || bytes.length < (o.gif?.keepUnder ?? 8192) || (meta.pages ?? 1) < 4 || o.gif?.toVideo === 'never') return null
+    if (!(await sharp(bytes, { animated: true }).stats()).isOpaque) return null
+    writeFileSync(sourceOf(hash), bytes)
+    const info = await encode[COMPATIBLE].info(sourceOf(hash))
+    const width = meta.width
+    const height = meta.pageHeight ?? meta.height
+    const delays = meta.delay ?? []
+    const duration = delays.length ? delays.reduce((a, b) => a + (b < 20 ? 100 : b), 0) / 1000 : info.duration
+    const full = { ...info, duration, video: { ...info.video, width, height } }
+    const { asset, meta: plan } = await video(hash, bytes, name, full)
+    const top = plan.rungs.at(-1)[0]
+    if ((await rung(hash, plan, top, 'mp4')).length > bytes.length * SMALLER) return null
+    Object.assign(asset, { animated: true, audio: false, loop: meta.loop ?? 0 })
+    if (hasCopy()) asset.copy = { src: url(hash, width, 'gif'), type: 'image/gif', bytes: bytes.length }
+    plan.gif = width
+    enqueue(hash, plan)
+    return store(hash, bytes, asset, plan)
+  }
+
+  async function serve(hash, meta, width, format) {
+    if (format === 'webp' && width === 0) return { bytes: readFileSync(join(dir, hash, 'poster.webp')), type: TYPES.webp, width, format, negotiated: false }
+    if (format === 'gif' && meta.gif === width) return { bytes: readFileSync(sourceOf(hash)), type: TYPES.gif, width, format, negotiated: false }
+    if (!meta.rungs.some(([w, f]) => w === width && f === format)) return null
+    const ready = existsSync(join(dir, hash, `${width}.${format}`))
+    if (!ready && meta.playable) return { bytes: readFileSync(sourceOf(hash)), type: TYPES[format], width, format, negotiated: false, temporary: true }
+    return { bytes: new Uint8Array(await rung(hash, meta, width, format)), type: meta.kind === 'audio' && format === 'webm' ? 'audio/webm' : TYPES[format], width, format, negotiated: false }
+  }
+
+  return { ingest, gif, serve, settled: () => line }
+}

package/src/video.mjs

@@ -0,0 +1,268 @@
+// Video, audio and GIF-to-video for media.build@1 (research 15 §3.3–3.4), through whichever providers media.encode@1
+// has bound (`@weft-js/plugin-media-ffmpeg`).
+//   Keep what is already delivered: an H.264 source at or under the top width is remuxed, not re-encoded, and an
+//   efficient codec has to beat the H.264 file by 15% to ship (re-encoding a lossy source can't win at a fixed target).
+//   Quality: a CRF search at the top width, sampled SSIMULACRA2 frames with mean ≥ target and worst frame ≥ target − 5.
+//   A mean alone lets AV1 hide ugly frames (research 15 measured 55 inside an 80 mean). No scorer: fixed CRFs.
+//   GIFs stay GIFs under 8 KB, under 4 frames, with real transparency (H.264 has no alpha; animated WebP does), or when
+//   nothing is 15% smaller. Noisy GIFs came out 70–180% larger as video.
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { extname, join } from 'node:path'
+import { promisify } from 'node:util'
+import sharp from 'sharp'
+
+const run = promisify(execFile)
+export const VIDEO = /\.(mp4|m4v|mov|webm|mkv|ogv)$/i
+export const AUDIO = /\.(mp3|wav|flac|ogg|oga|opus|m4a|aac)$/i
+const SMALLER = 0.85
+const COMPATIBLE = 'video/h264'
+const short = bytes => createHash('sha256').update(bytes).digest('hex').slice(0, 8)
+const need = (o, key) => ({ code: 'P101', severity: 'error', message: `${o} needs \`media.encode\` for ${key}, and nothing provides it. Add \`mediaFfmpeg()\` from @weft-js/plugin-media-ffmpeg to \`plugins\` in weft.config.ts.` })
+const errored = (name, e) => ({ asset: null, files: [], diagnostics: [{ code: e.code ?? 'M019', severity: 'error', message: `${name}: ${e.message}` }] })
+
+/** A temp file for ffmpeg to read: `work(path)` runs with the bytes on disk. */
+async function onDisk(name, bytes, work) {
+  const dir = mkdtempSync(join(tmpdir(), 'weft-media-'))
+  try {
+    const path = join(dir, `in${extname(name).toLowerCase()}`)
+    writeFileSync(path, bytes)
+    return await work(path, dir)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+const sourceType = (enc, info) => {
+  const container = enc.ext === 'webm' ? 'video/webm' : 'video/mp4'
+  return `${container}; codecs="${[info.video?.string, info.audio?.string].filter(Boolean).join(', ')}"`
+}
+
+/** SSIMULACRA2 over `times`: mean ≥ target and worst ≥ target − 5. */
+async function passes(enc, source, encoded, ctx) {
+  return onDisk(`x.${enc.ext}`, encoded, async (file, dir) => {
+    const scores = []
+    for (const [i, at] of ctx.times.entries()) {
+      const ref = join(dir, `ref${i}.png`)
+      const out = join(dir, `out${i}.png`)
+      writeFileSync(ref, await enc.still(source, { at, width: ctx.width }))
+      writeFileSync(out, await enc.still(file, { at, width: ctx.width }))
+      scores.push(parseFloat((await run(ctx.scorer, [ref, out])).stdout))
+    }
+    return scores.reduce((a, b) => a + b) / scores.length >= ctx.target && Math.min(...scores) >= ctx.target - 5
+  })
+}
+
+/** The highest CRF that passes, within 4 encodes. Video-only: audio has its own bitrate. */
+async function search(enc, source, ctx) {
+  let { min: lo, max: hi } = enc.knob
+  let best = lo
+  for (let i = 0; i < 4 && lo <= hi; i++) {
+    const knob = Math.round((lo + hi) / 2)
+    if (await passes(enc, source, await enc.encode(source, { knob, width: ctx.width, audio: false }), ctx)) {
+      best = knob
+      lo = knob + 1
+    } else hi = knob - 1
+  }
+  return best
+}
+
+/** One codec at every width, biggest last. */
+async function rungs(enc, stem, codec, source, widths, knob, { keepTop, audio, loopVideo }) {
+  const out = []
+  for (const width of widths) {
+    const copy = keepTop && width === widths.at(-1)
+    const bytes = await enc.encode(source, copy ? { copy, audio } : { knob, width, audio, loopVideo })
+    out.push({ width, bytes, name: `${stem}-${width}-${codec}-${short(bytes)}.${enc.ext}` })
+  }
+  const info = await onDisk(`x.${enc.ext}`, out.at(-1).bytes, file => enc.info(file))
+  return { key: enc.key, type: sourceType(enc, info), rungs: out, size: out.at(-1).bytes.length }
+}
+
+async function encodersFor(o, encode) {
+  const keys = [...new Set([...o.video.codecs.map(c => `video/${c}`), COMPATIBLE])]
+  const found = []
+  const diagnostics = []
+  for (const key of keys) {
+    const enc = encode[key]
+    if (enc && (await enc.encoderName())) found.push(enc)
+    else if (key === COMPATIBLE) return { error: enc ? null : need('Video', key), found, diagnostics }
+    else diagnostics.push({ code: 'M019', severity: 'warning', message: `No encoder for ${key}: it is left out of the ladder.` })
+  }
+  return { found, diagnostics }
+}
+
+/** The poster, its dominant colour and the placeholder, from one frame. */
+export async function poster(enc, source, stem, width, duration, o) {
+  const png = await enc.still(source, { at: Math.min(1, duration / 10), width })
+  const bytes = await sharp(png).webp({ quality: 80 }).toBuffer()
+  const name = `${stem}-poster-${short(bytes)}.webp`
+  const asset = { poster: name }
+  if (o.placeholder) {
+    const stats = await sharp(png).stats()
+    asset.dominant = `#${['r', 'g', 'b'].map(c => stats.dominant[c].toString(16).padStart(2, '0')).join('')}`
+    asset.placeholder = `data:image/webp;base64,${(await sharp(png).resize(16, 16, { fit: 'inside' }).webp({ quality: 40 }).toBuffer()).toString('base64')}`
+  }
+  return { asset, file: { name, bytes: new Uint8Array(bytes) } }
+}
+
+export const ladderOf = (o, width) => {
+  const top = Math.min(width, o.video.widths.at(-1))
+  return [...new Set([...o.video.widths.filter(w => w < top), top])]
+}
+
+async function encodeLadder(stem, source, info, o, encode, { widths, keepTop, audio, loopVideo, scorer }) {
+  const { found, diagnostics, error } = await encodersFor(o, encode)
+  if (error) return { error }
+  const top = widths.at(-1)
+  const { duration } = info
+  const times = [0.05, 0.25, 0.45, 0.65, 0.85].map(f => Math.round(duration * f * 1000) / 1000)
+  const ctx = { times, width: top, scorer, target: o.quality.target }
+  const compatible = found.find(e => e.key === COMPATIBLE)
+  const qualities = {}
+  const sets = []
+  for (const enc of [compatible, ...found.filter(e => e !== compatible)]) {
+    const kept = keepTop && enc === compatible
+    const knob = scorer && !kept ? await search(enc, source, ctx) : enc.knob.fixed
+    qualities[enc.key.slice(6)] = knob
+    sets.push(await rungs(enc, stem, enc.key.slice(6), source, widths, knob, { keepTop: kept, audio, loopVideo }))
+  }
+  return { sets, qualities, diagnostics }
+}
+
+
+/** Efficient sets first, H.264 last, dropping any that doesn't beat H.264 by 15%. */
+function chosen(sets) {
+  const [compatible, ...rest] = sets
+  const winners = rest.filter(s => s.size <= compatible.size * SMALLER).sort((a, b) => a.size - b.size)
+  return [...winners, compatible]
+}
+
+function finish(asset, sets, cover, diagnostics) {
+  const files = sets.flatMap(s => s.rungs.map(r => ({ name: r.name, bytes: r.bytes })))
+  if (cover) files.push(cover.file)
+  const compatible = sets.at(-1)
+  const top = compatible.rungs.at(-1)
+  const out = { ...asset, ...cover?.asset, src: top.name, sources: sets.map(s => ({ type: s.type, srcset: s.rungs.map(r => `${r.name} ${r.width}w`).join(', ') })) }
+  return { asset: out, files, diagnostics }
+}
+
+/** The compatible copy `encoder: 'compatible'` swaps in, and M014 with what it adds. */
+function withCopy(out, o, name, copy) {
+  if (o.encoder !== 'compatible' || !copy) return out
+  const efficient = out.files.filter(f => f.name !== copy.src && f.name.endsWith('.webm')).at(-1)?.bytes.length ?? copy.bytes
+  out.asset.copy = { src: copy.src, type: copy.type, bytes: copy.bytes, ratio: Math.round((copy.bytes / efficient) * 100) / 100 }
+  out.asset.swap = o.swap ?? 'intent'
+  out.diagnostics.push({ code: 'M014', severity: 'info', message: `${name}: \`encoder: 'compatible'\` adds ${Math.round((copy.added ?? 0) / 1024)} KB for the compatible copy.` })
+  return out
+}
+
+export async function video({ bytes, name, stem, audio }, o, encode, scorer) {
+  const probe = encode[COMPATIBLE]
+  if (!probe) return { asset: null, files: [], diagnostics: [need(name, COMPATIBLE)] }
+  try {
+    return await onDisk(name, bytes, async source => {
+      const info = await probe.info(source)
+      if (!info.video) return { asset: null, files: [], diagnostics: [{ code: 'M018', severity: 'error', message: `${name} has no video track.` }] }
+      const { width, height, hdr, codec, pix } = info.video
+      const widths = ladderOf(o, width)
+      const keepTop = !audio && codec === 'h264' && pix === 'yuv420p' && widths.at(-1) === width && (!info.audio || info.audio.codec === 'aac')
+      const built = await encodeLadder(stem, source, info, o, encode, { widths, keepTop, audio, scorer })
+      if (built.error) return { asset: null, files: [], diagnostics: [built.error] }
+      const sets = chosen(built.sets)
+      const cover = await poster(probe, source, stem, widths.at(-1), info.duration, o)
+      const diagnostics = built.diagnostics
+      if (hdr) diagnostics.push({ code: 'M015', severity: 'warning', message: `${name} is HDR or over 8 bits, and comes out 8-bit SDR.` })
+      const asset = { kind: 'video', width, height, type: 'video/mp4', name, quality: scorer ? 'ssimulacra2' : 'fixed', qualities: built.qualities, duration: info.duration, audio: !!(audio || info.audio) }
+      const out = finish(asset, sets, cover, diagnostics)
+      const top = sets.at(-1).rungs.at(-1)
+      return withCopy(out, o, name, sets.length > 1 ? { src: top.name, type: 'video/mp4', bytes: top.bytes.length, added: 0 } : null)
+    })
+  } catch (e) {
+    return errored(name, e)
+  }
+}
+
+export async function audioFile({ bytes, name, stem }, o, encode) {
+  const opus = encode['audio/opus']
+  const aac = encode['audio/aac']
+  if (!aac) return { asset: null, files: [], diagnostics: [need(name, 'audio/aac')] }
+  try {
+    return await onDisk(name, bytes, async source => {
+      const info = await aac.info(source)
+      if (!info.audio) return { asset: null, files: [], diagnostics: [{ code: 'M018', severity: 'error', message: `${name} has no audio track.` }] }
+      const under = limit => !info.audio.bitrate || info.audio.bitrate <= limit
+      const sets = []
+      for (const [enc, codec, limit] of [[opus, 'opus', 96_000], [aac, 'aac', 128_000]]) {
+        if (!enc || !(await enc.encoderName())) continue
+        const encoded = await enc.encode(source, { copy: info.audio.codec === codec && under(limit) })
+        const type = `${enc.ext === 'webm' ? 'audio/webm' : 'audio/mp4'}; codecs="${(await onDisk(`x.${enc.ext}`, encoded, f => enc.info(f))).audio.string}"`
+        sets.push({ type, name: `${stem}-${short(encoded)}.${enc.ext}`, bytes: encoded })
+      }
+      const last = sets.at(-1)
+      return {
+        asset: { kind: 'audio', src: last.name, width: 0, height: 0, type: 'audio/mp4', name, quality: 'fixed', duration: info.duration, audio: true, sources: sets.map(s => ({ type: s.type, srcset: `${s.name} 1w` })) },
+        files: sets.map(s => ({ name: s.name, bytes: s.bytes })),
+        diagnostics: [],
+      }
+    })
+  } catch (e) {
+    return errored(name, e)
+  }
+}
+
+/** Animated GIF: video when that's a real saving, animated WebP when it has transparency, else null (it stays a GIF). */
+export async function gif({ bytes, name, stem, audio, meta, width, height }, o, encode, scorer) {
+  const frames = meta.pages ?? 1
+  const toVideo = o.gif?.toVideo ?? 'auto'
+  if (toVideo === 'never' || !encode[COMPATIBLE]) return null
+  const keep = o.gif?.keepUnder ?? 8192
+  if (!audio && (bytes.length < keep || frames < 4)) return null
+  const opaque = (await sharp(bytes, { animated: true }).stats()).isOpaque
+  if (!opaque) return audio ? null : alphaWebp({ bytes, name, stem, width, height })
+  try {
+    return await onDisk(name, bytes, async source => {
+      const probe = encode[COMPATIBLE]
+      const info = await probe.info(source)
+      const delays = meta.delay ?? []
+      const total = delays.length ? delays.reduce((a, b) => a + (b < 20 ? 100 : b), 0) / 1000 : info.duration
+      const widths = ladderOf(o, width)
+      const built = await encodeLadder(stem, source, { ...info, duration: total }, o, encode, { widths, audio, loopVideo: !!audio, scorer })
+      if (built.error) return null
+      const sets = chosen(built.sets)
+      const smallest = Math.min(...sets.map(s => s.size))
+      if (!audio && smallest > bytes.length * SMALLER) return null
+      if (!audio) {
+        const check = await onDisk(`x.${sets[0].rungs.at(-1).name.split('.').pop()}`, sets[0].rungs.at(-1).bytes, f => probe.info(f))
+        if (Math.abs(check.duration - total) > Math.max(0.15, total * 0.05)) built.diagnostics.push({ code: 'M019', severity: 'warning', message: `${name}: the video runs ${check.duration} s, the GIF ${total} s.` })
+      }
+      const [winner, compatible] = sets.length > 1 ? [sets[0], sets.at(-1)] : [null, sets[0]]
+      const served = winner ? [winner, compatible] : [compatible]
+      const cover = await poster(probe, source, stem, widths.at(-1), total, o)
+      const asset = { kind: 'video', width, height, type: 'video/mp4', name, quality: scorer ? 'ssimulacra2' : 'fixed', qualities: built.qualities, duration: total, audio: !!audio, animated: !audio, loop: meta.loop ?? 0 }
+      const out = finish(asset, served, cover, built.diagnostics)
+      if (o.encoder === 'compatible') {
+        const original = `${stem}-${short(bytes)}.gif`
+        out.files.push({ name: original, bytes })
+        return withCopy(out, o, name, { src: original, type: 'image/gif', bytes: bytes.length, added: bytes.length })
+      }
+      return out
+    })
+  } catch (e) {
+    return errored(name, e)
+  }
+}
+
+async function alphaWebp({ bytes, name, stem, width, height }) {
+  const webp = await sharp(bytes, { animated: true }).webp({ quality: 80, effort: 5 }).toBuffer()
+  if (webp.length > bytes.length * SMALLER) return null
+  const fileName = `${stem}-${short(webp)}.webp`
+  const original = `${stem}-${short(bytes)}.gif`
+  return {
+    asset: { kind: 'graphic', src: original, width, height, type: 'image/gif', sources: [{ type: 'image/webp', srcset: `${fileName} ${width}w` }, { type: 'image/gif', srcset: `${original} ${width}w` }], name, quality: 'fixed', loop: 0 },
+    files: [{ name: fileName, bytes: new Uint8Array(webp) }, { name: original, bytes }],
+    diagnostics: [],
+  }
+}