jpegxl 0.0.0-stage → 8.4.0

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.
Files changed (264) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +379 -2
  3. package/THIRD_PARTY_NOTICES +73 -0
  4. package/dist/animation.browser.mjs +2 -0
  5. package/dist/animation.edge-light.mjs +7 -0
  6. package/dist/animation.mjs +2 -0
  7. package/dist/animation.workerd.mjs +7 -0
  8. package/dist/capture-complete.browser.mjs +2 -0
  9. package/dist/capture-complete.edge-light.mjs +5 -0
  10. package/dist/capture-complete.mjs +2 -0
  11. package/dist/capture-complete.workerd.mjs +5 -0
  12. package/dist/capture-groups.mjs +2 -0
  13. package/dist/capture.browser.mjs +2 -0
  14. package/dist/capture.edge-light.mjs +4 -0
  15. package/dist/capture.mjs +2 -0
  16. package/dist/capture.workerd.mjs +4 -0
  17. package/dist/cli-add.mjs +2 -0
  18. package/dist/cli-astro.mjs +2 -0
  19. package/dist/cli-cloudflare.mjs +2 -0
  20. package/dist/cli-emdash.mjs +2 -0
  21. package/dist/cli-places.mjs +2 -0
  22. package/dist/cli-selftest.mjs +2 -0
  23. package/dist/cli-workers.mjs +2 -0
  24. package/dist/cli.mjs +3 -0
  25. package/dist/decode.browser.mjs +2 -0
  26. package/dist/decode.edge-light.mjs +4 -0
  27. package/dist/decode.mjs +2 -0
  28. package/dist/decode.node.mjs +2 -0
  29. package/dist/decode.wasm +0 -0
  30. package/dist/decode.workerd.mjs +4 -0
  31. package/dist/format.browser.mjs +2 -0
  32. package/dist/format.edge-light.mjs +7 -0
  33. package/dist/format.mjs +2 -0
  34. package/dist/format.workerd.mjs +7 -0
  35. package/dist/general.wasm +0 -0
  36. package/dist/hdr.mjs +2 -0
  37. package/dist/helpers.mjs +2 -0
  38. package/dist/index.browser.mjs +2 -0
  39. package/dist/index.edge-light.mjs +7 -0
  40. package/dist/index.mjs +2 -0
  41. package/dist/index.workerd.mjs +7 -0
  42. package/dist/jpeg.browser.mjs +2 -0
  43. package/dist/jpeg.edge-light.mjs +6 -0
  44. package/dist/jpeg.mjs +2 -0
  45. package/dist/jpeg.node.mjs +2 -0
  46. package/dist/jpeg.wasm +0 -0
  47. package/dist/jpeg.workerd.mjs +6 -0
  48. package/dist/kernels.wasm +0 -0
  49. package/dist/metadata.mjs +2 -0
  50. package/dist/polyfill.mjs +2 -0
  51. package/dist/rebuild.wasm +0 -0
  52. package/dist/resumable.edge-light.mjs +4 -0
  53. package/dist/resumable.mjs +2 -0
  54. package/dist/resumable.node.mjs +2 -0
  55. package/dist/resumable.workerd.mjs +4 -0
  56. package/dist/serve.mjs +2 -0
  57. package/dist/serve.node.mjs +2 -0
  58. package/dist/upload.browser.mjs +2 -0
  59. package/dist/upload.edge-light.mjs +6 -0
  60. package/dist/upload.mjs +2 -0
  61. package/dist/upload.workerd.mjs +6 -0
  62. package/dist/verify.edge-light.mjs +4 -0
  63. package/dist/verify.mjs +2 -0
  64. package/dist/verify.node.mjs +2 -0
  65. package/dist/verify.workerd.mjs +4 -0
  66. package/dist/wasm-modules.mjs +2 -0
  67. package/examples/09-browser-upload-queue.html +13 -0
  68. package/examples/09-browser-upload-queue.mjs +74 -0
  69. package/examples/agents/jxl-agent.mjs +10 -0
  70. package/examples/agents/jxl-mcp.mjs +61 -0
  71. package/examples/agents/jxl-tools.mjs +172 -0
  72. package/examples/android/README.md +59 -0
  73. package/examples/android/app/build.gradle.kts +33 -0
  74. package/examples/android/app/src/main/AndroidManifest.xml +25 -0
  75. package/examples/android/app/src/main/assets/encoder.html +49 -0
  76. package/examples/android/app/src/main/assets/encoder.mjs +46 -0
  77. package/examples/android/app/src/main/java/app/rapier/jxlexample/BridgeProtocol.kt +150 -0
  78. package/examples/android/app/src/main/java/app/rapier/jxlexample/MainActivity.kt +550 -0
  79. package/examples/android/app/src/test/java/app/rapier/jxlexample/BridgeProtocolChecks.kt +145 -0
  80. package/examples/android/app/src/test/java/app/rapier/jxlexample/BridgeProtocolTest.kt +7 -0
  81. package/examples/android/build.gradle.kts +3 -0
  82. package/examples/android/gradle/wrapper/gradle-wrapper.jar +0 -0
  83. package/examples/android/gradle/wrapper/gradle-wrapper.properties +7 -0
  84. package/examples/android/gradle.properties +5 -0
  85. package/examples/android/gradlew +248 -0
  86. package/examples/android/gradlew.bat +82 -0
  87. package/examples/android/prepare-assets.mjs +51 -0
  88. package/examples/android/settings.gradle.kts +16 -0
  89. package/examples/android/test-jvm.sh +15 -0
  90. package/examples/astro/AGENTS.md +20 -0
  91. package/examples/astro/README.md +68 -0
  92. package/examples/astro/index.mjs +23 -0
  93. package/examples/astro/options.mjs +43 -0
  94. package/examples/astro/service-workers.mjs +162 -0
  95. package/examples/astro/service.mjs +91 -0
  96. package/examples/browser-no-bundler.html +24 -0
  97. package/examples/capacitor/README.md +10 -0
  98. package/examples/capacitor/capacitor.config.json +6 -0
  99. package/examples/capacitor/check.mjs +85 -0
  100. package/examples/capacitor/index.html +85 -0
  101. package/examples/capacitor/package.json +21 -0
  102. package/examples/capacitor/prepare-assets.mjs +26 -0
  103. package/examples/capacitor/save.mjs +14 -0
  104. package/examples/capacitor/vite.config.mjs +18 -0
  105. package/examples/decode-to-canvas.html +16 -0
  106. package/examples/desktop/app.mjs +66 -0
  107. package/examples/desktop/index.html +32 -0
  108. package/examples/desktop/prepare.mjs +32 -0
  109. package/examples/electron/main.mjs +44 -0
  110. package/examples/electron/preload.cjs +2 -0
  111. package/examples/electron/prepare-assets.mjs +7 -0
  112. package/examples/emdash/AGENTS.md +27 -0
  113. package/examples/emdash/README.md +178 -0
  114. package/examples/emdash/admin-work.mjs +283 -0
  115. package/examples/emdash/astro.config.mjs +13 -0
  116. package/examples/emdash/backfill.mjs +162 -0
  117. package/examples/emdash/background.mjs +107 -0
  118. package/examples/emdash/browser-candidate.mjs +25 -0
  119. package/examples/emdash/browser-tools.mjs +7 -0
  120. package/examples/emdash/color.mjs +51 -0
  121. package/examples/emdash/deliver.mjs +29 -0
  122. package/examples/emdash/digest.mjs +4 -0
  123. package/examples/emdash/host-policy.mjs +118 -0
  124. package/examples/emdash/index.d.ts +9 -0
  125. package/examples/emdash/index.mjs +25 -0
  126. package/examples/emdash/job-runner.mjs +549 -0
  127. package/examples/emdash/job-store.mjs +282 -0
  128. package/examples/emdash/jpeg-source.mjs +32 -0
  129. package/examples/emdash/library-jobs.mjs +232 -0
  130. package/examples/emdash/local-store.mjs +260 -0
  131. package/examples/emdash/media-admin.mjs +736 -0
  132. package/examples/emdash/media-plugin.mjs +1002 -0
  133. package/examples/emdash/media-settings.mjs +33 -0
  134. package/examples/emdash/media-storage.mjs +883 -0
  135. package/examples/emdash/media-words.d.mts +3 -0
  136. package/examples/emdash/media-words.mjs +319 -0
  137. package/examples/emdash/media-worker.mjs +96 -0
  138. package/examples/emdash/middleware.mjs +175 -0
  139. package/examples/emdash/node-admission.mjs +27 -0
  140. package/examples/emdash/original-cache-node.mjs +55 -0
  141. package/examples/emdash/original-cache-workers.mjs +31 -0
  142. package/examples/emdash/original-envelope.mjs +44 -0
  143. package/examples/emdash/originals.mjs +1131 -0
  144. package/examples/emdash/r2-store.mjs +54 -0
  145. package/examples/emdash/read-all.mjs +107 -0
  146. package/examples/emdash/server-only.mjs +2 -0
  147. package/examples/emdash/storage-local.mjs +19 -0
  148. package/examples/emdash/storage-r2.mjs +21 -0
  149. package/examples/emdash/storage.mjs +12 -0
  150. package/examples/emdash/structural-delivery.mjs +175 -0
  151. package/examples/emdash/thread-driver.mjs +262 -0
  152. package/examples/emdash/thread-worker.mjs +54 -0
  153. package/examples/emdash/work-queue.mjs +71 -0
  154. package/examples/files/index.d.ts +20 -0
  155. package/examples/files/index.mjs +49 -0
  156. package/examples/flutter/assets/web/encoder.html +5 -0
  157. package/examples/flutter/assets/web/encoder.mjs +41 -0
  158. package/examples/flutter/assets/web/headers.json +8 -0
  159. package/examples/flutter/assets/web/page.mjs +67 -0
  160. package/examples/flutter/lib/rapier_jxl.dart +318 -0
  161. package/examples/flutter/lib/src/bridge.dart +95 -0
  162. package/examples/flutter/prepare-assets.mjs +35 -0
  163. package/examples/flutter/pubspec.yaml +26 -0
  164. package/examples/ios/Package.swift +13 -0
  165. package/examples/ios/Sources/RapierJXL/Bridge.swift +110 -0
  166. package/examples/ios/Sources/RapierJXL/RapierJXL.swift +335 -0
  167. package/examples/ios/Sources/RapierJXL/Video.swift +131 -0
  168. package/examples/ios/Sources/RapierJXL/Web/encoder.html +6 -0
  169. package/examples/ios/Sources/RapierJXL/Web/encoder.mjs +41 -0
  170. package/examples/ios/Sources/RapierJXL/Web/headers.json +8 -0
  171. package/examples/ios/Sources/RapierJXL/Web/page.mjs +64 -0
  172. package/examples/ios/prepare-assets.mjs +44 -0
  173. package/examples/jpeg-exact.mjs +12 -0
  174. package/examples/netlify/AGENTS.md +28 -0
  175. package/examples/netlify/README.md +37 -0
  176. package/examples/netlify/edge.mjs +92 -0
  177. package/examples/netlify/index.mjs +51 -0
  178. package/examples/netlify/manifest.yml +8 -0
  179. package/examples/netlify/package.json +6 -0
  180. package/examples/next/AGENTS.md +34 -0
  181. package/examples/next/README.md +59 -0
  182. package/examples/next/index.d.ts +16 -0
  183. package/examples/next/index.mjs +99 -0
  184. package/examples/next/loader.mjs +13 -0
  185. package/examples/next/proxy.mjs +53 -0
  186. package/examples/node-png-to-jxl.mjs +9 -0
  187. package/examples/page-rects.d.ts +24 -0
  188. package/examples/page-rects.js +393 -0
  189. package/examples/polyfill.html +10 -0
  190. package/examples/r2/jxl-r2.mjs +311 -0
  191. package/examples/react-native/prepare-assets.mjs +52 -0
  192. package/examples/react-native/src/JXLProvider.tsx +54 -0
  193. package/examples/react-native/src/base64.ts +31 -0
  194. package/examples/react-native/src/codec.ts +166 -0
  195. package/examples/react-native/src/index.ts +3 -0
  196. package/examples/react-native/web/page.js +122 -0
  197. package/examples/react-native/web/worker.js +43 -0
  198. package/examples/snapdom/README.md +98 -0
  199. package/examples/snapdom/jxl.d.ts +65 -0
  200. package/examples/snapdom/jxl.js +541 -0
  201. package/examples/snapdom/svg-jxl.d.ts +23 -0
  202. package/examples/snapdom/svg-jxl.js +43 -0
  203. package/examples/svg-jxl.d.ts +31 -0
  204. package/examples/svg-jxl.js +291 -0
  205. package/examples/tauri/prepare-assets.mjs +7 -0
  206. package/examples/tauri/src-tauri/src/main.rs +50 -0
  207. package/examples/upload-widgets/AGENTS.md +23 -0
  208. package/examples/upload-widgets/README.md +59 -0
  209. package/examples/upload-widgets/filepond-example/index.html +17 -0
  210. package/examples/upload-widgets/filepond-example/main.mjs +13 -0
  211. package/examples/upload-widgets/filepond-example/server.mjs +53 -0
  212. package/examples/upload-widgets/filepond.mjs +31 -0
  213. package/examples/upload-widgets/shrink.mjs +86 -0
  214. package/examples/vite/AGENTS.md +38 -0
  215. package/examples/vite/README.md +73 -0
  216. package/examples/vite/client.d.ts +8 -0
  217. package/examples/vite/index.d.ts +17 -0
  218. package/examples/vite/index.mjs +117 -0
  219. package/examples/webpack/AGENTS.md +39 -0
  220. package/examples/webpack/README.md +72 -0
  221. package/examples/webpack/index.d.ts +18 -0
  222. package/examples/webpack/index.mjs +78 -0
  223. package/examples/workers/AGENTS.md +51 -0
  224. package/examples/workers/README.md +63 -0
  225. package/examples/workers/jxl-worker.mjs +282 -0
  226. package/examples/workers/wrangler.jsonc +14 -0
  227. package/package.json +247 -5
  228. package/skills/rapier-jxl/SKILL.md +49 -0
  229. package/types/animation.d.mts +35 -0
  230. package/types/capture-complete.d.mts +37 -0
  231. package/types/capture.d.mts +29 -0
  232. package/types/codec/animation-atlas.d.mts +50 -0
  233. package/types/codec/animation.d.mts +40 -0
  234. package/types/codec/channels.d.mts +125 -0
  235. package/types/codec/container-advanced.d.mts +117 -0
  236. package/types/codec/container-stream.d.mts +25 -0
  237. package/types/codec/decode.d.mts +136 -0
  238. package/types/codec/delta-palette.d.mts +29 -0
  239. package/types/codec/graphics.d.mts +35 -0
  240. package/types/codec/hybrid.d.mts +19 -0
  241. package/types/codec/icc.d.mts +85 -0
  242. package/types/codec/index.d.mts +60 -0
  243. package/types/codec/jpeg.d.mts +29 -0
  244. package/types/codec/layers.d.mts +38 -0
  245. package/types/codec/metadata.d.mts +53 -0
  246. package/types/codec/patches.d.mts +99 -0
  247. package/types/codec/photo-advanced.d.mts +120 -0
  248. package/types/codec/photo.d.mts +18 -0
  249. package/types/codec/splines.d.mts +45 -0
  250. package/types/codec/writer.d.mts +204 -0
  251. package/types/decode.d.mts +28 -0
  252. package/types/format.d.mts +97 -0
  253. package/types/hdr.d.mts +47 -0
  254. package/types/index.d.mts +40 -0
  255. package/types/jpeg.d.mts +39 -0
  256. package/types/metadata.d.mts +46 -0
  257. package/types/polyfill.d.mts +47 -0
  258. package/types/preparation-upload.d.mts +26 -0
  259. package/types/result.d.mts +100 -0
  260. package/types/resumable.d.mts +203 -0
  261. package/types/serve.d.mts +49 -0
  262. package/types/types.d.mts +536 -0
  263. package/types/upload.d.mts +42 -0
  264. package/types/verify.d.mts +99 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 rapier.website
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,3 +1,380 @@
1
- # Temporary Holding Version
1
+ # rapier-jxl
2
2
 
