@layerporter/image-optimizer-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,45 @@
+LayerPorter Proprietary Software License
+
+Copyright (c) 2026 LayerPorter. All rights reserved.
+
+1. LIMITED LICENSE
+
+Subject to your compliance with this License, LayerPorter grants you a limited, non-exclusive, non-transferable, non-sublicensable right to download, install, and use the unmodified official LayerPorter Website Image Optimizer MCP package solely for its intended functionality.
+
+You may make only those copies that are technically necessary for installation, execution, backup, or package-manager caching, and only for those purposes.
+
+2. RESTRICTIONS
+
+Except where expressly permitted by this License or required by applicable law, you may not, and may not permit any third party to:
+
+(a) copy or reproduce the Software except for the limited technical copies expressly permitted above;
+(b) modify, adapt, translate, alter, or create derivative works from the Software;
+(c) distribute, publish, republish, mirror, host for third-party download, sublicense, sell, rent, lease, assign, transfer, or otherwise make the Software available to third parties;
+(d) repackage, bundle, embed, or include the Software or substantial portions of it in another product, package, service, repository, or distribution;
+(e) reverse engineer, decompile, disassemble, or otherwise attempt to derive source code or underlying implementation details, except to the limited extent such restriction is prohibited by applicable law;
+(f) remove, obscure, or alter copyright, ownership, trademark, or other proprietary notices;
+(g) use the Software, its source code, or substantial portions of its implementation to create, train, reproduce, or distribute a competing or substantially similar software product.
+
+3. OWNERSHIP
+
+The Software is licensed, not sold. LayerPorter retains all right, title, and interest in and to the Software, including all intellectual property rights not expressly granted under this License. No rights to LayerPorter names, marks, logos, branding, or other identifiers are granted.
+
+4. THIRD-PARTY COMPONENTS
+
+Third-party software, libraries, or dependencies used with the Software remain subject to their respective licenses. This License does not replace or restrict rights granted by those third-party licenses.
+
+5. TERMINATION
+
+Your rights under this License terminate automatically if you materially breach its terms. Upon termination, you must stop using the Software and delete copies in your possession or control, except copies that applicable law requires you to retain.
+
+6. DISCLAIMER
+
+THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW.
+
+7. LIMITATION OF LIABILITY
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, LAYERPORTER WILL NOT BE LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS OF PROFITS, REVENUE, DATA, OR BUSINESS OPPORTUNITY ARISING FROM OR RELATED TO THE SOFTWARE.
+
+8. NO IMPLIED RIGHTS
+
+No permission is granted by implication, estoppel, or otherwise beyond the limited rights expressly stated in this License.

package/README.md

