@maravilla-labs/platform 0.15.0 → 0.17.0

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

@@ -151,6 +151,48 @@ interface ResizeOpts {
      * the Rust `ResizeOpts` exactly.
      */
     focal?: FocalPoint;
+    /**
+     * 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 | 'auto';
+    /**
+     * 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;
+}
+/**
+ * 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.
+ */
+interface SubjectBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
 }
 /** Options for `transforms.ocr`. */
 interface OcrOpts {
@@ -443,9 +485,92 @@ interface TransformsService {
  * `crates/platform/tests/derive_key_vectors.json`.
  */
 declare function keyFor(srcKey: string, spec: TransformSpec): string;
+/** Inputs for {@link focalCssFrame}. */
+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 — 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.
+     */
+    subject?: 'union' | 'primary';
+}
+/** CSS values produced by {@link focalCssFrame}. */
+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;
+}
+/**
+ * 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 })`.
+ */
+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
+ * `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`).
+ */
+declare function focalCssFrame(input: FocalCssFrameInput): FocalCssFrame;
 /** Convenience namespace mirroring the Rust `transforms::keyFor` re-export. */
 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
@@ -500,4 +625,4 @@ interface TransformsPatternSpec {
  */
 type TransformsConfig = Record<string, TransformsPatternSpec>;
 
-export { 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 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, transforms as y };
+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.15.0",
+  "version": "0.17.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/transforms.ts

@@ -205,6 +205,49 @@ export interface ResizeOpts {
    * the Rust `ResizeOpts` exactly.
    */
   focal?: FocalPoint;
+  /**
+   * 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 | 'auto';
+  /**
+   * 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;
+}
+
+/**
+ * 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`. */
@@ -604,9 +647,172 @@ 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 — 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.
+   */
+  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%"`. */
+  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 };
+}
+
+/**
+ * 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
+ * `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 { 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 };
+  if (!box || imgWidth <= 0 || imgHeight <= 0 || !(containerAspect > 0)) return base;
+
+  const iar = imgWidth / imgHeight; // source aspect
+  const car = containerAspect; // container aspect
+  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 (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
+  // 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,
+  primaryFaceBox,
 };
 
 // ── Declarative `transforms` config (consumed by the adapter compiler) ──

package/tests/focal-css.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest';
+
+import { focalCssFrame, unionFaceBox, primaryFaceBox, type FaceBox } from '../src/transforms.js';
+
+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', () => {
+    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);
+  });
+
+  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();
+  });
+});