@incodetech/core 2.1.1 → 2.2.0-rc.1

package/dist/Actor-iTq7YY48.d.ts

@@ -0,0 +1 @@
+import "./StateMachine-EDpYWy0i.js";

package/dist/BrowserDiagnosticsCryptoProvider-BwGL3Lmi.esm.js

@@ -0,0 +1,95 @@
+//#region ../infra/src/crypto/truesightKey.ts
+/** Interim P1 key id — the BE looks up the AES key by this label. */
+const TRUESIGHT_KID = "truesight-v1";
+const KEY_LENGTH_BYTES = 32;
+/** Recovers the key from its two obfuscated halves. Throws on malformed input. */
+function decodeTruesightKey(s0Base64, s1Base64) {
+	const s0 = fromBase64(s0Base64);
+	const s1 = fromBase64(s1Base64);
+	if (s0.length !== s1.length || s0.length === 0) throw new Error("truesight key halves are malformed");
+	const key = new Uint8Array(s0.length);
+	for (let i = 0; i < key.length; i += 1) key[i] = s1[(i + 7) % s1.length] ^ s0[i];
+	return key;
+}
+/**
+* The bundle's key, decoded lazily — `null` when this build carries no key
+* (defines absent → collect-only mode, uploads disabled). Returns a fresh
+* copy per call so callers may zero their copy after use.
+*/
+function getTruesightKey() {
+	try {
+		const key = decodeTruesightKey("Z5SNwx3tvo9MEpKXEnanT6Onh7iUZMrZiYA1RUZKbko=", "QHRMF00NdMLP3SR0Z2jjNiffdu+wAATSt208l8XIJhQ=");
+		return key.length === KEY_LENGTH_BYTES ? key : null;
+	} catch {
+		return null;
+	}
+}
+function fromBase64(value) {
+	return Uint8Array.from(atob(value), (char) => char.charCodeAt(0));
+}
+//#endregion
+//#region ../infra/src/providers/browser/BrowserDiagnosticsCryptoProvider.ts
+/**
+* Browser sealer for TrueSight diagnostics (ENG-48677 plan §1.5): JSON string →
+* gzip via native CompressionStream → AES-256-GCM via WebCrypto → contract
+* envelope. Designed to be loaded as a LAZY chunk — zero bytes on the host
+* page's critical path.
+*
+* The CryptoKey is imported once (non-extractable) and the raw bytes are zeroed
+* immediately after import; `getKeyBytes` must therefore return a fresh copy.
+*/
+var BrowserDiagnosticsCryptoProvider = class {
+	constructor(getKeyBytes = getTruesightKey, kid = TRUESIGHT_KID) {
+		this.getKeyBytes = getKeyBytes;
+		this.kid = kid;
+		this.keyPromise = null;
+	}
+	isSupported() {
+		return typeof crypto !== "undefined" && typeof crypto.subtle !== "undefined" && typeof crypto.getRandomValues === "function" && typeof CompressionStream !== "undefined";
+	}
+	async seal(plaintext) {
+		const [gz, key] = await Promise.all([gzipUtf8(plaintext), this.importKeyOnce()]);
+		const iv = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(12));
+		const additionalData = new TextEncoder().encode(`v1|A256GCM|gzip|${this.kid}`);
+		const sealed = new Uint8Array(await crypto.subtle.encrypt({
+			name: "AES-GCM",
+			iv,
+			additionalData
+		}, key, gz));
+		const tagStart = sealed.length - 16;
+		return {
+			version: 1,
+			alg: "A256GCM",
+			compression: "gzip",
+			kid: this.kid,
+			iv: toBase64Url(iv),
+			ciphertext: toBase64Url(sealed.subarray(0, tagStart)),
+			tag: toBase64Url(sealed.subarray(tagStart))
+		};
+	}
+	importKeyOnce() {
+		this.keyPromise ??= (async () => {
+			const bytes = this.getKeyBytes();
+			if (!bytes || bytes.length !== 32) throw new Error("TrueSight diagnostics key unavailable in this build");
+			const copy = new Uint8Array(bytes);
+			try {
+				return await crypto.subtle.importKey("raw", copy, { name: "AES-GCM" }, false, ["encrypt"]);
+			} finally {
+				copy.fill(0);
+				bytes.fill(0);
+			}
+		})();
+		return this.keyPromise;
+	}
+};
+async function gzipUtf8(text) {
+	const stream = new Blob([text]).stream().pipeThrough(new CompressionStream("gzip"));
+	return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+function toBase64Url(bytes) {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i += 1) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/u, "");
+}
+//#endregion
+export { BrowserDiagnosticsCryptoProvider };

