@beltec/face-gate 0.1.0 → 0.1.2

package/README.md

@@ -1,218 +1,218 @@
-# @beltec/face-gate
-
-**Face Gate, uma solução BelTec** — validação de fotos de rosto para o cadastro de visitantes e moradores no
-controle de acesso. Este pacote traz:
-
-- **`<FaceGate>`** (React): webcam com validação em **tempo real** — mira que segue o rosto, orientação do que
-  corrigir, captura automática só quando a pessoa fica parada com tudo aprovado, scanner sobre a foto e a foto
-  final (com o fundo removido, se contratado).
-- **`@beltec/face-gate/server`** (Node/Next): guarda a sua chave, emite o ticket do navegador e valida arquivos.
-
-O `client_secret` **nunca** vai ao navegador: o seu servidor pede um ticket de uso único (60 s) e só ele chega à
-página.
-
-```
-navegador ──POST /api/face-gate/ticket──▶ seu servidor ──chave──▶ Face Gate API
-navegador ◀──────── ticket (60 s) ────────┘
-navegador ══ WebSocket (ticket) ══▶ Face Gate API  (quadros ao vivo → captura → resultado)
-```
-
-## Instalação
-
-```bash
-npm install @beltec/face-gate
-```
-
-React 18+ no navegador; Node 18.17+ no servidor. Crie a chave no portal do Face Gate
-(**Chaves de acesso**): você recebe o `client_id` e o `client_secret` (este aparece uma vez só).
-
-```bash
-# .env do seu servidor
-FACE_GATE_CLIENT_ID=...
-FACE_GATE_CLIENT_SECRET=...
-```
-
-## Next.js (App Router)
-
-**1. Rota que emite o ticket** — `app/api/face-gate/ticket/route.ts`
-
-```ts
-import { createFaceGate } from "@beltec/face-gate/server";
-
-const faceGate = createFaceGate({
-  clientId: process.env.FACE_GATE_CLIENT_ID!,
-  clientSecret: process.env.FACE_GATE_CLIENT_SECRET!,
-});
-
-// Só usuários logados no SEU sistema abrem a câmera (cada captura consome tokens do seu plano).
-export const POST = faceGate.ticketHandler({
-  authorize: async (req) => Boolean(await getSessionFromYourApp(req)),
-});
-```
-
-**2. A tela** — um Client Component
-
-```tsx
-"use client";
-import { FaceGate } from "@beltec/face-gate";
-import "@beltec/face-gate/styles.css";
-
-export function CadastroFoto() {
-  return (
-    <FaceGate
-      clean // devolve a foto sem fundo (serviço "validar e remover fundo" contratado)
-      getTicket={async () => {
-        const r = await fetch("/api/face-gate/ticket", { method: "POST" });
-        if (!r.ok) throw new Error("Não foi possível abrir a câmera");
-        return r.json();
-      }}
-      onCapture={({ image, result }) => {
-        if (result.accepted) salvarFoto(image); // data URL (PNG sem fundo ou JPEG do quadro)
-      }}
-      onError={(e) => console.warn(e.code, e.message)}
-    />
-  );
-}
-```
-
-## Validar um arquivo (sem webcam)
-
-```ts
-import { createFaceGate } from "@beltec/face-gate/server";
-
-const faceGate = createFaceGate({ clientId, clientSecret });
-const result = await faceGate.validate(fileBuffer, { clean: true, model: "birefnet-portrait" });
-
-result.accepted;        // true | false
-result.hard_fails;      // ex.: ["eyes_closed", "glasses_sunglasses"]
-result.cleaned_image;   // PNG sem fundo (data URL), quando clean
-result.usage?.tokens;   // tokens gastos nesta análise
-```
-
-Com melhoria de imagem: `faceGate.validate(fileBuffer, { enhance: "classic" })` (veja abaixo).
-
-Express/Fastify funcionam igual: use `createStreamTicket()` na sua rota e devolva `{ ticket, url }` ao navegador.
-
-## `<FaceGate>` — propriedades
-
-| Prop | Tipo | Padrão | |
-|---|---|---|---|
-| `getTicket` | `() => Promise<{ ticket, url }>` | — | chama a sua rota de ticket |
-| `onCapture` | `({ image, frame, result }) => void` | — | foto capturada e validada |
-| `onLive` | `(result) => void` | — | cada quadro analisado ao vivo |
-| `onError` | `(error: FaceGateError) => void` | — | câmera negada, limite de tokens, rede… |
-| `clean` | `boolean` | `false` | remover o fundo da foto capturada |
-| `model` | `"u2net" \| "u2netp" \| "birefnet-portrait"` | servidor | modelo da remoção de fundo |
-| `device` | `"cpu" \| "gpu"` | servidor | onde rodar a remoção de fundo |
-| `enhance` | `"classic" \| "gfpgan" \| null` | `null` | melhorar a foto capturada antes de validar (serviço "validar com melhoria") |
-| `thresholds` | `Record<string, number>` | servidor | limiares (nomes de `GET /v1/thresholds`) |
-| `autoFrame` | `boolean` | `true` | enquadramento automático: a imagem aproxima e acompanha o rosto, mantendo-o no centro; a foto capturada é esse recorte e só sai com o rosto centralizado (tolerância de 8%, ou a sua em `thresholds` se for mais rígida). Ignora as tarjas pretas que algumas câmeras acrescentam |
-| `mirror` | `boolean` | `true` | prévia espelhada, como um espelho (a foto enviada e a final não são espelhadas) |
-| `autoStart` | `boolean` | `false` | ligar a câmera ao montar |
-| `intro` | `boolean` | `true` | abertura animada do escudo |
-| `watermark` | `boolean` | `true` | escudo no canto do vídeo |
-| `labels` | `Partial<FaceGateLabels>` | pt-BR | troque qualquer texto |
-
-### Aparência
-
-Os estilos usam o prefixo `.fg-` e variáveis CSS:
-
-```css
-.minha-tela .fg-root {
-  --fg-accent: #c9a43e;      /* mira, botão, barra de "fique parado" */
-  --fg-accent-text: #1d2125; /* texto sobre o botão */
-  --fg-surface: #1d2125;     /* fundo do vídeo */
-  --fg-radius: 12px;
-}
-```
-
-Respeita `prefers-reduced-motion` (sem animações).
-
-## Melhoria de imagem
-
-Serviço contratável **"Validar com melhoria"** (scope `validate_enhance`). A API melhora a foto, valida a
-versão melhorada e devolve `enhancement` com o resultado **antes** (original) e **depois** (melhorada) e a
-imagem melhorada (`enhancement.enhanced_image`, JPEG). No `<FaceGate enhance="classic">`, só a foto
-capturada passa pela melhoria (os quadros ao vivo não), o `onCapture` entrega a melhorada em `image` e a
-tela mostra o selo "Imagem melhorada".
-
-| Método | O que faz | Custo |
-|---|---|---|
-| `classic` | balanço de branco, exposição, contraste local, redução de ruído e nitidez leve. Determinística, não altera o rosto | baixo |
-| `gfpgan` | a clássica + restauração do rosto com IA (GFPGAN). Recria detalhes do rosto: a resposta traz o aviso `face_restored_ai` e o componente mostra o alerta | alto |
-
-**Regra:** a melhoria só corrige luz (`poor_lighting`, `overexposed`) e rosto não encontrado por falta de
-luz (`no_face`). As demais falhas da foto original — desfoque, olhos fechados, óculos escuros, pose… —
-continuam reprovando (`enhancement.carried_over`). Com `clean`, o fundo é removido da foto melhorada (exige
-também o serviço "validar e remover fundo").
-
-**Tokens:** a validação roda duas vezes (antes e depois) e soma a etapa `usage.breakdown.enhance`
-(a clássica é barata; o GFPGAN custa bem mais).
-
-## Avatar
-
-Serviço **Avatar** contratado (`POST /v1/photos/avatar`): valida a foto e, se aprovada, devolve o avatar só com a
-pessoa do rosto em foco — o fundo e outros elementos ou pessoas são removidos —, recortado centrado no rosto.
-
-```ts
-import { createFaceGate } from "@beltec/face-gate/server";
-
-const faceGate = createFaceGate({ clientId, clientSecret });
-const r = await faceGate.avatar(fileBuffer, {
-  shape: "round",            // "round" (padrão; fora do círculo transparente) | "square"
-  size: 512,                 // 64 a 1024
-  backgroundColor: "#1d252a", // ou background: <imagem> (tem prioridade); sem nenhum = PNG transparente
-  margin: 25,                 // só com fundo: % do quadro deixado para o fundo (0 a 60)
-  layout: "bottom",           // só com fundo: "center" | "bottom" | "left" | "right"
-});
-
-if (r.accepted) r.avatar_image; // data:image/png;base64,...
-else r.hard_fails;             // sem avatar: os mesmos motivos da validação
-```
-
-| Opção | Tipo | Padrão | |
-|---|---|---|---|
-| `shape` | `"round" \| "square"` | `"round"` | formato do recorte |
-| `size` | `number` | `512` | lado em pixels (64 a 1024) |
-| `backgroundColor` | `string` | — | cor sólida `#RRGGBB` |
-| `background` | `Blob \| ArrayBuffer \| Uint8Array` | — | imagem de fundo (preenche o quadro) |
-| `template` | `number` | — | id de um **template de avatar** salvo no portal (Avatares): formato, tamanho, fundo e enquadramento prontos, sem reenviar a imagem; as outras opções têm prioridade |
-| `backgroundPosition` | `{ x?, y?, zoom? }` | centro, `zoom` 100 | **só com `background`**: qual parte da imagem aparece — `x`/`y` de 0 a 100 (50 = centro, como o `object-position` do CSS) e `zoom` de 100 a 300 % |
-| `margin` | `number` | `0` | **só com fundo**: % do quadro deixado para o fundo em volta da pessoa (0 a 60) |
-| `layout` | `"center" \| "bottom" \| "left" \| "right"` | `"center"` | **só com fundo**: onde a pessoa fica (centro, apoiada na base, base à esquerda/direita) |
-| `model` / `device` | | servidor (BiRefNet) | modelo de remoção de fundo que separa a pessoa |
-| `thresholds` | `Record<string, number>` | servidor | limiares da validação |
-
-O resultado traz também `avatar` (`shape`, `size`, `model`, `background`, `margin`, `layout`). **Tokens:** soma a etapa `avatar`
-em `usage.breakdown` (a separação da pessoa roda na imagem analisada inteira).
-
-## Tokens e erros
-
-Cada foto capturada (e cada `validate`) consome **tokens** do seu plano — megapixels processados × peso de cada
-etapa; foto maior ou remoção de fundo com BiRefNet gastam mais. Os quadros ao vivo da webcam não consomem.
-O plano limita os tokens por **janela** (ex.: 5 h a partir do 1º uso) e por **mês** (renova no aniversário do
-contrato).
-
-`FaceGateError.code`:
-
-| code | quando |
-|---|---|
-| `token_window_limit` | janela de tokens esgotada (`resetsAt` = quando renova) |
-| `token_month_limit` | teto mensal atingido (`resetsAt` = data da renovação) |
-| `forbidden` | serviço não contratado, chave bloqueada/expirada, fora do contrato ou IP não liberado |
-| `unauthorized` | chave/ticket inválido ou expirado |
-| `camera_denied` / `camera_unavailable` | permissão negada, sem câmera ou página sem HTTPS |
-| `network` / `server` / `bad_request` | falhas de conexão ou da API |
-
-## Segurança e LGPD
-
-- A whitelist de IPs da chave vale para o **seu servidor** (onde o ticket é emitido); o navegador usa só o
-  ticket de uso único.
-- A API não guarda as imagens: só o resultado e metadados da validação.
-- A câmera exige HTTPS (ou `localhost`).
-- As chamadas do servidor saem com o User-Agent `face-gate-sdk/<versão> (node <versão>; <sistema>)`
-  (`SDK_USER_AGENT`). Assim, uma tentativa de um IP não liberado aparece no portal como "SDK Face Gate <versão>".
-
----
-
-© BelTec, do grupo Belfort. Uso sujeito ao contrato do Face Gate.
+# @beltec/face-gate
+
+**Face Gate, uma solução BelTec** — validação de fotos de rosto para o cadastro de visitantes e moradores no
+controle de acesso. Este pacote traz:
+
+- **`<FaceGate>`** (React): webcam com validação em **tempo real** — mira que segue o rosto, orientação do que
+  corrigir, captura automática só quando a pessoa fica parada com tudo aprovado, scanner sobre a foto e a foto
+  final (com o fundo removido, se contratado).
+- **`@beltec/face-gate/server`** (Node/Next): guarda a sua chave, emite o ticket do navegador e valida arquivos.
+
+O `client_secret` **nunca** vai ao navegador: o seu servidor pede um ticket de uso único (60 s) e só ele chega à
+página.
+
+```
+navegador ──POST /api/face-gate/ticket──▶ seu servidor ──chave──▶ Face Gate API
+navegador ◀──────── ticket (60 s) ────────┘
+navegador ══ WebSocket (ticket) ══▶ Face Gate API  (quadros ao vivo → captura → resultado)
+```
+
+## Instalação
+
+```bash
+npm install @beltec/face-gate
+```
+
+React 18+ no navegador; Node 18.17+ no servidor. Crie a chave no portal do Face Gate
+(**Chaves de acesso**): você recebe o `client_id` e o `client_secret` (este aparece uma vez só).
+
+```bash
+# .env do seu servidor
+FACE_GATE_CLIENT_ID=...
+FACE_GATE_CLIENT_SECRET=...
+```
+
+## Next.js (App Router)
+
+**1. Rota que emite o ticket** — `app/api/face-gate/ticket/route.ts`
+
+```ts
+import { createFaceGate } from "@beltec/face-gate/server";
+
+const faceGate = createFaceGate({
+  clientId: process.env.FACE_GATE_CLIENT_ID!,
+  clientSecret: process.env.FACE_GATE_CLIENT_SECRET!,
+});
+
+// Só usuários logados no SEU sistema abrem a câmera (cada captura consome tokens do seu plano).
+export const POST = faceGate.ticketHandler({
+  authorize: async (req) => Boolean(await getSessionFromYourApp(req)),
+});
+```
+
+**2. A tela** — um Client Component
+
+```tsx
+"use client";
+import { FaceGate } from "@beltec/face-gate";
+import "@beltec/face-gate/styles.css";
+
+export function CadastroFoto() {
+  return (
+    <FaceGate
+      clean // devolve a foto sem fundo (serviço "validar e remover fundo" contratado)
+      getTicket={async () => {
+        const r = await fetch("/api/face-gate/ticket", { method: "POST" });
+        if (!r.ok) throw new Error("Não foi possível abrir a câmera");
+        return r.json();
+      }}
+      onCapture={({ image, result }) => {
+        if (result.accepted) salvarFoto(image); // data URL (PNG sem fundo ou JPEG do quadro)
+      }}
+      onError={(e) => console.warn(e.code, e.message)}
+    />
+  );
+}
+```
+
+## Validar um arquivo (sem webcam)
+
+```ts
+import { createFaceGate } from "@beltec/face-gate/server";
+
+const faceGate = createFaceGate({ clientId, clientSecret });
+const result = await faceGate.validate(fileBuffer, { clean: true, model: "birefnet-portrait" });
+
+result.accepted;        // true | false
+result.hard_fails;      // ex.: ["eyes_closed", "glasses_sunglasses"]
+result.cleaned_image;   // PNG sem fundo (data URL), quando clean
+result.usage?.tokens;   // tokens gastos nesta análise
+```
+
+Com melhoria de imagem: `faceGate.validate(fileBuffer, { enhance: "classic" })` (veja abaixo).
+
+Express/Fastify funcionam igual: use `createStreamTicket()` na sua rota e devolva `{ ticket, url }` ao navegador.
+
+## `<FaceGate>` — propriedades
+
+| Prop | Tipo | Padrão | |
+|---|---|---|---|
+| `getTicket` | `() => Promise<{ ticket, url }>` | — | chama a sua rota de ticket |
+| `onCapture` | `({ image, frame, result }) => void` | — | foto capturada e validada |
+| `onLive` | `(result) => void` | — | cada quadro analisado ao vivo |
+| `onError` | `(error: FaceGateError) => void` | — | câmera negada, limite de tokens, rede… |
+| `clean` | `boolean` | `false` | remover o fundo da foto capturada |
+| `model` | `"u2net" \| "u2netp" \| "birefnet-portrait"` | servidor | modelo da remoção de fundo |
+| `device` | `"cpu" \| "gpu"` | servidor | onde rodar a remoção de fundo |
+| `enhance` | `"classic" \| "gfpgan" \| null` | `null` | melhorar a foto capturada antes de validar (serviço "validar com melhoria") |
+| `thresholds` | `Record<string, number>` | servidor | limiares (nomes de `GET /v1/thresholds`) |
+| `autoFrame` | `boolean` | `true` | enquadramento automático: a imagem aproxima e acompanha o rosto, mantendo-o no centro; a foto capturada é esse recorte e só sai com o rosto centralizado (tolerância de 8%, ou a sua em `thresholds` se for mais rígida). Ignora as tarjas pretas que algumas câmeras acrescentam |
+| `mirror` | `boolean` | `true` | prévia espelhada, como um espelho (a foto enviada e a final não são espelhadas) |
+| `autoStart` | `boolean` | `false` | ligar a câmera ao montar |
+| `intro` | `boolean` | `true` | abertura animada do escudo |
+| `watermark` | `boolean` | `true` | escudo no canto do vídeo |
+| `labels` | `Partial<FaceGateLabels>` | pt-BR | troque qualquer texto |
+
+### Aparência
+
+Os estilos usam o prefixo `.fg-` e variáveis CSS:
+
+```css
+.minha-tela .fg-root {
+  --fg-accent: #c9a43e;      /* mira, botão, barra de "fique parado" */
+  --fg-accent-text: #1d2125; /* texto sobre o botão */
+  --fg-surface: #1d2125;     /* fundo do vídeo */
+  --fg-radius: 12px;
+}
+```
+
+Respeita `prefers-reduced-motion` (sem animações).
+
+## Melhoria de imagem
+
+Serviço contratável **"Validar com melhoria"** (scope `validate_enhance`). A API melhora a foto, valida a
+versão melhorada e devolve `enhancement` com o resultado **antes** (original) e **depois** (melhorada) e a
+imagem melhorada (`enhancement.enhanced_image`, JPEG). No `<FaceGate enhance="classic">`, só a foto
+capturada passa pela melhoria (os quadros ao vivo não), o `onCapture` entrega a melhorada em `image` e a
+tela mostra o selo "Imagem melhorada".
+
+| Método | O que faz | Custo |
+|---|---|---|
+| `classic` | balanço de branco, exposição, contraste local, redução de ruído e nitidez leve. Determinística, não altera o rosto | baixo |
+| `gfpgan` | a clássica + restauração do rosto com IA (GFPGAN). Recria detalhes do rosto: a resposta traz o aviso `face_restored_ai` e o componente mostra o alerta | alto |
+
+**Regra:** a melhoria só corrige luz (`poor_lighting`, `overexposed`) e rosto não encontrado por falta de
+luz (`no_face`). As demais falhas da foto original — desfoque, olhos fechados, óculos escuros, pose… —
+continuam reprovando (`enhancement.carried_over`). Com `clean`, o fundo é removido da foto melhorada (exige
+também o serviço "validar e remover fundo").
+
+**Tokens:** a validação roda duas vezes (antes e depois) e soma a etapa `usage.breakdown.enhance`
+(a clássica é barata; o GFPGAN custa bem mais).
+
+## Avatar
+
+Serviço **Avatar** contratado (`POST /v1/photos/avatar`): valida a foto e, se aprovada, devolve o avatar só com a
+pessoa do rosto em foco — o fundo e outros elementos ou pessoas são removidos —, recortado centrado no rosto.
+
+```ts
+import { createFaceGate } from "@beltec/face-gate/server";
+
+const faceGate = createFaceGate({ clientId, clientSecret });
+const r = await faceGate.avatar(fileBuffer, {
+  shape: "round",            // "round" (padrão; fora do círculo transparente) | "square"
+  size: 512,                 // 64 a 1024
+  backgroundColor: "#1d252a", // ou background: <imagem> (tem prioridade); sem nenhum = PNG transparente
+  margin: 25,                 // só com fundo: % do quadro deixado para o fundo (0 a 60)
+  layout: "bottom",           // só com fundo: "center" | "bottom" | "left" | "right"
+});
+
+if (r.accepted) r.avatar_image; // data:image/png;base64,...
+else r.hard_fails;             // sem avatar: os mesmos motivos da validação
+```
+
+| Opção | Tipo | Padrão | |
+|---|---|---|---|
+| `shape` | `"round" \| "square"` | `"round"` | formato do recorte |
+| `size` | `number` | `512` | lado em pixels (64 a 1024) |
+| `backgroundColor` | `string` | — | cor sólida `#RRGGBB` |
+| `background` | `Blob \| ArrayBuffer \| Uint8Array` | — | imagem de fundo (preenche o quadro) |
+| `template` | `number` | — | id de um **template de avatar** salvo no portal (Avatares): formato, tamanho, fundo e enquadramento prontos, sem reenviar a imagem; as outras opções têm prioridade |
+| `backgroundPosition` | `{ x?, y?, zoom? }` | centro, `zoom` 100 | **só com `background`**: qual parte da imagem aparece — `x`/`y` de 0 a 100 (50 = centro, como o `object-position` do CSS) e `zoom` de 100 a 300 % |
+| `margin` | `number` | `0` | **só com fundo**: % do quadro deixado para o fundo em volta da pessoa (0 a 60) |
+| `layout` | `"center" \| "bottom" \| "left" \| "right"` | `"center"` | **só com fundo**: onde a pessoa fica (centro, apoiada na base, base à esquerda/direita) |
+| `model` / `device` | | servidor (BiRefNet) | modelo de remoção de fundo que separa a pessoa |
+| `thresholds` | `Record<string, number>` | servidor | limiares da validação |
+
+O resultado traz também `avatar` (`shape`, `size`, `model`, `background`, `margin`, `layout`). **Tokens:** soma a etapa `avatar`
+em `usage.breakdown` (a separação da pessoa roda na imagem analisada inteira).
+
+## Tokens e erros
+
+Cada foto capturada (e cada `validate`) consome **tokens** do seu plano — megapixels processados × peso de cada
+etapa; foto maior ou remoção de fundo com BiRefNet gastam mais. Os quadros ao vivo da webcam não consomem.
+O plano limita os tokens por **janela** (ex.: 5 h a partir do 1º uso) e por **mês** (renova no aniversário do
+contrato).
+
+`FaceGateError.code`:
+
+| code | quando |
+|---|---|
+| `token_window_limit` | janela de tokens esgotada (`resetsAt` = quando renova) |
+| `token_month_limit` | teto mensal atingido (`resetsAt` = data da renovação) |
+| `forbidden` | serviço não contratado, chave bloqueada/expirada, fora do contrato ou IP não liberado |
+| `unauthorized` | chave/ticket inválido ou expirado |
+| `camera_denied` / `camera_unavailable` | permissão negada, sem câmera ou página sem HTTPS |
+| `network` / `server` / `bad_request` | falhas de conexão ou da API |
+
+## Segurança e LGPD
+
+- A whitelist de IPs da chave vale para o **seu servidor** (onde o ticket é emitido); o navegador usa só o
+  ticket de uso único.
+- A API não guarda as imagens: só o resultado e metadados da validação.
+- A câmera exige HTTPS (ou `localhost`).
+- As chamadas do servidor saem com o User-Agent `face-gate-sdk/<versão> (node <versão>; <sistema>)`
+  (`SDK_USER_AGENT`). Assim, uma tentativa de um IP não liberado aparece no portal como "SDK Face Gate <versão>".
+
+---
+
+© BelTec, do grupo Belfort. Uso sujeito ao contrato do Face Gate.

