@bluepic/embed 0.4.0-next.90 → 0.4.0-next.91

package/dist/util/autoCrop/applyAutoCrop.d.ts

@@ -0,0 +1,20 @@
+import type { Template } from '@bluepic/types';
+export type ApplyAutoCropOptions = {
+    src: string;
+    /** Natural dimensions as the field already resolved them. */
+    natural: {
+        width: number;
+        height: number;
+    };
+    aspectRatio: number;
+    cropMode: Template.ImageValue['cropMode'];
+};
+/**
+ * Full auto-crop pass for one image: load → detect → solve.
+ *
+ * Returns `null` for every "can't help here" case — no detector registered,
+ * image unreachable or not CORS-readable, no faces found, nothing worth
+ * proposing. Callers treat `null` as "keep the existing behaviour" and must
+ * not surface an error.
+ */
+export declare function applyAutoCrop(opts: ApplyAutoCropOptions): Promise<Template.Crop | null>;

package/dist/util/autoCrop/index.d.ts

@@ -0,0 +1,5 @@
+export type { FaceBox, FaceDetector } from './types';
+export { solveAutoCrop, MIN_FACE_SCORE, FACE_VERTICAL_ANCHOR } from './solveAutoCrop';
+export type { SolveAutoCropOptions } from './solveAutoCrop';
+export { setFaceDetector, hasFaceDetector, detectFacesSafe } from './registry';
+export { applyAutoCrop } from './applyAutoCrop';

package/dist/util/autoCrop/registry.d.ts

@@ -0,0 +1,12 @@
+import type { FaceDetector, FaceBox } from './types';
+export declare function setFaceDetector(next: FaceDetector | null): void;
+export declare function hasFaceDetector(): boolean;
+/**
+ * Run the registered detector, swallowing every failure.
+ *
+ * The `FaceDetector` contract already says "never throw", but this is the
+ * boundary between our code and a host-supplied function — so we enforce it
+ * here rather than trusting it. A rejected promise from a third-party
+ * detector must not be able to break an image upload.
+ */
+export declare function detectFacesSafe(source: ImageBitmap | HTMLImageElement | HTMLCanvasElement): Promise<FaceBox[]>;

package/dist/util/autoCrop/solveAutoCrop.d.ts

@@ -0,0 +1,39 @@
+import type { Template } from '@bluepic/types';
+import type { FaceBox } from './types';
+/**
+ * Faces below this confidence are ignored. Deliberately strict: a false
+ * positive silently reframes the user's image around a non-face, which is
+ * worse than not suggesting anything at all.
+ */
+export declare const MIN_FACE_SCORE = 0.6;
+/**
+ * Where the face centre should sit vertically inside the crop, as a fraction
+ * of crop height. 0.5 is dead centre and reads as "passport photo"; the rule
+ * of thirds puts eyes near the upper third, and ~0.4 for the face *centre*
+ * approximates that while staying safe for group shots.
+ */
+export declare const FACE_VERTICAL_ANCHOR = 0.4;
+export type SolveAutoCropOptions = {
+    faces: FaceBox[];
+    /** Natural (unscaled) image dimensions in pixels. */
+    natural: {
+        width: number;
+        height: number;
+    };
+    /** Target aspect ratio of the field (width / height). */
+    aspectRatio: number;
+    cropMode: Template.ImageValue['cropMode'];
+};
+/**
+ * Propose a crop rectangle that frames the detected faces.
+ *
+ * Returns `null` whenever there is nothing sensible to propose — no faces, a
+ * degenerate input, or a crop mode where cropping isn't what happens. `null`
+ * means "leave the existing default alone", never "error".
+ *
+ * The geometry mirrors what `cover` already does: the crop is the largest
+ * rectangle of the target ratio that fits inside the image (so no pixels are
+ * wasted), slid so the faces are well framed. It never zooms in — cropping
+ * tighter than necessary would throw away resolution the renderer wants.
+ */
+export declare function solveAutoCrop(opts: SolveAutoCropOptions): Template.Crop | null;

package/dist/util/autoCrop/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Face-detection contract for auto-crop.
+ *
+ * The embed deliberately ships NO detector implementation. It builds as a
+ * single-file IIFE/UMD bundle (see vite.config.ts `formats`), so a bundled
+ * onnxruntime-web would be inlined and shipped to every consumer whether or
+ * not they use auto-crop. The host app — which has real code-splitting —
+ * owns the runtime and registers it via `setFaceDetector`.
+ *
+ * That split also keeps the EU story intact: bx-template serves its own lazy
+ * chunk from template.bluepic.eu, so no CDN is involved.
+ */
+/** A detected face, in natural image pixels, origin top-left. */
+export type FaceBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Detector confidence, 0..1. */
+    score: number;
+};
+/**
+ * Detects faces in an already-decoded image.
+ *
+ * Contract: must NEVER throw. Auto-crop is a convenience — a missing model,
+ * a WASM failure or a tainted canvas must degrade to "no suggestion", not to
+ * a failed upload. Return `[]` in all of those cases.
+ */
+export type FaceDetector = (source: ImageBitmap | HTMLImageElement | HTMLCanvasElement) => Promise<FaceBox[]>;

