@incodetech/core 2.1.0-rc.2 → 2.1.0-rc.3

package/dist/Face2DProvider-BeLlYBbB.esm.js

@@ -0,0 +1,824 @@
+import { t as createHiddenVideoElement } from "./video-C2WIj6TS.esm.js";
+import { i as dtAlpha, n as asRvfc, r as createFaceLandmarker, t as MAX_EMA_DT_MS } from "./mediapipeShared-CRAKVElv.esm.js";
+
+//#region ../infra/src/avatar/2d-default-avatar/assets.ts
+/**
+* 2D avatar MediaPipe asset resolution — **self-contained** (no shared
+* `avatarDefaults`; owns its asset config). No VRM here — 2D satin face.
+* See docs/features/FACE_AVATAR.md → Isolation and ownership.
+*
+* Prebuilt tasks-vision ESM + wasm + the face-landmarker model. Public CDNs for
+* development; production should self-host.
+*/
+const DEFAULT_MEDIAPIPE_MODULE_URL = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.35";
+const DEFAULT_FACE_LANDMARKER_MODEL_URL = "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task";
+function valid(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+function resolveAvatar2DAssets(overrides) {
+	const moduleUrl = valid(overrides?.mediapipeModulePath) ? overrides.mediapipeModulePath : DEFAULT_MEDIAPIPE_MODULE_URL;
+	return {
+		mediapipeModulePath: moduleUrl,
+		mediapipeWasmPath: valid(overrides?.mediapipeWasmPath) ? overrides.mediapipeWasmPath : `${moduleUrl}/wasm`,
+		faceLandmarkerModelPath: valid(overrides?.faceLandmarkerModelPath) ? overrides.faceLandmarkerModelPath : DEFAULT_FACE_LANDMARKER_MODEL_URL
+	};
+}
+
+//#endregion
+//#region ../infra/src/avatar/renderers/SatinSmileyRenderer.ts
+const SPRITE = 512;
+const HEAD_CX = 256;
+const HEAD_CY = 256;
+const HEAD_R = 150;
+const HALO_R = HEAD_R + 28;
+const EYE_Y = 218;
+const EYE_DX = 56;
+const EYE_RX = 12;
+const NOSE_Y0 = 258;
+const NOSE_Y1 = 292;
+const MOUTH_Y = 330;
+const MOUTH_HALF = 44;
+const YAW_PARALLAX = 90;
+const PITCH_PARALLAX = 72;
+const REST_SMILE = .35;
+const PALETTES = {
+	detecting: {
+		stops: [
+			"#f4f9ff",
+			"#dbeafe",
+			"#cbe0fb",
+			"#aacdf3"
+		],
+		occlusion: "#6f9fd8",
+		contact: "#3a5f8f",
+		feature: "#007aff",
+		halo: "#2f86f0"
+	},
+	success: {
+		stops: [
+			"#f0fdf4",
+			"#dcfce7",
+			"#bbf7d0",
+			"#86c79a"
+		],
+		occlusion: "#3f7a52",
+		contact: "#1f5132",
+		feature: "#15803d",
+		halo: "#22c55e"
+	},
+	error: {
+		stops: [
+			"#fff1f1",
+			"#fee2e2",
+			"#fecaca",
+			"#e89a9a"
+		],
+		occlusion: "#8c4a4a",
+		contact: "#5f1e1e",
+		feature: "#b91c1c",
+		halo: "#dc2626"
+	}
+};
+const clamp$1 = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+function hexToRgb(hex) {
+	const h = hex.replace("#", "");
+	return [
+		parseInt(h.slice(0, 2), 16),
+		parseInt(h.slice(2, 4), 16),
+		parseInt(h.slice(4, 6), 16)
+	];
+}
+function rgb(c) {
+	return `rgb(${c[0] | 0}, ${c[1] | 0}, ${c[2] | 0})`;
+}
+function rgba(c, a) {
+	return `rgba(${c[0] | 0}, ${c[1] | 0}, ${c[2] | 0}, ${a})`;
+}
+function toRgbPalette(p) {
+	return {
+		stops: [
+			hexToRgb(p.stops[0]),
+			hexToRgb(p.stops[1]),
+			hexToRgb(p.stops[2]),
+			hexToRgb(p.stops[3])
+		],
+		occlusion: hexToRgb(p.occlusion),
+		contact: hexToRgb(p.contact),
+		feature: hexToRgb(p.feature),
+		halo: hexToRgb(p.halo)
+	};
+}
+const RGB_PALETTES = {
+	detecting: toRgbPalette(PALETTES.detecting),
+	success: toRgbPalette(PALETTES.success),
+	error: toRgbPalette(PALETTES.error)
+};
+function clonePalette(p) {
+	return {
+		stops: [
+			[...p.stops[0]],
+			[...p.stops[1]],
+			[...p.stops[2]],
+			[...p.stops[3]]
+		],
+		occlusion: [...p.occlusion],
+		contact: [...p.contact],
+		feature: [...p.feature],
+		halo: [...p.halo]
+	};
+}
+function easeRgb(cur, target, t) {
+	cur[0] += (target[0] - cur[0]) * t;
+	cur[1] += (target[1] - cur[1]) * t;
+	cur[2] += (target[2] - cur[2]) * t;
+}
+/** Ease every channel of `cur` toward `target` in place (smooth state crossfade). */
+function easePaletteToward(cur, target, t) {
+	for (let i = 0; i < 4; i += 1) easeRgb(cur.stops[i], target.stops[i], t);
+	easeRgb(cur.occlusion, target.occlusion, t);
+	easeRgb(cur.contact, target.contact, t);
+	easeRgb(cur.feature, target.feature, t);
+	easeRgb(cur.halo, target.halo, t);
+}
+function resolveOverride() {
+	const v = globalThis.__incodeAvatarState;
+	return v === "detecting" || v === "success" || v === "error" ? v : null;
+}
+var SatinSmileyRenderer = class {
+	constructor(size = 512) {
+		this.ctx = null;
+		this.presence = 0;
+		this.faceState = "detecting";
+		this.eased = clonePalette(RGB_PALETTES.detecting);
+		this.size = size;
+		this.canvas = document.createElement("canvas");
+		this.canvas.width = size;
+		this.canvas.height = size;
+	}
+	init() {
+		this.ctx = this.canvas.getContext("2d");
+	}
+	getCanvas() {
+		return this.canvas;
+	}
+	/** Set the verdict state (detecting/success/error); colours ease toward it. */
+	setState(state) {
+		this.faceState = state;
+	}
+	dispose() {
+		this.ctx = null;
+	}
+	render(frame) {
+		const ctx = this.ctx;
+		if (!ctx) return;
+		const s = this.size;
+		ctx.clearRect(0, 0, s, s);
+		const state = resolveOverride() ?? this.faceState;
+		easePaletteToward(this.eased, RGB_PALETTES[state], .08);
+		const target = frame.tracked ? 1 : 0;
+		this.presence += (target - this.presence) * .12;
+		const faceAlpha = this.presence;
+		const k = s / SPRITE;
+		const slideX = frame.rootOffset.x * s * .03;
+		const slideY = frame.rootOffset.y * s * .03;
+		const scale = 1 + clamp$1(frame.depth, -.6, .8) * .35;
+		const yaw = clamp$1(frame.headEuler.y, -.9, .9);
+		const pitch = clamp$1(frame.headEuler.x, -.9, .9);
+		this.drawHalo(ctx, s, k, scale, slideX, slideY);
+		ctx.save();
+		ctx.translate(s / 2 + slideX, s / 2 + slideY);
+		ctx.rotate(frame.headEuler.z);
+		ctx.scale(scale * k, scale * k);
+		ctx.translate(-SPRITE / 2, -SPRITE / 2);
+		if (faceAlpha > .02) {
+			ctx.globalAlpha = faceAlpha;
+			this.drawBall(ctx);
+			const featX = yaw * YAW_PARALLAX;
+			const featY = pitch * PITCH_PARALLAX;
+			ctx.save();
+			ctx.translate(HEAD_CX, HEAD_CY);
+			ctx.scale(1 - Math.abs(yaw) * .24, 1 - Math.abs(pitch) * .12);
+			ctx.translate(-HEAD_CX, -HEAD_CY);
+			ctx.translate(featX, featY);
+			const feat = rgb(this.eased.feature);
+			let blinkL = clamp$1(frame.blink.left, 0, 1);
+			let blinkR = clamp$1(frame.blink.right, 0, 1);
+			if (state === "success") {
+				blinkL = 0;
+				blinkR = .85;
+			}
+			this.drawEye(ctx, HEAD_CX - EYE_DX, EYE_Y, blinkL, feat);
+			this.drawEye(ctx, HEAD_CX + EYE_DX, EYE_Y, blinkR, feat);
+			this.drawNose(ctx, feat);
+			let mouth = Math.max(REST_SMILE, clamp$1(frame.smile ?? 0, 0, 1));
+			if (state === "success") mouth = 1;
+			else if (state === "error") mouth = -.55;
+			this.drawMouth(ctx, mouth, feat);
+			ctx.restore();
+			ctx.globalAlpha = 1;
+		}
+		ctx.restore();
+	}
+	/** Dashed halo ring around the head — the "we've got you" frame (state-colored). */
+	drawHalo(ctx, s, k, scale, slideX, slideY) {
+		ctx.save();
+		ctx.translate(s / 2 + slideX, s / 2 + slideY);
+		ctx.scale(scale, scale);
+		ctx.globalAlpha = .9;
+		ctx.strokeStyle = rgb(this.eased.halo);
+		ctx.lineWidth = 4 * k;
+		ctx.lineCap = "round";
+		ctx.setLineDash([15 * k, 12 * k]);
+		ctx.beginPath();
+		ctx.arc(0, 0, HALO_R * k, 0, Math.PI * 2);
+		ctx.stroke();
+		ctx.setLineDash([]);
+		ctx.restore();
+	}
+	/** Soft 3D-shaded ball via runtime gradients (so state colours can ease). */
+	drawBall(ctx) {
+		const p = this.eased;
+		const contact = ctx.createRadialGradient(256, 424, 0, 256, 424, 122);
+		contact.addColorStop(0, rgba(p.contact, .28));
+		contact.addColorStop(1, rgba(p.contact, 0));
+		ctx.fillStyle = contact;
+		ctx.beginPath();
+		ctx.ellipse(256, 424, 122, 26, 0, 0, Math.PI * 2);
+		ctx.fill();
+		const body = ctx.createRadialGradient(HEAD_CX - HEAD_R * .28, HEAD_CY - HEAD_R * .34, HEAD_R * .08, HEAD_CX, HEAD_CY, HEAD_R * 1.05);
+		body.addColorStop(0, rgb(p.stops[0]));
+		body.addColorStop(.45, rgb(p.stops[1]));
+		body.addColorStop(.8, rgb(p.stops[2]));
+		body.addColorStop(1, rgb(p.stops[3]));
+		ctx.fillStyle = body;
+		ctx.beginPath();
+		ctx.arc(HEAD_CX, HEAD_CY, HEAD_R, 0, Math.PI * 2);
+		ctx.fill();
+		const occl = ctx.createRadialGradient(HEAD_CX, HEAD_CY, HEAD_R * .68, HEAD_CX, HEAD_CY, HEAD_R);
+		occl.addColorStop(0, rgba(p.occlusion, 0));
+		occl.addColorStop(1, rgba(p.occlusion, .22));
+		ctx.fillStyle = occl;
+		ctx.beginPath();
+		ctx.arc(HEAD_CX, HEAD_CY, HEAD_R, 0, Math.PI * 2);
+		ctx.fill();
+		const spec = ctx.createRadialGradient(200, 190, 0, 200, 190, 64);
+		spec.addColorStop(0, "rgba(255, 255, 255, 0.85)");
+		spec.addColorStop(1, "rgba(255, 255, 255, 0)");
+		ctx.fillStyle = spec;
+		ctx.beginPath();
+		ctx.ellipse(200, 190, 64, 48, 0, 0, Math.PI * 2);
+		ctx.fill();
+	}
+	/** One eye: a near-round dot (open) that flattens to a line as blink → 1. */
+	drawEye(ctx, cx, cy, blink, color) {
+		const ry = 2.5 + (1 - blink) * 14;
+		ctx.fillStyle = color;
+		ctx.beginPath();
+		ctx.ellipse(cx, cy, EYE_RX, ry, 0, 0, Math.PI * 2);
+		ctx.fill();
+	}
+	/** Nose: a short, rounded vertical line under the eyes (personhood cue). */
+	drawNose(ctx, color) {
+		ctx.strokeStyle = color;
+		ctx.lineWidth = 8;
+		ctx.lineCap = "round";
+		ctx.beginPath();
+		ctx.moveTo(HEAD_CX, NOSE_Y0);
+		ctx.lineTo(HEAD_CX, NOSE_Y1);
+		ctx.stroke();
+	}
+	/** Mouth: a rounded line — flat at rest, bowing up with smile, down on frown. */
+	drawMouth(ctx, smile, color) {
+		const cy = MOUTH_Y;
+		const curve = 2 + smile * 32;
+		const lift = smile * 10;
+		ctx.strokeStyle = color;
+		ctx.lineWidth = 11;
+		ctx.lineCap = "round";
+		ctx.beginPath();
+		ctx.moveTo(HEAD_CX - MOUTH_HALF, cy - lift);
+		ctx.quadraticCurveTo(HEAD_CX, cy + curve, HEAD_CX + MOUTH_HALF, cy - lift);
+		ctx.stroke();
+	}
+};
+
+//#endregion
+//#region ../infra/src/avatar/2d-default-avatar/pose.ts
+const AVATAR2D_NEUTRAL_POSE = {
+	tracked: false,
+	headEuler: {
+		x: 0,
+		y: 0,
+		z: 0
+	},
+	rootOffset: {
+		x: 0,
+		y: 0
+	},
+	depth: 0,
+	blink: {
+		left: 0,
+		right: 0
+	},
+	mouthOpen: 0,
+	smile: 0
+};
+const LM_NOSE_TIP = 4;
+const LM_EYE_L = 33;
+const LM_EYE_L_INNER = 133;
+const LM_EYE_R = 263;
+const LM_EYE_R_INNER = 362;
+const LM_FOREHEAD = 10;
+const LM_CHIN = 152;
+const AVATAR2D_POSE_CONFIG = {
+	yawGain: 2.2,
+	pitchUpGain: 3.4,
+	pitchDownGain: 2.6,
+	rollGain: 1,
+	rotMax: .9,
+	lateralGain: 1.6,
+	lateralMax: 1,
+	depthGain: 2,
+	depthMax: .8,
+	signYaw: 1,
+	signPitch: 1,
+	signRoll: 1,
+	signX: 1,
+	signY: 1
+};
+function clamp(v, lo, hi) {
+	return Math.min(hi, Math.max(lo, v));
+}
+/** Soft deadzone (continuous past the threshold): kills idle micro-jitter. (§3b.) */
+function deadzone(v, dz) {
+	return Math.abs(v) <= dz ? 0 : v - Math.sign(v) * dz;
+}
+const AVATAR2D_DEADZONE = {
+	rot: .005,
+	roll: .006,
+	pos: .03,
+	depth: .1
+};
+const MEDIAN_WINDOW = 7;
+/**
+* Below this face-size ratio the detector emits sporadic single-frame outlier
+* spikes ("the avatar jumps") that the deadzone (idle-only) and the EMA (delays,
+* doesn't reject) both miss; run the {@link Median} first in that regime. At/above
+* it, the face is near and exp smoothing alone is enough. (FACE_AVATAR.md → Pose pipeline.)
+*/
+const MEDIAN_FACE_RATIO = .35;
+/**
+* Single-axis rolling-window median for outlier rejection. Returns the latest
+* sample until the window fills (no start-up lag spike), then the middle of the
+* sorted window. The buffer stays in insertion order so `shift()` evicts the
+* OLDEST sample, not the smallest. Ported from the incode-personhood-widget
+* `MedianFilter` — **copied, not shared** (POC isolation; renderer is the only
+* shared surface). Use three independent instances (one per axis).
+*/
+var Median = class {
+	constructor() {
+		this.buf = [];
+	}
+	reset() {
+		this.buf = [];
+	}
+	filter(x) {
+		this.buf.push(x);
+		if (this.buf.length > MEDIAN_WINDOW) this.buf.shift();
+		if (this.buf.length < MEDIAN_WINDOW) return x;
+		const sorted = [...this.buf].sort((a, b) => a - b);
+		return sorted[Math.floor(sorted.length / 2)];
+	}
+};
+/**
+* Caps on the auto-calibrated neutral so calibration cancels small device/framing
+* bias but NOT the user's real starting orientation. Yaw/roll only (straight ≈ 0
+* for both); pitch + position are left unbounded (pitch has a person-specific
+* baseline; position is genuine framing) — bounding those risks an "always looks
+* down/off-centre" artifact. Tune on device.
+*/
+const AVATAR2D_NEUTRAL_BIAS = {
+	yaw: .06,
+	roll: .05
+};
+/**
+* Raw pose from landmarks, in **pixel space** (multiply normalized coords by the
+* input width/height) so distances/angles aren't skewed on non-square frames.
+* Returns null on a missing or non-finite frame (NaN guard).
+*/
+function computeRawPose(result, width, height) {
+	const lm = result.faceLandmarks?.[0];
+	if (!lm) return null;
+	const nose = lm[LM_NOSE_TIP];
+	const eyeLo = lm[LM_EYE_L];
+	const eyeLi = lm[LM_EYE_L_INNER];
+	const eyeRo = lm[LM_EYE_R];
+	const eyeRi = lm[LM_EYE_R_INNER];
+	const forehead = lm[LM_FOREHEAD];
+	const chin = lm[LM_CHIN];
+	if (!nose || !eyeLo || !eyeLi || !eyeRo || !eyeRi || !forehead || !chin) return null;
+	const nx = nose.x * width;
+	const ny = nose.y * height;
+	const lx = (eyeLo.x + eyeLi.x) / 2 * width;
+	const ly = (eyeLo.y + eyeLi.y) / 2 * height;
+	const rx = (eyeRo.x + eyeRi.x) / 2 * width;
+	const ry = (eyeRo.y + eyeRi.y) / 2 * height;
+	const fy = forehead.y * height;
+	const cy = chin.y * height;
+	const eyeMidX = (lx + rx) / 2;
+	const eyeMidY = (ly + ry) / 2;
+	const faceMidY = (fy + cy) / 2;
+	const eyeDist = Math.hypot(rx - lx, ry - ly) || 1e-4;
+	const faceH = Math.abs(cy - fy) || 1e-4;
+	const yaw = (nx - eyeMidX) / eyeDist;
+	const pitch = (ny - faceMidY) / faceH;
+	const roll = Math.atan2(ry - ly, rx - lx);
+	if (!Number.isFinite(yaw) || !Number.isFinite(pitch) || !Number.isFinite(roll) || !Number.isFinite(eyeMidX) || !Number.isFinite(eyeDist)) return null;
+	let faceSizeRatio;
+	if (width > 0 && height > 0) {
+		let minX = Infinity;
+		let minY = Infinity;
+		let maxX = -Infinity;
+		let maxY = -Infinity;
+		for (let i = 0; i < lm.length; i += 1) {
+			const p = lm[i];
+			if (p.x < minX) minX = p.x;
+			if (p.x > maxX) maxX = p.x;
+			if (p.y < minY) minY = p.y;
+			if (p.y > maxY) maxY = p.y;
+		}
+		const bw = (maxX - minX) * width;
+		const bh = (maxY - minY) * height;
+		if (bw > 0 && bh > 0) faceSizeRatio = Math.sqrt(bw * bh) / Math.min(width, height);
+	}
+	return {
+		yaw,
+		pitch,
+		roll,
+		eyeMidX,
+		eyeMidY,
+		eyeDist,
+		faceH,
+		faceSizeRatio
+	};
+}
+/** Map a raw pose (relative to neutral) into head euler + offset + depth. */
+function mapToPose(raw, neutral, cfg) {
+	let dRoll = raw.roll - neutral.roll;
+	dRoll = Math.atan2(Math.sin(dRoll), Math.cos(dRoll));
+	const dist = neutral.dist || 1e-4;
+	const dPitch = deadzone(raw.pitch - neutral.pitch, AVATAR2D_DEADZONE.rot);
+	const pitchGain = dPitch < 0 ? cfg.pitchUpGain : cfg.pitchDownGain;
+	const dYaw = deadzone(raw.yaw - neutral.yaw, AVATAR2D_DEADZONE.rot);
+	const dRollDz = deadzone(dRoll, AVATAR2D_DEADZONE.roll);
+	const relX = deadzone((raw.eyeMidX - neutral.cx) / dist, AVATAR2D_DEADZONE.pos);
+	const relY = deadzone((raw.eyeMidY - neutral.cy) / dist, AVATAR2D_DEADZONE.pos);
+	const faceHN = neutral.faceH || 1e-4;
+	const relZ = deadzone((raw.faceH - neutral.faceH) / faceHN, AVATAR2D_DEADZONE.depth);
+	return {
+		headEuler: {
+			x: clamp(dPitch * pitchGain * cfg.signPitch, -cfg.rotMax, cfg.rotMax),
+			y: clamp(dYaw * cfg.yawGain * cfg.signYaw, -cfg.rotMax, cfg.rotMax),
+			z: clamp(dRollDz * cfg.rollGain * cfg.signRoll, -cfg.rotMax, cfg.rotMax)
+		},
+		rootOffset: {
+			x: clamp(relX * cfg.lateralGain * cfg.signX, -cfg.lateralMax, cfg.lateralMax),
+			y: clamp(relY * cfg.lateralGain * cfg.signY, -cfg.lateralMax, cfg.lateralMax)
+		},
+		depth: clamp(relZ * cfg.depthGain, -cfg.depthMax, cfg.depthMax)
+	};
+}
+/** Per-eye blink + mouth-open + smile straight from the ARKit blendshapes. */
+function blinkMouthFromBlendshapes(result) {
+	const categories = result.faceBlendshapes?.[0]?.categories ?? [];
+	let left = 0;
+	let right = 0;
+	let jaw = 0;
+	let smileL = 0;
+	let smileR = 0;
+	for (const c of categories) if (c.categoryName === "eyeBlinkLeft") left = c.score;
+	else if (c.categoryName === "eyeBlinkRight") right = c.score;
+	else if (c.categoryName === "jawOpen") jaw = c.score;
+	else if (c.categoryName === "mouthSmileLeft") smileL = c.score;
+	else if (c.categoryName === "mouthSmileRight") smileR = c.score;
+	return {
+		blink: {
+			left,
+			right
+		},
+		mouthOpen: jaw,
+		smile: (smileL + smileR) / 2
+	};
+}
+
+//#endregion
+//#region ../infra/src/avatar/2d-default-avatar/Face2DProvider.ts
+/**
+* 2D satin-face avatar — MediaPipe-tracked, 2D sprite renderer.
+* **Self-contained** (its own MediaPipe loop; see FACE_AVATAR.md → Isolation and ownership).
+* Carries mobile robustness patterns (FACE_AVATAR.md → Mobile hardening): `window.Module` shield,
+* CPU delegate, transformation matrix OFF, landmark-derived pose, NaN guards.
+*/
+const DEFAULT_MAX_FPS = 30;
+const NEUTRAL_FRAMES = 20;
+const FACE_LOST_MS = 600;
+const HEAD_ALPHA = .4;
+const POS_ALPHA = .35;
+const DEPTH_ALPHA = .2;
+const EXPR_ALPHA = .5;
+const MAX_DETECT_FAILURES = 30;
+const CAL_MOTION_YAWPITCH = .012;
+const CAL_MOTION_ROLL = .02;
+const CAL_FALLBACK_MULT = 3;
+var Avatar2DProvider = class {
+	constructor() {
+		this.renderer = new SatinSmileyRenderer(512);
+		this.videoHandle = null;
+		this.landmarker = null;
+		this.inputCanvas = document.createElement("canvas");
+		this.inputCtx = null;
+		this.rafId = null;
+		this.lastFrameAt = 0;
+		this.minFrameIntervalMs = 1e3 / DEFAULT_MAX_FPS;
+		this.stopped = false;
+		this.mediapipeModulePath = "";
+		this.mediapipeWasmPath = "";
+		this.faceLandmarkerModelPath = "";
+		this.detectFailures = 0;
+		this.current = structuredClonePose(AVATAR2D_NEUTRAL_POSE);
+		this.target = structuredClonePose(AVATAR2D_NEUTRAL_POSE);
+		this.lastFaceAt = 0;
+		this.calibrated = false;
+		this.nFrames = 0;
+		this.sum = {
+			yaw: 0,
+			pitch: 0,
+			roll: 0,
+			cx: 0,
+			cy: 0,
+			dist: 0,
+			faceH: 0
+		};
+		this.neutral = {
+			yaw: 0,
+			pitch: 0,
+			roll: 0,
+			cx: 0,
+			cy: 0,
+			dist: 1,
+			faceH: 1
+		};
+		this.calAttempts = 0;
+		this.prevCalYaw = NaN;
+		this.prevCalPitch = NaN;
+		this.prevCalRoll = NaN;
+		this.seeded = false;
+		this.medYaw = new Median();
+		this.medPitch = new Median();
+		this.medRoll = new Median();
+		this.usingRvfc = false;
+		this.rvfcHandle = null;
+		this.loop = (now) => {
+			if (this.stopped) return;
+			this.scheduleNextFrame();
+			if (now - this.lastFrameAt < this.minFrameIntervalMs) return;
+			const dtMs = clamp(this.lastFrameAt > 0 ? now - this.lastFrameAt : this.minFrameIntervalMs, 1, MAX_EMA_DT_MS);
+			this.lastFrameAt = now;
+			const video = this.videoHandle?.element;
+			if (!video || video.readyState < 2 || !this.landmarker) {
+				this.renderer.render(this.current);
+				return;
+			}
+			const vw = video.videoWidth;
+			const vh = video.videoHeight;
+			if (vw > 0 && vh > 0) {
+				if (!this.inputCtx) this.inputCtx = this.inputCanvas.getContext("2d");
+				if (this.inputCtx) {
+					if (this.inputCanvas.width !== vw || this.inputCanvas.height !== vh) {
+						this.inputCanvas.width = vw;
+						this.inputCanvas.height = vh;
+					}
+					this.inputCtx.drawImage(video, 0, 0, vw, vh);
+					let result = null;
+					try {
+						result = this.landmarker.detectForVideo(this.inputCanvas, now);
+						this.detectFailures = 0;
+					} catch {
+						result = null;
+						this.detectFailures += 1;
+						if (this.detectFailures >= MAX_DETECT_FAILURES) this.recreateLandmarker();
+					}
+					if (result) this.ingest(result, vw, vh, now);
+				}
+			}
+			if (now - this.lastFaceAt > FACE_LOST_MS) this.target = structuredClonePose(AVATAR2D_NEUTRAL_POSE);
+			this.smoothTowardTarget(dtMs);
+			this.renderer.render(this.current);
+		};
+	}
+	getCanvas() {
+		return this.renderer.getCanvas();
+	}
+	setState(state) {
+		this.renderer.setState(state);
+	}
+	async start(stream, options = {}) {
+		const assets = resolveAvatar2DAssets({
+			mediapipeModulePath: options.assets?.mediapipeModulePath,
+			mediapipeWasmPath: options.assets?.mediapipeWasmPath,
+			faceLandmarkerModelPath: options.assets?.faceLandmarkerModelPath
+		});
+		this.mediapipeModulePath = assets.mediapipeModulePath;
+		this.mediapipeWasmPath = assets.mediapipeWasmPath;
+		this.faceLandmarkerModelPath = assets.faceLandmarkerModelPath;
+		this.minFrameIntervalMs = 1e3 / (options.maxFps ?? DEFAULT_MAX_FPS);
+		this.videoHandle = createHiddenVideoElement(stream, { keepStreamAlive: true });
+		try {
+			this.renderer.init();
+			this.landmarker = await this.createLandmarker();
+			if (this.stopped) {
+				this.landmarker?.close();
+				this.landmarker = null;
+				return;
+			}
+			const video = this.videoHandle?.element;
+			this.usingRvfc = !!(video && asRvfc(video));
+			this.scheduleNextFrame();
+		} catch (error) {
+			this.stop();
+			throw error;
+		}
+	}
+	/** rVFC (one callback per camera frame) when available, else capped rAF. (§1.) */
+	scheduleNextFrame() {
+		if (this.stopped) return;
+		const video = this.videoHandle?.element;
+		const rvfc = this.usingRvfc && video ? asRvfc(video) : null;
+		if (rvfc) this.rvfcHandle = rvfc.requestVideoFrameCallback(this.loop);
+		else this.rafId = requestAnimationFrame(this.loop);
+	}
+	stop() {
+		this.stopped = true;
+		if (this.rafId != null) {
+			cancelAnimationFrame(this.rafId);
+			this.rafId = null;
+		}
+		const stoppingVideo = this.videoHandle?.element;
+		if (stoppingVideo && this.rvfcHandle != null) {
+			asRvfc(stoppingVideo)?.cancelVideoFrameCallback(this.rvfcHandle);
+			this.rvfcHandle = null;
+		}
+		this.landmarker?.close();
+		this.landmarker = null;
+		this.renderer.dispose();
+		this.videoHandle?.dispose();
+		this.videoHandle = null;
+	}
+	/** Loads the FaceLandmarker via the shared shielded init (see mediapipeShared). */
+	createLandmarker() {
+		return createFaceLandmarker({
+			mediapipeModulePath: this.mediapipeModulePath,
+			mediapipeWasmPath: this.mediapipeWasmPath,
+			faceLandmarkerModelPath: this.faceLandmarkerModelPath
+		});
+	}
+	/** MediaPipe result → target pose (averaged-neutral calibration). */
+	ingest(result, vw, vh, now) {
+		const raw0 = computeRawPose(result, vw, vh);
+		if (!raw0) return;
+		const raw = this.applyMedian(raw0);
+		this.lastFaceAt = now;
+		if (!this.calibrated) {
+			this.calAttempts += 1;
+			const dRollMotion = Math.atan2(Math.sin(raw.roll - this.prevCalRoll), Math.cos(raw.roll - this.prevCalRoll));
+			const moved = Number.isFinite(this.prevCalYaw) && (Math.abs(raw.yaw - this.prevCalYaw) > CAL_MOTION_YAWPITCH || Math.abs(raw.pitch - this.prevCalPitch) > CAL_MOTION_YAWPITCH || Math.abs(dRollMotion) > CAL_MOTION_ROLL);
+			this.prevCalYaw = raw.yaw;
+			this.prevCalPitch = raw.pitch;
+			this.prevCalRoll = raw.roll;
+			const fallback = this.calAttempts >= NEUTRAL_FRAMES * CAL_FALLBACK_MULT;
+			if (!moved || fallback) {
+				this.nFrames += 1;
+				this.sum.yaw += raw.yaw;
+				this.sum.pitch += raw.pitch;
+				this.sum.roll += raw.roll;
+				this.sum.cx += raw.eyeMidX;
+				this.sum.cy += raw.eyeMidY;
+				this.sum.dist += raw.eyeDist;
+				this.sum.faceH += raw.faceH;
+			}
+			if (this.nFrames >= NEUTRAL_FRAMES) {
+				const n = this.nFrames;
+				this.neutral = {
+					yaw: clamp(this.sum.yaw / n, -AVATAR2D_NEUTRAL_BIAS.yaw, AVATAR2D_NEUTRAL_BIAS.yaw),
+					pitch: this.sum.pitch / n,
+					roll: clamp(this.sum.roll / n, -AVATAR2D_NEUTRAL_BIAS.roll, AVATAR2D_NEUTRAL_BIAS.roll),
+					cx: this.sum.cx / n,
+					cy: this.sum.cy / n,
+					dist: this.sum.dist / n || 1,
+					faceH: this.sum.faceH / n || 1
+				};
+				this.calibrated = true;
+			}
+			return;
+		}
+		const mapped = mapToPose(raw, this.neutral, AVATAR2D_POSE_CONFIG);
+		const { blink, mouthOpen, smile } = blinkMouthFromBlendshapes(result);
+		this.target = {
+			tracked: true,
+			headEuler: { ...mapped.headEuler },
+			rootOffset: { ...mapped.rootOffset },
+			depth: mapped.depth,
+			blink,
+			mouthOpen,
+			smile
+		};
+		if (!this.seeded) {
+			copyPoseInto(this.current, this.target);
+			this.seeded = true;
+		}
+	}
+	/**
+	* Outlier rejection (FACE_AVATAR.md → Pose pipeline): when the face is small in
+	* frame the detector emits single-frame spikes the deadzone/EMA can't reject —
+	* median-filter yaw/pitch/roll first. When the face is near, pass through and
+	* reset the buffers (no stale samples across distance regimes).
+	*/
+	applyMedian(raw) {
+		if (!(raw.faceSizeRatio !== void 0 && raw.faceSizeRatio < MEDIAN_FACE_RATIO)) {
+			this.medYaw.reset();
+			this.medPitch.reset();
+			this.medRoll.reset();
+			return raw;
+		}
+		return {
+			...raw,
+			yaw: this.medYaw.filter(raw.yaw),
+			pitch: this.medPitch.filter(raw.pitch),
+			roll: this.medRoll.filter(raw.roll)
+		};
+	}
+	smoothTowardTarget(dtMs) {
+		const c = this.current;
+		const t = this.target;
+		const ha = dtAlpha(HEAD_ALPHA, dtMs);
+		const pa = dtAlpha(POS_ALPHA, dtMs);
+		const da = dtAlpha(DEPTH_ALPHA, dtMs);
+		const ea = dtAlpha(EXPR_ALPHA, dtMs);
+		c.tracked = t.tracked;
+		c.headEuler.x += (t.headEuler.x - c.headEuler.x) * ha;
+		c.headEuler.y += (t.headEuler.y - c.headEuler.y) * ha;
+		c.headEuler.z += (t.headEuler.z - c.headEuler.z) * ha;
+		c.rootOffset.x += (t.rootOffset.x - c.rootOffset.x) * pa;
+		c.rootOffset.y += (t.rootOffset.y - c.rootOffset.y) * pa;
+		c.depth += (t.depth - c.depth) * da;
+		c.blink.left += (t.blink.left - c.blink.left) * ea;
+		c.blink.right += (t.blink.right - c.blink.right) * ea;
+		c.mouthOpen += (t.mouthOpen - c.mouthOpen) * ea;
+		c.smile += (t.smile - c.smile) * ea;
+	}
+	recreateLandmarker() {
+		this.detectFailures = 0;
+		this.landmarker?.close();
+		this.landmarker = null;
+		this.createLandmarker().then((lm) => {
+			if (this.stopped) {
+				lm.close();
+				return;
+			}
+			this.landmarker = lm;
+		}).catch(() => {});
+	}
+};
+function structuredClonePose(p) {
+	return {
+		tracked: p.tracked,
+		headEuler: { ...p.headEuler },
+		rootOffset: { ...p.rootOffset },
+		depth: p.depth,
+		blink: { ...p.blink },
+		mouthOpen: p.mouthOpen,
+		smile: p.smile
+	};
+}
+/** Copy src's values INTO dst's existing (mutated-in-place) objects — used to
+* seed the smoother on the first tracked frame without reallocating `current`. */
+function copyPoseInto(dst, src) {
+	dst.tracked = src.tracked;
+	dst.headEuler.x = src.headEuler.x;
+	dst.headEuler.y = src.headEuler.y;
+	dst.headEuler.z = src.headEuler.z;
+	dst.rootOffset.x = src.rootOffset.x;
+	dst.rootOffset.y = src.rootOffset.y;
+	dst.depth = src.depth;
+	dst.blink.left = src.blink.left;
+	dst.blink.right = src.blink.right;
+	dst.mouthOpen = src.mouthOpen;
+	dst.smile = src.smile;
+}
+/** Factory used by the avatar actor's provider selection (2D satin-face avatar). */
+function createProvider() {
+	return new Avatar2DProvider();
+}
+
+//#endregion
+export { createProvider };