sass-imobiliaria/specs/032-performance-homepage/plan.md

Plan — 032: Performance Homepage

Visão Técnica

A estratégia central é inverter o fluxo de dados: em vez de cada componente buscar seus próprios dados (model-per-component), o HomePage orquestra todos os fetches em paralelo e distribui via props. Isso elimina o waterfall e permite paralelizar corretamente.

ANTES (serial):
  HomePage mount → fetch config → render HomeScrollScene → fetch properties
                                                         → fetch agents (AgentsCarousel)

DEPOIS (paralelo):
  HomePage mount → Promise.all([config, properties, agents]) → render com dados prontos

---

Arquitetura das Mudanças

1. HomePage.tsx — Orchestrator

• Gerencia 3 estados: config, featuredProperties, agents
• Promise.all no único useEffect
• Injeta <link rel="preload"> via efeito secundário quando backgroundImage resolve
• Cache de config em sessionStorage com TTL 5 min
• Passa properties, loadingProperties, agents, loadingAgents como props para baixo

2. HomeScrollScene.tsx — Apresentação

• Remove useEffect de getFeaturedProperties e estado interno de properties
• Recebe properties: Property[] e loadingProperties: boolean via props
• Mantém isLight (necessário para estilos internos)
• Remove <style> inline com @keyframes (migra para index.css)
• Adiciona fetchPriority="high" na hero <img>
• RiseCard passa a usar hook useInView

3. AgentsCarousel.tsx — Apresentação

• Remove useEffect de getAgents e estado interno de agents/loading
• Recebe agents: Agent[] e loading: boolean via props
• Adiciona will-change: transform no track CSS

4. PropertyRowCard.tsx — Folha

• SlideImage: adiciona loading="lazy" e decoding="async"

5. hooks/useInView.ts — Utilitário

• Encapsula IntersectionObserver com disconnect no isIntersecting
• Aceita options?: IntersectionObserverInit
• Retorna { ref, inView }

6. index.css

• Adiciona bloco @keyframes fadeDown que estava inline em HomeScrollScene

---

Interface das Props Alteradas

// HomeScrollScene — novas props
interface HomeScrollSceneProps {
    headline: string
    subheadline: string | null
    ctaLabel: string
    ctaUrl: string
    backgroundImage?: string | null
    isLoading?: boolean
    properties: Property[]          // NOVO — antes buscado internamente
    loadingProperties: boolean      // NOVO
}

// AgentsCarousel — novas props
interface AgentsCarouselProps {
    agents: Agent[]                 // NOVO — antes buscado internamente
    loading: boolean                // NOVO
}

---

Estratégia de Cache — sessionStorage

const CACHE_KEY = 'homepage_config'
const CACHE_TTL = 5 * 60 * 1000 // 5 min

function getCachedConfig(): HomepageConfig | null {
    try {
        const raw = sessionStorage.getItem(CACHE_KEY)
        if (!raw) return null
        const { data, ts } = JSON.parse(raw)
        if (Date.now() - ts > CACHE_TTL) return null
        return data
    } catch { return null }
}

function setCachedConfig(data: HomepageConfig) {
    try {
        sessionStorage.setItem(CACHE_KEY, JSON.stringify({ data, ts: Date.now() }))
    } catch {}
}

---

Tratamento de CLS na Hero

O HomeScrollScene receberá isLoading do pai. Enquanto isLoading=true, o container sticky terá min-height: 100svh preservado via className, garantindo que o browser reserve o espaço mesmo antes da imagem carregar.

O skeleton inline já existente está correto — o problema atual é que o backgroundImage resolve mais tarde que o skeleton desaparece, causando re-layout. Com o preload dinâmico, a imagem chega antes.

---

Decisões de Design

Decisão	Alternativa rejeitada	Motivo
sessionStorage para cache	localStorage	sessionStorage expira ao fechar a aba — adequado para conteúdo editorial
Preload via document.createElement	react-helmet	Evita dependência extra para um caso simples
Props drilling em vez de Context	Context global de dados da home	Overkill para componentes de folha; props é suficiente e mais rastreável
useInView hook simples	Biblioteca externa (react-intersection-observer)	Sem dependência extra, controle total

---

Sequência de Implementação

1. hooks/useInView.ts                  (sem dependências)
2. index.css (keyframes)               (sem dependências)
3. PropertyRowCard.tsx (loading=lazy)  (sem dependências)
4. AgentsCarousel.tsx (props)          (depende de tipos Agent)
5. HomeScrollScene.tsx (props + refat) (depende de useInView)
6. HomePage.tsx (orchestrator)         (depende de todos acima)