@prenta/core 0.118.0

package/dist/media/merge-document-media.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Deep-merge helpers for `type: 'media'` fields on document update.
+ *
+ * Top-level document data is shallow-merged, so a partial media object like
+ * `{ featuredImage: { alt: '…' } }` would otherwise replace the whole value
+ * and drop `url` / `id` (#716). These helpers merge object patches onto the
+ * existing media value and reject incomplete media objects that still lack
+ * both `id` and a resolvable URL after merge.
+ */
+import type { FieldDefinition } from '../config/types.js';
+/**
+ * Merge a media-typed patch onto an existing value. Plain objects shallow-merge;
+ * bare IDs / null / non-objects replace.
+ */
+export declare function mergeMediaFieldValue(existing: unknown, patch: unknown): unknown;
+/**
+ * For every field present in `patch`, deep-merge media-shaped values onto
+ * `existing` and return a new top-level data object.
+ */
+export declare function mergeDocumentMediaFields(fields: Record<string, FieldDefinition>, existing: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+/** Throw a clear validation error when a media object lacks id and url. */
+export declare function assertMediaFieldsHaveIdentity(fields: Record<string, FieldDefinition>, data: Record<string, unknown>): void;
+//# sourceMappingURL=merge-document-media.d.ts.map

package/dist/media/merge-document-media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-document-media.d.ts","sourceRoot":"","sources":["../../src/media/merge-document-media.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AA2BzD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/E;AAqCD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAsDD,2EAA2E;AAC3E,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI,CAIN"}

package/dist/media/merge-document-media.js

@@ -0,0 +1,146 @@
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isResolvableUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    const trimmed = value.trim();
+    return (trimmed.startsWith('http://') ||
+        trimmed.startsWith('https://') ||
+        (trimmed.startsWith('/') && !trimmed.startsWith('//')));
+}
+function mediaObjectHasIdentity(value) {
+    const id = typeof value.id === 'string' ? value.id.trim() : '';
+    if (id.length > 0)
+        return true;
+    return (isResolvableUrl(value.url) ||
+        isResolvableUrl(value.publicUrl) ||
+        isResolvableUrl(value.src) ||
+        isResolvableUrl(value.imageUrl));
+}
+/**
+ * Merge a media-typed patch onto an existing value. Plain objects shallow-merge;
+ * bare IDs / null / non-objects replace.
+ */
+export function mergeMediaFieldValue(existing, patch) {
+    if (isPlainObject(existing) && isPlainObject(patch)) {
+        return { ...existing, ...patch };
+    }
+    return patch;
+}
+function mergeFieldValue(def, existing, patch) {
+    switch (def.type) {
+        case 'media':
+            return mergeMediaFieldValue(existing, patch);
+        case 'array': {
+            if (!Array.isArray(patch))
+                return patch;
+            if (!Array.isArray(existing))
+                return patch;
+            return patch.map((row, index) => {
+                const prev = existing[index];
+                if (!isPlainObject(row) || !isPlainObject(prev) || !def.fields)
+                    return row;
+                return mergeDocumentMediaFields(def.fields, prev, row);
+            });
+        }
+        case 'blocks': {
+            if (!Array.isArray(patch))
+                return patch;
+            if (!Array.isArray(existing))
+                return patch;
+            return patch.map((block, index) => {
+                if (!isPlainObject(block))
+                    return block;
+                const prev = existing[index];
+                const slug = typeof block.blockType === 'string'
+                    ? block.blockType
+                    : typeof block.type === 'string'
+                        ? block.type
+                        : null;
+                const blockDef = slug ? def.blocks.find((x) => x.slug === slug) : undefined;
+                if (!blockDef || !isPlainObject(prev))
+                    return block;
+                return mergeDocumentMediaFields(blockDef.fields, prev, block);
+            });
+        }
+        default:
+            return patch;
+    }
+}
+/**
+ * For every field present in `patch`, deep-merge media-shaped values onto
+ * `existing` and return a new top-level data object.
+ */
+export function mergeDocumentMediaFields(fields, existing, patch) {
+    const merged = { ...existing, ...patch };
+    for (const [key, def] of Object.entries(fields)) {
+        if (!Object.prototype.hasOwnProperty.call(patch, key))
+            continue;
+        merged[key] = mergeFieldValue(def, existing[key], patch[key]);
+    }
+    return merged;
+}
+function assertMediaValue(fieldPath, value) {
+    if (value == null)
+        return;
+    if (typeof value === 'string')
+        return;
+    if (!isPlainObject(value))
+        return;
+    if (mediaObjectHasIdentity(value))
+        return;
+    throw new Error(`Invalid media field "${fieldPath}": object is missing both id and url. ` +
+        'Media fields replace nested keys unless deep-merged — resend the full ' +
+        '{ id, url, alt, … } object, or send only the media id string.');
+}
+function assertField(def, value, path) {
+    switch (def.type) {
+        case 'media':
+            assertMediaValue(path, value);
+            return;
+        case 'array': {
+            if (!Array.isArray(value) || !def.fields)
+                return;
+            for (let i = 0; i < value.length; i++) {
+                const row = value[i];
+                if (!isPlainObject(row))
+                    continue;
+                for (const [key, child] of Object.entries(def.fields)) {
+                    assertField(child, row[key], `${path}[${i}].${key}`);
+                }
+            }
+            return;
+        }
+        case 'blocks': {
+            if (!Array.isArray(value))
+                return;
+            for (let i = 0; i < value.length; i++) {
+                const block = value[i];
+                if (!isPlainObject(block))
+                    continue;
+                const slug = typeof block.blockType === 'string'
+                    ? block.blockType
+                    : typeof block.type === 'string'
+                        ? block.type
+                        : null;
+                const blockDef = slug ? def.blocks.find((x) => x.slug === slug) : undefined;
+                if (!blockDef)
+                    continue;
+                for (const [key, child] of Object.entries(blockDef.fields)) {
+                    assertField(child, block[key], `${path}[${i}].${key}`);
+                }
+            }
+            return;
+        }
+        default:
+            return;
+    }
+}
+/** Throw a clear validation error when a media object lacks id and url. */
+export function assertMediaFieldsHaveIdentity(fields, data) {
+    for (const [key, def] of Object.entries(fields)) {
+        assertField(def, data[key], key);
+    }
+}
+//# sourceMappingURL=merge-document-media.js.map

package/dist/media/merge-document-media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-document-media.js","sourceRoot":"","sources":["../../src/media/merge-document-media.ts"],"names":[],"mappings":"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"}

package/dist/media/metadata-patch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared body → Prisma update mapping for media metadata writes.
+ * Used by `PUT /media/:id` and `POST /media/bulk-update` so decorative-alt
+ * rules stay in one place (#714 / #717).
+ */
+export declare const BULK_MEDIA_MAX_ITEMS = 50;
+export interface MediaMetadataPatch {
+    alt?: string;
+    title?: string;
+    filename?: string;
+    caption?: string;
+    description?: string;
+    focusKeyword?: string;
+    focalX?: number;
+    focalY?: number;
+    isDecorative?: boolean;
+}
+/** Map a partial media metadata patch to Prisma `media.update` data. */
+export declare function buildMediaMetadataUpdateData(body: MediaMetadataPatch): Record<string, unknown>;
+export declare function isEmptyMediaMetadataPatch(body: MediaMetadataPatch): boolean;
+//# sourceMappingURL=metadata-patch.d.ts.map

package/dist/media/metadata-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-patch.d.ts","sourceRoot":"","sources":["../../src/media/metadata-patch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,wEAAwE;AACxE,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2B9F;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAE3E"}

package/dist/media/metadata-patch.js

@@ -0,0 +1,37 @@
+/**
+ * Shared body → Prisma update mapping for media metadata writes.
+ * Used by `PUT /media/:id` and `POST /media/bulk-update` so decorative-alt
+ * rules stay in one place (#714 / #717).
+ */
+export const BULK_MEDIA_MAX_ITEMS = 50;
+/** Map a partial media metadata patch to Prisma `media.update` data. */
+export function buildMediaMetadataUpdateData(body) {
+    const data = {
+        ...(body.alt !== undefined ? { altText: body.alt } : {}),
+        ...(body.title !== undefined ? { title: body.title } : {}),
+        ...(body.filename !== undefined ? { filename: body.filename } : {}),
+        ...(body.caption !== undefined ? { caption: body.caption } : {}),
+        ...(body.description !== undefined ? { description: body.description } : {}),
+        ...(body.focusKeyword !== undefined ? { focusKeyword: body.focusKeyword } : {}),
+        ...(body.focalX !== undefined ? { focalPointX: body.focalX } : {}),
+        ...(body.focalY !== undefined ? { focalPointY: body.focalY } : {}),
+    };
+    // Decorative images use empty alt by design (#714). Explicit true forces
+    // alt=""; a non-empty alt clears the flag so the scorer stays coherent.
+    if (body.isDecorative === true) {
+        data.isDecorative = true;
+        data.altText = '';
+    }
+    else if (body.isDecorative === false) {
+        data.isDecorative = false;
+    }
+    if (typeof body.alt === 'string' && body.alt.trim().length > 0) {
+        data.isDecorative = false;
+        data.altText = body.alt;
+    }
+    return data;
+}
+export function isEmptyMediaMetadataPatch(body) {
+    return Object.keys(buildMediaMetadataUpdateData(body)).length === 0;
+}
+//# sourceMappingURL=metadata-patch.js.map

package/dist/media/metadata-patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-patch.js","sourceRoot":"","sources":["../../src/media/metadata-patch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAA;AActC,wEAAwE;AACxE,MAAM,UAAU,4BAA4B,CAAC,IAAwB;IACnE,MAAM,IAAI,GAA4B;QACpC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnE,CAAA;IAED,yEAAyE;IACzE,wEAAwE;IACxE,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAA;QACxB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;IACnB,CAAC;SAAM,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAA;IAC3B,CAAC;IAED,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,YAAY,GAAG,KAAK,CAAA;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAA;IACzB,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,IAAwB;IAChE,OAAO,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAA;AACrE,CAAC"}

package/dist/media/optimize.d.ts

@@ -0,0 +1,61 @@
+export interface OptimizationResult {
+    buffer: Buffer;
+    width: number;
+    height: number;
+    originalSize: number;
+    optimizedSize: number;
+    savings: number;
+    format: 'webp' | 'original';
+    mimeType: string;
+    filename: string;
+    blurHash?: string;
+    /** True when the output WebP used lossless encoding (no quality loss). */
+    lossless: boolean;
+}
+export interface OptimizeOptions {
+    /**
+     * When true, encode WebP in lossless mode (larger files, no encode loss).
+     * Default is **false** — high-quality lossy WebP for meaningful compression
+     * while preserving visual fidelity.
+     */
+    lossless?: boolean;
+    /** Lossy WebP quality (60–95). Ignored when `lossless` is true. */
+    quality?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    /** WebP encoder effort 0–6. Higher = smaller files, slower uploads. */
+    effort?: number;
+    /** Skip WebP conversion for these MIME types */
+    preserveFormats?: string[];
+}
+/** Default: high-quality lossy WebP — strong compression, visually sharp on web. */
+export declare const DEFAULT_IMAGE_OPTIMIZATION_LOSSLESS = false;
+/** Photo / opaque raster quality (visually lossless on typical displays). */
+export declare const DEFAULT_WEBP_QUALITY = 82;
+/** PNG with transparency — slightly higher to preserve clean edges. */
+export declare const DEFAULT_WEBP_QUALITY_ALPHA = 86;
+export declare const DEFAULT_MAX_IMAGE_DIMENSION = 4096;
+export declare const DEFAULT_WEBP_EFFORT = 4;
+export declare const MIN_WEBP_QUALITY = 60;
+export declare const MAX_WEBP_QUALITY = 95;
+/**
+ * Optimizes an image: converts to high-quality **lossy WebP** by default (strong
+ * compression, visually sharp), resizes if too large, and generates a blur
+ * placeholder. Pass `{ lossless: true }` for pixel-perfect lossless WebP.
+ * Non-image files and SVGs/GIFs are returned unchanged.
+ */
+export declare function optimizeImage(input: Buffer | ArrayBuffer | Uint8Array, originalFilename: string, mimeType: string, opts?: OptimizeOptions): Promise<OptimizationResult>;
+/**
+ * Extracts image metadata without performing optimization.
+ * Useful for non-destructive dimension/format reads.
+ */
+export declare function getImageMetadata(input: Buffer | ArrayBuffer | Uint8Array): Promise<{
+    width: number;
+    height: number;
+    format: keyof import("sharp").FormatEnum;
+    hasAlpha: boolean;
+    isAnimated: boolean;
+    space: keyof import("sharp").ColourspaceEnum;
+} | null>;
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=optimize.d.ts.map

package/dist/media/optimize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize.d.ts","sourceRoot":"","sources":["../../src/media/optimize.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,oFAAoF;AACpF,eAAO,MAAM,mCAAmC,QAAQ,CAAA;AACxD,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,KAAK,CAAA;AACtC,uEAAuE;AACvE,eAAO,MAAM,0BAA0B,KAAK,CAAA;AAC5C,eAAO,MAAM,2BAA2B,OAAO,CAAA;AAC/C,eAAO,MAAM,mBAAmB,IAAI,CAAA;AACpC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAClC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AA2DlC;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,EACxC,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CA8F7B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU;;;;;;;UAmB9E;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}

package/dist/media/optimize.js

@@ -0,0 +1,168 @@
+let _sharp = null;
+async function getSharp() {
+    if (!_sharp) {
+        const mod = await import(/* webpackIgnore: true */ 'sharp');
+        _sharp = (mod.default ?? mod);
+    }
+    return _sharp;
+}
+/** Default: high-quality lossy WebP — strong compression, visually sharp on web. */
+export const DEFAULT_IMAGE_OPTIMIZATION_LOSSLESS = false;
+/** Photo / opaque raster quality (visually lossless on typical displays). */
+export const DEFAULT_WEBP_QUALITY = 82;
+/** PNG with transparency — slightly higher to preserve clean edges. */
+export const DEFAULT_WEBP_QUALITY_ALPHA = 86;
+export const DEFAULT_MAX_IMAGE_DIMENSION = 4096;
+export const DEFAULT_WEBP_EFFORT = 4;
+export const MIN_WEBP_QUALITY = 60;
+export const MAX_WEBP_QUALITY = 95;
+const DEFAULT_OPTIONS = {
+    lossless: DEFAULT_IMAGE_OPTIMIZATION_LOSSLESS,
+    quality: DEFAULT_WEBP_QUALITY,
+    maxWidth: DEFAULT_MAX_IMAGE_DIMENSION,
+    maxHeight: DEFAULT_MAX_IMAGE_DIMENSION,
+    effort: DEFAULT_WEBP_EFFORT,
+    preserveFormats: ['image/svg+xml', 'image/gif'],
+};
+const OPTIMIZABLE_TYPES = new Set([
+    'image/jpeg',
+    'image/jpg',
+    'image/png',
+    'image/webp',
+    'image/tiff',
+    'image/avif',
+    'image/bmp',
+]);
+function unchangedResult(inputBuffer, originalSize, mimeType, originalFilename, width, height) {
+    return {
+        buffer: inputBuffer,
+        width,
+        height,
+        originalSize,
+        optimizedSize: originalSize,
+        savings: 0,
+        format: 'original',
+        mimeType,
+        filename: originalFilename,
+        lossless: false,
+    };
+}
+function resolveLossyQuality(opts, options, hasAlpha, mimeType) {
+    const base = opts.quality ??
+        (hasAlpha && mimeType === 'image/png' ? DEFAULT_WEBP_QUALITY_ALPHA : options.quality);
+    return Math.min(MAX_WEBP_QUALITY, Math.max(MIN_WEBP_QUALITY, base));
+}
+/**
+ * Optimizes an image: converts to high-quality **lossy WebP** by default (strong
+ * compression, visually sharp), resizes if too large, and generates a blur
+ * placeholder. Pass `{ lossless: true }` for pixel-perfect lossless WebP.
+ * Non-image files and SVGs/GIFs are returned unchanged.
+ */
+export async function optimizeImage(input, originalFilename, mimeType, opts = {}) {
+    const options = { ...DEFAULT_OPTIONS, ...opts };
+    const inputBuffer = input instanceof Buffer
+        ? input
+        : Buffer.from(new Uint8Array(input instanceof ArrayBuffer ? input : input.buffer));
+    const originalSize = inputBuffer.length;
+    const sharp = await getSharp();
+    if (!OPTIMIZABLE_TYPES.has(mimeType) || options.preserveFormats.includes(mimeType)) {
+        let width = 0;
+        let height = 0;
+        try {
+            const meta = await sharp(inputBuffer).metadata();
+            width = meta.width ?? 0;
+            height = meta.height ?? 0;
+        }
+        catch {
+            // non-image or unrecognized — return as-is
+        }
+        return unchangedResult(inputBuffer, originalSize, mimeType, originalFilename, width, height);
+    }
+    let pipeline = sharp(inputBuffer, { animated: false }).rotate(); // auto-orient based on EXIF
+    const metadata = await sharp(inputBuffer).metadata();
+    let { width = 0, height = 0 } = metadata;
+    const hasAlpha = metadata.hasAlpha === true;
+    if (width > options.maxWidth || height > options.maxHeight) {
+        pipeline = pipeline.resize(options.maxWidth, options.maxHeight, {
+            fit: 'inside',
+            withoutEnlargement: true,
+        });
+        const ratio = Math.min(options.maxWidth / width, options.maxHeight / height);
+        width = Math.round(width * ratio);
+        height = Math.round(height * ratio);
+    }
+    const effort = Math.min(6, Math.max(0, options.effort));
+    const useLossless = opts.lossless === true;
+    const optimizedBuffer = useLossless
+        ? await pipeline.webp({ lossless: true, effort }).toBuffer()
+        : await pipeline
+            .webp({
+            quality: resolveLossyQuality(opts, options, hasAlpha, mimeType),
+            alphaQuality: hasAlpha ? resolveLossyQuality(opts, options, true, mimeType) : undefined,
+            effort,
+            smartSubsample: true,
+        })
+            .toBuffer();
+    const optimizedSize = optimizedBuffer.length;
+    // If WebP is not smaller, keep the original bytes — no pointless re-encode.
+    if (optimizedSize >= originalSize) {
+        return unchangedResult(inputBuffer, originalSize, mimeType, originalFilename, metadata.width ?? 0, metadata.height ?? 0);
+    }
+    const webpFilename = originalFilename.replace(/\.[^.]+$/, '.webp');
+    let blurHash;
+    try {
+        const placeholder = await sharp(inputBuffer)
+            .resize(20, 20, { fit: 'inside' })
+            .webp({ quality: 20 })
+            .toBuffer();
+        blurHash = `data:image/webp;base64,${placeholder.toString('base64')}`;
+    }
+    catch {
+        // blur generation is best-effort
+    }
+    return {
+        buffer: optimizedBuffer,
+        width,
+        height,
+        originalSize,
+        optimizedSize,
+        savings: Math.round((1 - optimizedSize / originalSize) * 100),
+        format: 'webp',
+        mimeType: 'image/webp',
+        filename: webpFilename,
+        blurHash,
+        lossless: useLossless,
+    };
+}
+/**
+ * Extracts image metadata without performing optimization.
+ * Useful for non-destructive dimension/format reads.
+ */
+export async function getImageMetadata(input) {
+    const buffer = input instanceof Buffer
+        ? input
+        : Buffer.from(new Uint8Array(input instanceof ArrayBuffer ? input : input.buffer));
+    try {
+        const sharp = await getSharp();
+        const meta = await sharp(buffer).metadata();
+        return {
+            width: meta.width ?? null,
+            height: meta.height ?? null,
+            format: meta.format ?? null,
+            hasAlpha: meta.hasAlpha ?? false,
+            isAnimated: (meta.pages ?? 1) > 1,
+            space: meta.space ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+//# sourceMappingURL=optimize.js.map

package/dist/media/optimize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize.js","sourceRoot":"","sources":["../../src/media/optimize.ts"],"names":[],"mappings":"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"}

package/dist/media/seo.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Media SEO scoring.
+ *
+ * Pure, dependency-free functions that derive an SEO score and a list of
+ * actionable issues from a media asset's metadata. The score is intentionally
+ * *derived* (never persisted) so it can never drift out of sync with the
+ * underlying metadata — every read recomputes it from the current fields.
+ *
+ * The weights below are the contract the admin SEO drawer, the SEO Audit
+ * table, and the `validateMediaSEO` MCP tool all share. Changing a weight is a
+ * behavioural change to every surface that shows a media score, so keep the
+ * unit tests in `__tests__/seo.test.ts` as the source of truth.
+ */
+/** Coarse asset class derived from a MIME type. */
+export type MediaKind = 'image' | 'video' | 'pdf' | 'svg' | 'audio' | 'other';
+export type MediaSeoGrade = 'good' | 'needs-work' | 'poor' | 'critical';
+export type MediaSeoSeverity = 'critical' | 'high' | 'medium' | 'low';
+/** A single, actionable SEO problem with a stable machine-readable `type`. */
+export interface MediaSeoIssue {
+    /** Stable identifier, e.g. `missing-alt`. Safe to switch/route on. */
+    type: string;
+    severity: MediaSeoSeverity;
+    /** Human-readable, operator-safe description. */
+    message: string;
+    /** The asset field this issue maps to, when applicable. */
+    field?: string;
+    /** Whether the AI metadata flow can plausibly fix this issue. */
+    fixableWithAI: boolean;
+}
+export interface MediaSeoScoreResult {
+    /** 0–100, integer. */
+    score: number;
+    grade: MediaSeoGrade;
+    issues: MediaSeoIssue[];
+}
+/** The metadata subset the score depends on. */
+export interface MediaSeoInput {
+    fileName?: string | null;
+    mimeType?: string | null;
+    altText?: string | null;
+    title?: string | null;
+    caption?: string | null;
+    description?: string | null;
+    focusKeyword?: string | null;
+    sizeBytes?: number | null;
+    width?: number | null;
+    height?: number | null;
+    /**
+     * When true, empty alt is the correct WCAG treatment for a decorative
+     * image. Awards the alt weight and suppresses `missing-alt` /
+     * `missing-description` (#714).
+     */
+    isDecorative?: boolean | null;
+    /**
+     * Titles of documents that reference this asset. Used only for the
+     * non-scoring `low-quality-alt` advisory (#715).
+     */
+    usedOnTitles?: string[] | null;
+}
+export interface MediaSeoOptions {
+    /**
+     * Bytes above which an image is flagged as oversized. Defaults to 2 MB —
+     * large enough to allow a quality hero image, small enough to flag
+     * un-optimised originals. Set from `config.media.maxImageSeoBytes`.
+     */
+    maxImageBytes?: number;
+}
+/** SEO weights. Must sum to 100. */
+export declare const MEDIA_SEO_WEIGHTS: {
+    readonly altText: 30;
+    readonly title: 20;
+    readonly description: 20;
+    readonly caption: 10;
+    readonly descriptiveFileName: 10;
+    readonly focusKeyword: 10;
+};
+/** Map a MIME type to a coarse {@link MediaKind}. */
+export declare function mediaKind(mimeType?: string | null): MediaKind;
+/**
+ * Whether a filename is generic/non-descriptive (e.g. `IMG_4892.jpg`). A
+ * descriptive name needs at least one alphabetic run of 3+ chars and must not
+ * match a known camera/screenshot/default pattern.
+ */
+export declare function isGenericFilename(fileName?: string | null): boolean;
+/**
+ * True when alt looks like a migrated topic label rather than an image
+ * description: equals the filename stem, or exactly matches a document title
+ * that uses the asset. Does not change the score (#715).
+ */
+export declare function isLowQualityAlt(altText: string | null | undefined, fileName: string | null | undefined, usedOnTitles?: string[] | null): boolean;
+/** Map a numeric score to a grade bucket. */
+export declare function gradeForScore(score: number): MediaSeoGrade;
+/**
+ * Compute the SEO score (0–100) and issue list for a media asset.
+ *
+ * Scoring (weights in {@link MEDIA_SEO_WEIGHTS}, sum 100):
+ *   alt text +30, title +20, description +20, caption +10,
+ *   descriptive filename +10, focus keyword +10.
+ *
+ * Decorative assets (`isDecorative`) earn the alt weight with empty alt and
+ * skip description pressure — there is no meaningful description for a
+ * background flourish (#714).
+ *
+ * Issues are additive context and do not subtract from the score directly —
+ * e.g. an oversized image still scores on metadata, but surfaces an
+ * `oversized-image` issue operators can act on. `low-quality-alt` is advisory
+ * only and never changes the numeric score (#715).
+ */
+export declare function calculateMediaSeoScore(input: MediaSeoInput, options?: MediaSeoOptions): MediaSeoScoreResult;
+//# sourceMappingURL=seo.d.ts.map

package/dist/media/seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.d.ts","sourceRoot":"","sources":["../../src/media/seo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAA;AAE7E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,UAAU,CAAA;AAEvE,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAErE,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,MAAM,EAAE,aAAa,EAAE,CAAA;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAID,oCAAoC;AACpC,eAAO,MAAM,iBAAiB;;;;;;;CAOpB,CAAA;AA0CV,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAQnE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAC7B,OAAO,CAkBT;AAED,6CAA6C;AAC7C,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAK1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,eAAoB,GAC5B,mBAAmB,CA+HrB"}