@maravilla-labs/platform 0.14.0 → 0.16.0

package/src/transforms.ts

@@ -187,6 +187,54 @@ export interface ResizeOpts {
   format: ImageFormat;
   quality?: number;
   strip_metadata?: boolean;
+  /**
+   * Crop strategy when BOTH `width` and `height` are given (the output is
+   * cropped to fill the exact box rather than letterboxed):
+   * - `'center'` — crop around the geometric center.
+   * - `'focal'` — crop around the source's focal point. The server injects
+   *   the focal point from the persisted {@link FocalPointRecord} (set via
+   *   `detectFaces` or `setFocalPoint`); if none exists it falls back to
+   *   center.
+   * Omit for the default aspect-preserving fit (no crop).
+   */
+  crop?: 'focal' | 'center';
+  /**
+   * Explicit focal point for `crop: 'focal'`, normalized `0..=1`. Server-
+   * injected — callers normally omit this and let the platform resolve the
+   * stored focal point for `src_key`. Present here so the wire type mirrors
+   * the Rust `ResizeOpts` exactly.
+   */
+  focal?: FocalPoint;
+  /**
+   * Face-box-relative crop zoom for `crop: 'focal'`. A scale factor (`>= 1.0`)
+   * on the smallest output-aspect frame that fully contains the source's
+   * detected face(s): `1.0` frames tightly around the subject; larger values
+   * pull back for more headroom/context; a value large enough to exceed the
+   * image saturates to the plain scale-to-cover crop. Only meaningful with
+   * `crop: 'focal'` on a source that has stored face data (from `detectFaces`);
+   * ignored otherwise. Omit for the legacy point-only crop — when unset it does
+   * not affect the derived key, so existing crops are unchanged.
+   */
+  zoom?: number;
+  /**
+   * Union bounding box of the source's detected faces, normalized `0..=1`.
+   * Server-injected (like {@link ResizeOpts.focal}) and only when `zoom` is set
+   * — callers never pass this. Present so the wire type mirrors the Rust
+   * `ResizeOpts` exactly.
+   */
+  subject_box?: SubjectBox;
+}
+
+/**
+ * Union bounding box of a source's detected faces, normalized `0..=1`
+ * (top-left `x`/`y` + `w`/`h`). Sizes the `crop: 'focal'` {@link
+ * ResizeOpts.zoom} window; server-injected only.
+ */
+export interface SubjectBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
 }
 
 /** Options for `transforms.ocr`. */
@@ -195,6 +243,60 @@ export interface OcrOpts {
   lang?: string;
 }
 
