jpegxl 8.4.0 → 8.4.1

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 (88) hide show
  1. package/README.md +294 -229
  2. package/dist/animation.browser.mjs +2 -2
  3. package/dist/animation.mjs +2 -2
  4. package/dist/capture-complete.browser.mjs +2 -2
  5. package/dist/capture-complete.mjs +2 -2
  6. package/dist/capture-groups.mjs +2 -2
  7. package/dist/capture.browser.mjs +2 -2
  8. package/dist/capture.mjs +2 -2
  9. package/dist/cli-add.mjs +2 -2
  10. package/dist/cli-astro.mjs +2 -2
  11. package/dist/cli-cloudflare.mjs +2 -2
  12. package/dist/cli-emdash.mjs +2 -2
  13. package/dist/cli-places.mjs +2 -2
  14. package/dist/cli-selftest.mjs +2 -2
  15. package/dist/cli-workers.mjs +2 -2
  16. package/dist/cli.mjs +2 -2
  17. package/dist/decode.browser.mjs +2 -2
  18. package/dist/decode.mjs +2 -2
  19. package/dist/decode.node.mjs +2 -2
  20. package/dist/format.browser.mjs +2 -2
  21. package/dist/format.mjs +2 -2
  22. package/dist/hdr.mjs +2 -2
  23. package/dist/helpers.mjs +2 -2
  24. package/dist/index.browser.mjs +2 -2
  25. package/dist/index.mjs +2 -2
  26. package/dist/jpeg.browser.mjs +2 -2
  27. package/dist/jpeg.mjs +2 -2
  28. package/dist/jpeg.node.mjs +2 -2
  29. package/dist/metadata.mjs +2 -2
  30. package/dist/polyfill.mjs +2 -2
  31. package/dist/resumable.mjs +2 -2
  32. package/dist/resumable.node.mjs +2 -2
  33. package/dist/serve.mjs +2 -2
  34. package/dist/serve.node.mjs +2 -2
  35. package/dist/upload.browser.mjs +2 -2
  36. package/dist/upload.mjs +2 -2
  37. package/dist/verify.mjs +2 -2
  38. package/dist/verify.node.mjs +2 -2
  39. package/dist/wasm-modules.mjs +2 -2
  40. package/examples/agents/jxl-tools.mjs +8 -8
  41. package/examples/android/prepare-assets.mjs +2 -2
  42. package/examples/capacitor/prepare-assets.mjs +2 -2
  43. package/examples/emdash/admin-work.mjs +1 -1
  44. package/examples/emdash/backfill.mjs +4 -4
  45. package/examples/emdash/background.mjs +5 -5
  46. package/examples/emdash/browser-candidate.mjs +1 -1
  47. package/examples/emdash/deliver.mjs +2 -2
  48. package/examples/emdash/host-policy.mjs +6 -6
  49. package/examples/emdash/index.mjs +3 -3
  50. package/examples/emdash/job-runner.mjs +31 -31
  51. package/examples/emdash/job-store.mjs +21 -21
  52. package/examples/emdash/jpeg-source.mjs +2 -2
  53. package/examples/emdash/library-jobs.mjs +21 -21
  54. package/examples/emdash/local-store.mjs +16 -16
  55. package/examples/emdash/media-admin.mjs +9 -9
  56. package/examples/emdash/media-plugin.mjs +62 -62
  57. package/examples/emdash/media-storage.mjs +55 -55
  58. package/examples/emdash/media-words.mjs +89 -89
  59. package/examples/emdash/media-worker.mjs +1 -1
  60. package/examples/emdash/original-envelope.mjs +2 -2
  61. package/examples/emdash/originals.mjs +77 -77
  62. package/examples/emdash/r2-store.mjs +3 -3
  63. package/examples/emdash/read-all.mjs +14 -14
  64. package/examples/emdash/server-only.mjs +1 -1
  65. package/examples/emdash/storage.mjs +1 -1
  66. package/examples/emdash/structural-delivery.mjs +42 -42
  67. package/examples/emdash/thread-driver.mjs +15 -15
  68. package/examples/emdash/thread-worker.mjs +3 -3
  69. package/examples/emdash/work-queue.mjs +11 -11
  70. package/examples/flutter/prepare-assets.mjs +3 -3
  71. package/examples/ios/prepare-assets.mjs +3 -3
  72. package/examples/page-rects.js +14 -14
  73. package/examples/react-native/src/JXLProvider.tsx +19 -9
  74. package/examples/snapdom/jxl.js +3 -2
  75. package/examples/svg-jxl.js +10 -10
  76. package/package.json +1 -1
  77. package/types/animation.d.mts +2 -2
  78. package/types/capture-complete.d.mts +5 -5
  79. package/types/capture.d.mts +1 -1
  80. package/types/format.d.mts +2 -2
  81. package/types/index.d.mts +6 -6
  82. package/types/jpeg.d.mts +1 -1
  83. package/types/result.d.mts +5 -4
  84. package/types/resumable.d.mts +7 -7
  85. package/types/serve.d.mts +1 -1
  86. package/types/types.d.mts +19 -18
  87. package/types/upload.d.mts +1 -1
  88. package/types/verify.d.mts +4 -4
@@ -26,7 +26,7 @@ const OWNER = /^[a-f0-9]{32}$/;
26
26
  const WRITE_HORIZON_MS = 24 * 60 * 60 * 1000;