3
- 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.
3
+ [![npm](https://img.shields.io/npm/v/jpegxl)](https://www.npmjs.com/package/jpegxl)
4
+ [![downloads](https://img.shields.io/npm/dw/jpegxl)](https://www.npmjs.com/package/jpegxl)
5
+ [![license](https://img.shields.io/npm/l/jpegxl)](https://github.com/jackskip22/rapier-jxl/blob/main/LICENSE)
6
+ [![types](https://img.shields.io/npm/types/jpegxl)](https://www.npmjs.com/package/jpegxl)
7
+
8
+ JPEG XL in JavaScript and WebAssembly with WebGPU for high efforts.
9
+
10
+ rapier-jxl, published on npm as `jpegxl`.
11
+
12
+ Used by [SnapDOM's official JPEG XL plugin](https://snapdom.dev/plugins/jxl/) and the [EmDash JPEG XL Image Optimizer plugin](https://plugins.emdashcms.com/plugins/@rapier.website/jxl). [Try it in your browser](https://rapier.website/jxl).
13
+
14
+ rapier-jxl is the encoder inside [rapier.website](https://rapier.website), the free Markdown editor and painting app. Rapier is also a free [Android app](https://play.google.com/store/apps/details?id=app.rapier&referrer=utm_source%3Djxl-readme) that opens and converts JPEG XL pictures.
15
+
16
+ - Uploads over 2x faster than libvips.
17
+ - 61 KB Brotli exact capture.
18
+ - 293 KB Brotli complete capture.
19
+ - 331 KB Brotli upload.
20
+ - 485 KB Brotli full encoder with HDR and parallel workers. Used by [rapier.html](https://rapier.website)
21
+ - Lossless JPEG transcoding, decoding, verification, serving, metadata, animation, polyfill, CLI and resumable encoding
22
+ for edge isolates. Modules are single files.
23
+ - Browsers, workers, Node, Deno, Bun, Cloudflare Workers.
24
+ - No dependencies.
25
+ - MIT.
26
+
27
+ ```sh
28
+ npm install jpegxl
29
+ ```
30
+
31
+ ESM. From CommonJS: `await import('jpegxl')`.
32
+
33
+ ## Command line
34
+
35
+ ```sh
36
+ npx jpegxl photo.png # photo.jxl beside it
37
+ npx jpegxl scan.jpg # scan.jxl, lossless; the original JPEG can be restored
38
+ npx jpegxl photos/ --out dist/ # every PNG, JPEG and GIF in the folder
39
+ npx jpegxl hero.png --max-bytes 100KB # lower quality to fit, keeping dimensions
40
+ npx jpegxl scan.jxl --out back/ # back/scan.jpg, the original JPEG
41
+ npx jpegxl photos/ --out dist/ --json # one JSON line per file, then a summary
42
+ ```
43
+
44
+ `--quality 1–100`, default 90, exact for a JPEG. `--effort 1–9`, default 7. `--exact`, `--jpeg-pixels`, `--max-bytes`, `--out`, `--jobs` for helpers.
45
+ Automatic output names never replace files.
46
+ `--json` names what each file kept: `jpeg-bytes` (the JPEG restores exactly), `pixels` (exact) or `lossy`. A rerun
47
+ leaves finished files untouched.
48
+ At efforts 6–9, a JPEG at a quality stays a JPEG when that is smaller.
49
+ `--jpeg-pixels` encodes a JPEG's pixels; the file does not restore the JPEG.
50
+
51
+ ## Upload
52
+
53
+ ```js
54
+ import {encode, fit} from 'jpegxl/upload';
55
+
56
+ // file: a File or Blob from an input, a drop or a fetch.
57
+ const compress = async file => {
58
+ const result = await encode(file, {fidelity: {quality: 82}});
59
+ if (!result.bytes) throw Object.assign(new Error(result.reason.message), {code: result.reason.code});
60
+ return new Blob([result.bytes], {type: 'image/jxl'});
61
+ };
62
+ const small = file => fit(file, {maxBytes: 100_000}); // best quality under 100 KB; `meetsTarget` says whether it got there
63
+ ```
64
+
65
+ `variants` makes several sizes from one upload. All calls accept `onProgress` and `signal`, for progress bars and
66
+ cancelling. On Node and Deno, pass pixels `{data, width, height}`, or a PNG file as `new Blob([bytes])`. A JPEG needs one
67
+ setup step first. In Node, Deno or Bun, import `configureDecoder` from `jpegxl`, `decode` from `jpegxl/decode` and
68
+ `recompress` from `jpegxl/jpeg`, then call `configureDecoder(decode, null, recompress)` once.
69
+ A page with no bundler needs an import map or a path: `import {encode} from '../dist/upload.mjs'`.
70
+
71
+ ## Encode
72
+
73
+ ```js
74
+ import {writeFile} from 'node:fs/promises';
75
+ import {encode} from 'jpegxl';
76
+
77
+ const picture = {data: new Uint8Array([240, 120, 40, 255]), width: 1, height: 1};
78
+ await writeFile('picture.jxl', (await encode(picture, {fidelity: {quality: 90}})).bytes);
79
+ ```
80
+
81
+ Takes RGBA `{data, width, height}`, `ImageData`, a canvas (2D, WebGL or WebGPU), an `ImageBitmap`, a `VideoFrame`, a
82
+ `Blob`, a decoded image or a GPU texture `{texture, device}`, and returns a result record with the output in `result.bytes`. 8 or 16-bit, `Float16Array`
83
+ or `Float32Array` samples, including HDR. For animations, including an animated GIF `Blob`, use `jpegxl/animation`. Input `frames[i].duration` is milliseconds. `decode()` returns the frames in `result.frames`; each frame has `duration` in ticks and `durationSeconds` in seconds.
84
+
85
+ - `encode(jpeg, {fidelity: 'exact'})` keeps a JPEG so it restores exactly, as `recompress` does.
86
+ - At efforts 6–9, a JPEG at a quality stays a JPEG when that is smaller.
87
+ - A kept JPEG answers `kept: 'jpeg-bytes'`. `jpeg: 'pixels'` encodes its pixels, in `fit` and `variants` too.
88
+ - `originalBytes` is the input file's size. `largerThanOriginal` says the output is bigger.
89
+ - `jpegxl/hdr` reads OpenEXR and Radiance files.
90
+ - `fidelity`: `{quality: 1–100}`, default 90. `'exact'` is lossless.
91
+ - `effort`: 1–9, default 7. Lower is faster; 1–3 suit previews and uploads, 8–9 photography.
92
+ - Efforts 6–9 measure quality. Efforts 1–5 estimate it.
93
+ - `webgpu`: left out, efforts 7–9 use WebGPU where it helps; the result's `usedWebGPU` says whether it did. `'required'`
94
+ fails without it, and at efforts 1–6 or exact, which run on WebAssembly; `false` turns it off.
95
+ - `maxPixels`: no default bound; set it to bound memory. A side is at most 2^30 (the JPEG XL size field); what the host cannot hold refuses `JXL_MEMORY`. Very large images can be passed in strips with `rows(y, count)`.
96
+ - `verify(original, result)` from `jpegxl/verify` checks a file against its source: the file the encoder wrote. A file edited afterwards, such as one given Exif or XMP, is another file and is refused.
97
+
98
+ ## Screenshots
99
+
100
+ ```js
101
+ import {capture} from 'jpegxl/capture';
102
+ import {capture as page} from 'jpegxl/capture-complete';
103
+
104
+ const screenshot = canvas => capture(canvas); // lossless
105
+ const smaller = (canvas, rects) => page(canvas, {fidelity: {quality: 92}, ...rects}); // lossy photos, lossless text
106
+ ```
107
+
108
+ - Canvas (2D, WebGL or WebGPU), `ImageData`, an `ImageBitmap`, a `VideoFrame`, a `Blob` or 8-bit RGBA.
109
+ - `rects` is `{exactRects, photoRects}`: the areas to keep lossless, such as text, and where the photos are.
110
+ - `jpegxl/page-rects` finds both in a page element, for any library that draws one to a canvas: `const rects = pageRects(element, canvas, {area}); await capture(canvas, {...rects, fidelity: {quality: 85}})`.
111
+ - Tall pages in one file, as tall as the browser draws them; WebP stops at 16,383.
112
+ - Efforts 6–9 check photo quality with the browser's JPEG XL decoder. In Node, Deno, Bun and desktop apps, the one setup
113
+ step is `configureDecoder(decode)`, with `decode` from `jpegxl/decode`.
114
+
115
+ | Effort | `capture-complete` |
116
+ |---|---|
117
+ | 1–3 | Fast. 3 is the default, 2 for quick saves, 1 for live previews. |
118
+ | 4–5 | Deeper search: smaller text, graphics and photos without quality loss. |
119
+ | 6–9 | Automatically finds the smallest file at the quality you choose. 7–9 also search block sizes. |
120
+
121
+ ## JPEG, decoding, metadata
122
+
123
+ ```js
124
+ import {recompress, restore} from 'jpegxl/jpeg';
125
+ import {decode} from 'jpegxl/decode';
126
+ import {header} from 'jpegxl/metadata';
127
+
128
+ // jpeg: a Uint8Array holding a JPEG file.
129
+ const roundTrip = async jpeg => (await restore((await recompress(jpeg)).bytes)).bytes;
130
+ const pixels = async file => decode(file); // {width, height, data}, RGBA
131
+ const forCanvas = async bytes => decode(bytes, {format: 'uint8', colorSpace: 'srgb'}); // data is a Uint8ClampedArray
132
+ const size = file => header(file); // synchronous, from a file or its first bytes
133
+ ```
134
+
135
+ `inspect` also reads the first 64 KiB of a JPEG or PNG for its size, orientation and color as `encode` writes it.
136
+ `recompress` runs at effort 7 unless given one. `restore(...)` returns `{bytes, ...}`; the JPEG is `.bytes`.
137
+ When a JPEG's trailing data (such as a phone's motion-photo video) is longer than the format's reconstruction box holds, recompress's and verify's records carry `otherDecoders: {missing, reason: 'past-jbrd'}`: other decoders return the JPEG without its last `missing` bytes, while `restore` returns all of it.
138
+
139
+ `jpegxl/svg-jxl` converts the images inside any SVG to JPEG XL where that makes them smaller while automatically keeping shapes and text sharp.
140
+ `{fidelity: 'exact'}` keeps the images lossless.
141
+
142
+ ## Serving
143
+
144
+ For recompressed JPEGs, `serve` sends JPEG XL to browsers that support it and the original JPEG to the rest, with
145
+ `Vary: Accept`, ETag, `304` and `HEAD`.
146
+
147
+ ```js
148
+ import {createServer} from 'node:http';
149
+ import {readFile} from 'node:fs/promises';
150
+ import {serve} from 'jpegxl/serve';
151
+
152
+ // photo.jxl, made once: npx jpegxl photo.jpg
153
+ const stored = await readFile('photo.jxl');
154
+ createServer((req, res) => serve(stored, req, res)).listen(3000);
155
+ ```
156
+
157
+ Cloudflare Workers, Deno and Bun: `return serve(stored, request)`. `cacheControl` sets `Cache-Control` (default
158
+ `private, no-cache`).
159
+
160
+ ## Resumable encoding
161
+
162
+ For edge isolates with short time limits: an encode continues across requests in short steps and writes the same file
163
+ as one call.
164
+
165
+ ```js
166
+ import {start, advance, finish} from 'jpegxl/resumable';
167
+ import {encode} from 'jpegxl/upload';
168
+ import {verify} from 'jpegxl/verify';
169
+
170
+ // store: the original and the job's parts (R2, KV, a database). input names the original:
171
+ // {generation, sha256, byteLength}, with kind: 'file' for an uploaded file.
172
+ const step = async (saved, store, input, memoryBytes) => {
173
+ const job = {operation: encode, store, input, verify, memoryBytes};
174
+ const {checkpoint, done} = await advance(saved ?? await start({...job, options: {fidelity: {quality: 82}}}), job);
175
+ return done ? {result: await finish(checkpoint, job)} : {checkpoint}; // save checkpoint for the next request
176
+ };
177
+ ```
178
+
179
+ - `capture`, `encode`, `fit`, `variants`, `recompress`, `restore` and `verify`.
180
+ - Each `advance` runs for about 30 ms (`budget: {ms}`) and writes its parts to the store before it returns. A host that allows few store calls a request passes `budget.reads`: the call ends before more reads than that.
181
+ - Pass `memoryBytes` with each call to require a measured memory estimate below that many bytes. Unmeasured sizes, source types, and verified jobs refuse with `JXL_MEMORY` before encoding. Your host must enforce the process limit.
182
+ - `verify` from `jpegxl/verify` in the job verifies in the advances. `finish` returns the whole-file verifier's
183
+ receipt in `result.verification` (one per variant). A failed check rejects with `error.verification`; publish only a finished,
184
+ verified result. The saved plan keeps this choice for every request.
185
+ - Pixel verification needs the browser's JPEG XL decoding or the host's configured decoder. On a server, call
186
+ `configureDecoder(decode, restore)` from `jpegxl/verify` with `decode` from `jpegxl/decode` and `restore` from
187
+ `jpegxl/jpeg` in each new isolate. The resumable module carries no decoder.
188
+ - Keep the original immutable for its `generation` and SHA-256. Save the returned checkpoint with a revision check
189
+ after its parts are durable, and accept checkpoints only from your service. `finish` assembles the saved output;
190
+ hashing, decoding and scoring have already finished in the advances.
191
+ - `workerAdmission({operation, options, width, height})` says whether a job fits a Cloudflare Workers isolate (128 MB), from measured memory per operation, effort and size. A size not measured is not admitted; convert it in the browser.
192
+ - `workerAdmission` answers for `rapier-jxl`, `jpegxl/upload` (efforts 1-3, default 3) and `jpegxl/jpeg`.
193
+ - `store` is `{readSource(offset, length), read(ref), write(ref, bytes)}`. `input` is `{generation, sha256, byteLength, kind: 'file'}`; `sha256` is 64 lowercase hex digits, without a `sha256:` prefix.
194
+
195
+ For a candidate uploaded separately, use the existing `verify` verb. Store the candidate as immutable, ordered parts
196
+ of at most 1 MiB, each named by its SHA-256. Pass its result metadata without `bytes` or a `verification` receipt:
197
+
198
+ ```js
199
+ import {start, finish} from 'jpegxl/resumable';
200
+ import {verify} from 'jpegxl/verify';
201
+
202
+ const job = (store, input) => ({operation: verify, input, store});
203
+ const begin = (store, input, result, parts) => start({...job(store, input), options: {result, parts}});
204
+ // Persist and advance the checkpoint as above. When done, finish returns the receipt:
205
+ const done = (checkpoint, store, input) => finish(checkpoint, job(store, input));
206
+ ```
207
+
208
+ `finish` returns the same receipt as `verify(original, result)` and reads neither image. A failed check rejects with
209
+ `error.verification`. The service verifies the original generation and candidate revision again before publication;
210
+ metadata supplied by the uploader is a claim to check.
211
+
212
+ ## EmDash
213
+
214
+ Run in the site's folder:
215
+
216
+ ```sh
217
+ npx jpegxl add emdash
218
+ ```
219
+
220
+ For a coding agent: “Add rapier-jxl/emdash to this site, keeping its existing storage and EmDash options.”
221
+
222
+ For manual setup with EmDash 1.4, install the package and its matching Kumo version:
223
+
224
+ ```sh
225
+ npm install jpegxl @cloudflare/kumo@2.6.0
226
+ ```
227
+
228
+ Keep the existing imports and options; wrap `emdash({...})` with `jxl(emdash, {...})`:
229
+
230
+ ```js
231
+ // astro.config.mjs
232
+ import emdash from 'emdash/astro';
233
+ import {jxl} from 'jpegxl/emdash';
234
+
235
+ export default defineConfig({
236
+ integrations: [react(), jxl(emdash, {database: d1({binding: 'DB'}), storage: r2({binding: 'MEDIA'})})],
237
+ });
238
+ ```
239
+
240
+ Originals stay in the site's `r2()` storage on Cloudflare or `local()` storage on Node. Browsers that accept JPEG XL
241
+ get verified copies; other browsers get the original. Open **Plugins → JPEG XL Image Optimizer** to choose the goal, effort
242
+ and widths or convert the existing library. Without `jxl()`, the site serves its originals.
243
+
244
+ ## Astro
245
+
246
+ ```sh
247
+ npx jpegxl add astro
248
+ ```
249
+
250
+ Then `<Image src={photo} format="jxl" />`. Astro 6 and 7.
251
+
252
+ - [Photos average 24% smaller than Astro's default WebP.](https://github.com/jackskip22/rapier-jxl/blob/main/bench/README.md#astro)
253
+ - [JPEGs 18% smaller, lossless.](https://github.com/jackskip22/rapier-jxl/blob/main/bench/README.md#astro)
254
+
255
+ ## Vite
256
+
257
+ ```sh
258
+ npx jpegxl add vite
259
+ ```
260
+
261
+ Then `import hero from './hero.jpg?jxl'`. Vite 6, 7 and 8.
262
+
263
+ - [Photos 39% smaller than WebP and 11% smaller than AVIF at the same look.](https://github.com/jackskip22/rapier-jxl/blob/main/bench/README.md#vite)
264
+ - [Camera JPEGs 17% smaller, lossless.](https://github.com/jackskip22/rapier-jxl/blob/main/bench/README.md#vite)
265
+
266
+ ## Cloudflare Workers
267
+
268
+ ```sh
269
+ npx jpegxl public/ --out public/
270
+ npx jpegxl add workers --route example.com/*
271
+ ```
272
+
273
+ Serves JPEG XL to browsers that accept it and the original to the rest. Runs on Workers Free.
274
+
275
+ - [Phone JPEGs 18% smaller, lossless.](https://github.com/jackskip22/rapier-jxl/blob/main/bench/README.md#cloudflare-workers)
276
+
277
+ ## Cloudflare R2
278
+
279
+ ```sh
280
+ npx jpegxl add r2
281
+ ```
282
+
283
+ Every JPEG or PNG put into the bucket gets a JPEG XL file beside it, made from the bucket's event notifications through a Queue. A JPEG's is lossless: `restore` gives the same JPEG back exactly. Large pictures convert as a Cloudflare Workflow. Reads answer JPEG XL to browsers that accept it and the original to the rest.
284
+
285
+ ## Cloudflare Agents
286
+
287
+ ```sh
288
+ npx jpegxl add agents
289
+ ```
290
+
291
+ JPEG XL tools for agents in an Agents SDK project: convert, recompress, restore, verify and inspect, as an MCP server and for an Agent class. Pictures stay in R2; the agent gets keys, never bytes.
292
+
293
+ ## Workers and queues
294
+
295
+ ```js
296
+ import {encode, configure, close} from 'jpegxl/upload';
297
+
298
+ configure({helpers: {count: 3, memoryBytes: 1 << 30}});
299
+ const photo = (width, height) => ({data: new Uint8Array(width * height * 4).fill(200), width, height});
300
+ try {
301
+ const files = await Promise.all([photo(1200, 900), photo(300, 225)].map(picture => encode(picture)));
302
+ } finally {
303
+ await close();
304
+ }
305
+ ```
306
+
307
+ - In browsers, each module's import runs it in its own worker (upload: 349 KB Brotli); no setup is
308
+ needed. Imported inside a worker of your own, it runs there. Node, Deno, Bun and edge hosts run it in the calling thread.
309
+ - `configure` sets a module's queue before its first call: `helpers`, `maxPixels`, and in a browser `maxPendingBytes`,
310
+ `maxPendingJobs` and `workerFactory`. `close()` ends its worker and helpers; the next call starts them again.
311
+ - `helpers` adds worker threads; `helpers: true` sizes them by the device.
312
+ - `transfer: true` on encode, fit, variants or capture hands the pixels' buffer to the call instead of copying it; the buffer is empty afterwards.
313
+ - Errors carry a `code`, such as `JXL_INPUT`, `JXL_OPTIONS`, `JXL_WASM` or `JXL_WEBGPU`.
314
+
315
+ ### Error codes
316
+
317
+ Every package refusal has a `code`. The message gives the specific cause; use this table for the next step. Caller-thrown errors and cancellation reasons pass through unchanged.
318
+
319
+ | Code | What happened | What to do |
320
+ | --- | --- | --- |
321
+ | `JXL_INPUT` | The image, bytes or source record cannot be read as supplied. | Pass a supported image or the pixel shape named in the message; replace a damaged source file. |
322
+ | `JXL_OPTIONS` | An option name or value is not accepted. | Use the option name, allowed value or range given in the message. |
323
+ | `JXL_DIMENSIONS` | Picture width, height or pixel count exceeds the allowed size. | Use positive whole-pixel dimensions and reduce the size, or raise `maxPixels` when appropriate. |
324
+ | `JXL_JPEG` | The JPEG file is missing required data or contains malformed markers. | Pass a complete, valid JPEG file. |
325
+ | `JXL_DECODE` | The JPEG XL file cannot be decoded correctly. | Check that the input is a complete JPEG XL file and use a suitable decoder. |
326
+ | `JXL_RECONSTRUCTION` | The JPEG XL file does not contain an original JPEG to restore. | Restore from a file made with `recompress()`, or decode the JPEG XL image instead. |
327
+ | `JXL_TARGET` | The requested file size, image-quality target or verification claim cannot be met. | Reduce the requirement or keep the original; consult the result's target details. |
328
+ | `JXL_PLATFORM` | This environment lacks a required image or decoding capability. | Follow the message's setup instructions or use an environment with that capability. |
329
+ | `JXL_MEMORY` | Available memory or a configured queue budget is insufficient. | Use a smaller image, reduce concurrent jobs or increase the relevant memory budget. |
330
+ | `JXL_LIMIT` | An input, output or operation exceeds a permitted byte or work limit. | Reduce the input or output, or increase the named limit where supported. |
331
+ | `JXL_WASM` | WebAssembly is blocked, lacks SIMD, or its module failed to compile or start (the host's words are in the message and `cause`). | Allow WebAssembly, use a host with SIMD, or act on the host's words. |
332
+ | `JXL_WEBGPU` | A required GPU is unavailable, or this job does not use WebGPU. | Leave `webgpu` unset, or choose a supported GPU and a compatible effort. |
333
+ | `JXL_WORKER` | A worker could not start, communicate or finish. | Allow the required worker source and check the worker setup described in the message. |
334
+ | `JXL_IO` | An input, output or stored file could not be accessed. | Check the path, permissions and storage access, then retry. |
335
+ | `JXL_CLOSED` | A worker queue is closing or already closed. | Finish closing it before starting further work; create a new queue where required. |
336
+ | `JXL_UNSUPPORTED` | This operation does not offer the requested input or feature combination. | Use the supported module, input or settings named in the message. |
337
+ | `JXL_SETUP` | An `add` or `remove` command cannot safely change project files. | Follow the manual setup step in the message, or repair the package installation. |
338
+ | `JXL_INTERNAL` | The library encountered a problem it could not handle. | Report the operation, input type and options with a reproducible example. |
339
+
340
+
341
+ ## Browsers
342
+
343
+ ```html
344
+ <script type="module">
345
+ import {encode} from 'https://cdn.jsdelivr.net/npm/jpegxl@8/dist/index.mjs';
346
+ const {bytes} = await encode(document.querySelector('canvas'));
347
+ </script>
348
+ ```
349
+
350
+ Content Security Policy: `'wasm-unsafe-eval'`, and by where the package is served:
351
+
352
+ | Served | The policy also allows |
353
+ | --- | --- |
354
+ | From the page's own origin | That origin in `script-src` and `worker-src`. No blob worker and no inline script. |
355
+ | A module from a CDN | `blob:` in `worker-src` and the CDN in `script-src`: the worker starts as a local `blob:` module that imports the CDN file, which the CDN serves with CORS. |
356
+ | The workerd and edge-light entries | Nothing more: they install their precompiled WebAssembly on import. |
357
+ | Under Trusted Types for worker URLs | Your policy, through `workerFactory`; the package installs none. |
358
+
359
+ - Every module needs WebAssembly with SIMD (`JXL_WASM` without it), except `restore` and `metadata`.
360
+ - Without native JPEG XL: `import {install} from 'jpegxl/polyfill'; await install();` shows the page's JPEG XL images, and those added later.
361
+ - Vite, webpack 5, Next.js, Parcel and Astro work as is. A Vite 7 workspace that installs rapier-jxl above the app's
362
+ folder needs `optimizeDeps: {exclude: ['jpegxl']}`.
363
+ - Each module's file is also its own worker and helpers. Angular: add `{"glob": "index.mjs", "input":
364
+ "node_modules/jpegxl/dist", "output": "/"}` to the build's `assets` in `angular.json` (the module's file, such as
365
+ `upload.mjs`, for another module).
366
+ - Rollup and esbuild: copy the module's file (`jpegxl/dist/index.mjs`, or `upload.mjs` and so on) beside the bundle.
367
+
368
+ Node 20.16+ or 22.3+, Deno, Bun, Cloudflare Workers.
369
+
370
+ ## License
371
+
372
+ MIT. Third-party notices: `THIRD_PARTY_NOTICES`.
373
+
374
+ ## Contributing
375
+
376
+ Anybody is welcome to contribute to rapier-jxl, which is intended to be as universal as possible. You can also greatly assist the project by simply performing tests on your computer which is always turning up new edge cases to improve the encoder. Testing on every kind of device is essential for a universal encoder. Check the jobs/ folder in the repo root, open an issue with the job's name as its title if you've started work on it, then please submit your results by attaching them to that issue.
377
+
378
+ For feedback, requests or questions, feel free to join the discussion. The goal is to make rapier-jxl as easy, fast, small, powerful and reliable as possible for every use case, while keeping the architecture simple and general.
379
+
380
+ Examples and plugins can be added for very common use cases.
@@ -0,0 +1,73 @@
1
+ Acorn JavaScript parser (MIT; bundled into the command-line setup tool only)
2
+
3
+ Copyright (C) 2012-2022 by various contributors (see https://github.com/acornjs/acorn/blob/master/AUTHORS)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
22
+
23
+ Brotli dictionary and transforms (RFC 7932)
24
+
25
+ Copyright (c) 2009, 2010, 2013-2016 by the Brotli Authors.
26
+
27
+ Permission is hereby granted, free of charge, to any person obtaining a copy
28
+ of this software and associated documentation files (the "Software"), to deal
29
+ in the Software without restriction, including without limitation the rights
30
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
31
+ copies of the Software, and to permit persons to whom the Software is
32
+ furnished to do so, subject to the following conditions:
33
+
34
+ The above copyright notice and this permission notice shall be included in
35
+ all copies or substantial portions of the Software.
36
+
37
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
38
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
39
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
40
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
41
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
42
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
43
+ THE SOFTWARE.
44
+
45
+ JPEG XL perceptual-metric arithmetic (BSD-3-Clause)
46
+
47
+ Copyright (c) the JPEG XL Project Authors.
48
+ All rights reserved.
49
+
50
+ Redistribution and use in source and binary forms, with or without
51
+ modification, are permitted provided that the following conditions are met:
52
+
53
+ 1. Redistributions of source code must retain the above copyright notice, this
54
+ list of conditions and the following disclaimer.
55
+
56
+ 2. Redistributions in binary form must reproduce the above copyright notice,
57
+ this list of conditions and the following disclaimer in the documentation
58
+ and/or other materials provided with the distribution.
59
+
60
+ 3. Neither the name of the copyright holder nor the names of its
61
+ contributors may be used to endorse or promote products derived from
62
+ this software without specific prior written permission.
63
+
64
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
65
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
66
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
67
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
68
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
69
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
70
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
71
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
72
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
73
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.