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
@@ -95,7 +95,7 @@ function makeSchemaNode(check, jsonSchema, meta = {}) {
95
95
  function createSchemaBuilder() {
96
96
  return {
97
97
  boolean: () => makeSchemaNode((v, path, issues) => {
98
- if (typeof v !== 'boolean') issues.push({path, message: 'Expected boolean.'});
98
+ if (typeof v !== 'boolean') issues.push({path, message: 'boolean'});
99
99
  return v;
100
100
  }, {type: 'boolean'}, {typeName: 'ZodBoolean'}),
101
101
  string() {
@@ -103,10 +103,10 @@ function createSchemaBuilder() {
103
103
  const schema = {type: 'string', ...(c.minLength !== undefined && {minLength: c.minLength}),
104
104
  ...(c.maxLength !== undefined && {maxLength: c.maxLength}), ...(c.pattern && {pattern: c.pattern.source})};
105
105
  const node = makeSchemaNode((v, path, issues) => {
106
- if (typeof v !== 'string') { issues.push({path, message: 'Expected string.'}); return v; }
107
- if (c.minLength !== undefined && v.length < c.minLength) issues.push({path, message: `Expected at least ${c.minLength} characters.`});
108
- if (c.maxLength !== undefined && v.length > c.maxLength) issues.push({path, message: `Expected at most ${c.maxLength} characters.`});
109
- if (c.pattern && !c.pattern.test(v)) issues.push({path, message: 'Invalid string format.'});
106
+ if (typeof v !== 'string') { issues.push({path, message: 'string'}); return v; }
107
+ if (c.minLength !== undefined && v.length < c.minLength) issues.push({path, message: `>= ${c.minLength} chars`});
108
+ if (c.maxLength !== undefined && v.length > c.maxLength) issues.push({path, message: `<= ${c.maxLength} chars`});
109
+ if (c.pattern && !c.pattern.test(v)) issues.push({path, message: 'string: pattern'});
110
110
  return v;
111
111
  }, schema, {typeName: 'ZodString'});
112
112
  return Object.assign(node, {
@@ -122,10 +122,10 @@ function createSchemaBuilder() {
122
122
  const schema = {type: c.int ? 'integer' : 'number',
123
123
  ...(c.min !== undefined && {minimum: c.min}), ...(c.max !== undefined && {maximum: c.max})};
124
124
  const node = makeSchemaNode((v, path, issues) => {
125
- if (typeof v !== 'number' || !Number.isFinite(v)) { issues.push({path, message: 'Expected number.'}); return v; }
126
- if (c.int && !Number.isSafeInteger(v)) issues.push({path, message: 'Expected integer.'});
127
- if (c.min !== undefined && v < c.min) issues.push({path, message: `Expected >= ${c.min}.`});
128
- if (c.max !== undefined && v > c.max) issues.push({path, message: `Expected <= ${c.max}.`});
125
+ if (typeof v !== 'number' || !Number.isFinite(v)) { issues.push({path, message: 'number'}); return v; }
126
+ if (c.int && !Number.isSafeInteger(v)) issues.push({path, message: 'integer'});
127
+ if (c.min !== undefined && v < c.min) issues.push({path, message: `>= ${c.min}`});
128
+ if (c.max !== undefined && v > c.max) issues.push({path, message: `<= ${c.max}`});
129
129
  return v;
130
130
  }, schema, {typeName: 'ZodNumber'});
131
131
  return Object.assign(node, {int: () => build({...c, int: true}), min: min => build({...c, min}), max: max => build({...c, max})});
@@ -135,7 +135,7 @@ function createSchemaBuilder() {
135
135
  enum(values) {
136
136
  const allowed = [...values];
137
137
  return makeSchemaNode((v, path, issues) => {
138
- if (!allowed.includes(v)) issues.push({path, message: `Expected one of: ${allowed.join(', ')}.`});
138
+ if (!allowed.includes(v)) issues.push({path, message: `one of: ${allowed.join(', ')}`});
139
139
  return v;
140
140
  }, {type: 'string', enum: allowed}, {typeName: 'ZodEnum', values: allowed});
141
141
  },
@@ -157,9 +157,9 @@ function createSchemaBuilder() {
157
157
  const build = (strict = true) => {
158
158
  const node = makeSchemaNode((v, path, issues) => {
159
159
  const input = v === undefined ? {} : v;
160
- if (!isRecord(input)) { issues.push({path, message: 'Expected JSON object.'}); return input; }
160
+ if (!isRecord(input)) { issues.push({path, message: 'JSON object'}); return input; }
161
161
  if (strict) {
162
- for (const key of Object.keys(input)) if (!Object.hasOwn(shape, key)) issues.push({path: [...path, key], message: `Unexpected field ${key}.`});
162
+ for (const key of Object.keys(input)) if (!Object.hasOwn(shape, key)) issues.push({path: [...path, key], message: `unknown field: ${key}`});
163
163
  }
164
164
  const out = {};
165
165
  for (const [key, field] of Object.entries(shape)) {
@@ -178,7 +178,7 @@ function createSchemaBuilder() {
178
178
 
179
179
  function storage() {
180
180
  const value = activeStorage();
181
- if (!value) throw fail(500, 'storage_not_wrapped', 'Add rapier-jxl through jxl(emdash, {...}) in astro.config');
181
+ if (!value) throw fail(500, 'storage_not_wrapped', 'astro.config: jxl(emdash, {...})');
182
182
  return value;
183
183
  }
184
184
  // At most every 30 s on Node: a wake task a restart left locked is replaced (background.mjs recoverWake).
@@ -190,7 +190,7 @@ async function checkWake(ctx, media, call) {
190
190
  }
191
191
  async function runner(ctx, options = {}) {
192
192
  const media = storage(), backend = activeStorageScope();
193
- if (!backend) throw fail(500, 'storage_scope', 'Native storage has no configured backend scope');
193
+ if (!backend) throw fail(500, 'storage_scope', 'storage: backend scope');
194
194
  const scope = await digest(new TextEncoder().encode(JSON.stringify([ID, backend])));
195
195
  const host = media.host ?? hostLimits(media.originals?.platform ?? 'node');
196
196
  // Node with no CPU allowance runs each image job in a worker thread (thread-driver.mjs); other hosts step it.
@@ -214,17 +214,17 @@ async function runner(ctx, options = {}) {
214
214
  const saved = await service.calls.call(() => ctx.kv.compareAndSet(pointer, previous.revision,
215
215
  {...previous.value, id: ids[0], ids}));
216
216
  if (saved?.applied === true) return job;
217
- if (saved?.applied !== false) throw fail(503, 'JXL_IO', "Candidate job pointer is unconfirmed; check its state before retrying.");
217
+ if (saved?.applied !== false) throw fail(503, 'JXL_IO', "candidate pointer: unconfirmed; check state");
218
218
  previous = await service.calls.call(() => ctx.kv.getVersioned(pointer)) ?? {value: null, revision: null};
219
219
  }
220
- throw fail(409, 'JXL_BUSY', "Candidate job pointer changed too often; retry this request.");
220
+ throw fail(409, 'JXL_BUSY', "candidate pointer: changed; retry");
221
221
  }
222
222
  // A revision owns its pointer. Compare against the value seen before queueing so a delayed old library run
223
223
  // cannot replace a newer run's pointer; terminal replays also leave it alone.
224
224
  if (!job.done && !job.canceled && previous.value?.id !== job.id) {
225
225
  const saved = await service.calls.call(() => ctx.kv.compareAndSet(pointer, previous.revision,
226
226
  {id: job.id, ...(job.execution && {execution: job.execution})}));
227
- if (saved?.applied !== true && saved?.applied !== false) throw fail(503, 'JXL_IO', "Image job pointer is unconfirmed; check its state before retrying.");
227
+ if (saved?.applied !== true && saved?.applied !== false) throw fail(503, 'JXL_IO', "job pointer: unconfirmed; check state");
228
228
  }
229
229
  return job;
230
230
  };
@@ -233,7 +233,7 @@ async function runner(ctx, options = {}) {
233
233
 
234
234
  async function execution(service, ctx, id, selected) {
235
235
  const item = await service.calls.call(() => ctx.media.get(id));
236
- if (!item) throw fail(404, 'NOT_FOUND', 'The picture is missing');
236
+ if (!item) throw fail(404, 'NOT_FOUND', 'picture: missing');
237
237
  const archiveOriginals = (await archivePolicy(service, ctx)).admitting;
238
238
  return {...executionFor(service.host, selected, item, {archiveOriginals}), archiveOriginals};
239
239
  }
@@ -251,7 +251,7 @@ async function browserAdmission(service, ctx, {id, key, selected, expectedGenera
251
251
  const media = storage(), signal = ctx.request?.signal, call = action => service.calls.call(action);
252
252
  const state = await media.deliveryState(key, {signal, call});
253
253
  if (!state || expectedGeneration !== undefined && (state.generation !== expectedGeneration || state.revision !== expectedDeliveryRevision))
254
- throw fail(409, 'key_changed', 'The picture or delivery setting changed');
254
+ throw fail(409, 'key_changed', 'picture/delivery: changed');
255
255
  if (state.mode !== 'copies' || automatic && state.revision !== INITIAL_DELIVERY) return {skipped: true};
256
256
  const pointer = await mediaJobKey(service.scope, key, {generation: state.generation, deliveryRevision: state.revision});
257
257
  const previous = await call(() => ctx.kv.getVersioned(pointer)) ?? {value: null, revision: null};
@@ -262,7 +262,7 @@ async function browserAdmission(service, ctx, {id, key, selected, expectedGenera
262
262
  }
263
263
  const saved = await call(() => ctx.kv.compareAndSet(pointer, previous.revision,
264
264
  {...previous.value, ...(prior && {id: prior.id}), execution: choice}));
265
- if (saved?.applied !== true && saved?.applied !== false) throw fail(503, 'JXL_IO', "Browser work selection is unconfirmed; check its state before retrying.");
265
+ if (saved?.applied !== true && saved?.applied !== false) throw fail(503, 'JXL_IO', "browser work: unconfirmed; check state");
266
266
  // A racing native admission owns the pointer. Refresh it instead of claiming that no server work remains.
267
267
  if (saved.applied === false) {
268
268
  const current = await call(() => ctx.kv.get(pointer));
@@ -283,23 +283,23 @@ function jobRoute(request, permission, action, factory = runner) {
283
283
  function target(ctx) {
284
284
  const query = new URL(ctx.request.url).searchParams, id = query.get('id'), key = query.get('key');
285
285
  if (!/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(id ?? '') || !UPLOAD_KEY.test(key ?? ''))
286
- throw fail(400, 'media_id', 'Expected a media id and key');
286
+ throw fail(400, 'media_id', 'media: id and key');
287
287
  const replace = query.get('replace');
288
- if (replace !== null && replace !== 'true' && replace !== 'false') throw fail(400, 'JXL_OPTIONS', "Invalid replace value; pass true or false.");
288
+ if (replace !== null && replace !== 'true' && replace !== 'false') throw fail(400, 'JXL_OPTIONS', "replace: boolean");
289
289
  const expectedDeliveryRevision = query.get('deliveryRevision') ?? undefined;
290
290
  if (expectedDeliveryRevision !== undefined && !HEX32.test(expectedDeliveryRevision))
291
- throw fail(400, 'JXL_OPTIONS', "Invalid delivery revision; pass its saved revision.");
291
+ throw fail(400, 'JXL_OPTIONS', "deliveryRevision: saved revision");
292
292
  return {id, key, source: query.get('source'), expectedGeneration: query.get('generation') ?? undefined,
293
293
  expectedDeliveryRevision, replace: replace === 'true'};
294
294
  }
295
295
 
296
296
  export function inputResult(ctx) {
297
297
  const text = ctx.request.headers.get('x-rapier-result');
298
- if (!text || text.length > 8192) throw fail(400, 'JXL_INPUT', "Missing or large result record; send at most 8192 characters in x-rapier-result.");
298
+ if (!text || text.length > 8192) throw fail(400, 'JXL_INPUT', "x-rapier-result: <=8192 chars");
299
299
  let metadata;
300
- try { metadata = JSON.parse(text); } catch { throw fail(400, 'JXL_INPUT', "Invalid result JSON; send valid JSON in x-rapier-result."); }
300
+ try { metadata = JSON.parse(text); } catch { throw fail(400, 'JXL_INPUT', "x-rapier-result: invalid JSON"); }
301
301
  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata) || 'bytes' in metadata)
302
- throw fail(400, 'JXL_INPUT', "Invalid result metadata; send metadata as an object and bytes as the body.");
302
+ throw fail(400, 'JXL_INPUT', "metadata: object; bytes: body");
303
303
  return {...metadata, bytes: ctx.input};
304
304
  }
305
305
 
@@ -312,7 +312,7 @@ function floorOf(site) {
312
312
  function selectedResult(ctx, site) {
313
313
  const result = inputResult(ctx);
314
314
  if (site.maxKilobytes && result.bytes?.byteLength > site.maxKilobytes * 1024)
315
- throw fail(422, 'JXL_TARGET', "Copy exceeds its size target; regenerate it for that target.");
315
+ throw fail(422, 'JXL_TARGET', "copy: exceeds size target");
316
316
  return result;
317
317
  }
318
318
 
@@ -342,17 +342,17 @@ function binding(item, id, key) {
342
342
  if (!item || item.id !== id || item.status !== 'ready' || item.storageKey !== key ||
343
343
  !['image/jpeg', 'image/png'].includes(item.mimeType) ||
344
344
  (isJpegKey(key) ? item.mimeType !== 'image/jpeg' : !/\.png$/i.test(key) || item.mimeType !== 'image/png'))
345
- throw fail(409, 'key_changed', 'The picture is not the stored media item');
345
+ throw fail(409, 'key_changed', 'picture: stored media item mismatch');
346
346
  // EmDash's computeContentHash uses sha1:<40 lowercase hex> for deduplication. It is a captured database identity
347
347
  // fence, not the request's SHA-256 and not a cryptographic fidelity proof.
348
348
  if (item.contentHash != null && !/^sha1:[a-f0-9]{40}$/.test(item.contentHash))
349
- throw fail(409, 'key_changed', 'The stored media identity is not supported');
349
+ throw fail(409, 'key_changed', 'media identity: unsupported');
350
350
  return JSON.stringify([item.id, item.storageKey, item.status, item.mimeType, item.size, item.contentHash ?? null]);
351
351
  }
352
352
  async function structuralCandidate(ctx, service, target, site, pointerKey, mediaItem, width) {
353
353
  const {id, key, source, expectedGeneration, expectedDeliveryRevision, replace} = target;
354
354
  if (!/^[a-f0-9]{64}$/.test(expectedGeneration ?? '') || !HEX32.test(expectedDeliveryRevision ?? ''))
355
- throw fail(400, 'JXL_INPUT', "Invalid source identity; pass the captured generation and delivery revision.");
355
+ throw fail(400, 'JXL_INPUT', "source identity: generation and deliveryRevision");
356
356
  const media = storage(), signal = ctx.request.signal, call = action => service.calls.call(action);
357
357
  const item = await call(() => mediaItem(id)), identity = binding(item, id, key);
358
358
  const result = selectedResult(ctx, site), selectedSettings = JSON.stringify(site);
@@ -379,7 +379,7 @@ async function structuralCandidate(ctx, service, target, site, pointerKey, media
379
379
 
380
380
  async function pendingCandidate(ctx, width, mediaItem = nativeMediaItem) {
381
381
  if (width !== undefined && (!Number.isSafeInteger(width) || width < 16 || width > 8192))
382
- throw fail(422, 'JXL_DIMENSIONS', 'The responsive width must be from 16 to 8192.');
382
+ throw fail(422, 'JXL_DIMENSIONS', 'responsive width: 16-8192');
383
383
  const {id, key, source, expectedGeneration, expectedDeliveryRevision, replace} = target(ctx);
384
384
  const service = await runner(ctx), media = storage(), signal = ctx.request.signal;
385
385
  const call = action => service.calls.call(action);
@@ -393,17 +393,17 @@ async function pendingCandidate(ctx, width, mediaItem = nativeMediaItem) {
393
393
  const archive = original && (await archivePolicy(service, ctx)).admitting;
394
394
  const result = original ? submitted : selectedResult(ctx, site), exact = result.fidelity === 'exact' || result.fidelity?.maxError === 0;
395
395
  if (width !== undefined && (!Number.isSafeInteger(width) || width < 16 || result.width !== width))
396
- throw fail(422, 'JXL_DIMENSIONS', "Copy has the wrong width; regenerate it at the requested width.");
396
+ throw fail(422, 'JXL_DIMENSIONS', "copy: requested width");
397
397
  if (result.meetsTarget !== true || !['jpeg-bytes', 'pixels', 'lossy'].includes(result.kept) ||
398
398
  !Number.isSafeInteger(result.width) || !Number.isSafeInteger(result.height) || result.width < 1 || result.height < 1 ||
399
399
  !Number.isSafeInteger(result.width * result.height) ||
400
400
  media.maxPixels !== undefined && result.width * result.height > media.maxPixels || archive && !exact)
401
- throw fail(422, 'JXL_INPUT', "Invalid selected result; regenerate it with the current settings.");
401
+ throw fail(422, 'JXL_INPUT', "selected result: current settings");
402
402
  const floor = archive ? 'exact' : floorOf(site);
403
403
  if (!exact && (floor === 'exact' || !Number.isFinite(result.fidelity?.quality) || result.fidelity.quality > 100 ||
404
404
  result.fidelity.quality < floor.quality))
405
- throw fail(422, 'JXL_TARGET', "Copy misses its fidelity target; regenerate it for that target.");
406
- if (await bound(ctx, id, call) !== source) throw fail(409, 'key_changed', 'The picture changed');
405
+ throw fail(422, 'JXL_TARGET', "copy: fidelity target missed");
406
+ if (await bound(ctx, id, call) !== source) throw fail(409, 'key_changed', 'picture: changed');
407
407
  const snapshot = media.maxPixels === undefined ? await media.sourceSnapshot(key, {signal, call}) : null;
408
408
  const before = media.maxPixels === undefined ? snapshot && {...snapshot.source, size: snapshot.source.byteLength}
409
409
  : await media.sourceHead(key, {signal, call});
@@ -412,7 +412,7 @@ async function pendingCandidate(ctx, width, mediaItem = nativeMediaItem) {
412
412
  if (!before || before.generation !== expectedGeneration || before.sha256 !== undefined && before.sha256 !== source ||
413
413
  !selected || selected.generation !== expectedGeneration ||
414
414
  selected.revision !== expectedDeliveryRevision || selected.mode !== 'copies')
415
- throw fail(409, 'key_changed', 'The picture or delivery setting changed');
415
+ throw fail(409, 'key_changed', 'picture/delivery: changed');
416
416
  if (original && !archive && site.maxKilobytes > 0 && result.bytes.byteLength > site.maxKilobytes * 1024)
417
417
  return {key, stored: null, reason: 'JXL_TARGET'};
418
418
  if (!archive && width === undefined && result.bytes.byteLength >= before.size)
@@ -480,10 +480,10 @@ async function admit(service, ctx, {id, key, jobId, operation, options, maxBytes
480
480
  const snapshot = await storage().sourceSnapshot(key, {signal, call});
481
481
  // An explicit conversion or restore owns its fresh revision even if the upload hook was delayed.
482
482
  if (automatic && snapshot && (snapshot.delivery.mode !== 'copies' || snapshot.delivery.revision !== INITIAL_DELIVERY)) return null;
483
- if (!snapshot || snapshot.source.sha256 !== await bound(ctx, id, call)) throw fail(409, 'key_changed', 'The picture changed');
483
+ if (!snapshot || snapshot.source.sha256 !== await bound(ctx, id, call)) throw fail(409, 'key_changed', 'picture: changed');
484
484
  if (expectedGeneration !== undefined && (snapshot.source.generation !== expectedGeneration ||
485
485
  snapshot.source.deliveryRevision !== expectedDeliveryRevision || snapshot.delivery.mode !== 'copies'))
486
- throw fail(409, 'key_changed', 'The picture or delivery setting changed');
486
+ throw fail(409, 'key_changed', 'picture/delivery: changed');
487
487
  if (automatic) {
488
488
  const pointer = await mediaJobKey(service.scope, key, snapshot.source);
489
489
  const previous = await call(() => ctx.kv.get(pointer));
@@ -517,7 +517,7 @@ async function library(ctx, options = {}) {
517
517
  throw error;
518
518
  }
519
519
  if (!snapshot || snapshot.source.sha256 !== seen)
520
- throw fail(409, 'key_changed', 'The picture changed');
520
+ throw fail(409, 'key_changed', 'picture: changed');
521
521
  if (snapshot.delivery?.mode === 'original') return {skip: 'original', originalBytes: snapshot.source.byteLength};
522
522
  return {key: item.key, ...nativeOptions(selected, item.key, (await archivePolicy(service, ctx)).admitting),
523
523
  input: {...snapshot.source, kind: 'file'}};
@@ -531,7 +531,7 @@ async function library(ctx, options = {}) {
531
531
 
532
532
  async function originalsService(ctx, options = {}, {mediaItem = nativeMediaItem, mediaPage = nativeMediaPage} = {}) {
533
533
  const service = await runner(ctx, options), media = storage(), originals = media.originals;
534
- if (!originals) throw fail(422, 'JXL_UNSUPPORTED', "Original storage is unavailable; configure the native conditional adapter.");
534
+ if (!originals) throw fail(422, 'JXL_UNSUPPORTED', "original storage: native conditional adapter");
535
535
  const signal = ctx.request?.signal, call = action => service.calls.call(action);
536
536
  const read = () => originals.policy({signal, call});
537
537
  const status = async () => {
@@ -544,7 +544,7 @@ async function originalsService(ctx, options = {}, {mediaItem = nativeMediaItem,
544
544
  list: async cursor => {
545
545
  const page = await call(() => mediaPage(cursor));
546
546
  if (!page || !Array.isArray(page.items) || page.items.length > 1)
547
- throw fail(503, 'JXL_IO', "Invalid JPEG page; return at most one stored media item.");
547
+ throw fail(503, 'JXL_IO', "JPEG page: <=1 item");
548
548
  return {items: page.items.map(item => ({id: item.id, key: item.storageKey,
549
549
  identity: binding(item, item.id, item.storageKey)})), ...(page.nextCursor && {nextCursor: page.nextCursor})};
550
550
  },
@@ -570,10 +570,10 @@ async function originalsService(ctx, options = {}, {mediaItem = nativeMediaItem,
570
570
  async save(input) {
571
571
  if (!input || typeof input.enabled !== 'boolean' || !HEX32.test(input.id ?? '') ||
572
572
  Object.keys(input).some(key => !['enabled', 'id'].includes(key)))
573
- throw fail(400, 'JXL_OPTIONS', 'Choose the originals policy using its current saved identity.');
573
+ throw fail(400, 'JXL_OPTIONS', 'originals policy: current identity');
574
574
  const current = await read();
575
- if (current.id !== input.id) throw fail(409, 'JXL_POLICY_CHANGED', "Originals setting changed; read its current progress.");
576
- if (input.enabled && !current.available) throw fail(422, 'JXL_UNSUPPORTED', 'This host must keep the original JPEG files.');
575
+ if (current.id !== input.id) throw fail(409, 'JXL_POLICY_CHANGED', "originals policy: refresh progress");
576
+ if (input.enabled && !current.available) throw fail(422, 'JXL_UNSUPPORTED', 'host: retain original JPEGs');
577
577
  if (current.desired === input.enabled && current.phase === 'idle') return current;
578
578
  const id = current.desired === input.enabled ? current.id : crypto.randomUUID().replaceAll('-', '');
579
579
  // The immutable scheduled intent comes first. A crash after the control CAS can never strand
@@ -597,11 +597,11 @@ function createMcpSurface({originalPolicy, mediaList, z: overrideZ}) {
597
597
  const nullableOf = inner => typeof inner.nullable === 'function' ? inner.nullable() : z.nullable(inner);
598
598
  const parseInput = (schema, raw) => {
599
599
  const value = raw ?? {};
600
- if (!isRecord(value)) throw fail(400, 'JXL_INPUT', 'Invalid MCP tool input; send a JSON object matching the tool schema.');
600
+ if (!isRecord(value)) throw fail(400, 'JXL_INPUT', 'tool input: JSON object');
601
601
  const parsed = schema.safeParse(value);
602
602
  if (!parsed.success) {
603
603
  const first = parsed.error?.issues?.[0], field = first?.path?.length ? ` (${first.path.join('.')})` : '';
604
- throw fail(400, 'JXL_INPUT', `Invalid MCP tool input${field}; pass values matching the tool schema.`);
604
+ throw fail(400, 'JXL_INPUT', `tool input${field}: invalid schema`);
605
605
  }
606
606
  return parsed.data;
607
607
  };
@@ -683,7 +683,7 @@ function createMcpSurface({originalPolicy, mediaList, z: overrideZ}) {
683
683
  return {started: true, active: true, queued: selected.length, run: startedRun};
684
684
  }
685
685
  const targetId = input.runId ?? current?.id;
686
- if (!targetId) throw fail(409, 'JXL_INPUT', 'No active library conversion run; start one with action "start" or pass a saved runId.');
686
+ if (!targetId) throw fail(409, 'JXL_INPUT', 'library run: action start or runId');
687
687
  if (action === 'advance') {
688
688
  let next = await lib.advance(targetId), activeJob = null;
689
689
  if (next?.current?.jobId && next.current.stage === 'waiting') {
@@ -752,7 +752,7 @@ function createMcpSurface({originalPolicy, mediaList, z: overrideZ}) {
752
752
  // Replacing physical originals is the destructive direction: it needs the caller's explicit consent and the policy it
753
753
  // read, never the live policy filled in for it (a revision guards stale intent, not consent).
754
754
  if (input.keepOriginals === false && (input.confirm !== true || !input.policyId))
755
- throw fail(400, 'JXL_OPTIONS', "Unconfirmed change; to stop keeping original JPEG files pass confirm: true and the policyId from a read.");
755
+ throw fail(400, 'JXL_OPTIONS', "confirm: true; policyId: current");
756
756
  return originalsView(await orig.save({enabled: !input.keepOriginals, id: input.policyId ?? current.id}));
757
757
  }),
758
758
  };
@@ -792,13 +792,13 @@ function createMcpSurface({originalPolicy, mediaList, z: overrideZ}) {
792
792
  function preferenceRoute(mediaItem = nativeMediaItem) {
793
793
  return {methods: ['POST'], request: {body: 'json', maxBytes: 4096}, permission: 'media:upload', handler: async ctx => {
794
794
  const {id, key, generation, deliveryRevision, mode, inheritSettings = false} = ctx.input ?? {};
795
- const invalid = () => fail(400, 'JXL_INPUT', "Invalid delivery request; pass the picture and its saved delivery revision.");
795
+ const invalid = () => fail(400, 'JXL_INPUT', "delivery request: picture and deliveryRevision");
796
796
  if (typeof id !== 'string' || !/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(id) || typeof key !== 'string' || !UPLOAD_KEY.test(key) ||
797
797
  !['original', 'copies'].includes(mode) || typeof inheritSettings !== 'boolean') throw invalid();
798
798
  // A GIF, an SVG or any other type has no copy to choose: refuse it by name, never as a storage fault, before the
799
799
  // delivery identities only a converted type has.
800
800
  if (!serverImage(key) && !/\.(?:webp|avif)$/i.test(key))
801
- throw fail(422, 'JXL_UNSUPPORTED', "This picture type is not converted; only JPEG, PNG, WebP and AVIF are. Its original stays as it is.");
801
+ throw fail(422, 'JXL_UNSUPPORTED', "unsupported picture type: use JPEG, PNG, WebP or AVIF");
802
802
  if (typeof generation !== 'string' || !/^[a-f0-9]{64}$/.test(generation) ||
803
803
  typeof deliveryRevision !== 'string' || !HEX32.test(deliveryRevision)) throw invalid();
804
804
  const media = storage();
@@ -808,17 +808,17 @@ function preferenceRoute(mediaItem = nativeMediaItem) {
808
808
  const before = await media.physicalSourceHead(key, {signal: ctx.request.signal});
809
809
  const state = before ? await media.deliveryState(key, {signal: ctx.request.signal, generation: before.generation}) : null;
810
810
  if (!before || before.generation !== generation || !state || state.generation !== generation || state.revision !== deliveryRevision)
811
- throw fail(409, 'key_changed', 'The picture or delivery setting changed');
811
+ throw fail(409, 'key_changed', 'picture/delivery: changed');
812
812
  } else {
813
813
  const snapshot = await media.sourceSnapshot(key, {signal: ctx.request.signal});
814
814
  if (!snapshot || snapshot.source.generation !== generation || snapshot.source.deliveryRevision !== deliveryRevision ||
815
- snapshot.source.sha256 !== await bound(ctx, id)) throw fail(409, 'key_changed', 'The picture changed');
815
+ snapshot.source.sha256 !== await bound(ctx, id)) throw fail(409, 'key_changed', 'picture: changed');
816
816
  }
817
817
  try {
818
818
  const state = await media[mode === 'original' ? 'restoreOriginal' : 'resumeCopies'](key,
819
819
  {expectedGeneration: generation, expectedRevision: deliveryRevision, signal: ctx.request.signal});
820
820
  if (capturedIdentity !== undefined && binding(await mediaItem(id), id, key) !== capturedIdentity)
821
- throw fail(409, 'key_changed', 'The picture changed');
821
+ throw fail(409, 'key_changed', 'picture: changed');
822
822
  let captured;
823
823
  if (mode === 'copies') {
824
824
  const service = await runner(ctx), call = action => service.calls.call(action);
@@ -830,7 +830,7 @@ function preferenceRoute(mediaItem = nativeMediaItem) {
830
830
  const saved = await call(() => ctx.kv.compareAndSet(pointer, null, {execution: captured}));
831
831
  if (saved?.applied === false) captured = {...((await call(() => ctx.kv.get(pointer)))?.execution ?? captured),
832
832
  archiveOriginals: (await archivePolicy(service, ctx)).admitting};
833
- else if (saved?.applied !== true) throw fail(503, 'JXL_IO', "Conversion settings are unconfirmed; check their state before retrying.");
833
+ else if (saved?.applied !== true) throw fail(503, 'JXL_IO', "conversion settings: unconfirmed; check state");
834
834
  }
835
835
  return {generation: state.generation, mode: state.mode, deliveryRevision: state.revision,
836
836
  ...(captured && {execution: captured})};
@@ -896,7 +896,7 @@ async function scheduled(event, ctx, repositories) {
896
896
 
897
897
  export function createPlugin({mediaItem = nativeMediaItem, mediaPage = nativeMediaPage, mediaList = nativeMediaList, z} = {}) {
898
898
  if ([mediaItem, mediaPage, mediaList].some(value => typeof value !== 'function'))
899
- throw new TypeError('Native media identity uses server repository readers.');
899
+ throw new TypeError('media identity: server repository readers');
900
900
  const originalPolicy = (ctx, options) => originalsService(ctx, options, {mediaItem, mediaPage});
901
901
  const mcpSurface = createMcpSurface({originalPolicy, mediaList, z});
902
902
  return definePlugin({id: ID, version: VERSION, capabilities: ['media:read', 'media:bytes:read'], admin: ADMIN,
@@ -913,7 +913,7 @@ export function createPlugin({mediaItem = nativeMediaItem, mediaPage = nativeMed
913
913
  (run, ctx) => run.save(ctx.input), originalPolicy),
914
914
  'originals-advance': jobRoute({body: 'json', maxBytes: 256}, 'media:upload', async (run, ctx) => {
915
915
  const value = await run.resume(ctx.input?.id);
916
- if (!value) throw fail(409, 'JXL_POLICY_CHANGED', "Originals setting changed; read its current progress.");
916
+ if (!value) throw fail(409, 'JXL_POLICY_CHANGED', "originals policy: refresh progress");
917
917
  return value;
918
918
  }, originalPolicy),
919
919
  'removal-start': jobRoute({body: 'json', maxBytes: 1024}, 'plugins:manage',
@@ -932,7 +932,7 @@ export function createPlugin({mediaItem = nativeMediaItem, mediaPage = nativeMed
932
932
  // Ruling 91: the optimizer asks for an unchecked copy's color check (a library row's color: 'unchecked').
933
933
  'color-check': jobRoute({body: 'json', maxBytes: 1024}, 'media:upload', (service, ctx) => {
934
934
  const {key} = ctx.input ?? {};
935
- if (typeof key !== 'string' || !UPLOAD_KEY.test(key) || !hasSidecar(key)) throw fail(400, 'JXL_INPUT', "Invalid picture key; pass the stored picture key.");
935
+ if (typeof key !== 'string' || !UPLOAD_KEY.test(key) || !hasSidecar(key)) throw fail(400, 'JXL_INPUT', "picture key: stored key");
936
936
  return storage().checkColor(key, {signal: ctx.request.signal, call: action => service.calls.call(action)});
937
937
  }),
938
938
  'media-convert': jobRoute({body: 'json', maxBytes: 1024}, 'media:upload', async (service, ctx) => {
@@ -940,7 +940,7 @@ export function createPlugin({mediaItem = nativeMediaItem, mediaPage = nativeMed
940
940
  if (typeof id !== 'string' || !/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(id) || typeof key !== 'string' ||
941
941
  !UPLOAD_KEY.test(key) || !serverImage(key) || typeof generation !== 'string' || !/^[a-f0-9]{64}$/.test(generation) ||
942
942
  typeof deliveryRevision !== 'string' || !HEX32.test(deliveryRevision))
943
- throw fail(400, 'JXL_INPUT', "Invalid source selection; choose a stored JPEG or PNG with its saved delivery revision.");
943
+ throw fail(400, 'JXL_INPUT', "source: stored JPEG/PNG and deliveryRevision");
944
944
  const pointer = await mediaJobKey(service.scope, key, {generation, deliveryRevision});
945
945
  const captured = await service.calls.call(() => ctx.kv.get(pointer));
946
946
  const site = settings(captured?.execution?.settings ?? await service.calls.call(() => ctx.kv.get('settings')));
@@ -952,14 +952,14 @@ export function createPlugin({mediaItem = nativeMediaItem, mediaPage = nativeMed
952
952
  if (typeof id !== 'string' || !/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(id) || typeof key !== 'string' || !UPLOAD_KEY.test(key) ||
953
953
  typeof jobId !== 'string' || !HEX32.test(jobId) || !['encode', 'fit', 'recompress'].includes(operation) ||
954
954
  options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options)))
955
- throw fail(400, 'JXL_INPUT', "Invalid job request; pass its media ID, storage key, and image job ID.");
955
+ throw fail(400, 'JXL_INPUT', "job request: media ID, key, job ID");
956
956
  const site = settings(await service.calls.call(() => ctx.kv.get('settings')));
957
957
  const item = await service.calls.call(() => ctx.media.get(id));
958
- if (!item) throw fail(404, 'NOT_FOUND', 'The picture is missing');
958
+ if (!item) throw fail(404, 'NOT_FOUND', 'picture: missing');
959
959
  const policy = executionFor(service.host, {...site, effort: options?.effort ?? site.effort}, item,
960
960
  {work: {operation, options: {...options, effort: options?.effort ?? site.effort}}});
961
961
  if (policy.location === 'browser')
962
- throw fail(422, 'JXL_UNSUPPORTED', 'This host requires the selected browser conversion route for this picture.');
962
+ throw fail(422, 'JXL_UNSUPPORTED', 'picture: browser conversion route');
963
963
  return admit(service, ctx, {id, key, jobId, operation, options});
964
964
  }),
965
965
  'job-status': jobRoute({body: 'none'}, 'media:read', (service, ctx) =>
@@ -978,7 +978,7 @@ export function createPlugin({mediaItem = nativeMediaItem, mediaPage = nativeMed
978
978
  !item || typeof item !== 'object' || Array.isArray(item) ||
979
979
  typeof item.id !== 'string' || !/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(item.id) ||
980
980
  item.key != null && typeof item.key !== 'string'))
981
- throw fail(400, 'library_page', 'Send at most 8 media item records');
981
+ throw fail(400, 'library_page', 'media items: <=8');
982
982
  const rows = [], service = await runner(ctx), selected = settings(await service.calls.call(() => ctx.kv.get('settings')));
983
983
  for (const item of items) {
984
984
  const row = await libraryRow(storage(), item);