- FaceDetector (blaze_face_full_range, Apache-2.0, lazy/on-device) mede o maior rosto no canvas do recorte; math pura frameCardPhotoOnFace escala a face à referência TEAM_CARD_FACE_REFERENCE_SIZE=103 (mediana das 5 caixas da arte-mestre).
- Piso do time CARD_TEAM_PHOTO_MIN_ZOOM=0.2 com clamp contain/cover por eixo (minZoom opcional preserva os 3 modelos S13/S14); fallback silencioso ao enquadramento S15 sem rosto/falha.
- Stub e2e estendido ('noface'); unit novo da math e da seleção do rosto; craft com retrato real 86-98px vs 103 (±20%); crítica Tier 1 certificada.
Closes #1197
28 KiB
Impl: Card "Time de você": cabeça do visitante proporcional à dos candidatos
Status: aprovado Atualizado em: 2026-09-19 Issue: #1197 Intenção: docs/plans/cards-time-de-voce-escala-cabeca.md Appetite restante: herdado — ~1–1,5 dia eng (3 fases somam ≤1,5 dia; sem migration)
Leitura da intenção
- Outcome: o auto-enquadramento do card
Time de vocêpassa a mirar a proporção da cabeça: o rosto do visitante é medido com a mesma régua dos candidatos (caixa doFaceDetectorsobre o recorte e sobre a arte-mestre) e o zoom enquadra a cabeça na mesma ordem de grandeza (±20%) sempre que houver rosto; a cobertura da janela prevalece, o rosto nunca é cortado pela proporcionalidade e qualquer impossibilidade cai no enquadramento S15, em silêncio. Nada sai do aparelho; nenhum controle novo. - O que NÃO negociar:
- 100% no aparelho: foto e medida nunca saem; nada além dos assets same-origin; sem analytics.
- Fallback obrigatório e silencioso: sem rosto, detecção indisponível ou qualquer falha → enquadramento S15 (
frameCardPhotoOnBbox); nunca erro novo no funil — o único erro recuperável continua sendo o do recorte de fundo. - Cobertura da janela prevalece sobre a proporção; o rosto nunca é cortado pelo ajuste proporcional (quando a janela permite); pan/zoom seguem como escape.
- Métrica única dos dois lados (lado da caixa do rosto), maior rosto vence, referência literal dos candidatos, sem re-detecção em pan/zoom.
- Os 3 modelos S13/S14, a galeria, a copy e a privacidade ficam intocados; sem controle/toggle novo; sem migration/Consent/access.
- O que reavaliar (hipóteses da intenção):
- "Detecção no mesmo pipeline do recorte": confirmado, mas como passo tolerante do mesmo run — a caixa do rosto viaja no
CardCutoutResult(face), não como máquina de estado paralela; falha viranullsem log. - "Ajuste no adapter/hook": confirmado, porém a régua é 100% pura em
cardPhotoTransform.ts; o adapter só entrega a caixa no espaço de coords do recorte. - "±20% sempre": reaberto na execução com evidência de craft — no piso de cobertura (
zoom ≥ 1) as selfies fechadas ficavam 2,0–2,6× acima dos candidatos, deixando o caso "fechado fica gigante" (o principal do pedido) sem correção. Decisão do humano em 2026-09-19: o enquadramento do time pode descer abaixo do piso (CARD_TEAM_PHOTO_MIN_ZOOM=0.2), com o clamp mantendo a foto menor dentro da janela (a arte-mestre aparece ao redor, como na Cena 1 do design); o ajuste fino do visitante continua sendo o escape. - "Qualquer foto serve": o detector escolhido tem limite medido — rosto abaixo de ~10% da largura vira ruído e a 15% o score é ~0.58;
minDetectionConfidence: 0.5e a mediana da arte são os pins; reavaliar só com medição nova.
- "Detecção no mesmo pipeline do recorte": confirmado, mas como passo tolerante do mesmo run — a caixa do rosto viaja no
Abordagem recomendada
flowchart LR
P["foto escolhida"] --> CUT["cardCutout — engine no aparelho (S15)"]
CUT --> SEG["ImageSegmenter — recorte + bbox alfa"]
SEG --> FACE["detectCardFace — FaceDetector + blaze_face_full_range, lazy, catch local"]
FACE --> RES["CardCutoutResult — canvas + bbox + face"]
RES --> HOOK["useCardCutout — run id + estado"]
HOOK --> MATH["frameCardPhotoOnFace — math pura"]
REF["TEAM_CARD_FACE_REFERENCE_SIZE = 103"] -.-> MATH
MATH --> TR["transform proporcional (piso do time 0.2 + teto de rosto)"]
MATH --> FB["sem rosto ou falha: frameCardPhotoOnBbox (S15)"]
TR --> PV["prévia renderTeamCard — pan/zoom como escape"]
FB --> PV
PV --> DL["Baixar PNG no aparelho"]
STUB["stub e2e — ok / slow / error / noface"] -.-> CUT
Opções consideradas: A) FaceDetector no canvas do recorte + math pura nova com piso de cobertura e fallback S15 | B) enquadrar no adapter (DOM), "no olho", sem função pura | C) mudar a frameCardPhotoOnBbox existente para aceitar rosto.
Recomendação: A — reaproveita o runtime/wasm/stub que o S15 já paga, mantém a régua pura/testável em src/lib e deixa o adapter só medir; o fallback é o próprio caminho S15 intacto, então nada do funil regride.
Rejeitadas: B porque enquadramento sem função pura não tem pin de unit e reabre o rabbit hole "medir no olho" (adapter é DOM); C porque mexe na função pinada e nos 3 modelos para um comportamento que é só do time.
Decisões de engenharia
-
Detector —
FaceDetector+blaze_face_full_range(Apache-2.0), commitado e lazy. Opções: A)FaceDetectordo@mediapipe/tasks-visioncomblaze_face_full_range.tflite(float16, 1.083.786 B) | B)blaze_face_short_range.tflite(229.746 B) | C)FaceLandmarker(malha facial) | D) detector próprio/ONNX. Recomendação: A — é o único medido que enxerga a arte-mestre e a foto do visitante na mesma régua. ComminDetectionConfidence: 0.5(explícito, embora o default da lib também seja 0.5 — vira pin de contrato) ofull_rangedetecta os 5 rostos depublic/cards/team-card-base.png(1080×1440) de forma estável em 1×/2×/3× (scores 0.62–0.90; caixas em coords da arte: c1(45,609,108,108), c2(202,580,103,103), centro/Solla(336,540,149,149), c4(762,583,103,103), c5(926,608,99,99)); em canvas sintético com a Lenna a 40%/30%/20%/15% da largura detecta com scores 0.89/0.74/0.70/0.58 (caixas 278/186/119/75 px), degradando para ruído a 10% (scores ~0.2). OFaceDetectorjá vive no runtime que o S15 carrega — entra só um modelo novo, same-origin e lazy (só o time paga); a caixa do rosto é exatamente a métrica da intenção. Modelo commitado empublic/cards/blaze_face_full_range.tflite(origemhttps://storage.googleapis.com/mediapipe-models/face_detector/blaze_face_full_range/float16/1/blaze_face_full_range.tflite, SHA-2563698b18f063835bc609069ef052228fbe86d9c9a6dc8dcb7c7c2d69aed2b181b) compublic/cards/blaze_face_full_range.LICENSE.txtno padrão doselfie_segmenter.LICENSE.txt(origem + SHA + Apache-2.0 + nota do wasm).scripts/copy-card-vision-assets.mjsnão muda (copia só wasm). Rejeitadas: B porque não detectou nenhum rosto da arte-mestre (nem cropada, nem upscalada 2×/3×) nem um rosto sintético a 40% da largura — um detector que não mede a arte não tem como dar proporção; C porque a malha facial adiciona peso/superfície de API sem mudar a medida (a caixa do rosto já é o lado que importa) e não tem ganho medido; D porque reimplementar runtime/hosting/modelo está fora do appetite e repetiria o custo do S15 sem evidência. -
Onde detectar — no canvas do recorte, uma vez, maior rosto vence. Opções: A) no canvas do cutout (mesmo espaço de coords do
bbox, fundo já removido) | B) no bitmap original | C) no arquivo da foto antes do recorte. Recomendação: A — o canvas do recorte é o mesmo sistema de coordenadas dobboxque a math já usa (zero conversão de escala), o fundo removido reduz rostos de terceiros/objetos (menos falso positivo) e o custo roda uma única vez por foto, dentro do run do recorte; "maior rosto vence" (maior área) alinha com "em foto com mais de um rosto, vale o do visitante". Detecção uma vez, no recorte; nunca re-detecta em pan/zoom (a medida é do momento do recorte). Rejeitadas: B porque exigiria escalar as caixas do bitmap original para o canvas capado (≤1600 px) e detectaria rostos de fundo que o recorte acabou de remover; C porque duplicaria decode/custo antes do cutout e poderia medir um rosto que a segmentação nem manteve. -
Math pura —
frameCardPhotoOnFacecom piso do time, delegando ao S15 sem rosto. Opções: A) função nova emsrc/lib/cardPhotoTransform.ts:frameCardPhotoOnFace(source, window, bbox, face, referenceSize): CardPhotoTransform | null| B) mudar assinatura/comportamento deframeCardPhotoOnBbox| C) calcular o enquadramento no adapter (DOM) | D) manter o piso de coberturazoom ≥ 1(plano original). Recomendação: A — a régua fica inteira pura e pinável:s = coverScale(source, window) faceSize = Math.max(face.width, face.height) zoom = clamp(referenceSize / (faceSize * s), CARD_TEAM_PHOTO_MIN_ZOOM, CARD_PHOTO_MAX_ZOOM) offX = window.x + window.width/2 − (face.x + face.width/2) * s * zoom offY = window.y − bbox.y * s * zoom → clampCardPhotoTransform({ zoom, offX, offY }, source, window, CARD_TEAM_PHOTO_MIN_ZOOM)Piso do time (
CARD_TEAM_PHOTO_MIN_ZOOM = 0.2). O craft provou que o piso de cobertura do S13 (zoom ≥ 1) deixava as selfies fechadas em 2,0–2,6× a cabeça dos candidatos (207px e 270px vs. a referência de 103px): o caso "fechado fica gigante" — o principal do pedido — seguia sem correção. Decisão do humano (2026-09-19): permitir o zoom abaixo de 1. O clamp ganha umminZoomopcional (default =CARD_PHOTO_MIN_ZOOM, preservando os 3 modelos S13/S14) e, quando a foto desenhada é menor que a janela num eixo, ela é mantida dentro da janela (contain) em vez de pinada na borda — a foto nunca sai da prévia e o ajuste fino do visitante segue livre. Com o piso 0.2, a face alcançada nunca passa de +15% da referência (a caixa do rosto cobre o canvas no máximo;0.2 × 592 = 118px), ou seja, o aceite de ±20% fica garantido por construção; rostos minúsculos ficam no teto de 4 (e podem não ser detectados → fallback). Rosto nunca cortado: com a referência 103px, a face desenhada nunca passa de ~118px, muito dentro da janela 592×577; o posicionamento mantém o centro-x do rosto no centro-x da janela e o topo do bbox no topo (contain/cover por eixo do clamp). Face ausente/inválida/falha → delega aframeCardPhotoOnBbox; se o bbox também falhar →null→ erro recuperávelemptyde hoje. Rejeitadas: B porque a assinatura/comportamento são pinados (tests/unit/cardPhotoTransform.unit.spec.ts:58-114) e usados pelos 3 modelos; C porque o adapter é DOM e o enquadramento viraria opinião não testável; D (piso de cobertura) por não cumprir o aceite primário nos casos fechados — craft medido: cabeça 207px/270px contra referência de 103px, enquanto a Cena 1 do design mostra o alvo proporcional (busto menor que a janela). -
Referência — constante literal medida uma vez sobre a arte-mestre. Opções: A)
TEAM_CARD_FACE_REFERENCE_SIZE = 103emsrc/lib/cardModels.ts| B) medir a arte em runtime | C) usar máximo/média das 5 caixas. Recomendação: A — mediana das 5 caixas (99, 103, 103, 108, 149 → 103 px) é robusta ao outlier do rosto central/Solla (149) e ao par menor (99/103); o comentário da constante registra o método (modeloblaze_face_full_range,minDetectionConfidence: 0.5, SHA) e as 5 caixas; fica ao lado dos outros literais do time (TEAM_CARD_LABEL/TEAM_CARD_NAME_BANNER), auditável e com custo zero no aparelho. A mediana ainda é conservadora: puxa a cabeça do visitante para o tamanho típico, não para o maior. Rejeitadas: B porque paga inferência e movimento por um valor que não muda (a arte-mestre é fixa/versionada; a intenção já assumiu constante); C porque o máximo puxa a proporção para o rosto do Solla e a média fica sensível a um rosto fora de escala (média 112,4 / máxima 149). -
Integração —
faceviaja noCardCutoutResult; detector com catch local; prefetch intocado. Opções: A)CardCutoutResultganhaface: CardFaceBox | null;detectCardFace(canvas)singleton próprio (mesmoWASM_DIR) com catch local que nunca propaga;useCardCutout.startpassaresult.face+TEAM_CARD_FACE_REFERENCE_SIZEà math | B) segunda máquina de estado no hook para a detecção | C) incluir o modelo do detector no pré-aquecimento/progresso do cutout. Recomendação: A — a detecção é parte do resultado do mesmo run (mesma foto/canvas; sem corrida nova); falha de download/criação/detect viraface: nullsem log (guard de console/5xx do e2e intacto) e nunca viraerrordo hook; otry/finallydo engine continua fechando mask/bitmap. O detector cria lazily depois do cutout, antes de reportarratio: 1(a barra não congela em 100% esperando os ~1 MB): o prefetch atual (wasm + segmenter) fica intocado, o modelo entra no primeiro uso do time e a falha é tolerada — se a rede/modelo falhar, vale o enquadramento de hoje.CardComposer/cardRendernão mudam (photoTransform ?? teamReady?.transformjá consome o resultado do hook; o pan/zoom continua sendo o escape). Rejeitadas: B porque não há transições próprias (éface | nulldentro de um resultado existente) e um segundo ciclo pediria mais guardas de corrida; C porque acoplaria a falha do detector ao progresso/erro do recorte (um 404 no modelo viraria erro de recorte, violando o aceite). -
Stub de e2e — estender o seam existente com
'noface'. Opções: A)window.__cardsCutoutStubganha o modo'noface'(ok/slowdevolvem um rosto sintético determinístico;nofacedevolveface: null) | B) seam separadowindow.__cardsFaceStub('ok' | 'none'). Recomendação: A — um único seam, um únicoaddInitScript; o modo descreve o resultado do stub inteiro (recorte ok + sem rosto), que é exatamente o cenário de fallback a testar, e nenhum teste precisa da matriz "slow + noface". No modo stub o detector real nunca é chamado (nenhum fetch do.tflite, nenhuma inferência) — o e2e segue hermético e o guard não quebra. Rosto sintético: caixa determinística ancorada na elipse do stub (literais documentados no adapter junto deSTUB_MIN_EDGE). Testes novos no describe S18:ok→ card pronto/baixável pelo caminho proporcional;noface→ mesmo fluxo silencioso, semrole=alertnovo, card pronto (fallback). Rejeitadas: B porque dobra o contrato de teste (dois init scripts, dois tipos) sem nenhum caso que precise combinar os eixos; a face não é um engine separado, é parte do mesmo resultado. -
Sem migration, sem Consent/access, sem int, sem copy/controle novos. Opções: A) só
src/libpuro + adapter/hook + assets + testes | B) global/collection para a configuração | C) controle/toggle novo. Recomendação: A — 100% client-side: nenhuma superfície Payload, schema intocado (push:false), nenhuma chave de Consent, nenhum dado sai do aparelho; copy/estados do funil intactos (o texto novo é só comentário de código);E2E_AFFECTED_MANIFESTsem entrada nova (src/components/cards+src/lib/cardjá mapeiam parafrontend—scripts/lib/e2e-affected-manifest.mjs:78). Rejeitadas: B (config de produto que não varia por ambiente; a constante vive no catálogo puro), C (anti-goal explícito da intenção).
Componentes / mudanças
CardFaceBox+frameCardPhotoOnFace+CARD_TEAM_PHOTO_MIN_ZOOM(src/lib/cardPhotoTransform.ts): tipo da caixa do rosto em pixels da fonte (ao lado deCardAlphaBbox) e a math pura nova — proporção pelo lado, piso do time (0.2), teto de rosto, fallback por delegação aframeCardPhotoOnBbox;clampCardPhotoTransform/cardPhotoDrawRect/pan/zoomganhamminZoomopcional (default =CARD_PHOTO_MIN_ZOOM) e o clamp mantém a foto dentro da janela quando ela é menor (contain) e cobrindo quando é maior (cover), por eixo; reusacoverScale,CARD_PHOTO_MIN_ZOOM/MAX_ZOOM.TEAM_CARD_FACE_REFERENCE_SIZE = 103(src/lib/cardModels.ts): comentário com método, modelo+SHA, as 5 caixas e a mediana; ao lado dos literais do time.detectCardFace+CardCutoutResult.face(src/components/cards/cardCutout.ts):FACE_MODEL_URL='/cards/blaze_face_full_range.tflite',FACE_MIN_CONFIDENCE=0.5,faceDetectorPromisesingleton com reset em falha (padrão dosegmenterPromise), mapeamentoBoundingBox {originX,originY,width,height}→CardFaceBox, maior rosto por área, catch local devolvendonull(sem log); stub'noface'e rosto sintético nos modosok/slow; reusaWASM_DIR,supportsWasmSimde otry/finallydo engine.useCardCutout(src/components/cards/useCardCutout.ts): trocaframeCardPhotoOnBboxporframeCardPhotoOnFace(..., result.face, TEAM_CARD_FACE_REFERENCE_SIZE); run id/retry/progresso/estado intactos;nullcontinua virandoerror: 'empty'só quando o bbox também falha.CardComposer(src/components/cards/CardComposer.tsx) erenderTeamCard(src/lib/cardRender.ts): o slider de zoom usa o piso do time (0.2) e pan/zoom/arrasto passam o mesmo piso; o render do time desenha/clampeia com o piso do time. Nenhuma mudança visual fora do enquadramento inicial.public/cards/blaze_face_full_range.tflite+public/cards/blaze_face_full_range.LICENSE.txt(novos): modelo Apache-2.0 (1.083.786 B, SHA-2563698b18f…181b) e licença no padrão S15.scripts/copy-card-vision-assets.mjsnão muda.- Testes (editar):
tests/unit/cardPhotoTransform.unit.spec.ts(describe novo deframeCardPhotoOnFace: proporção exata, proporção abaixo do piso S13, piso do time com +20% garantido, teto de rosto, contain/cover do clamp comminZoom, fallback/delegação, entradas inválidas);tests/unit/cardModels.unit.spec.ts(pin da constante);tests/e2e/frontend.e2e.spec.ts(describeCards personalizados (S18 — cabeça proporcional)+ união'noface'nosetCutoutStub+ asserção do slider:noface→ zoom 1, rosto → zoom < 1).cardRender.unit.spec.tsintocado (pins passam com o piso do time). docs/changelog/2026-09-19-s18-card-cabeca-proporcional.md(novo).- Migration: sem migration — nenhuma collection/global/field;
push:falseintocado. - Access / Consent: não se aplica — nenhuma superfície Payload; foto/medida nunca saem do aparelho; sem chave nova de Consent.
- UI: Impeccable C — sem cena/controle novo; a prévia continua a mesma (muda o enquadramento inicial). O artefato
cards-time-de-voce-escala-cabeca-ui-design.html(Design tier: DEGRADED) serve de antes/depois e não certifica: exige sign-off humano no gate/PR. Craft no browser com fotos reais (perto/longe/sem rosto/multirrosto) + iPhone físico; sem shape novo.
Dados → forma (se aplicável)
Não se aplica (data-presentation Q3): nenhum KPI, mapa ou série; a única "forma" é a geometria do card (literais medidos) e o enquadramento. A caixa do rosto é geometria efêmera no aparelho — nunca dado apresentado, coletado ou enviado.
Fases verificáveis
- Tracer da math + referência — quota ~0,5 dia.
CardFaceBox;frameCardPhotoOnFace(proporção, piso de cobertura, teto de rosto, delegação);TEAM_CARD_FACE_REFERENCE_SIZE = 103com o comentário do método; units novos. Prova:pnpm gate:fastverde; unit pinando proporção (rosto pequeno amplia; rosto grande cai no piso), teto de rosto, fallback idêntico àframeCardPhotoOnBbox(deep equal) enullquando o bbox falha. - Detector no adapter + hook — quota ~0,5 dia. Modelo + licença;
detectCardFacelazy/singleton/catch local;CardCutoutResult.face; stub'noface'+ rosto sintético; hook passa face+constante. Prova:pnpm gate:fastverde; no browser, foto de perto e de longe chegam à prévia com a cabeça na mesma ordem de grandeza; foto sem rosto cai no enquadramento S15 sem alerta; bloquear o.tfliteno devtools não muda o fluxo nem loga nada; modo stub não baixa o modelo; iPhone físico no craft. - e2e + gates + changelog — quota ~0,25–0,5 dia. Testes do describe S18; changelog;
pnpm gate:fast; e2e localpnpm test:e2e --no-deps -- tests/e2e/frontend.e2e.spec.ts -g "S18";pnpm push. Prova: e2e verde com stub —ok→Confira seu card+ download PNG;noface→ mesmo fluxo,role=alertcount 0, card pronto; os 4 testes S15 seguem verdes; fixture de console-error intacto.
Craft (engine real, 2026-09-19)
Medição com o engine real (sem stub) neste worktree, cards baixados e medidos com o mesmo FaceDetector da referência (103px):
- Retrato real nítido (retrato oficial em domínio público, 2687×3356) em três enquadramentos: rosto do visitante = 96px (busto normal), 86px (fechado) e 98px (pessoa pequena sobre fundo liso) — todos dentro de ±20% da referência e com a detecção funcionando nos três.
- Com o piso de cobertura (implantação anterior do mesmo craft, fotos sintéticas): fechado/normal saíam 270px e 207px (2,0–2,6× a referência) → motivou a decisão do piso do time.
- Sem rosto (rosto desfocado): recorte ok + detecção falha → enquadramento S15, card pronto, zero
role=alert; o cenário "pessoa muito pequena" também cai no fallback silencioso (limite do segmentador/detector, registrado em Riscos). - Logs: o engine real loga
INFO: … XNNPACK delegateviaconsole.error(caminho real; o e2e usa o stub e mantém o guard de console intacto). - Crítica final (trigger c): certificada Tier 1 (
openai/gpt-5.6-sol), sem ajustes bloqueantes ("86–98 px para referência de 103 px, dentro de ±20%, sem cortar o rosto"; fallback e mobile OK). O artefato de referência nasceuDEGRADED(frontier sem quota no plan-issue) e por isso exige sign-off humano no PR, registrado no body.
Rabbit holes / Não escopo (engenharia)
- Re-detectar/rastrear rosto em pan/zoom; rastreamento em vídeo; escolher entre vários rostos; identificação/reconhecimento facial.
- Mudar a semântica default do
clampCardPhotoTransform(piso 1/cobertura) ou o range do slider dos 3 modelos S13/S14 — o S18 usa ominZoomopcional e o piso só no time; o default fica intocado. FaceLandmarker, detector próprio/ONNX, segunda lib de visão; medir a arte em runtime; auto-calibrar a referência.- Alterar
frameCardPhotoOnBbox,renderTeamCard,CardComposer, a arte-mestre, banners ou a janela ({286,439,592,577}). - Novo controle/toggle, copy nova, novo estado de erro (detecção nunca vira erro), persistir a medida, analytics da detecção.
- Worker/OffscreenCanvas/segundo wasm; CDN do modelo (assets seguem same-origin); engine real no CI.
- Migration/Consent/access/int; tocar o segmentador ou os 3 modelos antigos.
Riscos e mitigação
- Detector não detecta rosto (perfil, sombra, recorte difícil) →
detectCardFacedevolvenullsem log e a math delega àframeCardPhotoOnBbox: o fluxo fica exatamente o de hoje; unit do fallback + e2enoface. - Ruído em rosto muito pequeno (abaixo de ~10–15% da largura o score cai a ~0.2–0.58) →
minDetectionConfidence: 0.5+ "maior rosto vence" (um falso positivo pequeno dificilmente é o maior) + teto de zoom 4; foto de longe demais segue limitada e o pan/zoom é o escape; gatilho de revisão: taxa de falso negativo/positivo medida no craft com fotos reais. - Modelo de ~1 MB no primeiro uso do time → lazy depois do cutout (fora do bundle inicial), cache HTTP, sem entrada no denominador do progresso; falha tolerada (fallback); stub impede rede no e2e.
- iOS/Safari → mesmo runtime wasm do S15 (probe SIMD com caminho nosimd); modelo float16;
detectem<canvas>é API estável; validar em iPhone físico no craft, como no S15. - Guard de console/5xx do e2e → caminho de detecção sem logs; stub não chama o detector; nenhuma URL externa no runtime.
- Corrida/troca de foto → a detecção roda dentro do mesmo run do recorte e viaja no resultado; o run id do hook já ignora resultado velho; nenhum estado novo para sincronizar.
- Cobertura vs proporção → piso
CARD_PHOTO_MIN_ZOOM=1+clampCardPhotoTransformgarantem a janela sempre coberta; limite explícito: selfie muito fechada pode passar de +20% e rosto maior que a janela em zoom 1 respeita o limite da janela (cobertura manda) — registrado no aceite. - Ajuste percebido como "errado" pelo visitante → o enquadramento é só o inicial; arrastar/zoom continuam o escape e o CTA não trava.
- Colisão com S17 no mesmo pipeline → os dois tocam
cardCutout/CardComposer; se rodarem em paralelo, serializar (dependência registrada na intenção).
Revisão da sessão (simplify) — resolvido, adiado com gatilho, fora
Resolvido no simplify (não reabrir): format:check (prettier/organize-imports); readLargestFaceBox exportada + tests/unit/cardFaceDetection.unit.spec.ts; memoização falsa do fileset revertida (cada creator chama forVisionTasks direto); teto de rosto inalcançável removido (a garantia ficou estrutural: face desenhada ≤ ~118px) e o teste virou "+15% no piso" com o valor exato; zoomCardPhotoTransform com options object { anchor?, minZoom? } (fim do undefined posicional); doc do useCardCutout, JSDoc do removeCardPhotoBackground (face) e guards !(x > 0) (NaN) na math/filtro; describe (S13/S15/S18); testes novos de pan/zoom com o piso do time. Absorvido: o fix do codebaseConventions.unit.spec.ts (git ls-files -z para paths não-ASCII) — main estava vermelho no verify do deploy 4d376402 e o PR não passaria sem ele.
Adiados com gatilho (engenharia): piso do time selecionado no composer e reusado no renderTeamCard (hoje ambos importam a mesma constante; gatilho: um dos lados deixar de importá-la ou o piso virar por-modelo); config do time dividida entre cardModels (referência) e cardPhotoTransform (piso) (gatilho: recalibrar arte/janela/referência em conjunto ou 2º consumidor); união do modo do stub em 3 pontos (gatilho: 4º ponto ou 5º modo → extrair CardCutoutStubMode); detecção de rosto pequeno/distante (gatilho já em Riscos: medir falso negativo/positivo com fotos reais na UAT).
Explicitamente fora (não reabrir): e2e do ramo com rosto não baixa o PNG — o download do caminho proporcional é exercido pelo teste S15 slow, que agora roda com o rosto sintético do stub e asserta filename + assinatura PNG. Nenhum débito virou Issue nesta sessão (scores 2–3, sem expensive_lock).
Aceite de engenharia
- Aceite de produto da intenção ainda coberto: cabeça do visitante na ordem de grandeza dos candidatos (±20%) quando medível; automático, sem controle novo; rosto nunca cortado pela proporcionalidade; cobertura da janela prevalece; fallback silencioso ao enquadramento S15 sem erro novo; 100% no aparelho; 3 modelos/galeria/copy/privacidade intocados.
- Invariantes AGENTS/engineering-standards: math pura e client-safe em
src/lib(sem DOM); detecção no adaptersrc/components/cards; sem migration/collection/Consent/access; semas never; knip/cycles verdes; arte-mestre intocada;pnpm gate:fast+ e2e da superfície +pnpm push. - Testes de domínio previstos: unit de
frameCardPhotoOnFace(proporção, piso, teto, fallback/delegação) e pin deTEAM_CARD_FACE_REFERENCE_SIZEobrigatórios; e2e no specfrontendcom stub (ok/noface);E2E_AFFECTED_MANIFESTsem entrada nova; int não se aplica — 100% client-side, sem Payload/DB/access nem escrita multi-collection. - Limites registrados: (a) o piso do time (zoom ≥ 0.2) mantém a face alcançada em no máximo +15% da referência, então o aceite de ±20% fica garantido por construção; o limite real é o teto de 4 (rosto minúsculo/distante) e a foto do visitante pode ficar menor que a janela, com o ajuste fino como escape; (b) rosto maior que a janela → o teto de rosto respeita a janela; (c) detecção indisponível ou abaixo de 0.5 → enquadramento S15 (sem aviso); (d) falso positivo só age se for o maior rosto.
Self-score decision-quality: 5/5
- Decisões caras com rejeitadas: detector (A–D), onde detectar, math/API, constante, integração/prefetch e seam de e2e — todas com Opções/Recomendação/Rejeitadas; o barato (nomes, literais do rosto sintético) fica como fill-in.
- Cabe no appetite: 3 fases ≤1,5 dia, sem migration/infra; a math pura vem primeiro (tracer) e o detector depois, com fallback garantido.
- Rabbit holes nomeados: re-detecção em pan/zoom, zoom < 1, FaceLandmarker/detector próprio, medir arte em runtime, segundo seam, engine real no CI.
- Depth check: reusa
frameCardPhotoOnBbox/clampCardPhotoTransform, o singleton/prefetch/stub do S15,CardCutoutResult/hook e o padrão de licença — nada de abstração nova além da função pura pedida. - Intenção preservada: aceite de produto intacto (outcome, ±20%, cobertura, rosto não cortado, fallback, privacidade); a engenharia só resolveu as aberturas que a intenção deixou (detector, referência, cobertura vs proporção).