@weft-js/plugin-media 0.1.1 → 0.1.4

package/src/index.mjs

@@ -1,12 +1,22 @@
-// media() for weft.config.ts (research 15 §7.4, research 26 §2, research 29 §6): provides media.build@1 (src/build.mjs,
+// media() for weft.config.ts: 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 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']
 
@@ -14,55 +24,109 @@ 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
-  }
+function playbackOptions(input, out) {
   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)`)
+      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')
+    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')
+    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')
+    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
   }
+}
+
+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
+  }
+  playbackOptions(input, out)
   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)`)
+    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')
+    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")
+    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.placeholder !== undefined) {
+    if (![true, false, 'inline', 'file'].includes(input.placeholder))
+      fail(
+        'placeholder',
+        "true or 'inline' (a data: URL), 'file' (its own file, for a strict CSP), or false",
+      )
+    out.placeholder = input.placeholder === 'inline' ? true : input.placeholder
+  }
   if (input.gifLimit !== undefined) out.gifLimit = input.gifLimit
   return out
 }
@@ -95,21 +159,55 @@ export const media = definePlugin({
   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 }) },
+  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.",
+        '- 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).",
+        '- 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' }],
+    catalog: [
+      {
+        name: 'Media',
+        import: '@weft-js/core/media',
+        summary: '<Media src={x} alt>: dimensions, AVIF + fallback, srcset/sizes, placeholder',
+      },
+    ],
   }),
 })

package/src/server/ingest.mjs

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import sharp from 'sharp'
+import { optimize } from 'svgo'
+import { probe } from '@weft-js/core/media-probe'
+import { hex, isPhoto, MIME } from '../shared.mjs'
+import { unsafeSvg } from '../svg.mjs'
+import { sniff } from '../upload.mjs'
+
+export function imageIngest({ limit, metaOf, dir, encode, timed, url, store, refuse, o }) {
+  return 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')
+      return storeSvg(hash, bytes, name, size, { refuse, url, store })
+    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 },
+      )
+    }
+    return storeRaster({ meta, width, height, o, url, hash, name, bytes, store })
+  }
+}
+
+function storeSvg(hash, bytes, name, size, { refuse, url, store }) {
+  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 },
+  )
+}
+
+async function storeRaster({ meta, width, height, o, url, hash, name, bytes, store }) {
+  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 })
+}

package/src/server/serve.mjs

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import sharp from 'sharp'
+import { FIXED, encoders, MIME } from '../shared.mjs'
+
+const FORMATS_TIMED = new Set(['mp4', 'webm', 'm4a', 'gif', 'webp'])
+const EXT = { avif: 'avif', webp: 'webp', jpeg: 'jpg', png: 'png' }
+const FORMAT = { avif: 'avif', webp: 'webp', jpg: 'jpeg', png: 'png' }
+
+export function imageServe({ dir, flight, metaOf, timed, o, negotiate }) {
+  /** 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 serve
+}

package/src/server.mjs

@@ -1,23 +1,16 @@
-// 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>`,
+// `ingest` stores an original under its hash and returns a `z.media()` record; `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'
+import { DEFAULTS, MIME } from './shared.mjs'
+import { uploads } from './upload.mjs'
+import { imageIngest } from './server/ingest.mjs'
+import { imageServe } from './server/serve.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 })
@@ -28,10 +21,10 @@ 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)
+    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
+  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`. */
@@ -41,11 +34,13 @@ export function createMediaServer(input = {}) {
 }
 
 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 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 metaOf = (hash) => {
     const file = join(dir, hash, 'meta.json')
     return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null
   }
@@ -62,82 +57,9 @@ function storage(o, root, encode) {
 
   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)
-  }
+  const ingest = imageIngest({ limit, metaOf, dir, encode, timed, url, store, refuse, o })
 
-  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 }
-  }
+  const serve = imageServe({ dir, flight, metaOf, timed, o, negotiate })
 
   return { ingest, serve, settled: timed.settled }
 }

package/src/shared.mjs

@@ -1,6 +1,8 @@
 // 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.
 
+import { createHash } from 'node:crypto'
+
 /** Every option's default: the width ladder, the quality search, the placeholder, the GIF limit, the video ladder. */
 export const DEFAULTS = {
   formats: ['avif'],
@@ -10,20 +12,44 @@ export const DEFAULTS = {
   gifLimit: 256 * 1024,
   video: { codecs: ['av1'], widths: [640, 960, 1280, 1920] },
 }
-/** Encoder settings without a scorer (research 26 §2.4). */
+/** Encoder settings without a scorer. */
 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' }
+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 }),
+  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('')}`
+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)
+export const isPhoto = (meta) =>
+  ['jpeg', 'jpg', 'avif', 'heif', 'tiff', 'webp'].includes(meta.format) &&
+  !(meta.format === 'webp' && meta.hasAlpha)
+
+/**
+ * Adds the 16 px placeholder from `img` (a sharp pipeline) to `asset`. Inline it's a `data:` URL; with
+ * `placeholder: 'file'` it's a file of its own pushed to `files`, for a CSP whose `img-src` has no `data:`.
+ */
+export async function withPlaceholder(asset, files, img, stem, o) {
+  const tiny = await img.resize(16, 16, { fit: 'inside' }).webp({ quality: 40 }).toBuffer()
+  if (o.placeholder !== 'file') {
+    asset.placeholder = `data:image/webp;base64,${tiny.toString('base64')}`
+    return
+  }
+  asset.placeholder = `${stem}-placeholder-${createHash('sha256').update(tiny).digest('hex').slice(0, 8)}.webp`
+  files.push({ name: asset.placeholder, bytes: new Uint8Array(tiny) })
+}

package/src/upload/gif.mjs

@@ -0,0 +1,46 @@
+import { writeFileSync } from 'node:fs'
+import sharp from 'sharp'
+
+export function createGif({
+  encode,
+  o,
+  sourceOf,
+  video,
+  rung,
+  hasCopy,
+  url,
+  enqueue,
+  store,
+  COMPATIBLE,
+  SMALLER,
+}) {
+  /** An animated GIF: null when it should stay one (the rules in src/video.mjs, on the top H.264 rung). */
+  return 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)
+  }
+}