@@ -0,0 +1,124 @@
+# LayerPorter Website Image Optimizer MCP
+
+Technical candidate for page-aware website image optimization through Model Context Protocol.
+
+## Status
+
+The package is release-prepared but is **not yet claimed as a public npm or Official MCP Registry release**. Publication status changes only after the exact npm version and Registry entry are externally verified.
+
+Registry identity:
+
+- npm package: `@layerporter/image-optimizer-mcp`
+- MCP server: `com.layerporter/website-image-optimizer`
+- transport: `stdio`
+- Node.js: `>=22.12.0`
+
+The npm package carries `mcpName: com.layerporter/website-image-optimizer`, matching `server.json`, so the Official MCP Registry can verify package ownership after the package exists publicly on npm.
+
+## Tools
+
+The current server registers seven bounded tools:
+
+- `analyze_page_images`
+- `optimize_image`
+- `generate_responsive_variants`
+- `compare_image_versions`
+- `optimize_page_images`
+- `analyze_url_images`
+- `optimize_url_images`
+
+The first five operate on caller-provided image data or normalized page facts. The two URL tools perform bounded read-only HTTP(S) fetching through a dedicated SSRF-protected network boundary. URL mode is intentionally a fast static-HTML mode: it does not claim browser-rendered size, `currentSrc`, LCP, CSS-background discovery, or JavaScript-driven lazy content.
+
+Accepted optimized binaries are exposed as temporary MCP `resource_link` values and are read separately with `resources/read`; they are not embedded in the initial tool text response.
+
+## Runtime
+
+- Node.js `>=22.12.0`
+- MCP v2 server package
+- stdio transport
+- image processing through the shared image core / Sharp / libvips
+
+## Local source setup
+
+A source checkout does not contain the generated `src/image-core` copy. Sync it explicitly before MCP tests or direct server startup:
+
+```bash
+cd packages/image-core
+npm install --no-audit --no-fund
+npm test
+
+cd ../image-optimizer-mcp
+npm install --ignore-scripts --no-audit --no-fund
+npm run release:preflight
+npm run sync:core
+npm test
+node src/server.js
+```
+
+The last command starts the stdio MCP server and waits for a client connection. `npm pack` also runs `sync:core` through `prepack`; source setup and packed-artifact setup are verified separately.
+
+## Installation after public release
+
+Do not treat this command as available until the npm package has actually been published and verified:
+
+```bash
+npx -y @layerporter/image-optimizer-mcp
+```
+
+## License
+
+This package is proprietary LayerPorter software. The official unmodified package may be downloaded, installed, and used under the terms in `LICENSE`. Copying beyond technically necessary installation/runtime copies, modification, derivative works, repackaging, redistribution, sublicensing, resale, and unauthorized hosting are prohibited.
+
+The software is licensed, not sold. Third-party dependencies remain governed by their own licenses.
+
+## Release model
+
+The first npm version is a bootstrap release: npm staged publishing and Trusted Publisher configuration require the package to already exist. The first public package therefore must be published by the package owner with npm account 2FA. After that bootstrap, GitHub Actions Trusted Publishing can be configured for `.github/workflows/image-mcp-release.yml`, and later versions can use the staged OIDC release path.
+
+Official MCP Registry publication happens only **after** the matching npm version is publicly available. The Registry namespace uses ownership of `layerporter.com` and the server name `com.layerporter/website-image-optimizer`.
+
+## Safety boundary
+
+The current MCP package:
+
+- performs bounded public HTTP(S) reads only through `analyze_url_images` and `optimize_url_images`;
+- blocks unsafe URL schemes, URL credentials, localhost/private/link-local/reserved targets, unsafe DNS answers and redirects to prohibited addresses;
+- caps page bytes, per-image bytes, accepted total image bytes, redirects, image count, timeouts and concurrency;
+- writes accepted image artifacts only to its isolated temporary artifact store;
+- does not perform arbitrary filesystem write/delete/rename operations;
+- does not execute shell commands;
+- does not write to a website or production environment.
+
+Local transform tools consume caller-provided image buffers or normalized page facts. URL tools are read-only open-world operations. Hard safety comes from implementation controls, not only from MCP metadata.
+
+Temporary artifacts are process-local and ephemeral. Their default TTL is 30 minutes, but cleanup occurs during store operations/disposal rather than as a guarantee of physical deletion at an exact wall-clock instant. `resources/read` returns the resource blob separately; whether a client places that blob into model context is client-specific.
+
+## Verification
+
+Release preparation verifies:
+
+- package/server identity consistency;
+- proprietary license metadata and packaged `LICENSE` presence;
+- image-core and MCP tests;
+- packed npm artifact metadata;
+- clean installation of the packed tarball;
+- real stdio startup and client handshake from the packed artifact;
+- `tools/list`, transform calls, temporary `resource_link` and `resources/read`;
+- Official MCP Registry `server.json` validation;
+- full LayerPorter Astro build in the integrated repository tree.
+
+## Public documentation
+
+Canonical product pages after site release:
+
+- `https://layerporter.com/mcp/website-image-optimizer/`
+- `https://layerporter.com/docs/mcp/website-image-optimizer/`
+
+## Not yet included
+
+- confirmed public npm release;
+- confirmed Official MCP Registry publication;
+- hosted endpoint;
+- full browser crawler/runtime metrics collection;
+- production apply/write tool;
+- universal performance or quality claims.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@layerporter/image-optimizer-mcp",
+  "version": "0.1.0",
+  "description": "Page-aware MCP server for deterministic website image analysis and safe optimization.",
+  "mcpName": "com.layerporter/website-image-optimizer",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "layerporter-image-optimizer-mcp": "src/server.js"
+  },
+  "files": [
+    "src/**",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "scripts": {
+    "sync:core": "node scripts/sync-image-core.mjs",
+    "prepack": "npm run sync:core",
+    "test": "node --test tests/*.test.js",
+    "release:preflight": "node scripts/release-preflight.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "sharp": "0.35.4",
+    "zod": "^4.1.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OlegStrateg/layerporter-site.git",
+    "directory": "packages/image-optimizer-mcp"
+  },
+  "homepage": "https://layerporter.com/mcp/website-image-optimizer/",
+  "bugs": {
+    "url": "https://github.com/OlegStrateg/layerporter-site/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "image-optimization",
+    "webp",
+    "avif",
+    "core-web-vitals",
+    "lcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/server.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "com.layerporter/website-image-optimizer",
+  "title": "LayerPorter Website Image Optimizer",
+  "description": "Page-aware website image analysis and safe optimization MCP server.",
+  "websiteUrl": "https://layerporter.com/mcp/website-image-optimizer/",
+  "repository": {
+    "url": "https://github.com/OlegStrateg/layerporter-site",
+    "source": "github",
+    "subfolder": "packages/image-optimizer-mcp"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@layerporter/image-optimizer-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/src/artifact-result.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import { sanitizeForText } from './text-result.js';
+
+const MIME_BY_FORMAT = Object.freeze({
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  webp: 'image/webp',
+  avif: 'image/avif',
+});
+
+function safeStem(value) {
+  if (typeof value !== 'string' || !value.trim()) return 'optimized-image';
+  let raw = value.trim();
+  try {
+    raw = path.basename(new URL(raw).pathname) || raw;
+  } catch {
+    raw = path.basename(raw);
+  }
+  return (raw.replace(/\.[a-zA-Z0-9]+$/, '').replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 72) || 'optimized-image');
+}
+
+function extensionFor(format) {
+  if (format === 'jpeg' || format === 'jpg') return 'jpg';
+  if (format === 'png' || format === 'webp' || format === 'avif') return format;
+  return 'bin';
+}
+
+function artifactName(context, object) {
+  const format = object.output?.format ?? object.outputFormat ?? context.format ?? null;
+  const width = object.width ?? object.output?.width ?? context.width ?? null;
+  const suffix = Number.isFinite(width) && width > 0 ? `${width}w` : 'optimized';
+  return `${safeStem(context.source)}-${suffix}.${extensionFor(format)}`;
+}
+
+async function walk(value, store, links, context = {}) {
+  if (Buffer.isBuffer(value)) return { type: 'binary', byteLength: value.byteLength };
+  if (Array.isArray(value)) return Promise.all(value.map((item) => walk(item, store, links, context)));
+  if (!value || typeof value !== 'object') return value;
+
+  const nextContext = {
+    source: value.sourceUrl ?? value.id ?? context.source,
+    width: value.width ?? value.output?.width ?? context.width,
+    format: value.output?.format ?? value.outputFormat ?? context.format,
+  };
+  const out = {};
+
+  for (const [key, item] of Object.entries(value)) {
+    if (key === 'buffer' && Buffer.isBuffer(item)) {
+      if (value.status === 'ACCEPT') {
+        const format = value.output?.format ?? value.outputFormat ?? nextContext.format;
+        const mimeType = MIME_BY_FORMAT[format] ?? 'application/octet-stream';
+        const artifact = await store.put(item, {
+          name: artifactName(nextContext, value),
+          mimeType,
+        });
+        out.artifact = artifact;
+        links.push({
+          type: 'resource_link',
+          uri: artifact.uri,
+          name: artifact.name,
+          title: 'Optimized image artifact',
+          description: `Verified temporary image output. SHA-256 ${artifact.sha256}.`,
+          mimeType: artifact.mimeType,
+          size: artifact.size,
+        });
+      } else {
+        out.buffer = { type: 'binary', byteLength: item.byteLength };
+      }
+      continue;
+    }
+    out[key] = await walk(item, store, links, nextContext);
+  }
+
+  return out;
+}
+
+export async function artifactToolResult(value, store) {
+  const links = [];
+  const safeValue = await walk(value, store, links);
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(sanitizeForText(safeValue)),
+      },
+      ...links,
+    ],
+  };
+}

