@maravilla-labs/platform 0.16.0 → 0.17.0

package/dist/{transforms-DkAlUPu6.d.ts → transforms-C2zafn5k.d.ts}

@@ -152,21 +152,34 @@ interface ResizeOpts {
      */
     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.
+     * Face-box-relative crop zoom for `crop: 'focal'` — a scale factor
+     * (`0.4..=100.0`) or `'auto'`. A factor scales the smallest output-aspect
+     * frame around the (padded) subject: `1.0` = subject fills the frame; `> 1`
+     * pulls back for more context; `< 1` crops tighter, *into* the subject;
+     * large enough saturates to plain scale-to-cover. `'auto'` frames the subject
+     * to a comfortable, consistent occupancy. Only meaningful with `crop: 'focal'`
+     * on a source with stored face data (from `detectFaces`). Omit for the legacy
+     * point-only crop — unset it does not affect the derived key.
      */
-    zoom?: number;
+    zoom?: number | 'auto';
     /**
-     * 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.
+     * Extra margin around the subject box before framing, as a fraction of the
+     * box size added to every side (`0.15` = 15% breathing room). `crop: 'focal'`
+     * framing knob; default `0`. Like `zoom`, omitting it preserves the legacy key.
+     */
+    padding?: number;
+    /**
+     * Which detected face(s) to frame for `crop: 'focal'`: `'union'` (all faces,
+     * default — never clips a face) or `'primary'` (just the highest-confidence
+     * face, so a group photo can crop to one person). `'primary'` engages framing
+     * even without an explicit `zoom`.
+     */
+    subject?: 'union' | 'primary';
+    /**
+     * The resolved subject box (union or primary face), normalized `0..=1`.
+     * Server-injected (like {@link ResizeOpts.focal}) and only when the framing
+     * path is engaged — callers never pass this. Present so the wire type mirrors
+     * the Rust `ResizeOpts` exactly.
      */
     subject_box?: SubjectBox;
 }
