@klikeai/cut-preview 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# @klikeai/cut-preview
+
+Composição Remotion (`SmartStudioComposition`) + `calculateSmartStudioMetadata`
+empacotadas para o **preview ao vivo** do Klike Cut rodar no `@remotion/player`
+(browser/Lovable). O backend serve os `inputProps` em
+`GET /klike-cut/sessions/{id}/preview/player`; o front renderiza a composição ao
+vivo com estes símbolos.
+
+> Troque o escopo `@klikeai` pelo namespace npm da sua organização antes de publicar.
+
+## Build
+
+```bash
+cd remotion/preview-package
+npm install
+npm run build      # gera dist/index.js (ESM) + dist/index.d.ts (tsup)
+```
+
+## Publicar (passo a passo)
+
+1. **Escolha o nome/namespace** em `package.json` (`name`). Escopado
+   (`@suaorg/cut-preview`) é o recomendado — registre o escopo cedo p/ evitar
+   squatting.
+2. `npm login` com a conta que tem acesso ao escopo.
+3. Publique (escopado público exige `--access public`):
+   ```bash
+   npm publish --access public
+   ```
+4. **Versionamento é o contrato:** a `version` do pacote DEVE bater com
+   `COMPOSITION_VERSION` em
+   `app/services/klike_cut/preview_player.py`. A cada mudança da composição
+   (qualquer TSX em `../src`): `build` → bump da `version` E do
+   `COMPOSITION_VERSION` → `npm publish` → redeploy do backend. O front compara
+   as versões e cai no preview MP4 quando o pacote instalado está defasado.
+5. (Opcional) Automatize com CI publicando em tag `v*`.
+
+## Consumo no frontend (Lovable)
+
+Instale na MESMA versão de `remotion` (4.0.399) e adicione o Player:
+
+```bash
+npm install @remotion/player remotion@4.0.399 \
+  @remotion/captions@4.0.399 @remotion/transitions@4.0.399 \
+  @remotion/google-fonts@4.0.399 @remotion/layout-utils@4.0.399 \
+  @klikeai/cut-preview
+```
+
+```tsx
+import {Player} from '@remotion/player';
+import {SmartStudioComposition, calculateSmartStudioMetadata}
+  from '@klikeai/cut-preview';
+
+const {durationInFrames, fps, width, height} =
+  calculateSmartStudioMetadata({props: inputProps});
+
+<Player
+  component={SmartStudioComposition}
+  inputProps={inputProps}
+  durationInFrames={durationInFrames}
+  fps={fps}
+  compositionWidth={width}
+  compositionHeight={height}
+  controls
+  style={{width: '100%'}}
+/>
+```
+
+## Riscos / cuidados
+
+- **Exposição pública:** o código da composição (lógica de renderização visual)
+  fica público no npm. Não há segredo/credencial — é só apresentação —, mas é IP
+  visual. Se incomodar: pacote **privado** (npm pago / GitHub Packages) ou copiar
+  o `../src` direto no projeto do front.
+- **Drift de versão:** front com pacote < `COMPOSITION_VERSION` do backend →
+  `inputProps` podem não casar. Mitigado pela checagem de versão + fallback ao
+  MP4 (o backend responde `composition_version` no payload).
+- **peerDeps:** o front precisa de `remotion`/`@remotion/*` na MESMA versão
+  (4.0.399) + React 18/19. Versões divergentes = erro em runtime do Remotion.
+- **Manutenção:** toda mudança da composição = rebuild + republish + bump +
+  redeploy. Por isso o preview MP4 continua como rede de segurança.
+- **Assets `http(s)`:** `source.videoPath`, `endcard.logoUrl` e
+  `imageOverlays[].src` DEVEM ser URLs (o backend já entrega presignado). No
+  browser não existe o servidor de asset local do render SSR.

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import React from 'react';
+
+/**
+ * Contrato de inputProps Smart Studio ↔ Remotion.
+ *
+ * Espelha o JSON que o RemotionRenderer (Python) escreve em props.json.
+ * REGRA: todo tempo vem em MILISSEGUNDOS; a conversão ms→frame acontece num
+ * único ponto (utilitário msToFrames), usando o fps da composição. Cores em
+ * hex CSS (#RRGGBB), não no formato ASS.
+ *
+ * Fase A cobre só as camadas gráficas: captions, overlays e endcard. Os campos
+ * de cuts/zoom/reframe/transitions existem no contrato para as Fases B/C, mas
+ * na Fase A chegam desabilitados (esses passes rodam no FFmpeg antes).
+ */
+type Position = 'top' | 'center' | 'bottom';
+type CaptionDisplayMode = 'highlight' | 'plain' | 'word_by_word' | 'karaoke';
+interface SourceProps {
+    /** Path local do vídeo de entrada (o tempfile já baixado do S3 pelo Python). */
+    videoPath: string;
+    width: number;
+    height: number;
+    durationInSeconds: number;
+    fps: number;
+}
+interface OutputProps {
+    width: number;
+    height: number;
+    fps: number;
+}
+interface CaptionToken {
+    text: string;
+    startMs: number;
+    endMs: number;
+    confidence?: number;
+}
+/**
+ * Template visual da legenda (ortogonal ao displayMode):
+ * - classic: contorno duro (text-shadow 8 direções)
+ * - pill: bloco da página sobre fundo arredondado translúcido
+ * - box: token ATIVO ganha caixa sólida colorida (estilo CapCut)
+ * - glow: brilho suave na cor de destaque (sem contorno duro)
+ */
+type CaptionTemplate = 'classic' | 'pill' | 'box' | 'glow';
+/**
+ * Estilo das legendas. TODOS os campos são opcionais: o que vier daqui é
+ * OVERRIDE explícito do request — defaults e tema (stylePreset) são
+ * resolvidos no React (themes.ts), a fonte da verdade visual.
+ */
+interface CaptionStyle {
+    fontFamily?: string;
+    fontSize?: number;
+    primaryColor?: string;
+    highlightColor?: string;
+    outlineColor?: string;
+    bold?: boolean;
+    uppercase?: boolean;
+    italic?: boolean;
+    outlineWidth?: number;
+    activeScale?: number;
+    animateIn?: boolean;
+    template?: CaptionTemplate;
+    /** Âncora vertical do bloco (sempre dentro das safe zones). */
+    position?: 'bottom' | 'center' | 'top';
+}
+interface CaptionsProps {
+    enabled: boolean;
+    /** Override explícito; ausente = tema/default (themes.ts). */
+    displayMode?: CaptionDisplayMode;
+    /** Janela (ms) para agrupar tokens em "páginas" estilo TikTok. */
+    combineTokensWithinMs?: number;
+    tokens: CaptionToken[];
+    style: CaptionStyle;
+}
+type OverlayEnterAnimation = 'fade' | 'slide-up' | 'slide-down' | 'zoom' | 'spring-pop';
+interface OverlayItem {
+    text: string;
+    startMs: number;
+    endMs: number;
+    position: Position;
+    fontSize?: number;
+    color?: string;
+    /** ms de fade in/out (default suave se omitido). */
+    fadeMs?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    outlineColor?: string;
+    outlineWidth?: number;
+    /** Tipo de entrada; default "spring-pop". */
+    enterAnimation?: OverlayEnterAnimation;
+    /** ms do fade de saída (default = fadeMs). */
+    fadeOutMs?: number;
+}
+interface EndcardGradient {
+    from: string;
+    to: string;
+    /** Ângulo do linear-gradient em graus (default 160). */
+    angleDeg?: number;
+}
+interface EndcardProps {
+    enabled: boolean;
+    text: string;
+    durationMs: number;
+    /** Estilo = override explícito; defaults/tema resolvidos em themes.ts. */
+    background?: string;
+    color?: string;
+    fontSize?: number;
+    /** Gradiente de fundo; quando presente, tem precedência sobre background. */
+    gradient?: EndcardGradient;
+    /** URL http(s) do logo (o render.mjs converte path local em URL servida). */
+    logoUrl?: string;
+    logoHeightPx?: number;
+    fontFamily?: string;
+    /** Entrada animada (spring) do logo/texto (default true). */
+    animateIn?: boolean;
+}
+/** Barra de progresso do vídeo (acessório de tema; borda superior). */
+interface ProgressBarProps {
+    enabled: boolean;
+    color: string;
+    heightPx: number;
+}
+/**
+ * Safe zone do feed vertical — SEMPRE aplicada aos textos (legendas e
+ * overlays), independente de flag: a UI das plataformas ocupa o topo e
+ * principalmente o rodapé. Percentuais RELATIVOS À ALTURA (top/bottom) e à
+ * LARGURA (side) — os layers convertem para px via useVideoConfig (padding em
+ * % no CSS é relativo à largura, o que quebraria as margens verticais).
+ */
+interface SafeZonesProps {
+    enabled: boolean;
+    marginTopPercent: number;
+    marginBottomPercent: number;
+    marginSidePercent: number;
+}
+/** Reservados p/ Fases B/C — na Fase A chegam {enabled:false}. */
+interface ReframeProps {
+    enabled: boolean;
+    mode: 'blur_fill';
+}
+interface ZoomMoment {
+    startMs: number;
+    endMs: number;
+    factor: number;
+}
+interface ZoomProps {
+    enabled: boolean;
+    startMs: number;
+    endMs: number;
+    factor: number;
+    animated: boolean;
+    /** Multi-instância: janelas de zoom (sem sobreposição). Quando presente,
+     * tem precedência sobre startMs/endMs/factor (que ficam como legado). */
+    moments?: ZoomMoment[];
+}
+type CutTransitionType = 'none' | 'fade' | 'wipe' | 'slide';
+interface CutsProps {
+    enabled: boolean;
+    /** Segmentos a MANTER (ms na timeline do vídeo FONTE), ordenados. */
+    segmentsKeepMs: [number, number][];
+    /** Duração da transição entre segmentos (0/ausente = corte seco). */
+    transitionMs?: number;
+    /** Tipo explícito; ausente = tema decide (themes.ts). */
+    transitionType?: CutTransitionType;
+}
+type ColorGradePreset = 'warm' | 'cold' | 'vintage' | 'bw' | 'high_contrast' | 'vivid';
+/** Filtro de cor aplicado ao VÍDEO (não afeta textos nem endcard). */
+interface ColorGradeProps {
+    preset: ColorGradePreset;
+    /** 0-1 — interpola os filtros CSS do preset. */
+    intensity: number;
+}
+type ImageCorner = 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' | 'center';
+/** Imagem/logo sobreposta (add_image_overlay). */
+interface ImageOverlayItem {
+    /** URL http(s) — o render.mjs serve paths locais por HTTP. */
+    src: string;
+    startMs: number;
+    endMs: number;
+    corner: ImageCorner;
+    /** Altura como fração da ALTURA do canvas (0.05–0.3). */
+    heightPct: number;
+    opacity: number;
+}
+interface SmartStudioInputProps {
+    source: SourceProps;
+    output: OutputProps;
+    /** Nome do preset de tema (themes.ts). Ausente/desconhecido = defaults. */
+    stylePreset?: string;
+    captions: CaptionsProps;
+    overlays: OverlayItem[];
+    endcard: EndcardProps;
+    safeZones: SafeZonesProps;
+    /** Override explícito da progress bar; tema pode ligar por padrão. */
+    progressBar?: Partial<ProgressBarProps>;
+    reframe: ReframeProps;
+    zoom: ZoomProps;
+    cuts: CutsProps;
+    /** Filtro de cor sobre o vídeo (color_grade). */
+    colorGrade?: ColorGradeProps;
+    /** Imagens/logos sobrepostos (add_image_overlay). */
+    imageOverlays?: ImageOverlayItem[];
+    [key: string]: unknown;
+}
+/** Default usado pelo Studio e como base de merge. Vídeo precisa existir. */
+declare const DEFAULT_INPUT_PROPS: SmartStudioInputProps;
+
+/**
+ * Composição raiz do Smart Studio.
+ *
+ * Resolve o TEMA (props.stylePreset via themes.ts — a fonte da verdade visual)
+ * e mescla: defaults → tema → overrides explícitos do request. As layers
+ * recebem valores JÁ RESOLVIDOS.
+ *
+ * Empilha as camadas (z-order = ordem no JSX, de baixo p/ cima):
+ *   1. ReframeContainer/ZoomLayer/VideoBase — o vídeo de origem (já cortado
+ *      pelo FFmpeg), com reframe 9:16 (blur fill) e punch-in zoom opcionais
+ *   2. CaptionsLayer — legendas word-level do Whisper
+ *   3. OverlayLayer  — lettering/hook/CTA
+ *   4. ProgressBarLayer — barra de progresso (acessório de tema)
+ *   5. EndcardSequence — cartão final de CTA (sequência extra ao fim)
+ *
+ * Reframe/Zoom chegam desabilitados quando o FFmpeg já os aplicou (fallback)
+ * ou quando o plano não os pede.
+ */
+
+declare const SmartStudioComposition: React.FC<SmartStudioInputProps>;
+
+/**
+ * calculateMetadata da composição Smart Studio — extraído de Root.tsx para
+ * ser exportado pelo pacote de preview (klike-cut-preview).
+ *
+ * REGRA-CHAVE do contrato: o frontend (Remotion Player) calcula duração/fps/
+ * dimensões com ESTA MESMA função que o selectComposition roda no render
+ * server-side — elimina a classe de bug "arredondamento de frames divergiu
+ * entre preview e render".
+ */
+
+declare const FALLBACK_DURATION_IN_FRAMES = 300;
+interface SmartStudioMetadata {
+    durationInFrames: number;
+    fps: number;
+    width: number;
+    height: number;
+}
+declare const calculateSmartStudioMetadata: ({ props, }: {
+    props: SmartStudioInputProps;
+}) => SmartStudioMetadata;
+
+/**
+ * Temas (StylePreset) do Smart Studio — FONTE DA VERDADE visual.
+ *
+ * Um tema resolve, num único lugar, a identidade visual coerente do vídeo:
+ * fonte + paleta + template de legenda + animação de overlay + endcard +
+ * acessórios (progress bar). O Python NÃO conhece os valores dos temas — só
+ * passa o nome do preset em props.stylePreset (escolhido pelo Planner ou
+ * sobrescrito no request).
+ *
+ * Ordem de resolução (menor → maior precedência):
+ *   DEFAULTS (deste arquivo) → THEMES[stylePreset] → overrides explícitos do
+ *   request (props.captions.style / props.overlays[i] / props.endcard).
+ * Ou seja: o usuário sempre pode sobrescrever qualquer valor do tema.
+ */
+
+declare const STYLE_PRESETS: readonly ["bold_impact", "clean_saas", "ugc_casual", "premium_dark"];
+type StylePresetName = (typeof STYLE_PRESETS)[number];
+
+export { type CaptionDisplayMode, type CaptionStyle, type CaptionTemplate, type CaptionToken, type CaptionsProps, type ColorGradePreset, type ColorGradeProps, type CutTransitionType, type CutsProps, DEFAULT_INPUT_PROPS, type EndcardGradient, type EndcardProps, FALLBACK_DURATION_IN_FRAMES, type ImageCorner, type ImageOverlayItem, type OutputProps, type OverlayEnterAnimation, type OverlayItem, type Position, type ProgressBarProps, type ReframeProps, STYLE_PRESETS, type SafeZonesProps, SmartStudioComposition, type SmartStudioInputProps, type SmartStudioMetadata, type SourceProps, type StylePresetName, type ZoomMoment, type ZoomProps, calculateSmartStudioMetadata };