@maravilla-labs/platform 0.15.0 → 0.16.0

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

@@ -151,6 +151,35 @@ interface ResizeOpts {
      * 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.
+ */
+interface SubjectBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
 }
 /** Options for `transforms.ocr`. */
 interface OcrOpts {
@@ -443,9 +472,71 @@ 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, 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}. */
+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;
+/**
+ * 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;
 };
 /**
  * Per-pattern transforms declaration used inside the `transforms` block of
@@ -500,4 +591,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, 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 };

package/package.json

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

package/src/transforms.ts

@@ -205,6 +205,36 @@ export interface ResizeOpts {
    * 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`. */
@@ -604,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) ──

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);
+  });
+});