+/**
+ * Options for `transforms.detectFaces` — run face detection over an image and
+ * persist the resulting focal point (the center of the highest-scoring face,
+ * or the centroid of all faces) as a {@link FocalPointRecord} keyed on the
+ * source. The derived output is a JSON artifact listing the detected boxes.
+ */
+export interface DetectFacesOpts {
+  /** Minimum detector confidence to keep a face, `0..=1`. Defaults to `0.6` server-side. */
+  min_score?: number;
+  /** Cap on the number of faces retained (highest-scoring first). Defaults to `32` server-side. */
+  max_faces?: number;
+  /** Trade accuracy for latency (smaller detector input). Defaults to `false` server-side. */
+  fast?: boolean;
+}
+
+/** A focal point in normalized image coordinates, each component `0..=1`. */
+export interface FocalPoint {
+  x: number;
+  y: number;
+}
+
+/** A single detected face box, normalized to `0..1` of the image dimensions. */
+export interface FaceBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** Detector confidence, `0..1`. */
+  score: number;
+}
+
+/**
+ * Persisted focal-point record for a source image — the result of
+ * `detectFaces` or a manual `setFocalPoint`. Returned by `getFocalPoint`.
+ */
+export interface FocalPointRecord {
+  /** Storage key of the source image this focal point belongs to. */
+  src_key: string;
+  /** The resolved focal point, normalized `0..=1`. */
+  focal: FocalPoint;
+  /** Whether the point came from face detection or a manual override. */
+  source: 'faces' | 'manual';
+  /** Number of faces detected (`null` until a detection has run for this key). */
+  face_count: number | null;
+  /** The detected face boxes, when `source === 'faces'`. */
+  faces?: FaceBox[];
+  /** Content hash of the source bytes the detection ran against. */
+  src_hash?: string;
+  /** Version tag of the detector that produced this record. */
+  detector_version?: string;
+  /** Unix-epoch milliseconds the record was last written. */
+  updated_at: number;
+}
+
 /**
  * LibreOffice-supported output container for `doc_convert`. Each value
  * maps to a `--convert-to` filter and a derived-key extension.
@@ -326,6 +428,7 @@ export type TransformSpec =
   | ({ kind: 'extract_frames' } & ExtractFramesOpts)
   | ({ kind: 'extract_audio' } & ExtractAudioOpts)
   | ({ kind: 'resize' } & ResizeOpts)
+  | ({ kind: 'detect_faces' } & DetectFacesOpts)
   | ({ kind: 'ocr' } & OcrOpts)
   | ({ kind: 'doc_to_pdf' } & DocToPdfOpts)
   | ({ kind: 'doc_thumbnail' } & DocThumbnailOpts)
@@ -380,6 +483,30 @@ export interface TransformsService {
   resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
   probe(srcKey: string): Promise<MediaInfo>;
   ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
+  /**
+   * Run face detection over an image and persist the resulting focal point as
+   * a {@link FocalPointRecord}. Resolves to a `JobHandle` whose `output_key`
+   * holds a JSON artifact of the detected {@link FaceBox | boxes} once
+   * complete. Subsequent `resize` calls with `crop: 'focal'` on the same
+   * source pick up the stored focal point automatically.
+   */
+  detectFaces(srcKey: string, opts?: DetectFacesOpts | null): Promise<JobHandle>;
+  /**
+   * Manually set (or override) the focal point for a source image, normalized
+   * `0..=1`. Persists a {@link FocalPointRecord} with `source: 'manual'`.
+   * Resolves to `null`.
+   */
+  setFocalPoint(srcKey: string, point: FocalPoint): Promise<null>;
+  /**
+   * Read the persisted {@link FocalPointRecord} for a source, or `null` when
+   * none has been set (neither `detectFaces` nor `setFocalPoint` has run).
+   */
+  getFocalPoint(srcKey: string): Promise<FocalPointRecord | null>;
+  /**
+   * Remove the persisted focal point for a source. Resolves to `true` when a
+   * record was deleted, `false` when there was nothing to clear.
+   */
+  clearFocalPoint(srcKey: string): Promise<boolean>;
   /** Convert a LibreOffice-supported document to PDF. */
   docToPdf(srcKey: string, opts?: DocToPdfOpts | null): Promise<JobHandle>;
   /** Render a single page of a document as a raster thumbnail. */
@@ -452,6 +579,9 @@ function outputExtension(spec: TransformSpec): string {
       const fmt = (spec as { format?: ImageFormat }).format ?? 'jpg';
       return fmt;
     }
+    case 'detect_faces':
+      // Output key is the JSON artifact listing the detected face boxes.
+      return 'json';
     case 'ocr':
       return 'txt';
     case 'doc_to_pdf':
@@ -504,9 +634,122 @@ export function keyFor(srcKey: string, spec: TransformSpec): string {
   return `__derived/${srcHash}/${variantHash}.${ext}`;
 }
 