package/dist/index.cjs

@@ -55,6 +55,8 @@ var CLOSE = {
   4429: ["token_window_limit", "Limite de uso atingido. Aguarde e tente de novo."],
   1011: ["server", "Erro interno na API."]
 };
+var DEFAULT_FPS = 6;
+var MAX_BUFFERED = 32 * 1024;
 function openFaceGateStream(url, ticket, options, handlers, WS = WebSocket) {
   const ws = new WS(url);
   ws.binaryType = "arraybuffer";
@@ -65,7 +67,7 @@ function openFaceGateStream(url, ticket, options, handlers, WS = WebSocket) {
   ws.onmessage = (e) => {
     if (typeof e.data !== "string") return;
     const m = JSON.parse(e.data);
-    if (m.type === "ready") handlers.onReady?.();
+    if (m.type === "ready") handlers.onReady?.(Number(m.max_fps) || DEFAULT_FPS);
     else if (m.type === "frame") handlers.onFrame?.(m.seq, m.result, m.stable ?? { ms: 0, needed: 0 });
     else if (m.type === "captured") handlers.onCaptured?.(m.seq);
     else if (m.type === "final") {
@@ -81,7 +83,7 @@ function openFaceGateStream(url, ticket, options, handlers, WS = WebSocket) {
   const open = () => ws.readyState === 1;
   return {
     sendFrame: (frame) => {
-      if (!open()) return null;
+      if (!open() || ws.bufferedAmount > MAX_BUFFERED) return null;
       ws.send(frame);
       return ++seq;
     },
@@ -171,6 +173,13 @@ function cropTransform(c, mirror = true) {
   const move = `translate(${-c.x * 100}%, ${-c.y * 100}%)`;
   return mirror ? `translateX(100%) scale(${-k}, ${k}) ${move}` : `scale(${k}) ${move}`;
 }
+function overlayTransform(used, now, mirror = true) {
+  const k = used.s / now.s;
+  const dx = (used.x - now.x) / now.s;
+  const tx = mirror ? 1 - k - dx : dx;
+  const ty = (used.y - now.y) / now.s;
+  return `translate(${tx * 100}%, ${ty * 100}%) scale(${k})`;
+}
 function boxStyle(b, mirror) {
   const left = mirror ? 1 - b.xmax : b.xmin;
   return {
@@ -300,6 +309,12 @@ function FaceGate({
   const canvasRef = (0, import_react2.useRef)(null);
   const framesRef = (0, import_react2.useRef)(/* @__PURE__ */ new Map());
   const viewRef = (0, import_react2.useRef)(null);
+  const overlayRef = (0, import_react2.useRef)(null);
+  const overlayCropRef = (0, import_react2.useRef)(FULL);
+  const fpsRef = (0, import_react2.useRef)(6);
+  const sendRef = (0, import_react2.useRef)(() => {
+  });
+  const lastSeqRef = (0, import_react2.useRef)(0);
   const cropRef = (0, import_react2.useRef)(FULL);
   const targetRef = (0, import_react2.useRef)(FULL);
   const areaRef = (0, import_react2.useRef)(WHOLE);
@@ -334,6 +349,7 @@ function FaceGate({
     const tick = () => {
       cropRef.current = ease(cropRef.current, targetRef.current);
       if (viewRef.current) viewRef.current.style.transform = cropTransform(cropRef.current, mirror);
+      if (overlayRef.current) overlayRef.current.style.transform = overlayTransform(overlayCropRef.current, cropRef.current, mirror);
       id = requestAnimationFrame(tick);
     };
     id = requestAnimationFrame(tick);
@@ -456,7 +472,9 @@ function FaceGate({
     gateRef.current = { camera: false, socket: false, intro: !playIntro };
     framesRef.current.clear();
     hadFaceRef.current = false;
-    cropRef.current = targetRef.current = FULL;
+    lastSeqRef.current = 0;
+    cropRef.current = targetRef.current = overlayCropRef.current = FULL;
+    if (overlayRef.current) overlayRef.current.style.transform = "";
     areaRef.current = WHOLE;
     measuredRef.current = 0;
     lostSinceRef.current = 0;
@@ -495,13 +513,17 @@ function FaceGate({
       });
     }
     streamRef.current = openFaceGateStream(tk.value.url, tk.value.ticket, cfg.current.options, {
-      onReady: () => {
+      onReady: (maxFps) => {
+        fpsRef.current = Math.min(Math.max(maxFps, 1), 10);
         gateRef.current.socket = true;
         goLiveIfReady();
       },
       onFrame: (seq, r, st) => {
+        if (seq <= lastSeqRef.current) return;
+        lastSeqRef.current = seq;
         const f = framesRef.current.get(seq);
         if (f) f.result = r;
+        if (autoFrame) overlayCropRef.current = f?.crop ?? cropRef.current;
         aim(seq, r.dominant_face_bbox);
         const hasFace = Boolean(r.dominant_face_bbox);
         if (hasFace && !hadFaceRef.current) setDetectKey((k) => k + 1);
@@ -509,7 +531,6 @@ function FaceGate({
         setLive(r);
         setStable(st);
         cfg.current.onLive?.(r);
-        requestAnimationFrame(sendFrame);
       },
       onCaptured: (seq) => {
         const frames = framesRef.current;
@@ -543,6 +564,14 @@ function FaceGate({
   (0, import_react2.useEffect)(() => {
     if (autoStart) void start();
   }, []);
+  (0, import_react2.useEffect)(() => {
+    sendRef.current = sendFrame;
+  });
+  (0, import_react2.useEffect)(() => {
+    if (phase !== "live") return;
+    const id = setInterval(() => sendRef.current(), 1e3 / fpsRef.current);
+    return () => clearInterval(id);
+  }, [phase]);
   const cameraOn = phase === "starting" || phase === "live";
   const box = phase === "live" ? live?.dominant_face_bbox ?? null : null;
   const ok = Boolean(live?.accepted);
@@ -584,10 +613,18 @@ function FaceGate({
           children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "fg-search-sweep" })
         }
       ),
-      box && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "fg-track", "data-state": ok ? "ok" : "warn", style: boxStyle(box, mirror), "aria-hidden": "true", children: [
-        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "fg-track-line" }),
-        holding && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "fg-track-hold", style: { transform: `scaleX(${progress})` } })
-      ] }, detectKey),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        "div",
+        {
+          ref: overlayRef,
+          "aria-hidden": "true",
+          style: { position: "absolute", inset: 0, transformOrigin: "0 0", pointerEvents: "none" },
+          children: box && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "fg-track", "data-state": ok ? "ok" : "warn", style: boxStyle(box, mirror), children: [
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "fg-track-line" }),
+            holding && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "fg-track-hold", style: { transform: `scaleX(${progress})` } })
+          ] }, detectKey)
+        }
+      ),
       phase === "processing" && frozen && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("img", { src: frozen.url, alt: "", className: "fg-video", style: mirror ? { transform: "scaleX(-1)" } : void 0 }),
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "fg-scan", style: boxStyle(frozen.box, mirror), "aria-hidden": "true", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "fg-scan-line" }) })