27
27
  function fragments(ref, owner) {
28
28
  if (!HASH.test(ref?.hash ?? '') || !Number.isSafeInteger(ref.length) || ref.length < 0 || ref.length > MAX_PART)
29
- throw fail('JXL_INPUT', "Invalid part; pass immutable bytes of at most 1 MiB.");
29
+ throw fail('JXL_INPUT', "part: immutable bytes <=1MiB");
30
30
  return Array.from({length: Math.max(1, Math.ceil(ref.length / FRAGMENT))}, (_, index) => ({
31
31
  key: `jxl:${owner}:${ref.hash}:${index}`, offset: index * FRAGMENT,
32
32
  length: Math.min(FRAGMENT, ref.length - index * FRAGMENT),
@@ -52,19 +52,19 @@ const base64 = bytes => {
52
52
  // Only the JSON transport splits a part. The shared driver owns all source pages and journal records.
53
53
  const randomHex = () => [...crypto.getRandomValues(new Uint8Array(8))].map(byte => byte.toString(16).padStart(2, '0')).join('');
54
54
  export function createEmDashJobStore(ctx, {readSource, calls = createEmDashCallCounter(), owner, now = () => Date.now()} = {}) {
55
- if (!OWNER.test(owner ?? '')) throw fail('JXL_OPTIONS', "Invalid owner; pass the job ID for these parts.");
55
+ if (!OWNER.test(owner ?? '')) throw fail('JXL_OPTIONS', "owner: matching job ID");
56
56
  const parts = ctx?.storage?.jxlParts;
57
57
  if (typeof parts?.getMany !== 'function' || typeof parts?.putMany !== 'function' || typeof readSource !== 'function')
58
- throw fail('JXL_OPTIONS', "Missing job storage or source; supply jxlParts and a source reader.");
58
+ throw fail('JXL_OPTIONS', "job store: jxlParts and source reader");
59
59
  const cache = new Map();
60
60
  let known = null;
61
61
  async function readMany(refs) {
62
62
  if (!Array.isArray(refs) || refs.length > 128 || refs.reduce((n, ref) => n + ref.length, 0) > MAX_BATCH)
63
- throw fail('JXL_LIMIT', "Part batch too large; read at most 128 parts and 8 MiB.");
63
+ throw fail('JXL_LIMIT', "parts: <=128 and <=8MiB");
64
64
  const groups = refs.map(ref => fragments(ref, owner)), keys = [...new Set(groups.flat().map(part => part.key))].filter(key => !cache.has(key));
65
65
  if (keys.length) {
66
66
  const found = await calls.call(() => parts.getMany(keys));
67
- if (!(found instanceof Map)) throw fail('JXL_IO', "Invalid part batch; check storage and retry.");
67
+ if (!(found instanceof Map)) throw fail('JXL_IO', "part batch: storage");
68
68
  // Only a part that exists: a missing one stays unknown, so a later write of it is not skipped.
69
69
  for (const key of keys) if (found.has(key)) cache.set(key, found.get(key));
70
70
  }
@@ -73,19 +73,19 @@ export function createEmDashJobStore(ctx, {readSource, calls = createEmDashCallC
73
73
  for (const part of groups[index]) {
74
74
  const saved = cache.get(part.key);
75
75
  if (typeof saved !== 'string' || saved.length !== 4 * Math.ceil(part.length / 3))
76
- throw fail('JXL_IO', "Missing or truncated part; restore its saved data.");
76
+ throw fail('JXL_IO', "part: restore missing/truncated");
77
77
  // The runtime's own decoder where it has one (setFromBase64: strict, written in place, about a tenth of the
78
78
  // time of atob and a loop over its string); else atob.
79
79
  if (typeof bytes.setFromBase64 === 'function') {
80
80
  let done;
81
81
  try { done = bytes.subarray(part.offset, part.offset + part.length).setFromBase64(saved, {lastChunkHandling: 'strict'}); }
82
- catch { throw fail('JXL_IO', "Invalid part base64; check storage and retry."); }
83
- if (done.read !== saved.length || done.written !== part.length) throw fail('JXL_IO', "Wrong part length; check storage and retry.");
82
+ catch { throw fail('JXL_IO', "part: base64"); }
83
+ if (done.read !== saved.length || done.written !== part.length) throw fail('JXL_IO', "part: length mismatch");
84
84
  continue;
85
85
  }
86
86
  let text;
87
- try { text = atob(saved); } catch { throw fail('JXL_IO', "Invalid part base64; check storage and retry."); }
88
- if (text.length !== part.length) throw fail('JXL_IO', "Wrong part length; check storage and retry.");
87
+ try { text = atob(saved); } catch { throw fail('JXL_IO', "part: base64"); }
88
+ if (text.length !== part.length) throw fail('JXL_IO', "part: length mismatch");
89
89
  for (let i = 0; i < text.length; i++) bytes[part.offset + i] = text.charCodeAt(i);
90
90
  }
91
91
  return bytes;
@@ -97,7 +97,7 @@ export function createEmDashJobStore(ctx, {readSource, calls = createEmDashCallC
97
97
  const rows = [], named = new Set();
98
98
  for (const {ref, bytes} of items) {
99
99
  const pieces = fragments(ref, owner);
100
- if (!(bytes instanceof Uint8Array) || bytes.length !== ref.length) throw fail('JXL_INPUT', "Wrong part length; reload its record and retry.");
100
+ if (!(bytes instanceof Uint8Array) || bytes.length !== ref.length) throw fail('JXL_INPUT', "part: reload record");
101
101
  for (const part of pieces) {
102
102
  if (cache.has(part.key) || named.has(part.key)) continue;
103
103
  named.add(part.key);
@@ -194,9 +194,9 @@ export function createEmDashJobStore(ctx, {readSource, calls = createEmDashCallC
194
194
  return;
195
195
  }
196
196
  known = null;
197
- if (saved?.applied !== false) throw fail('JXL_IO', "Part ledger write unconfirmed; check it before retrying.");
197
+ if (saved?.applied !== false) throw fail('JXL_IO', "part ledger write: unconfirmed");
198
198
  }
199
- throw fail('JXL_IO', "Part ledger changed; reload its record and retry.");
199
+ throw fail('JXL_IO', "part ledger: changed; reload");
200
200
  }
201
201
  async function deleteKeys(keys) {
202
202
  let deleted = 0;
@@ -230,7 +230,7 @@ export function createEmDashJobStore(ctx, {readSource, calls = createEmDashCallC
230
230
  closedAt = now();
231
231
  const saved = await calls.call(() => parts.compareAndSet(ledgerKey, revision, valueOf(held, held.keys, held.pending, true, closedAt, held.unconfirmed)));
232
232
  if (saved?.applied === false) continue;
233
- if (saved?.applied !== true) throw fail('JXL_IO', "Part ledger close unconfirmed; check it before retrying.");
233
+ if (saved?.applied !== true) throw fail('JXL_IO', "part ledger close: unconfirmed");
234
234
  revision = saved.revision;
235
235
  }
236
236
  const keys = held.keys.filter(key => typeof key === 'string' && key.startsWith(`jxl:${owner}:`));
@@ -240,13 +240,13 @@ export function createEmDashJobStore(ctx, {readSource, calls = createEmDashCallC
240
240
  const deletedOpen = await deleteKeys(waiting), absent = waiting.length - deletedOpen;
241
241
  const live = Object.values(held.pending).filter(at => Number.isFinite(at) && now() - at < WRITE_HORIZON_MS).length;
242
242
  if ((absent > 0 && now() - closedAt < WRITE_HORIZON_MS) || live > 0)
243
- throw fail('JXL_BUSY', "Write may still commit; check its saved state before cleanup.");
243
+ throw fail('JXL_BUSY', "write: pending; check before cleanup");
244
244
  const deleted = deletedOpen + await deleteKeys(keys.filter(key => !open.has(key)));
245
245
  if (keys.length || Object.keys(held.pending).length)
246
246
  await calls.call(() => parts.compareAndSet(ledgerKey, revision, valueOf(held, [], {}, true, closedAt, [])));
247
247
  return deleted;
248
248
  }
249
- throw fail('JXL_IO', "Part ledger changed; reload its record and retry.");
249
+ throw fail('JXL_IO', "part ledger: changed; reload");
250
250
  },
251
251
  read: async ref => (await readMany([ref]))[0],
252
252
  readMany,
@@ -260,23 +260,23 @@ export function createEmDashJobStore(ctx, {readSource, calls = createEmDashCallC
260
260
  export async function acquireEmDashAdvance(ctx, {owner, scope, ms, now = () => Date.now(), calls = createEmDashCallCounter()} = {}) {
261
261
  if (!OWNER.test(owner ?? '') || typeof scope !== 'string' || !Number.isFinite(ms) || ms <= 0 || ms > 60000 ||
262
262
  typeof ctx?.kv?.getVersioned !== 'function' || typeof ctx?.kv?.compareAndSet !== 'function')
263
- throw fail('JXL_OPTIONS', "Invalid advance; pass a saved job and its budget.");
263
+ throw fail('JXL_OPTIONS', "advance: saved job and budget");
264
264
  const key = `jxl:advance:${scope}:${owner}`, at = now();
265
- if (!Number.isFinite(at)) throw fail('JXL_OPTIONS', "Invalid lease clock; pass a finite number.");
265
+ if (!Number.isFinite(at)) throw fail('JXL_OPTIONS', "lease clock: finite number");
266
266
  const row = await calls.call(() => ctx.kv.getVersioned(key));
267
267
  if (row?.value != null && (!Number.isFinite(row.value.until) || row.value.until < 0))
268
- throw fail('JXL_IO', "Invalid advance lease; check storage and retry.");
268
+ throw fail('JXL_IO', "advance lease: storage");
269
269
  if (row?.value?.until > at) return null;
270
270
  // Allow time for the call's I/O as well as its cooperative CPU budget. A dead process leaves only this short wait.
271
271
  const saved = await calls.call(() => ctx.kv.compareAndSet(key, row?.revision ?? null,
272
272
  {until: at + Math.max(30000, ms * 2)}));
273
273
  if (saved?.applied === false) return null;
274
274
  if (saved?.applied !== true || saved.revision == null)
275
- throw fail('JXL_IO', "Advance lease unconfirmed; check it before retrying.");
275
+ throw fail('JXL_IO', "advance lease: unconfirmed");
276
276
  return async () => {
277
277
  // A late release cannot clear the lease acquired by another invocation after expiry.
278
278
  const released = await calls.call(() => ctx.kv.compareAndSet(key, saved.revision, {until: 0}));
279
279
  if (released?.applied !== true && released?.applied !== false)
280
- throw fail('JXL_IO', "Lease release unconfirmed; check it before retrying.");
280
+ throw fail('JXL_IO', "lease release: unconfirmed");
281
281
  };
282
282
  }
@@ -10,10 +10,10 @@ export const pixelColor = samples => samples.renderingIntent !== undefined ? {co
10
10
  export async function jpegPixels(bytes, input, {maxPixels, signal} = {}) {
11
11
  const [{recompress}, {decode}] = await Promise.all([import('jpegxl/jpeg'), import('jpegxl/decode')]);
12
12
  const kept = await recompress(bytes, {effort: 1, ...(maxPixels === undefined ? {} : {maxPixels})});
13
- if (!(kept?.bytes instanceof Uint8Array)) throw fail('JXL_UNSUPPORTED', "JPEG recompression failed; keep the original JPEG.");
13
+ if (!(kept?.bytes instanceof Uint8Array)) throw fail('JXL_UNSUPPORTED', "JPEG recompression: keep original");
14
14
  signal?.throwIfAborted();
15
15
  const image = await decode(kept.bytes, maxPixels === undefined ? {} : {maxPixels}), data = new Uint8Array(image.data.buffer, image.data.byteOffset, image.data.byteLength);
16
- if (data.length !== image.width * image.height * 4) throw fail('JXL_UNSUPPORTED', "JPEG unreadable here; pass pixels from a host reader.");
16
+ if (data.length !== image.width * image.height * 4) throw fail('JXL_UNSUPPORTED', "JPEG: host reader pixels");
17
17
  const icc = image.rgbaICC instanceof Uint8Array && image.rgbaICC.byteLength > 0 && image.rgbaICC.byteLength <= 2048 ? image.rgbaICC : null;
18
18
  const enc = image.rgbaColorEncoding ?? {};
19
19
  const primaries = enc.space === 'gray' ? 'srgb' : enc.primaries;
@@ -10,13 +10,13 @@ const RETRY_LIMIT = 9;
10
10
  const terminal = state => state === 'done' || state === 'canceled';
11
11
  const normalize = items => {
12
12
  if (!Array.isArray(items) || !items.length || items.length > 100)
13
- throw fail('JXL_INPUT', "Invalid selection; send 1 to 100 images.");
13
+ throw fail('JXL_INPUT', "selection: 1-100 images");
14
14
  return items.map(item => {
15
- if (!item || typeof item !== 'object' || Array.isArray(item)) throw fail('JXL_INPUT', "Invalid image reference; pass its ID and key.");
15
+ if (!item || typeof item !== 'object' || Array.isArray(item)) throw fail('JXL_INPUT', "image reference: ID and key");
16
16
  const {id, key, name} = item;
17
17
  if (typeof id !== 'string' || !MEDIA.test(id) || typeof key !== 'string' || !KEY.test(key) ||
18
18
  name !== undefined && typeof name !== 'string')
19
- throw fail('JXL_INPUT', "Invalid image reference; pass its ID and key.");
19
+ throw fail('JXL_INPUT', "image reference: ID and key");
20
20
  return {id, key, name: name ?? key};
21
21
  });
22
22
  };
@@ -26,7 +26,7 @@ export function createLibraryRun(ctx, {scope, service, prepare, validate, now =
26
26
  const pages = ctx.storage?.jxl_library;
27
27
  if (!scope || typeof pages?.get !== 'function' || typeof pages?.compareAndSet !== 'function' ||
28
28
  typeof pages?.put !== 'function' || typeof prepare !== 'function' || typeof validate !== 'function')
29
- throw fail('JXL_OPTIONS', "Missing library storage or runner; configure both.");
29
+ throw fail('JXL_OPTIONS', "library: storage and runner");
30
30
  const call = action => service.calls.call(action), runKey = `jxl:library:${scope}`;
31
31
  const pageKey = (id, page) => `${scope}:${id}:${page}`;
32
32
  const read = async () => await call(() => ctx.kv.getVersioned(runKey)) ?? {value: null, revision: null};
@@ -42,11 +42,11 @@ export function createLibraryRun(ctx, {scope, service, prepare, validate, now =
42
42
  const changed = await call(() => ctx.kv.compareAndSet(runKey, row.revision, value));
43
43
  if (changed?.applied === true) return {value, revision: changed.revision};
44
44
  if (changed?.applied === false) return read();
45
- throw fail('JXL_IO', "Library checkpoint unconfirmed; check it before retrying.");
45
+ throw fail('JXL_IO', "library checkpoint: unconfirmed");
46
46
  }
47
47
  function own(row, id) {
48
48
  if (typeof id !== 'string' || !ID.test(id) || row.value?.id !== id)
49
- throw fail('JXL_INPUT', "Stale library run; reload it.");
49
+ throw fail('JXL_INPUT', "library run: reload");
50
50
  return row.value;
51
51
  }
52
52
  const schedule = id => service.work.schedule('library', id);
@@ -108,7 +108,7 @@ export function createLibraryRun(ctx, {scope, service, prepare, validate, now =
108
108
  if (!item) {
109
109
  const latest = await read();
110
110
  if (latest.revision !== row.revision) return view(latest);
111
- throw fail('JXL_IO', "Missing selection page; restore it.");
111
+ throw fail('JXL_IO', "selection page: restore missing");
112
112
  }
113
113
  const jobId = (await digest(new TextEncoder().encode(JSON.stringify([scope, id, item.id, item.key])))).slice(0, 32);
114
114
  return view(await save(row, {...run, current: {...item, jobId, stage: 'prepare', pageLength: page.items.length, command: null}}));
@@ -140,7 +140,7 @@ export function createLibraryRun(ctx, {scope, service, prepare, validate, now =
140
140
  return view(await save(row, {...run, current: {...item, stage: 'waiting'}}));
141
141
  }
142
142
  const job = await service.status(item.jobId);
143
- if (!job) throw fail('JXL_IO', "Missing image job; restore it.");
143
+ if (!job) throw fail('JXL_IO', "image job: restore missing");
144
144
  if (item.invalid) {
145
145
  const stopped = job.done || job.canceled ? job : await service.cancel(item.jobId);
146
146
  if (!stopped?.canceled && !stopped?.done) return view(row);
@@ -161,14 +161,14 @@ export function createLibraryRun(ctx, {scope, service, prepare, validate, now =
161
161
  async start({id, total, settings}) {
162
162
  if (typeof id !== 'string' || !ID.test(id) || !Number.isSafeInteger(total) || total < 1 ||
163
163
  !settings || typeof settings !== 'object' || Array.isArray(settings))
164
- throw fail('JXL_INPUT', "Incomplete request; pass run ID, selection count, and site settings.");
164
+ throw fail('JXL_INPUT', "request: run ID, count, settings");
165
165
  const selectedSettings = normalizeSettings(settings);
166
166
  const row = await read(), old = row.value;
167
167
  if (old?.id === id) {
168
- if (old.expected !== total) throw fail('JXL_INPUT', "Selection count changed; reload it.");
168
+ if (old.expected !== total) throw fail('JXL_INPUT', "selection count: changed; reload");
169
169
  return view(row);
170
170
  }
171
- if (old && !terminal(old.state)) throw fail('JXL_INPUT', "Library run active; finish or cancel it.");
171
+ if (old && !terminal(old.state)) throw fail('JXL_INPUT', "library run: finish or cancel");
172
172
  if (old?.cleanup !== null && old?.cleanup !== undefined) await clean(old);
173
173
  if (old) await service.work.remove('library', old.id);
174
174
  return view(await save(row, {id, scope, state: 'preparing', expected: total, settings: selectedSettings, pages: 0, total: 0,
@@ -178,36 +178,36 @@ export function createLibraryRun(ctx, {scope, service, prepare, validate, now =
178
178
  async append({id, page, items}) {
179
179
  const selection = normalize(items), row = await read(), run = own(row, id);
180
180
  if (!Number.isSafeInteger(page) || page < 0 || page > run.pages)
181
- throw fail('JXL_INPUT', "Page out of order; append the next page.");
181
+ throw fail('JXL_INPUT', "page: append next");
182
182
  const key = pageKey(id, page), data = {items: selection};
183
183
  if (page < run.pages) {
184
184
  const prior = await call(() => pages.get(key));
185
- if (JSON.stringify(prior) !== JSON.stringify(data)) throw fail('JXL_INPUT', "Page already saved; append the next page.");
185
+ if (JSON.stringify(prior) !== JSON.stringify(data)) throw fail('JXL_INPUT', "page: append next");
186
186
  return view(row);
187
187
  }
188
188
  if (run.state !== 'preparing' || run.total + selection.length > run.expected)
189
- throw fail('JXL_INPUT', "Selection closed; start a new selection.");
189
+ throw fail('JXL_INPUT', "selection: start new");
190
190
  let previous = run.lastId;
191
191
  for (const item of selection) {
192
192
  const normalized = item.id.toUpperCase();
193
- if (normalized <= previous) throw fail('JXL_INPUT', "IDs repeat or are unordered; use unique IDs in ascending order.");
193
+ if (normalized <= previous) throw fail('JXL_INPUT', "IDs: unique ascending");
194
194
  previous = normalized;
195
195
  }
196
196
  const put = await call(() => pages.compareAndSet(key, null, data));
197
197
  if (put?.applied !== true) {
198
- if (put?.applied !== false) throw fail('JXL_IO', "Selection page unconfirmed; check it before retrying.");
198
+ if (put?.applied !== false) throw fail('JXL_IO', "selection page: unconfirmed");
199
199
  const prior = await call(() => pages.get(key));
200
- if (JSON.stringify(prior) !== JSON.stringify(data)) throw fail('JXL_INPUT', "Selection page changed; reload it.");
200
+ if (JSON.stringify(prior) !== JSON.stringify(data)) throw fail('JXL_INPUT', "selection page: changed; reload");
201
201
  }
202
202
  return view(await save(row, {...run, pages: page + 1, total: run.total + selection.length, lastId: previous}));
203
203
  },
204
204
  async control({id, action}) {
205
- if (!['resume', 'pause', 'cancel'].includes(action)) throw fail('JXL_INPUT', "Unknown library action; use resume, pause, or cancel.");
205
+ if (!['resume', 'pause', 'cancel'].includes(action)) throw fail('JXL_INPUT', "action: resume, pause, cancel");
206
206
  let row = await read();
207
207
  for (let attempt = 0; attempt < 3; attempt++) {
208
208
  const run = own(row, id);
209
209
  if (terminal(run.state) || run.state === 'canceling') return view(row);
210
- if (action === 'resume' && run.total !== run.expected) throw fail('JXL_INPUT', "Incomplete selection; queue its remaining images.");
210
+ if (action === 'resume' && run.total !== run.expected) throw fail('JXL_INPUT', "selection: queue remaining");
211
211
  if (action === 'pause' && run.state === 'preparing') return view(row);
212
212
  // Schedule before the checkpoint so an interrupted acknowledgement cannot strand an accepted run.
213
213
  if (action !== 'pause') await schedule(id);
@@ -216,11 +216,11 @@ export function createLibraryRun(ctx, {scope, service, prepare, validate, now =
216
216
  if (saved.value?.id !== id || saved.value?.state === state) return view(saved);
217
217
  row = saved;
218
218
  }
219
- throw fail('JXL_IO', "Library run changed; read its progress.");
219
+ throw fail('JXL_IO', "library run: refresh progress");
220
220
  },
221
221
  advance,
222
222
  async resume(id) {
223
- if (typeof id !== 'string' || !ID.test(id)) throw fail('JXL_INPUT', "Invalid run ID; use the saved run ID.");
223
+ if (typeof id !== 'string' || !ID.test(id)) throw fail('JXL_INPUT', "run ID: saved ID");
224
224
  const row = await read();
225
225
  if (row.value?.id !== id) {
226
226
  await service.work.remove('library', id);
@@ -18,37 +18,37 @@ const contentType = key => /\.(?:jpe?g|jpe|jfif)$/i.test(key) ? 'image/jpeg' : /
18
18
  export function localStore(inner, directory, maxBytes = 256 * 1024 * 1024) {
19
19
  const root = resolve(directory), privateDirectory = join(root, PRIVATE);
20
20
  function filePath(key) {
21
- if (typeof key !== 'string' || !key || key.includes('\0')) throw invalid("Key escapes storage; use a key within its directory.");
21
+ if (typeof key !== 'string' || !key || key.includes('\0')) throw invalid("key: within storage directory");
22
22
  const path = resolve(root, key.replace(/^\//, ''));
23
- if (!path.startsWith(root + sep)) throw invalid("Key escapes storage; use a key within its directory.");
23
+ if (!path.startsWith(root + sep)) throw invalid("key: within storage directory");
24
24
  return path;
25
25
  }
26
26
  async function confinedPath(key) {
27
27
  const target = filePath(key);
28
- try { if ((await lstat(target)).isSymbolicLink()) throw invalid("Invalid media path; symbolic links are not permitted in storage."); }
28
+ try { if ((await lstat(target)).isSymbolicLink()) throw invalid("media path: no symlinks"); }
29
29
  catch (error) { if (error.code !== 'ENOENT') throw error; }
30
30
  let baseReal;
31
31
  try { baseReal = await realpath(root); } catch (error) { if (error.code === 'ENOENT') baseReal = root; else throw error; }
32
32
  for (let current = dirname(target); current.startsWith(root + sep); current = dirname(current)) {
33
33
  try {
34
34
  const info = await lstat(current);
35
- if (info.isSymbolicLink()) throw invalid("Invalid media path; symbolic links are not permitted in storage.");
35
+ if (info.isSymbolicLink()) throw invalid("media path: no symlinks");
36
36
  const actual = await realpath(current);
37
37
  if (actual !== baseReal && !actual.startsWith(baseReal + sep))
38
- throw invalid("Key escapes storage; use a key within its directory.");
38
+ throw invalid("key: within storage directory");
39
39
  break;
40
40
  } catch (error) { if (error.code !== 'ENOENT') throw error; }
41
41
  }
42
42
  try {
43
43
  const leaf = await lstat(target);
44
- if (leaf.isSymbolicLink()) throw invalid("Invalid media file; use a regular file.");
44
+ if (leaf.isSymbolicLink()) throw invalid("media file: regular file");
45
45
  } catch (error) { if (error.code !== 'ENOENT') throw error; }
46
46
  return target;
47
47
  }
48
48
  const revisionPath = key => join(privateDirectory, createHash('sha256').update(key).digest('hex') + '.revision.json');
49
49
  async function ensurePrivate(create = false) {
50
50
  try {
51
- if (!(await lstat(privateDirectory)).isDirectory()) throw invalid("Invalid revision directory; use a regular directory.");
51
+ if (!(await lstat(privateDirectory)).isDirectory()) throw invalid("revision directory: regular directory");
52
52
  return true;
53
53
  } catch (error) {
54
54
  if (error.code !== 'ENOENT') throw error;
@@ -61,7 +61,7 @@ export function localStore(inner, directory, maxBytes = 256 * 1024 * 1024) {
61
61
  const target = await confinedPath(key);
62
62
  try {
63
63
  const value = await lstat(target, {bigint: true});
64
- if (!value.isFile()) throw invalid("Invalid media file; use a regular file.");
64
+ if (!value.isFile()) throw invalid("media file: regular file");
65
65
  return [value.dev, value.ino, value.size, value.mtimeNs, value.ctimeNs, value.birthtimeNs].map(String);
66
66
  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
67
67
  }
@@ -80,20 +80,20 @@ export function localStore(inner, directory, maxBytes = 256 * 1024 * 1024) {
80
80
  const path = revisionPath(key);
81
81
  let info;
82
82
  try { info = await lstat(path); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
83
- if (!info.isFile() || info.size > MAX_REVISION_BYTES) throw invalid("Invalid revision; restore its saved record.");
83
+ if (!info.isFile() || info.size > MAX_REVISION_BYTES) throw invalid("revision: restore saved record");
84
84
  const bytes = await readFile(path);
85
85
  let value;
86
86
  try { value = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(bytes)); }
87
- catch { throw invalid("Invalid revision; restore its saved record."); }
87
+ catch { throw invalid("revision: restore saved record"); }
88
88
  if (bytes.length > MAX_REVISION_BYTES || value?.owner !== OWNER || value.kind !== 'revision' ||
89
89
  value.source !== key || !UUID.test(value.version ?? '') ||
90
90
  !(value.stat === null || Array.isArray(value.stat) && value.stat.length === 6 &&
91
91
  value.stat.every(item => typeof item === 'string' && /^-?[0-9]+$/.test(item))))
92
- throw invalid("Invalid revision; restore its saved record.");
92
+ throw invalid("revision: restore saved record");
93
93
  return {value, bytes};
94
94
  }
95
95
  async function writeRevision(key, value, bytes = Buffer.from(JSON.stringify(value))) {
96
- if (bytes.length > MAX_REVISION_BYTES) throw invalid("Revision too large; reduce its contents.");
96
+ if (bytes.length > MAX_REVISION_BYTES) throw invalid("revision: too large");
97
97
  await ensurePrivate(true);
98
98
  const path = revisionPath(key), temporary = path + '.' + randomUUID() + '.tmp';
99
99
  try { await writeFile(temporary, bytes, {flag: 'wx', mode: 0o600}); await rename(temporary, path); }
@@ -175,7 +175,7 @@ export function localStore(inner, directory, maxBytes = 256 * 1024 * 1024) {
175
175
  options?.signal?.throwIfAborted();
176
176
  if (!publicSource(key)) return key.startsWith(PRIVATE) ? {...result, ...(key.endsWith('.json') && {etag: await privateEtag(key)}), version: await privateEtag(key)} : result;
177
177
  const saved = await currentRevision(key, await identity(key));
178
- if (!saved) throw invalid("Media file disappeared; restore it before retrying.");
178
+ if (!saved) throw invalid("media file: restore missing");
179
179
  const version = saved.value.version;
180
180
  const metadata = saved.value.originalId ? {originalId: saved.value.originalId, representation: saved.value.representation,
181
181
  contentType: saved.value.contentType ?? result.contentType} : {};
@@ -202,7 +202,7 @@ export function localStore(inner, directory, maxBytes = 256 * 1024 * 1024) {
202
202
  });
203
203
  const compareAndSet = (key, body, {etag, contentType, signal} = {}) => locked(key, async () => {
204
204
  if (!key.startsWith(PRIVATE) || !key.endsWith('.json') || etag !== null && (typeof etag !== 'string' || !etag))
205
- throw invalid("Missing revision; pass the stored revision.");
205
+ throw invalid("revision: stored revision");
206
206
  signal?.throwIfAborted();
207
207
  if (await privateEtag(key) !== etag) return false;
208
208
  const result = await privateWrite({key, body, contentType, signal}, etag === null);
@@ -224,7 +224,7 @@ export function localStore(inner, directory, maxBytes = 256 * 1024 * 1024) {
224
224
  if (!publicSource(key) || !/\.(?:jpe?g|jpe|jfif)$/i.test(key) ||
225
225
  !UUID.test(options.expectedVersion ?? '') || options.etag !== options.expectedVersion ||
226
226
  !/^[a-f0-9]{32}$/.test(options.originalId ?? '') || !['jxl', 'jpeg'].includes(options.representation))
227
- throw invalid("Missing replacement identities; pass source and archive identities.");
227
+ throw invalid("replacement: source and archive identities");
228
228
  options.signal?.throwIfAborted();
229
229
  const before = await identity(key), prior = await currentRevision(key, before);
230
230
  if (!before || prior?.value.version !== options.expectedVersion) return null;
@@ -241,7 +241,7 @@ export function localStore(inner, directory, maxBytes = 256 * 1024 * 1024) {
241
241
  options.signal?.throwIfAborted();
242
242
  if (options.lastModified) {
243
243
  const time = new Date(options.lastModified);
244
- if (!Number.isFinite(time.getTime())) throw invalid("Invalid modification time; correct the file metadata.");
244
+ if (!Number.isFinite(time.getTime())) throw invalid("mtime: valid file timestamp");
245
245
  await utimes(filePath(temporary), time, time);
246
246
  }
247
247
  await rename(filePath(temporary), filePath(key));
@@ -47,7 +47,7 @@ function createOriginalsClient({request, change = () => {}}) {
47
47
  const accept = next => {
48
48
  check(control.signal);
49
49
  if (!next || typeof next.available !== 'boolean' || typeof next.enabled !== 'boolean' || typeof next.desired !== 'boolean'
50
- || !['idle', 'restoring', 'archiving'].includes(next.phase)) throw new Error('The originals policy is unavailable.');
50
+ || !['idle', 'restoring', 'archiving'].includes(next.phase)) throw new Error('originals policy: unavailable');
51
51
  if (held && held.stamp !== originalsStamp(next)) held = null;
52
52
  if (wanted !== undefined && next.desired === wanted) wanted = undefined;
53
53
  value = next; report(); return value;
@@ -74,7 +74,7 @@ function createOriginalsClient({request, change = () => {}}) {
74
74
  load: () => serial('originals-load', async () => accept(await call('/originals-policy'))),
75
75
  tick: () => serial('originals-advance', async () => {accept(await call('/originals-policy')); return advance();}),
76
76
  save: enabled => serial('originals-save', async () => {
77
- if (typeof enabled !== 'boolean') throw new TypeError('The originals policy is a boolean.');
77
+ if (typeof enabled !== 'boolean') throw new TypeError('originals policy: boolean');
78
78
  if (!value) accept(await call('/originals-policy'));
79
79
  if (enabled && !value.available || value.phase === 'restoring') return value;
80
80
  wanted = enabled; held = null;
@@ -164,7 +164,7 @@ async function browserConvert(item, selected, signal, update, widthsOnly = false
164
164
  // Queued work cannot claim a newer source or delivery decision with its older settings.
165
165
  if (item.generation && captured.generation !== item.generation || item.deliveryRevision && captured.deliveryRevision !== item.deliveryRevision
166
166
  || claimed && captured.mode !== 'copies')
167
- throw Object.assign(new Error('The picture or delivery setting changed.'), {code: 'key_changed'});
167
+ throw Object.assign(new Error('picture/delivery: changed'), {code: 'key_changed'});
168
168
  if (!widthsOnly && !claimed) {
169
169
  // A fresh revision owns this main conversion; older upload work cannot publish over it.
170
170
  captured = {...captured, ...await post('/delivery', {...identity(item), generation: captured.generation,
@@ -189,16 +189,16 @@ async function browserConvert(item, selected, signal, update, widthsOnly = false
189
189
  {file, settings: workerSettings, archiveOriginals, ...(deliveryOnly && {deliveryOnly: true}), ...(widthsOnly && {widthsOnly: true, main})},
190
190
  {signal, progress: progress => update({progress: Math.max(0, Math.min(1, progress))})});
191
191
  if (deliveryOnly && [made.result, ...made.copies].some(result => result?.meetsTarget && result.browserVerification?.verified !== true))
192
- throw Object.assign(new Error("Browser verifier did not verify this delivery; verify its original and candidate."), {code: 'JXL_INPUT'});
192
+ throw Object.assign(new Error("delivery: verify original/candidate"), {code: 'JXL_INPUT'});
193
193
  const bound = {...item, generation: captured.generation, deliveryRevision: captured.deliveryRevision};
194
194
  // A JPEG's exact archive is independent of its selected delivery goal. A missed Size limit must not discard it.
195
195
  let original;
196
196
  if (!widthsOnly && archiveOriginals && !deliveryOnly && made.original?.meetsTarget)
197
197
  original = await attach(`${ROUTE}/attach?${query(bound)}&source=${made.source}`, made.original, signal);
198
- if (original?.stored === 'pending' && !original.job?.id) throw new Error('Archive publication returned no saved job');
198
+ if (original?.stored === 'pending' && !original.job?.id) throw new Error('archive publication: missing job');
199
199
  let result = {stored: widthsOnly ? 'sidecar' : 'original', reason: made.result?.reason?.code};
200
200
  if (!widthsOnly && archiveOriginals && !deliveryOnly && made.archiveIsDelivery) {
201
- if (!original) throw new Error('The selected JPEG archive was not submitted.');
201
+ if (!original) throw new Error('JPEG archive: not submitted');
202
202
  result = original;
203
203
  } else if (!widthsOnly && made.result?.meetsTarget)
204
204
  result = await attach(`${ROUTE}/attach?${query(bound)}&source=${made.source}`, made.result, signal);
@@ -209,7 +209,7 @@ async function browserConvert(item, selected, signal, update, widthsOnly = false
209
209
  const submitted = [original, result, ...variants];
210
210
  const pending = submitted.find(reply => reply?.stored === 'pending' && reply.job?.id === stored.nativeJob?.id);
211
211
  if (pending) {
212
- if (!pending.job?.id) throw new Error('Publication returned no saved job');
212
+ if (!pending.job?.id) throw new Error('publication: missing job');
213
213
  // A successful upload can still be awaiting its durable verification and publication.
214
214
  update({...measured(item, stored, pending.job), progress: null});
215
215
  return stored;
@@ -307,7 +307,7 @@ function useImages({settings, loaded, ready, background, importBusy, blocked}) {
307
307
  }
308
308
  const nextCursor = page.nextCursor;
309
309
  if (!nextCursor) break;
310
- if (seenCursors.has(nextCursor) || nextCursor === cursor) throw new Error('Media pagination repeated a cursor');
310
+ if (seenCursors.has(nextCursor) || nextCursor === cursor) throw new Error('media page: repeated cursor');
311
311
  seenCursors.add(nextCursor); cursor = nextCursor;
312
312
  }
313
313
  check(control.signal);
@@ -481,7 +481,7 @@ function useImages({settings, loaded, ready, background, importBusy, blocked}) {
481
481
  records.current.set(row.id, admitted);
482
482
  enqueue({...current, ...measured(row, admitted)}, structuredClone(job.execution.settings), false, true, true);
483
483
  } else {
484
- if (!job.id) throw new Error('Server conversion returned no saved job.');
484
+ if (!job.id) throw new Error('server conversion: missing job');
485
485
  jobViews.current.set(job.id, job);
486
486
  queue.update(row.id, {nativeJob: {id: job.id}, job, activity: job.done ? null : 'server'});
487
487
  }