+// ── CSS-only focal framing (isomorphic, framework-agnostic) ───────────────
+
+/** Inputs for {@link focalCssFrame}. */
+export interface FocalCssFrameInput {
+  /** The source's focal point (from `detectFaces`/`getFocalPoint` or manual). */
+  focal: FocalPoint;
+  /** Detected face boxes (from the same record). Empty/absent → plain cover. */
+  faces?: FaceBox[] | null;
+  /**
+   * Source image intrinsic pixel dimensions — only their ratio is used. In the
+   * browser these are free from a loaded `<img>` (`naturalWidth`/`Height`);
+   * `detectFaces`' output artifact also carries them.
+   */
+  imgWidth: number;
+  imgHeight: number;
+  /** Target container aspect ratio, `width / height`. */
+  containerAspect: number;
+  /**
+   * Frame zoom, clamped to `>= 1`. `1` frames tightly around the face(s); larger
+   * pulls back toward the plain cover view. Defaults to `1`. Mirrors the
+   * server-side `resize({ crop: 'focal', zoom })` semantics.
+   */
+  zoom?: number;
+}
+
+/** CSS values produced by {@link focalCssFrame}. */
+export interface FocalCssFrame {
+  /** `object-position` value, e.g. `"44.0% 27.0%"`. */
+  objectPosition: string;
+  /** `transform: scale(...)` factor to apply on top of `object-fit: cover`. */
+  scale: number;
+  /** `transform-origin` — same anchor as `objectPosition`. */
+  transformOrigin: string;
+}
+
+const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+
+/**
+ * Union bounding box of detected faces, clamped to `0..1`; `null` for an empty
+ * list or a degenerate (zero-area) union. Sizes the {@link focalCssFrame} zoom
+ * window; mirrors the server-side union used by `resize({ crop:'focal', zoom })`.
+ */
+export function unionFaceBox(faces?: FaceBox[] | null): SubjectBox | null {
+  if (!faces || faces.length === 0) return null;
+  let x0 = Infinity,
+    y0 = Infinity,
+    x1 = -Infinity,
+    y1 = -Infinity;
+  for (const f of faces) {
+    x0 = Math.min(x0, f.x);
+    y0 = Math.min(y0, f.y);
+    x1 = Math.max(x1, f.x + f.w);
+    y1 = Math.max(y1, f.y + f.h);
+  }
+  x0 = clamp01(x0);
+  y0 = clamp01(y0);
+  x1 = clamp01(x1);
+  y1 = clamp01(y1);
+  const w = x1 - x0;
+  const h = y1 - y0;
+  if (w <= 0 || h <= 0) return null;
+  return { x: x0, y: y0, w, h };
+}
+
+/**
+ * Compute CSS values that frame a source image on its detected face(s) for a
+ * container of ANY aspect ratio — the browser-side counterpart to the server's
+ * `resize({ crop: 'focal', zoom })`. Instead of a pre-rendered crop per shape,
+ * apply the result to a single `<img>`:
+ *
+ * ```html
+ * <div style="aspect-ratio: 3/1; overflow: hidden">
+ *   <img
+ *     style="width:100%; height:100%; object-fit:cover;
+ *            object-position: {objectPosition}; transform-origin: {transformOrigin};
+ *            transform: scale({scale})" />
+ * </div>
+ * ```
+ *
+ * `object-position` pans the cover image onto the focal point; the extra
+ * `transform: scale` tightens the frame around the face(s) per `zoom`, scaling
+ * about the same anchor so the face stays put. Framework-agnostic: it returns
+ * plain CSS values — apply them however your framework applies styles.
+ *
+ * With no detected faces it degrades to a plain focal-point cover (`scale: 1`).
+ */
+export function focalCssFrame(input: FocalCssFrameInput): FocalCssFrame {
+  const { focal, faces, imgWidth, imgHeight, containerAspect } = input;
+  const zoom = input.zoom ?? 1;
+  const objectPosition = `${(clamp01(focal.x) * 100).toFixed(1)}% ${(clamp01(focal.y) * 100).toFixed(1)}%`;
+  const base: FocalCssFrame = { objectPosition, scale: 1, transformOrigin: objectPosition };
+
+  const box = unionFaceBox(faces);
+  if (!box || imgWidth <= 0 || imgHeight <= 0 || !(containerAspect > 0)) return base;
+
+  const iar = imgWidth / imgHeight; // source aspect
+  const car = containerAspect; // container aspect
+  const z = Math.max(1, zoom);
+
+  // Normalized width of the tight, output-aspect frame around the face(s),
+  // scaled by zoom. (Collapses to depend only on the aspect ratios.)
+  const targetW = z * Math.max(box.w, (box.h * car) / iar);
+  // Normalized width the browser's own `object-fit: cover` already shows.
+  const coverW = car >= iar ? 1 : car / iar;
+  // Extra scale to tighten from cover to the target window; floored at 1 (can't
+  // show more than cover) — the saturation floor matching the server crop.
+  const scale = Math.max(1, coverW / targetW);
+
+  return { objectPosition, scale: Math.round(scale * 1000) / 1000, transformOrigin: objectPosition };
+}
+
 /** Convenience namespace mirroring the Rust `transforms::keyFor` re-export. */
 export const transforms = {
   keyFor,
+  focalCssFrame,
+  unionFaceBox,
 };
 
 // ── Declarative `transforms` config (consumed by the adapter compiler) ──
