@uniweb/build 1.23.5 → 1.23.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -109,10 +109,9 @@ siteContentPlugin({
109
109
  assets: { // Asset processing (optional)
110
110
  process: true, // Process assets in production (default: true)
111
111
  convertToWebp: true, // Convert images to WebP (default: true)
112
- quality: 80, // WebP quality 1-100 (default: 80)
112
+ quality: 85, // WebP quality 1-100 (default: 85, the rule's)
113
113
  outputDir: 'assets', // Output subdirectory (default: 'assets')
114
- videoPosters: true, // Extract poster from videos (default: true, requires ffmpeg)
115
- pdfThumbnails: true // Generate PDF thumbnails (default: true, requires pdf-lib)
114
+ videoPosters: true // Extract poster from videos (default: true, requires ffmpeg)
116
115
  }
117
116
  })
118
117
  ```
@@ -149,29 +148,31 @@ seo:
149
148
 
150
149
  The plugin automatically discovers and processes assets referenced in your content. In content-driven sites, markdown acts as "code" - local asset references are like implicit imports and get optimized during build.
151
150
 
151
+ This processing is a static build's (`uniweb build`, `uniweb export`, `uniweb deploy --host`). Its pictures follow the same rule `uniweb push` and `uniweb publish` apply to what they upload (`prepareImage`, from `@uniweb/build/images`), so a picture is the same wherever the site is served.
152
+
152
153
  **Supported path formats:**
153
154
  - `./image.png` - Relative to the markdown file
154
155
  - `../shared/logo.png` - Relative paths with parent traversal
155
- - `/images/hero.png` - Absolute paths (resolved from `public/` or `assets/` folder)
156
+ - `/images/hero.png` - Absolute paths, resolved from `public/`
156
157
 
157
158
  **What gets processed:**
158
159
  - Images in markdown content: `![Alt](./photo.jpg)`
159
160
  - Media in frontmatter fields: `background`, `image`, `thumbnail`, `poster`, `avatar`, `logo`, `icon`, `video`, `pdf`, etc.
160
161
 
161
162
  **Image processing:**
162
- - PNG, JPG, JPEG, GIF → Converted to WebP for smaller file sizes
163
- - SVG, WebP, AVIF → Copied as-is (already optimized formats)
163
+ - PNG, JPG, JPEG, GIF → A WebP at quality 85 when it is at least 10% smaller, otherwise the file as it is. Either way it is turned upright as the photo's orientation says, keeps its transparency and animation, and loses its location and camera data. A WebP's colour is converted to sRGB with no profile embedded; a kept file keeps its own
164
+ - TIFF, HEIC → Always a WebP, since most browsers can't show them (a HEIC this machine can't decode, and a BMP, is copied as it is, with a warning)
165
+ - WebP → Copied without its location and camera data, or turned and made again when its orientation says to turn it
166
+ - SVG, AVIF → Copied as-is
167
+ - `public/` is copied as it is beside these copies, so a photo there keeps its metadata in that copy
164
168
  - All processed assets get content-hashed filenames for cache busting
165
169
 
166
170
  **Video poster extraction** (requires `ffmpeg` on system):
167
171
  - MP4, WebM, MOV, AVI, MKV → Poster frame extracted at 1 second
168
- - Poster images converted to WebP and added to `_assetMeta.posters`
172
+ - The poster is converted to WebP and set as the video's `poster` in the built page
169
173
  - Skipped if an explicit `poster` attribute is provided in markdown
170
174
 
171
- **PDF thumbnail generation** (requires `pdf-lib` package):
172
- - PDF files → Placeholder thumbnail with page count
173
- - Thumbnails added to `_assetMeta.thumbnails`
174
- - Skipped if an explicit `preview` attribute is provided in markdown
175
+ A PDF's preview is the one its author names with `preview`.
175
176
 
176
177
  **Explicit poster/preview images:**
177
178
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.23.5",
3
+ "version": "1.23.6",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -57,15 +57,15 @@
57
57
  "js-yaml": "^4.3.2",
58
58
  "sharp": "^0.35.5",
59
59
  "yaml": "^2.5.0",
60
- "@uniweb/projections": "~1.2.17",
61
60
  "@uniweb/content-reader": "~1.5.10",
62
- "@uniweb/content-writer": "~1.3.2",
63
- "@uniweb/semantic-parser": "~1.13.4",
61
+ "@uniweb/projections": "~1.2.17",
64
62
  "@uniweb/schemas": "~1.7.4",
65
- "@uniweb/theming": "~1.3.2"
63
+ "@uniweb/semantic-parser": "~1.13.5",
64
+ "@uniweb/theming": "~1.3.2",
65
+ "@uniweb/content-writer": "~1.3.2"
66
66
  },
67
67
  "optionalDependencies": {
68
- "@uniweb/runtime": "~1.6.4"
68
+ "@uniweb/runtime": "~1.6.5"
69
69
  },
70
70
  "peerDependencies": {
71
71
  "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
74
74
  "@tailwindcss/vite": "^4.0.0",
75
75
  "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
76
76
  "vite-plugin-svgr": "^4.0.0",
77
- "@uniweb/runtime": "~1.6.4",
78
- "@uniweb/core": "~1.6.12"
77
+ "@uniweb/core": "~1.6.13",
78
+ "@uniweb/runtime": "~1.6.5"
79
79
  },
80
80
  "peerDependenciesMeta": {
81
81
  "vite": {
package/src/images.js CHANGED
@@ -11,6 +11,9 @@ import { existsSync } from 'node:fs'
11
11
  import { join, extname, basename } from 'node:path'
12
12
  import sharp from 'sharp'
13
13
 
14
+ // The one rule for a picture a site keeps — what a push uploads, what a static build copies.
15
+ export { prepareImage, withoutPrivateMetadata, isPreparableImage, IMAGE_RULE } from './prepare-image.js'
16
+
14
17
  // Supported image extensions
15
18
  const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.gif']
16
19
 
@@ -0,0 +1,366 @@
1
+ /**
2
+ * AN IMAGE MADE READY BEFORE IT IS STORED OR SHIPPED — one rule for every picture a site keeps:
3
+ * what `uniweb push` and `uniweb publish` upload, and what a static build copies into `dist/`. So a
4
+ * picture is the same wherever the site is served.
5
+ *
6
+ * The rule:
7
+ *
8
+ * 1. **WebP, lossy, at one quality** (`IMAGE_RULE.quality`).
9
+ * 2. **The keep test.** The WebP replaces the file only when it is at most `IMAGE_RULE.keepRatio` of
10
+ * its size. Otherwise the file stays as it is. A format some browsers can't draw (TIFF, HEIC) is
11
+ * converted whatever the sizes.
12
+ * 3. **Alpha is kept**, and so is animation (a GIF's frames; an animated PNG is kept as it is, since
13
+ * its frames don't survive the conversion).
14
+ * 4. **Orientation is applied**: the pixels are turned as the photo's EXIF says. A file that would be
15
+ * kept but needs turning is converted instead, so no picture a page draws depends on a tag to
16
+ * stand up.
17
+ * 5. **Location and camera data are dropped**, from a kept file too, which loses them without being
18
+ * re-encoded (`withoutPrivateMetadata`). Its orientation stays, alone, since that is what turns
19
+ * it. **A WebP's colour is converted to sRGB, with no profile embedded**, as a host converting a
20
+ * picture that wasn't prepared does, so the two agree: a phone's Display P3 photo keeps its
21
+ * colours, managed into sRGB, and loses the wider gamut. A kept file keeps its own profile, since
22
+ * it isn't re-encoded and dropping the profile alone would shift its colours.
23
+ * 6. **No size cap.** A prepared file is the only copy kept, so it keeps its pixels.
24
+ * 7. **Which files.** JPEG, PNG, GIF, TIFF, HEIC and BMP are converted under the keep test. A WebP is
25
+ * kept without its location and camera data, unless its EXIF says to turn it. SVG, ICO and AVIF
26
+ * are left as they are, an AVIF's metadata included. A file this machine can't decode (HEIC with
27
+ * HEVC, and BMP, which sharp's builds don't read) is left as it is and reported `unreadable`, for
28
+ * its caller to say so.
29
+ * 8. **A picture other software fetches by its address** (`keepFormat`: a favicon, a touch icon, a
30
+ * social image) stays in its format, since a home screen takes a PNG and a link preview a JPEG or
31
+ * PNG. It only loses its location and camera data.
32
+ *
33
+ * Deterministic: the same bytes give the same result, so a prepared file has one identity wherever
34
+ * it is prepared with the same sharp. The quality and the keep ratio are starting points; changing
35
+ * either changes what new uploads become, and a caller that keeps what it prepared (`uniweb push`
36
+ * does, in `sync.json`) never prepares an unchanged file again because of it.
37
+ *
38
+ * @module @uniweb/build/images
39
+ */
40
+ import { crc32 } from 'node:zlib'
41
+ import sharp from 'sharp'
42
+
43
+ /** The rule's two numbers. */
44
+ export const IMAGE_RULE = Object.freeze({
45
+ /** WebP quality, lossy. */
46
+ quality: 85,
47
+ /** The WebP replaces the file only at or below this share of its size: at least 10% smaller. */
48
+ keepRatio: 0.9,
49
+ })
50
+
51
+ /** Formats the rule prepares, by extension. */
52
+ const PREPARED = new Set(['jpg', 'jpeg', 'png', 'gif', 'tif', 'tiff', 'heic', 'heif', 'bmp', 'webp'])
53
+
54
+ /** Formats every browser draws: kept when the WebP saves too little. */
55
+ const DRAWN_EVERYWHERE = new Set(['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp'])
56
+
57
+ const extOf = (ext) => String(ext || '').toLowerCase().replace(/^\./, '')
58
+
59
+ /**
60
+ * Whether the rule prepares a file with this extension.
61
+ *
62
+ * @param {string} ext - `png`, `.png` or `PNG`
63
+ * @returns {boolean}
64
+ */
65
+ export function isPreparableImage(ext) {
66
+ return PREPARED.has(extOf(ext))
67
+ }
68
+
69
+ /**
70
+ * Prepare an image under the rule.
71
+ *
72
+ * @param {Buffer} bytes - the file as its author has it
73
+ * @param {string} ext - its extension
74
+ * @param {{ quality?: number, keepFormat?: boolean }} [options] - `quality` overrides the rule's, for
75
+ * a static build whose site asks for another. `keepFormat`: a picture other software fetches by its
76
+ * address (rule 8), which only loses its private data.
77
+ * @returns {Promise<{ bytes: Buffer, ext: string, converted: boolean, unreadable?: boolean }>}
78
+ * `converted`: `bytes` is the WebP the rule made, `ext` `webp`. Otherwise `bytes` is the file as
79
+ * kept, without its location and camera data, in its own format.
80
+ */
81
+ export async function prepareImage(bytes, ext, { quality = IMAGE_RULE.quality, keepFormat = false } = {}) {
82
+ const kind = extOf(ext)
83
+ if (!PREPARED.has(kind)) return { bytes, ext: kind, converted: false }
84
+ const kept = () => ({ bytes: withoutPrivateMetadata(bytes, kind), ext: kind, converted: false })
85
+ if (keepFormat || (kind === 'png' && isAnimatedPng(bytes))) return kept()
86
+
87
+ let meta
88
+ let webp
89
+ try {
90
+ meta = await sharp(bytes, { animated: true }).metadata()
91
+ // A WebP is drawn everywhere as it is: only one its EXIF says to turn is made again.
92
+ if (kind === 'webp' && (meta.orientation || 1) === 1) return kept()
93
+ // sharp's default output: colour managed into sRGB, and every profile and tag dropped.
94
+ webp = await sharp(bytes, { animated: true })
95
+ .autoOrient()
96
+ .webp({ quality })
97
+ .toBuffer()
98
+ } catch {
99
+ // Not decodable here (HEIC with HEVC, BMP), or too large for WebP (over 16383 px a side). A
100
+ // file every browser draws is still kept without its private data; one that isn't, or that
101
+ // nothing here could read, is reported, since a page may not show it.
102
+ const drawn = DRAWN_EVERYWHERE.has(kind)
103
+ return {
104
+ bytes: drawn ? withoutPrivateMetadata(bytes, kind) : bytes,
105
+ ext: kind,
106
+ converted: false,
107
+ ...(drawn && meta ? {} : { unreadable: true }),
108
+ }
109
+ }
110
+
111
+ const turned = (meta.orientation || 1) !== 1
112
+ const smaller = webp.length <= bytes.length * IMAGE_RULE.keepRatio
113
+ if (!DRAWN_EVERYWHERE.has(kind) || turned || smaller) return { bytes: webp, ext: 'webp', converted: true }
114
+ return kept()
115
+ }
116
+
117
+ /**
118
+ * A kept file without its location and camera data, its pixels untouched. Its orientation, the one
119
+ * tag that turns the picture, stays: the first EXIF block's, written again as a block of its own.
120
+ *
121
+ * - **JPEG:** drops APP1 (EXIF and XMP), APP2 other than its colour profile, APP3–APP13 (IPTC
122
+ * among them), APP15 and comments, and whatever trails the image (a second picture a phone appends,
123
+ * with its own EXIF). Keeps JFIF (APP0), the colour profile (APP2 `ICC_PROFILE`) and Adobe's
124
+ * colour transform (APP14).
125
+ * - **PNG:** drops `eXIf`, `tEXt`, `zTXt`, `iTXt` and `tIME`, and keeps every other chunk. An `eXIf`
126
+ * after the image data turns nothing in a browser, so its orientation goes with it.
127
+ * - **WebP:** drops its `EXIF` and `XMP ` chunks and the flags that announce them, and keeps every
128
+ * other chunk.
129
+ * - Anything else, or a file that doesn't parse as its format, is returned as it is.
130
+ *
131
+ * @param {Buffer} bytes
132
+ * @param {string} ext
133
+ * @returns {Buffer}
134
+ */
135
+ export function withoutPrivateMetadata(bytes, ext) {
136
+ const kind = extOf(ext)
137
+ if (kind === 'jpg' || kind === 'jpeg') return stripJpeg(bytes) ?? bytes
138
+ if (kind === 'png') return stripPng(bytes) ?? bytes
139
+ if (kind === 'webp') return stripWebp(bytes) ?? bytes
140
+ return bytes
141
+ }
142
+
143
+ // ── EXIF: the orientation, kept alone ────────────────────────────────────────────────────────────
144
+
145
+ const EXIF_ID = Buffer.from('Exif\0\0', 'latin1')
146
+ const isExif = (payload) => payload.subarray(0, EXIF_ID.length).equals(EXIF_ID)
147
+
148
+ /** The TIFF structure in a block of EXIF, past the `Exif\0\0` that JPEG and some writers put first. */
149
+ const tiffOf = (payload) => (isExif(payload) ? payload.subarray(EXIF_ID.length) : payload)
150
+
151
+ /** The orientation a block of EXIF's first directory states, 1 when it states none. */
152
+ function orientationIn(tiff) {
153
+ if (tiff.length < 8) return 1
154
+ const little = tiff[0] === 0x49 && tiff[1] === 0x49
155
+ if (!little && !(tiff[0] === 0x4d && tiff[1] === 0x4d)) return 1
156
+ const u16 = (at) => (little ? tiff.readUInt16LE(at) : tiff.readUInt16BE(at))
157
+ const u32 = (at) => (little ? tiff.readUInt32LE(at) : tiff.readUInt32BE(at))
158
+ const directory = u32(4)
159
+ if (directory + 2 > tiff.length) return 1
160
+ for (let k = 0, count = u16(directory); k < count; k++) {
161
+ const entry = directory + 2 + k * 12
162
+ if (entry + 12 > tiff.length) return 1
163
+ if (u16(entry) !== 0x0112) continue
164
+ // A SHORT, as the standard has it, or a LONG, as some writers put it.
165
+ const value = u16(entry + 2) === 4 ? u32(entry + 8) : u16(entry + 8)
166
+ return value >= 1 && value <= 8 ? value : 1
167
+ }
168
+ return 1
169
+ }
170
+
171
+ /** A block of EXIF (its TIFF structure) that states an orientation and nothing else. */
172
+ function orientationOnly(orientation) {
173
+ const tiff = Buffer.alloc(26)
174
+ tiff.write('MM\0*', 0, 'latin1')
175
+ tiff.writeUInt32BE(8, 4) // the first directory
176
+ tiff.writeUInt16BE(1, 8) // one entry
177
+ tiff.writeUInt16BE(0x0112, 10) // Orientation
178
+ tiff.writeUInt16BE(3, 12) // a SHORT
179
+ tiff.writeUInt32BE(1, 14) // one value
180
+ tiff.writeUInt16BE(orientation, 18)
181
+ return tiff // the next directory, at 22, is 0: there is none
182
+ }
183
+
184
+ // ── JPEG ─────────────────────────────────────────────────────────────────────────────────────────
185
+
186
+ const ICC_ID = Buffer.from('ICC_PROFILE\0', 'latin1')
187
+
188
+ /** Whether a JPEG segment before the image data is dropped. */
189
+ function dropsJpegSegment(marker, payload) {
190
+ if (marker === 0xe1) return true // APP1: EXIF, XMP
191
+ if (marker === 0xe2) return !payload.subarray(0, ICC_ID.length).equals(ICC_ID) // APP2: keep the profile only
192
+ if (marker >= 0xe3 && marker <= 0xed) return true // APP3–APP13, IPTC (APP13) among them
193
+ if (marker === 0xef) return true // APP15
194
+ if (marker === 0xfe) return true // COM
195
+ return false
196
+ }
197
+
198
+ /** The JPEG without the segments `dropsJpegSegment` names, or null when it doesn't parse. */
199
+ function stripJpeg(buf) {
200
+ if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) return null
201
+ const out = [buf.subarray(0, 2)]
202
+ let exifRead = false
203
+ let i = 2
204
+ while (i < buf.length) {
205
+ if (buf[i] !== 0xff) return null
206
+ const marker = buf[i + 1]
207
+ if (marker === 0xff) { i++; continue } // fill byte
208
+ if (marker === 0xd9) { out.push(buf.subarray(i, i + 2)); return Buffer.concat(out) } // EOI
209
+ if ((marker >= 0xd0 && marker <= 0xd8) || marker === 0x01) { out.push(buf.subarray(i, i + 2)); i += 2; continue } // no length
210
+ if (i + 4 > buf.length) return null
211
+ const length = buf.readUInt16BE(i + 2)
212
+ const end = i + 2 + length
213
+ if (end > buf.length) return null
214
+ if (marker === 0xda) {
215
+ // The first scan: from here to the end of the image, every later table and scan included,
216
+ // is the picture. What follows its EOI is not.
217
+ const eoi = endOfImage(buf, end)
218
+ if (eoi < 0) return null
219
+ out.push(buf.subarray(i, eoi + 2))
220
+ return Buffer.concat(out)
221
+ }
222
+ const payload = buf.subarray(i + 4, end)
223
+ if (marker === 0xe1 && !exifRead && isExif(payload)) {
224
+ // The orientation stays, alone, where the EXIF was.
225
+ exifRead = true
226
+ const orientation = orientationIn(payload.subarray(EXIF_ID.length))
227
+ if (orientation !== 1) out.push(jpegSegment(0xe1, Buffer.concat([EXIF_ID, orientationOnly(orientation)])))
228
+ } else if (!dropsJpegSegment(marker, payload)) out.push(buf.subarray(i, end))
229
+ i = end
230
+ }
231
+ return null
232
+ }
233
+
234
+ /** A JPEG segment: its marker, its length and its payload. */
235
+ function jpegSegment(marker, payload) {
236
+ const head = Buffer.from([0xff, marker, 0, 0])
237
+ head.writeUInt16BE(payload.length + 2, 2)
238
+ return Buffer.concat([head, payload])
239
+ }
240
+
241
+ /** The offset of the EOI marker after a scan that starts at `from`, walking every later segment. */
242
+ function endOfImage(buf, from) {
243
+ let i = from
244
+ while (i + 1 < buf.length) {
245
+ if (buf[i] !== 0xff) { i++; continue }
246
+ const next = buf[i + 1]
247
+ if (next === 0x00 || next === 0xff || (next >= 0xd0 && next <= 0xd7)) { i += next === 0xff ? 1 : 2; continue } // stuffed byte, fill, restart
248
+ if (next === 0xd9) return i
249
+ if (i + 4 > buf.length) return -1
250
+ // A table or the next scan: its length says where its own data ends.
251
+ const end = i + 2 + buf.readUInt16BE(i + 2)
252
+ if (end > buf.length) return -1
253
+ i = end
254
+ }
255
+ return -1
256
+ }
257
+
258
+ // ── PNG ──────────────────────────────────────────────────────────────────────────────────────────
259
+
260
+ const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
261
+ const PRIVATE_PNG_CHUNKS = new Set(['eXIf', 'tEXt', 'zTXt', 'iTXt', 'tIME'])
262
+
263
+ function pngChunks(buf, visit) {
264
+ if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) return false
265
+ let i = 8
266
+ while (i + 12 <= buf.length) {
267
+ const length = buf.readUInt32BE(i)
268
+ const type = buf.toString('latin1', i + 4, i + 8)
269
+ const end = i + 12 + length
270
+ if (end > buf.length) return false
271
+ if (visit(type, i, end) === false) return true
272
+ i = end
273
+ if (type === 'IEND') return true
274
+ }
275
+ return false
276
+ }
277
+
278
+ /** The PNG without its private chunks, or null when it doesn't parse. */
279
+ function stripPng(buf) {
280
+ const out = [buf.subarray(0, 8)]
281
+ let exifRead = false
282
+ let afterData = false
283
+ const parsed = pngChunks(buf, (type, start, end) => {
284
+ if (type === 'IDAT') afterData = true
285
+ if (type === 'eXIf' && !exifRead && !afterData) {
286
+ // The orientation stays, alone, where the EXIF was.
287
+ exifRead = true
288
+ const orientation = orientationIn(tiffOf(buf.subarray(start + 8, end - 4)))
289
+ if (orientation !== 1) out.push(pngChunk('eXIf', orientationOnly(orientation)))
290
+ } else if (!PRIVATE_PNG_CHUNKS.has(type)) out.push(buf.subarray(start, end))
291
+ })
292
+ return parsed ? Buffer.concat(out) : null
293
+ }
294
+
295
+ /** A PNG chunk: its length, its type, its data and their CRC. */
296
+ function pngChunk(type, data) {
297
+ const head = Buffer.alloc(8)
298
+ head.writeUInt32BE(data.length, 0)
299
+ head.write(type, 4, 'latin1')
300
+ const crc = Buffer.alloc(4)
301
+ crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])) >>> 0)
302
+ return Buffer.concat([head, data, crc])
303
+ }
304
+
305
+ /** Whether a PNG is animated: an `acTL` chunk before its image data. */
306
+ function isAnimatedPng(buf) {
307
+ let animated = false
308
+ pngChunks(buf, (type) => {
309
+ if (type === 'acTL') animated = true
310
+ if (type === 'acTL' || type === 'IDAT') return false
311
+ })
312
+ return animated
313
+ }
314
+
315
+ // ── WebP ─────────────────────────────────────────────────────────────────────────────────────────
316
+
317
+ /** The flags in a `VP8X` chunk that say an `EXIF` and an `XMP ` chunk follow. */
318
+ const WEBP_EXIF = 0x08
319
+ const WEBP_XMP = 0x04
320
+
321
+ /** The WebP without its `EXIF` and `XMP ` chunks, or null when it doesn't parse. */
322
+ function stripWebp(buf) {
323
+ if (buf.length < 12 || buf.toString('latin1', 0, 4) !== 'RIFF' || buf.toString('latin1', 8, 12) !== 'WEBP') return null
324
+ const riffEnd = Math.min(8 + buf.readUInt32LE(4), buf.length)
325
+ const out = []
326
+ let header = null // the `VP8X` chunk, copied, since its flags change
327
+ let exifRead = false
328
+ let exifKept = false
329
+ let i = 12
330
+ while (i + 8 <= riffEnd) {
331
+ const type = buf.toString('latin1', i, i + 4)
332
+ const size = buf.readUInt32LE(i + 4)
333
+ if (i + 8 + size > riffEnd) return null
334
+ const end = Math.min(i + 8 + size + (size & 1), riffEnd)
335
+ if (type === 'EXIF') {
336
+ const payload = buf.subarray(i + 8, i + 8 + size)
337
+ const orientation = exifRead ? 1 : orientationIn(tiffOf(payload))
338
+ exifRead = true
339
+ if (orientation !== 1 && header) {
340
+ // The orientation stays, alone, written as the file had it: sharp puts `Exif\0\0` first.
341
+ const tiff = orientationOnly(orientation)
342
+ out.push(webpChunk('EXIF', isExif(payload) ? Buffer.concat([EXIF_ID, tiff]) : tiff))
343
+ exifKept = true
344
+ }
345
+ } else if (type === 'VP8X' && !header) {
346
+ header = Buffer.from(buf.subarray(i, end))
347
+ out.push(header)
348
+ } else if (type !== 'XMP ') out.push(buf.subarray(i, end))
349
+ i = end
350
+ }
351
+ if (header && header.length > 8) header[8] &= ~(WEBP_XMP | (exifKept ? 0 : WEBP_EXIF))
352
+ const body = Buffer.concat(out)
353
+ const riff = Buffer.alloc(12)
354
+ riff.write('RIFF', 0, 'latin1')
355
+ riff.writeUInt32LE(body.length + 4, 4)
356
+ riff.write('WEBP', 8, 'latin1')
357
+ return Buffer.concat([riff, body])
358
+ }
359
+
360
+ /** A WebP chunk: its type, its size, its data and the byte that pads it to an even length. */
361
+ function webpChunk(type, data) {
362
+ const head = Buffer.alloc(8)
363
+ head.write(type, 0, 'latin1')
364
+ head.writeUInt32LE(data.length, 4)
365
+ return Buffer.concat([head, data, Buffer.alloc(data.length & 1)])
366
+ }
@@ -1,8 +1,10 @@
1
1
  /**
2
2
  * Asset Processor
3
3
  *
4
- * Processes site assets (images) during build:
5
- * - Converts images to WebP for optimization
4
+ * Processes site assets (images) during a static build:
5
+ * - Prepares each picture under the one rule a push applies to what it uploads (`prepareImage`):
6
+ * a WebP when it saves, turned upright, without location and camera data. So a static site and a
7
+ * site published with Uniweb show the same picture.
6
8
  * - Generates content-hashed filenames for cache busting
7
9
  * - Caches processed assets to avoid redundant work
8
10
  *
@@ -13,12 +15,9 @@ import { readFile, writeFile, mkdir, stat, copyFile } from 'node:fs/promises'
13
15
  import { existsSync } from 'node:fs'
14
16
  import { join, basename, extname, dirname } from 'node:path'
15
17
  import { createHash } from 'node:crypto'
16
- import sharp from 'sharp'
17
18
  import { mimeFor } from '@uniweb/semantic-parser'
18
19
  import { drawnSize, RAN_OUT } from './drawn-size.js'
19
-
20
- // Image formats that can be converted to WebP
21
- const CONVERTIBLE_FORMATS = ['.png', '.jpg', '.jpeg', '.gif']
20
+ import { prepareImage, isPreparableImage } from '../prepare-image.js'
22
21
 
23
22
  // Image formats to pass through without conversion
24
23
  const PASSTHROUGH_FORMATS = ['.svg', '.webp', '.avif', '.ico']
@@ -49,25 +48,6 @@ async function getFileHash(filePath) {
49
48
  return createHash('md5').update(content).digest('hex').slice(0, 8)
50
49
  }
51
50
 
52
- /**
53
- * Convert an image to WebP format
54
- *
55
- * @param {Buffer} input - Input image buffer
56
- * @param {Object} options - Conversion options
57
- * @returns {Promise<Buffer>} WebP buffer
58
- */
59
- async function convertToWebp(input, options = {}) {
60
- const { quality = 80 } = options
61
-
62
- // ⭐ The picture as the author saw it. The conversion drops the tag saying how to turn a phone's
63
- // photo, so it's turned first, and sharp reads one frame unless told otherwise. ⛔ Until 2026-11-02
64
- // a portrait photo was drawn on its side, and an animated GIF was its first frame.
65
- return sharp(input, { animated: true })
66
- .autoOrient()
67
- .webp({ quality })
68
- .toBuffer()
69
- }
70
-
71
51
  /**
72
52
  * The size of a file the site serves, whole, so running out of it means it has none. Quiet, because a
73
53
  * file with no size is still copied.
@@ -89,7 +69,7 @@ export async function processAsset(asset, options = {}) {
89
69
  outputDir,
90
70
  assetsSubdir = 'assets',
91
71
  convertToWebp: shouldConvert = true,
92
- quality = 80,
72
+ quality,
93
73
  basePath = '/'
94
74
  } = options
95
75
 
@@ -119,12 +99,17 @@ export async function processAsset(asset, options = {}) {
119
99
  let outputExt = ext
120
100
  let converted = false
121
101
 
122
- if (isImage && shouldConvert && CONVERTIBLE_FORMATS.includes(ext)) {
123
- // Convert to WebP
124
- const input = await readFile(resolved)
125
- outputBuffer = await convertToWebp(input, { quality })
126
- outputExt = '.webp'
127
- converted = true
102
+ if (isImage && shouldConvert && isPreparableImage(ext)) {
103
+ // The picture under the one rule: a WebP when it saves, kept otherwise without its private
104
+ // data. ⛔ Until 2026-11-12 every PNG, JPEG and GIF became a WebP at quality 80, larger or not,
105
+ // its colour profile converted away, and a phone's location kept in a JPEG nothing converted.
106
+ const prepared = await prepareImage(await readFile(resolved), ext, quality ? { quality } : undefined)
107
+ if (prepared.unreadable) {
108
+ console.warn(`[asset-processor] ${basename(resolved)} is copied as it is: it can't be converted here, and some browsers can't show it`)
109
+ }
110
+ outputBuffer = prepared.bytes
111
+ outputExt = `.${prepared.ext}`
112
+ converted = prepared.converted
128
113
  } else if (isImage && PASSTHROUGH_FORMATS.includes(ext)) {
129
114
  // Copy as-is for SVG, WebP, etc.
130
115
  outputBuffer = await readFile(resolved)
@@ -286,7 +286,7 @@ async function writeShellAppearance(html, appearance) {
286
286
  * @param {Object} [options.assets] - Asset processing configuration
287
287
  * @param {boolean} [options.assets.process=true] - Process assets in production builds
288
288
  * @param {boolean} [options.assets.convertToWebp=true] - Convert images to WebP
289
- * @param {number} [options.assets.quality=80] - WebP quality (1-100)
289
+ * @param {number} [options.assets.quality] - WebP quality (1-100); the rule's (`IMAGE_RULE`) when unset
290
290
  * @param {string} [options.assets.outputDir='assets'] - Output subdirectory for processed assets
291
291
  * @param {boolean} [options.assets.videoPosters=true] - Extract poster frames from videos (requires ffmpeg)
292
292
  * @param {string} [options.foundationPath] - Path to foundation directory (for loading theme vars)
@@ -309,7 +309,8 @@ export function siteContentPlugin(options = {}) {
309
309
  const assetsOptions = {
310
310
  process: assetsConfig.process !== false, // Default true
311
311
  convertToWebp: assetsConfig.convertToWebp !== false, // Default true
312
- quality: assetsConfig.quality || 80,
312
+ // The site's own WebP quality, when it sets one; otherwise the rule's (`prepareImage`).
313
+ quality: assetsConfig.quality,
313
314
  outputDir: assetsConfig.outputDir || 'assets',
314
315
  videoPosters: assetsConfig.videoPosters !== false // Default true
315
316
  }
@@ -122,6 +122,37 @@ function collectReferencedModels(node, acc) {
122
122
  // with its serve URL.
123
123
  const isReadersText = (node, key) => key === 'text' && node.type === 'text'
124
124
 
125
+ /**
126
+ * The site-root pictures that software other than the site's pages fetches by their address: the
127
+ * favicon, the touch icon a phone puts on its home screen, the site's card picture (`info.preview`),
128
+ * and every social image (`seo`, the site's and each page's). A push uploads them as they are,
129
+ * because what fetches them takes a PNG icon or a JPEG or PNG picture, not the WebP a page's
130
+ * picture is prepared to.
131
+ *
132
+ * @param {object|null} siteDoc - the site-content document
133
+ * @returns {Set<string>}
134
+ */
135
+ function outsideAssetRefs(siteDoc) {
136
+ const refs = new Set()
137
+ if (!siteDoc) return refs
138
+ const take = (value) => {
139
+ if (typeof value === 'string' && value.startsWith('/') && !value.startsWith('//')) refs.add(value)
140
+ else walkEntityAssets(value, (ref) => ref.startsWith('/') && refs.add(ref))
141
+ }
142
+ take(siteDoc.info?.favicon)
143
+ take(siteDoc.info?.preview)
144
+ take(siteDoc.settings?.touch_icon)
145
+ take(siteDoc.settings?.seo)
146
+ const visit = (pages) => {
147
+ for (const page of pages || []) {
148
+ take(page.seo)
149
+ visit(page.$children)
150
+ }
151
+ }
152
+ visit(siteDoc.pages)
153
+ return refs
154
+ }
155
+
125
156
  // Invoke visitor(ref) for every local asset path string anywhere in the document.
126
157
  function walkEntityAssets(node, visitor) {
127
158
  if (typeof node === 'string') {
@@ -295,7 +326,7 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
295
326
  * siteContent: { buffer, entityCount, index, models }|null,
296
327
  * records: { buffer, entityCount, index, models, links }|null,
297
328
  * hashes: Object<string,string>, warnings: string[], refusals: string[],
298
- * skipped: number, localAssets: string[], applied: object, namesNew: string[],
329
+ * skipped: number, localAssets: string[], outsideAssets: string[], applied: object, namesNew: string[],
299
330
  * recordItemIdentity: { stamped: number, unknown: number, unbanked: string[] } }>}
300
331
  * Each record entry of `records.index` carries `lists`: the record's list items as
301
332
  * sent (`record-items.js::recordItemLists`), for the caller to bank against the
@@ -548,6 +579,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
548
579
  if (sitePath(face?.src)) localAssetSet.add(face.src)
549
580
  }
550
581
  const localAssets = [...localAssetSet]
582
+ // ⭐ The local pictures other software fetches by their address, which a push uploads as they are
583
+ // (`outsideAssetRefs`). Every other picture is one a page draws, and is prepared before it is stored.
584
+ const outsideAssets = [...outsideAssetRefs(siteDoc)].filter((ref) => localAssetSet.has(ref))
551
585
 
552
586
  // ⭐ THE IDENTITY OF A RECORD'S LIST ITEMS (`record-items.js`), taken on each document as it
553
587
  // will be sent — after every rewrite above. `opts.recordItemUuids` is the caller's bank: per
@@ -719,7 +753,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
719
753
  // Records that name a record this push creates — see `namesNew` above.
720
754
  namesNew,
721
755
  refusals,
722
- localAssets, applied,
756
+ localAssets, outsideAssets, applied,
723
757
  // The files a push uploads for its file records, each `{ ref, path, contentType }` — the file, and
724
758
  // a PDF's preview — and for its sections' co-located media, each `{ ref, path }`. Uploaded through
725
759
  // the media lane; `ref` is the key the second emit rewrites.