package/src/artifact-store.js

@@ -0,0 +1,153 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const ARTIFACT_SCHEME = 'layerporter-artifact:';
+const ARTIFACT_HOST = 'artifact';
+const ID_RE = /^[a-f0-9]{32}$/;
+
+const EXT_BY_MIME = Object.freeze({
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/webp': '.webp',
+  'image/avif': '.avif',
+});
+
+function artifactError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function safeName(value, mimeType) {
+  const fallback = `optimized-image${EXT_BY_MIME[mimeType] ?? '.bin'}`;
+  const raw = typeof value === 'string' && value.trim() ? path.basename(value.trim()) : fallback;
+  const cleaned = raw.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 96) || fallback;
+  if (path.extname(cleaned)) return cleaned;
+  return `${cleaned}${EXT_BY_MIME[mimeType] ?? '.bin'}`;
+}
+
+export function parseArtifactId(value) {
+  if (typeof value !== 'string' || !value.trim()) throw artifactError('INVALID_ARTIFACT_ID', 'artifact id is required');
+  let id = value.trim();
+  if (id.startsWith(`${ARTIFACT_SCHEME}//`)) {
+    const url = new URL(id);
+    if (url.protocol !== ARTIFACT_SCHEME || url.hostname !== ARTIFACT_HOST) {
+      throw artifactError('INVALID_ARTIFACT_URI', 'unsupported artifact URI');
+    }
+    id = url.pathname.replace(/^\/+/, '');
+  }
+  if (!ID_RE.test(id)) throw artifactError('INVALID_ARTIFACT_ID', 'invalid artifact id');
+  return id;
+}
+
+export class ArtifactStore {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir ?? path.join(os.tmpdir(), 'layerporter-image-optimizer-artifacts');
+    this.ttlMs = options.ttlMs ?? 30 * 60 * 1000;
+    this.maxArtifacts = options.maxArtifacts ?? 50;
+    this.maxTotalBytes = options.maxTotalBytes ?? 50 * 1024 * 1024;
+    this.maxArtifactBytes = options.maxArtifactBytes ?? 10 * 1024 * 1024;
+    this.records = new Map();
+    this.totalBytes = 0;
+    this.initialized = false;
+  }
+
+  async init() {
+    if (this.initialized) return;
+    await fs.mkdir(this.rootDir, { recursive: true, mode: 0o700 });
+    const now = Date.now();
+    for (const entry of await fs.readdir(this.rootDir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const filePath = path.join(this.rootDir, entry.name);
+      try {
+        const stat = await fs.stat(filePath);
+        if (now - stat.mtimeMs > this.ttlMs) await fs.unlink(filePath);
+      } catch {
+        // Best-effort cleanup only. Unknown files are never exposed through the in-memory index.
+      }
+    }
+    this.initialized = true;
+  }
+
+  async cleanupExpired(now = Date.now()) {
+    for (const [id, record] of this.records) {
+      if (record.expiresAtMs > now) continue;
+      this.records.delete(id);
+      this.totalBytes -= record.size;
+      await fs.unlink(record.filePath).catch(() => {});
+    }
+  }
+
+  async put(buffer, options = {}) {
+    if (!Buffer.isBuffer(buffer) || buffer.length === 0) throw artifactError('INVALID_ARTIFACT', 'artifact must be a non-empty Buffer');
+    if (buffer.length > this.maxArtifactBytes) throw artifactError('ARTIFACT_TOO_LARGE', 'artifact exceeds per-file byte limit');
+
+    await this.init();
+    await this.cleanupExpired();
+    if (this.records.size >= this.maxArtifacts) throw artifactError('ARTIFACT_STORE_FULL', 'artifact count limit reached');
+    if (this.totalBytes + buffer.length > this.maxTotalBytes) throw artifactError('ARTIFACT_STORE_FULL', 'artifact byte budget reached');
+
+    const id = crypto.randomUUID().replaceAll('-', '');
+    const mimeType = options.mimeType ?? 'application/octet-stream';
+    const name = safeName(options.name, mimeType);
+    const filePath = path.join(this.rootDir, `${id}-${name}`);
+    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
+    const createdAtMs = Date.now();
+    const expiresAtMs = createdAtMs + this.ttlMs;
+
+    await fs.writeFile(filePath, buffer, { flag: 'wx', mode: 0o600 });
+
+    const record = {
+      id,
+      name,
+      mimeType,
+      size: buffer.length,
+      sha256,
+      filePath,
+      createdAtMs,
+      expiresAtMs,
+    };
+    this.records.set(id, record);
+    this.totalBytes += record.size;
+    return this.publicMetadata(record);
+  }
+
+  publicMetadata(record) {
+    return {
+      id: record.id,
+      uri: `${ARTIFACT_SCHEME}//${ARTIFACT_HOST}/${record.id}`,
+      name: record.name,
+      mimeType: record.mimeType,
+      size: record.size,
+      sha256: record.sha256,
+      expiresAt: new Date(record.expiresAtMs).toISOString(),
+    };
+  }
+
+  async read(idOrUri) {
+    await this.init();
+    await this.cleanupExpired();
+    const id = parseArtifactId(idOrUri);
+    const record = this.records.get(id);
+    if (!record) throw artifactError('ARTIFACT_NOT_FOUND', 'artifact is missing or expired');
+    if (record.expiresAtMs <= Date.now()) {
+      await this.cleanupExpired();
+      throw artifactError('ARTIFACT_EXPIRED', 'artifact expired');
+    }
+
+    const buffer = await fs.readFile(record.filePath);
+    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
+    if (buffer.length !== record.size || sha256 !== record.sha256) {
+      throw artifactError('ARTIFACT_INTEGRITY_FAILED', 'artifact integrity verification failed');
+    }
+    return { ...this.publicMetadata(record), buffer };
+  }
+
+  async dispose() {
+    for (const record of this.records.values()) await fs.unlink(record.filePath).catch(() => {});
+    this.records.clear();
+    this.totalBytes = 0;
+  }
+}