@@ -533,6 +776,12 @@ export interface TransformsPatternSpec {
   /** Sugar for `resize` arrays — same shape, same semantics. */
   variants?: ResizeOpts[];
   ocr?: OcrOpts | OcrOpts[];
+  /**
+   * Run face detection on matching uploads and persist a focal point so
+   * `resize`/`variants` entries with `crop: 'focal'` crop around faces. Pass
+   * `true` for detector defaults, or an object to tune the detection.
+   */
+  detectFaces?: boolean | { min_score?: number; max_faces?: number; fast?: boolean };
 }
 
 /**

package/src/types.ts

@@ -206,37 +206,46 @@ export interface Database {
 
   /**
    * Update a single document in a collection.
-   * 
+   *
    * @param collection - The collection name
    * @param filter - Query filter to match the document to update
    * @param update - Update operations (MongoDB-style with $set, $inc, etc.)
-   * @returns Promise that resolves to an object with the number of modified documents
-   * 
+   * @returns Promise that resolves to real matched/modified counts — `modified`
+   *   is 0 when the filter matched nothing, so a conditional filter plus an
+   *   atomic operator is safe for enforcement (quotas, redemption caps, seats)
+   *
    * @example
    * ```typescript
-   * const result = await db.updateOne('users',
-   *   { email: 'john@example.com' },
-   *   { $set: { lastLogin: new Date() }, $inc: { loginCount: 1 } }
+   * // Atomic redemption-cap enforcement: only one of N concurrent checkouts
+   * // can win each remaining slot — no read-then-act needed.
+   * const result = await db.updateOne('discount_codes',
+   *   { id, redeemedCount: { $lt: maxRedemptions } },
+   *   { $inc: { redeemedCount: 1 } }
    * );
-   * console.log(`Modified ${result.modified} documents`);
+   * if (result.modified === 0) throw new Error('code exhausted');
    * ```
    */
-  updateOne(collection: string, filter: any, update: any): Promise<{ modified: number }>;
+  updateOne(
+    collection: string,
+    filter: any,
+    update: any,
+  ): Promise<{ modified: number; matched: number; matchedCount: number; modifiedCount: number }>;
 
   /**
    * Delete a single document from a collection.
-   * 
+   *
    * @param collection - The collection name
    * @param filter - Query filter to match the document to delete
-   * @returns Promise that resolves to an object with the number of deleted documents
-   * 
+   * @returns Promise that resolves to the real number of deleted documents
+   *   (0 when the filter matched nothing)
+   *
    * @example
    * ```typescript
    * const result = await db.deleteOne('posts', { _id: postId });
    * console.log(`Deleted ${result.deleted} documents`);
    * ```
    */