@@ -488,11 +501,22 @@ interface FocalCssFrameInput {
     /** 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.
+     * Frame zoom — a factor or `'auto'`. `1` frames tightly around the face(s);
+     * `> 1` pulls back toward cover; `< 1` crops tighter, into the face; `'auto'`
+     * targets a comfortable occupancy. Defaults to `1`. Mirrors the server-side
+     * `resize({ crop: 'focal', zoom })` semantics.
+     */
+    zoom?: number | 'auto';
+    /**
+     * Extra margin around the subject box, fraction per side (`0.15` = 15%).
+     * Defaults to `0`. Mirrors the server `padding` knob.
+     */
+    padding?: number;
+    /**
+     * Frame the `'union'` of all faces (default) or just the `'primary'`
+     * (highest-confidence) face — for a group photo, crop to one person.
      */
-    zoom?: number;
+    subject?: 'union' | 'primary';
 }
 /** CSS values produced by {@link focalCssFrame}. */
 interface FocalCssFrame {
@@ -509,6 +533,15 @@ interface FocalCssFrame {
  * window; mirrors the server-side union used by `resize({ crop:'focal', zoom })`.
  */
 declare function unionFaceBox(faces?: FaceBox[] | null): SubjectBox | null;
+/**
+ * The primary (highest-confidence) face as a subject box plus a focal point
+ * centred on it (eye-line biased), clamped to `0..1`; `null` if none. Mirrors
+ * the server's `subject: 'primary'` — lets a group photo crop to one person.
+ */
+declare function primaryFaceBox(faces?: FaceBox[] | null): {
+    box: SubjectBox;
+    focal: FocalPoint;
+} | null;
 /**
  * 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
@@ -537,6 +570,7 @@ declare const transforms: {
     keyFor: typeof keyFor;
     focalCssFrame: typeof focalCssFrame;
     unionFaceBox: typeof unionFaceBox;
+    primaryFaceBox: typeof primaryFaceBox;
 };
 /**
  * Per-pattern transforms declaration used inside the `transforms` block of
@@ -591,4 +625,4 @@ interface TransformsPatternSpec {
  */
 type TransformsConfig = Record<string, TransformsPatternSpec>;
 
-export { unionFaceBox as A, focalCssFrame as B, transforms as C, type DetachAudioOpts as D, type ExtractFramesOpts as E, type FramesetManifest as F, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type SubjectBox as S, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type ExtractAudioOpts as d, type DetectFacesOpts as e, type FocalPoint as f, type FaceBox as g, type FocalPointRecord as h, type DocFormat as i, type DocToPdfOpts as j, type DocThumbnailOpts as k, type DocConvertOpts as l, type DocToMarkdownOpts as m, type DocToHtmlOpts as n, type ImageRef as o, type DocReplaceImagesOpts as p, type DocInsertQrCodeOpts as q, type QrPayload as r, type DocTemplateMergeOpts as s, type TransformSpec as t, type JobHandle as u, type JobStatusResponse as v, type TransformsService as w, keyFor as x, type FocalCssFrameInput as y, type FocalCssFrame as z };
+export { unionFaceBox as A, primaryFaceBox as B, focalCssFrame as C, type DetachAudioOpts as D, type ExtractFramesOpts as E, type FramesetManifest as F, transforms as G, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type SubjectBox as S, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type ExtractAudioOpts as d, type DetectFacesOpts as e, type FocalPoint as f, type FaceBox as g, type FocalPointRecord as h, type DocFormat as i, type DocToPdfOpts as j, type DocThumbnailOpts as k, type DocConvertOpts as l, type DocToMarkdownOpts as m, type DocToHtmlOpts as n, type ImageRef as o, type DocReplaceImagesOpts as p, type DocInsertQrCodeOpts as q, type QrPayload as r, type DocTemplateMergeOpts as s, type TransformSpec as t, type JobHandle as u, type JobStatusResponse as v, type TransformsService as w, keyFor as x, type FocalCssFrameInput as y, type FocalCssFrame as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/transforms.ts

@@ -206,21 +206,34 @@ export interface ResizeOpts {
    */
   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.
+   * Face-box-relative crop zoom for `crop: 'focal'` — a scale factor
+   * (`0.4..=100.0`) or `'auto'`. A factor scales the smallest output-aspect
+   * frame around the (padded) subject: `1.0` = subject fills the frame; `> 1`
+   * pulls back for more context; `< 1` crops tighter, *into* the subject;
+   * large enough saturates to plain scale-to-cover. `'auto'` frames the subject
+   * to a comfortable, consistent occupancy. Only meaningful with `crop: 'focal'`
+   * on a source with stored face data (from `detectFaces`). Omit for the legacy
+   * point-only crop — unset it does not affect the derived key.
    */
-  zoom?: number;
+  zoom?: number | 'auto';
   /**
-   * 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.
+   * Extra margin around the subject box before framing, as a fraction of the
+   * box size added to every side (`0.15` = 15% breathing room). `crop: 'focal'`
+   * framing knob; default `0`. Like `zoom`, omitting it preserves the legacy key.
+   */
+  padding?: number;
+  /**
+   * Which detected face(s) to frame for `crop: 'focal'`: `'union'` (all faces,
+   * default — never clips a face) or `'primary'` (just the highest-confidence
+   * face, so a group photo can crop to one person). `'primary'` engages framing
+   * even without an explicit `zoom`.
+   */
+  subject?: 'union' | 'primary';
+  /**
+   * The resolved subject box (union or primary face), normalized `0..=1`.
+   * Server-injected (like {@link ResizeOpts.focal}) and only when the framing
+   * path is engaged — callers never pass this. Present so the wire type mirrors
+   * the Rust `ResizeOpts` exactly.
    */
   subject_box?: SubjectBox;
 }
@@ -652,13 +665,27 @@ export interface FocalCssFrameInput {
   /** 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.
+   * Frame zoom — a factor or `'auto'`. `1` frames tightly around the face(s);
+   * `> 1` pulls back toward cover; `< 1` crops tighter, into the face; `'auto'`
+   * targets a comfortable occupancy. Defaults to `1`. Mirrors the server-side
+   * `resize({ crop: 'focal', zoom })` semantics.
    */
-  zoom?: number;
+  zoom?: number | 'auto';
+  /**
+   * Extra margin around the subject box, fraction per side (`0.15` = 15%).
+   * Defaults to `0`. Mirrors the server `padding` knob.
+   */
+  padding?: number;
+  /**
+   * Frame the `'union'` of all faces (default) or just the `'primary'`
+   * (highest-confidence) face — for a group photo, crop to one person.
+   */
+  subject?: 'union' | 'primary';
 }
 
+/** `zoom: 'auto'` as a factor — mirrors the Rust `AUTO_ZOOM` (subject ~82%). */
+const AUTO_ZOOM = 1.22;
+
 /** CSS values produced by {@link focalCssFrame}. */
 export interface FocalCssFrame {
   /** `object-position` value, e.g. `"44.0% 27.0%"`. */
@@ -698,6 +725,29 @@ export function unionFaceBox(faces?: FaceBox[] | null): SubjectBox | null {
   return { x: x0, y: y0, w, h };
 }
 
+/**
+ * The primary (highest-confidence) face as a subject box plus a focal point
+ * centred on it (eye-line biased), clamped to `0..1`; `null` if none. Mirrors
+ * the server's `subject: 'primary'` — lets a group photo crop to one person.
+ */
+export function primaryFaceBox(
+  faces?: FaceBox[] | null,
+): { box: SubjectBox; focal: FocalPoint } | null {
+  if (!faces || faces.length === 0) return null;
+  const f = faces.reduce((a, b) => (b.score > a.score ? b : a));
+  const x0 = clamp01(f.x);
+  const y0 = clamp01(f.y);
+  const x1 = clamp01(f.x + f.w);
+  const y1 = clamp01(f.y + f.h);
+  const w = x1 - x0;
+  const h = y1 - y0;
+  if (w <= 0 || h <= 0) return null;
+  return {
+    box: { x: x0, y: y0, w, h },
+    focal: { x: x0 + w / 2, y: clamp01(y0 + 0.4 * 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
@@ -721,21 +771,33 @@ export function unionFaceBox(faces?: FaceBox[] | null): SubjectBox | null {
  * 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 { faces, imgWidth, imgHeight, containerAspect } = input;
+
+  // Subject box (+ focal): primary face re-centres on that face; union keeps the
+  // supplied focal. Mirrors the server-side subject selection.
+  let box: SubjectBox | null;
+  let focal = input.focal;
+  if (input.subject === 'primary') {
+    const p = primaryFaceBox(faces);
+    box = p?.box ?? null;
+    if (p) focal = p.focal;
+  } else {
+    box = unionFaceBox(faces);
+  }
+
   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);
+  const z = input.zoom === 'auto' ? AUTO_ZOOM : Math.max(0.01, input.zoom ?? 1);
+  const grow = 1 + 2 * Math.max(0, input.padding ?? 0);
+  const bw = box.w * grow;
+  const bh = box.h * grow;
 
-  // 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 of the (padded) output-aspect frame, scaled by zoom.
+  const targetW = z * Math.max(bw, (bh * 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
@@ -750,6 +812,7 @@ export const transforms = {
   keyFor,
   focalCssFrame,
   unionFaceBox,
+  primaryFaceBox,
 };
 
 // ── Declarative `transforms` config (consumed by the adapter compiler) ──

package/tests/focal-css.test.ts

@@ -1,8 +1,14 @@
 import { describe, expect, it } from 'vitest';
 
-import { focalCssFrame, unionFaceBox, type FaceBox } from '../src/transforms.js';
+import { focalCssFrame, unionFaceBox, primaryFaceBox, type FaceBox } from '../src/transforms.js';
 
-const face = (x: number, y: number, w: number, h: number): FaceBox => ({ x, y, w, h, score: 0.9 });
+const face = (x: number, y: number, w: number, h: number, score = 0.9): FaceBox => ({
+  x,
+  y,
+  w,
+  h,
+  score,
+});
 
 describe('unionFaceBox', () => {
   it('is null for no faces', () => {
@@ -103,4 +109,48 @@ describe('focalCssFrame', () => {
     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);
   });
+
+  const sq = { focal: { x: 0.5, y: 0.5 }, faces, imgWidth: 200, imgHeight: 200, containerAspect: 1 };
+
+  it('zoom < 1 crops tighter (larger scale than zoom=1)', () => {
+    const one = focalCssFrame({ ...sq, zoom: 1 }).scale;
+    const tight = focalCssFrame({ ...sq, zoom: 0.5 }).scale;
+    expect(tight).toBeCloseTo(one * 2, 3); // 0.2 face, zoom 0.5 → scale 10 vs 5
+  });
+
+  it("zoom 'auto' sits between tight and cover", () => {
+    const auto = focalCssFrame({ ...sq, zoom: 'auto' }).scale;
+    const one = focalCssFrame({ ...sq, zoom: 1 }).scale;
+    // auto ≈ 1/1.22 of the zoom=1 tightness (a touch pulled back), still > 1.
+    expect(auto).toBeCloseTo(one / 1.22, 3);
+    expect(auto).toBeGreaterThan(1);
+  });
+
+  it('padding pulls back (smaller scale than no padding)', () => {
+    const none = focalCssFrame({ ...sq, zoom: 1 }).scale;
+    const padded = focalCssFrame({ ...sq, zoom: 1, padding: 0.5 }).scale;
+    expect(padded).toBeCloseTo(none / 2, 3); // box ×2 → half the scale
+  });
+
+  it("subject 'primary' frames the main face, not the union", () => {
+    const two = [face(0.05, 0.05, 0.1, 0.1, 0.6), face(0.6, 0.4, 0.2, 0.2, 0.95)];
+    const union = focalCssFrame({ focal: { x: 0.4, y: 0.3 }, faces: two, imgWidth: 200, imgHeight: 200, containerAspect: 1, zoom: 1 });
+    const primary = focalCssFrame({ focal: { x: 0.4, y: 0.3 }, faces: two, imgWidth: 200, imgHeight: 200, containerAspect: 1, zoom: 1, subject: 'primary' });
+    // Primary re-centres on the high-score face (x≈0.7) and frames a smaller box
+    // → different object-position and a tighter scale than the wide union.
+    expect(primary.objectPosition).not.toBe(union.objectPosition);
+    expect(primary.scale).toBeGreaterThan(union.scale);
+  });
+});
+
+describe('primaryFaceBox', () => {
+  it('picks the highest-score face and eye-line focal', () => {
+    const p = primaryFaceBox([face(0.05, 0.05, 0.1, 0.1, 0.6), face(0.6, 0.2, 0.2, 0.3, 0.95)])!;
+    expect(p.box.x).toBeCloseTo(0.6);
+    expect(p.focal.x).toBeCloseTo(0.7);
+    expect(p.focal.y).toBeCloseTo(0.2 + 0.4 * 0.3);
+  });
+  it('is null without faces', () => {
+    expect(primaryFaceBox([])).toBeNull();
+  });
 });