@m4k/common 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to `@m4k/common` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.9]
+
+### Added
+
+- Added the versioned image-classification contract, candidate validation and input-bound results.
+- Added Unicode-safe option encoding and embedded-preview image options.
+
 ## [0.2.8]
 
 ### Changed

package/lib/classification.d.ts

@@ -0,0 +1,31 @@
+/** Closed, immutable classifier profile. Changing weights, runtime, prompt or preprocessing needs a new version. */
+export declare const imageClassifier: {
+    readonly id: "clip-image-labels";
+    readonly version: "1";
+    readonly model: "Xenova/clip-vit-base-patch32";
+    readonly revision: "6b7c523703ae26e39be4b03774966f8571c7f523";
+    readonly template: "This is a photo of {}";
+    readonly maxBytes: number;
+    readonly maxPixels: number;
+    readonly maxLabels: 32;
+};
+export type ClassificationOptions = {
+    classifierId: string;
+    classifierVersion: string;
+    labels: readonly string[];
+};
+export type ClassificationResult = {
+    classifierId: string;
+    classifierVersion: string;
+    /** SHA-256 of the exact uploaded representation, not of the decoded image. */
+    sha256: string;
+    /** Softmax across the complete candidate set, not calibrated independent probabilities. */
+    labels: {
+        label: string;
+        score: number;
+    }[];
+};
+/** ASCII-safe JSON for HTTP byte-string headers, preserving arbitrary Unicode label text. */
+export declare function encodeOptions(value: unknown): string;
+export declare function validateClassificationOptions(value: unknown): value is ClassificationOptions;
+//# sourceMappingURL=classification.d.ts.map

package/lib/classification.js

@@ -0,0 +1,32 @@
+/** Closed, immutable classifier profile. Changing weights, runtime, prompt or preprocessing needs a new version. */
+export const imageClassifier = {
+    id: "clip-image-labels",
+    version: "1",
+    model: "Xenova/clip-vit-base-patch32",
+    revision: "6b7c523703ae26e39be4b03774966f8571c7f523",
+    template: "This is a photo of {}",
+    maxBytes: 8 * 1024 * 1024,
+    maxPixels: 1024 * 1024,
+    maxLabels: 32,
+};
+/** ASCII-safe JSON for HTTP byte-string headers, preserving arbitrary Unicode label text. */
+export function encodeOptions(value) {
+    return JSON.stringify(value).replace(/[^\u0020-\u007e]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+export function validateClassificationOptions(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    return (o.classifierId === imageClassifier.id &&
+        o.classifierVersion === imageClassifier.version &&
+        Array.isArray(o.labels) &&
+        o.labels.length >= 2 &&
+        o.labels.length <= imageClassifier.maxLabels &&
+        new Set(o.labels).size === o.labels.length &&
+        o.labels.every((label) => typeof label === "string" &&
+            label.length > 0 &&
+            label.length <= 80 &&
+            label === label.trim() &&
+            !/[\u0000-\u001f\u007f{}]/.test(label)));
+}
+//# sourceMappingURL=classification.js.map

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+export { imageClassifier, encodeOptions, validateClassificationOptions, type ClassificationOptions, type ClassificationResult, } from "./classification.js";
 export type Progress = {
     progress: number;
 };
@@ -9,6 +10,8 @@ export type ProcessingError = {
 };
 type ImageFormat = "avif" | "jpeg" | "png" | "webp" | "tiff" | "dz" | "ppm" | "fits" | "gif" | "svg" | "heif" | "pdf" | "jp2";
 export type ImageOptions = {
+    /** Extract a bounded embedded JPEG preview from a TIFF-based camera file; never demosaic RAW. */
+    embeddedPreview?: boolean;
     /** The rotation of the image. If not provided, the image will be auto-rotated, according to the EXIF data. To disable auto-rotation, set to `0`. */
     rotate?: number;
     /** Resizing options. */

package/lib/index.js

@@ -1,3 +1,4 @@
+export { imageClassifier, encodeOptions, validateClassificationOptions, } from "./classification.js";
 export class ProcessedFile {
     name;
     type;
@@ -13,7 +14,8 @@ export function isImageNoOp(opt, inputExt) {
     const outFmt = opt.format ?? opt.ext ?? "avif";
     if (outFmt !== inputExt)
         return false;
-    return (!opt.resize &&
+    return (!opt.embeddedPreview &&
+        !opt.resize &&
         !opt.crop &&
         opt.rotate == null &&
         opt.quality == null &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4k/common",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Common types and utilities for m4k",
   "license": "MIT",
   "author": "sv2dev",