package/dist/BrowserLazyImportProvider-BhoA957O.esm.js

@@ -0,0 +1,114 @@
+import { t as BrowserTimerProvider } from "./BrowserTimerProvider-BXhgNxLt.esm.js";
+//#region ../infra/src/providers/browser/BrowserLazyImportProvider.ts
+/**
+* Per-module {@link LazyImport} handle.
+*
+* Encapsulates the caching, deduplication, and optional-timeout logic for a
+* single lazily-imported module:
+*  - Caches the resolved module (via a dedicated `loaded` flag, so a module
+*    that legitimately resolves `undefined` is still cached) and returns it
+*    immediately on subsequent calls.
+*  - Deduplicates concurrent `load()` calls behind a single in-flight promise.
+*  - Optionally races the dynamic import against a configurable timeout (ms).
+*  - On timeout or import error: emits a `console.warn`, clears the in-flight
+*    promise so the next `load()` call retries, and resolves `undefined`.
+*
+* An attempt-generation token (`attempt`) guards against a stale import
+* mutating state after it has been superseded: when a load times out (or the
+* handle is `reset()`), the token is bumped so the still-pending import can no
+* longer write to `cachedValue` / `loaded`.
+*/
+var LazyImportHandle = class {
+	constructor(_loader, _options, _timer) {
+		this._loader = _loader;
+		this._options = _options;
+		this._timer = _timer;
+		this._loaded = false;
+		this._attempt = 0;
+	}
+	get() {
+		return this._cachedValue;
+	}
+	load() {
+		if (this._loaded) return Promise.resolve(this._cachedValue);
+		if (!this._inFlight) this._inFlight = this.startLoad();
+		return this._inFlight;
+	}
+	reset() {
+		this._cachedValue = void 0;
+		this._loaded = false;
+		this._inFlight = void 0;
+		this._attempt++;
+	}
+	startLoad() {
+		const attempt = ++this._attempt;
+		const { timeoutMs } = this._options;
+		let loaderResult;
+		try {
+			loaderResult = this._loader();
+		} catch (err) {
+			loaderResult = Promise.reject(err);
+		}
+		const loadPromise = loaderResult.then((value) => {
+			if (attempt === this._attempt) {
+				this._cachedValue = value;
+				this._loaded = true;
+			}
+			return value;
+		}, (err) => {
+			if (attempt === this._attempt) {
+				this.warnFailure(err);
+				this._inFlight = void 0;
+			}
+		});
+		if (timeoutMs === void 0) return loadPromise;
+		let timeoutHandle;
+		const timeoutPromise = new Promise((resolve) => {
+			timeoutHandle = this._timer.setTimeout(() => {
+				if (attempt === this._attempt) {
+					this.warnTimeout(timeoutMs);
+					this._inFlight = void 0;
+					this._attempt++;
+				}
+				resolve(void 0);
+			}, timeoutMs);
+		});
+		return Promise.race([loadPromise, timeoutPromise]).finally(() => {
+			if (timeoutHandle !== void 0) this._timer.clearTimeout(timeoutHandle);
+		});
+	}
+	warnFailure(err) {
+		const { label, moduleName } = this._options;
+		console.warn(`[${label}] Failed to load ${moduleName}; ${this.fallback()}`, err);
+	}
+	warnTimeout(timeoutMs) {
+		const { label, moduleName } = this._options;
+		console.warn(`[${label}] ${moduleName} failed to load within ${timeoutMs / 1e3}s; ${this.fallback()}`);
+	}
+	fallback() {
+		return this._options.disabledMessage ?? "module will be unavailable.";
+	}
+};
+/**
+* Concrete implementation of {@link ILazyImportCapability}.
+*
+* `create()` returns a per-module {@link LazyImportHandle}. The
+* {@link ITimerCapability} is injected so tests can replace the real
+* `setTimeout`/`clearTimeout` with a controllable fake.
+*/
+var BrowserLazyImportProvider = class BrowserLazyImportProvider {
+	constructor(timer) {
+		this._timer = timer ?? BrowserTimerProvider.getInstance();
+	}
+	static getInstance() {
+		return this._instance ??= new BrowserLazyImportProvider();
+	}
+	static resetInstance() {
+		this._instance = void 0;
+	}
+	create(loader, options) {
+		return new LazyImportHandle(loader, options, this._timer);
+	}
+};
+//#endregion
+export { BrowserLazyImportProvider as t };