package/src/image-core/index.js

@@ -0,0 +1,168 @@
+import sharp from 'sharp';
+import { chooseOutputFormat, validatePolicy } from './policy.js';
+
+function assertBuffer(input) {
+  if (!Buffer.isBuffer(input) || input.length === 0) {
+    throw new TypeError('input must be a non-empty Buffer');
+  }
+}
+
+function assertTarget(target = {}) {
+  for (const key of ['width', 'height']) {
+    if (target[key] !== undefined && (!Number.isInteger(target[key]) || target[key] < 1)) {
+      throw new TypeError(`${key} must be a positive integer`);
+    }
+  }
+}
+
+function normalizeFormat(format, compression) {
+  if (format === 'heif' && compression === 'av1') return 'avif';
+  return format ?? null;
+}
+
+function orientedBounds(image, applyOrientation) {
+  if (applyOrientation && [5, 6, 7, 8].includes(image.orientation)) {
+    return { width: image.height, height: image.width };
+  }
+  return { width: image.width, height: image.height };
+}
+
+function encoder(pipeline, format, policy) {
+  switch (format) {
+    case 'jpeg':
+      return pipeline.jpeg({ quality: policy.quality, mozjpeg: true });
+    case 'png':
+      return pipeline.png({ compressionLevel: 9, adaptiveFiltering: true });
+    case 'webp':
+      return pipeline.webp({ quality: policy.quality, effort: Math.min(policy.effort, 6) });
+    case 'avif':
+      return pipeline.avif({ quality: policy.avifQuality, effort: policy.effort });
+    default:
+      throw new TypeError(`Unsupported encoder: ${format}`);
+  }
+}
+
+export async function inspectImage(input, options = {}) {
+  assertBuffer(input);
+  const policy = validatePolicy(options.policy);
+  const metadata = await sharp(input, { limitInputPixels: policy.maxPixels }).metadata();
+
+  if (!metadata.width || !metadata.height) {
+    throw new Error('Unable to determine image dimensions');
+  }
+  if (metadata.width > policy.maxWidth || metadata.height > policy.maxHeight) {
+    throw new RangeError(`Image dimensions exceed ${policy.maxWidth}x${policy.maxHeight}`);
+  }
+
+  return {
+    bytes: input.length,
+    format: normalizeFormat(metadata.format, metadata.compression),
+    mediaType: metadata.mediaType ?? null,
+    compression: metadata.compression ?? null,
+    width: metadata.width,
+    height: metadata.height,
+    orientation: metadata.orientation ?? null,
+    hasAlpha: Boolean(metadata.hasAlpha),
+    space: metadata.space ?? null,
+    channels: metadata.channels ?? null,
+  };
+}
+
+export async function optimizeImage(input, options = {}) {
+  assertBuffer(input);
+  const target = options.target ?? {};
+  assertTarget(target);
+  const policy = validatePolicy(options.policy);
+  const original = await inspectImage(input, { policy });
+  const outputFormat = chooseOutputFormat(original, policy);
+
+  if (policy.preserveAlpha && original.hasAlpha && outputFormat === 'jpeg') {
+    return {
+      status: 'REJECT',
+      reason: 'alpha_would_be_lost',
+      original,
+      output: original,
+      outputFormat: original.format,
+      savingsBytes: 0,
+      savingsPercent: 0,
+      buffer: input,
+    };
+  }
+
+  let pipeline = sharp(input, { limitInputPixels: policy.maxPixels });
+
+  if (policy.preserveOrientation) {
+    pipeline = pipeline.autoOrient();
+  }
+
+  pipeline = pipeline.keepIccProfile();
+
+  if (target.width || target.height) {
+    pipeline = pipeline.resize({
+      width: target.width,
+      height: target.height,
+      fit: 'inside',
+      withoutEnlargement: policy.withoutEnlargement,
+    });
+  }
+
+  const encoded = encoder(pipeline, outputFormat, policy);
+  const { data, info } = await encoded.toBuffer({ resolveWithObject: true });
+  const originalBounds = orientedBounds(original, policy.preserveOrientation);
+
+  if (policy.withoutEnlargement && (info.width > originalBounds.width || info.height > originalBounds.height)) {
+    throw new Error('no-upscale guard failed');
+  }
+  if (policy.preserveAlpha && original.hasAlpha && !info.channels) {
+    throw new Error('alpha verification unavailable');
+  }
+
+  const savingsBytes = original.bytes - data.length;
+  const savingsPercent = Number(((savingsBytes / original.bytes) * 100).toFixed(2));
+
+  if (policy.neverIncreaseBytes && data.length >= original.bytes) {
+    return {
+      status: 'REJECT',
+      reason: 'no_byte_saving',
+      original,
+      output: {
+        bytes: data.length,
+        format: outputFormat,
+        width: info.width,
+        height: info.height,
+        channels: info.channels,
+      },
+      outputFormat,
+      savingsBytes,
+      savingsPercent,
+      buffer: input,
+    };
+  }
+
+  const outputMetadata = await sharp(data, { limitInputPixels: policy.maxPixels }).metadata();
+  if (policy.preserveAlpha && original.hasAlpha && !outputMetadata.hasAlpha) {
+    throw new Error('alpha preservation guard failed');
+  }
+
+  return {
+    status: 'ACCEPT',
+    reason: 'smaller_without_guard_regression',
+    original,
+    output: {
+      bytes: data.length,
+      format: normalizeFormat(outputMetadata.format, outputMetadata.compression),
+      width: info.width,
+      height: info.height,
+      hasAlpha: Boolean(outputMetadata.hasAlpha),
+      orientation: outputMetadata.orientation ?? null,
+      space: outputMetadata.space ?? null,
+    },
+    outputFormat,
+    savingsBytes,
+    savingsPercent,
+    buffer: data,
+  };
+}
+
+export { DEFAULT_POLICY, validatePolicy, chooseOutputFormat } from './policy.js';
+export { analyzeImageUsage, analyzePageImages } from './page-analysis.js';