package/dist/util/backgroundRemoval.d.ts

@@ -0,0 +1,51 @@
+import { type FieldsBridge } from '@bluepic/types';
+/**
+ * The transform that performs background removal.
+ *
+ * `format: 'png'` is not optional dressing: `segment=foreground` writes
+ * transparent pixels, and without an alpha-capable output format Cloudflare
+ * flattens them — you'd pay for the transformation and get the original back.
+ */
+export declare const BACKGROUND_REMOVAL_TRANSFORM: {
+    readonly segment: "foreground";
+    readonly format: "png";
+};
+/**
+ * Whether the host can actually perform Cloudflare Images transforms.
+ *
+ * Absent capabilities read as `false`: a bridge that predates this field
+ * demonstrably has no forwarding, so assuming "yes" would produce broken URLs.
+ */
+export declare function hostSupportsImageAi(bridge: Pick<FieldsBridge, 'capabilities'> | null | undefined): boolean;
+export type ResolveBackgroundRemovalOptions = {
+    /** The field's `removeBackground` prop. */
+    enabled: boolean;
+    /** Host capability — see `hostSupportsImageAi`. */
+    capable: boolean;
+};
+/**
+ * Decide the `src` an image field should store.
+ *
+ * Three properties this relies on, all provided by `withCloudflareTransform`:
+ *
+ *  - **Idempotent** — safe to run on a src that already carries the transform,
+ *    which happens on every re-render and every draft reload.
+ *  - **Reversible** — turning the setting off restores the plain variant, so
+ *    existing drafts follow the toggle instead of freezing at whatever they
+ *    were uploaded with.
+ *  - **Silent passthrough** — legacy R2 srcs, Pexels and shared-drive links
+ *    are not delivery URLs and come back untouched rather than mangled.
+ *
+ * Never throws; the worst case is "the image is unchanged".
+ */
+export declare function resolveBackgroundRemoval(src: string, opts: ResolveBackgroundRemovalOptions): string;
+/**
+ * The untransformed counterpart of a src, for use as an `<img>` error
+ * fallback.
+ *
+ * `segment=foreground` is a Cloudflare open beta. When it fails the browser
+ * renders a broken image, which is strictly worse than showing the original —
+ * so every surface that applies the transform should also be able to fall back.
+ * Returns `null` when there is nothing to fall back to.
+ */
+export declare function backgroundRemovalFallbackSrc(src: string): string | null;

package/dist/util/cloudflareImages.d.ts

@@ -21,4 +21,6 @@ export declare function uploadImage(apiBaseUrl: string, templateId: string, cont
     type: string;
     url: string;
     uploadedAt: string;
+    imageId?: string | undefined;
+    deliveryBase?: string | undefined;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluepic/embed",
-  "version": "0.4.0-next.90",
+  "version": "0.4.0-next.91",
   "description": "Bluepic embed sdk",
   "type": "module",
   "sideEffects": false,
@@ -29,14 +29,15 @@
     "dev": "rimraf dist && concurrently \"npm:dev:vite\" \"npm:dev:types\"",
     "dev:vite": "vite build --watch",
     "dev:types": "vue-tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist --watch",
-    "playground:dev": "vite --config vite.playground.config.ts"
+    "playground:dev": "vite --config vite.playground.config.ts",
+    "test:autocrop": "tsx src/util/autoCrop/solveAutoCrop.test.ts"
   },
   "peerDependencies": {
     "vue": "^3.5.23"
   },
   "devDependencies": {
     "@auth0/auth0-vue": "^2.4.0",
-    "@bluepic/types": "^0.6.450",
+    "@bluepic/types": "^0.6.453",
     "@hono/zod-openapi": "^1.1.4",
     "@types/css": "^0.0.38",
     "@types/downloadjs": "^1.4.6",
@@ -55,7 +56,8 @@
     "vite": "^5.4.0",
     "vue": "^3.5.27",
     "vue-tsc": "^2.0.0",
-    "zod": "4.1.12"
+    "zod": "4.1.12",
+    "tsx": "^4.20.0"
   },
   "dependencies": {
     "@bluepic/raster": "^0.1.6",