package/dist/{BrowserStorageProvider-CBHBhKQN.esm.js → BrowserStorageProvider-k-FDkC4W.esm.js}

@@ -1,5 +1,4 @@
-import { n as resolveLocalStorage } from "./MotionSensorProvider-BHuHoYvJ.esm.js";
-
+import { t as resolveLocalStorage } from "./safeStorage-Ep56I-f_.esm.js";
 //#region ../infra/src/providers/browser/BrowserStorageProvider.ts
 /**
 * Browser-based storage provider wrapping localStorage.
@@ -64,6 +63,5 @@ var BrowserStorageProvider = class {
 		storage.clear();
 	}
 };
-
 //#endregion
-export { BrowserStorageProvider as t };
+export { BrowserStorageProvider as t };

package/dist/{BrowserTimerProvider-CHloo0eQ.esm.js → BrowserTimerProvider-BXhgNxLt.esm.js}

@@ -17,6 +17,5 @@ var BrowserTimerProvider = class BrowserTimerProvider {
 		clearInterval(handle);
 	}
 };
-
 //#endregion
-export { BrowserTimerProvider as t };
+export { BrowserTimerProvider as t };

package/dist/{BrowserVisibilityObserverProvider-GBS6XSii.esm.js → BrowserVisibilityObserverProvider-BX1BiLDK.esm.js}

@@ -13,6 +13,5 @@ var BrowserVisibilityObserverProvider = class {
 		};
 	}
 };
-
 //#endregion
-export { BrowserVisibilityObserverProvider as t };
+export { BrowserVisibilityObserverProvider as t };

package/dist/Face2DProvider-UUQt_vRC.esm.js

@@ -0,0 +1,437 @@
+import { t as createHiddenVideoElement } from "./video-BtSWtHy1.esm.js";
+import { a as publishAvatarStats, r as isAvatarStatsEnabled, t as createAvatarStatsReporter } from "./avatarStats-CdUOb3VD.esm.js";
+import { n as createFaceLandmarker, t as asRvfc } from "./mediapipeShared-B6oNoXEQ.esm.js";
+import { i as detectWorkerSourceInstrumentation, o as createFramePacer, r as createTrackProcessor } from "./privacyLensWorker-DI-Rg83h.esm.js";
+import { a as createAvatar2DPoseCore, c as SatinSmileyRenderer, i as AVATAR2D_POSE_CORE_DEFAULTS, l as resolveAvatar2DAssets, n as buildAvatar2DTrackWorkerSource, o as createAvatar2DPoseCoreDeps, r as canUseAvatar2DWorker, s as extractCompactFace, t as buildAvatar2DRenderWorkerSource, takeWarmAvatar2DWorker } from "./avatar2dWarm-DqucNFX4.esm.js";
+//#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 DETECT_MAX_EDGE = 320;
+const DETECT_MIN_INTERVAL_MS = 66;
+const DETECT_INTERVAL_TOLERANCE_MS = 8;
+const MAX_DETECT_FAILURES = 30;
+const WORKER_START_TIMEOUT_MS = 5e3;
+/** Grace period for the worker to ack 'stop' before hard termination. */
+const WORKER_STOP_GRACE_MS = 500;
+/** Cadence of the main→worker dev statsEnabled/state-override bridge. */
+const BRIDGE_INTERVAL_MS = 250;
+/** Dev override global (poc demos): workers can't see it, so it is bridged. */
+function readAvatarStateOverride() {
+	const v = globalThis.__incodeAvatarState;
+	return v === "detecting" || v === "success" || v === "error" ? v : null;
+}
+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.pacer = createFramePacer(DEFAULT_MAX_FPS);
+		this.stats = createAvatarStatsReporter("avatar-2d");
+		this.stopped = false;
+		this.renderWorker = null;
+		this.trackWorker = null;
+		this.clonedTrack = null;
+		this.bridgeId = null;
+		this.lastBridgedStatsEnabled = false;
+		this.lastBridgedOverride = null;
+		this.mediapipeModulePath = "";
+		this.mediapipeWasmPath = "";
+		this.faceLandmarkerModelPath = "";
+		this.detectFailures = 0;
+		this.poseCore = createAvatar2DPoseCore(AVATAR2D_POSE_CORE_DEFAULTS, createAvatar2DPoseCoreDeps());
+		this.lastDetectAt = 0;
+		this.usingRvfc = false;
+		this.rvfcHandle = null;
+		this.lastSetState = null;
+		this.loop = (now) => {
+			if (this.stopped) return;
+			this.scheduleNextFrame();
+			if (!this.pacer.shouldRender(now)) {
+				this.stats.frameDropped();
+				return;
+			}
+			const measure = isAvatarStatsEnabled();
+			const frameStart = measure ? performance.now() : 0;
+			let detectMs;
+			const video = this.videoHandle?.element;
+			if (video && video.readyState >= 2 && this.landmarker) this.detectOnMainThread(video, now, measure, (ms) => {
+				detectMs = ms;
+			});
+			this.renderer.render(this.poseCore.tick(now));
+			if (measure) this.stats.frameRendered(now, detectMs, performance.now() - frameStart);
+		};
+	}
+	getCanvas() {
+		return this.renderer.getCanvas();
+	}
+	setState(state) {
+		this.renderer.setState(state);
+		this.lastSetState = state;
+		try {
+			this.renderWorker?.postMessage({
+				type: "state",
+				state
+			});
+		} catch {}
+	}
+	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;
+		const maxFps = options.maxFps ?? DEFAULT_MAX_FPS;
+		this.pacer = createFramePacer(maxFps);
+		this.poseCore = createAvatar2DPoseCore({
+			...AVATAR2D_POSE_CORE_DEFAULTS,
+			dtSeedMs: 1e3 / maxFps
+		}, createAvatar2DPoseCoreDeps());
+		if (await this.tryStartWorker(stream, maxFps)) return;
+		if (this.stopped) return;
+		this.videoHandle = createHiddenVideoElement(stream, { keepStreamAlive: true });
+		try {
+			this.renderer.init();
+			const video = this.videoHandle.element;
+			this.usingRvfc = !!asRvfc(video);
+			this.scheduleNextFrame();
+			this.startMainTracking();
+		} catch (error) {
+			this.stop();
+			throw error;
+		}
+	}
+	/**
+	* Background landmarker bring-up for the MAIN-THREAD path. On failure the
+	* avatar stays in its neutral searching state (the face remains concealed)
+	* rather than tearing down the already-mounted canvas.
+	*/
+	async startMainTracking() {
+		try {
+			this.landmarker = await this.createLandmarker();
+			if (this.stopped) {
+				this.landmarker?.close();
+				this.landmarker = null;
+				return;
+			}
+			this.stats.dispose();
+			this.stats = createAvatarStatsReporter("avatar-2d", "main");
+		} catch (error) {
+			console.warn("[face-avatar] avatar-2d tracking failed to start — avatar stays in searching state (capture unaffected)", 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;
+		this.stats.dispose();
+		if (this.bridgeId != null) {
+			clearInterval(this.bridgeId);
+			this.bridgeId = null;
+		}
+		if (this.renderWorker || this.trackWorker) {
+			try {
+				this.renderWorker?.postMessage({ type: "stop" });
+				this.trackWorker?.postMessage({ type: "stop" });
+			} catch {}
+			const pendingRender = this.renderWorker;
+			const pendingTrack = this.trackWorker;
+			setTimeout(() => {
+				if (this.renderWorker === pendingRender || this.trackWorker === pendingTrack) this.finalizeWorkers();
+			}, WORKER_STOP_GRACE_MS);
+		}
+		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;
+	}
+	/**
+	* Worker transport, TWO workers: clone the track, feed it to a
+	* MediaStreamTrackProcessor, adopt (or boot) the TRACK worker, boot the
+	* RENDER worker, wire them with a MessageChannel, transfer the renderer's
+	* canvas + the readable, and wait for the render worker's ms-fast 'started'
+	* handshake (the track worker's MediaPipe bring-up runs in the background —
+	* or already ran via the tutorial warm-up). Any failure tears down —
+	* recreating the renderer if its canvas was already transferred — and
+	* returns false so the main-thread path takes over. Never throws.
+	*/
+	async tryStartWorker(stream, maxFps) {
+		if (!canUseAvatar2DWorker()) return false;
+		const sourceTrack = stream.getVideoTracks()[0];
+		if (!sourceTrack) return false;
+		let track = null;
+		let processor;
+		try {
+			track = sourceTrack.clone();
+			processor = createTrackProcessor(track);
+		} catch {
+			track?.stop();
+			return false;
+		}
+		let trackWorker = takeWarmAvatar2DWorker({
+			mediapipeModulePath: this.mediapipeModulePath,
+			mediapipeWasmPath: this.mediapipeWasmPath,
+			faceLandmarkerModelPath: this.faceLandmarkerModelPath
+		});
+		let trackBlobUrl = null;
+		if (!trackWorker) {
+			const trackSource = buildAvatar2DTrackWorkerSource();
+			const trackInstrumenter = detectWorkerSourceInstrumentation(trackSource);
+			if (trackInstrumenter) {
+				console.error(`[face-avatar] avatar-2d worker source was instrumented by "${trackInstrumenter}" and cannot run in a worker; using the slower main-thread avatar. Exclude packages/infra from that transform (see docs/features/FACE_AVATAR.md → Worker transport).`);
+				track.stop();
+				return false;
+			}
+			try {
+				trackBlobUrl = URL.createObjectURL(new Blob([trackSource], { type: "text/javascript" }));
+				trackWorker = new Worker(trackBlobUrl);
+			} catch {
+				if (trackBlobUrl) URL.revokeObjectURL(trackBlobUrl);
+				track.stop();
+				return false;
+			}
+		}
+		const renderSource = buildAvatar2DRenderWorkerSource();
+		const renderInstrumenter = detectWorkerSourceInstrumentation(renderSource);
+		let renderWorker = null;
+		let renderBlobUrl = null;
+		if (!renderInstrumenter) try {
+			renderBlobUrl = URL.createObjectURL(new Blob([renderSource], { type: "text/javascript" }));
+			renderWorker = new Worker(renderBlobUrl);
+		} catch {
+			if (renderBlobUrl) URL.revokeObjectURL(renderBlobUrl);
+			renderBlobUrl = null;
+			renderWorker = null;
+		}
+		if (!renderWorker) {
+			if (renderInstrumenter) console.error(`[face-avatar] avatar-2d worker source was instrumented by "${renderInstrumenter}" and cannot run in a worker; using the slower main-thread avatar. Exclude packages/infra from that transform (see docs/features/FACE_AVATAR.md → Worker transport).`);
+			trackWorker.terminate();
+			if (trackBlobUrl) URL.revokeObjectURL(trackBlobUrl);
+			track.stop();
+			return false;
+		}
+		trackWorker.onmessage = (event) => {
+			const message = event.data;
+			if (message?.type === "trackingFatal") {
+				console.warn("[face-avatar] avatar-2d worker tracking failed to start — avatar stays in searching state (capture unaffected):", message.message);
+				trackWorker.terminate();
+				if (this.trackWorker === trackWorker) this.trackWorker = null;
+				track.stop();
+				if (this.clonedTrack === track) this.clonedTrack = null;
+			} else if (message?.type === "stopped") {
+				trackWorker.terminate();
+				if (this.trackWorker === trackWorker) this.trackWorker = null;
+				track.stop();
+				if (this.clonedTrack === track) this.clonedTrack = null;
+			}
+		};
+		trackWorker.onerror = () => {
+			console.warn("[face-avatar] avatar-2d track worker error — pose frozen (capture unaffected)");
+			trackWorker.terminate();
+			if (this.trackWorker === trackWorker) this.trackWorker = null;
+			track.stop();
+			if (this.clonedTrack === track) this.clonedTrack = null;
+		};
+		let started;
+		try {
+			const channel = new MessageChannel();
+			const offscreen = this.renderer.getCanvas().transferControlToOffscreen();
+			const handshakeWorker = renderWorker;
+			const startedTrackWorker = trackWorker;
+			started = await new Promise((resolve) => {
+				const timer = setTimeout(() => resolve(false), WORKER_START_TIMEOUT_MS);
+				handshakeWorker.onmessage = (event) => {
+					if (event.data?.type === "started") {
+						clearTimeout(timer);
+						resolve(true);
+					} else if (event.data?.type === "fatal") {
+						clearTimeout(timer);
+						resolve(false);
+					}
+				};
+				handshakeWorker.onerror = () => {
+					clearTimeout(timer);
+					resolve(false);
+				};
+				handshakeWorker.postMessage({
+					type: "start",
+					canvas: offscreen,
+					port: channel.port1,
+					maxFps,
+					poseConfig: {
+						...AVATAR2D_POSE_CORE_DEFAULTS,
+						dtSeedMs: 1e3 / maxFps
+					},
+					statsEnabled: isAvatarStatsEnabled()
+				}, [offscreen, channel.port1]);
+				startedTrackWorker.postMessage({
+					type: "start",
+					readable: processor.readable,
+					port: channel.port2,
+					mediapipeModulePath: this.mediapipeModulePath,
+					mediapipeWasmPath: this.mediapipeWasmPath,
+					faceLandmarkerModelPath: this.faceLandmarkerModelPath,
+					detectMaxEdge: DETECT_MAX_EDGE,
+					detectMinIntervalMs: DETECT_MIN_INTERVAL_MS,
+					detectIntervalToleranceMs: DETECT_INTERVAL_TOLERANCE_MS
+				}, [processor.readable, channel.port2]);
+			});
+		} catch {
+			renderWorker.terminate();
+			trackWorker.terminate();
+			if (renderBlobUrl) URL.revokeObjectURL(renderBlobUrl);
+			if (trackBlobUrl) URL.revokeObjectURL(trackBlobUrl);
+			track.stop();
+			if (!this.stopped) this.renderer = new SatinSmileyRenderer(512);
+			return false;
+		}
+		if (renderBlobUrl) URL.revokeObjectURL(renderBlobUrl);
+		if (trackBlobUrl) URL.revokeObjectURL(trackBlobUrl);
+		if (!started || this.stopped) {
+			renderWorker.terminate();
+			trackWorker.terminate();
+			track.stop();
+			if (!this.stopped) this.renderer = new SatinSmileyRenderer(512);
+			return this.stopped;
+		}
+		this.renderWorker = renderWorker;
+		this.trackWorker = trackWorker;
+		this.clonedTrack = track;
+		this.lastBridgedStatsEnabled = isAvatarStatsEnabled();
+		this.lastBridgedOverride = null;
+		renderWorker.onmessage = (event) => {
+			const message = event.data;
+			if (message?.type === "stats") {
+				if (!this.stopped) publishAvatarStats(message.snapshot);
+			} else if (message?.type === "stopped") {
+				this.renderWorker?.terminate();
+				this.renderWorker = null;
+			}
+		};
+		renderWorker.onerror = () => {
+			console.warn("[face-avatar] avatar-2d render worker error — avatar frozen (capture unaffected)");
+			if (this.bridgeId != null) {
+				clearInterval(this.bridgeId);
+				this.bridgeId = null;
+			}
+			this.finalizeWorkers();
+		};
+		if (this.lastSetState) renderWorker.postMessage({
+			type: "state",
+			state: this.lastSetState
+		});
+		this.bridgeId = setInterval(() => {
+			if (!this.renderWorker) return;
+			const enabled = isAvatarStatsEnabled();
+			if (enabled !== this.lastBridgedStatsEnabled) {
+				this.lastBridgedStatsEnabled = enabled;
+				this.renderWorker.postMessage({
+					type: "statsEnabled",
+					value: enabled
+				});
+			}
+			const override = readAvatarStateOverride();
+			if (override !== this.lastBridgedOverride) {
+				this.lastBridgedOverride = override;
+				this.renderWorker.postMessage({
+					type: "override",
+					state: override
+				});
+			}
+		}, BRIDGE_INTERVAL_MS);
+		return true;
+	}
+	finalizeWorkers() {
+		this.renderWorker?.terminate();
+		this.renderWorker = null;
+		this.trackWorker?.terminate();
+		this.trackWorker = null;
+		this.clonedTrack?.stop();
+		this.clonedTrack = null;
+	}
+	/** Loads the FaceLandmarker via the shared shielded init (see mediapipeShared). */
+	createLandmarker() {
+		return createFaceLandmarker({
+			mediapipeModulePath: this.mediapipeModulePath,
+			mediapipeWasmPath: this.mediapipeWasmPath,
+			faceLandmarkerModelPath: this.faceLandmarkerModelPath
+		});
+	}
+	/** Main-thread detect fallback: downscale → detectForVideo → ingest. */
+	detectOnMainThread(video, now, measure, onDetectMs) {
+		if (!this.landmarker) return;
+		const vw = video.videoWidth;
+		const vh = video.videoHeight;
+		const detectDue = now - this.lastDetectAt >= DETECT_MIN_INTERVAL_MS - DETECT_INTERVAL_TOLERANCE_MS;
+		if (vw > 0 && vh > 0 && detectDue) {
+			if (!this.inputCtx) this.inputCtx = this.inputCanvas.getContext("2d");
+			if (this.inputCtx) {
+				this.lastDetectAt = now;
+				const dscale = Math.min(1, DETECT_MAX_EDGE / Math.max(vw, vh));
+				const dw = Math.max(1, Math.round(vw * dscale));
+				const dh = Math.max(1, Math.round(vh * dscale));
+				if (this.inputCanvas.width !== dw || this.inputCanvas.height !== dh) {
+					this.inputCanvas.width = dw;
+					this.inputCanvas.height = dh;
+				}
+				this.inputCtx.drawImage(video, 0, 0, dw, dh);
+				let result = null;
+				const detectStart = measure ? performance.now() : 0;
+				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 (measure) onDetectMs(performance.now() - detectStart);
+				this.poseCore.ingest(result ? extractCompactFace(result) : null, dw, dh, now);
+			}
+		}
+	}
+	recreateLandmarker() {
+		this.detectFailures = 0;
+		this.landmarker?.close();
+		this.landmarker = null;
+		this.createLandmarker().then((lm) => {
+			if (this.stopped) {
+				lm.close();
+				return;
+			}
+			this.landmarker = lm;
+		}).catch(() => {});
+	}
+};
+/** Factory used by the avatar actor's provider selection (2D satin-face avatar). */
+function createProvider() {
+	return new Avatar2DProvider();
+}
+//#endregion
+export { Avatar2DProvider, createProvider };