@maravilla-labs/platform 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @maravilla-labs/platform
 
+## 0.17.0
+
+### Minor Changes
+
+- 16d4f8d: Extend `resize({ crop: 'focal' })` framing with three more opt-in knobs (on top
+  of the initial `zoom` factor):
+  - **`zoom`** now also accepts values `< 1` (crop _into_ the subject) and
+    `'auto'` (a curated, consistent occupancy); range is `0.4..=100.0` | `'auto'`.
+  - **`padding`** — margin around the subject box (`0.0..=2.0`, fraction per side)
+    so a tight crop keeps breathing room around the head.
+  - **`subject`** — `'union'` (all faces, default) or `'primary'` (the
+    highest-confidence face, re-centred on it), so a group photo can crop to one
+    person.
+
+  Still fully backward compatible: the new fields never serialize when omitted, so
+  existing derived keys are byte-identical. The SDK CSS helpers gain the same
+  knobs plus a new `primaryFaceBox()` for parity.
+
+## 0.16.0
+
+### Minor Changes
+
+- 4b6b127: Add a `zoom` option to `resize({ crop: 'focal' })` for face-box-relative crop
+  framing. Until now a focal crop only centered a fixed-size window on the stored
+  focal _point_ — the detected face's bounding-box size was discarded, so there
+  was no way to control how tightly the subject was framed. `zoom` (a scale
+  factor, `1.0..=100.0`) now sizes the crop window from the union of the source's
+  detected faces: `1.0` frames tightly (a headshot), larger pulls back for
+  headroom/context, and a value large enough to exceed the image saturates to the
+  plain scale-to-cover crop. It's declarable in the `maravilla.config.ts`
+  `transforms` block too.
+
+  Fully backward compatible: `zoom` is optional and never serializes when omitted,
+  so every existing focal/center crop hashes to the same derived key and is
+  byte-identical. `zoom` is only honoured for `crop: 'focal'` on a source that has
+  stored face data (run `detectFaces` first); it's ignored for `crop: 'center'`
+  and a no-op when no faces were detected.
+
+  Also adds two pure, isomorphic, framework-agnostic helpers to
+  `@maravilla-labs/platform` — `focalCssFrame()` and `unionFaceBox()` — the
+  browser-side counterpart to the server crop: they turn a source's focal
+  point + detected faces into `object-position` + `transform: scale` CSS values,
+  so one `<img>` can re-frame around the face(s) for any container aspect ratio
+  and zoom without a server round-trip or a pre-rendered crop per shape.
+
 ## 0.15.0
 
 ### Minor Changes

package/dist/config.d.ts

@@ -1,5 +1,5 @@
-import { T as TransformsConfig } from './transforms-BPrlJoYd.js';
-export { a as TransformsPatternSpec } from './transforms-BPrlJoYd.js';
+import { T as TransformsConfig } from './transforms-C2zafn5k.js';
+export { a as TransformsPatternSpec } from './transforms-C2zafn5k.js';
 
 /**
  * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { ActAsContext, AddCircleMemberOptions, AddRelationOptions, ApiKeyInfo, A
 export { b as RenClient, a as RenClientOptions, R as RenEvent, g as getOrCreateClientId, r as renFetch, c as storageDelete, s as storageUpload } from './ren-DetHRhCL.js';
 import { LocalParticipant } from 'livekit-client';
 export { RegisterPushOptions, RegisterPushResult, offsetBefore, registerPush, unregisterPush } from './push.js';
-export { D as DetachAudioOpts, e as DetectFacesOpts, l as DocConvertOpts, i as DocFormat, q as DocInsertQrCodeOpts, p as DocReplaceImagesOpts, s as DocTemplateMergeOpts, k as DocThumbnailOpts, n as DocToHtmlOpts, m as DocToMarkdownOpts, j as DocToPdfOpts, d as ExtractAudioOpts, E as ExtractFramesOpts, g as FaceBox, f as FocalPoint, h as FocalPointRecord, F as FramesetManifest, I as ImageFormat, o as ImageRef, u as JobHandle, J as JobStatus, v as JobStatusResponse, M as MediaInfo, O as OcrOpts, Q as QrCodeSpec, r as QrPayload, R as ResizeOpts, c as ThumbnailOpts, b as TranscodeOpts, t as TransformSpec, T as TransformsConfig, a as TransformsPatternSpec, w as TransformsService, V as VideoFormat, x as keyFor, y as transforms } from './transforms-BPrlJoYd.js';
+export { D as DetachAudioOpts, e as DetectFacesOpts, l as DocConvertOpts, i as DocFormat, q as DocInsertQrCodeOpts, p as DocReplaceImagesOpts, s as DocTemplateMergeOpts, k as DocThumbnailOpts, n as DocToHtmlOpts, m as DocToMarkdownOpts, j as DocToPdfOpts, d as ExtractAudioOpts, E as ExtractFramesOpts, g as FaceBox, z as FocalCssFrame, y as FocalCssFrameInput, f as FocalPoint, h as FocalPointRecord, F as FramesetManifest, I as ImageFormat, o as ImageRef, u as JobHandle, J as JobStatus, v as JobStatusResponse, M as MediaInfo, O as OcrOpts, Q as QrCodeSpec, r as QrPayload, R as ResizeOpts, S as SubjectBox, c as ThumbnailOpts, b as TranscodeOpts, t as TransformSpec, T as TransformsConfig, a as TransformsPatternSpec, w as TransformsService, V as VideoFormat, C as focalCssFrame, x as keyFor, B as primaryFaceBox, G as transforms, A as unionFaceBox } from './transforms-C2zafn5k.js';
 
 /**
  * Media service for video/audio room management.

package/dist/index.js

@@ -2096,8 +2096,71 @@ function keyFor(srcKey, spec) {
   const ext = outputExtension(spec);
   return `__derived/${srcHash}/${variantHash}.${ext}`;
 }
+var AUTO_ZOOM = 1.22;
+var clamp01 = (n) => Math.min(1, Math.max(0, n));
+function unionFaceBox(faces) {
+  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 };
+}
+function primaryFaceBox(faces) {
+  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) }
+  };
+}
+function focalCssFrame(input) {
+  const { faces, imgWidth, imgHeight, containerAspect } = input;
+  let box;
+  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 = { objectPosition, scale: 1, transformOrigin: objectPosition };
+  if (!box || imgWidth <= 0 || imgHeight <= 0 || !(containerAspect > 0)) return base;
+  const iar = imgWidth / imgHeight;
+  const car = containerAspect;
+  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;
+  const targetW = z * Math.max(bw, bh * car / iar);
+  const coverW = car >= iar ? 1 : car / iar;
+  const scale = Math.max(1, coverW / targetW);
+  return { objectPosition, scale: Math.round(scale * 1e3) / 1e3, transformOrigin: objectPosition };
+}
 var transforms = {
-  keyFor
+  keyFor,
+  focalCssFrame,
+  unionFaceBox,
+  primaryFaceBox
 };
 
 // src/index.ts
@@ -2144,17 +2207,20 @@ export {
   attachTrack,
   clearPlatformCache,
   detachTrack,
+  focalCssFrame,
   getCurrentRequestStore,
   getOrCreateClientId,
   getPlatform,
   keyFor,
   offsetBefore,
+  primaryFaceBox,
   registerPush,
   renFetch,
   runWithRequest,
   storageDelete,
   storageUpload,
   transforms,
+  unionFaceBox,
   unregisterPush
 };
 //# sourceMappingURL=index.js.map