@weft-js/plugin-media 0.1.3 → 0.1.5-nightly.20261111.3

package/README.md

@@ -105,7 +105,7 @@ import { media } from '@weft-js/plugin-media'
 
 | Need | Why |
 | --- | --- |
-| Node 26 or later | `engines` in package.json |
+| Node 24 or later | `engines` in package.json |
 | `sharp` (a dependency of this package) | Every raster encode. For the media route, the **app** needs `sharp` in its own dependencies so the built server can load it; a build without it warns with M017. |
 | `ssimulacra2` on `PATH` (optional) | The quality search. It's the SSIMULACRA2 tool from libjxl. Without it, fixed qualities are used. |
 | A disk that outlives deploys (for uploads) | The media route stores files in `.weft/media`, or `WEFT_MEDIA_DIR`. |
@@ -172,7 +172,7 @@ All options are optional. `media()` with none is the configuration the defaults
 | `widths` | `number[]` | `[320, 640, 960, 1280, 1920, 2560]` | The width ladder, sorted for you. The largest also caps the output width. |
 | `quality.target` | `number` (1–100) | `80` | The SSIMULACRA2 score each format is searched to. 80 is about visually lossless at normal viewing. |
 | `quality.scorer` | `string` | `'ssimulacra2'` | The scorer command, or `'none'` to use fixed qualities. |
-| `placeholder` | `boolean` | `true` | Adds `dominant` (a `#rrggbb` colour) and `placeholder` (a 16 px WebP data URL). |
+| `placeholder` | `boolean` · `'inline'` · `'file'` | `true` | Adds `dominant` (a `#rrggbb` colour) and `placeholder`, a 16 px WebP. `true` or `'inline'`: a `data:` URL. `'file'`: its own hashed file, for a CSP without `data:` in `img-src`. `false`: neither. |
 | `gifLimit` | `number` (bytes) | `262144` (256 KB) | A GIF over this is M004, at build and in `weft check`. |
 | `encoder` | `'off' \| 'compatible' \| 'server'` | `'off'` | See [The `encoder` modes](#the-encoder-modes). |
 | `swap` | `'intent' \| 'idle' \| 'never'` | `'intent'` | When the compatible copy swaps in. Only valid with `encoder: 'compatible'`. |
@@ -400,6 +400,17 @@ media({ formats: ['avif', 'webp'], widths: [480, 960, 1440] })
 media({ quality: { scorer: 'none' } })
 ```
 
+**A strict CSP: the placeholder as a file**
+
+```ts
+media({ placeholder: 'file' })
+```
+
+The default placeholder is a `data:` URL, which `img-src 'self'` blocks.
+With `'file'` each image and video poster gets a `name-placeholder-<hash>.webp`
+of a few hundred bytes next to its ladder, and the record points at it.
+Uploads through the media route still inline theirs.
+
 **Uploads on a mounted volume**
 
 ```bash
@@ -448,6 +459,7 @@ export const Logo = () => (
 | `M017` in the server log | No `media()` in `plugins`, or the app doesn't list `sharp` in its own dependencies. |
 | `M018` on upload | Over `server.maxBytes` (20 MB by default), not an image sharp can read, or a video with no encoder installed. |
 | `P101 … needs media.encode` | A video or audio `?media` import with no `mediaFfmpeg()` in `plugins`. |
+| CSP reports a blocked `data:image/webp` | The inline placeholder. Set `placeholder: 'file'`, or add `data:` to `img-src`. |
 | Uploaded images vanish after a deploy | The store isn't on persistent storage. Point `WEFT_MEDIA_DIR` at a volume. |
 
 ## Related packages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weft-js/plugin-media",
-  "version": "0.1.3",
+  "version": "0.1.5-nightly.20261111.3",
   "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",
   "repository": {
@@ -26,10 +26,10 @@
     "svgo": "4.1.0"
   },
   "peerDependencies": {
-    "@weft-js/core": "^0.1.3"
+    "@weft-js/core": "^0.1.5-nightly.20261111.3"
   },
   "engines": {
-    "node": ">=26"
+    "node": ">=24"
   },
   "keywords": [
     "weft"

package/src/build.mjs

@@ -14,7 +14,7 @@ import sharp from 'sharp'
 import { optimize } from 'svgo'
 import { probe } from '@weft-js/core/media-probe'
 import { createMediaServer } from './server.mjs'
-import { DEFAULTS, FIXED, encoders, hex, isPhoto, MIME } from './shared.mjs'
+import { DEFAULTS, FIXED, encoders, hex, isPhoto, MIME, withPlaceholder } from './shared.mjs'
 import { unsafeSvg } from './svg.mjs'
 import { AUDIO, audioFile, gif, VIDEO, video } from './video.mjs'
 
@@ -288,8 +288,7 @@ async function raster({ bytes, name, stem, audio }, o, encode) {
   }
   if (o.placeholder) {
     asset.dominant = hex((await base().stats()).dominant)
-    const tiny = await base().resize(16, 16, { fit: 'inside' }).webp({ quality: 40 }).toBuffer()
-    asset.placeholder = `data:image/webp;base64,${tiny.toString('base64')}`
+    await withPlaceholder(asset, files, base(), stem, o)
   }
   return { asset, files, diagnostics }
 }

package/src/index.d.ts

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

package/src/index.mjs

@@ -119,7 +119,14 @@ function options(input) {
       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
 }

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'],
@@ -37,3 +39,17 @@ export const hex = ({ r, g, b }) =>
 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/video.mjs

@@ -28,9 +28,10 @@ export function createVideo({
       stem: 'poster',
       width,
       duration: info.duration,
-      o,
+      // The route serves only the poster and rungs, so an upload's placeholder stays inline.
+      o: { ...o, placeholder: !!o.placeholder },
     })
-    writeFileSync(join(dir, hash, 'poster.webp'), cover.file.bytes)
+    writeFileSync(join(dir, hash, 'poster.webp'), cover.files[0].bytes)
     const top = url(hash, plan.rungs.at(-1)[0], 'mp4')
     const asset = compatible({
       kind: 'video',

package/src/video.mjs

@@ -12,6 +12,7 @@ import { join } from 'node:path'
 import { promisify } from 'node:util'
 import sharp from 'sharp'
 import { errored, need, onDisk, short } from './video/common.mjs'
+import { withPlaceholder } from './shared.mjs'
 
 export { audioFile } from './video/audio.mjs'
 
@@ -104,12 +105,13 @@ export async function poster({ enc, source, stem, width, duration, o }) {
   const bytes = await sharp(png).webp({ quality: 80 }).toBuffer()
   const name = `${stem}-poster-${short(bytes)}.webp`
   const asset = { poster: name }
+  const files = [{ name, bytes: new Uint8Array(bytes) }]
   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')}`
+    await withPlaceholder(asset, files, sharp(png), stem, o)
   }
-  return { asset, file: { name, bytes: new Uint8Array(bytes) } }
+  return { asset, files }
 }
 
 export const ladderOf = (o, width) => {
@@ -170,7 +172,7 @@ function chosen(sets) {
 
 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)
+  if (cover) files.push(...cover.files)
   const compatible = sets.at(-1)
   const top = compatible.rungs.at(-1)
   const out = {