Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Selfie refinement — the missing preprocessing stage between the capture UI and
* the avatar reconstruction backend.
*
* Why this exists: the reconstruct lane (/api/avatars/reconstruct) feeds the raw
* photo straight to a generic image→3D model. Those models have no facial prior
* and reconstruct depth from shading/parallax — so a face photo with its full
* background (or worse, a flat 2D illustration) collapses to a textured plane:
* the "card" failure. The text→avatar lane right next to it works well precisely
* because it hands the model a clean, centred, plain-background figure. This
* module makes the selfie lane do the same to its input before upload:
*
* 1. assess() — gate the input (face present? sharp? a real photo not a flat
* drawing? close enough?) and surface actionable warnings.
* 2. refine() — isolate the human subject from the background (MediaPipe
* Selfie Segmentation), composite onto a neutral studio
* backdrop, and reframe to a centred head-and-shoulders square
* — the exact composition the reconstruction lane handles best.
*
* Everything runs in the browser. No server keys, no GPU workers, no upload of
* the raw frame. The deterministic math (framing, sharpness, flatness, quality
* verdict) is exported as pure functions so it is unit-tested without a DOM.
*
* Graceful degradation is a hard rule here (CLAUDE.md: "no errors without
* solutions"): if the segmentation model can't load, refine() still reframes off
* the detected face box — tight framing alone removes most of the background —
* and never throws into the capture flow.
*/
import { GATES } from './selfie-gates.js';
import { log } from './shared/log.js';
import { loadVision, modelUrl, visionWasmBase, withVisionDeadline } from './shared/mediapipe-assets.js';
// MediaPipe tasks-vision — same pinned build the face stack uses, so the WASM
// runtime is shared/cached across the landmarker and the segmenter.
// tasks-vision is bundled from the npm dependency; the WASM runtime comes from
// the shared resolver, which prefers our vendored copy over a CDN.
// Official Google-hosted binary selfie segmenter (Apache-2.0). One confidence
// mask: per-pixel probability the pixel belongs to the person.
const SELFIE_MODEL_URL =
modelUrl('image_segmenter/selfie_segmenter/float16/latest/selfie_segmenter.tflite');
// BlazeFace short-range detector (Apache-2.0): bounding boxes + count. Cheaper
// than the 478-point landmarker and the right tool for "where/how many faces".
const FACE_DETECTOR_MODEL_URL =
modelUrl('face_detector/blaze_face_short_range/float16/latest/blaze_face_short_range.tflite');
// Working resolution: cap the longest edge so the matte + reframe stay fast on
// phones. The output square is rendered at OUTPUT_SIZE regardless.
const WORK_MAX = 1024;
const OUTPUT_SIZE = 1024;
const JPEG_QUALITY = 0.92;
// Quality thresholds. Heuristic, tuned conservative so a real photo is never
// blocked — the only hard gate is "no face". Everything else is a warning the
// user can act on or ignore.
const THRESH = Object.freeze({
// Variance-of-Laplacian on an 8-bit grey image. Sharp phone selfies land in
// the hundreds-to-thousands; sub-this reads as soft/blurry.
sharpnessBlurry: 90,
// Fraction of near-flat 3×3 neighbourhoods. Cel-shaded drawings are mostly
// flat fills with hard edges; photographs carry sensor/texture noise.
flatnessHigh: 0.62,
// Mean saturation (0..1). Illustrations skew saturated; pairing high flatness
// with high saturation separates "cartoon" from "plain-wall photo".
saturationHigh: 0.28,
// Face width as a fraction of the frame's shorter edge — below this the
// subject is too far away for a faithful reconstruction.
faceTooFarRel: 0.14,
// Absolute minimum useful frame.
minDimPx: 320,
});
/* ────────────────────────────────────────────────────────────────────────── *
* Pure helpers — no DOM. Exported for unit tests.
* ────────────────────────────────────────────────────────────────────────── */
/**
* Variance-of-Laplacian sharpness on an 8-bit grey buffer. Higher = sharper.
* The Laplacian (4-neighbour) responds to edges; a blurry image has little
* high-frequency energy so its response variance is low.
*
* @param {Uint8Array|Uint8ClampedArray|number[]} grey row-major, length w*h
* @param {number} w
* @param {number} h
* @returns {number}
*/
export function laplacianVariance(grey, w, h) {
if (w < 3 || h < 3) return 0;
let sum = 0;
let sumSq = 0;
let n = 0;
for (let y = 1; y < h - 1; y++) {
for (let x = 1; x < w - 1; x++) {
const i = y * w + x;
const lap =
4 * grey[i] - grey[i - 1] - grey[i + 1] - grey[i - w] - grey[i + w];
sum += lap;
sumSq += lap * lap;
n++;
}
}
if (n === 0) return 0;
const mean = sum / n;
return sumSq / n - mean * mean;
}
/**
* Fraction of pixels whose 3×3 neighbourhood is nearly constant. A proxy for
* "flat-fill illustration vs. textured photograph". Operates on an 8-bit grey
* buffer; a neighbourhood counts as flat when its max−min span ≤ `tol`.
*
* @param {Uint8Array|Uint8ClampedArray|number[]} grey row-major, length w*h
* @param {number} w
* @param {number} h
* @param {number} [tol=6]
* @returns {number} 0..1
*/
export function flatnessScore(grey, w, h, tol = 6) {
if (w < 3 || h < 3) return 0;
let flat = 0;
let n = 0;
for (let y = 1; y < h - 1; y++) {
for (let x = 1; x < w - 1; x++) {
const i = y * w + x;
let mn = 255;
let mx = 0;
for (let dy = -1; dy <= 1; dy++) {
for (let dx = -1; dx <= 1; dx++) {
const v = grey[i + dy * w + dx];
if (v < mn) mn = v;
if (v > mx) mx = v;
}
}
if (mx - mn <= tol) flat++;
n++;
}
}
return n ? flat / n : 0;
}
/**
* Mean saturation (HSV S, 0..1) over an RGBA buffer, sampled with a stride for
* speed. Used together with flatness to flag illustrations.
*
* @param {Uint8Array|Uint8ClampedArray|number[]} rgba length w*h*4
* @param {number} w
* @param {number} h
* @param {number} [stride=4] sample every Nth pixel
* @returns {number} 0..1
*/
export function meanSaturation(rgba, w, h, stride = 4) {
let acc = 0;
let n = 0;
const step = Math.max(1, stride) * 4;
for (let i = 0; i < w * h * 4; i += step) {
const r = rgba[i];
const g = rgba[i + 1];
const b = rgba[i + 2];
const mx = Math.max(r, g, b);
const mn = Math.min(r, g, b);
acc += mx === 0 ? 0 : (mx - mn) / mx;
n++;
}
return n ? acc / n : 0;
}
/**
* Decide whether the input is good enough to reconstruct, and why not.
* Only "no face" blocks; everything else is a non-fatal warning. Pure.
*
* @param {{
* width: number, height: number,
* faceCount: number,
* faceBox?: { x:number, y:number, w:number, h:number } | null,
* sharpness: number,
* flatness: number,
* saturation: number,
* luma?: number,
* }} m `luma` is the mean face luma (0..255) when the caller measured it;
* omitted, lighting is not judged (the server stays the final authority).
* @returns {{ verdict: 'good'|'warn'|'block', issues: string[], primary: string|null, message: string }}
*/
export function assessPhotoQuality(m) {
const issues = [];
const shortEdge = Math.max(1, Math.min(m.width, m.height));
// A null count means the detector never loaded. That is not evidence about
// the photo, so the gate steps aside rather than telling someone their
// perfectly good selfie has no face in it. The reconstruction worker runs
// its own face pass and stays the authority either way.
const faceCountKnown = typeof m.faceCount === 'number';
if (faceCountKnown && !m.faceCount) {
return {
verdict: 'block',
issues: ['no-face'],
primary: 'no-face',
message:
"We couldn't find a face. Use a clear, front-facing photo with your face well-lit and unobscured.",
};
}
if (faceCountKnown && m.faceCount > 1) issues.push('multiple-faces');
if (m.faceBox) {
const faceRel = m.faceBox.w / shortEdge;
if (faceRel < THRESH.faceTooFarRel) issues.push('far');
}
if (m.width < THRESH.minDimPx || m.height < THRESH.minDimPx) issues.push('low-res');
if (m.sharpness < THRESH.sharpnessBlurry) issues.push('blurry');
if (typeof m.luma === 'number') {
if (m.luma < GATES.LUMA_MIN) issues.push('dark');
else if (m.luma > GATES.LUMA_MAX) issues.push('bright');
}
if (m.flatness > THRESH.flatnessHigh && m.saturation > THRESH.saturationHigh)
issues.push('illustration');
const MESSAGES = {
illustration:
'This looks like a drawing or cartoon. 3D works best from a real photo — a flat illustration may come out flat. You can continue, but a real selfie gives a real you.',
blurry: 'This photo looks soft. A sharper, well-lit shot reconstructs with more detail.',
dark: 'Your face is in shadow. Face a light source so your features are visible.',
bright: 'Your face is washed out. Step away from direct light or glare.',
far: 'Your face is small in frame. Move closer or crop tighter for a stronger likeness.',
'low-res': 'This image is low-resolution. A larger photo captures more facial detail.',
'multiple-faces': "More than one face detected — we'll use the largest. Crop to just you for the best result.",
};
const order = ['illustration', 'blurry', 'dark', 'bright', 'far', 'low-res', 'multiple-faces'];
const primary = order.find((k) => issues.includes(k)) || null;
return {
verdict: issues.length ? 'warn' : 'good',
issues,
primary,
message: primary ? MESSAGES[primary] : 'Looks great.',
};
}
/**
* Compute a centred, square head-and-shoulders crop from a detected face box.
* The face is placed in the upper third with headroom above and torso below —
* the framing reconstruction models reconstruct most reliably. Optionally
* widened to include the segmented subject's horizontal extent (shoulders are
* wider than the face). Always returns an integer square clamped inside the
* image; if the ideal square doesn't fit, the largest fitting square centred on
* the face is returned instead. Pure.
*
* @param {{ x:number, y:number, w:number, h:number }} faceBox pixel space
* @param {number} imgW
* @param {number} imgH
* @param {{ subjectBox?: {x:number,y:number,w:number,h:number}|null,
* headroom?: number, vertical?: number, scale?: number }} [opts]
* @returns {{ x:number, y:number, w:number, h:number }}
*/
export function computeSubjectFrame(faceBox, imgW, imgH, opts = {}) {
const headroom = opts.headroom ?? 0.7; // multiples of face height above the face top
const scale = opts.scale ?? 3.4; // crop side as multiples of face height
const faceCx = faceBox.x + faceBox.w / 2;
// Ideal square side from face height, widened if the subject mask is wider.
let side = faceBox.h * scale;
if (opts.subjectBox && opts.subjectBox.w > 0) {
side = Math.max(side, opts.subjectBox.w * 1.25);
}
side = Math.min(side, imgW, imgH); // can't exceed the frame
// Top: leave headroom above the face; the rest of the square falls below,
// capturing neck + shoulders.
let top = faceBox.y - faceBox.h * headroom;
let left = faceCx - side / 2;
// Clamp inside the image, preserving the square side.
left = Math.max(0, Math.min(left, imgW - side));
top = Math.max(0, Math.min(top, imgH - side));
return {
x: Math.round(left),
y: Math.round(top),
w: Math.round(side),
h: Math.round(side),
};
}
/**
* Bounding box (pixel space) of the foreground in a confidence mask, using a
* threshold. Returns null if nothing crosses the threshold. Pure.
*
* @param {Float32Array|number[]} mask length maskW*maskH, values 0..1
* @param {number} maskW
* @param {number} maskH
* @param {number} imgW target image width to scale the box into
* @param {number} imgH
* @param {number} [thresh=0.5]
* @returns {{ x:number, y:number, w:number, h:number } | null}
*/
export function maskBoundingBox(mask, maskW, maskH, imgW, imgH, thresh = 0.5) {
let minX = maskW;
let minY = maskH;
let maxX = -1;
let maxY = -1;
for (let y = 0; y < maskH; y++) {
for (let x = 0; x < maskW; x++) {
if (mask[y * maskW + x] >= thresh) {
if (x < minX) minX = x;
if (x > maxX) maxX = x;
if (y < minY) minY = y;
if (y > maxY) maxY = y;
}
}
}
if (maxX < 0) return null;
const sx = imgW / maskW;
const sy = imgH / maskH;
return {
x: Math.round(minX * sx),
y: Math.round(minY * sy),
w: Math.round((maxX - minX + 1) * sx),
h: Math.round((maxY - minY + 1) * sy),
};
}
/** Smoothstep — used to feather the segmentation mask edge into alpha. Pure. */
export function smoothstep(edge0, edge1, x) {
if (edge0 === edge1) return x < edge0 ? 0 : 1;
const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));
return t * t * (3 - 2 * t);
}
/* ────────────────────────────────────────────────────────────────────────── *
* DOM / MediaPipe wrappers — browser only.
* ────────────────────────────────────────────────────────────────────────── */
let _segmenterPromise = null;
/** Lazy-load the Selfie Segmenter. Resolves null (never throws) on failure. */
async function loadSegmenter() {
if (_segmenterPromise) return _segmenterPromise;
_segmenterPromise = (async () => {
const mod = await loadVision();
const { FilesetResolver, ImageSegmenter } = mod;
const vision = await FilesetResolver.forVisionTasks(await visionWasmBase());
return ImageSegmenter.createFromOptions(vision, {
baseOptions: { modelAssetPath: SELFIE_MODEL_URL, delegate: 'GPU' },
runningMode: 'IMAGE',
outputConfidenceMasks: true,
outputCategoryMask: false,
});
})();
_segmenterPromise = withVisionDeadline(_segmenterPromise, 'selfie segmenter').catch((err) => {
_segmenterPromise = null; // allow a retry on the next photo
log.warn('[selfie-refine] segmenter load failed:', err);
return null;
});
return _segmenterPromise;
}
let _detectorPromise = null;
/** Lazy-load the BlazeFace detector. Resolves null (never throws) on failure. */
async function loadFaceDetector() {
if (_detectorPromise) return _detectorPromise;
_detectorPromise = (async () => {
const mod = await loadVision();
const { FilesetResolver, FaceDetector } = mod;
const vision = await FilesetResolver.forVisionTasks(await visionWasmBase());
return FaceDetector.createFromOptions(vision, {
baseOptions: { modelAssetPath: FACE_DETECTOR_MODEL_URL, delegate: 'GPU' },
runningMode: 'IMAGE',
});
})();
_detectorPromise = withVisionDeadline(_detectorPromise, 'face detector').catch((err) => {
_detectorPromise = null;
log.warn('[selfie-refine] face detector load failed:', err);
return null;
});
return _detectorPromise;
}
/**
* Detect faces and return the largest as a normalised box plus the total count.
* Coordinates are fractions of the image (0..1) so the box is resolution
* independent. Returns null when no face is found or the detector is
* unavailable.
*
* @param {ImageBitmap|HTMLImageElement|HTMLCanvasElement} bitmap
* @returns {Promise<{ x:number, y:number, w:number, h:number, count:number } | null>}
*/
export async function detectFaceBox(bitmap) {
const detector = await loadFaceDetector();
if (!detector) return null;
const { w, h } = dimsOf(bitmap);
if (!w || !h) return null;
const res = detector.detect(bitmap);
const dets = res?.detections || [];
if (!dets.length) return null;
// Largest by area — the subject, not a bystander in the background.
let best = null;
let bestArea = -1;
for (const d of dets) {
const b = d.boundingBox;
if (!b) continue;
const area = b.width * b.height;
if (area > bestArea) {
bestArea = area;
best = b;
}
}
if (!best) return null;
return {
x: best.originX / w,
y: best.originY / h,
w: best.width / w,
h: best.height / h,
count: dets.length,
};
}
/** Pre-warm the detection + segmentation models (overlap with camera UI). */
export function warmRefiner() {
loadFaceDetector().catch(() => {});
loadSegmenter().catch(() => {});
}
/** @param {ImageBitmap|HTMLImageElement|HTMLCanvasElement} src */
function dimsOf(src) {
const w = src.width || src.naturalWidth || src.videoWidth || 0;
const h = src.height || src.naturalHeight || src.videoHeight || 0;
return { w, h };
}
/** Fit (w,h) within max, preserving aspect. */
function fitWithin(w, h, max) {
if (w <= max && h <= max) return { w, h };
const s = Math.min(max / w, max / h);
return { w: Math.round(w * s), h: Math.round(h * s) };
}
/**
* Assess a photo's suitability for reconstruction. Loads the face landmarker to
* locate the face, samples the pixels for sharpness/flatness/saturation, and
* returns the pure {@link assessPhotoQuality} verdict plus the face box (for
* reframing). Never throws — on detector failure it returns a permissive
* "good" so the server stays the final authority.
*
* @param {ImageBitmap|HTMLImageElement} bitmap
* @returns {Promise<{ verdict:string, issues:string[], primary:string|null, message:string, faceBox:object|null }>}
*/
export async function assessPhoto(bitmap) {
const { w, h } = dimsOf(bitmap);
try {
// Availability and result are separate answers: a detector that never
// loaded must not read as "this photo has no face in it".
const detector = await loadFaceDetector();
const face = detector ? await detectFaceBox(bitmap) : null;
// Sample at a small fixed size — quality metrics don't need full res and
// this keeps the per-pixel passes cheap.
const s = fitWithin(w, h, 256);
const canvas = makeCanvas(s.w, s.h);
const ctx = canvas.getContext('2d', { willReadFrequently: true });
ctx.drawImage(bitmap, 0, 0, s.w, s.h);
const { data } = ctx.getImageData(0, 0, s.w, s.h);
const grey = new Uint8Array(s.w * s.h);
for (let i = 0, p = 0; i < data.length; i += 4, p++) {
// Rec. 601 luma.
grey[p] = (data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114) | 0;
}
const faceBoxPx = face
? { x: face.x * w, y: face.y * h, w: face.w * w, h: face.h * h }
: null;
// Mean luma over the face region (whole frame when no box): the lighting
// gate cares whether the FACE is legible, not whether the room is bright.
let luma;
{
const bx = face ? Math.max(0, Math.round(face.x * s.w)) : 0;
const by = face ? Math.max(0, Math.round(face.y * s.h)) : 0;
const bw = face ? Math.min(s.w - bx, Math.max(1, Math.round(face.w * s.w))) : s.w;
const bh = face ? Math.min(s.h - by, Math.max(1, Math.round(face.h * s.h))) : s.h;
let sum = 0;
for (let y = by; y < by + bh; y++)
for (let x = bx; x < bx + bw; x++) sum += grey[y * s.w + x];
luma = sum / (bw * bh);
}
const assessment = assessPhotoQuality({
width: w,
height: h,
faceCount: detector ? (face ? face.count : 0) : null,
faceBox: faceBoxPx,
sharpness: laplacianVariance(grey, s.w, s.h),
flatness: flatnessScore(grey, s.w, s.h),
saturation: meanSaturation(data, s.w, s.h),
luma,
});
return { ...assessment, faceBox: faceBoxPx };
} catch (err) {
log.warn('[selfie-refine] assess failed, allowing through:', err);
return { verdict: 'good', issues: [], primary: null, message: '', faceBox: null };
}
}
/**
* Isolate the subject and reframe into a clean head-and-shoulders square on a
* neutral studio backdrop — the composition the reconstruction lane handles
* best. Returns a JPEG data URL. Never throws: on any failure it falls back to
* a plain centred crop (or the original frame) so capture always proceeds.
*
* @param {ImageBitmap|HTMLImageElement} bitmap
* @param {{ faceBox?: object|null, onStep?: (label:string)=>void }} [opts]
* @returns {Promise<{ dataUrl: string, isolated: boolean }>}
*/
export async function refineSelfie(bitmap, opts = {}) {
const onStep = opts.onStep || (() => {});
const { w: srcW, h: srcH } = dimsOf(bitmap);
const work = fitWithin(srcW, srcH, WORK_MAX);
// Draw the frame once at working resolution.
const frame = makeCanvas(work.w, work.h);
const fctx = frame.getContext('2d', { willReadFrequently: true });
fctx.drawImage(bitmap, 0, 0, work.w, work.h);
// Face box in working-resolution pixels (from the prior assess pass, or a
// fresh detect). Without a face we can still matte + centre-crop.
let faceBox = opts.faceBox
? { x: opts.faceBox.x * (work.w / srcW), y: opts.faceBox.y * (work.h / srcH), w: opts.faceBox.w * (work.w / srcW), h: opts.faceBox.h * (work.h / srcH) }
: null;
if (!faceBox) {
try {
const f = await detectFaceBox(bitmap);
if (f) faceBox = { x: f.x * work.w, y: f.y * work.h, w: f.w * work.w, h: f.h * work.h };
} catch (_) {}
}
let subjectBox = null;
let isolated = false;
// ── Matte the subject onto a neutral backdrop ────────────────────────────
try {
onStep('Isolating subject…');
const segmenter = await loadSegmenter();
if (segmenter) {
// Segment the original source, not the OffscreenCanvas working frame:
// MediaPipe accepts ImageBitmap/HTMLImageElement everywhere, whereas
// OffscreenCanvas input isn't supported across all builds. The mask
// covers the same aspect ratio either way, so the work-space sampling
// below is unaffected.
const result = segmenter.segment(bitmap);
const conf = result?.confidenceMasks?.[0];
if (conf) {
const maskW = conf.width;
const maskH = conf.height;
const maskArr = conf.getAsFloat32Array();
subjectBox = maskBoundingBox(maskArr, maskW, maskH, work.w, work.h, 0.5);
// Apply the feathered mask as alpha on the frame.
const img = fctx.getImageData(0, 0, work.w, work.h);
const d = img.data;
for (let y = 0; y < work.h; y++) {
const my = Math.min(maskH - 1, (y * maskH / work.h) | 0);
for (let x = 0; x < work.w; x++) {
const mx = Math.min(maskW - 1, (x * maskW / work.w) | 0);
const p = maskArr[my * maskW + mx];
const a = smoothstep(0.35, 0.65, p);
d[(y * work.w + x) * 4 + 3] = (a * 255) | 0;
}
}
// Composite over a neutral studio gradient: matted subject on top.
const subjectCanvas = makeCanvas(work.w, work.h);
subjectCanvas.getContext('2d').putImageData(img, 0, 0);
paintStudioBackdrop(fctx, work.w, work.h);
fctx.drawImage(subjectCanvas, 0, 0);
isolated = true;
if (typeof result.close === 'function') result.close();
else conf.close?.();
}
}
} catch (err) {
log.warn('[selfie-refine] segmentation failed, framing only:', err);
}
// ── Reframe to a centred head-and-shoulders square ───────────────────────
onStep('Reframing…');
const out = makeCanvas(OUTPUT_SIZE, OUTPUT_SIZE);
const octx = out.getContext('2d');
// Fill first so any crop that runs past the subject reads as studio, not black.
paintStudioBackdrop(octx, OUTPUT_SIZE, OUTPUT_SIZE);
const frameBox = faceBox
? computeSubjectFrame(faceBox, work.w, work.h, { subjectBox })
: centreSquare(work.w, work.h);
octx.drawImage(
frame,
frameBox.x, frameBox.y, frameBox.w, frameBox.h,
0, 0, OUTPUT_SIZE, OUTPUT_SIZE,
);
const dataUrl = await canvasToDataUrl(out, JPEG_QUALITY);
return { dataUrl, isolated };
}
/**
* Data URL from either a DOM canvas (toDataURL) or an OffscreenCanvas
* (convertToBlob → FileReader), so the working canvas can be either.
* @param {HTMLCanvasElement|OffscreenCanvas} canvas
* @param {number} quality
* @returns {Promise<string>}
*/
async function canvasToDataUrl(canvas, quality) {
if (typeof canvas.toDataURL === 'function') {
return canvas.toDataURL('image/jpeg', quality);
}
const blob = await canvas.convertToBlob({ type: 'image/jpeg', quality });
return await new Promise((resolve, reject) => {
const fr = new FileReader();
fr.onload = () => resolve(/** @type {string} */ (fr.result));
fr.onerror = () => reject(fr.error || new Error('blob read failed'));
fr.readAsDataURL(blob);
});
}
/** Largest centred square within (w,h). */
function centreSquare(w, h) {
const side = Math.min(w, h);
return { x: Math.round((w - side) / 2), y: Math.round((h - side) / 2), w: side, h: side };
}
/**
* Paint a soft, neutral studio backdrop — a gentle vertical grey gradient with
* a subtle radial vignette behind the head. Mirrors the "plain neutral studio
* background, soft even lighting" the text→avatar prompt steers toward.
* @param {CanvasRenderingContext2D} ctx
*/
function paintStudioBackdrop(ctx, w, h) {
const lin = ctx.createLinearGradient(0, 0, 0, h);
lin.addColorStop(0, '#d9dbe0');
lin.addColorStop(1, '#b7bac1');
ctx.fillStyle = lin;
ctx.fillRect(0, 0, w, h);
const rad = ctx.createRadialGradient(w / 2, h * 0.34, h * 0.05, w / 2, h * 0.34, h * 0.7);
rad.addColorStop(0, 'rgba(255,255,255,0.55)');
rad.addColorStop(1, 'rgba(255,255,255,0)');
ctx.fillStyle = rad;
ctx.fillRect(0, 0, w, h);
}
/** OffscreenCanvas when available (workers/perf), else a DOM canvas. */
function makeCanvas(w, h) {
if (typeof OffscreenCanvas === 'function') {
try {
return new OffscreenCanvas(w, h);
} catch (_) {}
}
const c = document.createElement('canvas');
c.width = w;
c.height = h;
return c;
}