-  deleteOne(collection: string, filter: any): Promise<{ deleted: number }>;
+  deleteOne(collection: string, filter: any): Promise<{ deleted: number; deletedCount: number }>;
 
   /**
    * Delete multiple documents from a collection.

package/tests/focal-css.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+
+import { focalCssFrame, unionFaceBox, type FaceBox } from '../src/transforms.js';
+
+const face = (x: number, y: number, w: number, h: number): FaceBox => ({ x, y, w, h, score: 0.9 });
+
+describe('unionFaceBox', () => {
+  it('is null for no faces', () => {
+    expect(unionFaceBox([])).toBeNull();
+    expect(unionFaceBox(null)).toBeNull();
+    expect(unionFaceBox(undefined)).toBeNull();
+  });
+
+  it('returns the single face', () => {
+    const b = unionFaceBox([face(0.3, 0.2, 0.1, 0.15)])!;
+    expect(b.x).toBeCloseTo(0.3);
+    expect(b.y).toBeCloseTo(0.2);
+    expect(b.w).toBeCloseTo(0.1);
+    expect(b.h).toBeCloseTo(0.15);
+  });
+
+  it('covers disjoint faces', () => {
+    const b = unionFaceBox([face(0.1, 0.1, 0.1, 0.1), face(0.7, 0.6, 0.1, 0.2)])!;
+    expect(b.x).toBeCloseTo(0.1);
+    expect(b.y).toBeCloseTo(0.1);
+    expect(b.x + b.w).toBeCloseTo(0.8);
+    expect(b.y + b.h).toBeCloseTo(0.8);
+  });
+
+  it('clamps out-of-range coordinates to 0..1', () => {
+    const b = unionFaceBox([face(-0.1, -0.2, 0.4, 0.5)])!;
+    expect(b.x).toBe(0);
+    expect(b.y).toBe(0);
+    expect(b.x + b.w).toBeLessThanOrEqual(1);
+    expect(b.y + b.h).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('focalCssFrame', () => {
+  const faces = [face(0.4, 0.4, 0.2, 0.2)];
+
+  it('anchors object-position on the focal point', () => {
+    const f = focalCssFrame({
+      focal: { x: 0.44, y: 0.27 },
+      faces,
+      imgWidth: 200,
+      imgHeight: 200,
+      containerAspect: 1,
+      zoom: 1,
+    });
+    expect(f.objectPosition).toBe('44.0% 27.0%');
+    expect(f.transformOrigin).toBe(f.objectPosition);
+  });
+
+  it('zoom=1 tightly frames the face (scale > 1)', () => {
+    const f = focalCssFrame({
+      focal: { x: 0.5, y: 0.5 },
+      faces,
+      imgWidth: 200,
+      imgHeight: 200,
+      containerAspect: 1,
+      zoom: 1,
+    });
+    // 0.2-wide face in a square container → scale 1/0.2 = 5.
+    expect(f.scale).toBeCloseTo(5, 3);
+  });
+
+  it('zoom pulls back linearly then saturates to cover (scale 1)', () => {
+    const at = (zoom: number) =>
+      focalCssFrame({ focal: { x: 0.5, y: 0.5 }, faces, imgWidth: 200, imgHeight: 200, containerAspect: 1, zoom }).scale;
+    expect(at(2)).toBeCloseTo(2.5, 3); // half the zoom=1 tightness
+    expect(at(100)).toBe(1); // saturates to plain cover
+  });
+
+  it('accounts for source aspect ratio (wide image, square container)', () => {
+    // 400x200 source (iar 2), square container: cover already shows half the
+    // width, so a 0.2-wide face needs scale 0.5/0.2 = 2.5, not 5.
+    const f = focalCssFrame({
+      focal: { x: 0.5, y: 0.5 },
+      faces,
+      imgWidth: 400,
+      imgHeight: 200,
+      containerAspect: 1,
+      zoom: 1,
+    });
+    expect(f.scale).toBeCloseTo(2.5, 3);
+  });
+
+  it('degrades to plain cover (scale 1) with no faces', () => {
+    const f = focalCssFrame({
+      focal: { x: 0.5, y: 0.5 },
+      faces: [],
+      imgWidth: 200,
+      imgHeight: 200,
+      containerAspect: 1.5,
+      zoom: 1,
+    });
+    expect(f.scale).toBe(1);
+  });
+
+  it('defaults zoom to 1 when omitted', () => {
+    const withDefault = focalCssFrame({ focal: { x: 0.5, y: 0.5 }, faces, imgWidth: 200, imgHeight: 200, containerAspect: 1 });
+    const explicit = focalCssFrame({ focal: { x: 0.5, y: 0.5 }, faces, imgWidth: 200, imgHeight: 200, containerAspect: 1, zoom: 1 });
+    expect(withDefault.scale).toBe(explicit.scale);
+  });
+});